@plantops/ui 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# @plantops/ui
+
+The shared React presentation layer for every PlantOps console (Doc 08 §2).
+
+Ant Design 6 supplies the components; this library supplies the *product* — the
+design language, the theme built from it, the shell every console renders
+inside, the icon-key registry Doc 05 §7 requires, and the handful of patterns
+that must not be reinvented per screen.
+
+## The rule that keeps it reusable
+
+**Nothing here calls the IAM.** It depends on `@plantops/contracts` for types and
+on nothing else in the workspace, enforced by the `scope:ui` boundary in the root
+ESLint config: every component takes data and callbacks and returns markup. The
+stateful half — a client, tokens, grants, navigation fetching — is
+[`@plantops/web-kit`](../web-kit), which depends on this.
+
+That split is what makes the gatepass and visitor consoles cheap. They mount the
+same provider and shell, render the same `<NavMenu>` from their own
+`/iam/navigation` response, and inherit the product's appearance without
+inheriting the IAM's screens.
+
+## What is in it
+
+| Area | Exports |
+|---|---|
+| `theme/` | `PlantOpsThemeProvider`, `plantOpsTheme`, `useColorMode`, and the raw tokens (`palette`, `neutral`, `spacing`, `radius`, `layout`, `typography`) |
+| `layout/` | `AppShell`, `NavMenu`, `Brand`, `UserMenu`, and the pure `nav-tree` helpers (`firstNavRoute`, `navSelectionForPath`, `flattenNavRoutes`) |
+| `icons/` | `NavIcon`, `iconForKey`, `knownIconKeys` — the `nav_node.icon` → icon-set map |
+| `feedback/` | `PageHeader`, `ScreenLoading`, `ScreenEmpty`, `ScreenError`, and `errorCopyFor` — one sentence per `IamErrorCode` |
+| `forms/` | `AuthLayout`, `CredentialsForm` |
+| `data/` | `DataTable` (bound to the Doc 06 §1 pagination envelope), `StatusTag` |
+
+## Using it
+
+```tsx
+import { AppShell, Brand, NavMenu, PageHeader, PlantOpsThemeProvider } from '@plantops/ui';
+
+<PlantOpsThemeProvider>
+  <AppShell brand={<Brand product="Gatepass" />} nav={<NavMenu tree={tree} … />}>
+    <PageHeader title="Passes" />
+  </AppShell>
+</PlantOpsThemeProvider>
+```
+
+Consumed as TypeScript source: `package.json` points `main` at `src/index.ts`, so
+a Next.js app lists it in `transpilePackages` and picks up changes without a
+separate library build.
+
+## Conventions worth knowing before adding a component
+
+- **No hex literals in components.** Colours come from `theme/tokens.ts` or from
+  antd's CSS variables (`var(--ant-color-primary)`). A literal that is right in
+  light mode is wrong in dark mode and cannot know which is showing.
+- **Red, amber and green are reserved for status.** PlantOps administers plants;
+  those three already mean something on a plant floor, which is why the brand
+  colour is a deep teal. See the header of `theme/tokens.ts`.
+- **Copy is part of the design language.** What a `403` says to a person lives in
+  `feedback/error-copy.ts`, not in each console, so the gatepass console cannot
+  invent a second wording — and so Doc 06 §2's "a denial never reveals whether
+  the target exists in another tenant" is enforceable by a test.
+- **`'use client'` on anything with state or an event handler.** These libraries
+  are consumed by Next.js App Router apps.
+
+## Tests
+
+```sh
+npx nx test @plantops/ui
+```
+
+jsdom, with the antd-shaped browser APIs stubbed in `src/test-setup.ts`. antd 6
+ships ESM inside its CommonJS build, so `transformIgnorePatterns` in
+`jest.config.cts` transforms `antd`, `@ant-design/*` and `@rc-component/*` rather
+than skipping them.

package/dist/data/data-table.d.ts

