@aglyn/shared-ui-theme 1.0.0-beta.143

package/src/lib/util/scheme-route-segment.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The visitor's scheme, as a path segment (AGL-2708).
+ *
+ * A published page resolves its dark scheme in JS rather than in CSS, so the
+ * scheme has to be decided before the first render. Reading it from the
+ * request inside the render — `cookies()` in a layout — decides it correctly
+ * but makes the route dynamic, and the catch-all page beneath declares
+ * `revalidate`: on the regeneration path Next renders that segment in a static
+ * context, where a dynamic API throws `DYNAMIC_SERVER_USAGE`. Per-visitor
+ * theming and ONE cached document are irreconcilable.
+ *
+ * Per-SCHEME theming and TWO cached documents are not. This module is that
+ * seam: the middleware resolves the scheme from the request — where reading
+ * cookies and headers costs nothing, because middleware runs ahead of the
+ * cache on every request — and spends it as a path segment. Next's route cache
+ * keys on the pathname, so `light` and `dark` become two entries of the same
+ * page instead of one entry that cannot answer either.
+ *
+ * ⚠️ TWO SEGMENTS, NOT FOUR. The request carries two separate answers — the
+ * visitor's explicit choice (cookie) and their device's preference (client
+ * hint) — and `useThemeModeState` keeps them apart so the switcher can show
+ * "Device default" checked rather than the scheme the device happens to be in.
+ * Encoding both would be four cache entries per page. This encodes only what
+ * they RESOLVE to, because that is the only part that changes a pixel: which
+ * radio is checked is settled at hydration from the cookie the browser already
+ * has, inside a menu a visitor has to open before they can see it. Four-fold
+ * cache multiplication is a poor price for the checked state of a hidden
+ * control, on a page that is billed per view.
+ *
+ * Nothing here imports React, MUI or `js-cookie`, and its one import is a type
+ * erased at compile time — the same constraint `util/theme-mode-cookie` and
+ * `util/color-scheme-hint` hold themselves to, and for the same two reasons:
+ * a Server Component may take it without pulling the theme library's context
+ * providers into the RSC graph, and the edge middleware may take it at all.
+ */
+import type { ThemeMode } from '../hocs/create-with-theme-provider';
+/**
+ * Every spelling the segment is allowed to take.
+ *
+ * A closed set on purpose: the segment is written by our own middleware and
+ * read back by a route, so an unknown value is never a visitor's preference —
+ * it is a stale link, a crawler walking a guessed URL, or a bug. Each such
+ * request must still render a page, which is what `parseSchemeRouteSegment`
+ * guarantees by resolving anything unrecognized to the light default rather
+ * than throwing.
+ */
+export declare const SCHEME_ROUTE_SEGMENTS: readonly ["light", "dark"];
+export type SchemeRouteSegment = (typeof SCHEME_ROUTE_SEGMENTS)[number];
+/**
+ * The scheme a request resolves to, as the segment that will carry it.
+ *
+ * This is the same precedence `useThemeModeState` applies on the client — a
+ * stated preference outranks a device default, and light is what remains when
+ * the request said neither — expressed once here so the server render and the
+ * hydration that follows it cannot disagree about which document was owed.
+ *
+ * `'system'` is not a scheme. The switcher writes it to mean "follow the
+ * device", and `parseThemeModeCookie` already reads it back as `null`; it is
+ * rejected here too so a caller passing a raw cookie value cannot smuggle it
+ * in as a choice.
+ *
+ * ⚠️ Light for a request that named nothing is a FALLBACK, not a default
+ * preference. Firefox and Safari send no client hint, so their visitors reach
+ * this with two nulls and are served the light document, then settle on their
+ * real device scheme once `prefers-color-scheme` can be evaluated — the same
+ * hydration-time settle those browsers have always had here. Choosing dark
+ * instead would not fix them; it would only move the flip to the other half of
+ * their visitors.
+ */
+export declare function resolveSchemeRouteSegment(chosen: ThemeMode, device: ThemeMode): SchemeRouteSegment;
+/**
+ * A path segment as the scheme to render.
+ *
+ * Total, by construction: an absent, misspelled or hostile segment renders the
+ * light document rather than refusing. A route that 500s on an unrecognized
+ * segment would turn a stale bookmark into an error page, and this segment is
+ * in the URL of every cached page on the site.
+ */
+export declare function parseSchemeRouteSegment(value: string | undefined | null): SchemeRouteSegment;

