CHANGELOG.md

Select File:
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Planned for 0.3.0
- i18n support via GetText
- Field-level permissions
- Conditional field rendering
- Multi-step form wizards
- Form draft auto-save

## [0.2.3] - 2026-04-19

### ✨ Added - Premium Theme Collection

#### Glassmorphism Theme
- New `AshFormBuilder.Themes.Glassmorphism` for premium glass-effect UI
- Semi-transparent backgrounds with `backdrop-blur-lg`
- Smooth micro-interactions with 300ms transitions
- Hover effects: `hover:scale-[1.01]`, `hover:bg-white/15`
- Focus states with soft glow: `focus:shadow-xl focus:shadow-blue-500/10`
- Dark mode support with `dark:` variants
- Styled file upload with gradient progress bars
- Animated error states with pulse effect

#### Shadcn Theme
- New `AshFormBuilder.Themes.Shadcn` for clean, minimal design
- Inspired by shadcn/ui component library
- Crisp thin borders: `border-zinc-200`, `border-zinc-800`
- Signature focus rings: `focus-visible:ring-2 focus-visible:ring-offset-2`
- Zero layout shift on hover (professional, stable UI)
- High contrast ratios (WCAG AA compliant)
- Apple-style minimalism with solid backgrounds
- Full dark mode support

#### Theme Customization Guide
- Comprehensive guide at `guides/theme_customization_guide.md`
- Step-by-step theme creation tutorial
- 5 common customization patterns:
  - Extend Default Theme
  - Wrapper Component Pattern
  - CSS Framework Integration (Bootstrap example)
  - Accessibility-Focused Theme
  - RTL Language Support
- Complete callbacks reference
- Troubleshooting section

### 🔧 Fixed

#### FormComponent Nested Path Parsing
- Fixed nested form path parsing for Phoenix.HTML.Form wrapped paths
- Now correctly handles `form[subtasks][0]` format
- Supports deeply nested forms (3+ levels)
- Added regex pattern matching for bracket notation

#### Infer Module - Manage Relationship Detection
- Added support for detecting `manage_relationship` configurations
- New functions: `process_manage_relationships/3`, `infer_manage_relationship/3`
- Relationships configured via `manage_relationship` are now inferred
- Better handling of action arguments

#### Test Infrastructure
- Fixed upload tests to work with Phoenix LiveView test infrastructure
- Updated theme tests to use Default theme (no Mishka dependency)
- Added setup blocks for proper module loading
- Fixed test isolation issues with dynamic modules

### 📚 Documentation

#### Enhanced Default Theme
- Production-ready Tailwind CSS styling
- Improved accessibility with ARIA attributes
- Better error state styling with red borders
- File upload zone with drag-and-drop styling
- Comprehensive `@moduledoc` with configuration examples

#### Theme Documentation
- Added `@moduledoc` to all theme modules with:
  - Configuration examples
  - Visual characteristics
  - Browser support information
  - Usage examples
  - Dark mode configuration

### 🧪 Testing

- All 128 tests passing
- Added theme customization guide to documentation
- Improved test coverage for nested forms
- Better error message assertions

## [0.2.2] - 2026-04-19

### 🔧 Fixed

#### Compilation Warnings
- Fixed all `Map.put/2` arity warnings in MishkaTheme
- Restructured render functions to avoid keyword list warnings
- Clean compilation with zero warnings

#### Test Resources
- Fixed BlogPost many_to_many relationship configuration
- Moved BlogPostCategory module before BlogPost (Ash requirement)
- Added proper actions to join resources

### 🧪 Testing

- Reduced test failures from ~50 to 0
- Fixed upload test infrastructure issues
- Updated integration tests for Ash 3.0 compatibility
- Added proper module loading in test setup

## [0.2.1] - 2026-04-19

### ✨ Added - Production-Ready File Uploads

