vident 1.0.0 → 1.0.2

data/lib/vident2/stimulus/controller.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "literal"
+require_relative "naming"
+
+module Vident2
+  module Stimulus
+    # `data-controller` fragment. Fields:
+    # - `path`    : raw underscored path (e.g. `"admin/user_card_component"`)
+    # - `name`    : dasherized/joined form (e.g. `"admin--user-card-component"`)
+    # - `alias_name`: optional Symbol the DSL uses to refer back to this
+    #   controller from other entries (`action(:save, on: :admin)`).
+    class Controller < ::Literal::Data
+      prop :path, String
+      prop :name, String
+      prop :alias_name, _Nilable(Symbol), default: nil
+
+      # `.parse(path = nil, as: nil, implied:)`
+      #
+      # No positional arg -> clone the implied controller (for unambiguous
+      # "refer to my own controller" use).
+      #
+      # One positional arg (String | Symbol) -> explicit controller path.
+      # `implied:` is unused in that branch but is accepted for uniformity
+      # with the other kinds' `.parse` signatures.
+      def self.parse(*args, as: nil, implied:, component_id: nil)
+        case args.size
+        when 0
+          new(path: implied.path, name: implied.name, alias_name: as)
+        when 1
+          raw = args[0]
+          path = raw.to_s
+          new(path: path, name: Naming.stimulize_path(path), alias_name: as)
+        else
+          raise ::Vident2::ParseError, "Controller.parse: expected 0 or 1 positional args, got #{args.size}"
+        end
+      end
+
+      def identifier = name
+
+      def to_s = name
+
+      def to_data_pair = [:controller, name]
+
+      def to_h = {controller: name}
+      # Ruby's `{**x}` splat calls #to_hash; alias so users can splat the
+      # data-attr pair directly into a tag's `data:` option.
+      alias_method :to_hash, :to_h
+
+      # Space-joined. Order preserved, duplicates kept (caller dedups).
+      def self.to_data_hash(controllers)
+        return {} if controllers.empty?
+        joined = controllers.map(&:name).reject(&:empty?).join(" ")
+        return {} if joined.empty?
+        {controller: joined}
+      end
+    end
+  end
+end

data/lib/vident2/stimulus/naming.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module Vident2
+  module Stimulus
+    # Pure naming helpers shared across value classes. No state, no
+    # inheritance — the v1 `StimulusAttributeBase` tree goes away in V2;
+    # each value class is a `Literal::Data` and just calls these module
+    # functions directly.
+    module Naming
+      module_function
+
+      # `"admin/users"` -> `"admin--users"`. Symbol or String accepted.
+      def stimulize_path(path)
+        path.to_s.split("/").map(&:dasherize).join("--")
+      end
+
+      # `:my_thing` -> `"myThing"`. Used for action method names and
+      # target names (not for attribute keys, which dasherize instead).
+      def js_name(name)
+        name.to_s.camelize(:lower)
+      end
+    end
+  end
+end

data/lib/vident2/stimulus/null.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Vident2
+  module Stimulus
+    # Sentinel that serialises to the literal string "null". Use in
+    # `value` / `param` positions where the Stimulus side expects a
+    # JSON-parsed JS `null` (Object / Array value types).
+    #
+    # A bare `nil` drops the attribute entirely. Reach for Null only when
+    # you need an explicit `"null"` in the emitted HTML.
+    Null = Object.new
+    def Null.inspect = "Vident2::Stimulus::Null"
+    def Null.to_s = "null"
+    Null.freeze
+  end
+end

