vident-typed 0.3.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1538a8d7159f4a3dea4c3bd40f5c0edc30c00262aabf9a505da74d4e0d3c0b1
-  data.tar.gz: 43203f969a1050c33ecad71cf700ef61bfc395489e9f0b1841b931499c4fcc38
+  metadata.gz: bf3e343d6c3fa3bc0d46ae3f3e59757c4e8c3b68c3c25396e1f579823165ca9a
+  data.tar.gz: 689e256dd186f7908fb1ce5ef63c051233c5835bfba3ae67f6cb9c1b79f3c1a2
 SHA512:
-  metadata.gz: 87d05c5014f1664dff493157015c2e32412a9c5771a409b4f0054a88fec8d9d3749ae8078b7a5b05536f811410ad5c27a1697a3f22bd1e229b20b0c185ad6d2c
-  data.tar.gz: 0edd2414cedc991e1410937ea2870ed193c146af30d839c76b80d5f3e928d9b58ebddb5c92930056414a791ae4380294d79cd330b7a6d3253ee337744c617318
+  metadata.gz: 17bc0adf84eac80b3e151e52f936a56577ec5abd8e3577e78084383d1b13aa6c4e3fbf1b5387587d6641d846b0d2278bdf9ac8e299b91001115b20ecf228731f
+  data.tar.gz: 0ef12ffef78471279aa0d698e3b369c390200dcdfc4f99075fb6c8bd9afd80f4b8c12355dc87c0190d9294563dc5275780102c2054f71f49be417b0e18bd8911

data/CHANGELOG.md