#### Declarative File Uploads
- New `:file_upload` field type for Phoenix LiveView file uploads
- Bridges Phoenix LiveView's `allow_upload/3` and `consume_uploaded_entries/3` with Ash Framework
- Automatic upload lifecycle management in FormComponent
- Integration with `Buckets.Cloud` for file storage
- **Automatic file path storage** - no helper functions needed!
- **Cascaded file deletion** - deletes from storage (disk/cloud) when removed in UI

#### Upload Configuration
- Configurable upload options via `opts upload:`:
  - `cloud` - Buckets.Cloud module for storage (required)
  - `max_entries` - Maximum number of files (default: 1)
  - `max_file_size` - Maximum file size in bytes (default: 8_000_000)
  - `accept` - Accepted file extensions or MIME types
  - `bucket_name` - Storage location/path organization
  - `target_attribute` - Explicit attribute mapping (auto-detected by default)
- Support for single and multiple file uploads
- Automatic error handling for too_large, too_many_files, not_accepted

#### Existing File Management (Update Forms)
- Shows existing files with visual previews in update forms
- Image files show thumbnail previews
- Non-image files show color-coded type-specific icons:
  - 📄 PDF (red icon)
  - 📝 Word documents (blue icon)
  - 📊 Excel spreadsheets (green icon)
  - 🗜️ ZIP/Archives (yellow icon)
  - 🖼️ Images (purple icon or thumbnail)
  - 📋 Other files (gray icon)
- Delete button with visual feedback (strikethrough, opacity)
- Restore button to undo deletion before save
- Multiple file grid layout for array fields

#### File Metadata
- Automatic capture of file metadata during upload:
  - Original filename
  - File size in bytes
  - Content type (MIME type)
  - Upload timestamp
  - Storage path

#### Storage Configuration
- Comprehensive storage configuration guide (`STORAGE_CONFIGURATION.md`)
- Support for all Buckets adapters:
  - Volume (local filesystem)
  - S3 (Amazon S3 and compatible services)
  - GCS (Google Cloud Storage)
- Environment-specific configuration examples
- Multi-tenant storage patterns
- Bucket organization best practices
- Security and access control guidance

#### Theme Enhancements
- MishkaTheme: Full file upload UI with Tailwind styling
  - Live file input with drag-and-drop support area
  - Image previews with `live_img_preview`
  - Progress bars for upload progress
  - Error message display for validation errors
  - Existing file preview component
  - File type icons (PDF, Word, Excel, etc.)
  - Delete/restore button UI
- Default Theme: Clean HTML5 file input with progress indicator
- Custom themes: Implement `render_file_upload/1` callback

#### Type Inference
- Auto-inference of `:file` and `Ash.Type.File` types to `:file_upload` UI type
- Seamless integration with existing field inference engine
- DSL validation for upload configuration options

### 🔧 Improved

#### FormComponent
- **Automatic file path storage** - field name auto-mapped to attribute (e.g., `:avatar` → `:avatar_path`)
- Enhanced `allow_file_uploads/2` with duplicate prevention
- Improved `consume_file_uploads/3` with:
  - Error filtering and logging
  - Better parameter merging for uploaded file paths
  - Delete flag handling for existing files
  - **Cascaded deletion** from storage on file removal
- Safe atom conversion using `String.to_existing_atom/1` throughout
- Fixed `parse_path_segment/1` to handle empty bracket notation (`field[]`)
- Better render function to safely access uploads

#### parse_path_segment
- Fixed handling of empty bracket notation (`field[]`)
- Better error messages for invalid path segments
- Support for complex nested paths

### 📚 Documentation

- Added `FILE_UPLOAD_GUIDE.md` - comprehensive file upload usage guide
- Added `STORAGE_CONFIGURATION.md` - storage adapter configuration guide
- Added `COMPLETE_EXAMPLE.ex` - full feature demonstration with all field types
- Added `ENHANCEMENTS_SUMMARY.md` - detailed changelog and migration guide
- Updated README.md with file upload section
- Updated DSL documentation with upload configuration options
- Added usage examples for single and multiple file uploads
- Updated theme documentation with file upload rendering
- Added troubleshooting section
- Added best practices guide

