poetry-ui 0.0.2

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

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Carousel family: the scroll-snap slide strip and its paging controls.
+    module Carousel
+      # A slide carousel on native scroll-snap: the viewport is a real
+      # scroll container, so touch, momentum, and snapping work with no
+      # JS, and prev/next paging plus arrow keys are layered on top.
+      # Declare slides with with_item; the component owns the region and
+      # slide ARIA and renders the controls.
+      #
+      # Looping, autoplay, and plugins are not supported.
+      #
+      # @example
+      #   render Poetry::Ui::Carousel::Component.new(label: "Featured") do |carousel|
+      #     carousel.with_item { "Slide one" }
+      #     carousel.with_item { "Slide two" }
+      #   end
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the orientation axis.
+        ORIENTATIONS = %i[horizontal vertical].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "label: is REQUIRED - the carousel region's accessible name.",
+          "Declare slides with with_item - the component stamps the slide roles " \
+          "(role=group + aria-roledescription=slide).",
+          "Slides are REAL scroll content: they stay reachable by swipe, wheel, and keyboard even " \
+          "before JS - never gate content behind the buttons alone.",
+          "Size slides with item classes (basis-full default; basis-1/2 lg:basis-1/3 for a gallery).",
+          "Change slide spacing as a TRIO: track_classes: \"-ml-1\" plus item classes " \
+          "\"pl-1 -scroll-ml-1\" - the gutter padding and its snap scroll-margin move together."
+        ].freeze
+
+        # States statically that with_item requires a content block, so
+        # static checks can flag the omission without rendering.
+        SLOT_REQUIRED_CONTENT = { item: "the slide" }.freeze
+
+        # The required slots, stated statically so static checks can flag
+        # a missing slide without rendering.
+        REQUIRED_SLOTS = { item: "at least one slide" }.freeze
+
+        renders_many :items,
+                     doc: "Declares one slide. The content block is required; classes: sizes the slide (basis-full " \
+                          "default).",
+                     renders: lambda { |classes: nil, &block|
+                       raise ArgumentError, "Carousel with_item requires a content block (the slide)" unless block
+
+                       slides << Slide.new(classes: classes, block: block)
+                       nil
+                     }
+
+        use_stimulus do
+          on :root do
+            controller :carousel do
+              register
+              value :orientation
+              action :keydown, on: :keydown
+            end
+          end
+          on :viewport do
+            controller :carousel do
+              target :viewport
+              action :scrolled, on: :scroll
+            end
+          end
+          # One element per control direction, forwarded into Button
+          # kwargs (previously hand-written target + action strings).
+          on :previous do
+            controller :carousel do
+              target :previous
+              action :previous, on: :click
+            end
+          end
+          on :next do
+            controller :carousel do
+              target :next
+              action :next, on: :click
+            end
+          end
+        end
+
+        option :label, :string, required: true,
+                                doc: "The carousel region's accessible name - required; rendering without it raises."
+        option :orientation, :symbol, default: :horizontal,
+                                      doc: "The scroll axis; snapping, controls, and arrow keys follow it."
+        option :show_controls, :boolean, default: true,
+                                         doc: "Renders the prev/next buttons; slides stay reachable by swipe, wheel, " \
+                                              "and keyboard without them."
+        option :track_classes, :string,
+               doc: "Utility classes for the slide track - change spacing as a trio: track_classes: \"-ml-1\" pairs " \
+                    "with item classes \"pl-1 -scroll-ml-1\"."
+
+        validates :orientation, inclusion: { in: ORIENTATIONS }
+
+        part "carousel", "The role=region root - the controller (paging, button state, arrow keys) " \
+                         "rides here",
+             states: {
+               "data-orientation" => { condition: "the scroll axis", values: ORIENTATIONS.map(&:to_s) }
+             }
+        part "carousel-content", "The viewport - a real scroll-snap container (tabindex=0); the " \
+                                 "platform owns the physics"
+        part "carousel-item", "One role=group slide - sized by item classes (basis-full default)"
+
+        # Enforces the required label and at least one slide.
+        # @api private
+        def before_render
+          raise ArgumentError, "Carousel requires label: (the region's accessible name)" if label.blank?
+          raise ArgumentError, "Carousel requires at least one with_item" unless items?
+        end
+
+        # The declared slides in render order.
+        # @api private
+        def slides
+          @slides ||= []
+        end
+
+        # Whether the scroll axis is vertical.
+        # @api private
+        def vertical? = orientation == :vertical
+
+        # Attributes for the role=region root.
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "role" => "region", "aria-roledescription" => "carousel", "aria-label" => label,
+              "data-slot" => "carousel", "data-orientation" => orientation
+            }.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        # Attributes for the scroll-snap viewport.
+        # @api private
+        def viewport_attributes
+          {
+            "data-slot" => "carousel-content",
+            # A REAL scroll region must be keyboard-reachable (the ScrollArea
+            # rule); the arrows then page it via the root's keydown.
+            "tabindex" => "0",
+            "class" => "#{css(:content)} #{css(vertical? ? :content_vertical : :content_horizontal)}"
+          }.merge(stimulus_attributes_for(:viewport))
+        end
+
+        # Attributes for one slide.
+        # @api private
+        def item_attributes(slide)
+          # class: rides the merger so caller classes WIN on conflicts -
+          # a raw join left basis-1/3 vs the dictionary's basis-full to
+          # the compiled sheet's cascade order (which picked basis-full,
+          # silently breaking the documented strip sizing).
+          {
+            "role" => "group", "aria-roledescription" => "slide", "data-slot" => "carousel-item",
+            "class" => css(:item, class: [css(vertical? ? :item_vertical : :item_horizontal),
+                                          slide.classes].compact)
+          }
+        end
+
+        # Button options for one prev/next control.
+        # @api private
+        def control_options(direction)
+          {
+            variant: :outline, size: :"icon-sm",
+            label: direction == :previous ? "Previous slide" : "Next slide",
+            class: "cn-carousel-#{direction} #{css(:control)} #{css(:"control_#{direction}_#{orientation}")}",
+            data: { slot: "carousel-#{direction == :previous ? "previous" : "next"}" }
+          }.merge(stimulus_attributes_for(direction))
+        end
+
+        # One declared slide: its extra classes and content block.
+        # @api private
+        Slide = Data.define(:classes, :block)
+
+        private :slides, :vertical?, :root_attributes, :viewport_attributes, :item_attributes, :control_options
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Carousel
+      # The Carousel preview: full-width slides, a responsive gallery, the
+      # spacing trio, and the vertical stack. The -left-12/-right-12
+      # controls need gutter room (px-14).
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_component(label: "Featured artwork", class: "mx-14 w-64") do |carousel|
+            3.times do |n|
+              carousel.with_item do
+                tag.div("Slide #{n + 1}",
+                        class: "flex aspect-square items-center justify-center rounded-md border bg-muted text-2xl")
+              end
+            end
+          end
+        end
+
+        # The Sizes gallery (absorbs the old strip preview): responsive
+        # per-item bases, mirroring the docs example - the golden pins the
+        # rig-width rendering.
+        def sizes
+          render_component(label: "Gallery sizes", class: "mx-14 w-96") do |carousel|
+            5.times do |n|
+              carousel.with_item(classes: "basis-1/2 lg:basis-1/3") do
+                tag.div((n + 1).to_s,
+                        class: "flex aspect-square items-center justify-center rounded-md border bg-muted text-2xl")
+              end
+            end
+          end
+        end
+
+        # The spacing trio (track_classes + per-item pl/-scroll-ml): the
+        # track margin, the gutter padding, and the snap scroll-margin
+        # move together - this preview pins the tightened geometry.
+        def spacing
+          render_component(label: "Tight gallery", track_classes: "-ml-1", class: "mx-14 w-80") do |carousel|
+            5.times do |n|
+              carousel.with_item(classes: "basis-1/3 pl-1 -scroll-ml-1") do
+                tag.div((n + 1).to_s,
+                        class: "flex aspect-square items-center justify-center rounded-md border bg-muted text-xl")
+              end
+            end
+          end
+        end
+
+        # Vertical stack, upstream's orientation proportions: fixed-height
+        # slides (the auto-height track cannot resolve percentage bases),
+        # two visible, enough roster to page. The -top-12/-bottom-12
+        # controls need gutter room (my-14).
+        def vertical
+          render_component(label: "Release milestones", orientation: :vertical,
+                           class: "mx-auto my-14 grid h-64 w-52") do |carousel|
+            6.times do |n|
+              carousel.with_item do
+                tag.div("Week #{n + 1}",
+                        class: "flex h-28 items-center justify-center rounded-md border bg-muted text-sm font-semibold")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Carousel
+      # Style dictionary for the Carousel family, on native scroll-snap:
+      # the content wrapper is the REAL scroll container
+      # (overflow + snap + hidden scrollbar) rather than an
+      # overflow-hidden + transform track; the gutter idiom (-ml-4 track,
+      # pl-4 items) and the control positions are kept as designed.
+      class Style < Poetry::Core::Style
+        base "relative"
+
+        element :content, "overflow-auto [scrollbar-width:none] snap-mandatory"
+        element :content_horizontal, "snap-x"
+        element :content_vertical, "snap-y"
+
+        element :track, "flex"
+        element :track_horizontal, "-ml-4"
+        element :track_vertical, "-mt-4 flex-col"
+
+        element :item, "min-w-0 shrink-0 grow-0 basis-full snap-start"
+        # The negative scroll-margin cancels the gutter from the snap area:
+        # native snap-start (and scrollIntoView) aligns the item's BORDER
+        # box, which includes the pl-4 gutter - without it, every slide
+        # after the first snaps 16px short and its trailing edge clips.
+        # An engine that translates by measured offsets never has this seam.
+        element :item_horizontal, "pl-4 -scroll-ml-4"
+        element :item_vertical, "pt-4 -scroll-mt-4"
+
+        element :control, "absolute touch-manipulation"
+        element :control_previous_horizontal, "inset-y-0 -left-12 my-auto"
+        element :control_previous_vertical, "-top-12 left-1/2 -translate-x-1/2 rotate-90"
+        element :control_next_horizontal, "inset-y-0 -right-12 my-auto"
+        element :control_next_vertical, "-bottom-12 left-1/2 -translate-x-1/2 rotate-90"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+<%# Fragment - button + input(s) as SIBLINGS, no wrapper: the source's
+    `peer` class contract (labels style via peer-*) breaks if poetry wraps.
+    The controller lives on the button; the input resolves by stable id. %>
+<%= content_tag(:button, **root_attributes.to_attributes) do %>
+  <span data-slot="checkbox-indicator" <% if indeterminate? %>data-indeterminate=""<% elsif checked? %>data-checked=""<% else %>data-unchecked=""<% end %> aria-hidden="true" class="<%= css(:indicator) %>">
+    <%# MinusIcon on indeterminate is a POETRY ADDITION (shadcn renders a
+        check for mixed state - a real gap). %>
+    <%= render Poetry::Ui::Icon::Component.new(name: indeterminate? ? :minus : :check, class: css(:icon)) %>
+  </span>
+<% end %>
+<% if form_participant? %>
+  <%# Rails parity hidden FIRST (last-wins ordering, Tags::CheckBox-exact)
+      so unchecked SUBMITS unchecked_value; disabled fields submit nothing. %>
+  <% if unchecked_value %>
+    <%= tag.input(type: "hidden", name: name, value: unchecked_value, disabled: disabled) %>
+  <% end %>
+  <%# THE form participant + the store: input.indeterminate is a JS-only
+      property - the controller derives it from the checked attributes on connect. %>
+  <%= tag.input(type: "checkbox", id: input_id, name: name, value: value, checked: checked?,
+                disabled: disabled, "data-slot": "checkbox-input", "aria-hidden": true,
+                tabindex: "-1", class: css(:input)) %>
+<% end %>

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

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # Checkbox family: the form-participating tri-state toggle.
+    module Checkbox
+      # A checkbox. A hidden native <input type=checkbox> is the form
+      # participant and the source of truth (server-rendered
+      # name/value/checked, Rails "1"/"0" plus the unchecked-hidden
+      # pair), while the visual button[role=checkbox] only reflects it
+      # via aria-checked and the data-checked / data-unchecked /
+      # data-indeterminate triple. Toggling flips the input and lets the
+      # real change event bubble; a native form reset re-syncs the
+      # visual state from the input. checked: is tri-valued - true,
+      # false, or :indeterminate (for select-all parents).
+      #
+      # The button and inputs render as siblings with no wrapper
+      # element, so peer-* label styling keyed on the `peer` class works.
+      #
+      # @example A form checkbox
+      #   render Poetry::Ui::Checkbox::Component.new(name: "terms", label: "Accept terms")
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the checked: axis.
+        STATES = [true, false, :indeterminate].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "A select-all run rides poetry_checkbox_group (wrapper) + poetry_checkbox_group_all " \
+          "(the mixed-state parent) + poetry_checkbox_group_item per member - toggles fan out " \
+          "and re-derive automatically.",
+          "Use poetry_checkbox (or f.check_box) - never a raw input[type=checkbox] with hand-written " \
+          "Tailwind, and never a hand-rolled button[role=checkbox].",
+          "Always give it a name: in forms - a checkbox without one submits nothing (visual-only mode " \
+          "is for controlled UI like DataTable row selection ONLY).",
+          "Every checkbox needs an accessible name: a Label/Field for= association (preferred) or label:.",
+          "Indeterminate is set programmatically/server-side only - no user gesture produces it; use it " \
+          "for select-all parents.",
+          "Select-all recipe: wrap parent + rows in data-controller=\"poetry--core--checkbox-group\" with " \
+          "data-action=\"poetry:checkbox:change->poetry--core--checkbox-group#changed\"; mark the parent " \
+          "box data: {\"poetry--core--checkbox-group-target\": \"all\"} and each row box target \"item\" - " \
+          "the parent fans out, rows re-derive checked/unchecked/indeterminate (DataTable's selectable: " \
+          "already does this for its own rows).",
+          "Instant-effect settings use Switch; pressed UI tools use Toggle; one-of-N uses RadioGroup.",
+          "NEVER write the checked attributes (data-checked/data-unchecked/data-indeterminate) without " \
+          "aria-checked and the input's checked property (the controller writes all three; agents " \
+          "patching DOM must too).",
+          "Don't suppress unchecked_value unless using the array idiom - an unchecked box that submits " \
+          "nothing silently keeps the old server value."
+        ].freeze
+
+        use_stimulus do
+          on :root do
+            controller :checked do
+              register
+              # No input-id value -> pure visual mode: state lives on the
+              # button's checked attributes alone (discouraged; see AGENT_RULES).
+              value :input_id, if: :form_participant?
+              action :toggle, on: :click
+            end
+          end
+        end
+
+        # The tri-valued checked: type - casts to exactly
+        # true | false | :indeterminate, so one option carries the whole
+        # state with no separate indeterminate: flag.
+        #
+        # @api private
+        class CheckedState < ActiveModel::Type::Value
+          def type
+            :checked_state
+          end
+
+          def cast(value)
+            return :indeterminate if value.to_s == "indeterminate"
+
+            ActiveModel::Type::Boolean.new.cast(value) || false
+          end
+        end
+
+        option :checked, CheckedState.new, default: false,
+                                           doc: "The state as ONE tri-valued option (true, false, or :indeterminate) " \
+                                                "- there is no separate indeterminate: flag."
+        option :name, :string,
+               doc: "Form participation: present renders the hidden native input pair; absent leaves the checkbox " \
+                    "visual-only (controlled UI)."
+        option :value, :string, default: "1", doc: "The value submitted when checked (the Rails check_box \"1\")."
+        option :unchecked_value, :string, default: "0",
+                                          doc: "The paired hidden input's value submitted when unchecked; nil " \
+                                               "suppresses the pair (the checkbox-array idiom)."
+        option :disabled, :boolean, default: false, doc: "Disables the visual button and the hidden input together."
+        option :required, :boolean, default: false,
+                                    doc: "aria-required ONLY, never native required - native required on the hidden " \
+                                         "input would make an unfocusable control invalid."
+        option :label, :string, doc: "aria-label fallback when no <label for>/Field association exists."
+
+        part "checkbox", "The visual button[role=checkbox] - reflects the hidden input via " \
+                         "aria-checked plus the checked triple",
+             states: {
+               "data-checked" => "checked (the controller reflects every toggle here, " \
+                                 "aria-checked in step)",
+               "data-unchecked" => "unchecked - the indicator goes invisible",
+               "data-indeterminate" => "checked: :indeterminate (server/programmatic only; " \
+                                       "the first toggle resolves it to checked)"
+             }
+        part "checkbox-indicator", "Centering span around the check glyph (minus when " \
+                                   "indeterminate) - CSS-hidden while unchecked, never unmounted",
+             states: {
+               "data-checked" => "mirrors the control (the controller reflects state on " \
+                                 "every part wearing the triple)",
+               "data-unchecked" => "mirrors the control - the indicator is invisible",
+               "data-indeterminate" => "mirrors the control - the glyph swaps to minus"
+             }
+
+        # Whether checked: is :indeterminate.
+        # @api private
+        def indeterminate?
+          checked == :indeterminate
+        end
+
+        # Whether checked: is exactly true.
+        # @api private
+        def checked?
+          checked == true
+        end
+
+        # The state word behind the data-* stamp.
+        # @api private
+        def state
+          return "indeterminate" if indeterminate?
+
+          checked? ? "checked" : "unchecked"
+        end
+
+        # The aria-checked value ("mixed" for indeterminate).
+        # @api private
+        def aria_checked
+          indeterminate? ? "mixed" : checked?.to_s
+        end
+
+        # The label-for target (Field-issued or auto) - server-stable so the
+        # sibling input resolves structurally by id, wrapper-free.
+        # @api private
+        def control_id
+          @control_id ||= poetry_instance_id("poetry-checkbox")
+        end
+
+        # The hidden input's id, derived from the control's.
+        # @api private
+        def input_id
+          "#{control_id}-input"
+        end
+
+        # Whether the hidden input pair renders (name: present).
+        # @api private
+        def form_participant?
+          name.present?
+        end
+
+        # Attributes for the visual button[role=checkbox].
+        # @api private
+        def root_attributes
+          attrs = {
+            "type" => "button", "role" => "checkbox", "id" => control_id,
+            "aria-checked" => aria_checked, "data-#{state}" => "",
+            "data-slot" => "checkbox", "disabled" => disabled
+          }
+          attrs["aria-required"] = true if required
+          attrs["aria-label"] = label if label.present?
+          html_attributes.merge_if_not_set(
+            attrs.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        private :indeterminate?, :checked?, :state, :aria_checked, :control_id, :input_id, :form_participant?
+        private :root_attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Checkbox
+      # The Checkbox preview matrix: all three check-states x disabled x
+      # invalid, the Field-bound recipe, and the disabled+checked footgun
+      # (disabled fields don't submit - a checked box that submits nothing).
+      class Preview < Poetry::Core::Preview::Base
+        # @!group States
+
+        def default
+          render_component(name: "terms", label: "Accept terms and conditions")
+        end
+
+        def checked
+          render_component(name: "terms", checked: true, label: "Accept terms and conditions")
+        end
+
+        # Server/programmatic only - the select-all parent over a partial
+        # selection. Announces as "mixed"; the first toggle resolves to
+        # checked (source-exact).
+        def indeterminate
+          render_component(name: "select_all", checked: :indeterminate, label: "Select all rows")
+        end
+
+        def disabled
+          render_component(name: "terms", disabled: true, label: "Accept terms and conditions")
+        end
+
+        # The footgun preview: disabled inputs DON'T submit - a disabled
+        # checked checkbox submits nothing, not "1".
+        def disabled_checked
+          render_component(name: "terms", checked: true, disabled: true, label: "Locked on (submits nothing)")
+        end
+
+        def invalid
+          render_component(name: "terms", label: "Accept terms and conditions", "aria-invalid": true)
+        end
+
+        # @!endgroup
+
+        # @!group Recipes
+
+        # Field-bound: control_attributes land the id (the label-for
+        # target), aria-describedby, and aria-required on the BUTTON.
+        def in_a_field
+          field = Field::Component.new(
+            id: "preview-newsletter", label_text: "Email newsletter",
+            hint: "Sent weekly. Unsubscribe anytime.", required: true
+          )
+          render_component(field) do
+            embed(Component.new(name: "newsletter", checked: true,
+                                **field.control_attributes.transform_keys(&:to_sym)))
+          end
+        end
+
+        # Visual-only mode (no name:) - controlled UI like DataTable row
+        # selection; state lives on the checked attributes alone (discouraged in forms).
+        def visual_only
+          render_component(checked: true, label: "Row selected")
+        end
+
+        # @!endgroup
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Checkbox
+      # Re-expressed through the cn-* theme layer: the well treatment
+      # rides .cn-checkbox in themes/default.css. Poetry mechanisms stay
+      # inline: data-unchecked:invisible keeps the indicator in the DOM
+      # CSS-hidden (nothing unmounts; there is no exit animation to
+      # await), the glyph keeps its designed size-3.5, and :input is the
+      # sr-only form store.
+      class Style < Poetry::Core::Style
+        base "cn-checkbox peer relative shrink-0 outline-none after:absolute " \
+             "after:-inset-x-3 after:-inset-y-2 " \
+             "disabled:cursor-not-allowed disabled:opacity-50"
+
+        element :indicator, "cn-checkbox-indicator grid place-content-center text-current transition-none " \
+                            "data-unchecked:invisible"
+
+        element :icon, ""
+
+        # The form participant + the store: visually hidden, out of the
+        # accessibility tree (the button is the accessible control).
+        element :input, "sr-only"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+<%# InputGroup anatomy: the readonly mono control, trailing copy
+    affordance with stacked copy/check glyphs swapping on data-copied. %>
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= content_tag(:div, **Poetry::Core::HTML::Attributes.new(group_attributes).to_attributes) do %>
+    <%= tag.input(**input_attributes.to_attributes) %>
+    <%= content_tag(:div, **Poetry::Core::HTML::Attributes.new(addon_attributes).to_attributes) do %>
+      <%= render copy_button do %>
+        <span class="<%= css(:icon_stack) %>">
+          <%= render Poetry::Ui::Icon::Component.new(name: :copy, class: css(:icon_copy)) %>
+          <%= render Poetry::Ui::Icon::Component.new(name: :check, class: css(:icon_check)) %>
+        </span>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>