@mohasinac/appkit 4.76.0 → 4.78.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.76.0",
-  "head": "5da3ede2a94c94baadd8314d99ff43092dc5abd2",
+  "version": "4.78.0",
+  "head": "fd8f0ee8109c0e0c16c567de8d8263c2bfa71551",
   "branch": "main",
   "dirty": true,
-  "builtAt": "2026-11-09T10:25:07.042Z"
+  "builtAt": "2026-11-09T13:25:12.547Z"
 }

package/dist/features/events/actions/event-actions.d.ts

@@ -1,9 +1,3 @@
-/**
- * Event Domain Actions (appkit/features/events)
- *
- * Business logic for event CRUD, status changes, entries, and public access.
- * Auth, rate-limiting, and input validation are handled by the calling server action.
- */
 import type { JsonValue } from "../../../schemas/types";
 import type { EventDocument, EventEntryDocument, EventEntryMedia } from "../schemas";
 import type { EventStatus } from "../types";

package/dist/features/events/actions/event-actions.js

@@ -1,3 +1,4 @@
+import { resolveEntryApproval, checkEntryMedia, resolveEntryLimit, } from "../schemas/firestore.js";
 /**
  * Event Domain Actions (appkit/features/events)
  *
@@ -510,11 +511,83 @@ export async function enterEvent(eventId, input, user, request) {
      * pool — that is the moderation path, not a standing review queue of every
      * entrant.
      */
-    const autoApprove = event.type === "poll" ||
+    /*
+     * ⚠ LEGACY FALLBACK ONLY — do not add a type to this expression.
+     *
+     * This was the whole decision until 2026-11-09, and it is `event.type ===`
+     * branching: the exact shape the governing principle calls a defect. It also
+     * meant a new type could not choose — `contest` is absent, so contest
+     * entries were moderated by accident, and changing that needed a release.
+     *
+     * It survives ONLY so events already in the database behave exactly as they
+     * did. `resolveEntryApproval` consults it last. A NEW type declares its
+     * default in `event-types-seed-data.ts`; a single event overrides with
+     * `entryApproval` on its own row. Delete this once every type has a default.
+     */
+    const legacyAutoApprove = event.type === "poll" ||
         event.type === "feedback" ||
         eventType === "giveaway" ||
         (event.type === "survey" &&
             !event.surveyConfig?.entryReviewRequired);
