@eifi1/ui-kit 0.33.0 → 0.34.0

package/src/rhf/form.tsx

@@ -1,323 +1,48 @@
 /**
- * The react-hook-form adapter: the five parts every form is built from, and the hook
- * they share. `@eifi1/ui-kit/rhf`.
- *
- * ```tsx
- * <Form {...form}>
- *   <FormField control={form.control} name="amount" render={({ field }) => (
- *     <FormItem>
- *       <FormLabel required>Amount</FormLabel>
- *       <FormControl>
- *         <NumberField value={field.value} onCommit={field.onChange} />
- *       </FormControl>
- *       <FormMessage />
- *     </FormItem>
- *   )} />
- * </Form>
- * ```
- *
- * The shape is shadcn's `form.tsx`, on purpose: Kastlan builds every form from that
- * file, so moving onto this one is an import line rather than a rewrite. What differs
- * is what the shadcn file gets wrong:
- *
- *  - **`aria-describedby` names only what is on screen.** shadcn always points the
- *    control at a description id, rendered or not, and at the message id whenever the
- *    field has an error, whether a message was rendered for it or not. A reference to
- *    a node that does not exist describes the field as nothing. Here the description
- *    and the message say when they are mounted, and the control points at exactly
- *    those.
- *  - **Merged, never replaced.** A control that already carries its own
- *    `aria-describedby` keeps it, first — the same rule as the kit's `error` prop
- *    (see `useFieldError` in components/ui.tsx).
- *  - **No Radix.** `FormControl` is a one-child `cloneElement`, not `Slot`, and the
- *    label is the kit's own `Label` — the kit carries no Radix dependency and this
- *    entry is not the place to start.
- *
- * ## Why this is its own entry
- *
- * The main barrel once shipped a react-hook-form hook (`use-rhf-wizard-step`) and
- * removed it: it made react-hook-form an install every consumer's typecheck paid for,
- * for a hook nobody called (see the wizard section of src/index.ts). This is the
- * answer to that, not a reversal of it. Nothing outside `src/rhf*` imports
- * react-hook-form — `__tests__/packaging-contract.test.ts` holds that — and the peer is
- * optional, so an app that does not use it installs nothing and imports nothing.
- *
- * ## Painting the field
- *
- * `FormControl` sets `aria-invalid` on its child. `NumberField` and the pickers paint
- * from that attribute; `Input`, `Select` and `Textarea` paint only from their
- * `invalid` prop (see its note in components/ui.tsx: a bare attribute announces but
- * does not paint), so pass it from the render prop —
- * `<Input {...field} invalid={fieldState.invalid} />`. `FormControl` does not inject
- * `invalid` itself because its child may be a native element, which would print it
- * into the DOM as an unknown attribute.
- *
- * ## Clearing a picker: `null`, unless the picker is told otherwise
- *
- * Nothing here touches a value. `FormField` is `Controller`, so what a control hands
- * `field.onChange` is exactly what lands in the form — and what the entity pickers
- * hand it on a clear is `null`: `EntityCombobox`'s "×", `InlineEntityCombobox`'s "×"
- * and its emptied text. (`MultiEntityCombobox` and `MultiSelect` clear to `[]`.)
- *
- * A zod schema that spells "no choice" as `""` (`z.string()`, or `z.literal("")` in a
- * union) then fails on the `null`. Say so on the PICKER, not here:
- *
- * ```tsx
- * <EntityCombobox clearValue="" value={field.value} onChange={field.onChange} … />
- * ```
- *
- * `clearValue` also types `onChange` (`(v: V | "") => void` rather than
- * `V | null`) and reads `""` back as "nothing selected", so an initial `defaultValues`
- * of `""` shows the placeholder rather than an unresolvable id. The adapter does not
- * coerce because it cannot see the schema: mapping `null` to `""` for every field
- * would break every schema that wants `null` (`z.string().nullable()`), which is the
- * pickers' default for a reason — it is the one value no option can have.
- */
-import {
-  Children,
-  cloneElement,
-  createContext,
-  isValidElement,
-  useCallback,
-  useContext,
-  useId,
-  useLayoutEffect,
-  useMemo,
-  useState,
-  type ComponentProps,
-  type ReactElement,
-} from "react";
-import {
-  Controller,
-  FormProvider,
-  useFormContext,
-  useFormState,
-  type ControllerProps,
-  type FieldPath,
-  type FieldValues,
-} from "react-hook-form";
-import { Label, type LabelProps } from "../components/ui";
-import { cn } from "../lib/cn";
-
-/** The form's `useForm()` return, spread in: `<Form {...form}>`. react-hook-form's own
- *  `FormProvider`, under the name the shadcn file gave it. */
-export const Form = FormProvider;
-
-// ── contexts ─────────────────────────────────────────────────────────────────
-
-const FormFieldContext = createContext<{ name: string } | null>(null);
-
-/** The two optional nodes a control can be described by. */
-type Described = "description" | "message";
-
-interface FormItemContextValue {
-  id: string;
-  mounted: Record<Described, boolean>;
-  mark: (slot: Described, on: boolean) => void;
-}
-
-const FormItemContext = createContext<FormItemContextValue | null>(null);
-
-// ── FormField ────────────────────────────────────────────────────────────────
-
-/**
- * react-hook-form's `Controller`, with the field's name put in context for the parts
- * below it. Takes exactly `Controller`'s props.
- */
-export function FormField<
-  TFieldValues extends FieldValues = FieldValues,
-  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
-  TTransformedValues = TFieldValues,
->(props: ControllerProps<TFieldValues, TName, TTransformedValues>) {
-  const value = useMemo(() => ({ name: props.name as string }), [props.name]);
-  return (
-    <FormFieldContext.Provider value={value}>
-      <Controller {...props} />
-    </FormFieldContext.Provider>
-  );
-}
-
-// ── useFormField ─────────────────────────────────────────────────────────────
-
-/**
- * The ids and the state of the field around the caller: for a part of your own that
- * sits beside the kit's (a character counter that belongs in `aria-describedby`, a
- * label with a different look).
- *
- * Throws outside a `FormField` + `FormItem` pair. shadcn's version answered there with
- * ids like `undefined-form-item`, which label nothing and fail nowhere.
- */
-export function useFormField() {
-  const field = useContext(FormFieldContext);
-  const item = useContext(FormItemContext);
-  if (!field) throw new Error("useFormField must be used inside <FormField>.");
-  if (!item) throw new Error("useFormField must be used inside <FormItem>.");
-  const { getFieldState } = useFormContext();
-  // Subscribes this part to the field's state, so a label or message re-renders when
-  // the field's error changes without the whole form doing so.
-  const formState = useFormState({ name: field.name });
-  const state = getFieldState(field.name, formState);
-  const formDescriptionId = `${item.id}-description`;
-  const formMessageId = `${item.id}-message`;
-  const describedBy = [
-    item.mounted.description && formDescriptionId,
-    item.mounted.message && formMessageId,
-  ]
-    .filter(Boolean)
-    .join(" ");
-  return {
-    id: item.id,
-    name: field.name,
-    formItemId: `${item.id}-control`,
-    formDescriptionId,
-    formMessageId,
-    /** The ids of the description and message that are actually rendered, or
-     *  `undefined` when neither is. */
-    describedBy: describedBy || undefined,
-    ...state,
-  };
-}
-
-// ── FormItem ─────────────────────────────────────────────────────────────────
-
-export type FormItemProps = ComponentProps<"div">;
-
-/** One field's box: mints the id its label, control, description and message share. */
-export function FormItem({ className, ...rest }: FormItemProps) {
-  const id = useId();
-  const [mounted, setMounted] = useState<Record<Described, boolean>>({
-    description: false,
-    message: false,
-  });
-  const mark = useCallback(
-    (slot: Described, on: boolean) =>
-      setMounted((prev) => (prev[slot] === on ? prev : { ...prev, [slot]: on })),
-    [],
-  );
-  const value = useMemo(() => ({ id, mounted, mark }), [id, mounted, mark]);
-  return (
-    <FormItemContext.Provider value={value}>
-      {/* `content-start`: stretched to a taller neighbour's height in a grid row, the
-          item gave the extra to its rows and its control sat lower (showcase audit). */}
-      <div data-slot="form-item" {...rest} className={cn("grid content-start gap-1", className)} />
-    </FormItemContext.Provider>
-  );
-}
-
-/** Report a describing node's presence to the item, so the control points at it only
- *  while it is on screen. A layout effect, so the reference lands before paint. */
-function useDescribes(slot: Described, on: boolean) {
-  const item = useContext(FormItemContext);
-  const mark = item?.mark;
-  useLayoutEffect(() => {
-    if (!on || !mark) return;
-    mark(slot, true);
-    return () => mark(slot, false);
-  }, [slot, on, mark]);
-}
-
-// ── FormLabel ────────────────────────────────────────────────────────────────
-
-export type FormLabelProps = LabelProps;
-
-/**
- * The kit's {@link Label}, bound to the control by `htmlFor` and turned to the danger
- * colour while the field is invalid. `required` draws the kit's `aria-hidden` mark:
- * whether the field is required is the control's to announce.
- */
-export function FormLabel({ className, ...rest }: FormLabelProps) {
-  const { error, formItemId } = useFormField();
-  return (
-    <Label
-      data-slot="form-label"
-      data-error={error ? true : undefined}
-      htmlFor={formItemId}
-      {...rest}
-      className={cn("data-[error=true]:text-[var(--danger)]", className)}
-    />
-  );
-}
-
-// ── FormControl ──────────────────────────────────────────────────────────────
-
-export interface FormControlProps {
-  /** Exactly one element: the kit field, or a native one. It receives `id`,
-   *  `aria-describedby` and `aria-invalid`. */
-  children: ReactElement;
-}
-
-type AriaProps = {
-  id?: string;
-  "aria-describedby"?: string;
-  "aria-invalid"?: ComponentProps<"input">["aria-invalid"];
-};
-
-/**
- * Wires its one child to the item: the `id` the label points at, `aria-describedby`
- * naming the rendered description and message, and `aria-invalid` while the field has
- * an error.
- *
- * The child's own values win where it has them (an explicit `id`, a set
- * `aria-invalid`), as they did under Radix `Slot`; its own `aria-describedby` is
- * merged in front of the item's rather than replaced.
- */
-export function FormControl({ children }: FormControlProps) {
-  const { invalid, formItemId, describedBy } = useFormField();
-  const child = Children.only(children);
-  if (!isValidElement<AriaProps>(child)) return child;
-  const own = child.props;
-  const merged = [own["aria-describedby"], describedBy].filter(Boolean).join(" ");
-  return cloneElement(child, {
-    id: own.id ?? formItemId,
-    "aria-describedby": merged || undefined,
-    "aria-invalid": own["aria-invalid"] ?? (invalid || undefined),
-  });
-}
-
-// ── FormDescription / FormMessage ────────────────────────────────────────────
-
-export type FormDescriptionProps = ComponentProps<"p">;
-
-/** Standing advice under the field ("at least twelve characters"). */
-export function FormDescription({ className, ...rest }: FormDescriptionProps) {
-  const { formDescriptionId } = useFormField();
-  useDescribes("description", true);
-  return (
-    <p
-      data-slot="form-description"
-      {...rest}
-      id={formDescriptionId}
-      className={cn("text-caption leading-tight text-[var(--text-muted)]", className)}
-    />
-  );
-}
-
-export type FormMessageProps = ComponentProps<"p">;
-
-/**
- * The field's error message, from the form — the kit renders no string of its own
- * here; the schema or the `rules` carry the words. Without an error it renders its
- * `children`, if any, and otherwise nothing.
- *
- * Deliberately NOT `role="alert"`, for the reason the kit's `error` prop gives: the
- * message is read when focus reaches the control, which is where a field's own error
- * is wanted, and an alert would interrupt on every keystroke of a form that
- * re-validates as you type.
+ * `Form`, and until 0.35 the shadcn scaffold under its old public names — the public face
+ * of ./form-core, where the scaffold lives (its header has the whole story: what differs
+ * from shadcn's file, why /rhf is its own entry, how a picker clears).
+ *
+ * 0.34 (refactor audit 2026-10, API-6f): no app builds a form from the scaffold any more.
+ * kastlan, the one /rhf consumer, uses `Form`, the bound `Rhf*` fields and `RhfField` for
+ * a control of its own, so the seven names and their props types leave the public
+ * surface in 0.35. The bound fields import the parts from the core, so the removal is
+ * the block below.
  */
