@jcsoftdev/ui 0.1.6 → 0.2.0

package/src/primitives/command/score.ts

@@ -0,0 +1,104 @@
+/**
+ * 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.
+ */
+
+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: string): string {
+  return text.toLowerCase().replace(COUNT_SPACE, " ");
+}
+
+function scoreFrom(
+  text: string,
+  search: string,
+  lowerText: string,
+  lowerSearch: string,
+  textIndex: number,
+  searchIndex: number,
+  memo: Map<number, number>,
+): number {
+  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 !== undefined) 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;
+}
+
+/**
+ * Scores `search` against `value` plus optional `keywords`. An empty search matches
+ * everything with score 1.
+ */
+export function commandScore(value: string, search: string, keywords?: readonly string[]): number {
+  if (search === "") return 1;
+  const text = keywords && keywords.length > 0 ? `${value} ${keywords.join(" ")}` : value;
+  return scoreFrom(text, search, normalise(text), normalise(search), 0, 0, new Map());
+}
+
+export type CommandFilter = (value: string, search: string, keywords?: readonly string[]) => number;

package/src/primitives/command/store.ts

@@ -0,0 +1,280 @@
+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;
+}
+
+interface GroupEntry {
+  rank: number;
+  element: HTMLElement | null;
+}
+
+export interface StoreOptions {
+  shouldFilter: boolean;
+  filter: CommandFilter;
+  /** Controlled highlighted value; `undefined` while uncontrolled. */
+  controlledValue: string | undefined;
+  onValueChange: ((value: string) => void) | undefined;
+}
+
+type Listener = () => void;
+
+/** Moves `entries` into the DOM slots they already occupy, in the order given. */
+function reorder(parent: Element, entries: HTMLElement[]) {
+  const current = [...parent.children].filter((child) => entries.includes(child as HTMLElement));
+  if (current.every((child, index) => child === entries[index])) return;
+  const markers = current.map((child) => {
+    const marker = document.createComment("");
+    parent.insertBefore(marker, child);
+    return marker;
+  });
+  entries.forEach((entry, index) => {
+    parent.insertBefore(entry, markers[index] ?? null);
+  });
+  for (const marker of markers) marker.remove();
+}
+
+/**
+ * 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 class CommandStore {
+  private state: CommandState = {
+    search: "",
+    value: "",
+    filtered: { count: 0, items: new Map(), groups: new Set() },
+  };
+  private listeners = new Set<Listener>();
+  private items = new Map<string, ItemEntry>();
+  private groups = new Map<string, GroupEntry>();
+  private rank = 0;
+  private dirty = false;
+  private searchDirty = false;
+  private ordered = false;
+  private revision = 0;
+  options: StoreOptions;
+
+  constructor(options: StoreOptions) {
+    this.options = options;
+  }
+
+  subscribe = (listener: Listener) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  getState = () => this.state;
+  /** Bumps whenever filtering or items change; drives DOM sorting and selection repair. */
+  getRevision = () => this.revision;
+
+  private emit() {
+    for (const listener of [...this.listeners]) listener();
+  }
+
+  isItemVisible(id: string): boolean {
+    const item = this.items.get(id);
+    if (item?.forceMount) return true;
+    const { search, filtered } = this.state;
+    if (!search || !this.options.shouldFilter) return true;
+    return (filtered.items.get(id) ?? 0) > 0;
+  }
+
+  isGroupVisible(id: string, forceMount: boolean): boolean {
+    if (forceMount) return true;
+    const { search, filtered } = this.state;
+    if (!search || !this.options.shouldFilter) return true;
+    return filtered.groups.has(id);
+  }
+
+  itemValue(id: string): string | undefined {
+    return this.items.get(id)?.value;
+  }
+
+  upsertItem(id: string, entry: Omit<ItemEntry, "rank" | "element">, element: HTMLElement | null) {
+    const existing = this.items.get(id);
+    this.items.set(id, {
+      ...entry,
+      rank: existing?.rank ?? this.rank++,
+      element: element ?? existing?.element ?? null,
+    });
+    this.schedule();
+  }
+
+  removeItem(id: string) {
+    this.items.delete(id);
+    this.schedule();
+  }
+
+  /** Highlighted item's id, for `aria-activedescendant`. */
+  activeId(): string | undefined {
+    const { value } = this.state;
+    if (value === "") return undefined;
+    for (const [id, item] of this.items) {
+      if (item.value === value && item.element?.isConnected && this.isItemVisible(id)) return id;
+    }
+    return undefined;
+  }
+
+  setItemElement(id: string, element: HTMLElement | null) {
+    const item = this.items.get(id);
+    if (item) item.element = element;
+  }
+
+  upsertGroup(id: string) {
+    if (!this.groups.has(id)) this.groups.set(id, { rank: this.rank++, element: null });
+  }
+
+  removeGroup(id: string) {
+    this.groups.delete(id);
+    this.schedule();
+  }
+
+  /** Runs the first filter pass; marks the store ready so `Empty` can tell "no items yet" from "no match". */
+  start() {
+    this.schedule();
+  }
+
+  /** Called from a ref callback, which runs before the group's layout effect: creates the entry. */
+  setGroupElement(id: string, element: HTMLElement | null) {
+    const group = this.groups.get(id);
+    if (group) group.element = element;
+    else if (element) this.groups.set(id, { rank: this.rank++, element });
+  }
+
+  /** Coalesces a burst of (un)registrations into one filter pass. */
+  private schedule() {
+    if (this.dirty) return;
+    this.dirty = true;
+    queueMicrotask(() => {
+      if (!this.dirty) return;
+      this.dirty = false;
+      this.refilter();
+      this.bump();
+    });
+  }
+
+  private bump() {
+    this.revision++;
+    this.emit();
+  }
+
+  setSearch(search: string) {
+    if (search === this.state.search) return;
+    this.state = { ...this.state, search };
+    this.searchDirty = true;
+    this.refilter();
+    this.bump();
+  }
+
+  /** Refilters after `shouldFilter` or `filter` changed. */
+  refresh() {
+    this.refilter();
+    this.bump();
+  }
+
+  /** Highlights `value`. Controlled owners hear about it through `onValueChange` only. */
+  setValue(value: string) {
+    if (value === this.state.value) return;
+    if (this.options.controlledValue === undefined) this.state = { ...this.state, value };
+    this.options.onValueChange?.(value);
+    this.emit();
+  }
+
+  /** Mirrors a controlled `value` prop into the store. */
+  syncValue(value: string) {
+    if (value === this.state.value) return;
+    this.state = { ...this.state, value };
+    this.emit();
+  }
+
+  private refilter() {
+    const { search } = this.state;
+    const { shouldFilter, filter } = this.options;
+    const scores = new Map<string, number>();
+    const groupBest = new Map<string, number>();
+    const filtering = shouldFilter && search !== "";
+    for (const [id, item] of this.items) {
+      const score = filtering ? filter(item.value, search, item.keywords) : 1;
+      if (score > 0) {
+        scores.set(id, score);
+        if (item.groupId !== undefined) {
+          groupBest.set(item.groupId, Math.max(groupBest.get(item.groupId) ?? 0, score));
+        }
+      }
+    }
+    this.state = {
+      ...this.state,
+      filtered: { count: scores.size, items: scores, groups: new Set(groupBest.keys()) },
+    };
+    this.groupBest = groupBest;
+  }
+
+  private groupBest = new Map<string, number>();
+
+  /** Reorders the rendered items and groups by score, or back to registration order. */
+  sort() {
+    const { search, filtered } = this.state;
+    const ranking = this.options.shouldFilter && search !== "";
+    if (!ranking && !this.ordered) return;
+    this.ordered = ranking;
+
+    const buckets = new Map<Element, { element: HTMLElement; score: number; rank: number }[]>();
+    const place = (element: HTMLElement | null, score: number, rank: number) => {
+      const parent = element?.parentElement;
+      if (!element || !parent) return;
+      const list = buckets.get(parent);
+      if (list) list.push({ element, score, rank });
+      else buckets.set(parent, [{ element, score, rank }]);
+    };
+    for (const [id, item] of this.items) {
+      place(item.element, filtered.items.get(id) ?? 0, item.rank);
+    }
+    for (const [id, group] of this.groups) {
+      place(group.element, this.groupBest.get(id) ?? 0, group.rank);
+    }
+    for (const [parent, list] of buckets) {
+      list.sort((a, b) => (ranking ? b.score - a.score : 0) || a.rank - b.rank);
+      reorder(
+        parent,
+        list.map((entry) => entry.element),
+      );
+    }
+  }
+
+  /** True once after each search change, so the highlight can jump to the first result. */
+  consumeSearchChange(): boolean {
+    const changed = this.searchDirty;
+    this.searchDirty = false;
+    return changed;
+  }
+
+  select(id: string) {
+    this.items.get(id)?.onSelect?.();
+  }
+}

