@molecule/app-reorderable-list-react 4.0.0 → 4.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
3
3
  Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
4
4
  Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
5
5
  To change this document, edit the module-level JSDoc in src/index.ts.
6
- Generated: 2026-11-12T04:41:27.346Z
6
+ Generated: 2026-11-21T12:47:08.628Z
7
7
  -->
8
8
 
9
9
  # @molecule/app-reorderable-list-react
@@ -19,7 +19,9 @@ glyph; otherwise the whole row drags), `className?`.
19
19
 
20
20
  Reordering works with a mouse (HTML5 drag) AND the keyboard: every row has
21
21
  move-up/move-down buttons (`data-mol-id="reorderable-move-{up,down}-<id>"`),
22
- and a focused row responds to Alt+ArrowUp / Alt+ArrowDown.
22
+ and Alt+ArrowUp / Alt+ArrowDown on a focused move button reorders its row.
23
+ Focus follows the item: a move that disables the used button (the item
24
+ reached the top or the bottom) moves focus to the same row's other button.
23
25
 
24
26
  > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
25
27
  > It is written to be read by coding agents as much as by people, and is generated from this
@@ -102,8 +104,15 @@ the data; this component only renders + emits new order on `onReorder`.
102
104
 
103
105
  Use the optional `renderHandle` slot to limit drag to a specific
104
106
  element (e.g. a "≡" handle on the left). Every row also ships explicit
105
- move-up/move-down buttons and supports Alt+ArrowUp / Alt+ArrowDown on the
106
- focused row, so the list is fully reorderable without a mouse.
107
+ move-up/move-down buttons; Alt+ArrowUp / Alt+ArrowDown on a focused move
108
+ button reorders too, and focus follows the item: when a move disables the
109
+ button that was used (the item reached the top or the bottom), focus moves
110
+ to the same row's other button. The list is fully reorderable without a
111
+ mouse.
112
+
113
+ Each row renders its position ("Item 2 of 3") in a screen-reader-only span
114
+ that both of its move buttons reference through `aria-describedby`, so the
115
+ buttons announce where the item sits.
107
116
 
