poetry-ui 0.0.2

data/app/components/poetry/ui/tag_group/component.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Removable-chip collections.
+    module TagGroup
+      # A collection of removable chips - recipients, filters, labels.
+      # The group is one Tab stop with grid semantics: arrow keys move
+      # between tags, Delete/Backspace removes the focused tag, each
+      # chip's remove button removes exactly its own, and focus recovers
+      # to a neighbor after a removal. With name: the group is a form
+      # value - one hidden name[] input submits per tag. Removal is
+      # cancelable via the poetry:tag-group:remove event, so a server
+      # (Turbo) re-render can own it instead.
+      #
+      # label: is required - it names the grid for assistive tech. Tags
+      # here are removal-only: toggling fixed choices is ToggleGroup,
+      # picking from options is Combobox multiple.
+      #
+      # @example Removable recipients that submit as recipients[]
+      #   render Poetry::Ui::TagGroup::Component.new(label: "Recipients", name: "recipients") do |group|
+      #     group.with_tag(value: "ada", label: "Ada")
+      #     group.with_tag(value: "grace", label: "Grace")
+      #   end
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Removable chips are a TagGroup - never hand-rolled badges with x buttons; removal " \
+          "keyboard (Delete/Backspace), focus recovery, and the live region ride the controller.",
+          "label: is REQUIRED (the grid's accessible name, rendered as a caption span).",
+          "name: turns the group into a form value - one hidden <name>[] input per tag " \
+          "submits; removing a tag removes its input.",
+          "Removal is cancelable: listen for poetry:tag-group:remove and preventDefault to " \
+          "own the removal server-side (Turbo re-render).",
+          "Choosing from options is Combobox multiple; toggling fixed choices is ToggleGroup - " \
+          "a TagGroup holds items that exist until removed."
+        ].freeze
+
+        renders_many :tags,
+                     doc: "Declares one chip. value: is its identity (and form value); label: is the accessible " \
+                          "name and the visible text when no block is given; removable: false drops the remove " \
+                          "button.",
+                     renders: lambda { |value:, label: nil, disabled: false, removable: true, **options, &block|
+                       tag_row(value: value, label: label, disabled: disabled, removable: removable, **options, &block)
+                     }
+
+        # Both controllers declare on the grid element: roving-focus owns
+        # the arrow keys, with the group's own keydown (removal keys)
+        # layered on the same event.
+        use_stimulus do
+          on :grid do
+            controller :tag_group do
+              register
+              action :keydown, on: :keydown
+            end
+            controller :roving_focus do
+              register
+              value :orientation, :horizontal
+              value :loop, true
+              action :keydown, on: :keydown
+            end
+          end
+          on :remove do
+            controller(:tag_group) { action :remove, on: :click }
+          end
+        end
+
+        option :name, :string, doc: "Makes the group a form value: one hidden <name>[] input submits per tag."
+        option :label, :string, required: true, doc: "The grid's accessible name, rendered as a caption span. Required."
+        option :described_by, :string,
+               doc: "Space-separated hint/error ids for the GRID (the labelled element) - a raw aria-describedby in " \
+                    "html_attributes would land on the outer wrapper div, unassociated for AT."
+
+        part "tag-group", "The labelled wrapper - caption span + grid stack here"
+        part "tag-group-label", "The caption span (label:), wired via aria-labelledby (a grid " \
+                                "is not a labelable form control - never a <label>)"
+        part "tag-group-grid", "The tag collection (role=grid; role=group + the tab stop when " \
+                               "empty) - roving focus, removal keys, and the focus-scoped " \
+                               "live region ride here",
+             states: {
+               "data-empty" => "no tags remain (controller-kept after removals)"
+             }
+        part "tag-group-tag", "One chip (role=row > gridcell): content, the remove button, " \
+                              "and - in form mode - the hidden name[] input",
+             states: {
+               "data-disabled" => "the tag is disabled (skipped by arrows and removal)",
+               "data-value" => { condition: "always - the tag's value (the remove event's " \
+                                            "detail and the hidden input's value)" }
+             }
+        part "tag-group-remove", "The per-tag remove button - tabbable (Tab steps from the " \
+                                 "row into it), removes exactly its own tag"
+
+        # @api private
+        def before_render
+          raise ArgumentError, "TagGroup requires label: (the grid's accessible name)" if label.blank?
+        end
+
+        # One instance id (ladder: caller id -> key -> random); every
+        # inner id derives from it - so a keyed group's label AND rows are
+        # all morph-stable, and rows never touch a group-level allocator.
+        # @api private
+        def instance_id
+          @instance_id ||= poetry_instance_id("poetry-tag-group")
+        end
+
+        # @api private
+        def label_id
+          "#{instance_id}-label"
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            { "data-slot" => "tag-group", "class" => css }.merge(component_data_attributes)
+          )
+        end
+
+        # @api private
+        def grid_attributes
+          attrs = {
+            "role" => tags.any? ? "grid" : "group",
+            "data-slot" => "tag-group-grid",
+            "class" => css(:grid),
+            "aria-labelledby" => label_id,
+            **(described_by.present? ? { "aria-describedby" => described_by } : {}),
+            # Polite only while focus is within (controller-flipped): SRs
+            # hear tags added mid-work without spam from elsewhere.
+            "aria-live" => "off",
+            "aria-atomic" => "false",
+            "aria-relevant" => "additions"
+          }
+          attrs["data-empty"] = "" if tags.none?
+          attrs["tabindex"] = "0" if tags.none?
+          attrs.merge(stimulus_attributes_for(:grid))
+        end
+
+        # Built here (not in the template) so the slot lambda can compose
+        # the full row - content, remove button, hidden input - around the
+        # consumer's block.
+        # @api private
+        def tag_row(value:, label:, disabled:, removable:, **options, &block)
+          # Rows are the reorderable collection: identity derives from
+          # value: (the collection contract - unique within the group),
+          # namespaced under the group's instance id so two groups with
+          # the same tag values never collide.
+          row_id = options[:id].presence ||
+                   "#{instance_id}-tag-#{Poetry::Core::StableId.key_token(value) || SecureRandom.hex(8)}"
+          attrs = {
+            "id" => row_id, "role" => "row", "data-slot" => "tag-group-tag",
+            "data-value" => value, "data-poetry-collection-item" => "",
+            "aria-label" => label || value.to_s,
+            "tabindex" => "-1", "class" => css(:tag)
+          }
+          attrs["data-disabled"] = "" if disabled
+
+          # Caller options ride along (they were silently discarded before);
+          # data-value is RESERVED - the row's collection identity comes
+          # from value:, any caller spelling loses.
+          options.delete(:"data-value")
+          options.delete("data-value")
+          merged = Poetry::Core::HTML::Attributes.merged(attrs, options.except(:id))
+          merged["data-value"] = value
+
+          content_tag(:div, merged) do
+            content_tag(:span, { "role" => "gridcell", "class" => css(:cell) }) do
+              safe_join([
+                # label: doubles as the visible content when no block is
+                # given (the builder's model-array path renders text-only).
+                block ? capture(&block) : label.to_s,
+                (remove_button(row_id, disabled: disabled) if removable),
+                (hidden_input(value) if name.present?)
+              ].compact)
+            end
+          end
+        end
+
+        private
+
+        def remove_button(row_id, disabled:)
+          button_id = "#{row_id}-remove"
+          attrs = {
+            "type" => "button", "id" => button_id,
+            "data-slot" => "tag-group-remove", "class" => css(:remove),
+            # labelledby chains button -> row: "Remove, <tag name>".
+            "aria-label" => t("poetry.tag_group.remove"),
+            "aria-labelledby" => "#{button_id} #{row_id}"
+          }
+          attrs["disabled"] = "" if disabled
+
+          content_tag(:button, attrs.merge(stimulus_attributes_for(:remove))) do
+            render(Icon::Component.new(name: :x))
+          end
+        end
+
+        def hidden_input(value)
+          tag.input(type: "hidden", name: "#{name}[]", value: value)
+        end
+
+        private :instance_id, :label_id, :root_attributes, :grid_attributes, :tag_row
+      end
+    end
+  end
+end

