@vexcms/core 0.0.20 → 0.1.0-alpha.3

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/fields/url/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,WAAW,aAAa,CAC5B,UAAU,SAAS,EAAE,GAAG,EAAE,CAC1B,SAAQ,cAAc,CAAC,UAAU,CAAC;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ,CAAC,UAAU,SAAS,EAAE,GAAG,EAAE,CAAE,SAAQ,SAAS,CAAC,UAAU,CAAC;IACjF,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC;IAC5C;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}

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

@@ -0,0 +1,37 @@
+import type { UrlField } from "./types";
+/**
+ * Converts a URL field definition to a Convex schema validator string.
+ *
+ * URL fields are stored as plain strings in Convex — the URL format is
+ * enforced at the admin form layer, not in the database schema. This
+ * function generates only the type constraint.
+ *
+ * Length constraints (`min`, `max`) are runtime validation — they do not
+ * affect the generated Convex validator string. Index configuration is
+ * handled separately by the collection schema builder.
+ *
+ * @param props - Input props.
+ * @param props.field - The resolved URL field definition.
+ * @returns Convex validator string: `"v.string()"` for required fields,
+ * `"v.optional(v.string())"` for optional fields.
+ *
+ * @example
+ * ```ts
+ * const field1 = url({ required: true })
+ * urlFieldToValidator({ field: field1 })  // "v.string()"
+ *
+ * const field2 = url({ required: false })
+ * urlFieldToValidator({ field: field2 })  // "v.optional(v.string())"
+ *
+ * const field3 = url({ min: { value: 10 }, max: { value: 2048 } })
+ * urlFieldToValidator({ field: field3 })  // "v.optional(v.string())"
+ * // Length constraints don't affect schema — handled at validation layer
+ * ```
+ *
+ * @see {@link urlFieldToInputSchema} for the admin-form Zod schema with URL format and length validation
+ * @internal Used by schema generation, not typically called directly.
+ */
+export declare function urlFieldToValidator(props: {
+    field: UrlField;
+}): string;
+//# sourceMappingURL=validator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../../src/fields/url/validator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GAAG,MAAM,CAKtE"}

package/dist/fields/utils.d.ts

@@ -0,0 +1,47 @@
+import { AdminField } from "./types";
+/**
+ * Wraps a string into lines that do not exceed `maxLen` characters, splitting
+ * on word boundaries.
+ *
+ * Used by `adminFieldToJSDocComment` to keep JSDoc comment lines within the
+ * conventional 80-character limit before emitting them into generated source files.
+ *
+ * @param props - Input props.
+ * @param props.text - The string to wrap.
+ * @param props.maxLen - Maximum character length per line.
+ * @returns An array of strings, each no longer than `maxLen` characters.
+ *
+ * @example
+ * ```ts
+ * wrapLines({ text: "This is a long description that should wrap.", maxLen: 20 })
+ * // → ["This is a long", "description that", "should wrap."]
+ * ```
+ */
+export declare function wrapLines(props: {
+    text: string;
+    maxLen: number;
+}): string[];
+/**
+ * Builds a tab-indented JSDoc comment block for a field's description.
+ *
+ * Reads `field.interfaceDescription` first, falling back to `field.description`.
+ * Returns an empty string when neither is set. The output is ready to insert
+ * directly above a property line in a generated TypeScript interface — lines are
+ * wrapped at 80 characters via `wrapLines`.
+ *
+ * @param props - Input props.
+ * @param props.field - The resolved field definition to extract the description from.
+ * @returns A tab-indented JSDoc block string ready to splice into generated
+ *   TypeScript source, or an empty string if the field has no description.
+ *
+ * @example
+ * ```ts
+ * const field = text({ description: "Page title shown in browser tabs." })
+ * adminFieldToJSDocComment({ field })
+ * // Returns a multi-line JSDoc block wrapping the description text
+ * ```
+ */
+export declare function adminFieldToJSDocComment(props: {
+    field: AdminField;
+}): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/fields/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/fields/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,EAAE,CAc3E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,GAAG,MAAM,CAW7E"}

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

