@shapio/schema 0.5.8 → 0.5.10

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { a as isEmptyRichText, i as RichTextResult, n as RichTextNode, o as richTextMediaIds, r as RichTextProblem, s as validateRichText, t as RichTextDocument } from "./validate-Oyo0GJ9j.js";
-import { S as SeoFieldKey, _ as SEO_FIELD_IDS, a as EMPTY_SEO_DEFAULTS, b as SEO_TITLE_TEMPLATE_PATTERN, c as seoDefaultsForLocale, d as SeoLocaleDefaults, f as SeoLocaleDefaultsSchema, g as SEO_EDITOR_ID, h as SEO_DESCRIPTION_SOFT_MAX, i as resolveSeo, l as SeoDefaults, m as SEO_COMPONENT_ID, n as ResolveSeoContext, o as applyTitleTemplate, p as SEO_COMPONENT_API_KEY, r as SeoKeys, s as isValidTitleTemplate, t as DEFAULT_SEO_KEYS, u as SeoDefaultsSchema, v as SEO_TITLE_PLACEHOLDER, x as SEO_TWITTER_HANDLE_PATTERN, y as SEO_TITLE_SOFT_MAX } from "./resolve-7-z9VQqw.js";
+import { S as SeoFieldKey, _ as SEO_FIELD_IDS, a as EMPTY_SEO_DEFAULTS, b as SEO_TITLE_TEMPLATE_PATTERN, c as seoDefaultsForLocale, d as SeoLocaleDefaults, f as SeoLocaleDefaultsSchema, g as SEO_EDITOR_ID, h as SEO_DESCRIPTION_SOFT_MAX, i as resolveSeo, l as SeoDefaults, m as SEO_COMPONENT_ID, n as ResolveSeoContext, o as applyTitleTemplate, p as SEO_COMPONENT_API_KEY, r as SeoKeys, s as isValidTitleTemplate, t as DEFAULT_SEO_KEYS, u as SeoDefaultsSchema, v as SEO_TITLE_PLACEHOLDER, x as SEO_TWITTER_HANDLE_PATTERN, y as SEO_TITLE_SOFT_MAX } from "./resolve-DlXILdG3.js";
 import { Static, TSchema, Type } from "typebox";
 //#region src/ids.d.ts
 /**
@@ -284,6 +284,11 @@ export declare const ModelDefinitionInputSchema: Type.TObject<{
   localized: Type.TOptional<Type.TBoolean>;
   /** Entries have separate draft and published states. Default true. */
   draftAndPublish: Type.TOptional<Type.TBoolean>;
