@ticketlayer/elements-core 0.1.0 → 0.2.0

package/dist/esm/cores/buy-tickets-button.js

@@ -0,0 +1,210 @@
+/**
+ * `tl-buy-tickets-button`: the pre-styled button that opens the purchase
+ * modal for one event.
+ *
+ * The sibling of `tl-buy-tickets-wrapper`. The wrapper turns whatever the host
+ * already has into the thing that opens the modal; this one IS the thing, so
+ * on top of the wrapper's single action it carries the four sale states a
+ * seller puts a button in, the label each one defaults to, and the price the
+ * button may show beside it.
+ *
+ * Until now it could not be split for a different reason from the wrapper's.
+ * Its four states painted themselves from literal hex in the component, and a
+ * core may hold no value at all, so there was nothing to lift. TKT-203 moved
+ * them onto token families - `available` to primary, `soldOut` to error,
+ * `comingSoon` to warning, `waitlist` to info, each deriving its hover with
+ * `color-mix` - and that is what unblocked this.
+ *
+ * What a core still cannot say, and this one does not try to: WHICH family a
+ * state paints with. `tokens` is a flat list and there is no shape for mapping
+ * one onto a status. So this core does what `tl-event-card`'s status badge
+ * does - it derives the CLASS NAME the state is rendered under
+ * (`derived.stateClass`) and leaves the stylesheet to say which family that
+ * class reaches for. The core names the state; the harness names the paint.
+ *
+ * Behaviour is what the Stencil component did, to the letter:
+ *
+ *  - `disabled`, `soldOut` and `comingSoon` are not pressable, and a press on
+ *    one of them does nothing whatever: no event, no modal.
+ *  - a press announces `tlClick` FIRST and opens the modal after, so a host
+ *    hears the intent even on a page that never started Live.
+ *  - with no client, or a connector too old to have the modal verbs, the press
+ *    still announces `tlClick` and then quietly opens nothing. Unlike the
+ *    wrapper this element has no error event to say so with, and inventing one
+ *    would be a new published surface rather than a split.
+ *  - the label is the `label` prop when the host set one, else the state's own.
+ *  - the price is formatted `en-GB`, in the button's currency, with the pence
+ *    shown only when there are any.
+ *
+ * What did not come across is the `console.error` the component wrote when the
+ * modal threw, for the reason `tl-cart` and `tl-promo-code` dropped theirs: a
+ * library should not write to its host's console.
+ *
+ * The other thing a core refuses to know is which key press counts as
+ * activation. `activate()` is the whole input surface; the harness decides what
+ * reaches it - a click and Enter or Space on the web, a press on a phone.
+ */
+import { defineElement } from '../define.js';
+const STRINGS = {
+    available: 'Buy Tickets',
+    soldOut: 'Sold Out',
+    waitlist: 'Join Waitlist',
+    comingSoon: 'On Sale Soon',
+};
+/** Sale state -> the class it renders under. */
+const STATE_CLASSES = {
+    available: 'state-available',
+    soldOut: 'state-sold-out',
+    waitlist: 'state-waitlist',
+    comingSoon: 'state-coming-soon',
+};
+/** The states a press does nothing in, whatever `disabled` says. */
+const NOT_PRESSABLE = ['soldOut', 'comingSoon'];
+const pressable = (props) => !props.disabled && !NOT_PRESSABLE.includes(props.state);
+/**
+ * As the component formatted it: `en-GB`, minor units, and the pence only when
+ * there are any. The locale is written down here rather than taken from
+ * `ctx.formatMoney` because that is what the element did before the split and
+ * this is a split, not a change (see the note on the card core's date).
+ */
+function formatPrice(priceInMinorUnits, currency) {
+    const amount = priceInMinorUnits / 100;
+    const hasDecimals = amount % 1 !== 0;
+    return new Intl.NumberFormat('en-GB', {
+        style: 'currency',
+        currency,
+        minimumFractionDigits: hasDecimals ? 2 : 0,
+        maximumFractionDigits: hasDecimals ? 2 : 0,
+    }).format(amount);
+}
+export const buyTicketsButtonCore = defineElement({
+    tag: 'tl-buy-tickets-button',
+    docs: 'A buy-tickets button in one of four sale states, which opens the purchase modal.',
+    category: 'purchase',
+    runtimes: ['web'],
+    tokens: [
+        'error',
+        'error-foreground',
+        'font-family',
+        'info',
+        'info-foreground',
+        'primary',
+        'primary-foreground',
+        'radius-lg',
+        'radius-md',
+        'radius-sm',
+        'warning',
+        'warning-foreground',
+    ],
+    sdkMethods: ['event.openModal'],
+    props: {
+        eventId: {
+            type: 'string',
+            attr: 'event-id',
+            required: true,
+            docs: 'Event ID to purchase tickets for',
+        },
+        occurrenceId: {
+            type: 'string',
+            tsType: 'string | undefined',
+            attr: 'occurrence-id',
+            docs: 'Optional pre-selected occurrence ID',
+        },
+        state: {
+            type: 'string',
+            tsType: '"available" | "comingSoon" | "soldOut" | "waitlist"',
+            attr: 'state',
+            default: 'available',
+            docs: 'Button state - determines colour, label, and icon',
+        },
+        label: {
+            type: 'string',
+            tsType: 'string | undefined',
+            attr: 'label',
+            docs: 'Button label override (default depends on state)',
+        },
+        variant: {
+            type: 'string',
+            tsType: '"outline" | "primary" | "secondary"',
+            attr: 'variant',
+            default: 'primary',
+            docs: 'Button variant',
+        },
+        size: {
+            type: 'string',
+            tsType: '"lg" | "md" | "sm"',
+            attr: 'size',
+            default: 'md',
+            docs: 'Button size',
+        },
+        fullWidth: {
+            type: 'boolean',
+            attr: 'full-width',
+            default: false,
+            docs: 'Full width button',
+        },
+        price: {
+            type: 'number',
+            tsType: 'number | undefined',
+            attr: 'price',
+            docs: 'Price to display (in minor units e.g. pence)',
+        },
+        currency: {
+            type: 'string',
+            attr: 'currency',
+            default: 'GBP',
+            docs: 'Currency code for price formatting',
+        },
+        pricePrefix: {
+            type: 'string',
+            attr: 'price-prefix',
+            default: 'From',
+            docs: 'Show price prefix text',
+        },
+        disabled: {
+            type: 'boolean',
+            attr: 'disabled',
+            default: false,
+            docs: 'Disabled state',
+        },
+    },
+    events: {
+        tlClick: {
+            detail: '{ eventId: string; occurrenceId?: string | undefined; }',
+            docs: 'Emitted when button is clicked (before modal opens)',
+        },
+    },
+    strings: STRINGS,
+    statuses: ['ready', 'disabled'],
+    state: () => ({}),
+    status: ({ props }) => (pressable(props) ? 'ready' : 'disabled'),
+    derive: ({ props, strings }) => ({
+        interactive: pressable(props),
+        buttonLabel: props.label || strings[props.state],
+        stateClass: STATE_CLASSES[props.state],
+        priceLabel: props.price === undefined ? null : formatPrice(props.price, props.currency),
+    }),
+    actions: (ctx) => ({
+        /** A click, a tap, Enter or Space: whatever the harness calls a press. */
+        activate() {
+            if (!pressable(ctx.props))
+                return;
+            // Announced first, and whatever happens next: a host that tracks buying
+            // intent hears it even on a page that never started Live.
+            ctx.emit('tlClick', { eventId: ctx.props.eventId, occurrenceId: ctx.props.occurrenceId });
+            const client = ctx.optionalClient();
+            // Tolerated rather than assumed, like every other accessor a core reads:
+            // the same core runs against whatever connector version the host has.
+            if (!client || !client.event)
+                return;
+            try {
+                client.event(ctx.props.eventId).openModal({ occurrenceId: ctx.props.occurrenceId });
+            }
+            catch {
+                // The component swallowed this too (it logged and carried on). This
+                // element has no error event to announce it with, and giving it one
+                // would be a new published surface rather than a split.
+            }
+        },
+    }),
+});

