@contember/bindx-repeater 0.1.0

package/dist/components/BlockRepeater.d.ts

@@ -0,0 +1,46 @@
+import { type ReactElement } from 'react';
+import type { AnyBrand } from '@contember/bindx';
+import { BINDX_COMPONENT, type SelectionProvider } from '@contember/bindx-react';
+import type { BlockRepeaterProps } from '../types.js';
+/**
+ * Block repeater component for has-many relations with type discrimination.
+ *
+ * Each item has a discrimination field that determines its block type,
+ * allowing different rendering based on the block type.
+ *
+ * @example
+ * ```tsx
+ * <BlockRepeater
+ *   field={entity.blocks}
+ *   discriminationField="type"
+ *   sortableBy="order"
+ *   blocks={{
+ *     text: { label: 'Text' },
+ *     image: { label: 'Image' },
+ *   }}
+ * >
+ *   {(items, methods) => (
+ *     <>
+ *       {items.map((item, info) => {
+ *         switch (info.blockType) {
+ *           case 'text': return <div key={item.id}>{item.content.value}</div>
+ *           case 'image': return <img key={item.id} src={item.url.value} />
+ *           default: return null
+ *         }
+ *       })}
+ *       {methods.blockList.map(b => (
+ *         <button key={b.name} onClick={() => methods.addItem(b.name)}>
+ *           Add {b.label ?? b.name}
+ *         </button>
+ *       ))}
+ *     </>
+ *   )}
+ * </BlockRepeater>
+ * ```
+ */
+export declare function BlockRepeater<TEntity extends object = object, TSelected = TEntity, TBrand extends AnyBrand = AnyBrand, TEntityName extends string = string, TSchema extends Record<string, object> = Record<string, object>, TBlockNames extends string = string>({ field, discriminationField, sortableBy, blocks, children, }: BlockRepeaterProps<TEntity, TSelected, TBrand, TEntityName, TSchema, TBlockNames>): ReactElement;
+declare const blockRepeaterWithSelection: typeof BlockRepeater & SelectionProvider & {
+    [BINDX_COMPONENT]: true;
+};
+export { blockRepeaterWithSelection as BlockRepeaterWithMeta };
+//# sourceMappingURL=BlockRepeater.d.ts.map

package/dist/components/BlockRepeater.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlockRepeater.d.ts","sourceRoot":"","sources":["../../src/components/BlockRepeater.tsx"],"names":[],"mappings":"AAAA,OAAc,EAAW,KAAK,YAAY,EAAkB,MAAM,OAAO,CAAA;AACzE,OAAO,KAAK,EAGX,QAAQ,EAIR,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAyC,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AACvH,OAAO,KAAK,EACX,kBAAkB,EAMlB,MAAM,aAAa,CAAA;AAMpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,aAAa,CAC5B,OAAO,SAAS,MAAM,GAAG,MAAM,EAC/B,SAAS,GAAG,OAAO,EACnB,MAAM,SAAS,QAAQ,GAAG,QAAQ,EAClC,WAAW,SAAS,MAAM,GAAG,MAAM,EACnC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/D,WAAW,SAAS,MAAM,GAAG,MAAM,EAClC,EACD,KAAK,EACL,mBAAmB,EACnB,UAAU,EACV,MAAM,EACN,QAAQ,GACR,EAAE,kBAAkB,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,CAAC,GAAG,YAAY,CA+HlG;AAGD,QAAA,MAAM,0BAA0B,EAAoB,OAAO,aAAa,GAAG,iBAAiB,GAAG;IAAE,CAAC,eAAe,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AA8D1H,OAAO,EAAE,0BAA0B,IAAI,qBAAqB,EAAE,CAAA"}

package/dist/components/Repeater.d.ts

@@ -0,0 +1,38 @@
+import { type ReactElement } from 'react';
+import type { AnyBrand } from '@contember/bindx';
+import { BINDX_COMPONENT, type SelectionProvider } from '@contember/bindx-react';
+import type { RepeaterProps } from '../types.js';
+/**
+ * Main repeater component for rendering has-many relations with full type safety.
+ *
+ * Uses a callback-style API where types flow from the `field` prop through
+ * the `items.map()` callback, ensuring compile-time type safety.
+ *
+ * @example
+ * ```tsx
+ * <Repeater field={author.articles} sortableBy="order">
+ *   {(items, { addItem, isEmpty }) => (
+ *     <>
+ *       {isEmpty && <p>No articles</p>}
+ *
+ *       {items.map((article, { index, isFirst, isLast, remove, moveUp, moveDown }) => (
+ *         <div key={article.id}>
+ *           {article.title.value}
+ *           <button onClick={remove}>Remove</button>
+ *           <button onClick={moveUp} disabled={isFirst}>↑</button>
+ *           <button onClick={moveDown} disabled={isLast}>↓</button>
+ *         </div>
+ *       ))}
+ *
+ *       <button onClick={() => addItem()}>Add</button>
+ *     </>
+ *   )}
+ * </Repeater>
+ * ```
+ */
+export declare function Repeater<TEntity extends object = object, TSelected = TEntity, TBrand extends AnyBrand = AnyBrand, TEntityName extends string = string, TSchema extends Record<string, object> = Record<string, object>>({ field, sortableBy, children, }: RepeaterProps<TEntity, TSelected, TBrand, TEntityName, TSchema>): ReactElement;
+declare const repeaterWithSelection: typeof Repeater & SelectionProvider & {
+    [BINDX_COMPONENT]: true;
+};
+export { repeaterWithSelection as RepeaterWithMeta };
+//# sourceMappingURL=Repeater.d.ts.map

package/dist/components/Repeater.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Repeater.d.ts","sourceRoot":"","sources":["../../src/components/Repeater.tsx"],"names":[],"mappings":"AAAA,OAAc,EAAW,KAAK,YAAY,EAAkB,MAAM,OAAO,CAAA;AACzE,OAAO,KAAK,EAGX,QAAQ,EAGR,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAyC,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AACvH,OAAO,KAAK,EACX,aAAa,EAMb,MAAM,aAAa,CAAA;AAMpB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,QAAQ,CACvB,OAAO,SAAS,MAAM,GAAG,MAAM,EAC/B,SAAS,GAAG,OAAO,EACnB,MAAM,SAAS,QAAQ,GAAG,QAAQ,EAClC,WAAW,SAAS,MAAM,GAAG,MAAM,EACnC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9D,EACD,KAAK,EACL,UAAU,EACV,QAAQ,GACR,EAAE,aAAa,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,GAAG,YAAY,CAuHhF;AAGD,QAAA,MAAM,qBAAqB,EAAe,OAAO,QAAQ,GAAG,iBAAiB,GAAG;IAAE,CAAC,eAAe,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AAyD3G,OAAO,EAAE,qBAAqB,IAAI,gBAAgB,EAAE,CAAA"}

