@aglyn/shared-ui-jsx 1.0.0-beta.147 → 1.0.0-beta.150

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/shared-ui-jsx",
-  "version": "1.0.0-beta.147",
+  "version": "1.0.0-beta.150",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -25,10 +25,10 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-mdi": "1.0.0-beta.147",
-    "@aglyn/shared-ui-theme": "1.0.0-beta.147",
-    "@aglyn/shared-util-tools": "1.0.0-beta.147",
-    "@aglyn/shared-util-vendor": "1.0.0-beta.147",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.150",
+    "@aglyn/shared-ui-theme": "1.0.0-beta.150",
+    "@aglyn/shared-util-tools": "1.0.0-beta.150",
+    "@aglyn/shared-util-vendor": "1.0.0-beta.150",
     "@mdi/js": "^7.4.47",
     "@swc/helpers": "0.5.23",
     "change-case": "^5.4.4",

package/src/lib/components/read-gated-empty-state.component.d.ts

@@ -0,0 +1,96 @@
+import type { ReactNode } from 'react';
+import type { ReadOutcome } from '../utils/read-outcome';
+export interface ReadGatedEmptyStateProps {
+    /** MDI path (e.g. `ICON_VARIANT_HOST_GROUP.path`) shown above the title. */
+    iconPath?: string;
+    /** Headline — the one-line "what this is / what to do" message. */
+    title: ReactNode;
+    /** Supporting copy under the title; keep it to a sentence or two. */
+    description?: ReactNode;
+    /** Primary call to action (usually a `<Button>`), rendered below the copy. */
+    action?: ReactNode;
+    /**
+     * Did the read behind this list actually succeed? REQUIRED, and
+     * deliberately not defaulted (AGL-1066).
+     *
+     * A list is empty for three different reasons and only one of them is
+     * "there is nothing here". Passing `loaded` is an assertion that the read
+     * reached the server and came back with zero rows; anything else renders
+     * the loading or degraded branch below and `title`/`description`/`action`
+     * are never shown. See `utils/read-outcome`.
+     */
+    read: ReadOutcome;
+    /**
+     * What could not be loaded, for the degraded copy — a lower-case noun
+     * phrase in the customer's terms: `'your sites'`, `'your workspaces'`.
+     */
+    subject?: string;
+    /** Re-runs the failed read. Omit only when nothing can retry it. */
+    onRetry?: () => void;
+    /**
+     * An action for the degraded branch that OUTRANKS the retry button
+     * (AGL-3080) — for a caller that knows retrying cannot work.
+     *
+     * The case it exists for is the console's stale session: every server read
+     * is being refused, so "Try again" is an invitation to fail, and what the
+     * reader needs is the way back into the sign-in dialog. Only the app knows
+     * that, because only the app holds the session store — which is exactly why
+     * this is a prop rather than a branch in here. A caller that passes nothing
+     * gets the retry button, which is the right answer for every read whose
+     * failure is not the session.
+     */
+    degradedAction?: ReactNode;
+}
+/**
+ * Reusable zero-state block: a centered icon, title, supporting copy and an
+ * optional call to action inside the standard `CardDisplay` framing. Use it
+ * wherever a list/grid can legitimately be empty (no sites yet, no org yet,
+ * empty media library) instead of leaving a blank content area.
+ *
+ * Distinct from {@link EmptyState} in this same library, which is the
+ * illustrated "nothing here" block for a panel that has no read behind it.
+ * This one is for a LIST, and the difference that matters is the gate.
+ *
+ * ## Lives here so a plugin can state the rule too (AGL-3080)
+ *
+ * It was the console's, at `apps/console/components/empty-state.component`,
+ * and the rule below is not an app's rule — the marketplace's own licence
+ * list asserts "this workspace holds no licenses" off the same three-valued
+ * evidence. A plugin may not import an app, so the choice was to move this or
+ * to let each plugin hand-roll a zero-state that forgets the gate, which is
+ * the defect AGL-1066 already found in every console surface that had one.
+ * The console keeps a wrapper at the old path that supplies
+ * {@link ReadGatedEmptyStateProps.degradedAction}, so its own call sites are
+ * unchanged.
+ *
+ * ## The zero-state is GATED, not merely offered (AGL-1066, AGL-1062)
+ *
+ * "No sites yet — Create a site to start building" is a statement of fact
+ * about someone's account, and it was reachable from a read that never
+ * reached the server: a stale session denies every server read while
+ * `persistentLocalCache` keeps listeners painting, so the list rendered, then
+ * emptied, then asserted the emptiness. On a page whose zero-state carries a
+ * **Create site** button that is not just wrong, it invites a customer to
+ * rebuild sites they still own.
+ *
+ * So the copy and the call to action live behind `read === 'loaded'`. This is
+ * a required prop rather than a caller-side `if` because the caller-side `if`
+ * is exactly what every surface forgot; putting it here means a new list
+ * cannot render a zero-state without answering the question first.
+ *
+ * ## The degraded branch says only what a list can know (AGL-2486)
+ *
+ * It used to end "if the banner above asks you to sign in again, that fixes
+ * it". There is no banner above any more — a stale session opens the re-auth
+ * dialog directly — and pointing at it was already the weaker half of a
+ * message told twice. What survives is the part only this surface knows:
+ * THIS list is incomplete, and nothing has been deleted. The diagnosis stays
+ * where the evidence is; a list that guessed at it would be the AGL-1179
+ * mistake at the surface instead of in a log.
+ */
+export declare function ReadGatedEmptyState({ iconPath, title, description, action, read, subject, onRetry, degradedAction, }: ReadGatedEmptyStateProps): import("react").JSX.Element;
+export declare namespace ReadGatedEmptyState {
+    var displayName: string;
+    var aglyn: boolean;
+}
+export default ReadGatedEmptyState;

