@vuu-ui/vuu-table-types 0.0.26 → 0.8.12

package/index.d.ts

@@ -1,33 +1,65 @@
+import type {
+  DataSourceRow,
+  DataSourceRowObject,
+  DataValueDescriptor,
+  DataValueTypeSimple,
+  DataValueValidationChecker,
+  EditValidationRule,
+} from "@vuu-ui/vuu-data-types";
 import type { Filter } from "@vuu-ui/vuu-filter-types";
 import type {
   VuuAggType,
-  VuuColumnDataType,
+  VuuMenuItem,
   VuuRowDataItemType,
   VuuSortType,
   VuuTable,
 } from "@vuu-ui/vuu-protocol-types";
-import type { ClientSideValidationChecker } from "@vuu-ui/vuu-ui-controls";
-import type { DateTimePattern } from "@vuu-ui/vuu-utils";
-import { DataSourceRow, DataSourceRowObject } from "@vuu-ui/vuu-data-types";
-import type { FunctionComponent, MouseEvent } from "react";
-import type { HTMLAttributes } from "react";
-
-export type TableSelectionModel = "none" | "single" | "checkbox" | "extended";
-
-export type TableHeading = { label: string; width: number };
-export type TableHeadings = TableHeading[][];
-
-export type ValueFormatter = (value: unknown) => string;
+import { CellPos } from "@vuu-ui/vuu-table/src/table-dom-utils";
+import type {
+  ColumnMap,
+  DateTimePattern,
+  RowClassNameGenerator,
+} from "@vuu-ui/vuu-utils";
+import type {
+  ComponentType,
+  CSSProperties,
+  FunctionComponent,
+  FunctionComponentElement,
+  HTMLAttributes,
+  MouseEvent,
+} from "react";
+
+export declare type GroupToggleTarget = "toggle-icon" | "group-column";
+
+export declare type TableSelectionModel =
+  | "none"
+  | "single"
+  | "checkbox"
+  | "extended";
+
+export declare type TableHeading = { label: string; width: number };
+export declare type TableHeadings = TableHeading[][];
+
+export declare type ValueFormatter<T extends string | JSX.Element = string> = (
+  value: unknown,
+) => T;
+
+export interface EditEventState {
+  editType?: EditType;
+  isValid?: boolean;
+  // value: unknown;
+  previousValue?: VuuRowDataItemType;
+  value: VuuRowDataItemType;
+}
 
-export type ClientSideValidationChecker = (
-  value?: VuuRowDataItemType
-) => string | false | undefined;
+export interface DataCellEditEvent extends EditEventState {
+  row: DataSourceRow;
+  columnName: string;
+}
 
