@commercelayer/app-elements 7.12.0 → 7.13.0

package/dist/ui/resources/useResourceFilters/FiltersSearchBar.d.ts

@@ -1,7 +1,7 @@
 import { JSX } from 'react';
 import { SearchBarProps } from '../../composite/SearchBar';
 import { FiltersInstructions } from './types';
-export interface FilterSearchBarProps extends Pick<SearchBarProps, "placeholder" | "debounceMs"> {
+export interface FilterSearchBarProps extends Pick<SearchBarProps, "placeholder" | "debounceMs" | "variant"> {
     /**
      * Array of instruction items to build the filters behaviors
      */
@@ -31,7 +31,7 @@ export interface FilterSearchBarProps extends Pick<SearchBarProps, "placeholder"
      */
     predicateWhitelist: string[];
 }
-declare function FiltersSearchBar({ instructions, placeholder, onUpdate, queryString, predicateWhitelist, debounceMs, }: FilterSearchBarProps): JSX.Element;
+declare function FiltersSearchBar({ instructions, placeholder, onUpdate, queryString, predicateWhitelist, debounceMs, variant, }: FilterSearchBarProps): JSX.Element;
 declare namespace FiltersSearchBar {
     var displayName: string;
 }

package/dist/ui/resources/useResourceFilters/activeFilters.d.ts

@@ -0,0 +1,111 @@
+import { ListableResourceType } from '@commercelayer/sdk';
+import { formatDateRange } from '../../../helpers/date';
+import { CurrencyRangeFieldValue, FiltersInstructionItem, FiltersInstructions, FormFullValues, UiFilterValue } from './types';
+/**
+ * Shared helpers to read the active filters out of a url query string and turn
+ * them into human readable labels.
+ *
+ * Used by both `FiltersNav` (legacy `ButtonFilter` look) and `FiltersBar`
+ * (metrics-style pills), so label resolution only ever has one implementation.
+ */
+export declare function getInstructionItemByFilterPredicate({ instructions, filterPredicate, }: {
+    instructions: FiltersInstructions;
+    filterPredicate: string;
+}): FiltersInstructionItem | undefined;
+/**
+ * Get label for user defined ButtonFilter component by reading the `instructionItem` object.
+ * If the filter has options and only one value is selected, the label will be the option label.
+ * Otherwise, the label will be the filter group label plus the number of selected values.
+ */
+export declare function getButtonFilterLabel({ values, instructionItem, }: {
+    values: string | string[];
+    instructionItem: FiltersInstructionItem;
+}): string;
+export declare function extractCurrencyRangeFilterValues({ activeFilters, instructions, }: {
+    activeFilters: Array<[string, UiFilterValue]>;
+    instructions: FiltersInstructions;
+}): Array<[string, CurrencyRangeFieldValue]>;
+/**
+ * Checks if a filter predicate belongs to a currency range filter
+ * by checking the instructions
+ */
+export declare function predicateBelongsToCurrencyRange({ filterPredicate, instructions, }: {
+    filterPredicate: string;
+    instructions: FiltersInstructions;
+}): boolean;
+export declare function makeCurrencyRangeFilterButtonLabel(value: CurrencyRangeFieldValue): string;
+/**
+ * Resolves every selected value to its option label and joins them.
+ *
+ * Unlike {@link getButtonFilterLabel}, which collapses multiple values into a
+ * counter (`Markets · 2`), this spells them all out (`Europe, Italy`) because a
+ * pill already shows the filter name separately.
+ */
+export declare function formatPillFilterValue({ values, instructionItem, }: {
+    values: string | string[];
+    instructionItem: FiltersInstructionItem;
+}): string;
+/**
+ * Compares two filter values ignoring array wrapping and ordering, so that
+ * `"placed"`, `["placed"]` and `["placed"]` in a different order all match.
+ * Range values (objects) are compared as-is.
+ */
+export declare function isSameFilterValue(a: unknown, b: unknown): boolean;
+export interface PillFilter {
+    /**
+     * Predicate of the filter, or `timePreset` for the time range.
+     * Used as react key and to know what to reset when removing the pill.
+     */
+    id: string;
+    /** Filter group label, e.g. `Payment status`. */
+    label: string;
+    /**
+     * Formatted value(s), e.g. `Paid, Authorized`.
+     * `undefined` when it has to be resolved by fetching the resource, see `fetch`.
+     */
+    value?: string;
+    /**
+     * Set for filters backed by a resource (`inputResourceGroup`, `inputSelect`),
+     * whose labels live on the resources themselves and have to be retrieved.
+     */
+    fetch?: {
+        resource: ListableResourceType;
+        ids: string[];
+        fieldForLabel: string;
+        fieldForValue: string;
+    };
+    /** Which reset strategy the remove button has to apply. */
+    kind: "group" | "timeRange";
+}
+/**
+ * Reads the url query string and returns one descriptor per active filter, ready
+ * to be rendered as a pill.
+ *
+ * Filters matching `defaultValues` are omitted: on a page where the current view
+ * (e.g. a tab) already implies a set of filters, only the user's additions are
+ * worth showing as removable pills.
+ *
+ * The free text filter is always omitted, since it is already visible in the
+ * search bar, and so are hidden filters and `viewTitle`.
+ */
+export declare function getPillFilters({ instructions, queryString, predicateWhitelist, defaultValues, timezone, locale, }: {
+    instructions: FiltersInstructions;
+    queryString: string;
+    predicateWhitelist: string[];
+    defaultValues?: FormFullValues;
+    timezone?: string;
+    locale?: Parameters<typeof formatDateRange>[0]["locale"];
+}): PillFilter[];
+/**
+ * Form values to apply when clearing all the filters at once.
+ *
+ * Hidden filters, `viewTitle` and the free text search are preserved — they are
+ * not represented as pills, so wiping them would be an invisible side effect.
+ * Everything else goes back to `defaultValues` (empty when not provided).
+ */
+export declare function getClearedFormValues({ instructions, queryString, predicateWhitelist, defaultValues, }: {
+    instructions: FiltersInstructions;
+    queryString: string;
+    predicateWhitelist: string[];
+    defaultValues?: FormFullValues;
+}): FormFullValues;

package/dist/ui/resources/useResourceFilters/activeFilters.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ui/resources/useResourceFilters/types.d.ts

@@ -138,6 +138,32 @@ export type FilterItemOptions = BaseFilterItem & {
          * props required for the UI component
          */
         props: Omit<InputResourceGroupProps, "onChange" | "defaultValues" | "title">;
+    } | {
+        /**
+         * UI component to render: a select dropdown, matching the style of the
+         * dashboard metrics filters. Prefer it over `inputResourceGroup` when the
+         * options are many, since it searches server-side instead of showing a
+         * checkbox list with a "see all" overlay.
+         */
+        component: "inputSelect";
+        /**
+         * props required for the UI component
+         */
+        props: Pick<InputResourceGroupProps, "resource" | "fieldForLabel" | "fieldForValue" | "searchBy" | "sortBy" | "filters" | "hideWhenSingleItem"> & {
+            /**
+             * How many options to load upfront. Capped at 25 by the Core API, which
+             * is why `searchBy` should be set when more options exist.
+             * @default 25
+             */
+            limit?: number;
+            placeholder?: string;
+            isClearable?: boolean;
+            /**
+             * Filter predicates are usually `_in`, so multiple values are expected.
+             * @default true
+             */
+            isMulti?: boolean;
+        };
     };
 };
 export interface FilterItemTextSearch extends Omit<BaseFilterItem, "sdk"> {

package/dist/ui/resources/useResourceFilters/useResourceFilters.d.ts

@@ -1,7 +1,11 @@
 import { ListableResourceType, QueryFilter } from '@commercelayer/sdk';
+import { SearchBarProps } from '../../composite/SearchBar';
 import { UseResourceListConfig } from '../useResourceList';
 import { ResourceListProps } from '../useResourceList/useResourceList';
+import { ResourceTableProps, UseResourceTableConfig } from '../useResourceTable/types';
 import { makeFilterAdapters } from './adapters';
+import { FiltersBarProps } from './FiltersBar';
+import { FiltersDrawerProps } from './FiltersDrawer';
 import { FiltersFormProps } from './FiltersForm';
 import { FiltersNavProps } from './FiltersNav';
 import { FiltersInstructions } from './types';
@@ -29,8 +33,34 @@ interface UseResourceFiltersHook {
      * Helper methods to transform filters from/to url query string, sdk and form values
      */
     adapters: ReturnType<typeof makeFilterAdapters>;
+    /**
+     * Search bar with the filters button on the right and the applied filters
+     * rendered as removable pills below.
+     *
+     * Clicking the filters button opens the drawer rendered by `FiltersDrawer`,
+     * unless an `onFilterClick` prop is provided.
+     *
+     * @example
+     * ```jsx
+     * const { FiltersBar, FiltersDrawer, FilteredTable } = useResourceFilters({ instructions })
+     *
+     * <FiltersBar queryString={queryString} onUpdate={onUpdate} />
+     * <FilteredTable type='orders' columns={columns} />
+     * <FiltersDrawer onUpdate={onUpdate} />
+     * ```
+     */
+    FiltersBar: (props: FiltersBarProps) => React.ReactNode;
+    /**
+     * Side drawer with the filters form, opened by the `FiltersBar` filters button.
+     * Render it once per page as a sibling of `FiltersBar`.
+     */
+    FiltersDrawer: (props: FiltersDrawerProps) => React.ReactNode;
     /**
      * Search bar component with filters navigation buttons
+     *
+     * @deprecated Use `FiltersBar` together with `FiltersDrawer` instead, they
+     * render the search bar and the filters as pills in the style used by the
+     * dashboard. This component will be removed in a future major release.
      */
     SearchWithNav: (props: Pick<FiltersNavProps, "onFilterClick" | "queryString"> & {
         /**
@@ -44,6 +74,11 @@ interface UseResourceFiltersHook {
          * @default 'Search...'
          */
         searchBarPlaceholder?: string;
+        /**
+         * Visual variant of the search bar. Use `outline` to match the style used
+         * in the dashboard (metrics) pages.
+         */
+        searchBarVariant?: SearchBarProps["variant"];
         /**
          * Milliseconds to wait before triggering the search bar callback
          * @default 500
@@ -65,6 +100,19 @@ interface UseResourceFiltersHook {
         };
         hideTitle?: boolean;
     }) => React.ReactNode;
+    /**
+     * Filtered ResourceTable component based on current active filters.
+     * Table sibling of `FilteredList`: renders a column-model data table wired
+     * to the active search/filters and pagination.
+     */
+    FilteredTable: <TResource extends ListableResourceType>(props: Omit<UseResourceTableConfig<TResource>, "query" | "metricsQuery"> & ResourceTableProps & {
+        query?: Omit<NonNullable<UseResourceTableConfig<TResource>["query"]>, "filters">;
+        metricsQuery?: Omit<NonNullable<UseResourceTableConfig<TResource>["metricsQuery"]>, "filter"> & {
+            /** Filters need to be configured within the `useResourceFilters` options. */
+            filter?: never;
+        };
+        hideTitle?: boolean;
+    }) => React.ReactNode;
     /**
      * SDK filters object to be used in the sdk query
      */

package/dist/ui/resources/useResourceList/adaptMetricsOrderToCore.d.ts

@@ -70,5 +70,10 @@ export interface MetricsResourceOrder {
         first_name?: string;
         last_name?: string;
     };
+    customer?: {
+        id?: string;
+        email?: string;
+        total_orders_count?: number;
+    };
 }
 export declare function adaptMetricsOrderToCore(metricsOrder: MetricsResourceOrder): Order;

package/dist/ui/resources/useResourceList/listFetcher.d.ts

@@ -12,11 +12,17 @@ export interface FetcherResponse<TResource> {
         cursor?: string | null;
     };
 }
-export declare function listFetcher<TResource extends ListableResourceType>({ currentData, resourceType, client, clientType, query, mode, pageNumber, }: {
+export declare function listFetcher<TResource extends ListableResourceType>({ currentData, resourceType, client, clientType, query, mode, pageNumber, cursor, }: {
     currentData?: FetcherResponse<Resource<TResource>>;
     resourceType: TResource;
     mode?: "infinite" | "pagination";
     pageNumber?: number;
+    /**
+     * Metrics API only: the cursor that opens the requested page. Used in
+     * `pagination` mode, where the caller keeps track of one cursor per page
+     * (the metrics API can only move forward on its own).
+     */
+    cursor?: string | null;
 } & ({
     client: CommerceLayerBundle;
     clientType: "coreSdkClient";

package/dist/ui/resources/useResourceList/useResourceList.d.ts

@@ -79,7 +79,9 @@ export type UseResourceListConfig<TResource extends ListableResourceType> = {
     preProcess?: (list: Array<Resource<TResource>>) => Array<Resource<TResource>>;
     /**
      * Pagination type: 'infinite' for infinite scrolling (default), 'pagination' for classic prev/next pagination.
-     * Note: 'pagination' mode is only supported for Core API (not Metrics API).
+     * Works with both the Core API and the Metrics API. Since the Metrics API is
+     * cursor-based, prev/next works by remembering the cursor that opens each
+     * visited page; arbitrary page jumps are not possible there.
      */
     paginationType?: "infinite" | "pagination";
     /**

package/dist/ui/resources/useResourceTable/index.d.ts

@@ -0,0 +1,2 @@
+export type { ResourceTableColumn, ResourceTableProps, ResourceTableSort, UseResourceTableConfig, UseResourceTableReturn, } from './types';
+export { useResourceTable } from './useResourceTable';

package/dist/ui/resources/useResourceTable/types.d.ts

@@ -0,0 +1,182 @@
+import { ListableResourceType } from '@commercelayer/sdk';
+import { FC, ReactNode } from 'react';
+import { SectionProps } from '../../atoms/Section';
+import { Resource } from '../useResourceList/listFetcher';
+import { UseResourceListConfig } from '../useResourceList/useResourceList';
+/**
+ * A single column definition for a `ResourceTable`.
+ *
+ * This is app-elements' own column type: TanStack Table is an implementation
+ * detail and its `ColumnDef` is intentionally not exposed here (see
+ * `docs/adr/0001-encapsulate-tanstack-table.md`).
+ */
+export interface ResourceTableColumn<TResource extends ListableResourceType> {
+    /**
+     * Header content. A plain string or any node (icon, tooltip, …).
+     */
+    header: ReactNode;
+    /**
+     * Cell renderer for this column. Receives the fetched resource for the row
+     * and returns whatever should be displayed in the cell.
+     */
+    cell: (props: {
+        resource: Resource<TResource>;
+    }) => ReactNode;
+    /**
+     * Stable, unique column id.
+     * When omitted it falls back to `sortBy`, then to a positional `col-<index>`.
+     * Provide one explicitly when two columns would otherwise collide.
+     */
+    id?: string;
+    /**
+     * Horizontal alignment applied to both the header and the cells.
+     * @default 'left'
+     */
+    align?: "left" | "right" | "center";
+    /**
+     * Optional CSS class applied to the column header, typically for width
+     * control (e.g. `"w-1/2"`).
+     */
+    width?: string;
+    /**
+     * Hide this column below the given breakpoint; it is shown at that width and
+     * up. These are app-elements' own breakpoints (see `styles/global.css`, which
+     * resets Tailwind's defaults): `md` 768px, `lg` 992px, `xl` 1280px. There is
+     * deliberately no `sm`.
+     *
+     * Common cases: `"md"` hides on mobile (shown on tablet + desktop), `"lg"`
+     * shows on desktop only. The column's data is still fetched; only its
+     * rendering is suppressed via CSS, so there is no layout shift on resize.
+     */
+    hideBelow?: "md" | "lg" | "xl";
+    /**
+     * When set, the column becomes sortable and this value is the CommerceLayer
+     * SDK sort attribute it sorts by (e.g. `"created_at"`).
+     *
+     * Sorting is server-side: clicking the header drives the SDK `sort` query
+     * param and refetches. Rows are never reordered client-side.
+     */
+    sortBy?: string;
+}
+/**
+ * SDK sort expression, e.g. `"created_at"` (asc) or `"-created_at"` (desc).
+ * `undefined` means no explicit table sort is applied.
+ */
+export type ResourceTableSort = string | undefined;
+export type UseResourceTableConfig<TResource extends ListableResourceType> = Omit<UseResourceListConfig<TResource>, "metricsQuery" | "query"> & {
+    /** The columns to render, in display order. */
+    columns: Array<ResourceTableColumn<TResource>>;
+    /**
+     * SDK query object, excluding `pageNumber` (handled internally) and
+     * `sort` (owned by the table's sorting state — set the initial sort with
+     * `sort` instead).
+     */
+    query?: Omit<NonNullable<UseResourceListConfig<TResource>["query"]>, "sort">;
+    /**
+     * When set, data is fetched from the Metrics API instead of the Core API.
+     *
+     * Sorting still works: a column's `sortBy` is sent as the metrics
+     * `search.sort_by` (so use metrics attribute names, e.g. `"order.placed_at"`)
+     * together with the matching `search.sort` direction — omit `search.sort_by`
+     * here and let the table own it.
+     */
+    metricsQuery?: {
+        search: {
+            limit?: number;
+            fields?: string[];
+        };
+        /**
+         * Metrics filters. When the table is rendered through
+         * `useResourceFilters`' `FilteredTable`, this is injected from the active
+         * filters and must not be set here.
+         */
+        filter?: Record<string, unknown>;
+    };
+    /**
+     * Optional row-level click handler. When provided the whole row becomes
+     * interactive (hover affordance + click). Use it to navigate with your
+     * app's router.
+     *
+     * The click event is passed as second argument, so it can be forwarded to
+     * helpers that need it (e.g. `navigateTo(...).onClick`).
+     */
+    onRowClick?: (resource: Resource<TResource>, event: React.MouseEvent<HTMLElement>) => void;
+    /**
+     * Return an href to make each row a real link (rendered as a stretched
+     * anchor over the row). This enables native link behavior — cmd/ctrl/middle
+     * click opens the row in a new tab, and the URL shows on hover.
+     *
+     * Combine with `onRowClick` for client-side navigation: a plain click calls
+     * `onRowClick` (and suppresses the default navigation), while modified
+     * clicks fall through to the browser. Return `undefined` to leave a row
+     * non-navigable.
+     *
+     * Note: avoid interactive elements in the first column when using this — the
+     * stretched anchor sits over the row (in-cell controls would need their own
+     * `relative`/`z-10` to stay clickable).
+     */
+    getRowHref?: (resource: Resource<TResource>) => string | undefined;
+    /**
+     * Controlled sort value (SDK sort expression, e.g. `"-created_at"`).
+     * Pass together with `onSortChange` to own the sort state (e.g. persist it
+     * in the URL). When omitted the table manages sort internally.
+     */
+    sort?: ResourceTableSort;
+    /**
+     * Called when the user changes the sort. Provide together with `sort` for
+     * controlled mode; the callback receives the new SDK sort expression (or
+     * `undefined` when sorting is cleared).
+     */
+    onSortChange?: (sort: ResourceTableSort) => void;
+    /**
+     * Initial sort used only when the table manages sort internally
+     * (uncontrolled). Ignored when `sort`/`onSortChange` are provided.
+     */
+    defaultSort?: ResourceTableSort;
+};
+/** Props of the `ResourceTable` component returned by the hook. */
+export interface ResourceTableProps {
+    /** Title. Can be a node or a function receiving the record count. */
+    title?: ((recordCount: number | undefined) => ReactNode) | ReactNode;
+    /** Action button rendered next to the title. */
+    actionButton?: SectionProps["actionButton"];
+    /**
+     * Rendered when the table has no rows.
+     * When omitted, a default message based on the resource name is shown.
+     */
+    emptyState?: ReactNode;
+    /** Force the title size. Defaults to `normal`. */
+    titleSize?: SectionProps["titleSize"];
+    /** `boxed` wraps the table in a bordered card. */
+    variant?: "boxed";
+    /**
+     * How the table behaves when its content is wider than the container.
+     * - `"fit"` (default): the table fills the container width; columns share the
+     *   available space (and wrap/shrink). Pair with `hideBelow` on columns to
+     *   drop low-value columns on small screens.
+     * - `"scroll"`: the table keeps its natural (unwrapped) width and scrolls
+     *   horizontally inside its own container; the title/action button stay fixed.
+     * @default 'fit'
+     */
+    layout?: "fit" | "scroll";
+}
+export interface UseResourceTableReturn<TResource extends ListableResourceType> {
+    /** The component that renders the data table. */
+    ResourceTable: FC<ResourceTableProps>;
+    /** Prev/next pagination controls. Renders `null` unless in `pagination` mode with more than one page. */
+    Pagination: FC;
+    /** The rows currently displayed (current page, or accumulated in infinite mode). */
+    list?: Array<Resource<TResource>>;
+    /** SDK pagination metadata. */
+    meta?: import('../useResourceList/listFetcher').FetcherResponse<Resource<TResource>>["meta"];
+    isLoading: boolean;
+    isFirstLoading: boolean;
+    error?: string;
+    /** Removes a row from the UI only (call after a successful delete API call). */
+    removeItem: (resourceId: string) => void;
+    /** Clears fetched data and refetches from the first page. */
+    refresh: () => void;
+    hasMorePages?: boolean;
+    /** The active sort (SDK sort expression), whether controlled or internal. */
+    sort: ResourceTableSort;
+}

package/dist/ui/resources/useResourceTable/useResourceTable.d.ts

@@ -0,0 +1,11 @@
+import { ListableResourceType } from '@commercelayer/sdk';
+import { UseResourceTableConfig, UseResourceTableReturn } from './types';
+/**
+ * `useResourceTable` fetches a CommerceLayer resource type and renders it as a
+ * data table driven by a column model, backed by TanStack Table v9.
+ *
+ * It reuses `useResourceList`'s fetch/pagination layer verbatim and only
+ * replaces item rendering with a TanStack-driven table. Sorting, filtering,
+ * search and pagination are all resolved server-side.
+ */
+export declare function useResourceTable<TResource extends ListableResourceType>(config: UseResourceTableConfig<TResource>): UseResourceTableReturn<TResource>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/app-elements",
-  "version": "7.12.0",
+  "version": "7.13.0",
   "type": "module",
   "license": "MIT",
   "files": [
@@ -38,6 +38,7 @@
     "@commercelayer/sdk": "8.0.0-beta.11",
     "@date-fns/tz": "^1.5.0",
     "@monaco-editor/react": "~4.7.0",
+    "@tanstack/react-table": "^9.0.0",
     "@types/lodash-es": "^4.17.12",
     "@types/react": "19.2.13",
     "@types/react-datepicker": "^7.0.0",