@pithyjs/pidl-catalog 0.1.0-beta.0

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

@@ -0,0 +1,314 @@
+{
+    "kind": "component",
+    "id": "ui.toggle",
+    "name": "Toggle",
+    "displayName": "Toggle",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "forms",
+    "bidi": true,
+    "description": "Accessible toggle / switch atom with a pill-shaped track and sliding thumb knob, role='switch' with aria-checked, error/success states with shake animation, helper/error text, loading spinner, 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",
+            "description": "Input name attribute for form submission."
+        },
+        {
+            "name": "value",
+            "label": "Value",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "default": "on",
+            "description": "Submitted value when the toggle is on."
+        },
+        {
+            "name": "checked",
+            "label": "Checked",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Checked (on) state — static or signal accessor for controlled toggle."
+        },
+        {
+            "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."
+        },
+        {
+            "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 track border, shake on transition."
+        },
+        {
+            "name": "errorMessage",
+            "label": "Error message",
+            "editor": { "tab": "settings" },
+            "type": "string | Signal<string>",
+            "description": "Error message shown below the toggle when error is truthy. Linked via aria-describedby with role='alert'."
+        },
+        {
+            "name": "helperText",
+            "label": "Helper text",
+            "type": "string",
+            "description": "Persistent hint text below the toggle. Hidden when error is visible."
+        },
+        {
+            "name": "success",
+            "label": "Success",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Visual success state — green track border / fill. Error takes precedence."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Control size — drives track/thumb dimensions and label font-size."
+        },
+        {
+            "name": "label",
+            "label": "Label",
+            "type": "string",
+            "required": true,
+            "placeholder": "Enable notifications",
+            "description": "Visible label text rendered next to the track. Always required."
+        },
+        {
+            "name": "loading",
+            "label": "Loading",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Loading state — overlays a spinner inside the track and sets aria-busy."
+        },
+        {
+            "name": "onChange",
+            "type": "(checked: boolean, e: Event) => void",
+            "description": "Fires whenever the checked state changes."
+        },
+        {
+            "name": "onBlur",
+            "type": "(e: FocusEvent) => void",
+            "description": "Fires when the toggle loses focus."
+        },
+        {
+            "name": "onFocus",
+            "type": "(e: FocusEvent) => void",
+            "description": "Fires when the toggle gains focus."
+        }
+    ],
+    "events": ["change", "blur", "focus"],
+    "slots": [],
+    "tokens": {
+        "track.height.sm": "calc(var(--font-size-xs) * 1.25)",
+        "track.height.md": "calc(var(--font-size-sm) * 1.25)",
+        "track.height.lg": "calc(var(--font-size-body) * 1.25)",
+        "track.width": "calc(track-height * 2)",
+        "track.bg.off": "--color-surface-variant",
+        "track.bg.on": "--color-primary",
+        "track.bg.on.hover": "--color-primary-hover",
+        "track.bg.error": "--color-danger",
+        "track.bg.success": "--color-success",
+        "track.border.default": "border(control) for width/style with border-color overridden to color-mix(in oklch, --color-border 80%, --color-text) — strengthened off-state contrast for ≥3:1 in dark mode",
+        "track.border.hover": "--color-primary",
+        "track.border.error": "--color-danger",
+        "track.border.success": "--color-success",
+        "track.radius": "--radius-pill",
+        "thumb.bg": "--color-on-primary",
+        "thumb.size": "calc(track-height - --_cmp-border-width * 2 - --border-width-hairline * 2)",
+        "thumb.radius": "50%",
+        "thumb.shadow": "--shadow-sm (unchecked), --shadow-md (checked/hover) — depth separation, no ring",
+        "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",
+        "shake.animation": "ui-form-shake",
+        "touch-target": "a11y.touch-target-pseudo (--control-min-touch)",
+        "spinner.color": "--_cmp-spinner-color → --color-primary (default), --color-on-primary (checked), --color-danger (error), --color-success (success)"
+    },
+    "spacing": {
+        "internal": {
+            "track-to-label": { "relationship": "lovers", "token": "xs" }
+        },
+        "external": {
+            "wrapper-to-helper": { "relationship": "lovers", "token": "xs" },
+            "wrapper-to-error": { "relationship": "lovers", "token": "xs" }
+        }
+    },
+    "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 track, GrayText for disabled",
+        "No validation logic — error/success props are visual only",
+        "Label prop is required",
+        "Native disabled (not aria-disabled)",
+        "Error takes precedence over success visually",
+        "Error shake skips initial render (firstRun guard)",
+        "Readonly is custom — native checkboxes ignore the readonly attribute. Toggling is blocked via click preventDefault, Space keydown preventDefault, and a change-event rollback",
+        "Native input has role='switch' — required for correct AT announcement",
+        "aria-checked must be synced to checked state (required by role='switch')",
+        "Track + thumb are purely decorative — aria-hidden on track",
+        "Thumb slides via inset-inline-start (logical property for RTL)",
+        "Fieldset[disabled] cascade — when disabled via a parent <fieldset disabled>, hover/active/pressed styles are suppressed via :not(:has(.ui-toggle-input:disabled)) guards on hover and active selectors; desaturation + cursor applied via a dedicated cascade rule",
+        "ToggleProps extends FormControlBaseProps"
+    ],
+    "a11y": [
+        "Native <input type='checkbox' role='switch'> — keyboard Space toggles",
+        "aria-checked synced to checked state (required by role='switch')",
+        "Wrapper is a <label> — clicking anywhere toggles 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",
+        "aria-readonly='true' when readonly",
+        "aria-busy='true' when loading",
+        "Auto-generated id enables FormField association",
+        "Focus ring on the visible track via :has(:focus-visible)",
+        "Forced-colors: Highlight for checked track, HighlightText for checked thumb, GrayText for disabled",
+        "Track has aria-hidden='true' (decorative — input is the real control)",
+        "Error shake respects prefers-reduced-motion",
+        "44px minimum touch target via touch-target-pseudo mixin (invisible hit area on wrapper)"
+    ],
+    "ai": {
+        "synonyms": [
+            "switch",
+            "on/off",
+            "toggle switch",
+            "toggle button",
+            "boolean switch",
+            "flip switch"
+        ],
+        "avoid": [
+            "div with role='switch' — use the native input via <Toggle>",
+            "raw color values for track / thumb — use design tokens",
+            "validation inside the component — belongs in Form/DynamicForm",
+            "Toggle without a label prop",
+            "Checkbox when you mean on/off — use Toggle for binary settings"
+        ],
+        "patterns": [
+            "Basic: <Toggle label=\"'Dark mode'\" />",
+            "Controlled: <Toggle label=\"'Notifications'\" checked=\"isEnabled\" onChange=\"toggle\" />",
+            "Required: <Toggle label=\"'Accept tracking'\" required=\"true\" />",
+            "Helper text: <Toggle label=\"'Auto-save'\" helperText=\"'Saves every 30 seconds'\" />",
+            "Error: <Toggle label=\"'Enable feature'\" error=\"hasError\" errorMessage=\"'Feature unavailable'\" />",
+            "Disabled: <Toggle label=\"'Premium feature'\" disabled=\"true\" />",
+            "Loading: <Toggle label=\"'Syncing...'\" loading=\"isSyncing\" checked=\"isEnabled\" />"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Basic toggle",
+            "pithy": "<Toggle label=\"'Dark mode'\" />",
+            "assertions": [
+                "renders <input type='checkbox' role='switch'>",
+                "label is visible",
+                "aria-checked='false'",
+                "no axe violations"
+            ]
+        },
+        {
+            "id": "checked",
+            "title": "Pre-checked toggle",
+            "pithy": "<Toggle label=\"'Notifications'\" checked=\"true\" />",
+            "assertions": [
+                "input.checked === true",
+                "data-checked on wrapper",
+                "aria-checked='true'"
+            ]
+        },
+        {
+            "id": "disabled",
+            "title": "Disabled toggle",
+            "pithy": "<Toggle label=\"'Locked'\" disabled=\"true\" />",
+            "assertions": ["input.disabled === true", "data-disabled on wrapper"]
+        },
+        {
+            "id": "readonly",
+            "title": "Readonly toggle",
+            "pithy": "<Toggle label=\"'Auto-set'\" readonly=\"true\" checked=\"true\" />",
+            "assertions": [
+                "click does not toggle",
+                "Space does not toggle",
+                "remains focusable"
+            ]
+        },
+        {
+            "id": "required",
+            "title": "Required toggle",
+            "pithy": "<Toggle label=\"'I agree'\" required=\"true\" />",
+            "assertions": ["aria-required on input", "asterisk visible on label"]
+        },
+        {
+            "id": "error",
+            "title": "Error with shake",
+            "pithy": "<Toggle label=\"'Enable'\" error=\"hasError\" errorMessage=\"'Unavailable'\" />",
+            "assertions": [
+                "aria-invalid on input",
+                "shake animation on transition",
+                "error message shown"
+            ]
+        },
+        {
+            "id": "success",
+            "title": "Success state",
+            "pithy": "<Toggle label=\"'Verified'\" success=\"true\" checked=\"true\" />",
+            "assertions": ["data-success on wrapper", "green track fill"]
+        },
+        {
+            "id": "loading",
+            "title": "Loading state",
+            "pithy": "<Toggle label=\"'Saving'\" loading=\"isSaving\" />",
+            "assertions": ["spinner visible", "aria-busy='true'", "thumb hidden"]
+        },
+        {
+            "id": "helper",
+            "title": "With helper text",
+            "pithy": "<Toggle label=\"'Auto-save'\" helperText=\"'Saves every 30 seconds'\" />",
+            "assertions": ["helper text visible", "aria-describedby set"]
+        }
+    ],
+    "designGuidance": {
+        "surface": "Track uses --color-surface-variant when off, switching to --color-primary when on. Hover deepens to --color-primary-hover. Thumb is always --color-on-primary (white).",
+        "depth": "Thumb has --shadow-sm (unchecked) / --shadow-md (checked/hover) for premium depth. Focus ring via box-shadow ring() with 2px offset on the track.",
+        "borders": "Stable border width on the track — only color changes across states. Pill shape via border-radius: 999px.",
+        "interactivity": "Hover grows thumb from border-thin inset to a flush edge-aligned position (filling the track height), and lifts shadow to --shadow-md (non-color size feedback for WCAG accessibility). Active applies pressed state-background + iOS-style thumb stretch (~30% wider) toward direction of travel (right when unchecking→checking, left when checking→unchecking). Focus shows ring on the track. Error shakes on transition. Thumb slides smoothly via inset-inline-start transition with springy easing (RTL-aware). Loading overlays spinner inside the track, hiding the thumb.",
+        "bestPractices": "Use Toggle for binary settings (on/off). Use Checkbox for opt-in/agreement scenarios. Always provide a label. Use disabled when the setting cannot be changed; use readonly when the value is meaningful but locked."
+    }
+}

