lostcoords-ui 0.4.1 → 0.5.0

data/app/views/lostcoords/ui/components/_lc_floating_panel.html.erb

@@ -0,0 +1,8 @@
+<%# locals: (id:, label:, title:, controller:, role:, trigger_variant:, attributes:, content:) %>
+<%= tag.div(class: "relative inline-flex", data: { controller: controller }) do %>
+  <%= lc_button label, variant: trigger_variant, id: "#{id}-trigger", aria: { haspopup: role, expanded: false, controls: id }, data: { "#{controller}_target" => "trigger", action: "#{controller}#toggle" } %>
+  <%= tag.div(**attributes) do %>
+    <% if title %><h2 id="<%= id %>-title" class="<%= lc_heading_class(size: :subheading) %>"><%= title %></h2><% end %>
+    <%= content %>
+  <% end %>
+<% end %>

data/config/helper_renames.json

@@ -6,7 +6,7 @@
   "button_class": "lc_button_class",
   "button_variants": "lc_button_variants",
   "card_class": "lc_card_class",
-  "card_surface_class": "lc_card_surface_class",
+  "card_surface_class": "lc_card_class",
   "container_class": "lc_container_class",
   "dialog_class": "lc_dialog_class",
   "dialog_kinds": "lc_dialog_kinds",
@@ -20,30 +20,29 @@
   "emoji_picker_toneable?": "lc_emoji_picker_toneable?",
   "emoji_picker_version": "lc_emoji_picker_version",
   "empty_state_class": "lc_empty_state_class",
-  "eyebrow_class": "lc_eyebrow_class",
   "field_class": "lc_field_class",
   "field_label_class": "lc_field_label_class",
-  "form_actions_class": "lc_form_actions_class",
-  "form_alert_class": "lc_form_alert_class",
-  "form_alert_icon": "lc_form_alert_icon",
-  "form_card_class": "lc_form_card_class",
+  "form_actions_class": "lc_inline_class",
+  "form_alert_class": "lc_alert_class",
+  "form_alert_icon": "lc_alert_icon",
+  "form_card_class": "lc_card_class",
   "glass_class": "lc_glass_class",
   "heading_class": "lc_heading_class",
   "heroicon": "lc_icon",
   "icon_badge_class": "lc_icon_badge_class",
   "icon_button_class": "lc_icon_button_class",
-  "icon_medallion_class": "lc_icon_medallion_class",
+  "icon_medallion_class": "lc_icon_badge_class",
   "inline_class": "lc_inline_class",
   "input_class": "lc_input_class",
   "menu_option_class": "lc_menu_option_class",
   "menu_popover_class": "lc_menu_popover_class",
-  "pill_class": "lc_pill_class",
-  "pill_row_class": "lc_pill_row_class",
+  "pill_class": "lc_toggle_class",
+  "pill_row_class": "lc_inline_class",
   "popover_class": "lc_popover_class",
   "prose_class": "lc_prose_class",
   "section_header_class": "lc_section_header_class",
-  "segmented_class": "lc_segmented_class",
-  "segmented_tab_class": "lc_segmented_tab_class",
+  "segmented_class": "lc_toggle_group_class",
+  "segmented_tab_class": "lc_toggle_group_item_class",
   "select_class": "lc_select_class",
   "sheet_chip_class": "lc_sheet_chip_class",
   "sheet_data": "lc_sheet_data",
@@ -54,7 +53,7 @@
   "skeleton_class": "lc_skeleton_class",
   "spinner_class": "lc_spinner_class",
   "stack_class": "lc_stack_class",
-  "status_pill_class": "lc_status_pill_class",
+  "status_pill_class": "lc_badge_class",
   "text_class": "lc_text_class",
   "textarea_class": "lc_textarea_class",
   "tw": "lc_tw",
@@ -68,45 +67,44 @@
   "ui_button_link_to": "lc_button_link_to",
   "ui_button_to": "lc_button_to",
   "ui_card": "lc_card",
