docs: clarify control-flow callback shapes

Document the mode-specific callback signatures for mapArray and For so generated API docs match runtime behavior.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ryansolid

.changeset/document-control-flow-callback-shapes.md

@@ -0,0 +1,6 @@
+---
+"@solidjs/signals": patch
+"solid-js": patch
+---
+
+Document the mode-specific callback shapes for mapArray and For.

packages/solid-signals/src/map.ts

@@ -16,9 +16,14 @@ export type Maybe<T> = T | void | null | undefined | false;
 
 /**
  * Reactively maps an array, reusing the previously-mapped value for unchanged
- * items. By default, the callback receives the raw row value and a reactive
- * index accessor. Index-owned and custom-keyed rows receive accessors where
- * the row can be preserved while that argument changes.
+ * items.
+ *
+ * The callback shape follows the keying mode:
+ * - default / `keyed: true` receives `(item, index)` where `item` is the raw
+ *   row value and `index` is an accessor.
+ * - `keyed: false` receives `(item, index)` where `item` is an accessor and
+ *   `index` is a stable number.
+ * - `keyed: item => key` receives accessors for both arguments.
  *
  * This is the underlying helper that powers `<For>`. App code should use
  * `<For>` directly; reach for `mapArray` when implementing custom list

packages/solid/src/client/flow.ts

@@ -35,6 +35,13 @@ const narrowedError = (name: string) =>
  * Receives a map function as its child and returns a JSX element for each
  * list item; if the list is empty, an optional `fallback` is rendered instead.
  *
+ * The child callback shape follows the keying mode:
+ * - default / `keyed={true}` receives `(item, index)` where `item` is the raw
+ *   row value and `index` is an accessor.
+ * - `keyed={false}` receives `(item, index)` where `item` is an accessor and
+ *   `index` is a stable number.
+ * - `keyed={(item) => key}` receives accessors for both arguments.
+ *
  * @example
  * ```tsx
  * <For each={items} fallback={<div>No items</div>}>

packages/solid/src/server/flow.ts

@@ -37,7 +37,6 @@ type ForOptions<T> = {
 
 /**
  * Creates a list of elements from a list
- *
  * @description https://docs.solidjs.com/reference/components/for
  */
 export function For<T extends readonly any[], U extends SolidElement>(props: {