@vexcms/core 0.0.8 → 0.0.10

package/dist/index.d.ts

@@ -5,6 +5,115 @@ import { VObject, GenericValidator, ObjectType, PropertyValidators, v } from 'co
 import { ColumnDef } from '@tanstack/react-table';
 import { ZodTypeAny, z } from 'zod';
 
+/**
+ * The style tier identifiers that a block can declare in admin.blockStyles.
+ * Each tier corresponds to a section in the style popover and a set of CSS properties.
+ */
+type StyleTier = "container" | "text" | "layout" | "media";
+/**
+ * Container styles — universal layout/visual properties applied to the block's outer wrapper.
+ * All values are Tailwind scale keys (e.g., "4" → 1rem/16px) or color strings.
+ */
+interface ContainerStyleConfig {
+    /** Tailwind margin scale value. Shorthand: applies to all sides. */
+    margin?: string;
+    marginTop?: string;
+    marginRight?: string;
+    marginBottom?: string;
+    marginLeft?: string;
+    /** Tailwind padding scale value. */
+    padding?: string;
+    paddingTop?: string;
+    paddingRight?: string;
+    paddingBottom?: string;
+    paddingLeft?: string;
+    /** Tailwind width class key (e.g., "full", "1/2", "screen"). */
+    width?: string;
+    /** Tailwind max-width class key. */
+    maxWidth?: string;
+    /** Background color — CSS color string or CSS variable reference. */
+    backgroundColor?: string;
+    /** Border width — Tailwind border width key (e.g., "", "2", "4"). */
+    borderWidth?: string;
+    /** Border color — CSS color string or CSS variable reference. */
+    borderColor?: string;
+    /** Border style. */
+    borderStyle?: "solid" | "dashed" | "dotted" | "none";
+    /** Tailwind border radius key (e.g., "sm", "md", "lg", "full"). */
+    borderRadius?: string;
+    /** Tailwind box shadow key (e.g., "sm", "md", "lg", "xl", "2xl", "none"). */
+    boxShadow?: string;
+    /** Tailwind opacity value (e.g., "0", "25", "50", "75", "100"). */
+    opacity?: string;
+    /** Display value. */
+    display?: "block" | "flex" | "grid" | "none" | "inline-flex";
+    /** Overflow value. */
+    overflow?: "hidden" | "scroll" | "auto" | "visible";
+}
+/**
+ * Text styles — typography properties for text-heavy blocks.
+ */
+interface TextStyleConfig {
+    /** Text alignment. */
+    textAlign?: "left" | "center" | "right" | "justify";
+    /** Tailwind font size key (e.g., "sm", "base", "lg", "xl", "2xl"). */
+    fontSize?: string;
+    /** Tailwind font weight key (e.g., "normal", "medium", "semibold", "bold"). */
+    fontWeight?: string;
+    /** Text color — CSS color string or CSS variable reference. */
+    color?: string;
+    /** Tailwind line height key (e.g., "tight", "snug", "normal", "relaxed"). */
+    lineHeight?: string;
+    /** Tailwind letter spacing key (e.g., "tighter", "tight", "normal", "wide"). */
+    letterSpacing?: string;
+}
+/**
+ * Layout styles — for blocks that contain child elements in flex/grid layouts.
+ */
+interface LayoutStyleConfig {
+    /** Tailwind gap scale value. */
+    gap?: string;
+    /** Flex direction. */
+    flexDirection?: "row" | "column" | "row-reverse" | "column-reverse";
+    /** Align items. */
+    alignItems?: "start" | "center" | "end" | "stretch" | "baseline";
+    /** Justify content. */
+    justifyContent?: "start" | "center" | "end" | "between" | "around" | "evenly";
+    /** Flex wrap. */
+    flexWrap?: "wrap" | "nowrap" | "wrap-reverse";
+}
+/**
+ * Media styles — for blocks with background images or media elements.
+ */
+interface MediaStyleConfig {
+    /** Object fit for background/media elements. */
+    objectFit?: "cover" | "contain" | "fill" | "none" | "scale-down";
+    /** Aspect ratio (e.g., "video", "square", "auto", or custom like "4/3"). */
+    aspectRatio?: string;
+    /** Object position (e.g., "center", "top", "bottom"). */
+    objectPosition?: string;
+}
+/**
+ * Combined style config for a single breakpoint.
+ * Which properties are present depends on the block's declared style tiers.
+ */
+interface BlockStyleValues extends ContainerStyleConfig, TextStyleConfig, LayoutStyleConfig, MediaStyleConfig {
+}
+/**
+ * The full blockStyles structure stored as JSON string.
+ * Keys are breakpoint names ("base" is always present, others come from config).
+ *
+ * @example
+ * ```json
+ * {
+ *   "base": { "margin": "4", "padding": "2", "backgroundColor": "#fff" },
+ *   "sm": { "margin": "6" },
+ *   "lg": { "margin": "8", "padding": "4" }
+ * }
+ * ```
+ */
+type BlockStylesData = Record<string, BlockStyleValues>;
+
 /**
  * A rich text document is an array of Slate/Plate element nodes.
  * This is the canonical type for all rich text content stored in VEX.
@@ -458,13 +567,21 @@ type UploadFieldDef = UploadFieldSingle | UploadFieldMany;
 interface JsonFieldDef extends BaseField {
     readonly type: "json";
 }
+/** Object field definition. Stores a named group of sub-fields as `v.object()`. */
+interface ObjectFieldDef extends BaseField {
+    readonly type: "object";
+    /** Named sub-fields that make up this object. */
+    fields: Record<string, VexField>;
+}
 /** Array field definition. Wraps an inner field in `v.array()`. */
 interface ArrayFieldDef extends BaseField {
     readonly type: "array";
     /** Display labels for the field (singular/plural). */
     labels?: Labels;
-    /** The inner field type for array elements. */
-    field: VexField;
+    /** The field type for each item in the array. */
+    items: VexField;
+    /** Default value for the array (used when creating new documents/blocks). */
+    defaultValue?: unknown[];
     /** Minimum number of items. */
     min?: number;
     /** Maximum number of items. */
@@ -487,6 +604,88 @@ interface RichTextFieldDef extends BaseField {
      */
     mediaCollection?: string;
 }
+/**
+ * Color picker field. Stores a color string in the configured format.
+ *
+ * @example
+ * ```ts
+ * accentColor: color({ label: "Accent Color", format: "hex" })
+ * primaryColor: color({ label: "Primary", format: "oklch", themeColors: true })
+ * ```
+ */
+interface ColorFieldDef extends BaseField {
+    readonly type: "color";
+    /**
+     * Default color value.
+     * Should be in the configured format (hex, hsl, or oklch).
+     */
+    defaultValue?: string;
+    /**
+     * Output format for the color value.
+     * - "hex" — e.g., "#3b82f6" (default)
+     * - "hsl" — e.g., "hsl(217, 91%, 60%)"
+     * - "oklch" — e.g., "oklch(0.623 0.214 259.1)"
+     */
+    format?: "hex" | "hsl" | "oklch";
+    /**
+     * When true, shows a "Theme Colors" tab in the color picker
+     * that displays CSS variables from the current page's computed styles.
+     * Users can select a theme color variable instead of picking a custom color.
+     *
+     * Default: false
+     */
+    themeColors?: boolean;
+}
+/**
+ * A single tab definition within a tabs field.
+ */
+interface TabDef<TSlug extends string = string, TFields extends Record<string, VexField> = Record<string, VexField>> {
+    /** Display label for the tab in the admin panel. */
+    label: string;
+    /**
+     * All fields in this tab are nested under this key as an object.
+     * e.g., `slug: "light"` → `{ light: { background: "#fff", ... } }`
+     */
+    slug: TSlug;
+    /** Fields within this tab. */
+    fields: TFields;
+}
+/**
+ * Tabs field definition. Groups fields into tabbed UI sections in the admin panel.
+ *
+ * - Tabs with `slug` create nested objects in the document
+ * - Tabs without `slug` flatten their fields onto the parent
+ *
+ * @example
+ * ```ts
+ * themeColors: tabs({
+ *   label: "Theme Colors",
+ *   tabs: [
+ *     {
+ *       label: "Light",
+ *       slug: "light",
+ *       fields: {
+ *         background: color({ label: "Background" }),
+ *         foreground: color({ label: "Foreground" }),
+ *       },
+ *     },
+ *     {
+ *       label: "Dark",
+ *       slug: "dark",
+ *       fields: {
+ *         background: color({ label: "Background" }),
+ *         foreground: color({ label: "Foreground" }),
+ *       },
+ *     },
+ *   ],
+ * })
+ * ```
+ */
+interface TabsFieldDef<TTabs extends TabDef[] = TabDef[]> extends BaseField {
+    readonly type: "tabs";
+    /** The tab definitions. */
+    tabs: TTabs;
+}
 /**
  * UI field definition. Non-persisted — renders a custom component only.
  * Skipped during schema generation, form validation, and column generation.
@@ -513,6 +712,16 @@ interface BlockAdminConfig {
     components?: {
         Editor?: ComponentType<any>;
     };
+    /**
+     * Enable block style controls in the admin panel.
+     *
+     * - `true` — enables container styles only (equivalent to `["container"]`)
+     * - `StyleTier[]` — enables specific style tiers (e.g., `["container", "text", "media"]`)
+     * - `undefined` / omitted — no style controls shown
+     *
+     * Available tiers: "container", "text", "layout", "media"
+     */
+    blockStyles?: true | StyleTier[];
 }
 /**
  * A block definition created by `defineBlock()`.
@@ -577,7 +786,7 @@ type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K>
  * }
  * ```
  */
