@donotdev/cli 0.0.4 → 0.0.5

package/templates/root-consumer/guides/COMPONENTS_ATOMIC.md.example

@@ -25,7 +25,7 @@ These are the only ways one should handle layout to get to quick results functio
 - **DualCard** - Side-by-side card layout for comparison or feature showcases.
 - **Text** - Typography component with semantic text variants.
 - **Blockquote** - Styled blockquote for citations and testimonials.
-- **List** - Bullet points, numbered lists, and feature lists with zero CSS.
+- **List** - Bullet points, numbered lists, and feature lists with zero CSS. Use `icon` prop for custom icons, `icon={null}` for plain bullets.
 - **DescriptionList** - Key-value pairs and metadata using semantic HTML (dl, dt, dd).
 - **Separator** - Visual separator with semantic styling variants.
 

package/templates/root-consumer/guides/COMPONENTS_UI.md.example

@@ -39,6 +39,12 @@
 
 ---
 
+## Helpers
+
+- **tList(t, key, count, icon?, size?)** - Translated array as List. Default: CheckCircle icon. Pass `null` for no icon (use with emoji labels).
+
+---
+
 ## Common Components
 
 - **AppLoading** - App-level loading component.

package/templates/root-consumer/guides/SETUP_I18N.md.example

@@ -4,15 +4,81 @@
 
 ---
 
+## Translation File Locations (CRITICAL)
+
+**Two paths - choose based on when translations are needed:**
+
+1. **Eager (`src/locales/`)**: Always loaded - use for common UI, navigation, app-wide content
+2. **Lazy (`src/pages/locales/`)**: Loaded when page loads - use for page-specific content
+
+**✅ RULE OF THUMB:**
+- **Eager**: Navigation, buttons, common messages (used everywhere)
+- **Lazy**: Page content, feature content, large text blocks (used on specific pages)
+
+**Framework auto-discovers both paths. No configuration needed.**
+
+---
+
 ## Standard Use
 
-**Files:** `src/locales/<namespace>_<2-char-ISO>.json` (eager) | `src/pages/locales/<namespace>_<2-char-ISO>.json` (lazy)
+**CRITICAL: Two Translation Paths - Choose Based on When Translations Are Needed**
+
+### Eager Translations (Always Loaded)
+**Path:** `src/locales/<namespace>_<2-char-ISO>.json`
+
+**Use for:**
+- Common UI elements (buttons, labels, navigation)
+- Critical app-wide translations (app name, common messages)
+- Translations needed on every page
+
+**Example:**
+```
+src/
+  locales/
+    common_en.json      # ✅ Eager - always available
+    common_fr.json
+    navigation_en.json  # ✅ Eager - used in header/sidebar
+    navigation_fr.json
+```
 
+### Lazy Translations (Loaded When Page Loads)
+**Path:** `src/pages/locales/<namespace>_<2-char-ISO>.json`
+
+**Use for:**
+- Page-specific content (page titles, descriptions, page content)
+- Feature-specific translations (dashboard, blog, admin)
+- Translations only needed when that page/feature is accessed
+
+**Example:**
+```
+src/
+  pages/
+    HomePage.tsx
+    locales/
+      home_en.json      # ✅ Lazy - loaded when HomePage loads
+      home_fr.json
+    dashboard/
+      DashboardPage.tsx
+      locales/
+        dashboard_en.json  # ✅ Lazy - loaded when DashboardPage loads
+        dashboard_fr.json
+```
+
+**✅ DECISION GUIDE:**
+- **Eager (`src/locales/`)**: Navigation, common buttons, app-wide messages
+- **Lazy (`src/pages/locales/`)**: Page content, feature-specific content, large text blocks
+
+**Usage:**
 ```tsx
 import { useTranslation } from '@donotdev/core';
 
-const { t } = useTranslation(NAMESPACE);
-t('title');
+// Eager namespace (common, navigation, etc.)
+const { t } = useTranslation('common');
+t('app.title');
+
+// Lazy namespace (page-specific)
+const { t } = useTranslation('home');
+t('hero.title');
 ```
 
 **LanguageSelector:** Included in layout presets. Import from `@donotdev/core` if needed elsewhere.
@@ -21,14 +87,87 @@ t('title');
 
 ## Advanced: Array Translations
 