package/dist/components/index.d.ts

@@ -0,0 +1,3 @@
+export { Repeater, RepeaterWithMeta } from './Repeater.js';
+export { BlockRepeater, BlockRepeaterWithMeta } from './BlockRepeater.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useSortedItems } from './useSortedItems.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/hooks/useSortedItems.d.ts

@@ -0,0 +1,10 @@
+import type { EntityAccessor, HasManyRef, AnyBrand } from '@contember/bindx';
+/**
+ * Hook that returns sorted items from a has-many ref and repairs order field values.
+ *
+ * @param hasMany - The has-many ref
+ * @param orderField - Optional field name for sorting
+ * @returns Sorted array of entity accessors
+ */
+export declare function useSortedItems<T extends object, S = T, TBrand extends AnyBrand = AnyBrand, TEntityName extends string = string, TSchema extends Record<string, object> = Record<string, object>>(hasMany: HasManyRef<T, S, TBrand, TEntityName, TSchema>, orderField: string | undefined): EntityAccessor<T, S, TBrand, TEntityName, TSchema>[];
+//# sourceMappingURL=useSortedItems.d.ts.map

package/dist/hooks/useSortedItems.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSortedItems.d.ts","sourceRoot":"","sources":["../../src/hooks/useSortedItems.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAI5E;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC7B,CAAC,SAAS,MAAM,EAChB,CAAC,GAAG,CAAC,EACL,MAAM,SAAS,QAAQ,GAAG,QAAQ,EAClC,WAAW,SAAS,MAAM,GAAG,MAAM,EACnC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAE/D,OAAO,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,EACvD,UAAU,EAAE,MAAM,GAAG,SAAS,GAC5B,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,CAgBtD"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Repeater components for has-many list management with Bindx
+ *
+ * @packageDocumentation
+ */
+export type { RepeaterAddItemIndex, RepeaterMoveItemIndex, RepeaterPreprocessCallback, RepeaterItemInfo, RepeaterItems, RepeaterMethods, RepeaterRenderFn, RepeaterProps, BlockDefinition, BlockRepeaterItemInfo, BlockRepeaterItems, BlockRepeaterMethods, BlockRepeaterRenderFn, BlockRepeaterProps, } from './types.js';
+export { useSortedItems } from './hooks/index.js';
+export { arrayMove, sortEntities, repairEntitiesOrder, } from './utils/index.js';
+export { Repeater, RepeaterWithMeta } from './components/index.js';
+export { BlockRepeater, BlockRepeaterWithMeta } from './components/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EACX,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,EAC1B,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,GAClB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAGjD,OAAO,EACN,SAAS,EACT,YAAY,EACZ,mBAAmB,GACnB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAClE,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,141 @@
+import type { ReactNode } from 'react';
+import type { EntityAccessor, HasManyRef, AnyBrand } from '@contember/bindx';
+/**
+ * Index for adding items to the repeater.
+ * - number: Adds at the specified index
+ * - 'first': Adds at the beginning
+ * - 'last' or undefined: Adds at the end
+ */
+export type RepeaterAddItemIndex = number | 'first' | 'last' | undefined;
+/**
+ * Index for moving items within the repeater.
+ * - number: Moves to the specified index
+ * - 'first': Moves to the beginning
+ * - 'last': Moves to the end
+ * - 'previous': Moves to the previous position
+ * - 'next': Moves to the next position
+ */
+export type RepeaterMoveItemIndex = number | 'first' | 'last' | 'previous' | 'next';
+/**
+ * Callback for preprocessing a newly created entity.
+ */
+export type RepeaterPreprocessCallback<T> = (entity: EntityAccessor<T>) => void;
+/**
+ * Information about a single repeater item, passed to the map callback.
+ */
+export interface RepeaterItemInfo {
+    /** Index of the item in the sorted list */
+    index: number;
+    /** Whether this is the first item */
+    isFirst: boolean;
+    /** Whether this is the last item */
+    isLast: boolean;
+    /** Remove this item from the repeater */
+    remove: () => void;
+    /** Move this item up (to previous position). Only available when sortableBy is defined. */
+    moveUp: () => void;
+    /** Move this item down (to next position). Only available when sortableBy is defined. */
+    moveDown: () => void;
+}
+/**
+ * Items collection object passed to the repeater render function.
+ * Provides a type-safe map() method for iterating over items.
+ */
+export interface RepeaterItems<TEntity, TSelected = TEntity, TBrand extends AnyBrand = AnyBrand, TEntityName extends string = string, TSchema extends Record<string, object> = Record<string, object>> {
+    /**
+     * Map over items with full type safety.
+     * Each item receives the entity accessor and item info (index, isFirst, isLast, remove, moveUp, moveDown).
+     */
+    map: <R>(fn: (entity: EntityAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema>, info: RepeaterItemInfo) => R) => R[];
+    /** Number of items in the repeater */
+    length: number;
+}
+/**
+ * Methods available at the repeater level for adding items.
+ */
+export interface RepeaterMethods<T = unknown> {
+    /**
+     * Adds a new item to the repeater.
+     * @param index - Where to add the item (default: 'last')
+     * @param preprocess - Optional callback to preprocess the new entity
+     */
+    addItem: (index?: RepeaterAddItemIndex, preprocess?: RepeaterPreprocessCallback<T>) => void;
+    /** Whether the repeater is empty */
+    isEmpty: boolean;
+}
+/**
+ * Render function type for the Repeater component.
+ */
+export type RepeaterRenderFn<TEntity, TSelected = TEntity, TBrand extends AnyBrand = AnyBrand, TEntityName extends string = string, TSchema extends Record<string, object> = Record<string, object>> = (items: RepeaterItems<TEntity, TSelected, TBrand, TEntityName, TSchema>, methods: RepeaterMethods<TEntity>) => ReactNode;
+/**
+ * Props for the Repeater component.
+ * Types flow from the field prop to the children callback for full type safety.
+ */
+export interface RepeaterProps<TEntity, TSelected = TEntity, TBrand extends AnyBrand = AnyBrand, TEntityName extends string = string, TSchema extends Record<string, object> = Record<string, object>> {
+    /** The has-many relation field */
+    field: HasManyRef<TEntity, TSelected, TBrand, TEntityName, TSchema>;
+    /** Optional field name for sorting (must be a numeric field) */
+    sortableBy?: string;
+    /** Render function that receives items collection and methods */
+    children: RepeaterRenderFn<TEntity, TSelected, TBrand, TEntityName, TSchema>;
+}
+/**
+ * Minimal block definition for headless use.
+ */
+export interface BlockDefinition {
+    label?: ReactNode;
+}
+/**
+ * Extended item info with block type discrimination.
+ */
+export interface BlockRepeaterItemInfo extends RepeaterItemInfo {
+    /** Value of the discrimination field */
+    blockType: string | null;
+    /** Resolved block definition, undefined if block type is unknown */
+    block: {
+        name: string;
+        label?: ReactNode;
+    } | undefined;
+}
+/**
+ * Items collection for BlockRepeater with BlockRepeaterItemInfo.
+ */
+export interface BlockRepeaterItems<TEntity, TSelected = TEntity, TBrand extends AnyBrand = AnyBrand, TEntityName extends string = string, TSchema extends Record<string, object> = Record<string, object>> {
+    map: <R>(fn: (entity: EntityAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema>, info: BlockRepeaterItemInfo) => R) => R[];
+    /** Number of items in the repeater */
+    length: number;
+}
+/**
+ * Methods for BlockRepeater — addItem requires a block type.
+ */
+export interface BlockRepeaterMethods<TBlockNames extends string> {
+    /** Add a new item with the given block type */
+    addItem: (type: TBlockNames, index?: RepeaterAddItemIndex) => void;
+    /** Whether the repeater is empty */
+    isEmpty: boolean;
+    /** List of all defined blocks */
+    blockList: ReadonlyArray<{
+        name: TBlockNames;
+        label?: ReactNode;
+    }>;
+}
+/**
+ * Render function type for BlockRepeater.
+ */
+export type BlockRepeaterRenderFn<TEntity, TSelected = TEntity, TBrand extends AnyBrand = AnyBrand, TEntityName extends string = string, TSchema extends Record<string, object> = Record<string, object>, TBlockNames extends string = string> = (items: BlockRepeaterItems<TEntity, TSelected, TBrand, TEntityName, TSchema>, methods: BlockRepeaterMethods<TBlockNames>) => ReactNode;
+/**
+ * Props for the BlockRepeater component.
+ */
+export interface BlockRepeaterProps<TEntity, TSelected = TEntity, TBrand extends AnyBrand = AnyBrand, TEntityName extends string = string, TSchema extends Record<string, object> = Record<string, object>, TBlockNames extends string = string> {
+    /** The has-many relation field */
+    field: HasManyRef<TEntity, TSelected, TBrand, TEntityName, TSchema>;
+    /** Name of the scalar field used to discriminate block types */
+    discriminationField: string;
+    /** Optional field name for sorting (must be a numeric field) */
+    sortableBy?: string;
+    /** Block definitions keyed by block type name */
+    blocks: Record<TBlockNames, BlockDefinition>;
+    /** Render function that receives items collection and methods */
+    children: BlockRepeaterRenderFn<TEntity, TSelected, TBrand, TEntityName, TSchema, TBlockNames>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/utils/arrayMove.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Moves an element from one position to another in an array.
+ * Returns a new array with the element moved.
+ *
+ * @param array - The source array
+ * @param from - The index to move from
+ * @param to - The index to move to
+ * @returns A new array with the element moved
+ */
+export declare function arrayMove<T>(array: T[], from: number, to: number): T[];
+//# sourceMappingURL=arrayMove.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"arrayMove.d.ts","sourceRoot":"","sources":["../../src/utils/arrayMove.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,CAAC,EAAE,CAItE"}

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export { arrayMove } from './arrayMove.js';
+export { sortEntities } from './sortEntities.js';
+export { repairEntitiesOrder } from './repairEntitiesOrder.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/utils/repairEntitiesOrder.d.ts

@@ -0,0 +1,10 @@
+import type { EntityAccessor } from '@contember/bindx';
+/**
+ * Repairs the order field values of entities to be sequential (0, 1, 2, ...).
+ * Only updates values that differ from their expected index.
+ *
+ * @param items - Array of entity accessors (already sorted)
+ * @param orderField - Name of the numeric field to update
+ */
+export declare function repairEntitiesOrder<T extends object, S = T>(items: EntityAccessor<T, S>[], orderField: string): void;
+//# sourceMappingURL=repairEntitiesOrder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repairEntitiesOrder.d.ts","sourceRoot":"","sources":["../../src/utils/repairEntitiesOrder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAY,MAAM,kBAAkB,CAAA;AAEhE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,GAAG,CAAC,EAC1D,KAAK,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAC7B,UAAU,EAAE,MAAM,GAChB,IAAI,CASN"}

package/dist/utils/sortEntities.d.ts

@@ -0,0 +1,11 @@
+import type { EntityAccessor } from '@contember/bindx';
+/**
+ * Sorts entities by a numeric order field.
+ * Returns a new sorted array.
+ *
+ * @param items - Array of entity accessors
+ * @param orderField - Name of the numeric field to sort by
+ * @returns New sorted array of entities
+ */
+export declare function sortEntities<T extends object, S = T>(items: EntityAccessor<T, S>[], orderField: string | undefined): EntityAccessor<T, S>[];
+//# sourceMappingURL=sortEntities.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sortEntities.d.ts","sourceRoot":"","sources":["../../src/utils/sortEntities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAY,MAAM,kBAAkB,CAAA;AAEhE;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,GAAG,CAAC,EACnD,KAAK,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAC7B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC5B,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAcxB"}

package/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "@contember/bindx-repeater",
+	"version": "0.1.0",
+	"description": "Repeater components for has-many list management",
+	"type": "module",
+	"main": "./src/index.ts",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"scripts": {
+		"build": "tsc --build",
+		"typecheck": "tsc --build"
+	},
+	"peerDependencies": {
+		"react": ">=18.0.0"
+	},
+	"dependencies": {
+		"@contember/bindx": "0.1.0",
+		"@contember/bindx-react": "0.1.0"
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/contember/bindx.git",
+		"directory": "packages/bindx-repeater"
+	}
+}

