@photon-ai/pho-ui 2.3.0 → 2.4.0

package/dist/index.js

@@ -1,73 +1,80 @@
 "use client";
-import { t as s } from "./chunks/cn-ChIgwEl3.js";
-import { n as r, r as o, t as E } from "./chunks/link-provider-9TFNyDqO.js";
-import { t as i } from "./chunks/resolve-variant-CcD8iG5l.js";
-import { n as I, r as n, t as A } from "./chunks/use-press-pulse-8iorQPsh.js";
+import { t as a } from "./chunks/cn-ChIgwEl3.js";
+import { n as r, r as E, t as o } from "./chunks/link-provider-9TFNyDqO.js";
+import { t as S } from "./chunks/resolve-variant-CcD8iG5l.js";
+import { n as A, r as T, t as I } from "./chunks/use-press-pulse-8iorQPsh.js";
 import "./utils.js";
-import { a as e, c as R, d as p, i as B, l as C, n as O, o as P, r as f, s as u, t as D, u as N } from "./chunks/button-DNNs5RsT.js";
-import { a as c, c as l, i as V, l as U, n as G, o as d, r as M, s as b, t as g } from "./chunks/error-Crs-wqMC.js";
-import { a as F, i as W, n as h, o as Z, r as v, s as w, t as x } from "./chunks/basic-page-BkLG3Ybg.js";
-import { a as z, c as Y, i as j, n as q, o as y, r as J, s as K, t as Q } from "./chunks/sidebar-Dt1F_CEP.js";
-import { t as $ } from "./chunks/input-CCd6XK7Z.js";
-import { t as sa } from "./chunks/close-button-GvqWbLl0.js";
-import { t as ra } from "./chunks/input-group-5AtpIhC_.js";
-import { n as Ea, t as _a } from "./chunks/card-DSW3Uhag.js";
-import { n as Sa, t as Ia } from "./chunks/dialog-fWS3A3Z-.js";
-import { i as Aa, n as Ta, r as ma, t as ea } from "./chunks/status-view-C8tabjDu.js";
+import { a as m, c as R, d as B, i as p, l as C, n as O, o as f, r as u, s as N, t as P, u as D } from "./chunks/button-DNNs5RsT.js";
+import { a as V, c, i as l, l as U, n as G, o as d, r as M, s as b, t as g } from "./chunks/error-Crs-wqMC.js";
+import { a as F, c as W, d as h, f as v, i as Z, l as w, m as x, n as H, o as Y, p as z, r as X, s as j, t as q, u as y } from "./chunks/basic-page-c_7Ii5Fr.js";
+import { a as K, c as Q, i as $, n as ss, o as as, r as ts, s as rs, t as Es } from "./chunks/sidebar-DvB-G0BP.js";
+import { t as _s } from "./chunks/input-DjvZoF8v.js";
+import { t as is } from "./chunks/close-button-GvqWbLl0.js";
+import { t as Ts } from "./chunks/input-group-fc9_jD4d.js";
+import { n as ns, t as es } from "./chunks/card-DSW3Uhag.js";
+import { n as Rs, t as Bs } from "./chunks/dialog-8SRNi_rv.js";
+import { i as Cs, n as Os, r as fs, t as us } from "./chunks/status-view-C8tabjDu.js";
 import "./components/status-view.js";
 export {
-  x as BASIC_PAGE_CALLOUT,
-  h as BASIC_PAGE_CARD,
-  v as BASIC_PAGE_ITEM,
-  W as BASIC_PAGE_ITEM_PANEL,
-  F as BASIC_PAGE_ITEM_PANEL_DIVIDED,
-  Z as BASIC_PAGE_ROW,
-  D as BUTTON_COLORS,
+  q as AUTO_SAVE_DELAY_MS,
+  H as BASIC_PAGE_CALLOUT,
+  X as BASIC_PAGE_CARD,
+  Z as BASIC_PAGE_ITEM,
+  F as BASIC_PAGE_ITEM_PANEL,
+  Y as BASIC_PAGE_ITEM_PANEL_DIVIDED,
+  j as BASIC_PAGE_ROW,
+  P as BUTTON_COLORS,
   O as BUTTON_SHAPES,
-  f as BUTTON_SIZES,
-  B as BUTTON_VARIANTS,
-  w as BasicPage,
-  e as Button,
-  P as ButtonLink,
-  _a as CARD_SURFACE,
-  A as CONTROL_PRESS_SCALE,
-  I as CONTROL_PRESS_SPRING,
-  Ea as Card,
-  sa as CloseButton,
-  Ia as Dialog,
-  u as EFFECT_BUTTON_SIZES,
+  u as BUTTON_SIZES,
+  p as BUTTON_VARIANTS,
+  W as BasicPage,
+  m as Button,
+  f as ButtonLink,
+  es as CARD_SURFACE,
+  w as CONDENSE_BAR_ENTER,
+  y as CONDENSE_BAR_RISE_PX,
+  h as CONDENSE_BAR_TRAVEL,
+  I as CONTROL_PRESS_SCALE,
+  A as CONTROL_PRESS_SPRING,
+  ns as Card,
+  is as CloseButton,
+  Bs as Dialog,
+  N as EFFECT_BUTTON_SIZES,
   R as EffectButton,
   C as EffectButtonLink,
   g as Error,
   G as ErrorView,
   M as GENERIC_ERROR_TITLE,
-  $ as Input,
-  ra as InputGroup,
-  E as LinkProvider,
-  Q as SIDEBAR_HEADER_INSET,
-  q as SIDEBAR_ITEM,
-  J as SIDEBAR_ITEM_ACTIVE,
-  j as SIDEBAR_ITEM_INACTIVE,
-  z as SIDEBAR_ROOT,
-  y as SIDEBAR_ROOT_BASE,
-  K as SIDEBAR_ROOT_INSET,
-  ea as STATUS_VIEW,
-  Ta as STATUS_VIEW_COPY,
-  ma as STATUS_VIEW_SIZES,
-  Y as Sidebar,
-  Aa as StatusView,
-  N as buttonVariants,
-  V as capitalizeFirst,
-  s as cn,
-  c as describeError,
-  p as effectButtonVariants,
+  _s as Input,
+  Ts as InputGroup,
+  o as LinkProvider,
+  Es as SIDEBAR_HEADER_INSET,
+  ss as SIDEBAR_ITEM,
+  ts as SIDEBAR_ITEM_ACTIVE,
+  $ as SIDEBAR_ITEM_INACTIVE,
+  K as SIDEBAR_ROOT,
+  as as SIDEBAR_ROOT_BASE,
+  rs as SIDEBAR_ROOT_INSET,
+  us as STATUS_VIEW,
+  Os as STATUS_VIEW_COPY,
+  fs as STATUS_VIEW_SIZES,
+  Q as Sidebar,
+  Cs as StatusView,
+  D as buttonVariants,
+  l as capitalizeFirst,
+  a as cn,
+  V as describeError,
+  B as effectButtonVariants,
+  v as formToasts,
   d as httpReasonPhrase,
   b as httpStatusExplanation,
-  l as isProblem,
-  o as isReactComponent,
+  c as isProblem,
+  E as isReactComponent,
   U as parseProblem,
-  i as resolveVariant,
-  Sa as useDialogPending,
+  S as resolveVariant,
+  z as useAutoSave,
+  x as useCondense,
+  Rs as useDialogPending,
   r as useLinkComponent,
-  n as usePressPulse
+  T as usePressPulse
 };

