@wangs-ui/skills 1.0.1

package/dist/bin.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { i as listSkills, n as updateSkills, r as addSkills, t as removeSkills } from "./src-BsIrKDsV.js";
+import path from "node:path";
+import { parseArgs } from "node:util";
+//#region bin.ts
+var HELP_TEXT = `
+\x1b[1m\x1b[36m🚀 Wangs UI Skills CLI\x1b[0m
+Install, update, and manage modular AI agent skills for Wangs UI React applications.
+
+\x1b[1mUsage:\x1b[0m
+  npx @wangs-ui/skills [command] [options]
+  wangs-ui-skills [command] [options]
+
+\x1b[1mCommands:\x1b[0m
+  \x1b[36mlist\x1b[0m                      List all available and installed skills
+  \x1b[36madd\x1b[0m [skills...]           Install specified skills (interactive if none provided)
+  \x1b[36mupdate\x1b[0m [skills...]        Update installed skills to latest versions
+  \x1b[36mremove\x1b[0m <skills...>        Remove specified skills from agent environment
+
+\x1b[1mOptions:\x1b[0m
+  --target <dir>            Target directory (default: current working directory)
+  -h, --help                Show help message
+  -v, --version             Show version
+
+\x1b[1mExamples:\x1b[0m
+  npx @wangs-ui/skills list
+  npx @wangs-ui/skills add create-form
+  npx @wangs-ui/skills add wangs-ui-components data-table dialog-modal
+  npx @wangs-ui/skills update
+  npx @wangs-ui/skills remove create-form
+`;
+async function main() {
+	const args = process.argv.slice(2);
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(HELP_TEXT);
+		return;
+	}
+	if (args.includes("--version") || args.includes("-v")) {
+		console.log("1.0.0");
+		return;
+	}
+	const parsed = parseArgs({
+		args,
+		options: { target: { type: "string" } },
+		allowPositionals: true,
+		strict: false
+	});
+	const baseDir = parsed.values.target ? path.resolve(parsed.values.target) : process.cwd();
+	const { positionals } = parsed;
+	const command = positionals[0] || "list";
+	const skillArgs = positionals.slice(1);
+	switch (command) {
+		case "list":
+		case "ls":
+			listSkills(baseDir);
+			break;
+		case "add":
+		case "install":
+		case "i":
+			await addSkills(skillArgs, baseDir);
+			break;
+		case "update":
+		case "up":
+			updateSkills(skillArgs, baseDir);
+			break;
+		case "remove":
+		case "rm":
+		case "delete":
+			removeSkills(skillArgs, baseDir);
+			break;
+		default:
+			console.log(`\x1b[31mUnknown command: "${command}"\x1b[0m`);
+			console.log(HELP_TEXT);
+			process.exit(1);
+	}
+}
+try {
+	await main();
+} catch (err) {
+	console.error("Error running @wangs-ui/skills:", err);
+	process.exit(1);
+}
+//#endregion
+export {};

package/dist/index.js

@@ -0,0 +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-BsIrKDsV.js";
+export { addSkills, getAgentSkillDirs, getInstalledSkills, getSkill, installSkill, isSkillInstalled, listSkills, loadAllSkills, removeSkill, removeSkills, updateSkills };

