luxen-ui 0.9.0 → 0.9.2

package/dist/elements/tree/tree.d.ts

@@ -5,6 +5,9 @@ export type TreeSelection = 'single' | 'multiple' | 'leaf' | 'none';
 /**
  * A hierarchical tree view composed of `<l-tree-item>` children.
  *
+ * The host carries `role="tree"`, so give it an accessible name with
+ * `aria-label` or `aria-labelledby` (e.g. `<l-tree aria-label="Files">`).
+ *
  * @slot - One or more `l-tree-item` elements.
  *
  * @csspart base - The root tree container.
@@ -24,6 +27,7 @@ export type TreeSelection = 'single' | 'multiple' | 'leaf' | 'none';
  */
 export declare class Tree extends LuxenElement {
     static styles: import("lit").CSSResult[];
+    private _internals;
     private _mutationObserver?;
     private _lastFocusedItem;
     /**
@@ -54,7 +58,13 @@ export declare class Tree extends LuxenElement {
     /** Collapses every item. */
     collapseAll(): void;
     private _syncAll;
-    private _syncSubtree;
+    /**
+     * Sync depth, checkbox visibility and ARIA position for a sibling group, then
+     * recurse. `aria-level`/`aria-setsize`/`aria-posinset` let screen readers
+     * announce "level N, M of K" — valuable here because `lazy` items mean the
+     * full set isn't always in the DOM (see WAI-ARIA Tree View pattern).
+     */
+    private _syncLevel;
     private _canShowCheckboxOn;
     private _rootItems;
     private _ensureTabStop;

package/dist/elements/tree/tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../src/html/elements/tree/tree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAM1D,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,IAAK,SAAQ,YAAY;IACpC,OAAgB,MAAM,4BAAwB;IAE9C,OAAO,CAAC,iBAAiB,CAAC,CAAmB;IAC7C,OAAO,CAAC,gBAAgB,CAAyB;IAEjD;;;;;;OAMG;IAEH,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAY;IAE7C;;;;OAIG;IAEH,QAAQ,CAAC,WAAW,UAAS;IAEpB,iBAAiB;IAUjB,oBAAoB;IAMpB,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC;IAQ9C,yEAAyE;IACzE,WAAW,CAAC,EAAE,eAAsB,EAAE;;KAAK,GAAG,QAAQ,EAAE;IAOxD,wCAAwC;IACxC,YAAY,IAAI,QAAQ,EAAE;IAI1B,4CAA4C;IAC5C,SAAS;IAMT,4BAA4B;IAC5B,WAAW;IAQX,OAAO,CAAC,QAAQ;IAsBhB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,cAAc;IAUtB,2DAA2D;IAC3D,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,aAAa,CAGnB;IAEF,OAAO,CAAC,kBAAkB;IAoB1B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,oBAAoB;IAS5B,0EAA0E;IAC1E,OAAO,CAAC,mBAAmB;IA6B3B,OAAO,CAAC,oBAAoB;IAM5B,OAAO,CAAC,QAAQ,CAqDd;IAEF,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,UAAU,CAMhB;IAEF,OAAO,CAAC,UAAU,CAqEhB;IAEO,MAAM;CAehB"}
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../src/html/elements/tree/tree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAM1D,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,IAAK,SAAQ,YAAY;IACpC,OAAgB,MAAM,4BAAwB;IAE9C,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,iBAAiB,CAAC,CAAmB;IAC7C,OAAO,CAAC,gBAAgB,CAAyB;IAEjD;;;;;;OAMG;IAEH,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAY;IAE7C;;;;OAIG;IAEH,QAAQ,CAAC,WAAW,UAAS;IAEpB,iBAAiB;IAgBjB,oBAAoB;IAMpB,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC;IAe9C,yEAAyE;IACzE,WAAW,CAAC,EAAE,eAAsB,EAAE;;KAAK,GAAG,QAAQ,EAAE;IAOxD,wCAAwC;IACxC,YAAY,IAAI,QAAQ,EAAE;IAI1B,4CAA4C;IAC5C,SAAS;IAMT,4BAA4B;IAC5B,WAAW;IAQX,OAAO,CAAC,QAAQ;IAoBhB;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,cAAc;IAUtB,2DAA2D;IAC3D,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,aAAa,CAGnB;IAEF,OAAO,CAAC,kBAAkB;IAuB1B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,oBAAoB;IAS5B,0EAA0E;IAC1E,OAAO,CAAC,mBAAmB;IA6B3B,OAAO,CAAC,oBAAoB;IAM5B,OAAO,CAAC,QAAQ,CAqDd;IAEF,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,UAAU,CAMhB;IAEF,OAAO,CAAC,UAAU,CAqEhB;IAEO,MAAM;CAahB"}

package/dist/elements/tree/tree.js

@@ -26,6 +26,9 @@ const styles = unsafeCSS(rawStyles);
 /**
  * A hierarchical tree view composed of `<l-tree-item>` children.
  *
+ * The host carries `role="tree"`, so give it an accessible name with
+ * `aria-label` or `aria-labelledby` (e.g. `<l-tree aria-label="Files">`).
+ *
  * @slot - One or more `l-tree-item` elements.
  *
  * @csspart base - The root tree container.
@@ -46,6 +49,7 @@ const styles = unsafeCSS(rawStyles);
 export class Tree extends LuxenElement {
     constructor() {
         super(...arguments);
+        this._internals = this.attachInternals();
         this._lastFocusedItem = null;
         _Tree_selection_accessor_storage.set(this, 'single');
         _Tree_independent_accessor_storage.set(this, false);
@@ -214,6 +218,13 @@ export class Tree extends LuxenElement {
     set independent(value) { __classPrivateFieldSet(this, _Tree_independent_accessor_storage, value, "f"); }
     connectedCallback() {
         super.connectedCallback();
+        this._internals.role = 'tree';
+        // Mirror the role to a DOM attribute too. The ElementInternals role alone is
+        // not `[role]`-selectable (CSS, querySelector, Cypress/Playwright CSS), which
+        // silently breaks consumers migrating from libraries that expose an attribute
+        // role. Respect an author-provided role if one is already set.
+        if (!this.hasAttribute('role'))
+            this.setAttribute('role', 'tree');
         this._mutationObserver = new MutationObserver(() => this._syncAll());
         this._mutationObserver.observe(this, { childList: true, subtree: true });
         this.addEventListener('l-tree-item-toggle', this._onItemToggle);
@@ -226,6 +237,13 @@ export class Tree extends LuxenElement {
         this.removeEventListener('l-tree-item-toggle', this._onItemToggle);
     }
     updated(changed) {
+        if (changed.has('selection')) {
+            // Mirror to ElementInternals (a11y tree) and a content attribute, so
+            // `[aria-multiselectable]` selectors keep matching — see tree-item `_aria`.
+            const multiselectable = this.selection === 'multiple' ? 'true' : 'false';
+            this._internals.ariaMultiSelectable = multiselectable;
+            this.setAttribute('aria-multiselectable', multiselectable);
+        }
         if (changed.has('selection') || changed.has('independent')) {
             this._syncAll();
         }
@@ -267,19 +285,25 @@ export class Tree extends LuxenElement {
             return;
         }
         const showCheckbox = this.selection === 'multiple';
-        for (const root of roots) {
-            this._syncSubtree(root, 0, showCheckbox);
-        }
+        this._syncLevel(roots, 0, showCheckbox);
         this._updateBranchStates();
         // Ensure at least one item is tabbable.
         this._ensureTabStop();
     }
-    _syncSubtree(item, depth, showCheckbox) {
-        item.depth = depth;
-        item.showCheckbox = showCheckbox && this._canShowCheckboxOn(item);
-        for (const child of item.getChildrenItems()) {
-            this._syncSubtree(child, depth + 1, showCheckbox);
-        }
+    /**
+     * Sync depth, checkbox visibility and ARIA position for a sibling group, then
+     * recurse. `aria-level`/`aria-setsize`/`aria-posinset` let screen readers
+     * announce "level N, M of K" — valuable here because `lazy` items mean the
+     * full set isn't always in the DOM (see WAI-ARIA Tree View pattern).
+     */
+    _syncLevel(items, depth, showCheckbox) {
+        const setSize = items.length;
+        items.forEach((item, index) => {
+            item.depth = depth;
+            item.showCheckbox = showCheckbox && this._canShowCheckboxOn(item);
+            item.setPosition(depth + 1, index + 1, setSize);
+            this._syncLevel(item.getChildrenItems(), depth + 1, showCheckbox);
+        });
     }
     _canShowCheckboxOn(_item) {
         if (this.selection !== 'multiple')
@@ -322,6 +346,10 @@ export class Tree extends LuxenElement {
         switch (this.selection) {
             case 'single':
                 this._setSingleSelection(item);
+                // Mirror the row-click behaviour: activating a branch also toggles it,
+                // so keyboard users expand lazy branches (and trigger their fetch) too.
+                if (!item.isLeaf())
+                    item.toggle();
                 break;
             case 'leaf':
                 if (item.isLeaf())
@@ -421,8 +449,6 @@ export class Tree extends LuxenElement {
       <div
         class="tree"
         part="base"
-        role="tree"
-        aria-multiselectable=${this.selection === 'multiple' ? 'true' : 'false'}
         @click=${this._onClick}
         @keydown=${this._onKeyDown}
         @focusin=${this._onFocusIn}

package/dist/elements/tree-item/tree-item.css

@@ -3,6 +3,10 @@
   color: var(--l-color-text-primary, CanvasText);
   font-size: 0.875rem;
   line-height: 1.5;
+  /* The host is the roving-tabindex focus target, but the visible ring is drawn
+     on the inner `.item` row. Suppress the host's UA outline so it doesn't paint
+     a second ring around the whole subtree (row + children). */
+  outline: none;
 }
 
 :host([disabled]) {
@@ -31,7 +35,7 @@
 
 .item:focus-visible,
 :host(:focus-visible) .item {
-  outline: 2px solid var(--l-focus-ring, Highlight);
+  outline: 2px solid var(--l-focus-ring);
   outline-offset: 1px;
 }
 

package/dist/elements/tree-item/tree-item.d.ts

@@ -52,6 +52,13 @@ export declare class TreeItem extends LuxenElement {
     set depth(value: number);
     get depth(): number;
     private _depth;
+    /**
+     * Set by `<l-tree>`: ARIA position within the tree. `level` is 1-based depth,
+     * `posInSet`/`setSize` describe the item's rank among its siblings. These let
+     * screen readers announce "level 2, 3 of 5" even when `lazy` children keep the
+     * full set out of the DOM.
+     */
+    setPosition(level: number, posInSet: number, setSize: number): void;
     /** Whether this item has nested tree-item children. */
     get hasChildren(): boolean;
     private _hasChildren;
@@ -66,9 +73,18 @@ export declare class TreeItem extends LuxenElement {
     connectedCallback(): void;
     disconnectedCallback(): void;
     updated(changed: PropertyValues<this>): void;
+    /** Leaf items omit `aria-expanded` entirely; branches reflect their state. */
+    private _reflectExpanded;
+    /**
+     * Write an ARIA state to BOTH ElementInternals (the semantic source, in the
+     * accessibility tree) and a content attribute (so `[aria-*]` CSS / query / test
+     * selectors keep matching — same belt-and-suspenders as the mirrored `role`).
+     * A `null` value clears both.
+     */
+    private _aria;
     private _setState;
     private _syncChildren;
-    /** Toggle expand state. Emits `lazy-load` the first time a lazy item opens. */
+    /** Toggle expand state. Opening a `lazy` item emits `lazy-load` (via `updated`). */
     toggle(): void;
     private _onCheckboxChange;
     render(): import("lit").TemplateResult<1>;

package/dist/elements/tree-item/tree-item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tree-item.d.ts","sourceRoot":"","sources":["../../../src/html/elements/tree-item/tree-item.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAQ7D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,QAAS,SAAQ,YAAY;IACxC,OAAgB,MAAM,4BAA4C;IAElE,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,cAAc,CAAC,CAAmB;IAE1C,oCAAoC;IAEpC,QAAQ,CAAC,QAAQ,UAAS;IAE1B,oCAAoC;IAEpC,QAAQ,CAAC,QAAQ,UAAS;IAE1B,yEAAyE;IAEzE,QAAQ,CAAC,aAAa,UAAS;IAE/B,oCAAoC;IAEpC,QAAQ,CAAC,QAAQ,UAAS;IAE1B,8EAA8E;IAE9E,QAAQ,CAAC,IAAI,UAAS;IAEtB,+DAA+D;IAE/D,QAAQ,CAAC,OAAO,UAAS;IAEzB,sDAAsD;IACtD,IAAI,YAAY,CAAC,KAAK,EAAE,OAAO,EAG9B;IACD,IAAI,YAAY,IAAI,OAAO,CAE1B;IACD,OAAO,CAAC,aAAa,CAAS;IAE9B,mEAAmE;IACnE,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,EAGtB;IACD,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,OAAO,CAAC,MAAM,CAAK;IAEnB,uDAAuD;IACvD,IAAI,WAAW,IAAI,OAAO,CAEzB;IACD,OAAO,CAAC,YAAY,CAAS;IAE7B,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,eAAsB,EAAE;;KAAK,GAAG,QAAQ,EAAE;IAO7D,4DAA4D;IAC5D,MAAM,IAAI,OAAO;IAIjB,2CAA2C;IAC3C,YAAY,IAAI,MAAM;IAUb,iBAAiB;IAQjB,oBAAoB;IAKpB,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC;IAe9C,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,aAAa;IAmBrB,+EAA+E;IAC/E,MAAM;IASN,OAAO,CAAC,iBAAiB,CAUvB;IAEO,MAAM;CAwFhB"}
+{"version":3,"file":"tree-item.d.ts","sourceRoot":"","sources":["../../../src/html/elements/tree-item/tree-item.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAQ7D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,QAAS,SAAQ,YAAY;IACxC,OAAgB,MAAM,4BAA4C;IAElE,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,cAAc,CAAC,CAAmB;IAE1C,oCAAoC;IAEpC,QAAQ,CAAC,QAAQ,UAAS;IAE1B,oCAAoC;IAEpC,QAAQ,CAAC,QAAQ,UAAS;IAE1B,yEAAyE;IAEzE,QAAQ,CAAC,aAAa,UAAS;IAE/B,oCAAoC;IAEpC,QAAQ,CAAC,QAAQ,UAAS;IAE1B,8EAA8E;IAE9E,QAAQ,CAAC,IAAI,UAAS;IAEtB,+DAA+D;IAE/D,QAAQ,CAAC,OAAO,UAAS;IAEzB,sDAAsD;IACtD,IAAI,YAAY,CAAC,KAAK,EAAE,OAAO,EAG9B;IACD,IAAI,YAAY,IAAI,OAAO,CAE1B;IACD,OAAO,CAAC,aAAa,CAAS;IAE9B,mEAAmE;IACnE,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,EAGtB;IACD,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,OAAO,CAAC,MAAM,CAAK;IAEnB;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAM5D,uDAAuD;IACvD,IAAI,WAAW,IAAI,OAAO,CAEzB;IACD,OAAO,CAAC,YAAY,CAAS;IAE7B,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,eAAsB,EAAE;;KAAK,GAAG,QAAQ,EAAE;IAO7D,4DAA4D;IAC5D,MAAM,IAAI,OAAO;IAIjB,2CAA2C;IAC3C,YAAY,IAAI,MAAM;IAUb,iBAAiB;IAajB,oBAAoB;IAKpB,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC;IAwB9C,8EAA8E;IAC9E,OAAO,CAAC,gBAAgB;IAIxB;;;;;OAKG;IACH,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,aAAa;IAmBrB,oFAAoF;IACpF,MAAM;IAMN,OAAO,CAAC,iBAAiB,CAUvB;IAEO,MAAM;CAyFhB"}

package/dist/elements/tree-item/tree-item.js

@@ -109,6 +109,17 @@ export class TreeItem extends LuxenElement {
     get depth() {
         return this._depth;
     }
+    /**
+     * Set by `<l-tree>`: ARIA position within the tree. `level` is 1-based depth,
+     * `posInSet`/`setSize` describe the item's rank among its siblings. These let
+     * screen readers announce "level 2, 3 of 5" even when `lazy` children keep the
+     * full set out of the DOM.
+     */
+    setPosition(level, posInSet, setSize) {
+        this._aria('ariaLevel', 'aria-level', String(level));
+        this._aria('ariaPosInSet', 'aria-posinset', String(posInSet));
+        this._aria('ariaSetSize', 'aria-setsize', String(setSize));
+    }
     /** Whether this item has nested tree-item children. */
     get hasChildren() {
         return this._hasChildren;
@@ -136,6 +147,12 @@ export class TreeItem extends LuxenElement {
     connectedCallback() {
         super.connectedCallback();
         this._internals.role = 'treeitem';
+        // Mirror the role to a DOM attribute too, so `[role="treeitem"]` selectors
+        // (CSS, querySelector, Cypress/Playwright CSS) keep matching — the
+        // ElementInternals role alone is not attribute-selectable. ARIA states are
+        // mirrored the same way in `_aria()` (aria-expanded/selected/disabled/…).
+        if (!this.hasAttribute('role'))
+            this.setAttribute('role', 'treeitem');
         this._childObserver = new MutationObserver(() => this._syncChildren());
         this._childObserver.observe(this, { childList: true });
         this._syncChildren();
@@ -146,16 +163,42 @@ export class TreeItem extends LuxenElement {
     }
     updated(changed) {
         if (changed.has('expanded')) {
-            this._internals.ariaExpanded = this.isLeaf() ? null : String(this.expanded);
+            this._reflectExpanded();
+            // Emit lazy-load for ANY transition to expanded (keyboard, chevron,
+            // `expandAll()`…), not just `toggle()` — otherwise keyboard users expand a
+            // lazy branch with no children and no fetch. Fires while still `lazy`; the
+            // consumer appends children and clears `lazy`, so it won't re-fire.
+            if (this.expanded && this.lazy)
+                this.emit('lazy-load');
             this.emit(this.expanded ? 'expand' : 'collapse');
         }
         if (changed.has('selected')) {
-            this._internals.ariaSelected = String(this.selected);
+            this._aria('ariaSelected', 'aria-selected', String(this.selected));
         }
         if (changed.has('disabled')) {
-            this._internals.ariaDisabled = this.disabled ? 'true' : null;
+            this._aria('ariaDisabled', 'aria-disabled', this.disabled ? 'true' : null);
+        }
+        if (changed.has('loading')) {
+            this._aria('ariaBusy', 'aria-busy', this.loading ? 'true' : null);
         }
     }
+    /** Leaf items omit `aria-expanded` entirely; branches reflect their state. */
+    _reflectExpanded() {
+        this._aria('ariaExpanded', 'aria-expanded', this.isLeaf() ? null : String(this.expanded));
+    }
+    /**
+     * Write an ARIA state to BOTH ElementInternals (the semantic source, in the
+     * accessibility tree) and a content attribute (so `[aria-*]` CSS / query / test
+     * selectors keep matching — same belt-and-suspenders as the mirrored `role`).
+     * A `null` value clears both.
+     */
+    _aria(key, attr, value) {
+        this._internals[key] = value;
+        if (value === null)
+            this.removeAttribute(attr);
+        else
+            this.setAttribute(attr, value);
+    }
     _setState(name, on) {
         if (!this._internals.states)
             return;
@@ -181,17 +224,14 @@ export class TreeItem extends LuxenElement {
         if (!this._hasChildren && !this.lazy && this.expanded) {
             this.expanded = false;
         }
-        this._internals.ariaExpanded = this.isLeaf() ? null : String(this.expanded);
+        this._reflectExpanded();
     }
-    /** Toggle expand state. Emits `lazy-load` the first time a lazy item opens. */
+    /** Toggle expand state. Opening a `lazy` item emits `lazy-load` (via `updated`). */
     toggle() {
         if (this.isLeaf() && !this.lazy)
             return;
-        const next = !this.expanded;
-        if (next && this.lazy) {
-            this.emit('lazy-load');
-        }
-        this.expanded = next;
+        // lazy-load is emitted centrally from `updated()` on the expand transition.
+        this.expanded = !this.expanded;
     }
     render() {
         return html `
@@ -245,6 +285,7 @@ export class TreeItem extends LuxenElement {
           part="checkbox"
           type="checkbox"
           tabindex="-1"
+          aria-hidden="true"
           .checked=${this.selected}
           .indeterminate=${this.indeterminate}
           ?disabled=${this.disabled}

package/dist/metadata/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.9.0",
+  "version": "0.9.2",
   "elements": [
     {
       "name": "avatar",
@@ -4017,7 +4017,7 @@
       "tag": "l-tree",
       "nativeTag": null,
       "selector": "l-tree",
-      "summary": "A hierarchical tree view composed of `<l-tree-item>` children.",
+      "summary": "A hierarchical tree view composed of `<l-tree-item>` children.\n\nThe host carries `role=\"tree\"`, so give it an accessible name with\n`aria-label` or `aria-labelledby` (e.g. `<l-tree aria-label=\"Files\">`).",
       "status": "stable",
       "appearances": [],
       "import": {
@@ -4247,6 +4247,25 @@
         }
       ],
       "methods": [
+        {
+          "name": "setPosition",
+          "params": [
+            {
+              "name": "level",
+              "type": "number"
+            },
+            {
+              "name": "posInSet",
+              "type": "number"
+            },
+            {
+              "name": "setSize",
+              "type": "number"
+            }
+          ],
+          "returns": null,
+          "description": "Set by `<l-tree>`: ARIA position within the tree. `level` is 1-based depth,\n`posInSet`/`setSize` describe the item's rank among its siblings. These let\nscreen readers announce \"level 2, 3 of 5\" even when `lazy` children keep the\nfull set out of the DOM."
+        },
         {
           "name": "getChildrenItems",
           "params": [
@@ -4274,7 +4293,7 @@
           "name": "toggle",
           "params": [],
           "returns": null,
-          "description": "Toggle expand state. Emits `lazy-load` the first time a lazy item opens."
+          "description": "Toggle expand state. Opening a `lazy` item emits `lazy-load` (via `updated`)."
         }
       ],
       "slots": [

package/dist/metadata/tree-item.json

@@ -106,6 +106,25 @@
     }
   ],
   "methods": [
+    {
+      "name": "setPosition",
+      "params": [
+        {
+          "name": "level",
+          "type": "number"
+        },
+        {
+          "name": "posInSet",
+          "type": "number"
+        },
+        {
+          "name": "setSize",
+          "type": "number"
+        }
+      ],
+      "returns": null,
+      "description": "Set by `<l-tree>`: ARIA position within the tree. `level` is 1-based depth,\n`posInSet`/`setSize` describe the item's rank among its siblings. These let\nscreen readers announce \"level 2, 3 of 5\" even when `lazy` children keep the\nfull set out of the DOM."
+    },
     {
       "name": "getChildrenItems",
       "params": [
@@ -133,7 +152,7 @@
       "name": "toggle",
       "params": [],
       "returns": null,
-      "description": "Toggle expand state. Emits `lazy-load` the first time a lazy item opens."
+      "description": "Toggle expand state. Opening a `lazy` item emits `lazy-load` (via `updated`)."
     }
   ],
   "slots": [

package/dist/metadata/tree.json

@@ -6,7 +6,7 @@
   "tag": "l-tree",
   "nativeTag": null,
   "selector": "l-tree",
-  "summary": "A hierarchical tree view composed of `<l-tree-item>` children.",
+  "summary": "A hierarchical tree view composed of `<l-tree-item>` children.\n\nThe host carries `role=\"tree\"`, so give it an accessible name with\n`aria-label` or `aria-labelledby` (e.g. `<l-tree aria-label=\"Files\">`).",
   "status": "stable",
   "appearances": [],
   "import": {

package/dist/templates/elements/tree.md

@@ -286,6 +286,24 @@ A roadmap of phases and tasks, where collapsing folds away phase details for a h
 - `Space` — Activates the item (selects or toggles expansion depending on mode)
 - `*` — Expands all sibling branches of the focused item
 
+### Selectors & testing
+
+Roles and ARIA states are set on `ElementInternals` (the accessibility-tree source) **and** mirrored to DOM attributes, so both `[role]` and `[aria-*]` selectors keep matching in CSS, `querySelector`, and Cypress/Playwright. Selection state is additionally exposed as the reflected `selected`/`expanded`/`disabled`/`indeterminate` boolean attributes (the component's own API).
+
+```js
+document.querySelectorAll('[role="treeitem"]'); // ✅ role is mirrored to an attribute
+document.querySelectorAll('[aria-selected="true"]'); // ✅ ARIA state is mirrored too
+tree.querySelectorAll('l-tree-item[selected]'); // ✅ reflected boolean attribute
+screen.getByRole('treeitem', { selected: true, expanded: true }); // ✅ name + state
+```
+
+```css
+/* Style by ARIA state or the reflected boolean attribute — both work. */
+l-tree-item[aria-selected='true']::part(base) {
+  background: var(--l-color-bg-fill-brand-subtle);
+}
+```
+
 ## API reference
 
 ### Importing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luxen-ui",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Modern web components and CSS-first UI library built with Lit. Framework-agnostic, customizable prefix, design tokens.",
   "keywords": [
     "custom-elements",
@@ -161,7 +161,9 @@
     "manifest": "cem analyze",
     "metadata": "pnpm run manifest && node scripts/normalize-metadata.mjs && node scripts/check-metadata.mjs",
     "preview": "vp preview",
-    "test": "vp test run --passWithNoTests",
+    "test": "vp test run --passWithNoTests && vp test run --config vitest.browser.config.ts",
+    "test:unit": "vp test run --passWithNoTests",
+    "test:components": "vp test run --config vitest.browser.config.ts",
     "test:e2e": "playwright test"
   }
 }

package/postcss-plugin-prefix.js

@@ -19,6 +19,10 @@ const plugin = (opts = {}) => {
     postcssPlugin: 'luxen-prefix',
 
     Once(root) {
+      // Canonical `--l-*` token names whose declarations we rename to the
+      // custom prefix. Used to emit the bridge block below.
+      const renamedTokens = new Set();
+
       root.walk((node) => {
         if (node.type === 'atrule') {
           if (node.name === 'keyframes' && node.params.startsWith('l-')) {
@@ -32,7 +36,9 @@ const plugin = (opts = {}) => {
 
         if (node.type === 'decl') {
           if (node.prop.startsWith('--l-')) {
-            node.prop = node.prop.replace(/^--l-/, `--${cssPrefix}-`);
+            const suffix = node.prop.slice('--l-'.length);
+            renamedTokens.add(suffix);
+            node.prop = `--${cssPrefix}-${suffix}`;
           }
 
           if (node.value.includes('l-')) {
@@ -40,12 +46,48 @@ const plugin = (opts = {}) => {
           }
         }
       });
+
+      emitPrefixAliases(root, cssPrefix, renamedTokens);
     },
   };
 };
 
 plugin.postcss = true;
 
+/**
+ * Bridges the canonical `--l-*` design-token namespace to the consumer's
+ * custom prefix.
+ *
+ * Each element ships its shadow-DOM CSS baked into the element JS, built once
+ * with the default `l` prefix — that CSS never passes through this plugin, so
+ * it keeps reading `var(--l-focus-ring)` etc. Meanwhile the consumer's imported
+ * preset now only defines `--{cssPrefix}-*`. Without a bridge the two
+ * namespaces never meet and every shadow token resolves to nothing.
+ *
+ * So for every `--l-*` token declaration we just renamed, append a one-time
+ * `:root` alias pointing the canonical name at the prefixed one:
+ *
+ *   :root { --l-focus-ring: var(--p-focus-ring); … }
+ *
+ * The block rides along with whichever imported file defines the tokens
+ * (preset / tokens / aliases), stays exhaustive automatically (it mirrors
+ * exactly what was renamed), and is a no-op for the default `l` build (the
+ * plugin early-returns before ever reaching here).
+ *
+ * @param {import('postcss').Root} root
+ * @param {string} cssPrefix
+ * @param {Set<string>} renamedTokens — canonical names without the `--l-` head
+ */
+function emitPrefixAliases(root, cssPrefix, renamedTokens) {
+  if (renamedTokens.size === 0) return;
+  const decls = [...renamedTokens]
+    .map((name) => `  --l-${name}: var(--${cssPrefix}-${name});`)
+    .join('\n');
+  root.append(
+    `\n/* luxen-prefix: bridge canonical --l-* tokens to --${cssPrefix}-* so shadow-DOM CSS resolves. */\n:root {\n${decls}\n}\n`,
+  );
+}
+
 function rewriteSelector(selector, elementPrefix, cssPrefix) {
   let result = selector;
   result = result.replace(/\.l-/g, `.${cssPrefix}-`);