@storyblok/schema 1.0.0-alpha.0

package/dist/helpers/define-asset.cjs

@@ -0,0 +1,43 @@
+
+//#region src/helpers/define-asset.ts
+const MAPI_ASSET_DEFAULTS = {
+	id: 1,
+	filename: "",
+	space_id: 1,
+	created_at: "",
+	updated_at: "",
+	short_filename: "",
+	content_type: "",
+	content_length: 0
+};
+/**
+* Defines a MAPI asset (standalone asset entity).
+* For asset fields embedded in story content, use {@link AssetFieldValue} instead.
+*
+* @example
+* const asset = defineMapiAsset({ filename: 'hero.png' });
+*/
+const defineMapiAsset = (asset) => ({
+	...MAPI_ASSET_DEFAULTS,
+	...asset
+});
+/**
+* Defines an asset creation payload for the upload flow.
+*
+* @example
+* const payload = defineAssetCreate({ filename: 'hero.png', alt: 'Hero image' });
+*/
+const defineAssetCreate = (asset) => asset;
+/**
+* Defines an asset update payload.
+*
+* @example
+* const payload = defineAssetUpdate({ alt: 'Updated hero image' });
+*/
+const defineAssetUpdate = (asset) => asset;
+
+//#endregion
+exports.defineAssetCreate = defineAssetCreate;
+exports.defineAssetUpdate = defineAssetUpdate;
+exports.defineMapiAsset = defineMapiAsset;
+//# sourceMappingURL=define-asset.cjs.map

package/dist/helpers/define-asset.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-asset.cjs","names":[],"sources":["../../src/helpers/define-asset.ts"],"sourcesContent":["import type { Asset, AssetCreate, AssetUpdate } from '../generated/mapi-types';\n\nconst MAPI_ASSET_DEFAULTS = {\n  id: 1,\n  filename: '',\n  space_id: 1,\n  created_at: '',\n  updated_at: '',\n  short_filename: '',\n  content_type: '',\n  content_length: 0,\n};\n\nexport type MapiAsset = Asset;\nexport type { AssetCreate, AssetUpdate };\n\ntype MapiAssetInput = { filename: string } & Partial<Omit<Asset, 'filename'>>;\n\n/**\n * Defines a MAPI asset (standalone asset entity).\n * For asset fields embedded in story content, use {@link AssetFieldValue} instead.\n *\n * @example\n * const asset = defineMapiAsset({ filename: 'hero.png' });\n */\nexport const defineMapiAsset = (asset: MapiAssetInput): MapiAsset => ({ ...MAPI_ASSET_DEFAULTS, ...asset });\n\n/**\n * Defines an asset creation payload for the upload flow.\n *\n * @example\n * const payload = defineAssetCreate({ filename: 'hero.png', alt: 'Hero image' });\n */\nexport const defineAssetCreate = (asset: AssetCreate): AssetCreate => asset;\n\n/**\n * Defines an asset update payload.\n *\n * @example\n * const payload = defineAssetUpdate({ alt: 'Updated hero image' });\n */\nexport const defineAssetUpdate = (asset: AssetUpdate): AssetUpdate => asset;\n"],"mappings":";;AAEA,MAAM,sBAAsB;CAC1B,IAAI;CACJ,UAAU;CACV,UAAU;CACV,YAAY;CACZ,YAAY;CACZ,gBAAgB;CAChB,cAAc;CACd,gBAAgB;CACjB;;;;;;;;AAcD,MAAa,mBAAmB,WAAsC;CAAE,GAAG;CAAqB,GAAG;CAAO;;;;;;;AAQ1G,MAAa,qBAAqB,UAAoC;;;;;;;AAQtE,MAAa,qBAAqB,UAAoC"}

package/dist/helpers/define-asset.d.cts

@@ -0,0 +1,32 @@
+import { Asset, AssetCreate, AssetUpdate } from "../generated/mapi-types.cjs";
+
+//#region src/helpers/define-asset.d.ts
+type MapiAsset = Asset;
+type MapiAssetInput = {
+  filename: string;
+} & Partial<Omit<Asset, 'filename'>>;
+/**
+ * Defines a MAPI asset (standalone asset entity).
+ * For asset fields embedded in story content, use {@link AssetFieldValue} instead.
+ *
+ * @example
+ * const asset = defineMapiAsset({ filename: 'hero.png' });
+ */
+declare const defineMapiAsset: (asset: MapiAssetInput) => MapiAsset;
+/**
+ * Defines an asset creation payload for the upload flow.
+ *
+ * @example
+ * const payload = defineAssetCreate({ filename: 'hero.png', alt: 'Hero image' });
+ */
+declare const defineAssetCreate: (asset: AssetCreate) => AssetCreate;
+/**
+ * Defines an asset update payload.
+ *
+ * @example
+ * const payload = defineAssetUpdate({ alt: 'Updated hero image' });
+ */
+declare const defineAssetUpdate: (asset: AssetUpdate) => AssetUpdate;
+//#endregion
+export { MapiAsset, defineAssetCreate, defineAssetUpdate, defineMapiAsset };
+//# sourceMappingURL=define-asset.d.cts.map

package/dist/helpers/define-asset.d.mts

@@ -0,0 +1,32 @@
+import { Asset, AssetCreate, AssetUpdate } from "../generated/mapi-types.mjs";
+
+//#region src/helpers/define-asset.d.ts
+type MapiAsset = Asset;
+type MapiAssetInput = {
+  filename: string;
+} & Partial<Omit<Asset, 'filename'>>;
+/**
+ * Defines a MAPI asset (standalone asset entity).
+ * For asset fields embedded in story content, use {@link AssetFieldValue} instead.
+ *
+ * @example
+ * const asset = defineMapiAsset({ filename: 'hero.png' });
+ */
+declare const defineMapiAsset: (asset: MapiAssetInput) => MapiAsset;
+/**
+ * Defines an asset creation payload for the upload flow.
+ *
+ * @example
+ * const payload = defineAssetCreate({ filename: 'hero.png', alt: 'Hero image' });
+ */
+declare const defineAssetCreate: (asset: AssetCreate) => AssetCreate;
+/**
+ * Defines an asset update payload.
+ *
+ * @example
+ * const payload = defineAssetUpdate({ alt: 'Updated hero image' });
+ */
+declare const defineAssetUpdate: (asset: AssetUpdate) => AssetUpdate;
+//#endregion
+export { MapiAsset, defineAssetCreate, defineAssetUpdate, defineMapiAsset };
+//# sourceMappingURL=define-asset.d.mts.map