@@ -0,0 +1,41 @@
+/**
+ * An antd `Table` wired to the IAM's pagination envelope (Doc 06 §1).
+ *
+ * Every list screen in every console — users, roles, clients, applications,
+ * bindings, service accounts, audit — receives `{ data, page, limit, total }`
+ * and has to turn it into a table with server-side paging. Doing that by hand
+ * per screen is where the same three mistakes appear: reading `data.length` as
+ * the total (so the pager shows one page of a thousand rows), losing the page
+ * on a refetch, and rendering an empty table where a "no results" explanation
+ * belongs.
+ *
+ * The component is generic over the row type and passes antd's `columns`
+ * through untouched, so it constrains nothing about how a screen looks — only
+ * about how it talks to the API.
+ */
+import type { Paginated } from '@plantops/contracts';
+import { type TableProps } from 'antd';
+import * as React from 'react';
+export interface DataTableQuery {
+    page: number;
+    limit: number;
+}
+export interface DataTableProps<T> {
+    /** The envelope. `undefined` while the first page is in flight. */
+    result: Paginated<T> | undefined;
+    columns: TableProps<T>['columns'];
+    rowKey: (row: T) => string;
+    loading?: boolean;
+    /** Fired when the pager moves. The caller refetches and passes the result back. */
+    onQueryChange?: (query: DataTableQuery) => void;
+    /** Shown instead of the table body when the result is empty. */
+    empty?: React.ReactNode;
+    /** Replaces the whole table — for a failed load. */
+    error?: React.ReactNode;
+    size?: TableProps<T>['size'];
+    onRowClick?: (row: T) => void;
+    /** Selection, expansion and the rest of antd's surface, when a screen needs it. */
+    tableProps?: Omit<TableProps<T>, 'columns' | 'dataSource' | 'rowKey' | 'loading' | 'pagination' | 'onChange'>;
+}
+export declare function DataTable<T>({ result, columns, rowKey, loading, onQueryChange, empty, error, size, onRowClick, tableProps, }: DataTableProps<T>): React.ReactNode;
+//# sourceMappingURL=data-table.d.ts.map

package/dist/data/data-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-table.d.ts","sourceRoot":"","sources":["../../src/data/data-table.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,mEAAmE;IACnE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IACjC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAClC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mFAAmF;IACnF,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAChD,gEAAgE;IAChE,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,oDAAoD;IACpD,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC7B,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC;IAC9B,mFAAmF;IACnF,UAAU,CAAC,EAAE,IAAI,CACf,UAAU,CAAC,CAAC,CAAC,EACb,SAAS,GAAG,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,GAAG,UAAU,CAC5E,CAAC;CACH;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,EAC3B,MAAM,EACN,OAAO,EACP,MAAM,EACN,OAAe,EACf,aAAa,EACb,KAAK,EACL,KAAK,EACL,IAAe,EACf,UAAU,EACV,UAAU,GACX,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,SAAS,CA4CrC"}

package/dist/data/data-table.js

@@ -0,0 +1,31 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { MAX_PAGE_SIZE } from '@plantops/contracts';
+import { Table } from 'antd';
+import { ScreenEmpty } from '../feedback/state-panels';
+export function DataTable({ result, columns, rowKey, loading = false, onQueryChange, empty, error, size = 'middle', onRowClick, tableProps, }) {
+    if (error !== undefined)
+        return error;
+    const rows = result?.data ?? [];
+    return (_jsx(Table, { ...tableProps, columns: columns, dataSource: rows, rowKey: rowKey, loading: loading, size: size, locale: {
+            emptyText: loading ? ' ' : (empty ?? _jsx(ScreenEmpty, {})),
+        }, onRow: onRowClick === undefined
+            ? tableProps?.onRow
+            : (row) => ({ onClick: () => onRowClick(row), style: { cursor: 'pointer' } }), pagination: result === undefined
+            ? false
+            : {
+                current: result.page,
+                pageSize: result.limit,
+                total: result.total,
+                // The server refuses anything above MAX_PAGE_SIZE (Doc 06 §1), so
+                // offering a larger option would be offering a 400.
+                pageSizeOptions: [10, 25, 50, MAX_PAGE_SIZE].map(String),
+                showSizeChanger: true,
+                showTotal: (total, [from, to]) => `${from}–${to} of ${total}`,
+            }, onChange: (pagination) => {
+            onQueryChange?.({
+                page: pagination.current ?? 1,
+                limit: pagination.pageSize ?? (result?.limit ?? 25),
+            });
+        }, scroll: { x: 'max-content' } }));
+}

