@pithyjs/pidl-catalog 0.1.0-beta.0

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

@@ -0,0 +1,135 @@
+{
+    "kind": "component",
+    "id": "ui.action-tile",
+    "name": "ActionTile",
+    "displayName": "Action Tile",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "content",
+    "bidi": true,
+    "description": "Full-width actionable row with a leading icon/glyph slot beside a bold title and a muted description. Renders a <button>. Used for choice lists — publish tiers, export options, setup steps.",
+    "props": [
+        {
+            "name": "title",
+            "label": "Title",
+            "type": "string",
+            "required": true,
+            "placeholder": "Share Preview",
+            "description": "Bold primary line. Combined with the description to form the default accessible name."
+        },
+        {
+            "name": "description",
+            "label": "Description",
+            "type": "string",
+            "required": false,
+            "placeholder": "One self-contained HTML file",
+            "description": "Muted secondary line describing the action."
+        },
+        {
+            "name": "loading",
+            "label": "Loading",
+            "type": "boolean | () => boolean",
+            "reactive": true,
+            "default": false,
+            "description": "Loading state — sets aria-busy, shows a spinner in the media slot, and blocks clicks. Accepts a static boolean or a () => boolean accessor."
+        },
+        {
+            "name": "disabled",
+            "label": "Disabled",
+            "type": "boolean | () => boolean",
+            "reactive": true,
+            "default": false,
+            "description": "Disabled state — sets aria-disabled (keeping the control focusable, like Button) 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 the title and description text."
+        }
+    ],
+    "events": [
+        {
+            "name": "onClick",
+            "description": "Fired on click. Guarded against the disabled and loading states — the handler is not invoked while either is truthy."
+        }
+    ],
+    "slots": [{ "name": "default", "displayName": "Icon" }],
+    "tokens": {
+        "color": "--color-primary (via --_action-tile-color), --color-on-primary, --color-surface, --color-text, --color-text-muted, --color-border",
+        "spacing": "--space-md (inline padding), --space-sm (block padding, media gap), --space-xs (title ↔ description)",
+        "radius": "--radius-md (tile), --radius-sm (media), --radius-pill (spinner)",
+        "size": "--font-size-sm (title, description), --icon-size-lg (media), --icon-size-sm (spinner)",
+        "border": "--border-width-hairline (idle), --border-width-thin (forced-colors, spinner)",
+        "motion": "--motion-transition-background, --motion-transition-color, --motion-duration-normal, --motion-duration-slow, --motion-easing-standard"
+    },
+    "spacing": {
+        "media-to-body": "--space-sm (close friends — glyph next to its label block)",
+        "title-to-description": "--space-xs (lovers — two lines of one action)"
+    },
+    "constraints": [
+        "title is required and must be non-empty — DEV warning when missing",
+        "Blocked (disabled or loading) tiles skip onClick invocation entirely (preventDefault + stopImmediatePropagation)",
+        "Default slot is treated as decorative (aria-hidden) — semantic content belongs in title / description / ariaLabel",
+        "Reactive loading / disabled accessors wire an internal effect; static booleans apply state once"
+    ],
+    "a11y": [
+        "Renders a real <button type='button'> — keyboard activation, focus ring, and form-control semantics for free",
+        "Accessible name defaults to the title + description text; explicit ariaLabel takes precedence",
+        "loading sets aria-busy='true' so assistive tech announces the in-progress action",
+        "Forced-colors: explicit border, GrayText when disabled"
+    ],
+    "ai": {
+        "synonyms": [
+            "action tile",
+            "action row",
+            "option row",
+            "choice",
+            "menu item",
+            "launcher"
+        ],
+        "avoid": [
+            "a <Button> stretched full-width with custom CSS to fit a title + description — use <ActionTile>, which owns the two-line layout and busy/disabled a11y",
+            "div with onClick — use <ActionTile> so keyboard activation and focus ring come for free",
+            "<Tile> for horizontal icon-beside-text rows — Tile is the vertical icon-over-label variant"
+        ],
+        "patterns": [
+            "Publish tier: <ActionTile title=\"'Share Preview'\" description=\"'One self-contained HTML file'\" @click=\"share\"><Icon name=\"'share'\" decorative=\"true\" size=\"'sm'\" /></ActionTile>",
+            "Busy tier: <ActionTile title=\"'Download Files'\" description=\"'A .zip of the static site'\" loading=\"isExporting\" @click=\"download\"><Icon name=\"'download'\" decorative=\"true\" size=\"'sm'\" /></ActionTile>",
+            "Disabled tier: <ActionTile title=\"'Go Live'\" description=\"'Coming soon'\" disabled=\"true\"><Icon name=\"'send'\" /></ActionTile>"
+        ]
+    },
+    "designGuidance": {
+        "surface": "Surface uses --color-surface with a hairline border. Hover blends the primary tint via the design-system state-background mixin.",
+        "depth": "Flat by default; no shadow — depth is reserved for the containing surface (e.g. a Modal).",
+        "borders": "Hairline border in idle; hover tints the border toward primary.",
+        "interactivity": "Hover, focus-visible, loading, and disabled states derive from design-system tokens — no bespoke colors. The media glyph inverts to primary on hover/focus.",
+        "darkMode": "Adapts automatically via --color-* tokens; the --_action-tile-color split keeps the media glyph contrast correct in either mode."
+    },
+    "examples": [
+        {
+            "id": "default",
+            "title": "Default action tile",
+            "pithy": "<ActionTile title=\"'Share Preview'\" description=\"'One self-contained HTML file'\"><Icon name=\"'share'\" decorative=\"true\" size=\"'sm'\" /></ActionTile>",
+            "assertions": [
+                "renders a <button class='ui-action-tile'>",
+                "title text content matches",
+                "description text content matches"
+            ]
+        },
+        {
+            "id": "loading",
+            "title": "Loading action tile",
+            "pithy": "<ActionTile title=\"'Download Files'\" loading=\"true\"><Icon name=\"'download'\" decorative=\"true\" size=\"'sm'\" /></ActionTile>",
+            "assertions": ["data-loading='true'", "aria-busy='true'"]
+        },
+        {
+            "id": "disabled",
+            "title": "Disabled action tile",
+            "pithy": "<ActionTile title=\"'Go Live'\" description=\"'Coming soon'\" disabled=\"true\"><Icon name=\"'send'\" /></ActionTile>",
+            "assertions": ["aria-disabled='true'", "data-disabled='true'"]
+        }
+    ]
+}

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