108
117
  ```typescript
109
118
  function ReorderableList<T>({
@@ -143,5 +152,9 @@ Peer dependencies:
143
152
  `<I18nProvider>` (for the control labels) or rendering throws.
144
153
  - Item `id`s must be unique — drop resolution matches by id.
145
154
  - Control labels ("Move up/down", "Drag to reorder", row position) render
146
- through `t(...)` with English defaults; no companion locale bond ships yet,
147
- so translate them by wiring a `reorderableList.*` bond when needed.
155
+ through `t(...)` under `reorderableList.*`, translated by the
156
+ `@molecule/app-locales-reorderable-list` companion bond.
157
+
158
+ ## Translations
159
+
160
+ Translation strings are provided by `@molecule/app-locales-reorderable-list`.
@@ -24,8 +24,15 @@ export interface ReorderableListProps<T> {
24
24
  *
25
25
  * Use the optional `renderHandle` slot to limit drag to a specific
26
26
  * element (e.g. a "≡" handle on the left). Every row also ships explicit
27
- * move-up/move-down buttons and supports Alt+ArrowUp / Alt+ArrowDown on the
28
- * focused row, so the list is fully reorderable without a mouse.
27
+ * move-up/move-down buttons; Alt+ArrowUp / Alt+ArrowDown on a focused move
28
+ * button reorders too, and focus follows the item: when a move disables the
29
+ * button that was used (the item reached the top or the bottom), focus moves
30
+ * to the same row's other button. The list is fully reorderable without a
31
+ * mouse.
32
+ *
33
+ * Each row renders its position ("Item 2 of 3") in a screen-reader-only span
34
+ * that both of its move buttons reference through `aria-describedby`, so the
35
+ * buttons announce where the item sits.
29
36
  * @param props - Component props (see {@link ReorderableListProps}).
30
37
  */
31
38
  export declare function ReorderableList<T>({ items, onReorder, renderItem, renderHandle, className, }: ReorderableListProps<T>): ReactElement;
@@ -1 +1 @@
1
- {"version":3,"file":"ReorderableList.d.ts","sourceRoot":"","sources":["../src/ReorderableList.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAM9E;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,CAAC,CAAA;CACR;AAED,+DAA+D;AAC/D,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,CAAA;IAC3B,6CAA6C;IAC7C,SAAS,EAAE,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAA;IAC/C,0DAA0D;IAC1D,UAAU,EAAE,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,KAAK,SAAS,CAAA;IACxE,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,SAAS,CAAA;IAC9B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,EACjC,KAAK,EACL,SAAS,EACT,UAAU,EACV,YAAY,EACZ,SAAS,GACV,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,YAAY,CAiKxC"}
1
+ {"version":3,"file":"ReorderableList.d.ts","sourceRoot":"","sources":["../src/ReorderableList.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAM9E;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,CAAC,CAAA;CACR;AAED,+DAA+D;AAC/D,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,CAAA;IAC3B,6CAA6C;IAC7C,SAAS,EAAE,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAA;IAC/C,0DAA0D;IAC1D,UAAU,EAAE,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,KAAK,SAAS,CAAA;IACxE,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,SAAS,CAAA;IAC9B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,EACjC,KAAK,EACL,SAAS,EACT,UAAU,EACV,YAAY,EACZ,SAAS,GACV,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,YAAY,CAyPxC"}
@@ -1,5 +1,5 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
- import { useState } from 'react';
2
+ import { useEffect, useId, useRef, useState } from 'react';
3
3
  import { useTranslation } from '@molecule/app-react';
4
4
  import { getClassMap } from '@molecule/app-ui';
5
5
  /**
@@ -8,8 +8,15 @@ import { getClassMap } from '@molecule/app-ui';
8
8
  *
9
9
  * Use the optional `renderHandle` slot to limit drag to a specific
10
10
  * element (e.g. a "≡" handle on the left). Every row also ships explicit
11
- * move-up/move-down buttons and supports Alt+ArrowUp / Alt+ArrowDown on the
12
- * focused row, so the list is fully reorderable without a mouse.
11
+ * move-up/move-down buttons; Alt+ArrowUp / Alt+ArrowDown on a focused move
12
+ * button reorders too, and focus follows the item: when a move disables the
13
+ * button that was used (the item reached the top or the bottom), focus moves
14
+ * to the same row's other button. The list is fully reorderable without a
15
+ * mouse.
16
+ *
17
+ * Each row renders its position ("Item 2 of 3") in a screen-reader-only span
18
+ * that both of its move buttons reference through `aria-describedby`, so the
19
+ * buttons announce where the item sits.
13
20
  * @param props - Component props (see {@link ReorderableListProps}).
14
21
  */
15
22
  export function ReorderableList({ items, onReorder, renderItem, renderHandle, className, }) {
@@ -17,6 +24,12 @@ export function ReorderableList({ items, onReorder, renderItem, renderHandle, cl
17
24
  const { t } = useTranslation();
18
25
  const [draggingId, setDraggingId] = useState(null);
19
26
  const [overId, setOverId] = useState(null);
27
+ /** The list's id prefix; each row's position span is `${baseId}-position-${index}`. */
28
+ const baseId = useId();
29
+ /** The rows' move buttons, keyed by item id — the focus effect's targets. */
30
+ const moveButtons = useRef(new Map());
31
+ /** The move whose focus settles once `items` changes: the item id and the button used. */
32
+ const focusRequest = useRef(null);
20
33
  /**
21
34
  * Moves the item at `index` by `delta` positions and emits the new order.
22
35
  * No-ops at the list boundaries. Shared by the move buttons and the
@@ -52,6 +65,71 @@ export function ReorderableList({ items, onReorder, renderItem, renderHandle, cl
52
65
  moveItem(index, 1);
53
66
  }
54
67
  }
68
+ /**
69
+ * Registers one move button under its item id (a `ref` callback), so the
70
+ * focus effect can reach either button of that row.
71
+ * @param id - The row's item id.
72
+ * @param button - Which button of the row this is.
73
+ * @returns The `ref` callback for the button.
74
+ */
75
+ function registerMoveButton(id, button) {
76
+ return (el) => {
77
+ const row = moveButtons.current.get(id) ?? { up: null, down: null };
78
+ row[button] = el;
79
+ moveButtons.current.set(id, row);
80
+ };
81
+ }
82
+ /**
83
+ * Moves the item with a move button, recording which button was used so the
84
+ * focus effect can settle focus after the new order lands.
85
+ * @param id - The moved item's id.
86
+ * @param index - Current position of the item to move.
87
+ * @param delta - -1 to move up, 1 to move down.
88
+ * @param button - The button the move came from.
89
+ */
90
+ function moveFromButton(id, index, delta, button) {
91
+ focusRequest.current = { id, button };
92
+ moveItem(index, delta);
93
+ }
94
+ /**
95
+ * Keyboard reordering for a focused move button: Alt+ArrowUp / Alt+ArrowDown
96
+ * move its item. A key that moves also records the button used, for the same
97
+ * focus settling a click gets.
98
+ * @param id - The row's item id.
99
+ * @param index - Current position of the row's item.
100
+ * @param button - Which button of the row this is.
101
+ * @param e - The keyboard event.
102
+ */
103
+ function onButtonKeyDown(id, index, button, e) {
104
+ if (e.altKey && (e.key === 'ArrowUp' || e.key === 'ArrowDown')) {
105
+ focusRequest.current = { id, button };
106
+ }
107
+ onItemKeyDown(index, e);
108
+ }
109
+ /**
110
+ * Focus settles after a move: when the button that was used is disabled by
111
+ * the new order (the item reached the top or the bottom), focus moves to the
112
+ * same row's other move button; otherwise it stays (the row is keyed by item
113
+ * id, so the focused button moves with its row). Runs after `items` changes
114
+ * and consumes the request the move recorded.
115
+ */
116
+ useEffect(() => {
117
+ const request = focusRequest.current;
118
+ focusRequest.current = null;
119
+ if (!request)
120
+ return;
121
+ const index = items.findIndex((item) => item.id === request.id);
122
+ if (index < 0)
123
+ return;
124
+ const row = moveButtons.current.get(request.id);
125
+ if (!row)
126
+ return;
127
+ const usedDisabled = request.button === 'up' ? index === 0 : index === items.length - 1;
128
+ if (!usedDisabled)
129
+ return;
130
+ const other = request.button === 'up' ? row.down : row.up;
131
+ other?.focus();
132
+ }, [items]);
55
133
  /**
56
134
  * Initiates a drag operation, storing the dragged item id in the transfer payload.
57
135
  * @param id
@@ -103,13 +181,14 @@ export function ReorderableList({ items, onReorder, renderItem, renderHandle, cl
103
181
  setDraggingId(null);
104
182
  setOverId(null);
105
183
  }
106
- return (_jsx("ul", { className: cm.cn(cm.stack(1), className), role: "list", children: items.map((item, index) => {
184
+ return (_jsx("ul", { className: cm.cn(cm.stack(1), className), children: items.map((item, index) => {
107
185
  const isDragging = draggingId === item.id;
108
186
  const isOver = overId === item.id && draggingId !== item.id;
187
+ const positionId = `${baseId}-position-${index}`;
109
188
  const position = t('reorderableList.position', { index: index + 1, total: items.length }, { defaultValue: 'Item {{index}} of {{total}}' });
110
- return (_jsxs("li", { draggable: !renderHandle, onDragStart: renderHandle ? undefined : (e) => onDragStart(item.id, e), onDragEnd: reset, onDragOver: (e) => onDragOver(item.id, e), onDrop: (e) => onDrop(item.id, e), onKeyDown: (e) => onItemKeyDown(index, e), tabIndex: 0, "aria-label": position, className: cm.cn(cm.flex({ align: 'center', gap: 'sm' })), style: {
189
+ return (_jsxs("li", { draggable: !renderHandle, onDragStart: renderHandle ? undefined : (e) => onDragStart(item.id, e), onDragEnd: reset, onDragOver: (e) => onDragOver(item.id, e), onDrop: (e) => onDrop(item.id, e), className: cm.cn(cm.flex({ align: 'center', gap: 'sm' })), style: {
111
190
  opacity: isDragging ? 0.4 : 1,
112
191
  borderTop: isOver ? '2px solid currentColor' : undefined,
113
- }, children: [renderHandle && (_jsx("span", { draggable: true, onDragStart: (e) => onDragStart(item.id, e), onDragEnd: reset, className: cm.cursorPointer, "aria-label": t('reorderableList.dragHandle', {}, { defaultValue: 'Drag to reorder' }), children: renderHandle() })), _jsx("div", { className: cm.flex1, children: renderItem(item, isDragging) }), _jsxs("div", { className: cm.cn(cm.flex({ align: 'center', gap: 'xs' })), children: [_jsx("button", { type: "button", "data-mol-id": `reorderable-move-up-${item.id}`, onClick: () => moveItem(index, -1), disabled: index === 0, "aria-label": t('reorderableList.moveUp', {}, { defaultValue: 'Move up' }), className: cm.cn(cm.cursorPointer, cm.sp('p', 1)), children: _jsx("span", { "aria-hidden": "true", children: "\u2191" }) }), _jsx("button", { type: "button", "data-mol-id": `reorderable-move-down-${item.id}`, onClick: () => moveItem(index, 1), disabled: index === items.length - 1, "aria-label": t('reorderableList.moveDown', {}, { defaultValue: 'Move down' }), className: cm.cn(cm.cursorPointer, cm.sp('p', 1)), children: _jsx("span", { "aria-hidden": "true", children: "\u2193" }) })] })] }, item.id));
192
+ }, children: [renderHandle && (_jsx("span", { draggable: true, onDragStart: (e) => onDragStart(item.id, e), onDragEnd: reset, className: cm.cursorPointer, "aria-label": t('reorderableList.dragHandle', {}, { defaultValue: 'Drag to reorder' }), children: renderHandle() })), _jsx("div", { className: cm.flex1, children: renderItem(item, isDragging) }), _jsxs("div", { className: cm.cn(cm.flex({ align: 'center', gap: 'xs' })), children: [_jsx("button", { type: "button", "data-mol-id": `reorderable-move-up-${item.id}`, ref: registerMoveButton(item.id, 'up'), onClick: () => moveFromButton(item.id, index, -1, 'up'), onKeyDown: (e) => onButtonKeyDown(item.id, index, 'up', e), disabled: index === 0, "aria-label": t('reorderableList.moveUp', {}, { defaultValue: 'Move up' }), "aria-describedby": positionId, className: cm.cn(cm.cursorPointer, cm.sp('p', 1)), children: _jsx("span", { "aria-hidden": "true", children: "\u2191" }) }), _jsx("button", { type: "button", "data-mol-id": `reorderable-move-down-${item.id}`, ref: registerMoveButton(item.id, 'down'), onClick: () => moveFromButton(item.id, index, 1, 'down'), onKeyDown: (e) => onButtonKeyDown(item.id, index, 'down', e), disabled: index === items.length - 1, "aria-label": t('reorderableList.moveDown', {}, { defaultValue: 'Move down' }), "aria-describedby": positionId, className: cm.cn(cm.cursorPointer, cm.sp('p', 1)), children: _jsx("span", { "aria-hidden": "true", children: "\u2193" }) })] }), _jsx("span", { id: positionId, className: cm.srOnly, children: position })] }, item.id));
114
193
  }) }));
115
194
  }
package/dist/index.d.ts CHANGED
@@ -10,7 +10,9 @@
10
10
  *
11
11
  * Reordering works with a mouse (HTML5 drag) AND the keyboard: every row has
12
12
  * move-up/move-down buttons (`data-mol-id="reorderable-move-{up,down}-<id>"`),
13
- * and a focused row responds to Alt+ArrowUp / Alt+ArrowDown.
13
+ * and Alt+ArrowUp / Alt+ArrowDown on a focused move button reorders its row.
14
+ * Focus follows the item: a move that disables the used button (the item
15
+ * reached the top or the bottom) moves focus to the same row's other button.
14
16
  *
15
17
  * @example
16
18
  * ```tsx
