@sproutsocial/seeds-react-tree 0.3.1 → 0.4.0

package/src/Common/TreeSearchableSelectBase.tsx

@@ -0,0 +1,383 @@
+import * as React from "react";
+import styled, { css } from "styled-components";
+import { Icon } from "@sproutsocial/seeds-react-icon";
+import { focusRing } from "@sproutsocial/seeds-react-mixins";
+import { Popout } from "@sproutsocial/seeds-react-popout/v2";
+import { TreeCombobox } from "../TreeCombobox";
+import { flattenTreeItems } from "./flattenTree";
+import type {
+  TreeItemData,
+  TreeSelectableNodes,
+  TreeSelectionIndicator,
+  TreeSelectionMode,
+} from "./types";
+
+const invalidStyles = css`
+  border-color: ${({ theme }) => theme.colors.form.border.error};
+`;
+
+const Trigger = styled.button<{ $isInvalid?: boolean; $fullWidth: boolean }>`
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: ${({ theme }) => theme.space[300]};
+  padding: ${({ theme }) => theme.space[200]} ${({ theme }) => theme.space[350]};
+  min-width: 160px;
+  width: ${({ $fullWidth }) => ($fullWidth ? "100%" : "auto")};
+  border-radius: ${({ theme }) => theme.radii[500]};
+  border: 1px solid ${({ theme }) => theme.colors.form.border.base};
+  background: ${({ theme }) => theme.colors.form.background.base};
+  font-family: ${({ theme }) => theme.fontFamily};
+  font-size: ${({ theme }) => theme.typography[200].fontSize};
+  line-height: ${({ theme }) => theme.typography[200].lineHeight};
+  color: ${({ theme }) => theme.colors.text.body};
+  text-align: left;
+  cursor: default;
+  outline: none;
+  user-select: none;
+  transition: border-color ${({ theme }) => theme.duration.fast}
+      ${({ theme }) => theme.easing.ease_in},
+    box-shadow ${({ theme }) => theme.duration.fast}
+      ${({ theme }) => theme.easing.ease_in};
+
+  &:focus-visible {
+    ${focusRing}
+  }
+
+  &[aria-disabled="true"],
+  &:disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+
+  ${({ $isInvalid }) => $isInvalid && invalidStyles}
+`;
+
+const TriggerLabel = styled.span`
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+`;
+
+const PlaceholderText = styled.span`
+  color: ${({ theme }) => theme.colors.text.subtext};
+`;
+
+const Chevron = styled.span<{ $open: boolean }>`
+  display: inline-flex;
+  align-items: center;
+  color: ${({ theme }) => theme.colors.icon.base};
+  transition: transform ${({ theme }) => theme.duration.fast}
+    ${({ theme }) => theme.easing.ease_in};
+  ${({ $open }) =>
+    $open &&
+    css`
+      transform: rotate(-180deg);
+    `}
+`;
+
+/*
+ * Visually-hidden input that mirrors the combobox's selected value into a
+ * form-submittable element. Matches Base UI's pattern (used by v3
+ * SearchableSelect): the input stays in the DOM so HTML forms pick up the
+ * value, but it's removed from view and from the accessibility tree.
+ */
+const HiddenInput = styled.input`
+  clip-path: inset(50%);
+  overflow: hidden;
+  white-space: nowrap;
+  border: 0;
+  padding: 0;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  position: fixed;
+  top: 0;
+  left: 0;
+`;
+
+const PopoutContent = styled.div<{ $width?: number | string }>`
+  display: flex;
+  flex-direction: column;
+  /* Width sizes to content within bounds: at least the trigger width, never */
+  /* wider than the available viewport space. Shallow popups stay flush with */
+  /* the trigger; deeply nested trees expand horizontally as needed. */
+  min-width: var(--radix-popover-trigger-width);
+  max-width: var(--radix-popper-available-width);
+  /* Height caps at 400px (or available viewport) so a popup with many */
+  /* expanded branches scrolls vertically instead of growing off-screen. */
+  max-height: min(var(--radix-popper-available-height), 400px);
+  width: ${({ $width }) =>
+    $width === undefined
+      ? "max-content"
+      : typeof $width === "number"
+      ? `${$width}px`
+      : $width};
+`;
+
+const MAX_INLINE_LABELS = 3;
+
+export type RenderTrigger = (selected: TreeItemData[]) => React.ReactNode;
+
+type TreeSearchableSelectBaseProps = {
+  items: ReadonlyArray<TreeItemData>;
+
+  selectionMode: Exclude<TreeSelectionMode, "none">;
+  selectableNodes?: TreeSelectableNodes;
+  /** Selected ids in the underlying Tree's array form. */
+  selectedIds: ReadonlyArray<string>;
+  /** Fires with the next selected ids whenever Tree's onSelectionChange fires. */
+  onSelectedIdsChange: (ids: string[]) => void;
+
+  /** Accessible name for the trigger. Required (label or labelledby). */
+  "aria-label"?: string;
+  "aria-labelledby"?: string;
+  "aria-describedby"?: string;
+
+  /** Trigger placeholder when nothing is selected. */
+  placeholder?: string;
+  /** Search input placeholder inside the popout. */
+  searchPlaceholder?: string;
+  /** Empty-state text shown inside the popout when the query has no matches. */
+  emptyText?: string;
+
+  /** Render override for the trigger label area. Receives resolved selected items. */
+  renderTrigger?: RenderTrigger;
+
+  /** Open state — controllable. */
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+
+  /** Close the popout immediately after a selection change. Single-select uses this. */
+  closeOnSelect: boolean;
+
+  disabled?: boolean;
+  isInvalid?: boolean;
+  required?: boolean;
+  readOnly?: boolean;
+  /**
+   * Name for the hidden form input. When set, the component participates in
+   * native HTML form submission. For multi-select, one `<input type="hidden">`
+   * is rendered per selected id under this name (so `formData.getAll(name)`
+   * returns every selection).
+   */
+  name?: string;
+  fullWidth?: boolean;
+
+  /**
+   * Popout content width. Defaults to the trigger's width (via Radix's
+   * `--radix-popover-trigger-width`). Pass a number (px) or any valid CSS
+   * width string to override.
+   */
+  contentWidth?: number | string;
+
+  /** Tree props passed through. */
+  renderSelectionIndicator?: TreeSelectionIndicator;
+  defaultExpanded?: ReadonlyArray<string>;
+  expanded?: ReadonlyArray<string>;
+  onExpandedChange?: (expanded: string[]) => void;
+
+  id?: string;
+  className?: string;
+};
+
+function defaultRenderTrigger(
+  selected: TreeItemData[],
+  placeholder: string
+): React.ReactNode {
+  if (selected.length === 0) {
+    return <PlaceholderText>{placeholder}</PlaceholderText>;
+  }
+  if (selected.length <= MAX_INLINE_LABELS) {
+    return selected.map((s) => s.label).join(", ");
+  }
+  return `${selected.length} selected`;
+}
+
+export function TreeSearchableSelectBase(props: TreeSearchableSelectBaseProps) {
+  const {
+    items,
+    selectionMode,
+    selectableNodes,
+    selectedIds,
+    onSelectedIdsChange,
+    placeholder = "Select...",
+    searchPlaceholder = "Search...",
+    emptyText = "No results found.",
+    renderTrigger,
+    open: openProp,
+    defaultOpen = false,
+    onOpenChange,
+    closeOnSelect,
+    disabled,
+    isInvalid,
+    required,
+    readOnly,
+    name,
+    fullWidth = true,
+    contentWidth,
+    renderSelectionIndicator,
+    defaultExpanded,
+    expanded,
+    onExpandedChange,
+    id,
+    className,
+  } = props;
+  const ariaLabel = props["aria-label"];
+  const ariaLabelledBy = props["aria-labelledby"];
+  const ariaDescribedBy = props["aria-describedby"];
+
+  const isOpenControlled = openProp !== undefined;
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen);
+  const open = isOpenControlled ? !!openProp : uncontrolledOpen;
+  const setOpen = (next: boolean) => {
+    if (!isOpenControlled) setUncontrolledOpen(next);
+    onOpenChange?.(next);
+  };
+
+  // Persist the search query across open/close so users don't lose their
+  // place after picking a multi-select item.
+  const [query, setQuery] = React.useState("");
+
+  // Stable id for the popup so the trigger's `aria-controls` resolves to a
+  // real DOM element when open. Colons from React.useId() get stripped — axe
+  // rejects them inside aria-* attribute values.
+  const reactId = React.useId();
+  const popupId = `tree-select-popup-${reactId.replace(/:/g, "")}`;
+
+  // Resolve selected ids to data once per change.
+  const flat = React.useMemo(() => flattenTreeItems(items), [items]);
+  const selectedItems = React.useMemo(() => {
+    const order = new Map(flat.map((it, i) => [it.id, i] as const));
+    return selectedIds
+      .map((id) => flat.find((it) => it.id === id))
+      .filter((it): it is TreeItemData => it != null)
+      .sort((a, b) => (order.get(a.id) ?? 0) - (order.get(b.id) ?? 0));
+  }, [flat, selectedIds]);
+
+  const handleSelectionChange = (next: string[]) => {
+    onSelectedIdsChange(next);
+    if (closeOnSelect) {
+      setOpen(false);
+    }
+  };
+
+  const triggerContent = renderTrigger
+    ? renderTrigger(selectedItems)
+    : defaultRenderTrigger(selectedItems, placeholder);
+
+  // Hidden input mirrors Base UI's pattern (see v3 SearchableSelect):
+  //   - Single-select: the primary input carries the value + name, so the
+  //     form picks it up like any text input.
+  //   - Multi-select: the primary input has no name (doesn't submit) and a
+  //     `<input type="hidden">` is rendered per selected id so
+  //     `formData.getAll(name)` returns every selection.
+  // When no `name` is provided, only an id-based primary input is rendered
+  // so the `FormField → input` association keeps working.
+  const isMulti = selectionMode === "multiple";
+  const primaryInputName = isMulti ? undefined : name;
+  const primaryInputId =
+    id && primaryInputName == null ? `${id}-hidden-input` : undefined;
+
+  return (
+    <>
+      <HiddenInput
+        type="text"
+        id={primaryInputId}
+        name={primaryInputName}
+        value={isMulti ? "" : selectedIds[0] ?? ""}
+        onChange={() => {
+          // Controlled value with no user-driven mutation — value updates come
+          // from the combobox's onSelectedIdsChange path, not from the input.
+        }}
+        disabled={disabled}
+        required={required && !isMulti}
+        readOnly={readOnly}
+        tabIndex={-1}
+        aria-hidden="true"
+      />
+      {isMulti && name
+        ? selectedIds.map((selectedId) => (
+            <input
+              key={selectedId}
+              type="hidden"
+              name={name}
+              value={selectedId}
+            />
+          ))
+        : null}
+      <Popout
+        open={open}
+        onOpenChange={setOpen}
+        side="bottom"
+        align="start"
+        // Popout v2's default has padding: space[400] around its content. Our
+        // inner sections (search header + tree list) own their padding, so we
+        // strip the outer padding here to match the v3 SearchableSelect popup.
+        style={{ padding: 0 }}
+        onEscapeKeyDown={(event) => {
+          // When the user has a query typed, the first Escape should clear the
+          // query (handled inside TreeCombobox) and leave the popout open.
+          // The second Escape (with empty query) closes it.
+          if (query.length > 0) {
+            event.preventDefault();
+          }
+        }}
+        content={
+          <PopoutContent id={popupId} $width={contentWidth}>
+            <TreeCombobox
+              /*
+               * The wrapper's `aria-label` / `aria-labelledby` already names the
+               * outer trigger combobox. Giving the inner search input the same
+               * name produces two `role="combobox"` elements with identical
+               * accessible names — confusing for AT and ambiguous for tests.
+               * The inner input is the "search-within-the-popup" control, so
+               * give it a distinct, generic label.
+               */
+              aria-label="Search"
+              items={items}
+              placeholder={searchPlaceholder}
+              emptyText={emptyText}
+              query={query}
+              onQueryChange={setQuery}
+              selectionMode={selectionMode}
+              selectableNodes={selectableNodes}
+              selected={selectedIds}
+              onSelectionChange={handleSelectionChange}
+              renderSelectionIndicator={renderSelectionIndicator}
+              defaultExpanded={defaultExpanded}
+              expanded={expanded}
+              onExpandedChange={onExpandedChange}
+            />
+          </PopoutContent>
+        }
+      >
+        <Trigger
+          type="button"
+          id={id}
+          className={className}
+          $isInvalid={isInvalid}
+          $fullWidth={fullWidth}
+          disabled={disabled}
+          role="combobox"
+          aria-haspopup="dialog"
+          aria-expanded={open}
+          aria-controls={open ? popupId : undefined}
+          aria-label={ariaLabel}
+          aria-labelledby={ariaLabelledBy}
+          aria-describedby={ariaDescribedBy}
+          aria-invalid={isInvalid || undefined}
+          aria-required={required || undefined}
+        >
+          <TriggerLabel>{triggerContent}</TriggerLabel>
+          <Chevron $open={open} aria-hidden>
+            <Icon name="chevron-down-outline" size="small" />
+          </Chevron>
+        </Trigger>
+      </Popout>
+    </>
+  );
+}