package/src/lib/util/scheme-route-segment.js

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * The visitor's scheme, as a path segment (AGL-2708).
+ *
+ * A published page resolves its dark scheme in JS rather than in CSS, so the
+ * scheme has to be decided before the first render. Reading it from the
+ * request inside the render — `cookies()` in a layout — decides it correctly
+ * but makes the route dynamic, and the catch-all page beneath declares
+ * `revalidate`: on the regeneration path Next renders that segment in a static
+ * context, where a dynamic API throws `DYNAMIC_SERVER_USAGE`. Per-visitor
+ * theming and ONE cached document are irreconcilable.
+ *
+ * Per-SCHEME theming and TWO cached documents are not. This module is that
+ * seam: the middleware resolves the scheme from the request — where reading
+ * cookies and headers costs nothing, because middleware runs ahead of the
+ * cache on every request — and spends it as a path segment. Next's route cache
+ * keys on the pathname, so `light` and `dark` become two entries of the same
+ * page instead of one entry that cannot answer either.
+ *
+ * ⚠️ TWO SEGMENTS, NOT FOUR. The request carries two separate answers — the
+ * visitor's explicit choice (cookie) and their device's preference (client
+ * hint) — and `useThemeModeState` keeps them apart so the switcher can show
+ * "Device default" checked rather than the scheme the device happens to be in.
+ * Encoding both would be four cache entries per page. This encodes only what
+ * they RESOLVE to, because that is the only part that changes a pixel: which
+ * radio is checked is settled at hydration from the cookie the browser already
+ * has, inside a menu a visitor has to open before they can see it. Four-fold
+ * cache multiplication is a poor price for the checked state of a hidden
+ * control, on a page that is billed per view.
+ *
+ * Nothing here imports React, MUI or `js-cookie`, and its one import is a type
+ * erased at compile time — the same constraint `util/theme-mode-cookie` and
+ * `util/color-scheme-hint` hold themselves to, and for the same two reasons:
+ * a Server Component may take it without pulling the theme library's context
+ * providers into the RSC graph, and the edge middleware may take it at all.
+ */ /**
+ * Every spelling the segment is allowed to take.
+ *
+ * A closed set on purpose: the segment is written by our own middleware and
+ * read back by a route, so an unknown value is never a visitor's preference —
+ * it is a stale link, a crawler walking a guessed URL, or a bug. Each such
+ * request must still render a page, which is what `parseSchemeRouteSegment`
+ * guarantees by resolving anything unrecognized to the light default rather
+ * than throwing.
+ */ export const SCHEME_ROUTE_SEGMENTS = [
+    'light',
+    'dark'
+];
+/**
+ * The scheme a request resolves to, as the segment that will carry it.
+ *
+ * This is the same precedence `useThemeModeState` applies on the client — a
+ * stated preference outranks a device default, and light is what remains when
+ * the request said neither — expressed once here so the server render and the
+ * hydration that follows it cannot disagree about which document was owed.
+ *
+ * `'system'` is not a scheme. The switcher writes it to mean "follow the
+ * device", and `parseThemeModeCookie` already reads it back as `null`; it is
+ * rejected here too so a caller passing a raw cookie value cannot smuggle it
+ * in as a choice.
+ *
+ * ⚠️ Light for a request that named nothing is a FALLBACK, not a default
+ * preference. Firefox and Safari send no client hint, so their visitors reach
+ * this with two nulls and are served the light document, then settle on their
+ * real device scheme once `prefers-color-scheme` can be evaluated — the same
+ * hydration-time settle those browsers have always had here. Choosing dark
+ * instead would not fix them; it would only move the flip to the other half of
+ * their visitors.
+ */ export function resolveSchemeRouteSegment(chosen, device) {
+    const scheme = isScheme(chosen) ? chosen : isScheme(device) ? device : 'light';
+    return scheme;
+}
+/**
+ * A path segment as the scheme to render.
+ *
+ * Total, by construction: an absent, misspelled or hostile segment renders the
+ * light document rather than refusing. A route that 500s on an unrecognized
+ * segment would turn a stale bookmark into an error page, and this segment is
+ * in the URL of every cached page on the site.
+ */ export function parseSchemeRouteSegment(value) {
+    return value === 'dark' ? 'dark' : 'light';
+}
+function isScheme(mode) {
+    return mode === 'light' || mode === 'dark';
+}
+
+//# sourceMappingURL=scheme-route-segment.js.map

