@phis/ui 0.2.1 → 0.4.0

package/helpers/css-linear-gradient.js

@@ -0,0 +1,122 @@
+function splitPhiCssGradientArguments(input) {
+    const stops = [];
+    let current = "";
+    let depth = 0;
+    for (const char of input) {
+        if (char === "(")
+            depth += 1;
+        if (char === ")")
+            depth = Math.max(0, depth - 1);
+        if (char === "," && depth === 0) {
+            stops.push(current.trim());
+            current = "";
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current.trim())
+        stops.push(current.trim());
+    return stops;
+}
+const PHI_CSS_NUMBER = "[-+]?(?:\\d+(?:\\.\\d+)?|\\.\\d+)";
+const PHI_CSS_ANGLE = new RegExp(`^(${PHI_CSS_NUMBER})(deg|grad|rad|turn)$`, "i");
+const PHI_CSS_GRADIENT_STOP = new RegExp(`^(.+?)(?:\\s+(${PHI_CSS_NUMBER})%)?$`);
+const PHI_CSS_DEGREES_PER_UNIT = { deg: 1, grad: 0.9, rad: 180 / Math.PI, turn: 360 };
+/**
+ * The first argument, when it is a direction.
+ *
+ * Only an angle or `to <side>` is one. Everything else is the first colour stop -- `red 0%` included,
+ * which read as a direction used to swallow the first stop and fall back to `to right`. A direction the
+ * Base cannot hold (a corner, an unreadable angle) is a problem rather than a stop.
+ */
+function readPhiCssGradientDirection(part) {
+    const side = part.match(/^to\s+(.+)$/i);
+    if (side) {
+        const target = side[1].trim().toLowerCase();
+        return target === "right" || target === "left" || target === "bottom" || target === "top"
+            ? { direction: `to ${target}` }
+            : { problem: `Gradient direction "${part}" is not supported; use an angle or one side.` };
+    }
+    const angle = part.match(PHI_CSS_ANGLE);
+    if (!angle) {
+        return null;
+    }
+    const unit = angle[2].toLowerCase();
+    const degrees = Number(angle[1]) * PHI_CSS_DEGREES_PER_UNIT[unit];
+    return Number.isFinite(degrees)
+        ? { direction: `${Math.round(degrees * 1000) / 1000}deg` }
+        : { problem: `Gradient angle "${part}" is not a number.` };
+}
+function readPhiCssGradientStop(part) {
+    const match = part.match(PHI_CSS_GRADIENT_STOP);
+    const color = match?.[1]?.trim();
+    if (!match || !color) {
+        return null;
+    }
+    // A colour is one token outside its parentheses; anything left over is a second position or a length.
+    let bare = color;
+    while (/\([^()]*\)/.test(bare))
+        bare = bare.replace(/\([^()]*\)/g, "");
+    if (/\s/.test(bare)) {
+        return null;
+    }
+    const percent = match[2] == null ? null : Number(match[2]);
+    return percent == null || Number.isFinite(percent) ? { color, percent } : null;
+}
+/**
+ * Positions for stops that name none, the way CSS places them: the first at 0, the last at 100, and
+ * any run in between evenly spaced between its neighbours.
+ */
+function placePhiCssGradientStops(stops) {
+    const percents = stops.map((stop) => stop.percent);
+    percents[0] ??= 0;
+    percents[percents.length - 1] ??= 100;
+    let previous = 0;
+    while (previous < percents.length - 1) {
+        let next = previous + 1;
+        while (percents[next] == null)
+            next += 1;
+        const start = percents[previous];
+        const end = percents[next];
+        for (let index = previous + 1; index < next; index += 1) {
+            percents[index] = start + ((end - start) * (index - previous)) / (next - previous);
+        }
+        previous = next;
+    }
+    return stops.map((stop, index) => ({ color: stop.color, percent: percents[index] }));
+}
+export function readPhiCssLinearGradient(css) {
+    const background = css.trim();
+    const kind = background.match(/^([a-z-]*gradient)\(/i)?.[1]?.toLowerCase();
+    if (!kind) {
+        return null;
+    }
+    if (kind !== "linear-gradient") {
+        return { problem: `A Background gradient is linear; "${kind}" is not supported.` };
+    }
+    if (!background.endsWith(")")) {
+        return { problem: "The gradient is not closed." };
+    }
+    const parts = splitPhiCssGradientArguments(background.slice("linear-gradient(".length, -1));
+    const direction = parts.length > 0 ? readPhiCssGradientDirection(parts[0]) : null;
+    if (direction && "problem" in direction) {
+        return { problem: direction.problem };
+    }
+    const stopParts = direction ? parts.slice(1) : parts;
+    if (stopParts.length < 2) {
+        return { problem: "A gradient needs at least two colour stops." };
+    }
+    const stops = stopParts.map(readPhiCssGradientStop);
+    const unreadable = stops.findIndex((stop) => stop === null);
+    if (unreadable >= 0) {
+        return { problem: `Gradient stop "${stopParts[unreadable]}" is not a colour with a percentage.` };
+    }
+    return {
+        gradient: {
+            // What CSS draws when a gradient names no direction.
+            direction: direction?.direction ?? "to bottom",
+            stops: placePhiCssGradientStops(stops),
+        },
+    };
+}

package/helpers/flags.d.ts

@@ -1 +1,11 @@
 export declare function hasPhiFlag(flags: number | null | undefined, flag: number): boolean;
+/**
+ * The flag set a stored config carries, read off its `flags` field.
+ *
+ * A config states its yes-or-no answers as bits (`PhiCmsFlags`), and a config that states none has none.
+ * Anything else in the field is a broken record and is refused rather than read as unset -- read as
+ * unset, a Sider would quietly lose its full height and the record would look as if it had never said so.
+ */
+/** Whether a stored config's `flags` carry the bit; the config may be absent, its field unset. */
+export declare function hasPhiConfigFlag(config: Record<string, unknown> | null | undefined, flag: number): boolean;
+export declare function readPhiFlags(value: unknown): number;

package/helpers/flags.js

@@ -1,3 +1,23 @@
 export function hasPhiFlag(flags, flag) {
     return ((flags ?? 0) & flag) === flag;
 }
+/**
+ * The flag set a stored config carries, read off its `flags` field.
+ *
+ * A config states its yes-or-no answers as bits (`PhiCmsFlags`), and a config that states none has none.
+ * Anything else in the field is a broken record and is refused rather than read as unset -- read as
+ * unset, a Sider would quietly lose its full height and the record would look as if it had never said so.
+ */
+/** Whether a stored config's `flags` carry the bit; the config may be absent, its field unset. */
+export function hasPhiConfigFlag(config, flag) {
+    return hasPhiFlag(readPhiFlags(config?.flags), flag);
+}
+export function readPhiFlags(value) {
+    if (value === undefined || value === null) {
+        return 0;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new Error(`A config's "flags" must be a non-negative integer, got ${JSON.stringify(value)}.`);
+    }
+    return value;
+}

package/helpers/form-id.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A Form id or a submit handler key as the registry files it: trimmed, lower-case.
+ *
+ * Three files normalised a Form id for themselves and a fourth its handler key, each `trim().toLowerCase()`;
+ * a registry that compares keys has to spell the comparison once, or a key written one way is filed
+ * under another.
+ */
+export declare function normalizePhiFormKey(value: string): string;

package/helpers/form-id.js

@@ -0,0 +1,10 @@
+/**
+ * A Form id or a submit handler key as the registry files it: trimmed, lower-case.
+ *
+ * Three files normalised a Form id for themselves and a fourth its handler key, each `trim().toLowerCase()`;
+ * a registry that compares keys has to spell the comparison once, or a key written one way is filed
+ * under another.
+ */
+export function normalizePhiFormKey(value) {
+    return value.trim().toLowerCase();
+}

package/helpers/format-date-time.d.ts

@@ -1,2 +1,7 @@
 export declare function formatPhiDate(value: string | null | undefined, locale: string): string;
 export declare function formatPhiDateTime(value: string | null | undefined, locale: string): string;
+/**
+ * How long ago or how far ahead, in the locale the caller names: "3 days ago", "in 2 hours". The
+ * largest unit the distance fills, so a moment reads in the words a person would use for it.
+ */
+export declare function formatPhiRelativeTime(value: string | null | undefined, locale: string, now?: number): string;

package/helpers/format-date-time.js

@@ -32,3 +32,34 @@ export function formatPhiDateTime(value, locale) {
         ? readFormatter(dateTimeFormatters, locale, { dateStyle: "medium", timeStyle: "short" }).format(date)
         : value || "—";
 }
+const relativeFormatters = new Map();
+const RELATIVE_UNITS = [
+    ["year", 365 * 24 * 60 * 60 * 1000],
+    ["month", 30 * 24 * 60 * 60 * 1000],
+    ["week", 7 * 24 * 60 * 60 * 1000],
+    ["day", 24 * 60 * 60 * 1000],
+    ["hour", 60 * 60 * 1000],
+    ["minute", 60 * 1000],
+];
+/**
+ * How long ago or how far ahead, in the locale the caller names: "3 days ago", "in 2 hours". The
+ * largest unit the distance fills, so a moment reads in the words a person would use for it.
+ */
+export function formatPhiRelativeTime(value, locale, now = Date.now()) {
+    const date = readPhiDate(value);
+    if (!date) {
+        return value || "—";
+    }
+    let formatter = relativeFormatters.get(locale);
+    if (!formatter) {
+        formatter = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+        relativeFormatters.set(locale, formatter);
+    }
+    const distance = date.getTime() - now;
+    for (const [unit, size] of RELATIVE_UNITS) {
+        if (Math.abs(distance) >= size) {
+            return formatter.format(Math.round(distance / size), unit);
+        }
+    }
+    return formatter.format(0, "minute");
+}

package/helpers/internal-path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * An address on this Site, and only one.
+ *
+ * The rule is phis-server's `normalizeAuthNextPath`, kept the same on both sides: one leading slash,
+ * no second slash or backslash after it, no control characters, and parsed against a fixed origin it
+ * must not leave. The backslash is the one that matters -- a browser reads `/\evil.com` as `//evil.com`,
+ * so a reader that refused only `//` sent a visitor who finished signing in onto somebody else's host.
+ *
+ * Returns the trimmed path with its query and fragment, or `null`. Where a caller wants only the
+ * pathname it resolves the accepted value itself; the check is what this shares.
+ */
+export declare function readPhiInternalPath(value: unknown): string | null;

package/helpers/internal-path.js

@@ -0,0 +1,28 @@
+/**
+ * An address on this Site, and only one.
+ *
+ * The rule is phis-server's `normalizeAuthNextPath`, kept the same on both sides: one leading slash,
+ * no second slash or backslash after it, no control characters, and parsed against a fixed origin it
+ * must not leave. The backslash is the one that matters -- a browser reads `/\evil.com` as `//evil.com`,
+ * so a reader that refused only `//` sent a visitor who finished signing in onto somebody else's host.
+ *
+ * Returns the trimmed path with its query and fragment, or `null`. Where a caller wants only the
+ * pathname it resolves the accepted value itself; the check is what this shares.
+ */
+export function readPhiInternalPath(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim();
+    if (!normalized.startsWith("/") ||
+        normalized.startsWith("//") ||
+        normalized.includes("\\") ||
+        /[\u0000-\u001f\u007f]/u.test(normalized)) {
+        return null;
+    }
+    try {
+        return new URL(normalized, "https://phi.invalid").origin === "https://phi.invalid" ? normalized : null;
+    }
+    catch {
+        return null;
+    }
+}

package/helpers/is-record.js

@@ -1,6 +1,7 @@
 // About thirty files each carried a private copy of this predicate, and "plain object record" had two
 // possible answers for arrays. One export means the answer is chosen once: arrays are not records, so a
-// JSON array never passes as a keyed config object.
+// JSON array never passes as a keyed config object. Seventy more copies had grown back by 2026-10-05;
+// `scripts/validate-record-predicate.mjs` now fails the build for every spelling of the question but this.
 export function isPhiRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }

package/helpers/layout-authoring-markers.d.ts

@@ -23,8 +23,6 @@ export type PhiLayoutAuthoringSignal = {
 export declare function isPhiLayoutAuthoringRender(signal: PhiLayoutAuthoringSignal): boolean;
 /** The layout band's marker, and nothing at all outside authoring. */
 export declare function phiLayoutDebugLayerMarker(authoring: boolean): "layout" | undefined;
-/** The slot band's class, joinable with a layout's own slot class. */
-export declare function phiLayoutScaffoldSlotMarker(authoring: boolean): "phi-layout-scaffold-slot" | undefined;
 /** Whether a slot holds something, which only the scaffold asks. */
 export declare function phiLayoutSlotContentMarker(authoring: boolean, hasContent: boolean): "false" | "true" | undefined;
 /** Joins a layout's own slot class with the marker, dropping what is absent. */

package/helpers/layout-authoring-markers.js

@@ -23,7 +23,7 @@ export function phiLayoutDebugLayerMarker(authoring) {
     return authoring ? "layout" : undefined;
 }
 /** The slot band's class, joinable with a layout's own slot class. */
-export function phiLayoutScaffoldSlotMarker(authoring) {
+function phiLayoutScaffoldSlotMarker(authoring) {
     return authoring ? "phi-layout-scaffold-slot" : undefined;
 }
 /** Whether a slot holds something, which only the scaffold asks. */

package/helpers/layout-style.d.ts

@@ -1,5 +1,5 @@
 import type { CSSProperties } from "react";
-import { type PhiLayoutEffectId, type PhiShadow } from "../types/layout-style";
+import { type PhiGlassLayoutEffectId, type PhiShadow } from "../types/layout-style";
 /**
  * What each glass strength is made of.
  *
@@ -17,20 +17,6 @@ export declare const PHI_GLASS_LAYOUT_EFFECT_DEFINITIONS: {
         readonly strengthPercent: 60;
     };
 };
-export declare const PHI_LAYOUT_EFFECT_DEFINITIONS: {
-    readonly glass: {
-        readonly backdropFilter: "blur(24px) saturate(1.2)";
-    };
-    readonly haze: {
-        readonly backdropFilter: "blur(10px) saturate(1.1)";
-    };
-    readonly blur: {
-        readonly filter: "blur(6px)";
-    };
-    readonly dim: {
-        readonly filter: "brightness(0.85)";
-    };
-};
 export declare const PHI_SHADOW_DEFINITIONS: {
     readonly none: "none";
     readonly soft: "var(--ant-box-shadow-tertiary)";
@@ -38,7 +24,7 @@ export declare const PHI_SHADOW_DEFINITIONS: {
 };
 export declare function resolvePhiShadow(value: PhiShadow | null | undefined): CSSProperties["boxShadow"] | undefined;
 export declare function resolvePhiLayoutEffectStyle({ effect, background, }: {
-    effect?: PhiLayoutEffectId | null;
+    effect?: PhiGlassLayoutEffectId | null;
     background?: CSSProperties["background"];
 }): CSSProperties | undefined;
 export declare function composePhiLayoutEffectStyle(baseStyle: CSSProperties, effectStyle: CSSProperties | null | undefined): CSSProperties;

package/helpers/layout-style.js

@@ -1,5 +1,5 @@
 import { PHI_COLOR, PHI_SHADOW } from "../theme/antd-css-var-contract";
-import { isPhiGlassLayoutEffectId, } from "../types/layout-style";
+import {} from "../types/layout-style";
 /**
  * What each glass strength is made of.
  *
@@ -17,20 +17,6 @@ function resolvePhiGlassBackground(background, strengthPercent) {
         : PHI_COLOR.bgElevated;
     return `color-mix(in srgb, ${base} ${strengthPercent}%, transparent)`;
 }
-export const PHI_LAYOUT_EFFECT_DEFINITIONS = {
-    glass: {
-        backdropFilter: PHI_GLASS_LAYOUT_EFFECT_DEFINITIONS.glass.filter,
-    },
-    haze: {
-        backdropFilter: PHI_GLASS_LAYOUT_EFFECT_DEFINITIONS.haze.filter,
-    },
-    blur: {
-        filter: "blur(6px)",
-    },
-    dim: {
-        filter: "brightness(0.85)",
-    },
-};
 export const PHI_SHADOW_DEFINITIONS = {
     none: "none",
     soft: PHI_SHADOW.tertiary,
@@ -48,23 +34,20 @@ export function resolvePhiLayoutEffectStyle({ effect, background, }) {
     if (effect == null) {
         return undefined;
     }
-    if (isPhiGlassLayoutEffectId(effect)) {
-        const glass = PHI_GLASS_LAYOUT_EFFECT_DEFINITIONS[effect];
-        /*
-         * The ground as `backgroundColor`, never as the `background` shorthand.
-         *
-         * Callers spread this into an inline style that also carries longhands, from an authored Background
-         * config or from the Shell Chrome Overlay, and React warns when a rerender has to drop a longhand
-         * from an element whose shorthand is still set. The value is always a colour, so the longhand says
-         * the same thing without the shorthand's silent resets.
-         */
-        return {
-            backgroundColor: resolvePhiGlassBackground(background, glass.strengthPercent),
-            backdropFilter: glass.filter,
-            WebkitBackdropFilter: glass.filter,
-        };
-    }
-    return PHI_LAYOUT_EFFECT_DEFINITIONS[effect];
+    const glass = PHI_GLASS_LAYOUT_EFFECT_DEFINITIONS[effect];
+    /*
+     * The ground as `backgroundColor`, never as the `background` shorthand.
+     *
+     * Callers spread this into an inline style that also carries longhands, from an authored Background
+     * config or from the Shell Chrome Overlay, and React warns when a rerender has to drop a longhand
+     * from an element whose shorthand is still set. The value is always a colour, so the longhand says
+     * the same thing without the shorthand's silent resets.
+     */
+    return {
+        backgroundColor: resolvePhiGlassBackground(background, glass.strengthPercent),
+        backdropFilter: glass.filter,
+        WebkitBackdropFilter: glass.filter,
+    };
 }
 export function composePhiLayoutEffectStyle(baseStyle, effectStyle) {
     if (!effectStyle) {

package/helpers/link-target.d.ts

@@ -37,7 +37,12 @@ export declare function collectPhiLinkTargetReferences(value: unknown, into?: Ma
  * certain way. Every Control downstream would otherwise ask a regex the same question and get it wrong
  * for the one case that matters -- an internal Page whose resolved path happens to be absolute.
  */
-export declare function resolvePhiLinkHref(target: PhiLinkTarget | null | undefined, resolved?: PhiResolvedLinkTargets | null): {
+export declare function resolvePhiLinkHref(target: PhiLinkTarget | null | undefined, resolved?: PhiResolvedLinkTargets | null, 
+/**
+ * Route parameters the caller fills in beside the target's own -- a list that links each of its entries
+ * to one detail route states the route once and the slug per entry. The caller's win.
+ */
+params?: Readonly<Record<string, string>>): {
     href: string;
     newTab: boolean;
     external: boolean;

package/helpers/link-target.js

@@ -1,4 +1,4 @@
-import { isPhiLinkTargetConfigKey, readPhiLinkTarget, } from "../types/references";
+import { fillPhiRouteParams, isPhiLinkTargetConfigKey, readPhiLinkTarget, } from "../types/references";
 /**
  * Every Page a stored config points at, found by the name of the field it stands under.
  *
@@ -46,21 +46,29 @@ export function collectPhiLinkTargetReferences(value, into = new Map()) {
  * certain way. Every Control downstream would otherwise ask a regex the same question and get it wrong
  * for the one case that matters -- an internal Page whose resolved path happens to be absolute.
  */
-export function resolvePhiLinkHref(target, resolved) {
+export function resolvePhiLinkHref(target, resolved, 
+/**
+ * Route parameters the caller fills in beside the target's own -- a list that links each of its entries
+ * to one detail route states the route once and the slug per entry. The caller's win.
+ */
+params) {
     if (!target) {
         return null;
     }
     if (target.kind === "external") {
         return { href: target.href, newTab: target.newTab === true, external: true };
     }
-    const path = resolved?.get(target.reference);
+    const pattern = resolved?.get(target.reference);
+    // A route with a parameter resolves to its pattern; a parameter nobody filled is no address at all.
+    const path = pattern ? fillPhiRouteParams(pattern, { ...target.params, ...params }) : null;
     if (!path) {
         return null;
     }
     const fragment = target.fragment?.replace(/^#/u, "").trim();
     return {
         href: fragment ? `${path}#${encodeURIComponent(fragment)}` : path,
-        newTab: target.newTab === true,
+        // A Page of the Site never opens a new tab; only an address elsewhere may (see the link field).
+        newTab: false,
         external: false,
     };
 }

package/helpers/locale.d.ts

@@ -7,6 +7,8 @@ export type NormalizeLocaleOptions = {
     defaultLocale?: string | null | undefined;
     availableLocales?: readonly string[] | null | undefined;
 };
+/** A locale as a lookup key: spelling fixed and lower-cased, so `de_AT`, `de-at` and `de-AT` are one key. */
+export declare function normalizePhiLocaleKey(value: string | null | undefined): string;
 /**
  * A locale tag in canonical spelling, with every subtag it came with.
  *

package/helpers/locale.js

@@ -8,6 +8,10 @@ function normalizeAreaSegment(area) {
 function normalizeLocaleCode(value) {
     return (value ?? "").trim().replace(/_/g, "-");
 }
+/** A locale as a lookup key: spelling fixed and lower-cased, so `de_AT`, `de-at` and `de-AT` are one key. */
+export function normalizePhiLocaleKey(value) {
+    return normalizeLocaleCode(value).toLowerCase();
+}
 function normalizeAvailableLocales(availableLocales) {
     if (!availableLocales?.length) {
         return [];

package/helpers/logout.d.ts

@@ -1,19 +1,3 @@
-/**
- * Ending a session, as the two places that perform it both do it.
- *
- * The request is the same in both -- the sign-out Page, and the Core Runtime adapter answering a
- * `session/clear` signal, which is what the account menu, the sidebar's sign-out entry and the
- * password-change dialog send. What follows it is not, and deliberately so: the Page replaces itself
- * so Back does not return to a sign-out that already happened, and the adapter loads the Page it stands
- * on again as a fresh document, because whether whoever is now nobody may still stand there is the
- * Area's answer, and nothing rendered or stored for the old session may outlive it. Two endings, two
- * reasons, one request.
- *
- * Some callers used to set `x-phis-site-key`, which never arrives: `next/proxy-runtime.ts` strips
- * every `x-phis-` header on the way through and sets the Site's own, so that a request from the open
- * internet cannot claim to come from inside. None sets it now, so none can look as if it forgot to.
- */
-export declare const PHI_LOGOUT_PATH = "/api/auth/logout";
 export type RequestPhiLogoutOptions = {
     signal?: AbortSignal;
     /** What the failure says, where a caller has a surface to say it on. */

package/helpers/logout.js

@@ -14,7 +14,7 @@ import { fetchPhiCsrfToken } from "./csrf-token";
  * every `x-phis-` header on the way through and sets the Site's own, so that a request from the open
  * internet cannot claim to come from inside. None sets it now, so none can look as if it forgot to.
  */
-export const PHI_LOGOUT_PATH = "/api/auth/logout";
+const PHI_LOGOUT_PATH = "/api/auth/logout";
 /**
  * Throws unless the session was ended, on the same grounds `fetchPhiCsrfToken` does: a caller that
  * means to stay quiet writes a `catch` and is visibly quiet, rather than forgetting an `if`.

package/helpers/motion.d.ts

@@ -11,7 +11,6 @@ export declare function resolvePhiMotionDurationMs(value: string | number): numb
  */
 export declare const PHI_MOTION_EASINGS: readonly ["linear", "ease", "ease-in", "ease-out", "ease-in-out"];
 export type PhiMotionEasing = (typeof PHI_MOTION_EASINGS)[number];
-export declare function isPhiMotionEasing(value: unknown): value is PhiMotionEasing;
 /**
  * A stored curve, or nothing where none was stored.
  *
@@ -44,6 +43,13 @@ export declare const PHI_SEQUENCE_TRANSITION_MAX_MS = 600000;
  * exactly, so the grid the spinner walks holds every value it offers.
  */
 export declare const PHI_SEQUENCE_TRANSITION_STEP_MS = 100;
+/**
+ * What a sequence that says nothing moves at: long enough to read as movement, short enough to
+ * ignore. Exported so that a Widget can state it as its default and the Inspector shows the number
+ * that is actually in effect instead of an empty box.
+ */
+export declare const PHI_SEQUENCE_DEFAULT_DURATION_MS = 320;
+export declare const PHI_SEQUENCE_DEFAULT_EASING: PhiMotionEasing;
 /**
  * The two ways of showing a sequence, and which end of a wider window an index means.
  *

package/helpers/motion.js

@@ -18,7 +18,7 @@ export function resolvePhiMotionDurationMs(value) {
  * for a block effect and a curve chosen for a Carousel mean the same thing without translation.
  */
 export const PHI_MOTION_EASINGS = ["linear", "ease", "ease-in", "ease-out", "ease-in-out"];
-export function isPhiMotionEasing(value) {
+function isPhiMotionEasing(value) {
     return typeof value === "string" && PHI_MOTION_EASINGS.includes(value);
 }
 /**
@@ -58,6 +58,13 @@ export const PHI_SEQUENCE_TRANSITION_MAX_MS = 600_000;
  * exactly, so the grid the spinner walks holds every value it offers.
  */
 export const PHI_SEQUENCE_TRANSITION_STEP_MS = 100;
+/**
+ * What a sequence that says nothing moves at: long enough to read as movement, short enough to
+ * ignore. Exported so that a Widget can state it as its default and the Inspector shows the number
+ * that is actually in effect instead of an empty box.
+ */
+export const PHI_SEQUENCE_DEFAULT_DURATION_MS = 320;
+export const PHI_SEQUENCE_DEFAULT_EASING = "ease-in-out";
 /**
  * The two ways of showing a sequence, and which end of a wider window an index means.
  *

package/helpers/overlay-events.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Keeps a pointer or keyboard event inside the Overlay it happened in.
+ *
+ * A picker or a tool button sits over the Builder Canvas, and a click that bubbled on would select or
+ * drag whatever block stands beneath it. Five private copies of this one line stood in three files.
+ */
+export declare function stopPhiOverlayEvent(event: {
+    stopPropagation: () => void;
+}): void;

package/helpers/overlay-events.js

@@ -0,0 +1,9 @@
+/**
+ * Keeps a pointer or keyboard event inside the Overlay it happened in.
+ *
+ * A picker or a tool button sits over the Builder Canvas, and a click that bubbled on would select or
+ * drag whatever block stands beneath it. Five private copies of this one line stood in three files.
+ */
+export function stopPhiOverlayEvent(event) {
+    event.stopPropagation();
+}

package/helpers/page-reference-tree.d.ts

@@ -0,0 +1,42 @@
+import type { PhiTreeOption } from "../types/tree";
+import { resolvePhiBuilderCmsFetchPath } from "./cms-paths";
+import type { PhiPresetPageNode } from "./cms-page-catalog";
+import type { PhiPageReferenceSelection } from "../components/widgets/client/shared/phi-page-reference-picker";
+export type PhiBuilderPageReferenceTreeLabels = {
+    landing: string;
+};
+/**
+ * The Area's Pages as the tree they are, with each node carrying what it stands for.
+ *
+ * Flattening this was the earlier answer and it cost the two things a tree is for. Nesting is how a
+ * reader tells two Pages called "Overview" apart, and it is how a node that cannot be chosen keeps its
+ * children reachable: a path with no Page of its own, or a Page whose deletion has been published, is
+ * still the branch its children hang from. Those nodes stand here disabled rather than absent.
+ *
+ * `value` is the Page's own reference, never its path and never the Builder key -- `REFERENCES.md` names
+ * both among the things that must not stand in for Page identity. A node with nothing to stand for takes
+ * its Builder key as a value it can be told apart by, and carries no `meta`; the absent `meta` is what
+ * makes it unchoosable, rather than something the caller has to check after the click.
+ *
+ * `/` carries its slot after its title. Whoever answers the root -- the base welcome, a Site package's
+ * landing -- tends to be called "Home", and so does the `/home` Page next to it; two entries with one
+ * name ask an author to guess. The mark sits in the label rather than the description, because a closed
+ * Select shows the label alone. `meta.title` keeps the bare title, which is what a link drawn from the
+ * pick should read.
+ */
+export declare function buildPhiBuilderPageReferenceTree(area: Parameters<typeof resolvePhiBuilderCmsFetchPath>[0], nodes: readonly PhiPresetPageNode[], allNodes: readonly PhiPresetPageNode[], labels?: PhiBuilderPageReferenceTreeLabels): PhiTreeOption<PhiPageReferenceSelection>[];
+/** How the Page scope picker tells a folder's value from a Page reference. */
+export declare const PHI_PAGE_SCOPE_FOLDER_VALUE_PREFIX = "folder:";
+/**
+ * The Area's Pages for a Region's Page scope (SHELL.md "Region visibility per Page"): the tree above,
+ * with its folders choosable too.
+ *
+ * A folder is not a Page and has no reference -- a Site Page is never nested under another -- so the
+ * only thing that names it is the start of its Pages' paths. That start is read off the nearest Page
+ * below it, one segment dropped per level, rather than off the folder's catalog key: outside Public the
+ * key leaves the package namespace out, and the address a visitor opens does not.
+ *
+ * A Page that has Pages below it (a Module's) keeps its reference; choosing it chooses the subtree.
+ * A Page whose deletion has been published stays unchoosable, as in the tree above.
+ */
+export declare function buildPhiBuilderPageScopeTree(area: Parameters<typeof resolvePhiBuilderCmsFetchPath>[0], nodes: readonly PhiPresetPageNode[], allNodes: readonly PhiPresetPageNode[], labels?: PhiBuilderPageReferenceTreeLabels): PhiTreeOption[];