package/dist/esm/cores/buy-tickets-wrapper.d.ts

@@ -0,0 +1,27 @@
+export interface BuyTicketsWrapperProps {
+    eventId: string;
+    occurrenceId: string | undefined;
+    disabled: boolean;
+}
+/**
+ * Nothing. The modal belongs to the client and the content belongs to the
+ * host, so there is nothing for this element to remember between clicks.
+ */
+export type BuyTicketsWrapperState = Record<string, never>;
+export interface BuyTicketsWrapperDerived {
+    /** Whether a press should do anything. The harness draws the rest from it. */
+    interactive: boolean;
+}
+export type BuyTicketsWrapperStatus = 'ready' | 'disabled';
+declare const STRINGS: {
+    noClient: string;
+    notAvailable: string;
+};
+export type BuyTicketsWrapperStrings = typeof STRINGS;
+export declare const buyTicketsWrapperCore: import("../define.js").ElementCore<BuyTicketsWrapperProps, BuyTicketsWrapperState, BuyTicketsWrapperDerived, {
+    activate(): void;
+}, BuyTicketsWrapperStatus, {
+    noClient: string;
+    notAvailable: string;
+}>;
+export {};

package/dist/esm/cores/buy-tickets-wrapper.js

@@ -0,0 +1,103 @@
+/**
+ * `tl-buy-tickets-wrapper`: whatever the page already has, turned into the
+ * thing that opens the purchase modal.
+ *
+ * The element renders nothing of its own - the host's own button, link or card
+ * is slotted into it - so this is the smallest core in the package: no state,
+ * one action, and three events that exist only because the modal reports back
+ * to whoever opened it.
+ *
+ * Until now it could not be split at all. Its events were `tl-complete`,
+ * `tl-error` and `tl-close`, and `defineElement` requires `tlSomething`; the
+ * names were renamed to `tlComplete`, `tlError` and `tlClose` (TKT-203), which
+ * is what made this possible. The rename is a breaking change to a published
+ * element and is deliberate.
+ *
+ * Behaviour is what the Stencil component did, to the letter:
+ *
+ *  - a disabled wrapper does nothing at all, and announces nothing.
+ *  - with no client on the page the click announces `tlError` rather than
+ *    throwing, because the host asked for a modal and deserves to hear that it
+ *    did not open.
+ *  - the modal is the client's, not the element's. This core asks for it and
+ *    then only relays what comes back.
+ *
+ * What did not come across is the `console.error` tracing, for the reason
+ * `tl-cart` and `tl-promo-code` dropped theirs: a library should not write to
+ * its host's console when it has an event for saying the same thing.
+ *
+ * What a core still cannot say, and this one does not try to: which key press
+ * counts as activation. `activate()` is the whole input surface, and each
+ * harness decides what reaches it - a click and Enter or Space on the web, a
+ * press on a phone.
+ */
+import { defineElement } from '../define.js';
+const STRINGS = {
+    noClient: 'SDK not initialized',
+    notAvailable: 'Tickets are not available',
+};
+export const buyTicketsWrapperCore = defineElement({
+    tag: 'tl-buy-tickets-wrapper',
+    docs: 'Wrap any content and open the purchase modal when it is activated.',
+    category: 'purchase',
+    runtimes: ['web'],
+    tokens: ['radius-sm', 'ring'],
+    sdkMethods: ['event.openModal'],
+    props: {
+        eventId: {
+            type: 'string',
+            attr: 'event-id',
+            required: true,
+            docs: 'The event ID to purchase tickets for',
+        },
+        occurrenceId: {
+            type: 'string',
+            tsType: 'string | undefined',
+            attr: 'occurrence-id',
+            docs: 'Optional specific occurrence ID (skips occurrence selector)',
+        },
+        disabled: {
+            type: 'boolean',
+            attr: 'disabled',
+            default: false,
+            docs: 'Whether the wrapper is disabled',
+        },
+    },
+    events: {
+        // `OrderResult` because that is the name the web harness writes, and the
+        // catalogue compares the two: it is the connector's name for the shape
+        // `ElementOrderResult` describes here.
+        tlComplete: { detail: 'OrderResult', docs: 'Emitted when purchase completes successfully' },
+        tlError: { detail: '{ message: string; }', docs: 'Emitted when an error occurs' },
+        tlClose: { detail: 'void', docs: 'Emitted when the modal closes' },
+    },
+    strings: STRINGS,
+    statuses: ['ready', 'disabled'],
+    state: () => ({}),
+    status: ({ props }) => (props.disabled ? 'disabled' : 'ready'),
+    derive: ({ props }) => ({ interactive: !props.disabled }),
+    actions: (ctx) => ({
+        /** A click, a tap, Enter or Space: whatever the harness calls a press. */
+        activate() {
+            if (ctx.props.disabled)
+                return;
+            const client = ctx.optionalClient();
+            if (!client) {
+                ctx.emit('tlError', { message: ctx.strings.noClient });
+                return;
+            }
+            // Tolerated rather than assumed, like every other accessor a core reads:
+            // the same core runs against whatever connector version the host has.
+            if (!client.event) {
+                ctx.emit('tlError', { message: ctx.strings.notAvailable });
+                return;
+            }
+            client.event(ctx.props.eventId).openModal({
+                occurrenceId: ctx.props.occurrenceId,
+                onComplete: (order) => ctx.emit('tlComplete', order),
+                onError: (err) => ctx.emit('tlError', { message: err.message }),
+                onClose: () => ctx.emit('tlClose', undefined),
+            });
+        },
+    }),
+});