data/app/components/poetry/ui/tag_group/preview.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module TagGroup
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(label: "Topics") do |group|
+            group.with_tag(value: "rails") { "Rails" }
+            group.with_tag(value: "hotwire") { "Hotwire" }
+            group.with_tag(value: "ruby") { "Ruby" }
+          end
+        end
+
+        # Form mode: one hidden topics[] input per tag submits; removing a
+        # tag removes its input.
+        def as_form_value
+          render_component(name: "post[topics]", label: "Topics") do |group|
+            group.with_tag(value: "news") { "News" }
+            group.with_tag(value: "release") { "Release" }
+          end
+        end
+
+        def with_disabled
+          render_component(label: "Filters") do |group|
+            group.with_tag(value: "status") { "Status: open" }
+            group.with_tag(value: "locked", disabled: true) { "Locked" }
+            group.with_tag(value: "assignee") { "Assignee: me" }
+          end
+        end
+
+        # removable: false - display-only chips keep grid navigation but
+        # no removal affordance.
+        def without_removal
+          render_component(label: "Capabilities") do |group|
+            group.with_tag(value: "read", removable: false) { "Read" }
+            group.with_tag(value: "write", removable: false) { "Write" }
+          end
+        end
+      end
+    end
+  end
+end

data/app/components/poetry/ui/tag_group/style.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module TagGroup
+      # Utility-only (the Separator/Spinner rule): chips wear the secondary
+      # badge treatment in structural utilities on semantic tokens - no
+      # upstream cn hook exists for a tag group; data-slot selectors are
+      # the restyle seam. The grid carries a focus ring for its empty-state
+      # tab-stop role.
+      class Style < Poetry::Core::Style
+        base "flex w-fit flex-col gap-1.5"
+
+        element :label, "text-sm font-medium"
+        element :grid, "flex flex-wrap items-center gap-1.5 rounded-md outline-none " \
+                       "focus-visible:ring-[3px] focus-visible:ring-ring/50"
+        element :tag, "inline-flex items-center gap-1 rounded-md border border-transparent " \
+                      "bg-secondary px-2 py-0.5 text-xs font-medium text-secondary-foreground " \
+                      "outline-none focus-visible:border-ring focus-visible:ring-[3px] " \
+                      "focus-visible:ring-ring/50 " \
+                      "data-disabled:pointer-events-none data-disabled:opacity-50"
+        element :cell, "contents"
+        element :remove, "-mr-0.5 inline-flex size-3.5 items-center justify-center rounded-sm " \
+                         "opacity-60 outline-none hover:opacity-100 " \
+                         "focus-visible:ring-2 focus-visible:ring-ring/50 [&_svg]:size-3"
+      end
+    end
+  end
+end

