@eifi1/ui-kit 0.9.0 → 0.11.0

package/src/rhf/use-rhf-wizard-step.ts

@@ -0,0 +1,113 @@
+/**
+ * The bridge between a react-hook-form step and the wizard's Next gate.
+ * `@eifi1/ui-kit/rhf`.
+ *
+ * ```tsx
+ * function AddressStep({ onUpdate }: { onUpdate: (v: Address) => void }) {
+ *   const form = useForm<Address>({ defaultValues });
+ *   useRhfWizardStep(form, { onValid: onUpdate });
+ *   return <Form {...form}>…</Form>;
+ * }
+ * ```
+ *
+ * Inside a `<StepperNav>` the hook registers the step's validator with the wizard, so
+ * Next (and Finish on a form-bearing last step) runs it: on success the values go to
+ * `onValid` and the wizard advances; on failure react-hook-form shows its own inline
+ * `<FormMessage>`s, focuses the first field in error, and the wizard stays put — and,
+ * since the result carries no per-field errors, says its "fill in the required
+ * fields" line so the button did not seem to do nothing. It also RETURNS the
+ * validator, for a nav of your own outside `<StepperNav>` (where there is no wizard
+ * context to register with, so nothing is registered).
+ *
+ * Two modes:
+ *
+ *  - **The whole form** (no `fields`): `form.handleSubmit`, exactly as kastlan's
+ *    `use-rhf-wizard-step.ts` — every rule and the resolver run, `onValid` receives
+ *    the TRANSFORMED values (a zod `.transform()` included), and focus follows the
+ *    form's own `shouldFocusError` (on by default).
+ *  - **Some fields** (`fields: ["iban", "bic"]`): `form.trigger(fields)`, for a wizard
+ *    that keeps one form across several steps, each of which validates only what it
+ *    shows. The first of those fields in error is focused (`shouldFocus`; the control
+ *    has to take `field.ref`), errors on fields of later steps are not raised, and
+ *    `onValid` receives `form.getValues()` — the untransformed values, because a
+ *    resolver's output is only produced for the whole form.
+ *
+ * Both callbacks are read through refs, so the validator is registered once per form
+ * however the caller writes them (an inline `(v) => onUpdate(v)` is the usual case).
+ *
+ * The positional `useRhfWizardStep(form, onValid)` of the hook kastlan kept is the
+ * whole-form mode, and still accepted.
+ *
+ * Why it lives here and not in `@eifi1/ui-kit/wizard`: it imports react-hook-form,
+ * which only this entry may (see packaging-contract).
+ */
+import { useCallback, useEffect, useRef } from "react";
+import type { FieldPath, FieldValues, UseFormReturn } from "react-hook-form";
+import { useOptionalWizardContext } from "../wizard/wizard-context";
+
+export type RhfWizardStepOptions<
+  TFieldValues extends FieldValues,
+  TTransformed = TFieldValues,
+> =
+  | {
+      /** Validate only these fields — the step's share of a form that spans steps. */
+      fields: readonly FieldPath<TFieldValues>[];
+      /** Called with `form.getValues()` when the fields pass, before the wizard
+       *  advances. */
+      onValid?: (values: TFieldValues) => void;
+    }
+  | {
+      /** Omitted: validate the whole form through `handleSubmit`. */
+      fields?: undefined;
+      /** Called with the form's (transformed) values when it passes, before the
+       *  wizard advances. */
+      onValid?: (values: TTransformed) => void;
+    };
+
+/**
+ * Connects `form` to the wizard's step validation and returns the step's validator.
+ * See the module note for the two modes.
+ */
+export function useRhfWizardStep<
+  TFieldValues extends FieldValues,
+  TContext = unknown,
+  TTransformed = TFieldValues,
+>(
+  form: UseFormReturn<TFieldValues, TContext, TTransformed>,
+  options?:
+    | RhfWizardStepOptions<TFieldValues, TTransformed>
+    | ((values: TTransformed) => void),
+): () => Promise<boolean> {
+  const opts = typeof options === "function" ? { onValid: options } : (options ?? {});
+  const optsRef = useRef(opts);
+  useEffect(() => {
+    optsRef.current = opts;
+  });
+
+  const validate = useCallback(async (): Promise<boolean> => {
+    const current = optsRef.current;
+    if (current.fields) {
+      const ok = await form.trigger([...current.fields], { shouldFocus: true });
+      if (ok) current.onValid?.(form.getValues());
+      return ok;
+    }
+    const onValid = current.onValid as ((values: TTransformed) => void) | undefined;
+    let ok = false;
+    await form.handleSubmit(
+      (values) => {
+        ok = true;
+        onValid?.(values);
+      },
+      () => {
+        ok = false;
+      },
+    )();
+    return ok;
+  }, [form]);
+
+  const wizard = useOptionalWizardContext();
+  const register = wizard?.registerStepValidate;
+  useEffect(() => register?.(validate), [register, validate]);
+
+  return validate;
+}

