@acms-subir/core 0.3.11 → 0.3.12

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @acms-subir/core
 
+## 0.3.12
+
+### Patch Changes
+
+- 8e70593: Expose upcomingEvents(Astro, options), calendarConfig(), and eventUrl() through the public theme SDK so coded templates can load calendar events without importing internal repository modules. Include public option/result types and migration documentation.
+
 ## 0.3.11
 
 ### Patch Changes

package/docs/theme-authoring.md

@@ -34,6 +34,31 @@ const { page, posts } = Astro.props;
 
 Public types: ChromeProps (site), HomeProps (settings, page, posts, tags), PageProps (settings, page, html), PostProps (settings, post, html, authors, related), EventProps (settings, event, occurrence, calendars, html, upcoming, origin, preview, rsvp), SectionProps (settings, page, variant, data). Public components: PostCard with card/row/feature variants, Pager with base/page/count, TagLabel with name/href/accent. Helpers include collectionUrl, postUrl, postsIndexUrl, tagUrl, formatDate, slugify, authorSlug, localeFromPath, localeHomeUrl and CONTENT. Use collectionUrl for non-default collections; postUrl is the built-in posts alias.
 
+### Upcoming events in coded templates
+
+Use the server-side calendar helpers from the public theme entry point. Replace imports from `@acms-subir/core/lib/repo/*` and `@acms-subir/core/lib/calendar/*`; internal folders are not package exports.
+
+```astro
+---
+import { upcomingEvents, calendarConfig, eventUrl } from '@acms-subir/core/theme';
+const calendar = calendarConfig();
+const upcoming = await upcomingEvents(Astro, { limit: 4, horizonDays: 90 });
+const date = new Intl.DateTimeFormat('en', { dateStyle: 'medium', timeZone: Astro.props.settings.timezone || 'UTC' });
+---
+{calendar.enabled && <section>
+  <a href={calendar.base}>Calendar</a>
+  {upcoming.map(({ event, start }) => (
+    <a href={eventUrl(event.slug)}>
+      {event.title} <time datetime={new Date(start).toISOString()}>{date.format(start)}</time>
+    </a>
+  ))}
+</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.
+
+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.
+
 Template filenames: `home.astro`, `event.astro`, `header.astro`, `footer.astro`, `post-<name>.astro`, `page-<name>.astro`.
 
 `header.astro` and `footer.astro` replace the site header and footer on every public page. They receive `ChromeProps` — one `site` prop (`SiteChrome`) with everything already resolved for the request: `title`, `tagline`, `logo`, `logoDark`, `homeUrl`, `links` (header nav, each `{ label, url, current, external }`, already localized), `footerLinks`, `social` (with inline SVG `icon`), `readLinks`, `footerHtml`, `languages` (`{ code, label, url, current }`, where `label` is the language's own name, e.g. "Español"), `search` (`{ url, label }` or null), `schemeToggle`, `liveHeader`, `headerStyle`, `footerStyle`. Core behaviors attach through data hooks, so keep them on your own elements: `data-search-open` (opens search), `data-scheme-toggle` (light/dark), `data-menu-open` (phone menu sheet, built from `site.links`) and a hidden `data-live-header` link (shown during a live stream).

package/package.json

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

package/src/theme-sdk/calendar.ts

@@ -0,0 +1,48 @@
+import { CALENDAR } from '../lib/calendar/config';
+import type { Occurrence } from '../lib/calendar/events';
+
+export { eventUrl } from '../lib/calendar/config';
+
+export interface ThemeCalendarConfig {
+  enabled: boolean;
+  base: string;
+  eventsBase: string;
+}
+
+/** Public calendar routes configured by the site's integration. */
+export function calendarConfig(): ThemeCalendarConfig {
+  const { enabled, base, eventsBase } = CALENDAR;
+  return { enabled, base, eventsBase };
+}
+
+export interface UpcomingEventsOptions {
+  /** Maximum distinct events; defaults to 6. Zero returns an empty list. */
+  limit?: number;
+  /** Look-ahead window in days; defaults to 400. */
+  horizonDays?: number;
+}
+
+/** Occurrence start/end are Unix milliseconds; event retains its authored fields. */
+export type UpcomingEvent = Pick<Occurrence, 'event' | 'start' | 'end' | 'allDay' | 'days'>;
+
+/** Server-side helper for Astro templates and endpoints. No repository access needed. */
+export async function upcomingEvents(
+  context: { locals: unknown },
+  { limit = 6, horizonDays = 400 }: UpcomingEventsOptions = {},
+): Promise<UpcomingEvent[]> {
+  if (!Number.isSafeInteger(limit) || limit < 0) {
+    throw new RangeError('upcomingEvents limit must be a non-negative safe integer');
+  }
+  if (!Number.isFinite(horizonDays) || horizonDays <= 0) {
+    throw new RangeError('upcomingEvents horizonDays must be a positive finite number');
+  }
+  if (!CALENDAR.enabled || limit === 0) return [];
+
+  const [{ getRepo }, { upcomingEvents: loadUpcomingEvents }] = await Promise.all([
+    import('../lib/repo'),
+    import('../lib/calendar/cards'),
+  ]);
+  const repo = await getRepo(context.locals);
+  const settings = await repo.getSettings();
+  return loadUpcomingEvents(repo, settings, Date.now(), { limit, horizonDays });
+}

package/src/theme-sdk/index.ts

@@ -1,5 +1,7 @@
 export { ThemeTokens, ThemeManifest, PostOptions, SectionDefinition, SectionInstance, SectionLayout, SectionPages, PagePreset, BUILTIN_SECTIONS, sectionDefinitions, sectionIssues, THEME_API_VERSION } from './contract.mjs';
 export { formatTime, formatDay } from './fields.mjs';
+export { upcomingEvents, calendarConfig, eventUrl } from './calendar';
+export type { UpcomingEventsOptions, UpcomingEvent, ThemeCalendarConfig } from './calendar';
 export { CONTENT, postsIndexUrl, postUrl, tagUrl, collectionUrl } from '../lib/content';
 export { formatDate } from '../lib/dates';
 export type { Page, Post, Settings, Tag, CalEvent, Calendar, User } from '../lib/schema';