@ticketlayer/elements-core 0.1.0 → 0.2.0

package/dist/cjs/cores/occurrence-selector.js

@@ -0,0 +1,528 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.occurrenceSelectorCore = exports.HORIZONTAL_MIN_WIDTH = void 0;
+/**
+ * `tl-occurrence-selector`: every date and time one event is on, and the one
+ * the buyer picks.
+ *
+ * The largest of the eighteen, and the last big one: 883 lines of Stencil with
+ * no spec at all, which is why TKT-202 wrote the characterisation spec first
+ * and split it on its own. Everything below is what that component did, ported
+ * rather than redesigned, and the spec
+ * (`packages/elements/src/components/tl-occurrence-selector/test/`) is the
+ * proof - it passed against the component before this file existed and passes
+ * against the harness now, unchanged.
+ *
+ * What it decides, in the order it decides it:
+ *
+ *  - Which of three views to render. A host can force one; otherwise five
+ *    occurrences or fewer is a LIST, more than five all on one calendar date
+ *    is a grid of SLOTS, and more than five over several dates is a CALENDAR
+ *    with the picked date's times beside it.
+ *  - Where the calendar opens. Ported with its bug intact: the dates are sorted
+ *    as `Date.toDateString()` STRINGS, so "Fri Jul 05 2030" sorts before
+ *    "Fri Jun 14 2030" and a weekday name decides the order before a month
+ *    does. Fixing that is a decision about the product, not part of moving the
+ *    code, and a split that quietly corrected it would be exactly the kind of
+ *    change the characterisation spec exists to catch.
+ *  - Which days a buyer may press, which are sold out, and how far the month
+ *    navigation may walk in each direction.
+ *  - Every label: the `en-GB` dates and times, the capacity line, the weekday
+ *    headings and the two month-navigation labels a screen reader reads.
+ *
+ * What is NOT here, and why:
+ *
+ *  - The `theme` prop. It is declared, because it is part of the element's
+ *    published surface, and it is the harness that acts on it: the prop is a
+ *    set of CSS CUSTOM PROPERTIES written onto the element, and a custom
+ *    property is not a fact every runtime has. A core holds no values at all,
+ *    so there is nothing here for it to hold.
+ *  - How wide the element is. `containerWidth` is state the harness measures
+ *    and pushes in through `resized()`; the core decides what a width MEANS
+ *    (`auto` becomes horizontal at 768px and not before), which is the same
+ *    bargain as `ctx.storage` - the core says what, the harness says where.
+ *  - Which token family a state paints with. The core derives the CLASS a
+ *    calendar day renders under and the stylesheet says what that class paints,
+ *    because a core cannot map a status onto a token family
+ *    (`tl-event-card`'s status badge and `tl-buy-tickets-button` make the same
+ *    bargain).
+ *
+ * What did not come across is the `console.error` on a failed read and the
+ * `console.log` on every selection, for the reason `tl-cart` and
+ * `tl-promo-code` dropped theirs: a library should not write to its host's
+ * console.
+ */
+const define_js_1 = require("../define.js");
+const STRINGS = {
+    noEventId: 'Event ID is required',
+    noClient: 'SDK not initialized.',
+    notFound: 'Event not found',
+    loadFailed: 'Failed to load occurrences',
+    empty: 'No dates available for this event.',
+    retry: 'Retry',
+    soldOut: 'Sold Out',
+    /** Follows the figure: "120 available". */
+    available: 'available',
+    selectADate: 'Select a date to see available times',
+    previousMonth: 'Previous month',
+    nextMonth: 'Next month',
+    weekdayMon: 'Mon',
+    weekdayTue: 'Tue',
+    weekdayWed: 'Wed',
+    weekdayThu: 'Thu',
+    weekdayFri: 'Fri',
+    weekdaySat: 'Sat',
+    weekdaySun: 'Sun',
+};
+/** Above this many pixels an `auto` layout puts the times beside the calendar. */
+exports.HORIZONTAL_MIN_WIDTH = 768;
+/** More than this many occurrences and the list view gives way. */
+const LIST_LIMIT = 5;
+// ---------------------------------------------------------------------------
+// Dates. Every one of these is the component's own arithmetic, moved.
+// ---------------------------------------------------------------------------
+/** Local midnight on the day `date` falls on. */
+function startOfDay(date) {
+    const start = new Date(date);
+    start.setHours(0, 0, 0, 0);
+    return start;
+}
+/** The key a day is held under, which is also what a harness hands back. */
+function dayKey(date) {
+    return date.toDateString();
+}
+/** Monday of the week `date` falls in. */
+function mondayOf(date) {
+    const monday = new Date(date);
+    const dayOfWeek = monday.getDay();
+    monday.setDate(monday.getDate() - (dayOfWeek === 0 ? 6 : dayOfWeek - 1));
+    monday.setHours(0, 0, 0, 0);
+    return monday;
+}
+/** The first of the month `date` falls in. */
+function firstOfMonth(date) {
+    return new Date(date.getFullYear(), date.getMonth(), 1);
+}
+const startTime = (occurrence) => new Date(occurrence.startsAt).getTime();
+const byStart = (a, b) => startTime(a) - startTime(b);
+/** As the component decided it: an explicit zero counts as gone. */
+const isSoldOut = (occurrence) => !!occurrence.soldOut || occurrence.availableCapacity === 0;
+/** Day key -> the occurrences on it, in the order the event gave them. */
+function occurrencesByDate(occurrences) {
+    const map = new Map();
+    for (const occurrence of occurrences) {
+        const key = dayKey(startOfDay(new Date(occurrence.startsAt)));
+        const on = map.get(key);
+        if (on)
+            on.push(occurrence);
+        else
+            map.set(key, [occurrence]);
+    }
+    return map;
+}
+/** The earliest and latest occurrence, or null when there are none. */
+function dateRangeOf(occurrences) {
+    if (!occurrences.length)
+        return null;
+    let first = new Date(occurrences[0].startsAt);
+    let last = new Date(occurrences[0].startsAt);
+    for (const occurrence of occurrences) {
+        const date = new Date(occurrence.startsAt);
+        if (date < first)
+            first = date;
+        if (date > last)
+            last = date;
+    }
+    return { first, last };
+}
+/** Whether everything fits between one Monday and the Sunday after it. */
+function isSingleWeek(occurrences) {
+    const range = dateRangeOf(occurrences);
+    if (!range)
+        return false;
+    const sunday = new Date(mondayOf(range.first));
+    sunday.setDate(sunday.getDate() + 6);
+    sunday.setHours(23, 59, 59, 999);
+    return range.last <= sunday;
+}
+/** Whether everything falls in one calendar month. */
+function isSingleMonth(occurrences) {
+    const range = dateRangeOf(occurrences);
+    if (!range)
+        return false;
+    return (range.first.getMonth() === range.last.getMonth() &&
+        range.first.getFullYear() === range.last.getFullYear());
+}
+/**
+ * Where the calendar opens.
+ *
+ * The sort is on `toDateString()` STRINGS and that is not an oversight here:
+ * it is what the component did, so "Fri Jul 05 2030" comes before
+ * "Fri Jun 14 2030" and the element opens on July. See the note at the top.
+ */
+function initialSelection(occurrences) {
+    if (!occurrences.length)
+        return null;
+    const today = startOfDay(new Date());
+    const keys = Array.from(occurrencesByDate(occurrences).keys()).sort();
+    let selected = null;
+    for (const key of keys) {
+        const date = new Date(key);
+        if (date >= today) {
+            selected = date;
+            break;
+        }
+    }
+    if (!selected && keys.length)
+        selected = new Date(keys[keys.length - 1]);
+    if (!selected)
+        return null;
+    return { selectedDate: selected, currentMonth: firstOfMonth(selected) };
+}
+/**
+ * The grid: one week when everything fits in one, else the whole month padded
+ * out to whole Monday-to-Sunday weeks.
+ */
+function calendarDays(occurrences, currentMonth) {
+    const days = [];
+    if (isSingleWeek(occurrences)) {
+        const range = dateRangeOf(occurrences);
+        if (!range)
+            return days;
+        const cursor = mondayOf(range.first);
+        for (let i = 0; i < 7; i += 1) {
+            days.push(new Date(cursor));
+            cursor.setDate(cursor.getDate() + 1);
+        }
+        return days;
+    }
+    const year = currentMonth.getFullYear();
+    const month = currentMonth.getMonth();
+    const monthStart = new Date(year, month, 1);
+    const monthEnd = new Date(year, month + 1, 0);
+    const startDay = monthStart.getDay();
+    const calendarStart = new Date(monthStart);
+    calendarStart.setDate(calendarStart.getDate() - (startDay === 0 ? 6 : startDay - 1));
+    const endDay = monthEnd.getDay();
+    const calendarEnd = new Date(monthEnd);
+    calendarEnd.setDate(calendarEnd.getDate() + (endDay === 0 ? 0 : 7 - endDay));
+    const cursor = new Date(calendarStart);
+    while (cursor <= calendarEnd) {
+        days.push(new Date(cursor));
+        cursor.setDate(cursor.getDate() + 1);
+    }
+    return days;
+}
+/**
+ * As the component formatted them: `en-GB`, written down here rather than taken
+ * from the host's locale 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 formatDate(date) {
+    return date.toLocaleDateString('en-GB', {
+        weekday: 'long',
+        day: 'numeric',
+        month: 'long',
+        year: 'numeric',
+    });
+}
+function formatTime(dateString) {
+    return new Date(dateString).toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' });
+}
+function formatMonth(date) {
+    return date.toLocaleDateString('en-GB', { month: 'long', year: 'numeric' });
+}
+/** The event detail's occurrences, as this element holds them. */
+function toOccurrence(occurrence) {
+    return {
+        id: occurrence.id,
+        startsAt: occurrence.startsAt,
+        endsAt: occurrence.endsAt,
+        status: occurrence.availabilityStatus,
+        availableCapacity: occurrence.availableCapacity,
+        soldOut: occurrence.availabilityStatus === 'sold_out',
+    };
+}
+exports.occurrenceSelectorCore = (0, define_js_1.defineElement)({
+    tag: 'tl-occurrence-selector',
+    docs: 'A smart occurrence selector component that fetches and displays event occurrences from the Ticketlayer API.',
+    category: 'discovery',
+    // Not `native`: the hand-kept manifest said `web` and there is no React
+    // Native harness for a calendar yet. Splitting it does not make that claim
+    // true, and the catalogue is read as a promise about where an element runs.
+    runtimes: ['web'],
+    tokens: [
+        'background',
+        'border',
+        'font-family',
+        'foreground',
+        'muted',
+        'muted-foreground',
+        'primary',
+        'primary-foreground',
+        'radius-md',
+    ],
+    sdkMethods: ['events.get'],
+    props: {
+        eventId: {
+            type: 'string',
+            attr: 'event-id',
+            required: true,
+            docs: 'Event ID to fetch occurrences for',
+        },
+        displayMode: {
+            type: 'string',
+            tsType: '"calendar" | "list" | "slots" | undefined',
+            attr: 'display-mode',
+            docs: 'Force a specific display mode (auto-detected if not set)',
+        },
+        orientation: {
+            type: 'string',
+            tsType: '"auto" | "horizontal" | "vertical"',
+            attr: 'orientation',
+            default: 'auto',
+            docs: 'Layout orientation (auto = horizontal on desktop, vertical on mobile)',
+        },
+        theme: {
+            type: 'object',
+            tsType: 'TlOccurrenceSelectorTheme | undefined',
+            attr: null,
+            docs: 'Theme configuration',
+        },
+    },
+    events: {
+        tlSelect: {
+            detail: '{ occurrence: TlOccurrence; }',
+            docs: 'Emitted when an occurrence is selected',
+        },
+    },
+    strings: STRINGS,
+    statuses: ['loading', 'error', 'empty', 'ready'],
+    state: () => ({
+        loading: true,
+        error: null,
+        occurrences: [],
+        currentMonth: new Date(),
+        selectedDate: null,
+        containerWidth: 0,
+    }),
+    /**
+     * On screen: wait for the host's client, then read the event.
+     *
+     * The component did this in `componentWillLoad`, which held the first paint
+     * until the read came back. A mount hook cannot hold a paint, so the element
+     * shows its own skeleton first instead of a blank - the same change
+     * `tl-ticket-selector` and `tl-event-card` took when they moved onto the hook
+     * (TKT-197).
+     *
+     * There is nothing to unsubscribe: this element reads once and lives on what
+     * it read, so the mount registers no teardown and the harness still gets one.
+     */
+    mount: (ctx) => {
+        if (!ctx.props.eventId) {
+            ctx.actions.loadFailed(ctx.strings.noEventId);
+            return;
+        }
+        void (async () => {
+            try {
+                await ctx.whenClient();
+            }
+            catch (err) {
+                if (!ctx.active())
+                    return;
+                ctx.actions.loadFailed(err instanceof Error ? err.message : ctx.strings.noClient);
+                return;
+            }
+            if (!ctx.active())
+                return;
+            await ctx.actions.load();
+        })();
+    },
+    status: ({ state }) => state.loading ? 'loading' : state.error ? 'error' : state.occurrences.length === 0 ? 'empty' : 'ready',
+    derive: ({ state, props, strings }) => {
+        const { occurrences, selectedDate } = state;
+        const byDate = occurrencesByDate(occurrences);
+        const range = dateRangeOf(occurrences);
+        // Which view. The component decided this once, when the read came back;
+        // deriving it means a host that changes `display-mode` afterwards is
+        // answered at once rather than at the next read (TKT-202, named in the
+        // pull request as the one behaviour this split does not preserve exactly).
+        const mode = props.displayMode
+            ? props.displayMode
+            : occurrences.length <= LIST_LIMIT
+                ? 'list'
+                : byDate.size === 1
+                    ? 'slots'
+                    : 'calendar';
+        const horizontal = props.orientation === 'horizontal'
+            ? true
+            : props.orientation === 'vertical'
+                ? false
+                : state.containerWidth >= exports.HORIZONTAL_MIN_WIDTH;
+        const row = (occurrence) => {
+            const soldOut = isSoldOut(occurrence);
+            const start = formatTime(occurrence.startsAt);
+            return {
+                id: occurrence.id,
+                dateLabel: formatDate(new Date(occurrence.startsAt)),
+                timeLabel: occurrence.endsAt ? `${start} - ${formatTime(occurrence.endsAt)}` : start,
+                startLabel: start,
+                soldOut,
+                capacityLabel: occurrence.availableCapacity
+                    ? `${occurrence.availableCapacity} ${strings.available}`
+                    : null,
+                statusKind: soldOut ? 'soldOut' : occurrence.availableCapacity ? 'available' : 'arrow',
+            };
+        };
+        const inTimeOrder = [...occurrences].sort(byStart);
+        const selectedKey = selectedDate ? dayKey(selectedDate) : null;
+        const selectedOn = selectedKey ? [...(byDate.get(selectedKey) ?? [])].sort(byStart) : [];
+        const today = startOfDay(new Date());
+        const firstMonth = range ? firstOfMonth(range.first) : null;
+        const lastMonth = range ? firstOfMonth(range.last) : null;
+        const days = calendarDays(occurrences, state.currentMonth).map((date) => {
+            const key = dayKey(date);
+            const on = byDate.get(key);
+            const hasOccurrences = !!on;
+            const soldOut = hasOccurrences && on.every(isSoldOut);
+            const otherMonth = date.getMonth() !== state.currentMonth.getMonth();
+            const selected = selectedKey === key;
+            const isToday = key === dayKey(today);
+            const past = date < today;
+            return {
+                key,
+                dayNumber: String(date.getDate()),
+                otherMonth,
+                hasOccurrences,
+                soldOut,
+                selected,
+                today: isToday,
+                past,
+                selectable: hasOccurrences,
+                className: [
+                    'calendar-day',
+                    otherMonth ? 'other-month' : '',
+                    hasOccurrences ? 'has-occurrences' : '',
+                    soldOut ? 'sold-out' : '',
+                    selected ? 'selected' : '',
+                    isToday ? 'today' : '',
+                    past ? 'past' : '',
+                ]
+                    .filter(Boolean)
+                    .join(' '),
+            };
+        });
+        return {
+            mode,
+            horizontal,
+            viewClass: `calendar-view ${horizontal ? 'horizontal' : 'vertical'}`,
+            rows: occurrences.map(row),
+            slots: inTimeOrder.map(row),
+            slotsDateLabel: inTimeOrder.length ? formatDate(new Date(inTimeOrder[0].startsAt)) : null,
+            monthLabel: formatMonth(state.currentMonth),
+            showMonthNav: !isSingleMonth(occurrences),
+            canGoBack: !!firstMonth && state.currentMonth > firstMonth,
+            canGoForward: !!lastMonth && state.currentMonth < lastMonth,
+            weekdayLabels: [
+                strings.weekdayMon,
+                strings.weekdayTue,
+                strings.weekdayWed,
+                strings.weekdayThu,
+                strings.weekdayFri,
+                strings.weekdaySat,
+                strings.weekdaySun,
+            ],
+            days,
+            selectedDateLabel: selectedDate && selectedOn.length ? formatDate(selectedDate) : null,
+            selectedSlots: selectedOn.map(row),
+        };
+    },
+    actions: (ctx) => ({
+        /**
+         * Read the event and take its occurrences. Also what Retry runs, which is
+         * why it sets `loading` and clears the error itself rather than relying on
+         * the state it started in.
+         */
+        async load() {
+            ctx.setState({ loading: true, error: null });
+            try {
+                const events = ctx.client().getEventsManager();
+                const read = events.get?.bind(events);
+                if (!read)
+                    throw new TypeError('eventsManager.get is not a function');
+                const detail = (await read(ctx.props.eventId));
+                if (!detail)
+                    throw new Error(ctx.strings.notFound);
+                const occurrences = (detail.occurrences ?? []).map(toOccurrence);
+                ctx.setState({ occurrences, ...(initialSelection(occurrences) ?? {}) });
+            }
+            catch (err) {
+                ctx.setState({
+                    error: err instanceof Error ? err.message : ctx.strings.loadFailed,
+                    occurrences: [],
+                });
+            }
+            finally {
+                ctx.setState({ loading: false });
+            }
+        },
+        /** Nothing to read: no event id, or the host never produced a client. */
+        loadFailed(message) {
+            ctx.setState({ error: message, loading: false });
+        },
+        /**
+         * The buyer picked an occurrence. A sold out one is not pickable, which the
+         * harness also renders as disabled: the core decides, the harness shows.
+         */
+        select(occurrenceId) {
+            const occurrence = ctx.state.occurrences.find((o) => o.id === occurrenceId);
+            if (!occurrence || isSoldOut(occurrence))
+                return;
+            ctx.emit('tlSelect', { occurrence });
+        },
+        /** The buyer picked a day. Only a day with something on it counts. */
+        selectDate(key) {
+            if (!occurrencesByDate(ctx.state.occurrences).has(key))
+                return;
+            const date = new Date(key);
+            if (Number.isNaN(date.getTime()))
+                return;
+            const { currentMonth } = ctx.state;
+            const movedMonth = date.getMonth() !== currentMonth.getMonth() || date.getFullYear() !== currentMonth.getFullYear();
+            ctx.setState({
+                selectedDate: date,
+                ...(movedMonth ? { currentMonth: firstOfMonth(date) } : {}),
+            });
+        },
+        /** Back a month, and never before the first month there is anything in. */
+        previousMonth() {
+            const range = dateRangeOf(ctx.state.occurrences);
+            if (!range)
+                return;
+            const next = new Date(ctx.state.currentMonth);
+            next.setMonth(next.getMonth() - 1);
+            if (next >= firstOfMonth(range.first))
+                ctx.setState({ currentMonth: next });
+        },
+        /** Forward a month, and never past the last month there is anything in. */
+        nextMonth() {
+            const range = dateRangeOf(ctx.state.occurrences);
+            if (!range)
+                return;
+            const next = new Date(ctx.state.currentMonth);
+            next.setMonth(next.getMonth() + 1);
+            if (next <= firstOfMonth(range.last))
+                ctx.setState({ currentMonth: next });
+        },
+        /**
+         * How wide the harness measures the element. What a width means is the
+         * core's (`auto` turns horizontal at 768px); measuring one is the
+         * runtime's, and on the web that is a `ResizeObserver`.
+         */
+        resized(width) {
+            if (width === ctx.state.containerWidth)
+                return;
+            ctx.setState({ containerWidth: width });
+        },
+    }),
+});