@_tc/template-core 0.1.13 → 0.1.15

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

@@ -18,7 +18,8 @@ Use this skill to generate or update TemplateCore business code.
    - optional `model/{modelKey}/project/{projectKey}.js`
 2. Read only the reference needed:
    - Model/menu/schema rules: `reference/model-schema.md`
-   - Runnable skeleton: `reference/project-template/`
+   - 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`.
@@ -27,8 +28,10 @@ Use this skill to generate or update TemplateCore business code.
 ## 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.
+- 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`
@@ -43,12 +46,17 @@ Use this skill to generate or update TemplateCore business code.
 
 ## Output Rules
 
-- Make generated code directly runnable.
+- 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
 

package/.skills/tc-generator/reference/example.md

@@ -34,7 +34,7 @@ async function main() {
     baseDir: join(__dirname, "."),
   });
 
-  await buildFE("dev");
+  buildFE("dev");
 }
 
 main().catch((error) => {

package/.skills/tc-generator/reference/model-schema.md

@@ -45,7 +45,7 @@ module.exports = {
   name: "Product Admin",
   desc: "Product management",
   icon: "",
-  homePage: "/_sidebar_/product?projk=default",
+  homePage: "/_sidebar_/product",
   menuLayout: "left",
   menu: [],
 };
@@ -63,7 +63,7 @@ Fields:
 | `menuLayout` | no | `"left"` default, or `"top"`. |
 | `menu` | yes | Menu tree. |
 
-For `left` layout, built-in menu routes are under `/_sidebar_/{menuKey}`. For `top` layout, built-in menu routes are `/{menuKey}`. Put project-specific query values, such as `projk`, in the project override when they differ per project.
+For `left` layout, built-in menu routes are under `/_sidebar_/{menuKey}`. For `top` layout, built-in menu routes are `/{menuKey}`. Keep shared model `homePage` project-neutral when multiple projects inherit the same model; put project-specific query values, such as `projk`, in the project override when they differ per project.
 
 ## Menu Types
 
@@ -173,6 +173,8 @@ Table list should return:
 
 Framework response wrapper is handled by `this.success(ctx, data)`.
 
+Controllers can use `app.extends.db` for simple persisted data instead of in-memory arrays. See `reference/runtime-extensions.md` for the default DB contract and override pattern.
+
 ## Field Schema
 
 Each field is JSON Schema plus TemplateCore options:

package/.skills/tc-generator/reference/project-template/config/config.default.js

@@ -1,3 +1,7 @@
 module.exports = {
   port: 9000,
+  // Optional: override the default `.template-core/template-core.sqlite` path.
+  // db: {
+  //   path: "data/app.sqlite",
+  // },
 };

package/.skills/tc-generator/reference/project-template/index.js

@@ -8,7 +8,7 @@ async function main() {
     baseDir: join(__dirname, "."),
   });
 
-  await buildFE("dev");
+  buildFE("dev");
 }
 
 main().catch((error) => {

package/.skills/tc-generator/reference/project-template/model/product/project/default.js

@@ -1,4 +1,5 @@
 module.exports = {
   name: "Default Product Project",
   desc: "Project-level overrides can be added here.",
+  homePage: "/_sidebar_/product?projk=default",
 };

package/.skills/tc-generator/reference/project-template/package.json

@@ -5,6 +5,21 @@
     "dev": "node index.js"
   },
   "dependencies": {
-    "@_tc/template-core": "0.0.3"
+    "@_tc/template-core": "latest",
+    "@vitejs/plugin-react": "6.0.1",
+    "clsx": "^2.1.0",
+    "date-fns": "^3.6.0",
+    "koa": "^2.15.0",
+    "koa-router": "^12.0.1",
+    "lodash": "^4.17.21",
+    "lucide-react": "^0.468.0",
+    "rc-field-form": "^1.44.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^6.28.0",
+    "tailwind-merge": "^2.4.0",
+    "vite": "8.0.10",
+    "xlsx": "^0.18.5",
+    "zustand": "^5.0.0"
   }
 }

package/.skills/tc-generator/reference/runtime-extensions.md