package/dist/esm/cores/cart-badge.d.ts

@@ -0,0 +1,48 @@
+/** Where the last known count is kept. The key the component used. */
+export declare const CART_COUNT_KEY = "tl_cart_count";
+export interface CartBadgeProps {
+    showEmpty: boolean;
+    icon?: string;
+    size: 'sm' | 'md' | 'lg';
+    badgeOnly: boolean;
+}
+export interface CartBadgeState {
+    itemCount: number;
+}
+export interface CartBadgeDerived {
+    /** The count as it is shown: anything over ninety-nine is "99+". */
+    displayCount: string;
+    /**
+     * Whether the count bubble is rendered.
+     *
+     * `showEmpty` has no effect on it, and deliberately still has none: the
+     * component computed `itemCount > 0 || showEmpty` and then rendered the
+     * bubble only when `showBadge && itemCount > 0`, so the prop has never done
+     * anything. Preserved rather than quietly fixed, because this split is
+     * behaviour-identical; making the prop work is a change a host can see.
+     */
+    showBadge: boolean;
+    /** Badge-only mode with nothing in the cart renders nothing whatsoever. */
+    renderNothing: boolean;
+    ariaLabel: string;
+    sizeClass: string;
+}
+export type CartBadgeStatus = 'ready';
+declare const STRINGS: {
+    /** Read as "Cart with 2 items". The count is appended. */
+    ariaPrefix: string;
+    ariaSuffix: string;
+    overflow: string;
+};
+export type CartBadgeStrings = typeof STRINGS;
+export declare const cartBadgeCore: import("../define.js").ElementCore<CartBadgeProps, CartBadgeState, CartBadgeDerived, {
+    countChanged(count: number): void;
+    hydrate(): void;
+    click(): void;
+}, "ready", {
+    /** Read as "Cart with 2 items". The count is appended. */
+    ariaPrefix: string;
+    ariaSuffix: string;
+    overflow: string;
+}>;
+export {};