@@ -0,0 +1,23 @@
+import { AdminField } from "../types";
+/**
+ * Converts any field definition to its Convex schema validator string.
+ *
+ * Dispatches to the field-type-specific validator function based on `field.type`.
+ * Used by the CLI during schema generation to build the Convex schema file.
+ *
+ * @param props Input props
+ * @param props.field - The resolved field definition to convert
+ * @returns A Convex validator string (e.g. `"v.string()"`, `"v.optional(v.boolean())"`)
+ * @throws An Error if an unrecognized field type is given. Reaching this is a
+ * compile error: the default arm binds the exhausted union to `never`, so a new
+ * member of `AdminField` fails typecheck here until a case is added
+ *
+ * @see {@link textFieldToValidator} for the text field implementation
+ * @see {@link numberFieldToValidator} for the number field implementation
+ * @see {@link checkboxFieldToValidator} for the checkbox field implementation
+ * @internal
+ */
+export declare function adminFieldToValidator<TFieldMeta extends {} = {}>(props: {
+    field: AdminField<TFieldMeta>;
+}): string;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/fields/validators/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AActC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,SAAS,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE;IACvE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;CAC/B,UAqCA"}

package/dist/fields/validators/utils.d.ts

@@ -0,0 +1,24 @@
+import { AdminField } from "../types";
+/**
+ * Wraps a Convex validator string in `v.optional()` when the field is not required.
+ *
+ * Used during schema generation to apply the correct Convex validator based on
+ * whether the field is marked as required in its config.
+ *
+ * @param props - handleOptionalValidators() input props
+ * @param props.field - The resolved field definition, used to check `required`
+ * @param props.validator - A Convex validator expression string (e.g. `"v.string()"`)
+ * @returns The validator string, wrapped in `v.optional(...)` if the field is optional
+ *
+ * @example
+ * ```ts
+ * handleOptionalValidators({ field: textField, validator: "v.string()" })
+ * // required field  → "v.string()"
+ * // optional field  → "v.optional(v.string())"
+ * ```
+ */
+export declare function applyBaseValidators(props: {
+    field: AdminField;
+    validator: string;
+}): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/fields/validators/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/fields/validators/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAKT"}

package/dist/framework.d.ts