package/src/Common/flattenTree.ts

@@ -0,0 +1,22 @@
+import type { TreeItemData } from "./types";
+
+/**
+ * Walk a tree depth-first and return every item in a flat array, preserving
+ * the original visit order.
+ *
+ * Used by `TreeSearchableSelect` wrappers to resolve selected ids back to
+ * their `TreeItemData` for rendering trigger labels.
+ */
+export function flattenTreeItems(
+  items: ReadonlyArray<TreeItemData>
+): TreeItemData[] {
+  const out: TreeItemData[] = [];
+  const walk = (nodes: ReadonlyArray<TreeItemData>) => {
+    for (const node of nodes) {
+      out.push(node);
+      if (node.children) walk(node.children);
+    }
+  };
+  walk(items);
+  return out;
+}

package/src/MultiTreeSearchableSelect.stories.tsx

@@ -0,0 +1,256 @@
+import React from "react";
+import styled from "styled-components";
+import type { Meta, StoryObj } from "@storybook/react";
+import { MultiTreeSearchableSelect } from "./MultiTreeSearchableSelect";
+import {
+  collections,
+  fileTree,
+  pokedex,
+  checkboxIndicator,
+  SelectionReadout,
+} from "./storyData";
+
+const meta: Meta<typeof MultiTreeSearchableSelect> = {
+  title: "Really Under Development/Tree/MultiTreeSearchableSelect",
+  component: MultiTreeSearchableSelect,
+};
+
+export default meta;
+type Story = StoryObj<typeof MultiTreeSearchableSelect>;
+
+const Stage = styled.div`
+  padding: ${({ theme }) => theme.space[500]};
+`;
+
+const Field = styled.div`
+  width: 300px;
+`;
+
+const TwoColumn = styled.div`
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: ${({ theme }) => theme.space[500]};
+  align-items: start;
+  max-width: 640px;
+`;
+
+const FieldLabel = styled.div`
+  ${({ theme }) => theme.typography[200]}
+  font-weight: ${({ theme }) => theme.fontWeights.semibold};
+  margin-bottom: ${({ theme }) => theme.space[200]};
+`;
+
+export const Basic: Story = {
+  name: "Basic",
+  render: () => (
+    <Stage>
+      <Field>
+        <MultiTreeSearchableSelect
+          aria-label="Pick collections"
+          items={collections}
+          placeholder="Pick collections"
+          renderSelectionIndicator={checkboxIndicator}
+          defaultExpanded={["customer-care"]}
+        />
+      </Field>
+    </Stage>
+  ),
+};
+
+export const Preselected: Story = {
+  name: "Pre-selected (uncontrolled default)",
+  render: () => (
+    <Stage>
+      <Field>
+        <MultiTreeSearchableSelect
+          aria-label="Pick collections"
+          items={collections}
+          placeholder="Pick collections"
+          renderSelectionIndicator={checkboxIndicator}
+          defaultExpanded={["customer-care"]}
+          defaultSelectedItemIds={["questions", "bug-reports"]}
+        />
+      </Field>
+    </Stage>
+  ),
+};
+
+export const Controlled: Story = {
+  name: "Controlled selection",
+  render: () => {
+    const [selected, setSelected] = React.useState<string[]>([
+      "questions",
+      "bug-reports",
+    ]);
+    return (
+      <Stage>
+        <Field>
+          <MultiTreeSearchableSelect
+            aria-label="Pick collections"
+            items={collections}
+            placeholder="Pick collections"
+            renderSelectionIndicator={checkboxIndicator}
+            defaultExpanded={["customer-care"]}
+            selectedItemIds={selected}
+            onSelectedItemIdsChange={setSelected}
+          />
+          <SelectionReadout selected={selected} />
+        </Field>
+      </Stage>
+    );
+  },
+};
+
+export const ManySelectionsCollapsesToCount: Story = {
+  name: "Many selections (N selected)",
+  render: () => {
+    const [selected, setSelected] = React.useState<string[]>([
+      "questions",
+      "bug-reports",
+      "feature-requests",
+      "complaints",
+    ]);
+    return (
+      <Stage>
+        <Field>
+          <MultiTreeSearchableSelect
+            aria-label="Pick collections"
+            items={collections}
+            placeholder="Pick collections"
+            renderSelectionIndicator={checkboxIndicator}
+            defaultExpanded={["customer-care"]}
+            selectedItemIds={selected}
+            onSelectedItemIdsChange={setSelected}
+          />
+          <SelectionReadout selected={selected} />
+        </Field>
+      </Stage>
+    );
+  },
+};
+
+export const LeavesOnly: Story = {
+  name: "Leaves-only selection",
+  render: () => (
+    <Stage>
+      <Field>
+        <MultiTreeSearchableSelect
+          aria-label="Pick files"
+          items={fileTree}
+          placeholder="Pick files"
+          selectableNodes="leaves"
+          renderSelectionIndicator={checkboxIndicator}
+        />
+      </Field>
+    </Stage>
+  ),
+};
+
+export const FullWidth: Story = {
+  name: "Full width",
+  render: () => (
+    <Stage>
+      <div style={{ width: 600 }}>
+        <MultiTreeSearchableSelect
+          aria-label="Pick collections"
+          items={collections}
+          placeholder="Pick collections"
+          renderSelectionIndicator={checkboxIndicator}
+          defaultExpanded={["customer-care"]}
+          fullWidth
+        />
+      </div>
+    </Stage>
+  ),
+};
+
+export const DisabledAndInvalid: Story = {
+  name: "Disabled & invalid states",
+  render: () => (
+    <Stage>
+      <TwoColumn>
+        <div>
+          <FieldLabel>Disabled</FieldLabel>
+          <MultiTreeSearchableSelect
+            aria-label="Disabled select"
+            items={collections}
+            placeholder="Pick collections"
+            renderSelectionIndicator={checkboxIndicator}
+            disabled
+          />
+        </div>
+        <div>
+          <FieldLabel>Invalid</FieldLabel>
+          <MultiTreeSearchableSelect
+            aria-label="Invalid select"
+            items={collections}
+            placeholder="Pick collections"
+            renderSelectionIndicator={checkboxIndicator}
+            isInvalid
+          />
+        </div>
+      </TwoColumn>
+    </Stage>
+  ),
+};
+
+export const DeepTree: Story = {
+  name: "Deep tree (7 levels)",
+  render: () => {
+    const [selected, setSelected] = React.useState<string[]>([]);
+    return (
+      <Stage>
+        <Field>
+          <MultiTreeSearchableSelect
+            aria-label="Pick Pokémon"
+            items={pokedex}
+            placeholder="Pick Pokémon"
+            searchPlaceholder="Search the Pokédex..."
+            renderSelectionIndicator={checkboxIndicator}
+            defaultExpanded={[
+              "gen-1",
+              "kanto",
+              "kanto-grass",
+              "bulbasaur-line",
+            ]}
+            selectedItemIds={selected}
+            onSelectedItemIdsChange={setSelected}
+          />
+          <SelectionReadout selected={selected} />
+        </Field>
+      </Stage>
+    );
+  },
+};
+
+export const CustomRenderTrigger: Story = {
+  name: "Custom renderTrigger",
+  render: () => {
+    const [selected, setSelected] = React.useState<string[]>([
+      "questions",
+      "bug-reports",
+    ]);
+    return (
+      <Stage>
+        <Field>
+          <MultiTreeSearchableSelect
+            aria-label="Pick collections"
+            items={collections}
+            placeholder="Pick collections"
+            renderSelectionIndicator={checkboxIndicator}
+            defaultExpanded={["customer-care"]}
+            selectedItemIds={selected}
+            onSelectedItemIdsChange={setSelected}
+            renderTrigger={(items) => (
+              <span>
+                <strong>{items.length}</strong>{" "}
+                {items.length === 1 ? "collection" : "collections"} picked
+              </span>
+            )}
+          />
+          <SelectionReadout selected={selected} />
+        </Field>
+      </Stage>
+    );
+  },
+};