@kontourai/survey 2.2.1 → 2.2.3

package/README.md

@@ -169,12 +169,20 @@ The embedded stylesheet is scoped to `.survey-workbench-embed` and bundles Conso
 
 ### Theme it as your own brand
 
-The bundled `--k-*` token defaults are emitted in overridable form
-(`--k-brand: var(--k-brand, <default>)`), so a host brand is authoritative: set
-any `--k-*` token on an ancestor of the embed (or inline on the embed element,
-or the host element of the web component) and it propagates in — no need to
-out-specificity the embed's own selectors. Unset tokens keep their default, so
-you only declare what you re-brand.
+The bundled stylesheet carries a literal default for every `--k-*` token on the
+embed element itself, so the workbench looks right in a host that declares no
+tokens at all. To re-brand it, declare the tokens you want **on the embed
+element** — a rule matching `.survey-workbench-embed`, or an inline `style`
+attribute. Tokens you leave alone keep their default, so you only declare what
+you re-brand.
+
+Setting `--k-*` on an *ancestor* of the embed does not reach it: the embed
+declares those tokens on its own root, and a declaration on an element always
+beats a value inherited from an ancestor. If you want the embed to inherit a
+token layer your page already publishes at `:root`, use the web component
+(`<survey-review-workbench>`) — its defaults sit on the shadow `:host`, so host
+tokens and inline styles propagate through — or restate the tokens on the embed
+element as below.
 
 ```css
 /* Your app's own palette drives the workbench — no Kontour branding. */

package/dist/src/review-workbench/review-queue-session.d.ts

@@ -74,6 +74,23 @@ export declare function currentReviewItem(session: ReviewQueueSessionState): Rev
 export declare function deriveQueueRowStatus(item: ReviewItem, session: ReviewQueueSessionState): ReviewQueueRowStatus;
 export declare function nextUnresolvedItemName(session: ReviewQueueSessionState): string | undefined;
 export declare function reviewSessionSummary(session: ReviewQueueSessionState): ReviewSessionSummary;
+/**
+ * The decision the field card's "keep" control records for a ReviewItem, or
+ * `undefined` when the item cannot represent that action at all.
+ *
+ * Every workbench decision resolves to a candidate role (see
+ * {@link workbenchDecisionDefinitions}), so a decision whose role the item does
+ * not carry is not recordable — `keep-current` on an item that has no `current`
+ * candidate is the case that matters, because that is exactly how an
+ * envelope-imported item is modelled (one `proposed` candidate, nothing prior).
+ * The card already labels that control "Leave unset" rather than "Keep current";
+ * this returns the decision that means the same thing and IS representable:
+ * `reject-proposed` — the proposed value is not applied and nothing is set.
+ *
+ * Deliberately NOT solved by synthesising an empty `current` candidate: that
+ * would invent a prior value, with provenance, that the source never had.
+ */
+export declare function keepActionDecision(item: ReviewItem, flaggedWrong: boolean): ReviewWorkbenchDecision | undefined;
 export declare function candidateForDecision(item: ReviewItem, decision: ReviewWorkbenchDecision): ReviewCandidate;
 /**
  * The value that should actually be applied for a decision: the reviewer's inline

package/dist/src/review-workbench/review-queue-session.js

@@ -125,6 +125,29 @@ export function reviewSessionSummary(session) {
         unresolved: 0,
     });
 }
+/**
+ * The decision the field card's "keep" control records for a ReviewItem, or
+ * `undefined` when the item cannot represent that action at all.
+ *
+ * Every workbench decision resolves to a candidate role (see
+ * {@link workbenchDecisionDefinitions}), so a decision whose role the item does
+ * not carry is not recordable — `keep-current` on an item that has no `current`
+ * candidate is the case that matters, because that is exactly how an
+ * envelope-imported item is modelled (one `proposed` candidate, nothing prior).
+ * The card already labels that control "Leave unset" rather than "Keep current";
+ * this returns the decision that means the same thing and IS representable:
+ * `reject-proposed` — the proposed value is not applied and nothing is set.
+ *
+ * Deliberately NOT solved by synthesising an empty `current` candidate: that
+ * would invent a prior value, with provenance, that the source never had.
+ */
+export function keepActionDecision(item, flaggedWrong) {
+    const hasRole = (role) => item.spec.candidates.some((candidate) => candidate.role === role);
+    if (flaggedWrong || !hasRole("current")) {
+        return hasRole("proposed") ? "reject-proposed" : undefined;
+    }
+    return "keep-current";
+}
 export function candidateForDecision(item, decision) {
     const definition = workbenchDecisionDefinitions[decision];
     const candidate = item.spec.candidates.find((entry) => entry.role === definition.candidateRole);

package/dist/src/review-workbench/review-workbench-css.generated.js

@@ -6,149 +6,149 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
   color-scheme: dark;
 
   /* structure */
-  --k-bg: var(--k-bg, #0a0e13);
-  --k-panel: var(--k-panel, #111824);
-  --k-panel-raised: var(--k-panel-raised, #16202d);
-  --k-line: var(--k-line, rgba(150, 180, 210, 0.12));
-  --k-line-strong: var(--k-line-strong, rgba(150, 180, 210, 0.22));
-  --k-shadow: var(--k-shadow, 0 26px 60px -42px rgba(0, 0, 0, 0.95));
+  --k-bg: #0a0e13;
+  --k-panel: #111824;
+  --k-panel-raised: #16202d;
+  --k-line: rgba(150, 180, 210, 0.12);
+  --k-line-strong: rgba(150, 180, 210, 0.22);
+  --k-shadow: 0 26px 60px -42px rgba(0, 0, 0, 0.95);
 
   /* text */
-  --k-text: var(--k-text, #eef3f8);
-  --k-text-muted: var(--k-text-muted, #aebccb);
-  --k-text-faint: var(--k-text-faint, #72869b);
+  --k-text: #eef3f8;
+  --k-text-muted: #aebccb;
+  --k-text-faint: #72869b;
 
   /* brand */
-  --k-brand: var(--k-brand, #5ce0c6);
-  --k-brand-contrast: var(--k-brand-contrast, #06080b);
+  --k-brand: #5ce0c6;
+  --k-brand-contrast: #06080b;
 
   /* semantic status scale */
-  --k-positive: var(--k-positive, #34d399);
-  --k-caution: var(--k-caution, #f3b14b);
-  --k-negative: var(--k-negative, #ff6f6f);
-  --k-neutral: var(--k-neutral, #6f8095);
-  --k-active: var(--k-active, #7aa2ff);
+  --k-positive: #34d399;
+  --k-caution: #f3b14b;
+  --k-negative: #ff6f6f;
+  --k-neutral: #6f8095;
+  --k-active: #7aa2ff;
   --k-positive-soft: color-mix(in oklab, var(--k-positive) 14%, transparent);
   --k-caution-soft: color-mix(in oklab, var(--k-caution) 14%, transparent);
   --k-negative-soft: color-mix(in oklab, var(--k-negative) 14%, transparent);
   --k-active-soft: color-mix(in oklab, var(--k-active) 14%, transparent);
 
   /* spacing */
-  --k-space-1: var(--k-space-1, 4px);
-  --k-space-2: var(--k-space-2, 8px);
-  --k-space-3: var(--k-space-3, 12px);
-  --k-space-4: var(--k-space-4, 16px);
-  --k-space-5: var(--k-space-5, 24px);
-  --k-space-6: var(--k-space-6, 32px);
+  --k-space-1: 4px;
+  --k-space-2: 8px;
+  --k-space-3: 12px;
+  --k-space-4: 16px;
+  --k-space-5: 24px;
+  --k-space-6: 32px;
 
   /* radius */
-  --k-radius-sm: var(--k-radius-sm, 9px);
-  --k-radius-md: var(--k-radius-md, 14px);
+  --k-radius-sm: 9px;
+  --k-radius-md: 14px;
 
   /* type */
-  --k-text-xs: var(--k-text-xs, 11px);
-  --k-text-sm: var(--k-text-sm, 12.5px);
-  --k-text-md: var(--k-text-md, 14px);
-  --k-text-lg: var(--k-text-lg, 18px);
-  --k-text-xl: var(--k-text-xl, 22px);
-  --k-text-2xl: var(--k-text-2xl, clamp(26px, 3.4vw, 38px));
+  --k-text-xs: 11px;
+  --k-text-sm: 12.5px;
+  --k-text-md: 14px;
+  --k-text-lg: 18px;
+  --k-text-xl: 22px;
+  --k-text-2xl: clamp(26px, 3.4vw, 38px);
 
   /* fonts */
-  --k-font-display: var(--k-font-display, "Fraunces", Georgia, "Times New Roman", serif);
-  --k-font-ui: var(--k-font-ui, "Hanken Grotesk", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif);
-  --k-font-mono: var(--k-font-mono, "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, monospace);
+  --k-font-display: "Fraunces", Georgia, "Times New Roman", serif;
+  --k-font-ui: "Hanken Grotesk", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --k-font-mono: "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
 
   /* motion */
-  --k-ease: var(--k-ease, cubic-bezier(0.22, 1, 0.36, 1));
-  --k-dur: var(--k-dur, 0.16s);
+  --k-ease: cubic-bezier(0.22, 1, 0.36, 1);
+  --k-dur: 0.16s;
 }
 
 .survey-workbench-embed[data-theme="light"]{
   color-scheme: light;
-  --k-bg: var(--k-bg, #f5f4ef);
-  --k-panel: var(--k-panel, #ffffff);
-  --k-panel-raised: var(--k-panel-raised, #fbfaf7);
-  --k-line: var(--k-line, rgba(36, 40, 46, 0.12));
-  --k-line-strong: var(--k-line-strong, rgba(36, 40, 46, 0.20));
-  --k-shadow: var(--k-shadow, 0 18px 50px -30px rgba(0, 0, 0, 0.25));
-  --k-text: var(--k-text, #202124);
-  --k-text-muted: var(--k-text-muted, #5b626b);
-  --k-text-faint: var(--k-text-faint, #707782);
-  --k-brand-contrast: var(--k-brand-contrast, #ffffff);
-  --k-positive: var(--k-positive, #168257);
-  --k-caution: var(--k-caution, #8a5a00);
-  --k-negative: var(--k-negative, #c83b3b);
-  --k-neutral: var(--k-neutral, #5f6975);
-  --k-active: var(--k-active, #3f6fd6);
+  --k-bg: #f5f4ef;
+  --k-panel: #ffffff;
+  --k-panel-raised: #fbfaf7;
+  --k-line: rgba(36, 40, 46, 0.12);
+  --k-line-strong: rgba(36, 40, 46, 0.20);
+  --k-shadow: 0 18px 50px -30px rgba(0, 0, 0, 0.25);
+  --k-text: #202124;
+  --k-text-muted: #5b626b;
+  --k-text-faint: #707782;
+  --k-brand-contrast: #ffffff;
+  --k-positive: #168257;
+  --k-caution: #8a5a00;
+  --k-negative: #c83b3b;
+  --k-neutral: #5f6975;
+  --k-active: #3f6fd6;
 }
 
 
 .survey-workbench-embed.theme-survey{
-  --k-bg: var(--k-bg, #06080b);
-  --k-brand: var(--k-brand, #5ce0c6);
-  --k-text-faint: var(--k-text-faint, #6f8095);
+  --k-bg: #06080b;
+  --k-brand: #5ce0c6;
+  --k-text-faint: #6f8095;
 }
 
 .survey-workbench-embed.theme-console{
-  --k-font-ui: var(--k-font-ui, "Aptos Narrow", "DIN Condensed", "IBM Plex Sans Condensed", "Gill Sans", sans-serif);
-  --k-font-display: var(--k-font-display, "Aptos Narrow", "DIN Condensed", "IBM Plex Sans Condensed", "Gill Sans", sans-serif);
-  --k-radius-sm: var(--k-radius-sm, 0);
-  --k-radius-md: var(--k-radius-md, 0);
-  --k-brand: var(--k-brand, #c9ff4a);
-  --k-brand-contrast: var(--k-brand-contrast, #11120f);
-  --k-bg: var(--k-bg, #11120f);
-  --k-panel: var(--k-panel, #191b16);
-  --k-panel-raised: var(--k-panel-raised, #20231e);
-  --k-line: var(--k-line, #3a4035);
-  --k-line-strong: var(--k-line-strong, #8ea36e);
-  --k-text: var(--k-text, #f2f0e8);
-  --k-text-muted: var(--k-text-muted, #a6ab9c);
-  --k-text-faint: var(--k-text-faint, #747a6c);
-  --k-positive: var(--k-positive, #a6d37b);
-  --k-caution: var(--k-caution, #e8c15f);
-  --k-negative: var(--k-negative, #ee776f);
-  --k-active: var(--k-active, #84d8c8);
+  --k-font-ui: "Aptos Narrow", "DIN Condensed", "IBM Plex Sans Condensed", "Gill Sans", sans-serif;
+  --k-font-display: "Aptos Narrow", "DIN Condensed", "IBM Plex Sans Condensed", "Gill Sans", sans-serif;
+  --k-radius-sm: 0;
+  --k-radius-md: 0;
+  --k-brand: #c9ff4a;
+  --k-brand-contrast: #11120f;
+  --k-bg: #11120f;
+  --k-panel: #191b16;
+  --k-panel-raised: #20231e;
+  --k-line: #3a4035;
+  --k-line-strong: #8ea36e;
+  --k-text: #f2f0e8;
+  --k-text-muted: #a6ab9c;
+  --k-text-faint: #747a6c;
+  --k-positive: #a6d37b;
+  --k-caution: #e8c15f;
+  --k-negative: #ee776f;
+  --k-active: #84d8c8;
 }
 
 .survey-workbench-embed.theme-flow{
-  --k-brand: var(--k-brand, #2f88a6);
+  --k-brand: #2f88a6;
 }
 
 .survey-workbench-embed.theme-surface{
-  --k-brand: var(--k-brand, #14a37a);
+  --k-brand: #14a37a;
 }
 
 .survey-workbench-embed[data-theme="light"].theme-survey,
 .survey-workbench-embed[data-theme="light"] .theme-survey{
-  --k-brand: var(--k-brand, #16806f);
+  --k-brand: #16806f;
 }
 
 .survey-workbench-embed[data-theme="light"].theme-console,
 .survey-workbench-embed[data-theme="light"] .theme-console{
-  --k-brand: var(--k-brand, #6c9400);
-  --k-brand-contrast: var(--k-brand-contrast, #ffffff);
-  --k-bg: var(--k-bg, #f3f5eb);
-  --k-panel: var(--k-panel, #fbfcf7);
-  --k-panel-raised: var(--k-panel-raised, #eef2e6);
-  --k-line: var(--k-line, #ccd5bf);
-  --k-line-strong: var(--k-line-strong, #8fa36f);
-  --k-text: var(--k-text, #1e2319);
-  --k-text-muted: var(--k-text-muted, #596250);
-  --k-text-faint: var(--k-text-faint, #77816d);
-  --k-positive: var(--k-positive, #2f7d32);
-  --k-caution: var(--k-caution, #8a6500);
-  --k-negative: var(--k-negative, #b93a36);
-  --k-active: var(--k-active, #247f75);
+  --k-brand: #6c9400;
+  --k-brand-contrast: #ffffff;
+  --k-bg: #f3f5eb;
+  --k-panel: #fbfcf7;
+  --k-panel-raised: #eef2e6;
+  --k-line: #ccd5bf;
+  --k-line-strong: #8fa36f;
+  --k-text: #1e2319;
+  --k-text-muted: #596250;
+  --k-text-faint: #77816d;
+  --k-positive: #2f7d32;
+  --k-caution: #8a6500;
+  --k-negative: #b93a36;
+  --k-active: #247f75;
 }
 
 .survey-workbench-embed[data-theme="light"].theme-flow,
 .survey-workbench-embed[data-theme="light"] .theme-flow{
-  --k-brand: var(--k-brand, #1f6f88);
+  --k-brand: #1f6f88;
 }
 
 .survey-workbench-embed[data-theme="light"].theme-surface,
 .survey-workbench-embed[data-theme="light"] .theme-surface{
-  --k-brand: var(--k-brand, #0f6b52);
+  --k-brand: #0f6b52;
 }
 
 
@@ -402,6 +402,17 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
   transition: width 0.35s cubic-bezier(0.2, 0.7, 0.3, 1);
 }
 
+/* \`.progress\` is a generic class name, and a host page may well have its own —
+   @kontourai/ui ships an unscoped \`.progress span { background: linear-gradient(…) }\`
+   that painted a gradient straight over this element's text in an embed. The
+   embed cannot claim the name, but it must not leave its own descendants
+   unstyled and open to a host rule; state the presentation explicitly. */
+.survey-workbench-embed .progress .ptext{
+  display: inline;
+  height: auto;
+  background: none;
+}
+
 .survey-workbench-embed .ptext{
   font-size: 13px;
   color: var(--k-muted);

package/dist/src/review-workbench/review-workbench-data.js

@@ -423,7 +423,7 @@ export const facilityCredentialReviewItemExample = {
         selectedCandidateId: "facility-credential-review-operating-license:candidate:current",
     },
 };
-function queueFixture(name, target, currentValue, proposedValue, candidateSetStatus, feedbackTags) {
+function queueFixture({ name, target, currentValue, proposedValue, candidateSetStatus, feedbackTags, proposalId, excerpts, }) {
     return {
         ...publicDirectoryReviewItemExample,
         metadata: {
@@ -450,6 +450,11 @@ function queueFixture(name, target, currentValue, proposedValue, candidateSetSta
                         ...candidate.source,
                         sourceId: `${name}:source:${role}`,
                     },
+                    locator: {
+                        ...candidate.locator,
+                        locator: `html:field=${target}`,
+                        excerpt: role === "proposed" ? excerpts.proposed : excerpts.current,
+                    },
                     extraction: {
                         ...candidate.extraction,
                         extractionId: `${name}:extraction:${role}`,
@@ -471,6 +476,15 @@ function queueFixture(name, target, currentValue, proposedValue, candidateSetSta
                     },
                     producer: {
                         ...candidate.producer,
+                        ...(role === "proposed" ? { proposalId, oldValue: currentValue } : {}),
+                        ...(candidate.producer?.sourceAuthority
+                            ? {
+                                sourceAuthority: {
+                                    ...candidate.producer.sourceAuthority,
+                                    scope: `${target} field on entity-123`,
+                                },
+                            }
+                            : {}),
                     },
                 };
             }),
@@ -652,12 +666,60 @@ const dailyHoursNoSourceReviewItemExample = {
     status: { observedCandidateCount: 2 },
 };
 export const reviewWorkbenchQueueExamples = [
-    queueFixture("public-directory-hours", "hours", "Weekdays 9am-5pm", "Weekdays 8am-6pm", "needs-review", ["hours-change", "crawler-suggested"]),
-    queueFixture("public-directory-phone", "phoneNumber", "+1-555-0100", "+1-555-0199", "needs-review", ["contact-field", "source-conflict"]),
+    queueFixture({
+        name: "public-directory-hours",
+        target: "hours",
+        currentValue: "Weekdays 9am-5pm",
+        proposedValue: "Weekdays 8am-6pm",
+        candidateSetStatus: "needs-review",
+        feedbackTags: ["hours-change", "crawler-suggested"],
+        proposalId: "proposal-451",
+        excerpts: {
+            current: "Program hours: Weekdays 9am-5pm. Closed weekends and public holidays.",
+            proposed: "Extended schedule for the fall term — program hours are now Weekdays 8am-6pm.",
+        },
+    }),
+    queueFixture({
+        name: "public-directory-phone",
+        target: "phoneNumber",
+        currentValue: "+1-555-0100",
+        proposedValue: "+1-555-0199",
+        candidateSetStatus: "needs-review",
+        feedbackTags: ["contact-field", "source-conflict"],
+        proposalId: "proposal-452",
+        excerpts: {
+            current: "Questions? Call the main office at +1-555-0100.",
+            proposed: "Our enrollment line has moved. Call +1-555-0199 to reach the office.",
+        },
+    }),
     dropInPriceReviewItemExample,
     dailyHoursNoSourceReviewItemExample,
     publicDirectoryReviewItemExample,
-    queueFixture("public-directory-address", "streetAddress", "100 Main Street", "102 Main Street", "needs-review", ["address-change", "producer-escalation-candidate"]),
-    queueFixture("public-directory-license", "licenseStatus", "ACTIVE", "EXPIRED", "escalated", ["licensing", "manual-review-required"]),
+    queueFixture({
+        name: "public-directory-address",
+        target: "streetAddress",
+        currentValue: "100 Main Street",
+        proposedValue: "102 Main Street",
+        candidateSetStatus: "needs-review",
+        feedbackTags: ["address-change", "producer-escalation-candidate"],
+        proposalId: "proposal-453",
+        excerpts: {
+            current: "Find us at 100 Main Street, Example City.",
+            proposed: "We have moved one door down to 102 Main Street, Example City.",
+        },
+    }),
+    queueFixture({
+        name: "public-directory-license",
+        target: "licenseStatus",
+        currentValue: "ACTIVE",
+        proposedValue: "EXPIRED",
+        candidateSetStatus: "escalated",
+        feedbackTags: ["licensing", "manual-review-required"],
+        proposalId: "proposal-454",
+        excerpts: {
+            current: "Operating license status: ACTIVE (renewed 2025-06-01).",
+            proposed: "Operating license status: EXPIRED as of 2026-05-31. Renewal not yet filed.",
+        },
+    }),
     regulatedRuleConflictReviewItemExample,
 ];