@guideify/react 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -184,8 +184,144 @@ 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.
+ *
+ * A flow this environment already publishes, or an event the customer already
+ * sends us — both of which exist before the checklist does. There is
+ * deliberately no third variant for "the user ticked it": the surface is only
+ * worth its corner of somebody's application if it reflects what has actually
+ * happened in the product, and a box you can tick yourself reports nothing.
+ */
+type ChecklistItemGoal = {
+    type: 'flow';
+    flowId: string;
+} | {
+    type: 'event';
+    name: string;
+};
+interface ChecklistItem {
+    id: string;
+    label: string;
+    /** Optional one-liner under the label. The renderer's document, not a string. */
+    body?: ContentNode;
+    goal: ChecklistItemGoal;
+}
+/**
+ * The persistent surface — BUILD_REPORT §8, J-02.
+ *
+ * **It carries no `trigger`, no `frequency` and no `priority`, and the three
+ * absences are the design.** A checklist is not triggered, it is present:
+ * `Trigger`'s five variants each describe a moment, which is precisely what
+ * this is not, and `Frequency` answers *how often does this fire* about
+ * something that never fires. It does not compete for the screen either — §8
+ * puts it outside the one-blocking-flow rule, so it never enters the sort that
+ * `priority` exists to break. Three fields pinned to a constant would each be a
+ * question the reader has to answer before discovering it was never asked.
+ *
+ * `audience` is the same `RuleNode` a flow takes, read by the same
+ * `evaluateRules`. Reusing the evaluator is what stops a second rule engine
+ * existing.
+ */
+interface Checklist {
+    id: string;
+    name: string;
+    version: number;
+    audience?: RuleNode;
+    items: ChecklistItem[];
+    /** Where the launcher sits. The host app's other corner is usually taken. */
+    position?: 'bottom-end' | 'bottom-start';
+    /** 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;
@@ -203,6 +339,29 @@ interface GuideifyConfig {
     envKey: string;
     flows: Flow[];
     settings?: ConfigSettings;
+    /**
+     * The one persistent surface this environment publishes, if it has one.
+     *
+     * **Singular, deliberately.** A corner of somebody else's application has
+     * room for one launcher; a list invites two of them fighting over the same
+     * 56 pixels, and nothing in this product could arbitrate between them.
+     *
+     * Additive with a safe default, which is the header's rule and is what makes
+     * it publishable to environments held on an older core by `sdkPin` (R-04): a
+     * core built before this field existed parses the artifact, ignores the key
+     * and runs its flows. `packages/sdk/test/checklist-config.test.mjs` pins
+     * that, because it is an accident of `validateConfig` until something asserts
+     * 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,144 @@ 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.
+ *
+ * A flow this environment already publishes, or an event the customer already
+ * sends us — both of which exist before the checklist does. There is
+ * deliberately no third variant for "the user ticked it": the surface is only
+ * worth its corner of somebody's application if it reflects what has actually
+ * happened in the product, and a box you can tick yourself reports nothing.
+ */
+type ChecklistItemGoal = {
+    type: 'flow';
+    flowId: string;
+} | {
+    type: 'event';
+    name: string;
+};
+interface ChecklistItem {
+    id: string;
+    label: string;
+    /** Optional one-liner under the label. The renderer's document, not a string. */
+    body?: ContentNode;
+    goal: ChecklistItemGoal;
+}
+/**
+ * The persistent surface — BUILD_REPORT §8, J-02.
+ *
+ * **It carries no `trigger`, no `frequency` and no `priority`, and the three
+ * absences are the design.** A checklist is not triggered, it is present:
+ * `Trigger`'s five variants each describe a moment, which is precisely what
+ * this is not, and `Frequency` answers *how often does this fire* about
+ * something that never fires. It does not compete for the screen either — §8
+ * puts it outside the one-blocking-flow rule, so it never enters the sort that
+ * `priority` exists to break. Three fields pinned to a constant would each be a
+ * question the reader has to answer before discovering it was never asked.
+ *
+ * `audience` is the same `RuleNode` a flow takes, read by the same
+ * `evaluateRules`. Reusing the evaluator is what stops a second rule engine
+ * existing.
+ */
+interface Checklist {
+    id: string;
+    name: string;
+    version: number;
+    audience?: RuleNode;
+    items: ChecklistItem[];
+    /** Where the launcher sits. The host app's other corner is usually taken. */
+    position?: 'bottom-end' | 'bottom-start';
+    /** 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;
@@ -203,6 +339,29 @@ interface GuideifyConfig {
     envKey: string;
     flows: Flow[];
     settings?: ConfigSettings;
+    /**
+     * The one persistent surface this environment publishes, if it has one.
+     *
+     * **Singular, deliberately.** A corner of somebody else's application has
+     * room for one launcher; a list invites two of them fighting over the same
+     * 56 pixels, and nothing in this product could arbitrate between them.
+     *
+     * Additive with a safe default, which is the header's rule and is what makes
+     * it publishable to environments held on an older core by `sdkPin` (R-04): a
+     * core built before this field existed parses the artifact, ignores the key
+     * and runs its flows. `packages/sdk/test/checklist-config.test.mjs` pins
+     * that, because it is an accident of `validateConfig` until something asserts
+     * 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.2.0",
+  "version": "0.4.0",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "main": "./dist/index.cjs",