-export function FormMessage({ className, children, ...rest }: FormMessageProps) {
-  const { error, formMessageId } = useFormField();
-  const body = error ? String(error.message ?? "") : children;
-  const shown = body !== undefined && body !== null && body !== false && body !== "";
-  useDescribes("message", shown);
-  if (!shown) return null;
-  return (
-    <p
-      data-slot="form-message"
-      {...rest}
-      id={formMessageId}
-      className={cn("text-caption leading-tight text-[var(--danger)]", className)}
-    >
-      {body}
-    </p>
-  );
-}
+import * as core from "./form-core";
+
+export { Form } from "./form-core";
+
+/* ── Deprecated 0.34, removed in 0.35 ───────────────────────────────────────
+ * Each is the core's own value under its public name. The replacement for all of them:
+ * a bound field (`RhfTextField`, `RhfSelect`, …), or `RhfField` around a control of
+ * your own — the same parts, folded into one element. */
+
+/** @deprecated 0.34 — the bound `Rhf*` fields, or `RhfField` for a control of your own;
+ *  removed in 0.35 (API-6f). */
+export const FormField = core.FormField;
+/** @deprecated 0.34 — `RhfField`, which reads the field's ids itself; removed in 0.35
+ *  (API-6f). */
+export const useFormField = core.useFormField;
+/** @deprecated 0.34 — the bound `Rhf*` fields, or `RhfField`; removed in 0.35 (API-6f). */
+export const FormItem = core.FormItem;
+/** @deprecated 0.34 — the bound fields' and `RhfField`'s `label`; removed in 0.35 (API-6f). */
+export const FormLabel = core.FormLabel;
+/** @deprecated 0.34 — `RhfField`, which wires its control the same way; removed in 0.35
+ *  (API-6f). */
+export const FormControl = core.FormControl;
+/** @deprecated 0.34 — the bound fields' and `RhfField`'s `hint`; removed in 0.35 (API-6f). */
+export const FormDescription = core.FormDescription;
+/** @deprecated 0.34 — the bound fields and `RhfField`, which show the error themselves;
+ *  removed in 0.35 (API-6f). */
+export const FormMessage = core.FormMessage;
+/** @deprecated 0.34 — goes with `FormItem`; removed in 0.35 (API-6f). */
+export type FormItemProps = core.FormItemProps;
+/** @deprecated 0.34 — goes with `FormLabel`; removed in 0.35 (API-6f). */
+export type FormLabelProps = core.FormLabelProps;
+/** @deprecated 0.34 — goes with `FormControl`; removed in 0.35 (API-6f). */
+export type FormControlProps = core.FormControlProps;
+/** @deprecated 0.34 — goes with `FormDescription`; removed in 0.35 (API-6f). */
+export type FormDescriptionProps = core.FormDescriptionProps;
+/** @deprecated 0.34 — goes with `FormMessage`; removed in 0.35 (API-6f). */
+export type FormMessageProps = core.FormMessageProps;

