@c2n/tree 0.0.9

package/react.d.ts

@@ -0,0 +1,26 @@
+// GENERATED by @c2n/framework-types. Do not edit by hand.
+//
+// JSX types for the custom elements of @c2n/tree. Import once, anywhere in the program:
+//
+//     import '@c2n/tree/react'
+//
+// Register the elements at module scope before React renders, or React writes an object prop as an
+// attribute and it stringifies.
+
+import type { DetailedHTMLProps, HTMLAttributes } from 'react'
+import type { Tree } from '@c2n/tree'
+import type { TreeItem } from '@c2n/tree/tree-item.js'
+
+/** Standard React host-element attributes plus the element's own public properties. */
+type C2Props<T> = DetailedHTMLProps<HTMLAttributes<T>, T> & Partial<Omit<T, keyof HTMLElement>>
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'c2-tree': C2Props<Tree>
+      'c2-tree-item': C2Props<TreeItem>
+    }
+  }
+}
+
+export {}

package/react.js

@@ -0,0 +1,3 @@
+// GENERATED by @c2n/framework-types. Do not edit by hand.
+// Types only — see the matching .d.ts.
+export {}

package/types/src/tree-item.d.ts

@@ -0,0 +1,153 @@
+import { LitElement, type PropertyValues } from 'lit';
+import type { TypedAddEventListener, TypedRemoveEventListener } from '@c2n/core/event-helper.js';
+import '@c2n/checkbox';
+import '@c2n/spinner';
+import type { TreeNode } from './tree-types';
+/** Fired when an item joins, leaves or changes identity, so its `c2-tree` can resync. */
+export declare const TREE_ITEM_CHANGE_EVENT = "c2-tree-item-change";
+/** Fired when the disclosure toggle is activated. */
+export declare const TREE_ITEM_TOGGLE_EVENT = "c2-tree-item-toggle";
+/** Fired when the row's checkbox is ticked or cleared. */
+export declare const TREE_ITEM_CHECK_EVENT = "c2-tree-item-check";
+/** Events fired by {@link TreeItem}, keyed for `addEventListener`. */
+export interface TreeItemEventMap {
+    'c2-tree-item-change': CustomEvent<void>;
+    'c2-tree-item-toggle': CustomEvent<void>;
+    'c2-tree-item-check': CustomEvent<boolean>;
+}
+export interface TreeItem {
+    addEventListener: TypedAddEventListener<TreeItem, TreeItemEventMap>;
+    removeEventListener: TypedRemoveEventListener<TreeItem, TreeItemEventMap>;
+}
+/**
+ * One row of a {@link https://github.com/code2nguyen/web-components | `c2-tree`}.
+ *
+ * Nest items to build the hierarchy — a branch's children are its own `c2-tree-item` element children:
+ *
+ * ```html
+ * <c2-tree>
+ *   <c2-tree-item value="src" label="src">
+ *     <c2-tree-item value="app.ts" label="app.ts"></c2-tree-item>
+ *   </c2-tree-item>
+ * </c2-tree>
+ * ```
+ *
+ * The item draws a row and nothing else: `expanded`, `selected`, `indeterminate`, `level` and the roving
+ * `tabindex` are all written by the parent `c2-tree`, which owns the tree's state. Setting them by hand works
+ * but is overwritten on the tree's next sync — drive the tree's `value` and `expanded-items` instead.
+ *
+ * The children slot is only rendered while the row is expanded, so a collapsed subtree is not laid out and
+ * stays out of the accessibility tree. The child elements themselves still exist in the DOM.
+ *
+ * @tag c2-tree-item
+ *
+ * @slot - The nested `c2-tree-item` children of this row.
+ * @slot label - Rich label content, replacing the `label` attribute.
+ * @slot icon - Icon shown between the disclosure toggle and the label.
+ * @slot actions - Trailing content, revealed on hover and focus by default.
+ * @slot toggle-icon - Replaces the default chevron. It is rotated by the component, so supply the collapsed orientation.
+ *
+ * @csspart row - The clickable row, excluding any nested children.
+ * @csspart toggle - The disclosure toggle.
+ * @csspart label - The label box.
+ * @csspart actions - The trailing actions box.
+ * @csspart group - The container holding the nested children.
+ *
+ * @cssproperty {pixel} [--c2-tree-item__row--min-height=28px] - Height of a row.
+ * @cssproperty {pixel} [--c2-tree-item__row--indent=16px] - Extra inset added per level of depth.
+ * @cssproperty {padding} [--c2-tree-item__row--padding-top=0px] - Space above the row's content. `row--min-height` is a floor, so this only grows the row once content plus padding passes it.
+ * @cssproperty {padding} [--c2-tree-item__row--padding-bottom=0px] - Space below the row's content. See `row--padding-top` for how it interacts with `row--min-height`.
+ * @cssproperty {padding} [--c2-tree-item__row--padding-inline-start=8px] - Inset of a root-level row.
+ * @cssproperty {padding} [--c2-tree-item__row--padding-inline-end=8px] - Space after the trailing actions.
+ * @cssproperty {pixel} [--c2-tree-item__row--gap=6px] - Space between toggle, checkbox, icon, label and actions.
+ * @cssproperty {border-radius} [--c2-tree-item__row--border-radius=4px] - Corner radius of the row highlight. Set `0` for edge-to-edge bands.
+ * @cssproperty {color} [--c2-tree-item--color=#18181b] - Label colour.
+ * @cssproperty {color} [--c2-tree-item--background=transparent] - Row background at rest.
+ * @cssproperty {font-size} [--c2-tree-item--font-size=14px] - Label size.
+ * @cssproperty {font-weight} --c2-tree-item--font-weight - Label weight.
+ * @cssproperty {font-family} --c2-tree-item--font-family - Label family.
+ * @cssproperty {pixel} [--c2-tree-item--line-height=20px] - Label line height.
+ * @cssproperty {color} --c2-tree-item__hover--color - Label colour while hovered. Defaults to the resting colour.
+ * @cssproperty {color} [--c2-tree-item__hover--background=#f4f4f5] - Row background while hovered.
+ * @cssproperty {color} [--c2-tree-item__selected--color=rgb(2, 101, 220)] - Label colour while selected.
+ * @cssproperty {color} [--c2-tree-item__selected--background=#edf1fe] - Row background while selected.
+ * @cssproperty {color} [--c2-tree-item__selected__hover--background=#e2e9fd] - Row background while selected and hovered.
+ * @cssproperty {outline} [--c2-tree-item__focus--outline=2px solid rgba(2, 101, 220, 0.4)] - Focus ring.
+ * @cssproperty {pixel} [--c2-tree-item__focus--outline-offset=-2px] - Focus ring inset.
+ * @cssproperty {opacity} [--c2-tree-item__disabled--opacity=0.38] - Opacity of a disabled row.
+ * @cssproperty {pixel} [--c2-tree-item__toggle--size=16px] - Size of the disclosure toggle.
+ * @cssproperty {color} [--c2-tree-item__toggle--color=#71717a] - Colour of the disclosure toggle.
+ * @cssproperty {angle} [--c2-tree-item__toggle--rotate=90deg] - Toggle rotation while expanded.
+ * @cssproperty {angle} [--c2-tree-item__toggle--rotate-collapsed=0deg] - Toggle rotation while collapsed.
+ * @cssproperty {time} [--c2-tree-item__toggle--transition-duration=150ms] - Length of the toggle rotation.
+ * @cssproperty {pixel} [--c2-tree-item__icon--size=16px] - Size of slotted icons.
+ * @cssproperty {color} --c2-tree-item__icon--color - Colour of slotted icons.
+ * @cssproperty {color} [--c2-tree-item__guide--color=#e4e4e7] - Colour of the indent guides.
+ * @cssproperty {pixel} [--c2-tree-item__guide--width=1px] - Thickness of the indent guides.
+ * @cssproperty {pixel} [--c2-tree-item__actions--gap=2px] - Space between trailing actions.
+ * @cssproperty {opacity} [--c2-tree-item__actions--opacity=0] - Opacity of the trailing actions at rest. Set `1` to always show them.
+ * @cssproperty {opacity} [--c2-tree-item__actions__hover--opacity=1] - Opacity of the trailing actions while the row is hovered or focused.
+ * @cssproperty {pixel} [--c2-tree-item__checkbox--margin-inline-end=2px] - Space after the selection checkbox.
+ */
+export declare class TreeItem extends LitElement {
+    #private;
+    static styles: import("lit").CSSResult;
+    /** Identity of the row. Selection and expansion are tracked by this value, so it must be unique in the tree. */
+    value: string;
+    /** Text of the row. Ignored when the `label` slot is filled; falls back to `value` when empty. */
+    label: string;
+    /** Blocks selection and expansion, and takes the row out of checkbox propagation. */
+    disabled: boolean;
+    /** Marks a branch whose children load on demand: the toggle shows before any child exists. */
+    hasChildren: boolean;
+    /** Turns the row into a link. The whole row becomes the click target; the toggle still only expands. */
+    href: string;
+    /** Browsing context for `href`, e.g. `_blank`. A `_blank` row gets `rel="noopener noreferrer"`. */
+    target?: string;
+    /** Arbitrary payload handed back on the tree's events. */
+    data?: unknown;
+    /** Whether the children are shown. Written by the parent `c2-tree`. */
+    expanded: boolean;
+    /** Whether the row is selected. Written by the parent `c2-tree`. */
+    selected: boolean;
+    /** Whether only part of the subtree is selected. Derived and written by the parent `c2-tree`. */
+    indeterminate: boolean;
+    /** Whether the children are being fetched. Written by the parent `c2-tree`. */
+    loading: boolean;
+    /** Depth of the row, `0` at the root. Written by the parent `c2-tree`. */
+    level: number;
+    /** Whether the parent `c2-tree` renders a selection checkbox. Written by the parent `c2-tree`. */
+    checkboxSelection: boolean;
+    /**
+     * Whether to draw the indent guides. Written by the parent `c2-tree`, and reflected because the rules are
+     * drawn in CSS and the stylesheet has to see it.
+     */
+    childrenOutline: boolean;
+    /** Number of siblings in this row's group, for `aria-setsize`. Written by the parent `c2-tree`. */
+    setSize: number;
+    /** 1-based index of this row among its siblings, for `aria-posinset`. Written by the parent `c2-tree`. */
+    posInSet: number;
+    /** Whether the parent `c2-tree` tracks selection at all, so a leaf knows whether to claim `aria-selected`. */
+    selectable: boolean;
+    private labelSlot?;
+    /** The row as a {@link TreeNode}, so both authoring modes produce the same event details and renderer input. */
+    get node(): TreeNode;
+    /** The nested rows, in document order. */
+    get childItems(): TreeItem[];
+    /** Whether the row can be expanded — it already has children, or declares that it will load some. */
+    get isBranch(): boolean;
+    /** The accessible name of the row, resolved from the `label` slot, the `label` attribute or `value`. */
+    get resolvedLabel(): string;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    willUpdate(changed: PropertyValues<this>): void;
+    updated(changed: PropertyValues<this>): void;
+    firstUpdated(): void;
+    render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'c2-tree-item': TreeItem;
+    }
+}
+//# sourceMappingURL=tree-item.d.ts.map

