@hypoth-ui/cli 0.0.1 → 0.1.1

package/templates/tree/tree.tsx

@@ -0,0 +1,138 @@
+"use client";
+
+import {
+  type HTMLAttributes,
+  type ReactNode,
+  createElement,
+  forwardRef,
+  useEffect,
+  useRef,
+} from "react";
+import "@hypoth-ui/wc";
+
+export type TreeSelectionMode = "single" | "multiple" | "none";
+export type TreeSize = "default" | "compact";
+
+export interface TreeRootProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Selection mode.
+   * @default "single"
+   */
+  selectionMode?: TreeSelectionMode;
+
+  /**
+   * Size variant.
+   * @default "default"
+   */
+  size?: TreeSize;
+
+  /**
+   * Show connecting lines.
+   * @default false
+   */
+  lines?: boolean;
+
+  /**
+   * Accessible label.
+   * @default "Tree"
+   */
+  label?: string;
+
+  /**
+   * Whether the tree is in a loading state.
+   * When true, sets aria-busy and disables keyboard navigation.
+   * @default false
+   */
+  loading?: boolean;
+
+  /**
+   * Text to display/announce during loading.
+   * @default "Loading..."
+   */
+  loadingText?: string;
+
+  /**
+   * Node IDs that are currently loading children.
+   * Allows for node-level loading indicators.
+   */
+  loadingNodes?: string[];
+
+  /**
+   * Callback when selection changes.
+   */
+  onSelectionChange?: (selectedItems: string[]) => void;
+
+  /**
+   * Tree content (TreeItem elements).
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Tree root component for hierarchical data display.
+ */
+export const TreeRoot = forwardRef<HTMLElement, TreeRootProps>(function TreeRoot(
+  {
+    selectionMode = "single",
+    size = "default",
+    lines = false,
+    label = "Tree",
+    loading = false,
+    loadingText = "Loading...",
+    loadingNodes,
+    onSelectionChange,
+    children,
+    className,
+    ...props
+  },
+  forwardedRef
+) {
+  const internalRef = useRef<HTMLElement>(null);
+
+  // Sync forwarded ref
+  useEffect(() => {
+    if (typeof forwardedRef === "function") {
+      forwardedRef(internalRef.current);
+    } else if (forwardedRef) {
+      (forwardedRef as React.MutableRefObject<HTMLElement | null>).current = internalRef.current;
+    }
+  }, [forwardedRef]);
+
+  // Set up event listeners
+  useEffect(() => {
+    const element = internalRef.current;
+    if (!element) return;
+
+    const handleSelectionChange = (e: Event) => {
+      const event = e as CustomEvent<{ selectedItems: string[] }>;
+      onSelectionChange?.(event.detail.selectedItems);
+    };
+
+    element.addEventListener("ds:selection-change", handleSelectionChange);
+    return () => element.removeEventListener("ds:selection-change", handleSelectionChange);
+  }, [onSelectionChange]);
+
+  // Sync loadingNodes as a property (cannot be set via attribute)
+  useEffect(() => {
+    const element = internalRef.current as HTMLElement & { loadingNodes?: Set<string> | string[] } | null;
+    if (element && loadingNodes !== undefined) {
+      element.loadingNodes = loadingNodes;
+    }
+  }, [loadingNodes]);
+
+  return createElement(
+    "ds-tree",
+    {
+      ref: internalRef,
+      "selection-mode": selectionMode,
+      size,
+      lines: lines || undefined,
+      label,
+      loading: loading || undefined,
+      "loading-text": loadingText,
+      class: className,
+      ...props,
+    },
+    children
+  );
+});

package/templates/tree/wc/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Tree component exports
+ */
+export { DsTree, type TreeSelectionMode, type TreeSize } from "./tree.js";
+export { DsTreeItem } from "./tree-item.js";
+export {
+  calculateTreeItemPosition,
+  updateTreeItemAriaAttributes,
+  updateAllTreeItemAriaAttributes,
+  type TreeItemPosition,
+} from "./tree-utils.js";

package/templates/tree/wc/tree-item.ts

