@_tc/template-core 0.1.16 → 0.2.0-bate.1

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

@@ -31,8 +31,13 @@ Every input-like component supports both modes. Check for `value !== undefined`
 
 // Uncontrolled
 <Input defaultValue="hello" />
+
+// Password fields get a built-in show/hide toggle
+<Input type="password" value={password} onChange={setPassword} />
 ```
 
+For `type="password"`, do not add a separate eye icon or clear button. The built-in password toggle is automatic; `allowClear` is hidden on password inputs.
+
 ### 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:
@@ -93,7 +98,7 @@ modal.confirm({
 
 Read the reference files (progressive disclosure):
 
-- `reference/component-api.md` — Full props tables for every component
+- `reference/component-api.md` — Props tables for the main public components
 - `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
@@ -119,6 +124,8 @@ When consuming the published TemplateCore package, `@_tc/template-core/fe/rc` re
 import { Button, DataTable, TableSearch } from '@_tc/template-core/fe/rc'
 ```
 
+Inside this source repository, use `@tc/ui-react` for the raw UI workspace package. The `@_tc/template-core/fe/rc` path is a published TemplateCore package export generated into `dist/package.json`.
+
 Style entry:
 
 ```tsx
@@ -129,4 +136,4 @@ import '@_tc/template-core/fe/tailwind_ui.css'
 
 ## Visual Style
 
-For `packages/ui/react/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.
+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.

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

@@ -45,12 +45,15 @@ interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, '
   onChange?: (value: string, event: ChangeEvent<HTMLInputElement>) => void
   allowClear?: boolean | { clearIcon: ReactNode }
   addonAfter?: ReactNode
+  inputClassName?: string
   className?: string
 }
 ```
 
 Note: `onChange` callback receives `(stringValue, event)` — two arguments, not one.
 
+Use `type="password"` for password fields. The component shows a built-in visibility toggle, supports controlled and uncontrolled values, and removes the native DOM `value` attribute while preserving the input value property. `allowClear` is intentionally hidden for password inputs. `addonAfter` shares the right-side accessory area with the password toggle.
+
 ---
 
 ## InputNumber
@@ -310,7 +313,7 @@ interface SchemaFormProps<T> {
   buttonClassName?: string
   submitButtonProps?: Omit<ButtonElementProps, 'type' | 'onClick' | 'children'>
   cancelButtonProps?: Omit<ButtonElementProps, 'onClick' | 'children'>
-  preserve?: boolean                        // default: false
+  preserve?: boolean                        // passed through to rc-field-form; TemplateCore does not set a default
 }
 ```
 
@@ -709,8 +712,8 @@ Max 5 visible messages.
 
 ```typescript
 interface NotificationProps {
-  type: 'info' | 'success' | 'warning' | 'error'
-  title: ReactNode
+  type?: 'info' | 'success' | 'warning' | 'error'  // default: 'info'
+  title?: ReactNode
   message?: ReactNode
   duration?: number
   closable?: boolean

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

@@ -14,7 +14,7 @@ For TemplateCore component work, aim for a dark, restrained, collaboration-tool
 - 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/ui/react/components/VIDEO_UI_STYLE_GUIDE.md` is the fuller visual reference.
+When editing this repository, `packages/react/ui/components/VIDEO_UI_STYLE_GUIDE.md` is the fuller visual reference.
 
 ---
 
@@ -350,10 +350,10 @@ import { Notification } from '@tc/ui-react'
 
 ## Compound Component Pattern
 
-Three components use compound patterns with Context:
+Three component families use context-based composition:
 
 1. **Menu**: `<Menu>` + `<Menu.Item>` + `<Menu.SubMenu>` + `<Menu.CollapseToggle>`
-2. **Radio**: `<Radio.Group>` + `<Radio>`
+2. **Radio**: `<RadioGroup>` + `<Radio>`
 3. **Breadcrumb**: `<Breadcrumb>` + `<BreadcrumbList>` + `<BreadcrumbItem>` + ...
 
 Children auto-detect parent via Context and inherit configuration.

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

@@ -6,10 +6,12 @@ Use these when building business UI on top of TemplateCore, especially Dashboard
 
 ```tsx
 import { AsyncSelect, LanguageSwitch, ThemeSwitch } from '@_tc/template-core/fe'
+import { api, get, post, request } from '@_tc/template-core/fe/common/request'
+import type { BaseResponse, RequestConfig, ResponseConfig } from '@_tc/template-core/fe/common/request'
 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.
+Inside this repository, use `@tc/ui-react` for the raw UI workspace package. In published business projects, prefer `@_tc/template-core/fe/rc` for UI components, `@_tc/template-core/fe` for frontend runtime helpers, and `@_tc/template-core/fe/common/request` when only the request layer is needed.
 
 ## LanguageSwitch
 
@@ -17,7 +19,7 @@ Inside this repository, `@tc/ui-react` is also valid for the raw UI library. In
 <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.
+Default languages are `zh-CN` and `en-US`. Pass `options` to replace the list. The current UI is a button-triggered dropdown; `option.label` can be a ReactNode and `buttonClassName` customizes the trigger. `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:
 
@@ -29,6 +31,13 @@ interface LanguageSwitchProps {
   defaultValue?: LanguageSwitchValue
   options?: Array<{ label: ReactNode; value: LanguageSwitchValue; searchText?: string }>
   onChange?: (language: LanguageSwitchValue) => void
+  disabled?: boolean
+  loading?: boolean
+  placeholder?: string
+  clearable?: boolean
+  searchable?: boolean
+  buttonClassName?: string
+  getPopupContainer?: (() => HTMLElement) | 'parent'
 }
 ```
 

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

@@ -28,10 +28,11 @@ 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. Do not `await` it; the current API starts the build/dev process and returns `void`.
+- Start the built-in frontend with `await buildFE("dev")` from `@_tc/template-core/bundler` when the user needs the admin UI. The current API returns `Promise<void>`; in dev mode it performs the initial build, then watches the business `frontend/` directory. Use `buildFE("prod", { output: "run", minifyHtml: true })` when the generated project should emit its own `app/public/dist` templates and compact final `.tpl` output.
+- `buildFE()` writes `FEBuildKey` into the output directory; the server uses it to invalidate local HTML ETag cache after frontend rebuilds.
 - 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.
+- The framework provides `app.extends.db` as a default SQLite-backed KV/SQL helper. Use it for small framework/business settings; override `app/extends/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`

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

@@ -34,7 +34,7 @@ async function main() {
     baseDir: join(__dirname, "."),
   });
 
