Feature release pre-v1.4.0

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [maclong9]

.github/ISSUE_TEMPLATE/02_FEATURE_REQUEST.md

@@ -31,6 +31,7 @@ assignees: ''
 - [ ] Extension to Existing Element
 - [ ] Performance Improvement
 - [ ] Documentation Enhancement
+- [ ] Developer Experience Enhancement
 - [ ] Other (please specify)
 
 ## Example Code

CONTRIBUTING.md

@@ -215,9 +215,10 @@ WebUI follows a compositional pattern for creating HTML elements. When adding a
 
 ## Adding New Style Modifiers
 
-Style modifiers in WebUI follow an extension pattern on the `Element` class. Here's how to add a new style modifier:
+Style modifiers in WebUI follow the unified style system pattern. Here's how to add a new style modifier:
 
 1. **File Location**: Add the new style modifier to the appropriate file in `Sources/WebUI/Styles/`:
+   - Core style operations go in the `Core/` directory
    - Appearance-related modifiers go in the `Appearance/` directory
    - Layout-related modifiers go in the `Base/` or `Positioning/` directories
    - Create a new file if the modifier doesn't fit an existing category
@@ -238,7 +239,33 @@ Style modifiers in WebUI follow an extension pattern on the `Element` class. Her
    }
    ```
 
-   b. **Implement the Extension Method**:
+   b. **Implement the Style Operation**:
+   ```swift
+   /// Style operation for the custom style
+   public struct StyleModifierOperation: StyleOperation {
+       /// Parameters for this style operation
+       public struct Parameters {
+           public let option: StyleOption
+
+           public init(option: StyleOption) {
+               self.option = option
+           }
+       }
+
+       /// Applies the style operation and returns CSS classes
+       public func applyClasses(params: Parameters) -> [String] {
+           return ["style-\(params.option.rawValue)"]
+       }
+
+       /// Shared instance
+       public static let shared = StyleModifierOperation()
+
+       /// Private initializer
+       private init() {}
+   }
+   ```
+
+   c. **Implement the Element Extension Method**:
    ```swift
    extension Element {
        /// Applies a style modifier to the element.
@@ -260,43 +287,45 @@ Style modifiers in WebUI follow an extension pattern on the `Element` class. Her
            option: StyleOption,
            on modifiers: Modifier...
        ) -> Element {
-           let baseClass = "style-\(option.rawValue)"
-           let newClasses = combineClasses([baseClass], withModifiers: modifiers)
-
-           return Element(
-               tag: self.tag,
-               id: self.id,
-               classes: (self.classes ?? []) + newClasses,
-               role: self.role,
-               label: self.label,
-               data: self.data,
-               isSelfClosing: self.isSelfClosing,
-               customAttributes: self.customAttributes,
-               content: self.contentBuilder
+           let params = StyleModifierOperation.Parameters(option: option)
+
+           return StyleModifierOperation.shared.applyToElement(
+               self,
+               params: params,
+               modifiers: modifiers
            )
        }
    }
    ```
 
-   c. **Update Responsive Support** (if applicable):
+   d. **Implement the Global Function for Declarative DSL**:
    ```swift
