freemium-ui 2.0.132 → 2.0.134

package/.github/workflows/pr-template-validation.yml

@@ -0,0 +1,367 @@
+name: PR Template Validation
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+
+permissions:
+  pull-requests: write
+  issues: write
+  contents: read
+
+jobs:
+  validate-template:
+    runs-on: ['self-hosted', 'Linux']
+    name: Validate PR Template Sections
+
+    steps:
+      - name: Check if PR is from a bot
+        id: bot-check
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const author = pr.user.login;
+            const authorType = pr.user.type;
+
+            console.log('=== Bot Detection ===');
+            console.log(`PR Author: ${author}`);
+            console.log(`Author Type: ${authorType}`);
+
+            const botUsers = [
+              'dependabot[bot]',
+              'dependabot-preview[bot]',
+              'renovate[bot]',
+              'github-actions[bot]',
+              'mergify[bot]',
+              'snyk-bot'
+            ];
+
+            const isBot =
+              botUsers.includes(author) ||
+              author.endsWith('[bot]') ||
+              authorType === 'Bot';
+
+            const isDependencyPR =
+              pr.title.toLowerCase().includes('bump') ||
+              pr.title.toLowerCase().includes('update dependencies') ||
+              pr.title.toLowerCase().includes('chore(deps)');
+
+            const shouldSkip = isBot || isDependencyPR;
+
+            console.log(`Is Bot: ${isBot}`);
+            console.log(`Is Dependency PR: ${isDependencyPR}`);
+            console.log(`Should Skip Validation: ${shouldSkip}`);
+
+            if (shouldSkip) {
+              console.log('⏭️ Skipping PR template validation for automated PR');
+
+              const botSkipMarker = '<!-- pr-bot-skip-marker -->';
+              const comments = await github.paginate(github.rest.issues.listComments, {
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                per_page: 100
+              });
+
+              const existingComment = comments.find(c => c.body.includes(botSkipMarker));
+              if (!existingComment) {
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: context.issue.number,
+                  body: `${botSkipMarker}\n🤖 **Automated PR Detected** - Skipping PR template validation.\n\nThis PR appears to be from a bot or automated process. Template validation is not required.`
+                });
+                console.log('Created bot skip comment');
+              } else {
+                console.log('Bot skip comment already exists, skipping duplicate');
+              }
+            }
+
+            return shouldSkip;
+
+      - name: Validate PR Template Completion
+        if: steps.bot-check.outputs.result != 'true'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.RUNWAYCI_GITHUB_PAT_TOKEN }}
+          script: |
+            const prBody = context.payload.pull_request.body || '';
+            const prTitle = context.payload.pull_request.title || '';
+            const errors = [];
+            const warnings = [];
+
+            console.log('=== Starting PR Template Validation ===');
+            console.log(`PR #${context.issue.number}: ${prTitle}`);
+
+            // 0. Validate PR Title (must match commit message format)
+            console.log('Checking PR Title format...');
+            const validTypes = ['feat', 'fix', 'chore', 'docs', 'refactor', 'test', 'perf', 'ci', 'build', 'style', 'revert'];
+            const titleRegex = /^(feat|fix|chore|docs|refactor|test|perf|ci|build|style|revert):\s*\[(MP-\d+|FS-\d+|FSURVEY-\d+|DEVREL-\d+|PLAT-\d+|MISC|Docs)\]\s+\S.*$/;
+            const hasTitleFormat = titleRegex.test(prTitle);
+
+            if (!hasTitleFormat) {
+              errors.push(`**PR Title**: Invalid format. Required format: \`type: [TICKET-ID] description\`
+
+              **Valid types**: ${validTypes.join(', ')}
+              **Valid tickets**: MP-xxxx, FS-xxxx, FSURVEY-xxxx, DEVREL-xxxx, PLAT-xxxx, MISC, Docs
+
+              **Examples**:
+              - ✅ \`feat: [MP-12345] Add new Dropdown variant\`
+              - ✅ \`feat: [FS-1000] Add Tooltip component\`
+              - ✅ \`feat: [FSURVEY-2024] Add survey builder enhancement\`
+              - ✅ \`fix: [MISC] Fix Modal focus trap\`
+              - ✅ \`chore: [DEVREL-4720] Update dependencies\`
+              - ❌ \`Add Dropdown variant\` (missing type and ticket)
+              - ❌ \`[MP-12345] Add feature\` (missing type prefix)
+
+              **Your title**: \`${prTitle}\``);
+            } else {
+              const titleMatch = prTitle.match(titleRegex);
+              console.log(`✓ PR Title format valid: ${titleMatch[1]} - ${titleMatch[2]}`);
+            }
+
+            // 1. Validate Type of Change (at least one checkbox selected)
+            console.log('Checking Type of Change...');
+            const typeRegex = /## Type of Change[\s\S]*?(?=##|$)/;
+            const typeSection = prBody.match(typeRegex)?.[0] || '';
+            const hasTypeSelected = /- \[x\]/i.test(typeSection);
+
+            if (!hasTypeSelected) {
+              errors.push('**Type of Change**: No type selected. Please check at least one box (Feature, Bugfix, Refactor, etc.).');
+            } else {
+              console.log('✓ Type of Change selected');
+            }
+
+            // 2. Validate Ticket Reference (must have valid ticket ID)
+            console.log('Checking Ticket Reference...');
+            const ticketRegex = /-\s*\*\*Ticket ID\*\*:\s*\[(MP-\d+|FS-\d+|FSURVEY-\d+|DEVREL-\d+|PLAT-\d+|MISC|Docs)\]/;
+            const hasTicketId = ticketRegex.test(prBody);
+
+            if (!hasTicketId) {
+              errors.push('**Ticket Reference**: Missing or invalid ticket ID. Required format: `[MP-xxxx]`, `[FS-xxxx]`, `[FSURVEY-xxxx]`, `[DEVREL-xxxx]`, `[PLAT-xxxx]`, `[MISC]`, or `[Docs]`');
+            } else {
+              const ticketMatch = prBody.match(ticketRegex);
+              console.log(`✓ Ticket ID found: ${ticketMatch[1]}`);
+            }
+
+            // 3. Validate Changes Made (minimum 3 bullet points with content)
+            console.log('Checking Changes Made...');
+            const changesRegex = /## Changes Made[\s\S]*?(?=##|$)/;
+            const changesSection = prBody.match(changesRegex)?.[0] || '';
+            const changesBullets = (changesSection.match(/^-\s+.+$/gm) || [])
+              .map(line => line.replace(/^-\s+/, '').trim())
+              .filter(content =>
+                content.length > 0 &&
+                !/^Change\s+\d+:?\s*$/i.test(content)
+              );
+
+            if (changesBullets.length < 3) {
+              errors.push(`**Changes Made**: Insufficient items listed (found ${changesBullets.length}). Please provide at least 3 bullet points describing your changes.`);
+            } else {
+              console.log(`✓ Changes Made: ${changesBullets.length} item(s) listed (minimum 3 met)`);
+            }
+
+            // 4. Validate Affected Areas (at least one checkbox selected)
+            console.log('Checking Affected Areas...');
+            const affectedRegex = /## Affected Areas[\s\S]*?(?=##|$)/;
+            const affectedSection = prBody.match(affectedRegex)?.[0] || '';
+            const hasAreaSelected = /- \[x\]/i.test(affectedSection);
+
+            if (!hasAreaSelected) {
+              errors.push('**Affected Areas**: No area selected. Please check at least one affected area (Components, Styles/Themes, Stories, etc.).');
+            } else {
+              console.log('✓ Affected Areas selected');
+            }
+
+            // 5. Validate Breaking Changes (must select exactly one option)
+            console.log('Checking Breaking Changes...');
+            const breakingRegex = /## Breaking Changes[\s\S]*?(?=##|$)/;
+            const breakingSection = prBody.match(breakingRegex)?.[0] || '';
+            const breakingSelections = breakingSection.match(
+              /^- \[[xX]\]\s+(Yes,?\s+this PR introduces breaking changes|No breaking changes.*)$/gim
+            ) || [];
+            const hasBreakingSelection = breakingSelections.length === 1;
+
+            if (!hasBreakingSelection) {
+              errors.push('**Breaking Changes**: Select exactly one option (Yes or No).');
+            } else {
+              console.log('✓ Breaking Changes option selected');
+            }
+
+            // 6. If breaking changes = yes, require description
+            const hasBreakingYes = /^-\s*\[[xX]\]\s+Yes,?\s+this PR introduces breaking changes/im.test(breakingSection);
+            if (hasBreakingYes) {
+              console.log('Breaking changes detected, checking for description...');
+              const descriptionPart = breakingSection
+                .replace(/^## Breaking Changes.*$/m, '')
+                .replace(/^- \[[ xX]\]\s+Yes,?\s+this PR introduces breaking changes.*$/m, '')
+                .replace(/^- \[[ xX]\]\s+No breaking changes.*$/m, '')
+                .replace(/<!---[\s\S]*?-->/g, '')
+                .trim();
+              const hasDescription = descriptionPart.length > 50;
+
+              if (!hasDescription) {
+                errors.push('**Breaking Changes**: You selected "Yes" but did not describe the breaking changes. Please provide details and migration steps.');
+              } else {
+                console.log('✓ Breaking changes description provided');
+              }
+            }
+
+            // 7. Validate Testing section (test steps required)
+            console.log('Checking Testing section...');
+            const testingRegex = /## How Has This Been Tested\?[\s\S]*?(?=##|$)/;
+            const testingSection = prBody.match(testingRegex)?.[0] || '';
+            const testStepsContent = testingSection
+              .replace(/\*\*Test Steps:\*\*/g, '')
+              .replace(/<!---[\s\S]*?-->/g, '')
+              .trim();
+            const numberedSteps = testStepsContent.match(/^\d+\.\s+.+$/gm) || [];
+            const hasTestSteps = numberedSteps.some(
+              step => !/^\d+\.\s+Step\s+\d+\s*$/i.test(step.trim())
+            );
+
+            if (!hasTestSteps) {
+              warnings.push('**Testing**: Test steps are missing or contain only placeholders. Please describe how you tested your changes (steps 1, 2, 3...).');
+            } else {
+              console.log('✓ Test steps provided');
+            }
+
+            // 8. Validate SDET Guidance (must be filled)
+            console.log('Checking SDET Guidance...');
+            const sdetRegex = /## What should the SDET know\?[\s\S]*?(?=##|$)/;
+            const sdetSection = prBody.match(sdetRegex)?.[0] || '';
+            const sdetContent = sdetSection
+              .split('## What should the SDET know?')[1] || '';
+            const sdetCleanContent = sdetContent
+              .replace(/<!---[\s\S]*?-->/g, '')
+              .replace(/^-\s+Test\s+scenario\s+\d+:?\s*$/gim, '')
+              .replace(/^-\s+Edge\s+case(\s+to\s+check)?:?\s*$/gim, '')
+              .replace(/^-\s+Focus\s+area:?\s*$/gim, '')
+              .trim();
+            const hasSdetGuidance = sdetCleanContent.length > 30;
+
+            if (!hasSdetGuidance) {
+              warnings.push('**SDET Guidance**: Please provide testing guidance for the QA team (test scenarios, edge cases, focus areas).');
+            } else {
+              console.log('✓ SDET guidance provided');
+            }
+
+            // 9. Check Screenshots for UI changes
+            console.log('Checking for UI changes...');
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.issue.number,
+              per_page: 100
+            });
+
+            const uiFiles = files.filter(file =>
+              file.filename.endsWith('.tsx') &&
+              (
+                file.filename.startsWith('src/components/') ||
+                file.filename.startsWith('src/stories/')
+              )
+            );
+
+            if (uiFiles.length > 0) {
+              console.log(`UI changes detected in ${uiFiles.length} files`);
+              const screenshotsRegex = /## Screenshots\/Videos[\s\S]*?(?=##|$)/;
+              const screenshotsSection = prBody.match(screenshotsRegex)?.[0] || '';
+              const hasScreenshots = /!\[.*?\]\(.*?\)|https?:\/\/\S+\.(png|jpg|jpeg|gif|mp4|webm|mov)(?:\?\S+)?|https?:\/\/github\.com\/user-attachments\/assets\/[^\s)]+/i.test(screenshotsSection);
+
+              if (!hasScreenshots) {
+                warnings.push(`**Screenshots/Videos**: UI changes detected in ${uiFiles.length} file(s) but no screenshots provided. Please consider adding before/after screenshots or a Storybook link.`);
+              } else {
+                console.log('✓ Screenshots provided for UI changes');
+              }
+            } else {
+              console.log('No UI changes detected');
+            }
+
+            // Generate validation report
+            console.log(`\nValidation Results: ${errors.length} errors, ${warnings.length} warnings`);
+
+            const docsRef = context.payload.pull_request.head.sha;
+            const repoUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}`;
+            const guideUrl = `${repoUrl}/blob/${docsRef}/.github/pr_validation_guide.md`;
+            const templateUrl = `${repoUrl}/blob/${docsRef}/.github/pull_request_template.md`;
+
+            const reportMarker = '<!-- pr-template-validation-report -->';
+            let comment = `${reportMarker}\n## 🔍 PR Template Validation Report\n\n`;
+
+            if (errors.length > 0) {
+              comment += '### ❌ Required Sections Missing\n\n';
+              comment += 'The following **required sections** must be completed:\n\n';
+              comment += errors.map(e => `- ${e}`).join('\n');
+              comment += '\n\n**⚠️ Action Required**: Please edit your PR description to include all required information.\n\n';
+              comment += `📖 **Verify against the rules:** [PR Validation Guide](${guideUrl})\n\n`;
+              comment += '---\n\n';
+            }
+
+            if (warnings.length > 0) {
+              comment += '### ⚠️ Recommended Improvements\n\n';
+              comment += 'Please consider adding:\n\n';
+              comment += warnings.map(w => `- ${w}`).join('\n');
+              comment += '\n\n---\n\n';
+            }
+
+            if (errors.length === 0 && warnings.length === 0) {
+              comment = `${reportMarker}\n## ✅ PR Template Complete\n\n`;
+              comment += 'All required sections are properly filled. Great job! 🎉\n';
+            }
+
+            // Add helpful footer
+            comment += '\n---\n\n';
+            comment += '<details>\n';
+            comment += '<summary>📋 PR Template Requirements</summary>\n\n';
+            comment += '**Required Sections:**\n';
+            comment += '- Type of Change (select at least one)\n';
+            comment += '- Ticket Reference (valid ticket ID)\n';
+            comment += '- Changes Made (minimum 3 items)\n';
+            comment += '- Affected Areas (select at least one)\n';
+            comment += '- Breaking Changes (select Yes/No)\n\n';
+            comment += '**Recommended Sections:**\n';
+            comment += '- Testing (test steps)\n';
+            comment += '- SDET Guidance (QA testing guidance)\n';
+            comment += '- Screenshots (if UI changes)\n\n';
+            comment += `📖 [PR Validation Guide](${guideUrl}) — full rules, examples, and troubleshooting\n`;
+            comment += `📝 [Pull Request Template](${templateUrl}) — the template structure\n`;
+            comment += '</details>\n';
+
+            // Post or update comment
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              per_page: 100
+            });
+
+            const botComment = comments.find(c =>
+              c.body.includes(reportMarker)
+            );
+
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: comment
+              });
+              console.log('Updated existing validation comment');
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: comment
+              });
+              console.log('Created new validation comment');
+            }
+
+            // Fail the check if there are errors (blocks merge with branch protection)
+            if (errors.length > 0) {
+              core.setFailed(`PR template validation failed: ${errors.length} required section(s) missing or incomplete`);
+            } else {
+              console.log('✅ PR template validation passed!');
+            }

