fancy-ui-react 0.2.0

package/dist/components/combobox/Combobox.js

@@ -0,0 +1,248 @@
+"use client";
+import { jsxs, Fragment, jsx } from "react/jsx-runtime";
+import { forwardRef, useState, useRef, useCallback, useMemo, useEffect, useSyncExternalStore } from "react";
+import { cn } from "../../utils.js";
+import { useConstant } from "../../internals/dom/ssr.js";
+import { useComposedRefs } from "../../internals/dom/use-composed-refs.js";
+import { useElementRef } from "../../internals/dom/use-element-ref.js";
+import { useEventCallback } from "../../internals/dom/use-event-callback.js";
+import { useLiveRef } from "../../internals/dom/use-live-ref.js";
+import { useField } from "../../internals/field.js";
+import { createListbox } from "../../internals/listbox.js";
+import { useFancyId } from "../../internals/use-id.js";
+import { useSoundCue } from "../../sound/use-sound.js";
+import { ComboboxPanel } from "./ComboboxPanel.js";
+import { defaultFilter } from "./match.js";
+import { COMBOBOX_KEY } from "./types.js";
+/* empty css             */
+function findOption(options, val) {
+  return options.find((o) => o.value === val);
+}
+function computeFilteredOptions(options, value, filter, q) {
+  const selectedLabel = findOption(options, value)?.label ?? "";
+  if (q === selectedLabel) return options;
+  return options.filter((o) => filter ? filter(o, q) : defaultFilter(o.label, q));
+}
+const activeIndexServerSnapshot = () => -1;
+const Combobox = forwardRef(function Combobox2({
+  options,
+  value: valueProp,
+  onValueChange,
+  placeholder,
+  disabled = false,
+  required = false,
+  invalid = false,
+  id,
+  name,
+  label,
+  filter,
+  emptyMessage = "No results",
+  className,
+  sound = false
+}, forwardedRef) {
+  const field = useField();
+  const uid = useFancyId();
+  const effectiveId = field?.controlId ?? id ?? `${uid}-input`;
+  const effectiveDisabled = field?.disabled ?? disabled;
+  const effectiveRequired = field?.required ?? required;
+  const effectiveInvalid = field?.invalid ?? invalid;
+  const panelId = `${uid}-listbox`;
+  const playCue = useSoundCue(sound);
+  const [value, setValueState] = useState(valueProp ?? "");
+  const [lastValueProp, setLastValueProp] = useState(valueProp);
+  if (lastValueProp !== valueProp) {
+    setLastValueProp(valueProp);
+    setValueState(valueProp ?? "");
+  }
+  const [query, setQueryState] = useState(() => findOption(options, value)?.label ?? "");
+  const queryRef = useRef(query);
+  const setQuery = useCallback((next) => {
+    queryRef.current = next;
+    setQueryState(next);
+  }, []);
+  const [open, setOpen] = useState(false);
+  const filteredOptions = useMemo(
+    () => computeFilteredOptions(options, value, filter, query),
+    [options, value, filter, query]
+  );
+  const optionsRef = useLiveRef(options);
+  const valueRef = useLiveRef(value);
+  const filterRef = useLiveRef(filter);
+  const listbox = useConstant(
+    () => createListbox({
+      count: () => computeFilteredOptions(
+        optionsRef.current,
+        valueRef.current,
+        filterRef.current,
+        queryRef.current
+      ).length,
+      enabled: (i) => !computeFilteredOptions(
+        optionsRef.current,
+        valueRef.current,
+        filterRef.current,
+        queryRef.current
+      )[i]?.disabled,
+      loop: true
+    })
+  );
+  useEffect(() => () => listbox.destroy(), [listbox]);
+  const getActiveIndex = useCallback(() => listbox.activeIndex, [listbox]);
+  const activeIndex = useSyncExternalStore(
+    listbox.subscribe,
+    getActiveIndex,
+    activeIndexServerSnapshot
+  );
+  useEffect(() => {
+    setQuery(findOption(optionsRef.current, value)?.label ?? "");
+  }, [value, optionsRef, setQuery]);
+  const [inputNode, setInputNode] = useElementRef();
+  const inputRef = useComposedRefs(setInputNode, forwardedRef);
+  const optionId = useCallback((index) => `${panelId}-option-${index}`, [panelId]);
+  function openPanel() {
+    if (effectiveDisabled) return;
+    setOpen(true);
+    const selectedIndex = filteredOptions.findIndex((o) => o.value === value);
+    listbox.setActive(selectedIndex >= 0 ? selectedIndex : filteredOptions.length > 0 ? 0 : -1);
+  }
+  const selectOption = useEventCallback((option) => {
+    if (effectiveDisabled || option.disabled) return;
+    const changed = value !== option.value;
+    setValueState(option.value);
+    setQuery(option.label);
+    setOpen(false);
+    if (changed) playCue("select");
+    onValueChange?.(option.value);
+  });
+  const resolveAndClose = useEventCallback(() => {
+    if (!open) return;
+    setOpen(false);
+    setQuery(findOption(options, value)?.label ?? "");
+  });
+  function handleInput(event) {
+    if (effectiveDisabled) return;
+    setQuery(event.target.value);
+    setOpen(true);
+    listbox.moveToEdge("first");
+  }
+  function handleFocus() {
+    openPanel();
+  }
+  function handleBlur() {
+    resolveAndClose();
+  }
+  function handleKeydown(event) {
+    if (effectiveDisabled) return;
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        if (!open) {
+          openPanel();
+          return;
+        }
+        listbox.move(1);
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        if (!open) {
+          openPanel();
+          return;
+        }
+        listbox.move(-1);
+        break;
+      case "Home":
+        if (!open) return;
+        event.preventDefault();
+        listbox.moveToEdge("first");
+        break;
+      case "End":
+        if (!open) return;
+        event.preventDefault();
+        listbox.moveToEdge("last");
+        break;
+      case "Enter": {
+        if (!open) return;
+        const active = filteredOptions[listbox.activeIndex];
+        if (active) {
+          event.preventDefault();
+          selectOption(active);
+        }
+        break;
+      }
+    }
+  }
+  const isActive = useCallback((index) => index === activeIndex, [activeIndex]);
+  const context = useMemo(
+    () => ({
+      open,
+      panelId,
+      inputRef: inputNode,
+      options: filteredOptions,
+      query,
+      activeIndex,
+      emptyMessage,
+      optionId,
+      isActive,
+      selectOption,
+      close: resolveAndClose
+    }),
+    [
+      open,
+      panelId,
+      inputNode,
+      filteredOptions,
+      query,
+      activeIndex,
+      emptyMessage,
+      optionId,
+      isActive,
+      selectOption,
+      resolveAndClose
+    ]
+  );
+  const resultsMessage = filteredOptions.length === 1 ? "1 result" : `${filteredOptions.length} results`;
+  const classes = cn(
+    "ft-combobox w-full rounded-[8px] border border-input bg-background px-[12px] py-[9px] text-[13px] text-foreground transition-colors",
+    "placeholder:text-muted-foreground",
+    "focus-visible:outline-none",
+    "disabled:cursor-not-allowed disabled:opacity-50",
+    effectiveInvalid && "border-destructive/50",
+    className
+  );
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs("div", { className: "ft-combobox-wrapper relative", children: [
+      /* @__PURE__ */ jsx(
+        "input",
+        {
+          ref: inputRef,
+          type: "text",
+          role: "combobox",
+          id: effectiveId,
+          placeholder,
+          value: query,
+          disabled: effectiveDisabled,
+          required: effectiveRequired,
+          "aria-invalid": effectiveInvalid ? "true" : void 0,
+          "aria-describedby": field?.describedBy,
+          "aria-label": field?.labelId ? void 0 : label,
+          "aria-expanded": open,
+          "aria-haspopup": "listbox",
+          "aria-autocomplete": "list",
+          "aria-controls": open ? panelId : void 0,
+          "aria-activedescendant": open && activeIndex >= 0 ? optionId(activeIndex) : void 0,
+          className: classes,
+          onChange: handleInput,
+          onFocus: handleFocus,
+          onBlur: handleBlur,
+          onKeyDown: handleKeydown
+        }
+      ),
+      name ? /* @__PURE__ */ jsx("input", { type: "hidden", name, value, disabled: effectiveDisabled }) : null,
+      /* @__PURE__ */ jsx("div", { className: "sr-only", role: "status", "aria-live": "polite", children: open ? resultsMessage : "" })
+    ] }),
+    /* @__PURE__ */ jsx(COMBOBOX_KEY.Provider, { value: context, children: /* @__PURE__ */ jsx(ComboboxPanel, {}) })
+  ] });
+});
+Combobox.displayName = "Combobox";
+export {
+  Combobox
+};

