@editora/ui-sortable 0.1.6 → 0.1.7

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.
Files changed (2) hide show
  1. package/README.md +200 -195
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,77 +1,93 @@
1
- # @editora/ui-sortable
2
-
3
- [![Version](https://img.shields.io/npm/v/@editora/ui-sortable)](https://www.npmjs.com/package/@editora/ui-sortable)
4
- [![License](https://img.shields.io/npm/l/@editora/ui-sortable)](https://github.com/ajaykr089/Editora/blob/main/LICENSE)
5
- [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
6
- [![Size](https://img.shields.io/bundlephobia/minzip/@editora/ui-sortable)](https://bundlephobia.com/package/@editora/ui-sortable)
7
-
8
- > [!IMPORTANT]
9
- > **Broader docs and examples:** https://editora-ecosystem.netlify.app/docs/ui-react/interactive/sortable
10
-
11
- Standalone package for the Editora sortable web component.
12
-
13
- `@editora/ui-sortable` is the smallest way to ship `<ui-sortable>` without importing the full `@editora/ui-core` catalog. It supports:
14
- - single-list reordering
15
- - multi-list transfer
16
- - nesting and hierarchy
17
- - multi-selection
18
- - keyboard-accessible drag and drop
19
- - indicator or container-style dropzones
20
- - an optional React wrapper via `@editora/ui-sortable/react`
21
-
22
- ## Installation
1
+ <h1 align="center">@editora/ui-sortable</h1>
2
+
3
+ <p align="center">
4
+ Drag-and-drop lists and boards as one web component, <code>&lt;ui-sortable&gt;</code>: reorder within a list, move
5
+ between lists, nest, clone and select several items, with full keyboard support. A small React wrapper is included.
6
+ </p>
7
+
8
+ <p align="center">
9
+ <a href="https://www.npmjs.com/package/@editora/ui-sortable"><img src="https://img.shields.io/npm/v/@editora/ui-sortable.svg" alt="npm version"></a>
10
+ <a href="https://www.npmjs.com/package/@editora/ui-sortable"><img src="https://img.shields.io/npm/dm/@editora/ui-sortable.svg" alt="npm downloads"></a>
11
+ <a href="https://github.com/ajaykr089/Editora/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@editora/ui-sortable.svg" alt="license"></a>
12
+ <a href="https://www.npmjs.com/package/@editora/ui-sortable"><img src="https://img.shields.io/npm/types/@editora/ui-sortable.svg" alt="TypeScript types included"></a>
13
+ </p>
14
+
15
+ <p align="center">
16
+ <a href="https://editora-ecosystem.netlify.app/docs/ui-react/interactive/sortable">Docs and examples</a> ·
17
+ <a href="https://editora-ecosystem-storybook.netlify.app/">Storybook</a> ·
18
+ <a href="https://github.com/ajaykr089/Editora">GitHub</a>
19
+ </p>
20
+
21
+ <p align="center">
22
+ <img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/ui-sortable/docs/images/board.png" alt="A board with four lists: Templates, Backlog with a nested item, In Progress and Done, each holding draggable cards with a drag handle" width="900">
23
+ </p>
24
+
25
+ ## Features
26
+
27
+ - **One component, many layouts.** A single list, several lists side by side (a board), horizontal lists, nested
28
+ hierarchies.
29
+ - **Reorder, transfer, nest and clone.** Drop an item between others, into another list, inside another item, or drag
30
+ a copy out of a template list.
31
+ - **Multi-selection**: select several items and move them together.
32
+ - **Keyboard and screen readers.** Space lifts the focused item, the arrow keys choose the place, Space drops it, and
33
+ the move is announced.
34
+ - **Persistence built in**: a `persist-request` event with the new positions, and a `persistKey` that keeps the positions across reloads.
35
+ - **Small.** The component is 17 KB gzipped (19 KB with the React wrapper), against about 490 KB for the whole
36
+ [`@editora/ui-core`](https://www.npmjs.com/package/@editora/ui-core) catalog it comes from.
37
+ - Custom item, list-header and empty-state rendering in React.
38
+
39
+ ## Install
23
40
 
24
41
  ```bash
25
42
  npm install @editora/ui-sortable
26
43
  ```
27
44
 
28
- If you want the React wrapper entry, also install React peer dependencies:
29
-
30
- ```bash
31
- npm install react react-dom
32
- ```
33
-
34
- Or install the standalone React-ready setup in one step:
35
-
36
- ```bash
37
- npm install @editora/ui-sortable react react-dom
38
- ```
45
+ For the React wrapper, React is a peer dependency: `npm install @editora/ui-sortable react react-dom`.
39
46
 
40
- ## Quick Start
47
+ ## Quick start
41
48
 
42
- Import the package once to register the custom element:
49
+ Import the package once to register the element, then give it `lists` and `items`:
43
50
 
44
- ```ts
45
- import '@editora/ui-sortable';
46
- ```
51
+ ```html
52
+ <script type="importmap">
53
+ {
54
+ "imports": {
55
+ "@editora/ui-sortable": "https://cdn.jsdelivr.net/npm/@editora/ui-sortable/dist/index.esm.js",
56
+ "@editora/ui-core/sortable": "https://cdn.jsdelivr.net/npm/@editora/ui-core/dist/sortable.esm.js"
57
+ }
58
+ }
59
+ </script>
60
+ <ui-sortable></ui-sortable>
47
61
 
48
- Then bind lists and items:
62
+ <script type="module">
63
+ import '@editora/ui-sortable';
49
64
 
50
- ```ts
51
- import '@editora/ui-sortable';
65
+ const sortable = document.querySelector('ui-sortable');
52
66
 
53
- const sortable = document.querySelector('ui-sortable');
67
+ sortable.lists = [
68
+ { id: 'backlog', label: 'Backlog' },
69
+ { id: 'in-progress', label: 'In Progress' },
70
+ { id: 'done', label: 'Done' }
71
+ ];
54
72
 
55
- sortable.lists = [
56
- { id: 'backlog', label: 'Backlog' },
57
- { id: 'in-progress', label: 'In Progress' },
58
- { id: 'done', label: 'Done' }
59
- ];
73
+ sortable.items = [
74
+ { id: 'story-1', label: 'Audit onboarding', listId: 'backlog' },
75
+ { id: 'story-2', label: 'Ship release notes', listId: 'in-progress' },
76
+ { id: 'story-3', label: 'Review handoff', listId: 'done' }
77
+ ];
60
78
 
61
- sortable.items = [
62
- { id: 'story-1', label: 'Audit onboarding', listId: 'backlog' },
63
- { id: 'story-2', label: 'Ship release notes', listId: 'in-progress' },
64
- { id: 'story-3', label: 'Review handoff', listId: 'done' }
65
- ];
79
+ sortable.addEventListener('change', (event) => console.log('order', event.detail.items));
80
+ </script>
66
81
  ```
67
82
 
68
- ```html
69
- <ui-sortable></ui-sortable>
70
- ```
83
+ <p align="center">
84
+ <img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/ui-sortable/docs/images/quick-start.png" alt="Three lists, Backlog, In Progress and Done, each with one card" width="900">
85
+ </p>
71
86
 
72
- ## React Wrapper
87
+ The element does not move your data: it fires `change` with the new `items`, and you store them. With a bundler, drop the
88
+ import map and `import '@editora/ui-sortable'`; without one, the import map above is all it needs.
73
89
 
74
- The package also exposes a standalone React wrapper:
90
+ ## React
75
91
 
76
92
  ```tsx
77
93
  import { Sortable, type SortableItem, type SortableList } from '@editora/ui-sortable/react';
@@ -86,7 +102,7 @@ const items: SortableItem[] = [
86
102
  { id: 'story-2', label: 'Ship release notes', listId: 'done' }
87
103
  ];
88
104
 
89
- export function Example() {
105
+ export default function Example() {
90
106
  return (
91
107
  <Sortable
92
108
  lists={lists}
@@ -100,19 +116,12 @@ export function Example() {
100
116
  }
101
117
  ```
102
118
 
103
- Use `@editora/ui-sortable/react` when you want the sortable wrapper only, without taking the rest of `@editora/ui-react`.
104
-
105
- If you are using Next.js, App Router, or another SSR/RSC framework, import `@editora/ui-sortable/react` from a client component because it registers the custom element in the browser runtime.
106
-
107
- ```tsx
108
- 'use client';
109
-
110
- import { Sortable } from '@editora/ui-sortable/react';
111
- ```
119
+ `@editora/ui-sortable/react` is the wrapper on its own, without the rest of `@editora/ui-react`.
112
120
 
113
- ## React Examples
121
+ ### A controlled board
114
122
 
115
- ### Controlled Board
123
+ Keep the items, and the selection, in state. This board has a template list that clones what you drag out of it, a
124
+ horizontal list, a nested item and a `persistKey` that remembers the positions:
116
125
 
117
126
  ```tsx
118
127
  import * as React from 'react';
@@ -132,7 +141,7 @@ const initialItems: SortableItem[] = [
132
141
  { id: 'review', label: 'Design review', listId: 'active' }
133
142
  ];
134
143
 
135
- export function ReleaseBoard() {
144
+ export default function ReleaseBoard() {
136
145
  const [items, setItems] = React.useState(initialItems);
137
146
  const [selection, setSelection] = React.useState<string[]>(['epic']);
138
147
 
@@ -152,7 +161,13 @@ export function ReleaseBoard() {
152
161
  }
153
162
  ```
154
163
 
155
- ### Flat List Sorting
164
+ <p align="center">
165
+ <img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/ui-sortable/docs/images/dragging.png" alt="The board while an item is dragged: a dashed drop preview shows where the card will land, and a Moving item label follows the pointer" width="900">
166
+ </p>
167
+
168
+ ### A flat list
169
+
170
+ For a single list that only reorders, turn nesting off:
156
171
 
157
172
  ```tsx
158
173
  import * as React from 'react';
@@ -168,7 +183,7 @@ const initialItems: SortableItem[] = [
168
183
  { id: 'seo', label: 'SEO metadata', listId: 'queue' }
169
184
  ];
170
185
 
171
- export function FlatSortableQueue() {
186
+ export default function FlatSortableQueue() {
172
187
  const [items, setItems] = React.useState(initialItems);
173
188
 
174
189
  return (
@@ -182,153 +197,143 @@ export function FlatSortableQueue() {
182
197
  }
183
198
  ```
184
199
 
185
- ### Clone Library
186
-
187
- ```tsx
188
- import { Sortable, type SortableItem, type SortableList } from '@editora/ui-sortable/react';
189
-
190
- const lists: SortableList[] = [
191
- { id: 'library', label: 'Template Library', cloneOnDrag: true },
192
- { id: 'campaign', label: 'Campaign Plan' }
193
- ];
194
-
195
- const items: SortableItem[] = [
196
- { id: 'press-kit', label: 'Press kit template', listId: 'library', cloneOnDrag: true },
197
- { id: 'email-series', label: 'Lifecycle email series', listId: 'library', cloneOnDrag: true },
198
- { id: 'owner-sync', label: 'Owner sync', listId: 'campaign' }
199
- ];
200
-
201
- export function CloneLibraryExample() {
202
- return <Sortable lists={lists} items={items} />;
203
- }
204
- ```
205
-
206
- ### Container Dropzones
207
-
208
- ```tsx
209
- <Sortable
210
- lists={lists}
211
- items={items}
212
- dropzoneStyle="container"
213
- />
214
- ```
215
-
216
- ### Custom Item Rendering
217
-
218
- ```tsx
219
- <Sortable
220
- lists={lists}
221
- items={items}
222
- selection={selection}
223
- onItemsChange={setItems}
224
- renderItem={(item, context) => (
225
- <div style={{ display: 'grid', gap: 8 }}>
226
- <div style={{ display: 'flex', justifyContent: 'space-between', gap: 12 }}>
227
- <strong>{item.label}</strong>
228
- <span>{context.selected ? 'Selected' : 'Ready'}</span>
229
- </div>
230
- {item.description && <div>{item.description}</div>}
231
- <small>{context.list?.label}</small>
232
- </div>
233
- )}
234
- />
235
- ```
236
-
237
- ### Custom List Headers And Empty States
200
+ ### Your own markup
238
201
 
239
- ```tsx
240
- <Sortable
241
- lists={lists}
242
- items={items}
243
- renderListHeader={(list, context) => (
244
- <div style={{ display: 'flex', justifyContent: 'space-between', gap: 12 }}>
245
- <strong>{list.label}</strong>
246
- <span>{context.itemCount} items</span>
247
- </div>
248
- )}
249
- renderEmptyState={(list) => (
250
- <div>
251
- No items in {list.label} yet. Drag something here to get started.
252
- </div>
253
- )}
254
- />
255
- ```
256
-
257
- ### Nested Hierarchy
202
+ `renderItem`, `renderListHeader` and `renderEmptyState` replace the default item, list header and empty message. The
203
+ context says whether the item is selected, how many items a list holds, and so on:
258
204
 
259
205
  ```tsx
206
+ import * as React from 'react';
260
207
  import { Sortable, type SortableItem, type SortableList } from '@editora/ui-sortable/react';
261
208
 
262
209
  const lists: SortableList[] = [
263
- { id: 'roadmap', label: 'Roadmap' }
210
+ { id: 'todo', label: 'To do' },
211
+ { id: 'done', label: 'Done' }
264
212
  ];
265
213
 
266
- const items: SortableItem[] = [
267
- { id: 'initiative', label: 'Reader retention initiative', listId: 'roadmap' },
268
- { id: 'survey', label: 'Audience survey', listId: 'roadmap', parentId: 'initiative' },
269
- { id: 'experiment', label: 'Paywall experiment', listId: 'roadmap' }
214
+ const initialItems: SortableItem[] = [
215
+ { id: 'brief', label: 'Write the brief', description: 'One page, with the audience.', listId: 'todo' },
216
+ { id: 'review', label: 'Legal review', listId: 'todo' }
270
217
  ];
271
218
 
272
- export function NestedHierarchyExample() {
273
- return <Sortable lists={lists} items={items} />;
219
+ export default function CustomRendering() {
220
+ const [items, setItems] = React.useState(initialItems);
221
+ const [selection, setSelection] = React.useState<string[]>(['brief']);
222
+
223
+ return (
224
+ <Sortable
225
+ lists={lists}
226
+ items={items}
227
+ selection={selection}
228
+ onItemsChange={setItems}
229
+ onSelectionChange={(detail) => setSelection(detail.selection)}
230
+ renderItem={(item, context) => (
231
+ <div style={{ display: 'grid', gap: 8 }}>
232
+ <div style={{ display: 'flex', justifyContent: 'space-between', gap: 12 }}>
233
+ <strong>{item.label}</strong>
234
+ <span>{context.selected ? 'Selected' : 'Ready'}</span>
235
+ </div>
236
+ {item.description && <div>{item.description}</div>}
237
+ <small>{context.list?.label}</small>
238
+ </div>
239
+ )}
240
+ renderListHeader={(list, context) => (
241
+ <div style={{ display: 'flex', justifyContent: 'space-between', gap: 12 }}>
242
+ <strong>{list.label}</strong>
243
+ <span>{context.itemCount} items</span>
244
+ </div>
245
+ )}
246
+ renderEmptyState={(list) => (
247
+ <div>
248
+ No items in {list.label} yet. Drag something here to get started.
249
+ </div>
250
+ )}
251
+ />
252
+ );
274
253
  }
275
254
  ```
276
255
 
277
- For broader usage patterns, Storybook-style variations, and the full prop reference, use the Editora docs:
278
-
279
- - https://editora-ecosystem.netlify.app/docs/ui-react/interactive/sortable
256
+ <p align="center">
257
+ <img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/ui-sortable/docs/images/custom.png" alt="Two lists with custom markup: a header showing the item count, cards showing Selected or Ready, and a custom message in the empty list" width="900">
258
+ </p>
259
+
260
+ ## Items and lists
261
+
262
+ | Item field | |
263
+ | --- | --- |
264
+ | `id`, `label`, `listId` | Required: the item's id, its text and the list it is in. |
265
+ | `parentId` | The id of the item this one is nested under. |
266
+ | `description` | A second line of text. |
267
+ | `cloneOnDrag` | Dragging this item leaves it where it is and drops a copy. |
268
+ | `disabled`, `dragDisabled`, `hidden` | Disable the item, stop it being dragged, or hide it. |
269
+
270
+ | List field | |
271
+ | --- | --- |
272
+ | `id`, `label` | Required. |
273
+ | `description`, `emptyLabel` | A line under the title, and the text of the empty state. |
274
+ | `orientation` | `'vertical'` (the default) or `'horizontal'`. |
275
+ | `cloneOnDrag` | Items dragged out of this list are copied. |
276
+ | `disabled` | Turn the list off. |
277
+
278
+ ## Options
279
+
280
+ | React prop | Attribute | |
281
+ | --- | --- | --- |
282
+ | `lists`, `items` | `lists`, `items` | The data. In HTML, set them as properties or as JSON attributes. |
283
+ | `selection` | `selection` | The selected item ids. |
284
+ | `allowNesting` | `allow-nesting` | Allow dropping an item inside another. |
285
+ | `dropzoneStyle` | `dropzone-style` | `indicator` (an insertion rail, the default) or `container` (the whole list highlights). |
286
+ | `dropIndicatorVisibility` | `drop-indicator-visibility` | `active` or `always`. |
287
+ | `dragPreviewSize` | `drag-preview-size` | `match-item` or `compact`. |
288
+ | `dragHandleMode` | `drag-handle-mode` | `handle` (drag by the grip) or `item` (drag anywhere on the card). |
289
+ | `dragHandleSelector` | `drag-handle-selector` | A selector for your own drag handle. |
290
+ | `persistKey` | `persist-key` | Keep where each item is in `localStorage` under this key, and restore it on load. |
291
+ | `filterQuery`, `sort`, `allowFilteredDrag` | `filter-query`, `sort`, `allow-filtered-drag` | Filter the items, sort them (`manual` or `label`), and allow dragging while filtered. |
292
+ | `showSelectionBadge` | `show-selection-badge` | Show the *Selected* badge on selected items. |
293
+ | `disabled` | `disabled` | Turn the whole component off. |
294
+
295
+ The React wrapper also takes `itemRadius`, `handleRadius`, `listGap` and `itemSpacing` for the look.
280
296
 
281
- ## Dropzone Styles
282
-
283
- Use the default insertion rails:
297
+ ## Events
284
298
 
285
- ```html
286
- <ui-sortable></ui-sortable>
287
- ```
299
+ | Event | React prop | `detail` |
300
+ | --- | --- | --- |
301
+ | `change` | `onChange` | `{ items, lists, selection, previousSelection, movedIds, source, operation, persistence }`. `source` is `pointer`, `keyboard`, `api` or `restore`; `operation` is `reorder`, `transfer`, `nest` or `clone`. |
302
+ | | `onItemsChange` | The new `items` array. |
303
+ | `selection-change` | `onSelectionChange` | `{ selection, previousSelection }` |
304
+ | `persist-request` | `onPersistRequest` | The same detail as `change`: `persistence.records` is `[{ id, listId, parentId, index }]`, ready to save. |
288
305
 
289
- Or switch to container-style dropzones:
306
+ ## Methods
290
307
 
291
- ```html
292
- <ui-sortable dropzone-style="container"></ui-sortable>
293
- ```
308
+ On the element (or a ref to it): `select(ids)`, `clearSelection()`, `moveSelection({ targetListId, beforeId?, parentId?, mode?, clone? })`,
309
+ `focusItem(id)`, `cancelDrag()` and `getPersistenceSnapshot()`.
294
310
 
295
- ## Common Attributes
311
+ ## Keyboard
296
312
 
297
- - `dropzone-style="indicator|container"`
298
- - `drop-indicator-visibility="active|always"`
299
- - `drag-preview-size="match-item|compact"`
300
- - `drag-handle-mode="handle|item"`
301
- - `allow-nesting`
302
- - `persist-key`
313
+ Focus an item, then press **Space** to lift it, the **arrow keys** to choose where it goes, and **Space** again to drop
314
+ it. The result is announced to screen readers ("Item reordered in Editorial Queue."), and a hint above the lists
315
+ explains the keys.
303
316
 
304
- ## Events
317
+ ## Types
305
318
 
306
- The component emits `CustomEvent`s such as:
307
- - `change`
308
- - `selection-change`
319
+ `@editora/ui-sortable` re-exports `UISortable`, `UISortableList`, `UISortableItem`, `UISortableChangeDetail` and
320
+ `UISortableDropzoneStyle`. `@editora/ui-sortable/react` exports `Sortable`, `SortableList`, `SortableItem`,
321
+ `SortableChangeDetail` and `SortableDropzoneStyle`.
309
322
 
310
- Each event provides structured detail payloads for the latest ordering or selection state.
323
+ ## Server rendering
311
324
 
312
- ## Type Exports
325
+ Both entries can be imported on the server: loading them does not touch the DOM, and the custom element is defined only
326
+ in the browser. On the server `Sortable` from `@editora/ui-sortable/react` renders an empty `<ui-sortable>` tag; the lists
327
+ and items are applied in the browser, once the element is defined and the component has mounted. A `'use client'` file
328
+ that renders it is still rendered on the server first (Next.js does this); that render produces the empty tag and does
329
+ not fail.
313
330
 
314
- The package also re-exports sortable types from `@editora/ui-core/sortable`, including:
315
- - `UISortable`
316
- - `UISortableList`
317
- - `UISortableItem`
318
- - `UISortableChangeDetail`
319
- - `UISortableDropzoneStyle`
331
+ ## Part of Editora
320
332
 
321
- The React subpath exports:
322
- - `Sortable`
323
- - `SortableList`
324
- - `SortableItem`
325
- - `SortableChangeDetail`
326
- - `SortableDropzoneStyle`
333
+ This is the sortable of [`@editora/ui-core`](https://www.npmjs.com/package/@editora/ui-core) as its own install. The same
334
+ component is also in [`@editora/ui-react`](https://www.npmjs.com/package/@editora/ui-react) and in the web components
335
+ catalog.
327
336
 
328
- ## Development
337
+ ## License
329
338
 
330
- ```bash
331
- cd packages/ui-sortable
332
- npm run build
333
- npm run test
334
- ```
339
+ MIT © [Ajay Kumar](https://github.com/ajaykr089)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@editora/ui-sortable",
3
- "version": "0.1.6",
3
+ "version": "0.1.7",
4
4
  "description": "Standalone install for the Editora sortable web component, with reordering, transfer, hierarchy, cloning, and keyboard-accessible drag and drop.",
5
5
  "homepage": "https://editora-ecosystem.netlify.app/docs/ui-react/interactive/sortable",
6
6
  "bugs": {
@@ -42,7 +42,7 @@
42
42
  "prepare": "npm run build"
43
43
  },
44
44
  "dependencies": {
45
- "@editora/ui-core": "^0.1.22"
45
+ "@editora/ui-core": "^0.1.23"
46
46
  },
47
47
  "peerDependencies": {
48
48
  "react": ">=16.8 <21",