@phis/ui 0.1.0

package/helpers/cms-preset-nodes.d.ts

@@ -0,0 +1,41 @@
+import { buildPhiCmsLayoutNode, buildPhiCmsWidgetNode } from "./cms-node-factories";
+import type { PhiCmsContentWidgetNode, PhiCmsLayoutNode } from "../types/cms";
+import type { PhiCmsInstanceId } from "../types/cms-instance-id";
+type PhiCmsPresetNodeDefaults = {
+    siteId: number;
+    visibilityMask: number;
+    status?: number;
+    flags?: number;
+};
+type PhiCmsPresetLayoutInput = Parameters<typeof buildPhiCmsLayoutNode>[0];
+type PhiCmsPresetWidgetInput = Parameters<typeof buildPhiCmsWidgetNode>[0];
+type PhiCmsPresetNodeInput<TInput> = Omit<TInput, "siteId" | "visibilityMask" | "status" | "flags" | "sortOrder"> & Partial<Pick<TInput & {
+    sortOrder?: number;
+}, "sortOrder">> & {
+    status?: number;
+    flags?: number;
+};
+/**
+ * The parts of a node that a Preset repeats rather than decides.
+ *
+ * A placement is four things -- what it is, where it sits, what it is called, how it is configured --
+ * and it was written as eleven, because `siteId`, `visibilityMask`, `status`, `flags`, `contentId` and
+ * `sortOrder` are the same for every node of a page and were spelled out on each of them. That is not
+ * detail a reader of a Preset needs; it is noise they have to look past to find the four that matter,
+ * and it is six chances to write the wrong page's `visibilityMask` on one node out of twenty.
+ *
+ * `sortOrder` follows `slotIndex` unless it is given. Presets set them to the same number almost
+ * everywhere, and where they differ it is deliberate and worth writing down.
+ */
+export declare function createPhiCmsPresetNodes(defaults: PhiCmsPresetNodeDefaults): {
+    layout(input: PhiCmsPresetNodeInput<PhiCmsPresetLayoutInput>): PhiCmsLayoutNode;
+    widget(input: PhiCmsPresetNodeInput<PhiCmsPresetWidgetInput>): PhiCmsContentWidgetNode;
+    /**
+     * Widgets stacked in one Layout, in the order they are written.
+     *
+     * Slots are counted for them, because a stack is a sequence and renumbering one by hand after
+     * inserting something in the middle is exactly the kind of edit that goes wrong quietly.
+     */
+    stack(parentLayoutNodeId: PhiCmsInstanceId, entries: readonly Omit<PhiCmsPresetNodeInput<PhiCmsPresetWidgetInput>, "parentLayoutNodeId" | "slotIndex">[], startAt?: number): PhiCmsContentWidgetNode[];
+};
+export {};

package/helpers/cms-preset-nodes.js

@@ -0,0 +1,55 @@
+import { buildPhiCmsLayoutNode, buildPhiCmsWidgetNode } from "./cms-node-factories";
+import { PhiCmsStatus } from "../constants/phi-cms";
+/**
+ * The parts of a node that a Preset repeats rather than decides.
+ *
+ * A placement is four things -- what it is, where it sits, what it is called, how it is configured --
+ * and it was written as eleven, because `siteId`, `visibilityMask`, `status`, `flags`, `contentId` and
+ * `sortOrder` are the same for every node of a page and were spelled out on each of them. That is not
+ * detail a reader of a Preset needs; it is noise they have to look past to find the four that matter,
+ * and it is six chances to write the wrong page's `visibilityMask` on one node out of twenty.
+ *
+ * `sortOrder` follows `slotIndex` unless it is given. Presets set them to the same number almost
+ * everywhere, and where they differ it is deliberate and worth writing down.
+ */
+export function createPhiCmsPresetNodes(defaults) {
+    const common = {
+        siteId: defaults.siteId,
+        visibilityMask: defaults.visibilityMask,
+        status: defaults.status ?? PhiCmsStatus.Published,
+        flags: defaults.flags ?? 0,
+    };
+    return {
+        layout(input) {
+            return buildPhiCmsLayoutNode({
+                ...common,
+                sortOrder: input.slotIndex,
+                ...input,
+            });
+        },
+        widget(input) {
+            return buildPhiCmsWidgetNode({
+                ...common,
+                sortOrder: input.slotIndex,
+                contentId: null,
+                ...input,
+            });
+        },
+        /**
+         * Widgets stacked in one Layout, in the order they are written.
+         *
+         * Slots are counted for them, because a stack is a sequence and renumbering one by hand after
+         * inserting something in the middle is exactly the kind of edit that goes wrong quietly.
+         */
+        stack(parentLayoutNodeId, entries, startAt = 0) {
+            return entries.map((entry, index) => buildPhiCmsWidgetNode({
+                ...common,
+                contentId: null,
+                parentLayoutNodeId,
+                slotIndex: startAt + index,
+                sortOrder: startAt + index,
+                ...entry,
+            }));
+        },
+    };
+}

