@coras-io/embed 0.1.0

package/dist/sdk/validation.js

@@ -0,0 +1,318 @@
+import { FIELDS } from "@coras-io/brand-tokens";
+import { validateBrandConfig } from "@coras-io/brand-tokens/validate";
+import { supportedCurrencies } from "../core/currency/constants.js";
+import { allLocales } from "../core/i18n/locale-codes.js";
+/**
+ * A typed, redacted validation error thrown for invalid host input before any
+ * element is rendered or updated. Messages are safe to surface to the host.
+ */
+export class CorasValidationError extends Error {
+    constructor(code, message, field) {
+        super(message);
+        this.name = "CorasValidationError";
+        this.code = code;
+        this.field = field;
+    }
+}
+export const PUBLIC_PAGES = [
+    "landing",
+    "search",
+    "details",
+    "payment",
+    "help",
+    "suggestion-widget",
+];
+/**
+ * Reject a page name outside the public set with a typed error. Shared by mount,
+ * update, navigate and prefetch so every entry point fails the same way — and
+ * before any state is mutated — instead of indexing the registry with an unknown
+ * page and throwing a bare TypeError.
+ */
+export function assertValidPage(page) {
+    if (!PUBLIC_PAGES.includes(page)) {
+        throw new CorasValidationError("invalid_page", `Unknown page "${String(page)}". Valid pages: ${PUBLIC_PAGES.join(", ")}.`, "page");
+    }
+}
+/** Allowed param keys per page (public names). */
+export const PAGE_PARAM_KEYS = {
+    landing: [
+        "country",
+        "city",
+        "startDate",
+        "endDate",
+        "sort",
+        "duration",
+        "price",
+        "categories",
+    ],
+    search: ["search", "startDate"],
+    details: ["id", "date"],
+    payment: ["metadata"],
+    help: ["content"],
+    "suggestion-widget": ["limit", "showExploreCard", "country", "city"],
+};
+/**
+ * URL params whose string form decodes to a non-string type. Everything not
+ * listed stays a string. Used by the URL helpers so a value round-trips through
+ * a URL as the type `mount()` validation expects (e.g. `limit=3` -> `3`, not
+ * `"3"`; `showExploreCard=false` -> `false`, not a truthy `"false"`).
+ */
+export const PAGE_PARAM_TYPES = {
+    limit: "number",
+    showExploreCard: "boolean",
+};
+const CONFIG_KEYS = [
+    "apiUrl",
+    "distributorId",
+    "assetsUrl",
+    "locale",
+    "allowedLocales",
+    "currency",
+    "allowedCurrencies",
+    "loyaltyPointsEnabled",
+    "theme",
+    "colorScheme",
+];
+const localeSet = new Set(allLocales);
+const currencySet = new Set(supportedCurrencies);
+const colorSchemes = new Set([
+    "light",
+    "dark",
+    "system",
+    "inherit",
+]);
+/** Normalize locale casing/separators (e.g. `en_ie`, `EN-IE` -> `en-IE`). */
+export function normalizeLocale(value) {
+    const parts = value.trim().replace(/_/g, "-").split("-");
+    if (parts.length === 0 || !parts[0])
+        return undefined;
+    const language = parts[0].toLowerCase();
+    const region = parts[1]?.toUpperCase();
+    const canonical = region ? `${language}-${region}` : language;
+    return localeSet.has(canonical) ? canonical : undefined;
+}
+/** Normalize currency casing (e.g. `eur` -> `EUR`). */
+export function normalizeCurrency(value) {
+    const canonical = value.trim().toUpperCase();
+    return currencySet.has(canonical)
+        ? canonical
+        : undefined;
+}
+function isLocalHost(hostname) {
+    return (hostname === "localhost" ||
+        hostname === "127.0.0.1" ||
+        hostname === "[::1]" ||
+        hostname.endsWith(".localhost"));
+}
+/**
+ * Require an https URL (http allowed only for localhost dev). Returns the
+ * parsed origin-safe href, or throws.
+ */
+export function assertSecureUrl(value, field) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new CorasValidationError("invalid_url", `${field} must be an absolute URL.`, field);
+    }
+    if (url.protocol === "https:")
+        return url.href;
+    if (url.protocol === "http:" && isLocalHost(url.hostname))
+        return url.href;
+    throw new CorasValidationError("invalid_url", `${field} must use https (http is only allowed for localhost).`, field);
+}
+// Strict hostname: alnum labels separated by dots, optional :port.
+// Rejects protocol-relative inputs, paths, and free-form strings.
+const BARE_HOSTNAME_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?::\d{1,5})?$/i;
+/**
+ * Asset URL must be one of:
+ *   - an https URL (http allowed only for localhost),
+ *   - a bare hostname like `images.coras.io[:port]`,
+ *   - a root-relative path like `/assets`.
+ * Rejected: protocol-relative URLs (`//host/x`), `javascript:` / `data:` URIs,
+ * traversal-style paths. `assetsUrl` is interpolated straight into image and
+ * SVG hrefs (see icon.component.ts), so a permissive validator is a foot-gun.
+ */
+function validateAssetsUrl(value) {
+    if (value === "") {
+        throw new CorasValidationError("invalid_url", "config.assetsUrl must not be empty.", "config.assetsUrl");
+    }
+    if (value.startsWith("/")) {
+        if (value.startsWith("//")) {
+            throw new CorasValidationError("invalid_url", "config.assetsUrl must not be protocol-relative.", "config.assetsUrl");
+        }
+        // Decode first so `%2e%2e` can't smuggle traversal past the raw check; a
+        // malformed escape (decodeURIComponent throws) is itself rejected.
+        let decoded;
+        try {
+            decoded = decodeURIComponent(value);
+        }
+        catch {
+            throw new CorasValidationError("invalid_url", "config.assetsUrl must be a valid encoded path.", "config.assetsUrl");
+        }
+        if (value.includes("..") || decoded.includes("..")) {
+            throw new CorasValidationError("invalid_url", "config.assetsUrl must not contain `..`.", "config.assetsUrl");
+        }
+        return;
+    }
+    if (value.includes("://")) {
+        assertSecureUrl(value, "config.assetsUrl");
+        return;
+    }
+    if (!BARE_HOSTNAME_RE.test(value)) {
+        throw new CorasValidationError("invalid_url", "config.assetsUrl must be an https URL, a bare hostname, or a root-relative path.", "config.assetsUrl");
+    }
+}
+// Field keys plus the BrandConfig meta keys validateBrandConfig understands.
+// Used only to surface unknown keys in strict mode (the schema itself strips
+// them silently, which a strict host wants flagged, not swallowed).
+const THEME_KEYS = [
+    ...FIELDS.map((field) => field.key),
+    "logo",
+    "fontFaces",
+    "dark",
+    "schemaVersion",
+];
+/**
+ * Validate `config.theme` (and its `dark` overrides) against the shared
+ * BrandConfig contract. Reuses brand-tokens' validator for per-field checks
+ * (colour/length/font/shadow, logo, fontFaces) and reports each failure with
+ * the same error pattern as the rest of validateConfig. In strict mode, unknown
+ * theme keys are rejected; otherwise they are ignored (the renderer strips them).
+ */
+function validateTheme(theme, strict) {
+    if (typeof theme !== "object" || Array.isArray(theme)) {
+        throw new CorasValidationError("invalid_theme", "config.theme must be an object.", "config.theme");
+    }
+    if (strict) {
+        rejectUnknownKeys(theme, THEME_KEYS, "config.theme");
+        if (theme.dark != null) {
+            rejectUnknownKeys(theme.dark, THEME_KEYS, "config.theme.dark");
+        }
+    }
+    const errors = validateBrandConfig(theme);
+    for (const [key, message] of Object.entries(errors)) {
+        if (message) {
+            throw new CorasValidationError("invalid_theme", `config.theme.${key}: ${message}`, `config.theme.${key}`);
+        }
+    }
+}
+function rejectUnknownKeys(object, allowed, context) {
+    for (const key of Object.keys(object)) {
+        if (!allowed.includes(key)) {
+            throw new CorasValidationError("unknown_key", `Unknown ${context} key "${key}".`, `${context}.${key}`);
+        }
+    }
+}
+export function validateConfig(config, strict) {
+    if (config == null || typeof config !== "object") {
+        throw new CorasValidationError("invalid_config", "config is required and must be an object.", "config");
+    }
+    if (strict) {
+        rejectUnknownKeys(config, CONFIG_KEYS, "config");
+    }
+    if (typeof config.apiUrl !== "string" || config.apiUrl.length === 0) {
+        throw new CorasValidationError("invalid_config", "config.apiUrl is required.", "config.apiUrl");
+    }
+    assertSecureUrl(config.apiUrl, "config.apiUrl");
+    if (typeof config.distributorId !== "string" ||
+        config.distributorId.length === 0) {
+        throw new CorasValidationError("invalid_config", "config.distributorId is required.", "config.distributorId");
+    }
+    const normalized = { ...config };
+    if (config.assetsUrl != null) {
+        validateAssetsUrl(config.assetsUrl);
+    }
+    if (config.theme != null) {
+        validateTheme(config.theme, strict);
+    }
+    if (config.locale != null) {
+        const locale = normalizeLocale(config.locale);
+        if (!locale) {
+            throw new CorasValidationError("invalid_locale", `Unsupported locale "${config.locale}".`, "config.locale");
+        }
+        normalized.locale = locale;
+    }
+    if (config.currency != null) {
+        const currency = normalizeCurrency(config.currency);
+        if (!currency) {
+            throw new CorasValidationError("invalid_currency", `Unsupported currency "${config.currency}".`, "config.currency");
+        }
+        normalized.currency = currency;
+    }
+    if (config.colorScheme != null &&
+        !colorSchemes.has(config.colorScheme)) {
+        throw new CorasValidationError("invalid_color_scheme", `Unsupported colorScheme "${config.colorScheme}". Valid values: light, dark, system, inherit.`, "config.colorScheme");
+    }
+    if (config.allowedLocales != null) {
+        normalized.allowedLocales = config.allowedLocales.map((value) => {
+            const locale = normalizeLocale(value);
+            if (!locale) {
+                throw new CorasValidationError("invalid_locale", `Unsupported locale "${value}" in config.allowedLocales.`, "config.allowedLocales");
+            }
+            return locale;
+        });
+    }
+    if (config.allowedCurrencies != null) {
+        normalized.allowedCurrencies = config.allowedCurrencies.map((value) => {
+            const currency = normalizeCurrency(value);
+            if (!currency) {
+                throw new CorasValidationError("invalid_currency", `Unsupported currency "${value}" in config.allowedCurrencies.`, "config.allowedCurrencies");
+            }
+            return currency;
+        });
+    }
+    return normalized;
+}
+export function validatePageParams(page, params, strict) {
+    if (params == null)
+        return {};
+    if (typeof params !== "object") {
+        throw new CorasValidationError("invalid_page_params", `params for page "${page}" must be an object.`, "params");
+    }
+    const allowed = PAGE_PARAM_KEYS[page];
+    if (strict) {
+        rejectUnknownKeys(params, allowed, "params");
+    }
+    // `details.id` is the public id and must be a non-empty string when present.
+    if (page === "details" && "id" in params) {
+        const id = params.id;
+        if (id != null && (typeof id !== "string" || id.length === 0)) {
+            throw new CorasValidationError("invalid_page_params", "params.id must be a non-empty string.", "params.id");
+        }
+    }
+    // `payment.metadata` is a free-form bag of client data; its keys are
+    // arbitrary, but every value must be a string so it can be serialized for
+    // the API forward.
+    if (page === "payment" && "metadata" in params) {
+        const metadata = params.metadata;
+        if (metadata != null) {
+            const isPlainObject = typeof metadata === "object" && !Array.isArray(metadata);
+            if (!isPlainObject ||
+                !Object.values(metadata).every((value) => typeof value === "string")) {
+                throw new CorasValidationError("invalid_page_params", "params.metadata must be an object of string values.", "params.metadata");
+            }
+        }
+    }
+    if (page === "suggestion-widget" && "limit" in params) {
+        const limit = params.limit;
+        if (limit != null && (typeof limit !== "number" || limit <= 0)) {
+            throw new CorasValidationError("invalid_page_params", "params.limit must be a positive number.", "params.limit");
+        }
+    }
+    return params;
+}
+/**
+ * Validate and normalize the full mount options before anything is rendered.
+ */
+export function validateMountOptions(options) {
+    if (!(options.container instanceof Element)) {
+        throw new CorasValidationError("missing_container", "container must be a DOM Element.", "container");
+    }
+    assertValidPage(options.page);
+    const strict = options.strict === true;
+    const config = validateConfig(options.config, strict);
+    const params = validatePageParams(options.page, options.params, strict);
+    return { page: options.page, config, params };
+}

