@marinoscar/platform-web 0.0.0-stage → 0.1.0-next.3

package/dist/telemetry/internal/useIsMounted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIsMounted.js","sourceRoot":"","sources":["../../../src/telemetry/internal/useIsMounted.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7B,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,GAAG,EAAE;YACV,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC;QAC1B,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAChD,CAAC"}

package/dist/telemetry/internal/useVisiblePolling.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `useVisiblePolling` — an interval that stops with the tab.
+ *
+ * Introduced by issue #266 for the jobs page and EXTRACTED here by #271, when
+ * the worker-fleet page needed the same behaviour. Extracted rather than
+ * copied, and the distinction is the whole point of this file existing: two
+ * implementations of "poll, but not in a background tab" would be two places
+ * the `visibilitychange` teardown could be got subtly wrong, and the second
+ * one would be discovered the way the first would have been — by a dashboard
+ * left open overnight, months later, in somebody's database load graph.
+ *
+ * `hooks/useJobs.ts` and `hooks/useWorkerNodes.ts` both RE-EXPORT this so each
+ * page keeps importing its polling from the hook module it already depends on
+ * (and so a page test that mocks that module still intercepts the poll). The
+ * re-exports are aliases of this one function; there is exactly one
+ * implementation, and this is it.
+ *
+ * =============================================================================
+ * WHY THE INTERVAL STOPS WITH THE TAB
+ * =============================================================================
+ *
+ * These pages poll because their contents change with nobody touching them: a
+ * queue drains, a worker stops heartbeating. An operator watching either needs
+ * the numbers to move, and a manual refresh button turns "is it recovering"
+ * into a clicking exercise.
+ *
+ * A bare `setInterval` keeps firing in a background tab, and that is not a
+ * micro-optimisation to skip. A dashboard left open on a second monitor
+ * overnight is ~2,900 requests at a 10-second poll — each one a real query
+ * against the same database the workers are competing for — and every response
+ * is discarded, because nobody is looking. Browsers throttle background timers
+ * but do not stop them, and the throttling is neither uniform nor something a
+ * server capacity plan can rely on.
+ *
+ * So the interval is torn down on `visibilitychange` to hidden and rebuilt on
+ * the way back, with ONE IMMEDIATE FETCH on return. The immediate fetch is the
+ * half that makes the pause invisible to the operator: without it, a tab
+ * restored after an hour would show hour-old numbers for up to a full interval,
+ * which is worse than not pausing at all — stale data that looks live.
+ */
+/**
+ * Call `callback` every `intervalMs` — but only while the document is visible.
+ *
+ * `callback` is held in a ref rather than being an effect dependency: a page
+ * naturally passes a fresh closure on every render (it reads the current
+ * filters), and depending on it directly would tear down and rebuild the
+ * interval on every keystroke, so the timer would never actually reach its
+ * period. The ref is updated on each render, so a tick always calls the
+ * LATEST closure while the timer itself survives.
+ *
+ * `intervalMs <= 0` disables polling entirely, which is what a test — or a
+ * caller with no reason to poll — passes.
+ */
+export declare function useVisiblePolling(callback: () => void, intervalMs: number): void;
+//# sourceMappingURL=useVisiblePolling.d.ts.map

package/dist/telemetry/internal/useVisiblePolling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVisiblePolling.d.ts","sourceRoot":"","sources":["../../../src/telemetry/internal/useVisiblePolling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CA4ChF"}

package/dist/telemetry/internal/useVisiblePolling.js

