@pithyjs/pidl-catalog 0.1.0-beta.0

package/dist/specs/atoms/content/tabs.pidl.json

@@ -0,0 +1,207 @@
+{
+    "kind": "component",
+    "id": "ui.tabs",
+    "name": "Tabs",
+    "displayName": "Tabs",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "content",
+    "bidi": false,
+    "description": "Accessible tabbed interface implementing the WAI-ARIA tablist pattern. Renders a role=tablist of role=tab buttons over eagerly-mounted role=tabpanel panels toggled via [hidden]. Roving tabindex with arrow-key navigation (Home/End, wrap), horizontal or vertical orientation, and automatic or manual activation.",
+    "props": [
+        {
+            "name": "items",
+            "label": "Tabs",
+            "type": "array",
+            "required": true,
+            "placeholder": [
+                {
+                    "id": "overview",
+                    "label": "Overview",
+                    "content": "Overview panel content."
+                },
+                {
+                    "id": "details",
+                    "label": "Details",
+                    "content": "Details panel content."
+                }
+            ],
+            "description": "Tabs in display order. Each item is { id, label, content, icon?, disabled? }.",
+            "itemSchema": {
+                "id": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Stable identifier — the selected value and the onChange key. Not used for DOM/ARIA ids (those are index-based), so it may contain any characters."
+                },
+                "label": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Tab button label"
+                },
+                "content": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Panel content, authored as text in the site builder. The component's TypeScript API additionally accepts a Node or a { el, destroy } ui-kit component."
+                },
+                "icon": {
+                    "type": "icon",
+                    "required": false,
+                    "description": "Optional leading icon name (resolved via the built-in icon fallback)"
+                },
+                "disabled": {
+                    "type": "boolean",
+                    "required": false,
+                    "description": "Skip this tab in keyboard nav and make it non-selectable"
+                }
+            }
+        },
+        {
+            "name": "defaultTab",
+            "label": "Default tab",
+            "type": "string",
+            "required": false,
+            "description": "Id of the initially-selected tab. Falls back to the first enabled tab when omitted or when it names a disabled/unknown tab."
+        },
+        {
+            "name": "orientation",
+            "label": "Orientation",
+            "type": "enum",
+            "enum": ["horizontal", "vertical"],
+            "default": "horizontal",
+            "description": "Layout axis of the tablist. Sets aria-orientation and the arrow-key axis (Left/Right vs Up/Down)."
+        },
+        {
+            "name": "fitted",
+            "label": "Full width",
+            "type": "boolean",
+            "required": false,
+            "default": false,
+            "editor": {
+                "visibleWhen": { "prop": "orientation", "equals": "horizontal" }
+            },
+            "description": "Stretch tabs to fill the tablist width in equal shares. Horizontal only — ignored (and dev-warned) for vertical orientation."
+        },
+        {
+            "name": "activation",
+            "label": "Activation",
+            "type": "enum",
+            "enum": ["automatic", "manual"],
+            "default": "automatic",
+            "description": "Whether the selected tab follows keyboard focus. 'automatic' selects on arrow-key focus; 'manual' moves focus only and selects on Enter/Space — preferred when switching tabs is expensive."
+        },
+        {
+            "name": "ariaLabel",
+            "label": "ARIA label",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "required": false,
+            "description": "Accessible name for the tablist. Recommended so screen-reader users can distinguish multiple tablists on a page."
+        },
+        {
+            "name": "onChange",
+            "label": "On change",
+            "editor": { "tab": "settings" },
+            "type": "(id: string, index: number) => void",
+            "required": false,
+            "description": "Called when the active tab changes (not on the initial render)."
+        }
+    ],
+    "tokens": {
+        "color": "--color-text-muted (idle tab), --color-text (hover), --color-primary (active tab + indicator), --color-divider (tablist track)",
+        "spacing": "--space-xs (tab gap, icon↔label), --space-md (tablist↔panels), --control-padding-x-sm / --control-padding-y-sm (tab padding)",
+        "radius": "--radius-sm (focus-ring rounding)",
+        "size": "--font-size-sm (tab label)",
+        "border": "--border-width-medium (track shadow + horizontal indicator), --border-width-thick (vertical accent bar)",
+        "motion": "--motion-transition-color (tab color), --motion-duration-normal (indicator slide)"
+    },
+    "spacing": {
+        "tab-gap": "--space-xs (close friends — tabs in one list)",
+        "icon-label-gap": "--space-xs (lovers — icon beside its label)",
+        "list-panels-gap": "--space-md (friends — tablist above its panels)"
+    },
+    "constraints": [
+        "items is required — an empty list renders an empty tablist",
+        "Panels mount eagerly and toggle [hidden], so per-panel state survives tab switches",
+        "The active panel is focusable (tabindex=0) per APG guidance for panels without a focusable child",
+        "Disabled tabs are skipped by arrow-key navigation and cannot be selected (by keyboard or click)",
+        "String content is inserted as text (textContent), never HTML — avoids injection and stray {{ }} interpolation",
+        "Keyboard model is delegated to createRovingTabindex from @pithyjs/core — arrows honour orientation, Home/End jump, navigation wraps",
+        "Tab labels compose <Text as='span'> — no raw styled spans",
+        "A single accent indicator glides to the active tab: JS measures the tab and sets the indicator transform/size; the glide is enabled only after the first static placement (no slide-in on mount) and is repositioned by a ResizeObserver on layout/viewport changes",
+        "Active state also reads via a pill fill (horizontal: primary tint; vertical: selected-state overlay + accent bar) and heavier label weight",
+        "Horizontal tablists scroll inline on overflow; the indicator lives inside the scroller so its position stays correct. Fitted tabs fill equal shares instead",
+        "Tabs are 44px min touch targets"
+    ],
+    "a11y": [
+        "role=tablist with aria-orientation; each tab is role=tab with aria-selected and aria-controls its panel",
+        "Each panel is role=tabpanel, aria-labelledby its tab, and focusable (tabindex=0) only when it has no focusable descendant",
+        "Roving tabindex: exactly one tab is in the Tab sequence (tabindex=0); arrows move focus among the rest",
+        "automatic activation selects on focus; manual activation selects on Enter/Space (focus and selection may diverge)",
+        "Disabled tabs carry aria-disabled=true and are excluded from the roving set",
+        "Forced-colors: active tab uses Highlight; disabled tab uses GrayText",
+        "ariaLabel forwarded to the tablist to name the widget"
+    ],
+    "ai": {
+        "synonyms": [
+            "tabs",
+            "tab panel",
+            "tabbed",
+            "tab bar",
+            "tablist",
+            "tabbed interface",
+            "segmented content",
+            "tab navigation"
+        ],
+        "avoid": [
+            "hand-rolling role=tab/tabpanel with manual keydown handlers — <Tabs> delegates the WAI-ARIA keyboard model to createRovingTabindex",
+            "using <Tabs> for sequential steps or primary page navigation — tabs are for switching between peer views of the same context, not a wizard or a site menu"
+        ],
+        "patterns": [
+            "Basic: <Tabs ariaLabel=\"'Settings'\" items=\"tabItems\" />  where tabItems = [{ id, label, content }]",
+            "With icons: items include an icon name, e.g. { id: 'code', label: 'Code', icon: 'copy', content: … }",
+            "Manual activation (expensive panels): <Tabs items=\"tabItems\" activation=\"'manual'\" />",
+            "Vertical: <Tabs items=\"tabItems\" orientation=\"'vertical'\" />",
+            "Component panels: content can be a ui-kit component, e.g. content: CodeBlock({ code })"
+        ]
+    },
+    "designGuidance": {
+        "surface": "Tabs are chromeless — no card or fill. The tablist sits on a thin --color-divider track; panels inherit the surrounding surface.",
+        "depth": "Flat. The only visual weight is the active-tab indicator and the color shift from text-muted to primary.",
+        "borders": "Horizontal tablist track is a --border-width-medium inset shadow; the active indicator (--border-width-medium) slides under the selected tab. Vertical track is a --border-width-medium inline-start border with a --border-width-thick accent bar beside the selected tab.",
+        "interactivity": "Idle tabs are muted; hover lifts to full text color; the selected tab is primary with the indicator. focus-visible shows the design-system focus ring on both tabs and the active panel.",
+        "motion": "The indicator scales in via motion-safe transition; respects prefers-reduced-motion.",
+        "bestPractices": "Use for switching between peer views of the same content (Preview/Code, Description/Reviews). Keep labels short. Prefer automatic activation unless rendering a panel is expensive, then use manual so arrowing through tabs does not thrash. Always provide ariaLabel when more than one tablist appears on a page."
+    },
+    "examples": [
+        {
+            "id": "default",
+            "title": "Basic tabs",
+            "pithy": "<Tabs ariaLabel=\"'Account'\" items=\"accountTabs\" />",
+            "assertions": [
+                "renders <div class='ui-tabs'>",
+                "contains [role='tablist']",
+                "first tab has aria-selected='true'",
+                "one [role='tabpanel'] visible, others [hidden]"
+            ]
+        },
+        {
+            "id": "manual",
+            "title": "Manual activation",
+            "pithy": "<Tabs ariaLabel=\"'Docs'\" items=\"docTabs\" activation=\"'manual'\" />",
+            "assertions": [
+                "arrow keys move focus without changing aria-selected",
+                "Enter/Space selects the focused tab"
+            ]
+        },
+        {
+            "id": "vertical",
+            "title": "Vertical orientation",
+            "pithy": "<Tabs ariaLabel=\"'Sections'\" items=\"sectionTabs\" orientation=\"'vertical'\" />",
+            "assertions": [
+                "tablist has aria-orientation='vertical'",
+                "Up/Down arrows navigate",
+                "root has data-orientation='vertical'"
+            ]
+        }
+    ]
+}

