@wangs-ui/skills 1.0.59 → 1.0.61

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as listSkills, n as updateSkills, r as addSkills, t as removeSkills } from "./src-CmtJDo3Y.js";
+import { i as listSkills, n as updateSkills, r as addSkills, t as removeSkills } from "./src-CusYgPAm.js";
 import path from "node:path";
 import { parseArgs } from "node:util";
 //#region bin.ts

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as getAgentSkillDirs, c as isSkillInstalled, d as loadAllSkills, i as listSkills, l as removeSkill, n as updateSkills, o as getInstalledSkills, r as addSkills, s as installSkill, t as removeSkills, u as getSkill } from "./src-CmtJDo3Y.js";
+import { a as getAgentSkillDirs, c as isSkillInstalled, d as loadAllSkills, i as listSkills, l as removeSkill, n as updateSkills, o as getInstalledSkills, r as addSkills, s as installSkill, t as removeSkills, u as getSkill } from "./src-CusYgPAm.js";
 export { addSkills, getAgentSkillDirs, getInstalledSkills, getSkill, installSkill, isSkillInstalled, listSkills, loadAllSkills, removeSkill, removeSkills, updateSkills };

package/dist/skills/i18n-usage/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: i18n-usage
-description: Guidelines, formatting rules, and MCP discovery protocol for internationalization with @wangs-ui/react-i18n and localized components.
+description: Comprehensive guidelines for application internationalization, JIT translations (t), ICU formatting, and locale-aware formatting with @wangs-ui/react-i18n.
 ---
 
-# Skill: Application Internationalization & Localization Protocol
+# Skill: Application Internationalization & Formatting Protocol
 
-Use this skill when handling multi-language interfaces, currency inputs, localized date formats, or dynamic text translations in Wangs UI applications.
+Use this skill when implementing multi-language interfaces, translating user-facing text, formatting dates, times, currencies, or numbers in React applications built with Wangs UI and `@wangs-ui/react-i18n`.
 
 ---
 
-## 1. MCP Inspection Protocol (Single Source of Truth)
+## 1. The MCP Discovery Protocol (Single Source of Truth)
 
-Do **NOT** guess component localization props or language switcher variants. Query the MCP server dynamically to inspect exact contracts and live story implementations:
+Do **NOT** guess component localization contracts, language switcher variants, or datepicker props. Query the MCP server dynamically to inspect exact props and live story implementations:
 
 ### Inspect Localized Component Contracts:
 
@@ -19,6 +19,8 @@ Do **NOT** guess component localization props or language switcher variants. Que
 get-documentation({ "id": "languageswitcher" })
 get-documentation({ "id": "currencyinput" })
 get-documentation({ "id": "datepicker" })
