From 75ae707e4dd73feb74cd56284b28ba226b421251 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Wed, 22 Jan 2025 19:12:44 +0200 Subject: [PATCH] chore(ui): add tsdocs for DataTable components (#11087) Add TSDocs for `DataTable` components to generate better docs for their props --- .../components/data-table-action-cell.tsx | 1 + .../components/data-table-command-bar.tsx | 9 +++++++++ .../components/data-table-filter-bar.tsx | 1 + .../components/data-table-filter-menu.tsx | 8 ++++++++ .../components/data-table-filter.tsx | 1 + .../components/data-table-pagination.tsx | 7 +++++++ .../components/data-table-search.tsx | 14 ++++++++++++++ .../components/data-table-select-cell.tsx | 1 + .../components/data-table-sorting-icon.tsx | 1 + .../components/data-table-sorting-menu.tsx | 8 ++++++++ .../data-table/components/data-table-table.tsx | 4 ++++ .../components/data-table-toolbar.tsx | 12 ++++++++++++ .../ui/src/blocks/data-table/data-table.tsx | 18 ++++++++++++++++++ 13 files changed, 85 insertions(+) diff --git a/packages/design-system/ui/src/blocks/data-table/components/data-table-action-cell.tsx b/packages/design-system/ui/src/blocks/data-table/components/data-table-action-cell.tsx index 98a326497b..0dea45c771 100644 --- a/packages/design-system/ui/src/blocks/data-table/components/data-table-action-cell.tsx +++ b/packages/design-system/ui/src/blocks/data-table/components/data-table-action-cell.tsx @@ -77,6 +77,7 @@ const DataTableActionCell = ({ ) } +DataTableActionCell.displayName = "DataTable.ActionCell" export { DataTableActionCell } export type { DataTableActionCellProps } diff --git a/packages/design-system/ui/src/blocks/data-table/components/data-table-command-bar.tsx b/packages/design-system/ui/src/blocks/data-table/components/data-table-command-bar.tsx index 5dde5c2811..af8d35b04f 100644 --- a/packages/design-system/ui/src/blocks/data-table/components/data-table-command-bar.tsx +++ b/packages/design-system/ui/src/blocks/data-table/components/data-table-command-bar.tsx @@ -6,9 +6,17 @@ import { useDataTableContext } from "@/blocks/data-table/context/use-data-table- import { CommandBar } from "@/components/command-bar" interface DataTableCommandBarProps { + /** + * The label to show when items are selected. If a function is passed, + * it will be called with the count of selected items. + */ selectedLabel?: ((count: number) => string) | string } +/** + * This component adds a command bar to the data table, which is used + * to show commands that can be executed on the selected rows. + */ const DataTableCommandBar = (props: DataTableCommandBarProps) => { const { instance } = useDataTableContext() @@ -55,6 +63,7 @@ const DataTableCommandBar = (props: DataTableCommandBarProps) => { ) } +DataTableCommandBar.displayName = "DataTable.CommandBar" export { DataTableCommandBar } export type { DataTableCommandBarProps } diff --git a/packages/design-system/ui/src/blocks/data-table/components/data-table-filter-bar.tsx b/packages/design-system/ui/src/blocks/data-table/components/data-table-filter-bar.tsx index 9fc1c8b6b4..9540b80c90 100644 --- a/packages/design-system/ui/src/blocks/data-table/components/data-table-filter-bar.tsx +++ b/packages/design-system/ui/src/blocks/data-table/components/data-table-filter-bar.tsx @@ -51,6 +51,7 @@ const DataTableFilterBar = ({ ) } +DataTableFilterBar.displayName = "DataTable.FilterBar" const DataTableFilterBarSkeleton = ({ filterCount, diff --git a/packages/design-system/ui/src/blocks/data-table/components/data-table-filter-menu.tsx b/packages/design-system/ui/src/blocks/data-table/components/data-table-filter-menu.tsx index d4a32bba73..94732638b3 100644 --- a/packages/design-system/ui/src/blocks/data-table/components/data-table-filter-menu.tsx +++ b/packages/design-system/ui/src/blocks/data-table/components/data-table-filter-menu.tsx @@ -8,9 +8,16 @@ import { Tooltip } from "@/components/tooltip" import { Funnel } from "@medusajs/icons" interface DataTableFilterMenuProps { + /** + * The tooltip to show when hovering over the filter menu. + */ tooltip?: string } +/** + * This component adds a filter menu to the data table, allowing users + * to filter the table's data. + */ const DataTableFilterMenu = (props: DataTableFilterMenuProps) => { const { instance } = useDataTableContext() @@ -56,6 +63,7 @@ const DataTableFilterMenu = (props: DataTableFilterMenuProps) => { ) } +DataTableFilterMenu.displayName = "DataTable.FilterMenu" const DataTableFilterMenuSkeleton = () => { return diff --git a/packages/design-system/ui/src/blocks/data-table/components/data-table-filter.tsx b/packages/design-system/ui/src/blocks/data-table/components/data-table-filter.tsx index 870dc1961d..1632a9d479 100644 --- a/packages/design-system/ui/src/blocks/data-table/components/data-table-filter.tsx +++ b/packages/design-system/ui/src/blocks/data-table/components/data-table-filter.tsx @@ -211,6 +211,7 @@ const DataTableFilter = ({ id, filter }: DataTableFilterProps) => { ) } +DataTableFilter.displayName = "DataTable.Filter" type DataTableFilterDateContentProps = { id: string diff --git a/packages/design-system/ui/src/blocks/data-table/components/data-table-pagination.tsx b/packages/design-system/ui/src/blocks/data-table/components/data-table-pagination.tsx index 26d3b099c8..35b933b6ee 100644 --- a/packages/design-system/ui/src/blocks/data-table/components/data-table-pagination.tsx +++ b/packages/design-system/ui/src/blocks/data-table/components/data-table-pagination.tsx @@ -7,9 +7,15 @@ import { Skeleton } from "@/components/skeleton" import { Table } from "@/components/table" interface DataTablePaginationProps { + /** + * The translations for strings in the pagination component. + */ translations?: React.ComponentProps["translations"] } +/** + * This component adds a pagination component and functionality to the data table. + */ const DataTablePagination = (props: DataTablePaginationProps) => { const { instance } = useDataTableContext() @@ -38,6 +44,7 @@ const DataTablePagination = (props: DataTablePaginationProps) => { /> ) } +DataTablePagination.displayName = "DataTable.Pagination" const DataTablePaginationSkeleton = () => { return ( diff --git a/packages/design-system/ui/src/blocks/data-table/components/data-table-search.tsx b/packages/design-system/ui/src/blocks/data-table/components/data-table-search.tsx index 854481a2df..30e89cc7a7 100644 --- a/packages/design-system/ui/src/blocks/data-table/components/data-table-search.tsx +++ b/packages/design-system/ui/src/blocks/data-table/components/data-table-search.tsx @@ -8,11 +8,24 @@ import * as React from "react" import { useDataTableContext } from "@/blocks/data-table/context/use-data-table-context" interface DataTableSearchProps { + /** + * If true, the search input will be focused on mount. + */ autoFocus?: boolean + /** + * Additional classes to pass to the search input. + */ className?: string + /** + * The placeholder text to show in the search input. + */ placeholder?: string } +/** + * This component adds a search input to the data table, allowing users + * to search through the table's data. + */ const DataTableSearch = (props: DataTableSearchProps) => { const { className, ...rest } = props const { instance } = useDataTableContext() @@ -43,6 +56,7 @@ const DataTableSearch = (props: DataTableSearchProps) => { /> ) } +DataTableSearch.displayName = "DataTable.Search" const DataTableSearchSkeleton = () => { return diff --git a/packages/design-system/ui/src/blocks/data-table/components/data-table-select-cell.tsx b/packages/design-system/ui/src/blocks/data-table/components/data-table-select-cell.tsx index 112ae4f153..50b046a693 100644 --- a/packages/design-system/ui/src/blocks/data-table/components/data-table-select-cell.tsx +++ b/packages/design-system/ui/src/blocks/data-table/components/data-table-select-cell.tsx @@ -21,6 +21,7 @@ const DataTableSelectCell = (props: DataTableSelectCellProps) => /> ) } +DataTableSelectCell.displayName = "DataTable.SelectCell" interface DataTableSelectHeaderProps { ctx: DataTableHeaderContext diff --git a/packages/design-system/ui/src/blocks/data-table/components/data-table-sorting-icon.tsx b/packages/design-system/ui/src/blocks/data-table/components/data-table-sorting-icon.tsx index 821779bcd0..4456412e46 100644 --- a/packages/design-system/ui/src/blocks/data-table/components/data-table-sorting-icon.tsx +++ b/packages/design-system/ui/src/blocks/data-table/components/data-table-sorting-icon.tsx @@ -40,6 +40,7 @@ const DataTableSortingIcon = (props: SortingIconProps) => { ) } +DataTableSortingIcon.displayName = "DataTable.SortingIcon" export { DataTableSortingIcon } export type { SortingIconProps } diff --git a/packages/design-system/ui/src/blocks/data-table/components/data-table-sorting-menu.tsx b/packages/design-system/ui/src/blocks/data-table/components/data-table-sorting-menu.tsx index 298bc9b5ca..1bc63f3c8a 100644 --- a/packages/design-system/ui/src/blocks/data-table/components/data-table-sorting-menu.tsx +++ b/packages/design-system/ui/src/blocks/data-table/components/data-table-sorting-menu.tsx @@ -10,9 +10,16 @@ import { ArrowDownMini, ArrowUpMini, DescendingSorting } from "@medusajs/icons" import * as React from "react" interface DataTableSortingMenuProps { + /** + * The tooltip to show when hovering over the sorting menu. + */ tooltip?: string } +/** + * This component adds a sorting menu to the data table, allowing users + * to sort the table's data. + */ const DataTableSortingMenu = (props: DataTableSortingMenuProps) => { const { instance } = useDataTableContext() @@ -114,6 +121,7 @@ const DataTableSortingMenu = (props: DataTableSortingMenuProps) => { ) } +DataTableSortingMenu.displayName = "DataTable.SortingMenu" function getSortLabel(column: DataTableColumn) { const meta = column.columnDef.meta as DataTableSortableColumnDefMeta | undefined diff --git a/packages/design-system/ui/src/blocks/data-table/components/data-table-table.tsx b/packages/design-system/ui/src/blocks/data-table/components/data-table-table.tsx index e6a7e2849b..1de92fcfb5 100644 --- a/packages/design-system/ui/src/blocks/data-table/components/data-table-table.tsx +++ b/packages/design-system/ui/src/blocks/data-table/components/data-table-table.tsx @@ -23,6 +23,9 @@ interface DataTableTableProps { emptyState?: DataTableEmptyStateProps } +/** + * This component renders the table in a data table, supporting advanced features. + */ const DataTableTable = (props: DataTableTableProps) => { const [hoveredRowId, setHoveredRowId] = React.useState(null) const isKeyDown = React.useRef(false) @@ -254,6 +257,7 @@ const DataTableTable = (props: DataTableTableProps) => { ) } +DataTableTable.displayName = "DataTable.Table" interface DataTableEmptyStateDisplayProps { state: DataTableEmptyState diff --git a/packages/design-system/ui/src/blocks/data-table/components/data-table-toolbar.tsx b/packages/design-system/ui/src/blocks/data-table/components/data-table-toolbar.tsx index 82543d44ad..470bd4d8c6 100644 --- a/packages/design-system/ui/src/blocks/data-table/components/data-table-toolbar.tsx +++ b/packages/design-system/ui/src/blocks/data-table/components/data-table-toolbar.tsx @@ -11,11 +11,23 @@ interface DataTableToolbarTranslations { } interface DataTableToolbarProps { + /** + * Additional classes to pass to the wrapper `div` of the component. + */ className?: string + /** + * The children to show in the toolbar. + */ children?: React.ReactNode + /** + * The translations of strings in the toolbar. + */ translations?: DataTableToolbarTranslations } +/** + * Toolbar shown for the data table. + */ const DataTableToolbar = (props: DataTableToolbarProps) => { return (
diff --git a/packages/design-system/ui/src/blocks/data-table/data-table.tsx b/packages/design-system/ui/src/blocks/data-table/data-table.tsx index 489d3eac52..d44e2ad4a2 100644 --- a/packages/design-system/ui/src/blocks/data-table/data-table.tsx +++ b/packages/design-system/ui/src/blocks/data-table/data-table.tsx @@ -14,12 +14,29 @@ import { DataTableToolbar } from "./components/data-table-toolbar" import { DataTableContextProvider } from "./context/data-table-context-provider" import { UseDataTableReturn } from "./use-data-table" +/** + * The props of the `DataTable` component. + */ interface DataTableProps { + /** + * The instance returned by the `useDataTable` hook. + */ instance: UseDataTableReturn + /** + * The children of the component. + */ children?: React.ReactNode + /** + * Additional classes to pass to the wrapper `div` of the component. + */ className?: string } +/** + * This component creates a data table with filters, pagination, sorting, and more. + * It's built on top of the `Table` component while expanding its functionality. + * The `DataTable` is useful to create tables similar to those in the Medusa Admin dashboard. + */ const Root = ({ instance, children, @@ -33,6 +50,7 @@ const Root = ({ ) } +Root.displayName = "DataTable" const DataTable = Object.assign(Root, { Table: DataTableTable,