package/dist/specs/atoms/content/text.pidl.json

@@ -0,0 +1,212 @@
+{
+    "kind": "component",
+    "id": "ui.text",
+    "name": "Text",
+    "displayName": "Text",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "content",
+    "bidi": true,
+    "description": "Typography wrapper for body text content. Maps props to design-system typography tokens and utility classes. Uses logical properties for RTL/LTR support. Supports 18 semantic HTML tags.",
+    "props": [
+        {
+            "name": "text",
+            "reactive": true,
+            "label": "Text",
+            "editor": { "tab": "content", "multiline": true },
+            "type": "string | Signal<string>",
+            "placeholder": "Body copy. Replace this with your own content.",
+            "description": "Visible body text. Rendered as text inside the element; newlines (\\n) become <br> so multi-line input preserves its line breaks. When omitted, the component falls back to slot content."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "editor": { "type": "token-font" },
+            "type": "enum",
+            "enum": ["xs", "sm", "base", "lg", "xl", "2xl", "3xl", "4xl"],
+            "default": "base",
+            "description": "Font size — maps to u-text-* typography utilities"
+        },
+        {
+            "name": "weight",
+            "label": "Weight",
+            "type": "enum",
+            "enum": [
+                "thin",
+                "light",
+                "normal",
+                "medium",
+                "semibold",
+                "bold",
+                "extrabold"
+            ],
+            "default": "normal",
+            "description": "Font weight — maps to u-font-* typography utilities. Semantic tags (strong, em) preserve native weight unless overridden."
+        },
+        {
+            "name": "color",
+            "label": "Color",
+            "editor": { "type": "token-color" },
+            "type": "enum",
+            "enum": [
+                "text",
+                "text-muted",
+                "text-inverse",
+                "primary",
+                "secondary",
+                "tertiary"
+            ],
+            "default": "text",
+            "description": "Text color — maps to --color-* design tokens. Status colors (success/info/warning/danger) are intentionally excluded — those belong on Badge/Button/Icon where the color carries semantic meaning, not on plain text."
+        },
+        {
+            "name": "align",
+            "label": "Align",
+            "type": "enum",
+            "enum": ["start", "center", "end", "justify"],
+            "description": "Text alignment — uses logical values (start/end, not left/right) for RTL support"
+        },
+        {
+            "name": "truncate",
+            "label": "Truncate",
+            "editor": { "tab": "layout", "type": "number" },
+            "type": "boolean | number",
+            "default": false,
+            "description": "Truncation — true for single-line ellipsis, number (1-4) for line-clamp"
+        },
+        {
+            "name": "as",
+            "label": "Element",
+            "editor": { "tab": "settings" },
+            "type": "enum",
+            "enum": [
+                "p",
+                "span",
+                "div",
+                "small",
+                "strong",
+                "em",
+                "s",
+                "abbr",
+                "time",
+                "blockquote",
+                "figcaption",
+                "cite",
+                "q",
+                "mark",
+                "code",
+                "pre",
+                "kbd",
+                "samp"
+            ],
+            "default": "p",
+            "description": "HTML element tag — choose the semantically correct element"
+        },
+        {
+            "name": "title",
+            "label": "Title",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Expansion text for <abbr> — sets the title attribute. Only used when as='abbr'. Required for accessibility."
+        },
+        {
+            "name": "datetime",
+            "label": "Datetime",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Machine-readable date/time for <time> — sets the datetime attribute. Only used when as='time'."
+        }
+    ],
+    "events": [],
+    "tokens": {
+        "color.default": "--color-text",
+        "color.muted": "--color-text-muted",
+        "color.inverse": "--color-text-inverse",
+        "color.brand": "--color-{primary|secondary|tertiary}",
+        "color.status": "--color-{success|info|warning|danger}",
+        "font-size": "--font-size-{size} (via u-text-* utility)",
+        "font-weight": "--font-weight-{weight} (via u-font-* utility)"
+    },
+    "spacing": {
+        "internal": "margin: 0 (reset) — external spacing controlled by parent layout",
+        "label-to-input": "--space-sm (close friends — label and input are tightly coupled)"
+    },
+    "constraints": [
+        "Never use raw hex colors — use color prop with design token values",
+        "Never use physical CSS properties — all alignment uses logical values (start/end, not left/right)",
+        "When as='abbr', the title prop is required for accessibility",
+        "When as='time', the datetime prop is required for machine-readability",
+        "Semantic tags (strong, em, small) preserve native browser styles unless weight/size explicitly overridden",
+        "Use logical properties only (margin-inline-start, not margin-left)",
+        "Must handle forced-colors mode — color: CanvasText",
+        "Must handle high-contrast mode — bump text-muted to full text color"
+    ],
+    "a11y": [
+        "Uses semantic HTML elements — <p>, <strong>, <em>, <abbr>, <time>, etc.",
+        "<mark> and <s> include visually-hidden pseudo-elements for screen reader announcements ('[highlight start]', '[strikethrough start]')",
+        "<abbr> requires title attribute for expansion (dev warning if missing)",
+        "Forced-colors: all text uses CanvasText for visibility",
+        "High-contrast: text-muted is upgraded to full text color for readability"
+    ],
+    "ai": {
+        "synonyms": [
+            "paragraph",
+            "body text",
+            "label",
+            "caption",
+            "description",
+            "copy"
+        ],
+        "avoid": [
+            "div for text content — use <Text> with correct as prop",
+            "hardcoded font sizes — use size prop",
+            "text-align: left/right — use align='start'/'end'",
+            "color as inline style — use color prop"
+        ],
+        "patterns": [
+            "Body paragraph: <Text>Lorem ipsum...</Text>",
+            "Muted caption: <Text size=\"'sm'\" color=\"'text-muted'\">Last updated</Text>",
+            "Bold inline: <Text as=\"'strong'\" color=\"'primary'\">Important</Text>",
+            "Centered heading subtitle: <Text size=\"'lg'\" align=\"'center'\" color=\"'text-muted'\">Subtitle</Text>",
+            "Truncated card description: <Text truncate=\"2\">Long text...</Text>",
+            "Code inline: <Text as=\"'code'\" size=\"'sm'\">const x = 1</Text>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic-paragraph",
+            "title": "Basic paragraph",
+            "pithy": "<Text>Hello, world!</Text>",
+            "assertions": [
+                "renders <p> element",
+                "has class ui-text",
+                "color is --color-text"
+            ]
+        },
+        {
+            "id": "styled-text",
+            "title": "Styled text with size and color",
+            "pithy": "<Text size=\"'lg'\" weight=\"'bold'\" color=\"'primary'\">Featured</Text>",
+            "assertions": [
+                "has u-text-lg class",
+                "has u-font-bold class",
+                "data-color='primary'"
+            ]
+        },
+        {
+            "id": "semantic-abbr",
+            "title": "Abbreviation with expansion",
+            "pithy": "<Text as=\"'abbr'\" title=\"'Hypertext Markup Language'\">HTML</Text>",
+            "assertions": [
+                "renders <abbr> element",
+                "title='Hypertext Markup Language'"
+            ]
+        },
+        {
+            "id": "truncated",
+            "title": "Multi-line truncation",
+            "pithy": "<Text truncate=\"3\">Long text that spans multiple lines...</Text>",
+            "assertions": ["has u-line-clamp-3 class"]
+        }
+    ]
+}

