poetry-core 0.0.2

data/app/components/poetry/core/style.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    # The sidecar style class for a component: the dictionary from the
+    # component's style surface (declared with `style :attr, variants:` on the
+    # component) to CSS utility classes, resolved through the in-tree
+    # {CSS::Resolver}.
+    #
+    # @example
+    #   class Badge::Style < Poetry::Core::Style
+    #     base "inline-flex items-center rounded-md"
+    #     element :icon, "size-3 shrink-0"
+    #     variant :color, red: "bg-destructive/15 text-destructive",
+    #                     gray: "bg-muted text-muted-foreground"
+    #     compound({ color: :red, mode: :dark }, "bg-destructive/25")
+    #   end
+    #
+    # Defaults are NOT declared here - they live in exactly one place, the
+    # component's `style :attr, default:` (the single source of truth; the
+    # component's ActiveModel attributes resolve them before render). A
+    # `defaults` call raises to enforce that.
+    class Style
+      class << self
+        # Each Style class owns a resolver; subclasses extend a copy of their
+        # parent's dictionary.
+        #
+        # @return [CSS::Resolver]
+        def resolver
+          @resolver ||= superclass.respond_to?(:resolver) ? superclass.resolver.dup : CSS::Resolver.new
+        end
+
+        # -- The dictionary DSL (delegates to the resolver) --------------------
+
+        # Declares the root element's always-present utility classes - the
+        # dictionary's base layer, emitted before any variant classes.
+        #
+        # @param classes [String] space-separated utility classes
+        # @example
+        #   base "inline-flex items-center rounded-md"
+        # @return [void]
+        def base(classes)
+          resolver.base(classes)
+        end
+
+        # Declares the classes of a named inner element of the component's
+        # anatomy, resolved with `css(:name)` at render.
+        #
+        # @param name [Symbol] the element name (:icon, :label, ...)
+        # @param classes [String] space-separated utility classes
+        # @example
+        #   element :icon, "size-3 shrink-0"
+        # @return [void]
+        def element(name, classes)
+          resolver.element(name, classes)
+        end
+
+        # Declares one style axis: the classes each value of the component's
+        # matching `style :attr` declaration resolves to.
+        #
+        # @param attr [Symbol] the style attribute this axis resolves
+        # @param mapping [Hash{Symbol => String}] variant value => utility classes
+        # @example
+        #   variant :color, red: "bg-destructive/15 text-destructive",
+        #                   gray: "bg-muted text-muted-foreground"
+        # @return [void]
+        def variant(attr, mapping)
+          resolver.variant(attr, mapping)
+        end
+
+        # Declares classes emitted only when EVERY criteria pair matches the
+        # resolved style values - the cross-axis refinement a single
+        # variant cannot express.
+        #
+        # @param criteria [Hash{Symbol => Object}] style attribute => value pairs
+        # @param classes [String] utility classes added on a full match
+        # @example
+        #   compound({ color: :red, mode: :dark }, "bg-destructive/25")
+        # @return [void]
+        def compound(criteria, classes)
+          resolver.compound(criteria, classes)
+        end
+
+        # Single-source-of-defaults enforcement: defaults belong on the
+        # component (`style :attr, default:`), never in the style dictionary.
+        #
+        # @return [void]
+        # @raise [Poetry::Core::Error] always
+        def defaults(*)
+          raise Poetry::Core::Error,
+                "#{name} declares defaults in the style dictionary - defaults live on the component " \
+                "(`style :attr, default:`), the single source of truth"
+        end
+
+        # Resolves utility classes for the given criteria (and optional
+        # element). The `class:` option appends caller classes, which win on
+        # Tailwind conflicts.
+        #
+        # @param element [Symbol, nil] a declared element name, or nil for the root
+        # @param options [Hash] style attribute => value criteria, plus `class:`
+        # @return [String] the resolved utility classes
+        def css(element = nil, **options)
+          extra = options.delete(:class)
+          resolver.render(element, extra: extra, **options)
+        end
+
+        # { attr => [values] } - the declared variant space, for previews,
+        # docs, and the registry.
+        #
+        # @return [Hash{Symbol => Array<Symbol>}]
+        def variant_options
+          resolver.variant_options
+        end
+
+        # The sibling component class by convention
+        # (Poetry::Core::Dot::Style -> Poetry::Core::Dot::Component).
+        #
+        # @return [Class, nil]
+        def component_class
+          module_parent.const_get(:Component, false)
+        rescue NameError
+          nil
+        end
+
+        # The BEM block this dictionary belongs to, derived from the sibling
+        # component ("poetry/core/dot" -> "poetry-core-dot").
+        #
+        # @return [String, nil]
+        def bem_block
+          component_class&.component_path&.tr("/", "-")
+        end
+
+        # The capsule digest of this dictionary (the :bem leak-guard).
+        #
+        # @return [String]
+        def capsule
+          resolver.digest
+        end
+      end
+
+      # Instance-level mirror so `styler.css(...)` keeps working from the
+      # Styles concern.
+      #
+      # @return [String] the resolved utility classes (see {.css})
+      def css(...)
+        self.class.css(...)
+      end
+    end
+  end
+end

