@surflane/ui 0.9.0 → 0.10.1

package/README.md

@@ -5,20 +5,20 @@
 React 19 components for the Surflane design system, built on [Base UI](https://base-ui.com), with data, chart, date, tree, code highlighting and Markdown components. Browse them in the [catalog](https://surflane.page).
 
 ```sh
-npm install @surflane/ui @surflane/design-tokens
+npm install @surflane/ui @surflane/design-tokens @surflane/css @base-ui/react
 ```
 
-`@surflane/ui` and `@surflane/design-tokens` are released together with the same version. The package is ESM-only.
+`@surflane/ui`, `@surflane/design-tokens` and `@surflane/css` are released together with one version. Base UI is a peer dependency, 1.9 or later, so your app and Surflane share one copy. The package is ESM-only.
 
 ## Usage
 
-Import the stylesheets once at the application root. `all.css` brings the tokens, controls, composition, document typography and component styles:
+Import the stylesheets once at the application root. `all.css` brings the tokens, the theme transition, controls, composition, document typography and component styles:
 
 ```css
 @import '@surflane/ui/all.css';
 ```
 
-To ship only what you use, import component stylesheets instead, such as `@surflane/ui/button.css` and `@surflane/ui/dialog.css`. Each brings the tokens and the styles of what its component renders. The rules sit in `surflane.*` cascade layers, so your unlayered CSS overrides them. Set `data-theme="light"` or `data-theme="dark"` on `<html>` before the first paint and add `pui-typography` to `<body>`. With AppShell, which fills the window, also give `<body>` no margin and the `--chrome` background. The [install guide](https://surflane.page/install) walks through Vite, Next.js, React Router and Astro, with or without Tailwind CSS.
+To ship only what you use, import component stylesheets instead, such as `@surflane/ui/button.css` and `@surflane/ui/dialog.css`. Each brings the tokens and the styles of what its component renders. The rules sit in `surflane.*` cascade layers, so your unlayered CSS overrides them. Set `data-theme="light"` or `data-theme="dark"` on `<html>` before the first paint and add `surf-typography` to `<body>`. With AppShell, which fills the window, also give `<body>` no margin and the `--surf-chrome` background. The [install guide](https://surflane.page/install) walks through Vite, Next.js, React Router and Astro, with or without Tailwind CSS.
 
 ```tsx
 import {

package/dist/accordion.d.ts

@@ -1,26 +1,42 @@
 import * as React from 'react';
 import { Accordion as BaseAccordion } from '@base-ui/react/accordion';
 declare function AccordionRoot<Value = string>({ className, ...props }: BaseAccordion.Root.Props<Value>): React.JSX.Element;
-declare const AccordionTrigger: React.ForwardRefExoticComponent<Omit<Omit<import("@base-ui/react/accordion").AccordionTriggerProps, "ref"> & React.RefAttributes<HTMLElement>, "ref"> & {
+declare const AccordionTrigger: ({ className, children, indicator, ref, ...props }: React.ComponentPropsWithoutRef<typeof BaseAccordion.Trigger> & {
     indicator?: React.ReactNode;
-} & React.RefAttributes<HTMLElement>>;
-declare const AccordionPanel: React.ForwardRefExoticComponent<Omit<Omit<import("@base-ui/react/accordion").AccordionPanelProps, "ref"> & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+} & {
+    ref?: React.Ref<React.ComponentRef<typeof BaseAccordion.Trigger>>;
+}) => React.JSX.Element;
+declare const AccordionPanel: ({ className, children, render, ref, ...props }: React.ComponentPropsWithoutRef<typeof BaseAccordion.Panel> & {
+    ref?: React.Ref<React.ComponentRef<typeof BaseAccordion.Panel>>;
+}) => React.JSX.Element;
 export declare const Accordion: {
     Root: typeof AccordionRoot;
-    Item: React.ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react/accordion").AccordionItemProps, "ref"> & React.RefAttributes<HTMLDivElement>, "ref">, "size"> & {
-        size?: import("./sizing.js").ComponentSize;
-    } & React.RefAttributes<HTMLDivElement>>;
-    Header: React.ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react/accordion").AccordionHeaderProps, "ref"> & React.RefAttributes<HTMLHeadingElement>, "ref">, "size"> & {
-        size?: import("./sizing.js").ComponentSize;
-    } & React.RefAttributes<HTMLHeadingElement>>;
-    Trigger: React.ForwardRefExoticComponent<Omit<Omit<import("@base-ui/react/accordion").AccordionTriggerProps, "ref"> & React.RefAttributes<HTMLElement>, "ref"> & {
+    Item: ({ ref, ...props }: Omit<Omit<Omit<import("@base-ui/react/accordion").AccordionItemProps, "ref"> & React.RefAttributes<HTMLDivElement>, "ref">, "size"> & {
+        size?: import("./size.js").ComponentSize;
+    } & {
+        ref?: React.Ref<HTMLDivElement> | undefined;
+    }) => React.JSX.Element;
+    Header: ({ ref, ...props }: Omit<Omit<Omit<import("@base-ui/react/accordion").AccordionHeaderProps, "ref"> & React.RefAttributes<HTMLHeadingElement>, "ref">, "size"> & {
+        size?: import("./size.js").ComponentSize;
+    } & {
+        ref?: React.Ref<HTMLHeadingElement> | undefined;
+    }) => React.JSX.Element;
+    Trigger: ({ className, children, indicator, ref, ...props }: React.ComponentPropsWithoutRef<typeof BaseAccordion.Trigger> & {
         indicator?: React.ReactNode;
-    } & React.RefAttributes<HTMLElement>>;
-    Panel: React.ForwardRefExoticComponent<Omit<Omit<import("@base-ui/react/accordion").AccordionPanelProps, "ref"> & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+    } & {
+        ref?: React.Ref<React.ComponentRef<typeof BaseAccordion.Trigger>>;
+    }) => React.JSX.Element;
+    Panel: ({ className, children, render, ref, ...props }: React.ComponentPropsWithoutRef<typeof BaseAccordion.Panel> & {
+        ref?: React.Ref<React.ComponentRef<typeof BaseAccordion.Panel>>;
+    }) => React.JSX.Element;
 };
 export { AccordionPanel, AccordionRoot, AccordionTrigger };
-export declare const AccordionHeader: React.ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react/accordion").AccordionHeaderProps, "ref"> & React.RefAttributes<HTMLHeadingElement>, "ref">, "size"> & {
-    size?: import("./sizing.js").ComponentSize;
-} & React.RefAttributes<HTMLHeadingElement>>, AccordionItem: React.ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react/accordion").AccordionItemProps, "ref"> & React.RefAttributes<HTMLDivElement>, "ref">, "size"> & {
-    size?: import("./sizing.js").ComponentSize;
-} & React.RefAttributes<HTMLDivElement>>;
+export declare const AccordionHeader: ({ ref, ...props }: Omit<Omit<Omit<import("@base-ui/react/accordion").AccordionHeaderProps, "ref"> & React.RefAttributes<HTMLHeadingElement>, "ref">, "size"> & {
+    size?: import("./size.js").ComponentSize;
+} & {
+    ref?: React.Ref<HTMLHeadingElement> | undefined;
+}) => React.JSX.Element, AccordionItem: ({ ref, ...props }: Omit<Omit<Omit<import("@base-ui/react/accordion").AccordionItemProps, "ref"> & React.RefAttributes<HTMLDivElement>, "ref">, "size"> & {
+    size?: import("./size.js").ComponentSize;
+} & {
+    ref?: React.Ref<HTMLDivElement> | undefined;
+}) => React.JSX.Element;

package/dist/accordion.js

@@ -1,24 +1,23 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import * as React from 'react';
 import { Accordion as BaseAccordion } from '@base-ui/react/accordion';
 import { Icon } from './icon.js';
 import { skin, part } from './parts.js';
 function AccordionRoot({ className, ...props }) {
-    return (_jsx(BaseAccordion.Root, { ...props, className: skin('pui-accordion', className) }));
+    return (_jsx(BaseAccordion.Root, { ...props, className: skin('surf-accordion', className) }));
 }
-const AccordionTrigger = /* @__PURE__ */ React.forwardRef(function AccordionTrigger({ className, children, indicator, ...props }, ref) {
-    return (_jsxs(BaseAccordion.Trigger, { ...props, ref: ref, className: skin('pui-disclosure-trigger', className), children: [_jsx("span", { className: 'pui-disclosure-label', children: children }), indicator === undefined ? (_jsx(Icon, { name: 'chevron-forward', className: 'pui-disclosure-chevron' })) : (indicator)] }));
-});
-const AccordionPanel = /* @__PURE__ */ React.forwardRef(function AccordionPanel({ className, children, render, ...props }, ref) {
-    return (_jsx(BaseAccordion.Panel, { ...props, ref: ref, className: skin('pui-accordion-panel', className), render: render ??
-            ((panelProps, state) => (_jsx("div", { ...panelProps, inert: state.transitionStatus === 'ending' || undefined, "aria-hidden": state.transitionStatus === 'ending' || undefined }))), children: _jsx("div", { className: 'pui-disclosure-body', children: children }) }));
-});
+const AccordionTrigger = function AccordionTrigger({ className, children, indicator, ref, ...props }) {
+    return (_jsxs(BaseAccordion.Trigger, { ...props, ref: ref, className: skin('surf-disclosure-trigger', className), children: [_jsx("span", { className: 'surf-disclosure-label', children: children }), indicator === undefined ? (_jsx(Icon, { name: 'chevron-forward', className: 'surf-disclosure-chevron' })) : (indicator)] }));
+};
+const AccordionPanel = function AccordionPanel({ className, children, render, ref, ...props }) {
+    return (_jsx(BaseAccordion.Panel, { ...props, ref: ref, className: skin('surf-accordion-panel', className), render: render ??
+            ((panelProps, state) => (_jsx("div", { ...panelProps, inert: state.transitionStatus === 'ending' || undefined, "aria-hidden": state.transitionStatus === 'ending' || undefined }))), children: _jsx("div", { className: 'surf-disclosure-body', children: children }) }));
+};
 export const Accordion = {
     ...BaseAccordion,
     Root: AccordionRoot,
-    Item: /* @__PURE__ */ part(BaseAccordion.Item, 'pui-accordion-item'),
-    Header: /* @__PURE__ */ part(BaseAccordion.Header, 'pui-accordion-header'),
+    Item: /* @__PURE__ */ part(BaseAccordion.Item, 'surf-accordion-item'),
+    Header: /* @__PURE__ */ part(BaseAccordion.Header, 'surf-accordion-header'),
     Trigger: AccordionTrigger,
     Panel: AccordionPanel,
 };

package/dist/alert-dialog.d.ts

@@ -2,17 +2,21 @@ import * as React from 'react';
 import { type ComponentSizeAlias } from './sizing.js';
 import { AlertDialog as BaseAlertDialog } from '@base-ui/react/alert-dialog';
 import { DialogFooter, DialogHeader } from './dialog.js';
-declare const AlertDialogContent: React.ForwardRefExoticComponent<Omit<Omit<import("@base-ui/react/alert-dialog").AlertDialogPopupProps, "ref"> & React.RefAttributes<HTMLDivElement>, "ref"> & {
+declare const AlertDialogContent: ({ size, className, focusBoundaryLabel, ref, ...props }: React.ComponentPropsWithoutRef<typeof BaseAlertDialog.Popup> & {
     /** Width and density; an alert dialog is small unless set. */
     size?: ComponentSizeAlias;
     focusBoundaryLabel?: string;
-} & React.RefAttributes<HTMLDivElement>>;
+} & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => React.JSX.Element;
 export declare const AlertDialog: {
-    Content: React.ForwardRefExoticComponent<Omit<Omit<import("@base-ui/react/alert-dialog").AlertDialogPopupProps, "ref"> & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    Content: ({ size, className, focusBoundaryLabel, ref, ...props }: React.ComponentPropsWithoutRef<typeof BaseAlertDialog.Popup> & {
         /** Width and density; an alert dialog is small unless set. */
         size?: ComponentSizeAlias;
         focusBoundaryLabel?: string;
-    } & React.RefAttributes<HTMLDivElement>>;
+    } & {
+        ref?: React.Ref<HTMLDivElement>;
+    }) => React.JSX.Element;
     Header: typeof DialogHeader;
     Footer: typeof DialogFooter;
     Root: typeof BaseAlertDialog.Root;

package/dist/alert-dialog.js

@@ -1,16 +1,15 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import * as React from 'react';
 import { sizeName, skin } from './parts.js';
 import { useDialogFocusBoundary } from './dialog-focus.js';
 import { useComponentSize } from './sizing.js';
 import { AlertDialog as BaseAlertDialog } from '@base-ui/react/alert-dialog';
 import { DialogFooter, DialogHeader } from './dialog.js';
-const AlertDialogContent = /* @__PURE__ */ React.forwardRef(function AlertDialogContent({ size, className, focusBoundaryLabel = 'Continue dialog navigation', ...props }, ref) {
+const AlertDialogContent = function AlertDialogContent({ size, className, focusBoundaryLabel = 'Continue dialog navigation', ref, ...props }) {
     const scheme = useComponentSize(size);
     const portalRef = useDialogFocusBoundary(focusBoundaryLabel);
-    return (_jsxs(BaseAlertDialog.Portal, { ref: portalRef, children: [_jsx(BaseAlertDialog.Backdrop, { className: 'pui-dialog-backdrop' }), _jsx(BaseAlertDialog.Popup, { "data-ui-size": scheme, "data-size": sizeName(size), ...props, ref: ref, className: skin('pui-dialog-popup pui-dialog-content pui-confirm-content', className) })] }));
-});
+    return (_jsxs(BaseAlertDialog.Portal, { ref: portalRef, children: [_jsx(BaseAlertDialog.Backdrop, { className: 'surf-dialog-backdrop' }), _jsx(BaseAlertDialog.Popup, { "data-ui-size": scheme, "data-size": sizeName(size), ...props, ref: ref, className: skin('surf-dialog-popup surf-dialog-content surf-confirm-content', className) })] }));
+};
 export const AlertDialog = {
     ...BaseAlertDialog,
     Content: AlertDialogContent,

package/dist/app-shell.d.ts

@@ -1,4 +1,5 @@
 import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
 import { type ButtonProps } from './button.js';
 export type AppShellRootProps = React.ComponentPropsWithoutRef<'div'> & {
     layout?: 'header' | 'workspace';
@@ -13,53 +14,89 @@ export type AppShellRootProps = React.ComponentPropsWithoutRef<'div'> & {
     /** ⌘B, or Ctrl+B, toggles the sidebar unless focus is in a text field. */
     shortcut?: boolean;
 };
-export type AppShellSidebarToggleProps = Omit<ButtonProps, 'children'> & {
+export type AppShellSidebarToggleLabels = {
     /** The button's name in each state; it is also the tooltip. */
-    labels?: {
-        collapse?: string;
-        expand?: string;
-    };
+    collapse: string;
+    expand: string;
+    /** The shortcut the tooltip shows; ⌘B on Apple platforms, Ctrl+B elsewhere. */
+    shortcut: string;
+};
+export type AppShellSidebarToggleProps = Omit<ButtonProps, 'children'> & {
+    labels?: Partial<AppShellSidebarToggleLabels>;
     children?: React.ReactNode;
 };
-export declare const AppShell: {
-    Root: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
-        layout?: "header" | "workspace";
-        /** Whether the sidebar is collapsed to its rail. Pass it to control the state. */
-        collapsed?: boolean;
-        /** The starting state when the shell controls it. */
-        defaultCollapsed?: boolean;
-        onCollapsedChange?: (collapsed: boolean) => void;
-        /** A localStorage key that remembers the state across visits. A server-rendered
-         * app reads a cookie into defaultCollapsed instead, so the first paint is right. */
-        persist?: string;
-        /** ⌘B, or Ctrl+B, toggles the sidebar unless focus is in a text field. */
-        shortcut?: boolean;
-    } & React.RefAttributes<HTMLDivElement>>;
-    Header: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
-    Sidebar: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>, "ref"> & React.RefAttributes<HTMLElement>>;
-    SidebarToggle: React.ForwardRefExoticComponent<Omit<AppShellSidebarToggleProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
-    Content: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
-    Page: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
-    Footer: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
-    Label: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & React.RefAttributes<HTMLSpanElement>>;
-    Link: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, "ref">, "children"> & {
-        icon: React.ReactNode;
-        label: string;
-    } & React.RefAttributes<HTMLAnchorElement>>;
+export type AppShellBrandProps = Omit<useRender.ComponentProps<'div'>, 'ref' | 'children'> & {
+    /** The product mark, about 24px. It is decorative: the name names the brand. */
+    mark?: React.ReactNode;
+    /** The product name, on one line. A long one truncates and keeps its text in title. */
+    name: string;
+    /** An optional second line, such as the workspace. */
+    description?: React.ReactNode;
 };
-export declare const AppShellRoot: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
-    layout?: "header" | "workspace";
-    /** Whether the sidebar is collapsed to its rail. Pass it to control the state. */
-    collapsed?: boolean;
-    /** The starting state when the shell controls it. */
-    defaultCollapsed?: boolean;
-    onCollapsedChange?: (collapsed: boolean) => void;
-    /** A localStorage key that remembers the state across visits. A server-rendered
-     * app reads a cookie into defaultCollapsed instead, so the first paint is right. */
-    persist?: string;
-    /** ⌘B, or Ctrl+B, toggles the sidebar unless focus is in a text field. */
-    shortcut?: boolean;
-} & React.RefAttributes<HTMLDivElement>>, AppShellHeader: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>, AppShellSidebar: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>, "ref"> & React.RefAttributes<HTMLElement>>, AppShellSidebarToggle: React.ForwardRefExoticComponent<Omit<AppShellSidebarToggleProps, "ref"> & React.RefAttributes<HTMLButtonElement>>, AppShellContent: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>, AppShellPage: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>, AppShellFooter: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>, AppShellLabel: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & React.RefAttributes<HTMLSpanElement>>, AppShellLink: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, "ref">, "children"> & {
+export type AppShellNavProps = React.ComponentPropsWithoutRef<'nav'> & {
+    /** A visible name over the links, which also names the navigation. Without it,
+     * name the navigation with aria-label. */
+    label?: string;
+};
+export type AppShellLinkProps = Omit<useRender.ComponentProps<'a'>, 'ref' | 'children'> & {
     icon: React.ReactNode;
     label: string;
-} & React.RefAttributes<HTMLAnchorElement>>;
+};
+export declare const AppShell: {
+    Root: ({ collapsed, defaultCollapsed, onCollapsedChange, persist, shortcut, layout, className, children, ref, ...props }: AppShellRootProps & {
+        ref?: React.Ref<HTMLDivElement>;
+    }) => React.JSX.Element;
+    Header: ({ className, ref, ...props }: React.ComponentPropsWithoutRef<"div"> & {
+        ref?: React.Ref<HTMLDivElement>;
+    }) => React.JSX.Element;
+    Sidebar: ({ className, id, ref, ...props }: React.ComponentPropsWithoutRef<"aside"> & {
+        ref?: React.Ref<HTMLElement>;
+    }) => React.JSX.Element;
+    SidebarToggle: ({ labels, className, children, onClick, ref, ...props }: AppShellSidebarToggleProps & {
+        ref?: React.Ref<HTMLButtonElement>;
+    }) => React.JSX.Element;
+    Brand: ({ mark, name, description, render, className, ref, ...props }: AppShellBrandProps & {
+        ref?: React.Ref<HTMLDivElement>;
+    }) => React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+    Nav: ({ label, className, children, ref, ...props }: AppShellNavProps & {
+        ref?: React.Ref<HTMLElement>;
+    }) => React.JSX.Element;
+    Content: ({ className, ref, ...props }: React.ComponentPropsWithoutRef<"div"> & {
+        ref?: React.Ref<HTMLDivElement>;
+    }) => React.JSX.Element;
+    Page: ({ className, ref, ...props }: React.ComponentPropsWithoutRef<"div"> & {
+        ref?: React.Ref<HTMLDivElement>;
+    }) => React.JSX.Element;
+    Footer: ({ className, ref, ...props }: React.ComponentPropsWithoutRef<"div"> & {
+        ref?: React.Ref<HTMLDivElement>;
+    }) => React.JSX.Element;
+    Label: ({ className, ref, ...props }: React.ComponentPropsWithoutRef<"span"> & {
+        ref?: React.Ref<HTMLSpanElement>;
+    }) => React.JSX.Element;
+    Link: ({ icon, label, render, className, ref, ...props }: AppShellLinkProps & {
+        ref?: React.Ref<HTMLAnchorElement>;
+    }) => React.JSX.Element;
+};
+export declare const AppShellRoot: ({ collapsed, defaultCollapsed, onCollapsedChange, persist, shortcut, layout, className, children, ref, ...props }: AppShellRootProps & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => React.JSX.Element, AppShellHeader: ({ className, ref, ...props }: React.ComponentPropsWithoutRef<"div"> & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => React.JSX.Element, AppShellSidebar: ({ className, id, ref, ...props }: React.ComponentPropsWithoutRef<"aside"> & {
+    ref?: React.Ref<HTMLElement>;
+}) => React.JSX.Element, AppShellSidebarToggle: ({ labels, className, children, onClick, ref, ...props }: AppShellSidebarToggleProps & {
+    ref?: React.Ref<HTMLButtonElement>;
+}) => React.JSX.Element, AppShellBrand: ({ mark, name, description, render, className, ref, ...props }: AppShellBrandProps & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => React.ReactElement<unknown, string | React.JSXElementConstructor<any>>, AppShellNav: ({ label, className, children, ref, ...props }: AppShellNavProps & {
+    ref?: React.Ref<HTMLElement>;
+}) => React.JSX.Element, AppShellContent: ({ className, ref, ...props }: React.ComponentPropsWithoutRef<"div"> & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => React.JSX.Element, AppShellPage: ({ className, ref, ...props }: React.ComponentPropsWithoutRef<"div"> & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => React.JSX.Element, AppShellFooter: ({ className, ref, ...props }: React.ComponentPropsWithoutRef<"div"> & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => React.JSX.Element, AppShellLabel: ({ className, ref, ...props }: React.ComponentPropsWithoutRef<"span"> & {
+    ref?: React.Ref<HTMLSpanElement>;
+}) => React.JSX.Element, AppShellLink: ({ icon, label, render, className, ref, ...props }: AppShellLinkProps & {
+    ref?: React.Ref<HTMLAnchorElement>;
+}) => React.JSX.Element;

package/dist/app-shell.js

@@ -1,6 +1,7 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
 import { cx, skin } from './parts.js';
 import { Button } from './button.js';
 import { Icon } from './icon.js';
@@ -15,7 +16,7 @@ const apple = () => typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(n
 const shortcutLabel = () => (apple() ? '⌘B' : 'Ctrl+B');
 /** Layout only. Routing, session, theme and mobile disclosure belong to the caller;
  * the shell keeps the sidebar's collapsed state unless you control it. */
-const Root = /* @__PURE__ */ React.forwardRef(function AppShellRoot({ collapsed, defaultCollapsed = false, onCollapsedChange, persist, shortcut = true, layout = 'header', className, children, ...props }, ref) {
+const Root = function AppShellRoot({ collapsed, defaultCollapsed = false, onCollapsedChange, persist, shortcut = true, layout = 'header', className, children, ref, ...props }) {
     const [own, setOwn] = React.useState(defaultCollapsed);
     const value = collapsed ?? own;
     const latest = React.useRef(value);
@@ -58,56 +59,93 @@ const Root = /* @__PURE__ */ React.forwardRef(function AppShellRoot({ collapsed,
     }, [shortcut, setCollapsed]);
     const sidebarId = React.useId();
     const shell = React.useMemo(() => ({ collapsed: value, setCollapsed, sidebarId, shortcut }), [value, setCollapsed, sidebarId, shortcut]);
-    return (_jsx(ShellContext.Provider, { value: shell, children: _jsx("div", { ...props, ref: ref, "data-layout": layout, "data-sidebar": value ? 'collapsed' : 'expanded', className: cx('pui-app-shell', className), children: children }) }));
-});
+    return (_jsx(ShellContext.Provider, { value: shell, children: _jsx("div", { ...props, ref: ref, "data-layout": layout, "data-sidebar": value ? 'collapsed' : 'expanded', className: cx('surf-app-shell', className), children: children }) }));
+};
 /** Collapses the sidebar to its rail and back. Its tooltip names the shortcut. */
-const SidebarToggle = /* @__PURE__ */ React.forwardRef(function AppShellSidebarToggle({ labels, className, children, onClick, ...props }, ref) {
+const SidebarToggle = function AppShellSidebarToggle({ labels, className, children, onClick, ref, ...props }) {
     const shell = React.useContext(ShellContext);
     if (!shell)
         throw new Error('AppShell.SidebarToggle belongs in AppShell.Root');
     const label = shell.collapsed
         ? (labels?.expand ?? 'Expand sidebar')
         : (labels?.collapse ?? 'Collapse sidebar');
-    return (_jsx(Tooltip, { label: label, shortcut: shell.shortcut ? shortcutLabel() : undefined, children: _jsx(Button, { variant: 'ghost', size: 'icon', ...props, ref: ref, "aria-label": label, "aria-expanded": !shell.collapsed, "aria-controls": shell.sidebarId, className: skin('pui-app-shell-toggle', className), onClick: (event) => {
+    return (_jsx(Tooltip, { label: label, shortcut: shell.shortcut ? (labels?.shortcut ?? shortcutLabel()) : undefined, children: _jsx(Button, { variant: 'ghost', size: 'icon', ...props, ref: ref, "aria-label": label, "aria-expanded": !shell.collapsed, "aria-controls": shell.sidebarId, className: skin('surf-app-shell-toggle', className), onClick: (event) => {
                 onClick?.(event);
                 if (!event.defaultPrevented)
                     shell.setCollapsed(!shell.collapsed);
             }, children: children ?? _jsx(Icon, { name: 'sidebar' }) }) }));
-});
-const Header = /* @__PURE__ */ React.forwardRef(function AppShellHeader({ className, ...props }, ref) {
-    return (_jsx("div", { ...props, ref: ref, className: cx('pui-app-shell-header', className) }));
-});
-const Sidebar = /* @__PURE__ */ React.forwardRef(function AppShellSidebar({ className, id, ...props }, ref) {
+};
+const Header = function AppShellHeader({ className, ref, ...props }) {
+    return (_jsx("div", { ...props, ref: ref, className: cx('surf-app-shell-header', className) }));
+};
+const Sidebar = function AppShellSidebar({ className, id, ref, ...props }) {
     const shell = React.useContext(ShellContext);
-    return (_jsx(SidebarContext.Provider, { value: true, children: _jsx("aside", { ...props, ref: ref, id: id ?? shell?.sidebarId, className: cx('pui-app-shell-sidebar', className) }) }));
-});
-const Content = /* @__PURE__ */ React.forwardRef(function AppShellContent({ className, ...props }, ref) {
-    return (_jsx("div", { ...props, ref: ref, className: cx('pui-app-shell-content', className) }));
-});
+    return (_jsx(SidebarContext.Provider, { value: true, children: _jsx("aside", { ...props, ref: ref, id: id ?? shell?.sidebarId, className: cx('surf-app-shell-sidebar', className) }) }));
+};
+const Content = function AppShellContent({ className, ref, ...props }) {
+    return (_jsx("div", { ...props, ref: ref, className: cx('surf-app-shell-content', className) }));
+};
 /**
  * The page surface inside a workspace Content. It insets from the shell on every
  * side but the sidebar's; without the sidebar, on narrow screens, it insets evenly.
  */
-const Page = /* @__PURE__ */ React.forwardRef(function AppShellPage({ className, ...props }, ref) {
-    return (_jsx("div", { ...props, ref: ref, className: cx('pui-app-shell-page', className) }));
-});
-const Footer = /* @__PURE__ */ React.forwardRef(function AppShellFooter({ className, ...props }, ref) {
-    return (_jsx("div", { ...props, ref: ref, className: cx('pui-app-shell-footer', className) }));
-});
-const Label = /* @__PURE__ */ React.forwardRef(function AppShellLabel({ className, ...props }, ref) {
-    return (_jsx("span", { ...props, ref: ref, className: cx('pui-app-shell-label', className) }));
-});
-const Link = /* @__PURE__ */ React.forwardRef(function AppShellLink({ icon, label, className, ...props }, ref) {
+const Page = function AppShellPage({ className, ref, ...props }) {
+    return (_jsx("div", { ...props, ref: ref, className: cx('surf-app-shell-page', className) }));
+};
+const Footer = function AppShellFooter({ className, ref, ...props }) {
+    return (_jsx("div", { ...props, ref: ref, className: cx('surf-app-shell-footer', className) }));
+};
+const Label = function AppShellLabel({ className, ref, ...props }) {
+    return (_jsx("span", { ...props, ref: ref, className: cx('surf-app-shell-label', className) }));
+};
+/** The product's mark and name. In the sidebar it is the top row, its mark centered
+ * on the links' icons; in the header it sits on one line. Pass `render`, such as
+ * `<a href='/' />`, to make it a link home. */
+const Brand = function AppShellBrand({ mark, name, description, render, className, ref, ...props }) {
+    return useRender({
+        defaultTagName: 'div',
+        render,
+        ref,
+        props: {
+            ...props,
+            className: cx('surf-app-shell-brand', className),
+            children: (_jsxs(_Fragment, { children: [mark != null && (_jsx("span", { className: 'surf-app-shell-brand-mark', "aria-hidden": 'true', children: mark })), _jsxs("span", { className: 'surf-app-shell-label surf-app-shell-brand-text', children: [_jsx("span", { className: 'surf-app-shell-brand-name', title: name, children: name }), description != null && (_jsx("span", { className: 'surf-app-shell-brand-description', children: description }))] })] })),
+        },
+    });
+};
+/** A list of Links with even gaps. In the workspace sidebar it lines its links up
+ * with the brand and the rail. */
+const Nav = function AppShellNav({ label, className, children, ref, ...props }) {
+    const id = React.useId();
+    return (_jsxs("nav", { "aria-labelledby": label ? id : undefined, ...props, ref: ref, className: cx('surf-app-shell-nav', className), children: [label && (_jsx("span", { id: id, className: 'surf-app-shell-nav-label', children: _jsx(Label, { children: label }) })), children] }));
+};
+/** A destination with an icon and a name. Pass a router's link as `render` to keep
+ * client navigation, or another element, such as a menu trigger for the account, to
+ * give it the same row. */
+const Link = function AppShellLink({ icon, label, render, className, ref, ...props }) {
     const shell = React.useContext(ShellContext);
     const inSidebar = React.useContext(SidebarContext);
+    const element = useRender({
+        defaultTagName: 'a',
+        render,
+        ref,
+        props: {
+            ...props,
+            'aria-label': props['aria-label'] ?? label,
+            className: cx('surf-app-shell-link', className),
+            children: (_jsxs(_Fragment, { children: [_jsx("span", { className: 'surf-app-shell-icon', "aria-hidden": 'true', children: icon }), _jsx(Label, { "aria-hidden": 'true', children: label })] })),
+        },
+    });
     // On the collapsed rail only the icon shows, so the name appears as a tooltip.
-    return (_jsx(Tooltip, { label: label, enabled: Boolean(shell?.collapsed && inSidebar), children: _jsxs("a", { ...props, ref: ref, "aria-label": props['aria-label'] ?? label, className: cx('pui-app-shell-link', className), children: [_jsx("span", { className: 'pui-app-shell-icon', "aria-hidden": 'true', children: icon }), _jsx(Label, { "aria-hidden": 'true', children: label })] }) }));
-});
+    return (_jsx(Tooltip, { label: label, disabled: !(shell?.collapsed && inSidebar), children: element }));
+};
 export const AppShell = {
     Root,
     Header,
     Sidebar,
     SidebarToggle,
+    Brand,
+    Nav,
     Content,
     Page,
     Footer,
@@ -115,4 +153,4 @@ export const AppShell = {
     Link,
 };
 // Flat names for React Server Components, which cannot dot into client exports.
-export const { Root: AppShellRoot, Header: AppShellHeader, Sidebar: AppShellSidebar, SidebarToggle: AppShellSidebarToggle, Content: AppShellContent, Page: AppShellPage, Footer: AppShellFooter, Label: AppShellLabel, Link: AppShellLink, } = AppShell;
+export const { Root: AppShellRoot, Header: AppShellHeader, Sidebar: AppShellSidebar, SidebarToggle: AppShellSidebarToggle, Brand: AppShellBrand, Nav: AppShellNav, Content: AppShellContent, Page: AppShellPage, Footer: AppShellFooter, Label: AppShellLabel, Link: AppShellLink, } = AppShell;