freemium-ui 2.0.133 → 2.0.134

package/.github/actionlint.yaml

@@ -0,0 +1,6 @@
+self-hosted-runner:
+  # fw-shared is the org's shared self-hosted runner label, used by every
+  # pull_request-triggered quality-gate job across the survey/freemium repos
+  # (e.g. survey-admin-microfrontend). Not an unknown/typo'd label.
+  labels:
+    - fw-shared

package/.github/pr_validation_guide.md

@@ -0,0 +1,305 @@
+# PR Validation Guide
+
+This document explains how PR validation works in the `freemium-ui` repository.
+
+## Overview
+
+Validation happens in two layers:
+
+```text
+┌──────────────────────┬─────────────────────────────────────┬─────────────────────┐
+│ Layer                │ What It Validates                   │ When                │
+├──────────────────────┼─────────────────────────────────────┼─────────────────────┤
+│ Git Hooks (Local)    │ Commit message format (fail-fast)   │ On commit           │
+│                      │ Lint, format, install, build        │ On commit           │
+├──────────────────────┼─────────────────────────────────────┼─────────────────────┤
+│ GitHub Actions       │ PR template completeness            │ On PR open/edit     │
+│                      │ Stale PR management                 │ Daily cron          │
+└──────────────────────┴─────────────────────────────────────┴─────────────────────┘
+```
+
+---
+
+## Local Validation — Git Hooks (Husky)
+
+### `.husky/pre-commit`
+
+Runs every time you commit, **before** the commit message is checked. Executes the quality & build chain:
+
+```text
+npm run lint    →   npm run format    →   npm install    →   npm run build
+```
+
+Any failure aborts the commit with a non-zero exit code.
+
+> The repo currently has no unit tests, so `npm run test` is intentionally **not** part of the pre-commit chain. Add it back once tests exist.
+
+### `.husky/commit-msg`
+
+Runs after `pre-commit` passes. Validates only the commit message format — no lint/test/build work happens here.
+
+Required format:
+
+```text
+type: [TICKET-ID] message
+```
+
+- **Valid types:** `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `perf`, `ci`, `build`, `style`, `revert`
+- **Valid tickets:** `MP-xxxx`, `FS-xxxx`, `FSURVEY-xxxx`, `DEVREL-xxxx`, `PLAT-xxxx`, `MISC`, `Docs`
+
+Examples:
+
+```text
+✅ feat: [FSURVEY-2024] Add new Dropdown variant
+✅ fix: [MP-12345] Fix Tooltip positioning
+✅ chore: [MISC] Bump rollup version
+✅ docs: [Docs] Update Storybook README
+❌ Add dropdown component              (no type, no ticket)
+❌ feat: Add dropdown component        (no ticket)
+❌ Feat: [MP-123] Add dropdown         (type must be lowercase)
+```
+
+**Skipped automatically for:**
+
+- Merge commits (`Merge branch ...`, `Merge pull request ...`)
+- Revert commits (`Revert ...`)
+- Dependabot-style commits (`Bump X from Y to Z`)
+
+### Bypass (Emergency Only)
+
+```bash
+git commit --no-verify -m "..."
+```
+
+Skips all local hooks. Server-side PR validation will still enforce the title format on PR open.
+
+---
+
+## GitHub Actions Workflows
+
+### 1. PR Template Validation
+
+**File:** `.github/workflows/pr-template-validation.yml`
+
+**Triggers:** PR `opened`, `edited`, `synchronize`
+
+**Purpose:** Ensures the PR title and description follow the template contract. Posts a sticky validation comment and fails the check (blocks merge via branch protection) when required sections are missing.
+
+**Automated PRs are skipped** (Dependabot, Renovate, github-actions[bot], mergify[bot], snyk-bot, and any author ending in `[bot]`).
+
+#### 🔴 REQUIRED — Blocks merge if missing
+
+| #   | Check                        | Rule                                                                           |
+| --- | ---------------------------- | ------------------------------------------------------------------------------ |
+| 1   | PR Title                     | Must match `type: [TICKET-ID] description` with valid type and ticket          |
+| 2   | Type of Change               | At least one `- [x]` checked                                                   |
+| 3   | Ticket Reference             | PR body must contain `- **Ticket ID**: [FSURVEY-xxxx]` (or other valid prefix) |
+| 4   | Changes Made                 | At least **3** real bullet points (placeholders like `Change 1:` don't count)  |
+| 5   | Affected Areas               | At least one `- [x]` checked                                                   |
+| 6   | Breaking Changes             | Exactly one of "Yes" / "No" checked                                            |
+| 7   | Breaking Changes Description | If "Yes" selected, description must be > 50 characters                         |
+
+#### 🟡 RECOMMENDED — Warning only, does not block
+
+| #   | Check              | Rule                                                                                                     |
+| --- | ------------------ | -------------------------------------------------------------------------------------------------------- |
+| 1   | Testing            | Numbered test steps with real content (not just `1. Step 1`)                                             |
+| 2   | SDET Guidance      | > 30 chars of real content (placeholders stripped)                                                       |
+| 3   | Screenshots/Videos | If `.tsx` files under `src/components/` or `src/stories/` changed and no image/video URL in Screenshots |
+
+### 2. Stale PR Management
+
+**File:** `.github/workflows/stale.yml`
+
+**Triggers:** Daily cron (`0 0 * * *`) and manual dispatch.
+
+**Purpose:** Closes/labels stale PRs and issues to keep the backlog tidy.
+
+---
+
+## Validation Flow
+
+When you run `git commit`:
+
+```text
+.husky/pre-commit
+   └─ npm run lint → npm run format → npm install → npm run build
+.husky/commit-msg
+   └─ validate message format (fails fast if malformed)
+```
+
+When you open a PR:
+
+```text
+GitHub Actions:
+  └─ PR Template Validation    (sticky comment, can block merge)
+
+Manual:
+  └─ Code review approval
+```
+
+---
+
+## What Gets Checked Where
+
+| Check                      |   Local (Husky)   | GitHub Actions |
+| -------------------------- | :---------------: | :------------: |
+| Commit message format      | ✅ (`commit-msg`) |                |
+| Lint                       | ✅ (`pre-commit`) |                |
+| Format                     | ✅ (`pre-commit`) |                |
+| Unit tests                 |     ⏸️ (none yet)     |                |
+| Install                    | ✅ (`pre-commit`) |                |
+| Build (rollup)             | ✅ (`pre-commit`) |                |
+| PR title format            |                   |       ✅       |
+| Type of Change selected    |                   |       ✅       |
+| Ticket ID in body          |                   |       ✅       |
+| Changes Made (min 3)       |                   |       ✅       |
+| Affected Areas selected    |                   |       ✅       |
+| Breaking Changes selection |                   |       ✅       |
+| Breaking description (>50) |                   |       ✅       |
+| Testing info               |                   |   ⚠️ (warn)    |
+| SDET guidance              |                   |   ⚠️ (warn)    |
+| Screenshots for UI changes |                   |   ⚠️ (warn)    |
+
+---
+
+## How to Fix Validation Failures
+
+### Local: "Invalid commit message format!"
+
+The `commit-msg` hook rejected your message (this runs after `pre-commit`). Re-run with the correct shape:
+
+```bash
+git commit -m "feat: [FSURVEY-8530] Add new Dropdown variant"
+```
+
+Since the message is preserved in `.git/COMMIT_EDITMSG`, re-running `git commit` (no `-m`) will reopen your editor with the previous content.
+
+### Local: Lint/format/install/build failed
+
+The `pre-commit` hook ran the quality chain and one step failed. Run the failing step directly to debug:
+
+```bash
+npm run lint
+npm run format
+npm install
+npm run build
+```
+
+### PR Template Validation Failed (GitHub Actions)
+
+1. Open the PR on GitHub → click **Edit** on the description
+2. Read the sticky "🔍 PR Template Validation Report" comment — it lists every failing check
+3. Fix the sections it flags. Common issues:
+   - **Ticket Reference missing:** Your body still has the placeholder `[FSURVEY-xxxx / PLAT-xxxx / MISC / Docs]`. Replace with the exact form: `- **Ticket ID**: [FSURVEY-8530]`
+   - **Changes Made insufficient:** Need at least 3 real bullets under `## Changes Made` — placeholders like `Change 1:` don't count
+   - **Breaking Changes:** Must check exactly one of Yes/No; both unchecked or both checked fails
+4. Save the PR description — the workflow re-runs automatically on the `edited` event
+
+### Common Gotchas
+
+| Symptom                                          | Cause                                                                                                                        |
+| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| Validation fails with valid-looking title        | PR title is lowercase `feat:` (correct) but ticket bracket has extra text like `[FSURVEY-8530 test]`                         |
+| "Ticket Reference missing" despite filling it in | The placeholder text `[FSURVEY-xxxx / PLAT-xxxx / MISC / Docs]` was not replaced with a real ticket like `[FSURVEY-8530]`                |
+| Screenshot warning on non-visual PR              | Path-based detection — any `.tsx` under `src/components/` or `src/stories/` triggers it even for pure logic changes          |
+
+---
+
+## Best Practices
+
+### Before Committing
+
+Since the `pre-commit` hook runs lint/format/install/build, ensure they pass cleanly:
+
+```bash
+npm run lint
+npm run format
+npm install
+npm run build
+```
+
+### Writing a Good PR
+
+1. **Keep it focused** — small, single-purpose PRs review faster
+2. **Fill the template honestly** — at least 3 meaningful bullets under Changes Made
+3. **Describe "why", not just "what"** — the Motivation section is free-form for a reason
+4. **Add screenshots/videos / Storybook links** for any UI/component change (recommended, not enforced)
+5. **Fill SDET guidance** when the change has non-obvious edge cases
+
+### PR Description Checklist
+
+Before you submit:
+
+- ✅ Type of Change has at least one `[x]`
+- ✅ Ticket ID line shows `- **Ticket ID**: [FSURVEY-0000]` with the real number
+- ✅ Changes Made has 3+ real bullets
+- ✅ Affected Areas has at least one `[x]`
+- ✅ Breaking Changes has exactly one `[x]` (Yes or No)
+- ✅ If breaking Yes: description > 50 chars
+- ✅ Screenshots / Storybook link added for UI changes (recommended)
+- ✅ Testing & SDET Guidance filled (recommended)
+
+---
+
+## Troubleshooting
+
+### GitHub Actions doesn't run on my PR
+
+1. Check the **Actions** tab of the repo for errors
+2. Verify the workflow file is on the PR's base branch (not only the feature branch)
+3. Confirm the PR author isn't auto-classified as a bot (skip logic inspects `user.type` and login suffix `[bot]`)
+4. The workflow uses `secrets.RUNWAYCI_GITHUB_PAT_TOKEN` — if it's missing or expired, the validation step fails before running any check
+
+### Validation seems wrong
+
+1. Copy your exact PR description and inspect it against the regexes in `.github/workflows/pr-template-validation.yml`
+2. Remember: checkboxes must use `- [x]` (lowercase `x`), though the code is actually case-insensitive (`[X]` also works)
+3. Bold must be `**Ticket ID**:` exactly — no underscores, no extra spaces inside the `**`
+
+### Need to bypass validation
+
+- **Local hook:** `git commit --no-verify` (skips both `pre-commit` and `commit-msg`)
+- **PR template validation:** Cannot be bypassed without repo admin disabling the required status check — this is intentional
+
+---
+
+## Configuration
+
+To change validation rules:
+
+| File                                           | What to change                                                                   |
+| ---------------------------------------------- | -------------------------------------------------------------------------------- |
+| `.github/workflows/pr-template-validation.yml` | Server-side template validation logic (regexes, thresholds, required vs warning) |
+| `.github/pull_request_template.md`             | The template users see when opening a PR                                         |
+| `.husky/commit-msg`                            | Local commit message format validation                                           |
+| `.husky/pre-commit`                            | Local lint / format / test / install / build chain                               |
+
+### Ticket Prefix Changes
+
+Valid ticket prefixes are defined in **two** places and must stay in sync:
+
+- `.husky/commit-msg` — regex `ticket_pattern` around line 30
+- `.github/workflows/pr-template-validation.yml` — `titleRegex` (line ~100) and `ticketRegex` (line ~137)
+
+---
+
+## Summary
+
+This system enforces:
+
+- ✅ Consistent commit messages (local, fail-fast)
+- ✅ Compilable, linted, formatted, tested code (local, before commit)
+- ✅ Complete PR descriptions with traceability to a ticket (GitHub Actions)
+
+All automated — fill the PR template properly and use the commit format, and the checks will pass.
+
+---
+
+## Related Files
+
+- [Pull Request Template](./pull_request_template.md)
+- [PR Template Validation Workflow](./workflows/pr-template-validation.yml)
+- [Stale PR Workflow](./workflows/stale.yml)
+- [Husky commit-msg Hook](../.husky/commit-msg)
+- [Husky pre-commit Hook](../.husky/pre-commit)

