@photon-ai/pho-ui 2.15.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"> {
     /**
@@ -159,9 +175,9 @@ export interface BasicPageTitleProps extends ComponentProps<"h1"> {
      * `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. Played once
-     * per visit: a title taking over from a loading page already on screen
-     * (its skeleton's, or the one painted before React) stays put. Skipped
-     * under reduced motion.
+     * 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;
     /**
@@ -187,12 +203,15 @@ declare function Title({ id, morphId, enter: enterProp, trailing, className, chi
 export interface BasicPageStackProps extends Omit<ComponentProps<"div">, RevealMotionConflicts> {
     /**
      * Whether mounting plays the page entrance. Left unset, the stack decides
-     * from what is on screen: it enters unless a loading stack — one marked
-     * `aria-busy`, or inside an `aria-busy` region — is already there, in
-     * which case the skeleton was the page's entrance and this stack takes
-     * its place at rest, values filling in. `true` always enters; `false`
-     * never does (static markup React re-renders as-is on its first commit
-     * has nothing to arrive from).
+     * 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>;
@@ -210,16 +229,19 @@ export interface BasicPageStackProps extends Omit<ComponentProps<"div">, RevealM
  * - **Entering the page** — whatever the page first shows (skeleton
  *   included) rides in with its stack.
  * - **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
- *   finds it on screen 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.
+ *   (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) — static markup never enters, and the twin finds the static
- *   one in the document and stays put on its own; `enter={false}` says so
- *   outright for markup that must never move.
+ *   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.
  *
@@ -236,8 +258,8 @@ export interface BasicPageHeaderProps extends Omit<ComponentProps<"div">, Reveal
      * `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. As for `Title`, stays put when it
-     * takes over from a loading page already on screen. Skipped under
-     * reduced motion.
+     * 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>;

package/package.json

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