@vexcms/core 0.0.20 → 0.1.0-alpha.3

package/dist/fields/blocks/types.d.ts

@@ -0,0 +1,253 @@
+import { ADMIN_FIELDS } from "../constants";
+import type { BaseField, BaseFieldInput, FieldAdminConfigInput } from "../baseTypes";
+import type { AdminField } from "../types";
+import { LucideIconName } from "../../utils";
+import type { FieldAdminConfig } from "../baseTypes";
+/**
+ * Field names reserved by the blocks system.
+ *
+ * These names are injected automatically on every block item stored in Convex
+ * and cannot be used as user field names inside `defineBlock({ fields: { ... } })`.
+ *
+ * - `blockType` — discriminant identifying the block's definition (e.g. `"heading"`)
+ * - `blockName` — user-editable label stored alongside the block data
+ * - `id`       — stable UUID assigned on creation; used as the React key and
+ *                  pre-requisites drag-and-drop reorder
+ */
+export declare const RESERVED_BLOCK_FIELD_NAMES: readonly ["blockType", "blockName", "id"];
+/**
+ * A Generic Block shape that all block data will follow coming out of Convex
+ */
+export interface GenericBlock extends Record<string, any> {
+    id: string;
+    blockType: string;
+    blockName?: string;
+}
+/**
+ * Admin UI configuration for a single block definition.
+ *
+ * @see {@link BlockConfigInput}
+ */
+export interface BlockAdminConfig {
+    /**
+     * Lucide icon name shown next to the block label in the picker dialog.
+     *
+     * Typed as `string` in `@vexcms/core` to avoid a React dependency.
+     * Rendered via the existing `<Icon name={...}>` component in `@vexcms/react`.
+     *
+     * @example "Sparkles" | "Puzzle" | "Megaphone" | "CreditCard"
+     */
+    icon?: LucideIconName;
+    /**
+     * Whether this block starts expanded when the page loads.
+     *
+     * Default: `true` (block is open by default)
+     *
+     * Note: Controlled by the field-level `admin.defaultCollapsed` setting —
+     * when that is `true`, all blocks start collapsed regardless of this value.
+     */
+    defaultCollapsed?: boolean;
+}
+/**
+ * Configuration input for a single block type, passed to `defineBlock()`.
+ *
+ * A block definition describes one variant in a blocks field — its stored
+ * discriminant (`slug`), its display name in the admin picker (`label`), the
+ * fields that make up its data shape, and optional admin UI config (icon).
+ * Three fields are injected automatically on every block item and must not
+ * appear in `fields`: `blockType`, `blockName`, and `id`.
+ *
+ * **Defaults applied by `defineBlock()`:**
+ * ```ts
+ * {
+ *   interfaceName: slugToPascalCase(slug) + "Block",  // e.g. "heading" → "HeadingBlock"
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const headingBlock = defineBlock({
+ *   slug:  "heading",
+ *   label: "Heading",
+ *   admin: { icon: "heading" },
+ *   fields: {
+ *     level: select({ options: [{ label: "H1", value: "h1" }] }),
+ *     text:  text({ required: true }),
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link BlockConfig} for the resolved output type
+ * @see {@link defineBlock} for the config function that produces this type
+ */
+export interface BlockConfigInput {
+    /**
+     * Unique identifier for this block type.
+     *
+     * Stored as `blockType: "slug"` on every block item. Used as the Convex
+     * `v.literal()` discriminant and Zod `z.literal()` key. Must start with a
+     * letter and contain only letters, numbers, hyphens, and underscores
+     * (`/^[a-zA-Z][a-zA-Z0-9_-]*$/`).
+     */
+    slug: string;
+    name?: string;
+    /** Display label shown in the admin block-type picker and as the block header. */
+    label?: string;
+    /**
+     * Fields that make up this block's data shape.
+     *
+     * Accepts any `AdminField`, including nested `group()` or `array()`.
+     * `blockType`, `blockName`, and `id` are injected automatically — do not
+     * include them here. `defineBlock()` throws if any reserved name is used.
+     */
+    fields: Record<string, AdminField>;
+    /** Admin UI configuration (picker icon). */
+    admin?: BlockAdminConfig;
+    /**
+     * Custom TypeScript interface name for this block type.
+     *
+     * Defaults to `${slugToPascalCase(slug)}Block` (e.g. `"heading"` → `"HeadingBlock"`).
+     */
+    interfaceName?: string;
+}
+/**
+ * Resolved block type definition, after `defineBlock()` applies all defaults.
+ *
+ * @see {@link BlockConfigInput} for the user-facing input type
+ * @see {@link defineBlock} for the config function that produces this type
+ */
+export interface BlockConfig<TBlockMeta extends {} = {}> {
+    /** Unique discriminant value stored as `blockType` on every block item. */
+    blockType: string;
+    blockName?: string;
+    id: string;
+    /** Display label shown in the admin block-type picker. */
+    label?: string;
+    /** Fields that make up this block's data shape. */
+    fields: Record<string, AdminField>;
+    /** Admin UI configuration. */
+    admin?: BlockAdminConfig;
+    /**
+     * TypeScript interface name for this block type.
+     *
+     * Always set after `defineBlock()`. Defaults to `${slugToPascalCase(slug)}Block`.
+     */
+    interfaceName: string;
+    /**
+     * Computed TypeScript object-type string including all three framework keys.
+     *
+     * E.g. `{ blockType: "heading"; blockName?: string; id: string; text: string }`.
+     * Used by `getFieldInterfaces` to emit the block's `export type` declaration.
+     */
+    interfaceType: string;
+    metadata?: TBlockMeta;
+}
+/**
+ * Configuration input for a `blocks()` field.
+ *
+ * Blocks fields store an ordered, heterogeneous list of typed objects. Each item
+ * carries `blockType` (which block definition it matches), `id` (stable UUID),
+ * `blockName` (user-editable label), plus the fields from that block's definition.
+ *
+ * **Defaults applied by `blocks()`:**
+ * ```ts
+ * {
+ *   type:         "blocks",
+ *   label:        "",    // inferred from field key by defineCollection
+ *   required:     false,
+ *   defaultValue: [],
+ *   labels:       { singular: "block", plural: "blocks" },
+ *   admin: {
+ *     hidden: false, readOnly: false, position: "main", width: "full",
+ *     cellAlignment: "left",
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * body: blocks({
+ *   label:  "Body",
+ *   blocks: [headingBlock, paragraphBlock],
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Named union alias + min/max constraints
+ * body: blocks({
+ *   label:         "Body",
+ *   interfaceName: "PageBlock",
+ *   blocks:        [headingBlock, paragraphBlock],
+ *   min:           1,
+ *   max:           20,
+ *   labels:        { singular: "section", plural: "sections" },
+ * })
+ * ```
+ *
+ * @see {@link BlocksField} for the resolved output type
+ * @see {@link blocks} for the config function that produces this type
+ */
+export interface BlocksFieldInput<TFieldMeta extends {} = {}> extends Omit<BaseFieldInput<TFieldMeta>, "admin"> {
+    admin?: FieldAdminConfigInput & {
+        defaultCollapsed?: boolean;
+    };
+    /** Block type definitions that are allowed in this field. */
+    blocks: BlockConfig<TFieldMeta>[];
+    /**
+     * Optional TypeScript union alias name.
+     *
+     * When set, emits `export type PageBlock = HeadingBlock | ParagraphBlock` and
+     * the collection interface uses `PageBlock[]` instead of the inline union.
+     */
+    interfaceName?: string;
+    /**
+     * Minimum number of block items.
+     *
+     * Enforced by the Zod inputSchema (form validation), not the Convex schema.
+     * Does not affect the generated `vex.schema.ts`.
+     */
+    min?: number;
+    /**
+     * Maximum number of block items.
+     *
+     * Enforced by the Zod inputSchema. When the max is reached, the "Add" button
+     * is disabled in the admin UI.
+     */
+    max?: number;
+    /** Singular/plural display labels used in the admin UI. Defaults to `{ singular: "block", plural: "blocks" }`. */
+    labels?: {
+        singular: string;
+        plural: string;
+    };
+    /** Pre-filled value when creating a new document. Defaults to `[]`. */
+    defaultValue?: Record<string, unknown>[];
+}
+/**
+ * Resolved configuration for a `blocks()` field, after all defaults are applied.
+ *
+ * @see {@link BlocksFieldInput} for the user-facing input type
+ * @see {@link blocks} for the config function that produces this type
+ */
+export interface BlocksField<TFieldMeta extends {} = {}> extends BaseField<TFieldMeta> {
+    readonly type: typeof ADMIN_FIELDS.blocks.type;
+    admin: FieldAdminConfig & {
+        defaultCollapsed: boolean;
+    };
+    /** Block type definitions allowed in this field. */
+    blocks: BlockConfig<TFieldMeta>[];
+    /** Optional TypeScript union alias name. */
+    interfaceName?: string;
+    /** Minimum number of block items (Zod-enforced). */
+    min?: number;
+    /** Maximum number of block items (Zod-enforced). */
+    max?: number;
+    /** Singular/plural display labels for the admin UI. */
+    labels: {
+        singular: string;
+        plural: string;
+    };
+    /** Pre-filled value when creating a new document. */
+    defaultValue: Record<string, unknown>[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/fields/blocks/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/fields/blocks/types.ts"],"names":[],"mappings":"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"}

package/dist/fields/blocks/validator.d.ts

@@ -0,0 +1,32 @@
+import type { BlocksField } from "./types";
+/**
+ * Converts a blocks field definition to a Convex schema validator string.
+ *
+ * Each block type becomes a `v.object()` with three framework keys first —
+ * `blockType: v.literal(slug)`, `blockName: v.optional(v.string())`,
+ * `id: v.string()` — followed by the block's own field validators. Multiple
+ * block types are combined with `v.union()`; a single block type uses a bare
+ * `v.object()`. The whole thing is wrapped in `v.array()`, then `v.optional()`
+ * when `field.required` is `false`.
+ *
+ * @param props - Input props.
+ * @param props.field - The resolved blocks field definition.
+ * @returns A Convex validator string.
+ *
+ * @example
+ * ```ts
+ * const heading   = defineBlock({ slug: "heading",   fields: { text: text({ required: true }) } })
+ * const paragraph = defineBlock({ slug: "paragraph", fields: { content: text() } })
+ * blocksFieldToValidator({ field: blocks({ blocks: [heading, paragraph] }) })
+ * // → 'v.optional(v.array(v.union(
+ * //      v.object({ blockType: v.literal("heading"), blockName: v.optional(v.string()), id: v.string(), text: v.string() }),
+ * //      v.object({ blockType: v.literal("paragraph"), blockName: v.optional(v.string()), id: v.string(), content: v.optional(v.string()) }),
+ * //    )))'
+ * ```
+ *
+ * @internal — Used by CLI schema generation via `adminFieldToValidator`.
+ */
+export declare function blocksFieldToValidator<TFieldMeta extends {} = {}>(props: {
+    field: BlocksField<TFieldMeta>;
+}): string;
+//# sourceMappingURL=validator.d.ts.map

package/dist/fields/blocks/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../../src/fields/blocks/validator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,SAAS,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE;IACxE,KAAK,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;CAChC,GAAG,MAAM,CAiCT"}

package/dist/fields/checkbox/config.d.ts

@@ -0,0 +1,46 @@
+import { BaseFieldMeta } from "../types";
+import type { CheckboxFieldInput, CheckboxField } from "./types";
+/**
+ * Creates a checkbox field with all defaults applied.
+ *
+ * Checkbox fields store boolean values — feature flags, opt-in toggles,
+ * published states, visibility flags, and similar on/off settings.
+ *
+ * Accepts {@link CheckboxFieldInput} (all optional) and returns {@link CheckboxField} with all defaults applied.
+ *
+ * **Defaults applied:**
+ * - `label` — `""` (inferred from the field key by `defineCollection`)
+ * - `required` — `false`
+ * - `defaultValue` — `false`
+ * - `admin.hidden` — `false`
+ * - `admin.readOnly` — `false`
+ * - `admin.position` — `"main"`
+ * - `admin.width` — `"full"`
+ * - `admin.cellAlignment` — `"left"`
+ *
+ * @param options - Checkbox field configuration. All properties are optional.
+ * @returns Resolved checkbox field definition with all defaults applied.
+ *
+ * @example
+ * ```ts
+ * import { checkbox, defineCollection } from '@vexcms/core'
+ *
+ * posts: defineCollection({
+ *   fields: {
+ *     // Minimal — label inferred from key ("Published")
+ *     published: checkbox(),
+ *
+ *     // Required field, checked by default when creating a new document
+ *     featured: checkbox({ defaultValue: true, admin: { width: "half" } }),
+ *
+ *     // Indexed flag for fast admin queries
+ *     archived: checkbox({ index: "by_archived" }),
+ *   }
+ * })
+ * ```
+ *
+ * @see {@link CheckboxFieldInput} for the full input type
+ * @see {@link CheckboxField} for the resolved output type
+ */
+export declare function checkbox<TFieldMeta extends BaseFieldMeta = BaseFieldMeta>(options?: CheckboxFieldInput<TFieldMeta>): CheckboxField<TFieldMeta>;
+//# sourceMappingURL=config.d.ts.map

package/dist/fields/checkbox/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/fields/checkbox/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,QAAQ,CAAC,UAAU,SAAS,aAAa,GAAG,aAAa,EACvE,OAAO,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,GACvC,aAAa,CAAC,UAAU,CAAC,CAyB3B"}

package/dist/fields/checkbox/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./config";
+export * from "./types";
+export * from "./validator";
+export * from "./inputSchema";
+//# sourceMappingURL=index.d.ts.map

package/dist/fields/checkbox/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/fields/checkbox/index.ts"],"names":[],"mappings":"AACA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/dist/fields/checkbox/inputSchema.d.ts

@@ -0,0 +1,27 @@
+import { ZodType } from "zod";
+import { CheckboxField } from "./types";
+/**
+ * Builds a Zod schema for validating a checkbox field value in the admin form.
+ *
+ * Checkbox fields are always boolean — there are no required/optional semantics
+ * beyond wrapping in `.optional()` for non-required fields. No min/max constraints.
+ *
+ * @param props - Input props.
+ * @param props.field - The resolved checkbox field definition
+ * @returns A Zod boolean schema with optionality and default applied
+ *
+ * @example
+ * ```ts
+ * const field = checkbox({ required: true })
+ * checkboxFieldToInputSchema({ field })
+ * // → z.boolean()
+ *
+ * const optionalField = checkbox()
+ * checkboxFieldToInputSchema({ field: optionalField })
+ * // → z.boolean().optional().default(false)
+ * ```
+ */
+export declare function checkboxFieldToInputSchema(props: {
+    field: CheckboxField;
+}): ZodType;
+//# sourceMappingURL=inputSchema.d.ts.map

package/dist/fields/checkbox/inputSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputSchema.d.ts","sourceRoot":"","sources":["../../../src/fields/checkbox/inputSchema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,KAAK,EAAE,aAAa,CAAC;CACtB,GAAG,OAAO,CAMV"}

package/dist/fields/checkbox/types.d.ts

@@ -0,0 +1,67 @@
+import { ADMIN_FIELDS } from "../constants";
+import { BaseField, BaseFieldInput, FieldAdminConfig } from "../baseTypes";
+/**
+ * Configuration input for a `checkbox()` field.
+ *
+ * Checkbox fields store boolean values — feature flags, opt-in toggles,
+ * published states, and similar on/off settings. All properties are optional;
+ * unset properties fall back to the defaults listed below.
+ *
+ * **Defaults applied by `checkbox()`:**
+ * ```ts
+ * {
+ *   type:         "checkbox",
+ *   label:        "",     // inferred from the field key by defineCollection
+ *   required:     false,  // field is optional by default
+ *   defaultValue: false,  // unchecked when creating a new document
+ *   admin: {
+ *     hidden:        false,   // visible in the admin form
+ *     readOnly:      false,   // editable by default
+ *     position:      "main",  // placed in the main content column, not the sidebar
+ *     width:         "full",  // spans the full form width, not half
+ *     cellAlignment: "left",  // value aligned left in the data table column
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Minimal — label inferred from the key ("Published")
+ * published: checkbox()
+ *
+ * // Checked by default when creating a new document
+ * featured: checkbox({ defaultValue: true, admin: { width: "half" } })
+ *
+ * // Indexed flag for fast admin queries
+ * archived: checkbox({ index: "by_archived" })
+ * ```
+ *
+ * @see {@link CheckboxField} for the resolved type after defaults are applied
+ * @see {@link checkbox} for the config function that applies defaults
+ * @see {@link BaseFieldInput} for shared properties (`label`, `description`, `required`, `admin`, `index`, `searchIndex`)
+ */
+export interface CheckboxFieldInput<TFieldMeta extends {} = {}> extends BaseFieldInput<TFieldMeta> {
+    /**
+     * Pre-filled value shown in the admin form when creating a new document.
+     * Does not affect database values — only the form's initial state.
+     */
+    defaultValue?: boolean;
+}
+/**
+ * Resolved configuration for a `checkbox()` field, after all defaults are applied.
+ *
+ * @see {@link CheckboxFieldInput} for the user-facing input type
+ * @see {@link checkbox} for the config function that produces this type
+ */
+export interface CheckboxField<TFieldMeta extends {} = {}> extends BaseField<TFieldMeta> {
+    readonly type: typeof ADMIN_FIELDS.checkbox.type;
+    /** Display label shown in the admin form. Always set — inferred from the field key if not provided. */
+    label: string;
+    /** Whether this field is required in the database schema. */
+    required: boolean;
+    /** Resolved admin UI configuration with all defaults applied. */
+    admin: FieldAdminConfig;
+    /** Pre-filled boolean value shown in the admin form when creating a new document. */
+    defaultValue: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/fields/checkbox/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/fields/checkbox/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,WAAW,kBAAkB,CACjC,UAAU,SAAS,EAAE,GAAG,EAAE,CAC1B,SAAQ,cAAc,CAAC,UAAU,CAAC;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,UAAU,SAAS,EAAE,GAAG,EAAE,CAAE,SAAQ,SAAS,CAAC,UAAU,CAAC;IACtF,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC;IACjD,uGAAuG;IACvG,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,QAAQ,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE,gBAAgB,CAAC;IACxB,qFAAqF;IACrF,YAAY,EAAE,OAAO,CAAC;CACvB"}

package/dist/fields/checkbox/validator.d.ts

@@ -0,0 +1,34 @@
+import type { CheckboxField } from "./types";
+/**
+ * Converts a checkbox field definition to a Convex schema validator.
+ *
+ * Generates the appropriate `v.boolean()` or `v.optional(v.boolean())` code
+ * for the Convex schema based on the field's `required` property.
+ *
+ * **Important notes:**
+ * - The `required` flag is the only property that affects the generated validator.
+ * - `index` is handled separately by collection index logic.
+ * - This function is used by the CLI during schema generation to build the Convex schema file.
+ *
+ * @param props - checkboxFieldToValidator() input props
+ * @param props.field - The checkbox field definition
+ * @returns Convex value type string: `"v.boolean()"` or `"v.optional(v.boolean())"`
+ *
+ * @example
+ * ```ts
+ * const field1 = checkbox({ required: true })
+ * checkboxFieldToValidator({ field: field1 })  // "v.boolean()"
+ *
+ * const field2 = checkbox({ required: false })
+ * checkboxFieldToValidator({ field: field2 })  // "v.optional(v.boolean())"
+ *
+ * const field3 = checkbox()
+ * checkboxFieldToValidator({ field: field3 })  // "v.optional(v.boolean())"
+ * ```
+ *
+ * @internal - Used by schema generation, not typically called by users
+ */
+export declare function checkboxFieldToValidator(props: {
+    field: CheckboxField;
+}): string;
+//# sourceMappingURL=validator.d.ts.map

package/dist/fields/checkbox/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../../src/fields/checkbox/validator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,KAAK,EAAE,aAAa,CAAC;CACtB,GAAG,MAAM,CAKT"}

package/dist/fields/color/config.d.ts

@@ -0,0 +1,49 @@
+import { BaseFieldMeta } from "../types";
+import type { ColorFieldInput, ColorField } from "./types";
+/**
+ * Creates a colour field with all defaults applied.
+ *
+ * Colour fields store a CSS colour string and render a swatch picker in the
+ * admin form. Common uses: theme palettes, per-document accent colours, block
+ * background overrides.
+ *
+ * Accepts {@link ColorFieldInput} (all optional) and returns {@link ColorField} with all defaults applied.
+ *
+ * **Defaults applied:**
+ * - `label` — `""` (inferred from the field key by `defineCollection`)
+ * - `required` — `false`
+ * - `defaultValue` — `""`
+ * - `format` — `"hex"`
+ * - `themeColors` — `false`
+ * - `admin.hidden` — `false`
+ * - `admin.readOnly` — `false`
+ * - `admin.position` — `"main"`
+ * - `admin.width` — `"full"`
+ * - `admin.cellAlignment` — `"left"`
+ *
+ * @param options - Colour field configuration. All properties are optional.
+ * @returns Resolved colour field definition with all defaults applied.
+ *
+ * @example
+ * ```ts
+ * import { color, defineCollection } from '@vexcms/core'
+ *
+ * themes: defineCollection({
+ *   fields: {
+ *     // Minimal — label inferred from key ("Brand Color"), stored as hex
+ *     brandColor: color(),
+ *
+ *     // Stored as oklch so the front end can interpolate it directly
+ *     primaryLight: color({ format: "oklch", required: true }),
+ *
+ *     // Offer the host app's design tokens as a second picker tab
+ *     overlayTint: color({ themeColors: true, admin: { width: "half" } }),
+ *   }
+ * })
+ * ```
+ *
+ * @see {@link ColorFieldInput} for the full input type
+ * @see {@link ColorField} for the resolved output type
+ */
+export declare function color<TFieldMeta extends BaseFieldMeta = BaseFieldMeta>(options?: ColorFieldInput<TFieldMeta>): ColorField<TFieldMeta>;
+//# sourceMappingURL=config.d.ts.map

package/dist/fields/color/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/fields/color/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,KAAK,CAAC,UAAU,SAAS,aAAa,GAAG,aAAa,EACpE,OAAO,CAAC,EAAE,eAAe,CAAC,UAAU,CAAC,GACpC,UAAU,CAAC,UAAU,CAAC,CA8BxB"}

package/dist/fields/color/convert.d.ts

@@ -0,0 +1,72 @@
+import { type ColorFormat } from "./formats";
+/**
+ * A colour in 8-bit sRGB with straight (non-premultiplied) alpha.
+ *
+ * This is the pivot representation for every notation: parsing produces one,
+ * serialising consumes one. sRGB rather than HSV because HSV is a *picker's*
+ * working model — `@uiw/react-color-sketch` happens to use it — while sRGB is
+ * what every CSS notation converts to and from.
+ *
+ * @example
+ * ```ts
+ * const ember: ColorValue = { r: 232, g: 98, b: 42, a: 1 };
+ * ```
+ */
+export interface ColorValue {
+    /** Red channel, `0`–`255`. */
+    r: number;
+    /** Green channel, `0`–`255`. */
+    g: number;
+    /** Blue channel, `0`–`255`. */
+    b: number;
+    /** Alpha, `0`–`1`. `1` is fully opaque. */
+    a: number;
+}
+/**
+ * Serialises a colour into one of the supported CSS notations.
+ *
+ * Alpha is emitted only when the colour is not fully opaque, so an opaque
+ * colour produces `#e8622a` rather than `#e8622aff` and `rgb(...)` rather than
+ * `rgba(..., 1)`.
+ *
+ * @param props - Input props.
+ * @param props.color - The colour to write.
+ * @param props.format - The notation to write it in.
+ * @returns A CSS colour string in `format`.
+ * @throws An Error if an unrecognised format is given. Reaching this is a
+ * compile error: the default arm binds the exhausted union to `never`.
+ *
+ * @example
+ * ```ts
+ * const ember = { r: 232, g: 98, b: 42, a: 1 };
+ * serializeColor({ color: ember, format: "hex" })   // "#e8622a"
+ * serializeColor({ color: ember, format: "oklch" }) // "oklch(65.7% 0.1793 40.9)"
+ * ```
+ */
+export declare function serializeColor(props: {
+    color: ColorValue;
+    format: ColorFormat;
+}): string;
+/**
+ * Parses a stored colour value into a {@link ColorValue}.
+ *
+ * Accepts every notation {@link serializeColor} can emit, regardless of the
+ * field's current `format` — so a field whose format changed still reads its
+ * stored colour instead of resetting. Values with no literal colour
+ * (`var(--token)`, the empty string) return `null`.
+ *
+ * @param props - Input props.
+ * @param props.value - The stored field value.
+ * @returns The parsed colour, or `null` when the value is empty, a theme-token
+ * reference, or not a recognised notation.
+ *
+ * @example
+ * ```ts
+ * parseColor({ value: "oklch(65.7% 0.1793 40.9)" }) // { r: 232, g: 98, b: 42, a: 1 }
+ * parseColor({ value: "var(--primary)" })           // null
+ * ```
+ */
+export declare function parseColor(props: {
+    value: string;
+}): ColorValue | null;
+//# sourceMappingURL=convert.d.ts.map

package/dist/fields/color/convert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../../src/fields/color/convert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,CAAC,EAAE,MAAM,CAAC;IACV,gCAAgC;IAChC,CAAC,EAAE,MAAM,CAAC;IACV,+BAA+B;IAC/B,CAAC,EAAE,MAAM,CAAC;IACV,2CAA2C;IAC3C,CAAC,EAAE,MAAM,CAAC;CACX;AAoPD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAAG,MAAM,CAqCxF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,GAAG,IAAI,CAgDtE"}

package/dist/fields/color/formats.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Supported storage notations for a `color()` field, keyed by format name.
+ *
+ * Each entry carries the anchored pattern that recognises values written in
+ * that notation. The patterns accept exactly what `serializeColor` in
+ * `@vexcms/react` emits, plus the equivalent hand-typed spellings.
+ *
+ * @internal
+ */
+export declare const COLOR_FORMATS: {
+    readonly hex: {
+        readonly format: "hex";
+        /** `#E8622A`, `#E8622A80`. Shorthand is rejected — the picker never emits it. */
+        readonly pattern: RegExp;
+    };
+    readonly rgb: {
+        readonly format: "rgb";
+        /** `rgb(232, 98, 42)`, `rgba(232, 98, 42, 0.5)`. */
+        readonly pattern: RegExp;
+    };
+    readonly hsl: {
+        readonly format: "hsl";
+        /** `hsl(17.7, 81%, 54%)`, `hsla(17.7, 81%, 54%, 0.5)`. */
+        readonly pattern: RegExp;
+    };
+    readonly oklch: {
+        readonly format: "oklch";
+        /** `oklch(65.7% 0.179 40.9)`, `oklch(65.7% 0.179 40.9 / 0.5)`. */
+        readonly pattern: RegExp;
+    };
+};
+/** Union of the notations a `color()` field can store: `"hex" | "rgb" | "hsl" | "oklch"`. */
+export type ColorFormat = (typeof COLOR_FORMATS)[keyof typeof COLOR_FORMATS]["format"];
+/** Every supported notation's pattern, in declaration order. */
+export declare const COLOR_FORMAT_PATTERNS: RegExp[];
+/** A value that is entirely one CSS custom-property reference: `var(--primary)`. */
+export declare const CSS_VAR_REFERENCE: RegExp;
+//# sourceMappingURL=formats.d.ts.map