package/dist/esm/cores/cart-badge.js

@@ -0,0 +1,147 @@
+/**
+ * `tl-cart-badge`: the cart icon with the item count on it.
+ *
+ * Small, and the second element that lives on a subscription: it binds
+ * `cart:updated` inside its own `mount` and hands the unsubscribe to
+ * `ctx.onTeardown` (TKT-197), so a badge that is moved in the DOM, or rendered
+ * twice by a host that mounts and unmounts it, never ends up counting twice.
+ *
+ * The one thing it remembers is the last count, so the badge does not flash
+ * empty on the next page before the cart has been read. That is behaviour, so
+ * it is here; where the count is written down is per runtime, so that is
+ * `ctx.storage`, which the harness supplies.
+ */
+import { defineElement } from '../define.js';
+/** Where the last known count is kept. The key the component used. */
+export const CART_COUNT_KEY = 'tl_cart_count';
+const STRINGS = {
+    /** Read as "Cart with 2 items". The count is appended. */
+    ariaPrefix: 'Cart with ',
+    ariaSuffix: ' items',
+    overflow: '99+',
+};
+/** Above this the bubble reads "99+" rather than a number nothing can fit. */
+const OVERFLOW_ABOVE = 99;
+const countOf = (cart) => {
+    const c = cart;
+    return typeof c?.itemCount === 'number' ? c.itemCount : 0;
+};
+export const cartBadgeCore = defineElement({
+    tag: 'tl-cart-badge',
+    docs: 'A cart icon carrying the number of items in the cart, kept current from the cart bus.',
+    category: 'cart',
+    runtimes: ['web'],
+    tokens: [
+        'font-family',
+        'foreground',
+        'muted',
+        'primary',
+        'primary-foreground',
+        'radius-md',
+        'spacing-1',
+        'spacing-2',
+        'spacing-3',
+    ],
+    sdkMethods: ['cart.get', 'cart.on'],
+    props: {
+        showEmpty: {
+            type: 'boolean',
+            attr: 'show-empty',
+            default: false,
+            docs: 'Show the badge even when count is 0',
+        },
+        icon: {
+            type: 'string',
+            tsType: 'string | undefined',
+            attr: 'icon',
+            docs: 'Custom icon (emoji or text). If not provided, uses cart SVG',
+        },
+        size: {
+            type: 'string',
+            tsType: '"lg" | "md" | "sm"',
+            attr: 'size',
+            default: 'md',
+            docs: 'Size variant',
+        },
+        badgeOnly: {
+            type: 'boolean',
+            attr: 'badge-only',
+            default: false,
+            docs: 'Badge only mode - only shows the count bubble, no icon or button',
+        },
+    },
+    events: {
+        tlClick: { detail: '{ itemCount: number; }', docs: 'Emitted when the badge is clicked' },
+    },
+    strings: STRINGS,
+    statuses: ['ready'],
+    state: () => ({ itemCount: 0 }),
+    /**
+     * On screen: show the remembered count straight away, then wait for the
+     * client, subscribe, and read the cart.
+     *
+     * Hydrating first is what keeps the badge from flashing empty; the component
+     * did it in `componentWillLoad` and this runs earlier still, in the harness's
+     * `connectedCallback`. A host with no store simply starts at zero.
+     */
+    mount: (ctx) => {
+        ctx.actions.hydrate();
+        void (async () => {
+            let client;
+            try {
+                client = await ctx.whenClient();
+            }
+            catch {
+                // A page that never started Live keeps the remembered count and says
+                // nothing, which is what the component did.
+                return;
+            }
+            if (!ctx.active())
+                return;
+            const manager = client.getCartManager?.();
+            if (!manager)
+                return;
+            const off = manager.on?.('cart:updated', (cart) => {
+                ctx.actions.countChanged(countOf(cart));
+            });
+            if (typeof off === 'function')
+                ctx.onTeardown(off);
+            try {
+                const read = manager.get?.bind(manager);
+                if (!read)
+                    return;
+                const cart = await read();
+                if (!ctx.active())
+                    return;
+                ctx.actions.countChanged(countOf(cart));
+            }
+            catch {
+                // The cart may not exist yet. Keep the remembered value.
+            }
+        })();
+    },
+    status: () => 'ready',
+    derive: ({ state, props, strings }) => ({
+        displayCount: state.itemCount > OVERFLOW_ABOVE ? strings.overflow : state.itemCount.toString(),
+        showBadge: state.itemCount > 0,
+        renderNothing: props.badgeOnly && state.itemCount === 0,
+        ariaLabel: `${strings.ariaPrefix}${state.itemCount}${strings.ariaSuffix}`,
+        sizeClass: `size-${props.size}`,
+    }),
+    actions: (ctx) => ({
+        /** A new count from the cart: show it, and remember it for next time. */
+        countChanged(count) {
+            ctx.setState({ itemCount: count });
+            ctx.storage.set(CART_COUNT_KEY, String(count));
+        },
+        /** Start from whatever the last visit left behind, or zero. */
+        hydrate() {
+            const stored = ctx.storage.get(CART_COUNT_KEY);
+            ctx.setState({ itemCount: (stored ? parseInt(stored, 10) : 0) || 0 });
+        },
+        /** The buyer asked for the cart. What that opens is the host's business. */
+        click() {
+            ctx.emit('tlClick', { itemCount: ctx.state.itemCount });
+        },
+    }),
+});

