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

package/.skills/tc-component-usage-skills/reference/patterns.md

@@ -0,0 +1,392 @@
+# Component Patterns
+
+Recurring patterns and best practices for `@tc/ui-react`.
+
+---
+
+## Visual Style Pattern
+
+For TemplateCore component work, aim for a dark, restrained, collaboration-tool feel:
+
+- Use deep backgrounds, low-contrast panels, subtle borders, and compact text.
+- Reserve saturated color for primary actions, selection, status, and collaboration identity.
+- Keep page shells and panels layered; avoid decorative gradients or oversized marketing-style sections for admin UI.
+- Every reusable component should cover default, hover, focus, active, disabled, loading, and error states where applicable.
+- Prefer stable dimensions for controls, table cells, icon buttons, and fixed-format UI so state changes do not shift layout.
+
+When editing this repository, `packages/react/ui/components/VIDEO_UI_STYLE_GUIDE.md` is the fuller visual reference.
+
+---
+
+## Form Patterns
+
+### SchemaForm: Data-Driven Forms
+
+The standard way to build forms. Define schemas, not JSX:
+
+```tsx
+const [form] = useForm<UserForm>()
+
+<SchemaForm<UserForm>
+  form={form}
+  schemas={[
+    { key: 'username', label: 'Username', type: 'input', required: true },
+    { key: 'email', label: 'Email', type: 'input',
+      rules: [{ type: 'email', message: 'Invalid email' }] },
+    { key: 'role', label: 'Role', type: 'select',
+      fieldProps: { options: [{ label: 'Admin', value: 'admin' }, { label: 'User', value: 'user' }] } },
+    { key: 'active', label: 'Active', type: 'switch' },
+  ]}
+  onFinish={handleSubmit}
+/>
+```
+
+### SchemaForm Layouts
+
+- **`layout='vertical'`** (default): Label above field. Footer buttons auto-rendered.
+- **`layout='horizontal'`**: Label beside field. **Footer buttons NOT auto-rendered** — provide via `footerButtons` prop or handle externally.
+- **Per-field override**: Set `layout` on individual schema items via `fieldLayout`.
+
+### Registering Custom SchemaForm Types
+
+TemplateCore already registers framework field type `asyncSelect`:
+
+```tsx
+<SchemaForm
+  schemas={[
+    {
+      key: 'ownerId',
+      label: 'Owner',
+      type: 'asyncSelect',
+      fieldProps: {
+        fetchConfig: { url: '/user/options', method: 'get' },
+      },
+    },
+  ]}
+/>
+```
+
+The options endpoint should return the normal TemplateCore response wrapper, usually via `this.success(ctx, options)`.
+
+```tsx
+// In the app-side module aliased as @tc/scalability/SchemaForm/data:
+const consumerComponentsMap = {
+  richText: RichTextEditor,
+  userSelector: UserSelect,
+}
+
+export default consumerComponentsMap
+// Now { type: 'richText', ... } works in schemas
+```
+
+### FormItem: Render Function Pattern
+
+When you need custom logic inside a form field:
+
+```tsx
+<FormItem label="Tags" name="tags">
+  {(value, onChange) => (
+    <TagInput value={value} onChange={(tags) => onChange(tags)} />
+  )}
+</FormItem>
+```
+
+### FormItem: Automatic Child Injection
+
+`FormItem` auto-clones children to inject `value`/`onChange`. It handles Input's two-arg `onChange(value, event)` signature correctly.
+
+### SubmitButton / AsynchronousButton for Async Forms
+
+```tsx
+<AsynchronousButton
+  onClick={async () => {
+    await submitToApi(form.getFieldsValue())
+  }}
+>
+  Save
+</AsynchronousButton>
+```
+
+Auto-shows loading spinner during async execution.
+
+---
+
+## DataTable Patterns
+
+### Basic Column Definition
+
+```tsx
+const columns: TableColumnDef<User>[] = [
+  { key: 'id', title: 'ID', dataIndex: 'id', width: '80px' },
+  { key: 'name', title: 'Name', dataIndex: 'name' },
+  { key: 'status', title: 'Status', dataIndex: 'status',
+    render: (value) => <Badge status={value} /> },
+  { key: 'action', title: 'Actions',
+    actions: (_value, record) => [
+      { key: 'edit', label: 'Edit', onClick: () => openEdit(record) },
+      { key: 'delete', label: 'Delete', danger: true, onClick: () => onDelete(record) },
+    ] },
+]
+```
+
+### Action Column Behavior
+
+`ActionBtn` handles the action column rendering:
+- **0 actions**: Shows `'-'`
+- **1 action**: Single button
+- **Multiple**: Uses overflow mode:
+  - `'auto'` (default): Uses ResizeObserver to detect fit; falls back to dropdown
+  - `'dropdown'`: Always shows "..." dropdown button
+  - `'inline'`: Shows all buttons inline (only for `DropdownBaseItem`)
+
+### Pagination
+
+```tsx
+// Let DataTable handle pagination internally
+<DataTable columns={columns} data={data} />
+
+// Control pagination externally
+<DataTable
+  columns={columns}
+  data={data}
+  pagination={{ current: 1, pageSize: 20, total: 100, onChange: fetchPage }}
+/>
+```
+
+### Row Selection
+
+```tsx
+<DataTable
+  columns={columns}
+  data={data}
+  rowSelection={{
+    selectedRowKeys: selectedIds,
+    onChange: (keys) => setSelectedIds(keys),
+  }}
+/>
+```
+
+Supports checkboxes, indeterminate (partial) state, page-level select-all.
+
+### Sticky Columns
+
+Action columns are auto-sticky right. Set `fixed: 'left'` or `fixed: 'right'` on other columns. IntersectionObserver-based shadow effects when scrolled.
+
+### Loading State
+
+```tsx
+<DataTable columns={columns} data={data} loading={isLoading} />
+```
+
+Shows skeleton overlay in `tableloading` mode while `loading={true}`.
+
+---
+
+## TableSearch Pattern
+
+```tsx
+<TableSearch<UserSearch>
+  schemas={[
+    { key: 'name', label: 'Name', type: 'input', isPermanent: true },
+    { key: 'status', label: 'Status', type: 'select',
+      fieldProps: { options: statusOptions }, isPermanent: true },
+    { key: 'createdAt', label: 'Created', type: 'date' },
+    { key: 'email', label: 'Email', type: 'input' },
+  ]}
+  onSearch={(values) => fetchData(values)}
+  onReset={() => fetchData({})}
+  onExport={(type, searchData) => exportData(type, searchData)}
+  exportMenuItems={exportItems}
+/>
+```
+
+`isPermanent: true` fields always show. Others hidden when collapsed. `expandBoundaries` (default 4) controls permanent field threshold.
+
+---
+
+## Overlay Patterns
+
+### Modal with Form
+
+```tsx
+const [open, setOpen] = useState(false)
+const [form] = useForm()
+
+<Modal open={open} onClose={() => setOpen(false)} title="Create User"
+  footer={
+    <div className="flex justify-end gap-2">
+      <Button onClick={() => setOpen(false)}>Cancel</Button>
+      <AsynchronousButton onClick={() => form.submit()}>Save</AsynchronousButton>
+    </div>
+  }
+>
+  <SchemaForm form={form} schemas={schemas} footerButtons={false}
+    onFinish={async (values) => { await createUser(values); setOpen(false); }} />
+</Modal>
+```
+
+### ConfirmDialog for Simple Confirmations
+
+```tsx
+<ConfirmDialog
+  open={confirmOpen}
+  title="Delete User"
+  content="This action cannot be undone. Continue?"
+  onOk={async () => { await deleteUser(id); setConfirmOpen(false); }}
+  onCancel={() => setConfirmOpen(false)}
+/>
+```
+
+### Imperative Confirm (modal)
+
+```tsx
+modal.confirm({
+  title: 'Delete',
+  content: 'Are you sure?',
+  onOk: async () => { await deleteUser(id); },
+})
+```
+
+### Drawer for Side Panels
+
+```tsx
+<Drawer open={open} onClose={() => setOpen(false)} title="User Details"
+  placement="right" width={480}
+>
+  <UserDetailContent userId={id} />
+</Drawer>
+```
+
+---
+
+## Menu Patterns
+
+### Declarative via items
+
+```tsx
+<Menu
+  mode="left"
+  items={[
+    { key: 'dashboard', label: 'Dashboard', icon: <HomeIcon /> },
+    { key: 'users', label: 'Users', icon: <UsersIcon />,
+      children: [
+        { key: 'users-list', label: 'All Users' },
+        { key: 'users-roles', label: 'Roles' },
+      ] },
+  ]}
+  selectedKey={currentKey}
+  onSelect={(key) => navigate(key)}
+/>
+```
+
+### Collapsible Sidebar
+
+```tsx
+<Menu mode="left" collapsed={collapsed} collapsedWidth={64} collapsedLabelTooltip>
+  <Menu.CollapseToggle ref={toggleRef} />
+  {/* items */}
+</Menu>
+```
+
+When collapsed without icon: shows first character of label. With `collapsedLabelTooltip`: hover shows full label via Popup.
+
+### Top Mode Menu
+
+```tsx
+<Menu mode="top" expandTrigger="hover">
+  <Menu.Item eventKey="home">Home</Menu.Item>
+  <Menu.SubMenu eventKey="products" label="Products" popup>
+    <Menu.Item eventKey="prod-list">List</Menu.Item>
+    <Menu.Item eventKey="prod-create">Create</Menu.Item>
+  </Menu.SubMenu>
+</Menu>
+```
+
+In `mode='top'`, SubMenus always use popup dropdowns.
+
+---
+
+## Notification & Message Patterns
+
+### Toast Messages
+
+```tsx
+import { message } from '@tc/ui-react'
+
+message.success('User created successfully')
+message.error('Failed to save')
+message.warning('Session expiring soon')
+message.info('New update available')
+```
+
+### Notifications (Corner)
+
+```tsx
+import { Notification } from '@tc/ui-react'
+
+// As component
+<Notification type="error" title="Upload Failed" message="Network error. Retry?" />
+
+// To manage manually, render conditionally
+```
+
+---
+
+## Layout Pattern
+
+```tsx
+<Layout
+  header={<Header />}
+  sidebar={<SidebarMenu />}
+  footer={<Footer />}
+>
+  <main className="p-6">
+    <Outlet />
+  </main>
+</Layout>
+```
+
+---
+
+## Compound Component Pattern
+
+Three components use compound patterns with Context:
+
+1. **Menu**: `<Menu>` + `<Menu.Item>` + `<Menu.SubMenu>` + `<Menu.CollapseToggle>`
+2. **Radio**: `<Radio.Group>` + `<Radio>`
+3. **Breadcrumb**: `<Breadcrumb>` + `<BreadcrumbList>` + `<BreadcrumbItem>` + ...
+
+Children auto-detect parent via Context and inherit configuration.
+
+---
+
+## Controlled/Uncontrolled Convention
+
+All input-like components follow this pattern:
+
+```typescript
+// Internal pattern used by every input component:
+const isControlled = props.value !== undefined
+// → Controlled: use props.value + props.onChange
+// → Uncontrolled: use internal useState(defaultValue)
+```
+
+This means both patterns work identically:
+
+```tsx
+// Controlled
+<Select value={val} onChange={setVal} options={opts} />
+
+// Uncontrolled
+<Select defaultValue="foo" options={opts} />
+```
+
+---
+
+## CSS Conventions
+
+- Import styles before using components: `@tc/ui-react/index.css` for raw UI usage, or `@_tc/template-core/fe/tailwind_ui.css` for published TemplateCore frontend entries.
+- All CSS classes are prefixed `tc-ui-<component-name>`
+- Tailwind CSS used for styling
+- Theme via CSS custom properties: `hsl(var(--theme-primary))`, `hsl(var(--theme-background))`, etc.
+- Customize by setting CSS variables or overriding Tailwind theme

