@upbound/monarch-blocks 0.4.1 → 0.6.0

package/dist/data-table.d.ts

@@ -1,8 +1,10 @@
 import * as React$1 from 'react';
 import { ReactNode, Dispatch, SetStateAction, ComponentType } from 'react';
 import { RowData, ColumnFilter, Cell, Column, ColumnOrderState, Row, ColumnDef, CellContext, HeaderGroup, TableOptions, TableState, InitialTableState, SortingFn, FilterFn, ExpandedState, ColumnFiltersState, PaginationState, SortingState, VisibilityState, ColumnPinningState, GroupingState, OnChangeFn, ColumnSizingState } from '@tanstack/react-table';
-import { DropdownMenuItem, IconName } from '@upbound/monarch-core';
+import { DropdownMenuItem } from '@upbound/monarch-core';
 import { f as CelFilterSchema, g as CelFilterTree, k as CompileResult, i as CelRestrictedOptionSelectPayload } from './types-BULiU2qC.js';
+import { T as TableDataState, a as DataTableEmptyView } from './empty-view-DO36LNvk.js';
+export { D as DataTableEmptyConfig, d as defaultEmptyConfig, b as defaultErrorConfig, c as defaultNoFilterFoundConfig } from './empty-view-DO36LNvk.js';
 
 /** A single entry (or nested submenu) in a cell's contextual right-click menu, alongside the built-in "Filter by this value" item. */
 type ContextualMenuAction<TData extends RowData = RowData, TValue = unknown> = {
@@ -77,9 +79,8 @@ type DataTableValueCellProps = {
 /**
  * A generic cell renderer: a link (when `href` is set), a dashed-underline
  * value with a hover tooltip (when `title` is set), or plain content — with
- * an em-dash placeholder when `content` is empty. Legacy injected its router
- * `Link` via a DI hook (`useLink()`); Monarch has no such layer, so the link
- * branch renders a plain `<a>`.
+ * an em-dash placeholder when `content` is empty. Consumers who need router
+ * navigation wrap their own router link with `Link asChild` at the call site.
  */
 declare function DataTableValueCell({ content, title, className, href, onClick }: DataTableValueCellProps): React$1.JSX.Element;
 /** A timestamp cell — relative time in the cell, absolute time on hover (via Monarch's `RelativeTime`); an em-dash when absent. */
@@ -87,180 +88,6 @@ declare function TimestampCell({ timestamp }: {
     timestamp?: Date | string | number;
 }): React$1.JSX.Element;
 
-/**
- * Non-CEL column filter definitions — the `meta.filter` vocabulary consumed by
- * contextual (right-click cell) filtering and by the plain filter bar.
- * Mirrors TableWrapper's `Filters/types.ts` shapes; `id` is omitted here since
- * it comes from the owning `ColumnDef.id`, not the filter definition itself.
- */
-type ColumnFilterType = 'checkbox' | 'radio' | 'dateRange' | 'text' | 'multiText';
-type ColumnFilterOption = {
-    label: string;
-    value: string;
-    disabled?: boolean;
-    children?: ColumnFilterOption[];
-};
-type FetchColumnFilterOptionsArgs = {
-    query: string;
-    page: number;
-    signal: AbortSignal;
-};
-type FetchColumnFilterOptionsResult = {
-    items: ColumnFilterOption[];
-    hasMore: boolean;
-};
-type FetchColumnFilterOptions = (args: FetchColumnFilterOptionsArgs) => Promise<FetchColumnFilterOptionsResult>;
-type ColumnFilterBase = {
-    title: string;
-    type: ColumnFilterType;
-    order?: number;
-};
-type StaticCheckboxColumnFilter = ColumnFilterBase & {
-    type: 'checkbox';
-    options: string[] | ColumnFilterOption[];
-    fetchFilterOptions?: never;
-    /** Whether the chip's value popup is a searchable Combobox. Defaults to `true`. */
-    searchable?: boolean;
-};
-type AsyncCheckboxColumnFilter = ColumnFilterBase & {
-    type: 'checkbox';
-    fetchFilterOptions: FetchColumnFilterOptions;
-    options?: never;
-    /** Whether the chip's value popup is a searchable Combobox. Defaults to `true`. */
-    searchable?: boolean;
-};
-type CheckboxColumnFilter = StaticCheckboxColumnFilter | AsyncCheckboxColumnFilter;
-type RadioColumnFilter = ColumnFilterBase & {
-    type: 'radio';
-    options: string[] | ColumnFilterOption[];
-    /** Whether the chip's value popup is a searchable Combobox. Defaults to `true`. */
-    searchable?: boolean;
-};
-type DateRangeColumnFilter = ColumnFilterBase & {
-    type: 'dateRange';
-    /** When true, always show time inputs. When false, never show them. When omitted, auto-detect from value. */
-    includeTime?: boolean;
-};
-type TextColumnFilter = ColumnFilterBase & {
-    type: 'text';
-    placeholder?: string;
-};
-type MultiTextColumnFilter = ColumnFilterBase & {
-    type: 'multiText';
-    /** Defaults to comma (`,`) when omitted. */
-    delimiter?: string;
-    description?: string;
-    placeholder?: string;
-};
-type ColumnFilterDefinition = CheckboxColumnFilter | DateRangeColumnFilter | RadioColumnFilter | TextColumnFilter | MultiTextColumnFilter;
-type CheckboxColumnFilterValue = string[] | undefined;
-type RadioColumnFilterValue = string | undefined;
-type DateRangeColumnFilterValue = {
-    startDate: Date | null;
-    endDate: Date | null;
-} | undefined;
-type TextColumnFilterValue = string | undefined;
-type MultiTextColumnFilterValue = string[] | undefined;
-type ColumnFilterValue = CheckboxColumnFilterValue | RadioColumnFilterValue | DateRangeColumnFilterValue | TextColumnFilterValue | MultiTextColumnFilterValue;
-
-/** Derives a contextual (right-click cell) column-filter value from a cell. */
-type ContextualFilterValueParser<TData extends RowData, TValue> = (cell: Cell<TData, TValue>) => ColumnFilterValue | undefined;
-/** Derives a contextual (right-click cell) global-search term from a cell. */
-type ContextualGlobalSearchValueParser<TData extends RowData, TValue> = (cell: Cell<TData, TValue>) => string | undefined;
-/** A fixed-width grid track: sizes to content or an explicit CSS length. */
-type GridColumnFixed = {
-    fixed: string;
-    flex?: never;
-};
-type GridColumnFlexContentMin = {
-    min: 'max-content' | 'min-content';
-    minCap?: string;
-};
-type GridColumnFlexFixedMin = {
-    min?: string;
-    minCap?: never;
-};
-/** A proportional grid track: shares space by weight, with optional min/max. */
-type GridColumnFlex = {
-    flex: number;
-    max?: string;
-    fixed?: never;
-} & (GridColumnFlexContentMin | GridColumnFlexFixedMin);
-/**
- * Column sizing for grid layout mode.
- *
- * Fixed column (sizes to content or explicit value):
- *   { fixed: 'max-content' }
- *   { fixed: '200px' }
- *
- * Proportional column (shares space by weight, with optional min/max):
- *   { flex: 2, min: '100px' }
- *   { flex: 0.5, min: 'max-content' }
- *   { flex: 0.5, min: 'max-content', minCap: '200px' }
- *   { flex: 1, min: '80px', max: '500px' }
- */
-type GridColumnSizing = GridColumnFixed | GridColumnFlex;
-/**
- * Column-def metadata `DataTable` reads — a straight port of TableWrapper's
- * `ColumnMeta` module augmentation. Import this file for its side effect
- * (`import '@/lib/data-table/table-meta'`) wherever a `ColumnDef` is authored
- * with any of these fields.
- */
-declare module '@tanstack/react-table' {
-    interface ColumnMeta<TData extends RowData, TValue> {
-        /** Pins the column left or right. Pinned columns are excluded from column reordering. */
-        pinning?: 'left' | 'right';
-        /** Marks an actions column — hides its header label and excludes it from contextual filtering. */
-        actions?: boolean;
-        /** The column's non-CEL filter definition, read by the plain filter bar and contextual filtering. */
-        filter?: ColumnFilterDefinition;
-        /** Parses a cell into a filter value for contextual (right-click) cell filtering. */
-        contextualFilterValue?: ContextualFilterValueParser<TData, TValue>;
-        /** Parses a cell into a search term for contextual (right-click) global search. */
-        contextualGlobalSearchValue?: ContextualGlobalSearchValueParser<TData, TValue>;
-        /** When true, the column is used only for filtering and is never rendered in the table. */
-        filterOnly?: boolean;
-        /** Column sizing for `layout="grid"` mode — see `GridColumnSizing`. */
-        grid?: GridColumnSizing;
-    }
-}
-
-type TableDataState = 'empty' | 'loading' | 'error' | 'success';
-
-/**
- * Monarch-native equivalent of TableWrapper's `EmptyConfig` — same four
- * states (error / empty / filtered-empty), rebuilt on Monarch's `Empty`
- * compound API instead of a single props-driven component. Two deliberate
- * adaptations: `icon` takes a Monarch `IconName` (no FontAwesome dependency),
- * and `action` is a rendered node rather than a `ComponentType` reference.
- * `details` has no native `Empty` slot — it composes `Alert` instead.
- */
-type DataTableEmptyConfig = {
-    icon?: IconName;
-    header?: React$1.ReactNode;
-    subheader?: React$1.ReactNode;
-    details?: React$1.ReactNode;
-    action?: React$1.ReactNode;
-    className?: string;
-    wrapperClassName?: string;
-};
-declare const defaultErrorConfig: DataTableEmptyConfig;
-declare const defaultEmptyConfig: DataTableEmptyConfig;
-declare const defaultNoFilterFoundConfig: DataTableEmptyConfig;
-type DataTableEmptyView = {
-    empty?: DataTableEmptyConfig;
-    error?: DataTableEmptyConfig;
-    filter?: DataTableEmptyConfig;
-};
-declare function DataTableEmptyView({ emptyView, tableState, filterCount, resetFilters, className, }: {
-    emptyView?: DataTableEmptyView;
-    /** `'success'`/`'loading'` render nothing here — the table body handles those. */
-    tableState: TableDataState;
-    filterCount: number;
-    resetFilters: () => void;
-    className?: string;
-}): React$1.JSX.Element;
-
 type RowCountRelation = 'eq' | 'gt';
 /** Pass `true` for defaults, `false` to disable the footer entirely (handled by the caller, not this component), or an object to toggle individual parts. */
 type DataTablePaginationConfig = boolean | {
@@ -385,6 +212,16 @@ interface TableHookOptions<TData extends RowData> extends Omit<TableOptions<TDat
     enablePagination?: boolean;
     rowCountRelation?: RowCountRelation;
 }
+/**
+ * Configures the "Filter" toolbar toggle that shows/hides the filter row
+ */
+type DataTableFilterVisibilityConfig = {
+    /** Controlled visibility. Omit for an uncontrolled toggle (DataTable owns the state). */
+    visible?: boolean;
+    onVisibleChange?: (visible: boolean) => void;
+    /** Initial visibility when uncontrolled. @default false */
+    defaultVisible?: boolean;
+};
 /** Wires the CEL filter builder into the filter row in place of plain column filters. */
 type DataTableCelFilterConfig<TData extends RowData> = {
     schema: CelFilterSchema;
@@ -479,6 +316,22 @@ interface DataTableProps<TData extends RowData> {
     stickyHeader?: StickyHeaderConfig;
     /** When set, renders the CEL filter builder in the filter row instead of column filters. */
     celFilterConfig?: DataTableCelFilterConfig<TData>;
+    /**
+     * Controls the "Filter" toggle button in the toolbar, immediately to the left of
+     * `ActionsComponent`, that shows/hides the filter row (CEL filter bar or plain
+     * `ViewFilter`) without touching filter state — only the row's presence changes.
+     * The toggle renders by default (whether this prop is omitted or set to `true`),
+     * with the filter row starting hidden. Pass an object for a controlled toggle
+     * (e.g. to persist the preference in the consumer) or to change the uncontrolled
+     * initial state via `defaultVisible`. Pass `false` to disable the toggle entirely
+     * and always show the filter row whenever filtering is enabled — the pre-toggle
+     * behavior.
+     *
+     * The button never renders if there's nothing to filter — no column has a
+     * `meta.filter` and no `celFilterConfig` is set — or if `disableFilters` is
+     * `true`, regardless of this prop's value.
+     */
+    filterVisibility?: boolean | DataTableFilterVisibilityConfig;
 }
 
 /**
@@ -488,7 +341,7 @@ interface DataTableProps<TData extends RowData> {
  * difference is that columns, headers, rows, cells, and menus render through
  * Monarch's own primitives instead of legacy's hand-rolled ones.
  */
-declare function DataTable<TData extends RowData>({ id, config, title, description, emptyView, showError, className, fitContent, loading, renderSkeletonCell, serverSidePagination, ActionsComponent: Actions, onRowRender, renderExpandedRow, expanded: parentExpanded, onExpandedChange: parentOnExpandedChange, disableSearch, disableFilters, disableSorting, paginationConfig, disableColumnReordering, disableColumnVisibility, disableColumnResizing, disableColumnPinning, searchTerm: parentGlobalFilter, onSearchTermChange: parentSetGlobalFilter, filters: parentColumnFilters, onFiltersChange: parentSetColumnFilters, pagination: parentPagination, onPaginationChange: parentSetPagination, sorting: parentSorting, onSortingChange: parentSetSorting, columnOrdering: parentColumnOrdering, onColumnOrderingChange: parentSetColumnOrdering, columnVisibility: parentColumnVisibility, onColumnVisibilityChange: parentSetColumnVisibility, columnPinning: parentColumnPinning, onColumnPinningChange: parentSetColumnPinning, grouping: parentGrouping, onGroupingChange: parentSetGrouping, celFilterClassName, showContextualFilter, onContextCell, contextualMenuActions, layout, initialColumnSizing, onColumnSizingPersist, stickyHeader, celFilterConfig, }: DataTableProps<TData>): React$1.JSX.Element;
+declare function DataTable<TData extends RowData>({ id, config, title, description, emptyView, showError, className, fitContent, loading, renderSkeletonCell, serverSidePagination, ActionsComponent: Actions, onRowRender, renderExpandedRow, expanded: parentExpanded, onExpandedChange: parentOnExpandedChange, disableSearch, disableFilters, disableSorting, paginationConfig, disableColumnReordering, disableColumnVisibility, disableColumnResizing, disableColumnPinning, searchTerm: parentGlobalFilter, onSearchTermChange: parentSetGlobalFilter, filters: parentColumnFilters, onFiltersChange: parentSetColumnFilters, pagination: parentPagination, onPaginationChange: parentSetPagination, sorting: parentSorting, onSortingChange: parentSetSorting, columnOrdering: parentColumnOrdering, onColumnOrderingChange: parentSetColumnOrdering, columnVisibility: parentColumnVisibility, onColumnVisibilityChange: parentSetColumnVisibility, columnPinning: parentColumnPinning, onColumnPinningChange: parentSetColumnPinning, grouping: parentGrouping, onGroupingChange: parentSetGrouping, celFilterClassName, showContextualFilter, onContextCell, contextualMenuActions, layout, initialColumnSizing, onColumnSizingPersist, stickyHeader, celFilterConfig, filterVisibility, }: DataTableProps<TData>): React$1.JSX.Element;
 
 type ViewFilterProps<TData extends RowData> = {
     columns: Column<TData, unknown>[];
@@ -508,4 +361,4 @@ type ViewFilterProps<TData extends RowData> = {
  */
 declare function ViewFilter<TData extends RowData>({ columns, columnFilters, onColumnFiltersChange, className, }: ViewFilterProps<TData>): React$1.JSX.Element;
 
-export { CellContextualFilter, type CellContextualFilterProps, ColumnOptions, type ColumnOptionsProps, type ContextualMenuAction, DataTable, DataTableBody, type DataTableCelFilterConfig, DataTableCell, type DataTableEmptyConfig, DataTableEmptyView, DataTableExpandedRow, DataTableGroupRow, DataTableHeader, DataTablePagination, type DataTablePaginationConfig, type DataTablePaginationProps, type DataTableProps, DataTableRow, type DataTableRowProps, DataTableSkeletonBody, DataTableValueCell, type DataTableValueCellProps, ExpandButton, RowActionItem, RowActions, type RowCountRelation, type StickyHeaderConfig, type TableHookOptions, type TableLayout, TimestampCell, ViewFilter, type ViewFilterProps, defaultEmptyConfig, defaultErrorConfig, defaultNoFilterFoundConfig, getActionsColumnDefinition, getExpandColumnDefinition, normalizePageSizeOptions };
+export { CellContextualFilter, type CellContextualFilterProps, ColumnOptions, type ColumnOptionsProps, type ContextualMenuAction, DataTable, DataTableBody, type DataTableCelFilterConfig, DataTableCell, DataTableEmptyView, DataTableExpandedRow, type DataTableFilterVisibilityConfig, DataTableGroupRow, DataTableHeader, DataTablePagination, type DataTablePaginationConfig, type DataTablePaginationProps, type DataTableProps, DataTableRow, type DataTableRowProps, DataTableSkeletonBody, DataTableValueCell, type DataTableValueCellProps, ExpandButton, RowActionItem, RowActions, type RowCountRelation, type StickyHeaderConfig, type TableHookOptions, type TableLayout, TimestampCell, ViewFilter, type ViewFilterProps, getActionsColumnDefinition, getExpandColumnDefinition, normalizePageSizeOptions };