package/dist/helpers/define-asset.mjs

@@ -0,0 +1,40 @@
+//#region src/helpers/define-asset.ts
+const MAPI_ASSET_DEFAULTS = {
+	id: 1,
+	filename: "",
+	space_id: 1,
+	created_at: "",
+	updated_at: "",
+	short_filename: "",
+	content_type: "",
+	content_length: 0
+};
+/**
+* Defines a MAPI asset (standalone asset entity).
+* For asset fields embedded in story content, use {@link AssetFieldValue} instead.
+*
+* @example
+* const asset = defineMapiAsset({ filename: 'hero.png' });
+*/
+const defineMapiAsset = (asset) => ({
+	...MAPI_ASSET_DEFAULTS,
+	...asset
+});
+/**
+* Defines an asset creation payload for the upload flow.
+*
+* @example
+* const payload = defineAssetCreate({ filename: 'hero.png', alt: 'Hero image' });
+*/
+const defineAssetCreate = (asset) => asset;
+/**
+* Defines an asset update payload.
+*
+* @example
+* const payload = defineAssetUpdate({ alt: 'Updated hero image' });
+*/
+const defineAssetUpdate = (asset) => asset;
+
+//#endregion
+export { defineAssetCreate, defineAssetUpdate, defineMapiAsset };
+//# sourceMappingURL=define-asset.mjs.map

package/dist/helpers/define-asset.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-asset.mjs","names":[],"sources":["../../src/helpers/define-asset.ts"],"sourcesContent":["import type { Asset, AssetCreate, AssetUpdate } from '../generated/mapi-types';\n\nconst MAPI_ASSET_DEFAULTS = {\n  id: 1,\n  filename: '',\n  space_id: 1,\n  created_at: '',\n  updated_at: '',\n  short_filename: '',\n  content_type: '',\n  content_length: 0,\n};\n\nexport type MapiAsset = Asset;\nexport type { AssetCreate, AssetUpdate };\n\ntype MapiAssetInput = { filename: string } & Partial<Omit<Asset, 'filename'>>;\n\n/**\n * Defines a MAPI asset (standalone asset entity).\n * For asset fields embedded in story content, use {@link AssetFieldValue} instead.\n *\n * @example\n * const asset = defineMapiAsset({ filename: 'hero.png' });\n */\nexport const defineMapiAsset = (asset: MapiAssetInput): MapiAsset => ({ ...MAPI_ASSET_DEFAULTS, ...asset });\n\n/**\n * Defines an asset creation payload for the upload flow.\n *\n * @example\n * const payload = defineAssetCreate({ filename: 'hero.png', alt: 'Hero image' });\n */\nexport const defineAssetCreate = (asset: AssetCreate): AssetCreate => asset;\n\n/**\n * Defines an asset update payload.\n *\n * @example\n * const payload = defineAssetUpdate({ alt: 'Updated hero image' });\n */\nexport const defineAssetUpdate = (asset: AssetUpdate): AssetUpdate => asset;\n"],"mappings":";AAEA,MAAM,sBAAsB;CAC1B,IAAI;CACJ,UAAU;CACV,UAAU;CACV,YAAY;CACZ,YAAY;CACZ,gBAAgB;CAChB,cAAc;CACd,gBAAgB;CACjB;;;;;;;;AAcD,MAAa,mBAAmB,WAAsC;CAAE,GAAG;CAAqB,GAAG;CAAO;;;;;;;AAQ1G,MAAa,qBAAqB,UAAoC;;;;;;;AAQtE,MAAa,qBAAqB,UAAoC"}

package/dist/helpers/define-block-folder.cjs

@@ -0,0 +1,40 @@
+
+//#region src/helpers/define-block-folder.ts
+const BLOCK_FOLDER_DEFAULTS = {
+	id: 1,
+	uuid: ""
+};
+/**
+* Defines a block folder for the MAPI.
+* API-assigned fields (`id`, `uuid`) are optional and filled with safe defaults.
+*
+* @example
+* import { defineBlockFolder } from '@storyblok/schema';
+* const folder = defineBlockFolder({ name: 'Layout' });
+*/
+const defineBlockFolder = (blockFolder) => ({
+	...BLOCK_FOLDER_DEFAULTS,
+	...blockFolder
+});
+/**
+* Defines a block folder creation payload for the MAPI.
+*
+* @example
+* import { defineBlockFolderCreate } from '@storyblok/schema';
+* const payload = defineBlockFolderCreate({ name: 'Layout' });
+*/
+const defineBlockFolderCreate = (blockFolder) => blockFolder;
+/**
+* Defines a block folder update payload for the MAPI.
+*
+* @example
+* import { defineBlockFolderUpdate } from '@storyblok/schema';
+* const payload = defineBlockFolderUpdate({ name: 'Updated Layout' });
+*/
+const defineBlockFolderUpdate = (blockFolder) => blockFolder;
+
+//#endregion
+exports.defineBlockFolder = defineBlockFolder;
+exports.defineBlockFolderCreate = defineBlockFolderCreate;
+exports.defineBlockFolderUpdate = defineBlockFolderUpdate;
+//# sourceMappingURL=define-block-folder.cjs.map

