@pithyjs/pidl-catalog 0.1.0-beta.0

package/dist/specs/layout/page-section.pidl.json

@@ -0,0 +1,105 @@
+{
+    "kind": "component",
+    "id": "ui.page-section",
+    "name": "PageSection",
+    "displayName": "Page Section",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "layout",
+    "bidi": true,
+    "description": "Semantic page section wrapper with consistent vertical spacing, optional containment, and full-bleed support. Named PageSection to avoid collision with native <section>.",
+    "props": [
+        {
+            "name": "spacing",
+            "label": "Spacing",
+            "editor": { "tab": "layout", "type": "token-space" },
+            "type": "enum",
+            "enum": ["0", "xs", "sm", "md", "lg", "xl"],
+            "default": "lg",
+            "description": "Vertical padding — maps to u-py-* utilities"
+        },
+        {
+            "name": "contained",
+            "label": "Contained",
+            "editor": { "tab": "layout" },
+            "type": "boolean",
+            "default": false,
+            "description": "Apply max-width + centered layout with gutters"
+        },
+        {
+            "name": "fullBleed",
+            "label": "Full bleed",
+            "editor": { "tab": "layout" },
+            "type": "boolean",
+            "default": false,
+            "description": "Edge-to-edge viewport width breakout"
+        },
+        {
+            "name": "as",
+            "label": "Element",
+            "editor": { "tab": "settings" },
+            "type": "enum",
+            "enum": ["section", "article", "aside", "header", "footer", "main"],
+            "default": "section",
+            "description": "Semantic HTML tag"
+        },
+        {
+            "name": "id",
+            "label": "Anchor ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Optional anchor id for in-page linking"
+        }
+    ],
+    "events": [],
+    "slots": [{ "name": "default", "displayName": "Content" }],
+    "tokens": {
+        "spacing": "--space-{spacing} (via u-py-*)",
+        "container.max-width": "CONTAINER_BREAKPOINTS.xl",
+        "container.gutter": "--space-md"
+    },
+    "spacing": {
+        "vertical-padding": "--space-{spacing} (strangers — between page sections use xl, within use lg)"
+    },
+    "constraints": [
+        "contained and fullBleed are mutually exclusive — fullBleed takes precedence",
+        "Use logical properties only — marginInline, paddingInline",
+        "Does not add max-width on its own — use contained prop or let the page wrapper control width"
+    ],
+    "a11y": [
+        "Uses semantic HTML elements via as prop — <section>, <article>, <aside>, <header>, <footer>, <main>",
+        "id prop enables in-page anchor navigation",
+        "No ARIA attributes needed — semantics come from the HTML element"
+    ],
+    "ai": {
+        "synonyms": [
+            "section wrapper",
+            "page section",
+            "content section",
+            "layout section"
+        ],
+        "avoid": [
+            "div with padding for page sections — use <PageSection>",
+            "contained + fullBleed together — they conflict"
+        ],
+        "patterns": [
+            "Contained section: <PageSection spacing=\"'lg'\" contained><Heading>Features</Heading></PageSection>",
+            "Full-bleed hero: <PageSection spacing=\"'xl'\" fullBleed>...</PageSection>",
+            "Anchored section: <PageSection id=\"'about'\" as=\"'article'\">...</PageSection>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic-section",
+            "title": "Basic page section",
+            "pithy": "<PageSection spacing=\"'lg'\"><Heading>Features</Heading><Text>Details here</Text></PageSection>",
+            "assertions": ["renders <section>", "has u-py-lg class"]
+        },
+        {
+            "id": "contained",
+            "title": "Contained section with max-width",
+            "pithy": "<PageSection contained><Text>Centered content</Text></PageSection>",
+            "assertions": ["has max-width style", "has margin-inline: auto"]
+        }
+    ]
+}

package/dist/specs/layout/smart-container.pidl.json

