@pithyjs/pidl-catalog 0.1.0-beta.0

package/dist/specs/atoms/forms/form-field.pidl.json

@@ -0,0 +1,106 @@
+{
+    "kind": "component",
+    "id": "ui.form-field",
+    "name": "FormField",
+    "displayName": "Form Field",
+    "version": "0.1.0",
+    "level": "molecule",
+    "domain": "forms",
+    "bidi": true,
+    "description": "Form field molecule — wraps a form atom (Input, Select, Textarea) with a visible label and optional required asterisk indicator. Provides label-to-input association via <label for>.",
+    "props": [
+        {
+            "name": "label",
+            "label": "Label",
+            "type": "string",
+            "required": true,
+            "placeholder": "Field label",
+            "description": "Visible label text displayed above the input"
+        },
+        {
+            "name": "required",
+            "label": "Required",
+            "type": "boolean",
+            "default": false,
+            "description": "Whether the field is required — shows red asterisk indicator after label"
+        },
+        {
+            "name": "inputId",
+            "label": "Input ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Explicit input ID — passed to <label for> and should match child input's id prop. Auto-generated if omitted."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Control size — matches label font to input size via shared control-font-sizes"
+        }
+    ],
+    "slots": [{ "name": "default", "displayName": "Content" }],
+    "tokens": {
+        "gap.label-to-input": "--space-sm (close friends)",
+        "text.label": "--color-text, --font-weight-medium",
+        "text.required": "--color-danger, --font-weight-bold",
+        "font-size": "shared.$control-font-sizes per size"
+    },
+    "spacing": {
+        "internal": {
+            "label-to-input": { "relationship": "close_friends", "token": "sm" },
+            "label-to-asterisk": { "relationship": "lovers", "token": "xs" }
+        }
+    },
+    "constraints": [
+        "Label is required — every form field needs a visible label",
+        "Required asterisk is aria-hidden (label text conveys required status via aria-required on the input)",
+        "Child input must receive the same id via its id prop for label association",
+        "Uses shared $control-font-sizes map for consistent sizing across form atoms"
+    ],
+    "a11y": [
+        "Visible <label for='...'> provides accessible name for the input",
+        "Required asterisk has aria-hidden='true' — decorative, input's aria-required conveys state",
+        "Label is clickable — focuses the associated input"
+    ],
+    "ai": {
+        "synonyms": [
+            "form field",
+            "field wrapper",
+            "label wrapper",
+            "form group",
+            "field group"
+        ],
+        "avoid": [
+            "Wrapping input without matching id — label association will break",
+            "Using FormField with floatingLabel Input — redundant visible labels"
+        ],
+        "patterns": [
+            "Basic: <FormField label=\"'Email'\"><Input label=\"'Email'\" type=\"'email'\" /></FormField>",
+            "Required: <FormField label=\"'Email'\" required=\"true\"><Input label=\"'Email'\" required=\"true\" /></FormField>",
+            "With helper: <FormField label=\"'Email'\"><Input label=\"'Email'\" helperText=\"'We will never share it'\" /></FormField>",
+            "With error: <FormField label=\"'Email'\"><Input label=\"'Email'\" error=\"hasError\" errorMessage=\"'Invalid'\" /></FormField>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Basic form field",
+            "pithy": "<FormField label=\"'Email'\"><Input label=\"'Email'\" type=\"'email'\" /></FormField>",
+            "assertions": ["visible label", "label for matches input id"]
+        },
+        {
+            "id": "required",
+            "title": "Required field with asterisk",
+            "pithy": "<FormField label=\"'Email'\" required=\"true\"><Input label=\"'Email'\" required=\"true\" /></FormField>",
+            "assertions": ["asterisk visible", "asterisk aria-hidden"]
+        }
+    ],
+    "designGuidance": {
+        "surface": "No background — transparent wrapper, label inherits text color.",
+        "borders": "No borders — the child input handles its own border styling.",
+        "interactivity": "Label click focuses the associated input. Required asterisk is purely visual.",
+        "bestPractices": "Always pair FormField with Input's label prop (for aria-label fallback). Don't combine with floatingLabel — use one or the other. Pass the same id to both FormField.inputId and Input.id for label association."
+    }
+}

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

