poetry-ui 0.0.2

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

@@ -0,0 +1,21 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= trigger %>
+  <%= content_tag(:dialog, **Poetry::Core::HTML::Attributes.new(dialog_attributes).to_attributes) do %>
+    <div data-slot="sheet-header" class="<%= css(:header) %>">
+      <h2 id="<%= title_id %>" data-slot="sheet-title" class="<%= css(:title) %>"><%= title %></h2>
+      <% if description? %>
+        <p id="<%= description_id %>" data-slot="sheet-description" class="<%= css(:description) %>"><%= description %></p>
+      <% end %>
+    </div>
+    <%= content %>
+    <% if footer? %><div data-slot="sheet-footer" class="<%= css(:footer) %>"><%= footer %></div><% end %>
+    <% if show_close_button %>
+      <%= render Poetry::Ui::Button::Component.new(variant: :ghost, size: :"icon-sm",
+                                                   label: t("poetry.sheet.close"),
+                                                   class: css(:close),
+                                                   data: { slot: "sheet-close", action: close_action }) do %>
+        <%= render Poetry::Ui::Icon::Component.new(name: :x) %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # A modal panel that slides in from a screen edge.
+    module Sheet
+      # A modal panel that slides in from a screen edge - navigation on
+      # the left, detail/edit panels on the right, pickers on the bottom.
+      # A re-skinned Dialog, so everything hard is INHERITED: the native
+      # <dialog> + showModal() platform behavior (focus trap, Esc, top
+      # layer, focus return), the data-open/data-closed pair, backdrop
+      # dismissal, scroll lock, dismissible:, show_close_button:, and the
+      # required title. The deltas: the side style (edge-anchored margins
+      # replace the parent's centering) and the slide-in animation.
+      #
+      # @example
+      #   render Poetry::Ui::Sheet::Component.new(side: :right) do |sheet|
+      #     sheet.with_trigger { "Edit profile" }
+      #     sheet.with_title { "Edit profile" }
+      #     "Sheet body"
+      #   end
+      class Component < Dialog::Component
+        # The closed vocabulary for the side style axis.
+        SIDES = %i[top right bottom left].freeze
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Open sheets with with_trigger(...) - never a hand-wired button.",
+          "with_title is REQUIRED (the accessible name) - the inherited Dialog rule.",
+          "Pick side by content: navigation left, detail/edit right, pickers bottom.",
+          "Do not put must-not-lose confirmations in a Sheet - that is AlertDialog.",
+          "Do not rebuild a centered Dialog with a Sheet; use Dialog."
+        ].freeze
+
+        # The Sheet gets its OWN controller - the dialog machinery plus
+        # the presence-hold close (the closed slide-out finishes before
+        # the panel hides).
+        # Redeclaring both elements REPLACES Dialog's :dialog controller
+        # wholesale (replace-on-redeclare); the inherited trigger lambda and
+        # close_action late-bind here through stimulus_action.
+        use_stimulus do
+          on :root do
+            controller :sheet do
+              register
+              value :dismissible
+            end
+          end
+          on :content do
+            controller :sheet do
+              target :dialog
+              action :close, on: :cancel
+              action :backdrop_close, on: :click
+            end
+          end
+          on :trigger do
+            controller(:sheet) { action :open }
+          end
+          on :close do
+            controller(:sheet) { action :close }
+          end
+        end
+
+        style :side, default: :right, required: true, variants: SIDES,
+                     doc: "The edge the sheet slides in from - a physical direction (right stays right in RTL)."
+
+        part "sheet", "Root wrapper around the trigger and the <dialog> element"
+        part "sheet-content", "The <dialog> panel, anchored to a screen edge - the slide " \
+                              "animation and the open state ride here",
+             states: {
+               "data-open" => "panel is open (the controller flips the pair at runtime)",
+               "data-closed" => "panel is closed or animating out (the server-rendered state; " \
+                                "the presence-hold close rides the closed slide-out)",
+               "data-side" => { condition: "always - the edge the sheet slides in from",
+                                values: SIDES.map(&:to_s) }
+             }
+        part "sheet-header", "Title block at the top of the panel"
+        part "sheet-title", "The heading - the sheet's accessible name (required slot)"
+        part "sheet-description", "Muted copy under the title, wired to aria-describedby"
+        part "sheet-footer", "Action row pinned to the bottom of the panel"
+
+        private
+
+        # The Sheet deltas on the inherited panel: the side's edge classes
+        # (the resolver applies variants only at the dictionary root; the
+        # Sheet's visual root IS the :content element, so the side branch
+        # merges in here) and the data-side stamp.
+        def panel_classes
+          [Style.side(side), content_class]
+        end
+
+        def panel_stamps
+          { "data-side" => side }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Sheet
+      # The Sheet preview: one example per edge (previews render CLOSED,
+      # the trigger page - the Dialog convention).
+      class Preview < Poetry::Core::Preview::Base
+        # side: :right - the detail/edit panel default.
+        def default
+          side_example(:right)
+        end
+
+        def left
+          side_example(:left)
+        end
+
+        def top
+          side_example(:top)
+        end
+
+        def bottom
+          side_example(:bottom)
+        end
+
+        # The canonical Sheet recipe: an edit form beside the page context,
+        # footer actions pinned to the edge by mt-auto.
+        def form
+          render_component(side: :right) do |sheet|
+            sheet.with_trigger(variant: :outline) { "Edit profile" }
+            sheet.with_title { "Edit profile" }
+            sheet.with_description { "Make changes to your profile here. Click save when you're done." }
+            sheet.with_footer do
+              embed(Poetry::Ui::Button::Component.new(type: :submit).with_content("Save changes"))
+            end
+            embed(Poetry::Ui::Label::Component.new(for_id: "sheet-demo-name").with_content("Name")) +
+              embed(Poetry::Ui::Input::Component.new(name: "name", value: "Pedro Duarte", id: "sheet-demo-name"))
+          end
+        end
+
+        private
+
+        def side_example(side)
+          render_component(side: side) do |sheet|
+            sheet.with_trigger(variant: :outline) { "Open #{side} sheet" }
+            sheet.with_title { "Slide from the #{side}" }
+            sheet.with_description { "A Dialog that stays visually adjacent to the page." }
+            sheet.with_footer do
+              embed(Poetry::Ui::Button::Component.new.with_content("Apply"))
+            end
+            "Sheet body content."
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Sheet
+      # Style dictionary for the Sheet family, on the native-dialog spine.
+      # m-0 and the per-side auto margins live in the theme TOGETHER (the
+      # side margins must beat m-0, which they only can from the same
+      # layer); the UA display guard stays inline.
+      class Style < Poetry::Core::Style
+        # open:flex, NOT flex: a bare display class would defeat the UA's
+        # dialog:not([open]) { display: none }.
+        # w-full rides the theme so the sides' w-3/4 beats it in-layer.
+        # No `relative`: the top layer discards it and the UA reasserts
+        # `absolute`, which pins the sheet to the DOCUMENT edge (it scrolls
+        # off-screen when opened below the fold). The UA `:modal` rule keeps
+        # it viewport-fixed, so the side auto-margins pin it to the viewport
+        # edge as intended.
+        element :content, "cn-sheet-content open:flex flex-col"
+
+        # The side branches ride cn-sheet-side-* theme rules (margins,
+        # edge borders, sizes, slide animations). Applied to :content by
+        # the component via Style.side - the resolver renders variants only
+        # at the dictionary root, and the Sheet's root wrapper is
+        # non-visual.
+        variant :side, {
+          top: "cn-sheet-side-top",
+          right: "cn-sheet-side-right",
+          bottom: "cn-sheet-side-bottom",
+          left: "cn-sheet-side-left"
+        }
+
+        element :header, "cn-sheet-header flex flex-col"
+        element :title, "cn-sheet-title"
+        element :description, "cn-sheet-description"
+        # mt-auto pins the footer to the bottom edge.
+        element :footer, "cn-sheet-footer mt-auto flex flex-col"
+        element :close, "cn-sheet-close"
+
+        # The side's edge classes for the <dialog> element.
+        def self.side(value)
+          resolver.variants.fetch(:side).fetch(value.to_sym)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+<%= content_tag(:div, **root_attributes.to_attributes) do %>
+  <%= content_tag(:div, peer_attributes) do %>
+    <div data-slot="sidebar-gap" class="<%= gap_classes %>"></div>
+    <div data-slot="sidebar-container" data-side="<%= side %>" class="<%= container_classes %>">
+      <div data-slot="sidebar-inner" class="<%= css(:inner) %>" <%= tag.attributes(**stimulus_attributes_for(:inner)) %>><%= nav %></div>
+    </div>
+  <% end %>
+  <%# The mobile sheet (DOM-move): rendered EMPTY; the controller
+      adopts the nav children on open and returns them on close. %>
+  <%= content_tag(:dialog, **mobile_dialog_attributes) do %>
+    <div class="sr-only">
+      <h2 id="<%= mobile_title_id %>">Sidebar</h2>
+      <p>Displays the mobile sidebar.</p>
+    </div>
+    <div data-slot="sidebar-mobile-inner" class="<%= css(:mobile_inner) %>" <%= tag.attributes(**stimulus_attributes_for(:mobile_inner)) %>></div>
+  <% end %>
+  <% if inset? %>
+    <main data-slot="sidebar-inset" class="<%= css(:inset) %>"><%= inset %></main>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The app-shell frame: collapsible navigation column plus content inset.
+    module Sidebar
+      # The app-shell frame: a collapsible navigation column plus the main
+      # content inset. Reach for it as the outermost layout of an
+      # application screen. The collapse is pure CSS off data-state; the
+      # controller flips the attribute, persists the sidebar_state cookie,
+      # and binds Cmd/Ctrl+B. Server-first: pass open: from the cookie
+      # (cookies[:sidebar_state] != "false") so the first paint matches the
+      # user's last choice with no flash. Below the md breakpoint the
+      # column becomes a slide-in sheet.
+      #
+      # @example App shell wired to the persisted cookie
+      #   <%= poetry_sidebar(open: cookies[:sidebar_state] != "false", collapsible: :icon) do |shell| %>
+      #     <% shell.with_nav do %>
+      #       <%= poetry_sidebar_group do %>...menu...<% end %>
+      #     <% end %>
+      #     <% shell.with_inset do %>
+      #       <%= poetry_sidebar_trigger %>
+      #       <main>...page...</main>
+      #     <% end %>
+      #   <% end %>
+      class Component < Poetry::Core::Component
+        # The closed vocabulary for the side axis.
+        SIDES = %i[left right].freeze
+        # The closed vocabulary for the column-treatment axis.
+        VARIANTS = %i[sidebar floating inset].freeze
+        # The closed vocabulary for the collapse-mode axis.
+        COLLAPSIBLE = %i[offcanvas icon none].freeze
+
+        # The expanded column width.
+        WIDTH = "16rem"
+        # The collapsed icon-rail width.
+        WIDTH_ICON = "3rem"
+        # The mobile sheet's panel width.
+        WIDTH_MOBILE = "18rem"
+
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Wrap the WHOLE shell: with_nav is the sidebar column, with_inset is the page area " \
+          "(the trigger lives in the inset).",
+          "Read the persisted state server-side - open: cookies[:sidebar_state] != \"false\" - so the " \
+          "first paint has no collapse flash.",
+          "collapsible: :icon keeps icon rails visible when collapsed; :offcanvas slides it fully away; " \
+          ":none is a static column.",
+          "Menu entries are poetry_sidebar_menu_button(href:) links (active: marks the current route) - " \
+          "navigation navigates."
+        ].freeze
+
+        # The same facts the before_render raise enforces, stated statically
+        # so static checks can flag a missing nav without rendering.
+        REQUIRED_SLOTS = { nav: "the sidebar column" }.freeze
+
+        renders_one :nav, doc: "The sidebar column's content (required) - groups, menus, header/footer."
+        renders_one :inset, doc: "The page area beside the column - rendered as the <main> inset."
+
+        use_stimulus do
+          on :root do
+            controller :sidebar do
+              register
+              value :open
+              value :collapsible
+            end
+          end
+          on :peer do
+            controller(:sidebar) { target :sidebar }
+          end
+          on :inner do
+            controller(:sidebar) { target :inner }
+          end
+          # The mobile sheet <dialog>: the Dialog-family cancel/backdrop
+          # pair under sidebar-namespaced action names.
+          on :mobile do
+            controller :sidebar do
+              target :mobile_dialog
+              action :close_mobile, on: :cancel
+              action :mobile_backdrop_close, on: :click
+            end
+          end
+          on :mobile_inner do
+            controller(:sidebar) { target :mobile_inner }
+          end
+          # Rendered by the poetry_sidebar_trigger / poetry_sidebar_rail
+          # helpers (helper-side strings; declared here so the contract
+          # covers the whole family surface).
+          on :trigger do
+            controller(:sidebar) { action :toggle, on: :click }
+          end
+        end
+
+        option :open, :boolean, default: true,
+                                doc: "The expanded/collapsed state at first paint - feed it from the persisted " \
+                                     "cookie so there is no collapse flash."
+        option :side, :symbol, default: :left, doc: "Which edge the column hangs on."
+        option :variant, :symbol, default: :sidebar,
+                                  doc: "The column treatment: flush column, floating card, or inset panel."
+        option :collapsible, :symbol, default: :offcanvas,
+                                      doc: "What collapsing does: slide fully away, shrink to an icon rail, or :none " \
+                                           "for a static column."
+
+        validates :side, inclusion: { in: SIDES }
+        validates :variant, inclusion: { in: VARIANTS }
+        validates :collapsible, inclusion: { in: COLLAPSIBLE }
+
+        part "sidebar-wrapper", "The provider shell around the column, the mobile dialog, and the inset",
+             vars: {
+               "--sidebar-width" => "the expanded column width (16rem) - the gap/container geometry reads it",
+               "--sidebar-width-icon" => "the collapsed icon-rail width (3rem)"
+             }
+        part "sidebar", "The desktop state peer - the collapse state lives here and the pure-CSS " \
+                        "group-data chrome keys on it",
+             states: {
+               "data-state" => "expanded or collapsed - the controller flips it and persists the cookie",
+               "data-collapsible" => { condition: "the collapse mode WHILE collapsed (empty while expanded " \
+                                                  "- source parity)",
+                                       values: %w[offcanvas icon none] },
+               "data-variant" => { condition: "the column treatment", values: %w[sidebar floating inset] },
+               "data-side" => { condition: "which edge the column hangs on", values: %w[left right] }
+             }
+        part "sidebar-gap", "The in-flow width ghost that pushes the inset over - its width animates " \
+                            "on collapse"
+        part "sidebar-container", "The fixed-position column itself",
+             states: {
+               "data-side" => { condition: "which edge it pins to", values: %w[left right] }
+             }
+        part "sidebar-inner", "The flex column receiving the nav slot - the mobile mode adopts its " \
+                              "children from here"
+        part "sidebar-mobile", "The mobile sheet <dialog> (below md) - server-rendered empty; the " \
+                               "controller adopts the nav children on open",
+             states: {
+               "data-open" => "sheet is open (presence flips the pair at runtime)",
+               "data-closed" => "sheet is closed (the server-rendered state)",
+               "data-mobile" => "always \"true\" - the mobile-mode marker",
+               "data-side" => { condition: "which edge the sheet slides from", values: %w[left right] },
+               "data-sidebar" => "always \"sidebar\" - the suite-wide sub-part marker"
+             },
+             vars: {
+               "--sidebar-width" => "overridden inline to the mobile sheet width (18rem)"
+             }
+        part "sidebar-mobile-inner", "The adoption container the nav children move into while the " \
+                                     "sheet is open"
+        part "sidebar-inset", "The <main> page area beside the column"
+        part "sidebar-header", "Top block of the column (with_nav content)"
+        part "sidebar-footer", "Bottom block of the column"
+        part "sidebar-content", "The scrollable middle of the column"
+        part "sidebar-group", "One titled section inside the content"
+        part "sidebar-group-label", "The section heading - fades and collapses away in icon mode"
+        part "sidebar-menu", "The <ul> of menu items inside a group"
+        part "sidebar-menu-item", "One <li> menu row (the group/menu-item hover scope)"
+        part "sidebar-menu-button", "The row's link (href:) or button - the navigation entry itself",
+             states: {
+               "data-active" => "the current route (active: - links also get aria-current=page)",
+               "data-open" => "when the button is a collapsible's trigger - the disclosure state the " \
+                              "collapsible controller flips",
+               "data-size" => "the row size variant (default, sm, or lg) - the action/badge tops key on it",
+               "data-variant" => { condition: "always - the treatment", values: %w[default outline] }
+             }
+        part "sidebar-menu-action", "The item-corner action button, absolutely positioned in the row",
+             states: {
+               "data-sidebar" => "always \"menu-action\" - the suite-wide sub-part marker"
+             }
+        part "sidebar-menu-badge", "The trailing count/status chrome in the row corner - " \
+                                   "pointer-transparent",
+             states: {
+               "data-sidebar" => "always \"menu-badge\" - the suite-wide sub-part marker"
+             }
+
+        # @api private
+        def before_render
+          raise ArgumentError, "Sidebar requires with_nav (the sidebar column)" unless nav?
+        end
+
+        # @api private
+        def data_state
+          open ? "expanded" : "collapsed"
+        end
+
+        # data-collapsible carries the mode only WHILE collapsed - the
+        # expanded peer has an empty data-collapsible.
+        # @api private
+        def data_collapsible
+          open ? "" : collapsible.to_s
+        end
+
+        # @api private
+        def inset_variant?
+          %i[floating inset].include?(variant)
+        end
+
+        # @api private
+        def root_attributes
+          html_attributes.merge_if_not_set(
+            {
+              "data-slot" => "sidebar-wrapper",
+              "style" => "--sidebar-width: #{WIDTH}; --sidebar-width-icon: #{WIDTH_ICON};",
+              "class" => css(:wrapper)
+            }.merge(stimulus_attributes_for(:root)).merge(component_data_attributes)
+          )
+        end
+
+        # @api private
+        def peer_attributes
+          {
+            "data-slot" => "sidebar", "class" => css(:peer),
+            "data-state" => data_state, "data-collapsible" => data_collapsible,
+            "data-variant" => variant, "data-side" => side
+          }.merge(stimulus_attributes_for(:peer))
+        end
+
+        # @api private
+        def gap_classes
+          inset_variant? ? "#{css(:gap)} #{css(:gap_inset)}" : css(:gap)
+        end
+
+        # @api private
+        def container_classes
+          inset_variant? ? "#{css(:container)} #{css(:container_inset)}" : css(:container)
+        end
+
+        # The mobile sheet <dialog> (DOM-move): server-rendered
+        # EMPTY - the controller adopts the nav children on open. Skinned
+        # with the Sheet's presence classes off the sidebar dictionary;
+        # md:hidden keeps it out of the desktop layout wholesale.
+        # @api private
+        def mobile_dialog_attributes
+          attrs = {
+            "data-slot" => "sidebar-mobile", "data-sidebar" => "sidebar",
+            "data-mobile" => "true", "data-side" => side, "data-closed" => "",
+            "class" => "#{css(:mobile)} #{Style.mobile_side(side)}",
+            "style" => "--sidebar-width: #{WIDTH_MOBILE};",
+            "aria-labelledby" => mobile_title_id
+          }
+          attrs.merge(stimulus_attributes_for(:mobile))
+        end
+
+        # @api private
+        def mobile_title_id
+          @mobile_title_id ||= poetry_instance_id("poetry-sidebar-mobile")
+        end
+
+        private :data_state, :data_collapsible, :inset_variant?, :root_attributes, :peer_attributes, :gap_classes
+        private :container_classes, :mobile_dialog_attributes, :mobile_title_id
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module Sidebar
+      # The Sidebar preview: the app shell in the icon-collapsible and
+      # offcanvas modes (the sidecar template composes the full nav + inset,
+      # since it is a helper-heavy structure).
+      class Preview < Poetry::Core::Preview::Base
+        def default
+          render_with_template(template: "poetry/ui/sidebar/shell_preview", locals: { collapsible: :icon })
+        end
+
+        def offcanvas_collapsed
+          render_with_template(template: "poetry/ui/sidebar/shell_preview",
+                               locals: { collapsible: :offcanvas, open: false })
+        end
+      end
+    end
+  end
+end

