@designcrowd/fe-shared-lib 1.5.20-ast-icons-1 → 1.5.20-dts-upgrades

package/.claude/settings.local.json

@@ -0,0 +1,33 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm outdated:*)",
+      "Bash(npm install:*)",
+      "Bash(npx npm-check-updates)",
+      "Bash(npm audit:*)",
+      "Skill(superpowers:writing-plans)",
+      "Bash(cat:*)",
+      "Bash(mkdir:*)",
+      "Skill(superpowers:subagent-driven-development)",
+      "Bash(echo:*)",
+      "Bash(ping:*)",
+      "Bash(docker system:*)",
+      "Bash(docker buildx du:*)",
+      "Bash(npm view:*)",
+      "Bash(~/.npmrc)",
+      "Bash(npm run bundle-translation:*)",
+      "mcp__plugin_context7_context7__resolve-library-id",
+      "Bash(node:*)",
+      "Bash(npm:*)",
+      "Bash(find:*)",
+      "Bash(git -C /home/zknowles/repos/fe-shared-lib log --oneline --all)",
+      "Bash(wc:*)",
+      "mcp__plugin_context7_context7__query-docs",
+      "Skill(superpowers:test-driven-development)",
+      "Bash(git rev-parse:*)",
+      "Bash(npx tsc:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)"
+    ]
+  }
+}

package/.npm-publish-token

@@ -0,0 +1 @@
+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

package/MODERNIZATION_ROADMAP.md