package/dist/primitives.js

@@ -48,6 +48,7 @@ export * from "@base-ui/react/popover";
 export * from "@base-ui/react/avatar";
 export * from "@base-ui/react/form";
 export * from "@base-ui/react/menu";
+export * from "@base-ui/react/toast";
 export * from "@base-ui/react/accordion";
 export * from "@base-ui/react/alert-dialog";
 export * from "@base-ui/react/autocomplete";
@@ -75,7 +76,6 @@ export * from "@base-ui/react/select";
 export * from "@base-ui/react/slider";
 export * from "@base-ui/react/switch";
 export * from "@base-ui/react/tabs";
-export * from "@base-ui/react/toast";
 export * from "@base-ui/react/toggle";
 export * from "@base-ui/react/toggle-group";
 export * from "@base-ui/react/toolbar";

package/dist/sections/basic-page.js

@@ -1,11 +1,18 @@
 "use client";
-import { a as _, i as E, n as I, o as a, r as s, s as P, t as C } from "../chunks/basic-page-BkLG3Ybg.js";
+import { a as A, c as E, d as s, f as a, i as S, l as C, m as I, n as B, o as P, p as e, r as N, s as o, t as D, u as R } from "../chunks/basic-page-c_7Ii5Fr.js";
 export {
-  C as BASIC_PAGE_CALLOUT,
-  I as BASIC_PAGE_CARD,
-  s as BASIC_PAGE_ITEM,
-  E as BASIC_PAGE_ITEM_PANEL,
-  _ as BASIC_PAGE_ITEM_PANEL_DIVIDED,
-  a as BASIC_PAGE_ROW,
-  P as BasicPage
+  D as AUTO_SAVE_DELAY_MS,
+  B as BASIC_PAGE_CALLOUT,
+  N as BASIC_PAGE_CARD,
+  S as BASIC_PAGE_ITEM,
+  A as BASIC_PAGE_ITEM_PANEL,
+  P as BASIC_PAGE_ITEM_PANEL_DIVIDED,
+  o as BASIC_PAGE_ROW,
+  E as BasicPage,
+  C as CONDENSE_BAR_ENTER,
+  R as CONDENSE_BAR_RISE_PX,
+  s as CONDENSE_BAR_TRAVEL,
+  a as formToasts,
+  e as useAutoSave,
+  I as useCondense
 };

