@pithyjs/pidl-catalog 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PithyJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/specs/atoms/actions/button.pidl.json

@@ -0,0 +1,289 @@
+{
+    "kind": "component",
+    "id": "ui.button",
+    "name": "Button",
+    "displayName": "Button",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "actions",
+    "bidi": true,
+    "description": "Accessible, reactive button with variants, color schemes, loading state, and anchor mode. Keyboard and ARIA correct by default. Uses aria-disabled to keep button focusable for assistive tech.",
+    "props": [
+        {
+            "name": "text",
+            "reactive": true,
+            "label": "Label",
+            "type": "string | Signal<string>",
+            "placeholder": "Click me",
+            "description": "Visible button label. Rendered as a text node inside the button. When omitted, the component falls back to slot content (`<Button>Click me</Button>` in templates)."
+        },
+        {
+            "name": "iconStart",
+            "reactive": true,
+            "label": "Leading icon",
+            "type": "icon",
+            "description": "Icon shown before the label. Picked from the registered sprite (see @pithyjs/vite-plugin/icons). Pair with `ariaLabel` for icon-only buttons."
+        },
+        {
+            "name": "iconEnd",
+            "reactive": true,
+            "label": "Trailing icon",
+            "type": "icon",
+            "description": "Icon shown after the label."
+        },
+        {
+            "name": "variant",
+            "label": "Variant",
+            "type": "enum",
+            "enum": ["solid", "outline", "ghost", "link"],
+            "default": "solid",
+            "description": "Visual style — solid (filled), outline (bordered), ghost (no background), link (text-only underlined)"
+        },
+        {
+            "name": "color",
+            "label": "Color",
+            "editor": { "type": "token-color" },
+            "type": "enum",
+            "enum": [
+                "primary",
+                "secondary",
+                "tertiary",
+                "success",
+                "info",
+                "warning",
+                "danger"
+            ],
+            "default": "primary",
+            "description": "Semantic color scheme — maps to design-system --color-* tokens."
+        },
+        {
+            "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": "shape",
+            "label": "Shape",
+            "type": "enum",
+            "enum": ["none", "xs", "sm", "md", "lg", "xl"],
+            "default": "md",
+            "description": "Border-radius shape — maps to design-system --radius-* tokens via data-shape attribute. 'xl' reads as pill, 'none' as square."
+        },
+        {
+            "name": "disabled",
+            "label": "Disabled",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Disabled state — accepts static boolean or signal accessor. Uses aria-disabled (not native disabled) to keep element focusable."
+        },
+        {
+            "name": "loading",
+            "label": "Loading",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Loading state — shows spinner, sets aria-busy, announces loading text to screen readers"
+        },
+        {
+            "name": "type",
+            "label": "Type",
+            "editor": { "tab": "settings" },
+            "type": "enum",
+            "enum": ["button", "submit", "reset"],
+            "default": "button",
+            "description": "HTML button type attribute — only used when as=\"button\""
+        },
+        {
+            "name": "loadingText",
+            "label": "Loading text",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "default": "Loading\u2026",
+            "description": "Screen-reader announcement during loading state"
+        },
+        {
+            "name": "fullWidth",
+            "label": "Full width",
+            "editor": { "tab": "layout" },
+            "type": "boolean",
+            "default": false,
+            "description": "Stretch to 100% container width"
+        },
+        {
+            "name": "as",
+            "label": "Element",
+            "editor": { "tab": "settings" },
+            "type": "enum",
+            "enum": ["button", "a"],
+            "default": "button",
+            "description": "Render as <a> for anchor semantics — with href keeps native link, without href becomes role=button"
+        },
+        {
+            "name": "href",
+            "label": "Link URL",
+            "type": "string",
+            "description": "Link URL — only used when as=\"a\". Preserves native link semantics (no role override)."
+        },
+        {
+            "name": "onClick",
+            "type": "(e: MouseEvent) => void",
+            "description": "Click handler — guarded against disabled and loading states"
+        },
+        {
+            "name": "ariaLabel",
+            "reactive": true,
+            "label": "ARIA label",
+            "editor": { "tab": "settings" },
+            "type": "string | Signal<string>",
+            "description": "Accessible label — forwarded as aria-label on the root element. Static string or signal accessor. Use when the button has no visible text (e.g. icon-only buttons)."
+        }
+    ],
+    "events": ["click"],
+    "slots": [
+        {
+            "name": "default",
+            "displayName": "Content",
+            "description": "Rich label content (icon, text). Interactive or container blocks are not allowed inside a button.",
+            "accepts": ["ui.icon", "ui.text"]
+        }
+    ],
+    "tokens": {
+        "solid.bg": "--color-{color}",
+        "solid.text": "--color-on-{color}",
+        "solid.bg-hover": "--color-{color}-hover",
+        "solid.bg-active": "--color-{color}-active",
+        "outline.border": "--border-width-hairline",
+        "outline.hover": "a11y.state-background(hover)",
+        "outline.active": "a11y.state-background(pressed)",
+        "ghost.hover": "color-mix(--_btn-color, --state-hover-opacity * 200%)",
+        "ghost.active": "a11y.state-background(pressed)",
+        "link.text-hover": "--color-{color}-hover",
+        "link.text-active": "--color-{color}-active",
+        "toggle.solid.bg-pressed": "--color-{color}-pressed (when aria-pressed=true or aria-expanded=true)",
+        "toggle.outline.bg-pressed": "a11y.state-background(selected)",
+        "toggle.ghost.bg-pressed": "a11y.state-background(selected)",
+        "radius": "--radius-{shape} (via data-shape attribute, mapped from radius.$radius-sizes)",
+        "focus": "--focus-ring-* (via u-focus-ring)",
+        "disabled.opacity": "--state-disabled-opacity",
+        "spinner.border": "--border-width-thin",
+        "spinner.animation": "--motion-animation-spin",
+        "font-weight": "--font-weight-medium"
+    },
+    "spacing": {
+        "internal": "Controlled by u-control-{size} utility — uses --control-padding-* and --control-gap-* tokens",
+        "icon-to-label": "--space-xs (lovers — icon and label are inseparable)"
+    },
+    "constraints": [
+        "Never use raw hex colors — use design system tokens via --_btn-* custom properties",
+        "Never use native disabled attribute — use aria-disabled to keep button focusable for assistive tech",
+        "Link variant skips u-control-* class — it's inline text, not a sized control",
+        "Radius is driven by data-shape attribute (mirrors variant/color/size pattern), not a u-radius-* class",
+        "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, Highlight border when toggled on"
+    ],
+    "a11y": [
+        "Provides role='button' and accessible name from slot content",
+        "When as='a' without href, adds role='button' with full keyboard emulation (Space + Enter)",
+        "When as='a' with href, keeps native link semantics (screen reader announces 'link')",
+        "Focus ring via u-focus-ring utility — meets 3:1 contrast with surrounding",
+        "Loading state: sets aria-busy='true', announces loadingText via aria-live region",
+        "Disabled state: uses aria-disabled (not native disabled) — element stays in tab order",
+        "Toggle / disclosure: aria-pressed='true' (toggles) or aria-expanded='true' (disclosures) renders a persistent on-state distinct from transient :active",
+        "Forced-colors: visible border for all variants, Highlight border when aria-pressed/expanded, GrayText for disabled"
+    ],
+    "ai": {
+        "synonyms": [
+            "cta",
+            "primary action",
+            "submit button",
+            "call to action",
+            "action button"
+        ],
+        "avoid": [
+            "div as button — use <Button> component",
+            "anchor without role when not a link — use as='a' without href",
+            "hardcoded colors — use color prop with semantic values",
+            "outline: none on focus — focus ring is handled by u-focus-ring"
+        ],
+        "patterns": [
+            "Primary solid button for main CTA: <Button color=\"'primary'\">Save</Button>",
+            "Danger outline for destructive actions: <Button variant=\"'outline'\" color=\"'danger'\">Delete</Button>",
+            "Ghost button in card footer: <Button variant=\"'ghost'\" size=\"'sm'\">Learn More</Button>",
+            "Full-width submit: <Button type=\"'submit'\" fullWidth>Sign Up</Button>",
+            "Loading state: <Button loading=\"isSaving\">Saving...</Button>",
+            "Pill shape for tags/filters: <Button shape=\"'xl'\" variant=\"'outline'\">All</Button>",
+            "Square chrome button: <Button color=\"'neutral'\" variant=\"'ghost'\" shape=\"'none'\">⌘K</Button>",
+            "Toggle button: <Button variant=\"'ghost'\" :aria-pressed=\"isOn\" @click=\"toggle()\">Bold</Button>",
+            "Disclosure trigger: <Button :aria-expanded=\"isOpen\" @click=\"toggle()\">Filters</Button>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic-solid",
+            "title": "Basic solid button",
+            "pithy": "<Button @click=\"save()\">Save</Button>",
+            "assertions": ["role=button has name 'Save'", "no violations in axe-core"]
+        },
+        {
+            "id": "outline-danger",
+            "title": "Danger outline button",
+            "pithy": "<Button variant=\"'outline'\" color=\"'danger'\" @click=\"remove()\">Delete</Button>",
+            "assertions": [
+                "role=button has name 'Delete'",
+                "data-variant='outline'",
+                "data-color='danger'"
+            ]
+        },
+        {
+            "id": "loading-state",
+            "title": "Button with reactive loading",
+            "pithy": "<Button loading=\"isLoading\" @click=\"submit()\">Submit</Button>",
+            "assertions": [
+                "aria-busy='true' when loading",
+                "spinner visible",
+                "screen reader announces 'Loading\u2026'"
+            ]
+        },
+        {
+            "id": "anchor-button",
+            "title": "Anchor rendered as button",
+            "pithy": "<Button as=\"'a'\" variant=\"'ghost'\">Open Menu</Button>",
+            "assertions": ["role='button'", "tabindex='0'", "Space + Enter activate"]
+        },
+        {
+            "id": "link-nav",
+            "title": "Anchor with href (native link)",
+            "pithy": "<Button as=\"'a'\" href=\"'/docs'\" variant=\"'link'\">Read Docs</Button>",
+            "assertions": [
+                "no role override",
+                "href='/docs'",
+                "screen reader announces 'link'"
+            ]
+        },
+        {
+            "id": "pill-shape",
+            "title": "Pill-shaped filter button",
+            "pithy": "<Button shape=\"'xl'\" variant=\"'outline'\" color=\"'neutral'\">All</Button>",
+            "assertions": [
+                "data-shape='xl'",
+                "border-radius resolves from --radius-xl",
+                "data-color='neutral'"
+            ]
+        },
+        {
+            "id": "toggle-pressed",
+            "title": "Toggle button with aria-pressed",
+            "pithy": "<Button variant=\"'ghost'\" :aria-pressed=\"isBold\" @click=\"toggle()\">B</Button>",
+            "assertions": [
+                "aria-pressed reflects state",
+                "persistent on-state styling distinct from :active",
+                "no violations in axe-core"
+            ]
+        }
+    ]
+}

