@phis/ui 0.2.1 → 0.3.0

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.
  *

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);
 }
 /**

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[];

package/helpers/page-reference-tree.js

@@ -0,0 +1,92 @@
+import { resolvePhiBuilderCmsFetchPath, resolvePhiBuilderCmsStoragePath } from "./cms-paths";
+const PHI_BUILDER_PAGE_REFERENCE_TREE_DEFAULT_LABELS = {
+    landing: "(Landing page)",
+};
+/**
+ * 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 function buildPhiBuilderPageReferenceTree(area, nodes, allNodes, labels = PHI_BUILDER_PAGE_REFERENCE_TREE_DEFAULT_LABELS) {
+    return nodes.map((node) => {
+        const path = resolvePhiBuilderCmsFetchPath(area, node.key, allNodes);
+        const reference = node.tombstoned === true ? undefined : node.reference;
+        return {
+            value: reference ?? node.key,
+            label: node.storagePath === "/" ? labelLanding(node.title, labels) : node.title,
+            description: path,
+            ...(reference
+                ? { meta: { reference, title: node.title, path } }
+                : { disabled: true }),
+            ...(node.children?.length
+                ? { children: buildPhiBuilderPageReferenceTree(area, node.children, allNodes, labels) }
+                : {}),
+        };
+    });
+}
+function labelLanding(title, labels) {
+    const trimmed = title.trim();
+    return trimmed ? `${trimmed} ${labels.landing}` : labels.landing;
+}
+/** How the Page scope picker tells a folder's value from a Page reference. */
+export 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 function buildPhiBuilderPageScopeTree(area, nodes, allNodes, labels = PHI_BUILDER_PAGE_REFERENCE_TREE_DEFAULT_LABELS) {
+    return nodes.map((node) => {
+        const children = node.children?.length
+            ? buildPhiBuilderPageScopeTree(area, node.children, allNodes, labels)
+            : undefined;
+        const reference = node.tombstoned === true ? undefined : node.reference;
+        const folder = reference == null && node.children?.length
+            ? resolveFolderPath(area, node.children, allNodes)
+            : null;
+        return {
+            value: reference ?? (folder ? `${PHI_PAGE_SCOPE_FOLDER_VALUE_PREFIX}${folder}` : node.key),
+            label: node.storagePath === "/" ? labelLanding(node.title, labels) : node.title,
+            description: folder ?? resolvePhiBuilderCmsFetchPath(area, node.key, allNodes),
+            ...(reference == null && folder == null ? { disabled: true } : {}),
+            ...(children ? { children } : {}),
+        };
+    });
+}
+/** The folder's own path, from the first Page below it, `depth` levels down. */
+function resolveFolderPath(area, nodes, allNodes, depth = 1) {
+    for (const node of nodes) {
+        if (node.reference != null) {
+            const segments = resolvePhiBuilderCmsStoragePath(area, node.key, allNodes).split("/").filter(Boolean);
+            return segments.length > depth ? `/${segments.slice(0, segments.length - depth).join("/")}` : null;
+        }
+    }
+    for (const node of nodes) {
+        const below = node.children?.length ? resolveFolderPath(area, node.children, allNodes, depth + 1) : null;
+        if (below != null) {
+            return below;
+        }
+    }
+    return null;
+}

package/helpers/phi-seo.d.ts

@@ -18,7 +18,6 @@ export type PhiPublicPageAlternates = {
     /** Keyed by locale code, plus `x-default` for the Site's default locale. */
     languages: Readonly<Record<string, string>>;
 };
-export declare const PHI_HREFLANG_DEFAULT_KEY = "x-default";
 /**
  * The first of the given values that is an absolute http(s) URL, without a trailing slash.
  *
@@ -27,8 +26,6 @@ export declare const PHI_HREFLANG_DEFAULT_KEY = "x-default";
  * nothing absolute -- no canonical, no alternates, no sitemap -- rather than by guessing a host.
  */
 export declare function resolvePhiSitePublicBase(...candidates: ReadonlyArray<string | null | undefined>): string | null;
-/** The absolute URL of one Public path in one locale. */
-export declare function buildPhiPublicPageUrl(publicBase: string, locale: string, path: string): string;
 /**
  * The canonical URL and the hreflang set of one Public Page, or `null` without a public base.
  *

package/helpers/phi-seo.js

@@ -1,5 +1,5 @@
 import { localizePath } from "./locale";
-export const PHI_HREFLANG_DEFAULT_KEY = "x-default";
+const PHI_HREFLANG_DEFAULT_KEY = "x-default";
 /**
  * The first of the given values that is an absolute http(s) URL, without a trailing slash.
  *
@@ -28,7 +28,7 @@ export function resolvePhiSitePublicBase(...candidates) {
     return null;
 }
 /** The absolute URL of one Public path in one locale. */