-export type DataCellEditHandler = (
-  row: DataSourceRow,
-  columnName: string,
-  value: VuuRowDataItemType
-) => Promise<string | true>;
+export declare type DataCellEditNotification = (
+  editEvent: DataCellEditEvent,
+) => void;
 
 export interface TableCellProps {
   className?: string;
@@ -36,46 +68,76 @@ export interface TableCellProps {
   onClick?: (event: MouseEvent, column: RuntimeColumnDescriptor) => void;
   onDataEdited?: DataCellEditHandler;
   row: DataSourceRow;
+  searchPattern?: Lowercase<string>;
 }
 
-export type CommitResponse = Promise<true | string>;
+export declare type CommitResponse = Promise<true | string>;
+
+export declare type EditType = "commit" | "change" | "cancel";
 
-export type DataItemCommitHandler<
-  T extends VuuRowDataItemType = VuuRowDataItemType
-> = (value: T) => CommitResponse;
+declare type DataItemEditHandler<T extends EditType = EditType> = (
+  editState: EditEventState,
+  editPhase: T,
+) => T extends "commit" ? Promise<string | true> : void;
 
-export type TableRowSelectHandler = (row: DataSourceRowObject | null) => void;
-export type TableRowSelectHandlerInternal = (row: DataSourceRow | null) => void;
+export declare type TableRowSelectHandler = (
+  row: DataSourceRowObject | null,
+) => void;
+export declare type TableRowSelectHandlerInternal = (
+  row: DataSourceRow | null,
+) => void;
 
 /**
  * Fired when user clicks a row, returning the row object (DataSourceRowObject)
  */
-export type TableRowClickHandler = (
+export declare type TableRowClickHandler = (
   evt: MouseEvent<HTMLDivElement>,
-  row: DataSourceRowObject
+  row: DataSourceRowObject,
 ) => void;
 
-export type TableRowClickHandlerInternal = (
+export declare type TableRowClickHandlerInternal = (
   evt: MouseEvent<HTMLDivElement>,
   row: DataSourceRow,
   rangeSelect: boolean,
-  keepExistingSelection: boolean
+  keepExistingSelection: boolean,
 ) => void;
 
 export interface TableCellRendererProps
   extends Omit<TableCellProps, "onDataEdited"> {
-  onCommit?: DataItemCommitHandler;
+  onEdit?: DataItemEditHandler;
 }
 
+/**
+ * static layout simply respects widths specified on column descriptors.
+ * fit layout attempts to fit columns to available space, either stretching
+ * or squeezing. manual indicates that user has resized one or more columns,
+ * on what was originally a fit layout. Once this happens, no further auto
+ * fitting will take place. Fit layout always respects max and min widths,
+ */
+export declare type ColumnLayout = "static" | "fit" | "manual";
+
 export interface TableAttributes {
   columnDefaultWidth?: number;
   columnFormatHeader?: "capitalize" | "uppercase";
+  columnLayout?: ColumnLayout;
   columnSeparators?: boolean;
   // showHighlightedRow?: boolean;
   rowSeparators?: boolean;
   zebraStripes?: boolean;
 }
 
+export declare type TableMenuLocation = "grid" | "header" | "filter";
+
+export interface VuuCellMenuItem extends VuuMenuItem {
+  rowKey: string;
+  field: string;
+  value: VuuRowDataItemType;
+}
+export interface VuuRowMenuItem extends VuuMenuItem {
+  rowKey: string;
+  row: { [key: string]: VuuRowDataItemType };
+}
+
 /**
  * TableConfig describes the configuration used to render a Table. It is
  * a required prop for Table and provided initially by user. It can be
@@ -91,6 +153,18 @@ export interface GridConfig extends TableConfig {
   selectionBookendWidth?: number;
 }
 
+// TODO tidy up this definition, currently split beween here and data-types
+export declare type DataValueTypeDescriptor = {
+  rules?: EditValidationRule[];
+  formatting?: ColumnTypeFormatting;
+  name: DataValueTypeSimple;
+  renderer?:
+    | ColumnTypeRendering
+    | LookupRenderer
+    | MappedValueTypeRenderer
+    | ValueListRenderer;
+};
+
 export declare type ColumnTypeFormatting = {
   alignOnDecimals?: boolean;
   decimals?: number;
@@ -98,15 +172,9 @@ export declare type ColumnTypeFormatting = {
   zeroPad?: boolean;
 };
 
-export type ColumnTypeValueMap = { [key: string]: string };
-
-export interface EditValidationRule {
-  name: string;
-  message?: string;
-  value?: string;
-}
+export declare type ColumnTypeValueMap = { [key: string]: string };
 
-export type ListOption = {
+export declare type ListOption = {
   label: string;
   value: number | string;
 };
@@ -119,13 +187,12 @@ export interface ColumnTypeRendering {
   // specific to Background renderer
   flashStyle?: "bg-only" | "arrow-bg" | "arrow";
   name: string;
-  rules?: EditValidationRule[];
 }
 export interface MappedValueTypeRenderer {
   map: ColumnTypeValueMap;
 }
 
-export type LookupTableDetails = {
+export declare type LookupTableDetails = {
   labelColumn: string;
   table: VuuTable;
   valueColumn: string;
@@ -145,45 +212,14 @@ export interface ValueListRenderer {
   values: string[];
 }
 
-export declare type DateTimeColumnTypeSimple = "date/time";
-
-type DateTimeColumnType =
-  | DateTimeColumnTypeSimple
-  | (Omit<ColumnTypeDescriptor, "name"> & { name: DateTimeColumnTypeSimple });
-
-export declare type DateTimeColumnDescriptor = Omit<
-  ColumnDescriptor,
-  "type"
-> & {
-  type: DateTimeColumnType;
-};
-
-export declare type ColumnTypeSimple =
-  | "string"
-  | "number"
-  | "boolean"
-  | "json"
-  | DateTimeColumnTypeSimple
-  | "checkbox";
-
-export declare type ColumnTypeDescriptor = {
-  formatting?: ColumnTypeFormatting;
-  name: ColumnTypeSimple;
-  renderer?:
-    | ColumnTypeRendering
-    | LookupRenderer
-    | MappedValueTypeRenderer
-    | ValueListRenderer;
-};
-
 export declare type ColumnTypeDescriptorCustomRenderer = {
   formatting?: ColumnTypeFormatting;
-  name: ColumnTypeSimple;
+  name: DataValueTypeSimple;
   renderer: ColumnTypeRendering;
 };
 
 export interface FormattingSettingsProps<
-  T extends ColumnDescriptor = ColumnDescriptor
+  T extends ColumnDescriptor = ColumnDescriptor,
 > {
   column: T;
   onChangeFormatting: (formatting: ColumnTypeFormatting) => void;
@@ -193,36 +229,39 @@ export interface FormattingSettingsProps<
    latter. e.g a server data type of long may be further refined as
    a date/time value using the column descriptor type.
    */
-  onChangeColumnType: (type: ColumnTypeSimple) => void;
+  onChangeColumnType: (type: DataValueTypeSimple) => void;
 }
 
-export interface ColumnTypeRendererWithValidationRules
-  extends ColumnTypeRendering {
+export interface ColumnTypeWithValidationRules
+  extends Omit<DataValueTypeDescriptor, "editRules"> {
   rules: EditValidationRule[];
 }
 
-export interface ColumnTypeWithValidationRules extends ColumnTypeDescriptor {
-  renderer: ColumnTypeRendererWithValidationRules;
-}
-
-export declare type ColumnType = ColumnTypeSimple | ColumnTypeDescriptor;
-
-export type ColumnSort = VuuSortType | number;
+export declare type ColumnSort = VuuSortType | number;
 
-export type PinLocation = "left" | "right" | "floating";
+export declare type PinLocation = "left" | "right" | "floating";
 
-export type ColumnAlignment = "left" | "right";
+export declare type ColumnAlignment = "left" | "right";
 
 /** This is a public description of a Column, defining all the
  * column attributes that can be defined by client. */
-export interface ColumnDescriptor {
+export interface ColumnDescriptor extends DataValueDescriptor {
   aggregate?: VuuAggType;
   align?: ColumnAlignment;
   className?: string;
+  /**
+   * Allows custom content to be rendered into the column header. This will be an identifier.
+   * The identifier will be used to retrieve content from the component registry. The componnet
+   * yielded will be rendered into the column header.
+   */
   colHeaderContentRenderer?: string;
   colHeaderLabelRenderer?: string;
-  editable?: boolean;
   flex?: number;
+  /**
+   * Only used when the column is included in a grouby clause.
+   * The icon will be displayed alongside the group label
+   */
+  getIcon?: (row: DataSourceRow) => string | undefined;
   /**
    Optional additional level(s) of heading to display above label.
    May span multiple columns, if multiple adjacent columns declare
@@ -231,17 +270,19 @@ export interface ColumnDescriptor {
   heading?: string[];
   hidden?: boolean;
   isSystemColumn?: boolean;
-  /** The Label to display on column in Table */
-  label?: string;
   locked?: boolean;
   maxWidth?: number;
   minWidth?: number;
-  name: string;
   pin?: PinLocation;
   resizeable?: boolean;
-  serverDataType?: VuuColumnDataType;
   sortable?: boolean;
-  type?: ColumnType;
+  /**
+   * 'client' columns will not receive data from dataSource.
+   * They can be used with a custom renderer, e.g to render
+   * action buttons.
+   * default is 'server'
+   */
+  source?: "client" | "server";
   width?: number;
 }
 
@@ -254,18 +295,17 @@ export interface ColumnDescriptorCustomRenderer
  * definitin with internal state values. */
 export interface RuntimeColumnDescriptor extends ColumnDescriptor {
   align?: "left" | "right";
+  ariaColIndex: number;
   CellRenderer?: FunctionComponent<TableCellRendererProps>;
   HeaderCellLabelRenderer?: FunctionComponent<HeaderCellProps>;
   HeaderCellContentRenderer?: FunctionComponent<HeaderCellProps>;
   canStretch?: boolean;
   className?: string;
-  clientSideEditValidationCheck?: ClientSideValidationChecker;
+  clientSideEditValidationCheck?: DataValueValidationChecker;
   endPin?: true | undefined;
   filter?: Filter;
   flex?: number;
   heading?: [...string[]];
-  /** A 1 based index for aria-colindex */
-  index?: number;
   isGroup?: boolean;
   isSystemColumn?: boolean;
   label: string;
@@ -301,17 +341,17 @@ export interface Heading {
 }
 
 // These are the actions that eventually get routed to the DataSource itself
-export type DataSourceAction =
+export declare type DataSourceAction =
   | GridActionCloseTreeNode
   | GridActionGroup
   | GridActionOpenTreeNode
   | GridActionSort;
 
-export type ScrollAction =
+export declare type ScrollAction =
   | GridActionScrollEndHorizontal
   | GridActionScrollStartHorizontal;
 
-export type GridAction =
+export declare type GridAction =
   | DataSourceAction
   | ScrollAction
   | GridActionResizeCol
@@ -346,19 +386,52 @@ export interface TableSettingsProps {
   tableConfig: TableConfig;
 }
 
-export type DefaultColumnConfiguration = <T extends string = string>(
+export declare type DefaultColumnConfiguration = <T extends string = string>(
   tableName: T,
-  columnName: string
+  columnName: string,
 ) => Partial<ColumnDescriptor> | undefined;
 
-export type ResizePhase = "begin" | "resize" | "end";
+export declare type DefaultTableConfiguration = (
+  vuuTable?: VuuTable,
+) => Partial<Omit<TableConfig, "columns">> | undefined;
+
+export declare type ResizePhase = "begin" | "resize" | "end";
 
-export type TableColumnResizeHandler = (
+export declare type TableColumnResizeHandler = (
   phase: ResizePhase,
   columnName: string,
-  width?: number
+  width?: number,
 ) => void;
 
+export interface BaseRowProps {
+  ariaRole?: string;
+  ariaRowIndex?: number;
+  className?: string;
+  columns: RuntimeColumnDescriptor[];
+  style?: CSSProperties;
+  /**
+   * In a virtualized row, the total width of leading columns not rendered (as
+   * virtualization optimisation)
+   */
+  virtualColSpan?: number;
+}
+
+export interface RowProps extends BaseRowProps {
+  classNameGenerator?: RowClassNameGenerator;
+  columnMap: ColumnMap;
+  groupToggleTarget?: GroupToggleTarget;
+  highlighted?: boolean;
+  offset: number;
+  onCellEdit?: CellEditHandler;
+  onClick?: TableRowClickHandlerInternal;
+  onDataEdited?: DataCellEditHandler;
+  onToggleGroup?: (row: DataSourceRow, column: RuntimeColumnDescriptor) => void;
+  row: DataSourceRow;
+  searchPattern: Lowercase<string>;
+  showBookends?: boolean;
+  zebraStripes?: boolean;
+}
+
 export interface HeaderCellProps
   extends Omit<HTMLAttributes<HTMLDivElement>, "onClick"> {
   classBase?: string;
@@ -368,4 +441,15 @@ export interface HeaderCellProps
   showMenu?: boolean;
 }
 
-export type TableConfigChangeHandler = (config: TableConfig) => void;
+export declare type TableConfigChangeHandler = (config: TableConfig) => void;
+
+export declare type CustomHeaderComponent = ComponentType<BaseRowProps>;
+export declare type CustomHeaderElement =
+  FunctionComponentElement<BaseRowProps>;
+export declare type CustomHeader = CustomHeaderComponent | CustomHeaderElement;
+
+/**
+ * The row and column index positions of a table cell
+ * [rowIndex, colIndex]
+ */
+export declare type CellPos = [number, number];

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "@vuu-ui/vuu-table-types",
-  "version": "0.0.26",
+  "version": "0.8.12",
   "devDependencies": {
-    "@vuu-ui/vuu-protocol-types": "0.0.26"
+    "@vuu-ui/vuu-data-types": "0.8.12",
+    "@vuu-ui/vuu-filter-types": "0.8.12",
+    "@vuu-ui/vuu-protocol-types": "0.8.12"
   },
   "author": "heswell",
   "license": "Apache-2.0",