package/.skills/tc-component-usage-skills/reference/template-core-frontend.md

@@ -0,0 +1,104 @@
+# TemplateCore Frontend Helpers
+
+Use these when building business UI on top of TemplateCore, especially Dashboard header tools and project pages.
+
+## Import Paths
+
+```tsx
+import { AsyncSelect, LanguageSwitch, ThemeSwitch } from '@_tc/template-core/fe'
+import { Button, DataTable, TableSearch } from '@_tc/template-core/fe/rc'
+```
+
+Inside this repository, `@tc/ui-react` is also valid for the raw UI library. In published business projects, prefer `@_tc/template-core/fe/rc` for UI components and `@_tc/template-core/fe` for frontend runtime helpers.
+
+## LanguageSwitch
+
+```tsx
+<LanguageSwitch />
+```
+
+Default languages are `zh-CN` and `en-US`. Pass `options` to replace the list. `onChange(language)` receives the selected language string. The component calls `i18nStore.getState().setLanguage()`, so it uses the same `tc_language` persistence as the UI i18n runtime.
+
+Useful props:
+
+```typescript
+type LanguageSwitchValue = 'zh-CN' | 'en-US' | (string & {})
+
+interface LanguageSwitchProps {
+  value?: LanguageSwitchValue
+  defaultValue?: LanguageSwitchValue
+  options?: Array<{ label: ReactNode; value: LanguageSwitchValue; searchText?: string }>
+  onChange?: (language: LanguageSwitchValue) => void
+}
+```
+
+## ThemeSwitch
+
+```tsx
+<ThemeSwitch showLabel />
+```
+
+Toggles `document.documentElement.classList` with the `dark` class and syncs `color-scheme`. By default it persists to `localStorage` key `tc_theme`.
+
+Useful props:
+
+```typescript
+type ThemeSwitchMode = 'light' | 'dark'
+
+interface ThemeSwitchProps {
+  value?: ThemeSwitchMode
+  defaultValue?: ThemeSwitchMode
+  onChange?: (mode: ThemeSwitchMode) => void
+  disabled?: boolean
+  showLabel?: boolean
+  persist?: boolean
+  storageKey?: string
+}
+```
+
+## AsyncSelect
+
+Use `AsyncSelect` when options should be loaded from a TemplateCore API.
+
+```tsx
+<AsyncSelect
+  fetchConfig={{ url: '/user/options', method: 'get' }}
+  placeholder="Select user"
+/>
+```
+
+The options array shape is:
+
+```ts
+Array<{ label: string; value: string | number; searchText?: string }>
+```
+
+The endpoint should return TemplateCore's normal response wrapper. In a controller, use:
+
+```js
+this.success(ctx, [
+  { label: "Alice", value: "u1" },
+  { label: "Bob", value: "u2" },
+]);
+```
+
+`AsyncSelect` reads `res.data.code === 0` and then maps `res.data.data`. It forwards most `Select` props except `options`; it owns option loading internally.
+
+## Dashboard Header Tools
+
+For a compact header user area, combine the helpers:
+
+```tsx
+import { LanguageSwitch, ThemeSwitch } from '@_tc/template-core/fe'
+
+export function HeaderTools() {
+  return (
+    <div className="flex items-center gap-2">
+      <LanguageSwitch className="w-32" />
+      <ThemeSwitch />
+    </div>
+  )
+}
+```
+
+Registering the header slot itself belongs to the generator/runtime extension docs. The supported Dashboard component key is `HeaderView.userArea`.