-export function buildPhiPublicPageUrl(publicBase, locale, path) {
+function buildPhiPublicPageUrl(publicBase, locale, path) {
     return `${publicBase}${localizePath(locale, path)}`;
 }
 /**

package/helpers/public-route-claims.d.ts

@@ -33,7 +33,6 @@ export type PhiPublicRoutePathCollision = {
     path: string;
     heldBy: PhiPublicRouteAddressHolder;
 };
-export declare function buildPhiPublicRouteIdentity(ownerModuleId: string, presetKey: string): string;
 /**
  * The address a route answers on: what this Site assigned it, or what it declared.
  *

package/helpers/public-route-claims.js

@@ -1,4 +1,4 @@
-export function buildPhiPublicRouteIdentity(ownerModuleId, presetKey) {
+function buildPhiPublicRouteIdentity(ownerModuleId, presetKey) {
     return `${ownerModuleId}/${presetKey}`;
 }
 /**

package/helpers/region-page-scope.d.ts

@@ -0,0 +1,26 @@
+import { type PhiCmsRegionConfig, type PhiCmsRegionKey, type PhiCmsRegionPageScope, type PhiCmsRegionPageScopeEntry, type PhiCmsRegionReveal, type PhiCmsResolvedRegionPageScope } from "../types/cms-presets";
+import { type PhiPageReference, type PhiResolvedLinkTargets } from "../types/references";
+/**
+ * The Region's Page scope as stored, or null where it stands on every Page. Only a Shell Region has one:
+ * a Page-owned Region belongs to a single Page already.
+ */
+export declare function readPhiCmsRegionPageScope(regionKey: PhiCmsRegionKey, config: PhiCmsRegionConfig | null | undefined): PhiCmsRegionPageScope | null;
+/** The entries a stored scope names, each read whole; an entry that names nothing is dropped. */
+export declare function readPhiCmsRegionPageScopeEntries(value: unknown): PhiCmsRegionPageScopeEntry[];
+/** The Pages a scope names by reference, for the render that resolves them. */
+export declare function collectPhiCmsRegionPageScopeReferences(scope: PhiCmsRegionPageScope | null): PhiPageReference[];
+/**
+ * The scope as the browser asks it, with every reference turned into the address it leads to now.
+ *
+ * A reference that does not resolve -- a Page deleted, a Module switched off -- drops out on its own.
+ * A list with nothing left in it is no rule at all, and the Region stands on every Page: an author who
+ * named Pages that are gone did not ask for a Region on no Page, and could not find it again if it were.
+ */
+export declare function resolvePhiCmsRegionPageScope(scope: PhiCmsRegionPageScope | null, links: PhiResolvedLinkTargets | null, availableLocales: readonly string[]): PhiCmsResolvedRegionPageScope | null;
+/** Whether the Region stands on the Page at `pagePath`, an address inside the Area. */
+export declare function phiCmsRegionPageScopeIncludes(scope: PhiCmsResolvedRegionPageScope | null, pagePath: string): boolean;
+/**
+ * How the Region comes into view. Only `header_top` reveals: it is the one band above the sticky Header
+ * that can leave without taking the Navigation with it.
+ */
+export declare function readPhiCmsRegionReveal(regionKey: PhiCmsRegionKey, config: PhiCmsRegionConfig | null | undefined): PhiCmsRegionReveal;

package/helpers/region-page-scope.js

@@ -0,0 +1,121 @@
+import { PHI_CMS_REGION_PAGE_SCOPE_MODES, PHI_CMS_REGION_REVEAL_MODES, PhiCmsRegionPageScopeEntryFlag, } from "../types/cms-presets";
+import { readPhiLinkTarget } from "../types/references";
+import { isPhiCmsShellOwnedRegion } from "./cms-region-keys";
+import { hasPhiFlag } from "./flags";
+import { stripLocaleAndAreaFromPathname } from "./locale";
+/*
+ * Which Pages a Shell Region stands on, and how `header_top` comes into view (SHELL.md "Region
+ * visibility per Page").
+ *
+ * The scope is stated by reference and resolved by the server for each render, with the render's own
+ * batch of link targets; the browser compares the visitor's path against what came out. The comparison
+ * stays in the browser because the Shell is a Next Layout, and a Layout of a dynamic Area is not rendered
+ * again when the visitor follows a link inside it: a rule decided on the server would hold the first
+ * Page's answer for every Page after it.
+ */
+/**
+ * The Region's Page scope as stored, or null where it stands on every Page. Only a Shell Region has one:
+ * a Page-owned Region belongs to a single Page already.
+ */
+export function readPhiCmsRegionPageScope(regionKey, config) {
+    if (!isPhiCmsShellOwnedRegion(regionKey)) {
+        return null;
+    }
+    const scope = config?.pageScope;
+    if (scope == null || !PHI_CMS_REGION_PAGE_SCOPE_MODES.includes(scope.mode) || scope.mode === "all") {
+        return null;
+    }
+    if (scope.mode === "root") {
+        return { mode: "root" };
+    }
+    return { mode: scope.mode, entries: readPhiCmsRegionPageScopeEntries(scope.entries) };
+}
+/** The entries a stored scope names, each read whole; an entry that names nothing is dropped. */
+export function readPhiCmsRegionPageScopeEntries(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.flatMap((entry) => {
+        if (entry == null || typeof entry !== "object") {
+            return [];
+        }
+        const record = entry;
+        const target = readPhiLinkTarget(record.pageLinkTarget);
+        if (target?.kind === "page") {
+            const flags = typeof record.flags === "number" ? record.flags : 0;
+            return [{ pageLinkTarget: target, ...(flags === 0 ? {} : { flags }) }];
+        }
+        const folder = typeof record.folder === "string" ? normalizePhiCmsRegionScopePath(record.folder) : null;
+        return folder == null ? [] : [{ folder }];
+    });
+}
+/** The Pages a scope names by reference, for the render that resolves them. */
+export function collectPhiCmsRegionPageScopeReferences(scope) {
+    return (scope?.entries ?? []).flatMap((entry) => "pageLinkTarget" in entry && entry.pageLinkTarget.kind === "page" ? [entry.pageLinkTarget.reference] : []);
+}
+/**
+ * The scope as the browser asks it, with every reference turned into the address it leads to now.
+ *
+ * A reference that does not resolve -- a Page deleted, a Module switched off -- drops out on its own.
+ * A list with nothing left in it is no rule at all, and the Region stands on every Page: an author who
+ * named Pages that are gone did not ask for a Region on no Page, and could not find it again if it were.
+ */
+export function resolvePhiCmsRegionPageScope(scope, links, availableLocales) {
+    if (scope == null || scope.mode === "all") {
+        return null;
+    }
+    if (scope.mode === "root") {
+        return { mode: "root" };
+    }
+    const paths = [];
+    const prefixes = [];
+    for (const entry of scope.entries ?? []) {
+        if ("folder" in entry) {
+            prefixes.push(entry.folder);
+            continue;
+        }
+        if (entry.pageLinkTarget.kind !== "page") {
+            continue;
+        }
+        const href = links?.get(entry.pageLinkTarget.reference);
+        const path = href == null
+            ? null
+            : normalizePhiCmsRegionScopePath(stripLocaleAndAreaFromPathname(href, { availableLocales: [...availableLocales] }));
+        if (path == null) {
+            continue;
+        }
+        (hasPhiFlag(entry.flags, PhiCmsRegionPageScopeEntryFlag.Subtree) ? prefixes : paths).push(path);
+    }
+    return paths.length === 0 && prefixes.length === 0 ? null : { mode: scope.mode, paths, prefixes };
+}
+/** An address inside the Area as it is compared: one leading slash, no trailing one. */
+function normalizePhiCmsRegionScopePath(path) {
+    const trimmed = path.trim();
+    if (!trimmed) {
+        return null;
+    }
+    return `/${trimmed.split("/").filter(Boolean).join("/")}`;
+}
+/** Whether the Region stands on the Page at `pagePath`, an address inside the Area. */
+export function phiCmsRegionPageScopeIncludes(scope, pagePath) {
+    if (scope == null) {
+        return true;
+    }
+    const page = normalizePhiCmsRegionScopePath(pagePath) ?? "/";
+    if (scope.mode === "root") {
+        return page === "/";
+    }
+    const matched = scope.paths.includes(page) ||
+        scope.prefixes.some((prefix) => prefix === "/" || page === prefix || page.startsWith(`${prefix}/`));
+    return scope.mode === "include" ? matched : !matched;
+}
+/**
+ * How the Region comes into view. Only `header_top` reveals: it is the one band above the sticky Header
+ * that can leave without taking the Navigation with it.
+ */
+export function readPhiCmsRegionReveal(regionKey, config) {
+    const reveal = config?.reveal;
+    return regionKey === "header_top" && reveal != null && PHI_CMS_REGION_REVEAL_MODES.includes(reveal)
+        ? reveal
+        : "always";
+}

package/helpers/renderable-block-defaults.d.ts

@@ -1,9 +1,6 @@
 import type { PhiRenderableBlockAnchor, PhiRenderableBlockBase, PhiRenderableBlockEffects, PhiRenderableBlockTransition, PhiRenderableBlockViewportEffect, PhiRenderableBlockVisibility } from "../types";
 export declare const PHI_RENDERABLE_BLOCK_DEFAULT_RENDER_MODE: "live";
 export declare const PHI_RENDERABLE_BLOCK_DEFAULT_VISIBILITY: PhiRenderableBlockVisibility;
-export declare const PHI_RENDERABLE_BLOCK_DEFAULT_ACCESS_POLICY: {
-    readonly access: "anyone";
-};
 export declare const PHI_RENDERABLE_BLOCK_DEFAULT_VIEWPORT_FLAGS = 0;
 export declare const PHI_RENDERABLE_BLOCK_DEFAULT_ENABLED = true;
 export declare const PHI_RENDERABLE_BLOCK_DEFAULT_DEBUG_MODE = false;

package/helpers/renderable-block-defaults.js

@@ -1,7 +1,7 @@
 import { PHI_VIEWER_ACCESS_ANYONE } from "../types/access";
 export const PHI_RENDERABLE_BLOCK_DEFAULT_RENDER_MODE = "live";
 export const PHI_RENDERABLE_BLOCK_DEFAULT_VISIBILITY = "visible";
-export const PHI_RENDERABLE_BLOCK_DEFAULT_ACCESS_POLICY = PHI_VIEWER_ACCESS_ANYONE;
+const PHI_RENDERABLE_BLOCK_DEFAULT_ACCESS_POLICY = PHI_VIEWER_ACCESS_ANYONE;
 export const PHI_RENDERABLE_BLOCK_DEFAULT_VIEWPORT_FLAGS = 0;
 export const PHI_RENDERABLE_BLOCK_DEFAULT_ENABLED = true;
 export const PHI_RENDERABLE_BLOCK_DEFAULT_DEBUG_MODE = false;

package/helpers/renderable-block-normalizers.d.ts

@@ -0,0 +1,26 @@
+import type { PhiRenderableBlockCapabilities, PhiRenderableBlockResponsiveSize, PhiRenderableBlockRuntime, PhiRenderableBlockSize, PhiResponsiveLength } from "../types/renderable-block";
+/**
+ * One stored length, plain or per profile.
+ *
+ * A profile value is `{ compact?, medium?, wide? }` and at least one of the three has to be a length,
+ * or it is not a profile value and states nothing. Read here rather than accepted as it stands, so a
+ * stored object cannot carry anything else into the config.
+ */
+export declare function readPhiResponsiveLength(value: unknown): PhiResponsiveLength | undefined;
+/**
+ * A size pair without its empty axes, or nothing where both are empty. Generic over the length, because
+ * the same stripping serves a profile pair and a plain one.
+ */
+export declare function stripPhiRenderableBlockSize<TLength>(value: {
+    width?: TLength | null;
+    height?: TLength | null;
+} | null | undefined): {
+    height?: NonNullable<TLength> | undefined;
+    width?: NonNullable<TLength> | undefined;
+} | undefined;
+/** A stored size pair, each axis plain or per profile; a bare length is a width. */
+export declare function normalizePhiRenderableBlockResponsiveSize(value: unknown): PhiRenderableBlockResponsiveSize | undefined;
+/** A stored size pair of plain lengths (a collapsed-size hint, a Region draft); a bare length is a width. */
+export declare function normalizePhiRenderableBlockSize(value: unknown): PhiRenderableBlockSize | undefined;
+export declare function normalizePhiRenderableBlockCapabilities(value: unknown): PhiRenderableBlockCapabilities | undefined;
+export declare function normalizePhiRenderableBlockRuntime(value: unknown): PhiRenderableBlockRuntime | undefined;