@storyblok/schema 0.1.0-alpha.1 → 0.1.0-alpha.3

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

@@ -1 +1 @@
-{"version":3,"file":"define-block.mjs","names":[],"sources":["../../src/helpers/define-block.ts"],"sourcesContent":["import type {\n  Block,\n  BlockFields,\n  NestableBlock,\n  RootBlock,\n} from '../generated/types/block';\nimport type { Prettify } from '../utils/prettify';\n\nexport type { Block, BlockFields, NestableBlock, RootBlock };\n\nconst BLOCK_DEFAULTS = {\n  id: 1,\n  created_at: '',\n  updated_at: '',\n  is_root: false,\n  is_nestable: true,\n};\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  TFields extends BlockFields = BlockFields,\n  TIsRoot extends boolean = false,\n  TIsNestable extends boolean = true,\n> = Prettify<\n  Omit<Block, 'name' | 'fields' | 'is_root' | 'is_nestable' | BlockOptional> & {\n    name: TName;\n    fields: TFields;\n    is_root?: TIsRoot;\n    is_nestable?: TIsNestable;\n  } & Partial<Pick<Block, Exclude<BlockOptional, 'is_root' | 'is_nestable'>>>\n>;\n\ntype DefinedBlock<\n  TName extends string,\n  TFields extends BlockFields,\n  TIsRoot extends boolean,\n  TIsNestable extends boolean,\n> = Prettify<\n  Omit<Block, 'name' | 'fields' | 'is_root' | 'is_nestable'> & {\n    name: TName;\n    fields: TFields;\n    is_root: TIsRoot;\n    is_nestable: TIsNestable;\n  }\n>;\n\n/**\n * Returns a {@link Block} content-shape definition. The user-facing input is an\n * ordered array of `defineField` calls under `fields`; the array index becomes\n * each field's `pos`. A thin, strongly-typed helper — it does not map to the\n * MAPI wire shape (the CLI owns the DSL→wire mapping). Throws only on duplicate\n * field names (a programming error).\n *\n * @example\n * const pageBlock = defineBlock({\n *   name: 'page',\n *   is_root: true,\n *   fields: [\n *     defineField('headline', { type: 'text', required: true }),\n *   ],\n * });\n */\nexport function defineBlock<\n  TName extends string,\n  const TFields extends BlockFields,\n  TIsRoot extends boolean = false,\n  TIsNestable extends boolean = true,\n>(\n  block: BlockInput<TName, TFields, TIsRoot, TIsNestable>,\n): DefinedBlock<TName, TFields, TIsRoot, TIsNestable>;\n\nexport function defineBlock(block: any) {\n  const inputFields = Array.isArray(block?.fields) ? block.fields : [];\n  const seen = new Set<string>();\n  const fields = inputFields.map((field: any, index: number) => {\n    const name = field?.name;\n    if (typeof name === 'string') {\n      if (seen.has(name)) {\n        throw new Error(`defineBlock: duplicate field name \"${name}\" in block \"${block?.name ?? ''}\"`);\n      }\n      seen.add(name);\n    }\n    return { ...field, pos: index };\n  });\n  return { ...BLOCK_DEFAULTS, ...block, fields };\n}\n"],"mappings":";AAUA,MAAM,iBAAiB;CACrB,IAAI;CACJ,YAAY;CACZ,YAAY;CACZ,SAAS;CACT,aAAa;CACd;AA0DD,SAAgB,YAAY,OAAY;CACtC,MAAM,cAAc,MAAM,QAAQ,OAAO,OAAO,GAAG,MAAM,SAAS,EAAE;CACpE,MAAM,uBAAO,IAAI,KAAa;CAC9B,MAAM,SAAS,YAAY,KAAK,OAAY,UAAkB;EAC5D,MAAM,OAAO,OAAO;AACpB,MAAI,OAAO,SAAS,UAAU;AAC5B,OAAI,KAAK,IAAI,KAAK,CAChB,OAAM,IAAI,MAAM,sCAAsC,KAAK,cAAc,OAAO,QAAQ,GAAG,GAAG;AAEhG,QAAK,IAAI,KAAK;;AAEhB,SAAO;GAAE,GAAG;GAAO,KAAK;GAAO;GAC/B;AACF,QAAO;EAAE,GAAG;EAAgB,GAAG;EAAO;EAAQ"}
+{"version":3,"file":"define-block.mjs","names":[],"sources":["../../src/helpers/define-block.ts"],"sourcesContent":["import type {\n  Block,\n  BlockFields,\n  NestableBlock,\n  RootBlock,\n} from '../generated/types/block';\nimport type { BlockFolder } from './define-folder';\nimport type { Prettify } from '../utils/prettify';\n\nexport type { Block, BlockFields, NestableBlock, RootBlock };\n\nconst BLOCK_DEFAULTS = {\n  id: 1,\n  created_at: '',\n  updated_at: '',\n  is_root: false,\n  is_nestable: true,\n};\n\n/** Fields that have safe defaults and may be omitted from block input. */\ntype BlockOptional = keyof typeof BLOCK_DEFAULTS;\n\n/** Accepted input for a block's `folder`: a folder ref, a raw path string, or `null` to explicitly ungroup. */\ntype FolderInput = BlockFolder | string | null;\n\n/** Normalizes a folder input type to the display path literal it resolves to. */\ntype NormalizeFolder<T> = T extends { path: infer P extends string } ? P : T;\n\ntype BlockInput<\n  TName extends string = string,\n  TFields extends BlockFields = BlockFields,\n  TIsRoot extends boolean = false,\n  TIsNestable extends boolean = true,\n  TFolder extends FolderInput | undefined = undefined,\n> = Prettify<\n  Omit<Block, 'name' | 'fields' | 'is_root' | 'is_nestable' | 'folder' | BlockOptional> & {\n    name: TName;\n    fields: TFields;\n    is_root?: TIsRoot;\n    is_nestable?: TIsNestable;\n    folder?: TFolder;\n  } & Partial<Pick<Block, Exclude<BlockOptional, 'is_root' | 'is_nestable'>>>\n>;\n\ntype DefinedBlock<\n  TName extends string,\n  TFields extends BlockFields,\n  TIsRoot extends boolean,\n  TIsNestable extends boolean,\n  TFolder extends FolderInput | undefined = undefined,\n> = Prettify<\n  Omit<Block, 'name' | 'fields' | 'is_root' | 'is_nestable' | 'folder'> & {\n    name: TName;\n    fields: TFields;\n    is_root: TIsRoot;\n    is_nestable: TIsNestable;\n  } & (TFolder extends undefined ? unknown : { folder: NormalizeFolder<TFolder> })\n>;\n\n/**\n * Returns a {@link Block} content-shape definition. The user-facing input is an\n * ordered array of `defineField` calls under `fields`; the array index becomes\n * each field's `pos`. A thin, strongly-typed helper — it does not map to the\n * MAPI wire shape (the CLI owns the DSL→wire mapping). Throws only on duplicate\n * field names (a programming error).\n *\n * @example\n * const pageBlock = defineBlock({\n *   name: 'page',\n *   is_root: true,\n *   fields: [\n *     defineField('headline', { type: 'text', required: true }),\n *   ],\n * });\n */\nexport function defineBlock<\n  TName extends string,\n  const TFields extends BlockFields,\n  TIsRoot extends boolean = false,\n  TIsNestable extends boolean = true,\n  const TFolder extends FolderInput | undefined = undefined,\n>(\n  block: BlockInput<TName, TFields, TIsRoot, TIsNestable, TFolder>,\n): DefinedBlock<TName, TFields, TIsRoot, TIsNestable, TFolder>;\n\nexport function defineBlock(block: any) {\n  const inputFields = Array.isArray(block?.fields) ? block.fields : [];\n  const seen = new Set<string>();\n  const fields = inputFields.map((field: any, index: number) => {\n    const name = field?.name;\n    if (typeof name === 'string') {\n      if (seen.has(name)) {\n        throw new Error(`defineBlock: duplicate field name \"${name}\" in block \"${block?.name ?? ''}\"`);\n      }\n      seen.add(name);\n    }\n    return { ...field, pos: index };\n  });\n\n  const { folder, ...restBlock } = block ?? {};\n  if (folder !== undefined && typeof restBlock.component_group_uuid === 'string') {\n    throw new Error(`defineBlock: block \"${block?.name ?? ''}\" sets both \"folder\" and \"component_group_uuid\"; use one`);\n  }\n  if (typeof folder === 'string' && !folder.split('/').some(segment => segment.trim() !== '')) {\n    throw new Error(`defineBlock: block \"${block?.name ?? ''}\" has an empty \"folder\" path`);\n  }\n  const normalizedFolder = folder === undefined\n    ? undefined\n    : (folder !== null && typeof folder === 'object' ? folder.path : folder);\n\n  return {\n    ...BLOCK_DEFAULTS,\n    ...restBlock,\n    ...(folder !== undefined && { folder: normalizedFolder }),\n    fields,\n  };\n}\n"],"mappings":";AAWA,MAAM,iBAAiB;CACrB,IAAI;CACJ,YAAY;CACZ,YAAY;CACZ,SAAS;CACT,aAAa;CACd;AAoED,SAAgB,YAAY,OAAY;CACtC,MAAM,cAAc,MAAM,QAAQ,OAAO,OAAO,GAAG,MAAM,SAAS,EAAE;CACpE,MAAM,uBAAO,IAAI,KAAa;CAC9B,MAAM,SAAS,YAAY,KAAK,OAAY,UAAkB;EAC5D,MAAM,OAAO,OAAO;AACpB,MAAI,OAAO,SAAS,UAAU;AAC5B,OAAI,KAAK,IAAI,KAAK,CAChB,OAAM,IAAI,MAAM,sCAAsC,KAAK,cAAc,OAAO,QAAQ,GAAG,GAAG;AAEhG,QAAK,IAAI,KAAK;;AAEhB,SAAO;GAAE,GAAG;GAAO,KAAK;GAAO;GAC/B;CAEF,MAAM,EAAE,QAAQ,GAAG,cAAc,SAAS,EAAE;AAC5C,KAAI,WAAW,UAAa,OAAO,UAAU,yBAAyB,SACpE,OAAM,IAAI,MAAM,uBAAuB,OAAO,QAAQ,GAAG,0DAA0D;AAErH,KAAI,OAAO,WAAW,YAAY,CAAC,OAAO,MAAM,IAAI,CAAC,MAAK,YAAW,QAAQ,MAAM,KAAK,GAAG,CACzF,OAAM,IAAI,MAAM,uBAAuB,OAAO,QAAQ,GAAG,8BAA8B;CAEzF,MAAM,mBAAmB,WAAW,SAChC,SACC,WAAW,QAAQ,OAAO,WAAW,WAAW,OAAO,OAAO;AAEnE,QAAO;EACL,GAAG;EACH,GAAG;EACH,GAAI,WAAW,UAAa,EAAE,QAAQ,kBAAkB;EACxD;EACD"}