package/src/components/BlockRepeater.tsx

@@ -0,0 +1,266 @@
+import React, { useMemo, type ReactElement, type ReactNode } from 'react'
+import type {
+	EntityAccessor,
+	HasManyRef,
+	AnyBrand,
+	SelectionFieldMeta,
+	SelectionMeta,
+	FieldRef,
+} from '@contember/bindx'
+import { SelectionScope, FIELD_REF_META } from '@contember/bindx'
+import { createCollectorProxy, mergeSelections, BINDX_COMPONENT, type SelectionProvider } from '@contember/bindx-react'
+import type {
+	BlockRepeaterProps,
+	BlockRepeaterItems,
+	BlockRepeaterItemInfo,
+	BlockRepeaterMethods,
+	BlockDefinition,
+	RepeaterAddItemIndex,
+} from '../types.js'
+import { useSortedItems } from '../hooks/useSortedItems.js'
+import { sortEntities } from '../utils/sortEntities.js'
+import { repairEntitiesOrder } from '../utils/repairEntitiesOrder.js'
+import { arrayMove } from '../utils/arrayMove.js'
+
+/**
+ * Block repeater component for has-many relations with type discrimination.
+ *
+ * Each item has a discrimination field that determines its block type,
+ * allowing different rendering based on the block type.
+ *
+ * @example
+ * ```tsx
+ * <BlockRepeater
+ *   field={entity.blocks}
+ *   discriminationField="type"
+ *   sortableBy="order"
+ *   blocks={{
+ *     text: { label: 'Text' },
+ *     image: { label: 'Image' },
+ *   }}
+ * >
+ *   {(items, methods) => (
+ *     <>
+ *       {items.map((item, info) => {
+ *         switch (info.blockType) {
+ *           case 'text': return <div key={item.id}>{item.content.value}</div>
+ *           case 'image': return <img key={item.id} src={item.url.value} />
+ *           default: return null
+ *         }
+ *       })}
+ *       {methods.blockList.map(b => (
+ *         <button key={b.name} onClick={() => methods.addItem(b.name)}>
+ *           Add {b.label ?? b.name}
+ *         </button>
+ *       ))}
+ *     </>
+ *   )}
+ * </BlockRepeater>
+ * ```
+ */
+export function BlockRepeater<
+	TEntity extends object = object,
+	TSelected = TEntity,
+	TBrand extends AnyBrand = AnyBrand,
+	TEntityName extends string = string,
+	TSchema extends Record<string, object> = Record<string, object>,
+	TBlockNames extends string = string,
+>({
+	field,
+	discriminationField,
+	sortableBy,
+	blocks,
+	children,
+}: BlockRepeaterProps<TEntity, TSelected, TBrand, TEntityName, TSchema, TBlockNames>): ReactElement {
+	const sortedItems = useSortedItems(field, sortableBy)
+
+	const items = useMemo((): BlockRepeaterItems<TEntity, TSelected, TBrand, TEntityName, TSchema> => {
+		const createItemInfo = (
+			entity: EntityAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema>,
+			index: number,
+		): BlockRepeaterItemInfo => {
+			const isFirst = index === 0
+			const isLast = index === sortedItems.length - 1
+
+			const discriminationRef = (entity.$fields as Record<string, unknown>)[discriminationField] as FieldRef<string> | undefined
+			const blockType = discriminationRef?.value ?? null
+			const blockDef = blockType !== null ? (blocks as Record<string, BlockDefinition>)[blockType] : undefined
+			const block = blockDef !== undefined && blockType !== null
+				? { name: blockType, label: blockDef.label }
+				: undefined
+
+			const remove = (): void => {
+				if (sortableBy) {
+					const items = sortEntities(field.items, sortableBy) as EntityAccessor<TEntity, TSelected>[]
+					const currentIndex = items.findIndex(item => item.id === entity.id)
+					if (currentIndex !== -1) {
+						items.splice(currentIndex, 1)
+						repairEntitiesOrder(items, sortableBy)
+					}
+				}
+				field.remove(entity.id)
+			}
+
+			const moveUp = (): void => {
+				if (!sortableBy || isFirst) return
+				const items = sortEntities(field.items, sortableBy) as EntityAccessor<TEntity, TSelected>[]
+				const currentIndex = items.findIndex(item => item.id === entity.id)
+				if (currentIndex === -1 || currentIndex === 0) return
+				const newItems = arrayMove(items, currentIndex, currentIndex - 1)
+				repairEntitiesOrder(newItems, sortableBy)
+			}
+
+			const moveDown = (): void => {
+				if (!sortableBy || isLast) return
+				const items = sortEntities(field.items, sortableBy) as EntityAccessor<TEntity, TSelected>[]
+				const currentIndex = items.findIndex(item => item.id === entity.id)
+				if (currentIndex === -1 || currentIndex === items.length - 1) return
+				const newItems = arrayMove(items, currentIndex, currentIndex + 1)
+				repairEntitiesOrder(newItems, sortableBy)
+			}
+
+			return { index, isFirst, isLast, remove, moveUp, moveDown, blockType, block }
+		}
+
+		return {
+			map: <R,>(
+				fn: (
+					entity: EntityAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema>,
+					info: BlockRepeaterItemInfo,
+				) => R,
+			): R[] => {
+				return sortedItems.map((entity, index) => {
+					const info = createItemInfo(entity, index)
+					return fn(entity, info)
+				})
+			},
+			length: sortedItems.length,
+		}
+	}, [sortedItems, field, sortableBy, discriminationField, blocks])
+
+	const methods = useMemo((): BlockRepeaterMethods<TBlockNames> => {
+		const blockList = (Object.keys(blocks) as TBlockNames[]).map(name => ({
+			name,
+			label: (blocks as Record<string, BlockDefinition>)[name]?.label,
+		}))
+
+		const addItem = (
+			type: TBlockNames,
+			index: RepeaterAddItemIndex = 'last',
+		): void => {
+			if (!sortableBy) {
+				if (index === 'last' || index === undefined) {
+					const entityId = field.add()
+					const items = field.items
+					const newEntity = items.find(item => item.id === entityId)
+					if (newEntity) {
+						const discriminationRef = (newEntity.$fields as Record<string, unknown>)[discriminationField] as FieldRef<string> | undefined
+						discriminationRef?.setValue(type)
+					}
+					return
+				}
+				throw new Error('Cannot add item at specific index without sortableBy field')
+			}
+
+			const currentItems = sortEntities(field.items, sortableBy) as EntityAccessor<TEntity, TSelected>[]
+
+			const resolvedIndex = (() => {
+				switch (index) {
+					case 'first':
+						return 0
+					case 'last':
+					case undefined:
+						return currentItems.length
+					default:
+						return index
+				}
+			})()
+
+			const entityId = field.add()
+			const items = field.items
+			const newEntity = items.find(item => item.id === entityId)
+
+			if (newEntity) {
+				const newSortedItems = [...currentItems]
+				newSortedItems.splice(resolvedIndex, 0, newEntity as EntityAccessor<TEntity, TSelected>)
+				repairEntitiesOrder(newSortedItems, sortableBy)
+
+				const discriminationRef = (newEntity.$fields as Record<string, unknown>)[discriminationField] as FieldRef<string> | undefined
+				discriminationRef?.setValue(type)
+			}
+		}
+
+		return {
+			addItem,
+			isEmpty: field.length === 0,
+			blockList,
+		}
+	}, [field, sortableBy, blocks, discriminationField])
+
+	return <>{children(items, methods)}</>
+}
+
+// Static method for selection extraction
+const blockRepeaterWithSelection = BlockRepeater as typeof BlockRepeater & SelectionProvider & { [BINDX_COMPONENT]: true }
+
+blockRepeaterWithSelection.getSelection = (
+	props: BlockRepeaterProps<unknown>,
+	collectNested: (children: ReactNode) => SelectionMeta,
+): SelectionFieldMeta => {
+	const meta = props.field[FIELD_REF_META]
+
+	const scope = new SelectionScope()
+	const collectorEntity = createCollectorProxy<unknown>(scope)
+
+	const mockItems: BlockRepeaterItems<unknown> = {
+		map: (fn) => {
+			fn(collectorEntity, {
+				index: 0,
+				isFirst: true,
+				isLast: true,
+				remove: () => {},
+				moveUp: () => {},
+				moveDown: () => {},
+				blockType: null,
+				block: undefined,
+			})
+			return []
+		},
+		length: 0,
+	}
+
+	const mockMethods: BlockRepeaterMethods<string> = {
+		addItem: () => {},
+		isEmpty: true,
+		blockList: [],
+	}
+
+	const syntheticChildren = props.children(mockItems, mockMethods)
+	const jsxSelection = collectNested(syntheticChildren)
+
+	const nestedSelection = scope.toSelectionMeta()
+	mergeSelections(nestedSelection, jsxSelection)
+
+	// Add discrimination field to selection
+	nestedSelection.fields.set(props.discriminationField, {
+		fieldName: props.discriminationField,
+		alias: props.discriminationField,
+		path: [...meta.path, meta.fieldName],
+		isArray: false,
+		isRelation: false,
+		nested: { fields: new Map() },
+	})
+
+	return {
+		fieldName: meta.fieldName,
+		alias: meta.fieldName,
+		path: meta.path,
+		isArray: true,
+		isRelation: true,
+		nested: nestedSelection,
+	}
+}
+
+blockRepeaterWithSelection[BINDX_COMPONENT] = true
+
+export { blockRepeaterWithSelection as BlockRepeaterWithMeta }