@@ -44,8 +46,8 @@
44
46
  * `<I18nProvider>` (for the control labels) or rendering throws.
45
47
  * - Item `id`s must be unique — drop resolution matches by id.
46
48
  * - Control labels ("Move up/down", "Drag to reorder", row position) render
47
- * through `t(...)` with English defaults; no companion locale bond ships yet,
48
- * so translate them by wiring a `reorderableList.*` bond when needed.
49
+ * through `t(...)` under `reorderableList.*`, translated by the
50
+ * `@molecule/app-locales-reorderable-list` companion bond.
49
51
  *
50
52
  * @module
51
53
  */
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,cAAc,sBAAsB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,cAAc,sBAAsB,CAAA"}
package/dist/index.js CHANGED
@@ -10,7 +10,9 @@
10
10
  *
11
11
  * Reordering works with a mouse (HTML5 drag) AND the keyboard: every row has
12
12
  * move-up/move-down buttons (`data-mol-id="reorderable-move-{up,down}-<id>"`),
13
- * and a focused row responds to Alt+ArrowUp / Alt+ArrowDown.
13
+ * and Alt+ArrowUp / Alt+ArrowDown on a focused move button reorders its row.
14
+ * Focus follows the item: a move that disables the used button (the item
15
+ * reached the top or the bottom) moves focus to the same row's other button.
14
16
  *
