@pylonts/dsl 1.1.1 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
   "type": "module",
   "main": "src/index.ts",
@@ -28,4 +28,4 @@
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   }
-}
+}

package/src/action.ts

@@ -0,0 +1,11 @@
+import { SchemaBase } from './dsl.js';
+
+/** An action a user can perform on a page (e.g. submit, approve, reject).
+ *  Subclasses use `type` as the discriminator. */
+export interface ActionSchema extends SchemaBase {
+  type: string;
+}
+
+export function defineAction(name: string, description?: string): ActionSchema {
+  return { name, description, type: 'gesture' };
+}

package/src/asset.ts

@@ -1,63 +1,63 @@
-/**
- * defineAsset — registry for reusable project assets (utils, components, flows, pages, hooks).
- *
- * Each asset declares its name, category, import path, tags, and optional usage example.
- * CLI scans all asset declarations, supports query (by tag/category) and generate (import links).
- *
- *   // assets/utils.assets.ts
- *   import { defineAsset } from '@pylonts/dsl';
- *   export const formatAmt = defineAsset({
- *     name: 'formatAmt',
- *     category: 'util',
- *     tags: ['amount', 'format'],
- *     import: { name: 'formatAmt', from: '@/utils/amount' },
- *     example: 'formatAmt(12345) => "12,345.00"',
- *   });
- *
- *   // CLI:
- *   // gen-cli asset list --tag form       → all form-related assets
- *   // gen-cli asset import formatAmt      → import { formatAmt } from '@/utils/amount';
- */
-
-export type AssetCategory = 'util' | 'component' | 'flow' | 'page' | 'hook';
-
-export interface AssetImport {
-  /** Named export, e.g. 'formatAmt' */
-  name: string;
-  /** Module path, e.g. '@/utils/amount' */
-  from: string;
-}
-
-export interface AssetConfig {
-  name: string;
-  category: AssetCategory;
-  tags: string[];
-  import: AssetImport;
-  description?: string;
-  /** One-liner usage example */
-  example?: string;
-  /** Link to detailed docs */
-  see?: string;
-}
-
-export interface AssetDef {
-  name: string;
-  category: AssetCategory;
-  tags: string[];
-  import: AssetImport;
-  description?: string;
-  example?: string;
-  see?: string;
-}
-
-export function defineAsset(config: AssetConfig): AssetDef {
-  return {
-    name: config.name,
-    category: config.category,
-    tags: config.tags,
-    import: config.import,
-    description: config.description,
-    example: config.example,
-    see: config.see,
-  };
-}
+/**
+ * defineAsset — registry for reusable project assets (utils, components, flows, pages, hooks).
+ *
+ * Each asset declares its name, category, import path, tags, and optional usage example.
+ * CLI scans all asset declarations, supports query (by tag/category) and generate (import links).
+ *
+ *   // assets/utils.assets.ts
+ *   import { defineAsset } from '@pylonts/dsl';
+ *   export const formatAmt = defineAsset({
+ *     name: 'formatAmt',
+ *     category: 'util',
+ *     tags: ['amount', 'format'],
+ *     import: { name: 'formatAmt', from: '@/utils/amount' },
+ *     example: 'formatAmt(12345) => "12,345.00"',
+ *   });
+ *
+ *   // CLI:
+ *   // pylonts gen asset list --tag form       → all form-related assets
+ *   // pylonts gen asset import formatAmt      → import { formatAmt } from '@/utils/amount';
+ */
+
+export type AssetCategory = 'util' | 'component' | 'flow' | 'page' | 'hook';
+
+export interface AssetImport {
+  /** Named export, e.g. 'formatAmt' */
+  name: string;
+  /** Module path, e.g. '@/utils/amount' */
+  from: string;
+}
+
+export interface AssetConfig {
+  name: string;
+  category: AssetCategory;
+  tags: string[];
+  import: AssetImport;
+  description?: string;
+  /** One-liner usage example */
+  example?: string;
+  /** Link to detailed docs */
+  see?: string;
+}
+
+export interface AssetDef {
+  name: string;
+  category: AssetCategory;
+  tags: string[];
+  import: AssetImport;
+  description?: string;
+  example?: string;
+  see?: string;
+}
+
+export function defineAsset(config: AssetConfig): AssetDef {
+  return {
+    name: config.name,
+    category: config.category,
+    tags: config.tags,
+    import: config.import,
+    description: config.description,
+    example: config.example,
+    see: config.see,
+  };
+}

