@12-apps/ui 6.24.8 → 6.26.0

package/src/components/form/CategorySelect/CategoryPanelList.tsx

@@ -5,12 +5,8 @@ import Box from '@mui/material/Box/index.js';
 import Button from '@mui/material/Button/index.js';
 import Skeleton from '@mui/material/Skeleton/index.js';
 
-import { categoryCheckState, isLeafCategory } from './category-tree';
-import {
-  CategoryHeadRow,
-  CategorySectionHeading,
-  SubcategoryRow,
-} from './CategoryRows';
+import { categoryCheckState, isLeafCategory, leavesOf } from './category-tree';
+import { CategorySectionHeading, CategoryTreeRow } from './CategoryRows';
 import { emptySx, listSx, skeletonSx } from './CategorySelect.styles';
 import type { CategoryGroup } from './CategorySelect.types';
 
@@ -33,6 +29,12 @@ interface PanelListProps {
   loading: boolean;
   showCounts: boolean;
   allowParentSelection: boolean;
+  /**
+   * True when the tree has a level BELOW the subcategories. It turns the
+   * section-heading treatment off — see {@link CategoryNodeRows}. Derived from
+   * the options the panel state already holds, never a caller's decision.
+   */
+  deepTree: boolean;
   isExpanded: (categoryId: string) => boolean;
   onToggleExpanded: (categoryId: string) => void;
   onActivateCategory: (group: CategoryGroup) => void;
@@ -114,60 +116,66 @@ function NoResults({
   );
 }
 
-/** One group: its heading or head row, then whichever children are visible. */
-function CategoryGroupRows({
-  group,
+/**
+ * One node: its heading or its row, then whichever children are visible.
+ *
+ * The SECTION-HEADING treatment — an inert uppercase label with its children
+ * always on show — belongs to a two-level tree and only there. It is what makes
+ * the "mover para…" picker read as "category, then the subcategory you pick",
+ * and it works because a two-level category has nothing to fold TO: everything
+ * under it is already the thing you came for. A third level breaks both halves
+ * at once — the heading has no chevron, so the panel opens onto every item in
+ * the catalogue, which is the flat list this component exists to replace. So a
+ * deep tree drops the treatment and every frame becomes a foldable row instead.
+ */
+function CategoryNodeRows({
+  node,
+  depth,
   props,
 }: {
-  group: CategoryGroup;
+  node: CategoryGroup;
+  depth: number;
   props: PanelListProps;
 }): React.JSX.Element {
   const { draft, query, single, allowParentSelection, rowIds, activeIndex, sheet } = props;
-  const categoryId = group.category.id;
+  const categoryId = node.category.id;
+  const leaf = isLeafCategory(node);
   const expanded = props.isExpanded(categoryId);
   // A childless category is the leaf, so it is selectable whatever the mode says
   // — the heading reading has no subcategory to point at, and would leave the
   // row inert.
-  const selectable = allowParentSelection || isLeafCategory(group);
-  const asHeading = single && !selectable;
-  const selectedCount = group.subcategories.filter((sub) => draft.has(sub.id)).length;
+  const selectable = allowParentSelection || leaf;
+  const asHeading = single && !selectable && !props.deepTree;
+  const selectedCount = leaf ? 0 : leavesOf(node).filter((id) => draft.has(id)).length;
 
   return (
     <>
       {asHeading ? (
-        <CategorySectionHeading option={group.category} query={query} />
+        <CategorySectionHeading option={node.category} query={query} />
       ) : (
-        <CategoryHeadRow
-          option={group.category}
+        <CategoryTreeRow
+          option={node.category}
           query={query}
+          depth={depth}
+          branch={!leaf}
           expanded={expanded}
           active={rowIds[activeIndex] === categoryId}
           sheet={sheet}
-          checkState={selectable ? categoryCheckState(group, draft) : undefined}
+          {...(selectable ? { checkState: categoryCheckState(node, draft) } : {})}
           single={single}
-          expandable={!isLeafCategory(group)}
           selectedCount={selectedCount}
           showCounts={props.showCounts}
           onToggleExpanded={() => props.onToggleExpanded(categoryId)}
-          onActivate={() => props.onActivateCategory(group)}
+          onActivate={() =>
+            leaf ? props.onActivateSubcategory(categoryId) : props.onActivateCategory(node)
+          }
           dataTestId={props.dataTestId}
           copy={props.copy}
         />
       )}
       {(expanded || asHeading) &&
-        group.subcategories.map((sub) => (
-          <SubcategoryRow
-            key={sub.id}
-            option={sub}
-            query={query}
-            selected={draft.has(sub.id)}
-            active={rowIds[activeIndex] === sub.id}
-            sheet={sheet}
-            single={single}
-            showCounts={props.showCounts}
-            onActivate={() => props.onActivateSubcategory(sub.id)}
-            dataTestId={props.dataTestId}
-          />
+        node.subcategories.map((sub) => (
+          <CategoryNodeRows key={sub.category.id} node={sub} depth={depth + 1} props={props} />
         ))}
     </>
   );
@@ -200,7 +208,7 @@ export function CategoryPanelList(props: PanelListProps): React.JSX.Element {
     return (
       <>
         {groups.map((group) => (
-          <CategoryGroupRows key={group.category.id} group={group} props={props} />
+          <CategoryNodeRows key={group.category.id} node={group} depth={0} props={props} />
         ))}
       </>
     );

package/src/components/form/CategorySelect/CategoryQuickActions.tsx

@@ -5,7 +5,7 @@ import { useMemo } from 'react';
 
 import type { CategorySelectCopy } from '../../../copy';
 
-import { collectLeafIds } from './category-tree';
+import { collectBranchIds, collectLeafIds } from './category-tree';
 import type { CategorySelectState } from './useCategorySelect';
 
 /** The panel's text-button treatment. */
@@ -41,9 +41,11 @@ export function CategoryQuickActions({
 }): React.JSX.Element {
   const allLeafIds = useMemo(() => collectLeafIds(state.allGroups), [state.allGroups]);
   const everythingPicked = allLeafIds.length > 0 && state.draft.size >= allLeafIds.length;
-  const allExpanded =
-    state.allGroups.length > 0 &&
-    state.allGroups.every((group) => state.isExpanded(group.category.id));
+  // Measured over every foldable node at every depth: on a deep tree the top
+  // storey can be open while the items under it are not, and a label reading
+  // "Recolher tudo" there would be describing a state the list is not in.
+  const branchIds = useMemo(() => collectBranchIds(state.allGroups), [state.allGroups]);
+  const allExpanded = branchIds.length > 0 && branchIds.every((id) => state.isExpanded(id));
 
   return (
     <>

package/src/components/form/CategorySelect/CategoryRows.tsx

@@ -12,6 +12,7 @@ import {
   markSx,
   METRICS,
   radioSx,
+  rowIndent,
   rowMetaSx,
   rowNameSx,
   rowSx,
@@ -57,18 +58,20 @@ export function CategoryRadio({ on }: { on: boolean }): React.JSX.Element {
   return <Box sx={(theme) => radioSx(theme, on)} aria-hidden="true" />;
 }
 
-interface CategoryHeadRowProps {
+interface CategoryTreeRowProps {
   option: CategorySelectOption;
   query: string;
+  /** 0 for a top-level category; each level below indents one more step. */
+  depth: number;
+  /** True when there is something under this row to fold. */
+  branch: boolean;
   expanded: boolean;
   active: boolean;
   sheet: boolean;
-  /** Absent in leaf-only mode, where the category is a heading with no checkbox. */
+  /** Absent where the row cannot be picked — a category acting as a frame. */
   checkState?: CategoryCheckState;
   /** Single-select draws a radio for the control: choosing a row is exclusive. */
   single: boolean;
-  /** False for a childless category — there is nothing under it to disclose. */
-  expandable: boolean;
   selectedCount: number;
   showCounts: boolean;
   onToggleExpanded: () => void;
@@ -77,7 +80,7 @@ interface CategoryHeadRowProps {
   copy: CategorySelectCopy;
 }
 
-/** The trailing number: how many children are picked, else the item count. */
+/** The trailing number: how many leaves are picked below, else the item count. */
 function rowMeta(
   selectedCount: number,
   showCounts: boolean,
@@ -88,19 +91,19 @@ function rowMeta(
   return null;
 }
 
-/** The disclosure chevron, or the space it would have taken on a childless row. */
-function HeadRowDisclosure({
+/** The disclosure chevron, or the space it would have taken on a leaf row. */
+function RowDisclosure({
   option,
   expanded,
-  expandable,
+  branch,
   onToggleExpanded,
   dataTestId,
   copy,
 }: Pick<
-  CategoryHeadRowProps,
-  'option' | 'expanded' | 'expandable' | 'onToggleExpanded' | 'dataTestId' | 'copy'
+  CategoryTreeRowProps,
+  'option' | 'expanded' | 'branch' | 'onToggleExpanded' | 'dataTestId' | 'copy'
 >): React.JSX.Element {
-  if (!expandable) {
+  if (!branch) {
     return <Box sx={{ width: METRICS.chevronButton, flex: '0 0 auto' }} />;
   }
   return (
@@ -121,11 +124,11 @@ function HeadRowDisclosure({
   );
 }
 
-/** The row's selection control, or the space it would have taken on a heading. */
-function HeadRowControl({
+/** The row's selection control, or the space it would have taken on a frame. */
+function RowControl({
   checkState,
   single,
-}: Pick<CategoryHeadRowProps, 'checkState' | 'single'>): React.JSX.Element {
+}: Pick<CategoryTreeRowProps, 'checkState' | 'single'>): React.JSX.Element {
   if (!checkState) return <Box sx={{ width: METRICS.boxSize, flex: '0 0 auto' }} />;
   // Single-select commits the moment a row is chosen, so the control is a radio
   // there: a checkbox would promise the accumulation this mode does not do.
@@ -134,51 +137,63 @@ function HeadRowControl({
 }
 
 /**
- * A top-level category row: disclosure chevron, optional checkbox, name, meta.
+ * The test id a row answers to.
  *
- * The chevron is its OWN button inside the row button — clicking it only folds,
- * while clicking the row does the row's job (expand as a heading, or tick when
- * the category is selectable). A CHILDLESS category has neither a fold nor a
- * heading to be: it draws no chevron, and it carries the control, because it is
- * itself the leaf.
+ * Keyed on DEPTH rather than on whether the row has children, because that is
+ * what the ids meant when the tree was two levels and specs were written against
+ * them: `-category-<id>` is a top-level row — childless or not — and `-option-`
+ * is anything filed under one.
  */
-export function CategoryHeadRow({
+function rowTestId(dataTestId: string, depth: number, id: string): string {
+  return depth === 0 ? `${dataTestId}-category-${id}` : `${dataTestId}-option-${id}`;
+}
+
+/**
+ * One row of the tree: disclosure chevron, optional control, name, meta.
+ *
+ * The chevron is its OWN button inside the row — clicking it only folds, while
+ * clicking the row does the row's job (expand as a frame, or mark when the row
+ * is selectable). A LEAF has neither a fold nor a frame to be: it draws no
+ * chevron, and it always carries the control, because it is what you pick.
+ */
+export function CategoryTreeRow({
   option,
   query,
+  depth,
+  branch,
   expanded,
   active,
   sheet,
   checkState,
   single,
-  expandable,
   selectedCount,
   showCounts,
   onToggleExpanded,
   onActivate,
   dataTestId,
   copy,
-}: CategoryHeadRowProps): React.JSX.Element {
+}: CategoryTreeRowProps): React.JSX.Element {
   const meta = rowMeta(selectedCount, showCounts, option.count);
   return (
     <Box
       component="div"
       role={checkState ? 'option' : 'button'}
       aria-selected={checkState ? checkState === 'on' : undefined}
-      aria-expanded={expandable ? expanded : undefined}
-      data-testid={`${dataTestId}-category-${option.id}`}
-      sx={(theme) => rowSx(theme, active, sheet)}
+      aria-expanded={branch ? expanded : undefined}
+      data-testid={rowTestId(dataTestId, depth, option.id)}
+      sx={(theme) => ({ ...rowSx(theme, active, sheet), ...rowIndent(depth) })}
       onClick={onActivate}
     >
-      <HeadRowDisclosure
+      <RowDisclosure
         option={option}
         expanded={expanded}
-        expandable={expandable}
+        branch={branch}
         onToggleExpanded={onToggleExpanded}
         dataTestId={dataTestId}
         copy={copy}
       />
-      <HeadRowControl checkState={checkState} single={single} />
-      <Box component="span" sx={(theme) => rowNameSx(theme, true)}>
+      <RowControl checkState={checkState} single={single} />
+      <Box component="span" sx={(theme) => rowNameSx(theme, depth === 0)}>
         <HighlightedName text={option.name} query={query} />
       </Box>
       {meta && (
@@ -190,57 +205,6 @@ export function CategoryHeadRow({
   );
 }
 
-interface SubcategoryRowProps {
-  option: CategorySelectOption;
-  query: string;
-  selected: boolean;
-  active: boolean;
-  sheet: boolean;
-  /** Single-select mode draws a radio; multi-select draws a checkbox. */
-  single: boolean;
-  showCounts: boolean;
-  onActivate: () => void;
-  dataTestId: string;
-}
-
-export function SubcategoryRow({
-  option,
-  query,
-  selected,
-  active,
-  sheet,
-  single,
-  showCounts,
-  onActivate,
-  dataTestId,
-}: SubcategoryRowProps): React.JSX.Element {
-  return (
-    <Box
-      component="div"
-      role="option"
-      aria-selected={selected}
-      data-testid={`${dataTestId}-option-${option.id}`}
-      sx={(theme) => ({ ...rowSx(theme, active, sheet), paddingLeft: '14px' })}
-      onClick={onActivate}
-    >
-      <Box sx={{ width: METRICS.chevronButton, flex: '0 0 auto' }} />
-      {single ? (
-        <CategoryRadio on={selected} />
-      ) : (
-        <CategoryCheckbox state={selected ? 'on' : 'off'} />
-      )}
-      <Box component="span" sx={(theme) => rowNameSx(theme, false)}>
-        <HighlightedName text={option.name} query={query} />
-      </Box>
-      {showCounts && option.count !== undefined && (
-        <Box component="span" sx={(theme) => rowMetaSx(theme, false)}>
-          {option.count}
-        </Box>
-      )}
-    </Box>
-  );
-}
-
 /** The category as a non-interactive heading (single-select, leaf-only). */
 export function CategorySectionHeading({
   option,

package/src/components/form/CategorySelect/CategorySelect.md

@@ -1,7 +1,7 @@
 # CategorySelect
 
-A hierarchical category picker: **categories are the frame, subcategories are what
-you pick.**
+A hierarchical picker: **the categories are the frame, whatever is filed at the
+bottom is what you pick.** Two levels by default; as many as the payload has.
 
 ```tsx
 import { CategorySelect } from '@12-apps/ui/form/CategorySelect';
@@ -33,7 +33,32 @@ Never pre-indent `name` (`"— Águas"`). The row draws the nesting; a baked-in
 travels everywhere the label goes, including the closed trigger.
 
 An option whose `parentId` matches nothing is promoted to top level rather than
-dropped, so a partial payload never makes a category invisible.
+dropped, so a partial payload never makes a category invisible. So is an option
+on a `parentId` RING — two rows naming each other would otherwise build a loop
+every walk of the tree follows until the stack gives out.
+
+### Depth
+
+**Nothing caps it at two.** Point a `parentId` at a subcategory and you get a
+third storey; the row indents one more step, folds, searches and reports its
+path like every level above it.
+
+```tsx
+const options = [
+  { id: 'beb', name: 'Bebidas' },
+  { id: 'beb.refri', name: 'Refrigerantes', parentId: 'beb' },
+  { id: 'p.coca', name: 'Coca-Cola', parentId: 'beb.refri' }, // an ITEM
+];
+```
+
+Two things follow from a deeper tree, and both are the component's own doing:
+
+- **A category stands for the leaves at the BOTTOM of it**, never for the
+  subcategories in between. `Bebidas` ticked means every drink under every one of
+  its subcategories, so the value a caller receives is uniformly leaves.
+- **The section-heading treatment switches off** (see below), because a heading
+  has no chevron and a three-level tree drawn flat is the list this component is
+  adopted to replace.
 
 ## Which rows are selectable
 
@@ -42,14 +67,14 @@ parent that HAS children can be ticked in its own right.
 
 | `allowParentSelection` | has children | the row |
 | --- | --- | --- |
-| `false` (default) | yes | a **heading** — no control; its subcategories are what you tick |
+| `false` (default) | yes | a **frame** — no control; what is filed under it is what you tick |
 | `false` | no | **selectable** — it is itself the leaf |
-| `true` | yes | **selectable** — ticking it selects **every subcategory under it** |
+| `true` | yes | **selectable** — ticking it selects **every leaf under it** |
 | `true` | no | **selectable** |
 
 Two of those deserve their reasons written down.
 
-**A parent with children, flag on, selects its CHILDREN** — not an id of its own.
+**A parent with children, flag on, selects its LEAVES** — not an id of its own.
 That is what makes the value a caller receives uniform: always leaves, never a
 mix of leaves and groups that every consumer would have to re-expand. The chip
 tray collapses a fully-selected category back to one chip bearing the category's
@@ -80,7 +105,8 @@ const [categories, setCategories] = useState<string[]>([]);
 ### `single` — the "move to…" picker
 
 Choosing a row commits immediately; there is nothing to batch. The trigger then
-reads `Pai › Filha`, so the chosen leaf keeps its context.
+reads the whole path — `Pai › Filha`, or `Pai › Filha › Item` on a deeper tree —
+so the chosen leaf keeps its context once the panel has closed over it.
 
 ```tsx
 <CategorySelect
@@ -94,8 +120,16 @@ reads `Pai › Filha`, so the chosen leaf keeps its context.
 
 ## Behaviour worth knowing
 
-- **Opens fully expanded.** Nothing a search could match hides behind a
-  disclosure.
+- **Opens with the top level unfolded.** On a two-level tree that is everything.
+  On a deeper one the items stay one click away, which is the whole point of
+  filing them under something. A **search reveals every hit regardless** — folded
+  or not — and clearing it restores exactly what you had folded.
+- **A frame you cannot tick is still a foldable ROW in a deep tree.** In a
+  two-level tree, single-select draws it as an inert uppercase heading with its
+  subcategories always on show: there is nothing to fold to, since everything
+  under it is already the thing you came for. Add a third level and that reading
+  breaks twice over — the heading has no chevron, so the panel opens onto the
+  whole catalogue — so the treatment is dropped and every frame gets a chevron.
 - **Selected categories pin above the list.** They survive scrolling and
   searching — a tick made at the bottom of a ten-category tree does not vanish
   the moment you look for the next one.
@@ -112,9 +146,9 @@ reads `Pai › Filha`, so the chosen leaf keeps its context.
 | Key | Does |
 | --- | --- |
 | `↑` `↓` | Move the cursor |
-| `→` | Expand the category |
-| `←` | Collapse it, or jump from a subcategory to its parent |
-| `Space` | Mark the row (single-select: pick it) — a heading category expands |
+| `→` | Expand the row, at any depth |
+| `←` | Collapse it, or jump from a leaf to its parent |
+| `Space` | Mark the row (single-select: pick it) — a frame expands instead |
 | `Enter` | Apply (single-select: pick, and expand on a heading, as `Space` does) |
 | `Esc` | Cancel, returning focus to the trigger |
 
@@ -126,7 +160,7 @@ the field.
 ## Styling
 
 Geometry is the design's absolute pixels — 38px trigger, 340px panel, 36px rows,
-1.5px checkbox borders. Those are deliberately not derived from `theme.spacing`,
+14px of indent per level, 1.5px checkbox borders. Those are deliberately not derived from `theme.spacing`,
 which is an 8px grid and would round the design away.
 
 **Colours come from the theme.** A tenant can white-label the palette, and the

package/src/components/form/CategorySelect/CategorySelect.styles.ts

@@ -28,6 +28,8 @@ export const METRICS = {
   rowRadius: 8,
   boxSize: 18,
   chevronButton: 22,
+  /** Extra left padding per level of nesting. */
+  rowIndentStep: 14,
   footerButton: 32,
   sheetFooterButton: 38,
   /** Below this width the panel becomes a bottom sheet. */
@@ -239,6 +241,17 @@ export const rowSx = (theme: Theme, active: boolean, sheet: boolean): CSSObject
   '&:focus-visible': { outline: `2px solid ${theme.palette.primary.main}`, outlineOffset: 1 },
 });
 
+/**
+ * How far a row sits in from the panel edge, by depth.
+ *
+ * One step per level, on top of {@link rowSx}'s own 8px gutter — depth 0 keeps
+ * that gutter, and every level below it adds `METRICS.rowIndentStep`. Absolute
+ * like the rest of this file: the step is the design's own 14px, not a spacing
+ * multiple that would round it.
+ */
+export const rowIndent = (depth: number): CSSObject =>
+  depth === 0 ? {} : { paddingLeft: `${depth * METRICS.rowIndentStep}px` };
+
 export const rowNameSx = (theme: Theme, isCategory: boolean): CSSObject => ({
   flex: 1,
   minWidth: 0,

package/src/components/form/CategorySelect/CategorySelect.tsx

@@ -4,7 +4,7 @@ import { useEffect, useMemo, useRef } from 'react';
 import { useTheme } from '@mui/material/styles/index.js';
 import useMediaQuery from '@mui/material/useMediaQuery/index.js';
 
-import { summarizeSelection } from './category-tree';
+import { categoryPath, summarizeSelection } from './category-tree';
 import { CategoryPanel } from './CategoryPanel';
 import { CategoryPanelSurface } from './CategoryPanelSurface';
 import { CategoryTrigger } from './CategoryTrigger';
@@ -26,14 +26,13 @@ function draftChanged(draft: ReadonlySet<string>, applied: readonly string[]): b
   return draft.size !== applied.length || applied.some((id) => !draft.has(id));
 }
 
-/** "Pai › Filha" for a chosen id, so the trigger carries its context. */
+/**
+ * "Pai › Filha" for a chosen id, so the trigger carries its context once the
+ * panel has closed over it. The whole path, at whatever depth the row sits.
+ */
 function singleLabel(groups: CategoryGroup[], value: string | null): string | undefined {
   if (!value) return undefined;
-  const asCategory = groups.find((group) => group.category.id === value);
-  if (asCategory) return asCategory.category.name;
-  const owner = groups.find((group) => group.subcategories.some((sub) => sub.id === value));
-  const sub = owner?.subcategories.find((candidate) => candidate.id === value);
-  return sub && owner ? `${owner.category.name} › ${sub.name}` : undefined;
+  return categoryPath(groups, value)?.join(' › ');
 }
 
 /** The optional props, resolved once so the component body stays branch-free. */
@@ -85,19 +84,22 @@ function usePanelFocus(
 }
 
 /**
- * A hierarchical category picker: categories as the frame, subcategories as the
- * thing you choose.
+ * A hierarchical category picker: categories as the frame, whatever is filed
+ * under them as the thing you choose.
  *
  * Two modes off one component. `multi` is the FILTER — ticks accumulate in a
  * draft and reach `onChange` only on Apply, so the list behind the panel does not
  * reload on every click. `single` is the "move to…" picker, where choosing a row
  * commits immediately because there is nothing to batch.
  *
- * The tree opens fully expanded: nothing a search could match is hidden behind a
- * disclosure. Selected categories pin above the list so they survive scrolling
- * and searching, search is accent-insensitive (`agua` finds `Águas`), and the
- * whole tree is keyboard-drivable — ↑↓ to move, → to open, ← to close, Space to
- * mark, Enter to apply, Esc to cancel.
+ * The tree nests as deep as the payload does — a picker can file ITEMS under a
+ * subcategory and get a third storey with no extra configuration. Opening
+ * unfolds the top level, and a search reveals every hit whatever is folded.
+ *
+ * Selected categories pin above the list so they survive scrolling and
+ * searching, search is accent-insensitive (`agua` finds `Águas`), and the whole
+ * tree is keyboard-drivable — ↑↓ to move, → to open, ← to close, Space to mark,
+ * Enter to apply, Esc to cancel.
  *
  * Under {@link METRICS.sheetBreakpoint} the panel becomes a bottom sheet, which
  * is the only way a 290px-tall list stays usable one-handed.

package/src/components/form/CategorySelect/CategorySelect.types.ts

@@ -22,10 +22,18 @@ export interface CategorySelectOption {
   count?: number;
 }
 
-/** A top-level category together with the subcategories nested under it. */
+/**
+ * One node of the category tree: an option together with whatever sits under it.
+ *
+ * Recursive rather than "a category and its flat subcategories" because the tree
+ * a caller hands over is not always two deep — a picker can file ITEMS under a
+ * subcategory, and the level below still has to nest, fold and search like the
+ * one above it. A node with an empty `subcategories` is the leaf.
+ */
 export interface CategoryGroup {
   category: CategorySelectOption;
-  subcategories: CategorySelectOption[];
+  /** The nodes directly below it, each a group in its own right. */
+  subcategories: CategoryGroup[];
 }
 
 /** One entry in the "selected" summary: a whole category, or a single leaf. */