phlex-cmdk 0.1.0

data/assets/js/cmdk_controller.js

@@ -0,0 +1,110 @@
+/**
+ * Optional Stimulus base controller for phlex-cmdk. The gem's runtime is
+ * framework-free; this thin layer adds idiomatic Hotwire ergonomics on top.
+ *
+ * Attach to the root (or any ancestor of one):
+ *
+ *   Cmdk::Root(data: { controller: 'cmdk' }) do ... end
+ *
+ * Extend it and override the hooks you care about:
+ *
+ *   import CmdkController from 'phlex-cmdk/controller' // or the copied file
+ *
+ *   export default class extends CmdkController {
+ *     itemSelected({ detail: { value } }) { this.runCommand(value) }
+ *     scopeChanged({ detail: { scope, query } }) {
+ *       if (scope === 'user') this.frameTarget.src = `/search/users?q=${query}`
+ *     }
+ *   }
+ *
+ * Requires `@hotwired/stimulus` (peer) and the runtime resolvable as the bare
+ * specifier `cmdk` (importmap: `pin 'cmdk', to: 'cmdk.js'`; bundlers: alias).
+ */
+
+import { Controller } from '@hotwired/stimulus'
+import Cmdk from 'cmdk'
+
+export default class CmdkController extends Controller {
+  #listeners = []
+
+  connect() {
+    Cmdk.scan(this.element)
+    this.#listeners = [
+      ['cmdk-item-select', (event) => this.itemSelected(event)],
+      ['cmdk-value-change', (event) => this.valueChanged(event)],
+      ['cmdk-search-change', (event) => this.searchChanged(event)],
+      ['cmdk-scope-change', (event) => this.scopeChanged(event)],
+    ]
+    for (const [type, listener] of this.#listeners) this.element.addEventListener(type, listener)
+  }
+
+  disconnect() {
+    for (const [type, listener] of this.#listeners) this.element.removeEventListener(type, listener)
+    this.#listeners = []
+  }
+
+  /** The [cmdk-root] this controller manages. */
+  get root() {
+    return this.element.matches('[cmdk-root]') ? this.element : this.element.querySelector('[cmdk-root]')
+  }
+
+  /** Snapshot of { search, scope, picker, query, value, filtered }. */
+  get state() {
+    return Cmdk.getState(this.root)
+  }
+
+  // ── Overridable event hooks (CustomEvents, payload in event.detail) ──
+
+  /** An item was chosen via click or Enter. Cancelable: event.preventDefault(). */
+  itemSelected(event) {}
+
+  /** The highlighted item changed. */
+  valueChanged(event) {}
+
+  /** The search query changed; detail carries { search, scope, query }. */
+  searchChanged(event) {}
+
+  /** A search scope was entered or left. */
+  scopeChanged(event) {}
+
+  // ── Actions / imperative API ──
+
+  /** Open the surrounding or contained <dialog cmdk-dialog>. */
+  open() {
+    Cmdk.openDialog(this.#dialog)
+  }
+
+  close() {
+    Cmdk.closeDialog(this.#dialog)
+  }
+
+  toggle() {
+    this.#dialog?.open ? this.close() : this.open()
+  }
+
+  setSearch(query) {
+    Cmdk.setSearch(this.root, query)
+  }
+
+  setValue(value) {
+    Cmdk.setValue(this.root, value)
+  }
+
+  /**
+   * Enter a scope programmatically. Works as a Stimulus action with params:
+   *   <button data-action="cmdk#enterScope" data-cmdk-scope-param="user">
+   * or called directly: this.enterScope('user')
+   */
+  enterScope(scopeOrEvent) {
+    const scope = typeof scopeOrEvent === 'string' ? scopeOrEvent : scopeOrEvent?.params?.scope
+    if (scope) Cmdk.enterScope(this.root, scope)
+  }
+
+  exitScope() {
+    Cmdk.exitScope(this.root)
+  }
+
+  get #dialog() {
+    return this.element.closest('dialog[cmdk-dialog]') || this.element.querySelector('dialog[cmdk-dialog]')
+  }
+}

data/lib/cmdk/base.rb

@@ -0,0 +1,24 @@
+module Cmdk
+  # Shared base for all cmdk components.
+  class Base < ::Phlex::HTML
+    # Inline equivalent of cmdk's srOnlyStyles, used for the accessible label.
+    SR_ONLY_STYLE = 'position:absolute;width:1px;height:1px;padding:0;margin:-1px;' \
+                    'overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;border-width:0'.freeze
+
+    private
+
+    # Merge user-supplied attributes into the component's defaults.
+    # User values win, except `class` and `style` which are concatenated
+    # and `data` hashes which are merged.
+    def merged(defaults, overrides)
+      defaults.merge(overrides) do |key, default, override|
+        case key
+        when :class then [default, override].compact.join(' ')
+        when :style then [default.to_s.chomp(';'), override].compact.join(';')
+        when :data then default.is_a?(Hash) && override.is_a?(Hash) ? default.merge(override) : override
+        else override
+        end
+      end
+    end
+  end
+end

data/lib/cmdk/dialog.rb

@@ -0,0 +1,35 @@
+module Cmdk
+  # Command menu inside a native <dialog>. Port of `<Command.Dialog>`.
+  #
+  # Replaces the Radix dialog with a native modal dialog: Escape closes it
+  # natively, clicking the backdrop closes it via the runtime, and the
+  # backdrop is styled with `dialog[cmdk-dialog]::backdrop` instead of
+  # `[cmdk-overlay]`. Accepts every `Cmdk::Root` option plus:
+  #
+  # - `open:` render the page with the dialog already open (runtime calls showModal)
+  # - `hotkey:` a key like "k" — the runtime toggles the dialog on cmd/ctrl+key
+  class Dialog < Base
+    def initialize(open: false, hotkey: nil, label: nil, default_value: nil, should_filter: true,
+                   loop: false, vim_bindings: true, disable_pointer_selection: false,
+                   dialog_attributes: {}, **attributes)
+      @open = open
+      @hotkey = hotkey
+      @dialog_attributes = dialog_attributes
+      @root_options = {
+        label: label, default_value: default_value, should_filter: should_filter, loop: loop,
+        vim_bindings: vim_bindings, disable_pointer_selection: disable_pointer_selection
+      }
+      @attributes = attributes
+    end
+
+    def view_template(&block)
+      data = {}
+      data[:cmdk_open] = '' if @open
+      data[:cmdk_dialog_hotkey] = @hotkey if @hotkey
+
+      dialog(**merged({ 'cmdk-dialog' => '', aria_label: @root_options[:label], data: data }, @dialog_attributes)) do
+        render Root.new(**@root_options, **@attributes), &block
+      end
+    end
+  end
+end

data/lib/cmdk/empty.rb

@@ -0,0 +1,15 @@
+module Cmdk
+  # Shown automatically when there are no results. Port of `<Command.Empty>`.
+  # Rendered hidden (inline display:none, so theme CSS cannot override it);
+  # the runtime toggles it based on the filtered result count.
+  class Empty < Base
+    def initialize(**attributes)
+      @attributes = attributes
+    end
+
+    def view_template(&block)
+      defaults = { 'cmdk-empty' => '', role: 'presentation', style: 'display:none' }
+      div(**merged(defaults, @attributes)) { block ? block.call : nil }
+    end
+  end
+end

data/lib/cmdk/footer.rb

@@ -0,0 +1,30 @@
+module Cmdk
+  # Palette footer, as seen in Raycast-style command menus (an extension over
+  # the React API). Render any content; include an element with the
+  # `cmdk-footer-hint` attribute (or pass no block to get one) and the runtime
+  # fills it with the selected item's `hint:` text and `kbd:` keys:
+  #
+  #   Cmdk::Item(hint: 'Open in New Tab', kbd: '⌘ ↵') { 'Figma' }
+  #
+  #   Cmdk::Footer() do
+  #     span { '🚀' }
+  #     div('cmdk-footer-hint' => '')
+  #   end
+  #
+  # The hint container gets `data-empty` when the selected item has no hint.
+  class Footer < Base
+    def initialize(**attributes)
+      @attributes = attributes
+    end
+
+    def view_template(&block)
+      div(**merged({ 'cmdk-footer' => '' }, @attributes)) do
+        if block
+          block.call
+        else
+          div('cmdk-footer-hint' => '')
+        end
+      end
+    end
+  end
+end

data/lib/cmdk/group.rb

@@ -0,0 +1,46 @@
+require 'securerandom'
+
+module Cmdk
+  # Groups items together with an optional heading. Port of `<Command.Group>`.
+  # Provide `value:` when there is no heading (it is used for sorting groups);
+  # with a string heading the value is inferred from it, matching React cmdk.
+  class Group < Base
+    def initialize(heading: nil, value: nil, force_mount: false, scope: nil, scope_only: false,
+                   server_filtered: false, **attributes)
+      @heading = heading
+      @value = value
+      @force_mount = force_mount
+      @scope = scope
+      @scope_only = scope_only
+      @server_filtered = server_filtered
+      @attributes = attributes
+    end
+
+    def view_template(&block)
+      heading_id = @heading ? "cmdk-heading-#{SecureRandom.hex(4)}" : nil
+
+      div(**merged(group_attributes, @attributes)) do
+        if @heading
+          div('cmdk-group-heading' => '', aria_hidden: 'true', id: heading_id) { @heading }
+        end
+        div('cmdk-group-items' => '', role: 'group', aria_labelledby: heading_id) do
+          block ? block.call : nil
+        end
+      end
+    end
+
+    private
+
+    def group_attributes
+      data = {}
+      value = @value || (@heading if @heading.is_a?(String))
+      data[:value] = value if value
+      data[:cmdk_force_mount] = '' if @force_mount
+      data[:cmdk_scope] = @scope if @scope
+      data[:cmdk_scope_only] = '' if @scope_only
+      data[:cmdk_server_filtered] = '' if @server_filtered
+
+      { 'cmdk-group' => '', role: 'presentation', data: data }
+    end
+  end
+end

data/lib/cmdk/input.rb

@@ -0,0 +1,34 @@
+module Cmdk
+  # Command menu search input. Port of `<Command.Input>` from cmdk.
+  # `id`, `aria-controls`, `aria-labelledby` and `aria-activedescendant`
+  # are wired up by the JS runtime at init.
+  class Input < Base
+    # `enterkeyhint:` labels the mobile keyboard's action key (pass nil to omit).
+    def initialize(value: nil, enterkeyhint: 'go', **attributes)
+      @value = value
+      @enterkeyhint = enterkeyhint
+      @attributes = attributes
+    end
+
+    def view_template
+      input(**merged(input_attributes, @attributes))
+    end
+
+    private
+
+    def input_attributes
+      {
+        'cmdk-input' => '',
+        type: 'text',
+        value: @value,
+        autocomplete: 'off',
+        autocorrect: 'off',
+        spellcheck: 'false',
+        role: 'combobox',
+        aria_autocomplete: 'list',
+        aria_expanded: 'true',
+        enterkeyhint: @enterkeyhint
+      }
+    end
+  end
+end

data/lib/cmdk/item.rb

@@ -0,0 +1,54 @@
+module Cmdk
+  # Command menu item. Port of `<Command.Item>` from cmdk.
+  #
+  # Like the React version, `value` is inferred from the rendered text content
+  # when not given (the runtime assigns `data-value` at init). `onSelect`
+  # becomes a bubbling `cmdk-item-select` CustomEvent with `detail.value`.
+  # `href:` is a Turbo-friendly extension: the runtime visits the URL on select.
+  class Item < Base
+    def initialize(value: nil, keywords: nil, disabled: false, force_mount: false, href: nil,
+                   scope: nil, scope_only: false, enters_scope: nil, server_filtered: false,
+                   hint: nil, kbd: nil, **attributes)
+      @value = value
+      @keywords = keywords
+      @disabled = disabled
+      @force_mount = force_mount
+      @href = href
+      @scope = scope
+      @scope_only = scope_only
+      @enters_scope = enters_scope
+      @server_filtered = server_filtered
+      @hint = hint
+      @kbd = kbd
+      @attributes = attributes
+    end
+
+    def view_template(&block)
+      div(**merged(item_attributes, @attributes)) { block ? block.call : nil }
+    end
+
+    private
+
+    def item_attributes
+      data = { disabled: @disabled.to_s, selected: 'false' }
+      data[:value] = @value if @value
+      data[:cmdk_keywords] = Array(@keywords).join(' ') if @keywords
+      data[:cmdk_force_mount] = '' if @force_mount
+      data[:href] = @href if @href
+      data[:cmdk_scope] = @scope if @scope
+      data[:cmdk_scope_only] = '' if @scope_only
+      data[:cmdk_enters_scope] = @enters_scope if @enters_scope
+      data[:cmdk_server_filtered] = '' if @server_filtered
+      data[:cmdk_hint] = @hint if @hint
+      data[:cmdk_kbd] = @kbd if @kbd
+
+      {
+        'cmdk-item' => '',
+        role: 'option',
+        aria_disabled: @disabled.to_s,
+        aria_selected: 'false',
+        data: data
+      }
+    end
+  end
+end

data/lib/cmdk/list.rb

@@ -0,0 +1,17 @@
+module Cmdk
+  # Contains items, groups and separators. Port of `<Command.List>` from cmdk.
+  # The JS runtime keeps the `--cmdk-list-height` CSS variable updated on this
+  # element so the list height can be animated.
+  class List < Base
+    def initialize(label: 'Suggestions', **attributes)
+      @label = label
+      @attributes = attributes
+    end
+
+    def view_template(&block)
+      div(**merged({ 'cmdk-list' => '', role: 'listbox', tabindex: '-1', aria_label: @label }, @attributes)) do
+        div('cmdk-list-sizer' => '') { block ? block.call : nil }
+      end
+    end
+  end
+end

data/lib/cmdk/loading.rb

@@ -0,0 +1,25 @@
+module Cmdk
+  # Loading indicator for asynchronous items. Port of `<Command.Loading>`.
+  # Conditionally render this yourself while loading, as in React cmdk.
+  class Loading < Base
+    def initialize(progress: nil, label: 'Loading...', **attributes)
+      @progress = progress
+      @label = label
+      @attributes = attributes
+    end
+
+    def view_template(&block)
+      defaults = {
+        'cmdk-loading' => '',
+        role: 'progressbar',
+        aria_valuenow: @progress,
+        aria_valuemin: '0',
+        aria_valuemax: '100',
+        aria_label: @label
+      }
+      div(**merged(defaults, @attributes)) do
+        div(aria_hidden: 'true') { block ? block.call : nil }
+      end
+    end
+  end
+end

data/lib/cmdk/root.rb

@@ -0,0 +1,62 @@
+module Cmdk
+  # Command menu root. Port of `<Command>` from cmdk.
+  #
+  # React props map to data attributes consumed by the JS runtime:
+  # shouldFilter, loop, vimBindings, disablePointerSelection, defaultValue.
+  # `onValueChange` becomes a bubbling `cmdk-value-change` CustomEvent;
+  # a custom `filter` can be registered via `Cmdk.setFilter(rootEl, fn)` in JS.
+  #
+  # `scopes:` enables scoped search (an extension over the React API): pass
+  # scope names (`scopes: %w[user doc]`). Typing the scope-picker prefix
+  # ("/" by default, override with `scope_picker: ':'`, disable with
+  # `scope_picker: false`) suggests `Cmdk::Item(enters_scope:)` items;
+  # committing one — or typing the name out ("/user ") — pins the scope as a
+  # pill before the input. The rest of the input is then matched only against
+  # items/groups tagged with the same `scope:`. Pass `active_scope:` to
+  # server-render an already-pinned scope.
+  class Root < Base
+    def initialize(label: nil, default_value: nil, should_filter: true, loop: false,
+                   vim_bindings: true, disable_pointer_selection: false, scopes: nil,
+                   scope_picker: nil, active_scope: nil, **attributes)
+      @label = label
+      @default_value = default_value
+      @should_filter = should_filter
+      @loop = loop
+      @vim_bindings = vim_bindings
+      @disable_pointer_selection = disable_pointer_selection
+      @scopes = scopes
+      @scope_picker = scope_picker
+      @active_scope = active_scope
+      @attributes = attributes
+    end
+
+    def view_template(&block)
+      div(**merged(root_attributes, @attributes)) do
+        label('cmdk-label' => '', style: SR_ONLY_STYLE) { @label }
+        yield_content(&block)
+      end
+    end
+
+    private
+
+    def yield_content(&block)
+      block ? block.call : nil
+    end
+
+    def root_attributes
+      data = {}
+      data[:cmdk_should_filter] = 'false' unless @should_filter
+      data[:cmdk_loop] = '' if @loop
+      data[:cmdk_vim_bindings] = 'false' unless @vim_bindings
+      data[:cmdk_disable_pointer_selection] = '' if @disable_pointer_selection
+      data[:cmdk_default_value] = @default_value if @default_value
+      data[:cmdk_scopes] = Array(@scopes).join(' ') if @scopes
+      data[:cmdk_active_scope] = @active_scope if @active_scope
+      unless @scope_picker.nil?
+        data[:cmdk_scope_picker] = @scope_picker == false ? 'false' : @scope_picker
+      end
+
+      { 'cmdk-root' => '', tabindex: '-1', data: data }
+    end
+  end
+end

data/lib/cmdk/separator.rb

@@ -0,0 +1,16 @@
+module Cmdk
+  # Visual and semantic separator. Port of `<Command.Separator>`.
+  # Hidden by the runtime while a search query is present, unless `always_render:`.
+  class Separator < Base
+    def initialize(always_render: false, **attributes)
+      @always_render = always_render
+      @attributes = attributes
+    end
+
+    def view_template
+      defaults = { 'cmdk-separator' => '', role: 'separator' }
+      defaults[:data] = { cmdk_always_render: '' } if @always_render
+      div(**merged(defaults, @attributes))
+    end
+  end
+end

data/lib/cmdk/version.rb

@@ -0,0 +1,3 @@
+module Cmdk
+  VERSION = '0.1.0'
+end

data/lib/cmdk.rb

@@ -0,0 +1,40 @@
+require 'date' # phlex 2.4 references Date in attribute generation without requiring it
+require 'phlex'
+
+# Phlex port of the cmdk React command menu. Renders the same markup contract
+# (cmdk-* attributes, ARIA roles) as the React package; runtime behavior is
+# provided by assets/js/cmdk.js.
+module Cmdk
+  extend Phlex::Kit
+
+  # Absolute path to the JS runtime, for serving or copying into asset pipelines.
+  def self.javascript_path
+    File.expand_path('../assets/js/cmdk.js', __dir__)
+  end
+
+  # Absolute path to the optional themes stylesheet (cmdk-vercel, cmdk-linear,
+  # cmdk-raycast). Plain dependency-free CSS — serve it, copy it, or import it
+  # into a Tailwind build.
+  def self.stylesheet_path
+    File.expand_path('../assets/css/cmdk_themes.css', __dir__)
+  end
+
+  # Absolute path to the optional Stimulus base controller (requires
+  # @hotwired/stimulus and the runtime pinned/aliased as `cmdk`).
+  def self.stimulus_controller_path
+    File.expand_path('../assets/js/cmdk_controller.js', __dir__)
+  end
+end
+
+require_relative 'cmdk/version'
+require_relative 'cmdk/base'
+require_relative 'cmdk/root'
+require_relative 'cmdk/input'
+require_relative 'cmdk/list'
+require_relative 'cmdk/item'
+require_relative 'cmdk/group'
+require_relative 'cmdk/separator'
+require_relative 'cmdk/empty'
+require_relative 'cmdk/loading'
+require_relative 'cmdk/footer'
+require_relative 'cmdk/dialog'

data/lib/phlex-cmdk.rb

@@ -0,0 +1 @@
+require_relative 'cmdk'

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: phlex-cmdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Leon Gieser
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: phlex
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: Phlex components and a dependency-free JS runtime providing feature parity
+  with the cmdk React command menu, plus scoped search, footer hints and ready-made
+  themes. Agnostic about styling (CSS, SCSS or Tailwind) and JS wiring (plain listeners
+  or Stimulus); progressively enhances with Turbo when present.
+email:
+- leon.gieser@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- assets/css/cmdk_themes.css
+- assets/js/cmdk.js
+- assets/js/cmdk_controller.js
+- lib/cmdk.rb
+- lib/cmdk/base.rb
+- lib/cmdk/dialog.rb
+- lib/cmdk/empty.rb
+- lib/cmdk/footer.rb
+- lib/cmdk/group.rb
+- lib/cmdk/input.rb
+- lib/cmdk/item.rb
+- lib/cmdk/list.rb
+- lib/cmdk/loading.rb
+- lib/cmdk/root.rb
+- lib/cmdk/separator.rb
+- lib/cmdk/version.rb
+- lib/phlex-cmdk.rb
+homepage: https://github.com/leongieser/phlex-cmdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/leongieser/phlex-cmdk
+  source_code_uri: https://github.com/leongieser/phlex-cmdk
+  changelog_uri: https://github.com/leongieser/phlex-cmdk/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: 'Fast, composable command menu for Phlex: a port of cmdk (React).'
+test_files: []