package/dist/data/scope-tree-select.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Choosing a node of the org tree, and saying which kind a node is.
+ *
+ * Both live in `@plantops/ui` because both are needed twice, by screens that
+ * must not disagree: Session 31's editor builds the structure and Session 35's
+ * access screen grants against it. Doc 09 §3.4 is explicit that the scope picker
+ * on the grant screen "shows the tree", so that the admin sees exactly where
+ * they are granting — a flat select of node names would hide the one thing that
+ * decides how far a grant reaches.
+ *
+ * Neither component fetches anything. They take the tree and a callback, which
+ * is what keeps `scope:ui` free of the IAM client (root `eslint.config.mjs`).
+ */
+import type { ScopeNodeDTO, ScopeNodeKind } from '@plantops/contracts';
+import * as React from 'react';
+/** The tag colour for any kind, suggested or tenant-supplied. */
+export declare function scopeKindColor(kind: ScopeNodeKind): string;
+export interface ScopeKindTagProps {
+    kind: ScopeNodeKind;
+}
+export declare function ScopeKindTag({ kind }: ScopeKindTagProps): React.ReactElement;
+export interface ScopeTreeSelectProps {
+    /** Roots of the caller's tree, as `GET /iam/scopes` returns them. */
+    tree: readonly ScopeNodeDTO[];
+    /** The chosen node id, or `null` for nothing chosen. */
+    value: string | null;
+    onChange: (id: string | null) => void;
+    /**
+     * Nodes the operator may not choose. They stay in the tree, greyed out and
+     * expandable: the node they *can* choose is often beneath one they cannot,
+     * and hiding a branch would make the tree lie about the organisation.
+     */
+    isDisabled?: (node: ScopeNodeDTO) => boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    /** Rendered when the tenant has no tree at all. */
+    notFoundContent?: React.ReactNode;
+    allowClear?: boolean;
+    style?: React.CSSProperties;
+}
+/**
+ * A tree picker over the org structure.
+ *
+ * `treeDefaultExpandAll` because an org tree is tens of nodes and a picker that
+ * opens collapsed makes the operator hunt for a plant they can already name.
+ * `treeNodeFilterProp="title"` so typing filters by the display name, which is
+ * the only part of a node a person knows — the `path` is id-derived labels
+ * (Doc 01 §3.5) and searching it would match nothing anyone typed.
+ */
+export declare function ScopeTreeSelect({ tree, value, onChange, isDisabled, placeholder, disabled, notFoundContent, allowClear, style, }: ScopeTreeSelectProps): React.ReactElement;
+//# sourceMappingURL=scope-tree-select.d.ts.map

package/dist/data/scope-tree-select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-tree-select.d.ts","sourceRoot":"","sources":["../../src/data/scope-tree-select.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEvE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAyC/B,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAE1D;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,wBAAgB,YAAY,CAAC,EAAE,IAAI,EAAE,EAAE,iBAAiB,GAAG,KAAK,CAAC,YAAY,CAM5E;AAED,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,IAAI,EAAE,SAAS,YAAY,EAAE,CAAC;IAC9B,wDAAwD;IACxD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACtC;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,eAAe,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAClC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,EAC9B,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,UAAU,EACV,WAAyC,EACzC,QAAgB,EAChB,eAAe,EACf,UAAiB,EACjB,KAAK,GACN,EAAE,oBAAoB,GAAG,KAAK,CAAC,YAAY,CAqB3C"}

package/dist/data/scope-tree-select.js