package/dist/specs/atoms/actions/icon-group.pidl.json

@@ -0,0 +1,141 @@
+{
+    "kind": "component",
+    "id": "ui.icon-group",
+    "name": "IconGroup",
+    "displayName": "Icon Group",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "actions",
+    "bidi": true,
+    "description": "Single-select icon-only segmented pill. Renders role='radiogroup' with one role='radio' button per item; the active option gets a circular indicator behind its icon.",
+    "props": [
+        {
+            "name": "items",
+            "label": "Items",
+            "type": "array",
+            "required": true,
+            "placeholder": [
+                { "value": "desktop", "icon": "desktop", "ariaLabel": "Desktop" },
+                { "value": "tablet", "icon": "tablet", "ariaLabel": "Tablet" },
+                { "value": "mobile", "icon": "mobile", "ariaLabel": "Mobile" }
+            ],
+            "description": "Options to choose from in display order. Each item is { value, icon, ariaLabel }.",
+            "itemSchema": {
+                "value": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Unique value identifier"
+                },
+                "icon": {
+                    "type": "string",
+                    "required": true,
+                    "editor": { "type": "icon" },
+                    "description": "Icon name passed to <Icon name=...>"
+                },
+                "ariaLabel": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Accessible label for the icon-only option"
+                }
+            }
+        },
+        {
+            "name": "value",
+            "label": "Value",
+            "type": "string | () => string",
+            "required": true,
+            "description": "Currently selected value. Must be a signal accessor () => string for interactive use — a static string sets the initial state only and will not update after user interaction."
+        },
+        {
+            "name": "ariaLabel",
+            "label": "ARIA label",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "required": true,
+            "placeholder": "View mode",
+            "description": "Accessible label for the radiogroup itself."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Control size — maps option hit area to --control-min-height-{size}."
+        },
+        {
+            "name": "iconSize",
+            "label": "Icon size",
+            "type": "enum",
+            "enum": ["xs", "sm", "md", "lg", "xl", "xxl"],
+            "default": "sm",
+            "description": "Icon size — passed to <Icon size=...>."
+        }
+    ],
+    "events": [
+        {
+            "name": "onChange",
+            "description": "Fires with the new value on click or keyboard activation."
+        }
+    ],
+    "slots": [],
+    "tokens": {
+        "color": "--color-surface (track), --color-text, --color-text-muted, --color-border",
+        "spacing": "--space-xs (track padding + gap)",
+        "radius": "--radius-pill (track), 50% (option indicator)",
+        "size": "--control-min-height-{size} (option hit area)",
+        "border": "--border-width-hairline (track)",
+        "motion": "--motion-transition-background, --motion-transition-color"
+    },
+    "spacing": {
+        "options-internal": "--space-xs (lovers — adjacent options)"
+    },
+    "constraints": [
+        "ariaLabel on the group is required — DEV warning when missing",
+        "ariaLabel on each item is required — icon-only buttons have no visible text",
+        "items length should be ≥ 2 — DEV warning otherwise",
+        "Keyboard: Left/Up = prev (wrap), Right/Down = next (wrap), Home = first, End = last — focus + activate per radiogroup spec"
+    ],
+    "a11y": [
+        "Container role='radiogroup' with required aria-label",
+        "Each option role='radio' with aria-checked + aria-label (per-item label drives the announce)",
+        "Roving tabindex: only the active option is in the Tab sequence",
+        "Forced-colors: selected option uses Highlight + HighlightText system colors with forced-color-adjust:none"
+    ],
+    "ai": {
+        "synonyms": [
+            "icon group",
+            "icon toggle",
+            "icon segmented",
+            "view selector",
+            "device selector"
+        ],
+        "avoid": [
+            "div with click handlers — use IconGroup for keyboard + ARIA semantics",
+            "checkbox group — IconGroup is single-select",
+            "Buttons row — that's a button group, not a radiogroup; semantics differ"
+        ],
+        "patterns": [
+            "Viewport selector: <IconGroup items=\"viewportItems\" value=\"viewport\" onChange=\"setViewport\" ariaLabel=\"'Viewport size'\" />",
+            "View density: <IconGroup items=\"densityItems\" value=\"density\" onChange=\"setDensity\" ariaLabel=\"'View density'\" />"
+        ]
+    },
+    "designGuidance": {
+        "surface": "Pill-shaped track on --color-surface with a hairline border. Each option is a square hit area with a circular active indicator (selected-state background overlay).",
+        "depth": "Flat — the active indicator carries the affordance, no shadow.",
+        "borders": "Hairline track border for definition.",
+        "interactivity": "Hover lightens text + tints the option background subtly. Focus-visible draws the design-system focus ring. Active state uses the design-system selected overlay for consistency with checkboxes/radios.",
+        "darkMode": "Adapts via --color-* tokens; no manual overrides needed."
+    },
+    "examples": [
+        {
+            "id": "viewport",
+            "title": "Viewport selector (desktop / tablet / mobile)",
+            "pithy": "<IconGroup items=\"viewportItems\" value=\"viewport\" onChange=\"setViewport\" ariaLabel=\"'Viewport size'\" />",
+            "assertions": [
+                "role='radiogroup'",
+                "three role='radio' children with aria-label per item"
+            ]
+        }
+    ]
+}