@@ -0,0 +1,96 @@
+/**
+ * `useVisiblePolling` — an interval that stops with the tab.
+ *
+ * Introduced by issue #266 for the jobs page and EXTRACTED here by #271, when
+ * the worker-fleet page needed the same behaviour. Extracted rather than
+ * copied, and the distinction is the whole point of this file existing: two
+ * implementations of "poll, but not in a background tab" would be two places
+ * the `visibilitychange` teardown could be got subtly wrong, and the second
+ * one would be discovered the way the first would have been — by a dashboard
+ * left open overnight, months later, in somebody's database load graph.
+ *
+ * `hooks/useJobs.ts` and `hooks/useWorkerNodes.ts` both RE-EXPORT this so each
+ * page keeps importing its polling from the hook module it already depends on
+ * (and so a page test that mocks that module still intercepts the poll). The
+ * re-exports are aliases of this one function; there is exactly one
+ * implementation, and this is it.
+ *
+ * =============================================================================
+ * WHY THE INTERVAL STOPS WITH THE TAB
+ * =============================================================================
+ *
+ * These pages poll because their contents change with nobody touching them: a
+ * queue drains, a worker stops heartbeating. An operator watching either needs
+ * the numbers to move, and a manual refresh button turns "is it recovering"
+ * into a clicking exercise.
+ *
+ * A bare `setInterval` keeps firing in a background tab, and that is not a
+ * micro-optimisation to skip. A dashboard left open on a second monitor
+ * overnight is ~2,900 requests at a 10-second poll — each one a real query
+ * against the same database the workers are competing for — and every response
+ * is discarded, because nobody is looking. Browsers throttle background timers
+ * but do not stop them, and the throttling is neither uniform nor something a
+ * server capacity plan can rely on.
+ *
+ * So the interval is torn down on `visibilitychange` to hidden and rebuilt on
+ * the way back, with ONE IMMEDIATE FETCH on return. The immediate fetch is the
+ * half that makes the pause invisible to the operator: without it, a tab
+ * restored after an hour would show hour-old numbers for up to a full interval,
+ * which is worse than not pausing at all — stale data that looks live.
+ */
+import { useEffect, useRef } from 'react';
+/**
+ * Call `callback` every `intervalMs` — but only while the document is visible.
+ *
+ * `callback` is held in a ref rather than being an effect dependency: a page
+ * naturally passes a fresh closure on every render (it reads the current
+ * filters), and depending on it directly would tear down and rebuild the
+ * interval on every keystroke, so the timer would never actually reach its
+ * period. The ref is updated on each render, so a tick always calls the
+ * LATEST closure while the timer itself survives.
+ *
+ * `intervalMs <= 0` disables polling entirely, which is what a test — or a
+ * caller with no reason to poll — passes.
+ */
+export function useVisiblePolling(callback, intervalMs) {
+    const callbackRef = useRef(callback);
+    callbackRef.current = callback;
+    useEffect(() => {
+        if (intervalMs <= 0)
+            return;
+        let timer = null;
+        const stop = () => {
+            if (timer !== null) {
+                clearInterval(timer);
+                timer = null;
+            }
+        };
+        const start = () => {
+            // Guarded rather than assumed: `visibilitychange` can fire more than
+            // once for the same effective state, and an unguarded `setInterval`
+            // would leak a second timer and double the request rate.
+            if (timer !== null)
+                return;
+            timer = setInterval(() => callbackRef.current(), intervalMs);
+        };
+        const onVisibilityChange = () => {
+            if (document.hidden) {
+                stop();
+                return;
+            }
+            // Catch up FIRST, then resume — see the file header on why a resumed
+            // poll that waits out a full interval is worse than never pausing.
+            callbackRef.current();
+            start();
+        };
+        // A tab that is already hidden at mount never starts one.
+        if (!document.hidden)
+            start();
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        return () => {
+            stop();
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+        };
+    }, [intervalMs]);
+}
+//# sourceMappingURL=useVisiblePolling.js.map

