@ticketlayer/elements-core 0.1.0 → 0.2.0

package/README.md

@@ -33,6 +33,15 @@ export const exampleCore = defineElement({
   state: () => ({ loading: true, error: null, items: [] }),
   status: ({ state }) => (state.loading ? 'loading' : state.error ? 'error' : 'ready'),
   derive: ({ state, strings }) => ({ caption: state.items.length ? '' : strings.empty }),
+  mount: (ctx) => {
+    void (async () => {
+      const client = await ctx.whenClient();
+      if (!ctx.active()) return;
+      await ctx.actions.load();
+      const off = client.on?.('cart:updated', () => ctx.actions.load());
+      if (off) ctx.onTeardown(off);
+    })();
+  },
   actions: (ctx) => ({
     async load() {
       const items = await ctx.client().getEventsManager().getTicketTypes(ctx.props.eventId, '');
@@ -47,6 +56,7 @@ A harness instantiates it, renders `view`, and forwards:
 ```ts
 const element = createElement(exampleCore, {
   client: () => getSDK(),
+  clientReady: () => whenSDK(),
   emit: (event, detail) => this.forward(event, detail),
 });
 element.subscribe((view) => (this.view = view));
@@ -55,6 +65,76 @@ element.subscribe((view) => (this.view = view));
 `view` is `{ status, props, state, strings, derived }`, recomputed after every
 change. The first three lines of a harness's render are a switch on `status`.
 
+## Mount and teardown
+
+`mount` is where a core says what happens when a harness puts the element on
+screen, and hands back what undoes it (TKT-197). Loading and subscribing belong
+here and not in a harness: a harness that decided when to load, or who owns a
+subscription, would have to decide it again for every runtime, and the two
+would drift. The web harness calls `mount()` from `connectedCallback` and its
+teardown from `disconnectedCallback`; a native harness calls the same two from
+whatever its runtime calls them.
+
+The rules, held by `test/mount.test.mjs` rather than by convention:
+
+| | |
+|---|---|
+| `instance.mount()` | Runs the core's `mount` and returns that mount's teardown. A core with no `mount` still mounts, and still returns a teardown that does nothing. |
+| The teardown | Runs everything registered with `ctx.onTeardown`, in reverse order, plus whatever `mount` returned. Idempotent: calling it a second time does nothing. A teardown from an earlier mount does nothing at all. |
+| Mounting while mounted | Tears the live mount down first. At most one mount is live, so a remount cannot leave two subscriptions behind. |
+| `destroy()` | Terminal. Runs the live mount's teardown, clears the timers and the listeners; mounting afterwards does nothing. A harness that only ever destroys still leaks nothing. |
+| `ctx.active()` | False once this mount has been torn down or the instance destroyed. A mount that awaits anything checks it before touching the state. |
+| `ctx.onTeardown(fn)` after teardown | Runs `fn` immediately, so a subscription made after an `await` cannot outlive the mount that asked for it. |
+| `ctx.whenClient()` | Resolves with the host's client once `clientReady` says it is up, and rejects when the host never produces one. On an action too, not only a mount: an action a buyer triggers can be the first thing that needs the client (`tl-promo-code` redeems a code without reading anything first), and `client()` would throw on a page that is still starting up. |
+
+On the web, `destroy()` is deliberately not called from `disconnectedCallback`:
+Stencil calls that for a move as well as a removal, and destroying there would
+leave a re-inserted element frozen. The teardown is what pairs with the mount.
+
+## What a core is handed besides the client
+
+`ctx.storage` is the runtime's key/value store: strings in, strings out,
+synchronous, and allowed to fail silently. It exists because a core is
+occasionally allowed to remember something between visits - `tl-cart-badge`
+keeps the last item count so the badge does not flash empty on the next page -
+and where that is written down is per runtime. The web harness passes a
+`localStorage` wrapper; a harness that passes nothing gets `NO_STORAGE`, whose
+reads come back null and whose writes go nowhere, so a core never has to ask
+whether it has somewhere to write.
+
+The rule is the same as for the client: the core says **what** it remembers and
+**when**, the harness says **where**.
+
+`ctx.query` is the second seam, and the same bargain. Two elements are the far
+end of a link somebody follows: `tl-login` exchanges the `?code=` a magic-link
+email lands on, and `tl-order-confirmation` finds its order in `?orderId=` and
+reads `?redirect_status=` to learn whether a payment provider sent the buyer
+back on a success. Where those parameters live is per runtime - the web has
+`window.location.search`, a native harness has its deep-link router - so the
+core says which parameter it reads and when, and the harness says where they
+come from. It reads one name at a time, synchronously, null when it is not
+there, and it is read-only: a core reports what a link said and does not
+rewrite the address bar, because navigation is the host's. The web harness
+passes `webQuery`; a harness that passes nothing gets `NO_QUERY`, whose reads
+come back null, and both elements fall through to what they do on a page with
+no link in it.
+
+## Props a type cannot say in one word
+
+`PropSpec.type` is the primitive a prop carries across every runtime. When the
+harness's type is narrower - a literal union, or a prop that may be undefined -
+the core writes it out as `tsType`:
+
+```ts
+size: { type: 'string', tsType: '"lg" | "md" | "sm"', attr: 'size', default: 'md', docs: 'Size variant' },
+icon: { type: 'string', tsType: 'string | undefined', attr: 'icon', docs: 'Custom icon' },
+```
+
+Written out for the same reason `EventSpec.detail` is: the catalogue is JSON and
+a type is not. The catalogue emitter compares `tsType ?? type` against what
+Stencil built, so a core and its harness cannot disagree about what a prop
+accepts.
+
 ## Tokens
 
 `tokens` names `@ticketlayer/theme` tokens by their canonical name: `primary`,
@@ -90,7 +170,64 @@ emitter take the CommonJS, because Jest will not load ESM from `node_modules`.
 
 ## What is here today
 
-`tl-ticket-selector` is the reference element: the first split, and the one the
-shape was proved against (TKT-68). The other seventeen still hold their
-behaviour in their Stencil component and their facts in the hand-kept manifest;
-they move across one at a time (TKT-11).
+Fifteen of the eighteen elements are split (TKT-11):
+
+| Core | What it proves |
+|---|---|
+| `tl-ticket-selector` | The reference element: the first split, and the one the shape was proved against (TKT-68, TKT-197). |
+| `tl-cart` | The first core to live on a subscription. It binds `cart:updated` in its own `mount` and hands the unsubscribe to `ctx.onTeardown`, and its lifecycle spec is the first end-to-end proof that a remount does not double subscribe (TKT-69). |
+| `tl-cart-badge` | The same subscription, plus `ctx.storage`: the one thing a core is allowed to remember. |
+| `tl-cart-drawer` | Two subscriptions on the client's own bus, and a state a host can drive from outside without hearing its own writes back. |
+| `tl-event-card` | A core filled either by a prop or by a read it starts itself, and an adapter that is behaviour rather than plumbing. |
+| `tl-promo-code` | A core with **no** `mount` hook at all: a harness still calls `mount()` and still gets a teardown. `whenClient()` on an action is what it needs instead. |
+| `tl-login` | The first core to read `ctx.query`, and the first whose whole shape is a phase machine. A magic-link code is single use, so the query is read once per instance and a remount cannot spend it again. |
+| `tl-my-orders` | Two subscriptions on the same bus, and a core whose emptiness is a question about the session rather than about the data: a 401 from the listing is not an error, it is the signed-out view. |
+| `tl-order-confirmation` | Three routes to one subject - a prop, the query, and a `checkout:completed` that arrives after the element is already on screen - and the last element of the eighteen to live on a subscription. |
+| `tl-event-list` | The smallest core there is: one read, one re-read when the question changes, and no events at all bar the click it passes on. |
+| `tl-order-tickets` | The one core that waits. Its mount owns a widening poll schedule and its teardown is what stops it, so no harness has to remember to. |
+| `tl-buy-tickets-wrapper` | The smallest core of the fifteen: no state at all, one action, and three events that exist only because the modal reports back to whoever opened it. Split once its events were renamed to `tlComplete`, `tlError` and `tlClose` (TKT-203). |
+| `tl-checkout-wrapper` | The same core pointed at the checkout, and the only one with no subject: the cart is the client's. |
+| `tl-buy-tickets-button` | The one whose look depends on its state. It derives the CLASS its sale state renders under and leaves the stylesheet to say which token family that class paints with, because a core cannot map a status onto one - the same bargain `tl-event-card`'s status badge makes. |
+| `tl-occurrence-selector` | The biggest, at 883 lines with no spec of its own, and the one split back to front: the characterisation spec was written and committed against the unsplit component FIRST, then passed unchanged against the harness. That is what makes it a split rather than a rewrite, bugs included - it still opens its calendar on the alphabetically first date, because `toDateString()` strings are what the component sorted (TKT-202). It also shows where the line falls: the core decides that `auto` turns horizontal at 768px, and the harness is what owns the `ResizeObserver` that measures one. |
+
+The other three still hold their behaviour in their Stencil component and their
+facts in the hand-kept `packages/elements/src/catalogue.manifest.json`; they move
+across one at a time.
+
+## What a core still cannot say
+
+Kept here because it is the useful half of a split, and because each one is a
+decision somebody will have to make rather than a gap to fill in quietly:
+
+- **Copy with something emphasised in the middle of it.** `strings` is a flat
+  map of finished sentences, so `tl-login`'s "We've sent a sign-in link to
+  **you@example.com**. Open it on this device to continue." is carried as
+  `sentLeadBefore` and `sentLeadAfter` with the address between them. That works
+  and it does not translate: a language that puts the address first has nowhere
+  to say so. What is missing is a placeholder in a string and a harness that
+  fills it.
+- **Which token family a status paints with.** `tokens` names the theme tokens
+  a harness renders with, and nothing in a core may hold a value. It is a flat
+  list, so there is no shape for saying that `soldOut` paints from `error` and
+  `waitlist` from `info`: a core can name the families its harnesses use, and
+  not which one belongs to which state. That is not a gap the split elements
+  wait on, because there is an answer already - the core derives the CLASS NAME
+  the status renders under and the stylesheet says which family that class
+  reaches for. `tl-event-card`'s status badge has done it since it was split,
+  and `tl-buy-tickets-button`, whose four states used to paint from literal hex
+  in the component and now read the `primary`, `error`, `info` and `warning`
+  families (TKT-203), was split on the same bargain. What is missing is only the
+  ability to state the mapping in the manifest, so a native harness with no
+  stylesheet could read it rather than write it out again.
+- **A file the buyer takes away.** `tl-ticket` downloads a PDF by making an
+  object URL and clicking an anchor. A core can say "the buyer asked for this
+  ticket"; it has no seam for handing a runtime a blob to save, the way
+  `ctx.storage` and `ctx.query` are seams for the other two runtime facts.
+- **A timer you can cancel.** `ctx.after(ms, fn)` schedules and hands nothing
+  back, and the instance only clears its timers on `destroy()`, which a web
+  harness never calls. `tl-order-tickets` polls, so it cancels by moving a
+  generation counter on and letting the stale timer fire into a no-op. That is
+  correct and it is not obvious, and every core that ever polls will have to
+  write it again until `after` returns its own cancel.
+- **Anything whose subject is another document.** `tl-seat-map` is an iframe and
+  a `postMessage` protocol. There is no runtime-neutral half to lift out of it.

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

@@ -0,0 +1,213 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buyTicketsButtonCore = void 0;
+/**
+ * `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.
+ */
+const define_js_1 = require("../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);
+}
+exports.buyTicketsButtonCore = (0, define_js_1.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/cjs/cores/buy-tickets-wrapper.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buyTicketsWrapperCore = void 0;
+/**
+ * `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.
+ */
+const define_js_1 = require("../define.js");
+const STRINGS = {
+    noClient: 'SDK not initialized',
+    notAvailable: 'Tickets are not available',
+};
+exports.buyTicketsWrapperCore = (0, define_js_1.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/cjs/cores/cart-badge.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cartBadgeCore = exports.CART_COUNT_KEY = void 0;
+/**
+ * `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.
+ */
+const define_js_1 = require("../define.js");
+/** Where the last known count is kept. The key the component used. */
+exports.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;
+};
+exports.cartBadgeCore = (0, define_js_1.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(exports.CART_COUNT_KEY, String(count));
+        },
+        /** Start from whatever the last visit left behind, or zero. */
+        hydrate() {
+            const stored = ctx.storage.get(exports.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 });
+        },
+    }),
+});