@pithyjs/pidl-catalog 0.1.0-beta.0

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

@@ -0,0 +1,422 @@
+{
+    "kind": "component",
+    "id": "ui.textarea",
+    "name": "Textarea",
+    "displayName": "Textarea",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "forms",
+    "bidi": true,
+    "description": "Textarea atom with auto-resize (CSS field-sizing with JS fallback), floating label, success/error states with shake animation and state icons, helper text, error message with aria-describedby, character counter, clear button, and loading spinner. No validation logic — states driven externally.",
+    "props": [
+        {
+            "name": "id",
+            "label": "ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Explicit textarea ID — overrides auto-generated ID. Used by FormField for label association."
+        },
+        {
+            "name": "name",
+            "label": "Name",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Textarea name attribute for form submission"
+        },
+        {
+            "name": "value",
+            "reactive": true,
+            "label": "Value",
+            "type": "string | Signal<string>",
+            "description": "Textarea value — static string or signal accessor for controlled textarea"
+        },
+        {
+            "name": "placeholder",
+            "label": "Placeholder",
+            "type": "string",
+            "description": "Placeholder text shown when textarea 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 — textarea is not editable but remains focusable. Accepts signal accessor."
+        },
+        {
+            "name": "required",
+            "label": "Required",
+            "type": "boolean",
+            "default": false,
+            "description": "Sets aria-required on the textarea"
+        },
+        {
+            "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 textarea 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 textarea. 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": "Message",
+            "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 inside the textarea, floats to top-inside on focus/fill."
+        },
+        {
+            "name": "autocomplete",
+            "label": "Autocomplete",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Autocomplete hint (e.g., 'off')"
+        },
+        {
+            "name": "maxLength",
+            "label": "Max length",
+            "type": "number",
+            "description": "Maximum character length — also enables character counter display with tabular-nums"
+        },
+        {
+            "name": "rows",
+            "label": "Rows",
+            "editor": { "tab": "layout" },
+            "type": "number",
+            "default": 3,
+            "description": "Initial visible rows. Ignored when autoResize is true and field-sizing is supported."
+        },
+        {
+            "name": "autoResize",
+            "label": "Auto resize",
+            "editor": { "tab": "layout" },
+            "type": "boolean",
+            "default": true,
+            "description": "Enable auto-resize — uses CSS field-sizing: content with JS fallback for Firefox"
+        },
+        {
+            "name": "maxBlockSize",
+            "label": "Max block size",
+            "editor": { "tab": "layout" },
+            "type": "string",
+            "description": "Maximum block-size for auto-resize (CSS value, e.g. '200px', '15rem'). No limit when omitted."
+        },
+        {
+            "name": "minBlockSize",
+            "label": "Min block size",
+            "editor": { "tab": "layout" },
+            "type": "string",
+            "description": "Minimum block-size (CSS value, e.g. '80px', '5rem'). Falls back to rows-based height when omitted."
+        },
+        {
+            "name": "clearable",
+            "label": "Clearable",
+            "type": "boolean",
+            "default": false,
+            "description": "Show clear button when textarea has value. 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 clear button."
+        },
+        {
+            "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) with current value and native Event"
+        },
+        {
+            "name": "onBlur",
+            "type": "(e: FocusEvent) => void",
+            "description": "Fires when textarea loses focus"
+        },
+        {
+            "name": "onFocus",
+            "type": "(e: FocusEvent) => void",
+            "description": "Fires when textarea gains focus"
+        }
+    ],
+    "events": ["input", "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.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 (via --_scroll-bg)",
+        "bg.focus": "--color-surface-bright (via --_scroll-bg)",
+        "bg.readonly": "--color-surface-variant (via --_scroll-bg)",
+        "bg.error": "color-mix(--color-danger 3%, --color-surface) — faint danger wash",
+        "text.placeholder": "--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",
+        "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",
+        "font-size.counter": "--font-size-xs (tabular-nums)",
+        "icon.size": "--_textarea-icon-size mapped per size",
+        "icon.state-success": "--color-success (checkmark)",
+        "icon.state-error": "--color-danger (triangle alert)",
+        "gap.actions": "--space-xs",
+        "gap.sub-text": "--space-xs (helper/error to wrapper)",
+        "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.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-form-shake with --motion-distance-subtle",
+        "success-pop.animation": "--motion-animation-fade-scale-in on false->true transition"
+    },
+    "spacing": {
+        "internal": {
+            "textarea-to-actions": { "relationship": "lovers", "token": "xs" },
+            "icon-to-counter": { "relationship": "lovers", "token": "xs" }
+        },
+        "external": {
+            "wrapper-to-helper": { "relationship": "lovers", "token": "xs" },
+            "wrapper-to-error": { "relationship": "lovers", "token": "xs" },
+            "label-to-textarea": { "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)",
+        "Error takes precedence over success visually",
+        "Error shake skips initial render (firstRun guard)",
+        "Character counter is included in aria-describedby for screen reader access, styled with tabular-nums",
+        "Clear button is a tabbable type='button' — keyboard-accessible",
+        "Loading hides clear button with aria-busy",
+        "Readonly suppresses focus styling — label always floated",
+        "TextareaProps extends FormControlBaseProps",
+        "Auto-resize uses CSS field-sizing: content as progressive enhancement with JS scrollHeight fallback",
+        "Helper text hidden when error message is visible"
+    ],
+    "a11y": [
+        "aria-label from required label prop — set when floatingLabel is false",
+        "Visible <label for='...'> when floatingLabel is true",
+        "aria-invalid='true' when error prop is truthy",
+        "aria-describedby dynamically updated — references error ID when error is active, helper ID when present, counter ID when maxLength is set",
+        "Error message has role='alert' 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",
+        "Focus ring via box-shadow ring() on wrapper :focus-within",
+        "Forced-colors: visible border, GrayText for disabled, Highlight outline on focus",
+        "Auto-generated id on <textarea> — enables FormField <label for='...'> association",
+        "Clicking wrapper focuses the inner textarea",
+        "Clear button has aria-label='Clear', type='button', and :focus-visible ring",
+        "Character counter linked via aria-describedby — screen readers announce count on focus",
+        "State icons have aria-hidden='true'",
+        "Error shake respects prefers-reduced-motion"
+    ],
+    "ai": {
+        "synonyms": [
+            "text area",
+            "multiline input",
+            "comment box",
+            "message field",
+            "multi-line text",
+            "rich text input"
+        ],
+        "avoid": [
+            "div with contentEditable — use <Textarea> component",
+            "hardcoded border colors — use design tokens",
+            "built-in validation — validation belongs in Form/DynamicForm",
+            "visible label in Textarea without floatingLabel — use FormField molecule",
+            "outline: none without alternative — focus ring handled by ring()"
+        ],
+        "patterns": [
+            "Basic: <Textarea label=\"'Bio'\" placeholder=\"'Tell us about yourself'\" />",
+            "Floating label: <Textarea label=\"'Message'\" floatingLabel=\"true\" />",
+            "Character counter: <Textarea label=\"'Bio'\" maxLength=\"500\" />",
+            "Fixed rows: <Textarea label=\"'Notes'\" autoResize=\"false\" rows=\"6\" />",
+            "Max height: <Textarea label=\"'Comment'\" maxBlockSize=\"'200px'\" />",
+            "Clearable: <Textarea label=\"'Search'\" clearable=\"true\" />",
+            "Loading: <Textarea label=\"'Content'\" loading=\"isSaving\" />",
+            "Error: <Textarea label=\"'Message'\" error=\"hasError\" errorMessage=\"'Message is required'\" />",
+            "Helper text: <Textarea label=\"'Bio'\" helperText=\"'Max 500 characters'\" maxLength=\"500\" />",
+            "Success: <Textarea label=\"'Bio'\" success=\"isValid\" />"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Basic textarea",
+            "pithy": "<Textarea label=\"'Bio'\" placeholder=\"'Tell us about yourself'\" />",
+            "assertions": [
+                "auto-resizes on input",
+                "aria-label set",
+                "no violations in axe-core"
+            ]
+        },
+        {
+            "id": "floating-label",
+            "title": "Floating label textarea",
+            "pithy": "<Textarea label=\"'Message'\" floatingLabel=\"true\" />",
+            "assertions": [
+                "visible <label>",
+                "no aria-label",
+                "label floats on focus"
+            ]
+        },
+        {
+            "id": "character-counter",
+            "title": "Textarea with character counter",
+            "pithy": "<Textarea label=\"'Bio'\" maxLength=\"500\" />",
+            "assertions": [
+                "counter shows 0/500",
+                "warn color at 80%",
+                "danger at limit",
+                "tabular-nums"
+            ]
+        },
+        {
+            "id": "fixed-rows",
+            "title": "Fixed rows without auto-resize",
+            "pithy": "<Textarea label=\"'Notes'\" autoResize=\"false\" rows=\"6\" />",
+            "assertions": ["resize: vertical", "no field-sizing", "6 rows visible"]
+        },
+        {
+            "id": "error-shake",
+            "title": "Error with shake animation",
+            "pithy": "<Textarea label=\"'Message'\" error=\"hasError\" />",
+            "assertions": [
+                "aria-invalid on error",
+                "shake animation on transition",
+                "no shake on initial render"
+            ]
+        },
+        {
+            "id": "clearable",
+            "title": "Clearable textarea",
+            "pithy": "<Textarea label=\"'Comment'\" clearable=\"true\" />",
+            "assertions": [
+                "clear button hidden when empty",
+                "clear button visible with value",
+                "clears on click"
+            ]
+        },
+        {
+            "id": "readonly",
+            "title": "Readonly textarea",
+            "pithy": "<Textarea label=\"'Terms'\" readonly=\"true\" value=\"'Non-editable content'\" />",
+            "assertions": [
+                "textarea is not editable",
+                "data-readonly on wrapper",
+                "remains focusable"
+            ]
+        },
+        {
+            "id": "loading",
+            "title": "Loading textarea",
+            "pithy": "<Textarea label=\"'Content'\" loading=\"isSaving\" />",
+            "assertions": [
+                "spinner visible",
+                "aria-busy='true'",
+                "clear button hidden"
+            ]
+        },
+        {
+            "id": "success",
+            "title": "Success textarea",
+            "pithy": "<Textarea label=\"'Bio'\" success=\"isValid\" />",
+            "assertions": [
+                "data-success on wrapper",
+                "checkmark icon visible",
+                "green border"
+            ]
+        },
+        {
+            "id": "helper-text",
+            "title": "Textarea with helper text",
+            "pithy": "<Textarea label=\"'Bio'\" helperText=\"'Max 500 characters'\" maxLength=\"500\" />",
+            "assertions": [
+                "helper text visible below",
+                "linked via aria-describedby",
+                "hidden when error active"
+            ]
+        }
+    ],
+    "designGuidance": {
+        "surface": "Transparent inner textarea on --color-surface wrapper. Hover brightens to --color-surface-bright. Focus also uses --color-surface-bright. Readonly uses --color-surface-variant.",
+        "depth": "No shadow by default. Focus ring via box-shadow ring() with --ring-offset: 0px.",
+        "borders": "Stable border width — only border-color changes across states.",
+        "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. Auto-resize grows textarea as user types. Clear button appears as an absolutely positioned control inside the wrapper when value present.",
+        "bestPractices": "Use autoResize (default) for most cases. Set maxBlockSize to cap growth. Use fixed rows for code/log fields. Combine maxLength with helperText for best UX. Use loading for async save feedback."
+    }
+}