package/src/rhf/line-items.tsx

@@ -11,7 +11,7 @@
  *       <RhfSelect name={`${name}.type`} options={TYPES} aria-label={label} />
  *     ) },
  *     { key: "amount", header: "Amount", width: "8rem", align: "end", render: ({ name, label }) => (
- *       <RhfMoneyField name={`${name}.amount`} ariaLabel={label} />
+ *       <RhfMoneyField name={`${name}.amount`} aria-label={label} />
  *     ) },
  *   ]}
  *   totals={{ amount: formatMoney(total) }}

package/src/rhf.ts

@@ -1,5 +1,6 @@
-// `@eifi1/ui-kit/rhf` — the react-hook-form adapter: Form, FormField, FormItem,
-// FormLabel, FormControl, FormDescription, FormMessage and useFormField.
+// `@eifi1/ui-kit/rhf` — the react-hook-form adapter: Form and the bound Rhf* fields (and
+// RhfField as the escape hatch). The shadcn scaffold (FormField, FormItem, FormLabel,
+// FormControl, FormDescription, FormMessage, useFormField) is deprecated in 0.34.
 //
 // The only entry point in the package that requires `react-hook-form`, and an optional
 // peer for that reason: an app without a form library installs nothing for it. NOT

package/src/search/command-palette-labels.ts

