@wangs-ui/skills 1.0.39 → 1.0.41

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-95qOyh-g.js";
+import { i as listSkills, n as updateSkills, r as addSkills, t as removeSkills } from "./src-Dolm1urJ.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-95qOyh-g.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-Dolm1urJ.js";
 export { addSkills, getAgentSkillDirs, getInstalledSkills, getSkill, installSkill, isSkillInstalled, listSkills, loadAllSkills, removeSkill, removeSkills, updateSkills };

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

@@ -1,166 +1,67 @@
 ---
 name: create-form
-description: Real-world patterns for building strongly-typed forms, multipart file uploads, server validation mapping, and dirty tracking with @wangs-ui/form.
+description: Architecture, validation workflows, and MCP discovery protocol for building forms and input controls with @wangs-ui/react-core.
 ---
 
-# Skill: Real-World Form Workflows with `@wangs-ui/form`
+# Skill: Form Architecture & Validation Workflows
 
-Use this skill when building CRUD forms, data entry dialogs, multi-field settings pages, or multipart forms in Wangs UI applications.
+Use this skill when building forms, data entry panels, settings pages, or multipart forms in Wangs UI applications.
 
 ---
 
-## 1. MCP Inspection Step (Before Building Fields)
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
 
-Before implementing specific input controls, query the MCP server to inspect their exact prop signatures:
+Do **NOT** hardcode or guess prop names, field configurations, or validation options. Retrieve active component definitions and live implementation stories directly from MCP:
 
-- `get-documentation({ id: "select" })` — Check option formats (`{ label, value }` vs object).
-- `get-documentation({ id: "datepicker" })` — Check `selectionMode` (`single`, `range`, `multiple`) and date format props.
-- `get-documentation({ id: "multiselect" })` — Check chips display and filter behavior.
-- `get-documentation({ id: "fileupload" })` — Check accepted mime types and upload handlers.
+### Inspect Component & Form Contracts:
 
----
-
-## 2. Recipe 1: Standard CRUD Form with Server Validation Mapping
-
-Real-world forms must handle async submission, loading state, and map backend validation errors back into `<Field>` errors:
-
-```tsx
-import React, { useState } from 'react';
-import Card from '@wangs-ui/react-core/primitive/card';
-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 { Form, Field } from '@wangs-ui/react-core';
-import { useFormControl } from '@wangs-ui/form';
-import { useI18n } from '@wangs-ui/react-i18n';
-
-interface UserFormValues {
-  fullName: string;
-  email: string;
-  role: string;
-}
-
-export default function UserForm({ onSuccess }: { onSuccess?: () => void }) {
-  const { t } = useI18n();
-  const formControl = useFormControl<UserFormValues>({ type: 'json' });
-  const [isSubmitting, setIsSubmitting] = useState(false);
-
-  const roleOptions = [
-    { label: t('Administrator'), value: 'admin' },
-    { label: t('Operator'), value: 'operator' },
-    { label: t('Viewer'), value: 'viewer' },
-  ];
-
-  const handleSubmit = async (values: UserFormValues) => {
-    setIsSubmitting(true);
-    try {
-      // Execute API call: await api.createUser(values);
-      onSuccess?.();
-    } catch (err: any) {
-      // Map server validation error directly to field
-      if (err?.fieldErrors?.email) {
-        formControl.setError('email', {
-          type: 'server',
-          message: err.fieldErrors.email,
-        });
-      }
-    } finally {
-      setIsSubmitting(false);
-    }
-  };
-
-  return (
-    <Card className="p-6">
-      <Form control={formControl} onSubmit={handleSubmit} className="flex flex-col gap-m">
-        <h2 className="heading-2">{t('User Information')}</h2>
-
-        {/* Text Field */}
-        <Field<string>
-          name="fullName"
-          label={t('Full Name')}
-          required
-          rules={{ required: t('Full name is required') }}
-        >
-          {(field) => (
-            <InputText {...field} placeholder={t('e.g. Jane Doe')} value={field.value || ''} />
-          )}
-        </Field>
-
-        {/* Email Field with Regex Validation */}
-        <Field<string>
-          name="email"
-          label={t('Email Address')}
-          required
-          rules={{
-            required: t('Email is required'),
-            pattern: {
-              value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
-              message: t('Enter a valid email address'),
-            },
-          }}
-        >
-          {(field) => (
-            <InputText {...field} placeholder={t('name@company.com')} value={field.value || ''} />
-          )}
-        </Field>
-
-        {/* Select Dropdown Field */}
-        <Field<string>
-          name="role"
-          label={t('Access Role')}
-          required
-          rules={{ required: t('Role selection is required') }}
-        >
-          {(field) => (
-            <Select
-              {...field}
-              options={roleOptions}
-              placeholder={t('Select role')}
-              value={field.value}
-              onChange={(e) => field.onChange(e.value)}
-            />
-          )}
-        </Field>
-
-        {/* Form Actions */}
-        <div className="flex justify-end gap-s pt-s">
-          <Button
-            type="button"
-            variant="text"
-            label={t('Reset')}
-            onClick={() => formControl.reset()}
-            disabled={isSubmitting}
-          />
-          <Button type="submit" label={t('Save User')} severity="primary" loading={isSubmitting} />
-        </div>
-      </Form>
-    </Card>
-  );
-}
+```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" })
+```
 
-## 3. Recipe 2: Multipart Form (File Upload + Metadata)
+### Inspect Knowledge Graph & Usages:
 
-For file uploads (avatar, attachment, documents), set `type: 'formdata'`:
+```json
+query_graph({ "query": "useFormControl" })
+query_graph({ "query": "Field" })
+```
 
-```tsx
-import { useFormControl } from '@wangs-ui/form';
+---
 
