@pithyjs/pidl-catalog 0.1.0-beta.0

package/dist/specs/atoms/forms/radio-group.pidl.json

@@ -0,0 +1,174 @@
+{
+    "kind": "component",
+    "id": "ui.radio-group",
+    "name": "RadioGroup",
+    "displayName": "Radio Group",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "forms",
+    "bidi": true,
+    "description": "Accessible group wrapper for related <Radio> controls. Renders <fieldset><legend> with optional helper/error text and aria-describedby wiring. Native fieldset[disabled] cascades to all child radios. Children are projected through the full PithyJS pipeline. Does NOT auto-inject `name` onto children — each <Radio> must declare its own.",
+    "props": [
+        {
+            "name": "id",
+            "label": "ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Explicit fieldset ID — overrides auto-generated ID."
+        },
+        {
+            "name": "label",
+            "label": "Label",
+            "type": "string",
+            "required": true,
+            "placeholder": "Pick one",
+            "description": "Required group label rendered inside <legend>. Provides the accessible name for the group."
+        },
+        {
+            "name": "hideLabel",
+            "label": "Hide label",
+            "type": "boolean",
+            "default": false,
+            "description": "Visually hide the legend (still announced by screen readers via .u-visually-hidden)."
+        },
+        {
+            "name": "helperText",
+            "label": "Helper text",
+            "type": "string",
+            "description": "Persistent helper text below the group. Wired via aria-describedby when no error is shown."
+        },
+        {
+            "name": "errorMessage",
+            "label": "Error message",
+            "type": "string | Signal<string>",
+            "description": "Error message rendered in a span with role='alert'. Linked via aria-describedby when error is truthy. Accepts a signal accessor for reactive updates."
+        },
+        {
+            "name": "error",
+            "label": "Error",
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Visual error state — sets aria-invalid='true' and data-error on the fieldset. Error message only displays when both error and errorMessage are set. Accepts a signal accessor for reactive updates."
+        },
+        {
+            "name": "disabled",
+            "label": "Disabled",
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Disables the entire group via native fieldset[disabled], cascading to every child radio without extra plumbing. Accepts a signal accessor for reactive updates."
+        }
+    ],
+    "events": [],
+    "slots": [
+        {
+            "name": "default",
+            "displayName": "Radios",
+            "description": "Children projected through renderChildren() — typically <Radio> elements but any markup is supported. The fieldset is marked as a site-builder drop zone.",
+            "accepts": ["ui.radio"]
+        }
+    ],
+    "tokens": {
+        "legend.color": "--color-text",
+        "helper.color": "--color-text-muted",
+        "error.color": "--color-danger",
+        "group.gap": "--space-sm"
+    },
+    "spacing": {
+        "internal": {
+            "legend-to-children": { "relationship": "close_friends", "token": "sm" },
+            "children-to-helper": { "relationship": "lovers", "token": "xs" },
+            "children-to-error": { "relationship": "lovers", "token": "xs" }
+        }
+    },
+    "constraints": [
+        "Use semantic <fieldset role='radiogroup'>/<legend> — never a div with role='group'",
+        "label prop is required — every group must have an accessible name",
+        "Native fieldset[disabled] (not aria-disabled) — cascades automatically to children",
+        "Error message only shown when both error=true and errorMessage are set",
+        "Children must be Radio controls (or compose them) — group semantics assume radio descendants",
+        "data-slot='children' is required on the fieldset for site-builder drop targeting",
+        "RadioGroup does NOT auto-inject `name` onto children — each <Radio> must declare its own `name` explicitly",
+        "Siblings sharing the same `name` are mutually exclusive and share arrow-key navigation"
+    ],
+    "a11y": [
+        "Native <fieldset role='radiogroup'><legend> — explicit radiogroup role for assistive technology",
+        "label always rendered inside <legend> (visually hidden via hideLabel when needed)",
+        "aria-invalid='true' when error prop is truthy",
+        "aria-describedby points to helper id (no error) or error id (when shown)",
+        "Error message has role='alert' for live region announcement",
+        "fieldset[disabled] cascades native disabled state to all child controls",
+        "Auto-generated id enables external aria-describedby/labelling"
+    ],
+    "ai": {
+        "synonyms": [
+            "radio set",
+            "radio list",
+            "single-select group",
+            "fieldset",
+            "option group",
+            "radio button group"
+        ],
+        "avoid": [
+            "Wrapping a single Radio in RadioGroup — use Radio directly",
+            "Using FormField around individual Radios — Radio already provides its own label; use RadioGroup for grouped controls",
+            "div with role='group' or role='radiogroup' — use the native <fieldset> via <RadioGroup>",
+            "Omitting the label prop — the group must have an accessible name",
+            "Adding aria-disabled — use the native disabled prop instead",
+            "Expecting RadioGroup to auto-inject name — it doesn't, set name on each Radio"
+        ],
+        "patterns": [
+            "Basic: <RadioGroup label=\"'Plan'\"><Radio label=\"'Free'\" name=\"'plan'\" value=\"'free'\" /><Radio label=\"'Pro'\" name=\"'plan'\" value=\"'pro'\" /></RadioGroup>",
+            "With helper: <RadioGroup label=\"'Plan'\" helperText=\"'Choose your subscription'\">...</RadioGroup>",
+            "With error: <RadioGroup label=\"'Plan'\" error=\"hasError\" errorMessage=\"'Please select a plan'\">...</RadioGroup>",
+            "Disabled (cascades): <RadioGroup label=\"'Locked options'\" disabled=\"true\">...</RadioGroup>",
+            "Visually hidden legend: <RadioGroup label=\"'Sort order'\" hideLabel=\"true\">...</RadioGroup>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Basic radio group",
+            "pithy": "<RadioGroup label=\"'Plan'\"><Radio label=\"'Free'\" name=\"'plan'\" value=\"'free'\" /><Radio label=\"'Pro'\" name=\"'plan'\" value=\"'pro'\" /></RadioGroup>",
+            "assertions": [
+                "fieldset > legend with label text",
+                "data-slot='children' on fieldset",
+                "no axe violations"
+            ]
+        },
+        {
+            "id": "helper",
+            "title": "Group with helper text",
+            "pithy": "<RadioGroup label=\"'Plan'\" helperText=\"'Choose your subscription'\"><Radio label=\"'Free'\" name=\"'plan'\" value=\"'free'\" /></RadioGroup>",
+            "assertions": ["helper rendered", "aria-describedby points to helper id"]
+        },
+        {
+            "id": "error",
+            "title": "Group with error",
+            "pithy": "<RadioGroup label=\"'Plan'\" error=\"true\" errorMessage=\"'Please select a plan'\"><Radio label=\"'Free'\" name=\"'plan'\" value=\"'free'\" /></RadioGroup>",
+            "assertions": [
+                "aria-invalid='true' on fieldset",
+                "error span with role='alert' visible",
+                "aria-describedby points to error id"
+            ]
+        },
+        {
+            "id": "disabled-cascade",
+            "title": "Disabled group cascades to children",
+            "pithy": "<RadioGroup label=\"'Locked'\" disabled=\"true\"><Radio label=\"'Free'\" name=\"'plan'\" value=\"'free'\" /></RadioGroup>",
+            "assertions": ["fieldset[disabled]", "child input matches :disabled"]
+        },
+        {
+            "id": "hide-label",
+            "title": "Visually hidden legend",
+            "pithy": "<RadioGroup label=\"'Sort order'\" hideLabel=\"true\"><Radio label=\"'Newest'\" name=\"'sort'\" value=\"'new'\" /></RadioGroup>",
+            "assertions": ["legend present", "legend has u-visually-hidden class"]
+        }
+    ],
+    "designGuidance": {
+        "surface": "No background by default — inherits the page surface. The group is a semantic container, not a visual card.",
+        "depth": "Flat — no shadow or elevation. Children carry their own focus state.",
+        "borders": "No border on the fieldset itself (UA defaults reset). Visual grouping comes from spacing, not chrome.",
+        "interactivity": "Stateless wrapper — interactivity lives on individual Radio children. fieldset[disabled] cascades native disabled to descendants without per-child wiring. Arrow keys navigate between siblings sharing the same `name`.",
+        "bestPractices": "Always pair related radios inside a RadioGroup. Use a clear, concise legend label. Prefer native disabled over per-child disabling. Use hideLabel sparingly — only when surrounding context already provides the accessible name. Ensure all child Radios share the same `name` attribute for mutual exclusion and keyboard navigation."
+    }
+}

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

