@henryx/onedot-ui 0.2.0 → 0.4.0

package/README.md

@@ -29,8 +29,8 @@ Components use the `od-` CSS namespace. Theme variables can be overridden on
 
 ### Tables
 
-`OdTable` supports local rows, function-backed remote data, and URL-backed
-Schema/query data. The three source modes are mutually exclusive:
+`OdTable` provides local tables and remote queries. The example below uses
+the existing local mode:
 
 ```vue
 <script setup lang="ts">
@@ -47,9 +47,16 @@ const rows = [{ id: 1, name: 'Ada' }]
 </template>
 ```
 
-For remote data, provide `load-schema` and `load-data`, or `schema-url` and
-`query-url`. Remote responses must follow `OdTableSchema` and
-`OdTableResult<T>`, including a stable, unique row key for every item.
+Remote tables default to frontend columns and one POST query endpoint
+returning paginated data plus `meta.fields` for query capabilities and enum
+options. Use `query-url` or `load-data`, with the same `columns` and `row-key`
+props. When the server determines columns, use `schema-url + query-url` or
+`load-schema + load-data`; omit frontend columns and row-key. Both column modes
+are supported starting in 0.4.0 (0.3.0 uses frontend columns).
+Both modes share query metadata. Field slots such as `#cell-name` match existing
+columns by field and let the page render links or dialog
+buttons. See the [OdTable guide](./用户使用手册/OdTable.md) for complete examples,
+and the [capability list](./用户使用手册/能力清单.md) for implementation status.
 
 ## Development
 
@@ -60,6 +67,9 @@ corepack pnpm dev
 ```
 
 Storybook is served at `http://localhost:6006`.
