cursedbelt 5.74.1 → 5.76.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "5.74.1",
+	"version": "5.76.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The React design system of the cursedbelt split — components, styles, theme. cursedbelt-core below it; server tier in cursedbelt-server.",

package/scripts/guardrailsEnforce.spec.ts

@@ -1045,6 +1045,74 @@ describe('no-select-as-action-menu', () => {
   });
 });
 
+describe('no-native-select — the OS draws its list (owner, 2026-10-10)', () => {
+  test('flags every NativeSelect in an app, a real form field included', () => {
+    const source = `<NativeSelect value={type} onChange={(e) => setType(e.target.value)}>
+      {TYPES.map((t) => <option key={t} value={t}>{t}</option>)}
+    </NativeSelect>
+    <NativeSelect value={kind} size="sm" onChange={pick} />`;
+    expect(check('no-native-select', source)).toHaveLength(2);
+  });
+
+  test('the styled controls, and a comment that names it, are not one', () => {
+    expect(check('no-native-select', `<SelectField value={sort} options={SORTS} />`)).toHaveLength(0);
+    expect(check('no-native-select', `// was a <NativeSelect> until 2026-10-10\n<PropertyPicker name="Type" />`)).toHaveLength(0);
+  });
+
+  test('a use that says why the OS picker is right is allowed', () => {
+    const source = `{/* guardrails-ignore no-native-select: a phone-first form — the OS wheel is the better control */}
+    <NativeSelect value={relation} onChange={pick} />`;
+    expect(check('no-native-select', source)).toHaveLength(0);
+  });
+});
+
+describe('typed-field-outside-a-form — Enter submits (owner, 2026-10-11; forge task 3043)', () => {
+  // vault's Settings before 3043: a password beside a click-only button, no <form> anywhere.
+  const clickOnly = `<SecretInput value={pw} onChange={setPw} label="Master password" />
+    <Input value={hint} onChange={(e) => setHint(e.target.value)} />
+    <Button disabled={!pw} onClick={onSave}>Save</Button>`;
+
+  test('flags each typed field in a file where nothing handles Enter', () => {
+    expect(check('typed-field-outside-a-form', clickOnly)).toHaveLength(2);
+    expect(check('typed-field-outside-a-form', `<input value={v} onChange={set} />\n<OtpInput length={6} />`)).toHaveLength(2);
+  });
+
+  test('a form, a submit or Enter handler, a self-submitting code or an autosave answers it', () => {
+    for (const handled of [
+      `<form className="contents" onSubmit={submit}>${clickOnly}</form>`,
+      `${clickOnly}\n<Wizard onSubmit={finish} />`,
+      `<SecretInput value={pw} onEnter={unlock} />`,
+      `<OtpInput length={6} onComplete={verify} />`,
+      `<Input onKeyDown={(e) => { if (e.key === "Enter") save(); }} />`,
+      `const autosave = useAutosave<Draft>({ save });\n<Input value={title} />`,
+    ]) {
+      expect(check('typed-field-outside-a-form', handled)).toHaveLength(0);
+    }
+  });
+
+  test('a field with nothing to submit is not one, and a comment naming one is not one', () => {
+    expect(check('typed-field-outside-a-form', `<Input type="search" value={q} onChange={setQ} />`)).toHaveLength(0);
+    expect(check('typed-field-outside-a-form', `<input type="checkbox" checked={on} />\n<input type={"range"} />`)).toHaveLength(0);
+    expect(check('typed-field-outside-a-form', `<Input value={url} readOnly />`)).toHaveLength(0);
+    expect(check('typed-field-outside-a-form', `// a <Input> used to sit here\n<Button onClick={go}>Go</Button>`)).toHaveLength(0);
+    // `readOnly={false}` is an editable field.
+    expect(check('typed-field-outside-a-form', `<Input value={v} readOnly={false} />`)).toHaveLength(1);
+  });
+
+  test('a field whose form is in its parent says so', () => {
+    const source = `{/* guardrails-ignore typed-field-outside-a-form: rendered inside AccountForm's <form> */}
+    <SecretInput value={pw} onChange={setPw} />`;
+    expect(check('typed-field-outside-a-form', source)).toHaveLength(0);
+  });
+
+  test('specs and the kit\'s own components are fixtures, not screens', () => {
+    expect(RULES['typed-field-outside-a-form'].check('src/App.spec.tsx', clickOnly)).toHaveLength(0);
+    expect(RULES['typed-field-outside-a-form'].check('libs/cursedbelt/src/react/components/SecretInput.tsx', clickOnly)).toHaveLength(0);
+    expect(RULES['typed-field-outside-a-form'].check('src/server/page.ts', clickOnly)).toHaveLength(0);
+    expect(APP_RULES).toContain('typed-field-outside-a-form');
+  });
+});
+
 describe('no-native-dialog', () => {
   test('flags each of the three native dialogs', () => {
     expect(check('no-native-dialog', `if (!window.confirm("sure?")) return;`)).toHaveLength(1);
@@ -1271,6 +1339,8 @@ describe('--all-app-rules (task 2219: a new belt rule reaches every app by itsel
     const rows: Record<string, number> = Object.fromEntries(APP_RULES.map((name) => [name, 0]));
     rows['no-hardcoded-colors'] = 2;
     rows['no-raw-inputs'] = 1;
+    // The same <input>, with no form in its file: Enter has nothing to submit (forge task 3043).
+    rows['typed-field-outside-a-form'] = 1;
     for (const [name, count] of Object.entries(overrides)) {
       if (count === undefined) delete rows[name];
       else rows[name] = count;

package/scripts/guardrailsEnforce.ts

@@ -113,6 +113,17 @@
 //     Semantic classes are never matched — `text-xs` IS 12px. A non-text glyph takes
 //     the per-line opt-out.
 //
+//   no-native-select — owner, 2026-10-10: a `NativeSelect`'s list is drawn by the OS, where no
+//     stylesheet reaches it, so it breaks the app's cohesion. `SelectField` / `ComboboxField` /
+//     `PropertyPicker` / `ChoiceMenu` instead; a use where the OS picker is genuinely better says
+//     why with `// guardrails-ignore no-native-select: <why>` on the line above. Ratcheted per app.
+//
+//   typed-field-outside-a-form — owner, 2026-10-11: Enter submits. A typed field in a file with no
+//     `<form` / `onSubmit` / `onEnter` / `onComplete` / `"Enter"` handler is a field beside a
+//     click-only button. Search, checkbox-like and read-only inputs are not matched; a field whose
+//     form is in its parent says so with `// guardrails-ignore typed-field-outside-a-form: <why>`.
+//     Ratcheted per app.
+//
 //   no-native-dialog — DESIGN.md core mandate: no `window.confirm` / `window.prompt` /
 //     `window.alert`. The browser draws them outside the page, so no stylesheet reaches
 //     them; they block the main thread; a browser can SUPPRESS a repeat dialog, after
@@ -2022,6 +2033,97 @@ const noSelectAsActionMenu: Rule = {
 	},
 };
 
+// ── no-native-select ────────────────────────────────────────────────────────
+// The owner, 2026-10-10, on vault's entry form: *"I saw we don't style the dropdowns and that is a
+// violation of our design requirements to have bad styling or missing styling break the app's
+// cohesiveness like that. cb should have components that handle this … we should not let anything
+// like that by us anymore."* The dropdowns were `NativeSelect`: its LIST is drawn by the OS — on
+// macOS Chrome a grey system menu no stylesheet reaches — so every app that used one had a control
+// that was not the kit's. `no-select-as-action-menu` caught only the action-menu shape of it.
+//
+// Every app now counts its `<NativeSelect` uses in its two-sided ratchet, so the number only falls:
+// `SelectField` / `ComboboxField` for a field, `PropertyPicker` for a record's property pill,
+// `ChoiceMenu` to choose-and-act. A use that is genuinely right — a form on a phone where the OS
+// wheel IS the better control — says so on the line above:
+// `// guardrails-ignore no-native-select: <why>`.
+const NATIVE_SELECT_IGNORE_RE = /guardrails-ignore\s+no-native-select\s*:/;
+
+const noNativeSelect: Rule = {
+	name: "no-native-select",
+	description:
+		"Owner, 2026-10-10: unstyled dropdowns break the app's cohesiveness. A `NativeSelect`'s list is drawn by the OS, outside the page, where no stylesheet reaches it. Use `SelectField` / `ComboboxField` for a form field, `PropertyPicker` for a record's property (Type, Folder, Tags), or `ChoiceMenu` to choose-and-act. Where the OS picker is the better control, say why on the line above: `// guardrails-ignore no-native-select: <why>`.",
+	check(filePath, source) {
+		const unix = filePath.replace(/\\/g, "/");
+		if (/(^|\/)(?:packages|libs)\/cursedbelt\/src\/react\/components\//.test(unix)) return [];
+		if (/\.(?:spec|test)\.[tj]sx?$/.test(unix)) return [];
+		const scannable = blankComments(source);
+		const lines = source.split("\n");
+		const out: Violation[] = [];
+		for (const match of scannable.matchAll(/<NativeSelect\b/g)) {
+			const line = lineOf(source, match.index ?? 0);
+			if (NATIVE_SELECT_IGNORE_RE.test(lines[line - 1] ?? "") || NATIVE_SELECT_IGNORE_RE.test(blockAbove(lines, line))) continue;
+			out.push({ file: filePath, line, snippet: lines[line - 1]?.trim() ?? "" });
+		}
+		return out;
+	},
+};
+
+// ── typed-field-outside-a-form ──────────────────────────────────────────────
+// The owner, 2026-10-11, on auth's emailed code: *"I entered an email code and pressed enter key
+// and nothing happened … Make sure other pages like the email password form let's hitting enter
+// submit it too as applicable."* Auth was fixed in auth e958057 and vault's Settings in forge task
+// 3043 — both the same shape: a typed field beside a click-only button, with no `<form>`, so Enter
+// (the browser's implicit submission) had nothing to submit.
+//
+// A file with a typed field — `<input>`, `<Input`, `<SecretInput`, `<OtpInput` — must handle Enter
+// SOMEWHERE: a `<form`, an `onSubmit=`, an `onEnter=`, an `onComplete=` (OtpInput submits itself
+// at its last digit), a key handler naming `"Enter"`, or a `useAutosave(` — an editor that saves
+// as you type has nothing to submit (vault's EntryEditor, forge task 3016.5). It is FILE-scoped on purpose: a field
+// whose form is in its parent file cannot be seen from here, so it would take an opt-out, and the
+// rule has to be quiet enough that an opt-out means something. Fields with nothing to submit are
+// not matched — `type="search"` (a live filter), a checkbox/radio/range/color/file/hidden input,
+// and a `readOnly` one. A field genuinely without an action says why on the line above:
+// `// guardrails-ignore typed-field-outside-a-form: <why>`. Ratcheted per app.
+const TYPED_FIELD_RE = /<(?:input|Input|SecretInput|OtpInput)\b/g;
+const ENTER_HANDLED_RE = /<form\b|\bonSubmit\s*=|\bonEnter\s*=|\bonComplete\s*=|["'`]Enter["'`]|\buseAutosave\s*(?:<[^>]*>\s*)?\(/;
+const NOTHING_TO_SUBMIT_RE =
+	/\btype\s*=\s*(?:\{\s*)?["'`](?:search|checkbox|radio|range|color|file|hidden|button|submit|reset|image)["'`]|\breadOnly\b(?!\s*=\s*\{\s*false\s*\})/;
+const TYPED_FIELD_IGNORE_RE = /guardrails-ignore\s+typed-field-outside-a-form\s*:/;
+
+/** The attribute text of the JSX tag opening at `start` — up to its `>`, skipping `{…}` expressions. */
+function tagText(source: string, start: number): string {
+	let depth = 0;
+	for (let i = start + 1; i < source.length && i < start + 2000; i++) {
+		const c = source[i];
+		if (c === "{") depth++;
+		else if (c === "}") depth--;
+		else if (c === ">" && depth === 0) return source.slice(start, i + 1);
+	}
+	return source.slice(start, start + 2000);
+}
+
+const typedFieldOutsideAForm: Rule = {
+	name: "typed-field-outside-a-form",
+	description:
+		"Owner, 2026-10-11: Enter must submit. A typed field (`<input>`, `Input`, `SecretInput`, `OtpInput`) in a file with no `<form`, `onSubmit`, `onEnter`, `onComplete` or `\"Enter\"` key handler is a field beside a click-only button, where Enter does nothing. Wrap the field and its button in `<form onSubmit>` (`className=\"contents\"` keeps a flex/grid parent's layout) and make the button `type=\"submit\"`. A field whose form is in its parent, or that truly has no action, says why on the line above: `// guardrails-ignore typed-field-outside-a-form: <why>`.",
+	check(filePath, source) {
+		const unix = filePath.replace(/\\/g, "/");
+		if (/(^|\/)(?:packages|libs)\/cursedbelt\/src\/react\/components\//.test(unix)) return [];
+		if (isTestSource(unix) || !/\.[jt]sx$/.test(unix)) return [];
+		const scannable = blankComments(source);
+		if (ENTER_HANDLED_RE.test(scannable)) return [];
+		const lines = source.split("\n");
+		const out: Violation[] = [];
+		for (const match of scannable.matchAll(TYPED_FIELD_RE)) {
+			if (NOTHING_TO_SUBMIT_RE.test(tagText(scannable, match.index ?? 0))) continue;
+			const line = lineOf(source, match.index ?? 0);
+			if (TYPED_FIELD_IGNORE_RE.test(lines[line - 1] ?? "") || TYPED_FIELD_IGNORE_RE.test(blockAbove(lines, line))) continue;
+			out.push({ file: filePath, line, snippet: lines[line - 1]?.trim() ?? "" });
+		}
+		return out;
+	},
+};
+
 // ── no-native-dialog ────────────────────────────────────────────────────────
 // `window.confirm` / `window.prompt` / `window.alert` — and their bare global
 // forms — are the browser's own chrome, and cursedbelt has shipped styled,
@@ -2925,6 +3027,8 @@ export const RULES: Record<string, Rule> = {
 	[choiceNeedsEmptyState.name]: choiceNeedsEmptyState,
 	[noSelectAsActionMenu.name]: noSelectAsActionMenu,
 	[noNativeDialog.name]: noNativeDialog,
+	[noNativeSelect.name]: noNativeSelect,
+	[typedFieldOutsideAForm.name]: typedFieldOutsideAForm,
 	[noFastTooltip.name]: noFastTooltip,
 	[noRawPassword.name]: noRawPassword,
 	[noRawNav.name]: noRawNav,

package/scripts/styleAreas.ts

@@ -349,7 +349,7 @@ export const AREAS: readonly Area[] = [
 			'components/AddItemsMenu.tsx',
 		],
 	},
-	{ name: 'palette', why: 'the ⌘K command palette and its hotkey/source hooks', roots: ['palette'] },
+	{ name: 'palette', why: 'the ⌘K command palette and its hotkey/source hooks, and the PropertyPicker built on its Command list', roots: ['palette', 'components/PropertyPicker.tsx'] },
 	{ name: 'pdf-viewer', why: 'the lazy PDF viewer (an optional peer already)', roots: ['pdf-viewer'] },
 	{
 		name: 'place-bar',

package/src/react/components/PropertyPicker.spec.tsx

@@ -0,0 +1,105 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { useRef, useState } from 'react';
+import { Input } from './Input.js';
+import { matchesShortcut, PropertyPicker } from './PropertyPicker.js';
+
+afterEach(cleanup);
+
+const TYPES = [
+  { value: 'login', label: 'Login' },
+  { value: 'apiKey', label: 'API key' },
+  { value: 'envFile', label: 'Env file' },
+];
+
+function Single({ onCreate }: { onCreate?: (q: string) => void }) {
+  const [value, setValue] = useState<string | null>('login');
+  const scope = useRef<HTMLDivElement>(null);
+  return (
+    <div ref={scope} data-testid='scope'>
+      <PropertyPicker name='Type' options={TYPES} value={value} onChange={setValue} onCreate={onCreate} shortcut='t' shortcutScope={scope} />
+      <Input aria-label='Name' />
+      <output data-testid='value'>{value}</output>
+    </div>
+  );
+}
+
+function Multi() {
+  const [value, setValue] = useState<string[]>(['prod']);
+  const [options, setOptions] = useState([
+    { value: 'prod', label: 'prod' },
+    { value: 'k8s', label: 'k8s' },
+  ]);
+  return (
+    <>
+      <PropertyPicker
+        multiple
+        name='Tags'
+        options={options}
+        value={value}
+        onChange={setValue}
+        onCreate={(q) => {
+          setOptions((o) => [...o, { value: q, label: q }]);
+          setValue((v) => [...v, q]);
+        }}
+      />
+      <output data-testid='value'>{value.join(',')}</output>
+    </>
+  );
+}
+
+const pill = (name: RegExp) => screen.getByRole('button', { name });
+const search = (name: string) => screen.getByRole('combobox', { name: new RegExp(`Search ${name}`, 'i') });
+
+describe('PropertyPicker', () => {
+  test('the pill shows the value; choosing a row sets it and closes the list', () => {
+    render(<Single />);
+    expect(pill(/^Type: Login$/)).toBeTruthy();
+    fireEvent.click(pill(/^Type:/));
+    fireEvent.click(screen.getByRole('option', { name: /API key/ }));
+    expect(screen.getByTestId('value').textContent).toBe('apiKey');
+    expect(screen.queryByRole('combobox', { name: /Search type/i })).toBeNull();
+  });
+
+  test('typing filters the list — the search is the point once it is long', () => {
+    render(<Single />);
+    fireEvent.click(pill(/^Type:/));
+    fireEvent.change(search('type'), { target: { value: 'env' } });
+    expect(screen.getByRole('option', { name: /Env file/ })).toBeTruthy();
+    expect(screen.queryByRole('option', { name: /^Login/ })).toBeNull();
+  });
+
+  test('a multiple picker toggles and stays open, and Enter on an unmatched query creates it', () => {
+    render(<Multi />);
+    fireEvent.click(pill(/^Tags:/));
+    fireEvent.click(screen.getByRole('option', { name: /k8s/ }));
+    expect(screen.getByTestId('value').textContent).toBe('prod,k8s');
+    fireEvent.click(screen.getByRole('option', { name: /prod/ }));
+    expect(screen.getByTestId('value').textContent).toBe('k8s');
+    const box = search('tags');
+    fireEvent.change(box, { target: { value: 'mcp' } });
+    fireEvent.keyDown(box, { key: 'Enter' });
+    expect(screen.getByTestId('value').textContent).toBe('k8s,mcp');
+    expect(search('tags')).toBeTruthy();
+  });
+
+  test('its one-key shortcut opens it from inside the scope, never while typing in a field', () => {
+    render(<Single />);
+    act(() => {
+      fireEvent.keyDown(screen.getByLabelText('Name'), { key: 't' });
+    });
+    expect(screen.queryByRole('combobox', { name: /Search type/i })).toBeNull();
+    act(() => {
+      fireEvent.keyDown(screen.getByTestId('scope'), { key: 't' });
+    });
+    expect(search('type')).toBeTruthy();
+  });
+
+  test('matchesShortcut: case is Shift, and a chord is never a bare key', () => {
+    const at = { target: null } as const;
+    expect(matchesShortcut({ ...at, key: 't', shiftKey: false, metaKey: false, ctrlKey: false, altKey: false }, 't')).toBe(true);
+    expect(matchesShortcut({ ...at, key: 'T', shiftKey: true, metaKey: false, ctrlKey: false, altKey: false }, 't')).toBe(false);
+    expect(matchesShortcut({ ...at, key: 'T', shiftKey: true, metaKey: false, ctrlKey: false, altKey: false }, 'T')).toBe(true);
+    expect(matchesShortcut({ ...at, key: 't', shiftKey: false, metaKey: true, ctrlKey: false, altKey: false }, 't')).toBe(false);
+  });
+});

package/src/react/components/PropertyPicker.tsx

@@ -0,0 +1,254 @@
+import { Check, Plus } from 'lucide-react';
+import { type ReactNode, type RefObject, useEffect, useMemo, useState } from 'react';
+import { cn } from '../lib/cn.js';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '../palette/Command.js';
+import { Button } from './Button.js';
+import { Popover } from './Popover.js';
+
+export interface PropertyOption {
+  /** What {@link PropertyPickerProps.onChange} hands back. */
+  value: string;
+  /** The row's text, and what the search matches. */
+  label: string;
+  /** A glyph before the label — a type icon, a folder, a swatch. */
+  icon?: ReactNode;
+  /** A short right-aligned note: a count, a parent path. Searched too. */
+  hint?: string;
+  disabled?: boolean;
+}
+
+interface PropertyPickerBase {
+  /**
+   * What the property IS, in sentence case — `Type`, `Folder`, `Tags`. The pill's
+   * accessible name, its tooltip, and the search box's placeholder all derive from it.
+   */
+  name: string;
+  options: readonly PropertyOption[];
+  /** The pill's glyph when the value has none of its own. */
+  icon?: ReactNode;
+  /** What the pill says with nothing chosen. Default `No <name>`. */
+  emptyLabel?: string;
+  /**
+   * Offer to make a value from what was typed: `Create “k8s”`. Called with the trimmed
+   * query; a single picker then has it chosen, a multiple one adds it.
+   */
+  onCreate?: (query: string) => void;
+  /**
+   * One key that opens this picker — `t`, `f`, `T` (Shift+t) — while focus is inside
+   * {@link shortcutScope} and not in a text field. Shown in the tooltip. Linear's issue
+   * panel is the model: the property menus are a keystroke away, never a mouse trip.
+   */
+  shortcut?: string;
+  /** Where {@link shortcut} listens. Without one the key is only advertised, never bound. */
+  shortcutScope?: RefObject<HTMLElement | null>;
+  disabled?: boolean;
+  className?: string;
+}
+
+export interface PropertyPickerSingleProps extends PropertyPickerBase {
+  multiple?: false;
+  value: string | null;
+  onChange: (value: string) => void;
+}
+
+export interface PropertyPickerMultiProps extends PropertyPickerBase {
+  multiple: true;
+  value: readonly string[];
+  onChange: (value: string[]) => void;
+}
+
+export type PropertyPickerProps = PropertyPickerSingleProps | PropertyPickerMultiProps;
+
+/** Is this keydown a bare press of `shortcut` (`T` meaning Shift+t), outside any text entry? */
+export function matchesShortcut(e: Pick<KeyboardEvent, 'key' | 'shiftKey' | 'metaKey' | 'ctrlKey' | 'altKey' | 'target'>, shortcut: string): boolean {
+  if (e.metaKey || e.ctrlKey || e.altKey) return false;
+  const wantShift = shortcut.length === 1 && shortcut !== shortcut.toLowerCase();
+  if (e.key.toLowerCase() !== shortcut.toLowerCase() || e.shiftKey !== wantShift) return false;
+  const t = e.target as HTMLElement | null;
+  if (!t || typeof t.closest !== 'function') return true;
+  return !t.closest('input, textarea, select, [contenteditable=""], [contenteditable="true"], [role="textbox"]');
+}
+
+/** The key as a person reads it in a tooltip: `T`, `⇧T`. */
+function shortcutLabel(shortcut: string): string {
+  return shortcut !== shortcut.toLowerCase() ? `⇧${shortcut.toUpperCase()}` : shortcut.toUpperCase();
+}
+
+/**
+ * **A property pill** — the Type / Folder / Tags row at the top of a record, Linear's issue
+ * panel and Obsidian's properties as one cursedbelt control. The pill shows the value; a
+ * click (or its one-key {@link PropertyPickerProps.shortcut}) opens a searchable list in a
+ * {@link Popover}; arrows and Enter choose; a `multiple` picker stays open and toggles.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────────
+ * The owner, 2026-10-10, on vault's entry form: *"I saw we don't style the dropdowns and that
+ * is a violation of our design requirements … cb should have components that handle this."*
+ * Its Type, Folder and field-kind controls were {@link NativeSelect}s, whose list the OS
+ * draws — on macOS a grey system menu no stylesheet reaches — beside a tree picker and a
+ * chip input that each looked different again. Three controls for one job, one of them not
+ * ours to style. This is the one control for "set a property of this record", drawn
+ * entirely by the kit, searchable the moment the list is long enough to need it.
+ *
+ * ── Which control to reach for ──────────────────────────────────────────────────
+ * - A property of the record being edited, in a header row → this.
+ * - A labelled field in a form column → {@link SelectField} / {@link ComboboxField}.
+ * - Choose-and-act-now (File under…) → {@link ChoiceMenu}.
+ */
+export function PropertyPicker(props: PropertyPickerProps) {
+  const {
+    name,
+    options,
+    icon,
+    emptyLabel,
+    onCreate,
+    shortcut,
+    shortcutScope,
+    disabled,
+    className,
+  } = props;
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState('');
+  const chosen = useMemo(
+    () => new Set(props.multiple ? props.value : props.value === null ? [] : [props.value]),
+    [props.multiple, props.value],
+  );
+
+  useEffect(() => {
+    const scope = shortcutScope?.current;
+    if (!shortcut || !scope || disabled) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.defaultPrevented || !matchesShortcut(e, shortcut)) return;
+      e.preventDefault();
+      setOpen(true);
+    };
+    scope.addEventListener('keydown', onKey);
+    return () => scope.removeEventListener('keydown', onKey);
+  }, [shortcut, shortcutScope, disabled]);
+
+  const setOpenAndReset = (next: boolean) => {
+    setOpen(next);
+    if (!next) setQuery('');
+  };
+
+  const choose = (value: string) => {
+    if (props.multiple) {
+      const next = chosen.has(value) ? props.value.filter((v) => v !== value) : [...props.value, value];
+      props.onChange(next);
+      setQuery('');
+    } else {
+      props.onChange(value);
+      setOpenAndReset(false);
+    }
+  };
+
+  const typed = query.trim();
+  const exact = options.some((o) => o.label.toLowerCase() === typed.toLowerCase());
+  const create = () => {
+    if (!onCreate || typed === '') return;
+    onCreate(typed);
+    if (props.multiple) setQuery('');
+    else setOpenAndReset(false);
+  };
+
+  const byValue = new Map(options.map((o) => [o.value, o]));
+  const picked = [...chosen].map((v) => byValue.get(v) ?? { value: v, label: v });
+  const first = picked[0];
+  const face: ReactNode =
+    picked.length === 0 ? (
+      <span className='text-muted-foreground'>{emptyLabel ?? `No ${name.toLowerCase()}`}</span>
+    ) : props.multiple ? (
+      <span className='truncate'>{picked.map((o) => o.label).join(', ')}</span>
+    ) : (
+      <span className='truncate'>{first?.label}</span>
+    );
+  const glyph = !props.multiple && first && 'icon' in first && first.icon ? first.icon : icon;
+  const tip = shortcut ? `${name} — press ${shortcutLabel(shortcut)}` : name;
+
+  return (
+    <Popover
+      open={open}
+      onOpenChange={setOpenAndReset}
+      align='start'
+      unstyled
+      label={name}
+      trigger={
+        <Button
+          type='button'
+          variant='ghost'
+          size='sm'
+          disabled={disabled}
+          tooltip={tip}
+          aria-label={`${name}: ${picked.length === 0 ? 'none' : picked.map((o) => o.label).join(', ')}`}
+          data-cb-property={name}
+          className={cn(
+            'max-w-64 gap-1.5 rounded-full border border-border px-2.5 font-normal',
+            '[&_svg]:size-3.5 [&_svg]:shrink-0 [&_svg]:text-muted-foreground',
+            className,
+          )}
+        >
+          {glyph}
+          {face}
+        </Button>
+      }
+    >
+      <Command
+        className='w-72 rounded-lg border border-border shadow-popover'
+        // cmdk names its input from this (`aria-labelledby`), over any `aria-label` on it.
+        label={`Search ${name.toLowerCase()}`}
+        loop
+      >
+        <CommandInput
+          value={query}
+          onValueChange={setQuery}
+          placeholder={`${props.multiple ? 'Add' : 'Set'} ${name.toLowerCase()}…`}
+          onKeyDown={(e) => {
+            // Enter on a query nothing matches makes it, the way Linear's label menu does.
+            if (e.key === 'Enter' && onCreate && typed !== '' && !exact) {
+              const anyMatch = options.some((o) => `${o.label} ${o.hint ?? ''}`.toLowerCase().includes(typed.toLowerCase()));
+              if (!anyMatch) {
+                e.preventDefault();
+                create();
+              }
+            }
+          }}
+        />
+        <CommandList maxHeightClassName='max-h-72'>
+          <CommandEmpty>{onCreate && typed !== '' ? 'Nothing matches — Enter creates it.' : 'Nothing matches.'}</CommandEmpty>
+          <CommandGroup>
+            {options.map((o) => (
+              <CommandItem
+                key={o.value}
+                value={`${o.label} ${o.hint ?? ''} ${o.value}`}
+                disabled={o.disabled}
+                onSelect={() => choose(o.value)}
+                data-checked={chosen.has(o.value) ? 'true' : undefined}
+              >
+                {o.icon ? <span className='flex size-4 shrink-0 items-center justify-center text-muted-foreground [&_svg]:size-4'>{o.icon}</span> : null}
+                <span className='min-w-0 flex-1 truncate'>{o.label}</span>
+                {o.hint ? <span className='shrink-0 truncate text-xs text-muted-foreground'>{o.hint}</span> : null}
+                <Check aria-hidden className={cn('size-4 shrink-0 text-foreground', chosen.has(o.value) ? 'opacity-100' : 'opacity-0')} />
+              </CommandItem>
+            ))}
+          </CommandGroup>
+          {onCreate && typed !== '' && !exact ? (
+            <CommandGroup>
+              <CommandItem value={`__create__ ${typed}`} onSelect={create} forceMount>
+                <Plus aria-hidden className='size-4 shrink-0 text-muted-foreground' />
+                <span className='min-w-0 flex-1 truncate'>
+                  Create “{typed}”
+                </span>
+              </CommandItem>
+            </CommandGroup>
+          ) : null}
+        </CommandList>
+      </Command>
+    </Popover>
+  );
+}

package/src/react/components/TooltipImpl.tsx

@@ -57,6 +57,8 @@ export default function TooltipImpl({
   const container = useFloatingContainer();
   const delay = useHoverHintDelay();
   const [open, setOpen] = useState(false);
+  /** Closed by an Escape: the bubble leaves with no exit animation — see the Escape effect. */
+  const [escaped, setEscaped] = useState(false);
   const resolvedSide = placement ?? side ?? 'top';
   const triggerRef = useRef<HTMLElement | null>(null);
   const wasFocusedRef = useRef(false);
@@ -247,15 +249,32 @@ export default function TooltipImpl({
    * update flushes its passive effects too, which is where the layer takes itself off Radix's
    * stack). By the time Radix asks "who is topmost" the hint is gone, and the same keypress
    * closes what is under it. A hint over nothing costs nothing: Escape still reaches the page.
+   *
+   * 🔴 …and it leaves WITHOUT its exit animation (`escaped`). Radix's Presence keeps a closing
+   * bubble mounted until its fade-out ends, and a mounted bubble is still the topmost layer — so
+   * in a real browser the Escape was swallowed anyway; jsdom runs no animation, which is how the
+   * spec above stayed green. Measured in vault (forge task 3016.1, 2026-10-10): close the Type
+   * picker with Escape, focus lands back on its pill, the pill's hint opens, and the next Escape
+   * closed only the hint while the entry sheet stayed up. With `animation: none` Presence unmounts
+   * inside the same `flushSync`. `e2e/overlays.spec.ts` proves it in Chromium.
    */
   useEffect(() => {
     if (!open) return;
     const onKeyDown = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') flushSync(() => setOpen(false));
+      if (event.key === 'Escape') {
+        flushSync(() => {
+          setEscaped(true);
+          setOpen(false);
+        });
+      }
     };
     window.addEventListener('keydown', onKeyDown, true);
     return () => window.removeEventListener('keydown', onKeyDown, true);
   }, [open]);
+  // The next opening animates again.
+  useEffect(() => {
+    if (open) setEscaped(false);
+  }, [open]);
 
   const bubble = (
     <RTooltip.Portal container={container}>
@@ -285,6 +304,7 @@ export default function TooltipImpl({
           // modal has body pointer events disabled).
           'z-50 rounded-md border border-border bg-popover px-2 py-1 text-xs text-popover-foreground shadow-[var(--shadow-overlay)]',
           TOOLTIP_MOTION,
+          escaped && 'animate-none!',
           multiline || maxWidth != null ? 'max-w-xs' : 'whitespace-nowrap',
           className,
         )}

package/src/react/index.ts

@@ -518,6 +518,14 @@ export { TruncatedText, type TruncatedTextProps } from './components/TruncatedTe
 export { UnstyledButton, type UnstyledButtonProps } from './components/UnstyledButton.js';
 export { PluginCard, type PluginCardProps } from './components/PluginCard.js';
 export { Popover, PopoverClose, type PopoverPoint, type PopoverProps } from './components/Popover.js';
+export {
+  matchesShortcut,
+  PropertyPicker,
+  type PropertyOption,
+  type PropertyPickerMultiProps,
+  type PropertyPickerProps,
+  type PropertyPickerSingleProps,
+} from './components/PropertyPicker.js';
 export { FloatingContainer } from './lib/floatingContainer.js';
 export {
   Progress,