@jcsoftdev/ui 0.1.6 → 0.2.0

package/dist/primitives/command/command.js

@@ -0,0 +1,488 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  useSyncExternalStore
+} from "react";
+import { composeHandlers, useComposedRefs } from "../../utils/compose.js";
+import * as DialogPrimitive from "../dialog/dialog.js";
+import { commandScore } from "./score.js";
+import { CommandStore } from "./store.js";
+const CommandContext = createContext(null);
+const GroupContext = createContext(null);
+const InDialogContext = createContext(false);
+function useCommandContext(part) {
+  const context = useContext(CommandContext);
+  if (!context) throw new Error(`<Command.${part}> must be rendered inside <Command>`);
+  return context;
+}
+function useCommandState(selector) {
+  const { store } = useCommandContext("useCommandState");
+  const read = () => selector(store.getState());
+  return useSyncExternalStore(store.subscribe, read, read);
+}
+const ITEM = "[data-ui-command-item]";
+const ENABLED_ITEM = `${ITEM}:not([data-disabled])`;
+const GROUP = "[data-ui-command-group]";
+const GROUP_HEADING = "[data-ui-command-group-heading]";
+const srOnly = {
+  position: "absolute",
+  width: 1,
+  height: 1,
+  padding: 0,
+  margin: -1,
+  overflow: "hidden",
+  clip: "rect(0, 0, 0, 0)",
+  whiteSpace: "nowrap",
+  borderWidth: 0
+};
+function Root({
+  label = "Command menu",
+  shouldFilter = true,
+  filter = commandScore,
+  value,
+  defaultValue = "",
+  onValueChange,
+  loop = false,
+  vimBindings = true,
+  onKeyDown,
+  children,
+  ref,
+  ...props
+}) {
+  const rootRef = useRef(null);
+  const composedRef = useComposedRefs(ref, rootRef);
+  const [store] = useState(() => {
+    const created = new CommandStore({
+      shouldFilter,
+      filter,
+      controlledValue: value,
+      onValueChange
+    });
+    created.syncValue(value ?? defaultValue);
+    return created;
+  });
+  const listId = useId();
+  const inputId = useId();
+  const labelId = useId();
+  const [context] = useState(() => ({
+    store,
+    rootRef,
+    listId,
+    inputId,
+    labelId,
+    loop
+  }));
+  context.loop = loop;
+  const previous = useRef({ shouldFilter, filter });
+  useLayoutEffect(() => {
+    store.options = { shouldFilter, filter, controlledValue: value, onValueChange };
+    if (previous.current.shouldFilter !== shouldFilter || previous.current.filter !== filter) {
+      previous.current = { shouldFilter, filter };
+      store.refresh();
+    }
+  });
+  useLayoutEffect(() => {
+    if (value !== void 0) store.syncValue(value);
+  }, [store, value]);
+  useEffect(() => store.start(), [store]);
+  const keyDown = (event) => {
+    onKeyDown?.(event);
+    if (event.defaultPrevented) return;
+    if (event.nativeEvent.isComposing || event.keyCode === 229) return;
+    const navigator = createNavigator(context);
+    const key = event.key;
+    const vim = vimBindings && event.ctrlKey;
+    if (key === "ArrowDown" || vim && (key === "n" || key === "j")) {
+      event.preventDefault();
+      if (event.metaKey) navigator.last();
+      else if (event.altKey) navigator.group(1);
+      else navigator.step(1);
+    } else if (key === "ArrowUp" || vim && (key === "p" || key === "k")) {
+      event.preventDefault();
+      if (event.metaKey) navigator.first();
+      else if (event.altKey) navigator.group(-1);
+      else navigator.step(-1);
+    } else if (key === "Home") {
+      event.preventDefault();
+      navigator.first();
+    } else if (key === "End") {
+      event.preventDefault();
+      navigator.last();
+    } else if (key === "Enter") {
+      event.preventDefault();
+      const id = navigator.selected()?.id;
+      if (id) store.select(id);
+    }
+  };
+  return /* @__PURE__ */ jsx(CommandContext.Provider, { value: context, children: /* @__PURE__ */ jsxs("div", { tabIndex: -1, "data-ui-command": "", ...props, ref: composedRef, onKeyDown: keyDown, children: [
+    /* @__PURE__ */ jsx("label", { htmlFor: inputId, id: labelId, style: srOnly, children: label }),
+    /* @__PURE__ */ jsx(Effects, {}),
+    children
+  ] }) });
+}
+function Effects() {
+  const { store, rootRef } = useCommandContext("Root");
+  const revision = useSyncExternalStore(store.subscribe, store.getRevision, store.getRevision);
+  useLayoutEffect(() => {
+    store.sort();
+    const root = rootRef.current;
+    if (!root) return;
+    const searchChanged = store.consumeSearchChange();
+    const enabled = [...root.querySelectorAll(ENABLED_ITEM)];
+    const current = store.getState().value;
+    const stillValid = enabled.some((item) => item.dataset.value === current);
+    if (searchChanged || !stillValid) {
+      const first = enabled[0]?.dataset.value ?? "";
+      if (first !== current) store.setValue(first);
+    }
+  }, [revision, store, rootRef]);
+  return null;
+}
+function createNavigator({ store, rootRef, loop }) {
+  const root = () => rootRef.current;
+  const enabled = () => [...root()?.querySelectorAll(ENABLED_ITEM) ?? []];
+  const selected = () => root()?.querySelector(`${ITEM}[data-selected="true"]`) ?? null;
+  const go = (item) => {
+    if (!item) return;
+    store.setValue(item.dataset.value ?? "");
+    const group = item.closest(GROUP);
+    const firstInGroup = group?.querySelector(ENABLED_ITEM) === item;
+    const heading = firstInGroup ? group?.querySelector(GROUP_HEADING) : null;
+    (heading ?? item).scrollIntoView({ block: "nearest" });
+  };
+  return {
+    selected,
+    first: () => go(enabled()[0]),
+    last: () => go(enabled().at(-1)),
+    step(direction) {
+      const items = enabled();
+      if (items.length === 0) return;
+      const current = selected();
+      const index = current ? items.indexOf(current) : -1;
+      let next = index === -1 ? direction === 1 ? 0 : items.length - 1 : index + direction;
+      if (next < 0 || next >= items.length) {
+        next = loop ? (next + items.length) % items.length : Math.min(Math.max(next, 0), items.length - 1);
+      }
+      go(items[next]);
+    },
+    group(direction) {
+      const items = enabled();
+      const current = selected();
+      const groups = [...new Set(items.map((item) => item.closest(GROUP)))];
+      const index = groups.indexOf(current?.closest(GROUP) ?? null);
+      let next = index + direction;
+      if (next < 0 || next >= groups.length) {
+        if (!loop) return;
+        next = (next + groups.length) % groups.length;
+      }
+      go(items.find((item) => item.closest(GROUP) === groups[next]));
+    }
+  };
+}
+function Input({ value, onValueChange, onKeyDown, ref, ...props }) {
+  const { store, listId, inputId, labelId } = useCommandContext("Input");
+  const inDialog = useContext(InDialogContext);
+  const search = useSyncExternalStore(
+    store.subscribe,
+    () => store.getState().search,
+    () => store.getState().search
+  );
+  const activeId = useSyncExternalStore(
+    store.subscribe,
+    () => store.activeId(),
+    () => void 0
+  );
+  useLayoutEffect(() => {
+    if (value !== void 0) store.setSearch(value);
+  }, [store, value]);
+  const change = (next) => {
+    if (value === void 0) store.setSearch(next);
+    onValueChange?.(next);
+  };
+  const [released, setReleased] = useState(false);
+  useEffect(() => setReleased(false), [search]);
+  const claimsEscape = !inDialog && search !== "" && !released;
+  return /* @__PURE__ */ jsx(
+    "input",
+    {
+      id: inputId,
+      type: "text",
+      autoComplete: "off",
+      autoCorrect: "off",
+      spellCheck: false,
+      role: "combobox",
+      "aria-expanded": true,
+      "aria-autocomplete": "list",
+      "aria-controls": listId,
+      "aria-labelledby": labelId,
+      "aria-activedescendant": activeId,
+      "data-ui-command-input": "",
+      "data-ui-escape-claim": claimsEscape ? "" : void 0,
+      ...props,
+      ref,
+      value: search,
+      onChange: (event) => change(event.target.value),
+      onKeyDown: composeHandlers(onKeyDown, (event) => {
+        if (event.key === "Escape" && claimsEscape && !event.nativeEvent.isComposing) {
+          event.preventDefault();
+          const before = store.getState().search;
+          change("");
+          setTimeout(() => {
+            if (store.getState().search === before) setReleased(true);
+          }, 0);
+        }
+      })
+    }
+  );
+}
+function List({ label = "Suggestions", children, ref, ...props }) {
+  const { listId } = useCommandContext("List");
+  const listRef = useRef(null);
+  const sizerRef = useRef(null);
+  const composedRef = useComposedRefs(ref, listRef);
+  useEffect(() => {
+    const list = listRef.current;
+    const sizer = sizerRef.current;
+    if (!list || !sizer || typeof ResizeObserver === "undefined") return;
+    const update = () => list.style.setProperty("--ui-command-list-height", `${sizer.offsetHeight.toFixed(1)}px`);
+    const observer = new ResizeObserver(update);
+    observer.observe(sizer);
+    update();
+    return () => observer.disconnect();
+  }, []);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      id: listId,
+      role: "listbox",
+      "aria-label": label,
+      "data-ui-command-list": "",
+      ...props,
+      ref: composedRef,
+      children: /* @__PURE__ */ jsx("div", { ref: sizerRef, "data-ui-command-list-sizer": "", children })
+    }
+  );
+}
+function Item({
+  value: valueProp,
+  keywords,
+  disabled = false,
+  onSelect,
+  forceMount = false,
+  onClick,
+  onPointerMove,
+  children,
+  ref,
+  ...props
+}) {
+  const { store } = useCommandContext("Item");
+  const group = useContext(GroupContext);
+  const id = useId();
+  const elementRef = useRef(null);
+  const [derived, setDerived] = useState(null);
+  const value = valueProp !== void 0 ? valueProp.trim() : derived ?? "";
+  const measuring = valueProp === void 0 && derived === null;
+  const onSelectRef = useRef(onSelect);
+  const keywordsKey = keywords?.join("
") ?? "";
+  const groupId = group?.id;
+  const visible = useSyncExternalStore(
+    store.subscribe,
+    () => forceMount || store.isItemVisible(id),
+    () => true
+  );
+  const selected = useSyncExternalStore(
+    store.subscribe,
+    () => {
+      const current = store.getState().value;
+      return current !== "" && current === store.itemValue(id);
+    },
+    () => false
+  );
+  useLayoutEffect(() => {
+    onSelectRef.current = onSelect;
+  });
+  useLayoutEffect(() => {
+    if (valueProp === void 0) setDerived(elementRef.current?.textContent?.trim() ?? "");
+  });
+  useLayoutEffect(() => () => store.removeItem(id), [store, id]);
+  useLayoutEffect(() => {
+    store.upsertItem(
+      id,
+      {
+        value,
+        keywords: keywords ?? [],
+        groupId,
+        forceMount,
+        onSelect: () => onSelectRef.current?.(value)
+      },
+      elementRef.current
+    );
+  }, [store, id, value, keywordsKey, groupId, forceMount]);
+  const composedRef = useComposedRefs(
+    ref,
+    elementRef,
+    (node) => store.setItemElement(id, node)
+  );
+  if (!visible && !measuring) return null;
+  return (
+    // biome-ignore lint/a11y/useFocusableInteractive lint/a11y/useKeyWithClickEvents: options are driven through aria-activedescendant and the root key handler
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        id,
+        role: "option",
+        "aria-selected": selected,
+        "aria-disabled": disabled || void 0,
+        "data-ui-command-item": "",
+        hidden: !visible || void 0,
+        "data-selected": selected,
+        "data-disabled": disabled ? "" : void 0,
+        "data-value": value,
+        ...props,
+        ref: composedRef,
+        onPointerMove: composeHandlers(onPointerMove, () => {
+          if (!disabled) store.setValue(value);
+        }),
+        onClick: composeHandlers(onClick, () => {
+          if (!disabled) onSelect?.(value);
+        }),
+        children
+      }
+    )
+  );
+}
+function Group({ heading, forceMount = false, children, ref, ...props }) {
+  const { store } = useCommandContext("Group");
+  const id = useId();
+  const headingId = useId();
+  const [scope] = useState(() => ({ id, forceMount }));
+  scope.forceMount = forceMount;
+  useLayoutEffect(() => {
+    store.upsertGroup(id);
+    return () => store.removeGroup(id);
+  }, [store, id]);
+  const visible = useSyncExternalStore(
+    store.subscribe,
+    () => store.isGroupVisible(id, forceMount),
+    () => true
+  );
+  const composedRef = useComposedRefs(
+    ref,
+    (node) => store.setGroupElement(id, node)
+  );
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      role: "presentation",
+      hidden: visible ? void 0 : true,
+      "data-ui-command-group": "",
+      ...props,
+      ref: composedRef,
+      children: [
+        heading ? /* @__PURE__ */ jsx("div", { "aria-hidden": "true", id: headingId, "data-ui-command-group-heading": "", children: heading }) : null,
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            role: "group",
+            "aria-labelledby": heading ? headingId : void 0,
+            "data-ui-command-group-items": "",
+            children: /* @__PURE__ */ jsx(GroupContext.Provider, { value: scope, children })
+          }
+        )
+      ]
+    }
+  );
+}
+function Separator({ alwaysRender = false, ...props }) {
+  const searching = useCommandState((state) => state.search !== "");
+  if (searching && !alwaysRender) return null;
+  return /* @__PURE__ */ jsx("div", { "aria-hidden": "true", "data-ui-command-separator": "", ...props });
+}
+function Empty(props) {
+  const { store } = useCommandContext("Empty");
+  const empty = useSyncExternalStore(
+    store.subscribe,
+    () => store.getRevision() > 0 && store.getState().filtered.count === 0,
+    () => false
+  );
+  if (!empty) return null;
+  return /* @__PURE__ */ jsx("div", { role: "presentation", "data-ui-command-empty": "", ...props });
+}
+function Loading({
+  progress,
+  label = "Loading...",
+  children,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      role: "progressbar",
+      "aria-valuenow": progress,
+      "aria-valuemin": 0,
+      "aria-valuemax": 100,
+      "aria-label": label,
+      "data-ui-command-loading": "",
+      ...props,
+      children: /* @__PURE__ */ jsx("div", { "aria-hidden": "true", children })
+    }
+  );
+}
+function Dialog({
+  open,
+  onOpenChange,
+  container,
+  overlayClassName,
+  contentClassName,
+  onOpenAutoFocus,
+  onCloseAutoFocus,
+  onEscapeKeyDown,
+  label,
+  children,
+  ...rootProps
+}) {
+  const rootLabel = label ?? "Command menu";
+  return /* @__PURE__ */ jsx(
+    DialogPrimitive.Root,
+    {
+      ...open !== void 0 ? { open } : {},
+      ...onOpenChange ? { onOpenChange } : {},
+      children: /* @__PURE__ */ jsxs(DialogPrimitive.Portal, { container, children: [
+        /* @__PURE__ */ jsx(DialogPrimitive.Overlay, { className: overlayClassName, "data-ui-command-overlay": "" }),
+        /* @__PURE__ */ jsx(
+          DialogPrimitive.Content,
+          {
+            "aria-label": rootLabel,
+            "aria-labelledby": void 0,
+            "aria-describedby": void 0,
+            className: contentClassName,
+            "data-ui-command-dialog": "",
+            ...onOpenAutoFocus ? { onOpenAutoFocus } : {},
+            ...onCloseAutoFocus ? { onCloseAutoFocus } : {},
+            ...onEscapeKeyDown ? { onEscapeKeyDown } : {},
+            children: /* @__PURE__ */ jsx(InDialogContext.Provider, { value: true, children: /* @__PURE__ */ jsx(Root, { label: rootLabel, ...rootProps, children }) })
+          }
+        )
+      ] })
+    }
+  );
+}
+export {
+  Dialog,
+  Empty,
+  Group,
+  Input,
+  Item,
+  List,
+  Loading,
+  Root,
+  Separator,
+  useCommandState
+};