+  /**
+   * Collections only: the stable ID of the collection this one extends (its parent). The model inherits
+   * the parent's fields, locked, and adds its own (plan polymorphic-types).
+   */
+  extends: Type.TOptional<Type.TString>;
   display: Type.TOptional<Type.TObject<{
     /** How entries open: `document` (default) or `form`. See `ENTRY_LAYOUTS`. */
     layout: Type.TOptional<Type.TEnum<["document", "form"]>>;
@@ -402,6 +407,11 @@ export declare const DefinitionInputSchema: Type.TUnion<[Type.TObject<{
   localized: Type.TOptional<Type.TBoolean>;
   /** Entries have separate draft and published states. Default true. */
   draftAndPublish: Type.TOptional<Type.TBoolean>;
+  /**
+   * Collections only: the stable ID of the collection this one extends (its parent). The model inherits
+   * the parent's fields, locked, and adds its own (plan polymorphic-types).
+   */
+  extends: Type.TOptional<Type.TString>;
   display: Type.TOptional<Type.TObject<{
     /** How entries open: `document` (default) or `form`. See `ENTRY_LAYOUTS`. */
     layout: Type.TOptional<Type.TEnum<["document", "form"]>>;
@@ -575,9 +585,28 @@ export type ModelDefinition = {
   description?: string;
   localized: boolean;
   draftAndPublish: boolean;
+  /**
+   * The stable ID of the collection this one extends. The stored definition holds its own fields only;
+   * `resolveModelDefinition` adds the inherited ones (ancestors' first).
+   */
+  extends?: string;
   fields: FieldDefinition[];
   display: ModelDisplay;
 };
+/** A field as a model sees it after inheritance: `inheritedFrom` names the declaring ancestor's ID. */
+export type ResolvedField = FieldDefinition & {
+  inheritedFrom?: string;
+};
+/**
+ * A model with its effective fields: every ancestor's fields (root first), then its own, and its display
+ * merged with its ancestors' (`resolveModelDefinition`). `ancestorIds` is required so code that needs
+ * effective fields can demand this type; a stored definition does not satisfy it.
+ */
+export type ResolvedModelDefinition = Omit<ModelDefinition, 'fields'> & {
+  fields: ResolvedField[];
+  /** Ancestors' stable IDs, root first; empty for a model that extends nothing. */
+  ancestorIds: readonly string[];
+};
 export type ComponentDefinition = {
   id: string;
   kind: 'component';
@@ -631,28 +660,28 @@ export declare const UID_PATTERN: RegExp;
 export declare const RICHTEXT_FORMAT = "shapio-richtext";
 export declare const RICHTEXT_FORMAT_VERSION = 1;
 //#endregion
-//#region src/editors/catalogue.d.ts
+//#region src/editors/catalog.d.ts
 /**
  * Built-in editors (ADR 0009): which data types each can edit and the schema of its options. The server
- * validates every field's editor choice against this catalogue, so selecting and configuring an editor is
+ * validates every field's editor choice against this catalog, so selecting and configuring an editor is
  * runtime metadata. Custom editors (loaded at runtime from the project) use namespaced IDs containing a dot,
  * e.g. `acme.colorWheel`; their options are free-form JSON here because their schema lives in the project.
  */
-export type EditorCatalogueEntry = {
+export type EditorCatalogEntry = {
   id: string;
   dataTypes: readonly DataType[];
   optionsSchema: TSchema;
   /** Extra compatibility rule beyond the data type (e.g. radio buttons only for single-value enums). */
   supports?: (field: FieldDefinition) => boolean;
 };
-export declare const EDITOR_CATALOGUE: ReadonlyMap<string, EditorCatalogueEntry>;
+export declare const EDITOR_CATALOG: ReadonlyMap<string, EditorCatalogEntry>;
 /** The editor a field gets when its definition names none. */
 export declare const DEFAULT_EDITORS: Readonly<Record<DataType, string>>;
 /** `vendor.name` (letters, digits, `_`, `-`), e.g. `acme.colorWheel`. Built-in IDs never contain a dot. */
 export declare const CUSTOM_EDITOR_ID_PATTERN: RegExp;
 export declare const isCustomEditorId: (id: string) => boolean;
 /** Built-in editors that can edit this field (for the admin's editor picker). */
-export declare const listCompatibleEditors: (field: FieldDefinition) => EditorCatalogueEntry[];
+export declare const listCompatibleEditors: (field: FieldDefinition) => EditorCatalogEntry[];
 //#endregion
 //#region src/display/layout.d.ts
 /**
@@ -733,7 +762,7 @@ export type FormLayout = {
 /**
  * The entry form's layout (`display.layout: 'form'`): every live field, the title included, in sections.
  * Field order decides everything: a group's section sits where its first field appears, with its fields in
- * field order, and every run of consecutive ungrouped fields is an unlabelled section of its own at its
+ * field order, and every run of consecutive ungrouped fields is an unlabeled section of its own at its
  * place. So name, price, sku, description with a Pricing group (price, sku) reads [name], Pricing [price,
  * sku], [description]. Unknown and deprecated ids are skipped. Pure: no values, no I/O.
  */
@@ -771,6 +800,87 @@ export declare const PLURAL_FALLBACK_SUFFIX = "Items";
  */
 export declare const suggestPlural: (apiKey: string) => string;
 //#endregion
+//#region src/naming/routePath.d.ts
+/** A route key: one to MAX_INHERITANCE_DEPTH API IDs joined by `/` (`products/digital`). */
+export declare const ROUTE_KEY_PATTERN: RegExp;
+/** Longest route key: every level at the longest API ID, plus the separators. */
+export declare const MAX_ROUTE_KEY_LENGTH: number;
+/** The route key of a model under its ancestors (root first): `products/digital`. A root's is `routeKeyOf`. */
+export declare const routePathOf: (definition: ModelDefinition, ancestors: readonly ModelDefinition[]) => string;
+/**
+ * Splits the path segments after a content prefix (`/api/content/`) into the route key and the rest: the
+ * leading segments that are API IDs (at most MAX_INHERITANCE_DEPTH) form the key; the first one that is not
+ * (an entry ID is a UUID, which always has a hyphen) starts the rest. A single segment that already holds a
+ * whole route key (`products%2Fdigital`, decoded) is taken as it is. Undefined when no segment is a key.
+ * Purely syntactic: shared by the server's URL rewrite and the in-process delivery matcher.
+ */
+export declare const splitRoutePath: (segments: readonly string[]) => {
+  routeKey: string;
+  rest: string[];
+} | undefined;
+//#endregion
+//#region src/inheritance/resolve.d.ts
+/**
+ * Model inheritance (plan polymorphic-types). A collection may extend another (`extends`, the parent's stable
+ * ID). Stored definitions hold their own fields only; the effective definition is resolved at read time:
+ * every ancestor's fields (root first, each marked `inheritedFrom`), then the model's own, and the display
+ * merged down the chain. Nothing is copied into children, so a parent edit changes one definition.
+ */
+/** Most levels a family may have, root included (`Products > Physical > Apparel` is three). */
+export declare const MAX_INHERITANCE_DEPTH = 8;
+export type DefinitionLookup = (id: string) => SchemaDefinition | undefined;
+/** Why an ancestor chain stops early. `invalid`: the parent is a component, a singleton or the model itself. */
+export type AncestorProblem = 'missing' | 'invalid' | 'cycle' | 'tooDeep';
+export type AncestorChain = {
+  /** The ancestors that resolve, root first (the parent last). */
+  ids: string[];
+  problem?: AncestorProblem;
+  /** The definition whose `extends` is the problem (the model itself or one of its ancestors). */
+  problemAt?: string;
+};
+/**
+ * The ancestors of a definition, root first, walking `extends` up. Stops at the first problem (missing,
+ * invalid or cyclic parent, or more than MAX_INHERITANCE_DEPTH levels) and returns what resolved so far.
+ */
+export declare const ancestorChain: (definition: SchemaDefinition, lookup: DefinitionLookup) => AncestorChain;
+/**
+ * A child's display over its parent's (already merged) one. Scalars and `listFieldIds` take the child's value
+ * when set, else the parent's. Groups are the parent's, then the child's. Canvas and strip take the child's
+ * list when set; else the parent's list (when set) with the child's own fields appended where the automatic
+ * rule would put them: canvas-eligible fields to the canvas, the other fields (not the cover) to the strip.
+ */
+export declare const mergeDisplay: (parent: ModelDisplay, child: ModelDisplay, ownFields: readonly FieldDefinition[]) => ModelDisplay;
+/**
+ * The effective definition of a model: ancestors' fields first (root first, `inheritedFrom` set, otherwise the
+ * same field objects' values and IDs), then its own fields; display merged root → model. A broken chain
+ * (see `ancestorChain`) resolves over the part that resolved; the validator reports the problem.
+ */
+export declare const resolveModelDefinition: (definition: ModelDefinition, lookup: DefinitionLookup) => ResolvedModelDefinition;
+/** The fields a resolved model declares itself (not inherited). */
+export declare const ownFields: (resolved: ResolvedModelDefinition) => FieldDefinition[];
+/** Definitions whose parent is `id`, in the given order. */
+export declare const findChildDefinitions: (definitions: readonly SchemaDefinition[], id: string) => ModelDefinition[];
+/**
+ * Inheritance lookups over one set of definitions (the active schema, a proposed one, a site's view), each
+ * memoised. Unknown IDs give empty answers; components and singletons are never resolved.
+ */
+export type DefinitionIndex = {
+  get: (id: string) => SchemaDefinition | undefined;
+  /** The effective definition of a collection or singleton; undefined for components and unknown IDs. */
+  resolve: (id: string) => ResolvedModelDefinition | undefined;
+  /** Ancestors' IDs, root first; [] for a root or an unknown ID. */
+  ancestors: (id: string) => readonly string[];
+  /** Direct children's IDs, in definition order. */
+  childrenOf: (id: string) => readonly string[];
+  /** Every descendant's ID (children, then their children, depth first), not the model itself. */
+  descendants: (id: string) => readonly string[];
+  /** The model and its descendants, the model first. */
+  family: (id: string) => readonly string[];
+  /** The family's root (the model itself when it extends nothing). */
+  rootOf: (id: string) => string;
+};
+export declare const createDefinitionIndex: (definitions: readonly SchemaDefinition[]) => DefinitionIndex;
+//#endregion
 //#region src/normalize.d.ts
 /** Input whose IDs have been assigned (see `assignIds`). */
 type WithIds<T extends {
@@ -807,7 +917,7 @@ export type ValidationIssue = {
   /** Set by cross-definition checks so a multi-definition apply can say which file is wrong. */
   definitionId?: string;
 };
-export type IssueCode = 'INVALID_STRUCTURE' | 'INVALID_TEXT' | 'INVALID_ID' | 'DUPLICATE_ID' | 'API_KEY_INVALID' | 'API_KEY_TOO_LONG' | 'API_KEY_RESERVED_PREFIX' | 'API_KEY_RESERVED' | 'API_KEY_COLLISION' | 'PLURAL_API_KEY_SAME_AS_SINGULAR' | 'GENERATED_NAME_COLLISION' | 'INVALID_SETTINGS' | 'INVALID_RANGE' | 'INVALID_PATTERN' | 'DUPLICATE_ENUM_VALUE' | 'INVALID_ENUM_VALUE' | 'UNSUPPORTED_FLAG' | 'INVALID_DEFAULT_VALUE' | 'UNKNOWN_EDITOR' | 'INCOMPATIBLE_EDITOR' | 'INVALID_EDITOR_OPTIONS' | 'UNKNOWN_FIELD_REFERENCE' | 'INVALID_FIELD_REFERENCE' | 'DUPLICATE_GROUP' | 'UNKNOWN_REFERENCE' | 'INVALID_REFERENCE_TARGET' | 'COMPONENT_CYCLE' | 'COMPONENT_TOO_DEEP' | 'REFERENCED_DEFINITION';
+export type IssueCode = 'INVALID_STRUCTURE' | 'INVALID_TEXT' | 'INVALID_ID' | 'DUPLICATE_ID' | 'API_KEY_INVALID' | 'API_KEY_TOO_LONG' | 'API_KEY_RESERVED_PREFIX' | 'API_KEY_RESERVED' | 'API_KEY_COLLISION' | 'PLURAL_API_KEY_SAME_AS_SINGULAR' | 'GENERATED_NAME_COLLISION' | 'INVALID_SETTINGS' | 'INVALID_RANGE' | 'INVALID_PATTERN' | 'DUPLICATE_ENUM_VALUE' | 'INVALID_ENUM_VALUE' | 'UNSUPPORTED_FLAG' | 'INVALID_DEFAULT_VALUE' | 'UNKNOWN_EDITOR' | 'INCOMPATIBLE_EDITOR' | 'INVALID_EDITOR_OPTIONS' | 'UNKNOWN_FIELD_REFERENCE' | 'INVALID_FIELD_REFERENCE' | 'DUPLICATE_GROUP' | 'UNKNOWN_REFERENCE' | 'INVALID_REFERENCE_TARGET' | 'COMPONENT_CYCLE' | 'COMPONENT_TOO_DEEP' | 'REFERENCED_DEFINITION' | 'UNKNOWN_PARENT' | 'INVALID_PARENT' | 'INHERITANCE_CYCLE' | 'INHERITANCE_TOO_DEEP' | 'INHERITED_FIELD_COLLISION' | 'INHERITED_FLAG_MISMATCH' | 'HAS_CHILDREN';
 export declare class SchemaValidationError extends Error {
   readonly issues: readonly ValidationIssue[];
   constructor(issues: readonly ValidationIssue[]);
@@ -842,9 +952,18 @@ export declare const foldApiKey: (key: string) => string;
 export declare const checkDefaultValue: (field: FieldDefinition) => string | null;
 //#endregion
 //#region src/validators/definition.d.ts
+/**
+ * The display's references to fields. Also run by the inheritance check on a child's resolved definition,
+ * whose display may name inherited fields.
+ */
+export declare const checkDisplay: (definition: SchemaDefinition) => ValidationIssue[];
 /** All problems with one definition, in document order. Empty means valid on its own. */
 export declare const validateDefinition: (definition: SchemaDefinition) => ValidationIssue[];
 //#endregion
+//#region src/validators/inheritance.d.ts
+/** Every inheritance problem of a schema (see the module comment). */
+export declare const checkInheritance: (definitions: readonly SchemaDefinition[], index?: DefinitionIndex) => ValidationIssue[];
+//#endregion
 //#region src/validators/naming.d.ts
 /**
  * The names GraphQL (package J) and other generated contracts derive from API keys. Defined here, with the
@@ -855,6 +974,11 @@ export declare const toTypeName: (apiKey: string) => string;
 /** Suffixes of the types generated for each model (`Page`, `PageFilter`, `PageInput`...). */
 export declare const MODEL_TYPE_SUFFIXES: readonly ["", "Filter", "Input", "Connection", "Edge", "Localizations", "Sort"];
 export declare const COMPONENT_TYPE_SUFFIXES: readonly ["", "Input"];
+/**
+ * Suffix of the GraphQL interface a model with children gets (`ProductInterface`, plan polymorphic-types).
+ * Claimed only by models that have children, so existing schemas keep validating.
+ */
+export declare const INTERFACE_TYPE_SUFFIX = "Interface";
 export declare const MUTATION_PREFIXES: readonly ["create", "update", "delete", "publish", "unpublish"];
 /**
  * The key a model is addressed by in the delivery API (`/api/content/:routeKey`, preview routes): the
@@ -902,8 +1026,14 @@ export type GeneratedName = {
   /** The definition property the name comes from, when not `apiKey` (for the issue path). */
   property?: 'pluralApiKey';
 };
-/** Every name a definition contributes to the GraphQL schema. */
-export declare const generatedNames: (definition: SchemaDefinition) => GeneratedName[];
+/**
+ * Every name a definition contributes to the GraphQL schema. Fields are its own: a model that extends another
+ * reuses the enum and zone types of inherited fields, which belong to the declaring model. `hasChildren` adds
+ * the interface name of a model other models extend.
+ */
+export declare const generatedNames: (definition: SchemaDefinition, options?: {
+  hasChildren?: boolean;
+}) => GeneratedName[];
 //#endregion
 //#region src/validators/parse.d.ts
 export type ParseDefinitionResult = {
@@ -937,15 +1067,16 @@ export declare const MAX_COMPONENT_DEPTH = 5;
 export declare const embeddedComponentIds: (definition: SchemaDefinition) => string[];
 /**
  * Cross-definition checks over a whole schema (every active definition with the proposed change applied):
- * unique IDs and API keys, GraphQL name collisions, relation and component targets, component cycles and
- * nesting depth. Each definition must already pass `validateDefinition`.
+ * unique IDs and API keys, model inheritance, GraphQL name collisions, relation and component targets,
+ * component cycles and nesting depth. Each definition must already pass `validateDefinition`.
  */
 export declare const validateSchema: (definitions: readonly SchemaDefinition[]) => ValidationIssue[];
 /** Definitions that reference `id` (relations, components, dynamic zones). Used to block deletions. */
 export declare const findReferencingDefinitions: (definitions: readonly SchemaDefinition[], id: string) => SchemaDefinition[];
 /**
- * Models that embed a component directly or through other components, i.e. whose entries change shape
- * when the component does (brief §5: "editing a shared component must account for all dependent models").
+ * Models that embed a component directly, through other components or through an inherited field, i.e.
+ * whose entries change shape when the component does (brief §5: "editing a shared component must account for
+ * all dependent models").
  */
 export declare const findDependentModels: (definitions: readonly SchemaDefinition[], componentId: string) => SchemaDefinition[];
 //#endregion
@@ -965,7 +1096,7 @@ export declare const isValidText: (text: string) => boolean;
 export declare const findInvalidText: (value: unknown, path?: string) => string | undefined;
 //#endregion
 //#region src/diff/types.d.ts
-export declare const CHANGE_KINDS: readonly ["definition.added", "definition.removed", "definition.apiKey", "definition.pluralApiKey", "definition.metadata", "model.kind", "model.localized", "model.draftAndPublish", "field.added", "field.removed", "field.order", "field.apiKey", "field.metadata", "field.editor", "field.type", "field.required", "field.localized", "field.public", "field.deprecated", "field.unique", "field.filterable", "field.sortable", "field.settings"];
+export declare const CHANGE_KINDS: readonly ["definition.added", "definition.removed", "definition.apiKey", "definition.pluralApiKey", "definition.metadata", "model.kind", "model.localized", "model.draftAndPublish", "model.extends", "field.added", "field.removed", "field.order", "field.apiKey", "field.metadata", "field.editor", "field.type", "field.required", "field.localized", "field.public", "field.deprecated", "field.unique", "field.filterable", "field.sortable", "field.settings"];
 export type ChangeKind = (typeof CHANGE_KINDS)[number];
 /**
  * One difference between two versions of a definition. `property` names the changed property for
@@ -1045,7 +1176,11 @@ export declare const typeChangeDropsValues: (from: StoredFieldShape, to: StoredF
 export type PlannedChange = SchemaChange & {
   dropsValues?: boolean;
 };
-/** Whether a (classified) change drops every stored value of its field; false for plans without the flag. */
+/**
+ * Whether a (classified) change drops every stored value of its field; false for plans without the flag. A
+ * type change Shapio cannot convert, or an inherited field a model loses when it moves to another parent
+ * (`field.removed` marked by the planner, plan polymorphic-types decision 6).
+ */
 export declare const changeDropsValues: (change: PlannedChange) => boolean;
 /** Classifies one change in the context of the definitions it was diffed from. */
 export declare const classifyChange: (change: SchemaChange, context: ClassifyContext) => ClassifiedChange;
@@ -1341,11 +1476,11 @@ export declare const THEME_KEY_PATTERN: RegExp;
 export declare const BUILT_IN_THEME_KEYS: readonly ["shapio", "classic", "murdered-out", "forest", "snowed", "butter"];
 export type BuiltInThemeKey = (typeof BUILT_IN_THEME_KEYS)[number];
 /**
- * A token value an extension may use: a hex colour or a colour function whose arguments are numbers, units
+ * A token value an extension may use: a hex color or a color function whose arguments are numbers, units
  * and separators only (no `;`, quotes, braces or nested functions such as `url()` or `var()`), so a value
  * can never escape its declaration.
  */
-export declare const THEME_COLOUR_PATTERN: RegExp;
+export declare const THEME_COLOR_PATTERN: RegExp;
 //#endregion
 //#region src/themes/contrast.d.ts
 /**
@@ -1362,14 +1497,14 @@ export declare const THEME_UI_PAIRS: readonly ContrastPair[];
  * passes, and other selected surfaces hold no controls.
  */
 export declare const THEME_DARK_UI_PAIRS: readonly ContrastPair[];
-/** The WCAG contrast ratio of two `#rrggbb` colours. */
+/** The WCAG contrast ratio of two `#rrggbb` colors. */
 export declare const contrastRatio: (a: string, b: string) => number;
 export type ContrastCheck = {
   foreground: string;
   background: string;
   /** 4.5 for text, 3 for controls. */
   required: number;
-  /** Undefined when a value is not a `#rrggbb` colour (functions such as `oklch()` are not checked). */
+  /** Undefined when a value is not a `#rrggbb` color (functions such as `oklch()` are not checked). */
   ratio: number | undefined;
 };
 /** Every pair the variant must meet, with its ratio. Missing tokens report an undefined ratio. */