package/dist/specs/layout/grid-item.pidl.json

@@ -0,0 +1,120 @@
+{
+    "kind": "component",
+    "id": "ui.grid-item",
+    "name": "GridItem",
+    "displayName": "Grid Item",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "layout",
+    "studioReady": false,
+    "bidi": true,
+    "description": "Grid child component for structured placement within a Grid. Maps props to utility classes for column/row spanning and positioning.",
+    "props": [
+        {
+            "name": "span",
+            "label": "Span",
+            "editor": { "tab": "layout", "type": "string" },
+            "type": "number | 'full'",
+            "description": "Column span (1-12 or 'full') — maps to u-col-span-*"
+        },
+        {
+            "name": "start",
+            "label": "Column start",
+            "editor": { "tab": "layout" },
+            "type": "number",
+            "description": "Column start line (1-13) — maps to u-col-start-*"
+        },
+        {
+            "name": "end",
+            "label": "Column end",
+            "editor": { "tab": "layout" },
+            "type": "number",
+            "description": "Column end line (1-13) — maps to u-col-end-*"
+        },
+        {
+            "name": "rowSpan",
+            "label": "Row span",
+            "editor": { "tab": "layout" },
+            "type": "number",
+            "description": "Row span (1-6) — maps to u-row-span-*"
+        },
+        {
+            "name": "rowStart",
+            "label": "Row start",
+            "editor": { "tab": "layout" },
+            "type": "number",
+            "description": "Row start line (1-7) — maps to u-row-start-*"
+        },
+        {
+            "name": "rowEnd",
+            "label": "Row end",
+            "editor": { "tab": "layout" },
+            "type": "number",
+            "description": "Row end line (1-7) — maps to u-row-end-*"
+        },
+        {
+            "name": "placeSelf",
+            "label": "Place self",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["start", "center", "end", "stretch"],
+            "description": "Place self alignment — maps to u-place-self-*"
+        },
+        {
+            "name": "as",
+            "label": "Element",
+            "editor": { "tab": "settings" },
+            "type": "enum",
+            "enum": ["div", "section", "article", "aside", "li"],
+            "default": "div",
+            "description": "HTML tag to render"
+        }
+    ],
+    "events": [],
+    "slots": [{ "name": "default", "displayName": "Content" }],
+    "tokens": {
+        "span": "u-col-span-{n} (1-12, full)",
+        "position": "u-col-start-{n}, u-col-end-{n}, u-row-start-{n}, u-row-end-{n}"
+    },
+    "spacing": {
+        "internal": "No internal spacing — controlled by parent Grid gap"
+    },
+    "constraints": [
+        "Must be a direct child of <Grid>",
+        "Column span clamped to 1-12",
+        "Column start/end clamped to 1-13",
+        "Row span clamped to 1-6",
+        "Row start/end clamped to 1-7",
+        "Use logical properties only (handled automatically via utility classes)"
+    ],
+    "a11y": [
+        "Uses semantic HTML via as prop — use <li> when parent Grid renders as <ul>/<ol>",
+        "No ARIA attributes needed — placement is presentational"
+    ],
+    "ai": {
+        "synonyms": ["grid cell", "grid child", "column span", "grid placement"],
+        "avoid": [
+            "manual grid-column CSS — use span/start/end props",
+            "GridItem outside of Grid — it has no effect without a grid parent"
+        ],
+        "patterns": [
+            "Spanning 2 columns: <GridItem span=\"2\"><div>Wide</div></GridItem>",
+            "Full-width row: <GridItem span=\"'full'\"><div>Banner</div></GridItem>",
+            "Positioned item: <GridItem start=\"2\" end=\"4\"><div>Middle</div></GridItem>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "span-2",
+            "title": "Item spanning 2 columns",
+            "pithy": "<Grid columns=\"3\"><GridItem span=\"2\"><div>Wide</div></GridItem><div>Normal</div></Grid>",
+            "assertions": ["has u-col-span-2 class"]
+        },
+        {
+            "id": "full-width",
+            "title": "Full-width item",
+            "pithy": "<Grid columns=\"3\"><GridItem span=\"'full'\"><div>Banner</div></GridItem></Grid>",
+            "assertions": ["has u-col-span-full class"]
+        }
+    ]
+}