package/.github/workflows/sonarqube-main.yml

@@ -0,0 +1,106 @@
+name: SonarQube Main Branch
+
+# Analyses the main branch after every merge, per the Platforms CX guidance
+# (https://confluence.freshworks.com/spaces/SHAR/pages/525401715/Sonarqube+integration+Frontend).
+#
+# This is what produces the overall project dashboard: total bugs, code smells,
+# vulnerabilities, security hotspots, duplication and coverage across the whole
+# codebase. Pull request analyses only report on changed code and never populate
+# a branch, so without this workflow the project's main branch stays empty.
+#
+# It also gives the New Code baseline that PR analyses diff against.
+
+on:
+  push:
+    branches:
+      - main
+  # Allows a one-off baseline run without waiting for a merge.
+  workflow_dispatch:
+
+concurrency:
+  group: sonarqube-main-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  analysis:
+    name: Analyse main branch
+    runs-on: fw-shared
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # SonarQube needs full history for blame attribution and new-code detection.
+          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: same GH_AUTH_TOKEN-in-.npmrc exposure as the PR
+      # workflow, even though this one only ever runs already-merged main
+      # code. No dependency's install script is needed to build or test 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: Test coverage
+        timeout-minutes: 15
+        env:
+          CI: true
+        run: npm run test:coverage
+
+      # Reads sonar-project.properties for scope and exclusions. No pull request
+      # parameters here — that is what makes this a branch analysis rather than a
+      # PR analysis, and therefore what populates the project dashboard.
+      #
+      # continue-on-error: the SonarQube instance is at its server-wide LOC
+      # licence limit, and branch analyses of net-new code are rejected with
+      # errorType LICENSING_LOC. Remove this once the limit is raised.
+      - 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 workspace mounted.
+        uses: sonarsource/sonarqube-scan-action@22918119ff8e1ca75a623e15c8296b6ea4fbe28f # v8.2.1
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+
+      # continue-on-error makes the job conclusion "success" regardless, which
+      # would hide auth, host, scanner and configuration failures.
+      # 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 main-branch analysis did not complete::Step outcome was '${{ steps.sonar.outcome }}'. The project dashboard may be stale — see the SonarQube analysis step log."