@@ -0,0 +1,312 @@
+{
+    "kind": "component",
+    "id": "ui.radio",
+    "name": "Radio",
+    "displayName": "Radio",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "forms",
+    "bidi": true,
+    "description": "Accessible radio button atom with a custom-rendered circle and inline SVG inner dot (animated via transform/opacity), error/success states with shake animation, helper/error text, loading spinner, arrow-key navigation across siblings sharing a `name`, and full a11y wiring. No validation logic — states driven externally.",
+    "props": [
+        {
+            "name": "id",
+            "label": "ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Explicit input ID — overrides auto-generated ID."
+        },
+        {
+            "name": "name",
+            "label": "Name",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "required": true,
+            "description": "Input name attribute. Required — radios sharing the same name form a mutually exclusive group and share arrow-key navigation."
+        },
+        {
+            "name": "value",
+            "label": "Value",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "required": true,
+            "description": "Submitted value when this radio is selected."
+        },
+        {
+            "name": "checked",
+            "label": "Checked",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Checked state — static or signal accessor for controlled radio."
+        },
+        {
+            "name": "disabled",
+            "label": "Disabled",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Disabled state — uses native disabled attribute."
+        },
+        {
+            "name": "readonly",
+            "label": "Read-only",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Readonly state — focusable but not toggleable. Native input ignores readonly, so toggling is intercepted via click preventDefault, Space keydown preventDefault, and a change-event rollback to the controlled value."
+        },
+        {
+            "name": "required",
+            "label": "Required",
+            "type": "boolean",
+            "default": false,
+            "description": "Sets aria-required and adds a visual asterisk to the label."
+        },
+        {
+            "name": "error",
+            "label": "Error",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Visual error state — sets aria-invalid, red ring, shake on transition."
+        },
+        {
+            "name": "errorMessage",
+            "label": "Error message",
+            "editor": { "tab": "settings" },
+            "type": "string | Signal<string>",
+            "description": "Error message shown below the radio when error is truthy. Linked via aria-describedby with role='alert'."
+        },
+        {
+            "name": "helperText",
+            "label": "Helper text",
+            "type": "string",
+            "description": "Persistent hint text below the radio. Hidden when error is visible."
+        },
+        {
+            "name": "success",
+            "label": "Success",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Visual success state — green border / fill. Error takes precedence."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Control size — drives circle dimensions and label font-size."
+        },
+        {
+            "name": "label",
+            "label": "Label",
+            "type": "string",
+            "required": true,
+            "placeholder": "Option label",
+            "description": "Visible label text rendered next to the circle. Always required."
+        },
+        {
+            "name": "loading",
+            "label": "Loading",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Loading state — overlays a spinner inside the circle and sets aria-busy."
+        },
+        {
+            "name": "onChange",
+            "type": "(checked: boolean, e: Event) => void",
+            "description": "Fires whenever the checked state changes to true."
+        },
+        {
+            "name": "onBlur",
+            "type": "(e: FocusEvent) => void",
+            "description": "Fires when the radio loses focus."
+        },
+        {
+            "name": "onFocus",
+            "type": "(e: FocusEvent) => void",
+            "description": "Fires when the radio gains focus."
+        }
+    ],
+    "events": ["change", "blur", "focus"],
+    "slots": [],
+    "tokens": {
+        "circle.size.sm": "calc(var(--font-size-xs) * 1.25)",
+        "circle.size.md": "calc(var(--font-size-sm) * 1.25)",
+        "circle.size.lg": "calc(var(--font-size-body) * 1.25)",
+        "circle.bg.default": "--color-surface",
+        "circle.border.default": "border(control)",
+        "circle.border.checked": "--color-primary",
+        "circle.border.hover": "--color-primary",
+        "circle.border.error": "--color-danger",
+        "circle.border.success": "--color-success",
+        "circle.radius": "50%",
+        "dot.color": "--color-primary",
+        "label.color": "--color-text",
+        "label.color.error": "--color-danger",
+        "focus.ring": "ring() with --ring-offset: 2px",
+        "disabled.opacity": "--state-disabled-opacity",
+        "required.indicator": "--color-danger asterisk",
+        "active.scale": "--motion-scale-big",
+        "shake.animation": "ui-form-shake",
+        "touch-target": "a11y.touch-target-pseudo (--control-min-touch)",
+        "spinner.color": "--_cmp-spinner-color → --color-primary (default), --color-danger (error), --color-success (success, scoped with :not([data-error]) so error wins)"
+    },
+    "spacing": {
+        "internal": {
+            "circle-to-label": { "relationship": "lovers", "token": "xs" }
+        },
+        "external": {
+            "wrapper-to-helper": { "relationship": "lovers", "token": "xs" },
+            "wrapper-to-error": { "relationship": "lovers", "token": "xs" },
+            "radio-to-radio": { "relationship": "close_friends", "token": "sm" }
+        }
+    },
+    "constraints": [
+        "Never use raw hex colors — use design system tokens",
+        "Use logical CSS properties only",
+        "All transitions wrapped in @include a11y.motion-safe",
+        "Must handle forced-colors mode — Highlight for checked, GrayText for disabled",
+        "No validation logic — error/success props are visual only",
+        "Label prop is required",
+        "`name` prop is required — radios without a name cannot form a group",
+        "Radios cannot be un-checked by the user — selecting another radio in the same `name` group un-checks the previous one",
+        "Arrow Up/Left moves focus+check to the previous sibling radio with the same `name`; Arrow Down/Right moves to the next. Disabled siblings are skipped. Wraps at the ends",
+        "Native disabled (not aria-disabled)",
+        "Error takes precedence over success visually",
+        "Error shake skips initial render (firstRun guard)",
+        "Readonly is custom — native radios ignore the readonly attribute. Toggling is blocked via click preventDefault, Space keydown preventDefault, and a change-event rollback that restores the controlled value if a stray event slips through",
+        "Inner dot rendered as an inline SVG <circle>, animated via transform scale(0)→scale(1) + opacity",
+        "Native input is visually hidden but stays focusable; visual focus ring is on .ui-radio-circle via :has(:focus-visible)",
+        "State icon is kept detached (never in the DOM) — the custom circle conveys all state; applyFormState mutates the detached element without injecting unnecessary DOM nodes",
+        "Fieldset[disabled] cascade — when disabled via a parent <fieldset disabled>, hover/active/pressed styles are suppressed via :not(:has(.ui-radio-input:disabled)) guards on hover and active selectors; desaturation + cursor applied via a dedicated cascade rule",
+        "RadioProps extends FormControlBaseProps",
+        "`RadioGroup` does NOT auto-inject `name` onto children — each `<Radio>` must declare its own"
+    ],
+    "a11y": [
+        "Native <input type='radio'> — full keyboard support (Space selects)",
+        "Arrow keys navigate between siblings sharing `name` (custom handler — sr-only input defeats the UA default)",
+        "Wrapper is a <label> — clicking anywhere selects the input",
+        "aria-invalid='true' when error prop is truthy",
+        "aria-describedby dynamically updated for helper/error",
+        "Error message has role='alert'",
+        "aria-required='true' when required",
+        "Readonly signaled via data-readonly + aria-description='Read-only' — aria-readonly is disallowed on role=radio per ARIA spec; toggling is blocked in JS",
+        "aria-busy='true' when loading",
+        "Auto-generated id enables FormField association",
+        "Focus ring on the visible circle via :has(:focus-visible)",
+        "Forced-colors: Highlight for checked, GrayText for disabled, Highlight outline on focus",
+        "Custom circle has aria-hidden='true' (decorative — input is the real control)",
+        "Error shake respects prefers-reduced-motion"
+    ],
+    "ai": {
+        "synonyms": [
+            "radio button",
+            "option button",
+            "single-select option",
+            "choice button",
+            "mutually exclusive choice"
+        ],
+        "avoid": [
+            "div with role='radio' — use the native input via <Radio>",
+            "raw color values for circle / dot — use design tokens",
+            "validation inside the component — belongs in Form/DynamicForm",
+            "Radio without a label prop",
+            "Radio without a name prop — radios need a name to group",
+            "multiple Radios in the same group with different `name` values — they won't be mutually exclusive",
+            "RadioGroup trying to auto-inject name — it doesn't, set it per Radio"
+        ],
+        "patterns": [
+            "Basic: <Radio label=\"'Cheese'\" name=\"'topping'\" value=\"'cheese'\" />",
+            "Required: <Radio label=\"'I agree'\" name=\"'consent'\" value=\"'yes'\" required=\"true\" />",
+            "Controlled: <Radio label=\"'Pro'\" name=\"'plan'\" value=\"'pro'\" checked=\"isPro\" onChange=\"selectPro\" />",
+            "Helper text: <Radio label=\"'Email'\" name=\"'contact'\" value=\"'email'\" helperText=\"'We will only email important updates'\" />",
+            "Error: <Radio label=\"'Accept'\" name=\"'tos'\" value=\"'yes'\" error=\"hasError\" errorMessage=\"'Required'\" />",
+            "Group: <RadioGroup label=\"'Plan'\"><Radio label=\"'Free'\" name=\"'plan'\" value=\"'free'\" /><Radio label=\"'Pro'\" name=\"'plan'\" value=\"'pro'\" /></RadioGroup>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Basic radio",
+            "pithy": "<Radio label=\"'Cheese'\" name=\"'topping'\" value=\"'cheese'\" />",
+            "assertions": [
+                "renders <input type='radio'>",
+                "label is visible",
+                "no axe violations"
+            ]
+        },
+        {
+            "id": "checked",
+            "title": "Pre-checked radio",
+            "pithy": "<Radio label=\"'Pro'\" name=\"'plan'\" value=\"'pro'\" checked=\"true\" />",
+            "assertions": ["input.checked === true", "data-checked on wrapper"]
+        },
+        {
+            "id": "disabled",
+            "title": "Disabled radio",
+            "pithy": "<Radio label=\"'Locked'\" name=\"'x'\" value=\"'x'\" disabled=\"true\" />",
+            "assertions": ["input.disabled === true", "data-disabled on wrapper"]
+        },
+        {
+            "id": "readonly",
+            "title": "Readonly radio",
+            "pithy": "<Radio label=\"'Auto-set'\" name=\"'x'\" value=\"'x'\" readonly=\"true\" checked=\"true\" />",
+            "assertions": [
+                "click does not toggle",
+                "Space does not toggle",
+                "remains focusable"
+            ]
+        },
+        {
+            "id": "required",
+            "title": "Required radio",
+            "pithy": "<Radio label=\"'I agree'\" name=\"'x'\" value=\"'y'\" required=\"true\" />",
+            "assertions": ["aria-required on input", "asterisk visible on label"]
+        },
+        {
+            "id": "error",
+            "title": "Error with shake",
+            "pithy": "<Radio label=\"'Accept'\" name=\"'x'\" value=\"'y'\" error=\"hasError\" errorMessage=\"'Required'\" />",
+            "assertions": [
+                "aria-invalid on input",
+                "shake animation on transition",
+                "error message shown"
+            ]
+        },
+        {
+            "id": "success",
+            "title": "Success state",
+            "pithy": "<Radio label=\"'Verified'\" name=\"'x'\" value=\"'y'\" success=\"true\" checked=\"true\" />",
+            "assertions": ["data-success on wrapper", "green ring"]
+        },
+        {
+            "id": "loading",
+            "title": "Loading state",
+            "pithy": "<Radio label=\"'Saving'\" name=\"'x'\" value=\"'y'\" loading=\"isSaving\" />",
+            "assertions": ["spinner visible", "aria-busy='true'"]
+        },
+        {
+            "id": "group",
+            "title": "Radio group with fieldset",
+            "pithy": "<RadioGroup label=\"'Plan'\"><Radio label=\"'Free'\" name=\"'plan'\" value=\"'free'\" /><Radio label=\"'Pro'\" name=\"'plan'\" value=\"'pro'\" /></RadioGroup>",
+            "assertions": [
+                "fieldset contains legend",
+                "data-slot='children' on fieldset",
+                "fieldset[disabled] cascades",
+                "arrow keys move between radios"
+            ]
+        }
+    ],
+    "designGuidance": {
+        "surface": "Circle uses --color-surface by default. On checked, the ring adopts --color-primary and the inner dot scales in. Hover deepens the ring to --color-primary-hover.",
+        "depth": "No shadow by default. Colored micro-shadow under the ring when checked. Focus ring via box-shadow ring() with 2px offset on the visible circle.",
+        "borders": "Stable border width — only color changes across states. Circle is always a perfect circle (border-radius: 50%).",
+        "interactivity": "Hover tints border. Active applies pressed state-background and a subtle compression. Focus shows ring on the circle. Error shakes on transition. Arrow keys navigate siblings sharing the same `name`. Loading overlays spinner inside the circle.",
+        "bestPractices": "Always provide a label, a name, and a value. Use <RadioGroup> to wrap related radios with a legend and helper/error text. Use disabled (not readonly) when the option is permanently unavailable; use readonly when the chosen value is meaningful but locked. For exactly two mutually exclusive options, prefer <Toggle> unless both options deserve labels."
+    }
+}