freemium-survey-components 2.0.484 → 2.0.486

package/docs/operations/alerts-configuration.md

@@ -0,0 +1,19 @@
+# Alerts Configuration
+
+No alerting is configured for this repo, and none is expected to be — it has no runtime to alert
+on (see [Monitoring → Overview](monitoring.md)).
+
+The only automated notification wired up in this repo is a best-effort Slack post on successful
+npm publish, defined in `.github/workflows/automated-version-bump.yml` (`Notify Slack channel`
+step): it posts to `SLACK_WEBHOOK_URL` (if configured as a repo secret) announcing the package
+name, version, and release URL after a version-bump PR is merged and published. This step runs
+with `continue-on-error: true` — a missing webhook or a failed post does not fail the workflow and
+nobody is alerted if it silently fails.
+
+If GitHub Actions failure notifications matter to this team (e.g. a failed `publish-after-merge`
+job), they come from GitHub's own workflow-failure notification settings for the repo/org, not from
+anything configured inside this codebase.
+
+> [UNVERIFIED] Whether org-level GitHub Actions failure notifications (email/Slack) are configured
+> for this repo outside of the workflow file itself was not checked — that would live in GitHub
+> org/repo notification settings, not in source control.

package/docs/operations/how-to-debug.md

@@ -0,0 +1,73 @@
+# How to Debug
+
+## 1. Enable the library's built-in debug logging
+
+`src/utils.tsx`'s `appLogger` gates every internal `console.log` call behind a `localStorage` flag
+read by `getFreshSurveyDebug` (`src/constants.ts`: `FRESH_SURVEY_DEBUG = 'fsc:debug'`). In the
+browser console, on the page rendering the survey:
+
+```js
+localStorage.setItem('fsc:debug', JSON.stringify({ log: true }));
+// then reload the page
+```
+
+This turns on `appLogger('Survey', {...})`, `appLogger('Card', {...})`,
+`appLogger('Standard', {...})`, `appLogger('Widget', {...})`, and per-`useEffect` logging inside
+`useCardSurvey`/`useStandardSurvey` — each call logs the component name and the full current
+props/state (survey, answers, active block/index, rendered blocks). This is the fastest way to see
+exactly what the navigation engine believes the current state is.
+
+`src/types.ts`'s `FreshSurveyDebugType` defines sibling debug flags used by other SurveyServ
+frontends under the same `localStorage` mechanism (`fwa:debug` for the admin app, `mfe:debug` for
+the microfrontend, `spw:debug` for the public widget, `spp:debug` for the public page, `fui:debug`
+for `freemium-ui`) — if you're debugging an issue that spans this library and its host, check
+whether the host has its own equivalent flag.
+
+> **Security note:** this logs the *full* current props/state, including `answers.formValues` —
+> real survey respondent data (which may include names, emails, free-text answers, or other PII).
+> Only enable `fsc:debug` in non-production environments. If you must reproduce against production
+> data, redact identifying fields before sharing the console output, and clear the `fsc:debug` key
+> from `localStorage` afterward (it persists across page reloads and sessions until removed).
+
+## 2. Reproduce in Storybook first
+
+Before debugging inside a consumer app, try to reproduce with the same survey shape in Storybook
+(`npm run storybook`) using a story under `src/stories/` or `src/survey/*.stories.tsx`, adapting
+`src/mocks/index.ts`'s `MOCK_SURVEY` to match the reported shape. If it reproduces in Storybook,
+the bug is in this repo; if it doesn't, the bug is likely in the consumer's integration (see
+[Support](support.md)).
+
+## 3. Isolate: navigation/branching vs. rendering vs. validation
+
+- **Wrong question shown next / survey ends too early or too late** → the bug is almost certainly
+  in `src/survey/utils/logics.ts` (`getNextLogicalBlock`, `fetchNextBlockIndex`,
+  `getNextBlockIndex`, `evaluateConditions`). Log the survey's `blocks`/`dependent_blocks`/
+  `display_logic` and the current `answers.formValues` (via `fsc:debug`) and trace which branch of
+  `evaluateConditions` should fire for the given operator/answer.
+- **A question renders with the wrong widget or missing data** → check the `switch` in
+  `src/survey/question.tsx` for that `question_type`, and the corresponding component under
+  `src/components/`.
+- **A "Next"/"Submit"/"Skip" button is missing, disabled, or in the wrong state** → check
+  `canDisplayButton`/`canDisableButton` (`logics.ts`) for that `ActionButtonTypes` case — these
+  functions are shared across all three layouts, so also check whether `surveyStyle`/`isWidget`/
+  `isMobile` branches inside the specific case are gating on the wrong condition for your layout.
+- **A field won't let the user proceed / shows a validation error incorrectly** → check the
+  relevant `*Validator` function in `logics.ts` (`dateValidator`, `formValidator`,
+  `textboxValidator`, `contactformValidator`, `fileUploadQnValidator`) and the corresponding
+  `ValidatingQuestions` error bucket.
+
+## 4. Check for the known sharp edges first
+
+Before deep-diving, rule out the documented gotchas in
+[Deep Dive → Failure modes & sharp edges](../architecture/deep-dive.md#6-failure-modes--sharp-edges) —
+in particular: `null` vs `undefined` in `answers.formValues` (skip vs. unanswered), the
+`survey.updated_at`-keyed caching in `useSurvey`, and README examples that no longer match the
+current prop shapes.
+
+## 5. There is no server-side log to check
+
+Because this library never makes a network call itself, there is no backend log, trace, or APM
+entry to correlate against — everything observable happens in the consumer's browser. If the
+report includes a network-layer symptom (e.g. `onFileUpload` failing), the failure is inside the
+callback the **host** implemented, not inside this library's call site — confirm the host's
+implementation of `onFileUpload`/`onSubmit` before assuming a library bug.

package/docs/operations/monitoring.md

@@ -0,0 +1,26 @@
+# Monitoring — Overview
+
+`freemium-survey-components` is a build-time-consumed UI component library, not a running
+service. There is no deployed process, endpoint, container, or pod for this repo to monitor — it
+has no uptime, no request rate, no dashboards of its own.
+
+What actually needs watching lives elsewhere:
+
+- **Runtime errors and rendering issues** surface inside the four consuming applications
+  (`survey-public-widget`, `survey-public-page`, `freshsurvey-web-admin-app`,
+  `survey-admin-microfrontend`) — their own frontend error monitoring / RUM tooling is where a bug
+  in this library would actually be observed in production. See
+  [How to Debug](how-to-debug.md) for how to correlate an issue back to this repo.
+- **Build/publish health** is observable via GitHub Actions runs on
+  `.github/workflows/automated-version-bump.yml` (version-bump PR creation and the
+  publish-after-merge job) — a failed `npm publish` or `npm run build` step there is the closest
+  thing this repo has to an "incident."
+- **Bundle size** (`lib/index.esm.js` / `lib/index.cjs.js` ~839 KB gzipped JS, `lib/bundle.css`
+  ~42 KB gzipped as of this writing) is not tracked automatically in CI today — see
+  [Deep Dive → Failure modes](../architecture/deep-dive.md#6-failure-modes--sharp-edges). If this
+  is added in the future, this page should be updated to describe it.
+- **Storybook/Chromatic** (`npm run chromatic`) provides visual-regression signal at PR time, not
+  runtime monitoring — see [Getting Started](../getting-started.md).
+
+There is no APM, log aggregation, or metrics pipeline configured in this repo, and none is
+expected for a library with this shape.

package/docs/operations/recent-issues.md

@@ -0,0 +1,22 @@
+# Recent Issues
+
+This page tracks recent notable fixes merged to this repo, as a quick "have we seen this before"
+reference. Source: `git log` on `main`. Update this list as new notable fixes land — do not let it
+grow unbounded; keep roughly the last 10–15 entries and drop the oldest.
+
+| Ticket                   | Summary                                                                                             |
+| ------------------------ | --------------------------------------------------------------------------------------------------- |
+| FSURVEY-8673             | Added `enableAnalytics` flag to `ProductConfigType`.                                                |
+| FSURVEY-8628             | Renamed the thank-you header CSS class to `fsc-thankyou-footer`.                                    |
+| FSURVEY-8568             | Fixed the `RESOLUTION` question and thank-you card rendering together and ignoring other questions. |
+| FSURVEY-8425             | Fixed Facebook-channel-preview button alignment and a NUMBER-variant issue with a minimum of 0.     |
+| FSURVEY-8425 (follow-up) | Fixed MCQ rendering issues in the survey.                                                           |
+| FSURVEY-8546             | Hid the widget footer when it would render no visible content.                                      |
+| MISC                     | Onboarded this repo to the Prism software catalog (`catalog-info.yaml`, `techdocs-ref: dir:.`).     |
+
+For anything not covered here, search closed PRs/issues on `freshdesk/freemium-survey-components`
+by `FSURVEY-` ticket prefix, or search Confluence space `SP` for
+"freemium-survey-components" (engineering briefs, roadmap docs) — see
+[Deep Dive → Failure modes & sharp edges](../architecture/deep-dive.md#6-failure-modes--sharp-edges)
+for the known, still-open structural issues (no test coverage, no PR CI gate, undeclared `lodash`
+dependency, inconsistent HTML sanitization) that are more "known risk" than "recent issue."

package/docs/operations/sop.md

@@ -0,0 +1,44 @@
+# SOP (Standard Operating Procedures)
+
+There is no running service to operate, restart, scale, or fail over — see
+[Monitoring → Overview](monitoring.md). The procedures below cover the two situations that
+actually recur for a published component library: cutting a release, and reacting to a broken
+release.
+
+## Cutting a release
+
+Follow [Getting Started → Versioning & npm publish flow](../getting-started.md#versioning--npm-publish-flow):
+trigger `automated-version-bump.yml` via `workflow_dispatch`, choose the version bump type, review
+and merge the generated PR, then confirm the `publish-after-merge` job succeeded (npm publish + git
+tag + GitHub Release).
+
+Before triggering a release:
+
+- Run `npm run build` locally and confirm it succeeds (CI does not run this for you on the
+  version-bump PR — see [Deep Dive → Failure modes](../architecture/deep-dive.md#6-failure-modes--sharp-edges)).
+- Run `npm run test-storybook` against a running/built Storybook and confirm no unexpected
+  snapshot diffs.
+- If the change affects a `PUBLIC` export's shape (see
+  [Deep Dive → Contracts & interfaces](../architecture/deep-dive.md#2-contracts--interfaces)),
+  choose `minor` or `major` accordingly, not `patch`, and note the breaking change in the PR.
+
+## Reacting to a broken release (bad version published to npm)
+
+1. **Do not attempt to unpublish** — npm restricts unpublishing versions with existing downloads;
+   treat forward-fixing as the default path.
+2. Trigger `automated-version-bump.yml` again with `version_type: patch` for a fix once the
+   regression is corrected on `main`.
+3. Notify the four consuming repos (`survey-public-widget`, `survey-public-page`,
+   `freshsurvey-web-admin-app`, `survey-admin-microfrontend`) if any of them auto-upgrade or are
+   about to release against the bad version — see
+   [Deep Dive → Dependencies & coupling](../architecture/deep-dive.md#3-dependencies--coupling)
+   for why version skew across consumers means impact isn't uniform or immediate.
+4. If the break is severe enough that consumers must pin away from it, communicate the last-known-good
+   version explicitly (e.g. in the incident thread / PR) since there is no automated deprecation
+   tooling wired into this repo's publish workflow.
+
+## Rolling back a merged-but-bad PR on `main`
+
+Standard git revert-and-release: revert the offending commit(s) on `main`, then follow "Cutting a
+release" above for a `patch` release containing the revert. There is no separate rollback
+mechanism for a published npm package beyond publishing a new (higher) version.

package/docs/operations/support.md

@@ -0,0 +1,39 @@
+# Support — Overview
+
+**Owning team:** `platforms/plat-maise-surveyserv` (system: `platforms/surveyserv`).
+
+Because this library has no runtime of its own, "support" for it means one of two things:
+
+1. **A consumer app hits a bug that traces back to this library** (rendering, navigation/branching,
+   validation, or a question-type widget behaving incorrectly). Start with
+   [How to Debug](how-to-debug.md) to confirm the bug is actually in this repo and not in how a
+   consumer is calling `Survey`/`WebInAppSurvey`/`ChannelPreview`, then file/fix it here.
+2. **A consumer needs a change to the public contract** (new question type, new prop, new exported
+   component) — see [Deep Dive → Change guidance](../architecture/deep-dive.md#7-change-guidance)
+   for what has to change together, and [Deep Dive → Contracts & interfaces](../architecture/deep-dive.md#2-contracts--interfaces)
+   for what's safe to change without a version bump vs. what's a breaking change for the four
+   dependent repos.
+
+## Where to raise things
+
+- **Bugs / feature requests against this repo:** GitHub issues on
+  `freshdesk/freemium-survey-components` (see `bugs.url` in `package.json`), or a PR directly using
+  this repo's `.github/pull_request_template.md`.
+- **"Is this library or my integration?"** — reproduce against a Storybook story first
+  (`npm run storybook`); if the same survey/question renders correctly in Storybook with the same
+  props but not in your app, the issue is very likely in how the consumer is calling the component
+  (prop shape, missing `onSubmit`/`callback()` invocation, CSS variable collision — see
+  [Deep Dive → Dependencies & coupling → Hidden coupling](../architecture/deep-dive.md#3-dependencies--coupling)),
+  not in this library.
+- **Freshrelease tracking:** ticket IDs referenced in commit/PR titles in this repo follow the
+  `FSURVEY-xxxx` pattern (see recent `git log` history and `.github/pull_request_template.md`'s
+  Ticket Reference section).
+
+## What good bug reports include
+
+- The exact `SurveyType` (or a minimal reproducing subset) and `answers` payload passed in.
+- Which top-level component was used (`Survey` vs `WebInAppSurvey` vs `ChannelPreview`) and
+  `surveyStyle`/`surveyType`.
+- Console output with `fsc:debug` logging enabled — see [How to Debug](how-to-debug.md).
+- The installed `freemium-survey-components` version (`npm ls freemium-survey-components` in the
+  consumer repo).

package/lib/bundle.css

@@ -3283,7 +3283,7 @@ div.surveyserv-widget-container.compact-container-style .fsc-radio-group button.
 .surveyserv-widget-container .question-container.thankyou .text,
 .freemium-survey-components .question-container.thankyou .text {
   text-align: center;
-  white-space: pre-wrap;
+  white-space: normal;
   font-weight: 500;
   font-size: var(--message-font-size, var(--fsc-font-size));
   word-break: break-word;