package/helpers/cms-region-keys.d.ts

@@ -0,0 +1,21 @@
+export declare const PHI_CMS_REGION_TYPE_BY_KEY: {
+    readonly header_top: 10;
+    readonly header_main: 11;
+    readonly header_bottom: 12;
+    readonly hero: 25;
+    readonly sider_left: 20;
+    readonly sider_right: 21;
+    readonly content: 30;
+    readonly footer_top: 39;
+    readonly footer_main: 40;
+    readonly footer_bottom: 41;
+    readonly drawer_right: 50;
+};
+export type PhiCmsRegionKey = keyof typeof PHI_CMS_REGION_TYPE_BY_KEY;
+export declare const PHI_CMS_SHELL_OWNED_REGION_KEYS: readonly ["header_top", "header_main", "sider_left", "footer_main", "footer_bottom"];
+export declare const PHI_CMS_PAGE_OWNED_REGION_KEYS: readonly ["header_bottom", "hero", "content", "sider_right", "footer_top", "drawer_right"];
+export declare function isPhiCmsShellOwnedRegion(regionKey: string): regionKey is (typeof PHI_CMS_SHELL_OWNED_REGION_KEYS)[number];
+export declare function isPhiCmsPageOwnedRegion(regionKey: string): regionKey is (typeof PHI_CMS_PAGE_OWNED_REGION_KEYS)[number];
+export declare const PHI_CMS_REGION_KEY_BY_TYPE: Record<number, PhiCmsRegionKey>;
+export declare function resolvePhiCmsRegionType(regionKey: string | null | undefined): 10 | 21 | 12 | 25 | 11 | 20 | 30 | 39 | 40 | 41 | 50;
+export declare function resolvePhiCmsRegionKey(regionType: number | null | undefined): "content" | "header_top" | "header_main" | "header_bottom" | "sider_left" | "sider_right" | "hero" | "footer_top" | "footer_main" | "footer_bottom" | "drawer_right" | undefined;

package/helpers/cms-region-keys.js

@@ -0,0 +1,44 @@
+import { PhiCmsRegionType } from "../constants/phi-cms";
+export const PHI_CMS_REGION_TYPE_BY_KEY = {
+    header_top: PhiCmsRegionType.HeaderTop,
+    header_main: PhiCmsRegionType.HeaderMain,
+    header_bottom: PhiCmsRegionType.HeaderBottom,
+    hero: PhiCmsRegionType.Hero,
+    sider_left: PhiCmsRegionType.SiderLeft,
+    sider_right: PhiCmsRegionType.SiderRight,
+    content: PhiCmsRegionType.Content,
+    footer_top: PhiCmsRegionType.FooterTop,
+    footer_main: PhiCmsRegionType.Footer,
+    footer_bottom: PhiCmsRegionType.FooterBottom,
+    drawer_right: PhiCmsRegionType.Drawer,
+};
+export const PHI_CMS_SHELL_OWNED_REGION_KEYS = [
+    "header_top",
+    "header_main",
+    "sider_left",
+    "footer_main",
+    "footer_bottom",
+];
+export const PHI_CMS_PAGE_OWNED_REGION_KEYS = [
+    "header_bottom",
+    "hero",
+    "content",
+    "sider_right",
+    "footer_top",
+    "drawer_right",
+];
+export function isPhiCmsShellOwnedRegion(regionKey) {
+    return PHI_CMS_SHELL_OWNED_REGION_KEYS.includes(regionKey);
+}
+export function isPhiCmsPageOwnedRegion(regionKey) {
+    return PHI_CMS_PAGE_OWNED_REGION_KEYS.includes(regionKey);
+}
+export const PHI_CMS_REGION_KEY_BY_TYPE = Object.fromEntries(Object.entries(PHI_CMS_REGION_TYPE_BY_KEY).map(([key, type]) => [type, key]));
+export function resolvePhiCmsRegionType(regionKey) {
+    return regionKey && regionKey in PHI_CMS_REGION_TYPE_BY_KEY
+        ? PHI_CMS_REGION_TYPE_BY_KEY[regionKey]
+        : PhiCmsRegionType.Content;
+}
+export function resolvePhiCmsRegionKey(regionType) {
+    return regionType == null ? undefined : PHI_CMS_REGION_KEY_BY_TYPE[regionType];
+}