data/lib/vident2/stimulus/outlet.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "literal"
+require_relative "naming"
+require_relative "controller"
+
+module Vident2
+  module Stimulus
+    # `data-<ctrl>-<name>-outlet` fragment. `selector` is the CSS selector
+    # the Stimulus runtime uses to resolve the outlet on the page.
+    #
+    # Auto-selector: `"#<component_id> [data-controller~=<outlet>]"`. If
+    # `component_id` is nil (host id not yet known) the `#<id>` prefix is
+    # omitted — caller must backfill if needed.
+    class Outlet < ::Literal::Data
+      prop :controller, Controller
+      prop :name, String
+      prop :selector, String
+
+      # `.parse(*args, implied:, component_id:)` grammar mirrors v1:
+      #   (Symbol)              -> outlet name on implied, auto-selector
+      #   (String)              -> outlet identifier, auto-selector
+      #   (Array[name, sel])    -> explicit [name, selector] pair
+      #   (Symbol|String, String) -> (name, explicit selector)
+      #   (String, Symbol, String) -> (ctrl_path, name, selector)
+      #   (<component instance>) -> grab stimulus_identifier and build auto-selector
+      def self.parse(*args, implied:, component_id: nil)
+        case args
+        in [Symbol => sym]
+          name = sym.to_s.dasherize
+          new(
+            controller: implied,
+            name: name,
+            selector: auto_selector(name, component_id: component_id)
+          )
+        in [String => str]
+          name = str.dasherize
+          new(
+            controller: implied,
+            name: name,
+            selector: auto_selector(str, component_id: component_id)
+          )
+        in [[identifier, selector]]
+          new(
+            controller: implied,
+            name: identifier.to_s.dasherize,
+            selector: selector
+          )
+        in [Symbol => sym, String => sel]
+          new(
+            controller: implied,
+            name: sym.to_s.dasherize,
+            selector: sel
+          )
+        in [String => id_or_name, String => sel]
+          new(
+            controller: implied,
+            name: id_or_name.dasherize,
+            selector: sel
+          )
+        in [String => ctrl_path, Symbol => sym, String => sel]
+          new(
+            controller: Controller.parse(ctrl_path, implied: implied),
+            name: sym.to_s.dasherize,
+            selector: sel
+          )
+        else
+          component_like = args.size == 1 ? args[0] : nil
+          if component_like && component_like.respond_to?(:stimulus_identifier)
+            ident = component_like.stimulus_identifier
+            new(
+              controller: implied,
+              name: ident,
+              selector: auto_selector(ident, component_id: component_id)
+            )
+          else
+            raise ::Vident2::ParseError, "Outlet.parse: invalid arguments #{args.inspect}"
+          end
+        end
+      end
+
+      def self.auto_selector(outlet_identifier, component_id:)
+        prefix = component_id ? "##{css_escape_ident(component_id)} " : ""
+        "#{prefix}[data-controller~=#{outlet_identifier}]"
+      end
+
+      # CSS-escapes anything outside the bare identifier alphabet
+      # (`A-Za-z0-9_-`) using the `\HH ` hex form (with trailing space
+      # delimiter). Bare `\<char>` works for many punctuation cases but
+      # not for whitespace, parens, or non-ASCII — the hex form is
+      # always valid per CSS Syntax §4.3.7.
+      def self.css_escape_ident(id)
+        id.to_s.gsub(/[^A-Za-z0-9_-]/) { |c| "\\#{c.ord.to_s(16)} " }
+      end
+
+      def to_s = selector
+
+      def data_attribute_key = :"#{controller.name}-#{name}-outlet"
+
+      def to_data_pair = [data_attribute_key, selector]
+
+      def to_h = {data_attribute_key => selector}
+      alias_method :to_hash, :to_h
+
+      def self.to_data_hash(outlets)
+        outlets.each_with_object({}) do |o, acc|
+          key, sel = o.to_data_pair
+          acc[key] = sel
+        end
+      end
+    end
+  end
+end

data/lib/vident2/stimulus/param.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "json"
+require "literal"
+require_relative "naming"
+require_relative "null"
+require_relative "controller"
+
+module Vident2
+  module Stimulus
+    # `data-<ctrl>-<name>-param` fragment — same shape as Value, distinct
+    # semantics on the JS side (read via `event.params.<camel>`).
+    class Param < ::Literal::Data
+      prop :controller, Controller
+      prop :name, String
+      prop :serialized, String
+
+      def self.parse(*args, implied:, component_id: nil)
+        case args
+        in [Symbol => name_sym, raw]
+          new(
+            controller: implied,
+            name: name_sym.to_s.dasherize,
+            serialized: serialize(raw)
+          )
+        in [String => ctrl_path, Symbol => name_sym, raw]
+          new(
+            controller: Controller.parse(ctrl_path, implied: implied),
+            name: name_sym.to_s.dasherize,
+            serialized: serialize(raw)
+          )
+        else
+          raise ::Vident2::ParseError, "Param.parse: invalid arguments #{args.inspect}"
+        end
+      end
+
+      def self.serialize(raw)
+        raise ::Vident2::ParseError, "Param.serialize: nil is not serializable — filter nil upstream" if raw.nil?
+        case raw
+        when Array, Hash then raw.to_json
+        else raw.to_s
+        end
+      end
+
+      def to_s = serialized
+
+      def data_attribute_key = :"#{controller.name}-#{name}-param"
+
+      def to_data_pair = [data_attribute_key, serialized]
+
+      def to_h = {data_attribute_key => serialized}
+      alias_method :to_hash, :to_h
+
+      def self.to_data_hash(params)
+        params.each_with_object({}) do |p, acc|
+          key, str = p.to_data_pair
+          acc[key] = str
+        end
+      end
+    end
+  end
+end