package/src/rhf.ts

@@ -7,3 +7,5 @@
 // the barrel dropped its last react-hook-form import (see the wizard section of
 // src/index.ts). The packaging contract test holds that line.
 export * from "./rhf/form";
+// The react-hook-form bridge to the wizard's Next gate (useWizard lives in /wizard).
+export * from "./rhf/use-rhf-wizard-step";

package/src/search/command-palette.tsx

@@ -100,6 +100,18 @@ export const DEFAULT_COMMAND_PALETTE_LABELS: CommandPaletteLabels = {
   close: "Close",
 };
 
+/**
+ * How tall the palette's rows are. `"compact"` (the default) is the desktop list the
+ * palette always drew, 36px a row; `"comfortable"` gives every row the kit's 44px touch
+ * target (`min-h-11`) and body-size text — keksdose's phone search, where a 36px row
+ * under a thumb picks its neighbour.
+ */
+export type CommandPaletteDensity = "compact" | "comfortable";
+
+/** A provider's answer is a promise — the only case with anything to wait for. */
+const isThenable = (value: unknown): value is PromiseLike<unknown> =>
+  typeof (value as PromiseLike<unknown> | null)?.then === "function";
+
 /** The defaults minus `dialog`, so a resolved `dialog` means someone SUPPLIED one —
  *  see the dialog's `aria-label` for why that distinction matters. */
 const { dialog: DEFAULT_DIALOG_NAME, ...DEFAULTS_WITHOUT_DIALOG } = DEFAULT_COMMAND_PALETTE_LABELS;
@@ -112,6 +124,14 @@ interface CommandPaletteProps {
    * query is allowed — return defaults like pages/recent). Sync or async; stale
    * async responses are ignored.
    *
+   * A SYNCHRONOUS provider (one returning an array, not a promise) never shows the
+   * "Searching…" hint: its answer is there the moment it is asked, and the hint only
+   * flashed through the debounce before results that were never late — keksdose's
+   * transaction search filters a list already in memory. The palette tells the two
+   * apart by what the provider RETURNS, call by call, so there is no prop to keep in
+   * step with the implementation: an async provider shows the hint from the first
+   * promise on (and during the debounce of every later query), a sync one never.
+   *
    * Its IDENTITY is not a re-run signal — it is read through a ref, so the palette
    * never re-searches merely because the caller rebuilt the callback. That is
    * deliberate: a provider closing over a list rendered from a query allocates a new
@@ -175,6 +195,8 @@ interface CommandPaletteProps {
    * up. `false` keeps the card on every viewport.
    */
   fullScreenOnPhone?: boolean;
+  /** Row height — see {@link CommandPaletteDensity}. Default `"compact"`. */
+  density?: CommandPaletteDensity;
   labels?: Partial<CommandPaletteLabels>;
 }
 
