@instruments/materia-ui 0.1.0

package/dist/data/decision-trees.js

@@ -0,0 +1,567 @@
+/**
+ * Component decision trees - the "which one do I reach for?" logic from
+ * `AGENTS.md`, converted from prose ASCII trees into validated structured data.
+ *
+ * Each {@link DecisionFamily} answers one user intent (float content over the
+ * page, show state, enter/choose a value, arrange things, load, empty/error,
+ * render a table). Its `tree` is a {@link DecisionNode}: interior nodes ask a
+ * `question` and branch; leaves name a component by its **manifest slug**
+ * (kebab-case, e.g. `alert-dialog`) so the docs site can link straight to the
+ * unit's page (`/components/<slug>` or `/compositions/<slug>`).
+ *
+ * Every leaf slug is validated against the generated docs manifest at
+ * generation time (`scripts/generate-docs-manifest.mjs`), so a component rename
+ * fails the manifest freshness test until the tree is updated - the drift gate. Family `id`s
+ * are validated against `COMPONENT_CATEGORIES`; a family renders on the shelf of
+ * its `id`, and several families may share a shelf (three feedback families
+ * live on `feedback`).
+ *
+ * This is a data-layer module: it imports nothing (the src layer matrix). The docs
+ * site imports it directly via `@instruments/materia-ui/data/decision-trees`.
+ *
+ * @module
+ */
+/**
+ * A type guard used by both the generator's validator and the renderer to tell
+ * a branching node from a terminal leaf.
+ */
+export const isDecisionLeaf = (node) => "slug" in node;
+export const DECISION_FAMILIES = [
+    // Overlays → `overlays`.
+    {
+        id: "overlays",
+        title: "Overlays",
+        intent: "I need to float content above the page",
+        tree: {
+            question: "Is it triggered by hover, or by click / programmatically?",
+            branches: [
+                {
+                    label: "Hover",
+                    next: {
+                        question: "How much content does it carry?",
+                        branches: [
+                            {
+                                label: "Just a short text label",
+                                next: { slug: "tooltip" },
+                            },
+                            {
+                                label: "Rich content (card, preview, stats)",
+                                next: { slug: "hover-card" },
+                            },
+                        ],
+                    },
+                },
+                {
+                    label: "Click / programmatic",
+                    next: {
+                        question: "How does it sit on the page?",
+                        branches: [
+                            {
+                                label: "Anchored to its trigger - dismiss on outside-click / Esc",
+                                next: {
+                                    slug: "popover",
+                                    note: "Menus → DropdownMenu; command palette → Command.",
+                                },
+                            },
+                            {
+                                label: "A centered modal that blocks the page until dismissed",
+                                next: {
+                                    question: "What kind of modal?",
+                                    branches: [
+                                        {
+                                            label: "Confirm / warn / destructive decision (Cancel + Action)",
+                                            next: { slug: "alert-dialog" },
+                                        },
+                                        {
+                                            label: "General modal (form, details, footer actions)",
+                                            next: { slug: "dialog" },
+                                        },
+                                        {
+                                            label: "Should animate out of its trigger element",
+                                            next: { slug: "morph-dialog" },
+                                        },
+                                    ],
+                                },
+                            },
+                            {
+                                label: "Slides in from an edge of the screen",
+                                next: {
+                                    question: "Which edge behaviour?",
+                                    branches: [
+                                        {
+                                            label: "Bottom sheet, gesture / drag to dismiss (mobile-ish)",
+                                            next: { slug: "drawer" },
+                                        },
+                                        {
+                                            label: "Generic edge panel with nested panels + controlled state, modal or non-modal",
+                                            next: { slug: "sidepanel" },
+                                        },
+                                        {
+                                            label: "A simpler edge overlay for a focused form / settings",
+                                            next: { slug: "sheet" },
+                                        },
+                                    ],
+                                },
+                            },
+                        ],
+                    },
+                },
+            ],
+        },
+        comparison: {
+            columns: ["Component", "Trigger", "Blocks page", "Best for"],
+            rows: [
+                [
+                    "Tooltip",
+                    "hover / focus",
+                    "no",
+                    "one-line hint on an icon / control",
+                ],
+                ["HoverCard", "hover", "no", "rich preview on hover"],
+                [
+                    "Popover",
+                    "click",
+                    "no",
+                    "anchored floating panel, dismiss on outside",
+                ],
+                [
+                    "Dialog",
+                    "click / prog",
+                    "yes",
+                    "modal form / details with header + footer",
+                ],
+                [
+                    "AlertDialog",
+                    "click / prog",
+                    "yes",
+                    "confirmations, warnings, destructive actions",
+                ],
+                [
+                    "MorphDialog",
+                    "click",
+                    "yes",
+                    "modal that morphs from its trigger (shared-layout)",
+                ],
+                [
+                    "Sheet",
+                    "click / prog",
+                    "yes",
+                    "edge panel for a focused form / settings",
+                ],
+                [
+                    "Drawer",
+                    "click / prog",
+                    "yes",
+                    "bottom sheet with gesture / drag dismissal",
+                ],
+                [
+                    "Sidepanel",
+                    "click / prog",
+                    "either",
+                    "side panel with nesting + modal / non-modal modes",
+                ],
+            ],
+        },
+        tieBreakers: [
+            "Destructive confirmations should always be an AlertDialog with a destructive action - never a plain Dialog.",
+        ],
+    },
+    // Status & feedback → `feedback`.
+    {
+        id: "feedback",
+        title: "Status & feedback",
+        intent: "I need to show state, a label, or a message",
+        tree: {
+            question: "Is it a transient notification (appears, then auto-dismisses)?",
+            branches: [
+                {
+                    label: "Yes - transient",
+                    next: { slug: "toast", note: "Toast notifications." },
+                },
+                {
+                    label: "No - persistent and inline",
+                    next: {
+                        question: "What is it, exactly?",
+                        branches: [
+                            {
+                                label: "A tiny coloured dot, no text (presence / status marker)",
+                                next: { slug: "dot" },
+                            },
+                            {
+                                label: "A short label chip",
+                                next: {
+                                    question: "Does it do anything when clicked?",
+                                    branches: [
+                                        {
+                                            label: "No - display-only metadata (status / category / count)",
+                                            next: { slug: "badge" },
+                                        },
+                                        {
+                                            label: "Yes - interactive (click, dismiss ×, select / filter)",
+                                            next: { slug: "tag" },
+                                        },
+                                    ],
+                                },
+                            },
+                            {
+                                label: "A full inline message block",
+                                next: {
+                                    slug: "alert",
+                                    note: "Default or destructive, optional icon. A richer contextual message with actions / progress / dismiss (a Banner) is in the guide but not yet a shipped unit - use Alert today.",
+                                },
+                            },
+                        ],
+                    },
+                },
+            ],
+        },
+        comparison: {
+            columns: ["Component", "Text?", "Interactive", "Use for"],
+            rows: [
+                ["Dot", "no", "no", "status / presence marker"],
+                ["Badge", "short", "no", "display-only status / category / count"],
+                [
+                    "Tag",
+                    "short",
+                    "yes",
+                    "selectable / removable / filter chip (dismiss, click)",
+                ],
+                [
+                    "Pill",
+                    "-",
+                    "-",
+                    "internal primitive behind Badge / Tag - don't use directly",
+                ],
+                [
+                    "Alert",
+                    "block",
+                    "no",
+                    "inline important notice (default / destructive)",
+                ],
+                [
+                    "Banner",
+                    "block",
+                    "optional",
+                    "contextual message with actions / progress / dismiss",
+                ],
+                ["Sonner", "block", "-", "transient toast notifications"],
+            ],
+        },
+        tieBreakers: [
+            "Badge vs Tag: if the chip does nothing when clicked, it's a Badge. The moment it needs a dismiss ×, a click handler, or selection state, it's a Tag.",
+            "Pill is the internal primitive behind Badge and Tag - never reach for it directly.",
+            "Banner is documented above but is not yet a shipped unit; use Alert for an inline notice until it lands.",
+        ],
+    },
+    // Inputs & selection → `forms`.
+    {
+        id: "forms",
+        title: "Inputs & selection",
+        intent: "I need the user to enter or choose something",
+        tree: {
+            question: "Free-text entry, or choosing from options?",
+            branches: [
+                {
+                    label: "Free-text entry",
+                    next: {
+                        question: "What surrounds the field?",
+                        branches: [
+                            {
+                                label: "A plain single value",
+                                next: { slug: "input" },
+                            },
+                            {
+                                label: "Addons / icons / buttons wrap it (currency, prefix / suffix, inline button)",
+                                next: { slug: "input-group" },
+                            },
+                            {
+                                label: "A search field (icon + clear button + shortcut)",
+                                next: { slug: "search-input" },
+                            },
+                        ],
+                    },
+                },
+                {
+                    label: "Choosing from options",
+                    next: {
+                        question: "What kind of chooser?",
+                        branches: [
+                            {
+                                label: "Type-to-filter, large or async lists, virtualized",
+                                next: { slug: "combobox" },
+                            },
+                            {
+                                label: "Styled dropdown (groups, separators, icons)",
+                                next: { slug: "select" },
+                            },
+                            {
+                                label: "The real native <select> (mobile, minimal)",
+                                next: { slug: "native-select" },
+                            },
+                            {
+                                label: "2–5 mutually exclusive options, all visible (mode / view switcher)",
+                                next: {
+                                    slug: "segmented-control",
+                                    note: "Content panels → Tabs; URL navigation → TabNavigation; multi-select or deselectable chips → ToggleGroup.",
+                                },
+                            },
+                        ],
+                    },
+                },
+            ],
+        },
+        comparison: {
+            columns: ["Component", "Kind", "Reach for it when"],
+            rows: [
+                ["Input", "text", "a plain single-line value"],
+                ["InputGroup", "text", "addons / icons / buttons wrap the field"],
+                ["SearchInput", "text", "search with icon + clear + shortcut"],
+                ["Combobox", "choice", "searchable / filterable, big or async lists"],
+                ["Select", "choice", "styled dropdown, grouped options"],
+                ["NativeSelect", "choice", "native select semantics / simplest case"],
+                [
+                    "SegmentedControl",
+                    "choice",
+                    "always-one-selected visible mode switcher",
+                ],
+            ],
+        },
+        tieBreakers: [
+            "For discrete controls reach for Checkbox / Radio / RadioGroup / Switch / Toggle / Slider / SegmentedControl instead.",
+            "Wrap any labelled control in Field to wire up its label, description and error.",
+        ],
+    },
+    // Layout → `layout`.
+    {
+        id: "layout",
+        title: "Layout",
+        intent: "I need to arrange things",
+        tree: {
+            question: "One dimension, two dimensions, or something else?",
+            branches: [
+                {
+                    label: "One dimension (a row or a column)",
+                    next: {
+                        question: "How much control do you need?",
+                        branches: [
+                            {
+                                label: "A stack with a gap (usually vertical)",
+                                next: { slug: "stack" },
+                            },
+                            {
+                                label: "Full flexbox control (direction / justify / align)",
+                                next: { slug: "flex" },
+                            },
+                            {
+                                label: "A horizontal cluster (buttons, chips) that wraps",
+                                next: { slug: "group" },
+                            },
+                        ],
+                    },
+                },
+                {
+                    label: "Two dimensions (a grid)",
+                    next: {
+                        question: "How much grid control?",
+                        branches: [
+                            {
+                                label: "Equal-width columns, responsive count",
+                                next: { slug: "simple-grid" },
+                            },
+                            {
+                                label: "Full grid control (spans, start, order)",
+                                next: { slug: "grid" },
+                            },
+                        ],
+                    },
+                },
+                {
+                    label: "Centering one thing",
+                    next: { slug: "center" },
+                },
+                {
+                    label: "Lock a child to a fixed width:height ratio",
+                    next: { slug: "aspect-ratio" },
+                },
+                {
+                    label: "User-draggable split panels",
+                    next: { slug: "resizable" },
+                },
+                {
+                    label: "A zero-opinion wrapper (would otherwise be a naked <div>)",
+                    next: { slug: "box" },
+                },
+                {
+                    label: "A spacer between things",
+                    next: { slug: "space" },
+                },
+                {
+                    label: "A page-level width + horizontal-padding wrapper",
+                    next: { slug: "container" },
+                },
+                {
+                    label: "A page vertical-rhythm section",
+                    next: { slug: "section" },
+                },
+                {
+                    label: "A whole-page frame (sidebar / header / scroll regions)",
+                    next: {
+                        slug: "sidebar",
+                        note: "The page frame itself - full-page arrangements (sidebar shell, fixed-height dashboard, auth split, minimal) are curated as recipes; see Templates.",
+                    },
+                },
+            ],
+        },
+        comparison: {
+            columns: ["Component", "Axis", "Use for"],
+            rows: [
+                [
+                    "Box",
+                    "-",
+                    "zero-opinion wrapper - the sanctioned naked-element escape hatch",
+                ],
+                ["Flex", "1D", "explicit flexbox (direction / justify / align / wrap)"],
+                ["Stack", "1D", "gapped stack (HStack / VStack variants)"],
+                ["Group", "1D", "horizontal cluster with wrap / position"],
+                ["Center", "-", "center a single child"],
+                ["Grid", "2D", "full grid (spans, start, order)"],
+                ["SimpleGrid", "2D", "equal columns, responsive cols"],
+                ["Container", "page", "max-width + inset wrapper"],
+                ["Section", "page", "vertical page rhythm"],
+            ],
+        },
+        tieBreakers: [
+            'All layout primitives take responsive props (gap={{ base, md, … }}) and are RSC-safe - no "use client".',
+            "Box vs Container: Container injects mx-auto + a max-width + the page gutter; Box is the neutral one (zero classes of its own).",
+        ],
+    },
+    // Loading & async → `feedback` (Skeleton / Spinner / LoadingState are all
+    // @category feedback; this family shares the feedback shelf).
+    {
+        id: "feedback",
+        title: "Loading & async",
+        intent: "I need to show a loading or async state",
+        tree: {
+            question: "What are you loading?",
+            branches: [
+                {
+                    label: "Blocking a whole region / page while it loads",
+                    next: { slug: "loading-state" },
+                },
+                {
+                    label: "An in-place placeholder that mirrors the final layout",
+                    next: {
+                        question: "What shape is the placeholder?",
+                        branches: [
+                            {
+                                label: "A generic block",
+                                next: { slug: "skeleton" },
+                            },
+                            {
+                                label: "Lines of text",
+                                next: {
+                                    slug: "skeleton",
+                                    note: "SkeletonText doesn't exist yet - use Skeleton.",
+                                },
+                            },
+                            {
+                                label: "A row with an avatar / tile + lines",
+                                next: {
+                                    slug: "skeleton",
+                                    note: "SkeletonRow doesn't exist yet - use Skeleton.",
+                                },
+                            },
+                        ],
+                    },
+                },
+                {
+                    label: "A small inline spinner (button, inline action)",
+                    next: { slug: "spinner" },
+                },
+            ],
+        },
+        tieBreakers: [
+            "Prefer Skeleton (a layout-stable placeholder) over a spinner for content areas.",
+            "Reserve LoadingState for genuinely blocking, full-region loads; reserve Spinner for small inline / action loading.",
+        ],
+    },
+    // Empty & error → `feedback` (Empty and ErrorState are both @category
+    // feedback; this family shares the feedback shelf).
+    {
+        id: "feedback",
+        title: "Empty & error",
+        intent: "I need to show an empty or error state",
+        tree: {
+            question: "What's the situation?",
+            branches: [
+                {
+                    label: "No data / nothing to show",
+                    next: {
+                        slug: "empty",
+                        note: "Pair with EmptyActions for a call-to-action.",
+                    },
+                },
+                {
+                    label: "Something failed and the user can retry",
+                    next: { slug: "error-state" },
+                },
+                {
+                    label: "A full-page error boundary",
+                    next: { slug: "error-state" },
+                },
+            ],
+        },
+        comparison: {
+            columns: ["Situation", "Component"],
+            rows: [
+                ["No data / nothing to show", "Empty (with EmptyActions)"],
+                ["Something failed + retry", "ErrorState - composes Empty"],
+                ["Full-page error boundary", "ErrorState / boundary"],
+            ],
+        },
+        tieBreakers: [
+            "ErrorState composes Empty, so don't hand-roll a retry Empty for failures.",
+        ],
+    },
+    // Tabular data → `data`.
+    {
+        id: "data",
+        title: "Tabular data",
+        intent: "I need to render a table",
+        tree: {
+            question: "Do you need sorting / filtering / column visibility / pagination / row selection?",
+            branches: [
+                {
+                    label: "Yes",
+                    next: {
+                        slug: "data-grid",
+                        note: "Headless, @tanstack/react-table; the DataGrid* parts frame it.",
+                    },
+                },
+                {
+                    label: "No",
+                    next: {
+                        slug: "table",
+                        note: "Semantic Table / TableHeader / TableRow / TableCell primitives.",
+                    },
+                },
+            ],
+        },
+        comparison: {
+            columns: ["Component", "Use for"],
+            rows: [
+                [
+                    "Table",
+                    "static / semantic tables - full control, no data-grid machinery",
+                ],
+                [
+                    "DataGrid",
+                    "interactive grids: sort, filter, paginate, select, column config",
+                ],
+            ],
+        },
+        tieBreakers: [
+            "Reach for DataGrid only when you need its machinery - a static Table is lighter and gives you full markup control.",
+        ],
+    },
+];

