rift-ds 1.0.0

package/components/CommandPalette/CommandPalette.d.ts

@@ -0,0 +1,62 @@
+import { default as React } from 'react';
+export interface CommandPaletteCommand {
+    /** Stable identifier */
+    id: string;
+    /** Display label — the primary text matched when filtering */
+    label: string;
+    /** Optional secondary line under the label */
+    description?: string;
+    /** Optional icon — Material Symbol name (string) or custom element (ReactNode) */
+    icon?: string | React.ReactNode;
+    /** Keyboard shortcut shown on the right, e.g. ['⌘', 'P'] */
+    shortcut?: string[];
+    /** Custom node at the row's right edge, after any `shortcut` — a badge or affordance the keycap slot can't express. It renders inside the option row, so keep it non-interactive: a focusable element here would nest controls. */
+    trailing?: React.ReactNode;
+    /** Extra terms that should match this command when filtering */
+    keywords?: string[];
+    /** Whether the command is disabled */
+    disabled?: boolean;
+    /** Called when this command is chosen */
+    onSelect?: () => void;
+}
+export interface CommandPaletteGroup {
+    /** Group heading */
+    label: string;
+    /** Commands within the group */
+    commands: CommandPaletteCommand[];
+}
+export interface CommandPaletteProps {
+    /** Whether the palette is open */
+    open: boolean;
+    /** Callback when the palette requests to open or close */
+    onOpenChange: (open: boolean) => void;
+    /** Commands, grouped under headings */
+    groups: CommandPaletteGroup[];
+    /** Placeholder for the search field */
+    placeholder?: string;
+    /** Message shown when the query matches nothing */
+    emptyMessage?: string;
+    /** Show a loading affordance in place of results */
+    loading?: boolean;
+    /**
+     * Bind Cmd+K / Ctrl+K globally to toggle the palette. Set to false when the
+     * host app owns the shortcut.
+     */
+    hotkey?: boolean;
+    /** Called with the chosen command, after its own `onSelect` */
+    onSelect?: (command: CommandPaletteCommand) => void;
+    /** Called as the user types, for async/server-side search */
+    onSearchChange?: (query: string) => void;
+    /** Skip built-in filtering — use when commands are filtered upstream */
+    manualFiltering?: boolean;
+    /** Hide the hint row at the bottom of the panel */
+    hideFooter?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+/**
+ * CommandPalette component — a modal Cmd+K launcher that searches a grouped
+ * command list. Filtering matches labels, descriptions, and keywords; the
+ * arrow keys move a highlight that stays in view, and Enter runs the command.
+ */
+export declare const CommandPalette: ({ open, onOpenChange, groups, placeholder, emptyMessage, loading, hotkey, onSelect, onSearchChange, manualFiltering, hideFooter, className, }: CommandPaletteProps) => React.ReactPortal | null;

package/components/CommandPalette/CommandPalette.js

@@ -0,0 +1,247 @@
+"use client";
+import { jsxs, jsx } from "react/jsx-runtime";
+import { useState, useRef, useId, useCallback, useMemo, useEffect } from "react";
+import ReactDOM from "react-dom";
+import { Kbd } from "../Kbd/Kbd.js";
+import "./CommandPalette.css";
+import "../../fonts/material-symbols.css";
+import { useMounted } from "../../behaviors/useMounted.js";
+import { useLayer } from "../../behaviors/useLayer.js";
+import { useFocusScope } from "../../behaviors/useFocusScope.js";
+import { useScrollLock } from "../../behaviors/useScrollLock.js";
+const CommandPalette = ({
+  open,
+  onOpenChange,
+  groups,
+  placeholder = "Type a command or search…",
+  emptyMessage = "No matching commands",
+  loading = false,
+  hotkey = true,
+  onSelect,
+  onSearchChange,
+  manualFiltering = false,
+  hideFooter = false,
+  className = ""
+}) => {
+  const [query, setQuery] = useState("");
+  const [rawActiveIndex, setActiveIndex] = useState(0);
+  const [prevOpen, setPrevOpen] = useState(open);
+  const inputRef = useRef(null);
+  const panelRef = useRef(null);
+  const listRef = useRef(null);
+  const generatedId = useId();
+  const baseClass = "ds-command-palette";
+  const mounted = useMounted();
+  const matches = useCallback(
+    (command) => {
+      const q = query.trim().toLowerCase();
+      if (manualFiltering || q === "") return true;
+      const haystack = [command.label, command.description ?? "", ...command.keywords ?? []].join(" ").toLowerCase();
+      return haystack.includes(q);
+    },
+    [manualFiltering, query]
+  );
+  const filteredGroups = useMemo(
+    () => groups.map((group) => ({ ...group, commands: group.commands.filter(matches) })).filter((group) => group.commands.length > 0),
+    [groups, matches]
+  );
+  const flatCommands = useMemo(
+    () => filteredGroups.flatMap((g) => g.commands).filter((c) => !c.disabled),
+    [filteredGroups]
+  );
+  if (prevOpen !== open) {
+    setPrevOpen(open);
+    if (!open) {
+      setQuery("");
+      setActiveIndex(0);
+    }
+  }
+  const activeIndex = Math.min(rawActiveIndex, Math.max(0, flatCommands.length - 1));
+  useEffect(() => {
+    if (!hotkey) return;
+    const handleHotkey = (e) => {
+      if (e.key.toLowerCase() === "k" && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        onOpenChange(!open);
+      }
+    };
+    document.addEventListener("keydown", handleHotkey);
+    return () => document.removeEventListener("keydown", handleHotkey);
+  }, [hotkey, open, onOpenChange]);
+  useLayer({ open, onDismiss: () => onOpenChange(false) });
+  useFocusScope(panelRef, { active: open, initialFocus: () => inputRef.current });
+  useScrollLock(open, { strategy: "cancel-events", allowWithin: listRef });
+  const runCommand = (command) => {
+    if (command.disabled) return;
+    command.onSelect?.();
+    onSelect?.(command);
+    onOpenChange(false);
+  };
+  const handleKeyDown = (e) => {
+    switch (e.key) {
+      case "ArrowDown":
+        e.preventDefault();
+        setActiveIndex(
+          (prev) => flatCommands.length === 0 ? 0 : (prev + 1) % flatCommands.length
+        );
+        break;
+      case "ArrowUp":
+        e.preventDefault();
+        setActiveIndex(
+          (prev) => flatCommands.length === 0 ? 0 : (prev - 1 + flatCommands.length) % flatCommands.length
+        );
+        break;
+      case "Home":
+        e.preventDefault();
+        setActiveIndex(0);
+        break;
+      case "End":
+        e.preventDefault();
+        setActiveIndex(Math.max(0, flatCommands.length - 1));
+        break;
+      case "Enter":
+        e.preventDefault();
+        if (flatCommands[activeIndex]) runCommand(flatCommands[activeIndex]);
+        break;
+    }
+  };
+  useEffect(() => {
+    if (!open || !listRef.current) return;
+    const active = listRef.current.querySelector(
+      `[data-command-index="${activeIndex}"]`
+    );
+    active?.scrollIntoView({ block: "nearest" });
+  }, [activeIndex, open]);
+  const handleQueryChange = (next) => {
+    setQuery(next);
+    setActiveIndex(0);
+    onSearchChange?.(next);
+  };
+  const listboxId = `${generatedId}-listbox`;
+  const activeCommand = flatCommands[activeIndex];
+  const activeDescendantId = activeCommand ? `${generatedId}-command-${activeCommand.id}` : void 0;
+  const classes = [baseClass, open ? `${baseClass}--open` : "", className].filter(Boolean).join(" ");
+  let commandIndex = 0;
+  const palette = /* @__PURE__ */ jsxs("div", { className: classes, children: [
+    /* @__PURE__ */ jsx("div", { className: `${baseClass}__backdrop`, onClick: () => onOpenChange(false) }),
+    /* @__PURE__ */ jsxs(
+      "div",
+      {
+        className: `${baseClass}__panel`,
+        ref: panelRef,
+        role: "dialog",
+        "aria-modal": "true",
+        "aria-label": "Command palette",
+        children: [
+          /* @__PURE__ */ jsxs("div", { className: `${baseClass}__search`, children: [
+            /* @__PURE__ */ jsx("span", { className: `${baseClass}__search-icon material-symbols-rounded`, "aria-hidden": "true", children: "search" }),
+            /* @__PURE__ */ jsx(
+              "input",
+              {
+                ref: inputRef,
+                type: "text",
+                className: `${baseClass}__input`,
+                role: "combobox",
+                autoComplete: "off",
+                "aria-expanded": true,
+                "aria-controls": listboxId,
+                "aria-autocomplete": "list",
+                "aria-activedescendant": activeDescendantId,
+                "aria-label": placeholder,
+                placeholder,
+                value: query,
+                onChange: (e) => handleQueryChange(e.target.value),
+                onKeyDown: handleKeyDown
+              }
+            ),
+            /* @__PURE__ */ jsx(
+              "button",
+              {
+                type: "button",
+                className: `${baseClass}__close`,
+                onClick: () => onOpenChange(false),
+                "aria-label": "Close command palette",
+                children: /* @__PURE__ */ jsx("span", { className: "material-symbols-rounded", "aria-hidden": "true", children: "close" })
+              }
+            )
+          ] }),
+          /* @__PURE__ */ jsxs("div", { className: `${baseClass}__list`, role: "listbox", id: listboxId, ref: listRef, children: [
+            loading && /* @__PURE__ */ jsx("p", { className: `${baseClass}__status`, children: "Loading…" }),
+            !loading && filteredGroups.length === 0 && /* @__PURE__ */ jsx("p", { className: `${baseClass}__status`, "aria-live": "polite", children: emptyMessage }),
+            !loading && filteredGroups.map((group) => /* @__PURE__ */ jsxs(
+              "div",
+              {
+                className: `${baseClass}__group`,
+                role: "group",
+                "aria-label": group.label,
+                children: [
+                  /* @__PURE__ */ jsx("p", { className: `${baseClass}__group-label`, children: group.label }),
+                  group.commands.map((command) => {
+                    const index = command.disabled ? -1 : commandIndex++;
+                    const isActive = index === activeIndex;
+                    return /* @__PURE__ */ jsxs(
+                      "div",
+                      {
+                        id: `${generatedId}-command-${command.id}`,
+                        "data-command-index": index,
+                        className: [
+                          `${baseClass}__command`,
+                          isActive ? `${baseClass}__command--active` : "",
+                          command.disabled ? `${baseClass}__command--disabled` : ""
+                        ].filter(Boolean).join(" "),
+                        role: "option",
+                        "aria-selected": isActive,
+                        "aria-disabled": command.disabled,
+                        onMouseEnter: () => index >= 0 && setActiveIndex(index),
+                        onMouseDown: (e) => e.preventDefault(),
+                        onClick: () => runCommand(command),
+                        children: [
+                          command.icon && /* @__PURE__ */ jsx(
+                            "span",
+                            {
+                              className: `${baseClass}__command-icon${typeof command.icon === "string" ? " material-symbols-rounded" : ""}`,
+                              "aria-hidden": "true",
+                              children: command.icon
+                            }
+                          ),
+                          /* @__PURE__ */ jsxs("span", { className: `${baseClass}__command-text`, children: [
+                            /* @__PURE__ */ jsx("span", { className: `${baseClass}__command-label`, children: command.label }),
+                            command.description && /* @__PURE__ */ jsx("span", { className: `${baseClass}__command-description`, children: command.description })
+                          ] }),
+                          command.shortcut && command.shortcut.length > 0 && /* @__PURE__ */ jsx("span", { className: `${baseClass}__shortcut`, children: command.shortcut.map((key, i) => /* @__PURE__ */ jsx(Kbd, { size: "compact", children: key }, i)) }),
+                          command.trailing && /* @__PURE__ */ jsx("span", { className: `${baseClass}__trailing`, children: command.trailing })
+                        ]
+                      },
+                      command.id
+                    );
+                  })
+                ]
+              },
+              group.label
+            ))
+          ] }),
+          !hideFooter && /* @__PURE__ */ jsxs("div", { className: `${baseClass}__footer`, children: [
+            /* @__PURE__ */ jsxs("span", { className: `${baseClass}__hint`, children: [
+              /* @__PURE__ */ jsx(Kbd, { size: "compact", children: "↑" }),
+              /* @__PURE__ */ jsx(Kbd, { size: "compact", children: "↓" }),
+              "to navigate"
+            ] }),
+            /* @__PURE__ */ jsxs("span", { className: `${baseClass}__hint`, children: [
+              /* @__PURE__ */ jsx(Kbd, { size: "compact", children: "↵" }),
+              "to select"
+            ] }),
+            /* @__PURE__ */ jsxs("span", { className: `${baseClass}__hint`, children: [
+              /* @__PURE__ */ jsx(Kbd, { size: "compact", children: "esc" }),
+              "to close"
+            ] })
+          ] })
+        ]
+      }
+    )
+  ] });
+  if (!mounted) return null;
+  return ReactDOM.createPortal(palette, document.body);
+};
+export {
+  CommandPalette
+};