package/src/lib/components/read-gated-empty-state.component.js

@@ -0,0 +1,138 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ 'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Alert, Box, Button, CircularProgress, Stack, Typography } from "@mui/material";
+import CardDisplay from "./card-display.js";
+import MdiIcon from "./mdi-icon/mdi-icon.js";
+/**
+ * Reusable zero-state block: a centered icon, title, supporting copy and an
+ * optional call to action inside the standard `CardDisplay` framing. Use it
+ * wherever a list/grid can legitimately be empty (no sites yet, no org yet,
+ * empty media library) instead of leaving a blank content area.
+ *
+ * Distinct from {@link EmptyState} in this same library, which is the
+ * illustrated "nothing here" block for a panel that has no read behind it.
+ * This one is for a LIST, and the difference that matters is the gate.
+ *
+ * ## Lives here so a plugin can state the rule too (AGL-3080)
+ *
+ * It was the console's, at `apps/console/components/empty-state.component`,
+ * and the rule below is not an app's rule — the marketplace's own licence
+ * list asserts "this workspace holds no licenses" off the same three-valued
+ * evidence. A plugin may not import an app, so the choice was to move this or
+ * to let each plugin hand-roll a zero-state that forgets the gate, which is
+ * the defect AGL-1066 already found in every console surface that had one.
+ * The console keeps a wrapper at the old path that supplies
+ * {@link ReadGatedEmptyStateProps.degradedAction}, so its own call sites are
+ * unchanged.
+ *
+ * ## The zero-state is GATED, not merely offered (AGL-1066, AGL-1062)
+ *
+ * "No sites yet — Create a site to start building" is a statement of fact
+ * about someone's account, and it was reachable from a read that never
+ * reached the server: a stale session denies every server read while
+ * `persistentLocalCache` keeps listeners painting, so the list rendered, then
+ * emptied, then asserted the emptiness. On a page whose zero-state carries a
+ * **Create site** button that is not just wrong, it invites a customer to
+ * rebuild sites they still own.
+ *
+ * So the copy and the call to action live behind `read === 'loaded'`. This is
+ * a required prop rather than a caller-side `if` because the caller-side `if`
+ * is exactly what every surface forgot; putting it here means a new list
+ * cannot render a zero-state without answering the question first.
+ *
+ * ## The degraded branch says only what a list can know (AGL-2486)
+ *
+ * It used to end "if the banner above asks you to sign in again, that fixes
+ * it". There is no banner above any more — a stale session opens the re-auth
+ * dialog directly — and pointing at it was already the weaker half of a
+ * message told twice. What survives is the part only this surface knows:
+ * THIS list is incomplete, and nothing has been deleted. The diagnosis stays
+ * where the evidence is; a list that guessed at it would be the AGL-1179
+ * mistake at the surface instead of in a log.
+ */ export function ReadGatedEmptyState({ iconPath, title, description, action, read, subject = 'this list', onRetry, degradedAction }) {
+    // A read still in flight is not an answer. Rendering the frame with a
+    // spinner keeps the page from jumping when the rows arrive, and — more to
+    // the point — keeps the zero-state's sentence out of the load window.
+    if (read === 'loading') {
+        return /*#__PURE__*/ _jsx(CardDisplay, {
+            contentGutterX: true,
+            contentGutterY: true,
+            children: /*#__PURE__*/ _jsx(Box, {
+                sx: {
+                    display: 'flex',
+                    justifyContent: 'center',
+                    py: 6
+                },
+                children: /*#__PURE__*/ _jsx(CircularProgress, {
+                    "aria-label": `Loading ${subject}`
+                })
+            })
+        });
+    }
+    if (read === 'unavailable') {
+        return /*#__PURE__*/ _jsx(Alert, {
+            severity: "warning",
+            action: degradedAction != null ? degradedAction : onRetry ? /*#__PURE__*/ _jsx(Button, {
+                color: "inherit",
+                size: "small",
+                onClick: onRetry,
+                children: 'Try again'
+            }) : null,
+            children: `${subject.charAt(0).toUpperCase()}${subject.slice(1)} could not be ` + 'loaded, so this list is incomplete. Nothing has been deleted.'
+        });
+    }
+    return /*#__PURE__*/ _jsx(CardDisplay, {
+        contentGutterX: true,
+        contentGutterY: true,
+        children: /*#__PURE__*/ _jsxs(Stack, {
+            spacing: 2,
+            sx: {
+                alignItems: 'center',
+                textAlign: 'center',
+                py: 6,
+                px: 2
+            },
+            children: [
+                iconPath ? /*#__PURE__*/ _jsx(MdiIcon, {
+                    color: "primary",
+                    fontSize: "large",
+                    path: iconPath
+                }) : null,
+                /*#__PURE__*/ _jsx(Typography, {
+                    variant: "h6",
+                    children: title
+                }),
+                description ? /*#__PURE__*/ _jsx(Typography, {
+                    color: "textSecondary",
+                    sx: {
+                        maxWidth: 440
+                    },
+                    children: description
+                }) : null,
+                action ? /*#__PURE__*/ _jsx("div", {
+                    children: action
+                }) : null
+            ]
+        })
+    });
+}
+ReadGatedEmptyState.displayName = 'ReadGatedEmptyState';
+ReadGatedEmptyState.aglyn = true;
+export default ReadGatedEmptyState;
+
+//# sourceMappingURL=read-gated-empty-state.component.js.map