package/dist/specs/layout/grid.pidl.json

@@ -0,0 +1,157 @@
+{
+    "kind": "component",
+    "id": "ui.grid",
+    "name": "Grid",
+    "displayName": "Grid",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "layout",
+    "bidi": true,
+    "description": "CSS grid layout atom with simple column counts, responsive breakpoints via container queries, and intrinsic auto-fit/fill patterns. Mobile-first: defaults to 1 column.",
+    "props": [
+        {
+            "name": "columns",
+            "label": "Columns",
+            "editor": { "tab": "layout", "type": "string" },
+            "type": "number | ResponsiveColumns | 'auto-fit' | 'auto-fill'",
+            "default": 1,
+            "description": "Column configuration — number (1-12), responsive object ({ base, sm, md, lg, xl }), or intrinsic auto-fit/auto-fill"
+        },
+        {
+            "name": "rows",
+            "label": "Rows",
+            "editor": { "tab": "layout" },
+            "type": "number",
+            "description": "Number of rows (1-6, optional)"
+        },
+        {
+            "name": "gap",
+            "label": "Gap",
+            "editor": { "tab": "layout", "type": "token-space" },
+            "type": "enum",
+            "enum": ["0", "xs", "sm", "md", "lg", "xl"],
+            "default": "md",
+            "description": "Gap between children — maps to u-gap-* utilities"
+        },
+        {
+            "name": "rowGap",
+            "label": "Row gap",
+            "editor": { "tab": "layout", "type": "token-space" },
+            "type": "enum",
+            "enum": ["0", "xs", "sm", "md", "lg", "xl"],
+            "description": "Override gap for rows only — maps to u-row-gap-*"
+        },
+        {
+            "name": "colGap",
+            "label": "Column gap",
+            "editor": { "tab": "layout", "type": "token-space" },
+            "type": "enum",
+            "enum": ["0", "xs", "sm", "md", "lg", "xl"],
+            "description": "Override gap for columns only — maps to u-col-gap-*"
+        },
+        {
+            "name": "align",
+            "label": "Align",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["start", "center", "end", "stretch", "baseline"],
+            "description": "Cross-axis alignment — maps to u-items-* utilities"
+        },
+        {
+            "name": "justify",
+            "label": "Justify",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["start", "end", "center", "between", "around", "evenly"],
+            "description": "Main-axis justification — maps to u-justify-* utilities"
+        },
+        {
+            "name": "minColumnWidth",
+            "label": "Min column width",
+            "editor": { "tab": "layout" },
+            "type": "string",
+            "description": "CSS value for auto-fit/fill min column width, e.g. '250px', '15rem'"
+        },
+        {
+            "name": "as",
+            "label": "Element",
+            "editor": { "tab": "settings" },
+            "type": "enum",
+            "enum": ["div", "section", "article", "aside", "ul", "ol"],
+            "default": "div",
+            "description": "HTML tag to render"
+        }
+    ],
+    "events": [],
+    "slots": [{ "name": "default", "displayName": "Content" }],
+    "tokens": {
+        "gap": "--space-{gap} (via u-gap-*)",
+        "columns": "u-grid-cols-{n} (1-12)",
+        "auto-min": "--grid-auto-min (CSS custom property for auto-fit/fill)"
+    },
+    "spacing": {
+        "between-cells": "--space-{gap} (friendship model — choose gap based on cell relationship)",
+        "card-grid": "--space-md (friends — cards in a grid)"
+    },
+    "constraints": [
+        "Columns clamped to 1-12 range",
+        "Rows clamped to 1-6 range",
+        "minColumnWidth applies to auto-fit/auto-fill and fluid numeric columns (columns ≥ 2 in auto-fit mode); it is ignored when rows/explicit placement force fixed tracks — fr units are not valid inside minmax()",
+        "Responsive columns use container queries — wrap in a container-type context for proper behavior",
+        "Use logical properties only (handled automatically via utility classes)"
+    ],
+    "a11y": [
+        "Uses semantic HTML via as prop",
+        "Grid is presentational — no ARIA grid role needed for layout grids",
+        "Use <ul>/<ol> with as prop for list-based grids"
+    ],
+    "ai": {
+        "synonyms": [
+            "grid layout",
+            "columns",
+            "card grid",
+            "responsive grid",
+            "css grid"
+        ],
+        "avoid": [
+            "manual grid-template-columns — use columns prop",
+            "media queries for responsive columns — use responsive object with container queries",
+            "float-based layouts — use <Grid>"
+        ],
+        "patterns": [
+            "Simple 3-column grid: <Grid columns=\"3\" gap=\"'lg'\"><div>A</div><div>B</div><div>C</div></Grid>",
+            "Responsive grid: <Grid columns=\"{ base: 1, sm: 2, lg: 3 }\" gap=\"'md'\">...</Grid>",
+            "Auto-fit cards: <Grid columns=\"'auto-fit'\" minColumnWidth=\"'250px'\" gap=\"'md'\">...</Grid>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "simple-grid",
+            "title": "Simple 3-column grid",
+            "pithy": "<Grid columns=\"3\" gap=\"'lg'\"><div>A</div><div>B</div><div>C</div></Grid>",
+            "assertions": [
+                "renders u-grid class",
+                "has u-grid-cols-3",
+                "has u-gap-lg"
+            ]
+        },
+        {
+            "id": "responsive-grid",
+            "title": "Responsive columns",
+            "pithy": "<Grid columns=\"{ base: 1, sm: 2, lg: 3 }\"><div>A</div><div>B</div><div>C</div></Grid>",
+            "assertions": [
+                "renders container wrapper",
+                "inner grid has responsive classes"
+            ]
+        },
+        {
+            "id": "auto-fit",
+            "title": "Auto-fit with min width",
+            "pithy": "<Grid columns=\"'auto-fit'\" minColumnWidth=\"'250px'\"><div>Card</div><div>Card</div></Grid>",
+            "assertions": [
+                "has u-grid-auto-fit class",
+                "--grid-auto-min set to 250px"
+            ]
+        }
+    ]
+}