@photon-ai/pho-ui 2.14.0 → 2.16.0

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

@@ -82,8 +82,19 @@ export interface BasicPageRootProps extends ComponentProps<"div"> {
      * space is margin, not content width.
      */
     width?: "base" | "wide";
+    /**
+     * This page was painted before React — rendered to a string and inlined
+     * ahead of the bundle (a boot skeleton), or the React twin re-rendering
+     * that markup as-is on its first commit. Marks the root with
+     * `data-basic-page-prerendered`. Nothing inside it plays the entrance,
+     * an explicit `enter` included: the page is already on screen, and
+     * starting values would blink it out. The React page taking over from
+     * it stays put too — it finds the marker in the document at its first
+     * render, while the twin is still there.
+     */
+    prerendered?: boolean;
 }
-declare function Root({ condense, width, className, children, ref, ...props }: BasicPageRootProps): import("react").JSX.Element;
+declare function Root({ condense, width, prerendered, className, children, ref, ...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
@@ -126,8 +137,9 @@ declare function CondenseScope({ adopt, children, }: {
 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.
+ * (`CondenseScope`) so its swap moves the same way: 0.2s ease-out. The bar
+ * fades in place; its page name rises in from 8px below and leaves the
+ * same way.
  */
 export declare const CONDENSE_BAR_ENTER: {
     readonly duration: 0.2;
@@ -143,6 +155,10 @@ export declare const CONDENSE_BAR_TRAVEL: {
     readonly duration: 0.2;
     readonly ease: "linear";
 };
+/**
+ * The bar's rise distance, signed as "from above": the page name comes
+ * from below, so it starts at `-CONDENSE_BAR_RISE_PX`.
+ */
 export declare const CONDENSE_BAR_RISE_PX = -8;
 export interface BasicPageTitleProps extends ComponentProps<"h1"> {
     /**
@@ -158,8 +174,10 @@ export interface BasicPageTitleProps extends ComponentProps<"h1"> {
      * the two form one upward stream and never overlap. Combines with
      * `morphId` for a mid-level page (a list that is itself a subpage): the
      * word rises in when the page is entered from its parent and flies in
-     * from the back link when returned to from its own subpage. Skipped
-     * under reduced motion.
+     * from the back link when returned to from its own subpage. Played once
+     * per visit: a title taking over from a loading part in this page's
+     * `Root` (its skeleton's), or from a prerendered page anywhere (the one
+     * painted before React), stays put. Skipped under reduced motion.
      */
     enter?: boolean;
     /**
@@ -181,15 +199,19 @@ export interface BasicPageTitleProps extends ComponentProps<"h1"> {
  * `shrink-0` siblings of a `min-w-0 truncate` label inside a `flex min-w-0`
  * row so they stay visible.
  */
-declare function Title({ id, morphId, enter, trailing, className, children, ...props }: BasicPageTitleProps): import("react").JSX.Element;
+declare function Title({ id, morphId, enter: enterProp, trailing, className, children, ...props }: BasicPageTitleProps): import("react").JSX.Element;
 export interface BasicPageStackProps extends Omit<ComponentProps<"div">, RevealMotionConflicts> {
     /**
-     * Play the page entrance on mount (the default). `false` renders the
-     * stack at rest, for a loading state that is already on screen — painted
-     * as static HTML before the bundle, re-rendered as-is on React's first
-     * commit, then shown by the page until its data arrives — so that none of
-     * those mounts moves it; the real stack, with its entrance, takes over
-     * with the data.
+     * Whether mounting plays the page entrance. Left unset, the stack decides
+     * from what is on screen: it enters unless it is taking over from a
+     * loading part in this page's `Root` — a stack marked `aria-busy`, or
+     * inside an `aria-busy` region — or a prerendered page is anywhere in
+     * the document. In the first case the skeleton was the page's entrance
+     * and this stack takes its place at rest, values filling in; in the
+     * second the page was painted before React and is already there. A
+     * loading part in some other page (one still on screen while this one
+     * mounts) does not count. `true` always enters, except inside a
+     * `Root prerendered`; `false` never does.
      */
     enter?: boolean;
     ref?: Ref<HTMLDivElement>;
@@ -199,21 +221,29 @@ export interface BasicPageStackProps extends Omit<ComponentProps<"div">, RevealM
  * each block lays out its children with `gap-3`.
  *
  * Mounting plays the page entrance: the stack rises 12px and fades in on the
- * Card-shell / Command spring while `Title` / `Back` above stay put. What
+ * Card-shell / Command spring while `Title` / `Back` above stay put. The
+ * entrance is the page's, played once per visit by whatever the page first
+ * shows; a stack that takes over from a loading one appears at rest. What
  * that means per state:
  *
  * - **Entering the page** — whatever the page first shows (skeleton
  *   included) rides in with its stack.
- * - **Skeleton in a separate component** — swapping it for the loaded
- *   return mounts a fresh stack, so the entrance replays as the
- *   data-arrival animation. That's the right feel for shapes the skeleton
- *   couldn't predict (lists of unknown length).
- * - **1:1 skeleton** — keep ONE stack mounted and branch its children
- *   (`{pending ? bones : content}`): values then fill in place with no
- *   motion.
- * - **Skeleton that is already on screen** (server-painted, then hydrated,
- *   then shown by the page) — `enter={false}`: the stack renders at rest and
- *   the entrance is the loaded stack's alone.
+ * - **Skeleton, then the data** — a skeleton is a stack under `aria-busy`
+ *   (its own, or a wrapper's). The loaded stack mounting in its place, in
+ *   the same `Root`, finds it there and renders at rest: the shape was
+ *   already there, the values fill in. Whether the skeleton is a separate
+ *   component (swapped for the loaded return) or one stack branching its
+ *   children (`{pending ? bones : content}`) makes no difference to the
+ *   motion. Only this page's `Root` counts: a skeleton still on screen in
+ *   the page being left does not hold the next page at rest.
+ * - **Skeleton that is already on screen before React** (rendered to a
+ *   string, painted before the bundle, re-rendered as-is on React's first
+ *   commit) — its `Root` says `prerendered`: static markup never enters,
+ *   nothing inside that root does either, and the React page taking over
+ *   finds the marker in the document and stays put on its own;
+ *   `enter={false}` says so outright for markup that must never move.
+ * - **A region the skeleton couldn't predict** (a list of unknown length)
+ *   — `Reveal` rises that region in once its shape is known.
  *
  * Static under reduced motion.
  */
@@ -227,12 +257,14 @@ export interface BasicPageHeaderProps extends Omit<ComponentProps<"div">, Reveal
      * Rise this header into place on mount — the Header flavor of `Title`'s
      * `enter`, for a subpage title that carries a description: the pair
      * floats up from below the departing morph word as one block. Put `enter`
-     * here and NOT on the `Title` inside. Skipped under reduced motion.
+     * here and NOT on the `Title` inside. As for `Title`, stays put when it
+     * takes over from a loading part in this page's `Root`, or from a
+     * prerendered page anywhere. Skipped under reduced motion.
      */
     enter?: boolean;
     ref?: Ref<HTMLDivElement>;
 }
-declare function Header({ enter, className, ...props }: BasicPageHeaderProps): import("react").JSX.Element;
+declare function Header({ enter: enterProp, className, ...props }: BasicPageHeaderProps): import("react").JSX.Element;
 /**
  * An action at the header row's end — a small button (or two) seated in
  * the `Header` grid the way `Search` is: top-right of the block, its top

package/package.json

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