@@ -0,0 +1,16 @@
+// The English words of ./command-palette, in a module with no component code: the English
+// catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
+// chunk like the other languages (0.34, KS U8). ./command-palette re-exports them.
+
+import type { CommandPaletteLabels } from "./command-palette";
+
+export const DEFAULT_COMMAND_PALETTE_LABELS: CommandPaletteLabels = {
+  placeholder: "Search…",
+  empty: "No results",
+  loading: "Searching…",
+  dialog: "Search",
+  error: "Search failed. Try again.",
+  clear: "Clear search",
+  submit: "Search",
+  close: "Close",
+};

package/src/search/command-palette.tsx

@@ -3,12 +3,15 @@ import type { ReactNode } from "react";
 import { createPortal } from "react-dom";
 import { CornerDownLeft, Search, X } from "lucide-react";
 import { cn } from "../lib/cn";
-import { FIELD_TOUCH_TEXT } from "../components/ui";
+import { FIELD_TOUCH_TEXT } from "../components/field-base";
 import { usePhoneLayout } from "../hooks/use-breakpoint";
 import { useOverlayHistory } from "../hooks/use-overlay-history";
 import { useFocusTrap } from "../hooks/use-focus-trap";
 import { useBodyScrollLock } from "../hooks/use-body-scroll-lock";
