@sproutsocial/seeds-react-tree 0.3.1

package/src/TreeCombobox.tsx

@@ -0,0 +1,291 @@
+import * as React from "react";
+import styled from "styled-components";
+import { Icon } from "@sproutsocial/seeds-react-icon";
+import { focusRing } from "@sproutsocial/seeds-react-mixins";
+import { Tree, type TreeProps } from "./Tree";
+import { TreeItem } from "./TreeItem";
+import { filterTree } from "./Common/filterTree";
+import { computeTreeNavigation, treeItemDomId } from "./Common/treeNavigation";
+import type { TreeItemData } from "./Common/types";
+
+const Root = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: ${({ theme }) => theme.space[300]};
+`;
+
+const InputGroup = styled.div`
+  display: flex;
+  align-items: center;
+  gap: ${({ theme }) => theme.space[200]};
+  padding: ${({ theme }) => theme.space[200]} ${({ theme }) => theme.space[300]};
+  border-radius: ${({ theme }) => theme.radii[500]};
+  border: 1px solid ${({ theme }) => theme.colors.form.border.base};
+  background: ${({ theme }) => theme.colors.form.background.base};
+  color: ${({ theme }) => theme.colors.icon.base};
+
+  &:focus-within {
+    ${focusRing}
+  }
+`;
+
+const ComboboxInput = styled.input`
+  flex: 1;
+  border: none;
+  background: transparent;
+  outline: none;
+  font-family: ${({ theme }) => theme.fontFamily};
+  ${({ theme }) => theme.typography[300]}
+  color: ${({ theme }) => theme.colors.text.body};
+
+  &::placeholder {
+    color: ${({ theme }) => theme.colors.text.subtext};
+  }
+`;
+
+const EmptyState = styled.div`
+  padding: ${({ theme }) => theme.space[400]};
+  text-align: center;
+  color: ${({ theme }) => theme.colors.text.subtext};
+  ${({ theme }) => theme.typography[300]}
+`;
+
+const NAV_KEYS = new Set([
+  "ArrowDown",
+  "ArrowUp",
+  "ArrowLeft",
+  "ArrowRight",
+  "Home",
+  "End",
+  "Enter",
+]);
+
+export type TreeComboboxProps = Omit<
+  TreeProps,
+  | "children"
+  | "focusedId"
+  | "onFocusedIdChange"
+  | "defaultFocusedId"
+  | "manageDomFocus"
+  | "aria-label"
+  | "aria-labelledby"
+> & {
+  items: ReadonlyArray<TreeItemData>;
+  /** Placeholder for the combobox input. */
+  placeholder?: string;
+  /** Text shown when the query has no matches. */
+  emptyText?: string;
+  /** Accessible name for the combobox. One of `aria-label` / `aria-labelledby` is required. */
+  "aria-label"?: string;
+  "aria-labelledby"?: string;
+  /** Controlled query value. */
+  query?: string;
+  /** Uncontrolled initial query. */
+  defaultQuery?: string;
+  onQueryChange?: (query: string) => void;
+};
+
+/**
+ * Combobox + tree pattern. Implements the WAI-ARIA combobox pattern with a
+ * tree as the popup (`aria-haspopup="tree"`). DOM focus stays on the input;
+ * `aria-activedescendant` points at the active treeitem, which the input's
+ * arrow-key handler moves through the visible tree. Selection and expansion
+ * reuse the underlying Tree's logic — Enter on the input synthesizes a click
+ * on the active row, ArrowRight/Left compute the new expanded set and pass
+ * it through Tree's controlled `expanded` prop.
+ */
+export function TreeCombobox(props: TreeComboboxProps) {
+  const {
+    items,
+    placeholder = "Search...",
+    emptyText = "No results found.",
+    query: queryProp,
+    defaultQuery = "",
+    onQueryChange,
+    selectionMode = "none",
+    selectableNodes = "all",
+    defaultExpanded,
+    expanded: expandedProp,
+    onExpandedChange,
+    defaultSelected,
+    selected: selectedProp,
+    onSelectionChange,
+    renderSelectionIndicator,
+    id,
+    className,
+  } = props;
+  const ariaLabel = props["aria-label"];
+  const ariaLabelledBy = props["aria-labelledby"];
+
+  const [uncontrolledQuery, setUncontrolledQuery] =
+    React.useState(defaultQuery);
+  const query = queryProp ?? uncontrolledQuery;
+  const setQuery = (next: string) => {
+    if (queryProp === undefined) setUncontrolledQuery(next);
+    onQueryChange?.(next);
+  };
+
+  // Track the user's last "real" expansion state so it can be restored when
+  // the query clears, matching the prior SearchableTree behavior.
+  const [userExpanded, setUserExpanded] = React.useState<string[]>(() => [
+    ...(defaultExpanded ?? expandedProp ?? []),
+  ]);
+
+  const { items: visibleItems, forceExpanded } = React.useMemo(
+    () => filterTree([...items], query),
+    [items, query]
+  );
+
+  const isFiltering = query.trim().length > 0;
+  const effectiveExpanded = isFiltering
+    ? Array.from(new Set([...userExpanded, ...forceExpanded]))
+    : expandedProp ?? userExpanded;
+
+  const handleExpandedChange = (next: string[]) => {
+    if (!isFiltering) {
+      setUserExpanded(next);
+    }
+    onExpandedChange?.(next);
+  };
+
+  const [focusedId, setFocusedId] = React.useState<string | null>(null);
+
+  const treeRef = React.useRef<HTMLUListElement>(null);
+  const reactId = React.useId();
+  const treeDomId = id ? `${id}-tree` : `${reactId}-tree`;
+
+  const findTreeItemEl = (itemId: string): HTMLElement | null =>
+    treeRef.current?.querySelector<HTMLElement>(
+      `[role="treeitem"][data-treeitem-id="${CSS.escape(itemId)}"]`
+    ) ?? null;
+
+  const handleInputKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === "Escape") {
+      if (query.length > 0) {
+        e.preventDefault();
+        setQuery("");
+        setFocusedId(null);
+      }
+      return;
+    }
+    if (!NAV_KEYS.has(e.key)) return;
+
+    const currentEl = focusedId ? findTreeItemEl(focusedId) : null;
+    const meta =
+      currentEl && focusedId
+        ? {
+            id: focusedId,
+            hasChildren: currentEl.getAttribute("aria-expanded") !== null,
+            isExpanded: currentEl.getAttribute("aria-expanded") === "true",
+            level: parseInt(currentEl.getAttribute("aria-level") ?? "1", 10),
+          }
+        : null;
+
+    // Enter: replay a row click on the active treeitem so we get TreeItem's
+    // exact selection/expansion semantics (single vs multi, leaves-only,
+    // branch-vs-leaf) for free.
+    if (e.key === "Enter") {
+      if (!currentEl) return;
+      e.preventDefault();
+      const row = currentEl.querySelector<HTMLElement>("[data-treeitem-row]");
+      row?.click();
+      return;
+    }
+
+    const result = computeTreeNavigation(
+      treeRef.current,
+      currentEl,
+      e.key,
+      meta
+    );
+    if (result.preventDefault) e.preventDefault();
+
+    if (result.expandToggle) {
+      const current = new Set(effectiveExpanded);
+      const willOpen =
+        result.expandToggle.next ?? !current.has(result.expandToggle.id);
+      if (willOpen) current.add(result.expandToggle.id);
+      else current.delete(result.expandToggle.id);
+      handleExpandedChange(Array.from(current));
+    }
+    if (result.nextFocusedId) {
+      setFocusedId(result.nextFocusedId);
+    }
+  };
+
+  // If a filter change drops the active item out of the visible set, the
+  // Tree's recovery layout-effect rebases focusedId via onFocusedIdChange.
+  // We accept that and don't reset focusedId on filter ourselves — clearing
+  // happens explicitly on Escape.
+
+  const showEmpty = visibleItems.length === 0;
+
+  return (
+    <Root className={className}>
+      <InputGroup>
+        <Icon name="magnifying-glass-outline" size="small" aria-hidden />
+        <ComboboxInput
+          type="text"
+          role="combobox"
+          id={id}
+          aria-label={ariaLabel}
+          aria-labelledby={ariaLabelledBy}
+          aria-expanded={!showEmpty}
+          aria-controls={treeDomId}
+          aria-haspopup="tree"
+          aria-autocomplete="list"
+          aria-activedescendant={
+            focusedId ? treeItemDomId(focusedId) : undefined
+          }
+          placeholder={placeholder}
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          onKeyDown={handleInputKeyDown}
+        />
+      </InputGroup>
+
+      <Tree
+        ref={treeRef}
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
+        id={treeDomId}
+        manageDomFocus={false}
+        selectionMode={selectionMode}
+        selectableNodes={selectableNodes}
+        expanded={effectiveExpanded}
+        onExpandedChange={handleExpandedChange}
+        selected={selectedProp}
+        defaultSelected={defaultSelected}
+        onSelectionChange={onSelectionChange}
+        renderSelectionIndicator={renderSelectionIndicator}
+        focusedId={focusedId}
+        onFocusedIdChange={setFocusedId}
+      >
+        {visibleItems.map((item) => (
+          <TreeNode key={item.id} item={item} />
+        ))}
+      </Tree>
+
+      {showEmpty ? (
+        <EmptyState role="status" aria-live="polite">
+          {emptyText}
+        </EmptyState>
+      ) : null}
+    </Root>
+  );
+}
+
+function TreeNode({ item }: { item: TreeItemData }) {
+  return (
+    <TreeItem
+      id={item.id}
+      label={item.label}
+      icon={item.icon}
+      disabled={item.disabled}
+    >
+      {item.children?.map((child) => (
+        <TreeNode key={child.id} item={child} />
+      ))}
+    </TreeItem>
+  );
+}

package/src/TreeItem.tsx

@@ -0,0 +1,218 @@
+import * as React from "react";
+import { Icon } from "@sproutsocial/seeds-react-icon";
+import { TreeItemContext, useTreeContext } from "./Common/treeContext";
+import { useTreeKeyboard } from "./Common/useTreeKeyboard";
+import { treeItemDomId } from "./Common/treeNavigation";
+import {
+  TreeItemChevron,
+  TreeItemEl,
+  TreeItemGroup,
+  TreeItemIcon,
+  TreeItemLabel,
+  TreeItemRow,
+} from "./TreeStyles";
+
+export type TreeItemProps = {
+  id: string;
+  label: React.ReactNode;
+  icon?: React.ReactNode;
+  disabled?: boolean;
+  children?: React.ReactNode;
+  /**
+   * Optional override for the row click target. When provided, this is used
+   * as the accessible name for the row (otherwise the rendered `label` is).
+   */
+  "aria-label"?: string;
+};
+
+function hasTreeItemChildren(children: React.ReactNode): boolean {
+  let found = false;
+  React.Children.forEach(children, (child) => {
+    if (found) return;
+    if (!React.isValidElement(child)) return;
+    const childType = child.type;
+    if (childType === React.Fragment) {
+      found = hasTreeItemChildren(
+        (child as React.ReactElement<{ children?: React.ReactNode }>).props
+          .children
+      );
+      return;
+    }
+    // Any other element child counts as a tree item. Consumers should only
+    // place TreeItems (or components that render one) inside a TreeItem.
+    found = true;
+  });
+  return found;
+}
+
+export function TreeItem(props: TreeItemProps) {
+  const { id, label, icon, disabled = false, children } = props;
+  const ctx = useTreeContext();
+  const { level } = React.useContext(TreeItemContext);
+
+  const hasChildren = React.useMemo(
+    () => hasTreeItemChildren(children),
+    [children]
+  );
+
+  const isExpanded = ctx.expanded.has(id);
+  const isSelected = ctx.selected.has(id);
+  const selectionMode = ctx.selectionMode;
+
+  // Roving tabindex: this item is tabbable when it's the focused id. When the
+  // host (e.g. a combobox) drives focus externally, no treeitem is tabbable.
+  const itemRef = React.useRef<HTMLLIElement>(null);
+  const isTabbable = ctx.manageDomFocus && ctx.focusedId === id;
+
+  // On first mount of the very first item, register ourselves as the initial
+  // roving target if nothing else has claimed it. Skipped when the host owns
+  // focus — the host decides when (if ever) to set an initial active id.
+  React.useEffect(() => {
+    if (!ctx.manageDomFocus) return;
+    if (ctx.focusedId !== null) return;
+    const root = ctx.rootRef.current;
+    if (!root) return;
+    const first = root.querySelector<HTMLElement>('[role="treeitem"]');
+    if (first === itemRef.current) {
+      ctx.setFocusedId(id);
+    }
+    // We only want this on mount; deps intentionally minimal.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const handleKeyDown = useTreeKeyboard(ctx);
+
+  const handleRowClick = (e: React.MouseEvent) => {
+    if (disabled) return;
+    // Ignore clicks that originated on the chevron — it owns its own handler.
+    const target = e.target as HTMLElement;
+    if (target.closest("[data-tree-chevron]")) return;
+
+    ctx.setFocusedId(id);
+    if (ctx.manageDomFocus) itemRef.current?.focus();
+
+    if (hasChildren && selectionMode === "none") {
+      ctx.toggleExpanded(id);
+      return;
+    }
+    if (hasChildren && ctx.selectableNodes === "leaves") {
+      ctx.toggleExpanded(id);
+      return;
+    }
+    if (selectionMode !== "none") {
+      ctx.toggleSelected(id, hasChildren);
+    }
+  };
+
+  const handleChevronClick = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    if (disabled) return;
+    ctx.setFocusedId(id);
+    if (ctx.manageDomFocus) itemRef.current?.focus();
+    ctx.toggleExpanded(id);
+  };
+
+  const ariaSelected =
+    selectionMode === "single" && ctx.selectableNodes !== "leaves"
+      ? isSelected
+      : undefined;
+  const ariaChecked =
+    selectionMode === "multiple"
+      ? isSelected
+      : selectionMode === "single" && ctx.selectableNodes === "leaves"
+      ? isSelected
+      : undefined;
+
+  const groupId = `${id}__group`;
+  const labelId = `${id}__label`;
+
+  return (
+    <TreeItemEl
+      ref={itemRef}
+      id={treeItemDomId(id)}
+      role="treeitem"
+      data-treeitem-id={id}
+      data-treeitem-active={
+        !ctx.manageDomFocus && ctx.focusedId === id ? true : undefined
+      }
+      aria-level={level}
+      aria-expanded={hasChildren ? isExpanded : undefined}
+      aria-selected={ariaSelected}
+      aria-checked={ariaChecked}
+      aria-disabled={disabled || undefined}
+      aria-labelledby={labelId}
+      aria-owns={hasChildren && isExpanded ? groupId : undefined}
+      tabIndex={isTabbable ? 0 : -1}
+      onKeyDown={(e) => {
+        if (!ctx.manageDomFocus) return;
+        handleKeyDown(e, {
+          id,
+          hasChildren,
+          isExpanded,
+          isDisabled: disabled,
+          level,
+        });
+      }}
+      onClick={(e) => {
+        // Branch treeitems contain descendant LIs whose row clicks bubble up.
+        // Only handle the click if it originated within this LI's own row —
+        // not within a descendant treeitem.
+        const target = e.target as HTMLElement;
+        const nearestTreeitem = target.closest('[role="treeitem"]');
+        if (nearestTreeitem !== e.currentTarget) return;
+        handleRowClick(e);
+      }}
+      onMouseDown={(e) => {
+        // In external-focus (combobox) mode, mousedown on a tabindex=-1
+        // treeitem would still steal DOM focus from the host input. Prevent
+        // it so focus stays where the host put it; onClick still fires.
+        if (!ctx.manageDomFocus) e.preventDefault();
+      }}
+      onFocus={() => {
+        if (!ctx.manageDomFocus) return;
+        if (!ctx.hasFocused) ctx.setHasFocused(true);
+        if (ctx.focusedId !== id) ctx.setFocusedId(id);
+      }}
+    >
+      <TreeItemRow
+        data-treeitem-row
+        $level={level}
+        $selected={isSelected}
+        $disabled={disabled}
+      >
+        {ctx.renderSelectionIndicator &&
+        !(ctx.selectableNodes === "leaves" && hasChildren)
+          ? ctx.renderSelectionIndicator({
+              selected: isSelected,
+              disabled,
+              selectionMode,
+            })
+          : null}
+
+        {icon != null ? <TreeItemIcon aria-hidden>{icon}</TreeItemIcon> : null}
+        <TreeItemLabel id={labelId}>{label}</TreeItemLabel>
+
+        {hasChildren ? (
+          <TreeItemChevron
+            data-tree-chevron
+            aria-hidden
+            $expanded={isExpanded}
+            onClick={handleChevronClick}
+          >
+            <Icon name="chevron-down-outline" size="small" />
+          </TreeItemChevron>
+        ) : null}
+      </TreeItemRow>
+
+      {hasChildren ? (
+        <TreeItemGroup role="group" id={groupId} hidden={!isExpanded}>
+          <TreeItemContext.Provider value={{ level: level + 1 }}>
+            {children}
+          </TreeItemContext.Provider>
+        </TreeItemGroup>
+      ) : null}
+    </TreeItemEl>
+  );
+}
+
+TreeItem.displayName = "TreeItem";

package/src/TreeStyles.tsx

@@ -0,0 +1,114 @@
+import styled, { css } from "styled-components";
+
+export const TreeRoot = styled.ul`
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  font-family: ${({ theme }) => theme.fontFamily};
+  ${({ theme }) => theme.typography[300]}
+  color: ${({ theme }) => theme.colors.text.body};
+`;
+
+export const TreeItemRow = styled.div<{
+  $level: number;
+  $selected: boolean;
+  $disabled: boolean;
+}>`
+  display: flex;
+  align-items: center;
+  gap: ${({ theme }) => theme.space[300]};
+  padding: ${({ theme }) => theme.space[300]};
+  padding-left: ${({ theme, $level }) =>
+    `calc(${theme.space[300]} + ${$level - 1} * ${theme.space[500]})`};
+  border-radius: ${({ theme }) => theme.radii[400]};
+  cursor: pointer;
+  user-select: none;
+  background: transparent;
+  transition: background-color ${({ theme }) => theme.duration.fast}
+    ${({ theme }) => theme.easing.ease_in};
+
+  &:hover {
+    background: ${({ theme }) => theme.colors.listItem.background.hover};
+  }
+
+  ${({ $selected, theme }) =>
+    $selected &&
+    css`
+      background: ${theme.colors.listItem.background.hover};
+      font-weight: ${theme.fontWeights.semibold};
+    `}
+
+  ${({ $disabled }) =>
+    $disabled &&
+    css`
+      opacity: 0.4;
+      cursor: not-allowed;
+      pointer-events: none;
+    `}
+`;
+
+export const TreeItemEl = styled.li`
+  list-style: none;
+  outline: none;
+
+  /*
+   * Tree rows stack tightly, so the standard outset Seeds focusRing bleeds
+   * into adjacent rows. Use an inset outline so the ring is drawn just inside
+   * the row's edge and never overlaps siblings or children.
+   *
+   * The same ring is drawn when [data-treeitem-active] is set so combobox
+   * hosts that drive the tree via aria-activedescendant (no real DOM focus)
+   * still get a visible "active" indicator on the row.
+   */
+  &:focus-visible > ${TreeItemRow}, &[data-treeitem-active] > ${TreeItemRow} {
+    outline: 2px solid
+      ${({ theme }) => theme.colors.button.primary.background.base};
+    outline-offset: -2px;
+  }
+`;
+
+export const TreeItemGroup = styled.ul`
+  list-style: none;
+  margin: 0;
+  padding: 0;
+`;
+
+export const TreeItemLabel = styled.span`
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+`;
+
+export const TreeItemIcon = styled.span`
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+`;
+
+export const TreeItemChevron = styled.button.attrs({
+  type: "button",
+  tabIndex: -1,
+})<{ $expanded: boolean }>`
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: ${({ theme }) => theme.space[500]};
+  height: ${({ theme }) => theme.space[500]};
+  padding: 0;
+  border: none;
+  background: transparent;
+  color: ${({ theme }) => theme.colors.icon.base};
+  cursor: pointer;
+  border-radius: ${({ theme }) => theme.radii[300]};
+  transition: transform ${({ theme }) => theme.duration.fast}
+    ${({ theme }) => theme.easing.ease_in};
+  transform: ${({ $expanded }) =>
+    $expanded ? "rotate(0deg)" : "rotate(-90deg)"};
+
+  &:hover {
+    background: ${({ theme }) => theme.colors.listItem.background.hover};
+  }
+`;