@@ -0,0 +1,264 @@
+# fe-shared-lib Modernization Roadmap
+
+> Generated: January 2026
+
+## Current State Overview
+
+| Area | Status | Health Score |
+|------|--------|--------------|
+| **Dependencies** | 27 security vulnerabilities (10 moderate, 17 high) | 4/10 |
+| **Vue Architecture** | Vue 3 but 82% Options API, mixins | 6/10 |
+| **Build Tooling** | Vite 6 + legacy Vue CLI remnants | 6/10 |
+| **Testing** | Zero automated tests | 1/10 |
+| **TypeScript** | 1.3% coverage, no tsconfig.json | 2/10 |
+| **Storybook** | v9 (modern) but mixed CSF2/CSF3 formats | 7/10 |
+
+---
+
+## Critical Security Issues (Immediate Action)
+
+1. **axios 1.6.7** → 1.13.2+ (SSRF & DoS vulnerabilities)
+2. **Storybook 9.0.4** → 9.1.17+ (environment variable exposure)
+3. **Vite 6.3.5** → 6.4.1+ (file serving vulnerabilities)
+4. **PostCSS 8.4.33** → 8.5.6+ (parsing fix)
+
+---
+
+## Key Modernization Areas
+
+### 1. Vue Component Architecture
+
+- 510 Vue files total
+- 93 components use Options API (legacy pattern)
+- Only 5 components use modern `<script setup>`
+- 5 mixins need conversion to composables
+
+**Mixins to Convert:**
+- `ButtonVariant.mixin.vue`
+- `Checkbox.mixin.js`
+- `FormControl.mixin.js`
+- `CollapsiblePanel.mixin.js`
+- `PaymentConfig.mixin.js`
+
+### 2. Build System Debt
+
+**Unused Dependencies to Remove:**
+- `@vue/cli-service` (5.0.8)
+- `@vue/cli-plugin-eslint` (5.0.8)
+- `ts-loader` (9.5.1)
+- `css-loader` (6.10.0)
+- `vue-style-loader` (4.1.3)
+- `postcss-loader` (8.1.0)
+
+**Custom Scripts Adding Maintenance Burden:**
+- `tailwind.build.js` - CSS compilation with require cache workaround
+- `tailwind.themes.js` - Storybook theme link injection
+
+### 3. TypeScript Gaps
+
+- No `tsconfig.json` exists
+- Only 6 `.ts` files in entire src/ directory (398 lines)
+- Zero type declarations for 77 exported components
+- ESLint configured for TypeScript but not enforced
+
+**Files with TypeScript:**
+- `src/atoms/components/SparkleIcon/sparkle-paths.ts`
+- `src/atoms/components/SparkleIcon/sparkle-with-spinner-paths.ts`
+- `src/atoms/components/SparkleIcon/index.ts`
+- `src/atoms/constants/constants.ts`
+- `src/experiences/models/websiteContextualModel.ts`
+- `src/atoms/components/PromoCard/PromoCard.stories.ts`
+
+### 4. Testing Infrastructure
+
+- Zero unit/integration/E2E tests
+- 74 main components without test coverage
+- `@vue/test-utils` installed but never used
+- Relies entirely on manual Storybook visual testing (45 story files)
+
+**High-Value Test Targets:**
+- `/src/experiences/helpers/email-validator.js`
+- `/src/experiences/helpers/hex-diff.js`
+- `/src/experiences/helpers/tracking.js`
+- API clients in `/src/experiences/clients/`
+
+### 5. Storybook Modernization
+
+- 57 stories use deprecated `.story` property syntax
+- 22 stories still use legacy CSF2 function format
+- No MDX documentation files
+- `autodocs: true` enabled but underutilized
+
+---
+
+## Proposed Modernization Roadmap
+
+### Phase 0: Security Fixes (Immediate)
+
+**Goal:** Patch critical vulnerabilities and remove dead code
+
+- [ ] Update axios to 1.13.2+
+- [ ] Update Storybook ecosystem to 9.1.17+
+- [ ] Update Vite to 6.4.1+
+- [ ] Update PostCSS to 8.5.6+
+- [ ] Remove unused Vue CLI dependencies
+- [ ] Remove unused Webpack loaders
+
+**Estimated Effort:** 1-2 days
+
+### Phase 1: Foundation
+
+**Goal:** Establish infrastructure for modern development
+
+- [ ] Create `tsconfig.json` with strict mode
+- [ ] Set up Vitest testing framework
+- [ ] Add test script to package.json and CI pipeline
+- [ ] Convert 5 mixins → composables
+- [ ] Standardize all Storybook stories to CSF3 format
+
+**Migration Commands:**
+```bash
+# Storybook CSF2 to CSF3 migration
+npx storybook@latest migrate csf-2-to-3 --glob="**/*.stories.js"
+```
+
+**Estimated Effort:** 1-2 weeks
+
+### Phase 2: TypeScript Adoption
+
+**Goal:** Improve type safety incrementally
+
+- [ ] Convert API clients to TypeScript
+- [ ] Convert helper functions to TypeScript
+- [ ] Convert constants files to TypeScript
+- [ ] Add type definitions for exported components
+- [ ] Enable strict TypeScript linting rules
+- [ ] Add `lang="ts"` to high-value Vue components
+
+**Priority Files:**
+1. `/src/experiences/clients/brand-crowd-api.client.js`
+2. `/src/experiences/clients/brand-page-api.client.js`
+3. `/src/experiences/helpers/*.js`
+4. `/src/experiences/constants/*.js`
+
+**Estimated Effort:** 2-3 weeks
+
+### Phase 3: Vue Modernization
+
+**Goal:** Migrate to modern Vue 3 patterns
+
+- [ ] Migrate Options API → Composition API (atoms first)
+- [ ] Add `<script setup>` to components
+- [ ] Add explicit `emits` declarations to all components
+- [ ] Replace `this.$refs` with `ref()` pattern
+- [ ] Standardize event naming conventions
+
+**Migration Order:**
+1. Simple atoms (Button, Icon, Badge)
+2. Form components (Input, Checkbox, Select)
+3. Complex atoms (Modal, Dropdown, Carousel)
+4. Experience components
+
+**Estimated Effort:** 4-6 weeks
+
+### Phase 4: Testing Coverage
+
+**Goal:** Establish comprehensive test coverage
+
+- [ ] Unit tests for utilities and helpers
+- [ ] Component tests for atoms
+- [ ] Integration tests for experiences
+- [ ] Add coverage thresholds (target 70%+)
+- [ ] Integrate tests into CI/CD pipeline
+- [ ] Add Storybook interaction testing
+
+**Recommended Testing Stack:**
+```
+Framework: Vitest
+DOM: Happy DOM
+Vue Testing: @vue/test-utils
+Coverage: Vitest coverage (c8)
+```
+
+**Estimated Effort:** 3-4 weeks
+
+### Phase 5: Build Tool Updates
+
+**Goal:** Modernize build pipeline
+
+- [ ] Tailwind CSS v3 → v4 migration
+- [ ] ESLint 8 → 9 (flat config)
+- [ ] Consolidate CSS build into Vite pipeline
+- [ ] Remove custom build scripts
+- [ ] Update remaining dependencies
+
+**Migration Commands:**
+```bash
+# Tailwind CSS v3 to v4 migration
+npx @tailwindcss/upgrade
+```
+
+**Estimated Effort:** 2-3 weeks
+
+---
+
+## Migration Tooling Available
+
+| Tool | Purpose | Command |
+|------|---------|---------|
+| Tailwind Upgrade | v3 → v4 automated migration | `npx @tailwindcss/upgrade` |
+| Storybook CSF | CSF2 → CSF3 story format | `npx storybook@latest migrate csf-2-to-3` |
+| Storybook MDX | MDX to CSF conversion | `npx storybook@latest migrate mdx-to-csf` |
+
+---
+
+## Dependency Version Targets
+
+### Core Framework
+| Package | Current | Target |
+|---------|---------|--------|
+| vue | 3.5.15 | 3.5.26 |
+| vue-router | 4.5.0 | 4.6.4 |
+| typescript | 5.3.3 | 5.9.x |
+
+### Build Tools
+| Package | Current | Target |
+|---------|---------|--------|
+| vite | 6.3.5 | 6.4.1+ |
+| tailwindcss | 3.4.1 | 4.x |
+| postcss | 8.4.33 | 8.5.6+ |
+| @vitejs/plugin-vue | 5.2.4 | 6.x |
+
+### Storybook
+| Package | Current | Target |
+|---------|---------|--------|
+| storybook | 9.0.4 | 9.1.17+ |
+| All @storybook/* addons | 9.0.4 | 9.1.17+ |
+
+### Code Quality
+| Package | Current | Target |
+|---------|---------|--------|
+| eslint | 8.56.0 | 9.x |
+| eslint-plugin-vue | 9.21.1 | 10.x |
+| stylelint | 16.2.1 | 17.x |
+
+---
+
+## Project Statistics
+
+- **Total Vue Components:** 510
+- **Atoms:** 466 components
+- **Experiences:** 43 components
+- **Icons:** ~100+ icon components
+- **Storybook Stories:** 45 files
+- **Total Source Lines:** 31,226
+
+---
+
+## Reference Links
+
+- [Vue 3 Composition API Migration](https://vuejs.org/guide/extras/composition-api-faq.html)
+- [Vue Composables Guide](https://vuejs.org/guide/reusability/composables.html)
+- [Tailwind CSS v4 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide)
+- [Storybook Migration Guide](https://storybook.js.org/docs/migration-guide)
+- [Vitest Documentation](https://vitest.dev/)

package/docs/plans/2026-01-19-typescript-declarations-design.md

@@ -0,0 +1,114 @@
+# fe-shared-lib TypeScript Declarations Design
+
+## Overview & Goals
+
+**Objective**: Add TypeScript declaration file to `@designcrowd/fe-shared-lib` so consumers get basic type checking and IDE autocomplete without converting the library to TypeScript.
+
+**Success Criteria**:
+- BrandCrowd.Nuxt's 117 `TS7016` errors for `@designcrowd/fe-shared-lib` resolve
+- Commonly-used components (Button, Modal, Icon, etc.) have typed props
+- Less-used components have minimal stub declarations
+- No changes to existing JavaScript/Vue component code
+
+**Approach**:
+1. Create `index.d.ts` at package root declaring all exports from `index.js`
+2. Add `"types": "./index.d.ts"` to `package.json` exports
+3. Define detailed prop interfaces for ~10 most-used components
+4. Use generic `DefineComponent<{}, {}, any>` for remaining components
+5. Publish new version for BrandCrowd.Nuxt to consume
+
+**Files to Create/Modify**:
+- `index.d.ts` (new) - Main declaration file
+- `package.json` - Add types field to exports
+
+## Implementation Details
+
+**Structure of `index.d.ts`**:
+
+```typescript
+import { DefineComponent, PropType } from 'vue';
+
+// ============ Detailed Component Types ============
+// Most-used components with full prop definitions
+
+export interface ButtonProps {
+  label?: string;
+  variant?: 'primary' | 'secondary' | 'success' | 'danger' | 'link';
+  size?: 'sm' | 'md' | 'lg';
+  disabled?: boolean;
+  isBusy?: boolean;
+  fullWidth?: boolean;
+  icon?: string;
+  // ... other props from examining Button.vue
+}
+
+export const Button: DefineComponent<ButtonProps>;
+export const Modal: DefineComponent<ModalProps>;
+export const Icon: DefineComponent<IconProps>;
+// ... ~10 detailed components
+
+// ============ Stub Component Types ============
+// Less-used components - typed but generic
+
+export const UploadYourLogoDropzone: DefineComponent<{}, {}, any>;
+export const SignUpModal: DefineComponent<{}, {}, any>;
+// ... remaining ~45 components
+
+// ============ Utilities ============
+export function setSharedLibLocaleAsync(locale: string): Promise<void>;
+export function tr(key: string, params?: Record<string, any>): string;
+
+// ============ API Clients ============
+export const brandPageApiClient: any;
+export const brandCrowdApiClient: any;
+```
+
+**Components to fully type** (based on usage frequency):
+1. Button
+2. Modal
+3. Icon
+4. Dropdown
+5. TextInput
+6. Textarea
+7. Checkbox
+8. Toggle
+9. Loader
+10. Select
+
+## Verification & Publishing
+
+**Local Testing** (before publishing):
+1. Create `index.d.ts` in fe-shared-lib
+2. In BrandCrowd.Nuxt, run `npm link ../fe-shared-lib`
+3. Run `npx vue-tsc --noEmit` - verify TS7016 errors for fe-shared-lib resolve
+4. Check IDE autocomplete works for Button props in a .vue file
+
+**Publishing Workflow**:
+1. Bump version in `package.json` (e.g., `1.5.20` → `1.5.21`)
+2. Commit with message: `Add TypeScript declarations for consumers`
+3. Build and publish: `npm publish` (or via CI pipeline)
+4. In BrandCrowd.Nuxt: `npm update @designcrowd/fe-shared-lib`
+
+**Iterative Improvement**:
+After initial release, prop types can be refined by:
+- Examining actual component `.vue` files for accurate prop definitions
+- Adding missing props as consumers report them
+- Eventually generating declarations from JSDoc or migrating to TypeScript
+
+**Rollback Plan**:
+If declarations cause issues, consumers can add to their own `types/vendor-modules.d.ts`:
+```typescript
+declare module '@designcrowd/fe-shared-lib';
+```
+This overrides the package's declarations with a permissive stub.
+
+## Checklist
+
+- [ ] Create `index.d.ts` with all exports from `index.js`
+- [ ] Add detailed prop interfaces for 10 most-used components
+- [ ] Add stub declarations for remaining components
+- [ ] Add types for utility functions (setSharedLibLocaleAsync, tr)
+- [ ] Update `package.json` with types field in exports
+- [ ] Test locally with `npm link` in BrandCrowd.Nuxt
+- [ ] Verify TS7016 errors resolve
+- [ ] Bump version and publish