poetry-ui 0.0.2

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

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # DataTable family: the sortable, filterable, paginated table plus
+    # its URL-state object.
+    module DataTable
+      # A data table: the composed Table with sortable column headers, a
+      # filter box, and Pagination, where sort/filter/page live in the
+      # URL as query params - shareable and back-button-correct. Data
+      # stays with the host: the controller builds a sanitized State from
+      # params, runs its own scope, and hands the page of rows in.
+      # Row-level mutation (inline edit, row actions) belongs to reactive
+      # components rendered inside cells, never to this component.
+      #
+      # @example A sortable notes table
+      #   <%= poetry_data_table(rows: @notes, state: state, total: @pages,
+      #                         path: ->(p) { notes_path(**p) }, caption: "Notes") do |t| %>
+      #     <% t.with_column("Title", key: :title, sortable: true) { |note| note.title } %>
+      #     <% t.with_column("Created", key: :created_at, sortable: true) { |note| note.created_at.to_date } %>
+      #   <% end %>
+      class Component < Poetry::Core::Component
+        # Projected into the registry, llms.txt, and the agent surface.
+        AGENT_RULES = [
+          "Build State.from_params(params, sortable: [...]) in the controller - NEVER order by raw params; " \
+          "the whitelist is what makes state.order_clause injection-safe.",
+          "Column cell blocks RETURN the cell content ({ |row| row.title }) - they must not write to the " \
+          "template buffer.",
+          "Sort/filter/page are URL state over GET links and a GET form. Row mutations (inline edit, row " \
+          "actions) belong to poetry-reactive components rendered inside cells - never to this component.",
+          "Give the table a caption: - it is the table's accessible purpose."
+        ].freeze
+
+        # The cell block is a per-row RENDERER, not captured content: it
+        # receives each row record (SLOT_BLOCK_YIELDS exempts it from the
+        # yieldless contract), and a column cannot exist without one.
+        SLOT_BLOCK_YIELDS = { column: "the row record" }.freeze
+        # Slots whose block content is required, with the hint the check surfaces.
+        SLOT_REQUIRED_CONTENT = { column: "the cell renderer - { |row| ... }" }.freeze
+
+        # The required slots, stated statically so static checks can flag
+        # a missing column without rendering.
+        REQUIRED_SLOTS = { column: "at least one column" }.freeze
+
+        renders_many :columns,
+                     doc: "Columns are DECLARED here and rendered per row by the template. A sortable column's key " \
+                          "must be in the state's whitelist - catching drift between the view's columns and the " \
+                          "controller's sortable: list at render, not as a silently unsortable header.",
+                     renders: lambda { |label, key: nil, sortable: false, classes: nil, &cell|
+                       if sortable && !key
+                         raise ArgumentError,
+                               "DataTable column #{label.inspect}: sortable: true requires a key:"
+                       end
+                       if sortable && !state.sortable?(key)
+                         raise ArgumentError,
+                               "DataTable column #{key.inspect} is sortable in the view but missing from the " \
+                               "controller's State sortable: whitelist (#{state.sortable.inspect}) - add it there"
+                       end
+                       raise ArgumentError, "DataTable column #{label.inspect} requires a cell block" unless cell
+
+                       column_defs << Column.new(label: label, key: key&.to_s, sortable: sortable, classes: classes,
+                                                 cell: cell)
+                       nil
+                     }
+
+        # The whole selection surface is selectable?-gated.
+        use_stimulus do
+          on :root, if: :selectable? do
+            controller :table_selection do
+              register
+              value :label, from: :selected_count_label
+            end
+          end
+          on :select_all do
+            controller :table_selection do
+              target :all
+              action :toggleAll, on: :change
+            end
+          end
+          on :row_checkbox do
+            controller :table_selection do
+              action :press, on: %i[pointerdown keydown]
+              action :toggled, on: :change
+            end
+          end
+        end
+
+        option :caption, :string, doc: "The table's accessible purpose, rendered as its <caption>."
+        option :empty_text, :string, default: "No results.", doc: "Shown in a full-width row when rows are empty."
+        option :filter, :boolean, default: true, doc: "Renders the filter form; false drops the toolbar row."
+        option :filter_label, :string, default: "Filter", doc: "The filter input's accessible label."
+        option :filter_placeholder, :string, default: "Filter…", doc: "The filter input's placeholder text."
+        option :filter_name, :string, default: "q", doc: "The query-param key the filter submits under."
+        option :frame, :string,
+               doc: "Wrap in a <turbo-frame data-turbo-action=\"advance\"> so hosts with Turbo scope the round trip " \
+                    "to the table while the URL still advances. The host response must render the same frame id."
+        option :sticky_header, :boolean, default: false,
+                                         doc: "Forwarded to the inner Table: sticky_header pins the thead while the " \
+                                              "table's scroll container scrolls; container_class caps that " \
+                                              "container's height (\"max-h-96\") - without a cap nothing sticks. The " \
+                                              "sticky scroll region needs an accessible name (the ScrollArea rule); " \
+                                              "scroll_label: falls back to caption:."
+        option :container_class, :string,
+               doc: "Caps the scroll container's height (e.g. \"max-h-96\") - without a cap the sticky header has " \
+                    "nothing to stick inside."
+        option :scroll_label, :string, doc: "Accessible name for the sticky scroll region; falls back to caption:."
+        option :selectable, ActiveModel::Type::Value.new,
+               doc: "Row selection: a lambda mapping each row to its id turns the feature ON - a leading checkbox " \
+                    "column (select-all with a real indeterminate middle state, shift ranges, count announcements) " \
+                    "whose checkboxes ARE the form value (selection_name[], plain checkboxes with no JS). Pair with " \
+                    "the action-bar block for bulk actions."
+        option :selection_name, :string, default: "selected_ids",
+                                         doc: "The checkbox field name; selected row ids post as selection_name[]."
+
+        part "data-table", "Root surface - toolbar, table, and pagination footer stack here"
+        part "data-table-toolbar", "The row above the table holding the filter form - " \
+                                   "renders unless filter: false"
+        part "data-table-filter", "The GET filter form (role=search) - hidden fields carry the " \
+                                  "current sort; a new filter resets the page"
+        part "table-container", "The composed Table's scroll container - Table renders it, " \
+                                "this surface owns where it sits"
+        part "data-table-footer", "The Pagination row - renders when total: is more than one page"
+        # The selection checkboxes (selectable: only) render INSIDE the
+        # composed Table's root, so ownership attributes them to Table
+        # (the NumberField-stepper precedent) - prose, not parts:
+        # data-slot="data-table-select-all" is the header checkbox (the
+        # controller drives its INDETERMINATE middle state as a property);
+        # data-slot="data-table-select-row" is one row's checkbox - THE
+        # form value (selection_name[], value from the selectable: lambda);
+        # the controller mirrors aria-selected/data-selected onto rows.
+
+        # The structural collaborators handed in at construction.
+        # @api private
+        attr_reader :rows, :state, :total
+
+        # Enforces at least one declared column.
+        # @api private
+        def before_render
+          raise ArgumentError, "DataTable requires at least one with_column" unless columns?
+        end
+
+        # The declared columns in order.
+        # @api private
+        def column_defs
+          @column_defs ||= []
+        end
+
+        # Attributes for the root surface.
+        # @api private
+        def root_attributes
+          attrs = { "data-slot" => "data-table" }.merge(component_data_attributes)
+          attrs = attrs.merge(stimulus_attributes_for(:root))
+          html_attributes.merge_if_not_set(attrs)
+        end
+
+        # Whether row selection is on (selectable: present).
+        # @api private
+        def selectable?
+          selectable.present?
+        end
+
+        # Attributes for the select-all header checkbox.
+        # @api private
+        def select_all_attributes
+          {
+            "type" => "checkbox", "data-slot" => "data-table-select-all",
+            "class" => css(:checkbox),
+            "aria-label" => t("poetry.data_table.select_all")
+          }.merge(stimulus_attributes_for(:select_all))
+        end
+
+        # Attributes for one row's selection checkbox - the form value.
+        # @api private
+        def select_row_attributes(row)
+          {
+            "type" => "checkbox", "data-slot" => "data-table-select-row",
+            "name" => "#{selection_name}[]", "value" => selectable.call(row),
+            "class" => css(:checkbox),
+            "aria-label" => t("poetry.data_table.select_row")
+          }.merge(stimulus_attributes_for(:row_checkbox))
+        end
+
+        # The localized count-announcement template.
+        # @api private
+        def selected_count_label = t("poetry.data_table.selected_count")
+
+        # Builds a URL for the given state params via the path: lambda.
+        # @api private
+        def path_for(params)
+          @path.call(params)
+        end
+
+        # th attributes: the Table head classes plus aria-sort on the
+        # actively sorted column (the APG announcement mechanism - one
+        # column at a time).
+        # @api private
+        def head_attributes(column)
+          attrs = { "data-slot" => "table-head", class: merge_classes(Table::Style.css(:head), column.classes) }
+          if column.sortable && state.sorted_by?(column.key)
+            attrs["aria-sort"] = state.dir == "asc" ? "ascending" : "descending"
+          end
+          attrs
+        end
+
+        # td attributes for one column's cells.
+        # @api private
+        def cell_attributes(column)
+          { "data-slot" => "table-cell", class: merge_classes(Table::Style.css(:cell), column.classes) }
+        end
+
+        # The sort affordance: a ghost Button-styled LINK to the toggled
+        # ordering (a real href - keyboard, middle-click, and share all work).
+        # @api private
+        def sort_link_options(column)
+          {
+            tag: :a, href: path_for(state.toggle_params(column.key)),
+            variant: :ghost, size: :sm, class: Style.css(:sort_link),
+            data: { slot: "data-table-sort" }
+          }
+        end
+
+        # The header glyph for a column's current sort state.
+        # @api private
+        def sort_icon(column)
+          return :"arrow-up-down" unless state.sorted_by?(column.key)
+
+          state.dir == "asc" ? :"arrow-up" : :"arrow-down"
+        end
+
+        # The filter input's id (the label's for= target).
+        # @api private
+        def filter_id
+          @filter_id ||= "#{poetry_instance_id("poetry-data-table")}-filter"
+        end
+
+        # The filter form's action is the bare collection URL; the current
+        # sort rides hidden fields and the page deliberately resets (a new
+        # filter is a new list).
+        # @api private
+        def filter_form_action
+          path_for({})
+        end
+
+        # Whether the pagination footer renders (total: > 1 page).
+        # @api private
+        def pagination?
+          total.present? && total > 1
+        end
+
+        # A declared column: header label, the whitelisted sort key, and the
+        # cell block (called per row, returns the cell content).
+        # @api private
+        Column = Data.define(:label, :key, :sortable, :classes, :cell)
+
+        private
+
+        # rows/state/path/total are structural collaborators, not typed
+        # options (see Pagination's path: for the precedent).
+        def initialize(rows:, state:, path:, total: nil, **)
+          super(**)
+          @rows = rows
+          @state = state
+          @path = path
+          @total = total
+        end
+
+        def merge_classes(*values)
+          values.compact.join(" ")
+        end
+
+        private :column_defs, :root_attributes, :selectable?, :select_all_attributes, :select_row_attributes
+        private :selected_count_label, :path_for, :head_attributes, :cell_attributes, :sort_link_options, :sort_icon
+        private :filter_id, :filter_form_action, :pagination?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module DataTable
+      # The DataTable preview: a small invoices dataset in the three states
+      # a host sees - sorted, filtered+paginated, and empty.
+      class Preview < Poetry::Core::Preview::Base
+        Invoice = Struct.new(:number, :customer, :amount, keyword_init: true)
+
+        ROWS = [
+          Invoice.new(number: "INV-001", customer: "Acme", amount: "$250.00"),
+          Invoice.new(number: "INV-002", customer: "Globex", amount: "$1,150.00"),
+          Invoice.new(number: "INV-003", customer: "Initech", amount: "$420.00")
+        ].freeze
+
+        def default
+          render_component(rows: ROWS, state: state(sort: "number", dir: "asc"),
+                           path: path, caption: "A list of recent invoices.") do |table|
+            columns(table)
+          end
+        end
+
+        # Row selection: selectable: maps rows to ids; the header
+        # checkbox tri-states, shift-click ranges, the checkboxes ARE the
+        # selected_ids[] form value. Pair with the action-bar block.
+        def selectable
+          render_component(rows: ROWS, state: state(sort: "number", dir: "asc"),
+                           path: path, caption: "A list of recent invoices.",
+                           selectable: ->(invoice) { invoice.number }) do |table| # rubocop:disable Style/SymbolProc
+            columns(table)
+          end
+        end
+
+        def filtered_and_paginated
+          render_component(rows: ROWS.first(2), total: 3,
+                           state: state(q: "inv", sort: "customer", dir: "desc", page: 2),
+                           path: path, caption: "A list of recent invoices.") do |table|
+            columns(table)
+          end
+        end
+
+        def empty
+          render_component(rows: [], state: state(q: "zzz"), path: path,
+                           caption: "A list of recent invoices.") do |table|
+            columns(table)
+          end
+        end
+
+        private
+
+        def columns(table)
+          table.with_column("Invoice", key: :number, sortable: true, &:number)
+          table.with_column("Customer", key: :customer, sortable: true, &:customer)
+          table.with_column("Amount", classes: "text-right", &:amount)
+        end
+
+        def state(**params)
+          State.from_params(params, sortable: %w[number customer])
+        end
+
+        def path
+          ->(params) { "?#{params.to_query}" }
+        end
+      end
+    end
+  end
+end

