@pithyjs/pidl-catalog 0.1.0-beta.0

package/dist/specs/atoms/content/code-block.pidl.json

@@ -0,0 +1,170 @@
+{
+    "kind": "component",
+    "id": "ui.code-block",
+    "name": "CodeBlock",
+    "displayName": "Code Block",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "content",
+    "bidi": false,
+    "description": "Syntax-highlighted code display for documentation pages. Renders a plaintext <pre><code> immediately (no layout shift), then lazy-loads Shiki and swaps in dual-theme highlighted markup. Supports 'Copy' and 'Copy as AI prompt' actions via ui-kit Button components.",
+    "props": [
+        {
+            "name": "code",
+            "label": "Code",
+            "type": "string",
+            "required": true,
+            "placeholder": "const x = 1;",
+            "description": "Source code to display. Rendered HTML-escaped in the synchronous fallback; passed to Shiki for highlighted output."
+        },
+        {
+            "name": "lang",
+            "label": "Language",
+            "type": "string",
+            "required": false,
+            "default": "text",
+            "placeholder": "typescript",
+            "description": "Language identifier for Shiki syntax highlighting (e.g. 'typescript', 'css', 'bash'). Falls back to plain text when omitted or unknown."
+        },
+        {
+            "name": "filename",
+            "label": "Filename",
+            "type": "string",
+            "required": false,
+            "placeholder": "index.ts",
+            "description": "Filename shown in the header bar. Falls back to the lang value when omitted."
+        },
+        {
+            "name": "highlightLines",
+            "label": "Highlight lines",
+            "type": "string",
+            "required": false,
+            "placeholder": "1,3-5",
+            "description": "Line numbers to highlight, e.g. '1,3-5'. Parsed into a Set<number> and forwarded to Shiki's line transformer. Has no effect until Shiki loads."
+        },
+        {
+            "name": "showCopy",
+            "label": "Show copy button",
+            "type": "boolean",
+            "required": false,
+            "default": true,
+            "description": "Show the 'Copy code' button in the header."
+        },
+        {
+            "name": "showCopyAsPrompt",
+            "label": "Show 'Copy as AI prompt' button",
+            "type": "boolean",
+            "required": false,
+            "default": true,
+            "description": "Show the 'Copy as AI prompt' button, which wraps the code in a markdown code fence prefixed by promptPrefix."
+        },
+        {
+            "name": "promptPrefix",
+            "label": "AI prompt prefix",
+            "type": "string",
+            "required": false,
+            "default": "Explain this code:",
+            "placeholder": "Explain this code:",
+            "description": "Text prepended before the markdown-fenced code block when 'Copy as AI prompt' is clicked."
+        },
+        {
+            "name": "ariaLabel",
+            "label": "ARIA label",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "required": false,
+            "description": "Accessible label forwarded as aria-label on the root element. Recommended when the visible filename/lang label is insufficient context."
+        }
+    ],
+    "tokens": {
+        "color": "--color-surface-variant (body bg), --color-surface-dim (header bg), --color-border, --color-text, --color-text-muted, --color-primary (line highlight tint)",
+        "spacing": "--space-xs (header padding, action gap), --space-sm (code padding)",
+        "radius": "--radius-md (root border-radius)",
+        "size": "--font-size-sm (code body), --font-size-xs (header label)",
+        "border": "--border-width-thin (outer border), --border-width-hairline (header divider)",
+        "motion": "--motion-transition-background"
+    },
+    "spacing": {
+        "header-actions-gap": "--space-xs (lovers — icon buttons beside each other)"
+    },
+    "constraints": [
+        "code is required — renders an empty <pre><code></code></pre> when code is an empty string",
+        "Shiki is loaded via dynamic import and module-scope memoised — one highlighter shared across all CodeBlock instances on the page",
+        "highlightLines applies only after Shiki resolves; the synchronous plaintext fallback shows no highlights",
+        "Both Copy buttons compose <Button variant='ghost' size='sm'> — no raw <button> elements",
+        "The language label composes <Text> — no raw <span> elements",
+        "Light/dark theme switching is CSS-only via [data-theme='dark'] on the root element — no JS event subscription"
+    ],
+    "a11y": [
+        "Root element accepts an aria-label for the code block as a whole",
+        "Header label uses <Text as='span'> with color='text-muted'",
+        "Copy buttons include reactive ariaLabel: 'Copy code' → 'Copied to clipboard' after click",
+        "An aria-live='polite' region (class ui-code-block-live) announces 'Copied to clipboard!' and 'Copied as AI prompt!' to screen readers",
+        "Forced-colors: outer border set to ButtonText; header divider set to ButtonText"
+    ],
+    "ai": {
+        "synonyms": [
+            "code block",
+            "syntax highlight",
+            "code snippet",
+            "code viewer",
+            "code display",
+            "code example",
+            "code sample"
+        ],
+        "avoid": [
+            "a bare <pre><code> with manually applied highlight.js or Prism — use <CodeBlock> which provides copy buttons, a11y live regions, and design-system token integration",
+            "hand-rolling copy buttons as raw <button> elements — CodeBlock's buttons compose from ui-kit <Button>"
+        ],
+        "patterns": [
+            "Basic: <CodeBlock code=\"'const x = 1;'\" lang=\"'typescript'\" />",
+            "With filename: <CodeBlock code=\"src\" lang=\"'tsx'\" filename=\"'App.tsx'\" />",
+            "Highlighted lines: <CodeBlock code=\"src\" lang=\"'css'\" highlightLines=\"'2,4-6'\" />",
+            "Copy only, no prompt button: <CodeBlock code=\"src\" lang=\"'bash'\" showCopyAsPrompt=\"false\" />",
+            "No copy buttons: <CodeBlock code=\"src\" lang=\"'json'\" showCopy=\"false\" showCopyAsPrompt=\"false\" />"
+        ]
+    },
+    "designGuidance": {
+        "surface": "Body uses --color-surface-variant; header uses --color-surface-dim — a subtle step darker. Together they read as one card-like container.",
+        "depth": "Thin border (--border-width-thin) defines the container boundary. No shadow — code blocks are content, not elevated UI.",
+        "borders": "Outer radius --radius-md; header divided from body by a hairline border in --color-border.",
+        "interactivity": "Copy buttons are ghost-variant — they disappear into the header and only become visible on hover/focus. Transient 'Copied!' label resets after 2 seconds.",
+        "darkMode": "Shiki dual-theme: --shiki-light and --shiki-dark CSS variables applied per token. Switching is purely CSS via [data-theme='dark'] — no re-render.",
+        "bestPractices": "Use ariaLabel when the code block is the primary content of a section, or when there are multiple code blocks on the same page with similar lang/filename labels."
+    },
+    "examples": [
+        {
+            "id": "default",
+            "title": "Basic TypeScript block",
+            "pithy": "<CodeBlock code=\"'const x: number = 1;'\" lang=\"'typescript'\" />",
+            "assertions": [
+                "renders <div class='ui-code-block'>",
+                "contains <pre class='ui-code-block-pre'>",
+                "header contains 'typescript'"
+            ]
+        },
+        {
+            "id": "with-filename",
+            "title": "With filename",
+            "pithy": "<CodeBlock code=\"'export default function App() {}'\" lang=\"'typescript'\" filename=\"'App.ts'\" />",
+            "assertions": [
+                "header contains 'App.ts'",
+                "does not contain 'typescript' as separate label"
+            ]
+        },
+        {
+            "id": "no-copy",
+            "title": "Read-only (no copy buttons)",
+            "pithy": "<CodeBlock code=\"'Hello, World!'\" lang=\"'text'\" showCopy=\"false\" showCopyAsPrompt=\"false\" />",
+            "assertions": ["no .ui-button elements rendered"]
+        },
+        {
+            "id": "highlight-lines",
+            "title": "With line highlights",
+            "pithy": "<CodeBlock code=\"src\" lang=\"'javascript'\" highlightLines=\"'1,3-5'\" />",
+            "assertions": [
+                "data-highlighted on lines 1, 3, 4, 5 (after Shiki resolves)"
+            ]
+        }
+    ]
+}

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