package/helpers/cms-routing.d.ts

@@ -0,0 +1,4 @@
+export declare const PHI_CMS_SPECIAL_ROOTS: ("app" | "admin" | "builder" | "editor" | "accounting")[];
+export type PhiCmsSpecialRoot = (typeof PHI_CMS_SPECIAL_ROOTS)[number];
+export declare function isKnownSpecialCmsRoot(root: string): boolean;
+export declare function normalizePhiCmsRouteSegment(segment: string): string;

package/helpers/cms-routing.js

@@ -0,0 +1,9 @@
+import { PHI_CMS_SPECIAL_AREA_KEYS } from "../constants/cms-areas";
+export const PHI_CMS_SPECIAL_ROOTS = PHI_CMS_SPECIAL_AREA_KEYS;
+const SPECIAL_ROOT_SET = new Set(PHI_CMS_SPECIAL_ROOTS);
+export function isKnownSpecialCmsRoot(root) {
+    return SPECIAL_ROOT_SET.has(root.trim().toLowerCase());
+}
+export function normalizePhiCmsRouteSegment(segment) {
+    return segment.trim().replace(/%2b/gi, "+");
+}

package/helpers/cms-scope-search-params.d.ts

@@ -0,0 +1,14 @@
+import { type PhiBuilderAreaKey } from "../constants/cms-areas";
+import type { PhiRuntimeModuleId } from "../types/cms-plugins";
+export declare const PHI_BUILDER_AREA_SEARCH_PARAM = "phiBuilderArea";
+export declare const PHI_BUILDER_PAGE_SEARCH_PARAM = "phiBuilderPage";
+export declare const PHI_BUILDER_NAVIGATION_KEY_SEARCH_PARAM = "navKey";
+export declare const PHI_BUILDER_REVISIONS_KIND_SEARCH_PARAM = "revisionKind";
+export declare const PHI_BUILDER_REVISIONS_SCOPE_SEARCH_PARAM = "revisionScope";
+export declare const PHI_BUILDER_THEME_KEY_SEARCH_PARAM = "themeKey";
+export declare const PHI_BUILDER_RUNTIME_MODULES_SEARCH_PARAM = "phiBuilderModules";
+export declare function normalizePhiBuilderAreaSearchParam(value: unknown): PhiBuilderAreaKey | null;
+export declare function normalizePhiBuilderPageSearchParam(value: unknown): string | null;
+export declare function serializePhiBuilderRuntimeModuleIdsSearchParam(moduleIds: readonly PhiRuntimeModuleId[]): string;
+export declare function normalizePhiBuilderRuntimeModuleIdsSearchParam(value: unknown): PhiRuntimeModuleId[] | null;
+export declare function normalizePhiBuilderRevisionsKindSearchParam(value: unknown): "area" | "page" | "navigation" | "theme" | null;

package/helpers/cms-scope-search-params.js