package/src/components/Repeater.tsx

@@ -0,0 +1,241 @@
+import React, { useMemo, type ReactElement, type ReactNode } from 'react'
+import type {
+	EntityAccessor,
+	HasManyRef,
+	AnyBrand,
+	SelectionFieldMeta,
+	SelectionMeta,
+} from '@contember/bindx'
+import { SelectionScope, FIELD_REF_META } from '@contember/bindx'
+import { createCollectorProxy, mergeSelections, BINDX_COMPONENT, type SelectionProvider } from '@contember/bindx-react'
+import type {
+	RepeaterProps,
+	RepeaterItems,
+	RepeaterItemInfo,
+	RepeaterMethods,
+	RepeaterAddItemIndex,
+	RepeaterPreprocessCallback,
+} from '../types.js'
+import { useSortedItems } from '../hooks/useSortedItems.js'
+import { sortEntities } from '../utils/sortEntities.js'
+import { repairEntitiesOrder } from '../utils/repairEntitiesOrder.js'
+import { arrayMove } from '../utils/arrayMove.js'
+
+/**
+ * Main repeater component for rendering has-many relations with full type safety.
+ *
+ * Uses a callback-style API where types flow from the `field` prop through
+ * the `items.map()` callback, ensuring compile-time type safety.
+ *
+ * @example
+ * ```tsx
+ * <Repeater field={author.articles} sortableBy="order">
+ *   {(items, { addItem, isEmpty }) => (
+ *     <>
+ *       {isEmpty && <p>No articles</p>}
+ *
+ *       {items.map((article, { index, isFirst, isLast, remove, moveUp, moveDown }) => (
+ *         <div key={article.id}>
+ *           {article.title.value}
+ *           <button onClick={remove}>Remove</button>
+ *           <button onClick={moveUp} disabled={isFirst}>↑</button>
+ *           <button onClick={moveDown} disabled={isLast}>↓</button>
+ *         </div>
+ *       ))}
+ *
+ *       <button onClick={() => addItem()}>Add</button>
+ *     </>
+ *   )}
+ * </Repeater>
+ * ```
+ */
+export function Repeater<
+	TEntity extends object = object,
+	TSelected = TEntity,
+	TBrand extends AnyBrand = AnyBrand,
+	TEntityName extends string = string,
+	TSchema extends Record<string, object> = Record<string, object>,
+>({
+	field,
+	sortableBy,
+	children,
+}: RepeaterProps<TEntity, TSelected, TBrand, TEntityName, TSchema>): ReactElement {
+	const sortedItems = useSortedItems(field, sortableBy)
+
+	// Create stable items collection object
+	const items = useMemo((): RepeaterItems<TEntity, TSelected, TBrand, TEntityName, TSchema> => {
+		const createItemInfo = (
+			entity: EntityAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema>,
+			index: number,
+		): RepeaterItemInfo => {
+			const isFirst = index === 0
+			const isLast = index === sortedItems.length - 1
+
+			const remove = (): void => {
+				if (sortableBy) {
+					const items = sortEntities(field.items, sortableBy) as EntityAccessor<TEntity, TSelected>[]
+					const currentIndex = items.findIndex(item => item.id === entity.id)
+					if (currentIndex !== -1) {
+						items.splice(currentIndex, 1)
+						repairEntitiesOrder(items, sortableBy)
+					}
+				}
+				field.remove(entity.id)
+			}
+
+			const moveUp = (): void => {
+				if (!sortableBy || isFirst) return
+				const items = sortEntities(field.items, sortableBy) as EntityAccessor<TEntity, TSelected>[]
+				const currentIndex = items.findIndex(item => item.id === entity.id)
+				if (currentIndex === -1 || currentIndex === 0) return
+				const newItems = arrayMove(items, currentIndex, currentIndex - 1)
+				repairEntitiesOrder(newItems, sortableBy)
+			}
+
+			const moveDown = (): void => {
+				if (!sortableBy || isLast) return
+				const items = sortEntities(field.items, sortableBy) as EntityAccessor<TEntity, TSelected>[]
+				const currentIndex = items.findIndex(item => item.id === entity.id)
+				if (currentIndex === -1 || currentIndex === items.length - 1) return
+				const newItems = arrayMove(items, currentIndex, currentIndex + 1)
+				repairEntitiesOrder(newItems, sortableBy)
+			}
+
+			return { index, isFirst, isLast, remove, moveUp, moveDown }
+		}
+
+		return {
+			map: <R,>(
+				fn: (
+					entity: EntityAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema>,
+					info: RepeaterItemInfo,
+				) => R,
+			): R[] => {
+				return sortedItems.map((entity, index) => {
+					const info = createItemInfo(entity, index)
+					return fn(entity, info)
+				})
+			},
+			length: sortedItems.length,
+		}
+	}, [sortedItems, field, sortableBy])
+
+	// Create methods object
+	const methods = useMemo((): RepeaterMethods<TEntity> => {
+		const addItem = (
+			index: RepeaterAddItemIndex = 'last',
+			preprocess?: RepeaterPreprocessCallback<TEntity>,
+		): void => {
+			if (!sortableBy) {
+				if (index === 'last' || index === undefined) {
+					const entityId = field.add()
+					if (preprocess) {
+						const items = field.items
+						const newEntity = items.find(item => item.id === entityId)
+						if (newEntity) {
+							preprocess(newEntity as unknown as EntityAccessor<TEntity>)
+						}
+					}
+					return
+				}
+				throw new Error('Cannot add item at specific index without sortableBy field')
+			}
+
+			const sortedItems = sortEntities(field.items, sortableBy) as EntityAccessor<TEntity, TSelected>[]
+
+			const resolvedIndex = (() => {
+				switch (index) {
+					case 'first':
+						return 0
+					case 'last':
+					case undefined:
+						return sortedItems.length
+					default:
+						return index
+				}
+			})()
+
+			const entityId = field.add()
+			const items = field.items
+			const newEntity = items.find(item => item.id === entityId)
+
+			if (newEntity) {
+				const newSortedItems = [...sortedItems]
+				newSortedItems.splice(resolvedIndex, 0, newEntity as EntityAccessor<TEntity, TSelected>)
+				repairEntitiesOrder(newSortedItems, sortableBy)
+
+				if (preprocess) {
+					preprocess(newEntity as unknown as EntityAccessor<TEntity>)
+				}
+			}
+		}
+
+		return {
+			addItem,
+			isEmpty: field.length === 0,
+		}
+	}, [field, sortableBy])
+
+	// Call children with items and methods
+	return <>{children(items, methods)}</>
+}
+
+// Static method for selection extraction
+const repeaterWithSelection = Repeater as typeof Repeater & SelectionProvider & { [BINDX_COMPONENT]: true }
+
+repeaterWithSelection.getSelection = (
+	props: RepeaterProps<unknown>,
+	collectNested: (children: ReactNode) => SelectionMeta,
+): SelectionFieldMeta => {
+	const meta = props.field[FIELD_REF_META]
+
+	// Create scope and collector proxy
+	const scope = new SelectionScope()
+	const collectorEntity = createCollectorProxy<unknown>(scope)
+
+	// Create mock items object for collection phase
+	const mockItems: RepeaterItems<unknown> = {
+		map: (fn) => {
+			// Invoke callback with collector proxy to track field access
+			fn(collectorEntity, {
+				index: 0,
+				isFirst: true,
+				isLast: true,
+				remove: () => {},
+				moveUp: () => {},
+				moveDown: () => {},
+			})
+			return []
+		},
+		length: 0,
+	}
+
+	// Create mock methods
+	const mockMethods: RepeaterMethods<unknown> = {
+		addItem: () => {},
+		isEmpty: true,
+	}
+
+	// Invoke children callback - this tracks all field access
+	const syntheticChildren = props.children(mockItems, mockMethods)
+
+	// Also analyze JSX structure
+	const jsxSelection = collectNested(syntheticChildren)
+
+	// Merge both tracking methods
+	const nestedSelection = scope.toSelectionMeta()
+	mergeSelections(nestedSelection, jsxSelection)
+
+	return {
+		fieldName: meta.fieldName,
+		alias: meta.fieldName,
+		path: meta.path,
+		isArray: true,
+		isRelation: true,
+		nested: nestedSelection,
+	}
+}
+
+repeaterWithSelection[BINDX_COMPONENT] = true
+
+export { repeaterWithSelection as RepeaterWithMeta }