data/app/components/poetry/core/wrapper/component.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    # Namespace of the conditional wrapper: {Wrapper::Component} renders
+    # outer HTML around a child component only when the child itself
+    # renders.
+    module Wrapper
+      # Wraps any component with custom HTML.
+      # The whole wrapper is only rendered when the child component's #render? returns true,
+      # so it can conditionally render the outer HTML for a component without
+      # conditionals in templates.
+      #
+      # Adapted from an MIT-licensed source (source and license in
+      # THIRD_PARTY_NOTICES.md).
+      #
+      # The child's render? is consulted before the child gains a view
+      # context: a render? that calls view helpers works standalone but
+      # not under the wrapper.
+      #
+      # @example
+      #   render Poetry::Core::Wrapper::Component.new(badge) do |wrapper|
+      #     tag.div(class: "mt-2") { wrapper.component }
+      #   end
+      class Component < ViewComponent::Base
+        # Raised when the block calls #component more than once - each
+        # wrapper renders its child exactly one time.
+        class DoubleRenderError < Poetry::Core::Error
+          # Names the child in the message.
+          #
+          # @param component [ViewComponent::Base] the child rendered twice
+          def initialize(component)
+            super("A child component could only be rendered once within a wrapper: #{component}")
+          end
+        end
+
+        # Raised when the wrapper's block never rendered the child - the
+        # wrap would silently drop it.
+        class UnrenderedChildError < Poetry::Core::Error
+          # Names the dropped child in the message.
+          #
+          # @param component [ViewComponent::Base] the child the block skipped
+          def initialize(component)
+            super("The block never rendered the wrapped child - call #component where it belongs: #{component}")
+          end
+        end
+
+        attr_reader :component_instance
+
+        delegate :render?, to: :component_instance
+
+        # Wraps a single child component; intentionally does not chain to
+        # ViewComponent::Base#initialize (it only needs the child reference).
+        #
+        # @param component [ViewComponent::Base] the child component to wrap
+        def initialize(component) # rubocop:disable Lint/MissingSuper
+          raise ArgumentError, "Wrapper wraps a component instance (got nil)" if component.nil?
+
+          @component_instance = component
+        end
+
+        # Returns the block's output, which must have rendered the child -
+        # a block that skips {#component} would drop the child silently,
+        # so it teaches instead. (An alias couldn't be used here:
+        # ViewComponent checks method presence when choosing between
+        # #call and a template.)
+        #
+        # @return [ActiveSupport::SafeBuffer, nil] the block's output
+        # @raise [UnrenderedChildError] when the block never called {#component}
+        def call
+          content.tap do
+            raise UnrenderedChildError, component_instance unless @rendered
+          end
+        end
+
+        # Returns the rendered child component.
+        # The name is chosen for convenient usage in templates,
+        # so `= wrapper.component` reads naturally at the spot where the
+        # child belongs.
+        #
+        # @return [ActiveSupport::SafeBuffer] the rendered child HTML
+        def component
+          raise DoubleRenderError, component_instance if @rendered
+
+          @rendered = component_instance.render_in(view_context).html_safe
+        end
+      end
+    end
+  end
+end

data/app/javascript/poetry/core/accordion_controller.js