-import { useKitLabels } from "../i18n/kit-labels";
+import { takeEscape, useDismissLayer } from "../hooks/use-dismiss";
+import { isImeEnter } from "../lib/ime";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { DEFAULT_COMMAND_PALETTE_LABELS } from "./command-palette-labels";
 
 export interface CommandItem {
   id: string;
@@ -92,16 +95,8 @@ export interface CommandPaletteLabels {
   close?: string;
 }
 
-export const DEFAULT_COMMAND_PALETTE_LABELS: CommandPaletteLabels = {
-  placeholder: "Search…",
-  empty: "No results",
-  loading: "Searching…",
-  dialog: "Search",
-  error: "Search failed. Try again.",
-  clear: "Clear search",
-  submit: "Search",
-  close: "Close",
-};
+// Defined in ./command-palette-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_COMMAND_PALETTE_LABELS };
 
 /**
  * How tall the palette's rows are. `"compact"` (the default) is the desktop list the
@@ -200,22 +195,12 @@ interface CommandPaletteProps {
   fullScreenOnPhone?: boolean;
   /** Row height — see {@link CommandPaletteDensity}. Default `"compact"`. */
   density?: CommandPaletteDensity;
-  labels?: Partial<CommandPaletteLabels>;
+  labels?: LabelOverride<CommandPaletteLabels>;
 }
 