package/dist/helpers/define-field-plugin.cjs

@@ -0,0 +1,21 @@
+
+//#region src/helpers/define-field-plugin.ts
+/**
+* Declares a custom field plugin: both the `fieldType` literal and the value
+* type infer from the single argument. `value` accepts any Standard Schema
+* validator (Zod, Valibot, ArkType, or hand-written) and is retained for
+* runtime use. A thin, strongly-typed identity helper — it does not validate.
+*
+* @example
+* const colorPicker = defineFieldPlugin({
+*   fieldType: 'my-custom-color-picker',
+*   value: z.object({ color: z.string(), alpha: z.number() }),
+* });
+*/
+function defineFieldPlugin(config) {
+	return config;
+}
+
+//#endregion
+exports.defineFieldPlugin = defineFieldPlugin;
+//# sourceMappingURL=define-field-plugin.cjs.map

package/dist/helpers/define-field-plugin.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-field-plugin.cjs","names":[],"sources":["../../src/helpers/define-field-plugin.ts"],"sourcesContent":["import type { StandardSchemaV1 } from '@standard-schema/spec';\n\n/**\n * Binds a Storyblok custom field `field_type` to a\n * [Standard Schema](https://standardschema.dev) validator. The validator (`S`,\n * retained on `value`) supplies both the static value type\n * (`StandardSchemaV1.InferOutput<S>`) and a runtime handle, so a single\n * declaration serves types and (future) runtime validation.\n */\nexport interface FieldPlugin<\n  F extends string = string,\n  S extends StandardSchemaV1 = StandardSchemaV1,\n> {\n  fieldType: F;\n  value: S;\n}\n\n/**\n * Declares a custom field plugin: both the `fieldType` literal and the value\n * type infer from the single argument. `value` accepts any Standard Schema\n * validator (Zod, Valibot, ArkType, or hand-written) and is retained for\n * runtime use. A thin, strongly-typed identity helper — it does not validate.\n *\n * @example\n * const colorPicker = defineFieldPlugin({\n *   fieldType: 'my-custom-color-picker',\n *   value: z.object({ color: z.string(), alpha: z.number() }),\n * });\n */\nexport function defineFieldPlugin<\n  const F extends string,\n  S extends StandardSchemaV1,\n>(config: { fieldType: F; value: S }): FieldPlugin<F, S> {\n  return config;\n}\n"],"mappings":";;;;;;;;;;;;;;AA6BA,SAAgB,kBAGd,QAAuD;AACvD,QAAO"}

package/dist/helpers/define-field-plugin.d.cts

@@ -0,0 +1,33 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/helpers/define-field-plugin.d.ts
+/**
+ * Binds a Storyblok custom field `field_type` to a
+ * [Standard Schema](https://standardschema.dev) validator. The validator (`S`,
+ * retained on `value`) supplies both the static value type
+ * (`StandardSchemaV1.InferOutput<S>`) and a runtime handle, so a single
+ * declaration serves types and (future) runtime validation.
+ */
+interface FieldPlugin<F extends string = string, S extends StandardSchemaV1 = StandardSchemaV1> {
+  fieldType: F;
+  value: S;
+}
+/**
+ * Declares a custom field plugin: both the `fieldType` literal and the value
+ * type infer from the single argument. `value` accepts any Standard Schema
+ * validator (Zod, Valibot, ArkType, or hand-written) and is retained for
+ * runtime use. A thin, strongly-typed identity helper — it does not validate.
+ *
+ * @example
+ * const colorPicker = defineFieldPlugin({
+ *   fieldType: 'my-custom-color-picker',
+ *   value: z.object({ color: z.string(), alpha: z.number() }),
+ * });
+ */
+declare function defineFieldPlugin<const F extends string, S extends StandardSchemaV1>(config: {
+  fieldType: F;
+  value: S;
+}): FieldPlugin<F, S>;
+//#endregion
+export { FieldPlugin, defineFieldPlugin };
+//# sourceMappingURL=define-field-plugin.d.cts.map

package/dist/helpers/define-field-plugin.d.mts

@@ -0,0 +1,33 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/helpers/define-field-plugin.d.ts
+/**
+ * Binds a Storyblok custom field `field_type` to a
+ * [Standard Schema](https://standardschema.dev) validator. The validator (`S`,
+ * retained on `value`) supplies both the static value type
+ * (`StandardSchemaV1.InferOutput<S>`) and a runtime handle, so a single
+ * declaration serves types and (future) runtime validation.
+ */
+interface FieldPlugin<F extends string = string, S extends StandardSchemaV1 = StandardSchemaV1> {
+  fieldType: F;
+  value: S;
+}
+/**
+ * Declares a custom field plugin: both the `fieldType` literal and the value
+ * type infer from the single argument. `value` accepts any Standard Schema
+ * validator (Zod, Valibot, ArkType, or hand-written) and is retained for
+ * runtime use. A thin, strongly-typed identity helper — it does not validate.
+ *
+ * @example
+ * const colorPicker = defineFieldPlugin({
+ *   fieldType: 'my-custom-color-picker',
+ *   value: z.object({ color: z.string(), alpha: z.number() }),
+ * });
+ */
+declare function defineFieldPlugin<const F extends string, S extends StandardSchemaV1>(config: {
+  fieldType: F;
+  value: S;
+}): FieldPlugin<F, S>;
+//#endregion
+export { FieldPlugin, defineFieldPlugin };
+//# sourceMappingURL=define-field-plugin.d.mts.map

package/dist/helpers/define-field-plugin.mjs