package/types/src/tree-item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-item.d.ts","sourceRoot":"","sources":["../../src/tree-item.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA4B,KAAK,cAAc,EAAE,MAAM,KAAK,CAAA;AAM/E,OAAO,KAAK,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AAChG,OAAO,eAAe,CAAA;AACtB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAE5C,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,wBAAwB,CAAA;AAC3D,qDAAqD;AACrD,eAAO,MAAM,sBAAsB,wBAAwB,CAAA;AAC3D,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,uBAAuB,CAAA;AAEzD,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,qBAAqB,EAAE,WAAW,CAAC,IAAI,CAAC,CAAA;IACxC,qBAAqB,EAAE,WAAW,CAAC,IAAI,CAAC,CAAA;IACxC,oBAAoB,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;CAC3C;AAED,MAAM,WAAW,QAAQ;IACvB,gBAAgB,EAAE,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAA;IACnE,mBAAmB,EAAE,wBAAwB,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAA;CAC1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,qBACa,QAAS,SAAQ,UAAU;;IACtC,OAAgB,MAAM,0BAAoB;IAE1C,gHAAgH;IACrE,KAAK,SAAK;IAErD,kGAAkG;IACtE,KAAK,SAAK;IAEtC,qFAAqF;IACzC,QAAQ,UAAQ;IAE5D,8FAA8F;IACvB,WAAW,UAAQ;IAE1F,wGAAwG;IAC5E,IAAI,SAAK;IAErC,mGAAmG;IACvE,MAAM,CAAC,EAAE,MAAM,CAAA;IAE3C,0DAA0D;IAC1B,IAAI,CAAC,EAAE,OAAO,CAAA;IAE9C,uEAAuE;IAC3B,QAAQ,UAAQ;IAE5D,oEAAoE;IACxB,QAAQ,UAAQ;IAE5D,iGAAiG;IACrD,aAAa,UAAQ;IAEjE,+EAA+E;IACnC,OAAO,UAAQ;IAE3D,0EAA0E;IAC1C,KAAK,SAAI;IAEzC,kGAAkG;IAClE,iBAAiB,UAAQ;IAEzD;;;OAGG;IACwE,eAAe,UAAQ;IAElG,mGAAmG;IACnE,OAAO,SAAI;IAE3C,0GAA0G;IAC1E,QAAQ,SAAI;IAE5C,8GAA8G;IAC9E,UAAU,UAAO;IAEpB,OAAO,CAAC,SAAS,CAAC,CAAiB;IAKhE,gHAAgH;IAChH,IAAI,IAAI,IAAI,QAAQ,CAInB;IAED,0CAA0C;IAC1C,IAAI,UAAU,IAAI,QAAQ,EAAE,CAI3B;IAED,qGAAqG;IACrG,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,wGAAwG;IACxG,IAAI,aAAa,IAAI,MAAM,CAE1B;IAEQ,iBAAiB;IAKjB,oBAAoB;IAapB,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC;IAKxC,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC;IAKrC,YAAY;IAwDZ,MAAM;CA+DhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,cAAc,EAAE,QAAQ,CAAA;KACzB;CACF"}

