@vueye-table/vue 3.0.0-alpha.1 → 3.0.0-alpha.10

package/dist/index.d.ts

@@ -1,9 +1,64 @@
-import { ComputedRef, MaybeRefOrGetter } from "vue";
-import { CellPosition, CellRange, ColumnDef, DataTable, EditResult, GridBounds, GridDirection, GridKey, GridSelection, MoveOptions, TableColumn, TableOptions, TableRow, TableSnapshot, TableStatePatch } from "@vueye-table/core";
+import { ComponentPublicInstance, ComputedRef, MaybeRef, MaybeRefOrGetter } from "vue";
+import { CellPosition, CellRange, ColumnDef, CopyOptions, DataTable, DeepKeys, EditResult, EditorSpec, ExpandedState, GridBounds, GridDirection, GridKey, GridSelection, MoveOptions, PathValue, PendingChanges, RowKey, StreamOptions, TableColumn, TableIssue, TableOptions, TableRenderItem, TableRow, TableSnapshot, TableState, TableStatePatch, TreeLoadController, TreeLoadSignal, VirtualAlign, VirtualItem, VirtualWindow } from "@vueye-table/core";
+//#region src/row-draft.d.ts
+/** A column-value bag. Only configured columns are present; dotted paths stay dotted keys. */
+type RowDraftValues<TRow> = { -readonly [P in DeepKeys<TRow>]?: PathValue<TRow, P>; };
+interface RowDraft<TRow> {
+  readonly rowKey: RowKey;
+  readonly values: RowDraftValues<TRow>;
+  readonly issues: readonly TableIssue[];
+  readonly status: "editing" | "saving" | "saved" | "cancelled" | "stale";
+  readonly pending: boolean;
+  /** Supply raw text for the column parser, including numeric/date input. */
+  setInput(column: string, input: string): void;
+  /** Set a computed column whose id is not a path in the row type. */
+  setValue(column: string, value: unknown): void;
+  save(): Promise<EditResult<TRow>>;
+  /** Discard an unsubmitted draft. A submitted validation batch is owned by the engine. */
+  cancel(): boolean;
+}
+//#endregion
+//#region src/source.d.ts
+interface SourceContext {
+  readonly signal: AbortSignal;
+}
+type TableSource<TRow> = AsyncIterable<TRow | readonly TRow[]> | ((context: SourceContext) => AsyncIterable<TRow | readonly TRow[]>);
+interface LoadMoreContext extends SourceContext {
+  /** Undefined on the first page. Validate or narrow the opaque cursor in your loader. */
+  readonly cursor: unknown;
+  readonly state: TableState;
+}
+interface LoadMoreResult<TRow> {
+  readonly rows: readonly TRow[];
+  readonly cursor?: unknown;
+  readonly done: boolean;
+}
+type LoadMore<TRow> = (context: LoadMoreContext) => Promise<LoadMoreResult<TRow>>;
+/** Schedule once per rendering frame and return its cancellation function. */
+type FrameScheduler = (publish: () => void) => () => void;
+interface SourceOptions<TRow> {
+  readonly source?: MaybeRef<TableSource<TRow> | undefined> | undefined;
+  readonly loadMore?: MaybeRef<LoadMore<TRow> | undefined> | undefined;
+  readonly streamOptions?: Omit<StreamOptions, "signal"> | undefined;
+  /** Non-component scopes use a 16ms timer by default. */
+  readonly scheduleFrame?: FrameScheduler | undefined;
+  /** Remaining flattened items at which a virtual renderer requests the next cursor page. */
+  readonly endThreshold?: number | undefined;
+}
+interface SourceBinding {
+  readonly endThreshold: number;
+  readonly loadingMode: "source" | "cursor" | undefined;
+  readonly canLoadMore: boolean;
+  readonly loadError: TableIssue | undefined;
+  loadNext(this: void): Promise<void>;
+  retry(this: void): void;
+}
+//#endregion
 //#region src/use-data-table.d.ts
 /** Options accepted by {@link useDataTable}. Data, columns, and state may be refs or getters. */
