prime-ui-kit 0.14.0 → 0.16.0

package/dist/layout/app-header/AppHeader.d.ts

@@ -4,6 +4,7 @@ export type AppHeaderLabels = {
     /** Name of the menu button that opens the off-canvas Sidebar. */
     menu: string;
 };
+export declare const APP_HEADER_LABELS: AppHeaderLabels;
 type HeaderProps = React.HTMLAttributes<HTMLElement> & {
     ref?: React.Ref<HTMLElement>;
 };
@@ -11,35 +12,37 @@ type DivProps = React.HTMLAttributes<HTMLDivElement> & {
     ref?: React.Ref<HTMLDivElement>;
 };
 export type AppHeaderRootProps = HeaderProps & {
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<AppHeaderLabels>;
 };
 /**
- * The bar at the very top of the content panel: where you are, global search, a few actions.
- * One row as high as the Sidebar brand row, so the two read as one line; sticky; lays itself out
- * from its own width (narrow: the search folds into an icon, the title truncates).
+ * The page's bar at the very top of the content panel: a title row as high as the Sidebar brand
+ * row (so the two read as one line) with only what the current page needs — the page title, the
+ * page's own buttons — and the page tools (`AppHeader.Tools`) as a second row under it. Sticky;
+ * lays itself out from its own width (narrow: the title icon goes, the title and its line of data
+ * truncate). Inside an `AppShell` a header the page renders moves into the shell's header row, and
+ * while the Sidebar is off-canvas the row starts with the menu button that opens it.
  */