package/types/src/tree-types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Public types shared by `c2-tree` and `c2-tree-item`.
+ *
+ * The tree can be authored two ways — nested `<c2-tree-item>` elements, or a `TreeNode[]` handed to the
+ * `items` property — and {@link TreeNode} is the single shape both speak. A declarative item synthesizes one
+ * from its own attributes through its `node` getter, so event details, renderers and the lazy loader never
+ * have to care which mode produced a row.
+ */
+/**
+ * One node of a tree.
+ *
+ * Shaped after `CascaderOption` so the two hierarchical components read alike. `children` is only meaningful
+ * in the data-driven mode: a declarative item's `node` deliberately leaves it `undefined` rather than walking
+ * its subtree on every event dispatch.
+ */
+export interface TreeNode {
+    /** Identity of the node. Selection and expansion are both tracked by this value, so it must be unique. */
+    value: string;
+    /** Text shown on the row. Falls back to {@link TreeNode.value} when omitted. */
+    label?: string;
+    /** Child nodes. Leave undefined and set {@link TreeNode.hasChildren} for a branch that loads on demand. */
+    children?: TreeNode[];
+    /** Blocks selection and expansion, and excludes the node from checkbox propagation. */
+    disabled?: boolean;
+    /**
+     * Marks a branch whose children are not loaded yet, so the row shows a toggle before anything is known
+     * about its contents. Expanding it runs the tree's `loadChildren`.
+     */
+    hasChildren?: boolean;
+    /** Arbitrary payload carried back to the consumer on `selection-change` and in the renderers. */
+    data?: unknown;
+}
+/** What a renderer or loader is told about the row it is being called for. */
+export interface TreeItemContext {
+    /** The node being rendered. */
+    node: TreeNode;
+    /** Depth of the node, `0` for a root. */
+    level: number;
+    /** Whether the node is currently expanded. */
+    expanded: boolean;
+    /** Whether the node is currently selected. */
+    selected: boolean;
+}
+/** Replaces part of a row's content. Returns anything Lit can render. */
+export type TreeItemRenderer = (context: TreeItemContext) => unknown;
+/** Resolves the children of a branch the first time it is expanded. */
+export type TreeChildrenLoader = (context: TreeItemContext) => Promise<TreeNode[]>;
+/** Detail of `c2-tree`'s `selection-change` event. */
+export interface TreeSelectionChangeEventDetail {
+    /** Values of every selected node, in tree order. */
+    value: string[];
+    /** The selected nodes themselves. */
+    nodes: TreeNode[];
+}
+/** Detail of `c2-tree`'s `expansion-change` event. */
+export interface TreeExpansionChangeEventDetail {
+    /** Values of every expanded node after the change. */
+    expandedItems: string[];
+    /** The node that was toggled. */
+    node: TreeNode;
+    /** Whether that node is now expanded. */
+    expanded: boolean;
+}
+/** Detail of `c2-tree`'s `item-click` event. */
+export interface TreeItemClickEventDetail {
+    /** The node whose row was clicked. */
+    node: TreeNode;
+}
+/** Detail of `c2-tree`'s `item-expand` event, the hook a declarative consumer loads children from. */
+export interface TreeItemExpandEventDetail {
+    /** The node being expanded. */
+    node: TreeNode;
+    /** True while the node's children still have to be produced. */
+    loading: boolean;
+}
+/** Detail of `c2-tree`'s `item-load-error` event. */
+export interface TreeItemLoadErrorEventDetail {
+    /** The node whose children failed to load. */
+    node: TreeNode;
+    /** Whatever `loadChildren` rejected with. */
+    error: unknown;
+}
+/** How a checkbox tick travels between a node and its relatives. */
+export type TreeSelectionPropagation = 'none' | 'descendants' | 'parents' | 'both';
+/** How many rows may be selected at once. */
+export type TreeSelectionMode = 'none' | 'single' | 'multiple';
+//# sourceMappingURL=tree-types.d.ts.map