@@ -0,0 +1,227 @@
+import { CollectionConfig } from "./collections";
+import { ClientVexConfig } from "./config";
+import type { AdminField, ApplyComponent, BaseFieldMeta, CellComponentProps, ComponentHKT, InputComponentProps } from "./fields";
+import type { VexDocument } from "./api/convex";
+import { CollectionSlug, GlobalSlug, VexDocumentGlobal } from "./types/generated";
+import { PaginationResult } from "./api/types";
+import { GlobalConfig } from "./globals";
+/**
+ * Maps every field type in the `AdminField` union to the framework's input component type
+ * for that field.
+ *
+ * Keyed by `AdminField['type']` — as new field types are added to the union, TypeScript
+ * automatically requires a matching component slot in this map.
+ *
+ * Each slot resolves to `ApplyComponent<F, InputComponentProps<MatchingFieldDef>>`, which
+ * means the component must accept the input props for that specific field type. This gives
+ * the component full autocomplete for field-specific properties (e.g. `fieldDef.max`
+ * on the text slot).
+ *
+ * @see {@link CellComponentProps} for the data table cell props
+ * @see {@link ComponentHKT} for how framework packages define their HKT
+ * @see {@link ApplyComponent} for how the HKT resolves to a concrete component type
+ */
+export type FieldComponentMap<F extends ComponentHKT, TFieldMeta extends BaseFieldMeta = BaseFieldMeta> = {
+    [K in AdminField["type"]]: {
+        input: ApplyComponent<F, InputComponentProps<TFieldMeta, Extract<AdminField<TFieldMeta>, {
+            type: K;
+        }>>>;
+        cell: ApplyComponent<F, CellComponentProps<Extract<AdminField<TFieldMeta>, {
+            type: K;
+        }>>>;
+    };
+};
+/**
+ * Props passed to the admin `Dashboard` view component.
+ *
+ * The Dashboard receives the full resolved VexCMS config and is responsible
+ * for rendering the admin shell — navigation sidebar, header, and a slot for
+ * the active view (collection list or edit form).
+ *
+ * @see {@link ViewComponentMap}
+ */
+export interface DashboardProps {
+    /** The full resolved VexCMS configuration. */
+    config: ClientVexConfig;
+}
+/**
+ * Props passed to the `CollectionListView` component.
+ *
+ * `TCollectionSlug` is inferred from the `collection` prop and narrows the collection type
+ * to a specific slug after `vex generate` runs. `TDoc` defaults to `VexDocument`
+ * and can be narrowed to a generated document interface when the caller has a
+ * typed initial data array.
+ *
+ * @see {@link ViewComponentMap}
+ */
+export interface CollectionListViewProps<TFieldMeta extends {} = {}, TCollectionMeta extends {} = {}, TCollectionSlug extends CollectionSlug = CollectionSlug, TDoc extends VexDocument = VexDocument> {
+    /** The resolved collection configuration for the collection being listed. */
+    collection: CollectionConfig<TFieldMeta, TCollectionMeta, TCollectionSlug>;
+    /**
+     * Pre-fetched documents from the server. Passed as `initialData` to
+     * the TanStack Query so the list renders immediately on first load.
+     * Omit when rendering client-side only.
+     */
+    initialData?: PaginationResult<TDoc>;
+}
+/**
+ * Props passed to the `CollectionEditView` component.
+ *
+ * `TCollectionSlug` is inferred from the `collection` prop. After `vex generate` runs,
+ * passing a collection of the wrong slug is a compile-time error.
+ *
+ * @see {@link ViewComponentMap}
+ */
+export interface CollectionEditViewProps<TFieldMeta extends {} = {}, TCollectionMeta extends {} = {}, TCollectionSlug extends CollectionSlug = CollectionSlug, TDocument extends VexDocument = VexDocument> {
+    /** The resolved collection configuration whose fields will be rendered. */
+    collection: CollectionConfig<TFieldMeta, TCollectionMeta, TCollectionSlug>;
+    /**
+     * The Convex document ID of the document being edited.
+     * Omit for new document creation — the form will be empty.
+     */
+    documentId: VexDocument["_id"];
+    /**
+     * Pre-fetched document from the server for SSR hydration.
+     * `null` explicitly means "no document found". `undefined` means "not loaded yet".
+     */
+    initialData?: TDocument | null;
+}
+/**
+ * Props passed to the `GlobalEditView` component.
+ *
+ * `TGlobalSlug` is inferred from the `global` prop. After `vex generate` runs,
+ * passing a global config with an unregistered slug is a compile-time error.
+ *
+ * @see {@link ViewComponentMap}
+ */
+export interface GlobalEditViewProps<TFieldMeta extends {} = {}, TGlobalMeta extends {} = {}, TGlobalSlug extends GlobalSlug = GlobalSlug, TDocument extends VexDocumentGlobal = VexDocumentGlobal> {
+    /** The resolved global configuration whose fields will be rendered. */
+    global: GlobalConfig<TFieldMeta, TGlobalMeta, TGlobalSlug>;
+    /**
+     * Pre-fetched document from the server for SSR hydration.
+     * `null` explicitly means "no document found". `undefined` means "not loaded yet".
+     */
+    initialData?: TDocument | null;
+}
+/**
+ * Maps the three required admin views to their framework component types.
+ *
+ * All three are required — omitting any one causes a TypeScript error at the
+ * `defineFrameworkAdapter` call site.
+ *
+ * @see {@link FrameworkAdapterInput}
+ */
+export type ViewComponentMap<F extends ComponentHKT> = {
+    /** Admin shell component receiving the full VexCMS config. */
+    dashboard: ApplyComponent<F, DashboardProps>;
+    /** Collection list view — renders a list of documents for a collection. */
+    collectionListView: ApplyComponent<F, CollectionListViewProps>;
+    /** Collection edit form — renders all field inputs for a collection. */
+    collectionEditView: ApplyComponent<F, CollectionEditViewProps>;
+};
+/**
+ * Input type for `defineFrameworkAdapter()`.
+ *
+ * Framework packages pass this to register their component implementations.
+ * TypeScript enforces that every field type in the `AdminField` union has both
+ * an input component (`fields`) and a cell component (`cells`), and that each
+ * component accepts the correct props for its field type.
+ *
+ * **What the HKT does:**
+ * The `F` parameter is the framework's HKT — a type-level function that maps
+ * a props type to the framework's component type. For React:
+ * ```ts
+ * interface ReactHKT extends ComponentHKT {
+ *   component: ComponentType<this['_props']>;
+ * }
+ * ```
+ * Passing `ReactHKT` as `F` means every slot in `fields` and `cells` resolves to
+ * `ComponentType<CorrectProps>`, giving the component full prop autocomplete.
+ *
+ * @example
+ * ```ts
+ * // In @vexcms/react
+ * import { defineFrameworkAdapter, ComponentHKT } from '@vexcms/core';
+ * import { ComponentType } from 'react';
+ *
+ * interface ReactHKT extends ComponentHKT {
+ *   component: ComponentType<this['_props']>;
+ * }
+ *
+ * export const reactAdapter = defineFrameworkAdapter<ReactHKT>({
+ *   name: 'react',
+ *   version: '0.1.0',
+ *   fields: {
+ *     text: TextInputComponent,  // must accept InputComponentProps<TextField>
+ *   },
+ *   cells: {
+ *     text: TextCellComponent,   // must accept CellComponentProps<TextField>
+ *   },
+ * });
+ * ```
+ *
+ * @see {@link FrameworkAdapter} for the resolved type returned by `defineFrameworkAdapter`
+ * @see {@link FieldComponentMap} for the field component slot types
+ * @see {@link CellComponentProps} for the cell component props
+ */
+export interface FrameworkAdapterInput<F extends ComponentHKT, TFieldMeta extends BaseFieldMeta = BaseFieldMeta> {
+    /** Framework name used for identification (e.g. `"react"`, `"solid"`). */
+    name: string;
+    /** Adapter version — should match the framework package version. */
+    version: string;
+    /**
+     * Input components for each field type, rendered in the document edit form.
+     * Every type in the `AdminField` union must have a corresponding component.
+     */
+    fields: FieldComponentMap<F, TFieldMeta>;
+    /**
+     * Admin view components — required for rendering the admin panel.
+     * All three must be provided; TypeScript enforces completeness.
+     */
+    views: ViewComponentMap<F>;
+}
+/**
+ * Resolved framework adapter returned by `defineFrameworkAdapter()`.
+ *
+ * @see {@link FrameworkAdapterInput} for the user-facing input type
+ * @see {@link defineFrameworkAdapter} for the function that produces this type
+ */
+export type FrameworkAdapter<F extends ComponentHKT, TFieldMeta extends BaseFieldMeta = BaseFieldMeta> = FrameworkAdapterInput<F, TFieldMeta>;
+/**
+ * Registers a framework adapter, enforcing that all field and cell components are
+ * implemented and typed correctly.
+ *
+ * This is a zero-runtime identity function — it returns the adapter unchanged.
+ * All enforcement happens at the TypeScript level via the `F` HKT parameter:
+ * missing components cause a type error, and each component gets autocomplete
+ * for its field-specific props.
+ *
+ * @param adapter - The framework adapter implementation.
+ * @returns The same adapter, verified by TypeScript.
+ *
+ * @example
+ * ```ts
+ * import { defineFrameworkAdapter, ComponentHKT } from '@vexcms/core';
+ * import { ComponentType } from 'react';
+ *
+ * interface ReactHKT extends ComponentHKT {
+ *   component: ComponentType<this['_props']>;
+ * }
+ *
+ * export const reactAdapter = defineFrameworkAdapter<ReactHKT>({
+ *   name: 'react',
+ *   version: '0.1.0',
+ *   fields: {
+ *     text: MyTextInput,  // TS error if missing or wrong props
+ *   },
+ *   cells: {
+ *     text: MyTextCell,
+ *   },
+ * });
+ * ```
+ *
+ * @see {@link FrameworkAdapterInput} for the full input type
+ * @see {@link FrameworkAdapter} for the resolved return type
+ */
+export declare function defineFrameworkAdapter<F extends ComponentHKT, TFieldMeta extends BaseFieldMeta = BaseFieldMeta>(adapter: FrameworkAdapterInput<F, TFieldMeta>): FrameworkAdapter<F, TFieldMeta>;
+//# sourceMappingURL=framework.d.ts.map