package/dist/sections/sidebar.js

@@ -1,5 +1,5 @@
 "use client";
-import { a as I, c as _, i as A, n as R, o as S, r as a, s, t as T } from "../chunks/sidebar-Dt1F_CEP.js";
+import { a as I, c as _, i as A, n as R, o as S, r as a, s, t as T } from "../chunks/sidebar-DvB-G0BP.js";
 export {
   T as SIDEBAR_HEADER_INSET,
   R as SIDEBAR_ITEM,

package/dist/src/components/command/command.d.ts

@@ -1,7 +1,7 @@
 import { ComponentProps, ReactNode } from 'react';
 import { Command as CommandPrimitive, useCommandState } from 'cmdk';
 import { Dialog as PhoDialog } from '../dialog';
-declare function Root({ className, children, ...props }: ComponentProps<typeof CommandPrimitive>): import("react").JSX.Element;
+declare function Root({ shouldFilter, className, children, ...props }: ComponentProps<typeof CommandPrimitive>): import("react").JSX.Element;
 /**
  * The input row — a bottom hairline separates it from the list. Position
  * leading icons absolutely and pad the input (`pl-9`), mirroring
@@ -89,9 +89,10 @@ declare function Dialog({ open, onOpenChange, label, className, children, ...pro
 /**
  * Command menu built on `cmdk` — a filterable list of actions driven from a
  * single input, keyboard-first. Compose inline (`Command.Root`) or as a
- * ⌘K-style modal palette (`Command.Dialog`, which owns the overlay). By
- * default cmdk filters and ranks items for you; pass `shouldFilter={false}`
- * to render your own result set (e.g. hierarchy-preserving navigation).
+ * ⌘K-style modal palette (`Command.Dialog`, which owns the overlay).
+ * Filtering is yours by default — filter in render so the rows' diff can
+ * glide; pass `shouldFilter` to hand matching and ranking to cmdk (its
+ * imperative reorder skips the animation).
  *
  * Rows share one layout via `Command.Item` `level` — idle
  * `item` → `subitem` → `subsubitem`, or flat `result` while searching.

package/dist/src/components/input/input.d.ts

@@ -15,6 +15,15 @@ export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
     }>;
     /** Node rendered at the right edge of the label row (e.g. "Forgot?"). */
     labelTrailing?: ReactNode;
+    /**
+     * Quiet word or glyph inside the field at its trailing edge (an
+     * auto-save's `Saved`, a live character count). Non-interactive overlay:
+     * it never takes the pointer, the invalid icon takes the corner over
+     * it, and the input reserves nothing — content that shows only
+     * sometimes brings its own surface wash (as `Saved` does) so long text
+     * fades beneath it instead of colliding.
+     */
+    trailing?: ReactNode;
     /** Class applied to the input wrapper. */
     wrapperClassName?: string;
     ref?: Ref<HTMLInputElement>;
@@ -24,7 +33,7 @@ export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
  * Pho's bordered surface, leading icon, invalid state, and a built-in password
  * reveal toggle.
  */
-export declare function Input({ label, hint, size, invalid, icon: Icon, labelTrailing, disabled, required, type, className, wrapperClassName, id, ref, ...props }: InputProps): import("react").JSX.Element;
+export declare function Input({ label, hint, size, invalid, icon: Icon, labelTrailing, trailing, disabled, required, type, className, wrapperClassName, id, ref, ...props }: InputProps): import("react").JSX.Element;
 export declare namespace Input {
     var displayName: string;
 }

package/dist/src/components/input-group/input-group.d.ts

@@ -1,4 +1,4 @@
-import { ComponentProps, ElementType, HTMLAttributes, InputHTMLAttributes, Ref } from 'react';
+import { ComponentProps, ElementType, HTMLAttributes, InputHTMLAttributes, Ref, ReactNode } from 'react';
 import { Separator as BaseSeparator } from '@base-ui/react/separator';
 /** Override Base UI's `string | (state) => string` className with plain string. */
 type StyledProps<T extends ElementType> = Omit<ComponentProps<T>, "className"> & {
@@ -20,6 +20,13 @@ export interface InputGroupRootProps extends HTMLAttributes<HTMLDivElement> {
  */
 declare function Root({ size, invalid, className, onPointerDown, ref, ...props }: InputGroupRootProps): import("react").JSX.Element;
 export interface InputGroupInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size"> {
+    /**
+     * Quiet word or glyph over the control's trailing edge, before the
+     * addons (an auto-save's `Saved`). Non-interactive overlay; content
+     * that shows only sometimes brings its own surface wash so long text
+     * fades beneath it. Reserves nothing.
+     */
+    trailing?: ReactNode;
     ref?: Ref<HTMLInputElement>;
 }
 /**
@@ -27,7 +34,7 @@ export interface InputGroupInputProps extends Omit<InputHTMLAttributes<HTMLInput
  * `Field.Root` it picks up the label and description wiring automatically;
  * standalone it behaves as a plain `<input>` (pass `aria-label` then).
  */
-declare function GroupInput({ className, ref, ...props }: InputGroupInputProps): import("react").JSX.Element;
+declare function GroupInput({ className, trailing, ref, ...props }: InputGroupInputProps): import("react").JSX.Element;
 /**
  * Inline content beside the control — prefix/suffix text, an icon, a `Kbd`
  * hint, or a small button. Text and icons render in the secondary tone so the

package/dist/src/components/scroll-area/index.d.ts

@@ -1 +1,2 @@
 export { ScrollArea } from './scroll-area';
+export { BLUR_MAX_PX } from './scroll-area-edges';

package/dist/src/components/scroll-area/scroll-area-edges.d.ts

@@ -2,6 +2,12 @@ import { Ref } from 'react';
 /** Overlay strip height — a short ramp, not a banner. `h-8` = 32px. */
 export declare const EDGE_CLASS = "pointer-events-none absolute inset-x-0 z-10 h-8";
 export declare const EDGE_REVEAL_PX = 32;
+/**
+ * The system's one blur strength. The edge fade peaks here, and a motion
+ * that softens (a scope swap, a bar title) borrows the same value, so
+ * every soft focus in the product is the same soft focus.
+ */
+export declare const BLUR_MAX_PX = 1;
 export declare function paintEdge(node: HTMLDivElement | null, progress: number): void;
 export declare function Edge({ edge, edgeRef, surface, className, }: {
     edge: "top" | "bottom";

package/dist/src/components/scroll-area/scroll-area.d.ts

@@ -1,9 +1,22 @@
-import { ComponentProps, ElementType } from 'react';
+import { ComponentProps, ElementType, Ref } from 'react';
 import { ScrollArea as BaseScrollArea } from '@base-ui/react/scroll-area';
 /** Override Base UI's `string | (state) => string` className with plain string. */
 type StyledProps<T extends ElementType> = Omit<ComponentProps<T>, "className"> & {
     className?: string;
 };
+/**
+ * The scrolled content. `inset` is a resting inset in the scroll axis —
+ * like a scroll view's safe-area padding: the content stands clear of the
+ * edges at rest but scrolls past them to the true edge, and the scrollbar
+ * and edge fade stay on `Root`'s edges. `insetTop` / `insetBottom` set the
+ * ends separately (they win over `inset`).
+ */
+declare function Content({ inset, insetTop, insetBottom, style, ref, ...props }: ComponentProps<typeof BaseScrollArea.Content> & {
+    inset?: number | string;
+    insetTop?: number | string;
+    insetBottom?: number | string;
+    ref?: Ref<HTMLDivElement>;
+}): import("react").JSX.Element;
 declare function Root({ className, children, ...props }: StyledProps<typeof BaseScrollArea.Root>): import("react").JSX.Element;
 declare function Viewport({ className, ref, ...props }: StyledProps<typeof BaseScrollArea.Viewport>): import("react").JSX.Element;
 declare function Scrollbar({ className, ...props }: StyledProps<typeof BaseScrollArea.Scrollbar>): import("react").JSX.Element;
@@ -18,7 +31,7 @@ declare function Thumb({ className, ...props }: StyledProps<typeof BaseScrollAre
 export declare const ScrollArea: {
     Root: typeof Root;
     Viewport: typeof Viewport;
-    Content: import('react').ForwardRefExoticComponent<Omit<import('@base-ui/react').ScrollAreaContentProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
+    Content: typeof Content;
     Scrollbar: typeof Scrollbar;
     Thumb: typeof Thumb;
     Corner: import('react').ForwardRefExoticComponent<Omit<import('@base-ui/react').ScrollAreaCornerProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;

package/dist/src/components/toast/index.d.ts

@@ -1 +1 @@
-export { Toast } from './toast';
+export { Toast, Toasty } from './toast';

package/dist/src/components/toast/toast.d.ts

@@ -1,4 +1,4 @@
-import { ComponentProps, ElementType } from 'react';
+import { ComponentProps, ElementType, ReactNode } from 'react';
 import { Toast as BaseToast } from '@base-ui/react/toast';
 /** Override Base UI's `string | (state) => string` className with plain string. */
 type StyledProps<T extends ElementType> = Omit<ComponentProps<T>, "className"> & {
@@ -11,12 +11,27 @@ declare function Title({ className, ...props }: StyledProps<typeof BaseToast.Tit
 declare function Description({ className, ...props }: StyledProps<typeof BaseToast.Description>): import("react").JSX.Element;
 declare function Close({ className, ...props }: StyledProps<typeof BaseToast.Close>): import("react").JSX.Element;
 /**
- * Toast built on Base UI `Toast` — a transient, non-blocking notification.
- * Wrap your app in `Toast.Provider`, render a `Toast.Portal` → `Viewport` that
- * maps `useToastManager().toasts` to `Toast.Root`s, then call
- * `useToastManager().add({ title, description })` to show one. Use a toast for
- * confirmation of a background action; for a choice the user must make, use
- * `Dialog`.
+ * Toasty — the whole toast system in one wrapper, Kumo-shaped: provider,
+ * portal, viewport, and the stacked card list with status variants. Wrap
+ * the app once and call `Toast.useToastManager().add({ title, type })`
+ * from any child; pass a `toastManager` from `createToastManager()` so
+ * code outside the tree (a form's auto-save, a query cache) can speak
+ * through the same lane. `manager.promise` shows loading → success/error
+ * with the matching glyphs.
+ */
+export declare function Toasty({ children, toastManager, }: {
+    children?: ReactNode;
+    toastManager?: ComponentProps<typeof BaseToast.Provider>["toastManager"];
+}): import("react").JSX.Element;
+/**
+ * Toast built on Base UI `Toast` — transient, non-blocking notifications
+ * in a sonner-style stack, styled after Cloudflare's Kumo: at rest the
+ * cards collapse into a peek (12px rise and −10% scale per depth, words
+ * hidden behind the front card), expand into a true list with a 12px gap
+ * on hover or focus, swipe to dismiss, three visible at most. `type`
+ * (`success` / `error` / `warning` / `info` / `loading`) tints hairline,
+ * glyph, and title together. Reach for `Toasty` unless you need to
+ * compose the parts yourself.
  */
 export declare const Toast: {
     Provider: import('react').FC<import('@base-ui/react').ToastProviderProps>;

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

@@ -72,6 +72,66 @@ export interface BasicPageRootProps extends ComponentProps<"div"> {
     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
@@ -283,9 +343,36 @@ export interface BasicPageAlertProps extends Omit<ComponentProps<"div">, "childr
  * instead.
  */
 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"> {
+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
@@ -315,7 +402,21 @@ export interface BasicPageFormProps<Values extends Record<string, unknown> = Rec
  * 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, className, children, onChange, ...props }: BasicPageFormProps<Values>): import("react").JSX.Element;
+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
@@ -546,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;
@@ -567,6 +669,7 @@ export declare const BasicPage: {
     Alert: typeof Alert;
     Footer: typeof Footer;
     Form: typeof Form;
+    Saved: typeof Saved;
     Fields: typeof Fields;
     Inline: typeof Inline;
     Submit: typeof Submit;

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 BasicPageRootProps, type BasicPageRowProps, type BasicPageRowLinkProps, type BasicPageBackProps, type BasicPageBreadcrumbsProps, type BasicPageCrumbProps, type BasicPageFooterProps, type BasicPageFormProps, type BasicPageFormErrors, 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.3.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 {