@wangs-ui/skills 1.0.36

package/skills/data-table/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: data-table
+description: Real-world patterns for building full CRUD DataTables with server pagination, search filters, batch actions, and confirmation modals.
+---
+
+# Skill: Real-World DataTable & Filter Workflows
+
+Use this skill when building administrative grids, filtered listing pages, or management dashboards with `@wangs-ui/react-core`.
+
+---
+
+## 1. MCP Inspection Step (Before Building Table)
+
+Query the MCP server to inspect supported features and slots:
+
+- `get-documentation({ id: "datatable" })` — Check `paginator`, `lazy`, `onPage`, `onSort`, `selectionMode`, and `dataKey`.
+- `get-documentation({ id: "column" })` — Check `body` template, `sortable`, `frozen`, and `headerStyle`.
+- `get-documentation({ id: "tag" })` — Check severity colors for status pill badges (`success`, `warning`, `danger`, `info`).
+
+---
+
+## 2. Recipe: Full CRUD Data Grid with Filter Toolbar & Batch Actions
+
+```tsx
+import React, { useState } from 'react';
+import DataTable, { Column } from '@wangs-ui/react-core/primitive/datatable';
+import Button from '@wangs-ui/react-core/primitive/button';
+import InputText from '@wangs-ui/react-core/primitive/inputtext';
+import Select from '@wangs-ui/react-core/primitive/select';
+import Tag from '@wangs-ui/react-core/primitive/tag';
+import Dialog from '@wangs-ui/react-core/primitive/dialog';
+import Card from '@wangs-ui/react-core/primitive/card';
+import { useI18n } from '@wangs-ui/react-i18n';
+import { SearchLine, DeleteBin6Line, EditLine, AddLine } from '@wangs-ui/react-icons';
+
+interface CustomerRecord {
+  id: string;
+  name: string;
+  email: string;
+  status: 'active' | 'pending' | 'suspended';
+  createdAt: string;
+}
+
+export default function CustomerManagementView() {
+  const { t } = useI18n();
+  const [records, setRecords] = useState<CustomerRecord[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [searchQuery, setSearchQuery] = useState('');
+  const [selectedStatus, setSelectedStatus] = useState<string | null>(null);
+  const [selectedRows, setSelectedRows] = useState<CustomerRecord[]>([]);
+  const [deleteTarget, setDeleteTarget] = useState<CustomerRecord | null>(null);
+
+  // Status Badge Template
+  const statusTemplate = (row: CustomerRecord) => {
+    const severityMap: Record<string, 'success' | 'warning' | 'danger'> = {
+      active: 'success',
+      pending: 'warning',
+      suspended: 'danger',
+    };
+    return <Tag value={t(row.status)} severity={severityMap[row.status] || 'info'} />;
+  };
+
+  // Row Actions Template
+  const actionsTemplate = (row: CustomerRecord) => (
+    <div className="flex items-center gap-xs">
+      <Button
+        variant="text"
+        icon={<EditLine />}
+        aria-label={t('Edit')}
+        onClick={() => console.log('Edit', row.id)}
+      />
+      <Button
+        variant="text"
+        severity="danger"
+        icon={<DeleteBin6Line />}
+        aria-label={t('Delete')}
+        onClick={() => setDeleteTarget(row)}
+      />
+    </div>
+  );
+
+  return (
+    <Card className="flex flex-col gap-m p-6">
+      {/* 1. Filter & Search Toolbar */}
+      <div className="flex flex-wrap items-center justify-between gap-s">
+        <div className="flex flex-wrap items-center gap-s">
+          <InputText
+            value={searchQuery}
+            onChange={(e) => setSearchQuery(e.target.value)}
+            placeholder={t('Search customer...')}
+            className="w-64"
+          />
+          <Select
+            value={selectedStatus}
+            options={[
+              { label: t('All Statuses'), value: null },
+              { label: t('Active'), value: 'active' },
+              { label: t('Pending'), value: 'pending' },
+              { label: t('Suspended'), value: 'suspended' },
+            ]}
+            onChange={(e) => setSelectedStatus(e.value)}
+            placeholder={t('Filter status')}
+          />
+        </div>
+
+        <Button label={t('Add Customer')} icon={<AddLine />} severity="primary" />
+      </div>
+
+      {/* 2. Batch Selection Action Bar */}
+      {selectedRows.length > 0 && (
+        <div className="flex items-center justify-between rounded bg-primary-50 px-4 py-2 text-primary-900">
+          <span className="p font-medium">
+            {t('{{count}} items selected', { count: selectedRows.length })}
+          </span>
+          <Button
+            size="small"
+            severity="danger"
+            label={t('Delete Selected')}
+            icon={<DeleteBin6Line />}
+            onClick={() => console.log('Batch delete', selectedRows)}
+          />
+        </div>
+      )}
+
+      {/* 3. Paginated DataTable */}
+      <DataTable
+        value={records}
+        loading={loading}
+        selection={selectedRows}
+        onSelectionChange={(e) => setSelectedRows(e.value)}
+        dataKey="id"
+        paginator
+        rows={10}
+        rowsPerPageOptions={[10, 25, 50]}
+        emptyMessage={t('No customers found')}
+      >
+        <Column selectionMode="multiple" headerStyle={{ width: '3rem' }} />
+        <Column field="name" header={t('Customer Name')} sortable />
+        <Column field="email" header={t('Email')} sortable />
+        <Column field="status" header={t('Status')} body={statusTemplate} sortable />
+        <Column header={t('Actions')} body={actionsTemplate} headerStyle={{ width: '6rem' }} />
+      </DataTable>
+
+      {/* 4. Delete Confirmation Dialog */}
+      <Dialog
+        visible={!!deleteTarget}
+        onHide={() => setDeleteTarget(null)}
+        header={t('Delete Customer')}
+        footer={
+          <div className="flex justify-end gap-xs">
+            <Button variant="text" label={t('Cancel')} onClick={() => setDeleteTarget(null)} />
+            <Button
+              severity="danger"
+              label={t('Delete')}
+              onClick={() => {
+                // Execute delete API
+                setDeleteTarget(null);
+              }}
+            />
+          </div>
+        }
+      >
+        <p className="p">
+          {t('Are you sure you want to delete {{name}}?', { name: deleteTarget?.name })}
+        </p>
+      </Dialog>
+    </Card>
+  );
+}
+```
+
+---
+
+## 3. Mandatory Best Practices
+
+1. **Always Supply `dataKey`**: Never enable row selection without `dataKey="id"`.
+2. **Translate All Headers & Messages**: Pass table headers and empty state messages into `t()`.
+3. **Control Batch Action Appearance**: Show batch action banner only when `selectedRows.length > 0`.