package/dist/framework.d.ts.map

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

package/dist/globals/config/config.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=config.d.ts.map

package/dist/globals/config/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/globals/config/config.ts"],"names":[],"mappings":""}

package/dist/globals/config/types.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=types.d.ts.map

package/dist/globals/config/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/globals/config/types.ts"],"names":[],"mappings":""}

package/dist/globals/config.d.ts

@@ -0,0 +1,47 @@
+import type { ComponentHKT } from "../fields";
+import type { GlobalConfig, GlobalConfigInput, ReservedGlobalFieldKey } from "./types";
+import type { GlobalSlug } from "../types/generated";
+/**
+ * Defines a singleton global document for the VexCMS project.
+ *
+ * **Flat API:** `globals.get({ slug: "siteSettings" })` returns a flat document
+ * where user fields (`siteName`, `activeTheme`, …) are at root level alongside
+ * `_id`, `_creationTime`, and `_slug`. The DB stores data nested in a `data`
+ * field; the VexCMS API layer handles flattening on read and re-nesting on write.
+ *
+ * **Reserved field keys:** `_id`, `_creationTime`, and `_slug` may not be used
+ * as field names. A compile-time error is emitted on the offending field when
+ * they are used. A runtime error is also thrown for JS consumers.
+ *
+ * @typeParam TFieldMeta - Metadata on each field definition.
+ * @typeParam TGlobalMeta - Metadata on the global config itself.
+ * @typeParam TGlobalSlug - The slug string literal (inferred by TypeScript).
+ * @typeParam TFieldSlug - Union of field key string literals.
+ * @typeParam TComponent - Framework HKT binding.
+ * @param config - The raw global configuration.
+ * @returns The resolved `GlobalConfig` with all defaults applied.
+ * @throws {Error} When `config.fields` contains one of the reserved keys
+ *   `_id`, `_creationTime`, or `_slug`.
+ *
+ * @example
+ * ```ts
+ * export const siteSettings = defineGlobal({
+ *   slug: "siteSettings",
+ *   label: "Site Settings",
+ *   fields: {
+ *     siteName: text({ label: "Site Name", required: true }),
+ *     activeTheme: relationship({ label: "Active Theme", collection: "themes" }),
+ *   },
+ *   admin: { group: "Site Builder" },
+ * });
+ * ```
+ *
+ * @see {@link GlobalConfigInput} for the user-facing input type
+ * @see {@link GlobalConfig} for the resolved return type
+ */
+export declare function defineGlobal<TFieldMeta extends {} = {}, TGlobalMeta extends {} = {}, TGlobalSlug extends GlobalSlug = GlobalSlug, TFieldSlug extends string = string, TComponent extends ComponentHKT = ComponentHKT>(config: string extends TFieldSlug ? GlobalConfigInput<TFieldMeta, TGlobalMeta, TGlobalSlug, TFieldSlug, TComponent> : [TFieldSlug & ReservedGlobalFieldKey] extends [never] ? GlobalConfigInput<TFieldMeta, TGlobalMeta, TGlobalSlug, TFieldSlug, TComponent> : {
+    fields: {
+        [K in TFieldSlug & ReservedGlobalFieldKey]: "Field name is reserved — cannot use _id, _creationTime, or _slug";
+    };
+}): GlobalConfig<TFieldMeta, TGlobalMeta, TGlobalSlug, TFieldSlug, TComponent>;
+//# sourceMappingURL=config.d.ts.map

