@designcrowd/fe-shared-lib 1.5.1-icontranslation → 1.5.2

package/docs/plans/2025-11-03-typescript-declarations-design.md

@@ -1,222 +0,0 @@
-# TypeScript Declaration Files Design
-
-**Date:** 2025-11-03
-**Goal:** Add TypeScript declaration files (.d.ts) to the published npm package to support TypeScript consumers while enabling gradual migration to TypeScript.
-
-## Overview
-
-This design adds basic TypeScript support to `@designcrowd/fe-shared-lib` by auto-generating declaration files during the publish process. The approach allows:
-- Immediate TypeScript support for library consumers
-- Gradual migration from JavaScript to TypeScript over time
-- No breaking changes for existing JavaScript consumers
-- Clean git history (declarations not committed)
-
-## Architecture
-
-### Tooling Choice
-
-Use `vue-tsc` (Vue's TypeScript compiler) to generate declarations from existing `.vue` and `.js` files. This tool:
-- Understands Vue 3 component structure
-- Extracts type information from JavaScript code
-- Generates `.d.ts` files for both `.vue` and `.js` files
-- Supports gradual TypeScript adoption
-
-### File Structure
-
-Generated declarations will be placed in `dist/types/`:
-
-```
-/dist/
-  ├── types/
-  │   ├── index.d.ts              # Main entry point
-  │   ├── atoms/
-  │   │   └── components/
-  │   │       ├── Button/
-  │   │       │   └── Button.vue.d.ts
-  │   │       ├── Icon/
-  │   │       └── ...
-  │   ├── experiences/
-  │   └── useSharedLibTranslate.d.ts
-```
-
-### Package.json Configuration
-
-**New Fields:**
-- `"types": "./dist/types/index.d.ts"` - Points TypeScript to declarations
-
-**Updated Scripts:**
-- `build:types` - Generate declaration files
-- `docker:publish` - Run `build:types` before building Docker image
-
-### Type Generation Level
-
-**Basic Component Exports:** Each component is typed as a generic Vue component. TypeScript consumers get:
-- Import/export type checking
-- Basic component type (can use in templates)
-- IDE autocomplete for component names
-
-**What's NOT included (can be added later):**
-- Detailed prop types with specific values
-- Event emission types
-- Slot definitions
-- Exposed method signatures
-
-## Implementation Details
-
-### 1. TypeScript Configuration
-
-Create `tsconfig.declarations.json`:
-```json
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "declaration": true,
-    "emitDeclarationOnly": true,
-    "outDir": "./dist/types",
-    "rootDir": "./",
-    "skipLibCheck": true
-  },
-  "include": [
-    "src/**/*",
-    "index.js",
-    "*.d.ts"
-  ],
-  "exclude": [
-    "node_modules",
-    "dist",
-    ".storybook",
-    "**/*.stories.js"
-  ]
-}
-```
-
-Create base `tsconfig.json` (if doesn't exist):
-```json
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    "module": "ESNext",
-    "moduleResolution": "node",
-    "lib": ["ESNext", "DOM"],
-    "jsx": "preserve",
-    "strict": false,
-    "allowJs": true,
-    "checkJs": false,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "resolveJsonModule": true
-  }
-}
-```
-
-### 2. Package.json Updates
-
-```json
-{
-  "types": "./dist/types/index.d.ts",
-  "scripts": {
-    "build:types": "vue-tsc --project tsconfig.declarations.json",
-    "docker:publish": "npm run build:types && docker build . --build-arg NPM_TOKEN=$NPM_TOKEN"
-  }
-}
-```
-
-### 3. Dockerfile Updates
-
-Ensure `dist/types` is copied in the Dockerfile:
-```dockerfile
-COPY dist/types ./dist/types
-```
-
-### 4. Git Configuration
-
-Add to `.gitignore`:
-```
-dist/types/
-```
-
-### 5. Manual Type Definitions
-
-Create `src/useSharedLibTranslate.d.ts` for translation utilities:
-```typescript
-export function setSharedLibLocaleAsync(locale: string): Promise<void>;
-export function tr(key: string, params?: Record<string, any>): string;
-```
-
-## Gradual Migration Path
-
-### Writing New Code
-- New components: Use `<script setup lang="ts">` in `.vue` files
-- New utilities: Write as `.ts` files
-- `vue-tsc` automatically generates declarations
-
-### Converting Existing Code
-- Convert one component at a time
-- Change `<script>` to `<script setup lang="ts">`
-- Add type annotations incrementally
-- No coordination needed across components
-
-### Priority for Migration
-1. Utility functions and helpers (highest value)
-2. Complex components with many props
-3. Simple presentational components (lowest priority)
-
-## Edge Cases & Considerations
-
-### Multi-Theme Components
-Theme-specific exports (e.g., `DcomIcon`) are in `index.js`, so they'll automatically get declarations. No special handling needed.
-
-### Translation Bundles
-Translation JSON files don't need type definitions. The `tr()` function signature is sufficient.
-
-### API Clients
-Exported clients (`brandPageApiClient`, `brandCrowdApiClient`) will get basic type definitions. Can be enhanced later with Axios response types.
-
-### Storybook Files
-Excluded from type generation (`.exclude` in tsconfig). Stories are dev-only and don't need declarations.
-
-## Validation Steps
-
-Before publishing:
-1. Run `npm run build:types` locally
-2. Verify `dist/types/index.d.ts` exists
-3. Check all exports are present in `index.d.ts`
-4. Create test TypeScript project:
-   ```typescript
-   import { Button, Icon } from '@designcrowd/fe-shared-lib';
-   ```
-5. Verify IDE autocomplete works
-6. Test `npm run docker:publish` includes types
-
-## Breaking Changes
-
-**None.** This is purely additive:
-- JavaScript consumers continue working unchanged
-- TypeScript consumers gain type support
-- No runtime behavior changes
-- No API changes
-
-## Dependencies
-
-Already installed:
-- `typescript: 5.3.3` (devDependency)
-- `@vue/eslint-config-typescript: 12.0.0` (devDependency)
-
-Need to verify `vue-tsc` is available (should be included with `@vitejs/plugin-vue` or add as devDependency).
-
-## Future Enhancements
-
-Once this is working, can incrementally add:
-1. Detailed prop types with specific values (e.g., `theme: 'brandCrowd' | 'designCom'`)
-2. Event emission types (e.g., `@click`, `@change`)
-3. Slot definitions with scoped slot props
-4. Generic type parameters for complex components
-5. Full JSDoc comments for better IDE hints
-
-## Success Criteria
-
-- ✅ TypeScript consumers can import components without type errors
-- ✅ IDE provides autocomplete for component names
-- ✅ `dist/types/index.d.ts` published to npm
-- ✅ No breaking changes for JavaScript consumers
-- ✅ New TypeScript files can be added without build changes