-  "ui_card_surface": "lc_card_surface",
+  "ui_card_surface": "lc_card",
   "ui_container": "lc_container",
   "ui_copy_button": "lc_copy_button",
   "ui_copy_content": "lc_copy_content",
   "ui_dialog": "lc_dialog",
-  "ui_disclosure": "lc_disclosure",
+  "ui_disclosure": "lc_collapsible",
   "ui_emoji_picker": "lc_emoji_picker",
   "ui_empty_state": "lc_empty_state",
-  "ui_eyebrow": "lc_eyebrow",
   "ui_field": "lc_field",
-  "ui_form_actions": "lc_form_actions",
-  "ui_form_alert": "lc_form_alert",
-  "ui_form_card": "lc_form_card",
+  "ui_form_actions": "lc_inline",
+  "ui_form_alert": "lc_alert",
+  "ui_form_card": "lc_card",
   "ui_heading": "lc_heading",
   "ui_icon_badge": "lc_icon_badge",
   "ui_icon_button": "lc_icon_button",
   "ui_inline": "lc_inline",
   "ui_input": "lc_input",
   "ui_label!": "lc_label!",
-  "ui_medallion": "lc_medallion",
+  "ui_medallion": "lc_icon_badge",
   "ui_menu": "lc_menu",
   "ui_menu_option": "lc_menu_option",
   "ui_normalize_attributes": "lc_normalize_attributes",
   "ui_option!": "lc_option!",
-  "ui_pill": "lc_pill",
-  "ui_pill_row": "lc_pill_row",
+  "ui_pill": "lc_toggle",
+  "ui_pill_row": "lc_inline",
   "ui_popover": "lc_popover",
   "ui_prose": "lc_prose",
   "ui_render_dialog": "lc_render_dialog",
   "ui_render_panel": "lc_render_panel",
   "ui_section": "lc_section",
-  "ui_segmented": "lc_segmented",
-  "ui_segmented_tab": "lc_segmented_tab",
+  "ui_segmented": "lc_toggle_group",
+  "ui_segmented_tab": "lc_toggle_group_item",
   "ui_select": "lc_select",
-  "ui_sheet": "lc_sheet",
+  "ui_sheet": "lc_dialog",
   "ui_skeleton": "lc_skeleton",
   "ui_spinner": "lc_spinner",
   "ui_stack": "lc_stack",
-  "ui_status_pill": "lc_status_pill",
+  "ui_status_pill": "lc_badge",
   "ui_text": "lc_text",
   "ui_textarea": "lc_textarea",
   "ui_toast": "lc_toast"

data/config/importmap.rb

@@ -1,3 +1,11 @@
-# Keys match the host's own helpers/ and controllers/ pins, so imports and stimulus-loading resolve the same way.
+# Everything lives under lostcoords/ui/*. Controllers are also pinned under the host's controllers/* key,
+# so eagerLoadControllersFrom("controllers", application) registers them as lc-* identifiers. A host file
+# with the same name, such as app/javascript/controllers/lc_dialog_controller.js, replaces the gem's.
+pin "lostcoords/ui", to: "lostcoords/ui/index.js", preload: false
 pin_all_from Lostcoords::Ui::Engine.root.join("app/javascript/lostcoords/ui/controllers"), under: "controllers", to: "lostcoords/ui/controllers", preload: false
-pin_all_from Lostcoords::Ui::Engine.root.join("app/javascript/lostcoords/ui/helpers"), under: "helpers", to: "lostcoords/ui/helpers", preload: false
+pin_all_from Lostcoords::Ui::Engine.root.join("app/javascript/lostcoords/ui/helpers"), under: "lostcoords/ui/helpers", to: "lostcoords/ui/helpers", preload: false
+# pin_all_from keeps one mapping per directory, so the namespaced controller keys are pinned one by one.
+Dir[Lostcoords::Ui::Engine.root.join("app/javascript/lostcoords/ui/controllers/*.js")].each do |path|
+  name = File.basename(path, ".js")
+  pin "lostcoords/ui/controllers/#{name}", to: "lostcoords/ui/controllers/#{name}.js", preload: false
+end

data/config/locales/en.yml