package/types/src/tree-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-types.d.ts","sourceRoot":"","sources":["../../src/tree-types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,0GAA0G;IAC1G,KAAK,EAAE,MAAM,CAAA;IACb,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,2GAA2G;IAC3G,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAA;IACrB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,iGAAiG;IACjG,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,CAAA;IACd,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,8CAA8C;IAC9C,QAAQ,EAAE,OAAO,CAAA;IACjB,8CAA8C;IAC9C,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAA;AAEpE,uEAAuE;AACvE,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;AAElF,sDAAsD;AACtD,MAAM,WAAW,8BAA8B;IAC7C,oDAAoD;IACpD,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,qCAAqC;IACrC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAClB;AAED,sDAAsD;AACtD,MAAM,WAAW,8BAA8B;IAC7C,sDAAsD;IACtD,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,iCAAiC;IACjC,IAAI,EAAE,QAAQ,CAAA;IACd,yCAAyC;IACzC,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,gDAAgD;AAChD,MAAM,WAAW,wBAAwB;IACvC,sCAAsC;IACtC,IAAI,EAAE,QAAQ,CAAA;CACf;AAED,sGAAsG;AACtG,MAAM,WAAW,yBAAyB;IACxC,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,CAAA;IACd,gEAAgE;IAChE,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,4BAA4B;IAC3C,8CAA8C;IAC9C,IAAI,EAAE,QAAQ,CAAA;IACd,6CAA6C;IAC7C,KAAK,EAAE,OAAO,CAAA;CACf;AAED,oEAAoE;AACpE,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,aAAa,GAAG,SAAS,GAAG,MAAM,CAAA;AAElF,6CAA6C;AAC7C,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAA"}

