@phis/ui 0.2.0 → 0.3.0

package/plugins/runtime-modules/tour/controller/client.js

@@ -0,0 +1,162 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../../types/signals";
+import { PhiTourControl } from "../../../../components/controls/phi-tour-control";
+import { createPhiRuntimeControllerClient } from "../../../../components/runtime/runtime-controller-client-factory";
+import { usePhiSignalDispatcher, usePhiSignalListener } from "../../../../components/runtime/runtime-signal-bus";
+import { usePhiSignalRuntimePartition } from "../../../../components/runtime/runtime-signal-partition";
+import { readPhiVisualAnchor, waitForPhiVisualAnchor } from "../../../../components/runtime/runtime-visual-anchors";
+import { fetchPhiUserState, writePhiUserState } from "../../../../components/runtime/user-state-client";
+import { PHI_TOUR_PROGRESS_USER_STATE_KEY } from "../ids";
+import { PHI_TOUR_RUNTIME_CONTROLLER_DEFINITION } from "./definition";
+import { readPhiTourProgress, recordPhiTourProgress, shouldOfferPhiTour, } from "./progress";
+/** How long a step waits for its target before its `ifMissing` decides. */
+const TARGET_WAIT_MS = 4000;
+const PROGRESS_DESCRIPTOR = {
+    key: PHI_TOUR_PROGRESS_USER_STATE_KEY,
+    shape: "value",
+    valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.tourProgress,
+};
+const TOUR_LISTEN_FILTER = { scopes: ["area"], channels: ["tour"] };
+function PhiTourControllerView({ address, config }) {
+    const partition = usePhiSignalRuntimePartition();
+    const dispatchSignal = usePhiSignalDispatcher();
+    const tour = config.pageTour;
+    const [storedRun, setRun] = useState(null);
+    // A Tour still running from the previous Page ends with it, unrecorded: it is not this Page's.
+    const run = storedRun && storedRun.tour.id === tour?.id ? storedRun : null;
+    /*
+     * The viewer's progress as last read or written: `undefined` while unread, `null` where there is no
+     * account to keep it on. A first visit is offered only where this answered -- a Tour that opens by
+     * itself on every visit because nothing could be remembered is worse than none.
+     */
+    const progressRef = useRef(undefined);
+    /*
+     * The Tour already offered on this Page. The config arrives as a new object on every render of the
+     * Area, so the offer is keyed by the Tour's id, not by the object -- otherwise it restarts each time.
+     */
+    const offeredRef = useRef(null);
+    const available = tour != null;
+    const announce = useCallback((correlationId) => {
+        dispatchSignal({
+            scope: "area",
+            channel: "tour",
+            action: "change",
+            value: { available },
+            valueType: "json",
+            valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.tourAvailability,
+            sender: address,
+            receiver: "broadcast",
+            ...(correlationId ? { correlationId } : {}),
+        });
+    }, [address, available, dispatchSignal]);
+    const record = useCallback((finished, status) => {
+        if (progressRef.current === null)
+            return;
+        const next = recordPhiTourProgress(progressRef.current ?? null, finished, status);
+        progressRef.current = next;
+        // Remembering is a convenience; a write that fails costs a second offer, not the Tour.
+        void writePhiUserState({ descriptor: PROGRESS_DESCRIPTOR, value: next }).catch(() => undefined);
+    }, []);
+    const start = useCallback((startTour) => {
+        setRun({ tour: startTour, index: 0, presented: null });
+    }, []);
+    /*
+     * A Page with a Tour, a Page without, another Page with another one: the availability is said again,
+     * and a first visit is offered once progress has been read.
+     */
+    useEffect(() => {
+        announce();
+    }, [announce]);
+    useEffect(() => {
+        if (!tour) {
+            offeredRef.current = null;
+            return undefined;
+        }
+        if (offeredRef.current === tour.id)
+            return undefined;
+        const abort = new AbortController();
+        const offer = () => {
+            offeredRef.current = tour.id;
+            if (progressRef.current !== null && shouldOfferPhiTour(progressRef.current ?? null, tour)) {
+                start(tour);
+            }
+        };
+        if (progressRef.current !== undefined) {
+            offer();
+            return undefined;
+        }
+        fetchPhiUserState(abort.signal)
+            .then((state) => {
+            progressRef.current = readPhiTourProgress(state[PHI_TOUR_PROGRESS_USER_STATE_KEY]);
+            offer();
+        })
+            .catch(() => {
+            if (!abort.signal.aborted)
+                progressRef.current = null;
+        });
+        return () => abort.abort();
+    }, [start, tour]);
+    usePhiSignalListener(useCallback((signal) => {
+        if (signal.receiver !== address)
+            return;
+        if (signal.action === "reload") {
+            announce(signal.correlationId);
+            return;
+        }
+        if (signal.action === "open" && tour) {
+            start(tour);
+        }
+    }, [address, announce, start, tour]), useMemo(() => ({ ...TOUR_LISTEN_FILTER, receiver: address }), [address]));
+    /*
+     * The shown step's target, waited for before the step is presented. Not found in time, the step's
+     * `ifMissing` decides: passed over, or the Tour ends. It is never presented centered instead, and
+     * never pointed at anything but its own address in this partition.
+     */
+    const step = run ? run.tour.steps[run.index] ?? null : null;
+    // A step centered on purpose has nothing to wait for.
+    const presented = run && step?.target == null ? run.index : run?.presented ?? null;
+    useEffect(() => {
+        if (!run || run.presented === run.index || !step?.target)
+            return undefined;
+        const abort = new AbortController();
+        void waitForPhiVisualAnchor(partition, step.target, { timeoutMs: TARGET_WAIT_MS, signal: abort.signal })
+            .then((element) => {
+            if (abort.signal.aborted)
+                return;
+            if (element) {
+                setRun({ ...run, presented: run.index });
+                return;
+            }
+            const next = run.index + 1;
+            setRun(step.ifMissing === "stop" || next >= run.tour.steps.length
+                ? null
+                : { ...run, index: next });
+        });
+        return () => abort.abort();
+    }, [partition, run, step]);
+    const steps = useMemo(() => (run?.tour.steps ?? []).map((definition) => ({
+        key: definition.key,
+        title: definition.title,
+        description: definition.description,
+        target: definition.target
+            ? () => readPhiVisualAnchor(partition, definition.target)
+            : null,
+        placement: definition.placement,
+    })), [partition, run?.tour.steps]);
+    if (!run)
+        return null;
+    return (_jsx(PhiTourControl, { open: presented != null, current: presented ?? 0, steps: steps, labels: run.tour.labels, onStepChange: (index) => setRun({ ...run, index, presented }), onClose: () => {
+            record(run.tour, "dismissed");
+            setRun(null);
+        }, onFinish: () => {
+            record(run.tour, "completed");
+            setRun(null);
+        } }));
+}
+export const PHI_TOUR_RUNTIME_CONTROLLER_PLUGIN = {
+    ...PHI_TOUR_RUNTIME_CONTROLLER_DEFINITION,
+    renderController: ({ key, address, config }) => _jsx(PhiTourControllerView, { address: address, config: config }, key),
+};
+export const PhiTourRuntimeControllerClient = createPhiRuntimeControllerClient(PHI_TOUR_RUNTIME_CONTROLLER_PLUGIN);