@@ -0,0 +1,466 @@
+{
+    "kind": "component",
+    "id": "ui.input",
+    "name": "Input",
+    "displayName": "Input",
+    "version": "0.3.0",
+    "level": "atom",
+    "domain": "forms",
+    "bidi": true,
+    "description": "Text input atom with floating label, success/error states with shake animation and state icons, helper text, error message with aria-describedby, character counter, clear button, password visibility toggle, loading spinner, and polished prefix/suffix grouping. No validation logic — states driven externally.",
+    "props": [
+        {
+            "name": "type",
+            "label": "Type",
+            "type": "enum",
+            "enum": ["text", "email", "password", "number", "tel", "url"],
+            "default": "text",
+            "description": "HTML input type — standard text-like types only (date/file deferred)"
+        },
+        {
+            "name": "id",
+            "label": "ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Explicit input ID — overrides auto-generated ID. Used by FormField for label association."
+        },
+        {
+            "name": "name",
+            "label": "Name",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Input name attribute for form submission"
+        },
+        {
+            "name": "value",
+            "reactive": true,
+            "label": "Value",
+            "type": "string | Signal<string>",
+            "description": "Input value — static string or signal accessor for controlled input"
+        },
+        {
+            "name": "placeholder",
+            "label": "Placeholder",
+            "type": "string",
+            "description": "Placeholder text shown when input is empty"
+        },
+        {
+            "name": "disabled",
+            "label": "Disabled",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Disabled state — uses native disabled attribute. Accepts signal accessor."
+        },
+        {
+            "name": "readonly",
+            "label": "Read-only",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Readonly state — input is not editable but remains focusable. Accepts signal accessor."
+        },
+        {
+            "name": "required",
+            "label": "Required",
+            "type": "boolean",
+            "default": false,
+            "description": "Sets aria-required on the input"
+        },
+        {
+            "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 input 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 input. 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": "Email",
+            "description": "Accessible label — used as aria-label or as floating label text when floatingLabel is true"
+        },
+        {
+            "name": "floatingLabel",
+            "label": "Floating label",
+            "type": "boolean",
+            "default": false,
+            "description": "Enable floating label — label starts centered inside the input (like a placeholder), floats to top-inside on focus/fill. Uses visible <label for> instead of aria-label."
+        },
+        {
+            "name": "autocomplete",
+            "label": "Autocomplete",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Autocomplete hint (e.g., 'email', 'current-password', 'off')"
+        },
+        {
+            "name": "maxLength",
+            "label": "Max length",
+            "type": "number",
+            "description": "Maximum character length — also enables character counter display with tabular-nums"
+        },
+        {
+            "name": "min",
+            "label": "Min",
+            "editor": { "type": "number" },
+            "type": "number | string",
+            "description": "Minimum value — primarily for type='number'"
+        },
+        {
+            "name": "max",
+            "label": "Max",
+            "editor": { "type": "number" },
+            "type": "number | string",
+            "description": "Maximum value — primarily for type='number'"
+        },
+        {
+            "name": "step",
+            "label": "Step",
+            "editor": { "type": "number" },
+            "type": "number | string",
+            "description": "Step value — primarily for type='number'"
+        },
+        {
+            "name": "clearable",
+            "label": "Clearable",
+            "type": "boolean",
+            "default": false,
+            "description": "Show clear button when input has value. Hidden when disabled, readonly, or loading."
+        },
+        {
+            "name": "showPasswordToggle",
+            "label": "Show password toggle",
+            "type": "boolean",
+            "description": "Show password visibility toggle (eye icon). Auto-enabled for password inputs, can be opted out — true when type='password', false otherwise. Conditional on `type`, so there is no static default."
+        },
+        {
+            "name": "loading",
+            "label": "Loading",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Loading state — shows spinner, sets aria-busy, hides suffix, clear button, and password toggle."
+        },
+        {
+            "name": "prefix",
+            "type": "() => ComponentHandle",
+            "description": "Leading content slot — renders with tinted background and separator border"
+        },
+        {
+            "name": "suffix",
+            "type": "() => ComponentHandle",
+            "description": "Trailing content slot — renders with tinted background and separator border. Hidden during loading."
+        },
+        {
+            "name": "onInput",
+            "type": "(value: string, e: InputEvent) => void",
+            "description": "Fires on every keystroke with current value and native InputEvent"
+        },
+        {
+            "name": "onChange",
+            "type": "(value: string, e: Event) => void",
+            "description": "Fires on commit (blur/Enter) with current value and native Event"
+        },
+        {
+            "name": "onBlur",
+            "type": "(e: FocusEvent) => void",
+            "description": "Fires when input loses focus"
+        },
+        {
+            "name": "onFocus",
+            "type": "(e: FocusEvent) => void",
+            "description": "Fires when input gains focus"
+        }
+    ],
+    "events": ["input", "change", "blur", "focus"],
+    "slots": [
+        {
+            "name": "prefix",
+            "displayName": "Prefix",
+            "description": "Icon or label at the inline-start of the input.",
+            "accepts": ["ui.icon", "ui.text"],
+            "max": 1
+        },
+        {
+            "name": "suffix",
+            "displayName": "Suffix",
+            "description": "Icon or action button at the inline-end of the input.",
+            "accepts": ["ui.icon", "ui.button"],
+            "max": 1
+        }
+    ],
+    "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, no double-border)",
+        "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 (via --_scroll-bg)",
+        "bg.hover": "--color-surface-bright (subtle tint on hover)",
+        "bg.focus": "--color-surface-bright (tint on active field)",
+        "bg.readonly": "--color-surface-variant",
+        "bg.error": "color-mix(--color-danger 3%, --color-surface) — faint danger wash",
+        "bg.prefix-suffix": "--color-surface-variant (tinted grouping)",
+        "text.placeholder": "--color-text-muted",
+        "text.prefix-suffix": "--color-text-muted",
+        "text.counter": "--color-text-muted → --color-warning → --color-danger",
+        "text.helper": "--color-text-muted (--font-size-xs)",
+        "text.error-message": "--color-danger (--font-size-xs)",
+        "text.label-resting": "--color-text-muted",
+        "text.label-floating": "--color-primary (focus) / --color-text-muted (filled)",
+        "text.label-error": "--color-danger",
+        "text.label-success": "--color-success",
+        "radius": "--radius-md (via u-radius-md)",
+        "focus.ring": "ring() with --ring-offset: 0px — no double-border gap",
+        "disabled.opacity": "--state-disabled-opacity",
+        "font-size.sm": "--font-size-xs",
+        "font-size.md": "--font-size-sm",
+        "font-size.lg": "--font-size-body",
+        "font-size.label-floating": "--font-size-xs (scaled 0.85)",
+        "font-size.counter": "--font-size-xs (tabular-nums)",
+        "icon.size": "--_input-icon-size mapped per size (--icon-size-xs / --icon-size-sm / --icon-size-md)",
+        "icon.password-toggle": "--icon-size-md (always, interactive control needs readable detail)",
+        "icon.state-success": "--color-success (checkmark)",
+        "icon.state-error": "--color-danger (triangle alert)",
+        "gap.prefix-suffix": "--space-xs",
+        "gap.sub-text": "--space-xs (helper/error to input)",
+        "spinner.border": "--border-width-thin",
+        "caret.default": "--color-primary",
+        "caret.error": "--color-danger",
+        "caret.success": "--color-success",
+        "selection.default": "color-mix(--color-primary, --state-selected-opacity)",
+        "selection.error": "color-mix(--color-danger, --state-selected-opacity)",
+        "selection.success": "color-mix(--color-success, --state-selected-opacity)",
+        "spinner.animation": "--motion-animation-spin",
+        "spinner.adaptive": "--color-text-muted default, --color-danger on error, --color-success on success",
+        "required.indicator": "--color-danger asterisk on floating label via [data-required]",
+        "shake.animation": "ui-input-shake with --motion-distance-subtle",
+        "success-pop.animation": "--motion-animation-fade-scale-in on false→true transition",
+        "error-message.animation": "--motion-animation-fade-in on appear",
+        "helper-text.animation": "--motion-animation-fade-in on reappear (after error clears)"
+    },
+    "spacing": {
+        "internal": {
+            "prefix-to-input": { "relationship": "lovers", "token": "xs" },
+            "input-to-suffix": { "relationship": "lovers", "token": "xs" }
+        },
+        "external": {
+            "input-to-helper": { "relationship": "lovers", "token": "xs" },
+            "input-to-error": { "relationship": "lovers", "token": "xs" },
+            "label-to-input": { "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 or floating label text",
+        "Uses native disabled (not aria-disabled) — disabled inputs don't need to stay focusable",
+        "Error takes precedence over success visually (CSS source order + state icon priority)",
+        "Floating label + prefix = DEV warning (position conflict)",
+        "Error shake skips initial render (firstRun guard)",
+        "Character counter is aria-hidden (decorative) with tabular-nums",
+        "Clear button is a tabbable type='button' — keyboard-accessible, participates in tab order",
+        "Password toggle is a tabbable type='button' — keyboard-accessible, participates in tab order",
+        "Loading hides suffix, clear button, and password toggle with aria-busy",
+        "Readonly suppresses focus styling (no ring, no border change, no bg tint) — label always floated",
+        "InputProps extends FormControlBaseProps — shared form control interface for Input, Select, Textarea",
+        "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",
+        "Error message and helper text fade in using --motion-animation-fade-in",
+        "Success icon uses --motion-animation-fade-scale-in on false→true transition (skips initial render)",
+        "Icon sizes use --_input-icon-size custom prop mapped to --icon-size-* per control size"
+    ],
+    "a11y": [
+        "aria-label from required label prop — set when floatingLabel is false",
+        "Visible <label for='...'> when floatingLabel is true — replaces aria-label",
+        "aria-invalid='true' when error prop is truthy — triggers red border + shake",
+        "aria-describedby dynamically updated — references error ID only when error is active, helper ID when present",
+        "Error message has role='alert' (assertive live region) for screen reader announcement",
+        "aria-required='true' when required prop is true",
+        "aria-busy='true' when loading is true",
+        "Native disabled attribute — removes from tab order (correct for inputs)",
+        "Focus ring via box-shadow ring() on wrapper :focus-within (--ring-offset: 0px)",
+        "Forced-colors: visible border, GrayText for disabled, Highlight outline on focus",
+        "Auto-generated id on <input> — enables FormField <label for='...'> association",
+        "Clicking wrapper focuses the inner input",
+        "Clear button has aria-label='Clear', type='button', and :focus-visible ring",
+        "Password toggle has aria-label='Show password'/'Hide password', aria-pressed toggle, type='button', and :focus-visible ring",
+        "Character counter has aria-hidden='true' (browser enforces maxLength)",
+        "State icons have aria-hidden='true' (decorative, state conveyed via border + aria-invalid)",
+        "Error shake respects prefers-reduced-motion"
+    ],
+    "ai": {
+        "synonyms": [
+            "text field",
+            "text input",
+            "form field",
+            "text box",
+            "input field",
+            "form input"
+        ],
+        "avoid": [
+            "div or span as input — use <Input> component",
+            "hardcoded border colors — use design tokens",
+            "built-in validation — validation belongs in Form/DynamicForm",
+            "visible label in Input without floatingLabel — use FormField molecule",
+            "outline: none without alternative — focus ring handled by ring()",
+            "manual eye icon for password — use built-in showPasswordToggle"
+        ],
+        "patterns": [
+            "Floating label: <Input label=\"'Email'\" floatingLabel=\"true\" type=\"'email'\" />",
+            "Clearable: <Input label=\"'Search'\" clearable=\"true\" />",
+            "Character counter: <Input label=\"'Bio'\" maxLength=\"200\" />",
+            "Loading: <Input label=\"'Username'\" loading=\"isChecking\" />",
+            "Success state: <Input label=\"'Email'\" success=\"isValid\" />",
+            "Error state: <Input label=\"'Email'\" error=\"hasError\" />",
+            "Error with message: <Input label=\"'Email'\" error=\"hasError\" errorMessage=\"emailError\" />",
+            "Helper text: <Input label=\"'Email'\" helperText=\"'We will never share your email'\" />",
+            "Helper + error swap: <Input label=\"'Email'\" helperText=\"'Enter your email'\" error=\"hasError\" errorMessage=\"'Invalid email'\" />",
+            "Password: <Input label=\"'Password'\" type=\"'password'\" />",
+            "Password no toggle: <Input label=\"'API Key'\" type=\"'password'\" showPasswordToggle=\"false\" />",
+            "With prefix: <Input label=\"'Price'\" prefix=\"currencyPrefix\" type=\"'number'\" />",
+            "All features: <Input label=\"'Name'\" floatingLabel=\"true\" clearable=\"true\" maxLength=\"50\" helperText=\"'Your display name'\" />"
+        ]
+    },
+    "examples": [
+        {
+            "id": "floating-label",
+            "title": "Floating label input",
+            "pithy": "<Input label=\"'Email Address'\" floatingLabel=\"true\" type=\"'email'\" />",
+            "assertions": [
+                "visible <label>",
+                "no aria-label",
+                "label floats on focus",
+                "no violations in axe-core"
+            ]
+        },
+        {
+            "id": "clearable",
+            "title": "Clearable input",
+            "pithy": "<Input label=\"'Search'\" clearable=\"true\" placeholder=\"'Search...'\" />",
+            "assertions": [
+                "clear button hidden when empty",
+                "clear button visible with value",
+                "clears on click"
+            ]
+        },
+        {
+            "id": "character-counter",
+            "title": "Input with character counter",
+            "pithy": "<Input label=\"'Bio'\" maxLength=\"200\" placeholder=\"'Tell us about yourself'\" />",
+            "assertions": [
+                "counter shows 0/200",
+                "warn color at 80%",
+                "danger at limit",
+                "tabular-nums"
+            ]
+        },
+        {
+            "id": "loading",
+            "title": "Loading state",
+            "pithy": "<Input label=\"'Username'\" loading=\"isChecking\" />",
+            "assertions": [
+                "spinner visible",
+                "aria-busy='true'",
+                "suffix hidden",
+                "password toggle hidden"
+            ]
+        },
+        {
+            "id": "success",
+            "title": "Success state with checkmark",
+            "pithy": "<Input label=\"'Email'\" success=\"true\" value=\"'valid@email.com'\" />",
+            "assertions": [
+                "data-success on wrapper",
+                "green border",
+                "checkmark icon visible"
+            ]
+        },
+        {
+            "id": "error-shake",
+            "title": "Error with shake animation and alert icon",
+            "pithy": "<Input label=\"'Email'\" error=\"hasError\" />",
+            "assertions": [
+                "aria-invalid on error",
+                "shake animation on transition",
+                "no shake on initial render",
+                "alert triangle icon visible"
+            ]
+        },
+        {
+            "id": "error-message",
+            "title": "Error with message",
+            "pithy": "<Input label=\"'Email'\" error=\"hasError\" errorMessage=\"'Invalid email'\" />",
+            "assertions": [
+                "error message visible when error=true",
+                "aria-describedby links to error",
+                "role='alert'"
+            ]
+        },
+        {
+            "id": "helper-text",
+            "title": "Helper text with error swap",
+            "pithy": "<Input label=\"'Email'\" helperText=\"'We will never share your email'\" error=\"hasError\" errorMessage=\"'Invalid email'\" />",
+            "assertions": [
+                "helper visible by default",
+                "helper hidden when error active",
+                "error replaces helper"
+            ]
+        },
+        {
+            "id": "password-toggle",
+            "title": "Password with visibility toggle",
+            "pithy": "<Input label=\"'Password'\" type=\"'password'\" />",
+            "assertions": [
+                "eye icon visible",
+                "toggles input type on click",
+                "aria-label updates"
+            ]
+        }
+    ],
+    "designGuidance": {
+        "surface": "Transparent inner input on --color-surface wrapper. Hover brightens to --color-surface-bright. Focus also uses --color-surface-bright. Readonly uses --color-surface-variant. Prefix/suffix have tinted --color-surface-variant background.",
+        "depth": "No shadow by default. Focus ring via box-shadow ring() with --ring-offset: 0px (no double-border gap).",
+        "borders": "Stable border width — only border-color changes across states. Prefix/suffix have hairline separator borders.",
+        "interactivity": "Hover changes border color + subtle bg tint. Focus shows ring + bg tint. Error shakes on transition + shows alert icon. Success shows checkmark icon with pop-in bounce. Error message fades in. Helper text fades in when reappearing. Loading shows spinner. Clear button fades in when value present. Password toggle auto-appears for type='password'.",
+        "bestPractices": "Use floatingLabel for polished forms. Combine clearable + maxLength for best UX. Use loading for async validation feedback. Use helperText for persistent hints, errorMessage for validation feedback — error replaces helper automatically. Error/success are mutually exclusive (error wins). Password toggle is automatic — opt out only when needed (e.g., API key fields)."
+    }
+}