@@ -0,0 +1,190 @@
+# TemplateCore Runtime Extensions
+
+Use this reference when generating business code that needs persistence, Dashboard customization, or frontend helper components.
+
+## Default DB
+
+`app.extends.db` is available by default. It stores framework/business data in SQLite at:
+
+```text
+.template-core/template-core.sqlite
+```
+
+The default path is relative to the business project `baseDir`. Configure it in `config/config.default.js`:
+
+```js
+module.exports = {
+  port: 9000,
+  db: {
+    path: "data/app.sqlite",
+  },
+};
+```
+
+Prefer `db.path` for new projects. The current runtime also accepts `db` as a string and object aliases `filename`, `sqlitePath`, or `sqlite: string | { path, filename }` for compatibility.
+
+Common methods:
+
+```ts
+app.extends.db.dbPath
+app.extends.db.getDBConnection()
+app.extends.db.execDB(sql)
+app.extends.db.getDBData(key, { namespace })
+app.extends.db.getDBDataRecord(key, { namespace })
+app.extends.db.setDBData(key, value, { namespace })
+app.extends.db.hasDBData(key, { namespace })
+app.extends.db.deleteDBData(key, { namespace })
+app.extends.db.listDBData({ namespace, limit, offset })
+app.extends.db.countDBData({ namespace })
+app.extends.db.clearDBData({ namespace })
+app.extends.db.queryDB(sql, params)
+app.extends.db.runDB(sql, params)
+app.extends.db.getDBFirst(sql, params)
+app.extends.db.transactionDB((db) => ...)
+app.extends.db.closeDB()
+```
+
+SQL safety rule: put user input in `params`; do not concatenate it into SQL strings. `execDB(sql)` is only for fixed SQL such as migrations.
+
+Example controller storage:
+
+```js
+const { baseFn } = require("@_tc/template-core");
+
+module.exports = (app) => {
+  const BaseController = baseFn.baseControllerFn(app);
+
+  return class SettingController extends BaseController {
+    get = async (ctx) => {
+      const data = app.extends.db.getDBData("site-setting", {
+        namespace: "settings",
+      });
+
+      this.success(ctx, data || {});
+    };
+
+    save = async (ctx) => {
+      app.extends.db.setDBData("site-setting", ctx.request.body, {
+        namespace: "settings",
+      });
+
+      this.success(ctx, {});
+    };
+  };
+};
+```
+
+If the runtime does not support the built-in SQLite module or the project needs another store, generate `app/extend/db.js` or `app/extend/db.ts` and preserve the same method names so existing controllers keep working.
+
+## Dashboard Component Slot
+
+Use `frontend/extended/dash/components.tsx` to fill supported Dashboard slots. The current slot is:
+
+```text
+HeaderView.userArea
+```
+
+Example:
+
+```tsx
+import { LanguageSwitch, ThemeSwitch } from '@_tc/template-core/fe'
+import type { DashComponentsMap } from '@_tc/template-core/fe'
+
+const components = {
+  'HeaderView.userArea': ({ projectInfo }) => {
+    return (
+      <div className="flex items-center gap-2">
+        <span className="max-w-32 truncate text-xs text-muted-foreground">
+          {projectInfo?.name}
+        </span>
+        <LanguageSwitch />
+        <ThemeSwitch />
+      </div>
+    )
+  },
+} satisfies DashComponentsMap
+
+export default components
+```
+
+Keep header content compact; the default header already owns brand, title, and menu layout.
+
+## Dashboard Custom Routes
+
+Use `frontend/extended/dash/customRoutes.tsx` when a `custom` menu item needs a route inside the built-in Dashboard.
+
+```tsx
+import type { DashRoutesExtender } from '@_tc/template-core/fe'
+
+const extendDashRoutes: DashRoutesExtender = ({ topRoutes, sidebarRoutes }) => {
+  topRoutes.push({
+    path: '/custom-page',
+    component: <div>Custom Page</div>,
+  })
+
+  sidebarRoutes.push({
+    path: 'custom-sidebar-page',
+    component: <div>Custom Sidebar Page</div>,
+  })
+}
+
+export default extendDashRoutes
+```
+
+`topRoutes` are appended under `/dash`. `sidebarRoutes` are appended inside the default sidebar containers.
+
+## Frontend Helpers
+
+Import TemplateCore frontend helpers from `@_tc/template-core/fe`:
+
+```tsx
+import { AsyncSelect, LanguageSwitch, ThemeSwitch } from '@_tc/template-core/fe'
+```
+
+Import UI components from the published UI re-export:
+
+```tsx
+import { Button, DataTable, TableSearch } from '@_tc/template-core/fe/rc'
+```
+
+`LanguageSwitch` updates the shared i18n language and persists through `tc_language`. `ThemeSwitch` toggles the root `dark` class and persists through `tc_theme`. `AsyncSelect` loads options from a `fetchConfig` endpoint returning `{ label, value, searchText? }[]`.
+
+## SchemaForm Extensions
+
+TemplateCore already registers a framework SchemaForm type named `asyncSelect`. Use it in Schema CRUD model config when a field should fetch options from an API:
+
+```js
+owner_id: {
+  type: "string",
+  label: "Owner",
+  createFormOption: {
+    comType: "asyncSelect",
+    fetchConfig: {
+      url: "/user/options",
+      method: "get",
+    },
+  },
+  editFormOption: {
+    comType: "asyncSelect",
+    fetchConfig: {
+      url: "/user/options",
+      method: "get",
+    },
+  },
+}
+```
+
+The options controller should return the normal TemplateCore response wrapper:
+
+```js
+this.success(ctx, [
+  { label: "Alice", value: "u1" },
+  { label: "Bob", value: "u2" },
+]);
+```
+
+For project-specific field types, create `frontend/extended/SchemaForm/data.ts` and default-export a component map keyed by field type.
+
+## SchemaPage CallCom Extensions
+
+Use `frontend/extended/SchemaPage/CallCom/data.ts` when model `componentConfig` should open a custom runtime component instead of built-in create/edit/detail components. Custom components can import `schemaEventBus`, `eventsInfo`, and `merge` from `@_tc/template-core/fe` to close panels or refresh Schema tables.