@crewlethq/ui 0.2.0 → 0.4.0

package/dist/Tree/index.d.ts

@@ -0,0 +1,8 @@
+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 { treeItemAction, treeStep, useTreeState } from './useTreeState.js';
+export type { TreeItemAction, TreeKeyEvent, TreeState, TreeStep, TreeViewHandle } from './useTreeState.js';
+export { SIZE_EPSILON, useLayoutAnchor, useMeasuredSizes } from './useMeasuredSizes.js';
+export type { MeasuredSizes } from './useMeasuredSizes.js';

package/dist/Tree/index.js

@@ -0,0 +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';

package/dist/Tree/layout.d.ts

@@ -0,0 +1,160 @@
+/**
+ * A tidy layout for a forest of variable size boxes, as a pure function.
+ *
+ * WHY IT IS HAND WRITTEN. The package ships no layout library: the ones that
+ * exist either lay out general graphs (and cost two orders of magnitude more
+ * code and time for a tree) or assume every node is the same size, and a unit
+ * card that stacks its seats inside it is as tall as its membership. This is
+ * the Reingold-Tilford family, sized to that problem.
+ *
+ * THE RULES IT KEEPS.
+ *
+ * - SIZES ARE INPUT. Nothing here measures anything: the caller passes each
+ *   box's width and height (measured in a browser by `useMeasuredSizes`,
+ *   injected in a test), so the layout is deterministic and testable without a
+ *   DOM.
+ * - CHILDREN SIT AT THEIR PARENT'S BOTTOM PLUS `gapY` (`ranks: 'per-parent'`,
+ *   the default), or on a band shared by every box of their depth
+ *   (`ranks: 'shared'`). Per-parent is the tidier of the two where cards vary
+ *   in height, because a short card's children do not hang a tall neighbour's
+ *   height below it; shared is what an ORG CHART looks like, where a rank of
+ *   the organization is a row a reader scans across, and it is what the
+ *   console's own chart draws. See [LayoutGaps.ranks].
+ * - SEPARATION IS BY VERTICAL EXTENT, NOT BY DEPTH. A tall card in one subtree
+ *   can sit beside a grandchild in the next, and a contour indexed by depth
+ *   would let the two overlap. Each subtree's left and right outline is kept
+ *   as a function of y, and a neighbour is placed `gapX` clear of every y they
+ *   share, including the band between a parent and its children where the
+ *   connector runs. On shared ranks that band carries no constraint, because
+ *   nothing is ever drawn between two ranks: a subtree is then held clear of
+ *   its neighbour exactly where the two have boxes on one rank, which is the
+ *   separation a rank-and-order layout keeps and is why a wide subtree's outer
+ *   grandchild may sit under its parent's neighbour.
+ * - PARENTS ARE CENTRED over their first and last child.
+ * - SIBLINGS ARE PACKED FROM BOTH SIDES AND AVERAGED. Packing only from the
+ *   left pushes a small subtree between two large ones against its left
+ *   neighbour. Both packings satisfy every separation, the constraints are
+ *   linear, so their average does too; the result is also mirror symmetric,
+ *   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.
+ *
+ * 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
+ * breakpoints, so a layout is roughly quadratic in the worst case; for the few
+ * hundred boxes of an organization chart that is well under a millisecond per
+ * hundred nodes, and it runs on a size change, never per frame.
+ */
+import type { CanvasRect } from '../Canvas/geometry.js';
+/** One box to lay out: a size, an id and its children. */
+export interface LayoutNode {
+    id: string;
+    width: number;
+    height: number;
+    children: readonly LayoutNode[];
+}
+/**
+ * Where a box's top edge sits: under its own parent, or on its depth's band.
+ *
+ * `per-parent` puts every box `gapY` under its own parent's bottom, so a rank
+ * of the chart is not a straight line and a short card's children ride up
+ * beside a tall neighbour's. It is the tidier drawing of a forest whose cards
+ * vary a lot in height.
+ *
+ * `shared` gives every depth ONE band, as tall as the tallest box in it, and
+ * centres each box in its band; the next band starts `gapY` below. That is
+ * what an ORG CHART is: a rank is a row a reader scans across, and two units
+ * of one company sit on one line whether or not one of them carries a lead
+ * along its bottom edge. It is also what a rank-and-order graph layout
+ * produces for a tree, which is what the console's chart is drawn with.
+ */
+export type LayoutRanks = 'per-parent' | 'shared';
+export interface LayoutGaps {
+    /** Horizontal space between neighbouring boxes that share any height. */
+    gapX: number;
+    /**
+     * Vertical space between ranks: a box's bottom and its children's tops on
+     * `per-parent`, one band's bottom and the next band's top on `shared`.
+     */
+    gapY: number;
+    /** Where a box's top edge sits. Unset, `per-parent`. */
+    ranks?: LayoutRanks | undefined;
+    /**
+     * Space kept on all four sides of the forest.
+     *
+     * IT IS PART OF THE LAYOUT rather than padding on whatever draws it, because
+     * the canvas scrolls and CLIPS: a margin drawn as padding is outside the
+     * scrollable content, so the outermost card's halo, its focus ring and the
+     * control hanging under it are cut off at the frame at exactly the moment a
+     * reader has panned to that card. Unset, none.
+     */
+    margin?: number | undefined;
+}
+/** A box where the layout put it. */
+export interface PlacedNode extends CanvasRect {
+    id: string;
+    depth: number;
+    parent: string | null;
+}
+export interface ForestLayout {
+    /** Every box, in pre-order. */
+    nodes: PlacedNode[];
+    byId: Map<string, PlacedNode>;
+    /** The forest's extent: always at the origin. */
+    bounds: CanvasRect;
+}
+/** 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';
+/**
+ * One connector: the child it arrives at, the parent it leaves, and the path.
+ *
+ * IT CARRIES THE CHILD'S ID because a connector can be the child's own colour.
+ * A chart that tints a node by what it holds tints the line into it too, or the
+ * branch arrives at a tinted card in the chart's neutral ink and reads as
+ * somebody else's. The id is the only thing a caller needs to ask its own
+ * question about the line, and it costs nothing to the caller that has none.
+ */
+export interface TreeConnector {
+    /** The box the connector arrives at. */
+    id: string;
+    /** The box it leaves. */
+    parent: string;
+    /** SVG path data, in layout coordinates. */
+    d: string;
+}
+/**
+ * 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.
+ *
+ * Here rather than in the component that draws them, because it is arithmetic
+ * over the layout and nothing about it is React's.
+ */
+export declare function layoutConnectors(layout: ForestLayout, shape?: TreeConnectorShape): TreeConnector[];