@@ -1,6 +1,29 @@
 en:
   lostcoords:
     ui:
+      pager:
+        label: "Pages"
+        previous: "Previous"
+        next: "Next"
+      skip_link:
+        label: "Skip to content"
+      spinner:
+        label: "Loading…"
+      dialog:
+        trigger: "Open dialog"
+        cancel: "Cancel"
+        close: "Close %{title}"
+      menu:
+        label: "Actions"
+      popover:
+        trigger: "Open popover"
+      breadcrumb:
+        label: "Breadcrumb"
+      code_block:
+        label: "Source code"
+        copy: "Copy %{label}"
+        expand: "Show all code"
+        collapse: "Show less code"
       copy_button:
         label: "Copy"
         copied: "Copied"

data/config/locales/es.yml

@@ -1,6 +1,29 @@
 es:
   lostcoords:
     ui:
+      pager:
+        label: "Páginas"
+        previous: "Anterior"
+        next: "Siguiente"
+      skip_link:
+        label: "Saltar al contenido"
+      spinner:
+        label: "Cargando…"
+      dialog:
+        trigger: "Abrir diálogo"
+        cancel: "Cancelar"
+        close: "Cerrar %{title}"
+      menu:
+        label: "Acciones"
+      popover:
+        trigger: "Abrir panel"
+      breadcrumb:
+        label: "Ruta de navegación"
+      code_block:
+        label: "Código fuente"
+        copy: "Copiar %{label}"
+        expand: "Mostrar todo el código"
+        collapse: "Mostrar menos código"
       copy_button:
         label: "Copiar"
         copied: "Copiado"

data/config/locales/ja.yml

@@ -1,6 +1,29 @@
 ja:
   lostcoords:
     ui:
+      pager:
+        label: "ページ"
+        previous: "前へ"
+        next: "次へ"
+      skip_link:
+        label: "本文へ移動"
+      spinner:
+        label: "読み込み中…"
+      dialog:
+        trigger: "ダイアログを開く"
+        cancel: "キャンセル"
+        close: "%{title}を閉じる"
+      menu:
+        label: "操作"
+      popover:
+        trigger: "パネルを開く"
+      breadcrumb:
+        label: "パンくずリスト"
+      code_block:
+        label: "ソースコード"
+        copy: "%{label}をコピー"
+        expand: "コードをすべて表示"
+        collapse: "コードを折りたたむ"
       copy_button:
         label: "コピー"
         copied: "コピー済み"

data/lib/lostcoords/ui/action_view.rb

@@ -3,8 +3,10 @@ require "action_view"
 require "active_support/core_ext/hash"
 require "active_support/core_ext/object/blank"
 require "tailwind_merge"
-require "lostcoords/ui/resources"
-require "lostcoords/ui/icons"
-require "lostcoords/ui/helpers"
+require_relative "resources"
+require_relative "icons"
+require_relative "parts"
+require_relative "form_builder"
+require_relative "helpers"
 
 Lostcoords::Ui.load_translations!

data/lib/lostcoords/ui/builders.rb

@@ -10,7 +10,7 @@ module Lostcoords::Ui
 
       def component?
         !name.to_s.end_with?("_class") &&
-          !%i[lc_tw lc_sheet_data lc_form_alert_icon].include?(name) &&
+          !%i[lc_tw lc_sheet_data lc_alert_icon].include?(name) &&
           helper != "EmojiPickerHelper"
       end
     end

data/lib/lostcoords/ui/form_builder.rb