data/lib/vident2/stimulus/target.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "literal"
+require_relative "naming"
+require_relative "controller"
+
+module Vident2
+  module Stimulus
+    # `data-<ctrl>-target` fragment. One per target reference; the Array
+    # aggregator groups by controller and space-joins same-key values.
+    class Target < ::Literal::Data
+      prop :controller, Controller
+      prop :name, String
+
+      # `.parse(*args, implied:)`:
+      #   (Symbol)         -> target `:name` on implied controller
+      #   (String)         -> target name as-is on implied (already js-cased)
+      #   (String, Symbol) -> explicit (controller_path, target_name)
+      def self.parse(*args, implied:, component_id: nil)
+        case args
+        in [Symbol => sym]
+          new(controller: implied, name: Naming.js_name(sym))
+        in [String => str]
+          new(controller: implied, name: str)
+        in [String => ctrl_path, Symbol => sym]
+          new(
+            controller: Controller.parse(ctrl_path, implied: implied),
+            name: Naming.js_name(sym)
+          )
+        else
+          raise ::Vident2::ParseError, "Target.parse: invalid arguments #{args.inspect}"
+        end
+      end
+
+      def to_s = name
+
+      def data_attribute_key = :"#{controller.name}-target"
+
+      def to_data_pair = [data_attribute_key, name]
+
+      # Splat target for inline `data: {**target.to_h}` usage.
+      def to_h = {data_attribute_key => name}
+      alias_method :to_hash, :to_h
+
+      # Same-key concat with space. Example:
+      #   Target(row)                       -> "foo-target" => "row"
+      #   Target(row) + Target(cell)        -> "foo-target" => "row cell"
+      #   Target(row) + Target(x, on: bar)  -> {"foo-target"=>"row", "bar-target"=>"x"}
+      def self.to_data_hash(targets)
+        targets.each_with_object({}) do |t, acc|
+          key, value = t.to_data_pair
+          acc[key] = acc.key?(key) ? "#{acc[key]} #{value}" : value
+        end
+      end
+    end
+  end
+end

data/lib/vident2/stimulus/value.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+require "literal"
+require_relative "naming"
+require_relative "controller"
+require_relative "null"
+
+module Vident2
+  module Stimulus
+    # `data-<ctrl>-<name>-value` fragment. Holds the *serialised* form
+    # (always a String post-parse); Array/Hash inputs go through `to_json`,
+    # other non-nil inputs through `to_s`. The `Null` sentinel's `to_s`
+    # produces `"null"` naturally. Only `nil` drops at the caller —
+    # `false`, blank strings, and empty collections emit their serialised
+    # form.
+    class Value < ::Literal::Data
+      prop :controller, Controller
+      prop :name, String
+      prop :serialized, String
+
+      # `.parse(*args, implied:)` grammar:
+      #   (Symbol, raw)           -> implied controller, value named `Symbol`
+      #   (String, Symbol, raw)   -> explicit (controller_path, name, raw)
+      #
+      # The caller (Resolver / mutator) is responsible for filtering out
+      # `nil` before reaching here — see `serialize` for the check.
+      def self.parse(*args, implied:, component_id: nil)
+        case args
+        in [Symbol => name_sym, raw]
+          new(
+            controller: implied,
+            name: name_sym.to_s.dasherize,
+            serialized: serialize(raw)
+          )
+        in [String => ctrl_path, Symbol => name_sym, raw]
+          new(
+            controller: Controller.parse(ctrl_path, implied: implied),
+            name: name_sym.to_s.dasherize,
+            serialized: serialize(raw)
+          )
+        else
+          raise ::Vident2::ParseError, "Value.parse: invalid arguments #{args.inspect}"
+        end
+      end
+
+      # Raw -> String. `Null` sentinel serialises to `"null"` via its
+      # own `to_s`. `nil` should have been filtered upstream; raising
+      # here catches misrouted callers early.
+      def self.serialize(raw)
+        raise ::Vident2::ParseError, "Value.serialize: nil is not serializable — filter nil upstream" if raw.nil?
+        case raw
+        when Array, Hash then raw.to_json
+        else raw.to_s
+        end
+      end
+
+      def to_s = serialized
+
+      def data_attribute_key = :"#{controller.name}-#{name}-value"
+
+      def to_data_pair = [data_attribute_key, serialized]
+
+      def to_h = {data_attribute_key => serialized}
+      alias_method :to_hash, :to_h
+
+      # One entry per Value instance. Later-instance same-key wins on
+      # collision (Hash#merge semantics).
+      def self.to_data_hash(values)
+        values.each_with_object({}) do |v, acc|
+          key, str = v.to_data_pair
+          acc[key] = str
+        end
+      end
+    end
+  end
+end