@@ -0,0 +1,20 @@
+//#region src/helpers/define-field-plugin.ts
+/**
+* Declares a custom field plugin: both the `fieldType` literal and the value
+* type infer from the single argument. `value` accepts any Standard Schema
+* validator (Zod, Valibot, ArkType, or hand-written) and is retained for
+* runtime use. A thin, strongly-typed identity helper — it does not validate.
+*
+* @example
+* const colorPicker = defineFieldPlugin({
+*   fieldType: 'my-custom-color-picker',
+*   value: z.object({ color: z.string(), alpha: z.number() }),
+* });
+*/
+function defineFieldPlugin(config) {
+	return config;
+}
+
+//#endregion
+export { defineFieldPlugin };
+//# sourceMappingURL=define-field-plugin.mjs.map

package/dist/helpers/define-field-plugin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-field-plugin.mjs","names":[],"sources":["../../src/helpers/define-field-plugin.ts"],"sourcesContent":["import type { StandardSchemaV1 } from '@standard-schema/spec';\n\n/**\n * Binds a Storyblok custom field `field_type` to a\n * [Standard Schema](https://standardschema.dev) validator. The validator (`S`,\n * retained on `value`) supplies both the static value type\n * (`StandardSchemaV1.InferOutput<S>`) and a runtime handle, so a single\n * declaration serves types and (future) runtime validation.\n */\nexport interface FieldPlugin<\n  F extends string = string,\n  S extends StandardSchemaV1 = StandardSchemaV1,\n> {\n  fieldType: F;\n  value: S;\n}\n\n/**\n * Declares a custom field plugin: both the `fieldType` literal and the value\n * type infer from the single argument. `value` accepts any Standard Schema\n * validator (Zod, Valibot, ArkType, or hand-written) and is retained for\n * runtime use. A thin, strongly-typed identity helper — it does not validate.\n *\n * @example\n * const colorPicker = defineFieldPlugin({\n *   fieldType: 'my-custom-color-picker',\n *   value: z.object({ color: z.string(), alpha: z.number() }),\n * });\n */\nexport function defineFieldPlugin<\n  const F extends string,\n  S extends StandardSchemaV1,\n>(config: { fieldType: F; value: S }): FieldPlugin<F, S> {\n  return config;\n}\n"],"mappings":";;;;;;;;;;;;;AA6BA,SAAgB,kBAGd,QAAuD;AACvD,QAAO"}

package/dist/helpers/define-field.cjs

@@ -1,13 +1,20 @@
 const require_is_record = require('../utils/is-record.cjs');
 
 //#region src/helpers/define-field.ts
+/** Type guard for a defined folder ref: has `path`, and never `fields` (defined block) or `slug` (datasource). */
+const isFolderRef = (ref) => require_is_record.isRecord(ref) && typeof ref.path === "string" && !Array.isArray(ref.fields) && !("slug" in ref);
 function defineField(name, field) {
 	const { allow, datasource, ...rest } = field;
 	const normalized = {
 		...rest,
 		name
 	};
-	if (allow !== void 0) normalized.allow = (Array.isArray(allow) ? allow : [allow]).map((ref) => typeof ref === "string" ? ref : require_is_record.isRecord(ref) ? ref.name : void 0);
+	if (allow !== void 0) {
+		const refs = Array.isArray(allow) ? allow : [allow];
+		const folderRefs = refs.filter(isFolderRef);
+		if (folderRefs.length > 0 && folderRefs.length < refs.length) throw new Error(`defineField: "allow" on field "${name}" mixes block and folder references; the editor restricts by either blocks or folders, not both`);
+		normalized.allow = refs.map((ref) => isFolderRef(ref) ? { folder: ref.path } : typeof ref === "string" ? ref : require_is_record.isRecord(ref) ? ref.name : void 0);
+	}
 	if (datasource !== void 0) normalized.datasource = typeof datasource === "string" ? datasource : require_is_record.isRecord(datasource) ? datasource.slug : void 0;
 	return normalized;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"define-field.cjs","names":["isRecord"],"sources":["../../src/helpers/define-field.ts"],"sourcesContent":["import type {\n  AssetFieldValue,\n  BlockContent,\n  BlockContentInput,\n  BlocksFieldValue,\n  Field,\n  FieldType,\n  FieldValue,\n  FieldValueInput,\n  MultilinkFieldValue,\n  PluginFieldValue,\n  RichtextFieldValue,\n  TableFieldValue,\n} from '../generated/types/field';\nimport type { Prettify } from '../utils/prettify';\nimport { isRecord } from '../utils/is-record';\n\nexport type {\n  AssetFieldValue,\n  BlockContent,\n  BlockContentInput,\n  BlocksFieldValue,\n  Field,\n  FieldType,\n  FieldValue,\n  FieldValueInput,\n  MultilinkFieldValue,\n  PluginFieldValue,\n  RichtextFieldValue,\n  TableFieldValue,\n};\n\n/** A block reference for `allow`: a defined block object or its name. */\ntype AllowRef = string | { name: string };\n/** A datasource reference for `datasource`: a defined datasource object or its slug. */\ntype DatasourceRef = string | { slug: string };\n\ntype NameOf<T> = T extends string ? T : T extends { name: infer N extends string } ? N : never;\ntype SlugOf<T> = T extends string ? T : T extends { slug: infer S extends string } ? S : never;\n\n/** Normalizes an `allow` input (ref, name, or array thereof) to a tuple of block-name strings. */\ntype NormalizeAllow<T> = T extends readonly any[]\n  ? { [I in keyof T]: NameOf<T[I]> }\n  : readonly [NameOf<T>];\n\n/**\n * Field config accepted by {@link defineField}: the content-shape field plus the\n * DSL reference keys. `allow` replaces the wire `component_whitelist`; `datasource`\n * holds the datasource ref/slug (the wire `source` selector still passes through).\n */\nexport type FieldInput = Field & {\n  allow?: AllowRef | readonly AllowRef[];\n  datasource?: DatasourceRef;\n  required?: boolean;\n};\n\n/** Result of {@link defineField}: the field stamped with `name`, with refs normalized to strings. */\nexport type DefinedField<TName extends string, TField extends FieldInput> = Prettify<\n  Omit<TField, 'allow' | 'datasource' | 'name'>\n  & { name: TName }\n  & (TField extends { allow: infer A } ? { allow: NormalizeAllow<A> } : unknown)\n  & (TField extends { datasource: infer D } ? { datasource: SlugOf<D> } : unknown)\n>;\n\n/**\n * Returns a {@link Field} stamped with the given `name`, normalizing reference\n * keys to strings so everything downstream sees plain names/slugs. A thin,\n * strongly-typed identity helper — it does not validate or throw.\n *\n * Use inside a {@link defineBlock} `fields` array — `pos` is injected from the\n * array index by `defineBlock`.\n *\n * @example\n * defineField('headline', { type: 'text', max_length: 100, required: true });\n * defineField('body', { type: 'bloks', allow: [heroBlock, 'teaser'] });\n * defineField('theme', { type: 'option', source: 'internal', datasource: colors });\n */\nexport function defineField<\n  const TName extends string,\n  const TField extends FieldInput,\n>(name: TName, field: TField): DefinedField<TName, TField>;\nexport function defineField(name: string, field: Record<string, unknown>): Record<string, unknown> {\n  const { allow, datasource, ...rest } = field;\n  const normalized: Record<string, unknown> = { ...rest, name };\n  if (allow !== undefined) {\n    const refs = Array.isArray(allow) ? allow : [allow];\n    normalized.allow = refs.map(ref => (typeof ref === 'string' ? ref : isRecord(ref) ? ref.name : undefined));\n  }\n  if (datasource !== undefined) {\n    normalized.datasource = typeof datasource === 'string' ? datasource : isRecord(datasource) ? datasource.slug : undefined;\n  }\n  return normalized;\n}\n"],"mappings":";;;AAiFA,SAAgB,YAAY,MAAc,OAAyD;CACjG,MAAM,EAAE,OAAO,YAAY,GAAG,SAAS;CACvC,MAAM,aAAsC;EAAE,GAAG;EAAM;EAAM;AAC7D,KAAI,UAAU,OAEZ,YAAW,SADE,MAAM,QAAQ,MAAM,GAAG,QAAQ,CAAC,MAAM,EAC3B,KAAI,QAAQ,OAAO,QAAQ,WAAW,MAAMA,2BAAS,IAAI,GAAG,IAAI,OAAO,OAAW;AAE5G,KAAI,eAAe,OACjB,YAAW,aAAa,OAAO,eAAe,WAAW,aAAaA,2BAAS,WAAW,GAAG,WAAW,OAAO;AAEjH,QAAO"}