-type VexField = TextFieldDef | NumberFieldDef | CheckboxFieldDef | SelectFieldDef<string> | DateFieldDef | ImageUrlFieldDef | RelationshipFieldDef | UploadFieldDef | JsonFieldDef | ArrayFieldDef | RichTextFieldDef | UIFieldDef | BlocksFieldDef;
+type VexField = TextFieldDef | NumberFieldDef | CheckboxFieldDef | SelectFieldDef<string> | DateFieldDef | ImageUrlFieldDef | RelationshipFieldDef | UploadFieldDef | JsonFieldDef | ObjectFieldDef | ArrayFieldDef | RichTextFieldDef | UIFieldDef | BlocksFieldDef | ColorFieldDef | TabsFieldDef;
 /**
  * Infer the TypeScript value type from a VexField.
  * Uses the `type` discriminant and field options to determine the type.
@@ -610,6 +819,8 @@ type InferFieldType<F extends VexField> = F extends {
 } ? string : F extends {
     type: "json";
 } ? unknown : F extends {
+    type: "object";
+} ? Record<string, unknown> : F extends {
     type: "richtext";
 } ? RichTextDocument : F extends {
     type: "blocks";
@@ -617,7 +828,11 @@ type InferFieldType<F extends VexField> = F extends {
     type: "array";
 } ? unknown[] : F extends {
     type: "ui";
-} ? never : never;
+} ? never : F extends {
+    type: "color";
+} ? string : F extends {
+    type: "tabs";
+} ? Record<string, unknown> : never;
 /**
  * Infer the discriminated union type for a blocks field.
  * Each block becomes an object type with `blockType` literal + `_key` + its field types.
@@ -629,8 +844,40 @@ type InferBlockUnion<F extends VexField> = F extends BlocksFieldDef ? F["blocks"
 } & {
     [K in keyof TFields]: InferFieldType<TFields[K] & VexField>;
 } : never : never : never;
+/**
+ * Infer the expanded tab fields from a tabs field definition.
+ * Each tab becomes a property keyed by its slug with an object of its inferred fields.
+ */
+type InferTabsExpansion<F extends TabsFieldDef> = F["tabs"][number] extends infer T ? T extends TabDef<infer TSlug, infer TFields> ? {
+    [K in TSlug]?: {
+        [FK in keyof TFields]: InferFieldType<TFields[FK] & VexField>;
+    };
+} : {} : {};
+/**
+ * Extract keys of fields that are tabs fields.
+ */
+type TabsFieldKeys<F extends Record<string, any>> = {
+    [K in keyof F]: (F[K] & VexField) extends {
+        type: "tabs";
+    } ? K : never;
+}[keyof F];
+/**
+ * Extract keys of fields that are NOT tabs fields.
+ */
+type NonTabsFieldKeys<F extends Record<string, any>> = {
+    [K in keyof F]: (F[K] & VexField) extends {
+        type: "tabs";
+    } ? never : K;
+}[keyof F];
+/**
+ * Expand all tabs fields in a record into their tab slug entries.
+ * Produces a union of objects (one per tabs field) which gets intersected.
+ */
+type ExpandTabsFields<F extends Record<string, any>> = TabsFieldKeys<F> extends infer TK ? TK extends keyof F ? InferTabsExpansion<F[TK] & TabsFieldDef> : {} : {};
 /**
  * Infer the document type from a record of fields.
+ * Tabs fields are expanded: instead of `colors: Record<string, unknown>`,
+ * produces `light?: { ... }; dark?: { ... }` based on the tab definitions.
  *
  * @example
  * ```ts
@@ -641,9 +888,16 @@ type InferBlockUnion<F extends VexField> = F extends BlocksFieldDef ? F["blocks"
  * // { title: string; count: number }
  * ```
  */
