@pushwoosh/websdk-common 0.0.0 → 6.17.0

package/web-popups/index.d.ts

@@ -0,0 +1,9 @@
+export { WebPopupReader, WebPopupBox, WebPopupSlotView } from './WebPopupReader';
+export { WEB_POPUP_TEMPLATES, findWebPopupTemplate } from './templates';
+export { parseWebPopupJson, stringifyWebPopup, resolveWebPopupPages, resolveWebPopupPageSize, startPageOf, safeUrl, sanitizeWebPopupHtml, normalizeWebPopupColors, normalizeWebPopupValues, webPopupValuesMap, collectWebPopupFormCodes, webPopupExpired, normalizeWebPopupDark, WEB_POPUP_MAX_SIZE_PX, } from './helpers';
+export { webPopupTimerLabels, webPopupTimerRemaining, webPopupTimeZoneSupported, webPopupWallClockMs, type WebPopupTimerLabels, } from './timer';
+export { normalizeWebPopupLayout, substituteWebPopupLayoutValues, WEB_POPUP_VALUE_KEY_PATTERN, webPopupBackgroundImageStyle, webPopupContainerStyle, webPopupCssLength, webPopupPaddingValue, webPopupTracksValue, } from './layout';
+export { WEB_POPUP_VERSION, WEB_POPUP_FONT_STACK, WEB_POPUP_TEXT_COLOR, WEB_POPUP_TEXT_SECONDARY_COLOR, WEB_POPUP_ACCENT_COLOR, WEB_POPUP_BACKGROUND_COLOR, WEB_POPUP_DEFAULT_COLORS, webPopupTextColor, WEB_POPUP_TEXT_VARIANT_STYLES, WEB_POPUP_BG_SECTION_FALLBACK, WEB_POPUP_TEXT_SLOT_PADDING, WEB_POPUP_BUTTON_SLOT_PADDING, webPopupSlotGap, webPopupSlotRole, type WebPopupSlotRole, WEB_POPUP_DEFAULT_WIDTH, WEB_POPUP_LAYOUT_MAX_DEPTH, WEB_POPUP_LAYOUT_MAX_NODES, webPopupButtonPillStyle, webPopupFormInputStyle, WEB_POPUP_FORM_INPUT_BORDER, WEB_POPUP_FORM_ERROR_COLOR, WEB_POPUP_FORM_ERROR_COLOR_DARK, WEB_POPUP_ON_ACCENT_COLOR, WEB_POPUP_FORM_DEFAULTS, WEB_POPUP_CHOICE_DEFAULTS, WEB_POPUP_MAX_CHOICE_OPTIONS, WEB_POPUP_RATING_DEFAULTS, WEB_POPUP_RETRY_ERROR, webPopupRatingScores, } from './constants';
+export { resolveWebPopupBoxChrome, resolveWebPopupColors, autoDarkWebPopupColors, webPopupColorAlpha, webPopupDarkColors, webPopupDarkEnabled, webPopupEffectiveScheme, webPopupImageSrc, webPopupMixColor, webPopupShiftColor, } from './palette';
+export { WEB_POPUP_GLYPH_NAMES, WEB_POPUP_GLYPH_PATHS, WEB_POPUP_GLYPH_SIZES, WEB_POPUP_THUMB_UP_PATH, } from './glyphs';
+export { type WebPopupJson, type WebPopupKind, type WebPopupParams, type WebPopupColors, type WebPopupChrome, type WebPopupPageParams, type WebPopupResolvedPage, type WebPopupDark, type WebPopupResolvedColors, type WebPopupColorScheme, type WebPopupColorSchemePref, type WebPopupSlot, type WebPopupImage, type WebPopupVideo, type WebPopupPlacement, type WebPopupOverlay, type WebPopupAnimation, type WebPopupButtonAction, type WebPopupButtonVariant, type WebPopupTextVariant, type WebPopupTextAlign, type WebPopupVAnchor, type WebPopupHAnchor, type WebPopupReaderMode, type WebPopupReaderProps, type WebPopupLeafRenderers, type WebPopupBoxProps, type WebPopupLayoutNode, type WebPopupContainerNode, type WebPopupContentNode, type WebPopupImageNode, type WebPopupContainerType, type WebPopupContainerProps, type WebPopupContentZone, type WebPopupContentTone, type WebPopupCssLength, type WebPopupBoxSides, type WebPopupAlignItems, type WebPopupJustifyContent, type WebPopupValueParam, type WebPopupValueControl, type WebPopupLengthUnit, type WebPopupLengthRange, type WebPopupValueRef, type WebPopupTemplate, type WebPopupFormField, type WebPopupFormFieldKind, type WebPopupFormPrivacy, type WebPopupFormSubmitPayload, type WebPopupFormSubmitResult, type WebPopupFormSubmitHandler, type WebPopupTimerSlot, type WebPopupTimerExpireAction, type WebPopupTimerRemaining, type WebPopupChoiceSlot, type WebPopupChoiceOption, type WebPopupChoiceControl, type WebPopupChoiceSubmitPayload, type WebPopupChoiceSubmitHandler, type WebPopupRatingSlot, type WebPopupRatingScale, type WebPopupRatingSubmitMode, type WebPopupRatingSubmitPayload, type WebPopupRatingSubmitHandler, type WebPopupSubscribeResult, type WebPopupGlyphSlot, type WebPopupGlyphName, type WebPopupGlyphSize, type WebPopupSlotViewProps, } from './types';

