@_tc/template-core 0.0.1-bate.45 → 0.0.1-bate.47

package/.skills/tc-component-usage-skills/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: tc-component-usage-skills
+description: Use when building or modifying React UI in TemplateCore projects. Covers how to choose, compose, and correctly use components from `@tc/ui-react` / `@_tc/template-core/fe/rc`, plus TemplateCore frontend helpers from `@_tc/template-core/fe` such as `AsyncSelect`, `LanguageSwitch`, and `ThemeSwitch`. Includes patterns for forms, tables, modals, drawers, menus, Dashboard toolbar UI, and TC visual style.
+---
+
+# TC Component Usage
+
+Use this skill when writing React components that consume `@tc/ui-react`, `@_tc/template-core/fe/rc`, or TemplateCore frontend helpers from `@_tc/template-core/fe`.
+
+## Quick Decision Flow
+
+1. **Displaying data?** → `DataTable` or `Card`
+2. **Collecting input?** → `Form` / `SchemaForm` (built on `rc-field-form`) with `Input`, `Select`, `DatePicker`, `Switch`, `Textarea`, `InputNumber`, `Checkbox`, `Radio`, `TreeSelect`, `Upload`; TemplateCore model-driven pages can also use framework field type `asyncSelect`
+3. **Page layout?** → `Layout`
+4. **Overlays?** → `Modal` / `modal.confirm()` / `Drawer` / `Popup` / `Tooltip` / `ImagePreview`
+5. **Navigation?** → `Menu` / `Breadcrumb` / `Tabs` / `Pagination`
+6. **Feedback?** → `message.success()` / `Notification` / `Loading` / `Skeleton` / `ConfirmDialog`
+7. **Search & filter?** → `TableSearch` / `Search`
+8. **Language/theme toolbar?** → `LanguageSwitch` / `ThemeSwitch` from `@_tc/template-core/fe`
+9. **Remote select options?** → `AsyncSelect` from `@_tc/template-core/fe`
+
+## Core Patterns
+
+### Controlled vs Uncontrolled
+
+Every input-like component supports both modes. Check for `value !== undefined` → controlled mode, else uses `defaultValue` state internally.
+
+```tsx
+// Controlled
+<Input value={val} onChange={(v) => setVal(v)} />
+
+// Uncontrolled
+<Input defaultValue="hello" />
+```
+
+### Form Integration (rc-field-form)
+
+`Form` / `FormItem` / `SchemaForm` wrap `rc-field-form`. `FormItem` auto-clones children to inject `value`/`onChange`. Prefer `SchemaForm` for data-driven forms:
+
+```tsx
+const [form] = useForm<T>();
+<SchemaForm form={form} schemas={[
+  { key: 'name', label: 'Name', type: 'input', required: true },
+  { key: 'status', label: 'Status', type: 'select', fieldProps: { options: [...] } },
+]} onFinish={(vals) => ...} />
+```
+
+UI-library built-in `type` values: `input`, `inputNumber`, `select`, `textarea`, `switch`, `date`, `checkbox`.
+TemplateCore adds framework type `asyncSelect` via `@tc/scalability/SchemaForm/frameData`; custom app types are registered via `@tc/scalability/SchemaForm/data`.
+
+### Modal (Declarative + Imperative)
+
+```tsx
+// Declarative
+<Modal open={open} onClose={() => setOpen(false)} title="Title">
+  <Content />
+</Modal>
+
+// Imperative (async ok supported)
+modal.confirm({
+  title: 'Confirm',
+  content: 'Are you sure?',
+  onOk: async () => { await doSomething(); },
+});
+```
+
+### DataTable
+
+```tsx
+<DataTable
+  columns={columns}
+  data={data}
+  rowKey="id"
+  loading={loading}
+  pagination={{ current, pageSize, total, onChange }}
+  rowSelection={{ selectedRowKeys, onChange }}
+/>
+```
+
+## When to Use Each Overlay
+
+| Component | Use Case |
+|-----------|----------|
+| `Modal` | Center-screen dialog, forms, confirmations |
+| `Drawer` | Side panel for details, filters, settings |
+| `Popup` | Dropdown menus, selects, hover cards |
+| `Tooltip` | Brief hints on hover |
+| `ImagePreview` | Full-screen image gallery with zoom/rotate |
+| `Notification` | Passive corner notifications |
+| `Message` | Transient top-center toasts |
+
+## When You Need More Detail
+
+Read the reference files (progressive disclosure):
+
+- `reference/component-api.md` — Full props tables for every component
+- `reference/patterns.md` — Deeper patterns: schema forms, table columns, action buttons, horizontal forms
+- `reference/examples.md` — Copy-paste examples for common scenarios
+- `reference/template-core-frontend.md` — TemplateCore frontend helper components and Dashboard toolbar composition
+
+## Validation
+
+Before claiming work is done, verify:
+
+```bash
+pnpm type-check
+```
+
+## Component Import Convention
+
+```tsx
+import { Button, Form, FormItem, Input, DataTable, Modal, modal, useForm } from '@tc/ui-react'
+import { AsyncSelect, LanguageSwitch, ThemeSwitch } from '@_tc/template-core/fe'
+```
+
+When consuming the published TemplateCore package, `@_tc/template-core/fe/rc` re-exports the UI component library:
+
+```tsx
+import { Button, DataTable, TableSearch } from '@_tc/template-core/fe/rc'
+```
+
+Style entry:
+
+```tsx
+import '@tc/ui-react/index.css'
+// or, in published TemplateCore frontend entries:
+import '@_tc/template-core/fe/tailwind_ui.css'
+```
+
+## Visual Style
+
+For `packages/react/ui/components` or TemplateCore business UI, keep the default product feel dark, restrained, dense, and tool-like: stable small type, subtle borders, consistent focus rings, controlled saturated accents, and complete default/hover/focus/active/disabled/loading/error states.