koval-ui 0.15.12 → 0.16.0

package/dist/index.d.ts

@@ -1,16 +1,22 @@
+import { AccessorFn as AccessorFn_2 } from '@tanstack/react-table';
 import { AriaAttributes } from 'react';
 import { AriaRole } from 'react';
 import { ButtonHTMLAttributes } from 'react';
+import { CellContext } from '@tanstack/react-table';
 import { ChangeEvent } from 'react';
+import { ColumnFiltersState } from '@tanstack/react-table';
+import { ColumnPinningState } from '@tanstack/react-table';
 import { ComponentProps } from 'react';
 import { DetailedHTMLProps } from 'react';
 import { ElementType } from 'react';
 import { FC } from 'react';
 import { FieldsetHTMLAttributes } from 'react';
+import { FilterFnOption } from '@tanstack/react-table';
 import { FocusEvent as FocusEvent_2 } from 'react';
 import { FormHTMLAttributes } from 'react';
 import { ForwardedRef } from 'react';
 import { ForwardRefExoticComponent } from 'react';
+import { HeaderContext } from '@tanstack/react-table';
 import { HTMLAttributeReferrerPolicy } from 'react';
 import { HTMLAttributes } from 'react';
 import { HTMLInputAutoCompleteAttribute } from 'react';
@@ -20,11 +26,16 @@ import { InputHTMLAttributes } from 'react';
 import { InvalidEvent } from 'react';
 import { KeyboardEvent as KeyboardEvent_2 } from 'react';
 import { MouseEvent as MouseEvent_2 } from 'react';
+import { MutableRefObject } from 'react';
+import { PaginationState } from '@tanstack/react-table';
 import { Placement } from '@floating-ui/react-dom';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
+import { RowSelectionState } from '@tanstack/react-table';
 import { SelectHTMLAttributes } from 'react';
+import { SortingFn as SortingFn_2 } from '@tanstack/react-table';
+import { SortingState } from '@tanstack/react-table';
 import { SVGProps } from 'react';
 import { SyntheticEvent } from 'react';
 import { TextareaHTMLAttributes } from 'react';
@@ -39,6 +50,8 @@ children?: ReactNode;
 href?: string | undefined;
 } & RefAttributes<HTMLAnchorElement>>;
 
+export declare type AccessorFn = AccessorFn_2<TableData, TableRow | TableValue>;
+
 declare const Actions: ForwardRefExoticComponent<DataAttributes & AriaAttributes & {
 id?: string | undefined;
 role?: AriaRole | undefined;
@@ -254,6 +267,11 @@ autoRotate?: number | undefined;
 onRotate?: ((index: number) => void) | undefined;
 } & RefAttributes<HTMLDivElement>>;
 
+export declare type CellComponent = FC<unknown & {
+    value?: TableValue;
+    cellContext: CellContext<TableData, TableRow | TableValue>;
+}>;
+
 declare type ChildProps = {
     name?: Props_4['name'];
     disabled?: Props_4['disabled'];
@@ -279,6 +297,124 @@ as?: string | undefined;
 children?: ReactNode;
 } & RefAttributes<HTMLElement>>;
 
