@persona/design-system 0.9.1 → 0.10.0

package/dist/DataTable-fZ7SNbIH.d.mts

@@ -0,0 +1,439 @@
+import { t as Pagination } from "./Pagination-COcFWlha.mjs";
+import { i as BaseFilterConfig, n as AttributeColumn, s as FilterConfig } from "./types-Dx8PgO8a.mjs";
+import { n as TableControlsProps, t as TableControls } from "./TableControls-UfObf-ZN.mjs";
+import { C as RowAction, O as SortProps, _ as DataTableColumns, l as DataTableColumnFormat, t as BulkAction } from "./types-CjQzH0MM.mjs";
+import { t as RenderFormatFn } from "./useTableColumns-rLskKJhd.mjs";
+import { ComponentProps } from "react";
+import * as _$styled_components0 from "styled-components";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+import { ColumnFiltersState, RowData } from "@tanstack/react-table";
+
+//#region components/DataTable/DataTable.d.ts
+declare module '@tanstack/react-table' {
+  interface ColumnMeta<TData extends RowData, TValue> {
+    align?: 'left' | 'right';
+    format?: {
+      type: string;
+    };
+    minWidth?: number;
+    width?: number;
+    headerTooltip?: React.ReactNode;
+  }
+}
+declare const StyledDataTableControls: _$styled_components0.StyledComponent<(<TFilter extends BaseFilterConfig = FilterConfig>({
+  filters,
+  filterResolver,
+  filterPanel,
+  searchProps,
+  defaultShowFilters,
+  showFilters: controlledShowFilters,
+  setShowFilters: controlledSetShowFilters,
+  className,
+  tableActions,
+  propertiesButton,
+  isLoading,
+  isFilterPanelLoading,
+  showViews,
+  canEditViews,
+  onSelectView,
+  views,
+  hiddenViewIds,
+  currentView,
+  onAddView,
+  onViewNameChange,
+  onReorderViews,
+  onViewHiddenChange,
+  onDuplicateView,
+  onDeleteView,
+  onSaveView,
+  onSetDefaultView,
+  onUnsetDefaultView,
+  isViewDirty,
+  selectedRows,
+  bulkActions,
+  onClearSelection,
+  title,
+  presetViews,
+  compact,
+  columnConfigurationProps,
+  showFiltersAlways,
+  onError,
+  "data-tour-target": dataTourTarget
+}: TableControlsProps<TFilter>) => _$react_jsx_runtime0.JSX.Element), any, {}, never>;
+declare const DataTableControls: typeof StyledDataTableControls & typeof TableControls;
+declare const DataTableContainer: _$styled_components0.StyledComponent<"div", any, {
+  $stickyHeader: boolean;
+}, never>;
+declare const FloatingActionBarContainer: _$styled_components0.StyledComponent<"div", any, {}, never>;
+type ClientPaginationProps = {
+  clientPagination: true;
+  pageSize?: number;
+  pageSizeOptions?: number[];
+};
+interface DataTableProps<TData extends RowData, TFilter extends BaseFilterConfig = FilterConfig> {
+  /**
+   * Data to render.
+   * If a row has a _details property that is a function, it will be called
+   * with the row data as props.
+   * If a row has a _details property that is a React node, it will be rendered as is.
+   */
+  data: TData[];
+  /**
+   * Columns to display in the table. May be a string or column config object.
+   *
+   * Strings get converted from camelCase to Start Case.
+   */
+  columns: DataTableColumns<TData, DataTableColumnFormat<TData>>;
+  /**
+   * Component to render details for expandable rows.
+   * Useful if we want to render the same details component for every row.
+   * Receives rowData as props.
+   */
+  detailComponent?: React.ComponentType<{
+    rowData: TData;
+  }>;
+  /**
+   * When `'always'`, the leading expand column is shown even if no rows are expandable.
+   * When `'auto'`, the column is omitted unless at least one row can expand. Rows that
+   * cannot expand keep an empty spacer in this column so labels stay aligned.
+   */
+  expandColumnVisibility?: 'auto' | 'always';
+  /**
+   * Whether to display table controls such as search, filters, views, and selection
+   */
+  showControls?: boolean;
+  /**
+   * Props to pass to the TableControls component
+   */
+  controls?: TableControlsProps<TFilter>;
+  /**
+   * Custom text to display when the table is empty. Will default to "No results found"
+   */
+  emptyState?: {
+    title?: string;
+    description?: string;
+  };
+  /**
+   * Whether to display pagination controls. If true, will use client-side pagination. If an object,
+   * can be either advanced configuration of cleitn paginaton or server-side pagination state..
+   */
+  pagination?: boolean | ClientPaginationProps | ComponentProps<typeof Pagination>;
+  /**
+   * Whether to display sort controls. If true, will use client-side sorting. If an object, will use server-side sorting.
+   */
+  sort?: boolean | SortProps;
+  /**
+   * Whether to display the column properties button and popover. Allows control of column visiblity and ordering.
+   */
+  showColumnProperties?: boolean;
+  /**
+   * Whether to enable sorting removal. If true, will allow sorting to be removed by clicking the sort control.
+   */
+  enableSortingRemoval?: boolean;
+  /**
+   * Set to true to sort descending first, which is the case for most of our tables.
+   */
+  sortDescFirst?: boolean;
+  /**
+   * Called when column visibility or ordering is updated. Useful for saving column properties.
+   */
+  onUpdateColumnProperties?: (newConfiguration: AttributeColumn[]) => void;
+  /**
+   * Whether the table is loading data
+   */
+  isLoading?: boolean;
+  /**
+   * Whether to enable row selection
+   */
+  enableRowSelection?: boolean;
+  /**
+   * Whether to enable automatic sub row selection when a parent row is selected
+   */
+  enableSubRowSelection?: boolean;
+  /**
+   * Define the row id for the given row. Used by row selection and bulk actions.
+   */
+  getRowId?: (row: TData) => string;
+  /**
+   * Define the aria label for the given row.
+   */
+  getRowLabel?: (row: TData) => string;
+  /**
+   * Determine if a row can be selected. Used to disable row selection for specific rows.
+   */
+  getRowSelectable?: (row: TData) => boolean;
+  /**
+   * Makes the row link cell an anchor if provided. Get link for the given row.
+   */
+  getLinkToRow?: (row: TData) => string;
+  /**
+   * If set, each row will be a link to the given prefix + the row's `id` value.
+   * `getLinkToRow` will override this.
+   */
+  rowLinkPrefix?: string;
+  /**
+   * Column id whose cell contains the row link when `getLinkToRow`/`rowLinkPrefix` is set.
+   * Defaults to the first visible non-feature column (not select/expand/action). URL-formatted
+   * columns are skipped.
+   */
+  rowLinkColumnId?: string;
+  /**
+   * Component to use for row links. Defaults to the PDS router-aware link.
+   * Pass a custom component (e.g. Next.js Link) to use a different router.
+   * The component renders as an inline anchor inside the link cell and receives `to`,
+   * `className`, and `children`.
+   */
+  rowLinkComponent?: React.ElementType;
+  /**
+   * Whether to show the compact variant of the table.
+   * Compact tables do not support views.
+   */
+  compact?: boolean;
+  /**
+   * Disables the row hover highlight. Use for read-only, non-interactive tables where the
+   * hover background would misleadingly imply rows are selectable or clickable.
+   */
+  disableRowHover?: boolean;
+  /**
+   * Title to display in the table.
+   */
+  title?: string;
+  /**
+   * Whether to make the table header sticky when scrolling vertically.
+   * When enabled, the controls and table header will remain visible at the top of the viewport while scrolling through table data.
+   * Note that the sticky header styling assumes this component is contained within a parent with `display: flex` and `flex-direction: column`.
+   */
+  stickyHeader?: boolean;
+  /**
+   * Enable client-side search functionality.
+   * Pass an object to configure the search input.
+   */
+  clientSearch?: boolean | {
+    placeholder?: string;
+    initialValue?: string;
+  };
+  /**
+   * Controlled search term for client-side search.
+   * When provided, the search input becomes controlled.
+   * Use with onSearchTermChange to manage search state externally.
+   */
+  searchTerm?: string;
+  /**
+   * Called when the search term changes (for controlled search).
+   * Only used when searchTerm prop is provided.
+   */
+  onSearchTermChange?: (searchTerm: string) => void;
+  /**
+   * Whether to use manual filtering. If true, will not use the global filter function 'includesString'.
+   */
+  manualFiltering?: boolean;
+  /**
+   * Controlled expanded row IDs.
+   * When provided, row expansion becomes controlled.
+   * Use with onExpandedRowsChange to manage expansion state externally.
+   */
+  expandedRowIds?: Set<string>;
+  /**
+   * Called when expanded rows change (for controlled expansion).
+   * Only used when expandedRowIds prop is provided.
+   */
+  onExpandedRowsChange?: (expandedRowIds: Set<string>) => void;
+  /**
+   * Enable client-side filtering functionality.
+   * Users must explicitly define filter types for columns in TableControls.
+   */
+  clientFiltering?: boolean;
+  /**
+   * @internal Not part of the public API surface.
+   * Used exclusively by the DashboardDataTable wrapper to share TanStack column-filter
+   * state with the dashboard's generateClientFilters adapter.
+   * Pass only via the wrapper's any-cast spread — do not use directly.
+   * @deprecated Prefer `column.filter` for defining client-side filters.
+   */
+  columnFilters?: ColumnFiltersState;
+  /**
+   * When true, the empty-state message will read "No results found. Try changing your filters."
+   * even when the DataTable's own filter state is empty.
+   * Use this when the host manages active server-side filters outside the DataTable
+   * (e.g. via an injected filterPanel) so the conditional empty state still reflects those filters.
+   */
+  hasExternalActiveFilters?: boolean;
+  /**
+   * Called when the column-level filter state changes.
+   * Use this to drive an injected filter-panel UI from outside the DataTable,
+   * e.g. to feed `generateClientFilters` with the current TanStack filter state.
+   */
+  onColumnFiltersChange?: (filters: ColumnFiltersState) => void;
+  /**
+   * Host-provided cell format renderer.
+   * The PDS built-in handles string, number, date, datetime, url, sticker, image, id, and pii.
+   * Pass a custom renderer to handle additional application-specific formats (e.g. tags, files,
+   * status indicators) or to override PDS defaults.
+   */
+  renderFormat?: RenderFormatFn<TData, DataTableColumnFormat<TData>>;
+  /**
+   * Actions to display in each table row.
+   * Can be a static array (same actions for all rows) or a function that
+   * receives the row data and returns actions specific to that row.
+   */
+  rowActions?: RowAction[] | ((row: TData) => RowAction[]);
+  /**
+   * Bulk actions to display when there are selected rows.
+   * For standard variant, actions will be shown in the table controls.
+   * For compact variant, actions will be shown in a floating action bar.
+   * If bulkActions are provided in `controls.bulkActions`, they will override the bulkActions prop.
+   */
+  bulkActions?: BulkAction[];
+  /**
+   * Function that returns available bulk actions based on selected rows.
+   * This allows dynamic bulk actions that change based on the selection.
+   * Takes precedence over static bulkActions prop.
+   */
+  getAvailableBulkActions?: (selectedRows: TData[]) => BulkAction[];
+  /**
+   * Callback fired when the set of selected rows changes.
+   * Receives the currently selected row data objects.
+   */
+  onRowSelectionChange?: (selectedRows: TData[]) => void;
+  /**
+   * If present, will display a thin row between rows as UI affordance to add a new row.
+   * The row will be added after the row identified by the provided rowId, and the addAsChild flag will
+   * indicate if the added row will be a sibling or a child of the referenced row
+   * Adding said row will be handled by this `onAddRow` callback.
+   */
+  onAddRow?: (rowId: string, addAsChild: boolean) => void;
+  /**
+   * Called to determine if a row can be added after the provided row.
+   * If not provided, assume true.
+   * If this resolves to false, we will hide the inserter row.
+   */
+  canAddAfterRow?: (row: TData, addAsChild: boolean) => boolean;
+  /**
+   * Called when a row is clicked. If provided, rows will have cursor pointer
+   * and clicking a row will call this function with the row id.
+   * When omitted, rows that can expand (via `_details` or `detailComponent`) toggle expand/collapse on row click.
+   */
+  onRowClick?: (rowId: string) => void;
+  /**
+   * The active row id. If provided, the row will be in an active state.
+   */
+  activeRowId?: string;
+  /**
+   * Called with the ordered ids of the rows currently displayed, reflecting
+   * client-side search, filtering, and sorting. Lets a parent step through the
+   * on-screen order (e.g. prev/next navigation in a detail panel).
+   */
+  onDisplayedRowIdsChange?: (rowIds: string[]) => void;
+  /**
+   * Custom left offset in pixels to add to all pinned columns.
+   * Useful when the table is nested inside containers that need additional spacing.
+   */
+  pinnedColumnLeftOffset?: number;
+  /**
+   * When false, the table does not scroll horizontally on its own and an ancestor is expected
+   * to. Set this when a host scrolls the table and positions its header or pinned columns
+   * against that ancestor, so those offsets are not trapped in the table's own scrollport.
+   * Combining this with `stickyHeader` is contradictory: `stickyHeader` gives the table an
+   * inner scrollport of its own, which is the thing this prop gives up.
+   */
+  scrollsHorizontally?: boolean;
+  /**
+   * Custom content to render inside the floating action bar, between the
+   * selection count and the action buttons. Only rendered when the floating
+   * action bar is visible (compact mode with selected rows).
+   */
+  floatingBarContent?: React.ReactNode;
+}
+/**
+ * The DataTable component is the core of Persona's table experiences.
+ *
+ * This component implements `@tanstack/react-table` and exposes a simplified, easy to use API.
+ *
+ * Planned functionality
+ * - Column visibility, reordering
+ * - Row selection
+ * - Cell types (e.g. links, buttons, Stickers)
+ *
+ * Client-side support
+ * - ✅ Sorting
+ * - ✅ Search (enable with clientSearch prop)
+ * - ✅ Pagination
+ * - ✅ Filtering (requires explicit filter configuration in TableControls)
+ *
+ * Server-side support
+ * - ✅ Sorting
+ * - ✅ Filtering
+ * - ✅ Pagination
+ *
+ * @example
+ * // Basic usage with client-side search
+ * <DataTable
+ *   data={data}
+ *   columns={columns}
+ *   showControls={true}
+ *   clientSearch={{ placeholder: "Search accounts..." }}
+ * />
+ *
+ * @example
+ * // Column-level search control
+ * const columns = [
+ *   { accessor: 'id', header: 'ID', searchable: false },
+ *   { accessor: 'name', header: 'Name' }, // searchable by default
+ *   { accessor: 'email', header: 'Email' },
+ * ];
+ */
+declare const DataTable: <TData extends RowData, TFilter extends BaseFilterConfig = FilterConfig>({
+  data,
+  columns,
+  detailComponent,
+  expandColumnVisibility,
+  showControls,
+  controls,
+  emptyState,
+  isLoading,
+  pagination,
+  sort,
+  sortDescFirst,
+  enableSortingRemoval,
+  showColumnProperties,
+  onUpdateColumnProperties,
+  enableRowSelection,
+  enableSubRowSelection,
+  getRowId,
+  getRowLabel,
+  getRowSelectable,
+  getLinkToRow,
+  rowLinkPrefix,
+  rowLinkColumnId,
+  rowLinkComponent,
+  compact,
+  disableRowHover,
+  title,
+  clientSearch,
+  searchTerm: controlledSearchTerm,
+  onSearchTermChange,
+  manualFiltering,
+  expandedRowIds: controlledExpandedRowIds,
+  onExpandedRowsChange,
+  clientFiltering,
+  columnFilters: controlledColumnFilters,
+  hasExternalActiveFilters,
+  onColumnFiltersChange,
+  renderFormat,
+  rowActions,
+  bulkActions,
+  getAvailableBulkActions,
+  onRowSelectionChange,
+  onAddRow,
+  stickyHeader,
+  canAddAfterRow,
+  onRowClick,
+  activeRowId,
+  onDisplayedRowIdsChange,
+  pinnedColumnLeftOffset,
+  scrollsHorizontally,
+  floatingBarContent
+}: DataTableProps<TData, TFilter>) => _$react_jsx_runtime0.JSX.Element;
+//#endregion
+export { FloatingActionBarContainer as a, DataTableProps as i, DataTableContainer as n, DataTableControls as r, DataTable as t };
+//# sourceMappingURL=DataTable-fZ7SNbIH.d.mts.map