package/dist/Tree/model.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The visible order of a collapsible tree, as pure functions.
+ *
+ * WHY IT EXISTS. Two views of one hierarchy need the same answers: a chart
+ * drawn as a `tree` and an outline drawn as a `treegrid`. They are different
+ * ARIA patterns (a treegrid has cells and row actions a tree must not contain)
+ * so they cannot share one keyboard hook, but "what is the next visible row",
+ * "where does Left go" and "which row does typing `eng` land on" must not have
+ * two answers. The model is that shared half; each view owns its roles, its
+ * focus and its keys.
+ *
+ * THE RULES IT KEEPS.
+ *
+ * - VISIBLE ORDER IS PRE-ORDER, skipping the descendants of collapsed nodes.
+ * - RIGHT EXPANDS A CLOSED NODE, or moves to the first child of an open one;
+ *   LEFT COLLAPSES AN OPEN NODE, or moves to the parent. A leaf only moves.
+ * - TYPE AHEAD matches the start of a visible label, case insensitively, from
+ *   the row after the current one and wrapping. Typing one character again
+ *   cycles through the rows that start with it. A word never STARTS with `+`,
+ *   `-` or `0`: those are a canvas's zoom and fit keys, and a press that means
+ *   "fit" one moment and "find the row starting with zero" the next is a press
+ *   nobody can predict. Inside a word they are ordinary characters, so
+ *   "Q3 2026" is still typed whole.
+ * - NOTHING IS MUTATED. Expansion is a set the view owns and passes in.
+ *
+ * Every function is named for the tree, because this module's exports reach a
+ * consumer through the package barrel: `visible` and `level` are words an
+ * application has its own meaning for, and `treeVisible` and `treeLevel` are
+ * not.
+ */
+/** One node as a caller describes it: an id, the text a reader sees, and children. */
+export interface TreeInput {
+    id: string;
+    /** What type ahead matches against: the text a person reads on the row. */
+    label: string;
+    children?: readonly TreeInput[];
+}
+export interface TreeModel {
+    roots: readonly string[];
+    children: ReadonlyMap<string, readonly string[]>;
+    parent: ReadonlyMap<string, string | null>;
+    label: ReadonlyMap<string, string>;
+    /** Zero for a root. */
+    depth: ReadonlyMap<string, number>;
+    /** Every node in pre-order, collapsed or not. */
+    order: readonly string[];
+}
+/** Builds the model. Ids must be unique across the whole forest. */
+export declare function createTreeModel(forest: readonly TreeInput[]): TreeModel;
+/** Whether a node has children, so a view gives it `aria-expanded` and a chevron. */
+export declare function treeExpandable(tree: TreeModel, id: string): boolean;
+/** `aria-level`: one for a root. */
+export declare function treeLevel(tree: TreeModel, id: string): number;
+/** `aria-setsize`: how many siblings, itself included. */
+export declare function treeSetSize(tree: TreeModel, id: string): number;
+/** `aria-posinset`: one based position among its siblings. */
+export declare function treePosInSet(tree: TreeModel, id: string): number;
+export declare function treeParent(tree: TreeModel, id: string): string | null;
+export declare function treeFirstChild(tree: TreeModel, id: string): string | null;
+/** Its ancestors, the root first. */
+export declare function treeAncestors(tree: TreeModel, id: string): string[];
+/** The expanded set with every ancestor of `id` opened, so the node is visible. */
+export declare function treeExpandTo(tree: TreeModel, expanded: ReadonlySet<string>, id: string): Set<string>;
+/** Every node that can be expanded: what "Expand all" sets. */
+export declare function treeAllExpandable(tree: TreeModel): Set<string>;
+/** Every visible node, in order. */
+export declare function treeVisible(tree: TreeModel, expanded: ReadonlySet<string>): string[];
+export declare function treeFirst(tree: TreeModel): string | null;
+export declare function treeLast(tree: TreeModel, expanded: ReadonlySet<string>): string | null;
+/** The next visible node after `id`, or null at the end. */
+export declare function treeNext(tree: TreeModel, expanded: ReadonlySet<string>, id: string): string | null;
+/** The visible node before `id`, or null at the start. */
+export declare function treePrevious(tree: TreeModel, expanded: ReadonlySet<string>, id: string): string | null;
+/** What Right means on `id`: expand it, move to its first child, or nothing. */
+export declare function treeExpandOrDescend(tree: TreeModel, expanded: ReadonlySet<string>, id: string): {
+    expand: string;
+} | {
+    focus: string;
+} | null;
+/** What Left means on `id`: collapse it, move to its parent, or nothing. */
+export declare function treeCollapseOrAscend(tree: TreeModel, expanded: ReadonlySet<string>, id: string): {
+    collapse: string;
+} | {
+    focus: string;
+} | null;
+/**
+ * How long a pause ends a type ahead word: the WAI-ARIA practices' own
+ * examples use half a second.
+ */
+export declare const TYPE_AHEAD_RESET_MS = 500;
+/**
+ * The word typed so far, and when its last key was pressed (milliseconds). A
+ * view starts from `{ text: '', at: 0 }` and keeps what `typeAheadBuffer`
+ * returns.
+ */
+export interface TypeAheadState {
+    text: string;
+    at: number;
+}
+/** Whether a key press at `now` is a type ahead character rather than a command. */
+export declare function isTypeAheadKey(event: {
+    key: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+}, state: TypeAheadState, now: number): boolean;
+/** The buffer after a type ahead key at `now`. */
+export declare function typeAheadBuffer(state: TypeAheadState, key: string, now: number): TypeAheadState;
+/** The visible node whose label starts with `text`, searching after `from` and wrapping. */
+export declare function treeTypeAhead(tree: TreeModel, expanded: ReadonlySet<string>, from: string | null, text: string): string | null;

