@commercelayer/app-elements 7.13.0 → 7.15.0

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

@@ -3,6 +3,14 @@ import { EditMetadataOverlayProps } from '../../../hooks/useEditMetadataOverlay'
 interface MetadataOverlay extends Omit<EditMetadataOverlayProps, "resourceId" | "resourceType"> {
 }
 export interface ResourceMetadataProps {
+    /**
+     * How the block renders, overriding what it infers from where it sits.
+     *
+     * Inferred by default — `PageLayout`'s sidebar slot reports `"sidebar"`, while a
+     * page and a drawer both report the wider `"default"`. Pass it only to force a
+     * rendering the surrounding surface would not choose.
+     */
+    variant?: "default" | "sidebar";
     resourceType: ListableResourceType;
     resourceId: string;
     /**
@@ -18,6 +26,7 @@ export declare const isUpdatableType: (value: any) => value is UpdatableType;
  * More in detail the `metadata` attribute is a JSON object, customizable for several purposes, and this component will allow to show and manage its keys with a simple (string kind) values.
  */
 export declare const ResourceMetadata: import('../../atoms/SkeletonTemplate').SkeletonTemplateComponent<{
+    variant?: "default" | "sidebar" | undefined;
     resourceType: ListableResourceType;
     resourceId: string;
     overlay?: MetadataOverlay | undefined;

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

@@ -1,9 +1,28 @@
 import { ListableResourceType } from '@commercelayer/sdk';
 import { EditTagsOverlayProps } from '../../hooks/useEditTagsOverlay';
-type TaggableResource = Extract<ListableResourceType, "addresses" | "bundles" | "coupons" | "customers" | "gift_cards" | "line_items" | "line_item_options" | "order_subscriptions" | "orders" | "buy_x_pay_y_promotions" | "external_promotions" | "fixed_amount_promotions" | "fixed_price_promotions" | "flex_promotions" | "free_gift_promotions" | "free_shipping_promotions" | "percentage_discount_promotions" | "returns" | "shipments" | "shipping_methods" | "sku_options" | "skus">;
+/**
+ * The resources the API can tag, as a value so that a caller can ask at runtime —
+ * `ResourceAdminBlocks` leaves the block out for a stock item or an import.
+ *
+ * The SDK declares an `isTaggable()` helper and a `taggableResources` array in its
+ * types but ships neither in its build, so calling them typechecks and then throws.
+ * Hence our own list, checked against `ListableResourceType` by `satisfies`.
+ */
+export declare const taggableResources: readonly ["addresses", "bundles", "coupons", "customers", "gift_cards", "line_items", "line_item_options", "order_subscriptions", "orders", "buy_x_pay_y_promotions", "external_promotions", "fixed_amount_promotions", "fixed_price_promotions", "flex_promotions", "free_gift_promotions", "free_shipping_promotions", "percentage_discount_promotions", "returns", "shipments", "shipping_methods", "sku_options", "skus"];
+export type TaggableResource = (typeof taggableResources)[number];
+/** Whether the API can tag this resource. */
+export declare function isTaggableResource(resourceType: ListableResourceType): resourceType is TaggableResource;
 interface TagsOverlay extends Omit<EditTagsOverlayProps, "resourceId" | "resourceType"> {
 }
 export interface ResourceTagsProps {
+    /**
+     * How the block renders, overriding what it infers from where it sits.
+     *
+     * Inferred by default — `PageLayout`'s sidebar slot reports `"sidebar"`, while a
+     * page and a drawer both report the wider `"default"`. Pass it only to force a
+     * rendering the surrounding surface would not choose.
+     */
+    variant?: "default" | "sidebar";
     resourceType: TaggableResource;
     resourceId: string;
     /**
@@ -19,6 +38,7 @@ export interface ResourceTagsProps {
  * This component generates an all-in-one visualization and editing interface for managing tags relationship of requested resource.
  */
 export declare const ResourceTags: import('../atoms/SkeletonTemplate').SkeletonTemplateComponent<{
+    variant?: "default" | "sidebar" | undefined;
     resourceType: TaggableResource;
     resourceId: string;
     overlay?: TagsOverlay

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

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

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

@@ -0,0 +1,22 @@
+import { JSX } from 'react';
+import { FilterItemOptions, FiltersInstructions } from './types';
+export interface FiltersBarSelectProps {
+    /** The promoted filter, already known to be an `inputSelect` in the bar. */
+    item: FilterItemOptions;
+    instructions: FiltersInstructions;
+    queryString: string;
+    predicateWhitelist: string[];
+    onUpdate: (queryString: string) => void;
+}
+/**
+ * A filter rendered in `FiltersBar` rather than in the drawer.
+ *
+ * It works straight on the query string, as the search bar does: there is no form
+ * around it to submit, so a choice applies immediately. Single-valued — the
+ * trigger has one line to state what the page is showing — while the predicate
+ * stays `_in`, so links shared before the filter was promoted keep working.
+ */
+export declare function FiltersBarSelect({ item, instructions, queryString, predicateWhitelist, onUpdate, }: FiltersBarSelectProps): JSX.Element | null;
+export declare namespace FiltersBarSelect {
+    var displayName: string;
+}

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

@@ -147,15 +147,49 @@ export type FilterItemOptions = BaseFilterItem & {
          */
         component: "inputSelect";
         /**
-         * props required for the UI component
+         * Where the field is rendered.
+         *
+         * `"bar"` promotes it out of the drawer and into `FiltersBar`, as a
+         * fixed-width trigger beside the search field — for the one filter a page
+         * is really read through, such as the price list on prices or the stock
+         * location on inventory. The drawer then skips it, the way it already
+         * skips the search bar: one control, one home.
+         *
+         * A promoted filter produces no pill (the trigger already states it) and
+         * is single-select, so give it `isMulti: false` and a `placeholder` that
+         * reads as the unfiltered state ("All price lists").
+         *
+         * `hidden: true` wins over this: a tab that pins the filter must not leave
+         * a select next to it claiming otherwise.
+         *
+         * @default 'drawer'
          */
-        props: Pick<InputResourceGroupProps, "resource" | "fieldForLabel" | "fieldForValue" | "searchBy" | "sortBy" | "filters" | "hideWhenSingleItem"> & {
+        position?: "bar" | "drawer";
+        /**
+         * 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: ({
+            /**
+             * 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 +246,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/useResourceSelectOptions.d.ts

@@ -0,0 +1,35 @@
+import { InputSelectValue } from '../../forms/InputSelect';
+import { FilterItemOptions } from './types';
+type SelectRender = Extract<FilterItemOptions["render"], {
+    component: "inputSelect";
+}>;
+/** The props of a select whose options come from a resource, not a fixed list. */
+export type ResourceSelectProps = Exclude<SelectRender["props"], {
+    options: unknown;
+}>;
+/** Core caps `pageSize` at 25, so this is also the most we can load in one go. */
+export declare const defaultOptionsLimit = 10;
+export interface ResourceSelectOptions {
+    /** Options to hand to the select: the first page, plus anything selected. */
+    initialValues: InputSelectValue[];
+    /** The first page is still loading. */
+    isLoading: boolean;
+    /** How many records exist in total, once known. */
+    recordCount?: number;
+    /** Whether the labels of the current selection have been resolved. */
+    hasResolvedSelection: boolean;
+    /** Server-side search, when the instruction sets `searchBy`. */
+    loadAsyncValues?: (hint: string) => Promise<InputSelectValue[]>;
+}
+/**
+ * Loads the options of a resource-backed filter select.
+ *
+ * Shared by the two places such a select is rendered — the filters drawer and,
+ * for a filter promoted with `position: "bar"`, the filters bar — so that both
+ * fetch the same way and a value picked in one resolves its label in the other.
+ */
+export declare function useResourceSelectOptions({ props, selectedValues, }: {
+    props: ResourceSelectProps;
+    selectedValues: string[];
+}): ResourceSelectOptions;
+export {};

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

@@ -1,4 +1,4 @@
-import { FilterItemOptions, FiltersInstructions } from './types';
+import { FilterItemOptions, FiltersInstructionItem, FiltersInstructions } from './types';
 /**
  * Show the filter label with the counter for selected options
  * or just the total of available options when nothing is selected
@@ -27,3 +27,20 @@ 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;
+/**
+ * Whether a filter is promoted out of the drawer and into `FiltersBar`.
+ *
+ * `hidden` wins: a tab that pins the predicate must not leave a select in the bar
+ * claiming otherwise.
+ */
+export declare function isBarFilter(instructionItem: FiltersInstructionItem): 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.15.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 {};