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

package/dist/onboarding/headless/feature-notices.d.ts

@@ -0,0 +1,56 @@
+/**
+ * One feature a notice can be about.
+ *
+ * @stability experimental
+ */
+export interface FeatureNoticeDef {
+    /** The feature key (`ai`, `storage`, `push`, an app's own). */
+    feature: string;
+    /** Its name in copy: "<label> isn't enabled yet". */
+    label: string;
+    /** The exact admin read permission of its settings page; its holders see "Set it up". */
+    adminPermission: string;
+    /** The admin settings page that turns it on. */
+    setupHref: string;
+}
+/**
+ * The built-in notices; the permissions are the exact strings the admin
+ * controllers enforce (`ai_config:read`, `storage_config:read`, `push:read`).
+ *
+ * @stability experimental
+ */
+export declare const PLATFORM_FEATURE_NOTICES: readonly FeatureNoticeDef[];
+/**
+ * Registers (or, for an existing key, replaces) a feature notice. Call at
+ * module scope.
+ *
+ * @param def - the notice.
+ * @throws Error when a field is blank or `setupHref` is not an app route.
+ *
+ * @example
+ * ```ts
+ * registerFeatureNotice({ feature: 'maps', label: 'Maps', adminPermission: 'system_settings:read', setupHref: '/admin/settings/maps' });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function registerFeatureNotice(def: FeatureNoticeDef): void;
+/**
+ * The notice for `feature`, or `undefined` when none is registered.
+ *
+ * @param feature - the feature key.
+ * @returns the notice.
+ *
+ * @stability experimental
+ */
+export declare function featureNoticeFor(feature: string): FeatureNoticeDef | undefined;
+/**
+ * Every registered notice, in registration order.
+ *
+ * @returns the notices.
+ *
+ * @stability experimental
+ */
+export declare function registeredFeatureNotices(): FeatureNoticeDef[];
+//# sourceMappingURL=feature-notices.d.ts.map

package/dist/onboarding/headless/feature-notices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-notices.d.ts","sourceRoot":"","sources":["../../../src/onboarding/headless/feature-notices.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,eAAe,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,gBAAgB,EAI9D,CAAC;AAIH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAMjE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAE9E;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,IAAI,gBAAgB,EAAE,CAE7D"}

package/dist/onboarding/headless/feature-notices.js

@@ -0,0 +1,62 @@
+// The feature-notice registry (issue #745): what `FeatureUnavailableNotice`
+// says about a feature that is not set up, and where an administrator fixes
+// it. The permission only picks the words; the admin route and the API keep
+// their own gates.
+/**
+ * The built-in notices; the permissions are the exact strings the admin
+ * controllers enforce (`ai_config:read`, `storage_config:read`, `push:read`).
+ *
+ * @stability experimental
+ */
+export const PLATFORM_FEATURE_NOTICES = Object.freeze([
+    { feature: 'ai', label: 'AI', adminPermission: 'ai_config:read', setupHref: '/admin/settings/ai' },
+    { feature: 'storage', label: 'Storage', adminPermission: 'storage_config:read', setupHref: '/admin/settings/storage' },
+    { feature: 'push', label: 'Web Push', adminPermission: 'push:read', setupHref: '/admin/settings/push' },
+]);
+const notices = new Map(PLATFORM_FEATURE_NOTICES.map((def) => [def.feature, def]));
+/**
+ * Registers (or, for an existing key, replaces) a feature notice. Call at
+ * module scope.
+ *
+ * @param def - the notice.
+ * @throws Error when a field is blank or `setupHref` is not an app route.
+ *
+ * @example
+ * ```ts
+ * registerFeatureNotice({ feature: 'maps', label: 'Maps', adminPermission: 'system_settings:read', setupHref: '/admin/settings/maps' });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export function registerFeatureNotice(def) {
+    for (const field of ['feature', 'label', 'adminPermission', 'setupHref']) {
+        if (typeof def[field] !== 'string' || def[field].trim() === '')
+            throw new Error(`registerFeatureNotice: ${field} is required`);
+    }
+    if (!def.setupHref.startsWith('/'))
+        throw new Error('registerFeatureNotice: setupHref must be an app route starting with "/"');
+    notices.set(def.feature, Object.freeze({ ...def }));
+}
+/**
+ * The notice for `feature`, or `undefined` when none is registered.
+ *
+ * @param feature - the feature key.
+ * @returns the notice.
+ *
+ * @stability experimental
+ */
+export function featureNoticeFor(feature) {
+    return notices.get(feature);
+}
+/**
+ * Every registered notice, in registration order.
+ *
+ * @returns the notices.
+ *
+ * @stability experimental
+ */
+export function registeredFeatureNotices() {
+    return [...notices.values()];
+}
+//# sourceMappingURL=feature-notices.js.map