package/dist/helpers/define-block-folder.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-block-folder.cjs","names":[],"sources":["../../src/helpers/define-block-folder.ts"],"sourcesContent":["import type { ComponentFolder, ComponentFolderCreate, ComponentFolderUpdate } from '../generated/mapi-types';\n\nexport type { ComponentFolder, ComponentFolderCreate, ComponentFolderUpdate };\n\nconst BLOCK_FOLDER_DEFAULTS = {\n  id: 1,\n  uuid: '',\n};\n\ntype BlockFolderInput = { name: string } & Partial<Omit<ComponentFolder, 'name'>>;\n\n/**\n * Defines a block folder for the MAPI.\n * API-assigned fields (`id`, `uuid`) are optional and filled with safe defaults.\n *\n * @example\n * import { defineBlockFolder } from '@storyblok/schema';\n * const folder = defineBlockFolder({ name: 'Layout' });\n */\nexport const defineBlockFolder = (blockFolder: BlockFolderInput): ComponentFolder => ({\n  ...BLOCK_FOLDER_DEFAULTS,\n  ...blockFolder,\n});\n\n/**\n * Defines a block folder creation payload for the MAPI.\n *\n * @example\n * import { defineBlockFolderCreate } from '@storyblok/schema';\n * const payload = defineBlockFolderCreate({ name: 'Layout' });\n */\nexport const defineBlockFolderCreate = (blockFolder: ComponentFolderCreate): ComponentFolderCreate => blockFolder;\n\n/**\n * Defines a block folder update payload for the MAPI.\n *\n * @example\n * import { defineBlockFolderUpdate } from '@storyblok/schema';\n * const payload = defineBlockFolderUpdate({ name: 'Updated Layout' });\n */\nexport const defineBlockFolderUpdate = (blockFolder: ComponentFolderUpdate): ComponentFolderUpdate => blockFolder;\n"],"mappings":";;AAIA,MAAM,wBAAwB;CAC5B,IAAI;CACJ,MAAM;CACP;;;;;;;;;AAYD,MAAa,qBAAqB,iBAAoD;CACpF,GAAG;CACH,GAAG;CACJ;;;;;;;;AASD,MAAa,2BAA2B,gBAA8D;;;;;;;;AAStG,MAAa,2BAA2B,gBAA8D"}

package/dist/helpers/define-block-folder.d.cts

@@ -0,0 +1,34 @@
+import { ComponentFolder, ComponentFolderCreate, ComponentFolderUpdate } from "../generated/mapi-types.cjs";
+
+//#region src/helpers/define-block-folder.d.ts
+type BlockFolderInput = {
+  name: string;
+} & Partial<Omit<ComponentFolder, 'name'>>;
+/**
+ * Defines a block folder for the MAPI.
+ * API-assigned fields (`id`, `uuid`) are optional and filled with safe defaults.
+ *
+ * @example
+ * import { defineBlockFolder } from '@storyblok/schema';
+ * const folder = defineBlockFolder({ name: 'Layout' });
+ */
+declare const defineBlockFolder: (blockFolder: BlockFolderInput) => ComponentFolder;
+/**
+ * Defines a block folder creation payload for the MAPI.
+ *
+ * @example
+ * import { defineBlockFolderCreate } from '@storyblok/schema';
+ * const payload = defineBlockFolderCreate({ name: 'Layout' });
+ */
+declare const defineBlockFolderCreate: (blockFolder: ComponentFolderCreate) => ComponentFolderCreate;
+/**
+ * Defines a block folder update payload for the MAPI.
+ *
+ * @example
+ * import { defineBlockFolderUpdate } from '@storyblok/schema';
+ * const payload = defineBlockFolderUpdate({ name: 'Updated Layout' });
+ */
+declare const defineBlockFolderUpdate: (blockFolder: ComponentFolderUpdate) => ComponentFolderUpdate;
+//#endregion
+export { defineBlockFolder, defineBlockFolderCreate, defineBlockFolderUpdate };
+//# sourceMappingURL=define-block-folder.d.cts.map

package/dist/helpers/define-block-folder.d.mts

@@ -0,0 +1,34 @@
+import { ComponentFolder, ComponentFolderCreate, ComponentFolderUpdate } from "../generated/mapi-types.mjs";
+
+//#region src/helpers/define-block-folder.d.ts
+type BlockFolderInput = {
+  name: string;
+} & Partial<Omit<ComponentFolder, 'name'>>;
+/**
+ * Defines a block folder for the MAPI.
+ * API-assigned fields (`id`, `uuid`) are optional and filled with safe defaults.
+ *
+ * @example
+ * import { defineBlockFolder } from '@storyblok/schema';
+ * const folder = defineBlockFolder({ name: 'Layout' });
+ */
+declare const defineBlockFolder: (blockFolder: BlockFolderInput) => ComponentFolder;
+/**
+ * Defines a block folder creation payload for the MAPI.
+ *
+ * @example
+ * import { defineBlockFolderCreate } from '@storyblok/schema';
+ * const payload = defineBlockFolderCreate({ name: 'Layout' });
+ */
+declare const defineBlockFolderCreate: (blockFolder: ComponentFolderCreate) => ComponentFolderCreate;
+/**
+ * Defines a block folder update payload for the MAPI.
+ *
+ * @example
+ * import { defineBlockFolderUpdate } from '@storyblok/schema';
+ * const payload = defineBlockFolderUpdate({ name: 'Updated Layout' });
+ */
+declare const defineBlockFolderUpdate: (blockFolder: ComponentFolderUpdate) => ComponentFolderUpdate;
+//#endregion
+export { defineBlockFolder, defineBlockFolderCreate, defineBlockFolderUpdate };
+//# sourceMappingURL=define-block-folder.d.mts.map

package/dist/helpers/define-block-folder.mjs

@@ -0,0 +1,37 @@
+//#region src/helpers/define-block-folder.ts
+const BLOCK_FOLDER_DEFAULTS = {
+	id: 1,
+	uuid: ""
+};
+/**
+* Defines a block folder for the MAPI.
+* API-assigned fields (`id`, `uuid`) are optional and filled with safe defaults.
+*
+* @example
+* import { defineBlockFolder } from '@storyblok/schema';
+* const folder = defineBlockFolder({ name: 'Layout' });
+*/
+const defineBlockFolder = (blockFolder) => ({
+	...BLOCK_FOLDER_DEFAULTS,
+	...blockFolder
+});
+/**
+* Defines a block folder creation payload for the MAPI.
+*
+* @example
+* import { defineBlockFolderCreate } from '@storyblok/schema';
+* const payload = defineBlockFolderCreate({ name: 'Layout' });
+*/
+const defineBlockFolderCreate = (blockFolder) => blockFolder;
+/**
+* Defines a block folder update payload for the MAPI.
+*
+* @example
+* import { defineBlockFolderUpdate } from '@storyblok/schema';
+* const payload = defineBlockFolderUpdate({ name: 'Updated Layout' });
+*/
+const defineBlockFolderUpdate = (blockFolder) => blockFolder;
+
+//#endregion
+export { defineBlockFolder, defineBlockFolderCreate, defineBlockFolderUpdate };
+//# sourceMappingURL=define-block-folder.mjs.map

