@agntcms/next 0.2.0

package/dist/index.cjs

@@ -0,0 +1,372 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  BooleanField: () => BooleanField,
+  ButtonField: () => ButtonField,
+  FormOverridesField: () => FormOverridesField,
+  HoneypotCollisionError: () => HoneypotCollisionError,
+  ImageField: () => ImageField,
+  InvalidFormFieldError: () => InvalidFormFieldError,
+  InvalidFormNameError: () => InvalidFormNameError,
+  LinkField: () => LinkField,
+  ListField: () => ListField,
+  NumberField: () => NumberField,
+  ReferenceField: () => ReferenceField,
+  RichTextField: () => RichTextField,
+  SelectField: () => SelectField,
+  SubmissionsNotReadableError: () => SubmissionsNotReadableError,
+  TextField: () => TextField,
+  VideoField: () => VideoField,
+  defineForm: () => defineForm,
+  defineSection: () => defineSection,
+  hasUniqueSectionIds: () => hasUniqueSectionIds,
+  hrefOf: () => hrefOf,
+  isExternalLink: () => isExternalLink,
+  linkAnchorAttrs: () => linkAnchorAttrs,
+  normalizeLinkValue: () => normalizeLinkValue,
+  validateEmail: () => validateEmail,
+  validateExternalUrl: () => validateExternalUrl,
+  validateInternalSlug: () => validateInternalSlug,
+  validatePhone: () => validatePhone
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/domain/fields.ts
+var TextField = { kind: "text" };
+var RichTextField = { kind: "richText" };
+var ImageField = { kind: "image" };
+var VideoField = { kind: "video" };
+var ReferenceField = { kind: "reference" };
+var LinkField = { kind: "link" };
+var NumberField = { kind: "number" };
+var BooleanField = { kind: "boolean" };
+var SelectField = (options, opts) => ({
+  kind: "select",
+  options,
+  ...opts?.default !== void 0 ? { default: opts.default } : {}
+});
+var ButtonField = (variants, opts) => ({
+  kind: "button",
+  variants,
+  ...opts?.default !== void 0 ? { default: opts.default } : {}
+});
+var ListField = (itemSchema, opts) => ({
+  kind: "list",
+  itemSchema,
+  ...opts?.min !== void 0 ? { min: opts.min } : {},
+  ...opts?.max !== void 0 ? { max: opts.max } : {},
+  ...opts?.default !== void 0 ? { default: opts.default } : {}
+});
+
+// src/domain/invariants.ts
+function hasUniqueSectionIds(page) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const section of page.sections) {
+    if (seen.has(section.id)) return false;
+    seen.add(section.id);
+  }
+  return true;
+}
+
+// src/domain/linkValidation.ts
+var SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-/]*[a-z0-9])?$/;
+var validateInternalSlug = (slug) => {
+  if (slug === "") return null;
+  if (/^https?:\/\//i.test(slug)) return "slug must not include a protocol";
+  if (slug.startsWith("//")) return "slug must not start with //";
+  if (slug.startsWith("/")) return "slug must not start with /";
+  if (slug.endsWith("/")) return "slug must not end with /";
+  if (slug.includes("//")) return "slug must not contain //";
+  if (slug.includes("..")) return "slug must not contain ..";
+  if (!SLUG_PATTERN.test(slug)) {
+    return "slug must use lowercase letters, digits, hyphens, and slashes only";
+  }
+  return null;
+};
+var validateExternalUrl = (url) => {
+  if (url === "") return null;
+  if (typeof url !== "string") return "URL must be a string";
+  if (!/^https?:\/\//i.test(url)) {
+    return "External link must start with http:// or https://";
+  }
+  try {
+    const parsed = new globalThis.URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return "External link must use http or https";
+    }
+  } catch {
+    return "External link is not a valid URL";
+  }
+  return null;
+};
+var EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var validateEmail = (email) => {
+  if (email === "") return null;
+  if (typeof email !== "string") return "Invalid email address";
+  if (!EMAIL_PATTERN.test(email)) return "Invalid email address";
+  return null;
+};
+var validatePhone = (phone) => {
+  if (phone === "") return null;
+  if (typeof phone !== "string") return "Phone number is too short";
+  const digits = phone.replace(/[^\d+]/g, "").replace(/\+/g, "");
+  if (digits.length < 7) return "Phone number is too short";
+  return null;
+};
+
+// src/domain/link.ts
+function hrefOf(link) {
+  if (link.type === "external") return link.url;
+  if (link.type === "email") {
+    if (link.email === "") return "";
+    return "mailto:" + link.email;
+  }
+  if (link.type === "phone") {
+    if (link.phone === "") return "";
+    return "tel:" + link.phone.replace(/[^\d+]/g, "");
+  }
+  const slug = link.slug.startsWith("/") ? link.slug.slice(1) : link.slug;
+  if (slug === "" || slug === "home") return "/";
+  return "/" + slug;
+}
+function isExternalLink(link) {
+  return link.type === "external";
+}
+function linkAnchorAttrs(link) {
+  const href = hrefOf(link);
+  if (link.type === "external") {
+    return { href, target: "_blank", rel: "noreferrer" };
+  }
+  return { href };
+}
+function normalizeLinkValue(raw) {
+  if (raw === null || typeof raw !== "object") {
+    return { type: "internal", slug: "", label: "" };
+  }
+  const obj = raw;
+  const label = typeof obj["label"] === "string" ? obj["label"] : "";
+  if (obj["type"] === "internal") {
+    const slug = typeof obj["slug"] === "string" ? obj["slug"] : "";
+    return { type: "internal", slug, label };
+  }
+  if (obj["type"] === "external") {
+    const url = typeof obj["url"] === "string" ? obj["url"] : "";
+    return { type: "external", url, label };
+  }
+  if (obj["type"] === "email") {
+    const email = typeof obj["email"] === "string" ? obj["email"] : "";
+    return { type: "email", email, label };
+  }
+  if (obj["type"] === "phone") {
+    const phone = typeof obj["phone"] === "string" ? obj["phone"] : "";
+    return { type: "phone", phone, label };
+  }
+  if (typeof obj["href"] === "string") {
+    const href = obj["href"];
+    if (/^mailto:/i.test(href)) {
+      return { type: "email", email: href.slice("mailto:".length), label };
+    }
+    if (/^tel:/i.test(href)) {
+      return { type: "phone", phone: href.slice("tel:".length), label };
+    }
+    if (/^https?:\/\//i.test(href)) {
+      return { type: "external", url: href, label };
+    }
+    const slug = href.startsWith("/") ? href.slice(1) : href;
+    return { type: "internal", slug, label };
+  }
+  return { type: "internal", slug: "", label: "" };
+}
+
+// src/domain/form.ts
+var FORM_FORBIDDEN_KINDS = /* @__PURE__ */ new Set([
+  "image",
+  "video",
+  "reference",
+  "list",
+  // `formOverrides` is a section-only descriptor (it overrides another
+  // form schema instance). Putting it inside a form would mean a form's
+  // payload could carry overrides for itself or another form — a
+  // recursive shape with no ergonomic editor UI. Section-only by design.
+  "formOverrides",
+  // `button` is a section-only descriptor: a styled CTA with an
+  // optional link. Public-form payloads collect user input — a button
+  // value is authored content, not a submitted answer. Section-only
+  // by design (mirrors `formOverrides`).
+  "button"
+]);
+var SubmissionsNotReadableError = class extends Error {
+  constructor(message = "submission adapter does not support reading") {
+    super(message);
+    this.name = "SubmissionsNotReadableError";
+  }
+};
+
+// src/domain/formOverrides.ts
+var FormOverridesField = (formName, opts) => ({
+  kind: "formOverrides",
+  formName,
+  ...opts?.default !== void 0 ? { default: opts.default } : {}
+});
+
+// src/sections/defineSection.ts
+function builtInDefault(fieldName, descriptor) {
+  switch (descriptor.kind) {
+    case "image":
+      return { filename: "placeholder.png", alt: "Placeholder image" };
+    case "video":
+      return { url: "" };
+    case "richText":
+      return "Start writing here...";
+    case "text":
+      return fieldName.charAt(0).toUpperCase() + fieldName.slice(1).replace(/([A-Z])/g, " $1");
+    case "reference":
+      return { slug: "" };
+    case "link":
+      return { type: "internal", slug: "", label: "Learn more" };
+    case "button": {
+      const firstVariant = descriptor.variants[0]?.value ?? "";
+      return { label: "Get started", variant: firstVariant };
+    }
+    case "number":
+      return 0;
+    case "boolean":
+      return false;
+    case "select":
+      return descriptor.options[0]?.value ?? "";
+    case "list":
+      return [];
+    case "formOverrides":
+      return {};
+    default: {
+      const _exhaustive = descriptor;
+      void _exhaustive;
+      return "";
+    }
+  }
+}
+function defineSection(input) {
+  const defaults = {};
+  for (const [key, descriptor] of Object.entries(input.schema)) {
+    defaults[key] = descriptor.default ?? builtInDefault(key, descriptor);
+  }
+  return {
+    name: input.name,
+    ...input.category !== void 0 ? { category: input.category } : {},
+    schema: input.schema,
+    component: input.component,
+    defaults,
+    // Conditional spread mirrors the `category` pattern — required so
+    // `exactOptionalPropertyTypes` does not see `layouts: undefined` being
+    // assigned to an optional-only property.
+    ...input.layouts !== void 0 ? { layouts: input.layouts } : {}
+  };
+}
+
+// src/forms/defineForm.ts
+var InvalidFormFieldError = class extends Error {
+  formName;
+  fieldName;
+  fieldKind;
+  constructor(formName, fieldName, fieldKind) {
+    super(
+      `Form "${formName}": field "${fieldName}" uses kind "${fieldKind}", which is not allowed in a form schema in v1. Allowed kinds: text, richText, number, boolean, select, link. Forbidden kinds: image, reference, list, formOverrides. See ARCHITECTURE.md \xA76.5.`
+    );
+    this.name = "InvalidFormFieldError";
+    this.formName = formName;
+    this.fieldName = fieldName;
+    this.fieldKind = fieldKind;
+  }
+};
+var HoneypotCollisionError = class extends Error {
+  formName;
+  fieldName;
+  reason;
+  constructor(formName, fieldName, reason = "collision") {
+    super(
+      reason === "empty" ? `Form "${formName}": honeypot name must be a non-empty string.` : `Form "${formName}": honeypot name "${fieldName}" collides with a real field. Choose a honeypot name that does not appear in the schema.`
+    );
+    this.name = "HoneypotCollisionError";
+    this.formName = formName;
+    this.fieldName = fieldName;
+    this.reason = reason;
+  }
+};
+var InvalidFormNameError = class extends Error {
+  constructor(name) {
+    super(
+      `Invalid form name ${JSON.stringify(name)}. Use letters, digits, hyphen, and underscore only (no path separators).`
+    );
+    this.name = "InvalidFormNameError";
+  }
+};
+var FORM_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+function defineForm(input) {
+  if (typeof input.name !== "string" || !FORM_NAME_PATTERN.test(input.name)) {
+    throw new InvalidFormNameError(input.name);
+  }
+  for (const [fieldName, descriptor] of Object.entries(input.schema)) {
+    const kind = descriptor.kind;
+    if (FORM_FORBIDDEN_KINDS.has(kind)) {
+      throw new InvalidFormFieldError(input.name, fieldName, kind);
+    }
+  }
+  if (input.honeypot !== void 0) {
+    if (typeof input.honeypot !== "string" || input.honeypot === "") {
+      throw new HoneypotCollisionError(input.name, input.honeypot, "empty");
+    }
+    if (Object.prototype.hasOwnProperty.call(input.schema, input.honeypot)) {
+      throw new HoneypotCollisionError(input.name, input.honeypot, "collision");
+    }
+  }
+  return input.honeypot !== void 0 ? { name: input.name, schema: input.schema, honeypot: input.honeypot } : { name: input.name, schema: input.schema };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BooleanField,
+  ButtonField,
+  FormOverridesField,
+  HoneypotCollisionError,
+  ImageField,
+  InvalidFormFieldError,
+  InvalidFormNameError,
+  LinkField,
+  ListField,
+  NumberField,
+  ReferenceField,
+  RichTextField,
+  SelectField,
+  SubmissionsNotReadableError,
+  TextField,
+  VideoField,
+  defineForm,
+  defineSection,
+  hasUniqueSectionIds,
+  hrefOf,
+  isExternalLink,
+  linkAnchorAttrs,
+  normalizeLinkValue,
+  validateEmail,
+  validateExternalUrl,
+  validateInternalSlug,
+  validatePhone
+});