package/plugins/runtime-modules/tour/controller/definition.d.ts

@@ -0,0 +1,48 @@
+import { type PhiResolvedPageTour } from "../../../../types/tours";
+export type PhiTourControllerConfig = {
+    /** The shown Page's Tour, handed on by the Page resolution while that Page is shown; `null` for none. */
+    pageTour: PhiResolvedPageTour | null;
+};
+/**
+ * Runs the Tour of whichever Page is shown (design/TOURS.md).
+ *
+ * The Area mounts it once, and every Page that carries a Tour hands it in as a Page overlay of this
+ * config -- the `pageTour` flag is what tells the Page resolution that this Controller takes it. From
+ * there it is the whole workflow: whether a Tour is available, starting one when the button asks or once
+ * on a first visit, waiting for each step's target, and keeping the viewer's progress.
+ */
+export declare const PHI_TOUR_RUNTIME_CONTROLLER_DEFINITION: {
+    kind: "controller";
+    pluginKey: string;
+    key: string;
+    title: string;
+    description: string;
+    iconFamily: string;
+    flags: "pageTour"[];
+    allowedMountScopes: "area"[];
+    runtimeSignals: {
+        emits: {
+            id: string;
+            action: "change";
+            valueType: "json";
+            valueSchema: `${string}/signals/${string}`;
+        }[];
+        listens: ({
+            id: string;
+            channel: string;
+            action: "open";
+            valueType: "none";
+        } | {
+            id: string;
+            channel: string;
+            action: "reload";
+            valueType: "none";
+        })[];
+    };
+    defaultConfig: {
+        pageTour: null;
+    };
+    parseConfig: (raw: Record<string, unknown>) => {
+        pageTour: PhiResolvedPageTour | null;
+    };
+};