@@ -0,0 +1,273 @@
+import { type TemplateResult, html, nothing } from "lit";
+import { property, state } from "lit/decorators.js";
+import { classMap } from "lit/directives/class-map.js";
+import { DSElement } from "../../base/ds-element.js";
+import { emitEvent } from "../../events/emit.js";
+import { define } from "../../registry/define.js";
+import type { DsTree } from "./tree.js";
+import { calculateTreeItemPosition } from "./tree-utils.js";
+
+// Chevron icon
+const chevronIcon = html`
+  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
+    <path d="M9 18l6-6-6-6" />
+  </svg>
+`;
+
+/**
+ * Tree item component for hierarchical nodes.
+ *
+ * @element ds-tree-item
+ *
+ * @slot - Item content (label)
+ * @slot icon - Optional leading icon
+ * @slot children - Nested TreeItem elements
+ *
+ * @fires ds-expand - When expand state changes
+ * @fires ds-select - When item is selected
+ * @fires ds-activate - When item is activated (Enter/double-click)
+ */
+export class DsTreeItem extends DSElement {
+  static override styles = [];
+
+  /**
+   * Unique item ID.
+   */
+  @property({ type: String, attribute: "item-id" })
+  itemId = "";
+
+  /**
+   * Whether item is expanded.
+   */
+  @property({ type: Boolean, reflect: true })
+  expanded = false;
+
+  /**
+   * Whether item is selected.
+   */
+  @property({ type: Boolean, reflect: true })
+  selected = false;
+
+  /**
+   * Whether item is disabled.
+   */
+  @property({ type: Boolean, reflect: true })
+  disabled = false;
+
+  /**
+   * Whether this item is loading (e.g., fetching children).
+   * Can be set directly or inherited from tree's loadingNodes.
+   */
+  @property({ type: Boolean, reflect: true })
+  loading = false;
+
+  @state()
+  private hasChildren = false;
+
+  @state()
+  private _level = 1;
+
+  @state()
+  private _setSize = 1;
+
+  @state()
+  private _posInSet = 1;
+
+  private get treeRoot(): DsTree | null {
+    return this.closest("ds-tree") as DsTree | null;
+  }
+
+  /**
+   * Returns true if this item is loading (either directly or via tree's loadingNodes).
+   */
+  private get isLoading(): boolean {
+    if (this.loading) return true;
+    const tree = this.treeRoot;
+    if (tree && this.itemId) {
+      return tree.isNodeLoading(this.itemId);
+    }
+    return false;
+  }
+
+  /**
+   * Returns true if the tree root is in a loading state.
+   */
+  private get isTreeLoading(): boolean {
+    return this.treeRoot?.loading ?? false;
+  }
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+    this.updateHasChildren();
+    // Calculate position after DOM is ready
+    requestAnimationFrame(() => {
+      this.updateAriaPosition();
+    });
+  }
+
+  /**
+   * Update ARIA position attributes for APG compliance.
+   * Provides screen readers with context like "Item 3 of 5, level 2".
+   */
+  private updateAriaPosition(): void {
+    const position = calculateTreeItemPosition(this as unknown as HTMLElement);
+    this._level = position.level;
+    this._setSize = position.setSize;
+    this._posInSet = position.posInSet;
+  }
+
+  private updateHasChildren(): void {
+    const childrenSlot = this.querySelector("[slot=children]");
+    this.hasChildren = childrenSlot !== null && childrenSlot.querySelector("ds-tree-item") !== null;
+  }
+
+  private handleExpandClick(event: Event): void {
+    event.stopPropagation();
+    if (this.disabled || this.isTreeLoading || this.isLoading || !this.hasChildren) return;
+
+    this.expanded = !this.expanded;
+    emitEvent(this, "expand", {
+      detail: {
+        itemId: this.itemId,
+        expanded: this.expanded,
+      },
+    });
+  }
+
+  private handleContentClick(): void {
+    if (this.disabled || this.isTreeLoading) return;
+
+    const tree = this.treeRoot;
+    if (tree) {
+      tree.handleItemSelect(this.itemId);
+      this.selected = tree.isItemSelected(this.itemId);
+    }
+
+    emitEvent(this, "select", {
+      detail: {
+        itemId: this.itemId,
+        selected: this.selected,
+      },
+    });
+  }
+
+  private handleKeyDown(event: KeyboardEvent): void {
+    if (this.disabled || this.isTreeLoading) return;
+
+    switch (event.key) {
+      case "ArrowRight":
+        if (this.hasChildren && !this.expanded) {
+          event.preventDefault();
+          this.expanded = true;
+          emitEvent(this, "expand", {
+            detail: {
+              itemId: this.itemId,
+              expanded: true,
+            },
+          });
+        }
+        break;
+
+      case "ArrowLeft":
+        if (this.hasChildren && this.expanded) {
+          event.preventDefault();
+          this.expanded = false;
+          emitEvent(this, "expand", {
+            detail: {
+              itemId: this.itemId,
+              expanded: false,
+            },
+          });
+        }
+        break;
+
+      case "Enter":
+        event.preventDefault();
+        emitEvent(this, "activate", { detail: { itemId: this.itemId } });
+        break;
+
+      case " ":
+        event.preventDefault();
+        this.handleContentClick();
+        break;
+    }
+  }
+
+  override render(): TemplateResult {
+    const classes = {
+      "ds-tree-item": true,
+    };
+
+    // Check for children via slot
+    this.updateHasChildren();
+
+    const itemLoading = this.isLoading;
+
+    return html`
+      <li
+        class=${classMap(classes)}
+        role="treeitem"
+        aria-expanded=${this.hasChildren ? (this.expanded ? "true" : "false") : nothing}
+        aria-selected=${this.selected ? "true" : "false"}
+        aria-busy=${itemLoading ? "true" : nothing}
+        aria-level=${this._level}
+        aria-setsize=${this._setSize}
+        aria-posinset=${this._posInSet}
+        ?data-expanded=${this.expanded}
+        ?data-selected=${this.selected}
+        ?data-disabled=${this.disabled}
+        ?data-loading=${itemLoading}
+      >
+        <div
+          class="ds-tree-item__content"
+          tabindex=${this.disabled ? -1 : 0}
+          @click=${this.handleContentClick}
+          @keydown=${this.handleKeyDown}
+        >
+          ${
+            this.hasChildren
+              ? html`
+                <button
+                  type="button"
+                  class="ds-tree-item__expand"
+                  aria-label=${this.expanded ? "Collapse" : "Expand"}
+                  tabindex="-1"
+                  @click=${this.handleExpandClick}
+                >
+                  ${chevronIcon}
+                </button>
+              `
+              : html`<span class="ds-tree-item__spacer"></span>`
+          }
+          <slot name="icon"></slot>
+          <span class="ds-tree-item__label">
+            <slot></slot>
+          </span>
+        </div>
+        ${
+          this.hasChildren
+            ? html`
+              <ul
+                class="ds-tree-item__children ds-tree"
+                role="group"
+                ?hidden=${!this.expanded}
+              >
+                <slot name="children" @slotchange=${this.updateHasChildren}></slot>
+              </ul>
+            `
+            : nothing
+        }
+      </li>
+    `;
+  }
+}
+
+// Register the component
+define("ds-tree-item", DsTreeItem);
+
+// TypeScript declaration for HTML
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-tree-item": DsTreeItem;
+  }
+}