-interface UseDataTableOptions<TRow> extends Omit<TableOptions<TRow>, "data" | "columns" | "rowCount"> {
-  readonly data: MaybeRefOrGetter<readonly TRow[]>;
+interface UseDataTableOptions<TRow, TSignal extends TreeLoadSignal = AbortSignal> extends Omit<TableOptions<TRow, TSignal>, "data" | "columns" | "rowCount">, SourceOptions<TRow> {
+  /** Initial rows for a source, or the caller-owned array for an ordinary table. */
+  readonly data?: MaybeRefOrGetter<readonly TRow[]> | undefined;
   readonly columns: MaybeRefOrGetter<readonly ColumnDef<TRow>[]>;
   readonly rowCount?: MaybeRefOrGetter<number | undefined> | undefined;
   /**
@@ -18,11 +73,14 @@ type TableOperations<TRow> = Omit<DataTable<TRow>, "getSnapshot" | "getState" |
  * `table.rows` and `table.pageCount` directly, and every change goes through a named operation.
  * Watching a field needs a getter: `watch(() => table.page, ...)`.
  */
-type DataTableBinding<TRow> = TableSnapshot<TRow> & TableOperations<TRow> & {
+type DataTableBinding<TRow> = TableSnapshot<TRow> & SourceBinding & TableOperations<TRow> & {
   /** The engine behind the binding. */
   readonly table: DataTable<TRow>;
   /** The current snapshot, replaced on every change. */
   readonly snapshot: TableSnapshot<TRow>;
+  readonly expanded: ExpandedState;
+  readonly pendingChanges: PendingChanges<TRow>;
+  editRow(key: RowKey): RowDraft<TRow>;
 };
 /**
  * A binding for any row type, for components that accept every table. Row types make the binding
@@ -34,6 +92,9 @@ type AnyDataTableBinding = DataTableBinding<any>;
  * columns, row count, and state, and stops listening when the scope ends.
  */
 declare function useDataTable<TRow>(options: UseDataTableOptions<TRow>): DataTableBinding<TRow>;
+declare function useDataTable<TRow, TSignal extends TreeLoadSignal = AbortSignal>(options: UseDataTableOptions<TRow, TSignal> & (AbortSignal extends TSignal ? unknown : {
+  readonly createChildLoadController: () => TreeLoadController<TSignal>;
+})): DataTableBinding<TRow>;
 //#endregion
 //#region src/use-data-grid.d.ts
 /** The cell being edited and the text typed so far. */
@@ -46,12 +107,15 @@ interface GridEditor {
  * copy, paste, and clearing. Positions refer to the current page and the visible columns.
  */
 interface DataGridBinding<TRow> {
+  readonly table: DataTableBinding<TRow>;
   readonly selection: GridSelection | undefined;
   readonly range: CellRange | undefined;
   readonly editor: GridEditor | undefined;
   readonly bounds: ComputedRef<GridBounds>;
   /** The latest edit outcome, to show a rejected value. */
   readonly lastResult: EditResult<TRow> | undefined;
+  /** Serializable editor metadata for an editable cell; no component resolution. */
+  editorFor(position: CellPosition): EditorSpec | undefined;
   cellAt(position: CellPosition): {
     row: TableRow<TRow>;
     column: TableColumn<TRow>;
@@ -69,16 +133,27 @@ interface DataGridBinding<TRow> {
   updateDraft(draft: string): void;
   /** Write the draft through the table, then move the focus if asked. */
   commitEdit(then?: GridDirection): EditResult<TRow> | undefined;
+  /** Submit through core validation; retain a refused/pending editor for correction. */
+  submitEdit(edit?: {
+    readonly input: string;
+  } | {
+    readonly value: unknown;
+  }, then?: GridDirection): EditResult<TRow> | undefined;
+  toggleCheckbox(): boolean;
   cancelEdit(): void;
   /** The selected range as tab-separated text. */
-  copy(): string;
+  copy(options?: CopyOptions): string;
   /** Paste tab-separated text at the top-left of the selection. */
   paste(text: string): EditResult<TRow> | undefined;
   clear(): EditResult<TRow> | undefined;
   /** Handle a key press. Returns `true` when the grid used it, so the caller can prevent the default. */
   handleKey(event: GridKey): boolean;
 }
-declare function useDataGrid<TRow>(table: DataTableBinding<TRow>): DataGridBinding<TRow>;
+interface DataGridOptions {
+  /** Falls back to the first visible column if the configured column is hidden. */
+  readonly treeColumn?: () => string | undefined;
+}
+declare function useDataGrid<TRow>(table: DataTableBinding<TRow>, gridOptions?: DataGridOptions): DataGridBinding<TRow>;
 //#endregion
 //#region src/injection.d.ts
 /** Make a table available to every component below the current one. */
@@ -92,5 +167,45 @@ declare function provideDataGrid<TRow>(grid: DataGridBinding<TRow>): void;
 /** Read the grid provided by an ancestor, or `undefined` outside a grid. */
 declare function injectDataGrid<TRow = unknown>(): DataGridBinding<TRow> | undefined;
 //#endregion
-export { type AnyDataTableBinding, type DataGridBinding, type DataTableBinding, type GridEditor, type UseDataTableOptions, injectDataGrid, injectDataTable, provideDataGrid, provideDataTable, useDataGrid, useDataTable };
+//#region src/use-virtual.d.ts
+interface VirtualViewportOptions {
+  readonly scrollElement: MaybeRefOrGetter<HTMLElement | null | undefined>;
+  readonly overscan?: number | undefined;
+  /** Number of items rendered before mount, without overscan. Defaults to 10. */
+  readonly initialCount?: number | undefined;
+  /** Space before the items, such as a sticky header or leading row-number column. */
+  readonly scrollMargin?: MaybeRefOrGetter<number> | undefined;
+}
+interface UseVirtualRowsOptions<TRow> extends VirtualViewportOptions {
+  readonly estimateRowHeight?: number | ((index: number) => number) | undefined;
+  /** Connect logical grid focus to the rendered data row, skipping details. */
+  readonly grid?: DataGridBinding<TRow> | undefined;
+}
+interface UseVirtualColumnsOptions extends VirtualViewportOptions {
+  readonly estimateColumnWidth?: number | ((index: number) => number) | undefined;
+}
+interface VirtualRowItem<TRow> extends VirtualItem {
+  readonly renderItem: TableRenderItem<TRow>;
+}
+interface VirtualColumnItem<TRow> extends VirtualItem {
+  readonly column: TableColumn<TRow>;
+}
+interface VirtualBinding<TItem extends VirtualItem> extends Omit<VirtualWindow, "items"> {
+  readonly items: readonly TItem[];
+  getItem(index: number): TItem | undefined;
+  scrollToIndex(index: number, options?: {
+    readonly align?: VirtualAlign | undefined;
+  }): void;
+  scrollToKey(key: RowKey, options?: {
+    readonly align?: VirtualAlign | undefined;
+  }): void;
+  /** Pass the virtual item key explicitly; null releases its previously observed element. */
+  measureElement(element: Element | ComponentPublicInstance | null, key: RowKey): void;
+}
+/** Virtualize data and detail render items. scrollToKey accepts the parent data-row key. */
+declare function useVirtualRows<TRow>(table: DataTableBinding<TRow>, options: UseVirtualRowsOptions<TRow>): VirtualBinding<VirtualRowItem<TRow>>;
+/** Virtualize visible columns and bring the active logical column into view. */
+declare function useVirtualColumns<TRow>(grid: DataGridBinding<TRow>, options: UseVirtualColumnsOptions): VirtualBinding<VirtualColumnItem<TRow>>;
+//#endregion
+export { type AnyDataTableBinding, type DataGridBinding, type DataGridOptions, type DataTableBinding, type FrameScheduler, type GridEditor, type LoadMore, type LoadMoreContext, type LoadMoreResult, type RowDraft, type RowDraftValues, type SourceBinding, type SourceContext, type SourceOptions, type TableSource, type UseDataTableOptions, type UseVirtualColumnsOptions, type UseVirtualRowsOptions, type VirtualBinding, type VirtualColumnItem, type VirtualRowItem, type VirtualViewportOptions, injectDataGrid, injectDataTable, provideDataGrid, provideDataTable, useDataGrid, useDataTable, useVirtualColumns, useVirtualRows };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/use-data-table.ts","../src/use-data-grid.ts","../src/injection.ts"],"mappings":";;;;UAmBiB,oBAAoB,cAAc,KACjD,aAAa;WAGJ,MAAM,0BAA0B;WAChC,SAAS,0BAA0B,UAAU;WAC7C,WAAW;;;;;WAKX,QAAQ,iBAAiB;;KAG/B,gBAAgB,QAAQ,KAAK,UAAU;;;;;;KAOhC,iBAAiB,QAAQ,cAAc,QACjD,gBAAgB;;WAEL,OAAO,UAAU;;WAEjB,UAAU,cAAc;;;;;;KAOzB,sBAAsB;;;;;iBA4ClB,aAAa,MAAM,SAAS,oBAAoB,QAAQ,iBAAiB;;;;UCzExE;WACN,UAAU;WACV;;;;;;UAOM,gBAAgB;WACtB,WAAW;WACX,OAAO;WACP,QAAQ;WACR,QAAQ,YAAY;;WAEpB,YAAY,WAAW;EAChC,OAAO,UAAU;IAAiB,KAAK,SAAS;IAAO,QAAQ,YAAY;;EAC3E,UAAU,UAAU;EACpB,WAAW,UAAU;EACrB,UAAU,UAAU;EACpB,UAAU,UAAU,cAAc;aAAqB;;EACvD,KAAK,WAAW,eAAe,UAAU;EACzC;;EAEA,UAAU;EACV,YAAY;;EAEZ,WAAW,OAAO,gBAAgB,WAAW;EAC7C;;EAEA;;EAEA,MAAM,eAAe,WAAW;EAChC,SAAS,WAAW;;EAEpB,UAAU,OAAO;;iBAGH,YAAY,MAAM,OAAO,iBAAiB,QAAQ,gBAAgB;;;;iBCpDlE,iBAAiB,MAAM,OAAO,iBAAiB;;;;;iBAQ/C,gBAAgB,gBAC9B,oBACC,iBAAiB;iBAUJ,gBAAgB,MAAM,MAAM,gBAAgB;;iBAK5C,eAAe,mBAAmB,gBAAgB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/row-draft.ts","../src/source.ts","../src/use-data-table.ts","../src/use-data-grid.ts","../src/injection.ts","../src/use-virtual.ts"],"mappings":"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"}