package/dist/index.d.cts

@@ -0,0 +1,133 @@
+import { P as Page, h as LinkValue } from './form-BqY0H1V5.cjs';
+export { A as AnyFormDefinition, j as BooleanField, B as ButtonField, i as ButtonValue, c as FieldDescriptor, y as FieldKind, x as FieldValueFor, b as FormDefinition, p as FormFieldDescriptor, q as FormFieldOverride, n as FormFieldOverrides, r as FormOverridesField, m as FormOverridesFieldDescriptor, a as FormSchema, I as ImageField, d as ImageValue, L as LinkField, l as ListField, z as ListItem, N as NumberField, C as PageSeo, w as PageSummary, f as ReferenceField, g as ReferenceValue, R as RichTextField, D as Section, S as SectionSchema, k as SelectField, E as SelectOption, s as Submission, t as SubmissionAdapterInfo, o as SubmissionStorageAdapter, u as SubmissionSummary, v as SubmissionsNotReadableError, T as TextField, V as VideoField, e as VideoValue } from './form-BqY0H1V5.cjs';
+export { G as Global } from './global-CV23g5Bn.cjs';
+export { A as AnySectionDefinition, D as DataOf, a as DefineSectionInput, E as EditableSlot, F as FieldDataType, S as SectionComponent, b as SectionDefinition, c as SlotItem, d as defineSection } from './defineSection-9qQ5ulAH.cjs';
+export { D as DefineFormInput, H as HoneypotCollisionError, I as InvalidFormFieldError, a as InvalidFormNameError, d as defineForm } from './defineForm-CJ8KZC93.cjs';
+
+/**
+ * Returns `true` when every `section.id` in the page appears exactly once.
+ * Empty `sections` arrays are trivially unique.
+ */
+declare function hasUniqueSectionIds(page: Page): boolean;
+
+/**
+ * Validate the slug stored on an internal `LinkValue`.
+ *
+ * Returns `null` when valid (including the empty string, which the
+ * editor renders as "not yet selected"), an error message otherwise.
+ */
+declare const validateInternalSlug: (slug: string) => string | null;
+/**
+ * Validate the URL stored on an external `LinkValue`.
+ *
+ * Returns `null` when valid (including the empty string, which the
+ * editor renders as "not yet entered"), an error message otherwise.
+ *
+ * Only absolute http(s) URLs pass. Site-relative paths belong to the
+ * internal branch — if the author types `/about`, they should switch
+ * the segmented control to "Internal" and enter `about` instead.
+ */
+declare const validateExternalUrl: (url: string) => string | null;
+/**
+ * Validate the email stored on an `email` `LinkValue`.
+ *
+ * Returns `null` when valid (including the empty string, which the
+ * editor renders as "not yet entered"), an error message otherwise.
+ */
+declare const validateEmail: (email: string) => string | null;
+/**
+ * Validate the phone string stored on a `phone` `LinkValue`.
+ *
+ * Returns `null` when valid (including the empty string, which the
+ * editor renders as "not yet entered"). Non-empty input must contain
+ * at least seven digits after stripping every character that is
+ * neither a digit nor a leading `+`. Country-code structure is not
+ * validated — it's overkill for v1 and would reject authored strings
+ * that real-world dialler apps handle fine.
+ */
+declare const validatePhone: (phone: string) => string | null;
+
+/**
+ * Resolve a `LinkValue` to the href string a section component should
+ * render in an `<a>` element.
+ *
+ * Internal slugs route through the catch-all (`app/[[...slug]]/page.tsx`)
+ * so they always live under the site root:
+ *   - empty slug or `'home'` → `'/'`
+ *   - `'about'`               → `'/about'`
+ *   - `'/blog'`               → `'/blog'`   (defensive: strip leading `/`)
+ *   - `'blog/welcome'`        → `'/blog/welcome'`
+ *
+ * External links return their URL verbatim; the validator already
+ * enforces the http(s) protocol allow-list, so we don't re-check here.
+ *
+ * Email links return `mailto:<email>` when the email is non-empty, or
+ * `''` when empty — the empty href lets a section component skip the
+ * anchor entirely when an author has not yet filled the field.
+ *
+ * Phone links return `tel:<digits>` with non-`[\d+]` characters
+ * stripped from the URI (so parens, spaces, and hyphens that authors
+ * type for legibility are removed before emitting `tel:`). The
+ * original formatted string stays in `link.phone` for display
+ * purposes. Empty phone → `''`, same rationale as email.
+ */
+declare function hrefOf(link: LinkValue): string;
+/**
+ * True iff the link points outside the current site.
+ *
+ * Only the `external` branch returns true. `email` and `phone` fire
+ * native handlers (mail client, dialler) — they do not navigate to a
+ * different site, so they are NOT considered "external" for the
+ * purpose of `target='_blank'` / `rel='noreferrer'`. Use
+ * `linkAnchorAttrs` to pick the right anchor attributes from a
+ * `LinkValue`.
+ */
+declare function isExternalLink(link: LinkValue): boolean;
+/**
+ * Canonical helper for translating a `LinkValue` into anchor
+ * attributes. Returns the href every link should carry, plus the
+ * `target='_blank'` / `rel='noreferrer'` pair only for the `external`
+ * branch.
+ *
+ * Why a single helper instead of letting consumers compose `hrefOf` +
+ * `isExternalLink` themselves: the contract for "open in a new tab"
+ * has gotten more nuanced as the discriminated union grew. Email and
+ * phone hand off to native OS handlers and would behave incorrectly
+ * with `target='_blank'` (Safari opens a blank tab that lingers after
+ * the mailto handler resolves). Centralising the decision here means
+ * marketing-site primitives, custom CTA buttons, navigation menus,
+ * and any future link-rendering surface make the same choice.
+ *
+ * Section authors should prefer:
+ *   const attrs = linkAnchorAttrs(link)
+ *   <a {...attrs}>{link.label}</a>
+ * over manually computing `target` / `rel`.
+ */
+declare function linkAnchorAttrs(link: LinkValue): {
+    href: string;
+    target?: '_blank';
+    rel?: 'noreferrer';
+};
+/**
+ * Project an arbitrary value into the canonical `LinkValue` shape.
+ *
+ * Three input cases:
+ *   1. Old-shape `{ href, label, external? }`: infer `type` from the
+ *      `href` protocol — `mailto:` → email, `tel:` → phone, `http(s):`
+ *      → external, otherwise internal. For the internal branch we
+ *      strip the leading `/` so the stored slug matches the page-id
+ *      model (no leading slash, see `hrefOf`).
+ *   2. New-shape `{ type: 'internal' | 'external' | 'email' | 'phone',
+ *      … }`: returned as-is, narrowed.
+ *   3. Anything else (null, primitives, garbage objects): collapse to
+ *      a blank internal link so the renderer can still emit something
+ *      and the editor can re-author from a known-good baseline.
+ *
+ * The function is intentionally lenient: it never throws. A throwing
+ * normaliser would push error-handling onto every section component
+ * for the rare case of legacy data, defeating the point of the
+ * defensive narrowing.
+ */
+declare function normalizeLinkValue(raw: unknown): LinkValue;
+
+export { LinkValue, Page, hasUniqueSectionIds, hrefOf, isExternalLink, linkAnchorAttrs, normalizeLinkValue, validateEmail, validateExternalUrl, validateInternalSlug, validatePhone };