package/dist/components/combobox/ComboboxPanel.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The portalled listbox panel.
+ *
+ * A `<div role="listbox">`, not a `<ul>` — its rows are real `<button>`s
+ * (role="option" overrides the native semantics for assistive tech), and a
+ * `<button>` is not a permitted child of `<ul>`.
+ *
+ * No focus trap: focus never leaves the input for this pattern
+ * (`aria-activedescendant` tracks the active row instead), so there is
+ * nothing to move focus into or return it from. Each row is a real button so
+ * it stays natively keyboard-operable and the a11y linter is right to ask
+ * for one, but `tabindex="-1"` keeps it out of the tab sequence — the input
+ * is the only stop — and `onMouseDown` calls `preventDefault()` so the
+ * pointer's own focus-on-mousedown never fires before the row's own
+ * `onClick` runs: without it, clicking a row would blur the input a beat
+ * before selecting anything.
+ *
+ * It arrives and leaves on ONE bidirectional transition, never a split
+ * in/out pair: one leg handed the in-flight counterpart's current position
+ * means a panel reopened mid-exit continues from where it is instead of
+ * snapping to invisible first. `entering` is what tells it which way it is
+ * going, and it comes from the presence clock rather than the transition's
+ * own direction.
+ */
+export declare function ComboboxPanel(): import("react").JSX.Element;
+export declare namespace ComboboxPanel {
+    var displayName: string;
+}

