@ticketlayer/elements-core 0.1.0

package/dist/esm/define.js

@@ -0,0 +1,177 @@
+const CATEGORIES = [
+    'discovery',
+    'purchase',
+    'cart',
+    'checkout',
+    'account',
+    'tickets',
+];
+const RUNTIMES = ['web', 'native'];
+/**
+ * Declare a core. The checks here are the ones a type cannot make: a tag that
+ * is not a `tl-` custom element name, a category or runtime outside the set the
+ * catalogue knows, a duplicated token, a status list that does not include what
+ * `status` can return. They run at import time, so a malformed core fails the
+ * build rather than a browser.
+ */
+export function defineElement(core) {
+    const fail = (message) => {
+        throw new Error(`[elements-core] ${core.tag || '<no tag>'}: ${message}`);
+    };
+    if (!/^tl-[a-z0-9]+(-[a-z0-9]+)*$/.test(core.tag))
+        fail('tag must look like tl-something');
+    if (!CATEGORIES.includes(core.category))
+        fail(`category must be one of ${CATEGORIES.join(', ')}`);
+    if (!core.runtimes.length || core.runtimes.some((r) => !RUNTIMES.includes(r))) {
+        fail(`runtimes must be a non-empty subset of ${RUNTIMES.join(', ')}`);
+    }
+    if (new Set(core.tokens).size !== core.tokens.length)
+        fail('tokens must not repeat');
+    if (!core.statuses.length)
+        fail('statuses must not be empty');
+    for (const [name, spec] of Object.entries(core.events)) {
+        if (!/^tl[A-Z]/.test(name))
+            fail(`event ${name} must be named tlSomething`);
+        if (!spec.detail)
+            fail(`event ${name} must state its detail type`);
+    }
+    for (const [name, spec] of Object.entries(core.props)) {
+        if (spec.required && spec.default !== undefined)
+            fail(`prop ${name} is required and has a default`);
+    }
+    return Object.freeze({ ...core });
+}
+const DEFAULT_LOCALE = 'en-GB';
+const DEFAULT_CURRENCY = 'GBP';
+/**
+ * Instantiate a core. The instance owns the state and the timers; the harness
+ * owns the pixels. `subscribe` fires after every change with the whole view, so
+ * a harness only has to assign it to whatever makes its runtime re-render.
+ */
+export function createElement(core, options = {}) {
+    const defaults = {};
+    for (const [name, spec] of Object.entries(core.props)) {
+        if (spec.default !== undefined)
+            defaults[name] = spec.default;
+    }
+    let props = { ...defaults, ...(options.props ?? {}) };
+    const strings = { ...core.strings, ...(options.strings ?? {}) };
+    const locale = options.locale ?? DEFAULT_LOCALE;
+    const fallbackCurrency = options.currency ?? DEFAULT_CURRENCY;
+    let resolveClient = toResolver(options.client);
+    let state = core.state(props);
+    let destroyed = false;
+    const timers = new Set();
+    const listeners = new Set();
+    const formatMoney = (amountInMinorUnits, currency) => new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency: currency || fallbackCurrency,
+    }).format(amountInMinorUnits / 100);
+    const viewContext = () => ({ props, state, strings, formatMoney });
+    const buildView = () => {
+        const ctx = viewContext();
+        return {
+            status: core.status(ctx),
+            props,
+            state,
+            strings,
+            derived: core.derive(ctx),
+        };
+    };
+    const notify = () => {
+        if (destroyed)
+            return;
+        const view = buildView();
+        for (const listener of [...listeners])
+            listener(view);
+    };
+    const actionContext = {
+        get props() {
+            return props;
+        },
+        get state() {
+            return state;
+        },
+        strings,
+        formatMoney,
+        setState(patch) {
+            if (destroyed)
+                return;
+            const next = typeof patch === 'function' ? patch(state) : patch;
+            state = { ...state, ...next };
+            notify();
+        },
+        emit(event, detail) {
+            if (!core.events[event]) {
+                throw new Error(`[elements-core] ${core.tag}: ${event} is not a declared event`);
+            }
+            options.emit?.(event, detail);
+        },
+        client() {
+            const client = resolveClient();
+            if (!client) {
+                throw new Error(`[elements-core] ${core.tag}: no client. A harness hands the core the client the host published.`);
+            }
+            return client;
+        },
+        optionalClient() {
+            try {
+                return resolveClient();
+            }
+            catch {
+                return null;
+            }
+        },
+        after(ms, run) {
+            if (destroyed)
+                return;
+            const handle = setTimeout(() => {
+                timers.delete(handle);
+                if (!destroyed)
+                    run();
+            }, ms);
+            timers.add(handle);
+        },
+    };
+    const actions = core.actions(actionContext);
+    return {
+        core,
+        get props() {
+            return props;
+        },
+        get state() {
+            return state;
+        },
+        get view() {
+            return buildView();
+        },
+        actions,
+        setProps(next) {
+            if (destroyed)
+                return;
+            props = { ...props, ...next };
+            notify();
+        },
+        setClient(client) {
+            resolveClient = toResolver(client);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        destroy() {
+            destroyed = true;
+            for (const handle of timers)
+                clearTimeout(handle);
+            timers.clear();
+            listeners.clear();
+        },
+    };
+}
+function toResolver(client) {
+    if (typeof client === 'function')
+        return client;
+    return () => client ?? null;
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@ticketlayer/elements-core`: the headless cores the Ticketlayer Elements
+ * render.
+ *
+ * One core per element, in `src/cores/`. A core is plain TypeScript: state,
+ * actions, derived values, a status, its copy, the theme tokens its harnesses
+ * use and the `tl*` events it emits, with no DOM, no React and no client of its
+ * own. The harnesses are thin: `packages/elements` renders a core with Stencil
+ * on the web, and a React Native harness will render the same core in an app
+ * (platform plan section 2.7, AGENTS.md, TKT-11).
+ *
+ * `elements.catalogue.json` is emitted from the manifests these cores carry, so
+ * what the docs site and a native host read is a projection of the object that
+ * runs, not a second copy kept by hand.
+ */
+export { createElement, defineElement } from './define.js';
+export type { ActionContext, ActionMap, CreateElementOptions, ElementCategory, ElementCore, ElementDefinition, ElementInstance, ElementView, EventSpec, PropSpec, PropSpecs, PropType, Runtime, StringMap, ViewContext, } from './define.js';
+export { manifestOf } from './manifest.js';
+export type { AnyElementCore, ElementManifest, ManifestEvent, ManifestProp } from './manifest.js';
+export type { ElementCartManager, ElementClient, ElementEventsManager } from './client.js';
+export { cartTotals, expressesFee, minorUnits, selectionTotals, FEE_LABEL_FALLBACK, } from './money.js';
+export type { TlCartLike, TlFeeQuote, TlSelectionLine, TlSelectionTotals, TlTotals, } from './money.js';
+export * from './cores/index.js';

package/dist/esm/index.js

@@ -0,0 +1,19 @@
+/**
+ * `@ticketlayer/elements-core`: the headless cores the Ticketlayer Elements
+ * render.
+ *
+ * One core per element, in `src/cores/`. A core is plain TypeScript: state,
+ * actions, derived values, a status, its copy, the theme tokens its harnesses
+ * use and the `tl*` events it emits, with no DOM, no React and no client of its
+ * own. The harnesses are thin: `packages/elements` renders a core with Stencil
+ * on the web, and a React Native harness will render the same core in an app
+ * (platform plan section 2.7, AGENTS.md, TKT-11).
+ *
+ * `elements.catalogue.json` is emitted from the manifests these cores carry, so
+ * what the docs site and a native host read is a projection of the object that
+ * runs, not a second copy kept by hand.
+ */
+export { createElement, defineElement } from './define.js';
+export { manifestOf } from './manifest.js';
+export { cartTotals, expressesFee, minorUnits, selectionTotals, FEE_LABEL_FALLBACK, } from './money.js';
+export * from './cores/index.js';

package/dist/esm/manifest.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The manifest: the declarative half of a core, as JSON.
+ *
+ * `elements.catalogue.json` is emitted from these (TKT-11), so the facts the
+ * docs site, the CLI and a native host read are a projection of the object the
+ * element actually runs on. There is no second copy to forget:
+ * `packages/elements/src/catalogue.manifest.json` is the hand-kept file this
+ * replaces, one element at a time, and the emitter refuses a tag that appears
+ * in both.
+ *
+ * Only what can be serialised is here. The behaviour (`state`, `status`,
+ * `derive`, `actions`) is code, and all the manifest can say about it is the
+ * set of statuses a harness must render and the names of the actions it can
+ * call.
+ */
+import type { ElementCategory, ElementCore, Runtime } from './define.js';
+export interface ManifestProp {
+    name: string;
+    attr: string | null;
+    type: string;
+    default: unknown;
+    required: boolean;
+    docs: string;
+}
+export interface ManifestEvent {
+    name: string;
+    detail: string;
+    docs: string;
+}
+export interface ElementManifest {
+    tag: string;
+    docs: string;
+    category: ElementCategory;
+    runtimes: Runtime[];
+    /** Canonical `@ticketlayer/theme` token names, sorted. */
+    tokens: string[];
+    /** Client methods the core calls, as `manager.method`, sorted. */
+    sdkMethods: string[];
+    props: ManifestProp[];
+    events: ManifestEvent[];
+    strings: Record<string, string>;
+    statuses: string[];
+    actions: string[];
+}
+/**
+ * A core with its type parameters forgotten, which is all a registry or the
+ * catalogue emitter needs. `any` and not `unknown`: `status`, `derive` and
+ * `actions` take their context as a parameter, so a narrower type here would
+ * make every real core fail to fit.
+ */
+export type AnyElementCore = ElementCore<any, any, any, any, string, any>;
+/** Project a core onto its manifest. Sorted, so the catalogue diff is stable. */
+export declare function manifestOf(core: AnyElementCore): ElementManifest;

package/dist/esm/manifest.js

@@ -0,0 +1,51 @@
+/** Project a core onto its manifest. Sorted, so the catalogue diff is stable. */
+export function manifestOf(core) {
+    const props = Object.entries(core.props)
+        .map(([name, spec]) => ({
+        name,
+        attr: spec.attr,
+        type: spec.type,
+        default: spec.default ?? null,
+        required: !!spec.required,
+        docs: spec.docs,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const events = Object.entries(core.events)
+        .map(([name, spec]) => ({ name, detail: spec.detail, docs: spec.docs }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        tag: core.tag,
+        docs: core.docs,
+        category: core.category,
+        runtimes: [...core.runtimes],
+        tokens: [...core.tokens].sort(),
+        sdkMethods: [...core.sdkMethods].sort(),
+        props,
+        events,
+        strings: { ...core.strings },
+        statuses: [...core.statuses],
+        actions: Object.keys(dryRunActions(core)).sort(),
+    };
+}
+/**
+ * The action names, without running anything. `actions` is a factory, so the
+ * only way to learn the names is to build it once against a context whose
+ * every member throws: a core that called the client or set state while
+ * declaring its actions would fail here, loudly, which is the intent.
+ */
+function dryRunActions(core) {
+    const refuse = (what) => () => {
+        throw new Error(`[elements-core] ${core.tag}: ${what} cannot run while the actions are declared`);
+    };
+    return core.actions({
+        props: {},
+        state: {},
+        strings: core.strings,
+        formatMoney: refuse('formatMoney'),
+        setState: refuse('setState'),
+        emit: refuse('emit'),
+        client: refuse('client'),
+        optionalClient: refuse('optionalClient'),
+        after: refuse('after'),
+    });
+}

package/dist/esm/money.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The money rows a cart-shaped view renders: subtotal, the booking fee, a
+ * discount and the total.
+ *
+ * Pure: no Stencil, no DOM, no SDK. A core derives these figures and a harness
+ * renders what it returns, so the rule for what is shown can be unit tested on
+ * its own (the platform plan's headless-core split, AGENTS.md). It lived in
+ * `packages/elements/src/utils/cart-totals.ts` until the core split (TKT-68)
+ * and is re-exported from there, so every existing import still resolves.
+ *
+ * The client (`@ticketlayer/live`) already derives these figures from the
+ * sales-surface response and publishes `subtotal`, `fees`, `discount`,
+ * `total`, `hasFees` and `feeLabel` on the cart it hands us. Cores never
+ * import the client, so the same rule is stated here for the case where a
+ * host binds an older connector, or a bare sales cart: read what is there,
+ * and never invent money that is not.
+ *
+ * Money is integer minor units (2500 = 25.00) everywhere on this platform.
+ * Nothing here divides or multiplies money; the only division is the one
+ * `formatPrice` does to render it.
+ */
+/** Shown when the response names no fee of its own. */
+export declare const FEE_LABEL_FALLBACK = "Booking fee";
+export interface TlCartLike {
+    currency?: string | null;
+    items?: Array<{
+        type?: string;
+        name?: string;
+        quantity?: number;
+        subtotal?: number | string;
+    }>;
+    itemsSubtotal?: number | string;
+    subtotal?: number | string;
+    fees?: number | string;
+    totalFees?: number | string;
+    discount?: number | string;
+    totalDiscounts?: number | string;
+    totalTax?: number | string;
+    total?: number | string;
+    hasFees?: boolean;
+    feeLabel?: string | null;
+}
+export interface TlTotals {
+    currency: string;
+    /** Ticket lines, in minor units. */
+    subtotal: number;
+    /** The fee, in minor units. 0 when the response reports none. */
+    fees: number;
+    /** Discount as a positive magnitude, in minor units. */
+    discount: number;
+    /** What the buyer pays: the server's figure whenever the response has one. */
+    total: number;
+    /** Whether to render the fee row. See {@link expressesFee}. */
+    showFee: boolean;
+    /** The fee profile's label as the response gives it, or the fallback. */
+    feeLabel: string;
+}
+/**
+ * Minor units, or null when the value is not minor units. Integers and
+ * all-digit strings only: a decimal is not minor units, and treating it as
+ * money here would put floating point into a total.
+ */
+export declare function minorUnits(value: unknown): number | null;
+/**
+ * THE RULE: a fee of zero is not the same as no fee.
+ *
+ * Render the fee row when the response EXPRESSES a fee - an amount above
+ * zero, or a fee the surface has NAMED (a `type: 'fee'` line or a fee label)
+ * even where it computes to zero. A response with no fee figure at all, or a
+ * bare zero nothing names, expresses no fee: a channel with no fee profile
+ * renders no row, and we never show a "Booking fee 0.00" the surface did not
+ * put there.
+ */
+export declare function expressesFee(fees: number | null, named: boolean): boolean;
+export declare function cartTotals(cart: TlCartLike | null | undefined): TlTotals;
+export interface TlSelectionLine {
+    price?: number;
+    quantity?: number;
+}
+/** A fee the surface has quoted for a selection, when it ever quotes one. */
+export interface TlFeeQuote {
+    amount: number;
+    label?: string | null;
+}
+export interface TlSelectionTotals {
+    subtotal: number;
+    fees: number;
+    total: number;
+    showFee: boolean;
+    feeLabel: string;
+}
+/**
+ * The totals for a selection that is not yet a cart (tl-ticket-selector).
+ *
+ * The buyer-facing surface quotes no fee before the cart exists - there is no
+ * quote or preview operation, and the channel's fee profile is not exposed to
+ * a publishable key - so `quote` is null on every call today and no fee row is
+ * rendered. It is a parameter rather than an assumption so that the row lights
+ * up from data the moment the surface quotes one, and so the rule stays
+ * testable now.
+ */
+export declare function selectionTotals(lines: TlSelectionLine[], quote?: TlFeeQuote | null): TlSelectionTotals;

package/dist/esm/money.js

@@ -0,0 +1,110 @@
+/**
+ * The money rows a cart-shaped view renders: subtotal, the booking fee, a
+ * discount and the total.
+ *
+ * Pure: no Stencil, no DOM, no SDK. A core derives these figures and a harness
+ * renders what it returns, so the rule for what is shown can be unit tested on
+ * its own (the platform plan's headless-core split, AGENTS.md). It lived in
+ * `packages/elements/src/utils/cart-totals.ts` until the core split (TKT-68)
+ * and is re-exported from there, so every existing import still resolves.
+ *
+ * The client (`@ticketlayer/live`) already derives these figures from the
+ * sales-surface response and publishes `subtotal`, `fees`, `discount`,
+ * `total`, `hasFees` and `feeLabel` on the cart it hands us. Cores never
+ * import the client, so the same rule is stated here for the case where a
+ * host binds an older connector, or a bare sales cart: read what is there,
+ * and never invent money that is not.
+ *
+ * Money is integer minor units (2500 = 25.00) everywhere on this platform.
+ * Nothing here divides or multiplies money; the only division is the one
+ * `formatPrice` does to render it.
+ */
+/** Shown when the response names no fee of its own. */
+export const FEE_LABEL_FALLBACK = 'Booking fee';
+/**
+ * Minor units, or null when the value is not minor units. Integers and
+ * all-digit strings only: a decimal is not minor units, and treating it as
+ * money here would put floating point into a total.
+ */
+export function minorUnits(value) {
+    if (typeof value === 'number')
+        return Number.isInteger(value) ? value : null;
+    if (typeof value === 'string' && /^-?\d+$/.test(value))
+        return Number(value);
+    return null;
+}
+/**
+ * THE RULE: a fee of zero is not the same as no fee.
+ *
+ * Render the fee row when the response EXPRESSES a fee - an amount above
+ * zero, or a fee the surface has NAMED (a `type: 'fee'` line or a fee label)
+ * even where it computes to zero. A response with no fee figure at all, or a
+ * bare zero nothing names, expresses no fee: a channel with no fee profile
+ * renders no row, and we never show a "Booking fee 0.00" the surface did not
+ * put there.
+ */
+export function expressesFee(fees, named) {
+    if (fees === null)
+        return named;
+    return fees > 0 || named;
+}
+const lineType = (line) => line.type || 'ticket';
+export function cartTotals(cart) {
+    const c = cart || {};
+    const lines = Array.isArray(c.items) ? c.items : [];
+    const feeLines = lines.filter((l) => lineType(l) === 'fee');
+    const discountLines = lines.filter((l) => lineType(l) === 'discount');
+    const subtotal = minorUnits(c.itemsSubtotal) ??
+        minorUnits(c.subtotal) ??
+        lines
+            .filter((l) => !['fee', 'tax', 'discount'].includes(lineType(l)))
+            .reduce((sum, l) => sum + (minorUnits(l.subtotal) ?? 0), 0);
+    const feeFromLines = feeLines.length
+        ? feeLines.reduce((sum, l) => sum + (minorUnits(l.subtotal) ?? 0), 0)
+        : null;
+    const fees = minorUnits(c.totalFees) ?? minorUnits(c.fees) ?? feeFromLines;
+    const discountFromLines = discountLines.length
+        ? discountLines.reduce((sum, l) => sum + Math.abs(minorUnits(l.subtotal) ?? 0), 0)
+        : null;
+    const discount = minorUnits(c.totalDiscounts) ?? minorUnits(c.discount) ?? discountFromLines;
+    const tax = minorUnits(c.totalTax) ?? 0;
+    const named = (typeof c.feeLabel === 'string' && !!c.feeLabel) ||
+        feeLines.some((l) => typeof l.name === 'string' && !!l.name);
+    const label = (typeof c.feeLabel === 'string' && c.feeLabel) ||
+        feeLines.map((l) => l.name).find((n) => typeof n === 'string' && !!n) ||
+        FEE_LABEL_FALLBACK;
+    return {
+        currency: c.currency || 'GBP',
+        subtotal,
+        fees: fees ?? 0,
+        discount: discount ?? 0,
+        // The server's total is what the buyer is charged, so it wins over any sum
+        // we could do here. We only add up when the response carries no total.
+        total: minorUnits(c.total) ?? subtotal + (fees ?? 0) + tax - (discount ?? 0),
+        // The client already applied the rule; honour its answer when it sent one.
+        showFee: typeof c.hasFees === 'boolean' ? c.hasFees : expressesFee(fees, named),
+        feeLabel: label,
+    };
+}
+/**
+ * The totals for a selection that is not yet a cart (tl-ticket-selector).
+ *
+ * The buyer-facing surface quotes no fee before the cart exists - there is no
+ * quote or preview operation, and the channel's fee profile is not exposed to
+ * a publishable key - so `quote` is null on every call today and no fee row is
+ * rendered. It is a parameter rather than an assumption so that the row lights
+ * up from data the moment the surface quotes one, and so the rule stays
+ * testable now.
+ */
+export function selectionTotals(lines, quote = null) {
+    const subtotal = (lines || []).reduce((sum, l) => sum + (minorUnits(l.price) ?? 0) * (Math.max(0, Math.trunc(l.quantity || 0)) || 0), 0);
+    const fees = quote ? minorUnits(quote.amount) : null;
+    const named = !!quote?.label;
+    return {
+        subtotal,
+        fees: fees ?? 0,
+        total: subtotal + (fees ?? 0),
+        showFee: quote ? expressesFee(fees, named) : false,
+        feeLabel: quote?.label || FEE_LABEL_FALLBACK,
+    };
+}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@ticketlayer/elements-core",
+  "version": "0.1.0",
+  "description": "The headless cores the Ticketlayer Elements render: state, actions, derived values, status, strings, tokens and events, with no runtime in them",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ticketlayer/live.git",
+    "directory": "packages/elements-core"
+  },
+  "homepage": "https://docs.ticketlayer.com/elements",
+  "bugs": {
+    "url": "https://github.com/ticketlayer/live/issues"
+  },
+  "keywords": [
+    "ticketlayer",
+    "elements",
+    "headless",
+    "ticketing"
+  ],
+  "author": "Ticketlayer",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@ticketlayer/theme": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "clean": "rm -rf dist",
+    "pretest": "pnpm run build",
+    "test": "node --test test/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}