data/lib/vident2/tailwind.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Vident2
+  # Thin Tailwind CSS merge integration — exposes a lazy per-thread merger
+  # instance so the ClassListBuilder can collapse conflicting utilities
+  # when ::TailwindMerge::Merger is available.
+  module Tailwind
+    def tailwind_merger
+      return unless tailwind_merge_available?
+      return @tailwind_merger if defined?(@tailwind_merger)
+
+      @tailwind_merger = Thread.current[:vident2_tailwind_merger] ||= ::TailwindMerge::Merger.new
+    end
+
+    def tailwind_merge_available?
+      defined?(::TailwindMerge::Merger) && ::TailwindMerge::Merger.respond_to?(:new)
+    end
+  end
+end

data/lib/vident2/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Vident2
+  VERSION = "2.0.0.alpha0"
+end

data/lib/vident2/view_component/base.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Vident2
+  module ViewComponent
+    class Base < ::ViewComponent::Base
+      include ::Vident2::Component
+
+      class << self
+        def cache_component_modified_time
+          cache_sidecar_view_modified_time + cache_rb_component_modified_time
+        end
+
+        def cache_sidecar_view_modified_time
+          ::File.exist?(template_path) ? ::File.mtime(template_path).to_i.to_s : ""
+        end
+
+        def cache_rb_component_modified_time
+          ::File.exist?(component_path) ? ::File.mtime(component_path).to_i.to_s : ""
+        end
+
+        def template_path
+          extensions = [".html.erb", ".erb", ".html.haml", ".haml", ".html.slim", ".slim"]
+          base_path = Rails.root.join(components_base_path, virtual_path)
+
+          extensions.each do |ext|
+            potential_path = "#{base_path}#{ext}"
+            return potential_path if File.exist?(potential_path)
+          end
+
+          Rails.root.join(components_base_path, "#{virtual_path}.html.erb").to_s
+        end
+
+        def component_path
+          Rails.root.join(components_base_path, "#{virtual_path}.rb").to_s
+        end
+
+        def components_base_path
+          ::Rails.configuration.view_component.view_component_path || "app/components"
+        end
+      end
+
+      SELF_CLOSING_TAGS = Set[*%i[area base br col embed hr img input link meta param source track wbr]].freeze
+
+      # ViewComponent lifecycle hook: resolve stimulus DSL procs now that
+      # `@view_context` is set (so `helpers` works inside them).
+      def before_render
+        resolve_stimulus_attributes_at_render_time
+        super
+      end
+
+      # Same block-capture-first ordering as the Phlex adapter. Children
+      # instantiated inside the block can still mutate this instance's
+      # Draft (outlet-host pattern) before we seal.
+      def root_element(**overrides, &block)
+        tag_type = root_element_tag_type
+        child_content = view_context.capture(self, &block) if block
+        options = build_root_element_attributes(overrides)
+        if SELF_CLOSING_TAGS.include?(tag_type)
+          view_context.tag(tag_type, options)
+        else
+          view_context.content_tag(tag_type, child_content, options)
+        end
+      end
+
+      # Inline ERB helpers: emit `data-*="..."` attribute strings for the
+      # given stimulus input. Thin wrappers around the plural/singular
+      # parsers — Collection#to_h is the splat target used by v1's helpers
+      # too. Returns an ActiveSupport::SafeBuffer.
+      def as_stimulus_targets(...)  = to_data_attribute_string(**stimulus_targets(...).to_h)
+      def as_stimulus_target(...)   = to_data_attribute_string(**stimulus_target(...).to_h)
+      def as_stimulus_actions(...)  = to_data_attribute_string(**stimulus_actions(...).to_h)
+      def as_stimulus_action(...)   = to_data_attribute_string(**stimulus_action(...).to_h)
+      def as_stimulus_controllers(...) = to_data_attribute_string(**stimulus_controllers(...).to_h)
+      def as_stimulus_controller(...)  = to_data_attribute_string(**stimulus_controller(...).to_h)
+      def as_stimulus_outlets(...)  = to_data_attribute_string(**stimulus_outlets(...).to_h)
+      def as_stimulus_outlet(...)   = to_data_attribute_string(**stimulus_outlet(...).to_h)
+      def as_stimulus_values(...)   = to_data_attribute_string(**stimulus_values(...).to_h)
+      def as_stimulus_value(...)    = to_data_attribute_string(**stimulus_value(...).to_h)
+      def as_stimulus_params(...)   = to_data_attribute_string(**stimulus_params(...).to_h)
+      def as_stimulus_param(...)    = to_data_attribute_string(**stimulus_param(...).to_h)
+      def as_stimulus_classes(...)  = to_data_attribute_string(**stimulus_classes(...).to_h)
+      def as_stimulus_class(...)    = to_data_attribute_string(**stimulus_class(...).to_h)
+
+      # Short aliases — same semantics as the singular `as_stimulus_*` above.
+      alias_method :as_target,     :as_stimulus_target
+      alias_method :as_action,     :as_stimulus_action
+      alias_method :as_controller, :as_stimulus_controller
+      alias_method :as_outlet,     :as_stimulus_outlet
+      alias_method :as_value,      :as_stimulus_value
+      alias_method :as_param,      :as_stimulus_param
+      alias_method :as_class,      :as_stimulus_class
+
+      private
+
+      def generate_child_element(tag_name, stimulus_data_attributes, options, &block)
+        options[:data] ||= {}
+        options[:data].merge!(stimulus_data_attributes)
+        if SELF_CLOSING_TAGS.include?(tag_name.to_sym)
+          view_context.tag(tag_name, options)
+        elsif block
+          view_context.content_tag(tag_name, view_context.capture(&block), options)
+        else
+          view_context.content_tag(tag_name, nil, options)
+        end
+      end
+
+      def escape_attribute_name_for_html(name)
+        name.to_s.gsub(/[^a-zA-Z0-9\-_]/, "").tr("_", "-")
+      end
+
+      def escape_attribute_value_for_html(value)
+        value.to_s.gsub('"', "&quot;").gsub("'", "&#39;")
+      end
+
+      def to_data_attribute_string(**attributes)
+        attributes.map { |key, value| "data-#{escape_attribute_name_for_html(key)}=\"#{escape_attribute_value_for_html(value)}\"" }
+          .join(" ")
+          .html_safe
+      end
+    end
+  end
+end

