@vexcms/core 0.0.19 → 0.1.0-alpha.2

package/dist/globals/types.d.ts

@@ -0,0 +1,175 @@
+import type { ApplyComponent, ComponentHKT, AdminField } from "../fields";
+import type { GlobalSlug } from "../types/generated";
+import type { LucideIconName } from "../utils";
+/**
+ * Field keys that are reserved by the VexCMS globals system and cannot be
+ * used as user-defined field names on a global. These are the system fields
+ * that appear on every flat global document returned by the API.
+ */
+export type ReservedGlobalFieldKey = "_id" | "_creationTime" | "_slug";
+/**
+ * User-facing admin panel configuration input for `defineGlobal()`.
+ *
+ * Intentionally narrower than `AdminCollectionConfigInput` — globals cannot
+ * be relationship targets (no picker), have no list view (no `table` config),
+ * and always use `label` as the admin page title (no `useAsTitle`).
+ * Consequently this interface has only one generic: `TComponent`.
+ *
+ * @typeParam TComponent - Component HKT binding; defaults to `ComponentHKT`.
+ */
+export interface GlobalAdminConfigInput<TComponent extends ComponentHKT = ComponentHKT> {
+    /**
+     * Sidebar group label this global appears under (e.g. `"Site Builder"`).
+     * Ungrouped when omitted.
+     */
+    group?: string;
+    /**
+     * Short description shown beneath the global label in `GlobalsListView`.
+     */
+    description?: string;
+    /**
+     * Live preview configuration. Reserved for future `LivePreviewPanel`
+     * integration — included now so adding live preview later is non-breaking.
+     */
+    livePreview?: {
+        url: string;
+    };
+    /**
+     * Lucide icon name shown in the admin sidebar.
+     * See https://lucide.dev/icons/
+     */
+    icon?: LucideIconName;
+    /**
+     * Custom React component for rendering this global in contexts where a
+     * compact preview is needed (e.g. future cross-global reference UI).
+     * Typed via the HKT machinery — resolves to `ComponentType<...>` in React.
+     */
+    components?: {
+        preview?: ApplyComponent<TComponent, {
+            slug: string;
+        }>;
+    };
+}
+/**
+ * Resolved admin config after `defineGlobal()` applies defaults.
+ *
+ * @typeParam TComponent - Component HKT binding.
+ */
+export interface GlobalAdminConfig<TComponent extends ComponentHKT = ComponentHKT> {
+    /** Sidebar group label. Empty string when not set. */
+    group: string;
+    /** Description. Empty string when not set. */
+    description: string;
+    /** Live preview config. */
+    livePreview?: {
+        url: string;
+    };
+    /** Lucide icon name. */
+    icon?: LucideIconName;
+    /** Custom preview component. */
+    components: {
+        preview?: ApplyComponent<TComponent, {
+            slug: string;
+        }>;
+    };
+}
+/**
+ * User-facing input to `defineGlobal()`.
+ *
+ * Mirrors `CollectionConfigInput` with the same five generics. The constraint
+ * `[TFieldSlug & ReservedGlobalFieldKey] extends [never]` is enforced in
+ * `defineGlobal`'s function signature — a compile-time error is emitted if
+ * any field key is `_id`, `_creationTime`, or `_slug`.
+ *
+ * @typeParam TFieldMeta - Metadata attached to each field definition.
+ * @typeParam TGlobalMeta - Metadata attached to the global config itself.
+ * @typeParam TGlobalSlug - The slug string literal type (inferred by `defineGlobal`).
+ * @typeParam TFieldSlug - Union of field key string literals.
+ * @typeParam TComponent - Component HKT binding.
+ *
+ * @example
+ * ```ts
+ * 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 GlobalConfig} for the resolved return type
+ * @see {@link defineGlobal} for the config function
+ */
+export interface GlobalConfigInput<TFieldMeta extends {} = {}, TGlobalMeta extends {} = {}, TGlobalSlug extends string = string, TFieldSlug extends string = string, TComponent extends ComponentHKT = ComponentHKT> {
+    /**
+     * Unique slug for this global. Becomes the `_slug` discriminator on the flat
+     * document and the lookup key in `vex_globals`. Must be camelCase and unique
+     * across all globals in the project.
+     */
+    slug: TGlobalSlug;
+    /**
+     * Human-readable label shown in the admin sidebar and page heading.
+     * Always used as the admin page title — globals have no `useAsTitle`.
+     * @example "Site Settings"
+     */
+    label: string;
+    /**
+     * Field definitions for this global. All field types supported by
+     * `defineCollection` are valid. Field keys must not be `_id`,
+     * `_creationTime`, or `_slug` (enforced at compile time by `defineGlobal`).
+     */
+    fields: Record<TFieldSlug, AdminField<TFieldMeta>>;
+    /** Admin panel display and behaviour config. */
+    admin?: GlobalAdminConfigInput<TComponent>;
+    /**
+     * Override the generated TypeScript interface name. Inferred from `slug`
+     * with `Global` suffix when omitted (e.g. `"siteSettings"` → `"SiteSettingsGlobal"`).
+     */
+    interfaceName?: string;
+    /** Arbitrary metadata attached to this global config. */
+    meta?: TGlobalMeta;
+    /**
+     * Draft and versioning config. Parsed but ignored in v35 — versioning for
+     * globals lands in Spec 36. Included now for forward compatibility so
+     * `defineGlobal` call sites don't need to change when Spec 36 ships.
+     */
+    versions?: {
+        /** Enable draft/publish workflow. Default: `false`. */
+        drafts?: boolean;
+    };
+}
+/**
+ * Resolved global config returned by `defineGlobal()` and stored in
+ * `VexConfig.globals`.
+ *
+ * @typeParam TFieldMeta - Field-level metadata.
+ * @typeParam TGlobalMeta - Global-level metadata.
+ * @typeParam TGlobalSlug - The exact slug type (narrowed from `GlobalSlug`).
+ * @typeParam TFieldSlug - Union of field key string literals.
+ * @typeParam TComponent - Component HKT binding.
+ */
+export interface GlobalConfig<TFieldMeta extends {} = {}, TGlobalMeta extends {} = {}, TGlobalSlug extends GlobalSlug = GlobalSlug, TFieldSlug extends string = string, TComponent extends ComponentHKT = ComponentHKT> {
+    /** Unique slug — the lookup key in `vex_globals`. */
+    slug: TGlobalSlug;
+    /** Human-readable label. */
+    label: string;
+    /** Resolved field definitions. */
+    fields: Record<TFieldSlug, AdminField<TFieldMeta>>;
+    /** Resolved admin config. */
+    admin: GlobalAdminConfig<TComponent>;
+    /**
+     * PascalCase interface name for generated TypeScript types.
+     * E.g. `"siteSettings"` → `"SiteSettingsGlobal"`.
+     */
+    interfaceName: string;
+    /** Global-level metadata. */
+    meta: TGlobalMeta;
+    /** Resolved versioning config. Always present after defaults. */
+    versions: {
+        drafts: boolean;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/globals/utils.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import type { GlobalConfig } from "./types";
+import type { VexDocumentGlobal } from "../types";
+/**
+ * Builds `defaultValues` for a TanStack Form from a global config.
+ *
+ * Mirrors `getCollectionDefaultValues` — operates on `GlobalConfig` rather
+ * than `CollectionConfig`. When `document` is provided (edit mode), uses its
+ * field values; otherwise falls back to each field's `defaultValue`.
+ *
+ * @param props - Input props.
+ * @param props.global - The global config whose fields define the form shape.
+ * @param props.document - Optional existing flat global document (edit mode).
+ *   `null` means "no document persisted yet" — create mode with defaults.
+ * @returns `Record<fieldKey, value>` ready for `useForm({ defaultValues })`.
+ */
+export declare function getGlobalDefaultValues(props: {
+    global: GlobalConfig;
+    document?: VexDocumentGlobal | null;
+}): Record<string, unknown>;
+/**
+ * Builds a Zod object schema for validating all fields in a global.
+ *
+ * Mirrors `getCollectionInputSchema` — same field-level logic, operates on
+ * `GlobalConfig`. Used by `updateGlobal` server function to validate user
+ * data before writing to `vex_globals`.
+ *
+ * @param props - Input props.
+ * @param props.global - The global config whose fields define the schema.
+ * @returns A `z.object` schema with one key per field.
+ */
+export declare function getGlobalInputSchema(props: {
+    global: GlobalConfig;
+}): z.ZodObject<{
+    [x: string]: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}, z.core.$strip>;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/globals/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAgB,MAAM,KAAK,CAAC;AAEtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACrC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAW1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE;;kBAOnE"}