package/dist/primitives/command/score.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Fuzzy scoring for command palettes. DOM-free and pure.
+ *
+ * A character-by-character matcher in the style of `command-score`: every character of
+ * the search must appear in order in the candidate. Matches that continue a run, start a
+ * word or follow a separator score higher; skipped characters, case mismatches and an
+ * incomplete tail cost a little. Returns 0 when the search cannot be matched, otherwise a
+ * number in (0, 1] where higher is better.
+ */
+/**
+ * Scores `search` against `value` plus optional `keywords`. An empty search matches
+ * everything with score 1.
+ */
+export declare function commandScore(value: string, search: string, keywords?: readonly string[]): number;
+export type CommandFilter = (value: string, search: string, keywords?: readonly string[]) => number;

package/dist/primitives/command/score.js

@@ -0,0 +1,73 @@
+const SCORE_CONTINUE_MATCH = 1;
+const SCORE_SPACE_WORD_JUMP = 0.9;
+const SCORE_NON_SPACE_WORD_JUMP = 0.8;
+const SCORE_CHARACTER_JUMP = 0.17;
+const SCORE_TRANSPOSITION = 0.1;
+const PENALTY_SKIPPED = 0.999;
+const PENALTY_CASE_MISMATCH = 0.9999;
+const PENALTY_NOT_COMPLETE = 0.99;
+const IS_GAP = /[\\/_+.#"@[({&]/;
+const COUNT_GAPS = /[\\/_+.#"@[({&]/g;
+const IS_SPACE = /[\s-]/;
+const COUNT_SPACE = /[\s-]/g;
+function normalise(text) {
+  return text.toLowerCase().replace(COUNT_SPACE, " ");
+}
+function scoreFrom(text, search, lowerText, lowerSearch, textIndex, searchIndex, memo) {
+  if (searchIndex === search.length) {
+    return textIndex === text.length ? SCORE_CONTINUE_MATCH : PENALTY_NOT_COMPLETE;
+  }
+  const key = textIndex * (search.length + 1) + searchIndex;
+  const cached = memo.get(key);
+  if (cached !== void 0) return cached;
+  const searchChar = lowerSearch.charAt(searchIndex);
+  let index = lowerText.indexOf(searchChar, textIndex);
+  let best = 0;
+  while (index >= 0) {
+    let score = scoreFrom(text, search, lowerText, lowerSearch, index + 1, searchIndex + 1, memo);
+    if (score > best) {
+      if (index === textIndex) {
+        score *= SCORE_CONTINUE_MATCH;
+      } else if (IS_GAP.test(text.charAt(index - 1))) {
+        score *= SCORE_NON_SPACE_WORD_JUMP;
+        const breaks = text.slice(textIndex, index - 1).match(COUNT_GAPS);
+        if (breaks && textIndex > 0) score *= PENALTY_SKIPPED ** breaks.length;
+      } else if (IS_SPACE.test(text.charAt(index - 1))) {
+        score *= SCORE_SPACE_WORD_JUMP;
+        const breaks = text.slice(textIndex, index - 1).match(COUNT_SPACE);
+        if (breaks && textIndex > 0) score *= PENALTY_SKIPPED ** breaks.length;
+      } else {
+        score *= SCORE_CHARACTER_JUMP;
+        if (textIndex > 0) score *= PENALTY_SKIPPED ** (index - textIndex);
+      }
+      if (text.charAt(index) !== search.charAt(searchIndex)) score *= PENALTY_CASE_MISMATCH;
+    }
+    const next = lowerSearch.charAt(searchIndex + 1);
+    const swapped = score < SCORE_TRANSPOSITION && lowerText.charAt(index - 1) === next;
+    const doubled = next === lowerSearch.charAt(searchIndex) && lowerText.charAt(index - 1) !== searchChar;
+    if (swapped || doubled) {
+      const transposed = scoreFrom(
+        text,
+        search,
+        lowerText,
+        lowerSearch,
+        index + 1,
+        searchIndex + 2,
+        memo
+      );
+      if (transposed * SCORE_TRANSPOSITION > score) score = transposed * SCORE_TRANSPOSITION;
+    }
+    if (score > best) best = score;
+    index = lowerText.indexOf(searchChar, index + 1);
+  }
+  memo.set(key, best);
+  return best;
+}
+function commandScore(value, search, keywords) {
+  if (search === "") return 1;
+  const text = keywords && keywords.length > 0 ? `${value} ${keywords.join(" ")}` : value;
+  return scoreFrom(text, search, normalise(text), normalise(search), 0, 0, /* @__PURE__ */ new Map());
+}
+export {
+  commandScore
+};

package/dist/primitives/command/store.d.ts

@@ -0,0 +1,89 @@
+import type { CommandFilter } from "./score.js";
+/** What `useCommandState` selectors receive. */
+export interface CommandState {
+    /** The search text. */
+    search: string;
+    /** The highlighted item's `value` (empty when nothing is highlighted). */
+    value: string;
+    /** Result of the last filter pass. */
+    filtered: {
+        /** Number of visible items. */
+        count: number;
+        /** Visible item ids mapped to their score. */
+        items: Map<string, number>;
+        /** Ids of the groups that have at least one visible item. */
+        groups: Set<string>;
+    };
+}
+interface ItemEntry {
+    value: string;
+    keywords: readonly string[];
+    groupId: string | undefined;
+    forceMount: boolean;
+    rank: number;
+    element: HTMLElement | null;
+    onSelect: (() => void) | undefined;
+}
+export interface StoreOptions {
+    shouldFilter: boolean;
+    filter: CommandFilter;
+    /** Controlled highlighted value; `undefined` while uncontrolled. */
+    controlledValue: string | undefined;
+    onValueChange: ((value: string) => void) | undefined;
+}
+type Listener = () => void;
+/**
+ * Framework-free state for one command menu. Items and groups register here; filtering
+ * runs once per change and each item subscribes only to the booleans it renders, so
+ * typing re-renders just the items whose visibility or highlight flips.
+ */
+export declare class CommandStore {
+    private state;
+    private listeners;
+    private items;
+    private groups;
+    private rank;
+    private dirty;
+    private searchDirty;
+    private ordered;
+    private revision;
+    options: StoreOptions;
+    constructor(options: StoreOptions);
+    subscribe: (listener: Listener) => () => void;
+    getState: () => CommandState;
+    /** Bumps whenever filtering or items change; drives DOM sorting and selection repair. */
+    getRevision: () => number;
+    private emit;
+    isItemVisible(id: string): boolean;
+    isGroupVisible(id: string, forceMount: boolean): boolean;
+    itemValue(id: string): string | undefined;
+    upsertItem(id: string, entry: Omit<ItemEntry, "rank" | "element">, element: HTMLElement | null): void;
+    removeItem(id: string): void;
+    /** Highlighted item's id, for `aria-activedescendant`. */
+    activeId(): string | undefined;
+    setItemElement(id: string, element: HTMLElement | null): void;
+    upsertGroup(id: string): void;
+    removeGroup(id: string): void;
+    /** Runs the first filter pass; marks the store ready so `Empty` can tell "no items yet" from "no match". */
+    start(): void;
+    /** Called from a ref callback, which runs before the group's layout effect: creates the entry. */
+    setGroupElement(id: string, element: HTMLElement | null): void;
+    /** Coalesces a burst of (un)registrations into one filter pass. */
+    private schedule;
+    private bump;
+    setSearch(search: string): void;
+    /** Refilters after `shouldFilter` or `filter` changed. */
+    refresh(): void;
+    /** Highlights `value`. Controlled owners hear about it through `onValueChange` only. */
+    setValue(value: string): void;
+    /** Mirrors a controlled `value` prop into the store. */
+    syncValue(value: string): void;
+    private refilter;
+    private groupBest;
+    /** Reorders the rendered items and groups by score, or back to registration order. */
+    sort(): void;
+    /** True once after each search change, so the highlight can jump to the first result. */
+    consumeSearchChange(): boolean;
+    select(id: string): void;
+}
+export {};