package/dist/telemetry/internal/useVisiblePolling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVisiblePolling.js","sourceRoot":"","sources":["../../../src/telemetry/internal/useVisiblePolling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAoB,EAAE,UAAkB;IACxE,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrC,WAAW,CAAC,OAAO,GAAG,QAAQ,CAAC;IAE/B,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,UAAU,IAAI,CAAC;YAAE,OAAO;QAE5B,IAAI,KAAK,GAA0C,IAAI,CAAC;QAExD,MAAM,IAAI,GAAG,GAAG,EAAE;YAChB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,aAAa,CAAC,KAAK,CAAC,CAAC;gBACrB,KAAK,GAAG,IAAI,CAAC;YACf,CAAC;QACH,CAAC,CAAC;QAEF,MAAM,KAAK,GAAG,GAAG,EAAE;YACjB,qEAAqE;YACrE,oEAAoE;YACpE,yDAAyD;YACzD,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO;YAC3B,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;QAC/D,CAAC,CAAC;QAEF,MAAM,kBAAkB,GAAG,GAAG,EAAE;YAC9B,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;gBACpB,IAAI,EAAE,CAAC;gBACP,OAAO;YACT,CAAC;YACD,qEAAqE;YACrE,mEAAmE;YACnE,WAAW,CAAC,OAAO,EAAE,CAAC;YACtB,KAAK,EAAE,CAAC;QACV,CAAC,CAAC;QAEF,0DAA0D;QAC1D,IAAI,CAAC,QAAQ,CAAC,MAAM;YAAE,KAAK,EAAE,CAAC;QAC9B,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC;QAElE,OAAO,GAAG,EAAE;YACV,IAAI,EAAE,CAAC;YACP,QAAQ,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC;QACvE,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;AACnB,CAAC"}

package/dist/telemetry/internal/visuallyHidden.d.ts

@@ -0,0 +1,12 @@
+export declare const visuallyHidden: {
+    readonly border: 0;
+    readonly clipPath: "inset(50%)";
+    readonly height: "1px";
+    readonly margin: "-1px";
+    readonly overflow: "hidden";
+    readonly padding: 0;
+    readonly position: "absolute";
+    readonly whiteSpace: "nowrap";
+    readonly width: "1px";
+};
+//# sourceMappingURL=visuallyHidden.d.ts.map

package/dist/telemetry/internal/visuallyHidden.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visuallyHidden.d.ts","sourceRoot":"","sources":["../../../src/telemetry/internal/visuallyHidden.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,cAAc;;;;;;;;;;CAUjB,CAAC"}

package/dist/telemetry/internal/visuallyHidden.js

@@ -0,0 +1,15 @@
+// The screen-reader-only style (issue #704): the same declarations as
+// `@mui/utils/visuallyHidden`, inlined so the package does not reach into a
+// transitive dependency of `@mui/material`. Not exported.
+export const visuallyHidden = {
+    border: 0,
+    clipPath: 'inset(50%)',
+    height: '1px',
+    margin: '-1px',
+    overflow: 'hidden',
+    padding: 0,
+    position: 'absolute',
+    whiteSpace: 'nowrap',
+    width: '1px',
+};
+//# sourceMappingURL=visuallyHidden.js.map

package/dist/telemetry/internal/visuallyHidden.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visuallyHidden.js","sourceRoot":"","sources":["../../../src/telemetry/internal/visuallyHidden.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,4EAA4E;AAC5E,0DAA0D;AAC1D,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,MAAM,EAAE,CAAC;IACT,QAAQ,EAAE,YAAY;IACtB,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,MAAM;IACd,QAAQ,EAAE,QAAQ;IAClB,OAAO,EAAE,CAAC;IACV,QAAQ,EAAE,UAAU;IACpB,UAAU,EAAE,QAAQ;IACpB,KAAK,EAAE,KAAK;CACJ,CAAC"}

package/dist/telemetry/theme/augment.d.ts