package/templates/tree/wc/tree-utils.ts

@@ -0,0 +1,143 @@
+/**
+ * Tree structure utilities for APG-compliant ARIA attributes.
+ *
+ * Calculates aria-level, aria-setsize, and aria-posinset for tree items
+ * to provide proper screen reader context (e.g., "Item 3 of 5, level 2").
+ */
+
+export interface TreeItemPosition {
+  /** Nesting depth (1-based, root items are level 1) */
+  level: number;
+  /** Number of siblings at this level */
+  setSize: number;
+  /** Position among siblings (1-based) */
+  posInSet: number;
+}
+
+/**
+ * Calculate position attributes for a tree item element.
+ *
+ * @param element - The ds-tree-item element
+ * @returns Position info for aria-level, aria-setsize, aria-posinset
+ *
+ * @example
+ * ```ts
+ * const position = calculateTreeItemPosition(treeItemElement);
+ * // { level: 2, setSize: 3, posInSet: 1 }
+ * ```
+ */
+export function calculateTreeItemPosition(element: HTMLElement): TreeItemPosition {
+  // Calculate level by counting ancestor tree items
+  let level = 1;
+  let parent: HTMLElement | null = element.parentElement;
+
+  while (parent) {
+    // Check if parent is a tree item (indicates nested level)
+    if (parent.tagName?.toLowerCase() === "ds-tree-item") {
+      level++;
+    }
+    // Stop at tree root
+    if (parent.tagName?.toLowerCase() === "ds-tree") {
+      break;
+    }
+    parent = parent.parentElement;
+  }
+
+  // Find siblings at the same level
+  const siblings = getSiblingTreeItems(element);
+  const setSize = siblings.length;
+  const posInSet = siblings.indexOf(element) + 1;
+
+  return { level, setSize, posInSet };
+}
+
+/**
+ * Get sibling tree items at the same level.
+ *
+ * @param element - The ds-tree-item element
+ * @returns Array of sibling tree item elements
+ */
+function getSiblingTreeItems(element: HTMLElement): HTMLElement[] {
+  // Find the container (either tree root or children slot)
+  let container: HTMLElement | null = element.parentElement;
+
+  // If parent is a slot, get the slot's parent
+  if (container?.tagName?.toLowerCase() === "slot") {
+    container = container.parentElement;
+  }
+
+  // If parent is a ul with role="group", get its parent (the tree-item)
+  // and then find the children slot
+  if (container?.getAttribute("role") === "group") {
+    container = container.parentElement;
+  }
+
+  if (!container) {
+    return [element];
+  }
+
+  // Query for direct tree-item children
+  // This handles both root level (ds-tree > ds-tree-item)
+  // and nested level (ds-tree-item [slot=children] > ds-tree-item)
+  const items: HTMLElement[] = [];
+
+  // Check direct children and slotted children
+  const checkChildren = (parent: HTMLElement) => {
+    for (const child of parent.children) {
+      if (child.tagName?.toLowerCase() === "ds-tree-item") {
+        items.push(child as HTMLElement);
+      } else if (child.tagName?.toLowerCase() === "slot") {
+        // Get assigned elements from slot
+        const slot = child as HTMLSlotElement;
+        for (const assigned of slot.assignedElements()) {
+          if (assigned.tagName?.toLowerCase() === "ds-tree-item") {
+            items.push(assigned as HTMLElement);
+          }
+        }
+      }
+    }
+  };
+
+  // For root tree, check its direct children
+  if (container.tagName?.toLowerCase() === "ds-tree") {
+    checkChildren(container);
+  } else if (container.tagName?.toLowerCase() === "ds-tree-item") {
+    // For nested items, find the children slot container
+    const childrenSlot = container.querySelector('[slot="children"]');
+    if (childrenSlot) {
+      for (const child of childrenSlot.children) {
+        if (child.tagName?.toLowerCase() === "ds-tree-item") {
+          items.push(child as HTMLElement);
+        }
+      }
+    }
+  }
+
+  // If no items found via DOM traversal, fall back to the element itself
+  return items.length > 0 ? items : [element];
+}
+
+/**
+ * Update ARIA position attributes on a tree item element.
+ *
+ * @param element - The ds-tree-item element to update
+ */
+export function updateTreeItemAriaAttributes(element: HTMLElement): void {
+  const position = calculateTreeItemPosition(element);
+
+  element.setAttribute("aria-level", String(position.level));
+  element.setAttribute("aria-setsize", String(position.setSize));
+  element.setAttribute("aria-posinset", String(position.posInSet));
+}
+
+/**
+ * Update ARIA position attributes on all tree items within a tree.
+ *
+ * @param treeRoot - The ds-tree root element
+ */
+export function updateAllTreeItemAriaAttributes(treeRoot: HTMLElement): void {
+  const items = treeRoot.querySelectorAll("ds-tree-item");
+  for (const item of items) {
+    updateTreeItemAriaAttributes(item as unknown as HTMLElement);
+  }
+}