-/** Registers a global ⌘K / Ctrl-K shortcut that calls `onOpen`. */
-export function useCommandKey(onOpen: () => void): void {
-  useEffect(() => {
-    const handler = (e: KeyboardEvent) => {
-      if ((e.metaKey || e.ctrlKey) && (e.key === "k" || e.key === "K")) {
-        e.preventDefault();
-        onOpen();
-      }
-    };
-    document.addEventListener("keydown", handler);
-    return () => document.removeEventListener("keydown", handler);
-  }, [onOpen]);
-}
+// Defined in ./use-command-key, so `GlobalSearch` can listen for ⌘K without loading the
+// palette before it is opened (0.34, MOD-1).
+export { useCommandKey } from "./use-command-key";
 
 /**
  * A ⌘K-style command palette: a top-centred modal with a search field and a
@@ -389,19 +374,21 @@ export function CommandPalette({
       e.preventDefault();
       setActive((i) => Math.max(i - 1, 0));
     } else if (e.key === "Enter") {
+      // The Enter that confirms an IME composition is the IME's (BUG-9).
+      if (isImeEnter(e)) return;
       e.preventDefault();
       if (dirty) commit(draft);
       else choose(flat[active]);
     }
   };
 
-  // Escape on the whole dialog, not only the field: once Tab has moved focus to a row
-  // (or a footer control), Escape used to do nothing at all.
+  // A layer on the kit's Escape stack while open (Wave 2, DUP-1), taken on the whole
+  // dialog, not only the field: once Tab has moved focus to a row (or a footer
+  // control), Escape used to do nothing at all. It closed without stopping the key, so
+  // a dialog the palette was opened from closed with it.
+  useDismissLayer(open, onClose);
   const onDialogKeyDown = (e: React.KeyboardEvent) => {
-    if (e.key === "Escape") {
-      e.preventDefault();
-      onClose();
-    }
+    takeEscape(e);
   };
 
   // Keep the active row scrolled into view.
@@ -438,10 +425,10 @@ export function CommandPalette({
         onKeyDown={onDialogKeyDown}
         data-fullscreen={isPhone || undefined}
         className={cn(
-          "flex w-full flex-col overflow-hidden bg-[var(--bg-surface)] outline-none",
+          "flex w-full flex-col overflow-hidden bg-surface outline-none",
           isPhone
             ? "h-full"
-            : "max-h-[70vh] max-w-xl rounded-xl border border-[var(--border)] shadow-2xl",
+            : "max-h-[70vh] max-w-xl rounded-xl border border-subtle shadow-2xl",
         )}
         // Full screen means edge to edge, so the notch, the home indicator and the
         // rounded corners are the panel's to keep clear of.
@@ -456,8 +443,8 @@ export function CommandPalette({
             : undefined
         }
       >
-        <div className="flex shrink-0 items-center gap-2 border-b border-[var(--border)] px-3">
-          <Search className="size-4 shrink-0 text-[var(--text-placeholder)]" />
+        <div className="flex shrink-0 items-center gap-2 border-b border-subtle px-3">
+          <Search className="size-4 shrink-0 text-placeholder" />
           <input
             ref={inputRef}
             role="combobox"
@@ -470,13 +457,13 @@ export function CommandPalette({
             placeholder={l.placeholder}
             enterKeyHint={submitMode ? "search" : undefined}
             className={cn(
-              "w-full bg-transparent py-3 outline-none placeholder:text-[var(--text-placeholder)] text-[var(--text-primary)]",
+              "w-full bg-transparent py-3 outline-none placeholder:text-placeholder text-primary",
               // 16px on a phone, or iOS zooms the page in on focus — and on any other
               // touch screen too (a tablet's popover), FIELD_TOUCH_TEXT (§10.1).
               isPhone ? "text-base" : cn("text-sm", FIELD_TOUCH_TEXT),
             )}
           />
-          {loading && <span className="shrink-0 text-caption text-[var(--text-placeholder)]">{l.loading}</span>}
+          {loading && <span className="shrink-0 text-caption text-placeholder">{l.loading}</span>}
           {fieldText !== "" && (
             <button
               type="button"
@@ -486,7 +473,7 @@ export function CommandPalette({
                 // Clearing starts the next query far more often than it ends this one.
                 inputRef.current?.focus();
               }}
-              className="shrink-0 rounded p-1 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]"
+              className="shrink-0 rounded p-1 text-placeholder hover:text-secondary"
             >
               <X className="size-4" />
             </button>
@@ -499,7 +486,7 @@ export function CommandPalette({
                 commit(draft);
                 inputRef.current?.focus();
               }}
-              className="shrink-0 rounded p-1 text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
+              className="shrink-0 rounded p-1 text-secondary hover:text-primary"
             >
               <CornerDownLeft className="size-4" />
             </button>
@@ -508,7 +495,7 @@ export function CommandPalette({
             <button
               type="button"
               onClick={onClose}
-              className="-me-1 shrink-0 rounded px-1 py-2 text-sm text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
+              className="-me-1 shrink-0 rounded px-1 py-2 text-sm text-secondary hover:text-primary"
             >
               {l.close ?? DEFAULT_COMMAND_PALETTE_LABELS.close}
             </button>
@@ -518,14 +505,14 @@ export function CommandPalette({
         {/* The status lines sit outside the listbox: a listbox owns options and groups,
             and "No results" is neither. */}
         {failed && !loading && (
-          <div role="alert" className="px-3 py-6 text-center text-sm text-[var(--text-muted)]">
+          <div role="alert" className="px-3 py-6 text-center text-sm text-muted">
             {l.error ?? DEFAULT_COMMAND_PALETTE_LABELS.error}
           </div>
         )}
         {/* `results`, not `flat`: a group whose only row is its "Searching…" line is not
             an empty result. */}
         {!failed && results.length === 0 && !loading && (
-          <div className="px-3 py-6 text-center text-sm text-[var(--text-muted)]">{l.empty}</div>
+          <div className="px-3 py-6 text-center text-sm text-muted">{l.empty}</div>
         )}
         {/* Listbox grouping: each group is a `role="group"` named by its heading, and
             the list markup in between is presentational so the listbox's children are
@@ -537,7 +524,7 @@ export function CommandPalette({
               <div
                 id={groupId(groupIndex)}
                 role="presentation"
-                className="px-3 pb-0.5 pt-2 text-micro font-semibold uppercase tracking-wide text-[var(--text-placeholder)]"
+                className="px-3 pb-0.5 pt-2 text-micro font-semibold uppercase tracking-wide text-placeholder"
               >
                 {group}
               </div>
@@ -549,7 +536,7 @@ export function CommandPalette({
                         key={item.id}
                         role="presentation"
                         className={cn(
-                          "flex items-center gap-2.5 px-3 text-xs text-[var(--text-placeholder)]",
+                          "flex items-center gap-2.5 px-3 text-xs text-placeholder",
                           comfortable ? "min-h-11 py-2.5" : "py-2",
                         )}
                       >
@@ -575,14 +562,14 @@ export function CommandPalette({
                       "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)]",
+                        ? "bg-active text-primary"
+                        : "text-secondary",
                     ),
                   };
                   const inner = (
                     <>
                       {item.icon && (
-                        <span className="flex size-4 shrink-0 items-center justify-center text-[var(--text-placeholder)]">
+                        <span className="flex size-4 shrink-0 items-center justify-center text-placeholder">
                           {item.icon}
                         </span>
                       )}
@@ -590,7 +577,7 @@ export function CommandPalette({
                         {item.label}
                       </span>
                       {item.hint && (
-                        <span data-private={redact || undefined} className="shrink-0 text-xs text-[var(--text-placeholder)]">
+                        <span data-private={redact || undefined} className="shrink-0 text-xs text-placeholder">
                           {item.hint}
                         </span>
                       )}
@@ -636,7 +623,7 @@ export function CommandPalette({
         </ul>
 
         {l.hint && (
-          <div className="border-t border-[var(--border)] px-3 py-1.5 text-caption text-[var(--text-placeholder)]">
+          <div className="border-t border-subtle px-3 py-1.5 text-caption text-placeholder">
             {l.hint}
           </div>
         )}

package/src/search/global-search-labels.ts

@@ -0,0 +1,13 @@
+// The English words of ./global-search, in a module with no component code: the English
+// catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
+// chunk like the other languages (0.34, KS U8). ./global-search re-exports them.
+
+import type { GlobalSearchLabels } from "./global-search";
+
+export const DEFAULT_GLOBAL_SEARCH_LABELS: GlobalSearchLabels = {
+  trigger: "Search",
+  placeholder: "Search or jump to…",
+  shortcut: (keys) => `Search (${keys})`,
+  suggestions: "Try",
+  results: "Results",
+};