@@ -0,0 +1,148 @@
+{
+    "kind": "component",
+    "id": "ui.smart-container",
+    "name": "SmartContainer",
+    "displayName": "Smart Container",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "layout",
+    "bidi": true,
+    "description": "Higher-level layout component providing 5 opinionated responsive layout recipes (auto-grid, stack-to-row, row-wrap, sidebar, equal-cards) that adapt to container width via CSS container queries.",
+    "props": [
+        {
+            "name": "recipe",
+            "label": "Recipe",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": [
+                "auto-grid",
+                "stack-to-row",
+                "row-wrap",
+                "sidebar",
+                "equal-cards"
+            ],
+            "default": "auto-grid",
+            "description": "Layout recipe — each provides a different responsive behavior pattern"
+        },
+        {
+            "name": "minItem",
+            "label": "Min item",
+            "editor": { "tab": "layout" },
+            "type": "string",
+            "description": "Minimum item width for auto-grid recipe, e.g. '14rem', '250px'"
+        },
+        {
+            "name": "gap",
+            "label": "Gap",
+            "editor": { "tab": "layout", "type": "token-space" },
+            "type": "enum",
+            "enum": ["0", "xs", "sm", "md", "lg", "xl"],
+            "default": "md",
+            "description": "Gap between children — maps to u-gap-* utilities"
+        },
+        {
+            "name": "density",
+            "label": "Density",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["compact", "normal", "relaxed"],
+            "default": "normal",
+            "description": "Density scaling — compact (0.9), normal (1.0), relaxed (1.25)"
+        },
+        {
+            "name": "align",
+            "label": "Align",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["start", "center", "end", "stretch", "baseline"],
+            "description": "Cross-axis alignment — maps to u-items-* utilities"
+        },
+        {
+            "name": "justify",
+            "label": "Justify",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["start", "end", "center", "between", "around", "evenly"],
+            "description": "Main-axis justification — maps to u-justify-* utilities"
+        },
+        {
+            "name": "lanes",
+            "label": "Lanes",
+            "editor": { "tab": "layout" },
+            "type": "number",
+            "default": 3,
+            "description": "Max column count for equal-cards recipe (2-6)"
+        },
+        {
+            "name": "as",
+            "label": "Element",
+            "editor": { "tab": "settings" },
+            "type": "enum",
+            "enum": ["div", "section", "article", "aside"],
+            "default": "div",
+            "description": "HTML tag to render (outer container)"
+        }
+    ],
+    "events": [],
+    "slots": [{ "name": "default", "displayName": "Content" }],
+    "tokens": {
+        "gap": "--space-{gap} (via u-gap-*)",
+        "density": "density custom property via applyElementDensity()",
+        "auto-min": "--grid-auto-min (CSS custom property for auto-grid)"
+    },
+    "spacing": {
+        "between-children": "--space-{gap} (friendship model — choose gap based on child relationship)",
+        "card-grid": "--space-md (friends — cards in a grid)"
+    },
+    "constraints": [
+        "minItem only applies to auto-grid recipe — ignored for other recipes",
+        "lanes only applies to equal-cards recipe (clamped 2-6) — ignored for other recipes",
+        "Uses double-nesting (outer container-type + inner layout) — outer element has container-type: inline-size",
+        "Use logical properties only (handled automatically via utility classes)"
+    ],
+    "a11y": [
+        "Uses semantic HTML via as prop for the outer container",
+        "Layout is presentational — no ARIA attributes needed",
+        "Density scaling is visual only — does not affect screen reader content"
+    ],
+    "ai": {
+        "synonyms": [
+            "smart layout",
+            "responsive container",
+            "auto layout",
+            "adaptive grid",
+            "card container"
+        ],
+        "avoid": [
+            "manual media queries — use recipe prop for responsive behavior",
+            "SmartContainer for simple 1-direction layouts — use <Stack> instead",
+            "SmartContainer when exact column control needed — use <Grid> instead"
+        ],
+        "patterns": [
+            "Auto-grid cards: <SmartContainer recipe=\"'auto-grid'\" minItem=\"'14rem'\" gap=\"'lg'\"><Card/><Card/><Card/></SmartContainer>",
+            "Sidebar layout: <SmartContainer recipe=\"'sidebar'\"><aside>Nav</aside><main>Content</main></SmartContainer>",
+            "Equal cards: <SmartContainer recipe=\"'equal-cards'\" lanes=\"4\" gap=\"'md'\"><Card/><Card/><Card/><Card/></SmartContainer>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "auto-grid",
+            "title": "Auto-grid with minimum item width",
+            "pithy": "<SmartContainer recipe=\"'auto-grid'\" minItem=\"'14rem'\" gap=\"'lg'\"><div>Card 1</div><div>Card 2</div><div>Card 3</div></SmartContainer>",
+            "assertions": [
+                "outer has u-container-inline",
+                "inner has u-grid-auto-fit",
+                "--grid-auto-min set"
+            ]
+        },
+        {
+            "id": "equal-cards",
+            "title": "Equal cards with lane limit",
+            "pithy": "<SmartContainer recipe=\"'equal-cards'\" lanes=\"4\"><div>A</div><div>B</div><div>C</div><div>D</div></SmartContainer>",
+            "assertions": [
+                "inner has responsive grid column classes",
+                "capped at 4 columns"
+            ]
+        }
+    ]
+}

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