package/types/src/tree.d.ts

@@ -0,0 +1,176 @@
+import { LitElement, type PropertyValues } from 'lit';
+import type { TypedAddEventListener, TypedRemoveEventListener } from '@c2n/core/event-helper.js';
+import './tree-item';
+import { TreeItem } from './tree-item';
+import type { TreeChildrenLoader, TreeExpansionChangeEventDetail, TreeItemClickEventDetail, TreeItemExpandEventDetail, TreeItemLoadErrorEventDetail, TreeItemRenderer, TreeNode, TreeSelectionChangeEventDetail, TreeSelectionMode, TreeSelectionPropagation } from './tree-types';
+/** Events fired by {@link Tree}, keyed for `addEventListener`. */
+export interface TreeEventMap {
+    'selection-change': CustomEvent<TreeSelectionChangeEventDetail>;
+    'expansion-change': CustomEvent<TreeExpansionChangeEventDetail>;
+    'item-click': CustomEvent<TreeItemClickEventDetail>;
+    'item-expand': CustomEvent<TreeItemExpandEventDetail>;
+    'item-load-error': CustomEvent<TreeItemLoadErrorEventDetail>;
+}
+export interface Tree {
+    addEventListener: TypedAddEventListener<Tree, TreeEventMap>;
+    removeEventListener: TypedRemoveEventListener<Tree, TreeEventMap>;
+}
+/**
+ * Hierarchical tree view with expansion, selection and lazy loading.
+ *
+ * It can be authored two ways, and both produce the same DOM and the same events. Nest the rows in markup:
+ *
+ * ```html
+ * <c2-tree expanded-items="src">
+ *   <c2-tree-item value="src" label="src">
+ *     <c2-tree-item value="app.ts" label="app.ts"></c2-tree-item>
+ *   </c2-tree-item>
+ * </c2-tree>
+ * ```
+ *
+ * …or hand it data, which it renders into the same `c2-tree-item` elements:
+ *
+ * ```ts
+ * tree.items = [{ value: 'src', label: 'src', children: [{ value: 'app.ts', label: 'app.ts' }] }]
+ * ```
+ *
+ * The tree owns all state. `value` holds the selected rows, `expanded-items` the expanded ones, and every
+ * row's `expanded`, `selected`, `indeterminate`, `level` and roving `tabindex` are written from here on each
+ * sync — so drive those two arrays rather than the rows.
+ *
+ * In the data-driven mode `renderItem` takes over a row's whole content, or `renderIcon`, `renderLabel` and
+ * `renderActions` replace one part each. They are handed to Lit, so they return a Lit template or a DOM node —
+ * not framework markup such as JSX.
+ *
+ * `children-outline` draws a vertical rule per level of depth, the way a file explorer marks which branch each
+ * row belongs to. It is off by default; `--c2-tree-item__guide--color` and `--c2-tree-item__guide--width` style
+ * the rules once it is on.
+ *
+ * Only expanded rows render their children slot, which keeps a collapsed subtree out of both layout and the
+ * accessibility tree — though the child elements are still created. Reach for virtualization rather than this
+ * component once a tree runs to many thousands of rows.
+ *
+ * ### Keyboard
+ *
+ * Arrow Up and Down walk the visible rows. Arrow Right expands a collapsed branch, then moves to its first
+ * child; Arrow Left collapses an expanded one, then moves to its parent. Home and End jump to the ends, Enter
+ * and Space select, `*` expands every sibling of the focused row, and typing a few letters jumps to the
+ * matching row. With `selection="multiple"`, Shift extends a range and Ctrl or Cmd toggles a single row.
+ *
+ * @tag c2-tree
+ *
+ * @slot - The root `c2-tree-item` rows, when authoring in markup.
+ * @slot empty - Shown instead of the rows when the tree holds nothing.
+ *
+ * @slotcomponent c2-tree-item
+ *
+ * @csspart tree - The scrolling container holding the rows.
+ *
+ * @event {CustomEvent<TreeSelectionChangeEventDetail>} selection-change - Fired after the user changes the selection. Does not bubble: several components fire `selection-change`, so a listener belongs on the element itself.
+ * @event {CustomEvent<TreeExpansionChangeEventDetail>} expansion-change - Fired after a row is expanded or collapsed. Does not bubble.
+ * @event {CustomEvent<TreeItemClickEventDetail>} item-click - Fired when a row is clicked, selected or not.
+ * @event {CustomEvent<TreeItemExpandEventDetail>} item-expand - Fired when a row expands. Call `preventDefault()` to keep it closed. This is where a consumer authoring in markup appends children for a lazily loaded branch.
+ * @event {CustomEvent<TreeItemLoadErrorEventDetail>} item-load-error - Fired when `loadChildren` rejects.
+ *
+ * @cssproperty {color} [--c2-tree--background=#ffffff] - Background of the tree.
+ * @cssproperty {padding} [--c2-tree--padding-top=4px] - Space above the first row.
+ * @cssproperty {padding} [--c2-tree--padding-right=0px] - Space right of the rows.
+ * @cssproperty {padding} [--c2-tree--padding-bottom=4px] - Space below the last row.
+ * @cssproperty {padding} [--c2-tree--padding-left=0px] - Space left of the rows.
+ * @cssproperty {border} --c2-tree--border-top - Top border.
+ * @cssproperty {border} --c2-tree--border-right - Right border.
+ * @cssproperty {border} --c2-tree--border-bottom - Bottom border.
+ * @cssproperty {border} --c2-tree--border-left - Left border.
+ * @cssproperty {border-radius} [--c2-tree--border-top-left-radius=8px] - Top-left corner radius.
+ * @cssproperty {border-radius} [--c2-tree--border-top-right-radius=8px] - Top-right corner radius.
+ * @cssproperty {border-radius} [--c2-tree--border-bottom-left-radius=8px] - Bottom-left corner radius.
+ * @cssproperty {border-radius} [--c2-tree--border-bottom-right-radius=8px] - Bottom-right corner radius.
+ * @cssproperty {pixel} --c2-tree--max-height - Height at which the tree starts scrolling.
+ * @cssproperty {font-size} [--c2-tree--font-size=14px] - Base font size, inherited by the rows.
+ * @cssproperty {font-family} --c2-tree--font-family - Base font family, inherited by the rows.
+ * @cssproperty {opacity} [--c2-tree__disabled--opacity=0.38] - Opacity of a disabled tree.
+ * @cssproperty {color} [--c2-tree__empty--color=#71717a] - Colour of the empty message.
+ * @cssproperty {padding} [--c2-tree__empty--padding=18px] - Space around the empty message.
+ */
+export declare class Tree extends LitElement {
+    #private;
+    static styles: import("lit").CSSResult;
+    /** Nodes to render. Leave empty and nest `c2-tree-item` elements instead to author the tree in markup. */
+    items: TreeNode[];
+    /** Values of the selected rows. Reflected as a `;`-separated attribute. */
+    value: string[];
+    /** Values of the expanded rows. Reflected as a `;`-separated attribute. */
+    expandedItems: string[];
+    /** How many rows may be selected at once. */
+    selection: TreeSelectionMode;
+    /** Shows a checkbox on every row. Implies `selection="multiple"`. */
+    checkboxSelection: boolean;
+    /** How a checkbox tick travels between a row and its relatives. */
+    selectionPropagation: TreeSelectionPropagation;
+    /** Draws a vertical rule per level of depth, marking which branch each row belongs to. */
+    childrenOutline: boolean;
+    /** Freezes the whole tree. */
+    disabled: boolean;
+    /** Expands a branch when its row is clicked — or activated with Enter or Space — not only when its toggle is. */
+    expandOnClick: boolean;
+    /** Resolves the children of a branch the first time it is expanded. */
+    loadChildren?: TreeChildrenLoader;
+    /**
+     * Replaces the whole content of every row — icon, label and trailing actions together. Takes precedence over
+     * `renderIcon`, `renderLabel` and `renderActions`. The toggle and the selection checkbox are structural and
+     * stay. Only used in the data-driven mode; author the slots directly when the rows are written in markup.
+     */
+    renderItem?: TreeItemRenderer;
+    /** Replaces the label of every row. Only used in the data-driven mode. */
+    renderLabel?: TreeItemRenderer;
+    /** Adds an icon to every row. Only used in the data-driven mode. */
+    renderIcon?: TreeItemRenderer;
+    /** Adds trailing content to every row. Only used in the data-driven mode. */
+    renderActions?: TreeItemRenderer;
+    private container?;
+    private rootSlot?;
+    /** Every row in the tree, in document order, expanded or not. */
+    get allItems(): TreeItem[];
+    /**
+     * The rows a user can actually see and move to — every row whose ancestors are all expanded, skipping any row
+     * `hidden` takes off the page. A filtered-out row must not stay in the keyboard order, or Arrow Down walks
+     * onto something nobody can see.
+     */
+    get visibleItems(): TreeItem[];
+    /**
+     * The root rows, from whichever mode produced them. Data-driven rows live in this shadow root and slotted
+     * rows in the light DOM, so both sources are read; below the root the two modes are identical and
+     * `TreeItem.childItems` serves both.
+     */
+    get rootItems(): TreeItem[];
+    /** The rows that are currently selected, in tree order. */
+    getSelectedNodes(): TreeNode[];
+    /** Expands a row. Unknown or disabled values are ignored. */
+    expand(value: string): void;
+    /** Collapses a row. Unknown values are ignored. */
+    collapse(value: string): void;
+    /** Expands a collapsed row, or collapses an expanded one. */
+    toggle(value: string): void;
+    /** Expands every branch already present in the tree. Branches that load on demand are left alone. */
+    expandAll(): void;
+    /** Collapses every branch. */
+    collapseAll(): void;
+    /** Selects every enabled row. Only meaningful while several rows may be selected. */
+    selectAll(): void;
+    /** Clears the selection. */
+    clearSelection(): void;
+    /** Moves focus to a row, expanding its ancestors if needed. */
+    focusItem(value: string): void;
+    /** Drops the cached "already loaded" mark so the next expand runs `loadChildren` again. */
+    reload(value?: string): void;
+    connectedCallback(): void;
+    willUpdate(changed: PropertyValues<this>): void;
+    updated(changed: PropertyValues<this>): void;
+    render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'c2-tree': Tree;
+    }
+}
+//# sourceMappingURL=tree.d.ts.map