@@ -0,0 +1,59 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Tag, TreeSelect } from 'antd';
+import * as React from 'react';
+import { scopeKindLabel, scopeTreeData } from './scope-tree';
+/**
+ * The four kinds, told apart at a glance (Doc 09 §3.1: "kinds rendered
+ * distinctly").
+ *
+ * Colour carries the nesting rather than the meaning — the sequence runs from
+ * the widest scope to the narrowest, so a tree reads as a gradient inward and an
+ * out-of-place kind is visible without reading the label. Nothing enforces that
+ * nesting (Doc 01 §3.5 pins no kind to a depth), which is exactly why seeing it
+ * is useful.
+ */
+const KIND_COLOR = {
+    group: 'purple',
+    plant: 'blue',
+    department: 'cyan',
+    gate: 'green',
+};
+/**
+ * Colours a tenant's own kind labels can land on.
+ *
+ * The gradient argument above only holds for the suggested four, which nest in
+ * a known order. A tenant vocabulary has no order this component can know, so
+ * the weaker invariant is the one worth keeping: **distinct kinds look
+ * distinct**. Assignment is a hash of the label, so it is stable across
+ * renders, across sessions and across users looking at the same tree — which a
+ * palette handed out in first-seen order would not be.
+ */
+const FALLBACK_COLORS = ['magenta', 'volcano', 'orange', 'gold', 'lime', 'geekblue'];
+function fallbackColor(kind) {
+    let hash = 0;
+    for (let index = 0; index < kind.length; index += 1) {
+        hash = (hash * 31 + kind.charCodeAt(index)) | 0;
+    }
+    return FALLBACK_COLORS[Math.abs(hash) % FALLBACK_COLORS.length] ?? 'default';
+}
+/** The tag colour for any kind, suggested or tenant-supplied. */
+export function scopeKindColor(kind) {
+    return KIND_COLOR[kind] ?? fallbackColor(kind);
+}
+export function ScopeKindTag({ kind }) {
+    return (_jsx(Tag, { color: scopeKindColor(kind), style: { marginInlineEnd: 0 }, children: scopeKindLabel(kind) }));
+}
+/**
+ * A tree picker over the org structure.
+ *
+ * `treeDefaultExpandAll` because an org tree is tens of nodes and a picker that
+ * opens collapsed makes the operator hunt for a plant they can already name.
+ * `treeNodeFilterProp="title"` so typing filters by the display name, which is
+ * the only part of a node a person knows — the `path` is id-derived labels
+ * (Doc 01 §3.5) and searching it would match nothing anyone typed.
+ */
+export function ScopeTreeSelect({ tree, value, onChange, isDisabled, placeholder = 'Choose where this applies', disabled = false, notFoundContent, allowClear = true, style, }) {
+    const treeData = React.useMemo(() => scopeTreeData(tree, { isDisabled }), [tree, isDisabled]);
+    return (_jsx(TreeSelect, { value: value ?? undefined, onChange: (next) => onChange(next ?? null), treeData: treeData, disabled: disabled, allowClear: allowClear, showSearch: true, treeNodeFilterProp: "title", treeDefaultExpandAll: true, placeholder: placeholder, notFoundContent: notFoundContent, style: { width: '100%', ...style } }));
+}