package/dist/helpers/define-block-folder.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-block-folder.mjs","names":[],"sources":["../../src/helpers/define-block-folder.ts"],"sourcesContent":["import type { ComponentFolder, ComponentFolderCreate, ComponentFolderUpdate } from '../generated/mapi-types';\n\nexport type { ComponentFolder, ComponentFolderCreate, ComponentFolderUpdate };\n\nconst BLOCK_FOLDER_DEFAULTS = {\n  id: 1,\n  uuid: '',\n};\n\ntype BlockFolderInput = { name: string } & Partial<Omit<ComponentFolder, 'name'>>;\n\n/**\n * Defines a block folder for the MAPI.\n * API-assigned fields (`id`, `uuid`) are optional and filled with safe defaults.\n *\n * @example\n * import { defineBlockFolder } from '@storyblok/schema';\n * const folder = defineBlockFolder({ name: 'Layout' });\n */\nexport const defineBlockFolder = (blockFolder: BlockFolderInput): ComponentFolder => ({\n  ...BLOCK_FOLDER_DEFAULTS,\n  ...blockFolder,\n});\n\n/**\n * Defines a block folder creation payload for the MAPI.\n *\n * @example\n * import { defineBlockFolderCreate } from '@storyblok/schema';\n * const payload = defineBlockFolderCreate({ name: 'Layout' });\n */\nexport const defineBlockFolderCreate = (blockFolder: ComponentFolderCreate): ComponentFolderCreate => blockFolder;\n\n/**\n * Defines a block folder update payload for the MAPI.\n *\n * @example\n * import { defineBlockFolderUpdate } from '@storyblok/schema';\n * const payload = defineBlockFolderUpdate({ name: 'Updated Layout' });\n */\nexport const defineBlockFolderUpdate = (blockFolder: ComponentFolderUpdate): ComponentFolderUpdate => blockFolder;\n"],"mappings":";AAIA,MAAM,wBAAwB;CAC5B,IAAI;CACJ,MAAM;CACP;;;;;;;;;AAYD,MAAa,qBAAqB,iBAAoD;CACpF,GAAG;CACH,GAAG;CACJ;;;;;;;;AASD,MAAa,2BAA2B,gBAA8D;;;;;;;;AAStG,MAAa,2BAA2B,gBAA8D"}

package/dist/helpers/define-block.cjs

@@ -0,0 +1,51 @@
+
+//#region src/helpers/define-block.ts
+const BLOCK_DEFAULTS = {
+	id: 1,
+	created_at: "",
+	updated_at: "",
+	is_root: false,
+	is_nestable: true,
+	component_group_uuid: null
+};
+function defineBlock(block) {
+	const inputSchema = Array.isArray(block?.schema) ? block.schema : [];
+	const seen = /* @__PURE__ */ new Set();
+	const schemaRecord = {};
+	inputSchema.forEach((field, index) => {
+		const name = field?.name;
+		if (typeof name !== "string") return;
+		if (seen.has(name)) throw new Error(`defineBlock: duplicate field name "${name}" in block "${block?.name ?? ""}"`);
+		seen.add(name);
+		const { name: _name, ...rest } = field;
+		schemaRecord[name] = {
+			...rest,
+			pos: index
+		};
+	});
+	return {
+		...BLOCK_DEFAULTS,
+		...block,
+		schema: schemaRecord
+	};
+}
+/**
+* Defines a block creation payload for the MAPI.
+*
+* @example
+* const payload = defineBlockCreate({ name: 'page', schema: { ... } });
+*/
+const defineBlockCreate = (block) => block;
+/**
+* Defines a block update payload for the MAPI.
+*
+* @example
+* const payload = defineBlockUpdate({ display_name: 'Page' });
+*/
+const defineBlockUpdate = (block) => block;
+
+//#endregion
+exports.defineBlock = defineBlock;
+exports.defineBlockCreate = defineBlockCreate;
+exports.defineBlockUpdate = defineBlockUpdate;
+//# sourceMappingURL=define-block.cjs.map