@@ -0,0 +1,65 @@
+/**
+ * MUI module augmentation for the telemetry UI's theme-token contract
+ * (issue #686, platform-packages PP-1.15).
+ *
+ * Two palette roles beyond MUI's defaults, the first entries of the telemetry
+ * package's extension-point catalog (theme tokens, see #704):
+ *
+ * - `palette.status` — what a value MEANS: `ok`, `warn`, `crit`, `info` and
+ *   `neutral`. Used for status codes, severities, outcomes, up/down cells.
+ * - `palette.chart.series` — categorical colours for chart lines and series
+ *   that carry no meaning beyond "a different series", in assignment order.
+ *
+ * Rule: series colours are never used for status, and status colours are
+ * never used as a generic series colour.
+ *
+ * `withTelemetryTokens` (`telemetryTokens.ts`) fills both from the theme's own
+ * palette when the app did not set them, so an app overrides a token simply by
+ * passing it in its `createTheme` options:
+ *
+ * ```ts
+ * createTheme({ palette: { status: { crit: '#b00020' }, chart: { series: ['#0057b8', '#ffd700'] } } });
+ * ```
+ *
+ * The interface name `PaletteChart` with `series: string[]` and
+ * `Palette.chart: PaletteChart` are deliberate: TypeScript merges identical
+ * interface declarations, so an app that already augments MUI with the same
+ * shape keeps compiling. Do not change the shape.
+ *
+ * A MODULE (`export {}`), not a `.d.ts` script: a script's `declare module`
+ * would redeclare the package instead of augmenting it, and a `.d.ts` is only
+ * seen by programs whose `include` happens to cover it. `theme/index.ts` and
+ * `theme/telemetryTokens.ts` import this file for its side effect, so every
+ * program that compiles the theme (the app, the visual harness, vitest) gets
+ * the augmentation with it.
+ */
+export {};
+declare module '@mui/material/styles' {
+    /** Status colours: what a value means. Never used as a series colour. */
+    interface PaletteStatus {
+        /** Healthy, succeeded, 2xx, up. */
+        ok: string;
+        /** Needs attention: 4xx, warnings, a highlighted tile. */
+        warn: string;
+        /** Failed: 5xx, error logs, down. */
+        crit: string;
+        /** Informational: 3xx, info logs. */
+        info: string;
+        /** No particular status: "other" log records. */
+        neutral: string;
+    }
+    /** Chart colours. Series colours are never used for status. */
+    interface PaletteChart {
+        /** Categorical series colours, in assignment order. */
+        series: string[];
+    }
+    interface Palette {
+        status: PaletteStatus;
+        chart: PaletteChart;
+    }
+    interface PaletteOptions {
+        status?: Partial<PaletteStatus>;
+        chart?: Partial<PaletteChart>;
+    }
+}
+//# sourceMappingURL=augment.d.ts.map

package/dist/telemetry/theme/augment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"augment.d.ts","sourceRoot":"","sources":["../../../src/telemetry/theme/augment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,CAAC;AAEV,OAAO,QAAQ,sBAAsB,CAAC;IACpC,yEAAyE;IACzE,UAAU,aAAa;QACrB,mCAAmC;QACnC,EAAE,EAAE,MAAM,CAAC;QACX,0DAA0D;QAC1D,IAAI,EAAE,MAAM,CAAC;QACb,qCAAqC;QACrC,IAAI,EAAE,MAAM,CAAC;QACb,qCAAqC;QACrC,IAAI,EAAE,MAAM,CAAC;QACb,iDAAiD;QACjD,OAAO,EAAE,MAAM,CAAC;KACjB;IAED,+DAA+D;IAC/D,UAAU,YAAY;QACpB,uDAAuD;QACvD,MAAM,EAAE,MAAM,EAAE,CAAC;KAClB;IAED,UAAU,OAAO;QACf,MAAM,EAAE,aAAa,CAAC;QACtB,KAAK,EAAE,YAAY,CAAC;KACrB;IAED,UAAU,cAAc;QACtB,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;QAChC,KAAK,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;KAC/B;CACF"}

package/dist/telemetry/theme/augment.js

