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

package/dist/core/index.js

@@ -0,0 +1,21 @@
+// `@marinoscar/platform-web/core`: the web host ports every packaged page
+// reuses (issue #696). Documented in ./README.md.
+export { isPlatformApiError } from './api-client.js';
+// The packaged-page slot contract (PP-14.23): the optional `slots` prop every
+// packaged page takes, and the hook that applies the table slots to a page's
+// columns.
+export { PageSlotsFrame, SLOT_DETAIL_PANEL_COLUMN_ID, SLOT_ROW_ACTIONS_COLUMN_ID, useTableSlotColumns } from './page-slots.js';
+export { PlatformHostProvider, useOptionalPlatformHost, usePlatformApi, useOptionalPlatformPort, usePlatformHost, usePlatformPort, usePlatformViewer, } from './host.js';
+// The browser HTTP client (issue #727, PP-6.6): the access-token holder, the
+// one-shot refresh and the cross-page refresh lock, moved from the reference
+// app's `services/api.ts`. The identity slice's `AuthProvider` drives it.
+export { ApiError, PlatformHttpClient } from './http/client.js';
+// The adapter from that client to the transport port (issue #868): an app
+// keeps ONE `PlatformHttpClient` and hands the packaged pages this view of it.
+export { createPlatformApiClient, toHttpRequestOptions, toPlatformApiError } from './http/platform-api-client.js';
+// The Server-Sent Events client (issue #900): the incremental parser, the
+// reconnecting GET stream and the single-shot POST stream, moved from the
+// reference app's `services/sse.ts`. The app binds `connectSse` to the
+// notifications slice and `postSse` to the transport port's `postSse`.
+export { SseParser, connectSse, postSse } from './http/sse.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,kDAAkD;AAElD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAUrD,8EAA8E;AAC9E,6EAA6E;AAC7E,WAAW;AACX,OAAO,EAAE,cAAc,EAAE,2BAA2B,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAU/H,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,uBAAuB,EACvB,eAAe,EACf,eAAe,EACf,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAEnB,6EAA6E;AAC7E,6EAA6E;AAC7E,0EAA0E;AAC1E,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAQhE,0EAA0E;AAC1E,+EAA+E;AAC/E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAElH,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,uEAAuE;AACvE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC"}

package/dist/core/page-slots.d.ts