package/dist/skills/create-form/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: create-form
+description: Architecture, validation workflows, and MCP discovery protocol for building forms and input controls with @wangs-ui/react-core.
+---
+
+# Skill: Form Architecture & Validation Workflows
+
+Use this skill when building forms, data entry panels, settings pages, or multipart forms in Wangs UI applications.
+
+---
+
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
+
+Do **NOT** hardcode or guess prop names, field configurations, or validation options. Retrieve active component definitions and live implementation stories directly from MCP:
+
+### Inspect Component & Form Contracts:
+
+```json
+get-documentation({ "id": "form" })
+get-documentation({ "id": "field" })
+get-documentation({ "id": "input" })
+get-documentation({ "id": "numberinput" })
+get-documentation({ "id": "select" })
+get-documentation({ "id": "multiselect" })
+get-documentation({ "id": "datepicker" })
+get-documentation({ "id": "fileupload" })
+```
+
+### Inspect Live Story Implementations:
+
+```json
+get-documentation-for-story({ "id": "form", "storyName": "Default" })
+get-documentation-for-story({ "id": "field", "storyName": "Default" })
+get-documentation-for-story({ "id": "select", "storyName": "Basic" })
+get-documentation-for-story({ "id": "datepicker", "storyName": "Default" })
+get-documentation-for-story({ "id": "fileupload", "storyName": "Default" })
+```
+
+### Inspect Knowledge Graph & Usages:
+
+```json
+query_graph({ "query": "useFormControl" })
+query_graph({ "query": "Field" })
+```
+
+---
+
+## 2. Form Architecture & State Principles
+
+1. **State & Control**:
+   - Standard REST payload forms use `useFormControl` with JSON mode.
+   - Multipart file upload workflows use `useFormControl` with FormData mode.
+2. **Field Composition**:
+   - Form inputs are wrapped with `<Field>` layout containers for unified label, tooltip, helper text, and error rendering.
+   - Exact props, slot rendering functions, and field binding options must be retrieved via MCP (`get-documentation({ "id": "field" })`).
+3. **Server Validation Error Mapping**:
+   - Backend validation responses (e.g. `422 Unprocessable Entity`) are mapped back into the form instance via `formControl.setError()`.
+4. **Submission Lifecycle**:
+   - In-flight network requests should manage loading state on submit actions and prevent accidental reset during mutations.
+
+---
+
+## 3. Mandatory Implementation Rules
+
+1. **Always Query MCP First**: Never guess input props or event signatures; obtain the exact types from `get-documentation`.
+2. **Strict Subpath Imports**: All components must be imported via their granular subpath (`@wangs-ui/react-core/primitive/*`, `@wangs-ui/form`).
+3. **Translate All Visible Strings**: Every field label, placeholder, helper text, and error message must be wrapped in `t('...')` from `@wangs-ui/react-i18n`.

package/dist/skills/data-table/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: data-table
+description: Architecture, workflows, and MCP discovery protocol for building DataTables with sorting, pagination, filtering, selection, and export.
+---
+
+# Skill: DataTable Architecture & Integration Workflows
+
+Use this skill when implementing data grids, server-paginated tables, filterable listing views, or batch management interfaces with `@wangs-ui/react-core`.
+
+---
+
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
+
+Do **NOT** guess table prop names or hardcode table structures. Query the MCP server dynamically to inspect exact TypeScript signatures, live story implementations, and companion controls:
+
+### Inspect Component Contracts:
+
+```json
+get-documentation({ "id": "datatable" })
+get-documentation({ "id": "exportbutton" })
+get-documentation({ "id": "filtercontainer" })
+get-documentation({ "id": "bulkactionbutton" })
+```
+
+### Inspect Live Story Implementations:
+
+```json
+get-documentation-for-story({ "id": "datatable", "storyName": "Basic" })
+get-documentation-for-story({ "id": "datatable", "storyName": "ServerPagination" })
+get-documentation-for-story({ "id": "datatable", "storyName": "Sortable" })
+get-documentation-for-story({ "id": "datatable", "storyName": "MultipleSelection" })
+get-documentation-for-story({ "id": "datatable", "storyName": "CustomColumn" })
+get-documentation-for-story({ "id": "exportbutton", "storyName": "WithTable" })
+```
+
+### Inspect Knowledge Graph & Usages:
+
+```json
+query_graph({ "query": "DataTable" })
+query_graph({ "query": "useDataTableFetch" })
+```
+
+---
+
+## 2. Core Architecture & Mental Model
+
+The Wangs UI `DataTable` is built on a modular, headless-first architecture:
+
+1. **Declarative Column Definitions (`TableColumn<T>[]`)**:
+   Columns are configured as typed array objects, not as JSX children. Check `get-documentation({ "id": "datatable" })` for column field types.
+2. **Table Instance Hook (`useDataTable`)**:
+   Coordinates table state (sorting, pagination, selection, column ordering, pinning, visibility).
+3. **Data Fetching Hook (`useDataTableFetch`)**:
+   Feeds server-side data, handles loading indicators, manages query parameters (`search`, `filter`, `sort`, `page`, `limit`), and debounces requests automatically.
+4. **Ecosystem Companions**:
+   - `FilterContainer` & `FilterToggleButton`: Filter popovers and faceted search.
+   - `ExportButton`: Client/server export to Excel, CSV, PDF, or Print.
+   - `BulkActionButton`: Contextual batch actions triggered when rows are selected.
+   - `CustomColumn`: User-controlled column ordering, visibility toggling, and pinning.
+
+---
+
+## 3. Mandatory Implementation Rules
+
+1. **Query MCP for Current Code Patterns**: Always run `get-documentation-for-story` for `datatable` before drafting code.
+2. **Strict Subpath Imports**: Import via `@wangs-ui/react-core/primitive/datatable` and companion primitive paths.
+3. **Always Translate Visible Copy**: All column header labels, empty state messages, and action button labels must be wrapped in `t('...')` from `@wangs-ui/react-i18n`.
+4. **Stable Row Identity**: Always configure a unique key identifier for stable selection and row identity.