@@ -0,0 +1,32 @@
+import { isPhiBuilderAreaKey } from "../constants/cms-areas";
+import { readPhiRuntimeModuleIds } from "../plugins/runtime-modules/settings";
+export const PHI_BUILDER_AREA_SEARCH_PARAM = "phiBuilderArea";
+export const PHI_BUILDER_PAGE_SEARCH_PARAM = "phiBuilderPage";
+export const PHI_BUILDER_NAVIGATION_KEY_SEARCH_PARAM = "navKey";
+export const PHI_BUILDER_REVISIONS_KIND_SEARCH_PARAM = "revisionKind";
+export const PHI_BUILDER_REVISIONS_SCOPE_SEARCH_PARAM = "revisionScope";
+export const PHI_BUILDER_THEME_KEY_SEARCH_PARAM = "themeKey";
+export const PHI_BUILDER_RUNTIME_MODULES_SEARCH_PARAM = "phiBuilderModules";
+export function normalizePhiBuilderAreaSearchParam(value) {
+    return isPhiBuilderAreaKey(value) ? value : null;
+}
+export function normalizePhiBuilderPageSearchParam(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+export function serializePhiBuilderRuntimeModuleIdsSearchParam(moduleIds) {
+    return JSON.stringify(moduleIds);
+}
+export function normalizePhiBuilderRuntimeModuleIdsSearchParam(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        return null;
+    }
+    try {
+        return readPhiRuntimeModuleIds(JSON.parse(value));
+    }
+    catch {
+        return null;
+    }
+}
+export function normalizePhiBuilderRevisionsKindSearchParam(value) {
+    return value === "area" || value === "page" || value === "navigation" || value === "theme" ? value : null;
+}

package/helpers/css-length.d.ts

@@ -0,0 +1 @@
+export declare function resolvePhiCssLength(value: unknown): string | undefined;

package/helpers/css-length.js

@@ -0,0 +1,10 @@
+export function resolvePhiCssLength(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return `${value}px`;
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed || undefined;
+    }
+    return undefined;
+}

package/helpers/external-href.d.ts

@@ -0,0 +1 @@
+export declare function isPhiExternalHref(href: string): boolean;

package/helpers/external-href.js

@@ -0,0 +1,3 @@
+export function isPhiExternalHref(href) {
+    return /^(https?:)?\/\//.test(href) || href.startsWith("mailto:") || href.startsWith("tel:");
+}

package/helpers/flags.d.ts

@@ -0,0 +1 @@
+export declare function hasPhiFlag(flags: number | null | undefined, flag: number): boolean;

package/helpers/flags.js

@@ -0,0 +1,3 @@
+export function hasPhiFlag(flags, flag) {
+    return ((flags ?? 0) & flag) === flag;
+}

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

@@ -0,0 +1,2 @@
+export declare function formatPhiDate(value: string | null | undefined): string;
+export declare function formatPhiDateTime(value: string | null | undefined): string;

package/helpers/format-date-time.js

@@ -0,0 +1,25 @@
+const PHI_DATE_TIME_FORMATTER = new Intl.DateTimeFormat(undefined, {
+    dateStyle: "medium",
+    timeStyle: "short",
+});
+const PHI_DATE_FORMATTER = new Intl.DateTimeFormat(undefined, {
+    dateStyle: "medium",
+});
+function readPhiDate(value) {
+    if (!value) {
+        return null;
+    }
+    const timestamp = Date.parse(value);
+    if (Number.isNaN(timestamp)) {
+        return null;
+    }
+    return new Date(timestamp);
+}
+export function formatPhiDate(value) {
+    const date = readPhiDate(value);
+    return date ? PHI_DATE_FORMATTER.format(date) : value || "—";
+}
+export function formatPhiDateTime(value) {
+    const date = readPhiDate(value);
+    return date ? PHI_DATE_TIME_FORMATTER.format(date) : value || "—";
+}

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

@@ -0,0 +1,28 @@
+/**
+ * The authoring markers a layout puts in the DOM, and the one question that decides whether it should.
+ *
+ * `data-phi-layout-debug-layer`, `phi-layout-scaffold-slot` and `data-phi-layout-has-content` describe
+ * the tree for the Builder's scaffold. Nothing else reads them: no other stylesheet, no JavaScript. They
+ * were emitted unconditionally, so every visitor of every published page carried them -- bytes on each
+ * render, and a description of the authoring model handed to people who cannot author.
+ *
+ * Whether a render is an authoring one is not a new flag. A layout already receives `editSlotAction`,
+ * `editSlotLabels` and `capabilities`, all three of them things only the Builder passes and all three
+ * absent on a published page. Reading them is what keeps this from becoming another value someone has
+ * to remember to thread. `validate-authoring-marker-contracts.ts` pins the coupling, because an
+ * implicit signal that nothing checks is an implicit signal that quietly stops being true.
+ */
+export type PhiLayoutAuthoringSignal = {
+    editSlotAction?: unknown;
+    editSlotLabels?: unknown;
+    capabilities?: unknown;
+};
+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. */
+export declare function phiLayoutSlotClassName(authoring: boolean, ownClassName?: string): string | undefined;

