From fba85949e7e95ff84a9f4a874ff8c4a3931c4aab Mon Sep 17 00:00:00 2001 From: Michael Salzmann Date: Thu, 12 Sep 2024 07:53:01 +0200 Subject: [PATCH] fix: regenerate outdated README.md files (#2900) --- packages/components/data-table/README.md | 146 +++++++++++++++--- .../dropdowns/dropdown-menu/README.md | 5 +- .../components/fields/date-field/README.md | 6 +- .../components/fields/radio-field/README.md | 2 +- .../inputs/multiline-text-input/README.md | 2 +- .../components/inputs/text-input/README.md | 42 ++--- .../primary-action-dropdown/README.md | 2 +- packages/components/stamp/README.md | 14 +- 8 files changed, 159 insertions(+), 60 deletions(-) diff --git a/packages/components/data-table/README.md b/packages/components/data-table/README.md index 39148494c6..704191f207 100644 --- a/packages/components/data-table/README.md +++ b/packages/components/data-table/README.md @@ -59,33 +59,129 @@ export default Example; ## Properties -| Props | Type | Required | Default | Description | -| ------------------------- | ---------------------------------------------------------------- | :------: | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `rows` | `Array: Row[]` | ✅ | | The list of data that needs to be rendered in the table. Each object in the list can have any shape as long as it has a unique identifier. The data is rendered by using the callback render function `itemRenderer`. | -| `columns` | `Array: TColumn[]`
[See signature.](#signature-columns) | | `[]` | Each object requires a unique `key` which should correspond to property key of the items of `rows` that you want to render under this column, and a `label` which defines the name shown on the header. The list of columns to be rendered. Each column can be customized (see properties below). | -| `footer` | `ReactNode` | | | Element to render within the `tfoot` (footer) element of the table. | -| `maxWidth` | `union`
Possible values:
`number , string` | | | The max width (a number of pixels or a css value string with units) for which the table is allowed to grow. If unset, the table will grow horizontally to fill its parent. | -| `maxHeight` | `union`
Possible values:
`number , string` | | | The max height (a number of pixels or a css value string with units) for which the table is allowed to grow. If unset, the table will grow vertically to fill its parent and we are able to have a sticky header. | -| `onRowClick` | `Function`
[See signature.](#signature-onRowClick) | | | A callback function, called when a user clicks on a row. | -| `isCondensed` | `boolean` | | `true` | Set this to `true` to reduce the paddings of all cells, allowing the table to display more data in less space. | -| `onColumnResized` | `Function`
[See signature.](#signature-onColumnResized) | | | A callback function, called when a column has been resized. Use this callback to get the resized column widths and save them, to be able to restore the value once the user comes back to the page. | -| `disableSelfContainment` | `boolean` | | `false` | Set this to `true` to take control of the containment of the table and doing it on a parent element. This means that the table will grow in size without adding scrollbars on itself, both vertically and horizontally and, as a consequence, the `maxHeight` and `maxWidth` props are ignored. If you need to enforce these constraints, you must also apply them on the parent element. Additionally, the sticky behaviour of the header will get fixed relatively to the closest parent element with `position: relative`. | -| `disableHeaderStickiness` | `boolean` | | | Set this to `true` to prevent the header from being sticky. The header can be sticky only if the table does not have a `maxHeight` set. | -| `itemRenderer` | `Function`
[See signature.](#signature-itemRenderer) | | `(row, column) => row[column.key]` | The default function used to render the content of each item in a cell. In case a column has its own `renderItem` render function, it will take precedence over this function. | -| `wrapHeaderLabels` | `boolean` | | `true` | Set this to `false` to ensure that every column can render their label in one line. By default the header cell grows in height in case the label does not fit in one line. | -| `verticalCellAlignment` | `union`
Possible values:
`'top' , 'center' , 'bottom'` | | `'top'` | The default cell vertical alignment of each row (not the table header). | -| `horizontalCellAlignment` | `union`
Possible values:
`'left' , 'center' , 'right'` | | `'left'` | The default cell horizontal alignment. In case a column has its own `align` property, it will take precedence over this value. | -| `sortedBy` | `string` | | | The key of the column for which the data is currently sorted by. | -| `onSortChange` | `Function`
[See signature.](#signature-onSortChange) | | | A callback function, called when a sortable column's header is clicked. It's required when the `isSortable` flag is set on at least one column. | -| `sortDirection` | `union`
Possible values:
`'desc' , 'asc'` | | | The sorting direction. | -| `customSettingsPayload` | `Record` | | | Manage custom settings for the table | -| `customColumns` | `Array: TColumn[]` | | | The columns of the nested items to be rendered in the table. Just like the columns, Each object requires a unique `key` which should correspond to property key of the items of `rows` that you want to render under this column, and a `label` which defines the name shown on the header. The list of columns to be rendered. | -| `customRows` | `Array: Row[]` | | | The list of data that needs to be rendered in the nested component. Each object in the list can have any shape as long as it has a unique identifier. | +| Props | Type | Required | Default | Description | +| --------- | ---------------------------------------------------------------- | :------: | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `rows` | `Array: Row[]` | ✅ | | The list of data that needs to be rendered in the table. Each object in the list can have any shape as long as it has a unique identifier. The data is rendered by using the callback render function `itemRenderer`. | +| `columns` | `Array: TColumn[]`
[See signature.](#signature-columns) | | `[]` | Each object requires a unique `key` which should correspond to property key of the items of `rows` that you want to render under this column, and a `label` which defines the name shown on the header. The list of columns to be rendered.Column item shape:``` | + +{ +key: string; +label: ReactNode; +width?: string; +align?: 'left' | 'center' | 'right'; +onClick?: (event: MouseEventHandler) => void; +renderItem?: (row: Row, isRowCollapsed: boolean) => ReactNode; +headerIcon?: ReactNode; +isTruncated?: boolean; +isSortable?: boolean; +disableResizing?: boolean; +shouldIgnoreRowClick?: boolean; +} + +````[Colum signatures with description](/?path=/docs/components-datatable-readme--props#signatures) | +| `customColumns` | `Array: TColumn[]`
[See signature.](#signature-customColumns) | | | The columns of the nested items to be rendered in the table. Just like the columns, Each object requires a unique `key` which should correspond to property key of the items of `rows` that you want to render under this column, and a `label` which defines the name shown on the header. The list of columns to be rendered. | +| `footer` | `ReactNode` | | | Element to render within the `tfoot` (footer) element of the table. | +| `maxWidth` | `union`
Possible values:
`number , string` | | | The max width (a number of pixels or a css value string with units) for which the table is allowed to grow. If unset, the table will grow horizontally to fill its parent. | +| `maxHeight` | `union`
Possible values:
`number , string` | | | The max height (a number of pixels or a css value string with units) for which the table is allowed to grow. If unset, the table will grow vertically to fill its parent and we are able to have a sticky header. | +| `onRowClick` | `Function`
[See signature.](#signature-onRowClick) | | | A callback function, called when a user clicks on a row. | +| `isCondensed` | `boolean` | | `true` | Set this to `true` to reduce the paddings of all cells, allowing the table to display more data in less space. | +| `onColumnResized` | `Function`
[See signature.](#signature-onColumnResized) | | | A callback function, called when a column has been resized. Use this callback to get the resized column widths and save them, to be able to restore the value once the user comes back to the page. | +| `disableSelfContainment` | `boolean` | | `false` | Set this to `true` to take control of the containment of the table and doing it on a parent element. This means that the table will grow in size without adding scrollbars on itself, both vertically and horizontally and, as a consequence, the `maxHeight` and `maxWidth` props are ignored. If you need to enforce these constraints, you must also apply them on the parent element. Additionally, the sticky behaviour of the header will get fixed relatively to the closest parent element with `position: relative`. | +| `disableHeaderStickiness` | `boolean` | | | Set this to `true` to prevent the header from being sticky. The header can be sticky only if the table does not have a `maxHeight` set. | +| `itemRenderer` | `Function`
[See signature.](#signature-itemRenderer) | | `(row, column) => row[column.key]` | The default function used to render the content of each item in a cell. In case a column has its own `renderItem` render function, it will take precedence over this function. | +| `wrapHeaderLabels` | `boolean` | | `true` | Set this to `false` to ensure that every column can render their label in one line. By default the header cell grows in height in case the label does not fit in one line. | +| `verticalCellAlignment` | `union`
Possible values:
`'top' , 'center' , 'bottom'` | | `'top'` | The default cell vertical alignment of each row (not the table header). | +| `horizontalCellAlignment` | `union`
Possible values:
`'left' , 'center' , 'right'` | | `'left'` | The default cell horizontal alignment. In case a column has its own `align` property, it will take precedence over this value. | +| `sortedBy` | `string` | | | The key of the column for which the data is currently sorted by. | +| `onSortChange` | `Function`
[See signature.](#signature-onSortChange) | | | A callback function, called when a sortable column's header is clicked. It's required when the `isSortable` flag is set on at least one column. | +| `sortDirection` | `union`
Possible values:
`'desc' , 'asc'` | | | The sorting direction. | +| `renderNestedRow` | `Function`
[See signature.](#signature-renderNestedRow) | | | Custom row renderer for nested rows. | +| `maxExpandableHeight` | `number` | | | If this is provided, then it should control the height of the expanded rows. In the event where there is more content than the maxHeight, a scrollbar should make provision for the overflow. | ## Signatures ### Signature `columns` +```ts +{ + /** + * The unique key of the column that is used to identify your data type. + * You can use this value to determine which value from a row item should be rendered. + *
+ * For example, if the data is a list of users, where each user has a `firstName` property, + * the column key should be `firstName`, which renders the correct value by default. + * The key can also be some custom or computed value, in which case you need to provide + * an explicit mapping of the value by implementing either the `itemRendered` function or + * the column-specific `renderItem` function. + */ + key: string; + /** + * The label of the column that will be shown on the column header. + */ + label: ReactNode; + /** + * Sets a width for this column. Accepts the same values as the ones specified for + * individual [grid-template-columns](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns). + *
+ * For example, using `minmax` pairs (e.g. `minmax(200px, 400px)`), a combinations of + * fraction values (`1fr`/`2fr`/etc), or fixed values such as `200px`. + * By default, the column grows according to the content and respecting the total table available width. + */ + width?: string; + /** + * Use this to override the table's own `horizontalCellAlignment` prop for this specific column. + */ + align?: 'left' | 'center' | 'right'; + /** + * A callback function, called when the header cell is clicked. + */ + onClick?: (event: MouseEventHandler) => void; + /** + * A callback function to render the content of cells under this column, overriding + * the default `itemRenderer` prop of the table. + */ + renderItem?: (row: Row, isRowCollapsed: boolean) => ReactNode; + /** + * Use this prop to place an `Icon` or `IconButton` on the left of the column label. + * It is advised to place these types of components through this prop instead of `label`, + * in order to properly position and align the elements. + * This is particularly useful for medium-sized icons which require more vertical space than the typography. + */ + headerIcon?: ReactNode; + /** + * Set this to `true` to allow text content of this cell to be truncated with an ellipsis, + * instead of breaking into multiple lines. + *
+ * NOTE: when using this option, it is recommended to specify a `width` for the column, because + * if the table doesn't have enough space for all columns, it will start clipping the columns + * with _truncated_ content, and if no `width` is set (or the value is set `auto` -- the default) + * it can shrink until the column disappears completely. + * By enforcing a minimum width for these columns, the table will respect them and grow horizontally, + * adding scrollbars if needed. + */ + isTruncated?: boolean; + /** + * Set this to `true` to show a sorting button, which calls `onSortChange` upon being clicked. + * You should enable this flag for every column you want to be able to sort. + * When at least one column is sortable, the table props `sortBy`, `sortDirection` and `onSortChange` should be provided. + */ + isSortable?: boolean; + /** + * Set this to `true` to prevent this column from being manually resized by dragging + * the edge of the header with a mouse. + */ + disableResizing?: boolean; + /** + * Set this to `true` to prevent click event propagation for this cell. + * You might want this if you need the column to have its own call-to-action or input while + * the row also has a defined `onRowClick`. + */ + shouldIgnoreRowClick?: boolean; +} +```` + +### Signature `customColumns` + ```ts { /** @@ -187,3 +283,9 @@ export default Example; ```ts (columnKey: string, sortDirection: 'asc' | 'desc') => void ``` + +### Signature `renderNestedRow` + +```ts +(row: Row) => ReactNode; +``` diff --git a/packages/components/dropdowns/dropdown-menu/README.md b/packages/components/dropdowns/dropdown-menu/README.md index aee9f84390..cc402f813f 100644 --- a/packages/components/dropdowns/dropdown-menu/README.md +++ b/packages/components/dropdowns/dropdown-menu/README.md @@ -11,10 +11,7 @@ It allows to use any component as the element used to trigger the floating panel The panel can be customized to render whatever is needed. However, as a common use case would be to render a list of elements and select one of them, this component provides some helpers to easily implement such use case. -Something to bear in mind: - -- when the panel is open, the document scroll is blocked -- if there is limited screen estate, the `menuPosition` may be adjusted to ensure the menu is displayed properly +Something to bear in mind is that, when the panel is open, the document scroll is blocked. ## Installation diff --git a/packages/components/fields/date-field/README.md b/packages/components/fields/date-field/README.md index 737c1f4311..2e67bdcdb3 100644 --- a/packages/components/fields/date-field/README.md +++ b/packages/components/fields/date-field/README.md @@ -66,9 +66,9 @@ export default Example; | `isCondensed` | `boolean` | | | Use this property to reduce the paddings of the component for a ui compact variant | | `minValue` | `string` | | | A minimum selectable date. Must either be an empty string or a date formatted as "YYYY-MM-DD". | | `maxValue` | `string` | | | A maximum selectable date. Must either be an empty string or a date formatted as "YYYY-MM-DD". | -| `title` | `union`
Possible values:
`string , ReactNode` | ✅ | | Title of the label | -| `hint` | `union`
Possible values:
`string , ReactNode` | | | Hint for the label. Provides a supplementary but important information regarding the behaviour of the input (e.g warn about uniqueness of a field, when it can only be set once), whereas `description` can describe it in more depth. Can also receive a `hintIcon`. | -| `description` | `union`
Possible values:
`string , ReactNode` | | | Provides a description for the title. | +| `title` | `ReactNode` | ✅ | | Title of the label | +| `hint` | `ReactNode` | | | Hint for the label. Provides a supplementary but important information regarding the behaviour of the input (e.g warn about uniqueness of a field, when it can only be set once), whereas `description` can describe it in more depth. Can also receive a `hintIcon`. | +| `description` | `ReactNode` | | | Provides a description for the title. | | `onInfoButtonClick` | `Function`
[See signature.](#signature-onInfoButtonClick) | | | Function called when info button is pressed.
Info button will only be visible when this prop is passed. | | `hintIcon` | `ReactElement` | | | Icon to be displayed beside the hint text.
Will only get rendered when `hint` is passed as well. | | `badge` | `ReactNode` | | | Badge to be displayed beside the label.
Might be used to display additional information about the content of the field (E.g verified email) | diff --git a/packages/components/fields/radio-field/README.md b/packages/components/fields/radio-field/README.md index c6e1ba0504..73203b96da 100644 --- a/packages/components/fields/radio-field/README.md +++ b/packages/components/fields/radio-field/README.md @@ -61,7 +61,7 @@ export default Example; | `isRequired` | `boolean` | | | Indicates if the value is required. Shows an the "required asterisk" if so. | | `touched` | `boolean` | | | Indicates whether the field was touched. Errors will only be shown when the field was touched. | | `name` | `string` | | | Used as HTML name of the input component. | -| `value` | `string` or `boolean` | ✅ | | Value of the input component. | +| `value` | `union`
Possible values:
`string , boolean` | ✅ | | Value of the input component. | | `onChange` | `ChangeEventHandler` | | | Called with an event containing the new value. Required when input is not read only. Parent should pass it back as value. | | `onBlur` | `FocusEventHandler` | | | Called when input is blurred | | `onFocus` | `FocusEventHandler` | | | Called when input is focused | diff --git a/packages/components/inputs/multiline-text-input/README.md b/packages/components/inputs/multiline-text-input/README.md index 72b9e99d71..bae6eb1550 100644 --- a/packages/components/inputs/multiline-text-input/README.md +++ b/packages/components/inputs/multiline-text-input/README.md @@ -67,7 +67,7 @@ export default Example; | `hasError` | `boolean` | | | Indicates that input has errors | | `hasWarning` | `boolean` | | | Control to indicate on the input if there are selected values that are potentially invalid | | `horizontalConstraint` | `union`
Possible values:
`, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 'scale', 'auto'` | | | Horizontal size limit of the input fields. | -| `rightActionIcon` | `ReactElement` | | | Custom action icon to be displayed on the right side of the input. | +| `rightActionIcon` | `ReactElement` | | | Custom action icon to be displayed on the right side of the input. **Will only show**, if `rightActionProps` is provided. | | `rightActionProps` | `TSecondaryButtonIconProps` | | | Props for the right-action icon-button. Required when rightActionIcon is provided. At least a `label` and an `onClick` prop/function need to be provided. | | `isCondensed` | `boolean` | | | Set this to `true` to reduce the paddings of the input allowing the input to display more data in less space. | | `maxRows` | `number` | | | Set this to value to determine the maximum text rows of the text area. Any text overflow past this row number would implement a scroll | diff --git a/packages/components/inputs/text-input/README.md b/packages/components/inputs/text-input/README.md index 166cc68347..a10a40017f 100644 --- a/packages/components/inputs/text-input/README.md +++ b/packages/components/inputs/text-input/README.md @@ -41,27 +41,27 @@ export default Example; ## Properties -| Props | Type | Required | Default | Description | -| ---------------------- | ----------------------------------------------------------------------------------------------------- | :------: | --------- | ------------------------------------------------------------------------------------------------------------------------- | -| `id` | `string` | | | Used as HTML id property. An id is auto-generated when it is not specified. | -| `autoComplete` | `string` | | | Used as HTML autocomplete property | -| `aria-invalid` | `boolean` | | | Indicate if the value entered in the input is invalid. | -| `aria-errormessage` | `string` | | | HTML ID of an element containing an error message related to the input. | -| `className` | `string` | | | `className` forwarded to the underlying ``. | -| `name` | `string` | | | Used as HTML name of the input component. property | -| `value` | `string` | ✅ | | Value of the input component. | -| `onChange` | `ChangeEventHandler` | | | Called with an event containing the new value. Required when input is not read only. Parent should pass it back as value. | -| `onBlur` | `FocusEventHandler` | | | Called when input is blurred | -| `onFocus` | `FocusEventHandler` | | | Called when input is focused | -| `isAutofocussed` | `boolean` | | | Focus the input on initial render | -| `isCondensed` | `boolean` | | | Use this property to reduce the paddings of the component for a ui compact variant | -| `isDisabled` | `boolean` | | | Indicates that the input cannot be modified (e.g not authorized, or changes currently saving). | -| `isReadOnly` | `boolean` | | | Indicates that the field is displaying read-only content | -| `hasError` | `boolean` | | | Indicates if the input has invalid values | -| `hasWarning` | `boolean` | | | | -| `placeholder` | `string` | | | Placeholder text for the input | -| `maxLength` | `number` | | | Maximum number of characters allowed in the input field | -| `horizontalConstraint` | `union`
Possible values:
`, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 'scale', 'auto'` | | `'scale'` | Horizontal size limit of the input fields. | +| Props | Type | Required | Default | Description | +| ---------------------- | ----------------------------------------------------------------------------------------------------- | :------: | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `string` | | | Used as HTML id property. An id is auto-generated when it is not specified. | +| `autoComplete` | `string` | | | Used as HTML autocomplete property | +| `aria-invalid` | `boolean` | | | Indicate if the value entered in the input is invalid. | +| `aria-errormessage` | `string` | | | HTML ID of an element containing an error message related to the input. | +| `className` | `string` | | | `className` forwarded to the underlying ``. | +| `name` | `string` | | | Used as HTML name of the input component. property | +| `value` | `string` | ✅ | | Value of the input component. | +| `onChange` | `ChangeEventHandler` | | | Called with an event containing the new value. Required when input is not read only. Parent should pass it back as value. | +| `onBlur` | `FocusEventHandler` | | | Called when input is blurred | +| `onFocus` | `FocusEventHandler` | | | Called when input is focused | +| `isAutofocussed` | `boolean` | | | Focus the input on initial render | +| `isCondensed` | `boolean` | | | Use this property to reduce the paddings of the component for a ui compact variant | +| `isDisabled` | `boolean` | | | Indicates that the input cannot be modified (e.g not authorized, or changes currently saving). | +| `isReadOnly` | `boolean` | | | Indicates that the field is displaying read-only content | +| `hasError` | `boolean` | | | Indicates if the input has invalid values | +| `hasWarning` | `boolean` | | | | +| `placeholder` | `string` | | | Placeholder text for the input | +| `horizontalConstraint` | `union`
Possible values:
`, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 'scale', 'auto'` | | `'scale'` | Horizontal size limit of the input fields. | +| `maxLength` | `number` | | | Maximum number of characters allowed in the input. If this prop is used, it is recommended to inform the user about this limit in the InputField description, or otherwise. | ## `data-*` props diff --git a/packages/components/primary-action-dropdown/README.md b/packages/components/primary-action-dropdown/README.md index 9135321120..1a3a6aac0e 100644 --- a/packages/components/primary-action-dropdown/README.md +++ b/packages/components/primary-action-dropdown/README.md @@ -71,7 +71,7 @@ export default Example; | `onClick` | `Function`
[See signature.](#signature-onClick) | ✅ | | Event handler triggers whenever the option is clicked. | | `isDisabled` | `boolean` | | `false` | Disables the option within the dropdown. If all options are disabled the dropdown will be disabled. | | `children` | `string` | ✅ | | Any string which serves as the label. | -| `iconLeft` | `ReactNode` | ✅ | | Any React node. | +| `iconLeft` | `ReactNode` | | | Any React node. | ### Signatures diff --git a/packages/components/stamp/README.md b/packages/components/stamp/README.md index e7d16225db..41371c5491 100644 --- a/packages/components/stamp/README.md +++ b/packages/components/stamp/README.md @@ -39,10 +39,10 @@ export default Example; ## Properties -| Props | Type | Required | Default | Description | -| ------------- | ------------------------------------------------------------------------------------------------------------- | :------: | --------------- | -------------------------------------------------------------------------------------------------- | -| `tone` | `union`
Possible values:
`, 'critical', 'warning', 'positive', 'information', 'primary', 'secondary'` | | `'information'` | Indicates the color scheme of stamp | -| `isCondensed` | `boolean` | | `false` | If `true`, renders a condensed version of the stamp. | -| `children` | `ReactNode` | | | Content to render within the stamp. This property has been **deprecated** in favor of `label`. | -| `icon` | `ReactElement` | | | Icon to render beside (left) the stamp text. | -| `label` | `string` | | | Text to render within the stamp. | +| Props | Type | Required | Default | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------- | :------: | --------------- | ------------------------------------------------------------------------ | +| `tone` | `union`
Possible values:
`, 'critical', 'warning', 'positive', 'information', 'primary', 'secondary'` | | `'information'` | Indicates the color scheme of stamp | +| `isCondensed` | `boolean` | | `false` | If `true`, renders a condensed version of the stamp. | +| `children` | `ReactNode` | | | Content to render within the stamp. @deprecated in favor of `label`. | +| `icon` | `ReactElement` | | | Icon to render beside (left) the stamp text. | +| `label` | `string` | | | Text to render within the stamp. |