@@ -0,0 +1,37 @@
+/**
+ * MUI module augmentation for the telemetry UI's theme-token contract
+ * (issue #686, platform-packages PP-1.15).
+ *
+ * Two palette roles beyond MUI's defaults, the first entries of the telemetry
+ * package's extension-point catalog (theme tokens, see #704):
+ *
+ * - `palette.status` — what a value MEANS: `ok`, `warn`, `crit`, `info` and
+ *   `neutral`. Used for status codes, severities, outcomes, up/down cells.
+ * - `palette.chart.series` — categorical colours for chart lines and series
+ *   that carry no meaning beyond "a different series", in assignment order.
+ *
+ * Rule: series colours are never used for status, and status colours are
+ * never used as a generic series colour.
+ *
+ * `withTelemetryTokens` (`telemetryTokens.ts`) fills both from the theme's own
+ * palette when the app did not set them, so an app overrides a token simply by
+ * passing it in its `createTheme` options:
+ *
+ * ```ts
+ * createTheme({ palette: { status: { crit: '#b00020' }, chart: { series: ['#0057b8', '#ffd700'] } } });
+ * ```
+ *
+ * The interface name `PaletteChart` with `series: string[]` and
+ * `Palette.chart: PaletteChart` are deliberate: TypeScript merges identical
+ * interface declarations, so an app that already augments MUI with the same
+ * shape keeps compiling. Do not change the shape.
+ *
+ * A MODULE (`export {}`), not a `.d.ts` script: a script's `declare module`
+ * would redeclare the package instead of augmenting it, and a `.d.ts` is only
+ * seen by programs whose `include` happens to cover it. `theme/index.ts` and
+ * `theme/telemetryTokens.ts` import this file for its side effect, so every
+ * program that compiles the theme (the app, the visual harness, vitest) gets
+ * the augmentation with it.
+ */
+export {};
+//# sourceMappingURL=augment.js.map

package/dist/telemetry/theme/augment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"augment.js","sourceRoot":"","sources":["../../../src/telemetry/theme/augment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG"}