+/**
+ * Table column config
+ */
+export declare type Column = {
+    /**
+     * Provide a unique id for the column
+     */
+    id: string;
+    /**
+     * Provide a human-readable title for the column
+     */
+    name: string;
+    /**
+     * Define a type of column data
+     * @see ColumnTypes
+     */
+    columnType?: keyof typeof ColumnTypes;
+    /**
+     * Provide a custom React component to render column cells
+     * @see CellComponent
+     */
+    columnCell?: CellComponent;
+    /**
+     * Set the width of the columns. Defaults to 166
+     */
+    size?: number;
+    /**
+     * Enable to allow user editing of the column
+     */
+    editable?: boolean;
+    /**
+     * Enable to allow user filtering of the column
+     */
+    filterable?: boolean;
+    /**
+     * Enable to make a column able to sort in ascending or descending order
+     */
+    sortable?: boolean;
+    /**
+     * Enable to make a column able to pin the left or right side
+     */
+    pinnable?: boolean;
+    /**
+     * Define a type of sorting to be used for the column. Can be one of supported modes or custom function
+     * @see SortingModes
+     * @see SortingFn
+     */
+    sortingFn?: keyof typeof SortingModes | SortingFn;
+    /**
+     * Define a type of filtering to be used for the column. Can be one of supported modes or custom function
+     * @see FilterFnOption
+     * @see CustomFilterFns
+     */
+    filterFn?: FilterFnOption<TableData> | keyof typeof CustomFilterFns;
+    /**
+     * Set props for each table cell. Useful for formatting dates, currencies, etc.
+     * @see ColumnFormatOptions
+     */
+    cellProps?: ColumnFormatOptions;
+    /**
+     * Provide a custom React component to render the column header
+     * @see HeaderCell
+     */
+    headerCell?: HeaderCell;
+    /**
+     * Provide a custom React component to render the column footer
+     * @see FooterCell
+     */
+    footerCell?: FooterCell;
+    /**
+     * Provide a custom React component to render the column filter input
+     * @see FilterInput
+     */
+    filterInput?: FilterInput;
+} & ({
+    /**
+     * Provide an accessor key to get column cell value from table data
+     * @example
+     * {
+     *     accessorKey: "foo.bar[6].bazz"
+     * }
+     */
+    accessorKey: string;
+    /**
+     * Provide an accessor function to get column cell value from table data
+     */
+    accessorFn?: never;
+} | {
+    /**
+     * Provide an accessor key to get column cell value from table data
+     * @example
+     * {
+     *     accessorKey: "foo.bar[6].bazz"
+     * }
+     */
+    accessorKey?: never;
+    /**
+     * Provide an accessor function to get column cell value from table data
+     */
+    accessorFn: AccessorFn;
+});
+
+export { ColumnFiltersState }
+
+export declare type ColumnFormatOptions = NumberProps | DateFormatOptions | Record<string, unknown>;
+
+export { ColumnPinningState }
+
+export declare enum ColumnTypes {
+    text = "text",
+    decimal = "decimal",
+    percentage = "percentage",
+    currency = "currency",
+    unit = "unit",
+    date = "date",
+    select = "select"
+}
+
 declare enum CompactDisplayModes {
     short = "short",
     long = "long"
@@ -417,10 +553,130 @@ declare enum CurrencyCodes {
     ZWL = "ZWL"
 }
 
+declare enum CurrencyDisplayTypes {
+    code = "code",
+    symbol = "symbol",
+    narrowSymbol = "narrowSymbol",
+    name = "name"
+}
+
+declare enum CurrencySignModes {
+    standard = "standard",
+    accounting = "accounting"
+}
+
+declare enum CustomFilterFns {
+    isInDateRange = "isInDateRange",
+    isInPercentRange = "isInPercentRange"
+}
+
 declare type DataAttributeKey = `data-${string}`;
 
 declare type DataAttributes = Record<DataAttributeKey, string>;
 
+export declare const DataTable: ForwardRefExoticComponent<DataAttributes & AriaAttributes & {
+id?: string | undefined;
+role?: AriaRole | undefined;
+className?: string | undefined;
+} & {
+children?: ReactNode;
+/**
+* Provide table columns configuration
+* @see Column
+*/
+columns: Column[];
+/**
+* Provide data for the table
+* @see TableData
+*/
+tableData: TableData;
+/**
+* Provide a callback to capture table data changes
+* @see EditState
+*/
+onEdit?: ((editState: EditState) => void) | undefined;
+/**
+* Control column pinning state externally
+* @see ColumnPinningState
+*/
+columnPinning?: ColumnPinningState | undefined;
+/**
+* Control pagination state externally
+* @see PaginationState
+*/
+pagination?: PaginationState | undefined;
+/**
+* Provide a callback to capture pagination changes
+* @see PaginationState
+*/
+onPaginationChange?: ((paginationState: PaginationState) => void) | undefined;
+/**
+* Manage column filters externally
+* @see ColumnFiltersState
+*/
+columnFilters?: ColumnFiltersState | undefined;
+/**
+* Provide a callback to capture column filters changes
+* @see ColumnFiltersState
+*/
+onFiltersChange?: ((filterState: ColumnFiltersState) => void) | undefined;
+/**
+* Manage row selection externally
+* @see RowSelectionState
+*/
+rowSelection?: RowSelectionState | undefined;
+/**
+* Provide a callback to capture row selection changes
+* @see RowSelectionState
+*/
+onRowSelect?: ((selectionState: RowSelectionState) => void) | undefined;
+/**
+* Control table data sorting externally
+* @see SortingState
+*/
+sorting?: SortingState | undefined;
+/**
+* Provide a callback to capture table data sorting changes
+* @see SortingState
+*/
+onSortingChange?: ((sortingState: SortingState) => void) | undefined;
+/**
+* Configure how table data is processed inside or outside the component
+* @see ProcessingModes
+*/
+processingMode?: "external" | "internal" | undefined;
+/**
+* Select which type of table to render
+* @see RenderModes
+*/
+renderMode?: "virtual" | "paginated" | undefined;
+/**
+* Set a controlled page count number for pagination. Required for renderMode="paginated-controlled"
+* @see https://morewings.github.io/koval-ui/?path=/story/components-datatable--paginated-controlled&args=tableData:rows100
+*/
+pageCount?: number | undefined;
+/**
+* Provide a string with a BCP 47 language tag or an Intl.Locale instance,
+* or an array of such locale identifiers.
+* Used to format dates, numbers, and units.
+* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#locales
+* @see Locale
+*/
+locale?: Locale | undefined;
+/**
+* Enable column selection
+*/
+selectable?: boolean | undefined;
+/**
+* Set a height constrain to the data table. 'full' sets to 100% of viewport height
+*/
+tableHeight?: number | "full" | undefined;
+/**
+* Set a caption text to render below the table
+*/
+caption?: string | undefined;
+} & RefAttributes<HTMLTableElement>>;
+
 declare type DateFormatOptions = {
     /**
      * The representation of the weekday
@@ -505,6 +761,8 @@ declare type DateFormatOptions = {
     timeZone?: string;
 };
 
+declare type DateRangeFilterValue = string[];
+
 export declare const DateTime: ForwardRefExoticComponent<DataAttributes & AriaAttributes & {
 id?: string | undefined;
 role?: AriaRole | undefined;
@@ -625,6 +883,11 @@ placement?: "left" | "right" | undefined;
 id: string;
 } & RefAttributes<HTMLDivElement>>;
 
+/**
+ * Record which represents table change requested by the user. Key is equal to row index
+ */
+export declare type EditState = Record<number, TableRow>;
+
 export declare const Em: ForwardRefExoticComponent<DataAttributes & AriaAttributes & {
 id?: string | undefined;
 role?: AriaRole | undefined;
@@ -645,6 +908,13 @@ caption?: string | undefined;
 position?: "center" | "left" | "right" | undefined;
 } & RefAttributes<HTMLDivElement>>;
 
+export declare type FilterInput = FC<unknown & {
+    value: FilterValue;
+    onChange: (value: FilterValue) => void;
+}>;
+
+declare type FilterValue = DateRangeFilterValue | RangeFilterValue | string;
+
 declare type FluidUnit = 'fluid';
 
 export declare const Footer: ForwardRefExoticComponent<DataAttributes & AriaAttributes & {
@@ -655,6 +925,10 @@ className?: string | undefined;
 children?: ReactNode;
 } & RefAttributes<HTMLDivElement>>;
 
+export declare type FooterCell = FC<unknown & {
+    cellContext: HeaderContext<TableData, TableRow | TableValue>;
+}>;
+
 export declare const Form: ForwardRefExoticComponent<Omit<DataAttributes & NativeProps & AriaAttributes & {
 id?: string | undefined;
 role?: AriaRole | undefined;
@@ -750,6 +1024,11 @@ children?: ReactNode;
 
 export declare const Header: FC<Props_3>;
 
+export declare type HeaderCell = FC<unknown & {
+    title?: string;
+    headerContext: HeaderContext<TableData, TableValue | TableRow>;
+}>;
+
 export declare const I: ForwardRefExoticComponent<DataAttributes & AriaAttributes & {
 id?: string | undefined;
 role?: AriaRole | undefined;
@@ -1264,34 +1543,19 @@ export declare const NumberCurrency: ForwardRefExoticComponent<DataAttributes &
 id?: string | undefined;
 role?: AriaRole | undefined;
 className?: string | undefined;
-} & Omit<NumberProps, "notation" | "compactDisplay"> & {
-/**
-* Provide ISO 4217 currency code
-* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currency_2
-*/
-currency: keyof typeof CurrencyCodes;
-/**
-* How to display the currency in currency formatting
-* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currencydisplay
-*/
-currencyDisplay?: "symbol" | "name" | "code" | "narrowSymbol" | undefined;
-/**
-* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currencysign
-*/
-currencySign?: "standard" | "accounting" | undefined;
-} & RefAttributes<HTMLSpanElement>>;
+} & Omit<NumberProps, "unitDisplay" | "unit" | "notation" | "compactDisplay"> & RefAttributes<HTMLSpanElement>>;
 
 export declare const NumberDecimal: ForwardRefExoticComponent<DataAttributes & AriaAttributes & {
 id?: string | undefined;
 role?: AriaRole | undefined;
 className?: string | undefined;
-} & NumberProps & RefAttributes<HTMLSpanElement>>;
+} & Omit<NumberProps, "unitDisplay" | "unit" | "currency" | "currencyDisplay" | "currencySign"> & RefAttributes<HTMLSpanElement>>;
 
 export declare const NumberPercent: ForwardRefExoticComponent<DataAttributes & AriaAttributes & {
 id?: string | undefined;
 role?: AriaRole | undefined;
 className?: string | undefined;
-} & Omit<NumberProps, "notation" | "compactDisplay"> & RefAttributes<HTMLSpanElement>>;
+} & Omit<NumberProps, "unitDisplay" | "unit" | "currency" | "currencyDisplay" | "currencySign" | "notation" | "compactDisplay"> & RefAttributes<HTMLSpanElement>>;
 
 declare type NumberProps = {
     /** Provide a value to be formatted */
@@ -1332,24 +1596,37 @@ declare type NumberProps = {
      * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#signdisplay
      */
     signDisplay?: keyof typeof SignDisplayModes;
+    /**
+     * Provide a unit for the number
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#unit_2
+     */
+    unit?: keyof typeof Units;
+    /**
+     * The unit formatting style to use in unit formatting
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#unitdisplay
+     */
+    unitDisplay?: keyof typeof UnitDisplayModes;
+    /**
+     * Provide ISO 4217 currency code
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currency_2
+     */
+    currency: keyof typeof CurrencyCodes;
+    /**
+     * How to display the currency in currency formatting
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currencydisplay
+     */
+    currencyDisplay?: keyof typeof CurrencyDisplayTypes;
+    /**
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#currencysign
+     */
+    currencySign?: keyof typeof CurrencySignModes;
 };
 
 export declare const NumberUnit: ForwardRefExoticComponent<DataAttributes & AriaAttributes & {
 id?: string | undefined;
 role?: AriaRole | undefined;
 className?: string | undefined;
-} & NumberProps & {
-/**
-* Provide a unit for the number
-* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#unit_2
-*/
-unit: keyof typeof Units;
-/**
-* The unit formatting style to use in unit formatting
-* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#unitdisplay
-*/
-unitDisplay?: "short" | "narrow" | "long" | undefined;
-} & RefAttributes<HTMLSpanElement>>;
+} & Omit<NumberProps, "currency" | "currencyDisplay" | "currencySign"> & RefAttributes<HTMLSpanElement>>;
 
 declare type OffsetConfig = {
     /** The number of columns to off set this item from left side on extremely small devices (≥360px) */
@@ -1418,6 +1695,8 @@ showNavigation?: boolean | undefined;
 showPageButtons?: boolean | undefined;
 } & RefAttributes<HTMLDivElement>>;
 
