@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/alert-dialog.json

@@ -0,0 +1,190 @@
+{
+  "name": "AlertDialog",
+  "slug": "alert-dialog",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A modal that asks one question with two answers, for anything irreversible.\n\nWraps Base UI's `AlertDialog`: the popup takes `role=\"alertdialog\"`, focus is\ntrapped and restored, and — unlike {@link Dialog } — an outside press does not\ndismiss it. Everything else (scrim, surface, portal theme stamping) is shared\nwith the rest of the overlay family.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Trigger",
+    "Content",
+    "Title",
+    "Description",
+    "Footer",
+    "Cancel",
+    "Action"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "AlertDialog.Root",
+      "description": "Groups the parts of an alert dialog and owns its open state. Renders no\nelement.",
+      "props": [],
+      "typeReferences": [
+        "BaseAlertDialog.Root.Props"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "AlertDialog.Trigger",
+      "description": "The control that raises the alert. Unstyled — pass\n`render={<Button variant=\"danger-outline\" />}`.",
+      "props": [],
+      "typeReferences": [
+        "BaseAlertDialog.Trigger.Props"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "AlertDialog.Content",
+      "description": "The alert's portal, scrim and popup.\n\nThere is no corner close affordance, and Base UI does not dismiss an alert on\nan outside press: the whole point of the component is that the user answers\nthe question. Provide exactly one {@link AlertDialogCancel} and one\n{@link AlertDialogAction}.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the popup surface."
+        },
+        {
+          "name": "width",
+          "type": "\"sm\" | \"md\" | \"lg\"",
+          "required": false,
+          "defaultValue": "sm",
+          "description": ""
+        },
+        {
+          "name": "keepMounted",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Keep the popup mounted while closed."
+        },
+        {
+          "name": "backdropClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the scrim behind it."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseAlertDialog.Popup.Props, \"className\">",
+        "VariantProps<typeof alertDialogPopupVariants>"
+      ]
+    },
+    {
+      "name": "Title",
+      "usage": "AlertDialog.Title",
+      "description": "The question being asked. Wired to the popup's `aria-labelledby`.",
+      "props": [],
+      "typeReferences": [
+        "BaseAlertDialog.Title.Props"
+      ]
+    },
+    {
+      "name": "Description",
+      "usage": "AlertDialog.Description",
+      "description": "What the consequences are. Wired to the popup's `aria-describedby`.",
+      "props": [],
+      "typeReferences": [
+        "BaseAlertDialog.Description.Props"
+      ]
+    },
+    {
+      "name": "Footer",
+      "usage": "AlertDialog.Footer",
+      "description": "The two-answer action strip.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Cancel",
+      "usage": "AlertDialog.Cancel",
+      "description": "The safe answer. Styled as a secondary button, because backing out must never\nbe the loudest thing on the surface.",
+      "props": [],
+      "typeReferences": [
+        "BaseAlertDialog.Close.Props"
+      ]
+    },
+    {
+      "name": "Action",
+      "usage": "AlertDialog.Action",
+      "description": "The answer that does the thing. Closes the alert on press, so hang the work\noff `onClick`.",
+      "props": [
+        {
+          "name": "tone",
+          "type": "\"accent\" | \"danger\"",
+          "required": false,
+          "defaultValue": "accent",
+          "description": "Which answer this is. `\"danger\"` for anything destructive, `\"accent\"` for a\nconfirmation that merely proceeds. Defaults to `\"accent\"`."
+        }
+      ],
+      "typeReferences": [
+        "BaseAlertDialog.Close.Props"
+      ]
+    }
+  ],
+  "variants": {
+    "width": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "defaultVariants": {
+    "width": "sm"
+  },
+  "tokensUsed": [
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-6",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A modal that asks one question with two answers, for anything irreversible.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<AlertDialog.Root>\n  <AlertDialog.Trigger render={<Button variant=\"danger-outline\">Delete</Button>} />\n  <AlertDialog.Content>\n    <AlertDialog.Title>Delete universe 3?</AlertDialog.Title>\n    <AlertDialog.Description>Every patched fixture goes with it.</AlertDialog.Description>\n    <AlertDialog.Footer>\n      <AlertDialog.Cancel>Keep</AlertDialog.Cancel>\n      <AlertDialog.Action tone=\"danger\" onClick={remove}>Delete</AlertDialog.Action>\n    </AlertDialog.Footer>\n  </AlertDialog.Content>\n</AlertDialog.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/alert-dialog",
+  "mdUrl": "/docs/components/alert-dialog.md",
+  "jsonUrl": "/r/components/alert-dialog.json",
+  "specimens": [
+    {
+      "title": "AlertDialog",
+      "group": "overlays",
+      "components": [
+        "AlertDialog"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"danger\">\n    <AlertDialog.Root>\n      <AlertDialog.Trigger render={<Button variant=\"danger\">{COPY.destructive.action}</Button>} />\n      <AlertDialog.Content>\n        <AlertDialog.Title>{COPY.destructive.title}</AlertDialog.Title>\n        <AlertDialog.Description>{COPY.destructive.hint}</AlertDialog.Description>\n        <AlertDialog.Footer>\n          <AlertDialog.Cancel render={<Button>Keep it</Button>} />\n          <AlertDialog.Action tone=\"danger\">{COPY.destructive.action}</AlertDialog.Action>\n        </AlertDialog.Footer>\n      </AlertDialog.Content>\n    </AlertDialog.Root>\n  </Specimen>\n  <Specimen label=\"accent\">\n    <AlertDialog.Root>\n      <AlertDialog.Trigger render={<Button>Reload show</Button>} />\n      <AlertDialog.Content width=\"sm\">\n        <AlertDialog.Title>Reload the show file</AlertDialog.Title>\n        <AlertDialog.Description>\n          Unsaved edits to 3 cues are discarded.\n        </AlertDialog.Description>\n        <AlertDialog.Footer>\n          <AlertDialog.Cancel render={<Button>Cancel</Button>} />\n          <AlertDialog.Action>Reload</AlertDialog.Action>\n        </AlertDialog.Footer>\n      </AlertDialog.Content>\n    </AlertDialog.Root>\n  </Specimen>\n</Specimens>",
+      "note": "The destructive twin: no scrim dismissal, no close button, and an explicit pair of Cancel and Action.",
+      "interaction": "Escape is deliberately not enough on its own; the action has to be chosen."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/app-bar.json

@@ -0,0 +1,244 @@
+{
+  "name": "AppBar",
+  "slug": "app-bar",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The horizontal bar a site or an application wears across the top: brand slot,\nnavigation slot, actions slot, one chrome rung tall.\n\n`AppShell` is the frame for a screen that owns the viewport; this is the bar\nfor a document that scrolls — a marketing page, a documentation site, a\nconsole's public half. `NavigationMenu` is neither: it is the *menu* that\ngoes inside `AppBar.Nav` when a section has children.\n\nSix parts. `Root` is the `<header>`, `Brand` the leading link, `Nav` the\n`<nav>` landmark that takes the remaining width and scrolls when the links\noutgrow it, `Link` one destination in one of two registers, `Separator` the\nseam between clusters, and `Actions` the trailing controls.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Brand",
+    "Nav",
+    "Link",
+    "Separator",
+    "Actions"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "AppBar.Root",
+      "description": "The bar across the top of a document: brand, navigation, actions.\n\nOne rung of the chrome ladder tall, from `--cue-chrome-toolbar` — the same\ntoken `Toolbar` and the docs site's hand-rolled header use, so a page that\nstacks a bar on a toolbar gets two equal strips rather than two guesses.\n\nSticky by default, and translucent because of it: a bar pinned over scrolling\ncontent needs a ground, and `bg-surface-1/95` plus `backdrop-blur` says\n\"there is content under this\" where an opaque fill would claim the content\nends here. `z-40` is above the page and below the `z-50` this library's\noverlays float at, so a menu opened from the bar is never behind it.\n\n**This is a bar, not a menu.** `NavigationMenu` is the mega-menu — triggers\nthat open panels — and it goes *inside* an `AppBar.Nav` when a section has\nchildren. This component is the strip it sits in.\n\nStatic markup — no `\"use client\"` on this module, deliberately: a site header\nis where a framework reads its data, so the bar has to be renderable from a\nserver component. The one part with state is the navigation's scroller, and\nthe client boundary is drawn around that alone (`_edge-scroller.tsx`).\n\nIt adds **no viewport breakpoint**. `AppShell` holds the library's only one,\nfor navigation shape, and a horizontal bar does not need it: the brand and\nthe actions are `shrink-0`, the navigation between them takes the remaining\nwidth and scrolls inside it, so a 390px viewport gets the same bar with a\nshorter window onto the same links rather than a second layout to maintain.",
+      "props": [
+        {
+          "name": "sticky",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Keep the bar at the top of the viewport as the page scrolls. Defaults to\n`true`.\n\nSet it `false` inside `AppShell`, where nothing scrolls the document and a\nsticky bar would be solving a problem the shell has already solved."
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"header\">"
+      ]
+    },
+    {
+      "name": "Brand",
+      "usage": "AppBar.Brand",
+      "description": "The leading slot, and the way home.\n\nA link rather than a box, because that is what a brand in a bar is: pass\n`href`, or `render={<NextLink href=\"/\" />}` to go through a router. It sets\nthe bar's own type register (mono, UI size, full-contrast ink) so a wordmark\nand a version chip sit on one baseline without a class of their own.\n\n`shrink-0`: the brand is the one thing in the bar that must never be\ncompressed, because a half-drawn wordmark reads as a broken page.",
+      "props": [
+        {
+          "name": "render",
+          "type": "RenderProp<Record<string, unknown>>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Replace the rendered element (Base UI render prop). Accepts an element —\n`render={<NextLink href=\"/x\" />}` — or a function returning one. This is\nhow the design system composes with a router without depending on one."
+        }
+      ],
+      "typeReferences": [
+        "Omit<LinkProps, \"variant\" | \"external\">"
+      ]
+    },
+    {
+      "name": "Nav",
+      "usage": "AppBar.Nav",
+      "description": "The `<nav>` landmark between the brand and the actions, and the one part of\nthe bar that gives up width.\n\nName it: `aria-label=\"Sections\"`, or whatever this bar's links are. A\ndocument with more than one navigation and no names on them is a screen\nreader listing \"navigation, navigation\".\n\nThe alignment sits on the frame rather than on the scrolling `<nav>` itself,\nand that is load-bearing: `justify-content: flex-end` on a scroll container\npushes the overflow off the *start* edge, where several browsers cannot\nscroll to reach it. Aligning the frame and letting the nav grow from its\nstart keeps every link reachable at every width.",
+      "props": [
+        {
+          "name": "align",
+          "type": "\"center\" | \"end\" | \"start\"",
+          "required": false,
+          "defaultValue": "end",
+          "description": "Where the links sit when they are narrower than the space. Defaults to `\"end\"`."
+        },
+        {
+          "name": "overflow",
+          "type": "\"clip\" | \"scroll\"",
+          "required": false,
+          "defaultValue": "scroll",
+          "description": "What the navigation does when the links do not fit. Defaults to `\"scroll\"`.\n\nThe same behaviour `Toolbar` and `SegmentedControl` have, from the same\nmodule: the links scroll inside the bar, the overflowing edge is faded and\na pager chevron appears there. This is what lets the bar survive a phone\nwithout a viewport breakpoint."
+        },
+        {
+          "name": "previousLabel",
+          "type": "string",
+          "required": false,
+          "defaultValue": "Show earlier links",
+          "description": "Accessible name for the chevron that reveals links off the leading edge."
+        },
+        {
+          "name": "nextLabel",
+          "type": "string",
+          "required": false,
+          "defaultValue": "Show later links",
+          "description": "Accessible name for the chevron that reveals links off the trailing edge."
+        },
+        {
+          "name": "frameClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the frame around the `<nav>`, which is what takes the remaining width."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The links, and any separators between clusters of them."
+        }
+      ],
+      "typeReferences": [
+        "Omit<React.ComponentPropsWithoutRef<\"nav\">, \"children\">"
+      ]
+    },
+    {
+      "name": "Link",
+      "usage": "AppBar.Link",
+      "description": "One destination in the bar.\n\nA `Link`, so `render={<NextLink href=\"/x\" />}` composes it with a router and\n`external` gives an outbound link its `↗`, plus the bar's type register and\nthe `shrink-0` that keeps a label from being squeezed into an ellipsis while\nthe navigation around it scrolls.",
+      "props": [
+        {
+          "name": "register",
+          "type": "\"strong\" | \"muted\"",
+          "required": false,
+          "defaultValue": "muted",
+          "description": "Which register the link is set in. Defaults to `\"muted\"`."
+        },
+        {
+          "name": "active",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "This is the page the reader is on.\n\nInks the link with the accent and sets `aria-current=\"page\"` — the same\nbargain `Sidebar.Item` makes, so the current destination is announced and\nnot merely coloured. Overrides `register`: a current page is never\nfurniture."
+        },
+        {
+          "name": "external",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Open in a new tab, mark the anchor `rel=\"noreferrer noopener\"` and append a\n`↗`. The glyph is not decoration: a link that replaces the user's context\nwithout warning is a WCAG 3.2.5 failure, and the arrow is the warning."
+        },
+        {
+          "name": "render",
+          "type": "RenderProp<Record<string, unknown>>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Replace the rendered element (Base UI render prop). Accepts an element —\n`render={<NextLink href=\"/x\" />}` — or a function returning one. This is\nhow the design system composes with a router without depending on one."
+        }
+      ],
+      "typeReferences": [
+        "LinkProps"
+      ]
+    },
+    {
+      "name": "Separator",
+      "usage": "AppBar.Separator",
+      "description": "The hairline that splits one cluster of links from the next.\n\nSized from the space ladder rather than stretched to the bar's full height: a\nrule from rim to rim would cut the bar in two, and this is a seam inside one\nlist.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes, merged over the hairline defaults."
+        }
+      ],
+      "typeReferences": [
+        "Omit<SeparatorProps, \"orientation\">"
+      ]
+    },
+    {
+      "name": "Actions",
+      "usage": "AppBar.Actions",
+      "description": "The trailing slot: the controls that belong to the whole product rather than\nto a page — a theme picker, an account menu, a status chip.\n\n`shrink-0`, and spaced on the bar's own rhythm rather than a tighter one, so\na cluster of actions reads as part of the bar instead of as a widget bolted\nto the end of it.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-chrome-toolbar",
+    "--cue-edge-fade",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-surface-1",
+    "--cue-text-ui"
+  ],
+  "summary": "The horizontal bar across the top of a document: brand slot, navigation slot, actions slot, one chrome rung tall.",
+  "examples": [
+    {
+      "title": "The three slots",
+      "code": "<AppBar.Root>\n  <AppBar.Brand render={<NextLink href=\"/\" />}>\n    <Eyebrow>@cueplusplus/ui</Eyebrow>\n    <Chip tone=\"accent\" variant=\"outline\">{version}</Chip>\n  </AppBar.Brand>\n\n  <AppBar.Nav aria-label=\"Sections\">\n    <AppBar.Link render={<NextLink href=\"/docs\" />}>Getting started</AppBar.Link>\n    <AppBar.Link render={<NextLink href=\"/docs/theming\" />}>Theming</AppBar.Link>\n\n    <AppBar.Separator />\n\n    <AppBar.Link render={<NextLink href=\"/kitchen-sink\" />} register=\"strong\">Kitchen sink</AppBar.Link>\n    <AppBar.Link external render={<a href=\"https://skills.cueplusplus.com\" />}>Skills</AppBar.Link>\n  </AppBar.Nav>\n\n  <AppBar.Actions>\n    <AppBar.Separator />\n    <ThemePicker />\n  </AppBar.Actions>\n</AppBar.Root>",
+      "language": "tsx"
+    },
+    {
+      "title": "It renders on the server",
+      "code": "// A server component. `manifest()` reads the build's own JSON.\nexport function SiteHeader() {\n  const { version } = manifest();\n  return <AppBar.Root>…</AppBar.Root>;\n}",
+      "language": "tsx"
+    },
+    {
+      "title": "Inside a shell",
+      "code": "<AppShell.Root>\n  <AppBar.Root sticky={false}>…</AppBar.Root>\n  <AppShell.Body>…</AppShell.Body>\n</AppShell.Root>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<AppBar.Root>\n  <AppBar.Brand render={<NextLink href=\"/\" />}>\n    <Eyebrow>@cueplusplus/ui</Eyebrow>\n  </AppBar.Brand>\n  <AppBar.Nav aria-label=\"Sections\">\n    <AppBar.Link render={<NextLink href=\"/docs\" />}>Docs</AppBar.Link>\n    <AppBar.Link render={<NextLink href=\"/theming\" />}>Theming</AppBar.Link>\n    <AppBar.Separator />\n    <AppBar.Link render={<NextLink href=\"/gallery\" />} register=\"strong\">Gallery</AppBar.Link>\n    <AppBar.Link external render={<a href=\"https://skills.cueplusplus.com\" />}>Skills</AppBar.Link>\n  </AppBar.Nav>\n  <AppBar.Separator />\n  <AppBar.Actions><ThemePicker /></AppBar.Actions>\n</AppBar.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/app-bar",
+  "mdUrl": "/docs/components/app-bar.md",
+  "jsonUrl": "/r/components/app-bar.json",
+  "whenToUse": [
+    "Any document that scrolls and needs a persistent identity and a way around: a marketing site, a documentation site, a console's signed-out half.",
+    "Whenever a header is currently a hand-rolled `<header>` with a sticky rule, a chrome height and three flex clusters. That is this component, and it is where it came from.",
+    "Above an `AppShell`, with `sticky={false}`, when a product wants one product-wide bar over a console frame that already owns the viewport."
+  ],
+  "whenNotToUse": [
+    "As the title bar of an application window. That is `TitleBar` — window furniture with a centred document name and a drag region, not a navigation bar.",
+    "As the mega-menu itself. `NavigationMenu` is the menu; it goes *inside* `AppBar.Nav` when a section has children.",
+    "As a strip of tools for the view below it. That is `Toolbar`, which is a roving-focus ARIA toolbar rather than a `<nav>`."
+  ],
+  "commonMistakes": [
+    "Leaving `AppBar.Nav` unnamed. A page with a bar and a sidebar then has two navigations a screen reader can only call \"navigation\"; give each an `aria-label`.",
+    "Setting every link `register=\"strong\"`. Two registers only work as a contrast — a bar in which everything is loud is a bar in which nothing is.",
+    "Using `register=\"strong\"` for the current page. `active` is that: it inks the link with the accent *and* sets `aria-current=\"page\"`, so the current destination is announced rather than merely coloured.",
+    "Reaching for a viewport breakpoint to make the bar fit a phone. It already does — the navigation scrolls. `AppShell` holds the library's only breakpoint, and it is for navigation shape.",
+    "Putting the actions inside `AppBar.Nav`. A theme picker is not a destination, and it lands in the navigation landmark's list if you do."
+  ],
+  "specimens": [
+    {
+      "title": "AppBar",
+      "group": "chrome",
+      "components": [
+        "AppBar"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-4)\">\n  <div className=\"overflow-hidden rounded-(--radius-surface) border border-border\">\n    <BarSample />\n  </div>\n  {/* The same component, given a phone's worth of room. `sticky` is\n   * off in both because a bench is not a page. */}\n  <div className=\"w-full max-w-[26rem] overflow-hidden rounded-(--radius-surface) border border-border\">\n    <BarSample />\n  </div>\n</div>",
+      "note": "The horizontal bar a document wears across the top: brand, a navigation that gives up the width the other two do not, and an actions cluster. Drawn twice — the same markup at full width and boxed to 26rem, because the bar has no viewport breakpoint and does not need one.",
+      "interaction": "the narrow copy scrolls: drag it, or press the chevron that appears at whichever edge still hides a link. Every link lifts to the accent on hover; the current page is already inked with it."
+    }
+  ]
+}