package/types/src/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/tree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA4B,KAAK,cAAc,EAAE,MAAM,KAAK,CAAA;AAM/E,OAAO,KAAK,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AAIhG,OAAO,aAAa,CAAA;AACpB,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,OAAO,KAAK,EACV,kBAAkB,EAClB,8BAA8B,EAC9B,wBAAwB,EACxB,yBAAyB,EACzB,4BAA4B,EAC5B,gBAAgB,EAChB,QAAQ,EACR,8BAA8B,EAC9B,iBAAiB,EACjB,wBAAwB,EACzB,MAAM,cAAc,CAAA;AAMrB,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,kBAAkB,EAAE,WAAW,CAAC,8BAA8B,CAAC,CAAA;IAC/D,kBAAkB,EAAE,WAAW,CAAC,8BAA8B,CAAC,CAAA;IAC/D,YAAY,EAAE,WAAW,CAAC,wBAAwB,CAAC,CAAA;IACnD,aAAa,EAAE,WAAW,CAAC,yBAAyB,CAAC,CAAA;IACrD,iBAAiB,EAAE,WAAW,CAAC,4BAA4B,CAAC,CAAA;CAC7D;AAED,MAAM,WAAW,IAAI;IACnB,gBAAgB,EAAE,qBAAqB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;IAC3D,mBAAmB,EAAE,wBAAwB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;CAClE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,qBACa,IAAK,SAAQ,UAAU;;IAClC,OAAgB,MAAM,0BAAoB;IAE1C,0GAA0G;IAC1D,KAAK,EAAE,QAAQ,EAAE,CAAK;IAEtE,2EAA2E;IACX,KAAK,EAAE,MAAM,EAAE,CAAK;IAEpF,2EAA2E;IACkB,aAAa,EAAE,MAAM,EAAE,CAAK;IAEzH,6CAA6C;IACjB,SAAS,EAAE,iBAAiB,CAAW;IAEnE,qEAAqE;IACP,iBAAiB,UAAQ;IAEvF,mEAAmE;IACH,oBAAoB,EAAE,wBAAwB,CAAS;IAEvH,0FAA0F;IACf,eAAe,UAAQ;IAElG,8BAA8B;IACc,QAAQ,UAAQ;IAE5D,iHAAiH;IACtD,aAAa,UAAQ;IAEhF,uEAAuE;IACvC,YAAY,CAAC,EAAE,kBAAkB,CAAA;IAEjE;;;;OAIG;IAC6B,UAAU,CAAC,EAAE,gBAAgB,CAAA;IAE7D,0EAA0E;IAC1C,WAAW,CAAC,EAAE,gBAAgB,CAAA;IAE9D,oEAAoE;IACpC,UAAU,CAAC,EAAE,gBAAgB,CAAA;IAE7D,6EAA6E;IAC7C,aAAa,CAAC,EAAE,gBAAgB,CAAA;IAE7C,OAAO,CAAC,SAAS,CAAC,CAAa;IAEvB,OAAO,CAAC,QAAQ,CAAC,CAAiB;IAa7D,iEAAiE;IACjE,IAAI,QAAQ,IAAI,QAAQ,EAAE,CAUzB;IAED;;;;OAIG;IACH,IAAI,YAAY,IAAI,QAAQ,EAAE,CAW7B;IAED;;;;OAIG;IACH,IAAI,SAAS,IAAI,QAAQ,EAAE,CAK1B;IAED,2DAA2D;IAC3D,gBAAgB,IAAI,QAAQ,EAAE;IAI9B,6DAA6D;IAC7D,MAAM,CAAC,KAAK,EAAE,MAAM;IAKpB,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM;IAKtB,6DAA6D;IAC7D,MAAM,CAAC,KAAK,EAAE,MAAM;IAKpB,qGAAqG;IACrG,SAAS;IAIT,8BAA8B;IAC9B,WAAW;IAIX,qFAAqF;IACrF,SAAS;IAKT,4BAA4B;IAC5B,cAAc;IAId,+DAA+D;IAC/D,SAAS,CAAC,KAAK,EAAE,MAAM;IASvB,2FAA2F;IAC3F,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM;IAyBZ,iBAAiB;IAKjB,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC;IAYxC,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC;IAyYrC,MAAM;CAsBhB;AAsBD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,SAAS,EAAE,IAAI,CAAA;KAChB;CACF"}

