@crewlethq/ui 0.4.4 → 0.5.0

package/dist/TagsInput/index.js

@@ -1,10 +1,10 @@
-export { TagsInput } from '../chunk-6KCO2D5C.js';
-import '../chunk-S2XHHEW4.js';
-import '../chunk-PZSWF74H.js';
-import '../chunk-KIC7BZYJ.js';
-import '../chunk-7RPGY3JE.js';
-import '../chunk-ITHXJHBB.js';
-import '../chunk-F27EPQ7D.js';
+export { TagsInput } from '../chunk-KD4H66L6.js';
+import '../chunk-74KMX7YH.js';
+import '../chunk-WIATRXEJ.js';
+import '../chunk-6MU7HNB4.js';
 import '../chunk-RSAQOKH3.js';
+import '../chunk-7RPGY3JE.js';
+import '../chunk-R25RGPUB.js';
+import '../chunk-4UQ7SMPK.js';
 import '../chunk-BZFWDIV6.js';
 import '../chunk-ODEQTPFM.js';

package/dist/ThemeSwitcher/ThemeSwitcher.d.ts

@@ -1,15 +1,46 @@
-export interface ThemeSwitcherProps {
+import { type DensityPreference, type ThemePreference } from './preferences.js';
+/**
+ * Who holds a preference: the control, or the application around it.
+ *
+ * STORED, the default: the control reads the choice kept under `storageKey`,
+ * writes the root attribute and storage when it changes, and tells `onChange`
+ * afterwards. Every stored control on one key reads one value, so two of them
+ * on a page agree.
+ *
+ * CONTROLLED, with `value`: the control draws `value`, calls `onChange` with
+ * the reader's pick and WRITES NOTHING, neither the root attribute nor
+ * storage. The application owns the preference (normally one
+ * `useThemePreference` it hands to every control that shows it), so a second
+ * writer here would be a second opinion about which theme is on. A
+ * `storageKey` has nothing to name in that mode, and the types refuse one.
+ *
+ * A control is one or the other for its whole life: the two are different
+ * components underneath, so switching remounts it.
+ */
+export type PreferenceControl<T extends string> = {
+    value?: undefined;
+    /** Told after a pick is applied and stored. */
+    onChange?: ((next: T) => void) | undefined;
     /** Where the choice is kept. */
-    storageKey?: string;
+    storageKey?: string | undefined;
+} | {
+    /** The choice to draw. The control writes nothing of its own. */
+    value: T;
+    /** The reader's pick. Nothing changes until `value` does. */
+    onChange: (next: T) => void;
+    storageKey?: undefined;
+};
+interface ThemeRowProps {
     /** Names the group. */
-    label?: string;
+    label?: string | undefined;
     /** What each choice is called out loud. The glyphs say nothing on their own. */
-    lightLabel?: string;
-    systemLabel?: string;
-    darkLabel?: string;
-    size?: 'sm' | 'md';
-    className?: string;
+    lightLabel?: string | undefined;
+    systemLabel?: string | undefined;
+    darkLabel?: string | undefined;
+    size?: 'sm' | 'md' | undefined;
+    className?: string | undefined;
 }
+export type ThemeSwitcherProps = ThemeRowProps & PreferenceControl<ThemePreference>;
 /**
  * Light, the system's, or dark.
  *
@@ -21,21 +52,21 @@ export interface ThemeSwitcherProps {
  * EACH OPTION IS A WORD, not a picture of one. The glyphs are the whole of
  * what is drawn, so without a spoken name the row is three unnamed buttons.
  */
-export declare function ThemeSwitcher({ storageKey, label, lightLabel, systemLabel, darkLabel, size, className, }: ThemeSwitcherProps): import("react").JSX.Element;
-export interface DensitySwitcherProps {
-    storageKey?: string;
-    label?: string;
+export declare function ThemeSwitcher(props: ThemeSwitcherProps): import("react").JSX.Element;
+interface DensityRowProps {
+    label?: string | undefined;
     /** What each choice is called out loud. */
-    compactLabel?: string;
-    normalLabel?: string;
-    comfortableLabel?: string;
+    compactLabel?: string | undefined;
+    normalLabel?: string | undefined;
+    comfortableLabel?: string | undefined;
     /** What each choice is drawn as. One letter, which is a picture of a size. */
-    compactMark?: string;
-    normalMark?: string;
-    comfortableMark?: string;
-    size?: 'sm' | 'md';
-    className?: string;
+    compactMark?: string | undefined;
+    normalMark?: string | undefined;
+    comfortableMark?: string | undefined;
+    size?: 'sm' | 'md' | undefined;
+    className?: string | undefined;
 }
+export type DensitySwitcherProps = DensityRowProps & PreferenceControl<DensityPreference>;
 /**
  * How much room the interface gives itself.
  *
@@ -44,4 +75,5 @@ export interface DensitySwitcherProps {
  * nothing: a reader was offered "S" and left to guess. The mark stays, and
  * each option is called Compact, Normal or Comfortable.
  */
-export declare function DensitySwitcher({ storageKey, label, compactLabel, normalLabel, comfortableLabel, compactMark, normalMark, comfortableMark, size, className, }: DensitySwitcherProps): import("react").JSX.Element;
+export declare function DensitySwitcher(props: DensitySwitcherProps): import("react").JSX.Element;
+export {};

package/dist/ThemeSwitcher/index.d.ts

@@ -1,4 +1,4 @@
 export { DensitySwitcher, ThemeSwitcher } from './ThemeSwitcher.js';
-export type { DensitySwitcherProps, ThemeSwitcherProps } from './ThemeSwitcher.js';
-export { applyDensity, applyStoredPreferences, applyTheme, useDensityPreference, useThemePreference, } from './preferences.js';
-export type { DensityPreference, PreferenceOptions, StoredPreferences, ThemePreference, } from './preferences.js';
+export type { DensitySwitcherProps, PreferenceControl, ThemeSwitcherProps } from './ThemeSwitcher.js';
+export { applyDensity, applyStoredPreferences, applyTheme, resolveTheme, useDensityPreference, useSystemTheme, useThemePreference, } from './preferences.js';
+export type { DensityPreference, PreferenceOptions, ResolvedTheme, StoredPreferences, ThemePreference, } from './preferences.js';

package/dist/ThemeSwitcher/index.js

@@ -1,6 +1,7 @@
-export { DensitySwitcher, ThemeSwitcher, applyDensity, applyStoredPreferences, applyTheme, useDensityPreference, useThemePreference } from '../chunk-R66KLW7S.js';
-import '../chunk-7PEFUMQJ.js';
-import '../chunk-Q3B66TJM.js';
+export { DensitySwitcher, ThemeSwitcher } from '../chunk-S7KW47IQ.js';
+export { applyDensity, applyStoredPreferences, applyTheme, resolveTheme, useDensityPreference, useSystemTheme, useThemePreference } from '../chunk-K3OWD7BJ.js';
+import '../chunk-DHPUMOTX.js';
+import '../chunk-QY7UU5ZB.js';
 import '../chunk-BHHIIK3M.js';
 import '../chunk-BZFWDIV6.js';
 import '../chunk-ODEQTPFM.js';

package/dist/ThemeSwitcher/preferences.d.ts

@@ -6,10 +6,13 @@ export type DensityPreference = 'normal' | 'compact' | 'comfortable';
  * Puts the theme on the root element.
  *
  * `system` REMOVES the attribute rather than writing a third value, because
- * the stylesheet's own default is the system's: a document with no attribute
- * is light, or dark where the platform asks for dark. A `data-theme="system"`
- * would match neither selector and paint the light palette on a reader who
- * asked for dark.
+ * following the system IS the absence of a choice, and the stylesheet's own
+ * default is the system's: a document with no attribute is dark, or light
+ * where the platform asks for light. What beats the system is an explicit
+ * value, in both directions: `light` by a block of its own, `dark` by keeping
+ * the light media block from matching. A `data-theme="system"` names no
+ * palette, so it would be a choice only to the code that asks whether the
+ * attribute is there at all, which is the wrong answer to give it.
  */
 export declare function applyTheme(theme: ThemePreference): void;
 /** Puts the density on the root element. `normal` removes the attribute. */
@@ -24,11 +27,22 @@ export interface PreferenceOptions {
  * WHY IT IS A HOOK RATHER THAN A CONTEXT. Nothing renders differently by
  * theme: the palette is CSS custom properties on the root, so the only state
  * is which attribute is set, and a context would make every component that
- * reads it re-render for a change none of them draw.
+ * reads it re-render for a change none of them draw. Two calls with one
+ * `storageKey` read one value, so a toggle and a row on the same page agree.
  */
 export declare function useThemePreference({ storageKey, }: PreferenceOptions): [ThemePreference, (next: ThemePreference) => void];
 /** The reader's density, kept on the root element and in storage. */
 export declare function useDensityPreference({ storageKey, }: PreferenceOptions): [DensityPreference, (next: DensityPreference) => void];
+/** The palette the root actually paints: a choice, or the system's answer. */
+export type ResolvedTheme = 'light' | 'dark';
+/**
+ * The palette the platform asks for, now and whenever it changes. A server,
+ * and a browser that cannot be asked, are answered dark, which is what the
+ * theme layer paints for them.
+ */
+export declare function useSystemTheme(): ResolvedTheme;
+/** What a preference paints on a platform that asks for `system`. */
+export declare function resolveTheme(preference: ThemePreference, system: ResolvedTheme): ResolvedTheme;
 export interface StoredPreferences {
     themeKey?: string | undefined;
     densityKey?: string | undefined;

package/dist/ThemeToggle/ThemeToggle.d.ts

@@ -0,0 +1,40 @@
+import { type IconButtonSize, type IconButtonVariant } from '../IconButton/index.js';
+import type { PreferenceControl } from '../ThemeSwitcher/ThemeSwitcher.js';
+import { type ThemePreference } from '../ThemeSwitcher/preferences.js';
+interface ToggleButtonProps {
+    /** Named for what a press does, while the page is dark. */
+    toLightLabel?: string | undefined;
+    /** Named for what a press does, while the page is light. */
+    toDarkLabel?: string | undefined;
+    /** The rail's foot wears `sm`, the quiet step beside the identity row. */
+    size?: IconButtonSize | undefined;
+    variant?: IconButtonVariant | undefined;
+    className?: string | undefined;
+}
+/**
+ * `onChange` receives `light` or `dark`, never `system`: a press is a choice.
+ * Stored (the default) or controlled by `value`, as `ThemeSwitcher` is, and a
+ * controlled toggle writes nothing of its own.
+ */
+export type ThemeToggleProps = ToggleButtonProps & PreferenceControl<ThemePreference>;
+/**
+ * One press from the palette on the screen to the other one.
+ *
+ * IT FLIPS WHAT IS PAINTED, NOT WHAT WAS CHOSEN. A reader following a dark
+ * system has the preference `system`; toggling that preference has no
+ * opposite to go to, and cycling light, system, dark would spend a press on
+ * `system`, which repaints nothing and reads as a button that did not work.
+ * So the toggle RESOLVES the preference against the platform (the query the
+ * theme layer itself answers) and writes the explicit opposite, which beats
+ * the system in both directions. Following the system again is a choice in the
+ * full `ThemeSwitcher`, which is where a settings screen offers it.
+ *
+ * NAMED FOR THE ACTION, drawn as the destination. The name changes with the
+ * palette ("Switch to the light theme" on a dark page), so a screen reader
+ * hears what a press will do, and the glyph is the palette it goes to: a sun
+ * on a dark page, a moon on a light one. It is NOT `aria-pressed`, because
+ * neither palette is the "on" state of the other, and a pressed state beside a
+ * changing name would announce the change twice in two contradicting ways.
+ */
+export declare function ThemeToggle(props: ThemeToggleProps): import("react").JSX.Element;
+export {};

package/dist/ThemeToggle/index.d.ts

@@ -0,0 +1,2 @@
+export { ThemeToggle } from './ThemeToggle.js';
+export type { ThemeToggleProps } from './ThemeToggle.js';

package/dist/ThemeToggle/index.js

@@ -0,0 +1,5 @@
+export { ThemeToggle } from '../chunk-C5WJUZVR.js';
+import '../chunk-K3OWD7BJ.js';
+import '../chunk-4UQ7SMPK.js';
+import '../chunk-BZFWDIV6.js';
+import '../chunk-ODEQTPFM.js';

package/dist/TimeWindowPicker/index.js

@@ -1,13 +1,13 @@
-export { DEFAULT_TIME_WINDOW_LABELS, TIME_WINDOW_SPANS, TimeWindowPicker, describeTimeWindow, isTimeWindowSet, parseTimeWindowDuration, resolveTimeWindow, timeWindowMatchesPreset } from '../chunk-XJWXPRSK.js';
-import '../chunk-KNYYCWMK.js';
-import '../chunk-EFSG7HNU.js';
+export { DEFAULT_TIME_WINDOW_LABELS, TIME_WINDOW_SPANS, TimeWindowPicker, describeTimeWindow, isTimeWindowSet, parseTimeWindowDuration, resolveTimeWindow, timeWindowMatchesPreset } from '../chunk-JGRNTBF2.js';
+import '../chunk-SJQ546ID.js';
+import '../chunk-AUS5FNQE.js';
 import '../chunk-GXQ3B46I.js';
-import '../chunk-KIC7BZYJ.js';
-import '../chunk-GKHAKGOF.js';
+import '../chunk-6MU7HNB4.js';
+import '../chunk-DSUY5F4E.js';
 import '../chunk-PQADV6P6.js';
 import '../chunk-7RPGY3JE.js';
-import '../chunk-ITHXJHBB.js';
-import '../chunk-F27EPQ7D.js';
-import '../chunk-BZYDZBAN.js';
+import '../chunk-R25RGPUB.js';
+import '../chunk-4UQ7SMPK.js';
+import '../chunk-ETYEBKR4.js';
 import '../chunk-BZFWDIV6.js';
 import '../chunk-ODEQTPFM.js';

package/dist/Toaster/index.js

@@ -1,5 +1,5 @@
-export { ToastProvider, Toaster, useToast } from '../chunk-NPZY6YYL.js';
+export { ToastProvider, Toaster, useToast } from '../chunk-UG5ZMAXW.js';
 import '../chunk-7RPGY3JE.js';
-import '../chunk-ITHXJHBB.js';
+import '../chunk-R25RGPUB.js';
 import '../chunk-BZFWDIV6.js';
 import '../chunk-ODEQTPFM.js';

package/dist/Toolbar/index.js

@@ -1,4 +1,4 @@
-export { Toolbar, ToolbarOverflow, ToolbarWide } from '../chunk-5EKIWVOR.js';
+export { Toolbar, ToolbarOverflow, ToolbarWide } from '../chunk-PGRPNDWM.js';
 import '../chunk-7RPGY3JE.js';
-import '../chunk-ITHXJHBB.js';
+import '../chunk-R25RGPUB.js';
 import '../chunk-ODEQTPFM.js';

package/dist/{Toolbar-IP6LXN45.css → Toolbar-HUOSMNTH.css}

@@ -37,7 +37,9 @@
   display: none;
 }
 
-@media (max-width: 900px) {
+/* Under the shell's breakpoint, strictly, as the shell switches: the wide
+   controls fold into the overflow where the rail becomes a drawer. */
+@media (width < 1024px) {
   .crewlet-toolbar__wide {
     display: none;
   }

package/dist/Tooltip/index.js

@@ -1,4 +1,4 @@
-export { Tooltip } from '../chunk-5KSRXHOW.js';
+export { Tooltip } from '../chunk-CQY5NTRS.js';
 import '../chunk-7RPGY3JE.js';
-import '../chunk-ITHXJHBB.js';
+import '../chunk-R25RGPUB.js';
 import '../chunk-ODEQTPFM.js';

package/dist/Tree/index.d.ts

@@ -1,7 +1,7 @@
 export { createTreeModel, isTypeAheadKey, treeAllExpandable, treeAncestors, treeCollapseOrAscend, treeExpandOrDescend, treeExpandTo, treeExpandable, treeFirst, treeFirstChild, treeLast, treeLevel, treeNext, treeParent, treePosInSet, treePrevious, treeSetSize, treeTypeAhead, treeVisible, typeAheadBuffer, TYPE_AHEAD_RESET_MS, } from './model.js';
 export type { TreeInput, TreeModel, TypeAheadState } from './model.js';
-export { layoutConnectors, layoutForest } from './layout.js';
-export type { ForestLayout, LayoutGaps, LayoutNode, LayoutRanks, PlacedNode, TreeConnector, TreeConnectorShape, } from './layout.js';
+export { layoutConnectors, layoutForest, placeGroups } from './layout.js';
+export type { ForestLayout, LayoutGaps, LayoutGroup, LayoutGroupInset, LayoutNode, LayoutRanks, PlacedGroup, PlacedNode, TreeConnector, TreeConnectorShape, } from './layout.js';
 export { treeItemAction, treeStep, useTreeState } from './useTreeState.js';
 export type { TreeItemAction, TreeKeyEvent, TreeState, TreeStep, TreeViewHandle } from './useTreeState.js';
 export { SIZE_EPSILON, useLayoutAnchor, useMeasuredSizes } from './useMeasuredSizes.js';

package/dist/Tree/index.js

@@ -1 +1 @@
-export { SIZE_EPSILON, TYPE_AHEAD_RESET_MS, createTreeModel, isTypeAheadKey, layoutConnectors, layoutForest, treeAllExpandable, treeAncestors, treeCollapseOrAscend, treeExpandOrDescend, treeExpandTo, treeExpandable, treeFirst, treeFirstChild, treeItemAction, treeLast, treeLevel, treeNext, treeParent, treePosInSet, treePrevious, treeSetSize, treeStep, treeTypeAhead, treeVisible, typeAheadBuffer, useLayoutAnchor, useMeasuredSizes, useTreeState } from '../chunk-NTRZGNEX.js';
+export { SIZE_EPSILON, TYPE_AHEAD_RESET_MS, createTreeModel, isTypeAheadKey, layoutConnectors, layoutForest, placeGroups, treeAllExpandable, treeAncestors, treeCollapseOrAscend, treeExpandOrDescend, treeExpandTo, treeExpandable, treeFirst, treeFirstChild, treeItemAction, treeLast, treeLevel, treeNext, treeParent, treePosInSet, treePrevious, treeSetSize, treeStep, treeTypeAhead, treeVisible, typeAheadBuffer, useLayoutAnchor, useMeasuredSizes, useTreeState } from '../chunk-S3BCVWTU.js';

package/dist/Tree/layout.d.ts

@@ -38,6 +38,14 @@
  *   which is what reads as tidy.
  * - A ZERO HEIGHT BOX STILL OCCUPIES ITS ROW, so two of them are never drawn
  *   on top of each other.
+ * - A GROUP IS ROOM THE LAYOUT KEEPS, NOT A BOX DRAWN OVER IT AFTERWARDS. A
+ *   run of siblings can be enclosed in a box (a unit's seats, say) whose
+ *   padding and header are part of every member's outline, so a neighbour
+ *   that is not a member is held `gapX` clear of the BOX rather than of the
+ *   member card, while two members of one box stay `gapX` apart from each
+ *   other. The header is reserved above the run's rank and the padding below
+ *   it, on both rank modes, so a box never reaches into the gap a connector
+ *   runs through. See [LayoutGroup].
  *
  * Coordinates come back with the forest's top left corner at the origin plus
  * `margin`, and boxes in pre-order. The outline merge costs time proportional to a subtree's
@@ -79,6 +87,10 @@ export interface LayoutGaps {
     gapY: number;
     /** Where a box's top edge sits. Unset, `per-parent`. */
     ranks?: LayoutRanks | undefined;
+    /**
+     * Runs of siblings enclosed in a box: see [LayoutGroup]. Unset, none.
+     */
+    groups?: readonly LayoutGroup[] | undefined;
     /**
      * Space kept on all four sides of the forest.
      *
@@ -90,6 +102,44 @@ export interface LayoutGaps {
      */
     margin?: number | undefined;
 }
+/** The room a group's box keeps around its members: see [LayoutGroup]. */
+export interface LayoutGroupInset {
+    /** Between the box's side and its outermost member, on each side. */
+    x: number;
+    /** Between the box's top and its members' tops: its header lives here. */
+    top: number;
+    /** Between its members' bottoms and the box's bottom. */
+    bottom: number;
+}
+/**
+ * A box drawn round a RUN OF SIBLINGS: consecutive children of one parent, or
+ * consecutive roots.
+ *
+ * WHY SIBLINGS, AND WHY CONSECUTIVE. A box is one rectangle, and a rectangle
+ * round boxes that are not next to each other in the drawing encloses
+ * whatever lies between them: a member two ranks down, or a neighbour placed
+ * between two members, would be drawn inside a group it does not belong to.
+ * A run of siblings is the one shape a tidy layout keeps together on one rank
+ * with nothing between its members, so it is the shape a box can be drawn
+ * round honestly; anything else is refused by name rather than drawn wrong.
+ * An organization's unit is such a run: the seats that report to one lead.
+ *
+ * Each group carries its own inset because a header's height is a MEASURED
+ * value (a label and whatever chip rides beside it), and two groups need not
+ * say the same amount.
+ */
+export interface LayoutGroup {
+    id: string;
+    /** The boxes it encloses, in any order. Every one is a box of the forest. */
+    members: readonly string[];
+    inset: LayoutGroupInset;
+}
+/** A group where the layout put it: its members' extent plus its inset. */
+export interface PlacedGroup extends CanvasRect {
+    id: string;
+    members: readonly string[];
+    inset: LayoutGroupInset;
+}
 /** A box where the layout put it. */
 export interface PlacedNode extends CanvasRect {
     id: string;
@@ -100,13 +150,39 @@ export interface ForestLayout {
     /** Every box, in pre-order. */
     nodes: PlacedNode[];
     byId: Map<string, PlacedNode>;
-    /** The forest's extent: always at the origin. */
+    /**
+     * Every group, in the order it was given, as the rectangle its box is drawn
+     * in. Absent from a layout built by hand with none.
+     */
+    groups?: PlacedGroup[];
+    /**
+     * The rank mode it was laid out on, which is where a connector's run goes:
+     * see [layoutConnectors]. Absent from a layout built by hand, which is then
+     * read as `per-parent`.
+     */
+    ranks?: LayoutRanks;
+    /** The forest's extent, groups included: always at the origin. */
     bounds: CanvasRect;
 }
+/**
+ * Each group's rectangle: its members' extent, plus its inset on every side.
+ *
+ * Exported because the extent is a function of where the members are DRAWN,
+ * which during a relayout is on the way to where the layout put them: a box
+ * computed once from the target would sit at the end of a journey its members
+ * are still making.
+ */
+export declare function placeGroups(byId: ReadonlyMap<string, CanvasRect>, groups: readonly Pick<LayoutGroup, 'id' | 'members' | 'inset'>[]): PlacedGroup[];
 /** Lays out a forest of measured boxes: see the module doc for the rules. */
 export declare function layoutForest(roots: readonly LayoutNode[], gaps: LayoutGaps): ForestLayout;
-/** The two shapes a connector is drawn in: see [layoutConnectors]. */
-export type TreeConnectorShape = 'step' | 'curve';
+/**
+ * The shapes a connector is drawn in: see [layoutConnectors].
+ *
+ * `elbow` (the default) and `straight` are the org chart's own pair; `step` and
+ * `curve` are the two drawings this chart had before the elbow, kept because
+ * each is a real choice a caller makes knowing what it costs.
+ */
+export type TreeConnectorShape = 'elbow' | 'straight' | 'step' | 'curve';
 /**
  * One connector: the child it arrives at, the parent it leaves, and the path.
  *
@@ -128,31 +204,30 @@ export interface TreeConnector {
  * The connector from each box to its parent, as SVG path data: down from the
  * parent's bottom centre and into the child's top centre.
  *
- * TWO SHAPES, AND THE DEFAULT IS THE STEP: down, a rounded corner, across the
- * middle of the gap, another rounded corner, and down into the child. The
- * square step and the single cubic were both tried here first.
- *
- * A SQUARE step reads correctly at any width but meets its own siblings at a
- * right angle on the shared horizontal run, so a parent with four children
- * draws one long line with four corners on it and which corner belongs to
- * which child is read by tracing.
- *
- * A single CUBIC from the parent's bottom to the child's top (`curve`) fixes
- * that when the children sit close together, and loses definition exactly
- * where a chart is widest. A subtree is as wide as everything under it, so the
- * horizontal distance between a parent and an outer child grows without bound
- * while the vertical gap stays one rank; with both control points halfway down
- * that gap, the curve spends most of its length running horizontally in the
- * middle of the gap and reads as a long flat line passing under the parent,
- * its ends two stubs nowhere near it. Measured on a three-unit company: 430
- * units across, 105 down.
- *
- * The rounded step is the shape that keeps both properties, so it is what a
- * chart gets unless it asks otherwise: the corner is where the branch turns,
- * so it sits near the CHILD rather than shared with its siblings, and the drop
- * into each child is vertical however far to the side it is. `curve` is the
- * shape of the console's own org chart, which this package is drawn to match,
- * and a caller that wants that drawing asks for it knowing the above.
+ * `elbow`, THE DEFAULT, is ORTHOGONAL: down, a quarter circle of
+ * [ELBOW_RADIUS], across the run the parent's children share, another quarter
+ * circle, and down into the child. Every straight piece of it is vertical or
+ * horizontal, so a branch reads as a line of the org chart rather than as a
+ * drawing, and the corner is where the branch turns, near the CHILD, so which
+ * corner belongs to which child is read without tracing. The corners are true
+ * circular arcs (`A`), which is what a radius is; a quadratic through the
+ * corner point is not round and bulges at the size the design draws.
+ *
+ * `straight` is one segment from the parent's bottom centre to the child's
+ * top: the drawing for a chart dense enough that the run a parent's children
+ * share would be a line with forty corners on it.
+ *
+ * `step` is the elbow with a softer [STEP_RADIUS] turn drawn in quadratics,
+ * which this chart drew before the elbow. `curve` is a single cubic from the
+ * parent's bottom to the child's top, both handles on the run: the console's
+ * own org chart draws it, and it loses definition exactly where a chart is
+ * widest, because a subtree is as wide as everything under it while the gap
+ * stays one rank, so an outer child's curve spends most of its length running
+ * flat through the gap. Measured on a three-unit company: 430 units across,
+ * 105 down.
+ *
+ * Every shape but `straight` runs across at the same height, [busOf], which
+ * keeps it clear of every group box.
  *
  * Here rather than in the component that draws them, because it is arithmetic
  * over the layout and nothing about it is React's.

package/dist/TreeCanvas/TreeCanvas.d.ts

@@ -46,6 +46,17 @@
  * still on screen. Nothing else is an input to the layout: a badge whose text
  * changes inside a slot that keeps its size lays nothing out again.
  *
+ * A RUN OF SIBLINGS CAN BE ENCLOSED IN A BOX, a unit round its seats, with a
+ * label along its top (`groups`). The box is room the layout KEEPS rather than
+ * a rectangle drawn over it afterwards: its padding and header are part of the
+ * members' outlines, so a card that is not a member is never drawn inside one
+ * and two boxes are never drawn over each other. The label rides OVER the
+ * connectors, on the box's own fill, so a branch dropping into a member passes
+ * behind the words rather than through them. The box is drawing, like the
+ * connectors, and hidden from assistive technology; what it SAYS is given to
+ * each member card as its description, which is where a reader of the tree
+ * meets it.
+ *
  * AND IT MOVES. A chart arrives rank by rank rather than all at once, and a
  * relayout TWEENS every card from where it was to where it is, connectors and
  * all, so adding a seat is visibly the same chart rearranging rather than a
@@ -107,6 +118,11 @@ export interface TreeItemProps {
     'aria-posinset': number;
     'aria-expanded': boolean | undefined;
     'aria-selected': boolean;
+    /**
+     * The label of the group box the node's card is drawn in, for the card's
+     * own node: see `TreeCanvasProps.groups`. Unset for every other node.
+     */
+    'aria-describedby': string | undefined;
     'data-tree-id': string;
     ref: (el: HTMLElement | null) => void;
     onClick: (event: MouseEvent<HTMLElement>) => void;
@@ -224,6 +240,33 @@ export interface TreeComposing {
     /** Escape inside the ghost. Cancelling is the caller's: it owns the form. */
     onCancel: () => void;
 }
+/**
+ * A box drawn round a run of sibling cards, with a label along its top: a unit
+ * round the seats in it, say. See `TreeCanvasProps.groups`.
+ */
+export interface TreeCanvasGroup {
+    /** The group's own id. Unique among the groups, and never a card's id. */
+    id: string;
+    /**
+     * What the box is called, such as "Engineering · Core". Drawn along its top
+     * in the tertiary ink, and read as the description of every member card.
+     */
+    label: string;
+    /**
+     * A short key AHEAD of the label, such as the project key chip a unit's
+     * work is filed under: "ENG Engineering · Core", as the approved org chart
+     * reads it and as a rail row's `lead` puts a project's key before its name.
+     * Drawn and described with the label.
+     */
+    lead?: ReactNode | undefined;
+    /**
+     * The CARDS it encloses: ids `cards` returns, all children of one card (or
+     * all roots) and consecutive among them. A member that is not drawn right
+     * now (inside a closed card) is left out, and a group with none drawn is not
+     * drawn at all. Anything else is refused: see [LayoutGroup].
+     */
+    memberIds: readonly string[];
+}
 export interface TreeCanvasProps {
     /** The accessible name of the chart, such as "Structure chart". */
     label: string;
@@ -268,16 +311,6 @@ export interface TreeCanvasProps {
      * the pointer would move the card somebody was aiming at out from under them.
      */
     renderUnder?: ((id: string, card: TreeCardContext) => ReactNode) | undefined;
-    /**
-     * Whether a card is drawn with the dashed edge.
-     *
-     * It is the mark a card carries when it stands for somebody outside the
-     * system: a person rather than an agent, a seat nobody holds. The BOUNDARY
-     * says it rather than a hue, so it reads to a reader who cannot separate the
-     * hue at all, and the card's frame is this component's to draw so the mark
-     * is too. Unset, every card takes the solid edge.
-     */
-    cardOutline?: ((id: string) => boolean) | undefined;
     /**
      * The hue a card is tinted with, and the connector arriving at it.
      *
@@ -317,11 +350,24 @@ export interface TreeCanvasProps {
      */
     ranks?: LayoutRanks | undefined;
     /**
-     * The shape of the connectors: a rounded step (the default) or the single
-     * cubic the console's org chart draws. See [layoutConnectors], which states
-     * what each shape costs.
+     * The shape of the connectors: `elbow` (the default), orthogonal with a
+     * small round corner; `straight`, one segment; or the two older drawings,
+     * the softer `step` and the single `curve` the console's org chart draws.
+     * See [layoutConnectors], which states what each shape costs.
      */
     connector?: TreeConnectorShape | undefined;
+    /**
+     * Boxes drawn round runs of sibling cards, each with a label along its top:
+     * see [TreeCanvasGroup]. Keep it stable, as `nodes` is: it is an input to
+     * the layout.
+     *
+     * WHAT A GROUP IS FOR. A chart's cards say who reports to whom; a group says
+     * which of them work TOGETHER, the seats of one unit under the lead they
+     * report to, which the lines alone cannot: two units under one lead are two
+     * runs of children with nothing between them. The box is laid out, not
+     * painted over the layout, so a card outside it is never drawn inside it.
+     */
+    groups?: readonly TreeCanvasGroup[] | undefined;
     /**
      * Carries out Enter (activate) or Delete and Backspace (remove) on a node.
      * Return false when the node has no such action, so the key travels on.
@@ -381,4 +427,4 @@ export interface TreeCanvasProps {
     ref?: Ref<TreeCanvasHandle> | undefined;
     className?: string | undefined;
 }
-export declare function TreeCanvas({ label, nodes, cards, cardOf, renderCard, renderUnder, cardOutline, cardTone, appearance, ranks, connector, onNodeKey, onNodeKeyDown, hasNodeMenu, selectedId, onSelect, anchorNode, overlay, controlsPlacement, controlsExtra, controlsBelow, hint, dimmed, composing, labels, ref, className, }: TreeCanvasProps): import("react").JSX.Element;
+export declare function TreeCanvas({ label, nodes, cards, cardOf, renderCard, renderUnder, cardTone, appearance, ranks, connector, groups, onNodeKey, onNodeKeyDown, hasNodeMenu, selectedId, onSelect, anchorNode, overlay, controlsPlacement, controlsExtra, controlsBelow, hint, dimmed, composing, labels, ref, className, }: TreeCanvasProps): import("react").JSX.Element;

package/dist/TreeCanvas/index.d.ts

@@ -1,3 +1,3 @@
 import './TreeCanvas.css';
 export { TreeCanvas } from './TreeCanvas.js';
-export type { TreeActionsProps, TreeCanvasHandle, TreeCanvasProps, TreeCardContext, TreeCardInput, TreeCardTone, TreeComposing, TreeItemProps, } from './TreeCanvas.js';
+export type { TreeActionsProps, TreeCanvasGroup, TreeCanvasHandle, TreeCanvasProps, TreeCardContext, TreeCardInput, TreeCardTone, TreeComposing, TreeItemProps, } from './TreeCanvas.js';

package/dist/TreeCanvas/index.js

@@ -1,10 +1,10 @@
-export { TreeCanvas } from '../chunk-7HPRF5XN.js';
-import '../chunk-NTRZGNEX.js';
-import '../chunk-CMEE37QJ.js';
+export { TreeCanvas } from '../chunk-FUF52K7E.js';
+import '../chunk-S3BCVWTU.js';
+import '../chunk-BMYPGGPV.js';
 import '../chunk-53DVJCVW.js';
 import '../chunk-7RPGY3JE.js';
-import '../chunk-ITHXJHBB.js';
-import '../chunk-F27EPQ7D.js';
-import '../chunk-BZYDZBAN.js';
+import '../chunk-R25RGPUB.js';
+import '../chunk-4UQ7SMPK.js';
+import '../chunk-ETYEBKR4.js';
 import '../chunk-BZFWDIV6.js';
 import '../chunk-ODEQTPFM.js';

package/dist/TreeCanvas/motion.d.ts

@@ -29,9 +29,10 @@
  * two speeds. The tween is over the layout's own numbers, so a frame is a
  * position rather than a promise about one, and the connectors are recomputed
  * from those same numbers: a line that did not travel with its cards would
- * spend the whole relayout pointing at where a card used to be.
+ * spend the whole relayout pointing at where a card used to be, and so is every
+ * group's box, which is drawn round wherever its members are this frame.
  */
-import type { ForestLayout } from '../Tree/index.js';
+import { type ForestLayout } from '../Tree/index.js';
 /** How far apart two cards are revealed, in milliseconds. */
 export declare const ENTRANCE_STEP_MS = 60;
 /** How long a relayout takes to move every card from where it was to where it is. */