@@ -0,0 +1,144 @@
+{
+    "kind": "component",
+    "id": "ui.stack",
+    "name": "Stack",
+    "displayName": "Stack",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "layout",
+    "bidi": true,
+    "description": "Flexbox layout atom that arranges children in a vertical or horizontal stack. Maps props to design-system utility classes — no custom CSS required.",
+    "props": [
+        {
+            "name": "direction",
+            "label": "Direction",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["vertical", "horizontal"],
+            "default": "vertical",
+            "description": "Stack direction — vertical (column) or horizontal (row)"
+        },
+        {
+            "name": "gap",
+            "label": "Gap",
+            "editor": { "tab": "layout", "type": "token-space" },
+            "type": "enum",
+            "enum": ["0", "xs", "sm", "md", "lg", "xl"],
+            "default": "md",
+            "description": "Gap between children — maps to u-gap-* utilities"
+        },
+        {
+            "name": "align",
+            "label": "Align",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["start", "center", "end", "stretch", "baseline"],
+            "default": "stretch",
+            "description": "Cross-axis alignment — maps to u-items-* utilities"
+        },
+        {
+            "name": "wrap",
+            "label": "Wrap",
+            "editor": { "tab": "layout" },
+            "type": "boolean",
+            "default": false,
+            "description": "Whether children wrap to next line"
+        },
+        {
+            "name": "reverse",
+            "label": "Reverse",
+            "editor": { "tab": "layout" },
+            "type": "boolean",
+            "default": false,
+            "description": "Reverse the stacking order"
+        },
+        {
+            "name": "minChildWidth",
+            "label": "Min child width",
+            "editor": { "tab": "layout" },
+            "type": "string",
+            "description": "Minimum child width (CSS value, e.g. '200px'). Only applies to horizontal stacks — injects a <style> with flex-basis/min-inline-size per child."
+        },
+        {
+            "name": "as",
+            "label": "Element",
+            "editor": { "tab": "settings" },
+            "type": "enum",
+            "enum": [
+                "div",
+                "section",
+                "article",
+                "aside",
+                "header",
+                "footer",
+                "main",
+                "nav",
+                "ul",
+                "ol",
+                "fieldset"
+            ],
+            "default": "div",
+            "description": "HTML tag to render"
+        }
+    ],
+    "events": [],
+    "slots": [{ "name": "default", "displayName": "Content" }],
+    "tokens": {
+        "gap": "--space-{gap} (via u-gap-*)",
+        "align": "u-items-{align}",
+        "direction": "u-vstack | u-hstack"
+    },
+    "spacing": {
+        "between-children": "--space-{gap} (friendship model — choose gap based on child relationship)"
+    },
+    "constraints": [
+        "Never use raw margin/padding between children — use gap prop",
+        "Use logical properties only (handled automatically via utility classes)",
+        "Choose gap value using the friendship spacing model"
+    ],
+    "a11y": [
+        "Uses semantic HTML via as prop — choose correct element for context",
+        "No ARIA attributes needed — layout is presentational"
+    ],
+    "ai": {
+        "synonyms": [
+            "flex column",
+            "flex row",
+            "vertical layout",
+            "horizontal layout",
+            "vstack",
+            "hstack"
+        ],
+        "avoid": [
+            "nested divs with margin — use <Stack> with gap prop",
+            "manual flexbox styling — use <Stack> component"
+        ],
+        "patterns": [
+            "Form field group: <Stack gap=\"'sm'\"><label>Name</label><input/></Stack>",
+            "Button row: <Stack direction=\"'horizontal'\" gap=\"'md'\" align=\"'center'\"><Button>Save</Button><Button variant=\"'ghost'\">Cancel</Button></Stack>",
+            "Page layout: <Stack gap=\"'xl'\" as=\"'main'\"><section>...</section></Stack>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "vertical-stack",
+            "title": "Basic vertical stack",
+            "pithy": "<Stack gap=\"'md'\"><Text>Item 1</Text><Text>Item 2</Text></Stack>",
+            "assertions": [
+                "renders <div>",
+                "has u-vstack class",
+                "has u-gap-md class"
+            ]
+        },
+        {
+            "id": "horizontal-stack",
+            "title": "Horizontal button row",
+            "pithy": "<Stack direction=\"'horizontal'\" gap=\"'sm'\" align=\"'center'\"><Button>Save</Button><Button variant=\"'ghost'\">Cancel</Button></Stack>",
+            "assertions": [
+                "has u-hstack class",
+                "has u-gap-sm class",
+                "has u-items-center class"
+            ]
+        }
+    ]
+}