package/dist/globals/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/globals/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AACvF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,YAAY,CAC1B,UAAU,SAAS,EAAE,GAAG,EAAE,EAC1B,WAAW,SAAS,EAAE,GAAG,EAAE,EAC3B,WAAW,SAAS,UAAU,GAAG,UAAU,EAC3C,UAAU,SAAS,MAAM,GAAG,MAAM,EAClC,UAAU,SAAS,YAAY,GAAG,YAAY,EAE9C,MAAM,EAAE,MAAM,SAAS,UAAU,GAC7B,iBAAiB,CAAC,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,CAAC,GAC/E,CAAC,UAAU,GAAG,sBAAsB,CAAC,SAAS,CAAC,KAAK,CAAC,GACnD,iBAAiB,CAAC,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,CAAC,GAC/E;IACE,MAAM,EAAE;SACL,CAAC,IAAI,UAAU,GACd,sBAAsB,GAAG,kEAAkE;KAC9F,CAAC;CACH,GACN,YAAY,CAAC,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,CAAC,CAmC5E"}

package/dist/globals/index.d.ts

@@ -0,0 +1,5 @@
+export { defineGlobal } from "./config";
+export type { GlobalConfig, GlobalConfigInput, GlobalAdminConfig, GlobalAdminConfigInput, ReservedGlobalFieldKey, } from "./types";
+export { getGlobalDefaultValues, getGlobalInputSchema } from "./utils";
+export { globalConfigToInterface, globalConfigToFieldTypeMap } from "./interfaceGen";
+//# sourceMappingURL=index.d.ts.map

