From cd660baf22a0d06edd9dac2a178599e5ee556728 Mon Sep 17 00:00:00 2001 From: tcbegley Date: Sat, 15 Feb 2025 07:17:36 +0000 Subject: [PATCH 1/4] Make all props after id keyword only --- justfile | 8 ++++++- tests/test_positional_args.py | 44 +++++++++++++++++++++++++---------- 2 files changed, 39 insertions(+), 13 deletions(-) diff --git a/justfile b/justfile index 6a6ad29f..784aa14c 100644 --- a/justfile +++ b/justfile @@ -137,4 +137,10 @@ _move-generated-files: if file_.name in ("__init__.py", "_table.py", "_version.py", "icons.py", "themes.py"): continue filename = "__init__.py" if file_.name == "_imports_.py" else file_.name - file_.rename(file_.parent / "_components" / filename) + new_file = file_.parent / "_components" / filename + file_.rename(new_file) + # enforce keyword arguments only after the id argument + id_pattern = " id: typing.Optional[str] = None,\n" + new_file.write_text( + new_file.read_text().replace(id_pattern, f"{id_pattern}{8 * ' '}*,\n") + ) diff --git a/tests/test_positional_args.py b/tests/test_positional_args.py index 8f2f7901..9c5a7d9c 100644 --- a/tests/test_positional_args.py +++ b/tests/test_positional_args.py @@ -1,12 +1,15 @@ +import inspect + +import dash_bootstrap_components as dbc +import pytest from dash import Dash, html -from dash_bootstrap_components import Checklist, RadioItems, Select +from dash_bootstrap_components._components import __all__ as COMPONENT_NAMES from selenium.webdriver.common.by import By def test_dbpa001_checklist(dash_duo): """ - Check that the options and value positional arguments are working for - Checklist. + Check that the options and value positional arguments are working for dbc.Checklist. """ app = Dash() @@ -18,12 +21,12 @@ def test_dbpa001_checklist(dash_duo): value = "OptionB" - with_keywords = Checklist( + with_keywords = dbc.Checklist( options=options, value=value, id="with-keywords", ) - without_keywords = Checklist(options, value, id="without-keywords") + without_keywords = dbc.Checklist(options, value, id="without-keywords") app.layout = html.Div([with_keywords, without_keywords]) @@ -59,7 +62,7 @@ def test_dbpa001_checklist(dash_duo): def test_dbpa002_radio_items(dash_duo): """ Check that the options and value positional arguments are working for - RadioItems. + dbc.RadioItems. """ app = Dash() @@ -71,12 +74,12 @@ def test_dbpa002_radio_items(dash_duo): value = "OptionB" - with_keywords = RadioItems( + with_keywords = dbc.RadioItems( options=options, value=value, id="with-keywords", ) - without_keywords = RadioItems(options, value, id="without-keywords") + without_keywords = dbc.RadioItems(options, value, id="without-keywords") app.layout = html.Div([with_keywords, without_keywords]) @@ -111,8 +114,7 @@ def test_dbpa002_radio_items(dash_duo): def test_dbpa003_select(dash_duo): """ - Check that the options and value positional arguments are working for - Select. + Check that the options and value positional arguments are working for dbc.Select. """ app = Dash() @@ -124,12 +126,12 @@ def test_dbpa003_select(dash_duo): value = "OptionB" - with_keywords = Select( + with_keywords = dbc.Select( options=options, value=value, id="with-keywords", ) - without_keywords = Select(options, value, id="without-keywords") + without_keywords = dbc.Select(options, value, id="without-keywords") app.layout = html.Div([with_keywords, without_keywords]) @@ -160,3 +162,21 @@ def test_dbpa003_select(dash_duo): by=By.TAG_NAME, value="option" ) ] + + +@pytest.mark.parametrize("component_name", COMPONENT_NAMES) +def test_dbpa004_keyword_only_args(component_name): + component = getattr(dbc, component_name) + signature = inspect.signature(component) + id_seen = False + for name, param in signature.parameters.items(): + if name == "id": + id_seen = True + elif id_seen: + # all parameters after the id should be keyword only or **kwargs + assert param.kind in ( + inspect.Parameter.KEYWORD_ONLY, + inspect.Parameter.VAR_KEYWORD, + ) + + assert id_seen From 36f036e133d580bf29761c530987b79ee40002b0 Mon Sep 17 00:00:00 2001 From: tcbegley Date: Fri, 21 Feb 2025 22:26:43 +0000 Subject: [PATCH 2/4] Reorder props and make docstrings consistent --- src/components/accordion/Accordion.js | 98 ++- src/components/accordion/AccordionItem.js | 41 +- src/components/alert/Alert.js | 112 ++-- src/components/badge/Badge.js | 93 ++- src/components/breadcrumb/Breadcrumb.js | 59 +- src/components/button/Button.js | 105 ++-- src/components/buttongroup/ButtonGroup.js | 44 +- src/components/card/Card.js | 72 +-- src/components/card/CardBody.js | 43 +- src/components/card/CardFooter.js | 39 +- src/components/card/CardGroup.js | 38 +- src/components/card/CardHeader.js | 40 +- src/components/card/CardImg.js | 67 ++- src/components/card/CardImgOverlay.js | 44 +- src/components/card/CardLink.js | 59 +- src/components/carousel/Carousel.js | 156 +++-- src/components/collapse/Collapse.js | 56 +- src/components/dropdownmenu/DropdownMenu.js | 140 ++--- .../dropdownmenu/DropdownMenuItem.js | 71 +-- src/components/fade/Fade.js | 60 +- src/components/form/Form.js | 61 +- src/components/form/FormFeedback.js | 52 +- src/components/form/FormFloating.js | 38 +- src/components/form/FormText.js | 42 +- src/components/form/Label.js | 94 ++- src/components/input/Checkbox.js | 161 +++-- src/components/input/Checklist.js | 222 ++++--- src/components/input/Input.js | 566 +++++++++--------- src/components/input/InputGroup.js | 40 +- src/components/input/InputGroupText.js | 36 +- src/components/input/RadioButton.js | 123 ++-- src/components/input/RadioItems.js | 191 +++--- src/components/input/Select.js | 112 ++-- src/components/input/Switch.js | 157 +++-- src/components/input/Textarea.js | 368 ++++++------ src/components/layout/Col.js | 126 ++-- src/components/layout/Container.js | 56 +- src/components/layout/Row.js | 63 +- src/components/layout/Stack.js | 46 +- src/components/listgroup/ListGroup.js | 67 ++- src/components/listgroup/ListGroupItem.js | 78 ++- src/components/modal/Modal.js | 184 +++--- src/components/modal/ModalBody.js | 32 +- src/components/modal/ModalFooter.js | 30 +- src/components/modal/ModalHeader.js | 40 +- src/components/modal/ModalTitle.js | 30 +- src/components/nav/Nav.js | 88 +-- src/components/nav/NavItem.js | 34 +- src/components/nav/NavLink.js | 81 ++- src/components/nav/Navbar.js | 72 +-- src/components/nav/NavbarBrand.js | 56 +- src/components/nav/NavbarSimple.js | 125 ++-- src/components/nav/NavbarToggler.js | 49 +- src/components/offcanvas/Offcanvas.js | 110 ++-- src/components/pagination/Pagination.js | 67 +-- src/components/placeholder/Placeholder.js | 75 +-- src/components/popover/Popover.js | 190 +++--- src/components/popover/PopoverBody.js | 43 +- src/components/popover/PopoverHeader.js | 41 +- src/components/progress/Progress.js | 86 +-- src/components/spinner/Spinner.js | 102 ++-- src/components/table/Table.js | 67 +-- src/components/tabs/Tab.js | 120 ++-- src/components/tabs/Tabs.js | 77 ++- src/components/toast/Toast.js | 177 +++--- src/components/tooltip/Tooltip.js | 100 ++-- src/private/Link.js | 19 +- src/private/types.js | 23 + 68 files changed, 3109 insertions(+), 3145 deletions(-) create mode 100644 src/private/types.js diff --git a/src/components/accordion/Accordion.js b/src/components/accordion/Accordion.js index 1eb4e26c..38cea6a3 100644 --- a/src/components/accordion/Accordion.js +++ b/src/components/accordion/Accordion.js @@ -15,11 +15,11 @@ import {getLoadingState} from '../../private/util'; function Accordion({ children, active_item, - key, - class_name, - className, always_open = false, start_collapsed = false, + class_name, + className, + key, setProps, ...otherProps }) { @@ -92,52 +92,22 @@ Accordion.dashPersistence = { Accordion.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. - */ - id: PropTypes.string, - - /** - * The children of this component + * The children of the Accordion. */ children: PropTypes.node, /** - * Defines CSS styles which will override styles previously set. - */ - style: PropTypes.object, - - /** - * Often used with CSS to style elements with common properties. + * The ID of the Accordion. */ - class_name: PropTypes.string, - - /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. - */ - className: PropTypes.string, - - /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info - */ - key: PropTypes.string, - - /** - * Renders accordion edge-to-edge with its parent container - */ - flush: PropTypes.bool, + id: PropTypes.string, /** * The item_id of the currently active item. If item_id has not been specified * for the active item, this will default to item-i, where i is the index * (starting from 0) of the item. * - * If `always_open=True`, this needs to be a list of string IDs. + * If `always_open=True`, then active_item should be a list item_ids of all the + * currently open AccordionItems */ active_item: PropTypes.oneOfType([ PropTypes.string, @@ -145,23 +115,33 @@ Accordion.propTypes = { ]), /** - * You can make accordion items stay open when another item is opened by - * using the always_open prop. + * If True, multiple items can be expanded at once. */ always_open: PropTypes.bool, /** - * Set to True for all items to be collapsed initially. + * If True, all items will start collapsed. */ start_collapsed: PropTypes.bool, /** - * Used to allow user interactions in this component to be persisted when - * the component - or the page - is refreshed. If `persisted` is truthy and - * hasn't changed from its previous value, a `value` that the user has - * changed while using the app will keep that change, as long as - * the new `value` also matches what was given originally. - * Used in conjunction with `persistence_type`. + * If True the Accordion will be rendered edge-to-edge within its parent container. + */ + flush: PropTypes.bool, + + /** + * Additional inline styles to apply to the Accordion + */ + style: PropTypes.object, + + /** + * Additional CSS class to apply to the Accordion. + */ + class_name: PropTypes.string, + + /** + * Used to allow user interactions to be persisted when the page is refreshed. + * See https://dash.plotly.com/persistence for more details */ persistence: PropTypes.oneOfType([ PropTypes.bool, @@ -170,20 +150,34 @@ Accordion.propTypes = { ]), /** - * Properties whose user interactions will persist after refreshing the - * component or the page. Since only `value` is allowed this prop can + * Properties to persist. Since only `active_item` is supported, this prop can * normally be ignored. */ persisted_props: PropTypes.arrayOf(PropTypes.oneOf(['active_item'])), /** * Where persisted user changes will be stored: - * memory: only kept in memory, reset on page refresh. - * local: window.localStorage, data is kept after the browser quit. - * session: window.sessionStorage, data is cleared once the browser quit. + * - memory: only kept in memory, reset on page refresh. + * - local: window.localStorage, data is kept after the browser quit. + * - session: window.sessionStorage, data is cleared once the browser quit. */ persistence_type: PropTypes.oneOf(['local', 'session', 'memory']), + /** + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info + */ + key: PropTypes.string, + + /** + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS class to apply to the Accordion. + */ + className: PropTypes.string, + /** * Dash-assigned callback that gets fired when the value changes. */ diff --git a/src/components/accordion/AccordionItem.js b/src/components/accordion/AccordionItem.js index b772bedd..10589639 100644 --- a/src/components/accordion/AccordionItem.js +++ b/src/components/accordion/AccordionItem.js @@ -11,12 +11,12 @@ import {getLoadingState, stringifyId} from '../../private/util'; * A component to build up the children of the accordion. */ function AccordionItem({ + children, + id, title, item_id, class_name, className, - id, - children, ...otherProps }) { const {toggle, idx} = useContext(AccordionContext); @@ -43,46 +43,49 @@ function AccordionItem({ AccordionItem.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. + * The ID of the AccordionItem. */ id: PropTypes.string, /** - * The children of this component + * The children of the AccordionItem. */ children: PropTypes.node, /** - * Defines CSS styles which will override styles previously set. + * Text to display in the header of the AccordionItem. + */ + title: PropTypes.node, + + /** + * Optional identifier for item used for determining which item is visible if not + * specified, and AccordionItem is being used inside Accordion component, the item_id + * will be set to "item-i" where i is (zero indexed) position of item in list items + * passed to Accordion component. + */ + item_id: PropTypes.string, + + /** + * Additional inline CSS styles to apply to the AccordionItem. */ style: PropTypes.object, /** - * Often used with CSS to style elements with common properties. + * Additional CSS classes to apply to the AccordionItem. */ class_name: PropTypes.string, /** * **DEPRECATED** Use `class_name` instead. * - * Often used with CSS to style elements with common properties. + * Additional CSS classes to apply to the AccordionItem. */ className: PropTypes.string, /** - * The title on display in the collapsed accordion item. - */ - title: PropTypes.node, - - /** - * Optional identifier for item used for determining which item is visible - * if not specified, and AccordionItem is being used inside Accordion component, the itemId - * will be set to "item-i" where i is (zero indexed) position of item in list - * items pased to Accordion component. + * Dash-assigned callback that gets fired when the value changes. */ - item_id: PropTypes.string + setProps: PropTypes.func }; export default AccordionItem; diff --git a/src/components/alert/Alert.js b/src/components/alert/Alert.js index 73d1a970..b60ac8dd 100644 --- a/src/components/alert/Alert.js +++ b/src/components/alert/Alert.js @@ -15,19 +15,25 @@ import {getLoadingState} from '../../private/util'; */ function Alert({ children, + is_open = true, + color = 'success', dismissable, + duration = null, + fade, style, class_name, className, - fade, - color = 'success', - is_open = true, - duration = null, setProps, ...otherProps }) { const timeout = useRef(null); + const dismiss = () => { + if (setProps) { + setProps({is_open: false}); + } + }; + useEffect(() => { if (duration) { if (is_open) { @@ -38,13 +44,7 @@ function Alert({ } } return () => clearTimeout(timeout.current); - }, [is_open]); - - const dismiss = () => { - if (setProps) { - setProps({is_open: false}); - } - }; + }, [is_open, duration]); const isBootstrapColor = bootstrapColors.has(color); return ( @@ -57,7 +57,7 @@ function Alert({ transition={fade} style={!isBootstrapColor ? {backgroundColor: color, ...style} : style} {...omit( - ['persistence', 'persisted_props', 'persistence_type', 'setProps'], + ['persistence', 'persisted_props', 'persistence_type'], otherProps )} data-dash-is-loading={getLoadingState() || undefined} @@ -74,77 +74,57 @@ Alert.dashPersistence = { Alert.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. - */ - id: PropTypes.string, - - /** - * The children of this component. + * The children of the Alert. */ children: PropTypes.node, /** - * Defines CSS styles which will override styles previously set. + * The ID of the Alert. */ - style: PropTypes.object, + id: PropTypes.string, /** - * Often used with CSS to style elements with common properties. + * Whether the Alert is open (i.e. visible to the user). Default: True. */ - class_name: PropTypes.string, + is_open: PropTypes.bool, /** - * **DEPRECATED** Use `class_name` instead. + * Alert color, options: primary, secondary, success, info, warning, danger, + * link or any valid CSS color of your choice (e.g. a hex code, a decimal code or a CSS color name) * - * Often used with CSS to style elements with common properties. - */ - className: PropTypes.string, - - /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * Default: success. */ - key: PropTypes.string, + color: PropTypes.string, /** - * Alert color, options: primary, secondary, success, info, warning, danger, - * link or any valid CSS color of - * your choice (e.g. a hex code, a decimal code or a CSS color name) - * Default: secondary. + * If True, add a close button that allows Alert to be dismissed. */ - color: PropTypes.string, + dismissable: PropTypes.bool, /** - * Whether alert is open. Default: True. + * Duration in milliseconds after which the Alert dismisses itself. */ - is_open: PropTypes.bool, + duration: PropTypes.number, /** - * If True, a fade animation will be applied when `is_open` is toggled. If - * False the Alert will simply appear and disappear. + * If True, a fade animation will be applied when `is_open` is toggled. If False the + * Alert will simply appear and disappear. */ fade: PropTypes.bool, /** - * If true, add a close button that allows Alert to be dismissed. + * Additional inline styles to apply to the Alert. */ - dismissable: PropTypes.bool, + style: PropTypes.object, /** - * Duration in milliseconds after which the Alert dismisses itself. + * Additional CSS class to apply to the Alert. */ - duration: PropTypes.number, + class_name: PropTypes.string, /** - * Used to allow user interactions in this component to be persisted when - * the component - or the page - is refreshed. If `persisted` is truthy and - * hasn't changed from its previous value, a `value` that the user has - * changed while using the app will keep that change, as long as - * the new `value` also matches what was given originally. - * Used in conjunction with `persistence_type`. + * Used to allow user interactions to be persisted when the page is refreshed. + * See https://dash.plotly.com/persistence for more details */ persistence: PropTypes.oneOfType([ PropTypes.bool, @@ -153,20 +133,34 @@ Alert.propTypes = { ]), /** - * Properties whose user interactions will persist after refreshing the - * component or the page. Since only `value` is allowed this prop can - * normally be ignored. + * Properties to persist. Since only `is_open` is supported, this prop can normally be + * ignored. */ persisted_props: PropTypes.arrayOf(PropTypes.oneOf(['is_open'])), /** * Where persisted user changes will be stored: - * memory: only kept in memory, reset on page refresh. - * local: window.localStorage, data is kept after the browser quit. - * session: window.sessionStorage, data is cleared once the browser quit. + * - memory: only kept in memory, reset on page refresh. + * - local: window.localStorage, data is kept after the browser quit. + * - session: window.sessionStorage, data is cleared once the browser quit. */ persistence_type: PropTypes.oneOf(['local', 'session', 'memory']), + /** + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info + */ + key: PropTypes.string, + + /** + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS class to apply to the Alert. + */ + className: PropTypes.string, + /** * Dash-assigned callback that gets fired when the value changes. */ diff --git a/src/components/badge/Badge.js b/src/components/badge/Badge.js index 04a07e0b..1ea8afa6 100644 --- a/src/components/badge/Badge.js +++ b/src/components/badge/Badge.js @@ -14,12 +14,12 @@ import {getLoadingState} from '../../private/util'; function Badge({ children, href, - style, - className, - class_name, - text_color, color = 'secondary', + text_color, n_clicks = 0, + style, + class_name, + className, setProps, ...otherProps }) { @@ -50,56 +50,47 @@ function Badge({ Badge.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. - */ - id: PropTypes.string, - - /** - * The children of this component. + * The children of the Badge. */ children: PropTypes.node, /** - * Defines CSS styles which will override styles previously set. + * The ID of the Badge. */ - style: PropTypes.object, + id: PropTypes.string, /** - * Often used with CSS to style elements with common properties. + * Badge color, options: primary, secondary, success, info, warning, danger, link or + * any valid CSS color of your choice (e.g. a hex code, a decimal code or a CSS + * color name). + * + * Default: secondary. */ - class_name: PropTypes.string, + color: PropTypes.string, /** - * **DEPRECATED** Use `class_name` instead. + * Set the color of the text to one of the Bootstrap contextual colors. * - * Often used with CSS to style elements with common properties. + * Options: primary, secondary, success, info, warning, danger, light or dark. */ - className: PropTypes.string, + text_color: PropTypes.string, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * The number of times the Badge has been clicked. */ - key: PropTypes.string, + n_clicks: PropTypes.number, /** - * Badge color, options: primary, secondary, success, info, warning, danger, - * link or any valid CSS color of - * your choice (e.g. a hex code, a decimal code or a CSS color name) - * Default: secondary. + * A URL to link to when the Badge is clicked. */ - color: PropTypes.string, + href: PropTypes.string, /** - * Badge color, options: primary, secondary, success, info, warning, danger, - * link or any valid CSS color of - * your choice (e.g. a hex code, a decimal code or a CSS color name) - * Default: secondary. + * If True, clicking on the Badge will behave like a hyperlink. If False, the Badge + * will behave like a dcc.Link component, and can be used in conjunction with + * dcc.Location for navigation within a Dash app. */ - text_color: PropTypes.string, + external_link: PropTypes.bool, /** * Make badge "pill" shaped (rounded ends, like a pill). Default: False. @@ -107,9 +98,14 @@ Badge.propTypes = { pill: PropTypes.bool, /** - * Attach link to badge. + * Additional inline CSS styles to apply to the Badge.. */ - href: PropTypes.string, + style: PropTypes.object, + + /** + * Additional CSS classes to apply to the Badge. + */ + class_name: PropTypes.string, /** * HTML tag to use for the Badge. Default: span. @@ -117,30 +113,29 @@ Badge.propTypes = { tag: PropTypes.string, /** - * If true, the browser will treat this as an external link, - * forcing a page refresh at the new location. If false, - * this just changes the location without triggering a page - * refresh. Use this if you are observing dcc.Location, for - * instance. Defaults to true for absolute URLs and false - * otherwise. + * Target attribute to pass on to the link. Only applies to external links. */ - external_link: PropTypes.bool, + target: PropTypes.string, /** - * An integer that represents the number of times - * that this element has been clicked on. + * Sets the title attribute of the underlying HTML button. */ - n_clicks: PropTypes.number, + title: PropTypes.string, /** - * Target attribute to pass on to the link. Only applies to external links. + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info */ - target: PropTypes.string, + key: PropTypes.string, /** - * Sets the title attribute of the underlying HTML button. + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Badge. */ - title: PropTypes.string, + className: PropTypes.string, /** * Dash-assigned callback that gets fired when the value changes. diff --git a/src/components/breadcrumb/Breadcrumb.js b/src/components/breadcrumb/Breadcrumb.js index 8cb3b397..3610c810 100644 --- a/src/components/breadcrumb/Breadcrumb.js +++ b/src/components/breadcrumb/Breadcrumb.js @@ -11,12 +11,12 @@ import {getLoadingState} from '../../private/util'; */ function Breadcrumb({ items, - tag, class_name, className, + item_style, item_class_name, itemClassName, - item_style, + tag, ...otherProps }) { return ( @@ -45,9 +45,7 @@ function Breadcrumb({ Breadcrumb.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. + * The ID of the Breadcrumb. */ id: PropTypes.string, @@ -57,7 +55,7 @@ Breadcrumb.propTypes = { items: PropTypes.arrayOf( PropTypes.shape({ /** - * Label to display inside the breadcrumbs. + * The label to display inside the breadcrumbs. */ label: PropTypes.string, /** @@ -65,15 +63,13 @@ Breadcrumb.propTypes = { */ href: PropTypes.string, /** - * Apply 'active' style to this component. + * If True, the item will be displayed as active. */ active: PropTypes.bool, /** - * If true, the browser will treat this as an external link, forcing a - * page refresh at the new location. If false, this just changes the - * location without triggering a page refresh. Use this if you are - * observing dcc.Location, for instance. Defaults to true for absolute - * URLs and false otherwise. + * If True, clicking on the item will behave like a hyperlink. If False, the item + * will behave like a dcc.Link component, and can be used in conjunction with + * dcc.Location for navigation within a Dash app. */ external_link: PropTypes.bool, /** @@ -81,58 +77,63 @@ Breadcrumb.propTypes = { */ target: PropTypes.string, /** - * title attribute for the inner a element + * Title attribute for the inner anchor element */ title: PropTypes.string }) ), /** - * Defines CSS styles which will override styles previously set. + * Additional inline CSS styles to apply to the Breadcrumb. */ style: PropTypes.object, /** - * Defines inline CSS styles that will be added to each item in the - * breadcrumbs. + * Additional inline CSS styles to apply to each item. */ item_style: PropTypes.object, /** - * Often used with CSS to style elements with common properties. + * Additional CSS classes to apply to the Breadcrumb. */ class_name: PropTypes.string, /** - * **DEPRECATED** - Use class_name instead. + * Additional CSS classes to apply to each item. + */ + item_class_name: PropTypes.string, + + /** + * A unique identifier for the component, used to improve performance by React.js + * while rendering components * - * Often used with CSS to style elements with common properties. + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info */ - className: PropTypes.string, + key: PropTypes.string, /** - * Class name to apply to each item. + * **DEPRECATED** - Use class_name instead. + * + * Additional CSS classes to apply to the Breadcrumb. */ - item_class_name: PropTypes.string, + className: PropTypes.string, /** * **DEPRECATED** - use item_class_name instead. * - * Class name ot apply to each item. + * Additional CSS classes to apply to each item. */ itemClassName: PropTypes.string, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * HTML tag to use for the outer breadcrumb component. Default: "nav". */ - key: PropTypes.string, + tag: PropTypes.object, /** - * HTML tag to use for the outer breadcrumb component. Default: "nav". + * Dash-assigned callback that gets fired when the value changes. */ - tag: PropTypes.object + setProps: PropTypes.func }; export default Breadcrumb; diff --git a/src/components/button/Button.js b/src/components/button/Button.js index 6a1cccc8..442e2c4a 100644 --- a/src/components/button/Button.js +++ b/src/components/button/Button.js @@ -16,20 +16,20 @@ import {getLoadingState} from '../../private/util'; */ function Button({ children, + n_clicks = 0, + color, + outline, disabled, href, - setProps, target, type, download, name, value, - className, class_name, - color, - outline, + className, rel, - n_clicks = 0, + setProps, ...otherProps }) { const incrementClicks = () => { @@ -68,96 +68,77 @@ function Button({ Button.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. - */ - id: PropTypes.string, - - /** - * The children of this component. + * The children of this Button. */ children: PropTypes.node, /** - * Often used with CSS to style elements with common properties. - */ - class_name: PropTypes.string, - - /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. + * The ID of the Button. */ - className: PropTypes.string, + id: PropTypes.string, /** - * Defines CSS styles which will override styles previously set. + * The number of times the Button has been clicked. */ - style: PropTypes.object, + n_clicks: PropTypes.number, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * Button color, options: primary, secondary, success, info, warning, danger, + * link. Default: primary. */ - key: PropTypes.string, + color: PropTypes.string, /** - * Pass a URL (relative or absolute) to make the menu entry a link. + * A URL to link to. If this property is set, the Button will behave like a dcc.Link + * for relative links, and like an html tag for external links. This can be + * overridden with the `external_link` property. */ href: PropTypes.string, /** - * If true, the browser will treat this as an external link, - * forcing a page refresh at the new location. If false, - * this just changes the location without triggering a page - * refresh. Use this if you are observing dcc.Location, for - * instance. Defaults to true for absolute URLs and false - * otherwise. + * If True, clicking on the Button will behave like a hyperlink. If False, the Button + * will behave like a dcc.Link component, and can be used in conjunction with + * dcc.Location for navigation within a Dash app. */ external_link: PropTypes.bool, /** - * An integer that represents the number of times - * that this element has been clicked on. + * Additional CSS classes to apply to the Component */ - n_clicks: PropTypes.number, + class_name: PropTypes.string, /** - * Whether button is in active state. Default: False. + * Additional inline CSS styles to apply to the Component. */ - active: PropTypes.bool, + style: PropTypes.object, /** - * Button color, options: primary, secondary, success, info, warning, danger, - * link. Default: primary. + * If True, the 'active' class is applied to the Button. Default: False. */ - color: PropTypes.string, + active: PropTypes.bool, /** - * Disable button (make unclickable). Default: False. + * If True, the Button will be disabled. Default: False. */ disabled: PropTypes.bool, /** - * Button size, options: 'lg', 'md', 'sm'. + * The size of the Button. Options: 'sm', 'md', 'lg'. */ size: PropTypes.string, /** - * Sets the title attribute of the underlying HTML button. + * The title of the Button. */ title: PropTypes.string, /** - * Set outline button style, which removes background images and colors for a - * lightweight style. + * If True, the outline style is applied to the Button. Default: False. */ outline: PropTypes.bool, /** - * Target attribute to pass on to link if using Button as an external link. + * The target attribute to pass on to the link. Only applies to external links. */ target: PropTypes.string, @@ -170,7 +151,8 @@ Button.propTypes = { type: PropTypes.oneOf(['button', 'reset', 'submit']), /** - * Indicates that the hyperlink is to be used for downloading a resource. + * If the Button is a link, this attribute specifies that the target will be + * downloaded. */ download: PropTypes.string, @@ -181,9 +163,8 @@ Button.propTypes = { name: PropTypes.string, /** - * Defines the value associated with the button’s name when it’s submitted - * with the form data. This value is passed to the server in params when the - * form is submitted. + * Defines the value associated with the button’s name when it’s submitted with the + * form data. This value is passed to the server in params when the form is submitted. */ value: PropTypes.string, @@ -192,6 +173,24 @@ Button.propTypes = { */ rel: PropTypes.string, + /** + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info + */ + key: PropTypes.string, + + /** + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Component + */ + className: PropTypes.string, + + /** + * Dash-assigned callback that gets fired when the value changes. + */ setProps: PropTypes.func }; diff --git a/src/components/buttongroup/ButtonGroup.js b/src/components/buttongroup/ButtonGroup.js index b7407131..c79998d4 100644 --- a/src/components/buttongroup/ButtonGroup.js +++ b/src/components/buttongroup/ButtonGroup.js @@ -24,50 +24,54 @@ function ButtonGroup({children, class_name, className, ...otherProps}) { ButtonGroup.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. + * The children of this ButtonGroup + */ + children: PropTypes.node, + + /** + * The ID of the ButtonGroup */ id: PropTypes.string, /** - * The children of this component + * Size of button group, options: 'sm', 'md', 'lg'. */ - children: PropTypes.node, + size: PropTypes.string, /** - * Defines CSS styles which will override styles previously set. + * Group buttons vertically. */ - style: PropTypes.object, + vertical: PropTypes.bool, /** - * Often used with CSS to style elements with common properties. + * Additional inline CSS styles to apply to the ButtonGroup. */ - class_name: PropTypes.string, + style: PropTypes.object, /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. + * Additional CSS classes to apply to the ButtonGroup */ - className: PropTypes.string, + class_name: PropTypes.string, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info */ key: PropTypes.string, /** - * Group buttons vertically. + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the ButtonGroup */ - vertical: PropTypes.bool, + className: PropTypes.string, /** - * Size of button group, options: 'sm', 'md', 'lg'. + * Dash-assigned callback that gets fired when the value changes. */ - size: PropTypes.string + setProps: PropTypes.func }; export default ButtonGroup; diff --git a/src/components/card/Card.js b/src/components/card/Card.js index 746a4e56..b5d2a778 100644 --- a/src/components/card/Card.js +++ b/src/components/card/Card.js @@ -8,10 +8,9 @@ import {bootstrapColors} from '../../private/BootstrapColors'; import {getLoadingState} from '../../private/util'; /** - * Component for creating Bootstrap cards. Use in conjunction with CardBody, - * CardImg, CardLink, CardHeader and CardFooter. Can also be used in - * conjunction with CardColumns, CardDeck, CardGroup for different layout - * options. + * Component for creating Bootstrap cards. Use in conjunction with CardBody, CardImg, + * CardLink, CardHeader and CardFooter. Can also be used in conjunction with + * CardColumns, CardDeck, CardGroup for different layout options. */ function Card({ children, @@ -19,8 +18,8 @@ function Card({ inverse, outline, style, - className, class_name, + className, ...otherProps }) { const isBootstrapColor = bootstrapColors.has(color); @@ -41,64 +40,69 @@ function Card({ Card.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. + * The children of this Card + */ + children: PropTypes.node, + + /** + * The ID of the Card */ id: PropTypes.string, /** - * The children of this component + * Card color, options: primary, secondary, success, info, warning, danger, light, + * dark or any valid CSS color of your choice (e.g. a hex code, a decimal code or a + * CSS color name). + * + * Default is light. */ - children: PropTypes.node, + color: PropTypes.string, /** - * Defines CSS styles which will override styles previously set. + * Apply the `card-body` class to the card, so that there is no need to also include + * a CardBody component in the children of this Card. Default: False */ - style: PropTypes.object, + body: PropTypes.bool, /** - * Often used with CSS to style elements with common properties. + * Apply color styling to just the border of the Card. */ - class_name: PropTypes.string, + outline: PropTypes.bool, /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. + * Invert text colours for use with a darker background. */ - className: PropTypes.string, + inverse: PropTypes.bool, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * Additional inline CSS styles to apply to the Card. */ - key: PropTypes.string, + style: PropTypes.object, /** - * Card color, options: primary, secondary, success, info, warning, danger, - * light, dark or any valid CSS color of - * your choice (e.g. a hex code, a decimal code or a CSS color name). - * Default is light. + * Additional CSS classes to apply to the Card */ - color: PropTypes.string, + class_name: PropTypes.string, /** - * Apply the `card-body` class to the card, so that there is no need to also - * include a CardBody component in the children of this Card. Default: False + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info */ - body: PropTypes.bool, + key: PropTypes.string, /** - * Apply color styling to just the border of the card. + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Card */ - outline: PropTypes.bool, + className: PropTypes.string, /** - * Invert text colours for use with a darker background. + * Dash-assigned callback that gets fired when the value changes. */ - inverse: PropTypes.bool + setProps: PropTypes.func }; export default Card; diff --git a/src/components/card/CardBody.js b/src/components/card/CardBody.js index d5077687..e83b9288 100644 --- a/src/components/card/CardBody.js +++ b/src/components/card/CardBody.js @@ -7,10 +7,9 @@ import RBCard from 'react-bootstrap/Card'; import {getLoadingState} from '../../private/util'; /** - * Wrap the content of your `Card` in `CardBody` to apply padding and other - * styles. + * Wrap the content of your `Card` in `CardBody` to apply padding and other styles. */ -function CardBody({children, className, class_name, ...otherProps}) { +function CardBody({children, class_name, className, ...otherProps}) { return ( {children} @@ -31,73 +33,76 @@ function CardImg({ CardImg.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. + * The children of the CardImg + */ + children: PropTypes.node, + + /** + * The ID of the CardImg */ id: PropTypes.string, /** - * The children of this component + * The URI of the embeddable content. */ - children: PropTypes.node, + src: PropTypes.string, /** - * Defines CSS styles which will override styles previously set. + * Additional inline CSS styles to apply to the CardImg. */ style: PropTypes.object, /** - * Often used with CSS to style elements with common properties. + * Additional CSS classes to apply to the CardImg */ class_name: PropTypes.string, /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. + * HTML tag to use for the CardImg, default: img */ - className: PropTypes.string, + tag: PropTypes.string, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * If True the card-img-top class will be applied which rounds the top corners of the + * image to match the corners of the card. */ - key: PropTypes.string, + top: PropTypes.bool, /** - * HTML tag to use for the card body, default: div + * If True the card-img-bottom class will be applied which rounds the bottom corners + * of the image to match the corners of the card. */ - tag: PropTypes.string, + bottom: PropTypes.bool, /** - * Set to True if image is at top of card. This will apply the card-img-top - * class which rounds the top corners to match the corners of the card. + * Alternative text in case an image can't be displayed. */ - top: PropTypes.bool, + alt: PropTypes.string, /** - * Set to True if image is at bottom of card. This will apply the - * card-img-bottom class which rounds the bottom corners to match the corners - * of the card. + * Text to be displayed as a tooltip when hovering */ - bottom: PropTypes.bool, + title: PropTypes.string, /** - * The URI of the embeddable content. + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info */ - src: PropTypes.string, + key: PropTypes.string, /** - * Alternative text in case an image can't be displayed. + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the CardImg */ - alt: PropTypes.string, + className: PropTypes.string, /** - * Text to be displayed as a tooltip when hovering + * Dash-assigned callback that gets fired when the value changes. */ - title: PropTypes.string + setProps: PropTypes.func }; export default CardImg; diff --git a/src/components/card/CardImgOverlay.js b/src/components/card/CardImgOverlay.js index 5ce9a103..ecbf1ae2 100644 --- a/src/components/card/CardImgOverlay.js +++ b/src/components/card/CardImgOverlay.js @@ -7,10 +7,10 @@ import RBCard from 'react-bootstrap/Card'; import {getLoadingState} from '../../private/util'; /** - * Use CardImgOverlay to turn an image into the background of your card and add - * text on top of it. + * Use CardImgOverlay to turn an image into the background of your card and add text on + * top of it. */ -function CardImgOverlay({children, className, class_name, ...otherProps}) { +function CardImgOverlay({children, class_name, className, ...otherProps}) { return ( { - // note - the default 'd-block w-100' is from the examples in the Bootstrap docs. - item.imgClassName = - typeof item.imgClassName !== 'undefined' - ? item.imgClassName - : 'd-block w-100'; - const useLink = item.href && true; const additionalProps = useLink ? { @@ -47,7 +41,10 @@ function Carousel({ > {item.alt} @@ -88,39 +85,15 @@ Carousel.dashPersistence = { Carousel.propTypes = { /** - * The ID of the component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. + * The ID of the Carousel. */ id: PropTypes.string, /** - * Defines CSS styles of the carousel container. Will override styles previously set. - */ - style: PropTypes.object, - - /** - * Defines the className of the carousel container. Often used with CSS to style elements with common properties. - */ - class_name: PropTypes.string, - - /** - * **DEPRECATED** Use `class_name` instead. - * - * efines the className of the carousel container. Often used with CSS to style elements with common properties. - */ - className: PropTypes.string, - - /** - * The items to display on the slides in the carousel + * The items to display on the slides in the Carousel. */ items: PropTypes.arrayOf( PropTypes.exact({ - /** - * A unique identifier for the slide, used to improve performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info. - */ - key: PropTypes.string, /** * The URL of the image */ @@ -130,57 +103,61 @@ Carousel.propTypes = { */ alt: PropTypes.string, /** - * The className for the image. The default is 'd-block w-100' + * The header of the text on the slide. It is displayed in a
element */ - img_class_name: PropTypes.string, + header: PropTypes.string, /** - * **DEPRECATED** Use `img_class_name` instead. - * - * The className for the image. The default is 'd-block w-100' + * A caption for the item. */ - imgClassName: PropTypes.string, + caption: PropTypes.string, /** - * The style for the image + * Additional inline CSS styles for the image */ img_style: PropTypes.object, /** - * The header of the text on the slide. It is displayed in a
element - */ - header: PropTypes.string, - /** - * The caption of the item. The text is displayed in a

element + * The className for the image. The default is 'd-block w-100' */ - caption: PropTypes.string, + img_class_name: PropTypes.string, /** * The class name for the header and caption container */ caption_class_name: PropTypes.string, /** - * **DEPRECATED** Use `caption_class_name` instead. - * - * The class name for the header and caption container - */ - captionClassName: PropTypes.string, - /** - * Optional hyperlink to add to the item. Item will be rendered as a - * HTML or as a Dash-style link depending on whether the link is - * deemed to be internal or external. Override this automatic detection - * with the external_link argument. + * Optional hyperlink to add to the item. Item will be rendered as a HTML or + * as a Dash-style link depending on whether the link is deemed to be internal or + * external. Override this automatic detection with the external_link argument. */ href: PropTypes.string, /** - * Optional target attribute for the link. Only applies if `href` is set, default `_self`. + * Optional target attribute for the link. Only applies if `href` is set, default + * `_self`. */ target: PropTypes.string, /** - * If true, the browser will treat this as an external link, - * forcing a page refresh at the new location. If false, - * this just changes the location without triggering a page - * refresh. Use this if you are observing dcc.Location, for - * instance. Defaults to true for absolute URLs and false - * otherwise. + * If True, clicking on the item will behave like a hyperlink. If False, the item + * will behave like a dcc.Link component, and can be used in conjunction with + * dcc.Location for navigation within a Dash app. + */ + external_link: PropTypes.bool, + /** + * A unique identifier for the slide, used to improve performance by React.js + * while rendering components. + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info. + */ + key: PropTypes.string, + /** + * **DEPRECATED** Use `img_class_name` instead. + * + * The className for the image. The default is 'd-block w-100' */ - external_link: PropTypes.bool + imgClassName: PropTypes.string, + /** + * **DEPRECATED** Use `caption_class_name` instead. + * + * The class name for the header and caption container + */ + captionClassName: PropTypes.string }) ).isRequired, @@ -189,6 +166,12 @@ Carousel.propTypes = { */ active_index: PropTypes.number, + /** + * The interval at which the Carousel automatically cycles through the slides. If + * None, the Carousel will not automatically cycle. + */ + interval: PropTypes.number, + /** * Show the Carousel previous and next arrows for changing the current slide */ @@ -200,34 +183,28 @@ Carousel.propTypes = { indicators: PropTypes.bool, /** - * Autoplays the carousel after the user manually cycles the first item. If "carousel", autoplays the carousel on load. + * Defines CSS styles of the carousel container. Will override styles previously set. */ - ride: PropTypes.oneOf(['carousel']), + style: PropTypes.object, /** - * controls whether the slide animation on the Carousel works or not + * Defines the className of the carousel container. Additional CSS classes to apply to the Component */ - slide: PropTypes.bool, + class_name: PropTypes.string, /** - * Add `variant="dark"` to the Carousel for darker controls, indicators, and - * captions. + * Enables animation on the Carousel as it transitions between slides. */ - variant: PropTypes.oneOf(['dark']), + slide: PropTypes.bool, /** - *the interval at which the carousel automatically cycles (default: 5000) - * If set to None, carousel will not Autoplay (i.e. will not automatically cycle). + * Add `variant="dark"` to the Carousel for darker controls, indicators, and captions. */ - interval: PropTypes.number, + variant: PropTypes.oneOf(['dark']), /** - * Used to allow user interactions in this component to be persisted when - * the component - or the page - is refreshed. If `persisted` is truthy and - * hasn't changed from its previous value, a `value` that the user has - * changed while using the app will keep that change, as long as - * the new `value` also matches what was given originally. - * Used in conjunction with `persistence_type`. + * Used to allow user interactions to be persisted when the page is refreshed. + * See https://dash.plotly.com/persistence for more details */ persistence: PropTypes.oneOfType([ PropTypes.bool, @@ -244,12 +221,19 @@ Carousel.propTypes = { /** * Where persisted user changes will be stored: - * memory: only kept in memory, reset on page refresh. - * local: window.localStorage, data is kept after the browser quit. - * session: window.sessionStorage, data is cleared once the browser quit. + * - memory: only kept in memory, reset on page refresh. + * - local: window.localStorage, data is kept after the browser quit. + * - session: window.sessionStorage, data is cleared once the browser quit. */ persistence_type: PropTypes.oneOf(['local', 'session', 'memory']), + /** + * **DEPRECATED** Use `class_name` instead. + * + * efines the className of the carousel container. Additional CSS classes to apply to the Component + */ + className: PropTypes.string, + /** * Dash-assigned callback that gets fired when the value changes. */ diff --git a/src/components/collapse/Collapse.js b/src/components/collapse/Collapse.js index b8561d35..4cad44e9 100644 --- a/src/components/collapse/Collapse.js +++ b/src/components/collapse/Collapse.js @@ -42,61 +42,65 @@ const Collapse = React.forwardRef(function Collapse( Collapse.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. + * The children of the Collapse.. + */ + children: PropTypes.node, + + /** + * The ID of the Collapse. */ id: PropTypes.string, /** - * The children of this component. + * Whether collapse is currently open. */ - children: PropTypes.node, + is_open: PropTypes.bool, /** - * Defines CSS styles which will override styles previously set. + * The dimension used when collapsing e.g. height will collapse vertically, + * whilst width will collapse horizontally */ - style: PropTypes.object, + dimension: PropTypes.oneOf(['height', 'width']), /** - * Often used with CSS to style elements with common properties. + * Set to True when using a collapse inside a navbar. */ - class_name: PropTypes.string, + navbar: PropTypes.bool, /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. + * Additional inline CSS styles to apply to the Component. */ - className: PropTypes.string, + style: PropTypes.object, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * Additional CSS classes to apply to the Component */ - key: PropTypes.string, + class_name: PropTypes.string, /** - * Whether collapse is currently open. + * The HTML tag used for the collapse component. */ - is_open: PropTypes.bool, + tag: PropTypes.string, /** - * Set to True when using a collapse inside a navbar. + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info */ - navbar: PropTypes.bool, + key: PropTypes.string, /** - * The dimension used when collapsing e.g. height will collapse vertically, - * whilst width will collapse horizontally + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Component */ - dimension: PropTypes.oneOf(['height', 'width']), + className: PropTypes.string, /** - * The HTML tag used for the collapse component. + * Dash-assigned callback that gets fired when the value changes. */ - tag: PropTypes.string + setProps: PropTypes.func }; export default Collapse; diff --git a/src/components/dropdownmenu/DropdownMenu.js b/src/components/dropdownmenu/DropdownMenu.js index 28ed2d36..e0ae3a26 100644 --- a/src/components/dropdownmenu/DropdownMenu.js +++ b/src/components/dropdownmenu/DropdownMenu.js @@ -17,23 +17,22 @@ import {getLoadingState} from '../../private/util'; */ function DropdownMenu({ children, - nav, label, - in_navbar, + color, + direction, size, - right, + disabled = false, + class_name, align_end, - direction, - color, + in_navbar, + nav, + caret = true, + menu_variant = 'light', group, toggle_style, - toggleClassName, toggle_class_name, className, - class_name, - caret = true, - disabled = false, - menu_variant = 'light', + toggleClassName, ...otherProps }) { const [dropdownOpen, setDropdownOpen] = useState(false); @@ -57,19 +56,13 @@ function DropdownMenu({ disabled={disabled} navbar={in_navbar} className={class_name || className} - drop={ - direction === 'left' - ? 'start' - : direction === 'right' - ? 'end' - : direction - } + drop={direction} onToggle={(show, event) => { if (!event || event.source !== 'select') { setDropdownOpen(show); } }} - align={align_end ? 'end' : right ? 'end' : 'start'} + align={align_end ? 'end' : 'start'} {...omit(['setProps'], otherProps)} data-dash-is-loading={getLoadingState() || undefined} > @@ -102,83 +95,68 @@ function DropdownMenu({ DropdownMenu.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. + * The children of the DropdownMenu. */ - id: PropTypes.string, + children: PropTypes.node, /** - * The children of this component. + * The ID of the DropdownMenu. */ - children: PropTypes.node, + id: PropTypes.string, /** - * Defines CSS styles which will override styles previously set. + * Label for the DropdownMenu toggle. */ - style: PropTypes.object, + label: PropTypes.node, /** - * Often used with CSS to style elements with common properties. + * Set the color of the DropdownMenu toggle. Available options are: 'primary', + * 'secondary', 'success', 'warning', 'danger', 'info', 'link' or any valid CSS color + * of your choice (e.g. a hex code, a decimal code or a CSS color name). + * + * Default: 'primary' */ - class_name: PropTypes.string, + color: PropTypes.string, /** - * **DEPRECATED** Use `class_name` instead. + * Direction in which to expand the DropdownMenu. Options are 'down', 'start', 'up' + * and 'end'. * - * Often used with CSS to style elements with common properties. + * Default: 'down'. */ - className: PropTypes.string, + direction: PropTypes.oneOf(['down', 'start', 'up', 'end']), /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * Size of the DropdownMenu. 'sm' corresponds to small, 'md' to medium and 'lg' to + * large. */ - key: PropTypes.string, + size: PropTypes.oneOf(['sm', 'md', 'lg']), /** - * Label for the DropdownMenu toggle. + * Disable the dropdown. */ - label: PropTypes.node, + disabled: PropTypes.bool, /** - * Direction in which to expand the DropdownMenu. Default: 'down'. `left` - * and `right` have been deprecated, and `start` and `end` should be used - * instead. + * Additional inline CSS styles to apply to the DropdownMenu. */ - direction: PropTypes.oneOf([ - 'down', - 'start', - 'end', - 'up', - 'left', - 'right', - 'end' - ]), + style: PropTypes.object, /** - * Align the DropdownMenu along the right side of its parent. Default: False. + * Additional CSS classes to apply to the DropdownMenu */ - align_end: PropTypes.bool, + class_name: PropTypes.string, /** - * **DEPRECATED** Use `align_end` instead. - * * Align the DropdownMenu along the right side of its parent. Default: False. */ - right: PropTypes.bool, + align_end: PropTypes.bool, /** * Set this to True if the DropdownMenu is inside a navbar. Default: False. */ in_navbar: PropTypes.bool, - /** - * Disable the dropdown. - */ - disabled: PropTypes.bool, - /** * Set this to True if the DropdownMenu is inside a nav for styling consistent * with other nav items. Default: False. @@ -191,48 +169,52 @@ DropdownMenu.propTypes = { caret: PropTypes.bool, /** - * Set the color of the DropdownMenu toggle. Available options are: 'primary', - * 'secondary', 'success', 'warning', 'danger', 'info', 'link' or any valid CSS - * color of your choice (e.g. a hex code, a decimal code or a CSS color name) - * Default: 'primary' + * Set `menu_variant="dark"` to create a dark-mode drop down instead. */ - color: PropTypes.string, + menu_variant: PropTypes.oneOf(['light', 'dark']), /** - * Set `menu_variant="dark"` to create a dark-mode drop down instead + * Set group to True if the DropdownMenu is inside a ButtonGroup. */ - menu_variant: PropTypes.oneOf(['light', 'dark']), + group: PropTypes.bool, /** - * Defines CSS styles which will override styles previously set. The styles - * set here apply to the DropdownMenu toggle. + * Additional inline CSS styles to apply to the DropdownMenu toggle. */ toggle_style: PropTypes.object, /** - * Often used with CSS to style elements with common properties. The classes - * specified with this prop will be applied to the DropdownMenu toggle. + * Additional CSS classes to apply to the DropdownMenu. */ toggle_class_name: PropTypes.string, /** - * **DEPRECATED** Use `toggle_class_name` instead. + * A unique identifier for the component, used to improve performance by React.js + * while rendering components * - * Often used with CSS to style elements with common properties. The classes - * specified with this prop will be applied to the DropdownMenu toggle. + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info */ - toggleClassName: PropTypes.string, + key: PropTypes.string, /** - * Size of the DropdownMenu. 'sm' corresponds to small, 'md' to medium - * and 'lg' to large. + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the DropdownMenu */ - size: PropTypes.oneOf(['sm', 'md', 'lg']), + className: PropTypes.string, /** - * Set group to True if the DropdownMenu is inside a ButtonGroup. + * **DEPRECATED** Use `toggle_class_name` instead. + * + * Additional CSS classes to apply to the DropdownMenu The classes + * specified with this prop will be applied to the DropdownMenu toggle. + */ + toggleClassName: PropTypes.string, + + /** + * Dash-assigned callback that gets fired when the value changes. */ - group: PropTypes.bool + setProps: PropTypes.func }; export default DropdownMenu; diff --git a/src/components/dropdownmenu/DropdownMenuItem.js b/src/components/dropdownmenu/DropdownMenuItem.js index 66b2b571..39e313db 100644 --- a/src/components/dropdownmenu/DropdownMenuItem.js +++ b/src/components/dropdownmenu/DropdownMenuItem.js @@ -14,14 +14,14 @@ import {getLoadingState} from '../../private/util'; function DropdownMenuItem({ children, href, - target, - disabled, - className, + n_clicks = 0, class_name, + disabled, header, divider, - n_clicks = 0, toggle = true, + target, + className, setProps, ...otherProps }) { @@ -62,40 +62,41 @@ function DropdownMenuItem({ DropdownMenuItem.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. + * The children of this DropdownMenuItem. + */ + children: PropTypes.node, + + /** + * The ID of the DropdownMenuItem. */ id: PropTypes.string, /** - * The children of this component. + * A URL to link to, if the DropdownMenuItem is clicked. */ - children: PropTypes.node, + href: PropTypes.string, /** - * Defines CSS styles which will override styles previously set. + * If True, clicking on the DropdownMenuItem will behave like a hyperlink. If False, + * the DropdownMenuItem will behave like a dcc.Link component, and can be used in + * conjunction with dcc.Location for navigation within a Dash app. */ - style: PropTypes.object, + external_link: PropTypes.bool, /** - * Often used with CSS to style elements with common properties. + * The number of times the DropdownMenuItem has been clicked. */ - class_name: PropTypes.string, + n_clicks: PropTypes.number, /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. + * Additional inline CSS styles to apply to the DropdownMenuItem. */ - className: PropTypes.string, + style: PropTypes.object, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * Additional CSS classes to apply to the DropdownMenuItem */ - key: PropTypes.string, + class_name: PropTypes.string, /** * Style this item as 'active'. @@ -119,36 +120,30 @@ DropdownMenuItem.propTypes = { */ header: PropTypes.bool, - /** - * Pass a URL (relative or absolute) to make the menu entry a link. - */ - href: PropTypes.string, - /** * Whether to toggle the DropdownMenu on click. Default: True. */ toggle: PropTypes.bool, /** - * If true, the browser will treat this as an external link, - * forcing a page refresh at the new location. If false, - * this just changes the location without triggering a page - * refresh. Use this if you are observing dcc.Location, for - * instance. Defaults to true for absolute URLs and false - * otherwise. + * Target attribute to pass on to the link. Only applies to external links. */ - external_link: PropTypes.bool, + target: PropTypes.string, /** - * An integer that represents the number of times - * that this element has been clicked on. + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info */ - n_clicks: PropTypes.number, + key: PropTypes.string, /** - * Target attribute to pass on to the link. Only applies to external links. + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the DropdownMenuItem */ - target: PropTypes.string, + className: PropTypes.string, /** * Dash-assigned callback that gets fired when the value changes. diff --git a/src/components/fade/Fade.js b/src/components/fade/Fade.js index f1825c1a..990c2a88 100644 --- a/src/components/fade/Fade.js +++ b/src/components/fade/Fade.js @@ -11,7 +11,7 @@ import {getLoadingState} from '../../private/util'; * controlled by the `is_open` prop which can be targetted by callbacks. */ const Fade = React.forwardRef(function Fade( - {children, is_in, style, className, class_name, tag, ...otherProps}, + {children, is_in, style, class_name, tag, className, ...otherProps}, ref ) { // set visibility to hidden after transition has completed to hide tooltips @@ -35,46 +35,30 @@ const Fade = React.forwardRef(function Fade( Fade.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. - */ - id: PropTypes.string, - - /** - * The children of this component + * The children of the Fade */ children: PropTypes.node, /** - * Defines CSS styles which will override styles previously set. + * The ID of the Fade */ - style: PropTypes.object, - - /** - * Often used with CSS to style elements with common properties. - */ - class_name: PropTypes.string, + id: PropTypes.string, /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. + * Controls whether the children of the Fade component are currently visible + * or not. */ - className: PropTypes.string, + is_in: PropTypes.bool, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * Additional inline CSS styles to apply to the Fade. */ - key: PropTypes.string, + style: PropTypes.object, /** - * Controls whether the children of the Fade component are currently visible - * or not. + * Additional CSS classes to apply to the Fade */ - is_in: PropTypes.bool, + class_name: PropTypes.string, /** * The duration of the transition, in milliseconds. @@ -106,7 +90,27 @@ Fade.propTypes = { /** * HTML tag to use for the fade component. Default: div. */ - tag: PropTypes.string + tag: PropTypes.string, + + /** + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info + */ + key: PropTypes.string, + + /** + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Fade + */ + className: PropTypes.string, + + /** + * Dash-assigned callback that gets fired when the value changes. + */ + setProps: PropTypes.func }; export default Fade; diff --git a/src/components/form/Form.js b/src/components/form/Form.js index 5835b4ec..3084ad0f 100644 --- a/src/components/form/Form.js +++ b/src/components/form/Form.js @@ -11,10 +11,10 @@ import {getLoadingState} from '../../private/util'; */ function Form({ children, - className, - class_name, - prevent_default_on_submit = true, n_submit = 0, + prevent_default_on_submit = true, + class_name, + className, setProps, ...otherProps }) { @@ -39,40 +39,29 @@ function Form({ Form.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. - */ - id: PropTypes.string, - - /** - * The children of this component + * The children of this Form */ children: PropTypes.node, /** - * Defines CSS styles which will override styles previously set. + * The ID of the Form */ - style: PropTypes.object, + id: PropTypes.string, /** - * Often used with CSS to style elements with common properties. + * Number of times the form was submitted. */ - class_name: PropTypes.string, + n_submit: PropTypes.number, /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. + * Additional inline CSS styles to apply to the Form. */ - className: PropTypes.string, + style: PropTypes.object, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * Additional CSS classes to apply to the Form */ - key: PropTypes.string, + class_name: PropTypes.string, /** * The URI of a program that processes the information submitted via the form. @@ -80,22 +69,32 @@ Form.propTypes = { action: PropTypes.string, /** - * Defines which HTTP method to use when submitting the form. Can be GET - * (default) or POST. + * Defines which HTTP method to use when submitting the form. Can be GET (default) or + * POST. */ method: PropTypes.oneOf(['GET', 'POST']), /** - * Number of times the `Enter` key was pressed while the input had focus. + * The form calls preventDefault on submit events. If you want form data be posted to + * the endpoint specified by `action` on submit events, set prevent_default_on_submit + * to False. Defaults to True. */ - n_submit: PropTypes.number, + prevent_default_on_submit: PropTypes.bool, /** - * The form calls preventDefault on submit events. If you want form data to - * be posted to the endpoint specified by `action` on submit events, set - * prevent_default_on_submit to False. Defaults to True. + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info */ - prevent_default_on_submit: PropTypes.bool, + key: PropTypes.string, + + /** + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Form + */ + className: PropTypes.string, /** * Dash-assigned callback that gets fired when the input changes. diff --git a/src/components/form/FormFeedback.js b/src/components/form/FormFeedback.js index b7dbbbcf..901b1e91 100644 --- a/src/components/form/FormFeedback.js +++ b/src/components/form/FormFeedback.js @@ -7,11 +7,11 @@ import RBFormControl from 'react-bootstrap/FormControl'; import {getLoadingState} from '../../private/util'; /** - * The FormFeedback component can be used to provide feedback on input values - * in a form. Add the form feedback to your layout and set the `valid` or - * `invalid` props of the associated input to toggle visibility. + * The FormFeedback component can be used to provide feedback on input values in a form. + * Add the form feedback to your layout and set the `valid` or `invalid` props of the + * associated input to toggle visibility. */ -function FormFeedback({children, className, class_name, ...otherProps}) { +function FormFeedback({children, class_name, className, ...otherProps}) { return ( checkbox element. + * A label to display alongside the Checkbox. */ - input_style: PropTypes.object, + label: PropTypes.node, /** - * **DEPRECATED** Use `input_style` instead. - * - * The style of the checkbox element. + * Additional CSS classes to apply to the container div. */ - inputStyle: PropTypes.object, + class_name: PropTypes.string, /** - * The class of the checkbox element + * Additional inline CSS styles to apply to the container div. */ - input_class_name: PropTypes.string, + style: PropTypes.object, /** - * **DEPRECATED** Use `input_class_name` instead. - * - * The class of the checkbox element + * Additional inline CSS styles to apply to the element. */ - inputClassName: PropTypes.string, + input_style: PropTypes.object, /** - * The label of the element + * Additional CSS classes to apply to the element. */ - label: PropTypes.node, + input_class_name: PropTypes.string, /** - * The id of the label + * The ID of the label */ label_id: PropTypes.string, /** - * Inline style arguments to apply to the

element which will serve as the element's context menu. */ - readonly: PropTypes.oneOfType([ - PropTypes.bool, - PropTypes.oneOf(['readOnly', 'readonly', 'READONLY']) - ]), + contextmenu: PropTypes.string, /** - * **DEPRECATED** Use `readonly` instead - * - * Indicates whether the element can be edited. + * Defines the number of columns in a textarea. */ - readOnly: PropTypes.oneOfType([ - PropTypes.bool, - PropTypes.oneOf(['readOnly', 'readonly', 'READONLY']) - ]), + cols: PropTypes.oneOfType([PropTypes.string, PropTypes.number]), /** - * This attribute specifies that the user must fill in a value before - * submitting a form. It cannot be used when the type attribute is hidden, - * image, or a button type (submit, reset, or button). The :optional and - * :required CSS pseudo-classes will be applied to the field as appropriate. - * required is an HTML boolean attribute - it is enabled by a boolean or - * 'required'. Alternative capitalizations `REQUIRED` - * are also acccepted. + * Defines the text direction. Allowed values are ltr (Left-To-Right) or rtl (Right-To-Left) */ - required: PropTypes.oneOfType([ - PropTypes.oneOf(['required', 'REQUIRED']), - PropTypes.bool - ]), + dir: PropTypes.string, /** - * Defines the number of rows in a text area. + * Indicates whether the user can interact with the element. */ - rows: PropTypes.oneOfType([PropTypes.string, PropTypes.number]), + disabled: PropTypes.oneOfType([PropTypes.string, PropTypes.bool]), /** - * Indicates whether the text should be wrapped. + * Defines whether the element can be dragged. */ - wrap: PropTypes.string, + draggable: PropTypes.oneOfType([ + // enumerated property, not a boolean property: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable + PropTypes.oneOf(['true', 'false']), + PropTypes.bool + ]), /** - * Defines a keyboard shortcut to activate or add focus to the element. + * Indicates the form that is the owner of the element. */ - accesskey: PropTypes.string, + form: PropTypes.string, /** - * **DEPRECATED** Use `accesskey` instead - * - * Defines a keyboard shortcut to activate or add focus to the element. + * Prevents rendering of given element, while keeping child elements, e.g. script elements, active. */ - accessKey: PropTypes.string, + hidden: PropTypes.string, /** - * Often used with CSS to style elements with common properties. + * Defines the language used in the element. */ - class_name: PropTypes.string, + lang: PropTypes.string, /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. + * Defines the maximum number of characters allowed in the element. */ - className: PropTypes.string, + maxlength: PropTypes.oneOfType([PropTypes.string, PropTypes.number]), /** - * Indicates whether the element's content is editable. + * Defines the minimum number of characters allowed in the element. */ - contenteditable: PropTypes.oneOfType([PropTypes.string, PropTypes.number]), + minlength: PropTypes.oneOfType([PropTypes.string, PropTypes.number]), /** - * **DEPRECATED** Use `contenteditable` instead - * - * Indicates whether the element's content is editable. + * Name of the element. For example used by the server to identify the fields in form submits. */ - contentEditable: PropTypes.oneOfType([PropTypes.string, PropTypes.number]), + name: PropTypes.string, /** - * Defines the ID of a element which will serve as the element's context menu. + * Indicates whether the element can be edited. */ - contextmenu: PropTypes.string, + readonly: PropTypes.oneOfType([ + PropTypes.bool, + PropTypes.oneOf(['readOnly', 'readonly', 'READONLY']) + ]), /** - * **DEPRECATED** Use `contextmenu` instead - * - * Defines the ID of a element which will serve as the element's context menu. + * This attribute specifies that the user must fill in a value before + * submitting a form. It cannot be used when the type attribute is hidden, + * image, or a button type (submit, reset, or button). The :optional and + * :required CSS pseudo-classes will be applied to the field as appropriate. + * required is an HTML boolean attribute - it is enabled by a boolean or + * 'required'. Alternative capitalizations `REQUIRED` + * are also acccepted. */ - contextMenu: PropTypes.string, + required: PropTypes.oneOfType([ + PropTypes.oneOf(['required', 'REQUIRED']), + PropTypes.bool + ]), /** - * Defines the text direction. Allowed values are ltr (Left-To-Right) or rtl (Right-To-Left) + * Defines the number of rows in a text area. */ - dir: PropTypes.string, + rows: PropTypes.oneOfType([PropTypes.string, PropTypes.number]), /** - * Defines whether the element can be dragged. + * Indicates whether spell checking is allowed for the element. */ - draggable: PropTypes.oneOfType([ + spellcheck: PropTypes.oneOfType([ // enumerated property, not a boolean property: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable PropTypes.oneOf(['true', 'false']), PropTypes.bool ]), /** - * Prevents rendering of given element, while keeping child elements, e.g. script elements, active. + * Overrides the browser's default tab order and follows the one specified instead. */ - hidden: PropTypes.string, + tabindex: PropTypes.oneOfType([PropTypes.string, PropTypes.number]), /** - * Defines the language used in the element. + * Text to be displayed in a tooltip when hovering over the element. */ - lang: PropTypes.string, + title: PropTypes.string, /** - * Indicates whether spell checking is allowed for the element. + * Indicates whether the text should be wrapped. */ - spellcheck: PropTypes.oneOfType([ - // enumerated property, not a boolean property: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable - PropTypes.oneOf(['true', 'false']), - PropTypes.bool - ]), + wrap: PropTypes.string, /** - * **DEPRECATED** Use `spellcheck` instead - * - * Indicates whether spell checking is allowed for the element. + * Whether or not the form should increment the n_submit prop when enter key is + * pressed. If True, use shift + enter to create a newline. Default: True */ - spellCheck: PropTypes.oneOfType([ - // enumerated property, not a boolean property: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable - PropTypes.oneOf(['true', 'false']), - PropTypes.bool - ]), + submit_on_enter: PropTypes.bool, /** - * Defines CSS styles which will override styles previously set. + * If true, changes to input will be sent back to the Dash server only on enter or + * when losing focus. If it's false, it will sent the value back on every change. + * If debounce is a number, the value will be sent to the server only after the user + * has stopped typing for that number of milliseconds */ - style: PropTypes.object, + debounce: PropTypes.oneOfType([PropTypes.bool, PropTypes.number]), /** - * Overrides the browser's default tab order and follows the one specified instead. + * Used to allow user interactions to be persisted when the page is refreshed. + * See https://dash.plotly.com/persistence for more details */ - tabindex: PropTypes.oneOfType([PropTypes.string, PropTypes.number]), + persistence: PropTypes.oneOfType([ + PropTypes.bool, + PropTypes.string, + PropTypes.number + ]), /** - * **DEPRECATED** Use `tabindex` instead - * - * Overrides the browser's default tab order and follows the one specified instead. + * Properties whose user interactions will persist after refreshing the + * component or the page. Since only `value` is allowed this prop can + * normally be ignored. */ - tabIndex: PropTypes.oneOfType([PropTypes.string, PropTypes.number]), + persisted_props: PropTypes.arrayOf(PropTypes.oneOf(['value'])), /** - * Text to be displayed in a tooltip when hovering over the element. + * Where persisted user changes will be stored: + * - memory: only kept in memory, reset on page refresh. + * - local: window.localStorage, data is kept after the browser quit. + * - session: window.sessionStorage, data is cleared once the browser quit. */ - title: PropTypes.string, + persistence_type: PropTypes.oneOf(['local', 'session', 'memory']), /** - * Dash-assigned callback that gets fired when the value changes. + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info */ - setProps: PropTypes.func, + key: PropTypes.string, /** - * Set the size of the Textarea, valid options are 'sm', 'md', or 'lg' + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Textarea */ - size: PropTypes.string, + className: PropTypes.string, /** - * Apply valid style to the Textarea for feedback purposes. This will cause - * any FormFeedback in the enclosing div with valid=True to display. + * **DEPRECATED** Use `accesskey` instead + * + * Defines a keyboard shortcut to activate or add focus to the element. */ - valid: PropTypes.bool, + accessKey: PropTypes.string, /** - * Apply invalid style to the Textarea for feedback purposes. This will cause - * any FormFeedback in the enclosing div with valid=False to display. + * **DEPRECATED** Use `autofocus` instead + * + * The element should be automatically focused after the page loaded. */ - invalid: PropTypes.bool, + autoFocus: PropTypes.string, /** - * Number of times the input lost focus. + * **DEPRECATED** Use `contenteditable` instead + * + * Indicates whether the element's content is editable. */ - n_blur: PropTypes.number, + contentEditable: PropTypes.oneOfType([PropTypes.string, PropTypes.number]), /** - * Number of times the `Enter` key was pressed while the textarea had focus. Only - * updates if submit_on_enter is True. + * **DEPRECATED** Use `contextmenu` instead + * + * Defines the ID of a element which will serve as the element's context menu. */ - n_submit: PropTypes.number, + contextMenu: PropTypes.string, /** - * Whether or not the form should increment the n_submit prop when enter key is - * pressed. If True, use shift + enter to create a newline. Default: True + * **DEPRECATED** Use `maxlength` instead + * + * Defines the maximum number of characters allowed in the element. */ - submit_on_enter: PropTypes.bool, + maxLength: PropTypes.oneOfType([PropTypes.string, PropTypes.number]), /** - * An integer that represents the number of times - * that this element has been clicked on. + * **DEPRECATED** Use `minlength` instead + * + * Defines the minimum number of characters allowed in the element. */ - n_clicks: PropTypes.number, + minLength: PropTypes.oneOfType([PropTypes.string, PropTypes.number]), /** - * If true, changes to input will be sent back to the Dash server only on enter or - * when losing focus. If it's false, it will sent the value back on every change. - * If debounce is a number, the value will be sent to the server only after the user - * has stopped typing for that number of milliseconds + * **DEPRECATED** Use `readonly` instead + * + * Indicates whether the element can be edited. */ - debounce: PropTypes.oneOfType([PropTypes.bool, PropTypes.number]), + readOnly: PropTypes.oneOfType([ + PropTypes.bool, + PropTypes.oneOf(['readOnly', 'readonly', 'READONLY']) + ]), /** - * Used to allow user interactions in this component to be persisted when - * the component - or the page - is refreshed. If `persisted` is truthy and - * hasn't changed from its previous value, a `value` that the user has - * changed while using the app will keep that change, as long as - * the new `value` also matches what was given originally. - * Used in conjunction with `persistence_type`. + * **DEPRECATED** Use `spellcheck` instead + * + * Indicates whether spell checking is allowed for the element. */ - persistence: PropTypes.oneOfType([ - PropTypes.bool, - PropTypes.string, - PropTypes.number + spellCheck: PropTypes.oneOfType([ + // enumerated property, not a boolean property: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable + PropTypes.oneOf(['true', 'false']), + PropTypes.bool ]), /** - * Properties whose user interactions will persist after refreshing the - * component or the page. Since only `value` is allowed this prop can - * normally be ignored. + * **DEPRECATED** Use `tabindex` instead + * + * Overrides the browser's default tab order and follows the one specified instead. */ - persisted_props: PropTypes.arrayOf(PropTypes.oneOf(['value'])), + tabIndex: PropTypes.oneOfType([PropTypes.string, PropTypes.number]), /** - * Where persisted user changes will be stored: - * memory: only kept in memory, reset on page refresh. - * local: window.localStorage, data is kept after the browser quit. - * session: window.sessionStorage, data is cleared once the browser quit. + * Dash-assigned callback that gets fired when the value changes. */ - persistence_type: PropTypes.oneOf(['local', 'session', 'memory']) -}; - -Textarea.dashPersistence = { - persisted_props: ['value'], - persistence_type: 'local' + setProps: PropTypes.func }; export default Textarea; diff --git a/src/components/layout/Col.js b/src/components/layout/Col.js index caefbb55..bbc82a1e 100644 --- a/src/components/layout/Col.js +++ b/src/components/layout/Col.js @@ -5,6 +5,7 @@ import PropTypes from 'prop-types'; import {omit} from 'ramda'; import RBCol from 'react-bootstrap/Col'; +import {columnPropType} from '../../private/types'; import {getLoadingState} from '../../private/util'; const alignMap = { @@ -16,7 +17,7 @@ const alignMap = { }; /** - * Component for creating Bootstrap columns to control the layout of your page. + * Col for creating Bootstrap columns to control the layout of your page. * * Use the width argument to specify width, or use the breakpoint arguments * (xs, sm, md, lg, xl) to control the width of the columns on different screen @@ -24,6 +25,8 @@ const alignMap = { */ function Col({ children, + align, + class_name, width, xs, sm, @@ -31,9 +34,7 @@ function Col({ lg, xl, xxl, - align, className, - class_name, ...otherProps }) { [width, xs, sm, md, lg, xl, xxl].forEach(breakpoint => { @@ -62,135 +63,116 @@ function Col({ ); } -const stringOrNumberProp = PropTypes.oneOfType([ - PropTypes.number, - PropTypes.string -]); -const columnProps = PropTypes.oneOfType([ - PropTypes.string, - PropTypes.number, - PropTypes.bool, - PropTypes.shape({ - size: PropTypes.oneOfType([ - PropTypes.bool, - PropTypes.number, - PropTypes.string - ]), - // example size values: - // 12 || "12" => col-12 or col-`width`-12 - // auto => col-auto or col-`width`-auto - // true => col or col-`width` - order: stringOrNumberProp, - offset: stringOrNumberProp - }) -]); - Col.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. - */ - id: PropTypes.string, - - /** - * The children of this component + * The children of this Col */ children: PropTypes.node, /** - * Defines CSS styles which will override styles previously set. + * The ID of the Col */ - style: PropTypes.object, + id: PropTypes.string, /** - * Often used with CSS to style elements with common properties. + * Set vertical alignment of this column's content in the parent row. Options are + * 'start', 'center', 'end', 'stretch', 'baseline'. */ - class_name: PropTypes.string, + align: PropTypes.oneOf(['start', 'center', 'end', 'stretch', 'baseline']), /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. + * Additional inline CSS styles to apply to the Col. */ - className: PropTypes.string, + style: PropTypes.object, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * Additional CSS classes to apply to the Col */ - key: PropTypes.string, + class_name: PropTypes.string, /** - * Specify the width of the column. Behind the scenes this sets behaviour at - * the xs breakpoint, and will be overriden if xs is specified. + * Specify the width of the column. Behind the scenes this sets behaviour at the xs + * breakpoint, and will be overriden if xs is specified. * * Valid arguments are boolean, an integer in the range 1-12 inclusive, or a - * dictionary with keys 'offset', 'order', 'size'. See the documentation for - * more details. + * dictionary with keys 'offset', 'order', 'size'. See the documentation for more + * details. */ - width: columnProps, + width: columnPropType, /** * Specify column behaviour on an extra small screen. * * Valid arguments are boolean, an integer in the range 1-12 inclusive, or a - * dictionary with keys 'offset', 'order', 'size'. See the documentation for - * more details. + * dictionary with keys 'offset', 'order', 'size'. See the documentation for more + * details. */ - xs: columnProps, + xs: columnPropType, /** * Specify column behaviour on a small screen. * * Valid arguments are boolean, an integer in the range 1-12 inclusive, or a - * dictionary with keys 'offset', 'order', 'size'. See the documentation for - * more details. + * dictionary with keys 'offset', 'order', 'size'. See the documentation for more + * details. */ - sm: columnProps, + sm: columnPropType, /** * Specify column behaviour on a medium screen. * * Valid arguments are boolean, an integer in the range 1-12 inclusive, or a - * dictionary with keys 'offset', 'order', 'size'. See the documentation for - * more details. + * dictionary with keys 'offset', 'order', 'size'. See the documentation for more + * details. */ - md: columnProps, + md: columnPropType, /** * Specify column behaviour on a large screen. * * Valid arguments are boolean, an integer in the range 1-12 inclusive, or a - * dictionary with keys 'offset', 'order', 'size'. See the documentation for - * more details. + * dictionary with keys 'offset', 'order', 'size'. See the documentation for more + * details. */ - lg: columnProps, + lg: columnPropType, /** * Specify column behaviour on an extra large screen. * * Valid arguments are boolean, an integer in the range 1-12 inclusive, or a - * dictionary with keys 'offset', 'order', 'size'. See the documentation for - * more details. + * dictionary with keys 'offset', 'order', 'size'. See the documentation for more + * details. */ - xl: columnProps, + xl: columnPropType, /** * Specify column behaviour on an extra extra large screen. * * Valid arguments are boolean, an integer in the range 1-12 inclusive, or a - * dictionary with keys 'offset', 'order', 'size'. See the documentation for - * more details. + * dictionary with keys 'offset', 'order', 'size'. See the documentation for more + * details. + */ + xxl: columnPropType, + + /** + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info */ - xxl: columnProps, + key: PropTypes.string, + + /** + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Col + */ + className: PropTypes.string, /** - * Set vertical alignment of this column's content in the parent row. Options - * are 'start', 'center', 'end', 'stretch', 'baseline'. + * Dash-assigned callback that gets fired when the value changes. */ - align: PropTypes.oneOf(['start', 'center', 'end', 'stretch', 'baseline']) + setProps: PropTypes.func }; export default Col; diff --git a/src/components/layout/Container.js b/src/components/layout/Container.js index 8acc9503..7cbe03bd 100644 --- a/src/components/layout/Container.js +++ b/src/components/layout/Container.js @@ -7,10 +7,9 @@ import RBContainer from 'react-bootstrap/Container'; import {getLoadingState} from '../../private/util'; /** - * Containers provide a means to center and horizontally pad your site’s - * contents. + * Containers provide a means to center and horizontally pad your site’s contents. */ -function Container({children, className, class_name, tag, ...otherProps}) { +function Container({children, class_name, tag, className, ...otherProps}) { return ( { const [linkActive, setLinkActive] = useState(false); @@ -69,45 +68,23 @@ const NavLink = ({ NavLink.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. - */ - id: PropTypes.string, - - /** - * The children of this component + * The children of the NavLink. */ children: PropTypes.node, - - /** - * Defines CSS styles which will override styles previously set. - */ - style: PropTypes.object, - - /** - * Often used with CSS to style elements with common properties. - */ - class_name: PropTypes.string, - /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. + * The ID of the NavLink. */ - className: PropTypes.string, + id: PropTypes.string, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * The URL of the linked resource. */ - key: PropTypes.string, + href: PropTypes.string, /** - * The URL of the linked resource. + * The number of times the NavLink has been clicked. */ - href: PropTypes.string, + n_clicks: PropTypes.number, /** * Apply 'active' style to this component. Set to "exact" to automatically @@ -133,26 +110,42 @@ NavLink.propTypes = { disabled: PropTypes.bool, /** - * If true, the browser will treat this as an external link, - * forcing a page refresh at the new location. If false, - * this just changes the location without triggering a page - * refresh. Use this if you are observing dcc.Location, for - * instance. Defaults to true for absolute URLs and false - * otherwise. + * If True, clicking on the NavLink will behave like a hyperlink. If False, the + * NavLink will behave like a dcc.Link component, and can be used in conjunction with + * dcc.Location for navigation within a Dash app. */ external_link: PropTypes.bool, /** - * An integer that represents the number of times - * that this element has been clicked on. + * Additional inline CSS styles to apply to the NavLink. */ - n_clicks: PropTypes.number, + style: PropTypes.object, + + /** + * Additional CSS classes to apply to the NavLink. + */ + class_name: PropTypes.string, /** * Target attribute to pass on to the link. Only applies to external links. */ target: PropTypes.string, + /** + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info + */ + key: PropTypes.string, + + /** + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the NavLink. + */ + className: PropTypes.string, + /** * Dash-assigned callback that gets fired when the input changes. */ diff --git a/src/components/nav/Navbar.js b/src/components/nav/Navbar.js index f7b16d42..b336fb1c 100644 --- a/src/components/nav/Navbar.js +++ b/src/components/nav/Navbar.js @@ -12,13 +12,13 @@ import {getLoadingState} from '../../private/util'; */ function Navbar({ children, - style, - className, - class_name, dark = true, - tag, color = 'primary', expand = 'md', + style, + class_name, + tag, + className, ...otherProps }) { const isBootstrapColor = bootstrapColors.has(color); @@ -39,41 +39,15 @@ function Navbar({ } Navbar.propTypes = { - /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. - */ - id: PropTypes.string, - /** * The children of this component */ children: PropTypes.node, /** - * Defines CSS styles which will override styles previously set. - */ - style: PropTypes.object, - - /** - * Often used with CSS to style elements with common properties. - */ - class_name: PropTypes.string, - - /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. - */ - className: PropTypes.string, - - /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * The ID of the component */ - key: PropTypes.string, + id: PropTypes.string, /** * Applies the `navbar-dark` class to the Navbar, causing text in the children @@ -106,6 +80,21 @@ Navbar.propTypes = { */ color: PropTypes.string, + /** + * Specify screen size at which to expand the menu bar, e.g. sm, md, lg etc. + */ + expand: PropTypes.oneOfType([PropTypes.bool, PropTypes.string]), + + /** + * Additional inline CSS styles to apply to the Component. + */ + style: PropTypes.object, + + /** + * Additional CSS classes to apply to the Component + */ + class_name: PropTypes.string, + /** * The ARIA role attribute. */ @@ -117,9 +106,24 @@ Navbar.propTypes = { tag: PropTypes.string, /** - * Specify screen size at which to expand the menu bar, e.g. sm, md, lg etc. + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info + */ + key: PropTypes.string, + + /** + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Component + */ + className: PropTypes.string, + + /** + * Dash-assigned callback that gets fired when the input changes */ - expand: PropTypes.oneOfType([PropTypes.bool, PropTypes.string]) + setProps: PropTypes.func }; export default Navbar; diff --git a/src/components/nav/NavbarBrand.js b/src/components/nav/NavbarBrand.js index 5aa4825e..f1c51737 100644 --- a/src/components/nav/NavbarBrand.js +++ b/src/components/nav/NavbarBrand.js @@ -8,9 +8,9 @@ import Link from '../../private/Link'; import {getLoadingState} from '../../private/util'; /** - * Call out attention to a brand name or site title within a navbar. + * Call out attention to a brand name or site title within a Navbar. */ -function NavbarBrand({children, className, class_name, href, ...otherProps}) { +function NavbarBrand({children, class_name, href, className, ...otherProps}) { return ( { @@ -64,88 +64,90 @@ function Offcanvas({ Offcanvas.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. + * The children of the Offcanvas. + */ + children: PropTypes.node, + + /** + * The ID of the Offcanvas. */ id: PropTypes.string, /** - * The children of this component + * Whether offcanvas is currently open. */ - children: PropTypes.node, + is_open: PropTypes.bool, /** - * Defines CSS styles which will override styles previously set. + * The header title */ - style: PropTypes.object, + title: PropTypes.node, /** - * Often used with CSS to style elements with common properties. + * Which side of the viewport the offcanvas will appear from. */ - class_name: PropTypes.string, + placement: PropTypes.oneOf(['start', 'end', 'top', 'bottom']), /** - * **DEPRECATED** - Use class_name instead. - * - * Often used with CSS to style elements with common properties. + * Includes an offcanvas-backdrop element. Alternatively, specify 'static' for a + * backdrop which doesn't close the modal on click. */ - className: PropTypes.string, + backdrop: PropTypes.oneOfType([PropTypes.bool, PropTypes.oneOf(['static'])]), /** - * The ARIA labelledby attribute + * Specify whether the Offcanvas should contain a close button + * in the header */ - labelledby: PropTypes.string, + close_button: PropTypes.bool, /** - * **DEPRECATED** Use `labelledby` instead - * - * The ARIA labelledby attribute + * If True, the offcanvas will close when the escape key is pressed. */ - labelledBy: PropTypes.string, + keyboard: PropTypes.bool, /** - * Includes an offcanvas-backdrop element. Alternatively, specify 'static' for a - * backdrop which doesn't close the modal on click. + * Allow body scrolling while offcanvas is open. */ - backdrop: PropTypes.oneOfType([PropTypes.bool, PropTypes.oneOf(['static'])]), + scrollable: PropTypes.bool, /** - * CSS class to apply to the backdrop. + * Additional inline CSS styles to apply to the Offcanvas. */ - backdrop_class_name: PropTypes.string, + style: PropTypes.object, /** - * **DEPRECATED** - Use backdrop_class_name instead. - * - * CSS class to apply to the backdrop. + * Additional CSS classes to apply to the Offcanvas */ - backdropClassName: PropTypes.string, + class_name: PropTypes.string, /** - * Close the offcanvas when escape key is pressed. + * CSS class to apply to the backdrop. */ - keyboard: PropTypes.bool, + backdrop_class_name: PropTypes.string, /** - * Whether offcanvas is currently open. + * Puts the focus on the offcanvas when initialized. */ - is_open: PropTypes.bool, + autofocus: PropTypes.bool, /** - * Which side of the viewport the offcanvas will appear from. + * The ARIA labelledby attribute */ - placement: PropTypes.oneOf(['start', 'end', 'top', 'bottom']), + labelledby: PropTypes.string, /** - * Allow body scrolling while offcanvas is open. + * **DEPRECATED** - Use class_name instead. + * + * Additional CSS classes to apply to the Offcanvas */ - scrollable: PropTypes.bool, + className: PropTypes.string, /** - * Puts the focus on the offcanvas when initialized. + * **DEPRECATED** - Use backdrop_class_name instead. + * + * CSS class to apply to the backdrop. */ - autofocus: PropTypes.bool, + backdropClassName: PropTypes.string, /** * **DEPRECATED** Use `autofocus` instead @@ -155,15 +157,11 @@ Offcanvas.propTypes = { autoFocus: PropTypes.bool, /** - * The header title - */ - title: PropTypes.node, - - /** - * Specify whether the Component should contain a close button - * in the header + * **DEPRECATED** Use `labelledby` instead + * + * The ARIA labelledby attribute */ - close_button: PropTypes.bool, + labelledBy: PropTypes.string, /** * Dash-assigned callback that gets fired when the value changes. diff --git a/src/components/pagination/Pagination.js b/src/components/pagination/Pagination.js index 5920e1e1..be653541 100644 --- a/src/components/pagination/Pagination.js +++ b/src/components/pagination/Pagination.js @@ -11,16 +11,16 @@ import {getLoadingState} from '../../private/util'; * component. */ function Pagination({ - setProps, class_name, - className, + active_page = 1, min_value = 1, + max_value, step = 1, - active_page = 1, fully_expanded = true, previous_next = false, first_last = false, - max_value, + className, + setProps, ...otherProps }) { // Check max_value is correct value re. step size and if not, change it @@ -29,7 +29,7 @@ function Pagination({ max_value = max_value + step - ((max_value - min_value) % step); } - // Functiont o set the active page + // Function to set the active page const setActivePage = value => { if (setProps) { setProps({active_page: value}); @@ -151,33 +151,14 @@ function Pagination({ Pagination.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. + * The ID of the Pagination */ id: PropTypes.string, /** - * Often used with CSS to style elements with common properties. - */ - class_name: PropTypes.string, - - /** - * **DEPRECATED** - Use class_name instead. - * - * Often used with CSS to style elements with common properties. - */ - className: PropTypes.string, - - /** - * Defines CSS styles which will override styles previously set. - */ - style: PropTypes.object, - - /** - * Set the size of all page items in the pagination. + * The currently active page */ - size: PropTypes.oneOf(['sm', 'lg']), + active_page: PropTypes.number, /** * Minimum (leftmost) value to appear in the pagination. @@ -197,28 +178,44 @@ Pagination.propTypes = { step: PropTypes.number, /** - * The currently active page + * Set the size of all page items in the Pagination. */ - active_page: PropTypes.number, + size: PropTypes.oneOf(['sm', 'lg']), /** - * When True, this will display all numbers between `min_value` and - * `max_value`. + * When True, this will display all numbers between `min_value` and `max_value`. */ fully_expanded: PropTypes.bool, /** - * When True, this will display a previous and next icon before and after - * the individual page numbers. + * When True, this will display a previous and next icon before and after the + * individual page numbers. */ previous_next: PropTypes.bool, /** - * When True, this will display a first and last icon at the beginning - * and end of the component. + * When True, this will display a first and last icon at the beginning and end of the + * Pagination. */ first_last: PropTypes.bool, + /** + * Additional inline CSS styles to apply to the Pagination.. + */ + style: PropTypes.object, + + /** + * Additional CSS classes to apply to the Pagination. + */ + class_name: PropTypes.string, + + /** + * **DEPRECATED** - Use class_name instead. + * + * Additional CSS classes to apply to the Pagination. + */ + className: PropTypes.string, + /** * Dash-assigned callback that gets fired when the input changes. */ diff --git a/src/components/placeholder/Placeholder.js b/src/components/placeholder/Placeholder.js index 3fb2acc1..beca351e 100644 --- a/src/components/placeholder/Placeholder.js +++ b/src/components/placeholder/Placeholder.js @@ -154,43 +154,17 @@ function Placeholder({ Placeholder.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. - */ - id: PropTypes.string, - - /** - * The children of this component. + * The children of the Placeholder. */ children: PropTypes.node, /** - * Defines CSS styles which will override styles previously set. + * The ID of the Placeholder. */ - style: PropTypes.object, - - /** - * Often used with CSS to style elements with common properties. - */ - class_name: PropTypes.string, - - /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. - */ - className: PropTypes.string, - - /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info - */ - key: PropTypes.string, + id: PropTypes.string, /** - * Changes the animation of the placeholder. + * Changes the animation of the Placeholder. */ animation: PropTypes.oneOf(['glow', 'wave']), @@ -201,7 +175,7 @@ Placeholder.propTypes = { color: PropTypes.string, /** - * Component size variations. Only valid when `button=false`. + * Placeholder size variations. Only valid when `button=false`. */ size: PropTypes.oneOf(['xs', 'sm', 'lg']), @@ -228,6 +202,16 @@ Placeholder.propTypes = { */ show_initially: PropTypes.bool, + /** + * Additional inline CSS styles to apply to the Placeholder. + */ + style: PropTypes.object, + + /** + * Additional CSS classes to apply to the Placeholder + */ + class_name: PropTypes.string, + /** * Specify placeholder behaviour on an extra small screen. * @@ -277,8 +261,8 @@ Placeholder.propTypes = { xxl: PropTypes.number, /** - * Specify component and prop to trigger showing the placeholder - * example: `{"output-container": "children", "grid": ["rowData", "columnDefs]}` + * Specify component and prop to trigger showing the placeholder. Example: + * `{"output-container": "children", "grid": ["rowData", "columnDefs]}` * */ target_components: PropTypes.objectOf( @@ -286,9 +270,30 @@ Placeholder.propTypes = { ), /** - * Setting display to "show" or "hide" will override the loading state coming from dash-renderer + * Setting display to "show" or "hide" will override the loading state coming from + * dash-renderer + */ + display: PropTypes.oneOf(['auto', 'show', 'hide']), + + /** + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info + */ + key: PropTypes.string, + + /** + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Placeholder + */ + className: PropTypes.string, + + /** + * Dash-assigned callback that gets fired when the value changes. */ - display: PropTypes.oneOf(['auto', 'show', 'hide']) + setProps: PropTypes.func }; export default Placeholder; diff --git a/src/components/popover/Popover.js b/src/components/popover/Popover.js index 77a2d893..16062324 100644 --- a/src/components/popover/Popover.js +++ b/src/components/popover/Popover.js @@ -9,27 +9,27 @@ import {getLoadingState} from '../../private/util'; /** * Popover creates a toggleable overlay that can be used to provide additional - * information or content to users without having to load a new page or open a - * new window. + * information or content to users without having to load a new page or open a new + * window. * - * Use the `PopoverHeader` and `PopoverBody` components to control the layout - * of the children. + * Use the `PopoverHeader` and `PopoverBody` components to control the layout of the + * children. */ function Popover({ children, - is_open, - className, - class_name, - style, id, + is_open, + placement = 'right', hide_arrow, - offset, - body, delay = {show: 0, hide: 50}, - placement = 'right', + offset, flip = true, + body, autohide = false, + style, + class_name, + className, ...otherProps }) { // Calcualte the offset to pass to the popperconfig @@ -65,7 +65,7 @@ function Popover({ > @@ -27,41 +27,25 @@ function Table(props) { Table.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. + * The children of this Table */ - id: PropTypes.string, + children: PropTypes.node, /** - * The children of this component + * The ID of the Table */ - children: PropTypes.node, + id: PropTypes.string, /** - * Defines CSS styles which will override styles previously set. + * Additional inline CSS styles to apply to the Table. */ style: PropTypes.object, /** - * Often used with CSS to style elements with common properties. + * Additional CSS classes to apply to the Table. */ class_name: PropTypes.string, - /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. - */ - className: PropTypes.string, - - /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info - */ - key: PropTypes.string, - /** * Specify table size, options: 'sm', 'md', 'lg' */ @@ -91,13 +75,6 @@ Table.propTypes = { */ color: PropTypes.string, - /** - * **DEPRECATED** - Use color="dark" instead. - * - * Apply the `table-dark` class for dark cell backgrounds and light text. - */ - dark: PropTypes.bool, - /** * Apply the `table-hover` class which enables a hover state on table rows * within the table body. @@ -108,7 +85,27 @@ Table.propTypes = { * Set to True or one of the breakpoints 'sm', 'md', 'lg', 'xl' to make table * scroll horizontally at lower breakpoints. */ - responsive: PropTypes.oneOfType([PropTypes.bool, PropTypes.string]) + responsive: PropTypes.oneOfType([PropTypes.bool, PropTypes.string]), + + /** + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info + */ + key: PropTypes.string, + + /** + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Table. + */ + className: PropTypes.string, + + /** + * Dash-assigned callback that gets fired when the value changes. + */ + setProps: PropTypes.func }; export default Table; diff --git a/src/components/tabs/Tab.js b/src/components/tabs/Tab.js index 54924d39..44c25c4d 100644 --- a/src/components/tabs/Tab.js +++ b/src/components/tabs/Tab.js @@ -11,16 +11,32 @@ function Tab(props) { Tab.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. + * The children of this Tab. + */ + children: PropTypes.node, + + /** + * The ID of the Tab. */ id: PropTypes.string, /** - * The children of this component + * The tab's label, displayed in the tab itself. */ - children: PropTypes.node, + label: PropTypes.string, + + /** + * Optional identifier for tab used for determining which tab is visible + * if not specified, and Tab is being used inside Tabs component, the tabId + * will be set to "tab-i" where i is (zero indexed) position of tab in list + * tabs pased to Tabs component. + */ + tab_id: PropTypes.string, + + /** + * Determines if Tab is disabled or not - defaults to false + */ + disabled: PropTypes.bool, /** * Defines CSS styles which will override styles previously set. The styles @@ -53,101 +69,89 @@ Tab.propTypes = { active_label_style: PropTypes.object, /** - * Often used with CSS to style elements with common properties. + * Additional CSS classes to apply to the Component */ class_name: PropTypes.string, /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. - */ - className: PropTypes.string, - - /** - * Often used with CSS to style elements with common properties. The classes + * Additional CSS classes to apply to the Component The classes * specified with this prop will be applied to the NavItem in the tab. */ tab_class_name: PropTypes.string, /** - * **DEPRECATED** Use `tab_class_name` instead - * - * Often used with CSS to style elements with common properties. The classes - * specified with this prop will be applied to the NavItem in the tab. - */ - tabClassName: PropTypes.string, - - /** - * Often used with CSS to style elements with common properties. The classes + * Additional CSS classes to apply to the Component The classes * specified with this prop will be applied to the NavItem in the tab when it * is active. */ active_tab_class_name: PropTypes.string, /** - * **DEPRECATED** Use `active_tab_class_name` instead - * - * Often used with CSS to style elements with common properties. The classes - * specified with this prop will be applied to the NavItem in the tab when it - * is active. + * Additional CSS classes to apply to the Component The classes + * specified with this prop will be applied to the NavLink in the tab. */ - activeTabClassName: PropTypes.string, + label_class_name: PropTypes.string, /** - * Often used with CSS to style elements with common properties. The classes - * specified with this prop will be applied to the NavLink in the tab. + * Additional CSS classes to apply to the Component The classes + * specified with this prop will be applied to the NavLink in the tab when + * it is active. */ - label_class_name: PropTypes.string, + active_label_class_name: PropTypes.string, /** - * **DEPRECATED** Use `label_class_name` instead + * A unique identifier for the component, used to improve performance by React.js + * while rendering components * - * Often used with CSS to style elements with common properties. The classes - * specified with this prop will be applied to the NavLink in the tab. + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info */ - labelClassName: PropTypes.string, + key: PropTypes.string, /** - * Often used with CSS to style elements with common properties. The classes - * specified with this prop will be applied to the NavLink in the tab when - * it is active. + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Component */ - active_label_class_name: PropTypes.string, + className: PropTypes.string, /** - * **DEPRECATED** Use `active_label_class_name` instead + * **DEPRECATED** Use `tab_class_name` instead * - * Often used with CSS to style elements with common properties. The classes - * specified with this prop will be applied to the NavLink in the tab when - * it is active. + * Additional CSS classes to apply to the Component The classes + * specified with this prop will be applied to the NavItem in the tab. */ - activeLabelClassName: PropTypes.string, + tabClassName: PropTypes.string, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * **DEPRECATED** Use `active_tab_class_name` instead + * + * Additional CSS classes to apply to the Component The classes + * specified with this prop will be applied to the NavItem in the tab when it + * is active. */ - key: PropTypes.string, + activeTabClassName: PropTypes.string, /** - * The tab's label, displayed in the tab itself. + * **DEPRECATED** Use `label_class_name` instead + * + * Additional CSS classes to apply to the Component The classes + * specified with this prop will be applied to the NavLink in the tab. */ - label: PropTypes.string, + labelClassName: PropTypes.string, /** - * Optional identifier for tab used for determining which tab is visible - * if not specified, and Tab is being used inside Tabs component, the tabId - * will be set to "tab-i" where i is (zero indexed) position of tab in list - * tabs pased to Tabs component. + * **DEPRECATED** Use `active_label_class_name` instead + * + * Additional CSS classes to apply to the Component The classes + * specified with this prop will be applied to the NavLink in the tab when + * it is active. */ - tab_id: PropTypes.string, + activeLabelClassName: PropTypes.string, /** - * Determines if tab is disabled or not - defaults to false + * Dash-assigned callback that gets fired when the value changes. */ - disabled: PropTypes.bool + setProps: PropTypes.func }; export default Tab; diff --git a/src/components/tabs/Tabs.js b/src/components/tabs/Tabs.js index 73bdb2dd..4d91166b 100644 --- a/src/components/tabs/Tabs.js +++ b/src/components/tabs/Tabs.js @@ -13,17 +13,17 @@ import { } from '../../private/util'; /** - * Create Bootstrap styled tabs. Use the `active_tab` property to set, or get - * get the currently active tab in a callback. + * Create Bootstrap styled tabs. Use the `active_tab` property to set, or get the + * currently active tab in a callback. */ function Tabs({ children, id, - className, - class_name, - style, active_tab, + style, + class_name, key, + className, setProps }) { children = parseChildrenToArray(children); @@ -149,55 +149,35 @@ Tabs.dashPersistence = { Tabs.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. - */ - id: PropTypes.string, - - /** - * The children of this component + * The children of this Tabs component. Each child should be a Tab component. */ children: PropTypes.node, /** - * Defines CSS styles which will override styles previously set. + * The ID of the Tabs. */ - style: PropTypes.object, - - /** - * Often used with CSS to style elements with common properties. - */ - class_name: PropTypes.string, + id: PropTypes.string, /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. + * The tab_id of the currently active tab. If tab_id has not been specified + * for the active tab, this will default to tab-i, where i is the index + * (starting from 0) of the tab. */ - className: PropTypes.string, + active_tab: PropTypes.string, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * Additional inline CSS styles to apply to the Tabs.. */ - key: PropTypes.string, + style: PropTypes.object, /** - * The tab_id of the currently active tab. If tab_id has not been specified - * for the active tab, this will default to tab-i, where i is the index - * (starting from 0) of the tab. + * Additional CSS classes to apply to the Tabs. */ - active_tab: PropTypes.string, + class_name: PropTypes.string, /** - * Used to allow user interactions in this component to be persisted when - * the component - or the page - is refreshed. If `persisted` is truthy and - * hasn't changed from its previous value, a `value` that the user has - * changed while using the app will keep that change, as long as - * the new `value` also matches what was given originally. - * Used in conjunction with `persistence_type`. + * Used to allow user interactions to be persisted when the page is refreshed. + * See https://dash.plotly.com/persistence for more details */ persistence: PropTypes.oneOfType([ PropTypes.bool, @@ -214,12 +194,27 @@ Tabs.propTypes = { /** * Where persisted user changes will be stored: - * memory: only kept in memory, reset on page refresh. - * local: window.localStorage, data is kept after the browser quit. - * session: window.sessionStorage, data is cleared once the browser quit. + * - memory: only kept in memory, reset on page refresh. + * - local: window.localStorage, data is kept after the browser quit. + * - session: window.sessionStorage, data is cleared once the browser quit. */ persistence_type: PropTypes.oneOf(['local', 'session', 'memory']), + /** + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info + */ + key: PropTypes.string, + + /** + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Tabs. + */ + className: PropTypes.string, + /** * Dash-assigned callback that gets fired when the value changes. */ diff --git a/src/components/toast/Toast.js b/src/components/toast/Toast.js index 88d86a3f..97f153cb 100644 --- a/src/components/toast/Toast.js +++ b/src/components/toast/Toast.js @@ -8,28 +8,28 @@ import RBToast from 'react-bootstrap/Toast'; import {getLoadingState} from '../../private/util'; /** - * Toasts can be used to push messages and notifactions to users. Control - * visibility of the toast with the `is_open` prop, or use `duration` to set a - * timer for auto-dismissal. + * Toasts can be used to push messages and notifactions to users. Control visibility of + * the toast with the `is_open` prop, or use `duration` to set a timer for + * auto-dismissal. */ function Toast({ children, + is_open = true, + dismissable = false, + duration, + n_dismiss = 0, + color, header, icon, header_style, - headerClassName, header_class_name, body_style, - bodyClassName, body_class_name, - duration, - setProps, - className, class_name, - color, - is_open = true, - n_dismiss = 0, - dismissable = false, + className, + headerClassName, + bodyClassName, + setProps, ...otherProps }) { const dismiss = () => { @@ -103,133 +103,93 @@ Toast.dashPersistence = { Toast.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. - */ - id: PropTypes.string, - - /** - * The children of this component + * The children of the Toast. */ children: PropTypes.node, /** - * Defines CSS styles which will override styles previously set. - */ - style: PropTypes.object, - - /** - * Often used with CSS to style elements with common properties. - */ - class_name: PropTypes.string, - - /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. + * The ID of the Toast. */ - className: PropTypes.string, - - /** - * Defines CSS styles which will override styles previously set. The styles - * set here apply to the header of the toast. - */ - header_style: PropTypes.object, + id: PropTypes.string, /** - * Often used with CSS to style elements with common properties. The classes - * specified with this prop will be applied to the header of the toast. + * Whether Toast is currently open. */ - header_class_name: PropTypes.string, + is_open: PropTypes.bool, /** - * **DEPRECATED** - use `header_class_name` instead - * - * Often used with CSS to style elements with common properties. The classes - * specified with this prop will be applied to the header of the toast. + * Set to True to add a dismiss button to the header which will close the + * toast on click */ - headerClassName: PropTypes.string, + dismissable: PropTypes.bool, /** - * Defines CSS styles which will override styles previously set. The styles - * set here apply to the body of the toast. + * Duration in milliseconds after which the Alert dismisses itself. */ - body_style: PropTypes.object, + duration: PropTypes.number, /** - * Often used with CSS to style elements with common properties. The classes - * specified with this prop will be applied to the body of the toast. + * An integer that represents the number of times that the dismiss button has + * been clicked on. */ - body_class_name: PropTypes.string, + n_dismiss: PropTypes.number, /** - * **DEPRECATED** - use `body_class_name` instead. - * - * Often used with CSS to style elements with common properties. The classes - * specified with this prop will be applied to the body of the toast. + * Text to populate the header with */ - bodyClassName: PropTypes.string, + header: PropTypes.node, /** - * HTML tag to use for the Toast, default: div + * Add a contextually coloured icon to the header of the toast. Options are: + * "primary", "secondary", "success", "warning", "danger", "info", "light" or + * "dark". */ - tag: PropTypes.string, + icon: PropTypes.string, /** - * Whether Toast is currently open. + * Toast color, options: primary, secondary, success, info, warning, danger, + * light, dark. Default: secondary. */ - is_open: PropTypes.bool, + color: PropTypes.string, /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * Additional inline CSS styles to apply to the Toast.. */ - key: PropTypes.string, + style: PropTypes.object, /** - * Text to populate the header with + * Additional CSS classes to apply to the Toast. */ - header: PropTypes.node, + class_name: PropTypes.string, /** - * Set to True to add a dismiss button to the header which will close the - * toast on click + * Additional inline CSS styles to apply to the Toast header. */ - dismissable: PropTypes.bool, + header_style: PropTypes.object, /** - * Duration in milliseconds after which the Alert dismisses itself. + * Additional CSS classes to apply to the Toast header. */ - duration: PropTypes.number, + header_class_name: PropTypes.string, /** - * An integer that represents the number of times that the dismiss button has - * been clicked on. + * Additional CSS classes to apply to the Toast body. */ - n_dismiss: PropTypes.number, + body_style: PropTypes.object, /** - * Add a contextually coloured icon to the header of the toast. Options are: - * "primary", "secondary", "success", "warning", "danger", "info", "light" or - * "dark". + * Additional CSS classes to apply to the Toast body. */ - icon: PropTypes.string, + body_class_name: PropTypes.string, /** - * Toast color, options: primary, secondary, success, info, warning, danger, - * light, dark. Default: secondary. + * HTML tag to use for the Toast, default: div */ - color: PropTypes.string, + tag: PropTypes.string, /** - * Used to allow user interactions in this component to be persisted when - * the component - or the page - is refreshed. If `persisted` is truthy and - * hasn't changed from its previous value, a `value` that the user has - * changed while using the app will keep that change, as long as - * the new `value` also matches what was given originally. - * Used in conjunction with `persistence_type`. + * Used to allow user interactions to be persisted when the page is refreshed. + * See https://dash.plotly.com/persistence for more details */ persistence: PropTypes.oneOfType([ PropTypes.bool, @@ -246,12 +206,43 @@ Toast.propTypes = { /** * Where persisted user changes will be stored: - * memory: only kept in memory, reset on page refresh. - * local: window.localStorage, data is kept after the browser quit. - * session: window.sessionStorage, data is cleared once the browser quit. + * - memory: only kept in memory, reset on page refresh. + * - local: window.localStorage, data is kept after the browser quit. + * - session: window.sessionStorage, data is cleared once the browser quit. */ persistence_type: PropTypes.oneOf(['local', 'session', 'memory']), + /** + * A unique identifier for the component, used to improve performance by React.js + * while rendering components + * + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info + */ + key: PropTypes.string, + + /** + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Toast. + */ + className: PropTypes.string, + + /** + * **DEPRECATED** - use `header_class_name` instead + * + * Additional CSS classes to apply to the Toast. The classes + * specified with this prop will be applied to the header of the toast. + */ + headerClassName: PropTypes.string, + + /** + * **DEPRECATED** - use `body_class_name` instead. + * + * Additional CSS classes to apply to the Toast. The classes + * specified with this prop will be applied to the body of the toast. + */ + bodyClassName: PropTypes.string, + /** * Dash-assigned callback that gets fired when the input changes. **/ diff --git a/src/components/tooltip/Tooltip.js b/src/components/tooltip/Tooltip.js index 2e4cb6d0..2b411908 100644 --- a/src/components/tooltip/Tooltip.js +++ b/src/components/tooltip/Tooltip.js @@ -14,18 +14,18 @@ import {getLoadingState} from '../../private/util'; */ function Tooltip({ - id, children, + id, is_open, - className, - class_name, + trigger = 'hover focus', style, + class_name, delay = {show: 0, hide: 50}, placement = 'auto', flip = true, autohide = true, fade = true, - trigger = 'hover focus', + className, ...otherProps }) { return ( @@ -53,45 +53,40 @@ function Tooltip({ Tooltip.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. - */ - id: PropTypes.string, - - /** - * The children of this component + * The children of this Tooltip. */ children: PropTypes.node, /** - * Defines CSS styles which will override styles previously set. - */ - style: PropTypes.object, - - /** - * Often used with CSS to style elements with common properties. + * The ID of the Tooltip. */ - class_name: PropTypes.string, + id: PropTypes.string, /** - * **DEPRECATED** Use `class_name` instead. - * - * Often used with CSS to style elements with common properties. + * The id of the element to attach the tooltip to */ - className: PropTypes.string, + target: PropTypes.oneOfType([PropTypes.string, PropTypes.object]), /** - * A unique identifier for the component, used to improve - * performance by React.js while rendering components - * See https://reactjs.org/docs/lists-and-keys.html for more info + * Whether the Tooltip is open or not. */ - key: PropTypes.string, + is_open: PropTypes.bool, /** - * The id of the element to attach the tooltip to + * Space separated list of triggers (e.g. "click hover focus legacy"). These + * specify ways in which the target component can toggle the tooltip. If + * omitted you must toggle the tooltip yourself using callbacks. Options + * are: + * - "click": toggles the popover when the target is clicked. + * - "hover": toggles the popover when the target is hovered over with the + * cursor. + * - "focus": toggles the popover when the target receives focus + * - "legacy": toggles the popover when the target is clicked, but will also + * dismiss the popover when the user clicks outside of the popover. + * + * Default is "hover focus" */ - target: PropTypes.oneOfType([PropTypes.string, PropTypes.object]), + trigger: PropTypes.string, /** * How to place the tooltip. @@ -115,15 +110,15 @@ Tooltip.propTypes = { ]), /** - * Whether to flip the direction of the popover if too close to the container - * edge, default True. + * Control the delay of hide and show events. */ - flip: PropTypes.bool, + delay: PropTypes.shape({show: PropTypes.number, hide: PropTypes.number}), /** - * Control the delay of hide and show events. + * Whether to flip the direction of the popover if too close to the container + * edge, default True. */ - delay: PropTypes.shape({show: PropTypes.number, hide: PropTypes.number}), + flip: PropTypes.bool, /** * Optionally hide tooltip when hovering over tooltip content - default True. @@ -137,25 +132,34 @@ Tooltip.propTypes = { fade: PropTypes.bool, /** - * Space separated list of triggers (e.g. "click hover focus legacy"). These - * specify ways in which the target component can toggle the tooltip. If - * omitted you must toggle the tooltip yourself using callbacks. Options - * are: - * - "click": toggles the popover when the target is clicked. - * - "hover": toggles the popover when the target is hovered over with the - * cursor. - * - "focus": toggles the popover when the target receives focus - * - "legacy": toggles the popover when the target is clicked, but will also - * dismiss the popover when the user clicks outside of the popover. + * Additional inline CSS styles to apply to the Component. + */ + style: PropTypes.object, + + /** + * Additional CSS classes to apply to the Component + */ + class_name: PropTypes.string, + + /** + * A unique identifier for the component, used to improve performance by React.js + * while rendering components * - * Default is "hover focus" + * See https://react.dev/learn/rendering-lists#why-does-react-need-keys for more info */ - trigger: PropTypes.string, + key: PropTypes.string, /** - * Whether the Tooltip is open or not. + * **DEPRECATED** Use `class_name` instead. + * + * Additional CSS classes to apply to the Component + */ + className: PropTypes.string, + + /** + * Dash-assigned callback that gets fired when the value changes. */ - is_open: PropTypes.bool + setProps: PropTypes.func }; export default Tooltip; diff --git a/src/private/Link.js b/src/private/Link.js index 32981e5e..963f60d5 100644 --- a/src/private/Link.js +++ b/src/private/Link.js @@ -87,9 +87,7 @@ const Link = React.forwardRef(function Link( Link.propTypes = { /** - * The ID of this component, used to identify dash components - * in callbacks. The ID needs to be unique across all of the - * components in an app. + * The ID of the component */ id: PropTypes.string, @@ -99,19 +97,19 @@ Link.propTypes = { children: PropTypes.node, /** - * Defines CSS styles which will override styles previously set. + * Additional inline CSS styles to apply to the Component. */ style: PropTypes.object, /** - * Often used with CSS to style elements with common properties. + * Additional CSS classes to apply to the Component */ class_name: PropTypes.string, /** * **DEPRECATED** Use `class_name` instead. * - * Often used with CSS to style elements with common properties. + * Additional CSS classes to apply to the Component */ className: PropTypes.string, @@ -126,12 +124,9 @@ Link.propTypes = { disabled: PropTypes.bool, /** - * If true, the browser will treat this as an external link, - * forcing a page refresh at the new location. If false, - * this just changes the location without triggering a page - * refresh. Use this if you are observing dcc.Location, for - * instance. Defaults to true for absolute URLs and false - * otherwise. + * If True, clicking on the Link will behave like a hyperlink. If False, the Link will + * behave like a dcc.Link component, and can be used in conjunction with dcc.Location + * for navigation within a Dash app. */ external_link: PropTypes.bool, diff --git a/src/private/types.js b/src/private/types.js new file mode 100644 index 00000000..c1f7618c --- /dev/null +++ b/src/private/types.js @@ -0,0 +1,23 @@ +import PropTypes from 'prop-types'; + +const stringOrNumberPropType = PropTypes.oneOfType([ + PropTypes.number, + PropTypes.string +]); + +const columnPropType = PropTypes.oneOfType([ + PropTypes.bool, + PropTypes.string, + PropTypes.number, + PropTypes.shape({ + size: PropTypes.oneOfType([ + PropTypes.bool, + PropTypes.number, + PropTypes.string + ]), + order: stringOrNumberPropType, + offset: stringOrNumberPropType + }) +]); + +export {columnPropType}; From b50f48ebdc6a9a0b503b3c6c052c5a963e973f31 Mon Sep 17 00:00:00 2001 From: tcbegley Date: Fri, 21 Feb 2025 22:41:15 +0000 Subject: [PATCH 3/4] Some typos --- src/components/badge/Badge.js | 2 +- src/components/button/Button.js | 6 +++--- src/components/carousel/Carousel.js | 7 ++++--- src/components/collapse/Collapse.js | 8 ++++---- src/components/input/Checklist.js | 2 +- src/components/input/RadioItems.js | 4 ++-- src/components/input/Select.js | 4 ++-- src/components/layout/Container.js | 6 +++--- src/components/modal/ModalBody.js | 6 +++--- src/components/nav/Navbar.js | 6 +++--- src/components/nav/NavbarToggler.js | 6 +++--- src/components/pagination/Pagination.js | 2 +- src/components/popover/PopoverHeader.js | 2 +- src/components/progress/Progress.js | 2 +- src/components/spinner/Spinner.js | 4 ++-- src/components/tabs/Tab.js | 20 ++++++++++---------- src/components/tabs/Tabs.js | 2 +- src/components/toast/Toast.js | 2 +- src/components/tooltip/Tooltip.js | 6 +++--- src/private/Link.js | 6 +++--- src/private/util.js | 2 +- 21 files changed, 53 insertions(+), 52 deletions(-) diff --git a/src/components/badge/Badge.js b/src/components/badge/Badge.js index 1ea8afa6..2d627ded 100644 --- a/src/components/badge/Badge.js +++ b/src/components/badge/Badge.js @@ -98,7 +98,7 @@ Badge.propTypes = { pill: PropTypes.bool, /** - * Additional inline CSS styles to apply to the Badge.. + * Additional inline CSS styles to apply to the Badge. */ style: PropTypes.object, diff --git a/src/components/button/Button.js b/src/components/button/Button.js index 442e2c4a..e337ae99 100644 --- a/src/components/button/Button.js +++ b/src/components/button/Button.js @@ -103,12 +103,12 @@ Button.propTypes = { external_link: PropTypes.bool, /** - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Button. */ class_name: PropTypes.string, /** - * Additional inline CSS styles to apply to the Component. + * Additional inline CSS styles to apply to the Button. */ style: PropTypes.object, @@ -184,7 +184,7 @@ Button.propTypes = { /** * **DEPRECATED** Use `class_name` instead. * - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Button */ className: PropTypes.string, diff --git a/src/components/carousel/Carousel.js b/src/components/carousel/Carousel.js index 8e6d1950..cb0ee3ca 100644 --- a/src/components/carousel/Carousel.js +++ b/src/components/carousel/Carousel.js @@ -8,7 +8,7 @@ import Link from '../../private/Link'; import {getLoadingState} from '../../private/util'; /** - * Component for creating Bootstrap carousel. This component is a slideshow + * Carousel. for creating Bootstrap carousel. This component is a slideshow * for cycling through a series of content. */ function Carousel({ @@ -188,7 +188,8 @@ Carousel.propTypes = { style: PropTypes.object, /** - * Defines the className of the carousel container. Additional CSS classes to apply to the Component + * Defines the className of the carousel container. Additional CSS classes to apply to + * the Carousel. */ class_name: PropTypes.string, @@ -230,7 +231,7 @@ Carousel.propTypes = { /** * **DEPRECATED** Use `class_name` instead. * - * efines the className of the carousel container. Additional CSS classes to apply to the Component + * efines the className of the carousel container. Additional CSS classes to apply to the Carousel. */ className: PropTypes.string, diff --git a/src/components/collapse/Collapse.js b/src/components/collapse/Collapse.js index 4cad44e9..e00075a6 100644 --- a/src/components/collapse/Collapse.js +++ b/src/components/collapse/Collapse.js @@ -42,7 +42,7 @@ const Collapse = React.forwardRef(function Collapse( Collapse.propTypes = { /** - * The children of the Collapse.. + * The children of the Collapse. */ children: PropTypes.node, @@ -68,12 +68,12 @@ Collapse.propTypes = { navbar: PropTypes.bool, /** - * Additional inline CSS styles to apply to the Component. + * Additional inline CSS styles to apply to the Collapse. */ style: PropTypes.object, /** - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Collapse. */ class_name: PropTypes.string, @@ -93,7 +93,7 @@ Collapse.propTypes = { /** * **DEPRECATED** Use `class_name` instead. * - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Collapse. */ className: PropTypes.string, diff --git a/src/components/input/Checklist.js b/src/components/input/Checklist.js index 7379cf94..19a9ea8e 100644 --- a/src/components/input/Checklist.js +++ b/src/components/input/Checklist.js @@ -159,7 +159,7 @@ Checklist.propTypes = { * ``` * [ * {"label": "label1", "value": "value1"}, - * {"label": "label2", "value": "value2"}, ... + * {"label": "label2", "value": "value2"}, * ] * ``` */ diff --git a/src/components/input/RadioItems.js b/src/components/input/RadioItems.js index 57d46f2d..9f6c2934 100644 --- a/src/components/input/RadioItems.js +++ b/src/components/input/RadioItems.js @@ -150,7 +150,7 @@ RadioItems.propTypes = { * ``` * [ * {"label": "label1", "value": "value1"}, - * {"label": "label2", "value": "value2"}, ... + * {"label": "label2", "value": "value2"}, * ] * ``` */ @@ -169,7 +169,7 @@ RadioItems.propTypes = { * which is equal to * [ * {label: `label1`, value: `value1`}, - * {label: `label2`, value: `value2`}, ... + * {label: `label2`, value: `value2`}, * ] */ PropTypes.object, diff --git a/src/components/input/Select.js b/src/components/input/Select.js index dbdcc94f..1d18ccd5 100644 --- a/src/components/input/Select.js +++ b/src/components/input/Select.js @@ -91,7 +91,7 @@ Select.propTypes = { * ``` * [ * {"label": "label1", "value": "value1"}, - * {"label": "label2", "value": "value2"}, ... + * {"label": "label2", "value": "value2"}, * ] * ``` */ @@ -110,7 +110,7 @@ Select.propTypes = { * which is equal to * [ * {label: `label1`, value: `value1`}, - * {label: `label2`, value: `value2`}, ... + * {label: `label2`, value: `value2`}, * ] */ PropTypes.object, diff --git a/src/components/layout/Container.js b/src/components/layout/Container.js index 7cbe03bd..d1831e1e 100644 --- a/src/components/layout/Container.js +++ b/src/components/layout/Container.js @@ -45,12 +45,12 @@ Container.propTypes = { fluid: PropTypes.oneOfType([PropTypes.bool, PropTypes.string]), /** - * Additional inline CSS styles to apply to the Component. + * Additional inline CSS styles to apply to the Container. */ style: PropTypes.object, /** - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Container. */ class_name: PropTypes.string, @@ -70,7 +70,7 @@ Container.propTypes = { /** * **DEPRECATED** Use `class_name` instead. * - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Container. */ className: PropTypes.string, diff --git a/src/components/modal/ModalBody.js b/src/components/modal/ModalBody.js index 351dc657..476ea34e 100644 --- a/src/components/modal/ModalBody.js +++ b/src/components/modal/ModalBody.js @@ -35,12 +35,12 @@ ModalBody.propTypes = { id: PropTypes.string, /** - * Additional inline CSS styles to apply to the Component. + * Additional inline CSS styles to apply to the ModalBody. */ style: PropTypes.object, /** - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the ModalBody. */ class_name: PropTypes.string, @@ -52,7 +52,7 @@ ModalBody.propTypes = { /** * **DEPRECATED** Use `class_name` instead. * - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the ModalBody. */ className: PropTypes.string, diff --git a/src/components/nav/Navbar.js b/src/components/nav/Navbar.js index b336fb1c..e41521f5 100644 --- a/src/components/nav/Navbar.js +++ b/src/components/nav/Navbar.js @@ -86,12 +86,12 @@ Navbar.propTypes = { expand: PropTypes.oneOfType([PropTypes.bool, PropTypes.string]), /** - * Additional inline CSS styles to apply to the Component. + * Additional inline CSS styles to apply to the Navbar. */ style: PropTypes.object, /** - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Navbar. */ class_name: PropTypes.string, @@ -116,7 +116,7 @@ Navbar.propTypes = { /** * **DEPRECATED** Use `class_name` instead. * - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Navbar. */ className: PropTypes.string, diff --git a/src/components/nav/NavbarToggler.js b/src/components/nav/NavbarToggler.js index 94754c3e..1fed8412 100644 --- a/src/components/nav/NavbarToggler.js +++ b/src/components/nav/NavbarToggler.js @@ -51,12 +51,12 @@ NavbarToggler.propTypes = { n_clicks: PropTypes.number, /** - * Additional inline CSS styles to apply to the Component. + * Additional inline CSS styles to apply to the NavbarToggler. */ style: PropTypes.object, /** - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the NavbarToggler. */ class_name: PropTypes.string, @@ -76,7 +76,7 @@ NavbarToggler.propTypes = { /** * **DEPRECATED** Use `class_name` instead. * - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the NavbarToggler. */ className: PropTypes.string, diff --git a/src/components/pagination/Pagination.js b/src/components/pagination/Pagination.js index be653541..1bbfd269 100644 --- a/src/components/pagination/Pagination.js +++ b/src/components/pagination/Pagination.js @@ -200,7 +200,7 @@ Pagination.propTypes = { first_last: PropTypes.bool, /** - * Additional inline CSS styles to apply to the Pagination.. + * Additional inline CSS styles to apply to the Pagination. */ style: PropTypes.object, diff --git a/src/components/popover/PopoverHeader.js b/src/components/popover/PopoverHeader.js index 73713f4b..180f9bb3 100644 --- a/src/components/popover/PopoverHeader.js +++ b/src/components/popover/PopoverHeader.js @@ -33,7 +33,7 @@ PopoverHeader.propTypes = { id: PropTypes.string, /** - * Additional inline CSS styles to apply to the PopoverHeader.. + * Additional inline CSS styles to apply to the PopoverHeader. */ style: PropTypes.object, diff --git a/src/components/progress/Progress.js b/src/components/progress/Progress.js index 8f63bcad..80f050f0 100644 --- a/src/components/progress/Progress.js +++ b/src/components/progress/Progress.js @@ -227,7 +227,7 @@ Progress.propTypes = { striped: PropTypes.bool, /** - * Additional inline CSS styles to apply to the Progress.. + * Additional inline CSS styles to apply to the Progress. */ style: PropTypes.object, diff --git a/src/components/spinner/Spinner.js b/src/components/spinner/Spinner.js index 25b51891..65f0f14d 100644 --- a/src/components/spinner/Spinner.js +++ b/src/components/spinner/Spinner.js @@ -239,7 +239,7 @@ Spinner.propTypes = { fullscreen_style: PropTypes.object, /** - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Spinner when fullscreen=True. */ fullscreen_class_name: PropTypes.string, @@ -261,7 +261,7 @@ Spinner.propTypes = { /** * **DEPRECATED** - use `fullscreen_class_name` instead. * - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Spinner when fullscreen=True. */ fullscreenClassName: PropTypes.string, diff --git a/src/components/tabs/Tab.js b/src/components/tabs/Tab.js index 44c25c4d..d16584e2 100644 --- a/src/components/tabs/Tab.js +++ b/src/components/tabs/Tab.js @@ -69,31 +69,31 @@ Tab.propTypes = { active_label_style: PropTypes.object, /** - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Tabs. */ class_name: PropTypes.string, /** - * Additional CSS classes to apply to the Component The classes + * Additional CSS classes to apply to the Tabs. The classes * specified with this prop will be applied to the NavItem in the tab. */ tab_class_name: PropTypes.string, /** - * Additional CSS classes to apply to the Component The classes + * Additional CSS classes to apply to the Tabs. The classes * specified with this prop will be applied to the NavItem in the tab when it * is active. */ active_tab_class_name: PropTypes.string, /** - * Additional CSS classes to apply to the Component The classes + * Additional CSS classes to apply to the Tabs. The classes * specified with this prop will be applied to the NavLink in the tab. */ label_class_name: PropTypes.string, /** - * Additional CSS classes to apply to the Component The classes + * Additional CSS classes to apply to the Tabs. The classes * specified with this prop will be applied to the NavLink in the tab when * it is active. */ @@ -110,14 +110,14 @@ Tab.propTypes = { /** * **DEPRECATED** Use `class_name` instead. * - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Tabs. */ className: PropTypes.string, /** * **DEPRECATED** Use `tab_class_name` instead * - * Additional CSS classes to apply to the Component The classes + * Additional CSS classes to apply to the Tabs. The classes * specified with this prop will be applied to the NavItem in the tab. */ tabClassName: PropTypes.string, @@ -125,7 +125,7 @@ Tab.propTypes = { /** * **DEPRECATED** Use `active_tab_class_name` instead * - * Additional CSS classes to apply to the Component The classes + * Additional CSS classes to apply to the Tabs. The classes * specified with this prop will be applied to the NavItem in the tab when it * is active. */ @@ -134,7 +134,7 @@ Tab.propTypes = { /** * **DEPRECATED** Use `label_class_name` instead * - * Additional CSS classes to apply to the Component The classes + * Additional CSS classes to apply to the Tabs. The classes * specified with this prop will be applied to the NavLink in the tab. */ labelClassName: PropTypes.string, @@ -142,7 +142,7 @@ Tab.propTypes = { /** * **DEPRECATED** Use `active_label_class_name` instead * - * Additional CSS classes to apply to the Component The classes + * Additional CSS classes to apply to the Tabs. The classes * specified with this prop will be applied to the NavLink in the tab when * it is active. */ diff --git a/src/components/tabs/Tabs.js b/src/components/tabs/Tabs.js index 4d91166b..a8f108b0 100644 --- a/src/components/tabs/Tabs.js +++ b/src/components/tabs/Tabs.js @@ -166,7 +166,7 @@ Tabs.propTypes = { active_tab: PropTypes.string, /** - * Additional inline CSS styles to apply to the Tabs.. + * Additional inline CSS styles to apply to the Tabs. */ style: PropTypes.object, diff --git a/src/components/toast/Toast.js b/src/components/toast/Toast.js index 97f153cb..f2c3bde8 100644 --- a/src/components/toast/Toast.js +++ b/src/components/toast/Toast.js @@ -153,7 +153,7 @@ Toast.propTypes = { color: PropTypes.string, /** - * Additional inline CSS styles to apply to the Toast.. + * Additional inline CSS styles to apply to the Toast. */ style: PropTypes.object, diff --git a/src/components/tooltip/Tooltip.js b/src/components/tooltip/Tooltip.js index 2b411908..3686a058 100644 --- a/src/components/tooltip/Tooltip.js +++ b/src/components/tooltip/Tooltip.js @@ -132,12 +132,12 @@ Tooltip.propTypes = { fade: PropTypes.bool, /** - * Additional inline CSS styles to apply to the Component. + * Additional inline CSS styles to apply to the Tooltip. */ style: PropTypes.object, /** - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Tooltip */ class_name: PropTypes.string, @@ -152,7 +152,7 @@ Tooltip.propTypes = { /** * **DEPRECATED** Use `class_name` instead. * - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Tooltip */ className: PropTypes.string, diff --git a/src/private/Link.js b/src/private/Link.js index 963f60d5..a4443b76 100644 --- a/src/private/Link.js +++ b/src/private/Link.js @@ -97,19 +97,19 @@ Link.propTypes = { children: PropTypes.node, /** - * Additional inline CSS styles to apply to the Component. + * Additional inline CSS styles to apply to the Link. */ style: PropTypes.object, /** - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Link. */ class_name: PropTypes.string, /** * **DEPRECATED** Use `class_name` instead. * - * Additional CSS classes to apply to the Component + * Additional CSS classes to apply to the Link. */ className: PropTypes.string, diff --git a/src/private/util.js b/src/private/util.js index a2004baa..f2217e89 100644 --- a/src/private/util.js +++ b/src/private/util.js @@ -30,7 +30,7 @@ const sanitizeOptions = options => { * which is equal to * [ * {label: `label1`, value: `value1`}, - * {label: `label2`, value: `value2`}, ... + * {label: `label2`, value: `value2`}, * ] */ return Object.entries(options).map(([value, label]) => ({ From 2d7395d36662675bdd7fc8167542a3ad86ce7733 Mon Sep 17 00:00:00 2001 From: tcbegley Date: Fri, 21 Feb 2025 22:55:41 +0000 Subject: [PATCH 4/4] Update Table tests --- src/components/table/__tests__/Table.test.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/components/table/__tests__/Table.test.js b/src/components/table/__tests__/Table.test.js index 1866ba5b..248fff32 100644 --- a/src/components/table/__tests__/Table.test.js +++ b/src/components/table/__tests__/Table.test.js @@ -70,7 +70,7 @@ describe('Table', () => { // dark table const { container: {firstChild: tableDark} - } = render(); + } = render(
); expect(tableDark).toHaveClass('table-dark'); // table with hover animations