@robr0/design-system 0.8.0 → 0.9.0

package/components/TreeView/TreeView.css

@@ -0,0 +1,119 @@
+/* ============================================
+   TREEVIEW COMPONENT
+   Collapsible hierarchy for files, folders,
+   and nested structures
+   ============================================ */
+
+/* Base */
+
+.ds-treeview {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* ============================================
+   ITEM — the focusable treeitem (roving tabindex)
+   ============================================ */
+
+.ds-treeview__item {
+  outline: none;
+}
+
+/* The focus ring draws on the item's own row, never on the subtree */
+.ds-treeview__item:focus-visible > .ds-treeview__row {
+  outline: 2px solid var(--color-action-primary-bg);
+  outline-offset: -2px;
+}
+
+/* ============================================
+   ROW — one line of the tree
+   Indentation steps per depth via a custom
+   property the component sets inline.
+   ============================================ */
+
+.ds-treeview__row {
+  display: flex;
+  align-items: center;
+  gap: var(--gap-xs);
+  padding: var(--padding-xxs) var(--padding-sm);
+  padding-left: calc(var(--padding-sm) + var(--ds-treeview-depth, 0) * var(--gap-md));
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  transition: background-color var(--motion-duration-fast) var(--motion-ease-standard);
+}
+
+/* States */
+
+.ds-treeview__row:hover {
+  background-color: var(--color-action-passive-bg-hover);
+}
+
+.ds-treeview__row--selected {
+  background-color: var(--color-action-passive-bg-active);
+}
+
+.ds-treeview__row--selected .ds-treeview__label {
+  font-weight: var(--font-paragraph-sm-em-weight);
+}
+
+/* ============================================
+   CHEVRON — rotates a quarter turn on expand
+   ============================================ */
+
+.ds-treeview__chevron {
+  flex-shrink: 0;
+  --icon-size: var(--icon-size-sm);
+  color: var(--color-icon-primary);
+  transition: transform var(--motion-duration-fast) var(--motion-ease-standard);
+}
+
+.ds-treeview__item[aria-expanded='true'] > .ds-treeview__row .ds-treeview__chevron {
+  transform: rotate(90deg);
+}
+
+/* Leaves keep the chevron column so labels align across depths */
+.ds-treeview__chevron--spacer {
+  display: inline-block;
+  width: var(--icon-size-sm);
+  height: var(--icon-size-sm);
+}
+
+/* ============================================
+   ICON
+   ============================================ */
+
+.ds-treeview__icon {
+  flex-shrink: 0;
+  --icon-size: var(--icon-size-sm);
+  color: var(--color-icon-primary);
+}
+
+/* ============================================
+   LABEL
+   ============================================ */
+
+.ds-treeview__label {
+  font-family: var(--font-paragraph-sm-family);
+  font-size: var(--font-paragraph-sm-size);
+  font-weight: var(--font-paragraph-sm-weight);
+  line-height: var(--font-paragraph-sm-line-height);
+  letter-spacing: var(--font-paragraph-sm-letter-spacing);
+  color: var(--color-text-primary);
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+/* ============================================
+   GROUP — nested children
+   ============================================ */
+
+.ds-treeview__group {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}

package/components/TreeView/TreeView.d.ts

@@ -0,0 +1,45 @@
+import { default as React } from 'react';
+export interface TreeViewNode {
+    /** Unique identifier for the node */
+    id: string;
+    /** Text shown on the row */
+    label: string;
+    /** Material Symbol name; defaults to `folder` for branches and `draft` for leaves */
+    icon?: string;
+    /** Child nodes; a non-empty list makes the node an expandable branch */
+    children?: TreeViewNode[];
+}
+/** Props owned by TreeView itself — everything else falls through to the root <ul>. */
+type TreeViewOwnProps = {
+    /** Tree data to render */
+    nodes: TreeViewNode[];
+    /** IDs of initially expanded branches (uncontrolled) */
+    defaultExpandedIds?: string[];
+    /** Expanded branch IDs (controlled) — pair with `onExpandedChange` */
+    expandedIds?: string[];
+    /** Called with the full list of expanded branch IDs whenever a branch toggles */
+    onExpandedChange?: (ids: string[]) => void;
+    /** Selected node ID (controlled) — pair with `onSelect` */
+    selectedId?: string;
+    /** ID of the initially selected node (uncontrolled) */
+    defaultSelectedId?: string;
+    /**
+     * Called with the node's ID when a row is selected via click, Enter, or
+     * Space. Intentionally shadows the native `select` event handler, which
+     * has no meaning on a tree widget.
+     */
+    onSelect?: (id: string) => void;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface TreeViewProps extends TreeViewOwnProps, Omit<React.ComponentPropsWithoutRef<'ul'>, keyof TreeViewOwnProps> {
+}
+/**
+ * TreeView renders a collapsible hierarchy — files, folders, and other
+ * nested structures — as a WAI-ARIA tree. Branches expand and collapse,
+ * one node can be selected, and a roving tabindex gives the whole tree a
+ * single tab stop with full arrow-key navigation. Expansion and selection
+ * each work controlled or uncontrolled.
+ */
+export declare const TreeView: React.ForwardRefExoticComponent<TreeViewProps & React.RefAttributes<HTMLUListElement>>;
+export {};

package/components/TreeView/TreeView.js

@@ -0,0 +1,232 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import React, { useState, useMemo, useRef, useCallback } from "react";
+import "./TreeView.css";
+import "../../fonts/material-symbols.css";
+const isBranchNode = (node) => Array.isArray(node.children) && node.children.length > 0;
+const TreeView = React.forwardRef(
+  ({
+    nodes,
+    defaultExpandedIds = [],
+    expandedIds,
+    onExpandedChange,
+    selectedId,
+    defaultSelectedId,
+    onSelect,
+    className = "",
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-treeview";
+    const baseId = React.useId();
+    const [internalExpanded, setInternalExpanded] = useState(
+      () => new Set(defaultExpandedIds)
+    );
+    const [internalSelected, setInternalSelected] = useState(
+      defaultSelectedId
+    );
+    const [focusedId, setFocusedId] = useState(void 0);
+    const expandedSet = useMemo(
+      () => expandedIds !== void 0 ? new Set(expandedIds) : internalExpanded,
+      [expandedIds, internalExpanded]
+    );
+    const selected = selectedId !== void 0 ? selectedId : internalSelected;
+    const itemRefs = useRef(/* @__PURE__ */ new Map());
+    const indexById = useMemo(() => {
+      const map = /* @__PURE__ */ new Map();
+      let i = 0;
+      const walk = (list) => {
+        for (const node of list) {
+          map.set(node.id, i);
+          i += 1;
+          if (node.children) walk(node.children);
+        }
+      };
+      walk(nodes);
+      return map;
+    }, [nodes]);
+    const parentById = useMemo(() => {
+      const map = /* @__PURE__ */ new Map();
+      const walk = (list, parent) => {
+        for (const node of list) {
+          map.set(node.id, parent);
+          if (node.children) walk(node.children, node.id);
+        }
+      };
+      walk(nodes);
+      return map;
+    }, [nodes]);
+    const visibleNodes = useMemo(() => {
+      const out = [];
+      const walk = (list) => {
+        for (const node of list) {
+          out.push(node);
+          if (isBranchNode(node) && expandedSet.has(node.id)) walk(node.children);
+        }
+      };
+      walk(nodes);
+      return out;
+    }, [nodes, expandedSet]);
+    const visibleIds = useMemo(
+      () => new Set(visibleNodes.map((node) => node.id)),
+      [visibleNodes]
+    );
+    const tabbableId = focusedId !== void 0 && visibleIds.has(focusedId) ? focusedId : selected !== void 0 && visibleIds.has(selected) ? selected : visibleNodes[0]?.id;
+    const commitExpanded = useCallback(
+      (next) => {
+        if (expandedIds === void 0) setInternalExpanded(next);
+        onExpandedChange?.(Array.from(next));
+      },
+      [expandedIds, onExpandedChange]
+    );
+    const toggleBranch = useCallback(
+      (id) => {
+        const next = new Set(expandedSet);
+        if (next.has(id)) {
+          next.delete(id);
+        } else {
+          next.add(id);
+        }
+        commitExpanded(next);
+      },
+      [expandedSet, commitExpanded]
+    );
+    const selectNode = useCallback(
+      (id) => {
+        if (selectedId === void 0) setInternalSelected(id);
+        onSelect?.(id);
+      },
+      [selectedId, onSelect]
+    );
+    const focusNode = useCallback((id) => {
+      if (id === void 0) return;
+      setFocusedId(id);
+      itemRefs.current.get(id)?.focus();
+    }, []);
+    const handleKeyDown = (event, node) => {
+      const branch = isBranchNode(node);
+      const expanded = expandedSet.has(node.id);
+      const index = visibleNodes.findIndex((n) => n.id === node.id);
+      let handled = true;
+      switch (event.key) {
+        case "ArrowDown":
+          focusNode(visibleNodes[index + 1]?.id);
+          break;
+        case "ArrowUp":
+          focusNode(visibleNodes[index - 1]?.id);
+          break;
+        case "ArrowRight":
+          if (branch && !expanded) {
+            toggleBranch(node.id);
+          } else if (branch && expanded) {
+            focusNode(node.children[0]?.id);
+          }
+          break;
+        case "ArrowLeft":
+          if (branch && expanded) {
+            toggleBranch(node.id);
+          } else {
+            focusNode(parentById.get(node.id));
+          }
+          break;
+        case "Home":
+          focusNode(visibleNodes[0]?.id);
+          break;
+        case "End":
+          focusNode(visibleNodes[visibleNodes.length - 1]?.id);
+          break;
+        case "Enter":
+        case " ":
+          selectNode(node.id);
+          break;
+        default:
+          handled = false;
+      }
+      if (handled) {
+        event.preventDefault();
+        event.stopPropagation();
+      }
+    };
+    const renderNode = (node, depth) => {
+      const branch = isBranchNode(node);
+      const expanded = branch && expandedSet.has(node.id);
+      const isSelected = selected === node.id;
+      const labelId = `${baseId}-label-${indexById.get(node.id)}`;
+      const icon = node.icon ?? (branch ? "folder" : "draft");
+      const rowClasses = [
+        `${baseClass}__row`,
+        isSelected && `${baseClass}__row--selected`
+      ].filter(Boolean).join(" ");
+      return /* @__PURE__ */ jsxs(
+        "li",
+        {
+          role: "treeitem",
+          "aria-expanded": branch ? expanded : void 0,
+          "aria-selected": isSelected,
+          "aria-labelledby": labelId,
+          tabIndex: node.id === tabbableId ? 0 : -1,
+          className: `${baseClass}__item`,
+          ref: (el) => {
+            if (el) {
+              itemRefs.current.set(node.id, el);
+            } else {
+              itemRefs.current.delete(node.id);
+            }
+          },
+          onKeyDown: (event) => handleKeyDown(event, node),
+          onFocus: (event) => {
+            event.stopPropagation();
+            setFocusedId(node.id);
+          },
+          onClick: (event) => {
+            event.stopPropagation();
+            if (branch) toggleBranch(node.id);
+            selectNode(node.id);
+            focusNode(node.id);
+          },
+          children: [
+            /* @__PURE__ */ jsxs(
+              "div",
+              {
+                className: rowClasses,
+                style: { "--ds-treeview-depth": depth },
+                children: [
+                  branch ? /* @__PURE__ */ jsx(
+                    "span",
+                    {
+                      className: `${baseClass}__chevron material-symbols-rounded`,
+                      "aria-hidden": "true",
+                      children: "chevron_right"
+                    }
+                  ) : /* @__PURE__ */ jsx(
+                    "span",
+                    {
+                      className: `${baseClass}__chevron ${baseClass}__chevron--spacer`,
+                      "aria-hidden": "true"
+                    }
+                  ),
+                  /* @__PURE__ */ jsx(
+                    "span",
+                    {
+                      className: `${baseClass}__icon material-symbols-rounded`,
+                      "aria-hidden": "true",
+                      children: icon
+                    }
+                  ),
+                  /* @__PURE__ */ jsx("span", { id: labelId, className: `${baseClass}__label`, children: node.label })
+                ]
+              }
+            ),
+            expanded && /* @__PURE__ */ jsx("ul", { role: "group", className: `${baseClass}__group`, children: node.children.map((child) => renderNode(child, depth + 1)) })
+          ]
+        },
+        node.id
+      );
+    };
+    const classes = [baseClass, className].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsx("ul", { ...rest, ref, role: "tree", className: classes, children: nodes.map((node) => renderNode(node, 0)) });
+  }
+);
+TreeView.displayName = "TreeView";
+export {
+  TreeView
+};

package/components/registry.d.ts

@@ -4,10 +4,11 @@
  *
  * The data lives in registry.json. Each entry in `components` carries:
  *
- *   name        the folder under src/components (also the exported name)
- *   label       the display name — "Navigation" for the Nav folder
- *   slug        the website route segment — stored, not derived, so the
- *               Nav → navigation exception is plain data rather than a
+ *   name        the exported component name; also the folder under
+ *               src/components unless `folder` says otherwise
+ *   label       the display name — "Nav list" for the NavList folder
+ *   slug        the website route segment — stored, not derived, so a
+ *               name-to-slug exception stays plain data rather than a
  *               special case duplicated across validators
  *   description one line, used for the page title, the sidebar search index,
  *               and anywhere the component is summarised
@@ -16,6 +17,9 @@
  *               uses hooks or defines handlers. Presentational components are
  *               deliberately false so consumers can render them from a React
  *               Server Component.
+ *   folder      set only when the implementation lives in a shared folder
+ *               rather than one named after the component — the nine chart
+ *               components all live in Chart/. Omitted everywhere else.
  *
  * `docOnlyHelpers` names the internal documentation helpers that are
  * deliberately excluded from the public count.
@@ -31,7 +35,7 @@
 export interface ComponentMeta {
     /** Folder under src/components, and the exported component name */
     name: string;
-    /** Display name — may differ from `name` (Nav → "Navigation") */
+    /** Display name — may differ from `name` (NavList → "Nav list") */
     label: string;
     /** Website route segment under /components */
     slug: string;
@@ -41,10 +45,22 @@ export interface ComponentMeta {
     category: string;
     /** Whether the component declares 'use client' */
     client: boolean;
+    /** Folder under src/components when it differs from `name` (shared folders like Chart) */
+    folder?: string;
+}
+export interface ComponentCategoryMeta {
+    /** Category id — the value each component's `category` field carries, and the website route segment under /components */
+    id: string;
+    /** Display name for the category, used for section headings and landing pages */
+    label: string;
+    /** One-line summary of what the category holds */
+    description: string;
 }
 /** Full metadata for every public component, alphabetical by name. */
 export declare const componentMetadata: readonly ComponentMeta[];
-/** The categories a component may belong to. */
+/** Full metadata for every component category, alphabetical by id. */
+export declare const componentCategoryMetadata: readonly ComponentCategoryMeta[];
+/** The category ids a component may belong to. */
 export declare const componentCategories: readonly string[];
 /**
  * The official public component list, names only.

package/components/registry.js

@@ -1,11 +1,13 @@
 import registry from "./registry.json.js";
 const componentMetadata = registry.components;
-const componentCategories = registry.categories;
+const componentCategoryMetadata = registry.categories;
+const componentCategories = registry.categories.map((c) => c.id);
 const componentRegistry = registry.components.map((c) => c.name);
 const COMPONENT_COUNT = registry.components.length;
 export {
   COMPONENT_COUNT,
   componentCategories,
+  componentCategoryMetadata,
   componentMetadata,
   componentRegistry
 };