@tallyui/pos 3.4.0 → 3.5.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { Money, TaxRounding, StoreSettings, TallyConnector, SyncContext, StoreSettingsChoice, StoreSettingsChoices, ProductTraits, OrderCreateLine, PaymentMethodKind, CommandServerRefs, CommandWarning, CommandError, ServerCapabilities, OrderCreateEnvelope, RegisterCommandType, RegisterCommandResult, VariantSummary, TraitContext, CommandResult, AnyCommandEnvelope, CommandEnvelope, OrderCreatePayload, RegisterCommandEnvelope } from '@tallyui/core';
+import { Money, TaxRounding, StoreSettings, TallyConnector, SyncContext, StoreSettingsChoice, StoreSettingsChoices, ProductTraits, ProductCategory, TraitContext, OrderCreateLine, PaymentMethodKind, CommandServerRefs, CommandWarning, CommandError, ServerCapabilities, OrderCreateEnvelope, RegisterCommandType, RegisterCommandResult, VariantSummary, CommandResult, AnyCommandEnvelope, CommandEnvelope, OrderCreatePayload, RegisterCommandEnvelope } from '@tallyui/core';
 export { getProductStock, withStockOverlay } from '@tallyui/core';
 export { countFresh, readFresh, watchFresh } from '@tallyui/core/rxdb';
 import * as rxdb from 'rxdb';
@@ -618,6 +618,53 @@ declare function buildReceiptData(order: SentOrder, config: ReceiptConfig): Rece
  */
 declare function searchProducts<Doc>(docs: Doc[], term: string, traits: ProductTraits<Doc>): Doc[];
 