package/skills/dialog-modal/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: dialog-modal
+description: Real-world patterns for modal forms, async confirmation workflows, and multi-step dialogs with Wangs UI Dialog and Modal components.
+---
+
+# Skill: Real-World Dialog & Modal Workflows
+
+Use this skill when building interactive modals, create/edit modal forms, destructive action confirmations, or slide-in overlay panels.
+
+---
+
+## 1. MCP Inspection Step (Before Implementing Overlays)
+
+Query the MCP server to check overlay configuration and animation options:
+
+- `get-documentation({ id: "dialog" })` — Check `header`, `footer`, `visible`, `onHide`, `modal`, and `dismissableMask`.
+- `get-documentation({ id: "modal" })` — Check fullscreen modes, size variants, and slide-in drawer options.
+- `get-documentation({ id: "toast" })` — Check severity toasts (`success`, `error`, `info`, `warn`) to trigger after modal actions.
+
+---
+
+## 2. Recipe: Create/Edit Form inside a Modal Dialog
+
+This real-world recipe coordinates a modal wrapper with an embedded `@wangs-ui/form`, handles saving state, prevents accidental dismiss while saving, and resets state upon close:
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import Dialog from '@wangs-ui/react-core/primitive/dialog';
+import Button from '@wangs-ui/react-core/primitive/button';
+import InputText from '@wangs-ui/react-core/primitive/inputtext';
+import { Form, Field } from '@wangs-ui/react-core';
+import { useFormControl } from '@wangs-ui/form';
+import { useI18n } from '@wangs-ui/react-i18n';
+
+interface EditItemModel {
+  title: string;
+  code: string;
+}
+
+interface ItemModalProps {
+  visible: boolean;
+  item?: EditItemModel | null;
+  onHide: () => void;
+  onSaved: (item: EditItemModel) => void;
+}
+
+export default function ItemFormModal({ visible, item, onHide, onSaved }: ItemModalProps) {
+  const { t } = useI18n();
+  const formControl = useFormControl<EditItemModel>({ type: 'json' });
+  const [saving, setSaving] = useState(false);
+
+  // Sync form values when modal opens or item changes
+  useEffect(() => {
+    if (visible) {
+      formControl.reset(item || { title: '', code: '' });
+    }
+  }, [visible, item]);
+
+  const handleFormSubmit = async (values: EditItemModel) => {
+    setSaving(true);
+    try {
+      // Execute API call: await api.save(values);
+      onSaved(values);
+      onHide();
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const footerActions = (
+    <div className="flex justify-end gap-xs">
+      <Button type="button" variant="text" label={t('Cancel')} onClick={onHide} disabled={saving} />
+      <Button
+        type="submit"
+        form="modal-item-form"
+        label={item ? t('Save Changes') : t('Create Item')}
+        severity="primary"
+        loading={saving}
+      />
+    </div>
+  );
+
+  return (
+    <Dialog
+      visible={visible}
+      onHide={() => !saving && onHide()}
+      header={item ? t('Edit Item') : t('New Item')}
+      footer={footerActions}
+      style={{ width: '450px' }}
+      modal
+    >
+      <Form
+        id="modal-item-form"
+        control={formControl}
+        onSubmit={handleFormSubmit}
+        className="flex flex-col gap-m pt-xs"
+      >
+        <Field<string>
+          name="title"
+          label={t('Item Title')}
+          required
+          rules={{ required: t('Title is required') }}
+        >
+          {(field) => (
+            <InputText {...field} placeholder={t('Enter title')} value={field.value || ''} />
+          )}
+        </Field>
+
+        <Field<string>
+          name="code"
+          label={t('Item Code')}
+          required
+          rules={{ required: t('Code is required') }}
+        >
+          {(field) => (
+            <InputText {...field} placeholder={t('e.g. SKU-100')} value={field.value || ''} />
+          )}
+        </Field>
+      </Form>
+    </Dialog>
+  );
+}
+```
+
+---
+
+## 3. Mandatory Best Practices
+
+1. **Decouple Submit Button from Form Body**: Use `form="modal-item-form"` on the submit button inside `footer` so actions stay neatly aligned in the footer bar.
+2. **Prevent Close During Mutation**: Guard `onHide={() => !saving && onHide()}` to prevent accidental dismissal during in-flight network requests.
+3. **Always Reset on Open**: Sync initial values in an effect keyed on `visible`.

package/skills/i18n-usage/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: i18n-usage
+description: Real-world internationalization, currency formatting, localized date pickers, and plural interpolation with @wangs-ui/react-i18n.
+---
+
+# Skill: Application Internationalization & Formatting
+
+Use this skill when handling multi-language UI, currency inputs, localized dates, or dynamic sentence translations.
+
+---
+
+## 1. MCP Inspection Step (Before Localizing Complex Components)
+
+Query the MCP server to inspect component-specific localization props:
+
+- `get-documentation({ id: "currencyinput" })` — Check currency prefix, locale formatting, and min/max constraints.
+- `get-documentation({ id: "datepicker" })` — Check month/day names, firstDayOfWeek, and dateFormat options.
+- `get-documentation({ id: "languageswitcher" })` — Check language picker dropdown variants.
+
+---
+
+## 2. Recipe: Localized Currency, Date, and Pluralization Flow
+
+```tsx
+import React, { useState } from 'react';
+import Card from '@wangs-ui/react-core/primitive/card';
+import CurrencyInput from '@wangs-ui/react-core/primitive/currencyinput';
+import DatePicker from '@wangs-ui/react-core/primitive/datepicker';
+import { useI18n } from '@wangs-ui/react-i18n';
+
+export default function InvoiceSummary() {
+  const { t, currentLocale, setLocale } = useI18n();
+  const [amount, setAmount] = useState<number | null>(1500000);
+  const [dueDate, setDueDate] = useState<Date | null>(new Date());
+  const itemCount = 5;
+
+  return (
+    <Card className="flex flex-col gap-m p-6">
+      <div className="flex items-center justify-between">
+        <h2 className="heading-2">{t('Invoice Summary')}</h2>
+        {/* Language selector toggle */}
+        <button
+          className="text-primary-600 underline text-sm"
+          onClick={() => setLocale(currentLocale === 'en' ? 'id' : 'en')}
+        >
+          {currentLocale === 'en' ? 'Bahasa Indonesia' : 'English'}
+        </button>
+      </div>
+
+      {/* 1. Currency Formatting Input */}
+      <div className="flex flex-col gap-xs">
+        <label className="heading-4">{t('Total Amount')}</label>
+        <CurrencyInput
+          value={amount}
+          onValueChange={(e) => setAmount(e.value ?? null)}
+          currency={currentLocale === 'id' ? 'IDR' : 'USD'}
+          locale={currentLocale === 'id' ? 'id-ID' : 'en-US'}
+        />
+      </div>
+
+      {/* 2. Localized Date Picker */}
+      <div className="flex flex-col gap-xs">
+        <label className="heading-4">{t('Payment Due Date')}</label>
+        <DatePicker
+          value={dueDate}
+          onChange={(e) => setDueDate(e.value as Date)}
+          dateFormat={currentLocale === 'id' ? 'dd/mm/yy' : 'mm/dd/yy'}
+          showIcon
+        />
+      </div>
+
+      {/* 3. Parameterized Translation */}
+      <p className="p text-secondary-600">
+        {t('Invoice includes {{count}} billed line items.', { count: itemCount })}
+      </p>
+    </Card>
+  );
+}
+```
+
+---
+
+## 3. Mandatory Translation Rules
+
+1. **Sentence Keys in Natural English**: Always write `t('Invoice Summary')` instead of artificial dotted paths like `t('invoice.summary.title')`.
+2. **Dynamic Variables in Double Braces**: Always use `t('Hello, {{name}}', { name })`.
+3. **No Concatenation**: Never write `t('Total:') + ' ' + total`. Use `t('Total: {{total}}', { total })`.

package/skills/layout-navigation/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: layout-navigation
+description: Guidelines and patterns for page layout, sidebar navigation, breadcrumbs, and tabs using Wangs UI layout blocks.
+---
+
+# Skill: Layout & Navigation Structure
+
+Use this skill when constructing application shells, multi-level sidebars, page headers, breadcrumbs, or tabbed views with `@wangs-ui/react-core`.
+
+---
+
+## 1. App Shell Pattern
+
+```tsx
+import React from 'react';
+import AppLayout from '@wangs-ui/react-core/blocks/applayout';
+import Sidebar from '@wangs-ui/react-core/blocks/sidebar';
+import Breadcrumb from '@wangs-ui/react-core/primitive/breadcrumb';
+import { HomeLine, UserLine, SettingsLine } from '@wangs-ui/react-icons';
+import { useI18n } from '@wangs-ui/react-i18n';
+
+export default function MainAppShell({ children }: { children: React.ReactNode }) {
+  const { t } = useI18n();
+
+  const navigationItems = [
+    { label: t('Dashboard'), icon: <HomeLine />, href: '/dashboard' },
+    { label: t('Users'), icon: <UserLine />, href: '/users' },
+    { label: t('Settings'), icon: <SettingsLine />, href: '/settings' },
+  ];
+
+  return (
+    <AppLayout
+      sidebar={<Sidebar items={navigationItems} />}
+      header={
+        <header className="flex h-14 items-center justify-between border-b border-secondary-200 px-6">
+          <Breadcrumb model={[{ label: t('Home') }, { label: t('Dashboard') }]} />
+        </header>
+      }
+    >
+      <main className="p-6">{children}</main>
+    </AppLayout>
+  );
+}
+```
+
+---
+
+## 2. Best Practices
+
+1. **Page Title & Breadcrumb Alignment**:
+   Every page view inside the layout should provide clear `.heading-1` hierarchy and synchronized breadcrumbs.
+2. **Spacing Grid Consistency**:
+   Use consistent outer container padding (`p-6` / `p-xxl`) across views.
+3. **Tabbed Subviews**:
+   When separating complex forms or detail views, use `<Tabs>` component with controlled tab index.
+
+---
+
+## 3. MCP Navigation & Block Inspection
+
+To inspect complete navigation options, badge counters, collapsible sidebars, or responsive header controls:
+
+- Call MCP tool `get-documentation({ id: "sidebar" })` or `get-documentation({ id: "breadcrumb" })` to view full configuration options and live stories.

package/skills/wangs-ui-components/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: wangs-ui-components
+description: Foundational rules, subpath imports, design tokens, and the MCP Discovery Protocol for building React apps with Wangs UI.
+---
+
+# Skill: Wangs UI Component Fundamentals & MCP Protocol
+
+Use this skill whenever you write or modify UI components using Wangs UI (`@wangs-ui/react-core`, `@wangs-ui/react-icons`, `@wangs-ui/react-presets`).
+
+---
+
+## 1. The MCP Discovery Protocol (Mandatory Before Writing Code)
+
+Do **NOT** guess component props, Pass-Through (`pt`) slots, or event names. Follow this discovery protocol:
+
+```mermaid
+graph TD
+    A[Identify Component Needed] --> B[Call get-documentation id]
+    B --> C{Need live story / variant?}
+    C -->|Yes| D[Call get-documentation-for-story]
+    C -->|No| E[Check Graphify: query_graph]
+    D --> E
+    E --> F[Implement Component with Subpath Imports]
+```
+
+1. **Step 1: Inspect Props & Types**:
+   Call `get-documentation({ id: "<component-name>" })` (e.g. `button`, `inputtext`, `datatable`) to get the exact prop interfaces, severity variants, and sizes.
+2. **Step 2: Inspect Live Usage & Slots**:
+   Call `get-documentation-for-story({ id: "<component-name>", storyName: "<variant>" })` to view how props, icons, and pass-through (`pt`) classes are composed in real code.
+3. **Step 3: Inspect Codebase Relationships**:
+   Call `query_graph({ query: "<ComponentName>" })` to see how other parts of the monorepo compose this component.
+
+---
+
+## 2. Subpath Modular Imports (Mandatory)
+
+Always import via specific subpaths to guarantee tree-shaking and avoid bundling entire packages:
+
+```tsx
+// Primitives
+import Button from '@wangs-ui/react-core/primitive/button';
+import Card from '@wangs-ui/react-core/primitive/card';
+import InputText from '@wangs-ui/react-core/primitive/inputtext';
+import Select from '@wangs-ui/react-core/primitive/select';
+import Tag from '@wangs-ui/react-core/primitive/tag';
+
+// Providers & Hooks
+import { WangsUiProvider } from '@wangs-ui/react-core/api';
+import { useI18n } from '@wangs-ui/react-i18n';
+
+// Icons
+import { SearchLine, AddLine, DeleteBin6Line, CheckLine } from '@wangs-ui/react-icons';
+```
+
+---
+
+## 3. Strict Primitive Substitution Rule
+
+Never write raw HTML when a Wangs UI primitive exists:
+
+| Forbidden Raw HTML        | Mandatory Wangs UI Component | Subpath Import                               |
+| :------------------------ | :--------------------------- | :------------------------------------------- |
+| `<button>`                | `Button`                     | `@wangs-ui/react-core/primitive/button`      |
+| `<input type="text">`     | `InputText`                  | `@wangs-ui/react-core/primitive/inputtext`   |
+| `<input type="number">`   | `InputNumber`                | `@wangs-ui/react-core/primitive/inputnumber` |
+| `<input type="checkbox">` | `Checkbox`                   | `@wangs-ui/react-core/primitive/checkbox`    |
+| `<select>`                | `Select`                     | `@wangs-ui/react-core/primitive/select`      |
+| `<dialog>` / modal        | `Dialog` / `Modal`           | `@wangs-ui/react-core/primitive/dialog`      |
+| `<table>`                 | `DataTable`                  | `@wangs-ui/react-core/primitive/datatable`   |
+| Container box             | `Card`                       | `@wangs-ui/react-core/primitive/card`        |
+| Pill badge                | `Tag` / `Badge`              | `@wangs-ui/react-core/primitive/tag`         |
+
+---
+
+## 4. Typography Scale & 4px Spacing Tokens
+
+### Typography Helper Classes
+
+- `.heading-1` — Page title (22px, 600)
+- `.heading-2` — Section / Card title (18px, 600)
+- `.heading-3` — Sub-header (16px, 500)
+- `.heading-4` — Field label (14px, 500)
+- `.heading-5` — Small group header (12px, 600)
+- `.p` — Body copy (12px, 500)
+
+### 4px Spacing Tokens
+
+- Gap: `gap-xs` (4px), `gap-s` (6px), `gap-md` (8px), `gap-m` (12px), `gap-l` (16px), `gap-xl` (20px), `gap-xxl` (24px)
+- Padding: `p-xs`, `p-s`, `p-md`, `p-m`, `p-l`, `p-xl`, `p-xxl`