package/dist/helpers/define-block.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-block.cjs","names":[],"sources":["../../src/helpers/define-block.ts"],"sourcesContent":["import type { ComponentCreate, Component as ComponentGenerated, ComponentUpdate, ComponentSchemaField as Field } from '../generated/mapi-types';\nimport type { Prettify } from '../utils/prettify';\n\nexport type { ComponentCreate, ComponentUpdate };\n\nconst BLOCK_DEFAULTS = {\n  id: 1,\n  created_at: '',\n  updated_at: '',\n  is_root: false,\n  is_nestable: true,\n  component_group_uuid: null,\n};\n\n/** Input form: an ordered array of named fields. The array index becomes `pos`. */\nexport type BlockSchemaInput = ReadonlyArray<Field & { name: string; required?: boolean }>;\n\n/** Wire form: the MAPI object map keyed by field name. This is what `defineBlock` returns. */\nexport type BlockSchema = Record<string, Field & { required?: boolean }>;\n\n/** Converts an array-form schema input into the wire-shape object map at the type level. */\nexport type SchemaArrayToRecord<T extends BlockSchemaInput> = {\n  [F in T[number] as F['name']]: Omit<F, 'name'>;\n};\n\n/**\n * A Storyblok block.\n */\nexport type Block<\n  TName extends string = string,\n  TBlockSchema extends BlockSchema = BlockSchema,\n  TIsRoot extends boolean = boolean,\n  TIsNestable extends boolean = boolean,\n  TComponentGroupUuid extends string | null = string | null,\n> = Prettify<\n  Omit<ComponentGenerated, 'name' | 'schema' | 'is_root' | 'is_nestable' | 'component_group_uuid'> & {\n    name: TName;\n    schema: TBlockSchema;\n    is_root?: TIsRoot;\n    is_nestable?: TIsNestable;\n    component_group_uuid?: TComponentGroupUuid;\n  }\n>;\n\n/** Extract only root blocks from a schema union. */\nexport type RootBlocks<T extends Block> =\n  T extends { is_root: true } ? T : never;\n\n/** Extract only nestable blocks from a schema union. */\nexport type NestableBlocks<T extends Block> =\n  T extends { is_nestable: true } ? T : never;\n\n/** Fields that have safe defaults and may be omitted from block input. */\ntype BlockOptional = keyof typeof BLOCK_DEFAULTS;\n\ntype BlockInput<\n  TName extends string = string,\n  TInputSchema extends BlockSchemaInput = BlockSchemaInput,\n  TIsRoot extends boolean = false,\n  TIsNestable extends boolean = true,\n  TComponentGroupUuid extends string | null = null,\n> = Prettify<\n  Omit<ComponentGenerated, 'name' | 'schema' | 'is_root' | 'is_nestable' | 'component_group_uuid' | BlockOptional> & {\n    name: TName;\n    schema: TInputSchema;\n    is_root?: TIsRoot;\n    is_nestable?: TIsNestable;\n    component_group_uuid?: TComponentGroupUuid;\n  } & Partial<Pick<ComponentGenerated, Exclude<BlockOptional, 'is_root' | 'is_nestable' | 'component_group_uuid'>>>\n>;\n\ntype DefinedBlock<\n  TName extends string,\n  TBlockSchema,\n  TIsRoot extends boolean,\n  TIsNestable extends boolean,\n  TComponentGroupUuid extends string | null,\n> = Prettify<\n  Omit<ComponentGenerated, 'name' | 'schema' | 'is_root' | 'is_nestable' | 'component_group_uuid'> & {\n    name: TName;\n    schema: TBlockSchema;\n    is_root: TIsRoot;\n    is_nestable: TIsNestable;\n    component_group_uuid: TComponentGroupUuid;\n  }\n>;\n\n/**\n * Returns a {@link Block} with object-shape `schema` (matches the MAPI wire\n * shape). The user-facing input is an ordered array of `defineField` calls;\n * the array index becomes the field's `pos` in the returned map. Throws if\n * two fields share the same `name`.\n *\n * @example\n * const pageBlock = defineBlock({\n *   name: 'page',\n *   is_root: true,\n *   schema: [\n *     defineField('headline', { type: 'text', required: true }),\n *   ],\n * });\n */\nexport function defineBlock<\n  TName extends string,\n  const TInputSchema extends BlockSchemaInput,\n  TIsRoot extends boolean = false,\n  TIsNestable extends boolean = true,\n  TComponentGroupUuid extends string | null = null,\n>(\n  block: BlockInput<TName, TInputSchema, TIsRoot, TIsNestable, TComponentGroupUuid>,\n): DefinedBlock<TName, SchemaArrayToRecord<TInputSchema>, TIsRoot, TIsNestable, TComponentGroupUuid>;\n\nexport function defineBlock(block: any) {\n  const inputSchema = Array.isArray(block?.schema) ? block.schema : [];\n  const seen = new Set<string>();\n  const schemaRecord: Record<string, unknown> = {};\n  inputSchema.forEach((field: any, index: number) => {\n    const name = field?.name;\n    if (typeof name !== 'string') {\n      return;\n    }\n    if (seen.has(name)) {\n      throw new Error(`defineBlock: duplicate field name \"${name}\" in block \"${block?.name ?? ''}\"`);\n    }\n    seen.add(name);\n    const { name: _name, ...rest } = field;\n    schemaRecord[name] = { ...rest, pos: index };\n  });\n  return { ...BLOCK_DEFAULTS, ...block, schema: schemaRecord };\n}\n\n/**\n * Defines a block creation payload for the MAPI.\n *\n * @example\n * const payload = defineBlockCreate({ name: 'page', schema: { ... } });\n */\nexport const defineBlockCreate = (block: ComponentCreate): ComponentCreate => block;\n\n/**\n * Defines a block update payload for the MAPI.\n *\n * @example\n * const payload = defineBlockUpdate({ display_name: 'Page' });\n */\nexport const defineBlockUpdate = (block: ComponentUpdate): ComponentUpdate => block;\n"],"mappings":";;AAKA,MAAM,iBAAiB;CACrB,IAAI;CACJ,YAAY;CACZ,YAAY;CACZ,SAAS;CACT,aAAa;CACb,sBAAsB;CACvB;AAoGD,SAAgB,YAAY,OAAY;CACtC,MAAM,cAAc,MAAM,QAAQ,OAAO,OAAO,GAAG,MAAM,SAAS,EAAE;CACpE,MAAM,uBAAO,IAAI,KAAa;CAC9B,MAAM,eAAwC,EAAE;AAChD,aAAY,SAAS,OAAY,UAAkB;EACjD,MAAM,OAAO,OAAO;AACpB,MAAI,OAAO,SAAS,SAClB;AAEF,MAAI,KAAK,IAAI,KAAK,CAChB,OAAM,IAAI,MAAM,sCAAsC,KAAK,cAAc,OAAO,QAAQ,GAAG,GAAG;AAEhG,OAAK,IAAI,KAAK;EACd,MAAM,EAAE,MAAM,OAAO,GAAG,SAAS;AACjC,eAAa,QAAQ;GAAE,GAAG;GAAM,KAAK;GAAO;GAC5C;AACF,QAAO;EAAE,GAAG;EAAgB,GAAG;EAAO,QAAQ;EAAc;;;;;;;;AAS9D,MAAa,qBAAqB,UAA4C;;;;;;;AAQ9E,MAAa,qBAAqB,UAA4C"}

package/dist/helpers/define-block.d.cts