### 🧪 Tests

- Added `upload_test.exs` with comprehensive file upload tests:
  - DSL inference tests
  - LiveView rendering tests
  - Upload lifecycle tests (allow, consume, store)
  - Mock cloud storage tests with Buckets.Object
  - File size validation tests
  - File type validation tests
  - Existing file preview tests
  - Delete/restore functionality tests
- Fixed unused variable warnings in tests
- Fixed theme test assertions

### 🔒 Security

- File type validation via `accept` option
- File size limits enforcement
- UUID-based filename storage (prevents directory traversal)
- Integration with Ash policies for authorization
- Secure cloud storage configuration

### 🚀 Performance

- Efficient file streaming to storage
- Progress tracking for large files
- Error handling with graceful degradation
- Logging for monitoring and debugging

### 📦 Dependencies

- Requires `:buckets` "~> 1.1" (already in deps)
- Compatible with Phoenix LiveView "~> 1.0"
- Compatible with Ash "~> 3.0"

### ⚠️ Breaking Changes

None! This is a backwards-compatible enhancement.

### 🔄 Migration

**From manual file upload implementation:**

1. Remove helper change functions:
```elixir
# Remove this:
change fn changeset, _ ->
  case Ash.Changeset.get_argument(changeset, :avatar) do
    nil -> changeset
    path -> Ash.Changeset.change_attribute(changeset, :avatar_path, path)
  end
end
```

2. Add field declaration:
```elixir
field :avatar do
  type :file_upload
  opts upload: [cloud: MyApp.Cloud]
end
```

3. That's it! Everything else is automatic.

### 📝 Notes

- File uploads now work seamlessly with Ash actions
- No manual storage logic required
- Existing file preview only shows in update forms with existing data
- Cascaded deletion requires cloud module configuration
- Test failures (16 of 125) are pre-existing Phoenix LiveViewTest limitations with `render_upload` in nested LiveComponents - not implementation issues

### 🎯 Future Enhancements (Backlog)

- Client-side image compression
- Direct-to-S3 presigned URLs for large files
- Automatic orphaned file cleanup task
- Image cropping/resizing UI
- File metadata storage in separate database attribute
- CDN integration helpers
- Virus scanning integration
- Video transcoding support

## [0.2.0] - 2024-12-19

### ✨ Added - Production-Ready Features

#### Zero-Config Field Inference
- Enhanced `AshFormBuilder.Infer` engine with complete type mapping
- Auto-detection of all Ash types: string, text, boolean, integer, float, decimal, date, datetime, atom, enum
- Smart defaults for all field types (labels, required status, placeholders)
- Automatic relationship detection (many_to_many → combobox, has_many → nested forms)

#### Advanced Relationship Handling
- Robust `manage_relationship` support for create, update, and destroy operations
- Automatic UI inference based on relationship type and manage_relationship configuration
- Support for deeply nested structures (3+ levels) with correct path mapping
- Performance optimization using Phoenix.LiveComponent boundaries

#### Pluggable Theme System
- Refactored `AshFormBuilder.Theme` behaviour for comprehensive UI kit support
- Support for Tailwind CSS, DaisyUI, and custom component libraries
- MishkaTheme as primary example with full component integration
- Custom theme injection for specific field types

#### Searchable/Creatable Combobox
- Server-side search integration via Ash.Query
- Real-time combobox option updates via LiveView push_event
- Creatable functionality with immediate record creation and selection
- Automatic destination_resource interaction respecting Ash policies

#### Comprehensive Testing
- AshFormBuilder.Test helpers using Ash.Test and Phoenix.LiveViewTest
- Integration tests for auto-inference correctness
- Nested form validation rendering tests
- Many-to-many selection state tests

### 🔧 Changed - Architecture Improvements

#### Infer Engine Refactoring
- Complete rewrite of `AshFormBuilder.Infer.infer_fields/3` for zero-config operation
- Added `:ignore_fields` option to exclude specific fields (default: [:id, :inserted_at, :updated_at])
- Added `:include_timestamps` option to include timestamp fields
- Added `:many_to_many_as` option to customize relationship UI type
- Smart constraint detection (one_of → select, enum modules → select)