package/dist/telemetry/theme/telemetryTokens.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The telemetry UI's theme-token contract (issue #686, platform-packages
+ * PP-1.15): `palette.status.{ok,warn,crit,info,neutral}` and
+ * `palette.chart.series`, declared in `augment.ts`.
+ *
+ * Packages own structure, apps own appearance: the telemetry UI never reads a
+ * raw MUI palette role (`success`, `error`, `warning`, `info`, `secondary`,
+ * `grey`) to mean "status" or "chart series". It reads these tokens, and an
+ * app restyles it by setting them in its own theme.
+ *
+ * Rule: series tokens are never used for status, and status tokens are never
+ * used as a series colour.
+ *
+ * Defaults derive from the theme's own palette, so a theme that sets nothing
+ * looks exactly as it did before the tokens existed:
+ *
+ * | Token            | Default                                                    |
+ * |------------------|------------------------------------------------------------|
+ * | `status.ok`      | `palette.success.main`                                     |
+ * | `status.warn`    | `palette.warning.main`                                     |
+ * | `status.crit`    | `palette.error.main`                                       |
+ * | `status.info`    | `palette.info.main`                                        |
+ * | `status.neutral` | `palette.grey[500]`                                        |
+ * | `chart.series`   | `primary, secondary, warning, success, error, info` `.main`, then `grey[500]`, `text.primary` |
+ *
+ * Packaged with the telemetry UI in `@marinoscar/platform-web/telemetry`
+ * (#704); the app applies `withTelemetryTokens` to its own themes.
+ */
+import './augment.js';
+import { type Theme } from '@mui/material/styles';
+/**
+ * `palette.status`: what a value MEANS. Never used as a series colour. The
+ * same shape as the `PaletteStatus` MUI augmentation this slice declares.
+ *
+ * @extensionPoint theme-token
+ * @stability experimental
+ */
+export interface TelemetryStatusTokens {
+    /** Healthy, succeeded, 2xx, up. Default `palette.success.main`. */
+    ok: string;
+    /** Needs attention: 4xx, warnings, a highlighted tile. Default `palette.warning.main`. */
+    warn: string;
+    /** Failed: 5xx, error logs, down. Default `palette.error.main`. */
+    crit: string;
+    /** Informational: 3xx, info logs. Default `palette.info.main`. */
+    info: string;
+    /** No particular status: "other" log records. Default `palette.grey[500]`. */
+    neutral: string;
+}
+/**
+ * `palette.chart`: categorical chart colours. Never used for status. The same
+ * shape as the `PaletteChart` MUI augmentation this slice declares.
+ *
+ * @extensionPoint theme-token
+ * @stability experimental
+ */
+export interface TelemetryChartTokens {
+    /**
+     * Series colours, in assignment order. Default: the `.main` of `primary`,
+     * `secondary`, `warning`, `success`, `error` and `info`, then `grey[500]`
+     * and `text.primary`.
+     */
+    series: string[];
+}
+/**
+ * Every telemetry token of a theme, complete (missing ones derived).
+ *
+ * @stability experimental
+ */
+export interface TelemetryTokens {
+    /** `palette.status`. */
+    status: TelemetryStatusTokens;
+    /** `palette.chart`. */
+    chart: TelemetryChartTokens;
+}
+/**
+ * Pure accessor: the theme's telemetry tokens, with every missing token
+ * derived from its palette. For code that receives a theme which may not
+ * have been through {@link withTelemetryTokens} (a test's `createTheme()`,
+ * MUI's default theme outside any provider). Never mutates `theme`.
+ *
+ * @param theme - any MUI theme.
+ * @returns the complete tokens.
+ *
+ * @stability experimental
+ */
+export declare function telemetryTokens(theme: Theme): TelemetryTokens;
+/**
+ * Pure and idempotent: a copy of `theme` whose `palette.status` and
+ * `palette.chart` are complete. Tokens the app already set win; missing ones
+ * derive from the theme's own palette (`ok` = `success.main`, `warn` =
+ * `warning.main`, `crit` = `error.main`, `info` = `info.main`, `neutral` =
+ * `grey[500]`, `chart.series` = the `.main` of `primary`, `secondary`,
+ * `warning`, `success`, `error` and `info`, then `grey[500]` and
+ * `text.primary`). The input theme is not
+ * mutated, and nothing else in it changes. A package never creates a theme:
+ * the app passes its own through this.
+ *
+ * @param theme - the app's theme (from `createTheme`).
+ * @returns the theme with complete telemetry tokens.
+ *
+ * @example
+ * ```ts
+ * export const lightTheme = withTelemetryTokens(
+ *   createTheme({ palette: { mode: 'light', status: { crit: '#b00020' }, chart: { series: ['#0057b8', '#ffd700'] } } }),
+ * );
+ * ```
+ *
+ * @extensionPoint theme-token
+ * @stability experimental
+ */
+export declare function withTelemetryTokens(theme: Theme): Theme;
+/**
+ * The telemetry tokens of the theme in context (`useTheme()` + {@link telemetryTokens}).
+ *
+ * @returns the complete tokens.
+ *
+ * @stability experimental
+ */
+export declare function useTelemetryTokens(): TelemetryTokens;
+//# sourceMappingURL=telemetryTokens.d.ts.map

package/dist/telemetry/theme/telemetryTokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetryTokens.d.ts","sourceRoot":"","sources":["../../../src/telemetry/theme/telemetryTokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,cAAc,CAAC;AAEtB,OAAO,EAAmD,KAAK,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAEnG;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IACX,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,MAAM,EAAE,qBAAqB,CAAC;IAC9B,uBAAuB;IACvB,KAAK,EAAE,oBAAoB,CAAC;CAC7B;AA8BD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,eAAe,CAc7D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAUvD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAGpD"}

package/dist/telemetry/theme/telemetryTokens.js

@@ -0,0 +1,129 @@
+/**
+ * The telemetry UI's theme-token contract (issue #686, platform-packages
+ * PP-1.15): `palette.status.{ok,warn,crit,info,neutral}` and
+ * `palette.chart.series`, declared in `augment.ts`.
+ *
+ * Packages own structure, apps own appearance: the telemetry UI never reads a
+ * raw MUI palette role (`success`, `error`, `warning`, `info`, `secondary`,
+ * `grey`) to mean "status" or "chart series". It reads these tokens, and an
+ * app restyles it by setting them in its own theme.
+ *
+ * Rule: series tokens are never used for status, and status tokens are never
+ * used as a series colour.
+ *
+ * Defaults derive from the theme's own palette, so a theme that sets nothing
+ * looks exactly as it did before the tokens existed:
+ *
+ * | Token            | Default                                                    |
+ * |------------------|------------------------------------------------------------|
+ * | `status.ok`      | `palette.success.main`                                     |
+ * | `status.warn`    | `palette.warning.main`                                     |
+ * | `status.crit`    | `palette.error.main`                                       |
+ * | `status.info`    | `palette.info.main`                                        |
+ * | `status.neutral` | `palette.grey[500]`                                        |
+ * | `chart.series`   | `primary, secondary, warning, success, error, info` `.main`, then `grey[500]`, `text.primary` |
+ *
+ * Packaged with the telemetry UI in `@marinoscar/platform-web/telemetry`
+ * (#704); the app applies `withTelemetryTokens` to its own themes.
+ */
+import './augment.js';
+import { useMemo } from 'react';
+import { useTheme } from '@mui/material/styles';
+function defaultStatus(theme) {
+    const { palette } = theme;
+    return {
+        ok: palette.success.main,
+        warn: palette.warning.main,
+        crit: palette.error.main,
+        info: palette.info.main,
+        neutral: palette.grey[500],
+    };
+}
+function defaultSeries(theme) {
+    const { palette } = theme;
+    // Distinct hues first (primary and info are both blue in the base theme).
+    return [
+        palette.primary.main,
+        palette.secondary.main,
+        palette.warning.main,
+        palette.success.main,
+        palette.error.main,
+        palette.info.main,
+        palette.grey[500],
+        palette.text.primary,
+    ];
+}
+/**
+ * Pure accessor: the theme's telemetry tokens, with every missing token
+ * derived from its palette. For code that receives a theme which may not
+ * have been through {@link withTelemetryTokens} (a test's `createTheme()`,
+ * MUI's default theme outside any provider). Never mutates `theme`.
+ *
+ * @param theme - any MUI theme.
+ * @returns the complete tokens.
+ *
+ * @stability experimental
+ */
+export function telemetryTokens(theme) {
+    const own = theme.palette;
+    const status = { ...defaultStatus(theme) };
+    for (const [key, value] of Object.entries(own.status ?? {})) {
+        if (typeof value === 'string' && value !== '')
+            status[key] = value;
+    }
+    const series = own.chart?.series;
+    return {
+        status,
+        chart: {
+            ...own.chart,
+            series: Array.isArray(series) && series.length > 0 ? [...series] : defaultSeries(theme),
+        },
+    };
+}
+/**
+ * Pure and idempotent: a copy of `theme` whose `palette.status` and
+ * `palette.chart` are complete. Tokens the app already set win; missing ones
+ * derive from the theme's own palette (`ok` = `success.main`, `warn` =
+ * `warning.main`, `crit` = `error.main`, `info` = `info.main`, `neutral` =
+ * `grey[500]`, `chart.series` = the `.main` of `primary`, `secondary`,
+ * `warning`, `success`, `error` and `info`, then `grey[500]` and
+ * `text.primary`). The input theme is not
+ * mutated, and nothing else in it changes. A package never creates a theme:
+ * the app passes its own through this.
+ *
+ * @param theme - the app's theme (from `createTheme`).
+ * @returns the theme with complete telemetry tokens.
+ *
+ * @example
+ * ```ts
+ * export const lightTheme = withTelemetryTokens(
+ *   createTheme({ palette: { mode: 'light', status: { crit: '#b00020' }, chart: { series: ['#0057b8', '#ffd700'] } } }),
+ * );
+ * ```
+ *
+ * @extensionPoint theme-token
+ * @stability experimental
+ */
+export function withTelemetryTokens(theme) {
+    const tokens = telemetryTokens(theme);
+    return {
+        ...theme,
+        palette: {
+            ...theme.palette,
+            status: tokens.status,
+            chart: tokens.chart,
+        },
+    };
+}
+/**
+ * The telemetry tokens of the theme in context (`useTheme()` + {@link telemetryTokens}).
+ *
+ * @returns the complete tokens.
+ *
+ * @stability experimental
+ */
+export function useTelemetryTokens() {
+    const theme = useTheme();
+    return useMemo(() => telemetryTokens(theme), [theme]);
+}
+//# sourceMappingURL=telemetryTokens.js.map

package/dist/telemetry/theme/telemetryTokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetryTokens.js","sourceRoot":"","sources":["../../../src/telemetry/theme/telemetryTokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,cAAc,CAAC;AACtB,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAqD,MAAM,sBAAsB,CAAC;AAoDnG,SAAS,aAAa,CAAC,KAAY;IACjC,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC1B,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI;QACxB,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI;QAC1B,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI;QACxB,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI;QACvB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC;KAC3B,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,KAAY;IACjC,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC1B,0EAA0E;IAC1E,OAAO;QACL,OAAO,CAAC,OAAO,CAAC,IAAI;QACpB,OAAO,CAAC,SAAS,CAAC,IAAI;QACtB,OAAO,CAAC,OAAO,CAAC,IAAI;QACpB,OAAO,CAAC,OAAO,CAAC,IAAI;QACpB,OAAO,CAAC,KAAK,CAAC,IAAI;QAClB,OAAO,CAAC,IAAI,CAAC,IAAI;QACjB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC;QACjB,OAAO,CAAC,IAAI,CAAC,OAAO;KACrB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,KAAY;IAC1C,MAAM,GAAG,GAAG,KAAK,CAAC,OAAiC,CAAC;IACpD,MAAM,MAAM,GAAkB,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;IAC1D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;QAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE;YAAE,MAAM,CAAC,GAA0B,CAAC,GAAG,KAAK,CAAC;IAC5F,CAAC;IACD,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC;IACjC,OAAO;QACL,MAAM;QACN,KAAK,EAAE;YACL,GAAG,GAAG,CAAC,KAAK;YACZ,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC;SACxF;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAY;IAC9C,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACtC,OAAO;QACL,GAAG,KAAK;QACR,OAAO,EAAE;YACP,GAAG,KAAK,CAAC,OAAO;YAChB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB;KACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;AACxD,CAAC"}

package/dist/telemetry/ui/admin.d.ts

@@ -0,0 +1,35 @@
+import type { PlatformSettingsPage } from '../../core/index.js';
+/**
+ * One telemetry admin card: the `PlatformSettingsPage` card shape (#696) plus
+ * its icon, structurally a `SettingsCardDef` of the reference app.
+ *
+ * @stability experimental
+ */
+export type TelemetryAdminCard = PlatformSettingsPage<'telemetry'>['card'] & {
+    /** The card and rail icon (an MUI SvgIcon). */
+    Icon: PlatformSettingsPage['Icon'];
+};
+/**
+ * The three Observability cards of the telemetry slice, in registry order:
+ *
+ * - `Telemetry` (`/admin/settings/telemetry`, `telemetry:read`): NO `feature`,
+ *   deliberately; it is where telemetry is switched on. Saving needs
+ *   `telemetry:write`, which the page gates.
+ * - `Telemetry Explorer` (`…/explorer`, `telemetry:query`, `feature: 'telemetry'`).
+ * - `Telemetry Dashboard` (`…/dashboard`, `telemetry:query`, `feature: 'telemetry'`).
+ *
+ * The permissions are the exact strings the telemetry controllers enforce.
+ * Both nested pages sit under the Telemetry route, so a longest-prefix title
+ * resolver names them correctly.
+ *
+ * @example
+ * ```tsx
+ * // apps/web/src/config/adminSections.tsx, the Observability section
+ * cards: [...telemetryAdminCards, { ...doctorSettingsPage.card, Icon: doctorSettingsPage.Icon }],
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare const telemetryAdminCards: readonly TelemetryAdminCard[];
+//# sourceMappingURL=admin.d.ts.map

package/dist/telemetry/ui/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../../../src/telemetry/ui/admin.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,GAAG;IAC3E,+CAA+C;IAC/C,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;CACpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,kBAAkB,EA0B3D,CAAC"}