@@ -0,0 +1,175 @@
+{
+    "kind": "component",
+    "id": "ui.heading",
+    "name": "Heading",
+    "displayName": "Heading",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "content",
+    "bidi": true,
+    "description": "Semantic heading component for page titles and section headers. Renders the correct <h1>-<h6> tag based on level prop. Size and weight can be overridden independently of heading level.",
+    "props": [
+        {
+            "name": "text",
+            "reactive": true,
+            "label": "Text",
+            "type": "string | Signal<string>",
+            "placeholder": "Your heading",
+            "description": "Visible heading text. Rendered as a text node inside the h1-h6 tag. When omitted, the component falls back to slot content."
+        },
+        {
+            "name": "level",
+            "label": "Level",
+            "editor": { "tab": "settings" },
+            "type": "number",
+            "enum": [1, 2, 3, 4, 5, 6],
+            "default": 2,
+            "description": "Heading level — determines the HTML tag <h1>-<h6>. Non-integers are rounded, out-of-range values are clamped to 1-6."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "editor": { "type": "token-font" },
+            "type": "enum",
+            "enum": ["xs", "sm", "base", "lg", "xl", "2xl", "3xl", "4xl"],
+            "description": "Font size override — maps to u-text-* utilities. When omitted, uses native heading level size from browser defaults + typography scale."
+        },
+        {
+            "name": "weight",
+            "label": "Weight",
+            "type": "enum",
+            "enum": [
+                "thin",
+                "light",
+                "normal",
+                "medium",
+                "semibold",
+                "bold",
+                "extrabold"
+            ],
+            "description": "Font weight override — maps to u-font-* utilities. When omitted, uses native heading weight (semibold)."
+        },
+        {
+            "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"
+        }
+    ],
+    "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, optional override)",
+        "font-weight": "--font-weight-{weight} (via u-font-* utility, optional override)"
+    },
+    "spacing": {
+        "internal": "margin: 0 (reset) — external spacing controlled by parent layout",
+        "heading-to-content": "--space-sm (close friends — heading and its content are tightly coupled)",
+        "heading-to-heading": "--space-xs (lovers — main heading and subheading)",
+        "section-heading": "--space-lg (acquaintances — heading introducing a new section)"
+    },
+    "constraints": [
+        "Never skip heading levels — go from h1 to h2, not h1 to h3",
+        "Never use raw hex colors — use color prop with design token values",
+        "Never use physical CSS properties — alignment uses logical values (start/end, not left/right)",
+        "Use level for document hierarchy and size for visual override — they are independent",
+        "Must handle forced-colors mode — color: CanvasText",
+        "Must handle high-contrast mode — bump text-muted to full text color"
+    ],
+    "a11y": [
+        "Renders correct <h1>-<h6> tag — critical for document outline and screen reader navigation",
+        "Never skip heading levels in the document hierarchy",
+        "Visual size can differ from semantic level via the size prop",
+        "Forced-colors: uses CanvasText for visibility",
+        "High-contrast: text-muted upgraded to full text color"
+    ],
+    "ai": {
+        "synonyms": [
+            "title",
+            "header",
+            "section title",
+            "page title",
+            "heading text",
+            "h1",
+            "h2",
+            "h3"
+        ],
+        "avoid": [
+            "div with font-size for headings — use <Heading> with correct level",
+            "skipping heading levels (h1 to h3) — always use consecutive levels",
+            "using level for visual size — use size prop for visual override",
+            "hardcoded font sizes or weights — use size/weight props"
+        ],
+        "patterns": [
+            "Page title: <Heading level=\"1\">Welcome</Heading>",
+            "Section heading: <Heading level=\"2\" color=\"'primary'\">Features</Heading>",
+            "Visually large h3: <Heading level=\"3\" size=\"'2xl'\">Big Section</Heading>",
+            "Centered subtitle: <Heading level=\"2\" size=\"'lg'\" align=\"'center'\" color=\"'text-muted'\">Our Mission</Heading>",
+            "Card title: <Heading level=\"3\" size=\"'md'\" weight=\"'bold'\">Card Title</Heading>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "page-title",
+            "title": "Page title (h1)",
+            "pithy": "<Heading level=\"1\">Welcome to PithyJS</Heading>",
+            "assertions": [
+                "renders <h1> element",
+                "has class ui-heading",
+                "data-color='text'"
+            ]
+        },
+        {
+            "id": "styled-section",
+            "title": "Styled section heading",
+            "pithy": "<Heading level=\"2\" size=\"'xl'\" color=\"'primary'\" align=\"'center'\">Features</Heading>",
+            "assertions": [
+                "renders <h2>",
+                "has u-text-xl class",
+                "data-color='primary'",
+                "data-align='center'"
+            ]
+        },
+        {
+            "id": "visual-override",
+            "title": "Visual size independent of level",
+            "pithy": "<Heading level=\"4\" size=\"'2xl'\">Visually Large h4</Heading>",
+            "assertions": ["renders <h4> element", "has u-text-2xl class"]
+        },
+        {
+            "id": "truncated-heading",
+            "title": "Truncated heading",
+            "pithy": "<Heading level=\"3\" truncate>Very Long Heading That Truncates</Heading>",
+            "assertions": ["has u-truncate class"]
+        }
+    ]
+}

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