package/src/lib/components/read-gated-empty-state.component.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/jsx/src/lib/components/read-gated-empty-state.component.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n'use client'\n\nimport { Alert, Box, Button, CircularProgress, Stack, Typography } from '@mui/material'\nimport type { ReactNode } from 'react'\nimport CardDisplay from './card-display'\nimport MdiIcon from './mdi-icon/mdi-icon'\nimport type { ReadOutcome } from '../utils/read-outcome'\n\nexport interface ReadGatedEmptyStateProps {\n  /** MDI path (e.g. `ICON_VARIANT_HOST_GROUP.path`) shown above the title. */\n  iconPath?: string\n  /** Headline — the one-line \"what this is / what to do\" message. */\n  title: ReactNode\n  /** Supporting copy under the title; keep it to a sentence or two. */\n  description?: ReactNode\n  /** Primary call to action (usually a `<Button>`), rendered below the copy. */\n  action?: ReactNode\n  /**\n   * Did the read behind this list actually succeed? REQUIRED, and\n   * deliberately not defaulted (AGL-1066).\n   *\n   * A list is empty for three different reasons and only one of them is\n   * \"there is nothing here\". Passing `loaded` is an assertion that the read\n   * reached the server and came back with zero rows; anything else renders\n   * the loading or degraded branch below and `title`/`description`/`action`\n   * are never shown. See `utils/read-outcome`.\n   */\n  read: ReadOutcome\n  /**\n   * What could not be loaded, for the degraded copy — a lower-case noun\n   * phrase in the customer's terms: `'your sites'`, `'your workspaces'`.\n   */\n  subject?: string\n  /** Re-runs the failed read. Omit only when nothing can retry it. */\n  onRetry?: () => void\n  /**\n   * An action for the degraded branch that OUTRANKS the retry button\n   * (AGL-3080) — for a caller that knows retrying cannot work.\n   *\n   * The case it exists for is the console's stale session: every server read\n   * is being refused, so \"Try again\" is an invitation to fail, and what the\n   * reader needs is the way back into the sign-in dialog. Only the app knows\n   * that, because only the app holds the session store — which is exactly why\n   * this is a prop rather than a branch in here. A caller that passes nothing\n   * gets the retry button, which is the right answer for every read whose\n   * failure is not the session.\n   */\n  degradedAction?: ReactNode\n}\n\n/**\n * Reusable zero-state block: a centered icon, title, supporting copy and an\n * optional call to action inside the standard `CardDisplay` framing. Use it\n * wherever a list/grid can legitimately be empty (no sites yet, no org yet,\n * empty media library) instead of leaving a blank content area.\n *\n * Distinct from {@link EmptyState} in this same library, which is the\n * illustrated \"nothing here\" block for a panel that has no read behind it.\n * This one is for a LIST, and the difference that matters is the gate.\n *\n * ## Lives here so a plugin can state the rule too (AGL-3080)\n *\n * It was the console's, at `apps/console/components/empty-state.component`,\n * and the rule below is not an app's rule — the marketplace's own licence\n * list asserts \"this workspace holds no licenses\" off the same three-valued\n * evidence. A plugin may not import an app, so the choice was to move this or\n * to let each plugin hand-roll a zero-state that forgets the gate, which is\n * the defect AGL-1066 already found in every console surface that had one.\n * The console keeps a wrapper at the old path that supplies\n * {@link ReadGatedEmptyStateProps.degradedAction}, so its own call sites are\n * unchanged.\n *\n * ## The zero-state is GATED, not merely offered (AGL-1066, AGL-1062)\n *\n * \"No sites yet — Create a site to start building\" is a statement of fact\n * about someone's account, and it was reachable from a read that never\n * reached the server: a stale session denies every server read while\n * `persistentLocalCache` keeps listeners painting, so the list rendered, then\n * emptied, then asserted the emptiness. On a page whose zero-state carries a\n * **Create site** button that is not just wrong, it invites a customer to\n * rebuild sites they still own.\n *\n * So the copy and the call to action live behind `read === 'loaded'`. This is\n * a required prop rather than a caller-side `if` because the caller-side `if`\n * is exactly what every surface forgot; putting it here means a new list\n * cannot render a zero-state without answering the question first.\n *\n * ## The degraded branch says only what a list can know (AGL-2486)\n *\n * It used to end \"if the banner above asks you to sign in again, that fixes\n * it\". There is no banner above any more — a stale session opens the re-auth\n * dialog directly — and pointing at it was already the weaker half of a\n * message told twice. What survives is the part only this surface knows:\n * THIS list is incomplete, and nothing has been deleted. The diagnosis stays\n * where the evidence is; a list that guessed at it would be the AGL-1179\n * mistake at the surface instead of in a log.\n */\nexport function ReadGatedEmptyState({\n  iconPath,\n  title,\n  description,\n  action,\n  read,\n  subject = 'this list',\n  onRetry,\n  degradedAction,\n}: ReadGatedEmptyStateProps) {\n  // A read still in flight is not an answer. Rendering the frame with a\n  // spinner keeps the page from jumping when the rows arrive, and — more to\n  // the point — keeps the zero-state's sentence out of the load window.\n  if (read === 'loading') {\n    return (\n      <CardDisplay contentGutterX contentGutterY>\n        <Box sx={{ display: 'flex', justifyContent: 'center', py: 6 }}>\n          <CircularProgress aria-label={`Loading ${subject}`} />\n        </Box>\n      </CardDisplay>\n    )\n  }\n\n  if (read === 'unavailable') {\n    return (\n      <Alert\n        severity=\"warning\"\n        action={\n          degradedAction ??\n          (onRetry ? (\n            <Button color=\"inherit\" size=\"small\" onClick={onRetry}>\n              {'Try again'}\n            </Button>\n          ) : null)\n        }\n      >\n        {`${subject.charAt(0).toUpperCase()}${subject.slice(1)} could not be ` +\n          'loaded, so this list is incomplete. Nothing has been deleted.'}\n      </Alert>\n    )\n  }\n\n  return (\n    <CardDisplay contentGutterX contentGutterY>\n      <Stack\n        spacing={2}\n        sx={{ alignItems: 'center', textAlign: 'center', py: 6, px: 2 }}\n      >\n        {iconPath ? (\n          <MdiIcon color=\"primary\" fontSize=\"large\" path={iconPath} />\n        ) : null}\n        <Typography variant=\"h6\">{title}</Typography>\n        {description ? (\n          <Typography\n            color=\"textSecondary\"\n            sx={{ maxWidth: 440 }}\n          >\n            {description}\n          </Typography>\n        ) : null}\n        {action ? <div>{action}</div> : null}\n      </Stack>\n    </CardDisplay>\n  )\n}\n\nReadGatedEmptyState.displayName = 'ReadGatedEmptyState'\nReadGatedEmptyState.aglyn = true\n\nexport default ReadGatedEmptyState\n"],"names":["Alert","Box","Button","CircularProgress","Stack","Typography","CardDisplay","MdiIcon","ReadGatedEmptyState","iconPath","title","description","action","read","subject","onRetry","degradedAction","contentGutterX","contentGutterY","sx","display","justifyContent","py","aria-label","severity","color","size","onClick","charAt","toUpperCase","slice","spacing","alignItems","textAlign","px","fontSize","path","variant","maxWidth","div","displayName","aglyn"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;;AAEA,SAASA,KAAK,EAAEC,GAAG,EAAEC,MAAM,EAAEC,gBAAgB,EAAEC,KAAK,EAAEC,UAAU,QAAQ,gBAAe;AAEvF,OAAOC,iBAAiB,oBAAgB;AACxC,OAAOC,aAAa,yBAAqB;AA6CzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CC,GACD,OAAO,SAASC,oBAAoB,EAClCC,QAAQ,EACRC,KAAK,EACLC,WAAW,EACXC,MAAM,EACNC,IAAI,EACJC,UAAU,WAAW,EACrBC,OAAO,EACPC,cAAc,EACW;IACzB,sEAAsE;IACtE,0EAA0E;IAC1E,sEAAsE;IACtE,IAAIH,SAAS,WAAW;QACtB,qBACE,KAACP;YAAYW,cAAc;YAACC,cAAc;sBACxC,cAAA,KAACjB;gBAAIkB,IAAI;oBAAEC,SAAS;oBAAQC,gBAAgB;oBAAUC,IAAI;gBAAE;0BAC1D,cAAA,KAACnB;oBAAiBoB,cAAY,CAAC,QAAQ,EAAET,SAAS;;;;IAI1D;IAEA,IAAID,SAAS,eAAe;QAC1B,qBACE,KAACb;YACCwB,UAAS;YACTZ,MAAM,EACJI,yBAAAA,iBACCD,wBACC,KAACb;gBAAOuB,OAAM;gBAAUC,MAAK;gBAAQC,SAASZ;0BAC3C;iBAED;sBAGL,GAAGD,QAAQc,MAAM,CAAC,GAAGC,WAAW,KAAKf,QAAQgB,KAAK,CAAC,GAAG,cAAc,CAAC,GACpE;;IAGR;IAEA,qBACE,KAACxB;QAAYW,cAAc;QAACC,cAAc;kBACxC,cAAA,MAACd;YACC2B,SAAS;YACTZ,IAAI;gBAAEa,YAAY;gBAAUC,WAAW;gBAAUX,IAAI;gBAAGY,IAAI;YAAE;;gBAE7DzB,yBACC,KAACF;oBAAQkB,OAAM;oBAAUU,UAAS;oBAAQC,MAAM3B;qBAC9C;8BACJ,KAACJ;oBAAWgC,SAAQ;8BAAM3B;;gBACzBC,4BACC,KAACN;oBACCoB,OAAM;oBACNN,IAAI;wBAAEmB,UAAU;oBAAI;8BAEnB3B;qBAED;gBACHC,uBAAS,KAAC2B;8BAAK3B;qBAAgB;;;;AAIxC;AAEAJ,oBAAoBgC,WAAW,GAAG;AAClChC,oBAAoBiC,KAAK,GAAG;AAE5B,eAAejC,oBAAmB"}

package/src/lib/utils/read-outcome.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Did the read that produced this list actually SUCCEED? (AGL-1066)
+ *
+ * A zero-state is a claim about the customer's DATA — "you have no sites",
+ * "your library is empty". A refused or unfinished read supports no such
+ * claim; all it establishes is that we could not look. `media-library` states
+ * the rule at its own call site (AGL-1062): *"no media" is a claim about the
+ * library, and a failed read is a claim about us.* This module is that rule
+ * made shared, because the console had it in exactly one place and every
+ * other list surface reached the opposite conclusion from the same evidence.
+ *
+ * It lives in `shared-ui-jsx` rather than the console (AGL-3080) because a
+ * PLUGIN's list surface answers the same question and cannot import an app.
+ * There is no UI here and there never was — the rule is about evidence, not
+ * about pixels — so the only thing the move changes is who may state it.
+ *
+ * ## Why a three-valued type and not a boolean
+ *
+ * Because two of the three states produce an empty array, and only one of
+ * them licenses the sentence. `loading` and `unavailable` both look like
+ * `items.length === 0` from the outside, which is precisely how a load window
+ * and a dead session both rendered as "No sites yet".
+ *
+ * ## Why it must be passed EXPLICITLY, and never defaulted
+ *
+ * A default answers the question for a caller who never asked it. That is the
+ * AGL-1380 bug shape — a loading default that reads as data — and it is the
+ * one this type exists to make unrepresentable. `EmptyState` therefore takes
+ * `read` as a REQUIRED prop: a surface cannot render a zero-state without
+ * first stating, in code, that its read succeeded.
+ *
+ * ## Reading a hook's state
+ *
+ * The console's list hooks converged on `{ ready, error }` (`useOrgHosts`,
+ * `useOrgScope`), where `error` means "this read gave up", not "this read
+ * returned nothing". {@link readOutcome} is the one translation from that
+ * pair, so the precedence — an error outranks a pending read — is decided
+ * once instead of at every call site.
+ */
+/**
+ * `loaded` is the ONLY value that licenses a zero-state. The other two mean
+ * "the list is empty because we do not know", which is a different sentence
+ * and a different UI.
+ */
+export type ReadOutcome = 'loading' | 'loaded' | 'unavailable';
+export interface ReadState {
+    /** The read settled — succeeded or gave up. */
+    ready: boolean;
+    /** The read gave up. Says nothing about what exists. */
+    error: boolean;
+}
+/**
+ * Translate a list hook's `{ ready, error }` into a {@link ReadOutcome}.
+ *
+ * `=== true` / `=== false` rather than truthiness on purpose:
+ * `strictNullChecks` is off repo-wide, so an `undefined` from a hook that has
+ * not adopted the pair yet must fall to `loading` — the conservative value —
+ * instead of silently reading as "loaded, and empty".
+ *
+ * `error` is checked first: a read that gave up is not still in flight, and a
+ * hook that latches `ready` alongside `error` (both of ours do) would
+ * otherwise be ambiguous.
+ */
+export declare function readOutcome(state: Partial<ReadState> | undefined): ReadOutcome;
+export default readOutcome;

