@mohasinac/appkit 4.63.5 → 4.64.1

package/dist/features/events/components/SpinWheel.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The wheel itself — segments, a pointer, and the settle.
+ *
+ * ## What this replaced
+ *
+ * A CSS circle with one 🎁 emoji rotating 2160deg on a fixed 3.2s timer. No
+ * segments, no pointer, and the prize list was loaded but used ONLY to decide
+ * whether to disable the button — so a visitor could not see what they might
+ * win. `prefers-reduced-motion` was ignored entirely, while every other
+ * primitive in `Motion.tsx` wires it.
+ *
+ * ## 🛑 SEGMENTS ARE EQUAL-SIZED, AND THAT IS NOT A SHORTCUT
+ *
+ * `weight` IS the odds. `toClientSpinPrize` is an allow-list emitting
+ * `{id, label, isActive}` only, and a tester case asserts
+ * `weightsInPublicSource: 0` — the stored shape leaked every wheel's odds into
+ * a client prop once already (Root Cause #70). Sizing a segment by its weight
+ * would publish the same information geometrically instead of as a number.
+ *
+ * So the wheel shows WHAT you could win, never how likely it is. That is also
+ * the honest framing: these are the prizes.
+ *
+ * @tag domain:events
+ * @tag layer:component
+ */
+import React from "react";
+export interface SpinWheelSegment {
+    id: string;
+    label: string;
+}
+export interface SpinWheelProps {
+    segments: SpinWheelSegment[];
+    /** Index of the winning segment once known, else null. */
+    winningIndex: number | null;
+    /** True from the click until the result is revealed. */
+    spinning: boolean;
+    /** Fired when the wheel has physically stopped. */
+    onSettled?: () => void;
+    size?: number;
+}
+export declare function SpinWheel({ segments, winningIndex, spinning, onSettled, size, }: SpinWheelProps): React.JSX.Element;

package/dist/features/events/components/SpinWheel.js

@@ -0,0 +1,128 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The wheel itself — segments, a pointer, and the settle.
+ *
+ * ## What this replaced
+ *
+ * A CSS circle with one 🎁 emoji rotating 2160deg on a fixed 3.2s timer. No
+ * segments, no pointer, and the prize list was loaded but used ONLY to decide
+ * whether to disable the button — so a visitor could not see what they might
+ * win. `prefers-reduced-motion` was ignored entirely, while every other
+ * primitive in `Motion.tsx` wires it.
+ *
+ * ## 🛑 SEGMENTS ARE EQUAL-SIZED, AND THAT IS NOT A SHORTCUT
+ *
+ * `weight` IS the odds. `toClientSpinPrize` is an allow-list emitting
+ * `{id, label, isActive}` only, and a tester case asserts
+ * `weightsInPublicSource: 0` — the stored shape leaked every wheel's odds into
+ * a client prop once already (Root Cause #70). Sizing a segment by its weight
+ * would publish the same information geometrically instead of as a number.
+ *
+ * So the wheel shows WHAT you could win, never how likely it is. That is also
+ * the honest framing: these are the prizes.
+ *
+ * @tag domain:events
+ * @tag layer:component
+ */
+import { useMemo } from "react";
+import { motion, useReducedMotion } from "motion/react";
+import { Div } from "../../../ui/index.js";
+/** Full turns before landing. Enough to read as a spin, short enough to wait. */
+const TURNS = 4;
+/** Degrees past the target before easing back — the "breath" at the end. */
+const OVERSHOOT_DEG = 9;
+/** Alternating fills. CSS variables, so a theme restyles the wheel with it. */
+const SEGMENT_FILLS = [
+    "var(--appkit-color-primary)",
+    "var(--appkit-color-primary-700)",
+    "var(--appkit-color-secondary)",
+    "var(--appkit-color-accent)",
+];
+function polar(cx, cy, r, deg) {
+    const rad = ((deg - 90) * Math.PI) / 180;
+    return { x: cx + r * Math.cos(rad), y: cy + r * Math.sin(rad) };
+}
+/** One pie slice from `startDeg` to `endDeg`, clockwise from 12 o'clock. */
+function segmentPath(cx, cy, r, startDeg, endDeg) {
+    const a = polar(cx, cy, r, startDeg);
+    const b = polar(cx, cy, r, endDeg);
+    const largeArc = endDeg - startDeg > 180 ? 1 : 0;
+    return `M ${cx} ${cy} L ${a.x} ${a.y} A ${r} ${r} 0 ${largeArc} 1 ${b.x} ${b.y} Z`;
+}
+export function SpinWheel({ segments, winningIndex, spinning, onSettled, size = 288, }) {
+    const reduced = useReducedMotion();
+    const n = Math.max(segments.length, 1);
+    const sweep = 360 / n;
+    const cx = size / 2;
+    const cy = size / 2;
+    const r = size / 2 - 6;
+    /**
+     * The rotation that puts the winning segment under the pointer.
+     *
+     * Segment i spans `[i*sweep, (i+1)*sweep)` clockwise from 12 o'clock, so its
+     * centre sits at `(i + 0.5) * sweep`. Rotating the wheel by the NEGATIVE of
+     * that brings the centre back to the top, where the pointer is. Whole turns
+     * are added on top purely for the look.
+     */
+    const target = useMemo(() => {
+        if (winningIndex === null)
+            return 0;
+        return TURNS * 360 - (winningIndex + 0.5) * sweep;
+    }, [winningIndex, sweep]);
+    /*
+     * 🛑 THE ANIMATION IS DRIVEN BY THE RESULT, NOT BY A TIMER.
+     *
+     * The old flow started a 3.2s CSS animation on click, awaited the server,
+     * then revealed the prize after ANOTHER blind 3.2s `setTimeout` — so the
+     * real wait was `latency + 3200ms`, the emoji visibly stopped before the
+     * prize card appeared, and the wheel never landed anywhere in particular
+     * because it always finished at 0deg mod 360.
+     *
+     * Here `winningIndex` stays null until the server answers; the wheel idles,
+     * then animates once to the segment it actually won.
+     *
+     * The keyframes are the "breath": overshoot a few degrees past the target,
+     * hold, then ease back onto it. Explicit keyframes rather than a spring so
+     * the overshoot is exact and cannot vary with the distance travelled.
+     */
+    const animate = winningIndex === null
+        ? { rotate: spinning ? TURNS * 360 : 0 }
+        : { rotate: [0, target + OVERSHOOT_DEG, target] };
+    const transition = winningIndex === null
+        ? { duration: spinning ? 2.4 : 0, ease: "linear", repeat: spinning ? Infinity : 0 }
+        : {
+            duration: 2.6,
+            // Most of the journey is the decelerating spin; the last 12% is the
+            // settle back from the overshoot.
+            times: [0, 0.88, 1],
+            // Mutable, not `as const` — motion types `ease` as `Easing[]`.
+            ease: ["easeOut", "easeInOut"],
+        };
+    /*
+     * The wrapper shrink-wraps the svg, which already carries width/height —
+     * it exists only to anchor the absolutely-positioned pointer. Sizing it
+     * again from props would be a second source of truth for one number.
+     */
+    return (_jsxs(Div, { className: "relative mx-auto inline-block leading-none", children: [_jsx(Div, { className: "absolute left-1/2 -translate-x-1/2 -top-0.5 z-10", "aria-hidden": "true", children: _jsx("svg", { width: "28", height: "22", viewBox: "0 0 28 22", children: _jsx("path", { d: "M14 22 L2 0 L26 0 Z", fill: "var(--appkit-color-text)", stroke: "var(--appkit-color-surface)", strokeWidth: "2" }) }) }), _jsxs(motion.svg, { width: size, height: size, viewBox: `0 0 ${size} ${size}`, 
+                // 🛑 Reduced motion skips the journey entirely and renders the wheel
+                // already landed. The result is identical; only the travel is removed.
+                animate: reduced ? { rotate: winningIndex === null ? 0 : target } : animate, transition: reduced ? { duration: 0 } : transition, onAnimationComplete: () => {
+                    if (winningIndex !== null)
+                        onSettled?.();
+                }, 
+                /*
+                 * 🛑 NOT `origin-center` — that class generates no rule in this
+                 * project's Tailwind build, and a class with no rule renders as an
+                 * unstyled element rather than as an error. It matters here: an SVG
+                 * element's transform-origin defaults to `0 0`, so without this the
+                 * wheel ORBITS its top-left corner instead of spinning in place.
+                 */
+                className: "[transform-origin:50%_50%]", role: "img", "aria-label": `Prize wheel with ${n} segment${n === 1 ? "" : "s"}: ${segments.map((s) => s.label).join(", ")}`, children: [segments.map((seg, i) => {
+                        const start = i * sweep;
+                        const end = start + sweep;
+                        const mid = start + sweep / 2;
+                        const labelPos = polar(cx, cy, r * 0.64, mid);
+                        return (_jsxs("g", { children: [_jsx("path", { d: segmentPath(cx, cy, r, start, end), fill: SEGMENT_FILLS[i % SEGMENT_FILLS.length], stroke: "var(--appkit-color-surface)", strokeWidth: "2" }), _jsx("text", { x: labelPos.x, y: labelPos.y, fill: "var(--appkit-color-text-on-primary)", fontSize: n > 6 ? 9 : 11, fontWeight: "600", textAnchor: "middle", dominantBaseline: "middle", transform: `rotate(${mid} ${labelPos.x} ${labelPos.y})`, children: seg.label.length > 18 ? `${seg.label.slice(0, 17)}…` : seg.label })] }, seg.id));
+                    }), _jsx("circle", { cx: cx, cy: cy, r: 16, fill: "var(--appkit-color-surface)", stroke: "var(--appkit-color-border)", strokeWidth: "2" })] })] }));
+}

package/dist/features/events/components/SpinWheelView.js

@@ -4,9 +4,9 @@ import { useCallback, useMemo, useState } from "react";
 import { useTranslations } from "next-intl";
 import { Button, ClaimCouponButton, Div, Heading, LoginRequiredModal, Row, Span, Stack, Text, useToast } from "../../../ui/index.js";
 import { isAuthError } from "../../../utils/auth-error.js";
+import { SpinWheel } from "./SpinWheel.js";
 import { normalizeError } from "../../../errors/normalize.js";
 import { toUserMessage } from "../../../errors/error-display-map.js";
-const CLS_WHEEL = "relative mx-auto aspect-square w-64 overflow-hidden rounded-full border-4 border-warning bg-[image:var(--appkit-gradient-promotion)]";
 // audit-content-alignment-ok: self-contained circular spin-wheel game widget, all text centered under the wheel by design
 const CLS_PRIZE_BOX = "rounded-xl border border-success bg-success-surface dark:border-success p-[var(--appkit-space-4)] text-center";
 const CLS_PRIZE_TITLE = "mt-1 text-[length:var(--appkit-text-lg)] font-bold text-success dark:text-success";
@@ -23,7 +23,6 @@ const DEFAULT_LABELS = {
     couponHint: "Coupon code:",
     errorFallback: "Spin failed. Please try again.",
 };
-const ANIMATION_MS = 3200;
 export function SpinWheelView({ eventId, prizes, alreadyUsed, initialPrizeId, initialCouponCode, windowStart, windowEnd, onSpin, labels, }) {
     const l = { ...DEFAULT_LABELS, ...(labels ?? {}) };
     const activePrizes = useMemo(() => prizes.filter((p) => p.isActive !== false), [prizes]);
@@ -48,14 +47,28 @@ export function SpinWheelView({ eventId, prizes, alreadyUsed, initialPrizeId, in
         setError(null);
         setSpinning(true);
         try {
+            /*
+             * 🛑 AWAIT FIRST, THEN LAND. The wheel idles while this resolves and
+             * only afterwards animates to the segment it actually won.
+             *
+             * It used to start a 3.2s CSS animation on click, await the server, and
+             * then reveal the prize after ANOTHER blind `setTimeout(3200)` — so the
+             * real wait was `latency + 3200ms`, the wheel visibly stopped before the
+             * prize appeared, and it never landed anywhere meaningful because the
+             * keyframes always finished at 0deg mod 360.
+             *
+             * `<SpinWheel>` now calls `onSettled` when it has physically stopped,
+             * which is what reveals the prize card — so the reveal is tied to the
+             * animation actually ending rather than to a duration guessed twice.
+             */
             const result = await onSpin(eventId);
-            window.setTimeout(() => {
-                setSpinning(false);
+            {
                 if (result.spinPrizeId) {
                     setResultPrizeId(result.spinPrizeId);
                     setResultCoupon(result.spinPrizeCouponCode);
                 }
                 else {
+                    setSpinning(false);
                     /*
                      * A 2xx with no prize. The server now refuses with a real status and
                      * code for every reason it knows (`reasonToHttp`), so reaching here
@@ -64,7 +77,7 @@ export function SpinWheelView({ eventId, prizes, alreadyUsed, initialPrizeId, in
                      */
                     setError(l.errorFallback);
                 }
-            }, ANIMATION_MS);
+            }
         }
         catch (err) {
             const e = normalizeError(err);
@@ -107,16 +120,24 @@ export function SpinWheelView({ eventId, prizes, alreadyUsed, initialPrizeId, in
     const wonPrize = resultPrizeId
         ? prizes.find((p) => p.id === resultPrizeId)
         : undefined;
-    return (_jsxs(Stack, { gap: "md", children: [_jsx(LoginRequiredModal, { isOpen: showLoginModal, onClose: () => setShowLoginModal(false), message: "You need to be signed in to spin the wheel. Please log in or create an account to continue." }), _jsxs(Heading, { level: 2, size: "xl", weight: "semibold", color: "primary", children: ["\uD83C\uDFA1 ", l.heading] }), _jsxs(Div, { className: CLS_WHEEL, "aria-label": "Spin wheel", children: [_jsx(Row, { className: "absolute inset-0", align: "center", justify: "center", style: {
-                            animation: spinning
-                                ? `lir-spin ${ANIMATION_MS}ms cubic-bezier(0.2, 0.8, 0.2, 1)`
-                                : undefined,
-                        }, children: _jsx(Text, { size: "4xl", children: "\uD83C\uDF81" }) }), _jsx("style", { children: `
- @keyframes lir-spin {
- 0% { transform: rotate(0deg); }
- 100% { transform: rotate(2160deg); }
- }
- ` })] }), wonPrize ? (_jsxs(Div, { className: CLS_PRIZE_BOX, children: [_jsx(Text, { className: "tracking-wide text-success", size: "sm", transform: "uppercase", children: l.wonHeadline }), _jsx(Text, { className: CLS_PRIZE_TITLE, children: wonPrize.label }), resultCoupon ? (_jsxs(_Fragment, { children: [_jsxs(Text, { className: CLS_PRIZE_BODY, children: [l.couponHint, " ", _jsx(Span, { weight: "semibold", className: "font-mono", children: resultCoupon })] }), _jsx(Row, { className: "mt-3", justify: "center", children: _jsx(ClaimCouponButton, { couponCode: resultCoupon, size: "sm", source: "spin" }) })] })) : null] })) : null, error ? (_jsx(Text, { className: CLS_ERROR_TEXT, children: error })) : null, _jsx(Row, { justify: "center", children: _jsx(Button, { variant: "primary", size: "lg", onClick: handleSpin, disabled: disabled, children: spinning ? l.spinningButton : l.spinButton }) }), alreadyUsed ? (
+    /*
+     * Which SEGMENT to land on — an index into `activePrizes`, because that is
+     * what the wheel draws.
+     *
+     * 🛑 `wonPrize` is looked up in the FULL list (a prize deactivated after
+     * somebody won it must still render), but the INDEX must come from the
+     * drawn list or the wheel would stop on the wrong wedge. `-1` means the
+     * won prize is no longer on the wheel, which is a real state: the result
+     * card still shows, the wheel simply does not animate to a segment that
+     * is not there.
+     */
+    const winningIndex = useMemo(() => {
+        if (!resultPrizeId)
+            return null;
+        const i = activePrizes.findIndex((p) => p.id === resultPrizeId);
+        return i >= 0 ? i : null;
+    }, [resultPrizeId, activePrizes]);
+    return (_jsxs(Stack, { gap: "md", children: [_jsx(LoginRequiredModal, { isOpen: showLoginModal, onClose: () => setShowLoginModal(false), message: "You need to be signed in to spin the wheel. Please log in or create an account to continue." }), _jsxs(Heading, { level: 2, size: "xl", weight: "semibold", color: "primary", children: ["\uD83C\uDFA1 ", l.heading] }), _jsx(SpinWheel, { segments: activePrizes.map((p) => ({ id: p.id, label: p.label })), winningIndex: winningIndex, spinning: spinning, onSettled: () => setSpinning(false) }), !wonPrize && activePrizes.length > 0 && (_jsx(Row, { wrap: true, gap: "xs", justify: "center", className: "mt-3", children: activePrizes.map((prize) => (_jsx(Span, { layout: "inline-flex", padding: "pill-sm", rounded: "full", size: "xs", surface: "muted", children: prize.label }, prize.id))) })), wonPrize ? (_jsxs(Div, { className: CLS_PRIZE_BOX, children: [_jsx(Text, { className: "tracking-wide text-success", size: "sm", transform: "uppercase", children: l.wonHeadline }), _jsx(Text, { className: CLS_PRIZE_TITLE, children: wonPrize.label }), resultCoupon ? (_jsxs(_Fragment, { children: [_jsxs(Text, { className: CLS_PRIZE_BODY, children: [l.couponHint, " ", _jsx(Span, { weight: "semibold", className: "font-mono", children: resultCoupon })] }), _jsx(Row, { className: "mt-3", justify: "center", children: _jsx(ClaimCouponButton, { couponCode: resultCoupon, size: "sm", source: "spin" }) })] })) : null] })) : null, error ? (_jsx(Text, { className: CLS_ERROR_TEXT, children: error })) : null, _jsx(Row, { justify: "center", children: _jsx(Button, { variant: "primary", size: "lg", onClick: handleSpin, disabled: disabled, children: spinning ? l.spinningButton : l.spinButton }) }), alreadyUsed ? (
             // audit-content-alignment-ok: self-contained circular spin-wheel game widget, status text centered under the wheel by design
             _jsx(Text, { size: "sm", align: "center", color: "muted", children: l.alreadySpun })) : !inWindow ? (
             // audit-content-alignment-ok: self-contained circular spin-wheel game widget, status text centered under the wheel by design

package/dist/features/events/constants/event-type-meta.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The ONE description of what an event type looks like and is called.
+ *
+ * ## Why this file exists
+ *
+ * The type had two unrelated visual languages and no shared label:
+ *
+ *  - The DETAIL HERO printed the raw enum under a CSS `capitalize`, so
+ *    `spin_wheel` rendered as the literal text **"Spin_wheel"** — the
+ *    underscore was never humanised anywhere.
+ *  - The CARD used a private `TYPE_ICONS` emoji map inside a `"use client"`
+ *    component, unexported and therefore unreachable from the hero.
+ *  - The COLOURS lived in a third place (`_constants.ts`), where `offer` and
+ *    `survey` shared one class string and `feedback` and `raffle` shared
+ *    another — so four of the eight types were not visually distinguishable.
+ *  - Both emoji were `aria-hidden` with NO text companion, so a screen-reader
+ *    user got no event type from a card at all.
+ *
+ * 🛑 `Record<EventType, …>` is the point. A ninth event type is a COMPILE
+ * ERROR here rather than a silently missing badge — the failure mode Root
+ * Cause #61 describes, where ten hand-written enumerations of one union
+ * drifted and nine of them never learned about the new member.
+ *
+ * @tag domain:events
+ * @tag layer:constants
+ */
+import type { EventType } from "../types";
+export interface EventTypeMeta {
+    /** Human label. Title case, never the raw enum. */
+    label: string;
+    /** Decorative glyph. ALWAYS paired with `label` for a screen reader. */
+    emoji: string;
+    /**
+     * The chip pairing. 🛑 `bg-{status}-surface` with `text-{status}` — both
+     * invert together with the theme, which is what keeps them readable in
+     * light and dark. Never pair either with a literal `text-white`: that is
+     * invisible in exactly one theme (Root Cause #67).
+     */
+    chipClass: string;
+    /** One line explaining what this kind of event is, for the hero subhead. */
+    blurb: string;
+}
+export declare const EVENT_TYPE_META: Record<EventType, EventTypeMeta>;
+/**
+ * Safe lookup for a value that arrived as a plain string — an API response, a
+ * URL parameter, a document written before a type existed.
+ *
+ * Falls back to a NEUTRAL chip with the raw value humanised, rather than to
+ * one of the real types: mislabelling a raffle as an offer is worse than
+ * admitting we do not recognise it.
+ */
+export declare function eventTypeMeta(type: string | undefined): EventTypeMeta;
+/** `spin_wheel` -> `Spin Wheel`. The thing CSS `capitalize` cannot do. */
+export declare function humaniseEventType(type: string | undefined): string;

package/dist/features/events/constants/event-type-meta.js

@@ -0,0 +1,109 @@
+/**
+ * The ONE description of what an event type looks like and is called.
+ *
+ * ## Why this file exists
+ *
+ * The type had two unrelated visual languages and no shared label:
+ *
+ *  - The DETAIL HERO printed the raw enum under a CSS `capitalize`, so
+ *    `spin_wheel` rendered as the literal text **"Spin_wheel"** — the
+ *    underscore was never humanised anywhere.
+ *  - The CARD used a private `TYPE_ICONS` emoji map inside a `"use client"`
+ *    component, unexported and therefore unreachable from the hero.
+ *  - The COLOURS lived in a third place (`_constants.ts`), where `offer` and
+ *    `survey` shared one class string and `feedback` and `raffle` shared
+ *    another — so four of the eight types were not visually distinguishable.
+ *  - Both emoji were `aria-hidden` with NO text companion, so a screen-reader
+ *    user got no event type from a card at all.
+ *
+ * 🛑 `Record<EventType, …>` is the point. A ninth event type is a COMPILE
+ * ERROR here rather than a silently missing badge — the failure mode Root
+ * Cause #61 describes, where ten hand-written enumerations of one union
+ * drifted and nine of them never learned about the new member.
+ *
+ * @tag domain:events
+ * @tag layer:constants
+ */
+export const EVENT_TYPE_META = {
+    sale: {
+        label: "Sale",
+        emoji: "🏷️",
+        chipClass: "bg-success-surface text-success",
+        blurb: "Reduced prices for a limited window.",
+    },
+    offer: {
+        label: "Offer",
+        emoji: "🎁",
+        chipClass: "bg-primary-surface text-primary",
+        blurb: "A code to use at checkout.",
+    },
+    poll: {
+        label: "Poll",
+        emoji: "📊",
+        chipClass: "bg-info-surface text-info",
+        blurb: "Vote — the result decides what we do next.",
+    },
+    survey: {
+        label: "Survey",
+        emoji: "📝",
+        // Was identical to `offer`. Distinct now: a survey asks, an offer gives.
+        chipClass: "bg-secondary-surface text-secondary",
+        blurb: "A few questions, and your answers shape the answer.",
+    },
+    feedback: {
+        label: "Feedback",
+        emoji: "💬",
+        chipClass: "bg-warning-surface text-warning",
+        blurb: "Tell us what is working and what is not.",
+    },
+    raffle: {
+        label: "Raffle",
+        emoji: "🎟️",
+        // Was identical to `feedback`. A prize draw is not a comment box.
+        chipClass: "bg-accent-surface text-accent",
+        blurb: "Free to enter. One entry, one winner.",
+    },
+    spin_wheel: {
+        // 🛑 THE BUG THIS FILE IS NAMED FOR. `capitalize` on the raw enum
+        // produced "Spin_wheel" on every spin event's hero.
+        label: "Spin the Wheel",
+        emoji: "🎡",
+        chipClass: "bg-error-surface text-error",
+        blurb: "One spin, one prize, straight to your wallet.",
+    },
+    lottery: {
+        label: "Lottery",
+        emoji: "🎰",
+        chipClass: "bg-info-surface text-info",
+        blurb: "Pick a numbered slot and claim its prize.",
+    },
+};
+/**
+ * Safe lookup for a value that arrived as a plain string — an API response, a
+ * URL parameter, a document written before a type existed.
+ *
+ * Falls back to a NEUTRAL chip with the raw value humanised, rather than to
+ * one of the real types: mislabelling a raffle as an offer is worse than
+ * admitting we do not recognise it.
+ */
+export function eventTypeMeta(type) {
+    const known = type ? EVENT_TYPE_META[type] : undefined;
+    if (known)
+        return known;
+    return {
+        label: humaniseEventType(type),
+        emoji: "📅",
+        chipClass: "bg-surface text-muted",
+        blurb: "",
+    };
+}
+/** `spin_wheel` -> `Spin Wheel`. The thing CSS `capitalize` cannot do. */
+export function humaniseEventType(type) {
+    if (!type)
+        return "Event";
+    return type
+        .split(/[_-]+/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}

package/dist/features/events/repository/event-likes.repository.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Event likes — toggle, count, and who liked recently.
+ *
+ * See `../schemas/likes.ts` for why the document id is the idempotency key
+ * and why no display name is stored on the row.
+ *
+ * @tag domain:events
+ * @tag layer:repository
+ * @tag access:server-only
+ */
+import { BaseRepository } from "../../../providers/db-firebase";
+import { type EventLikeDocument } from "../schemas/likes";
+export interface ToggleLikeResult {
+    /** The state AFTER the toggle — what the button should now show. */
+    liked: boolean;
+    /** The event's like count after the write. Safe to render directly. */
+    likeCount: number;
+}
+declare class EventLikesRepository extends BaseRepository<EventLikeDocument> {
+    constructor();
+    /**
+     * Like if not liked, unlike if liked. Returns the resulting state.
+     *
+     * 🛑 ONE TRANSACTION, ONE READ. The counter lives on the event
+     * (`stats.likeCount`) and the membership lives on the like document, so a
+     * bare `increment()` beside a bare `set()` would double-count a
+     * double-click: both writes would land and the count would say 2 for one
+     * person. Reading the like document inside the transaction is what makes
+     * the increment conditional on the membership actually changing.
+     *
+     * It is one read, not two — the event document is never read, because
+     * `FieldValue.increment` does not need its current value.
+     */
+    toggle(eventId: string, userId: string): Promise<ToggleLikeResult>;
+    /** Has this user liked it? One document read, no query, no index. */
+    hasLiked(eventId: string, userId: string): Promise<boolean>;
+    /**
+     * The most recent likers' user ids, newest first.
+     *
+     * Needs the composite index `(eventId ASC, createdAt DESC)` — declared in
+     * `appkit/firebase/base/firestore.indexes.json`. 🛑 Every like row is
+     * written with `createdAt`, so the `orderBy` cannot silently exclude rows
+     * the way an optional field would (Root Cause #100).
+     */
+    recentLikerIds(eventId: string, limit?: number, offset?: number): Promise<string[]>;
+    /**
+     * Like timestamps for the engagement chart, newest first and BOUNDED.
+     *
+     * `max` exists because this is the one method that reads more than a
+     * handful of rows, and an unbounded read on a popular event is exactly the
+     * N-document scan Rule #6 budgets against. 200 rows covers a 14-day chart
+     * at any volume worth plotting.
+     */
+    recentLikeTimes(eventId: string, max?: number): Promise<Date[]>;
+}
+export declare const eventLikesRepository: EventLikesRepository;
+export {};

package/dist/features/events/repository/event-likes.repository.js

@@ -0,0 +1,151 @@
+/**
+ * Event likes — toggle, count, and who liked recently.
+ *
+ * See `../schemas/likes.ts` for why the document id is the idempotency key
+ * and why no display name is stored on the row.
+ *
+ * @tag domain:events
+ * @tag layer:repository
+ * @tag access:server-only
+ */
+import { normalizeError } from "../../../errors/normalize.js";
+import { DatabaseError } from "../../../errors/index.js";
+import { serverLogger } from "../../../monitoring/index.js";
+import { BaseRepository } from "../../../providers/db-firebase/index.js";
+import { EVENT_LIKES_COLLECTION, EVENT_LIKE_FIELDS, eventLikeId, LIKERS_PREVIEW_LIMIT, } from "../schemas/likes.js";
+import { EVENTS_COLLECTION } from "../schemas/firestore.js";
+class EventLikesRepository extends BaseRepository {
+    constructor() {
+        super(EVENT_LIKES_COLLECTION);
+    }
+    /**
+     * Like if not liked, unlike if liked. Returns the resulting state.
+     *
+     * 🛑 ONE TRANSACTION, ONE READ. The counter lives on the event
+     * (`stats.likeCount`) and the membership lives on the like document, so a
+     * bare `increment()` beside a bare `set()` would double-count a
+     * double-click: both writes would land and the count would say 2 for one
+     * person. Reading the like document inside the transaction is what makes
+     * the increment conditional on the membership actually changing.
+     *
+     * It is one read, not two — the event document is never read, because
+     * `FieldValue.increment` does not need its current value.
+     */
+    async toggle(eventId, userId) {
+        try {
+            const db = this.db;
+            const likeRef = this.getCollection().doc(eventLikeId(eventId, userId));
+            const eventRef = db.collection(EVENTS_COLLECTION).doc(eventId);
+            return await db.runTransaction(async (tx) => {
+                const [likeSnap, eventSnap] = await Promise.all([tx.get(likeRef), tx.get(eventRef)]);
+                if (!eventSnap.exists) {
+                    // Liking a deleted event would create a row nothing can ever clean
+                    // up — the cascade keys on the event existing.
+                    throw new DatabaseError(`Event not found: ${eventId}`);
+                }
+                const current = Number(eventSnap.data()?.stats?.likeCount ?? 0);
+                if (likeSnap.exists) {
+                    tx.delete(likeRef);
+                    // 🛑 Floor at zero. A count can only go negative if it drifted —
+                    // a row deleted by the tester cascade without the counter moving,
+                    // say — and a public "-1 likes" is worse than an understated 0.
+                    const next = Math.max(0, current - 1);
+                    tx.update(eventRef, { "stats.likeCount": next, updatedAt: new Date() });
+                    return { liked: false, likeCount: next };
+                }
+                tx.set(likeRef, {
+                    eventId,
+                    userId,
+                    createdAt: new Date(),
+                });
+                const next = current + 1;
+                tx.update(eventRef, { "stats.likeCount": next, updatedAt: new Date() });
+                return { liked: true, likeCount: next };
+            });
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            serverLogger.error("eventLikes.toggle failed", { eventId, userId, message: e.message });
+            throw new DatabaseError(`Failed to toggle like: ${e.message}`);
+        }
+    }
+    /** Has this user liked it? One document read, no query, no index. */
+    async hasLiked(eventId, userId) {
+        try {
+            const snap = await this.getCollection().doc(eventLikeId(eventId, userId)).get();
+            return snap.exists;
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            serverLogger.warn("eventLikes.hasLiked failed", { eventId, userId, message: e.message });
+            // Fail CLOSED to "not liked": an unliked heart that turns out to be
+            // liked is one wasted tap, and `toggle` is idempotent on the id so the
+            // state self-corrects. Failing open would show a filled heart the user
+            // cannot un-fill.
+            return false;
+        }
+    }
+    /**
+     * The most recent likers' user ids, newest first.
+     *
+     * Needs the composite index `(eventId ASC, createdAt DESC)` — declared in
+     * `appkit/firebase/base/firestore.indexes.json`. 🛑 Every like row is
+     * written with `createdAt`, so the `orderBy` cannot silently exclude rows
+     * the way an optional field would (Root Cause #100).
+     */
+    async recentLikerIds(eventId, limit = LIKERS_PREVIEW_LIMIT, offset = 0) {
+        try {
+            const snapshot = await this.getCollection()
+                .where(EVENT_LIKE_FIELDS.EVENT_ID, "==", eventId)
+                .orderBy(EVENT_LIKE_FIELDS.CREATED_AT, "desc")
+                .limit(limit + offset)
+                .get();
+            return snapshot.docs
+                .slice(offset)
+                .map((d) => String(d.data().userId))
+                .filter(Boolean);
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            serverLogger.warn("eventLikes.recentLikerIds failed", { eventId, message: e.message });
+            return [];
+        }
+    }
+    /**
+     * Like timestamps for the engagement chart, newest first and BOUNDED.
+     *
+     * `max` exists because this is the one method that reads more than a
+     * handful of rows, and an unbounded read on a popular event is exactly the
+     * N-document scan Rule #6 budgets against. 200 rows covers a 14-day chart
+     * at any volume worth plotting.
+     */
+    async recentLikeTimes(eventId, max = 200) {
+        try {
+            const snapshot = await this.getCollection()
+                .where(EVENT_LIKE_FIELDS.EVENT_ID, "==", eventId)
+                .orderBy(EVENT_LIKE_FIELDS.CREATED_AT, "desc")
+                .limit(max)
+                .get();
+            return snapshot.docs
+                .map((d) => {
+                /*
+                 * Firestore hands back a Timestamp, the Admin SDK sometimes a Date,
+                 * and a seeded row a Date. Naming both shapes beats `unknown`: the
+                 * union is small, closed, and says what the field can actually be.
+                 */
+                const raw = d.data()
+                    .createdAt;
+                if (raw instanceof Date)
+                    return raw;
+                return typeof raw?.toDate === "function" ? raw.toDate() : null;
+            })
+                .filter((d) => d !== null);
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            serverLogger.warn("eventLikes.recentLikeTimes failed", { eventId, message: e.message });
+            return [];
+        }
+    }
+}
+export const eventLikesRepository = new EventLikesRepository();