package/web-popups/index.js

@@ -0,0 +1,8 @@
+export { WebPopupReader, WebPopupBox, WebPopupSlotView } from './WebPopupReader';
+export { WEB_POPUP_TEMPLATES, findWebPopupTemplate } from './templates';
+export { parseWebPopupJson, stringifyWebPopup, resolveWebPopupPages, resolveWebPopupPageSize, startPageOf, safeUrl, sanitizeWebPopupHtml, normalizeWebPopupColors, normalizeWebPopupValues, webPopupValuesMap, collectWebPopupFormCodes, webPopupExpired, normalizeWebPopupDark, WEB_POPUP_MAX_SIZE_PX } from './helpers';
+export { webPopupTimerLabels, webPopupTimerRemaining, webPopupTimeZoneSupported, webPopupWallClockMs } from './timer';
+export { normalizeWebPopupLayout, substituteWebPopupLayoutValues, WEB_POPUP_VALUE_KEY_PATTERN, webPopupBackgroundImageStyle, webPopupContainerStyle, webPopupCssLength, webPopupPaddingValue, webPopupTracksValue } from './layout';
+export { WEB_POPUP_VERSION, WEB_POPUP_FONT_STACK, WEB_POPUP_TEXT_COLOR, WEB_POPUP_TEXT_SECONDARY_COLOR, WEB_POPUP_ACCENT_COLOR, WEB_POPUP_BACKGROUND_COLOR, WEB_POPUP_DEFAULT_COLORS, webPopupTextColor, WEB_POPUP_TEXT_VARIANT_STYLES, WEB_POPUP_BG_SECTION_FALLBACK, WEB_POPUP_TEXT_SLOT_PADDING, WEB_POPUP_BUTTON_SLOT_PADDING, webPopupSlotGap, webPopupSlotRole, WEB_POPUP_DEFAULT_WIDTH, WEB_POPUP_LAYOUT_MAX_DEPTH, WEB_POPUP_LAYOUT_MAX_NODES, webPopupButtonPillStyle, webPopupFormInputStyle, WEB_POPUP_FORM_INPUT_BORDER, WEB_POPUP_FORM_ERROR_COLOR, WEB_POPUP_FORM_ERROR_COLOR_DARK, WEB_POPUP_ON_ACCENT_COLOR, WEB_POPUP_FORM_DEFAULTS, WEB_POPUP_CHOICE_DEFAULTS, WEB_POPUP_MAX_CHOICE_OPTIONS, WEB_POPUP_RATING_DEFAULTS, WEB_POPUP_RETRY_ERROR, webPopupRatingScores } from './constants';
+export { resolveWebPopupBoxChrome, resolveWebPopupColors, autoDarkWebPopupColors, webPopupColorAlpha, webPopupDarkColors, webPopupDarkEnabled, webPopupEffectiveScheme, webPopupImageSrc, webPopupMixColor, webPopupShiftColor } from './palette';
+export { WEB_POPUP_GLYPH_NAMES, WEB_POPUP_GLYPH_PATHS, WEB_POPUP_GLYPH_SIZES, WEB_POPUP_THUMB_UP_PATH } from './glyphs';

package/web-popups/layout.d.ts