data/lib/vident2/view_component.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "view_component"
+require "vident2/view_component/base"
+
+module Vident2
+  module ViewComponent
+  end
+end

data/lib/vident2.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/concern"
+require "literal"
+
+require "vident2/version"
+
+# Vident 2.0 — synthesis rearchitecture per doc/reviews/wave-4-synthesis.md.
+# Built side-by-side with Vident 1.x during development; renamed to Vident
+# at release.
+module Vident2
+end
+
+# V1 still ships alongside V2 — Vident::StableId is aliased as
+# Vident2::StableId in lib/vident2/stable_id.rb so the V2 namespace stays
+# self-referential.
+require "vident"
+
+require "vident2/engine" if defined?(Rails::Engine)
+require "vident2/error"
+require "vident2/stable_id"
+
+require "vident2/stimulus/naming"
+require "vident2/stimulus/null"
+require "vident2/stimulus/controller"
+require "vident2/stimulus/action"
+require "vident2/stimulus/target"
+require "vident2/stimulus/outlet"
+require "vident2/stimulus/value"
+require "vident2/stimulus/param"
+require "vident2/stimulus/class_map"
+require "vident2/stimulus/collection"
+require "vident2/internals/registry"
+require "vident2/internals/declaration"
+require "vident2/internals/declarations"
+require "vident2/internals/dsl"
+require "vident2/internals/draft"
+require "vident2/internals/plan"
+require "vident2/internals/resolver"
+require "vident2/internals/attribute_writer"
+require "vident2/internals/class_list_builder"
+
+require "vident2/tailwind"
+require "vident2/caching"
+
+require "vident2/component"
+
+require "vident2/phlex"
+require "vident2/view_component"