package/dist/skills/dialog-modal/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: dialog-modal
+description: Patterns, overlay selection criteria, and MCP discovery protocol for Dialog, Modal, and DialogForm components in Wangs UI.
+---
+
+# Skill: Dialog, Modal & Overlay Workflows
+
+Use this skill when building interactive modals, create/edit dialog forms, destructive action confirmations, or slide-in overlay panels.
+
+---
+
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
+
+Do **NOT** guess overlay props, event names, or footer slots. Query the MCP server dynamically to inspect exact contracts and live story implementations:
+
+### Inspect Overlay Contracts:
+
+```json
+get-documentation({ "id": "dialog" })
+get-documentation({ "id": "dialogform" })
+get-documentation({ "id": "modal" })
+get-documentation({ "id": "toast" })
+```
+
+### Inspect Live Story Implementations:
+
+```json
+get-documentation-for-story({ "id": "dialog", "storyName": "Confirmation" })
+get-documentation-for-story({ "id": "dialogform", "storyName": "Default" })
+get-documentation-for-story({ "id": "modal", "storyName": "Default" })
+```
+
+### Inspect Knowledge Graph & Usages:
+
+```json
+query_graph({ "query": "Dialog" })
+query_graph({ "query": "DialogForm" })
+```
+
+---
+
+## 2. Overlay Selection Matrix
+
+| Component        | Primary Use Case                              | Key Characteristics                                                                   |
+| :--------------- | :-------------------------------------------- | :------------------------------------------------------------------------------------ |
+| **`Dialog`**     | Confirmations, alerts, simple detail previews | Standard `header`, `footer`, and body layout; built-in backdrop dimming.              |
+| **`DialogForm`** | Create/Edit forms embedded inside a dialog    | Built-in form submit/cancel action bar, dirty state tracking, and submit lifecycle.   |
+| **`Modal`**      | Slide-in drawers, complex custom viewports    | Headless overlay primitive with flexible animations, size variants, and drawer modes. |
+
+---
+
+## 3. Mandatory Implementation Rules
+
+1. **Query MCP for Current Code Patterns**: Always inspect `dialog`, `dialogform`, or `modal` stories via MCP before writing overlay code.
+2. **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`.
+3. **Prevent Dismissal During Async Mutations**: Guard the close handler so users cannot accidentally dismiss the dialog while a mutation request is in-flight.
+4. **Coordinate with Toast Notifications**: Trigger feedback toasts on successful creation, update, or deletion actions.
+5. **Translate All Overlay Copy**: All dialog titles, confirmation descriptions, and button labels must be localized using `t('...')` from `@wangs-ui/react-i18n`.

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

@@ -0,0 +1,232 @@
+---
+name: i18n-usage
+description: Comprehensive guidelines for application internationalization, JIT translations (t), ICU formatting, and locale-aware formatting with @wangs-ui/react-i18n.
+---
+
+# Skill: Application Internationalization & Formatting Protocol
+
+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. The MCP Discovery Protocol (Single Source of Truth)
+
+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:
+
+```json
+get-documentation({ "id": "languageswitcher" })
+get-documentation({ "id": "currencyinput" })
+get-documentation({ "id": "datepicker" })
+get-documentation({ "id": "select" })
+get-documentation({ "id": "datatable" })
+```
+
+### Inspect Live Story Implementations:
+
+```json
+get-documentation-for-story({ "id": "languageswitcher", "storyName": "Basic" })
+get-documentation-for-story({ "id": "currencyinput", "storyName": "Basic" })
+get-documentation-for-story({ "id": "datepicker", "storyName": "Default" })
+```
+
+---
+
+## 2. Root Provider Setup (`WangsUiI18nProvider`)
+
+Wrap the application root with `WangsUiI18nProvider` from `@wangs-ui/react-i18n` to enable dynamic JIT translations, versioned cache invalidation, and locale context:
+
+```tsx
+import { WangsUiI18nProvider } from '@wangs-ui/react-i18n';
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+
+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
+
+Always write full, natural English sentences as translation keys. Never use artificial dotted namespace keys:
+
+```tsx
+// ✅ Good — Natural English
+t('Invoice Summary');
+t('Are you sure you want to delete this customer?');
+
+// ❌ 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');
+```
+
+### D. ICU Pluralization & Zero-State (`=0`)
+
+Always handle singular, plural, and zero states directly within ICU MessageFormat strings. Do **NOT** use JavaScript ternary operators:
+
+```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,
+});
+
+// ❌ 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)}
+    />
+  );
+}
+```
+
+---
+
+## 6. Strict Behavioral Constraints (MUST NOT)
+
+- **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/skills/layout-navigation/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: layout-navigation
+description: Architecture, navigation hierarchies, and MCP discovery protocol for AppLayout, Sidebar, Breadcrumb, and Tabs in Wangs UI.
+---
+
+# Skill: Application Layout & Navigation Hierarchy
+
+Use this skill when constructing application shells, multi-level sidebars, page headers, breadcrumbs, or tabbed views with `@wangs-ui/react-core`.
+
+---
+
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
+
+Do **NOT** guess layout block slots, sidebar item interfaces, or breadcrumb props. Query the MCP server dynamically to inspect exact contracts and live story implementations:
+
+### Inspect Layout & Navigation Contracts:
+
+```json
+get-documentation({ "id": "applayout" })
+get-documentation({ "id": "sidebar" })
+get-documentation({ "id": "breadcrumb" })
+get-documentation({ "id": "tabs" })
+```
+
+### Inspect Live Story Implementations:
+
+```json
+get-documentation-for-story({ "id": "applayout", "storyName": "Default" })
+get-documentation-for-story({ "id": "sidebar", "storyName": "Default" })
+get-documentation-for-story({ "id": "breadcrumb", "storyName": "Default" })
+get-documentation-for-story({ "id": "tabs", "storyName": "Default" })
+```
+
+### Inspect Knowledge Graph & Usages:
+
+```json
+query_graph({ "query": "AppLayout" })
+query_graph({ "query": "Sidebar" })
+```
+
+---
+
+## 2. Layout Architecture & Mental Model
+
+1. **Top-Level App Shell (`AppLayout`)**:
+   Provides structured slots for `sidebar`, `header`, and main content view, handling responsive viewport scaling and mobile navigation overlays.
+2. **Hierarchical Menu (`Sidebar`)**:
+   Renders single and nested navigation items, active route indicators, collapsible state, and notification badges.
+3. **Breadcrumb Trail (`Breadcrumb`)**:
+   Maintains clear navigational hierarchy on page headers.
+4. **Tabbed Sub-Views (`Tabs`)**:
+   Organizes complex entity detail views or multi-section settings into distinct tabbed panels.
+
+---
+
+## 3. Mandatory Implementation Rules
+
+1. **Query MCP for Current Code Patterns**: Inspect `applayout` and `sidebar` stories via MCP before assembling the layout.
+2. **Strict Subpath Imports**: Import layout blocks via `@wangs-ui/react-core/blocks/*` and primitives via `@wangs-ui/react-core/primitive/*`.
+3. **Consistent Spacing Grid**: Use standard container padding (`p-6` or `p-xxl`) across page contents.
+4. **Page Hierarchy Alignment**: Every page view inside the layout must provide a clear `.heading-1` hierarchy and synchronized breadcrumbs.
+5. **Translate Navigation Labels**: Wrap all sidebar item labels and breadcrumb texts in `t('...')` from `@wangs-ui/react-i18n`.