@keyfunc/keybricks-ds 1.0.0

package/components/navigation/Tree.d.ts

@@ -0,0 +1,83 @@
+import * as React from "react";
+
+export interface TreeItem {
+  /** Stable identity; falls back to `label` when omitted */
+  key?: string;
+  /** Row text; `label` is accepted as an alias */
+  title?: string;
+  label?: string;
+  icon?: string;
+  /** Leaf glyph hue: orange | green | purple | blue | teal | gray */
+  hue?: string;
+  /** Right-aligned count */
+  count?: number;
+  /** Small inline pill after the title */
+  tag?: string;
+  children?: TreeItem[];
+  /** Row is greyed out and inert (selection, check and drag all blocked) */
+  disabled?: boolean;
+  /** Row stays interactive but its checkbox is locked */
+  disableCheckbox?: boolean;
+  /** Clicking the row does not select it (folder-only trees) */
+  selectable?: boolean;
+  /** Hide this row's checkbox in a checkable tree */
+  checkable?: boolean;
+  /** false marks an expandable branch whose children arrive from `loadData` */
+  isLeaf?: boolean;
+}
+
+export interface TreeDropInfo {
+  dragKey: string;
+  dropKey: string;
+  position: "before" | "after" | "inside";
+  treeData: TreeItem[];
+}
+
+/**
+ * Nested tree view: expand/collapse, single or multiple selection, cascading checkboxes with
+ * indeterminate parents, disabled nodes, connector lines, async loading, search highlight,
+ * drag to move, keyboard navigation.
+ */
+export interface TreeProps {
+  items?: TreeItem[];
+  /** Alias for `items` */
+  treeData?: TreeItem[];
+  /** Keys of initially expanded branches */
+  defaultExpanded?: string[];
+  /** Controlled expansion */
+  expandedKeys?: string[];
+  onExpand?: (keys: string[]) => void;
+  /** Convenience single-selection seed */
+  defaultActive?: string;
+  defaultSelected?: string[];
+  selectedKeys?: string[];
+  onSelect?: (key: string | string[], keys: string[]) => void;
+  /** Render a checkbox on every row */
+  checkable?: boolean;
+  /** Parent and child checkboxes stop cascading into each other */
+  checkStrictly?: boolean;
+  defaultChecked?: string[];
+  checkedKeys?: string[];
+  onCheck?: (keys: string[], info: { key: string; checked: boolean; half: string[] }) => void;
+  /** Allow more than one selected row */
+  multiple?: boolean;
+  /** false = rows only expand, never select */
+  selectable?: boolean;
+  showIcon?: boolean;
+  /** Draw connector lines instead of plain indentation */
+  showLine?: boolean;
+  draggable?: boolean;
+  /** Also allow insert-between: a folder's outer 20% becomes a before/after rule. Off by default — a drag moves a node INTO a folder, and files are never drop targets. */
+  reorder?: boolean;
+  /** Highlights matches and auto-expands their ancestors */
+  searchValue?: string;
+  autoExpandOnSearch?: boolean;
+  /** Return (or resolve) the children of a branch the first time it opens */
+  loadData?: (node: TreeItem) => TreeItem[] | Promise<TreeItem[]>;
+  onDrop?: (info: TreeDropInfo) => void;
+  onContextMenu?: (key: string, event: React.MouseEvent) => void;
+  /** Trailing controls revealed on row hover */
+  rowActions?: (node: TreeItem) => React.ReactNode;
+  style?: React.CSSProperties;
+}
+export declare function Tree(props: TreeProps): JSX.Element;

package/components/navigation/Tree.jsx

