@guideify/react 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -184,8 +184,41 @@ interface Flow {
     priority?: number;
     /** Can the end user close this flow? Use false sparingly. */
     dismissible?: boolean;
+    /**
+     * The window the flow may start in — J-04. ISO 8601 instants; either end may
+     * be open. Judged by the SDK against the end user's clock at the moment it
+     * would start, so a flow turns on and off without a republish; a tour
+     * already running when `endsAt` passes is allowed to finish.
+     */
+    startsAt?: string;
+    endsAt?: string;
+    /**
+     * A banner, slideout or hotspot instead of a tour — J-03. A flow with a
+     * surface carries `steps: []`, and that is the design rather than a
+     * placeholder: every core that predates surfaces drops a flow with no
+     * steps, so an environment pinned to one (R-04) skips the flow instead of
+     * drawing a banner as a blocking modal. `docs/ANNOUNCEMENTS_PLAN.md` §1.
+     */
+    surface?: Surface;
     steps: Step[];
 }
+/**
+ * One non-blocking message — J-03. `content` is a step's document, so the
+ * renderer and the editor are the tour's own.
+ */
+type Surface = {
+    type: 'banner';
+    content: StepContent;
+    position?: 'top' | 'bottom';
+} | {
+    type: 'slideout';
+    content: StepContent;
+    corner?: 'bottom-end' | 'bottom-start';
+} | {
+    type: 'hotspot';
+    content: StepContent;
+    target: ElementFingerprint;
+};
 /**
  * What marks a checklist item done.
  *
@@ -236,6 +269,59 @@ interface Checklist {
     /** Hidden once every item is done, which is the default a customer expects. */
     dismissWhenComplete?: boolean;
 }
