@commercelayer/app-elements 7.13.0 → 7.14.0

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

@@ -147,15 +147,30 @@ export type FilterItemOptions = BaseFilterItem & {
          */
         component: "inputSelect";
         /**
-         * props required for the UI component
+         * props required for the UI component.
+         *
+         * Either a fixed list of `options` — statuses, kinds, anything the app
+         * already knows — or a `resource` the options are fetched from.
          */
-        props: Pick<InputResourceGroupProps, "resource" | "fieldForLabel" | "fieldForValue" | "searchBy" | "sortBy" | "filters" | "hideWhenSingleItem"> & {
+        props: ({
+            /**
+             * The options to choose from. An option can be hidden from the UI
+             * and still be accepted in the query, e.g. a status that is only
+             * ever set through a predefined link.
+             */
+            options: Array<{
+                label: string;
+                value: string;
+                isHidden?: boolean;
+            }>;
+        } | (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;
             /**
@@ -212,6 +227,15 @@ export type FiltersInstructionItem = FilterItemOptions | FilterItemTextSearch |
 export type FiltersInstructions = FiltersInstructionItem[];
 export declare function isItemOptions(item: FiltersInstructionItem): item is FilterItemOptions;
 export declare function isTextSearch(item: FiltersInstructionItem): item is FilterItemTextSearch;
+/**
+ * The predicate of the free text filter shown in the search bar, if any.
+ *
+ * Not simply the first `textSearch` instruction: apps also declare `textSearch`
+ * items for predicates they only want whitelisted (hidden ones driving tabs, for
+ * instance), and those can come first. There is at most one `searchBar` in a set
+ * of instructions, so this is unambiguous.
+ */
+export declare function getSearchBarPredicate(instructions: FiltersInstructions): string | undefined;
 export declare function isCurrencyRange(item: FiltersInstructionItem): item is FilterItemCurrencyRange;
 export declare function isGroupedPredicates(item: FiltersInstructionItem): item is FilterItemGroupedPredicates;
 /**

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

@@ -27,3 +27,13 @@ export declare function getActiveFilterCountFromUrl({ includeTextSearch, instruc
     queryString: string;
 }): number;
 export declare function getAllowedValuesFromItemOptions(instructionItem: FilterItemOptions): string[] | undefined;
+/**
+ * Whether an `options` filter holds a single value rather than a list.
+ *
+ * Two components can be single-valued and they say so differently: a toggle
+ * button through `mode`, a select through `isMulti`. Anything reading a filter
+ * value has to know which, so the value can be unwrapped from the array the URL
+ * always parses into — a predicate like `archived_at_null` expects `"hide"`,
+ * not `["hide"]`.
+ */
+export declare function isSingleValueOptionsItem(instructionItem: FilterItemOptions): boolean;

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

@@ -1 +1,2 @@
+export { refreshResourceLists, removeFromResourceLists, } from './resourceListSignals';
 export { type ResourceListItemTemplateProps, type ResourceListProps, type UseResourceListConfig, useResourceList, } from './useResourceList';

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

@@ -0,0 +1,46 @@
+import { ListableResourceType } from '@commercelayer/sdk';
+/**
+ * What a mounted list is being asked to do.
+ * - `removeItem` drops a single row without any request
+ * - `refresh` refetches from the first page
+ */
+type ResourceListSignal = {
+    kind: "removeItem";
+    resourceId: string;
+} | {
+    kind: "refresh";
+};
+type ResourceListSubscriber = (signal: ResourceListSignal) => void;
+/**
+ * Subscribe a mounted list to the signals for a resource type.
+ * Called by `useResourceList`; returns the unsubscribe function.
+ */
+export declare function subscribeToResourceLists(type: ListableResourceType, subscriber: ResourceListSubscriber): () => void;
+/**
+ * Drop a row from every mounted list of the given resource type, with no
+ * request. Call it right after a successful delete.
+ *
+ * Needed when the component that deletes is not the one rendering the list —
+ * typically a details drawer rendered as a sibling of the list, which leaves the
+ * list mounted, so it would otherwise keep showing the deleted row until the
+ * page is reloaded. Lists that do not hold the row ignore the signal, and the
+ * total record count is adjusted for those that do.
+ *
+ * @example
+ * await sdkClient.stock_items.delete(stockItem.id)
+ * removeFromResourceLists("stock_items", stockItem.id)
+ */
+export declare function removeFromResourceLists(type: ListableResourceType, resourceId: string): void;
+/**
+ * Refetch every mounted list of the given resource type from the first page.
+ *
+ * Prefer `removeFromResourceLists` after a delete: it is instant, and it neither
+ * flashes the loading skeleton nor renumbers an infinite list mid-scroll. Reach
+ * for this one when rows were created or edited elsewhere and the list content
+ * can no longer be patched locally.
+ *
+ * A signal emitted while no list is mounted is a no-op — which is harmless,
+ * since a list fetches on mount anyway.
+ */
+export declare function refreshResourceLists(type: ListableResourceType): void;
+export {};

package/dist/ui/resources/useResourceList/resourceListSignals.integration.test.d.ts

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

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

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

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

@@ -1,4 +1,4 @@
-import { ListableResourceType } from '@commercelayer/sdk';
+import { ListableResourceType, ResourceSortFields } from '@commercelayer/sdk';
 import { FC, ReactNode } from 'react';
 import { SectionProps } from '../../atoms/Section';
 import { Resource } from '../useResourceList/listFetcher';
@@ -34,35 +34,97 @@ export interface ResourceTableColumn<TResource extends ListableResourceType> {
      */
     align?: "left" | "right" | "center";
     /**
-     * Optional CSS class applied to the column header, typically for width
-     * control (e.g. `"w-1/2"`).
+     * What the column holds. Sets its width — as a share of the table, so it stays
+     * liquid — plus alignment and truncation, from one scale shared by every app
+     * (see `columnKindClassName`). Leave it off for the column that should absorb
+     * the leftover space: the name, email or SKU the row is about.
+     *
+     * Prefer this over `width`: it is what keeps a status column the same size in
+     * every app, and it makes the loading and loaded tables identical, since the
+     * widths no longer depend on the cell content.
+     */
+    kind?: ResourceTableColumnKind;
+    /**
+     * Escape hatch for a width `kind` cannot express, as a CSS class applied to
+     * the column header (e.g. `"w-1/2"`). Overrides the `kind` width.
+     *
+     * Note the table lays out with `table-layout: fixed`, so a class means what it
+     * says: a column narrower than its content clips rather than growing.
      */
     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
+     * When this column starts being shown, overriding the default.
+     *
+     * By default a table shows only its first column on mobile — a phone has room
+     * for what the row is about and little else — and everything else from `md` up.
+     * Set this to widen or narrow that:
+     *
+     * - `"lg"` / `"xl"` — appear later than the default (a low-value column)
+     * - `"never"` — always visible, mobile included. For the one column that is the
+     *   point of the table: a stock item's quantity, a price, a gift card balance.
+     *
+     * 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.
+     * The column's data is still fetched either way; only its rendering is
+     * suppressed, via CSS, so nothing shifts on resize.
      */
-    hideBelow?: "md" | "lg" | "xl";
+    hideBelow?: "md" | "lg" | "xl" | "never";
     /**
-     * When set, the column becomes sortable and this value is the CommerceLayer
-     * SDK sort attribute it sorts by (e.g. `"created_at"`).
+     * When set, the column becomes sortable and this value is the attribute it
+     * sorts by (e.g. `"created_at"`).
+     *
+     * Only attributes the API can actually sort by are accepted: the type is the
+     * resource's own sortable set, taken from the SDK (see `SortableAttribute`).
+     * Attributes reached through a relationship (`sku.code`, a market's name) are
+     * not sortable, so those columns stay static.
+     *
+     * On a `metricsQuery` table the value is a Metrics attribute instead
+     * (`"order.placed_at"`) — see `MetricsAttribute`.
      *
-     * Sorting is server-side: clicking the header drives the SDK `sort` query
-     * param and refetches. Rows are never reordered client-side.
+     * Sorting is server-side: the attribute goes into the SDK `sort` query param and
+     * the list refetches. Rows are never reordered client-side.
+     *
+     * Declaring it does not make the header interactive — table headers are inert.
+     * It marks the column as sortable and names the attribute, which is what a sort
+     * control outside the table reads to build its options.
      */
-    sortBy?: string;
+    sortBy?: SortableAttribute<TResource> | MetricsAttribute;
 }
+/**
+ * The kinds of column a resource table has, each with a width, an alignment and
+ * a truncation rule. Deliberately a short list: the point is that a status column
+ * is the same width in every app, which only holds if apps pick from a scale
+ * rather than sizing columns one by one.
+ *
+ * `text` is for the secondary strings a row carries — a market, a stock location,
+ * a customer, an origin. Without it they would split the leftover space evenly
+ * with the column the row is actually about, which is rarely what you want.
+ */
+export type ResourceTableColumnKind = "text" | "code" | "status" | "datetime" | "amount" | "count" | "actions";
+/**
+ * The attributes the API can sort a given resource by, straight from the SDK's
+ * `ResourceSortFields`. Every resource adds the shared `id`, `reference`,
+ * `reference_origin`, `created_at` and `updated_at` to its own set.
+ *
+ * This is the single source of truth for whether a column can be sortable: the
+ * API rejects anything else, and computed values (a status derived from several
+ * timestamps, a relationship's name) are not in it by definition.
+ */
+export type SortableAttribute<TResource extends ListableResourceType> = Extract<keyof ResourceSortFields[TResource], string>;
+/**
+ * A Metrics API sort attribute, always namespaced by its entity
+ * (`"order.placed_at"`). Metrics has its own attribute names, outside the SDK's
+ * resource types, so these can only be checked by shape — the dot is what tells
+ * them apart from a Core attribute.
+ */
+export type MetricsAttribute = `${string}.${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 ResourceTableSort<TResource extends ListableResourceType = ListableResourceType> = SortableAttribute<TResource> | `-${SortableAttribute<TResource>}` | MetricsAttribute | `-${MetricsAttribute}` | undefined;
 export type UseResourceTableConfig<TResource extends ListableResourceType> = Omit<UseResourceListConfig<TResource>, "metricsQuery" | "query"> & {
     /** The columns to render, in display order. */
     columns: Array<ResourceTableColumn<TResource>>;
@@ -121,18 +183,18 @@ export type UseResourceTableConfig<TResource extends ListableResourceType> = Omi
      * 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;
+    sort?: ResourceTableSort<TResource>;
     /**
-     * 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).
+     * Called when the sort changes. 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;
+    onSortChange?: (sort: ResourceTableSort<TResource>) => void;
     /**
      * Initial sort used only when the table manages sort internally
      * (uncontrolled). Ignored when `sort`/`onSortChange` are provided.
      */
-    defaultSort?: ResourceTableSort;
+    defaultSort?: ResourceTableSort<TResource>;
 };
 /** Props of the `ResourceTable` component returned by the hook. */
 export interface ResourceTableProps {
@@ -178,5 +240,13 @@ export interface UseResourceTableReturn<TResource extends ListableResourceType>
     refresh: () => void;
     hasMorePages?: boolean;
     /** The active sort (SDK sort expression), whether controlled or internal. */
-    sort: ResourceTableSort;
+    sort: ResourceTableSort<TResource>;
+    /**
+     * Sets the sort, for a control outside the table to drive — a field + direction
+     * picker, say. Table headers are inert (see `sortBy`).
+     *
+     * In controlled mode (`sort` + `onSortChange`) this calls `onSortChange` rather
+     * than holding state of its own.
+     */
+    setSort: (sort: ResourceTableSort<TResource>) => void;
 }

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/app-elements",
-  "version": "7.13.0",
+  "version": "7.14.0",
   "type": "module",
   "license": "MIT",
   "files": [
@@ -61,6 +61,7 @@
     "react-select": "^5.10.2",
     "react-toastify": "^11.1.0",
     "react-tooltip": "^5.30.1",
+    "stable-hash": "^0.0.6",
     "swr": "^2.4.2",
     "ts-invariant": "^0.10.3",
     "type-fest": "^5.7.0",
@@ -101,8 +102,8 @@
     "wouter": "^3.x"
   },
   "scripts": {
-    "build": "tsc && vite build && pnpm build:css-vendor && pnpm build:tailwind-cfg",
-    "build:tailwind-cfg": "cp ./src/styles/global.css ./dist/tailwind.global.css",
+    "build": "tsc && vite build && pnpm build:css-vendor",
+    "build:watch": "pnpm dlx concurrently@10 --kill-others --names vendor,lib --prefix-colors cyan,magenta \"pnpm build:css-vendor --watch\" \"APP_ELEMENTS_WATCH=true vite build --watch\"",
     "build:css-vendor": "pnpm dlx @tailwindcss/cli -i ./src/styles/vendor.css -o ./dist/vendor.css --minify",
     "check": "pnpm biome check",
     "check:fix": "pnpm biome check --write",

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

@@ -1,8 +0,0 @@
-import { default as React, JSX } from 'react';
-interface VisibilityTriggerProps extends React.HTMLAttributes<HTMLDivElement> {
-    rootMargin?: string;
-    callback: (entry: IntersectionObserverEntry) => void;
-    enabled: boolean;
-}
-export declare function VisibilityTrigger({ rootMargin, enabled, callback, ...rest }: VisibilityTriggerProps): JSX.Element;
-export {};