package/vue.d.ts

@@ -0,0 +1,52 @@
+// GENERATED by @c2n/framework-types. Do not edit by hand.
+//
+// Vue template types for the custom elements of @c2n/tree. Import once, anywhere in the program:
+//
+//     import '@c2n/tree/vue'
+//
+// Tell the compiler about the tags as well, or every c2-* tag is resolved as a Vue component and renders
+// nothing: template.compilerOptions.isCustomElement = (tag) => tag.startsWith('c2-') in vite.config.ts.
+
+import type { DefineComponent, HTMLAttributes } from 'vue'
+import type { Tree, TreeEventMap } from '@c2n/tree'
+import type { TreeItem, TreeItemEventMap } from '@c2n/tree/tree-item.js'
+
+/** The element's own public properties, plus every attribute Vue understands on a host element. */
+type C2Props<T> = Partial<Omit<T, keyof HTMLElement>> & HTMLAttributes
+
+declare module 'vue' {
+  interface GlobalComponents {
+    'c2-tree': DefineComponent<
+      C2Props<Tree> & {
+        'expanded-items'?: unknown
+        'checkbox-selection'?: unknown
+        'selection-propagation'?: unknown
+        'children-outline'?: unknown
+        'expand-on-click'?: unknown
+        onExpansionChange?: (event: TreeEventMap['expansion-change']) => void
+        onItemLoadError?: (event: TreeEventMap['item-load-error']) => void
+        onSelectionChange?: (event: TreeEventMap['selection-change']) => void
+        onItemClick?: (event: TreeEventMap['item-click']) => void
+        onItemExpand?: (event: TreeEventMap['item-expand']) => void
+      }
+    >
+    'c2-tree-item': DefineComponent<
+      C2Props<TreeItem> & {
+        'has-children'?: unknown
+        'children-outline'?: unknown
+        onTREE_ITEM_CHANGE_EVENT?: (event: TreeItemEventMap['TREE_ITEM_CHANGE_EVENT']) => void
+        onTREE_ITEM_TOGGLE_EVENT?: (event: TreeItemEventMap['TREE_ITEM_TOGGLE_EVENT']) => void
+        onTREE_ITEM_CHECK_EVENT?: (event: TreeItemEventMap['TREE_ITEM_CHECK_EVENT']) => void
+      }
+    >
+  }
+}
+
+declare module '@vue/runtime-dom' {
+  interface HTMLAttributes {
+    /** Vue's own definition omits it, and slotting a plain element into a component needs it. */
+    slot?: string
+  }
+}
+
+export {}

package/vue.js

@@ -0,0 +1,3 @@
+// GENERATED by @c2n/framework-types. Do not edit by hand.
+// Types only — see the matching .d.ts.
+export {}