@designcrowd/library.brand-page 6.2.11-builder-v2-1 → 6.2.12

package/lib/src/brand-page/utils/text-role-css.util.js

@@ -0,0 +1,186 @@
+import { CANONICAL_TEXT_STYLE_TYPES, isCanonicalTextStyleType, } from '../models/styles.model';
+import { PAGE_SCOPE_ID_ATTRIBUTE } from './style.util';
+import { composeTextDecoration, NEUTRAL_TYPOGRAPHY_VALUE, ROLE_VAR_ATTRS, rteTextDecorationClassName, roleVarRef, runTypographyFillValue, textRoleClassName, } from '@shared/text-role-typography.util';
+export { ROLE_VAR_ATTRS, roleVarRef, runTypographyFillValue, textRoleClassName, } from '@shared/text-role-typography.util';
+export const TEXT_ROLE_OPTIONS_KEY = Symbol('bpTextRoleOptions');
+export const TEXT_ROLE_STYLE_ATTRIBUTE = 'data-text-roles';
+export const TEXT_ROLE_SCOPED_ATTRIBUTE = 'data-text-roles-scoped';
+export const roleStyleFor = (type, options) => type && isCanonicalTextStyleType(type) ? options?.[type]?.style : undefined;
+export const roleClassFor = (type) => type && isCanonicalTextStyleType(type) ? textRoleClassName(type) : undefined;
+// Multi-word CSS custom identifiers are unquoted only when every token is valid.
+const UNQUOTED_FAMILY_TOKEN = /^-?[A-Za-z_][A-Za-z0-9_-]*$/;
+export const cssFontFamilyValue = (value) => value
+    .split(',')
+    .map((raw) => {
+    const family = raw.trim();
+    if (!family ||
+        family.startsWith('"') ||
+        family.startsWith("'") ||
+        family.startsWith('var(')) {
+        return family;
+    }
+    return family
+        .split(/\s+/)
+        .every((token) => UNQUOTED_FAMILY_TOKEN.test(token))
+        ? family
+        : `"${family}"`;
+})
+    .filter(Boolean)
+    .join(', ');
+const ROLE_VAR_MARK_ATTRS = ROLE_VAR_ATTRS.map((attr) => attr.markAttr);
+export const roleTypographyStyle = (own, roleStyle, options) => {
+    const omit = new Set(options?.omit ?? []);
+    const style = {};
+    const literal = (attr, value) => attr === 'fontFamily' ? cssFontFamilyValue(value) : value;
+    for (const attr of ROLE_VAR_MARK_ATTRS) {
+        if (omit.has(attr))
+            continue;
+        const ownValue = own?.[attr];
+        const roleValue = roleStyle?.[attr];
+        const hasOwn = ownValue != null && ownValue !== '';
+        const hasRole = roleValue != null && roleValue !== '';
+        if (roleStyle == null) {
+            if (hasOwn)
+                style[attr] = literal(attr, ownValue);
+            continue;
+        }
+        const effectiveRole = hasRole ? roleValue : NEUTRAL_TYPOGRAPHY_VALUE[attr];
+        if (hasOwn && (!hasRole || ownValue !== effectiveRole)) {
+            style[attr] =
+                attr === 'textDecoration'
+                    ? (composeTextDecoration(roleValue, ownValue) ??
+                        literal(attr, ownValue))
+                    : literal(attr, ownValue);
+        }
+        else if (hasRole) {
+            style[attr] = roleVarRef(attr);
+        }
+    }
+    return style;
+};
+export const fillRteRunTypography = (doc, roleStyle, styleObj) => {
+    const fillRun = (run) => {
+        const mark = run.marks?.find((candidate) => candidate.type === 'textStyle');
+        let attrs;
+        for (const attr of ROLE_VAR_MARK_ATTRS) {
+            const existing = (attrs ?? mark?.attrs)?.[attr];
+            const inheritedDecoration = attr === 'textDecoration' && existing === roleVarRef(attr);
+            if (!inheritedDecoration &&
+                existing !== undefined &&
+                existing !== null &&
+                existing !== '')
+                continue;
+            let value = runTypographyFillValue(attr, roleStyle, styleObj);
+            if (value == null)
+                continue;
+            if (inheritedDecoration && value === roleVarRef(attr))
+                continue;
+            if (attr === 'fontFamily')
+                value = cssFontFamilyValue(value);
+            if (existing !== value) {
+                attrs ??= { ...(mark?.attrs ?? {}) };
+                attrs[attr] = value;
+                // A filled value is the role's or block's, so a stale reset marker must not clear the role.
+                if (attr === 'textDecoration')
+                    delete attrs.textDecorationReset;
+            }
+        }
+        if (!attrs)
+            return run;
+        const nextMark = { type: 'textStyle', attrs };
+        const marks = mark
+            ? run.marks.map((candidate) => candidate === mark ? nextMark : candidate)
+            : [...(run.marks ?? []), nextMark];
+        return { ...run, marks };
+    };
+    const visit = (node) => {
+        const own = node.type === 'text' ? fillRun(node) : node;
+        const content = node.content?.map(visit);
+        return content?.some((child, index) => child !== node.content?.[index])
+            ? { ...own, content }
+            : own;
+    };
+    return visit(doc);
+};
+const TYPOGRAPHY_PROPS = [
+    ['font-family', 'fontFamily'],
+    ['font-size', 'fontSize'],
+    ['font-weight', 'fontWeight'],
+    ['font-style', 'fontStyle'],
+    ['line-height', 'lineHeight'],
+    ['letter-spacing', 'letterSpacing'],
+    ['text-decoration', 'textDecoration'],
+];
+// Defence in depth: role values are validated when stored, but these reach Page's raw SSR <style>
+// text, so nothing here may close a declaration or the style element.
+const sanitizeDeclarationValue = (value) => value.replace(/[^\w\s.%-]/g, '');
+const sanitizeFontFamilyValue = (value) => value
+    .split(',')
+    .map((family) => family.replace(/[^A-Za-z0-9 _-]/g, '').trim())
+    .filter(Boolean)
+    .join(', ');
+const roleDeclarations = (style) => TYPOGRAPHY_PROPS.flatMap(([cssProp, key]) => {
+    const value = style?.[key] || NEUTRAL_TYPOGRAPHY_VALUE[key];
+    if (!value)
+        return [];
+    const varAttr = ROLE_VAR_ATTRS.find((attr) => attr.markAttr === key);
+    if (!varAttr)
+        return [];
+    const declared = key === 'fontFamily'
+        ? cssFontFamilyValue(sanitizeFontFamilyValue(String(value)))
+        : sanitizeDeclarationValue(String(value));
+    return [`${varAttr.varName}: ${declared};`];
+}).join(' ');
+const buildRoleRules = (textStyleOptions, selectorPrefix) => CANONICAL_TEXT_STYLE_TYPES.flatMap((type) => {
+    const declarations = roleDeclarations(textStyleOptions[type]?.style);
+    return declarations
+        ? [`${selectorPrefix}.${textRoleClassName(type)} { ${declarations} }`]
+        : [];
+}).join('\n  ');
+const RTE_TEXT_DECORATION_VALUES = [
+    'var(--role-text-decoration)',
+    'none',
+    'underline',
+    'line-through',
+    'underline line-through',
+    'overline',
+    'underline overline',
+    'line-through overline',
+    'underline line-through overline',
+    'none underline',
+    'none line-through',
+    'none overline',
+    'none underline line-through',
+    'none underline overline',
+    'none line-through overline',
+    'none underline line-through overline',
+];
+const buildRteTextDecorationRules = (textStyleOptions, selectorPrefix) => CANONICAL_TEXT_STYLE_TYPES.flatMap((type) => {
+    const roleValue = textStyleOptions[type]?.style?.textDecoration;
+    const roleSelector = `${selectorPrefix}.${textRoleClassName(type)}`;
+    return RTE_TEXT_DECORATION_VALUES.map((localValue) => {
+        const className = rteTextDecorationClassName(localValue);
+        const decoration = composeTextDecoration(roleValue ?? 'none', localValue);
+        return `${roleSelector} .${className} { text-decoration: ${decoration}; }`;
+    });
+}).join('\n  ');
+export const buildTextRoleRootCssText = (textStyleOptions) => {
+    const rules = buildRoleRules(textStyleOptions, '');
+    const decorationRules = buildRteTextDecorationRules(textStyleOptions, '');
+    return [rules, decorationRules].filter(Boolean).join('\n');
+};
+export const buildTextRoleRootCss = (textStyleOptions) => {
+    const css = buildTextRoleRootCssText(textStyleOptions);
+    return css ? `<style ${TEXT_ROLE_STYLE_ATTRIBUTE}>\n  ${css}\n</style>` : '';
+};
+export const buildTextRoleScopedCssText = (textStyleOptions, scopeId) => {
+    if (!scopeId)
+        return '';
+    const rules = buildRoleRules(textStyleOptions, `[${PAGE_SCOPE_ID_ATTRIBUTE}="${scopeId}"] `);
+    const decorationRules = buildRteTextDecorationRules(textStyleOptions, `[${PAGE_SCOPE_ID_ATTRIBUTE}="${scopeId}"] `);
+    return [rules, decorationRules].filter(Boolean).join('\n');
+};
+export const buildTextRoleScopedCss = (textStyleOptions, scopeId) => {
+    const css = buildTextRoleScopedCssText(textStyleOptions, scopeId);
+    return css ? `<style ${TEXT_ROLE_SCOPED_ATTRIBUTE}>\n  ${css}\n</style>` : '';
+};