@@ -0,0 +1,201 @@
+import type { ReactNode } from 'react';
+/**
+ * A page slot: a function component taking `Props`.
+ *
+ * Declared with a METHOD signature so the compiler compares its parameter
+ * BIVARIANTLY. That is what lets a page hand a slot MORE data than the base
+ * contract names (the database backup page's `Sections` also receives the
+ * policy and the runs) while the page's `slots` type still extends
+ * {@link PageSlotsBase}, and lets an app keep a slot component typed against
+ * an older, narrower props shape. Pass a plain function component (a class
+ * component is not a slot).
+ *
+ * @typeParam Props - what the page passes the slot.
+ * @stability experimental
+ */
+export type PageSlot<Props = object> = {
+    /** The slot component's call signature (declared as a method so its parameter is compared bivariantly). */
+    slot(props: Props): ReactNode;
+}['slot'];
+/**
+ * What a page passes its `Header` slot.
+ *
+ * `title` and `description` are the page's own words (the same text as its
+ * registry card, so the hub card, the rail row, the compact AppBar title and
+ * the page `h1` keep naming it identically); a custom header should print the
+ * title as the page's `h1`. `readOnly` is true when the viewer lacks the page's
+ * write permission (the default header appends " (read-only)"). `actions` is
+ * the page's header-level actions: `null` on a page whose default header
+ * carries none, which is every packaged operations page (their buttons sit in
+ * the body, so a custom header never loses them).
+ *
+ * @stability experimental
+ */
+export interface PageHeaderSlotProps {
+    /** The page title. A custom header prints it as the page's `h1`. */
+    title: ReactNode;
+    /** The page subtitle, when the page has one. */
+    description?: ReactNode;
+    /** The viewer lacks the page's write permission. */
+    readOnly?: boolean;
+    /** The page's header-level actions, or `null` when its default header has none. */
+    actions?: ReactNode;
+}
+/**
+ * What a page passes its `Sections` slot. The slot is rendered twice, once at
+ * each end of the page body: return `null` for the position you do not want.
+ *
+ * @stability experimental
+ */
+export interface PageSectionsSlotProps {
+    /** Where this rendering sits: `'top'` is under the header, `'bottom'` after the page's own content. */
+    position: 'top' | 'bottom';
+}
+/**
+ * The slots every packaged page offers. A page's `slots` prop extends this
+ * (`interface JobsPageSlots extends PageSlotsBase, TableSlots<Job> { Filters?: ... }`);
+ * every member is optional, and an absent slot leaves the page's markup exactly
+ * as it was.
+ *
+ * Order of the body: `Header`, `BeforeContent`, `Sections` (`top`), the page's
+ * own content, `Sections` (`bottom`), `AfterContent`. All of it sits inside the
+ * page's existing container, so a slot's controls live inside the landmark the
+ * page already has.
+ *
+ * @example
+ * ```tsx
+ * <JobsPage slots={{ BeforeContent: MaintenanceNotice, Sections: ({ position }) => position === 'bottom' ? <RunbookLinks /> : null }} />
+ * ```
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export interface PageSlotsBase {
+    /** Replaces the page header (title and subtitle). */
+    Header?: PageSlot<PageHeaderSlotProps>;
+    /** A banner or notice area under the header. */
+    BeforeContent?: PageSlot<object>;
+    /** Extra sections, rendered at both ends of the body (see {@link PageSectionsSlotProps}). */
+    Sections?: PageSlot<PageSectionsSlotProps>;
+    /** Content after everything else on the page. */
+    AfterContent?: PageSlot<object>;
+}
+/**
+ * The shape the table slots need of a column: what {@link useTableSlotColumns}
+ * builds an extra column from. Every table column type of this package (the
+ * jobs, nodes and database backup slices' `*TableColumn`, and the datatable
+ * slice's `DataTableColumn`) satisfies it.
+ *
+ * @typeParam Row - the row type.
+ * @stability experimental
+ */
+export interface SlotTableColumn<Row> {
+    /** Stable column id. */
+    id: string;
+    /** Header text. */
+    label: string;
+    /** Narrow-screen placement. */
+    priority: 'primary' | 'secondary' | 'detail';
+    /** Cell content. */
+    render?: (row: Row) => ReactNode;
+}
+/**
+ * The slots a page that draws a table offers, over the table's `Row`.
+ *
+ * `RowActions` and `DetailPanel` are drawn as extra columns the page appends
+ * (`More actions`, secondary priority; `Details`, detail priority), so they
+ * appear in the grid, the tablet expander and the phone card with no new
+ * table prop. `Columns` runs last and sees every column, the slots' included.
+ *
+ * @typeParam Row - the row type.
+ * @typeParam Column - the table's column type (a page binds its own).
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export interface TableSlots<Row, Column extends SlotTableColumn<Row> = SlotTableColumn<Row>> {
+    /** Add, reorder or remove columns: receives the page's columns, returns the ones to draw. */
+    Columns?: (base: Column[]) => Column[];
+    /** Extra per-row actions (buttons, a menu), drawn in an extra `More actions` column. */
+    RowActions?: PageSlot<{
+        row: Row;
+    }>;
+    /** Extra content in the row's detail view (an extra `Details` column of detail priority). */
+    DetailPanel?: PageSlot<{
+        row: Row;
+    }>;
+    /** Extra controls above the table. */
+    Toolbar?: PageSlot<object>;
+}
+/**
+ * Id of the column {@link useTableSlotColumns} adds for `RowActions`.
+ *
+ * @stability experimental
+ */
+export declare const SLOT_ROW_ACTIONS_COLUMN_ID = "slot-row-actions";
+/**
+ * Id of the column {@link useTableSlotColumns} adds for `DetailPanel`.
+ *
+ * @stability experimental
+ */
+export declare const SLOT_DETAIL_PANEL_COLUMN_ID = "slot-detail-panel";
+/**
+ * Applies a page's table slots to its columns.
+ *
+ * With no table slot it returns `columns` itself (the same array), so the
+ * table receives exactly what it always did. Otherwise it appends a
+ * `RowActions` column and a `DetailPanel` column (in that order), then hands
+ * the result to `Columns`.
+ *
+ * @param columns - the page's own columns (stable identity: the page memoises them).
+ * @param slots - the page's table slots, or `undefined`.
+ * @returns the columns to draw.
+ *
+ * @example
+ * ```tsx
+ * const columns = useTableSlotColumns(baseColumns, slots);
+ * ```
+ *
+ * @stability experimental
+ */
+export declare function useTableSlotColumns<Row, Column extends SlotTableColumn<Row>>(columns: Column[], slots: Pick<TableSlots<Row, Column>, 'Columns' | 'RowActions' | 'DetailPanel'> | undefined): Column[];
+/**
+ * What {@link PageSlotsFrame} takes.
+ *
+ * @stability experimental
+ */
+export interface PageSlotsFrameProps {
+    /** The page's `slots` prop. Only the members of {@link PageSlotsBase} are read. */
+    slots: PageSlotsBase | undefined;
+    /** The page's own header, drawn when `slots.Header` is absent. */
+    header: ReactNode;
+    /** What `slots.Header` receives (the page's title, subtitle and read-only state). */
+    headerProps: PageHeaderSlotProps;
+    /** The page's own content. */
+    children?: ReactNode;
+}
+/**
+ * Lays a page body out in the order the slot contract names: `Header` (or the
+ * page's own `header`), `BeforeContent`, `Sections` (`top`), the page's own
+ * `children`, `Sections` (`bottom`), `AfterContent`.
+ *
+ * It renders a fragment: no wrapper element and no style, so a page that passes
+ * no slot produces exactly the markup `header` and `children` produce by
+ * themselves. A page puts it INSIDE its existing container (the `Container` and
+ * the `Box` that pads it), which is why the slots live in the landmark the page
+ * already has.
+ *
+ * @example
+ * ```tsx
+ * <Container maxWidth="lg">
+ *   <PageSlotsFrame slots={slots} header={<MyHeader />} headerProps={{ title: 'My page' }}>
+ *     <MyContent />
+ *   </PageSlotsFrame>
+ * </Container>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function PageSlotsFrame({ slots, header, headerProps, children }: PageSlotsFrameProps): ReactNode;
+//# sourceMappingURL=page-slots.d.ts.map

package/dist/core/page-slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-slots.d.ts","sourceRoot":"","sources":["../../src/core/page-slots.tsx"],"names":[],"mappings":"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"}

package/dist/core/page-slots.js

@@ -0,0 +1,121 @@
+// =============================================================================
+// The packaged-page slot contract (PP-14.23)
+// =============================================================================
+//
+// Every packaged page exported by this package takes ONE optional prop,
+// `slots`, whose members are optional components (or, for the table, one
+// optional function). A page that is not passed a slot renders exactly the
+// markup it always rendered; a slot only ever ADDS to the page or replaces one
+// named part of it. The contract is the same on every page, so an app learns it
+// once:
+//
+//   - `PageSlotsBase`: Header, BeforeContent, Sections (top and bottom),
+//     AfterContent.
+//   - `TableSlots<Row>`: Columns, RowActions, DetailPanel, Toolbar, for a page
+//     that draws a table.
+//   - page-specific slots, each documented in the page's slice README.
+//
+// A slot receives DATA (the row, the check, the page's state it already holds),
+// never an API client and never a setter into the page's internals. An app that
+// needs to call the API from a slot uses its own client or `usePlatformApi()`:
+// the permission checks stay on the server.
+//
+// `test/page-slots.contract.test.ts` enforces it: every exported `*Page`
+// component either declares a `slots` prop typed to this contract or is listed,
+// with a reason, in `test/page-slots.exempt.json`.
+// =============================================================================
+import { Fragment, createElement, useMemo } from 'react';
+/**
+ * Id of the column {@link useTableSlotColumns} adds for `RowActions`.
+ *
+ * @stability experimental
+ */
+export const SLOT_ROW_ACTIONS_COLUMN_ID = 'slot-row-actions';
+/**
+ * Id of the column {@link useTableSlotColumns} adds for `DetailPanel`.
+ *
+ * @stability experimental
+ */
+export const SLOT_DETAIL_PANEL_COLUMN_ID = 'slot-detail-panel';
+/**
+ * Applies a page's table slots to its columns.
+ *
+ * With no table slot it returns `columns` itself (the same array), so the
+ * table receives exactly what it always did. Otherwise it appends a
+ * `RowActions` column and a `DetailPanel` column (in that order), then hands
+ * the result to `Columns`.
+ *
+ * @param columns - the page's own columns (stable identity: the page memoises them).
+ * @param slots - the page's table slots, or `undefined`.
+ * @returns the columns to draw.
+ *
+ * @example
+ * ```tsx
+ * const columns = useTableSlotColumns(baseColumns, slots);
+ * ```
+ *
+ * @stability experimental
+ */
+export function useTableSlotColumns(columns, slots) {
+    const Columns = slots?.Columns;
+    const RowActions = slots?.RowActions;
+    const DetailPanel = slots?.DetailPanel;
+    return useMemo(() => {
+        if (!Columns && !RowActions && !DetailPanel)
+            return columns;
+        let next = columns;
+        if (RowActions) {
+            const column = {
+                id: SLOT_ROW_ACTIONS_COLUMN_ID,
+                label: 'More actions',
+                priority: 'secondary',
+                exportable: false,
+                hideable: false,
+                render: (row) => createElement(RowActions, { row }),
+            };
+            next = [...next, column];
+        }
+        if (DetailPanel) {
+            const column = {
+                id: SLOT_DETAIL_PANEL_COLUMN_ID,
+                label: 'Details',
+                priority: 'detail',
+                exportable: false,
+                render: (row) => createElement(DetailPanel, { row }),
+            };
+            next = [...next, column];
+        }
+        return Columns ? Columns(next) : next;
+    }, [columns, Columns, RowActions, DetailPanel]);
+}
+/**
+ * Lays a page body out in the order the slot contract names: `Header` (or the
+ * page's own `header`), `BeforeContent`, `Sections` (`top`), the page's own
+ * `children`, `Sections` (`bottom`), `AfterContent`.
+ *
+ * It renders a fragment: no wrapper element and no style, so a page that passes
+ * no slot produces exactly the markup `header` and `children` produce by
+ * themselves. A page puts it INSIDE its existing container (the `Container` and
+ * the `Box` that pads it), which is why the slots live in the landmark the page
+ * already has.
+ *
+ * @example
+ * ```tsx
+ * <Container maxWidth="lg">
+ *   <PageSlotsFrame slots={slots} header={<MyHeader />} headerProps={{ title: 'My page' }}>
+ *     <MyContent />
+ *   </PageSlotsFrame>
+ * </Container>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function PageSlotsFrame({ slots, header, headerProps, children }) {
+    const Header = slots?.Header;
+    const BeforeContent = slots?.BeforeContent;
+    const Sections = slots?.Sections;
+    const AfterContent = slots?.AfterContent;
+    return createElement(Fragment, null, Header ? createElement(Header, headerProps) : header, BeforeContent ? createElement(BeforeContent) : null, Sections ? createElement(Sections, { position: 'top' }) : null, children, Sections ? createElement(Sections, { position: 'bottom' }) : null, AfterContent ? createElement(AfterContent) : null);
+}
+//# sourceMappingURL=page-slots.js.map

package/dist/core/page-slots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-slots.js","sourceRoot":"","sources":["../../src/core/page-slots.tsx"],"names":[],"mappings":"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"}

package/dist/core/settings-page.d.ts

@@ -0,0 +1,47 @@
+import type { ComponentType } from 'react';
+import type { SvgIcon } from '@mui/material';
+/**
+ * Descriptor a packaged admin/settings page exports; the app turns it into a
+ * registry card (`{ ...page.card, Icon: page.Icon }`, appended to the right
+ * section) and a route (`path={page.card.path}`, wrapped in the app's
+ * permission gate for `page.card.permission`).
+ *
+ * @typeParam TFeature - the feature keys `card.feature` may take; `never` for a
+ *   page that is never feature-gated, so the card is assignable to any app's
+ *   card type.
+ *
+ * @example
+ * ```tsx
+ * // apps/web/src/config/adminSections.tsx
+ * { ...doctorSettingsPage.card, Icon: doctorSettingsPage.Icon },
+ * // apps/web/src/App.tsx
+ * <Route path={doctorSettingsPage.card.path} element={
+ *   <RequirePermission permission={doctorSettingsPage.card.permission!}><DoctorPage /></RequirePermission>
+ * } />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export interface PlatformSettingsPage<TFeature extends string = string> {
+    /** Stable id, e.g. `'doctor'`. */
+    id: string;
+    /** The registry card: the same text the page shows as its title and subtitle. */
+    card: {
+        /** Card and page title. */
+        title: string;
+        /** Card text and page subtitle. */
+        description: string;
+        /** The route, e.g. `/admin/settings/doctor`. */
+        path: string;
+        /** The exact permission the packaged API route enforces; absent means any signed-in user. */
+        permission?: string;
+        /** A deployment feature the card exists under (hidden while it is off). */
+        feature?: TFeature;
+    };
+    /** Default icon (an MUI SvgIcon); the app may override it. */
+    Icon: typeof SvgIcon;
+    /** The route element; reads everything from `usePlatformHost()`. */
+    Page: ComponentType;
+}
+//# sourceMappingURL=settings-page.d.ts.map

