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

package/dist/generated/types/block.d.cts

@@ -34,6 +34,12 @@ type Block<TName extends string = string, TFields extends BlockFields = BlockFie
    * directory layout.
    */
   component_group_uuid?: string | null;
+  /**
+   * Folder membership as a display name path (e.g. `'Layout/Heros'`); `null` =
+   * explicitly ungrouped (push clears the group). Absent = unmanaged (push
+   * leaves the remote group untouched).
+   */
+  folder?: string | null;
 }>;
 /**
  * A root {@link Block} (`is_root: true`). Given a union of blocks, narrows to

package/dist/generated/types/block.d.mts

@@ -34,6 +34,12 @@ type Block<TName extends string = string, TFields extends BlockFields = BlockFie
    * directory layout.
    */
   component_group_uuid?: string | null;
+  /**
+   * Folder membership as a display name path (e.g. `'Layout/Heros'`); `null` =
+   * explicitly ungrouped (push clears the group). Absent = unmanaged (push
+   * leaves the remote group untouched).
+   */
+  folder?: string | null;
 }>;
 /**
  * A root {@link Block} (`is_root: true`). Given a union of blocks, narrows to

package/dist/generated/types/field.d.cts

@@ -71,11 +71,30 @@ type IsNestable<T> = T extends {
 } ? false : T extends {
   is_nestable: true;
 } ? true : true;
+type AllowEntry = string | {
+  folder: string;
+};
+/**
+ * Keeps `TBlock` when its `folder` is `TFolder` or any nested subfolder (mirrors
+ * the editor's `isAnywhereInFolder`). This is a best-effort compile-time check,
+ * compared case-insensitively via `Lowercase` so `folder: 'blog'` and a `Blog`
+ * folder ref narrow the same. TypeScript cannot replicate the CLI's full slug at
+ * the type level, so separator/symbol drift (`'My Layout'` vs `'my-layout'`) is
+ * only reconciled at push/validate time — full folder identity is enforced
+ * there, not here. To rely on narrowing, prefer a `defineFolder` ref over a
+ * string path on both the block's `folder` and the field's `allow`: a shared ref
+ * carries the exact path on both sides, so no drift is possible.
+ */
+type MatchesFolder<TBlock, TFolder extends string> = TBlock extends {
+  folder: infer BF extends string;
+} ? Lowercase<BF> extends Lowercase<TFolder> | `${Lowercase<TFolder>}/${string}` ? TBlock : never : never;
 type ApplyAllow<TField, TBlocks> = TField extends {
-  allow: ReadonlyArray<infer TAllowed extends string>;
-} ? Extract<TBlocks, {
+  allow: ReadonlyArray<infer TAllowed extends AllowEntry>;
+} ? TAllowed extends string ? Extract<TBlocks, {
   name: TAllowed;
-}> : TBlocks extends any ? IsNestable<TBlocks> extends true ? TBlocks : never : never;
+}> : TAllowed extends {
+  folder: infer F extends string;
+} ? TBlocks extends any ? MatchesFolder<TBlocks, F> : never : never : TBlocks extends any ? IsNestable<TBlocks> extends true ? TBlocks : never : never;
 /**
  * Resolves a `custom` field to its registered plugin value. When the field's
  * `field_type` is a key of `TFieldPlugins`, the validator output is merged with

package/dist/generated/types/field.d.mts

@@ -71,11 +71,30 @@ type IsNestable<T> = T extends {
 } ? false : T extends {
   is_nestable: true;
 } ? true : true;
+type AllowEntry = string | {
+  folder: string;
+};
+/**
+ * Keeps `TBlock` when its `folder` is `TFolder` or any nested subfolder (mirrors
+ * the editor's `isAnywhereInFolder`). This is a best-effort compile-time check,
+ * compared case-insensitively via `Lowercase` so `folder: 'blog'` and a `Blog`
+ * folder ref narrow the same. TypeScript cannot replicate the CLI's full slug at
+ * the type level, so separator/symbol drift (`'My Layout'` vs `'my-layout'`) is
+ * only reconciled at push/validate time — full folder identity is enforced
+ * there, not here. To rely on narrowing, prefer a `defineFolder` ref over a
+ * string path on both the block's `folder` and the field's `allow`: a shared ref
+ * carries the exact path on both sides, so no drift is possible.
+ */
+type MatchesFolder<TBlock, TFolder extends string> = TBlock extends {
+  folder: infer BF extends string;
+} ? Lowercase<BF> extends Lowercase<TFolder> | `${Lowercase<TFolder>}/${string}` ? TBlock : never : never;
 type ApplyAllow<TField, TBlocks> = TField extends {
-  allow: ReadonlyArray<infer TAllowed extends string>;
-} ? Extract<TBlocks, {
+  allow: ReadonlyArray<infer TAllowed extends AllowEntry>;
+} ? TAllowed extends string ? Extract<TBlocks, {
   name: TAllowed;
-}> : TBlocks extends any ? IsNestable<TBlocks> extends true ? TBlocks : never : never;
+}> : TAllowed extends {
+  folder: infer F extends string;
+} ? TBlocks extends any ? MatchesFolder<TBlocks, F> : never : never : TBlocks extends any ? IsNestable<TBlocks> extends true ? TBlocks : never : never;
 /**
  * Resolves a `custom` field to its registered plugin value. When the field's
  * `field_type` is a key of `TFieldPlugins`, the validator output is merged with

package/dist/helpers/define-block.cjs

@@ -21,9 +21,14 @@ function defineBlock(block) {
 			pos: index
 		};
 	});
+	const { folder, ...restBlock } = block ?? {};
+	if (folder !== void 0 && typeof restBlock.component_group_uuid === "string") throw new Error(`defineBlock: block "${block?.name ?? ""}" sets both "folder" and "component_group_uuid"; use one`);
+	if (typeof folder === "string" && !folder.split("/").some((segment) => segment.trim() !== "")) throw new Error(`defineBlock: block "${block?.name ?? ""}" has an empty "folder" path`);
+	const normalizedFolder = folder === void 0 ? void 0 : folder !== null && typeof folder === "object" ? folder.path : folder;
 	return {
 		...BLOCK_DEFAULTS,
-		...block,
+		...restBlock,
+		...folder !== void 0 && { folder: normalizedFolder },
 		fields
 	};
 }

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

@@ -1 +1 @@
-{"version":3,"file":"define-block.cjs","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.cjs","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-block.d.cts

@@ -1,5 +1,6 @@
 import { Block, BlockFields, NestableBlock, RootBlock } from "../generated/types/block.cjs";
 import { Prettify } from "../utils/prettify.cjs";
+import { BlockFolder } from "./define-folder.cjs";
 
 //#region src/helpers/define-block.d.ts
 declare const BLOCK_DEFAULTS: {
@@ -11,18 +12,27 @@ declare const BLOCK_DEFAULTS: {
 };
 /** Fields that have safe defaults and may be omitted from block input. */
 type BlockOptional = keyof typeof BLOCK_DEFAULTS;
