@gravitee/gamma-lib-observability 6.2.1 → 6.3.0-feat-obs-170-consistent-failure-states.1f5f951

package/INTEGRATION.md

@@ -227,7 +227,7 @@ The lib is a **contributor**: it ships routes, nav and route metadata; the host
 - [ ] **Query client** — wrap the app in a single `QueryClientProvider` (shared singleton under Module Federation).
 - [ ] **Authenticated HTTP** — pass the `http` prop (or an `HttpProvider`) once so every internal source is authenticated (see [Authenticated HTTP](#authenticated-http-http-prop)).
 - [ ] **Mount routes** — `<Route path="observe/*" element={<observability.Routes … />} />`.
-- [ ] **Register navigation** — add `observability.navGroup` to your sidenav groups.
+- [ ] **Register navigation** — add `observability.navGroup` to your sidenav groups, or `observability.navGroupFor(capabilities)` once you know the user's capabilities (see [Sidebar navigation](#sidebar-navigation)).
 - [ ] **Active nav key** — resolve it with `observability.resolveRouteKey(pathname)` (see [Active nav key detection](#active-nav-key-detection)).
 - [ ] **Breadcrumbs** — build them from `observability.breadcrumbSegments(activeNavKey)` (see [Breadcrumbs](#breadcrumbs)).
 - [ ] **Merge route keys / routes** — spread `observability.routeKeys` / `observability.routes` into the module's own (see [Merging route keys and routes](#merging-route-keys-and-routes)).
@@ -943,6 +943,12 @@ const { navGroup } = observability;
 
 Only enabled features appear in `navGroup.items`.
 
+A host that knows its user's capabilities lists `navGroupFor(capabilities)` instead: the same group, without the sections the user may not read. It reads the same keys the routes mount on (`observability.dashboards.read`, `observability.logs.read`, `observability.traces.read`), so a section is never in the nav without being on screen. `navGroup` itself is unchanged and still lists every enabled feature.
+
+```ts
+const navGroup = observability.navGroupFor(capabilities);
+```
+
 Override titles and icons via `nav.overrides`:
 
 ```ts
@@ -1071,13 +1077,13 @@ const capabilities: DashboardCapabilities = {
 | `observability.logs.read`        | Shows the logs explorer and log detail routes, when logs are enabled.                                                                                                                                                                                                        |
 | `observability.traces.read`      | Shows the traces explorer and trace detail routes, when tracing is enabled.                                                                                                                                                                                                  |
 
-Every declared key is enforced: a section is on screen when its feature flag **and** its read capability both hold, and the catch-all redirect only targets sections that are actually mounted. Capabilities gate `ObservabilityRoutes`; components imported and mounted directly (`DashboardView`, `WidgetItem`, `LogsExplorerPage`, `TracingScreen`, …) are the host's own composition and are not gated, except where a prop says so (`DashboardView`'s `editable` requires the write capability).
+Every declared key is enforced: a section is on screen when its feature flag **and** its read capability both hold, and the catch-all redirect only targets sections that are actually mounted. A link to a section the host enabled but the reader may not read (a shared link, a bookmark) shows "No access to logs" (or traces, or dashboards) with "Ask an administrator for access." and a button to the first section they can read, instead of redirecting without a word; nothing is asked of the server. When no enabled section is readable at all, the page says "No access to observability". A link to a section the host did not enable, or to an unknown path, still redirects to the first readable section. Capabilities gate `ObservabilityRoutes`; components imported and mounted directly (`DashboardView`, `WidgetItem`, `LogsExplorerPage`, `TracingScreen`, …) are the host's own composition and are not gated, except where a prop says so (`DashboardView`'s `editable` requires the write capability).
 
 **Default behavior:** When no `CapabilityProvider` is present, all capabilities default to `false` (secure default). For initial integration without RBAC, pass all relevant capabilities as `true`.
 
 > **Migration note (breaking, v3).** Before v3, `observability.logs.read` and `observability.dashboards.read` were declared and documented but never read as route gates: the logs and dashboards sections were mounted on their feature flags alone. They now gate their routes exactly as `observability.traces.read` always has. A host that enables these features without declaring the read capabilities (or without any `CapabilityProvider`) loses the sections on upgrade — declare the keys `true` to keep the previous behavior. Capabilities describe what the host allows; per-user backend refusals are handled separately, see [Backend refusals](#backend-refusals-403).
 >
-> The sidebar entries from `defineObservabilityFeatures().navGroup` are built from the feature config alone — capabilities live in React context and are not visible there. A host that disables a capability should filter the matching nav item itself; a link left in place degrades safely (it lands on the first visible section).
+> The sidebar entries from `defineObservabilityFeatures().navGroup` are built from the feature config alone — capabilities live in React context and are not visible there. A host that knows its user's capabilities lists `navGroupFor(capabilities)` instead, which leaves out the sections the routes would not mount (see [Sidebar navigation](#sidebar-navigation)); a link left in place says the reader has no access to that section, with a way to one they can read.
 
 ---
 
@@ -1275,6 +1281,63 @@ Refusals are remembered **per verb family** (read, write), not per operation: on
 
 A store that enforces permissions must reject with `DashboardForbiddenError` (or a `status: 403` error) for the degradation to engage — see the port's documentation. Only a 403 earns the quiet degradation: any other listing failure is a fault, not a designed experience (its current silence on the list is a known gap).
 
+#### Refused data (logs, traces, analytics, filters)
+
+The same rule holds for the data behind the screens. The built-in HTTP sources reject a failed call with an `ObservabilityHttpError` that keeps the HTTP `status`; `isForbiddenError(error)` tells a refusal from any other failure, reading the status from the shape so a host source's own errors (anything with `status: 403`) count too. A refusal is named where it happened, never offered a retry, and never shown as "no data". Every refusal uses the same component, `AccessDeniedState`, so the reader is guided the same way everywhere: the title names the data, and the description is always "Ask an administrator for access." Its `compact` variant (a chart's area, dashboard tiles) drops the description by itself when its box is too short; its `inline` variant fits next to a control.
+
+| Where                          | On a refusal                                                                                               | On any other failure                                      |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| Logs page, logs table          | Headers kept; "No access to logs" where "No logs found" would be                                           | "Couldn't load logs" in the empty rows                    |
+| Logs page, chart               | "No access to analytics" in the chart's area, at its height                                                | "Couldn't load analytics" in its area                     |
+| Logs page, both refused        | One "No access to logs and analytics" for the page, in place of chart and table; no filters or time range  | Both failed: one card over the faint page, with Try again |
+| Log detail chart               | "No access to analytics" in the chart's place                                                              | "Couldn't load analytics" in its place                    |
+| Traces table                   | Headers kept; "No access to traces" in the empty rows; no filters or time range                            | "Couldn't load traces" with Try again                     |
+| Log and trace detail           | "No access to this log" / "No access to this trace"                                                        | "Couldn't load this log" with Try again                   |
+| A dashboard widget             | "No access to analytics" (or logs, traces) in that tile only, when the dashboard is mixed                  | "Couldn't load analytics" in that tile                    |
+| A whole dashboard              | One state named after the refused kinds, in place of the widget grid; title kept, no filters or time range | All failed: one card over the faint grid, with Try again  |
+| Filter bar (both filter lists) | "No access to filters." inline, next to the disabled "Add filter"                                          | "Couldn't load filters." with Try again                   |
+| Tracing API picker (paginated) | "No access to APIs." inline, next to the field                                                             | "Couldn't load APIs." with Try again                      |
+| Filter values                  | Falls back to typing the value, as for any listing failure                                                 | Same (unchanged)                                          |
+
+**404 that may stand for a refusal.** The trace search, trace detail and log detail endpoints answer 404 for an API the reader may not see, so that its existence does not leak. These three screens keep that promise: on a 404 (`isNotFoundError`), and on a log detail the source reports as missing, they show "API not found, or you don't have access" (in the traces table), "Trace not found, …" or "Log not found, …", with "Check the link, or ask an administrator for access.", and no retry. A 404 anywhere else keeps its existing handling.
+
+**Wording.** Every state names the kind of data refused, "No access to analytics", "No access to logs" or "No access to traces", and lists every kind when several are refused at once ("No access to logs and analytics"), so the reader asks for each access they lack. Analytics (`API_ANALYTICS`) and logs (`API_LOG`) are separate rights, as the analytics and logs filter catalogs are. On the Logs page the chart and the table each render from their own query, so one can be refused, or cover more APIs, without the other: the refused part says so in its own place and the other shows as usual. When both are refused the whole feature is, and the page shows a single state instead of two. Dashboards follow the same rule: a widget is refused only when the reader lacks a whole data kind (an API they may not read is narrowed out and shows as empty, so its existence does not leak), so a dashboard whose every widget is refused shows one state in place of its grid, and a mixed one shows a state in each refused tile. While editing, each widget keeps its own state, so the dashboard can still be laid out. A page with nothing left to show (Logs with both refused, Traces, a whole dashboard) also drops its filters and time range: a refusal does not depend on them, and controls that change nothing suggest the data could appear. The title, the dashboard's actions and the host's links stay. `DashboardView`'s `onWholeRefusedChange` tells a host page of its own when to do the same. A host widget backed by logs or traces names its kind through `WidgetAccessDenied`'s `dataKind`.
+
+An empty answer is not a refusal: a reader whose APIs have no traffic in range, or who may read none of them, gets the usual empty states. Sections are never hidden because a request was refused; which sections exist is decided by capabilities alone.
+
+**Retries.** The library's queries run on the host's `QueryClient`, and its `retry` setting still applies to failures (5xx, network). A 4xx answer is never retried: the server answered on purpose, so the screen says so at once instead of showing skeletons through every retry.
+
+### Load failures (5xx, network)
+
+A failure that is not a refusal (a 5xx, a network error, a host source's own error) is shown the same way everywhere, with `LoadFailedState`, the sibling of `AccessDeniedState`: same variants, a discreet icon, nothing in red, and in the data's own place, so a failure never reads as an empty answer and never sits above one. The table above lists where. "No data" and "No logs found" are for empty answers only.
+
+- **The page keeps its layout.** A failure is drawn over the faint shape of the data it stands in for (`ghost`: bars for a chart, lines for a table's rows, a number for a metric, a detail's sections, a dashboard's tiles), so it reads as data that is late, on the page the reader knows. When a whole page failed (the logs page with both parts failed, a dashboard whose every widget failed), the page itself stays in place, faint and out of reach (`inert`), each part drawing its ghost, under one card. A refusal does not do this: no data is on its way.
+
+- **Wording.** The title names the data: "Couldn't load logs", "Couldn't load analytics", "Couldn't load traces", "Couldn't load this log", "Couldn't load this trace". A compact state (a tile, a chart's area) shows the title alone. While Live is on, a state whose data follows the Live window (`followsLive`) counts down to the refresh that loads it again: "Trying again in 42 seconds.", and a page-level state's button reads "Try now". Otherwise (Live paused, an absolute range, a log or trace opened by id) a page-level state says "Something went wrong. Try again in a moment." with "Try again".
+- **No flicker between two failures.** While the same question is asked again (the next Live refresh, "Try again"), the failure stays on screen until an answer comes back, rather than flashing a loading state; the details stay open.
+- **One retry per page.** One part of a page failing (a widget tile, the logs chart or the logs table, the log detail's chart) gets no retry: the rest of the page still works and the next refresh asks again. A page whose every part failed gets exactly one "Try again", which re-runs every failed query on screen: the traces page, a log or trace detail (a drawer included), the logs page with both parts failed (one state, "Couldn't load logs and analytics"), the logs page without a chart, a dashboard whose every widget failed. The filter bar, the tracing API picker and the message list of a log detail keep their own inline "Try again": Live mode refreshes the data, never those lists.
+- **One state for a page.** A dashboard shows one state for all of it only when every widget has the same outcome, all refused (in place of its grid) or all failed (one card over its faint grid). Any mix, a refused widget next to a failed one included, keeps a state per tile. On the Logs page, a refusal on one side and a failure on the other stay each in place. Unlike a refusal, a failure keeps the filters and the time range: it may depend on them.
+- **Details on demand.** A state's "View details" opens a side panel with each failed call: its status, the call and when it failed, and "Copy for support", which copies it all as text. A compact or inline state shows the same text in a tooltip on its icon. There is no request id: the sources read no response headers. `ObservabilityHttpError` carries the `call` for this; a host source's error with a `status` and a `call` is described the same way. The `[gamma-lib-observability]` prefix of the error message stays in console logs.
+- **A failed refresh keeps the data.** Live mode refetches every minute by moving the window forward, and switching Paused back to Live refetches at once, on every page. When a refresh fails with data on screen, the data stays and the Live pill says so: an amber dot, and "Couldn't refresh at HH:MM. Showing earlier data." in its tooltip. That is the page's one signal of stale data, never a failure state over good data. A change of filters or time range is a new question: if it fails, the failure is shown, never the old data. A refusal never keeps old data either.
+- **Host widgets.** A host widget renderer shows its failure with `WidgetLoadFailed` (`error`, `failedAt`, `dataKind` for logs or traces, and `ghost`: `chart`, `rows` or `metric`), which also lets the dashboard show one card when every widget failed. Pass the query's own `error`: the same object from one render to the next.
+
+`QueryErrorBanner` stays exported for hosts that render it, but the library's pages no longer use it.
+
+**Try it.** The Storybook story `Routing/Permissions › Playground` renders every observability page through the real routes against mock sources. Its controls reach each case above without code, and default to everything allowed. Changing a right refreshes the page you are on, and navigating in the story's sidebar moves the Page control along:
+
+| Control                                                               | Values                                                   | What it drives                                                                                                        |
+| --------------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Page                                                                  | Home, Dashboard, Logs, Log detail, Tracing, Trace detail | The page the reader opens (Home: the section root)                                                                    |
+| Analytics                                                             | Allowed, Refused (403), Failing (500), Partly failing    | Dashboard widgets, the logs histogram, the log detail chart; partly: the breakdowns fail, time series and totals load |
+| Failed refresh                                                        | on / off                                                 | Data loads, then every refresh fails: the Live pill turns amber                                                       |
+| Logs                                                                  | Allowed, Refused (403), Failing (500)                    | The logs table, a log detail, the dashboard's logs widget                                                             |
+| Traces                                                                | Allowed, Refused (403), Failing (500)                    | The traces table and a trace detail                                                                                   |
+| API the reader may not see                                            | on / off                                                 | The deliberate 404 on the tracing page, a trace detail and a log detail                                               |
+| Filter lists                                                          | Allowed, Refused (403), Failing (500)                    | The filter bar's filter lists (analytics and tracing)                                                                 |
+| Tracing API list                                                      | Allowed, Refused (403), Failing (500)                    | The tracing API picker                                                                                                |
+| Capability: dashboards.read, dashboards.write, logs.read, traces.read | on / off                                                 | The host's capabilities: which sections exist, in the nav and the routes                                              |
+| Dashboard with a logs widget                                          | on / off                                                 | Adds a host widget backed by logs, for a dashboard mixing data kinds                                                  |
+
 **Concurrent edits.** `DashboardConflictError` carries `currentDashboard`, the dashboard as it now stands in the store, and the editor renders it from there rather than fetching again. The author then picks one of three resolutions, and each comes back to this port:
 
 - _Overwrite_ calls `updateDashboard(dashboard, signal, { force: true })`, which must apply the write over whatever revision is current, in one request. The HTTP adapter sends `If-Match: *`. The dashboard must still exist, so an overwrite never resurrects a deleted one.

package/USAGE_GUIDE.md

@@ -768,6 +768,7 @@ It returns an `ObservabilityFeatures` object with the following members:
 | -------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
 | `Routes`             | `(props: ObservabilityRoutesProps) => ReactNode`        | Route tree to mount under `observe/*`.                                                  |
 | `navGroup`           | `NavGroup`                                              | `{ label, items }` descriptor for the sidenav. Only enabled features appear in `items`. |
+| `navGroupFor`        | `(capabilities: DashboardCapabilities) => NavGroup`     | `navGroup` without the sections these capabilities cannot read.                         |
 | `routeKeys`          | `readonly string[]`                                     | Composite keys for enabled features, e.g. `['observe/dashboards', 'observe/logs']`.     |
 | `routes`             | `Record<string, { path; label }>`                       | Per-feature `{ path, label }` keyed by composite route key.                             |
 | `resolveRouteKey`    | `(pathname: string) => string \| null`                  | Reparses a host pathname into the matching composite route key. See below.              |

package/dist/components/AccessDeniedState.d.ts

@@ -0,0 +1,29 @@
+import { ReactNode } from 'react';
+/**
+ * - `default`: a page or a table's empty rows.
+ * - `compact`: a box with little room, such as a chart's area or a dashboard tile.
+ * - `inline`: one line next to a control, such as the filter bar or a picker.
+ */
+export type AccessDeniedStateVariant = 'default' | 'compact' | 'inline';
+export interface AccessDeniedStateProps {
+    /** What the reader may not see, naming the data: "No access to logs". */
+    readonly title: string;
+    /** How the reader gets access. Defaults to asking an administrator, the same everywhere. */
+    readonly description?: string;
+    /** Rendered under the text, e.g. a way back. Not shown inline. */
+    readonly action?: ReactNode;
+    /** @default 'default' */
+    readonly variant?: AccessDeniedStateVariant;
+    /** Replaces the lock, e.g. for a state that must not say whether access was the reason. */
+    readonly icon?: ReactNode;
+    readonly className?: string;
+}
+/**
+ * What a screen shows in place of data the reader may not see. Every refusal
+ * in the library uses it, so a reader is guided the same way everywhere: the
+ * title names the data, the description says how to get access. Deliberately
+ * not an error: nothing failed, so there is no retry and nothing in red. A
+ * refusal is about the reader, and retrying would get the same answer.
+ */
+export declare function AccessDeniedState({ title, description, action, variant, icon, className, }: AccessDeniedStateProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=AccessDeniedState.d.ts.map

package/dist/components/AccessDeniedState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccessDeniedState.d.ts","sourceRoot":"","sources":["../../src/components/AccessDeniedState.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAExE,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,yBAAyB;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,wBAAwB,CAAC;IAC5C,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,WAAiC,EACjC,MAAM,EACN,OAAmB,EACnB,IAAsC,EACtC,SAAS,GACV,EAAE,sBAAsB,2CA8BxB"}

package/dist/components/FailureCard.d.ts

@@ -0,0 +1,16 @@
+import { LoadFailure } from './failure-wording';
+export interface FailureCardProps {
+    readonly title: string;
+    readonly failures?: readonly LoadFailure[];
+    readonly onRetry?: () => void;
+    /** The data loads again on its own at each Live refresh: the card counts down to the next one. */
+    readonly followsLive?: boolean;
+    readonly className?: string;
+}
+/**
+ * The card a page-level or part-of-a-page failure shows over the faint shape
+ * of its data: what did not load, when it loads again on its own if it does,
+ * the page's one retry, and the details one step away in a side panel.
+ */
+export declare function FailureCard({ title, failures, onRetry, followsLive, className }: FailureCardProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=FailureCard.d.ts.map

package/dist/components/FailureCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FailureCard.d.ts","sourceRoot":"","sources":["../../src/components/FailureCard.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAoC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEvF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B,kGAAkG;IAClG,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAmB,EAAE,SAAS,EAAE,EAAE,gBAAgB,2CAmDzG"}

package/dist/components/FailureDetailsSheet.d.ts

@@ -0,0 +1,13 @@
+import { LoadFailure } from './failure-wording';
+export interface FailureDetailsSheetProps {
+    readonly failures: readonly LoadFailure[];
+    readonly open: boolean;
+    readonly onOpenChange: (open: boolean) => void;
+}
+/**
+ * The technical side of a failure, one step away from the page: each failed
+ * call with its status, the call and when it failed, and a copy of it all as
+ * text for a support ticket.
+ */
+export declare function FailureDetailsSheet({ failures, open, onOpenChange }: FailureDetailsSheetProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=FailureDetailsSheet.d.ts.map

package/dist/components/FailureDetailsSheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FailureDetailsSheet.d.ts","sourceRoot":"","sources":["../../src/components/FailureDetailsSheet.tsx"],"names":[],"mappings":"AAYA,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;CAChD;AAcD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,wBAAwB,2CA6B7F"}

package/dist/components/FailureGhost.d.ts

@@ -0,0 +1,14 @@
+/** The shape of the data a failure stands in for. */
+export type FailureGhostKind = 'chart' | 'rows' | 'metric' | 'detail' | 'tiles';
+export interface FailureGhostProps {
+    readonly kind: FailureGhostKind;
+    readonly className?: string;
+}
+/**
+ * The faint shape of the data a failure stands in for: bars for a chart, lines
+ * for a table's rows, a number for a metric. Drawn behind a failure state, it
+ * keeps the page's layout, so a failure reads as data that is late rather than
+ * as a different page. Decorative: hidden from assistive technology.
+ */
+export declare function FailureGhost({ kind, className }: FailureGhostProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=FailureGhost.d.ts.map

package/dist/components/FailureGhost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FailureGhost.d.ts","sourceRoot":"","sources":["../../src/components/FailureGhost.tsx"],"names":[],"mappings":"AAGA,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AA8FD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,iBAAiB,2CAOlE"}

package/dist/components/FailureOverlay.d.ts

@@ -0,0 +1,32 @@
+import { ReactNode } from 'react';
+import { LoadFailure } from './failure-wording';
+/**
+ * Whether this part of a page sits under a `FailureOverlay` that shows the
+ * failure for all of it: a failure state then draws only the faint shape of
+ * its data, and leaves the words to the overlay's one card.
+ */
+export declare function useUnderFailureOverlay(): boolean;
+/** The failure that holds a whole area: what the overlay's card says. */
+export interface AreaFailure {
+    readonly title: string;
+    readonly failures: readonly LoadFailure[];
+    readonly onRetry?: () => void;
+    /** The data loads again on its own at each Live refresh. */
+    readonly followsLive?: boolean;
+}
+export interface FailureOverlayProps {
+    /** The failure that holds the whole area, or `undefined` while it shows its content as usual. */
+    readonly failure: AreaFailure | undefined;
+    readonly children: ReactNode;
+}
+/**
+ * Keeps a page's layout when everything in it failed: its content stays in
+ * place, faint and out of reach, each part drawing the shape of its data, and
+ * one card over it says what failed. A failure then reads as data that is
+ * late, on the page the reader knows, rather than as a different page.
+ *
+ * The content keeps its place in the tree whether the area failed or not: the
+ * queries inside are what tell the page it failed, and when the data is back.
+ */
+export declare function FailureOverlay({ failure, children }: FailureOverlayProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=FailureOverlay.d.ts.map

package/dist/components/FailureOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FailureOverlay.d.ts","sourceRoot":"","sources":["../../src/components/FailureOverlay.tsx"],"names":[],"mappings":"AACA,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAElE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,mBAAmB,2CAuBxE"}

package/dist/components/LoadFailedState.d.ts

@@ -0,0 +1,47 @@
+import { AccessDeniedStateVariant } from './AccessDeniedState';
+import { FailureGhostKind } from './FailureGhost';
+import { LoadFailure } from './failure-wording';
+/** The same three as a refusal: a page or a table's rows, a small box, one line next to a control. */
+export type LoadFailedStateVariant = AccessDeniedStateVariant;
+export interface LoadFailedStateProps {
+    /** What did not load, naming the data: "Couldn't load logs". */
+    readonly title: string;
+    /** The failures behind it, described on demand for support. */
+    readonly failures?: readonly LoadFailure[];
+    /**
+     * Given to a page-level state only: re-runs the page's failed loads, and
+     * adds the guidance that goes with it. One part of a page failing gets no
+     * retry: the next refresh asks again, and the rest of the page still works.
+     */
+    readonly onRetry?: () => void;
+    /**
+     * The faint shape of the data the state stands in for, drawn behind it: bars
+     * for a chart, lines for a table's rows. Keeps the page's layout, so the
+     * failure reads as data that is late. Not drawn by the inline form.
+     */
+    readonly ghost?: FailureGhostKind;
+    /**
+     * The data loads again on its own at each Live refresh (a query built on the
+     * Live window): the state counts down to the next one while Live is on.
+     * Leave it off for data Live never reloads, such as a log opened by id.
+     * @default false
+     */
+    readonly followsLive?: boolean;
+    /** @default 'default' */
+    readonly variant?: LoadFailedStateVariant;
+    readonly className?: string;
+}
+/**
+ * What a screen shows in place of data that failed to load (5xx, network).
+ * Every failure in the library uses it, in the data's own place, so a failure
+ * never reads as an empty answer. The sibling of `AccessDeniedState`, with the
+ * same variants: a card over the faint shape of the data for a page or a part
+ * of one, a title over it for a tile, one line next to a control. Neutral,
+ * nothing in red, the technical details one step away (a side panel, or a
+ * tooltip on the icon of a small state) rather than in the text.
+ *
+ * Under a `FailureOverlay` that shows the failure for a whole area, it draws
+ * only the shape of its data: the overlay's card speaks for all of it.
+ */
+export declare function LoadFailedState({ title, failures, onRetry, ghost, followsLive, variant, className, }: LoadFailedStateProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=LoadFailedState.d.ts.map

package/dist/components/LoadFailedState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoadFailedState.d.ts","sourceRoot":"","sources":["../../src/components/LoadFailedState.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAEpE,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEvE,sGAAsG;AACtG,MAAM,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE9D,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,yBAAyB;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,QAAQ,EACR,OAAO,EACP,KAAK,EACL,WAAmB,EACnB,OAAmB,EACnB,SAAS,GACV,EAAE,oBAAoB,kDAsCtB"}

package/dist/components/QueryErrorBanner.d.ts

@@ -7,9 +7,11 @@ export interface QueryErrorBannerProps {
 }
 /**
  * Inline error banner for a failed data query. Exposed with `role="alert"` so
- * assistive technologies announce the failure as soon as it renders. Shared by
- * the observability explorer pages so logs and traces surface query errors
- * identically.
+ * assistive technologies announce the failure as soon as it renders.
+ *
+ * The library's own pages no longer use it: they show `LoadFailedState` in the
+ * data's own place, so a failure never sits above an empty table. Kept for
+ * hosts that still render it.
  */
 export declare function QueryErrorBanner({ message, onRetry, className }: QueryErrorBannerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=QueryErrorBanner.d.ts.map

package/dist/components/QueryErrorBanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"QueryErrorBanner.d.ts","sourceRoot":"","sources":["../../src/components/QueryErrorBanner.tsx"],"names":[],"mappings":"AAGA,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,qBAAqB,2CAiBtF"}
+{"version":3,"file":"QueryErrorBanner.d.ts","sourceRoot":"","sources":["../../src/components/QueryErrorBanner.tsx"],"names":[],"mappings":"AAGA,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,qBAAqB,2CAiBtF"}

package/dist/components/UnavailableState.d.ts

@@ -0,0 +1,16 @@
+import { ReactNode } from 'react';
+export interface UnavailableStateProps {
+    /** What was asked for, named in the title: "API", "Trace", "Log". */
+    readonly subject: string;
+    /** Rendered under the text, e.g. a way back. */
+    readonly action?: ReactNode;
+    readonly className?: string;
+}
+/**
+ * What a screen shows for a 404 that may stand for a refusal. Some endpoints
+ * answer "not found" for what the reader may not see, so that its existence
+ * does not leak; this state keeps that promise by never saying which of the
+ * two it is, and offers no retry since asking again gets the same answer.
+ */
+export declare function UnavailableState({ subject, action, className }: UnavailableStateProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=UnavailableState.d.ts.map

package/dist/components/UnavailableState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnavailableState.d.ts","sourceRoot":"","sources":["../../src/components/UnavailableState.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,qBAAqB,2CAUrF"}

package/dist/components/failure-wording.d.ts

@@ -0,0 +1,47 @@
+import { DataKind } from './refusal-wording';
+/** A failed load, with when it failed: what a failure state's details describe. */
+export interface LoadFailure {
+    readonly error: unknown;
+    /** When the load failed, in epoch milliseconds, when known. */
+    readonly at?: number;
+}
+/**
+ * What a page-level failure state says under its title, next to its one "Try
+ * again", when nothing will load the data again on its own.
+ */
+export declare const FAILURE_GUIDANCE = "Something went wrong. Try again in a moment.";
+/**
+ * The title of a failure, naming what did not load: "Couldn't load analytics",
+ * or every kind once when several parts failed, "Couldn't load logs and
+ * analytics".
+ */
+export declare function failureTitle(kinds: Iterable<DataKind>): string;
+/** "10:42", local time: the Live pill's refresh time. */
+export declare function formatClock(at: number): string;
+/** What is known of one failed call, for the details. */
+export interface FailureFacts {
+    /** The HTTP status, absent when no response came back. */
+    readonly status?: number;
+    /** The call that failed, "POST /observability/logs/search", when known. */
+    readonly call?: string;
+    /** The error's own message, kept only without a status: a network failure or a host source's error. */
+    readonly message?: string;
+    readonly at?: number;
+}
+/**
+ * Each distinct failed call, the latest when the same call failed several
+ * times. No request id: the sources read no response headers.
+ */
+export declare function failureFacts(failures: readonly LoadFailure[]): FailureFacts[];
+/** "HTTP 500", or "No response" when nothing came back. */
+export declare function failureStatusLabel(status: number | undefined): string;
+/** "Today, 10:42:13", or the date as well on another day. */
+export declare function formatFailureTime(at: number, now?: number): string;
+/**
+ * The technical details of one or several failures as text, for a support
+ * ticket: the status, the call and the time of each distinct failed call.
+ */
+export declare function describeFailures(failures: readonly LoadFailure[]): string;
+/** What a failure state says while Live mode is about to load the data again. */
+export declare function retryCountdown(seconds: number): string;
+//# sourceMappingURL=failure-wording.d.ts.map

package/dist/components/failure-wording.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-wording.d.ts","sourceRoot":"","sources":["../../src/components/failure-wording.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEjE,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,iDAAiD,CAAC;AAE/E;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,MAAM,CAE9D;AASD,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAG9C;AASD,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uGAAuG;IACvG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAkBD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAAG,YAAY,EAAE,CAQ7E;AAED,2DAA2D;AAC3D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAErE;AAED,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAI9E;AAUD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAEzE;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/components/index.d.ts

@@ -1,3 +1,9 @@
+export { AccessDeniedState } from './AccessDeniedState';
+export type { AccessDeniedStateProps, AccessDeniedStateVariant } from './AccessDeniedState';
+export { LoadFailedState } from './LoadFailedState';
+export type { LoadFailedStateProps, LoadFailedStateVariant } from './LoadFailedState';
+export type { FailureGhostKind } from './FailureGhost';
+export type { LoadFailure } from './failure-wording';
 export { QueryErrorBanner } from './QueryErrorBanner';
 export type { QueryErrorBannerProps } from './QueryErrorBanner';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AACtF,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/components/refusal-wording.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The kinds of data a screen reads, one per right: analytics
+ * (`API_ANALYTICS`), logs and traces (`API_LOG`). A refusal or a failure
+ * names the kind, so the reader knows which access to ask for, or what is
+ * missing from the screen.
+ */
+export type DataKind = 'logs' | 'traces' | 'analytics';
+/** The kinds of data a reader may be refused. */
+export type RefusedDataKind = DataKind;
+/** Every kind once, in a stable order: "logs, traces and analytics". */
+export declare function listDataKinds(kinds: Iterable<DataKind>): string;
+/**
+ * The title of a refusal: "No access to analytics", or every refused kind once,
+ * "No access to logs and analytics", so asking for one of them is not mistaken
+ * for enough.
+ */
+export declare function refusalTitle(kinds: Iterable<RefusedDataKind>): string;
+//# sourceMappingURL=refusal-wording.d.ts.map

package/dist/components/refusal-wording.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal-wording.d.ts","sourceRoot":"","sources":["../../src/components/refusal-wording.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEvD,iDAAiD;AACjD,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;AAKvC,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,MAAM,CAK/D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,MAAM,CAErE"}