package/src/lib/utils/read-outcome.js

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Did the read that produced this list actually SUCCEED? (AGL-1066)
+ *
+ * A zero-state is a claim about the customer's DATA — "you have no sites",
+ * "your library is empty". A refused or unfinished read supports no such
+ * claim; all it establishes is that we could not look. `media-library` states
+ * the rule at its own call site (AGL-1062): *"no media" is a claim about the
+ * library, and a failed read is a claim about us.* This module is that rule
+ * made shared, because the console had it in exactly one place and every
+ * other list surface reached the opposite conclusion from the same evidence.
+ *
+ * It lives in `shared-ui-jsx` rather than the console (AGL-3080) because a
+ * PLUGIN's list surface answers the same question and cannot import an app.
+ * There is no UI here and there never was — the rule is about evidence, not
+ * about pixels — so the only thing the move changes is who may state it.
+ *
+ * ## Why a three-valued type and not a boolean
+ *
+ * Because two of the three states produce an empty array, and only one of
+ * them licenses the sentence. `loading` and `unavailable` both look like
+ * `items.length === 0` from the outside, which is precisely how a load window
+ * and a dead session both rendered as "No sites yet".
+ *
+ * ## Why it must be passed EXPLICITLY, and never defaulted
+ *
+ * A default answers the question for a caller who never asked it. That is the
+ * AGL-1380 bug shape — a loading default that reads as data — and it is the
+ * one this type exists to make unrepresentable. `EmptyState` therefore takes
+ * `read` as a REQUIRED prop: a surface cannot render a zero-state without
+ * first stating, in code, that its read succeeded.
+ *
+ * ## Reading a hook's state
+ *
+ * The console's list hooks converged on `{ ready, error }` (`useOrgHosts`,
+ * `useOrgScope`), where `error` means "this read gave up", not "this read
+ * returned nothing". {@link readOutcome} is the one translation from that
+ * pair, so the precedence — an error outranks a pending read — is decided
+ * once instead of at every call site.
+ */ /**
+ * `loaded` is the ONLY value that licenses a zero-state. The other two mean
+ * "the list is empty because we do not know", which is a different sentence
+ * and a different UI.
+ */ /**
+ * Translate a list hook's `{ ready, error }` into a {@link ReadOutcome}.
+ *
+ * `=== true` / `=== false` rather than truthiness on purpose:
+ * `strictNullChecks` is off repo-wide, so an `undefined` from a hook that has
+ * not adopted the pair yet must fall to `loading` — the conservative value —
+ * instead of silently reading as "loaded, and empty".
+ *
+ * `error` is checked first: a read that gave up is not still in flight, and a
+ * hook that latches `ready` alongside `error` (both of ours do) would
+ * otherwise be ambiguous.
+ */ export function readOutcome(state) {
+    if ((state == null ? void 0 : state.error) === true) return 'unavailable';
+    if ((state == null ? void 0 : state.ready) === true) return 'loaded';
+    return 'loading';
+}
+export default readOutcome;
+
+//# sourceMappingURL=read-outcome.js.map