data/skills/vident/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: Vident
 description: This skill should be used when writing or editing Rails view components in a project that depends on `vident`, `vident-view_component`, or `vident-phlex` — i.e. any class inheriting from `Vident::ViewComponent::Base` or `Vident::Phlex::HTML`, any paired `*_component_controller.js` Stimulus file next to such a component, or the `stimulus_*` props / `stimulus do ... end` DSL / `child_element` / `root_element` / `class_list_for_stimulus_classes` / `Vident::StimulusNull` / `Vident::StableId` APIs. It also covers the `bin/rails generate vident:install` initializer and the per-request ID seeding it installs on `ApplicationController`.
-version: 0.1.0
+version: 0.2.0
 ---
 
 # Vident
@@ -10,6 +10,8 @@ Vident is a thin layer on top of ViewComponent / Phlex that gives a component th
 
 A Vident component is always a class with props, a single `root_element`, and (optionally) a `stimulus do ... end` block that declares the controllers, actions, targets, values, classes and outlets its paired JavaScript file needs.
 
+> **Going deeper.** This file is the everyday reference. For end-to-end walkthroughs (dashboard, forms, slot-based parent/child wiring, ERB helper comparisons), read [`examples.md`](examples.md). For the exhaustive public-API spec (every signature, raise-condition, and argument shape), read [`api-reference.md`](api-reference.md).
+
 ---
 
 ## 1. Stimulus → Vident mapping
@@ -419,7 +421,10 @@ Plural (`as_stimulus_targets`, `as_stimulus_actions`, `as_stimulus_values`, `as_
 
 Opens a `Vident::StimulusBuilder` instance scoped to the class. It supports `actions`, `targets`, `values`, `values_from_props`, `classes`, `outlets`. Multiple `stimulus do` blocks on the same class are merged; a subclass's block is merged with its superclass's (subclass entries appended, values/classes/outlets merged by key, subclass wins on conflicts).
 
-Procs passed anywhere in the DSL are evaluated via `instance_exec` on the **component instance** at render time, so they see `@ivars` and public/private instance methods.
+Procs passed anywhere in the DSL are evaluated via `instance_exec` on the **component instance** at render time (Phlex `before_template` / ViewComponent `before_render`), so they see `@ivars`, public/private instance methods, and the view context.
+
+- **Phlex**: `helpers` is deprecated in phlex-rails. Opt in per Rails helper via `include Phlex::Rails::Helpers::NumberWithPrecision` (etc.), or use the `phlex_helpers :number_with_precision, :t, :l` class macro on `Vident::Phlex::HTML` which expands to the matching includes. Then call the helper bare inside the proc — `number_with_precision(@amount, precision: 2)`. See [phlex.fun/rails/helpers](https://www.phlex.fun/rails/helpers) for the full adapter list.
+- **ViewComponent**: `helpers.<method>` and `view_context.<method>` both work.
 
 ---
 
@@ -553,6 +558,8 @@ Inside `<name>OutletConnected`, **do not iterate `this.<name>Outlets`**. Stimulu
 
 ## 8. Recipes
 
+One-liners per task. For worked end-to-end versions (dashboard with outlets, slot trigger, ERB variants) see [`examples.md`](examples.md).
+
 **Click handler on the root** — `stimulus do; actions [:click, :select]; end` + `select(event) {…}` in JS.
 
 **Click handler on a child button** — `card.child_element(:button, stimulus_action: [:click, :promote]) { "Promote" }`.
@@ -616,6 +623,8 @@ end
 
 ## 9. Key source files
 
+For the exhaustive public-API listing (every method signature, argument shape, and raise-condition, verified against current code), see [`api-reference.md`](api-reference.md). The files below are useful when you need to read the implementation itself.
+
 - `lib/vident/stimulus_builder.rb` — DSL evaluator.
 - `lib/vident/stimulus_attributes.rb` — parser for every `stimulus_*` input shape + `as_stimulus_*` helpers' backing.
 - `lib/vident/stimulus_{action,target,value,outlet,class,controller}.rb` — value objects; read `parse_arguments` to learn the argument shapes.