data/app/components/poetry/ui/data_table/state.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module DataTable
+      # The DataTable's URL state - sort/filter/page as query params
+      # (shareable, back-button-correct), sanitized at the door so request
+      # params can never reach an ORDER BY. `sort` is kept ONLY when it
+      # appears in the `sortable:` whitelist and `dir` only when it is
+      # asc/desc - so #order_clause is safe by construction, never by
+      # caller discipline.
+      #
+      # @example Building state in the controller
+      #   state = Poetry::Ui::DataTable::State.from_params(
+      #     params, sortable: %w[title created_at], default_sort: "created_at", default_dir: "desc"
+      #   )
+      #   scope = Note.all
+      #   scope = scope.where("title LIKE ?", "%#{Note.sanitize_sql_like(state.q)}%") if state.q
+      #   notes = scope.order(state.order_clause).offset(...).limit(per)
+      class State
+        # The closed vocabulary for the sort direction.
+        DIRECTIONS = %w[asc desc].freeze
+
+        # The sanitized pieces: filter query, sort column, direction,
+        # page number, and the sortable whitelist.
+        attr_reader :q, :sort, :dir, :page, :sortable
+
+        # Builds state from request params: sort survives only when it
+        # appears in the sortable: whitelist, dir only when asc/desc, the
+        # page floors at 1, and the query is stripped.
+        #
+        # @param params [Hash] the request params
+        # @param sortable [Array] the whitelist of sortable column keys
+        # @param default_sort [String, nil] the column when none is given
+        # @param default_dir [String] the direction when none is given
+        def self.from_params(params, sortable:, default_sort: nil, default_dir: "asc")
+          allowed = Array(sortable).map(&:to_s)
+          raw_sort = params[:sort].to_s
+          raw_dir = params[:dir].to_s
+
+          new(
+            q: params[:q].to_s.strip.presence,
+            sort: allowed.include?(raw_sort) ? raw_sort : default_sort&.to_s,
+            dir: DIRECTIONS.include?(raw_dir) ? raw_dir : default_dir.to_s,
+            page: [params[:page].to_i, 1].max,
+            sortable: allowed
+          )
+        end
+
+        # Direct construction with pre-sanitized values; prefer
+        # .from_params for anything that came in on a request.
+        def initialize(q: nil, sort: nil, dir: "asc", page: 1, sortable: [])
+          @q = q
+          @sort = sort
+          @dir = dir
+          @page = page
+          @sortable = sortable
+        end
+
+        # Whether the column is in the sortable whitelist.
+        def sortable?(column)
+          sortable.include?(column.to_s)
+        end
+
+        # Whether the column is the actively sorted one.
+        def sorted_by?(column)
+          sort == column.to_s
+        end
+
+        # Injection-safe by construction: sort survived the whitelist and dir
+        # the asc/desc check, so this can go straight into .order(). Nil when
+        # nothing is sorted.
+        def order_clause
+          return nil unless sort
+
+          { sort => dir.to_sym }
+        end
+
+        # The full state as query params (blank pieces omitted; page 1 is the
+        # default and stays out of the URL).
+        def to_params
+          params = {}
+          params[:q] = q if q
+          if sort
+            params[:sort] = sort
+            params[:dir] = dir
+          end
+          params[:page] = page if page > 1
+          params
+        end
+
+        # Params for clicking a sortable header: same column flips the
+        # direction, a new column starts ascending; the page resets (a new
+        # ordering is a new list).
+        def toggle_params(column)
+          column = column.to_s
+          next_dir = sorted_by?(column) && dir == "asc" ? "desc" : "asc"
+          to_params.except(:page).merge(sort: column, dir: next_dir)
+        end
+
+        # Params for navigating to a page of the current view.
+        def page_params(number)
+          number > 1 ? to_params.merge(page: number) : to_params.except(:page)
+        end
+
+        # The state a filter submission must carry as hidden fields: sort
+        # survives, the page resets (a new filter is a new list), and q is
+        # the form input itself.
+        def filter_params
+          to_params.except(:q, :page)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    module DataTable
+      # Re-expressed through the cn-* theme layer: the chrome rides
+      # poetry-named rules (own component - no upstream cn vocabulary).
+      class Style < Poetry::Core::Style
+        base "w-full"
+
+        element :toolbar, "cn-data-table-toolbar flex items-center"
+        element :container, "cn-data-table-container overflow-hidden " \
+                            "[&_tr[data-selected]]:bg-muted/50"
+        element :footer, "cn-data-table-footer"
+        element :empty, "cn-data-table-empty"
+
+        # POETRY ADDITION: the caption lives INSIDE the bordered container
+        # (a <caption> cannot leave its <table>), so Table's mt-4 needs a
+        # matching bottom margin or the text hugs the frame's border.
+        # Upstream never composes this - its bordered data-table demo has
+        # no caption; its captioned table demo has no border.
+        element :caption, "mb-4"
+
+        # POETRY ADDITION: the ghost sort button's px-3 shifts the header
+        # LABEL 12px off the column's data text (upstream's demo carries
+        # the same quirk and users patch it with a negative margin - here
+        # the component owns the link, so the component compensates).
+        # Negative on BOTH sides: only the binding side of the cell's
+        # text-align has any layout effect, so one class serves left- and
+        # right-aligned columns alike.
+        element :sort_link, "-mx-3"
+        # Selection: native checkboxes on the token accent; the
+        # selected-row wash rides the container (rows are controller-
+        # marked data-selected).
+        element :checkbox, "size-4 shrink-0 translate-y-px rounded-sm border-input " \
+                           "accent-primary outline-none " \
+                           "focus-visible:ring-[3px] focus-visible:ring-ring/50"
+        element :select_cell, "w-10"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+<%# Progressive enhancement: the native input is the visible control (and
+    the form value) until the controller builds segments into the group
+    and hides it from the tab order. %>
+<%= 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 %>