@tensor_1/react 2.42.0 → 2.43.0

package/README.md

@@ -762,6 +762,30 @@ The layout grid for dashboard widgets (HAR-1555; TENSOR's role dashboards). Pure
 - Refs reach the grid and item `<div>`s, and other props pass through. For an element you render yourself (a drag-and-drop library's sortable node, a server template), use `dashboardGridClassName(columns, gap)` and `dashboardGridItemClassName(span)`.
 - Plain HTML: `.uix-dashboard-grid` with `--cols-N` / `--{sm,md,lg,xl}-cols-N` and `--gap-sm|lg`, items `.uix-dashboard-grid__item` with `--span-2` / `--full`. Every direct child of the grid is a cell.
 
+### OrgChart
+
+Reporting lines as a top-down chart (HAR-1807; TENSOR's People directory). Managers sit above their direct reports, joined by lines; each person is a card with photo or initials, name, title, team, location and the number of direct reports, which is also the control that shows or hides them. Data fetching stays in the product: the chart asks for a person's reports through `loadChildren` the first time they are opened.
+
+```tsx
+<OrgChart
+  aria-label="Organisation"
+  nodes={roots}                       // OrgChartNode[]: { id, name, title?, team?, location?, photo?, badge?, reportCount?, children? }
+  loadChildren={(node) => api.reports(node.id)}
+  expanded={expanded} onToggle={(id, open) => setExpanded(next(expanded, id, open))}
+  selected={personId} onSelect={openPerson}
+  revealId={searchHit} onReveal={() => setSearchHit(null)}
+/>
+```
+
+- **Lazy reports:** a person with `reportCount > 0` and no `children` is expandable; on expand a loading row stands in for the reports, and a rejection shows an error row whose Enter, Space or click retries. Results are kept for the life of the chart. Expanding through a controlled `expanded` (a whole reporting line at once) loads each level as it appears.
+- **Search:** set `expanded` to the person's reporting line and `revealId` to the person; once their card exists the chart scrolls it into view, focuses it and calls `onReveal`. Set `revealId` back to null there, so the same person can be revealed again.
+- **Stacked rows:** a row of people without reports of their own is a column under their manager (`stackLeaves`, default true), so a team of eight takes one card width.
+- **Frame:** zoom out / in (25–150 %, around the frame's centre), Fit (the chart's width into the frame), the level button resets to 100 %; drag the background to pan (mouse and pen; touch scrolls). Opening a manager keeps their card where it was while their reports appear. Until the reader moves the view, a chart wider than the frame stays centred on its top, and `defaultZoom={'fit'}` keeps fitting as reports load. `--org-chart-max-height` (default 70vh) caps the frame. The root is an inline-size container: give it a width (a block, or `flex: 1` in a flex row).
+- **Narrow:** below 48rem of the chart's **own** width (a container query: a side panel counts as much as a phone) it is an indented vertical tree with guide lines; the toolbar steps aside.
+- **Keyboard:** one tab stop (roving tabindex). In the chart ↑ is the manager, ↓ the first report (↓ on a closed manager opens them first), ← → the previous and next person on the same level across teams; in a stacked column ↑ ↓ move along it. In the list the tree keys apply (↑ ↓ visible order, → open / first report, ← close / manager). From a stacked column, ← → go to the next column. Home / End, a letter jumps to the next visible person whose name starts with it, Enter opens the person (`onSelect`), Space shows or hides their reports. A failed load is announced.
+- **Words:** `labels` or `UixLabelsProvider` `orgChart` (`DEFAULT_ORG_CHART_LABELS`): the tree's default name (`chart`), loading, error, retry, `reportsOne` / `reportsMany` (`{count}`), expand / collapse, the toolbar and its buttons, `zoomLevel` / `resetZoom` (`{percent}`).
+- Plain HTML: `.uix-org-chart` > `__toolbar`, `__viewport` > `__canvas` > `ul.__tree[role=tree]` > `li.__item[role=treeitem]` > `.__node` (+ `ul.__group[role=group]`, `[data-stack]` for a column). The ARIA state on the item drives the styling.
+
 ### Select draws its own list
 
 `Select` (HAR-1572) no longer opens the browser's dropdown. It is the WAI-ARIA select-only combobox: a `<button role="combobox">` trigger and a UIx-drawn listbox in the top layer (a bottom sheet on phones). The props did not change, so existing call sites keep working:

package/dist/components/OrgChart.d.ts

@@ -0,0 +1,121 @@
+import * as react from 'react';
+import { HTMLAttributes } from 'react';
+
+/** One person (or position) in an {@link OrgChart}. */
+interface OrgChartNode {
+    id: string;
+    /** The person's name; also the card's accessible name. */
+    name: string;
+    /** Job title, under the name. */
+    title?: string;
+    team?: string;
+    location?: string;
+    /** Photo URL. Without one the card shows {@link OrgChartNode.initials}, else the name's initials. */
+    photo?: string;
+    initials?: string;
+    /** A short marker on the card, such as "You". It is read with the person's description. */
+    badge?: string;
+    /**
+     * How many people report directly to this one. With `loadChildren`, a count above 0 shows the
+     * count on the card and makes the person expandable before {@link OrgChartNode.children} is
+     * known. Once the reports are known, their number wins.
+     */
+    reportCount?: number;
+    /** The direct reports, when known. Otherwise `loadChildren` loads them on the first expand. */
+    children?: OrgChartNode[];
+}
+/** The words of an {@link OrgChart}. `{count}` and `{percent}` are filled in. */
+interface OrgChartLabels {
+    /** The tree's name when the chart gets no `aria-label` / `aria-labelledby`. */
+    chart: string;
+    /** The row in place of reports that are loading. */
+    loading: string;
+    /** The row in place of reports that could not be loaded; also announced. */
+    error: string;
+    /** The action in that row. Enter, Space or a click on the row runs it. */
+    retry: string;
+    /** Read after the person: one direct report. */
+    reportsOne: string;
+    /** Read after the person: `{count}` direct reports. */
+    reportsMany: string;
+    /** The report count's tooltip while the reports are hidden. */
+    expand: string;
+    /** The report count's tooltip while the reports are shown. */
+    collapse: string;
+    /** The zoom controls' group name. */
+    toolbar: string;
+    zoomIn: string;
+    zoomOut: string;
+    /** Fit the chart's width into the frame. */
+    fit: string;
+    /** The current zoom, shown on the reset button: `{percent}`. */
+    zoomLevel: string;
+    /** The reset button's name; it should start with the visible level. `{percent}`. */
+    resetZoom: string;
+}
+declare const DEFAULT_ORG_CHART_LABELS: OrgChartLabels;
+interface OrgChartProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'onToggle' | 'children'> {
+    /** The top of the chart: the people without a manager, or wherever the chart should start. */
+    nodes: OrgChartNode[];
+    /** Expanded people (controlled). Expanding one whose reports are not known loads them. */
+    expanded?: ReadonlySet<string>;
+    /** Expanded people at first render (uncontrolled). */
+    defaultExpanded?: ReadonlySet<string>;
+    /** A person was expanded or collapsed, by a click on the report count or by the keyboard. */
+    onToggle?: (id: string, expanded: boolean) => void;
+    /** The chosen person: highlighted, and the tree's entry point for the Tab key. */
+    selected?: string | null;
+    /** A card was clicked, or Enter pressed on it: open the person. */
+    onSelect?: (id: string) => void;
+    /**
+     * Loads a person's direct reports the first time they are expanded, for a chart that grows on
+     * demand. While it runs a loading row stands in for the reports; a rejection shows an error row
+     * whose Enter, Space or click retries, and is announced. The result is kept for the life of the
+     * chart.
+     */
+    loadChildren?: (node: OrgChartNode) => Promise<OrgChartNode[]>;
+    /**
+     * Bring this person into view and focus them once they are rendered: the target of a search.
+     * Expand their reporting line first (`expanded`); the chart waits until the card exists. Set it
+     * back to null in `onReveal`, so the same person can be revealed again later.
+     */
+    revealId?: string | null;
+    /** Called once the {@link OrgChartProps.revealId} person has been scrolled to and focused. */
+    onReveal?: (id: string) => void;
+    /**
+     * Stack a row of people who have no reports of their own in one column under their manager,
+     * instead of side by side. Default true: a team of eight then takes one card's width.
+     */
+    stackLeaves?: boolean;
+    /**
+     * Start at this zoom (0.25–1.5), or `'fit'` to fit the chart's width into the frame; the fit is
+     * kept as reports load until the reader zooms, pans or opens someone. Default 1.
+     */
+    defaultZoom?: number | 'fit';
+    /** Words of the chart. Default: `UixLabelsProvider` `orgChart`, then English. */
+    labels?: Partial<OrgChartLabels>;
+}
+/** The next zoom step above (`dir` 1) or below (`dir` -1) `zoom`. */
+declare const orgChartZoomStep: (zoom: number, dir: 1 | -1) => number;
+/** "Mira Kovač" → "MK"; one word → its first letter. */
+declare const orgChartInitials: (name: string) => string;
+/**
+ * An org chart over `.uix-org-chart` (HAR-1807): managers above their direct reports, joined by
+ * lines, each person a card with photo or initials, name, title, team, location and their number
+ * of direct reports. Reports load on expand (`loadChildren`); a person can be revealed by id for
+ * search. The frame zooms (buttons, and Fit for the chart's width) around its centre, pans by
+ * dragging its background, scrolls, and keeps an opened manager's card in place while their
+ * reports appear. Below 48rem of its own width it becomes an indented vertical tree.
+ *
+ * A WAI-ARIA tree with one tab stop. In the chart: ↑ manager, ↓ first report (expanding them
+ * first), ← → the previous and next person on the same level (from a stacked column, the next
+ * column); in a stacked column ↑ ↓ move along it. In the list: the tree keys (↑ ↓ visible order,
+ * → expand / first report, ← collapse / manager). Both: Home / End, a letter jumps to the next
+ * visible person whose name starts with it, Enter opens the person (`onSelect`), Space shows or
+ * hides their reports.
+ *
+ * The root is an inline-size container: give it a width (a block, or `flex: 1` in a flex row).
+ */
+declare function OrgChart({ nodes, expanded: controlledExpanded, defaultExpanded, onToggle, selected, onSelect, loadChildren, revealId, onReveal, stackLeaves, defaultZoom, labels: labelOverrides, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, ...props }: OrgChartProps): react.JSX.Element;
+
+export { DEFAULT_ORG_CHART_LABELS, OrgChart, type OrgChartLabels, type OrgChartNode, type OrgChartProps, orgChartInitials, orgChartZoomStep };