package/.github/workflows/stale.yml

@@ -0,0 +1,112 @@
+name: Stale PR Management
+
+on:
+  schedule:
+    - cron: '0 0 * * *' # Run daily at midnight UTC
+
+  workflow_dispatch: # Allow manual trigger
+
+permissions:
+  pull-requests: write
+  issues: write
+
+jobs:
+  stale:
+    runs-on: ['self-hosted', 'Linux']
+    name: Mark and Close Stale PRs
+
+    steps:
+      - uses: actions/stale@5bef64f19d7facfb25b37b414482c7164d639639 # v9
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+          # PR Configuration
+          days-before-stale: 2
+          days-before-close: 2
+
+          # Do not handle issues
+          days-before-issue-stale: -1
+          days-before-issue-close: -1
+
+          # Stale PR message (warning)
+          stale-pr-message: |
+            ## ⏰ Stale PR Warning
+
+            This pull request has been **inactive for 2 days** with no commits, comments, or reviews.
+
+            ### What happens next?
+
+            - This PR will be automatically closed in **2 days** if no activity occurs
+            - To prevent closure, you can:
+              - Push new commits
+              - Add a comment with updates or status
+              - Remove the `stale` label
+              - Request review from team members
+
+            ### Why does this matter?
+
+            - Keeps our PR list clean and manageable
+            - Helps identify abandoned or forgotten work
+            - Encourages timely reviews and merges
+
+            ### Need more time?
+
+            Simply comment on this PR to remove the stale label, or:
+            - Add `work-in-progress` label if still developing
+            - Add `blocked` label if waiting on external dependencies
+            - Add `on-hold` label if intentionally paused
+
+            ---
+
+            💡 **Tip:** Keep your PRs active by:
+            - Requesting reviews when ready
+            - Responding to feedback promptly
+            - Rebasing on latest main/dev branch
+            - Adding status updates if blocked
+
+          # Close message (final notice)
+          close-pr-message: |
+            ## 🔒 PR Automatically Closed
+
+            This pull request has been closed due to **4 days of inactivity** (2 days stale + 2 days grace period).
+
+            ### What you can do:
+
+            ✅ **Reopen this PR** if you want to continue working on it
+            ✅ **Create a new PR** with updated changes
+            ✅ **Link related issues** to track the work
+
+            ### Why was this closed?
+
+            - Helps maintain a clean, manageable PR list
+            - Prevents outdated PRs from accumulating
+            - Encourages active development workflow
+
+            ### Need help?
+
+            If this PR was closed in error or you need assistance:
+            - Comment mentioning a team member
+            - Reopen and add context about delays
+            - Reach out on team channels
+
+            ---
+
+          # Label configuration
+          stale-pr-label: 'stale'
+          exempt-pr-labels: 'work-in-progress,blocked,on-hold,keep-open,dependencies'
+          exempt-draft-pr: true
+
+          # Activity that removes stale label
+          remove-stale-when-updated: true
+
+          # Operations limit (prevent API rate limiting)
+          operations-per-run: 100
+
+          # Sort order (process oldest first)
+          ascending: true
+
+          # Delete branch on close (optional - uncomment if desired)
+          # delete-branch: true
+
+          # Additional configuration
+          enable-statistics: true