@@ -0,0 +1,165 @@
+import { Controller } from "@hotwired/stimulus"
+import { enterPresence, exitPresence, measurePresence } from "@poetry/controllers/helpers/presence"
+import { setState, stateOf } from "@poetry/controllers/helpers/state"
+
+// The accordion open-set machine: single (optionally collapsible)
+// or multiple. Composes with poetry--core--roving-focus (manageTabindex:
+// false - APG keeps every trigger tabbable) attached separately on the
+// same root. Panels ride the presence helper; the measured
+// --accordion-panel-height var feeds the vendored accordion-down/up
+// keyframes.
+
+// Safety net (ms) for clearing the data-transitioning window when
+// animationend never arrives - reduced motion or a zero-length animation.
+// Comfortably longer than the 0.2s accordion keyframe.
+const TRANSITION_FALLBACK_MS = 400
+
+// The component-facing event namespace (the poetry:<component> rule).
+const EVENT_PREFIX = "poetry:accordion"
+
+export default class extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = ["poetry:accordion:change"]
+
+  static values = {
+    type: { type: String, default: "single" },
+    collapsible: { type: Boolean, default: false }
+  }
+
+  // panel -> a clear() that ends its data-transitioning window.
+  #transitions = new Map()
+
+  /**
+   * Each trigger's click action: toggles its item - single mode closes
+   * the others first; single non-collapsible keeps the open item open.
+   * The change event reports the open values.
+   *
+   * @param {MouseEvent} event
+   */
+  toggle(event) {
+    const item = event.currentTarget.closest('[data-slot="accordion-item"]')
+    if (!item) return
+
+    if (stateOf(item) === "open") {
+      if (this.typeValue === "single" && !this.collapsibleValue) return
+      this.#close(item)
+    } else {
+      if (this.typeValue === "single") this.#openItems().forEach((other) => this.#close(other))
+      this.#open(item)
+    }
+    this.#reflectDisabled()
+    this.dispatch("change", { prefix: EVENT_PREFIX, detail: { values: this.#openItems().map((i) => i.dataset.value) } })
+  }
+
+  /**
+   * Reflects the locked-open trigger (aria-disabled) and adopts
+   * data-panel-open onto server-open triggers.
+   */
+  connect() {
+    this.#reflectDisabled()
+    this.#reflectTriggers() // server-open items adopt data-panel-open on connect
+  }
+
+  /**
+   * Flushes any in-flight transition window so its timer/listener doesn't
+   * outlive the controller (Turbo teardown, or a test between cases).
+   */
+  disconnect() {
+    for (const clear of [...this.#transitions.values()]) clear()
+  }
+
+  // Trigger reflection for the server-rendered state (the #open/#close
+  // paths carry it during interaction; this seeds it at connect so an
+  // already-open item's trigger isn't missing data-panel-open until first
+  // toggled).
+  #reflectTriggers() {
+    this.#items().forEach((item) => {
+      const trigger = this.#triggerOf(item)
+      if (trigger) setState(trigger, stateOf(item) === "open" ? "panel-open" : "panel-closed")
+    })
+  }
+
+  #open(item) {
+    const panel = this.#panelOf(item)
+    const trigger = this.#triggerOf(item)
+    setState(item, "open")
+    trigger?.setAttribute("aria-expanded", "true")
+    if (trigger) setState(trigger, "panel-open") // the trigger wears its panel's state (data-panel-open)
+    if (!panel) return
+    panel.hidden = false
+    measurePresence(panel, { property: "--accordion-panel-height" })
+    this.#markTransition(panel)
+    enterPresence(panel)
+  }
+
+  #close(item) {
+    const panel = this.#panelOf(item)
+    const trigger = this.#triggerOf(item)
+    setState(item, "closed")
+    trigger?.setAttribute("aria-expanded", "false")
+    if (trigger) setState(trigger, "panel-closed")
+    if (!panel) return
+    measurePresence(panel, { property: "--accordion-panel-height" })
+    this.#markTransition(panel)
+    exitPresence(panel, { onRemove: () => { panel.hidden = true } })
+  }
+
+  // Single non-collapsible: the open trigger is a no-op - expose that
+  // to AT instead of silently ignoring the click (the contract's call).
+  #reflectDisabled() {
+    const lockOpen = this.typeValue === "single" && !this.collapsibleValue
+    this.#items().forEach((item) => {
+      const trigger = this.#triggerOf(item)
+      if (!trigger) return
+      if (lockOpen && stateOf(item) === "open") {
+        trigger.setAttribute("aria-disabled", "true")
+      } else {
+        trigger.removeAttribute("aria-disabled")
+      }
+    })
+  }
+
+  // The resting-keyframe gate (accordion flicker fix): the panel keeps
+  // data-open the whole time it's open, so the theme's
+  // data-open:animate-accordion-down keyframe would REPLAY every time a
+  // display:none -> visible toggle restarts CSS animations (an accordion
+  // nested in a Tabs panel is the common case - the expand flickers on every
+  // return to the panel). aliases.css stops the keyframe unless
+  // data-transitioning is present; this rides it only for the open/close
+  // window, cleared on animationend (fallback for reduced-motion / zero-length
+  // animations where animationend may not fire).
+  #markTransition(panel) {
+    this.#transitions.get(panel)?.() // supersede any in-flight window
+
+    panel.setAttribute("data-transitioning", "")
+
+    const clear = () => {
+      panel.removeEventListener("animationend", onEnd)
+      clearTimeout(timer)
+      this.#transitions.delete(panel)
+      panel.removeAttribute("data-transitioning")
+    }
+    const onEnd = (event) => { if (event.target === panel) clear() }
+    const timer = setTimeout(clear, TRANSITION_FALLBACK_MS)
+
+    this.#transitions.set(panel, clear)
+    panel.addEventListener("animationend", onEnd)
+  }
+
+  #items() {
+    return [...this.element.querySelectorAll('[data-slot="accordion-item"]')]
+  }
+
+  #openItems() {
+    return this.#items().filter((item) => stateOf(item) === "open")
+  }
+
+  #triggerOf(item) {
+    return item.querySelector('[data-slot="accordion-trigger"]')
+  }
+
+  #panelOf(item) {
+    return item.querySelector('[data-slot="accordion-content"]')
+  }
+}