package/helpers/layout-authoring-markers.js

@@ -0,0 +1,33 @@
+/**
+ * The authoring markers a layout puts in the DOM, and the one question that decides whether it should.
+ *
+ * `data-phi-layout-debug-layer`, `phi-layout-scaffold-slot` and `data-phi-layout-has-content` describe
+ * the tree for the Builder's scaffold. Nothing else reads them: no other stylesheet, no JavaScript. They
+ * were emitted unconditionally, so every visitor of every published page carried them -- bytes on each
+ * render, and a description of the authoring model handed to people who cannot author.
+ *
+ * Whether a render is an authoring one is not a new flag. A layout already receives `editSlotAction`,
+ * `editSlotLabels` and `capabilities`, all three of them things only the Builder passes and all three
+ * absent on a published page. Reading them is what keeps this from becoming another value someone has
+ * to remember to thread. `validate-authoring-marker-contracts.ts` pins the coupling, because an
+ * implicit signal that nothing checks is an implicit signal that quietly stops being true.
+ */
+export function isPhiLayoutAuthoringRender(signal) {
+    return signal.editSlotAction != null || signal.editSlotLabels != null || signal.capabilities != null;
+}
+/** The layout band's marker, and nothing at all outside authoring. */
+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) {
+    return authoring ? "phi-layout-scaffold-slot" : undefined;
+}
+/** Whether a slot holds something, which only the scaffold asks. */
+export function phiLayoutSlotContentMarker(authoring, hasContent) {
+    return authoring ? (hasContent ? "true" : "false") : undefined;
+}
+/** Joins a layout's own slot class with the marker, dropping what is absent. */
+export function phiLayoutSlotClassName(authoring, ownClassName) {
+    return [ownClassName, phiLayoutScaffoldSlotMarker(authoring)].filter(Boolean).join(" ") || undefined;
+}

package/helpers/layout-padding-field.d.ts

@@ -0,0 +1,5 @@
+export declare const PHI_LAYOUT_PADDING_FIELDS: {
+    key: string;
+    type: "padding";
+    label: string;
+}[];

package/helpers/layout-padding-field.js

@@ -0,0 +1,7 @@
+export const PHI_LAYOUT_PADDING_FIELDS = [
+    {
+        key: "padding",
+        type: "padding",
+        label: "Padding",
+    },
+];

package/helpers/layout-style.d.ts

@@ -0,0 +1,45 @@
+import type { CSSProperties } from "react";
+import { type PhiLayoutEffectId, type PhiShadow } from "../types/layout-style";
+/**
+ * What each glass strength is made of.
+ *
+ * The two numbers move together. The radius alone decides how much of the ground survives as shape,
+ * the share decides how much of it survives as light, and changing one without the other gives a
+ * window that is dirty rather than glass that is lighter.
+ */
+export declare const PHI_GLASS_LAYOUT_EFFECT_DEFINITIONS: {
+    readonly glass: {
+        readonly filter: "blur(24px) saturate(1.2)";
+        readonly strengthPercent: 36;
+    };
+    readonly haze: {
+        readonly filter: "blur(10px) saturate(1.1)";
+        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)";
+    readonly strong: "var(--ant-box-shadow)";
+};
+export declare function resolvePhiShadow(value: PhiShadow | null | undefined): CSSProperties["boxShadow"] | undefined;
+export declare function resolvePhiLayoutEffectStyle({ effect, background, }: {
+    effect?: PhiLayoutEffectId | null;
+    background?: CSSProperties["background"];
+}): CSSProperties | undefined;
+export declare function composePhiLayoutEffectStyle(baseStyle: CSSProperties, effectStyle: CSSProperties | null | undefined): CSSProperties;
+export declare function combinePhiBoxShadows(...values: Array<CSSProperties["boxShadow"] | null | undefined>): CSSProperties["boxShadow"] | undefined;

