@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 +19 -6
- package/dist/ReorderableList.d.ts +9 -2
- package/dist/ReorderableList.d.ts.map +1 -1
- package/dist/ReorderableList.js +85 -6
- package/dist/index.d.ts +5 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -3
- package/package.json +5 -5
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-
|
|
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
|
|
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
|
|
106
|
-
|
|
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(...)`
|
|
147
|
-
|
|
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
|
|
28
|
-
*
|
|
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
|
|
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"}
|
package/dist/ReorderableList.js
CHANGED
|
@@ -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
|
|
12
|
-
*
|
|
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),
|
|
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),
|
|
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: () =>
|
|
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
|
|
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(...)`
|
|
48
|
-
*
|
|
49
|
+
* through `t(...)` under `reorderableList.*`, translated by the
|
|
50
|
+
* `@molecule/app-locales-reorderable-list` companion bond.
|
|
49
51
|
*
|
|
50
52
|
* @module
|
|
51
53
|
*/
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA
|
|
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
|
|
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(...)`
|
|
48
|
-
*
|
|
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.
|
|
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.
|
|
43
|
-
"@molecule/app-ui": "1.
|
|
44
|
-
"@molecule/app-ui-react": "4.
|
|
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",
|