+### Low-level: translateArray
+
 ```tsx
 import { translateArray, translateObjectArray, maybeTranslate } from '@donotdev/core';
 
-translateArray(t, 'benefits', 10);              // Up to 10 items (benefits.0-9), safe if only 4 exist
-translateObjectArray(t, 'cases', 10, ['useCase', 'bestFit']); // Up to 10 objects
-maybeTranslate(t, 'products.earlyBird.name');  // Auto-detects key vs string
+// Get array of strings (filters missing translations automatically)
+const benefits = translateArray(t, 'benefits', 10); // Up to 10 items (benefits.0-9), safe if only 4 exist
+const features = translateArray(t, 'features.list', 5); // Nested keys work
+
+// Get array of objects
+const cases = translateObjectArray(t, 'cases', 10, ['useCase', 'bestFit']);
+
+// Auto-detect if value is a translation key or literal string
+maybeTranslate(t, 'products.earlyBird.name');
 ```
 
+### High-level: tList (Recommended for Cards)
+
+`tList` wraps `translateArray` and returns a `List` component ready for `Card` content:
+
+```tsx
+import { tList } from '@donotdev/ui';
+
+// With default icon (CheckCircle)
+<Card content={tList(t, 'features.items', 4)} />
+
+// With custom icon
+<Card content={tList(t, 'features.items', 4, Star)} />
+
+// Without icon (for emoji-prefixed labels like "🚀 Kick-off")
+<Card content={tList(t, 'features.items', 4, null)} />
+```
+
+**JSON structure:**
+```json
+{
+  "features": {
+    "items": [
+      "Feature 1",
+      "Feature 2",
+      "Feature 3"
+    ]
+  }
+}
+```
+
+---
+
+## Advanced: Rich Text (Trans)
+
+For inline styling in translations, use `Trans` instead of `t()`. Use when translations contain HTML-like tags for styling.
+
+```tsx
+import { Trans } from '@donotdev/core';
+
+// Translation: "<accent>MVP</accent> in 2 weeks"
+<HeroSection title={<Trans ns={NAMESPACE} i18nKey="hero.title" />} />
+
+// Translation: "I need <accent>Clarity</accent>"
+<Card title={<Trans ns={NAMESPACE} i18nKey="products.transformation.title" />} />
+```
+
+**JSON with tags:**
+```json
+{
+  "hero": {
+    "title": "Idea to <accent>MVP</accent> in 2 weeks"
+  },
+  "products": {
+    "transformation": {
+      "title": "I need <accent>Clarity</accent>",
+      "subtitle": "...for a <accent>critical</accent> application"
+    }
+  }
+}
+```
+
+**Supported tags:** `<accent>` `<primary>` `<muted>` `<success>` `<warning>` `<error>` `<bold>` `<code>`
+
+**Note:** `Trans` accepts `ns` prop (string) for namespace. Use `t()` for plain strings, `Trans` for rich text with styling tags.
+
 ---
 
 ## Advanced: I18N Components

package/templates/root-consumer/guides/SETUP_LAYOUTS.md.example

@@ -18,6 +18,24 @@ export const appConfig: AppConfig = {
 
 ---
 
+## Preset Capabilities
+
+**The `docs` preset AUTOMATICALLY generates sidebar navigation from your `src/pages` files. You do not need to configure a sidebar manually.**
+
+All presets automatically include these components when applicable:
+
+*   **LanguageSelector** - Automatically shown if more than 1 language is configured
+*   **ThemeToggle** - Automatically shown if more than 1 theme is available
+*   **AuthMenu** - Automatically shown if auth is configured in `.env` (Firebase keys present)
+*   **Navigation Menu** - Automatically generated from `src/pages/*Page.tsx` files for sidebars
+*   **GoTo Component** - Command palette (Cmd+K) for quick navigation - always available
+*   **Footer** - Automatic footer with copyright and legal links
+*   **LegalLinks + Copyright** - Automatically included in footer from `config/legal.ts`
+
+**You don't need to add these manually - the framework handles them based on your configuration.**
+
+---
+
 ## Advanced: Slot Overrides
 
 **Customize zones:**

package/templates/root-consumer/guides/SETUP_PAGES.md.example

@@ -4,6 +4,14 @@
 
 ---
 
+## File Routing Rule
+
+**CRITICAL: Only files ending in `Page.tsx` inside `src/pages` become routes.**
+
+Files must be named `*Page.tsx` (e.g., `HomePage.tsx`, `AboutPage.tsx`, `BlogPostPage.tsx`). Files without the `Page.tsx` suffix are ignored by the routing system.
+
+---
+
 ## Standard Use
 
 **Pattern:** `src/pages/**/*Page.tsx` → routes