package/dist/specs/atoms/content/tile.pidl.json

@@ -0,0 +1,156 @@
+{
+    "kind": "component",
+    "id": "ui.tile",
+    "name": "Tile",
+    "displayName": "Tile",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "content",
+    "bidi": true,
+    "description": "Compact clickable tile with an icon/glyph slot above a visible label. Renders a <button> with optional selected state. Used for launchers, recents rails, and template pickers.",
+    "props": [
+        {
+            "name": "label",
+            "label": "Label",
+            "type": "string",
+            "required": true,
+            "placeholder": "Tile",
+            "description": "Visible label rendered below the media slot. Doubles as the default accessible name."
+        },
+        {
+            "name": "selected",
+            "label": "Selected",
+            "type": "boolean | () => boolean",
+            "required": false,
+            "description": "Selected state — opt-in toggle semantics. When provided, applies primary-tinted chrome and sets aria-pressed. Accepts a static boolean or a () => boolean accessor. Omit for non-toggle launcher tiles."
+        },
+        {
+            "name": "disabled",
+            "label": "Disabled",
+            "type": "boolean | () => boolean",
+            "default": false,
+            "description": "Disabled state — sets the disabled attribute and dims the chrome via the design-system disabled mixin. Accepts a static boolean or a () => boolean accessor."
+        },
+        {
+            "name": "ariaLabel",
+            "label": "ARIA label",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "required": false,
+            "description": "Accessible label override. Defaults to label."
+        },
+        {
+            "name": "draggable",
+            "label": "Draggable",
+            "editor": { "tab": "settings" },
+            "type": "boolean",
+            "default": false,
+            "description": "Marks the root button as a drag source via the native draggable attribute."
+        },
+        {
+            "name": "data",
+            "label": "Data",
+            "editor": { "tab": "settings" },
+            "type": "object",
+            "required": false,
+            "description": "Map of data-* attrs. CamelCase keys emit kebab-case attrs ({ componentId: 'card' } → data-component-id='card')."
+        },
+        {
+            "name": "labelRef",
+            "type": "function",
+            "required": false,
+            "description": "Callback invoked once with the rendered label span. Lets consumers wire effects (search-match highlight, badges) without querying Tile internals."
+        }
+    ],
+    "events": [
+        {
+            "name": "onClick",
+            "description": "Fired on click. Guarded against the disabled state — the handler is not invoked while disabled is truthy."
+        },
+        {
+            "name": "onDragStart",
+            "description": "Native dragstart listener — forwarded as-is."
+        },
+        {
+            "name": "onDragEnd",
+            "description": "Native dragend listener — forwarded as-is."
+        },
+        {
+            "name": "onAnimationEnd",
+            "description": "Native animationend listener — useful for one-shot CSS flash effects."
+        }
+    ],
+    "slots": [{ "name": "default", "displayName": "Content" }],
+    "tokens": {
+        "color": "--color-primary, --color-on-primary (via --_tile-color, --_tile-on-color), --color-surface, --color-text, --color-border",
+        "spacing": "--space-md (block padding, gap), --space-sm (inline padding)",
+        "radius": "--radius-md (tile), --radius-sm (media)",
+        "size": "--font-size-sm (label), --font-size-xs (glyph)",
+        "border": "--border-width-hairline (idle), --border-width-thin (forced-colors)",
+        "motion": "--motion-transition-background, --motion-transition-color, --motion-duration-normal, --motion-easing-standard"
+    },
+    "spacing": {
+        "media-to-label": "--space-md (friends — distinct content blocks inside the tile)",
+        "tiles-in-grid": "--space-sm (close friends — adjacent picker tiles)"
+    },
+    "constraints": [
+        "label is required and must be non-empty — DEV warning when missing",
+        "Disabled tiles skip onClick invocation entirely (preventDefault + stopImmediatePropagation)",
+        "Default slot is treated as decorative (aria-hidden) — semantic content belongs in label / ariaLabel",
+        "Reactive selected / disabled accessors wire an internal effect; static booleans apply state once"
+    ],
+    "a11y": [
+        "Renders a real <button type='button'> — gets keyboard activation, focus ring, and form-control semantics for free",
+        "aria-pressed is only set when selected is provided — non-toggle launcher tiles render as plain buttons (no toggle semantics)",
+        "aria-label defaults to label; explicit ariaLabel takes precedence",
+        "Forced-colors: explicit border + Highlight color when selected, GrayText when disabled"
+    ],
+    "ai": {
+        "synonyms": ["tile", "card", "launcher", "picker", "thumbnail", "item"],
+        "avoid": [
+            "div with onClick — use <Tile> so keyboard activation and focus ring come for free",
+            "raw background colors / radii — Tile handles surface and selection chrome",
+            "wrapping a <Button> with custom CSS — Tile is a sibling atom for vertical icon-over-label layouts"
+        ],
+        "patterns": [
+            "Recent picker: <Tile label=\"'Card'\" @click=\"insert\"> <Icon name=\"'card'\" decorative=\"true\" size=\"'sm'\" /> </Tile>",
+            "Selected tile: <Tile label=\"'Hero'\" selected=\"isHero\" @click=\"choose\"> <Icon name=\"'hero'\" /> </Tile>",
+            "Disabled tile: <Tile label=\"'Coming soon'\" disabled=\"true\"> <Icon name=\"'lock'\" /> </Tile>"
+        ]
+    },
+    "designGuidance": {
+        "surface": "Surface uses --color-surface with a hairline border. Hover/selected blend the primary tint via the design-system state-background mixin.",
+        "depth": "Flat by default; selected state uses tint + primary border, no shadow.",
+        "borders": "Hairline border in idle. Selected state swaps to a 1× primary border.",
+        "interactivity": "Hover, focus-visible, selected, and disabled states are all derived from design-system tokens — no bespoke colors.",
+        "darkMode": "Adapts automatically via --color-* tokens; the --_tile-color / --_tile-on-color split keeps the media glyph contrast correct in either mode."
+    },
+    "examples": [
+        {
+            "id": "default",
+            "title": "Default tile",
+            "pithy": "<Tile label=\"'Card'\"><Icon name=\"'card'\" decorative=\"true\" size=\"'sm'\" /></Tile>",
+            "assertions": [
+                "renders a <button class='ui-tile'>",
+                "label text content matches",
+                "aria-label matches label"
+            ]
+        },
+        {
+            "id": "selected",
+            "title": "Selected tile",
+            "pithy": "<Tile label=\"'Hero'\" selected=\"true\"><Icon name=\"'hero'\" decorative=\"true\" size=\"'sm'\" /></Tile>",
+            "assertions": ["data-selected='true'", "aria-pressed='true'"]
+        },
+        {
+            "id": "disabled",
+            "title": "Disabled launcher tile",
+            "pithy": "<Tile label=\"'Locked'\" disabled=\"true\"><Icon name=\"'lock'\" /></Tile>",
+            "assertions": [
+                "disabled attribute present",
+                "data-disabled='true'",
+                "aria-pressed not set (no selected prop)"
+            ]
+        }
+    ]
+}