package/src/primitives/dialog/dialog.tsx

@@ -0,0 +1,316 @@
+"use client";
+
+import {
+  type ComponentProps,
+  createContext,
+  type ReactNode,
+  type RefObject,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+} from "react";
+import { composeHandlers, useComposedRefs } from "../../utils/compose.js";
+import { Slot } from "../../utils/slot.js";
+import { useControllableState } from "../../utils/use-controllable-state.js";
+import { hideOthers } from "../hide-others.js";
+import { useEnabledPointerEvents } from "../pointer-events-lock.js";
+import { Portal } from "../portal.js";
+import { lockBodyScroll } from "../scroll-lock.js";
+import {
+  type FocusOutsideEvent,
+  type InteractOutsideEvent,
+  type PointerDownOutsideEvent,
+  useDismissableLayer,
+} from "../use-dismissable-layer.js";
+import { useFocusScope } from "../use-focus-scope.js";
+import { useLayer } from "../use-layer.js";
+import { usePresence } from "../use-presence.js";
+
+/**
+ * In-house modal dialog primitive (WAI-ARIA dialog pattern). Same part names and
+ * dismiss callbacks as the Radix dialog it replaced; `Dialog` and `Drawer` build on it.
+ */
+
+interface DialogContextValue {
+  open: boolean;
+  modal: boolean;
+  setOpen: (open: boolean) => void;
+  triggerRef: RefObject<HTMLElement | null>;
+  overlayRef: RefObject<HTMLElement | null>;
+  contentId: string;
+  titleId: string;
+  descriptionId: string;
+}
+
+const DialogContext = createContext<DialogContextValue | null>(null);
+
+function useDialogContext(part: string): DialogContextValue {
+  const context = useContext(DialogContext);
+  if (!context) throw new Error(`<${part}> must be rendered inside <Dialog>`);
+  return context;
+}
+
+function isProduction(): boolean {
+  return typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+}
+
+const stateOf = (open: boolean) => (open ? "open" : "closed");
+
+export interface DialogRootProps {
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Traps focus, hides the page and locks scroll while open. Defaults to true. */
+  modal?: boolean;
+  children?: ReactNode;
+}
+
+export function Root({
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  modal = true,
+  children,
+}: DialogRootProps) {
+  const [open, setOpen] = useControllableState({
+    prop: openProp,
+    defaultProp: defaultOpen,
+    onChange: onOpenChange,
+  });
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const overlayRef = useRef<HTMLElement | null>(null);
+  const contentId = useId();
+  const titleId = useId();
+  const descriptionId = useId();
+  const value = useMemo<DialogContextValue>(
+    () => ({
+      open,
+      modal,
+      setOpen,
+      triggerRef,
+      overlayRef,
+      contentId,
+      titleId,
+      descriptionId,
+    }),
+    [open, modal, setOpen, contentId, titleId, descriptionId],
+  );
+  return <DialogContext.Provider value={value}>{children}</DialogContext.Provider>;
+}
+
+type ButtonProps = ComponentProps<"button"> & { asChild?: boolean };
+
+export function Trigger({ asChild, onClick, ref, ...props }: ButtonProps) {
+  const context = useDialogContext("DialogTrigger");
+  const composedRef = useComposedRefs<HTMLButtonElement>(
+    ref,
+    context.triggerRef as RefObject<HTMLButtonElement | null>,
+  );
+  const Comp = asChild ? Slot : "button";
+  return (
+    <Comp
+      type={asChild ? undefined : "button"}
+      aria-haspopup="dialog"
+      aria-expanded={context.open}
+      aria-controls={context.open ? context.contentId : undefined}
+      data-state={stateOf(context.open)}
+      {...props}
+      ref={composedRef as never}
+      onClick={composeHandlers(onClick, () => context.setOpen(!context.open))}
+    />
+  );
+}
+
+export function Close({ asChild, onClick, ...props }: ButtonProps) {
+  const context = useDialogContext("DialogClose");
+  const Comp = asChild ? Slot : "button";
+  return (
+    <Comp
+      type={asChild ? undefined : "button"}
+      {...props}
+      onClick={composeHandlers(onClick, () => context.setOpen(false))}
+    />
+  );
+}
+
+export function Title({ asChild, ...props }: ComponentProps<"h2"> & { asChild?: boolean }) {
+  const { titleId } = useDialogContext("DialogTitle");
+  const Comp = asChild ? Slot : "h2";
+  return <Comp id={titleId} {...props} />;
+}
+
+export function Description({ asChild, ...props }: ComponentProps<"p"> & { asChild?: boolean }) {
+  const { descriptionId } = useDialogContext("DialogDescription");
+  const Comp = asChild ? Slot : "p";
+  return <Comp id={descriptionId} {...props} />;
+}
+
+export { Portal };
+
+export interface DialogOverlayProps extends ComponentProps<"div"> {
+  forceMount?: boolean;
+}
+
+export function Overlay({ forceMount, ref, ...props }: DialogOverlayProps) {
+  const { open, modal, overlayRef } = useDialogContext("DialogOverlay");
+  const present = modal && (forceMount || open);
+  const composedRef = useComposedRefs<HTMLDivElement>(
+    ref,
+    overlayRef as RefObject<HTMLDivElement | null>,
+  );
+  const mounted = usePresence(present, overlayRef);
+  useEnabledPointerEvents(overlayRef, mounted);
+  if (!mounted) return null;
+  return <div data-state={stateOf(open)} aria-hidden="true" {...props} ref={composedRef} />;
+}
+
+export interface DialogContentProps extends Omit<ComponentProps<"div">, "onFocus"> {
+  forceMount?: boolean;
+  onOpenAutoFocus?: (event: Event) => void;
+  onCloseAutoFocus?: (event: Event) => void;
+  onEscapeKeyDown?: (event: KeyboardEvent) => void;
+  onPointerDownOutside?: (event: PointerDownOutsideEvent) => void;
+  onFocusOutside?: (event: FocusOutsideEvent) => void;
+  onInteractOutside?: (event: InteractOutsideEvent) => void;
+}
+
+export function Content({ forceMount, ref, ...props }: DialogContentProps) {
+  const context = useDialogContext("DialogContent");
+  const nodeRef = useRef<HTMLDivElement | null>(null);
+  const composedRef = useComposedRefs<HTMLDivElement>(ref, nodeRef);
+  const mounted = usePresence(forceMount || context.open, nodeRef);
+  if (!mounted) return null;
+  return (
+    <ContentImpl
+      {...props}
+      ref={composedRef}
+      nodeRef={nodeRef}
+      engaged={context.open || !forceMount}
+    />
+  );
+}
+
+interface ContentImplProps extends Omit<DialogContentProps, "forceMount"> {
+  nodeRef: RefObject<HTMLDivElement | null>;
+  /** False only for a force-mounted content that is currently closed. */
+  engaged: boolean;
+}
+
+function ContentImpl({
+  nodeRef,
+  engaged,
+  onOpenAutoFocus,
+  onCloseAutoFocus,
+  onEscapeKeyDown,
+  onPointerDownOutside,
+  onFocusOutside,
+  onInteractOutside,
+  onPointerDownCapture,
+  onFocusCapture,
+  onBlurCapture,
+  ...props
+}: ContentImplProps) {
+  const context = useDialogContext("DialogContent");
+  const { open, modal, setOpen, triggerRef, overlayRef } = context;
+  const listening = open && engaged;
+  const isTop = useLayer(listening);
+  const interactedOutside = useRef(false);
+  const focusInTree = useRef<() => boolean>(() => false);
+
+  useEffect(() => {
+    if (listening) interactedOutside.current = false;
+  }, [listening]);
+
+  useEffect(() => {
+    if (!engaged || !modal) return;
+    const unlock = lockBodyScroll();
+    const show = hideOthers([nodeRef.current, overlayRef.current]);
+    return () => {
+      show();
+      unlock();
+    };
+  }, [engaged, modal, nodeRef, overlayRef]);
+
+  useFocusScope({
+    ref: nodeRef,
+    active: engaged,
+    trapped: modal && open,
+    isTop,
+    // Portaled React children (menus, popovers) own focus while they are open.
+    allowFocus: () => focusInTree.current(),
+    onMountAutoFocus: onOpenAutoFocus,
+    onUnmountAutoFocus: (event) => {
+      onCloseAutoFocus?.(event);
+      if (event.defaultPrevented) return;
+      // A non-modal dialog closed by pressing elsewhere leaves focus where the user put it.
+      if (!modal && interactedOutside.current) {
+        event.preventDefault();
+        return;
+      }
+      const trigger = triggerRef.current;
+      if (trigger && document.contains(trigger)) {
+        event.preventDefault();
+        trigger.focus({ preventScroll: true });
+      }
+    },
+  });
+
+  const layerProps = useDismissableLayer({
+    ref: nodeRef,
+    active: listening,
+    isTop,
+    onEscapeKeyDown,
+    onPointerDownOutside: (event) => {
+      onPointerDownOutside?.(event);
+      const original = event.detail.originalEvent;
+      const contextClick = original.button === 2 || (original.button === 0 && original.ctrlKey);
+      if (modal && contextClick) event.preventDefault();
+    },
+    onFocusOutside: (event) => {
+      onFocusOutside?.(event);
+      // A modal traps focus, so a stray focus event must not close it.
+      if (modal) event.preventDefault();
+    },
+    onInteractOutside: (event) => {
+      onInteractOutside?.(event);
+      const target = event.detail.originalEvent.target as Node | null;
+      if (!modal && target && triggerRef.current?.contains(target)) event.preventDefault();
+      if (!event.defaultPrevented) interactedOutside.current = true;
+    },
+    onDismiss: () => setOpen(false),
+  });
+
+  focusInTree.current = layerProps.isFocusInTree;
+
+  const ariaLabel = props["aria-label"];
+  const ariaLabelledBy = props["aria-labelledby"];
+  // Like Radix, the ids are always rendered so the name and description exist from the
+  // first focusin once Title/Description mount. A dangling reference is ignored by
+  // assistive tech; pass `aria-describedby={undefined}` (or your own id) to opt out.
+  useEffect(() => {
+    if (isProduction() || !engaged) return;
+    if (!ariaLabel && !ariaLabelledBy && !document.getElementById(context.titleId)) {
+      console.error(
+        "DialogContent requires a DialogTitle (or an aria-label) so screen readers can name the dialog.",
+      );
+    }
+  }, [engaged, context.titleId, ariaLabel, ariaLabelledBy]);
+
+  return (
+    <div
+      id={context.contentId}
+      role="dialog"
+      aria-modal={modal ? true : undefined}
+      aria-labelledby={context.titleId}
+      aria-describedby={context.descriptionId}
+      data-state={stateOf(open)}
+      tabIndex={-1}
+      {...props}
+      onPointerDownCapture={composeHandlers(onPointerDownCapture, layerProps.onPointerDownCapture)}
+      onFocusCapture={composeHandlers(onFocusCapture, layerProps.onFocusCapture)}
+      onBlurCapture={composeHandlers(onBlurCapture, layerProps.onBlurCapture)}
+    />
+  );
+}