package/.github/pull_request_template.md

@@ -0,0 +1,189 @@
+<!---
+📋 PR Template Guidelines:
+- PR TITLE must follow format: type: [TICKET-ID] description
+  Example: feat: [MP-12345] Add new Dropdown variant · feat: [FS-12345] for FS tickets
+- Sections marked with ⚠️ REQUIRED will be validated by GitHub Actions
+- Sections marked with ⚠️ RECOMMENDED should be filled for better reviews
+- Incomplete required sections will block PR merge
+- See .github/workflows/pr-template-validation.yml for validation rules
+-->
+
+## Type of Change ⚠️ REQUIRED
+
+<!--- REQUIRED: Put an `x` in at least ONE box that applies -->
+<!--- This should match your commit message type (feat/fix/chore/docs/etc.) -->
+
+- [ ] Feature (new functionality)
+- [ ] Bugfix (fixes an issue)
+- [ ] Refactor (code improvement without changing functionality)
+- [ ] Maintenance (dependency updates, chores)
+- [ ] Performance (optimization)
+- [ ] Documentation (content or code documentation updates)
+- [ ] Security (security fixes or improvements)
+- [ ] Configuration (build, CI/CD, or tooling changes)
+
+## Ticket Reference ⚠️ REQUIRED
+
+<!--- REQUIRED: Link to the related ticket or story -->
+
+- **Ticket ID**: [FSURVEY-xxxx / PLAT-xxxx / MISC / Docs]
+- **Ticket Link**: [Link to Freshrelease story or issue]
+
+## Motivation
+
+<!--- Why is this change required? What problem does it solve? -->
+<!--- If it fixes an open issue, please link to the freshrelease story here or ensure the id is in the PR title. -->
+<!--- Please ensure that you have run all lints related to this repo and also ensure that your PR is small enough for quick review. -->
+
+## Changes Made ⚠️ REQUIRED
+
+<!--- REQUIRED: Provide a clear description of what you changed -->
+<!--- REQUIRED: List at least 3 main changes in bullet points -->
+
+- Change 1:
+- Change 2:
+- Change 3:
+
+## Affected Areas ⚠️ REQUIRED
+
+<!--- REQUIRED: Put an `x` in at least ONE box that applies -->
+
+- [ ] Source (`src`)
+- [ ] Build / Bundling (`rollup.config.ts`, `scripts/`, `tsconfig.json`)
+- [ ] CI/CD workflows (`.github/workflows`)
+- [ ] Dependencies (`package.json`)
+
+## Breaking Changes ⚠️ REQUIRED
+
+<!--- REQUIRED: Select one option -->
+
+- [ ] Yes, this PR introduces breaking changes
+- [ ] No breaking changes
+
+<!--- REQUIRED if Yes: Describe the breaking changes (API changes, removed props, renamed components, version-bump impact) and migration steps below -->
+
+## Checklist
+
+<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
+<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
+
+### Code Quality
+
+- [ ] My code follows the code style of this project
+- [ ] I have run `npm run lint` and fixed all errors
+- [ ] I have run `npm run format` to format the code
+- [ ] No console.log or debugging code left in the changes
+  - Format: `type: [TICKET-ID] message`
+  - Valid types: feat, fix, chore, docs, refactor, test, perf, ci, build, style, revert
+  - Valid tickets: FSURVEY-xxxx / PLAT-xxxx / MISC / Docs
+
+### Testing
+
+- [ ] I have added tests to cover my changes
+- [ ] I have verified the component visually in Storybook (`npm run storybook`)
+- [ ] I have tested on multiple browsers (if UI changes)
+- [ ] All new and existing tests passed (`npm run test`)
+- [ ] I have tested the production bundle (`npm run build`)
+
+### Documentation
+
+- [ ] My change requires a change to the documentation
+- [ ] I have updated the documentation / Storybook stories accordingly
+- [ ] I have updated code comments where necessary
+- [ ] I have added JSDoc comments for new functions/components
+
+### Accessibility & Security
+
+- [ ] I have tested keyboard navigation (if UI changes)
+- [ ] I have verified ARIA labels and semantic HTML (if UI changes)
+- [ ] I have validated component props (required vs optional, defaults)
+- [ ] I have checked for security vulnerabilities (`npm audit`)
+
+### Dependencies
+
+- [ ] I have added new dependencies (list them below)
+- [ ] I have updated existing dependencies (list them below)
+- [ ] I have verified dependency compatibility with existing peer dependencies
+- [ ] I have checked for security vulnerabilities in new dependencies
+
+<!--- List new or updated dependencies here -->
+
+**New/Updated Dependencies:**
+
+-
+-
+
+## How Has This Been Tested? ⚠️ RECOMMENDED
+
+<!--- RECOMMENDED: Describe in detail how you tested your changes -->
+<!--- Include details of your testing environment and test steps -->
+
+**Testing Environment:**
+
+- Node version:
+- npm version:
+- Browser(s) tested:
+
+**Test Steps:**
+
+1. Step 1
+2. Step 2
+3. Step 3
+
+**Test Results:**
+
+- Result 1
+
+## Screenshots/Videos ⚠️ REQUIRED FOR UI CHANGES
+
+<!--- REQUIRED for UI changes: Add screenshots, videos, or a Storybook link to demonstrate the changes -->
+<!--- REQUIRED: Include before/after screenshots for visual changes -->
+
+**Before:**
+
+**After:**
+
+## Performance Impact
+
+<!--- Describe any performance implications of this change -->
+
+- [ ] No performance impact
+- [ ] Performance improvement (describe below)
+- [ ] Potential performance impact (describe below)
+
+<!--- If applicable, include bundle size changes, build time changes, etc. -->
+
+## Deployment / Release Notes
+
+<!--- Any special publish considerations? -->
+<!--- Version bump type (patch/minor/major), consumer migration, peer-dep updates, etc. -->
+
+- [ ] No special release steps required
+- [ ] Requires a specific version bump (patch / minor / major — describe below)
+- [ ] Requires consumer migration (describe below)
+
+## What should the SDET know? ⚠️ RECOMMENDED
+
+<!--- RECOMMENDED: Provide testing guidance for QA team -->
+<!--- Include test scenarios, edge cases, and areas to focus on -->
+
+- Test scenario 1:
+- Edge case to check:
+- Focus area:
+
+## Additional Context
+
+<!--- Add any other context, links, or information that reviewers should know -->
+<!--- Related PRs, design documents, API documentation, etc. -->
+
+## Reviewer Checklist
+
+<!--- For reviewers - ensure these are verified -->
+
+- [ ] Code changes align with the motivation and description
+- [ ] No unnecessary files or changes included
+- [ ] Code follows project conventions and style guide
+- [ ] Tests / stories are adequate and passing
+- [ ] Documentation is updated if needed
+- [ ] No security vulnerabilities introduced
+- [ ] Performance / bundle-size impact is acceptable