package/src/bases.ts

@@ -1,30 +1,30 @@
-import type { DtoMessage, ImportBase, ImportRef } from './dto.js';
-
-// Named base-schema references for common protocol DTOs.
-//
-// These are ImportRef metadata (not re-exports of the actual TypeBox schemas):
-// the DSL stores { from, name } so the generator can emit the import line and
-// the identifier — the runtime schema object itself is never loaded by the DSL.
-//
-// `import { PageRequest } from '@pylonts/dsl'` therefore gives .include() an
-// already-resolved reference — no static analysis or name lookup needed.
-
-/** Paginated query request base — renders `import { PageRequest } from '@pylonts/core'` + Intersect */
-export const PageRequest: ImportBase = { from: '@pylonts/core', name: 'PageRequest' };
-
-/** Paginated list response base — renders `import { PageResult } from '@pylonts/core'` + `PageResult(<row>)` */
-export const PageResult = (row: DtoMessage): ImportRef => ({
-  from: '@pylonts/core',
-  name: 'PageResult',
-  args: [row],
-});
-
-/** Paged rows type base without generic args — renders `import { PagedRows } from '@pylonts/core'` */
-export const PagedRows: ImportBase = { from: '@pylonts/core', name: 'PagedRows' };
-
-/** Paged rows type base — renders `import { PagedRows } from '@pylonts/core'` + `PagedRows(<row>)` */
-export const PageRows = (row: DtoMessage): ImportRef => ({
-  from: '@pylonts/core',
-  name: 'PagedRows',
-  args: [row],
+import type { DtoMessage, ImportBase, ImportRef } from './dto.js';
+
+// Named base-schema references for common protocol DTOs.
+//
+// These are ImportRef metadata (not re-exports of the actual TypeBox schemas):
+// the DSL stores { from, name } so the generator can emit the import line and
+// the identifier — the runtime schema object itself is never loaded by the DSL.
+//
+// `import { PageRequest } from '@pylonts/dsl'` therefore gives .include() an
+// already-resolved reference — no static analysis or name lookup needed.
+
+/** Paginated query request base — renders `import { PageRequest } from '@pylonts/core'` + Intersect */
+export const PageRequest: ImportBase = { from: '@pylonts/core', name: 'PageRequest' };
+
+/** Paginated list response base — renders `import { PageResult } from '@pylonts/core'` + `PageResult(<row>)` */
+export const PageResult = (row: DtoMessage): ImportRef => ({
+  from: '@pylonts/core',
+  name: 'PageResult',
+  args: [row],
+});
+
+/** Paged rows type base without generic args — renders `import { PagedRows } from '@pylonts/core'` */
+export const PagedRows: ImportBase = { from: '@pylonts/core', name: 'PagedRows' };
+
+/** Paged rows type base — renders `import { PagedRows } from '@pylonts/core'` + `PagedRows(<row>)` */
+export const PageRows = (row: DtoMessage): ImportRef => ({
+  from: '@pylonts/core',
+  name: 'PagedRows',
+  args: [row],
 });

package/src/component.ts

@@ -0,0 +1,22 @@
+import type { SchemaBase } from './dsl.js';
+import type { RefSchema } from './ref.js';
+import type { ActionSchema } from './action.js';
+import type { EventDataSchema } from './event.js';
+
+/** A component event trigger declaration. */
+export interface TriggerSchema extends SchemaBase {
+  /** Data the event carries (e.g. e.detail). */
+  eventData?: EventDataSchema;
+  /** Actions that fire when the event occurs. */
+  actions?: ActionSchema[];
+}
+
+/** A UI component declaration — a virtual schema that describes props and
+ *  event triggers, not a real renderable component.
+ *
+ *  properties: data bindings via RefSchema (or literal values).
+ *  triggers: event name → TriggerSchema bindings. */
+export interface ComponentSchema extends SchemaBase {
+  properties: Record<string, RefSchema | string | number | boolean>;
+  triggers: Record<string, TriggerSchema>;
+}

package/src/convert.ts

@@ -0,0 +1,13 @@
+import type { SchemaBase } from './dsl.js';
+
+/** Declares post-call result → page data field mapping.
+ *  Driver generates per-item transform (e.g. .map()) before setData. */
+export interface ConvertSchema extends SchemaBase {
+  type: 'convert';
+  /** { targetField: sourceField } — renames or copies fields from call result. */
+  fields: Record<string, string>;
+}
+
+export function defineConvert(name: string, fields: Record<string, string>): ConvertSchema {
+  return { name, type: 'convert', fields };
+}

package/src/curd.ts

@@ -1,92 +1,94 @@
-import { SchemaBase, Field, Operator } from './dsl.js';
-import { TableSchema } from './db.js';
-import { FrontAppSchema } from './project.js';
-import { ActionSchema } from './page.js';
-
-// Admin-only CRUD page standard: binds one entity table to a frontend admin
-// app, describing everything needed to generate the list page plus optional
-// add/update/detail pages. Field-level columns are plain Field instances
-// (table fields, cross-table refs allowed) — DTOs are derived by the generator,
-// the schema itself never references DtoMessage.
-
-/** Mode of an action page: modal dialog or standalone route. */
-export type ActionPageMode = 'modal' | 'route';
-
-/** One CRUD action page (add / update / detail). */
-export interface ActionPage {
-  mode: ActionPageMode;
-  /** Fields rendered on this page. Required, non-empty — every field the
-   *  frontend shows must be listed explicitly. */
-  columns: Field[];
-}
-
-/** List page configuration. */
-export interface CurdListConfig {
-  /** List columns; required, non-empty. Every field the list shows must be
-   *  listed explicitly. May include cross-table fields via foreign refs. */
-  columns: Field[];
-  /** Fuzzy keyword search on this table's columns. */
-  keyword?: { columns: Field[] };
-  /** Default sort. Required — column and direction are both mandatory. */
-  orderBy: { column: Field; direction: 'asc' | 'desc' };
-  /** Search condition fields; op defaults to 'eq'. */
-  searchFields?: { field: Field; op?: Operator }[];
-  /** Column header text overrides: Field.name → header text. */
-  columnTitles?: Record<string, string>;
-}
-
-/** Admin-only CRUD page standard: binds one entity table to a frontend
- *  admin app. Drives generation of the list page plus optional
- *  add/update/detail pages. */
-export interface CurdSchema extends SchemaBase {
-  /** The admin frontend app this CRUD belongs to (shared instance, type must be 'admin'). */
-  app: FrontAppSchema;
-  /** The bound entity table (shared instance). */
-  table: TableSchema;
-  /** List page Chinese title. */
-  title: string;
-  /** Sidebar menu section (group) this CRUD page belongs to. */
-  section: string;
-  /** Extra user actions on this page (beyond the standard CRUD). */
-  actions?: ActionSchema[];
-  /** Add/update/detail action pages. */
-  actionPages?: {
-    add?: ActionPage;
-    update?: ActionPage;
-    detail?: ActionPage;
-  };
-  list: CurdListConfig;
-}
-
-function assertColumns(curd: CurdSchema, pageName: string, columns: Field[]): void {
-  if (columns.length === 0) {
-    throw new Error(`curd ${curd.name}: ${pageName}.columns must be non-empty`);
-  }
-}
-
-function assertFieldsOwnTable(curd: CurdSchema, label: string, fields: Field[]): void {
-  for (const f of fields) {
-    if (f.schema !== curd.table) {
-      throw new Error(`curd ${curd.name}: ${label} field ${f.name} does not belong to table ${curd.table.name}`);
-    }
-  }
-}
-
-/** Defines an admin CRUD page standard. Runtime-validates admin app binding,
- *  non-empty columns and table field ownership (same style as defineTable). */
-export function defineCurd(name: string, schema: Omit<CurdSchema, 'name'>): CurdSchema {
-  const curd: CurdSchema = { name, ...schema };
-  if (curd.app.type !== 'admin') {
-    throw new Error(`curd ${name}: app ${curd.app.name} must be type 'admin' (got '${curd.app.type}')`);
-  }
-  if (!curd.section) {
-    throw new Error(`curd ${name}: section is required (sidebar menu group, e.g. '商户管理')`);
-  }
-  assertColumns(curd, 'list', curd.list.columns);
-  for (const [pageName, page] of Object.entries(curd.actionPages ?? {})) {
-    if (page) assertColumns(curd, `actionPages.${pageName}`, page.columns);
-  }
-  assertFieldsOwnTable(curd, 'keyword', curd.list.keyword?.columns ?? []);
-  assertFieldsOwnTable(curd, 'orderBy', [curd.list.orderBy.column]);
-  return curd;
+import { SchemaBase, Field, Operator } from './dsl.js';
+import { TableSchema } from './db.js';
+import { FrontAppSchema } from './project.js';
+import { ActionSchema } from './action.js';
+
+// Admin-only CRUD page standard: binds one entity table to a frontend admin
+// app, describing everything needed to generate the list page plus optional
+// add/update/detail pages. Field-level columns are plain Field instances
+// (table fields, cross-table refs allowed) — DTOs are derived by the generator,
+// the schema itself never references DtoMessage.
+
+/** Mode of an action page: modal dialog or standalone route. */
+export type ActionPageMode = 'modal' | 'route';
+
+/** One CRUD action page (add / update / detail). */
+export interface ActionPage {
+  mode: ActionPageMode;
+  /** For add/update: when true, render as modal on list page; when false/undefined, render as standalone route page. */
+  modal?: boolean;
+  /** Fields rendered on this page. Required, non-empty — every field the
+   *  frontend shows must be listed explicitly. */
+  columns: Field[];
+}
+
+/** List page configuration. */
+export interface CurdListConfig {
+  /** List columns; required, non-empty. Every field the list shows must be
+   *  listed explicitly. May include cross-table fields via foreign refs. */
+  columns: Field[];
+  /** Fuzzy keyword search on this table's columns. */
+  keyword?: { columns: Field[] };
+  /** Default sort. Required — column and direction are both mandatory. */
+  orderBy: { column: Field; direction: 'asc' | 'desc' };
+  /** Search condition fields; op defaults to 'eq'. */
+  searchFields?: { field: Field; op?: Operator }[];
+  /** Column header text overrides: Field.name → header text. */
+  columnTitles?: Record<string, string>;
+}
+
+/** Admin-only CRUD page standard: binds one entity table to a frontend
+ *  admin app. Drives generation of the list page plus optional
+ *  add/update/detail pages. */
+export interface CurdSchema extends SchemaBase {
+  /** The admin frontend app this CRUD belongs to (shared instance, type must be 'admin'). */
+  app: FrontAppSchema;
+  /** The bound entity table (shared instance). */
+  table: TableSchema;
+  /** List page Chinese title. */
+  title: string;
+  /** Sidebar menu section (group) this CRUD page belongs to. */
+  section: string;
+  /** Extra user actions on this page (beyond the standard CRUD). */
+  actions?: ActionSchema[];
+  /** Add/update/detail action pages. */
+  actionPages?: {
+    add?: ActionPage;
+    update?: ActionPage;
+    detail?: ActionPage;
+  };
+  list: CurdListConfig;
+}
+
+function assertColumns(curd: CurdSchema, pageName: string, columns: Field[]): void {
+  if (columns.length === 0) {
+    throw new Error(`curd ${curd.name}: ${pageName}.columns must be non-empty`);
+  }
+}
+
+function assertFieldsOwnTable(curd: CurdSchema, label: string, fields: Field[]): void {
+  for (const f of fields) {
+    if (f.schema !== curd.table) {
+      throw new Error(`curd ${curd.name}: ${label} field ${f.name} does not belong to table ${curd.table.name}`);
+    }
+  }
+}
+
+/** Defines an admin CRUD page standard. Runtime-validates admin app binding,
+ *  non-empty columns and table field ownership (same style as defineTable). */
+export function defineCurd(name: string, schema: Omit<CurdSchema, 'name'>): CurdSchema {
+  const curd: CurdSchema = { name, ...schema };
+  if (curd.app.type !== 'admin') {
+    throw new Error(`curd ${name}: app ${curd.app.name} must be type 'admin' (got '${curd.app.type}')`);
+  }
+  if (!curd.section) {
+    throw new Error(`curd ${name}: section is required (sidebar menu group, e.g. '商户管理')`);
+  }
+  assertColumns(curd, 'list', curd.list.columns);
+  for (const [pageName, page] of Object.entries(curd.actionPages ?? {})) {
+    if (page) assertColumns(curd, `actionPages.${pageName}`, page.columns);
+  }
+  assertFieldsOwnTable(curd, 'keyword', curd.list.keyword?.columns ?? []);
+  assertFieldsOwnTable(curd, 'orderBy', [curd.list.orderBy.column]);
+  return curd;
 }

package/src/db.ts

@@ -25,6 +25,8 @@ export interface TableSchemaOptions<
   actor?: boolean;
   generator?: string;
   autoIncrement?: Field;
+  /** 本表用于关联显示的名称字段（如 name / username）。被外键引用时，自动用该字段做 label 展示。 */
+  label?: Field;
   primaryKey?: Field | Field[];
   indexes?: Index[];
   foreignKeys?: Record<string, ForeignKey>;
@@ -55,6 +57,8 @@ export class TableSchema<
   indexes?: Index[];
   /** 外键，引用其他表的字段 */
   foreignKeys?: Record<string, ForeignKey>;
+  /** 本表用于关联显示的名称字段（如 name / username）。被外键引用时，自动用该字段做 label 展示。 */
+  label?: Field;
   /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
   phrase?: EntityPhrase;
   /** 本表引用的所有枚举定义（map，key 为枚举标识），显式声明供 gen-enums 收集 */
@@ -74,6 +78,7 @@ export class TableSchema<
     this.primaryKey = options.primaryKey;
     this.indexes = options.indexes;
     this.foreignKeys = options.foreignKeys;
+    this.label = options.label;
     this.phrase = options.phrase;
     this.enums = options.enums;
     this.columns = options.columns;
@@ -97,6 +102,12 @@ export function defineTable<
   schema: TableSchemaOptions<N, C, E>,
 ): TableSchema<N, C, E> {
   const table = new TableSchema<N, C, E>(name, schema);
+  if (table.generator && table.autoIncrement) {
+    throw new Error(`table '${name}': generator and autoIncrement are mutually exclusive`);
+  }
+  if (table.label && !Object.values(table.columns).includes(table.label)) {
+    throw new Error(`table '${name}': label field '${table.label.name}' must be one of the table's columns`);
+  }
   for (const key of Object.keys(table.columns)) {
     const field = table.columns[key] as Field;
     if (field.schema && field.schema !== table) {