@@ -0,0 +1,347 @@
+import React from "react";
+import { Icon } from "../icons/Icon.jsx";
+import { Checkbox } from "../forms/Checkbox.jsx";
+
+const docHues = { orange: "var(--cat-transform)", green: "var(--cat-source)", purple: "var(--cat-merge)", blue: "var(--info-fg)", teal: "var(--cat-output)", gray: "var(--text-muted)" };
+const INDENT = 18;
+
+const keyOf = (n) => (n.key != null ? n.key : n.label);
+const titleOf = (n) => (n.title != null ? n.title : n.label);
+const kidsOf = (n) => n.children || [];
+const isBranch = (n) => kidsOf(n).length > 0 || n.isLeaf === false;
+
+function walk(nodes, fn, parentKey = null, depth = 0) {
+  nodes.forEach((n) => { fn(n, parentKey, depth); walk(kidsOf(n), fn, keyOf(n), depth + 1); });
+}
+function indexNodes(items) {
+  const byKey = {}, parent = {}, all = [];
+  walk(items, (n, p, d) => { const k = keyOf(n); byKey[k] = n; parent[k] = p; all.push({ node: n, key: k, depth: d }); });
+  return { byKey, parent, all };
+}
+function descendants(node, out = []) {
+  kidsOf(node).forEach((c) => { out.push(c); descendants(c, out); });
+  return out;
+}
+/** Is `key` the dragged node itself, or anywhere inside its subtree? */
+function inSubtree(items, rootKey, key) {
+  const { byKey } = indexNodes(items);
+  const root = byKey[rootKey];
+  if (!root) return false;
+  return rootKey === key || descendants(root).some((d) => keyOf(d) === key);
+}
+function keysMatching(items, test) {
+  const hit = [];
+  const visit = (n, trail) => {
+    const t = [...trail, keyOf(n)];
+    if (test(n)) hit.push(...trail);
+    kidsOf(n).forEach((c) => visit(c, t));
+  };
+  items.forEach((n) => visit(n, []));
+  return [...new Set(hit)];
+}
+
+/* Cascading check: a parent is checked when every enabled descendant is checked,
+   indeterminate when only some are. Disabled nodes never change state. */
+function cascade(items, key, next) {
+  const { byKey, parent } = indexNodes(items);
+  const set = new Set(next);
+  const node = byKey[key];
+  if (!node) return next;
+  const checked = set.has(key);
+  descendants(node).forEach((d) => {
+    if (d.disabled || d.disableCheckbox) return;
+    checked ? set.add(keyOf(d)) : set.delete(keyOf(d));
+  });
+  let p = parent[key];
+  while (p != null) {
+    const pn = byKey[p];
+    const kids = kidsOf(pn).filter((c) => !c.disabled && !c.disableCheckbox);
+    const on = kids.filter((c) => set.has(keyOf(c)));
+    on.length && on.length === kids.length ? set.add(p) : set.delete(p);
+    p = parent[p];
+  }
+  return [...set];
+}
+/* Display state for every branch: full when all enabled descendants are checked,
+   half when only some. Keeps parents honest whatever the caller passed in. */
+function rollUp(items, checkedKeys) {
+  const full = new Set(checkedKeys), half = new Set();
+  const visit = (n) => {
+    kidsOf(n).forEach(visit);
+    if (!kidsOf(n).length) return;
+    const ds = descendants(n).filter((d) => !d.disabled && !d.disableCheckbox);
+    if (!ds.length) return;
+    const on = ds.filter((d) => full.has(keyOf(d))).length;
+    if (on === ds.length) full.add(keyOf(n));
+    else { full.delete(keyOf(n)); if (on > 0) half.add(keyOf(n)); }
+  };
+  items.forEach(visit);
+  return { full, half };
+}
+function halfKeys(items, checkedKeys) {
+  return [...rollUp(items, checkedKeys).half];
+}
+
+function Highlight({ text, query }) {
+  if (!query) return text;
+  const i = String(text).toLowerCase().indexOf(query.toLowerCase());
+  if (i < 0) return text;
+  return <>{String(text).slice(0, i)}<mark style={{ background: "var(--soft-bg)", color: "var(--info-fg)", fontWeight: "var(--weight-medium)", padding: 0, borderRadius: 2 }}>{String(text).slice(i, i + query.length)}</mark>{String(text).slice(i + query.length)}</>;
+}
+
+/** Guide lines for showLine: one 18px column per ancestor level, then the elbow. */
+function Guides({ trail, isLast, hasKids }) {
+  return (
+    <>
+      {trail.map((ancestorHasNext, i) => (
+        <span key={i} style={{ width: INDENT, alignSelf: "stretch", flexShrink: 0, borderLeft: ancestorHasNext ? "1px solid var(--border-subtle)" : "1px solid transparent", marginLeft: i === 0 ? 6 : 0 }} />
+      ))}
+      <span style={{ width: INDENT, alignSelf: "stretch", flexShrink: 0, position: "relative", marginLeft: trail.length === 0 ? 6 : 0 }}>
+        <span style={{ position: "absolute", left: 0, top: 0, height: isLast ? "50%" : "100%", borderLeft: "1px solid var(--border-subtle)" }} />
+        <span style={{ position: "absolute", left: 0, top: "50%", width: hasKids ? 6 : INDENT - 4, borderTop: "1px solid var(--border-subtle)" }} />
+      </span>
+    </>
+  );
+}
+
+function Row({ item, state, cfg, api }) {
+  const { node, key, depth, trail, isLast } = item;
+  const kids = kidsOf(node);
+  const branch = isBranch(node);
+  const open = state.expanded.includes(key);
+  const selected = state.selected.includes(key);
+  const checked = state.checked.has(key);
+  const half = !checked && state.half.has(key);
+  const loading = state.loading.includes(key);
+  const focused = state.focus === key;
+  const ringed = focused && state.focusMoved;
+  const [hover, setHover] = React.useState(false);
+  const disabled = !!node.disabled;
+  const dropAt = state.drop && state.drop.key === key ? state.drop.pos : null;
+  const selectable = cfg.selectable && node.selectable !== false;
+
+  const chevron = branch ? (
+    <span onClick={(e) => { e.stopPropagation(); api.toggle(key); }} style={{ width: 14, height: 14, display: "inline-flex", alignItems: "center", justifyContent: "center", color: "var(--text-muted)", flexShrink: 0, cursor: "pointer", transform: open ? "rotate(90deg)" : "none", transition: "transform var(--dur-fast) var(--ease-out)" }}>
+      {loading ? <Icon name="loader" size={12} style={{ animation: "kb-tree-spin 900ms linear infinite" }} /> : <Icon name="chevron-right" size={13} />}
+    </span>
+  ) : <span style={{ width: cfg.showLine ? 0 : 14, flexShrink: 0 }} />;
+
+  return (
+    <>
+      <div role="treeitem" tabIndex={focused ? 0 : -1} aria-expanded={branch ? open : undefined} aria-selected={selected} aria-disabled={disabled || undefined}
+        ref={(el) => { if (el && focused && state.focusMoved) el.focus({ preventScroll: true }); }}
+        draggable={cfg.draggable && !disabled}
+        onDragStart={(e) => { e.dataTransfer.effectAllowed = "move"; api.dragStart(key); }}
+        onDragOver={(e) => { if (!cfg.draggable) return; e.preventDefault(); const r = e.currentTarget.getBoundingClientRect(); api.dragOver(key, (e.clientY - r.top) / r.height); }}
+        onDragLeave={() => api.dragOver(null)}
+        onDrop={(e) => { e.preventDefault(); api.drop(key); }}
+        onDragEnd={() => api.dragEnd()}
+        onClick={() => { if (disabled) return; api.focus(key); if (selectable) api.select(key); if (branch) api.toggle(key); }}
+        onContextMenu={(e) => { if (cfg.onContextMenu) { e.preventDefault(); cfg.onContextMenu(key, e); } }}
+        onKeyDown={(e) => api.keyDown(e, item)}
+        onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}
+        style={{
+          minHeight: "var(--h-tree-item)", borderRadius: "var(--radius-md)", display: "flex", alignItems: "center", gap: 6,
+          padding: cfg.showLine ? "0 8px 0 2px" : "5px 8px", paddingLeft: cfg.showLine ? 2 : 8 + depth * INDENT, boxSizing: "border-box",
+          cursor: disabled ? "not-allowed" : "pointer", opacity: disabled ? 0.45 : 1,
+          background: dropAt === "inside" ? "var(--soft-bg)" : selected ? "var(--bg-active)" : hover && !disabled ? "var(--bg-hover)" : "transparent",
+          outline: dropAt === "inside" ? "2px solid var(--action-primary)" : ringed ? "2px solid var(--focus-border)" : "none", outlineOffset: -2,
+          boxShadow: dropAt === "before" ? "inset 0 2px 0 var(--action-primary)" : dropAt === "after" ? "inset 0 -2px 0 var(--action-primary)" : "none",
+          transition: "var(--t-hover)",
+        }}>
+        {cfg.showLine ? <Guides trail={trail} isLast={isLast} hasKids={branch} /> : null}
+        {chevron}
+        {cfg.checkable && node.checkable !== false ? (
+          <span onClick={(e) => e.stopPropagation()} style={{ display: "inline-flex", flexShrink: 0 }}>
+            <Checkbox size="sm" checked={checked} indeterminate={half} disabled={disabled || node.disableCheckbox} onChange={() => api.check(key)} />
+          </span>
+        ) : null}
+        {cfg.showIcon ? (
+          <span style={{ color: branch ? "var(--text-muted)" : docHues[node.hue || "gray"], display: "inline-flex", flexShrink: 0 }}>
+            <Icon name={node.icon || (branch ? (open ? "folder-open" : "folder") : "file-text")} size={15} />
+          </span>
+        ) : null}
+        <span style={{ fontFamily: "var(--font-sans)", fontSize: "var(--text-sm)", lineHeight: "var(--leading-sm)", fontWeight: selected ? "var(--weight-medium)" : "var(--weight-regular)", color: disabled ? "var(--text-muted)" : "var(--text-heading)", whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>
+          <Highlight text={titleOf(node)} query={cfg.searchValue} />
+        </span>
+        {node.tag ? <span style={{ fontFamily: "var(--font-sans)", fontSize: "var(--text-2xs)", lineHeight: 1, padding: "2px 5px", borderRadius: "var(--radius-sm)", background: "var(--bg-inset)", color: "var(--text-secondary)", flexShrink: 0 }}>{node.tag}</span> : null}
+        {node.count != null ? <span style={{ marginLeft: "auto", fontFamily: "var(--font-mono)", fontSize: "var(--text-2xs)", color: "var(--text-muted)", paddingLeft: 8 }}>{node.count}</span> : null}
+        {cfg.rowActions && !disabled ? <span style={{ marginLeft: node.count != null ? 6 : "auto", display: "flex", gap: 2, opacity: hover ? 1 : 0, transition: "var(--t-hover)" }} onClick={(e) => e.stopPropagation()}>{cfg.rowActions(node)}</span> : null}
+      </div>
+      {open && loading && !kids.length ? (
+        <div style={{ paddingLeft: 8 + (depth + 1) * INDENT + 14, fontFamily: "var(--font-sans)", fontSize: "var(--text-xs)", color: "var(--text-muted)", height: "var(--h-tree-item)", display: "flex", alignItems: "center" }}>Loading…</div>
+      ) : null}
+    </>
+  );
+}
+
+/**
+ * Nested tree view. Expand/collapse, single or multiple selection, cascading checkboxes
+ * (with indeterminate parents and `checkStrictly` opt-out), disabled nodes and disabled
+ * checkboxes, connector lines, async child loading, search highlighting, drag to move,
+ * and full keyboard navigation. Node shape: { key, title, icon, hue, count, tag, children,
+ * disabled, disableCheckbox, selectable, checkable, isLeaf }.
+ */
+export function Tree({
+  items = [], treeData,
+  defaultExpanded = [], expandedKeys, onExpand,
+  defaultActive, defaultSelected = [], selectedKeys, onSelect,
+  checkable = false, checkStrictly = false, defaultChecked = [], checkedKeys, onCheck,
+  multiple = false, selectable = true, showIcon = true, showLine = false, draggable = false,
+  searchValue = "", autoExpandOnSearch = true, loadData, onDrop, onContextMenu, rowActions, style, reorder = false,
+}) {
+  const raw = treeData || items;
+  /* Callers usually pass an inline array literal, so compare by value —
+     re-seeding on identity alone would wipe async-loaded children. */
+  const rawKey = JSON.stringify(raw);
+  const [data, setData] = React.useState(raw);
+  const seenKey = React.useRef(rawKey);
+  React.useEffect(() => { if (seenKey.current !== rawKey) { seenKey.current = rawKey; setData(raw); } }, [rawKey]);
+
+  const seedExpanded = defaultExpanded.length ? defaultExpanded : defaultActive ? [] : [];
+  const [expandedS, setExpandedS] = React.useState(seedExpanded);
+  const [selectedS, setSelectedS] = React.useState(defaultActive ? [defaultActive] : defaultSelected);
+  const [checkedS, setCheckedS] = React.useState(defaultChecked);
+  const [loading, setLoading] = React.useState([]);
+  const [loaded, setLoaded] = React.useState([]);
+  const [focus, setFocus] = React.useState(null);
+  const [focusMoved, setFocusMoved] = React.useState(false);
+  const [dragKey, setDragKey] = React.useState(null);
+  const [drop, setDrop] = React.useState(null);
+
+  const expanded = expandedKeys || expandedS;
+  const selected = selectedKeys || selectedS;
+  const checked = checkedKeys || checkedS;
+
+  const searchExpanded = React.useMemo(
+    () => (searchValue && autoExpandOnSearch ? keysMatching(data, (n) => String(titleOf(n)).toLowerCase().includes(searchValue.toLowerCase())) : []),
+    [data, searchValue, autoExpandOnSearch]
+  );
+  const openKeys = React.useMemo(() => [...new Set([...expanded, ...searchExpanded])], [expanded, searchExpanded]);
+  const view = React.useMemo(
+    () => (checkable && !checkStrictly ? rollUp(data, checked) : { full: new Set(checked), half: new Set() }),
+    [checkable, checkStrictly, data, checked]
+  );
+
+  /* Visible rows, with the sibling map each row needs to draw its guide lines. */
+  const rows = React.useMemo(() => {
+    const out = [];
+    const push = (nodes, depth, trail) => {
+      nodes.forEach((n, i) => {
+        const isLast = i === nodes.length - 1;
+        const key = keyOf(n);
+        out.push({ node: n, key, depth, trail, isLast });
+        if (kidsOf(n).length && openKeys.includes(key)) push(kidsOf(n), depth + 1, [...trail, !isLast]);
+      });
+    };
+    push(data, 0, []);
+    return out;
+  }, [data, openKeys]);
+
+  const setExpanded = (next) => { if (!expandedKeys) setExpandedS(next); onExpand && onExpand(next); };
+
+  const api = {
+    focus: (k) => { setFocus(k); setFocusMoved(false); },
+    toggle: (k) => {
+      const open = openKeys.includes(k);
+      if (!open && loadData && !loaded.includes(k) && !kidsOf(indexNodes(data).byKey[k]).length) {
+        setLoading((l) => [...l, k]);
+        setExpanded([...expanded, k]);
+        Promise.resolve(loadData(indexNodes(data).byKey[k])).then((kids) => {
+          setData((d) => {
+            const clone = JSON.parse(JSON.stringify(d));
+            const { byKey } = indexNodes(clone);
+            if (byKey[k]) byKey[k].children = kids || [];
+            return clone;
+          });
+          setLoaded((l) => [...l, k]);
+          setLoading((l) => l.filter((x) => x !== k));
+        });
+        return;
+      }
+      setExpanded(open ? expanded.filter((x) => x !== k) : [...expanded, k]);
+    },
+    select: (k) => {
+      const next = multiple ? (selected.includes(k) ? selected.filter((x) => x !== k) : [...selected, k]) : selected.includes(k) && multiple ? [] : [k];
+      if (!selectedKeys) setSelectedS(next);
+      onSelect && onSelect(multiple ? next : k, next);
+    },
+    check: (k) => {
+      const on = view.full.has(k);
+      let next = on ? [...view.full].filter((x) => x !== k) : [...view.full, k];
+      if (!checkStrictly) next = cascade(data, k, next);
+      if (!checkedKeys) setCheckedS(next);
+      onCheck && onCheck(next, { key: k, checked: !on, half: checkStrictly ? [] : halfKeys(data, next) });
+    },
+    dragStart: (k) => setDragKey(k),
+    /* Validity lives here, not in the row: only branches can be dropped *into*, and a node
+       can never land inside its own subtree (that would detach the whole branch). */
+    dragOver: (k, ratio) => {
+      if (k == null) return setDrop(null);
+      const node = indexNodes(data).byKey[k];
+      /* Only folders are drop targets: a file can't contain anything, so hovering one shows
+         nothing at all. With reorder, a folder's outer 20% becomes an insert rule instead. */
+      if (!node || node.disabled || !dragKey || !isBranch(node) || inSubtree(data, dragKey, k)) return setDrop(null);
+      const pos = reorder ? (ratio < 0.2 ? "before" : ratio > 0.8 ? "after" : "inside") : "inside";
+      setDrop({ key: k, pos });
+    },
+    dragEnd: () => { setDragKey(null); setDrop(null); },
+    drop: (k) => {
+      const info = drop && drop.key === k ? drop : null;
+      setDrop(null);
+      if (!dragKey || !info || inSubtree(data, dragKey, k)) return setDragKey(null);
+      /* Computed outside setData: React re-invokes updaters (StrictMode, concurrent
+         rebasing), which would fire the consumer's onDrop twice for one gesture. */
+      const clone = JSON.parse(JSON.stringify(data));
+      let moved = null;
+      const prune = (nodes) => nodes.filter((n) => {
+        if (keyOf(n) === dragKey) { moved = n; return false; }
+        if (n.children) n.children = prune(n.children);
+        return true;
+      });
+      const rootA = prune(clone);
+      if (!moved) return setDragKey(null);
+      let inserted = false;
+      const insert = (nodes) => {
+        const out = [];
+        nodes.forEach((n) => {
+          if (keyOf(n) === k && info.pos === "before") { out.push(moved); inserted = true; }
+          if (keyOf(n) === k && info.pos === "inside") { n.children = [...(n.children || []), moved]; inserted = true; }
+          else if (n.children) n.children = insert(n.children);
+          out.push(n);
+          if (keyOf(n) === k && info.pos === "after") { out.push(moved); inserted = true; }
+        });
+        return out;
+      };
+      const next = insert(rootA);
+      if (!inserted) return setDragKey(null);
+      setData(next);
+      /* Dropping into a collapsed folder would otherwise look like the node vanished. */
+      if (info.pos === "inside" && !expanded.includes(k)) setExpanded([...expanded, k]);
+      onDrop && onDrop({ dragKey, dropKey: k, position: info.pos, treeData: next });
+      setDragKey(null);
+    },
+    keyDown: (e, item) => {
+      const i = rows.findIndex((r) => r.key === item.key);
+      const go = (n) => { const t = rows[n]; if (!t) return; setFocus(t.key); setFocusMoved(true); };
+      if (e.key === "ArrowDown") { e.preventDefault(); go(i + 1); }
+      else if (e.key === "ArrowUp") { e.preventDefault(); go(i - 1); }
+      else if (e.key === "ArrowRight") { e.preventDefault(); if (isBranch(item.node) && !openKeys.includes(item.key)) api.toggle(item.key); else go(i + 1); }
+      else if (e.key === "ArrowLeft") { e.preventDefault(); if (isBranch(item.node) && openKeys.includes(item.key)) api.toggle(item.key); else { const p = rows.slice(0, i).reverse().find((r) => r.depth === item.depth - 1); if (p) { setFocus(p.key); setFocusMoved(true); } } }
+      else if (e.key === "Enter") { e.preventDefault(); if (!item.node.disabled) { if (selectable && item.node.selectable !== false) api.select(item.key); if (isBranch(item.node)) api.toggle(item.key); } }
+      else if (e.key === " ") { e.preventDefault(); if (checkable && !item.node.disabled && item.node.checkable !== false && !item.node.disableCheckbox) api.check(item.key); }
+    },
+  };
+
+  const state = { expanded: openKeys, selected, checked: view.full, half: view.half, loading, focus: focus || (rows[0] && rows[0].key), focusMoved, drop };
+  const cfg = { checkable, checkStrictly, multiple, selectable, showIcon, showLine, draggable, searchValue, onContextMenu, rowActions };
+
+  return (
+    <div role="tree" aria-multiselectable={multiple || undefined} style={{ display: "flex", flexDirection: "column", gap: showLine ? 0 : 1, ...style }}>
+      <style>{"@keyframes kb-tree-spin{to{transform:rotate(360deg)}}"}</style>
+      {rows.length === 0 ? (
+        <div style={{ padding: "10px 8px", fontFamily: "var(--font-sans)", fontSize: "var(--text-sm)", color: "var(--text-muted)" }}>No matching items</div>
+      ) : rows.map((r) => <Row key={r.key} item={r} state={state} cfg={cfg} api={api} />)}
+    </div>
+  );
+}