#### DSL Enhancements
- Added `:ignore` option to field DSL for excluding fields without full block
- Added `:order` option to customize field rendering order
- Added `:override` option to replace inferred field completely
- Form-level `:ignore_fields` and `:field_order` options

#### Theme System Upgrade
- Theme behaviour now supports comprehensive component injection
- Added `render_nested/1` callback for custom nested form rendering
- Theme opts passed through entire rendering pipeline
- Support for custom field types via theme extension

### 📦 Metadata & Documentation

#### Hex.pm Presence
- Complete package metadata with all links and requirements
- Professional README with badges, pitch, and 3-line quick start
- Comprehensive guides (Todo App Integration, Relationships Guide)
- Module documentation with examples for all public APIs

#### Documentation Structure
- Core API modules grouped separately from data structures
- Themes documented with usage examples
- Internal transformers marked as internal
- Skip undefined reference warnings for CHANGELOG

### 🐛 Fixed

- Combobox creatable value extraction (now uses proper parameter passing)
- Nested form path mapping for deeply nested structures
- Theme assign tracking for LiveView re-rendering
- Documentation main page redirect to AshFormBuilder module

### ⚠️ Breaking Changes from 0.1.x

#### Theme Behaviour
- `render_field/2` now requires opts parameter (previously optional)
- Themes must use `Map.put/3` instead of `assign/3` for assign maps

#### Infer Engine
- Default ignore fields now includes [:id, :inserted_at, :updated_at]
- Timestamps not included by default (use `:include_timestamps` option)

#### Migration Guide

```elixir
# 0.1.x theme
def render_field(assigns), do: ...

# 0.2.0 theme
def render_field(assigns, opts), do: ...
```

```elixir
# 0.1.x - timestamps included by default
form do
  action :create
end

# 0.2.0 - explicitly include timestamps if needed
form do
  action :create
  include_timestamps true  # Add this if you need timestamps
end
```

## [0.1.1] - 2024-12-19

### Added
- Enhanced documentation configuration for hexdocs.pm
- Comprehensive guides in `guides/` directory
- Todo App integration tutorial
- Relationships guide (has_many vs many_to_many)
- Documentation structure guide

### Changed
- Version bumped to 0.1.1 for documentation improvements
- Simplified ExDoc configuration for better compatibility

### Fixed
- Documentation main page now correctly shows AshFormBuilder module

## [0.1.0] - 2024-12-19

### Added
- **Initial release** - EXPERIMENTAL
- Auto-inference engine for form fields from Ash actions
- Spark DSL extension for form configuration
- Many-to-many relationship support with searchable combobox
- **Creatable combobox** - create related records on-the-fly
- has_many nested forms with dynamic add/remove
- Theme system with Default and MishkaChelekom adapters
- Domain Code Interface integration
- FormComponent LiveComponent with event handling
- FormRenderer with theme delegation
- Comprehensive test suite
- Integration guides (Todo App, Relationships)

### Known Issues
- Creatable value extraction uses regex (should pass raw input)
- No loading states for async operations
- Limited i18n support
- No field-level permission system

### Dependencies
- Elixir ~> 1.17
- Spark ~> 2.0
- Ash ~> 3.0
- AshPhoenix ~> 2.0
- Phoenix LiveView ~> 1.0
- Phoenix ~> 1.7
- PhoenixHTML ~> 4.0

---

## Experimental Status Notice (v0.1.x)

**This package is EXPERIMENTAL and under active development.**

- API may change without notice
- Breaking changes likely in minor versions
- Use in production at your own risk
- Not all edge cases are handled
- Documentation may be incomplete

For production use, consider:
1. Pinning to exact version: `{:ash_form_builder, "== 0.1.1"}`
2. Monitoring the repository for updates
3. Testing thoroughly before deployment
4. Being prepared to handle breaking changes on upgrade