@vectoriox/iox-ui 5.13.1 → 5.15.0

package/src/design-core/fonts.ts

@@ -77,19 +77,56 @@ export function parseFontFamilies(stack: string): string[] {
         .filter(Boolean);
 }
 
+/** Where Google serves the stylesheets, and the origin the font FILES come from (preconnect). */
+export const GOOGLE_FONTS_CSS_ORIGIN = 'https://fonts.googleapis.com';
+export const GOOGLE_FONTS_FILE_ORIGIN = 'https://fonts.gstatic.com';
+
+/** The ONE stylesheet URL for a catalog id — both renderers link exactly this (one per family, T7). */
+export function googleFontHref(id: string): string {
+    return `${GOOGLE_FONTS_CSS_ORIGIN}/css2?family=${id}&display=swap`;
+}
+
+const CATALOG_BY_LOWER = new Map(Object.entries(FONT_CATALOG).map(([family, id]) => [family.toLowerCase(), id]));
+
+/** The catalog id of a family name (case-insensitive), or null — a system or uploaded face has none. */
+export function catalogFontId(family: string | null | undefined): string | null {
+    return CATALOG_BY_LOWER.get(String(family ?? '').trim().toLowerCase()) ?? null;
+}
+
+const MONO_ROLE = 'font-mono';
+const ALWAYS_LOADED_ROLES = FONT_FAMILY_TOKENS.filter(role => role !== MONO_ROLE);
+const MONO_REFERENCE = /var\(\s*--iox-font-mono\b/;
+
+export interface FontsForTokensOptions {
+    /**
+     * The CSS that will actually render (node rules, element styles). `font-mono` is loaded only when
+     * something READS it — here or in another token's value — because no element style does: an org
+     * would otherwise download a monospace face for a site with no code on it.
+     */
+    usedCss?: string;
+}
+
 /**
- * The Google css2 ids to load for a token set: every catalog family named by a font role token,
- * one id per family (T7 — one `<link>` per family, so one bad id cannot sink the others).
+ * The Google css2 ids to load for a token set: every catalog family named by the display / body /
+ * label roles, plus mono when referenced (above). One id per family (T7 — one `<link>` per family, so
+ * one bad id cannot sink the others), in role order.
  */
-export function fontsForTokens(tokens: ReadonlyArray<DesignTokenLike> | null | undefined): string[] {
+export function fontsForTokens(
+    tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
+    opts: FontsForTokensOptions = {},
+): string[] {
+    const rows = (tokens ?? []).filter(t => !!t && typeof t.name === 'string');
+    const monoRead = MONO_REFERENCE.test(opts.usedCss ?? '')
+        || rows.some(t => t.name !== MONO_ROLE && MONO_REFERENCE.test(`${t.value ?? ''} ${t.values?.dark ?? ''}`));
+    const roles = monoRead ? FONT_FAMILY_TOKENS : ALWAYS_LOADED_ROLES;
     const seen = new Set<string>();
     const ids: string[] = [];
-    for (const role of FONT_FAMILY_TOKENS) {
-        const row = (tokens ?? []).find(t => t?.name === role);
+    for (const role of roles) {
+        const row = rows.find(t => t.name === role);
         for (const family of parseFontFamilies(row?.value ?? '')) {
-            const id = FONT_CATALOG[family];
-            if (id && !seen.has(family)) {
-                seen.add(family);
+            const id = catalogFontId(family);
+            if (id && !seen.has(id)) {
+                seen.add(id);
                 ids.push(id);
             }
         }

package/src/design-core/node-classes.ts

@@ -0,0 +1,82 @@
+import { ELEMENT_STYLE_MARKER_CLASS, elementStyleClass } from './element-styles';
+import { SPEC_SCHEMES } from './flavor-spec.generated';
+
+/**
+ * The design-system classes a node renders, in BOTH renderers (builder canvas, engine component
+ * path, engine string path) — ONE helper, so the three can never disagree about which class a node
+ * carries:
+ *
+ * - the element-style MARKER `iox-es iox-es-<id>` (design-system §3b-bis) — component CSS carrying
+ *   the system look is scoped to it, so a node saved before DS2 keeps its pre-DS2 look;
+ * - the section colour scheme `iox-scheme-<id>` (§3c) for a non-default `colorScheme` — the class
+ *   `compileSchemeCss` re-declares tokens on, so everything inside re-resolves.
+ *
+ * Renderers read `elementStyle` and `colorScheme` for exactly this and nothing else.
+ */
+
+/** The section colour schemes — the contract's `schemes` keys. */
+export enum ColorScheme {
+    Default = 'default',
+    Subtle = 'subtle',
+    Inverse = 'inverse',
+    Accent = 'accent',
+}
+
+/** The content trait (stored in `props`, not a style prop) that picks a node's scheme. */
+export const COLOR_SCHEME_TRAIT = 'colorScheme';
+
+/** The node types that offer a scheme (spec §3c: Section/Container; LinkedContainer is a Container that links). */
+export const COLOR_SCHEME_TYPES: ReadonlyArray<string> = ['Section', 'Container', 'LinkedContainer'];
+
+/** Every scheme in contract order, with the contract's label (Default · Subtle · Inverse · Brand). */
+export const COLOR_SCHEMES: ReadonlyArray<{ readonly id: ColorScheme; readonly label: string }> =
+    (Object.keys(SPEC_SCHEMES) as ColorScheme[]).map(id => ({ id, label: (SPEC_SCHEMES as Record<string, { label: string }>)[id].label }));
+
+const SCHEME_IDS = new Set<string>(Object.keys(SPEC_SCHEMES));
+const SCHEME_PREFIX = 'iox-scheme-';
+const MARKER_PREFIX = `${ELEMENT_STYLE_MARKER_CLASS}-`;
+
+/** `iox-scheme-<id>` for a known NON-default scheme, else null — an unknown id never reaches a class attribute. */
+export function colorSchemeClass(id: unknown): string | null {
+    return typeof id === 'string' && id !== ColorScheme.Default && SCHEME_IDS.has(id) ? `${SCHEME_PREFIX}${id}` : null;
+}
+
+/** The node shapes this module reads: a serialized node (`props`) or a builder node (`traits[]`). */
+export interface DesignClassSource {
+    elementStyle?: string | null;
+    props?: Readonly<Record<string, unknown>> | null;
+    traits?: ReadonlyArray<{ name?: string; default?: unknown }> | null;
+}
+
+/** A node's `colorScheme`, from `props` (serialized) or its trait (builder). */
+export function colorSchemeOf(node: DesignClassSource | null | undefined): string | null {
+    if (!node) return null;
+    const fromProps = node.props?.[COLOR_SCHEME_TRAIT];
+    if (fromProps !== undefined) return typeof fromProps === 'string' ? fromProps : null;
+    const trait = node.traits?.find(t => t?.name === COLOR_SCHEME_TRAIT)?.default;
+    return typeof trait === 'string' ? trait : null;
+}
+
+/** True when the node wears a known element style — the marker is on it. */
+export function hasElementStyleMarker(node: { elementStyle?: string | null } | null | undefined): boolean {
+    return elementStyleClass(node?.elementStyle) !== null;
+}
+
+/** The classes a node renders: `'iox-es iox-es-card iox-scheme-inverse'`, or `''` for none. */
+export function nodeDesignClasses(node: DesignClassSource | null | undefined): string {
+    const marker = elementStyleClass(node?.elementStyle);
+    return [marker ? `${ELEMENT_STYLE_MARKER_CLASS} ${marker}` : '', colorSchemeClass(colorSchemeOf(node)) ?? '']
+        .filter(Boolean).join(' ');
+}
+
+const isDesignClass = (c: string) =>
+    c === ELEMENT_STYLE_MARKER_CLASS || c.startsWith(MARKER_PREFIX) || c.startsWith(SCHEME_PREFIX);
+
+/** Make an element's design classes match the node — the live switch on the canvas and the
+ *  component path's one-time stamp. Removes stale ones; touches no other class. */
+export function syncNodeDesignClasses(el: { classList: DOMTokenList } | null | undefined, node: DesignClassSource | null | undefined): void {
+    if (!el?.classList) return;
+    for (const c of Array.from(el.classList).filter(isDesignClass)) el.classList.remove(c);
+    const classes = nodeDesignClasses(node);
+    if (classes) el.classList.add(...classes.split(' '));
+}

package/src/design-core/public-api.ts

@@ -14,9 +14,13 @@ export * from './css-names';
 export * from './token-css';
 export * from './flavor';
 export * from './element-styles';
+export * from './node-classes';
+export * from './empty-image';
 export * from './brand';
 export * from './flavor-tokens';
 export * from './flavor-seed';
 export * from './spring';
 export * from './fonts';
 export * from './token-names';
+export * from './design-settings';
+export * from './design-apply';

package/src/design-core/token-css.ts

@@ -1,5 +1,6 @@
 import { DesignMode } from './design-token.model';
 import { SPEC_A11Y, SPEC_SCHEMES } from './flavor-spec.generated';
+import { specTokenNames } from './token-names';
 
 /**
  * Design-token → CSS compilation, shared by BOTH renderers (flavors F0, design-system DS1).
@@ -14,6 +15,11 @@ import { SPEC_A11Y, SPEC_SCHEMES } from './flavor-spec.generated';
  *   4. reduced transparency `@media (prefers-reduced-transparency: reduce)`
  *   5. dark — LAST     `@media (prefers-color-scheme: dark)`
  *
+ * MODE (design-system D6) is a compile choice, never a row change: `auto` is the visitor-following
+ * order above; `light` compiles the base from light values and emits no dark block; `dark` compiles
+ * the base from DARK values (schemes and placeholders resolved from them too) and emits no dark block —
+ * so a Midnight site is dark for a light-OS visitor.
+ *
  * ⚠️ The appended-last contract: the dark block REDEFINES custom properties, so every consumer
  * appends it AFTER all of its base rules — the engine pushes it after the page's css blocks, the
  * builder registry keeps it as its last token rule (responsive A3 lesson).
@@ -32,6 +38,16 @@ export interface DesignTokenLike {
 export interface TokenCssOptions {
     /** Selector that carries the variables instead of `:root` — a preview wrapper, a specimen. */
     scope?: string;
+    /** The studio's colour mode (`settings.design.mode`). Absent = `auto`. */
+    mode?: DesignMode;
+    /**
+     * Declare every SPEC token the rows lack as `initial` on the scope (the guaranteed-invalid value),
+     * so a `var()` inside the scope cannot inherit a same-named property from an ANCESTOR. The builder
+     * needs it: the admin's `:root` chrome tokens share names with org tokens (`accent`, `surface-2`…),
+     * and a missing org row would silently paint the canvas in admin chrome. With it, the canvas
+     * computes exactly what the live site computes for that row — unset.
+     */
+    isolate?: boolean;
 }
 
 export interface TokenCssBlocks {
@@ -114,6 +130,16 @@ const DARK: ResolvedMode = 'dark';
 
 const modeValue = (t: DesignTokenLike, mode: ResolvedMode): string => (mode === DARK ? darkOf(t) ?? t.value : t.value);
 
+/** The rows as ONE mode: each row's value in that mode, no dark override left. `auto` (or none) →
+ *  the rows unchanged. */
+function rowsForMode(rows: ReadonlyArray<DesignTokenLike>, mode: DesignMode | undefined): DesignTokenLike[] {
+    if (mode !== LIGHT && mode !== DARK) return [...rows];
+    return rows.map(t => {
+        const { values: _dropped, ...rest } = t;
+        return { ...rest, value: modeValue(t, mode) };
+    });
+}
+
 /** Every token's ROOT value in one mode, with `var(--iox-…)` references resolved against the same
  *  set (recursively; a reference cycle or an unknown token is left as written). */
 export function resolveTokenValues(
@@ -223,10 +249,14 @@ export function compileTokenCssBlocks(
     tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
     opts: TokenCssOptions = {},
 ): TokenCssBlocks {
-    const rows = usableTokens(tokens);
+    const rows = rowsForMode(usableTokens(tokens), opts.mode);
     const root = opts.scope ?? ROOT;
+    const present = new Set(rows.map(t => t.name));
+    const unset: Array<[string, string]> = opts.isolate
+        ? [...specTokenNames()].filter(name => !present.has(name)).map((name): [string, string] => [name, 'initial'])
+        : [];
     const base = [
-        rule(root, rows.map((t): [string, string] => [t.name, t.value])),
+        rule(root, [...unset, ...rows.map((t): [string, string] => [t.name, t.value])]),
         compileSchemeCss(rows, opts.scope),
         ...ACCESSIBILITY_MEDIA.map(({ query, overrides }) =>
             media(query, [rule(root, presentOverrides(rows, overrides, false), '  ')])),

package/src/design-core/token-names.ts

@@ -30,3 +30,24 @@ export function unknownTokenReferences(css: string, alsoAllowed: Iterable<string
     const extra = new Set(alsoAllowed);
     return tokenReferences(css).filter(name => !spec.has(name) && !extra.has(name));
 }
+
+const LEGACY_SCOPE = /:not\(\s*\.iox-es\s*\)/;
+const RULE = /([^{}]+)\{([^{}]*)\}/g;
+
+/**
+ * Tokens read by a LEGACY rule — any rule whose selector is scoped `:not(.iox-es)` (the pre-DS2 look
+ * of a node that wears no element style, design-system §3b-bis). Such a rule must read NO token at
+ * all: a token it reads repaints a pre-DS2 page the moment the org's rows are seeded or a flavor is
+ * applied (D5). Returns `selector → names` for each offending rule; comments are ignored.
+ */
+export function legacyRuleTokenReferences(css: string): Array<{ selector: string; tokens: string[] }> {
+    const text = String(css ?? '').replace(/\/\*[\s\S]*?\*\//g, '');
+    const out: Array<{ selector: string; tokens: string[] }> = [];
+    for (const m of text.matchAll(RULE)) {
+        const selector = m[1].trim().replace(/\s+/g, ' ');
+        if (!LEGACY_SCOPE.test(selector)) continue;
+        const tokens = tokenReferences(m[2]);
+        if (tokens.length) out.push({ selector, tokens });
+    }
+    return out;
+}

package/styles/iox-design.css

@@ -0,0 +1,30 @@
+/* Design-system component CSS that EVERY renderer needs — the ONE copy.
+ *
+ * Same reason as iox-forms.css: the SSR engine's string renderer emits plain markup, the engine's
+ * component path renders the shared components, and the builder canvas renders its own twins, so a
+ * component-scoped copy in each would be three copies that drift. Consumers add this file to their
+ * `angular.json` styles.
+ *
+ * Everything here is scoped to the element-style marker (design-system §3b-bis): a node saved
+ * before element styles never matches, so it renders exactly as before.
+ */
+
+/* Empty images (DS3). A marked Image with no source carries `data-iox-empty` and a size-less
+   placeholder src (design-core `emptyImageSrc`), so it stays a real replaced element: its own
+   aspect-ratio and object-fit apply and this fill shows through — on the canvas behind the
+   "Add image" label, on the live site on its own. Out-specifies the node rule (0,2,1 vs 0,1,0)
+   only while the image is empty. */
+img.iox-es-media[data-iox-empty] {
+    background-color: var(--iox-surface-2);
+}
+
+/* An empty marked Gallery takes the same fill, on the element that carries its node rule (size,
+   radius): the string renderer's one div, or the component's inner `.iox-gallery` under the
+   `<iox-gallery>` host that wears the marker. Its cinematic overlay has nothing to darken. */
+.iox-gallery.iox-es-media[data-iox-empty],
+iox-gallery.iox-es-media[data-iox-empty] > .iox-gallery {
+    background-color: var(--iox-surface-2);
+}
+.iox-es-media[data-iox-empty] .iox-gallery__overlay {
+    display: none;
+}