@cueplusplus/ui 0.13.0

package/manifest/components/app-bar.json

@@ -0,0 +1,297 @@
+{
+  "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.",
+          "control": {
+            "kind": "boolean"
+          }
+        }
+      ],
+      "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.",
+          "control": {
+            "kind": "opaque"
+          }
+        }
+      ],
+      "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\"`.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "center",
+              "end",
+              "start"
+            ]
+          }
+        },
+        {
+          "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.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "clip",
+              "scroll"
+            ]
+          }
+        },
+        {
+          "name": "previousLabel",
+          "type": "string",
+          "required": false,
+          "defaultValue": "Show earlier links",
+          "description": "Accessible name for the chevron that reveals links off the leading edge.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "nextLabel",
+          "type": "string",
+          "required": false,
+          "defaultValue": "Show later links",
+          "description": "Accessible name for the chevron that reveals links off the trailing edge.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "frameClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the frame around the `<nav>`, which is what takes the remaining width.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The links, and any separators between clusters of them.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        }
+      ],
+      "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\"`.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "strong",
+              "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.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "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.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "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.",
+          "control": {
+            "kind": "opaque"
+          }
+        }
+      ],
+      "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.",
+          "control": {
+            "kind": "string"
+          }
+        }
+      ],
+      "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."
+    }
+  ]
+}