+For browsing without development compilation or file watching, run
+`corepack pnpm build:storybook` then `corepack pnpm preview:storybook`.
+See the [Storybook guide](./用户使用手册/Storybook.md) for preview and icon search usage.
 
 Open [Capabilities](http://localhost:6006/?path=/story/capabilities--all) for the
 complete catalog, existing Od stories and PrimeVue 4.5.5 (MIT) previews with Aura.
@@ -109,7 +119,7 @@ The full Tabler Vue catalog and raw SVG assets are shipped inside this package,
 so moving the component library to another application does not require a
 second icon dependency or a network request.
 
-The `0.2.0` release is prepared for npm publication. Maintainers should run
+The current package version is `0.4.0`. Maintainers should run
 `corepack pnpm release:check` before publishing subsequent versions.
 
 ## License

package/dist/components/OdTable.types.d.ts

@@ -1,4 +1,4 @@
-/** Public contracts and input validation shared by OdTable's implementation. */
+import { VNodeChild } from 'vue';
 export type OdTableRowKey = string | number;
 export type OdTableDataType = 'text' | 'number' | 'datetime' | 'boolean' | 'enum';
 export type OdTableOption = {
@@ -27,6 +27,16 @@ export type OdTableColumn = {
         false: string;
     };
 };
+export type OdTableCellContext<T extends object> = {
+    row: T;
+    rowKey: OdTableRowKey;
+    column: OdTableColumn;
+    value: unknown;
+    text: string;
+};
+export type OdTableSlots<T extends object> = {
+    [name: `cell-${string}`]: ((context: OdTableCellContext<T>) => VNodeChild) | undefined;
+};
 export type OdTableSorting = {
     field: string;
     direction: 'asc' | 'desc';
@@ -47,32 +57,46 @@ export type OdTableQuery = {
     sorting: OdTableSorting[];
 };
 export type OdTableInitialQuery = Partial<OdTableQuery>;
+export type OdTableFieldMeta = {
+    sortable?: boolean;
+    searchable?: boolean;
+    filterable?: boolean;
+    options?: OdTableOption[];
+};
+export type OdTableMeta = {
+    fields: Record<string, OdTableFieldMeta>;
+};
 export type OdTableResult<T> = {
     items: T[];
     total: number;
     page: number;
     pageSize: number;
+    meta: OdTableMeta;
 };
 export type OdTablePaginationConfig = {
     defaultPageSize?: number;
     pageSizeOptions?: number[];
 };
+/** Structure only: query capabilities and enum options belong to Result.meta. */
+export type OdTableSchemaColumn = Omit<OdTableColumn, 'sortable' | 'searchable' | 'filterable' | 'options'>;
 export type OdTableSchema = {
     rowKey: string;
-    columns: OdTableColumn[];
-    defaultSorting?: OdTableSorting[];
-    pagination?: {
-        defaultPageSize: number;
-        pageSizeOptions: number[];
-    };
+    columns: OdTableSchemaColumn[];
 };
-export type OdTableRequest = (url: string, options: {
-    method: 'GET' | 'POST';
+export type OdTableLoadSchema = (context: {
+    signal: AbortSignal;
+}) => Promise<OdTableSchema>;
+export type OdTableRequestOptions = {
     headers?: Record<string, string>;
-    body?: unknown;
     signal: AbortSignal;
-}) => Promise<unknown>;
-export type OdTableLoadSchema = () => Promise<OdTableSchema>;
+} & ({
+    method: 'GET';
+    body?: never;
+} | {
+    method: 'POST';
+    body: OdTableQuery;
+});
+export type OdTableRequest = (url: string, options: OdTableRequestOptions) => Promise<unknown>;
 export type OdTableLoadData<T> = (query: OdTableQuery, context: {
     signal: AbortSignal;
 }) => Promise<OdTableResult<T>>;
@@ -118,8 +142,8 @@ export type OdTableProps<T extends object> = {
     rowKey?: string;
     pagination?: OdTablePaginationConfig;
     loadSchema?: OdTableLoadSchema;
-    loadData?: OdTableLoadData<T>;
     schemaUrl?: string;
+    loadData?: OdTableLoadData<T>;
     queryUrl?: string;
     request?: OdTableRequest;
     initialQuery?: OdTableInitialQuery;
@@ -134,6 +158,7 @@ export type OdTableProps<T extends object> = {
 };
 export type OdTableExpose = {
     refresh: () => Promise<void>;
+    refreshSchema: () => Promise<void>;
 };
 export type OdTableEvents<T> = {
     'selection-change': (keys: OdTableRowKey[], rows: T[]) => void;
@@ -144,17 +169,17 @@ export type OdTableEvents<T> = {
         field: string;
         width: number;
     }) => void;
-    'schema-error': (error: unknown) => void;
     'data-error': (payload: {
         error: unknown;
         query: OdTableQuery;
     }) => void;
+    'schema-error': (error: unknown) => void;
     retry: (payload: {
         stage: 'schema' | 'data';
     }) => void;
     'config-error': (error: OdTableConfigError) => void;
 };
-export type OdTableConfigErrorCode = 'MODE_MISSING' | 'MODE_PARTIAL' | 'MODE_CONFLICT' | 'REQUEST_WITHOUT_URL_MODE' | 'REMOTE_PAGINATION' | 'INVALID_COLUMNS' | 'DUPLICATE_COLUMN_FIELD' | 'INVALID_COLUMN_FIELD' | 'INVALID_COLUMN_WIDTH' | 'INVALID_NUMBER_FORMAT' | 'SEARCHABLE_NON_TEXT' | 'FILTERABLE_NON_ENUM' | 'ENUM_OPTIONS_REQUIRED' | 'DUPLICATE_ENUM_OPTION' | 'INVALID_DEFAULT_SORTING' | 'INVALID_PAGINATION' | 'INVALID_ROW_KEY_FIELD' | 'MISSING_ROW_KEY' | 'DUPLICATE_ROW_KEY' | 'INVALID_INITIAL_QUERY' | 'INVALID_ROWS' | 'INVALID_RESULT' | 'RESULT_TOTAL_INVALID' | 'RESULT_PAGE_INVALID' | 'RESULT_PAGE_SIZE_INVALID' | 'RESULT_ITEMS_OVERFLOW' | 'RESULT_EMPTY_CONFLICT';
+export type OdTableConfigErrorCode = 'MODE_MISSING' | 'MODE_PARTIAL' | 'MODE_CONFLICT' | 'REQUEST_WITHOUT_URL_MODE' | 'INVALID_COLUMNS' | 'INVALID_SCHEMA' | 'INVALID_ROW_KEY_FIELD' | 'DUPLICATE_COLUMN_FIELD' | 'INVALID_COLUMN_FIELD' | 'INVALID_COLUMN_WIDTH' | 'INVALID_NUMBER_FORMAT' | 'SEARCHABLE_NON_TEXT' | 'FILTERABLE_NON_ENUM' | 'ENUM_OPTIONS_REQUIRED' | 'DUPLICATE_ENUM_OPTION' | 'INVALID_PAGINATION' | 'MISSING_ROW_KEY' | 'DUPLICATE_ROW_KEY' | 'INVALID_INITIAL_QUERY' | 'INVALID_ROWS' | 'INVALID_RESULT' | 'RESULT_TOTAL_INVALID' | 'RESULT_PAGE_INVALID' | 'RESULT_PAGE_SIZE_INVALID' | 'RESULT_ITEMS_OVERFLOW' | 'RESULT_EMPTY_CONFLICT' | 'INVALID_META' | 'META_QUERY_CONFLICT';
 export declare class OdTableConfigError extends Error {
     readonly name = "OdTableConfigError";
     readonly code: OdTableConfigErrorCode;
@@ -162,17 +187,16 @@ export declare class OdTableConfigError extends Error {
     constructor(code: OdTableConfigErrorCode, message: string, details?: unknown);
 }
 export type OdTableSourceMode = 'local' | 'function' | 'url';
-type OdTableSourceInput<T extends object> = Pick<OdTableProps<T>, 'columns' | 'rows' | 'rowKey' | 'pagination' | 'loadSchema' | 'loadData' | 'schemaUrl' | 'queryUrl' | 'request'>;
-export declare function validateOdTableColumns(columns: unknown): OdTableColumn[];
+type OdTableSourceInput<T extends object> = Partial<Pick<OdTableProps<T>, 'columns' | 'rows' | 'rowKey' | 'pagination' | 'loadSchema' | 'schemaUrl' | 'loadData' | 'queryUrl' | 'request'>>;
+export declare function validateOdTableColumns(columns: unknown, remote?: boolean): OdTableColumn[];
 export declare function validateOdTablePagination(pagination: unknown): OdTablePaginationConfig;
-export declare function validateOdTableSchema(schema: unknown): OdTableSchema;
 export declare function validateOdTableInitialQuery(query: unknown): OdTableInitialQuery | undefined;
 /**
- * Checks query conditions against the capabilities advertised by a Schema.
+ * Checks query conditions against resolved column capabilities.
  * Keeping this validation next to the shape validator prevents local and
  * remote modes from silently accepting conditions the column contract forbids.
  */
-export declare function validateOdTableInitialQueryForColumns(query: OdTableInitialQuery | undefined, columns: readonly OdTableColumn[]): OdTableInitialQuery | undefined;
+export declare function validateOdTableInitialQueryForColumns(query: OdTableInitialQuery | undefined, columns: readonly OdTableColumn[], pending?: boolean, code?: 'INVALID_INITIAL_QUERY' | 'META_QUERY_CONFLICT'): OdTableInitialQuery | undefined;
 export declare function validateOdTableRows<T extends object>(rows: unknown, rowKey: string): T[];
 export declare function validateOdTableSourceMode<T extends object>(input: OdTableSourceInput<T>): OdTableSourceMode;
 /**
@@ -181,4 +205,10 @@ export declare function validateOdTableSourceMode<T extends object>(input: OdTab
  * so callers can route them to `data-error` without string matching.
  */
 export declare function validateOdTableResult<T>(payload: unknown): OdTableResult<T>;
+/** Restored from the 0.2 Schema contract, restricted to the current structural role. */
+export declare function validateOdTableSchema(payload: unknown): OdTableSchema;
+/** Copy only supported metadata so extra response properties cannot define UI. */
+export declare function validateOdTableMeta(payload: unknown): OdTableMeta;
+/** A null snapshot means the first response has not arrived: all query UI is closed. */
+export declare function resolveOdTableRemoteColumns(columns: readonly OdTableColumn[], meta: OdTableMeta | null): OdTableColumn[];
 export {};

package/dist/components/OdTable.vue.d.ts

@@ -1,4 +1,4 @@
-import { OdTableConfigError, OdTableProps, OdTableQuery, OdTableRowKey } from './OdTable.types';
+import { OdTableConfigError, OdTableProps, OdTableQuery, OdTableRowKey, OdTableSlots } from './OdTable.types';
 declare const _default: <T extends object>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
         readonly onRetry?: ((payload: {
@@ -12,27 +12,28 @@ declare const _default: <T extends object>(__VLS_props: NonNullable<Awaited<type
             field: string;
             width: number;
         }) => any) | undefined;
-        readonly "onSchema-error"?: ((error: unknown) => any) | undefined;
         readonly "onData-error"?: ((payload: {
             error: unknown;
             query: OdTableQuery;
         }) => any) | undefined;
+        readonly "onSchema-error"?: ((error: unknown) => any) | undefined;
         readonly "onConfig-error"?: ((error: OdTableConfigError) => any) | undefined;
-    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onRetry" | "onSelection-change" | "onUpdate:selected-row-keys" | "onQuery-change" | "onColumn-visibility-change" | "onColumn-width-change" | "onSchema-error" | "onData-error" | "onConfig-error"> & OdTableProps<T> & Partial<{}>> & import('vue').PublicProps;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onRetry" | "onSelection-change" | "onUpdate:selected-row-keys" | "onQuery-change" | "onColumn-visibility-change" | "onColumn-width-change" | "onData-error" | "onSchema-error" | "onConfig-error"> & OdTableProps<T> & Partial<{}>> & import('vue').PublicProps;
     expose(exposed: import('vue').ShallowUnwrapRef<{
         refresh: () => Promise<void>;
+        refreshSchema: () => Promise<void>;
     }>): void;
     attrs: any;
-    slots: {};
+    slots: Readonly<OdTableSlots<T>> & OdTableSlots<T>;
     emit: ((evt: "retry", payload: {
         stage: "schema" | "data";
     }) => void) & ((evt: "selection-change", keys: OdTableRowKey[], rows: T[]) => void) & ((evt: "update:selected-row-keys", keys: OdTableRowKey[]) => void) & ((evt: "query-change", query: OdTableQuery) => void) & ((evt: "column-visibility-change", visibility: Record<string, boolean>) => void) & ((evt: "column-width-change", payload: {
         field: string;
         width: number;
-    }) => void) & ((evt: "schema-error", error: unknown) => void) & ((evt: "data-error", payload: {
+    }) => void) & ((evt: "data-error", payload: {
         error: unknown;
         query: OdTableQuery;
-    }) => void) & ((evt: "config-error", error: OdTableConfigError) => void);
+    }) => void) & ((evt: "schema-error", error: unknown) => void) & ((evt: "config-error", error: OdTableConfigError) => void);
 }>) => import('vue').VNode & {
     __ctx?: Awaited<typeof __VLS_setup>;
 };

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import { default as OdTable } from './components/OdTable.vue';
 export { OdButton, OdIcon, OdTable };
 export { OdTableConfigError } from './components/OdTable.types';
 export type { OdButtonVariant, OdSize } from './components/OdButton.vue';
-export type { OdTableColumn, OdTableConfigErrorCode, OdTableDataType, OdTableEvents, OdTableExpose, OdTableFilter, OdTableInitialQuery, OdTableLocale, OdTableOption, OdTablePaginationConfig, OdTableProps, OdTableQuery, OdTableRequest, OdTableResult, OdTableRowKey, OdTableSchema, OdTableSearch, OdTableSorting, OdTableLoadData, OdTableLoadSchema, } from './components/OdTable.types';
+export type { OdTableCellContext, OdTableColumn, OdTableConfigErrorCode, OdTableDataType, OdTableEvents, OdTableExpose, OdTableFilter, OdTableFieldMeta, OdTableInitialQuery, OdTableLocale, OdTableMeta, OdTableOption, OdTablePaginationConfig, OdTableProps, OdTableQuery, OdTableRequest, OdTableResult, OdTableRowKey, OdTableSearch, OdTableSorting, OdTableSlots, OdTableLoadData, OdTableSchemaColumn, OdTableSchema, OdTableLoadSchema, OdTableRequestOptions, } from './components/OdTable.types';
 export declare const OnedotUI: {
     install(app: App): void;
 };