@@ -0,0 +1,39 @@
+import { type CSSProperties } from 'react';
+import { type WebPopupBoxSides, type WebPopupContainerNode, type WebPopupCssLength, type WebPopupLayoutNode } from './types';
+/**
+ * Validate an embedded layout tree from the stored json. Returns the
+ * normalized tree, or null when the value isn't a renderable tree at all —
+ * the page is then dropped by resolveWebPopupPages.
+ */
+export declare function normalizeWebPopupLayout(raw: unknown): WebPopupLayoutNode | null;
+/** A page value key, as referenced from the tree by a `$key` token. */
+export declare const WEB_POPUP_VALUE_KEY_PATTERN: RegExp;
+/**
+ * Substitute a page's named values into its RAW layout tree — `$key` tokens
+ * in string props become the values, verbatim. Runs BEFORE
+ * normalizeWebPopupLayout (see resolveWebPopupPages), so a substituted value
+ * passes exactly the whitelists/clamps a literal one would; substitution is
+ * single-pass and normalizeWebPopupValues rejects values containing '$', so
+ * refs can't chain. Binding keys (`content`, `image`, `backgroundImage`) are
+ * never substituted — they already name params by design.
+ */
+export declare function substituteWebPopupLayoutValues(layout: unknown, values: Record<string, string>): unknown;
+export declare function webPopupCssLength(value: WebPopupCssLength): string;
+export declare function webPopupPaddingValue(padding: WebPopupCssLength | WebPopupBoxSides): string;
+/** grid-template value for Columns/Rows: absent sizes = one 1fr per child. */
+export declare function webPopupTracksValue(sizes: number | string | undefined, childCount: number): string;
+export declare function webPopupScrimGradient(dim?: number): string | null;
+/**
+ * The cover-background css of a container that draws an image behind its
+ * content. `dim` (0–1) is the image's scrim — a dark translucent layer
+ * painted as a gradient stacked over the url() in the same property, so it
+ * needs no extra element and rides along wherever the background is drawn.
+ */
+export declare function webPopupBackgroundImageStyle(src: string, dim?: number): CSSProperties;
+/**
+ * The inline style of a container node — grid, mirroring kit-helpers'
+ * Vertical/Horizontal/Columns/Rows semantics. The background image is passed
+ * resolved (looked up in the page's images by the caller) so this stays a
+ * pure props → css mapping.
+ */
+export declare function webPopupContainerStyle(node: WebPopupContainerNode, backgroundSrc?: string, backgroundDim?: number): CSSProperties;

package/web-popups/layout.js