package/dist/data/scope-tree.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Pure functions over the `ScopeNodeDTO` tree `GET /iam/scopes` returns — the
+ * WHERE dimension of every grant (Doc 01 §3.5, Doc 06 §6).
+ *
+ * In `@plantops/ui` rather than in a console because two screens need the same
+ * tree for opposite purposes and must not disagree about it: Session 31's editor
+ * *builds* the structure, and Session 35's access screen *points at* a node in
+ * it. A second copy would be two answers to "what may I select", which is the
+ * one question a grant screen has to get right.
+ *
+ * Nothing here knows an endpoint. It takes the tree the server sent and returns
+ * shapes antd's `Tree` and `TreeSelect` accept, which is the whole of what the
+ * two screens share.
+ *
+ * ## `path` is read for exactly one thing
+ *
+ * Coverage is subtree containment: a grant at a node covers every descendant
+ * (Doc 04 §4), and `path` is how that is expressed. `descendantIds` uses it to
+ * answer "which nodes are beneath this one" without a recursive walk, because a
+ * move picker has to grey out the moving node's own subtree — moving a node
+ * under its own descendant would orphan the subtree from its tree, which the
+ * server refuses with a 409 the operator should never have been able to reach.
+ *
+ * Nothing here parses the labels. They are `n_` + a node's UUID hex and never a
+ * display name (Doc 01 §3.5); a consumer that read meaning out of them would be
+ * doing the resolver's job badly.
+ */
+import { type ScopeNodeDTO, type ScopeNodeKind } from '@plantops/contracts';
+/**
+ * Display names for the kinds the IAM suggests.
+ *
+ * A lookup with a fallback rather than a total map, because `kind` is
+ * tenant-supplied text since ADR 0002 §6 and no fixed domain exists any more.
+ * Use {@link scopeKindLabel}; reading this record directly will hand you
+ * `undefined` for a tenant's own vocabulary.
+ */
+export declare const SCOPE_KIND_LABEL: Readonly<Record<string, string>>;
+/**
+ * What to call a kind in a console.
+ *
+ * An unrecognised label is a tenant's own word, so it is shown rather than
+ * hidden or replaced — capitalised for the same reason the four suggested ones
+ * are, and otherwise left exactly as the tenant typed it. Rendering something
+ * generic here would erode the legibility that justifies `kind` existing
+ * (ADR 0002 §1.2).
+ */
+export declare function scopeKindLabel(kind: ScopeNodeKind): string;
+/**
+ * The order kinds normally nest in — Group → Plant → Department → Gate for a
+ * tenant that has expressed no preference.
+ *
+ * A default for the add-child form, not a rule. Doc 01 §3.5 does not pin a kind
+ * to a depth, and an organisation with a department directly under a group is
+ * modelling itself honestly rather than incorrectly; the API accepts it. So this
+ * pre-selects the likely answer and lets the operator disagree — the same
+ * arrangement `defaultKindUnder` makes for nav nodes.
+ */
+export declare const SCOPE_KIND_ORDER: readonly ScopeNodeKind[];
+/**
+ * The kind a new child of `parent` most likely is.
+ *
+ * `vocabulary` is the tenant's own ordered list — `client.config`'s
+ * `scope_node_kinds` — falling back to the suggested four. A parent whose kind
+ * is not in the vocabulary at all (a tenant mid-rename, or a node created
+ * before the list changed) yields the deepest label rather than the shallowest:
+ * new nodes are far more often leaves than roots.
+ */
+export declare function defaultChildKind(parent: ScopeNodeDTO | null, vocabulary?: readonly ScopeNodeKind[]): ScopeNodeKind;
+/** One node with its depth in the rendered tree and the trail above it. */
+export interface FlatScopeNode {
+    node: ScopeNodeDTO;
+    /** 0 for a root. Counted in the tree, not read from `depth`. */
+    level: number;
+    /** Names of the ancestors, outermost first — a "Acme / Plant B" trail. */
+    ancestorNames: string[];
+}
+/** Every node, depth-first in display order. */
+export declare function flattenScopeTree(tree: readonly ScopeNodeDTO[]): FlatScopeNode[];
+/** The node with this id, anywhere in the tree. */
+export declare function findScopeNode(tree: readonly ScopeNodeDTO[], id: string): ScopeNodeDTO | null;
+/**
+ * The ids of `node` and everything beneath it.
+ *
+ * Includes the node itself, because every caller so far wants "the subtree I
+ * must not touch" rather than "the subtree minus its own root" — a move picker
+ * has to exclude the node as well as its descendants, since a node cannot be its
+ * own parent either.
+ *
+ * Matched on `path` rather than walked, so it is correct for a node handed in
+ * without its `children` populated.
+ */
+export declare function descendantIds(tree: readonly ScopeNodeDTO[], node: ScopeNodeDTO): Set<string>;
+/** One antd tree node — the shape `Tree` and `TreeSelect` both consume. */
+export interface ScopeTreeDataNode {
+    key: string;
+    value: string;
+    title: string;
+    /** The node this row stands for, so a renderer need not look it up again. */
+    node: ScopeNodeDTO;
+    disabled: boolean;
+    /** True when the row is only there to be expanded through. */
+    selectable: boolean;
+    children: ScopeTreeDataNode[];
+}
+export interface ScopeTreeDataOptions {
+    /**
+     * Rows the operator may not choose — greyed out but still expandable, because
+     * the node they *can* choose may be underneath one they cannot.
+     */
+    isDisabled?: (node: ScopeNodeDTO) => boolean;
+}
+/**
+ * The tree, as antd's `treeData`.
+ *
+ * `key` and `value` are both the node id: `Tree` reads the first and
+ * `TreeSelect` the second, and giving them the same value is what lets one
+ * function feed both.
+ */
+export declare function scopeTreeData(tree: readonly ScopeNodeDTO[], options?: ScopeTreeDataOptions): ScopeTreeDataNode[];
+/** Every node id in the tree — what an "expand all" needs. */
+export declare function allScopeNodeIds(tree: readonly ScopeNodeDTO[]): string[];
+/** How many nodes the tree holds, and how deep it goes. */
+export declare function scopeTreeSize(tree: readonly ScopeNodeDTO[]): {
+    nodes: number;
+    depth: number;
+};
+//# sourceMappingURL=scope-tree.d.ts.map