data/app/components/poetry/ui/sidebar/shell_preview.html.erb

@@ -0,0 +1,47 @@
+<%# The app shell: a grouped nav column + a page inset with the trigger. %>
+<% open = local_assigns.fetch(:open, true) %>
+<div class="h-96 overflow-hidden rounded-lg border">
+  <%= poetry_sidebar(collapsible: collapsible, open: open) do |shell| %>
+    <% shell.with_nav do %>
+      <%= poetry_sidebar_header do %>
+        <div class="flex items-center gap-2 px-2 py-1 text-sm font-semibold">Acme Inc</div>
+      <% end %>
+      <%= poetry_sidebar_content do %>
+        <%= poetry_sidebar_group do %>
+          <%= poetry_sidebar_group_label { "Platform" } %>
+          <%= poetry_sidebar_menu do %>
+            <%= poetry_sidebar_menu_item do %>
+              <%= poetry_sidebar_menu_button(href: "#", active: true) do %>
+                <%= poetry_icon(name: :"layout-dashboard") %><span>Dashboard</span>
+              <% end %>
+            <% end %>
+            <%= poetry_sidebar_menu_item do %>
+              <%= poetry_sidebar_menu_button(href: "#") do %>
+                <%= poetry_icon(name: :inbox) %><span>Inbox</span>
+              <% end %>
+              <%= poetry_sidebar_menu_badge do %>12<% end %>
+            <% end %>
+            <%= poetry_sidebar_menu_item do %>
+              <%= poetry_sidebar_menu_button(href: "#") do %>
+                <%= poetry_icon(name: :settings) %><span>Settings</span>
+              <% end %>
+              <%= poetry_sidebar_menu_action(label: "Settings options") do %>
+                <%= poetry_icon(name: :"ellipsis") %>
+              <% end %>
+            <% end %>
+          <% end %>
+        <% end %>
+      <% end %>
+      <%= poetry_sidebar_footer do %>
+        <div class="px-2 py-1 text-xs text-muted-foreground">v1.0.0</div>
+      <% end %>
+    <% end %>
+    <% shell.with_inset do %>
+      <div class="flex items-center gap-2 border-b p-3">
+        <%= poetry_sidebar_trigger %>
+        <span class="text-sm font-medium">Dashboard</span>
+      </div>
+      <div class="p-4 text-sm text-muted-foreground">Main content area.</div>
+    <% end %>
+  <% end %>
+</div>