package/dist/specs/organisms/content/accordion.pidl.json

@@ -0,0 +1,196 @@
+{
+    "kind": "component",
+    "id": "ui.accordion",
+    "name": "Accordion",
+    "displayName": "Accordion",
+    "version": "0.1.0",
+    "level": "organism",
+    "domain": "content",
+    "bidi": true,
+    "description": "Disclosure list built on native <details>/<summary>. Keyboard and screen-reader correct with zero ARIA scaffolding and a zero-JS baseline. Items are passed as a typed array and/or projected as children. Optional single-open mode closes siblings when one item opens (progressive enhancement).",
+    "props": [
+        {
+            "name": "items",
+            "reactive": true,
+            "label": "Items",
+            "type": "AccordionItem[] | Signal<AccordionItem[]>",
+            "placeholder": [
+                {
+                    "title": "What is this component?",
+                    "content": "A reusable disclosure list. Each row is a native <details> element, so it works with the keyboard and assistive technology out of the box."
+                },
+                {
+                    "title": "Do I need JavaScript?",
+                    "content": "No. The base markup is fully usable without JavaScript. Single-open behavior is layered on as a progressive enhancement."
+                },
+                {
+                    "title": "Can more than one item be open at once?",
+                    "content": "Yes, in the default 'multi' mode. Switch to 'single' mode to close sibling items automatically when one opens."
+                },
+                {
+                    "title": "How do I set an item open by default?",
+                    "content": "Pass a defaultOpen index (or array of indices), or set open: true on an individual item."
+                }
+            ],
+            "description": "Array of disclosure items, each with a title and content. Titles and content may be plain strings or reactive accessors.",
+            "itemSchema": {
+                "title": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Trigger label rendered inside the native <summary>"
+                },
+                "content": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Panel body revealed when the item is open"
+                },
+                "open": {
+                    "type": "boolean",
+                    "description": "Force this item open on first render"
+                }
+            }
+        },
+        {
+            "name": "mode",
+            "label": "Mode",
+            "type": "enum",
+            "enum": ["single", "multi"],
+            "default": "multi",
+            "description": "'multi' (default) lets every item open independently — pure native behavior, zero JS. 'single' closes sibling items when one opens via a progressive-enhancement toggle listener; with JS disabled it still degrades to independent multi-open."
+        },
+        {
+            "name": "defaultOpen",
+            "label": "Default open",
+            "editor": { "tab": "settings" },
+            "type": "number | number[]",
+            "description": "Which item index(es) start open. Accepts a single index or an array of indices, applied at build time via the open attribute. In 'single' mode more than one index is clamped to the first."
+        },
+        {
+            "name": "id",
+            "label": "Anchor ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Anchor id on the .ui-accordion root, useful for deep-linking."
+        }
+    ],
+    "requiredProps": [],
+    "events": [],
+    "slots": [
+        {
+            "name": "items",
+            "displayName": "Items",
+            "description": "Projected disclosure content rendered after the array-driven items. Author raw <details> blocks here to mix bespoke rows with the items array; single-open mode manages them too.",
+            "accepts": ["ui.text", "ui.heading", "ui.card"]
+        }
+    ],
+    "tokens": {
+        "item.surface": "--color-surface + --border-width-hairline --color-border + --radius-md",
+        "item.border.hover": "color-mix(in oklch, --color-primary 30%, --color-border) on hover / focus-within",
+        "trigger.padding-block": "--space-sm",
+        "trigger.padding-inline": "--space-md",
+        "trigger.font": "--font-size-md + --font-weight-semibold, --color-text",
+        "trigger.hover": "a11y.state-background(hover, --color-primary)",
+        "trigger.focus": "a11y.focus-ring on :focus-visible",
+        "chevron": "rotated border corner (--border-width-thin currentColor), flips 180deg via rotate on [open]",
+        "panel.color": "--color-text-muted",
+        "panel.padding": "--space-md inline + block-end",
+        "gap.items": "--space-sm (Close Friends — items in a list)",
+        "gap.trigger": "--space-sm (title ↔ chevron)",
+        "motion.chevron": "rotate --motion-duration-normal --motion-easing-standard (motion-safe)",
+        "motion.border": "--motion-transition-border (motion-safe)"
+    },
+    "spacing": {
+        "items-gap": "--space-sm (Close Friends — items in a list)",
+        "trigger-inline": "--space-md (comfortable tap target inset)",
+        "title-to-chevron": "--space-sm (Close Friends — label and disclosure affordance)",
+        "panel-inset": "--space-md (Friends — the answer is a distinct block under the trigger)"
+    },
+    "designGuidance": {
+        "surface": "Each item is a bordered --color-surface card with a hairline and --radius-md. The whole list reads as a stack of peers separated by --space-sm. No shadows — depth comes from the border and the open/closed affordance, not elevation.",
+        "depth": "Flat by design. The only motion is the chevron rotation and a border-color tint on hover/focus-within, both motion-safe wrapped so prefers-reduced-motion zeroes them.",
+        "borders": "Hairline --color-border at rest; on hover or focus-within the border tints toward --color-primary (30% mix) to signal interactivity. Forced-colors mode draws a 1px ButtonText border.",
+        "interactivity": "Interaction is entirely native: <summary> is a real disclosure control with built-in Tab focus, Enter/Space activation, and correct AT semantics. Do NOT add role='button' or aria-expanded — the native elements already expose the right state. The custom chevron replaces the default triangle (list-style: none + ::-webkit-details-marker hidden) purely for visual polish.",
+        "bestPractices": [
+            "Reach for 'single' mode when answers are long and only one should occupy the viewport at a time (classic FAQ); use 'multi' when users compare answers side by side.",
+            "Keep titles short and scannable — they render as the always-visible trigger.",
+            "Set defaultOpen to surface the most common question, but avoid opening several items in 'single' mode (the component clamps to the first).",
+            "For rich answers (lists, links, embedded components) project custom <details> children instead of the plain-text content prop.",
+            "Never wrap the trigger text in a heading for each item — repeated headings distort document outline; the native <summary> already conveys structure."
+        ]
+    },
+    "constraints": [
+        "Each item renders a native <details> containing a <summary> (trigger) and a .ui-accordion-panel (content) — accessible and usable with zero JavaScript",
+        "No ARIA attributes are added — native <details>/<summary> semantics are correct on their own",
+        "Single-open mode is a progressive enhancement: a toggle listener on each <details> closes open siblings; without JS the list degrades to independent multi-open",
+        "defaultOpen sets the open attribute at build time; in 'single' mode more than one index is clamped to the first",
+        "All CSS uses logical properties (inline/block) — RTL-safe",
+        "All transitions (chevron rotate, border tint) are wrapped in @include a11y.motion-safe",
+        "Forced-colors mode renders a 1px ButtonText border and ButtonText chevron",
+        "destroy() removes every toggle listener, disposes every reactive text effect, and empties the root"
+    ],
+    "a11y": {
+        "landmarks": [
+            "No landmark role — the accordion is a plain grouping of native disclosures. Wrap it in a labeled <section> (see FaqSection) when it needs a region name."
+        ],
+        "keyboard": {
+            "trigger": "Native <summary> receives Tab / Shift+Tab focus and toggles on Enter or Space — no custom key handling.",
+            "singleOpen": "Closing siblings happens on the toggle event, so keyboard-driven opens behave identically to pointer opens."
+        },
+        "focus": {
+            "visible": ":focus-visible on the <summary> paints the design-system focus ring via a11y.focus-ring."
+        },
+        "aria": {
+            "root": "<div class='ui-accordion'>",
+            "note": "Intentionally no aria-expanded / role=button — native <details>/<summary> already expose expanded/collapsed state to assistive technology."
+        },
+        "forcedColors": "forced-colors mode renders a 1px ButtonText border on each item and a ButtonText chevron so state stays visible without color.",
+        "motion": {
+            "reducedMotion": "Chevron rotation and border transition are wrapped in @include a11y.motion-safe — prefers-reduced-motion zeroes them. WCAG 2.3.3 satisfied."
+        }
+    },
+    "ai": {
+        "synonyms": [
+            "accordion",
+            "disclosure",
+            "expander",
+            "collapsible",
+            "collapse",
+            "details",
+            "expandable list",
+            "toggle list",
+            "show more"
+        ],
+        "avoid": [
+            "<div> with role='button' + aria-expanded and manual click handlers — use native <details>/<summary> via <Accordion>",
+            "Hand-rolled height animations that trap content from assistive tech — the native disclosure toggles content correctly",
+            "Wrapping each trigger in a heading — distorts the document outline"
+        ],
+        "patterns": [
+            "Basic multi-open: <Accordion items=\"items\"/>",
+            "Single-open FAQ: <Accordion mode=\"'single'\" items=\"faqs\" defaultOpen=\"0\"/>",
+            "First item open: <Accordion items=\"items\" defaultOpen=\"0\"/>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic-accordion",
+            "title": "Multi-open disclosure list",
+            "pithy": "<Accordion items=\"items\"/>",
+            "assertions": [
+                "renders a .ui-accordion root",
+                "one <details> per item",
+                "each <details> has a <summary> trigger",
+                "items open independently"
+            ]
+        },
+        {
+            "id": "single-open-accordion",
+            "title": "Single-open accordion",
+            "pithy": "<Accordion mode=\"'single'\" items=\"items\" defaultOpen=\"0\"/>",
+            "assertions": [
+                "first item starts open",
+                "opening one item closes the others"
+            ]
+        }
+    ]
+}