@@ -0,0 +1,290 @@
+import { WEB_POPUP_LAYOUT_MAX_DEPTH, WEB_POPUP_LAYOUT_MAX_NODES } from './constants';
+// Validation + css conversion for the embedded layout tree. The json is
+// API-writable and its styles land inline on customers' pages, so every prop
+// is normalized against a whitelist on parse: numbers are clamped, strings
+// must match a strict css-length/track pattern, enums fall back to defaults,
+// unknown props are dropped. Unknown node TYPES degrade instead of breaking:
+// a node with children renders as a Vertical stack (a container from a NEWER
+// editor keeps its content visible on an older engine build), a childless
+// unknown node is dropped.
+const CONTAINER_TYPES = ['Vertical', 'Horizontal', 'Columns', 'Rows'];
+const ORDERS = ['normal', 'reverse'];
+const ALIGN_ITEMS = ['start', 'center', 'end', 'stretch'];
+const JUSTIFY_CONTENT = ['start', 'center', 'end', 'space-between'];
+const TEXT_ALIGNS = ['left', 'center', 'right'];
+const TONES = ['default', 'inverse'];
+const MAX_LENGTH_PX = 2000;
+// String lengths carry a unit — clamp each to its own sane ceiling, like the
+// numeric branch: a wire value ("9999rem" scales off the HOST page's root
+// font size) must not be able to blow the popup past the viewport.
+const LENGTH_UNIT_MAX = {
+  px: MAX_LENGTH_PX,
+  '%': 100,
+  em: 125,
+  rem: 125
+};
+const LENGTH_PATTERN = /^(\d{1,4}(?:\.\d+)?)(px|%|em|rem)$/;
+const TRACK_UNIT_MAX = {
+  px: MAX_LENGTH_PX,
+  '%': 100,
+  fr: 100
+};
+const TRACK_PATTERN = /^(\d{1,4}(?:\.\d+)?)(px|%|fr)$/;
+const TRACK_KEYWORDS = ['auto', 'min-content', 'max-content'];
+const MAX_TRACKS = 12;
+function oneOf(value, allowed) {
+  return allowed.includes(value) ? value : undefined;
+}
+function cssLength(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return Math.min(Math.max(value, 0), MAX_LENGTH_PX);
+  }
+  if (typeof value !== 'string') return undefined;
+  const match = LENGTH_PATTERN.exec(value.trim());
+  if (!match) return undefined;
+  const [, amount, unit] = match;
+  return `${Math.min(parseFloat(amount), LENGTH_UNIT_MAX[unit])}${unit}`;
+}
+const BOX_SIDES = ['top', 'right', 'bottom', 'left'];
+function boxPadding(value) {
+  const whole = cssLength(value);
+  if (whole !== undefined) return whole;
+  if (typeof value !== 'object' || value === null) return undefined;
+  const sides = {};
+  for (const side of BOX_SIDES) {
+    const sideValue = cssLength(value[side]);
+    if (sideValue !== undefined) sides[side] = sideValue;
+  }
+  return Object.keys(sides).length > 0 ? sides : undefined;
+}
+function trackSize(token) {
+  if (TRACK_KEYWORDS.includes(token)) return token;
+  const match = TRACK_PATTERN.exec(token);
+  if (!match) return undefined;
+  const [, amount, unit] = match;
+  return `${Math.min(parseFloat(amount), TRACK_UNIT_MAX[unit])}${unit}`;
+}
+function trackSizes(value) {
+  if (typeof value === 'number') {
+    return Number.isInteger(value) && value >= 1 && value <= MAX_TRACKS ? value : undefined;
+  }
+  if (typeof value !== 'string') return undefined;
+  const tokens = value.trim().split(/\s+/);
+  if (tokens.length < 1 || tokens.length > MAX_TRACKS) return undefined;
+  const clamped = tokens.map(trackSize);
+  return clamped.every(token => token !== undefined) ? clamped.join(' ') : undefined;
+}
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function containerProps(raw) {
+  const props = {};
+  const gap = cssLength(raw.gap);
+  if (gap !== undefined) props.gap = gap;
+  const padding = boxPadding(raw.padding);
+  if (padding !== undefined) props.padding = padding;
+  const alignItems = oneOf(raw.alignItems, ALIGN_ITEMS);
+  if (alignItems) props.alignItems = alignItems;
+  const justifyContent = oneOf(raw.justifyContent, JUSTIFY_CONTENT);
+  if (justifyContent) props.justifyContent = justifyContent;
+  const alignContent = oneOf(raw.alignContent, JUSTIFY_CONTENT);
+  if (alignContent) props.alignContent = alignContent;
+  const backgroundImage = nonEmptyString(raw.backgroundImage);
+  if (backgroundImage) props.backgroundImage = backgroundImage;
+  const sizes = trackSizes(raw.sizes);
+  if (sizes !== undefined) props.sizes = sizes;
+  return props;
+}
+function normalizeNode(raw, depth, budget) {
+  if (depth > WEB_POPUP_LAYOUT_MAX_DEPTH || budget.nodes <= 0) return null;
+  if (typeof raw !== 'object' || raw === null) return null;
+  budget.nodes -= 1;
+  const node = raw;
+  const props = typeof node.props === 'object' && node.props !== null ? node.props : {};
+  if (node.type === 'Content') {
+    const content = nonEmptyString(props.content);
+    if (!content) return null;
+    const out = {
+      type: 'Content',
+      props: {
+        content
+      }
+    };
+    const align = oneOf(props.align, TEXT_ALIGNS);
+    if (align) out.props.align = align;
+    const tone = oneOf(props.tone, TONES);
+    if (tone && tone !== 'default') out.props.tone = tone;
+    return out;
+  }
+  if (node.type === 'Image') {
+    const image = nonEmptyString(props.image);
+    if (!image) return null;
+    const out = {
+      type: 'Image',
+      props: {
+        image
+      }
+    };
+    return out;
+  }
+  if (!Array.isArray(node.children)) return null;
+  const type = oneOf(node.type, CONTAINER_TYPES) ?? 'Vertical';
+  const children = [];
+  for (const child of node.children) {
+    const normalized = normalizeNode(child, depth + 1, budget);
+    if (normalized) children.push(normalized);
+  }
+  const out = containerProps(props);
+  // `order: 'reverse'` is applied right here and consumed: the normalized
+  // tree carries the children already reordered (and the sizes template
+  // reversed with them, so each child keeps its track) — the renderers and
+  // the editor canvas never see the prop. Caveat for hand-authored json: the
+  // "keeps its track" guarantee assumes one sizes token per child; with a
+  // mismatched count the reversed template pairs children with different
+  // tracks (grid itself would misalign such a template the same way).
+  if (oneOf(props.order, ORDERS) === 'reverse') {
+    children.reverse();
+    if (typeof out.sizes === 'string') out.sizes = out.sizes.split(' ').reverse().join(' ');
+  }
+  return {
+    type,
+    props: out,
+    children
+  };
+}
+/**
+ * Validate an embedded layout tree from the stored json. Returns the
+ * normalized tree, or null when the value isn't a renderable tree at all —
+ * the page is then dropped by resolveWebPopupPages.
+ */
+export function normalizeWebPopupLayout(raw) {
+  return normalizeNode(raw, 0, {
+    nodes: WEB_POPUP_LAYOUT_MAX_NODES
+  });
+}
+// --- value substitution ($refs) ---------------------------------------------
+/** A page value key, as referenced from the tree by a `$key` token. */
+export const WEB_POPUP_VALUE_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+const VALUE_REF_PATTERN = /^\$([a-zA-Z][a-zA-Z0-9-]*)$/;
+// Every whitespace-separated token of the form $key is replaced; separators
+// survive, so both a whole-string prop ('$stackGap') and a token inside a
+// sizes template ('1fr $imageWidth') substitute with the same rule. An
+// unknown key stays as-is and fails the prop whitelist downstream — the prop
+// is dropped, same as any invalid literal.
+function substituteString(value, values) {
+  if (!value.includes('$')) return value;
+  return value.split(/(\s+)/).map(token => {
+    const key = VALUE_REF_PATTERN.exec(token)?.[1];
+    // Own properties only: '$constructor' must stay an unknown ref, not
+    // resolve to an Object.prototype member.
+    return key !== undefined && Object.prototype.hasOwnProperty.call(values, key) ? values[key] : token;
+  }).join('');
+}
+/**
+ * Substitute a page's named values into its RAW layout tree — `$key` tokens
+ * in string props become the values, verbatim. Runs BEFORE
+ * normalizeWebPopupLayout (see resolveWebPopupPages), so a substituted value
+ * passes exactly the whitelists/clamps a literal one would; substitution is
+ * single-pass and normalizeWebPopupValues rejects values containing '$', so
+ * refs can't chain. Binding keys (`content`, `image`, `backgroundImage`) are
+ * never substituted — they already name params by design.
+ */
+export function substituteWebPopupLayoutValues(layout, values) {
+  if (typeof layout !== 'object' || layout === null || Object.keys(values).length === 0) return layout;
+  return substituteNode(layout, values, 0);
+}
+const BINDING_PROPS = new Set(['content', 'image', 'backgroundImage']);
+function substituteNode(raw, values, depth) {
+  if (depth > WEB_POPUP_LAYOUT_MAX_DEPTH || typeof raw !== 'object' || raw === null) return raw;
+  const node = raw;
+  const out = {
+    ...node
+  };
+  if (typeof node.props === 'object' && node.props !== null) {
+    const props = {
+      ...node.props
+    };
+    for (const [key, value] of Object.entries(props)) {
+      if (BINDING_PROPS.has(key)) continue;
+      if (typeof value === 'string') {
+        props[key] = substituteString(value, values);
+      } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        // Per-side paddings: one level of string sides.
+        const sides = {
+          ...value
+        };
+        for (const [side, sideValue] of Object.entries(sides)) {
+          if (typeof sideValue === 'string') sides[side] = substituteString(sideValue, values);
+        }
+        props[key] = sides;
+      }
+    }
+    out.props = props;
+  }
+  if (Array.isArray(node.children)) {
+    out.children = node.children.map(child => substituteNode(child, values, depth + 1));
+  }
+  return out;
+}
+// --- css conversion (shared by the reader and the editor's canvas) ---------
+export function webPopupCssLength(value) {
+  return typeof value === 'number' ? `${value}px` : value;
+}
+export function webPopupPaddingValue(padding) {
+  if (typeof padding === 'number' || typeof padding === 'string') return webPopupCssLength(padding);
+  const side = value => value === undefined ? '0' : webPopupCssLength(value);
+  return `${side(padding.top)} ${side(padding.right)} ${side(padding.bottom)} ${side(padding.left)}`;
+}
+/** grid-template value for Columns/Rows: absent sizes = one 1fr per child. */
+export function webPopupTracksValue(sizes, childCount) {
+  if (typeof sizes === 'string') return sizes;
+  const count = typeof sizes === 'number' ? sizes : Math.max(childCount, 1);
+  return `repeat(${count}, 1fr)`;
+}
+// The scrim as a standalone gradient, for the layers that can't stack it in
+// the same background property (a background VIDEO paints its own element).
+export function webPopupScrimGradient(dim = 0) {
+  if (!(dim > 0)) return null;
+  const scrim = `rgba(16, 24, 40, ${Math.min(dim, 1)})`;
+  return `linear-gradient(${scrim}, ${scrim})`;
+}
+/**
+ * The cover-background css of a container that draws an image behind its
+ * content. `dim` (0–1) is the image's scrim — a dark translucent layer
+ * painted as a gradient stacked over the url() in the same property, so it
+ * needs no extra element and rides along wherever the background is drawn.
+ */
+export function webPopupBackgroundImageStyle(src, dim = 0) {
+  // JSON.stringify quotes + escapes the url, so an src can't break out of
+  // the css function.
+  const image = `url(${JSON.stringify(src)})`;
+  const scrim = webPopupScrimGradient(dim);
+  return {
+    backgroundImage: scrim ? `${scrim}, ${image}` : image,
+    backgroundSize: 'cover',
+    backgroundPosition: 'center'
+  };
+}
+/**
+ * The inline style of a container node — grid, mirroring kit-helpers'
+ * Vertical/Horizontal/Columns/Rows semantics. The background image is passed
+ * resolved (looked up in the page's images by the caller) so this stays a
+ * pure props → css mapping.
+ */
+export function webPopupContainerStyle(node, backgroundSrc, backgroundDim = 0) {
+  const props = node.props ?? {};
+  const style = {
+    display: 'grid',
+    minWidth: 0
+  };
+  if (node.type === 'Horizontal') style.gridAutoFlow = 'column';
+  if (node.type === 'Columns') style.gridTemplateColumns = webPopupTracksValue(props.sizes, node.children.length);
+  if (node.type === 'Rows') style.gridTemplateRows = webPopupTracksValue(props.sizes, node.children.length);
+  if (props.gap !== undefined) style.gap = webPopupCssLength(props.gap);
+  if (props.padding !== undefined) style.padding = webPopupPaddingValue(props.padding);
+  if (props.alignItems) style.alignItems = props.alignItems;
+  if (props.justifyContent) style.justifyContent = props.justifyContent;
+  if (props.alignContent) style.alignContent = props.alignContent;
+  if (backgroundSrc) Object.assign(style, webPopupBackgroundImageStyle(backgroundSrc, backgroundDim));
+  return style;
+}

