@threadlabs/looma 0.1.22 → 0.1.24

package/dist/collection/components/ui-tree/ui-tree.js

@@ -5,10 +5,17 @@ export class UITree {
     host;
     label = 'Tree';
     hoverExpandDelay = 700;
+    /** Maximum resulting item depth accepted by pointer reordering. Zero is unlimited. */
+    maxDepth = 0;
     source = null;
     target = null;
     position = null;
+    rejectedTarget = null;
+    rejectedPosition = null;
+    rejection = null;
     hoverIntent = null;
+    structureObserver = null;
+    tabStop = null;
     componentDidLoad() {
         this.hoverIntent = createHoverIntent(this.hoverExpandDelay, this.expandTarget);
         this.host.addEventListener('dragstart', this.onDragStart);
@@ -19,6 +26,11 @@ export class UITree {
         this.host.addEventListener('drop', this.onDrop);
         this.host.addEventListener('dragend', this.onDragEnd);
         this.host.addEventListener('keydown', this.onKeyDown);
+        this.host.addEventListener('focusin', this.onFocusIn);
+        this.host.addEventListener('ui-tree-expansion-change', this.onExpansionChange);
+        this.syncStructuralLevels();
+        this.structureObserver = new MutationObserver(this.syncStructuralLevels);
+        this.structureObserver.observe(this.host, { childList: true, subtree: true });
     }
     disconnectedCallback() {
         this.hoverIntent?.destroy();
@@ -30,10 +42,44 @@ export class UITree {
         this.host.removeEventListener('drop', this.onDrop);
         this.host.removeEventListener('dragend', this.onDragEnd);
         this.host.removeEventListener('keydown', this.onKeyDown);
+        this.host.removeEventListener('focusin', this.onFocusIn);
+        this.host.removeEventListener('ui-tree-expansion-change', this.onExpansionChange);
+        this.structureObserver?.disconnect();
+        this.structureObserver = null;
+    }
+    syncStructuralLevels = () => {
+        for (const item of Array.from(this.host.querySelectorAll('ui-tree-item'))) {
+            item.dispatchEvent(new CustomEvent('ui-tree-structure-sync'));
+        }
+        this.syncTabStop();
+    };
+    syncTabStop(preferred) {
+        const items = this.visibleItems();
+        const next = preferred && items.includes(preferred)
+            ? preferred
+            : this.tabStop && items.includes(this.tabStop)
+                ? this.tabStop
+                : items[0] ?? null;
+        this.tabStop = next;
+        for (const item of items) {
+            item.dispatchEvent(new CustomEvent('ui-tree-roving-tab-stop', {
+                detail: { active: item === next },
+            }));
+        }
     }
     itemFromEvent(event) {
         return event.composedPath().find(node => (node instanceof HTMLElement && node.localName === 'ui-tree-item')) ?? null;
     }
+    eventTargetsInteractiveContent(event) {
+        for (const node of event.composedPath()) {
+            if (node instanceof HTMLElement && node.localName === 'ui-tree-item')
+                break;
+            if (node instanceof HTMLElement && node.matches('a, button, input, select, textarea, [role="button"], [role="link"]')) {
+                return true;
+            }
+        }
+        return false;
+    }
     itemId(item) {
         return item.itemId || item.getAttribute('item-id') || '';
     }
@@ -75,19 +121,56 @@ export class UITree {
                 .filter(Boolean),
         };
     }
-    permitsDrop(source, target, position) {
+    constraintDepth(item) {
+        if (item.dropDepth !== undefined)
+            return item.dropDepth;
+        const dropDepth = item.getAttribute('drop-depth');
+        if (dropDepth !== null)
+            return Number(dropDepth);
+        return Number(item.getAttribute('aria-level')) || 1;
+    }
+    subtreeDepth(item) {
+        if (item.subtreeDepth !== undefined)
+            return Math.max(0, Math.floor(item.subtreeDepth));
+        const override = item.getAttribute('subtree-depth');
+        if (override !== null)
+            return Math.max(0, Math.floor(Number(override)));
+        return Array.from(item.querySelectorAll('ui-tree-item')).reduce((deepest, descendant) => {
+            let nesting = 0;
+            let ancestor = descendant.parentElement?.closest('ui-tree-item') ?? null;
+            while (ancestor && ancestor !== item) {
+                nesting += 1;
+                ancestor = ancestor.parentElement?.closest('ui-tree-item') ?? null;
+            }
+            return ancestor === item ? Math.max(deepest, nesting + 1) : deepest;
+        }, 0);
+    }
+    dropRejection(source, target, position) {
         // A tree item can never move into (or beside) one of its own descendants.
         // Reject the target before showing any insertion affordance so the preview
         // stays truthful instead of promising a move the consumer must undo.
         if (source.contains(target))
-            return false;
+            return { reason: 'descendant' };
         const sourceMeta = this.itemMetadata(source);
         const targetMeta = this.itemMetadata(target);
         if (position === 'inside') {
-            return this.acceptsChildren(target)
-                && (targetMeta.accepts.length === 0 || targetMeta.accepts.includes(sourceMeta.type));
+            if (!this.acceptsChildren(target)
+                || (targetMeta.accepts.length > 0 && !targetMeta.accepts.includes(sourceMeta.type))) {
+                return { reason: 'incompatible' };
+            }
+        }
+        else if (sourceMeta.type !== targetMeta.type) {
+            return { reason: 'incompatible' };
         }
-        return sourceMeta.type === targetMeta.type;
+        const maxDepth = Math.max(0, Math.floor(this.maxDepth));
+        if (maxDepth > 0) {
+            const targetDepth = Math.max(0, Math.floor(this.constraintDepth(target)));
+            const subtreeDepth = this.subtreeDepth(source);
+            const resultingDepth = targetDepth + (position === 'inside' ? 1 : 0) + subtreeDepth;
+            if (resultingDepth > maxDepth)
+                return { reason: 'max-depth', maxDepth, resultingDepth };
+        }
+        return null;
     }
     clearTarget() {
         this.target?.removeAttribute('data-drop-position');
@@ -95,10 +178,16 @@ export class UITree {
         this.position = null;
         this.hoverIntent?.cancel();
     }
+    clearRejection() {
+        this.rejectedTarget = null;
+        this.rejectedPosition = null;
+        this.rejection = null;
+    }
     finishDrag() {
         this.source?.removeAttribute('data-dragging');
         this.source = null;
         this.clearTarget();
+        this.clearRejection();
     }
     expandTarget = (itemId) => {
         const item = Array.from(this.host.querySelectorAll('ui-tree-item'))
@@ -136,18 +225,29 @@ export class UITree {
             return false;
         if (!target || target === this.source) {
             this.clearTarget();
+            this.clearRejection();
             return false;
         }
         const row = this.rowFor(target);
         if (!row)
             return false;
         const position = classifyDropPosition(row.getBoundingClientRect(), clientY, this.acceptsChildren(target));
-        if (!this.permitsDrop(this.source, target, position)) {
+        const rejection = this.dropRejection(this.source, target, position);
+        if (rejection) {
             if (dataTransfer)
                 dataTransfer.dropEffect = 'none';
             this.clearTarget();
+            if (rejection.reason === 'max-depth') {
+                this.rejectedTarget = target;
+                this.rejectedPosition = position;
+                this.rejection = rejection;
+            }
+            else {
+                this.clearRejection();
+            }
             return false;
         }
+        this.clearRejection();
         if (dataTransfer)
             dataTransfer.dropEffect = 'move';
         if (this.target !== target || this.position !== position) {
@@ -189,12 +289,15 @@ export class UITree {
         if (this.itemAtPoint(event.clientX, event.clientY))
             return;
         this.clearTarget();
+        this.clearRejection();
     };
     dispatchReorder(source, target, position) {
         const sourceId = this.itemId(source);
         const targetId = this.itemId(target);
         if (!sourceId || !targetId)
             return;
+        if (position === 'inside')
+            this.expandTarget(targetId);
         const sourceMeta = this.itemMetadata(source);
         const targetMeta = this.itemMetadata(target);
         dispatchDetail(this.host, 'reorder', {
@@ -208,6 +311,21 @@ export class UITree {
             trigger: 'pointer',
         });
     }
+    dispatchReorderRejected(source, target, position, rejection) {
+        const sourceId = this.itemId(source);
+        const targetId = this.itemId(target);
+        if (!sourceId || !targetId)
+            return;
+        dispatchDetail(this.host, 'reorder-rejected', {
+            sourceId,
+            targetId,
+            position,
+            reason: 'max-depth',
+            maxDepth: rejection.maxDepth,
+            resultingDepth: rejection.resultingDepth,
+            trigger: 'pointer',
+        });
+    }
     onDrop = (event) => {
         if (!this.source || !this.target || !this.position)
             return;
@@ -217,14 +335,23 @@ export class UITree {
     };
     onDragEnd = (event) => {
         if (this.source) {
+            if (this.rejectedTarget && this.rejectedPosition && this.rejection) {
+                this.dispatchReorderRejected(this.source, this.rejectedTarget, this.rejectedPosition, this.rejection);
+                this.finishDrag();
+                return;
+            }
             const target = this.itemAtPoint(event.clientX, event.clientY);
             if (target && target !== this.source) {
                 const row = this.rowFor(target);
                 if (row) {
                     const position = classifyDropPosition(row.getBoundingClientRect(), event.clientY, this.acceptsChildren(target));
-                    if (this.permitsDrop(this.source, target, position)) {
+                    const rejection = this.dropRejection(this.source, target, position);
+                    if (!rejection) {
                         this.dispatchReorder(this.source, target, position);
                     }
+                    else if (rejection.reason === 'max-depth') {
+                        this.dispatchReorderRejected(this.source, target, position, rejection);
+                    }
                 }
             }
         }
@@ -234,7 +361,35 @@ export class UITree {
         return Array.from(this.host.querySelectorAll('ui-tree-item'))
             .filter(item => item.getClientRects().length > 0 && !item.hasAttribute('disabled'));
     }
+    parentItem(item) {
+        const parent = item.parentElement?.closest('ui-tree-item') ?? null;
+        return parent && this.host.contains(parent) ? parent : null;
+    }
+    firstVisibleChild(item, items) {
+        return items.find(candidate => this.parentItem(candidate) === item) ?? null;
+    }
+    focusItem(item) {
+        this.syncTabStop(item);
+        item.focus();
+    }
+    requestExpansion(item, expanded) {
+        item.dispatchEvent(new CustomEvent('ui-tree-request-expanded', {
+            detail: { expanded, trigger: 'keyboard' },
+        }));
+    }
+    onFocusIn = (event) => {
+        if (this.eventTargetsInteractiveContent(event))
+            return;
+        const item = this.itemFromEvent(event);
+        if (item)
+            this.syncTabStop(item);
+    };
+    onExpansionChange = () => {
+        requestAnimationFrame(() => this.syncTabStop());
+    };
     onKeyDown = (event) => {
+        if (this.eventTargetsInteractiveContent(event))
+            return;
         const current = this.itemFromEvent(event);
         if (!current)
             return;
@@ -242,14 +397,43 @@ export class UITree {
         const index = items.indexOf(current);
         if (index < 0)
             return;
-        const next = event.key === 'ArrowDown' ? items[index + 1] : event.key === 'ArrowUp' ? items[index - 1] : null;
-        if (!next)
+        const next = event.key === 'ArrowDown' ? items[index + 1]
+            : event.key === 'ArrowUp' ? items[index - 1]
+                : event.key === 'Home' ? items[0]
+                    : event.key === 'End' ? items.at(-1)
+                        : null;
+        if (next) {
+            event.preventDefault();
+            this.focusItem(next);
             return;
-        event.preventDefault();
-        next.focus();
+        }
+        if (event.key === 'ArrowLeft') {
+            if (current.getAttribute('aria-expanded') === 'true') {
+                event.preventDefault();
+                this.requestExpansion(current, false);
+            }
+            else if (this.parentItem(current)) {
+                event.preventDefault();
+                this.focusItem(this.parentItem(current));
+            }
+            return;
+        }
+        if (event.key === 'ArrowRight') {
+            if (current.getAttribute('aria-expanded') === 'false') {
+                event.preventDefault();
+                this.requestExpansion(current, true);
+            }
+            else if (current.getAttribute('aria-expanded') === 'true') {
+                const child = this.firstVisibleChild(current, items);
+                if (child) {
+                    event.preventDefault();
+                    this.focusItem(child);
+                }
+            }
+        }
     };
     render() {
-        return (h(Host, { key: '7da064127eb199f5e2cfc59489a07204c9dac2f2', role: "tree", "aria-label": this.label || 'Tree' }, h("slot", { key: '31a98a6774ab35e565dab65f1dd8202494432b32' })));
+        return (h(Host, { key: '549c09abc67dc60b16bf2d6b7d6346f214e9d6ae', role: "tree", "aria-label": this.label || 'Tree' }, h("slot", { key: 'fea59bde97611bf384e32ce4fb2b3eec9aca784f' })));
     }
     static get is() { return "ui-tree"; }
     static get encapsulation() { return "shadow"; }
@@ -304,6 +488,26 @@ export class UITree {
                 "reflect": false,
                 "attribute": "hover-expand-delay",
                 "defaultValue": "700"
+            },
+            "maxDepth": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Maximum resulting item depth accepted by pointer reordering. Zero is unlimited."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "max-depth",
+                "defaultValue": "0"
             }
         };
     }

package/dist/collection/components/ui-tree-item/ui-tree-item.js

@@ -7,8 +7,10 @@ export class UITreeItem {
     itemId = '';
     /** Accessible name used by the disclosure and drag handle. */
     label = '';
-    /** One-based visual and semantic nesting level. */
-    depth = 1;
+    /** Application hierarchy depth override used for drop constraints. Defaults to structural nesting. */
+    dropDepth;
+    /** Virtualized-tree descendant-depth override for the tree's max-depth drop constraint. */
+    subtreeDepth;
     /** Whether this item accepts children and exposes disclosure behavior. */
     container = false;
     /** Whether this item participates in pointer drag and drop. */
@@ -19,37 +21,74 @@ export class UITreeItem {
     dropScope = '';
     /** Comma-separated drag kinds accepted as children. Empty accepts every kind. */
     accepts = '';
-    /** Initial controlled expansion value. */
-    expanded = false;
+    /** Controlled expansion value. When omitted, `default-expanded` initializes uncontrolled state. */
+    expanded;
     /** Initial uncontrolled expansion value. */
     defaultExpanded = false;
     selected = false;
     disabled = false;
     internalExpanded = false;
+    structuralLevel = 1;
+    tabStop = false;
     syncExpandedFromProp() {
-        this.internalExpanded = this.expanded;
+        // A defined prop owns the rendered state; clearing it resumes the current
+        // uncontrolled state instead of replaying the initial default.
+        if (this.expanded !== undefined)
+            this.internalExpanded = this.expanded;
     }
     componentWillLoad() {
-        this.internalExpanded = this.expanded || this.defaultExpanded;
+        this.internalExpanded = this.expanded ?? this.defaultExpanded;
+        this.updateStructuralLevel();
     }
-    componentDidLoad() {
+    connectedCallback() {
         this.host.addEventListener('ui-tree-auto-expand', this.onAutoExpand);
+        this.host.addEventListener('ui-tree-structure-sync', this.updateStructuralLevel);
+        this.host.addEventListener('ui-tree-roving-tab-stop', this.onRovingTabStop);
+        this.host.addEventListener('ui-tree-request-expanded', this.onExpansionRequest);
     }
     disconnectedCallback() {
         this.host.removeEventListener('ui-tree-auto-expand', this.onAutoExpand);
+        this.host.removeEventListener('ui-tree-structure-sync', this.updateStructuralLevel);
+        this.host.removeEventListener('ui-tree-roving-tab-stop', this.onRovingTabStop);
+        this.host.removeEventListener('ui-tree-request-expanded', this.onExpansionRequest);
     }
+    updateStructuralLevel = () => {
+        const tree = this.host.closest('ui-tree');
+        let ancestor = this.host.parentElement?.closest('ui-tree-item') ?? null;
+        let level = 1;
+        while (ancestor && tree?.contains(ancestor)) {
+            level += 1;
+            ancestor = ancestor.parentElement?.closest('ui-tree-item') ?? null;
+        }
+        if (this.structuralLevel !== level)
+            this.structuralLevel = level;
+    };
     setExpanded(expanded, trigger) {
-        if (!this.container || this.disabled || this.internalExpanded === expanded)
+        const current = this.isExpanded();
+        if (!this.container || this.disabled || current === expanded)
             return;
-        this.internalExpanded = expanded;
+        if (this.expanded === undefined)
+            this.internalExpanded = expanded;
         dispatchDetail(this.host, 'expand', { id: this.itemId, expanded, trigger });
+        this.host.dispatchEvent(new CustomEvent('ui-tree-expansion-change'));
+    }
+    isExpanded() {
+        return this.expanded ?? this.internalExpanded;
     }
     onAutoExpand = () => {
         this.setExpanded(true, 'pointer');
     };
+    onRovingTabStop = (event) => {
+        this.tabStop = Boolean(event.detail?.active) && !this.disabled;
+    };
+    onExpansionRequest = (event) => {
+        const detail = event.detail;
+        if (typeof detail?.expanded === 'boolean')
+            this.setExpanded(detail.expanded, detail.trigger ?? 'keyboard');
+    };
     onDisclosureClick = (event) => {
         event.stopPropagation();
-        this.setExpanded(!this.internalExpanded, eventToTrigger(event));
+        this.setExpanded(!this.isExpanded(), eventToTrigger(event));
     };
     onDisclosureKeydown = (event) => {
         if (event.key !== 'ArrowRight' && event.key !== 'ArrowLeft')
@@ -65,16 +104,17 @@ export class UITreeItem {
         const interactive = path.some((node) => node instanceof HTMLElement && (node.matches('a, button, input, select, textarea, [role="button"], [role="link"]')
             || node.getAttribute('slot') === 'actions'));
         if (!interactive)
-            this.setExpanded(!this.internalExpanded, eventToTrigger(event));
+            this.setExpanded(!this.isExpanded(), eventToTrigger(event));
     };
     render() {
-        const level = Math.max(1, Math.floor(this.depth));
-        const disclosureLabel = `${this.internalExpanded ? 'Collapse' : 'Expand'} ${this.label || 'item'}`;
+        const level = this.structuralLevel;
+        const expanded = this.isExpanded();
+        const disclosureLabel = `${expanded ? 'Collapse' : 'Expand'} ${this.label || 'item'}`;
         const dragLabel = `Drag ${this.label || 'item'} to reorder`;
-        return (h(Host, { key: 'ea8ed538aa3883c87257a25614a066965364693f', role: "treeitem", "aria-level": String(level), "aria-expanded": this.container ? String(this.internalExpanded) : undefined, "aria-selected": String(this.selected), "aria-disabled": this.disabled ? 'true' : undefined, "data-container": this.container ? '' : undefined, "data-selected": this.selected ? '' : undefined, "data-disabled": this.disabled ? '' : undefined, "data-drag-type": this.dragType || 'item', "data-drop-scope": this.dropScope || undefined, "data-accepts": this.accepts || undefined, tabIndex: this.disabled ? -1 : 0, style: {
+        return (h(Host, { key: '36ad9eac3e0fe2a606e63294891b1c0697034b46', role: "treeitem", "aria-label": this.label || undefined, "aria-level": String(level), "aria-expanded": this.container ? String(expanded) : undefined, "aria-selected": String(this.selected), "aria-disabled": this.disabled ? 'true' : undefined, "data-container": this.container ? '' : undefined, "data-selected": this.selected ? '' : undefined, "data-disabled": this.disabled ? '' : undefined, "data-drag-type": this.dragType || 'item', "data-drop-scope": this.dropScope || undefined, "data-accepts": this.accepts || undefined, tabIndex: this.disabled || !this.tabStop ? -1 : 0, style: {
                 '--ui-tree-item-depth': String(level - 1),
                 'margin-inline-start': level > 1 ? 'var(--ui-tree-indent, 16px)' : '0px',
-            } }, h("div", { key: '740b93aa47e65d8a1cb899d4b9c966d9ad1d456f', class: "row", part: "row", onClick: this.onRowClick }, this.sortable && !this.disabled ? (h("button", { class: "drag-handle", part: "drag-handle", type: "button", draggable: true, "aria-label": dragLabel, title: dragLabel }, h("span", { innerHTML: loomaIconMarkup('grip-vertical') }))) : null, this.container ? (h("button", { class: "disclosure", part: "disclosure", type: "button", "aria-label": disclosureLabel, "aria-expanded": String(this.internalExpanded), disabled: this.disabled, onClick: this.onDisclosureClick, onKeyDown: this.onDisclosureKeydown }, h("span", { class: { 'disclosure-icon': true, 'disclosure-icon--expanded': this.internalExpanded }, innerHTML: loomaIconMarkup('chevron-down') }))) : h("span", { class: "disclosure-spacer", "aria-hidden": "true" }), h("span", { key: '37e1b7f1cdddf623734becef465ffde83d8b86f2', class: "leading", part: "leading" }, h("slot", { key: '0ab3a60c98628f009918d0d720772154912d2709', name: "leading" })), h("span", { key: 'defdd343f25a0f4354110e981f3889e1d09c27ee', class: "label", part: "label" }, h("slot", { key: 'bde46ccacc1a620348062fc300503c4f1736316b' })), h("span", { key: 'caff9ada38c41be90aeb6e331f4c54a51f31d26c', class: "actions", part: "actions" }, h("slot", { key: 'e11704d6871445c91eaa29c99302d8b751be69d3', name: "actions" })), h("span", { key: '9efc0e95588f1dd4527dade2b7ff9f2774462c2e', class: "drop-indicator row-drop-indicator", part: "drop-indicator", "aria-hidden": "true" })), this.container ? (h("div", { class: "children", part: "children", role: "group", hidden: !this.internalExpanded }, h("slot", { name: "children" }))) : null, h("span", { key: '8893ec2c4082bb8af942ef563055a2910d0d4201', class: "drop-indicator subtree-drop-indicator", part: "drop-indicator", "aria-hidden": "true" })));
+            } }, h("div", { key: 'e92f5bc73accef3b348559ea144e0b769c98c721', class: "row", part: "row", onClick: this.onRowClick }, this.sortable && !this.disabled ? (h("button", { class: "drag-handle", part: "drag-handle", type: "button", draggable: true, "aria-label": dragLabel, title: dragLabel }, h("span", { innerHTML: loomaIconMarkup('grip-vertical') }))) : null, this.container ? (h("button", { class: "disclosure", part: "disclosure", type: "button", "aria-label": disclosureLabel, "aria-expanded": String(expanded), disabled: this.disabled, onClick: this.onDisclosureClick, onKeyDown: this.onDisclosureKeydown }, h("span", { class: { 'disclosure-icon': true, 'disclosure-icon--expanded': expanded }, innerHTML: loomaIconMarkup('chevron-down') }))) : h("span", { class: "disclosure-spacer", "aria-hidden": "true" }), h("span", { key: 'dd2d0550d6846d0a4f80a4108968bfc32c18658f', class: "leading", part: "leading" }, h("slot", { key: '622d449a338dce57bc2e64aaf776471e8d3ce1b4', name: "leading" })), h("span", { key: '29c3e6ace4838ab941ada2547356288358faaeb2', class: "label", part: "label" }, h("slot", { key: 'f1594c11fa0b9fbe8a3c20df6edce19421cab148' })), h("span", { key: 'e4a6408f86b58a325145e713d116fc09322bb0d3', class: "actions", part: "actions" }, h("slot", { key: 'ff3afaf1089426e19ee1fc39c6567c3d40ca4272', name: "actions" })), h("span", { key: 'efcf23f7aad6c4353fa24bfe2a81001122335f72', class: "drop-indicator row-drop-indicator", part: "drop-indicator", "aria-hidden": "true" })), this.container ? (h("div", { class: "children", part: "children", role: "group", hidden: !expanded }, h("slot", { name: "children" }))) : null, h("span", { key: '21bfc8a6ad6e487cd044b5a3cbd7e8f900f2d1e1', class: "drop-indicator subtree-drop-indicator", part: "drop-indicator", "aria-hidden": "true" })));
     }
     static get is() { return "ui-tree-item"; }
     static get encapsulation() { return "shadow"; }
@@ -130,7 +170,7 @@ export class UITreeItem {
                 "attribute": "label",
                 "defaultValue": "''"
             },
-            "depth": {
+            "dropDepth": {
                 "type": "number",
                 "mutable": false,
                 "complexType": {
@@ -139,16 +179,34 @@ export class UITreeItem {
                     "references": {}
                 },
                 "required": false,
-                "optional": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Application hierarchy depth override used for drop constraints. Defaults to structural nesting."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "drop-depth"
+            },
+            "subtreeDepth": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "One-based visual and semantic nesting level."
+                    "text": "Virtualized-tree descendant-depth override for the tree's max-depth drop constraint."
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": false,
-                "attribute": "depth",
-                "defaultValue": "1"
+                "attribute": "subtree-depth"
             },
             "container": {
                 "type": "boolean",
@@ -259,16 +317,15 @@ export class UITreeItem {
                     "references": {}
                 },
                 "required": false,
-                "optional": false,
+                "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "Initial controlled expansion value."
+                    "text": "Controlled expansion value. When omitted, `default-expanded` initializes uncontrolled state."
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": false,
-                "attribute": "expanded",
-                "defaultValue": "false"
+                "attribute": "expanded"
             },
             "defaultExpanded": {
                 "type": "boolean",
@@ -334,7 +391,9 @@ export class UITreeItem {
     }
     static get states() {
         return {
-            "internalExpanded": {}
+            "internalExpanded": {},
+            "structuralLevel": {},
+            "tabStop": {}
         };
     }
     static get elementRef() { return "host"; }

package/dist/collection/field/combobox.js

@@ -0,0 +1,4 @@
+/** Map domain records at the boundary, preserving typed metadata for rich rows. */
+export function mapComboboxOptions(rows, map) {
+    return rows.map(row => ({ ...map(row), metadata: row }));
+}

package/dist/collection/field/valibot.js

@@ -0,0 +1,5 @@
+/** Valibot's Standard Schema implementation preserves async transforms and issue paths.
+ * Type-only Valibot imports keep the adapter free of a schema-library runtime. */
+export function valibotField(schema, options = {}) {
+    return { ...options, schema };
+}

package/dist/collection/field/validation.js

@@ -0,0 +1,62 @@
+/** Formatting is additive: every original character must survive in order.
+ * Normalization belongs to submitted output, never the visible editing buffer. */
+export function formatEditingValue(raw, selection, format) {
+    const unchanged = { display: raw, selection };
+    if (!format)
+        return unchanged;
+    let result;
+    try {
+        result = format(raw, selection);
+    }
+    catch {
+        return unchanged;
+    }
+    if (!result)
+        return unchanged;
+    const characters = Array.from(raw);
+    let cursor = 0;
+    for (const character of result.display)
+        if (character === characters[cursor])
+            cursor += 1;
+    if (!Number.isInteger(result.selection.start) || !Number.isInteger(result.selection.end) || cursor !== characters.length || result.selection.start < 0 || result.selection.end < result.selection.start
+        || result.selection.end > result.display.length)
+        return unchanged;
+    return result;
+}
+export async function validateField(request, config) {
+    let output = request.raw;
+    let issues = [];
+    const check = () => request.signal.throwIfAborted();
+    try {
+        check();
+        if (config.parse)
+            output = await config.parse(request.raw, request);
+        check();
+        if (config.schema) {
+            const result = await config.schema['~standard'].validate(output);
+            check();
+            if (result.issues)
+                issues = result.issues;
+            else if ('value' in result)
+                output = result.value;
+        }
+        if (!issues.some(issue => issue.severity !== 'warning')) {
+            if (config.normalize)
+                output = await config.normalize(output, request);
+            check();
+            if (config.validator) {
+                const result = await config.validator(output, request);
+                check();
+                issues = [...issues, ...(result.issues ?? [])];
+                if ('output' in result)
+                    output = result.output;
+            }
+        }
+    }
+    catch (error) {
+        check();
+        issues = [{ message: error instanceof Error ? error.message : 'Unable to validate this value.' }];
+    }
+    issues = [...issues, ...(config.issues ?? [])];
+    return { output: issues.some(issue => issue.severity !== 'warning') ? undefined : output, issues };
+}