15
17
  * @example
16
18
  * ```tsx
@@ -44,8 +46,8 @@
44
46
  * `<I18nProvider>` (for the control labels) or rendering throws.
45
47
  * - Item `id`s must be unique — drop resolution matches by id.
46
48
  * - Control labels ("Move up/down", "Drag to reorder", row position) render
47
- * through `t(...)` with English defaults; no companion locale bond ships yet,
48
- * so translate them by wiring a `reorderableList.*` bond when needed.
49
+ * through `t(...)` under `reorderableList.*`, translated by the
50
+ * `@molecule/app-locales-reorderable-list` companion bond.
49
51
  *
50
52
  * @module
51
53
  */
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@molecule/app-reorderable-list-react",
3
- "version": "4.0.0",
4
- "description": "Vertical drag-handle reorder list with onReorder callback",
3
+ "version": "4.0.2",
4
+ "description": "Vertical drag-handle reorder list with onReorder callback (HTML5 drag — mouse/pointer only, no touch)",
5
5
  "homepage": "https://www.molecule.dev/packages/app-reorderable-list-react",
6
6
  "type": "module",
7
7
  "main": "dist/index.js",
@@ -39,9 +39,9 @@
39
39
  "react": "^18.0.0 || ^19.0.0"
40
40
  },
41
41
  "devDependencies": {
42
- "@molecule/app-react": "4.0.0",
43
- "@molecule/app-ui": "1.3.9",
44
- "@molecule/app-ui-react": "4.0.0",
42
+ "@molecule/app-react": "4.10.1",
43
+ "@molecule/app-ui": "1.5.0",
44
+ "@molecule/app-ui-react": "4.2.0",
45
45
  "@testing-library/react": "16.3.3",
46
46
  "@types/node": "26.6.5",
47
47
  "@types/react": "19.3.0",