package/src/components/index.ts

@@ -0,0 +1,2 @@
+export { Repeater, RepeaterWithMeta } from './Repeater.js'
+export { BlockRepeater, BlockRepeaterWithMeta } from './BlockRepeater.js'

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export { useSortedItems } from './useSortedItems.js'

package/src/hooks/useSortedItems.ts

@@ -0,0 +1,38 @@
+import { useEffect, useMemo } from 'react'
+import type { EntityAccessor, HasManyRef, AnyBrand } from '@contember/bindx'
+import { sortEntities } from '../utils/sortEntities.js'
+import { repairEntitiesOrder } from '../utils/repairEntitiesOrder.js'
+
+/**
+ * Hook that returns sorted items from a has-many ref and repairs order field values.
+ *
+ * @param hasMany - The has-many ref
+ * @param orderField - Optional field name for sorting
+ * @returns Sorted array of entity accessors
+ */
+export function useSortedItems<
+	T extends object,
+	S = T,
+	TBrand extends AnyBrand = AnyBrand,
+	TEntityName extends string = string,
+	TSchema extends Record<string, object> = Record<string, object>,
+>(
+	hasMany: HasManyRef<T, S, TBrand, TEntityName, TSchema>,
+	orderField: string | undefined,
+): EntityAccessor<T, S, TBrand, TEntityName, TSchema>[] {
+	const items = hasMany.items
+
+	const sortedItems = useMemo(
+		() => sortEntities(items, orderField) as EntityAccessor<T, S, TBrand, TEntityName, TSchema>[],
+		[items, orderField],
+	)
+
+	useEffect(() => {
+		if (!orderField) {
+			return
+		}
+		repairEntitiesOrder(sortedItems, orderField)
+	}, [orderField, sortedItems])
+
+	return sortedItems
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Repeater components for has-many list management with Bindx
+ *
+ * @packageDocumentation
+ */
+
+// Types
+export type {
+	RepeaterAddItemIndex,
+	RepeaterMoveItemIndex,
+	RepeaterPreprocessCallback,
+	RepeaterItemInfo,
+	RepeaterItems,
+	RepeaterMethods,
+	RepeaterRenderFn,
+	RepeaterProps,
+	BlockDefinition,
+	BlockRepeaterItemInfo,
+	BlockRepeaterItems,
+	BlockRepeaterMethods,
+	BlockRepeaterRenderFn,
+	BlockRepeaterProps,
+} from './types.js'
+
+// Hooks (internal, but exposed for advanced use cases)
+export { useSortedItems } from './hooks/index.js'
+
+// Utils
+export {
+	arrayMove,
+	sortEntities,
+	repairEntitiesOrder,
+} from './utils/index.js'
+
+// Components
+export { Repeater, RepeaterWithMeta } from './components/index.js'
+export { BlockRepeater, BlockRepeaterWithMeta } from './components/index.js'

package/src/types.ts

@@ -0,0 +1,222 @@
+import type { ReactNode } from 'react'
+import type { EntityAccessor, HasManyRef, AnyBrand, FieldRef } from '@contember/bindx'
+
+/**
+ * Index for adding items to the repeater.
+ * - number: Adds at the specified index
+ * - 'first': Adds at the beginning
+ * - 'last' or undefined: Adds at the end
+ */
+export type RepeaterAddItemIndex = number | 'first' | 'last' | undefined
+
+/**
+ * Index for moving items within the repeater.
+ * - number: Moves to the specified index
+ * - 'first': Moves to the beginning
+ * - 'last': Moves to the end
+ * - 'previous': Moves to the previous position
+ * - 'next': Moves to the next position
+ */
+export type RepeaterMoveItemIndex = number | 'first' | 'last' | 'previous' | 'next'
+
+/**
+ * Callback for preprocessing a newly created entity.
+ */
+export type RepeaterPreprocessCallback<T> = (entity: EntityAccessor<T>) => void
+
+/**
+ * Information about a single repeater item, passed to the map callback.
+ */
+export interface RepeaterItemInfo {
+	/** Index of the item in the sorted list */
+	index: number
+
+	/** Whether this is the first item */
+	isFirst: boolean
+
+	/** Whether this is the last item */
+	isLast: boolean
+
+	/** Remove this item from the repeater */
+	remove: () => void
+
+	/** Move this item up (to previous position). Only available when sortableBy is defined. */
+	moveUp: () => void
+
+	/** Move this item down (to next position). Only available when sortableBy is defined. */
+	moveDown: () => void
+}
+
+/**
+ * Items collection object passed to the repeater render function.
+ * Provides a type-safe map() method for iterating over items.
+ */
+export interface RepeaterItems<
+	TEntity,
+	TSelected = TEntity,
+	TBrand extends AnyBrand = AnyBrand,
+	TEntityName extends string = string,
+	TSchema extends Record<string, object> = Record<string, object>,
+> {
+	/**
+	 * Map over items with full type safety.
+	 * Each item receives the entity accessor and item info (index, isFirst, isLast, remove, moveUp, moveDown).
+	 */
+	map: <R>(
+		fn: (
+			entity: EntityAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema>,
+			info: RepeaterItemInfo,
+		) => R
+	) => R[]
+
+	/** Number of items in the repeater */
+	length: number
+}
+
+/**
+ * Methods available at the repeater level for adding items.
+ */
+export interface RepeaterMethods<T = unknown> {
+	/**
+	 * Adds a new item to the repeater.
+	 * @param index - Where to add the item (default: 'last')
+	 * @param preprocess - Optional callback to preprocess the new entity
+	 */
+	addItem: (index?: RepeaterAddItemIndex, preprocess?: RepeaterPreprocessCallback<T>) => void
+
+	/** Whether the repeater is empty */
+	isEmpty: boolean
+}
+
+/**
+ * Render function type for the Repeater component.
+ */
+export type RepeaterRenderFn<
+	TEntity,
+	TSelected = TEntity,
+	TBrand extends AnyBrand = AnyBrand,
+	TEntityName extends string = string,
+	TSchema extends Record<string, object> = Record<string, object>,
+> = (
+	items: RepeaterItems<TEntity, TSelected, TBrand, TEntityName, TSchema>,
+	methods: RepeaterMethods<TEntity>,
+) => ReactNode
+
+/**
+ * Props for the Repeater component.
+ * Types flow from the field prop to the children callback for full type safety.
+ */
+export interface RepeaterProps<
+	TEntity,
+	TSelected = TEntity,
+	TBrand extends AnyBrand = AnyBrand,
+	TEntityName extends string = string,
+	TSchema extends Record<string, object> = Record<string, object>,
+> {
+	/** The has-many relation field */
+	field: HasManyRef<TEntity, TSelected, TBrand, TEntityName, TSchema>
+
+	/** Optional field name for sorting (must be a numeric field) */
+	sortableBy?: string
+
+	/** Render function that receives items collection and methods */
+	children: RepeaterRenderFn<TEntity, TSelected, TBrand, TEntityName, TSchema>
+}
+
+// ============================================================================
+// Block Repeater Types
+// ============================================================================
+
+/**
+ * Minimal block definition for headless use.
+ */
+export interface BlockDefinition {
+	label?: ReactNode
+}
+
+/**
+ * Extended item info with block type discrimination.
+ */
+export interface BlockRepeaterItemInfo extends RepeaterItemInfo {
+	/** Value of the discrimination field */
+	blockType: string | null
+	/** Resolved block definition, undefined if block type is unknown */
+	block: { name: string; label?: ReactNode } | undefined
+}
+
+/**
+ * Items collection for BlockRepeater with BlockRepeaterItemInfo.
+ */
+export interface BlockRepeaterItems<
+	TEntity,
+	TSelected = TEntity,
+	TBrand extends AnyBrand = AnyBrand,
+	TEntityName extends string = string,
+	TSchema extends Record<string, object> = Record<string, object>,
+> {
+	map: <R>(
+		fn: (
+			entity: EntityAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema>,
+			info: BlockRepeaterItemInfo,
+		) => R,
+	) => R[]
+
+	/** Number of items in the repeater */
+	length: number
+}
+
+/**
+ * Methods for BlockRepeater — addItem requires a block type.
+ */
+export interface BlockRepeaterMethods<TBlockNames extends string> {
+	/** Add a new item with the given block type */
+	addItem: (type: TBlockNames, index?: RepeaterAddItemIndex) => void
+
+	/** Whether the repeater is empty */
+	isEmpty: boolean
+
+	/** List of all defined blocks */
+	blockList: ReadonlyArray<{ name: TBlockNames; label?: ReactNode }>
+}
+
+/**
+ * Render function type for BlockRepeater.
+ */
+export type BlockRepeaterRenderFn<
+	TEntity,
+	TSelected = TEntity,
+	TBrand extends AnyBrand = AnyBrand,
+	TEntityName extends string = string,
+	TSchema extends Record<string, object> = Record<string, object>,
+	TBlockNames extends string = string,
+> = (
+	items: BlockRepeaterItems<TEntity, TSelected, TBrand, TEntityName, TSchema>,
+	methods: BlockRepeaterMethods<TBlockNames>,
+) => ReactNode
+
+/**
+ * Props for the BlockRepeater component.
+ */
+export interface BlockRepeaterProps<
+	TEntity,
+	TSelected = TEntity,
+	TBrand extends AnyBrand = AnyBrand,
+	TEntityName extends string = string,
+	TSchema extends Record<string, object> = Record<string, object>,
+	TBlockNames extends string = string,
+> {
+	/** The has-many relation field */
+	field: HasManyRef<TEntity, TSelected, TBrand, TEntityName, TSchema>
+
+	/** Name of the scalar field used to discriminate block types */
+	discriminationField: string
+
+	/** Optional field name for sorting (must be a numeric field) */
+	sortableBy?: string
+
+	/** Block definitions keyed by block type name */
+	blocks: Record<TBlockNames, BlockDefinition>
+
+	/** Render function that receives items collection and methods */
+	children: BlockRepeaterRenderFn<TEntity, TSelected, TBrand, TEntityName, TSchema, TBlockNames>
+}

package/src/utils/arrayMove.ts

@@ -0,0 +1,14 @@
+/**
+ * Moves an element from one position to another in an array.
+ * Returns a new array with the element moved.
+ *
+ * @param array - The source array
+ * @param from - The index to move from
+ * @param to - The index to move to
+ * @returns A new array with the element moved
+ */
+export function arrayMove<T>(array: T[], from: number, to: number): T[] {
+	const newArray = array.slice()
+	newArray.splice(to, 0, newArray.splice(from, 1)[0]!)
+	return newArray
+}

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export { arrayMove } from './arrayMove.js'
+export { sortEntities } from './sortEntities.js'
+export { repairEntitiesOrder } from './repairEntitiesOrder.js'

package/src/utils/repairEntitiesOrder.ts

@@ -0,0 +1,22 @@
+import type { EntityAccessor, FieldRef } from '@contember/bindx'
+
+/**
+ * Repairs the order field values of entities to be sequential (0, 1, 2, ...).
+ * Only updates values that differ from their expected index.
+ *
+ * @param items - Array of entity accessors (already sorted)
+ * @param orderField - Name of the numeric field to update
+ */
+export function repairEntitiesOrder<T extends object, S = T>(
+	items: EntityAccessor<T, S>[],
+	orderField: string,
+): void {
+	for (let i = 0; i < items.length; i++) {
+		const entity = items[i]!
+		const field = (entity as Record<string, unknown>)[orderField] as FieldRef<number> | undefined
+
+		if (field && field.value !== i) {
+			field.setValue(i)
+		}
+	}
+}

package/src/utils/sortEntities.ts

@@ -0,0 +1,28 @@
+import type { EntityAccessor, FieldRef } from '@contember/bindx'
+
+/**
+ * Sorts entities by a numeric order field.
+ * Returns a new sorted array.
+ *
+ * @param items - Array of entity accessors
+ * @param orderField - Name of the numeric field to sort by
+ * @returns New sorted array of entities
+ */
+export function sortEntities<T extends object, S = T>(
+	items: EntityAccessor<T, S>[],
+	orderField: string | undefined,
+): EntityAccessor<T, S>[] {
+	if (!orderField) {
+		return items
+	}
+
+	return [...items].sort((a, b) => {
+		const aField = (a as Record<string, unknown>)[orderField] as FieldRef<number> | undefined
+		const bField = (b as Record<string, unknown>)[orderField] as FieldRef<number> | undefined
+
+		const aValue = aField?.value ?? Number.MAX_SAFE_INTEGER
+		const bValue = bField?.value ?? Number.MAX_SAFE_INTEGER
+
+		return aValue - bValue
+	})
+}