@@ -0,0 +1,113 @@
+module Lostcoords::Ui
+  # Rails form builder that renders the library's controls and connects model errors to them.
+  #
+  #   <%= lc_form_with model: @project do |form| %>
+  #     <%= form.field :name, hint: "Shown to members" %>
+  #     <%= form.field :email, as: :email_field %>
+  #     <%= form.switch :public %>
+  #     <%= form.submit %>
+  #   <% end %>
+  #
+  # Every standard helper keeps its Rails signature. A symbol `size:` (:sm, :md, :lg) picks the control
+  # size; an integer still sets the HTML size attribute.
+  class FormBuilder < ActionView::Helpers::FormBuilder
+    INPUTS = %i[
+      text_field email_field password_field telephone_field phone_field url_field search_field number_field
+      date_field time_field datetime_field datetime_local_field month_field week_field
+    ].freeze
+
+    INPUTS.each do |selector|
+      define_method(selector) do |method, options = {}|
+        size = control_size!(options)
+        super(method, control_options(method, options, "input", @template.lc_input_class(size: size)))
+      end
+    end
+
+    def text_area(method, options = {})
+      super(method, control_options(method, options, "textarea", @template.lc_textarea_class))
+    end
+    alias textarea text_area
+
+    def select(method, choices = nil, options = {}, html_options = {}, &block)
+      size = control_size!(html_options)
+      super(method, choices, options, control_options(method, html_options, "select", @template.lc_select_class(size: size)), &block)
+    end
+
+    def check_box(method, options = {}, checked_value = "1", unchecked_value = "0")
+      super(method, control_options(method, options, "checkbox-input", @template.lc_checkbox_class), checked_value, unchecked_value)
+    end
+    alias checkbox check_box
+
+    def radio_button(method, tag_value, options = {})
+      super(method, tag_value, control_options(method, options, "radio-input", @template.lc_radio_class))
+    end
+
+    # A checkbox drawn as a switch, with its label beside it.
+    def switch(method, label: nil, hint: nil, checked_value: "1", unchecked_value: "0", **options)
+      input = check_box(method, { role: "switch", class: @template.lc_switch_class(extra: options.delete(:class)), data: { slot: "switch-input" } }.merge(options), checked_value, unchecked_value)
+      choice_label(method, label, hint, "switch", input)
+    end
+
+    # A checkbox with its label beside it.
+    def choice(method, label: nil, hint: nil, checked_value: "1", unchecked_value: "0", **options)
+      choice_label(method, label, hint, "checkbox", check_box(method, options, checked_value, unchecked_value))
+    end
+
+    def label(method, text = nil, options = {}, &block)
+      if text.is_a?(Hash)
+        options = text
+        text = nil
+      end
+      super(method, text, options.merge(class: @template.lc_field_label_class(extra: options[:class])), &block)
+    end
+
+    def submit(value = nil, options = {})
+      if value.is_a?(Hash)
+        options = value
+        value = nil
+      end
+      variant = options.delete(:variant) || :primary
+      size = options.delete(:size) || :md
+      super(value, options.merge(class: @template.lc_button_class(variant: variant, size: size, extra: options[:class])))
+    end
+
+    # Label, control, hint and the attribute's errors in one field. `as:` names the control helper;
+    # a block renders a custom control and receives its attributes to splat with `**control`.
+    def field(method, label: nil, hint: nil, as: :text_field, **options, &block)
+      @template.lc_field(label: label || human_name(method), id: field_id(method), hint: hint, error: errors_for(method)) do |control|
+        if block
+          @template.capture(control, &block)
+        else
+          public_send(as, method, **options, **control.to_hash.except(:id))
+        end
+      end
+    end
+
+    private
+      def control_size!(options)
+        options[:size].is_a?(Symbol) || options[:size].is_a?(String) && options[:size].match?(/\A[a-z]+\z/) ? options.delete(:size).to_sym : :md
+      end
+
+      def control_options(method, options, slot, classes)
+        options = options.dup
+        aria = (options.delete(:aria) || {}).dup
+        aria[:invalid] = true if errors_for(method).any? && !aria.key?(:invalid)
+        data = { slot: slot }.merge(options.delete(:data) || {})
+        options.merge(class: @template.lc_tw(classes, options[:class]), aria: aria, data: data)
+      end
+
+      def choice_label(method, text, hint, slot, input)
+        @template.send(:lc_choice_label, slot, text || human_name(method), hint, input, for: field_id(method))
+      end
+
+      def errors_for(method)
+        return [] unless object.respond_to?(:errors)
+
+        object.errors.full_messages_for(method)
+      end
+
+      def human_name(method)
+        object.class.respond_to?(:human_attribute_name) ? object.class.human_attribute_name(method) : method.to_s.humanize
+      end
+  end
+end

