@c2n/tree 0.0.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nguyen Thai Vinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @c2n/tree
+
+Hierarchical tree view with expansion, selection, checkbox selection and lazy loading, built with Lit.
+
+```bash
+npm install @c2n/tree
+```
+
+```html
+<script type="module">
+  import '@c2n/tree'
+</script>
+
+<c2-tree aria-label="Files" expanded-items="src" value="app">
+  <c2-tree-item value="src" label="src">
+    <c2-tree-item value="app" label="app.ts"></c2-tree-item>
+    <c2-tree-item value="main" label="main.ts"></c2-tree-item>
+  </c2-tree-item>
+  <c2-tree-item value="readme" label="README.md"></c2-tree-item>
+</c2-tree>
+```
+
+- **Two authoring modes, one result**: nest `c2-tree-item` elements as above, or set `items` to an array of
+  `{ value, label, children?, disabled?, hasChildren?, data? }` nodes and the tree renders the same elements
+  itself. Both produce identical DOM and the same events, so a docs example and a data-driven app agree.
+- **The tree owns the state**: `value` holds the selected rows and `expanded-items` the expanded ones, both
+  `;`-separated in the attribute and arrays in the property. Every row's `level`, `expanded`, `selected`,
+  `indeterminate` and roving `tabindex` are written from the tree on each sync — drive the two arrays, not the
+  rows.
+- **Expansion**: the toggle opens a branch. `expand-on-click` widens that to the whole row — and to Enter and
+  Space — which is what a navigation tree wants, where a branch row is a heading with nothing to select. A leaf
+  is never a branch, so a row that is only a link still just follows it.
+- **Selection**: `selection` is `none`, `single` or `multiple`. `checkbox-selection` adds a `c2-checkbox` per
+  row and implies `multiple`; `selection-propagation` (`none` | `descendants` | `parents` | `both`) controls how
+  far a tick travels, and a partly-selected branch is left indeterminate. Disabled rows are never selected by a
+  relative and are left out of the tally, so a branch is not stuck half-ticked by a row nobody can click.
+- **Lazy loading**: mark a branch `has-children` and set `loadChildren` to a promise-returning function. The row
+  shows a `c2-spinner` while it runs, a rejection fires `item-load-error` and the branch stays retryable. When
+  authoring in markup, listen for `item-expand` and append the children yourself instead.
+- **Keyboard**: a `tree` with a roving `tabindex`. Arrow Up/Down walk the visible rows, Arrow Right expands then
+  descends, Arrow Left collapses then ascends, Home/End jump to the ends, Enter and Space select, `*` expands
+  the focused row's siblings, and typing jumps to a matching row. Shift extends a range and Ctrl/Cmd toggles.
+- **Cost**: only expanded rows render their children slot, so a collapsed subtree is not laid out and stays
+  out of the accessibility tree. The elements are still created, so a tree of many thousands of rows wants
+  virtualization rather than this component.
+
+`selection-change` and `expansion-change` do not bubble — several components fire `selection-change`, so listen
+on the tree itself rather than an ancestor.
+
+Theming: `--c2-tree--*` for the container and `--c2-tree-item--*` for the rows, which inherit through the tree.
+`row--indent`, `row--border-radius` and `guide--color` do most of the work: set `row--border-radius: 0` for the
+edge-to-edge bands of a layers panel, and `actions--opacity: 1` to stop the trailing actions hiding until hover.
+The full list is in `custom-elements.json` and on the docs site.

package/dist/tree-item-C6XnvUA1.js

