@guideify/react 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -186,6 +186,56 @@ interface Flow {
     dismissible?: boolean;
     steps: Step[];
 }
+/**
+ * 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;
+}
 interface ThemeTokens {
     accent?: string;
     scrim?: string;
@@ -203,6 +253,21 @@ 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;
 }
 interface UserTraits {
     [key: string]: unknown;

package/dist/index.d.ts

@@ -186,6 +186,56 @@ interface Flow {
     dismissible?: boolean;
     steps: Step[];
 }
+/**
+ * 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;
+}
 interface ThemeTokens {
     accent?: string;
     scrim?: string;
@@ -203,6 +253,21 @@ 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;
 }
 interface UserTraits {
     [key: string]: unknown;

package/package.json

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