@inneropen/marvin-astro 1.1.0 → 1.2.0

package/src/fields.ts

@@ -0,0 +1,330 @@
+/**
+ * The field accessor handed to a repository's `transform`.
+ *
+ * Every reader defaults to the documented precedence — `data_json` first, `metadata_json`
+ * second — so a transform reads like a field list instead of a pile of coalescing operators.
+ */
+
+import { entryEmbeds, findEmbed, type MarvinEmbed } from './embeds.js';
+import type { MarkdownRenderer } from './markdown.js';
+import { preserveSoftBreaks } from './markdown.js';
+import {
+  asNumber,
+  asRecord,
+  asString,
+  asStringArray,
+  assetAlt,
+  assetField,
+  assetUrl,
+  collectionRole,
+  collectionSlugs,
+  entryAssets,
+  entryData,
+  entryMetadata,
+  entryResources,
+  field,
+  focalPoint,
+  resourceField,
+  selectAssetByRole,
+  selectFeaturedAsset,
+  selectIconAsset,
+  selectImageAsset,
+} from './normalize.js';
+import { formatDisplayDate } from './format.js';
+import type {
+  ApiImage,
+  ApiResourceLink,
+  AssetSelectOptions,
+  MarvinContentEntry,
+} from './types.js';
+
+export type ImageFieldOptions = Omit<AssetSelectOptions, 'type' | 'types'> & {
+  /**
+   * Exact roles to prefer, in order, before the looser role/usage match. Use for derived
+   * variants — e.g. `['hero-grade']` to prefer a colour-graded hero over the raw upload.
+   */
+  preferRoles?: string[];
+  /** `metadata_json` key holding a hand-authored `{src, alt, focalPoint}`. */
+  metadataKey?: string | false;
+  /** Alt text when the asset carries none. Defaults to the entry title. */
+  alt?: string;
+  /** Fall back to the list item's `featuredAsset`. Default `true`. */
+  fallbackToFeatured?: boolean;
+};
+
+export type IconFieldOptions = {
+  roles?: string[];
+  /** Fall back to the list item's `featuredAsset` when no icon asset is attached. */
+  fallbackToFeatured?: boolean;
+};
+
+export type MarkdownFieldOptions = {
+  /** Keep authored single newlines as hard breaks. Default `false`. */
+  softBreaks?: boolean;
+  /**
+   * Render a bare provider URL on its own line as its player, using the entry's `embeds`.
+   * Default `true`; `false` keeps every URL a plain link.
+   */
+  embeds?: boolean;
+};
+
+export type ResourceFieldOptions = {
+  /** Keep only these resource types, e.g. `['material', 'construction']`. */
+  types?: string[];
+  /** Keep only resources attached with this role. */
+  role?: string;
+  /** Build an href from the resource slug. */
+  href?: (slug: string) => string;
+};
+
+const DEFAULT_IMAGE_ROLES = ['hero', 'featured', 'card'];
+
+export type FieldAccessor = ReturnType<typeof createFieldAccessor>;
+
+export type FieldAccessorContext = {
+  renderMarkdown: MarkdownRenderer;
+  /** The route this entry resolves to, if the repository was given an `href` builder. */
+  href?: string;
+  /** The collection the entry was loaded from, when it came from one. */
+  collection?: string;
+};
+
+export function createFieldAccessor(
+  entry: MarvinContentEntry,
+  context: FieldAccessorContext
+) {
+  const title = asString((entry as { title?: unknown }).title);
+  const embeds = entryEmbeds(entry);
+
+  const accessor = {
+    /** The entry itself, for anything the accessor doesn't cover. */
+    entry,
+    /** The route this entry resolves to (from the repository's `href` option). */
+    href: context.href,
+    collection: context.collection,
+
+    /** `data_json` → `metadata_json`, untyped. */
+    raw(key: string): unknown {
+      return field(entry, key);
+    },
+
+    string(key: string): string | undefined {
+      return asString(field(entry, key));
+    },
+
+    number(key: string): number | undefined {
+      return asNumber(field(entry, key));
+    },
+
+    /** Booleans authored as strings (`"true"`, `"1"`, `"yes"`) read as booleans. */
+    bool(key: string): boolean {
+      const value = field(entry, key);
+      if (typeof value === 'boolean') return value;
+      if (typeof value === 'string') {
+        return ['true', '1', 'yes', 'on'].includes(value.trim().toLowerCase());
+      }
+      if (typeof value === 'number') return value !== 0;
+      return Boolean(value);
+    },
+
+    /** A string array, tolerating a single string authored in place of a list. */
+    list(key: string): string[] | undefined {
+      const value = field(entry, key);
+      const array = asStringArray(value);
+      if (array) return array;
+      const single = asString(value);
+      return single ? [single] : undefined;
+    },
+
+    /**
+     * An enum-guarded read: the value if it's in `allowed`, else `fallback`. Replaces the
+     * per-field `normalizeStatus`/`normalizeCategory`/`normalizeTone` guards that every site
+     * ends up writing.
+     */
+    oneOf<T extends string>(key: string, allowed: readonly T[] | Set<T>, fallback: T): T {
+      const value = asString(field(entry, key));
+      const set = allowed instanceof Set ? allowed : new Set<string>(allowed);
+      return value && set.has(value as T) ? (value as T) : fallback;
+    },
+
+    /** A field read as a display date ("Mon DD, YYYY"); already-formatted values pass through. */
+    date(key: string): string | undefined {
+      return formatDisplayDate(asString(field(entry, key)));
+    },
+
+    /** The raw ISO publish timestamp, if any. */
+    publishedAt(): string | undefined {
+      const value = (entry as { publishedAt?: unknown }).publishedAt;
+      return value != null ? String(value) : undefined;
+    },
+
+    /**
+     * Render a markdown field to HTML. Falls back to the entry's `contentMarkdown` when the
+     * named field is absent. Returns `undefined` when there is nothing to render, so the
+     * caller can omit the property rather than emit an empty string.
+     */
+    async markdown(
+      key = 'body',
+      options: MarkdownFieldOptions = {}
+    ): Promise<string | undefined> {
+      const raw =
+        field<string | string[]>(entry, key) ??
+        (entry as { contentMarkdown?: string | string[] }).contentMarkdown;
+      const source = Array.isArray(raw) ? raw.join('\n\n') : asString(raw);
+      if (!source) return undefined;
+      return context.renderMarkdown(options.softBreaks ? preserveSoftBreaks(source) : source, {
+        embeds: options.embeds === false ? undefined : embeds,
+      });
+    },
+
+    /**
+     * The resolved embed for an `embed` field (its value is the provider URL), or `undefined`
+     * when the field is empty or the server hasn't resolved it. Render it with `<Embed>` from
+     * `@inneropen/marvin-astro/components`, or output `embed.html`.
+     */
+    embed(key: string): MarvinEmbed | undefined {
+      return findEmbed(embeds, asString(field(entry, key)));
+    },
+
+    /**
+     * The entry's primary image. Checks, in order: a hand-authored `metadata_json.featuredImage`,
+     * the exact `preferRoles`, a role/usage match over the entry's image assets, and finally the
+     * list item's `featuredAsset`.
+     */
+    image(options: ImageFieldOptions = {}): ApiImage | undefined {
+      const {
+        preferRoles,
+        metadataKey = 'featuredImage',
+        alt: altFallback,
+        fallbackToFeatured = true,
+        roles = DEFAULT_IMAGE_ROLES,
+        usages = DEFAULT_IMAGE_ROLES,
+        allowUnroled = true,
+        ...rest
+      } = options;
+      const fallbackAlt = altFallback ?? title ?? '';
+
+      if (metadataKey) {
+        const authored = asRecord(entryMetadata(entry)[metadataKey]);
+        const src = asString(authored.src);
+        if (src) {
+          return {
+            src,
+            alt: asString(authored.alt) ?? fallbackAlt,
+            focalPoint: focalPoint(authored.focalPoint),
+          };
+        }
+      }
+
+      const asset =
+        (preferRoles?.length ? selectAssetByRole(entry, ...preferRoles) : undefined) ??
+        selectImageAsset(entry, { ...rest, roles, usages, allowUnroled }) ??
+        (fallbackToFeatured ? selectFeaturedAsset(entry) : undefined);
+
+      const src = assetUrl(asset);
+      if (!src) return undefined;
+
+      return {
+        src,
+        alt: assetAlt(asset, fallbackAlt) ?? fallbackAlt,
+        focalPoint: focalPoint(assetField(asset, 'focalPoint')),
+      };
+    },
+
+    /** URL of the entry's icon asset (`role: icon`, SVG preferred). */
+    icon(options: IconFieldOptions = {}): string | undefined {
+      const { roles = ['icon'], fallbackToFeatured = false } = options;
+      const asset = selectAssetByRole(entry, ...roles) ?? selectIconAsset(entry);
+      return (
+        assetUrl(asset) ?? (fallbackToFeatured ? assetUrl(selectFeaturedAsset(entry)) : undefined)
+      );
+    },
+
+    /** The raw asset placement matching `options` — when you need more than src/alt/focal. */
+    asset(options: AssetSelectOptions = {}): Record<string, unknown> | undefined {
+      return selectImageAsset(entry, options) ?? selectFeaturedAsset(entry);
+    },
+
+    /** The asset whose role is EXACTLY one of `roles`, in preference order. */
+    assetByRole(...roles: string[]): Record<string, unknown> | undefined {
+      return selectAssetByRole(entry, ...roles);
+    },
+
+    /** All asset placements on the entry. */
+    assets(): Record<string, unknown>[] {
+      return entryAssets(entry);
+    },
+
+    /** Every image asset resolved, filtered by role/usage — support/detail galleries. */
+    images(options: ImageFieldOptions = {}): (ApiImage & { usage?: string })[] {
+      const wanted = new Set([...(options.roles ?? []), ...(options.usages ?? [])]);
+      const fallbackAlt = options.alt ?? title ?? '';
+      const images: (ApiImage & { usage?: string })[] = [];
+
+      for (const asset of entryAssets(entry)) {
+        const usage = asString(assetField(asset, 'usage')) ?? asString(assetField(asset, 'role'));
+        const src = assetUrl(asset);
+        if (!src) continue;
+        if (wanted.size > 0 && (!usage || !wanted.has(usage))) continue;
+
+        images.push({
+          src,
+          alt: assetAlt(asset, fallbackAlt) ?? fallbackAlt,
+          focalPoint: focalPoint(assetField(asset, 'focalPoint')),
+          usage,
+        });
+      }
+
+      return images;
+    },
+
+    /** Attached resources, normalized to name/type/role/href. */
+    resources(options: ResourceFieldOptions = {}): ApiResourceLink[] {
+      const types = options.types?.length ? new Set(options.types) : undefined;
+
+      return entryResources(entry)
+        .map((relationship) => {
+          const nested = asRecord(relationship.resource);
+          const source = Object.keys(nested).length > 0 ? nested : relationship;
+          const slug = asString(resourceField(source, 'slug'));
+          return {
+            name: asString(resourceField(source, 'name')) ?? '',
+            type: asString(resourceField(source, 'resourceType')) ?? '',
+            role: asString(assetField(relationship, 'role')),
+            slug,
+            href: slug && options.href ? options.href(slug) : undefined,
+          };
+        })
+        .filter((resource) => Boolean(resource.name))
+        .filter((resource) => !types || types.has(resource.type))
+        .filter((resource) => !options.role || resource.role === options.role);
+    },
+
+    /** The first attached resource matching `options`. */
+    resource(options: ResourceFieldOptions = {}): ApiResourceLink | undefined {
+      return accessor.resources(options)[0];
+    },
+
+    /** The `metadata_json` blob. */
+    metadata(): Record<string, unknown> {
+      return entryMetadata(entry);
+    },
+
+    /** The `data_json` blob. Empty on a list item that was not hydrated. */
+    data(): Record<string, unknown> {
+      return entryData(entry);
+    },
+
+    /** Slugs of every collection the entry belongs to. */
+    collections(): string[] {
+      return collectionSlugs(entry);
+    },
+
+    /** The entry's membership role within `collectionSlug`. */
+    role(collectionSlug: string): string | undefined {
+      return collectionRole(entry, collectionSlug);
+    },
+  };
+
+  return accessor;
+}