package/web-popups/palette.d.ts

@@ -0,0 +1,34 @@
+import { type WebPopupColorScheme, type WebPopupColors, type WebPopupDark, type WebPopupImage, type WebPopupOverlay, type WebPopupResolvedColors } from './types';
+/** Hue and saturation survive; only lightness moves. Non-hex colors pass through. */
+export declare function webPopupShiftColor(color: string, direction: 'fold' | 'lift'): string;
+/** `ratio` of `over` blended into `base`; either color non-hex = `base` unchanged. */
+export declare function webPopupMixColor(base: string, over: string, ratio: number): string;
+/** `color` at `alpha` as rgba(); a non-hex color renders full-strength instead of being guessed at. */
+export declare function webPopupColorAlpha(color: string, alpha: number): string;
+export declare function autoDarkWebPopupColors(light: WebPopupColors): WebPopupColors;
+/** The dark palette a popup renders with: authored roles over the autogenerated ones. */
+export declare function webPopupDarkColors(light: WebPopupColors, dark?: WebPopupDark): WebPopupColors;
+/** True when the popup opts into dark mode at all — the host's cue to watch the media query. */
+export declare function webPopupDarkEnabled(chrome: {
+    dark?: WebPopupDark;
+}): boolean;
+/** The scheme a popup actually draws with: 'dark' only when it opts in. */
+export declare function webPopupEffectiveScheme(chrome: {
+    dark?: WebPopupDark;
+}, scheme?: WebPopupColorScheme): WebPopupColorScheme;
+export declare function resolveWebPopupColors(chrome: {
+    colors: WebPopupColors;
+    dark?: WebPopupDark;
+}, scheme?: WebPopupColorScheme): WebPopupResolvedColors;
+/** The url drawn for `scheme`; a dark source only exists when authored. */
+export declare function webPopupImageSrc(image: WebPopupImage, scheme?: WebPopupColorScheme): string;
+/** The page dim and box shadow for the scheme actually drawn; the light ones
+ * stand in wherever the dark palette authored no override. */
+export declare function resolveWebPopupBoxChrome(chrome: {
+    dark?: WebPopupDark;
+    overlay?: WebPopupOverlay;
+    boxShadow: string;
+}, scheme?: WebPopupColorScheme): {
+    overlay?: WebPopupOverlay;
+    boxShadow: string;
+};