@@ -0,0 +1,215 @@
+
+# Change Log
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+
+## [Unreleased]
+
+### Added
+
+- New monorepo structure for the Vident project, retaining the separate gems however.
+- All gems now have the same version and are released together.
+
+### Changed
+
+### Fixed
+
+## [0.12.1] - 2024-06-12
+
+### Fixed
+
+- parsing of targets where the controller is also specified
+
+## [0.12.0] - 2024-02-25
+
+### Added
+
+- `outlet` DSL methods updated so that the selector is scoped to the component's root element by default. This 
+  is probably the most common use case, and it's now the default.
+- `with_outlets` DSL method added to generate the data-* attributes for the outlets and return as a fragment  
+  of HTML
+
+
+## [0.11.0] - 2024-02-21
+
+### Added
+
+- `outlet_host` DSL method to support components hooking themselves into a host component's outlets
+
+
+
+## [0.10.1] - 2024-02-21
+
+### Added
+
+- `outlets` option now accepts either a string stimulus controller identifier, a component instance, or a tuple of 
+  identifier and CSS selector for the outlet.
+
+
+## [0.10.0] - 2024-02-21
+
+### Added
+
+- `outlets` option for components, used to specify Stimulus outlets 
+
+## [0.9.0] - 2023-08-11
+
+### Added
+
+- `#cache_key` support is now part of the core gem, and can be added to components using `Vident::Caching` module
+
+## [0.8.0] - 2023-03-31
+
+### Added
+
+- new gems for Vident related functionality, eg `vident-typed` and `vident-tailwind`
+- `vident` is now the core gem which can be used with any component system. Gems for Phlex and ViewComponent are available, `vident-phlex` and `vident-view_component`, and `vident-typed-phlex` and `vident-typed-view_component` are available with typed attributes support.
+
+### Changed
+
+- removed functionality for `better_html`, `dry-types`, `view_component`, and `phlex` from the core gem
+- gem is now a Rails Engine and supports eager and autoloading
+
+### Fixed
+
+- Fix untyped attributes inheritance
+
+## [0.7.0] - 2023-03-08  
+
+### Added
+
+- new `Vident::Tailwind` module which uses [tailwind_merge](https://github.com/gjtorikian/tailwind_merge) to merge TailwindCSS classes
+
+### Changed
+
+- Removed a dependency on intenal constants from `phlex`
+
+## [0.6.3] - 2023-03-03
+
+### Fixed
+
+- Fix for changes to HTML tag collection in Phlex
+
+
+## [0.6.2] - 2023-02-23
+
+### Fixed
+
+- Element tag options are not set when no ID is provided
+
+
+## [0.6.1] - 2023-02-20
+
+### Fixed
+
+- `better_html` support fix for aliased dsl methods
+
+
+## [0.6.0] - 2023-02-20
+
+### Added
+
+- Experimental support for `better_html` in the root components (the stimulus attributes are generated with `html_attributes`)
+
+
+
+## [0.5.1] - 2023-02-17
+
+### Added
+
+- N/A
+
+### Changed
+
+- N/A
+
+### Fixed
+
+- Typed attributes was not always using custom coercion methods if they were defined 
+
+### Removed
+
+- N/A
+
+### Deprecated
+
+- N/A
+
+### Security
+
+- N/A
+
+---
+
+# Package Changelogs
+
+## vident-better_html
+
+### [0.6.0] - 2023-02-20
+
+#### Added
+
+- Experimental support for `better_html` in the root components (the stimulus attributes are generated with `html_attributes`)
+
+### [0.6.1] - 2023-02-20
+
+#### Fixed
+
+- `better_html` support fix for aliased dsl methods
+
+## vident-tailwind
+
+### [0.1.1] - 2023-04-02
+
+#### Fixed
+
+- `tailwind_merge` should only take a non-nil value, and since it uses the class string as a cache key, it should not be blank.
+
+## vident-typed-view_component
+
+### [0.3.0] - 2023-08-12
+
+- Update to depend on `vident-view_component` v0.3.0
+- Adds support for new `Vident::Caching` module
+- Update examples to support view_component v3
+
+### [0.1.0] - 2023-04-01
+
+- Initial release, extracted from `vident`
+
+## vident-view_component
+
+### [0.3.0] - 2023-08-12
+
+- Update to depend on `vident` v0.9.0
+- Adds support for new `Vident::Caching` module
+- Update examples to support view_component v3
+
+### [0.1.0] - 2023-04-01
+
+- Initial release, extracted from `vident`
+
+## vident-phlex
+
+### [0.3.0] - 2023-08-12
+
+- Update to depend on `vident` v0.9.0
+- Adds support for new `Vident::Caching` module
+
+### [0.1.0] - 2023-04-01
+
+- Initial release, extracted from `vident`
+
+## vident-typed-phlex
+
+### [0.3.0] - 2023-08-12
+
+- Update to depend on `vident-typed` v0.3.0
+- Adds support for new `Vident::Caching` module
+
+### [0.1.0] - 2023-04-01
+
+- Initial release, extracted from `vident`

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022-2025 Stephen Ierodiaconou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,10 +1,657 @@
+# Vident
+
+Vident is a collection of gems that provide a set of tools for building web applications with Ruby on Rails.
+
+## Included Gems
+
+- `vident`: The core Vident library
+- `vident-better_html`: Better HTML integration for Vident
+- `vident-phlex`: Phlex integration for Vident
+- `vident-tailwind`: Tailwind CSS integration for Vident
+- `vident-typed`: Type system for Vident components
+- `vident-typed-minitest`: Minitest integration for typed Vident components
+- `vident-typed-phlex`: Phlex integration for typed Vident components
+- `vident-typed-view_component`: ViewComponent integration for typed Vident
+- `vident-view_component`: ViewComponent integration for Vident
+- `vident-view_component-caching`: Caching support for Vident ViewComponents
+
+## Directory Structure
+
+The repository is structured like this:
+
+```
+vident/
+├── lib/                       # All gem code
+│   ├── vident.rb              # Core entry point
+│   ├── vident-phlex.rb        # Gem entry points
+│   ├── vident-better_html.rb
+│   ├── vident/                # Shared code
+│       ├── base.rb
+│       ├── phlex/             # Phlex integration
+│       ├── better_html/       # Better HTML integration
+│       └── ...
+├── test/                      # All tests
+│   ├── vident/                # Core tests
+│   ├── vident-phlex/          # Tests for each gem
+│   └── ...
+├── docs/                      # Documentation
+├── examples/                  # Examples
+├── vident.gemspec            # Gemspec for core gem
+├── vident-phlex.gemspec      # Gemspecs for each gem
+└── ...
+```
+
+## Development
+
+### Setting Up Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/stevegeek/vident.git
+cd vident
+
+# Install dependencies
+bundle install
+```
+
+### Running Tests
+
+To run tests for all gems:
+
+```bash
+rake test
+```
+
+To run tests for a specific gem:
+
+```bash
+rake test:vident-phlex
+```
+
+### Building and Installing Gems
+
+To build all gems:
+
+```bash
+rake build
+```
+
+To install all gems locally:
+
+```bash
+rake install
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+The gems are available as open source under the terms of the [MIT License](LICENSE.txt).
+
+---
+
+# Component Documentation
+
+## gem: vident-better_html
+
+# Vident::BetterHtml
+Short description and motivation.
+
+### Usage
+How to use my plugin.
+
+```ruby
+BetterHtml.config = BetterHtml::Config.new(YAML.load(File.read(".better-html.yml")))
+
+BetterHtml.configure do |config|
+  config.template_exclusion_filter = proc { |filename| !filename.start_with?(Rails.root.to_s) }
+end
+# ViewComponent needs to do this hack to work in certain cases
+# see https://github.com/Shopify/better-html/pull/98
+class BetterHtml::HtmlAttributes
+  alias_method :to_s_without_html_safe, :to_s
+
+  def to_s
+    to_s_without_html_safe.html_safe
+  end
+end
+```
+
+### Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "vident-better_html"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install vident-better_html
+```
+
+---
+
+## gem: vident-phlex
+
+# Vident::Phlex
+
+[Phlex](https://phlex.fun/) powered [Vident](https://github.com/stevegeek/vident) components.
+
+```ruby
+class ApplicationComponent < ::Vident::Phlex::HTML
+end
+```
+
+For more details see [vident](https://github.com/stevegeek/vident).
+
+### Usage
+How to use my plugin.
+
+### Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "vident-phlex"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install vident-phlex
+```
+
+---
+
+## gem: vident-tailwind
+
+# Vident::Tailwind
+Short description and motivation.
+
+### Usage
+How to use my plugin.
+
+### Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "vident-tailwind"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install vident-tailwind
+```
+
+---
+
+## gem: vident-typed-minitest
+
+# Vident::Typed::Minitest
+Short description and motivation.
+
+### Usage
+How to use my plugin.
+
+### Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "vident-typed-minitest"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install vident-typed-minitest
+```
+
+---
+
+## gem: vident-typed-phlex
+
+# Vident::Typed::Phlex
+
+Adds typed attributes to Vident Phlex based components.
+
+```ruby
+class ApplicationComponent < ::Vident::Typed::Phlex::HTML
+end
+```
+
+For more details see [vident](https://github.com/stevegeek/vident).
+
+### Usage
+How to use my plugin.
+
+### Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "vident-typed-phlex"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install vident-typed-phlex
+```
+
+---
+
+## gem: vident-typed-view_component
+
+# Vident::Typed::ViewComponent
+
+Adds typed attributes to Vident ViewComponent components.
+
+```ruby
+class ApplicationComponent < ::Vident::Typed::ViewComponent::Base
+end
+```
+
+For more details see [vident](https://github.com/stevegeek/vident).
+
+### Examples
+
+Before we dive into a specific example note that there are some components implemented in `test/dummy/app/components`.
+
+Try them out by starting Rails:
+
+```bash
+cd test/dummy
+bundle install
+rails assets:precompile
+rails s
+```
+
+and visiting http://localhost:3000
+
+
+### A Vident component example (without Stimulus)
+
+First is an example component that uses `Vident::Typed::ViewComponent::Base` but no Stimulus features.
+
+It is an avatar component that can either be displayed as an image or as initials.
+
+It supports numerous sizes and shapes and can optionally have a border. It also generates a cache key for use in fragment caching or etag generation.
+
+```ruby
+class AvatarComponent < ::Vident::Typed::ViewComponent::Base
+  include ::Vident::Tailwind
+  include ::Vident::Caching
+
+  no_stimulus_controller
+  with_cache_key :attributes
+
+  attribute :url, String, allow_nil: true, allow_blank: false
+  attribute :initials, String, allow_blank: false
+
+  attribute :shape, Symbol, in: %i[circle square], default: :circle
+
+  attribute :border, :boolean, default: false
+
+  attribute :size, Symbol, in: %i[tiny small normal medium large x_large xx_large], default: :normal
+
+  private
+
+  def default_html_options
+    if image_avatar?
+      { class: "inline-block object-contain", src: url, alt: t(".image") }
+    else
+      { class: "inline-flex items-center justify-center bg-gray-500" }
+    end
+  end
+
+  def element_classes
+    [size_classes, shape_class, border? ? "border" : ""]
+  end
+
+  alias_method :image_avatar?, :url?
+
+  def shape_class
+    (shape == :circle) ? "rounded-full" : "rounded-md"
+  end
+
+  def size_classes
+    case size
+    when :tiny
+      "w-6 h-6"
+    when :small
+      "w-8 h-8"
+    when :medium
+      "w-12 h-12"
+    when :large
+      "w-14 h-14"
+    when :x_large
+      "sm:w-24 sm:h-24 w-16 h-16"
+    when :xx_large
+      "sm:w-32 sm:h-32 w-24 h-24"
+    else
+      "w-10 h-10"
+    end
+  end
+
+  def text_size_class
+    case size
+    when :tiny
+      "text-xs"
+    when :small
+      "text-xs"
+    when :medium
+      "text-lg"
+    when :large
+      "sm:text-xl text-lg"
+    when :extra_large
+      "sm:text-2xl text-xl"
+    else
+      "text-medium"
+    end
+  end
+end
+```
+
+```erb
+<%= render root(
+             element_tag: image_avatar? ? :img : :div,
+             html_options: default_html_options
+           ) do %>
+  <% unless image_avatar? %>
+    <span class="<%= text_size_class %> font-medium leading-none text-white"><%= initials %></span>
+  <% end %>
+<% end %>
+
+```
+
+Example usages:
+
+```erb
+<!-- These will render -->
+<%= render AvatarComponent.new(url: "https://someurl.com/avatar.jpg", initials: "AB" size: :large) %>
+<%= render AvatarComponent.new(url: "https://someurl.com/avatar.jpg", html_options: {alt: "My alt text", class: "object-scale-down"}) %>
+<%= render AvatarComponent.new(initials: "SG", size: :small) %>
+<%= render AvatarComponent.new(initials: "SG", size: :large, html_options: {class: "border-2 border-red-600"}) %>
+
+<!-- These will raise an error -->
+<!-- missing initals -->
+<%= render AvatarComponent.new(url: "https://someurl.com/avatar.jpg", size: :large) %> 
+<!-- initials blank -->
+<%= render AvatarComponent.new(initials: "", size: :large) %> 
+ <!-- invalid size -->
+<%= render AvatarComponent.new(initials: "SG", size: :foo_bar) %>
+```
+
+
+The following is rendered when used `render AvatarComponent.new(initials: "SG", size: :small, border: true)`:
+
+```html
+<div class="avatar-component w-8 h-8 rounded-full border inline-flex items-center justify-center bg-gray-500" id="avatar-component-9790427-12">
+  <span class="text-xs font-medium leading-none text-white">SG</span>
+</div>
+```
+
+The following is rendered when used `render AvatarComponent.new(url: "https://i.pravatar.cc/300", initials: "AB", html_options: {alt: "My alt text", class: "block"})`:
+
+```html
+<img src="https://i.pravatar.cc/300" alt="My alt text" class="avatar-component w-10 h-10 rounded-full object-contain block" id="avatar-component-7083941-11">
+```
+
+----
+
+![Example](examples/avatar.png)
+
+
+### Another ViewComponent + Vident example with Stimulus
+
+Consider the following ERB that might be part of an application's views. The app uses `ViewComponent`, `Stimulus` and `Vident`.
+
+The Greeter is a component that displays a text input and a button. When the button is clicked, the text input's value is
+used to greet the user. At the same time the button changes to be a 'reset' button, which resets the greeting when clicked again.
+
+![ex1.gif](examples/ex1.gif)
+
+```erb
+<%# app/views/home/index.html.erb %>
+
+<!-- ... -->
+
+<!-- render the Greeter ViewComponent (that uses Vident) -->
+<%= render ::GreeterComponent.new(cta: "Hey!", html_options: {class: "my-4"}) do |greeter| %>
+  <%# this component has a slot called `trigger` that renders a `ButtonComponent` (which also uses Vident) %> 
+  <% greeter.with_trigger(
+       
+       # The button component has attributes that are typed
+       before_clicked: "Greet",
+       after_clicked: "Greeted! Reset?",
+       
+       # A stimulus action is added to the button that triggers the `greet` action on the greeter stimulus controller.
+       # This action will be added to any defined on the button component itself
+       actions: [
+         greeter.action(:click, :greet),
+       ],
+       
+       # We can also override the default button classes of our component, or set other HTML attributes
+       html_options: {
+         class: "bg-red-500 hover:bg-red-700"
+       }
+     ) %>
+<% end %>
+
+<!-- ... -->
+```
+
+The output HTML of the above, using Vident, is:
+
+```html 
+<div class="greeter-component py-2 my-4" 
+     data-controller="greeter-component" 
+     data-greeter-component-pre-click-class="text-md text-gray-500" 
+     data-greeter-component-post-click-class="text-xl text-blue-700" 
+     id="greeter-component-1599855-6">
+  <input type="text" 
+         data-greeter-component-target="name" 
+         class="shadow appearance-none border rounded py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline">
+  <button class="button-component ml-4 whitespace-no-wrap bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded bg-red-500 hover:bg-red-700" 
+          data-controller="button-component" 
+          data-action="click->greeter-component#greet button-component#changeMessage" 
+          data-button-component-after-clicked-message="Greeted! Reset?" 
+          data-button-component-before-clicked-message="Greet" 
+          id="button-component-7799479-7">Hey!</button>
+  <!-- you can also use the `target_tag` helper to render targets -->
+  <span class="ml-4 text-md text-gray-500" 
+        data-greeter-component-target="output">
+    ...
+  </span>
+</div>
+```
+
+Let's look at the components in more detail.
+
+The main component is the `GreeterComponent`:
+
+```ruby
+# app/components/greeter_component.rb
+
+class GreeterComponent < ::Vident::ViewComponent::Base
+  renders_one :trigger, ButtonComponent
+end
+```
+
+```erb
+<%# app/components/greeter_component.html.erb %>
+
+<%# Rendering the `root` element creates a tag which has stimulus `data-*`s, a unique id & other attributes set. %>
+<%# The stimulus controller name (identifier) is derived from the component name, and then used to generate the relavent data attribute names. %>
+
+<%= render root named_classes: {
+  pre_click: "text-md text-gray-500", # named classes are exposed to Stimulus as `data-<controller>-<n>-class` attributes
+  post_click: "text-xl text-blue-700",
+  html_options: {class: "py-2"}
+} do |greeter| %>
+
+  <%# `greeter` is the root element and exposes methods to generate stimulus targets and actions %>
+  <input type="text"
+         <%= greeter.as_target(:name) %>
+         class="shadow appearance-none border rounded py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline">
+  
+  <%# Render the slot %>
+  <%= trigger %>
+  
+  <%# you can also use the `target_tag` helper to render targets %>
+  <%= greeter.target_tag(
+        :span, 
+        :output, 
+        # Stimulus named classes can be referenced to set class attributes at render time
+        class: "ml-4 #{greeter.named_classes(:pre_click)}" 
+      ) do %>
+    ...
+  <% end %>
+<% end %>
+
+```
+
+```js
+// app/components/greeter_component_controller.js
+
+import { Controller } from "@hotwired/stimulus"
+
+// This is a Stimulus controller that is automatically registered for the `GreeterComponent`
+// and is 'sidecar' to the component. You can see that while in the ERB we use Ruby naming conventions
+// with snake_case Symbols, here they are converted to camelCase names. We can also just use camelCase 
+// in the ERB if we want.
+export default class extends Controller {
+  static targets = [ "name", "output" ]
+  static classes = [ "preClick", "postClick" ]
+
+  greet() {
+    this.clicked = !this.clicked;
+    this.outputTarget.classList.toggle(this.preClickClasses, !this.clicked);
+    this.outputTarget.classList.toggle(this.postClickClasses, this.clicked);
+
+    if (this.clicked)
+      this.outputTarget.textContent = `Hello, ${this.nameTarget.value}!`
+    else
+      this.clear();
+  }
+
+  clear() {
+    this.outputTarget.textContent = '...';
+    this.nameTarget.value = '';
+  }
+}
+```
+
+The slot renders a `ButtonComponent` component:
+
+```ruby
+# app/components/button_component.rb
+
+class ButtonComponent < ::Vident::Typed::ViewComponent::Base
+  # The attributes can specify an expected type, a default value and if nil is allowed.
+  attribute :after_clicked, String, default: "Greeted!"
+  attribute :before_clicked, String, allow_nil: false
+
+  # This example is a templateless ViewComponent.
+  def call
+    # The button is rendered as a <button> tag with an click action on its own controller.
+    render root(
+      element_tag: :button,
+      
+      # We can define actions as arrays of Symbols, or pass manually manually crafted strings.
+      # Here we specify the action name only, implying an action on the current components controller
+      # and the default event type of `click`.
+      actions: [:change_message],
+      # Alternatively: [:click, :change_message] or ["click", "changeMessage"] or even "click->button-component#changeMessage"
+      
+      # A couple of data values are also set which will be available to the controller
+      data_maps: [{after_clicked_message: after_clicked, before_clicked_message: before_clicked}],
+      
+      # The <button> tag has a default styling set directly on it. Note that
+      # if not using utility classes, you can style the component using its 
+      # canonical class name (which is equal to the component's stimulus identifier), 
+      # in this case `button-component`.
+      html_options: {class: "ml-4 whitespace-no-wrap bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"}
+    ) do
+      @before_clicked
+    end
+  end
+end
+```
+
+```js  
+// app/components/button_component_controller.js
+
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  // The action is in camelCase.
+  changeMessage() {
+    this.clicked = !this.clicked;
+    // The data attributes have their naming convention converted to camelCase.
+    this.element.textContent = this.clicked ? this.data.get("afterClickedMessage") : this.data.get("beforeClickedMessage");
+  }
+}
+
+```
+
+### Usage
+How to use my plugin.
+
+### Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "vident-typed-view_component"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install vident-typed-view_component
+```
+
+---
+
+## gem: vident-typed
+
 # Vident::Typed
 Short description and motivation.
 
-## Usage
+### Usage
 How to use my plugin.
 
-## Installation
+### Installation
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -21,8 +668,199 @@ Or install it yourself as:
 $ gem install vident-typed
 ```
 
-## Contributing
-Contribution directions go here.
+---
 
-## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+## gem: vident-view_component-caching
+
+# Vident::ViewComponent::Caching
+Short description and motivation.
+
+### Usage
+How to use my plugin.
+
+### Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "vident-view_component-caching"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install vident-view_component-caching
+```
+
+---
+
+## gem: vident-view_component
+
+# Vident::ViewComponent
+
+[ViewComponent](https://viewcomponent.org/) powered [Vident](https://github.com/stevegeek/vident) components.
+
+```ruby
+class ApplicationComponent < ::Vident::ViewComponent::Base
+end
+```
+
+For more details see [vident](https://github.com/stevegeek/vident).
+
+### Examples
+
+Before we dive into a specific example note that there are some components implemented in the `test/dummy/app/components`.
+
+Try them out by starting Rails:
+
+```bash
+cd test/dummy
+bundle install
+rails assets:precompile
+rails s
+```
+
+and visiting http://localhost:3000
+
+
+### A Vident component example (without Stimulus)
+
+First is an example component that uses `Vident::ViewComponent::Base` but no Stimulus features. 
+
+It is an avatar component that can either be displayed as an image or as initials. It supports numerous sizes and shapes and can optionally have a border. It also generates a cache key for use in fragment caching or etag generation.
+
+```ruby
+class AvatarComponent < ::Vident::ViewComponent::Base
+  include ::Vident::Tailwind
+  include ::Vident::Caching
+
+  no_stimulus_controller
+  with_cache_key :attributes
+
+  attribute :url, allow_nil: true
+  attribute :initials, allow_nil: false
+
+  attribute :shape, default: :circle
+
+  attribute :border, default: false
+
+  attribute :size, default: :normal
+
+  private
+
+  def default_html_options
+    if image_avatar?
+      { class: "inline-block object-contain", src: url, alt: t(".image") }
+    else
+      { class: "inline-flex items-center justify-center bg-gray-500" }
+    end
+  end
+
+  def element_classes
+    [size_classes, shape_class, border? ? "border" : ""]
+  end
+
+  alias_method :image_avatar?, :url?
+
+  def shape_class
+    (shape == :circle) ? "rounded-full" : "rounded-md"
+  end
+
+  def size_classes
+    case size
+    when :tiny
+      "w-6 h-6"
+    when :small
+      "w-8 h-8"
+    when :medium
+      "w-12 h-12"
+    when :large
+      "w-14 h-14"
+    when :x_large
+      "sm:w-24 sm:h-24 w-16 h-16"
+    when :xx_large
+      "sm:w-32 sm:h-32 w-24 h-24"
+    else
+      "w-10 h-10"
+    end
+  end
+
+  def text_size_class
+    case size
+    when :tiny
+      "text-xs"
+    when :small
+      "text-xs"
+    when :medium
+      "text-lg"
+    when :large
+      "sm:text-xl text-lg"
+    when :extra_large
+      "sm:text-2xl text-xl"
+    else
+      "text-medium"
+    end
+  end
+end
+```
+
+```erb
+<%= render root(
+             element_tag: image_avatar? ? :img : :div,
+             html_options: default_html_options
+           ) do %>
+  <% unless image_avatar? %>
+    <span class="<%= text_size_class %> font-medium leading-none text-white"><%= initials %></span>
+  <% end %>
+<% end %>
+```
+
+Example usages:
+
+```erb
+<%= render AvatarComponent.new(url: "https://someurl.com/avatar.jpg", initials: "AB" size: :large) %>
+<%= render AvatarComponent.new(url: "https://someurl.com/avatar.jpg", html_options: {alt: "My alt text", class: "object-scale-down"}) %>
+<%= render AvatarComponent.new(initials: "SG", size: :small) %>
+<%= render AvatarComponent.new(initials: "SG", size: :large, html_options: {class: "border-2 border-red-600"}) %>
+```
+
+The following is rendered when used `render AvatarComponent.new(initials: "SG", size: :small, border: true)`:
+
+```html
+<div class="avatar-component w-8 h-8 rounded-full border inline-flex items-center justify-center bg-gray-500" id="avatar-component-9790427-12">
+  <span class="text-xs font-medium leading-none text-white">SG</span>
+</div>
+```
+
+The following is rendered when used `render AvatarComponent.new(url: "https://i.pravatar.cc/300", initials: "AB", html_options: {alt: "My alt text", class: "block"})`:
+
+```html
+<img src="https://i.pravatar.cc/300" alt="My alt text" class="avatar-component w-10 h-10 rounded-full object-contain block" id="avatar-component-7083941-11">
+```
+
+----
+
+![Example](examples/avatar.png)
+
+### Usage
+How to use my plugin.
+
+### Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "vident-view_component"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install vident-view_component
+```

data/lib/vident/typed/attributes.rb

@@ -147,7 +147,7 @@ module Vident
         def allows_blank?(options)
           return true unless options
           allow_blank = options[:allow_blank]
-          allow_blank.nil? ? true : allow_blank
+          allow_blank.nil? || allow_blank
         end
 
         def map_primitive_to_dry_type(signatures, strict, converter)

data/lib/vident/typed/component.rb

@@ -20,7 +20,7 @@ module Vident
         attribute :outlet_host, :any, delegates: false
 
         attribute :targets, Array, default: [], delegates: false
-        attribute :data_maps, Array, default: [], delegates: false
+        attribute :values, Array, default: [], delegates: false
 
         # TODO normalise the syntax of defining actions, controllers, etc
         attribute :named_classes, Hash, delegates: false

data/lib/vident/typed/version.rb

@@ -1,5 +1,5 @@
 module Vident
   module Typed
-    VERSION = "0.3.0"
+    VERSION = Vident::VERSION
   end
 end

data/lib/vident/typed.rb

@@ -1,5 +1,9 @@
 require "vident/typed/version"
-require "vident/typed/engine"
+require "vident/typed/typed_niling_struct"
+require "vident/typed/types"
+require "vident/typed/attributes"
+require "vident/typed/component"
+require "vident/typed/engine" if defined?(Rails)
 
 require "dry-struct"
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: vident-typed
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Stephen Ierodiaconou
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-21 00:00:00.000000000 Z
+date: 2025-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -16,60 +15,54 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '7.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '7.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '7.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '7.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: vident
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.8.0
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1'
+        version: 0.13.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.0
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '1'
+        version: 0.13.0
 - !ruby/object:Gem::Dependency
   name: dry-struct
   requirement: !ruby/object:Gem::Requirement
@@ -97,9 +90,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE.txt
 - README.md
-- Rakefile
-- lib/tasks/vident/typed_tasks.rake
 - lib/vident/typed.rb
 - lib/vident/typed/attributes.rb
 - lib/vident/typed/component.rb
@@ -107,14 +100,13 @@ files:
 - lib/vident/typed/typed_niling_struct.rb
 - lib/vident/typed/types.rb
 - lib/vident/typed/version.rb
-homepage: https://github.com/stevegeek/vident-typed
+homepage: https://github.com/stevegeek/vident
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/stevegeek/vident-typed
-  source_code_uri: https://github.com/stevegeek/vident-typed
-  changelog_uri: https://github.com/stevegeek/vident-typed/blob/main/CHANGELOG.md
-post_install_message:
+  homepage_uri: https://github.com/stevegeek/vident
+  source_code_uri: https://github.com/stevegeek/vident
+  changelog_uri: https://github.com/stevegeek/vident/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -122,15 +114,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Vident with typed attributes
 test_files: []

data/Rakefile

@@ -1,8 +0,0 @@
-require "bundler/setup"
-
-APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
-load "rails/tasks/engine.rake"
-
-load "rails/tasks/statistics.rake"
-
-require "bundler/gem_tasks"

data/lib/tasks/vident/typed_tasks.rake

@@ -1,4 +0,0 @@
-# desc "Explaining what the task does"
-# task :vident_typed do
-#   # Task goes here
-# end