+get-documentation({ "id": "select" })
+get-documentation({ "id": "datatable" })
 ```
 
 ### Inspect Live Story Implementations:
@@ -31,52 +33,200 @@ get-documentation-for-story({ "id": "datepicker", "storyName": "Default" })
 
 ---
 
-## 2. Translation Syntax & Golden Rules
+## 2. Root Provider Setup (`WangsUiI18nProvider`)
 
-1. **Sentence Keys in Natural English**:
-   Always write human-readable English sentence keys:
+Wrap the application root with `WangsUiI18nProvider` from `@wangs-ui/react-i18n` to enable dynamic JIT translations, versioned cache invalidation, and locale context:
 
-   ```tsx
-   // ✅ Good
-   t('Invoice Summary');
-   t('Are you sure you want to delete this customer?');
+```tsx
+import { WangsUiI18nProvider } from '@wangs-ui/react-i18n';
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
 
-   // ❌ Bad — artificial dotted keys
-   t('invoice.summary.title');
-   ```
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <WangsUiI18nProvider defaultLocale="en" baseUrl={import.meta.env.VITE_API_URL || ''}>
+      <App />
+    </WangsUiI18nProvider>
+  </React.StrictMode>,
+);
+```
+
+---
+
+## 3. Translation Protocol with `useI18n()`
+
+The `@wangs-ui/react-i18n` package uses a Just-In-Time (JIT) translation architecture where natural English text strings serve as database keys.
+
+### A. Consumer-Level Translation for `ReactNode` Props (Mandatory)
+
+All user-facing text props in Wangs UI components (`placeholder`, `label`, `emptyMessage`, `header`, `tooltip`, etc.) are typed as `ReactNode` and rendered as-is. Components do **NOT** automatically translate custom strings. Translation **MUST** be called at the application/consumer level:
+
+```tsx
+import { useI18n } from '@wangs-ui/react-i18n';
+import Button from '@wangs-ui/react-core/primitive/button';
+import DataTable from '@wangs-ui/react-core/primitive/datatable';
+import Select from '@wangs-ui/react-core/primitive/select';
+
+export function OrderList() {
+  const { t } = useI18n();
+
+  return (
+    <div>
+      <Select placeholder={t('Search category...')} />
+      <DataTable emptyMessage={t('No orders found')} />
+      <Button label={t('Create new order')} />
+    </div>
+  );
+}
+```
+
+### B. Natural English Sentence Keys
 
-2. **Dynamic Variables in Double Braces (`{{var}}`)**:
-   Pass variables as an object using `{{variableName}}` interpolation:
+Always write full, natural English sentences as translation keys. Never use artificial dotted namespace keys:
 
-   ```tsx
-   // ✅ Good
-   t('Welcome back, {{name}}!', { name: user.name });
+```tsx
+// ✅ Good — Natural English
+t('Invoice Summary');
+t('Are you sure you want to delete this customer?');
 
-   // ❌ Bad — string concatenation breaks translation word order
-   t('Welcome back, ') + user.name + '!';
-   ```
+// ❌ Bad — Artificial dotted keys
+t('invoice.summary.title');
+t('dialog.delete.customer.confirm');
+```
+
+### C. Named Variable Interpolation (Single Braces `{var}`)
+
+Pass interpolation values inside a plain object using descriptive named variables. This provides crucial semantic context for AI translation engines:
+
+```tsx
+// ✅ Good — Named variables provide context
+t('Upload {count} files to {groupName}', { count: 5, groupName: 'Marketing' });
+t('Welcome back, {userName}!', { userName: user.name });
+
+// ❌ Bad — Concatenation or positional arguments
+t('Welcome back, ' + user.name);
+t('Upload {0} files to {1}', 5, 'Marketing');
+```
 
-3. **Pluralization with ICU Formats**:
-   Use ICU plural format for quantity-dependent sentences:
+### D. ICU Pluralization & Zero-State (`=0`)
 
-   ```tsx
-   t('{count, plural, =0 {No items selected} one {# item selected} other {# items selected}}', {
-     count: selectedCount,
-   });
-   ```
+Always handle singular, plural, and zero states directly within ICU MessageFormat strings. Do **NOT** use JavaScript ternary operators:
 
-4. **Runtime Locale Switching**:
-   Use the `useI18n()` hook to read or update active language:
-   ```tsx
-   import { useI18n } from '@wangs-ui/react-i18n';
+```tsx
+// ✅ Good — Clean ICU pluralization with zero-state handling
+t('{count, plural, =0 {No items selected} one {1 item selected} other {{count} items selected}}', {
+  count: selectedCount,
+});
 
-   const { t, currentLocale, setLocale } = useI18n();
-   ```
+// ❌ Bad — Manual JS branching
+selectedCount === 0
+  ? t('No items selected')
+  : selectedCount === 1
+    ? t('1 item selected')
+    : t('{count} items selected', { count: selectedCount });
+```
+
+### E. Rich Text / Annotated Strings
+
+Use standard supported HTML tags (`<a>`, `<b>`, `<i>`, `<u>`, `<s>`, `<br/>`, `<sub>`, `<sup>`, `<code>`, `<mark>`) for inline styling. Tags are automatically parsed into React elements without custom regex or string manipulation:
+
+```tsx
+import Link from '@wangs-ui/foundation/theme/Link';
+
+t('You have selected <b>{count} items</b>. Click <a>here</a> to review.', {
+  count: selectedCount,
+  a: (chunks) => <Link href="/review">{chunks}</Link>,
+});
+```
+
+---
+
+## 4. Locale Formatting Protocol with `useLocaleFormatter()`
+
+For locale-aware formatting of dates, relative times, currencies, numbers, and display names, use the dedicated `useLocaleFormatter()` hook. All functions automatically adapt to the active locale without triggering backend database requests:
+
+```tsx
+import { useLocaleFormatter } from '@wangs-ui/react-i18n';
+
+export function SummaryCard({ updatedAt, amount, count }: Props) {
+  const {
+    formatDate,
+    formatRelativeTime,
+    formatCurrency,
+    formatNumber,
+    formatDisplayName,
+    formatList,
+    truncateText,
+  } = useLocaleFormatter();
+
+  return (
+    <div>
+      {/* Date formatting with Go tokens or date-fns tokens, and timezone */}
+      <p>{formatDate(new Date(), 'dd MMMM yyyy, HH:mm', 'Asia/Jakarta')}</p>
+
+      {/* Relative time */}
+      <p>{formatRelativeTime(updatedAt)}</p>
+
+      {/* Currency formatting */}
+      <p>{formatCurrency(amount, 'IDR')}</p>
+
+      {/* Number formatting with locale grouping */}
+      <p>{formatNumber(count)}</p>
+
+      {/* ISO code to localized name */}
+      <p>{formatDisplayName('id', 'language')}</p>
+
+      {/* Localized list */}
+      <p>{formatList(['Finance', 'Operations', 'IT'])}</p>
+
+      {/* Emoji & multi-byte safe text truncation */}
+      <p>{truncateText('Long product description with emojis 🚀', 20)}</p>
+    </div>
+  );
+}
+```
+
+> [!NOTE]
+> Formatters MUST NOT be called as standalone `t()` keys (e.g. `t(formatRelativeTime(date))`). Instead, pass the formatted result as a named variable:
+>
+> ```tsx
+> const { t } = useI18n();
+> const { formatRelativeTime } = useLocaleFormatter();
+> const label = t('Updated {time}', { time: formatRelativeTime(updatedAt) });
+> ```
+
+---
+
+## 5. Language Switching UI Integration
+
+Connect the Wangs UI `LanguageSwitcher` primitive directly with `useI18n()` state:
+
+```tsx
+import LanguageSwitcher from '@wangs-ui/react-core/primitive/languageswitcher';
+import { useI18n } from '@wangs-ui/react-i18n';
+
+export function HeaderLanguageSwitcher() {
+  const { locale, setLocale, languageOptions } = useI18n();
+
+  return (
+    <LanguageSwitcher
+      options={languageOptions}
+      value={locale}
+      onChange={(code) => setLocale(code)}
+    />
+  );
+}
+```
 
 ---
 
-## 3. Mandatory Implementation Rules
+## 6. Strict Behavioral Constraints (MUST NOT)
 
-1. **Inspect Localized Components via MCP**: Query `currencyinput` and `datepicker` documentation before binding locale-sensitive formatters.
-2. **Never Hardcode User-Facing Text**: Every visible label, placeholder, dialog title, tooltip, and error message in the application must pass through `t()`.
-3. **Keep Context Intact**: Do not split sentences into separate phrases across JSX elements; translate the full sentence as a single unit.
+- **NO Formatters Destructured from `useI18n()`:** Formatters are isolated in `useLocaleFormatter()`. Never attempt to import `formatDate` or `formatCurrency` from `useI18n()`.
+- **NO String Concatenation in `t()` Keys:** Never concatenate strings or use dynamic template literals (e.g. `t('Hello ' + user.name)` or ``t(`Hello ${user.name}`)``). This creates infinite distinct keys in the translation database and prevents caching.
+- **NO Manual Zero-State JavaScript Branching:** Always use ICU `=0` syntax inside a single plural key.
+- **NO Dotted Artificial Translation Keys:** Never use dotted keys like `t('app.header.title')`. Use natural English sentences.
+- **NO Custom Markdown Formatting Symbols:** Do not use `*bold*` or `_italic_` in translation keys. Use valid HTML tags like `<b>bold</b>`.
+- **NO Hardcoded Static Translation Dictionaries:** Do not bundle static translation files (`id.json`, `zh.json`). The JIT backend broker manages translations dynamically.
+- **NO Unnecessary English Key Modifications:** Minor typos or punctuation changes in keys create orphaned entries in the translation backend and trigger new AI translation costs.

package/dist/{src-CmtJDo3Y.js → src-CusYgPAm.js}

@@ -12,7 +12,7 @@ var SKILL_default$6 = "---\nname: data-table\ndescription: Architecture, workflo
 var SKILL_default$5 = "---\nname: dialog-modal\ndescription: Patterns, overlay selection criteria, and MCP discovery protocol for Dialog, Modal, and DialogForm components in Wangs UI.\n---\n\n# Skill: Dialog, Modal & Overlay Workflows\n\nUse this skill when building interactive modals, create/edit dialog forms, destructive action confirmations, or slide-in overlay panels.\n\n---\n\n## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)\n\nDo **NOT** guess overlay props, event names, or footer slots. Query the MCP server dynamically to inspect exact contracts and live story implementations:\n\n### Inspect Overlay Contracts:\n\n```json\nget-documentation({ \"id\": \"dialog\" })\nget-documentation({ \"id\": \"dialogform\" })\nget-documentation({ \"id\": \"modal\" })\nget-documentation({ \"id\": \"toast\" })\n```\n\n### Inspect Live Story Implementations:\n\n```json\nget-documentation-for-story({ \"id\": \"dialog\", \"storyName\": \"Confirmation\" })\nget-documentation-for-story({ \"id\": \"dialogform\", \"storyName\": \"Default\" })\nget-documentation-for-story({ \"id\": \"modal\", \"storyName\": \"Default\" })\n```\n\n### Inspect Knowledge Graph & Usages:\n\n```json\nquery_graph({ \"query\": \"Dialog\" })\nquery_graph({ \"query\": \"DialogForm\" })\n```\n\n---\n\n## 2. Overlay Selection Matrix\n\n| Component        | Primary Use Case                              | Key Characteristics                                                                   |\n| :--------------- | :-------------------------------------------- | :------------------------------------------------------------------------------------ |\n| **`Dialog`**     | Confirmations, alerts, simple detail previews | Standard `header`, `footer`, and body layout; built-in backdrop dimming.              |\n| **`DialogForm`** | Create/Edit forms embedded inside a dialog    | Built-in form submit/cancel action bar, dirty state tracking, and submit lifecycle.   |\n| **`Modal`**      | Slide-in drawers, complex custom viewports    | Headless overlay primitive with flexible animations, size variants, and drawer modes. |\n\n---\n\n## 3. Mandatory Implementation Rules\n\n1. **Query MCP for Current Code Patterns**: Always inspect `dialog`, `dialogform`, or `modal` stories via MCP before writing overlay code.\n2. **Strict Subpath Imports**: Import via `@wangs-ui/react-core/primitive/dialog`, `@wangs-ui/react-core/primitive/dialogform`, `@wangs-ui/react-core/primitive/modal`, or `@wangs-ui/react-core/primitive/toast`.\n3. **Prevent Dismissal During Async Mutations**: Guard the close handler so users cannot accidentally dismiss the dialog while a mutation request is in-flight.\n4. **Coordinate with Toast Notifications**: Trigger feedback toasts on successful creation, update, or deletion actions.\n5. **Translate All Overlay Copy**: All dialog titles, confirmation descriptions, and button labels must be localized using `t('...')` from `@wangs-ui/react-i18n`.\n";
 //#endregion
 //#region skills/i18n-usage/SKILL.md?raw
-var SKILL_default$4 = "---\nname: i18n-usage\ndescription: Guidelines, formatting rules, and MCP discovery protocol for internationalization with @wangs-ui/react-i18n and localized components.\n---\n\n# Skill: Application Internationalization & Localization Protocol\n\nUse this skill when handling multi-language interfaces, currency inputs, localized date formats, or dynamic text translations in Wangs UI applications.\n\n---\n\n## 1. MCP Inspection Protocol (Single Source of Truth)\n\nDo **NOT** guess component localization props or language switcher variants. Query the MCP server dynamically to inspect exact contracts and live story implementations:\n\n### Inspect Localized Component Contracts:\n\n```json\nget-documentation({ \"id\": \"languageswitcher\" })\nget-documentation({ \"id\": \"currencyinput\" })\nget-documentation({ \"id\": \"datepicker\" })\n```\n\n### Inspect Live Story Implementations:\n\n```json\nget-documentation-for-story({ \"id\": \"languageswitcher\", \"storyName\": \"Basic\" })\nget-documentation-for-story({ \"id\": \"currencyinput\", \"storyName\": \"Basic\" })\nget-documentation-for-story({ \"id\": \"datepicker\", \"storyName\": \"Default\" })\n```\n\n---\n\n## 2. Translation Syntax & Golden Rules\n\n1. **Sentence Keys in Natural English**:\n   Always write human-readable English sentence keys:\n\n   ```tsx\n   // ✅ Good\n   t('Invoice Summary');\n   t('Are you sure you want to delete this customer?');\n\n   // ❌ Bad — artificial dotted keys\n   t('invoice.summary.title');\n   ```\n\n2. **Dynamic Variables in Double Braces (`{{var}}`)**:\n   Pass variables as an object using `{{variableName}}` interpolation:\n\n   ```tsx\n   // ✅ Good\n   t('Welcome back, {{name}}!', { name: user.name });\n\n   // ❌ Bad — string concatenation breaks translation word order\n   t('Welcome back, ') + user.name + '!';\n   ```\n\n3. **Pluralization with ICU Formats**:\n   Use ICU plural format for quantity-dependent sentences:\n\n   ```tsx\n   t('{count, plural, =0 {No items selected} one {# item selected} other {# items selected}}', {\n     count: selectedCount,\n   });\n   ```\n\n4. **Runtime Locale Switching**:\n   Use the `useI18n()` hook to read or update active language:\n   ```tsx\n   import { useI18n } from '@wangs-ui/react-i18n';\n\n   const { t, currentLocale, setLocale } = useI18n();\n   ```\n\n---\n\n## 3. Mandatory Implementation Rules\n\n1. **Inspect Localized Components via MCP**: Query `currencyinput` and `datepicker` documentation before binding locale-sensitive formatters.\n2. **Never Hardcode User-Facing Text**: Every visible label, placeholder, dialog title, tooltip, and error message in the application must pass through `t()`.\n3. **Keep Context Intact**: Do not split sentences into separate phrases across JSX elements; translate the full sentence as a single unit.\n";
+var SKILL_default$4 = "---\nname: i18n-usage\ndescription: Comprehensive guidelines for application internationalization, JIT translations (t), ICU formatting, and locale-aware formatting with @wangs-ui/react-i18n.\n---\n\n# Skill: Application Internationalization & Formatting Protocol\n\nUse this skill when implementing multi-language interfaces, translating user-facing text, formatting dates, times, currencies, or numbers in React applications built with Wangs UI and `@wangs-ui/react-i18n`.\n\n---\n\n## 1. The MCP Discovery Protocol (Single Source of Truth)\n\nDo **NOT** guess component localization contracts, language switcher variants, or datepicker props. Query the MCP server dynamically to inspect exact props and live story implementations:\n\n### Inspect Localized Component Contracts:\n\n```json\nget-documentation({ \"id\": \"languageswitcher\" })\nget-documentation({ \"id\": \"currencyinput\" })\nget-documentation({ \"id\": \"datepicker\" })\nget-documentation({ \"id\": \"select\" })\nget-documentation({ \"id\": \"datatable\" })\n```\n\n### Inspect Live Story Implementations:\n\n```json\nget-documentation-for-story({ \"id\": \"languageswitcher\", \"storyName\": \"Basic\" })\nget-documentation-for-story({ \"id\": \"currencyinput\", \"storyName\": \"Basic\" })\nget-documentation-for-story({ \"id\": \"datepicker\", \"storyName\": \"Default\" })\n```\n\n---\n\n## 2. Root Provider Setup (`WangsUiI18nProvider`)\n\nWrap the application root with `WangsUiI18nProvider` from `@wangs-ui/react-i18n` to enable dynamic JIT translations, versioned cache invalidation, and locale context:\n\n```tsx\nimport { WangsUiI18nProvider } from '@wangs-ui/react-i18n';\nimport React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport App from './App';\n\nReactDOM.createRoot(document.getElementById('root')!).render(\n  <React.StrictMode>\n    <WangsUiI18nProvider defaultLocale=\"en\" baseUrl={import.meta.env.VITE_API_URL || ''}>\n      <App />\n    </WangsUiI18nProvider>\n  </React.StrictMode>,\n);\n```\n\n---\n\n## 3. Translation Protocol with `useI18n()`\n\nThe `@wangs-ui/react-i18n` package uses a Just-In-Time (JIT) translation architecture where natural English text strings serve as database keys.\n\n### A. Consumer-Level Translation for `ReactNode` Props (Mandatory)\n\nAll user-facing text props in Wangs UI components (`placeholder`, `label`, `emptyMessage`, `header`, `tooltip`, etc.) are typed as `ReactNode` and rendered as-is. Components do **NOT** automatically translate custom strings. Translation **MUST** be called at the application/consumer level:\n\n```tsx\nimport { useI18n } from '@wangs-ui/react-i18n';\nimport Button from '@wangs-ui/react-core/primitive/button';\nimport DataTable from '@wangs-ui/react-core/primitive/datatable';\nimport Select from '@wangs-ui/react-core/primitive/select';\n\nexport function OrderList() {\n  const { t } = useI18n();\n\n  return (\n    <div>\n      <Select placeholder={t('Search category...')} />\n      <DataTable emptyMessage={t('No orders found')} />\n      <Button label={t('Create new order')} />\n    </div>\n  );\n}\n```\n\n### B. Natural English Sentence Keys\n\nAlways write full, natural English sentences as translation keys. Never use artificial dotted namespace keys:\n\n```tsx\n// ✅ Good — Natural English\nt('Invoice Summary');\nt('Are you sure you want to delete this customer?');\n\n// ❌ Bad — Artificial dotted keys\nt('invoice.summary.title');\nt('dialog.delete.customer.confirm');\n```\n\n### C. Named Variable Interpolation (Single Braces `{var}`)\n\nPass interpolation values inside a plain object using descriptive named variables. This provides crucial semantic context for AI translation engines:\n\n```tsx\n// ✅ Good — Named variables provide context\nt('Upload {count} files to {groupName}', { count: 5, groupName: 'Marketing' });\nt('Welcome back, {userName}!', { userName: user.name });\n\n// ❌ Bad — Concatenation or positional arguments\nt('Welcome back, ' + user.name);\nt('Upload {0} files to {1}', 5, 'Marketing');\n```\n\n### D. ICU Pluralization & Zero-State (`=0`)\n\nAlways handle singular, plural, and zero states directly within ICU MessageFormat strings. Do **NOT** use JavaScript ternary operators:\n\n```tsx\n// ✅ Good — Clean ICU pluralization with zero-state handling\nt('{count, plural, =0 {No items selected} one {1 item selected} other {{count} items selected}}', {\n  count: selectedCount,\n});\n\n// ❌ Bad — Manual JS branching\nselectedCount === 0\n  ? t('No items selected')\n  : selectedCount === 1\n    ? t('1 item selected')\n    : t('{count} items selected', { count: selectedCount });\n```\n\n### E. Rich Text / Annotated Strings\n\nUse standard supported HTML tags (`<a>`, `<b>`, `<i>`, `<u>`, `<s>`, `<br/>`, `<sub>`, `<sup>`, `<code>`, `<mark>`) for inline styling. Tags are automatically parsed into React elements without custom regex or string manipulation:\n\n```tsx\nimport Link from '@wangs-ui/foundation/theme/Link';\n\nt('You have selected <b>{count} items</b>. Click <a>here</a> to review.', {\n  count: selectedCount,\n  a: (chunks) => <Link href=\"/review\">{chunks}</Link>,\n});\n```\n\n---\n\n## 4. Locale Formatting Protocol with `useLocaleFormatter()`\n\nFor locale-aware formatting of dates, relative times, currencies, numbers, and display names, use the dedicated `useLocaleFormatter()` hook. All functions automatically adapt to the active locale without triggering backend database requests:\n\n```tsx\nimport { useLocaleFormatter } from '@wangs-ui/react-i18n';\n\nexport function SummaryCard({ updatedAt, amount, count }: Props) {\n  const {\n    formatDate,\n    formatRelativeTime,\n    formatCurrency,\n    formatNumber,\n    formatDisplayName,\n    formatList,\n    truncateText,\n  } = useLocaleFormatter();\n\n  return (\n    <div>\n      {/* Date formatting with Go tokens or date-fns tokens, and timezone */}\n      <p>{formatDate(new Date(), 'dd MMMM yyyy, HH:mm', 'Asia/Jakarta')}</p>\n\n      {/* Relative time */}\n      <p>{formatRelativeTime(updatedAt)}</p>\n\n      {/* Currency formatting */}\n      <p>{formatCurrency(amount, 'IDR')}</p>\n\n      {/* Number formatting with locale grouping */}\n      <p>{formatNumber(count)}</p>\n\n      {/* ISO code to localized name */}\n      <p>{formatDisplayName('id', 'language')}</p>\n\n      {/* Localized list */}\n      <p>{formatList(['Finance', 'Operations', 'IT'])}</p>\n\n      {/* Emoji & multi-byte safe text truncation */}\n      <p>{truncateText('Long product description with emojis 🚀', 20)}</p>\n    </div>\n  );\n}\n```\n\n> [!NOTE]\n> Formatters MUST NOT be called as standalone `t()` keys (e.g. `t(formatRelativeTime(date))`). Instead, pass the formatted result as a named variable:\n>\n> ```tsx\n> const { t } = useI18n();\n> const { formatRelativeTime } = useLocaleFormatter();\n> const label = t('Updated {time}', { time: formatRelativeTime(updatedAt) });\n> ```\n\n---\n\n## 5. Language Switching UI Integration\n\nConnect the Wangs UI `LanguageSwitcher` primitive directly with `useI18n()` state:\n\n```tsx\nimport LanguageSwitcher from '@wangs-ui/react-core/primitive/languageswitcher';\nimport { useI18n } from '@wangs-ui/react-i18n';\n\nexport function HeaderLanguageSwitcher() {\n  const { locale, setLocale, languageOptions } = useI18n();\n\n  return (\n    <LanguageSwitcher\n      options={languageOptions}\n      value={locale}\n      onChange={(code) => setLocale(code)}\n    />\n  );\n}\n```\n\n---\n\n## 6. Strict Behavioral Constraints (MUST NOT)\n\n- **NO Formatters Destructured from `useI18n()`:** Formatters are isolated in `useLocaleFormatter()`. Never attempt to import `formatDate` or `formatCurrency` from `useI18n()`.\n- **NO String Concatenation in `t()` Keys:** Never concatenate strings or use dynamic template literals (e.g. `t('Hello ' + user.name)` or ``t(`Hello ${user.name}`)``). This creates infinite distinct keys in the translation database and prevents caching.\n- **NO Manual Zero-State JavaScript Branching:** Always use ICU `=0` syntax inside a single plural key.\n- **NO Dotted Artificial Translation Keys:** Never use dotted keys like `t('app.header.title')`. Use natural English sentences.\n- **NO Custom Markdown Formatting Symbols:** Do not use `*bold*` or `_italic_` in translation keys. Use valid HTML tags like `<b>bold</b>`.\n- **NO Hardcoded Static Translation Dictionaries:** Do not bundle static translation files (`id.json`, `zh.json`). The JIT backend broker manages translations dynamically.\n- **NO Unnecessary English Key Modifications:** Minor typos or punctuation changes in keys create orphaned entries in the translation backend and trigger new AI translation costs.\n";
 //#endregion
 //#region skills/layout-navigation/SKILL.md?raw
 var SKILL_default$3 = "---\nname: layout-navigation\ndescription: Architecture, navigation hierarchies, and MCP discovery protocol for AppLayout, Sidebar, Breadcrumb, and Tabs in Wangs UI.\n---\n\n# Skill: Application Layout & Navigation Hierarchy\n\nUse this skill when constructing application shells, multi-level sidebars, page headers, breadcrumbs, or tabbed views with `@wangs-ui/react-core`.\n\n---\n\n## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)\n\nDo **NOT** guess layout block slots, sidebar item interfaces, or breadcrumb props. Query the MCP server dynamically to inspect exact contracts and live story implementations:\n\n### Inspect Layout & Navigation Contracts:\n\n```json\nget-documentation({ \"id\": \"applayout\" })\nget-documentation({ \"id\": \"sidebar\" })\nget-documentation({ \"id\": \"breadcrumb\" })\nget-documentation({ \"id\": \"tabs\" })\n```\n\n### Inspect Live Story Implementations:\n\n```json\nget-documentation-for-story({ \"id\": \"applayout\", \"storyName\": \"Default\" })\nget-documentation-for-story({ \"id\": \"sidebar\", \"storyName\": \"Default\" })\nget-documentation-for-story({ \"id\": \"breadcrumb\", \"storyName\": \"Default\" })\nget-documentation-for-story({ \"id\": \"tabs\", \"storyName\": \"Default\" })\n```\n\n### Inspect Knowledge Graph & Usages:\n\n```json\nquery_graph({ \"query\": \"AppLayout\" })\nquery_graph({ \"query\": \"Sidebar\" })\n```\n\n---\n\n## 2. Layout Architecture & Mental Model\n\n1. **Top-Level App Shell (`AppLayout`)**:\n   Provides structured slots for `sidebar`, `header`, and main content view, handling responsive viewport scaling and mobile navigation overlays.\n2. **Hierarchical Menu (`Sidebar`)**:\n   Renders single and nested navigation items, active route indicators, collapsible state, and notification badges.\n3. **Breadcrumb Trail (`Breadcrumb`)**:\n   Maintains clear navigational hierarchy on page headers.\n4. **Tabbed Sub-Views (`Tabs`)**:\n   Organizes complex entity detail views or multi-section settings into distinct tabbed panels.\n\n---\n\n## 3. Mandatory Implementation Rules\n\n1. **Query MCP for Current Code Patterns**: Inspect `applayout` and `sidebar` stories via MCP before assembling the layout.\n2. **Strict Subpath Imports**: Import layout blocks via `@wangs-ui/react-core/blocks/*` and primitives via `@wangs-ui/react-core/primitive/*`.\n3. **Consistent Spacing Grid**: Use standard container padding (`p-6` or `p-xxl`) across page contents.\n4. **Page Hierarchy Alignment**: Every page view inside the layout must provide a clear `.heading-1` hierarchy and synchronized breadcrumbs.\n5. **Translate Navigation Labels**: Wrap all sidebar item labels and breadcrumb texts in `t('...')` from `@wangs-ui/react-i18n`.\n";
@@ -144,7 +144,7 @@ function removeSkill(skillId, baseDir = process.cwd()) {
 //#endregion
 //#region src/commands/list.ts
 function listSkills(baseDir = process.cwd()) {
-	intro(`\x1b[1m\x1b[36m📦 Wangs UI Consumer Skills Registry\x1b[0m (v1.0.59)`);
+	intro(`\x1b[1m\x1b[36m📦 Wangs UI Consumer Skills Registry\x1b[0m (v1.0.61)`);
 	const allSkills = loadAllSkills();
 	const targetDirs = getAgentSkillDirs(baseDir);
 	if (allSkills.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wangs-ui/skills",
-  "version": "1.0.59",
+  "version": "1.0.61",
   "description": "CLI to install, update, and manage modular AI agent skills for Wangs UI React applications",
   "keywords": [
     "agents",

package/skills/i18n-usage/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: i18n-usage
-description: Guidelines, formatting rules, and MCP discovery protocol for internationalization with @wangs-ui/react-i18n and localized components.
+description: Comprehensive guidelines for application internationalization, JIT translations (t), ICU formatting, and locale-aware formatting with @wangs-ui/react-i18n.
 ---
 
-# Skill: Application Internationalization & Localization Protocol
+# Skill: Application Internationalization & Formatting Protocol
 
-Use this skill when handling multi-language interfaces, currency inputs, localized date formats, or dynamic text translations in Wangs UI applications.
+Use this skill when implementing multi-language interfaces, translating user-facing text, formatting dates, times, currencies, or numbers in React applications built with Wangs UI and `@wangs-ui/react-i18n`.
 
 ---
 
-## 1. MCP Inspection Protocol (Single Source of Truth)
+## 1. The MCP Discovery Protocol (Single Source of Truth)
 
-Do **NOT** guess component localization props or language switcher variants. Query the MCP server dynamically to inspect exact contracts and live story implementations:
+Do **NOT** guess component localization contracts, language switcher variants, or datepicker props. Query the MCP server dynamically to inspect exact props and live story implementations:
 
 ### Inspect Localized Component Contracts:
 
@@ -19,6 +19,8 @@ Do **NOT** guess component localization props or language switcher variants. Que
 get-documentation({ "id": "languageswitcher" })
 get-documentation({ "id": "currencyinput" })
 get-documentation({ "id": "datepicker" })
+get-documentation({ "id": "select" })
+get-documentation({ "id": "datatable" })
 ```
 
 ### Inspect Live Story Implementations:
@@ -31,52 +33,200 @@ get-documentation-for-story({ "id": "datepicker", "storyName": "Default" })
 
 ---
 
-## 2. Translation Syntax & Golden Rules
+## 2. Root Provider Setup (`WangsUiI18nProvider`)
 
-1. **Sentence Keys in Natural English**:
-   Always write human-readable English sentence keys:
+Wrap the application root with `WangsUiI18nProvider` from `@wangs-ui/react-i18n` to enable dynamic JIT translations, versioned cache invalidation, and locale context:
 
-   ```tsx
-   // ✅ Good
-   t('Invoice Summary');
-   t('Are you sure you want to delete this customer?');
+```tsx
+import { WangsUiI18nProvider } from '@wangs-ui/react-i18n';
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
 
-   // ❌ Bad — artificial dotted keys
-   t('invoice.summary.title');
-   ```
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <WangsUiI18nProvider defaultLocale="en" baseUrl={import.meta.env.VITE_API_URL || ''}>
+      <App />
+    </WangsUiI18nProvider>
+  </React.StrictMode>,
+);
+```
+
+---
+
+## 3. Translation Protocol with `useI18n()`
+
+The `@wangs-ui/react-i18n` package uses a Just-In-Time (JIT) translation architecture where natural English text strings serve as database keys.
+
+### A. Consumer-Level Translation for `ReactNode` Props (Mandatory)
+
+All user-facing text props in Wangs UI components (`placeholder`, `label`, `emptyMessage`, `header`, `tooltip`, etc.) are typed as `ReactNode` and rendered as-is. Components do **NOT** automatically translate custom strings. Translation **MUST** be called at the application/consumer level:
+
+```tsx
+import { useI18n } from '@wangs-ui/react-i18n';
+import Button from '@wangs-ui/react-core/primitive/button';
+import DataTable from '@wangs-ui/react-core/primitive/datatable';
+import Select from '@wangs-ui/react-core/primitive/select';
+
+export function OrderList() {
+  const { t } = useI18n();
+
+  return (
+    <div>
+      <Select placeholder={t('Search category...')} />
+      <DataTable emptyMessage={t('No orders found')} />
+      <Button label={t('Create new order')} />
+    </div>
+  );
+}
+```
+
+### B. Natural English Sentence Keys
 
-2. **Dynamic Variables in Double Braces (`{{var}}`)**:
-   Pass variables as an object using `{{variableName}}` interpolation:
+Always write full, natural English sentences as translation keys. Never use artificial dotted namespace keys:
 
-   ```tsx
-   // ✅ Good
-   t('Welcome back, {{name}}!', { name: user.name });
+```tsx
+// ✅ Good — Natural English
+t('Invoice Summary');
+t('Are you sure you want to delete this customer?');
 
-   // ❌ Bad — string concatenation breaks translation word order
-   t('Welcome back, ') + user.name + '!';
-   ```
+// ❌ Bad — Artificial dotted keys
+t('invoice.summary.title');
+t('dialog.delete.customer.confirm');
+```
+
+### C. Named Variable Interpolation (Single Braces `{var}`)
+
+Pass interpolation values inside a plain object using descriptive named variables. This provides crucial semantic context for AI translation engines:
+
+```tsx
+// ✅ Good — Named variables provide context
+t('Upload {count} files to {groupName}', { count: 5, groupName: 'Marketing' });
+t('Welcome back, {userName}!', { userName: user.name });
+
+// ❌ Bad — Concatenation or positional arguments
+t('Welcome back, ' + user.name);
+t('Upload {0} files to {1}', 5, 'Marketing');
+```
 
-3. **Pluralization with ICU Formats**:
-   Use ICU plural format for quantity-dependent sentences:
+### D. ICU Pluralization & Zero-State (`=0`)
 
-   ```tsx
-   t('{count, plural, =0 {No items selected} one {# item selected} other {# items selected}}', {
-     count: selectedCount,
-   });
-   ```
+Always handle singular, plural, and zero states directly within ICU MessageFormat strings. Do **NOT** use JavaScript ternary operators:
 
-4. **Runtime Locale Switching**:
-   Use the `useI18n()` hook to read or update active language:
-   ```tsx
-   import { useI18n } from '@wangs-ui/react-i18n';
+```tsx
+// ✅ Good — Clean ICU pluralization with zero-state handling
+t('{count, plural, =0 {No items selected} one {1 item selected} other {{count} items selected}}', {
+  count: selectedCount,
+});
 
-   const { t, currentLocale, setLocale } = useI18n();
-   ```
+// ❌ Bad — Manual JS branching
+selectedCount === 0
+  ? t('No items selected')
+  : selectedCount === 1
+    ? t('1 item selected')
+    : t('{count} items selected', { count: selectedCount });
+```
+
+### E. Rich Text / Annotated Strings
+
+Use standard supported HTML tags (`<a>`, `<b>`, `<i>`, `<u>`, `<s>`, `<br/>`, `<sub>`, `<sup>`, `<code>`, `<mark>`) for inline styling. Tags are automatically parsed into React elements without custom regex or string manipulation:
+
+```tsx
+import Link from '@wangs-ui/foundation/theme/Link';
+
+t('You have selected <b>{count} items</b>. Click <a>here</a> to review.', {
+  count: selectedCount,
+  a: (chunks) => <Link href="/review">{chunks}</Link>,
+});
+```
+
+---
+
+## 4. Locale Formatting Protocol with `useLocaleFormatter()`
+
+For locale-aware formatting of dates, relative times, currencies, numbers, and display names, use the dedicated `useLocaleFormatter()` hook. All functions automatically adapt to the active locale without triggering backend database requests:
+
+```tsx
+import { useLocaleFormatter } from '@wangs-ui/react-i18n';
+
+export function SummaryCard({ updatedAt, amount, count }: Props) {
+  const {
+    formatDate,
+    formatRelativeTime,
+    formatCurrency,
+    formatNumber,
+    formatDisplayName,
+    formatList,
+    truncateText,
+  } = useLocaleFormatter();
+
+  return (
+    <div>
+      {/* Date formatting with Go tokens or date-fns tokens, and timezone */}
+      <p>{formatDate(new Date(), 'dd MMMM yyyy, HH:mm', 'Asia/Jakarta')}</p>
+
+      {/* Relative time */}
+      <p>{formatRelativeTime(updatedAt)}</p>
+
+      {/* Currency formatting */}
+      <p>{formatCurrency(amount, 'IDR')}</p>
+
+      {/* Number formatting with locale grouping */}
+      <p>{formatNumber(count)}</p>
+
+      {/* ISO code to localized name */}
+      <p>{formatDisplayName('id', 'language')}</p>
+
+      {/* Localized list */}
+      <p>{formatList(['Finance', 'Operations', 'IT'])}</p>
+
+      {/* Emoji & multi-byte safe text truncation */}
+      <p>{truncateText('Long product description with emojis 🚀', 20)}</p>
+    </div>
+  );
+}
+```
+
+> [!NOTE]
+> Formatters MUST NOT be called as standalone `t()` keys (e.g. `t(formatRelativeTime(date))`). Instead, pass the formatted result as a named variable:
+>
+> ```tsx
+> const { t } = useI18n();
+> const { formatRelativeTime } = useLocaleFormatter();
+> const label = t('Updated {time}', { time: formatRelativeTime(updatedAt) });
+> ```
+
+---
+
+## 5. Language Switching UI Integration
+
+Connect the Wangs UI `LanguageSwitcher` primitive directly with `useI18n()` state:
+
+```tsx
+import LanguageSwitcher from '@wangs-ui/react-core/primitive/languageswitcher';
+import { useI18n } from '@wangs-ui/react-i18n';
+
+export function HeaderLanguageSwitcher() {
+  const { locale, setLocale, languageOptions } = useI18n();
+
+  return (
+    <LanguageSwitcher
+      options={languageOptions}
+      value={locale}
+      onChange={(code) => setLocale(code)}
+    />
+  );
+}
+```
 
 ---
 
-## 3. Mandatory Implementation Rules
+## 6. Strict Behavioral Constraints (MUST NOT)
 
-1. **Inspect Localized Components via MCP**: Query `currencyinput` and `datepicker` documentation before binding locale-sensitive formatters.
-2. **Never Hardcode User-Facing Text**: Every visible label, placeholder, dialog title, tooltip, and error message in the application must pass through `t()`.
-3. **Keep Context Intact**: Do not split sentences into separate phrases across JSX elements; translate the full sentence as a single unit.
+- **NO Formatters Destructured from `useI18n()`:** Formatters are isolated in `useLocaleFormatter()`. Never attempt to import `formatDate` or `formatCurrency` from `useI18n()`.
+- **NO String Concatenation in `t()` Keys:** Never concatenate strings or use dynamic template literals (e.g. `t('Hello ' + user.name)` or ``t(`Hello ${user.name}`)``). This creates infinite distinct keys in the translation database and prevents caching.
+- **NO Manual Zero-State JavaScript Branching:** Always use ICU `=0` syntax inside a single plural key.
+- **NO Dotted Artificial Translation Keys:** Never use dotted keys like `t('app.header.title')`. Use natural English sentences.
+- **NO Custom Markdown Formatting Symbols:** Do not use `*bold*` or `_italic_` in translation keys. Use valid HTML tags like `<b>bold</b>`.
+- **NO Hardcoded Static Translation Dictionaries:** Do not bundle static translation files (`id.json`, `zh.json`). The JIT backend broker manages translations dynamically.
+- **NO Unnecessary English Key Modifications:** Minor typos or punctuation changes in keys create orphaned entries in the translation backend and trigger new AI translation costs.