freemium-ui 2.0.132 → 2.0.134

package/docs/index.md

@@ -0,0 +1,35 @@
+# Freemium UI
+
+Freemium UI (`freemium-ui` on npm, currently `2.0.133`) is a lightweight React + TypeScript UI component library built on Styled Components. It ships ~30 reusable components (buttons, dropdowns, modals, tables, date pickers, toasts, etc.), a theming layer (`light` / `dark` / `dew`), and a Storybook-driven catalog, and is consumed as a regular npm dependency by the SurveyServ/Freemium frontends.
+
+## Purpose & boundary
+
+Freemium UI exists to give every SurveyServ/Freemium frontend a single, consistent set of presentational React components and a shared theme contract, so product screens don't each reimplement buttons, tables, dropdowns, or overlays. It owns: the component implementations under `src/components/`, the theme definitions (`src/themes/`), and the npm package build/publish pipeline (Rollup + GitHub Actions).
+
+**Not responsible for:** business logic, data fetching/state for a specific product screen, routing, authentication, or backend APIs — those live in the consuming applications (`freshsurvey-web-admin-app`, `survey-admin-microfrontend`, and others). It also does not own any database tables (it is a pure UI library) and does not expose a network API — its contract is everything exported from `src/index.ts`: React components and their props, shared types, theme objects (`Themes`, `FreemiumUiTheme`), `FreemiumUIGlobalStyles`, and `StyleSheetManager` (see [Deep Dive → Contracts & interfaces](architecture/deep-dive.md#2-contracts--interfaces)).
+
+## Tech & runtime
+
+| Aspect                        | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Language(s)                   | TypeScript (`^4.9.5`), strict mode (`tsconfig.json`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Framework(s)                  | React `^17.0.2` (declared as a regular dependency but built as `external` — see [Deep Dive](architecture/deep-dive.md)), Styled Components `^6.1.8`                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Key UI deps                   | `@radix-ui/react-*` (popover, select, dialog/alert-dialog, checkbox, radio-group, tabs, tooltip, dropdown-menu, accordion, toast, label, switch, avatar), `@blueprintjs/datetime2` (date/time pickers), `downshift` (combobox logic), `@dnd-kit/*` (Reorder), `@tanstack/react-table` (Table/WorkspaceTable), `react-quill` (QuillEditor)                                                                                                                                                                                                                                                |
+| Build                         | Rollup 4 (`rollup.config.ts`) → CJS + ESM + `.d.ts` bundles in `lib/`; Storybook 8 for local dev/preview                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Package outputs               | `main: lib/index.cjs.js`, `module: lib/index.js`, `typings: lib/index.d.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Runtime / version constraints | Consumer apps must supply React 17.x themselves — `rollup.config.ts`'s `external` array only excludes `react`/`react-dom` from the bundle; `styled-components` is bundled into `lib/` rather than externalized, despite `getting-started.md` telling consumers to install it separately (see Deep Dive → Dependencies). Local dev observed on Node 16.20.2; `buildspec.yml` uses Node 18, `.github/workflows/pr-quality.yml`/`sonarqube-main.yml` use Node 20 — several devDependencies (Storybook 8, Rollup 4, Husky 9) declare `engines.node >=18` and warn (`EBADENGINE`) on Node 16. |
+
+## What's here
+
+| Section                                                         | What you'll find                                                                                                                                    |
+| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Getting Started](getting-started.md)                           | Local install, Storybook, build, test commands, and the npm publish/version-bump flow                                                               |
+| [Architecture → Code Structure](architecture/code-structure.md) | Every component grouped by category — the "where do I find X" map                                                                                   |
+| [Architecture → Deep Dive](architecture/deep-dive.md)           | Control flow, full contracts table, dependencies/coupling, naming conventions, state/invariants, failure modes, change guidance, staleness triggers |
+| [Operations](operations/monitoring.md)                          | Monitoring, alerts, SOP, support, debugging, recent issues — honest stubs for a library with no running service                                     |
+| [ADRs](adrs/index.md)                                           | Architecture decision records found in the repo/Confluence (currently none)                                                                         |
+
+## Ownership
+
+Team: platforms/plat-maise-surveyserv
+System: platforms/surveyserv

package/docs/operations/alerts-configuration.md

@@ -0,0 +1,11 @@
+# Alerts configuration
+
+There is no dedicated alerting system (no PagerDuty, Opsgenie, Datadog monitor, etc.) configured for this repo — it is a library with no running service to page on.
+
+The closest things to "alerts" today:
+
+- **GitHub Actions failure notifications.** A failed run of any workflow in `.github/workflows/` (`security_verification.yml`, `automated-version-bump.yml`, `pr-preview-deploy.yml`, `enhanced-pr-labeler.yml`, `pr-template-validation.yml`, `stale.yml`) surfaces via GitHub's own notification settings (email/Slack app, per the individual's or org's GitHub notification configuration) — `> [UNVERIFIED]` whether the `platforms/plat-maise-surveyserv` team has a shared Slack channel wired to these via a GitHub-Slack integration; not configured inside this repo's workflow YAML.
+- **`npm publish` failure.** If `publish-after-merge` (in `automated-version-bump.yml`) fails after a version-bump PR is merged, the version bump lands on `main` but the npm package is never actually published — there is no automatic retry or alert; this must be caught by someone noticing the workflow run failed and manually re-running/publishing.
+- **Stale PR bot.** `.github/workflows/stale.yml` runs daily and marks/closes stale PRs — a low-stakes "alert" that a PR has gone unattended.
+
+If you need real alerting (e.g. "notify the team when a publish fails"), it does not exist yet — that would be a new addition to `automated-version-bump.yml` or a GitHub notification/Slack-integration configuration change, not something already wired up.

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

@@ -0,0 +1,43 @@
+# How to Debug
+
+## 1. Reproduce in isolation first
+
+Before debugging inside a consumer app, reproduce the issue in this repo's own Storybook (`npm run storybook`), using the matching theme toolbar setting (`light`/`dark`/`dew`, from `.storybook/preview.tsx`). This immediately tells you whether the bug is in Freemium UI itself or in how the consumer app is using/theming it.
+
+## 2. Turn on the built-in debug flag
+
+`src/utils/index.ts` exposes `appLogger`, gated by a `localStorage` flag:
+
+```js
+localStorage.setItem('fui:debug', JSON.stringify({ log: true }));
+```
+
+Any code path that calls `appLogger('some-title', props)` will then log to the console. As of this writing, grep the codebase for `appLogger(` to see which components currently call it — it is not wired into every component.
+
+> **Caution:** `appLogger` logs whatever `props` it's given verbatim, with no redaction. Only enable `fui:debug` in non-production environments, and don't leave it set on a page that may render real user/customer data.
+
+## 3. Theming issues (wrong colors/fonts/missing styles)
+
+- Confirm `ThemeProvider` is mounted with the theme the consumer expects (`Themes.light`/`.dark`/`.DewTheme`) — components read theme values from styled-components context, not from props, so a missing/duplicate `ThemeProvider` is the most common cause of "unstyled" or wrong-colored components.
+- If using `Themes.DewTheme`: confirm `appendDewStyles({ root, theme, mode })` has actually run and injected the `@freshworks/dew-styles` CSS variables — `DewTheme`'s color/typography/shadow values are literal `var(--color-*)` strings and render as broken/inherited styles if those variables aren't present in the DOM. See [Deep Dive → Failure modes](../architecture/deep-dive.md#6-failure-modes--sharp-edges).
+
+## 4. Overlay/portal issues (Modal, Drawer, Tooltip, Popover, Menu, Dropdown, Confirmation not appearing or clipped)
+
+These all use `usePortalContainer`/`useShadowDomScrollFix` (`src/hooks/index.ts`) to render into `document.body` or a Shadow Root. If an overlay renders in the wrong place or scrolling breaks inside a widget:
+
+- Check whether the app is inside a Shadow DOM — `usePortalContainer` falls back to `document.body` if it can't resolve a `ShadowRoot` from the trigger element's `getRootNode()`.
+- Check `Z_INDEX` (`src/themes/index.ts`) against any competing z-index scheme in the host app.
+
+## 5. Toasts not appearing
+
+- Confirm the component calling `useToasts()` is actually inside a `ThemeProvider` subtree — `useToasts()` outside one silently no-ops (`addToast` does nothing) rather than throwing. See [Deep Dive → State, data & invariants](../architecture/deep-dive.md#5-state-data--invariants).
+- If toasts should persist while the browser tab is unfocused, confirm `retainOnWindowBlur` was passed to `ToastProvider` — note its listener cleanup has a known bug (listeners are added but never actually removed on unmount), see [Deep Dive → Failure modes](../architecture/deep-dive.md#6-failure-modes--sharp-edges).
+
+## 6. Build/bundle issues
+
+- The two Rollup warnings below are **expected** on every `npm run build` and are not regressions: an "Unresolved dependency" for `@freshworks/dew-styles`'s CSS imports, and a "Circular dependency" inside the bundled `@blueprintjs/core`. Anything else new in the build output is worth investigating.
+- If a consumer app's bundle size jumped after a `freemium-ui` bump, check whether the new/updated dependency is in `rollup.config.ts`'s `external` array — if not, it's now bundled into every consumer.
+
+## 7. AutoComplete/network issues
+
+`AutoComplete`'s `url` mode goes through `src/utils/request.ts`, which **swallows all errors and returns `undefined`** rather than rejecting or surfacing an error — a failed fetch looks identical to "no data" from the component's perspective. If `AutoComplete` silently shows no options, check the network tab / server logs directly rather than expecting a thrown error in the component.

package/docs/operations/monitoring.md

@@ -0,0 +1,16 @@
+# Monitoring — Overview
+
+Freemium UI is a published npm library, not a running service — there is no server, container, or endpoint to instrument with APM/metrics/dashboards. "Monitoring" here means **build/publish health**, not runtime health.
+
+What actually exists today:
+
+| Signal                 | Where                                                                                                                                               | What it tells you                                                                                                                                          |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CI build status        | GitHub Actions on the repo (Actions tab)                                                                                                            | Whether `npm install`/lint/build succeeded on a given push/PR                                                                                              |
+| Security scan          | `.github/workflows/security_verification.yml` (`Codepot` scan via `freshactions/codepot@dev`) runs on every push to any branch                      | Whether a push introduced a flagged security issue                                                                                                         |
+| PR preview deploy      | `.github/workflows/pr-preview-deploy.yml` (Storybook build → S3 → optional CloudFront invalidation → PR comment)                                    | Whether a PR's Storybook preview built and deployed; cleaned up by `pr-preview-cleanup.yml` on PR close                                                    |
+| Storybook demo         | `https://freemium-ui.netlify.app` (linked from `README.md`)                                                                                         | Manual visual reference — `> [UNVERIFIED]` whether this is kept auto-deployed from `main` or is stale; no workflow in `.github/workflows/` targets Netlify |
+| npm publish success    | `.github/workflows/automated-version-bump.yml`'s `publish-after-merge` job, and the npm registry page for `freemium-ui`                             | Whether the latest version bump actually published                                                                                                         |
+| Consumer-side breakage | Not monitored from this repo — would show up in `freshsurvey-web-admin-app`'s or `survey-admin-microfrontend`'s own CI/runtime after a version bump | This repo has no visibility into whether a published version broke a consumer                                                                              |
+
+There is no dashboard, APM (Datadog/New Relic/etc.), or bundle-size tracking wired up in this repo today. Bundle size is a known live concern (see [Deep Dive → Failure modes](../architecture/deep-dive.md#6-failure-modes--sharp-edges) — most dependencies are bundled, not externalized) and is called out as an open roadmap item ("Build size optimization" stream) in Confluence, but no automated bundle-size check exists in this repo's CI yet.

package/docs/operations/recent-issues.md

@@ -0,0 +1,14 @@
+# Recent Issues
+
+Sourced from this repo's own git history and the Confluence "Frontend Roadmap — Surveyserv (Backlog 2026)" / "Reskinning Project - Freshworks Dew 2.0 Design System" pages (enrichment only — code is the source of truth for current state).
+
+## Recently fixed (git history)
+
+- **`FSURVEY-8509` — Shadow DOM scrolling issues in `Modal` and `Drawer`.** Wheel/touch scroll events crossing a shadow boundary were getting retargeted and blocked by `react-remove-scroll` (used internally by Radix `Dialog`). Fixed by `useShadowDomScrollFix` (`src/hooks/index.ts`), which stops propagation of `wheel`/`touchmove` at the shadow root when the portal container is inside a Shadow DOM. If a similar "can't scroll inside an embedded widget" report comes in for a component that _doesn't_ already use this hook, that's the fix pattern to reuse.
+
+## Open, evidenced from Confluence (as of this writing — verify current status in Freshrelease before acting)
+
+- **`FSURVEY-8755` — Unit tests for `freemium-ui`.** Tracked as a recurring 2-SP/sprint item until 95% coverage; the repo currently has zero `*.test.*`/`*.spec.*` files (verified locally), so this is a from-scratch effort.
+- **`FSURVEY-8766` — SonarQube integration for `freemium-ui`.** Depends on a cross-repo spike (`FSURVEY-8734`) deciding SonarCloud vs. self-hosted; not yet wired into this repo's CI.
+- **Dew 2.0 reskinning ("Reskinning Project - Freshworks Dew 2.0 Design System", Confluence, last updated Jul 2025) lists `freemium-ui`'s palette/typography/styling consolidation for the Dew theme as "Not Started".** This is stale relative to the code: `Themes.DewTheme` (`src/themes/index.ts`) already exists with a full color/typography/shadow mapping to Dew CSS variables, and `.storybook/preview.tsx` already wires up a `dew` theme toggle. Treat the Confluence page as out of date and the code as current — but the underlying concern (consistent Dew rollout, "supporting dew theme in shadow DOM") may still have open follow-up work; confirm with the owning team rather than assuming it's fully done.
+- **Build size optimization** is an active roadmap stream for the wider Surveyserv frontend family; `freemium-ui` itself isn't explicitly one of the Stream 5 line items in the roadmap page, but [Deep Dive → Failure modes](../architecture/deep-dive.md#6-failure-modes--sharp-edges) shows nearly all of its dependencies (`@radix-ui/*`, `@blueprintjs/*`, `@dnd-kit/*`, `@tanstack/react-table`, `styled-components`, `react-quill`, etc.) are bundled rather than externalized — a natural candidate if/when that stream reaches this repo.

package/docs/operations/sop.md

@@ -0,0 +1,25 @@
+# SOP (Standard Operating Procedures)
+
+## Cutting a new release
+
+1. Merge the change(s) into `main` (normal PR flow — see `.github/pull_request_template.md`).
+2. From the Actions tab, manually trigger **"Automated Version Bump and Publish"** (`workflow_dispatch` on `.github/workflows/automated-version-bump.yml`), choosing `patch`/`minor`/`major`.
+3. This opens a `chore(release): bump version to vX.Y.Z` PR against `main` — review it (it should only touch `package.json`/`package-lock.json`) and merge it.
+4. Merging triggers `publish-after-merge`: `npm ci && npm run build`, then `npm publish` to `registry.npmjs.org`, a `vX.Y.Z` git tag, and generated release notes. Confirm the workflow run went green and the new version shows up on the npm registry.
+5. If a downstream repo (`freshsurvey-web-admin-app`, `survey-admin-microfrontend`) needs the new version, that is a **separate** PR in that repo bumping its own `freemium-ui` version range — this repo's publish does not push changes to dependents.
+
+Full command-level detail: [Getting Started → Version bump & npm publish flow](../getting-started.md#version-bump--npm-publish-flow).
+
+## Reviewing a dependency bump PR
+
+- Check whether the bumped dependency is in `rollup.config.ts`'s `external` array (currently only `react`/`react-dom`) — if not, it will be **bundled** into `lib/`, so a major version bump of any other dependency (all `@radix-ui/*`, `@blueprintjs/*`, `styled-components`, etc.) changes what ships inside the published package, not just what's installed locally.
+- Run `npm run build` locally and check for **new** Rollup warnings beyond the two known/expected ones (the `@blueprintjs/core` circular dependency, the `@freshworks/dew-styles` CSS unresolved-dependency) — see [Deep Dive → Failure modes](../architecture/deep-dive.md#6-failure-modes--sharp-edges).
+- For a `react`/`react-dom` bump: check both known dependents (`freshsurvey-web-admin-app`, `survey-admin-microfrontend`) are on a compatible version before merging, since they are not covered by this repo's CI.
+
+## Adding/changing a component
+
+Follow [Deep Dive → Change guidance](../architecture/deep-dive.md#7-change-guidance) — scaffold the four-file component split, add the barrel export, add a Storybook story, and run `npm run lint && npm run typescript && npm run build` before opening a PR. The `.github/pull_request_template.md` requires ticking "Documentation" / "Source" checkboxes as applicable and filling the "What should the SDET know?" section — there is no SDET-owned test suite in this repo today (`npm test` finds 0 test files), so manual Storybook verification is the practical bar.
+
+## Handling a stale PR bot action
+
+`.github/workflows/stale.yml` runs daily and will mark/close inactive PRs automatically — if a legitimate long-running PR gets flagged, comment on it or push a commit to reset its stale timer; there is no manual override list configured.

package/docs/operations/support.md

@@ -0,0 +1,15 @@
+# Support — Overview
+
+**Owning team:** `platforms/plat-maise-surveyserv` (see `catalog-info.yaml`), part of the `platforms/surveyserv` system.
+
+**Where to file issues:** GitHub Issues on this repo — `https://github.com/freshdesk/freemium-ui/issues` (from `package.json#bugs.url`). Internally, work is tracked in Freshrelease under the `FSURVEY` project (e.g. `FSURVEY-8755` — unit tests for `freemium-ui`, tracked on the Confluence "Frontend Roadmap — Surveyserv (Backlog 2026)" page).
+
+**Who consumes this library (and would be affected by a regression):** `freshsurvey-web-admin-app` and `survey-admin-microfrontend`, both in `platforms/surveyserv` — see [Deep Dive → Dependencies & coupling](../architecture/deep-dive.md#3-dependencies--coupling).
+
+**What support does _not_ cover:** this repo has no running service, so there is no on-call rotation, incident channel, or runtime SLA for it in the traditional sense. `> [UNVERIFIED]` whether `platforms/plat-maise-surveyserv` has a dedicated Slack channel for this repo — none is referenced in the repo itself; check the team's Prism/Backstage entity or ask the team directly.
+
+**Typical support scenarios:**
+
+- _"A component looks/behaves wrong in my app"_ — first reproduce it in Storybook (`npm run storybook`) against the same theme (`light`/`dark`/`dew`) the consumer app uses; see [How to Debug](how-to-debug.md).
+- _"I need a prop/component that doesn't exist yet"_ — check [Deep Dive → Contracts & interfaces](../architecture/deep-dive.md#2-contracts--interfaces) first; some things (e.g. `QuillEditor`, several icons) already exist in the codebase but aren't exported yet — that's a small, low-risk PR rather than new work.
+- _"A version bump broke my app"_ — check the release notes on the relevant `vX.Y.Z` GitHub tag/release, and compare against [Deep Dive → Failure modes](../architecture/deep-dive.md#6-failure-modes--sharp-edges) for known sharp edges (bundling, Dew CSS-variable dependency, React version assumptions).

package/lib/README.md

@@ -85,3 +85,12 @@ Publish the package to npm
 ```
 npm publish
 ```
+
+## AIPDLC (SurveyServ)
+
+This repo is onboarded to AIPDLC (Freshworks AI Product Development Lifecycle) for the SurveyServ team.
+
+- Run AIPDLC phases with the SurveyServ scope, e.g. `/fw-system-design --scope=bu/surveyserv`.
+- `/fw-init` generates a local `.aipdlc/workspace.json` pointer; it is **gitignored** (per-developer, per-epic state) — run `/fw-init` locally to (re)create it.
+- Team-wide AIPDLC customization (dev/deploy overlays, rules) lives in `freshworks/ai-builder-artifacts` under `bu/platform/modules/surveyserv/`.
+- This package pins **Node 18** (see `.nvmrc`; Storybook 8 requires Node ≥18) — run `nvm use` before installing.