package/dist/Tree/useMeasuredSizes.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The rendered size of each card, measured by the browser, for a layout to use.
+ *
+ * WHY IT EXISTS. A card's height depends on what it holds (a unit stacks its
+ * seats), its spacing scales with the density setting, and its text follows
+ * the reader's own browser font size. A layout fed sizes copied into
+ * TypeScript as constants would overlap cards in compact or comfortable
+ * density and at any font size but the one somebody tested. So the cards are
+ * rendered at their real width (a token), measured, and the measured sizes are
+ * what the layout runs on.
+ *
+ * THE RULES IT KEEPS.
+ *
+ * - ONE ResizeObserver for every card, not one per card: a chart of a few
+ *   hundred cards should cost one observer and one batched update per frame.
+ * - A SIZE CHANGE IS APPLIED BEFORE PAINT. The observer reports after layout
+ *   and before paint, and the update is flushed synchronously there, so a card
+ *   that grows (a font finished loading, density changed, an operation added a
+ *   seat) is never painted overlapping its neighbour for a frame.
+ * - SUB-PIXEL NOISE IS NOT A CHANGE. Fractional re-measurements under half a
+ *   pixel do not trigger a relayout, which would otherwise jitter a chart
+ *   whose text renders at fractional sizes.
+ * - NOTHING IS LAID OUT BEFORE IT IS MEASURED. `measured(ids)` says whether
+ *   every card a layout needs has a size yet; until it does the caller shows
+ *   nothing and fits nothing.
+ * - THE ACTED ON NODE STAYS PUT. `useLayoutAnchor` moves the view before paint
+ *   so the node the operator just touched keeps its screen position when a
+ *   relayout moves it in the world.
+ *
+ * Sizes are border box, unscaled by any transform: a card inside a zoomed
+ * canvas reports the size it is laid out at, which is the size a layout needs.
+ * The observer WATCHES the border box too, not the default content box:
+ * density scales a card's padding, and a change to padding alone moves the
+ * border box without touching the content box, so an observer left on the
+ * default would never report it and the cards would overlap. A size is kept
+ * after its card unmounts, so a card that returns (an undo) is placed at its
+ * last size until the observer reports it again.
+ */
+import type { CanvasPoint, CanvasSize } from '../Canvas/geometry.js';
+/** Changes smaller than this, in CSS pixels, are measurement noise rather than a new size. */
+export declare const SIZE_EPSILON = 0.5;
+export interface MeasuredSizes {
+    /** The ref callback for the element drawn for `id`. Stable for the life of the id. */
+    measure: (id: string) => (el: HTMLElement | null) => void;
+    /** Every size seen so far, by id. A new map whenever any size changes. */
+    sizes: ReadonlyMap<string, CanvasSize>;
+    /** Whether every one of `ids` has been measured at least once. */
+    measured: (ids: Iterable<string>) => boolean;
+}
+export declare function useMeasuredSizes(): MeasuredSizes;
+/**
+ * Keeps the acted on node still on screen when a new layout moves it.
+ *
+ * `positions` is each node's world position in the current layout (null while
+ * there is none); `anchorId` is the node the operator just acted on. When a
+ * new layout moves that node, `keep(before, after)` runs before paint with its
+ * old and new position; a canvas's `anchor` is exactly that. A node that did
+ * not exist in the previous layout has no position to keep, so the caller
+ * anchors something that did (a new seat's unit, a deleted seat's neighbour).
+ */
+export declare function useLayoutAnchor(positions: ReadonlyMap<string, CanvasPoint> | null, anchorId: string | null, keep: (before: CanvasPoint, after: CanvasPoint) => void): void;