@@ -0,0 +1,90 @@
+import { Component, ComponentCreate, ComponentSchemaField, ComponentUpdate } from "../generated/mapi-types.cjs";
+import { Prettify } from "../utils/prettify.cjs";
+
+//#region src/helpers/define-block.d.ts
+declare const BLOCK_DEFAULTS: {
+  id: number;
+  created_at: string;
+  updated_at: string;
+  is_root: boolean;
+  is_nestable: boolean;
+  component_group_uuid: null;
+};
+/** Input form: an ordered array of named fields. The array index becomes `pos`. */
+type BlockSchemaInput = ReadonlyArray<ComponentSchemaField & {
+  name: string;
+  required?: boolean;
+}>;
+/** Wire form: the MAPI object map keyed by field name. This is what `defineBlock` returns. */
+type BlockSchema = Record<string, ComponentSchemaField & {
+  required?: boolean;
+}>;
+/** Converts an array-form schema input into the wire-shape object map at the type level. */
+type SchemaArrayToRecord<T extends BlockSchemaInput> = { [F in T[number] as F['name']]: Omit<F, 'name'> };
+/**
+ * A Storyblok block.
+ */
+type Block<TName extends string = string, TBlockSchema extends BlockSchema = BlockSchema, TIsRoot extends boolean = boolean, TIsNestable extends boolean = boolean, TComponentGroupUuid extends string | null = string | null> = Prettify<Omit<Component, 'name' | 'schema' | 'is_root' | 'is_nestable' | 'component_group_uuid'> & {
+  name: TName;
+  schema: TBlockSchema;
+  is_root?: TIsRoot;
+  is_nestable?: TIsNestable;
+  component_group_uuid?: TComponentGroupUuid;
+}>;
+/** Extract only root blocks from a schema union. */
+type RootBlocks<T extends Block> = T extends {
+  is_root: true;
+} ? T : never;
+/** Extract only nestable blocks from a schema union. */
+type NestableBlocks<T extends Block> = T extends {
+  is_nestable: true;
+} ? T : never;
+/** Fields that have safe defaults and may be omitted from block input. */
+type BlockOptional = keyof typeof BLOCK_DEFAULTS;
+type BlockInput<TName extends string = string, TInputSchema extends BlockSchemaInput = BlockSchemaInput, TIsRoot extends boolean = false, TIsNestable extends boolean = true, TComponentGroupUuid extends string | null = null> = Prettify<Omit<Component, 'name' | 'schema' | 'is_root' | 'is_nestable' | 'component_group_uuid' | BlockOptional> & {
+  name: TName;
+  schema: TInputSchema;
+  is_root?: TIsRoot;
+  is_nestable?: TIsNestable;
+  component_group_uuid?: TComponentGroupUuid;
+} & Partial<Pick<Component, Exclude<BlockOptional, 'is_root' | 'is_nestable' | 'component_group_uuid'>>>>;
+type DefinedBlock<TName extends string, TBlockSchema, TIsRoot extends boolean, TIsNestable extends boolean, TComponentGroupUuid extends string | null> = Prettify<Omit<Component, 'name' | 'schema' | 'is_root' | 'is_nestable' | 'component_group_uuid'> & {
+  name: TName;
+  schema: TBlockSchema;
+  is_root: TIsRoot;
+  is_nestable: TIsNestable;
+  component_group_uuid: TComponentGroupUuid;
+}>;
+/**
+ * Returns a {@link Block} with object-shape `schema` (matches the MAPI wire
+ * shape). The user-facing input is an ordered array of `defineField` calls;
+ * the array index becomes the field's `pos` in the returned map. Throws if
+ * two fields share the same `name`.
+ *
+ * @example
+ * const pageBlock = defineBlock({
+ *   name: 'page',
+ *   is_root: true,
+ *   schema: [
+ *     defineField('headline', { type: 'text', required: true }),
+ *   ],
+ * });
+ */
+declare function defineBlock<TName extends string, const TInputSchema extends BlockSchemaInput, TIsRoot extends boolean = false, TIsNestable extends boolean = true, TComponentGroupUuid extends string | null = null>(block: BlockInput<TName, TInputSchema, TIsRoot, TIsNestable, TComponentGroupUuid>): DefinedBlock<TName, SchemaArrayToRecord<TInputSchema>, TIsRoot, TIsNestable, TComponentGroupUuid>;
+/**
+ * Defines a block creation payload for the MAPI.
+ *
+ * @example
+ * const payload = defineBlockCreate({ name: 'page', schema: { ... } });
+ */
+declare const defineBlockCreate: (block: ComponentCreate) => ComponentCreate;
+/**
+ * Defines a block update payload for the MAPI.
+ *
+ * @example
+ * const payload = defineBlockUpdate({ display_name: 'Page' });
+ */
+declare const defineBlockUpdate: (block: ComponentUpdate) => ComponentUpdate;
+//#endregion
+export { Block, BlockSchema, NestableBlocks, RootBlocks, defineBlock, defineBlockCreate, defineBlockUpdate };
+//# sourceMappingURL=define-block.d.cts.map

package/dist/helpers/define-block.d.mts