@@ -208,6 +230,7 @@ export function CommandPalette({
   searchOn = "input",
   redactLabels = false,
   fullScreenOnPhone = true,
+  density = "compact",
   labels,
 }: CommandPaletteProps) {
   const l = useKitLabels("commandPalette", DEFAULTS_WITHOUT_DIALOG, labels);
@@ -259,6 +282,10 @@ export function CommandPalette({
   const searchRef = useRef(search);
   searchRef.current = search;
   const reqId = useRef(0);
+  /** What the provider's last answer was: a promise (`false`), an array (`true`), or
+   *  not known yet. Only a provider known to be async shows "Searching…" while the
+   *  debounce runs — see `search`. */
+  const syncRef = useRef<boolean | undefined>(undefined);
   /** The query the results on screen answer, and the row highlighted in them — so a
    *  re-run for the SAME query (a `revision` change: a source streaming in) keeps the
    *  highlight on its row instead of throwing it back to the top mid-arrow. */
@@ -295,10 +322,13 @@ export function CommandPalette({
   useEffect(() => {
     if (!open) return;
     const id = ++reqId.current;
-    setLoading(true);
+    if (syncRef.current === false) setLoading(true);
     const run = async () => {
       try {
-        const r = await Promise.resolve(searchRef.current(query));
+        const answer = searchRef.current(query);
+        syncRef.current = !isThenable(answer);
+        if (!syncRef.current) setLoading(true);
+        const r = await answer;
         if (reqId.current === id) {
           const keep = shownQuery.current === query ? activeIdRef.current : undefined;
           const at = keep === undefined ? -1 : groupItems(r).flat.findIndex((item) => item.id === keep);
@@ -366,11 +396,14 @@ export function CommandPalette({
   // Keep the active row scrolled into view.
   useEffect(() => {
     const el = listRef.current?.querySelector<HTMLElement>(`[data-index="${active}"]`);
-    el?.scrollIntoView({ block: "nearest" });
+    // Optional-called, as in combobox-core: jsdom has no scrollIntoView, and every
+    // consumer's tests crashed on the first highlighted row (kastlan stubbed it).
+    el?.scrollIntoView?.({ block: "nearest" });
   }, [active]);
 
   if (!open) return null;
 
+  const comfortable = density === "comfortable";
   let flatIndex = -1;
   return createPortal(
     <div
@@ -503,7 +536,10 @@ export function CommandPalette({
                       <li
                         key={item.id}
                         role="presentation"
-                        className="flex items-center gap-2.5 px-3 py-2 text-xs text-[var(--text-placeholder)]"
+                        className={cn(
+                          "flex items-center gap-2.5 px-3 text-xs text-[var(--text-placeholder)]",
+                          comfortable ? "min-h-11 py-2.5" : "py-2",
+                        )}
                       >
                         {item.icon && <span className="flex size-4 shrink-0 items-center justify-center">{item.icon}</span>}
                         <span className="min-w-0 flex-1 truncate">{item.label}</span>
@@ -525,7 +561,8 @@ export function CommandPalette({
                     "data-index": idx,
                     onMouseMove: () => setActive(idx),
                     className: cn(
-                      "flex w-full items-center gap-2.5 px-3 py-2 text-start text-sm",
+                      "flex w-full items-center gap-2.5 px-3 text-start",
+                      comfortable ? "min-h-11 py-2.5 text-base" : "py-2 text-sm",
                       isActive
                         ? "bg-[var(--bg-active)] text-[var(--text-primary)]"
                         : "text-[var(--text-secondary)]",

package/src/search/global-search.tsx

@@ -7,7 +7,7 @@ import { TOPBAR_TRIGGER_CLASS } from "../shell/topbar-controls";
 import { cn } from "../lib/cn";
 import { useKitLabels } from "../i18n/kit-labels";
 import { CommandPalette, DEFAULT_COMMAND_PALETTE_LABELS, useCommandKey } from "./command-palette";
-import type { CommandItem, CommandPaletteLabels } from "./command-palette";
+import type { CommandItem, CommandPaletteDensity, CommandPaletteLabels } from "./command-palette";
 import { createSearchIndex } from "./search-index";
 import type { SearchEntry, SearchIndexOptions } from "./search-index";
 
@@ -94,6 +94,14 @@ export interface GlobalSearchProps {
   sources?: readonly GlobalSearchSource[];
   /** What the empty query shows, under the `suggestions` heading. */
   suggestions?: readonly GlobalSearchSuggestion[];
+  /**
+   * Show each suggested ENTRY under its own `group` instead of all of them under the
+   * one `suggestions` heading — keksdose's empty palette listed "Pages" and "Actions"
+   * apart, and one "Try" heading over both lost the difference. An entry with no
+   * `group` and a query suggestion (`{ query }`) stay under `suggestions`. `groupOrder`
+   * orders these groups as it orders the results'. Off by default.
+   */
+  suggestionsKeepGroups?: boolean;
   /** Groups listed here come first, in this order; the rest follow in ranking order. */
   groupOrder?: readonly string[];
   /** Ranking and capping — `groupLimit` (default 8) applies to every group. */
@@ -130,6 +138,23 @@ export interface GlobalSearchProps {
   hideTriggerOnPhone?: boolean;
   /** Class for the default trigger button, merged over `TOPBAR_TRIGGER_CLASS`. */
   triggerClassName?: string;
+  /**
+   * The default trigger's magnifier, in px. Default 16 (`size-4`), as it always was;
+   * 20 matches the kit's other top-bar triggers (`TopbarIconButton` draws `size-5`) and
+   * keksdose's top bar, which reached into the button with `[&_svg]:size-5` for it.
+   */
+  triggerIconSize?: number;
+  /**
+   * Whether the trigger's accessible name includes the shortcut: `"plain"` (default)
+   * names it "Search"; `"withShortcut"` names it by `labels.shortcut(keys)` —
+   * "Search (⌘K)" on Apple platforms, "Search (Ctrl K)" elsewhere — the same text its
+   * tooltip shows, so a speech-control user ("click Search") and a sighted keyboard user
+   * meet the shortcut in the name itself (keksdose C25). `aria-keyshortcuts` is set
+   * either way. Also reaches a custom trigger as `triggerProps.label`.
+   */
+  triggerName?: "plain" | "withShortcut";
+  /** The palette's row height — `CommandPalette`'s `density`. Default `"compact"`. */
+  density?: CommandPaletteDensity;
   labels?: Partial<GlobalSearchLabels>;
   /** Passed through to the palette (`empty`, `loading`, `error`, `hint`, …). */
   paletteLabels?: Partial<CommandPaletteLabels>;
@@ -211,6 +236,7 @@ function GlobalSearchImpl({
   entries,
   sources,
   suggestions,
+  suggestionsKeepGroups = false,
   groupOrder,
   indexOptions,
   navigate,
@@ -226,6 +252,9 @@ function GlobalSearchImpl({
   trigger = "button",
   hideTriggerOnPhone = false,
   triggerClassName,
+  triggerIconSize,
+  triggerName = "plain",
+  density,
   labels,
   paletteLabels,
 }: GlobalSearchProps & { navigate: (href: string) => void; hrefFor: (href: string) => string }) {
@@ -360,12 +389,27 @@ function GlobalSearchImpl({
   // which the compiler lint cannot tell from a read during render.
   /* eslint-disable react-hooks/refs */
   const items = useMemo((): CommandItem[] => {
+    const ordered = (out: CommandItem[]) => {
+      if (!order.length) return out;
+      const rank = (group: string) => {
+        const i = order.indexOf(group);
+        return i === -1 ? order.length : i;
+      };
+      // Stable: within a rank, groups keep the order their best hit gave them.
+      return out
+        .map((item, i) => ({ item, i }))
+        .sort((a, b) => rank(a.item.group) - rank(b.item.group) || a.i - b.i)
+        .map(({ item }) => item);
+    };
+
     if (!q) {
       const out: CommandItem[] = [];
+      const groupOf = (entry: SearchEntry) =>
+        suggestionsKeepGroups ? (entry.group ?? l.suggestions) : l.suggestions;
       suggestionList.forEach((s, i) => {
         if (typeof s === "string") {
           const entry = byId.get(s);
-          if (entry) out.push(toItem("try:", entry, l.suggestions));
+          if (entry) out.push(toItem("try:", entry, groupOf(entry)));
         } else if ("query" in s) {
           out.push({
             id: `try:q${i}`,
@@ -380,9 +424,10 @@ function GlobalSearchImpl({
               refocusField();
             },
           });
-        } else out.push(toItem("try:", s, l.suggestions));
+        } else out.push(toItem("try:", s, groupOf(s)));
       });
-      return out;
+      // One heading has nothing to order; kept groups are ordered like results.
+      return suggestionsKeepGroups ? ordered(out) : out;
     }
 
     const out = index.search(q).map((hit) => toItem("s:", hit.entry, hit.entry.group ?? l.results));
@@ -410,17 +455,8 @@ function GlobalSearchImpl({
       }
     }
 
-    if (!order.length) return out;
-    const rank = (group: string) => {
-      const i = order.indexOf(group);
-      return i === -1 ? order.length : i;
-    };
-    // Stable: within a rank, groups keep the order their best hit gave them.
-    return out
-      .map((item, i) => ({ item, i }))
-      .sort((a, b) => rank(a.item.group) - rank(b.item.group) || a.i - b.i)
-      .map(({ item }) => item);
-  }, [q, suggestionList, byId, index, sourceList, sourceResults, order, groupLimit, toItem, l.suggestions, l.results, pl.loading, pl.error, setOpen, setQuery, noop, redactLabels]);
+    return ordered(out);
+  }, [q, suggestionList, suggestionsKeepGroups, byId, index, sourceList, sourceResults, order, groupLimit, toItem, l.suggestions, l.results, pl.loading, pl.error, setOpen, setQuery, noop, redactLabels]);
   /* eslint-enable react-hooks/refs */
 
   // The palette re-runs its provider on a `revision` change, never on the provider's
@@ -434,9 +470,10 @@ function GlobalSearchImpl({
 
   const apple = useMemo(() => isApplePlatform(), []);
   const keys = apple ? "⌘K" : "Ctrl K";
+  const triggerLabel = triggerName === "withShortcut" ? l.shortcut(keys) : l.trigger;
   const triggerProps: GlobalSearchTriggerProps = {
     open: openSearch,
-    label: l.trigger,
+    label: triggerLabel,
     tooltip: l.shortcut(keys),
     keys,
     ariaKeyShortcuts: "Meta+K Control+K",
@@ -456,12 +493,15 @@ function GlobalSearchImpl({
               <button
                 type="button"
                 onClick={openSearch}
-                aria-label={l.trigger}
+                aria-label={triggerLabel}
                 aria-keyshortcuts={triggerProps.ariaKeyShortcuts}
                 aria-haspopup="dialog"
                 className={cn(TOPBAR_TRIGGER_CLASS, triggerClassName)}
               >
-                <Search className="size-4" />
+                <Search
+                  className={triggerIconSize === undefined ? "size-4" : undefined}
+                  style={triggerIconSize === undefined ? undefined : { width: triggerIconSize, height: triggerIconSize }}
+                />
               </button>
             </Tooltip>
           )}
@@ -475,6 +515,7 @@ function GlobalSearchImpl({
         searchOn={searchOn}
         redactLabels={redactLabels}
         fullScreenOnPhone={fullScreenOnPhone}
+        density={density}
         labels={resolvedPaletteLabels}
       />
     </>