@@ -0,0 +1,189 @@
+{
+    "kind": "component",
+    "id": "ui.badge",
+    "name": "Badge",
+    "displayName": "Badge",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "content",
+    "bidi": true,
+    "description": "Inline status badge for counts, labels, and dot indicators. Renders a <span> with semantic color, size, and variant styling. In dot mode renders a compact colored circle with role='status'.",
+    "props": [
+        {
+            "name": "text",
+            "reactive": true,
+            "label": "Text",
+            "type": "string | Signal<string>",
+            "placeholder": "New",
+            "description": "Visible badge text. Rendered as a text node inside the badge. Ignored in dot mode. When omitted, the component falls back to slot content."
+        },
+        {
+            "name": "iconStart",
+            "reactive": true,
+            "label": "Leading icon",
+            "type": "icon",
+            "description": "Icon shown before the badge text. Ignored in dot mode."
+        },
+        {
+            "name": "color",
+            "label": "Color",
+            "editor": { "type": "token-color" },
+            "type": "enum",
+            "enum": [
+                "primary",
+                "secondary",
+                "tertiary",
+                "success",
+                "info",
+                "warning",
+                "danger"
+            ],
+            "default": "primary",
+            "description": "Semantic color — maps to --color-* design tokens via --_badge-* custom properties."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Badge size — controls font-size and padding"
+        },
+        {
+            "name": "variant",
+            "label": "Variant",
+            "type": "enum",
+            "enum": ["filled", "outline", "subtle"],
+            "default": "filled",
+            "description": "Display variant — filled (solid bg), outline (border only), subtle (tinted bg)"
+        },
+        {
+            "name": "dot",
+            "label": "Dot",
+            "type": "boolean",
+            "default": false,
+            "description": "Dot-only mode — renders a small colored circle with no text. Requires label for accessibility."
+        },
+        {
+            "name": "pulse",
+            "label": "Pulse",
+            "type": "boolean",
+            "default": false,
+            "description": "Pulsing animation for dot mode — live indicator (respects prefers-reduced-motion)"
+        },
+        {
+            "name": "label",
+            "label": "Label",
+            "type": "string",
+            "required": false,
+            "description": "Accessible label. Required when dot is true. Optional for text badges (visible content is the accessible name)."
+        }
+    ],
+    "events": [],
+    "tokens": {
+        "color": "--color-{color}, --color-on-{color} (via --_badge-color, --_badge-on-color)",
+        "size": "--font-size-{xs|sm|body}, --space-{xs|sm|md}",
+        "radius": "--radius-pill (pill shape)",
+        "border": "--border-width-thin (outline variant, 40% opacity)",
+        "shadow": "--shadow-xs (filled variant depth)",
+        "motion": "--motion-duration-deliberate, --motion-easing-standard (pulse animation)"
+    },
+    "spacing": {
+        "badge-to-text": "--space-xs (lovers — badge inline with label)",
+        "badges-in-group": "--space-xs (lovers — related badges side by side)"
+    },
+    "constraints": [
+        "label is required when dot is true — DEV warning when missing",
+        "Dot mode ignores children, variant, and size — always renders as a solid colored circle sized by --space-sm token",
+        "Text badges use visible content as accessible name unless label overrides it",
+        "Colors are semantic only (primary/secondary/tertiary/success/info/warning/danger) — no text colors",
+        "Text truncates with ellipsis at max-inline-size 12rem (~20 chars at body font-size)",
+        "size has no effect in dot mode — DEV warning when set to a non-default size",
+        "Pulse animation respects prefers-reduced-motion (static opacity fallback)",
+        "pulse without dot has no effect — DEV warning when set on text badges",
+        "user-select: none — badges are labels, not selectable content"
+    ],
+    "a11y": [
+        "Dot mode: role='status' + aria-label for live-region semantics",
+        "Text badges: visible text content serves as accessible name",
+        "Explicit label prop overrides visible text via aria-label",
+        "Forced-colors: border fallback ensures visibility in high-contrast mode"
+    ],
+    "ai": {
+        "synonyms": [
+            "badge",
+            "tag",
+            "chip",
+            "label",
+            "pill",
+            "status indicator",
+            "count"
+        ],
+        "avoid": [
+            "div for badges — use <Badge> component",
+            "raw background colors — use color prop",
+            "hardcoded pill radius — component handles it",
+            "span with manual styling — use variant prop"
+        ],
+        "patterns": [
+            "Status badge: <Badge color=\"'success'\">Active</Badge>",
+            "Count badge: <Badge color=\"'danger'\" size=\"'sm'\">3</Badge>",
+            "Outline badge: <Badge variant=\"'outline'\" color=\"'info'\">Beta</Badge>",
+            "Subtle badge: <Badge variant=\"'subtle'\" color=\"'warning'\">Pending</Badge>",
+            "Dot indicator: <Badge dot=\"true\" color=\"'danger'\" label=\"'3 unread'\" />",
+            "Pulsing live dot: <Badge dot=\"true\" pulse=\"true\" color=\"'success'\" label=\"'Online'\" />"
+        ]
+    },
+    "designGuidance": {
+        "surface": "Filled uses solid semantic color bg with on-color text + inner glass highlight. Outline uses 40% opacity border. Subtle uses 18% tinted bg.",
+        "depth": "Filled has shadow-xs + inner highlight for subtle depth. Outline/subtle are flat.",
+        "borders": "Outline variant uses thin inset box-shadow at 40% opacity. Filled has inner glass highlight.",
+        "interactivity": "Badges are non-interactive (no hover/focus states). Use Button with badge styling for clickable tags.",
+        "darkMode": "Colors adapt automatically via --color-* custom properties. Dark-mode semantic tokens use higher lightness with dark on-colors for WCAG AA contrast.",
+        "inlineUsage": "Badges use vertical-align: super for notification-count positioning inline with text. min-inline-size guarantees circles for single-char content (counts). margin-inline-start provides optical spacing from preceding text."
+    },
+    "examples": [
+        {
+            "id": "filled",
+            "title": "Filled status badge",
+            "pithy": "<Badge color=\"'success'\">Active</Badge>",
+            "assertions": [
+                "has ui-badge class",
+                "data-variant='filled'",
+                "data-color='success'"
+            ]
+        },
+        {
+            "id": "outline",
+            "title": "Outline badge",
+            "pithy": "<Badge variant=\"'outline'\" color=\"'info'\">Beta</Badge>",
+            "assertions": ["data-variant='outline'", "data-color='info'"]
+        },
+        {
+            "id": "subtle",
+            "title": "Subtle badge",
+            "pithy": "<Badge variant=\"'subtle'\" color=\"'warning'\">Pending</Badge>",
+            "assertions": ["data-variant='subtle'", "data-color='warning'"]
+        },
+        {
+            "id": "dot",
+            "title": "Dot indicator",
+            "pithy": "<Badge dot=\"true\" color=\"'danger'\" label=\"'Unread messages'\" />",
+            "assertions": [
+                "has ui-badge-dot class",
+                "role='status'",
+                "aria-label='Unread messages'"
+            ]
+        },
+        {
+            "id": "pulsing-dot",
+            "title": "Pulsing live indicator",
+            "pithy": "<Badge dot=\"true\" pulse=\"true\" color=\"'success'\" label=\"'Online'\" />",
+            "assertions": [
+                "has ui-badge-pulse class",
+                "role='status'",
+                "aria-label='Online'"
+            ]
+        }
+    ]
+}

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

