diff --git a/src/dash-table/Table.js b/src/dash-table/Table.js index 1be951830..7ea272dae 100644 --- a/src/dash-table/Table.js +++ b/src/dash-table/Table.js @@ -85,23 +85,84 @@ export const defaultProps = { }; export const propTypes = { + /** + * The [row, column] index of which cell is currently + * active. + */ active_cell: PropTypes.array, - // .exact + + /** + * Columns describes various aspects about each individual column. + * `name` and `id` are the only required parameters. + */ columns: PropTypes.arrayOf(PropTypes.shape({ + + /** + * TODO - What does this do? + */ clearable: PropTypes.bool, + + /** + * If True, the user can delete the column by clicking on a little `x` + * button on the column. + * If there are merged, multi-header columns then you can choose + * which column header row to display the "x" in by + * supplying a column row index. + * For example, `0` will display the "x" on the first row, + * `1` on the second row. + * If the "x" appears on a merged column, then clicking on that button + * will delete *all* of the merged columns associated with it. + */ deletable: PropTypes.oneOfType([ PropTypes.bool, PropTypes.number ]), + + /** + * If True, then the data associated with this column is editable. + * Note that this can be toggled on a per-table basis with the + * higher level `editable` flag. + */ editable: PropTypes.bool, + + /** + * If True, then the name of this column is editable. + */ editable_name: PropTypes.oneOfType([ PropTypes.bool, PropTypes.number ]), + + /** + * If True, then the column and its data is hidden. + * This can be useful if you want to transport extra + * meta data (like a data index) to and from callbacks + * but you don't necessarily want to display that data. + */ hidden: PropTypes.bool, + + /** + * The `id` of the column. + * The column `id` is used to match cells in data + * with particular columns. + * The `id` is not visible in the table. + */ id: PropTypes.string.isRequired, - name: PropTypes.string.isRequired, - // .exact + /** + * The `name` of the column, + * as it appears in the column header. + * If `name` is a list of strings, then the columns + * will render with multiple headers rows. + */ + name: PropTypes.oneOfType([ + PropTypes.string, + PropTypes.arrayOf(PropTypes.string) + ]).isRequired, + + /** + * DEPRECATED + * Please use `column_static_dropdown` instead + */ options: PropTypes.arrayOf(PropTypes.shape({ label: PropTypes.oneOfType([ PropTypes.number, @@ -112,44 +173,245 @@ export const propTypes = { PropTypes.string ]).isRequired })), + + /** + * The data-type of the column's data. + * `numeric` and `text` are currently the same. + * `dropdown` is used to render cells as dropdowns. + * NOTE: This feature has not been fully implemented. + * In the future, it's data types will impact things like + * text formatting options in the cell (e.g. display 2 decimals + * for a number), filtering options and behavior, and editing + * behavior. + * Stay tuned by following [https://github.com/plotly/dash-table/issues/166](https://github.com/plotly/dash-table/issues/166) + */ type: PropTypes.oneOf(['dropdown', 'numeric', 'text']) + })), + + /** + * `content_style` toggles between a set of CSS styles for + * two common behaviors: + * TODO - `fit` - The table will ...? + * `grow` - The table will expand to its parents container. + */ content_style: PropTypes.oneOf(['fit', 'grow']), - // .exact + /** + * css is a way to embed CSS selectors and rules + * onto the page. + * We recommend starting with the `style_*` properties + * before using this `css` property. + * + * Example: + * [ + * {"selector": ".dash-spreadsheet", "rule": 'font-family: "monospace"'} + * ] + * + */ css: PropTypes.arrayOf(PropTypes.shape({ selector: PropTypes.string.isRequired, rule: PropTypes.string.isRequired })), + /** + * The contents of the table. + * The keys in item in data should match the column IDs. + * Example: + * + * [ + * {'column-1': 4.5, 'column-2': 'montreal', 'column-3': 'canada'}, + * {'column-1': 8, 'column-2': 'boston', 'column-3': 'america'} + * ] + * + */ data: PropTypes.arrayOf(PropTypes.object), + + /** + * The previous state of `data`. `data_previous` + * has the same structure as `data` and it will be updated + * whenever `data` changes, either through a callback or + * by editing the table. + * This is a read-only property: setting this property will not + * have any impact on the table. + */ data_previous: PropTypes.arrayOf(PropTypes.object), + + /** + * The unix timestamp when the data was last edited. + * Use this property with other timestamp properties + * (such as `n_clicks_timestamp` in `dash_html_components`) + * to determine which property has changed within a callback. + */ data_timestamp: PropTypes.number, + /** + * If True, then the data in all of the cells is editable. + * Note that this can be toggled on a per-column basis with the + * `editable` flag inside the `columns` property. + */ editable: PropTypes.bool, + + /** + * When selecting multiple cells + * (via clicking on a cell and then shift-clicking on another cell), + * `end_cell` represents the [row, column] coordinates of the cell + * in one of the corners of the region. + * `start_cell` represents the coordinates of the other corner. + */ end_cell: PropTypes.arrayOf(PropTypes.number), + + /** + * The ID of the table. + */ id: PropTypes.string, + + /** + * If True, then the `active_cell` is in a focused state. + */ is_focused: PropTypes.bool, + + /** + * If True, then column headers that have neighbors with duplicate names + * will be merged into a single cell. + * This will be applied for single column headers and multi-column + * headers. + */ merge_duplicate_headers: PropTypes.bool, + + /** + * `n_fixed_columns` will "fix" the set of columns so that + * they remain visible when scrolling horizontally across + * the unfixed columns. `n_fixed_columns` fixes columns + * from left-to-right, so `n_fixed_columns=3` will fix + * the first 3 columns. + * + * Note that fixing columns introduces some changes to the + * underlying markup of the table and may impact the + * way that your columns are rendered or sized. + * View the documentation examples to learn more. + */ n_fixed_columns: PropTypes.number, + + /** + * `n_fixed_rows` will "fix" the set of rows so that + * they remain visible when scrolling vertically down + * the table. `n_fixed_rows` fixes rows + * from top-to-bottom, starting from the headers, + * so `n_fixed_columns=1` will fix the header row, + * `n_fixed_rows=2` will fix the header row and the first row, + * or the first two header rows (if there are multiple headers). + */ n_fixed_rows: PropTypes.number, + + /** + * If True, then a `x` will appear next to each `row` + * and the user can delete the row. + */ row_deletable: PropTypes.bool, + + /** + * If `single`, then the user can select a single row + * via a radio button that will appear next to each row. + * If `multi`, then the user can select multiple rows + * via a checkbox that will appear next to each row. + * If `False`, then the user will not be able to select rows + * and no additional UI elements will appear. + * + * When a row is selected, its index will be contained + * in `selected_rows`. + */ row_selectable: PropTypes.oneOf(['single', 'multi', false]), + + /** + * `selected_cell` represents the cell that is currently + * selected. + * TODO - How is this different than `active_cell`? + */ selected_cell: PropTypes.arrayOf(PropTypes.arrayOf(PropTypes.number)), + + /** + * `selected_rows` contains the indices of the rows that + * are selected via the UI elements that appear when + * `row_selectable` is `'single'` or `'multi'`. + */ selected_rows: PropTypes.arrayOf(PropTypes.number), + setProps: PropTypes.func, + + /** + * When selecting multiple cells + * (via clicking on a cell and then shift-clicking on another cell), + * `start_cell` represents the [row, column] coordinates of the cell + * in one of the corners of the region. + * `end_cell` represents the coordinates of the other corner. + */ start_cell: PropTypes.arrayOf(PropTypes.number), + + /** + * DEPRECATED + */ style_as_list_view: PropTypes.bool, + /** + * "pagination" refers to a mode of the table where + * not all of the rows are displayed at once: only a subset + * are displayed (a "page") and the next subset of rows + * can viewed by clicking "Next" or "Previous" buttons + * at the bottom of the page. + * + * Pagination is used to improve performance: instead of + * rendering all of the rows at once (which can be expensive), + * we only display a subset of them. + * + * With pagination, we can either page through data that exists + * in the table (e.g. page through `10,000` rows in `data` `100` rows at a time) + * or we can update the data on-the-fly with callbacks + * when the user clicks on the "Previous" or "Next" buttons. + * These modes can be toggled with this `pagination_mode` parameter: + * - `'fe'` refers to "front-end" paging: passing large data up-front + * - `'be'` refers to "back-end" paging: updating the data on the fly via callbacks + * - `False` will disable paging, attempting to render all of the data at once + * TODO - What does `True` do? + * + * NOTE: The `fe` and `be` names may change in the future. + * Tune in to [https://github.com/plotly/dash-table/issues/167](https://github.com/plotly/dash-table/issues/167) for more. + */ pagination_mode: PropTypes.oneOf(['fe', 'be', true, false]), - // .exact + + /** + * `pagination_settings` controls the pagination settings + * _and_ represents the current state of the pagination UI. + * - `page_size` represents the number of rows that will be + * displayed on a particular page. + * - `current_page` represents which page the user is on. + * Use this property to index through data in your callbacks with + * backend paging. + * TODO - What does `displayed_pages` to? + */ pagination_settings: PropTypes.shape({ displayed_pages: PropTypes.number.isRequired, current_page: PropTypes.number.isRequired, page_size: PropTypes.number.isRequired }), + + /** + * DEPRECATED + */ navigation: PropTypes.string, - // .exact + /** + * `column_conditional_dropdowns` specifies the available options + * for dropdowns in various columns and cells. + * This property allows you to specify different dropdowns + * depending on certain conditions. For example, you may + * render different "city" dropdowns in a row depending on the + * current value in the "state" column. + * + * NOTE: The naming and the behavior of this option may change + * in the future. + * Tune in to [https://github.com/plotly/dash-table/issues/168](https://github.com/plotly/dash-table/issues/168) + */ +>>>>>>> :pencil: prop type comments column_conditional_dropdowns: PropTypes.arrayOf(PropTypes.shape({ id: PropTypes.string.isRequired, // .exact @@ -165,7 +427,17 @@ export const propTypes = { })).isRequired })).isRequired })), - // .exact + /** + * `column_static_dropdown` represents the available dropdown + * options for different columns. + * The `id` property refers to the column ID. + * The `dropdown` property refers to the `options` of the + * dropdown. + * + * NOTE: The naming and the behavior of this option may change + * in the future. + * Tune in to [https://github.com/plotly/dash-table/issues/168](https://github.com/plotly/dash-table/issues/168) + */ column_static_dropdown: PropTypes.arrayOf(PropTypes.shape({ id: PropTypes.string.isRequired, // .exact @@ -178,30 +450,156 @@ export const propTypes = { })).isRequired })), + /** + * The `filtering` controls whether or not the filtering UI + * should be displayed and the `filtering` behavior. + * If `False`, then the filtering UI is not displayed + * If `fe`, then the filtering UI is displayed and the filtering + * happens in the "front-end". That is, it is performed on the data + * that exists in the `data` property. + * If `be`, then the filtering UI is displayed but it is the + * responsibility of the developer to program the filtering + * through a callback (where `filtering_settings` would be the input + * and `data` would be the output). + * TODO - What does `True` do? + * NOTE - Several aspects of filtering may change in the future, + * including the naming of this property. + * Tune in to [https://github.com/plotly/dash-table/issues/167](https://github.com/plotly/dash-table/issues/167) + */ filtering: PropTypes.oneOf(['fe', 'be', true, false]), + + /** + * If `filtering` is enabled, then the current filtering + * string is represented in this `filtering_settings` + * property. + * NOTE: The shape and structure of this property will + * likely change in the future. + * Stay tuned in [https://github.com/plotly/dash-table/issues/169](https://github.com/plotly/dash-table/issues/169) + */ filtering_settings: PropTypes.string, + + /** + * UNSTABLE + * In the future, there may be several modes of the + * filtering UI like `basic`, `advanced`, etc. + * Currently, we only `basic`. + * NOTE - This will likely change in the future, + * subscribe to changes here: + * [https://github.com/plotly/dash-table/issues/169](https://github.com/plotly/dash-table/issues/169) + */ filtering_type: PropTypes.oneOf(['basic']), + + /** + * UNSTABLE + * In the future, there may be several modes of the + * filtering UI like `basic`, `advanced`, etc + * NOTE - This will likely change in the future, + * subscribe to changes here: + * [https://github.com/plotly/dash-table/issues/169](https://github.com/plotly/dash-table/issues/169) + */ filtering_types: PropTypes.arrayOf(PropTypes.oneOf([ 'basic' ])), + /** + * The `sorting` property enables data to be + * sorted on a per-column basis. + * Enabling `sorting` will display a UI element + * on each of the columns (up and down arrows). + * + * Sorting can be performed in the "front-end" + * with the `fe` setting or via a callback in your + * python "back-end" with the `be` setting. + * Clicking on the sort arrows will update the + * `sorting_settings` property. + */ sorting: PropTypes.oneOf(['fe', 'be', true, false]), + + /** + * Sorting can be performed across multiple columns + * (e.g. sort by country, and within each country, + * sort by year) or by a single column. + * + * NOTE - With multi-column sort, it's currently + * not possible to determine the order in which + * the columns were sorted through the UI. + * See [https://github.com/plotly/dash-table/issues/170](https://github.com/plotly/dash-table/issues/170) + */ sorting_type: PropTypes.oneOf(['single', 'multi']), + + /** + * `sorting_settings` describes the current state + * of the sorting UI. + * That is, if the user clicked on the sort arrow + * of a column, then this property will be updated + * with the column ID and the direction + * (`asc` or `desc`) of the sort. + * For multi-column sorting, this will be a list of + * sorting parameters, in the order in which they were + * clicked. + * + * NOTE - We may rename `columnId` to `column_id` in + * the future. + * Subscribe to [https://github.com/plotly/dash-table/issues/171](https://github.com/plotly/dash-table/issues/171) + * for details. + */ sorting_settings: PropTypes.arrayOf( // .exact PropTypes.shape({ columnId: PropTypes.oneOfType([PropTypes.string, PropTypes.number]).isRequired, direction: PropTypes.oneOf(['asc', 'desc']).isRequired })), + + /** + * When we sort, should empty strings (`''`) be considered + * valid values (they will appear first when sorting ascending) + * or should they be ignored (always appearing last)? + */ sorting_treat_empty_string_as_none: PropTypes.bool, + /** + * CSS styles to be applied to the outer `table` container. + * + * This is commonly used for setting properties like the + * width or the height of the table. + */ style_table: PropTypes.object, + /** + * CSS styles to be applied to each individual cell of the table. + * + * This includes the header cells, the `data` cells, and the filter + * cells. + */ style_cell: PropTypes.object, + + /** + * CSS styles to be applied to each individual data cell. + * + * That is, unlike `style_cell`, it excludes the header and filter cells. + */ style_data: PropTypes.object, + + /** + * CSS styles to be applied to the filter cells. + * + * Note that this may change in the future as we build out a + * more complex filtering UI. + */ style_filter: PropTypes.object, + + /** + * CSS styles to be applied to each individual header cell. + * + * That is, unlike `style_cell`, it excludes the `data` and filter cells. + */ style_header: PropTypes.object, + /** + * Conditional CSS styles for the cells. + * + * This can be used to apply styles to cells on a per-column basis. + */ style_cell_conditional: PropTypes.arrayOf(PropTypes.shape({ // .exact if: PropTypes.shape({ @@ -209,6 +607,11 @@ export const propTypes = { }) })), + /** + * Conditional CSS styles for the data cells. + * + * This can be used to apply styles to data cells on a per-column basis. + */ style_data_conditional: PropTypes.arrayOf(PropTypes.shape({ // .exact if: PropTypes.shape({ @@ -220,6 +623,11 @@ export const propTypes = { }) })), + /** + * Conditional CSS styles for the filter cells. + * + * This can be used to apply styles to filter cells on a per-column basis. + */ style_filter_conditional: PropTypes.arrayOf(PropTypes.shape({ // .exact if: PropTypes.shape({ @@ -227,6 +635,11 @@ export const propTypes = { }) })), + /** + * Conditional CSS styles for the header cells. + * + * This can be used to apply styles to header cells on a per-column basis. + */ style_header_conditional: PropTypes.arrayOf(PropTypes.shape({ // .exact if: PropTypes.shape({ @@ -238,13 +651,37 @@ export const propTypes = { }) })), + /** + * This property represents the current state of `data` + * on the current page. This property will be updated + * on paging, sorting, and filtering. + */ derived_viewport_data: PropTypes.arrayOf(PropTypes.object), + + /** + * TODO - Is this the `selected_rows` or just the indicies w.r.t. + * the original data? + */ derived_viewport_indices: PropTypes.arrayOf(PropTypes.number), + + /** + * This property represents the visible state of `data` + * across all pages after the front-end sorting and filtering + * as been applied. + */ derived_virtual_data: PropTypes.arrayOf(PropTypes.object), + + /** + * TODO - Is this the `selected_rows` or just the indicies w.r.t. + * the original data? + */ derived_virtual_indices: PropTypes.arrayOf(PropTypes.number), + /** + * DEPRECATED + */ dropdown_properties: PropTypes.any, }; Table.defaultProps = defaultProps; -Table.propTypes = propTypes; \ No newline at end of file +Table.propTypes = propTypes;