feat(conform-react): list.insert (#270)

docs/complex-structures.md

@@ -110,7 +110,7 @@ function Example() {
 }
 ```
 
-For information about modifying list (e.g. append / remove / reorder), see the [list intent](/docs/intent-button.md#list-intent) section.
+For information about modifying list (e.g. insert / remove / reorder), see the [list intent](/docs/intent-button.md#list-intent) section.
 
 ## Nested List
 

docs/intent-button.md

@@ -99,7 +99,7 @@ export default function Todos() {
         ))}
       </ul>
       <div>
-        <button {...list.append(tasks.name)}>Add task</button>
+        <button {...list.insert(tasks.name)}>Add task</button>
       </div>
       <button>Save</button>
     </form>
@@ -159,7 +159,7 @@ export default function Todos() {
         ))}
       </ul>
       <div>
-        <button {...list.append(tasks.name)} ref={buttonRef}>
+        <button {...list.insert(tasks.name)} ref={buttonRef}>
           Add task
         </button>
       </div>

examples/react-router/src/todos.tsx

@@ -74,7 +74,7 @@ export function Component() {
 					</button>
 				</p>
 			))}
-			<button {...list.append(tasks.name)}>Add task</button>
+			<button {...list.insert(tasks.name)}>Add task</button>
 			<hr />
 			<button>Save</button>
 		</Form>

examples/remix/app/routes/todos.tsx

@@ -76,7 +76,7 @@ export default function TodoForm() {
 					</button>
 				</p>
 			))}
-			<button {...list.append(tasks.name)}>Add task</button>
+			<button {...list.insert(tasks.name)}>Add task</button>
 			<hr />
 			<button>Save</button>
 		</Form>

packages/conform-dom/intent.ts

@@ -8,6 +8,7 @@ export interface IntentButtonProps {
 }
 
 export type ListIntentPayload<Schema = unknown> =
+	| { name: string; operation: 'insert'; defaultValue?: Schema; index?: number }
 	| { name: string; operation: 'prepend'; defaultValue?: Schema }
 	| { name: string; operation: 'append'; defaultValue?: Schema }
 	| { name: string; operation: 'replace'; defaultValue: Schema; index: number }
@@ -21,21 +22,34 @@ type ExtractListIntentPayload<Operation, Schema = unknown> = Pretty<
 	>
 >;
 
+type ListIntent<Operation> = {} extends ExtractListIntentPayload<Operation>
+	? <Schema>(
+			name: string,
+			payload?: ExtractListIntentPayload<Operation, Schema>,
+	  ) => IntentButtonProps
+	: <Schema>(
+			name: string,
+			payload: ExtractListIntentPayload<Operation, Schema>,
+	  ) => IntentButtonProps;
+
 /**
  * Helpers to configure an intent button for modifying a list
  *
  * @see https://conform.guide/api/react#list
  */
 export const list = new Proxy<{
-	[Operation in ListIntentPayload['operation']]: {} extends ExtractListIntentPayload<Operation>
-		? <Schema>(
-				name: string,
-				payload?: ExtractListIntentPayload<Operation, Schema>,
-		  ) => IntentButtonProps
-		: <Schema>(
-				name: string,
-				payload: ExtractListIntentPayload<Operation, Schema>,
-		  ) => IntentButtonProps;
+	/**
+	 * @deprecated You can use `insert` without specifying an index instead
+	 */
+	append: ListIntent<'append'>;
+	/**
+	 * @deprecated You can use `insert` with zero index instead
+	 */
+	prepend: ListIntent<'prepend'>;
+	insert: ListIntent<'insert'>;
+	replace: ListIntent<'replace'>;
+	remove: ListIntent<'remove'>;
+	reorder: ListIntent<'reorder'>;
 }>({} as any, {
 	get(_target, operation: any) {
 		return (name: string, payload = {}): IntentButtonProps => ({
@@ -94,6 +108,7 @@ export function requestIntent(
 	},
 ): void {
 	if (!form) {
+		// eslint-disable-next-line no-console
 		console.warn('No form element is provided');
 		return;
 	}
@@ -152,6 +167,9 @@ export function updateList<Schema>(
 		case 'append':
 			list.push(payload.defaultValue as any);
 			break;
+		case 'insert':
+			list.splice(payload.index ?? list.length, 0, payload.defaultValue as any);
+			break;
 		case 'replace':
 			list.splice(payload.index, 1, payload.defaultValue);
 			break;

packages/conform-react/README.md

@@ -270,7 +270,7 @@ function Example() {
       ))}
 
       {/* Setup a button that can append a new row with optional default value */}
-      <button {...list.append(items.name, { defaultValue: '' })}>add</button>
+      <button {...list.insert(items.name, { defaultValue: '' })}>add</button>
     </fieldset>
   );
 }
@@ -502,11 +502,11 @@ import { list } from '@conform-to/react';
 function Example() {
   return (
     <form>
-      {/* To append a new row with optional defaultValue */}
-      <button {...list.append('name', { defaultValue })}>Append</button>
-
-      {/* To prepend a new row with optional defaultValue */}
-      <button {...list.prepend('name', { defaultValue })}>Prepend</button>
+      {/*
+        To insert a new row with optional defaultValue at a given index.
+        If no index is given, then the element will be appended at the end of the list.
+      */}
+      <button {...list.insert('name', { index, defaultValue })}>Insert</button>
 
       {/* To remove a row by index */}
       <button {...list.remove('name', { index })}>Remove</button>

packages/conform-react/hooks.ts

@@ -712,6 +712,7 @@ export function useFieldList<Schema extends Array<any> | undefined>(
 				switch (intent.payload.operation) {
 					case 'append':
 					case 'prepend':
+					case 'insert':
 					case 'replace':
 						return updateList(list, {
 							...intent.payload,

playground/app/routes/simple-list.tsx

@@ -84,13 +84,13 @@ export default function SimpleList() {
 				<div className="flex flex-row gap-2">
 					<button
 						className="rounded-md border p-2 hover:border-black"
-						{...list.prepend(items.name)}
+						{...list.insert(items.name, { index: 0 })}
 					>
 						Insert top
 					</button>
 					<button
 						className="rounded-md border p-2 hover:border-black"
-						{...list.append(items.name)}
+						{...list.insert(items.name)}
 					>
 						Insert bottom
 					</button>

playwright.config.ts

@@ -40,6 +40,8 @@ const config: PlaywrightTestConfig = {
 
 		/* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
 		trace: 'on-first-retry',
+		/* Take screenshot on testrun failure. */
+		screenshot: 'only-on-failure',
 	},
 
 	/* Configure projects for major browsers */