@phis/ui 0.3.0 → 0.4.0

package/types/cms-plugins.d.ts

@@ -93,7 +93,12 @@ export type PhiCmsConfigFieldChoicePresentation = "select" | "segmented" | "tabs
  */
 export type PhiCmsConfigFieldCollectionPresentation = "inline" | "overlay" | "select";
 export type PhiCmsConfigFieldChoiceMode = "single" | "multiple";
-export type PhiCmsConfigFieldChoiceValueType = "string" | "string[]";
+/**
+ * What a `choice` stores. A text or a list of texts is the rule; `number` is a closed list of numbers --
+ * a key that is a number everywhere else, in the parser, the URL and the contracts, as the Image's
+ * Variant is -- and is stored as that number rather than spelled as a text the reader has to convert.
+ */
+export type PhiCmsConfigFieldChoiceValueType = "string" | "string[]" | "number";
 export type PhiCmsConfigFieldChoiceCreateBehavior = "none" | "accept-custom" | "create-record";
 export type PhiCmsConfigFieldColorMode = "single" | "gradient" | "both";
 export type PhiCmsConfigFieldValueStorage = "field" | "self";
@@ -135,6 +140,12 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
 }) | (PhiCmsConfigFieldBase & {
     type: "data-provider";
     providerKind?: PhiRuntimeDataProviderKind;
+    /**
+     * The one record Provider this binding names, for a Widget that can only read one: a Gallery
+     * reads a Folder, an entry header an entry. The Inspector then offers no choice of Provider -- a list
+     * that holds a single right answer and several wrong ones -- and asks only for its parameters.
+     */
+    providerKey?: PhiRuntimeDataProviderKey;
 }) | (PhiCmsConfigFieldBase & {
     type: "calendar-adapter";
 }) | (PhiCmsConfigFieldBase & {
@@ -235,10 +246,25 @@ export type PhiCmsConfigField = (PhiCmsConfigFieldBase & {
      */
     presentation?: "slider";
     suffix?: string;
+}) | (PhiCmsConfigFieldBase & {
+    type: "choice";
+    valueType: "number";
+    options: PhiControlOption<number>[];
+    emptyOption?: PhiControlOption;
+    emptyValue?: null | undefined;
+    placeholder?: string;
+    mode?: never;
+    presentation?: never;
+    optionsProvider?: never;
+    allowCustom?: never;
+    createBehavior?: never;
+    filter?: never;
+    patchOnChange?: never;
+    optionPresets?: never;
 }) | (PhiCmsConfigFieldBase & {
     type: "choice";
     mode?: PhiCmsConfigFieldChoiceMode;
-    valueType?: PhiCmsConfigFieldChoiceValueType;
+    valueType?: Exclude<PhiCmsConfigFieldChoiceValueType, "number">;
     presentation?: PhiCmsConfigFieldChoicePresentation;
     options?: PhiControlOption[];
     optionsProvider?: PhiControlOptionsProviderConfig;
@@ -635,11 +661,12 @@ export type PhiResolvedCmsRequest = {
     runtime: PhiBlockRuntime;
     serverCapabilities: import("./server-capabilities").PhiCapabilitySnapshot | null;
     /**
-     * The Tour the Page's route carries, untranslated, with the language its owning Module writes in.
-     * Translated only where the Area has a Controller to hand it to (types/tours.ts).
+     * The Tour the Page's route carries, untranslated, with the Module that owns it and the language that
+     * Module writes in. Translated only where the Area has a Controller to hand it to (types/tours.ts).
      */
     pageTour?: {
         definition: import("./tours").PhiTourDefinition;
+        ownerModuleId: PhiRuntimeModuleId;
         sourceLocale?: string;
     } | null;
 };

package/types/tour-controller.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Where a Tour is asked for: the Tour Controller of the Area, which the Tour Module mounts.
+ *
+ * Here, in the foundation, rather than in that Module: the Tour button is Core's, so any Area -- and any
+ * Module's own Page -- can place it without depending on the Tour Module. With the Module off nobody
+ * answers at this address, and the button, never told that a Tour is there, stays hidden.
+ */
+export declare const PHI_TOUR_CONTROLLER_PLUGIN_KEY = "@phis/ui/modules/tour/controller";
+export declare const PHI_TOUR_CONTROLLER_KEY = "default";
+export declare const PHI_TOUR_CONTROLLER_ADDRESS: `controller:${string}/${string}:${string}`;

package/types/tour-controller.js

@@ -0,0 +1,13 @@
+import { PHI_SHARED_PACKAGE_NAME, createPhiControllerSignalAddress } from "./signals";
+// Apart from `types/tours.ts`, so the Tour button, placed in every Area, carries the address and not the
+// Tour definition's checks.
+/**
+ * Where a Tour is asked for: the Tour Controller of the Area, which the Tour Module mounts.
+ *
+ * Here, in the foundation, rather than in that Module: the Tour button is Core's, so any Area -- and any
+ * Module's own Page -- can place it without depending on the Tour Module. With the Module off nobody
+ * answers at this address, and the button, never told that a Tour is there, stays hidden.
+ */
+export const PHI_TOUR_CONTROLLER_PLUGIN_KEY = `${PHI_SHARED_PACKAGE_NAME}/modules/tour/controller`;
+export const PHI_TOUR_CONTROLLER_KEY = "default";
+export const PHI_TOUR_CONTROLLER_ADDRESS = createPhiControllerSignalAddress(PHI_TOUR_CONTROLLER_PLUGIN_KEY, PHI_TOUR_CONTROLLER_KEY, "default");

package/types/tours.d.ts

@@ -1,4 +1,5 @@
-import { type PhiSignalAddress } from "./signals";
+import { type PhiSignalAction, type PhiSignalAddress, type PhiSignalChannel, type PhiSignalValue, type PhiSignalValueSchema, type PhiSignalValueType } from "./signals";
+import type { PhiVisualAnchorAddress } from "./visual-anchors";
 /**
  * Guided Tours ([design/TOURS.md](../design/TOURS.md)).
  *
@@ -7,20 +8,6 @@ import { type PhiSignalAddress } from "./signals";
  * (`pageTour` among its flags) receives it as a Page overlay of its config. There is no registry of
  * Tours and no Tour content in the CMS.
  */
-/**
- * The addresses a step can point at: a CMS instance, one of its declared subcontrols, a Region. A
- * Controller is an address too, but it owns no element, so it is never a visual target.
- */
-export type PhiVisualAnchorAddress = Exclude<PhiSignalAddress, `controller:${string}`>;
-/**
- * The attribute a Phi Control marks one of its parts with -- a Table's header row, its toolbar -- so the
- * Widget drawing that Control can offer the part as `cms:<instanceId>:<part>` (design/TOURS.md,
- * Visual-anchor registration). An inert mark until a Widget registers the part: the address is the
- * Widget's contract, the attribute only says where the part is drawn.
- */
-export declare const PHI_VISUAL_ANCHOR_PART_ATTRIBUTE = "data-phi-anchor-part";
-/** The instance a part address belongs to -- `cms:<id>` of `cms:<id>:<part>` -- or `null` for a whole one. */
-export declare function readPhiVisualAnchorOwner(address: string): PhiVisualAnchorAddress | null;
 /**
  * Where a step's panel sits relative to its target. Four sides, not Ant Design's twelve: a Tour points
  * at something, and the corner variants are layout tuning no definition should have to carry.
@@ -28,6 +15,20 @@ export declare function readPhiVisualAnchorOwner(address: string): PhiVisualAnch
 export type PhiTourPlacement = "top" | "bottom" | "left" | "right";
 /** What a step does when its target is not there to point at: pass over it, or end the Tour. */
 export type PhiTourMissingTargetPolicy = "skip" | "stop";
+/**
+ * One signal a step sends: to prepare what it points at, or to put it away again (design/TOURS.md,
+ * Signaling and orchestration). An ordinary Area signal under the Tour Controller's address, to one named
+ * receiver that already listens for it -- the Tour adds no channel and no receiver of its own. The value
+ * travels with the Page, so it is plain data.
+ */
+export type PhiTourStepSignal = {
+    receiver: PhiSignalAddress;
+    channel: PhiSignalChannel;
+    action: PhiSignalAction;
+    valueType: PhiSignalValueType;
+    valueSchema?: PhiSignalValueSchema;
+    value?: PhiSignalValue;
+};
 export type PhiTourStepDefinition = {
     /** The step's identity within its Tour; progress is stored under it, never under a position. */
     key: string;
@@ -41,6 +42,17 @@ export type PhiTourStepDefinition = {
     description?: string;
     placement?: PhiTourPlacement;
     ifMissing?: PhiTourMissingTargetPolicy;
+    /**
+     * Sent when the step is asked for, before its target is waited for: what makes the target appear --
+     * selecting something so its Inspector opens, opening a slot.
+     */
+    prepare?: readonly PhiTourStepSignal[];
+    /**
+     * Sent when the step is left, however it is left: the next step, the previous one, a step passed over,
+     * the Tour closed or finished, the Page left. What `prepare` opened, this puts away, so nothing a step
+     * brought up stands in front of the steps after it.
+     */
+    release?: readonly PhiTourStepSignal[];
 };
 export type PhiTourDefinition = {
     /** `<module id>/<key>`: namespaced by the Module that owns the Page. */
@@ -62,16 +74,6 @@ export type PhiTourLabels = {
 export type PhiResolvedPageTour = PhiTourDefinition & {
     labels: PhiTourLabels;
 };
-/**
- * Where a Tour is asked for: the Tour Controller of the Area, which the Tour Module mounts.
- *
- * Here, in the foundation, rather than in that Module: the Tour button is Core's, so any Area -- and any
- * Module's own Page -- can place it without depending on the Tour Module. With the Module off nobody
- * answers at this address, and the button, never told that a Tour is there, stays hidden.
- */
-export declare const PHI_TOUR_CONTROLLER_PLUGIN_KEY = "@phis/ui/modules/tour/controller";
-export declare const PHI_TOUR_CONTROLLER_KEY = "default";
-export declare const PHI_TOUR_CONTROLLER_ADDRESS: `controller:${string}/${string}:${string}`;
 /** The flag a Controller definition carries to receive the shown Page's Tour as `pageTour` in its config. */
 export declare const PHI_PAGE_TOUR_CONTROLLER_FLAG = "pageTour";
 /** The config key the Page's Tour arrives under. */

package/types/tours.js

@@ -1,26 +1,4 @@
-import { PHI_SHARED_PACKAGE_NAME, createPhiControllerSignalAddress } from "./signals";
-/**
- * The attribute a Phi Control marks one of its parts with -- a Table's header row, its toolbar -- so the
- * Widget drawing that Control can offer the part as `cms:<instanceId>:<part>` (design/TOURS.md,
- * Visual-anchor registration). An inert mark until a Widget registers the part: the address is the
- * Widget's contract, the attribute only says where the part is drawn.
- */
-export const PHI_VISUAL_ANCHOR_PART_ATTRIBUTE = "data-phi-anchor-part";
-/** The instance a part address belongs to -- `cms:<id>` of `cms:<id>:<part>` -- or `null` for a whole one. */
-export function readPhiVisualAnchorOwner(address) {
-    const [family, instanceId, part] = address.split(":");
-    return family === "cms" && instanceId && part ? `cms:${instanceId}` : null;
-}
-/**
- * Where a Tour is asked for: the Tour Controller of the Area, which the Tour Module mounts.
- *
- * Here, in the foundation, rather than in that Module: the Tour button is Core's, so any Area -- and any
- * Module's own Page -- can place it without depending on the Tour Module. With the Module off nobody
- * answers at this address, and the button, never told that a Tour is there, stays hidden.
- */
-export const PHI_TOUR_CONTROLLER_PLUGIN_KEY = `${PHI_SHARED_PACKAGE_NAME}/modules/tour/controller`;
-export const PHI_TOUR_CONTROLLER_KEY = "default";
-export const PHI_TOUR_CONTROLLER_ADDRESS = createPhiControllerSignalAddress(PHI_TOUR_CONTROLLER_PLUGIN_KEY, PHI_TOUR_CONTROLLER_KEY, "default");
+import { isPhiSignalAction, isPhiSignalValueType, } from "./signals";
 /** The flag a Controller definition carries to receive the shown Page's Tour as `pageTour` in its config. */
 export const PHI_PAGE_TOUR_CONTROLLER_FLAG = "pageTour";
 /** The config key the Page's Tour arrives under. */
@@ -53,6 +31,14 @@ export function collectPhiTourDefinitionErrors(definition) {
         if (step.target?.startsWith("controller:")) {
             errors.push(`Tour "${definition.id}" step "${step.key}" points at a Controller, which draws nothing.`);
         }
+        for (const signal of [...step.prepare ?? [], ...step.release ?? []]) {
+            if (signal.receiver === "broadcast") {
+                errors.push(`Tour "${definition.id}" step "${step.key}" broadcasts; a step signal names its receiver.`);
+            }
+            if (!isPhiSignalAction(signal.action) || !isPhiSignalValueType(signal.valueType)) {
+                errors.push(`Tour "${definition.id}" step "${step.key}" sends "${signal.channel}" with an unknown action or value type.`);
+            }
+        }
     }
     return errors;
 }

package/types/visual-anchors.d.ts

@@ -0,0 +1,15 @@
+import type { PhiSignalAddress } from "./signals";
+/**
+ * The addresses a step can point at: a CMS instance, one of its declared subcontrols, a Region. A
+ * Controller is an address too, but it owns no element, so it is never a visual target.
+ */
+export type PhiVisualAnchorAddress = Exclude<PhiSignalAddress, `controller:${string}`>;
+/**
+ * The attribute a Phi Control marks one of its parts with -- a Table's header row, its toolbar -- so the
+ * Widget drawing that Control can offer the part as `cms:<instanceId>:<part>` (design/TOURS.md,
+ * Visual-anchor registration). An inert mark until a Widget registers the part: the address is the
+ * Widget's contract, the attribute only says where the part is drawn.
+ */
+export declare const PHI_VISUAL_ANCHOR_PART_ATTRIBUTE = "data-phi-anchor-part";
+/** The instance a part address belongs to -- `cms:<id>` of `cms:<id>:<part>` -- or `null` for a whole one. */
+export declare function readPhiVisualAnchorOwner(address: string): PhiVisualAnchorAddress | null;

package/types/visual-anchors.js

@@ -0,0 +1,12 @@
+/**
+ * The attribute a Phi Control marks one of its parts with -- a Table's header row, its toolbar -- so the
+ * Widget drawing that Control can offer the part as `cms:<instanceId>:<part>` (design/TOURS.md,
+ * Visual-anchor registration). An inert mark until a Widget registers the part: the address is the
+ * Widget's contract, the attribute only says where the part is drawn.
+ */
+export const PHI_VISUAL_ANCHOR_PART_ATTRIBUTE = "data-phi-anchor-part";
+/** The instance a part address belongs to -- `cms:<id>` of `cms:<id>:<part>` -- or `null` for a whole one. */
+export function readPhiVisualAnchorOwner(address) {
+    const [family, instanceId, part] = address.split(":");
+    return family === "cms" && instanceId && part ? `cms:${instanceId}` : null;
+}

package/types.d.ts

@@ -42,7 +42,9 @@ export type * from "./types/site-theme";
 export * from "./types/server-capabilities";
 export * from "./types/core-runtime-controller";
 export * from "./types/signals";
+export * from "./types/tour-controller";
 export * from "./types/tours";
+export * from "./types/visual-anchors";
 export type { PhiCmsWidgetConfigBase } from "./components/widgets/config/parser-primitives";
 export * from "./components/widgets/config/control-signal-config";
 export type * from "./components/widgets/config/background";

package/types.js

@@ -21,6 +21,9 @@ export * from "./types/runtime-module-locale";
 export * from "./types/server-capabilities";
 export * from "./types/core-runtime-controller";
 export * from "./types/signals";
-// The Tour Controller's address and the Tour definition shape, for a Module that brings its own Tour.
+// The Tour Controller's address, the Tour definition shape and the visual anchors, for a Module that
+// brings its own Tour.
+export * from "./types/tour-controller";
 export * from "./types/tours";
+export * from "./types/visual-anchors";
 export * from "./components/widgets/config/control-signal-config";