-type InferFieldsType<F extends Record<string, VexField>> = {
-    [K in keyof F]: InferFieldType<F[K] & VexField>;
-};
+type InferFieldsType<F extends Record<string, VexField>> = 0 extends (1 & F) ? {
+    [x: string]: unknown;
+} : {
+    [K in NonTabsFieldKeys<F> & keyof F]: InferFieldType<F[K] & VexField>;
+} & UnionToIntersection<ExpandTabsFields<F>>;
+/**
+ * Convert a union to an intersection.
+ * Used to merge expanded tab objects into a single type.
+ */
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
 
 /**
  * Responsive breakpoint for the live preview iframe.
@@ -940,41 +1194,33 @@ interface GlobalAdminConfig<TFields extends Record<string, VexField> = Record<st
      */
     useAsTitle?: keyof TFields;
     /**
-     * Field keys to show as default columns in the admin view.
-     * If not set, all fields are shown.
-     */
-    defaultColumns?: (keyof TFields)[];
-    /**
-     * Disable the "Create New" button in the admin panel.
-     *
-     * Default: `false`
-     */
-    disableCreate?: boolean;
-    /**
-     * Disable the delete action in the admin panel.
-     *
-     * Default: `false`
+     * Live preview configuration.
+     * When set, the admin edit view shows a toggleable side-by-side preview panel
+     * with an iframe loading the configured URL.
      */