package/dist/index.d.ts

@@ -0,0 +1,133 @@
+import { P as Page, h as LinkValue } from './form-BqY0H1V5.js';
+export { A as AnyFormDefinition, j as BooleanField, B as ButtonField, i as ButtonValue, c as FieldDescriptor, y as FieldKind, x as FieldValueFor, b as FormDefinition, p as FormFieldDescriptor, q as FormFieldOverride, n as FormFieldOverrides, r as FormOverridesField, m as FormOverridesFieldDescriptor, a as FormSchema, I as ImageField, d as ImageValue, L as LinkField, l as ListField, z as ListItem, N as NumberField, C as PageSeo, w as PageSummary, f as ReferenceField, g as ReferenceValue, R as RichTextField, D as Section, S as SectionSchema, k as SelectField, E as SelectOption, s as Submission, t as SubmissionAdapterInfo, o as SubmissionStorageAdapter, u as SubmissionSummary, v as SubmissionsNotReadableError, T as TextField, V as VideoField, e as VideoValue } from './form-BqY0H1V5.js';
+export { G as Global } from './global-CV23g5Bn.js';
+export { A as AnySectionDefinition, D as DataOf, a as DefineSectionInput, E as EditableSlot, F as FieldDataType, S as SectionComponent, b as SectionDefinition, c as SlotItem, d as defineSection } from './defineSection-Kr0pWqMY.js';
+export { D as DefineFormInput, H as HoneypotCollisionError, I as InvalidFormFieldError, a as InvalidFormNameError, d as defineForm } from './defineForm-Bp9vzW56.js';
+
+/**
+ * Returns `true` when every `section.id` in the page appears exactly once.
+ * Empty `sections` arrays are trivially unique.
+ */
+declare function hasUniqueSectionIds(page: Page): boolean;
+
+/**
+ * Validate the slug stored on an internal `LinkValue`.
+ *
+ * Returns `null` when valid (including the empty string, which the
+ * editor renders as "not yet selected"), an error message otherwise.
+ */
+declare const validateInternalSlug: (slug: string) => string | null;
+/**
+ * Validate the URL stored on an external `LinkValue`.
+ *
+ * Returns `null` when valid (including the empty string, which the
+ * editor renders as "not yet entered"), an error message otherwise.
+ *
+ * Only absolute http(s) URLs pass. Site-relative paths belong to the
+ * internal branch — if the author types `/about`, they should switch
+ * the segmented control to "Internal" and enter `about` instead.
+ */
+declare const validateExternalUrl: (url: string) => string | null;
+/**
+ * Validate the email stored on an `email` `LinkValue`.
+ *
+ * Returns `null` when valid (including the empty string, which the
+ * editor renders as "not yet entered"), an error message otherwise.
+ */
+declare const validateEmail: (email: string) => string | null;
+/**
+ * Validate the phone string stored on a `phone` `LinkValue`.
+ *
+ * Returns `null` when valid (including the empty string, which the
+ * editor renders as "not yet entered"). Non-empty input must contain
+ * at least seven digits after stripping every character that is
+ * neither a digit nor a leading `+`. Country-code structure is not
+ * validated — it's overkill for v1 and would reject authored strings
+ * that real-world dialler apps handle fine.
+ */
+declare const validatePhone: (phone: string) => string | null;
+
+/**
+ * Resolve a `LinkValue` to the href string a section component should
+ * render in an `<a>` element.
+ *
+ * Internal slugs route through the catch-all (`app/[[...slug]]/page.tsx`)
+ * so they always live under the site root:
+ *   - empty slug or `'home'` → `'/'`
+ *   - `'about'`               → `'/about'`
+ *   - `'/blog'`               → `'/blog'`   (defensive: strip leading `/`)
+ *   - `'blog/welcome'`        → `'/blog/welcome'`
+ *
+ * External links return their URL verbatim; the validator already
+ * enforces the http(s) protocol allow-list, so we don't re-check here.
+ *
+ * Email links return `mailto:<email>` when the email is non-empty, or
+ * `''` when empty — the empty href lets a section component skip the
+ * anchor entirely when an author has not yet filled the field.
+ *
+ * Phone links return `tel:<digits>` with non-`[\d+]` characters
+ * stripped from the URI (so parens, spaces, and hyphens that authors
+ * type for legibility are removed before emitting `tel:`). The
+ * original formatted string stays in `link.phone` for display
+ * purposes. Empty phone → `''`, same rationale as email.
+ */
+declare function hrefOf(link: LinkValue): string;
+/**
+ * True iff the link points outside the current site.
+ *
+ * Only the `external` branch returns true. `email` and `phone` fire
+ * native handlers (mail client, dialler) — they do not navigate to a
+ * different site, so they are NOT considered "external" for the
+ * purpose of `target='_blank'` / `rel='noreferrer'`. Use
+ * `linkAnchorAttrs` to pick the right anchor attributes from a
+ * `LinkValue`.
+ */
+declare function isExternalLink(link: LinkValue): boolean;
+/**
+ * Canonical helper for translating a `LinkValue` into anchor
+ * attributes. Returns the href every link should carry, plus the
+ * `target='_blank'` / `rel='noreferrer'` pair only for the `external`
+ * branch.
+ *
+ * Why a single helper instead of letting consumers compose `hrefOf` +
+ * `isExternalLink` themselves: the contract for "open in a new tab"
+ * has gotten more nuanced as the discriminated union grew. Email and
+ * phone hand off to native OS handlers and would behave incorrectly
+ * with `target='_blank'` (Safari opens a blank tab that lingers after
+ * the mailto handler resolves). Centralising the decision here means
+ * marketing-site primitives, custom CTA buttons, navigation menus,
+ * and any future link-rendering surface make the same choice.
+ *
+ * Section authors should prefer:
+ *   const attrs = linkAnchorAttrs(link)
+ *   <a {...attrs}>{link.label}</a>
+ * over manually computing `target` / `rel`.
+ */
+declare function linkAnchorAttrs(link: LinkValue): {
+    href: string;
+    target?: '_blank';
+    rel?: 'noreferrer';
+};
+/**
+ * Project an arbitrary value into the canonical `LinkValue` shape.
+ *
+ * Three input cases:
+ *   1. Old-shape `{ href, label, external? }`: infer `type` from the
+ *      `href` protocol — `mailto:` → email, `tel:` → phone, `http(s):`
+ *      → external, otherwise internal. For the internal branch we
+ *      strip the leading `/` so the stored slug matches the page-id
+ *      model (no leading slash, see `hrefOf`).
+ *   2. New-shape `{ type: 'internal' | 'external' | 'email' | 'phone',
+ *      … }`: returned as-is, narrowed.
+ *   3. Anything else (null, primitives, garbage objects): collapse to
+ *      a blank internal link so the renderer can still emit something
+ *      and the editor can re-author from a known-good baseline.
+ *
+ * The function is intentionally lenient: it never throws. A throwing
+ * normaliser would push error-handling onto every section component
+ * for the rare case of legacy data, defeating the point of the
+ * defensive narrowing.
+ */
+declare function normalizeLinkValue(raw: unknown): LinkValue;
+
+export { LinkValue, Page, hasUniqueSectionIds, hrefOf, isExternalLink, linkAnchorAttrs, normalizeLinkValue, validateEmail, validateExternalUrl, validateInternalSlug, validatePhone };