@pithyjs/pidl-catalog 0.1.0-beta.0

package/dist/specs/atoms/forms/select.pidl.json

@@ -0,0 +1,420 @@
+{
+    "kind": "component",
+    "id": "ui.select",
+    "name": "Select",
+    "displayName": "Select",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "forms",
+    "bidi": true,
+    "description": "Custom select dropdown atom with searchable options, keyboard navigation, success/error states with shake animation and state icons, helper text, error message with aria-describedby, clear button, and loading spinner. No validation logic — states driven externally.",
+    "props": [
+        {
+            "name": "options",
+            "reactive": true,
+            "label": "Options",
+            "type": "SelectOption[] | Signal<SelectOption[]>",
+            "required": true,
+            "placeholder": [
+                { "value": "us", "label": "United States" },
+                { "value": "ca", "label": "Canada" },
+                { "value": "uk", "label": "United Kingdom" }
+            ],
+            "description": "Options to display in the dropdown. Each option has value, label, and optional disabled flag.",
+            "itemSchema": {
+                "value": { "type": "string", "required": true },
+                "label": { "type": "string", "required": true },
+                "disabled": { "type": "boolean" }
+            }
+        },
+        {
+            "name": "id",
+            "label": "ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Explicit trigger ID — overrides auto-generated ID. Used by FormField for label association."
+        },
+        {
+            "name": "name",
+            "label": "Name",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Select name attribute for form submission via hidden native <select>"
+        },
+        {
+            "name": "value",
+            "reactive": true,
+            "label": "Value",
+            "type": "string | Signal<string>",
+            "description": "Selected value — static string or signal accessor for controlled select"
+        },
+        {
+            "name": "placeholder",
+            "label": "Placeholder",
+            "type": "string",
+            "description": "Placeholder text shown when no option is selected"
+        },
+        {
+            "name": "disabled",
+            "label": "Disabled",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Disabled state — prevents opening and interaction. Accepts signal accessor."
+        },
+        {
+            "name": "readonly",
+            "label": "Read-only",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Readonly state — trigger is not interactive but remains focusable. Accepts signal accessor."
+        },
+        {
+            "name": "required",
+            "label": "Required",
+            "type": "boolean",
+            "default": false,
+            "description": "Sets aria-required on trigger + red asterisk on placeholder via data-required"
+        },
+        {
+            "name": "error",
+            "label": "Error",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Visual error state — sets aria-invalid, shows red border + alert icon, shakes on transition. No validation logic."
+        },
+        {
+            "name": "errorMessage",
+            "label": "Error message",
+            "editor": { "tab": "settings" },
+            "type": "string | Signal<string>",
+            "description": "Error message shown below select when error is truthy. Linked via aria-describedby with role='alert'. Replaces helper text when visible."
+        },
+        {
+            "name": "helperText",
+            "label": "Helper text",
+            "type": "string",
+            "description": "Persistent hint text below select. Hidden when error message is visible. Linked via aria-describedby."
+        },
+        {
+            "name": "success",
+            "label": "Success",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Visual success state — shows green border + checkmark icon. Error takes precedence when both are true."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Control size — maps to u-control-* utilities (padding, min-height, gap)"
+        },
+        {
+            "name": "label",
+            "label": "Label",
+            "type": "string",
+            "required": true,
+            "placeholder": "Country",
+            "description": "Accessible label — used as aria-label on the trigger button"
+        },
+        {
+            "name": "searchable",
+            "label": "Searchable",
+            "type": "boolean",
+            "default": false,
+            "description": "Enable search/filter input in the dropdown. Filters options by label as user types."
+        },
+        {
+            "name": "clearable",
+            "label": "Clearable",
+            "type": "boolean",
+            "default": false,
+            "description": "Show clear button when a value is selected. Hidden when disabled, readonly, or loading."
+        },
+        {
+            "name": "loading",
+            "label": "Loading",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Loading state — shows spinner, sets aria-busy, hides chevron and clear button."
+        },
+        {
+            "name": "onChange",
+            "type": "(value: string, option: SelectOption | undefined) => void",
+            "description": "Fires when the selected value changes, with the value and matching option object"
+        },
+        {
+            "name": "onBlur",
+            "type": "(e: FocusEvent) => void",
+            "description": "Fires when select loses focus (entire component, not just trigger)"
+        },
+        {
+            "name": "onFocus",
+            "type": "(e: FocusEvent) => void",
+            "description": "Fires when trigger gains focus"
+        }
+    ],
+    "events": ["change", "blur", "focus"],
+    "slots": [],
+    "tokens": {
+        "border.default": "border(control) — stable width, color-only changes",
+        "border.hover": "--color-primary (border-color) + --color-surface-bright (bg tint)",
+        "border.focus": "--color-focus-ring + ring() box-shadow (--ring-offset: 0px)",
+        "border.open": "Same as focus — ring persists while dropdown is visible",
+        "border.error": "--color-danger + shake animation on transition",
+        "border.success": "--color-success + --ring-color: --color-success",
+        "border.disabled": "opacity via --state-disabled-opacity",
+        "bg.default": "--color-surface",
+        "bg.hover": "--color-surface-bright",
+        "bg.focus": "--color-surface-bright",
+        "bg.readonly": "--color-surface-variant",
+        "bg.dropdown": "--color-surface with --shadow-lg",
+        "bg.option-hover": "state-background(hover) mixin with --color-primary",
+        "bg.option-pressed": "state-background(pressed) mixin with --color-primary",
+        "bg.option-selected": "color-mix --color-primary at --state-selected-opacity",
+        "text.placeholder": "--color-text-muted at opacity 0.65",
+        "text.option": "--color-text",
+        "text.option-selected": "--color-primary + --font-weight-medium",
+        "text.empty": "--color-text-muted (centered)",
+        "text.helper": "--color-text-muted (--font-size-xs)",
+        "text.error-message": "--color-danger (--font-size-xs)",
+        "radius": "--radius-md (via u-radius-md)",
+        "radius.dropdown": "--radius-md",
+        "radius.search": "--radius-sm",
+        "radius.option": "--radius-sm (pill-like hover with margin-inline: xs)",
+        "scrollbar": "thin scrollbar-width with --color-border thumb",
+        "search.highlight": "<mark> wraps matched text with --color-primary + --font-weight-semibold",
+        "focus.ring": "ring() with --ring-offset: 0px",
+        "disabled.opacity": "--state-disabled-opacity",
+        "font-size.sm": "--font-size-xs",
+        "font-size.md": "--font-size-sm",
+        "font-size.lg": "--font-size-body",
+        "icon.chevron": "--_select-icon-size mapped per size, rotates 180deg when open, darkens to --color-text on hover/open",
+        "icon.check": "--icon-size-sm (selected option checkmark, --color-primary)",
+        "icon.state-success": "--color-success (checkmark)",
+        "icon.state-error": "--color-danger (triangle alert)",
+        "icon.clear": "--_select-icon-size (× button)",
+        "gap.trigger": "--space-xs (between value, icons, chevron)",
+        "gap.option": "--space-xs (label to check)",
+        "gap.sub-text": "--space-xs (helper/error to trigger)",
+        "dropdown.z-index": "var(--_select-dropdown-z) default 100",
+        "dropdown.max-height": "var(--_select-dropdown-max-block) default 15rem",
+        "dropdown.animation.open": "--motion-animation-slide-up (entrance), --motion-animation-slide-down when flipped to top",
+        "dropdown.animation.close": "--motion-animation-fade-out with exit easing",
+        "dropdown.flip": "Auto-flips to top (data-placement='top') when insufficient viewport space below",
+        "shake.animation": "ui-form-shake (shared form keyframe)",
+        "success-pop.animation": "--motion-animation-fade-scale-in on false→true transition",
+        "spinner.animation": "--motion-animation-spin",
+        "spinner.adaptive": "--color-text-muted default, --color-danger on error, --color-success on success",
+        "listbox.scroll-shadows": "background-attachment:local fade indicators using --_scroll-bg, --state-hover-opacity, --space-lg/sm",
+        "search.focus-ring": "var(--ring-color) inherited from wrapper — adapts to error/success state"
+    },
+    "spacing": {
+        "internal": {
+            "trigger-gap": { "relationship": "lovers", "token": "xs" },
+            "option-padding-inline": { "relationship": "friends", "token": "md" },
+            "option-padding-block": {
+                "relationship": "close_friends",
+                "token": "sm"
+            },
+            "search-padding": { "relationship": "lovers", "token": "xs" },
+            "listbox-padding-block": { "relationship": "lovers", "token": "xs" }
+        },
+        "external": {
+            "trigger-to-dropdown": { "relationship": "lovers", "token": "xs" },
+            "select-to-helper": { "relationship": "lovers", "token": "xs" },
+            "select-to-error": { "relationship": "lovers", "token": "xs" },
+            "label-to-select": { "relationship": "close_friends", "token": "sm" },
+            "field-to-field": { "relationship": "friends", "token": "md" }
+        }
+    },
+    "constraints": [
+        "Never use raw hex colors — use design system tokens",
+        "Use logical CSS properties only (margin-inline-start, not margin-left)",
+        "All transitions wrapped in @include a11y.motion-safe",
+        "Must handle forced-colors mode — add visible border for ButtonText",
+        "No validation logic — error/success props are visual only",
+        "Label prop is required — used as aria-label on the combobox trigger",
+        "Error takes precedence over success visually (CSS source order + state icon priority)",
+        "Error shake skips initial render (firstRun guard)",
+        "Error shake uses shared ui-form-shake keyframe from _form-animations.scss",
+        "Dropdown animation uses design system --motion-animation-slide-down",
+        "Loading hides chevron and clear button with aria-busy",
+        "Readonly prevents dropdown from opening — trigger shows variant background",
+        "SelectProps extends FormControlBaseProps — shared form control interface",
+        "Helper text hidden when error message is visible (error replaces helper)",
+        "State icons auto-injected: checkmark for success (pop-in animation), triangle alert for error",
+        "Hidden native <select> for form submission (aria-hidden, tabindex=-1)",
+        "Dropdown closes on outside click, Escape, Tab, focusout, and ancestor scroll",
+        "Search input filters options by label (case-insensitive) with matching text highlighted via <mark>",
+        "Keyboard navigation skips disabled options",
+        "Type-ahead: typing characters on closed trigger jumps to matching option (500ms buffer)",
+        "Escape in search clears query first, second Escape closes dropdown",
+        "Trigger is <div role=combobox> not <button> — allows nested clear <button> (valid HTML)",
+        "Trigger has user-select: none to prevent text selection on drag",
+        "Required shows red asterisk on placeholder via CSS ::after"
+    ],
+    "a11y": [
+        "role='combobox' on trigger button — standard ARIA combobox pattern",
+        "aria-haspopup='listbox' — indicates dropdown type",
+        "aria-expanded toggles with dropdown open/close state",
+        "aria-controls links trigger to listbox element",
+        "aria-activedescendant tracks keyboard-highlighted option",
+        "aria-label from required label prop on trigger",
+        "aria-invalid='true' when error prop is truthy",
+        "aria-describedby links to error message and/or helper text",
+        "Error message has role='alert' (assertive live region)",
+        "aria-required='true' when required prop is true",
+        "aria-busy='true' when loading is true",
+        "role='listbox' on dropdown option list",
+        "role='option' on each option with aria-selected",
+        "aria-disabled='true' on disabled options",
+        "role='searchbox' on search input with aria-autocomplete='list'",
+        "Search input has aria-label='Search {label}' and aria-controls to listbox",
+        "Auto-generated id on trigger — enables FormField <label for> association",
+        "Keyboard nav: ArrowDown/Up, Enter/Space to select, Escape to close, Home/End, PageUp/PageDown (5 options)",
+        "aria-live='polite' region announces filtered option count for screen readers",
+        "State icon has aria-hidden='true' — decorative, not announced",
+        "Escape stopPropagation prevents closing parent modals",
+        "Focus ring via box-shadow ring() on trigger :focus-visible",
+        "Forced-colors: visible borders, Highlight for active/selected, GrayText for disabled",
+        "Clear button has aria-label='Clear selection' and type='button'",
+        "Empty state has role='presentation' (not interactive)"
+    ],
+    "ai": {
+        "synonyms": [
+            "dropdown",
+            "select box",
+            "picker",
+            "combo box",
+            "select input",
+            "option list"
+        ],
+        "avoid": [
+            "native <select> element — use <Select> component for consistent styling",
+            "hardcoded border colors — use design tokens",
+            "built-in validation — validation belongs in Form/DynamicForm",
+            "visible label in Select — use FormField molecule for external label",
+            "outline: none without alternative — focus ring handled by ring()"
+        ],
+        "patterns": [
+            "Basic: <Select label=\"'Country'\" options=\"countries\" />",
+            "Placeholder: <Select label=\"'Status'\" options=\"statuses\" placeholder=\"'Choose...'\" />",
+            "Searchable: <Select label=\"'Country'\" options=\"countries\" searchable=\"true\" />",
+            "Clearable: <Select label=\"'Priority'\" options=\"priorities\" clearable=\"true\" />",
+            "Controlled: <Select label=\"'Role'\" options=\"roles\" value=\"selectedRole\" onChange=\"handleChange\" />",
+            "Error state: <Select label=\"'Category'\" options=\"categories\" error=\"hasError\" errorMessage=\"'Required field'\" />",
+            "Helper text: <Select label=\"'Region'\" options=\"regions\" helperText=\"'Choose your nearest region'\" />",
+            "Loading: <Select label=\"'Team'\" options=\"teams\" loading=\"isLoading\" />",
+            "With FormField: <FormField label=\"'Country'\" required=\"true\"><Select label=\"'Country'\" options=\"countries\" required=\"true\" /></FormField>"
+        ]
+    },
+    "itemSchema": {
+        "SelectOption": {
+            "value": {
+                "type": "string",
+                "required": true,
+                "description": "Option value used as selected value"
+            },
+            "label": {
+                "type": "string",
+                "required": true,
+                "description": "Display label shown in dropdown and trigger"
+            },
+            "disabled": {
+                "type": "boolean",
+                "description": "Whether this option is disabled"
+            }
+        }
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Basic select with options",
+            "pithy": "<Select label=\"'Country'\" options=\"countries\" placeholder=\"'Select a country'\" />",
+            "assertions": [
+                "renders trigger button",
+                "shows placeholder",
+                "opens dropdown on click",
+                "no violations in axe-core"
+            ]
+        },
+        {
+            "id": "searchable",
+            "title": "Searchable select",
+            "pithy": "<Select label=\"'Country'\" options=\"countries\" searchable=\"true\" />",
+            "assertions": [
+                "search input in dropdown",
+                "filters options by label",
+                "keyboard nav works in search"
+            ]
+        },
+        {
+            "id": "clearable",
+            "title": "Clearable select",
+            "pithy": "<Select label=\"'Priority'\" options=\"priorities\" clearable=\"true\" value=\"selectedPriority\" />",
+            "assertions": [
+                "clear button hidden when empty",
+                "clear button visible with value",
+                "clears on click"
+            ]
+        },
+        {
+            "id": "error",
+            "title": "Error state with message",
+            "pithy": "<Select label=\"'Category'\" options=\"categories\" error=\"hasError\" errorMessage=\"'Please select a category'\" />",
+            "assertions": [
+                "aria-invalid on error",
+                "shake animation on transition",
+                "error message visible",
+                "role='alert'"
+            ]
+        },
+        {
+            "id": "success",
+            "title": "Success state",
+            "pithy": "<Select label=\"'Status'\" options=\"statuses\" success=\"true\" value=\"'active'\" />",
+            "assertions": [
+                "data-success on wrapper",
+                "green border",
+                "checkmark icon visible"
+            ]
+        },
+        {
+            "id": "loading",
+            "title": "Loading state",
+            "pithy": "<Select label=\"'Team'\" options=\"teams\" loading=\"isLoading\" />",
+            "assertions": [
+                "spinner visible",
+                "aria-busy='true'",
+                "chevron hidden",
+                "dropdown blocked"
+            ]
+        },
+        {
+            "id": "keyboard-nav",
+            "title": "Full keyboard navigation",
+            "pithy": "<Select label=\"'Role'\" options=\"roles\" />",
+            "assertions": [
+                "Enter/Space opens",
+                "ArrowDown/Up navigates",
+                "Enter selects",
+                "Escape closes",
+                "Home/End jump"
+            ]
+        }
+    ],
+    "designGuidance": {
+        "surface": "Trigger on --color-surface, hover brightens to --color-surface-bright. Dropdown on --color-surface with --shadow-lg. Readonly trigger uses --color-surface-variant. Selected options have faint primary bg tint.",
+        "depth": "No shadow on trigger by default. Focus ring via box-shadow ring(). Dropdown has --shadow-lg for elevated depth. Options have rounded corners with inline margin for pill-like hover.",
+        "borders": "Stable border width — only border-color changes across states. Dropdown has card border. Search input has control border.",
+        "interactivity": "Hover changes border color + subtle bg tint. Focus shows ring. Open state keeps ring active. Chevron rotates 180deg + darkens on hover/open. Options highlight on hover/keyboard with pressed state on click. Error shakes on transition. Success shows checkmark pop-in. Dropdown slides up on open, fades out on close. Auto-flips to top when near viewport bottom. Search highlights matching text. Type-ahead on closed trigger.",
+        "bestPractices": "Use searchable for long option lists (>7 items). Use clearable when selection is optional. Use placeholder to hint expected selection. Combine with FormField for visible label. Error/success are mutually exclusive (error wins). Loading blocks interaction."
+    }
+}