diff --git a/CHANGELOG.md b/CHANGELOG.md index cbe94863ce3..d99eed8cf3f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ - Added `minWidth` prop to `EuiButton` ([4056](https://github.com/elastic/eui/pull/4056)) - Added `isSelected` prop to easily turn `EuiButton`, `EuiButtonEmpty`, and `EuiButtonIcon` into toggle buttons ([4056](https://github.com/elastic/eui/pull/4056)) - Updated `EuiButtonGroup` props and render for better accessibility ([4056](https://github.com/elastic/eui/pull/4056)) +- Added more exports for `EuiBasicTable` types ([#4125](https://github.com/elastic/eui/pull/4125)) **Breaking changes** diff --git a/src-docs/src/views/tables/basic/basic_section.js b/src-docs/src/views/tables/basic/basic_section.js index bc7c146460f..9f25e5ff613 100644 --- a/src-docs/src/views/tables/basic/basic_section.js +++ b/src-docs/src/views/tables/basic/basic_section.js @@ -2,9 +2,22 @@ import React from 'react'; import { GuideSectionTypes } from '../../../components'; import { renderToHtml } from '../../../services'; import { EuiCode } from '../../../../../src/components'; -import { propsInfo } from './props_info'; - import { Table } from './basic'; +import { EuiBasicTable } from '../../../../../src/components/basic_table'; +import { + Criteria, + CriteriaWithPagination, +} from '!!prop-loader!../../../../../src/components/basic_table/basic_table'; +import { Pagination } from '!!prop-loader!../../../../../src/components/basic_table/pagination_bar'; +import { + EuiTableFieldDataColumnType, + EuiTableComputedColumnType, + EuiTableActionsColumnType, + EuiTableSelectionType, + EuiTableSortingType, +} from '!!prop-loader!../../../../../src/components/basic_table/table_types'; +import { CustomItemAction } from '!!prop-loader!../../../../../src/components/basic_table/action_types'; +import { DefaultItemActionProps as DefaultItemAction } from './props'; const source = require('!!raw-loader!./basic'); const html = renderToHtml(Table); @@ -81,6 +94,18 @@ export const section = { ), - props: propsInfo, + props: { + EuiBasicTable, + Criteria, + CriteriaWithPagination, + Pagination, + EuiTableSortingType, + EuiTableSelectionType, + EuiTableFieldDataColumnType, + EuiTableComputedColumnType, + EuiTableActionsColumnType, + DefaultItemAction, + CustomItemAction, + }, demo: , }; diff --git a/src-docs/src/views/tables/basic/props.tsx b/src-docs/src/views/tables/basic/props.tsx new file mode 100644 index 00000000000..0cabf76cdeb --- /dev/null +++ b/src-docs/src/views/tables/basic/props.tsx @@ -0,0 +1,9 @@ +import React, { FunctionComponent } from 'react'; +import { DefaultItemAction } from '../../../../../src/components/basic_table/action_types'; + +// Simulating the `item` generic +type T = {}; + +export const DefaultItemActionProps: FunctionComponent> = () =>
; diff --git a/src/components/basic_table/action_types.ts b/src/components/basic_table/action_types.ts index 1057e7b9c9c..d42fb5829d9 100644 --- a/src/components/basic_table/action_types.ts +++ b/src/components/basic_table/action_types.ts @@ -27,13 +27,28 @@ type IconFunction = (item: T) => EuiIconType; type ButtonColor = EuiButtonIconColor | EuiButtonEmptyColor; type EuiButtonIconColorFunction = (item: T) => ButtonColor; -interface DefaultItemActionBase { +export interface DefaultItemActionBase { + /** + * The display name of the action (will be the button caption) + */ name: ReactNode | ((item: T) => ReactNode); + /** + * Describes the action (will be the button title) + */ description: string; + /** + * A handler function to execute the action + */ onClick?: (item: T) => void; href?: string; target?: string; + /** + * A callback function that determines whether the action is available + */ available?: (item: T) => boolean; + /** + * A callback function that determines whether the action is enabled + */ enabled?: (item: T) => boolean; isPrimary?: boolean; 'data-test-subj'?: string; @@ -41,6 +56,9 @@ interface DefaultItemActionBase { export interface DefaultItemEmptyButtonAction extends DefaultItemActionBase { + /** + * The type of action + */ type?: 'button'; color?: EuiButtonEmptyColor | EuiButtonIconColorFunction; } @@ -48,7 +66,13 @@ export interface DefaultItemEmptyButtonAction export interface DefaultItemIconButtonAction extends DefaultItemActionBase { type: 'icon'; + /** + * Associates an icon with the button + */ icon: EuiIconType | IconFunction; + /** + * Defines the color of the button + */ color?: EuiButtonIconColor | EuiButtonIconColorFunction; } @@ -58,8 +82,17 @@ export type DefaultItemAction = ExclusiveUnion< >; export interface CustomItemAction { + /** + * The function that renders the action. Note that the returned node is expected to have `onFocus` and `onBlur` functions + */ render: (item: T, enabled: boolean) => ReactElement; + /** + * A callback that defines whether the action is available + */ available?: (item: T) => boolean; + /** + * A callback that defines whether the action is enabled + */ enabled?: (item: T) => boolean; isPrimary?: boolean; } diff --git a/src/components/basic_table/basic_table.tsx b/src/components/basic_table/basic_table.tsx index 3ada08a1b25..3f69432e32e 100644 --- a/src/components/basic_table/basic_table.tsx +++ b/src/components/basic_table/basic_table.tsx @@ -177,10 +177,16 @@ export type EuiBasicTableColumn = | EuiTableActionsColumnType; export interface Criteria { + /** + * If the shown items represents a page (slice) into a bigger set, this describes this page + */ page?: { index: number; size: number; }; + /** + * If the shown items are sorted, this describes the sort criteria + */ sort?: { field: keyof T; direction: Direction; @@ -188,6 +194,9 @@ export interface Criteria { } export interface CriteriaWithPagination extends Criteria { + /** + * If the shown items represents a page (slice) into a bigger set, this describes this page + */ page: { index: number; size: number; @@ -198,24 +207,81 @@ type CellPropsCallback = (item: T, column: EuiBasicTableColumn) => object; type RowPropsCallback = (item: T) => object; interface BasicTableProps extends Omit { + /** + * Describes how to extract a unique ID from each item, used for selections & expanded rows + */ itemId?: ItemId; + /** + * Row expansion uses the itemId prop to identify each row + */ itemIdToExpandedRowMap?: ItemIdToExpandedRowMap; + /** + * A list of objects to who in the table - an item per row + */ items: T[]; + /** + * Applied to `EuiTableRowCell` + */ cellProps?: object | CellPropsCallback; + /** + * An array of one of the objects: #EuiTableFieldDataColumnType, #EuiTableComputedColumnType or #EuiTableActionsColumnType. + */ columns: Array>; + /** + * Error message to display + */ error?: string; + /** + * Describes the content of the table. If not specified, the caption will be "This table contains {itemCount} rows." + */ tableCaption?: string; + /** + * Indicates which column should be used as the identifying cell in each row. Should match a "field" prop in FieldDataColumn + */ rowHeader?: string; hasActions?: boolean; isExpandable?: boolean; isSelectable?: boolean; + /** + * Provides an infinite loading indicator + */ loading?: boolean; + /** + * Message to display if table is empty + */ noItemsMessage?: ReactNode; + /** + * Called whenever pagination or sorting changes (this property is required when either pagination or sorting is configured). See #Criteria or #CriteriaWithPagination + */ onChange?: (criteria: Criteria) => void; + /** + * Configures #Pagination + */ pagination?: undefined; + /** + * If true, will convert table to cards in mobile view + */ + responsive?: boolean; + /** + * Applied to `EuiTableRow` + */ rowProps?: object | RowPropsCallback; + /** + * Configures #EuiTableSelectionType + */ selection?: EuiTableSelectionType; + /** + * Configures #EuiTableSortingType + */ sorting?: EuiTableSortingType; + /** + * Sets the table-layout CSS property. Note that auto tableLayout prevents truncateText from working properly. + */ + tableLayout?: 'fixed' | 'auto'; + /** + * Applied to table cells => Any cell using render function will set this to be false, leading to unnecessary word breaks. Apply textOnly: true in order to ensure it breaks properly + */ + textOnly?: boolean; } type BasicTableWithPaginationProps = Omit< diff --git a/src/components/basic_table/index.ts b/src/components/basic_table/index.ts index 28abc47f05c..f9301c3cf2d 100644 --- a/src/components/basic_table/index.ts +++ b/src/components/basic_table/index.ts @@ -21,6 +21,8 @@ export { EuiBasicTable, EuiBasicTableProps, EuiBasicTableColumn, + Criteria, + CriteriaWithPagination, } from './basic_table'; export { EuiInMemoryTable, EuiInMemoryTableProps } from './in_memory_table'; export { @@ -32,3 +34,5 @@ export { EuiTableSelectionType, EuiTableSortingType, } from './table_types'; +export { Pagination } from './pagination_bar'; +export { DefaultItemAction, CustomItemAction } from './action_types'; diff --git a/src/components/basic_table/pagination_bar.tsx b/src/components/basic_table/pagination_bar.tsx index f7c0dc9e6eb..29b4a53f69e 100644 --- a/src/components/basic_table/pagination_bar.tsx +++ b/src/components/basic_table/pagination_bar.tsx @@ -26,10 +26,25 @@ import { } from '../table/table_pagination/table_pagination'; export interface Pagination { + /** + * The current page (zero-based) index + */ pageIndex: number; + /** + * The maximum number of items that can be shown in a single page + */ pageSize: number; + /** + * The total number of items the page is "sliced" of + */ totalItemCount: number; + /** + * Configures the page size dropdown options + */ pageSizeOptions?: number[]; + /** + * Hides the page size dropdown + */ hidePerPageOptions?: boolean; } diff --git a/src/components/basic_table/table_types.ts b/src/components/basic_table/table_types.ts index 551ffd6168a..3dc227d0595 100644 --- a/src/components/basic_table/table_types.ts +++ b/src/components/basic_table/table_types.ts @@ -41,15 +41,39 @@ export interface EuiTableFooterProps { export interface EuiTableFieldDataColumnType extends CommonProps, TdHTMLAttributes { + /** + * A field of the item (may be a nested field) + */ field: keyof T | string; // supports outer.inner key paths + /** + * The display name of the column + */ name: ReactNode; + /** + * A description of the column (will be presented as a title over the column header) + */ description?: string; + /** + * Describes the data types of the displayed value (serves as a rendering hint for the table) + */ dataType?: EuiTableDataType; + /** + * A CSS width property. Hints for the required width of the column (e.g. "30%", "100px", etc..) + */ width?: string; + /** + * Defines whether the user can sort on this column. If a function is provided, this function returns the value to sort against + */ sortable?: boolean | ((item: T) => Primitive); isExpander?: boolean; textOnly?: boolean; + /** + * Defines the horizontal alignment of the column + */ align?: HorizontalAlignment; + /** + * Indicates whether this column should truncate its content when it doesn't fit + */ truncateText?: boolean; isMobileHeader?: boolean; mobileOptions?: { @@ -59,7 +83,13 @@ export interface EuiTableFieldDataColumnType header?: boolean; }; hideForMobile?: boolean; + /** + * Describe a custom renderer function for the content + */ render?: (value: any, record: T) => ReactNode; + /** + * Content to display in the footer beneath this column + */ footer?: | string | ReactElement @@ -69,35 +99,84 @@ export interface EuiTableFieldDataColumnType export interface EuiTableComputedColumnType extends CommonProps, TdHTMLAttributes { + /** + * A function that computes the value for each item and renders it + */ render: (record: T) => ReactNode; + /** + * The display name of the column + */ name?: ReactNode; + /** + * A description of the column (will be presented as a title over the column header + */ description?: string; + /** + * If provided, allows this column to be sorted on. Must return the value to sort against. + */ sortable?: (item: T) => Primitive; + /** + * A CSS width property. Hints for the required width of the column + */ width?: string; + /** + * Indicates whether this column should truncate its content when it doesn't fit + */ truncateText?: boolean; isExpander?: boolean; align?: HorizontalAlignment; } export interface EuiTableActionsColumnType { + /** + * An array of one of the objects: #DefaultItemAction or #CustomItemAction + */ actions: Array>; + /** + * The display name of the column + */ name?: ReactNode; + /** + * A description of the column (will be presented as a title over the column header + */ description?: string; + /** + * A CSS width property. Hints for the required width of the column + + */ width?: string; } export interface EuiTableSortingType { + /** + * Indicates the property/field to sort on + */ sort?: { field: keyof T; direction: Direction; }; + /** + * Enables/disables unsorting of table columns. Supported by EuiInMemoryTable. + */ allowNeutralSort?: boolean; + /** + * Enables the default sorting ability for each column. + */ enableAllColumns?: boolean; } export interface EuiTableSelectionType { + /** + * A callback that will be called whenever the item selection changes + */ onSelectionChange?: (selection: T[]) => void; + /** + * A callback that is called per item to indicate whether it is selectable + */ selectable?: (item: T) => boolean; + /** + * A callback that is called per item to retrieve a message for its selectable state.We display these messages as a tooltip on an unselectable checkbox + */ selectableMessage?: (selectable: boolean, item: T) => string; initialSelected?: T[]; }