data/lib/lostcoords/ui/parts.rb

@@ -0,0 +1,154 @@
+module Lostcoords::Ui
+  # Builders yielded by compound components, so their parts are scoped and discoverable:
+  #
+  #   <%= lc_card do |card| %>
+  #     <%= card.header title: "Members", description: "People in this workspace" %>
+  #     <%= card.content do %>…<% end %>
+  #     <%= card.footer do %>…<% end %>
+  #   <% end %>
+  #
+  # Every part carries data-slot, so a context can style it without matching classes.
+  module Parts
+    class Base
+      def initialize(view)
+        @view = view
+      end
+
+      private
+        attr_reader :view
+
+        def merge(defaults, attributes)
+          view.send(:lc_attributes, defaults, attributes)
+        end
+
+        def slot(name, attributes, defaults = {})
+          merge(defaults.merge(data: { slot: name }), attributes)
+        end
+
+        def part(tag_name, name, classes, attributes, &block)
+          view.content_tag(tag_name, slot(name, attributes, class: classes), &block)
+        end
+    end
+
+    class Card < Base
+      def header(title: nil, description: nil, level: 3, **attributes, &actions)
+        heading = [ (self.title(title, level: level) if title), (self.description(description) if description) ].compact
+        action = view.capture(&actions) if actions
+        part(:header, "card-header", "flex min-w-0 items-start justify-between gap-content", attributes) do
+          view.safe_join([
+            (view.tag.div(view.safe_join(heading), class: "flex min-w-0 flex-col gap-tight", data: { slot: "card-heading" }) if heading.any?),
+            (view.tag.div(action, class: "flex shrink-0 items-center gap-related", data: { slot: "card-action" }) if action.present?)
+          ].compact)
+        end
+      end
+
+      def title(content = nil, level: 3, **attributes, &block)
+        view.lc_heading(content, level: level, size: :subheading, **slot("card-title", attributes), &block)
+      end
+
+      def description(content = nil, **attributes, &block)
+        view.lc_text(content, size: :small, tone: :muted, **slot("card-description", attributes), &block)
+      end
+
+      def content(**attributes, &block)
+        part(:div, "card-content", "flex min-w-0 flex-col gap-content", attributes, &block)
+      end
+
+      def footer(**attributes, &block)
+        part(:div, "card-footer", "flex min-w-0 flex-wrap items-center justify-end gap-related", attributes, &block)
+      end
+    end
+
+    # Splats into a control as `**field`, so the control gets the field's id and validation attributes.
+    class Field < Base
+      attr_reader :id
+
+      def initialize(view, id, control)
+        super(view)
+        @id = id
+        @control = control
+      end
+
+      def to_hash = @control
+    end
+
+    class Dialog < Base
+      def initialize(view, id)
+        super(view)
+        @id = id
+      end
+
+      def footer(**attributes, &block)
+        part(:div, "dialog-footer", "flex flex-wrap items-center justify-end gap-related", attributes, &block)
+      end
+
+      def close(label = nil, variant: :secondary, **attributes)
+        label ||= view.send(:lc_t, "lostcoords.ui.dialog.cancel")
+        view.lc_button(label, variant: variant, **merge({ data: { action: "lc-dialog#close", slot: "dialog-close" } }, attributes))
+      end
+    end
+
+    class Alert < Base
+      def actions(**attributes, &block)
+        part(:div, "alert-actions", "flex flex-wrap items-center gap-related pt-tight", attributes, &block)
+      end
+    end
+
+    class Tabs < Base
+      Panel = Data.define(:value, :label, :content, :attributes)
+
+      attr_reader :panels
+
+      def initialize(view)
+        super
+        @panels = []
+      end
+
+      # Records a panel; lc_tabs renders the tab list and panels after the block.
+      def panel(label, value: nil, **attributes, &block)
+        value = (value || label).to_s
+        raise ArgumentError, "tab label must not be blank" if label.blank?
+        raise ArgumentError, "duplicate tab value: #{value}" if @panels.any? { |panel| panel.value == value }
+
+        @panels << Panel.new(value, label, (view.capture(&block) if block), attributes)
+        nil
+      end
+    end
+
+    class NavList < Base
+      def initialize(view, compact)
+        super(view)
+        @compact = compact
+      end
+
+      # current: marks the page the reader is on with aria-current="page".
+      def link(label, url, current: false, indent: false, **attributes)
+        view.tag.li(class: ("ps-content" if indent), data: { slot: "nav-item" }) do
+          view.link_to(label, url, **merge({ class: view.lc_nav_link_class(compact: @compact), aria: { current: ("page" if current) }, data: { slot: "nav-link" } }, attributes))
+        end
+      end
+
+      # The list is named with aria-label rather than an id, so the same navigation can render twice,
+      # as in a sidebar and a phone menu.
+      def group(title, **attributes, &block)
+        part(:li, "nav-group", "flex flex-col gap-tight not-first:pt-section", attributes) do
+          view.safe_join([
+            view.tag.span(title, class: "px-3 pb-tight text-caption font-semibold text-foreground", aria: { hidden: true }, data: { slot: "nav-group-title" }),
+            view.tag.ul(view.capture(&block), class: "m-0 flex list-none flex-col gap-px p-0", aria: { label: title })
+          ])
+        end
+      end
+    end
+
+    class DescriptionList < Base
+      def item(term, detail = nil, **attributes, &block)
+        part(:div, "description-item", "grid min-w-0 gap-tight py-heading sm:grid-cols-[minmax(0,1fr)_minmax(0,2fr)] sm:gap-content", attributes) do
+          view.safe_join([
+            view.tag.dt(term, class: "text-label text-muted-foreground", data: { slot: "description-term" }),
+            view.tag.dd(block ? view.capture(&block) : detail, class: "m-0 min-w-0 text-body text-foreground [overflow-wrap:anywhere]", data: { slot: "description-detail" })
+          ])
+        end
+      end
+    end
+  end
+end