@@ -0,0 +1,90 @@
+import { Component, ComponentCreate, ComponentSchemaField, ComponentUpdate } from "../generated/mapi-types.mjs";
+import { Prettify } from "../utils/prettify.mjs";
+
+//#region src/helpers/define-block.d.ts
+declare const BLOCK_DEFAULTS: {
+  id: number;
+  created_at: string;
+  updated_at: string;
+  is_root: boolean;
+  is_nestable: boolean;
+  component_group_uuid: null;
+};
+/** Input form: an ordered array of named fields. The array index becomes `pos`. */
+type BlockSchemaInput = ReadonlyArray<ComponentSchemaField & {
+  name: string;
+  required?: boolean;
+}>;
+/** Wire form: the MAPI object map keyed by field name. This is what `defineBlock` returns. */
+type BlockSchema = Record<string, ComponentSchemaField & {
+  required?: boolean;
+}>;
+/** Converts an array-form schema input into the wire-shape object map at the type level. */
+type SchemaArrayToRecord<T extends BlockSchemaInput> = { [F in T[number] as F['name']]: Omit<F, 'name'> };
+/**
+ * A Storyblok block.
+ */
+type Block<TName extends string = string, TBlockSchema extends BlockSchema = BlockSchema, TIsRoot extends boolean = boolean, TIsNestable extends boolean = boolean, TComponentGroupUuid extends string | null = string | null> = Prettify<Omit<Component, 'name' | 'schema' | 'is_root' | 'is_nestable' | 'component_group_uuid'> & {
+  name: TName;
+  schema: TBlockSchema;
+  is_root?: TIsRoot;
+  is_nestable?: TIsNestable;
+  component_group_uuid?: TComponentGroupUuid;
+}>;
+/** Extract only root blocks from a schema union. */
+type RootBlocks<T extends Block> = T extends {
+  is_root: true;
+} ? T : never;
+/** Extract only nestable blocks from a schema union. */
+type NestableBlocks<T extends Block> = T extends {
+  is_nestable: true;
+} ? T : never;
+/** Fields that have safe defaults and may be omitted from block input. */
+type BlockOptional = keyof typeof BLOCK_DEFAULTS;
+type BlockInput<TName extends string = string, TInputSchema extends BlockSchemaInput = BlockSchemaInput, TIsRoot extends boolean = false, TIsNestable extends boolean = true, TComponentGroupUuid extends string | null = null> = Prettify<Omit<Component, 'name' | 'schema' | 'is_root' | 'is_nestable' | 'component_group_uuid' | BlockOptional> & {
+  name: TName;
+  schema: TInputSchema;
+  is_root?: TIsRoot;
+  is_nestable?: TIsNestable;
+  component_group_uuid?: TComponentGroupUuid;
+} & Partial<Pick<Component, Exclude<BlockOptional, 'is_root' | 'is_nestable' | 'component_group_uuid'>>>>;
+type DefinedBlock<TName extends string, TBlockSchema, TIsRoot extends boolean, TIsNestable extends boolean, TComponentGroupUuid extends string | null> = Prettify<Omit<Component, 'name' | 'schema' | 'is_root' | 'is_nestable' | 'component_group_uuid'> & {
+  name: TName;
+  schema: TBlockSchema;
+  is_root: TIsRoot;
+  is_nestable: TIsNestable;
+  component_group_uuid: TComponentGroupUuid;
+}>;
+/**
+ * Returns a {@link Block} with object-shape `schema` (matches the MAPI wire
+ * shape). The user-facing input is an ordered array of `defineField` calls;
+ * the array index becomes the field's `pos` in the returned map. Throws if
+ * two fields share the same `name`.
+ *
+ * @example
+ * const pageBlock = defineBlock({
+ *   name: 'page',
+ *   is_root: true,
+ *   schema: [
+ *     defineField('headline', { type: 'text', required: true }),
+ *   ],
+ * });
+ */
+declare function defineBlock<TName extends string, const TInputSchema extends BlockSchemaInput, TIsRoot extends boolean = false, TIsNestable extends boolean = true, TComponentGroupUuid extends string | null = null>(block: BlockInput<TName, TInputSchema, TIsRoot, TIsNestable, TComponentGroupUuid>): DefinedBlock<TName, SchemaArrayToRecord<TInputSchema>, TIsRoot, TIsNestable, TComponentGroupUuid>;
+/**
+ * Defines a block creation payload for the MAPI.
+ *
+ * @example
+ * const payload = defineBlockCreate({ name: 'page', schema: { ... } });
+ */
+declare const defineBlockCreate: (block: ComponentCreate) => ComponentCreate;
+/**
+ * Defines a block update payload for the MAPI.
+ *
+ * @example
+ * const payload = defineBlockUpdate({ display_name: 'Page' });
+ */
+declare const defineBlockUpdate: (block: ComponentUpdate) => ComponentUpdate;
+//#endregion
+export { Block, BlockSchema, NestableBlocks, RootBlocks, defineBlock, defineBlockCreate, defineBlockUpdate };
+//# sourceMappingURL=define-block.d.mts.map

package/dist/helpers/define-block.mjs

@@ -0,0 +1,48 @@
+//#region src/helpers/define-block.ts
+const BLOCK_DEFAULTS = {
+	id: 1,
+	created_at: "",
+	updated_at: "",
+	is_root: false,
+	is_nestable: true,
+	component_group_uuid: null
+};
+function defineBlock(block) {
+	const inputSchema = Array.isArray(block?.schema) ? block.schema : [];
+	const seen = /* @__PURE__ */ new Set();
+	const schemaRecord = {};
+	inputSchema.forEach((field, index) => {
+		const name = field?.name;
+		if (typeof name !== "string") return;
+		if (seen.has(name)) throw new Error(`defineBlock: duplicate field name "${name}" in block "${block?.name ?? ""}"`);
+		seen.add(name);
+		const { name: _name, ...rest } = field;
+		schemaRecord[name] = {
+			...rest,
+			pos: index
+		};
+	});
+	return {
+		...BLOCK_DEFAULTS,
+		...block,
+		schema: schemaRecord
+	};
+}
+/**
+* Defines a block creation payload for the MAPI.
+*
+* @example
+* const payload = defineBlockCreate({ name: 'page', schema: { ... } });
+*/
+const defineBlockCreate = (block) => block;
+/**
+* Defines a block update payload for the MAPI.
+*
+* @example
+* const payload = defineBlockUpdate({ display_name: 'Page' });
+*/
+const defineBlockUpdate = (block) => block;
+
+//#endregion
+export { defineBlock, defineBlockCreate, defineBlockUpdate };
+//# sourceMappingURL=define-block.mjs.map