data/app/components/poetry/ui/textarea/component.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Multiline free-text inputs.
+    module Textarea
+      # A multiline free-text input: the native <textarea> with the
+      # library's styling and zero JS. It auto-grows with its content via
+      # CSS (the field-sizing-content property); browsers without support
+      # keep the rows:/minimum-height sizing plus the native resize
+      # handle. Label pairing, description wiring, and error state flow
+      # in from the Field/FormBuilder layer - use Input for single-line
+      # text.
+      #
+      # @example A free-text field
+      #   render Poetry::Ui::Textarea::Component.new(name: "bio", rows: 4,
+      #                                              placeholder: "Tell us about yourself")
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Wire through Field/FormBuilder (control_attributes) - never hand-write the aria plumbing.",
+          "Placeholder is NOT a label - pair with Label/Field always.",
+          "Use Textarea for free text; Input for single-line; do not bolt a JS autosizer on " \
+          "(auto-grow is CSS).",
+          "Do not set native required - required flows as aria-required via Field."
+        ].freeze
+
+        option :name, :string, doc: "The submitted field name."
+        option :value, :string, doc: "The initial text, rendered as the element's content."
+        option :placeholder, :string, doc: "Hint text shown while empty - never a substitute for a label."
+        option :rows, :integer,
+               doc: "The initial visual rows - the minimum height under CSS auto-grow, and the fixed size in " \
+                    "browsers without it."
+        option :disabled, :boolean, default: false, doc: "Disables the control and forwards to the native element."
+        option :invalid, :boolean, default: false,
+                                   doc: "Marks the field errored (aria-invalid + the destructive ring); set by " \
+                                        "Field/FormBuilder from model errors."
+
+        part "textarea", "The <textarea> element itself - value renders as content; " \
+                         "auto-grow is the field-sizing-content CSS property, zero JS"
+
+        # @api private
+        def call
+          # value as CONTENT (escaped by content_tag - the </textarea>
+          # injection surface).
+          content_tag(:textarea, value, **root_attributes.to_attributes)
+        end
+
+        # @api private
+        def root_attributes
+          attrs = { "data-slot" => "textarea" }.merge(component_data_attributes)
+          attrs["name"] = name if name.present?
+          attrs["placeholder"] = placeholder if placeholder.present?
+          attrs["rows"] = rows if rows.present?
+          attrs["disabled"] = true if disabled
+          attrs["aria-invalid"] = true if invalid
+          html_attributes.merge_if_not_set(attrs)
+        end
+
+        private :root_attributes
+      end
+    end
+  end
+end