@@ -0,0 +1,170 @@
+{
+    "kind": "component",
+    "id": "ui.callout",
+    "name": "Callout",
+    "displayName": "Callout",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "content",
+    "bidi": true,
+    "description": "Static, tone-driven admonition/callout container for docs pages. Renders a role=note region with a decorative leading tone icon, a visually-hidden tone label (so tone is never conveyed by color alone), an optional bold title, and the body content. Tone (info | tip | warning | danger) drives the accent bar, tinted surface, and default icon.",
+    "props": [
+        {
+            "name": "content",
+            "label": "Content",
+            "type": "string",
+            "required": true,
+            "placeholder": "This behaviour is experimental and may change.",
+            "description": "The callout body, authored as text in the site builder. The component's TypeScript API additionally accepts a Node or a { el, destroy } ui-kit component. Strings are inserted as text (never HTML) — avoids injection and stray {{ }} interpolation."
+        },
+        {
+            "name": "tone",
+            "label": "Tone",
+            "type": "enum",
+            "enum": ["info", "tip", "warning", "danger"],
+            "default": "info",
+            "description": "Semantic tone driving the accent color, tinted surface, default icon, and visually-hidden label. Each tone has a distinct icon shape so tone is never conveyed by color alone: info→circle-info, tip→lightbulb, warning→triangle alert, danger→octagon alert. The legacy spelling 'warn' is still accepted as a deprecated alias for 'warning'."
+        },
+        {
+            "name": "title",
+            "label": "Title",
+            "type": "string",
+            "required": false,
+            "description": "Optional bold heading line above the body. Rendered as literal text (never HTML) via a bold <Text> line — not a document heading, so it does not affect heading hierarchy."
+        },
+        {
+            "name": "icon",
+            "label": "Icon",
+            "type": "icon",
+            "required": false,
+            "description": "Override the default tone icon with a named icon (resolved via the built-in icon fallback)."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "type": "enum",
+            "enum": ["md", "sm"],
+            "default": "md",
+            "description": "Density. 'md' (default) is the full docs callout; 'sm' is a compact variant for inline hints beside form fields — tighter padding, gap, and radius, with a smaller icon."
+        },
+        {
+            "name": "dismissible",
+            "label": "Dismissible",
+            "type": "boolean",
+            "default": false,
+            "description": "Show a trailing dismiss (×) button that tears down and removes the callout when clicked. The TypeScript API also accepts an onDismiss callback, fired just before removal."
+        },
+        {
+            "name": "ariaLabel",
+            "label": "ARIA label",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "required": false,
+            "description": "Accessible name for the callout container. Useful when several callouts share a page and need to be distinguished by assistive tech."
+        }
+    ],
+    "tokens": {
+        "color": "--color-info/success/warning/danger (per-tone accent, theme-aware), --color-surface (tint base), --color-text (body). Fill = color-mix(accent 12%, surface); border = color-mix(accent 30%, transparent); icon chip = color-mix(accent 20%, transparent); title = the tone accent (meets text contrast in both themes).",
+        "spacing": "--space-xs (icon chip padding), --space-sm (title↔body), --space-md (container padding + chip↔content gap)",
+        "radius": "--radius-lg (container), --radius-md (compact container, data-size='sm'), --radius-sm (icon chip + focus-ring rounding on body links)",
+        "border": "--border-width-hairline (full tone border), --border-width-medium (flush inset accent bar), --border-width-thin (forced-colors border)",
+        "typography": "--font-size-lg + weight semibold (title, via the <Text> component)"
+    },
+    "spacing": {
+        "chip-content-gap": "--space-md (friends — the icon chip beside the message column)",
+        "chip-padding": "--space-xs (the tinted chip's inset around the md icon → a 28px chip)",
+        "title-body-gap": "--space-sm (close friends — title above its body)",
+        "container-padding": "--space-md (comfortable reading padding; inline-start adds the accent-bar width so content clears the flush bar)"
+    },
+    "constraints": [
+        "content is required — it is the callout body",
+        "Inline container — no interactivity of its own except the optional dismiss (×) button when dismissible=true; body content may also contain its own links/controls",
+        "String content is inserted as text (textContent), never HTML — avoids injection and stray {{ }} interpolation",
+        "title is rendered as literal text via a bold <Text as='strong'> line — never a Heading atom, so it does not inject document hierarchy",
+        "Tone is conveyed by a visually-hidden text label (Information:/Tip:/Warning:/Danger:), never by color alone (WCAG 1.4.1)",
+        "The leading tone icon is decorative (aria-hidden) and resolves via the built-in icon fallback — no app sprite setup required",
+        "icon overrides the tone default glyph when provided"
+    ],
+    "a11y": [
+        "role=note names the container as an admonition region",
+        "Tone is announced via a visually-hidden label placed before the title/body — tone is never conveyed by color alone",
+        "Tone glyphs resolve through the normal icon pipeline, so an app sprite registering the same generic names (info/tip/alert/octagon-alert) overrides them. The visually-hidden tone label keeps the non-color-alone guarantee intact regardless, but an app that overrides these names should keep the shapes visually distinct",
+        "The leading tone icon is decorative (aria-hidden=true) so it is not double-announced",
+        "ariaLabel, when provided, sets the container's accessible name",
+        "Forced-colors: the accent tint is replaced by a solid CanvasText border so the container stays perceivable"
+    ],
+    "ai": {
+        "synonyms": [
+            "callout",
+            "admonition",
+            "note",
+            "notice",
+            "info box",
+            "warning box",
+            "alert box",
+            "tip",
+            "aside",
+            "banner note"
+        ],
+        "avoid": [
+            "using <Callout> as a transient or floating notification — it is an inline docs container (it can be dismissible, but it does not stack, auto-dismiss, or portal); use a feedback component (Toast/AlertDialog) for those",
+            "using <Badge> for a sentence-length message — Badge clips long text; <Callout> is for multi-word admonitions"
+        ],
+        "patterns": [
+            "Basic: <Callout content=\"'Heads up — this is experimental.'\" />",
+            "Toned with title: <Callout tone=\"'warning'\" title=\"'Deprecated'\" content=\"'Use the new API instead.'\" />",
+            "Danger: <Callout tone=\"'danger'\" content=\"'This action cannot be undone.'\" />",
+            "Custom icon: <Callout tone=\"'tip'\" icon=\"'eye'\" content=\"'Preview before publishing.'\" />"
+        ]
+    },
+    "designGuidance": {
+        "surface": "A tone-tinted fill (accent mixed ~12% into --color-surface) inside a full translucent tone border, with a flush inset accent bar on the inline-start edge and a tinted icon chip anchoring the tone. Every tone reads at a glance in both light and dark themes.",
+        "depth": "Flat — no shadow. Visual weight comes from the tinted fill, the tone border, the flush accent bar, and the icon chip.",
+        "borders": "A full --border-width-hairline tone border (color-mix of the accent at 30% alpha) around the whole card, plus a flush --border-width-medium accent bar rendered as an inset box-shadow (so it follows the rounded corners; RTL-flipped via :dir(rtl)). Forced-colors falls back to a solid CanvasText border.",
+        "interactivity": "The container itself is inert except for the optional trailing dismiss (×) button (dismissible=true), a ghost <Button> that removes the callout. Any other interactivity comes from body content (e.g. links), which surfaces the design-system focus ring.",
+        "motion": "Static by default — the exit transition is scoped to the dismissing state, so ordinary layout/theme changes are never animated. When dismissible, dismissing plays a motion-safe exit (fade + collapse to zero footprint, absorbing one gap along the flex container's main axis so siblings slide up); reduced-motion removes it instantly. Focus moves to the nearest survivor before removal.",
+        "bestPractices": "Use for tone-driven asides in docs and long-form content: info for context, tip for suggestions, warn for caveats, danger for irreversible/destructive warnings. Keep the title short and the body scannable. Prefer one callout per idea rather than stacking many."
+    },
+    "examples": [
+        {
+            "id": "default",
+            "title": "Info callout",
+            "pithy": "<Callout content=\"'PithyJS updates only signal-bound DOM nodes.'\" />",
+            "assertions": [
+                "renders <div class='ui-callout'>",
+                "role='note'",
+                "data-tone='info'",
+                "leading icon has data-icon='info'"
+            ]
+        },
+        {
+            "id": "tones",
+            "title": "All tones",
+            "pithy": "<Callout tone=\"'danger'\" content=\"'This cannot be undone.'\" />",
+            "assertions": [
+                "data-tone reflects the tone prop",
+                "each tone uses a distinct icon shape: info→info, tip→tip, warning→alert, danger→octagon-alert",
+                "a visually-hidden label announces the tone"
+            ]
+        },
+        {
+            "id": "titled",
+            "title": "With title",
+            "pithy": "<Callout tone=\"'warning'\" title=\"'Deprecated'\" content=\"'Use the new API.'\" />",
+            "assertions": [
+                "renders a bold .ui-callout-title line",
+                "title text stays literal (no HTML/interpolation)"
+            ]
+        },
+        {
+            "id": "component-body",
+            "title": "Component body",
+            "pithy": "<Callout content=\"body\" />",
+            "assertions": [
+                "content binds a context variable holding a { el, destroy } handle (e.g. const body = CodeBlock({ code }))",
+                "the component mounts in the callout body",
+                "its destroy is chained to the callout's destroy"
+            ]
+        }
+    ]
+}