@contember/react-block-repeater 2.0.0-alpha.39 → 2.0.0-alpha.40

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@contember/react-block-repeater",
   "license": "Apache-2.0",
-  "version": "2.0.0-alpha.39",
+  "version": "2.0.0-alpha.40",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/production/index.js",
@@ -29,10 +29,11 @@
     "ae:test": "api-extractor run"
   },
   "dependencies": {
-    "@contember/react-binding": "2.0.0-alpha.39",
-    "@contember/react-multipass-rendering": "2.0.0-alpha.39",
-    "@contember/react-repeater": "2.0.0-alpha.39",
-    "@contember/react-utils": "2.0.0-alpha.39",
+    "@contember/react-binding": "2.0.0-alpha.40",
+    "@contember/react-multipass-rendering": "2.0.0-alpha.40",
+    "@contember/react-repeater": "2.0.0-alpha.40",
+    "@contember/react-utils": "2.0.0-alpha.40",
+    "@radix-ui/primitive": "^1.1.0",
     "@radix-ui/react-slot": "^1.1.0"
   },
   "peerDependencies": {

package/src/components/Block.tsx

@@ -1,13 +1,41 @@
 import { BindingError, Component } from '@contember/react-binding'
 import { ReactNode } from 'react'
 
+/**
+ * Props for the {@link Block} component.
+ */
 export interface BlockProps {
+	/**
+	 * The content of the block.
+	 */
 	children: ReactNode
+	/**
+	 * Identifier of the block.
+	 */
 	name: string
+	/**
+	 * Optional label for the block.
+	 */
 	label?: ReactNode
+	/**
+	 * Optional form for the block.
+	 */
 	form?: ReactNode
 }
 
+/**
+ * Represents individual blocks within a block repeater.
+ *
+ * ## Props {@link BlockProps}
+ * - name, children, ?label, ?form
+ *
+ * ## Example
+ * ```tsx
+ * <Block name="text" label="Text">
+ *     <Field field="content" />
+ * </Block>
+ * ```
+ */
 export const Block = Component<BlockProps>(props => {
 	throw new BindingError('"Block" component is not supposed to be rendered.')
 }, ({ label, children, form }) => {

package/src/components/BlockRepeater.tsx

@@ -4,13 +4,42 @@ import { useState } from 'react'
 import { extractBlocks } from '../internal/helpers/staticAnalyzer'
 import { BlockRepeaterConfigContext } from '../contexts'
 
+/**
+ * Props for the {@link BlockRepeater} component.
+ */
 export type BlockRepeaterProps =
 	& {
+		/**
+		 * A field that is used to determine the order of the entities.
+		 */
 		sortableBy: RepeaterProps['sortableBy']
+
+		/**
+		 * Discrimination field is a field that is used to determine which block should be rendered for a given entity.
+		 */
 		discriminationField: SugaredRelativeSingleField['field']
 	}
 	& RepeaterProps
 
+/**
+ * A repeater component that renders different blocks based on the value of a discrimination field.
+ * This is headless component that does not impose any UI. Check DefaultBlockRepeater in UI library for a styled version.
+ *
+ * ## Props {@link BlockRepeaterProps}
+ * - field or entities, sortableBy, discriminationField, children
+ *
+ * ## Example
+ * ```tsx
+ * <BlockRepeater field="blocks" discriminationField="type" sortableBy="order">
+ *     <Block name="text" label="Text">
+ *         <Field field="content" />
+ *     </Block>
+ *     <Block name="image" label="Image">
+ *         <ImageField field="image" />
+ *     </Block>
+ * </BlockRepeater>
+ * ```
+ */
 export const BlockRepeater = Component<BlockRepeaterProps>(({ children, ...props }, env) => {
 	const [blocks] = useState(() => extractBlocks(children, env))
 	if (Object.keys(blocks).length === 0) {

package/src/components/BlockRepeaterAddItemTrigger.tsx

@@ -1,23 +1,66 @@
 import { Slot } from '@radix-ui/react-slot'
 import { useBlockRepeaterConfig } from '../contexts'
-import React, { ReactElement, useMemo } from 'react'
+import React, { ReactElement, useCallback, useMemo } from 'react'
 import { EntityAccessor } from '@contember/react-binding'
 import { RepeaterAddItemIndex, useRepeaterMethods } from '@contember/react-repeater'
+import { composeEventHandlers } from '@radix-ui/primitive'
 
+
+const SlotType = Slot as React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & React.RefAttributes<HTMLButtonElement>>
+
+/**
+ * Props for the {@link BlockRepeaterAddItemTrigger} component.
+ */
 export interface BlockRepeaterAddItemTriggerProps {
-	children: ReactElement
+
+	/**
+	 * The type of the item to add.
+	 */
 	type: string
+
+	/**
+	 * The index at which to add the item.
+	 * Can be one of:
+	 *  - number: Adds the item at the specified index.
+	 *  - `'first'`: Adds the item at the beginning.
+	 *  - undefined or `'last'`: Adds the item at the end.
+	 */
 	index?: RepeaterAddItemIndex
+
+	/**
+	 * A function to preprocess the entity.
+	 */
 	preprocess?: EntityAccessor.BatchUpdatesHandler
+
+	/**
+	 * The button element.
+	 */
+	children: ReactElement
 }
 
+/**
+ * A trigger component for adding item of given type to a block repeater.
+ *
+ * ## Props {@link BlockRepeaterAddItemTriggerProps}
+ * - type, ?index, ?preprocess, children
+ *
+ * ## Example
+ * ```tsx
+ * <BlockRepeaterAddItemTrigger type="image" index="first">
+ *     <button>Add Image</button>
+ * </BlockRepeaterAddItemTrigger>
+ * ```
+ */
 export const BlockRepeaterAddItemTrigger = ({ preprocess, index, type, ...props }: BlockRepeaterAddItemTriggerProps) => {
 	const { discriminatedBy } = useBlockRepeaterConfig()
 
 	const { addItem } = useRepeaterMethods()
-	const onClick = useMemo(() => () => addItem?.(index, it => {
+	const doAddItem = useCallback(() => addItem(index, (it, options) => {
 		it().getField(discriminatedBy).updateValue(type)
-	}), [addItem, discriminatedBy, index, type])
+		preprocess?.(it, options)
+	}), [addItem, discriminatedBy, index, preprocess, type])
+
+	const { onClick, ...otherProps } = props as React.ButtonHTMLAttributes<HTMLButtonElement>
 
-	return <Slot onClick={onClick} {...props} />
+	return <SlotType onClick={composeEventHandlers(onClick, doAddItem)} {...otherProps} />
 }

package/src/contexts.ts

@@ -8,4 +8,8 @@ const BlockRepeaterConfigContext_ = createRequiredContext<{
 }>('BlockRepeaterConfigContext')
 /** @internal */
 export const BlockRepeaterConfigContext = BlockRepeaterConfigContext_[0]
+
+/**
+ * Returns configuration of the block repeater (discrimination field and blocks map).
+ */
 export const useBlockRepeaterConfig = BlockRepeaterConfigContext_[1]

package/src/hooks/useBlockRepeaterCurrentBlock.ts

@@ -1,7 +1,11 @@
 import { useEntity } from '@contember/react-binding'
 import { useBlockRepeaterConfig } from '../contexts'
+import { BlockProps } from '../components'
 
-export const useBlockRepeaterCurrentBlock = () => {
+/**
+ * Returns the current block props (see {@link BlockProps}).
+ */
+export const useBlockRepeaterCurrentBlock = (): BlockProps | undefined => {
 	const entity = useEntity()
 	const { discriminatedBy, blocks } = useBlockRepeaterConfig()
 	const field = entity.getField<string>(discriminatedBy).value