-interface ProfileUploadValues {
-  displayName: string;
-  avatar: File | null;
-}
+## 2. Form Architecture & State Principles
 
-// Generates FormData under the hood
-const formControl = useFormControl<ProfileUploadValues>({ type: 'formdata' });
-```
+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.
 
 ---
 
-## 4. Key Implementation Rules
+## 3. Mandatory Implementation Rules
 
-1. **Always Use `<Form>` & `<Field>`**: Never bind raw uncontrolled inputs.
-2. **Translate All Labels & Error Messages**: Wrap text in `t('...')`.
-3. **Handle Loading State**: Disable reset buttons and set `loading={isSubmitting}` on submit buttons.
+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

@@ -1,178 +1,68 @@
 ---
 name: data-table
-description: Real-world patterns for building full CRUD DataTables with server pagination, search filters, batch actions, and confirmation modals.
+description: Architecture, workflows, and MCP discovery protocol for building DataTables with sorting, pagination, filtering, selection, and export.
 ---
 
-# Skill: Real-World DataTable & Filter Workflows
+# Skill: DataTable Architecture & Integration Workflows
 
-Use this skill when building administrative grids, filtered listing pages, or management dashboards with `@wangs-ui/react-core`.
+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 Step (Before Building Table)
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
 
-Query the MCP server to inspect supported features and slots:
+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:
 
-- `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`).
+### 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:
 
-## 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>
-  );
-}
+```json
+query_graph({ "query": "DataTable" })
+query_graph({ "query": "useDataTableFetch" })
 ```
 
 ---
 
-## 3. Mandatory Best Practices
+## 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. **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`.
+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

@@ -1,131 +1,58 @@
 ---
 name: dialog-modal
-description: Real-world patterns for modal forms, async confirmation workflows, and multi-step dialogs with Wangs UI Dialog and Modal components.
+description: Patterns, overlay selection criteria, and MCP discovery protocol for Dialog, Modal, and DialogForm components in Wangs UI.
 ---
 
-# Skill: Real-World Dialog & Modal Workflows
+# Skill: Dialog, Modal & Overlay Workflows
 
-Use this skill when building interactive modals, create/edit modal forms, destructive action confirmations, or slide-in overlay panels.
+Use this skill when building interactive modals, create/edit dialog forms, destructive action confirmations, or slide-in overlay panels.
 
 ---
 
-## 1. MCP Inspection Step (Before Implementing Overlays)
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
 
-Query the MCP server to check overlay configuration and animation options:
+Do **NOT** guess overlay props, event names, or footer slots. Query the MCP server dynamically to inspect exact contracts and live story implementations:
 
-- `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.
+### 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" })
+```
 
-## 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>
-  );
-}
+### Inspect Knowledge Graph & Usages:
+
+```json
+query_graph({ "query": "Dialog" })
+query_graph({ "query": "DialogForm" })
 ```
 
 ---
 
-## 3. Mandatory Best Practices
+## 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. **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`.
+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`.