package/dist/helpers/define-block.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-block.mjs","names":[],"sources":["../../src/helpers/define-block.ts"],"sourcesContent":["import type { ComponentCreate, Component as ComponentGenerated, ComponentUpdate, ComponentSchemaField as Field } from '../generated/mapi-types';\nimport type { Prettify } from '../utils/prettify';\n\nexport type { ComponentCreate, ComponentUpdate };\n\nconst BLOCK_DEFAULTS = {\n  id: 1,\n  created_at: '',\n  updated_at: '',\n  is_root: false,\n  is_nestable: true,\n  component_group_uuid: null,\n};\n\n/** Input form: an ordered array of named fields. The array index becomes `pos`. */\nexport type BlockSchemaInput = ReadonlyArray<Field & { name: string; required?: boolean }>;\n\n/** Wire form: the MAPI object map keyed by field name. This is what `defineBlock` returns. */\nexport type BlockSchema = Record<string, Field & { required?: boolean }>;\n\n/** Converts an array-form schema input into the wire-shape object map at the type level. */\nexport type SchemaArrayToRecord<T extends BlockSchemaInput> = {\n  [F in T[number] as F['name']]: Omit<F, 'name'>;\n};\n\n/**\n * A Storyblok block.\n */\nexport type Block<\n  TName extends string = string,\n  TBlockSchema extends BlockSchema = BlockSchema,\n  TIsRoot extends boolean = boolean,\n  TIsNestable extends boolean = boolean,\n  TComponentGroupUuid extends string | null = string | null,\n> = Prettify<\n  Omit<ComponentGenerated, 'name' | 'schema' | 'is_root' | 'is_nestable' | 'component_group_uuid'> & {\n    name: TName;\n    schema: TBlockSchema;\n    is_root?: TIsRoot;\n    is_nestable?: TIsNestable;\n    component_group_uuid?: TComponentGroupUuid;\n  }\n>;\n\n/** Extract only root blocks from a schema union. */\nexport type RootBlocks<T extends Block> =\n  T extends { is_root: true } ? T : never;\n\n/** Extract only nestable blocks from a schema union. */\nexport type NestableBlocks<T extends Block> =\n  T extends { is_nestable: true } ? T : never;\n\n/** Fields that have safe defaults and may be omitted from block input. */\ntype BlockOptional = keyof typeof BLOCK_DEFAULTS;\n\ntype BlockInput<\n  TName extends string = string,\n  TInputSchema extends BlockSchemaInput = BlockSchemaInput,\n  TIsRoot extends boolean = false,\n  TIsNestable extends boolean = true,\n  TComponentGroupUuid extends string | null = null,\n> = Prettify<\n  Omit<ComponentGenerated, 'name' | 'schema' | 'is_root' | 'is_nestable' | 'component_group_uuid' | BlockOptional> & {\n    name: TName;\n    schema: TInputSchema;\n    is_root?: TIsRoot;\n    is_nestable?: TIsNestable;\n    component_group_uuid?: TComponentGroupUuid;\n  } & Partial<Pick<ComponentGenerated, Exclude<BlockOptional, 'is_root' | 'is_nestable' | 'component_group_uuid'>>>\n>;\n\ntype DefinedBlock<\n  TName extends string,\n  TBlockSchema,\n  TIsRoot extends boolean,\n  TIsNestable extends boolean,\n  TComponentGroupUuid extends string | null,\n> = Prettify<\n  Omit<ComponentGenerated, 'name' | 'schema' | 'is_root' | 'is_nestable' | 'component_group_uuid'> & {\n    name: TName;\n    schema: TBlockSchema;\n    is_root: TIsRoot;\n    is_nestable: TIsNestable;\n    component_group_uuid: TComponentGroupUuid;\n  }\n>;\n\n/**\n * Returns a {@link Block} with object-shape `schema` (matches the MAPI wire\n * shape). The user-facing input is an ordered array of `defineField` calls;\n * the array index becomes the field's `pos` in the returned map. Throws if\n * two fields share the same `name`.\n *\n * @example\n * const pageBlock = defineBlock({\n *   name: 'page',\n *   is_root: true,\n *   schema: [\n *     defineField('headline', { type: 'text', required: true }),\n *   ],\n * });\n */\nexport function defineBlock<\n  TName extends string,\n  const TInputSchema extends BlockSchemaInput,\n  TIsRoot extends boolean = false,\n  TIsNestable extends boolean = true,\n  TComponentGroupUuid extends string | null = null,\n>(\n  block: BlockInput<TName, TInputSchema, TIsRoot, TIsNestable, TComponentGroupUuid>,\n): DefinedBlock<TName, SchemaArrayToRecord<TInputSchema>, TIsRoot, TIsNestable, TComponentGroupUuid>;\n\nexport function defineBlock(block: any) {\n  const inputSchema = Array.isArray(block?.schema) ? block.schema : [];\n  const seen = new Set<string>();\n  const schemaRecord: Record<string, unknown> = {};\n  inputSchema.forEach((field: any, index: number) => {\n    const name = field?.name;\n    if (typeof name !== 'string') {\n      return;\n    }\n    if (seen.has(name)) {\n      throw new Error(`defineBlock: duplicate field name \"${name}\" in block \"${block?.name ?? ''}\"`);\n    }\n    seen.add(name);\n    const { name: _name, ...rest } = field;\n    schemaRecord[name] = { ...rest, pos: index };\n  });\n  return { ...BLOCK_DEFAULTS, ...block, schema: schemaRecord };\n}\n\n/**\n * Defines a block creation payload for the MAPI.\n *\n * @example\n * const payload = defineBlockCreate({ name: 'page', schema: { ... } });\n */\nexport const defineBlockCreate = (block: ComponentCreate): ComponentCreate => block;\n\n/**\n * Defines a block update payload for the MAPI.\n *\n * @example\n * const payload = defineBlockUpdate({ display_name: 'Page' });\n */\nexport const defineBlockUpdate = (block: ComponentUpdate): ComponentUpdate => block;\n"],"mappings":";AAKA,MAAM,iBAAiB;CACrB,IAAI;CACJ,YAAY;CACZ,YAAY;CACZ,SAAS;CACT,aAAa;CACb,sBAAsB;CACvB;AAoGD,SAAgB,YAAY,OAAY;CACtC,MAAM,cAAc,MAAM,QAAQ,OAAO,OAAO,GAAG,MAAM,SAAS,EAAE;CACpE,MAAM,uBAAO,IAAI,KAAa;CAC9B,MAAM,eAAwC,EAAE;AAChD,aAAY,SAAS,OAAY,UAAkB;EACjD,MAAM,OAAO,OAAO;AACpB,MAAI,OAAO,SAAS,SAClB;AAEF,MAAI,KAAK,IAAI,KAAK,CAChB,OAAM,IAAI,MAAM,sCAAsC,KAAK,cAAc,OAAO,QAAQ,GAAG,GAAG;AAEhG,OAAK,IAAI,KAAK;EACd,MAAM,EAAE,MAAM,OAAO,GAAG,SAAS;AACjC,eAAa,QAAQ;GAAE,GAAG;GAAM,KAAK;GAAO;GAC5C;AACF,QAAO;EAAE,GAAG;EAAgB,GAAG;EAAO,QAAQ;EAAc;;;;;;;;AAS9D,MAAa,qBAAqB,UAA4C;;;;;;;AAQ9E,MAAa,qBAAqB,UAA4C"}