package/src/lib/util/scheme-route-segment.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/theme/src/lib/util/scheme-route-segment.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The visitor's scheme, as a path segment (AGL-2708).\n *\n * A published page resolves its dark scheme in JS rather than in CSS, so the\n * scheme has to be decided before the first render. Reading it from the\n * request inside the render — `cookies()` in a layout — decides it correctly\n * but makes the route dynamic, and the catch-all page beneath declares\n * `revalidate`: on the regeneration path Next renders that segment in a static\n * context, where a dynamic API throws `DYNAMIC_SERVER_USAGE`. Per-visitor\n * theming and ONE cached document are irreconcilable.\n *\n * Per-SCHEME theming and TWO cached documents are not. This module is that\n * seam: the middleware resolves the scheme from the request — where reading\n * cookies and headers costs nothing, because middleware runs ahead of the\n * cache on every request — and spends it as a path segment. Next's route cache\n * keys on the pathname, so `light` and `dark` become two entries of the same\n * page instead of one entry that cannot answer either.\n *\n * ⚠️ TWO SEGMENTS, NOT FOUR. The request carries two separate answers — the\n * visitor's explicit choice (cookie) and their device's preference (client\n * hint) — and `useThemeModeState` keeps them apart so the switcher can show\n * \"Device default\" checked rather than the scheme the device happens to be in.\n * Encoding both would be four cache entries per page. This encodes only what\n * they RESOLVE to, because that is the only part that changes a pixel: which\n * radio is checked is settled at hydration from the cookie the browser already\n * has, inside a menu a visitor has to open before they can see it. Four-fold\n * cache multiplication is a poor price for the checked state of a hidden\n * control, on a page that is billed per view.\n *\n * Nothing here imports React, MUI or `js-cookie`, and its one import is a type\n * erased at compile time — the same constraint `util/theme-mode-cookie` and\n * `util/color-scheme-hint` hold themselves to, and for the same two reasons:\n * a Server Component may take it without pulling the theme library's context\n * providers into the RSC graph, and the edge middleware may take it at all.\n */\nimport type { ThemeMode } from '../hocs/create-with-theme-provider'\n\n/**\n * Every spelling the segment is allowed to take.\n *\n * A closed set on purpose: the segment is written by our own middleware and\n * read back by a route, so an unknown value is never a visitor's preference —\n * it is a stale link, a crawler walking a guessed URL, or a bug. Each such\n * request must still render a page, which is what `parseSchemeRouteSegment`\n * guarantees by resolving anything unrecognized to the light default rather\n * than throwing.\n */\nexport const SCHEME_ROUTE_SEGMENTS = ['light', 'dark'] as const\n\nexport type SchemeRouteSegment = (typeof SCHEME_ROUTE_SEGMENTS)[number]\n\n/**\n * The scheme a request resolves to, as the segment that will carry it.\n *\n * This is the same precedence `useThemeModeState` applies on the client — a\n * stated preference outranks a device default, and light is what remains when\n * the request said neither — expressed once here so the server render and the\n * hydration that follows it cannot disagree about which document was owed.\n *\n * `'system'` is not a scheme. The switcher writes it to mean \"follow the\n * device\", and `parseThemeModeCookie` already reads it back as `null`; it is\n * rejected here too so a caller passing a raw cookie value cannot smuggle it\n * in as a choice.\n *\n * ⚠️ Light for a request that named nothing is a FALLBACK, not a default\n * preference. Firefox and Safari send no client hint, so their visitors reach\n * this with two nulls and are served the light document, then settle on their\n * real device scheme once `prefers-color-scheme` can be evaluated — the same\n * hydration-time settle those browsers have always had here. Choosing dark\n * instead would not fix them; it would only move the flip to the other half of\n * their visitors.\n */\nexport function resolveSchemeRouteSegment(\n  chosen: ThemeMode,\n  device: ThemeMode,\n): SchemeRouteSegment {\n  const scheme = isScheme(chosen) ? chosen : isScheme(device) ? device : 'light'\n  return scheme\n}\n\n/**\n * A path segment as the scheme to render.\n *\n * Total, by construction: an absent, misspelled or hostile segment renders the\n * light document rather than refusing. A route that 500s on an unrecognized\n * segment would turn a stale bookmark into an error page, and this segment is\n * in the URL of every cached page on the site.\n */\nexport function parseSchemeRouteSegment(\n  value: string | undefined | null,\n): SchemeRouteSegment {\n  return value === 'dark' ? 'dark' : 'light'\n}\n\nfunction isScheme(mode: ThemeMode): mode is SchemeRouteSegment {\n  return mode === 'light' || mode === 'dark'\n}\n"],"names":["SCHEME_ROUTE_SEGMENTS","resolveSchemeRouteSegment","chosen","device","scheme","isScheme","parseSchemeRouteSegment","value","mode"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCC,GAGD;;;;;;;;;CASC,GACD,OAAO,MAAMA,wBAAwB;IAAC;IAAS;CAAO,CAAS;AAI/D;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,SAASC,0BACdC,MAAiB,EACjBC,MAAiB;IAEjB,MAAMC,SAASC,SAASH,UAAUA,SAASG,SAASF,UAAUA,SAAS;IACvE,OAAOC;AACT;AAEA;;;;;;;CAOC,GACD,OAAO,SAASE,wBACdC,KAAgC;IAEhC,OAAOA,UAAU,SAAS,SAAS;AACrC;AAEA,SAASF,SAASG,IAAe;IAC/B,OAAOA,SAAS,WAAWA,SAAS;AACtC"}

package/src/lib/util/theme-editor-defaults.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { HostThemeScheme } from '@aglyn/shared-data-types';
+import { type ThemeColorToken } from './theme-editor-fields';
+/** The color a slot renders in one scheme when the site leaves it unset. */
+export declare function inheritedThemeColor(scheme: HostThemeScheme, token: ThemeColorToken, host?: string): string | undefined;
+/**
+ * The corner radius every site ships with. Read rather than written as a
+ * literal, so the default the editor shows cannot stop matching the theme.
+ *
+ * One value for every site, unlike the colors above: the tenant default
+ * changes the PALETTE and takes the rest of its options — shape, spacing,
+ * type ramp, component behaviour — from the same place the brand does.
+ */
+export declare const INHERITED_BORDER_RADIUS: number;
+/** The spacing unit the brand theme ships. */
+export declare const INHERITED_SPACING: number;
+/**
+ * The first family of the brand's font stack — what "Theme default" means in
+ * the font select, named rather than left as a long CSS list.
+ */
+export declare const INHERITED_FONT_FAMILY: string;
+/** MUI's own toolbar heights, which apply while the site sets none. */
+export declare const INHERITED_TOOLBAR_HEIGHTS: {
+    readonly xs: 56;
+    readonly sm: 64;
+};

package/src/lib/util/theme-editor-defaults.js

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ var _ref;
+var _consoleOptions_shape, _consoleOptions_typography;
+import { consoleOptions } from "../console.theme.js";
+import { siteFallbackTheme } from "../tenant.theme.js";
+import { DEFAULT_TOOLBAR_SM, DEFAULT_TOOLBAR_XS } from "./theme-editor-fields.js";
+function builtPalette(scheme, host) {
+    return siteFallbackTheme(host, scheme).palette;
+}
+/** The color a slot renders in one scheme when the site leaves it unset. */ export function inheritedThemeColor(scheme, token, host) {
+    var _palette_group;
+    const palette = builtPalette(scheme, host);
+    const [group, key] = token.split('.');
+    const value = token === 'divider' ? palette['divider'] : (_palette_group = palette[group]) == null ? void 0 : _palette_group[key != null ? key : 'main'];
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * The corner radius every site ships with. Read rather than written as a
+ * literal, so the default the editor shows cannot stop matching the theme.
+ *
+ * One value for every site, unlike the colors above: the tenant default
+ * changes the PALETTE and takes the rest of its options — shape, spacing,
+ * type ramp, component behaviour — from the same place the brand does.
+ */ export const INHERITED_BORDER_RADIUS = typeof ((_consoleOptions_shape = consoleOptions.shape) == null ? void 0 : _consoleOptions_shape.borderRadius) === 'number' ? consoleOptions.shape.borderRadius : 4;
+/** The spacing unit the brand theme ships. */ export const INHERITED_SPACING = typeof consoleOptions.spacing === 'number' ? consoleOptions.spacing : 8;
+/**
+ * The first family of the brand's font stack — what "Theme default" means in
+ * the font select, named rather than left as a long CSS list.
+ */ export const INHERITED_FONT_FAMILY = String((_ref = (_consoleOptions_typography = consoleOptions.typography) == null ? void 0 : _consoleOptions_typography.fontFamily) != null ? _ref : '').split(',')[0].replace(/["']/g, '').trim();
+/** MUI's own toolbar heights, which apply while the site sets none. */ export const INHERITED_TOOLBAR_HEIGHTS = {
+    xs: DEFAULT_TOOLBAR_XS,
+    sm: DEFAULT_TOOLBAR_SM
+};
+
+//# sourceMappingURL=theme-editor-defaults.js.map

package/src/lib/util/theme-editor-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/theme/src/lib/util/theme-editor-defaults.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { HostThemeScheme } from '@aglyn/shared-data-types'\nimport { consoleOptions } from '../console.theme'\nimport { siteFallbackTheme } from '../tenant.theme'\nimport {\n  DEFAULT_TOOLBAR_SM,\n  DEFAULT_TOOLBAR_XS,\n  type ThemeColorToken,\n} from './theme-editor-fields'\n\n/**\n * What each theme editor control resolves to when the site sets nothing\n * (AGL-1180, AGL-2938): the theme that site is layered over.\n *\n * Read off the BUILT themes rather than the options, because text, divider\n * and the light and dark shades are derived by MUI, and the raw options would\n * leave those slots with nothing to report. The editor shows these beside\n * every \"Default\", and anything that proposes a change to a site's theme\n * reads the same values, so \"the default primary\" is one color wherever it\n * is named.\n *\n * WHICH theme is a property of the site, not of the platform (AGL-3068): the\n * operator's own hosts are layered over the brand, every customer site over\n * the neutral tenant default. Named by its site key, and unnamed resolves\n * what a customer site resolves — a \"Default\" that reported the brand to a\n * site publishing in the tenant palette named a color that site never draws.\n *\n * Kept apart from `theme-editor-fields.ts` because this module builds the\n * themes when it loads, and the catalog is read where no theme needs\n * building.\n */\n\ntype PaletteRecord = Record<string, unknown>\n\nfunction builtPalette(\n  scheme: HostThemeScheme,\n  host: string | undefined,\n): PaletteRecord {\n  return siteFallbackTheme(host, scheme).palette as unknown as PaletteRecord\n}\n\n/** The color a slot renders in one scheme when the site leaves it unset. */\nexport function inheritedThemeColor(\n  scheme: HostThemeScheme,\n  token: ThemeColorToken,\n  host?: string,\n): string | undefined {\n  const palette = builtPalette(scheme, host)\n  const [group, key] = token.split('.')\n  const value =\n    token === 'divider'\n      ? palette['divider']\n      : (palette[group] as PaletteRecord | undefined)?.[key ?? 'main']\n  return typeof value === 'string' ? value : undefined\n}\n\n/**\n * The corner radius every site ships with. Read rather than written as a\n * literal, so the default the editor shows cannot stop matching the theme.\n *\n * One value for every site, unlike the colors above: the tenant default\n * changes the PALETTE and takes the rest of its options — shape, spacing,\n * type ramp, component behaviour — from the same place the brand does.\n */\nexport const INHERITED_BORDER_RADIUS =\n  typeof consoleOptions.shape?.borderRadius === 'number'\n    ? consoleOptions.shape.borderRadius\n    : 4\n\n/** The spacing unit the brand theme ships. */\nexport const INHERITED_SPACING =\n  typeof consoleOptions.spacing === 'number' ? consoleOptions.spacing : 8\n\n/**\n * The first family of the brand's font stack — what \"Theme default\" means in\n * the font select, named rather than left as a long CSS list.\n */\nexport const INHERITED_FONT_FAMILY = String(\n  (consoleOptions.typography as { fontFamily?: string } | undefined)\n    ?.fontFamily ?? '',\n)\n  .split(',')[0]\n  .replace(/[\"']/g, '')\n  .trim()\n\n/** MUI's own toolbar heights, which apply while the site sets none. */\nexport const INHERITED_TOOLBAR_HEIGHTS = {\n  xs: DEFAULT_TOOLBAR_XS,\n  sm: DEFAULT_TOOLBAR_SM,\n} as const\n"],"names":["consoleOptions","siteFallbackTheme","DEFAULT_TOOLBAR_SM","DEFAULT_TOOLBAR_XS","builtPalette","scheme","host","palette","inheritedThemeColor","token","group","key","split","value","undefined","INHERITED_BORDER_RADIUS","shape","borderRadius","INHERITED_SPACING","spacing","INHERITED_FONT_FAMILY","String","typography","fontFamily","replace","trim","INHERITED_TOOLBAR_HEIGHTS","xs","sm"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;IAkEQA,uBAaNA;AA5EH,SAASA,cAAc,QAAQ,sBAAkB;AACjD,SAASC,iBAAiB,QAAQ,qBAAiB;AACnD,SACEC,kBAAkB,EAClBC,kBAAkB,QAEb,2BAAuB;AA0B9B,SAASC,aACPC,MAAuB,EACvBC,IAAwB;IAExB,OAAOL,kBAAkBK,MAAMD,QAAQE,OAAO;AAChD;AAEA,0EAA0E,GAC1E,OAAO,SAASC,oBACdH,MAAuB,EACvBI,KAAsB,EACtBH,IAAa;QAONC;IALP,MAAMA,UAAUH,aAAaC,QAAQC;IACrC,MAAM,CAACI,OAAOC,IAAI,GAAGF,MAAMG,KAAK,CAAC;IACjC,MAAMC,QACJJ,UAAU,YACNF,OAAO,CAAC,UAAU,IACjBA,iBAAAA,OAAO,CAACG,MAAM,qBAAf,AAACH,cAA8C,CAACI,cAAAA,MAAO,OAAO;IACpE,OAAO,OAAOE,UAAU,WAAWA,QAAQC;AAC7C;AAEA;;;;;;;CAOC,GACD,OAAO,MAAMC,0BACX,SAAOf,wBAAAA,eAAegB,KAAK,qBAApBhB,sBAAsBiB,YAAY,MAAK,WAC1CjB,eAAegB,KAAK,CAACC,YAAY,GACjC,EAAC;AAEP,4CAA4C,GAC5C,OAAO,MAAMC,oBACX,OAAOlB,eAAemB,OAAO,KAAK,WAAWnB,eAAemB,OAAO,GAAG,EAAC;AAEzE;;;CAGC,GACD,OAAO,MAAMC,wBAAwBC,gBAClCrB,6BAAAA,eAAesB,UAAU,qBAA1B,AAACtB,2BACGuB,UAAU,mBAAI,IAEjBX,KAAK,CAAC,IAAI,CAAC,EAAE,CACbY,OAAO,CAAC,SAAS,IACjBC,IAAI,GAAE;AAET,qEAAqE,GACrE,OAAO,MAAMC,4BAA4B;IACvCC,IAAIxB;IACJyB,IAAI1B;AACN,EAAU"}

package/src/lib/util/theme-editor-fields.d.ts

@@ -0,0 +1,315 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { HostTheme, HostThemeScheme, HostThemeSchemeColors } from '@aglyn/shared-data-types';
+import { type HostThemeComponentKey } from './host-theme';
+/**
+ * The host theme editor's field catalog (AGL-2938): every control the editor
+ * renders, the range each one accepts, the token it writes, and the write
+ * itself.
+ *
+ * It lives here rather than beside the editor because the editor is not the
+ * only thing that changes a site's theme. Anything that proposes a theme
+ * change has to offer exactly the controls the editor offers, with the same
+ * bounds, and has to write each one the way the editor writes it. A copy of
+ * this list anywhere else is a second answer to "what can a theme hold" that
+ * drifts from the first the day a control is added, so the editor renders
+ * from this module and every other writer reads it.
+ *
+ * Pure data and pure functions over `HostTheme`: no MUI, no React and no
+ * brand theme. What a control resolves to when the site sets nothing is the
+ * brand theme's business, in `theme-editor-defaults.ts`.
+ *
+ * Deliberately NOT re-exported from this library's index: the index reaches
+ * every published page, and nothing a visitor renders needs the catalog.
+ * Reach it as `@aglyn/shared-ui-theme/util/theme-editor-fields`.
+ */
+/**
+ * MUI's own toolbar breakpoint. `mixins.toolbar` has to carry this exact
+ * query, because the rule it competes with is MUI's `@media (min-width:600px)
+ * { min-height: 64px }` (AGL-1242).
+ */
+export declare const TOOLBAR_SM_MIN_WIDTH = 600;
+export declare const TOOLBAR_SM_QUERY = "@media (min-width:600px)";
+/** MUI's stock Toolbar heights, shown when the host has set none. */
+export declare const DEFAULT_TOOLBAR_XS = 56;
+export declare const DEFAULT_TOOLBAR_SM = 64;
+/**
+ * `createMixins` spreads `...mixins` AFTER its default, so anything we write
+ * REPLACES the stock toolbar wholesale — including its short-landscape rule.
+ * Carrying it forward keeps that behavior instead of dropping it silently.
+ */
+export declare const TOOLBAR_LANDSCAPE_QUERY = "@media (min-width:0px)";
+export declare const TOOLBAR_LANDSCAPE_RULE: {
+    '@media (orientation: landscape)': {
+        minHeight: number;
+    };
+};
+/** Reads a px `minHeight` out of `mixins.toolbar` for one breakpoint. */
+export declare function readToolbarHeight(theme: HostTheme, breakpoint: 'xs' | 'sm'): number;
+/**
+ * Builds a COMPLETE `mixins.toolbar`, in the order MUI emits it.
+ *
+ * Two things this exists to get right, both because `mixins.toolbar` replaces
+ * MUI's default wholesale rather than merging into it (AGL-1242):
+ *
+ * - **Completeness.** Anything omitted is simply gone. Writing only a desktop
+ *   height left portrait phones with no `min-height` at all, so unset
+ *   breakpoints fall back to MUI's own 56 / 64.
+ * - **Key order.** These land in one CSS rule, so the last matching
+ *   declaration wins. MUI emits the landscape clause BEFORE the sm height;
+ *   emitting it after makes a wide landscape window — i.e. every desktop —
+ *   48px tall.
+ */
+export declare function buildToolbarMixin(xs: number | undefined, sm: number | undefined): {
+    minHeight: string;
+    "@media (min-width:0px)": {
+        '@media (orientation: landscape)': {
+            minHeight: number;
+        };
+    };
+    "@media (min-width:600px)": {
+        minHeight: string;
+    };
+};
+/**
+ * Serializes the branches whose KEY ORDER changes what renders.
+ *
+ * `deepEqual` is order-INsensitive on purpose (AGL-56: Firestore hands the
+ * palette back in a different key order than the editor builds it, and a
+ * string compare left Save enabled forever), so on its own it cannot see a
+ * reorder of `mixins.toolbar` — a change that really does alter the CSS.
+ *
+ * Deliberately narrow: only `mixins`. `components.*.styleOverrides` are CSS
+ * objects too, but widening this would re-expose the AGL-56 failure for every
+ * host with component overrides, and order-sensitivity has only actually been
+ * demonstrated here.
+ *
+ * Firestore does NOT hand a map back in the order it was written, and it
+ * hands different readers different orders (AGL-3146) — which is why what
+ * renders is canonicalized in `hostThemeToThemeOptions` rather than trusted
+ * from storage. A freshly-loaded document is still not dirty here, because
+ * the draft is seeded from the loaded document itself: both sides of this
+ * comparison carry whatever order THIS reader was given.
+ */
+export declare function orderSensitiveKey(theme: HostTheme): string;
+export type PaletteColorKey = 'primary' | 'secondary' | 'tertiary' | 'surface' | 'error' | 'warning' | 'info' | 'success';
+export declare const PALETTE_COLOR_FIELDS: Array<{
+    key: PaletteColorKey;
+    label: string;
+}>;
+export type SurfaceColorPath = ['background', 'default'] | ['background', 'paper'] | ['text', 'primary'] | ['text', 'secondary'] | ['text', 'disabled'] | ['tint', 'primary'] | ['tint', 'secondary'] | ['tint', 'tertiary'];
+export declare const SURFACE_COLOR_FIELDS: Array<{
+    path: SurfaceColorPath;
+    label: string;
+}>;
+/**
+ * Pale accent washes (AGL-1244).
+ *
+ * Separate from {@link PALETTE_COLOR_FIELDS} because a tint is a STRING LEAF,
+ * not a `{ main }` record — the palette fields all write `main`, and a tint has
+ * none. It rides the same `SurfaceColorPath` machinery as `background`/`text`
+ * for exactly that reason, and is listed apart only so the editor can head it
+ * "Tints" instead of filing it under "Background & text".
+ */
+export declare const TINT_COLOR_FIELDS: Array<{
+    path: SurfaceColorPath;
+    label: string;
+}>;
+/** The one color leaf that is neither a palette color nor a member of a group. */
+export declare const DIVIDER_COLOR_FIELD: {
+    readonly key: "divider";
+    readonly label: "Divider";
+};
+/** Curated Google Fonts choices for the font family selector. */
+export declare const GOOGLE_FONT_OPTIONS: Array<{
+    family: string;
+    category: 'sans-serif' | 'serif' | 'monospace' | 'display';
+    weights: Array<number>;
+}>;
+export declare function fontFamilyStack(family: string, category: (typeof GOOGLE_FONT_OPTIONS)[number]['category']): string;
+export declare function getSchemeColor(colors: HostThemeSchemeColors | undefined, path: SurfaceColorPath): string | undefined;
+/** The two color schemes the editor edits, in tab order. */
+export declare const THEME_EDITOR_SCHEMES: readonly HostThemeScheme[];
+/**
+ * Every color the editor edits per scheme, named the way a diff names it: a
+ * palette key (`primary`), a group path joined with a dot
+ * (`background.default`, `tint.primary`), or `divider`.
+ */
+export type ThemeColorToken = PaletteColorKey | 'background.default' | 'background.paper' | 'text.primary' | 'text.secondary' | 'text.disabled' | 'tint.primary' | 'tint.secondary' | 'tint.tertiary' | 'divider';
+/** Where a color control sits in the editor's Color scheme card. */
+export type ThemeColorGroup = 'palette' | 'surface' | 'tint' | 'divider';
+/** Every color field the editor renders, in the order it renders them. */
+export declare const THEME_COLOR_FIELDS: ReadonlyArray<{
+    token: ThemeColorToken;
+    label: string;
+    group: ThemeColorGroup;
+}>;
+/** Whether visitors get a dark scheme; absent from the document means `auto`. */
+export type ThemeDarkSchemeValue = 'auto' | 'off';
+export declare const DARK_SCHEME_FIELD: {
+    readonly label: "Dark scheme";
+    readonly options: readonly [{
+        readonly value: "auto";
+        readonly label: "Follows the visitor";
+    }, {
+        readonly value: "off";
+        readonly label: "Off — always light";
+    }];
+};
+/**
+ * The font select's value for "no font of the site's own": the theme's
+ * default stack, with nothing to load.
+ */
+export declare const SYSTEM_FONT_VALUE = "__system__";
+export declare const FONT_FAMILY_FIELD: {
+    readonly label: "Font family";
+};
+/** The corner radius slider, in px. */
+export declare const BORDER_RADIUS_FIELD: {
+    readonly label: "Border radius";
+    readonly min: 0;
+    readonly max: 24;
+    readonly step: 1;
+};
+/** The spacing unit MUI multiplies every `spacing(n)` by, in px. */
+export declare const SPACING_FIELD: {
+    readonly label: "Spacing unit (px)";
+    readonly min: 2;
+    readonly max: 16;
+    readonly step: 1;
+};
+/** The two nav heights, either side of MUI's toolbar breakpoint, in px. */
+export declare const TOOLBAR_HEIGHT_FIELDS: {
+    readonly xs: {
+        readonly label: "Nav height, mobile (px)";
+        readonly min: 40;
+        readonly max: 160;
+        readonly step: 1;
+    };
+    readonly sm: {
+        readonly label: "Nav height, desktop (px)";
+        readonly min: 40;
+        readonly max: 160;
+        readonly step: 1;
+    };
+};
+/** The raw-JSON component overrides, limited to the sanitizer's whitelist. */
+export declare const COMPONENT_OVERRIDES_FIELD: {
+    readonly label: "Component overrides";
+    readonly components: readonly ["MuiAppBar", "MuiAvatar", "MuiBadge", "MuiButton", "MuiButtonBase", "MuiCard", "MuiCardContent", "MuiCheckbox", "MuiChip", "MuiCircularProgress", "MuiDivider", "MuiIconButton", "MuiLinearProgress", "MuiLink", "MuiList", "MuiListItem", "MuiMenu", "MuiPaper", "MuiRadio", "MuiSlider", "MuiSwitch", "MuiTab", "MuiTabs", "MuiTextField", "MuiToolbar", "MuiTooltip", "MuiTypography"];
+};
+/**
+ * The media queries a component override may scope a style to: either side
+ * of MUI's own toolbar breakpoint, the one breakpoint the editor already
+ * names. MUI's `down('sm')` stops a twentieth of a pixel short of it.
+ */
+export declare const THEME_EDITOR_MEDIA_QUERIES: {
+    readonly mobile: "@media (max-width:599.95px)";
+    readonly desktop: "@media (min-width:600px)";
+};
+export type ThemeEditorMedia = keyof typeof THEME_EDITOR_MEDIA_QUERIES;
+export type ThemeEditorControlId = `color.${ThemeColorToken}` | 'darkScheme' | 'fontFamily' | 'borderRadius' | 'spacing' | 'navHeight.xs' | 'navHeight.sm' | 'components';
+/** One control the editor renders, described well enough to be offered elsewhere. */
+export interface ThemeEditorControl {
+    /** Stable id: what a diff row, a proposal and a spec name the control by. */
+    id: ThemeEditorControlId;
+    /** The label the editor shows. */
+    label: string;
+    kind: 'color' | 'select' | 'number' | 'json';
+    /** Edited once per scheme, under the Light and Dark tabs. */
+    perScheme: boolean;
+    /** A color control's token. */
+    token?: ThemeColorToken;
+    /** A select's values, or the components a JSON control accepts. */
+    options?: readonly string[];
+    /** A number control's inclusive bounds and its step. */
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/**
+ * Every value-bearing control the editor renders, in the order it renders
+ * them. The buttons that act on these values rather than hold one — Copy
+ * from light, Reset to default, Discard, Save — are not controls: a reset is
+ * a control set back to nothing, and a copy is every color control of one
+ * scheme written from the other.
+ */
+export declare const THEME_EDITOR_CONTROLS: readonly ThemeEditorControl[];
+/** The catalog entry for a control id. */
+export declare function themeEditorControl(id: ThemeEditorControlId): ThemeEditorControl;
+/** A color the site set for one scheme; `undefined` when the slot inherits. */
+export declare function readThemeColor(theme: HostTheme | undefined, scheme: HostThemeScheme, token: ThemeColorToken): string | undefined;
+/**
+ * Sets one color for one scheme, or clears it with `undefined` so the slot
+ * inherits again. A palette color writes `main` and keeps whatever else its
+ * record carries, and clearing it drops the record; a group member that
+ * leaves its group empty drops the group.
+ */
+export declare function writeThemeColor(theme: HostTheme, scheme: HostThemeScheme, token: ThemeColorToken, hex: string | undefined): HostTheme;
+/** Replaces one scheme's colors with a copy of the other's. */
+export declare function copyThemeSchemeColors(theme: HostTheme, from: HostThemeScheme, to: HostThemeScheme): HostTheme;
+/** The dark scheme switch as the select shows it. */
+export declare function readDarkScheme(theme: HostTheme | undefined): ThemeDarkSchemeValue;
+/**
+ * Absent means "follows the visitor"; only the opt-out is written, so the
+ * saved document stays empty for the common case.
+ */
+export declare function writeDarkScheme(theme: HostTheme, value: ThemeDarkSchemeValue): HostTheme;
+/** The font select's value: the site's font, or {@link SYSTEM_FONT_VALUE}. */
+export declare function readFontFamily(theme: HostTheme | undefined): string;
+/**
+ * Picks a font from {@link GOOGLE_FONT_OPTIONS}, loading it and naming it as
+ * the typography's stack, or {@link SYSTEM_FONT_VALUE} to go back to the
+ * theme default. A family outside the curated list changes nothing.
+ */
+export declare function writeFontFamily(theme: HostTheme, value: string): HostTheme;
+/** Sets the corner radius, or clears it with `undefined` so it inherits. */
+export declare function writeBorderRadius(theme: HostTheme, value: number | undefined): HostTheme;
+/** Sets the spacing unit; anything but a positive number clears it. */
+export declare function writeSpacing(theme: HostTheme, value: number | undefined): HostTheme;
+/**
+ * Sets one nav height — anything but a positive number clears it — and
+ * rebuilds the whole toolbar mixin around both, because `mixins.toolbar`
+ * replaces MUI's default rather than merging into it (AGL-1242).
+ */
+export declare function writeToolbarHeight(theme: HostTheme, breakpoint: 'xs' | 'sm', value: number | undefined): HostTheme;
+/**
+ * Drops the site's component overrides. With nothing stored the site renders
+ * the brand's own component styles, which is what the editor's "Reset to
+ * theme defaults" means.
+ */
+export declare function resetComponentOverrides(theme: HostTheme): HostTheme;
+/** One leaf of a component override, as a writer names it. */
+export interface ThemeComponentOverrideLeaf {
+    component: HostThemeComponentKey;
+    /** `styleOverrides` styles a slot; `defaultProps` sets a prop's default. */
+    target: 'styleOverrides' | 'defaultProps';
+    /** The style slot (`root`, `contained`, `h1`); `null` for a default prop. */
+    slot: string | null;
+    /** A camelCase CSS property, or the prop's name. */
+    property: string;
+    /** Scopes a style to one side of the toolbar breakpoint; `null` for every width. */
+    media: ThemeEditorMedia | null;
+    value: string | number | boolean;
+}
+/**
+ * Sets one leaf inside the site's component overrides and keeps every other
+ * override the site has. The stored overrides are deep-merged over the
+ * brand's own at render time, so naming one property changes that property
+ * and inherits the rest of the component.
+ */
+export declare function writeComponentOverride(theme: HostTheme, leaf: ThemeComponentOverrideLeaf): HostTheme;