package/dist/data/docs-manifest.d.ts

@@ -0,0 +1,76 @@
+export interface DocsPropEntry {
+    name: string;
+    type: string;
+    required: boolean;
+    defaultValue?: string;
+    description?: string;
+    typeTruncated?: boolean;
+}
+export interface DocsExportEntry {
+    name: string;
+    kind: string;
+    props: DocsPropEntry[];
+}
+export interface DocsAnatomyNode {
+    slot: string;
+    label: string;
+    description?: string;
+    children?: DocsAnatomyNode[];
+}
+export interface DocsComponentEntry {
+    slug: string;
+    module: string;
+    title: string;
+    /** A data/component-categories family: COMPONENT_CATEGORIES for components, COMPOSITION_CATEGORIES for compositions (validated at generation). */
+    category: string;
+    description: string;
+    exports: DocsExportEntry[];
+    bestPractices: string[];
+    /** Same-layer component/composition slugs this unit's implementation imports. */
+    uses: string[];
+    /** Same-layer component/composition slugs that import this unit. */
+    usedBy: string[];
+    /** Compound-component slot tree, when the unit ships a *-anatomy.ts. */
+    anatomy?: DocsAnatomyNode;
+}
+export interface DoctrineGate {
+    path: string;
+    doctrine: string | null;
+}
+export interface DoctrineRule {
+    id: string;
+    name: string;
+    statement: string;
+    gates: DoctrineGate[];
+    messages?: string[];
+    layers?: readonly string[];
+    matrix?: Record<string, readonly string[]>;
+}
+export interface DocsRestrictedImport {
+    groups: string[];
+    message: string;
+}
+export interface DocsReplacement {
+    tag: string;
+    guidance: string;
+}
+export interface DocsDoctrine {
+    rules: DoctrineRule[];
+    restrictedImports: DocsRestrictedImport[];
+    replacements: DocsReplacement[];
+}
+export interface DocsStorybookInventory {
+    addons: string[];
+    anatomyFiles: number;
+    storyFiles: number;
+    storiesWithPlay: number;
+}
+export interface DocsManifest {
+    components: DocsComponentEntry[];
+    compositions: DocsComponentEntry[];
+    doctrine: DocsDoctrine;
+    storybook: DocsStorybookInventory;
+}
+/** The slug of every documented component and composition. */
+export type DocsUnitSlug = "accordion" | "alert" | "alert-dialog" | "anchor" | "animated-number" | "aspect-ratio" | "attribute-card" | "avatar" | "badge" | "border-beam" | "box" | "breadcrumb" | "button" | "button-group" | "calendar" | "card" | "card-grid" | "carousel" | "center" | "chart" | "checkbox" | "checkbox-card" | "checkbox-field" | "code" | "collapsible" | "color-palette" | "color-wheel" | "combobox" | "command" | "container" | "context-menu" | "cookie-banner" | "country-combobox" | "country-select" | "data-grid" | "data-grid-column-filter" | "data-grid-column-header" | "data-grid-column-visibility" | "data-grid-pagination" | "data-grid-table" | "delivery-banner" | "description-list" | "dialog" | "document-list" | "dot" | "dot-matrix-loader" | "drawer" | "dropdown-menu" | "easing-curve" | "editorial-card" | "empty" | "empty-state" | "error-boundary" | "error-state" | "expand-button" | "expandable-text" | "fade-overlay" | "field" | "file-upload" | "flex" | "folder-tile" | "gallery" | "grid" | "group" | "heading" | "hotspot-indicator" | "hover-card" | "icon" | "icon-box" | "icon-card" | "icon-morph" | "identified-surface" | "input" | "input-card" | "input-group" | "input-otp" | "item" | "kbd" | "label" | "loading-state" | "location-input" | "logo" | "marquee-text" | "media-frame" | "mega-menu" | "menu-item" | "menubar" | "mobile-navigation" | "month-year-picker" | "morph-dialog" | "motion-config" | "native-select" | "navigation-menu" | "page-header" | "page-toolbar" | "pagination" | "phone-input" | "pill" | "pixel-loader" | "popover" | "product-card" | "product-specifications-selector" | "progress" | "progress-dots" | "prompt-panel" | "quantity-control" | "quick-view" | "radio" | "radio-card" | "radio-group" | "requirement-item" | "resizable" | "scrim" | "scroll-area" | "scroll-fade" | "scroll-frame" | "search-input" | "section" | "section-header" | "segmented" | "segmented-control" | "select" | "separator" | "settings-card" | "sheet" | "shimmer" | "shine" | "sidebar" | "sidepanel" | "simple-grid" | "site-footer" | "skeleton" | "slider" | "social-icon" | "space" | "spinner" | "stack" | "stagger" | "stepper" | "streaming-text" | "sub-navigation" | "success-tick-ripple" | "swatch" | "swatch-fan" | "swatch-group" | "swatch-selector" | "switch" | "tab-navigation" | "table" | "tabs" | "tag" | "tag-selector" | "text" | "textarea" | "thinking-loader" | "thinking-orb" | "thinking-trace" | "time-slot-picker" | "toast" | "toggle" | "toggle-group" | "tooltip" | "variant-selector" | "verge" | "visually-hidden" | "voice";
+export declare const docsManifest: DocsManifest;