package/plugins/runtime-modules/tour/controller/definition.js

@@ -0,0 +1,41 @@
+import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../../types/signals";
+import { PHI_PAGE_TOUR_CONFIG_KEY, PHI_PAGE_TOUR_CONTROLLER_FLAG, PHI_TOUR_CONTROLLER_KEY, PHI_TOUR_CONTROLLER_PLUGIN_KEY, readPhiResolvedPageTour, } from "../../../../types/tours";
+/**
+ * Runs the Tour of whichever Page is shown (design/TOURS.md).
+ *
+ * The Area mounts it once, and every Page that carries a Tour hands it in as a Page overlay of this
+ * config -- the `pageTour` flag is what tells the Page resolution that this Controller takes it. From
+ * there it is the whole workflow: whether a Tour is available, starting one when the button asks or once
+ * on a first visit, waiting for each step's target, and keeping the viewer's progress.
+ */
+export const PHI_TOUR_RUNTIME_CONTROLLER_DEFINITION = {
+    kind: "controller",
+    pluginKey: PHI_TOUR_CONTROLLER_PLUGIN_KEY,
+    key: PHI_TOUR_CONTROLLER_KEY,
+    title: "Tour Controller",
+    description: "Offers and runs the Tour of the shown Page, and keeps where each person stands in it.",
+    iconFamily: "tour",
+    flags: [PHI_PAGE_TOUR_CONTROLLER_FLAG],
+    allowedMountScopes: ["area"],
+    runtimeSignals: {
+        emits: [
+            /*
+             * Whether the shown Page has a Tour, to whoever offers one -- broadcast, because the button is
+             * placed by the Site and this Controller does not know where. Said again whenever it is asked, so a
+             * button that mounts late is not left guessing.
+             */
+            {
+                id: "availability",
+                action: "change",
+                valueType: "json",
+                valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.tourAvailability,
+            },
+        ],
+        listens: [
+            { id: "tourOpen", channel: "tour", action: "open", valueType: "none" },
+            { id: "availabilityRequest", channel: "tour", action: "reload", valueType: "none" },
+        ],
+    },
+    defaultConfig: { pageTour: null },
+    parseConfig: (raw) => ({ pageTour: readPhiResolvedPageTour(raw[PHI_PAGE_TOUR_CONFIG_KEY]) }),
+};

package/plugins/runtime-modules/tour/controller/progress.d.ts

@@ -0,0 +1,19 @@
+import type { PhiTourDefinition } from "../../../../types/tours";
+export type PhiTourProgressStatus = "completed" | "dismissed";
+/**
+ * Where one person stands in every Tour of a Site, kept under one user-state value.
+ *
+ * Per Tour only the version last finished and how: a Tour completed or dismissed in its current version
+ * is not offered by itself again, and raising the version offers it anew. The history of earlier versions
+ * is not kept -- the value is bounded by the Module's 4 KB namespace, and a version is all an offer needs.
+ */
+export type PhiTourProgress = {
+    tours: Readonly<Record<string, {
+        version: number;
+        status: PhiTourProgressStatus;
+    }>>;
+};
+export declare function readPhiTourProgress(value: unknown): PhiTourProgress;
+/** Whether a Tour opens by itself: never finished in this version, either way. */
+export declare function shouldOfferPhiTour(progress: PhiTourProgress | null, tour: Pick<PhiTourDefinition, "id" | "version">): boolean;
+export declare function recordPhiTourProgress(progress: PhiTourProgress | null, tour: Pick<PhiTourDefinition, "id" | "version">, status: PhiTourProgressStatus): PhiTourProgress;