package/dist/core/settings-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-page.d.ts","sourceRoot":"","sources":["../../src/core/settings-page.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,oBAAoB,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM;IACpE,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,iFAAiF;IACjF,IAAI,EAAE;QACJ,2BAA2B;QAC3B,KAAK,EAAE,MAAM,CAAC;QACd,mCAAmC;QACnC,WAAW,EAAE,MAAM,CAAC;QACpB,gDAAgD;QAChD,IAAI,EAAE,MAAM,CAAC;QACb,6FAA6F;QAC7F,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,2EAA2E;QAC3E,OAAO,CAAC,EAAE,QAAQ,CAAC;KACpB,CAAC;IACF,8DAA8D;IAC9D,IAAI,EAAE,OAAO,OAAO,CAAC;IACrB,oEAAoE;IACpE,IAAI,EAAE,aAAa,CAAC;CACrB"}

package/dist/core/settings-page.js

@@ -0,0 +1,5 @@
+// The settings-page descriptor (issue #696, PP-2.7). A packaged admin or
+// settings page exports one; the app turns it into a registry card and a route
+// (Settings UI Pattern: the app stays the owner of its registries and routes).
+export {};
+//# sourceMappingURL=settings-page.js.map

package/dist/core/settings-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-page.js","sourceRoot":"","sources":["../../src/core/settings-page.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,+EAA+E;AAC/E,+EAA+E"}