package/dist/styles/contrast-fixtures.d.ts

@@ -0,0 +1,10 @@
+import type { ContrastPair } from "./contrast.js";
+/**
+ * Default-theme contrast pairs validated in CI (plan F-004, P-058; pairs from
+ * Appendix J). `tokens` lists the CSS variables each colour resolves from so a
+ * stale check can confirm they still exist in the generated token sheet.
+ */
+export type DefaultContrastPair = ContrastPair & {
+    tokens: [string, string];
+};
+export declare const DEFAULT_CONTRAST_PAIRS: DefaultContrastPair[];

package/dist/styles/contrast-fixtures.js

@@ -0,0 +1,61 @@
+export const DEFAULT_CONTRAST_PAIRS = [
+    {
+        label: "Primary button text on primary button background",
+        foreground: "#ffffff",
+        background: "#4657d4",
+        threshold: "AA-normal",
+        tokens: [
+            "--coras-button-primary-text-color",
+            "--coras-button-primary-background",
+        ],
+    },
+    {
+        label: "Body text on page background",
+        foreground: "#000000",
+        background: "#ffffff",
+        threshold: "AA-normal",
+        tokens: ["--coras-color-text", "--coras-color-background"],
+    },
+    {
+        label: "Secondary text on page background",
+        foreground: "#666666",
+        background: "#ffffff",
+        threshold: "AA-normal",
+        tokens: ["--coras-color-text-secondary", "--coras-color-background"],
+    },
+    {
+        label: "Heading/secondary brand text on background",
+        foreground: "#161c44",
+        background: "#ffffff",
+        threshold: "AA-normal",
+        tokens: ["--coras-brand-secondary", "--coras-color-background"],
+    },
+    {
+        label: "Muted/placeholder text on surface",
+        foreground: "#888888",
+        background: "#fcfcff",
+        threshold: "AA-large",
+        tokens: ["--coras-color-text-muted", "--coras-color-surface"],
+    },
+    {
+        label: "Error alert text on error alert background",
+        foreground: "#c9224a",
+        background: "#fae9ed",
+        threshold: "AA-normal",
+        tokens: ["--coras-color-error", "--coras-color-error-surface"],
+    },
+    {
+        label: "Focus ring on background",
+        foreground: "#4657d4",
+        background: "#ffffff",
+        threshold: "AA-large",
+        tokens: ["--coras-color-focus-ring", "--coras-color-background"],
+    },
+    {
+        label: "Navbar text on navbar background",
+        foreground: "#000000",
+        background: "#ffffff",
+        threshold: "AA-normal",
+        tokens: ["--coras-navbar-text-color", "--coras-navbar-background"],
+    },
+];