@@ -0,0 +1,242 @@
+import { LitElement, html, nothing, unsafeCSS } from "lit";
+import { property, query } from "lit/decorators.js";
+import { customElement } from "@c2n/core/element-helper.js";
+import { isServer } from "lit-html/is-server.js";
+import { classMap } from "lit/directives/class-map.js";
+import { ifDefined } from "lit/directives/if-defined.js";
+import "@c2n/checkbox";
+import "@c2n/spinner";
+//#region src/tree-item.scss?inline
+var tree_item_default = "/* ex : var((width: 24px), width, c2-checkbox)  returns var(--c2-checkbox-width, 24px) */\n:host {\n  display: block;\n  color: var(--c2-tree-item--color,#18181b);\n  font-size: var(--c2-tree-item--font-size,14px);\n  font-weight: var(--c2-tree-item--font-weight);\n  font-family: var(--c2-tree-item--font-family);\n  line-height: var(--c2-tree-item--line-height,20px);\n}\n\n:host([hidden]) {\n  display: none;\n}\n\n:host(:focus) {\n  outline: none;\n}\n\n.row {\n  position: relative;\n  color: inherit;\n  text-decoration: none;\n  display: flex;\n  align-items: center;\n  box-sizing: border-box;\n  gap: var(--c2-tree-item__row--gap,6px);\n  min-height: var(--c2-tree-item__row--min-height,28px);\n  border-radius: var(--c2-tree-item__row--border-radius,4px);\n  background: var(--c2-tree-item--background,transparent);\n  cursor: pointer;\n  user-select: none;\n  transition: background-color 250ms cubic-bezier(0.2, 0, 0, 1), color 250ms cubic-bezier(0.2, 0, 0, 1);\n  padding-inline-start: calc(var(--c2-tree-item__row--indent,16px) * var(--level, 0) + var(--c2-tree-item__row--padding-inline-start,8px));\n  padding-inline-end: var(--c2-tree-item__row--padding-inline-end,8px);\n  padding-top: var(--c2-tree-item__row--padding-top,0px);\n  padding-bottom: var(--c2-tree-item__row--padding-bottom,0px);\n  inline-size: 100%;\n  min-inline-size: max-content;\n}\n\n:host([children-outline]) .row::before {\n  content: \"\";\n  position: absolute;\n  inset-block: 0;\n  inset-inline-start: calc(var(--c2-tree-item__row--padding-inline-start,8px) + var(--c2-tree-item__toggle--size,16px) / 2);\n  inline-size: calc(var(--c2-tree-item__row--indent,16px) * var(--level, 0));\n  pointer-events: none;\n  background-image: repeating-linear-gradient(to right, var(--c2-tree-item__guide--color,#e4e4e7) 0 var(--c2-tree-item__guide--width,1px), transparent var(--c2-tree-item__guide--width,1px) var(--c2-tree-item__row--indent,16px));\n}\n\n:host([children-outline]:dir(rtl)) .row::before {\n  background-image: repeating-linear-gradient(to left, var(--c2-tree-item__guide--color,#e4e4e7) 0 var(--c2-tree-item__guide--width,1px), transparent var(--c2-tree-item__guide--width,1px) var(--c2-tree-item__row--indent,16px));\n}\n\n:host(:not([disabled])) .row:hover {\n  color: var(--c2-tree-item__hover--color,var(--c2-tree-item--color,#18181b));\n  background: var(--c2-tree-item__hover--background,#f4f4f5);\n}\n\n:host([selected]) .row {\n  color: var(--c2-tree-item__selected--color,rgb(2, 101, 220));\n  background: var(--c2-tree-item__selected--background,#edf1fe);\n}\n\n:host([selected]:not([disabled])) .row:hover {\n  background: var(--c2-tree-item__selected__hover--background,var(--c2-tree-item__selected--background,#e2e9fd));\n}\n\n:host(:focus-visible) .row {\n  outline: var(--c2-tree-item__focus--outline,2px solid rgba(2, 101, 220, 0.4));\n  outline-offset: var(--c2-tree-item__focus--outline-offset,-2px);\n}\n\n:host([disabled]) {\n  opacity: var(--c2-tree-item__disabled--opacity,0.38);\n}\n\n:host([disabled]) .row {\n  cursor: default;\n}\n\n.toggle {\n  display: inline-flex;\n  flex: none;\n  align-items: center;\n  justify-content: center;\n  inline-size: var(--c2-tree-item__toggle--size,16px);\n  block-size: var(--c2-tree-item__toggle--size,16px);\n  color: var(--c2-tree-item__toggle--color,#71717a);\n  background: none;\n  border: none;\n  padding: 0;\n  cursor: inherit;\n  transform: rotate(var(--c2-tree-item__toggle--rotate-collapsed,0deg));\n  transition: transform var(--c2-tree-item__toggle--transition-duration,150ms) cubic-bezier(0.2, 0, 0, 1);\n}\n\n:host([expanded]) .toggle {\n  transform: rotate(var(--c2-tree-item__toggle--rotate,90deg));\n}\n\n.toggle.is-leaf {\n  visibility: hidden;\n}\n\n.toggle svg,\nslot[name=toggle-icon]::slotted(*) {\n  inline-size: 100%;\n  block-size: 100%;\n}\n\n.spinner {\n  flex: none;\n  --c2-spinner--size: var(--c2-tree-item__toggle--size,16px);\n  --c2-spinner--stroke-width: 6px;\n}\n\n.checkbox {\n  flex: none;\n  margin-inline-end: var(--c2-tree-item__checkbox--margin-inline-end,2px);\n}\n\nslot[name=icon]::slotted(*) {\n  flex: none;\n  color: var(--c2-tree-item__icon--color);\n  --c2-feather-icon--size: var(--c2-tree-item__icon--size,16px);\n  --c2-mat-icon--size: var(--c2-tree-item__icon--size,16px);\n  inline-size: var(--c2-tree-item__icon--size,16px);\n  block-size: var(--c2-tree-item__icon--size,16px);\n}\n\n.label {\n  flex: 1 1 auto;\n  min-inline-size: 0;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n\n.actions {\n  display: inline-flex;\n  flex: none;\n  align-items: center;\n  gap: var(--c2-tree-item__actions--gap,2px);\n  opacity: var(--c2-tree-item__actions--opacity,0);\n  transition: opacity 250ms cubic-bezier(0.2, 0, 0, 1);\n}\n\n.row:hover .actions,\n:host(:focus-visible) .actions,\n.actions:focus-within {\n  opacity: var(--c2-tree-item__actions__hover--opacity,1);\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .row,\n  .toggle,\n  .actions {\n    transition: none;\n  }\n}";
+//#endregion
+//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/tree-item.ts
+var _TreeItem;
+/** Fired when an item joins, leaves or changes identity, so its `c2-tree` can resync. */
+var TREE_ITEM_CHANGE_EVENT = "c2-tree-item-change";
+/** Fired when the disclosure toggle is activated. */
+var TREE_ITEM_TOGGLE_EVENT = "c2-tree-item-toggle";
+/** Fired when the row's checkbox is ticked or cleared. */
+var TREE_ITEM_CHECK_EVENT = "c2-tree-item-check";
+var TreeItem = class TreeItem extends LitElement {
+	static {
+		_TreeItem = this;
+	}
+	constructor(..._args) {
+		super(..._args);
+		this.value = "";
+		this.label = "";
+		this.disabled = false;
+		this.hasChildren = false;
+		this.href = "";
+		this.expanded = false;
+		this.selected = false;
+		this.indeterminate = false;
+		this.loading = false;
+		this.level = 0;
+		this.checkboxSelection = false;
+		this.childrenOutline = false;
+		this.setSize = 1;
+		this.posInSet = 1;
+		this.selectable = true;
+		this.#resolvedLabel = "";
+		this.#handleChildSlotChange = () => {
+			this.#notify();
+		};
+	}
+	static {
+		this.styles = unsafeCSS(tree_item_default);
+	}
+	/** Cached so the accessible name is not recomputed from slotted nodes on every sync. */
+	#resolvedLabel;
+	/** The row as a {@link TreeNode}, so both authoring modes produce the same event details and renderer input. */
+	get node() {
+		return {
+			value: this.value,
+			label: this.label || void 0,
+			disabled: this.disabled,
+			hasChildren: this.isBranch,
+			data: this.data
+		};
+	}
+	/** The nested rows, in document order. */
+	get childItems() {
+		if (isServer || !this.children) return [];
+		return [...this.children].filter((child) => child instanceof _TreeItem);
+	}
+	/** Whether the row can be expanded — it already has children, or declares that it will load some. */
+	get isBranch() {
+		return this.hasChildren || this.childItems.length > 0;
+	}
+	/** The accessible name of the row, resolved from the `label` slot, the `label` attribute or `value`. */
+	get resolvedLabel() {
+		return this.#resolvedLabel || this.label || this.value;
+	}
+	connectedCallback() {
+		super.connectedCallback();
+		this.#notify();
+	}
+	disconnectedCallback() {
+		super.disconnectedCallback();
+		this.#notify();
+	}
+	/**
+	* Asks the parent tree to resync. Only identity changes qualify: the tree writes `expanded`, `selected`,
+	* `level` and friends on every pass, so notifying on those would loop.
+	*/
+	#notify() {
+		this.dispatchEvent(new CustomEvent(TREE_ITEM_CHANGE_EVENT, {
+			bubbles: true,
+			composed: true
+		}));
+	}
+	willUpdate(changed) {
+		if (!this.hasUpdated) return;
+		if (changed.has("value") || changed.has("disabled") || changed.has("hasChildren")) this.#notify();
+	}
+	updated(changed) {
+		if (changed.has("level")) this.style.setProperty("--level", String(this.level));
+		this.#syncAria();
+	}
+	firstUpdated() {
+		this.#readLabelSlot();
+	}
+	/**
+	* ARIA is written imperatively on the host: `role="treeitem"` has to sit on the element the tree moves focus
+	* to, and the `role="group"` holding the children must be a descendant of it.
+	*/
+	#syncAria() {
+		this.setAttribute("role", "treeitem");
+		this.setAttribute("aria-level", String(this.level + 1));
+		this.setAttribute("aria-setsize", String(this.setSize));
+		this.setAttribute("aria-posinset", String(this.posInSet));
+		if (this.isBranch) this.setAttribute("aria-expanded", String(this.expanded));
+		else this.removeAttribute("aria-expanded");
+		if (this.selectable) this.setAttribute("aria-selected", String(this.selected));
+		else this.removeAttribute("aria-selected");
+		if (this.disabled) this.setAttribute("aria-disabled", "true");
+		else this.removeAttribute("aria-disabled");
+		this.setAttribute("aria-label", this.resolvedLabel);
+	}
+	#readLabelSlot() {
+		const assigned = this.labelSlot?.assignedNodes({ flatten: true }) ?? [];
+		this.#resolvedLabel = assigned.map((node) => node.textContent ?? "").join("").trim();
+		this.#syncAria();
+	}
+	#handleToggle(event) {
+		event.stopPropagation();
+		event.preventDefault();
+		if (this.disabled) return;
+		this.dispatchEvent(new CustomEvent(TREE_ITEM_TOGGLE_EVENT, {
+			bubbles: true,
+			composed: true
+		}));
+	}
+	#handleCheckboxChange(event) {
+		event.stopPropagation();
+		const checked = event.target.checked;
+		this.dispatchEvent(new CustomEvent(TREE_ITEM_CHECK_EVENT, {
+			detail: checked,
+			bubbles: true,
+			composed: true
+		}));
+	}
+	render() {
+		const branch = this.isBranch;
+		const content = html`
+      ${this.loading ? html`<c2-spinner class="spinner" part="toggle" aria-hidden="true"></c2-spinner>` : html`<span class="toggle ${classMap({ "is-leaf": !branch })}" part="toggle" aria-hidden="true" @click=${this.#handleToggle}>
+              <slot name="toggle-icon">
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                  <polyline points="9 18 15 12 9 6"></polyline>
+                </svg>
+              </slot>
+            </span>`}
+      ${this.checkboxSelection ? html`<c2-checkbox
+              class="checkbox"
+              part="checkbox"
+              tabindex="-1"
+              aria-label=${this.resolvedLabel}
+              .checked=${this.selected}
+              .indeterminate=${this.indeterminate}
+              ?disabled=${this.disabled}
+              @click=${(event) => {
+			event.stopPropagation();
+			if (this.href) event.preventDefault();
+		}}
+              @change=${this.#handleCheckboxChange}
+            ></c2-checkbox>` : nothing}
+      <slot name="icon"></slot>
+      <span class="label" part="label">
+        <slot name="label" @slotchange=${this.#readLabelSlot}>${this.label || this.value}</slot>
+      </span>
+      <span class="actions" part="actions"><slot name="actions"></slot></span>
+    `;
+		const row = this.href && !this.disabled ? html`<a
+            class="row"
+            part="row"
+            href=${this.href}
+            target=${ifDefined(this.target || void 0)}
+            rel=${this.target === "_blank" ? "noopener noreferrer" : nothing}
+            tabindex="-1"
+            >${content}</a
+          >` : html`<div class="row" part="row">${content}</div>`;
+		return html`
+      ${row} ${this.expanded ? html`<div class="group" part="group" role="group"><slot @slotchange=${this.#handleChildSlotChange}></slot></div>` : nothing}
+    `;
+	}
+	#handleChildSlotChange;
+};
+__decorate([property({
+	type: String,
+	reflect: true
+})], TreeItem.prototype, "value", void 0);
+__decorate([property({ type: String })], TreeItem.prototype, "label", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], TreeItem.prototype, "disabled", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true,
+	attribute: "has-children"
+})], TreeItem.prototype, "hasChildren", void 0);
+__decorate([property({ type: String })], TreeItem.prototype, "href", void 0);
+__decorate([property({ type: String })], TreeItem.prototype, "target", void 0);
+__decorate([property({ attribute: false })], TreeItem.prototype, "data", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], TreeItem.prototype, "expanded", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], TreeItem.prototype, "selected", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], TreeItem.prototype, "indeterminate", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], TreeItem.prototype, "loading", void 0);
+__decorate([property({ attribute: false })], TreeItem.prototype, "level", void 0);
+__decorate([property({ attribute: false })], TreeItem.prototype, "checkboxSelection", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true,
+	attribute: "children-outline"
+})], TreeItem.prototype, "childrenOutline", void 0);
+__decorate([property({ attribute: false })], TreeItem.prototype, "setSize", void 0);
+__decorate([property({ attribute: false })], TreeItem.prototype, "posInSet", void 0);
+__decorate([property({ attribute: false })], TreeItem.prototype, "selectable", void 0);
+__decorate([query("slot[name=\"label\"]")], TreeItem.prototype, "labelSlot", void 0);
+TreeItem = _TreeItem = __decorate([customElement("c2-tree-item")], TreeItem);
+//#endregion
+export { __decorate as a, TreeItem as i, TREE_ITEM_CHECK_EVENT as n, TREE_ITEM_TOGGLE_EVENT as r, TREE_ITEM_CHANGE_EVENT as t };

package/dist/tree-item.js

@@ -0,0 +1,2 @@
+import { i as TreeItem, n as TREE_ITEM_CHECK_EVENT, r as TREE_ITEM_TOGGLE_EVENT, t as TREE_ITEM_CHANGE_EVENT } from "./tree-item-C6XnvUA1.js";
+export { TREE_ITEM_CHANGE_EVENT, TREE_ITEM_CHECK_EVENT, TREE_ITEM_TOGGLE_EVENT, TreeItem };