-declare function AppHeaderRoot({ labels, className, children, ...rest }: AppHeaderRootProps): import("react/jsx-runtime").JSX.Element;
+declare function AppHeaderRoot(props: AppHeaderRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AppHeaderRoot {
     var displayName: string;
 }
 export type AppHeaderStartProps = DivProps;
 /** The leading zone: the menu button, a back button, the title or breadcrumbs. Takes the free width. */
-declare function AppHeaderStart({ className, ...rest }: AppHeaderStartProps): import("react/jsx-runtime").JSX.Element;
+declare function AppHeaderStart({ className, children, ...rest }: AppHeaderStartProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AppHeaderStart {
     var displayName: string;
 }
-export type AppHeaderTitleProps = DivProps & {
-    /**
-     * Tag of the name: `h1` when the header carries the page title (no `PageContent.Header` in
-     * main) — the description stays outside the heading's name. Default `span`.
-     */
-    as?: "span" | "h1";
-};
+export type AppHeaderTitleProps = DivProps;
 /**
  * Where you are: an optional `AppHeader.Icon`, the name and an optional `AppHeader.Description`
- * under it — the same anatomy as the Sidebar brand. The name truncates.
+ * under it — the same anatomy as the Sidebar brand. The name is the page's `<h1>` (an app page
+ * titles itself in the header); the description stays outside the heading's name. The name
+ * truncates.
  */
-declare function AppHeaderTitle({ as: NameTag, className, children, ...rest }: AppHeaderTitleProps): import("react/jsx-runtime").JSX.Element;
+declare function AppHeaderTitle({ className, children, ...rest }: AppHeaderTitleProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AppHeaderTitle {
     var displayName: string;
 }
@@ -57,40 +60,28 @@ declare namespace AppHeaderIcon {
 export type AppHeaderDescriptionProps = React.HTMLAttributes<HTMLSpanElement> & {
     ref?: React.Ref<HTMLSpanElement>;
 };
-/** Muted second line under the title (a workspace, a period); hidden on a narrow header. */
+/** Muted line of data under the title (a period, a count); on a narrow header it truncates. */
 declare function AppHeaderDescription({ className, ...rest }: AppHeaderDescriptionProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AppHeaderDescription {
     var displayName: string;
 }
-export type AppHeaderSeparatorProps = Omit<DividerProps, "orientation" | "children">;
-/** A short vertical line between groups in a zone (a back button | the path), with air on both sides. */
-declare function AppHeaderSeparator({ className, ...rest }: AppHeaderSeparatorProps): import("react/jsx-runtime").JSX.Element;
-declare namespace AppHeaderSeparator {
-    var displayName: string;
-}
-export type AppHeaderSearchProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children"> & {
-    /** Placeholder text; also the button's name when the header is narrow and the field folds. */
-    children: React.ReactNode;
-    /** Key hint at the end. Default `⌘K`; `null` hides it. */
-    shortcut?: React.ReactNode;
-    ref?: React.Ref<HTMLButtonElement>;
-};
+export type AppHeaderSeparatorProps = Omit<DividerProps, "orientation" | "children" | "align" | "size" | "inset">;
 /**
- * Global search entry: looks like a field, works as a button that opens your CommandMenu (wire
- * `onClick` and the shortcut). On a narrow header it folds into a square search button.
+ * A short vertical line between groups in a zone (a back button | the path), with air on both
+ * sides: the inset vertical Divider, one text line tall.
  */
-declare function AppHeaderSearch({ children, shortcut, className, ...rest }: AppHeaderSearchProps): import("react/jsx-runtime").JSX.Element;
-declare namespace AppHeaderSearch {
+declare function AppHeaderSeparator({ className, ...rest }: AppHeaderSeparatorProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppHeaderSeparator {
     var displayName: string;
 }
 export type AppHeaderToolsProps = DivProps;
 /**
  * The page's tools in the header — a `PageToolbar.Root` (sections, period, filters, the primary
  * action): the header's second row, the full width under the title row, so the toolbar lays
- * itself out from that width (one row when wide, two when narrow). Root moves it there wherever
- * it is written.
+ * itself out from that width (one row when wide, two when narrow). Root places it there wherever
+ * it is written — directly, in a fragment or inside a component of the page.
  */
-declare function AppHeaderTools({ className, ...rest }: AppHeaderToolsProps): import("react/jsx-runtime").JSX.Element;
+declare function AppHeaderTools(props: AppHeaderToolsProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AppHeaderTools {
     var displayName: string;
 }
@@ -100,16 +91,16 @@ declare function AppHeaderActions({ className, ...rest }: AppHeaderActionsProps)
 declare namespace AppHeaderActions {
     var displayName: string;
 }
-export type AppHeaderMenuButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children"> & {
-    /**
-     * `narrow` (default): shown below 768px, where an `offCanvas="auto"` Sidebar leaves the layout;
-     * `always`: on every width (`offCanvas="always"`).
-     */
-    show?: "narrow" | "always";
+export type AppHeaderMenuButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children" | "aria-expanded" | "aria-controls"> & {
     ref?: React.Ref<HTMLButtonElement>;
 };
-/** Opens the off-canvas Sidebar: an icon button named by `labels.menu`; wire `onClick` and `aria-expanded`. */
-declare function AppHeaderMenuButton({ show, className, ...rest }: AppHeaderMenuButtonProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Opens the off-canvas Sidebar of the shell: an icon button named by `labels.menu`, with
+ * `aria-expanded` and `aria-controls` from the shell. The bar draws one itself; this part moves it
+ * to another place in the header. Renders nothing while the Sidebar is a rail on screen, or
+ * outside a shell with a Sidebar.
+ */
+declare function AppHeaderMenuButton(props: AppHeaderMenuButtonProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AppHeaderMenuButton {
     var displayName: string;
 }
@@ -120,7 +111,6 @@ export declare const AppHeader: {
     Icon: typeof AppHeaderIcon;
     Description: typeof AppHeaderDescription;
     Separator: typeof AppHeaderSeparator;
-    Search: typeof AppHeaderSearch;
     Tools: typeof AppHeaderTools;
     Actions: typeof AppHeaderActions;
     MenuButton: typeof AppHeaderMenuButton;

package/dist/layout/app-shell/AppShell.d.ts

@@ -1,7 +1,52 @@
 import * as React from "react";
+import { type OutletStore } from "../../internal/slot";
+/**
+ * The navigation of the shell, as its Sidebar publishes it: what a menu button anywhere in the
+ * shell needs (`AppHeader.MenuButton`, `Sidebar.Toggle` outside the rail, a BottomNav «Ещё»).
+ */
+export type AppShellNavState = {
+    /** `id` of the navigation landmark, for `aria-controls`. */
+    navId: string;
+    /** The navigation is an off-canvas panel now (a phone, or `offCanvas="always"`). */
+    offCanvas: boolean;
+    /** The off-canvas panel is open. */
+    open: boolean;
+    setOpen: (open: boolean) => void;
+    /** The navigation is in view: the off-canvas panel open, or the rail expanded. */
+    expanded: boolean;
+    /** Opens or closes the off-canvas panel; on screen, expands or folds the rail. */
+    toggle: () => void;
+};
+type ShellRegistry = {
+    /** The Sidebar publishes its navigation (`null` when it leaves). */
+    publishNav: (nav: AppShellNavState | null) => void;
+    /** The header outlet: a page's own `AppHeader.Root` moves here. */
+    headers: OutletStore;
+};
+/**
+ * The navigation of the nearest `AppShell.Root`, as its Sidebar publishes it; `null` outside a
+ * shell or before a Sidebar is in it. For a trigger of the navigation outside the rail.
+ */
+export declare function useAppShellNav(): AppShellNavState | null;
+/** How the Sidebar publishes its navigation into the shell (`null` outside a shell). */
+export declare function useAppShellNavPublisher(): ShellRegistry["publishNav"] | null;
+/**
+ * The outlet a page's `AppHeader.Root` moves into: the shell's header row. `null` outside a
+ * shell, and in the outlet itself (the header there is in place).
+ */
+export declare function useAppShellHeaderOutlet(): OutletStore | null;
+/**
+ * Starts a frame of its own inside a shell: a preview of a screen (`ExampleFrame`) is not the
+ * page, so a header or a Sidebar in it stays in the preview instead of joining the shell around it.
+ */
+export declare function AppShellBoundary({ children }: {
+    children?: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
 export type AppShellRootProps = React.HTMLAttributes<HTMLDivElement> & {
     ref?: React.Ref<HTMLDivElement>;
-    /** Viewport-high shell: only `AppShell.Main` scrolls. Otherwise the document scrolls. */
+    /**
+     * As on `AppShell.Root`: only `<main>` scrolls.
+     */
     fillViewport?: boolean;
 };
 export type AppShellNavProps = React.HTMLAttributes<HTMLDivElement> & {
@@ -14,7 +59,9 @@ declare namespace AppShellNav {
 }
 /**
  * Grid: navigation column | content panel. Everything that is not `AppShell.Nav` goes into the
- * content panel, which is the page itself (the layer around the shell): cards on it are the next layer.
+ * content panel, which is the page itself (the layer around the shell): cards on it are the next
+ * layer. The root owns the navigation state the Sidebar publishes and the header row the page's
+ * `AppHeader.Root` moves into.
  */
 declare function AppShellRoot({ fillViewport, className, children, ...rest }: AppShellRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AppShellRoot {
@@ -32,6 +79,9 @@ declare namespace AppShellFooter {
 export type AppShellContentWidth = "contained" | "full";
 export type AppShellMainProps = React.HTMLAttributes<HTMLElement> & {
     ref?: React.Ref<HTMLElement>;
+    /**
+     * `full` — the whole panel with gutters; `contained` — a centred column up to `--prime-layout-content-max-width`.
+     */
     contentWidth?: AppShellContentWidth;
 };
 /** `<main>` with the canonical gutters; scrolls inside the panel when `fillViewport` is set. */
@@ -40,22 +90,36 @@ declare namespace AppShellMain {
     var displayName: string;
 }
 export type AppShellTemplateProps = Omit<AppShellRootProps, "children" | "ref"> & {
-    /** Forwarded to the `<main>`. */
     ref?: React.Ref<HTMLElement>;
-    /** Navigation column content, usually `Sidebar.Root`. */
+    /**
+     * Navigation column content; without it the panel takes the full width.
+     */
     nav?: React.ReactNode;
-    /** The top bar of the content panel, an `AppHeader.Root`; no header when omitted. */
+    /**
+     * The default header row, an `AppHeader.Root`: a page that renders its own header replaces it while that page is on screen.
+     */
     header?: React.ReactNode;
-    /** `AppShell.Footer` content (`BottomNav`); no footer when omitted. */
+    /**
+     * Footer content (`BottomNav`); no footer when omitted.
+     */
     footer?: React.ReactNode;
+    /**
+     * Page content inside Main.
+     */
     children?: React.ReactNode;
+    /**
+     * Props for Main (e.g. `contentWidth`).
+     */
     mainProps?: Omit<AppShellMainProps, "children" | "ref">;
-    /** Main scrolls back to the top whenever this value changes (pass the router pathname). */
+    /**
+     * Main scrolls back to the top whenever this value changes; pass the router pathname.
+     */
     scrollResetKey?: unknown;
 };
 /**
  * Root + Nav + the header + Main + Footer in one; main scrolls to the top when `scrollResetKey`
- * changes.
+ * changes. `header` is the default header row: a page that renders its own `AppHeader.Root`
+ * replaces it while it is on screen.
  */
 declare function AppShellTemplate({ ref, nav, header, footer, children, mainProps, scrollResetKey, ...rootProps }: AppShellTemplateProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AppShellTemplate {

package/dist/layout/bottom-nav/BottomNav.d.ts

@@ -4,16 +4,19 @@ export type BottomNavLabels = {
     /** `aria-label` of the `<nav>` landmark. */
     nav: string;
 };
+export declare const BOTTOM_NAV_LABELS: BottomNavLabels;
 export type BottomNavRootProps = React.HTMLAttributes<HTMLElement> & {
-    /** Icons without visible labels; the labels still name the items for screen readers. */
+    /**
+     * Icons without visible labels; the labels stay in the DOM as visually hidden text and name the items.
+     */
     iconOnly?: boolean;
     /**
-     * A glass capsule floating over the content (backdrop blur, inset from the edges) instead of
-     * a flat bar at the edge, with a selection capsule that glides to the current item. It places
-     * itself at the bottom of its positioned container (`AppShell.Footer`), so the page scrolls
-     * under it.
+     * A glass capsule floating over the content at the bottom of its positioned container (`AppShell.Footer`), with a selection capsule gliding under the current item; the page scrolls under it.
      */
     floating?: boolean;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<BottomNavLabels>;
     /** The `<nav>`. */
     ref?: React.Ref<HTMLElement>;
@@ -23,28 +26,35 @@ export type BottomNavRootProps = React.HTMLAttributes<HTMLElement> & {
  * action beside it. Inside `AppShell.Footer` it shows only while the Sidebar rail is off screen;
  * once the rail is on screen, Sidebar navigates.
  */
-declare function BottomNavRoot({ iconOnly, floating, labels, className, children, ...rest }: BottomNavRootProps): import("react/jsx-runtime").JSX.Element;
+declare function BottomNavRoot({ iconOnly, floating, labels: labelsProp, className, children, ...rest }: BottomNavRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace BottomNavRoot {
     var displayName: string;
 }
 export type BottomNavActionProps = Omit<React.ComponentPropsWithoutRef<"button">, "children"> & {
-    /** The glyph, e.g. `<Icon name="action.add" />`. */
+    /**
+     * The glyph, e.g. `<Icon name="action.add" />`.
+     */
     children: React.ReactNode;
-    /** The action has no visible text: `aria-label` names it. */
+    /**
+     * The name of the action: the button has no visible text.
+     */
     "aria-label": string;
     ref?: React.Ref<HTMLButtonElement>;
 };
 /**
  * A round button beside the bar for the screen's main action (create, search, assistant): a
- * `Button shape="circle"` (`l`, neutral) — in a flat bar a muted disk at its edge, in `floating` a
- * glass disk as tall as the capsule (the capsule's own glass, set on the Button by class: Button
- * has no glass look).
+ * `Button shape="circle"` (`l`, neutral) — in a flat bar a solid disk at its edge, in `floating` a
+ * Button `glass` disk as tall as the capsule (the bar gives it its height); the bar draws the rim
+ * and the lift around it.
  */
 declare function BottomNavAction({ className, children, ...rest }: BottomNavActionProps): import("react/jsx-runtime").JSX.Element;
 declare namespace BottomNavAction {
     var displayName: string;
 }
 export type BottomNavItemIconProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
+    /**
+     * The icon, e.g. `<Icon name="nav.home" />`.
+     */
     children: React.ReactNode;
     ref?: React.Ref<HTMLSpanElement>;
 };
@@ -54,11 +64,17 @@ declare namespace BottomNavItemIcon {
     var displayName: string;
 }
 export type BottomNavItemCountProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children" | "color"> & {
-    /** The number (or a short status). */
+    /**
+     * The number (or a short status such as «99+»).
+     */
     children: React.ReactNode;
-    /** Badge hue. Default `red`: a count on a section asks for attention. */
+    /**
+     * Badge hue: a count on a section asks for attention.
+     */
     color?: PaletteColor;
-    /** Badge treatment. Default `solid`. */
+    /**
+     * Badge treatment.
+     */
     variant?: Exclude<Variant, "ghost">;
     /** The Badge `<span>`. */
     ref?: React.Ref<HTMLSpanElement>;
@@ -69,24 +85,44 @@ declare namespace BottomNavItemCount {
     var displayName: string;
 }
 type BottomNavItemOwnProps = {
-    /** Current section: `aria-current="page"`. Links rendered by a router may set it themselves. */
+    /**
+     * Current section: `aria-current="page"`; the icon and the label turn primary (the others are muted) and the glyph sits on a soft pill; floating, the item is in the accent on the selection capsule (the others in full ink).
+     */
     current?: boolean;
+    /**
+     * Not interactive: `disabled` / `aria-disabled`, `data-disabled`, out of the Tab order; an `href` link loses its `href`, an `asChild` child keeps its own and only its clicks are blocked.
+     */
     disabled?: boolean;
-    /** Render the single child element (a router link) as the item; its children are the content. */
+    /**
+     * Renders the single child (e.g. a router `NavLink`) as the item; its children are the label and parts.
+     */
     asChild?: boolean;
-    /** `BottomNav.ItemIcon`, an optional `BottomNav.ItemCount` and the label. */
+    /**
+     * `BottomNav.ItemIcon`, an optional `BottomNav.ItemCount` and a short label (one word).
+     */
     children?: React.ReactNode;
 };
-export type BottomNavItemProps = BottomNavItemOwnProps & Omit<React.ComponentPropsWithoutRef<"button">, keyof BottomNavItemOwnProps> & {
-    /** Renders an `<a>` instead of a `<button>`. */
+export type BottomNavItemProps = BottomNavItemOwnProps & Omit<React.HTMLAttributes<HTMLElement>, keyof BottomNavItemOwnProps> & {
+    /**
+     * Renders an `<a>` (with `target`, `rel`).
+     */
     href?: string;
+    /**
+     * Where the `<a>` opens (`href` only).
+     */
     target?: string;
+    /**
+     * Relationship of the `<a>` (`href` only).
+     */
     rel?: string;
-    /** The `<a>`, `<button>` or the `asChild` element. */
     ref?: React.Ref<HTMLElement>;
 };
-/** A section of the bar: the icon above a short label, both in the primary color while current. */
-declare function BottomNavItem({ current, disabled, asChild, href, className, children, onClick, type, ref, ...rest }: BottomNavItemProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * A section of the bar: the icon above a short label, both in the primary color while current. A
+ * link (`href`), a button, or the consumer's element (`asChild`, a router link) — the kit's
+ * interactive element with its disabled guard.
+ */
+declare function BottomNavItem({ current, disabled, asChild, href, target, rel, className, children, ...rest }: BottomNavItemProps): import("react/jsx-runtime").JSX.Element;
 declare namespace BottomNavItem {
     var displayName: string;
 }

package/dist/layout/index.d.ts

@@ -1,7 +1,7 @@
-export type { AppHeaderActionsProps, AppHeaderDescriptionProps, AppHeaderIconProps, AppHeaderLabels, AppHeaderMenuButtonProps, AppHeaderRootProps, AppHeaderSearchProps, AppHeaderSeparatorProps, AppHeaderStartProps, AppHeaderTitleProps, AppHeaderToolsProps, } from "./app-header/AppHeader";
+export type { AppHeaderActionsProps, AppHeaderDescriptionProps, AppHeaderIconProps, AppHeaderLabels, AppHeaderMenuButtonProps, AppHeaderRootProps, AppHeaderSeparatorProps, AppHeaderStartProps, AppHeaderTitleProps, AppHeaderToolsProps, } from "./app-header/AppHeader";
 export { AppHeader } from "./app-header/AppHeader";
-export type { AppShellContentWidth, AppShellFooterProps, AppShellMainProps, AppShellNavProps, AppShellRootProps, AppShellTemplateProps, } from "./app-shell/AppShell";
-export { AppShell } from "./app-shell/AppShell";
+export type { AppShellContentWidth, AppShellFooterProps, AppShellMainProps, AppShellNavProps, AppShellNavState, AppShellRootProps, AppShellTemplateProps, } from "./app-shell/AppShell";
+export { AppShell, useAppShellNav } from "./app-shell/AppShell";
 export type { BottomNavActionProps, BottomNavItemCountProps, BottomNavItemIconProps, BottomNavItemProps, BottomNavLabels, BottomNavRootProps, } from "./bottom-nav/BottomNav";
 export { BottomNav } from "./bottom-nav/BottomNav";
 export type { SidebarAccountProps, SidebarBrandLogoProps, SidebarBrandProps, SidebarContentProps, SidebarFooterProps, SidebarGroupProps, SidebarHeaderProps, SidebarItemActionProps, SidebarItemCountProps, SidebarItemIconProps, SidebarItemProps, SidebarItemShortcutProps, SidebarLabels, SidebarMode, SidebarRootProps, SidebarSubContentProps, SidebarSubProps, SidebarSubTriggerProps, SidebarToggleProps, } from "./sidebar/Sidebar";