@ixfx/components 0.13.0 → 0.13.2

package/docs-user/flat-list.md

@@ -28,11 +28,16 @@ list.addEventListener('flat-list-activate', ({ detail }) => open(detail.node));
 | `selectionMode` / `selection-mode` | | `'single'` | As `ixfx-vertical-list` |
 | `interactionMode` / `interaction-mode` | | `'standard'` | As `ixfx-vertical-list` |
 | `itemWrap`, `searchModes`, `itemsDraggable` | | | Passed to the inner list |
+| `itemsDroppable` / `items-droppable` | `boolean` | `false` | Rows and empty space accept native drops. See [Drops](#drops) |
+| `canDrop` | `(node, dataTransfer) => boolean` | | Refuse a drag up front. `node` is the row, or the current level's node over empty space |
+| `validateEdit` | `(value, node) => boolean` | | Opts in to [rename](#rename) and validates the typed text |
+| `markedKey` / `marked-key` | `string` | | Keep this node's row visibly marked across level changes. Not a selection |
+| `virtualize`, `itemHeight` / `item-height` | `boolean`, `number` | `false`, `0` | Render only visible rows; needs a fixed row height. See [virtualisation](../vertical-list/README.md#virtualisation) |
 | `withUp` / `with-up` | `boolean` | `true` | Up button in the crumb bar |
 | `hideRoot` / `hide-root` | `boolean` | `false` | Hide the root crumb |
 | `emptyText` / `empty-text` | `string` | `'Empty'` | Shown for a level with no children |
 
-A node counts as a branch unless `item.isLeaf` is `true` or its `children` is `[]`. `item.icon`, `iconColor`, `textColor` and `badge` are honoured.
+A node counts as a branch unless `item.isLeaf` is `true` or its `children` is `[]`. Set `item.isLeaf: false` to force a branch even when `children` is `[]`: an empty folder that can still be entered, showing `emptyText`. `item.icon`, `iconColor`, `textColor` and `badge` are honoured.
 
 ## Methods
 
@@ -43,6 +48,7 @@ A node counts as a branch unless `item.isLeaf` is `true` or its `children` is `[
 | `navigateUp()` | Go to the parent. `false` at the root |
 | `currentNode` | Node whose children are listed |
 | `selectedNodes` | Selected `TreeNode`s in the current level |
+| `beginEdit(key)` | Rename a row in place. Needs `validateEdit` and `item.editable`; `false` otherwise |
 | `registry` / `dispatch(id, args)` | The inner list's command registry, e.g. `dispatch('list.search.filter')` |
 | `list` | The inner `ixfx-vertical-list` |
 
@@ -53,6 +59,10 @@ A node counts as a branch unless `item.isLeaf` is `true` or its `children` is `[
 | `flat-list-navigate` | `{ path, previousPath, node, direction }` | The level changed. `direction` is `into`, `up` or `jump` |
 | `flat-list-select` | `{ selected, selectedKeys, previous }` | Selection changed (nodes, not elements) |
 | `flat-list-activate` | `{ node }` | A **leaf** was double-clicked or Enter was pressed |
+| `flat-list-drop` | `{ node, dataTransfer }` | Something was dropped. See [Drops](#drops) |
+| `flat-list-context-menu` | `{ node, nodes, x, y }` | Cancelable. See [Context menu](#context-menu) |
+| `flat-list-edit-commit` | `{ node, value }` | A rename was committed |
+| `flat-list-edit-cancel` | `{ node }` | A rename ended without a change |
 
 The inner list's `list-*` events also cross the shadow boundary, with row elements as their `item`.
 
@@ -67,14 +77,46 @@ The inner list's `list-*` events also cross the shadow boundary, with row elemen
 
 Selection is cleared on every level change. Arrow Left and Backspace are ignored while the search field is focused.
 
+## Drops
+
+With `items-droppable`, a drag over a row, or over empty space, is accepted unless `canDrop` refuses it. A drop fires `flat-list-drop` with that row's node, or the **current level's node** for empty space. Dropping on a branch row reports it and does **not** enter it. Native OS drags work: `dataTransfer` carries `files`, `text/uri-list` and any custom MIME type the source wrote. The row under the drag gets the vertical-list [drop highlight](../vertical-list/README.md#drop-targets).
+
+## Context menu
+
+`flat-list-context-menu` fires on right-click or the menu key. The row is selected first, so `nodes` is the selection to act on and `node` is the row clicked. Open your own `ixfx-menu-container` at `x, y`. Call `preventDefault()` to suppress the native menu.
+
+## Rename
+
+Rename is **opt-in**: set `validateEdit = (value, node) => boolean`, and mark the rows that may be renamed with `item.editable: true`. Without both, rows are plain text and `beginEdit` returns `false`. Returning `false` from the validator rejects the text and the edit ends as a cancel.
+
+```typescript
+list.validateEdit = (value, node) => value.trim() !== '' && !names.has(value);
+list.addEventListener('flat-list-edit-commit', ({ detail }) => rename(detail.node.item.key, detail.value));
+list.beginEdit('set:2');   // e.g. from your own context menu
+```
+
+`beginEdit(key)` starts the edit. Commit and cancel arrive as `flat-list-edit-commit` / `flat-list-edit-cancel`. The label is not rewritten for you: change `item.label` in your tree in response, and the level refreshes.
+
 ## Incremental search
 
 Navigate / select / filter search works over the current level, as in [`ixfx-vertical-list`](../vertical-list/README.md#incremental-search) — see [`docs/infra-incremental.md`](../../docs/infra-incremental.md). `search-modes` limits the modes. There is no default shortcut: bind a key or button to `dispatch('list.search.filter')` (or `.navigate` / `.select`). The highlight rule is built in, so no page-level `::highlight()` rule is needed. The search is closed when the level changes.
 
 ## CSS variables
 
-`--flat-list-bg`, `--flat-list-text`, `--flat-list-border`, `--flat-list-radius`, `--flat-list-crumb-padding`, `--flat-list-crumb-font-size` (default `--text-s`), `--flat-list-chevron-gap`, `--flat-list-empty-text`. Each falls back to the matching `--list-*` variable. Other `--list-*` variables (e.g. `--list-item-height`) reach the inner list.
+`--flat-list-bg`, `--flat-list-text`, `--flat-list-border`, `--flat-list-radius`, `--flat-list-crumb-padding`, `--flat-list-crumb-font-size` (default `--text-s`), `--flat-list-toolbar-gap`, `--flat-list-chevron-gap`, `--flat-list-marked-bg`, `--flat-list-marked-bar`, `--flat-list-empty-text`. Each falls back to the matching `--list-*` variable. Other `--list-*` variables (e.g. `--list-item-height`) reach the inner list.
+
+## Toolbar slot
+
+Anything you put inside the element goes in a toolbar to the right of the crumb bar, which shrinks to make room. With nothing slotted, the crumbs use the full width.
+
+```html
+<ixfx-flat-list>
+  <ixfx-button>New Set</ixfx-button>
+</ixfx-flat-list>
+```
+
+Space between items is `--flat-list-toolbar-gap`.
 
 ## CSS parts
 
-`crumbs` (the bar above the list), `empty`.
+`crumbs` (the bar above the list), `toolbar` (the slot's wrapper), `empty`.

package/docs-user/index.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
-  "version": "0.13.0",
-  "generated": "2026-10-01T19:52:29.255Z",
+  "version": "0.13.2",
+  "generated": "2026-10-01T21:51:41.922Z",
   "components": [
     {
       "name": "ac-text",

package/docs-user/vertical-list.md

@@ -16,9 +16,12 @@ A scrollable vertical list of items with selection, keyboard navigation, and inc
 8. [Native drag-out](#native-drag-out)
 9. [Keyboard navigation](#keyboard-navigation)
 10. [Incremental search](#incremental-search)
-11. [Virtualisation](#virtualisation)
-12. [CSS variables](#css-variables)
-13. [CSS parts](#css-parts)
+11. [Drop targets](#drop-targets)
+12. [Context menu](#context-menu)
+13. [In-place rename](#in-place-rename)
+14. [Virtualisation](#virtualisation)
+15. [CSS variables](#css-variables)
+16. [CSS parts](#css-parts)
 
 ---
 
@@ -120,6 +123,9 @@ To reflect selection state inside the custom element's shadow DOM, target the `:
 | `interactionMode` / `interaction-mode` | `ListInteractionMode` | `'standard'` | How gestures map to selection changes (see table below) |
 | `virtualize` / `virtualize` | `boolean` | `false` | Only render the viewport window (+ overscan) into the DOM; pool and recycle the rest. See [Virtualisation](#virtualisation) |
 | `itemHeight` / `item-height` | `number` | `0` | Fixed row height in px. Required for `virtualize` — every row must be exactly this tall |
+| `itemsDroppable` / `items-droppable` | `boolean` | `false` | Rows and empty space accept native drops. See [Drop targets](#drop-targets) |
+| `editValidator` | `((value, key) => boolean) \| undefined` | `undefined` | Opts in to [in-place rename](#in-place-rename) and validates the typed text. Unset ⇒ rows are plain text |
+| `canDrop` | `((item, dataTransfer) => boolean) \| undefined` | `undefined` | Refuse a drag before any event or highlight |
 | `filterPredicate` | `((el: Element) => boolean) \| undefined` | `undefined` | External filter; only items returning `true` are shown |
 | `checkboxRenderer` | `((checked: boolean) => unknown) \| CustomCheckboxOptions \| undefined` | `undefined` | Custom content for the checkbox in `checked` mode. See [Custom checkbox](#custom-checkbox) |
 | `formatter` | `((item: unknown, index: number) => unknown) \| undefined` | `undefined` | Renders one `items` entry into its row. See [Adapter items](#adapter-items) |
@@ -645,6 +651,56 @@ list.filterPredicate = undefined;
 
 ---
 
+## Drop targets
+
+Set `items-droppable` to make rows — and the empty space around them — accept native drags, including OS drags carrying files (`dataTransfer.files`, `text/uri-list`, custom MIME types).
+
+| Event | Detail | Notes |
+|---|---|---|
+| `list-drag-over` | `{ key, item, dataTransfer }` | Cancelable. **`preventDefault()` accepts the drop**; without it the drag is refused. Fires repeatedly while the drag moves |
+| `list-drop` | `{ key, item, dataTransfer }` | The drop landed |
+| `list-drag-leave` | `{ key }` | The drag left its last target (also when it is cancelled) |
+
+`key` / `item` are `undefined` over empty list space. The list sets `dropEffect` to `copy` when you accept without choosing one — set `dataTransfer.dropEffect` in the `list-drag-over` handler to override.
+
+The row under the drag gets `data-drop-target` (the host does, over empty space). Style it with `--list-drop-target-bg` and `--list-drop-target-outline`.
+
+`canDrop = (item, dataTransfer) => boolean` refuses a drag up front — no events, no highlight — e.g. to let a leaf row refuse what a folder row accepts.
+
+```typescript
+list.itemsDroppable = true;
+list.canDrop = (item, dt) => item?.hasAttribute('data-folder') ?? false;
+list.addEventListener('list-drag-over', e => e.preventDefault());
+list.addEventListener('list-drop', ({ detail }) => addFiles(detail.key, detail.dataTransfer.files));
+```
+
+---
+
+## Context menu
+
+`list-context-menu` `{ key, item, x, y, selectedKeys }` fires on right-click, and for the menu key (or Shift+F10) on the cursor row. A row that is not selected is selected first, as dragging does, so `selectedKeys` is what the menu acts on. Open your own `ixfx-menu-container` at `x, y` (viewport coordinates).
+
+The event is cancelable: call `preventDefault()` to suppress the browser's native menu. The menu key never shows the native menu; it only fires this event. Right-clicking empty space fires nothing.
+
+---
+
+## In-place rename
+
+Rename is **opt-in**: set `editValidator = (value, key) => boolean` first. Without it `beginEdit` returns `false` and rows stay plain text. The validator runs on commit; returning `false` rejects the text and the edit ends as a cancel.
+
+`list.beginEdit(key)` swaps an [`ixfx-editable-label`](../editable-label/README.md) into the row, selects its text and focuses it. It returns `false` if there is no `editValidator`, or the row is unknown or not rendered.
+
+The editor replaces the row's `[data-edit-label]` element, or the whole row if there is none. Mark the text element in rows that carry icons or badges, and set `data-edit-value` there if the editable text differs from its content.
+
+| Event | Detail | When |
+|---|---|---|
+| `list-edit-commit` | `{ key, value }` | Enter or blur with a changed value |
+| `list-edit-cancel` | `{ key }` | Escape, an unchanged value, or one the label rejects |
+
+The list never rewrites the label itself; the original row content returns when editing ends. Update your data in response to `list-edit-commit`. `editingKey` reports the row being edited. Keys typed in the editor do not reach the list.
+
+---
+
 ## Virtualisation
 
 Set `virtualize` to window the list: only the rows near the viewport (plus an overscan of 3 rows) ever exist in the DOM. Everything else is pooled off-DOM and recycled **by identity** as you scroll, so a list of tens of thousands of rows keeps a tiny, fast DOM. Works for hand-supplied `<li>` / `data-list-item` elements **and** adapter (`items`) rows.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
   "type": "module",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "packageManager": "pnpm@10.0.0",
   "description": "Web components for ixfx — Lit-based UI toolkit",
   "author": "Clint Heyer",

package/dist/flat-list-eYItri8-.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"flat-list-eYItri8-.d.ts","names":[],"sources":["../src/flat-list/types.ts","../src/flat-list/flat-list.ts"],"mappings":";;;;;;;;;KAGY;KAEA;;WAED;;WAEA;;WAEA,MAAM;;WAEN;;KAGC;WACD,UAAU,YAAY;WACtB,cAAc;WACd,UAAU,YAAY;;KAGrB;WACD,MAAM;;KAGL,wBAAwB,YAAY;KACpC,sBAAsB,YAAY;KAClC,wBAAwB,YAAY;UAE/B;EACf,sBAAsB;EACtB,oBAAoB;EACpB,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cCgGX,wBAAwB;;EAEnC,MAAM;EAGN,OAAO;;EAIP;;EAIA,cAAc;EAGd,iBAAiB;;EAIjB,QAAQ,GAAG,UAAU,GAAG;EAGxB,aAAa;EAGb,eAAe;EAGf,iBAAiB;EAGjB;EAGA;EAGA;EAGA;EAGA;;EAIA;;UAIQ;UAES;UACA;;MAcb,QAAQ;;MAKR,YAAY;;EAKhB,SAAS,mBAAmB,OAAO;;MAK/B,eAAe;MAIf,iBAAiB,YAAY;;EAWjC,WAAW;;EASX,aAAa;;EASb;EAqBS;YAQU,WAAW,SAAS;YAyBpB,QAAQ,SAAS;YAgNjB,wBAAM;SA0CT,sBAAM;;QA6EhB;YACI;IACR,kBAAkB;;;UAIL;EACf,iBAAiB,gBAAgB,yBAC/B,MAAM,GACN,WAAW,MAAM,iBAAiB,OAAO,wBAAwB,aACjE,oBAAoB;EAEtB,iBACE,cACA,UAAU,oCACV,oBAAoB"}

package/dist/types-D-kYF16b.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types-D-kYF16b.d.ts","names":[],"sources":["../src/common/types.ts"],"mappings":";;KAQY;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;EAMA;;;;;;EAMA;;;;;;;;EAQA;;EAEA;;EAEA;;;;;;;EAOA;;;KAIU;EACV,MAAM;;;;;;;EAON,WAAW;;;;;;;KAQD,uBAAuB;EAAgB,MAAM;EAAU;GAAiB;;;;;;KAOxE,uBAAuB,MAAM,UAAU;;;;;;;KAQvC;;;;;;;;;KAUA;;;;;;;;;KAUA"}

package/dist/vertical-list-DheZSEmB.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"vertical-list-DheZSEmB.d.ts","names":[],"sources":["../src/vertical-list/vertical-list.ts"],"mappings":";;;;;;;UA4DiB;EACf,WAAW;EACX;EACA;;UAGe;;;;;;EAMf;;cAkCW,4BAA4B;;EAEvC,eAAe;EAGf,iBAAiB;EAGjB,mBAAmB,IAAI;;;;;;EAQvB;;;;;;;;;;;;;;;;;;;EAqBA,oBAAoB,gCAAgC;;;;;;EAQpD;;;;;;EAQA;;;;;EAOA,qBAAqB,wBAAwB;EAG7C,mBAAmB,8BAA8B;;;;;;;;;;;EAajD;;;;;EAOA;;;;;;;;;EAWA,aAAa,eAAe;;;;;;;EAS5B,QAAQ,eAAe;;;;;EAOvB,aAAa,eAAe;;;;;EAO5B,aAAa,eAAe;;;;;;EAQ5B,SAAS,eAAe;;;;;;;;;;;;;;;;;;EAoBxB;;;;;;EAQA;mBAyCiB;UAeT;UA6EA;;WA6EC,QAAM,qBAAA;;MAYX,YAAY;EA2BP;EAsBA;;;;;;YA4BU;EAwDV,QAAQ,SAAS;;MAgFtB,gBAAgB;;MAKhB,iBAAiB,YAAY;EAIjC,QAAQ,MAAM,kBAAkB,UAAU;;;;;;;EA4B1C,WAAW,MAAM,UAAU;;EA2B3B,YAAY,OAAO,SAAS,WAAW;EAIvC;;;;;;EAmBA,SAAS,gBAAgB;;;;;;EAwBzB,SAAS,WAAW,WAAW,OAAO;EAItC,OAAO,MAAM;EAIb,WAAW,OAAO,SAAS;EAI3B,SAAS,MAAM;EAIf;EAIA;;MAQI,gBAAgB;;MAKhB;;EAMJ,WAAW,MAAM;;EAKjB,gBAAgB,MAAM;;EAKtB,mBAAmB,MAAM;;;;;;EASzB,SAAS;;EAgCT,aAAa,cAAc;;;;;;;;EAW3B;;;;;;;EAuBA;EAsBE,eAAe,0CAA0C,UAAU;;;;;EA2CrE,YAAY,MAAM;;;;;;;;;;;EAclB,WAAW,aAAa;UAmiBhB;UAgBA;UAOA;UAiBA;;;;;;;UA4GA;;;;;UAuBA;UAcA;UAYA;UAQA;UAWA;UAMA;UAIA;UA0DA;UAUA;UAMA;SAUQ,sBAAM;EA2Kb,wBAAM;;QAeT;YACI;IACR,sBAAsB;;YAGd,4BAA4B;;UAGvB,oCAAoC;EACnD,iCAAiC;EACjC,0BAA0B,yBAAyB"}