package/dist/data/scope-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-tree.d.ts","sourceRoot":"","sources":["../../src/data/scope-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAK7D,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAM1D;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EAA+B,CAAC;AAErF;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,UAAU,GAAE,SAAS,aAAa,EAAqB,GACtD,aAAa,CAOf;AAED,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,YAAY,CAAC;IACnB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,gDAAgD;AAChD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,YAAY,EAAE,GAC5B,aAAa,EAAE,CAkBjB;AAED,mDAAmD;AACnD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,EAAE,EAAE,MAAM,GACT,YAAY,GAAG,IAAI,CAErB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,IAAI,EAAE,YAAY,GACjB,GAAG,CAAC,MAAM,CAAC,CAOb;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,8DAA8D;IAC9D,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC;CAC9C;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,OAAO,GAAE,oBAAyB,GACjC,iBAAiB,EAAE,CAiBrB;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,EAAE,CAEvE;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,YAAY,EAAE,GAAG;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,CAMA"}

package/dist/data/scope-tree.js

@@ -0,0 +1,163 @@
+/**
+ * Pure functions over the `ScopeNodeDTO` tree `GET /iam/scopes` returns — the
+ * WHERE dimension of every grant (Doc 01 §3.5, Doc 06 §6).
+ *
+ * In `@plantops/ui` rather than in a console because two screens need the same
+ * tree for opposite purposes and must not disagree about it: Session 31's editor
+ * *builds* the structure, and Session 35's access screen *points at* a node in
+ * it. A second copy would be two answers to "what may I select", which is the
+ * one question a grant screen has to get right.
+ *
+ * Nothing here knows an endpoint. It takes the tree the server sent and returns
+ * shapes antd's `Tree` and `TreeSelect` accept, which is the whole of what the
+ * two screens share.
+ *
+ * ## `path` is read for exactly one thing
+ *
+ * Coverage is subtree containment: a grant at a node covers every descendant
+ * (Doc 04 §4), and `path` is how that is expressed. `descendantIds` uses it to
+ * answer "which nodes are beneath this one" without a recursive walk, because a
+ * move picker has to grey out the moving node's own subtree — moving a node
+ * under its own descendant would orphan the subtree from its tree, which the
+ * server refuses with a 409 the operator should never have been able to reach.
+ *
+ * Nothing here parses the labels. They are `n_` + a node's UUID hex and never a
+ * display name (Doc 01 §3.5); a consumer that read meaning out of them would be
+ * doing the resolver's job badly.
+ */
+import { SUGGESTED_SCOPE_NODE_KINDS, } from '@plantops/contracts';
+/**
+ * Display names for the kinds the IAM suggests.
+ *
+ * A lookup with a fallback rather than a total map, because `kind` is
+ * tenant-supplied text since ADR 0002 §6 and no fixed domain exists any more.
+ * Use {@link scopeKindLabel}; reading this record directly will hand you
+ * `undefined` for a tenant's own vocabulary.
+ */
+export const SCOPE_KIND_LABEL = {
+    group: 'Group',
+    plant: 'Plant',
+    department: 'Department',
+    gate: 'Gate',
+};
+/**
+ * What to call a kind in a console.
+ *
+ * An unrecognised label is a tenant's own word, so it is shown rather than
+ * hidden or replaced — capitalised for the same reason the four suggested ones
+ * are, and otherwise left exactly as the tenant typed it. Rendering something
+ * generic here would erode the legibility that justifies `kind` existing
+ * (ADR 0002 §1.2).
+ */
+export function scopeKindLabel(kind) {
+    const known = SCOPE_KIND_LABEL[kind];
+    if (known !== undefined)
+        return known;
+    const trimmed = kind.trim();
+    if (trimmed.length === 0)
+        return kind;
+    return trimmed.charAt(0).toUpperCase() + trimmed.slice(1);
+}
+/**
+ * The order kinds normally nest in — Group → Plant → Department → Gate for a
+ * tenant that has expressed no preference.
+ *
+ * A default for the add-child form, not a rule. Doc 01 §3.5 does not pin a kind
+ * to a depth, and an organisation with a department directly under a group is
+ * modelling itself honestly rather than incorrectly; the API accepts it. So this
+ * pre-selects the likely answer and lets the operator disagree — the same
+ * arrangement `defaultKindUnder` makes for nav nodes.
+ */
+export const SCOPE_KIND_ORDER = SUGGESTED_SCOPE_NODE_KINDS;
+/**
+ * The kind a new child of `parent` most likely is.
+ *
+ * `vocabulary` is the tenant's own ordered list — `client.config`'s
+ * `scope_node_kinds` — falling back to the suggested four. A parent whose kind
+ * is not in the vocabulary at all (a tenant mid-rename, or a node created
+ * before the list changed) yields the deepest label rather than the shallowest:
+ * new nodes are far more often leaves than roots.
+ */
+export function defaultChildKind(parent, vocabulary = SCOPE_KIND_ORDER) {
+    const order = vocabulary.length > 0 ? vocabulary : SCOPE_KIND_ORDER;
+    const deepest = order[order.length - 1] ?? 'gate';
+    if (parent === null)
+        return order[0] ?? 'group';
+    const index = order.indexOf(parent.kind);
+    if (index === -1)
+        return deepest;
+    return order[index + 1] ?? deepest;
+}
+/** Every node, depth-first in display order. */
+export function flattenScopeTree(tree) {
+    const rows = [];
+    const walk = (nodes, level, ancestorNames) => {
+        for (const node of nodes) {
+            rows.push({ node, level, ancestorNames });
+            if (node.children.length > 0) {
+                walk(node.children, level + 1, [...ancestorNames, node.name]);
+            }
+        }
+    };
+    walk(tree, 0, []);
+    return rows;
+}
+/** The node with this id, anywhere in the tree. */
+export function findScopeNode(tree, id) {
+    return flattenScopeTree(tree).find((row) => row.node.id === id)?.node ?? null;
+}
+/**
+ * The ids of `node` and everything beneath it.
+ *
+ * Includes the node itself, because every caller so far wants "the subtree I
+ * must not touch" rather than "the subtree minus its own root" — a move picker
+ * has to exclude the node as well as its descendants, since a node cannot be its
+ * own parent either.
+ *
+ * Matched on `path` rather than walked, so it is correct for a node handed in
+ * without its `children` populated.
+ */
+export function descendantIds(tree, node) {
+    const prefix = `${node.path}.`;
+    const ids = new Set([node.id]);
+    for (const row of flattenScopeTree(tree)) {
+        if (row.node.path.startsWith(prefix))
+            ids.add(row.node.id);
+    }
+    return ids;
+}
+/**
+ * The tree, as antd's `treeData`.
+ *
+ * `key` and `value` are both the node id: `Tree` reads the first and
+ * `TreeSelect` the second, and giving them the same value is what lets one
+ * function feed both.
+ */
+export function scopeTreeData(tree, options = {}) {
+    const { isDisabled } = options;
+    const build = (node) => {
+        const disabled = isDisabled?.(node) ?? false;
+        return {
+            key: node.id,
+            value: node.id,
+            title: node.name,
+            node,
+            disabled,
+            selectable: !disabled,
+            children: node.children.map(build),
+        };
+    };
+    return tree.map(build);
+}
+/** Every node id in the tree — what an "expand all" needs. */
+export function allScopeNodeIds(tree) {
+    return flattenScopeTree(tree).map((row) => row.node.id);
+}
+/** How many nodes the tree holds, and how deep it goes. */
+export function scopeTreeSize(tree) {
+    const rows = flattenScopeTree(tree);
+    return {
+        nodes: rows.length,
+        depth: rows.reduce((deepest, row) => Math.max(deepest, row.level + 1), 0),
+    };
+}

