@designcrowd/fe-shared-lib 1.5.0-jj-4 → 1.5.1-icontranslation

package/GT-8753.md

@@ -0,0 +1,127 @@
+# GT-8753: SVG Icon Translation Issue - Problem & Solution
+
+## Problem Description
+
+The `DcomIcon` component in `@designcrowd/fe-shared-lib` (v1.4.9) has hardcoded `lang="en"` attributes in its SVG `<title>` and `<desc>` accessibility elements, preventing proper internationalization.
+
+**Current Code** (`Icon.vue` lines 21-22):
+```vue
+<title :id="`${name}-${id}-title`" lang="en">{{ title }}</title>
+<desc :id="`${name}-${id}-desc`" lang="en">{{ description }}</desc>
+```
+
+**Impact**: All Design.com pages using DcomIcon display English accessibility text regardless of the user's locale (fr-FR, es-ES, pt-PT, etc.), creating a poor experience for non-English users and failing accessibility standards for internationalized content.
+
+**Affected Pages in BrandCrowd.Net**:
+- `/maker/free-logos`
+- `/business-name-generator`
+- `/maker/contact`
+- `/logo-maker`
+- Multi-Asset homemaker pages (e.g., `/facebook-covers`)
+
+**Used in 6 components** across BrandCrowd.Net's Nuxt application.
+
+---
+
+## Proposed Solution
+
+### 1. Add a `lang` Prop to DcomIcon Component
+
+**File**: `src/atoms/components/design-com/Icon/Icon.vue`
+
+Add a new optional prop to accept the language code:
+
+```vue
+<script>
+export default {
+  props: {
+    // ... existing props ...
+    lang: {
+      type: String,
+      required: false,
+      default: 'en', // fallback to English
+    },
+  },
+  // ... rest of component ...
+}
+</script>
+```
+
+### 2. Update Template to Use Dynamic Lang Attribute
+
+**Change lines 21-22** from:
+```vue
+<title :id="`${name}-${id}-title`" lang="en">{{ title }}</title>
+<desc :id="`${name}-${id}-desc`" lang="en">{{ description }}</desc>
+```
+
+To:
+```vue
+<title :id="`${name}-${id}-title`" :lang="lang">{{ title }}</title>
+<desc :id="`${name}-${id}-desc`" :lang="lang">{{ description }}</desc>
+```
+
+### 3. Consumer Usage Pattern
+
+Consumers (like BrandCrowd.Net) can then pass the current locale:
+
+```vue
+<template>
+  <DcomIcon
+    :name="feature.iconName"
+    size="md"
+    :lang="currentLang"
+    :alt-text="$t(`icons.${feature.iconName}.title`)"
+  />
+</template>
+
+<script setup>
+const { locale } = useI18n();
+// Convert 'fr-FR' to 'fr' for HTML lang attribute
+const currentLang = computed(() => locale.value.split('-')[0]);
+</script>
+```
+
+---
+
+## Benefits
+
+✅ **Backward Compatible**: Default value of `'en'` preserves existing behavior
+✅ **Minimal Change**: Only 3 lines modified in the component
+✅ **Flexible**: Consumers control the language based on their i18n setup
+✅ **Standards Compliant**: Proper `lang` attributes improve accessibility
+✅ **Simple**: No complex translation logic needed in the shared library
+
+---
+
+## Testing Checklist
+
+- [ ] Verify `lang` prop defaults to `'en'` when not provided
+- [ ] Test passing different language codes ('fr', 'es', 'pt', 'de')
+- [ ] Confirm rendered HTML shows correct `lang` attribute in title/desc
+- [ ] Update Storybook story to demonstrate lang prop usage
+- [ ] Verify no breaking changes to existing consumers
+
+---
+
+## Implementation Notes
+
+**Why this approach works well:**
+
+1. **Separation of Concerns**: The shared library handles rendering with the correct lang attribute, while consumers handle translation logic specific to their i18n setup
+2. **Accessibility Best Practice**: The `lang` attribute tells screen readers which language pronunciation rules to use, critical for international users
+3. **Minimal Surface Area**: Adding a single prop is safer than building complex translation logic into a shared component library
+
+---
+
+## File Location in fe-shared-lib
+
+**Primary file to modify:**
+- `src/atoms/components/design-com/Icon/Icon.vue`
+
+**Lines to change:**
+- Line 21-22 (template)
+- Props definition (add `lang` prop)
+
+**Current component location in BrandCrowd.Net node_modules:**
+- `/home/zknowles/BrandCrowd.Net/BrandCrowd.Nuxt/node_modules/@designcrowd/fe-shared-lib/src/atoms/components/design-com/Icon/Icon.vue`

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designcrowd/fe-shared-lib",
-  "version": "1.5.0-jj-4",
+  "version": "1.5.1-icontranslation",
   "scripts": {
     "start": "run-p storybook watch:translation",
     "build": "npm run build:css --production",

package/public/css/tailwind-brandCrowd.css

@@ -738,6 +738,9 @@ video {
 .theme-brandCrowd .tw-mt-0 {
   margin-top: 0px;
 }
+.theme-brandCrowd .tw-mt-0\.5 {
+  margin-top: 0.125rem;
+}
 .theme-brandCrowd .tw-mt-1 {
   margin-top: 0.25rem;
 }
@@ -750,9 +753,6 @@ video {
 .theme-brandCrowd .tw-mt-4 {
   margin-top: 1rem;
 }
-.theme-brandCrowd .tw-mt-6 {
-  margin-top: 1.5rem;
-}
 .theme-brandCrowd .tw-mt-8 {
   margin-top: 2rem;
 }
@@ -926,9 +926,6 @@ video {
 .theme-brandCrowd .tw-flex-none {
   flex: none;
 }
-.theme-brandCrowd .tw-flex-shrink-0 {
-  flex-shrink: 0;
-}
 .theme-brandCrowd .tw-grow {
   flex-grow: 1;
 }

package/public/css/tailwind-brandPage.css

@@ -738,6 +738,9 @@ video {
 .theme-brandPage .tw-mt-0 {
   margin-top: 0px;
 }
+.theme-brandPage .tw-mt-0\.5 {
+  margin-top: 0.125rem;
+}
 .theme-brandPage .tw-mt-1 {
   margin-top: 0.25rem;
 }
@@ -750,9 +753,6 @@ video {
 .theme-brandPage .tw-mt-4 {
   margin-top: 1rem;
 }
-.theme-brandPage .tw-mt-6 {
-  margin-top: 1.5rem;
-}
 .theme-brandPage .tw-mt-8 {
   margin-top: 2rem;
 }
@@ -926,9 +926,6 @@ video {
 .theme-brandPage .tw-flex-none {
   flex: none;
 }
-.theme-brandPage .tw-flex-shrink-0 {
-  flex-shrink: 0;
-}
 .theme-brandPage .tw-grow {
   flex-grow: 1;
 }

package/public/css/tailwind-crazyDomains.css

@@ -738,6 +738,9 @@ video {
 .theme-crazyDomains .tw-mt-0 {
   margin-top: 0px;
 }
+.theme-crazyDomains .tw-mt-0\.5 {
+  margin-top: 0.125rem;
+}
 .theme-crazyDomains .tw-mt-1 {
   margin-top: 0.25rem;
 }
@@ -750,9 +753,6 @@ video {
 .theme-crazyDomains .tw-mt-4 {
   margin-top: 1rem;
 }
-.theme-crazyDomains .tw-mt-6 {
-  margin-top: 1.5rem;
-}
 .theme-crazyDomains .tw-mt-8 {
   margin-top: 2rem;
 }
@@ -926,9 +926,6 @@ video {
 .theme-crazyDomains .tw-flex-none {
   flex: none;
 }
-.theme-crazyDomains .tw-flex-shrink-0 {
-  flex-shrink: 0;
-}
 .theme-crazyDomains .tw-grow {
   flex-grow: 1;
 }

package/public/css/tailwind-designCom.css

@@ -738,6 +738,9 @@ video {
 .theme-designCom .tw-mt-0 {
   margin-top: 0px;
 }
+.theme-designCom .tw-mt-0\.5 {
+  margin-top: 0.125rem;
+}
 .theme-designCom .tw-mt-1 {
   margin-top: 0.25rem;
 }
@@ -750,9 +753,6 @@ video {
 .theme-designCom .tw-mt-4 {
   margin-top: 1rem;
 }
-.theme-designCom .tw-mt-6 {
-  margin-top: 1.5rem;
-}
 .theme-designCom .tw-mt-8 {
   margin-top: 2rem;
 }
@@ -926,9 +926,6 @@ video {
 .theme-designCom .tw-flex-none {
   flex: none;
 }
-.theme-designCom .tw-flex-shrink-0 {
-  flex-shrink: 0;
-}
 .theme-designCom .tw-grow {
   flex-grow: 1;
 }

package/public/css/tailwind-designCrowd.css

@@ -738,6 +738,9 @@ video {
 .theme-designCrowd .tw-mt-0 {
   margin-top: 0px;
 }
+.theme-designCrowd .tw-mt-0\.5 {
+  margin-top: 0.125rem;
+}
 .theme-designCrowd .tw-mt-1 {
   margin-top: 0.25rem;
 }
@@ -750,9 +753,6 @@ video {
 .theme-designCrowd .tw-mt-4 {
   margin-top: 1rem;
 }
-.theme-designCrowd .tw-mt-6 {
-  margin-top: 1.5rem;
-}
 .theme-designCrowd .tw-mt-8 {
   margin-top: 2rem;
 }
@@ -926,9 +926,6 @@ video {
 .theme-designCrowd .tw-flex-none {
   flex: none;
 }
-.theme-designCrowd .tw-flex-shrink-0 {
-  flex-shrink: 0;
-}
 .theme-designCrowd .tw-grow {
   flex-grow: 1;
 }