package/dist/Tree/useTreeState.d.ts

@@ -0,0 +1,89 @@
+/**
+ * A collapsible tree's state, and what a key press asks of it.
+ *
+ * ONE COPY FOR BOTH PATTERNS. A chart drawn as a `tree` and an outline drawn
+ * as a `treegrid` keep the same expansion and roving focus rules over the same
+ * visible order model; only their roles, their focus and their cells differ.
+ * That shared half lives here.
+ */
+import { type TreeInput, type TreeModel } from './model.js';
+/** The slice of a keyboard event these functions read, so a plain object works too. */
+export interface TreeKeyEvent {
+    key: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+    shiftKey?: boolean;
+}
+export interface TreeState {
+    readonly model: TreeModel;
+    readonly expanded: ReadonlySet<string>;
+    /** Every visible node, in order. */
+    readonly rows: readonly string[];
+    /** The roving tab stop: always a visible node, or `null` for an empty tree. */
+    readonly active: string | null;
+    setActive(id: string): void;
+    toggle(id: string): void;
+    expandAll(): void;
+    /** Collapses everything but the tops, so the tree keeps something to stand on. */
+    collapseAll(): void;
+    /** Opens every collapsed ancestor of `id`; true when any was closed. */
+    open(id: string): boolean;
+    /**
+     * The node typing `key` at `now` finds after `from`: `null` when nothing
+     * matches, `undefined` when the key is not a type ahead key at all.
+     */
+    typed(event: TreeKeyEvent, from: string, now: number): string | null | undefined;
+}
+/**
+ * What is collapsed, which node holds the tab stop, and type ahead.
+ *
+ * COLLAPSED, NOT EXPANDED, IS WHAT IS KEPT: a node nobody has closed is open,
+ * which is also what a node an operation just added should be. The tab stop is
+ * the node last focused, else the selection, else the first node, and is moved
+ * to the nearest visible ancestor when its own node is hidden or gone, so the
+ * tree always has exactly one way in.
+ */
+export declare function useTreeState(forest: readonly TreeInput[], selected: string | null): TreeState;
+/** What a navigation key asks of a tree: focus a node, or open or close one. */
+export type TreeStep = {
+    readonly focus: string;
+} | {
+    readonly toggle: string;
+};
+/**
+ * What a navigation key pressed on `id` asks for: a step, `null` for a key
+ * that is the tree's but leads nowhere (Up on the first node), or `undefined`
+ * for a key that is not the tree's at all, which the caller leaves alone.
+ *
+ * Down and Up walk the visible order; Right opens a closed node or enters an
+ * open one; Left closes an open node or climbs to the parent; Home and End
+ * jump; a printable key types ahead. A chord with Ctrl, Command or Alt is
+ * never the tree's.
+ */
+export declare function treeStep(tree: TreeState, id: string, event: TreeKeyEvent & {
+    timeStamp: number;
+}): TreeStep | null | undefined;
+/**
+ * What a key press asks of the ITEM it landed on, as opposed to of the tree.
+ *
+ * `activate` is the item's primary action (a row's editor, a card's form),
+ * `remove` deletes it, and `menu` opens its own menu, which the widget handles
+ * itself because it owns which menu is open. Shift+F10 is the menu too: the
+ * ContextMenu key is missing from several keyboards and every platform that
+ * lacks it offers that chord instead.
+ *
+ * Shift with Enter, Delete or Backspace is NOT the item's: those are a text
+ * selection's or an application's, and an item that claimed them would delete
+ * a node while somebody was extending a selection over it.
+ */
+export type TreeItemAction = 'activate' | 'remove' | 'menu';
+export declare function treeItemAction(event: TreeKeyEvent): TreeItemAction | null;
+/** What a screen can ask of a tree view it holds a ref to. */
+export interface TreeViewHandle {
+    /** Open every collapsed ancestor of a node, focus it, and bring it into view. */
+    focusNode(id: string): void;
+    expandAll(): void;
+    /** Collapse everything but the tops, so the tree keeps something to stand on. */
+    collapseAll(): void;
+}