data/lib/lostcoords/ui/tokens.rb

@@ -4,9 +4,32 @@ module Lostcoords::Ui
   module Tokens
     THEME_PATH = File.expand_path("../../../app/assets/tailwind/lostcoords/ui/theme.css", __dir__)
     DECLARATION = /(?<![\w-])(--[\w-]+)\s*:/
+    COLORS = {
+      "--background" => "Page background",
+      "--foreground" => "Main text and headings",
+      "--card" => "Cards and grouped content",
+      "--card-foreground" => "Text on cards",
+      "--popover" => "Menus, popovers and dialogs",
+      "--popover-foreground" => "Text on menus, popovers and dialogs",
+      "--primary" => "Primary actions, links, selected states and keyboard focus",
+      "--primary-foreground" => "Text and icons on a solid primary background",
+      "--secondary" => "Secondary buttons",
+      "--secondary-foreground" => "Text on secondary buttons",
+      "--muted" => "Subtle backgrounds: badges, code, skeletons, table headers",
+      "--muted-foreground" => "Secondary text, hints and placeholders",
+      "--accent" => "Hovered rows, menu items and inline code",
+      "--accent-foreground" => "Text on accent backgrounds",
+      "--destructive" => "Errors and destructive actions",
+      "--success" => "Successful actions and positive feedback",
+      "--warning" => "Warnings and items needing attention",
+      "--border" => "Dividers and outlines",
+      "--input" => "Input and toggle fills",
+      "--ring" => "Keyboard focus ring; unset, it follows --primary"
+    }.freeze
+    FONTS = %w[--font-sans --font-display --font-mono --font-japanese].freeze
 
     def self.names
-      File.read(THEME_PATH).scan(DECLARATION).flatten.uniq.sort
+      (COLORS.keys + FONTS).sort
     end
   end
 

data/lib/lostcoords/ui/version.rb

@@ -1,5 +1,5 @@
 module Lostcoords
   module Ui
-    VERSION = "0.4.1"
+    VERSION = "0.5.0"
   end
 end