package/dist/components/combobox/ComboboxPanel.js

@@ -0,0 +1,110 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useRef, Fragment } from "react";
+import { cn } from "../../utils.js";
+import { Portal } from "../../internals/Portal.js";
+import { useDismissable } from "../../internals/dismissable.js";
+import { useComposedRefs } from "../../internals/dom/use-composed-refs.js";
+import { useElementRef } from "../../internals/dom/use-element-ref.js";
+import { useAnchorPosition } from "../../internals/use-anchor-position.js";
+import { anchored, originFor } from "../../internals/motion/anchored.js";
+import { usePresence } from "../../internals/motion/presence.js";
+import { getMatchRange } from "./match.js";
+import { COMBOBOX_KEY } from "./types.js";
+function ComboboxPanel() {
+  const ctx = COMBOBOX_KEY.useRequired();
+  const [panel, setPanelNode] = useElementRef();
+  const { side: resolvedSide, align: resolvedAlign } = useAnchorPosition(panel, {
+    anchor: ctx.inputRef,
+    side: "bottom",
+    align: "start",
+    offset: 4
+  });
+  const presence = usePresence(ctx.open);
+  useDismissable(panel, {
+    onDismiss: ctx.close,
+    exclude: [ctx.inputRef],
+    active: ctx.open
+  });
+  const panelRef = useComposedRefs(
+    setPanelNode,
+    presence.register(anchored, (entering) => ({ side: resolvedSide, entering }))
+  );
+  const frozen = useRef({
+    options: ctx.options,
+    query: ctx.query,
+    activeIndex: ctx.activeIndex
+  });
+  if (ctx.open) {
+    frozen.current = { options: ctx.options, query: ctx.query, activeIndex: ctx.activeIndex };
+  }
+  const view = frozen.current;
+  return /* @__PURE__ */ jsx(Portal, { children: presence.mounted ? /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: panelRef,
+      id: ctx.panelId,
+      role: "listbox",
+      className: "ft-combobox-panel border-border bg-popover text-popover-foreground flex max-h-[260px] w-max min-w-[220px] flex-col gap-[1px] overflow-auto rounded-[10px] border p-[5px] text-[13px] shadow-lg outline-none",
+      "data-state": presence.surfaceState,
+      "data-side": resolvedSide,
+      "data-align": "start",
+      style: { transformOrigin: originFor(resolvedSide, resolvedAlign) },
+      children: view.options.length === 0 ? /* @__PURE__ */ jsx(
+        "div",
+        {
+          role: "presentation",
+          className: "ft-combobox-empty text-muted-foreground rounded-[6px] px-[10px] py-[7px]",
+          children: ctx.emptyMessage
+        }
+      ) : view.options.map((option, index) => {
+        const range = getMatchRange(option.label, view.query);
+        const isActive = index === view.activeIndex;
+        return (
+          /*
+          	`onMouseDown` below defends against a real browser's
+          	focus-follows-mousedown default action stealing focus onto this
+          	row before its own `onClick` commits — without it, that focus
+          	shift blurs the input first, which closes the panel (unmounting
+          	this row) before the click already in flight can land. jsdom
+          	implements no such default action to suppress, so no test in this
+          	repo can watch this guard prevent that outcome — only that the
+          	call happens (`Combobox.test.tsx`'s "the row's mousedown handler
+          	calls preventDefault" dispatches a bare `mousedown` and checks
+          	`event.defaultPrevented`). Do not delete this as dead code on the
+          	strength of a green suite.
+          */
+          /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              id: ctx.optionId(index),
+              role: "option",
+              tabIndex: -1,
+              disabled: option.disabled,
+              "aria-selected": isActive,
+              "aria-disabled": option.disabled ? "true" : void 0,
+              className: cn(
+                "ft-combobox-option w-full cursor-pointer rounded-[6px] px-[10px] py-[7px] text-left",
+                isActive && !option.disabled && "bg-accent text-accent-foreground",
+                option.disabled && "pointer-events-none opacity-50"
+              ),
+              onMouseDown: (event) => event.preventDefault(),
+              onClick: () => ctx.selectOption(option),
+              children: range ? /* @__PURE__ */ jsxs(Fragment, { children: [
+                option.label.slice(0, range.start),
+                /* @__PURE__ */ jsx("strong", { children: option.label.slice(range.start, range.end) }),
+                option.label.slice(range.end)
+              ] }) : option.label
+            },
+            option.value
+          )
+        );
+      })
+    }
+  ) : null });
+}
+ComboboxPanel.displayName = "ComboboxPanel";
+export {
+  ComboboxPanel
+};