package/dist/styles/contrast.d.ts

@@ -0,0 +1,19 @@
+export type WcagThreshold = "AA-normal" | "AA-large" | "AAA-normal";
+/** Parse `#rgb` / `#rrggbb` into `[r, g, b]` (0–255). */
+export declare function parseHex(hex: string): [number, number, number];
+/** Relative luminance per WCAG (`0.2126R + 0.7152G + 0.0722B`, linearized). */
+export declare function relativeLuminance(color: string): number;
+/** Contrast ratio (1–21) between two colours. Order-independent. */
+export declare function contrastRatio(a: string, b: string): number;
+export declare function meetsContrast(foreground: string, background: string, threshold?: WcagThreshold): boolean;
+export type ContrastPair = {
+    label: string;
+    foreground: string;
+    background: string;
+    threshold: WcagThreshold;
+};
+export type ContrastResult = ContrastPair & {
+    ratio: number;
+    passes: boolean;
+};
+export declare function evaluateContrast(pairs: ContrastPair[]): ContrastResult[];

package/dist/styles/contrast.js

@@ -0,0 +1,100 @@
+// WCAG contrast utilities (plan F-004, P-058). Pure functions reused by the
+// default-theme CI check and Coras Studio's live contrast panel (exposed via
+// the `@coras-io/embed/contrast` entry).
+const MIN_RATIO = {
+    // AA normal text and AA UI/large both per WCAG 1.4.3 / 1.4.11.
+    "AA-normal": 4.5,
+    "AA-large": 3,
+    "AAA-normal": 7,
+};
+function channelToLinear(channel) {
+    const c = channel / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+/** Parse `#rgb` / `#rrggbb` into `[r, g, b]` (0–255). */
+export function parseHex(hex) {
+    const value = hex.trim().replace(/^#/, "");
+    const full = value.length === 3
+        ? value
+            .split("")
+            .map((c) => c + c)
+            .join("")
+        : value;
+    if (!/^[0-9a-fA-F]{6}$/.test(full)) {
+        throw new Error(`Cannot parse colour "${hex}"`);
+    }
+    return [
+        parseInt(full.slice(0, 2), 16),
+        parseInt(full.slice(2, 4), 16),
+        parseInt(full.slice(4, 6), 16),
+    ];
+}
+// A lazily-created 1x1 canvas context, used to rasterize any CSS colour
+// (`oklch()`, `rgb()`, `hsl()`, named) to sRGB bytes. `null` when there is no
+// DOM (the Node CI check only ever feeds hex, so it never needs this).
+let colorContext;
+function canvasContext() {
+    if (colorContext !== undefined)
+        return colorContext;
+    const doc = globalThis.document;
+    const canvas = doc?.createElement("canvas");
+    const ctx = canvas?.getContext("2d", { willReadFrequently: true }) ?? null;
+    if (canvas)
+        canvas.width = canvas.height = 1;
+    colorContext = ctx;
+    return ctx;
+}
+/** Rasterize any valid CSS colour to sRGB `[r, g, b]`; null if unsupported. */
+function rasterize(color) {
+    const ctx = canvasContext();
+    if (!ctx)
+        return null;
+    // An invalid value leaves `fillStyle` unchanged, so probe from two bases:
+    // if the result differs, the colour was rejected (e.g. an unresolved `var()`).
+    ctx.fillStyle = "#000000";
+    ctx.fillStyle = color;
+    const fromBlack = ctx.fillStyle;
+    ctx.fillStyle = "#ffffff";
+    ctx.fillStyle = color;
+    if (ctx.fillStyle !== fromBlack)
+        return null;
+    ctx.clearRect(0, 0, 1, 1);
+    ctx.fillRect(0, 0, 1, 1);
+    const data = ctx.getImageData(0, 0, 1, 1).data;
+    return [data[0], data[1], data[2]];
+}
+/** Parse a colour to sRGB `[r, g, b]`: hex directly, else via the canvas. */
+function toRgb(color) {
+    try {
+        return parseHex(color);
+    }
+    catch {
+        const rgb = rasterize(color);
+        if (!rgb)
+            throw new Error(`Cannot parse colour "${color}"`);
+        return rgb;
+    }
+}
+/** Relative luminance per WCAG (`0.2126R + 0.7152G + 0.0722B`, linearized). */
+export function relativeLuminance(color) {
+    const [r, g, b] = toRgb(color);
+    return (0.2126 * channelToLinear(r) +
+        0.7152 * channelToLinear(g) +
+        0.0722 * channelToLinear(b));
+}
+/** Contrast ratio (1–21) between two colours. Order-independent. */
+export function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    const [hi, lo] = la >= lb ? [la, lb] : [lb, la];
+    return (hi + 0.05) / (lo + 0.05);
+}
+export function meetsContrast(foreground, background, threshold = "AA-normal") {
+    return contrastRatio(foreground, background) >= MIN_RATIO[threshold];
+}
+export function evaluateContrast(pairs) {
+    return pairs.map((pair) => {
+        const ratio = contrastRatio(pair.foreground, pair.background);
+        return { ...pair, ratio, passes: ratio >= MIN_RATIO[pair.threshold] };
+    });
+}

package/dist/styles/defaults/component.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("lit").CSSResult;
+export default _default;

package/dist/styles/defaults/component.js

@@ -0,0 +1,31 @@
+import { css } from "lit";
+import { focusRing } from "../primitives.js";
+export default css `
+  ${focusRing}
+
+  :host {
+    box-sizing: border-box;
+    font-family: var(--coras-font-family-sans);
+    font-size: var(--coras-font-size-base);
+    line-height: 1.5;
+    color: var(--coras-color-text);
+  }
+
+  :host *,
+  :host *::before,
+  :host *::after {
+    box-sizing: inherit;
+  }
+
+  [hidden] {
+    display: none !important;
+  }
+
+  :host a,
+  :host a:hover,
+  :host a:active {
+    text-decoration: none;
+    font-weight: 600;
+    color: var(--coras-color-primary-500);
+  }
+`;

package/dist/styles/primitives.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared CSS primitives (plan F-004, P-063). Components compose these instead
+ * of re-authoring focus rings, screen-reader helpers, or skeleton shimmer, so
+ * accessibility and branding stay consistent. All values resolve from the
+ * semantic token tier.
+ */
+/** Visible focus ring using the brand focus token. */
+export declare const focusRing: import("lit").CSSResult;
+/** Accessible "visually hidden" helper that remains in the accessibility tree. */
+export declare const visuallyHidden: import("lit").CSSResult;
+/** Loading skeleton shimmer; respects reduced-motion. */
+export declare const skeleton: import("lit").CSSResult;
+/** Reset for native controls used as branded buttons/fields. */
+export declare const controlReset: import("lit").CSSResult;

package/dist/styles/primitives.js

@@ -0,0 +1,68 @@
+import { css } from "lit";
+/**
+ * Shared CSS primitives (plan F-004, P-063). Components compose these instead
+ * of re-authoring focus rings, screen-reader helpers, or skeleton shimmer, so
+ * accessibility and branding stay consistent. All values resolve from the
+ * semantic token tier.
+ */
+/** Visible focus ring using the brand focus token. */
+export const focusRing = css `
+  :where(:focus-visible) {
+    outline: 2px solid var(--coras-color-focus-ring);
+    outline-offset: 2px;
+  }
+`;
+/** Accessible "visually hidden" helper that remains in the accessibility tree. */
+export const visuallyHidden = css `
+  .coras-sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+`;
+/** Loading skeleton shimmer; respects reduced-motion. */
+export const skeleton = css `
+  .coras-skeleton {
+    background: linear-gradient(
+      90deg,
+      var(--coras-color-surface-sunken) 25%,
+      var(--coras-palette-neutral-100) 37%,
+      var(--coras-color-surface-sunken) 63%
+    );
+    background-size: 400% 100%;
+    border-radius: var(--coras-radius-sm);
+    animation: coras-skeleton-shimmer 1.4s ease infinite;
+  }
+
+  @keyframes coras-skeleton-shimmer {
+    0% {
+      background-position: 100% 50%;
+    }
+    100% {
+      background-position: 0 50%;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .coras-skeleton {
+      animation: none;
+    }
+  }
+`;
+/** Reset for native controls used as branded buttons/fields. */
+export const controlReset = css `
+  .coras-control-reset {
+    appearance: none;
+    margin: 0;
+    font: inherit;
+    color: inherit;
+    background: none;
+    border: none;
+  }
+`;