package/src/format.ts

@@ -0,0 +1,63 @@
+const MONTHS = [
+  'Jan',
+  'Feb',
+  'Mar',
+  'Apr',
+  'May',
+  'Jun',
+  'Jul',
+  'Aug',
+  'Sep',
+  'Oct',
+  'Nov',
+  'Dec',
+];
+
+/**
+ * Format a date value for display as "Mon DD, YYYY".
+ *
+ * ISO dates/timestamps (e.g. a raw `publishedAt` like "2026-07-21T21:22:42.045708Z") are read in
+ * UTC — via the date part only, so there's no off-by-one day shift from the viewer's timezone.
+ * Values that are already human-readable (e.g. a hand-entered "Jul 02, 2024") pass through
+ * unchanged, and empty input returns `undefined` so callers can omit the field.
+ */
+export function formatDisplayDate(value: string | null | undefined): string | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+
+  const iso = /^(\d{4})-(\d{2})-(\d{2})/.exec(trimmed);
+  if (iso) {
+    const [, year, month, day] = iso;
+    const name = MONTHS[Number(month) - 1];
+    if (name) return `${name} ${day}, ${year}`;
+  }
+
+  return trimmed;
+}
+
+/**
+ * Pick `count` items deterministically from `items`, seeded by `pageSlug`.
+ *
+ * Same page → same selection on every build, different pages → different selections. Use for
+ * rotating pull-quotes, value bands, related links: variety across the site without the
+ * hydration mismatch a random pick would cause.
+ */
+export function selectValuesForPage<T>(items: T[], pageSlug: string, count = 4): T[] {
+  const seeded = [...items];
+  let seed = 0;
+
+  for (const character of pageSlug) {
+    seed = (seed * 31 + character.charCodeAt(0)) >>> 0;
+  }
+
+  for (let index = seeded.length - 1; index > 0; index -= 1) {
+    seed = (seed * 1664525 + 1013904223) >>> 0;
+
+    const target = seed % (index + 1);
+
+    [seeded[index], seeded[target]] = [seeded[target], seeded[index]];
+  }
+
+  return seeded.slice(0, count);
+}