package/dist/components/combobox/index.d.ts

@@ -0,0 +1,4 @@
+export { Combobox } from "./Combobox.js";
+export type { ComboboxProps, ComboboxOption } from "./Combobox.js";
+export { COMBOBOX_KEY } from "./types.js";
+export type { ComboboxContext } from "./types.js";

package/dist/components/combobox/match.d.ts

@@ -0,0 +1,15 @@
+export declare function defaultFilter(label: string, query: string): boolean;
+export interface MatchRange {
+    start: number;
+    end: number;
+}
+/**
+ * Finds the first case-insensitive occurrence of `query` inside `label`.
+ *
+ * Returns `null` when `query` is empty or not literally present in `label`
+ * — including when a custom `filter` matched the option for a reason
+ * unrelated to a literal substring (fuzzy matching, matching a different
+ * field entirely). Callers render the label plain in that case instead of
+ * fabricating a highlighted span.
+ */
+export declare function getMatchRange(label: string, query: string): MatchRange | null;

package/dist/components/combobox/match.js

@@ -0,0 +1,14 @@
+"use client";
+function defaultFilter(label, query) {
+  return label.toLowerCase().includes(query.toLowerCase());
+}
+function getMatchRange(label, query) {
+  if (!query) return null;
+  const index = label.toLowerCase().indexOf(query.toLowerCase());
+  if (index === -1) return null;
+  return { start: index, end: index + query.length };
+}
+export {
+  defaultFilter,
+  getMatchRange
+};