data/app/components/poetry/ui/textarea/preview.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Textarea
+      # The Textarea preview matrix: the five ported examples (demo,
+      # disabled, with-label, with-text, with-button) plus the invalid
+      # state and long auto-grown content.
+      class Preview < Poetry::Core::Preview::Base
+        # @!group States
+
+        def default
+          render_component(placeholder: "Type your message here.")
+        end
+
+        def disabled
+          render_component(placeholder: "Type your message here.", disabled: true)
+        end
+
+        def invalid
+          render_component(placeholder: "Type your message here.", invalid: true,
+                           value: "too short")
+        end
+
+        # field-sizing-content auto-grows with the content (Chromium);
+        # elsewhere: min-h-16 + the native resize handle.
+        def auto_grown
+          render_component("aria-label": "Notes", value: "Paragraph one.\n\nParagraph two keeps pushing the height - " \
+                                                         "no JS autosizer, the CSS does it.\n\nParagraph three.")
+        end
+
+        def taller_start
+          render_component(rows: 8, placeholder: "Starts eight rows tall.")
+        end
+
+        # @!endgroup
+
+        # @!group Recipes
+
+        # textarea-with-label parity (Label pairs by for=).
+        def with_label
+          render_component(Field::Component.new(id: "preview-message", label_text: "Your message")) do
+            embed(Component.new(name: "message", placeholder: "Type your message here.",
+                                id: "preview-message"))
+          end
+        end
+
+        # textarea-with-text parity: the hint wires via describedby.
+        def with_hint
+          field = Field::Component.new(
+            id: "preview-bio", label_text: "Bio",
+            hint: "Your message will be copied to the support team."
+          )
+          render_component(field) do
+            embed(Component.new(name: "bio", placeholder: "Tell us about yourself",
+                                **field.control_attributes.transform_keys(&:to_sym)))
+          end
+        end
+
+        # Model-error rendering: aria-invalid + error-before-hint.
+        def with_error
+          field = Field::Component.new(
+            id: "preview-report", label_text: "Report",
+            hint: "Markdown is supported.", error: "can't be blank", required: true
+          )
+          render_component(field) do
+            embed(Component.new(name: "report", **field.control_attributes.transform_keys(&:to_sym)))
+          end
+        end
+
+        # @!endgroup
+      end
+    end
+  end
+end

data/app/components/poetry/ui/textarea/style.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Textarea
+      # Re-expressed through the cn-* theme layer. The one behavioral
+      # novelty stays inline: field-sizing-content is CSS-only auto-grow
+      # (Chromium-first; other engines fall back to min-h-16 + the native
+      # resize handle - graceful, no polyfill, no JS autosizer ever).
+      # Placeholder color rides the theme (the rhea AA hold - see
+      # the Input dictionary note).
+      class Style < Poetry::Core::Style
+        base "cn-textarea flex field-sizing-content min-h-16 w-full outline-none " \
+             "disabled:cursor-not-allowed disabled:opacity-50"
+      end
+    end
+  end
+end

data/app/components/poetry/ui/time_field/component.html.erb

@@ -0,0 +1,6 @@
+<%# DateField's template verbatim: native input visible (and THE form
+    value) until the controller builds segments into the group. %>
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= content_tag(:span, "", **Poetry::Core::HTML::Attributes.new(group_attributes).to_attributes) %>
+  <%= tag.input(**input_attributes.to_attributes) %>
+<% end %>