package/dist/core/viewer.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The signed-in viewer, as packaged pages may see it.
+ *
+ * @stability experimental
+ */
+export interface PlatformViewer {
+    /** The signed-in user's id, or `null` when nobody is signed in. */
+    userId: string | null;
+    /**
+     * The signed-in user's own email address, when the app shares it (issue
+     * #737: the email settings page names where its test message goes).
+     * Optional; a page treats its absence as unknown.
+     */
+    email?: string | null;
+    /** Whether the viewer holds `permission` (the exact string the API enforces). */
+    hasPermission(permission: string): boolean;
+    /** Feature switches the app exposes to settings surfaces (e.g. ai, telemetry). */
+    isFeatureEnabled(feature: string): boolean;
+    /**
+     * Re-reads the signed-in user (display name, avatar, roles) from the API.
+     * Optional. A page that changes the viewer's own account (the user-data
+     * pages after a deletion or a factory reset) calls it when it is present.
+     */
+    refresh?(): Promise<void>;
+}
+//# sourceMappingURL=viewer.d.ts.map

package/dist/core/viewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewer.d.ts","sourceRoot":"","sources":["../../src/core/viewer.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,iFAAiF;IACjF,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3C,kFAAkF;IAClF,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3C;;;;OAIG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

package/dist/core/viewer.js