+    /*
+     * The event's own setting wins, then the type's default, then the legacy
+     * expression. Anything unrecognised resolves to MODERATED — fail closed, so
+     * newer config against an older deploy cannot start publishing unreviewed
+     * user content.
+     */
+    /*
+     * ⚠ The TYPE-level default is passed as `undefined` for now. The precedence
+     * chain is built for three levels — event row, then type default, then the
+     * legacy expression — and `event-types-seed-data.ts` is where a type's
+     * default belongs, beside the `ruleSets` it already carries.
+     *
+     * Reading it here needs the type definition loaded at this point, which this
+     * action does not currently do. Stated rather than faked: the EVENT-level
+     * override the owner asked for works completely; the type-level default is
+     * the next step and slots into the middle argument with no other change.
+     */
+    /*
+     * ── THE EVENT'S OWN ENTRY RULES, enforced on the SERVER ──────────────
+     *
+     * 🛑 Both checks live here rather than only in the route's zod schema,
+     * because zod cannot see the EVENT. The schema can bound request size with
+     * a fixed ceiling; only this point knows that THIS contest allows 3 photos
+     * and 1 video and one entry per person.
+     *
+     * 🛑 And a client-side form that hides the submit button is not
+     * enforcement — the POST is still reachable. This is the write path, so it
+     * is where the limits have to hold.
+     */
+    const mediaProblem = checkEntryMedia(input.media, event.entryMedia);
+    if (mediaProblem)
+        throw new ValidationError(mediaProblem);
+    /*
+     * One entry per participant by default (owner, 2026-11-09: "for now block
+     * single entry only"), overridable per event via `entryLimit`.
+     *
+     * ⚠ Checked for signed-in users only. A guest entry has no stable identity
+     * to count against — `guestIpHash` exists but an IP is shared by households
+     * and whole offices, so counting on it would block real people. Guest
+     * participation is gated separately by `allowGuestParticipation`; an event
+     * that needs a hard per-person limit should require sign-in, which is what
+     * the contest does.
+     *
+     * ⚠ NOT race-safe against two simultaneous submissions from one account.
+     * Making it so needs a transaction around count+create, or a deterministic
+     * entry id like `${eventId}:${uid}`. Stated rather than implied: the window
+     * is small and the consequence is a duplicate entry, not a lost one.
+     */
+    if (user?.uid) {
+        const limit = resolveEntryLimit(event.entryLimit);
+        const already = await eventEntryRepository.countUserEntries(resolvedEventId, user.uid);
+        if (already >= limit) {
+            throw new ValidationError(limit === 1
+                ? "You have already entered this event."
+                : `You have reached the limit of ${limit} entries for this event.`);
+        }
+    }
+    const approvalMode = resolveEntryApproval(event, undefined, legacyAutoApprove);
+    const autoApprove = approvalMode === "auto";
     const reviewStatus = autoApprove ? "approved" : "pending";
     const entry = await eventEntryRepository.createEntry({
         eventId: resolvedEventId,

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

@@ -5,6 +5,7 @@ import { useUrlTable } from "../../../react/hooks/useUrlTable.js";
 import { useEvents } from "../hooks/useEvents.js";
 import { Div } from "../../../ui/components/Div.js";
 import { Grid, Row, Stack } from "../../../ui/components/Layout.js";
+import { Button } from "../../../ui/components/Button.js";
 import { ListingFilterDrawer } from "../../../ui/components/ListingFilterDrawer.js";
 import { ListingToolbar, applyToggleVisibility } from "../../../ui/components/ListingToolbar.js";
 import { useFieldVisibility } from "../../shell/useFieldVisibility.js";
@@ -119,6 +120,24 @@ export function EventsIndexListing({ initialData, facetCounts }) {
         filterParts.push(sieveFilter(EVENT_FIELDS.STARTS_AT, SIEVE_OP.GTE, dateFrom));
     if (dateTo)
         filterParts.push(sieveFilter(EVENT_FIELDS.ENDS_AT, SIEVE_OP.LTE, dateTo));
+    /*
+     * LIVE / FINISHED tabs, split BY DATE WINDOW rather than by `status`
+     * (owner, 2026-11-09): an event is finished when its `endsAt` has passed.
+     *
+     * Why not `status`: the two can disagree. An event whose `endsAt` passed
+     * while nobody moved it off `active` would sit under "Live" forever, and a
+     * tab that lies about what is running is worse than no tab. The clock
+     * cannot forget to be updated.
+     *
+     * The "Show expired" toggle stays and the two do NOT fight: it widens the
+     * STATUS set, this narrows the DATE window. Selecting Finished with "Show
+     * expired" off still works, because a finished event may still be `active`.
+     */
+    const phase = table.get(TABLE_KEYS.TAB);
+    if (phase === "live" || phase === "finished") {
+        const nowIso = new Date().toISOString();
+        filterParts.push(sieveFilter(EVENT_FIELDS.ENDS_AT, phase === "live" ? SIEVE_OP.GTE : SIEVE_OP.LT, nowIso));
+    }
     const params = {
         q: table.get(TABLE_KEYS.QUERY) || undefined,
         page: table.getNumber(TABLE_KEYS.PAGE, 1),
@@ -131,7 +150,23 @@ export function EventsIndexListing({ initialData, facetCounts }) {
     const commitSearch = useCallback(() => {
         table.set(TABLE_KEYS.QUERY, searchInput.trim());
     }, [searchInput, table]);
-    return (_jsxs(Div, { className: "min-h-screen", children: [_jsx(ListingToolbar, { filterCount: activeFilterCount, onFiltersClick: openFilters, searchValue: searchInput, searchPlaceholder: "Search events...", onSearchChange: setSearchInput, onSearchCommit: commitSearch, sortValue: table.get(TABLE_KEYS.SORT) || sortBy(EVENT_FIELDS.STARTS_AT, "ASC"), sortOptions: EVENT_PUBLIC_SORT_OPTIONS, onSortChange: (v) => { table.set(TABLE_KEYS.SORT, v); }, view: view, onViewChange: handleViewToggle, onResetAll: resetAll, hasActiveState: hasActiveState, toggles: applyToggleVisibility([
+    return (_jsxs(Div, { className: "min-h-screen", children: [_jsx(Row, { gap: "xs", className: "px-[var(--appkit-space-4)] pt-[var(--appkit-space-3)]", children: [
+                    { key: "", label: "All" },
+                    { key: "live", label: "Live" },
+                    { key: "finished", label: "Finished" },
+                ].map((t) => {
+                    const active = (table.get(TABLE_KEYS.TAB) || "") === t.key;
+                    return (_jsx(Button, { variant: active ? "primary" : "ghost", size: "sm", "aria-pressed": active, onClick: () => {
+                            /*
+                             * Reset to page 1. Without this, switching from a set with 5
+                             * pages to one with 1 leaves `page=4` in the URL and the grid
+                             * renders empty — which reads as "no finished events" rather
+                             * than "you are past the end".
+                             */
+                            table.set(TABLE_KEYS.PAGE, "");
+                            table.set(TABLE_KEYS.TAB, t.key);
+                        }, children: t.label }, t.key || "all"));
+                }) }), _jsx(ListingToolbar, { filterCount: activeFilterCount, onFiltersClick: openFilters, searchValue: searchInput, searchPlaceholder: "Search events...", onSearchChange: setSearchInput, onSearchCommit: commitSearch, sortValue: table.get(TABLE_KEYS.SORT) || sortBy(EVENT_FIELDS.STARTS_AT, "ASC"), sortOptions: EVENT_PUBLIC_SORT_OPTIONS, onSortChange: (v) => { table.set(TABLE_KEYS.SORT, v); }, view: view, onViewChange: handleViewToggle, onResetAll: resetAll, hasActiveState: hasActiveState, toggles: applyToggleVisibility([
                     { label: "Show expired", active: showExpired, onChange: (next) => table.set(TABLE_KEYS.SHOW_EXPIRED, next ? "true" : "") },
                 ], editMode ? {} : toolbarVisibilityFields, toolbarFieldOrder) }), totalPages > 1 && (_jsx(StickyToolbar, { offset: "header+pagination", tone: "translucent", border: true, padding: "toolbar", children: _jsx(Row, { justify: "center", children: _jsx(Pagination, { currentPage: currentPage, totalPages: totalPages, onPageChange: (p) => table.setPage(p) }) }) })), _jsx(Div, { padding: "y-lg", children: isLoading ? (_jsx(Grid, { cols: "cards", gap: "lg", children: Array.from({ length: 6 }).map((_, i) => (_jsxs(Div, { className: `${__O.hidden} animate-pulse`, border: "subtle", rounded: "xl", children: [_jsx(Div, { className: "aspect-video", surface: "subtle" }), _jsxs(Stack, { className: `${__P.p4}`, gap: "sm", children: [_jsx(Div, { className: "h-4 w-3/4", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-3 w-full", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-3 w-2/3", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-8 mt-2", surface: "subtle", rounded: "default" })] })] }, i))) })) : events.length === 0 ? (_jsx(Text, { paddingY: "3xl", color: "muted", size: "sm", align: "start", children: "No events found." })) : view === "list" ? (_jsx(Stack, { className: "divide-y divide-zinc-100 divide-[var(--appkit-color-border-subtle)]", border: "subtle", rounded: "xl", children: events.map((event) => (_jsx(EventCard, { event: event }, event.id))) })) : (_jsx(Grid, { cols: "cards", gap: "lg", children: events.map((event) => (_jsx(EventCard, { event: event }, event.id))) })) }), _jsx(ListingFilterDrawer, { open: filterOpen, onClose: () => setFilterOpen(false), onApply: applyFilters, onClear: clearFilters, activeCount: activeFilterCount, children: _jsx(EventFilters, { table: pendingTable, variant: "public", counts: facetCounts, hideEmpty: Boolean(facetCounts) }) })] }));
 }

package/dist/features/events/schemas/firestore.d.ts

@@ -124,6 +124,68 @@ export interface EventDocument extends BaseDocument {
      */
     isPinned?: boolean;
     /** Test-data flag — set on the shared admin-seeded test event; swept by testDataCleanup. */
+    /**
+     * Who may publish an entry: nobody (`"moderated"`) or the entrant
+     * (`"auto"`). Set ON THE EVENT, per owner 2026-11-09.
+     *
+     * ## 🛑 This replaces a hardcoded type switch
+     *
+     * `enterEvent` decided this with:
+     *
+     *   const autoApprove =
+     *     event.type === "poll" || event.type === "feedback" ||
+     *     eventType === "giveaway" ||
+     *     (event.type === "survey" && !surveyConfig?.entryReviewRequired);
+     *
+     * That is `event.type === …` branching, which the governing principle names
+     * as a defect rather than a safeguard: *"a mechanism never asks what TYPE is
+     * this — it asks what CAPABILITY does this have"*. It also meant a NEW event
+     * type could not choose: `contest` is absent from that list, so contest
+     * entries were moderated by accident rather than by decision, and changing
+     * it would have required an appkit release.
+     *
+     * Now it is a value on the row. A moderated photo contest and an
+     * auto-approving one are two seed rows, not two code paths.
+     *
+     * 🛑 OPEN union, deliberately — `(string & {})` keeps autocomplete while
+     * allowing a mode this release has never heard of. `resolveEntryApproval`
+     * treats anything unknown as MODERATED, which is the fail-closed direction:
+     * an unrecognised setting must not publish unreviewed user content.
+     *
+     * Unset falls back to the type's default, then to the legacy expression, so
+     * no existing event changes behaviour. See `resolveEntryApproval`.
+     */
+    entryApproval?: EntryApprovalMode;
+    /**
+     * How much media ONE entry may carry. Owner spec 2026-11-09: **up to 3
+     * photos and 1 video, 4 items total.**
+     *
+     * 🛑 ON THE EVENT ROW, not in code, for the same reason `entryApproval` is:
+     * *"for now block single entry only but later allow config changes for all
+     * on the events"*. A second contest wanting 10 photos is a seed edit.
+     *
+     * The caps were already enforced — but as literals inside the submission
+     * route's zod schema (`.min(1).max(4)` plus two `.refine`s). That works for
+     * exactly one contest and cannot vary per event, which is the shape this
+     * project keeps having to undo.
+     *
+     * ⚠ zod cannot express these statically once they are per-event, so the
+     * schema keeps an ABSOLUTE ceiling (a sanity bound on request size) and the
+     * handler enforces THIS event's numbers after loading it. Both run; the
+     * schema is the cheap gate, the handler is the real one.
+     */
+    entryMedia?: EventEntryMediaLimits;
+    /**
+     * How many entries ONE participant may submit to this event.
+     *
+     * Owner, 2026-11-09: *"for now block single entry only"* — so the default
+     * is 1, and an event that wants more sets its own number.
+     *
+     * 🛑 Enforced on the SERVER, not by hiding the form. A client that has
+     * already submitted can still POST again; the check belongs where the write
+     * happens.
+     */
+    entryLimit?: number;
     isTestData?: boolean;
     /** When isTestData, the cutoff after which testDataCleanup deletes this doc. */
     testDataExpiresAt?: Date;
@@ -492,4 +554,74 @@ export declare const eventQueryHelpers: {
     readonly withRaffle: () => readonly ["hasRaffle", "==", true];
     readonly raffleNotYetDrawn: () => readonly ["raffleWinnerUserId", "==", null];
 };
+/**
+ * How an event decides whether a submitted entry is published immediately.
+ *
+ * 🛑 OPEN, not a closed enum. The platform ships two modes; a deployment
+ * that needs a third ("auto below N entries", "auto for verified buyers")
+ * writes its own slug and a resolver rule rather than waiting for a release.
+ */
+export type EntryApprovalMode = "auto" | "moderated" | (string & {});
+/**
+ * Resolve the approval mode for one entry submission.
+ *
+ * Order, most specific first:
+ *   1. `event.entryApproval`      — this event's own decision
+ *   2. `typeDefault`              — the event TYPE's default, from seed config
+ *   3. the legacy expression      — see below
+ *
+ * 🛑 FAILS CLOSED. Anything not recognised as `"auto"` resolves to
+ * moderated. An unknown mode arriving from newer config against an older
+ * deploy must not start publishing unreviewed user content — degrading to a
+ * review queue is recoverable, publishing is not.
+ *
+ * ⚠ The third fallback is a MIGRATION PATH, not a design. It reproduces the
+ * hardcoded type switch this field replaced so that events already in the
+ * database keep behaving exactly as they did. It should be deleted once every
+ * event type declares its own default in `event-types-seed-data.ts`.
+ */
+export declare function resolveEntryApproval(event: {
+    entryApproval?: EntryApprovalMode;
+    type?: string;
+    surveyConfig?: unknown;
+}, typeDefault?: EntryApprovalMode, legacyAutoApprove?: boolean): "auto" | "moderated";
+/**
+ * Per-entry media caps. All optional — an unset field falls back to the
+ * platform default in `resolveEntryMediaLimits`.
+ */
+export interface EventEntryMediaLimits {
+    /** Max images in one entry. Platform default: 3. */
+    maxImages?: number;
+    /** Max videos in one entry. Platform default: 1. */
+    maxVideos?: number;
+    /** Max items overall. Platform default: 4. */
+    maxTotal?: number;
+    /** Require at least one image. Platform default: true. */
+    requireImage?: boolean;
+}
+/**
+ * The platform defaults, stated once. Owner spec 2026-11-09 for the Diwali
+ * photo/video contest: 3 photos + 1 video, 4 total.
+ *
+ * 🛑 `maxTotal` is NOT `maxImages + maxVideos`. It is a separate cap on
+ * purpose: 3 + 1 = 4 today, but an event allowing 5 images and 2 videos may
+ * still want a 5-item ceiling. Deriving it would silently remove that choice.
+ */
+export declare const DEFAULT_ENTRY_MEDIA_LIMITS: Required<EventEntryMediaLimits>;
+/** This event's caps, with every unset field filled from the platform default. */
+export declare function resolveEntryMediaLimits(limits?: EventEntryMediaLimits): Required<EventEntryMediaLimits>;
+/**
+ * Check one submission's media against an event's caps.
+ *
+ * Returns a human-readable reason, or `null` when it passes. A string rather
+ * than a boolean because the caller surfaces it to the participant — "At most
+ * 3 photos" is actionable; "invalid" is not.
+ */
+export declare function checkEntryMedia(media: ReadonlyArray<{
+    type: string;
+}> | undefined, limits?: EventEntryMediaLimits): string | null;
+/** How many entries one participant may submit. Platform default: 1. */
+export declare const DEFAULT_ENTRY_LIMIT = 1;
+/** This event's per-participant entry limit. */
+export declare function resolveEntryLimit(entryLimit?: number): number;
 export {};

package/dist/features/events/schemas/firestore.js

@@ -140,3 +140,83 @@ export const eventQueryHelpers = {
     withRaffle: () => ["hasRaffle", "==", true],
     raffleNotYetDrawn: () => ["raffleWinnerUserId", "==", null],
 };
+/**
+ * Resolve the approval mode for one entry submission.
+ *
+ * Order, most specific first:
+ *   1. `event.entryApproval`      — this event's own decision
+ *   2. `typeDefault`              — the event TYPE's default, from seed config
+ *   3. the legacy expression      — see below
+ *
+ * 🛑 FAILS CLOSED. Anything not recognised as `"auto"` resolves to
+ * moderated. An unknown mode arriving from newer config against an older
+ * deploy must not start publishing unreviewed user content — degrading to a
+ * review queue is recoverable, publishing is not.
+ *
+ * ⚠ The third fallback is a MIGRATION PATH, not a design. It reproduces the
+ * hardcoded type switch this field replaced so that events already in the
+ * database keep behaving exactly as they did. It should be deleted once every
+ * event type declares its own default in `event-types-seed-data.ts`.
+ */
+export function resolveEntryApproval(event, typeDefault, legacyAutoApprove) {
+    const chosen = event.entryApproval ?? typeDefault;
+    if (chosen !== undefined)
+        return chosen === "auto" ? "auto" : "moderated";
+    return legacyAutoApprove ? "auto" : "moderated";
+}
+/**
+ * The platform defaults, stated once. Owner spec 2026-11-09 for the Diwali
+ * photo/video contest: 3 photos + 1 video, 4 total.
+ *
+ * 🛑 `maxTotal` is NOT `maxImages + maxVideos`. It is a separate cap on
+ * purpose: 3 + 1 = 4 today, but an event allowing 5 images and 2 videos may
+ * still want a 5-item ceiling. Deriving it would silently remove that choice.
+ */
+export const DEFAULT_ENTRY_MEDIA_LIMITS = {
+    maxImages: 3,
+    maxVideos: 1,
+    maxTotal: 4,
+    requireImage: true,
+};
+/** This event's caps, with every unset field filled from the platform default. */
+export function resolveEntryMediaLimits(limits) {
+    return {
+        maxImages: limits?.maxImages ?? DEFAULT_ENTRY_MEDIA_LIMITS.maxImages,
+        maxVideos: limits?.maxVideos ?? DEFAULT_ENTRY_MEDIA_LIMITS.maxVideos,
+        maxTotal: limits?.maxTotal ?? DEFAULT_ENTRY_MEDIA_LIMITS.maxTotal,
+        requireImage: limits?.requireImage ?? DEFAULT_ENTRY_MEDIA_LIMITS.requireImage,
+    };
+}
+/**
+ * Check one submission's media against an event's caps.
+ *
+ * Returns a human-readable reason, or `null` when it passes. A string rather
+ * than a boolean because the caller surfaces it to the participant — "At most
+ * 3 photos" is actionable; "invalid" is not.
+ */
+export function checkEntryMedia(media, limits) {
+    const l = resolveEntryMediaLimits(limits);
+    const items = media ?? [];
+    if (!items.length) {
+        return l.requireImage ? "Add at least one photo" : null;
+    }
+    if (items.length > l.maxTotal)
+        return `At most ${l.maxTotal} items in total`;
+    const images = items.filter((m) => m.type === "image").length;
+    const videos = items.filter((m) => m.type === "video").length;
+    if (images > l.maxImages)
+        return `At most ${l.maxImages} photos`;
+    if (videos > l.maxVideos)
+        return `At most ${l.maxVideos} video${l.maxVideos === 1 ? "" : "s"}`;
+    if (l.requireImage && images < 1)
+        return "At least one photo is required";
+    return null;
+}
+/** How many entries one participant may submit. Platform default: 1. */
+export const DEFAULT_ENTRY_LIMIT = 1;
+/** This event's per-participant entry limit. */
+export function resolveEntryLimit(entryLimit) {
+    return typeof entryLimit === "number" && entryLimit > 0
+        ? entryLimit
+        : DEFAULT_ENTRY_LIMIT;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.76.0",
+  "version": "4.78.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"