-type BlockInput<TName extends string = string, TFields extends BlockFields = BlockFields, TIsRoot extends boolean = false, TIsNestable extends boolean = true> = Prettify<Omit<Block, 'name' | 'fields' | 'is_root' | 'is_nestable' | BlockOptional> & {
+/** Accepted input for a block's `folder`: a folder ref, a raw path string, or `null` to explicitly ungroup. */
+type FolderInput = BlockFolder | string | null;
+/** Normalizes a folder input type to the display path literal it resolves to. */
+type NormalizeFolder<T> = T extends {
+  path: infer P extends string;
+} ? P : T;
+type BlockInput<TName extends string = string, TFields extends BlockFields = BlockFields, TIsRoot extends boolean = false, TIsNestable extends boolean = true, TFolder extends FolderInput | undefined = undefined> = Prettify<Omit<Block, 'name' | 'fields' | 'is_root' | 'is_nestable' | 'folder' | BlockOptional> & {
   name: TName;
   fields: TFields;
   is_root?: TIsRoot;
   is_nestable?: TIsNestable;
+  folder?: TFolder;
 } & Partial<Pick<Block, Exclude<BlockOptional, 'is_root' | 'is_nestable'>>>>;
-type DefinedBlock<TName extends string, TFields extends BlockFields, TIsRoot extends boolean, TIsNestable extends boolean> = Prettify<Omit<Block, 'name' | 'fields' | 'is_root' | 'is_nestable'> & {
+type DefinedBlock<TName extends string, TFields extends BlockFields, TIsRoot extends boolean, TIsNestable extends boolean, TFolder extends FolderInput | undefined = undefined> = Prettify<Omit<Block, 'name' | 'fields' | 'is_root' | 'is_nestable' | 'folder'> & {
   name: TName;
   fields: TFields;
   is_root: TIsRoot;
   is_nestable: TIsNestable;
-}>;
+} & (TFolder extends undefined ? unknown : {
+  folder: NormalizeFolder<TFolder>;
+})>;
 /**
  * Returns a {@link Block} content-shape definition. The user-facing input is an
  * ordered array of `defineField` calls under `fields`; the array index becomes
@@ -39,7 +49,7 @@ type DefinedBlock<TName extends string, TFields extends BlockFields, TIsRoot ext
  *   ],
  * });
  */
-declare function defineBlock<TName extends string, const TFields extends BlockFields, TIsRoot extends boolean = false, TIsNestable extends boolean = true>(block: BlockInput<TName, TFields, TIsRoot, TIsNestable>): DefinedBlock<TName, TFields, TIsRoot, TIsNestable>;
+declare function defineBlock<TName extends string, const TFields extends BlockFields, TIsRoot extends boolean = false, TIsNestable extends boolean = true, const TFolder extends FolderInput | undefined = undefined>(block: BlockInput<TName, TFields, TIsRoot, TIsNestable, TFolder>): DefinedBlock<TName, TFields, TIsRoot, TIsNestable, TFolder>;
 //#endregion
 export { defineBlock };
 //# sourceMappingURL=define-block.d.cts.map

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

@@ -1,5 +1,6 @@
 import { Block, BlockFields, NestableBlock, RootBlock } from "../generated/types/block.mjs";
 import { Prettify } from "../utils/prettify.mjs";
+import { BlockFolder } from "./define-folder.mjs";
 
 //#region src/helpers/define-block.d.ts
 declare const BLOCK_DEFAULTS: {
@@ -11,18 +12,27 @@ declare const BLOCK_DEFAULTS: {
 };
 /** Fields that have safe defaults and may be omitted from block input. */
 type BlockOptional = keyof typeof BLOCK_DEFAULTS;
-type BlockInput<TName extends string = string, TFields extends BlockFields = BlockFields, TIsRoot extends boolean = false, TIsNestable extends boolean = true> = Prettify<Omit<Block, 'name' | 'fields' | 'is_root' | 'is_nestable' | BlockOptional> & {
+/** Accepted input for a block's `folder`: a folder ref, a raw path string, or `null` to explicitly ungroup. */
+type FolderInput = BlockFolder | string | null;
+/** Normalizes a folder input type to the display path literal it resolves to. */
+type NormalizeFolder<T> = T extends {
+  path: infer P extends string;
+} ? P : T;
+type BlockInput<TName extends string = string, TFields extends BlockFields = BlockFields, TIsRoot extends boolean = false, TIsNestable extends boolean = true, TFolder extends FolderInput | undefined = undefined> = Prettify<Omit<Block, 'name' | 'fields' | 'is_root' | 'is_nestable' | 'folder' | BlockOptional> & {
   name: TName;
   fields: TFields;
   is_root?: TIsRoot;
   is_nestable?: TIsNestable;
+  folder?: TFolder;
 } & Partial<Pick<Block, Exclude<BlockOptional, 'is_root' | 'is_nestable'>>>>;
-type DefinedBlock<TName extends string, TFields extends BlockFields, TIsRoot extends boolean, TIsNestable extends boolean> = Prettify<Omit<Block, 'name' | 'fields' | 'is_root' | 'is_nestable'> & {
+type DefinedBlock<TName extends string, TFields extends BlockFields, TIsRoot extends boolean, TIsNestable extends boolean, TFolder extends FolderInput | undefined = undefined> = Prettify<Omit<Block, 'name' | 'fields' | 'is_root' | 'is_nestable' | 'folder'> & {
   name: TName;
   fields: TFields;
   is_root: TIsRoot;
   is_nestable: TIsNestable;
-}>;
+} & (TFolder extends undefined ? unknown : {
+  folder: NormalizeFolder<TFolder>;
+})>;
 /**
  * Returns a {@link Block} content-shape definition. The user-facing input is an
  * ordered array of `defineField` calls under `fields`; the array index becomes
@@ -39,7 +49,7 @@ type DefinedBlock<TName extends string, TFields extends BlockFields, TIsRoot ext
  *   ],
  * });
  */
-declare function defineBlock<TName extends string, const TFields extends BlockFields, TIsRoot extends boolean = false, TIsNestable extends boolean = true>(block: BlockInput<TName, TFields, TIsRoot, TIsNestable>): DefinedBlock<TName, TFields, TIsRoot, TIsNestable>;
+declare function defineBlock<TName extends string, const TFields extends BlockFields, TIsRoot extends boolean = false, TIsNestable extends boolean = true, const TFolder extends FolderInput | undefined = undefined>(block: BlockInput<TName, TFields, TIsRoot, TIsNestable, TFolder>): DefinedBlock<TName, TFields, TIsRoot, TIsNestable, TFolder>;
 //#endregion
 export { defineBlock };
 //# sourceMappingURL=define-block.d.mts.map

package/dist/helpers/define-block.mjs

@@ -20,9 +20,14 @@ function defineBlock(block) {
 			pos: index
 		};
 	});
+	const { folder, ...restBlock } = block ?? {};
+	if (folder !== void 0 && typeof restBlock.component_group_uuid === "string") throw new Error(`defineBlock: block "${block?.name ?? ""}" sets both "folder" and "component_group_uuid"; use one`);
+	if (typeof folder === "string" && !folder.split("/").some((segment) => segment.trim() !== "")) throw new Error(`defineBlock: block "${block?.name ?? ""}" has an empty "folder" path`);
+	const normalizedFolder = folder === void 0 ? void 0 : folder !== null && typeof folder === "object" ? folder.path : folder;
 	return {
 		...BLOCK_DEFAULTS,
-		...block,
+		...restBlock,
+		...folder !== void 0 && { folder: normalizedFolder },
 		fields
 	};
 }

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.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

@@ -9,6 +9,7 @@
 * @example
 * export const schema = defineSchema({
 *   blocks: { pageBlock, heroBlock },
+*   folders: { layout },
 *   datasources: { colorsDatasource },
 *   fieldPlugins: { colorPicker },
 * });

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

@@ -1 +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 { 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  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 *   datasources: { colorsDatasource },\n *   fieldPlugins: { colorPicker },\n * });\n */\nexport function defineSchema<const T extends SchemaConfig>(schema: T): T {\n  return schema;\n}\n"],"mappings":";;;;;;;;;;;;;;;AAwBA,SAAgB,aAA2C,QAAc;AACvE,QAAO"}
+{"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"}