package/.skills/tc-generator/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: tc-generator
+description: Generate TemplateCore business projects, modules, model configurations, Schema CRUD pages, controllers, routers, and project overrides that follow this repository's Koa + React + model-driven conventions. Use when the user asks to create or modify TC/TemplateCore projects, admin modules, model/mode.js files, schemaConfig CRUD pages, menu structures, or app/controller and app/router files.
+---
+
+# TC Generator
+
+Use this skill to generate or update TemplateCore business code.
+
+## Quick Workflow
+
+1. Identify the target business root. In this repository, a generated project usually uses:
+   - `index.js`
+   - `config/config.default.js`
+   - `app/controller/*.js`
+   - `app/router/*.js`
+   - `model/{modelKey}/mode.js`
+   - optional `model/{modelKey}/project/{projectKey}.js`
+2. Read only the reference needed:
+   - Model/menu/schema rules: `reference/model-schema.md`
+   - Runtime extensions (db, Dashboard slots/routes, frontend helpers): `reference/runtime-extensions.md`
+   - Standalone skeleton: `reference/project-template/`
+   - Complete product CRUD example: `reference/example.md`
+3. Generate the smallest working slice first: config, entry, controller, router, model.
+4. Keep keys stable. Array merge and project overrides depend on `key`.
+5. Prefer CommonJS `.js` for generated business examples unless the existing business project already uses TypeScript.
+
+## TemplateCore Conventions
+
+- Start the app with `serverStart({ name, baseDir })` from `@_tc/template-core`.
+- Start the built-in frontend with `buildFE("dev")` from `@_tc/template-core/bundler` when the user needs the admin UI. Do not `await` it; the current API starts the build/dev process and returns `void`.
+- If `buildFE("dev")` is used in a standalone project, include the TemplateCore peer dependencies or use the package manager's peer dependency auto-install behavior.
+- Business code lives under the user's `baseDir`, not inside TemplateCore framework folders.
+- The framework provides `app.extends.db` as a default SQLite-backed KV/SQL helper. Use it for small framework/business settings; override `app/extend/db.js` only when the project needs a custom storage implementation.
+- Backend loaders map filenames to camelCase fields:
+  - `app/controller/product.js` -> `app.controller.product`
+  - `app/service/user-profile.js` -> `app.service.userProfile`
+- Controller and service files export a factory: `module.exports = (app) => class Xxx {}`.
+- Router files export a function: `module.exports = (app, router) => { ... }`.
+- Schema pages expect REST-like endpoints:
+  - `GET {api}/list` for table data
+  - `GET {api}` for detail/edit fetch
+  - `POST {api}` for create
+  - `PUT {api}` for update
+  - `DELETE {api}` for remove
+
+## Output Rules
+
+- Make generated code directly runnable when package dependencies are installed.
+- Include realistic in-memory data only for demos or scaffolds.
+- Use `$i18n::...` only when also adding or pointing to language resources; otherwise write plain labels.
+- For Schema CRUD, include `tableOption`, `createFormOption`, `editFormOption`, and `detailPanelOption` only where the field should appear.
+- For edit/detail components, set `fetchKey` to the primary key field.
+- For remove buttons, use `$schema::{field}` to pull values from the current row.
+- Generate frontend extensions only when needed:
+  - Dashboard header UI: `frontend/extended/dash/components.tsx` with `HeaderView.userArea`
+  - Dashboard custom routes: `frontend/extended/dash/customRoutes.tsx`
+  - SchemaForm field types: `frontend/extended/SchemaForm/data.ts`
+  - SchemaPage custom call components: `frontend/extended/SchemaPage/CallCom/data.ts`
+
+## Validation
+
+When editing an existing project, verify with the closest available command:
+
+```bash
+pnpm type-check
+pnpm dev
+```
+
+For generated standalone CommonJS examples, at minimum inspect paths and imports against the current package name.