+{"version":3,"file":"define-field.cjs","names":["isRecord"],"sources":["../../src/helpers/define-field.ts"],"sourcesContent":["import type {\n  AssetFieldValue,\n  BlockContent,\n  BlockContentInput,\n  BlocksFieldValue,\n  Field,\n  FieldType,\n  FieldValue,\n  FieldValueInput,\n  MultilinkFieldValue,\n  PluginFieldValue,\n  RichtextFieldValue,\n  TableFieldValue,\n} from '../generated/types/field';\nimport type { BlockFolder } from './define-folder';\nimport type { Prettify } from '../utils/prettify';\nimport { isRecord } from '../utils/is-record';\n\nexport type {\n  AssetFieldValue,\n  BlockContent,\n  BlockContentInput,\n  BlocksFieldValue,\n  Field,\n  FieldType,\n  FieldValue,\n  FieldValueInput,\n  MultilinkFieldValue,\n  PluginFieldValue,\n  RichtextFieldValue,\n  TableFieldValue,\n};\n\n/** A block reference for `allow`: a defined block object or its name. */\ntype AllowRef = string | { name: string };\n/** A folder reference for `allow`: a defined folder object (no string shorthand — bare strings are block names). */\ntype FolderAllowRef = BlockFolder;\n/** A datasource reference for `datasource`: a defined datasource object or its slug. */\ntype DatasourceRef = string | { slug: string };\n\ntype NameOf<T> = T extends string ? T : T extends { name: infer N extends string } ? N : never;\ntype SlugOf<T> = T extends string ? T : T extends { slug: infer S extends string } ? S : never;\n\n/** Normalizes a single `allow` entry: folder refs to `{ folder: path }`, everything else to a name string. */\ntype NormalizeAllowEntry<T> = T extends { path: infer P extends string }\n  ? { folder: P }\n  : NameOf<T>;\n/** Normalizes an `allow` input (ref, name, or array thereof) to a tuple of normalized entries. */\ntype NormalizeAllow<T> = T extends readonly any[]\n  ? { [I in keyof T]: NormalizeAllowEntry<T[I]> }\n  : readonly [NormalizeAllowEntry<T>];\n\n/** Type guard for a defined folder ref: has `path`, and never `fields` (defined block) or `slug` (datasource). */\nconst isFolderRef = (ref: unknown): ref is BlockFolder =>\n  isRecord(ref) && typeof ref.path === 'string' && !Array.isArray(ref.fields) && !('slug' in ref);\n\n/**\n * Field config accepted by {@link defineField}: the content-shape field plus the\n * DSL reference keys. `allow` replaces the wire `component_whitelist`; `datasource`\n * holds the datasource ref/slug (the wire `source` selector still passes through).\n */\nexport type FieldInput = Field & {\n  allow?: AllowRef | FolderAllowRef | readonly (AllowRef | FolderAllowRef)[];\n  datasource?: DatasourceRef;\n  required?: boolean;\n};\n\n/** Result of {@link defineField}: the field stamped with `name`, with refs normalized to strings. */\nexport type DefinedField<TName extends string, TField extends FieldInput> = Prettify<\n  Omit<TField, 'allow' | 'datasource' | 'name'>\n  & { name: TName }\n  & (TField extends { allow: infer A } ? { allow: NormalizeAllow<A> } : unknown)\n  & (TField extends { datasource: infer D } ? { datasource: SlugOf<D> } : unknown)\n>;\n\n/**\n * Returns a {@link Field} stamped with the given `name`, normalizing reference\n * keys to strings so everything downstream sees plain names/slugs. A thin,\n * strongly-typed identity helper — it does not validate or throw.\n *\n * Use inside a {@link defineBlock} `fields` array — `pos` is injected from the\n * array index by `defineBlock`.\n *\n * @example\n * defineField('headline', { type: 'text', max_length: 100, required: true });\n * defineField('body', { type: 'bloks', allow: [heroBlock, 'teaser'] });\n * defineField('theme', { type: 'option', source: 'internal', datasource: colors });\n */\nexport function defineField<\n  const TName extends string,\n  const TField extends FieldInput,\n>(name: TName, field: TField): DefinedField<TName, TField>;\nexport function defineField(name: string, field: Record<string, unknown>): Record<string, unknown> {\n  const { allow, datasource, ...rest } = field;\n  const normalized: Record<string, unknown> = { ...rest, name };\n  if (allow !== undefined) {\n    const refs = Array.isArray(allow) ? allow : [allow];\n    const folderRefs = refs.filter(isFolderRef);\n    if (folderRefs.length > 0 && folderRefs.length < refs.length) {\n      throw new Error(`defineField: \"allow\" on field \"${name}\" mixes block and folder references; the editor restricts by either blocks or folders, not both`);\n    }\n    normalized.allow = refs.map(ref =>\n      isFolderRef(ref)\n        ? { folder: ref.path }\n        : (typeof ref === 'string' ? ref : isRecord(ref) ? ref.name : undefined),\n    );\n  }\n  if (datasource !== undefined) {\n    normalized.datasource = typeof datasource === 'string' ? datasource : isRecord(datasource) ? datasource.slug : undefined;\n  }\n  return normalized;\n}\n"],"mappings":";;;;AAqDA,MAAM,eAAe,QACnBA,2BAAS,IAAI,IAAI,OAAO,IAAI,SAAS,YAAY,CAAC,MAAM,QAAQ,IAAI,OAAO,IAAI,EAAE,UAAU;AAsC7F,SAAgB,YAAY,MAAc,OAAyD;CACjG,MAAM,EAAE,OAAO,YAAY,GAAG,SAAS;CACvC,MAAM,aAAsC;EAAE,GAAG;EAAM;EAAM;AAC7D,KAAI,UAAU,QAAW;EACvB,MAAM,OAAO,MAAM,QAAQ,MAAM,GAAG,QAAQ,CAAC,MAAM;EACnD,MAAM,aAAa,KAAK,OAAO,YAAY;AAC3C,MAAI,WAAW,SAAS,KAAK,WAAW,SAAS,KAAK,OACpD,OAAM,IAAI,MAAM,kCAAkC,KAAK,iGAAiG;AAE1J,aAAW,QAAQ,KAAK,KAAI,QAC1B,YAAY,IAAI,GACZ,EAAE,QAAQ,IAAI,MAAM,GACnB,OAAO,QAAQ,WAAW,MAAMA,2BAAS,IAAI,GAAG,IAAI,OAAO,OACjE;;AAEH,KAAI,eAAe,OACjB,YAAW,aAAa,OAAO,eAAe,WAAW,aAAaA,2BAAS,WAAW,GAAG,WAAW,OAAO;AAEjH,QAAO"}

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

@@ -1,12 +1,15 @@
 import { AssetFieldValue, Field, MultilinkFieldValue, PluginFieldValue, RichtextFieldValue, TableFieldValue } from "../generated/overlay/_internal.gen.cjs";
 import { BlockContent, BlockContentInput, BlocksFieldValue, FieldType, FieldValue, FieldValueInput } from "../generated/types/field.cjs";
 import { Prettify } from "../utils/prettify.cjs";
+import { BlockFolder } from "./define-folder.cjs";
 
 //#region src/helpers/define-field.d.ts
 /** A block reference for `allow`: a defined block object or its name. */
 type AllowRef = string | {
   name: string;
 };