data/app/javascript/poetry/core/action_bar_controller.js

@@ -0,0 +1,109 @@
+import { Controller } from "@hotwired/stimulus"
+import { announce } from "@poetry/controllers/helpers/announce"
+import { isImeKeydown } from "@poetry/controllers/helpers/escape"
+
+// The floating bulk-actions bar (the ActionBar contract): shows
+// while its table's selection is non-empty, and holds the contract rules -
+// focus NEVER moves in on show; if focus was inside when the bar hides,
+// it returns to where it was before entering (the FocusScope restoreFocus
+// equivalent, scoped small); "Actions available." is announced ONCE per
+// appearance; the visible count RETAINS its last non-zero value while the
+// bar animates out (never a "None selected" flash); Escape anywhere
+// inside clears the selection (the table's engine listens for
+export default class ActionBarController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = ["poetry:data-table:clear-selection"]
+
+  static targets = ["count"]
+  static values = {
+    label: { type: String, default: "%{count} selected" }
+  }
+
+  #announced = false
+  #focusBefore = null
+  #onSelectionChange = (event) => this.#update(event.detail)
+  #onFocusin = (event) => {
+    if (!this.element.contains(event.target)) return
+    if (this.element.contains(this.#focusBefore)) return
+
+    this.#focusBefore = event.relatedTarget instanceof HTMLElement ? event.relatedTarget : null
+  }
+
+  /**
+   * Subscribes to the table's selection-change on the shared wrapper and
+   * starts the focus bookkeeping the hide-restore needs.
+   */
+  connect() {
+    // The bar and its table share a wrapper; listen there so the pairing
+    // is positional, never an id contract.
+    this.element.parentElement?.addEventListener(
+      "poetry:data-table:selection-change", this.#onSelectionChange
+    )
+    document.addEventListener("focusin", this.#onFocusin)
+  }
+
+  /** Unwires both listeners. */
+  disconnect() {
+    this.element.parentElement?.removeEventListener(
+      "poetry:data-table:selection-change", this.#onSelectionChange
+    )
+    document.removeEventListener("focusin", this.#onFocusin)
+  }
+
+  /**
+   * The keydown action: Escape anywhere inside clears the selection.
+   *
+   * @param {KeyboardEvent} event
+   */
+  keydown(event) {
+    if (event.key !== "Escape" || isImeKeydown(event)) return
+
+    event.preventDefault()
+    event.stopPropagation()
+    this.clear()
+  }
+
+  /**
+   * The clear affordance (and Escape): asks the table's engine - which
+   * owns the state - to clear the selection.
+   */
+  clear() {
+    this.dispatch("clear-selection", { prefix: "poetry:data-table" })
+  }
+
+  #update({ count }) {
+    const open = count > 0
+
+    if (open) {
+      // Retain-on-exit: only NON-ZERO counts ever render.
+      if (this.hasCountTarget) {
+        this.countTarget.textContent = this.labelValue.replace("%{count}", String(count))
+      }
+
+      if (this.element.hidden) {
+        this.element.hidden = false
+
+        if (!this.#announced) {
+          announce(this.element.getAttribute("data-available-label") || "Actions available.")
+          this.#announced = true
+        }
+      }
+
+      this.element.setAttribute("data-open", "")
+      return
+    }
+
+    this.#announced = false
+    this.element.removeAttribute("data-open")
+    this.element.hidden = true
+
+    // Focus never moved IN on show; but if the user tabbed in and the bar
+    // just vanished under them, put focus back where it was.
+    if (this.element.contains(document.activeElement) && this.#focusBefore?.isConnected) {
+      this.#focusBefore.focus()
+    }
+
+    this.#focusBefore = null
+  }
+}