package/src/index.ts

@@ -0,0 +1,169 @@
+/**
+ * `@inneropen/marvin-astro` — site integration for Marvin CMS.
+ *
+ * Sits above `@inneropen/marvin-sdk` (transport). This layer is the part every Marvin-backed site
+ * rewrites: repositories with a static fallback, site chrome from collections, and payload
+ * normalization. Astro components (forms, media embeds, entry-type renderers) live under
+ * `@inneropen/marvin-astro/components`.
+ *
+ * ```ts
+ * // src/lib/content.ts
+ * export const marvin = createMarvinContent({ site: { fallback: staticSite } });
+ *
+ * export const posts = marvin.repository({
+ *   collections: ['bench-notes', 'journal', 'blog'],
+ *   hydrate: true,
+ *   href: (slug) => `/bench-notes/${slug}`,
+ *   fallback: () => staticPosts,
+ *   transform: async (entry, f) => ({
+ *     slug: entry.slug,
+ *     title: entry.title ?? 'Untitled',
+ *     noteNumber: f.string('noteNumber'),
+ *     bodyHtml: await f.markdown('body'),
+ *     image: f.image({ roles: ['hero', 'featured', 'card'] }),
+ *   }),
+ * });
+ * ```
+ */
+
+import { createBackend } from './client.js';
+import { createChromeLoader, type ChromeOptions } from './chrome.js';
+import { createFetcher } from './fetch.js';
+import { createMarkdownRenderer } from './markdown.js';
+import { createRepository, type Repository, type RepositoryOptions } from './repository.js';
+import { loadSectionLanding, type SectionLandingOptions } from './sections.js';
+import { createSiteLoader, type SiteOptions } from './site.js';
+import type { MarvinAstroConfig } from './config.js';
+import type { ApiSite, ApiSiteChrome, SectionLanding } from './types.js';
+
+export type MarvinContentOptions = MarvinAstroConfig & {
+  site?: SiteOptions;
+  chrome?: ChromeOptions;
+};
+
+export type MarvinContent = ReturnType<typeof createMarvinContent>;
+
+/**
+ * Build the content layer for one Marvin workspace.
+ *
+ * Connection settings come from `MARVIN_API_URL`, `MARVIN_SITE_CLIENT_TOKEN` and
+ * `MARVIN_WORKSPACE_SLUG` unless passed explicitly. Everything returned degrades to its static
+ * fallback when the backend is unreachable, so a site still builds offline.
+ */
+export function createMarvinContent(options: MarvinContentOptions = {}) {
+  const backend = createBackend(options);
+  const fetcher = createFetcher(backend);
+  const renderMarkdown = createMarkdownRenderer(backend.config.markdown);
+  const siteLoader = createSiteLoader(fetcher, options.site);
+  const chromeLoader = createChromeLoader(fetcher, siteLoader, options.chrome);
+  const repositories: Repository<unknown>[] = [];
+
+  return {
+    /** The resolved configuration, with the token still in place — don't log it. */
+    config: backend.config,
+    /** Latch control and the raw SDK client. */
+    backend,
+    /** Guarded, never-throwing wrappers around every published endpoint. */
+    fetch: fetcher,
+    renderMarkdown,
+
+    /** True when Marvin is configured and not currently latched out as unreachable. */
+    hasBackend: () => backend.hasBackend(),
+
+    /** Resolved site identity, SEO and brand assets. Memoized per process. */
+    getSite(): Promise<ApiSite> {
+      return siteLoader.get();
+    },
+
+    /** Navigation, footer, legal, social and inquiry links. Memoized per process. */
+    getSiteChrome(): Promise<ApiSiteChrome> {
+      return chromeLoader.get();
+    },
+
+    /** Title/intro/hero for an index page, driven by a `page` entry of the same slug. */
+    getSectionLanding(slug: string, sectionOptions?: SectionLandingOptions): Promise<SectionLanding> {
+      return loadSectionLanding(fetcher, slug, renderMarkdown, sectionOptions);
+    },
+
+    /** A collection-backed content repository: `all()` / `bySlug()` / `featured()`. */
+    repository<T>(repositoryOptions: RepositoryOptions<T>): Repository<T> {
+      const repository = createRepository<T>({ fetcher, renderMarkdown }, repositoryOptions);
+      repositories.push(repository as Repository<unknown>);
+      return repository;
+    },
+
+    /** Drop every memoized result and re-open the failure latch. */
+    reset() {
+      backend.clearLatch();
+      siteLoader.reset();
+      chromeLoader.reset();
+      for (const repository of repositories) repository.reset();
+    },
+  };
+}
+
+export {
+  createBackend,
+  errorMessage,
+  isNetworkFailure,
+  type MarvinBackend,
+} from './client.js';
+export {
+  DEFAULT_DEV_RETRY_MS,
+  DEFAULT_HYDRATE_CONCURRENCY,
+  ENV_KEYS,
+  describeConfig,
+  readEnv,
+  resolveConfig,
+  type MarvinAstroConfig,
+  type MarvinLogger,
+  type ResolvedConfig,
+} from './config.js';
+export { createFetcher, type HydratedEntry, type MarvinFetcher } from './fetch.js';
+export {
+  createFieldAccessor,
+  type FieldAccessor,
+  type IconFieldOptions,
+  type ImageFieldOptions,
+  type MarkdownFieldOptions,
+  type ResourceFieldOptions,
+} from './fields.js';
+export { formatDisplayDate, selectValuesForPage } from './format.js';
+export {
+  createMarkdownRenderer,
+  preserveSoftBreaks,
+  type MarkdownOptions,
+  type MarkdownRenderer,
+  type RenderMarkdownOptions,
+} from './markdown.js';
+export { entryEmbeds, findEmbed, siteEmbeds } from './embeds.js';
+export * from './normalize.js';
+export {
+  createRepository,
+  type Repository,
+  type RepositoryContext,
+  type RepositoryOptions,
+} from './repository.js';
+export {
+  buildFallbackSite,
+  buildSeo,
+  createSiteLoader,
+  type SiteLoader,
+  type SiteOptions,
+} from './site.js';
+export {
+  createChromeLoader,
+  defaultResolveHref,
+  metadataLink,
+  socialLinkFromKey,
+  toNavigationLink,
+  type ChromeLoader,
+  type ChromeOptions,
+  type HrefContext,
+  type NavigationContext,
+  type NavigationLinkInput,
+  type ResolveHref,
+  type SocialLinkInput,
+} from './chrome.js';
+export { loadSectionLanding, type SectionLandingOptions } from './sections.js';
+export type * from './types.js';