package/.nvmrc

@@ -0,0 +1 @@
+18

package/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.

package/catalog-info.yaml

@@ -0,0 +1,33 @@
+# Prism (Backstage) software catalog descriptor.
+# Registers this repo as the shared UI component library of the SurveyServ
+# system. The `platforms/surveyserv` System entity itself is declared in the
+# freshdesk/surveyserv repo (see PR #5448) — not redeclared here to avoid a
+# duplicate-entity conflict in the catalog.
+# Schema: `get_catalog_schema` in the Prism MCP server is the source of truth.
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: freemium-ui
+  namespace: platforms
+  title: Freemium UI
+  description: >-
+    Lightweight, Styled-Components-based React UI component library shared
+    across SurveyServ/Freemium frontends. Published as an npm package.
+  annotations:
+    github.com/project-slug: freshdesk/freemium-ui
+    backstage.io/techdocs-ref: dir:./tech-docs
+  tags:
+    - react
+    - library
+    - typescript
+    - ui-components
+    - styled-components
+  labels:
+    exposure: internal
+    language: TypeScript
+    orgVersion: v1alpha1
+spec:
+  type: library
+  lifecycle: production
+  owner: platforms/plat-maise-surveyserv
+  system: platforms/surveyserv

package/docs/adrs/index.md