package/lib/src/brand-page/utils/text-role-reconnect.util.d.ts

@@ -0,0 +1,90 @@
+import type { BrandPageModel, TextStyleDeclaration } from '../models';
+import { isCanonicalTextStyleType, type TextStyleOptions, type LegacyTextStyleType, type CanonicalTextStyleType } from '../models/styles.model';
+export { isCanonicalTextStyleType };
+/**
+ * The one definition of "a text field whose role isn't one of the ten reconnects to its nearest
+ * role and keeps its look" (ADR 0021), shared by migration-22 (upgrade) and the AI write
+ * boundary (`applyAiStyle`).
+ *
+ * MIGRATION-22 SNAPSHOT DEPENDENCY: this is shared with maker and AI writes, but migration-22 reads
+ * it as part of its v21 -> v22 output. Before changing reconnect behaviour after that migration
+ * releases, copy the v22 semantics into the migration (or add a later migration).
+ */
+/**
+ * The per-site legacy → canonical target map. `paragraphs` and `buttons` are fixed; `titles`/
+ * `headings` snap to the heading tier whose default size is nearest the OLD role's size, kept on
+ * DISTINCT tiers so migration-22's colour seed is unambiguous.
+ */
+export type LegacyTargetMap = Record<LegacyTextStyleType, CanonicalTextStyleType>;
+export declare const HEADING_TIERS: ("button" | "heading1" | "heading2" | "heading3" | "heading4" | "heading5" | "heading6" | "paragraph1" | "paragraph2" | "paragraph3")[];
+export declare const PARAGRAPH_TIERS: ("button" | "heading1" | "heading2" | "heading3" | "heading4" | "heading5" | "heading6" | "paragraph1" | "paragraph2" | "paragraph3")[];
+/** The kind of text a field holds — the tiers a site-wide edit of that kind reaches. */
+export type TextRoleFamily = 'headings' | 'paragraphs' | 'button';
+export declare const FAMILY_TIERS: Record<TextRoleFamily, readonly CanonicalTextStyleType[]>;
+export declare const nearestBySize: (size: number, tiers: readonly CanonicalTextStyleType[]) => CanonicalTextStyleType;
+export declare const computeLegacyTargets: (options: Partial<TextStyleOptions> | undefined) => LegacyTargetMap;
+/**
+ * The role nearest a field's own font size: heading tiers for display-sized text, paragraph tiers
+ * for body, `paragraph1` when there is no size. A `paragraphs`-family field stays on a paragraph
+ * tier however big it is, so a site-wide heading edit never repaints it. `button` is never a best
+ * fit — a button field reaches it through its starting role or the retired `buttons` successor.
+ */
+export declare const bestFitRole: (style: TextStyleDeclaration, family?: TextRoleFamily) => CanonicalTextStyleType;
+export declare const DETACHED_UNSET_EFFECTIVE: Record<string, string>;
+export declare const materialiseLegacyTypography: (style: TextStyleDeclaration, oldRoleStyle: object, inheritedFontFamily?: string) => void;
+/**
+ * What a reconnect needs beyond the role table, all optional:
+ * - `startingRole` — the field's own role, which wins over successor and nearest-by-size;
+ * - `family` — the kind of text the field holds (`bestFitRole` keeps a paragraph on a paragraph
+ *   tier; migration-22 job A2 votes its font into that family);
+ * - `renderedDefaults` — values a renderer draws for an unset prop, which beat the role, so they
+ *   are the look to keep (the button view model's line height, the profile's sizes);
+ * - `inheritedFontFamily` — the site text font an unset family drew from the page root;
+ * - `drawnBeforeCascade` — the field was last drawn by the resolver before BP-5969's per-property
+ *   cascade (migration-22's input), where a role replaced its typography and those defaults.
+ */
+export interface ReconnectSpec {
+    startingRole?: CanonicalTextStyleType;
+    family?: TextRoleFamily;
+    renderedDefaults?: Partial<Record<string, string>>;
+    inheritedFontFamily?: string;
+    drawnBeforeCascade?: boolean;
+}
+export type RenderedDefaultsForContent = (content: Record<string, unknown>, key: string) => Partial<Record<string, string>> | undefined;
+export declare const BUTTON_ELEMENT_RECONNECT: ReconnectSpec;
+/**
+ * The reconnect spec for one content style field. Every button element starts on Button text and
+ * keeps what makes it different as overrides (James Joung, 2026-09-28): a section's
+ * `buttonTextStyle` and a link button's `titleStyle`.
+ */
+export declare const contentFieldReconnectSpec: (contentType: string | undefined, key: string) => ReconnectSpec;
+/**
+ * The font a field's own value shows, read the same way as the reconnect's look pin
+ * (`pinDrawnLook`), before its role's cascade would replace it (R16, migration-22 job A2, which
+ * only counts this — never mutates the field). A legacy role's font wins over the field's own, as
+ * production drew it; with no old role (undefined, `'none'`, an unknown string, or a retired role
+ * missing from the site's options) the field's own font wins, else the site's. A canonical role —
+ * which A2's input never holds — draws its own font, else the role's, else the site's.
+ */
+export declare const drawnFontFamily: (style: Partial<TextStyleDeclaration> | undefined, options: TextStyleOptions | undefined, siteFont: string) => string;
+/**
+ * Reconnect one style to a canonical role, keeping its look. A canonical role is returned as is.
+ * Otherwise the role is `startingRole ?? (retired ? its successor : nearest by size)`, the look is
+ * pinned, and values equal to the new role are dropped, so only a real difference remains as an
+ * override. The look is the retired role's typography where that role replaced the field's own
+ * (`drawnBeforeCascade`); else the field's own values, then a renderer's defaults, then the old
+ * role's or the inherited values.
+ */
+export declare const reconnectTextStyle: <T extends object>(style: T, targets: LegacyTargetMap, options: TextStyleOptions | undefined, spec?: ReconnectSpec) => T;
+export declare const siteTextFontName: (brandPageModel: BrandPageModel) => string | undefined;
+/**
+ * Reconnect every persisted text field outside the ten, in place: content style keys (each with
+ * `contentFieldReconnectSpec`) and `textItems[].textStyle`, then per viewport the footer copyright,
+ * the nav tabs (starting role `paragraph1`), the hamburger menu (`button`) and the header button
+ * (`button`), then the Save Contact button (`button`). An unset family keeps the site text font.
+ * A payment or shop success message with no role of its own gets the look it drew
+ * (`seedSuccessMessageStyle`). Otherwise a no-op on canonical data.
+ */
+export declare const reconnectTextStyleRoles: (brandPageModel: BrandPageModel, targets: LegacyTargetMap, options: TextStyleOptions, walk?: Pick<ReconnectSpec, "drawnBeforeCascade"> & {
+    renderedDefaultsForContent?: RenderedDefaultsForContent;
+}) => void;