package/plugins/runtime-modules/tour/controller/progress.js

@@ -0,0 +1,24 @@
+export function readPhiTourProgress(value) {
+    const tours = {};
+    const raw = typeof value === "object" && value !== null
+        ? value.tours
+        : null;
+    if (typeof raw === "object" && raw !== null) {
+        for (const [id, entry] of Object.entries(raw)) {
+            const record = entry;
+            if (typeof record?.version === "number"
+                && (record.status === "completed" || record.status === "dismissed")) {
+                tours[id] = { version: record.version, status: record.status };
+            }
+        }
+    }
+    return { tours };
+}
+/** Whether a Tour opens by itself: never finished in this version, either way. */
+export function shouldOfferPhiTour(progress, tour) {
+    const entry = progress?.tours[tour.id];
+    return !entry || entry.version < tour.version;
+}
+export function recordPhiTourProgress(progress, tour, status) {
+    return { tours: { ...progress?.tours, [tour.id]: { version: tour.version, status } } };
+}

package/plugins/runtime-modules/tour/definition.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Offers the Tours the Site's Pages carry (design/TOURS.md, "Decided direction").
+ *
+ * It owns no Tour. A Tour belongs to the Module that owns the Page, which attaches it to its route
+ * preset; the foundation -- visual anchors, `PhiTourControl`, the Page hand-over, the Tour button and the
+ * address it asks -- is Core's. What this Module brings is the Controller that runs a Tour, so switching
+ * it off switches Tours off for every Module alike: the buttons, unanswered, stay hidden, and every Tour
+ * stays where it is, unoffered. No Module depends on this one to carry a Tour or place its button.
+ */
+export declare const PHI_TOUR_RUNTIME_MODULE_DEFINITION: {
+    moduleId: "@phis/ui/modules/tour";
+    kind: "module";
+    eligibleAreas: readonly ["public", "app", "admin", "builder", "editor", "accounting"];
+    serverBinding: import("../../../types").PhiRuntimeModuleServerBinding;
+    controllerType: "@phis/ui/modules/tour/controller/default";
+    controller: import("../contracts").PhiRuntimeModuleControllerDescriptor;
+    controllerMountPolicy: "area";
+    title: string;
+    description: string;
+    category: "workspace";
+    icon: string;
+    userState: {
+        key: "@phis/ui/modules/tour/progress";
+        shape: "value";
+        valueSchema: `${string}/signals/${string}`;
+    }[];
+};

package/plugins/runtime-modules/tour/definition.js

@@ -0,0 +1,32 @@
+import { PHI_CMS_AREA_KEYS } from "../../../constants/cms-areas";
+import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../types/signals";
+import { buildPhiRuntimeModuleControllerDescriptor } from "../contracts";
+import { PHI_CORE_SERVER_BINDING } from "../../../types/server-capabilities";
+import { PHI_TOUR_RUNTIME_CONTROLLER_DEFINITION } from "./controller/definition";
+import { PHI_TOUR_CONTROLLER_TYPE } from "./controller/address";
+import { PHI_TOUR_PROGRESS_USER_STATE_KEY, PHI_TOUR_RUNTIME_MODULE_ID } from "./ids";
+/**
+ * Offers the Tours the Site's Pages carry (design/TOURS.md, "Decided direction").
+ *
+ * It owns no Tour. A Tour belongs to the Module that owns the Page, which attaches it to its route
+ * preset; the foundation -- visual anchors, `PhiTourControl`, the Page hand-over, the Tour button and the
+ * address it asks -- is Core's. What this Module brings is the Controller that runs a Tour, so switching
+ * it off switches Tours off for every Module alike: the buttons, unanswered, stay hidden, and every Tour
+ * stays where it is, unoffered. No Module depends on this one to carry a Tour or place its button.
+ */
+export const PHI_TOUR_RUNTIME_MODULE_DEFINITION = {
+    moduleId: PHI_TOUR_RUNTIME_MODULE_ID,
+    kind: "module",
+    eligibleAreas: PHI_CMS_AREA_KEYS,
+    serverBinding: PHI_CORE_SERVER_BINDING,
+    controllerType: PHI_TOUR_CONTROLLER_TYPE,
+    controller: buildPhiRuntimeModuleControllerDescriptor(PHI_TOUR_RUNTIME_CONTROLLER_DEFINITION),
+    controllerMountPolicy: "area",
+    title: "Tours",
+    description: "Runs the guided Tours of the Site's Pages, for every Module that brings one.",
+    category: "workspace",
+    icon: "antd:question-circle",
+    userState: [
+        { key: PHI_TOUR_PROGRESS_USER_STATE_KEY, shape: "value", valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.tourProgress },
+    ],
+};

