@acms-subir/core 0.3.22 → 0.3.23

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @acms-subir/core
 
+## 0.3.23
+
+### Patch Changes
+
+- 1a0ceb2: Narrow event lists by tag. Section sources take `tag` (only items with that tag) and `excludeTag` (leave them out) for events as well as posts, so one shared calendar can feed a Classes page (`tag: "Class"`) and a home page that leaves classes out (`excludeTag: "Class"`). The section editor shows both pickers, listing the tags used on events. The same options work in `upcomingEvents()` from `@acms-subir/core/theme`, `listEvents()` and `listOccurrences()` from `@acms-subir/core/server`, the app API (`/api/v1/events?tag=&excludeTag=`, and `events({ tag, excludeTag })` in the client), and `/api/calendar/events`. A filter matches a tag's name in any case or its slug ("bible-study" matches "Bible Study"); internal `#` tags match by their full name and are never matched by the public APIs. Section tags with spaces or a leading `#` no longer fail the pre-publish check.
+
 ## 0.3.22
 
 ### Patch Changes

package/docs/sections.md

@@ -97,11 +97,11 @@ Field keys are camelCase. Every field takes `label`, optional `help` (one line s
 | `date` | `YYYY-MM-DD` | string. Format with `formatDay()` | one-off dates |
 | `time` | `HH:MM` | string. Format with `formatTime()` | times of day |
 | `list` | array of rows | array of rows (sub-fields resolved the same way) | repeating things: services, people, plans, photos |
-| `source` | `{ calendar?, collection?, tag?, resource?, limit }` | fresh `EventItem[]` / `PostItem[]` / `BookingItem[]` | content that must stay current on its own |
+| `source` | `{ calendar?, collection?, tag?, excludeTag?, resource?, limit }` | fresh `EventItem[]` / `PostItem[]` / `BookingItem[]` | content that must stay current on its own |
 
 `list` options: `fields` (scalar sub-fields only; a list can't contain a list or source), `itemLabel` (the sub-field shown on collapsed rows), `min`, `max` (default 50).
 
-`source` options: `source: "events" | "posts" | "bookings"`. The owner picks which calendar / collection + tag / resource, and how many (1–24).
+`source` options: `source: "events" | "posts" | "bookings"`. The owner picks which calendar / collection / resource, and how many (1–24). Events and posts can also be narrowed by tag: `tag` shows only items with that tag, and `excludeTag` leaves out items with it. Both take a tag's name (any case) or slug, so a Classes page can show events tagged "Class" while the home page leaves them out. A theme can preset them in the field's `default`, e.g. `{ "tag": "Class", "limit": 6 }`.
 
 **When to use `source` instead of `list`:** if the thing already exists elsewhere in ACMS (calendar events, blog posts, booking links), link to it with `source`. Then the homepage updates itself when the calendar changes. Use a `list` only for content that lives nowhere else.
 

package/docs/server.md

@@ -27,9 +27,9 @@ use, so a site can replace any of them, or turn them all off, and keep the same
 ```ts
 getRepo(locals: unknown): Promise<Repo>
 currentUser(ctx: { request: Request; cookies: AstroCookies; locals: unknown }): Promise<ServerUser | null>
-listEvents(repo: Repo, opts?: { publishedOnly?: boolean; calendar?: string; hostedBy?: string }): Promise<CalEvent[]>
+listEvents(repo: Repo, opts?: { publishedOnly?: boolean; calendar?: string; hostedBy?: string; tag?: string; excludeTag?: string }): Promise<CalEvent[]>
 getEvent(repo: Repo, id: string): Promise<CalEvent | null>
-listOccurrences(repo: Repo, w: { eventId?: string; from: Date | number; to: Date | number }): Promise<Occurrence[]>
+listOccurrences(repo: Repo, w: { eventId?: string; from: Date | number; to: Date | number; tag?: string; excludeTag?: string }): Promise<Occurrence[]>
 cancelOccurrence(repo: Repo, eventId: string, occurrenceKey: string, ctx: WriteContext): Promise<CalEvent>
 restoreOccurrence(repo: Repo, eventId: string, occurrenceKey: string, ctx: WriteContext): Promise<CalEvent>
 
@@ -74,12 +74,14 @@ The types `Repo`, `Role`, `ServerUser`, `CalEvent`, `Occurrence`, `ListEventsOpt
 - **`listEvents(repo, opts)`**: events by first start date, earliest first. By default,
   every status except archived. `publishedOnly: true` returns only published events.
   `calendar` (an id or slug) limits the list to one calendar. `hostedBy` (a user id)
-  limits it to events that person hosts (`event.hostIds`). Values are the live ones;
-  unpublished edits staged in the admin are not merged in.
+  limits it to events that person hosts (`event.hostIds`). `tag` keeps only events with
+  that tag and `excludeTag` leaves them out; both take a tag's name (any case) or slug,
+  and an internal `#` tag by its full name. Values are the live ones; unpublished edits
+  staged in the admin are not merged in.
 - **`getEvent(repo, id)`**: one event, or `null`.
-- **`listOccurrences(repo, { eventId?, from, to })`**: occurrences in `[from, to)`,
-  soonest first, for one event or all non-archived events. The window can be up to 400
-  days. Each occurrence has its `key` (below) and `cancelled`, which is true when the
+- **`listOccurrences(repo, { eventId?, from, to, tag?, excludeTag? })`**: occurrences in
+  `[from, to)`, soonest first, for one event or all non-archived events, narrowed by tag
+  like `listEvents`. The window can be up to 400 days. Each occurrence has its `key` (below) and `cancelled`, which is true when the
   whole event or just that date is cancelled. Drafts are included, so check
   `o.event.status` before showing anything publicly.
 - **`cancelOccurrence(repo, eventId, key, { url, locals })`**: cancels one date of a

package/docs/theme-authoring.md

@@ -55,7 +55,7 @@ const date = new Intl.DateTimeFormat('en', { dateStyle: 'medium', timeZone: Astr
 </section>}
 ```
 
-`calendarConfig()` returns a fresh `{ enabled, base, eventsBase }` object; `eventUrl(slug)` uses the configured event base. `upcomingEvents(Astro, options?)` resolves storage through `Astro.locals` and loads the site's timezone settings. It returns the next or ongoing occurrence of each distinct published, publicly listed native event, soonest first, including recurring and all-day events. Private/unlisted calendars and external feed entries are excluded; cancelled public events remain visible so templates can label them. Disabled calendars and a zero limit return `[]` without accessing storage. Storage errors propagate to the template.
+`calendarConfig()` returns a fresh `{ enabled, base, eventsBase }` object; `eventUrl(slug)` uses the configured event base. `upcomingEvents(Astro, options?)` resolves storage through `Astro.locals` and loads the site's timezone settings. It returns the next or ongoing occurrence of each distinct published, publicly listed native event, soonest first, including recurring and all-day events. Private/unlisted calendars and external feed entries are excluded; cancelled public events remain visible so templates can label them. `tag` keeps only events with that tag and `excludeTag` leaves them out (a tag's name in any case, or its slug), e.g. `upcomingEvents(Astro, { tag: 'Class' })` for a Classes page. Disabled calendars and a zero limit return `[]` without accessing storage. Storage errors propagate to the template.
 
 Options default to `{ limit: 6, horizonDays: 400 }`. The limit must be a non-negative safe integer and the horizon a positive finite number. Each `UpcomingEvent` contains `{ event, start, end, allDay, days }`, with start/end in Unix milliseconds. Format occurrence timestamps using the site's timezone rather than the authored `event.start` when displaying recurring events. `UpcomingEvent`, `UpcomingEventsOptions`, and `ThemeCalendarConfig` are exported types.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acms-subir/core",
-  "version": "0.3.22",
+  "version": "0.3.23",
   "publishConfig": {
     "access": "public"
   },

package/src/components/sections/SectionFields.tsx

@@ -25,6 +25,8 @@ export interface SectionTargets {
   calendars: { slug: string; name: string }[];
   collections: { key: string; label: string }[];
   tags: string[];
+  /** tags on published events (the events source picks from these) */
+  eventTags?: string[];
   resources: { slug: string; name: string }[];
   features: { events: boolean; bookings: boolean };
   ai?: { enabled: boolean; languages: string[] };
@@ -321,27 +323,46 @@ function SourceInput({ id, field, value, onChange, targets }: InputProps<SourceF
   const off = (field.source === 'events' && !targets.features.events) || (field.source === 'bookings' && !targets.features.bookings);
   let from = '';
   let picker: ReactNode = null;
+  // only items with one tag, and/or leaving out another ("events not tagged Class")
+  const tag = String(v.tag ?? ''), excludeTag = String(v.excludeTag ?? '');
+  const tagged = `${tag ? ` tagged “${tag}”` : ''}${tag && excludeTag ? ',' : ''}${excludeTag ? ` not tagged “${excludeTag}”` : ''}`;
+  const tagPickers = (names: string[]) => {
+    // a saved tag no item uses any more stays listed, so the picker shows what's stored
+    const list = [...new Set([...names, tag, excludeTag].filter(Boolean))];
+    return (
+      <>
+        <select aria-label="Only items with this tag" value={tag} onChange={(e) => set({ tag: e.target.value })}>
+          <option value="">Any tag</option>
+          {list.map((t) => <option key={t} value={t}>{t}</option>)}
+        </select>
+        <select aria-label="Leave out items with this tag" value={excludeTag} onChange={(e) => set({ excludeTag: e.target.value })}>
+          <option value="">Leave nothing out</option>
+          {list.map((t) => <option key={t} value={t}>Leave out “{t}”</option>)}
+        </select>
+      </>
+    );
+  };
   if (field.source === 'events') {
     const cal = targets.calendars.find((c) => c.slug === v.calendar);
-    from = `Calendar${cal ? ` → ${cal.name}` : ' · all public calendars'}`;
+    from = `${cal ? `Calendar → ${cal.name}` : 'All public calendars'}${tagged ? ` · events${tagged}` : ''}`;
     picker = (
-      <select id={id} aria-label="Calendar" value={String(v.calendar ?? '')} onChange={(e) => set({ calendar: e.target.value })}>
-        <option value="">All public calendars</option>
-        {targets.calendars.map((c) => <option key={c.slug} value={c.slug}>{c.name}</option>)}
-      </select>
+      <>
+        <select id={id} aria-label="Calendar" value={String(v.calendar ?? '')} onChange={(e) => set({ calendar: e.target.value })}>
+          <option value="">All public calendars</option>
+          {targets.calendars.map((c) => <option key={c.slug} value={c.slug}>{c.name}</option>)}
+        </select>
+        {tagPickers(targets.eventTags ?? targets.tags)}
+      </>
     );
   } else if (field.source === 'posts') {
     const col = targets.collections.find((c) => c.key === (v.collection ?? 'posts'));
-    from = `${col?.label ?? 'Posts'}${v.tag ? ` tagged “${v.tag}”` : ''}`;
+    from = `${col?.label ?? 'Posts'}${tagged}`;
     picker = (
       <>
         <select id={id} aria-label="Collection" value={String(v.collection ?? 'posts')} onChange={(e) => set({ collection: e.target.value === 'posts' ? '' : e.target.value })}>
           {targets.collections.map((c) => <option key={c.key} value={c.key}>{c.label}</option>)}
         </select>
-        <select aria-label="Tag" value={String(v.tag ?? '')} onChange={(e) => set({ tag: e.target.value })}>
-          <option value="">Any tag</option>
-          {targets.tags.map((t) => <option key={t} value={t}>{t}</option>)}
-        </select>
+        {tagPickers(targets.tags)}
       </>
     );
   } else {

package/src/lib/calendar/cards.ts

@@ -2,7 +2,7 @@
 // block (data-dyn="events"), the /calendar page and embeds. Stable
 // .pc-ev-card* classes are the styling API, like .pc-cal-* for the grid.
 import type { ContentRepository } from '../repo/types';
-import type { CalEvent, Settings } from '../schema';
+import { tagFilter, type CalEvent, type Settings } from '../schema';
 import { siteLocale } from '../dates';
 import { eventImage } from './images';
 import { eventUrl } from './config';
@@ -62,21 +62,23 @@ export function eventCardHtml(
   );
 }
 
-// next occurrence of each distinct event, soonest first
+// next occurrence of each distinct event, soonest first; tag/excludeTag
+// narrow by event tag (name or slug, any case)
 export async function upcomingEvents(
   repo: ContentRepository,
   settings: Settings,
   now: number,
-  opts: { calendarIds?: string[]; limit: number; horizonDays?: number }
+  opts: { calendarIds?: string[]; limit: number; horizonDays?: number; tag?: string; excludeTag?: string }
 ) {
   const tz = settings.timezone || 'UTC';
+  const tagged = tagFilter(opts.tag, opts.excludeTag);
   const { events } = await collectViewEvents(repo, settings, {
     displayTz: tz, now, windowStartMs: now, windowEndMs: now + (opts.horizonDays ?? 400) * 86_400_000,
   }, { audience: 'public', calendarIds: opts.calendarIds, includeFeeds: false });
   const seen = new Set<string>();
   const out: Pick<Occurrence, 'event' | 'start' | 'end' | 'allDay' | 'days' | 'cancelled'>[] = [];
   for (const v of events) {
-    if (!v.event || v.end <= now || seen.has(v.event.id)) continue;
+    if (!v.event || v.end <= now || seen.has(v.event.id) || !tagged(v.event.tags)) continue;
     seen.add(v.event.id);
     out.push({ event: v.event, start: v.start, end: v.end, allDay: v.allDay, days: v.days, cancelled: Boolean(v.cancelled) });
     if (out.length >= opts.limit) break;

package/src/lib/mobile/calendar.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import type { ContentRepository } from '../repo/types';
-import type { BookingLink, CalEvent, Calendar, Resource, Settings } from '../schema';
+import { publicTags, tagFilter, type BookingLink, type CalEvent, type Calendar, type Resource, type Settings } from '../schema';
 import { ApiError } from '../api';
 import { CALENDAR, bookingsEnabled, resourceUrl, bookingLinkUrl, publicEventFields } from '../calendar/config';
 import { calendarToJson, eventToJson } from '../calendar/api';
@@ -23,7 +23,9 @@ export async function listCalendars(repo: ContentRepository, url: URL) {
   const origin = siteOrigin(await repo.getSettings(), url);
   return { calendars: (await repo.listCalendars()).filter(c => c.visibility === 'public').map(c => calendarToJson(c, origin)) };
 }
-export const eventsQuery = z.object({ ...pageQuery, locale: localeQuery, from: isoDayOrInstant.optional(), to: isoDayOrInstant.optional(), calendar: z.string().min(1).max(200).optional(), q: z.string().max(100).optional() }).strict();
+// tag/excludeTag: a public tag's name or slug (internal "#" tags are never matched, as they are never shown)
+export const eventsQuery = z.object({ ...pageQuery, locale: localeQuery, from: isoDayOrInstant.optional(), to: isoDayOrInstant.optional(), calendar: z.string().min(1).max(200).optional(),
+  tag: z.string().min(1).max(100).optional(), excludeTag: z.string().min(1).max(100).optional(), q: z.string().max(100).optional() }).strict();
 export async function listEvents(repo: ContentRepository, url: URL) {
   requireCalendar();
   const q = eventsQuery.parse(queryParams(url));
@@ -44,7 +46,9 @@ export async function listEvents(repo: ContentRepository, url: URL) {
   const cal = q.calendar ? calendars.find(c => c.slug === q.calendar && c.visibility !== 'private') : null;
   if (q.calendar && !cal) throw new ApiError(404, 'Calendar not found.');
   const publicCalendars = new Map(calendars.filter(c => c.visibility === 'public' || c.id === cal?.id).map(c => [c.id, c]));
+  const tagged = tagFilter(q.tag, q.excludeTag);
   const visible = events.map(e => localizeDoc(e, locale ?? undefined)).filter(e => (cal ? e.calendarIds.includes(cal.id) && eventIsPublic(e, all) : eventIsListed(e, all))
+    && tagged(publicTags(e.tags))
     && (!term || indexed!.has(e.id) || `${e.title} ${e.excerpt} ${e.location.name}`.toLowerCase().includes(term.toLowerCase())));
   const occurrences = expandEvents(visible, settings, { displayTz: settings.timezone || 'UTC', now: Date.now(), windowStartMs: from, windowEndMs: to });
   occurrences.sort((a, b) => a.start - b.start || (a.event.id < b.event.id ? -1 : a.event.id > b.event.id ? 1 : 0));

package/src/lib/schema.ts

@@ -155,6 +155,18 @@ export type Post = z.infer<typeof Post>;
 // and for post-list blocks.
 export const isInternalTag = (name: string) => name.startsWith('#');
 export const publicTags = (names: string[]) => names.filter((n) => !isInternalTag(n));
+// Filters name a tag by its name (any case) or its slug: "Bible Study",
+// "bible study" and "bible-study" all match a "Bible Study" tag. Internal
+// tags match by name only, so "class" never picks up "#class".
+export function hasTag(names: string[], wanted: string): boolean {
+  const w = wanted.trim().toLowerCase();
+  if (!w) return false;
+  const slug = /^[a-z0-9-]+$/.test(w);
+  return names.some((n) => n.trim().toLowerCase() === w || (slug && !isInternalTag(n.trim()) && slugify(n) === w));
+}
+/** only `tag` (when set), never `excludeTag` (when set) */
+export const tagFilter = (tag?: string, excludeTag?: string) => (names: string[]) =>
+  (!tag?.trim() || hasTag(names, tag)) && (!excludeTag?.trim() || !hasTag(names, excludeTag));
 
 export const MediaVariant = z.object({ w: z.number(), key: z.string() });
 export type MediaVariant = z.infer<typeof MediaVariant>;

package/src/lib/section-targets.ts

@@ -18,6 +18,8 @@ export interface SectionTargets {
   calendars: { slug: string; name: string }[];
   collections: { key: string; label: string }[];
   tags: string[];
+  /** tags on published events (the events source picks from these) */
+  eventTags: string[];
   resources: { slug: string; name: string }[];
   features: { events: boolean; bookings: boolean };
   /** AI help for text fields: provider configured + languages to translate into */
@@ -26,6 +28,13 @@ export interface SectionTargets {
   i18n: { defaultLocale: string; locales: { code: string; name: string }[]; drafts: boolean };
 }
 
+// one entry per tag, ignoring case (the first spelling wins), A–Z
+function uniqueTags(names: string[]) {
+  const seen = new Map<string, string>();
+  for (const n of names.map((x) => x.trim()).filter(Boolean)) if (!seen.has(n.toLowerCase())) seen.set(n.toLowerCase(), n);
+  return [...seen.values()].sort((a, b) => a.localeCompare(b));
+}
+
 export async function sectionTargets(repo: ContentRepository, locals?: unknown): Promise<SectionTargets> {
   const bookings = bookingsEnabled();
   const settings = await repo.getSettings();
@@ -54,6 +63,7 @@ export async function sectionTargets(repo: ContentRepository, locals?: unknown):
     calendars: calendars.filter((c) => c.visibility !== 'private').map((c) => ({ slug: c.slug, name: c.name })),
     collections: Object.entries(CONTENT.collections).map(([key, c]) => ({ key, label: c.plural })),
     tags: [...new Set(tags.map((t) => t.name))].sort((a, b) => a.localeCompare(b)),
+    eventTags: uniqueTags(events.flatMap((e) => e.tags)),
     resources: publicResources.map((r) => ({ slug: r.slug, name: r.name })),
     features: { events: CALENDAR.enabled, bookings },
     ai: { enabled: Boolean(settings.ai.enabled && settings.ai.model), languages: languageNames() },

package/src/lib/sections.ts

@@ -1,7 +1,7 @@
 import sanitizeHtml from 'sanitize-html';
 import type { z } from 'zod';
 import type { ContentRepository } from './repo/types';
-import { authorSlug, type Settings, type User } from './schema';
+import { authorSlug, tagFilter, type Settings, type User } from './schema';
 import { htmlToPlaintext } from './plaintext';
 import type { SectionInstance as SectionInstanceSchema, SectionDefinition } from '../theme-sdk/contract.mjs';
 import { normalizeData, safeUrl, SOURCE_LIMIT_MAX, isEmptyValue, safeFocus, focusKey } from '../theme-sdk/fields.mjs';
@@ -21,7 +21,8 @@ import { localizeDoc, isExtraLocale } from './translations';
 //   • migrations/<type>.mjs upgrades older instances on the fly
 //   • link fields resolve their ref (page/post/event/booking) to today's URL
 //   • richtext is sanitized
-//   • source fields ("next 3 Youth events") become fresh item arrays
+//   • source fields ("next 3 Youth events", "events not tagged Class") become
+//     fresh item arrays
 
 type Instance = z.infer<typeof SectionInstanceSchema>;
 type Definition = z.infer<typeof SectionDefinition>;
@@ -121,7 +122,7 @@ function resolveScalar(field: FieldDef, value: unknown, refs: RefMap, lp: Lp = s
 }
 
 async function resolveSource(field: Extract<FieldDef, { type: 'source' }>, value: unknown, ctx: ResolveContext): Promise<unknown[]> {
-  const cfg = (value ?? {}) as { calendar?: string; collection?: string; tag?: string; resource?: string; limit?: number };
+  const cfg = (value ?? {}) as { calendar?: string; collection?: string; tag?: string; excludeTag?: string; resource?: string; limit?: number };
   const limit = Math.max(1, Math.min(SOURCE_LIMIT_MAX, Number(cfg.limit) || 3));
   const { repo, settings, now } = ctx;
   // another language (settings.locale is set to it by the renderer)
@@ -137,7 +138,7 @@ async function resolveSource(field: Extract<FieldDef, { type: 'source' }>, value
     }
     const tz = settings.timezone || 'UTC';
     const locale = siteLocale(settings);
-    return (await upcomingEvents(repo, settings, now, { calendarIds, limit })).map((o): EventItem => {
+    return (await upcomingEvents(repo, settings, now, { calendarIds, limit, tag: cfg.tag, excludeTag: cfg.excludeTag })).map((o): EventItem => {
       const e = lang ? localizeDoc(o.event, lang) : o.event;
       const f = formatOccurrence(o, tz, locale);
       const ctaHref = safeUrl(e.cta.href);
@@ -152,7 +153,8 @@ async function resolveSource(field: Extract<FieldDef, { type: 'source' }>, value
   if (field.source === 'posts') {
     const collection = cfg.collection && CONTENT.collections[cfg.collection] ? cfg.collection : 'posts';
     let posts = await repo.listPublishedPosts(collection);
-    if (cfg.tag) posts = posts.filter((p) => p.tags.some((t) => t.toLowerCase() === cfg.tag!.toLowerCase()));
+    const tagged = tagFilter(cfg.tag, cfg.excludeTag);
+    posts = posts.filter((p) => tagged(p.tags));
     const shown = posts.slice(0, limit);
     // public byline only: name, profile URL, avatar — never emails or roles
     const users = shown.some((p) => p.authorIds.length || p.authorId) ? new Map((await repo.listUsers()).map((u) => [u.id, u])) : new Map();

package/src/pages/api/calendar/events/index.ts

@@ -14,14 +14,16 @@ import { readJson } from '../../../../lib/api';
 import { runAgentTool } from '../../../../lib/agent';
 import { waitUntilFrom } from '../../../../lib/webhooks';
 import { fail } from '../../../../lib/calendar/http';
+import { publicTags, tagFilter } from '../../../../lib/schema';
 
 // Public read API for other sites, apps and lobby screens.
 //   GET /api/calendar/events?from=2026-10-01&to=2026-10-31&calendar=youth&q=night
+//   GET /api/calendar/events?tag=class (or excludeTag=class; a tag's name or slug)
 //   → { timezone, from, to, occurrences: [{ id, start, end, allDay, cancelled, event }] }
 //   GET /api/calendar/events?expand=0 → { events: [...] } (rules, not instances)
 // Anonymous callers see public calendars (and an unlisted one when asked by
 // slug). A key with events:read also sees private calendars and private
-// custom fields.
+// custom fields, and its tag filters also match internal "#" tags.
 const CORS = {
   'Access-Control-Allow-Origin': '*',
   'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
@@ -55,6 +57,11 @@ export const GET: APIRoute = async ({ request, locals, url }) => {
       return full ? true : eventIsListed(e, map);
     });
     if (q) events = events.filter((e) => `${e.title} ${e.excerpt} ${e.location.name}`.toLowerCase().includes(q));
+    const tag = url.searchParams.get('tag')?.slice(0, 100), excludeTag = url.searchParams.get('excludeTag')?.slice(0, 100);
+    if (tag || excludeTag) {
+      const tagged = tagFilter(tag, excludeTag);
+      events = events.filter((e) => tagged(full ? e.tags : publicTags(e.tags)));
+    }
 
     if (url.searchParams.get('expand') === '0') {
       return withCors(json({ timezone: tz, events: events.map((e) => eventToJson(e, origin, map, settings.timezone, { includePrivate: full })) }));

package/src/server/index.ts

@@ -44,6 +44,10 @@ export interface ListEventsOptions {
   calendar?: string;
   /** only events this Team member hosts (CalEvent.hostIds) */
   hostedBy?: string;
+  /** only events with this tag (name or slug, any case) */
+  tag?: string;
+  /** leave out events with this tag (name or slug, any case) */
+  excludeTag?: string;
 }
 
 export interface OccurrenceWindow {
@@ -52,6 +56,10 @@ export interface OccurrenceWindow {
   /** window start and end, as a Date or Unix milliseconds; at most 400 days */
   from: Date | number;
   to: Date | number;
+  /** only events with this tag (name or slug, any case) */
+  tag?: string;
+  /** leave out events with this tag (name or slug, any case) */
+  excludeTag?: string;
 }
 
 /** Where a write came from: used for webhook URLs and background work. */
@@ -108,6 +116,10 @@ export async function listEvents(repo: Repo, opts: ListEventsOptions = {}): Prom
     events = events.filter((e) => e.calendarIds.includes(cal.id));
   }
   if (opts.hostedBy) events = events.filter((e) => e.hostIds.includes(opts.hostedBy!));
+  if (opts.tag || opts.excludeTag) {
+    const tagged = (await import('../lib/schema')).tagFilter(opts.tag, opts.excludeTag);
+    events = events.filter((e) => tagged(e.tags));
+  }
   return events;
 }
 
@@ -126,7 +138,7 @@ export async function listOccurrences(repo: Repo, window: OccurrenceWindow): Pro
   if (!Number.isFinite(from) || !Number.isFinite(to) || to <= from) throw new RangeError('listOccurrences needs a "to" after "from".');
   if (to - from > MAX_WINDOW) throw new RangeError('listOccurrences windows are at most 400 days.');
   const r = internal(repo);
-  const [{ expandEvents }, settings] = await Promise.all([import('../lib/calendar/events'), r.getSettings()]);
+  const [{ expandEvents }, { tagFilter }, settings] = await Promise.all([import('../lib/calendar/events'), import('../lib/schema'), r.getSettings()]);
   let events: CalEvent[];
   if (window.eventId) {
     const e = await r.getEvent(window.eventId);
@@ -134,7 +146,8 @@ export async function listOccurrences(repo: Repo, window: OccurrenceWindow): Pro
   } else {
     events = (await r.listEvents()).filter((e) => e.status !== 'archived');
   }
-  return expandEvents(events, settings, { displayTz: settings.timezone || 'UTC', now: Date.now(), windowStartMs: from, windowEndMs: to });
+  const tagged = tagFilter(window.tag, window.excludeTag);
+  return expandEvents(events.filter((e) => tagged(e.tags)), settings, { displayTz: settings.timezone || 'UTC', now: Date.now(), windowStartMs: from, windowEndMs: to });
 }
 
 /**

package/src/theme-sdk/calendar.ts

@@ -20,6 +20,10 @@ export interface UpcomingEventsOptions {
   limit?: number;
   /** Look-ahead window in days; defaults to 400. */
   horizonDays?: number;
+  /** Only events with this tag (name or slug, any case). */
+  tag?: string;
+  /** Leave out events with this tag (name or slug, any case). */
+  excludeTag?: string;
 }
 
 /**
@@ -32,7 +36,7 @@ export type UpcomingEvent = Pick<Occurrence, 'event' | 'start' | 'end' | 'allDay
 /** Server-side helper for Astro templates and endpoints. No repository access needed. */
 export async function upcomingEvents(
   context: { locals: unknown },
-  { limit = 6, horizonDays = 400 }: UpcomingEventsOptions = {},
+  { limit = 6, horizonDays = 400, tag, excludeTag }: UpcomingEventsOptions = {},
 ): Promise<UpcomingEvent[]> {
   if (!Number.isSafeInteger(limit) || limit < 0) {
     throw new RangeError('upcomingEvents limit must be a non-negative safe integer');
@@ -48,5 +52,5 @@ export async function upcomingEvents(
   ]);
   const repo = await getRepo(context.locals);
   const settings = await repo.getSettings();
-  return loadUpcomingEvents(repo, settings, Date.now(), { limit, horizonDays });
+  return loadUpcomingEvents(repo, settings, Date.now(), { limit, horizonDays, tag, excludeTag });
 }

package/src/theme-sdk/fields.mjs

@@ -7,7 +7,8 @@
 //   number → number        toggle → boolean
 //   link   → { label, href, ref? }   (ref = 'page:<id>' | 'post:<id>' | 'event:<id>' | 'booking:<id>')
 //   list   → Array<Record<subKey, scalar | link>>
-//   source → { calendar?, collection?, tag?, resource?, limit? }  (resolved to items at render time)
+//   source → { calendar?, collection?, tag?, excludeTag?, resource?, limit? }  (resolved to items at render time;
+//            tags are names or slugs, for events and posts)
 
 export const SCALAR_TYPES = /** @type {const} */ (['text', 'textarea', 'richtext', 'image', 'url', 'link', 'select', 'number', 'toggle', 'date', 'time']);
 export const SOURCE_KINDS = /** @type {const} */ (['events', 'posts', 'bookings']);
@@ -218,9 +219,13 @@ export function valueIssues(field, value, path = field.label) {
       if (!isObject(value)) return bad();
       const limit = value.limit ?? 3;
       if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > SOURCE_LIMIT_MAX) return bad(`${field.label}: show between 1 and ${SOURCE_LIMIT_MAX}`);
-      for (const k of ['calendar', 'collection', 'tag', 'resource']) {
+      for (const k of ['calendar', 'collection', 'resource']) {
         if (value[k] !== undefined && (typeof value[k] !== 'string' || !/^[a-z0-9-]{0,100}$/i.test(value[k]))) return bad();
       }
+      // tag names, like "Bible Study" or "#class"
+      for (const k of ['tag', 'excludeTag']) {
+        if (value[k] !== undefined && (typeof value[k] !== 'string' || value[k].length > 100 || /[\u0000-\u001f\u007f]/.test(value[k]))) return bad();
+      }
       return [];
     }
     default: return typeof value === 'string' ? [] : bad();