@@ -0,0 +1,127 @@
+{
+    "kind": "component",
+    "id": "ui.icon",
+    "name": "Icon",
+    "displayName": "Icon",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "content",
+    "bidi": true,
+    "description": "Inline icon wrapper with accessible sizing and labelling. Renders children (inline SVG or icon markup) inside a <span> with design-system icon size tokens and proper ARIA attributes. Discriminated union enforces label when not decorative.",
+    "props": [
+        {
+            "name": "name",
+            "reactive": true,
+            "label": "Icon name",
+            "editor": { "type": "icon" },
+            "placeholder": "sparkles",
+            "type": "string | Signal<string>",
+            "required": false,
+            "description": "Icon identifier — sets data-icon attribute and resolves SVG from sprite registry. Pass a function (e.g. () => signal()) for reactive icon swapping; the SVG re-mounts only when the resolved name changes."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "type": "enum",
+            "enum": ["xs", "sm", "md", "lg", "xl", "xxl"],
+            "default": "md",
+            "description": "Icon size — maps to --icon-size-* design tokens via u-icon-* utility classes"
+        },
+        {
+            "name": "color",
+            "label": "Color",
+            "editor": { "type": "token-color" },
+            "type": "enum",
+            "enum": [
+                "text",
+                "text-muted",
+                "text-inverse",
+                "primary",
+                "secondary",
+                "tertiary",
+                "success",
+                "info",
+                "warning",
+                "danger"
+            ],
+            "description": "Icon color — maps to --color-* design tokens. Defaults to undefined (inherits via currentColor)."
+        },
+        {
+            "name": "decorative",
+            "label": "Decorative",
+            "editor": { "tab": "settings" },
+            "type": "boolean",
+            "default": false,
+            "description": "Whether the icon is purely decorative — hides from assistive tech when true"
+        },
+        {
+            "name": "label",
+            "label": "Label",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Accessible label — required when decorative is false. TypeScript enforces via discriminated union."
+        }
+    ],
+    "events": [],
+    "tokens": {
+        "size": "--icon-size-{size} (via u-icon-{size})",
+        "color": "--color-{color} (via data-color attribute)"
+    },
+    "spacing": {
+        "icon-to-label": "--space-xs (lovers — icon and label are inseparable)"
+    },
+    "constraints": [
+        "label is required when decorative is false — enforced at TypeScript level via discriminated union",
+        "color defaults to undefined (inherits currentColor) — differs from Text/Heading which default to 'text'",
+        "name sets data-icon attribute and resolves SVG from icon sprite registry via <svg><use href='sprite.svg#name'/></svg> when no children are provided (this is the runtime output; static export rewrites it post-hoc to a document-local <use href='#pithy-icon-name'> and inlines the symbol, so the exported markup differs from what the component emits)",
+        "Children take precedence over registry (explicit inline SVG always wins over sprite resolution); reactive name is ignored when children are present",
+        "Reactive name (function) only re-mounts the SVG when the resolved name actually changes; identical re-runs are a no-op. The effect is disposed on destroy().",
+        "Missing icon names render a placeholder (dashed circle + '?') with data-icon-missing attribute and DEV console warning"
+    ],
+    "a11y": [
+        "Semantic icons: role='img' + aria-label from label prop",
+        "Decorative icons: aria-hidden='true' + role='none' — completely hidden from assistive tech",
+        "If decorative=false and label is empty, role='img' is intentionally skipped to avoid broken ARIA state",
+        "DEV warning when semantic icon missing label, or decorative icon has unused label"
+    ],
+    "ai": {
+        "synonyms": ["icon", "svg icon", "inline icon", "glyph", "symbol"],
+        "avoid": [
+            "img tag for icons — use <Icon> with inline SVG",
+            "aria-hidden on semantic icons — use decorative prop",
+            "hardcoded icon sizes — use size prop"
+        ],
+        "patterns": [
+            "Semantic icon (inline SVG): <Icon label=\"'Search'\" size=\"'lg'\"><svg>...</svg></Icon>",
+            "Semantic icon (sprite): <Icon label=\"'Search'\" name=\"'search'\" size=\"'lg'\" />",
+            "Decorative icon: <Icon decorative size=\"'sm'\" name=\"'star'\" />",
+            "Colored icon: <Icon label=\"'Warning'\" color=\"'warning'\" name=\"'warning'\" />",
+            "Reactive icon (theme toggle): <Icon decorative name=\"() => isDark() ? 'sun' : 'moon'\" />"
+        ]
+    },
+    "examples": [
+        {
+            "id": "semantic",
+            "title": "Semantic icon with label",
+            "pithy": "<Icon label=\"'Search'\"><svg viewBox=\"0 0 24 24\"><path d=\"M...\"/></svg></Icon>",
+            "assertions": ["role='img'", "aria-label='Search'", "has ui-icon class"]
+        },
+        {
+            "id": "decorative",
+            "title": "Decorative icon",
+            "pithy": "<Icon decorative size=\"'sm'\"><svg viewBox=\"0 0 24 24\"><path d=\"M...\"/></svg></Icon>",
+            "assertions": ["aria-hidden='true'", "role='none'", "has u-icon-sm class"]
+        },
+        {
+            "id": "reactive-name",
+            "title": "Reactive icon driven by a signal",
+            "pithy": "<Icon decorative name=\"() => mode() === 'dark' ? 'sun' : 'moon'\" />",
+            "assertions": [
+                "data-icon swaps when signal changes",
+                "<use href> updates to '#sun' or '#moon'",
+                "no SVG rebuild when signal fires with same value",
+                "effect disposed on destroy()"
+            ]
+        }
+    ]
+}