@sjolystinnovation/app-kit 0.22.0 → 1.0.0

package/src/sections/editors.tsx

@@ -0,0 +1,311 @@
+"use client";
+
+import { PlusIcon, TrashIcon } from "@heroicons/react/24/outline";
+import { useState, type ChangeEvent, type ReactNode } from "react";
+import { toast } from "../toast";
+import { contentImagePath } from "../ui/ContentImage";
+import { TextInput } from "../ui/TextInput";
+import { withDefaults, type TextOverrides } from "../ui/withDefaults";
+import { defaultSectionsEditorStrings, type SectionsEditorStrings } from "./sectionsEditorStrings";
+import type { ContactSection, CtaSection, FeatureSection, FeedSection, HeroSection, ImageSection, StatItem, StatsSection, TextSection } from "./types";
+
+/** How the editor uploads and previews images. */
+export interface SectionImages {
+  /** Uploads the file and resolves to the new image's id. */
+  upload: (file: File) => Promise<{ id: string }>;
+  /** The preview's URL for an image id. Defaults to `contentImagePath`. */
+  src?: ((id: string) => string) | undefined;
+}
+
+/** What an editor for one section type gets. */
+export interface SectionEditorProps<S> {
+  section: S;
+  /** Merges the changes into the section. */
+  patch: (changes: Partial<S>) => void;
+  strings: SectionsEditorStrings;
+  images: SectionImages;
+}
+
+/** Props for `SectionField`. */
+export interface SectionFieldProps {
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+  /** A three-row text area instead of a one-line input. */
+  textarea?: boolean | undefined;
+}
+
+/** A labeled text field for a section editor. */
+export function SectionField({ label, value, onChange, textarea }: SectionFieldProps) {
+  if (textarea) {
+    return (
+      <div>
+        <label className="block text-sm font-medium text-gray-700 mb-1">{label}</label>
+        <textarea
+          rows={3}
+          value={value}
+          onChange={e => onChange(e.target.value)}
+          className="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm text-gray-900 focus:outline-none focus:ring-2 focus:ring-primary"
+        />
+      </div>
+    );
+  }
+  return <TextInput label={label} value={value} onChange={e => onChange(e.target.value)} />;
+}
+
+/** Props for `ImagePicker`. */
+export interface ImagePickerProps {
+  imageId: string | null;
+  onChange: (id: string | null) => void;
+  /** The label above the picker. Defaults to `strings.image`. */
+  label?: string | undefined;
+  images: SectionImages;
+  strings?: TextOverrides<SectionsEditorStrings> | undefined;
+}
+
+/** Uploads an image and shows a preview, with a button to clear it. A failed upload shows a toast. */
+export function ImagePicker({ imageId, onChange, label, images, strings }: ImagePickerProps) {
+  const text = withDefaults(defaultSectionsEditorStrings, strings);
+  const [uploading, setUploading] = useState(false);
+  const src = images.src ?? contentImagePath;
+
+  const handleFile = async (e: ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    e.target.value = "";
+    if (!file) return;
+    setUploading(true);
+    try {
+      const { id } = await images.upload(file);
+      onChange(id);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : text.uploadFailed);
+    } finally {
+      setUploading(false);
+    }
+  };
+
+  return (
+    <div>
+      <label className="block text-sm font-medium text-gray-700 mb-1">{label ?? text.image}</label>
+      {imageId != null && <img src={src(imageId)} alt="" className="mb-2 h-32 w-auto rounded-lg border border-gray-200 object-cover" />}
+      <div className="flex items-center gap-3">
+        <label className="inline-flex items-center gap-1.5 rounded-lg bg-gray-100 text-gray-700 font-medium px-4 py-2 text-sm hover:bg-gray-200 transition cursor-pointer">
+          {uploading ? text.uploading : imageId != null ? text.replaceImage : text.uploadImage}
+          <input type="file" accept="image/*" onChange={handleFile} disabled={uploading} className="hidden" />
+        </label>
+        {imageId != null && (
+          <button type="button" onClick={() => onChange(null)} className="text-sm text-red-500 hover:text-red-700">
+            {text.removeImage}
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function BulletEditor({ bullets, onChange, strings }: { bullets: string[]; onChange: (bullets: string[]) => void; strings: SectionsEditorStrings }) {
+  return (
+    <div>
+      <label className="block text-sm font-medium text-gray-700 mb-1">{strings.bullets}</label>
+      <div className="space-y-2">
+        {bullets.map((bullet, i) => (
+          <div key={i} className="flex items-center gap-2">
+            <input
+              value={bullet}
+              onChange={e => onChange(bullets.map((b, j) => (j === i ? e.target.value : b)))}
+              className="flex-1 rounded-lg border border-gray-300 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-primary"
+            />
+            <button type="button" onClick={() => onChange(bullets.filter((_, j) => j !== i))} className="p-2 rounded-lg text-red-500 hover:bg-red-50">
+              <TrashIcon className="h-4 w-4" />
+            </button>
+          </div>
+        ))}
+        <button type="button" onClick={() => onChange([...bullets, ""])} className="inline-flex items-center gap-1.5 text-sm text-gray-600 hover:text-gray-900">
+          <PlusIcon className="h-4 w-4" /> {strings.addBullet}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+/** Props for `HeroSectionEditor`. */
+export interface HeroSectionEditorProps extends SectionEditorProps<HeroSection> {
+  /** Extra fields between the subheading and the buttons, such as a background image picker. */
+  media?: ReactNode;
+}
+
+/** Edits a hero's heading, subheading and two buttons. */
+export function HeroSectionEditor({ section, patch, strings, media }: HeroSectionEditorProps) {
+  return (
+    <div className="space-y-4">
+      <SectionField label={strings.heading} value={section.heading} onChange={v => patch({ heading: v })} />
+      <SectionField label={strings.subheading} value={section.subheading} onChange={v => patch({ subheading: v })} textarea />
+      {media}
+      <div className="grid sm:grid-cols-2 gap-4">
+        <SectionField label={strings.primaryButtonLabel} value={section.primaryLabel} onChange={v => patch({ primaryLabel: v })} />
+        <SectionField label={strings.primaryButtonHref} value={section.primaryHref} onChange={v => patch({ primaryHref: v })} />
+        <SectionField label={strings.secondaryButtonLabel} value={section.secondaryLabel} onChange={v => patch({ secondaryLabel: v })} />
+        <SectionField label={strings.secondaryButtonHref} value={section.secondaryHref} onChange={v => patch({ secondaryHref: v })} />
+      </div>
+    </div>
+  );
+}
+
+/** Edits a feature's heading, text and bullets. */
+export function FeatureSectionEditor({ section, patch, strings }: SectionEditorProps<FeatureSection>) {
+  return (
+    <div className="space-y-4">
+      <SectionField label={strings.heading} value={section.heading} onChange={v => patch({ heading: v })} />
+      <SectionField label={strings.text} value={section.text} onChange={v => patch({ text: v })} textarea />
+      <BulletEditor bullets={section.bullets} onChange={bullets => patch({ bullets })} strings={strings} />
+    </div>
+  );
+}
+
+/** Edits a text section's heading and Markdown body. */
+export function TextSectionEditor({ section, patch, strings }: SectionEditorProps<TextSection>) {
+  return (
+    <div className="space-y-4">
+      <SectionField label={strings.heading} value={section.heading} onChange={v => patch({ heading: v })} />
+      <SectionField label={strings.body} value={section.body} onChange={v => patch({ body: v })} textarea />
+    </div>
+  );
+}
+
+/** Props for `FeedSectionEditor`. */
+export interface FeedSectionEditorProps extends SectionEditorProps<FeedSection> {
+  /** Extra fields after the count, such as a filter. */
+  children?: ReactNode;
+  /** The classes on the grid. Defaults to `grid sm:grid-cols-2 gap-4`. */
+  className?: string | undefined;
+}
+
+/** Edits a feed's heading and how many items it shows, at least one. */
+export function FeedSectionEditor({ section, patch, strings, children, className = "grid sm:grid-cols-2 gap-4" }: FeedSectionEditorProps) {
+  return (
+    <div className={className}>
+      <SectionField label={strings.heading} value={section.heading} onChange={v => patch({ heading: v })} />
+      <TextInput label={strings.count} type="number" value={section.limit.toString()} onChange={e => patch({ limit: Math.max(1, Number(e.target.value) || 1) })} />
+      {children}
+    </div>
+  );
+}
+
+/** Edits a contact section's heading and text. */
+export function ContactSectionEditor({ section, patch, strings }: SectionEditorProps<ContactSection>) {
+  return (
+    <div className="space-y-4">
+      <SectionField label={strings.heading} value={section.heading} onChange={v => patch({ heading: v })} />
+      <SectionField label={strings.text} value={section.text} onChange={v => patch({ text: v })} textarea />
+    </div>
+  );
+}
+
+/** Edits a call to action's heading, text and button. */
+export function CtaSectionEditor({ section, patch, strings }: SectionEditorProps<CtaSection>) {
+  return (
+    <div className="space-y-4">
+      <SectionField label={strings.heading} value={section.heading} onChange={v => patch({ heading: v })} />
+      <SectionField label={strings.text} value={section.text} onChange={v => patch({ text: v })} textarea />
+      <div className="grid sm:grid-cols-2 gap-4">
+        <SectionField label={strings.buttonLabel} value={section.primaryLabel} onChange={v => patch({ primaryLabel: v })} />
+        <SectionField label={strings.buttonHref} value={section.primaryHref} onChange={v => patch({ primaryHref: v })} />
+      </div>
+    </div>
+  );
+}
+
+/** A live number a stats item can show. */
+export interface StatSource<Live extends string> {
+  value: Live;
+  /** The option's name in the source list. */
+  label: string;
+  /** The label an item gets when it picks this source with no label yet. */
+  defaultItemLabel: string;
+}
+
+/** Props for `StatsSectionEditor`. */
+export interface StatsSectionEditorProps<Live extends string> extends SectionEditorProps<StatsSection<Live>> {
+  /** The live sources after the manual number, in list order. */
+  sources?: readonly StatSource<Live>[] | undefined;
+}
+
+/** Edits a stats band's heading and items. Each item is a manual number or one of the live sources. */
+export function StatsSectionEditor<Live extends string = never>({ section, patch, strings, sources = [] }: StatsSectionEditorProps<Live>) {
+  const items = section.items;
+  const onChange = (next: StatItem<Live>[]) => patch({ items: next } as Partial<StatsSection<Live>>);
+  const update = (i: number, changes: Partial<StatItem<Live>>) => onChange(items.map((it, j) => (j === i ? { ...it, ...changes } : it)));
+  const defaults: Record<string, string> = { static: "", ...Object.fromEntries(sources.map(s => [s.value, s.defaultItemLabel])) };
+
+  return (
+    <div className="space-y-4">
+      <SectionField label={strings.headingOptional} value={section.heading} onChange={v => patch({ heading: v } as Partial<StatsSection<Live>>)} />
+      <div>
+        <label className="block text-sm font-medium text-gray-700 mb-1">{strings.stats}</label>
+        <div className="space-y-3">
+          {items.map((item, i) => (
+            <div key={i} className="flex flex-wrap items-end gap-2 rounded-lg border border-gray-200 p-3">
+              <label className="text-xs text-gray-600">
+                {strings.source}
+                <select
+                  value={item.source}
+                  onChange={e => {
+                    const source = e.target.value as StatItem<Live>["source"];
+                    update(i, { source, ...(item.label ? {} : { label: defaults[source] ?? "" }) });
+                  }}
+                  className="mt-1 block rounded-lg border border-gray-300 px-3 py-2 text-sm"
+                >
+                  <option value="static">{strings.sourceStatic}</option>
+                  {sources.map(s => (
+                    <option key={s.value} value={s.value}>
+                      {s.label}
+                    </option>
+                  ))}
+                </select>
+              </label>
+              {item.source === "static" && (
+                <div className="w-28">
+                  <TextInput label={strings.value} value={item.value} onChange={e => update(i, { value: e.target.value })} />
+                </div>
+              )}
+              <div className="flex-1 min-w-[10rem]">
+                <TextInput label={strings.label} value={item.label} onChange={e => update(i, { label: e.target.value })} />
+              </div>
+              <button type="button" onClick={() => onChange(items.filter((_, j) => j !== i))} className="p-2 rounded-lg text-red-500 hover:bg-red-50">
+                <TrashIcon className="h-4 w-4" />
+              </button>
+            </div>
+          ))}
+          <button type="button" onClick={() => onChange([...items, { source: "static", value: "", label: "" }])} className="inline-flex items-center gap-1.5 text-sm text-gray-600 hover:text-gray-900">
+            <PlusIcon className="h-4 w-4" /> {strings.addStat}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/** Edits an image section: the image, the layout, the alt text, and a text or a caption by layout. */
+export function ImageSectionEditor({ section, patch, strings, images }: SectionEditorProps<ImageSection>) {
+  const layout = section.layout ?? "standard";
+  const usesText = layout === "left" || layout === "right" || layout === "overlay" || layout === "overlayFull";
+  return (
+    <div className="space-y-4">
+      <ImagePicker imageId={section.imageId} onChange={imageId => patch({ imageId })} images={images} strings={strings} />
+      <div>
+        <label className="block text-sm font-medium text-gray-700 mb-1">{strings.layout}</label>
+        <select value={layout} onChange={e => patch({ layout: e.target.value as ImageSection["layout"] })} className="rounded-lg border border-gray-300 px-3 py-2 text-sm">
+          <option value="standard">{strings.layoutStandard}</option>
+          <option value="full">{strings.layoutFull}</option>
+          <option value="left">{strings.layoutLeft}</option>
+          <option value="right">{strings.layoutRight}</option>
+          <option value="overlay">{strings.layoutOverlay}</option>
+          <option value="overlayFull">{strings.layoutOverlayFull}</option>
+        </select>
+      </div>
+      <SectionField label={strings.altText} value={section.alt} onChange={v => patch({ alt: v })} />
+      {usesText && <SectionField label={strings.text} value={section.text} onChange={v => patch({ text: v })} textarea />}
+      {!usesText && <SectionField label={strings.caption} value={section.caption} onChange={v => patch({ caption: v })} />}
+    </div>
+  );
+}

package/src/sections/factory.ts

@@ -0,0 +1,26 @@
+import type { BaseSection, SectionOf } from "./types";
+
+let counter = 0;
+
+/** A new section id, unique within the page. */
+function newSectionId(): string {
+  return `s-${Date.now()}-${counter++}`;
+}
+
+/** The starting fields of each section type, without the id, the type and `visible`. */
+export type SectionTemplates<S extends BaseSection> = {
+  [K in S["type"]]: Omit<SectionOf<S, K>, "id" | "type" | "visible">;
+};
+
+/**
+ * Builds the app's `createSection` from its starting fields. Each call gets a new id and its own
+ * copy of the fields, so two sections never share an array.
+ */
+export function createSectionFactory<S extends BaseSection>(templates: SectionTemplates<S>): (type: S["type"]) => S {
+  return type => ({ id: newSectionId(), visible: true, type, ...structuredClone(templates[type as S["type"]]) }) as unknown as S;
+}
+
+/** A deep copy of the section with a new id. */
+export function cloneSection<S extends BaseSection>(section: S): S {
+  return { ...structuredClone(section), id: newSectionId() };
+}

package/src/sections/index.ts

@@ -0,0 +1,69 @@
+export { SHARED_SECTION_TYPES } from "./types";
+export type {
+  BaseSection,
+  ContactSection,
+  CtaSection,
+  FeatureSection,
+  FeedSection,
+  HeroSection,
+  ImageLayout,
+  ImageSection,
+  SectionExtensions,
+  SectionOf,
+  Sections,
+  SharedSectionType,
+  StatItem,
+  StatsSection,
+  TextSection,
+} from "./types";
+export { cloneSection, createSectionFactory } from "./factory";
+export type { SectionTemplates } from "./factory";
+export {
+  SectionRenderer,
+  createContactRenderer,
+  createImageRenderer,
+  createTextRenderer,
+  ctaRenderer,
+  featureRenderer,
+  heroRenderer,
+} from "./SectionRenderer";
+export type {
+  ContactRendererOptions,
+  ImageDimensions,
+  ImageRendererOptions,
+  SectionImageProps,
+  SectionLinkProps,
+  SectionRenderContext,
+  SectionRenderFn,
+  SectionRendererProps,
+  SectionRenderers,
+  TextRendererOptions,
+} from "./SectionRenderer";
+export { SmartLink } from "./SmartLink";
+export type { SmartLinkProps } from "./SmartLink";
+export { SectionsEditor } from "./SectionsEditor";
+export type { SectionEditors, SectionsEditorProps } from "./SectionsEditor";
+export {
+  ContactSectionEditor,
+  CtaSectionEditor,
+  FeatureSectionEditor,
+  FeedSectionEditor,
+  HeroSectionEditor,
+  ImagePicker,
+  ImageSectionEditor,
+  SectionField,
+  StatsSectionEditor,
+  TextSectionEditor,
+} from "./editors";
+export type {
+  FeedSectionEditorProps,
+  HeroSectionEditorProps,
+  ImagePickerProps,
+  SectionEditorProps,
+  SectionFieldProps,
+  SectionImages,
+  StatSource,
+  StatsSectionEditorProps,
+} from "./editors";
+export { defaultSectionTypeLabels, defaultSectionsEditorStrings } from "./sectionsEditorStrings";
+export type { SectionsEditorStrings } from "./sectionsEditorStrings";

package/src/sections/sectionsEditorStrings.ts

@@ -0,0 +1,108 @@
+// Plain values, with no "use client", so a server component can import them.
+
+import type { SharedSectionType } from "./types";
+
+/** The sections editor's text. Pass the app's own language. The defaults are English. */
+export interface SectionsEditorStrings {
+  hide: string;
+  show: string;
+  moveUp: string;
+  moveDown: string;
+  duplicate: string;
+  /** The title of the button that removes a section. */
+  remove: string;
+  addSection: string;
+  heading: string;
+  headingOptional: string;
+  subheading: string;
+  text: string;
+  body: string;
+  primaryButtonLabel: string;
+  primaryButtonHref: string;
+  secondaryButtonLabel: string;
+  secondaryButtonHref: string;
+  buttonLabel: string;
+  buttonHref: string;
+  bullets: string;
+  addBullet: string;
+  count: string;
+  stats: string;
+  source: string;
+  sourceStatic: string;
+  value: string;
+  label: string;
+  addStat: string;
+  layout: string;
+  layoutStandard: string;
+  layoutFull: string;
+  layoutLeft: string;
+  layoutRight: string;
+  layoutOverlay: string;
+  layoutOverlayFull: string;
+  altText: string;
+  caption: string;
+  image: string;
+  uploadImage: string;
+  replaceImage: string;
+  uploading: string;
+  /** The button that clears the picked image. */
+  removeImage: string;
+  uploadFailed: string;
+}
+
+export const defaultSectionsEditorStrings: SectionsEditorStrings = {
+  hide: "Hide",
+  show: "Show",
+  moveUp: "Move up",
+  moveDown: "Move down",
+  duplicate: "Duplicate",
+  remove: "Remove",
+  addSection: "Add section",
+  heading: "Heading",
+  headingOptional: "Heading (optional)",
+  subheading: "Subheading",
+  text: "Text",
+  body: "Body (markdown)",
+  primaryButtonLabel: "Primary button label",
+  primaryButtonHref: "Primary button link",
+  secondaryButtonLabel: "Secondary button label",
+  secondaryButtonHref: "Secondary button link",
+  buttonLabel: "Button label",
+  buttonHref: "Button link",
+  bullets: "Bullet points",
+  addBullet: "Add bullet",
+  count: "Number to show",
+  stats: "Stats",
+  source: "Source",
+  sourceStatic: "Manual number",
+  value: "Value",
+  label: "Label",
+  addStat: "Add stat",
+  layout: "Layout",
+  layoutStandard: "Standard (centered)",
+  layoutFull: "Full width",
+  layoutLeft: "Image left, text right",
+  layoutRight: "Image right, text left",
+  layoutOverlay: "Text over image",
+  layoutOverlayFull: "Text over image (full width)",
+  altText: "Alt text",
+  caption: "Caption (optional)",
+  image: "Image",
+  uploadImage: "Upload image",
+  replaceImage: "Replace image",
+  uploading: "Uploading…",
+  removeImage: "Remove",
+  uploadFailed: "Failed to upload image",
+};
+
+/** The default name of each shared section type, on its badge and in the add list. */
+export const defaultSectionTypeLabels: Record<SharedSectionType, string> = {
+  hero: "Hero",
+  feature: "Feature",
+  text: "Text",
+  feed: "Feed",
+  contact: "Contact form",
+  cta: "Call to action",
+  stats: "Stats band",
+  image: "Image",
+};

package/src/sections/types.ts

@@ -0,0 +1,107 @@
+// Plain types, with no "use client", so a server component can import them.
+
+/** The fields every section has. `type` picks the renderer and the editor. */
+export interface BaseSection<T extends string = string> {
+  id: string;
+  type: T;
+  visible: boolean;
+}
+
+/** The page's opening band, with a heading and up to two buttons. */
+export interface HeroSection extends BaseSection<"hero"> {
+  heading: string;
+  subheading: string;
+  primaryLabel: string;
+  primaryHref: string;
+  secondaryLabel: string;
+  secondaryHref: string;
+}
+
+/** A card with a heading, a short text and a list of ticked bullets. */
+export interface FeatureSection extends BaseSection<"feature"> {
+  heading: string;
+  text: string;
+  bullets: string[];
+}
+
+/** A heading and a Markdown body. */
+export interface TextSection extends BaseSection<"text"> {
+  heading: string;
+  body: string;
+}
+
+/** A list of the app's latest items. The app registers its renderer, since only it knows the items. */
+export interface FeedSection extends BaseSection<"feed"> {
+  heading: string;
+  limit: number;
+}
+
+/** A heading and a text above the app's contact form. */
+export interface ContactSection extends BaseSection<"contact"> {
+  heading: string;
+  text: string;
+}
+
+/** A band with a heading, a text and one button. */
+export interface CtaSection extends BaseSection<"cta"> {
+  heading: string;
+  text: string;
+  primaryLabel: string;
+  primaryHref: string;
+}
+
+/** One number in a stats band. `static` shows `value`. Any other source is a live number the app looks up. */
+export interface StatItem<Live extends string = never> {
+  source: "static" | Live;
+  value: string;
+  label: string;
+}
+
+/** A band of numbers. The app registers its renderer, since only it can look up the live numbers. */
+export interface StatsSection<Live extends string = never> extends BaseSection<"stats"> {
+  heading: string;
+  items: StatItem<Live>[];
+}
+
+export type ImageLayout = "standard" | "full" | "left" | "right" | "overlay" | "overlayFull";
+
+/** An uploaded image in one of the layouts, with a caption or a text. */
+export interface ImageSection extends BaseSection<"image"> {
+  imageId: string | null;
+  alt: string;
+  caption: string;
+  layout: ImageLayout;
+  text: string;
+}
+
+/** The section types the library knows. */
+export type SharedSectionType = "hero" | "feature" | "text" | "feed" | "contact" | "cta" | "stats" | "image";
+
+/** Every shared section type, in the order the editor offers them. */
+export const SHARED_SECTION_TYPES: readonly SharedSectionType[] = ["hero", "feature", "text", "feed", "contact", "cta", "stats", "image"];
+
+/** The extra fields an app adds to a shared section, by type. */
+export type SectionExtensions = { [K in SharedSectionType]?: object };
+
+type Extra<E extends SectionExtensions, K extends SharedSectionType> = E[K] extends object ? E[K] : unknown;
+
+/**
+ * The union of the shared sections, each with the app's extra fields. `Live` names the live
+ * sources a stats item can show. An app with its own section types adds them to the union.
+ *
+ * ```ts
+ * type Section = Sections<{ hero: { backgroundImageId: string | null } }, "builds" | "parts">;
+ * ```
+ */
+export type Sections<E extends SectionExtensions = Record<never, never>, Live extends string = never> =
+  | (HeroSection & Extra<E, "hero">)
+  | (FeatureSection & Extra<E, "feature">)
+  | (TextSection & Extra<E, "text">)
+  | (FeedSection & Extra<E, "feed">)
+  | (ContactSection & Extra<E, "contact">)
+  | (CtaSection & Extra<E, "cta">)
+  | (StatsSection<Live> & Extra<E, "stats">)
+  | (ImageSection & Extra<E, "image">);
+
+/** The member of a section union with the given type. */
+export type SectionOf<S extends BaseSection, K extends S["type"]> = Extract<S, { type: K }>;

package/src/seo/index.ts

@@ -4,6 +4,7 @@ export { ref, serializeGraph, type OrganizationInfo, type SchemaNode, type Schem
 export {
   defineSite,
   LEGAL_PAGE_KEYS,
+  type DefaultLegalPageKey,
   NOINDEX,
   SHARE_IMAGE_SIZE,
   type Crumb,

package/src/seo/site.ts

@@ -2,6 +2,9 @@ import type { Metadata, MetadataRoute } from "next";
 import { isIndexableEnvironment } from "./environment";
 import { ref, type OrganizationInfo, type SchemaNode } from "./schema";
 import { parseTimestamp } from "./sitemap";
+import { LEGAL_PAGE_KEYS, type DefaultLegalPageKey } from "../legal/keys";
+
+export { LEGAL_PAGE_KEYS, type DefaultLegalPageKey } from "../legal/keys";
 
 /** The size of the share image. */
 export const SHARE_IMAGE_SIZE = { width: 1200, height: 630 } as const;
@@ -64,12 +67,9 @@ export interface LocaleEntryOptions<L extends string> {
   lastModified?: ((locale: L) => Date | undefined) | undefined;
 }
 
-/** The legal pages every site has, as `createLegalService` names them. */
-export const LEGAL_PAGE_KEYS = ["terms", "privacy", "cookies"] as const;
-
 /** Options for `legalEntries`. */
 export interface LegalEntriesInput<K extends string, L extends string> {
-  /** The legal pages, each at `/<key>` below the locale. Defaults to `LEGAL_PAGE_KEYS`. */
+  /** The legal pages, each at `/<key>` below the locale, such as the legal service's `keys`. Defaults to `LEGAL_PAGE_KEYS`. */
   keys?: readonly K[] | undefined;
   /** A function that returns when a page last changed, as the API's timestamp. A site without locales passes no locale. */
   updatedAt: (key: K, locale: L | undefined) => Promise<string | null | undefined>;
@@ -221,7 +221,7 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
    * timestamps are fetched in parallel. An error from `updatedAt` fails the sitemap, so a stale one
    * is served rather than one without dates.
    */
-  const legalEntries = async <K extends string = (typeof LEGAL_PAGE_KEYS)[number]>({
+  const legalEntries = async <K extends string = DefaultLegalPageKey>({
     keys,
     updatedAt,
   }: LegalEntriesInput<K, L>): Promise<MetadataRoute.Sitemap> => {

package/src/session/expiry.ts

@@ -19,11 +19,13 @@ export const SESSION_ERRORS = {
  * The codes a failed sign-in reports in next-auth's `error`. Wrong credentials and every API answer
  * look the same, so the message never hints that a password was right. Only an API that does not
  * answer, or a gateway error, reports `unavailable`. That depends on the server, never on the
- * password.
+ * password. `lockedOut` is the API's `lockedOut` code after too many failed sign-ins, which the API
+ * gives whether the password was right or wrong.
  */
 export const SIGN_IN_ERRORS = {
   invalidCredentials: "InvalidCredentials",
   unavailable: "SignInUnavailable",
+  lockedOut: "LockedOut",
 } as const;
 
 /** One of the values in `SESSION_ERRORS`. */