@stonecrop/schema 0.11.9 → 0.12.0

package/README.md

@@ -430,7 +430,7 @@ This package provides the type system used throughout Stonecrop:
 - **`@stonecrop/stonecrop`** - Registry uses `DoctypeMeta` for schema storage; `getDescendantLinks()` / `getAncestorLinks()` for relationship traversal
 - **`@stonecrop/graphql-client`** - `StonecropClient` implements `DataClient`; uses `GetRecordOptions` / `GetRecordsOptions` for fetch parameters
 - **`@stonecrop/aform`** - Renders fields based on `FieldMeta` definitions
-- **`@stonecrop/atable`** - Uses `FieldMeta` for column configuration
+- **`@stonecrop/atable`** - Uses `ColumnSchema` for schema-driven column derivation; `TableColumn` (ATable's runtime column type) extends `ColumnSchema`, widening `format`/`modalComponent` to accept live functions and adding `mask`/`originalIndex`
 - **Backend APIs** - Validates and stores doctypes using these schemas
 
 ## Development

package/dist/schema.d.ts

@@ -109,6 +109,154 @@ export declare type Cardinality = z.infer<typeof Cardinality>;
  */
 export declare function classifyFieldType(fieldName: string, field: GraphQLField<unknown, unknown>, entityTypes: Set<string>, options?: GraphQLConversionOptions): GraphQLConversionFieldMeta;
 
+/**
+ * Authoring contract for doctype field declarations that can be rendered as table columns.
+ * Pass a `ColumnSchema[]` array to ATable's `:schema` prop; `schemaToColumns` converts it
+ * to `TableColumn[]` internally — callers working from a doctype schema never need to
+ * construct `TableColumn` directly.
+ *
+ * Notes on specific properties:
+ * - `align` uses an explicit string union rather than `CanvasTextAlign` — this package is
+ *   used server-side by the CLI where browser DOM types are absent. The values are identical.
+ * - `format` is a serialized function string; the table store's `getFormattedValue` deserializes
+ *   it via `Function(...)`. `TableColumn.format` widens this to also accept a live function.
+ * - `mask` is absent — it is function-typed only and cannot be serialized to JSON. It lives
+ *   exclusively on `TableColumn`.
+ * - `modalComponent` is string-only — functions cannot appear in schema JSON. `TableColumn`
+ *   widens this to also accept a factory function.
+ *
+ * @public
+ */
+export declare interface ColumnSchema {
+    /** Unique identifier for the field within its doctype. Maps to `name` on `TableColumn`. */
+    fieldname: string;
+    /**
+     * Semantic field type (e.g. `'Data'`, `'Int'`, `'Date'`, `'Check'`). Fields without a
+     * `fieldtype` are treated as non-scalar (nested table or fieldset) and excluded by
+     * `schemaToColumns`.
+     */
+    fieldtype?: string;
+    /**
+     * Human-readable column header. When absent, ATable assigns labels alphabetically
+     * (A, B, C, …).
+     */
+    label?: string;
+    /** When `true`, the field is excluded from the derived columns by `schemaToColumns`. */
+    hidden?: boolean;
+    /**
+     * Horizontal text alignment for the column cell and header.
+     *
+     * @defaultValue 'left'
+     */
+    align?: 'left' | 'right' | 'center' | 'start' | 'end';
+    /**
+     * Whether the column cell is editable in the table.
+     *
+     * @defaultValue false
+     */
+    edit?: boolean;
+    /**
+     * CSS width of the column (e.g. `'20ch'`, `'200px'`).
+     *
+     * @defaultValue '40ch'
+     */
+    width?: string;
+    /**
+     * When `true`, the column is pinned to the left side of the table.
+     *
+     * @defaultValue false
+     */
+    pinned?: boolean;
+    /**
+     * When `true`, the column can be resized by dragging the header edge.
+     *
+     * @defaultValue false
+     */
+    resizable?: boolean;
+    /**
+     * When `true`, clicking the column header sorts the table by this column.
+     *
+     * @defaultValue true
+     */
+    sortable?: boolean;
+    /**
+     * When `true`, a filter control is rendered in the column header.
+     *
+     * @defaultValue true
+     */
+    filterable?: boolean;
+    /**
+     * The type of filter control to render. When absent, a default is derived from `fieldtype`
+     * (`Check` → `checkbox`, `Date` → `date`, `Datetime` → `dateRange`, `Select` → `select`,
+     * numeric types → `number`, everything else → `text`).
+     */
+    filterType?: 'text' | 'select' | 'number' | 'date' | 'dateRange' | 'checkbox' | 'component';
+    /**
+     * Static option list for `filterType: 'select'`. When absent, options are derived from
+     * the unique values present in the column's rows.
+     */
+    filterOptions?: any[];
+    /** Registered component name used when `filterType` is `'component'`. */
+    filterComponent?: string;
+    /**
+     * Registered component name rendered inside the table cell instead of the default display.
+     * When absent, the table renders the value as plain text in a `<td>`.
+     */
+    cellComponent?: string;
+    /**
+     * Additional props passed to `cellComponent`.
+     *
+     * Only applicable when `cellComponent` is set.
+     */
+    cellComponentProps?: Record<string, any>;
+    /**
+     * Registered component name rendered in the cell's modal editor. String-only — functions
+     * cannot appear in schema JSON. `TableColumn.modalComponent` widens this to also accept a
+     * factory function.
+     *
+     * The following props are automatically passed to the modal component:
+     * - `colIndex` — the column index of the current cell
+     * - `rowIndex` — the row index of the current cell
+     * - `store` — the table data store
+     */
+    modalComponent?: string;
+    /**
+     * Extra props passed to `modalComponent` in addition to the standard cell props.
+     *
+     * Only applicable when `modalComponent` is set.
+     */
+    modalComponentExtraProps?: Record<string, any>;
+    /**
+     * Serialized function string used to format the cell value for display. Deserialized at
+     * render time by the table store's `getFormattedValue`. `TableColumn.format` widens this
+     * to also accept a live function directly.
+     */
+    format?: string;
+    /**
+     * When `true`, this column is treated as a Gantt bar column.
+     *
+     * Only applicable for Gantt tables.
+     *
+     * @defaultValue false
+     */
+    isGantt?: boolean;
+    /**
+     * Registered component name used to render Gantt bars in this column.
+     *
+     * Only applicable for Gantt tables.
+     *
+     * @defaultValue 'AGanttCell'
+     */
+    ganttComponent?: string;
+    /**
+     * Number of columns this Gantt bar spans across. When absent, the bar stretches to cover
+     * all non-pinned columns in the table.
+     *
+     * Only applicable for Gantt tables.
+     */
+    colspan?: number;
+}
+
 /**
  * Output of GraphQL schema conversion — one per entity type.
  *

package/dist/src/column-schema.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Authoring contract for doctype field declarations that can be rendered as table columns.
+ * Pass a `ColumnSchema[]` array to ATable's `:schema` prop; `schemaToColumns` converts it
+ * to `TableColumn[]` internally — callers working from a doctype schema never need to
+ * construct `TableColumn` directly.
+ *
+ * Notes on specific properties:
+ * - `align` uses an explicit string union rather than `CanvasTextAlign` — this package is
+ *   used server-side by the CLI where browser DOM types are absent. The values are identical.
+ * - `format` is a serialized function string; the table store's `getFormattedValue` deserializes
+ *   it via `Function(...)`. `TableColumn.format` widens this to also accept a live function.
+ * - `mask` is absent — it is function-typed only and cannot be serialized to JSON. It lives
+ *   exclusively on `TableColumn`.
+ * - `modalComponent` is string-only — functions cannot appear in schema JSON. `TableColumn`
+ *   widens this to also accept a factory function.
+ *
+ * @public
+ */
+export interface ColumnSchema {
+    /** Unique identifier for the field within its doctype. Maps to `name` on `TableColumn`. */
+    fieldname: string;
+    /**
+     * Semantic field type (e.g. `'Data'`, `'Int'`, `'Date'`, `'Check'`). Fields without a
+     * `fieldtype` are treated as non-scalar (nested table or fieldset) and excluded by
+     * `schemaToColumns`.
+     */
+    fieldtype?: string;
+    /**
+     * Human-readable column header. When absent, ATable assigns labels alphabetically
+     * (A, B, C, …).
+     */
+    label?: string;
+    /** When `true`, the field is excluded from the derived columns by `schemaToColumns`. */
+    hidden?: boolean;
+    /**
+     * Horizontal text alignment for the column cell and header.
+     *
+     * @defaultValue 'left'
+     */
+    align?: 'left' | 'right' | 'center' | 'start' | 'end';
+    /**
+     * Whether the column cell is editable in the table.
+     *
+     * @defaultValue false
+     */
+    edit?: boolean;
+    /**
+     * CSS width of the column (e.g. `'20ch'`, `'200px'`).
+     *
+     * @defaultValue '40ch'
+     */
+    width?: string;
+    /**
+     * When `true`, the column is pinned to the left side of the table.
+     *
+     * @defaultValue false
+     */
+    pinned?: boolean;
+    /**
+     * When `true`, the column can be resized by dragging the header edge.
+     *
+     * @defaultValue false
+     */
+    resizable?: boolean;
+    /**
+     * When `true`, clicking the column header sorts the table by this column.
+     *
+     * @defaultValue true
+     */
+    sortable?: boolean;
+    /**
+     * When `true`, a filter control is rendered in the column header.
+     *
+     * @defaultValue true
+     */
+    filterable?: boolean;
+    /**
+     * The type of filter control to render. When absent, a default is derived from `fieldtype`
+     * (`Check` → `checkbox`, `Date` → `date`, `Datetime` → `dateRange`, `Select` → `select`,
+     * numeric types → `number`, everything else → `text`).
+     */
+    filterType?: 'text' | 'select' | 'number' | 'date' | 'dateRange' | 'checkbox' | 'component';
+    /**
+     * Static option list for `filterType: 'select'`. When absent, options are derived from
+     * the unique values present in the column's rows.
+     */
+    filterOptions?: any[];
+    /** Registered component name used when `filterType` is `'component'`. */
+    filterComponent?: string;
+    /**
+     * Registered component name rendered inside the table cell instead of the default display.
+     * When absent, the table renders the value as plain text in a `<td>`.
+     */
+    cellComponent?: string;
+    /**
+     * Additional props passed to `cellComponent`.
+     *
+     * Only applicable when `cellComponent` is set.
+     */
+    cellComponentProps?: Record<string, any>;
+    /**
+     * Registered component name rendered in the cell's modal editor. String-only — functions
+     * cannot appear in schema JSON. `TableColumn.modalComponent` widens this to also accept a
+     * factory function.
+     *
+     * The following props are automatically passed to the modal component:
+     * - `colIndex` — the column index of the current cell
+     * - `rowIndex` — the row index of the current cell
+     * - `store` — the table data store
+     */
+    modalComponent?: string;
+    /**
+     * Extra props passed to `modalComponent` in addition to the standard cell props.
+     *
+     * Only applicable when `modalComponent` is set.
+     */
+    modalComponentExtraProps?: Record<string, any>;
+    /**
+     * Serialized function string used to format the cell value for display. Deserialized at
+     * render time by the table store's `getFormattedValue`. `TableColumn.format` widens this
+     * to also accept a live function directly.
+     */
+    format?: string;
+    /**
+     * When `true`, this column is treated as a Gantt bar column.
+     *
+     * Only applicable for Gantt tables.
+     *
+     * @defaultValue false
+     */
+    isGantt?: boolean;
+    /**
+     * Registered component name used to render Gantt bars in this column.
+     *
+     * Only applicable for Gantt tables.
+     *
+     * @defaultValue 'AGanttCell'
+     */
+    ganttComponent?: string;
+    /**
+     * Number of columns this Gantt bar spans across. When absent, the bar stretches to cover
+     * all non-pinned columns in the table.
+     *
+     * Only applicable for Gantt tables.
+     */
+    colspan?: number;
+}
+//# sourceMappingURL=column-schema.d.ts.map

package/dist/src/column-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-schema.d.ts","sourceRoot":"","sources":["../../src/column-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAY;IAC5B,2FAA2F;IAC3F,SAAS,EAAE,MAAM,CAAA;IAEjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd,wFAAwF;IACxF,MAAM,CAAC,EAAE,OAAO,CAAA;IAEhB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,CAAA;IAErD;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IAEd;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAEhB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IAEpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,WAAW,CAAA;IAE3F;;;OAGG;IACH,aAAa,CAAC,EAAE,GAAG,EAAE,CAAA;IAErB,yEAAyE;IACzE,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAExC;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAE9C;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB"}

package/dist/src/index.d.ts

@@ -4,4 +4,5 @@ export type { ActionDefinition, Cardinality, CustomFetch, DataClient, DoctypeCon
 export { parseDoctype, parseField, validateDoctype, validateField, type ValidationError, type ValidationResult, } from './validation';
 export { buildScalarMap, classifyFieldType, convertGraphQLSchema, defaultIsEntityField, defaultIsEntityType, GQL_SCALAR_MAP, INTERNAL_SCALARS, WELL_KNOWN_SCALARS, type ConvertedGraphQLDoctype, type GraphQLConversionFieldMeta, type GraphQLConversionOptions, type IntrospectionSource, } from './converter';
 export { toSlug, toPascalCase, pascalToSnake, snakeToCamel, camelToSnake, snakeToLabel, camelToLabel } from './naming';
+export type { ColumnSchema } from './column-schema';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,kBAAkB,EAClB,mBAAmB,EACnB,QAAQ,EACR,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GAClB,MAAM,aAAa,CAAA;AAGpB,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAGvE,YAAY,EACX,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,UAAU,EACV,cAAc,EACd,WAAW,EACX,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,YAAY,GACZ,MAAM,WAAW,CAAA;AAGlB,OAAO,EACN,YAAY,EACZ,UAAU,EACV,eAAe,EACf,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACrB,MAAM,cAAc,CAAA;AAGrB,OAAO,EACN,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,GACxB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,kBAAkB,EAClB,mBAAmB,EACnB,QAAQ,EACR,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GAClB,MAAM,aAAa,CAAA;AAGpB,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAGvE,YAAY,EACX,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,UAAU,EACV,cAAc,EACd,WAAW,EACX,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,YAAY,GACZ,MAAM,WAAW,CAAA;AAGlB,OAAO,EACN,YAAY,EACZ,UAAU,EACV,eAAe,EACf,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACrB,MAAM,cAAc,CAAA;AAGrB,OAAO,EACN,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,GACxB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAGtH,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/schema",
-  "version": "0.11.9",
+  "version": "0.12.0",
   "type": "module",
   "types": "./dist/schema.d.ts",
   "exports": {