+/**
+ * What pressing a resource entry does.
+ *
+ * A tour this environment already publishes, or a page the customer already
+ * keeps. There is deliberately no third variant holding an article: hosting
+ * help content is an editor, a search index and a second copy of documentation
+ * that already lives somewhere, and a variant can be added later where a CMS
+ * cannot be taken back out. RESOURCE_CENTRE_PLAN §2.1.
+ *
+ * `href` reaches an attribute, so whatever draws it passes it through
+ * `sanitizeUrl` first.
+ */
+type ResourceAction = {
+    type: 'flow';
+    flowId: string;
+} | {
+    type: 'link';
+    href: string;
+};
+interface ResourceEntry {
+    id: string;
+    label: string;
+    /** Optional one-liner under the label. The renderer's document, not a string. */
+    body?: ContentNode;
+    action: ResourceAction;
+}
+interface ResourceSection {
+    id: string;
+    /** Absent on the one section of a centre that has no need to name its groups. */
+    title?: string;
+    entries: ResourceEntry[];
+}
+/**
+ * The always-on help surface — J-06.
+ *
+ * `Checklist`'s sibling, and the difference between them is the design: a
+ * checklist item is **completed by evidence**, once, and a resource entry is
+ * **used**, any number of times. So there is no `goal` here and no done-state,
+ * and no `dismissWhenComplete`, because this does not complete — it is what is
+ * still in the corner after the checklist has taken itself away.
+ *
+ * No `trigger`, `frequency` or `priority`, for the three reasons `Checklist`
+ * gives. `position` is the launcher's and is shared with the checklist's; where
+ * both are published and disagree, the checklist's is drawn.
+ */
+interface ResourceCentre {
+    id: string;
+    name: string;
+    version: number;
+    audience?: RuleNode;
+    sections: ResourceSection[];
+    position?: 'bottom-end' | 'bottom-start';
+}
 interface ThemeTokens {
     accent?: string;
     scrim?: string;
@@ -268,6 +354,14 @@ interface GuideifyConfig {
      * it.
      */
     checklist?: Checklist;
+    /**
+     * The help surface behind the same launcher, if the environment has one.
+     *
+     * Additive on `checklist`'s argument, and pinned the same way:
+     * `packages/sdk/test/resources-config.test.mjs` asserts that a core which has
+     * never heard of the key ignores it and runs its flows.
+     */
+    resources?: ResourceCentre;
 }
 interface UserTraits {
     [key: string]: unknown;

package/dist/index.d.ts

@@ -184,8 +184,41 @@ interface Flow {
     priority?: number;
     /** Can the end user close this flow? Use false sparingly. */
     dismissible?: boolean;
+    /**
+     * The window the flow may start in — J-04. ISO 8601 instants; either end may
+     * be open. Judged by the SDK against the end user's clock at the moment it
+     * would start, so a flow turns on and off without a republish; a tour
+     * already running when `endsAt` passes is allowed to finish.
+     */
+    startsAt?: string;
+    endsAt?: string;
+    /**
+     * A banner, slideout or hotspot instead of a tour — J-03. A flow with a
+     * surface carries `steps: []`, and that is the design rather than a
+     * placeholder: every core that predates surfaces drops a flow with no
+     * steps, so an environment pinned to one (R-04) skips the flow instead of
+     * drawing a banner as a blocking modal. `docs/ANNOUNCEMENTS_PLAN.md` §1.
+     */
+    surface?: Surface;
     steps: Step[];
 }
+/**
+ * One non-blocking message — J-03. `content` is a step's document, so the
+ * renderer and the editor are the tour's own.
+ */
+type Surface = {
+    type: 'banner';
+    content: StepContent;
+    position?: 'top' | 'bottom';
+} | {
+    type: 'slideout';
+    content: StepContent;
+    corner?: 'bottom-end' | 'bottom-start';
+} | {
+    type: 'hotspot';
+    content: StepContent;
+    target: ElementFingerprint;
+};
 /**
  * What marks a checklist item done.
  *
@@ -236,6 +269,59 @@ interface Checklist {
     /** Hidden once every item is done, which is the default a customer expects. */
     dismissWhenComplete?: boolean;
 }
+/**
+ * What pressing a resource entry does.
+ *
+ * A tour this environment already publishes, or a page the customer already
+ * keeps. There is deliberately no third variant holding an article: hosting
+ * help content is an editor, a search index and a second copy of documentation
+ * that already lives somewhere, and a variant can be added later where a CMS
+ * cannot be taken back out. RESOURCE_CENTRE_PLAN §2.1.
+ *
+ * `href` reaches an attribute, so whatever draws it passes it through
+ * `sanitizeUrl` first.
+ */
+type ResourceAction = {
+    type: 'flow';
+    flowId: string;
+} | {
+    type: 'link';
+    href: string;
+};
+interface ResourceEntry {
+    id: string;
+    label: string;
+    /** Optional one-liner under the label. The renderer's document, not a string. */
+    body?: ContentNode;
+    action: ResourceAction;
+}
+interface ResourceSection {
+    id: string;
+    /** Absent on the one section of a centre that has no need to name its groups. */
+    title?: string;
+    entries: ResourceEntry[];
+}
+/**
+ * The always-on help surface — J-06.
+ *
+ * `Checklist`'s sibling, and the difference between them is the design: a
+ * checklist item is **completed by evidence**, once, and a resource entry is
+ * **used**, any number of times. So there is no `goal` here and no done-state,
+ * and no `dismissWhenComplete`, because this does not complete — it is what is
+ * still in the corner after the checklist has taken itself away.
+ *
+ * No `trigger`, `frequency` or `priority`, for the three reasons `Checklist`
+ * gives. `position` is the launcher's and is shared with the checklist's; where
+ * both are published and disagree, the checklist's is drawn.
+ */
+interface ResourceCentre {
+    id: string;
+    name: string;
+    version: number;
+    audience?: RuleNode;
+    sections: ResourceSection[];
+    position?: 'bottom-end' | 'bottom-start';
+}
 interface ThemeTokens {
     accent?: string;
     scrim?: string;
@@ -268,6 +354,14 @@ interface GuideifyConfig {
      * it.
      */
     checklist?: Checklist;
+    /**
+     * The help surface behind the same launcher, if the environment has one.
+     *
+     * Additive on `checklist`'s argument, and pinned the same way:
+     * `packages/sdk/test/resources-config.test.mjs` asserts that a core which has
+     * never heard of the key ignores it and runs its flows.
+     */
+    resources?: ResourceCentre;
 }
 interface UserTraits {
     [key: string]: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guideify/react",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "main": "./dist/index.cjs",