package/dist/specs/atoms/actions/segmented-control.pidl.json

@@ -0,0 +1,137 @@
+{
+    "kind": "component",
+    "id": "ui.segmented-control",
+    "name": "SegmentedControl",
+    "displayName": "Segmented Control",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "actions",
+    "bidi": true,
+    "description": "Single-select segmented filter. Renders a role='radiogroup' container with one role='radio' button per item. Supports arrow-key navigation, Home/End jump, and roving tabindex.",
+    "props": [
+        {
+            "name": "items",
+            "label": "Items",
+            "type": "array",
+            "required": true,
+            "placeholder": [
+                { "value": "all", "label": "All" },
+                { "value": "active", "label": "Active" },
+                { "value": "archived", "label": "Archived" }
+            ],
+            "description": "Options to choose from in display order. Each item is { value, label }.",
+            "itemSchema": {
+                "value": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Unique value identifier"
+                },
+                "label": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Visible text"
+                }
+            }
+        },
+        {
+            "name": "value",
+            "label": "Value",
+            "type": "string | () => string",
+            "required": true,
+            "description": "Currently selected value. Must be a signal accessor () => string for interactive use — a static string sets the initial state only and will not update after user interaction."
+        },
+        {
+            "name": "ariaLabel",
+            "label": "ARIA label",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "required": true,
+            "placeholder": "Filter scope",
+            "description": "Accessible label for the radiogroup — required by WAI-ARIA."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Control size — drives font-size and padding."
+        }
+    ],
+    "events": [
+        {
+            "name": "onChange",
+            "description": "Fires with the new value on click or keyboard activation."
+        }
+    ],
+    "slots": [],
+    "tokens": {
+        "color": "--color-surface-variant (track), --color-surface (selected), --color-text, --color-text-muted",
+        "spacing": "--space-xs/sm/md/lg (size-driven padding)",
+        "radius": "--radius-sm",
+        "shadow": "--shadow-xs (selected lift)",
+        "border": "--border-width-thin (track inset)",
+        "size": "--font-size-{xs|sm|body} (size-driven font-size)",
+        "motion": "--motion-transition-background, --motion-transition-color, --motion-duration-normal, --motion-easing-standard"
+    },
+    "spacing": {
+        "options-internal": "--space-xs (lovers — text content inside an option)"
+    },
+    "constraints": [
+        "ariaLabel is required — DEV warning when missing",
+        "items length should be ≥ 2 — DEV warning otherwise (single-option radiogroup is a button)",
+        "value must match one of items[].value to render with a checked option — otherwise the first option becomes tabbable but no option is checked",
+        "Keyboard: Left/Up = prev (wrap), Right/Down = next (wrap), Home = first, End = last — focus + activate per radiogroup spec"
+    ],
+    "a11y": [
+        "Container role='radiogroup' with required aria-label",
+        "Each option role='radio' with aria-checked reflecting active state",
+        "Roving tabindex: only the active option is in the Tab sequence (tabindex=0)",
+        "Forced-colors: selected option uses Highlight + HighlightText system colors with forced-color-adjust:none"
+    ],
+    "ai": {
+        "synonyms": [
+            "segmented",
+            "filter",
+            "toggle",
+            "switch",
+            "tab bar",
+            "pill toggle"
+        ],
+        "avoid": [
+            "div with click handlers — use SegmentedControl for keyboard + ARIA semantics",
+            "checkbox group — segmented is single-select, not multi",
+            "Tabs — these are filters / mode switches, not navigation between content panels"
+        ],
+        "patterns": [
+            "Filter scope: <SegmentedControl items=\"options\" value=\"current\" onChange=\"set\" ariaLabel=\"'Filter scope'\" />",
+            "Sort order: <SegmentedControl items=\"sortOptions\" value=\"sort\" onChange=\"setSort\" ariaLabel=\"'Sort order'\" />",
+            "View density: <SegmentedControl items=\"densities\" value=\"density\" onChange=\"setDensity\" ariaLabel=\"'View density'\" size=\"'sm'\" />"
+        ]
+    },
+    "designGuidance": {
+        "surface": "Track uses --color-surface-variant; the selected option lifts onto --color-surface with shadow-xs for tactile depth.",
+        "depth": "Selected option only — flat track, raised pill.",
+        "borders": "Hairline track inset via padding (no border) lets the selected pill align with the container edge.",
+        "interactivity": "Hover lightens unselected option text; active option keeps full text contrast. Focus-visible draws the design-system focus ring on whichever option has keyboard focus.",
+        "darkMode": "Adapts via --color-* tokens; no manual overrides needed."
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "All / Sections filter",
+            "pithy": "<SegmentedControl items=\"levelOptions\" value=\"levelFilter\" onChange=\"setLevel\" ariaLabel=\"'Component scope'\" />",
+            "assertions": [
+                "role='radiogroup'",
+                "aria-label='Component scope'",
+                "two role='radio' children"
+            ]
+        },
+        {
+            "id": "small",
+            "title": "Compact density toggle",
+            "pithy": "<SegmentedControl items=\"densityOptions\" value=\"density\" onChange=\"setDensity\" ariaLabel=\"'Density'\" size=\"'sm'\" />",
+            "assertions": ["data-size='sm'"]
+        }
+    ]
+}