package/dist/components/combobox/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The contract between the Combobox root and its portalled listbox panel.
+ *
+ * Combobox is a **closed set**: `options` is the only vocabulary of valid
+ * values, and the root owns everything that decides which of them are
+ * currently visible, which is active for keyboard navigation, and how a
+ * click or Enter on a row resolves back into `value`. The panel only ever
+ * reads this and calls back into it — it never touches `value` or `query`
+ * directly, the same division a popover context draws between a root and its
+ * content.
+ */
+/** One selectable option. `value` is what `Combobox` reads and writes; `label` is what a person sees and types against. */
+export interface ComboboxOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+export interface ComboboxContext {
+    /** Whether the panel is open. Read by the panel's own exit transition to
+     *  tell an entrance from a departure — one bidirectional transition
+     *  cannot distinguish them on its own. Also the panel's dismissable
+     *  `active` gate: the instant this flips false the layer stops answering
+     *  Escape, so a second Escape during the fade reaches whatever is
+     *  underneath instead of being swallowed by a panel that is already
+     *  leaving. */
+    readonly open: boolean;
+    /** The panel's own id — also what the input's `aria-controls` points at while open. */
+    readonly panelId: string;
+    /** The real input element, once mounted — what the panel anchors against and excludes from outside-click dismissal. */
+    readonly inputRef: HTMLInputElement | null;
+    /** The options currently visible in the panel, already filtered by the current query. */
+    readonly options: ComboboxOption[];
+    /** The current query text, for computing each row's highlighted span. */
+    readonly query: string;
+    /** Index of the keyboard-active row within `options`, or -1 when none is active. */
+    readonly activeIndex: number;
+    /** Shown in place of the option list when `options` is empty. */
+    readonly emptyMessage: string;
+    /** The dom id a row at this index must carry, so `aria-activedescendant` can point at it. */
+    optionId(index: number): string;
+    /** Whether the row at this index is the keyboard-active one. */
+    isActive(index: number): boolean;
+    /** Commits `option` as the selection and closes the panel. No-ops for a disabled option. */
+    selectOption(option: ComboboxOption): void;
+    /** Closes the panel, resolving the query back to the current value's label (or clearing it). Routes Escape, outside click, and blur through the same rule. */
+    close(): void;
+}
+/**
+ * The context the root publishes to its panel.
+ *
+ * The Svelte source keys this on a `unique symbol` passed to
+ * `setContext`/`getContext`; React's own context object plays that role here,
+ * under the same name, because the Svelte `index.ts` exports the key — so it
+ * keeps its public identity on both sides.
+ *
+ * Read it with `COMBOBOX_KEY.useRequired()`: the panel is only ever rendered
+ * by the root, so a missing provider is a programming error rather than a
+ * degrade-gracefully case.
+ */
+export declare const COMBOBOX_KEY: import("../../internals/dom/context.js").InternalContext<ComboboxContext>;

package/dist/components/combobox/types.js

@@ -0,0 +1,6 @@
+"use client";
+import { createInternalContext } from "../../internals/dom/context.js";
+const COMBOBOX_KEY = createInternalContext("COMBOBOX_KEY");
+export {
+  COMBOBOX_KEY
+};

package/dist/components/command-menu/CommandMenu.d.ts

@@ -0,0 +1,37 @@
+import type { ReactNode } from "react";
+import type { CommandItem } from "./types.js";
+export type { CommandItem };
+export interface CommandMenuProps {
+    /** Whether the menu is open. Controlled when given; the component keeps its own copy either way. */
+    open?: boolean;
+    /** Fires whenever `open` changes, from Escape, an outside click, or committing an item. */
+    onOpenChange?: (open: boolean) => void;
+    /** The full, unfiltered vocabulary. */
+    items: CommandItem[];
+    /** The current search text. Controlled when given. Reset to `""` every time the menu reopens. */
+    query?: string;
+    /** Fires whenever `query` changes. */
+    onQueryChange?: (query: string) => void;
+    /** Called with the committed item — Enter on the active row, or a click. Fires after the item's own `onSelect`. */
+    onSelect?: (item: CommandItem) => void;
+    /** Placeholder for the search field. */
+    placeholder?: string;
+    /** Shown in place of the list when nothing matches. */
+    emptyMessage?: string;
+    /** Accessible name for the dialog (and its search field — see the README). */
+    label?: string;
+    /** Matches an item against the current query. Default: case- and diacritic-insensitive substring match on `label` plus `keywords`. */
+    filter?: (item: CommandItem, query: string) => boolean;
+    /** Additional CSS classes for the panel. */
+    className?: string;
+    /** Rendered before each row's label, given that row's item. Treated as decorative — see the README. */
+    icon?: (item: CommandItem) => ReactNode;
+    /** Rendered in place of the list when nothing matches, instead of `emptyMessage`. */
+    empty?: ReactNode;
+    /**
+     * Plays the matching interface cue through the sound controller. Off by
+     * default; only audible once the user has enabled sound.
+     */
+    sound?: boolean;
+}
+export declare const CommandMenu: import("react").ForwardRefExoticComponent<CommandMenuProps & import("react").RefAttributes<HTMLDivElement>>;