@explorer02/cfm-survey-sdk 0.2.3 → 0.2.4

package/templates/docs/templates/SliderMatrixScale.tsx

@@ -0,0 +1,248 @@
+'use client';
+
+/**
+ * Portable SliderMatrixScale — copy to src/components/SliderMatrixScale.tsx
+ * Requires: CustomSliderTrack.tsx, surveyUiScaleUtils.ts
+ */
+
+import React from 'react';
+import type { SliderMatrixQuestion, MatrixRowAnswers } from '@explorer02/cfm-survey-sdk';
+import { tickColorFromIndex } from './surveyUiScaleUtils';
+import { CustomSliderTrack } from './CustomSliderTrack';
+
+type SliderMatrixScaleProps = {
+  question: SliderMatrixQuestion;
+  selectedValue?: MatrixRowAnswers;
+  onSelect: (value: MatrixRowAnswers) => void;
+};
+
+export function SliderMatrixScale({ question, selectedValue = {}, onSelect }: SliderMatrixScaleProps) {
+  const {
+    statementRows,
+    scaleAnchorLabels: labels,
+    ticks,
+    enableInputBox,
+    displayValues,
+    hasNotApplicableOption: enableNotApplicable,
+    sliderStyle,
+  } = question;
+
+  const tickCount = ticks.count;
+  const tickValues = ticks.marks.map((mark, index) => ({
+    value: mark.tickPosition,
+    label: mark.tickLabel,
+    color: tickColorFromIndex(index, tickCount),
+  }));
+  const sliderType = sliderStyle === 'graphics' ? 'graphics' : undefined;
+
+  const handleSliderChange = (rowId: string, val: number | 'N/A') => {
+    onSelect({ ...selectedValue, [rowId]: val });
+  };
+
+  const baseRow = statementRows[0];
+  const min = baseRow?.min ?? 0;
+  const max = baseRow?.max ?? 10;
+  const step = baseRow?.step ?? 1;
+
+  const marks: number[] = [];
+  if (tickCount && tickCount > 1) {
+    const markStep = (max - min) / (tickCount - 1);
+    for (let i = 0; i < tickCount; i++) {
+      marks.push(Number((min + i * markStep).toFixed(2)));
+    }
+  } else {
+    for (let i = min; i <= max; i += step) {
+      marks.push(Number(i.toFixed(2)));
+    }
+  }
+
+  const htmlStep = tickCount && tickCount > 1 ? (max - min) / (tickCount - 1) : step;
+
+  const renderHeaderRow = () => {
+    if ((!labels || labels.length === 0) && tickValues.length === 0) {
+      return null;
+    }
+    return (
+      <div style={{
+        display: 'flex', width: '100%', marginBottom: '4px', alignItems: 'flex-end',
+        padding: '0 16px', boxSizing: 'border-box',
+      }}>
+        <div style={{ flex: '0 0 25%', paddingRight: '16px' }} />
+
+        <div style={{ flex: '1', position: 'relative' }}>
+          {labels && labels.length > 0 && (
+            <div style={{
+              position: 'relative', display: 'flex', justifyContent: 'space-between',
+              margin: '0 16px', marginBottom: '16px', color: '#111827', fontSize: '14px', fontWeight: 500,
+            }}>
+              {labels.map((lbl, idx) => (
+                <div key={idx} style={{ width: 0, display: 'flex', justifyContent: 'center' }}>
+                  <span style={{ whiteSpace: 'nowrap' }}>{lbl}</span>
+                </div>
+              ))}
+            </div>
+          )}
+
+          <div style={{
+            position: 'relative', margin: '0 16px', marginBottom: '8px',
+            color: '#4b5563', fontSize: '14px', fontWeight: 400, height: '28px',
+          }}>
+            {tickValues.length > 0 ? (
+              tickValues.map((tv, idx) => {
+                const percentage = max !== min ? ((tv.value - min) / (max - min)) * 100 : 0;
+                const sliceWidth = tickValues.length > 1 ? 100 / (tickValues.length - 1) : 100;
+                return (
+                  <div key={idx} style={{
+                    position: 'absolute', left: `${percentage}%`, transform: 'translateX(-50%)',
+                    width: `${sliceWidth}%`, display: 'flex', justifyContent: 'center',
+                  }}>
+                    {sliderType === 'graphics' ? (
+                      <div style={{ wordBreak: 'break-word', textAlign: 'center', lineHeight: '1.2', fontWeight: 500, color: '#4b5563', fontSize: '13px' }}>
+                        {tv.label}
+                      </div>
+                    ) : (
+                      <div style={{
+                        backgroundColor: tv.color, color: 'white', padding: '4px 8px', borderRadius: '4px',
+                        fontWeight: 600, wordBreak: 'break-word', textAlign: 'center', lineHeight: '1.2',
+                        boxShadow: '0 1px 2px rgba(0,0,0,0.1)',
+                      }}>
+                        {tv.label}
+                      </div>
+                    )}
+                  </div>
+                );
+              })
+            ) : (
+              marks.map((m, idx) => {
+                const percentage = max !== min ? ((m - min) / (max - min)) * 100 : 0;
+                const sliceWidth = marks.length > 1 ? 100 / (marks.length - 1) : 100;
+                return (
+                  <div key={idx} style={{
+                    position: 'absolute', left: `${percentage}%`, transform: 'translateX(-50%)',
+                    width: `${sliceWidth}%`, display: 'flex', justifyContent: 'center',
+                  }}>
+                    <span style={{ wordBreak: 'break-word', textAlign: 'center', lineHeight: '1.2' }}>{m}</span>
+                  </div>
+                );
+              })
+            )}
+          </div>
+        </div>
+
+        {enableInputBox && <div style={{ width: '80px', marginLeft: '16px' }} />}
+        {enableNotApplicable && (
+          <div style={{ width: '40px', marginLeft: '16px', textAlign: 'center', fontSize: '13px', fontWeight: 600, color: '#4b5563', paddingBottom: '8px' }}>
+            N/A
+          </div>
+        )}
+      </div>
+    );
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+      {renderHeaderRow()}
+
+      {statementRows.map(row => {
+        const rowVal = selectedValue[row.id];
+        const isNa = rowVal === 'N/A';
+        const val = typeof rowVal === 'number' ? rowVal : isNa ? row.min : (row.defaultValue ?? row.min);
+
+        return (
+          <div key={row.id} style={{
+            display: 'flex', width: '100%', alignItems: 'center',
+            backgroundColor: '#f3f4f6', borderRadius: '12px', padding: '16px', boxSizing: 'border-box',
+          }}>
+            <div style={{ flex: '0 0 25%', paddingRight: '16px', fontSize: '15px', color: '#111827', wordWrap: 'break-word', display: 'flex', alignItems: 'center' }}>
+              {row.statementText !== 'Question' && row.statementText !== '' ? (
+                <span dangerouslySetInnerHTML={{ __html: row.statementText }} />
+              ) : null}
+            </div>
+
+            <div style={{ flex: '1' }}>
+              <CustomSliderTrack
+                min={row.min}
+                max={row.max}
+                htmlStep={htmlStep}
+                value={val}
+                disabled={isNa}
+                displayValues={displayValues}
+                hasSelectedValue={typeof rowVal === 'number'}
+                sliderType={sliderType}
+                ticks={tickCount}
+                onChange={v => handleSliderChange(row.id, v)}
+              />
+            </div>
+
+            {enableInputBox && (
+              <div style={{
+                marginLeft: '16px', width: '80px', display: 'flex', alignItems: 'stretch',
+                border: '1px solid #d1d5db', borderRadius: '8px', overflow: 'hidden',
+                backgroundColor: isNa ? '#e5e7eb' : '#fff', boxSizing: 'border-box',
+              }}>
+                <input
+                  type="text"
+                  value={isNa ? '' : Math.round(Number(val))}
+                  disabled={isNa}
+                  onChange={e => {
+                    if (e.target.value === '') return;
+                    let num = Number(e.target.value);
+                    if (!isNaN(num)) {
+                      if (num < row.min) num = row.min;
+                      if (num > row.max) num = row.max;
+                      handleSliderChange(row.id, num);
+                    }
+                  }}
+                  style={{
+                    width: '50px', padding: '8px', border: 'none',
+                    fontSize: '14px', outline: 'none', backgroundColor: 'transparent', textAlign: 'center',
+                  }}
+                />
+                <div style={{ display: 'flex', flexDirection: 'column', borderLeft: '1px solid #d1d5db', backgroundColor: '#f9fafb', width: '30px' }}>
+                  <button
+                    disabled={isNa}
+                    onClick={() => {
+                      const num = Number((Number(val) + htmlStep).toFixed(2));
+                      if (num <= row.max) handleSliderChange(row.id, num);
+                    }}
+                    style={{ flex: 1, border: 'none', background: 'none', cursor: isNa ? 'not-allowed' : 'pointer', display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#4b5563' }}
+                  >
+                    <svg width="10" height="6" viewBox="0 0 10 6" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1 5L5 1L9 5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" /></svg>
+                  </button>
+                  <div style={{ height: '1px', backgroundColor: '#d1d5db', width: '100%' }} />
+                  <button
+                    disabled={isNa}
+                    onClick={() => {
+                      const num = Number((Number(val) - htmlStep).toFixed(2));
+                      if (num >= row.min) handleSliderChange(row.id, num);
+                    }}
+                    style={{ flex: 1, border: 'none', background: 'none', cursor: isNa ? 'not-allowed' : 'pointer', display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#4b5563' }}
+                  >
+                    <svg width="10" height="6" viewBox="0 0 10 6" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1 1L5 5L9 1" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" /></svg>
+                  </button>
+                </div>
+              </div>
+            )}
+
+            {enableNotApplicable && (
+              <div style={{ marginLeft: '16px', width: '40px', display: 'flex', justifyContent: 'center' }}>
+                <input
+                  type="checkbox"
+                  checked={isNa}
+                  onChange={e => {
+                    if (e.target.checked) {
+                      handleSliderChange(row.id, 'N/A');
+                    } else {
+                      handleSliderChange(row.id, row.defaultValue ?? row.min);
+                    }
+                  }}
+                  style={{ width: '20px', height: '20px', cursor: 'pointer' }}
+                />
+              </div>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/templates/docs/templates/SurveyStickyChrome.tsx

@@ -0,0 +1,24 @@
+import Header from '@/components/Header';
+import ProgressBar from '@/components/ProgressBar';
+
+type SurveyStickyChromeProps = {
+  progressPercentage: number;
+};
+
+/**
+ * Sticky top chrome: brand header + progress bar.
+ * Keeps progress visible while scrolling long pages (e.g. last question below the fold).
+ */
+export default function SurveyStickyChrome({ progressPercentage }: SurveyStickyChromeProps) {
+  return (
+    <div
+      className="sticky top-0 z-30 shadow-[0_2px_8px_rgba(0,0,0,0.06)]"
+      style={{ background: 'var(--cfm-header-bg, #fff)' }}
+    >
+      <Header embedded />
+      <div className="mx-auto w-full max-w-4xl px-4 pb-5 pt-4 sm:px-6 lg:px-8">
+        <ProgressBar progressPercentage={progressPercentage} />
+      </div>
+    </div>
+  );
+}

package/templates/docs/templates/customFieldValues.ts

@@ -0,0 +1,36 @@
+/**
+ * Portable custom field values template — copy to src/lib/customFieldValues.ts
+ *
+ * Populate keys from survey logic rules where conditionEntity.entityType === 'CUSTOM_FIELD'.
+ * Values come from CRM/transaction context — NOT from survey respondent UI.
+ *
+ * See: docs/00-integration/custom-field-logic-and-navigation.md
+ *      docs/00-integration/client-lib-folder.md
+ */
+
+import type { CustomFieldValueMap } from '@explorer02/cfm-survey-sdk';
+
+/**
+ * fieldType → client value shape:
+ *
+ * | fieldType              | Value shape                          | Example |
+ * |------------------------|--------------------------------------|---------|
+ * | TEXT / TEXT_MULTI      | string                               | 'abc' |
+ * | TEXTAREA               | string                               | 'long text' |
+ * | NUMBER                 | number or numeric string             | 2 or '0' |
+ * | PICKLIST               | string (option id)                   | 'uuid-option-id' |
+ * | PICKLIST_MULTISELECT   | string[] (option ids)                | ['id-a', 'id-b'] |
+ * | DATETIME               | epoch ms (number or numeric string)  | 1781029800000 |
+ *
+ * Missing keys are treated as empty for logic evaluation.
+ */
+export const CUSTOM_FIELD_VALUES: CustomFieldValueMap = {
+  // Example — skip SLIDER page when CASE_SENSITIVE_TEXT equals 'abc' (integration-test survey):
+  // '_c_67199096d294be011a2b4773': 'abc',
+
+  // '_c_6a436c1244764c9d4a6ce2fc': 'var2',              // TEXT
+  // '_c_6a436c3644764c9d4a6ce3f5': 2,                   // NUMBER
+  // '_c_6a436c9e44764c9d4a6ce717': 'option-id-uuid',     // PICKLIST
+  // '_c_6a436cbb44764c9d4a6ce7e5': ['option-id'],        // PICKLIST_MULTISELECT
+  // '_c_6a4386dc44208eb8b08a9056': 1781029800000,        // DATETIME epoch ms
+};

package/templates/docs/templates/implementation_plan.md

@@ -1,13 +1,15 @@
 # Survey UI Implementation Plan
 
 > Copy this file to `./implementation_plan.md` in the project root. Fill every section before writing React code.
+>
+> Pipeline: [`agent-operating-contract.md`](../00-integration/agent-operating-contract.md) → [`agent-execution-flow.md`](../00-integration/agent-execution-flow.md)
 
 ## 0. Project Context
 
 - **Framework:** [ ] Next.js App Router  [ ] Vite  [ ] CRA  [ ] Existing app
 - **Package import name:** (from `package.json` — `@explorer02/cfm-survey-sdk` or `@repo/sdk`)
 - **instanceId:** (JWT — wired in SurveyPage)
-- **Branding source:** (client prompt / mockup description — no wizard)
+- **Branding source:** (client prompt / mockup description; optional wizard override via `survey-ui-config.json`)
 
 ## 1. Data Fetching & State
 
@@ -26,6 +28,7 @@
 - [ ] `onAction` START / NEXT / PREVIOUS / SUBMIT wiring
 - [ ] `onAction(SCROLL)` once on first scroll (mark as started)
 - [ ] `onAction(RECORD_QUESTION_VIEW)` via IntersectionObserver on question wrappers
+- [ ] `SurveyStickyChrome` (sticky Header + ProgressBar) on content phase — see `19-survey-sticky-chrome.md`
 - [ ] `ProgressBar` bound to `state.progressPercentage` (path-scoped — see `00-integration/progress.md`)
 - [ ] Back via `state.canGoBack`; primary label via `state.primaryButtonType`
 - [ ] Read `00-integration/skip-logic-and-navigation.md` for skip/Back behavior
@@ -91,7 +94,34 @@ Fill from `00-integration/component-checklist.md`:
 | `RankOrderScale.tsx` | `RANK_ORDER` | |
 | `lib/heatmapCoords.ts` | `HEATMAP` | copy from `templates/heatmapCoords.ts` |
 
-## 3c. Logic inventory (from fetched survey)
+| `lib/surveyUiScaleUtils.ts` | NPS/matrix colors | copy from `templates/surveyUiScaleUtils.ts` |
+| `lib/customFieldValues.ts` | CRM logic input | copy from `templates/customFieldValues.ts` when survey has `_c_…` ids |
+| `lib/surveyUiScaleUtils.ts` | NPS/tick/matrix helpers | copy from `templates/surveyUiScaleUtils.ts` |
+| `lib/surveyUiIcons.tsx` | CSAT emoji/star | copy from `templates/surveyUiIcons.tsx` |
+
+## 3c. Matrix variant inventory (from fetched survey)
+
+Read `00-integration/canonical-survey-fixtures.md`. For each matrix question note:
+
+| questionId | type | displayStyle | statementLayout | transposeTable | selectionMode | Labels visible? |
+|------------|------|--------------|-----------------|----------------|---------------|---------------|
+| | | | | | | row + column/anchor |
+
+## 3d. Custom field inventory (mandatory when `_c_…` ids found)
+
+After fetch, scan `skipLogics`, `displayLogic`, `answerLogic`, and `endPages` for `entityType: 'CUSTOM_FIELD'`.
+
+| `_c_` id | fieldType | used in (skip/display/answer/end) | logic field (e.g. CASE_SENSITIVE_TEXT) | CRM value | populated in `lib/customFieldValues.ts`? |
+|----------|-----------|-----------------------------------|----------------------------------------|-----------|---------------------------------------------|
+| | | | | | |
+
+**Blocking gate:** if any row above is filled → copy `templates/customFieldValues.ts` → `src/lib/customFieldValues.ts` before Phase 5 BUILD.
+
+Wire map in **both** places: `useSurveySDK({ options: { customFieldValues } })` and `<Question customFieldValues={...} />`.
+
+See `00-integration/custom-field-logic-and-navigation.md` and `00-integration/client-lib-folder.md`.
+
+## 3e. Logic inventory (from fetched survey)
 
 Scan `survey.pages` for logic flags. Fill after fetch:
 
@@ -99,9 +129,7 @@ Scan `survey.pages` for logic flags. Fill after fetch:
 |------------|------------|--------------|----------------------------------|---------------------------|
 | | | | | |
 
-Custom field ids found → populate `CUSTOM_FIELD_VALUES` map. See `00-integration/custom-field-logic-and-navigation.md`.
-
-## 3d. Per-Type SDK Integration (from fetched survey)
+## 3f. Per-Type SDK Integration (from fetched survey)
 
 Fill from `00-integration/question-type-sdk-matrix.md`:
 
@@ -119,7 +147,7 @@ Fill from `00-integration/question-type-sdk-matrix.md`:
 | LikertMatrixScale | | `06-likert-matrix-scale.md` |
 | SliderMatrixScale | | `07-slider-matrix-scale.md` |
 | FileUploadScale | | `08-file-upload-scale.md` |
-| Header / Footer / ProgressBar / LanguageSelector | | `10`–`12` |
+| Header / Footer / SurveyStickyChrome / LanguageSelector | | `10`–`12`, `19` |
 
 ## 3e. Interaction dependencies (from survey inventory)
 
@@ -139,7 +167,7 @@ Inventory required config fields per type:
 | MCQ | `selectionMode`, `minSelections`, `maxSelections`, `defaultOptionIds`, answer-logic on options |
 | RANK_ORDER | `interactionMode`, `optionDisplay`, `requireRankAll`, `shuffleOptions` |
 | CFM/CSAT/RATING | `gridLayout`, `displayStyle`, `selectionMode`, `hasNotApplicableOption`, `statementLayout` |
-| SLIDER_MATRIX | `enableInputBox`, `enableNotApplicable`, `sliderStyle` |
+| SLIDER_MATRIX | `enableInputBox`, `hasNotApplicableOption`, `sliderStyle`, `statementRows`, `ticks` |
 | FILE_UPLOAD | `maxFileCount`, `fileSizeLimit`, `fileSizeLimitType`, upload API configured? |
 | HEATMAP | `maxClicksAllowed`, image URL |
 
@@ -149,8 +177,27 @@ Inventory required config fields per type:
 
 ## 5. Theme, Brand & Logo
 
-- [ ] CSS-only logo (no `<img>`, no `public/` uploads)
+- [ ] Logo: text/CSS (`data-cfm-logo-text`) **or** local `public/` image (`data-cfm-logo`) — see `wizard-preview-build-guide.md`; no external URLs
 - [ ] Primary / hover colors from client prompt
+- [ ] `src/styles/survey-theme.css` with `--cfm-*` CSS variables (full template set)
+- [ ] **Wizard preview contract:** `var(--cfm-*)` in chrome/scales + `data-cfm-*` on editable text/logo — see `00-integration/wizard-preview-build-guide.md`
+- [ ] **Wizard per-type styling:** `selectionStyles.ts`, `labelStyles.ts`, per-type tokens — see `00-integration/wizard-question-type-styling.md`
+- [ ] **Draft** `./survey-ui-config.json` in sync with theme tokens (seeds optional wizard in Phase 6b)
+- [ ] `previewBridge.ts` wired for wizard live preview (see `ui-customization-wizard.md`)
+- [ ] If `survey-ui-config.json` exists: apply per `apply-ui-config.md` (Phase 5 draft or Phase 6c final)
+
+## 5b. Wizard handoff (Phase 6b–6c — when client uses wizard)
+
+See `wizard-config-handoff.md`.
+
+- [ ] `customize-ui` uploaded component previews to S3
+- [ ] Deployed wizard link sent to client: `http://43.204.26.213:3000/wizard-app/index.html?session=…&secret=…` (from CLI output)
+- [ ] CLI `customize-ui` exited 0 — waited for client submit
+- [ ] Read `survey-ui-config.diff.md` — paths changed: ___
+- [ ] Applied from `survey-ui-config.final.json` (AWS) or `survey-ui-config.json` (local)
+- [ ] Every diff path applied (count matches)
+- [ ] `confirm-ui-config` run (AWS)
+- [ ] Verify + build re-run after apply
 
 ## 6. Submit & Thank You
 
@@ -165,7 +212,7 @@ Inventory required config fields per type:
 - [ ] `bash templates/verify-agent-build.sh` passes
 - [ ] `grep -r "not yet implemented"` → zero matches
 
-## 8. AWS Deploy Readiness (fill if client prompt mentions AWS / CloudFront / S3 / EC2 / Sprinklr)
+## 8. AWS Deploy Readiness (fill if client prompt mentions AWS / CloudFront / S3 / EC2 / Sprinklr, or wizard deploy.target is aws)
 
 - [ ] Next.js `output: "export"` + `assetPrefix: "./"` configured (see `setup.md#nextjs-aws-static-export`)
 - [ ] `images.unoptimized: true` in `next.config.js`

package/templates/docs/templates/labelStyles.ts

@@ -0,0 +1,33 @@
+/**
+ * Label item styling for matrix / slider tick labels (wizard Question Types step).
+ * Copy to `src/lib/surveyUi/labelStyles.ts`.
+ */
+import type { CSSProperties } from 'react';
+
+export function hintLabelStyle(): CSSProperties {
+  return {
+    color: 'var(--cfm-hint-label-color, #6b7280)',
+    backgroundColor: 'var(--cfm-hint-label-bg, transparent)',
+  };
+}
+
+export function matrixColumnLabelStyle(): CSSProperties {
+  return {
+    color: 'var(--cfm-matrix-column-label-color, #4b5563)',
+    backgroundColor: 'var(--cfm-matrix-column-label-bg, transparent)',
+  };
+}
+
+export function csatColumnLabelStyle(): CSSProperties {
+  return {
+    color: 'var(--cfm-csat-column-label-color, #4b5563)',
+    backgroundColor: 'var(--cfm-csat-column-label-bg, transparent)',
+  };
+}
+
+export function sliderTickLabelStyle(): CSSProperties {
+  return {
+    color: 'var(--cfm-slider-tick-label-color, #4b5563)',
+    backgroundColor: 'var(--cfm-slider-tick-label-bg, transparent)',
+  };
+}

package/templates/docs/templates/selectionStyles.ts

@@ -0,0 +1,100 @@
+/**
+ * Portable selection styling helpers for wizard live preview + apply-ui-config.
+ * Copy to `src/lib/surveyUi/selectionStyles.ts` when building agent projects.
+ *
+ * Question card theme tokens (wizard → Theme & Colors → Question card):
+ *   --cfm-matrix-selected     = cell selected color (annulus fill between ring and dot)
+ *   --cfm-input-focus-ring   = focus ring (outer border + inner dot)
+ */
+import type { CSSProperties } from 'react';
+
+export const cellSelectedVar = 'var(--cfm-matrix-selected, var(--cfm-primary))';
+export const focusRingVar = 'var(--cfm-input-focus-ring, var(--cfm-primary))';
+
+const unselectedRing = '#d1d5db';
+const unselectedDot = '#d1d5db';
+
+/** NPS / large scale radio — outer ring border + annulus fill. */
+export function scaleRadioRingStyle(
+  isSelected: boolean,
+  opts: { pill?: boolean; size?: string } = {},
+): CSSProperties {
+  const { pill = false, size = 'var(--cfm-nps-cell-size, 32px)' } = opts;
+  return {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: size,
+    height: size,
+    borderRadius: pill ? '9999px' : '50%',
+    border: `2px solid ${isSelected ? focusRingVar : unselectedRing}`,
+    backgroundColor: isSelected ? cellSelectedVar : '#fff',
+    transition: 'all 0.15s',
+    boxSizing: 'border-box',
+  };
+}
+
+/** Inner dot — focus ring color when selected. */
+export function scaleRadioDotStyle(
+  isSelected: boolean,
+  opts: { pill?: boolean } = {},
+): CSSProperties {
+  const { pill = false } = opts;
+  return {
+    borderRadius: '50%',
+    width: pill ? '40%' : '33%',
+    height: pill ? '40%' : '33%',
+    backgroundColor: isSelected ? focusRingVar : unselectedDot,
+  };
+}
+
+/** Compact matrix radio (CSAT / Likert / CFM grid). */
+export function matrixRadioRingStyle(isSelected: boolean, size = '18px'): CSSProperties {
+  return {
+    display: 'flex',
+    width: size,
+    height: size,
+    alignItems: 'center',
+    justifyContent: 'center',
+    borderRadius: '50%',
+    margin: '0 auto',
+    border: `2px solid ${isSelected ? focusRingVar : unselectedRing}`,
+    backgroundColor: isSelected ? cellSelectedVar : '#fff',
+    transition: 'all 0.15s',
+    boxSizing: 'border-box',
+  };
+}
+
+export function matrixRadioDotStyle(isSelected: boolean, size = '8px'): CSSProperties {
+  return {
+    width: size,
+    height: size,
+    borderRadius: '50%',
+    backgroundColor: isSelected ? focusRingVar : 'transparent',
+  };
+}
+
+/** Numbered / solid scale cell when selected. */
+export function scaleCellSelectedStyle(isSelected: boolean): CSSProperties {
+  return isSelected
+    ? {
+        border: `2px solid ${focusRingVar}`,
+        backgroundColor: cellSelectedVar,
+        color: '#fff',
+      }
+    : {};
+}
+
+export function unselectedOpacityStyle(): CSSProperties {
+  return { opacity: 'var(--cfm-csat-unselected-opacity, 0.5)' };
+}
+
+export function emojiSizeStyle(): CSSProperties {
+  return {
+    fontSize: 'var(--cfm-csat-emoji-size, 28px)',
+    lineHeight: 1,
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+  };
+}

package/templates/docs/templates/surveyUiIcons.tsx

@@ -12,7 +12,9 @@ import {
   FaFaceGrin,
   FaFaceGrinWide,
   FaFaceGrinStars,
+  FaStar,
 } from 'react-icons/fa6';
+import { FaRegStar } from 'react-icons/fa';
 
 const EMOJI_COLORS = [
   '#dc2626', '#e04832', '#ea580c', '#f59e0b', '#eab308',
@@ -50,3 +52,12 @@ export function getEmojiForIndex(index: number, total: number): React.ReactNode
   const key = Math.min(11, Math.max(1, Math.round(percent * 10) + 1));
   return CsatEmojiSet[key];
 }
+
+export const CsatStarIcons: { filled: React.ReactNode; empty: React.ReactNode } = {
+  filled: React.createElement(FaStar as React.ElementType, {
+    style: { color: '#e20074', fontSize: '28px' },
+  }),
+  empty: React.createElement(FaRegStar as React.ElementType, {
+    style: { color: '#d1d5db', fontSize: '28px', stroke: '#d1d5db', strokeWidth: '16px' },
+  }),
+};

package/templates/docs/templates/surveyUiScaleUtils.ts

@@ -0,0 +1,51 @@
+/**
+ * Portable scale utilities — copy to src/lib/surveyUiScaleUtils.ts or co-locate with components.
+ */
+import type { NpsScalePoint, ScaleColumn } from '@explorer02/cfm-survey-sdk';
+
+export const SCALE_COLORS: readonly string[] = [
+  '#e2001a', '#e4251b', '#ec610a', '#f18b00', '#f7b200', '#fcd900',
+  '#d2dc00', '#9fca00', '#6bb300', '#339a00', '#008000',
+] as const;
+
+export function getAccentColor(value: number): string {
+  return SCALE_COLORS[value] ?? '#e20074';
+}
+
+export function tickColorFromIndex(index: number, total: number): string {
+  if (total <= 1) return '#e20074';
+  const hue = Math.round((index / (total - 1)) * 120);
+  return `hsl(${hue}, 90%, 40%)`;
+}
+
+export function nonNaScaleColumns(columns: ScaleColumn[]): ScaleColumn[] {
+  return columns.filter(col => col.id !== 'na');
+}
+
+export function starValueFromOption(option: NpsScalePoint, index: number): number {
+  const numeric = Number(option.optionLabel);
+  return Number.isFinite(numeric) && option.optionLabel.trim() !== '' ? numeric : index;
+}
+
+export function npsValueFromOption(option: NpsScalePoint, index: number): number {
+  const numeric = Number(option.optionLabel);
+  return Number.isFinite(numeric) && option.optionLabel.trim() !== '' ? numeric : index;
+}
+
+/** Matches SDK matrixColumnStoredValue — scale-matrix answers store column ids. */
+export function matrixColumnStoredValue(column: { id: string; label: string }): string | null {
+  return column.id === 'na' ? null : column.id;
+}
+
+/** @deprecated Use matrixColumnStoredValue */
+export function columnSubmitValue(column: { id: string; label: string }): string | null {
+  return matrixColumnStoredValue(column);
+}
+
+export function columnAccentColor(column: { id: string; label: string }): string | undefined {
+  const numeric = Number(column.label);
+  if (Number.isFinite(numeric) && column.label.trim() !== '') {
+    return getAccentColor(numeric);
+  }
+  return undefined;
+}