package/helpers/layout-style.js

@@ -0,0 +1,92 @@
+import { PHI_COLOR, PHI_SHADOW } from "../theme/antd-css-var-contract";
+import { isPhiGlassLayoutEffectId, } from "../types/layout-style";
+/**
+ * What each glass strength is made of.
+ *
+ * The two numbers move together. The radius alone decides how much of the ground survives as shape,
+ * the share decides how much of it survives as light, and changing one without the other gives a
+ * window that is dirty rather than glass that is lighter.
+ */
+export const PHI_GLASS_LAYOUT_EFFECT_DEFINITIONS = {
+    glass: { filter: "blur(24px) saturate(1.2)", strengthPercent: 36 },
+    haze: { filter: "blur(10px) saturate(1.1)", strengthPercent: 60 },
+};
+function resolvePhiGlassBackground(background, strengthPercent) {
+    const base = typeof background === "string" && background.trim()
+        ? background
+        : 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,
+    strong: PHI_SHADOW.primary,
+};
+export function resolvePhiShadow(value) {
+    if (value == null) {
+        return undefined;
+    }
+    return typeof value === "string"
+        ? PHI_SHADOW_DEFINITIONS[value]
+        : value.value;
+}
+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];
+}
+export function composePhiLayoutEffectStyle(baseStyle, effectStyle) {
+    if (!effectStyle) {
+        return baseStyle;
+    }
+    const effectBackground = effectStyle.background ?? effectStyle.backgroundColor;
+    if (effectBackground == null) {
+        return { ...baseStyle, ...effectStyle };
+    }
+    const baseRest = { ...baseStyle };
+    delete baseRest.background;
+    delete baseRest.backgroundColor;
+    const effectRest = { ...effectStyle };
+    delete effectRest.background;
+    delete effectRest.backgroundColor;
+    return {
+        ...baseRest,
+        ...effectRest,
+        backgroundColor: effectBackground,
+    };
+}
+export function combinePhiBoxShadows(...values) {
+    const shadows = values.filter((value) => typeof value === "string" && value !== "none");
+    return shadows.length > 0 ? shadows.join(", ") : values.some((value) => value === "none") ? "none" : undefined;
+}

package/helpers/locale.d.ts

@@ -0,0 +1,23 @@
+import { type PhiCmsAreaKey } from "../constants/cms-areas";
+export { PHI_CANONICAL_SOURCE_LOCALE } from "@phis/contracts/locale";
+export declare const SUPPORTED_CMS_AREAS: readonly ["public", "app", "admin", "builder", "editor", "accounting"];
+export type SiteLocale = string;
+export type SiteArea = PhiCmsAreaKey;
+export type NormalizeLocaleOptions = {
+    defaultLocale?: string | null | undefined;
+    availableLocales?: readonly string[] | null | undefined;
+};
+export declare function normalizeLocale(input: string | null | undefined, options?: NormalizeLocaleOptions): SiteLocale;
+export declare function localizePath(locale: SiteLocale | string, targetPath: string): string;
+/**
+ * The path for a staff Area, which carries no locale prefix.
+ *
+ * Only the Public Area is localized in the URL; `/admin`, `/builder`, `/editor`, `/accounting` and
+ * `/app` are routed by their own segment. A caller that has no locale to offer wants this rather than
+ * a locale it had to invent.
+ */
+export declare function phiAreaPath(area: SiteArea | string, targetPath: string): string;
+export declare function localizeAreaPath(locale: SiteLocale | string, area: SiteArea | string, targetPath: string): string;
+export declare function resolvePhiNavHref(locale: SiteLocale | string, currentArea: SiteArea | string, href: string): string;
+export declare function stripLocaleFromPathname(pathname: string, options?: Pick<NormalizeLocaleOptions, "defaultLocale" | "availableLocales">): string;
+export declare function stripLocaleAndAreaFromPathname(pathname: string, options?: Pick<NormalizeLocaleOptions, "defaultLocale" | "availableLocales">): string;