package/.github/workflows/pr-quality.yml

@@ -0,0 +1,114 @@
+name: PR Quality
+
+on:
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: pr-quality-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Lint, format, test, and build
+    runs-on: fw-shared
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # SonarQube needs full history for blame attribution and new-code
+          # detection, plus the base branch to diff the pull request against.
+          fetch-depth: 0
+          # Do not leave the GITHUB_TOKEN in the workspace git config. The SonarQube
+          # scan action runs in a container with the workspace mounted, and no step
+          # here performs a git network operation that would need the credential.
+          persist-credentials: false
+
+      # Node 20 LTS — align with org runner or bump when standard changes
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      # Configures npm to fetch @freshworks scoped packages from GitHub Packages —
+      # needed here because this package depends on @freshworks/dew-styles.
+      - name: Configure npm for GitHub Packages
+        run: |
+          echo "@freshdesk:registry=https://npm.pkg.github.com/" >> .npmrc
+          echo "@freshworks:registry=https://npm.pkg.github.com/" >> .npmrc
+          echo "@freshworksinc:registry=https://npm.pkg.github.com/" >> .npmrc
+          echo "//npm.pkg.github.com/:_authToken=${{ secrets.GH_AUTH_TOKEN }}" >> .npmrc
+
+      # --ignore-scripts: this job runs PR-controlled code, and npm ci runs
+      # lifecycle scripts (this repo's own `prepare` script, plus any
+      # dependency's install/postinstall) before the token is removed below.
+      # No dependency here has an install script that's actually needed to
+      # build or test (verified against the lockfile) — husky's `prepare` is
+      # pointless in CI anyway, since no local commit happens here.
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      # The step above appends a literal GH_AUTH_TOKEN to the workspace .npmrc.
+      # Remove it so the token does not persist into later steps — the SonarQube
+      # scan action runs in a container with the workspace mounted. No step after
+      # this one installs packages. The tracked .npmrc in this repo is empty, so
+      # there's nothing to restore — just delete the appended file.
+      - name: Remove npm auth token from workspace
+        if: ${{ always() }}
+        run: git checkout -- .npmrc || rm -f .npmrc
+
+      - name: Prettier check
+        run: npm run check
+
+      - name: ESLint
+        run: npm run lint:ci
+
+      # Coverage is collected here (not a plain test run) so SonarQube has an
+      # lcov report to read.
+      - name: Unit tests
+        timeout-minutes: 15
+        env:
+          CI: true
+        run: npm run test:coverage
+
+      # Reads sonar-project.properties for scope/exclusions; the pull request
+      # parameters below are the only per-run values.
+      # continue-on-error: the SonarQube instance is at its server-wide LOC
+      # licence limit, so analyses can fail server-side. A quality signal must
+      # not block PRs until that is resolved and the quality gate is reviewed.
+      - name: SonarQube analysis
+        id: sonar
+        continue-on-error: true
+        # Pinned to v8.2.1 rather than the mutable @master ref — this action
+        # runs with SONAR_TOKEN and the PR workspace mounted.
+        uses: sonarsource/sonarqube-scan-action@22918119ff8e1ca75a623e15c8296b6ea4fbe28f # v8.2.1
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+          SONAR_SCANNER_OPTS: >
+            -Dsonar.pullrequest.key=${{ github.event.pull_request.number }}
+            -Dsonar.pullrequest.branch=${{ github.head_ref }}
+            -Dsonar.pullrequest.base=${{ github.event.pull_request.base.ref }}
+
+      # continue-on-error makes the job conclusion "success" regardless, which
+      # would hide auth, host, scanner and configuration failures. Surface the
+      # real outcome as an annotation without blocking the PR.
+      # Caveat: this only catches scanner-side failures. A server-side rejection
+      # (e.g. LICENSING_LOC) still exits 0 — verify via the SonarQube task API:
+      # /api/ce/component?component=<projectKey>
+      - name: Flag SonarQube analysis failure
+        if: steps.sonar.outcome != 'success'
+        run: |
+          echo "::warning title=SonarQube analysis did not complete::Step outcome was '${{ steps.sonar.outcome }}'. Quality data for this PR may be missing — see the SonarQube analysis step log."
+
+      # ESLint is already run as a dedicated step above. The real library build
+      # is `build` (rollup -> lib/, then a post-build script) — not
+      # `build-react-app`, which is a vestigial CRA-scaffold script.
+      - name: Production build
+        run: DISABLE_ESLINT_PLUGIN=true npm run build