@adapttable/mantine 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,226 @@
+import * as react from 'react';
+import { ReactNode, RefObject, DependencyList } from 'react';
+import { BaseDataTableProps, TableSource, UseServerDataOptions, UrlStateAdapter, UseSavedViewsOptions, ActiveFilterChip, FilterDef, TableLabels, UseSavedViewsResult } from '@adapttable/core';
+export { ActionConfirm, ActiveFilterChip, BulkAction, CellProps, ColorScheme, ColumnDef, ConfirmHandler, ConfirmRequest, Direction, ExtraFilters, FilterDef, FilterOption, FilterType, FilterValue, InfiniteQueryLike, PageSelector, PaginatedResponse, PaginationMode, RowAction, SavedView, SortByOption, SortDirection, SortableValue, TableLabels, TableQuery, TableQueryParams, TableSource, UrlStateAdapter, UseBackendDataOptions, UseDataTableResult, UseFrontendDataOptions, UseSavedViewsOptions, UseSavedViewsResult, UseTableUrlStateOptions, UseTableUrlStateResult, createHistoryAdapter, createMemoryAdapter, defaultConfirm, defaultLabels, deriveSortByOptions, getHistoryAdapter, useBackendData, useDataTable, useFrontendData, useSavedViews, useTableUrlState } from '@adapttable/core';
+
+/** Overridable sub-components. Each defaults to a styled Mantine part. */
+interface DataTableSlots {
+    /** Replace the loading skeleton. */
+    skeleton?: ReactNode;
+    /** Replace the empty-state. */
+    empty?: ReactNode;
+}
+/** Per-part class name overrides. */
+interface DataTableClassNames {
+    root?: string;
+    toolbar?: string;
+    table?: string;
+    card?: string;
+    footer?: string;
+}
+/** Props for the Mantine `<DataTable>`. */
+interface DataTableProps<TRow> extends Omit<BaseDataTableProps<TRow>, "source"> {
+    /**
+     * Full-control tier: a prebuilt source (`useFrontendData` /
+     * `useBackendData`). Omit it and pass `data` for the zero-ceremony tiers.
+     */
+    source?: TableSource<TRow>;
+    /**
+     * Frontend tier: the raw rows — the table filters, sorts and pages them.
+     * Combined with `onQueryChange` it becomes the server tier: `data` is the
+     * current page, rendered as-is.
+     */
+    data?: readonly TRow[];
+    /** Server tier: total row count across all pages (drives the pager). */
+    total?: number;
+    /** Server tier: a request is in flight. */
+    loading?: boolean;
+    /**
+     * Server tier: fired with the consolidated query (page, limit, search,
+     * sort, filters) whenever it changes — including once on mount with the
+     * URL-restored values. Fetch in response and hand back `data` + `total`.
+     */
+    onQueryChange?: UseServerDataOptions<TRow>["onQueryChange"];
+    /**
+     * Namespace for this table's URL params (`urlKey="left"` → `left.q`,
+     * `left.page`, …) so multiple tables can share one URL. Applies to the
+     * `data` / `onQueryChange` tiers; a prebuilt `source` owns its own state.
+     */
+    urlKey?: string;
+    /**
+     * URL-state backend for the `data` / `onQueryChange` tiers. Defaults to
+     * the browser History API; supply a router adapter (react-router,
+     * Next.js) — or `createMemoryAdapter()` in tests — to integrate with an
+     * existing navigation stack.
+     */
+    urlAdapter?: UrlStateAdapter;
+    /**
+     * Sync table state (search, sort, page, filters) to the URL. `false`
+     * keeps everything in memory — the table works identically, the address
+     * bar never changes, and any `urlAdapter` is ignored.
+     *
+     * @default true
+     */
+    urlSync?: boolean;
+    /**
+     * Saved views: capture the table's current URL state (search, sort, page,
+     * filters, column layout) under a name and re-apply it on demand. Setting
+     * this renders a Saved-views menu in the toolbar next to the Columns
+     * button. `adapter` / `urlKey` default to the table's own `urlAdapter` /
+     * `urlKey`, so usually only `storageKey` is needed.
+     */
+    savedViews?: UseSavedViewsOptions;
+    /** Replace sub-components (skeleton, empty-state). */
+    slots?: DataTableSlots;
+    /** Per-part class name overrides. */
+    classNames?: DataTableClassNames;
+    /**
+     * Animate rows/cards on mount (dependency-free; honors reduced motion).
+     * Off by default.
+     */
+    animate?: boolean;
+}
+
+/**
+ * Batteries-included Mantine data table. Drop in `columns`, a `rowKey`,
+ * and a data tier — raw `data` (frontend), `data` + `onQueryChange`
+ * (server), or a prebuilt `source` — to get a fully styled, sortable,
+ * filterable, paginated table with selection, bulk actions, RTL, dark
+ * mode, and optional entrance animation.
+ *
+ * @typeParam TRow - The row type.
+ */
+declare function DataTable<TRow>(props: Readonly<DataTableProps<TRow>>): react.JSX.Element;
+
+/** Props for {@link ActiveFilterChips}. */
+interface ActiveFilterChipsProps {
+    /** The chips to render. */
+    chips: readonly ActiveFilterChip[];
+    /** Optional clear-all handler; the link is hidden when omitted. */
+    onClearAll?: () => void;
+    /** Accessible label for the strip. */
+    label: string;
+    /** Clear-all link text. */
+    clearAllLabel: string;
+}
+/** A wrapping strip of removable filter chips. Renders nothing when empty. */
+declare function ActiveFilterChips({ chips, onClearAll, label, clearAllLabel, }: Readonly<ActiveFilterChipsProps>): react.JSX.Element | null;
+
+/** Props for {@link AutoFilterForm}. */
+interface AutoFilterFormProps<TRow> {
+    /** The resolved declarative definitions, in render order. */
+    defs: readonly FilterDef<TRow>[];
+    /** The resolved source whose `extra` bag the controls read and write. */
+    source: TableSource<TRow>;
+    /** Resolved labels — the range widgets read the operator/value strings. */
+    labels: Required<TableLabels>;
+}
+/**
+ * The auto-built filter form: one labeled, Mantine-native control per
+ * declarative {@link FilterDef}. Values live in the source's `extra` bag
+ * (so the URL, chips and — on frontend data — the predicate all follow);
+ * clearing a control writes the empty value, which drops the URL param.
+ * Range types render operator-first: an operator select plus one value
+ * input (two for "Between"), persisted as the inclusive pair.
+ *
+ * @typeParam TRow - The row type.
+ */
+declare function AutoFilterForm<TRow>({ defs, source, labels, }: Readonly<AutoFilterFormProps<TRow>>): react.JSX.Element;
+
+/** Props for {@link EmptyState}. */
+interface EmptyStateProps {
+    /** Headline text. */
+    title: string;
+    /** Optional supporting description. */
+    description?: string;
+    /** Optional custom icon (defaults to an inbox glyph). */
+    icon?: ReactNode;
+    /** Optional call-to-action (e.g. a clear-filters button). */
+    action?: ReactNode;
+}
+/** Centred "nothing to show" placeholder. */
+declare function EmptyState({ title, description, icon, action, }: Readonly<EmptyStateProps>): react.JSX.Element;
+
+/** Props for {@link ErrorState}. */
+interface ErrorStateProps {
+    /** The error to surface. */
+    error: Error;
+    /** Title line. */
+    title: string;
+    /** Supporting message. */
+    message: string;
+    /** Retry button label. */
+    retryLabel: string;
+    /** Optional retry handler; the button is hidden when omitted. */
+    onRetry?: () => void;
+    /** Whether a retry is in flight. */
+    isRetrying?: boolean;
+}
+/** Inline error alert with an optional retry button. */
+declare function ErrorState({ error, title, message, retryLabel, onRetry, isRetrying, }: Readonly<ErrorStateProps>): react.JSX.Element;
+
+/** Props for {@link PaginationFooter}. */
+interface PaginationFooterProps {
+    page: number;
+    totalPages: number;
+    limit: number;
+    total: number;
+    fromIndex: number;
+    toIndex: number;
+    onPageChange: (page: number) => void;
+    onLimitChange: (limit: number) => void;
+    labels: Required<TableLabels>;
+}
+/** Desktop pagination bar: page-size + range on the left, pager on the right. */
+declare function PaginationFooter({ page, totalPages, limit, total, fromIndex, toIndex, onPageChange, onLimitChange, labels, }: Readonly<PaginationFooterProps>): react.JSX.Element;
+
+/** Props for {@link SavedViewsMenu}. */
+interface SavedViewsMenuProps {
+    /** The saved-views state from core's `useSavedViews`. */
+    views: UseSavedViewsResult;
+    /** Resolved table labels (e.g. `table.labels` from `useDataTable`). */
+    labels: Required<TableLabels>;
+}
+/**
+ * Saved-views menu: lists every captured view (click a name to apply it, the
+ * trailing ✕ to delete it) above a save row that captures the table's
+ * CURRENT URL state under the typed name. Pairs with core's `useSavedViews`
+ * and composes into the `toolbar` slot — or let `<DataTable savedViews>`
+ * mount it for you next to the Columns menu.
+ */
+declare function SavedViewsMenu({ views, labels, }: Readonly<SavedViewsMenuProps>): react.JSX.Element;
+
+/** Props for {@link TableSkeleton}. */
+interface TableSkeletonProps {
+    /** Number of placeholder columns. */
+    columns: number;
+    /** Number of placeholder rows. Defaults to 5. */
+    rows?: number;
+    /** Screen-reader text announcing the loading state. */
+    loadingLabel?: string;
+}
+/** Loading placeholder that mirrors the table shape to avoid layout shift. */
+declare function TableSkeleton({ columns, rows, loadingLabel, }: Readonly<TableSkeletonProps>): react.JSX.Element;
+
+/** Tuning for the mount stagger. */
+interface MountStaggerOptions {
+    /** Master switch. When `false`, the hook is a no-op. */
+    enabled: boolean;
+    /** Per-item delay in ms. Defaults to 40. */
+    step?: number;
+    /** Tween duration in ms. Defaults to 320. */
+    duration?: number;
+}
+/**
+ * Dependency-free entrance stagger using the Web Animations API. Animates
+ * descendants marked with `data-stagger` once on mount (and whenever
+ * `deps` change), honoring `prefers-reduced-motion`. Works without GSAP;
+ * GSAP fans can swap in their own hook of the same shape.
+ *
+ * @param ref - Ref to the container whose `[data-stagger]` items animate.
+ * @param deps - Re-run the stagger when these change (e.g. the row set).
+ * @param options - See {@link MountStaggerOptions}.
+ */
+declare function useMountStagger(ref: RefObject<HTMLElement | null>, deps: DependencyList, options: MountStaggerOptions): void;
+
+export { ActiveFilterChips, type ActiveFilterChipsProps, AutoFilterForm, type AutoFilterFormProps, DataTable, type DataTableClassNames, type DataTableProps, type DataTableSlots, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, type MountStaggerOptions, PaginationFooter, type PaginationFooterProps, SavedViewsMenu, type SavedViewsMenuProps, TableSkeleton, type TableSkeletonProps, useMountStagger };