package/web-popups/palette.js

@@ -0,0 +1,157 @@
+// Scheme resolution for the popup palette: the authored light/dark roles plus
+// the derived ones (input surface, borders, the label over an accent fill).
+import { WEB_POPUP_DEFAULT_COLORS, WEB_POPUP_FORM_ERROR_COLOR, WEB_POPUP_FORM_ERROR_COLOR_DARK, WEB_POPUP_FORM_INPUT_BORDER, WEB_POPUP_ON_ACCENT_COLOR, WEB_POPUP_TEXT_COLOR, WEB_POPUP_TEXT_SECONDARY_COLOR } from './constants';
+const HEX_RE = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+function parseHex(color) {
+  const hex = HEX_RE.exec(color.trim())?.[1];
+  if (!hex) return null;
+  const full = hex.length === 3 ? hex.split('').map(c => c + c).join('') : hex;
+  return [0, 2, 4].map(i => parseInt(full.slice(i, i + 2), 16));
+}
+function toHex([r, g, b]) {
+  return `#${[r, g, b].map(v => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0')).join('')}`;
+}
+function rgbToHsl([r, g, b]) {
+  const [rn, gn, bn] = [r / 255, g / 255, b / 255];
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === rn) h = (gn - bn) / d + (gn < bn ? 6 : 0);else if (max === gn) h = (bn - rn) / d + 2;else h = (rn - gn) / d + 4;
+  return [h / 6, s, l];
+}
+function hueToChannel(p, q, t) {
+  let tn = t;
+  if (tn < 0) tn += 1;
+  if (tn > 1) tn -= 1;
+  if (tn < 1 / 6) return p + (q - p) * 6 * tn;
+  if (tn < 1 / 2) return q;
+  if (tn < 2 / 3) return p + (q - p) * (2 / 3 - tn) * 6;
+  return p;
+}
+function hslToRgb([h, s, l]) {
+  if (s === 0) {
+    const v = l * 255;
+    return [v, v, v];
+  }
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  return [hueToChannel(p, q, h + 1 / 3) * 255, hueToChannel(p, q, h) * 255, hueToChannel(p, q, h - 1 / 3) * 255];
+}
+// Mirror the light half onto [0.07, 0.5]: #FFFFFF lands on the dark canvas
+// tone and near-whites stay apart instead of collapsing into one floor.
+function foldLightness(l) {
+  return l > 0.5 ? 0.07 + (1 - l) * ((0.5 - 0.07) / 0.5) : l;
+}
+// Mirror the dark half onto [0.5, 0.93]: #000000 lands short of glaring white.
+function liftLightness(l) {
+  return l < 0.5 ? 0.93 - l * ((0.93 - 0.5) / 0.5) : l;
+}
+/** Hue and saturation survive; only lightness moves. Non-hex colors pass through. */
+export function webPopupShiftColor(color, direction) {
+  const rgb = parseHex(color);
+  if (!rgb) return color;
+  const [h, s, l] = rgbToHsl(rgb);
+  return toHex(hslToRgb([h, s, direction === 'fold' ? foldLightness(l) : liftLightness(l)]));
+}
+/** `ratio` of `over` blended into `base`; either color non-hex = `base` unchanged. */
+export function webPopupMixColor(base, over, ratio) {
+  const a = parseHex(base);
+  const b = parseHex(over);
+  if (!a || !b) return base;
+  return toHex(a.map((v, i) => v + (b[i] - v) * ratio));
+}
+/** `color` at `alpha` as rgba(); a non-hex color renders full-strength instead of being guessed at. */
+export function webPopupColorAlpha(color, alpha) {
+  const rgb = parseHex(color);
+  if (!rgb || alpha >= 1) return color;
+  const [r, g, b] = rgb;
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+function isLightColor(color) {
+  const rgb = parseHex(color);
+  if (!rgb) return false;
+  // Perceived luminance, not HSL lightness: #FFFF00 and #0000FF share l = 0.5.
+  const [r, g, b] = rgb;
+  return (0.299 * r + 0.587 * g + 0.114 * b) / 255 > 0.6;
+}
+// The dark counterpart of a light palette: text lifts, surfaces fold, the
+// accent and the over-image inverse color stay as authored.
+export function autoDarkWebPopupColors(light) {
+  return {
+    background: webPopupShiftColor(light.background, 'fold'),
+    accent: light.accent,
+    text: webPopupShiftColor(light.text, 'lift'),
+    textSecondary: webPopupShiftColor(light.textSecondary, 'lift'),
+    textInverse: light.textInverse
+  };
+}
+// Light keeps the values the popup shipped with before dark mode existed
+// (white cards, grey border, white label) — enabling dark must not restyle it.
+function derivedColors(colors, scheme) {
+  if (scheme === 'light') {
+    return {
+      surface: WEB_POPUP_DEFAULT_COLORS.background,
+      surfaceText: WEB_POPUP_TEXT_COLOR,
+      border: WEB_POPUP_FORM_INPUT_BORDER,
+      onAccent: WEB_POPUP_ON_ACCENT_COLOR,
+      error: WEB_POPUP_FORM_ERROR_COLOR,
+      chromeIcon: WEB_POPUP_TEXT_SECONDARY_COLOR
+    };
+  }
+  return {
+    surface: webPopupMixColor(colors.background, colors.text, 0.08),
+    surfaceText: colors.text,
+    border: webPopupMixColor(colors.background, colors.text, 0.24),
+    onAccent: isLightColor(colors.accent) ? WEB_POPUP_TEXT_COLOR : WEB_POPUP_ON_ACCENT_COLOR,
+    error: WEB_POPUP_FORM_ERROR_COLOR_DARK,
+    chromeIcon: colors.textSecondary
+  };
+}
+/** The dark palette a popup renders with: authored roles over the autogenerated ones. */
+export function webPopupDarkColors(light, dark) {
+  return {
+    ...autoDarkWebPopupColors(light),
+    ...(dark?.colors ?? {})
+  };
+}
+/** True when the popup opts into dark mode at all — the host's cue to watch the media query. */
+export function webPopupDarkEnabled(chrome) {
+  return chrome.dark?.enabled === true;
+}
+/** The scheme a popup actually draws with: 'dark' only when it opts in. */
+export function webPopupEffectiveScheme(chrome, scheme = 'light') {
+  return scheme === 'dark' && webPopupDarkEnabled(chrome) ? 'dark' : 'light';
+}
+// Every color a renderer needs, for the scheme actually drawn. Asking for
+// 'dark' on a popup without dark mode returns the light palette.
+export function resolveWebPopupColors(chrome, scheme = 'light') {
+  const effective = webPopupEffectiveScheme(chrome, scheme);
+  const colors = effective === 'dark' ? webPopupDarkColors(chrome.colors, chrome.dark) : chrome.colors;
+  return {
+    ...colors,
+    scheme: effective,
+    ...derivedColors(colors, effective)
+  };
+}
+/** The url drawn for `scheme`; a dark source only exists when authored. */
+export function webPopupImageSrc(image, scheme = 'light') {
+  return scheme === 'dark' && image.srcDark ? image.srcDark : image.src;
+}
+/** The page dim and box shadow for the scheme actually drawn; the light ones
+ * stand in wherever the dark palette authored no override. */
+export function resolveWebPopupBoxChrome(chrome, scheme = 'light') {
+  if (webPopupEffectiveScheme(chrome, scheme) === 'light') {
+    return {
+      overlay: chrome.overlay,
+      boxShadow: chrome.boxShadow
+    };
+  }
+  return {
+    overlay: chrome.dark?.overlay ?? chrome.overlay,
+    boxShadow: chrome.dark?.boxShadow ?? chrome.boxShadow
+  };
+}

package/web-popups/templates.d.ts

@@ -0,0 +1,3 @@
+import { type WebPopupTemplate } from './types';
+export declare const WEB_POPUP_TEMPLATES: WebPopupTemplate[];
+export declare function findWebPopupTemplate(name: string): WebPopupTemplate | undefined;

package/web-popups/templates.js

@@ -0,0 +1,125 @@
+// The system layout templates — the small blessed set of arrangements the
+// editor's kind catalog (smart-blocks) instantiates: a kind is a template
+// name plus gallery data (label, chrome, demo content, value defaults); only
+// a genuinely unique arrangement warrants a kind carrying its own tree. The
+// trees reference `$key` value params (resolved per page at render, see
+// substituteWebPopupLayoutValues) and bind the canonical keys — zone 'main',
+// image 'image' — which the catalog may rebind when instantiating.
+// EDITOR-ONLY, like the kind catalog: the display engine renders the tree
+// embedded in each page and must not pull this module.
+// The default padded box around a content zone (matches the editor canvas).
+const CONTENT_PAD = {
+  top: 24,
+  right: 24,
+  bottom: 22,
+  left: 24
+};
+// The single content zone in a padded box — the whole `content` template and
+// the text half of the image ones.
+const contentStack = () => ({
+  type: 'Vertical',
+  props: {
+    padding: CONTENT_PAD
+  },
+  children: [{
+    type: 'Content',
+    props: {
+      content: 'main',
+      align: 'center'
+    }
+  }]
+});
+const imageWidthParam = () => ({
+  key: 'imageWidth',
+  label: 'Image width',
+  control: {
+    kind: 'percent',
+    min: 20,
+    max: 70
+  },
+  value: '45%'
+});
+const imageSideParam = () => ({
+  key: 'imageSide',
+  label: 'Image position',
+  control: {
+    kind: 'select',
+    options: [{
+      value: 'normal',
+      label: 'Right'
+    }, {
+      value: 'reverse',
+      label: 'Left'
+    }]
+  },
+  value: 'normal'
+});
+export const WEB_POPUP_TEMPLATES = [
+// Just the content stack, no image.
+{
+  name: 'content',
+  layout: contentStack(),
+  params: []
+},
+// Image on top, the content stack below.
+{
+  name: 'vertical',
+  layout: {
+    type: 'Vertical',
+    children: [{
+      type: 'Image',
+      props: {
+        image: 'image'
+      }
+    }, contentStack()]
+  },
+  params: []
+},
+// Image beside the content; which side and how wide are the page's knobs.
+{
+  name: 'horizontal',
+  layout: {
+    type: 'Columns',
+    props: {
+      sizes: '1fr $imageWidth',
+      alignItems: 'center',
+      order: '$imageSide'
+    },
+    children: [contentStack(), {
+      type: 'Image',
+      props: {
+        image: 'image'
+      }
+    }]
+  },
+  params: [imageWidthParam(), imageSideParam()]
+},
+// The content over a cover background image (an inverse-tone zone: the
+// copy uses the palette's textInverse, the image gets the Dim scrim knob).
+{
+  name: 'content-over-image',
+  layout: {
+    type: 'Vertical',
+    props: {
+      padding: {
+        top: 36,
+        right: 24,
+        bottom: 34,
+        left: 24
+      },
+      backgroundImage: 'image'
+    },
+    children: [{
+      type: 'Content',
+      props: {
+        content: 'main',
+        align: 'center',
+        tone: 'inverse'
+      }
+    }]
+  },
+  params: []
+}];
+export function findWebPopupTemplate(name) {
+  return WEB_POPUP_TEMPLATES.find(template => template.name === name);
+}