@wangs-ui/skills 1.0.36

package/dist/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/dist/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`

package/dist/src-C22mKmnQ.js

@@ -0,0 +1,210 @@
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { cancel, intro, isCancel, multiselect, outro } from "@clack/prompts";
+//#region src/registry.ts
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+function getSkillsDir() {
+	const candidates = [
+		path.resolve(__dirname, "skills"),
+		path.resolve(__dirname, "../skills"),
+		path.resolve(__dirname, "../../skills")
+	];
+	for (const c of candidates) if (fs.existsSync(c)) return c;
+	return path.resolve(__dirname, "skills");
+}
+function loadAllSkills() {
+	const skillsDir = getSkillsDir();
+	if (!fs.existsSync(skillsDir)) return [];
+	const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+	const skills = [];
+	for (const entry of entries) if (entry.isDirectory()) {
+		const skillMdPath = path.join(skillsDir, entry.name, "SKILL.md");
+		if (fs.existsSync(skillMdPath)) {
+			const content = fs.readFileSync(skillMdPath, "utf-8");
+			const { name: entryName } = entry;
+			let name = entryName;
+			let description = "Wangs UI consumer skill";
+			const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+			if (frontmatterMatch) {
+				const fm = frontmatterMatch[1];
+				const nameMatch = fm.match(/^name:\s*(.+)$/m);
+				const descMatch = fm.match(/^description:\s*(.+)$/m);
+				if (nameMatch) name = nameMatch[1].trim();
+				if (descMatch) description = descMatch[1].trim();
+			}
+			skills.push({
+				id: entry.name,
+				name,
+				description,
+				content
+			});
+		}
+	}
+	return skills;
+}
+function getSkill(id) {
+	return loadAllSkills().find((s) => s.id === id || s.name === id);
+}
+//#endregion
+//#region src/detector.ts
+function getAgentSkillDirs(baseDir = process.cwd()) {
+	const dirs = [];
+	const candidates = [
+		path.join(baseDir, ".agents", "skills"),
+		path.join(baseDir, ".claude", "skills"),
+		path.join(baseDir, ".opencode", "skills"),
+		path.join(baseDir, ".kilo", "skills")
+	];
+	for (const c of candidates) if (fs.existsSync(c) || fs.existsSync(path.dirname(c))) dirs.push(c);
+	if (dirs.length === 0) dirs.push(path.join(baseDir, ".agents", "skills"));
+	return dirs;
+}
+function isSkillInstalled(skillId, baseDir = process.cwd()) {
+	const dirs = getAgentSkillDirs(baseDir);
+	for (const d of dirs) {
+		const skillPath = path.join(d, skillId, "SKILL.md");
+		if (fs.existsSync(skillPath)) return true;
+	}
+	return false;
+}
+function getInstalledSkills(baseDir = process.cwd()) {
+	const dirs = getAgentSkillDirs(baseDir);
+	const installed = /* @__PURE__ */ new Set();
+	for (const d of dirs) if (fs.existsSync(d)) {
+		const entries = fs.readdirSync(d, { withFileTypes: true });
+		for (const entry of entries) if (entry.isDirectory()) {
+			const skillMd = path.join(d, entry.name, "SKILL.md");
+			if (fs.existsSync(skillMd)) installed.add(entry.name);
+		}
+	}
+	return Array.from(installed);
+}
+function installSkill(skill, baseDir = process.cwd()) {
+	const targetDirs = getAgentSkillDirs(baseDir);
+	const writtenPaths = [];
+	for (const baseSkillDir of targetDirs) {
+		const destDir = path.join(baseSkillDir, skill.id);
+		fs.mkdirSync(destDir, { recursive: true });
+		const destFile = path.join(destDir, "SKILL.md");
+		fs.writeFileSync(destFile, skill.content, "utf-8");
+		writtenPaths.push(destFile);
+	}
+	return writtenPaths;
+}
+function removeSkill(skillId, baseDir = process.cwd()) {
+	const targetDirs = getAgentSkillDirs(baseDir);
+	const removedPaths = [];
+	for (const baseSkillDir of targetDirs) {
+		const destDir = path.join(baseSkillDir, skillId);
+		if (fs.existsSync(destDir)) {
+			fs.rmSync(destDir, {
+				recursive: true,
+				force: true
+			});
+			removedPaths.push(destDir);
+		}
+	}
+	return removedPaths;
+}
+//#endregion
+//#region src/commands/list.ts
+function listSkills(baseDir = process.cwd()) {
+	intro("\x1B[1m\x1B[36m📦 Wangs UI Consumer Skills Registry\x1B[0m");
+	const allSkills = loadAllSkills();
+	const targetDirs = getAgentSkillDirs(baseDir);
+	if (allSkills.length === 0) {
+		console.log("No skills found in registry.");
+		outro("Done.");
+		return;
+	}
+	console.log(`\nAgent directories: \x1b[2m${targetDirs.join(", ")}\x1b[0m\n`);
+	for (const skill of allSkills) {
+		const statusBadge = isSkillInstalled(skill.id, baseDir) ? "\x1B[32m[Installed]\x1B[0m" : "\x1B[90m[Available]\x1B[0m";
+		console.log(`  ${statusBadge} \x1b[1m${skill.id}\x1b[0m`);
+		console.log(`    \x1b[90m${skill.description}\x1b[0m\n`);
+	}
+	outro(`Total skills: ${allSkills.length} | Run \x1b[36mnpx @wangs-ui/skills add <skill-name>\x1b[0m to install.`);
+}
+//#endregion
+//#region src/commands/add.ts
+async function addSkills(skillIds, baseDir = process.cwd()) {
+	intro("\x1B[1m\x1B[36m➕ Install Wangs UI Consumer Skills\x1B[0m");
+	const allSkills = loadAllSkills();
+	let targetIds = skillIds.filter(Boolean);
+	if (targetIds.length === 0) {
+		const selected = await multiselect({
+			message: "Select Wangs UI skills to install into your agent environment:",
+			options: allSkills.map((s) => ({
+				value: s.id,
+				label: s.id,
+				hint: s.description
+			})),
+			required: true
+		});
+		if (isCancel(selected)) {
+			cancel("Operation cancelled.");
+			return;
+		}
+		targetIds = selected;
+	}
+	const installedList = [];
+	for (const id of targetIds) {
+		const skill = getSkill(id);
+		if (!skill) {
+			console.log(`\x1b[33m⚠️  Skill "${id}" not found in registry. Run "list" to view available skills.\x1b[0m`);
+			continue;
+		}
+		const paths = installSkill(skill, baseDir);
+		installedList.push(skill.id);
+		for (const p of paths) console.log(`  \x1b[32m✔\x1b[0m Installed \x1b[1m${skill.id}\x1b[0m -> \x1b[2m${p}\x1b[0m`);
+	}
+	if (installedList.length > 0) outro(`\x1b[32mSuccessfully installed ${installedList.length} skill(s)!\x1b[0m`);
+	else outro("No skills were installed.");
+}
+//#endregion
+//#region src/commands/update.ts
+function updateSkills(skillIds = [], baseDir = process.cwd()) {
+	intro("\x1B[1m\x1B[36m🔄 Update Wangs UI Consumer Skills\x1B[0m");
+	let targets = skillIds.filter(Boolean);
+	if (targets.length === 0) targets = getInstalledSkills(baseDir);
+	if (targets.length === 0) {
+		console.log("No installed skills found in project to update.");
+		outro("Done.");
+		return;
+	}
+	const updatedList = [];
+	for (const id of targets) {
+		const skill = getSkill(id);
+		if (!skill) {
+			console.log(`\x1b[33m⚠️  Skill "${id}" not found in current registry.\x1b[0m`);
+			continue;
+		}
+		const paths = installSkill(skill, baseDir);
+		updatedList.push(skill.id);
+		for (const p of paths) console.log(`  \x1b[32m✔\x1b[0m Updated \x1b[1m${skill.id}\x1b[0m -> \x1b[2m${p}\x1b[0m`);
+	}
+	outro(`\x1b[32mSuccessfully updated ${updatedList.length} skill(s)!\x1b[0m`);
+}
+//#endregion
+//#region src/commands/remove.ts
+function removeSkills(skillIds, baseDir = process.cwd()) {
+	intro("\x1B[1m\x1B[31m🗑️  Remove Wangs UI Consumer Skills\x1B[0m");
+	const targets = skillIds.filter(Boolean);
+	if (targets.length === 0) {
+		console.log("Please specify skill name(s) to remove.");
+		outro("Aborted.");
+		return;
+	}
+	const removedList = [];
+	for (const id of targets) {
+		const paths = removeSkill(id, baseDir);
+		if (paths.length > 0) {
+			removedList.push(id);
+			for (const p of paths) console.log(`  \x1b[31m✔\x1b[0m Removed \x1b[1m${id}\x1b[0m from \x1b[2m${p}\x1b[0m`);
+		} else console.log(`  \x1b[90m- Skill "${id}" was not installed.\x1b[0m`);
+	}
+	outro(`\x1b[32mCompleted. Removed ${removedList.length} skill(s).\x1b[0m`);
+}
+//#endregion
+export { getAgentSkillDirs as a, isSkillInstalled as c, getSkillsDir as d, loadAllSkills as f, listSkills as i, removeSkill as l, updateSkills as n, getInstalledSkills as o, addSkills as r, installSkill as s, removeSkills as t, getSkill as u };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@wangs-ui/skills",
+  "version": "1.0.36",
+  "description": "CLI to install, update, and manage modular AI agent skills for Wangs UI React applications",
+  "keywords": [
+    "agents",
+    "ai",
+    "antigravity",
+    "claude-code",
+    "cli",
+    "cursor",
+    "kilo",
+    "mcp",
+    "opencode",
+    "skills",
+    "wangs-ui"
+  ],
+  "homepage": "https://github.com/fewangsit/wangs-ui-react",
+  "license": "MIT",
+  "author": "Wangsit FE Developer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fewangsit/wangs-ui-react.git",
+    "directory": "packages/skills"
+  },
+  "bin": {
+    "skills": "dist/bin.js",
+    "wangs-ui-skills": "dist/bin.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0"
+  },
+  "devDependencies": {},
+  "scripts": {
+    "build": "vite build",
+    "check:publint": "publint",
+    "check:attw": "attw --pack ."
+  }
+}

package/skills/create-form/SKILL.md

@@ -0,0 +1,166 @@
+---
+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.
+---
+
+# Skill: Real-World Form Workflows with `@wangs-ui/form`
+
+Use this skill when building CRUD forms, data entry dialogs, multi-field settings pages, or multipart forms in Wangs UI applications.
+
+---
+
+## 1. MCP Inspection Step (Before Building Fields)
+
+Before implementing specific input controls, query the MCP server to inspect their exact prop signatures:
+
+- `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.
+
+---
+
+## 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>
+  );
+}
+```
+
+---
+
+## 3. Recipe 2: Multipart Form (File Upload + Metadata)
+
+For file uploads (avatar, attachment, documents), set `type: 'formdata'`:
+
+```tsx
+import { useFormControl } from '@wangs-ui/form';
+
+interface ProfileUploadValues {
+  displayName: string;
+  avatar: File | null;
+}
+
+// Generates FormData under the hood
+const formControl = useFormControl<ProfileUploadValues>({ type: 'formdata' });
+```
+
+---
+
+## 4. Key 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.