-   extension Element {
-       /// Responsive version for use within the .responsive block
-       @discardableResult
-       public func styleModifier(option: StyleOption) -> Element {
-           return self.styleModifier(option: option, on: []).proxy()
-       }
+   /// Applies the style modifier in the responsive context with Declarative syntax.
+   ///
+   /// - Parameters:
+   ///   - option: The style option to apply.
+   /// - Returns: A responsive modification for the style.
+   public func styleModifier(option: StyleOption) -> ResponsiveModification {
+       let params = StyleModifierOperation.Parameters(option: option)
+
+       return StyleModifierOperation.shared.asModification(params: params)
    }
    ```
 
+   f. **Register in StyleRegistry** (optional but recommended):
+   ```swift
+   // In StyleRegistry.swift
+   public static let styleModifier = StyleModifierOperation.shared
+   ```
+
 3. **Testing**: Add unit tests for the new style modifier in the `Tests` directory.
 
 4. **Documentation**: Include comprehensive DocC documentation with:
    - Method-level documentation explaining the modifier's purpose
    - Parameter documentation for all method parameters
    - Usage examples showing common implementations
    - Visual examples if the style has a significant impact on appearance
-   - Examples of using the modifier within responsive blocks
+   - Examples of using the modifier with all three interfaces (direct, on, and Declarative)
 
 ### Adding Extensions to Existing Elements
 
@@ -332,30 +361,62 @@ You can extend existing elements with specialized methods to improve developer e
 
 3. **Documentation**: As with other additions, include comprehensive DocC documentation.
 
-### Using Responsive Styling
-
-WebUI provides a block-based responsive API for cleaner responsive designs.
-
-### Basic Usage
-
-The `.responsive` modifier allows applying multiple style changes across different breakpoints in a single block:
-
-```swift
-Text { "Responsive Content" }
-  .font(size: .sm)
-  .background(color: .neutral(._500))
-  .responsive {
-    $0.md {
-      $0.font(size: .lg)
-      $0.background(color: .neutral(._700))
-      $0.padding(of: 4)
-    }
-    $0.lg {
-      $0.font(size: .xl)
-      $0.background(color: .neutral(._900))
-    }
-  }
-```
+## Responsive Styling System
+
+WebUI provides a powerful responsive styling system with multiple syntaxes for flexibility and developer experience.
+
+### Responsive Styling Options
+
+WebUI supports two different ways to apply responsive styles:
+
+1. **Declarative Block Syntax** - Create responsive styles in a clean, concise way:
+1. **Declaritive** (using the result builder pattern):
+   ```swift
+   Text { "Responsive Content" }
+     .font(size: .sm)
+     .responsive {
+       md {
+         font(size: .lg)
+         background(color: .neutral(._700))
+       }
+       lg {
+         font(size: .xl)
+         padding(of: 6)
+       }
+     }
+   ```
+
+2. **Direct Breakpoint Modifiers** (for single property changes):
+   ```swift
+   Text { "Responsive Content" }
+     .font(size: .sm, on: .xs)
+     .font(size: .lg, on: .md)
+     .font(size: .xl, on: .lg)
+   ```
+
+### Implementing Responsive Support
+
+When adding new style modifiers, you must implement both interfaces to ensure full responsive support:
+
+1. **Element Extension** - For direct styling and breakpoint modifiers
+2. **Global Function** - For Declaritive syntax with result builders
+
+The unified style system makes this process simple by deriving both interfaces from a single style operation.
+
+### Unified Style System
+
+WebUI uses a unified style system that defines each style operation once and derives multiple interfaces from it:
+
+1. **Core Style Operations** - Define the core logic for generating CSS classes
+2. **Interface Adapters** - Adapt the core operations to different contexts (Element extensions and global functions)
+3. **StyleRegistry** - Provides centralized access to all style operations
+
+This approach provides several benefits:
+- Single point of definition for each style
+- Consistency across different interfaces
+- Reduced code duplication
+- Easier maintenance and extension
+- Clean, Declarative syntax for responsive styling
 
 ### File Organization Principles
 
@@ -367,18 +428,21 @@ When organizing code in the WebUI library, follow these principles:
 4. **Manageable Size**: Keep files under on the smaller side where possible
 5. **Clear Dependencies**: Make dependencies between components explicit and avoid circularity
 
-When refactoring or adding new code, consider if you should:
-- Add to an existing file (for small, closely related additions)
-- Create a new file in an existing directory (for new components in an established category)
-- Create a new directory (for entirely new subsystems or categories)
+When adding new style operations:
+- Create the style operation in `Styles/Core/`
+- Register it in `StyleRegistry`
+- Implement the three interface adapters (Element, ResponsiveBuilder, global function)
+- Add comprehensive documentation and tests
+
+### Style Operation File Structure
 
-### Adding Support to Custom Style Methods
+Each style operation file should follow this structure:
 
-When creating custom style modifiers, ensure they work within responsive blocks by:
+1. **Style Operation Implementation** - The core logic for generating CSS classes
+2. **Element Extension** - For direct styling with the `on: modifiers` parameter
+3. **Global Function** - For Declarative syntax within responsive blocks
 
-1. Adding a version without the `on modifiers` parameter
-2. Using the `.proxy()` method to maintain the proper element chain
-3. Adding examples showing how to use the style in responsive contexts
+This structure ensures full support across both interfaces and maintains consistency across the codebase.
 
 ## Styleguides
 

README.md

@@ -40,6 +40,7 @@
 - [Development](#development)
   - [Quick Reference](#quick-reference)
 - [Contributing](#contributing)
+- [Funding](#funding)
 - [Support](#support)
 - [License](#license)
 - [Acknowledgements](#acknowledgements)
@@ -140,6 +141,14 @@ else and are greatly appreciated.
 
 Please see our [CONTRIBUTING.md](CONTRIBUTING.md) document for detailed guidelines on how to contribute to this project. All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md).
 
+## Funding
+
+WebUI is an independent open-source project that relies on community support. If you find it useful, please consider supporting its development:
+
+- [GitHub Sponsors](https://github.com/sponsors/maclong9) - Direct support for maintainers
+
+Your support helps ensure WebUI remains actively maintained and continuously improved. Organizations using WebUI in production are especially encouraged to contribute financially to ensure the project's long-term sustainability.
+
 ## Support
 
 Reach out to the maintainer at one of the following places: