@rozie-ui/sortable-list-lit 0.1.5 → 0.1.8

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Dan Krieger and Rozie.js contributors
+Copyright (c) 2026 One Learning Community LTD
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/index.cjs

@@ -333,19 +333,22 @@ let SortableList = class SortableList extends (0, _lit_labs_preact_signals.Signa
 		this._rozieTornDown = false;
 		this._rozieReconcileSeq = 0;
 		this.instance = null;
-		this.__rowKey = {
-			map: /* @__PURE__ */ new WeakMap(),
-			seq: 0
-		};
+		this.__rowKeyMap = /* @__PURE__ */ new WeakMap();
+		this.__rowKeySeq = 0;
 		this.keyFor = (item, index) => {
 			if (typeof this.itemKey === "function") return this.itemKey(item, index);
 			if (typeof this.itemKey === "string" && item !== null && typeof item === "object" && item[this.itemKey] != null) return item[this.itemKey];
 			if (item !== null && typeof item === "object" || typeof item === "function") {
-				if (!this.__rowKey.map.has(item)) this.__rowKey.map.set(item, "__rk" + this.__rowKey.seq++);
-				return this.__rowKey.map.get(item);
+				if (!this.__rowKeyMap.has(item)) this.__rowKeyMap.set(item, "__rk" + this.__rowKeySeq++);
+				return this.__rowKeyMap.get(item);
 			}
 			return index;
 		};
+		this.resolveGroup = () => this.cloneable && typeof this.group === "string" ? {
+			name: this.group,
+			pull: "clone",
+			put: true
+		} : this.group ?? void 0;
 		this.itemClassFor = (item, index) => {
 			const v = this.itemClass;
 			return typeof v === "function" ? v(item, index) : v;
@@ -362,6 +365,7 @@ let SortableList = class SortableList extends (0, _lit_labs_preact_signals.Signa
 		};
 		this.keyboardEnabled = () => !this.disabled && !this.disableKeyboard;
 		this.onRowKeyDown = ($event, index) => {
+			if ($event.target !== $event.currentTarget) return;
 			if (!this.keyboardEnabled()) return;
 			const key = $event.key;
 			if (key === " " || key === "Spacebar" || key === "Enter") {
@@ -413,6 +417,7 @@ let SortableList = class SortableList extends (0, _lit_labs_preact_signals.Signa
 	}
 	static {
 		this.styles = lit.css`
+:host{display:contents}
 .rozie-sortable-wrap[data-rozie-s-0af24eae] { display: block; }
 .rozie-sortable-list[data-rozie-s-0af24eae] { display: block; }
 .rozie-sortable-item[data-rozie-s-0af24eae] { display: block; outline: none; }
@@ -490,11 +495,7 @@ let SortableList = class SortableList extends (0, _lit_labs_preact_signals.Signa
 			options: {
 				animation: this.animation,
 				disabled: this.disabled,
-				group: this.cloneable && typeof this.group === "string" ? {
-					name: this.group,
-					pull: "clone",
-					put: true
-				} : this.group,
+				group: this.resolveGroup(),
 				handle: this.handle,
 				ghostClass: this.ghostClass,
 				chosenClass: this.chosenClass,
@@ -548,7 +549,15 @@ let SortableList = class SortableList extends (0, _lit_labs_preact_signals.Signa
 	}
 	updated(changedProperties) {
 		if (this.__rozieFirstUpdateDone && changedProperties.has("disabled")) ((v) => this.instance?.option("disabled", v))(this.disabled);
-		if (this.__rozieFirstUpdateDone && changedProperties.has("group")) ((v) => this.instance?.option("group", v))(this.group);
+		if (this.__rozieFirstUpdateDone && changedProperties.has("group")) {
+			this.group;
+			this.instance?.option("group", this.resolveGroup());
+		}
+		if (this.__rozieFirstUpdateDone && changedProperties.has("cloneable")) {
+			this.cloneable;
+			this.instance?.option("group", this.resolveGroup());
+		}
+		if (this.__rozieFirstUpdateDone && changedProperties.has("swapThreshold")) ((v) => this.instance?.option("swapThreshold", v))(this.swapThreshold);
 		if (this.__rozieFirstUpdateDone && changedProperties.has("handle")) ((v) => this.instance?.option("handle", v))(this.handle);
 		if (this.__rozieFirstUpdateDone && changedProperties.has("ghostClass")) ((v) => this.instance?.option("ghostClass", v))(this.ghostClass);
 		if (this.__rozieFirstUpdateDone && changedProperties.has("chosenClass")) ((v) => this.instance?.option("chosenClass", v))(this.chosenClass);
@@ -634,9 +643,16 @@ let SortableList = class SortableList extends (0, _lit_labs_preact_signals.Signa
 	* with React/Vue/Svelte/Solid/Angular). Both Lit attribute-naming
 	* forms are folded into the skip set: kebab-case for model props
 	* (explicit `attribute:`) AND lowercased property name (Lit's default).
+	*
+	* command-palette-per-level-virtual / portal-through-portal cluster —
+	* `data-rozie-ref` is ALWAYS skipped too (a reserved compiler bookkeeping
+	* attribute, never a consumer prop) so a parent-assigned `ref=` on this
+	* component's own host tag can never clobber this component's OWN
+	* internal `data-rozie-ref` ref markers via fallthrough re-application.
 	*/
 	get $attrs() {
 		const __skip = new Set([
+			"data-rozie-ref",
 			"items",
 			"item-key",
 			"itemkey",

package/dist/index.d.cts

@@ -5,27 +5,89 @@ import { LitElement } from "lit";
 declare const SortableList_base: typeof LitElement;
 declare class SortableList extends SortableList_base {
   static styles: _$lit.CSSResult;
+  /**
+   * The bound items array. The sole `model: true` prop — two-way bind it (`r-model:items` / `v-model:items` / `bind:items` / `[(items)]`) and SortableList writes the re-ordered array back whenever a drag, cross-list move, or keyboard reorder commits, with no manual `onChange → setState` wiring.
+   * @example
+   * <SortableList r-model:items="$data.todos" itemKey="id" />
+   */
   _items_attr: any[];
   private _itemsControllable;
-  itemKey: string | (((...args: unknown[]) => unknown) | null);
-  handle: string;
-  group: string;
+  /**
+   * The per-row key the framework reconciler tracks each item by across a reorder — either a property name (e.g. `itemKey="id"` reads `item.id`) or an `(item, index) => key` function. With neither, id-less object items get a stable synthetic key via an internal `WeakMap` (survives reorder by object identity); primitive items fall back to index — pass a function for reorderable duplicate primitives.
+   */
+  itemKey: string | (((...args: any[]) => any) | null);
+  /**
+   * CSS selector identifying the per-row drag handle, so a drag starts only from that element rather than anywhere in the row. Authored class names render literally on every target (React included), so a plain `.grip` works; `$classSelector('grip')` is an optional, typo-checked way to author it.
+   */
+  handle: string | null;
+  /**
+   * SortableJS group name enabling cross-list drag — two lists sharing a `group` accept items between each other (the source fires `remove`, the destination fires `add`). Set `cloneable: true` to flip a string group into clone-mode.
+   */
+  group: string | null;
+  /**
+   * Reorder animation duration in milliseconds. `0` disables the animation. Runtime-updatable.
+   */
   animation: number;
+  /**
+   * Temporarily disable dragging without unmounting — reapplied live via `instance.option('disabled', v)` (no remount). Also suppresses keyboard reordering: a disabled list is not sortable by any input, so rows lose their `tabindex` and the keydown handler no-ops.
+   */
   disabled: boolean;
+  /**
+   * Opt out of keyboard reordering (Space lift / Arrow move / Esc cancel / Enter drop) while leaving pointer drag enabled. Rows drop out of the tab order (no `tabindex`) and the keydown handler no-ops. Keyboard access is gated on `!disabled && !disableKeyboard`.
+   */
   disableKeyboard: boolean;
+  /**
+   * Verbatim SortableJS options pass-through for anything not covered by the named props. The named props win on key conflict but `options` lands AFTER them in the merge so consumers can override defaults; handler keys (`onStart`, `onEnd`, `onUpdate`, `onAdd`, `onRemove`, `onClone`) are stripped — the helper owns those paths.
+   */
   options: any;
-  labelFor: ((...args: unknown[]) => unknown) | null;
-  ghostClass: string;
-  chosenClass: string;
-  dragClass: string;
-  filter: string;
-  easing: string;
+  /**
+   * Optional `(item, idx) => string` returning the screen-reader label for the aria-live announcer during keyboard drag. Defaults to `item.label` (or `String(item)` when no `label` field exists).
+   */
+  labelFor: ((...args: any[]) => any) | null;
+  /**
+   * Class name applied to the drop-placeholder (ghost) element while dragging. Forwarded live via `instance.option`, so toggling it at runtime takes effect without a remount.
+   */
+  ghostClass: string | null;
+  /**
+   * Class name applied to the currently-chosen item while dragging. Forwarded live via `instance.option` (no remount needed to change it).
+   */
+  chosenClass: string | null;
+  /**
+   * Class name applied to the dragging element. Only takes effect in fallback mode (`forceFallback: true`). Forwarded live via `instance.option`.
+   */
+  dragClass: string | null;
+  /**
+   * CSS selector that prevents drag initiation on matching rows (locked items). SortableJS checks it at `mousedown`/`touchstart` and aborts the drag if it matches. A `data-*` attribute selector (e.g. `[data-locked]`) is the most robust choice across all targets.
+   */
+  filter: string | null;
+  /**
+   * CSS easing function for the reorder animation (e.g. `'ease-in'`, `'cubic-bezier(0.4, 0, 0.2, 1)'`). Runtime-updatable.
+   */
+  easing: string | null;
+  /**
+   * Force SortableJS's mouse-event drag path over HTML5 DnD — useful for touch devices, consistent cross-browser behavior, and synthetic test drivers (and `dragClass` only applies in this mode). **Construction-time only**: SortableJS reads it once at construction, so re-key the `<SortableList>` to toggle it at runtime.
+   */
   forceFallback: boolean;
+  /**
+   * SortableJS swap threshold (0..1) — a lower value makes rows swap earlier as the dragged item overlaps a neighbor. Reapplied live via `instance.option('swapThreshold', v)` — SortableJS reads it on every dragover, so no remount is needed.
+   */
   swapThreshold: number;
+  /**
+   * High-level prop that REPLACES a string `group` with SortableJS's `{ name, pull: 'clone', put: true }` clone-mode object form — the source deposits a COPY onto the destination and keeps its own array unchanged (the palette → canvas pattern). With `group: null` it is a no-op (a clone-mode list with no group name has no peer to clone into). Reapplied live — toggling `cloneable` (or changing `group`) recomputes the clone-mode shape and reapplies it via `instance.option('group', …)`, no remount.
+   */
   cloneable: boolean;
+  /**
+   * Extra class(es) merged onto the list container (the SortableJS root) alongside the base `rozie-sortable-list` class. Accepts a `String`, `Array`, or `Object` (Vue-style class binding), normalized identically across all six targets — the hook for bridging a CSS framework (`.list-group`) or a flex/grid parent onto the component.
+   */
   listClass: string | any[] | any;
-  itemClass: string | any[] | any | (((...args: unknown[]) => unknown) | null);
-  itemStyle: string | any | (((...args: unknown[]) => unknown) | null);
+  /**
+   * Extra class(es) merged onto every item row alongside the base `rozie-sortable-item` class. Accepts a `String`, `Array`, or `Object` (Vue-style class binding) applied uniformly, OR an `(item, index) => class` function for per-row classes evaluated at render time. Normalized identically across all six targets.
+   */
+  itemClass: string | any[] | any | (((...args: any[]) => any) | null);
+  /**
+   * Per-row inline style applied to the `.rozie-sortable-item` wrapper. Accepts a CSS `String`, a flat style object (`Record<string, string | number>`), or an `(item, index) => string | object` function for per-row styling. Because it lands on the wrapper — the direct child of the list container — it can drive CSS-grid placement (`grid-column` / `grid-row` / `align-self`) when `listClass` sets `display: grid`. Normalized per target; `null` / empty drops the attribute.
+   */
+  itemStyle: string | any | (((...args: any[]) => any) | null);
   private _liftedIndex;
   private _ariaLiveText;
   private _refListEl;
@@ -52,11 +114,14 @@ declare class SortableList extends SortableList_base {
   attributeChangedCallback(name: string, old: string | null, value: string | null): void;
   render(): _$lit.TemplateResult<1>;
   instance: any;
-  __rowKey: {
-    map: WeakMap<object, any>;
-    seq: number;
-  };
+  __rowKeyMap: WeakMap<object, any>;
+  __rowKeySeq: number;
   keyFor: (item: any, index: any) => any;
+  resolveGroup: () => string | {
+    name: string;
+    pull: "clone";
+    put: true;
+  } | undefined;
   itemClassFor: (item: any, index: any) => any;
   itemStyleFor: (item: any, index: any) => any;
   getLabel: (idx: any) => any;
@@ -79,6 +144,12 @@ declare class SortableList extends SortableList_base {
    * with React/Vue/Svelte/Solid/Angular). Both Lit attribute-naming
    * forms are folded into the skip set: kebab-case for model props
    * (explicit `attribute:`) AND lowercased property name (Lit's default).
+   *
+   * command-palette-per-level-virtual / portal-through-portal cluster —
+   * `data-rozie-ref` is ALWAYS skipped too (a reserved compiler bookkeeping
+   * attribute, never a consumer prop) so a parent-assigned `ref=` on this
+   * component's own host tag can never clobber this component's OWN
+   * internal `data-rozie-ref` ref markers via fallthrough re-application.
    */
   private get $attrs();
   /**

package/dist/index.d.mts

@@ -5,27 +5,89 @@ import { LitElement } from "lit";
 declare const SortableList_base: typeof LitElement;
 declare class SortableList extends SortableList_base {
   static styles: _$lit.CSSResult;
+  /**
+   * The bound items array. The sole `model: true` prop — two-way bind it (`r-model:items` / `v-model:items` / `bind:items` / `[(items)]`) and SortableList writes the re-ordered array back whenever a drag, cross-list move, or keyboard reorder commits, with no manual `onChange → setState` wiring.
+   * @example
+   * <SortableList r-model:items="$data.todos" itemKey="id" />
+   */
   _items_attr: any[];
   private _itemsControllable;
-  itemKey: string | (((...args: unknown[]) => unknown) | null);
-  handle: string;
-  group: string;
+  /**
+   * The per-row key the framework reconciler tracks each item by across a reorder — either a property name (e.g. `itemKey="id"` reads `item.id`) or an `(item, index) => key` function. With neither, id-less object items get a stable synthetic key via an internal `WeakMap` (survives reorder by object identity); primitive items fall back to index — pass a function for reorderable duplicate primitives.
+   */
+  itemKey: string | (((...args: any[]) => any) | null);
+  /**
+   * CSS selector identifying the per-row drag handle, so a drag starts only from that element rather than anywhere in the row. Authored class names render literally on every target (React included), so a plain `.grip` works; `$classSelector('grip')` is an optional, typo-checked way to author it.
+   */
+  handle: string | null;
+  /**
+   * SortableJS group name enabling cross-list drag — two lists sharing a `group` accept items between each other (the source fires `remove`, the destination fires `add`). Set `cloneable: true` to flip a string group into clone-mode.
+   */
+  group: string | null;
+  /**
+   * Reorder animation duration in milliseconds. `0` disables the animation. Runtime-updatable.
+   */
   animation: number;
+  /**
+   * Temporarily disable dragging without unmounting — reapplied live via `instance.option('disabled', v)` (no remount). Also suppresses keyboard reordering: a disabled list is not sortable by any input, so rows lose their `tabindex` and the keydown handler no-ops.
+   */
   disabled: boolean;
+  /**
+   * Opt out of keyboard reordering (Space lift / Arrow move / Esc cancel / Enter drop) while leaving pointer drag enabled. Rows drop out of the tab order (no `tabindex`) and the keydown handler no-ops. Keyboard access is gated on `!disabled && !disableKeyboard`.
+   */
   disableKeyboard: boolean;
+  /**
+   * Verbatim SortableJS options pass-through for anything not covered by the named props. The named props win on key conflict but `options` lands AFTER them in the merge so consumers can override defaults; handler keys (`onStart`, `onEnd`, `onUpdate`, `onAdd`, `onRemove`, `onClone`) are stripped — the helper owns those paths.
+   */
   options: any;
-  labelFor: ((...args: unknown[]) => unknown) | null;
-  ghostClass: string;
-  chosenClass: string;
-  dragClass: string;
-  filter: string;
-  easing: string;
+  /**
+   * Optional `(item, idx) => string` returning the screen-reader label for the aria-live announcer during keyboard drag. Defaults to `item.label` (or `String(item)` when no `label` field exists).
+   */
+  labelFor: ((...args: any[]) => any) | null;
+  /**
+   * Class name applied to the drop-placeholder (ghost) element while dragging. Forwarded live via `instance.option`, so toggling it at runtime takes effect without a remount.
+   */
+  ghostClass: string | null;
+  /**
+   * Class name applied to the currently-chosen item while dragging. Forwarded live via `instance.option` (no remount needed to change it).
+   */
+  chosenClass: string | null;
+  /**
+   * Class name applied to the dragging element. Only takes effect in fallback mode (`forceFallback: true`). Forwarded live via `instance.option`.
+   */
+  dragClass: string | null;
+  /**
+   * CSS selector that prevents drag initiation on matching rows (locked items). SortableJS checks it at `mousedown`/`touchstart` and aborts the drag if it matches. A `data-*` attribute selector (e.g. `[data-locked]`) is the most robust choice across all targets.
+   */
+  filter: string | null;
+  /**
+   * CSS easing function for the reorder animation (e.g. `'ease-in'`, `'cubic-bezier(0.4, 0, 0.2, 1)'`). Runtime-updatable.
+   */
+  easing: string | null;
+  /**
+   * Force SortableJS's mouse-event drag path over HTML5 DnD — useful for touch devices, consistent cross-browser behavior, and synthetic test drivers (and `dragClass` only applies in this mode). **Construction-time only**: SortableJS reads it once at construction, so re-key the `<SortableList>` to toggle it at runtime.
+   */
   forceFallback: boolean;
+  /**
+   * SortableJS swap threshold (0..1) — a lower value makes rows swap earlier as the dragged item overlaps a neighbor. Reapplied live via `instance.option('swapThreshold', v)` — SortableJS reads it on every dragover, so no remount is needed.
+   */
   swapThreshold: number;
+  /**
+   * High-level prop that REPLACES a string `group` with SortableJS's `{ name, pull: 'clone', put: true }` clone-mode object form — the source deposits a COPY onto the destination and keeps its own array unchanged (the palette → canvas pattern). With `group: null` it is a no-op (a clone-mode list with no group name has no peer to clone into). Reapplied live — toggling `cloneable` (or changing `group`) recomputes the clone-mode shape and reapplies it via `instance.option('group', …)`, no remount.
+   */
   cloneable: boolean;
+  /**
+   * Extra class(es) merged onto the list container (the SortableJS root) alongside the base `rozie-sortable-list` class. Accepts a `String`, `Array`, or `Object` (Vue-style class binding), normalized identically across all six targets — the hook for bridging a CSS framework (`.list-group`) or a flex/grid parent onto the component.
+   */
   listClass: string | any[] | any;
-  itemClass: string | any[] | any | (((...args: unknown[]) => unknown) | null);
-  itemStyle: string | any | (((...args: unknown[]) => unknown) | null);
+  /**
+   * Extra class(es) merged onto every item row alongside the base `rozie-sortable-item` class. Accepts a `String`, `Array`, or `Object` (Vue-style class binding) applied uniformly, OR an `(item, index) => class` function for per-row classes evaluated at render time. Normalized identically across all six targets.
+   */
+  itemClass: string | any[] | any | (((...args: any[]) => any) | null);
+  /**
+   * Per-row inline style applied to the `.rozie-sortable-item` wrapper. Accepts a CSS `String`, a flat style object (`Record<string, string | number>`), or an `(item, index) => string | object` function for per-row styling. Because it lands on the wrapper — the direct child of the list container — it can drive CSS-grid placement (`grid-column` / `grid-row` / `align-self`) when `listClass` sets `display: grid`. Normalized per target; `null` / empty drops the attribute.
+   */
+  itemStyle: string | any | (((...args: any[]) => any) | null);
   private _liftedIndex;
   private _ariaLiveText;
   private _refListEl;
@@ -52,11 +114,14 @@ declare class SortableList extends SortableList_base {
   attributeChangedCallback(name: string, old: string | null, value: string | null): void;
   render(): _$lit.TemplateResult<1>;
   instance: any;
-  __rowKey: {
-    map: WeakMap<object, any>;
-    seq: number;
-  };
+  __rowKeyMap: WeakMap<object, any>;
+  __rowKeySeq: number;
   keyFor: (item: any, index: any) => any;
+  resolveGroup: () => string | {
+    name: string;
+    pull: "clone";
+    put: true;
+  } | undefined;
   itemClassFor: (item: any, index: any) => any;
   itemStyleFor: (item: any, index: any) => any;
   getLabel: (idx: any) => any;
@@ -79,6 +144,12 @@ declare class SortableList extends SortableList_base {
    * with React/Vue/Svelte/Solid/Angular). Both Lit attribute-naming
    * forms are folded into the skip set: kebab-case for model props
    * (explicit `attribute:`) AND lowercased property name (Lit's default).
+   *
+   * command-palette-per-level-virtual / portal-through-portal cluster —
+   * `data-rozie-ref` is ALWAYS skipped too (a reserved compiler bookkeeping
+   * attribute, never a consumer prop) so a parent-assigned `ref=` on this
+   * component's own host tag can never clobber this component's OWN
+   * internal `data-rozie-ref` ref markers via fallthrough re-application.
    */
   private get $attrs();
   /**

package/dist/index.mjs

@@ -306,19 +306,22 @@ let SortableList = class SortableList extends SignalWatcher(LitElement) {
 		this._rozieTornDown = false;
 		this._rozieReconcileSeq = 0;
 		this.instance = null;
-		this.__rowKey = {
-			map: /* @__PURE__ */ new WeakMap(),
-			seq: 0
-		};
+		this.__rowKeyMap = /* @__PURE__ */ new WeakMap();
+		this.__rowKeySeq = 0;
 		this.keyFor = (item, index) => {
 			if (typeof this.itemKey === "function") return this.itemKey(item, index);
 			if (typeof this.itemKey === "string" && item !== null && typeof item === "object" && item[this.itemKey] != null) return item[this.itemKey];
 			if (item !== null && typeof item === "object" || typeof item === "function") {
-				if (!this.__rowKey.map.has(item)) this.__rowKey.map.set(item, "__rk" + this.__rowKey.seq++);
-				return this.__rowKey.map.get(item);
+				if (!this.__rowKeyMap.has(item)) this.__rowKeyMap.set(item, "__rk" + this.__rowKeySeq++);
+				return this.__rowKeyMap.get(item);
 			}
 			return index;
 		};
+		this.resolveGroup = () => this.cloneable && typeof this.group === "string" ? {
+			name: this.group,
+			pull: "clone",
+			put: true
+		} : this.group ?? void 0;
 		this.itemClassFor = (item, index) => {
 			const v = this.itemClass;
 			return typeof v === "function" ? v(item, index) : v;
@@ -335,6 +338,7 @@ let SortableList = class SortableList extends SignalWatcher(LitElement) {
 		};
 		this.keyboardEnabled = () => !this.disabled && !this.disableKeyboard;
 		this.onRowKeyDown = ($event, index) => {
+			if ($event.target !== $event.currentTarget) return;
 			if (!this.keyboardEnabled()) return;
 			const key = $event.key;
 			if (key === " " || key === "Spacebar" || key === "Enter") {
@@ -386,6 +390,7 @@ let SortableList = class SortableList extends SignalWatcher(LitElement) {
 	}
 	static {
 		this.styles = css`
+:host{display:contents}
 .rozie-sortable-wrap[data-rozie-s-0af24eae] { display: block; }
 .rozie-sortable-list[data-rozie-s-0af24eae] { display: block; }
 .rozie-sortable-item[data-rozie-s-0af24eae] { display: block; outline: none; }
@@ -463,11 +468,7 @@ let SortableList = class SortableList extends SignalWatcher(LitElement) {
 			options: {
 				animation: this.animation,
 				disabled: this.disabled,
-				group: this.cloneable && typeof this.group === "string" ? {
-					name: this.group,
-					pull: "clone",
-					put: true
-				} : this.group,
+				group: this.resolveGroup(),
 				handle: this.handle,
 				ghostClass: this.ghostClass,
 				chosenClass: this.chosenClass,
@@ -521,7 +522,15 @@ let SortableList = class SortableList extends SignalWatcher(LitElement) {
 	}
 	updated(changedProperties) {
 		if (this.__rozieFirstUpdateDone && changedProperties.has("disabled")) ((v) => this.instance?.option("disabled", v))(this.disabled);
-		if (this.__rozieFirstUpdateDone && changedProperties.has("group")) ((v) => this.instance?.option("group", v))(this.group);
+		if (this.__rozieFirstUpdateDone && changedProperties.has("group")) {
+			this.group;
+			this.instance?.option("group", this.resolveGroup());
+		}
+		if (this.__rozieFirstUpdateDone && changedProperties.has("cloneable")) {
+			this.cloneable;
+			this.instance?.option("group", this.resolveGroup());
+		}
+		if (this.__rozieFirstUpdateDone && changedProperties.has("swapThreshold")) ((v) => this.instance?.option("swapThreshold", v))(this.swapThreshold);
 		if (this.__rozieFirstUpdateDone && changedProperties.has("handle")) ((v) => this.instance?.option("handle", v))(this.handle);
 		if (this.__rozieFirstUpdateDone && changedProperties.has("ghostClass")) ((v) => this.instance?.option("ghostClass", v))(this.ghostClass);
 		if (this.__rozieFirstUpdateDone && changedProperties.has("chosenClass")) ((v) => this.instance?.option("chosenClass", v))(this.chosenClass);
@@ -607,9 +616,16 @@ let SortableList = class SortableList extends SignalWatcher(LitElement) {
 	* with React/Vue/Svelte/Solid/Angular). Both Lit attribute-naming
 	* forms are folded into the skip set: kebab-case for model props
 	* (explicit `attribute:`) AND lowercased property name (Lit's default).
+	*
+	* command-palette-per-level-virtual / portal-through-portal cluster —
+	* `data-rozie-ref` is ALWAYS skipped too (a reserved compiler bookkeeping
+	* attribute, never a consumer prop) so a parent-assigned `ref=` on this
+	* component's own host tag can never clobber this component's OWN
+	* internal `data-rozie-ref` ref markers via fallthrough re-application.
 	*/
 	get $attrs() {
 		const __skip = new Set([
+			"data-rozie-ref",
 			"items",
 			"item-key",
 			"itemkey",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rozie-ui/sortable-list-lit",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "type": "module",
   "private": false,
   "license": "MIT",
@@ -40,7 +40,7 @@
     "src"
   ],
   "dependencies": {
-    "@rozie/runtime-lit": "0.1.1"
+    "@rozie/runtime-lit": "0.2.1"
   },
   "peerDependencies": {
     "lit": "^3.2",

package/src/SortableList.ts

@@ -14,6 +14,7 @@ interface RozieDefaultSlotCtx {
 @customElement('rozie-sortable-list')
 export default class SortableList extends SignalWatcher(LitElement) {
   static styles = css`
+:host{display:contents}
 .rozie-sortable-wrap[data-rozie-s-0af24eae] { display: block; }
 .rozie-sortable-list[data-rozie-s-0af24eae] { display: block; }
 .rozie-sortable-item[data-rozie-s-0af24eae] { display: block; outline: none; }
@@ -35,28 +36,90 @@ export default class SortableList extends SignalWatcher(LitElement) {
 }
 `;
 
+  /**
+   * The bound items array. The sole `model: true` prop — two-way bind it (`r-model:items` / `v-model:items` / `bind:items` / `[(items)]`) and SortableList writes the re-ordered array back whenever a drag, cross-list move, or keyboard reorder commits, with no manual `onChange → setState` wiring.
+   * @example
+   * <SortableList r-model:items="$data.todos" itemKey="id" />
+   */
   @property({ type: Array, attribute: 'items' }) _items_attr: any[] = [];
   private _itemsControllable = createLitControllableProperty<any[]>({ host: this, eventName: 'items-change', defaultValue: [], initialControlledValue: undefined });
-  @property({ type: String }) itemKey: string | (((...args: unknown[]) => unknown) | null) = null;
-  @property({ type: String, reflect: true }) handle: string = null;
-  @property({ type: String, reflect: true }) group: string = null;
+  /**
+   * The per-row key the framework reconciler tracks each item by across a reorder — either a property name (e.g. `itemKey="id"` reads `item.id`) or an `(item, index) => key` function. With neither, id-less object items get a stable synthetic key via an internal `WeakMap` (survives reorder by object identity); primitive items fall back to index — pass a function for reorderable duplicate primitives.
+   */
+  @property({ type: String }) itemKey: string | (((...args: any[]) => any) | null) = null;
+  /**
+   * CSS selector identifying the per-row drag handle, so a drag starts only from that element rather than anywhere in the row. Authored class names render literally on every target (React included), so a plain `.grip` works; `$classSelector('grip')` is an optional, typo-checked way to author it.
+   */
+  @property({ type: String, reflect: true }) handle: string | null = null;
+  /**
+   * SortableJS group name enabling cross-list drag — two lists sharing a `group` accept items between each other (the source fires `remove`, the destination fires `add`). Set `cloneable: true` to flip a string group into clone-mode.
+   */
+  @property({ type: String, reflect: true }) group: string | null = null;
+  /**
+   * Reorder animation duration in milliseconds. `0` disables the animation. Runtime-updatable.
+   */
   @property({ type: Number, reflect: true }) animation: number = 150;
+  /**
+   * Temporarily disable dragging without unmounting — reapplied live via `instance.option('disabled', v)` (no remount). Also suppresses keyboard reordering: a disabled list is not sortable by any input, so rows lose their `tabindex` and the keydown handler no-ops.
+   */
   @property({ type: Boolean, reflect: true }) disabled: boolean = false;
+  /**
+   * Opt out of keyboard reordering (Space lift / Arrow move / Esc cancel / Enter drop) while leaving pointer drag enabled. Rows drop out of the tab order (no `tabindex`) and the keydown handler no-ops. Keyboard access is gated on `!disabled && !disableKeyboard`.
+   */
   @property({ type: Boolean, reflect: true }) disableKeyboard: boolean = false;
+  /**
+   * Verbatim SortableJS options pass-through for anything not covered by the named props. The named props win on key conflict but `options` lands AFTER them in the merge so consumers can override defaults; handler keys (`onStart`, `onEnd`, `onUpdate`, `onAdd`, `onRemove`, `onClone`) are stripped — the helper owns those paths.
+   */
   @property({ type: Object }) options: any = {};
-  @property({ type: Function }) labelFor: ((...args: unknown[]) => unknown) | null = null;
-  @property({ type: String, reflect: true }) ghostClass: string = null;
-  @property({ type: String, reflect: true }) chosenClass: string = null;
-  @property({ type: String, reflect: true }) dragClass: string = null;
-  @property({ type: String, reflect: true }) filter: string = null;
-  @property({ type: String, reflect: true }) easing: string = null;
+  /**
+   * Optional `(item, idx) => string` returning the screen-reader label for the aria-live announcer during keyboard drag. Defaults to `item.label` (or `String(item)` when no `label` field exists).
+   */
+  @property({ type: Function }) labelFor: ((...args: any[]) => any) | null = null;
+  /**
+   * Class name applied to the drop-placeholder (ghost) element while dragging. Forwarded live via `instance.option`, so toggling it at runtime takes effect without a remount.
+   */
+  @property({ type: String, reflect: true }) ghostClass: string | null = null;
+  /**
+   * Class name applied to the currently-chosen item while dragging. Forwarded live via `instance.option` (no remount needed to change it).
+   */
+  @property({ type: String, reflect: true }) chosenClass: string | null = null;
+  /**
+   * Class name applied to the dragging element. Only takes effect in fallback mode (`forceFallback: true`). Forwarded live via `instance.option`.
+   */
+  @property({ type: String, reflect: true }) dragClass: string | null = null;
+  /**
+   * CSS selector that prevents drag initiation on matching rows (locked items). SortableJS checks it at `mousedown`/`touchstart` and aborts the drag if it matches. A `data-*` attribute selector (e.g. `[data-locked]`) is the most robust choice across all targets.
+   */
+  @property({ type: String, reflect: true }) filter: string | null = null;
+  /**
+   * CSS easing function for the reorder animation (e.g. `'ease-in'`, `'cubic-bezier(0.4, 0, 0.2, 1)'`). Runtime-updatable.
+   */
+  @property({ type: String, reflect: true }) easing: string | null = null;
+  /**
+   * Force SortableJS's mouse-event drag path over HTML5 DnD — useful for touch devices, consistent cross-browser behavior, and synthetic test drivers (and `dragClass` only applies in this mode). **Construction-time only**: SortableJS reads it once at construction, so re-key the `<SortableList>` to toggle it at runtime.
+   */
   @property({ type: Boolean, reflect: true }) forceFallback: boolean = false;
+  /**
+   * SortableJS swap threshold (0..1) — a lower value makes rows swap earlier as the dragged item overlaps a neighbor. Reapplied live via `instance.option('swapThreshold', v)` — SortableJS reads it on every dragover, so no remount is needed.
+   */
   @property({ type: Number, reflect: true }) swapThreshold: number = 1;
+  /**
+   * High-level prop that REPLACES a string `group` with SortableJS's `{ name, pull: 'clone', put: true }` clone-mode object form — the source deposits a COPY onto the destination and keeps its own array unchanged (the palette → canvas pattern). With `group: null` it is a no-op (a clone-mode list with no group name has no peer to clone into). Reapplied live — toggling `cloneable` (or changing `group`) recomputes the clone-mode shape and reapplies it via `instance.option('group', …)`, no remount.
+   */
   @property({ type: Boolean, reflect: true }) cloneable: boolean = false;
+  /**
+   * Extra class(es) merged onto the list container (the SortableJS root) alongside the base `rozie-sortable-list` class. Accepts a `String`, `Array`, or `Object` (Vue-style class binding), normalized identically across all six targets — the hook for bridging a CSS framework (`.list-group`) or a flex/grid parent onto the component.
+   */
   @property({ type: String }) listClass: string | any[] | any = '';
-  @property({ type: String }) itemClass: string | any[] | any | (((...args: unknown[]) => unknown) | null) = '';
-  @property({ type: String }) itemStyle: string | any | (((...args: unknown[]) => unknown) | null) = null;
-  private _liftedIndex = signal(null);
+  /**
+   * Extra class(es) merged onto every item row alongside the base `rozie-sortable-item` class. Accepts a `String`, `Array`, or `Object` (Vue-style class binding) applied uniformly, OR an `(item, index) => class` function for per-row classes evaluated at render time. Normalized identically across all six targets.
+   */
+  @property({ type: String }) itemClass: string | any[] | any | (((...args: any[]) => any) | null) = '';
+  /**
+   * Per-row inline style applied to the `.rozie-sortable-item` wrapper. Accepts a CSS `String`, a flat style object (`Record<string, string | number>`), or an `(item, index) => string | object` function for per-row styling. Because it lands on the wrapper — the direct child of the list container — it can drive CSS-grid placement (`grid-column` / `grid-row` / `align-self`) when `listClass` sets `display: grid`. Normalized per target; `null` / empty drops the attribute.
+   */
+  @property({ type: String }) itemStyle: string | any | (((...args: any[]) => any) | null) = null;
+  private _liftedIndex = signal<any>(null);
   private _ariaLiveText = signal('');
   @query('[data-rozie-ref="listEl"]') private _refListEl!: HTMLElement;
   @query('[data-rozie-ref="__rozieRoot"]') private _ref__rozieRoot!: HTMLElement;
@@ -136,17 +199,7 @@ private __rozieFirstUpdateDone = false;
       options: {
         animation: this.animation,
         disabled: this.disabled,
-        // `cloneable` is a high-level Rozie prop that REPLACES a string
-        // `group` with SortableJS's `{ name, pull: 'clone', put: true }`
-        // object form. When `cloneable:false`, pass `$props.group` through
-        // verbatim. When `cloneable:true` AND `$props.group` is null,
-        // leave it null — a clone-mode list without a group name is not
-        // meaningful (no peer list can join the cross-list flow).
-        group: this.cloneable && typeof this.group === 'string' ? {
-          name: this.group,
-          pull: 'clone',
-          put: true
-        } : this.group,
+        group: this.resolveGroup(),
         handle: this.handle,
         ghostClass: this.ghostClass,
         chosenClass: this.chosenClass,
@@ -212,7 +265,9 @@ private __rozieFirstUpdateDone = false;
 
   updated(changedProperties: Map<string, unknown>): void {
     if (this.__rozieFirstUpdateDone && (changedProperties.has('disabled'))) { const __watchVal = (() => this.disabled)(); ((v: any) => this.instance?.option('disabled', v))(__watchVal); }
-    if (this.__rozieFirstUpdateDone && (changedProperties.has('group'))) { const __watchVal = (() => this.group)(); ((v: any) => this.instance?.option('group', v))(__watchVal); }
+    if (this.__rozieFirstUpdateDone && (changedProperties.has('group'))) { const __watchVal = (() => this.group)(); (() => this.instance?.option('group', this.resolveGroup()))(); }
+    if (this.__rozieFirstUpdateDone && (changedProperties.has('cloneable'))) { const __watchVal = (() => this.cloneable)(); (() => this.instance?.option('group', this.resolveGroup()))(); }
+    if (this.__rozieFirstUpdateDone && (changedProperties.has('swapThreshold'))) { const __watchVal = (() => this.swapThreshold)(); ((v: any) => this.instance?.option('swapThreshold', v))(__watchVal); }
     if (this.__rozieFirstUpdateDone && (changedProperties.has('handle'))) { const __watchVal = (() => this.handle)(); ((v: any) => this.instance?.option('handle', v))(__watchVal); }
     if (this.__rozieFirstUpdateDone && (changedProperties.has('ghostClass'))) { const __watchVal = (() => this.ghostClass)(); ((v: any) => this.instance?.option('ghostClass', v))(__watchVal); }
     if (this.__rozieFirstUpdateDone && (changedProperties.has('chosenClass'))) { const __watchVal = (() => this.chosenClass)(); ((v: any) => this.instance?.option('chosenClass', v))(__watchVal); }
@@ -242,7 +297,7 @@ private __rozieFirstUpdateDone = false;
 <div class="rozie-sortable-wrap" ${rozieSpread(this.$attrs)} ${rozieListeners(this.$listeners)} data-rozie-ref="__rozieRoot" data-rozie-s-0af24eae>
   <div class="${(rozieClass(['rozie-sortable-list', this.listClass]))}" part="list" data-rozie-ref="listEl" data-rozie-s-0af24eae>${keyed(this._rozieReconcileSeq ?? 0, html`
     <slot name="header"></slot>
-    ${repeat<any>(this.items, (item, index) => this.keyFor(item, index), (item, index) => html`<div class="${(rozieClass(['rozie-sortable-item', this.itemClassFor(item, index), { 'rozie-sortable-item-lifted': this._liftedIndex.value === index }]))}" key=${rozieAttr(this.keyFor(item, index))} style=${rozieStyle(this.itemStyleFor(item, index))} data-id=${rozieAttr(this.keyFor(item, index))} role="listitem" tabindex=${rozieAttr(this.keyboardEnabled() ? 0 : null)} @keydown=${($event: Event) => { this.onRowKeyDown($event, index); }} data-rozie-s-0af24eae>
+    ${repeat<any>(this.items, (item, index) => this.keyFor(item, index), (item, index) => html`<div class="${(rozieClass(['rozie-sortable-item', this.itemClassFor(item, index), { 'rozie-sortable-item-lifted': this._liftedIndex.value === index }]))}" key=${rozieAttr(this.keyFor(item, index))} style=${rozieStyle(this.itemStyleFor(item, index))} data-id=${rozieAttr(this.keyFor(item, index))} role="listitem" tabindex=${rozieAttr(this.keyboardEnabled() ? 0 : null)} @keydown=${($event: KeyboardEvent & { currentTarget: HTMLDivElement; target: HTMLDivElement }) => { this.onRowKeyDown($event, index); }} data-rozie-s-0af24eae>
       ${this.__rozieDefaultSlot__ !== undefined ? this.__rozieDefaultSlot__({item: item, index: index}) : html`<slot data-rozie-params=${(() => { try { return JSON.stringify({item: item, index: index}); } catch { return '{}'; } })()}></slot>`}
     </div>`)}
     <slot name="footer"></slot>
@@ -254,10 +309,9 @@ private __rozieFirstUpdateDone = false;
 
   instance: any = null;
 
-  __rowKey = {
-  map: new WeakMap(),
-  seq: 0
-};
+  __rowKeyMap = new WeakMap();
+
+  __rowKeySeq = 0;
 
   keyFor = (item: any, index: any) => {
   // (a) function itemKey: consumer-supplied (item, index) => key.
@@ -271,16 +325,22 @@ private __rozieFirstUpdateDone = false;
   // (c) id-less object (or function) item: assign-on-first-sight WeakMap
   //     synthetic id. Survives reorder because it is keyed by object identity.
   if (item !== null && typeof item === 'object' || typeof item === 'function') {
-    if (!this.__rowKey.map.has(item)) {
-      this.__rowKey.map.set(item, '__rk' + this.__rowKey.seq++);
+    if (!this.__rowKeyMap.has(item)) {
+      this.__rowKeyMap.set(item, '__rk' + this.__rowKeySeq++);
     }
-    return this.__rowKey.map.get(item);
+    return this.__rowKeyMap.get(item);
   }
   // (d) primitive item: fall back to index. NOTE: duplicate primitives are
   //     unsafe to reorder this way — pass a function itemKey for those.
   return index;
 };
 
+  resolveGroup = () => this.cloneable && typeof this.group === 'string' ? {
+  name: this.group,
+  pull: 'clone' as const,
+  put: true as const
+} : this.group ?? undefined;
+
   itemClassFor = (item: any, index: any) => {
   const v = this.itemClass;
   return typeof v === 'function' ? v(item, index) : v;
@@ -301,6 +361,13 @@ private __rozieFirstUpdateDone = false;
   keyboardEnabled = () => !this.disabled && !this.disableKeyboard;
 
   onRowKeyDown = ($event: any, index: any) => {
+  // Origin guard (quick 260716-ggq): reorder keys apply ONLY when the row
+  // element ITSELF is focused. A slotted interactive child (an <input>,
+  // <button>, etc. rendered into the row's default slot) bubbles its own
+  // keydown up to this handler — without this guard, Space/Enter typed into
+  // that child would be hijacked for lift/drop instead of reaching the
+  // child. Must run FIRST, before the keyboardEnabled() check.
+  if ($event.target !== $event.currentTarget) return;
   // Defense-in-depth: when keyboard reordering is off the rows carry no
   // tabindex and can't receive focus, but a consumer-focused row (or a
   // programmatic .focus()) must still no-op here rather than reorder.
@@ -392,9 +459,15 @@ private __rozieFirstUpdateDone = false;
    * with React/Vue/Svelte/Solid/Angular). Both Lit attribute-naming
    * forms are folded into the skip set: kebab-case for model props
    * (explicit `attribute:`) AND lowercased property name (Lit's default).
+   *
+   * command-palette-per-level-virtual / portal-through-portal cluster —
+   * `data-rozie-ref` is ALWAYS skipped too (a reserved compiler bookkeeping
+   * attribute, never a consumer prop) so a parent-assigned `ref=` on this
+   * component's own host tag can never clobber this component's OWN
+   * internal `data-rozie-ref` ref markers via fallthrough re-application.
    */
   private get $attrs(): Record<string, string> {
-    const __skip = new Set<string>(['items', 'item-key', 'itemkey', 'handle', 'group', 'animation', 'disabled', 'disable-keyboard', 'disablekeyboard', 'options', 'label-for', 'labelfor', 'ghost-class', 'ghostclass', 'chosen-class', 'chosenclass', 'drag-class', 'dragclass', 'filter', 'easing', 'force-fallback', 'forcefallback', 'swap-threshold', 'swapthreshold', 'cloneable', 'list-class', 'listclass', 'item-class', 'itemclass', 'item-style', 'itemstyle']);
+    const __skip = new Set<string>(['data-rozie-ref', 'items', 'item-key', 'itemkey', 'handle', 'group', 'animation', 'disabled', 'disable-keyboard', 'disablekeyboard', 'options', 'label-for', 'labelfor', 'ghost-class', 'ghostclass', 'chosen-class', 'chosenclass', 'drag-class', 'dragclass', 'filter', 'easing', 'force-fallback', 'forcefallback', 'swap-threshold', 'swapthreshold', 'cloneable', 'list-class', 'listclass', 'item-class', 'itemclass', 'item-style', 'itemstyle']);
     const out: Record<string, string> = {};
     for (const a of Array.from(this.attributes)) {
       if (__skip.has(a.name)) continue;