package/dist/onboarding/headless/feature-notices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-notices.js","sourceRoot":"","sources":["../../../src/onboarding/headless/feature-notices.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,4EAA4E;AAC5E,4EAA4E;AAC5E,mBAAmB;AAkBnB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAgC,MAAM,CAAC,MAAM,CAAC;IACjF,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,gBAAgB,EAAE,SAAS,EAAE,oBAAoB,EAAE;IAClG,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,qBAAqB,EAAE,SAAS,EAAE,yBAAyB,EAAE;IACtH,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,SAAS,EAAE,sBAAsB,EAAE;CACxG,CAAC,CAAC;AAEH,MAAM,OAAO,GAAG,IAAI,GAAG,CAA2B,wBAAwB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;AAE7G;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAqB;IACzD,KAAK,MAAM,KAAK,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,iBAAiB,EAAE,WAAW,CAAU,EAAE,CAAC;QAClF,IAAI,OAAO,GAAG,CAAC,KAAK,CAAC,KAAK,QAAQ,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,KAAK,cAAc,CAAC,CAAC;IACjI,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAC;IAC/H,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAC/B,CAAC"}

package/dist/onboarding/headless/getting-started.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The "Getting started" user-menu action.
+ *
+ * @stability experimental
+ */
+export interface GettingStartedAction {
+    /** Show the menu item: under a provider, once the state has loaded. */
+    visible: boolean;
+    /** The item's label. */
+    label: string;
+    /** Clears the stored welcome and dismissals, so the dialog and the checklists return. Never throws. */
+    run(): Promise<void>;
+}
+/**
+ * The label of the "Getting started" action.
+ *
+ * @stability experimental
+ */
+export declare const GETTING_STARTED_LABEL = "Getting started";
+/**
+ * The "Getting started" action for the app's own user menu.
+ *
+ * @returns the action.
+ *
+ * @example
+ * ```tsx
+ * const gettingStarted = useGettingStartedAction();
+ * {gettingStarted.visible && <MenuItem onClick={() => void gettingStarted.run()}>{gettingStarted.label}</MenuItem>}
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useGettingStartedAction(): GettingStartedAction;
+//# sourceMappingURL=getting-started.d.ts.map

package/dist/onboarding/headless/getting-started.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getting-started.d.ts","sourceRoot":"","sources":["../../../src/onboarding/headless/getting-started.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;IACjB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,uGAAuG;IACvG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,IAAI,oBAAoB,CAI9D"}

package/dist/onboarding/headless/getting-started.js

@@ -0,0 +1,28 @@
+import { useCallback } from 'react';
+import { useOnboarding } from './provider.js';
+/**
+ * The label of the "Getting started" action.
+ *
+ * @stability experimental
+ */
+export const GETTING_STARTED_LABEL = 'Getting started';
+/**
+ * The "Getting started" action for the app's own user menu.
+ *
+ * @returns the action.
+ *
+ * @example
+ * ```tsx
+ * const gettingStarted = useGettingStartedAction();
+ * {gettingStarted.visible && <MenuItem onClick={() => void gettingStarted.run()}>{gettingStarted.label}</MenuItem>}
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useGettingStartedAction() {
+    const { available, state, reopen } = useOnboarding();
+    const run = useCallback(() => reopen(), [reopen]);
+    return { visible: available && state !== null, label: GETTING_STARTED_LABEL, run };
+}
+//# sourceMappingURL=getting-started.js.map

package/dist/onboarding/headless/getting-started.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getting-started.js","sourceRoot":"","sources":["../../../src/onboarding/headless/getting-started.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAEpC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAgB9C;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,iBAAiB,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,aAAa,EAAE,CAAC;IACrD,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAClD,OAAO,EAAE,OAAO,EAAE,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,KAAK,EAAE,qBAAqB,EAAE,GAAG,EAAE,CAAC;AACrF,CAAC"}

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

@@ -0,0 +1,12 @@
+export type { OnboardingBlock, OnboardingFunnelStep, OnboardingMetricsResponse, OnboardingMilestoneMetric, OnboardingResponse, OnboardingState, OnboardingStep, } from '@marinoscar/platform-contract/onboarding';
+export { createOnboardingClient } from './client.js';
+export type { OnboardingClient, OnboardingSettingsWrite } from './client.js';
+export { ONBOARDING_INERT, OnboardingProvider, useOnboarding } from './provider.js';
+export type { OnboardingProviderProps, UseOnboardingReturn } from './provider.js';
+export { useOnboardingMetrics } from './use-onboarding-metrics.js';
+export type { UseOnboardingMetricsReturn } from './use-onboarding-metrics.js';
+export { PLATFORM_FEATURE_NOTICES, featureNoticeFor, registerFeatureNotice, registeredFeatureNotices, } from './feature-notices.js';
+export type { FeatureNoticeDef } from './feature-notices.js';
+export { GETTING_STARTED_LABEL, useGettingStartedAction } from './getting-started.js';
+export type { GettingStartedAction } from './getting-started.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/onboarding/headless/index.ts"],"names":[],"mappings":"AAKA,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,yBAAyB,EACzB,yBAAyB,EACzB,kBAAkB,EAClB,eAAe,EACf,cAAc,GACf,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACpF,YAAY,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACtF,YAAY,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/onboarding/headless/index.js

@@ -0,0 +1,10 @@
+// `@marinoscar/platform-web/onboarding/headless`: the onboarding client, the
+// provider and its hooks, the feature-notice registry and the "Getting
+// started" action, with no component but the provider (issue #745).
+// Documented in ../README.md.
+export { createOnboardingClient } from './client.js';
+export { ONBOARDING_INERT, OnboardingProvider, useOnboarding } from './provider.js';
+export { useOnboardingMetrics } from './use-onboarding-metrics.js';
+export { PLATFORM_FEATURE_NOTICES, featureNoticeFor, registerFeatureNotice, registeredFeatureNotices, } from './feature-notices.js';
+export { GETTING_STARTED_LABEL, useGettingStartedAction } from './getting-started.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/onboarding/headless/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,uEAAuE;AACvE,oEAAoE;AACpE,8BAA8B;AAW9B,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEnE,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/onboarding/headless/provider.d.ts

@@ -0,0 +1,94 @@
+import type { OnboardingResponse } from '@marinoscar/platform-contract/onboarding';
+import type { ReactElement, ReactNode } from 'react';
+import type { OnboardingClient, OnboardingSettingsWrite } from './client.js';
+/**
+ * What {@link useOnboarding} returns.
+ *
+ * @stability experimental
+ */
+export interface UseOnboardingReturn {
+    /** True under an {@link OnboardingProvider}; false for the inert answer. */
+    available: boolean;
+    /** The app's display name (for copy), from the provider. */
+    appName: string;
+    /** The last read with the optimistic overlay applied; `null` until it resolves, when it failed or without `user_settings:read`. */
+    state: OnboardingResponse | null;
+    /** True only until the first read settles. */
+    isLoading: boolean;
+    /** A later re-read is in flight. */
+    isRefreshing: boolean;
+    /** The last request failure, as a sentence. */
+    error: string | null;
+    /** Re-read; `refresh: true` asks the API to re-run the Doctor probes. Never throws. */
+    refresh(options?: {
+        refresh?: boolean;
+    }): Promise<void>;
+    /** Writes stored UI state (platform or app fields; `null` clears one). Never throws. */
+    update(patch: OnboardingSettingsWrite): Promise<void>;
+    /** Closes the welcome for good, with optional app fields (a goal). Never throws. */
+    markWelcomeSeen(extra?: OnboardingSettingsWrite): Promise<void>;
+    /** Hides the Get started checklist. Never throws. */
+    dismissChecklist(): Promise<void>;
+    /** Hides the administrator's setup prompt. Never throws. */
+    dismissAdmin(): Promise<void>;
+    /** Skips (or, with `false`, un-skips) a skippable step. Never throws. */
+    setSkipped(stepId: string, skipped: boolean): Promise<void>;
+    /** Shows the welcome and the checklists again ("Getting started"). Never throws. */
+    reopen(): Promise<void>;
+}
+/**
+ * The answer without a provider: nothing to show, nothing to do.
+ *
+ * @stability experimental
+ */
+export declare const ONBOARDING_INERT: UseOnboardingReturn;
+/**
+ * What {@link OnboardingProvider} takes.
+ *
+ * @stability experimental
+ */
+export interface OnboardingProviderProps {
+    /** The routed shell. */
+    children: ReactNode;
+    /** The app's display name, used in the welcome and the Setup guide. Default `'this app'`. */
+    appName?: string;
+    /** The client to use. Default: `createOnboardingClient(host.api)`; keep its identity stable. */
+    client?: OnboardingClient;
+}
+/**
+ * Runs `GET /api/onboarding` once for everything below it. Mount it once,
+ * inside the platform host provider, around the authenticated shell.
+ *
+ * @param props - see {@link OnboardingProviderProps}.
+ * @returns the provider element.
+ * @throws Error when no `client` is given and no `PlatformHostProvider` is mounted.
+ *
+ * @example
+ * ```tsx
+ * <AppPlatformHostProvider>
+ *   <OnboardingProvider appName={APP_NAME}>
+ *     <Layout />
+ *   </OnboardingProvider>
+ * </AppPlatformHostProvider>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function OnboardingProvider(props: OnboardingProviderProps): ReactElement;
+/**
+ * The shell's shared onboarding state, or {@link ONBOARDING_INERT} with no
+ * {@link OnboardingProvider} above.
+ *
+ * @returns the state and its actions.
+ *
+ * @example
+ * ```tsx
+ * const { state, markWelcomeSeen } = useOnboarding();
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useOnboarding(): UseOnboardingReturn;
+//# sourceMappingURL=provider.d.ts.map

package/dist/onboarding/headless/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/onboarding/headless/provider.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,kBAAkB,EAAmB,MAAM,0CAA0C,CAAC;AAEpG,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE7E;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,SAAS,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,mIAAmI;IACnI,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACjC,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,oCAAoC;IACpC,YAAY,EAAE,OAAO,CAAC;IACtB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uFAAuF;IACvF,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,wFAAwF;IACxF,MAAM,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,oFAAoF;IACpF,eAAe,CAAC,KAAK,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,qDAAqD;IACrD,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,4DAA4D;IAC5D,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,yEAAyE;IACzE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,oFAAoF;IACpF,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAID;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,mBAc7B,CAAC;AA6BH;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,wBAAwB;IACxB,QAAQ,EAAE,SAAS,CAAC;IACpB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gGAAgG;IAChG,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,YAAY,CAmG/E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,IAAI,mBAAmB,CAEnD"}

package/dist/onboarding/headless/provider.js

@@ -0,0 +1,204 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// =============================================================================
+// OnboardingProvider and useOnboarding (issue #745, PP-9.3)
+// =============================================================================
+//
+// ONE FETCH PER SHELL. The welcome dialog, the checklists, the user menu's
+// "Getting started" and the Setup guide all read the same answer, so the app
+// mounts `OnboardingProvider` once around its authenticated shell. With no
+// provider above it, `useOnboarding` answers an inert "nothing to show" and
+// requests nothing (chrome rendered alone, tests, previews).
+//
+// DERIVED, NOT STORED. Every step's status comes from `GET /api/onboarding`.
+// The browser writes only UI state (welcome seen, a checklist dismissed, a
+// step skipped) through `PATCH /api/user-settings` with `If-Match`.
+//
+// WRITES ARE OPTIMISTIC: closing the dialog closes it now. The written fields
+// overlay the last read until the re-read lands; a FAILED write keeps the
+// overlay for the session (a dialog that comes back after being closed is
+// worse than a preference that did not persist) and reports `error`.
+// =============================================================================
+import { ONBOARDING_READ_PERMISSION } from '@marinoscar/platform-contract/onboarding';
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { isPlatformApiError, useOptionalPlatformHost } from '../../core/index.js';
+import { useIsMounted } from '../internal/use-is-mounted.js';
+import { createOnboardingClient } from './client.js';
+const noop = async () => undefined;
+/**
+ * The answer without a provider: nothing to show, nothing to do.
+ *
+ * @stability experimental
+ */
+export const ONBOARDING_INERT = Object.freeze({
+    available: false,
+    appName: '',
+    state: null,
+    isLoading: false,
+    isRefreshing: false,
+    error: null,
+    refresh: noop,
+    update: noop,
+    markWelcomeSeen: noop,
+    dismissChecklist: noop,
+    dismissAdmin: noop,
+    setSkipped: noop,
+    reopen: noop,
+});
+const OnboardingContext = createContext(null);
+OnboardingContext.displayName = 'OnboardingContext';
+function messageFor(err, fallback) {
+    return isPlatformApiError(err) && err.message ? err.message : fallback;
+}
+function applyOverlay(state, overlay) {
+    if (!overlay)
+        return state;
+    const settings = { ...state.settings };
+    for (const [key, value] of Object.entries(overlay)) {
+        settings[key] = value === null ? (key === 'skipped' ? [] : null) : value;
+    }
+    const skipped = new Set(settings['skipped'] ?? []);
+    const mark = (block) => {
+        const steps = block.steps.map((step) => ({ ...step, skipped: step.skippable && skipped.has(step.id) }));
+        return { ...block, steps, allResolved: steps.every((step) => step.status === 'done' || step.skipped) };
+    };
+    return {
+        settings: settings,
+        user: mark(state.user),
+        admin: state.admin ? mark(state.admin) : null,
+        // The other audiences' blocks (org_admin, an app's own) keep their skips in step with the overlay.
+        ...(state.audiences ? { audiences: Object.fromEntries(Object.entries(state.audiences).map(([id, block]) => [id, mark(block)])) } : {}),
+    };
+}
+/**
+ * Runs `GET /api/onboarding` once for everything below it. Mount it once,
+ * inside the platform host provider, around the authenticated shell.
+ *
+ * @param props - see {@link OnboardingProviderProps}.
+ * @returns the provider element.
+ * @throws Error when no `client` is given and no `PlatformHostProvider` is mounted.
+ *
+ * @example
+ * ```tsx
+ * <AppPlatformHostProvider>
+ *   <OnboardingProvider appName={APP_NAME}>
+ *     <Layout />
+ *   </OnboardingProvider>
+ * </AppPlatformHostProvider>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function OnboardingProvider(props) {
+    const host = useOptionalPlatformHost();
+    const api = host?.api;
+    const client = useMemo(() => {
+        if (props.client)
+            return props.client;
+        if (!api) {
+            throw new Error('OnboardingProvider: no PlatformHostProvider above this component and no client was passed. ' +
+                'Mount PlatformHostProvider (from @marinoscar/platform-web/core) or pass createOnboardingClient(api).');
+        }
+        return createOnboardingClient(api);
+    }, [props.client, api]);
+    const canRead = host ? host.viewer.hasPermission(ONBOARDING_READ_PERMISSION) : true;
+    const isMounted = useIsMounted();
+    const [state, setState] = useState(null);
+    const [isLoading, setIsLoading] = useState(canRead);
+    const [isRefreshing, setIsRefreshing] = useState(false);
+    const [error, setError] = useState(null);
+    const [overlay, setOverlay] = useState(null);
+    const loaded = useRef(false);
+    const writeSeq = useRef(0);
+    const refresh = useCallback(async (options = {}) => {
+        if (!canRead) {
+            if (isMounted())
+                setIsLoading(false);
+            return;
+        }
+        try {
+            if (loaded.current)
+                setIsRefreshing(true);
+            setError(null);
+            const data = await client.get(options.refresh ? { refresh: true } : {});
+            loaded.current = true;
+            if (isMounted())
+                setState(data);
+        }
+        catch (err) {
+            if (isMounted())
+                setError(messageFor(err, 'Failed to load the getting-started steps'));
+        }
+        finally {
+            if (isMounted()) {
+                setIsLoading(false);
+                setIsRefreshing(false);
+            }
+        }
+    }, [canRead, client, isMounted]);
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    const update = useCallback(async (patch) => {
+        const seq = ++writeSeq.current;
+        setOverlay((current) => ({ ...(current ?? {}), ...patch }));
+        try {
+            await client.write(patch);
+        }
+        catch (err) {
+            if (isMounted())
+                setError(messageFor(err, 'Failed to save your onboarding progress'));
+            return;
+        }
+        await refresh();
+        if (isMounted() && writeSeq.current === seq)
+            setOverlay(null);
+    }, [client, refresh, isMounted]);
+    const skippedNow = useCallback(() => {
+        const fromOverlay = overlay?.['skipped'];
+        if (Array.isArray(fromOverlay))
+            return fromOverlay;
+        return state?.settings.skipped ?? [];
+    }, [overlay, state]);
+    const value = useMemo(() => ({
+        available: true,
+        appName: props.appName ?? 'this app',
+        state: state ? applyOverlay(state, overlay) : null,
+        isLoading,
+        isRefreshing,
+        error,
+        refresh,
+        update,
+        markWelcomeSeen: (extra) => update({ ...(extra ?? {}), welcomeSeenAt: new Date().toISOString() }),
+        dismissChecklist: () => update({ checklistDismissedAt: new Date().toISOString() }),
+        dismissAdmin: () => update({ adminDismissedAt: new Date().toISOString() }),
+        setSkipped: (stepId, skipped) => {
+            const current = new Set(skippedNow());
+            if (skipped)
+                current.add(stepId);
+            else
+                current.delete(stepId);
+            return update({ skipped: current.size > 0 ? [...current] : null });
+        },
+        reopen: () => update({ welcomeSeenAt: null, checklistDismissedAt: null, adminDismissedAt: null }),
+    }), [props.appName, state, overlay, isLoading, isRefreshing, error, refresh, update, skippedNow]);
+    return _jsx(OnboardingContext.Provider, { value: value, children: props.children });
+}
+/**
+ * The shell's shared onboarding state, or {@link ONBOARDING_INERT} with no
+ * {@link OnboardingProvider} above.
+ *
+ * @returns the state and its actions.
+ *
+ * @example
+ * ```tsx
+ * const { state, markWelcomeSeen } = useOnboarding();
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useOnboarding() {
+    return useContext(OnboardingContext) ?? ONBOARDING_INERT;
+}
+//# sourceMappingURL=provider.js.map

package/dist/onboarding/headless/provider.js.map

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

package/dist/onboarding/headless/use-onboarding-metrics.d.ts

@@ -0,0 +1,35 @@
+import type { OnboardingMetricsResponse } from '@marinoscar/platform-contract/onboarding';
+import type { OnboardingClient } from './client.js';
+/**
+ * What {@link useOnboardingMetrics} returns.
+ *
+ * @stability experimental
+ */
+export interface UseOnboardingMetricsReturn {
+    /** `null` until the first read resolves. */
+    metrics: OnboardingMetricsResponse | null;
+    /** A read is in flight. */
+    isLoading: boolean;
+    /** The request failed. */
+    error: string | null;
+    /** Read again. Never throws. */
+    reload(): Promise<void>;
+}
+/**
+ * Loads `GET /admin/onboarding/metrics?days=` (aggregates only).
+ *
+ * @param days - the cohort window, in days.
+ * @param client - the client. Default: `createOnboardingClient(host.api)`.
+ * @returns the metrics, the loading flag, the error and `reload`.
+ * @throws Error when no `client` is given and no `PlatformHostProvider` is mounted.
+ *
+ * @example
+ * ```tsx
+ * const { metrics } = useOnboardingMetrics(30);
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useOnboardingMetrics(days: number, client?: OnboardingClient): UseOnboardingMetricsReturn;
+//# sourceMappingURL=use-onboarding-metrics.d.ts.map

package/dist/onboarding/headless/use-onboarding-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-onboarding-metrics.d.ts","sourceRoot":"","sources":["../../../src/onboarding/headless/use-onboarding-metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,0CAA0C,CAAC;AAM1F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,4CAA4C;IAC5C,OAAO,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC1C,2BAA2B;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,0BAA0B;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,gCAAgC;IAChC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,0BAA0B,CAiCxG"}

package/dist/onboarding/headless/use-onboarding-metrics.js

@@ -0,0 +1,58 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { isPlatformApiError, useOptionalPlatformHost } from '../../core/index.js';
+import { useIsMounted } from '../internal/use-is-mounted.js';
+import { createOnboardingClient } from './client.js';
+/**
+ * Loads `GET /admin/onboarding/metrics?days=` (aggregates only).
+ *
+ * @param days - the cohort window, in days.
+ * @param client - the client. Default: `createOnboardingClient(host.api)`.
+ * @returns the metrics, the loading flag, the error and `reload`.
+ * @throws Error when no `client` is given and no `PlatformHostProvider` is mounted.
+ *
+ * @example
+ * ```tsx
+ * const { metrics } = useOnboardingMetrics(30);
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useOnboardingMetrics(days, client) {
+    const host = useOptionalPlatformHost();
+    const api = host?.api;
+    const resolved = useMemo(() => {
+        if (client)
+            return client;
+        if (!api)
+            throw new Error('useOnboardingMetrics: no PlatformHostProvider above this component and no client was passed.');
+        return createOnboardingClient(api);
+    }, [client, api]);
+    const [metrics, setMetrics] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const isMounted = useIsMounted();
+    const reload = useCallback(async () => {
+        try {
+            setIsLoading(true);
+            setError(null);
+            const data = await resolved.metrics(days);
+            if (isMounted())
+                setMetrics(data);
+        }
+        catch (err) {
+            if (isMounted()) {
+                setError(isPlatformApiError(err) && err.status === 403 ? 'You do not have permission to see activation metrics' : 'Failed to load the activation metrics');
+            }
+        }
+        finally {
+            if (isMounted())
+                setIsLoading(false);
+        }
+    }, [resolved, days, isMounted]);
+    useEffect(() => {
+        void reload();
+    }, [reload]);
+    return { metrics, isLoading, error, reload };
+}
+//# sourceMappingURL=use-onboarding-metrics.js.map

package/dist/onboarding/headless/use-onboarding-metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-onboarding-metrics.js","sourceRoot":"","sources":["../../../src/onboarding/headless/use-onboarding-metrics.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAElE,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAmBrD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,MAAyB;IAC1E,MAAM,IAAI,GAAG,uBAAuB,EAAE,CAAC;IACvC,MAAM,GAAG,GAAG,IAAI,EAAE,GAAG,CAAC;IACtB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE;QAC5B,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAC1B,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,8FAA8F,CAAC,CAAC;QAC1H,OAAO,sBAAsB,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAClB,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAmC,IAAI,CAAC,CAAC;IAC/E,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IACjD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IACxD,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IAEjC,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;QACpC,IAAI,CAAC;YACH,YAAY,CAAC,IAAI,CAAC,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,CAAC;YACf,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC1C,IAAI,SAAS,EAAE;gBAAE,UAAU,CAAC,IAAI,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,SAAS,EAAE,EAAE,CAAC;gBAChB,QAAQ,CAAC,kBAAkB,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,sDAAsD,CAAC,CAAC,CAAC,uCAAuC,CAAC,CAAC;YAC7J,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,SAAS,EAAE;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;IACH,CAAC,EAAE,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;IAEhC,SAAS,CAAC,GAAG,EAAE;QACb,KAAK,MAAM,EAAE,CAAC;IAChB,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC/C,CAAC"}