camox 0.44.0 → 0.46.0

package/dist/core/lib/contentType.d.ts

@@ -1,20 +1,48 @@
+import { Collection } from "../createCollection.js";
 import { IconId, IconValue } from "./iconTypes.js";
-import * as _$_sinclair_typebox0 from "@sinclair/typebox";
-import { Static, TArray, TObject, TSchema, TUnsafe } from "@sinclair/typebox";
-
+import { SystemOrderKey } from "@camox/api-contract";
+import { Static, TArray, TBoolean, TObject, TSchema, TUnsafe } from "@sinclair/typebox";
 //#region src/core/lib/contentType.d.ts
-declare class FieldToken {
+export declare const ReferenceContentBrand: unique symbol;
+export type ReferenceSchema<T extends Record<string, TSchema>> = TUnsafe<string | null> & {
+  readonly [ReferenceContentBrand]: T;
+  fieldType: "Reference";
+};
+export type ReferenceListSchema<T extends Record<string, TSchema>> = TUnsafe<string[]> & {
+  readonly [ReferenceContentBrand]: T;
+  fieldType: "ReferenceList";
+};
+/** The keys a query can order a collection's records by: its text fields and system metadata. */
+export type OrderableKeys<T extends Record<string, TSchema>> = { [K in keyof T & string]: T[K] extends {
+  fieldType: "String";
+} ? K : never; }[keyof T & string] | SystemOrderKey;
+/** A single-key ordering: `{ title: "asc" }`. */
+export type QueryOrderBy<K extends string> = { [P in K]: { [Q in P]: "asc" | "desc"; } & { [Q in Exclude<K, P>]?: never; }; }[K];
+type Range<N extends number, Acc extends number[] = []> = Acc["length"] extends N ? Acc[number] : Range<N, [...Acc, Acc["length"]]>;
+/** 1 to 100: literal limits outside it are rejected; computed `number` limits are checked on sync. */
+type QueryLimit = Exclude<Range<101>, 0>;
+export type ValidQueryLimit<L extends number> = number extends L ? number : L extends QueryLimit ? L : never;
+/**
+ * Defines a query-backed list's membership and order in code: optionally one ordering key and a
+ * limit (at most, and by default, 100 records). Live pages list published records ordered by
+ * their published content; the preview lists drafts too. Ties break by record id.
+ */
+export type ReferenceQuery<T extends Record<string, TSchema>, L extends number = number> = {
+  orderBy?: QueryOrderBy<OrderableKeys<T>>;
+  limit?: L & ValidQueryLimit<L>;
+};
+export declare class FieldToken {
   readonly fieldName: string;
   constructor(fieldName: string);
   toString(): string;
 }
-type SettingsScope = "block" | "item";
+export type SettingsScope = "block" | "item";
 /**
  * Serializable conditional block produced by the settings proxy. Emits Handlebars-style
  * `{{#if ...}}...{{/if}}` syntax wrapping each child line, tagged with its scope so the
  * server-side resolver knows whether to read from `settings` or `itemSettings`.
  */
-declare class Conditional {
+export declare class Conditional {
   readonly scope: SettingsScope;
   readonly settingName: string;
   readonly enumValue: string | null;
@@ -23,27 +51,31 @@ declare class Conditional {
   get openTag(): string;
   get closeTag(): string;
 }
-type ConditionalChild = string | FieldToken | Conditional;
-type ConditionalLines = ConditionalChild | ReadonlyArray<ConditionalChild>;
-type ContentProxy<TShape extends Record<string, TSchema>> = { [K in keyof TShape & string]: string & FieldToken };
+export type ConditionalChild = string | FieldToken | Conditional;
+export type ConditionalLines = ConditionalChild | ReadonlyArray<ConditionalChild>;
+export type ContentProxy<TShape extends Record<string, TSchema>> = { [K in keyof TShape & string]: TShape[K] extends ReferenceSchema<infer T> ? ContentProxy<T> : string & FieldToken; };
 /**
  * Callable shape for one entry on the settings proxy. Booleans take a single `lines`
  * argument; enums take `(value, lines)`. Settings of other shapes are disallowed — they
  * don't make sense as conditions.
  */
 type SettingCallable<T extends TSchema> = Static<T> extends boolean ? (lines: ConditionalLines) => Conditional : Static<T> extends string ? (value: Static<T>, lines: ConditionalLines) => Conditional : never;
-type SettingsProxy<TShape extends Record<string, TSchema>> = { [K in keyof TShape & string]: SettingCallable<TShape[K]> };
-type ToMarkdownBuilder<TContent extends Record<string, TSchema>, TSettings extends Record<string, TSchema> = Record<string, never>> = (c: ContentProxy<TContent>, s: SettingsProxy<TSettings>) => ReadonlyArray<string | FieldToken | Conditional>;
+export type SettingsProxy<TShape extends Record<string, TSchema>> = { [K in keyof TShape & string]: SettingCallable<TShape[K]>; };
+export type ToMarkdownBuilder<TContent extends Record<string, TSchema>, TSettings extends Record<string, TSchema> = Record<string, never>> = (c: ContentProxy<TContent>, s: SettingsProxy<TSettings>) => ReadonlyArray<string | FieldToken | Conditional>;
 declare const EmbedURLBrand: unique symbol;
-type EmbedURL = string & {
+export type EmbedURL = string & {
   readonly [EmbedURLBrand]: true;
 };
-declare const ItemSettingsBrand: unique symbol;
-type WithItemSettings<S extends Record<string, TSchema>> = {
+declare const ArtifactSourceBrand: unique symbol;
+export type ArtifactSource = string & {
+  readonly [ArtifactSourceBrand]: true;
+};
+export declare const ItemSettingsBrand: unique symbol;
+export type WithItemSettings<S extends Record<string, TSchema>> = {
   readonly [ItemSettingsBrand]?: S;
 };
 declare const LinkBrand: unique symbol;
-type LinkValue = ({
+export type LinkValue = ({
   type: "external";
   href: string;
 } | {
@@ -55,7 +87,7 @@ type LinkValue = ({
 } & {
   readonly [LinkBrand]: true;
 };
-type ImageValue = {
+export type ImageValue = {
   url: string;
   alt: string;
   filename: string;
@@ -65,7 +97,7 @@ type ImageValue = {
 } & {
   readonly __brand: "ImageValue";
 };
-type FileValue = {
+export type FileValue = {
   url: string;
   alt: string;
   filename: string;
@@ -75,155 +107,319 @@ type FileValue = {
 } & {
   readonly __brand: "FileValue";
 };
+export type StringField = TUnsafe<string> & {
+  fieldType: "String";
+};
+export type LinkField = TUnsafe<LinkValue>;
+export type ImageField = TUnsafe<ImageValue>;
+export type ImageListField = TArray<TUnsafe<ImageValue>>;
+export type FileField = TUnsafe<FileValue>;
+export type FileListField = TArray<TUnsafe<FileValue>>;
+export type EmbedField = TUnsafe<EmbedURL>;
+declare const ArtifactDataBrand: unique symbol;
+/** An artifact field; `D` carries the names of its Artifact Data at the type level only. */
+export type ArtifactField<D extends string = string> = TUnsafe<ArtifactSource> & {
+  fieldType: "Artifact";
+  readonly [ArtifactDataBrand]?: D;
+};
+export type IconField = TUnsafe<IconValue>;
+export type RepeaterField<T extends Record<string, TSchema>, S extends Record<string, TSchema>> = TArray<TObject<T>> & WithItemSettings<S>;
+export type EnumSetting<O extends Record<string, string>> = TUnsafe<keyof O & string> & {
+  fieldType: "Enum";
+};
+export type BooleanSetting = TBoolean & {
+  fieldType: "Boolean";
+};
+type StringOptions = {
+  title?: string;
+  maxLength?: number;
+  minLength?: number;
+  pattern?: string;
+};
 /**
- * Type builders for createBlock content schemas.
- * All fields must have default values.
+ * Builds the fields of a block or repeatable item's content.
+ * `enum` and `boolean` are not content: declare them in `settings` instead.
  */
-declare const Type$1: {
-  Icon: (options: {
-    default: IconId;
+export interface ContentFieldBuilder {
+  /**
+   * An inline-editable text field.
+   *
+   * @example
+   * field.string({ default: "Hello", maxLength: 100, title: "Title" })
+   */
+  string: (options: StringOptions & {
+    default: string;
+  }) => StringField;
+  /**
+   * A link with text, a target (external URL or internal page) and a new-tab flag.
+   *
+   * @example
+   * field.link({ default: { text: "Learn more", href: "/", newTab: false }, title: "CTA" })
+   */
+  link: (options: {
+    default: {
+      text: string;
+      href: string;
+      newTab: boolean;
+    };
     title?: string;
-  }) => TUnsafe<IconValue>;
+  }) => LinkField;
   /**
-   * Creates a string field with a required default value.
+   * An image asset.
    *
    * @example
-   * Type.String({ default: 'Hello' })
-   * Type.String({ default: 'Hello', maxLength: 100, title: 'Title' })
+   * field.image({ title: "Hero" })
    */
-  String: (options: {
+  image: (options?: {
+    title?: string;
+    required?: boolean;
+  }) => ImageField;
+  /**
+   * A list of image assets.
+   *
+   * @example
+   * field.imageList({ title: "Gallery", defaultItems: 3 })
+   */
+  imageList: (options?: {
+    title?: string;
+    defaultItems?: number;
+  }) => ImageListField;
+  /**
+   * A file asset.
+   *
+   * @example
+   * field.file({ accept: ["application/pdf"], title: "Datasheet" })
+   */
+  file: (options: {
+    accept: string[];
+    title?: string;
+    required?: boolean;
+  }) => FileField;
+  /**
+   * A list of file assets.
+   *
+   * @example
+   * field.fileList({ accept: ["application/pdf"], title: "Attachments" })
+   */
+  fileList: (options: {
+    accept: string[];
+    title?: string;
+    defaultItems?: number;
+  }) => FileListField;
+  /**
+   * A URL that must match `pattern`, rendered as an embed.
+   *
+   * @example
+   * field.embed({
+   *   pattern: "https:\\/\\/(www\\.)?youtube\\.com\\/watch\\?v=.+",
+   *   default: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+   *   title: "YouTube URL",
+   * })
+   */
+  embed: (options: {
+    pattern: string;
     default: string;
     title?: string;
-    maxLength?: number;
-    minLength?: number;
-    pattern?: string;
-  }) => TUnsafe<string>;
+  }) => EmbedField;
   /**
-   * Creates a repeatable array of object items.
-   * The default array is auto-generated based on minItems.
+   * A self-contained web page, usually written by an agent, rendered in a sandboxed frame.
+   * `size: "fill"` fills a container whose size you control; `size: "content"` follows the
+   * page's height. The source is optional: an empty artifact renders nothing on the website.
    *
-   * Items may also declare per-item `settings` (Enum/Boolean only) — not
-   * inline-editable; they appear in the sidebar when the item is selected,
-   * similar to block-level settings.
+   * @example
+   * field.artifact({ size: "fill", title: "Hero visual" })
+   */
+  artifact: <const D extends string = never>(options: {
+    size: "fill" | "content";
+    /**
+     * Sibling content fields and settings shared with the artifact as Artifact Data. Inside a
+     * repeater, the siblings are the item's own fields and settings.
+     */
+    data?: readonly D[];
+    default?: string;
+    title?: string;
+  }) => ArtifactField<NoInfer<D>>;
+  /**
+   * An icon from the set configured in `camox()`.
+   *
+   * @example
+   * field.icon({ default: "lucide:star", title: "Icon" })
+   */
+  icon: (options: {
+    default: IconId;
+    title?: string;
+  }) => IconField;
+  /**
+   * Selects a record of `collection` by identity; its content is resolved independently.
+   *
+   * @example
+   * field.reference(customers, { title: "Customer" })
+   */
+  reference: <T extends Record<string, TSchema>>(collection: Collection<T>, options?: {
+    title?: string;
+    required?: boolean;
+  }) => ReferenceSchema<T>;
+  /**
+   * An ordered list of distinct records of `collection`; each resolves independently.
+   * An empty list is always valid, so there is no `required` or `minItems`.
+   * `toMarkdown` renders each linked record (one list item per record, in stored order);
+   * the block's own `toMarkdown` includes the whole list through its token.
+   *
+   * With `query`, the list is query-backed: code defines its membership and order, editors
+   * cannot pick, remove or reorder records, and nothing is stored on the block.
    *
    * @example
-   * Type.Repeater({
-   *   content: {
-   *     title: Type.String({ default: 'Item' }),
-   *     description: Type.String({ default: 'Description' }),
-   *   },
-   *   settings: {
-   *     highlighted: Type.Boolean({ default: false, title: 'Highlighted' }),
-   *   },
+   * field.referenceList(customers, { maxItems: 6, toMarkdown: (c) => [c.name] })
+   * field.referenceList(articles, { query: { orderBy: { publishedAt: "desc" }, limit: 3 } })
+   */
+  referenceList: <T extends Record<string, TSchema>, const L extends number = number>(collection: Collection<T>, options?: {
+    title?: string;
+    description?: string;
+    maxItems?: number;
+    query?: ReferenceQuery<T, L>;
+    toMarkdown?: ToMarkdownBuilder<T>;
+  }) => ReferenceListSchema<T>;
+  /**
+   * Repeatable items, each with its own content and optional settings. Repeaters may nest.
+   * Item settings are edited in the sidebar when the item is selected.
+   *
+   * @example
+   * field.repeater({
+   *   content: (field) => ({
+   *     title: field.string({ default: "Item" }),
+   *     description: field.string({ default: "Description" }),
+   *   }),
+   *   settings: (setting) => ({
+   *     highlighted: setting.boolean({ default: false, title: "Highlighted" }),
+   *   }),
    *   minItems: 1,
    *   maxItems: 10,
-   *   title: 'Items',
-   *   toMarkdown: (c) => [`### ${c.title}`, c.description],
+   *   title: "Items",
+   *   toMarkdown: (c, s) => [`### ${c.title}`, s.highlighted(c.description)],
    * })
    */
-  Repeater: <T extends Record<string, TSchema>, S extends Record<string, TSchema> = Record<string, never>>(options: {
-    content: T;
-    settings?: S;
+  repeater: <T extends Record<string, TSchema>, S extends Record<string, TSchema> = Record<string, never>>(options: {
+    content: (field: ContentFieldBuilder) => T & NoInfer<ArtifactDataCheck<T, S>>;
+    settings?: (setting: SettingBuilder) => S;
     minItems: number;
     maxItems: number;
     title?: string;
     toMarkdown: ToMarkdownBuilder<T, S>;
-  }) => TArray<TObject<T>> & WithItemSettings<S>;
+  }) => RepeaterField<T, S>;
+}
+/** Content fields that can't be Artifact Data: artifact sources, repeaters and references. */
+type UnsharedField = {
+  fieldType: "Artifact" | "Reference" | "ReferenceList";
+} | TArray<TObject<any>>;
+/** The sibling names an artifact can list in `data`: shared content fields, then settings. */
+export type ArtifactDataName<T extends Record<string, TSchema>, S extends Record<string, TSchema>> = { [K in keyof T & string]: T[K] extends UnsharedField ? never : K; }[keyof T & string] | (string extends keyof S ? never : keyof S & string);
+/**
+ * Checks each artifact's `data` against its siblings. Applied to the `content` callback's return
+ * type, because callback parameters are context-sensitive (ADR 0001).
+ */
+export type ArtifactDataCheck<T extends Record<string, TSchema>, S extends Record<string, TSchema>> = true extends HasAnyField<T> ? unknown : { [K in ArtifactKey<T>]: ArtifactField<ArtifactDataName<T, S>>; };
+/** Shapes with fields that already fail to type check (`any`) are left to that error. */
+type HasAnyField<T extends Record<string, TSchema>> = { [K in keyof T]-?: 0 extends 1 & T[K] ? true : false; }[keyof T];
+type ArtifactKey<T extends Record<string, TSchema>> = { [K in keyof T & string]-?: T[K] extends {
+  fieldType: "Artifact";
+} ? K : never; }[keyof T & string];
+/**
+ * Builds the settings of a block or repeatable item: presentation options edited in the
+ * sidebar, never inline. Only `enum` and `boolean` are settings.
+ */
+export interface SettingBuilder {
   /**
-   * Creates an enum field with a set of predefined options.
+   * One of a fixed set of options; keys are stored, values are editor labels.
    *
    * @example
-   * Type.Enum({
-   *   default: 'left',
-   *   options: { left: 'Left', center: 'Center', right: 'Right' },
-   *   title: 'Alignment'
-   * })
+   * setting.enum({ default: "left", options: { left: "Left", right: "Right" }, title: "Alignment" })
    */
-  Enum: <const O extends Record<string, string>>(options: {
+  enum: <const O extends Record<string, string>>(options: {
     default: keyof O & string;
     options: O;
     title?: string;
-  }) => TUnsafe<keyof O & string>;
+  }) => EnumSetting<O>;
   /**
-   * Creates a boolean toggle field.
+   * A toggle.
    *
    * @example
-   * Type.Boolean({ default: false, title: 'Show background' })
+   * setting.boolean({ default: false, title: "Show background" })
    */
-  Boolean: (options: {
+  boolean: (options: {
     default: boolean;
     title?: string;
-  }) => _$_sinclair_typebox0.TBoolean;
+  }) => BooleanSetting;
+}
+/**
+ * Builds the fields of a collection record. Records are created through an authoring form, so
+ * `string` needs no default. Collections have no settings: `enum` and `boolean` are content here.
+ */
+export interface CollectionFieldBuilder extends Pick<ContentFieldBuilder, "imageList" | "fileList" | "embed"> {
   /**
-   * Creates an embed field for URLs matching a specific pattern.
+   * An image asset. Never required: collection fields can't be (the API rejects it).
    *
    * @example
-   * Type.Embed({
-   *   pattern: 'https:\\/\\/(www\\.)?youtube\\.com\\/watch\\?v=.+',
-   *   default: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
-   *   title: 'YouTube URL'
-   * })
+   * field.image({ title: "Cover" })
    */
-  Embed: (options: {
-    pattern: string;
-    default: string;
+  image: (options?: {
     title?: string;
-  }) => TUnsafe<EmbedURL>;
+  }) => ImageField;
   /**
-   * Creates a link field with text, href/pageId, and newTab properties.
-   * Supports both external URLs and internal page links.
+   * A file asset. Never required: collection fields can't be (the API rejects it).
    *
    * @example
-   * Type.Link({ default: { text: 'Learn more', href: '/', newTab: false }, title: 'CTA' })
+   * field.file({ accept: ["application/pdf"], title: "Brochure" })
    */
-  Link: (options: {
-    default: {
-      text: string;
-      href: string;
-      newTab: boolean;
-    };
+  file: (options: {
+    accept: string[];
     title?: string;
-  }) => TUnsafe<LinkValue>;
+  }) => FileField;
   /**
-   * Creates an image asset field.
+   * An ordered list of distinct records of another collection, e.g. an article's co-authors.
+   * Collections hold manual lists only: a query would fan out across a whole collection.
    *
    * @example
-   * Type.Image({ title: 'Hero' })
+   * field.referenceList(authors, { title: "Co-authors" })
    */
-  Image: (options?: {
+  referenceList: <T extends Record<string, TSchema>>(collection: Collection<T>, options?: {
     title?: string;
-  }) => TUnsafe<ImageValue>;
+    description?: string;
+    maxItems?: number;
+    toMarkdown?: ToMarkdownBuilder<T>;
+  }) => ReferenceListSchema<T>;
   /**
-   * Creates a file asset field.
+   * Selects a record of another collection by identity, e.g. an article's author. Never
+   * required: an unpublished record resolves empty on the live site.
    *
    * @example
-   * Type.File({ accept: ['application/pdf'], title: 'Datasheet' })
+   * field.reference(authors, { title: "Author" })
    */
-  File: (options: {
-    accept: string[];
+  reference: <T extends Record<string, TSchema>>(collection: Collection<T>, options?: {
     title?: string;
-  }) => TUnsafe<FileValue>;
+  }) => ReferenceSchema<T>;
   /**
-   * Creates an array of image assets.
+   * A text field.
    *
    * @example
-   * Type.ImageList({ title: 'Gallery', defaultItems: 3 })
+   * field.string({ minLength: 1, title: "Name" })
    */
-  ImageList: (options?: {
-    title?: string;
-    defaultItems?: number;
-  }) => TArray<TUnsafe<ImageValue>>;
+  string: (options?: StringOptions & {
+    default?: string;
+  }) => StringField;
   /**
-   * Creates an array of file assets.
+   * One of a fixed set of options; keys are stored, values are editor labels.
    *
    * @example
-   * Type.FileList({ accept: ['application/pdf'], title: 'Attachments' })
+   * field.enum({ default: "draft", options: { draft: "Draft", final: "Final" } })
    */
-  FileList: (options: {
-    accept: string[];
-    title?: string;
-    defaultItems?: number;
-  }) => TArray<TUnsafe<FileValue>>;
-};
+  enum: SettingBuilder["enum"];
+  /**
+   * A toggle.
+   *
+   * @example
+   * field.boolean({ default: false, title: "Featured" })
+   */
+  boolean: SettingBuilder["boolean"];
+}
 //#endregion
-export { EmbedURL, FileValue, ImageValue, ItemSettingsBrand, LinkValue, ToMarkdownBuilder, Type$1 as Type };
+export {};