+/** A folder reference for `allow`: a defined folder object (no string shorthand — bare strings are block names). */
+type FolderAllowRef = BlockFolder;
 /** A datasource reference for `datasource`: a defined datasource object or its slug. */
 type DatasourceRef = string | {
   slug: string;
@@ -17,15 +20,21 @@ type NameOf<T> = T extends string ? T : T extends {
 type SlugOf<T> = T extends string ? T : T extends {
   slug: infer S extends string;
 } ? S : never;
-/** Normalizes an `allow` input (ref, name, or array thereof) to a tuple of block-name strings. */
-type NormalizeAllow<T> = T extends readonly any[] ? { [I in keyof T]: NameOf<T[I]> } : readonly [NameOf<T>];
+/** Normalizes a single `allow` entry: folder refs to `{ folder: path }`, everything else to a name string. */
+type NormalizeAllowEntry<T> = T extends {
+  path: infer P extends string;
+} ? {
+  folder: P;
+} : NameOf<T>;
+/** Normalizes an `allow` input (ref, name, or array thereof) to a tuple of normalized entries. */
+type NormalizeAllow<T> = T extends readonly any[] ? { [I in keyof T]: NormalizeAllowEntry<T[I]> } : readonly [NormalizeAllowEntry<T>];
 /**
  * Field config accepted by {@link defineField}: the content-shape field plus the
  * DSL reference keys. `allow` replaces the wire `component_whitelist`; `datasource`
  * holds the datasource ref/slug (the wire `source` selector still passes through).
  */
 type FieldInput = Field & {
-  allow?: AllowRef | readonly AllowRef[];
+  allow?: AllowRef | FolderAllowRef | readonly (AllowRef | FolderAllowRef)[];
   datasource?: DatasourceRef;
   required?: boolean;
 };

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

@@ -1,12 +1,15 @@
 import { AssetFieldValue, Field, MultilinkFieldValue, PluginFieldValue, RichtextFieldValue, TableFieldValue } from "../generated/overlay/_internal.gen.mjs";
 import { BlockContent, BlockContentInput, BlocksFieldValue, FieldType, FieldValue, FieldValueInput } from "../generated/types/field.mjs";
 import { Prettify } from "../utils/prettify.mjs";
+import { BlockFolder } from "./define-folder.mjs";
 
 //#region src/helpers/define-field.d.ts
 /** A block reference for `allow`: a defined block object or its name. */
 type AllowRef = string | {
   name: string;
 };
+/** A folder reference for `allow`: a defined folder object (no string shorthand — bare strings are block names). */
+type FolderAllowRef = BlockFolder;
 /** A datasource reference for `datasource`: a defined datasource object or its slug. */
 type DatasourceRef = string | {
   slug: string;
@@ -17,15 +20,21 @@ type NameOf<T> = T extends string ? T : T extends {
 type SlugOf<T> = T extends string ? T : T extends {
   slug: infer S extends string;
 } ? S : never;
-/** Normalizes an `allow` input (ref, name, or array thereof) to a tuple of block-name strings. */
-type NormalizeAllow<T> = T extends readonly any[] ? { [I in keyof T]: NameOf<T[I]> } : readonly [NameOf<T>];
+/** Normalizes a single `allow` entry: folder refs to `{ folder: path }`, everything else to a name string. */
+type NormalizeAllowEntry<T> = T extends {
+  path: infer P extends string;
+} ? {
+  folder: P;
+} : NameOf<T>;
+/** Normalizes an `allow` input (ref, name, or array thereof) to a tuple of normalized entries. */
+type NormalizeAllow<T> = T extends readonly any[] ? { [I in keyof T]: NormalizeAllowEntry<T[I]> } : readonly [NormalizeAllowEntry<T>];
 /**
  * Field config accepted by {@link defineField}: the content-shape field plus the
  * DSL reference keys. `allow` replaces the wire `component_whitelist`; `datasource`
  * holds the datasource ref/slug (the wire `source` selector still passes through).
  */
 type FieldInput = Field & {
-  allow?: AllowRef | readonly AllowRef[];
+  allow?: AllowRef | FolderAllowRef | readonly (AllowRef | FolderAllowRef)[];
   datasource?: DatasourceRef;
   required?: boolean;
 };

package/dist/helpers/define-field.mjs

@@ -1,13 +1,20 @@
 import { isRecord } from "../utils/is-record.mjs";
 
 //#region src/helpers/define-field.ts
+/** Type guard for a defined folder ref: has `path`, and never `fields` (defined block) or `slug` (datasource). */
+const isFolderRef = (ref) => isRecord(ref) && typeof ref.path === "string" && !Array.isArray(ref.fields) && !("slug" in ref);
 function defineField(name, field) {
 	const { allow, datasource, ...rest } = field;
 	const normalized = {
 		...rest,
 		name
 	};
-	if (allow !== void 0) normalized.allow = (Array.isArray(allow) ? allow : [allow]).map((ref) => typeof ref === "string" ? ref : isRecord(ref) ? ref.name : void 0);
+	if (allow !== void 0) {
+		const refs = Array.isArray(allow) ? allow : [allow];
+		const folderRefs = refs.filter(isFolderRef);
+		if (folderRefs.length > 0 && folderRefs.length < refs.length) throw new Error(`defineField: "allow" on field "${name}" mixes block and folder references; the editor restricts by either blocks or folders, not both`);
+		normalized.allow = refs.map((ref) => isFolderRef(ref) ? { folder: ref.path } : typeof ref === "string" ? ref : isRecord(ref) ? ref.name : void 0);
+	}
 	if (datasource !== void 0) normalized.datasource = typeof datasource === "string" ? datasource : isRecord(datasource) ? datasource.slug : void 0;
 	return normalized;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"define-field.mjs","names":[],"sources":["../../src/helpers/define-field.ts"],"sourcesContent":["import type {\n  AssetFieldValue,\n  BlockContent,\n  BlockContentInput,\n  BlocksFieldValue,\n  Field,\n  FieldType,\n  FieldValue,\n  FieldValueInput,\n  MultilinkFieldValue,\n  PluginFieldValue,\n  RichtextFieldValue,\n  TableFieldValue,\n} from '../generated/types/field';\nimport type { Prettify } from '../utils/prettify';\nimport { isRecord } from '../utils/is-record';\n\nexport type {\n  AssetFieldValue,\n  BlockContent,\n  BlockContentInput,\n  BlocksFieldValue,\n  Field,\n  FieldType,\n  FieldValue,\n  FieldValueInput,\n  MultilinkFieldValue,\n  PluginFieldValue,\n  RichtextFieldValue,\n  TableFieldValue,\n};\n\n/** A block reference for `allow`: a defined block object or its name. */\ntype AllowRef = string | { name: string };\n/** A datasource reference for `datasource`: a defined datasource object or its slug. */\ntype DatasourceRef = string | { slug: string };\n\ntype NameOf<T> = T extends string ? T : T extends { name: infer N extends string } ? N : never;\ntype SlugOf<T> = T extends string ? T : T extends { slug: infer S extends string } ? S : never;\n\n/** Normalizes an `allow` input (ref, name, or array thereof) to a tuple of block-name strings. */\ntype NormalizeAllow<T> = T extends readonly any[]\n  ? { [I in keyof T]: NameOf<T[I]> }\n  : readonly [NameOf<T>];\n\n/**\n * Field config accepted by {@link defineField}: the content-shape field plus the\n * DSL reference keys. `allow` replaces the wire `component_whitelist`; `datasource`\n * holds the datasource ref/slug (the wire `source` selector still passes through).\n */\nexport type FieldInput = Field & {\n  allow?: AllowRef | readonly AllowRef[];\n  datasource?: DatasourceRef;\n  required?: boolean;\n};\n\n/** Result of {@link defineField}: the field stamped with `name`, with refs normalized to strings. */\nexport type DefinedField<TName extends string, TField extends FieldInput> = Prettify<\n  Omit<TField, 'allow' | 'datasource' | 'name'>\n  & { name: TName }\n  & (TField extends { allow: infer A } ? { allow: NormalizeAllow<A> } : unknown)\n  & (TField extends { datasource: infer D } ? { datasource: SlugOf<D> } : unknown)\n>;\n\n/**\n * Returns a {@link Field} stamped with the given `name`, normalizing reference\n * keys to strings so everything downstream sees plain names/slugs. A thin,\n * strongly-typed identity helper — it does not validate or throw.\n *\n * Use inside a {@link defineBlock} `fields` array — `pos` is injected from the\n * array index by `defineBlock`.\n *\n * @example\n * defineField('headline', { type: 'text', max_length: 100, required: true });\n * defineField('body', { type: 'bloks', allow: [heroBlock, 'teaser'] });\n * defineField('theme', { type: 'option', source: 'internal', datasource: colors });\n */\nexport function defineField<\n  const TName extends string,\n  const TField extends FieldInput,\n>(name: TName, field: TField): DefinedField<TName, TField>;\nexport function defineField(name: string, field: Record<string, unknown>): Record<string, unknown> {\n  const { allow, datasource, ...rest } = field;\n  const normalized: Record<string, unknown> = { ...rest, name };\n  if (allow !== undefined) {\n    const refs = Array.isArray(allow) ? allow : [allow];\n    normalized.allow = refs.map(ref => (typeof ref === 'string' ? ref : isRecord(ref) ? ref.name : undefined));\n  }\n  if (datasource !== undefined) {\n    normalized.datasource = typeof datasource === 'string' ? datasource : isRecord(datasource) ? datasource.slug : undefined;\n  }\n  return normalized;\n}\n"],"mappings":";;;AAiFA,SAAgB,YAAY,MAAc,OAAyD;CACjG,MAAM,EAAE,OAAO,YAAY,GAAG,SAAS;CACvC,MAAM,aAAsC;EAAE,GAAG;EAAM;EAAM;AAC7D,KAAI,UAAU,OAEZ,YAAW,SADE,MAAM,QAAQ,MAAM,GAAG,QAAQ,CAAC,MAAM,EAC3B,KAAI,QAAQ,OAAO,QAAQ,WAAW,MAAM,SAAS,IAAI,GAAG,IAAI,OAAO,OAAW;AAE5G,KAAI,eAAe,OACjB,YAAW,aAAa,OAAO,eAAe,WAAW,aAAa,SAAS,WAAW,GAAG,WAAW,OAAO;AAEjH,QAAO"}
+{"version":3,"file":"define-field.mjs","names":[],"sources":["../../src/helpers/define-field.ts"],"sourcesContent":["import type {\n  AssetFieldValue,\n  BlockContent,\n  BlockContentInput,\n  BlocksFieldValue,\n  Field,\n  FieldType,\n  FieldValue,\n  FieldValueInput,\n  MultilinkFieldValue,\n  PluginFieldValue,\n  RichtextFieldValue,\n  TableFieldValue,\n} from '../generated/types/field';\nimport type { BlockFolder } from './define-folder';\nimport type { Prettify } from '../utils/prettify';\nimport { isRecord } from '../utils/is-record';\n\nexport type {\n  AssetFieldValue,\n  BlockContent,\n  BlockContentInput,\n  BlocksFieldValue,\n  Field,\n  FieldType,\n  FieldValue,\n  FieldValueInput,\n  MultilinkFieldValue,\n  PluginFieldValue,\n  RichtextFieldValue,\n  TableFieldValue,\n};\n\n/** A block reference for `allow`: a defined block object or its name. */\ntype AllowRef = string | { name: string };\n/** A folder reference for `allow`: a defined folder object (no string shorthand — bare strings are block names). */\ntype FolderAllowRef = BlockFolder;\n/** A datasource reference for `datasource`: a defined datasource object or its slug. */\ntype DatasourceRef = string | { slug: string };\n\ntype NameOf<T> = T extends string ? T : T extends { name: infer N extends string } ? N : never;\ntype SlugOf<T> = T extends string ? T : T extends { slug: infer S extends string } ? S : never;\n\n/** Normalizes a single `allow` entry: folder refs to `{ folder: path }`, everything else to a name string. */\ntype NormalizeAllowEntry<T> = T extends { path: infer P extends string }\n  ? { folder: P }\n  : NameOf<T>;\n/** Normalizes an `allow` input (ref, name, or array thereof) to a tuple of normalized entries. */\ntype NormalizeAllow<T> = T extends readonly any[]\n  ? { [I in keyof T]: NormalizeAllowEntry<T[I]> }\n  : readonly [NormalizeAllowEntry<T>];\n\n/** Type guard for a defined folder ref: has `path`, and never `fields` (defined block) or `slug` (datasource). */\nconst isFolderRef = (ref: unknown): ref is BlockFolder =>\n  isRecord(ref) && typeof ref.path === 'string' && !Array.isArray(ref.fields) && !('slug' in ref);\n\n/**\n * Field config accepted by {@link defineField}: the content-shape field plus the\n * DSL reference keys. `allow` replaces the wire `component_whitelist`; `datasource`\n * holds the datasource ref/slug (the wire `source` selector still passes through).\n */\nexport type FieldInput = Field & {\n  allow?: AllowRef | FolderAllowRef | readonly (AllowRef | FolderAllowRef)[];\n  datasource?: DatasourceRef;\n  required?: boolean;\n};\n\n/** Result of {@link defineField}: the field stamped with `name`, with refs normalized to strings. */\nexport type DefinedField<TName extends string, TField extends FieldInput> = Prettify<\n  Omit<TField, 'allow' | 'datasource' | 'name'>\n  & { name: TName }\n  & (TField extends { allow: infer A } ? { allow: NormalizeAllow<A> } : unknown)\n  & (TField extends { datasource: infer D } ? { datasource: SlugOf<D> } : unknown)\n>;\n\n/**\n * Returns a {@link Field} stamped with the given `name`, normalizing reference\n * keys to strings so everything downstream sees plain names/slugs. A thin,\n * strongly-typed identity helper — it does not validate or throw.\n *\n * Use inside a {@link defineBlock} `fields` array — `pos` is injected from the\n * array index by `defineBlock`.\n *\n * @example\n * defineField('headline', { type: 'text', max_length: 100, required: true });\n * defineField('body', { type: 'bloks', allow: [heroBlock, 'teaser'] });\n * defineField('theme', { type: 'option', source: 'internal', datasource: colors });\n */\nexport function defineField<\n  const TName extends string,\n  const TField extends FieldInput,\n>(name: TName, field: TField): DefinedField<TName, TField>;\nexport function defineField(name: string, field: Record<string, unknown>): Record<string, unknown> {\n  const { allow, datasource, ...rest } = field;\n  const normalized: Record<string, unknown> = { ...rest, name };\n  if (allow !== undefined) {\n    const refs = Array.isArray(allow) ? allow : [allow];\n    const folderRefs = refs.filter(isFolderRef);\n    if (folderRefs.length > 0 && folderRefs.length < refs.length) {\n      throw new Error(`defineField: \"allow\" on field \"${name}\" mixes block and folder references; the editor restricts by either blocks or folders, not both`);\n    }\n    normalized.allow = refs.map(ref =>\n      isFolderRef(ref)\n        ? { folder: ref.path }\n        : (typeof ref === 'string' ? ref : isRecord(ref) ? ref.name : undefined),\n    );\n  }\n  if (datasource !== undefined) {\n    normalized.datasource = typeof datasource === 'string' ? datasource : isRecord(datasource) ? datasource.slug : undefined;\n  }\n  return normalized;\n}\n"],"mappings":";;;;AAqDA,MAAM,eAAe,QACnB,SAAS,IAAI,IAAI,OAAO,IAAI,SAAS,YAAY,CAAC,MAAM,QAAQ,IAAI,OAAO,IAAI,EAAE,UAAU;AAsC7F,SAAgB,YAAY,MAAc,OAAyD;CACjG,MAAM,EAAE,OAAO,YAAY,GAAG,SAAS;CACvC,MAAM,aAAsC;EAAE,GAAG;EAAM;EAAM;AAC7D,KAAI,UAAU,QAAW;EACvB,MAAM,OAAO,MAAM,QAAQ,MAAM,GAAG,QAAQ,CAAC,MAAM;EACnD,MAAM,aAAa,KAAK,OAAO,YAAY;AAC3C,MAAI,WAAW,SAAS,KAAK,WAAW,SAAS,KAAK,OACpD,OAAM,IAAI,MAAM,kCAAkC,KAAK,iGAAiG;AAE1J,aAAW,QAAQ,KAAK,KAAI,QAC1B,YAAY,IAAI,GACZ,EAAE,QAAQ,IAAI,MAAM,GACnB,OAAO,QAAQ,WAAW,MAAM,SAAS,IAAI,GAAG,IAAI,OAAO,OACjE;;AAEH,KAAI,eAAe,OACjB,YAAW,aAAa,OAAO,eAAe,WAAW,aAAa,SAAS,WAAW,GAAG,WAAW,OAAO;AAEjH,QAAO"}

package/dist/helpers/define-folder.cjs

@@ -0,0 +1,19 @@
+
+//#region src/helpers/define-folder.ts
+function defineFolder(input) {
+	if (input.name.trim() === "") throw new Error(`defineFolder: folder name must not be empty`);
+	if (input.name.includes("/")) throw new Error(`defineFolder: folder name "${input.name}" must not contain "/"`);
+	const path = input.parent ? `${input.parent.path}/${input.name}` : input.name;
+	return input.parent ? {
+		name: input.name,
+		parent: input.parent,
+		path
+	} : {
+		name: input.name,
+		path
+	};
+}
+
+//#endregion
+exports.defineFolder = defineFolder;
+//# sourceMappingURL=define-folder.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define-folder.cjs","names":[],"sources":["../../src/helpers/define-folder.ts"],"sourcesContent":["import type { Prettify } from '../utils/prettify';\n\n/**\n * A block folder (Storyblok component group) content-shape definition. Identity\n * is the resolved name path — no UUID; the CLI matches/creates groups by path\n * at push time.\n */\nexport interface BlockFolder {\n  name: string;\n  parent?: BlockFolder;\n  path: string;\n}\n\ntype FolderPath<TName extends string, TParent extends BlockFolder | undefined>\n  = TParent extends { path: infer P extends string } ? `${P}/${TName}` : TName;\n\ntype DefinedFolder<TName extends string, TParent extends BlockFolder | undefined> = Prettify<\n  { name: TName; path: FolderPath<TName, TParent> }\n  & (TParent extends BlockFolder ? { parent: TParent } : unknown)\n>;\n\n/**\n * Returns a {@link BlockFolder} definition. `path` is computed eagerly from the\n * `parent` chain (display names joined with `/`). Throws only on `/` in the\n * name (a programming error — it would corrupt path semantics).\n *\n * @example\n * const layout = defineFolder({ name: 'Layout' });\n * const heros = defineFolder({ name: 'Heros', parent: layout });\n * // heros.path === 'Layout/Heros'\n */\nexport function defineFolder<\n  const TName extends string,\n  const TParent extends BlockFolder | undefined = undefined,\n>(input: { name: TName; parent?: TParent }): DefinedFolder<TName, TParent>;\nexport function defineFolder(input: { name: string; parent?: BlockFolder }): BlockFolder {\n  if (input.name.trim() === '') {\n    throw new Error(`defineFolder: folder name must not be empty`);\n  }\n  if (input.name.includes('/')) {\n    throw new Error(`defineFolder: folder name \"${input.name}\" must not contain \"/\"`);\n  }\n  const path = input.parent ? `${input.parent.path}/${input.name}` : input.name;\n  return input.parent\n    ? { name: input.name, parent: input.parent, path }\n    : { name: input.name, path };\n}\n"],"mappings":";;AAmCA,SAAgB,aAAa,OAA4D;AACvF,KAAI,MAAM,KAAK,MAAM,KAAK,GACxB,OAAM,IAAI,MAAM,8CAA8C;AAEhE,KAAI,MAAM,KAAK,SAAS,IAAI,CAC1B,OAAM,IAAI,MAAM,8BAA8B,MAAM,KAAK,wBAAwB;CAEnF,MAAM,OAAO,MAAM,SAAS,GAAG,MAAM,OAAO,KAAK,GAAG,MAAM,SAAS,MAAM;AACzE,QAAO,MAAM,SACT;EAAE,MAAM,MAAM;EAAM,QAAQ,MAAM;EAAQ;EAAM,GAChD;EAAE,MAAM,MAAM;EAAM;EAAM"}

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

@@ -0,0 +1,39 @@
+import { Prettify } from "../utils/prettify.cjs";
+
+//#region src/helpers/define-folder.d.ts
+/**
+ * A block folder (Storyblok component group) content-shape definition. Identity
+ * is the resolved name path — no UUID; the CLI matches/creates groups by path
+ * at push time.
+ */
+interface BlockFolder {
+  name: string;
+  parent?: BlockFolder;
+  path: string;
+}
+type FolderPath<TName extends string, TParent extends BlockFolder | undefined> = TParent extends {
+  path: infer P extends string;
+} ? `${P}/${TName}` : TName;
+type DefinedFolder<TName extends string, TParent extends BlockFolder | undefined> = Prettify<{
+  name: TName;
+  path: FolderPath<TName, TParent>;
+} & (TParent extends BlockFolder ? {
+  parent: TParent;
+} : unknown)>;
+/**
+ * Returns a {@link BlockFolder} definition. `path` is computed eagerly from the
+ * `parent` chain (display names joined with `/`). Throws only on `/` in the
+ * name (a programming error — it would corrupt path semantics).
+ *
+ * @example
+ * const layout = defineFolder({ name: 'Layout' });
+ * const heros = defineFolder({ name: 'Heros', parent: layout });
+ * // heros.path === 'Layout/Heros'
+ */
+declare function defineFolder<const TName extends string, const TParent extends BlockFolder | undefined = undefined>(input: {
+  name: TName;
+  parent?: TParent;
+}): DefinedFolder<TName, TParent>;
+//#endregion
+export { BlockFolder, defineFolder };
+//# sourceMappingURL=define-folder.d.cts.map

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

@@ -0,0 +1,39 @@
+import { Prettify } from "../utils/prettify.mjs";
+
+//#region src/helpers/define-folder.d.ts
+/**
+ * A block folder (Storyblok component group) content-shape definition. Identity
+ * is the resolved name path — no UUID; the CLI matches/creates groups by path
+ * at push time.
+ */
+interface BlockFolder {
+  name: string;
+  parent?: BlockFolder;
+  path: string;
+}
+type FolderPath<TName extends string, TParent extends BlockFolder | undefined> = TParent extends {
+  path: infer P extends string;
+} ? `${P}/${TName}` : TName;
+type DefinedFolder<TName extends string, TParent extends BlockFolder | undefined> = Prettify<{
+  name: TName;
+  path: FolderPath<TName, TParent>;
+} & (TParent extends BlockFolder ? {
+  parent: TParent;
+} : unknown)>;
+/**
+ * Returns a {@link BlockFolder} definition. `path` is computed eagerly from the
+ * `parent` chain (display names joined with `/`). Throws only on `/` in the
+ * name (a programming error — it would corrupt path semantics).
+ *
+ * @example
+ * const layout = defineFolder({ name: 'Layout' });
+ * const heros = defineFolder({ name: 'Heros', parent: layout });
+ * // heros.path === 'Layout/Heros'
+ */
+declare function defineFolder<const TName extends string, const TParent extends BlockFolder | undefined = undefined>(input: {
+  name: TName;
+  parent?: TParent;
+}): DefinedFolder<TName, TParent>;
+//#endregion
+export { BlockFolder, defineFolder };
+//# sourceMappingURL=define-folder.d.mts.map

package/dist/helpers/define-folder.mjs

@@ -0,0 +1,18 @@
+//#region src/helpers/define-folder.ts
+function defineFolder(input) {
+	if (input.name.trim() === "") throw new Error(`defineFolder: folder name must not be empty`);
+	if (input.name.includes("/")) throw new Error(`defineFolder: folder name "${input.name}" must not contain "/"`);
+	const path = input.parent ? `${input.parent.path}/${input.name}` : input.name;
+	return input.parent ? {
+		name: input.name,
+		parent: input.parent,
+		path
+	} : {
+		name: input.name,
+		path
+	};
+}
+
+//#endregion
+export { defineFolder };
+//# sourceMappingURL=define-folder.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define-folder.mjs","names":[],"sources":["../../src/helpers/define-folder.ts"],"sourcesContent":["import type { Prettify } from '../utils/prettify';\n\n/**\n * A block folder (Storyblok component group) content-shape definition. Identity\n * is the resolved name path — no UUID; the CLI matches/creates groups by path\n * at push time.\n */\nexport interface BlockFolder {\n  name: string;\n  parent?: BlockFolder;\n  path: string;\n}\n\ntype FolderPath<TName extends string, TParent extends BlockFolder | undefined>\n  = TParent extends { path: infer P extends string } ? `${P}/${TName}` : TName;\n\ntype DefinedFolder<TName extends string, TParent extends BlockFolder | undefined> = Prettify<\n  { name: TName; path: FolderPath<TName, TParent> }\n  & (TParent extends BlockFolder ? { parent: TParent } : unknown)\n>;\n\n/**\n * Returns a {@link BlockFolder} definition. `path` is computed eagerly from the\n * `parent` chain (display names joined with `/`). Throws only on `/` in the\n * name (a programming error — it would corrupt path semantics).\n *\n * @example\n * const layout = defineFolder({ name: 'Layout' });\n * const heros = defineFolder({ name: 'Heros', parent: layout });\n * // heros.path === 'Layout/Heros'\n */\nexport function defineFolder<\n  const TName extends string,\n  const TParent extends BlockFolder | undefined = undefined,\n>(input: { name: TName; parent?: TParent }): DefinedFolder<TName, TParent>;\nexport function defineFolder(input: { name: string; parent?: BlockFolder }): BlockFolder {\n  if (input.name.trim() === '') {\n    throw new Error(`defineFolder: folder name must not be empty`);\n  }\n  if (input.name.includes('/')) {\n    throw new Error(`defineFolder: folder name \"${input.name}\" must not contain \"/\"`);\n  }\n  const path = input.parent ? `${input.parent.path}/${input.name}` : input.name;\n  return input.parent\n    ? { name: input.name, parent: input.parent, path }\n    : { name: input.name, path };\n}\n"],"mappings":";AAmCA,SAAgB,aAAa,OAA4D;AACvF,KAAI,MAAM,KAAK,MAAM,KAAK,GACxB,OAAM,IAAI,MAAM,8CAA8C;AAEhE,KAAI,MAAM,KAAK,SAAS,IAAI,CAC1B,OAAM,IAAI,MAAM,8BAA8B,MAAM,KAAK,wBAAwB;CAEnF,MAAM,OAAO,MAAM,SAAS,GAAG,MAAM,OAAO,KAAK,GAAG,MAAM,SAAS,MAAM;AACzE,QAAO,MAAM,SACT;EAAE,MAAM,MAAM;EAAM,QAAQ,MAAM;EAAQ;EAAM,GAChD;EAAE,MAAM,MAAM;EAAM;EAAM"}

package/dist/helpers/define-schema.cjs

@@ -0,0 +1,23 @@
+
+//#region src/helpers/define-schema.ts
+/**
+* Typed identity wrapper for a schema object, consistent with the other
+* `define*` helpers. Preserves the exact literal shape via `const` inference so
+* {@link Schema} can derive block, datasource, and field-plugin types from
+* `typeof schema`. Does not validate or transform.
+*
+* @example
+* export const schema = defineSchema({
+*   blocks: { pageBlock, heroBlock },
+*   folders: { layout },
+*   datasources: { colorsDatasource },
+*   fieldPlugins: { colorPicker },
+* });
+*/
+function defineSchema(schema) {
+	return schema;
+}
+
+//#endregion
+exports.defineSchema = defineSchema;
+//# sourceMappingURL=define-schema.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define-schema.cjs","names":[],"sources":["../../src/helpers/define-schema.ts"],"sourcesContent":["import type { Block } from './define-block';\nimport type { Datasource } from './define-datasource';\nimport type { BlockFolder } from './define-folder';\nimport type { FieldPlugin } from './define-field-plugin';\n\n/** Minimal shape accepted by {@link defineSchema}; extra keys pass through unchanged. */\nexport interface SchemaConfig {\n  blocks: Record<string, Block>;\n  folders?: Record<string, BlockFolder>;\n  datasources?: Record<string, Datasource>;\n  fieldPlugins?: Record<string, FieldPlugin>;\n}\n\n/**\n * Typed identity wrapper for a schema object, consistent with the other\n * `define*` helpers. Preserves the exact literal shape via `const` inference so\n * {@link Schema} can derive block, datasource, and field-plugin types from\n * `typeof schema`. Does not validate or transform.\n *\n * @example\n * export const schema = defineSchema({\n *   blocks: { pageBlock, heroBlock },\n *   folders: { layout },\n *   datasources: { colorsDatasource },\n *   fieldPlugins: { colorPicker },\n * });\n */\nexport function defineSchema<const T extends SchemaConfig>(schema: T): T {\n  return schema;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA2BA,SAAgB,aAA2C,QAAc;AACvE,QAAO"}

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

@@ -0,0 +1,31 @@
+import { Block } from "../generated/types/block.cjs";
+import { BlockFolder } from "./define-folder.cjs";
+import { Datasource } from "./define-datasource.cjs";
+import { FieldPlugin } from "./define-field-plugin.cjs";
+
+//#region src/helpers/define-schema.d.ts
+/** Minimal shape accepted by {@link defineSchema}; extra keys pass through unchanged. */
+interface SchemaConfig {
+  blocks: Record<string, Block>;
+  folders?: Record<string, BlockFolder>;
+  datasources?: Record<string, Datasource>;
+  fieldPlugins?: Record<string, FieldPlugin>;
+}
+/**
+ * Typed identity wrapper for a schema object, consistent with the other
+ * `define*` helpers. Preserves the exact literal shape via `const` inference so
+ * {@link Schema} can derive block, datasource, and field-plugin types from
+ * `typeof schema`. Does not validate or transform.
+ *
+ * @example
+ * export const schema = defineSchema({
+ *   blocks: { pageBlock, heroBlock },
+ *   folders: { layout },
+ *   datasources: { colorsDatasource },
+ *   fieldPlugins: { colorPicker },
+ * });
+ */
+declare function defineSchema<const T extends SchemaConfig>(schema: T): T;
+//#endregion
+export { SchemaConfig, defineSchema };
+//# sourceMappingURL=define-schema.d.cts.map

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

@@ -0,0 +1,31 @@
+import { Block } from "../generated/types/block.mjs";
+import { BlockFolder } from "./define-folder.mjs";
+import { Datasource } from "./define-datasource.mjs";
+import { FieldPlugin } from "./define-field-plugin.mjs";
+
+//#region src/helpers/define-schema.d.ts
+/** Minimal shape accepted by {@link defineSchema}; extra keys pass through unchanged. */
+interface SchemaConfig {
+  blocks: Record<string, Block>;
+  folders?: Record<string, BlockFolder>;
+  datasources?: Record<string, Datasource>;
+  fieldPlugins?: Record<string, FieldPlugin>;
+}
+/**
+ * Typed identity wrapper for a schema object, consistent with the other
+ * `define*` helpers. Preserves the exact literal shape via `const` inference so
+ * {@link Schema} can derive block, datasource, and field-plugin types from
+ * `typeof schema`. Does not validate or transform.
+ *
+ * @example
+ * export const schema = defineSchema({
+ *   blocks: { pageBlock, heroBlock },
+ *   folders: { layout },
+ *   datasources: { colorsDatasource },
+ *   fieldPlugins: { colorPicker },
+ * });
+ */
+declare function defineSchema<const T extends SchemaConfig>(schema: T): T;
+//#endregion
+export { SchemaConfig, defineSchema };
+//# sourceMappingURL=define-schema.d.mts.map

package/dist/helpers/define-schema.mjs

@@ -0,0 +1,22 @@
+//#region src/helpers/define-schema.ts
+/**
+* Typed identity wrapper for a schema object, consistent with the other
+* `define*` helpers. Preserves the exact literal shape via `const` inference so
+* {@link Schema} can derive block, datasource, and field-plugin types from
+* `typeof schema`. Does not validate or transform.
+*
+* @example
+* export const schema = defineSchema({
+*   blocks: { pageBlock, heroBlock },
+*   folders: { layout },
+*   datasources: { colorsDatasource },
+*   fieldPlugins: { colorPicker },
+* });
+*/
+function defineSchema(schema) {
+	return schema;
+}
+
+//#endregion
+export { defineSchema };
+//# sourceMappingURL=define-schema.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define-schema.mjs","names":[],"sources":["../../src/helpers/define-schema.ts"],"sourcesContent":["import type { Block } from './define-block';\nimport type { Datasource } from './define-datasource';\nimport type { BlockFolder } from './define-folder';\nimport type { FieldPlugin } from './define-field-plugin';\n\n/** Minimal shape accepted by {@link defineSchema}; extra keys pass through unchanged. */\nexport interface SchemaConfig {\n  blocks: Record<string, Block>;\n  folders?: Record<string, BlockFolder>;\n  datasources?: Record<string, Datasource>;\n  fieldPlugins?: Record<string, FieldPlugin>;\n}\n\n/**\n * Typed identity wrapper for a schema object, consistent with the other\n * `define*` helpers. Preserves the exact literal shape via `const` inference so\n * {@link Schema} can derive block, datasource, and field-plugin types from\n * `typeof schema`. Does not validate or transform.\n *\n * @example\n * export const schema = defineSchema({\n *   blocks: { pageBlock, heroBlock },\n *   folders: { layout },\n *   datasources: { colorsDatasource },\n *   fieldPlugins: { colorPicker },\n * });\n */\nexport function defineSchema<const T extends SchemaConfig>(schema: T): T {\n  return schema;\n}\n"],"mappings":";;;;;;;;;;;;;;;AA2BA,SAAgB,aAA2C,QAAc;AACvE,QAAO"}