@pithyjs/pidl-catalog 0.1.0-beta.0

package/dist/specs/atoms/forms/search-input.pidl.json

@@ -0,0 +1,265 @@
+{
+    "kind": "component",
+    "id": "ui.search-input",
+    "name": "SearchInput",
+    "displayName": "Search input",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "forms",
+    "studioReady": true,
+    "bidi": true,
+    "description": "Search field composed from the <Input> atom — leading magnifier, clear button, optional keyboard-shortcut chip, and a debounced query callback. Renders a <form role=\"search\"> landmark by default, which can be dropped (landmark=false) when the field lives inside a dialog such as <CommandPalette>. This is UI only: it owns no index, no fetching and no results list. Wire onSearch to whatever backend you have — the docs search engine itself lands in R3.",
+    "props": [
+        {
+            "name": "value",
+            "reactive": true,
+            "label": "Value",
+            "type": "string | Signal<string>",
+            "description": "Field value — a static string, or an accessor for a controlled field. Leave unset for an uncontrolled field."
+        },
+        {
+            "name": "placeholder",
+            "reactive": true,
+            "label": "Placeholder",
+            "type": "string | Signal<string>",
+            "default": "Search",
+            "placeholder": "Search the docs",
+            "description": "Placeholder text. An accessor is kept in sync after construction, so a locale switch takes effect without rebuilding the field."
+        },
+        {
+            "name": "label",
+            "label": "Label",
+            "type": "string",
+            "default": "Search",
+            "placeholder": "Search",
+            "description": "Accessible name. Always applied to the field's aria-label, and additionally rendered as a visible <label> when showLabel is true. A whitespace-only value falls back to 'Search' rather than producing an empty accessible name."
+        },
+        {
+            "name": "showLabel",
+            "label": "Show label",
+            "editor": { "tab": "content" },
+            "type": "boolean",
+            "default": false,
+            "description": "Render the label visibly above the field. Off by default: a magnifier plus a placeholder is the established convention for a search box, and a visible label costs a line of vertical space in a navbar."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Control size, passed straight through to <Input> so a search field lines up with every other control on the row."
+        },
+        {
+            "name": "disabled",
+            "label": "Disabled",
+            "editor": { "tab": "settings" },
+            "reactive": true,
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Disabled state — uses the native disabled attribute via <Input>."
+        },
+        {
+            "name": "loading",
+            "label": "Loading",
+            "editor": { "tab": "settings" },
+            "reactive": true,
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Shows the <Input> spinner and sets aria-busy. Use it while a query is in flight; the field stays editable."
+        },
+        {
+            "name": "debounce",
+            "label": "Debounce (ms)",
+            "editor": { "tab": "settings" },
+            "type": "number",
+            "default": 200,
+            "description": "Idle window before onSearch fires. 0 fires it synchronously on every keystroke — right for a local in-memory filter, wrong for anything that hits the network."
+        },
+        {
+            "name": "shortcutHint",
+            "label": "Shortcut hint",
+            "type": "string",
+            "placeholder": "⌘K",
+            "description": "Keyboard shortcut to advertise, rendered as a <kbd> chip in the Input suffix and hidden from assistive tech. Purely a hint for sighted users — it binds nothing. The binding belongs to <CommandPalette>."
+        },
+        {
+            "name": "landmark",
+            "label": "Search landmark",
+            "editor": { "tab": "settings" },
+            "type": "boolean",
+            "default": true,
+            "description": "Wrap the field in <form role=\"search\"> so it appears in a screen reader's landmark list. Set false inside a dialog: a search landmark nested in a modal is a landmark the reader cannot navigate to sensibly, and <CommandPalette> relies on this. Several mounted landmarks must not share a name — give each a distinct label or leave only one as a landmark; DEV warns on duplicates (axe: landmark-unique)."
+        },
+        {
+            "name": "id",
+            "label": "Element id",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Explicit id for the <input>. Generated when omitted — the visible label's `for` is wired to it either way."
+        },
+        {
+            "name": "name",
+            "label": "Name",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "placeholder": "q",
+            "description": "name attribute, for a field that posts to a real search endpoint."
+        },
+        {
+            "name": "autoFocus",
+            "label": "Autofocus",
+            "editor": { "tab": "settings" },
+            "type": "boolean",
+            "default": false,
+            "description": "Focus the field once mounted. Reserve it for a search-first surface (a dialog, a dedicated search page) — stealing focus on an ordinary page moves the reader without asking."
+        },
+        {
+            "name": "class",
+            "label": "Extra classes",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Extra class names appended after 'ui-search-input'."
+        },
+        {
+            "name": "onSearch",
+            "label": "On search",
+            "type": "(query: string) => void",
+            "description": "Debounced query callback — the one to hand a search backend. Fires `debounce` ms after the last change, always with the newest query."
+        },
+        {
+            "name": "onInput",
+            "label": "On input",
+            "type": "(query: string) => void",
+            "description": "Undebounced query callback, on every keystroke. Use it for local UI that must track the field exactly (a character count, a live filter over an array already in memory)."
+        },
+        {
+            "name": "onSubmit",
+            "label": "On submit",
+            "type": "(query: string) => void",
+            "description": "Enter, or a form submit. The pending debounced onSearch is flushed first, so a consumer never sees onSubmit for a query its onSearch was never told about."
+        },
+        {
+            "name": "onClear",
+            "label": "On clear",
+            "type": "() => void",
+            "description": "Fires when the query is deliberately emptied — the clear button, Escape, or clear(). Deleting the last character by hand does NOT fire it; that is an ordinary edit reported through onInput/onSearch."
+        }
+    ],
+    "tokens": {
+        "typography": "--font-size-sm + --font-weight-medium (visible label), --line-height-body; the field's own type scale comes from input.scss",
+        "color": "--color-text (label), --color-text-muted (magnifier at rest), --color-primary (magnifier on focus-within)",
+        "spacing": "--space-sm (label ↔ field, Close Friends)",
+        "icon": "--_input-icon-size — the private custom property input.scss sets per control size, so the magnifier tracks the same scale as the success/error state icon opposite it",
+        "motion": "--motion-transition-color on the magnifier, inside prefers-reduced-motion: no-preference",
+        "kbd": "the design system's kbd-chip mixin (--radius-sm, --border-width-hairline, --color-border, --color-surface, --color-text-muted)"
+    },
+    "spacing": {
+        "label-to-field": "--space-sm (Close Friends) — a label belongs to the field directly beneath it",
+        "icon-to-text": "inherited from .ui-input's --space-xs gap (Lovers) — the magnifier and the query are one unit"
+    },
+    "constraints": [
+        "COMPOSES the <Input> atom — it never renders a bare <input>. Sizing, border, focus ring, hover, disabled, loading and the clear button all come from input.scss, so a search field is visually identical to every other control on the page",
+        "The element is type=\"search\" (set on the element, not through <Input>'s type enum, which lists only the types it styles). WebKit's own cancel button is suppressed in CSS — <Input> already renders a real, keyboard-reachable clear button",
+        "Escape clears a non-empty field and stops there. On an EMPTY field it does nothing and does not stop propagation. That hands the key to an enclosing dialog ONLY if the dialog listens in the bubble phase: <Modal> listens on window in CAPTURE with stopImmediatePropagation(), so inside <CommandPalette> the FIRST Escape closes the dialog and this handler never runs (see the matching constraint in command-palette.pidl.json)",
+        "Enter always preventDefaults — the implicit form submission would reload the page. Callers navigate from onSubmit",
+        "onClear is fired only for a deliberate clear (clear button, Escape, clear()). The clear button is detected in the CAPTURE phase, which is what lets it be told apart from backspacing the last character: <Input>'s own click handler dispatches an identical synthetic input event",
+        "onSearch is debounced; onInput is not. Both fire for the same keystroke — pick one per consumer rather than wiring both to the same handler",
+        "destroy() cancels the pending debounced search, so a component unmounted mid-type never fires a query into a dead consumer",
+        "It owns no results and no request lifecycle. The backend (Pagefind / Fuse over the codex index) is R3"
+    ],
+    "a11y": [
+        "The field always has an accessible name: aria-label by default, plus a real <label for> when showLabel is true",
+        "role=\"search\" on the wrapping <form>, with an aria-label, so the field appears in a screen reader's landmark list under a name — and landmark=false exists precisely so it does NOT when it sits inside a dialog",
+        "Two landmarks of the same role must not share an accessible name (axe: landmark-unique) — a landmark list of identical 'Search' rows is no better than none. No single instance can see the collision, so a DEV-only cross-instance counter warns when duplicates are mounted together",
+        "shortcutHint is aria-hidden. A '⌘K' read aloud as part of the field's surroundings is noise: the chip is a hint for sighted users and binds nothing",
+        "The magnifier is decorative (aria-hidden) — the field's own name already says what it is",
+        "The clear button comes from <Input>: a real <button> that leaves the tab order (tabindex -1 + aria-hidden) while the field is empty, so there is no dead focus stop",
+        "Escape-to-clear is deliberately conditional, and propagation is stopped ONLY when the key actually cleared something. Swallowing Escape on an empty field would trap a keyboard user inside a bubble-phase dialog they were trying to leave. A capture-phase dialog such as <Modal> claims the key before this handler ever sees it",
+        "type=\"search\" earns the field the right virtual keyboard on touch — an enter key labelled 'search'",
+        "The magnifier's focus colour change is decoration on top of the field's own focus ring, never the only focus indicator",
+        "Colour transitions are wrapped in prefers-reduced-motion: no-preference via the a11y motion-safe mixin",
+        "The kbd chip restores a visible border under forced colours, where the background that normally shapes it is discarded"
+    ],
+    "ai": {
+        "synonyms": [
+            "search",
+            "search box",
+            "search field",
+            "search bar",
+            "filter input",
+            "query input",
+            "find",
+            "type to search",
+            "site search",
+            "docs search"
+        ],
+        "avoid": [
+            "hand-rolling <input type=\"search\"> with a magnifier — the clear button, debounce, Escape handling and landmark are exactly what this component exists to own",
+            "leaving landmark=true inside a dialog or a command palette — a search landmark nested in a modal is not navigable as a landmark",
+            "mounting several landmark=true fields that all fall back to the default 'Search' name — the landmark list becomes a row of identical entries; give each a distinct label",
+            "wiring the same handler to BOTH onInput and onSearch — the backend then runs twice per keystroke, once undebounced",
+            "debounce=0 with a network-backed onSearch — that is one request per keystroke",
+            "expecting it to render results: it renders a field. Compose it with your own list, or reach for <CommandPalette> for the dialog shell",
+            "setting autoFocus on an ordinary page — it moves the reader's focus without being asked"
+        ],
+        "patterns": [
+            "Docs header: <SearchInput placeholder=\"'Search the docs'\" shortcutHint=\"'⌘K'\" onSearch=\"runQuery\" />",
+            "Local list filter, no debounce: <SearchInput debounce=\"0\" onInput=\"setFilter\" />",
+            "Inside a dialog: <SearchInput landmark=\"false\" autoFocus=\"true\" onInput=\"setQuery\" />",
+            "Real GET form: <SearchInput name=\"'q'\" onSubmit=\"submitSearch\" />",
+            "Visible label on a dedicated search page: <SearchInput showLabel=\"true\" label=\"'Search articles'\" size=\"'lg'\" />"
+        ]
+    },
+    "designGuidance": {
+        "surface": "The <Input> surface, unmodified — --color-surface at rest, --color-surface-bright on hover. The two affix cells the Input normally paints (the bordered prefix/suffix wells that make a currency symbol read as attached) are stripped here: a magnifier is chrome INSIDE the field, not an affix beside it, so it sits transparent and flush with the text.",
+        "depth": "Flat, plus the Input's focus glow. A search field is a control on the page, not a surface above it.",
+        "borders": "One border, the Input's own, at a width that never changes across states — hover and focus recolour it rather than resize it, so nothing reflows as the reader moves through the form.",
+        "interactivity": "The magnifier warms from --color-text-muted to --color-primary on focus-within. That is decoration layered on the field's real focus ring, never a substitute for it. The clear button appears only once there is something to clear.",
+        "motion": "Colour only, and only outside prefers-reduced-motion: reduce.",
+        "darkMode": "Nothing to do — every value is a --color-* token, so the muted/active relationship inverts with the theme.",
+        "bestPractices": "Give it a placeholder that says what is being searched ('Search the docs'), not just 'Search' — the accessible name already says that. Add shortcutHint only when a shortcut actually exists. Keep the default 200ms debounce for anything network-backed and drop to 0 only for an in-memory filter. In a navbar, use the sm size and let the field flex; on a dedicated search page, lg with showLabel reads as the primary task."
+    },
+    "examples": [
+        {
+            "id": "default",
+            "title": "Docs search",
+            "pithy": "<SearchInput placeholder=\"'Search the docs'\" shortcutHint=\"'⌘K'\" />",
+            "assertions": [
+                "renders <form role='search' class='ui-search-input' aria-label='Search'>",
+                "the field is type='search' with a magnifier in .ui-input-prefix",
+                "the shortcut renders as a <kbd> inside an aria-hidden .ui-input-suffix"
+            ]
+        },
+        {
+            "id": "debounce",
+            "title": "Debounced query",
+            "pithy": "<SearchInput onSearch=\"runQuery\" debounce=\"200\" />",
+            "assertions": [
+                "a burst of keystrokes produces exactly one onSearch call",
+                "the call carries the newest query",
+                "destroy() cancels a pending call"
+            ]
+        },
+        {
+            "id": "clearing",
+            "title": "Clearing",
+            "pithy": "<SearchInput onClear=\"showEverything\" />",
+            "assertions": [
+                "the clear button empties the field and fires onClear",
+                "Escape on a non-empty field clears it and stops propagating",
+                "Escape on an empty field propagates so an enclosing dialog can close",
+                "deleting the last character by hand does not fire onClear"
+            ]
+        },
+        {
+            "id": "in-dialog",
+            "title": "Inside a dialog",
+            "pithy": "<SearchInput landmark=\"false\" autoFocus=\"true\" />",
+            "assertions": [
+                "renders a <div>, not a <form>, and carries no role",
+                "the field takes focus on the microtask after mount"
+            ]
+        }
+    ]
+}