package/templates/tree/wc/tree.ts

@@ -0,0 +1,139 @@
+import { type TemplateResult, html, nothing } from "lit";
+import { property, state } from "lit/decorators.js";
+import { classMap } from "lit/directives/class-map.js";
+import { DSElement } from "../../base/ds-element.js";
+import { emitEvent } from "../../events/emit.js";
+import { define } from "../../registry/define.js";
+
+export type TreeSelectionMode = "single" | "multiple" | "none";
+export type TreeSize = "default" | "compact";
+
+/**
+ * Tree root component for hierarchical data display.
+ *
+ * @element ds-tree
+ *
+ * @slot - TreeItem elements
+ *
+ * @fires ds-selection-change - When selection changes
+ *
+ * @cssprop --ds-tree-indent - Indentation for nested items
+ */
+export class DsTree extends DSElement {
+  static override styles = [];
+
+  /**
+   * Selection mode.
+   */
+  @property({ type: String, attribute: "selection-mode", reflect: true })
+  selectionMode: TreeSelectionMode = "single";
+
+  /**
+   * Size variant.
+   */
+  @property({ type: String, reflect: true })
+  size: TreeSize = "default";
+
+  /**
+   * Show connecting lines.
+   */
+  @property({ type: Boolean, reflect: true })
+  lines = false;
+
+  /**
+   * Accessible label.
+   */
+  @property({ type: String })
+  label = "Tree";
+
+  /**
+   * Whether the tree is in a loading state.
+   * When true, sets aria-busy and disables keyboard navigation.
+   */
+  @property({ type: Boolean, reflect: true })
+  loading = false;
+
+  /**
+   * Text to display/announce during loading.
+   */
+  @property({ type: String, attribute: "loading-text" })
+  loadingText = "Loading...";
+
+  /**
+   * Node IDs that are currently loading children.
+   * Allows for node-level loading indicators.
+   */
+  @property({ attribute: false })
+  loadingNodes: Set<string> | string[] = new Set();
+
+  @state()
+  private selectedItems: Set<string> = new Set();
+
+  /**
+   * Checks if a specific node is currently loading.
+   */
+  isNodeLoading(nodeId: string): boolean {
+    if (this.loadingNodes instanceof Set) {
+      return this.loadingNodes.has(nodeId);
+    }
+    return this.loadingNodes.includes(nodeId);
+  }
+
+  handleItemSelect(itemId: string): void {
+    // Disable selection during loading
+    if (this.loading) return;
+    if (this.selectionMode === "none") return;
+
+    if (this.selectionMode === "single") {
+      this.selectedItems.clear();
+      this.selectedItems.add(itemId);
+    } else {
+      if (this.selectedItems.has(itemId)) {
+        this.selectedItems.delete(itemId);
+      } else {
+        this.selectedItems.add(itemId);
+      }
+    }
+
+    emitEvent(this, "selection-change", {
+      detail: { selectedItems: Array.from(this.selectedItems) },
+    });
+
+    this.requestUpdate();
+  }
+
+  isItemSelected(itemId: string): boolean {
+    return this.selectedItems.has(itemId);
+  }
+
+  override render(): TemplateResult {
+    const classes = {
+      "ds-tree": true,
+    };
+
+    return html`
+      <ul
+        class=${classMap(classes)}
+        role="tree"
+        aria-label=${this.label}
+        aria-multiselectable=${this.selectionMode === "multiple" ? "true" : nothing}
+        aria-busy=${this.loading ? "true" : nothing}
+        data-size=${this.size !== "default" ? this.size : nothing}
+        ?data-lines=${this.lines}
+        ?data-loading=${this.loading}
+      >
+        <slot></slot>
+      </ul>
+    `;
+  }
+}
+
+// Register the component
+define("ds-tree", DsTree);
+
+// TypeScript declaration for HTML
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-tree": DsTree;
+  }
+}