package/dist/data/status-tag.d.ts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+/** What a state means to the person reading the row. */
+export type StatusTone = 'good' | 'attention' | 'stopped' | 'neutral';
+export interface StatusTagProps {
+    /** The raw enum value from the API. */
+    status: string;
+    /** Overrides the derived tone — for a state whose meaning is screen-specific. */
+    tone?: StatusTone;
+    /** Overrides the label. Defaults to the status, capitalised. */
+    label?: string;
+}
+export declare function statusTone(status: string): StatusTone;
+export declare function StatusTag({ status, tone, label }: StatusTagProps): React.ReactElement;
+//# sourceMappingURL=status-tag.d.ts.map

package/dist/data/status-tag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-tag.d.ts","sourceRoot":"","sources":["../../src/data/status-tag.tsx"],"names":[],"mappings":"AAmBA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AA4BtE,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAErD;AAED,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,cAAc,GAAG,KAAK,CAAC,YAAY,CAQrF"}

package/dist/data/status-tag.js

@@ -0,0 +1,50 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * One vocabulary for "what state is this row in".
+ *
+ * The IAM has four independent status enums — user (`active`/`locked`/
+ * `disabled`), client (`active`/`suspended`), service account (`active`/
+ * `revoked`) and the derived expired-binding flag — and they mean roughly the
+ * same three things. Rendering each with its own ad-hoc colour is how a console
+ * ends up showing `disabled` in red on one screen and grey on the next, which
+ * quietly teaches an admin that the colour means nothing.
+ *
+ * So: statuses map to a small set of *tones*, and the tone decides the colour.
+ * Unknown values render neutrally with their own label rather than throwing,
+ * because a status enum can gain a member in a migration long before this file
+ * hears about it.
+ */
+import { Tag } from 'antd';
+const TONE_COLOR = {
+    good: 'green',
+    attention: 'gold',
+    stopped: 'red',
+    neutral: 'default',
+};
+/**
+ * Status string → tone.
+ *
+ * `locked` is `attention` rather than `stopped` on purpose: it is reversible by
+ * an administrator in one click, where `disabled` and `revoked` are decisions.
+ */
+const TONE_FOR_STATUS = {
+    active: 'good',
+    enabled: 'good',
+    locked: 'attention',
+    pending: 'attention',
+    expiring: 'attention',
+    disabled: 'stopped',
+    suspended: 'stopped',
+    revoked: 'stopped',
+    expired: 'stopped',
+    inactive: 'neutral',
+};
+export function statusTone(status) {
+    return TONE_FOR_STATUS[status.toLowerCase()] ?? 'neutral';
+}
+export function StatusTag({ status, tone, label }) {
+    const resolved = tone ?? statusTone(status);
+    const text = label ?? status.charAt(0).toUpperCase() + status.slice(1).replace(/_/g, ' ');
+    return (_jsx(Tag, { color: TONE_COLOR[resolved], style: { marginInlineEnd: 0 }, children: text }));
+}