@photon-ai/pho-ui 2.2.0 → 2.4.0

package/dist/src/sections/basic-page/basic-page.d.ts

@@ -1,5 +1,6 @@
 import { AnchorHTMLAttributes, ComponentProps, ReactNode, Ref } from 'react';
-import { ButtonLinkProps } from '../../components/button';
+import { ButtonLinkProps, ButtonProps } from '../../components/button';
+import { Form as FormElement } from '../../components/form';
 /** Bordered card that stacks rows with hairline dividers. */
 export declare const BASIC_PAGE_CARD = "rounded-base border border-pho-secondary bg-pho-primary divide-y divide-pho-secondary [&>:has(+[data-basic-page-alert])]:border-b-0";
 /**
@@ -59,9 +60,78 @@ export declare const BASIC_PAGE_ITEM_PANEL_DIVIDED = "-mx-2 -mt-1.5 flex items-c
  * `Title` and `Back` (the page chrome) stay put while the body below rises
  * in.
  */
-declare function Root({ className, ...props }: ComponentProps<"div"> & {
+export interface BasicPageRootProps extends ComponentProps<"div"> {
     ref?: Ref<HTMLDivElement>;
+    /**
+     * Condense on scroll — on by default. Once the title has scrolled out of
+     * the pane, a sticky bar pins to the top with the way back and the page
+     * name: the large title collapsing into its bar. It assembles itself
+     * from `Title` and the trail's tail crumb; nothing to wire. Pass `false`
+     * for a page that should scroll away whole.
+     */
+    condense?: boolean;
+}
+declare function Root({ condense, className, children, ...props }: BasicPageRootProps): import("react").JSX.Element;
+/**
+ * Condensing header — the page's way back once the title has scrolled away.
+ * `Root condense` renders a sticky bar in the reserved top zone; `Title` and
+ * `Breadcrumbs` report what belongs in it (the heading, the tail crumb)
+ * through this context, so the bar assembles itself and consumers only set
+ * the flag. The bar stays out of the way until the whole heading has left
+ * the scrollport, then fades in pinned to the top.
+ */
+interface CondenseTail {
+    label: ReactNode;
+    href: string;
+    onClick?: ComponentProps<"a">["onClick"];
+}
+/**
+ * What the condensed bar would show, for an app shell that shows it
+ * itself: whether the title has left the pane, the page name, the way
+ * back. Idle (`condensed: false`, both null) outside any `CondenseScope`.
+ */
+export interface BasicPageCondense {
+    condensed: boolean;
+    title: ReactNode | null;
+    back: CondenseTail | null;
+}
+/**
+ * Hands the condensed bar to the app shell. On a narrow viewport the shell
+ * already has a bar of its own; two stacked bars is one too many. Wrap the
+ * shell (its bar and the routed pages) in `CondenseScope` and read
+ * `useCondense()` where the bar is: while `condensed`, show `title` in the
+ * middle and `back` as a plain chevron beside the menu button. While
+ * `adopt` is true the page renders no bar of its own; pass `adopt={false}`
+ * on viewports where the shell bar does not exist (desktop) and the page's
+ * bar returns. State still tracks either way — `useCondense()` always
+ * answers.
+ */
+declare function CondenseScope({ adopt, children, }: {
+    adopt?: boolean;
+    children?: ReactNode;
 }): import("react").JSX.Element;
+/** The nearest scope's condense state — see `CondenseScope`. */
+export declare function useCondense(): BasicPageCondense;
+/**
+ * The condensed bar's motion, exported for a shell that adopts the bar
+ * (`CondenseScope`) so its swap moves the same way: 0.2s ease-out, dropping
+ * in from 8px above and leaving the same way.
+ */
+export declare const CONDENSE_BAR_ENTER: {
+    readonly duration: 0.2;
+    readonly ease: "easeOut";
+};
+/**
+ * The displacement channel of the same move: travel is linear, like the
+ * library's other linear transitions (the 100ms control inks), while the
+ * fade and the soft focus keep the ease-out. Spread it per axis:
+ * `transition={{ ...CONDENSE_BAR_ENTER, y: CONDENSE_BAR_TRAVEL }}`.
+ */
+export declare const CONDENSE_BAR_TRAVEL: {
+    readonly duration: 0.2;
+    readonly ease: "linear";
+};
+export declare const CONDENSE_BAR_RISE_PX = -8;
 export interface BasicPageTitleProps extends ComponentProps<"h1"> {
     /**
      * Shared-element key. Pair with the same `morphId` on the subpage's
@@ -113,7 +183,7 @@ export interface BasicPageStackProps extends Omit<ComponentProps<"div">, RevealM
  *
  * Static under reduced motion.
  */
-declare function Stack({ className, ...props }: BasicPageStackProps): import("react").JSX.Element;
+declare function Stack({ className, children, ...props }: BasicPageStackProps): import("react").JSX.Element;
 /**
  * Title + optional description pair. No gap between them — the block's
  * `gap-3` only applies between this header and the card.
@@ -178,7 +248,7 @@ declare function Card({ animateHeight, className, children, ...props }: BasicPag
  * </BasicPage.Card>
  * ```
  */
-declare function Item({ className, ...props }: ComponentProps<"div"> & {
+declare function Item({ className, ...props }: Omit<ComponentProps<"div">, RevealMotionConflicts> & {
     ref?: Ref<HTMLDivElement>;
 }): import("react").JSX.Element;
 export interface BasicPageItemPanelProps extends ComponentProps<"div"> {
@@ -222,7 +292,7 @@ declare function CalloutTitle({ id, className, children, ...props }: ComponentPr
 declare function CalloutDescription({ className, ...props }: ComponentProps<"p"> & {
     ref?: Ref<HTMLParagraphElement>;
 }): import("react").JSX.Element;
-export interface BasicPageRowProps extends Omit<ComponentProps<"div">, "title"> {
+export interface BasicPageRowProps extends Omit<ComponentProps<"div">, "title" | RevealMotionConflicts> {
     /** Left-side field name — plain text, or compose with a trailing hint. */
     label: ReactNode;
     /** Optional helper under the label. */
@@ -272,23 +342,117 @@ export interface BasicPageAlertProps extends Omit<ComponentProps<"div">, "childr
  * For a page that failed to load outright, swap the stack for an `ErrorView`
  * instead.
  */
-declare function Alert({ error, show, className, children, ...props }: BasicPageAlertProps): import("react").JSX.Element;
+declare function Alert({ error: errorProp, show, className, children, ...props }: BasicPageAlertProps): import("react").JSX.Element;
+/**
+ * The nearest `Form autoSave`'s trigger, for controls whose changes never
+ * bubble as native events (a Base UI checkbox, a select): call it in the
+ * control's own onChange and the save runs after the usual pause. Null
+ * outside an auto-saving form.
+ */
+export declare function useAutoSave(): ((field?: string) => void) | null;
+/** Typing pause before an auto-save fires; blur flushes it immediately. */
+export declare const AUTO_SAVE_DELAY_MS = 800;
+/**
+ * The toast lane auto-save failures speak through. Host it once in the app
+ * shell — `<Toast.Provider toastManager={formToasts}>` around a viewport —
+ * and every `Form autoSave` reaches it without wiring. A failure toast
+ * carries Retry and stays until the save lands (the next success closes it).
+ */
+export declare const formToasts: import('@base-ui/react').ToastManager<any>;
+/** Field errors keyed by `name`, the shape Base UI `Form` maps onto fields. */
+export type BasicPageFormErrors = Record<string, string | string[]>;
+export interface BasicPageFormProps<Values extends Record<string, unknown> = Record<string, unknown>> extends Omit<ComponentProps<typeof FormElement>, "onFormSubmit" | "errors" | "action" | "autoSave"> {
+    /**
+     * Documents save themselves; transactions submit. With `autoSave`, the
+     * form runs `action` on its own — after a typing pause, immediately on
+     * blur — once native validation passes, and skips quietly while it does
+     * not. Controls stay enabled throughout; put a `Saved` in the field's
+     * hint for the inline Saving…/Saved word. A failure keeps the value in
+     * place and raises a Retry toast on `formToasts` that stays until a
+     * save lands. Keep the explicit `Submit` for creations and anything
+     * paid or irreversible.
+     */
+    autoSave?: boolean;
+    /**
+     * The save. Receives the field values keyed by `name`, after native
+     * validation passed. Resolve to finish; return `{ errors }` to put
+     * messages on fields; throw (a `Problem`, an `Error`) for the form's
+     * `Alert`. While it runs, every control and the submit are disabled.
+     */
+    action?: (values: Values) => void | {
+        errors?: BasicPageFormErrors;
+    } | Promise<void | {
+        errors?: BasicPageFormErrors;
+    }>;
+    /** Field errors to start with — from a previous round trip. */
+    errors?: BasicPageFormErrors;
+}
+/**
+ * The form. A `<form>` that owns the save lifecycle so the page parts can
+ * read it: `Submit` shows pending, `Footer show="dirty"` appears after the
+ * first edit and leaves when the action lands, `Alert` shows what the
+ * action threw, and field errors the action returns land under their
+ * fields. Uncontrolled by design — give fields `defaultValue` and a `name`,
+ * and remount with `key` when the record changes; there is no state to
+ * seed. Lay the fields out in `Fields` (the form card, its `Footer` inside
+ * at the bottom), or keep a `Card` of `Row`s for a settings page that
+ * saves, its `Footer` following the card one block gap below.
+ *
+ * The form adds no spacing. Inside a `Stack`, one form around a card and
+ * its footer is one block; a form that spans several blocks goes around
+ * the `Stack` instead, and the blocks keep the Stack's rhythm.
+ */
+declare function Form<Values extends Record<string, unknown>>({ action, errors: initialErrors, autoSave, className, children, onChange, onBlur, ...props }: BasicPageFormProps<Values>): import("react").JSX.Element;
+/**
+ * The inline word for an auto-saving field — put it inside the field at
+ * its trailing edge (`Input trailing`), where the eye already is while
+ * typing. Quiet gray, never colored, so it cannot be read as validation:
+ * "Saving…" while the save runs, "Saved" for a breath after it lands,
+ * then nothing at all — idle it renders nothing and reserves nothing.
+ * Words fade through the system's 1px soft focus — no travel — and
+ * carry their own surface wash, so long
+ * input text fades beneath them instead of colliding. With `name` it
+ * speaks only for that field; without, for the whole form.
+ */
+declare function Saved({ name, className, ...props }: Omit<ComponentProps<"output">, RevealMotionConflicts> & {
+    name?: string;
+}): import("react").JSX.Element;
+/**
+ * The form card: labelled fields stacked, label above control, one rhythm
+ * (`gap-5`). Where a `Card` of `Row`s is a table of settings, this is a
+ * sheet to fill in — a create page, a long edit. `Input` brings its own
+ * label and hint; wrap other controls in `Field`. `Alert` and `Footer`
+ * sit inside, at the bottom — unlike a `Card` of rows, a sheet keeps its
+ * submit: the button's box lines up with the fields' edge.
+ */
+declare function Fields({ className, ...props }: ComponentProps<"div"> & {
+    ref?: Ref<HTMLDivElement>;
+}): import("react").JSX.Element;
+/** Fields side by side from `sm` (a first and last name), stacked below. */
+declare function Inline({ className, ...props }: ComponentProps<"div"> & {
+    ref?: Ref<HTMLDivElement>;
+}): import("react").JSX.Element;
+/** The submit. A small effect `Button`, pending while the action runs. */
+declare function Submit({ children, ...props }: Omit<ButtonProps, "type">): import("react").JSX.Element;
 export interface BasicPageFooterProps extends ComponentProps<"div"> {
     /**
-     * Animated presence for dirty-state bars: the card glides open/closed on a
-     * height spring while the content fades. Omit for a static, always-visible
-     * footer (no animation). No reveal plays on first mount — only on flips.
+     * Animated presence for the dirty-state action: the card glides
+     * open/closed on a height spring while the button fades. Omit for a
+     * static, always-visible footer (no animation). No reveal plays on first
+     * mount — only on flips.
      */
-    show?: boolean;
+    show?: boolean | "dirty";
     ref?: Ref<HTMLDivElement>;
 }
 /**
- * Trailing bar inside a card — typically a save status + submit button that
- * appears after the form is dirty. Same horizontal/vertical padding as a row.
- * Pass `show` (instead of conditional rendering) to animate the bar in and
- * out following the onboarding card's motion language.
+ * Save action for a card. After a `Card` of rows it sits outside, below the
+ * surface, its trailing edge on the rows' text edge, so the card
+ * holds only rows; inside `Fields` it sits at the bottom of the sheet.
+ * Typically a submit button that appears after the form is dirty; pass
+ * `show` (instead of conditional rendering) to animate it in and out
+ * following the onboarding card's motion language.
  */
-declare function Footer({ show, className, ...props }: BasicPageFooterProps): import("react").JSX.Element;
+declare function Footer({ show: showProp, className, ...props }: BasicPageFooterProps): import("react").JSX.Element;
 /**
  * DOM handlers whose React signatures clash with Motion's gesture props of
  * the same name on `motion.*` elements — excluded from `Reveal`'s public API
@@ -304,12 +468,19 @@ export interface BasicPageRevealProps extends Omit<ComponentProps<"div">, Reveal
      * the one-shot data-arrival entrance.
      */
     show?: boolean;
+    /**
+     * Clip the block while its height animates (the default). Pass `false`
+     * for a block whose content must show whole from the first frame — a
+     * button with a rim, a shadow — and let it fade in as the space opens.
+     */
+    clip?: boolean;
     /**
      * Which gap the presence variant compensates while collapsing —
-     * `"stack"` for a Stack block (`gap-10`), `"block"` for an element
+     * `"stack"` for a Stack block (`gap-10`), `"fields"` for a field in a
+     * `Fields` sheet (`gap-5`), `"block"` for an element
      * inside a block (`gap-3`). @default "stack"
      */
-    gap?: "stack" | "block";
+    gap?: "stack" | "block" | "fields";
     /**
      * Set when this wraps multiple `Card` rows — the extra element Reveal
      * needs for `AnimatePresence` sits between them and the card's own
@@ -334,7 +505,7 @@ export interface BasicPageRevealProps extends Omit<ComponentProps<"div">, Reveal
  * `Footer` grammar): a whole section of the Stack that appears or leaves at
  * runtime glides open/closed while its neighbours follow.
  */
-declare function Reveal({ show, gap, dividers, className, ...props }: BasicPageRevealProps): import("react").JSX.Element;
+declare function Reveal({ show, clip, gap, dividers, className, ...props }: BasicPageRevealProps): import("react").JSX.Element;
 export interface BasicPageBreadcrumbsProps extends ComponentProps<"nav"> {
     /** `Crumb`s, root-most first; the last one is the immediate parent. */
     children: ReactNode;
@@ -342,23 +513,26 @@ export interface BasicPageBreadcrumbsProps extends ComponentProps<"nav"> {
 /**
  * The trail above the title — where this page sits, root-most crumb first,
  * ending with the immediate parent; the current page is the `Title` below.
- * Place inside `Root`, before `Title`. It floats in `Root`'s reserved top
- * padding (vertically centered in the 64px zone) instead of taking layout
- * space, so `Title` sits at the same position whether or not a page has
- * one.
+ * Place inside `Root`, before `Title`. It floats in the page's top-left
+ * corner instead of taking layout space, and the column reserves a 64px
+ * top zone for it, so `Title` sits at the same position whether or not a
+ * page has one.
  *
  * One form at every depth: `‹ parent / parent / parent` — the chevron opens
  * the trail (it is the way up), slashes separate the crumbs (they are the
  * path), one crumb or many. Below `sm` the path collapses to `‹ parent` —
  * the last crumb alone. Crumbs render through the host's `LinkProvider`.
  *
- * The offsets align the first *label* glyph with the title glyph. Title
- * text sits 40px in (`px-5` root gutter + `px-5` title pad); inside a `sm`
- * ghost button the label sits 29.75px in (8px icon-side pad + 15.75px
- * chevron, 1.125em at the 14px `text-base`, + 4px gap + 2px label-span
- * `px-0.5`) — so `left` is the 10.25px difference. `top-4` centers the 32px
- * buttons in the 64px reserved zone. The chevron and the ghost hover pills
- * hang in the padding — the usual optical alignment for borderless controls.
+ * Four crumbs or more, the middle folds: `‹ root / … / parent / parent`,
+ * with the folded pages behind the ellipsis as a menu. The trail keeps a
+ * width ceiling at any depth, and the fold never touches the tail, so the
+ * title morph is unaffected.
+ *
+ * It sits in the page's top-left corner — `top-4 left-3`, the chevron ink
+ * 20px from the edge, the column gutter's width — as chrome of the pane,
+ * not of the column: on a wide pane it stays at the corner while the
+ * column centers. `top-4` centers the 32px buttons in the 64px reserved
+ * zone; the ghost hover pills hang in the corner padding.
  *
  * Motion between pages: the tail crumb is the morph partner of the child
  * page's `Title` (pair their `morphId`s); everything before it holds still.
@@ -393,7 +567,7 @@ export type BasicPageBackProps = BasicPageCrumbProps;
  * path with `Breadcrumbs` + `Crumb` instead.
  */
 declare function Back({ className, ...props }: BasicPageBackProps): import("react").JSX.Element;
-export interface BasicPageRowLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "title"> {
+export interface BasicPageRowLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "title" | RevealMotionConflicts> {
     /** Left-side field name — plain text, or compose with a trailing badge. */
     label: ReactNode;
     /** Optional helper under the label. */
@@ -473,6 +647,7 @@ declare function RowLink({ label, description, leading, href, className, childre
  */
 export declare const BasicPage: {
     Root: typeof Root;
+    CondenseScope: typeof CondenseScope;
     Breadcrumbs: typeof Breadcrumbs;
     Crumb: typeof Crumb;
     Back: typeof Back;
@@ -493,6 +668,11 @@ export declare const BasicPage: {
     Value: typeof Value;
     Alert: typeof Alert;
     Footer: typeof Footer;
+    Form: typeof Form;
+    Saved: typeof Saved;
+    Fields: typeof Fields;
+    Inline: typeof Inline;
+    Submit: typeof Submit;
     Reveal: typeof Reveal;
 };
 export {};

package/dist/src/sections/basic-page/index.d.ts

@@ -1 +1 @@
-export { BasicPage, BASIC_PAGE_CARD, BASIC_PAGE_CALLOUT, BASIC_PAGE_ROW, BASIC_PAGE_ITEM, BASIC_PAGE_ITEM_PANEL, BASIC_PAGE_ITEM_PANEL_DIVIDED, type BasicPageRowProps, type BasicPageRowLinkProps, type BasicPageBackProps, type BasicPageBreadcrumbsProps, type BasicPageCrumbProps, type BasicPageFooterProps, type BasicPageItemPanelProps, } from './basic-page';
+export { BasicPage, formToasts, AUTO_SAVE_DELAY_MS, useCondense, useAutoSave, type BasicPageCondense, BASIC_PAGE_CARD, CONDENSE_BAR_ENTER, CONDENSE_BAR_TRAVEL, CONDENSE_BAR_RISE_PX, BASIC_PAGE_CALLOUT, BASIC_PAGE_ROW, BASIC_PAGE_ITEM, BASIC_PAGE_ITEM_PANEL, BASIC_PAGE_ITEM_PANEL_DIVIDED, type BasicPageRootProps, type BasicPageRowProps, type BasicPageRowLinkProps, type BasicPageBackProps, type BasicPageBreadcrumbsProps, type BasicPageCrumbProps, type BasicPageFooterProps, type BasicPageFormProps, type BasicPageFormErrors, type BasicPageItemPanelProps, } from './basic-page';

package/dist/src/sections/sidebar/sidebar.d.ts

@@ -1,4 +1,5 @@
 import { AnchorHTMLAttributes, ButtonHTMLAttributes, ComponentProps, FC, ReactNode, Ref } from 'react';
+import { Button } from '../../components/button';
 /**
  * Sidebar — Pho's first SECTION: a composed app rail, not a micro component.
  * It encodes the navigation rail used across Photon surfaces (the Pho docs
@@ -52,9 +53,37 @@ interface RootProps extends ComponentProps<"aside"> {
 declare function Root({ className, inset, ...props }: RootProps): import("react").JSX.Element;
 /** Brand slot at the top of the rail — logo, wordmark, workspace switcher. */
 declare function Header({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
-/** The scrollable middle — a stack of `Sidebar.Group`s. */
-declare function Nav({ className, ...props }: ComponentProps<"nav">): import("react").JSX.Element;
-/** One titled cluster of nav rows: a `GroupLabel` followed by a `List`. */
+/**
+ * The rail's search row — an outlined button dressed to `Item` metrics so
+ * its label lines up with the rows below, the shortcut at the trailing
+ * edge. The press is the Button's own; wire `onClick` (and a global ⌘K)
+ * to a `Command.Dialog`.
+ */
+declare function Search({ label, kbd, className, ...props }: Omit<ComponentProps<typeof Button>, "children" | "variant" | "size"> & {
+    label?: ReactNode;
+    kbd?: string;
+}): import("react").JSX.Element;
+/**
+ * The scrollable middle — a stack of `Sidebar.Group`s in a `ScrollArea`
+ * (overlay scrollbar, edge fade). Pass `scroll={false}` where a parent
+ * scrolls the whole rail as one column (a narrow-viewport drawer) — the
+ * nav is then a plain stack at its natural height.
+ *
+ * The nav owns its breathing room toward its neighbors as a resting inset
+ * (a scroll view's safe-area padding): 24px above, 16px below by default —
+ * rows stand clear of the ends at rest and scroll through the gap, under
+ * the edge fade, instead of clipping at a dead margin. `inset` /
+ * `insetTop` / `insetBottom` override it; the same values become plain
+ * padding when `scroll={false}`, so both modes keep one geometry. A
+ * `Header` right before the nav and a `Footer` after it drop their own
+ * margins — the gap lives here, not on the neighbors.
+ */
+declare function Nav({ scroll, inset, insetTop, insetBottom, className, style, children, ...props }: ComponentProps<"nav"> & {
+    scroll?: boolean;
+    inset?: number | string;
+    insetTop?: number | string;
+    insetBottom?: number | string;
+}): import("react").JSX.Element;
 declare function Group({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
 /** The cluster's caption — description ink, regular weight. */
 declare function GroupLabel({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
@@ -151,6 +180,7 @@ declare function AccountRow({ name, avatarSrc, initials, className, ...props }:
 export declare const Sidebar: {
     Root: typeof Root;
     Header: typeof Header;
+    Search: typeof Search;
     Nav: typeof Nav;
     Group: typeof Group;
     GroupLabel: typeof GroupLabel;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photon-ai/pho-ui",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Pho Design System — Photon's React component library, built on Base UI",
   "license": "UNLICENSED",
   "repository": {

package/src/styles/pho.css

@@ -36,6 +36,25 @@
   }
 }
 
+@layer base {
+  /* Each block surface registers itself, so anything that needs to fade
+     into "the background it sits on" (a scroll area's edge wash) reads
+     `--pho-surface` and inherits the nearest surface ancestor's color —
+     live across themes, no wiring. */
+  .bg-pho-page {
+    --pho-surface: var(--background-color-pho-page);
+  }
+  .bg-pho-primary {
+    --pho-surface: var(--background-color-pho-primary);
+  }
+  .bg-pho-secondary {
+    --pho-surface: var(--background-color-pho-secondary);
+  }
+  .bg-pho-inverse {
+    --pho-surface: var(--background-color-pho-inverse);
+  }
+}
+
 /* True squircle corners (progressive enhancement; falls back to border-radius
    where `corner-shape` is unsupported). Pair with a `rounded-*` utility. */
 @utility squircle {