@plantops/web-kit 0.1.0

package/dist/use-async.js

@@ -0,0 +1,76 @@
+'use client';
+/**
+ * "Fetch this when the screen opens, and tell me how it went."
+ *
+ * Every screen in every console does the same four things: call one endpoint,
+ * show a skeleton while it is in flight, show the failure if it fails, and
+ * offer a reload. Written per screen, it is four `useState`s and a race
+ * condition — the classic one where a slow first request resolves after a fast
+ * second and overwrites it.
+ *
+ * This is deliberately small. It is not a data-fetching library: no cache, no
+ * deduplication, no background revalidation. Those matter when many components
+ * request the same thing; an admin console's screens each own their data, and
+ * the two things that genuinely are shared — grants and navigation — have their
+ * own providers precisely so they are fetched once.
+ */
+import * as React from 'react';
+/**
+ * Runs `request` when `deps` change, and again on `reload()`.
+ *
+ * `request` is called with an `AbortSignal`; passing it on is optional but
+ * turns an abandoned request into a cancelled one. Results from a superseded
+ * call are dropped either way — the generation counter below is what makes the
+ * race impossible rather than merely unlikely.
+ */
+export function useAsync(request, deps, options = {}) {
+    const { enabled = true } = options;
+    const [data, setData] = React.useState(undefined);
+    const [error, setError] = React.useState(null);
+    const [loading, setLoading] = React.useState(enabled);
+    const [nonce, setNonce] = React.useState(0);
+    // The latest `request` without making it a dependency: a caller writing an
+    // inline arrow — which is every caller — would otherwise re-fetch on every
+    // render. `deps` is the caller's explicit statement of what the request
+    // depends on, and it is the only thing that should trigger one.
+    const requestRef = React.useRef(request);
+    requestRef.current = request;
+    React.useEffect(() => {
+        if (!enabled) {
+            setLoading(false);
+            return;
+        }
+        const controller = new AbortController();
+        let current = true;
+        setLoading(true);
+        requestRef
+            .current(controller.signal)
+            .then((value) => {
+            if (!current)
+                return;
+            setData(value);
+            setError(null);
+        })
+            .catch((cause) => {
+            if (!current || controller.signal.aborted)
+                return;
+            setError(cause);
+        })
+            .finally(() => {
+            if (current)
+                setLoading(false);
+        });
+        return () => {
+            current = false;
+            controller.abort();
+        };
+        // `deps` is the caller's dependency list by design, and `request` is read
+        // through a ref so an inline arrow does not re-fetch on every render. The
+        // spread is what the rule cannot verify statically, and is the point.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [enabled, nonce, ...deps]);
+    const reload = React.useCallback(() => {
+        setNonce((value) => value + 1);
+    }, []);
+    return { data, error, loading, reload };
+}

package/dist/use-navigation.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The menu, from `GET /iam/navigation` (Doc 05 §4).
+ *
+ * A hook rather than a provider because a console fetches it once, in the shell
+ * layout, and passes the tree down as a prop to whatever renders it — the
+ * sidebar, a mobile drawer, a command palette. Wrapping it in a context would
+ * add an indirection for a single consumer.
+ *
+ * It is not cached here, for the reason `libs/iam-client/src/endpoints/
+ * navigation.ts` gives: the menu changes when the *catalog* changes as well as
+ * when grants change, it is fetched once per shell load rather than once per
+ * request, and there is no burst for a cache to absorb — only staleness to
+ * introduce. {@link UseNavigationResult.reload} exists for the platform admin
+ * who has just edited the catalog and wants to see it (Doc 09 §2.1).
+ */
+import type { NavigationResponse, NavNodeDTO } from '@plantops/contracts';
+export interface UseNavigationResult {
+    /** The response, once it lands. */
+    navigation: NavigationResponse | undefined;
+    /** The tree alone — `[]` while loading, and for a subject who may see nothing. */
+    tree: NavNodeDTO[];
+    loading: boolean;
+    error: unknown;
+    reload: () => void;
+}
+/**
+ * @param applicationId Narrows to one application's menu. Omit for the
+ *   cross-application shell — one top-level node per enabled application
+ *   (Doc 05 §4), which is what the admin console renders.
+ */
+export declare function useNavigation(applicationId?: string): UseNavigationResult;
+//# sourceMappingURL=use-navigation.d.ts.map

package/dist/use-navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-navigation.d.ts","sourceRoot":"","sources":["../src/use-navigation.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAK1E,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,UAAU,EAAE,kBAAkB,GAAG,SAAS,CAAC;IAC3C,kFAAkF;IAClF,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAoBzE"}

package/dist/use-navigation.js

@@ -0,0 +1,24 @@
+'use client';
+import { useAuth, useIam } from './iam-provider';
+import { useAsync } from './use-async';
+/**
+ * @param applicationId Narrows to one application's menu. Omit for the
+ *   cross-application shell — one top-level node per enabled application
+ *   (Doc 05 §4), which is what the admin console renders.
+ */
+export function useNavigation(applicationId) {
+    const client = useIam();
+    const { status, subject } = useAuth();
+    const state = useAsync(() => client.navigation.tree(applicationId === undefined ? {} : { applicationId }), 
+    // Re-fetched when the subject changes: the menu is a projection of *their*
+    // grants, so serving the previous user's menu would be both wrong and
+    // alarming.
+    [client, subject?.id, subject?.sessionId, applicationId], { enabled: status === 'authenticated' });
+    return {
+        navigation: state.data,
+        tree: state.data?.tree ?? [],
+        loading: state.loading,
+        error: state.error,
+        reload: state.reload,
+    };
+}

package/dist/use-notices.d.ts

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import { type DescribedError } from './errors';
+export interface Notices {
+    /**
+     * Reports a failure and hands back what it was, so a caller that also wants
+     * to render it inline does not describe it twice.
+     */
+    error: (error: unknown, options?: {
+        title?: string;
+    }) => DescribedError;
+    success: (text: string) => void;
+    info: (text: string) => void;
+    /**
+     * The Doc 09 §4 notice: "after a role/binding change, surface that access
+     * updates may take a few seconds (cache invalidation, Doc 04 §7)".
+     *
+     * Every screen that grants, revokes, or changes what a role carries owes the
+     * admin this sentence. Without it, the admin checks immediately, sees the old
+     * access, and concludes the change did not save — the single most predictable
+     * misreading of a correctly-working cache.
+     */
+    accessChanged: (text?: string) => void;
+    /**
+     * "Are you sure?", resolving to what they chose.
+     *
+     * Here for the same reason `error` is: `Modal.confirm(…)` called statically
+     * renders outside `ConfigProvider`, so it arrives unthemed and, in dark mode,
+     * close to unreadable. `App.useApp()` gives the hooked version, and
+     * `PlantOpsThemeProvider` mounts the `App` it needs.
+     *
+     * A promise rather than an `onOk` callback because the thing a caller does
+     * next is almost always `await` — deactivate, then reload — and threading
+     * that through a callback turns one linear function into two.
+     */
+    confirm: (options: ConfirmOptions) => Promise<boolean>;
+}
+export interface ConfirmOptions {
+    title: string;
+    /** What the action does, and what it does *not* do. Worth writing. */
+    content?: React.ReactNode;
+    okText?: string;
+    cancelText?: string;
+    /** Renders the confirm button in the danger tone. */
+    danger?: boolean;
+}
+export declare function useNotices(): Notices;
+//# sourceMappingURL=use-notices.d.ts.map

package/dist/use-notices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-notices.d.ts","sourceRoot":"","sources":["../src/use-notices.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAE9D,MAAM,WAAW,OAAO;IACtB;;;OAGG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,cAAc,CAAC;IACxE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B;;;;;;;;OAQG;IACH,aAAa,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;;;;;;;;;;;OAWG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,UAAU,IAAI,OAAO,CAkFpC"}

package/dist/use-notices.js

@@ -0,0 +1,60 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Feedback: what the console says after something succeeded, failed, or will
+ * take a moment to take effect.
+ *
+ * Goes through antd's `App.useApp()` hooks rather than the static
+ * `message.error(…)` functions, because the static ones render outside the
+ * React tree and therefore outside `ConfigProvider` — they come out unthemed,
+ * and in dark mode nearly unreadable. `PlantOpsThemeProvider` mounts the `App`
+ * these hooks need.
+ *
+ * ## Why an error toast is a *notification* and a success is a *message*
+ *
+ * A success is an acknowledgement: it needs a second of the user's attention
+ * and then should get out of the way. A failure needs to be read, may carry a
+ * request id worth copying, and must not vanish while the user is still working
+ * out what happened — so it stays until dismissed.
+ */
+import { App } from 'antd';
+import * as React from 'react';
+import { describeError } from './errors';
+export function useNotices() {
+    const { message, modal, notification } = App.useApp();
+    return React.useMemo(() => ({
+        error: (error, options) => {
+            const described = describeError(error);
+            notification.error({
+                message: options?.title ?? described.copy.title,
+                description: (_jsxs(_Fragment, { children: [_jsx("div", { children: described.copy.description }), described.details.length > 0 && (_jsx("ul", { style: { margin: '8px 0 0', paddingInlineStart: 20 }, children: described.details.map((detail) => (_jsxs("li", { children: [_jsx("strong", { children: detail.field }), " \u2014 ", detail.message] }, `${detail.field}:${detail.message}`))) })), described.requestId !== null && (_jsxs("div", { style: { marginBlockStart: 8, fontSize: 12, opacity: 0.75 }, children: ["Request ", described.requestId] }))] })),
+                duration: 0,
+            });
+            return described;
+        },
+        success: (text) => {
+            void message.success(text);
+        },
+        info: (text) => {
+            void message.info(text);
+        },
+        accessChanged: (text) => {
+            void message.info(text ??
+                'Saved. Access changes can take a few seconds to reach every screen.', 4);
+        },
+        confirm: (options) => new Promise((resolve) => {
+            modal.confirm({
+                title: options.title,
+                content: options.content,
+                okText: options.okText ?? 'Confirm',
+                cancelText: options.cancelText ?? 'Cancel',
+                okButtonProps: options.danger === true ? { danger: true } : undefined,
+                onOk: () => resolve(true),
+                // Fires for the cancel button, the close icon and the mask click
+                // alike, so every way out of the dialog resolves rather than
+                // leaving the caller's `await` pending forever.
+                onCancel: () => resolve(false),
+            });
+        }),
+    }), [message, modal, notification]);
+}

package/dist/use-permission.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Permission-aware controls (Doc 09 §4).
+ *
+ * "Buttons/actions the subject lacks permission for are hidden/disabled (UX
+ * only; server enforces)." Every screen session from Session 28 onward uses
+ * this hook, which is why it is here rather than in `admin-web`: gatepass and
+ * visitor hide their buttons with the same code.
+ *
+ * ## Hide or disable?
+ *
+ * Hide by default. A disabled button is a promise that something exists and
+ * could be reached, which invites a support ticket asking how; an absent one
+ * says nothing. Disable when the control's absence would make a layout
+ * incoherent — a toolbar with one button left, a table column of actions where
+ * some rows are actionable and some are not — and give it a `title` saying
+ * which permission is missing, because "greyed out and unexplained" is the
+ * worst of both.
+ *
+ * ## What this is not
+ *
+ * It is not authorisation. `usePermission` reads the resolved grants the server
+ * sent this browser; anything the browser can read, the browser can lie about.
+ * The server checks again on every call (`PermissionGuard`, Session 23) and a
+ * deep link into a hidden screen still 403s (Doc 09 §4). This exists so a user
+ * is not shown doors they cannot open — not so the doors are locked.
+ *
+ * ## While grants are loading
+ *
+ * `usePermission` answers `false` until they arrive. Showing a control and then
+ * removing it is worse than showing it a moment late, and a screen that wants
+ * to hold the whole thing back reads `loading` and renders a skeleton.
+ */
+import type { PermissionKey, ScopePath } from '@plantops/contracts';
+import * as React from 'react';
+export interface PermissionQuery {
+    /**
+     * Restrict the question to a place in the org tree — "may I do this *here*".
+     *
+     * Omit for the broad question ("may I do this anywhere"), which is what a nav
+     * item or a list screen asks: Doc 05 §3 is explicit that visibility is
+     * permission-based, not scope-based, and that scope filters data *within* a
+     * screen.
+     */
+    scopePath?: ScopePath;
+}
+export interface PermissionApi {
+    /** Does the subject hold this permission (optionally, at this node)? */
+    can: (permission: PermissionKey, query?: PermissionQuery) => boolean;
+    /** Any of them — the OR a nav node's `menu_permission` rows express. */
+    canAny: (permissions: readonly PermissionKey[], query?: PermissionQuery) => boolean;
+    /** All of them — for a screen that genuinely needs two. */
+    canAll: (permissions: readonly PermissionKey[], query?: PermissionQuery) => boolean;
+    /**
+     * The minimal covering paths for a permission (Doc 04 §4.1).
+     *
+     * What a screen narrows its query by: "show me the gates I may check in at"
+     * rather than "show me every gate and let the server refuse most of them".
+     */
+    scopesFor: (permission: PermissionKey) => readonly ScopePath[];
+    /** True until the first resolve lands; every answer above is `false` meanwhile. */
+    loading: boolean;
+}
+/** The whole permission surface, for a screen asking several questions. */
+export declare function usePermissions(): PermissionApi;
+/**
+ * One permission, as a boolean — the common case.
+ *
+ * ```tsx
+ * const canCreate = usePermission('iam.client.user.create');
+ * {canCreate && <Button type="primary">Add user</Button>}
+ * ```
+ */
+export declare function usePermission(permission: PermissionKey, query?: PermissionQuery): boolean;
+export interface PermittedProps {
+    /** Held (at `scopePath`, if given) to render `children`. */
+    permission: PermissionKey | readonly PermissionKey[];
+    scopePath?: ScopePath;
+    children: React.ReactNode;
+    /** Rendered instead when the subject lacks it. Usually nothing. */
+    fallback?: React.ReactNode;
+}
+/**
+ * Renders `children` only if the subject holds the permission.
+ *
+ * The JSX form of {@link usePermission}, for a block of markup that would
+ * otherwise need a variable and a conditional. An array means "any of these",
+ * matching the OR semantics `menu_permission` uses for nav visibility
+ * (Doc 05 §3).
+ */
+export declare function Permitted({ permission, scopePath, children, fallback, }: PermittedProps): React.ReactNode;
+//# sourceMappingURL=use-permission.d.ts.map

package/dist/use-permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-permission.d.ts","sourceRoot":"","sources":["../src/use-permission.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAS/B,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,GAAG,EAAE,CAAC,UAAU,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC;IACrE,wEAAwE;IACxE,MAAM,EAAE,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,EAAE,KAAK,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC;IACpF,2DAA2D;IAC3D,MAAM,EAAE,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,EAAE,KAAK,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC;IACpF;;;;;OAKG;IACH,SAAS,EAAE,CAAC,UAAU,EAAE,aAAa,KAAK,SAAS,SAAS,EAAE,CAAC;IAC/D,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,IAAI,aAAa,CAkB9C;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,aAAa,EACzB,KAAK,CAAC,EAAE,eAAe,GACtB,OAAO,CAGT;AAED,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,UAAU,EAAE,aAAa,GAAG,SAAS,aAAa,EAAE,CAAC;IACrD,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,EACxB,UAAU,EACV,SAAS,EACT,QAAQ,EACR,QAAe,GAChB,EAAE,cAAc,GAAG,KAAK,CAAC,SAAS,CAQlC"}

package/dist/use-permission.js

@@ -0,0 +1,48 @@
+'use client';
+import * as React from 'react';
+import { useGrants } from './grants-provider';
+import { holdsPermission, holdsPermissionAt, permissionScopes, } from './scope-coverage';
+/** The whole permission surface, for a screen asking several questions. */
+export function usePermissions() {
+    const { grants, loading } = useGrants();
+    return React.useMemo(() => {
+        const can = (permission, query) => query?.scopePath === undefined
+            ? holdsPermission(grants, permission)
+            : holdsPermissionAt(grants, permission, query.scopePath);
+        return {
+            can,
+            canAny: (permissions, query) => permissions.some((key) => can(key, query)),
+            canAll: (permissions, query) => permissions.length > 0 && permissions.every((key) => can(key, query)),
+            scopesFor: (permission) => permissionScopes(grants, permission),
+            loading,
+        };
+    }, [grants, loading]);
+}
+/**
+ * One permission, as a boolean — the common case.
+ *
+ * ```tsx
+ * const canCreate = usePermission('iam.client.user.create');
+ * {canCreate && <Button type="primary">Add user</Button>}
+ * ```
+ */
+export function usePermission(permission, query) {
+    const { can } = usePermissions();
+    return can(permission, query);
+}
+/**
+ * Renders `children` only if the subject holds the permission.
+ *
+ * The JSX form of {@link usePermission}, for a block of markup that would
+ * otherwise need a variable and a conditional. An array means "any of these",
+ * matching the OR semantics `menu_permission` uses for nav visibility
+ * (Doc 05 §3).
+ */
+export function Permitted({ permission, scopePath, children, fallback = null, }) {
+    const { can, canAny } = usePermissions();
+    const query = scopePath === undefined ? undefined : { scopePath };
+    const allowed = Array.isArray(permission)
+        ? canAny(permission, query)
+        : can(permission, query);
+    return allowed ? children : fallback;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@plantops/web-kit",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@plantops/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "nx": {
+    "tags": [
+      "type:lib",
+      "scope:web"
+    ]
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "antd": "^6.6.1"
+  },
+  "dependencies": {
+    "@plantops/contracts": "^0.1.0",
+    "@plantops/iam-client": "^0.1.0",
+    "@plantops/ui": "^0.1.0",
+    "tslib": "^2.3.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dileepraghumajji/plant-ops.git",
+    "directory": "libs/web-kit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "antd": "^6.6.1"
+  }
+}