@@ -0,0 +1,11 @@
+# ADRs
+
+No architecture decision records exist in this repository (no `adrs/` source files documenting an actual decision, and no dedicated ADR pages found in Confluence for `freemium-ui` specifically — this page and the empty `adrs/` scaffold directory are onboarding artifacts, not ADRs themselves). The `adrs/` directory at the repo root is scaffolding for future ADR source files — currently empty.
+
+Key architectural decisions that _have_ been made but are only recorded implicitly in code/config (candidates for a retroactive ADR if the team wants one):
+
+- Externalizing only `react`/`react-dom` at build time and bundling every other dependency (`rollup.config.ts`'s `external` array) — see [Deep Dive → Dependencies & coupling](../architecture/deep-dive.md#3-dependencies--coupling).
+- Adopting Radix UI primitives + a shared shadow-DOM-aware portal pattern (`usePortalContainer`/`useShadowDomScrollFix`) for every overlay component — see [Deep Dive → Architecture & control flow](../architecture/deep-dive.md#1-architecture--control-flow).
+- Adding a third `dew`/`DewTheme` theme, driven by CSS variables from `@freshworks/dew-styles`, alongside the original `light`/`dark` themes — see the Confluence "Reskinning Project - Freshworks Dew 2.0 Design System" page and [Deep Dive → Idiomatic vernacular](../architecture/deep-dive.md#4-idiomatic-vernacular).
+
+No ADRs recorded yet.