package/src/lib/utils/read-outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/jsx/src/lib/utils/read-outcome.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Did the read that produced this list actually SUCCEED? (AGL-1066)\n *\n * A zero-state is a claim about the customer's DATA — \"you have no sites\",\n * \"your library is empty\". A refused or unfinished read supports no such\n * claim; all it establishes is that we could not look. `media-library` states\n * the rule at its own call site (AGL-1062): *\"no media\" is a claim about the\n * library, and a failed read is a claim about us.* This module is that rule\n * made shared, because the console had it in exactly one place and every\n * other list surface reached the opposite conclusion from the same evidence.\n *\n * It lives in `shared-ui-jsx` rather than the console (AGL-3080) because a\n * PLUGIN's list surface answers the same question and cannot import an app.\n * There is no UI here and there never was — the rule is about evidence, not\n * about pixels — so the only thing the move changes is who may state it.\n *\n * ## Why a three-valued type and not a boolean\n *\n * Because two of the three states produce an empty array, and only one of\n * them licenses the sentence. `loading` and `unavailable` both look like\n * `items.length === 0` from the outside, which is precisely how a load window\n * and a dead session both rendered as \"No sites yet\".\n *\n * ## Why it must be passed EXPLICITLY, and never defaulted\n *\n * A default answers the question for a caller who never asked it. That is the\n * AGL-1380 bug shape — a loading default that reads as data — and it is the\n * one this type exists to make unrepresentable. `EmptyState` therefore takes\n * `read` as a REQUIRED prop: a surface cannot render a zero-state without\n * first stating, in code, that its read succeeded.\n *\n * ## Reading a hook's state\n *\n * The console's list hooks converged on `{ ready, error }` (`useOrgHosts`,\n * `useOrgScope`), where `error` means \"this read gave up\", not \"this read\n * returned nothing\". {@link readOutcome} is the one translation from that\n * pair, so the precedence — an error outranks a pending read — is decided\n * once instead of at every call site.\n */\n\n/**\n * `loaded` is the ONLY value that licenses a zero-state. The other two mean\n * \"the list is empty because we do not know\", which is a different sentence\n * and a different UI.\n */\nexport type ReadOutcome = 'loading' | 'loaded' | 'unavailable'\n\nexport interface ReadState {\n  /** The read settled — succeeded or gave up. */\n  ready: boolean\n  /** The read gave up. Says nothing about what exists. */\n  error: boolean\n}\n\n/**\n * Translate a list hook's `{ ready, error }` into a {@link ReadOutcome}.\n *\n * `=== true` / `=== false` rather than truthiness on purpose:\n * `strictNullChecks` is off repo-wide, so an `undefined` from a hook that has\n * not adopted the pair yet must fall to `loading` — the conservative value —\n * instead of silently reading as \"loaded, and empty\".\n *\n * `error` is checked first: a read that gave up is not still in flight, and a\n * hook that latches `ready` alongside `error` (both of ours do) would\n * otherwise be ambiguous.\n */\nexport function readOutcome(state: Partial<ReadState> | undefined): ReadOutcome {\n  if (state?.error === true) return 'unavailable'\n  if (state?.ready === true) return 'loaded'\n  return 'loading'\n}\n\nexport default readOutcome\n"],"names":["readOutcome","state","error","ready"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCC,GAED;;;;CAIC,GAUD;;;;;;;;;;;CAWC,GACD,OAAO,SAASA,YAAYC,KAAqC;IAC/D,IAAIA,CAAAA,yBAAAA,MAAOC,KAAK,MAAK,MAAM,OAAO;IAClC,IAAID,CAAAA,yBAAAA,MAAOE,KAAK,MAAK,MAAM,OAAO;IAClC,OAAO;AACT;AAEA,eAAeH,YAAW"}