+export { PaginationState }
+
 declare type Permission = `https://${string}` | 'self' | '*' | 'src' | 'none' | boolean;
 
 export declare type PermissionsConfig = {
@@ -1665,6 +1944,17 @@ children?: ReactNode;
 contentEditable?: HTMLAttributes<HTMLPreElement>['contentEditable'];
 } & RefAttributes<HTMLPreElement>>;
 
+export declare enum ProcessingModes {
+    /**
+     * Data processed by the table. Semi-controlled mode, prop changes overwrite the state
+     */
+    internal = "internal",
+    /**
+     * Data processed by the developer. Full controlled mode
+     */
+    external = "external"
+}
+
 export declare const Progress: ForwardRefExoticComponent<DataAttributes & AriaAttributes & {
 id?: string | undefined;
 role?: AriaRole | undefined;
@@ -1742,6 +2032,7 @@ declare type Props_6 = {
     type?: keyof typeof ActionTypes;
     onClick?: (name: MouseEvent_2<HTMLButtonElement>) => void;
     className?: string;
+    disabled?: boolean;
 };
 
 declare type Props_7 = {
@@ -1784,6 +2075,19 @@ export declare const Provider: FC<Props>;
 
 declare type Range_2<TStart extends number, TFinish extends number> = Exclude<Enumerate<TFinish>, Enumerate<TStart>>;
 
+declare type RangeFilterValue = number[];
+
+export declare enum RenderModes {
+    /**
+     * Table renders as a virtualized list containing all cells
+     */
+    virtual = "virtual",
+    /**
+     * Table renders as multiple pages of a certain size
+     */
+    paginated = "paginated"
+}
+
 export declare const Row: ForwardRefExoticComponent<DataAttributes & AriaAttributes & {
 id?: string | undefined;
 role?: AriaRole | undefined;
@@ -1794,6 +2098,8 @@ as?: string | undefined;
 children: ReactNode;
 } & RefAttributes<HTMLElement>>;
 
+export { RowSelectionState }
+
 export declare const S: ForwardRefExoticComponent<DataAttributes & AriaAttributes & {
 id?: string | undefined;
 role?: AriaRole | undefined;
@@ -1986,6 +2292,20 @@ className?: string | undefined;
 children?: ReactNode;
 } & RefAttributes<HTMLElement>>;
 
+export declare type SortingFn = SortingFn_2<TableData>;
+
+export declare enum SortingModes {
+    auto = "auto",
+    alphanumeric = "alphanumeric",
+    alphanumericCaseSensitive = "alphanumericCaseSensitive",
+    text = "text",
+    textCaseSensitive = "textCaseSensitive",
+    datetime = "datetime",
+    basic = "basic"
+}
+
+export { SortingState }
+
 declare type Source = {
     /**
      * Provide the source image url
@@ -2069,8 +2389,21 @@ role?: AriaRole | undefined;
 className?: string | undefined;
 } & {
 children: ReactNode;
+wrapperRef?: MutableRefObject<HTMLDivElement | null> | undefined;
+wrapperClassName?: string | undefined;
 } & RefAttributes<HTMLTableElement>>;
 
+/**
+ * Very liberal table data definition
+ */
+export declare type TableData = TableRow[];
+
+declare type TableRow = {
+    [property: string]: TableRow | TableValue;
+};
+
+declare type TableValue = string | number;
+
 export declare const Tabs: ForwardRefExoticComponent<DataAttributes & AriaAttributes & {
 id?: string | undefined;
 role?: AriaRole | undefined;
@@ -2395,6 +2728,12 @@ children?: ReactNode;
 
 declare type Unit = number | 'fluid';
 
+declare enum UnitDisplayModes {
+    short = "short",
+    narrow = "narrow",
+    long = "long"
+}
+
 /**
  * List of available units
  * @see https://tc39.es/ecma402/#table-sanctioned-single-unit-identifiers