package/src/markdown.ts

@@ -0,0 +1,84 @@
+import { Marked, type MarkedOptions, type Tokens } from 'marked';
+import { findEmbed, type MarvinEmbeds } from './embeds.js';
+
+export type MarkdownOptions = MarkedOptions;
+
+/** Per-call options for a {@link MarkdownRenderer}. */
+export type RenderMarkdownOptions = {
+  /**
+   * The entry's `embeds` map. A paragraph that is exactly a URL with an entry here renders as
+   * that embed's Marvin-built HTML instead of a link.
+   */
+  embeds?: MarvinEmbeds | null;
+};
+
+export type MarkdownRenderer = (
+  markdown: string | string[] | null | undefined,
+  options?: RenderMarkdownOptions
+) => Promise<string>;
+
+// Per-call data rides on marked's parse options: marked merges them over the instance defaults and
+// hands the merged object to the renderer as `this.options` for that parse only. A symbol key
+// keeps it clear of marked's own option names.
+const EMBEDS = Symbol('marvin.embeds');
+type ParseOptionsWithEmbeds = MarkedOptions & { [EMBEDS]?: MarvinEmbeds | null };
+
+// One run of non-space characters starting with a scheme. `<url>`, `[text](url)` and a URL inside
+// a sentence all fail this, so they stay links.
+const BARE_URL = /^https?:\/\/\S+$/i;
+
+/**
+ * The embed for a paragraph that is exactly a URL with an `embeds` entry, else `undefined`.
+ * Exported for tests; the renderer below is the only caller.
+ */
+export function paragraphEmbedHtml(
+  token: Pick<Tokens.Paragraph, 'text'>,
+  embeds: MarvinEmbeds | null | undefined
+): string | undefined {
+  if (!embeds) return undefined;
+  const text = token.text.trim();
+  if (!BARE_URL.test(text)) return undefined;
+  const html = findEmbed(embeds, text)?.html;
+  return typeof html === 'string' && html.trim() ? html : undefined;
+}
+
+/**
+ * A markdown renderer with its own `marked` instance — options are per-site, not global, so two
+ * `createMarvinContent()` instances in one process can't clobber each other's settings.
+ *
+ * `breaks: false` is the default because CMS body copy is authored as prose: a soft-wrapped
+ * paragraph should render as one paragraph. Where authored line breaks must survive (a landing
+ * intro, an address block), pass `breaks: true` or pre-convert with a trailing double space.
+ *
+ * Pass the entry's `embeds` to turn a bare provider URL on its own line into its player:
+ *
+ * ```ts
+ * await renderMarkdown(body, { embeds: entryEmbeds(entry) });
+ * ```
+ */
+export function createMarkdownRenderer(options: MarkdownOptions = {}): MarkdownRenderer {
+  const marked = new Marked();
+  marked.setOptions({ gfm: true, breaks: false, ...options });
+  marked.use({
+    renderer: {
+      paragraph(token) {
+        const embeds = (this.options as ParseOptionsWithEmbeds)[EMBEDS];
+        const html = paragraphEmbedHtml(token, embeds);
+        // `false` hands the token back to marked's default paragraph renderer.
+        return html === undefined ? false : `${html}\n`;
+      },
+    },
+  });
+
+  return async (markdown, renderOptions = {}) => {
+    const source = Array.isArray(markdown) ? markdown.join('\n\n') : (markdown ?? '');
+    if (!source) return '';
+    const parseOptions: ParseOptionsWithEmbeds = { [EMBEDS]: renderOptions.embeds ?? null };
+    return await marked.parse(source, parseOptions);
+  };
+}
+
+/** Turn single newlines into hard breaks, leaving paragraph breaks alone. */
+export function preserveSoftBreaks(source: string): string {
+  return source.replace(/(?<!\n)\n(?!\n)/g, '  \n');
+}