-    disableDelete?: boolean;
+    livePreview?: LivePreviewConfig<TFields>;
 }
 /**
- * A global definition. Users create these as plain objects
- * with `as const satisfies VexGlobal`.
+ * A global definition. Globals are singleton documents — only one
+ * document exists per global. The admin panel shows them as a single
+ * editable form, not a list view.
  *
  * @example
  * ```ts
- * const siteSettings = {
+ * const siteSettings = defineGlobal({
  *   slug: "site_settings",
  *   label: "Site Settings",
  *   fields: {
- *     siteName: { type: "text", label: "Site Name", required: true },
+ *     siteName: text({ label: "Site Name", required: true }),
+ *     description: text({ label: "Description" }),
  *   },
- * } as const satisfies VexGlobal;
+ *   admin: { useAsTitle: "siteName" },
+ * });
  * ```
  */
-interface VexGlobal<TFields extends Record<string, VexField> = Record<string, VexField>> {
+interface VexGlobal<TFields extends Record<string, VexField> = Record<string, VexField>, TSlug extends string = string> {
     /** The global identifier, used in URLs and the database. */
-    readonly slug: string;
+    readonly slug: TSlug;
     /**
      * The fields that make up this global document.
      */
@@ -991,9 +1237,15 @@ interface VexGlobal<TFields extends Record<string, VexField> = Record<string, Ve
     tableName?: string;
     /**
      * Admin UI configuration for this global.
-     * Controls sidebar grouping, icons, and permissions.
+     * Controls sidebar grouping, icons, and live preview.
      */
     admin?: GlobalAdminConfig<TFields>;
+    /**
+     * Versioning and draft/publish workflow configuration.
+     * When `drafts` is enabled, the admin panel shows Save Draft + Publish
+     * and version history, same as versioned collections.
+     */
+    versions?: VersionsConfig;
     /**
      * TypeScript interface name used in generated `vex.types.ts`.
      * If not set, auto-generated from slug via PascalCase conversion.
@@ -1383,15 +1635,24 @@ interface MediaConfigInput {
 type ExtractSlug<T> = T extends {
     slug: infer S extends string;
 } ? S : never;
+/**
+ * Expand field keys from a fields record, replacing tabs field keys with their tab slugs.
+ */
+type ExpandedFieldKeys<TFields extends Record<string, any>> = {
+    [K in keyof TFields & string]: (TFields[K] & VexField) extends {
+        type: "tabs";
+    } ? (TFields[K] & TabsFieldDef)["tabs"][number] extends TabDef<infer TSlug> ? TSlug : never : K;
+}[keyof TFields & string];
 /**
  * Extract field keys from a VexCollection (including auth extra keys) or VexGlobal.
+ * Tabs fields are expanded: instead of the tabs field name, the tab slugs are returned.
  *
  * @example
  * type K = ExtractFieldKeys<typeof posts>; // "title" | "slug" | "status" | "featured"
  */
 type ExtractFieldKeys<T> = T extends VexCollection<infer TFields, infer TExtraKeys> ? T extends {
     _isMedia: true;
-} ? (keyof TFields & string) | (TExtraKeys & string) | DefaultMediaFieldKeys : (keyof TFields & string) | (TExtraKeys & string) : T extends VexMediaCollection<infer TFields> ? (keyof TFields & string) | DefaultMediaFieldKeys : T extends VexGlobal<infer TFields> ? keyof TFields & string : never;
+} ? ExpandedFieldKeys<TFields> | (TExtraKeys & string) | DefaultMediaFieldKeys : ExpandedFieldKeys<TFields> | (TExtraKeys & string) : T extends VexMediaCollection<infer TFields> ? ExpandedFieldKeys<TFields> | DefaultMediaFieldKeys : T extends VexGlobal<infer TFields> ? ExpandedFieldKeys<TFields> : never;
 /**
  * Extract the inferred document type from a VexCollection or VexGlobal.
  * Includes `_id` (system field) and auth extra keys (typed as `string`).
@@ -1480,8 +1741,24 @@ type SingleResourceEntry<R, TUser, TOrg> = R extends {
  * TS eagerly resolves intersection members for LSP autocomplete.
  */
 type ResourcePermissionMap<TResources extends readonly any[], TUser, TOrg> = TResources extends readonly [infer Head, ...infer Tail] ? SingleResourceEntry<Head, TUser, TOrg> & ResourcePermissionMap<Tail, TUser, TOrg> : {};
+/**
+ * Permission check for admin panel access.
+ * - `boolean` — static allow/deny
+ * - `(props) => boolean` — dynamic check based on user (and org if configured)
+ *
+ * Defaults to `false` if not specified for a role.
+ */
+type AdminPermissionCheck<TUser = Record<string, any>, TOrg = never> = boolean | (([TOrg] extends [never] ? (props: {
+    user: TUser;
+}) => boolean : (props: {
+    user: TUser;
+    organization: TOrg;
+}) => boolean));
 type RolesWithPermissions<TRoles extends string, TResources extends readonly any[], TUser = Record<string, any>, TOrg = never> = {
-    [Role in TRoles]: ResourcePermissionMap<TResources, TUser, TOrg>;
+    [Role in TRoles]: ResourcePermissionMap<TResources, TUser, TOrg> & {
+        /** Whether this role can access the admin panel. Defaults to false if not specified. */
+        admin?: AdminPermissionCheck<TUser, TOrg>;
+    };
 };
 /**
  * Input shape for `defineAccess()` WITHOUT organization support.
@@ -1583,6 +1860,21 @@ interface VexAccessConfig {
     boolean | Partial<Record<AccessAction, PermissionCheck<string, any, any, any>>>> | undefined>;
 }
 
+/**
+ * Responsive breakpoint configuration for block style controls.
+ * Keys are breakpoint names (used as Tailwind prefixes), values are min-width in pixels.
+ *
+ * @example
+ * ```ts
+ * breakpoints: {
+ *   sm: 640,
+ *   md: 768,
+ *   lg: 1024,
+ *   xl: 1280,
+ * }
+ * ```
+ */
+type BreakpointConfig = Record<string, number>;
 /** Resolved Vex CMS configuration */
 interface VexConfig {
     /** Base URL path for the admin panel */
@@ -1603,6 +1895,8 @@ interface VexConfig {
     access?: VexAccessConfig;
     /** Global rich text editor adapter. Used by all richtext fields unless overridden. */
     editor?: VexEditorAdapter;
+    /** Responsive breakpoints for block style controls. If not set, styles apply to all viewports. */
+    breakpoints?: BreakpointConfig;
 }
 /**
  * Client-safe version of VexConfig with all non-serializable values stripped.
@@ -1621,6 +1915,8 @@ interface ClientVexConfig {
     media?: ClientMediaConfig;
     /** Global rich text editor adapter. */
     editor?: VexEditorAdapter;
+    /** Responsive breakpoints for block style controls. If not set, styles apply to all viewports. */
+    breakpoints?: BreakpointConfig;
 }
 /**
  * Input configuration for `defineConfig`. All fields are optional
@@ -1676,7 +1972,44 @@ interface VexConfigInput {
      * Pass `plateEditor()` from `@vexcms/richtext/editor`.
      */
     editor?: VexEditorAdapter;
+    /**
+     * Responsive breakpoints for block style controls.
+     * Keys are Tailwind prefix names, values are min-width in pixels.
+     * If not set, block styles apply to all viewports (no breakpoint tabs).
+     */
+    breakpoints?: BreakpointConfig;
+    /**
+     * Plugins to apply to the config. Each plugin is a function that receives
+     * the config input and returns a modified config input. Plugins run
+     * sequentially before the config is resolved.
+     *
+     * @example
+     * ```ts
+     * export default defineConfig({
+     *   plugins: [
+     *     seoPlugin({ collections: ["pages"] }),
+     *   ],
+     *   collections: [pages],
+     * })
+     * ```
+     */
+    plugins?: VexPlugin[];
 }