@@ -0,0 +1,4 @@
+// The viewer port (issue #696, PP-2.7): who is looking, as a packaged page may
+// see it. The app's adapter derives it from its own auth context.
+export {};
+//# sourceMappingURL=viewer.js.map

package/dist/core/viewer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewer.js","sourceRoot":"","sources":["../../src/core/viewer.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,kEAAkE"}

package/dist/credentials/headless/index.d.ts

@@ -0,0 +1,3 @@
+export { savedSecretHelperText, secretForSubmit } from './saved-secret.js';
+export type { SavedSecretHelperTextOptions, SavedSecretInfo } from './saved-secret.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/credentials/headless/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/credentials/headless/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC3E,YAAY,EAAE,4BAA4B,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/credentials/headless/index.js

@@ -0,0 +1,5 @@
+// `@marinoscar/platform-web/credentials/headless`: the write-only secret
+// field's wording and submit rule, with no component (issue #735). Documented
+// in ../README.md.
+export { savedSecretHelperText, secretForSubmit } from './saved-secret.js';
+//# sourceMappingURL=index.js.map

package/dist/credentials/headless/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/credentials/headless/index.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,8EAA8E;AAC9E,mBAAmB;AAEnB,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/credentials/headless/saved-secret.d.ts

@@ -0,0 +1,75 @@
+import type { CredentialInfoDto } from '@marinoscar/platform-contract/credentials';
+/**
+ * What the page knows about the stored secret: the presentation fields of a
+ * credential info (`CredentialInfoDto` from `@marinoscar/platform-contract/credentials`),
+ * or `null` when nothing is stored.
+ *
+ * @stability experimental
+ */
+export type SavedSecretInfo = Pick<CredentialInfoDto, 'hint'> & Partial<Pick<CredentialInfoDto, 'label'>> & {
+    /** When it was last changed: an ISO string or a `Date`. */
+    readonly updatedAt?: string | Date | null;
+};
+/**
+ * Options of {@link savedSecretHelperText}.
+ *
+ * @stability experimental
+ */
+export interface SavedSecretHelperTextOptions {
+    /**
+     * What the secret is called in the sentence.
+     *
+     * @defaultValue `'key'`
+     */
+    readonly noun?: string;
+    /**
+     * The sentence when nothing is stored.
+     *
+     * @defaultValue `'No <noun> is saved yet.'`
+     */
+    readonly emptyHelp?: string;
+    /**
+     * Formats the last-change date.
+     *
+     * @defaultValue `date.toLocaleDateString()`
+     */
+    readonly formatDate?: (date: Date) => string;
+}
+/**
+ * The helper text under a write-only secret field.
+ *
+ * Saved: "A key is saved (••••abcd), updated 10/8/2026. Leave this blank to
+ * keep it, or type a new one to replace it." The hint and the date are left
+ * out when unknown, and the sentence still reads. Not saved: `emptyHelp`.
+ *
+ * @param info - the stored secret's presentation fields, or `null`/`undefined` when none is stored.
+ * @param options - the noun, the empty sentence and the date format.
+ * @returns the sentence.
+ *
+ * @example
+ * ```ts
+ * savedSecretHelperText({ hint: '••••abcd', updatedAt: '2026-10-08T00:00:00Z' }, { noun: 'secret access key' });
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function savedSecretHelperText(info: SavedSecretInfo | null | undefined, options?: SavedSecretHelperTextOptions): string;
+/**
+ * What to send for a write-only secret field: the typed value, or `undefined`
+ * when the field is blank, so the API keeps the stored secret ("blank
+ * preserves"). The value is sent byte for byte (never trimmed).
+ *
+ * @param value - the field's current value.
+ * @returns the value, or `undefined` for `''`.
+ *
+ * @example
+ * ```ts
+ * await api.patch('/admin/storage-config', { secretAccessKey: secretForSubmit(secret) });
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function secretForSubmit(value: string): string | undefined;
+//# sourceMappingURL=saved-secret.d.ts.map

package/dist/credentials/headless/saved-secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saved-secret.d.ts","sourceRoot":"","sources":["../../../src/credentials/headless/saved-secret.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AAEnF;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,GAC3D,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC,GAAG;IAC1C,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;CAC3C,CAAC;AAEJ;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC;CAC9C;AAOD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EACxC,OAAO,GAAE,4BAAiC,GACzC,MAAM,CASR;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjE"}

package/dist/credentials/headless/saved-secret.js

@@ -0,0 +1,67 @@
+// =============================================================================
+// The "saved secret" wording, once (issue #735, PP-8.8)
+// =============================================================================
+//
+// Five pages of the reference app render a write-only secret field with their
+// own hint sentence (storage, e-mail, the AI provider card, the telemetry
+// connection, a user's own AI key). This is the unified sentence, headless, for
+// an app that renders its own field; `SecretField` (../ui) uses it.
+//
+// Secrets are WRITE-ONLY: the API never returns one, only the store's
+// non-secret `hint` (`••••abcd`). A blank field therefore means "keep what is
+// stored", which is what the sentence tells the user and what
+// `secretForSubmit` sends.
+// =============================================================================
+/** `a key`, `an access key`. */
+function withArticle(noun) {
+    return /^[aeiou]/i.test(noun) ? `An ${noun}` : `A ${noun}`;
+}
+/**
+ * The helper text under a write-only secret field.
+ *
+ * Saved: "A key is saved (••••abcd), updated 10/8/2026. Leave this blank to
+ * keep it, or type a new one to replace it." The hint and the date are left
+ * out when unknown, and the sentence still reads. Not saved: `emptyHelp`.
+ *
+ * @param info - the stored secret's presentation fields, or `null`/`undefined` when none is stored.
+ * @param options - the noun, the empty sentence and the date format.
+ * @returns the sentence.
+ *
+ * @example
+ * ```ts
+ * savedSecretHelperText({ hint: '••••abcd', updatedAt: '2026-10-08T00:00:00Z' }, { noun: 'secret access key' });
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function savedSecretHelperText(info, options = {}) {
+    const noun = options.noun ?? 'key';
+    if (!info)
+        return options.emptyHelp ?? `No ${noun} is saved yet.`;
+    const which = info.hint ? ` (${info.hint})` : '';
+    const date = info.updatedAt ? new Date(info.updatedAt) : null;
+    const format = options.formatDate ?? ((d) => d.toLocaleDateString());
+    const when = date && !Number.isNaN(date.getTime()) ? `, updated ${format(date)}` : '';
+    return `${withArticle(noun)} is saved${which}${when}. Leave this blank to keep it, or type a new one to replace it.`;
+}
+/**
+ * What to send for a write-only secret field: the typed value, or `undefined`
+ * when the field is blank, so the API keeps the stored secret ("blank
+ * preserves"). The value is sent byte for byte (never trimmed).
+ *
+ * @param value - the field's current value.
+ * @returns the value, or `undefined` for `''`.
+ *
+ * @example
+ * ```ts
+ * await api.patch('/admin/storage-config', { secretAccessKey: secretForSubmit(secret) });
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function secretForSubmit(value) {
+    return value === '' ? undefined : value;
+}
+//# sourceMappingURL=saved-secret.js.map

package/dist/credentials/headless/saved-secret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"saved-secret.js","sourceRoot":"","sources":["../../../src/credentials/headless/saved-secret.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,wDAAwD;AACxD,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,gFAAgF;AAChF,oEAAoE;AACpE,EAAE;AACF,sEAAsE;AACtE,8EAA8E;AAC9E,8DAA8D;AAC9D,2BAA2B;AAC3B,gFAAgF;AA2ChF,gCAAgC;AAChC,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAwC,EACxC,UAAwC,EAAE;IAE1C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,KAAK,CAAC;IACnC,IAAI,CAAC,IAAI;QAAE,OAAO,OAAO,CAAC,SAAS,IAAI,MAAM,IAAI,gBAAgB,CAAC;IAElE,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9D,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC,CAAO,EAAE,EAAE,CAAC,CAAC,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAC3E,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACtF,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,YAAY,KAAK,GAAG,IAAI,iEAAiE,CAAC;AACvH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AAC1C,CAAC"}

package/dist/credentials/index.d.ts

@@ -0,0 +1,5 @@
+export { SecretField } from './ui/secret-field.js';
+export type { SecretFieldProps, SecretFieldSlots } from './ui/secret-field.js';
+export { savedSecretHelperText, secretForSubmit } from './headless/index.js';
+export type { SavedSecretHelperTextOptions, SavedSecretInfo } from './headless/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/credentials/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC7E,YAAY,EAAE,4BAA4B,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}