data/app/components/poetry/ui/time_field/component.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Segmented time-of-day editors.
+    module TimeField
+      # A segmented time editor: hour, minute, and - with seconds: -
+      # second segments, each typed or stepped independently. The form
+      # value is a native <input type=time> submitting HH:MM[:SS], and
+      # without JS that native input simply renders, so the field always
+      # works. The user's locale decides 12- vs 24-hour editing (an
+      # AM/PM segment appears exactly when the locale is twelve-hour);
+      # hour_cycle: pins it explicitly.
+      #
+      # A TimeField is a DateField specialized to time-of-day - segments
+      # share the date-field-* part vocabulary.
+      #
+      # @example
+      #   render Poetry::Ui::TimeField::Component.new(
+      #     name: "starts_at", label: "Start time", value: "09:30"
+      #   )
+      class Component < DateField::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Time entry is a TimeField (poetry_time_field / form.time_field) - never a masked " \
+          "Input or a pair of selects; params[<name>] is HH:MM (HH:MM:SS with seconds:).",
+          "12- vs 24-hour follows the user's locale automatically (the dayPeriod segment " \
+          "appears only under twelve-hour cycles); hour_cycle: pins it when a product must.",
+          "For a date AND a time, compose a DateField and a TimeField side by side - there " \
+          "is no datetime component by design."
+        ].freeze
+
+        # EXTENDS DateField's root declaration (extend: true merges into
+        # the inherited element) - same date-field controller, two more
+        # values; group/input inherit untouched.
+        use_stimulus do
+          on :root, extend: true do
+            controller :date_field do
+              value :seconds, true, if: :seconds
+              value :hour_cycle, if: -> { hour_cycle.present? }
+            end
+          end
+        end
+
+        option :seconds, :boolean, default: false, doc: "Adds the seconds segment; the wire format becomes HH:MM:SS."
+        option :hour_cycle, :string, doc: "Pins the hour cycle (h12/h23/h11/h24) instead of the locale's."
+
+        part "time-field", "Root - the controller and the enhanced/disabled surface ride " \
+                           "here (segments inside share the date-field-* vocabulary)",
+             states: {
+               "data-enhanced" => "the controller connected and built segments (no JS = the " \
+                                  "native input, visible and styled)",
+               "data-disabled" => "disabled: is set",
+               "data-invalid" => "invalid: is set (the group wears the destructive ring)"
+             }
+        part "time-field-group", "The bordered segment row - hidden until enhancement, then " \
+                                 "the editing surface (cn-input chrome, focus-within ring)",
+             states: {
+               "data-disabled" => "disabled: is set (chrome dims, pointer events off)",
+               "data-invalid" => "invalid: is set (destructive border + ring)"
+             }
+        part "time-field-input", "The native <input type=time> - THE form value in both " \
+                                 "modes; tabindex -1 + aria-hidden once segments exist"
+
+        private
+
+        def input_type
+          "time"
+        end
+
+        def slot_prefix
+          "time-field"
+        end
+
+        def iso(candidate)
+          candidate.respond_to?(:strftime) ? candidate.strftime("%H:%M#{":%S" if seconds}") : candidate.to_s
+        end
+
+        def placeholder_iso
+          placeholder_value.present? ? iso(placeholder_value) : "12:00#{":00" if seconds}"
+        end
+      end
+    end
+  end
+end

data/app/components/poetry/ui/time_field/preview.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module TimeField
+      # The TimeField preview: empty and valued fields, seconds, a pinned
+      # 24-hour cycle, disabled, and a pinned locale.
+      class Preview < Poetry::Core::Preview::Base
+        # Empty: hour/minute placeholders (plus AM/PM under twelve-hour
+        # locales) once enhanced; the styled native input before that.
+        def default
+          render_component(name: "meeting[at]", label: "Start time")
+        end
+
+        def with_value
+          render_component(name: "meeting[at]", value: "13:05", label: "Start time")
+        end
+
+        def with_seconds
+          render_component(name: "job[cutoff]", value: "09:30:15", seconds: true, label: "Cutoff")
+        end
+
+        # A pinned 24-hour cycle regardless of the page locale.
+        def twenty_four_hour
+          render_component(name: "shift[start]", value: "21:15", hour_cycle: "h23", label: "Shift start")
+        end
+
+        def disabled
+          render_component(name: "meeting[at]", value: "13:05", disabled: true, label: "Start time")
+        end
+
+        # locale: pins the cycle AND the dayPeriod/label language instead
+        # of following the page locale.
+        def localized
+          render_component(name: "termin[um]", value: "14:30", locale: "de-DE", label: "Uhrzeit")
+        end
+      end
+    end
+  end
+end

data/app/components/poetry/ui/time_field/style.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module TimeField
+      # DateField's style verbatim (one segment engine, two components) -
+      # including the group/date-field marker name, which the enhanced-
+      # input selector keys on. See date_field/style.rb for the rationale.
+      class Style < Poetry::Core::Style
+        base "group/date-field flex w-full flex-col"
+
+        element :group,
+                "cn-input hidden w-fit min-w-0 select-none items-center tabular-nums " \
+                "group-data-[enhanced]/date-field:flex " \
+                "focus-within:border-ring focus-within:ring-[3px] focus-within:ring-ring/50 " \
+                "data-invalid:border-destructive data-invalid:ring-destructive/20 " \
+                "dark:data-invalid:ring-destructive/40 " \
+                "data-disabled:pointer-events-none data-disabled:opacity-50 " \
+                "[&_[data-slot=date-field-segment]]:rounded-sm " \
+                "[&_[data-slot=date-field-segment]]:px-0.5 " \
+                "[&_[data-slot=date-field-segment]]:outline-none " \
+                "[&_[data-slot=date-field-segment]:focus]:bg-accent " \
+                "[&_[data-slot=date-field-segment]:focus]:text-accent-foreground " \
+                "[&_[data-slot=date-field-segment][data-placeholder]]:text-muted-foreground " \
+                "[&_[data-slot=date-field-literal]]:text-muted-foreground"
+        element :input, "group-data-[enhanced]/date-field:sr-only"
+      end
+    end
+  end
+end