package/plugins/runtime-modules/tour/ids.d.ts

@@ -0,0 +1,7 @@
+export declare const PHI_TOUR_RUNTIME_MODULE_ID: "@phis/ui/modules/tour";
+/**
+ * Where a person's Tours stand on this Site, one value for all of them: which version of which Tour was
+ * completed or dismissed. One key rather than one per Tour, because the Tours a Site carries come from
+ * whichever Modules own its Pages and this Module may only write keys it declared.
+ */
+export declare const PHI_TOUR_PROGRESS_USER_STATE_KEY: "@phis/ui/modules/tour/progress";

package/plugins/runtime-modules/tour/ids.js

@@ -0,0 +1,8 @@
+import { PHI_SHARED_PACKAGE_NAME } from "../../../types/signals";
+export const PHI_TOUR_RUNTIME_MODULE_ID = `${PHI_SHARED_PACKAGE_NAME}/modules/tour`;
+/**
+ * Where a person's Tours stand on this Site, one value for all of them: which version of which Tour was
+ * completed or dismissed. One key rather than one per Tour, because the Tours a Site carries come from
+ * whichever Modules own its Pages and this Module may only write keys it declared.
+ */
+export const PHI_TOUR_PROGRESS_USER_STATE_KEY = `${PHI_TOUR_RUNTIME_MODULE_ID}/progress`;

package/plugins/runtime-modules/tour/module.d.ts

@@ -0,0 +1 @@
+export declare const PHI_TOUR_RUNTIME_MODULE: import("../contracts").PhiRuntimeModule;

package/plugins/runtime-modules/tour/module.js

@@ -0,0 +1,4 @@
+import { PHI_TOUR_RUNTIME_CONTROLLER_DEFINITION } from "./controller/definition";
+import { PHI_TOUR_RUNTIME_MODULE_DEFINITION } from "./definition";
+import { createPhiAreaBaseRuntimeModule } from "../area-base-module";
+export const PHI_TOUR_RUNTIME_MODULE = createPhiAreaBaseRuntimeModule(PHI_TOUR_RUNTIME_MODULE_DEFINITION, PHI_TOUR_RUNTIME_CONTROLLER_DEFINITION);

package/plugins/runtime-modules/tour/server.d.ts

@@ -0,0 +1 @@
+export declare function createPhiTourRuntimeModuleServerAreaContribution(): import("../area-contributions").PhiRuntimeModuleServerAreaContribution;

package/plugins/runtime-modules/tour/server.js

@@ -0,0 +1,14 @@
+import { definePhiRuntimeModuleServerAreaContribution } from "../area-contributions";
+import { PHI_TOUR_RUNTIME_MODULE_DEFINITION } from "./definition";
+export function createPhiTourRuntimeModuleServerAreaContribution() {
+    return definePhiRuntimeModuleServerAreaContribution({
+        moduleId: PHI_TOUR_RUNTIME_MODULE_DEFINITION.moduleId,
+        catalogEntry: {
+            definition: PHI_TOUR_RUNTIME_MODULE_DEFINITION,
+            widgets: [],
+            layouts: [],
+            routes: [],
+            load: () => import("./module").then((module) => module.PHI_TOUR_RUNTIME_MODULE),
+        },
+    });
+}

package/plugins/runtime-modules/user-management/cards.js