+/**
+ * A Vex plugin is a function that transforms the config input.
+ * Plugins receive the config (with all previous plugins applied)
+ * and return a modified config. Use a curried function for options:
+ *
+ * @example
+ * ```ts
+ * export const myPlugin = (opts: MyOpts): VexPlugin =>
+ *   (config) => ({
+ *     ...config,
+ *     collections: [...(config.collections ?? []), myCollection],
+ *   })
+ * ```
+ */
+type VexPlugin = (config: VexConfigInput) => VexConfigInput;
 
 declare function defineConfig(vexConfig: VexConfigInput): VexConfig;
 
@@ -1759,6 +2092,37 @@ declare function defineMediaCollection<TFields extends Record<string, VexField>
     admin?: CollectionAdminConfig<TFields, DefaultMediaFieldKeys>;
 }): VexMediaCollection<TFields, TSlug>;
 
+/**
+ * Creates a VexGlobal with full LSP autocomplete on field names
+ * and `admin.useAsTitle`, etc.
+ *
+ * A global is a singleton document — only one document exists per global.
+ * The admin panel shows it as a single editable form, not a list.
+ *
+ * @example
+ * ```ts
+ * export const siteSettings = defineGlobal({
+ *   slug: "site_settings",
+ *   label: "Site Settings",
+ *   fields: {
+ *     siteName: text({ label: "Site Name", required: true }),
+ *     description: text({ label: "Description" }),
+ *   },
+ *   admin: { useAsTitle: "siteName" },
+ *   versions: { drafts: true },
+ * });
+ * ```
+ */
+declare function defineGlobal<TFields extends Record<string, VexField>, TSlug extends string = string>(props: {
+    readonly slug: TSlug;
+    fields: TFields;
+    label?: string;
+    tableName?: string;
+    admin?: GlobalAdminConfig<TFields>;
+    versions?: VersionsConfig;
+    interfaceName?: string;
+}): VexGlobal<TFields, TSlug>;
+
 /**
  * Define access permissions for the Vex CMS admin panel.
  *
@@ -1813,6 +2177,69 @@ declare function hasPermission(props: {
     throwOnDenied?: boolean;
 }): ResolvedFieldPermissions | boolean;
 
+/**
+ * Check whether a user has access to the admin panel.
+ *
+ * Evaluates the `admin` permission on each of the user's roles.
+ * If any role has `admin: true` (or a callback that returns true),
+ * the user is granted access. Returns false if no role grants access
+ * or if the access config is not defined.
+ *
+ * @param props.access - The VexAccessConfig from defineAccess
+ * @param props.user - The user object (passed to dynamic permission callbacks)
+ * @param props.userRoles - The user's role(s) as a string array
+ * @param props.organization - Optional organization object (passed to callbacks if org support is configured)
+ * @returns Whether the user can access the admin panel
+ */
+declare function checkAdminAccess(props: {
+    access: VexAccessConfig | undefined;
+    user: Record<string, any>;
+    userRoles: string[];
+    organization?: Record<string, any>;
+}): boolean;
+
+/**
+ * Framework-agnostic site metadata object.
+ * Consumers (Next.js, TanStack Start, etc.) map this to their framework's metadata format.
+ */
+interface SiteMetadata {
+    title: string;
+    description: string;
+    ogImage?: string;
+    twitterHandle?: string;
+}
+/**
+ * Build site metadata by merging site-wide defaults with per-page overrides.
+ *
+ * Resolution order (per-page wins over site-wide):
+ * - title: page.metaTitle → page.title → site.metaTitle → site.name → "Untitled"
+ * - description: page.metaDescription → site.metaDescription → site.description → ""
+ * - ogImage: page.ogImage → site.ogImage → undefined
+ * - twitterHandle: site.twitterHandle → undefined
+ *
+ * @param props.site - Site settings fields (from globals)
+ * @param props.page - Optional per-page overrides
+ * @param props.titleSuffix - Optional suffix appended to title (e.g. " | My Site")
+ * @returns Framework-agnostic metadata object
+ */
+declare function buildSiteMetadata(props: {
+    site: {
+        name?: string;
+        metaTitle?: string;
+        metaDescription?: string;
+        description?: string;
+        ogImage?: string;
+        twitterHandle?: string;
+    };
+    page?: {
+        title?: string;
+        metaTitle?: string;
+        metaDescription?: string;
+        ogImage?: string;
+    };
+    titleSuffix?: string;
+}): SiteMetadata;
+
 /**
  * Strip non-serializable values from VexConfig for safe passage across
  * RSC / JSON serialization boundaries (e.g., server layout → client component).
@@ -2079,6 +2506,8 @@ declare function upload(options: Omit<UploadFieldSingle, "type">): UploadFieldDe
 
 declare function json(options?: Omit<JsonFieldDef, "type">): JsonFieldDef;
 
+declare function object(options: Omit<ObjectFieldDef, "type">): ObjectFieldDef;
+
 declare function array(options: Omit<ArrayFieldDef, "type">): ArrayFieldDef;
 
 /**
@@ -2165,6 +2594,30 @@ declare function blocks(props: {
     admin?: BlocksFieldDef["admin"];
 }): BlocksFieldDef;
 
+/**
+ * Creates a color field definition.
+ *
+ * @param props - Color field configuration
+ * @param props.label - Display label in admin panel
+ * @param props.format - Output format: "hex" (default), "hsl", or "oklch"
+ * @param props.themeColors - When true, shows theme CSS variable picker tab
+ * @returns ColorFieldDef
+ */
+declare function color(props?: Omit<ColorFieldDef, "type">): ColorFieldDef;
+
+/**
+ * Creates a tabs field definition.
+ * Groups fields into tabbed UI sections in the admin panel.
+ *
+ * Tabs with `slug` create nested objects in the document.
+ * Tabs without `slug` flatten their fields onto the parent.
+ *
+ * @param props - Tabs field configuration
+ * @param props.tabs - Array of tab definitions with label, optional slug, and fields
+ * @returns TabsFieldDef with preserved tab slug and field type information
+ */
+declare function tabs<const TTabs extends TabDef[]>(props: Omit<TabsFieldDef<TTabs>, "type">): TabsFieldDef<TTabs>;
+
 /**
  * Define a block type for use with the `blocks()` field.
  *
@@ -2197,6 +2650,48 @@ declare function defineBlock<TFields extends Record<string, VexField>>(props: {
     interfaceName?: string;
 }): BlockDef<TFields>;
 
+interface StylePreset {
+    /** Tailwind scale value (stored in blockStyles JSON). */
+    value: string;
+    /** Display label in the popover. */
+    label: string;
+    /** Size hint shown next to the label (e.g., "16px / 1rem"). */
+    hint: string;
+}
+declare const SPACING_PRESETS: StylePreset[];
+declare const FONT_SIZE_PRESETS: StylePreset[];
+declare const FONT_WEIGHT_PRESETS: StylePreset[];
+declare const BORDER_RADIUS_PRESETS: StylePreset[];
+declare const BOX_SHADOW_PRESETS: StylePreset[];
+declare const OPACITY_PRESETS: StylePreset[];
+declare const WIDTH_PRESETS: StylePreset[];
+declare const MAX_WIDTH_PRESETS: StylePreset[];
+declare const LINE_HEIGHT_PRESETS: StylePreset[];
+declare const LETTER_SPACING_PRESETS: StylePreset[];
+declare const BORDER_WIDTH_PRESETS: StylePreset[];
+declare const ASPECT_RATIO_PRESETS: StylePreset[];
+
+/**
+ * Convert a blockStyles JSON string into a Tailwind class string.
+ *
+ * Handles responsive breakpoint prefixes. The "base" breakpoint has no prefix,
+ * all other breakpoints use their key as prefix (e.g., "sm:", "md:", "lg:").
+ *
+ * @param props.blockStylesJson - The raw JSON string from the block instance's blockStyles field
+ * @returns Tailwind class string ready to use in className, or empty string if input is empty/invalid
+ *
+ * @example
+ * ```ts
+ * blockStylesToTailwind({
+ *   blockStylesJson: '{"base":{"margin":"4","padding":"2"},"sm":{"margin":"6"}}'
+ * })
+ * // → "m-4 p-2 sm:m-6"
+ * ```
+ */
+declare function blockStylesToTailwind(props: {
+    blockStylesJson: string | undefined;
+}): string;
+
 /**
  * Generate the complete TypeScript source for `vex.types.ts`.
  *
@@ -2667,4 +3162,4 @@ declare function planMigration(props: {
     config: VexConfig;
 }): MigrationOp[];
 
-export { ALL_SYSTEM_FIELDS, type AccessAction, type AdminConfig, type AdminConfigInput, type AdminLivePreviewConfig, type AdminMetaInput, type AdminSidebarInput, type AnyVexCollection, type ArrayFieldDef, type AuthCollectionFieldKeys, type AuthTableFieldKeys, type BlockAdminConfig, type BlockDef, type BlocksFieldDef, type CellComponentProps, type CheckboxFieldDef, type ClientMediaConfig, type ClientVexConfig, type CollectionAdminConfig, type CollectionKind, type CollectionQueryImports, DEFAULT_AUTOSAVE_INTERVAL, DEFAULT_BREAKPOINTS, DEFAULT_MAX_VERSIONS_PER_DOC, type DateFieldDef, type DefaultMediaFieldKeys, type DistributiveOmit, type ExtractDocType, type ExtractFieldKeys, type ExtractSlug, type ExtractSlugs, type FieldAdminConfig, type FieldComponentProps, type FieldPermissionResult, type FileStorageAdapter, GENERATED_HEADER, type GeneratedFiles, type GlobalAdminConfig, type ImageUrlFieldDef, type IndexConfig, type InferBlockUnion, type InferFieldType, type InferFieldsType, type JsonFieldDef, LOCKED_MEDIA_FIELDS, type LivePreviewBreakpoint, type LivePreviewConfig, type LockedMediaField, type LookupBySlug, type MediaConfig, type MediaConfigInput, type MergedCollectionResult, type MigrationOp, type NumberFieldDef, OVERRIDABLE_MEDIA_FIELDS, type OverridableMediaField, PREVIEW_SNAPSHOT_DEBOUNCE_MS, type PermissionCallbackProps, type PermissionCheck, type RelationshipFieldDef, type RemovedFieldInfo, type ResolvedCollectionMatch, type ResolvedFieldPermissions, type ResolvedIndex, type ResolvedSearchIndex, type ResourcePermissions, type RichTextDocument, type RichTextElement, type RichTextFieldDef, type RichTextText, type RolesWithPermissions, type SchemaDiff, type SchemaFieldInfo, type SearchIndexConfig, type SelectFieldDef, type SelectOption, type TextFieldDef, type UIFieldDef, type UploadFieldDef, VERSION_SYSTEM_FIELDS, type VersioningFieldKeys, type VersionsConfig, type VexAccessConfig, VexAccessConfigError, VexAccessError, type VexAccessInput, type VexAccessInputBase, type VexAccessInputWithOrg, type VexAuthAdapter, VexAuthConfigError, VexBlockValidationError, type VexCollection, type VexConfig, type VexConfigInput, type VexDraftsMode, type VexEditorAdapter, type VexEditorComponentProps, VexError, type VexField, VexFieldValidationError, type VexGlobal, type VexMediaCollection, VexMediaConfigError, type VexQueryCtx, type VexRenderComponentProps, VexSlugConflictError, addRemovedFieldsAsOptional, array, blocks, checkbox, createDocument, createVexQuery, date, defineAccess, defineBlock, defineCollection, defineConfig, defineMediaCollection, deleteDocument, deletePreviewSnapshot, diffSchema, extendTable, extractLivePreviewConfigs, extractUserFields, fieldMetaToZod, findCollectionBySlug, generateCollectionQueries, generateColumns, generateFormDefaultValues, generateFormSchema, generateIndexFile, generateVexSchema, generateVexTypes, getAllCollections, getDocument, getPreviewSnapshot, hasPermission, imageUrl, isMediaCollection, json, listDocuments, makeFieldsOptional, mergeAuthCollectionWithUserCollection, number, planMigration, relationship, resolvePreviewURL, richtext, sanitizeConfigForClient, searchDocuments, select, shouldReloadURL, slugToInterfaceName, text, toTitleCase, ui, updateDocument, upload, upsertPreviewSnapshot, vexQuery };
+export { ALL_SYSTEM_FIELDS, ASPECT_RATIO_PRESETS, type AccessAction, type AdminConfig, type AdminConfigInput, type AdminLivePreviewConfig, type AdminMetaInput, type AdminSidebarInput, type AnyVexCollection, type ArrayFieldDef, type AuthCollectionFieldKeys, type AuthTableFieldKeys, BORDER_RADIUS_PRESETS, BORDER_WIDTH_PRESETS, BOX_SHADOW_PRESETS, type BlockAdminConfig, type BlockDef, type BlockStyleValues, type BlockStylesData, type BlocksFieldDef, type BreakpointConfig, type CellComponentProps, type CheckboxFieldDef, type ClientMediaConfig, type ClientVexConfig, type CollectionAdminConfig, type CollectionKind, type CollectionQueryImports, type ColorFieldDef, type ContainerStyleConfig, DEFAULT_AUTOSAVE_INTERVAL, DEFAULT_BREAKPOINTS, DEFAULT_MAX_VERSIONS_PER_DOC, type DateFieldDef, type DefaultMediaFieldKeys, type DistributiveOmit, type ExtractDocType, type ExtractFieldKeys, type ExtractSlug, type ExtractSlugs, FONT_SIZE_PRESETS, FONT_WEIGHT_PRESETS, type FieldAdminConfig, type FieldComponentProps, type FieldPermissionResult, type FileStorageAdapter, GENERATED_HEADER, type GeneratedFiles, type GlobalAdminConfig, type ImageUrlFieldDef, type IndexConfig, type InferBlockUnion, type InferFieldType, type InferFieldsType, type JsonFieldDef, LETTER_SPACING_PRESETS, LINE_HEIGHT_PRESETS, LOCKED_MEDIA_FIELDS, type LayoutStyleConfig, type LivePreviewBreakpoint, type LivePreviewConfig, type LockedMediaField, type LookupBySlug, MAX_WIDTH_PRESETS, type MediaConfig, type MediaConfigInput, type MediaStyleConfig, type MergedCollectionResult, type MigrationOp, type NumberFieldDef, OPACITY_PRESETS, OVERRIDABLE_MEDIA_FIELDS, type ObjectFieldDef, type OverridableMediaField, PREVIEW_SNAPSHOT_DEBOUNCE_MS, type PermissionCallbackProps, type PermissionCheck, type RelationshipFieldDef, type RemovedFieldInfo, type ResolvedCollectionMatch, type ResolvedFieldPermissions, type ResolvedIndex, type ResolvedSearchIndex, type ResourcePermissions, type RichTextDocument, type RichTextElement, type RichTextFieldDef, type RichTextText, type RolesWithPermissions, SPACING_PRESETS, type SchemaDiff, type SchemaFieldInfo, type SearchIndexConfig, type SelectFieldDef, type SelectOption, type SiteMetadata, type StylePreset, type StyleTier, type TabDef, type TabsFieldDef, type TextFieldDef, type TextStyleConfig, type UIFieldDef, type UploadFieldDef, VERSION_SYSTEM_FIELDS, type VersioningFieldKeys, type VersionsConfig, type VexAccessConfig, VexAccessConfigError, VexAccessError, type VexAccessInput, type VexAccessInputBase, type VexAccessInputWithOrg, type VexAuthAdapter, VexAuthConfigError, VexBlockValidationError, type VexCollection, type VexConfig, type VexConfigInput, type VexDraftsMode, type VexEditorAdapter, type VexEditorComponentProps, VexError, type VexField, VexFieldValidationError, type VexGlobal, type VexMediaCollection, VexMediaConfigError, type VexPlugin, type VexQueryCtx, type VexRenderComponentProps, VexSlugConflictError, WIDTH_PRESETS, addRemovedFieldsAsOptional, array, blockStylesToTailwind, blocks, buildSiteMetadata, checkAdminAccess, checkbox, color, createDocument, createVexQuery, date, defineAccess, defineBlock, defineCollection, defineConfig, defineGlobal, defineMediaCollection, deleteDocument, deletePreviewSnapshot, diffSchema, extendTable, extractLivePreviewConfigs, extractUserFields, fieldMetaToZod, findCollectionBySlug, generateCollectionQueries, generateColumns, generateFormDefaultValues, generateFormSchema, generateIndexFile, generateVexSchema, generateVexTypes, getAllCollections, getDocument, getPreviewSnapshot, hasPermission, imageUrl, isMediaCollection, json, listDocuments, makeFieldsOptional, mergeAuthCollectionWithUserCollection, number, object, planMigration, relationship, resolvePreviewURL, richtext, sanitizeConfigForClient, searchDocuments, select, shouldReloadURL, slugToInterfaceName, tabs, text, toTitleCase, ui, updateDocument, upload, upsertPreviewSnapshot, vexQuery };