+/** The product's categories: `getCategories`, else `getCategoryNames` with each name as its id. */
+declare function productCategories<Doc>(doc: Doc, traits: ProductTraits<Doc>): ProductCategory[];
+/** Every category across `docs`, once per id (the first name seen wins), sorted by name (natural, case-insensitive), ties by id. */
+declare function listCategories<Doc>(docs: readonly Doc[], traits: ProductTraits<Doc>): ProductCategory[];
+/** Whether `doc` is in the category with this id. */
+declare function inCategory<Doc>(doc: Doc, categoryId: string, traits: ProductTraits<Doc>): boolean;
+
+/** A sort on one field: ascending or descending. */
+interface ProductSort {
+    field: string;
+    dir: 'asc' | 'desc';
+}
+type ProductSortValue = string | number | undefined;
+/** The fields productSortValue knows, in the default column order. */
+declare const PRODUCT_SORT_FIELDS: readonly ["name", "sku", "barcode", "price", "stock", "category"];
+declare function productSortValue<Doc>(doc: Doc, field: string, traits: ProductTraits<Doc>, context?: TraitContext): ProductSortValue;
+declare function sortProducts<Doc>(docs: Doc[], sort: ProductSort | null | undefined, valueOf: (doc: Doc, field: string) => ProductSortValue): Doc[];
+
+type CatalogueView = 'grid' | 'table';
+type CatalogueGridColumns = 'auto' | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+interface CatalogueViewState {
+    view: CatalogueView;
+    gridColumns: CatalogueGridColumns;
+    sort: ProductSort | null;
+    categoryId: string | null;
+}
+declare const DEFAULT_CATALOGUE_VIEW_STATE: CatalogueViewState;
+type CatalogueViewAction = {
+    type: 'setView';
+    view: CatalogueView;
+} | {
+    type: 'setGridColumns';
+    gridColumns: CatalogueGridColumns;
+} | {
+    type: 'setSort';
+    sort: ProductSort | null;
+} | {
+    type: 'setCategory';
+    categoryId: string | null;
+} | {
+    type: 'replace';
+    state: CatalogueViewState;
+};
+declare function catalogueViewReducer(state: CatalogueViewState, action: CatalogueViewAction): CatalogueViewState;
+declare function normalizeCatalogueViewState(raw: unknown, defaults?: CatalogueViewState): CatalogueViewState;
+declare function resolveGridColumns(gridColumns: CatalogueGridColumns, containerWidth: number): number;
+
 /** The `stock_levels` collection as a live map of key to stock value. */
 declare function stockOverlay$(collection: RxCollection): Observable<Map<string, unknown>>;
 /**
@@ -2449,4 +2496,4 @@ declare function planLegs(plan: TenderPlan, rowsSinceFrom: {
     };
 };
 
-export { type Actor, type AddLineInput, type AppliedDiscount, type BackendNotFound, type BasketLine, CartError, type CashMovement, type CashMovementCollection, type CatalogueEntry, type ChargeInput, type ChargeLine, type Closure, type ClosureCollection, type ClosureContext, type ClosureScope, type CommandTransport, type Correction, CurrencyProvider, type CurrencyProviderProps, type CustomerSummary, DISCOUNTS_UNSUPPORTED, type Discount, type DisplayLine, type DisplayTotals, type FeeLine, type FinalizeOptions, type HttpTransportOptions, type LedgerRow, type LineItem, type LineTaxLine, type LogEntry, type LogLevel, type LogSink, type Logger, MAX_TENDER_MINOR, MICROS_PER_MINOR, type Movement$1 as Movement, type MovementType, type Order, type OrderBuilder, type OrderBuilderOptions, OrderContentMismatchError, type OrderManager, type OrderManagerOptions, type OrderOutbox, type OrderOutboxOptions, type OrderTaxTotals, type OrderTransportContext, type OutboxState, type ParkedOrderSummary, type Payment, type PaymentMethod, type PaymentTransport, type PlanLeg, type PosOrder, type PosOrderLine, type PosOrderLocalWarning, PosOrderOpenClosedError, type PosOrderPayment, type PosOrderServerFailures, type PosOrderSyncStatus, type RateTaxLine, type ReceiptConfig, type ReceiptData, type ReceiptLineItem, type RecordedFigures, RegisterApprovalRequiredError, type RegisterBucket, RegisterCloseIncompleteError, type RegisterCommand, type RegisterCommandCollection, type RegisterCounters, type RegisterDocument, type RegisterFact, type RegisterHost, RegisterIdInvalidError, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, type RegisterOutbox, type RegisterOutboxOptions, type RegisterSession, RegisterSessionAlreadyOpenError, RegisterSessionClosedError, type RegisterSessionCollection, RegisterSessionRequiredError, type RegisterStore, RegisterTenderInProgressError, type Repository, type ResolveStoreSettingsOptions, SALE_SAVING, type SaleStage, type SentOrder, type ShippingLine, type SplitTab, type StoreSettingsResolution, type StoreSettingsState, TAX_ROUNDING_MIXED_NOTE, type TaxContext, type TaxLineInput, TaxProvider, type TaxProviderProps, type TaxRateMap, type TenderAction, type TenderKey, type TenderLineId, type TenderPlan, type TenderState, type TenderView, type TransportOutcome, UnsupportedOrderVersionError, type UseOrderOutboxOptions, type UseOrderOutboxResult, type UseRegisterOutboxOptions, type UseRegisterOutboxResult, type UseRegisterSessionOptions, activePlan, addEntryToCart, addPosOrderCollection, advancePerpetual, allocateOrderDiscount, appliedMinor, backToSelling, bindRegister, buildClosureDocument, buildReceiptData, buildXReportDocument, callbackSink, cashMovementSchema, catalogueEntries, changeMinor, clampClosureScope, closeNeedsApproval, closeSession, closureCommand, closureSchema, computeOrderTax, consoleSink, countVariance, createBackendNotFound, createHttpCommandTransport, createLogger, createOrderBuilder, createOrderManager, createOrderOutbox, createRegisterOutbox, createRepository, denominationTotal, denominations, deriveExpected, deriveSettled, ensureRegister, evenSplitShareMinor, exportCsv, finalizeOrder, findEntryByCode, formatClosureDate, getBoundRegisterId, getDeviceId, initTenderState, initialTenderState, isServerDecimal, labelKeys, minorToDecimal, mintClosureNumber, mintUuid, movementCommand, movementFieldError, needsAttention, nextSaleCounter, normalizeAmount, observeRegister$, openSession, openSessionSelector, orderDraftSchema, outboxLogger, overThreshold, parkedOrderSummaries$, parseMinor, planLegs, posOrderCollection, posOrderSchema, posOrdersLogger, quickTenderedAmounts, ratePpmFromPercent, readBoundRegister, readRegister, reconcileRegisterCommands, recordMovement, recordRegisterFact, registerCommandCollection, registerCommandSchema, registerCommandsLogger, registerFactsLogger, registerSessionCollection, registerSessionSchema, requireOpenSession, resolveStoreSettings, restoreOrderDraft, roundMicrosToMinor, saleLogger, sameSale, searchProducts, selectClosureRows, sessionOpenCommand, sessionTransitionCommand, stampSession, startCounting, stockOverlay$, stockOverlayAsOf$, taxFiguresForBasket, taxLinesByRate, taxLogger, taxMicros, taxProviderProps, tenderReducer, toOrderCreateEnvelope, unbindRegister, useCurrencyCode, useCurrencyFormatter, useOrderOutbox, useParkedSales, useRegisterOutbox, useRegisterSession, useSale, useStoreSettings, useTax, uuidv7, validAmount, varianceText, variantPriceLabel, voidMovement, withPricingContext, writeClosure, writeOrderDraft };
+export { type Actor, type AddLineInput, type AppliedDiscount, type BackendNotFound, type BasketLine, CartError, type CashMovement, type CashMovementCollection, type CatalogueEntry, type CatalogueGridColumns, type CatalogueView, type CatalogueViewAction, type CatalogueViewState, type ChargeInput, type ChargeLine, type Closure, type ClosureCollection, type ClosureContext, type ClosureScope, type CommandTransport, type Correction, CurrencyProvider, type CurrencyProviderProps, type CustomerSummary, DEFAULT_CATALOGUE_VIEW_STATE, DISCOUNTS_UNSUPPORTED, type Discount, type DisplayLine, type DisplayTotals, type FeeLine, type FinalizeOptions, type HttpTransportOptions, type LedgerRow, type LineItem, type LineTaxLine, type LogEntry, type LogLevel, type LogSink, type Logger, MAX_TENDER_MINOR, MICROS_PER_MINOR, type Movement$1 as Movement, type MovementType, type Order, type OrderBuilder, type OrderBuilderOptions, OrderContentMismatchError, type OrderManager, type OrderManagerOptions, type OrderOutbox, type OrderOutboxOptions, type OrderTaxTotals, type OrderTransportContext, type OutboxState, PRODUCT_SORT_FIELDS, type ParkedOrderSummary, type Payment, type PaymentMethod, type PaymentTransport, type PlanLeg, type PosOrder, type PosOrderLine, type PosOrderLocalWarning, PosOrderOpenClosedError, type PosOrderPayment, type PosOrderServerFailures, type PosOrderSyncStatus, type ProductSort, type ProductSortValue, type RateTaxLine, type ReceiptConfig, type ReceiptData, type ReceiptLineItem, type RecordedFigures, RegisterApprovalRequiredError, type RegisterBucket, RegisterCloseIncompleteError, type RegisterCommand, type RegisterCommandCollection, type RegisterCounters, type RegisterDocument, type RegisterFact, type RegisterHost, RegisterIdInvalidError, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, type RegisterOutbox, type RegisterOutboxOptions, type RegisterSession, RegisterSessionAlreadyOpenError, RegisterSessionClosedError, type RegisterSessionCollection, RegisterSessionRequiredError, type RegisterStore, RegisterTenderInProgressError, type Repository, type ResolveStoreSettingsOptions, SALE_SAVING, type SaleStage, type SentOrder, type ShippingLine, type SplitTab, type StoreSettingsResolution, type StoreSettingsState, TAX_ROUNDING_MIXED_NOTE, type TaxContext, type TaxLineInput, TaxProvider, type TaxProviderProps, type TaxRateMap, type TenderAction, type TenderKey, type TenderLineId, type TenderPlan, type TenderState, type TenderView, type TransportOutcome, UnsupportedOrderVersionError, type UseOrderOutboxOptions, type UseOrderOutboxResult, type UseRegisterOutboxOptions, type UseRegisterOutboxResult, type UseRegisterSessionOptions, activePlan, addEntryToCart, addPosOrderCollection, advancePerpetual, allocateOrderDiscount, appliedMinor, backToSelling, bindRegister, buildClosureDocument, buildReceiptData, buildXReportDocument, callbackSink, cashMovementSchema, catalogueEntries, catalogueViewReducer, changeMinor, clampClosureScope, closeNeedsApproval, closeSession, closureCommand, closureSchema, computeOrderTax, consoleSink, countVariance, createBackendNotFound, createHttpCommandTransport, createLogger, createOrderBuilder, createOrderManager, createOrderOutbox, createRegisterOutbox, createRepository, denominationTotal, denominations, deriveExpected, deriveSettled, ensureRegister, evenSplitShareMinor, exportCsv, finalizeOrder, findEntryByCode, formatClosureDate, getBoundRegisterId, getDeviceId, inCategory, initTenderState, initialTenderState, isServerDecimal, labelKeys, listCategories, minorToDecimal, mintClosureNumber, mintUuid, movementCommand, movementFieldError, needsAttention, nextSaleCounter, normalizeAmount, normalizeCatalogueViewState, observeRegister$, openSession, openSessionSelector, orderDraftSchema, outboxLogger, overThreshold, parkedOrderSummaries$, parseMinor, planLegs, posOrderCollection, posOrderSchema, posOrdersLogger, productCategories, productSortValue, quickTenderedAmounts, ratePpmFromPercent, readBoundRegister, readRegister, reconcileRegisterCommands, recordMovement, recordRegisterFact, registerCommandCollection, registerCommandSchema, registerCommandsLogger, registerFactsLogger, registerSessionCollection, registerSessionSchema, requireOpenSession, resolveGridColumns, resolveStoreSettings, restoreOrderDraft, roundMicrosToMinor, saleLogger, sameSale, searchProducts, selectClosureRows, sessionOpenCommand, sessionTransitionCommand, sortProducts, stampSession, startCounting, stockOverlay$, stockOverlayAsOf$, taxFiguresForBasket, taxLinesByRate, taxLogger, taxMicros, taxProviderProps, tenderReducer, toOrderCreateEnvelope, unbindRegister, useCurrencyCode, useCurrencyFormatter, useOrderOutbox, useParkedSales, useRegisterOutbox, useRegisterSession, useSale, useStoreSettings, useTax, uuidv7, validAmount, varianceText, variantPriceLabel, voidMovement, withPricingContext, writeClosure, writeOrderDraft };

package/dist/index.js

@@ -1454,6 +1454,110 @@ function searchProducts(docs, term, traits) {
   });
 }
 
+// src/product/categories.ts
+function productCategories(doc, traits) {
+  return traits.getCategories ? traits.getCategories(doc) : traits.getCategoryNames(doc).map((name) => ({ id: name, name }));
+}
+function listCategories(docs, traits) {
+  const categories = /* @__PURE__ */ new Map();
+  for (const doc of docs) {
+    for (const category of productCategories(doc, traits)) {
+      if (!categories.has(category.id)) categories.set(category.id, category);
+    }
+  }
+  return [...categories.values()].sort((a, b) => a.name.localeCompare(b.name, void 0, { numeric: true, sensitivity: "base" }) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+function inCategory(doc, categoryId, traits) {
+  return productCategories(doc, traits).some((category) => category.id === categoryId);
+}
+
+// src/product/catalogue-view-state.ts
+var DEFAULT_CATALOGUE_VIEW_STATE = Object.freeze({
+  view: "grid",
+  gridColumns: "auto",
+  sort: null,
+  categoryId: null
+});
+function catalogueViewReducer(state, action) {
+  switch (action.type) {
+    case "setView":
+      return state.view === action.view ? state : { ...state, view: action.view };
+    case "setGridColumns":
+      return state.gridColumns === action.gridColumns ? state : { ...state, gridColumns: action.gridColumns };
+    case "setCategory":
+      return state.categoryId === action.categoryId ? state : { ...state, categoryId: action.categoryId };
+    case "setSort":
+      return state.sort?.field === action.sort?.field && state.sort?.dir === action.sort?.dir ? state : { ...state, sort: action.sort };
+    case "replace":
+      return action.state;
+  }
+}
+function normalizeCatalogueViewState(raw, defaults = DEFAULT_CATALOGUE_VIEW_STATE) {
+  if (typeof raw !== "object" || raw === null) return defaults;
+  try {
+    const { view, gridColumns, sort, categoryId } = raw;
+    const candidate = sort;
+    return {
+      categoryId: categoryId === null || typeof categoryId === "string" && categoryId.length > 0 ? categoryId : defaults.categoryId,
+      view: view === "grid" || view === "table" ? view : defaults.view,
+      gridColumns: gridColumns === "auto" || typeof gridColumns === "number" && Number.isInteger(gridColumns) && gridColumns >= 2 && gridColumns <= 8 ? gridColumns : defaults.gridColumns,
+      sort: sort === null ? null : typeof candidate === "object" && candidate && typeof candidate.field === "string" && candidate.field.length > 0 && (candidate.dir === "asc" || candidate.dir === "desc") ? { field: candidate.field, dir: candidate.dir } : defaults.sort
+    };
+  } catch {
+    return defaults;
+  }
+}
+var MIN_TILE_WIDTH = 160;
+function resolveGridColumns(gridColumns, containerWidth) {
+  return gridColumns === "auto" ? Math.max(2, Math.min(6, Math.floor((containerWidth - 8) / (MIN_TILE_WIDTH + 8)))) : gridColumns;
+}
+
+// src/product/sort-products.ts
+import { resolvePrice as resolvePrice2, resolvePriceRange } from "@tallyui/core";
+var PRODUCT_SORT_FIELDS = ["name", "sku", "barcode", "price", "stock", "category"];
+function productSortValue(doc, field, traits, context) {
+  let value;
+  switch (field) {
+    case "name":
+      value = traits.getName(doc);
+      break;
+    case "sku":
+      value = traits.getSku(doc);
+      break;
+    case "barcode":
+      value = traits.getBarcode(doc);
+      break;
+    case "price": {
+      const variants = traits.getVariants?.(doc, context);
+      value = variants && variants.length >= 2 ? resolvePriceRange(variants, context?.currency)?.min.amount : resolvePrice2(traits.getPrices(doc, context), context?.currency)?.current.amount;
+      break;
+    }
+    case "stock":
+      value = traits.getStock(doc).quantity;
+      break;
+    case "category":
+      value = traits.getCategoryNames(doc).join(", ");
+      break;
+    default:
+      return void 0;
+  }
+  return value === "" ? void 0 : value;
+}
+function sortProducts(docs, sort, valueOf) {
+  if (!sort) return docs;
+  return docs.map((doc, index) => ({ doc, index, value: valueOf(doc, sort.field) })).sort((a, b) => {
+    const aMissing = a.value === void 0 || a.value === "";
+    const bMissing = b.value === void 0 || b.value === "";
+    if (aMissing || bMissing) {
+      return aMissing === bMissing ? a.index - b.index : aMissing ? 1 : -1;
+    }
+    const av = a.value;
+    const bv = b.value;
+    const comparison = typeof av === "number" ? typeof bv === "number" ? av - bv : -1 : typeof bv === "number" ? 1 : av.localeCompare(bv, void 0, { numeric: true, sensitivity: "base" });
+    return (sort.dir === "desc" ? -comparison : comparison) || a.index - b.index;
+  }).map(({ doc }) => doc);
+}
+
 // src/product/stock.ts
 import { map as map3 } from "rxjs";
 import { STOCK_LEVELS_LAST_PASS } from "@tallyui/core";
@@ -3905,7 +4009,7 @@ function useRegisterSession(options) {
 }
 
 // src/sale/cart.ts
-import { resolvePrice as resolvePrice2 } from "@tallyui/core";
+import { resolvePrice as resolvePrice3 } from "@tallyui/core";
 var CartError = class extends Error {
 };
 function addEntryToCart(builder, entry, traits, currency) {
@@ -3916,7 +4020,7 @@ function addEntryToCart(builder, entry, traits, currency) {
     return existing.id;
   }
   const name = traits.getName(product) + (traits.getVariantCount(product) > 1 ? ` \xB7 ${variant.title}` : "");
-  const unitPrice = resolvePrice2(variant.prices, currency)?.current;
+  const unitPrice = resolvePrice3(variant.prices, currency)?.current;
   if (!unitPrice) throw new CartError(`No ${currency} price for ${name}`);
   return builder.addLine({
     productId: traits.getId(product),
@@ -4424,7 +4528,7 @@ function useSale(settings, opts) {
 }
 
 // src/sale/catalogue.ts
-import { findVariantByCode, formatMoney as formatMoney2, resolvePrice as resolvePrice3 } from "@tallyui/core";
+import { findVariantByCode, formatMoney as formatMoney2, resolvePrice as resolvePrice4 } from "@tallyui/core";
 function catalogueEntries(products, traits, context) {
   return products.flatMap((product) => {
     const variants = traits.getVariants ? traits.getVariants(product, context) : traits.hasVariants(product) ? [] : [{
@@ -4442,7 +4546,7 @@ function findEntryByCode(entries, code) {
   return variant ? entries.find((entry) => entry.variant === variant) : void 0;
 }
 function variantPriceLabel(variant, currency, locale) {
-  const price = resolvePrice3(variant.prices, currency);
+  const price = resolvePrice4(variant.prices, currency);
   return price ? formatMoney2(price.current, locale) : void 0;
 }
 
@@ -5606,10 +5710,12 @@ function planLegs(plan, rowsSinceFrom, balanceMinor) {
 export {
   CartError,
   CurrencyProvider,
+  DEFAULT_CATALOGUE_VIEW_STATE,
   DISCOUNTS_UNSUPPORTED,
   MAX_TENDER_MINOR,
   MICROS_PER_MINOR,
   OrderContentMismatchError,
+  PRODUCT_SORT_FIELDS,
   PosOrderOpenClosedError,
   RegisterApprovalRequiredError,
   RegisterCloseIncompleteError,
@@ -5639,6 +5745,7 @@ export {
   callbackSink,
   cashMovementSchema,
   catalogueEntries,
+  catalogueViewReducer,
   changeMinor,
   clampClosureScope,
   closeNeedsApproval,
@@ -5670,10 +5777,12 @@ export {
   getBoundRegisterId,
   getDeviceId,
   getProductStock,
+  inCategory,
   initTenderState,
   initialTenderState,
   isServerDecimal,
   labelKeys,
+  listCategories,
   minorToDecimal,
   mintClosureNumber,
   mintUuid,
@@ -5682,6 +5791,7 @@ export {
   needsAttention,
   nextSaleCounter,
   normalizeAmount,
+  normalizeCatalogueViewState,
   observeRegister$,
   openSession,
   openSessionSelector,
@@ -5694,6 +5804,8 @@ export {
   posOrderCollection,
   posOrderSchema,
   posOrdersLogger,
+  productCategories,
+  productSortValue,
   quickTenderedAmounts,
   ratePpmFromPercent,
   readBoundRegister,
@@ -5709,6 +5821,7 @@ export {
   registerSessionCollection,
   registerSessionSchema,
   requireOpenSession,
+  resolveGridColumns,
   resolveStoreSettings,
   restoreOrderDraft,
   roundMicrosToMinor,
@@ -5718,6 +5831,7 @@ export {
   selectClosureRows,
   sessionOpenCommand,
   sessionTransitionCommand,
+  sortProducts,
   stampSession,
   startCounting,
   stockOverlay$,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/pos",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "type": "module",
   "description": "Shared POS business logic for Tally UI — tax, orders, payments, discounts, receipts",
   "main": "./dist/index.js",
@@ -27,20 +27,20 @@
     "directory": "packages/pos"
   },
   "peerDependencies": {
-    "@tallyui/core": "^3.4.0",
+    "@tallyui/core": "^3.5.0",
     "react": ">=18",
     "rxdb": "~17.5.0",
     "rxjs": ">=7"
   },
   "devDependencies": {
-    "@tallyui/core": "3.4.0",
+    "@tallyui/core": "3.5.0",
     "@types/react": ">=18",
     "react": "^19.2.4",
     "rxdb": "17.5.0",
     "rxjs": "7.8.2",
-    "@tallyui/connector-medusa": "3.4.0",
-    "@tallyui/connector-woocommerce": "3.4.0",
-    "@tallyui/database": "3.4.0"
+    "@tallyui/connector-medusa": "3.5.0",
+    "@tallyui/connector-woocommerce": "3.5.0",
+    "@tallyui/database": "3.5.0"
   },
   "scripts": {
     "build": "tsup",

package/src/index.ts

@@ -55,7 +55,7 @@ export { buildReceiptData } from './receipt';
 export type { ReceiptData, ReceiptLineItem, ReceiptConfig } from './receipt';
 
 // Product
-export { searchProducts, withStockOverlay, getProductStock, stockOverlay$, stockOverlayAsOf$ } from './product';
+export { searchProducts, sortProducts, productSortValue, PRODUCT_SORT_FIELDS, type ProductSort, type ProductSortValue, catalogueViewReducer, normalizeCatalogueViewState, resolveGridColumns, DEFAULT_CATALOGUE_VIEW_STATE, type CatalogueView, type CatalogueGridColumns, type CatalogueViewState, type CatalogueViewAction, withStockOverlay, getProductStock, stockOverlay$, stockOverlayAsOf$, productCategories, listCategories, inCategory } from './product';
 
 // Sale
 export { useSale, DISCOUNTS_UNSUPPORTED, SALE_SAVING, saleLogger, addEntryToCart, CartError, catalogueEntries, findEntryByCode, variantPriceLabel } from './sale';

package/src/product/catalogue-view-state.ts

@@ -0,0 +1,60 @@
+import type { ProductSort } from './sort-products';
+
+export type CatalogueView = 'grid' | 'table';
+export type CatalogueGridColumns = 'auto' | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+export interface CatalogueViewState {
+  view: CatalogueView;
+  gridColumns: CatalogueGridColumns;
+  sort: ProductSort | null;
+  categoryId: string | null;
+}
+export const DEFAULT_CATALOGUE_VIEW_STATE: CatalogueViewState = Object.freeze({
+  view: 'grid', gridColumns: 'auto', sort: null, categoryId: null,
+});
+
+export type CatalogueViewAction =
+  | { type: 'setView'; view: CatalogueView }
+  | { type: 'setGridColumns'; gridColumns: CatalogueGridColumns }
+  | { type: 'setSort'; sort: ProductSort | null }
+  | { type: 'setCategory'; categoryId: string | null }
+  | { type: 'replace'; state: CatalogueViewState };
+
+export function catalogueViewReducer(state: CatalogueViewState, action: CatalogueViewAction): CatalogueViewState {
+  switch (action.type) {
+    case 'setView': return state.view === action.view ? state : { ...state, view: action.view };
+    case 'setGridColumns': return state.gridColumns === action.gridColumns ? state : { ...state, gridColumns: action.gridColumns };
+    case 'setCategory': return state.categoryId === action.categoryId ? state : { ...state, categoryId: action.categoryId };
+    case 'setSort': return state.sort?.field === action.sort?.field && state.sort?.dir === action.sort?.dir
+      ? state : { ...state, sort: action.sort };
+    case 'replace': return action.state;
+  }
+}
+
+export function normalizeCatalogueViewState(raw: unknown, defaults: CatalogueViewState = DEFAULT_CATALOGUE_VIEW_STATE): CatalogueViewState {
+  if (typeof raw !== 'object' || raw === null) return defaults;
+  try {
+    const { view, gridColumns, sort, categoryId } = raw as Record<string, unknown>;
+    const candidate = sort as Partial<ProductSort> | null;
+    return {
+      categoryId: categoryId === null || (typeof categoryId === 'string' && categoryId.length > 0)
+        ? categoryId : defaults.categoryId,
+      view: view === 'grid' || view === 'table' ? view : defaults.view,
+      gridColumns: gridColumns === 'auto' || (typeof gridColumns === 'number' && Number.isInteger(gridColumns)
+        && gridColumns >= 2 && gridColumns <= 8) ? gridColumns as CatalogueGridColumns : defaults.gridColumns,
+      sort: sort === null ? null : typeof candidate === 'object' && candidate
+        && typeof candidate.field === 'string' && candidate.field.length > 0
+        && (candidate.dir === 'asc' || candidate.dir === 'desc')
+        ? { field: candidate.field, dir: candidate.dir } : defaults.sort,
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+// Keep product names readable and touch targets at least 160 px wide where two columns fit.
+const MIN_TILE_WIDTH = 160;
+export function resolveGridColumns(gridColumns: CatalogueGridColumns, containerWidth: number): number {
+  // ProductGrid has 4 px padding on each side of the content and each cell: 160 px tile + 8.
+  return gridColumns === 'auto'
+    ? Math.max(2, Math.min(6, Math.floor((containerWidth - 8) / (MIN_TILE_WIDTH + 8)))) : gridColumns;
+}

package/src/product/categories.ts

@@ -0,0 +1,26 @@
+import type { ProductCategory, ProductTraits } from '@tallyui/core';
+
+/** The product's categories: `getCategories`, else `getCategoryNames` with each name as its id. */
+export function productCategories<Doc>(doc: Doc, traits: ProductTraits<Doc>): ProductCategory[] {
+  return traits.getCategories
+    ? traits.getCategories(doc)
+    : traits.getCategoryNames(doc).map((name) => ({ id: name, name }));
+}
+
+/** Every category across `docs`, once per id (the first name seen wins), sorted by name (natural, case-insensitive), ties by id. */
+export function listCategories<Doc>(docs: readonly Doc[], traits: ProductTraits<Doc>): ProductCategory[] {
+  const categories = new Map<string, ProductCategory>();
+  for (const doc of docs) {
+    for (const category of productCategories(doc, traits)) {
+      if (!categories.has(category.id)) categories.set(category.id, category);
+    }
+  }
+  return [...categories.values()].sort((a, b) =>
+    a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: 'base' })
+    || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+/** Whether `doc` is in the category with this id. */
+export function inCategory<Doc>(doc: Doc, categoryId: string, traits: ProductTraits<Doc>): boolean {
+  return productCategories(doc, traits).some((category) => category.id === categoryId);
+}

package/src/product/index.ts

@@ -1,2 +1,5 @@
 export { searchProducts } from './search-products';
+export { productCategories, listCategories, inCategory } from './categories';
+export { catalogueViewReducer, normalizeCatalogueViewState, resolveGridColumns, DEFAULT_CATALOGUE_VIEW_STATE, type CatalogueView, type CatalogueGridColumns, type CatalogueViewState, type CatalogueViewAction } from './catalogue-view-state';
+export { sortProducts, productSortValue, PRODUCT_SORT_FIELDS, type ProductSort, type ProductSortValue } from './sort-products';
 export { withStockOverlay, getProductStock, stockOverlay$, stockOverlayAsOf$ } from './stock';

package/src/product/sort-products.ts

@@ -0,0 +1,51 @@
+import { resolvePrice, resolvePriceRange, type ProductTraits, type TraitContext } from '@tallyui/core';
+
+/** A sort on one field: ascending or descending. */
+export interface ProductSort { field: string; dir: 'asc' | 'desc' }
+export type ProductSortValue = string | number | undefined;
+/** The fields productSortValue knows, in the default column order. */
+export const PRODUCT_SORT_FIELDS = ['name', 'sku', 'barcode', 'price', 'stock', 'category'] as const;
+
+export function productSortValue<Doc>(
+  doc: Doc, field: string, traits: ProductTraits<Doc>, context?: TraitContext,
+): ProductSortValue {
+  let value: ProductSortValue;
+  switch (field) {
+    case 'name': value = traits.getName(doc); break;
+    case 'sku': value = traits.getSku(doc); break;
+    case 'barcode': value = traits.getBarcode(doc); break;
+    case 'price': {
+      const variants = traits.getVariants?.(doc, context);
+      value = variants && variants.length >= 2
+        ? resolvePriceRange(variants, context?.currency)?.min.amount
+        : resolvePrice(traits.getPrices(doc, context), context?.currency)?.current.amount;
+      break;
+    }
+    case 'stock': value = traits.getStock(doc).quantity; break;
+    case 'category': value = traits.getCategoryNames(doc).join(', '); break;
+    default: return undefined;
+  }
+  return value === '' ? undefined : value;
+}
+
+export function sortProducts<Doc>(
+  docs: Doc[], sort: ProductSort | null | undefined,
+  valueOf: (doc: Doc, field: string) => ProductSortValue,
+): Doc[] {
+  if (!sort) return docs;
+  return docs.map((doc, index) => ({ doc, index, value: valueOf(doc, sort.field) }))
+    .sort((a, b) => {
+      const aMissing = a.value === undefined || a.value === '';
+      const bMissing = b.value === undefined || b.value === '';
+      if (aMissing || bMissing) {
+        return aMissing === bMissing ? a.index - b.index : aMissing ? 1 : -1;
+      }
+      const av = a.value!;
+      const bv = b.value!;
+      const comparison = typeof av === 'number'
+        ? (typeof bv === 'number' ? av - bv : -1)
+        : (typeof bv === 'number' ? 1 : av.localeCompare(bv, undefined, { numeric: true, sensitivity: 'base' }));
+      return (sort.dir === 'desc' ? -comparison : comparison) || a.index - b.index;
+    })
+    .map(({ doc }) => doc);
+}