@crewlethq/ui 0.2.0 → 0.3.0

package/dist/TreeCanvas/TreeCanvas.d.ts

@@ -0,0 +1,384 @@
+/**
+ * A hierarchy drawn as cards on a canvas, with the ARIA tree pattern over it.
+ *
+ * WHAT IT OWNS AND WHAT IT DOES NOT. It owns the layout, the connectors, the
+ * keyboard pattern, focus and the per node menu state. It draws no card: the
+ * caller renders each one and is handed the props that make an element a
+ * treeitem, so a card can be anything from a name to a stack of rows without
+ * this component knowing what a seat, a unit or a company is.
+ *
+ * THE KEYBOARD PATTERN IS A TREE, AND ITS ITEMS HOLD NOTHING FOCUSABLE. Each
+ * card's header and each row inside a card is a `treeitem` with its level,
+ * position and expansion, and focus moves among them by a roving tab stop:
+ * arrows walk the visible order, Right and Left open, close and climb, Home
+ * and End jump, and typing finds a node by name. A treeitem's own keys act on
+ * it: Enter activates, Delete or Backspace removes, the ContextMenu key or
+ * Shift+F10 opens its menu. The buttons a pointer uses (expand, add, more)
+ * sit BESIDE the treeitem in a strip hidden from assistive technology and out
+ * of the tab order, because a control inside a treeitem is a control a screen
+ * reader cannot reach and a keyboard user would Tab through by the hundred;
+ * the menu they open is the same one the ContextMenu key opens. A press on
+ * that strip never leaves focus in it: the treeitem takes the focus, so what
+ * holds it is always a node a screen reader can announce and the arrows can
+ * move from. `ctx.actions` is what a caller spreads on such a strip.
+ *
+ * THE POINTER'S CONTROLS ARE QUIET UNTIL THE CARD IS REACHED, and that is why
+ * they are the component's to place rather than the caller's. The actions strip
+ * is drawn OVER the end of the card and the add control hangs UNDER it
+ * (`renderUnder`), both appearing on hover, on focus and on the selected card;
+ * so a name has the card's whole width rather than the half left beside three
+ * buttons nobody is pointing at, and the chart at rest is cards and connectors
+ * rather than a field of chrome. The room each takes is reserved whether or not
+ * it is drawn, because a chart that grew under the pointer would move the card
+ * somebody was aiming at out from under them.
+ *
+ * FOCUS NEVER SCROLLS BEHIND THE TRANSFORM'S BACK. A node is focused with
+ * `preventScroll` and then revealed by panning the canvas, and a node inside a
+ * collapsed card has its ancestors opened first. The caller decides which node
+ * is focused after an operation, an undo or a redo, through the handle.
+ *
+ * THE LAYOUT IS MEASURED. Every card is rendered at the card width variable
+ * and measured, the gaps between cards and the space around the whole chart
+ * are read from probes drawn with spacing tokens (so density scales them with
+ * everything else), and the layout places them: under each parent, or on a
+ * band per depth, which is what an org chart is and what the `node`
+ * appearance takes (`ranks`). A relayout keeps the node the operator acted on
+ * 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.
+ *
+ * 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
+ * new one. Both are `motion.ts`, both are off under `prefers-reduced-motion`,
+ * and neither changes what is drawn in the end or what any of it is called.
+ *
+ * A NODE IS ADDED IN THE CHART, NOT IN A DIALOG OVER IT. `composing` names a
+ * GHOST: a card the layout knows about and the data does not, drawn where the
+ * new node will be, holding the form that makes it. The chart makes room for
+ * it, draws the branch into it, eases onto it and gives the reader their view
+ * back when it goes. It is in `cards` and NOT in `nodes`, which is the whole
+ * of why the tree is untouched by it: no level, no position, no set size and
+ * no key of any real node moves, and no arrow key, type ahead or selection can
+ * land on something that is not there yet. See [TreeComposing].
+ *
+ * Ported from the engine dashboard's org builder canvas, with the generic half
+ * of its suite.
+ */
+import { type KeyboardEvent, type MouseEvent, type ReactNode, type Ref } from 'react';
+import { type CanvasLabels } from '../Canvas/index.js';
+import { type TreeConnectorShape, type TreeInput, type TreeItemAction, type LayoutRanks, type TreeModel, type TreeViewHandle } from '../Tree/index.js';
+/** A card of the layout: its id and the cards nested under it. */
+export interface TreeCardInput {
+    id: string;
+    children: TreeCardInput[];
+}
+/**
+ * The six hues a card can be tinted with, and the connector arriving at it.
+ *
+ * DECORATIVE AND PER ENTITY, never a series: two cards sharing a hue say
+ * nothing, so the palette is not measured for separability and the chart owes
+ * no legend (`--color-node-*` in the tokens package says the same). It is what
+ * an operator picks for one agent so they can find it again, and what a chart
+ * with no such choice derives from a stable identity.
+ *
+ * A NAMED SET RATHER THAN A COLOUR. A caller that could hand in any colour
+ * would hand in a literal, and the fill, the border, the halo and the ink of a
+ * tinted card are four measured steps of one hue rather than one value with
+ * three alphas applied by whoever drew it last.
+ */
+export type TreeCardTone = 'purple' | 'cyan' | 'green' | 'amber' | 'rose' | 'blue';
+/**
+ * The props that make an element the pointer-only strip of controls beside a
+ * node: see `TreeCardContext.actions`.
+ */
+export interface TreeActionsProps {
+    className: string;
+    'aria-hidden': 'true';
+    /** Set while a menu inside the strip is open, so the strip stays drawn. */
+    'data-menu-open': 'true' | undefined;
+    onMouseDown(event: MouseEvent<HTMLElement>): void;
+}
+/** The props that make an element the treeitem of a node. */
+export interface TreeItemProps {
+    role: 'treeitem';
+    tabIndex: number;
+    'aria-level': number;
+    'aria-setsize': number;
+    'aria-posinset': number;
+    'aria-expanded': boolean | undefined;
+    'aria-selected': boolean;
+    'data-tree-id': string;
+    ref: (el: HTMLElement | null) => void;
+    onClick: (event: MouseEvent<HTMLElement>) => void;
+    onDoubleClick: () => void;
+}
+/** What a card needs from the tree it is drawn in. */
+export interface TreeCardContext {
+    /** The props that make an element the treeitem of `id`. Spread them. */
+    item(id: string): TreeItemProps;
+    expanded(id: string): boolean;
+    expandable(id: string): boolean;
+    toggle(id: string): void;
+    /** Makes `id` the current node without moving focus, as a pointer action on its card does. */
+    activate(id: string): void;
+    /**
+     * The whole of a node's pointer-only strip of controls: its class, its
+     * removal from the accessibility tree and the press that lands on the node.
+     * Spread it on the element holding the expand, add and more buttons, and put
+     * that element IMMEDIATELY AFTER the node's own treeitem.
+     *
+     * WHY THE COMPONENT OWNS IT. The strip is drawn OVER the end of the card and
+     * is quiet until the card is reached, so the node's name has the card's whole
+     * width to say itself in rather than the half left over beside three buttons
+     * nobody is pointing at. Where it sits, when it appears and what covers what
+     * are the chart's decisions, not the caller's: left to the caller the strip
+     * was a permanent column and every name in the chart was truncated to fit
+     * beside it. The immediate-sibling rule is what the reveal is keyed on, which
+     * is why it is stated here and not merely implied.
+     *
+     * `press` is the same landing behaviour on its own, for a pointer-only region
+     * that is NOT this strip (a chip drawn along a card's bottom edge, say).
+     */
+    actions(id: string): TreeActionsProps;
+    /**
+     * The props that make a press anywhere in a pointer-only strip land on `id`
+     * rather than on the button it hit. Wrap the strip in them.
+     */
+    press(id: string): {
+        onMouseDown(event: MouseEvent<HTMLElement>): void;
+    };
+    menuOpen(id: string): boolean;
+    setMenuOpen(id: string, open: boolean): void;
+}
+/**
+ * What a screen can ask of a tree drawn on a CANVAS: everything a tree view
+ * answers, and the two things only a view with a viewport under it can.
+ *
+ * Separate from [TreeViewHandle] rather than added to it, because the other
+ * view of one hierarchy is a grid of rows with no viewport to move: a handle
+ * that promised these there would be a promise kept by doing nothing.
+ */
+export interface TreeCanvasHandle extends TreeViewHandle {
+    /**
+     * Ease onto one node's own card, remembering the view it left.
+     *
+     * For a surface opened ABOUT that node: the view moves to it with room
+     * around it, so the decision being made has the part of the chart it is
+     * about behind it. A node whose card has not been laid out yet is ignored.
+     */
+    focusRegion(id: string): void;
+    /** Give back the view [focusRegion] left. */
+    restoreView(): void;
+}
+/**
+ * A node being COMPOSED: the ghost card a new node's form is drawn in, before
+ * there is a node to draw.
+ *
+ * THE PHANTOM IS THE LAYOUT'S AND NOT THE DATA'S. A chart that asked for a
+ * child's name in a dialog over itself said nothing about WHERE that child
+ * would go, which is the one thing a chart is for. So the card is grafted into
+ * the CARD forest, under `parent` and after its existing children, exactly
+ * where the new node will land; `nodes` is untouched, and that is what keeps
+ * every real node's level, position in set, set size and key the same while a
+ * node is being composed. A screen reader is never told a unit has seven
+ * children while six exist. Nothing focusable by the tree's own keys is in it,
+ * either: the arrows, type ahead and the selection walk `nodes`, so they walk
+ * past a ghost that is not in them.
+ *
+ * IT IS DRAWN OUTSIDE THE TREE ELEMENT for the same reason. A form is not a
+ * `treeitem` and a `tree` may hold nothing else, so the ghost is a sibling of
+ * the tree in the same transformed world: the layout places it, and what is
+ * inside it is an ordinary region of the page that a screen reader reads and
+ * Tab walks.
+ *
+ * WHAT THE CHART DOES ABOUT IT. It opens `parent` if it is closed, eases onto
+ * the ghost with the room a form needs rather than the room a label needs
+ * ([CANVAS_COMPOSE_CONTEXT]), moves focus to the first control inside it, and
+ * on Escape calls `onCancel`. When it goes, the view the reader left is given
+ * back and focus returns to `parent`. Under `prefers-reduced-motion` every
+ * part of that still happens; only the animations do not.
+ */
+export interface TreeComposing {
+    /**
+     * The ghost card's own id.
+     *
+     * IT MUST NOT BE AN ID OF `nodes`. A ghost in the node forest is a node, and
+     * then everything this arrangement exists to avoid is back: a set size that
+     * counts it, an arrow key that lands on it and a selection that can hold it.
+     */
+    id: string;
+    /** The card it hangs under, which is the node the new one is being added to. */
+    parent: string;
+    /**
+     * The accessible name of the ghost, such as "Add to Engineering".
+     *
+     * THE GHOST IS A NAMED REGION rather than an anonymous box with a form in
+     * it, because focus is moved into it: a reader who arrives at a field with
+     * nothing around it has been told what to type and not what they are making
+     * or where it is going. The name says both, and it is the only thing about
+     * the ghost this component cannot work out for itself.
+     */
+    label: string;
+    /** What is drawn inside the ghost: the form that makes the node. */
+    render: () => ReactNode;
+    /** Escape inside the ghost. Cancelling is the caller's: it owns the form. */
+    onCancel: () => void;
+}
+export interface TreeCanvasProps {
+    /** The accessible name of the chart, such as "Structure chart". */
+    label: string;
+    /**
+     * The hierarchy as the tree pattern reads it: every node, nested.
+     *
+     * Keep it stable across renders (a `useMemo` over what it is derived from).
+     * A fresh array each render rebuilds the model, and with it the visible
+     * order and the layout, on every push a parent takes.
+     */
+    nodes: readonly TreeInput[];
+    /**
+     * Which CARDS the layout draws, and how they nest. A node drawn as a row
+     * inside another node's card is not a card of its own, so this is not always
+     * the node forest: it is asked again whenever the model or the expansion
+     * changes, and is given both.
+     *
+     * Keep it stable too, for the reason `nodes` is: it is asked again whenever
+     * it changes identity, and the tidy layout it feeds is the most expensive
+     * thing this component does.
+     */
+    cards: (model: TreeModel, expanded: ReadonlySet<string>) => TreeCardInput[];
+    /** The card a node is drawn in: itself, or the card holding its row. Stable, as `cards` is. */
+    cardOf: (id: string) => string;
+    /** Draws one card. Everything it needs from the tree is the second argument. */
+    renderCard: (id: string, card: TreeCardContext) => ReactNode;
+    /**
+     * What hangs UNDER a card, on the branch its children come off: the control
+     * that adds one, normally. Return nothing for a card that takes none.
+     *
+     * IT IS A SLOT RATHER THAN SOMETHING THE CALLER DRAWS ITSELF because of where
+     * it has to be. A control below the card is below the card's MEASURED bottom,
+     * which is where the layout puts the next rank and where the connectors
+     * start, so a caller drawing it itself either has it overlap its own
+     * children or has to tell the layout a height that is not the card's. Drawn
+     * here it is part of the card, so the space is reserved by the same
+     * measurement that reserves the name's, and every connector already leaves
+     * from below it.
+     *
+     * THE ROOM IS KEPT WHETHER OR NOT IT IS DRAWN. It is quiet until the card is
+     * reached, like the actions strip, and a chart that grew a rank taller under
+     * 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.
+     *
+     * ONE ANSWER FOR BOTH, because they are one statement. A tinted card reached
+     * by a branch in the chart's neutral ink reads as somebody else's branch
+     * ending on it, and two functions would be two places for that to come
+     * apart. Unset, or answered with nothing, a card is the chart's own neutral
+     * surface and the branch is the chart's own ink.
+     */
+    cardTone?: ((id: string) => TreeCardTone | undefined) | undefined;
+    /**
+     * How a card is drawn.
+     *
+     * `card` (the default) is a panel: one width for every card in the chart, its
+     * lines stacked with room around them, and the pointer's controls over its
+     * top right corner. It is what a chart of a few dozen nodes reads best as.
+     *
+     * `node` is an org chart NODE: as wide as its own name between a fixed icon
+     * zone and a fixed actions column, one rank tall, its two lines centred
+     * between them, with the actions as a column down its right edge and the add
+     * hanging under its bottom edge. Denser, and it is the drawing the console's
+     * own org chart uses, which this package is matched to. A chart of a hundred
+     * nodes fits on a screen in it; a card that has more to say than a name and a
+     * caption does not belong in it.
+     */
+    appearance?: 'card' | 'node' | undefined;
+    /**
+     * Where a card's top edge sits: under its own parent (`per-parent`) or on a
+     * band shared by every card of its depth (`shared`). See [LayoutRanks].
+     *
+     * Unset, it follows the appearance, because the two are one decision about
+     * what the chart IS. A chart of panels is a hierarchy of things with
+     * contents, where a short card's children riding up beside a tall
+     * neighbour's is tidier; a chart of org chart NODES is an organization,
+     * where 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.
+     */
+    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.
+     */
+    connector?: TreeConnectorShape | 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.
+     *
+     * The Menu key is not here: which menu is open is this component's state, so
+     * it opens the node's own menu itself when `hasNodeMenu` says there is one.
+     */
+    onNodeKey?: ((id: string, action: Exclude<TreeItemAction, 'menu'>) => boolean) | undefined;
+    /**
+     * Any other key the caller claims on a node, such as Alt with an arrow to
+     * move it among its siblings. Asked FIRST, while the node itself holds
+     * focus; return true when it was handled, and the chart swallows the key.
+     *
+     * The same contract the grid of rows keeps (`TreeGridProps.onRowKeyDown`),
+     * because the two are two views of one hierarchy and a key that moves a node
+     * in one has to move it in the other.
+     */
+    onNodeKeyDown?: ((id: string, event: KeyboardEvent<HTMLElement>) => boolean) | undefined;
+    /** Whether a node has a menu the ContextMenu key and Shift+F10 can open. */
+    hasNodeMenu?: ((id: string) => boolean) | undefined;
+    /** The selected node, drawn as `aria-selected` on its treeitem. */
+    selectedId?: string | null | undefined;
+    /**
+     * Selection follows focus. Called with every node focus reaches, so a caller
+     * that selects only some of them (a group heading is no node of the data)
+     * filters here.
+     */
+    onSelect?: ((id: string) => void) | undefined;
+    /**
+     * The node the operator just acted on, which a relayout keeps still on
+     * screen. Without one the node holding focus is kept still instead.
+     */
+    anchorNode?: string | null | undefined;
+    /** Drawn over the canvas without the transform, such as a note about the chart. */
+    overlay?: ReactNode | undefined;
+    /** Which corner the canvas's controls sit in. A chart's own corner is the top right. */
+    controlsPlacement?: 'top-right' | 'bottom-right' | undefined;
+    /** Anything else in the canvas's control bar: see [CanvasProps.controlsExtra]. */
+    controlsExtra?: ReactNode | undefined;
+    /** Bars stacked under the canvas's control bar: see [CanvasProps.controlsBelow]. */
+    controlsBelow?: ReactNode | undefined;
+    /** A note under the canvas's controls, about a key or a state: see [CanvasProps.hint]. */
+    hint?: ReactNode | undefined;
+    /**
+     * Pushes the chart back, for a surface opened over it about one of its
+     * nodes. See [CanvasProps.dimmed]; pair it with `focusRegion` on the handle,
+     * which says WHICH node the surface is about.
+     */
+    dimmed?: boolean | undefined;
+    /**
+     * A node being composed in the chart rather than in a surface over it: see
+     * [TreeComposing]. Null, and the chart is the data and nothing else.
+     */
+    composing?: TreeComposing | null | undefined;
+    /** The canvas control labels, for another language. */
+    labels?: Partial<CanvasLabels> | undefined;
+    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-runtime").JSX.Element;

package/dist/TreeCanvas/index.d.ts

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

package/dist/TreeCanvas/index.js

@@ -0,0 +1,10 @@
+export { TreeCanvas } from '../chunk-7HPRF5XN.js';
+import '../chunk-NTRZGNEX.js';
+import '../chunk-CMEE37QJ.js';
+import '../chunk-53DVJCVW.js';
+import '../chunk-7RPGY3JE.js';
+import '../chunk-ITHXJHBB.js';
+import '../chunk-F27EPQ7D.js';
+import '../chunk-BZYDZBAN.js';
+import '../chunk-BZFWDIV6.js';
+import '../chunk-ODEQTPFM.js';

package/dist/TreeCanvas/motion.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The two motions a chart of cards has, and the one question they both ask
+ * first: has the reader asked for less?
+ *
+ * A CHART ARRIVES RANK BY RANK. Every card at once is a picture that appears;
+ * one rank after another, a few dozen milliseconds apart, is a hierarchy being
+ * drawn, and the order the eye is walked in (down, then across) is the order
+ * the chart is read in afterwards. It runs ONCE, when the chart is first laid
+ * out, and never again: a chart that replayed its entrance on every push would
+ * be a chart nobody could read while anything was happening.
+ *
+ * A RELAYOUT MOVES CARDS RATHER THAN REPLACING THEM. Adding a seat re-centres
+ * every ancestor over its children and shifts whole subtrees sideways; jumped,
+ * the card the operator just made appears somewhere that has nothing to do
+ * with where the one they pressed was, and so does everything else. Tweened,
+ * the chart is visibly the same chart rearranging, which is the only way the
+ * reader keeps their place in it. The canvas's own anchor is the other half of
+ * that and is unaffected: it keeps the node acted on STILL ON SCREEN, over the
+ * targets, while the cards travel to them.
+ *
+ * NEITHER RUNS WHEN THE READER HAS ASKED FOR LESS. Both are read through
+ * [useStillness], and under `prefers-reduced-motion: reduce` the chart is laid
+ * out complete and every relayout is a jump: nothing is hidden, nothing is
+ * slower to reach, and no control moves later than it would have.
+ *
+ * WHY IT IS JAVASCRIPT AND NOT CSS. A card's position is a transform the
+ * layout computes, and a CSS transition on it would fire on the first paint of
+ * every card the measurement pass adds, which is the entrance played twice at
+ * 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.
+ */
+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. */
+export declare const REFLOW_MS = 350;
+/** The order cards are revealed in: down the chart, then across each row. */
+export declare function entranceOrder(layout: ForestLayout): string[];
+/** Whether the reader has asked for less motion, and again whenever that changes. */
+export declare function useStillness(): boolean;
+/**
+ * The cards revealed so far, or `null` once the chart is whole.
+ *
+ * `null` rather than "every id" so a caller has one cheap answer for the state
+ * a chart is in for all but its first second, and never walks a set per card
+ * per render for the rest of its life.
+ */
+export declare function useEntrance(layout: ForestLayout | null, still: boolean): ReadonlySet<string> | null;
+/**
+ * The layout as it is DRAWN this frame: the target, or a point on the way to
+ * it while a relayout is travelling.
+ *
+ * The bounds are the target's throughout, so the canvas neither grows nor
+ * shrinks under a pan while the cards move: what is scrollable is where the
+ * chart is going to be.
+ */
+export declare function useReflow(layout: ForestLayout | null, still: boolean): ForestLayout | null;