package/dist/esm/cores/cart-drawer.d.ts

@@ -0,0 +1,44 @@
+/** What opens the drawer, and what closes it. Relayed on the client's bus. */
+export declare const OPEN_INTENT = "ui:cart-requested";
+export declare const CLOSE_INTENT = "ui:modal-close-requested";
+export interface CartDrawerProps {
+    side: 'right' | 'left';
+    heading: string;
+    open: boolean;
+}
+export interface CartDrawerState {
+    visible: boolean;
+}
+export interface CartDrawerDerived {
+    visible: boolean;
+    /** The modifier the panel carries for the edge it slides from. */
+    sideClass: string;
+    /** `aria-hidden`, as the attribute's string. */
+    ariaHidden: 'true' | 'false';
+}
+export type CartDrawerStatus = 'open' | 'closed';
+declare const STRINGS: {
+    close: string;
+    privacy: string;
+    privacyHref: string;
+    reportAbuse: string;
+    reportAbuseHref: string;
+    poweredBy: string;
+    brand: string;
+    brandHref: string;
+};
+export type CartDrawerStrings = typeof STRINGS;
+export declare const cartDrawerCore: import("../define.js").ElementCore<CartDrawerProps, CartDrawerState, CartDrawerDerived, {
+    setOpen(open: boolean): void;
+    openChanged(open: boolean): void;
+}, CartDrawerStatus, {
+    close: string;
+    privacy: string;
+    privacyHref: string;
+    reportAbuse: string;
+    reportAbuseHref: string;
+    poweredBy: string;
+    brand: string;
+    brandHref: string;
+}>;
+export {};