package/dist/globals/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/globals/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/globals/interfaceGen.d.ts

@@ -0,0 +1,33 @@
+import type { GlobalConfig } from "./types";
+/**
+ * Converts a resolved `GlobalConfig` to a TypeScript `export interface` source string.
+ *
+ * The generated interface extends `VexDocumentGlobal<"slug">` (which itself
+ * extends `VexDocument`), adding user fields at root level. This produces the
+ * flat shape returned by `globals.get` — no `data` wrapper.
+ *
+ * @param props.global - The resolved global definition to convert.
+ * @returns TypeScript source string for one flat global interface block.
+ *
+ * @example
+ * ```ts
+ * globalConfigToInterface({ global: siteSettings });
+ * // → 'export interface SiteSettingsGlobal extends VexDocumentGlobal<"siteSettings"> {\n\tsiteName: string\n\t...\n}'
+ * ```
+ */
+export declare function globalConfigToInterface(props: {
+    global: GlobalConfig;
+}): string;
+/**
+ * Converts a resolved `GlobalConfig` to the TypeScript source string for its
+ * `GlobalsFieldTypeMap` entry in the `declare module '@vexcms/core'` block.
+ *
+ * Powers `GlobalRelationshipKeysOf<TGlobalSlug>` for populate type narrowing.
+ *
+ * @param props.global - The resolved global definition.
+ * @returns TypeScript source string for one `GlobalsFieldTypeMap` entry.
+ */
+export declare function globalConfigToFieldTypeMap(props: {
+    global: GlobalConfig;
+}): string;
+//# sourceMappingURL=interfaceGen.d.ts.map

package/dist/globals/interfaceGen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaceGen.d.ts","sourceRoot":"","sources":["../../src/globals/interfaceGen.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GAAG,MAAM,CAyB/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GAAG,MAAM,CAelF"}