@krizaka/ui 3.7.1 → 3.9.0

package/README.md

@@ -9,7 +9,7 @@
 
 **The Krizaka front-end platform's components, shared by every product.**
 The primitives (button, badge, avatar, field, theme, countdown…) on the semantic `--kz-*` tokens, the animated marks
-of Krizaka, Orazaka, Orochia, Yazakia and Yororis, and the Krizaka motion signature — one easing, one way to enter, reveal, roll, shine
+of Krizaka, Orazaka, Orochia, Yasakia and Yororis, and the Krizaka motion signature — one easing, one way to enter, reveal, roll, shine
 and open.
 
 [![npm](https://img.shields.io/npm/v/@krizaka/ui?color=196df5&label=npm)](https://www.npmjs.com/package/@krizaka/ui)
@@ -185,7 +185,7 @@ light or a product's — is a set of tokens.
 | `@krizaka/ui/date-picker` | `DatePicker`, `DateRangePicker` (`presets`), `Calendar` — ISO dates, the locale's names through `@krizaka/intl`, `min`/`max`/`isDateDisabled`, the APG grid keyboard | client |
 | `@krizaka/ui/search-field` | `SearchField` (`onSearch` debounced, `onSubmit`, `shortcut` ⌘K, `suggestions`, `clearLabel`, `landmark`) | client |
 | `@krizaka/ui/video-player` | `VideoPlayer` (`src` or a signed-source function, `loadHls={() => import("hls.js")}` (optional peer, loaded only without native HLS), `tracks`, `playbackRates`, `preload`, `pauseWhenHidden`, `overlay` for a gate, `labels`; keyboard Space/K, J/L, arrows, M, F, C) | client |
-| `@krizaka/ui/file-upload` | `Dropzone` (`accept`, `maxSize`, `maxFiles`, refusals with reasons), `UploadList` (preview, progress, speed, pause/resume/retry/cancel), `useUploadQueue` (`upload(file, { signal, onProgress, resumed })`: Tus-ready without depending on it), `acceptsFile`, `formatBytes` | client |
+| `@krizaka/ui/file-upload` | `Dropzone` (`accept`, `maxSize`, `maxFiles`, refusals with reasons), `UploadList` (preview, progress, speed, pause/resume/retry/cancel), `useUploadQueue` (`upload(file, { signal, onProgress, resumed })`: Tus-ready without depending on it; `retries`, `backoff`, `shouldRetry` — a queue of `@krizaka/pacer`), `acceptsFile`, `formatBytes` | client |
 | `@krizaka/ui/media-capture` | `MediaCapture` (`mode` photo·video·both, `facing`, `maxDuration`, permission asked on a gesture, the file picker as the way out, `onCapture({ blob, kind, url })`) | client |
 | `@krizaka/ui/video-trimmer` | `VideoTrimmer` (`duration`, `value` [start, end], `minLength`, `step`/`largeStep`, `frames` or children, `time` + `onSeek`, `classNames` per part, `renderHandle`) | client |
 | `@krizaka/ui/audio-player` | `AudioPlayer` (a seekable waveform: `peaks` or `computePeaks`, `bars`, `playbackRates`, `duration`), `resamplePeaks`, `computeAudioPeaks` | client |
@@ -198,11 +198,13 @@ light or a product's — is a set of tokens.
 | `@krizaka/ui/argument-card` | `ArgumentCard` (compact: `icon`, `title`, `meta`, `facts`, `hook` — the trap in one line —, `more`, `actions`; in a panel: `points`, `rule`, `details`, `panelLabel`) | server |
 | `@krizaka/ui/mascot-quote` | `MascotQuote` (`bird`, `mood`, `label`, the sentence as children, `variant` inline·callout, `animated`) | client |
 | `@krizaka/ui/decision-list` | `DecisionList` (`decisions`: `chose`, `refused`, `because`, `cost`; `labels`, `reveal`) | server |
-| `@krizaka/ui/code-block` | `CodeBlock` (`code`, `language`, `file`, `copyLabel`, `copiedLabel`, `highlight`), `CodeTabs` (`label`, `tabs`), `highlight` | client |
+| `@krizaka/ui/code-block` | `CodeBlock` (`code`, `language`, `file`, `lineNumbers`, `annotations` — highlight · added · removed · focus · dim · error · warning —, `copyLabel`, `copiedLabel`, `highlight`), `CodeTabs` (`label`, `tabs`), `highlight`, `normalizeCodeLanguage` — on TanStack Highlight (TS, TSX, JS, JSON, YAML, Bash, HTML, CSS, Java, Kotlin, diff) | client |
+| `@krizaka/ui/markdown` | `Markdown` (the source as children; `streaming`, `headingIds`, `codeLabels`, `linkAs`), `parseSource`, `healStreaming` — TanStack Markdown on the tokens, raw HTML never rendered; `@krizaka/ui/native/markdown`: the same AST in `Text` and `View` (`onLinkPress`) | server |
+| `@krizaka/ui/recipes` | `defineRecipe` (the variants of a component as classes of the tokens: `tv(recipe)` on the web), `nativeRecipe(recipe).resolve(props, theme)` (the phone's styles from the same classes), `ROLES`, `withAlpha` | server |
 | `@krizaka/ui/action-bar` | `ActionBar` (`actions`: `href`, `label`, `icon`; `variant` buttons·icons — the words in a CSS tooltip —, `primaryFirst`, `size`, `label`, `linkAs`) | server |
 | `@krizaka/ui/cta-panel` | `CtaPanel` (`id`, `title`, `body`, the actions as children, `level`, `reveal`) | server |
 | `@krizaka/ui/toc` | `Toc` (`label`, `items`; the section being read marked), `TocLayout` (`toc`, the sections as children) | client |
-| `@krizaka/ui/app-shell` | `AppShell.Root` (`defaultCollapsed`, `collapsed` + `onCollapsedChange`) `/Sidebar` (`label`, `brand`, `footer`, `collapseLabels`, `closeLabel`; a drawer on a phone) `/Group/Item` (`icon`, `label`, `current`, `badge`, `asChild`) `/Body/Header` (`title`, `menuLabel`, `actions`) `/Main` — see [Layouts and templates](#layouts-and-templates) | client |
+| `@krizaka/ui/app-shell` | `AppShell.Root` (`defaultCollapsed`, `collapsed` + `onCollapsedChange`) `/Sidebar` (`label`, `brand`, `footer`, `collapseLabels`, `closeLabel`; a drawer on a phone) `/Group/Item` (`icon`, `label`, `current`, `badge`, `shortcut`, `asChild`) `/Body/Header` (`title`, `menuLabel`, `actions`) `/Search` (`label`, `onOpen`, `shortcut` ⌘K — opens the app's `CommandDialog`) `/Main`; `collapseShortcut` (⌘B), `useShortcuts` — see [Layouts and templates](#layouts-and-templates) | client |
 | `@krizaka/ui/dashboard-layout` | `DashboardLayout` (`title`, `eyebrow`, `description`, `actions`, `toolbar`, `headingAs`), `Widget` (`title`, `description`, `action`, `span` 1·2·3·full, `level`) | server |
 | `@krizaka/ui/settings-layout` | `SettingsLayout` (`title`, `description`, `nav`, `navLabel`, `linkAs`), `SettingsSection` (`title`, `description`, `footer`) | server |
 | `@krizaka/ui/auth-layout` | `AuthLayout` (`brand`, `title`, `description`, `footer`, `legal`, `promise`, `aside`, `asideFooter`) | server |
@@ -250,7 +252,7 @@ applies it before the first paint (no flash), the provider reports it. A persist
 
 ## Page blocks
 
-> Category **blocks** of krizaka.com/docs/ui. The pieces every page of a Krizaka site is made of — one frame, one hero,
+> Category **blocks** of ui.krizaka.com. The pieces every page of a Krizaka site is made of — one frame, one hero,
 > sections on one rhythm, cards that lead or argue, decisions, code, calls to act — so every page reads the same.
 
 ```tsx
@@ -280,7 +282,7 @@ import { LinkCard } from "@krizaka/ui/link-card";
 
 ## Page templates
 
-> Category **templates** of krizaka.com/docs/ui: every page of a Krizaka site has its template.
+> Category **templates** of ui.krizaka.com: every page of a Krizaka site has its template.
 
 Fifteen templates, each a **distinct composition** of the blocks — not the same card grid everywhere: `LandingPage`
 (split hero with the product alive, a band of proofs, a bento), `ProductPage` (split hero in the product's brand,
@@ -300,7 +302,7 @@ boundary stays where it is: a template is a Server Component.
 
 ## Layouts and screens
 
-> Category **layouts** of krizaka.com/docs/ui, and **templates**: whole screens composed from the platform.
+> Category **layouts** of ui.krizaka.com, and **templates**: whole screens composed from the platform.
 
 The shells of the products' screens, read from their real screens (Orochia web, admin and mobile; Orazaka web-client,
 web-admin and mobile; krizaka.com): `AppShell` (sidebar that collapses, header, drawer on a phone), `DashboardLayout`
@@ -315,7 +317,7 @@ React Native shells are `@krizaka/ui/native`'s (DS4): same names where the conce
 
 ## Registry — the code drives the documentation
 
-Every component is also published as data: **[krizaka.com/docs/ui](https://www.krizaka.com/docs/ui)** is generated
+Every component is also published as data: **[ui.krizaka.com](https://ui.krizaka.com)** is generated
 from it at every build of the site (one page per component: when to use it, live examples with their code for the web
 and React Native, props, accessibility), and, later, a `npx @krizaka/cli add <name>` may copy a primitive into a
 product that forks it knowingly. Built by `scripts/build-registry.mjs` after tsup, from three sources in the code:
@@ -405,7 +407,7 @@ const { theme, scheme, mode, setMode, radius } = useTheme(); // theme.surface1,
 | `Segmented` | `options` (`value`, `label`, `disabled`), `value`, `onValueChange`, `size` | The web `Tabs variant="segmented"` (a tab list). To filter, `Chip.Group`. |
 | `Progress` | `variant` bar·ring, `size`, `value`/`max`, `label`, `valueText`, a ring's centre as children | The fill is the `accent` → `accent2` gradient (react-native-svg); it animates to each new value. |
 | `Toaster`, `toast` | `toast(title, { description, tone, icon, action, onPress, id, duration, onDismiss })`, `toast.success/warning/error/info`, `toast.dismiss(id?)`; `Toaster closeLabel position offset duration max` | No sonner: a light queue of its own. `offset` takes the safe-area inset (no safe-area dependency). |
-| `KrizakaMark`, `OrazakaMark`, `OrochiaMark`, `YazakiaMark`, `YororisMark`, `ProductMark` (`id`) | `size`, `animated`, `title`, `neutral` (default `theme.textMuted`) | The brand marks, drawn with react-native-svg from the web marks' geometry. |
+| `KrizakaMark`, `OrazakaMark`, `OrochiaMark`, `YasakiaMark`, `YororisMark`, `ProductMark` (`id`) | `size`, `animated`, `title`, `neutral` (default `theme.textMuted`) | The brand marks, drawn with react-native-svg from the web marks' geometry. |
 
 Every animation (skeleton, badge dot, urgent countdown, progress, toast entrance, the marks) stops when the system
 asks to reduce motion (`useReducedMotion()`). Accessibility goes through `role` and `aria-*` (RN ≥ 0.71): headings,
@@ -435,12 +437,12 @@ Testing Library (`src/native/*.test.tsx`); `scripts/native-dist.mjs` checks that
 ## The marks
 
 ```tsx
-import { KrizakaLogo, OrazakaLogo, OrochiaLogo, ProductLogo, YazakiaLogo, YororisLogo } from "@krizaka/ui";
+import { KrizakaLogo, OrazakaLogo, OrochiaLogo, ProductLogo, YasakiaLogo, YororisLogo } from "@krizaka/ui";
 
 <OrochiaLogo size={36} />                       // decorative (aria-hidden)
 <KrizakaLogo size={48} title="Krizaka" />       // an image with an accessible name
 <ProductLogo id="orazaka" animated={false} />   // by id, still
-<YazakiaLogo size={32} />                       // Yazakia: emerald → turquoise, two voices that meet
+<YasakiaLogo size={32} />                       // Yasakia: emerald → turquoise, two voices that meet
 <YororisLogo size={32} />                       // Yororis: sand → sage, the hold
 ```
 
@@ -497,7 +499,7 @@ classes the components use are generated in your stylesheet.
 ```
 
 Every component, with when to use it, live examples and their code (web and React Native) and its props:
-[krizaka.com/docs/ui](https://www.krizaka.com/docs/ui).
+[ui.krizaka.com](https://ui.krizaka.com).
 
 ## Develop
 

package/dist/action-bar.js

@@ -7,7 +7,8 @@ import {
 } from "./chunk-XCBVFMNV.js";
 import {
   buttonVariants
-} from "./chunk-Z6FUPB3Q.js";
+} from "./chunk-2NB27LM7.js";
+import "./chunk-2VNYHG4E.js";
 import {
   cn
 } from "./chunk-4LOMIQVX.js";

package/dist/action-bar.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/action-bar/action-bar.tsx"],"sourcesContent":["// Server-safe. A row of actions that leave or move on (blocks.css): discuss · propose · report, read the docs, see the\n// code. `buttons`: buttons with their words — the end of a page or a section. `icons`: icon buttons whose words are the\n// accessible name and a tooltip on hover and focus (CSS only: no script, no portal) — the foot of a card.\nimport type * as React from \"react\";\n\nimport { BlockLink, isExternal, type LinkComponent } from \"../block-link\";\nimport { buttonVariants } from \"../button/button\";\nimport { cn } from \"../cn\";\nimport { ExternalGlyph } from \"../glyphs\";\n\nexport interface Action {\n  /** Where it leads. An absolute URL opens in a new tab, with the external mark. */\n  href: string;\n  /** Its words (the accessible name, and the tooltip of an icon action). */\n  label: string;\n  /** Its icon (a signature icon): decorative. Required by `variant=\"icons\"`. */\n  icon?: React.ReactNode;\n}\n\nexport type ActionBarProps = React.HTMLAttributes<HTMLUListElement> & {\n  /** The actions, in order of importance. */\n  actions: readonly Action[];\n  /**\n   * `buttons` (with their words) or `icons` (icon buttons, the words in a tooltip).\n   * @default \"buttons\"\n   */\n  variant?: \"buttons\" | \"icons\";\n  /**\n   * The first action as the primary button (the one action a block is about); the others stay secondary.\n   * @default false\n   */\n  primaryFirst?: boolean;\n  /**\n   * The buttons' size: `sm` in a card, `md` in a section, `lg` on a hero or a closing call.\n   * @default \"md\"\n   */\n  size?: \"sm\" | \"md\" | \"lg\";\n  /** What the actions are about (`Talk about Krizaka Java`): the list's accessible name. */\n  label?: string;\n  /** The app's link component for internal addresses (Next's `Link`); an `<a>` otherwise. */\n  linkAs?: LinkComponent;\n};\n\n/** A row of link actions: buttons with their words, or icon buttons with a tooltip. */\nexport function ActionBar({ actions, variant = \"buttons\", primaryFirst = false, size = \"md\", label, linkAs, className, ...props }: ActionBarProps) {\n  const icons = variant === \"icons\";\n  return (\n    <ul className={cn(\"kz-actions\", className)} data-variant={icons ? \"icons\" : undefined} aria-label={label} {...props}>\n      {actions.map((a, i) => {\n        const external = isExternal(a.href);\n        return (\n          <li key={a.href}>\n            {icons ? (\n              <BlockLink\n                href={a.href}\n                linkAs={linkAs}\n                external={external}\n                aria-label={a.label}\n                data-tip={a.label}\n                className={buttonVariants({ variant: \"ghost\", size: \"icon\", shape: \"cut\", className: size === \"sm\" ? \"h-9 w-9\" : undefined })}\n              >\n                {a.icon}\n              </BlockLink>\n            ) : (\n              <BlockLink\n                href={a.href}\n                linkAs={linkAs}\n                external={external}\n                className={buttonVariants({ variant: primaryFirst && i === 0 ? \"primary\" : \"secondary\", size, shape: \"cut\", className: \"gap-2\" })}\n              >\n                {a.icon}\n                {a.label}\n                {external && <ExternalGlyph className=\"h-3 w-3 opacity-70\" />}\n              </BlockLink>\n            )}\n          </li>\n        );\n      })}\n    </ul>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAqDc,cAWA,YAXA;AATP,SAAS,UAAU,EAAE,SAAS,UAAU,WAAW,eAAe,OAAO,OAAO,MAAM,OAAO,QAAQ,WAAW,GAAG,MAAM,GAAmB;AACjJ,QAAM,QAAQ,YAAY;AAC1B,SACE,oBAAC,QAAG,WAAW,GAAG,cAAc,SAAS,GAAG,gBAAc,QAAQ,UAAU,QAAW,cAAY,OAAQ,GAAG,OAC3G,kBAAQ,IAAI,CAAC,GAAG,MAAM;AACrB,UAAM,WAAW,WAAW,EAAE,IAAI;AAClC,WACE,oBAAC,QACE,kBACC;AAAA,MAAC;AAAA;AAAA,QACC,MAAM,EAAE;AAAA,QACR;AAAA,QACA;AAAA,QACA,cAAY,EAAE;AAAA,QACd,YAAU,EAAE;AAAA,QACZ,WAAW,eAAe,EAAE,SAAS,SAAS,MAAM,QAAQ,OAAO,OAAO,WAAW,SAAS,OAAO,YAAY,OAAU,CAAC;AAAA,QAE3H,YAAE;AAAA;AAAA,IACL,IAEA;AAAA,MAAC;AAAA;AAAA,QACC,MAAM,EAAE;AAAA,QACR;AAAA,QACA;AAAA,QACA,WAAW,eAAe,EAAE,SAAS,gBAAgB,MAAM,IAAI,YAAY,aAAa,MAAM,OAAO,OAAO,WAAW,QAAQ,CAAC;AAAA,QAE/H;AAAA,YAAE;AAAA,UACF,EAAE;AAAA,UACF,YAAY,oBAAC,iBAAc,WAAU,sBAAqB;AAAA;AAAA;AAAA,IAC7D,KAtBK,EAAE,IAwBX;AAAA,EAEJ,CAAC,GACH;AAEJ;","names":[]}
+{"version":3,"sources":["../src/action-bar/action-bar.tsx"],"sourcesContent":["// Server-safe. A row of actions that leave or move on (blocks.css): discuss · propose · report, read the docs, see the\n// code. `buttons`: buttons with their words — the end of a page or a section. `icons`: icon buttons whose words are the\n// accessible name and a tooltip on hover and focus (CSS only: no script, no portal) — the foot of a card.\nimport type * as React from \"react\";\n\nimport { BlockLink, isExternal, type LinkComponent } from \"../block-link\";\nimport { buttonVariants } from \"../button/button\";\nimport { cn } from \"../cn\";\nimport { ExternalGlyph } from \"../glyphs\";\n\nexport interface Action {\n  /** Where it leads. An absolute URL opens in a new tab, with the external mark. */\n  href: string;\n  /** Its words (the accessible name, and the tooltip of an icon action). */\n  label: string;\n  /** Its icon (a signature icon): decorative. Required by `variant=\"icons\"`. */\n  icon?: React.ReactNode;\n}\n\nexport type ActionBarProps = React.HTMLAttributes<HTMLUListElement> & {\n  /** The actions, in order of importance. */\n  actions: readonly Action[];\n  /**\n   * `buttons` (with their words) or `icons` (icon buttons, the words in a tooltip).\n   * @default \"buttons\"\n   */\n  variant?: \"buttons\" | \"icons\";\n  /**\n   * The first action as the primary button (the one action a block is about); the others stay secondary.\n   * @default false\n   */\n  primaryFirst?: boolean;\n  /**\n   * The buttons' size: `sm` in a card, `md` in a section, `lg` on a hero or a closing call.\n   * @default \"md\"\n   */\n  size?: \"sm\" | \"md\" | \"lg\";\n  /** What the actions are about (`Talk about Krizaka Java`): the list's accessible name. */\n  label?: string;\n  /** The app's link component for internal addresses (Next's `Link`); an `<a>` otherwise. */\n  linkAs?: LinkComponent;\n};\n\n/** A row of link actions: buttons with their words, or icon buttons with a tooltip. */\nexport function ActionBar({ actions, variant = \"buttons\", primaryFirst = false, size = \"md\", label, linkAs, className, ...props }: ActionBarProps) {\n  const icons = variant === \"icons\";\n  return (\n    <ul className={cn(\"kz-actions\", className)} data-variant={icons ? \"icons\" : undefined} aria-label={label} {...props}>\n      {actions.map((a, i) => {\n        const external = isExternal(a.href);\n        return (\n          <li key={a.href}>\n            {icons ? (\n              <BlockLink\n                href={a.href}\n                linkAs={linkAs}\n                external={external}\n                aria-label={a.label}\n                data-tip={a.label}\n                className={buttonVariants({ variant: \"ghost\", size: \"icon\", shape: \"cut\", className: size === \"sm\" ? \"h-9 w-9\" : undefined })}\n              >\n                {a.icon}\n              </BlockLink>\n            ) : (\n              <BlockLink\n                href={a.href}\n                linkAs={linkAs}\n                external={external}\n                className={buttonVariants({ variant: primaryFirst && i === 0 ? \"primary\" : \"secondary\", size, shape: \"cut\", className: \"gap-2\" })}\n              >\n                {a.icon}\n                {a.label}\n                {external && <ExternalGlyph className=\"h-3 w-3 opacity-70\" />}\n              </BlockLink>\n            )}\n          </li>\n        );\n      })}\n    </ul>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAqDc,cAWA,YAXA;AATP,SAAS,UAAU,EAAE,SAAS,UAAU,WAAW,eAAe,OAAO,OAAO,MAAM,OAAO,QAAQ,WAAW,GAAG,MAAM,GAAmB;AACjJ,QAAM,QAAQ,YAAY;AAC1B,SACE,oBAAC,QAAG,WAAW,GAAG,cAAc,SAAS,GAAG,gBAAc,QAAQ,UAAU,QAAW,cAAY,OAAQ,GAAG,OAC3G,kBAAQ,IAAI,CAAC,GAAG,MAAM;AACrB,UAAM,WAAW,WAAW,EAAE,IAAI;AAClC,WACE,oBAAC,QACE,kBACC;AAAA,MAAC;AAAA;AAAA,QACC,MAAM,EAAE;AAAA,QACR;AAAA,QACA;AAAA,QACA,cAAY,EAAE;AAAA,QACd,YAAU,EAAE;AAAA,QACZ,WAAW,eAAe,EAAE,SAAS,SAAS,MAAM,QAAQ,OAAO,OAAO,WAAW,SAAS,OAAO,YAAY,OAAU,CAAC;AAAA,QAE3H,YAAE;AAAA;AAAA,IACL,IAEA;AAAA,MAAC;AAAA;AAAA,QACC,MAAM,EAAE;AAAA,QACR;AAAA,QACA;AAAA,QACA,WAAW,eAAe,EAAE,SAAS,gBAAgB,MAAM,IAAI,YAAY,aAAa,MAAM,OAAO,OAAO,WAAW,QAAQ,CAAC;AAAA,QAE/H;AAAA,YAAE;AAAA,UACF,EAAE;AAAA,UACF,YAAY,oBAAC,iBAAc,WAAU,sBAAqB;AAAA;AAAA;AAAA,IAC7D,KAtBK,EAAE,IAwBX;AAAA,EAEJ,CAAC,GACH;AAEJ;","names":[]}

package/dist/app-shell.d.ts

@@ -9,6 +9,7 @@ declare const appShell: tailwind_variants.TVReturnType<{
             header?: tailwind_variants.ClassValue;
             main?: tailwind_variants.ClassValue;
             nav?: tailwind_variants.ClassValue;
+            search?: tailwind_variants.ClassValue;
             title?: tailwind_variants.ClassValue;
             group?: tailwind_variants.ClassValue;
             root?: tailwind_variants.ClassValue;
@@ -16,6 +17,9 @@ declare const appShell: tailwind_variants.TVReturnType<{
             overlay?: tailwind_variants.ClassValue;
             brand?: tailwind_variants.ClassValue;
             itemLabel?: tailwind_variants.ClassValue;
+            itemHint?: tailwind_variants.ClassValue;
+            searchLabel?: tailwind_variants.ClassValue;
+            searchKeys?: tailwind_variants.ClassValue;
             actions?: tailwind_variants.ClassValue;
             sidebar?: tailwind_variants.ClassValue;
             item?: tailwind_variants.ClassValue;
@@ -32,6 +36,7 @@ declare const appShell: tailwind_variants.TVReturnType<{
             header?: tailwind_variants.ClassValue;
             main?: tailwind_variants.ClassValue;
             nav?: tailwind_variants.ClassValue;
+            search?: tailwind_variants.ClassValue;
             title?: tailwind_variants.ClassValue;
             group?: tailwind_variants.ClassValue;
             root?: tailwind_variants.ClassValue;
@@ -39,6 +44,9 @@ declare const appShell: tailwind_variants.TVReturnType<{
             overlay?: tailwind_variants.ClassValue;
             brand?: tailwind_variants.ClassValue;
             itemLabel?: tailwind_variants.ClassValue;
+            itemHint?: tailwind_variants.ClassValue;
+            searchLabel?: tailwind_variants.ClassValue;
+            searchKeys?: tailwind_variants.ClassValue;
             actions?: tailwind_variants.ClassValue;
             sidebar?: tailwind_variants.ClassValue;
             item?: tailwind_variants.ClassValue;
@@ -57,6 +65,7 @@ declare const appShell: tailwind_variants.TVReturnType<{
     group: string;
     item: string;
     itemLabel: string;
+    itemHint: string;
     itemBadge: string;
     footer: string;
     collapse: string;
@@ -64,6 +73,9 @@ declare const appShell: tailwind_variants.TVReturnType<{
     header: string;
     menuButton: string;
     title: string;
+    search: string;
+    searchLabel: string;
+    searchKeys: string;
     actions: string;
     main: string;
 }, undefined, {
@@ -74,6 +86,7 @@ declare const appShell: tailwind_variants.TVReturnType<{
             header?: tailwind_variants.ClassValue;
             main?: tailwind_variants.ClassValue;
             nav?: tailwind_variants.ClassValue;
+            search?: tailwind_variants.ClassValue;
             title?: tailwind_variants.ClassValue;
             group?: tailwind_variants.ClassValue;
             root?: tailwind_variants.ClassValue;
@@ -81,6 +94,9 @@ declare const appShell: tailwind_variants.TVReturnType<{
             overlay?: tailwind_variants.ClassValue;
             brand?: tailwind_variants.ClassValue;
             itemLabel?: tailwind_variants.ClassValue;
+            itemHint?: tailwind_variants.ClassValue;
+            searchLabel?: tailwind_variants.ClassValue;
+            searchKeys?: tailwind_variants.ClassValue;
             actions?: tailwind_variants.ClassValue;
             sidebar?: tailwind_variants.ClassValue;
             item?: tailwind_variants.ClassValue;
@@ -99,6 +115,7 @@ declare const appShell: tailwind_variants.TVReturnType<{
     group: string;
     item: string;
     itemLabel: string;
+    itemHint: string;
     itemBadge: string;
     footer: string;
     collapse: string;
@@ -106,6 +123,9 @@ declare const appShell: tailwind_variants.TVReturnType<{
     header: string;
     menuButton: string;
     title: string;
+    search: string;
+    searchLabel: string;
+    searchKeys: string;
     actions: string;
     main: string;
 }, tailwind_variants.TVReturnTypeLike<unknown, {
@@ -118,6 +138,7 @@ declare const appShell: tailwind_variants.TVReturnType<{
     group: string;
     item: string;
     itemLabel: string;
+    itemHint: string;
     itemBadge: string;
     footer: string;
     collapse: string;
@@ -125,6 +146,9 @@ declare const appShell: tailwind_variants.TVReturnType<{
     header: string;
     menuButton: string;
     title: string;
+    search: string;
+    searchLabel: string;
+    searchKeys: string;
     actions: string;
     main: string;
 }>>;
@@ -137,9 +161,15 @@ type AppShellRootProps = React.ComponentProps<"div"> & {
     onCollapsedChange?: (collapsed: boolean) => void;
     /** The words of the "skip to content" link (`Skip to content`), the first tab stop; it lands on `AppShell.Main`. Without it, no link. */
     skipLabel?: string;
+    /**
+     * The shortcut that folds and unfolds the sidebar (a combination: `mod+b` is ⌘B on a Mac, Ctrl+B elsewhere), or `false`
+     * for none.
+     * @default "mod+b"
+     */
+    collapseShortcut?: string | false;
 };
 /** The shell: holds the collapse (desktop) and the drawer (phone) state. Children: Sidebar, then Body. */
-declare function AppShellRoot({ defaultCollapsed, collapsed: controlled, onCollapsedChange, skipLabel, className, children, ...props }: AppShellRootProps): React.JSX.Element;
+declare function AppShellRoot({ defaultCollapsed, collapsed: controlled, onCollapsedChange, skipLabel, collapseShortcut, className, children, ...props }: AppShellRootProps): React.JSX.Element;
 type AppShellSidebarProps = Omit<React.ComponentProps<"nav">, "children"> & {
     /** The navigation's accessible name (`Studio`, `Administration`). */
     label: string;
@@ -171,13 +201,18 @@ type AppShellItemProps = Omit<React.ComponentProps<"a">, "children"> & {
     current?: boolean;
     /** A count beside it (unread, pending): a number or a few characters. */
     badge?: React.ReactNode;
+    /**
+     * A keyboard shortcut that goes to it: a sequence (`g d`: G then D) or a combination (`mod+1`). It clicks the item, so a
+     * router link navigates. The keys are shown on hover and focus when the sidebar is open.
+     */
+    shortcut?: string;
     /** Renders your link (Next's `Link`) with the item's look: pass it as the only child. */
     asChild?: boolean;
     /** Your link element when `asChild`. */
     children?: React.ReactElement;
 };
 /** A destination of the sidebar: icon, words, a count. */
-declare function AppShellItem({ icon, label, current, badge, asChild, children, className, ...props }: AppShellItemProps): React.JSX.Element;
+declare function AppShellItem({ icon, label, current, badge, shortcut, asChild, children, className, ...props }: AppShellItemProps): React.JSX.Element;
 /** The column right of the sidebar: Header, then Main. */
 declare function AppShellBody({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
 type AppShellHeaderProps = Omit<React.ComponentProps<"header">, "title"> & {
@@ -190,6 +225,19 @@ type AppShellHeaderProps = Omit<React.ComponentProps<"header">, "title"> & {
 };
 /** The top of the screen: the drawer's button (phone), the title, the actions. Sticky. */
 declare function AppShellHeader({ title, menuLabel, actions, className, children, ...props }: AppShellHeaderProps): React.JSX.Element;
+type AppShellSearchProps = Omit<React.ComponentProps<"button">, "children" | "onClick"> & {
+    /** The words ("Search", "Search creators"): the accessible name, shown beside the keys on a desktop. */
+    label: string;
+    /** Called when the button is pressed or the shortcut is typed: open your command palette (`CommandDialog`) here. */
+    onOpen: () => void;
+    /**
+     * The shortcut that opens it (a combination); shown on its keys.
+     * @default "mod+k"
+     */
+    shortcut?: string;
+};
+/** The header's search: a button that looks like a field (a magnifier, its words, ⌘K) and opens the app's command palette. */
+declare function AppShellSearch({ label, onOpen, shortcut, className, ...props }: AppShellSearchProps): React.JSX.Element;
 /** The screen's content. */
 declare function AppShellMain({ className, ...props }: React.ComponentProps<"main">): React.JSX.Element;
 declare const AppShell: {
@@ -199,7 +247,37 @@ declare const AppShell: {
     Item: typeof AppShellItem;
     Body: typeof AppShellBody;
     Header: typeof AppShellHeader;
+    Search: typeof AppShellSearch;
     Main: typeof AppShellMain;
 };
 
-export { AppShell, AppShellBody, AppShellGroup, type AppShellGroupProps, AppShellHeader, type AppShellHeaderProps, AppShellItem, type AppShellItemProps, AppShellMain, AppShellRoot, type AppShellRootProps, AppShellSidebar, type AppShellSidebarProps, appShell };
+type ShortcutMap = Readonly<Record<string, ((event: KeyboardEvent) => void) | undefined>>;
+type Combo = {
+    key: string;
+    mod: boolean;
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+};
+/** `"mod+shift+k"` → its parts. A lone `+` key is written `plus`. */
+declare function parseCombo(combo: string): Combo;
+/** Whether a key event is this combination: its modifiers exactly (`mod` is ⌘ or Ctrl by platform), then its key. */
+declare function matchesCombo(event: Pick<KeyboardEvent, "key" | "metaKey" | "ctrlKey" | "altKey" | "shiftKey">, combo: string, apple?: boolean): boolean;
+/** The keys of a shortcut to show on a keycap: `["⌘", "K"]` on a Mac, `["Ctrl", "K"]` elsewhere; a sequence `g d` is `["G", "D"]`. */
+declare function formatShortcut(shortcut: string, apple?: boolean): string[];
+/** Whether the person is on an Apple device — `false` on the server and in the first client render (no mismatch), then right. */
+declare function useApple(): boolean;
+/** The `aria-keyshortcuts` of a combination (`Control+K`, `Meta+K` on a Mac); a sequence has none (it is not a chord). */
+declare function ariaKeyShortcuts(shortcut: string, apple?: boolean): string | undefined;
+/**
+ * Binds shortcuts for as long as the component lives (`enabled` turns them off). Each key is a combination or a sequence,
+ * each value runs when it is pressed; the handler may change on every render. A shortcut that fires is `preventDefault`ed.
+ * A sequence waits `timeout` ms for its next key.
+ */
+declare function useShortcuts(map: ShortcutMap, { enabled, timeout }?: {
+    enabled?: boolean;
+    timeout?: number;
+}): void;
+
+export { AppShell, AppShellBody, AppShellGroup, type AppShellGroupProps, AppShellHeader, type AppShellHeaderProps, AppShellItem, type AppShellItemProps, AppShellMain, AppShellRoot, type AppShellRootProps, AppShellSearch, type AppShellSearchProps, AppShellSidebar, type AppShellSidebarProps, type ShortcutMap, appShell, ariaKeyShortcuts, formatShortcut, matchesCombo, parseCombo, useApple, useShortcuts };