@@ -1,6 +1,7 @@
 import "server-only";
 import { PHI_TR_CTX_WEB_UI_LABEL } from "../../../gateway/tr";
-import { definePhiLabelSet, getPhiLabelSet } from "../../../gateway/label-set";
+import { definePhiRuntimeModuleLabelSet, getPhiLabelSet } from "../../../gateway/label-set";
+import { PHI_USER_MANAGEMENT_RUNTIME_MODULE_IDENTITY } from "./ids";
 import { getResolvedSiteStats } from "../../../gateway/site-stats";
 import { createPhiDashboardCardId, } from "../../../types/dashboard-cards";
 import { PHI_USER_MANAGEMENT_RUNTIME_MODULE_ID } from "./ids";
@@ -12,7 +13,7 @@ import { PHI_USER_MANAGEMENT_RUNTIME_MODULE_ID } from "./ids";
  * it came from. That distinction is why the fan-in is answered in the Site rather than by a Collection
  * provider calling Core directly.
  */
-const PHI_USER_MANAGEMENT_DASHBOARD_CARD_LABEL_SET = definePhiLabelSet({
+const PHI_USER_MANAGEMENT_DASHBOARD_CARD_LABEL_SET = definePhiRuntimeModuleLabelSet(PHI_USER_MANAGEMENT_RUNTIME_MODULE_IDENTITY, {
     key: "cards:user-management-accounts",
     ctx: PHI_TR_CTX_WEB_UI_LABEL,
     labels: {
@@ -33,9 +34,6 @@ function readLabels(context) {
 }
 export const PHI_USER_MANAGEMENT_RUNTIME_MODULE_DASHBOARD_CARDS = {
     async listCards(context) {
-        if (context.area !== "admin") {
-            return [];
-        }
         const labels = await readLabels(context);
         return [{
                 cardId: PHI_USER_MANAGEMENT_ACCOUNTS_CARD_ID,

package/plugins/runtime-modules/user-management/controller/client.d.ts

@@ -1,6 +1,6 @@
 import { type PhiUserManagementControllerConfig } from "../controller/definition";
 export declare const PHI_USER_MANAGEMENT_RUNTIME_CONTROLLER_PLUGIN: {
-    renderController: ({ key, address, runtime }: import("../../../../types").PhiRuntimeControllerRenderArgs<PhiUserManagementControllerConfig, unknown>) => import("react").JSX.Element;
+    renderController: ({ key, address, runtime, config }: import("../../../../types").PhiRuntimeControllerRenderArgs<PhiUserManagementControllerConfig, unknown>) => import("react").JSX.Element;
     kind: "controller";
     pluginKey: string;
     key: string;
@@ -11,22 +11,27 @@ export declare const PHI_USER_MANAGEMENT_RUNTIME_CONTROLLER_PLUGIN: {
     runtimeSignals: {
         emits: ({
             id: string;
-            action: "activate";
+            action: "close";
             valueType: "none";
             valueSchema?: undefined;
         } | {
             id: string;
-            action: "close";
+            action: "activate";
             valueType: "none";
             valueSchema?: undefined;
         } | {
             id: string;
-            action: "activate";
+            action: "change";
+            valueType: "boolean";
+            valueSchema?: undefined;
+        } | {
+            id: string;
+            action: "change";
             valueType: "json";
             valueSchema: `${string}/signals/${string}`;
         } | {
             id: string;
-            action: "change";
+            action: "activate";
             valueType: "json";
             valueSchema: `${string}/signals/${string}`;
         })[];
@@ -59,10 +64,11 @@ export declare const PHI_USER_MANAGEMENT_RUNTIME_CONTROLLER_PLUGIN: {
             channel: string;
             action: "reload";
             valueType: "none";
-            valueSchema?: undefined;
         })[];
     };
-    defaultConfig: {};
-    parseConfig: () => PhiUserManagementControllerConfig;
+    defaultConfig: {
+        signalRoutes: null;
+    };
+    parseConfig: (raw: Record<string, unknown>) => PhiUserManagementControllerConfig;
 };
 export declare const PhiUserManagementRuntimeControllerClient: (props: import("../../contracts").PhiRuntimeModuleControllerClientProps) => import("react").JSX.Element;