-  buildFE("dev");
+  await buildFE("dev");
 }
 
 main().catch((error) => {
@@ -48,6 +48,10 @@ main().catch((error) => {
 ```js
 module.exports = {
   port: 9000,
+  auth: {
+    ATKey: "Authorization",
+    RTKey: "RT",
+  },
 };
 ```
 

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

@@ -1,5 +1,9 @@
 module.exports = {
   port: 9000,
+  auth: {
+    ATKey: "Authorization",
+    RTKey: "RT",
+  },
   // 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, "."),
   });
 
-  buildFE("dev");
+  await buildFE("dev");
 }
 
 main().catch((error) => {

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

@@ -1,5 +1,7 @@
 module.exports = {
   name: "Default Product Project",
   desc: "Project-level overrides can be added here.",
+  // Single-project scaffolds can include projk directly. For shared multi-project
+  // models, prefer keeping mode.js project-neutral and override homePage per project.
   homePage: "/_sidebar_/product?projk=default",
 };

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

@@ -74,7 +74,75 @@ module.exports = (app) => {
 };
 ```
 
-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.
+If the runtime does not support the built-in SQLite module or the project needs another store, generate `app/extends/db.js` or `app/extends/db.ts` and preserve the same method names so existing controllers keep working.
+
+## Default Crypto
+
+`app.extends.crypto` is available by default for backend code. It uses `app.config.signKey` as the default signing secret.
+
+Use it for lightweight signed payloads, auth tokens, API signatures, base64url encoding, and constant-time string comparison.
+
+Common methods:
+
+```ts
+app.extends.crypto.base64urlEncode(value)
+app.extends.crypto.base64urlDecode(value)
+app.extends.crypto.base64urlDecodeToBuffer(value)
+app.extends.crypto.hmacSign(payload, { secret, algorithm })
+app.extends.crypto.safeEqual(left, right)
+app.extends.crypto.createSignedPayload(payload, { secret, algorithm, separator })
+app.extends.crypto.verifySignedPayload(token, { secret, algorithm, separator })
+```
+
+Signed payload example:
+
+```js
+module.exports = (app) => {
+  return class AuthService {
+    createToken(account) {
+      const now = Date.now();
+
+      return app.extends.crypto.createSignedPayload({
+        account,
+        exp: now + 1000 * 60 * 60 * 24 * 7,
+        iat: now,
+      });
+    }
+
+    verifyToken(token) {
+      const payload = app.extends.crypto.verifySignedPayload(
+        token && token.replace(/^Bearer\s+/i, "")
+      );
+
+      if (!payload || Date.now() > payload.exp) return null;
+
+      return payload;
+    }
+
+    comparePassword(inputPassword, storedPassword) {
+      return app.extends.crypto.safeEqual(inputPassword, storedPassword);
+    }
+  };
+};
+```
+
+Custom signing options:
+
+```js
+const token = app.extends.crypto.createSignedPayload(
+  { id: 1, scope: "admin" },
+  {
+    secret: "custom-secret",
+    algorithm: "sha512",
+    separator: ".",
+  }
+);
+
+const payload = app.extends.crypto.verifySignedPayload(token, {
+  secret: "custom-secret",
+  algorithm: "sha512",
+});
+```
 
 ## Dashboard Component Slot
 
@@ -109,6 +177,20 @@ export default components
 
 Keep header content compact; the default header already owns brand, title, and menu layout.
 
+## Server Router Guard
+
+Use `app/router-guard.js` or `app/router-guard.ts` in the generated business project when unmatched server paths need custom fallback behavior. The file lives directly under the business `app/` directory.
+
+```js
+module.exports = (app) => (ctx) => {
+  if (!ctx.path.startsWith(app.options.apiPrefix || '/api')) {
+    return '/dash'
+  }
+}
+```
+
+The guard runs only from the final catch-all router after normal `app/router/*` routes fail to match. Return a string to redirect, return `{ status, body }` to send a custom response, or return nothing to keep the default fallback: API paths return HTTP 200 with `{ code: 404, message }`, while non-API paths return HTTP 404 with `notFound`.
+
 ## Dashboard Custom Routes
 
 Use `frontend/extended/dash/customRoutes.tsx` when a `custom` menu item needs a route inside the built-in Dashboard.
@@ -133,6 +215,22 @@ export default extendDashRoutes
 
 `topRoutes` are appended under `/dash`. `sidebarRoutes` are appended inside the default sidebar containers.
 
+## Dashboard Route Guard
+
+Use `frontend/extended/dash/routeGuard.ts` when the built-in Dashboard needs a one-time guard before its default `homePage` or first-menu redirect.
+
+```ts
+import type { DashRouteGuard } from '@_tc/template-core/fe'
+
+const dashRouteGuard: DashRouteGuard = ({ isLoggedIn }) => {
+  if (!isLoggedIn) return '/login'
+}
+
+export default dashRouteGuard
+```
+
+Return a login URL string when the framework should jump with `window.location.href`; the login page does not need to be inside Dash routes. `DashRouteGuardResult` is `string | undefined`, and `undefined` also interrupts the built-in Dashboard redirect, including the implicit return from a logged-in branch.
+
 ## Frontend Helpers
 
 Import TemplateCore frontend helpers from `@_tc/template-core/fe`:
@@ -141,13 +239,25 @@ Import TemplateCore frontend helpers from `@_tc/template-core/fe`:
 import { AsyncSelect, LanguageSwitch, ThemeSwitch } from '@_tc/template-core/fe'
 ```
 
+Request helpers and request types are available from the root frontend entry or the explicit request subpath:
+
+```ts
+import { api, get, post, request } from '@_tc/template-core/fe'
+import type { BaseResponse, RequestConfig, ResponseConfig } from '@_tc/template-core/fe'
+
+import { api as requestApi } from '@_tc/template-core/fe/common/request'
+import type { BaseResponse as ApiResponse } from '@_tc/template-core/fe/common/request'
+```
+
 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? }[]`.
+Inside this source repository, use `@tc/ui-react` for the raw UI workspace package. The `@_tc/template-core/fe/rc` path is for published TemplateCore consumers.
+
+`LanguageSwitch` is a button-triggered dropdown that updates the shared i18n language and persists through `tc_language`; use `buttonClassName` when the trigger needs custom sizing or styling. `ThemeSwitch` toggles the root `dark` class and persists through `tc_theme`. `AsyncSelect` loads options from a `fetchConfig` endpoint returning `{ label, value, searchText? }[]`.
 
 ## SchemaForm Extensions