@withpotter/lib 0.13.0-next.101

package/dist/intents/types.d.ts

@@ -0,0 +1,246 @@
+import type { BookingMode, CreateBookingInput, FulfillmentStatus } from '@withpotter/lib/api/types';
+export interface EntityLabel {
+    singular: string;
+    plural: string;
+}
+export interface IntentNavItem {
+    id: string;
+    label: string;
+    href: string;
+    icon: string;
+    badge?: string;
+    /**
+     * Generic items are shared platform capabilities (Collections, Discounts, Invoices, Loyalty)
+     * rather than intent-specific features.  When `generic` is true the sidebar
+     * respects the merchant's `hiddenModules` / `enabledBehaviors` toggles —
+     * the item can be disabled without touching the intent config.
+     */
+    generic?: boolean;
+    /** When generic, only show if one of these behaviors is enabled */
+    requiredBehavior?: string[];
+}
+export interface IntentNavGroup {
+    key: string;
+    label: string;
+    items: IntentNavItem[];
+}
+export interface IntentPage {
+    id: string;
+    route: string;
+    label: string;
+    icon: string;
+}
+export interface StatDef {
+    key: string;
+    label: string;
+    dataKey: string;
+    format: 'number' | 'currency' | 'percentage';
+    icon: string;
+}
+export interface ActionDef {
+    key: string;
+    label: string;
+    icon: string;
+    href?: string;
+    action?: string;
+    variant: 'primary' | 'secondary' | 'destructive';
+}
+export interface ColumnDef {
+    key: string;
+    label: string;
+}
+export interface FilterDef {
+    key: string;
+    label: string;
+    type: 'select' | 'dateRange' | 'text';
+    options?: {
+        value: string;
+        label: string;
+    }[];
+}
+export interface BookingQueryStyle {
+    key: string;
+    bookingTypes: CreateBookingInput['type'][];
+    bookingModes: BookingMode[];
+    defaultBookingType: CreateBookingInput['type'];
+    defaultBookingMode: BookingMode;
+}
+export interface EmptyStateDef {
+    title: string;
+    description: string;
+    actionLabel: string;
+    actionHref: string;
+}
+/**
+ * Names for the four booking measures in the analytics operating band. A padel
+ * club reads "Booked today", a cinema reads "Sold today", a landlord reads
+ * "Check-ins today" — same field, the vertical's noun.
+ */
+export interface AnalyticsBookingMetricLabels {
+    today: string;
+    upcoming: string;
+    noShow: string;
+    revenue: string;
+}
+export interface OrderDisplay {
+    statusLabels: Record<string, string>;
+    statusColors: Record<string, string>;
+    statusIcons: Record<string, string>;
+    fulfillmentLabels?: Partial<Record<FulfillmentStatus, string>>;
+    /** Baseline shell copy for the orders page; operating-model can override this. */
+    pageSubtitle?: string;
+    /** Intent-owned label for the fulfillment control. */
+    fulfillmentLabel?: string;
+    /** Baseline visibility for fulfillment fields; operating-model can override this. */
+    hideFulfillment: boolean;
+    /** Baseline visibility for shipping fields; operating-model can override this. */
+    hideShipping: boolean;
+    /** Status-label keys whose tabs filter fulfillment rather than order lifecycle. */
+    fulfillmentTabStatuses?: Record<string, FulfillmentStatus>;
+    /**
+     * Status keys that are booking-level (not order-level).
+     * These use `bookingStatus` query filter instead of `status`.
+     * Default: [] (all keys are order-level).
+     */
+    bookingStatusKeys?: string[];
+}
+export interface IntentConfig {
+    key: string;
+    label: string;
+    description: string;
+    icon: string;
+    /**
+     * Nouns the dashboard renames per business model. There is deliberately no
+     * `customer` here: the CRM is a shared layer across every model a merchant
+     * runs, so the sidebar protects that label (see PROTECTED_LABELS) and every
+     * intent shows "Customers". Archetype-specific customer language lives in
+     * `emptyStates.customers` instead, where it describes this model's people
+     * without renaming the shared directory.
+     */
+    entities: {
+        item: EntityLabel;
+        order: EntityLabel;
+        booking: EntityLabel;
+        /**
+         * What the thing a booking occupies is called: a court, a table, a room, a
+         * stylist, a property. Optional because not every archetype is
+         * resource-backed, and callers fall back to the neutral "Resource".
+         *
+         * This exists because the resource noun previously lived only in the nav
+         * label ('Tables', 'Resources'), which no component could reach — so any
+         * surface naming a resource had to hardcode one vertical's word for it.
+         */
+        resource?: EntityLabel;
+    };
+    navigation: {
+        groups: IntentNavGroup[];
+    };
+    pages: IntentPage[];
+    pageSections: {
+        orderDetail: string[];
+        orderList: {
+            columns: ColumnDef[];
+            filters: FilterDef[];
+            actions: ActionDef[];
+            bulkActions: ActionDef[];
+            stats?: StatDef[];
+        };
+        itemDetail: string[];
+        itemList: {
+            columns: ColumnDef[];
+            filters: FilterDef[];
+            stats?: StatDef[];
+            /** Enables stock filters + inline editing for quantity/threshold */
+            trackInventory?: boolean;
+            searchPlaceholder?: string;
+        };
+    };
+    /**
+     * The home's own numbers come from the widget board, not from here.
+     *
+     * `stats` used to sit beside `quickActions`: four `StatDef`s per archetype,
+     * forty-four in all, resolved by three functions (`resolveStatDefs`,
+     * `resolveDashboardStats`, `resolveMultiIntentStats`) that between them had
+     * no caller outside their own tests. The home renders widgets; the only
+     * components that ever drew a stats grid from a config — `HomeLauncher` and
+     * `MobileOverview` — were themselves imported by nothing.
+     *
+     * `quickActions` stays because the Operations hub reads it.
+     */
+    dashboard: {
+        quickActions: ActionDef[];
+    };
+    analyticsPage?: {
+        /** Which supporting analytics tab IDs to show (e.g., ['traffic', 'sales']) */
+        tabs?: string[];
+    };
+    analyticsLabels?: {
+        bookingMetrics?: AnalyticsBookingMetricLabels;
+    };
+    emptyStates: {
+        orders: EmptyStateDef;
+        items: EmptyStateDef;
+        customers: EmptyStateDef;
+    };
+    orderDisplay: OrderDisplay;
+    /**
+     * Booking page filter/default preset for the active intent.
+     * Keeps booking queries scoped to the active primary intent.
+     */
+    queryStyle?: BookingQueryStyle;
+    behaviorFilter?: {
+        include: string;
+        exclude?: string[];
+    };
+    editor?: {
+        /** Behaviors auto-enabled when creating a product in this intent context */
+        intrinsicBehaviors: string[];
+        /** Behaviors hidden from the Features toggle in the editor */
+        hiddenBehaviors?: string[];
+        labels?: {
+            titlePlaceholder?: string;
+            descriptionPlaceholder?: string;
+        };
+    };
+}
+export type IntentMode = 'single' | 'multi';
+export interface ResolvedIntentConfig {
+    mode: IntentMode;
+    /**
+     * Which archetype's *wording* to use — stat labels, empty states, nouns.
+     * Always exactly one, because a screen has to call things something.
+     */
+    primary: IntentConfig;
+    all: IntentConfig[];
+    /**
+     * Which archetypes the screen is currently *showing*, as opposed to which one
+     * it is worded as.
+     *
+     * An explicit `?intent=` narrows to that one. Its absence means all of them:
+     * a merchant who clicks Orders wants their orders, not the orders of
+     * whichever archetype they last happened to look at. Before this existed,
+     * every screen filtered by `primary`, so an unscoped Orders silently showed
+     * one archetype's rows and looked like missing data.
+     */
+    activeKeys: string[];
+    /**
+     * The configs `activeKeys` names, in `all` order.
+     *
+     * Three screens had each written `all.filter(c => activeKeys.includes(c.key))`
+     * or a ternary on `isAllIntents` beside it, which is the same set twice and a
+     * place for the two to disagree.
+     */
+    active: IntentConfig[];
+    /**
+     * Whether this business runs any archetype at all.
+     *
+     * Read as `primary.key !== 'default'` in two places, which asks a
+     * business-wide question of one arbitrary archetype — `primary` is whichever
+     * was ticked first unless sessionStorage overrode it. It happens to give the
+     * right answer, because the fallback replaces the whole set rather than one
+     * member, but it reads as though the archetype matters and it does not.
+     */
+    hasArchetype: boolean;
+    /** True when the view spans every archetype rather than one. */
+    isAllIntents: boolean;
+}

package/dist/intents/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/intents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/intents/use-active-intent.d.ts

@@ -0,0 +1,27 @@
+import type { ResolvedIntentConfig } from './types';
+/**
+ * Builds an href that preserves the active intent in multi-intent mode.
+ *
+ * Usage:
+ *   const withIntent = useIntentHref();
+ *   <Link href={withIntent('/dashboard/orders')} />
+ *   <Link href={withIntent('/dashboard/orders', 'booking')} />  // override
+ */
+export declare function useIntentHref(): (path: string, intentKey?: string) => string;
+/**
+ * Hook for screens that need to switch the active intent in multi-intent mode.
+ *
+ * Returns:
+ *   - `mode` / `primary` / `all` from useIntentConfig()
+ *   - `setActive(key)` — updates ?intent= query param + sessionStorage; triggers a soft re-render
+ *   - `isMulti` — convenience boolean
+ *
+ * Behavior:
+ *   - In single-intent mode, setActive is a no-op (always primary).
+ *   - In multi-intent mode, setActive uses router.replace so back-button history isn't polluted.
+ */
+export declare function useActiveIntent(): ResolvedIntentConfig & {
+    isMulti: boolean;
+    setActive: (key: string | string[]) => void;
+    clearActive: () => void;
+};

package/dist/intents/use-active-intent.js

@@ -0,0 +1,74 @@
+"use client";
+import { useCallback } from "react";
+import { usePathname, useRouter, useSearchParams } from "next/navigation";
+import { useIntentConfig } from "./use-intent-config";
+const INTENT_STORAGE_KEY = "potter:activeIntent";
+function useIntentHref() {
+  const intentConfig = useIntentConfig();
+  return useCallback(
+    (path, intentKey) => {
+      if (intentConfig.mode !== "multi") return path;
+      if (!intentKey && intentConfig.isAllIntents) return path;
+      const key = intentKey ?? intentConfig.activeKeys.join(",");
+      const sep = path.includes("?") ? "&" : "?";
+      return `${path}${sep}intent=${encodeURIComponent(key)}`;
+    },
+    [intentConfig]
+  );
+}
+function useActiveIntent() {
+  const intentConfig = useIntentConfig();
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const setActive = useCallback(
+    /**
+     * Narrow to one archetype, or to several at once.
+     *
+     * Several, because a narrowing is not always one archetype: a place that
+     * seats guests and does takeaway has ONE menu, and the chip that says Menu
+     * has to select both `dine-in` and `food-orders` or it shows half a menu
+     * under the merchant's own word for all of it. The sidebar has always
+     * built comma-joined `?intent=` hrefs for exactly this reason; only the
+     * setter was stuck at one.
+     */
+    (key) => {
+      if (intentConfig.mode !== "multi") return;
+      const keys = (Array.isArray(key) ? key : [key]).filter(
+        (k) => intentConfig.all.some((c) => c.key === k)
+      );
+      if (keys.length === 0) return;
+      const value = keys.join(",");
+      try {
+        sessionStorage.setItem(INTENT_STORAGE_KEY, value);
+      } catch {
+      }
+      const params = new URLSearchParams(searchParams?.toString() ?? "");
+      params.set("intent", value);
+      router.replace(`${pathname}?${params.toString()}`, { scroll: false });
+    },
+    [intentConfig, router, pathname, searchParams]
+  );
+  const clearActive = useCallback(() => {
+    if (intentConfig.mode !== "multi") return;
+    try {
+      sessionStorage.removeItem(INTENT_STORAGE_KEY);
+    } catch {
+    }
+    const params = new URLSearchParams(searchParams?.toString() ?? "");
+    params.delete("intent");
+    const qs = params.toString();
+    router.replace(qs ? `${pathname}?${qs}` : pathname, { scroll: false });
+  }, [intentConfig, router, pathname, searchParams]);
+  return {
+    ...intentConfig,
+    isMulti: intentConfig.mode === "multi",
+    setActive,
+    clearActive
+  };
+}
+export {
+  useActiveIntent,
+  useIntentHref
+};
+//# sourceMappingURL=use-active-intent.js.map

package/dist/intents/use-active-intent.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/intents/use-active-intent.ts"],"sourcesContent":["'use client';\n\nimport { useCallback } from 'react';\nimport { usePathname, useRouter, useSearchParams } from 'next/navigation';\nimport { useIntentConfig } from './use-intent-config';\nimport type { IntentConfig, ResolvedIntentConfig } from './types';\n\nconst INTENT_STORAGE_KEY = 'potter:activeIntent';\n\n/**\n * Builds an href that preserves the active intent in multi-intent mode.\n *\n * Usage:\n *   const withIntent = useIntentHref();\n *   <Link href={withIntent('/dashboard/orders')} />\n *   <Link href={withIntent('/dashboard/orders', 'booking')} />  // override\n */\nexport function useIntentHref() {\n  const intentConfig = useIntentConfig();\n  return useCallback(\n    (path: string, intentKey?: string) => {\n      if (intentConfig.mode !== 'multi') return path;\n      // An explicit key means the caller is deliberately narrowing to one.\n      // Otherwise carry what the merchant is currently in — which may be\n      // nothing at all. It used to default to `primary.key`, so a link built on\n      // an unnarrowed screen quietly narrowed the destination to whichever\n      // archetype sessionStorage last saw.\n      if (!intentKey && intentConfig.isAllIntents) return path;\n      const key = intentKey ?? intentConfig.activeKeys.join(',');\n      const sep = path.includes('?') ? '&' : '?';\n      return `${path}${sep}intent=${encodeURIComponent(key)}`;\n    },\n    [intentConfig],\n  );\n}\n\n/**\n * Hook for screens that need to switch the active intent in multi-intent mode.\n *\n * Returns:\n *   - `mode` / `primary` / `all` from useIntentConfig()\n *   - `setActive(key)` — updates ?intent= query param + sessionStorage; triggers a soft re-render\n *   - `isMulti` — convenience boolean\n *\n * Behavior:\n *   - In single-intent mode, setActive is a no-op (always primary).\n *   - In multi-intent mode, setActive uses router.replace so back-button history isn't polluted.\n */\nexport function useActiveIntent(): ResolvedIntentConfig & {\n  isMulti: boolean;\n  setActive: (key: string | string[]) => void;\n  clearActive: () => void;\n} {\n  const intentConfig = useIntentConfig();\n  const router = useRouter();\n  const pathname = usePathname();\n  const searchParams = useSearchParams();\n\n  const setActive = useCallback(\n    /**\n     * Narrow to one archetype, or to several at once.\n     *\n     * Several, because a narrowing is not always one archetype: a place that\n     * seats guests and does takeaway has ONE menu, and the chip that says Menu\n     * has to select both `dine-in` and `food-orders` or it shows half a menu\n     * under the merchant's own word for all of it. The sidebar has always\n     * built comma-joined `?intent=` hrefs for exactly this reason; only the\n     * setter was stuck at one.\n     */\n    (key: string | string[]) => {\n      if (intentConfig.mode !== 'multi') return;\n      const keys = (Array.isArray(key) ? key : [key]).filter((k) =>\n        intentConfig.all.some((c: IntentConfig) => c.key === k),\n      );\n      if (keys.length === 0) return;\n      const value = keys.join(',');\n\n      // Persist for sibling pages that resolve from sessionStorage\n      try {\n        sessionStorage.setItem(INTENT_STORAGE_KEY, value);\n      } catch {\n        // ignore (SSR / privacy mode)\n      }\n\n      // Update URL — this re-runs useSearchParams in useIntentConfig\n      const params = new URLSearchParams(searchParams?.toString() ?? '');\n      params.set('intent', value);\n      router.replace(`${pathname}?${params.toString()}`, { scroll: false });\n    },\n    [intentConfig, router, pathname, searchParams],\n  );\n\n  /** Drop the narrowing and show every archetype again. */\n  const clearActive = useCallback(() => {\n    if (intentConfig.mode !== 'multi') return;\n    try {\n      sessionStorage.removeItem(INTENT_STORAGE_KEY);\n    } catch {\n      // ignore (SSR / privacy mode)\n    }\n    const params = new URLSearchParams(searchParams?.toString() ?? '');\n    params.delete('intent');\n    const qs = params.toString();\n    router.replace(qs ? `${pathname}?${qs}` : pathname, { scroll: false });\n  }, [intentConfig, router, pathname, searchParams]);\n\n  return {\n    ...intentConfig,\n    isMulti: intentConfig.mode === 'multi',\n    setActive,\n    clearActive,\n  };\n}\n"],"mappings":";AAEA,SAAS,mBAAmB;AAC5B,SAAS,aAAa,WAAW,uBAAuB;AACxD,SAAS,uBAAuB;AAGhC,MAAM,qBAAqB;AAUpB,SAAS,gBAAgB;AAC9B,QAAM,eAAe,gBAAgB;AACrC,SAAO;AAAA,IACL,CAAC,MAAc,cAAuB;AACpC,UAAI,aAAa,SAAS,QAAS,QAAO;AAM1C,UAAI,CAAC,aAAa,aAAa,aAAc,QAAO;AACpD,YAAM,MAAM,aAAa,aAAa,WAAW,KAAK,GAAG;AACzD,YAAM,MAAM,KAAK,SAAS,GAAG,IAAI,MAAM;AACvC,aAAO,GAAG,IAAI,GAAG,GAAG,UAAU,mBAAmB,GAAG,CAAC;AAAA,IACvD;AAAA,IACA,CAAC,YAAY;AAAA,EACf;AACF;AAcO,SAAS,kBAId;AACA,QAAM,eAAe,gBAAgB;AACrC,QAAM,SAAS,UAAU;AACzB,QAAM,WAAW,YAAY;AAC7B,QAAM,eAAe,gBAAgB;AAErC,QAAM,YAAY;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAWhB,CAAC,QAA2B;AAC1B,UAAI,aAAa,SAAS,QAAS;AACnC,YAAM,QAAQ,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,GAAG,GAAG;AAAA,QAAO,CAAC,MACtD,aAAa,IAAI,KAAK,CAAC,MAAoB,EAAE,QAAQ,CAAC;AAAA,MACxD;AACA,UAAI,KAAK,WAAW,EAAG;AACvB,YAAM,QAAQ,KAAK,KAAK,GAAG;AAG3B,UAAI;AACF,uBAAe,QAAQ,oBAAoB,KAAK;AAAA,MAClD,QAAQ;AAAA,MAER;AAGA,YAAM,SAAS,IAAI,gBAAgB,cAAc,SAAS,KAAK,EAAE;AACjE,aAAO,IAAI,UAAU,KAAK;AAC1B,aAAO,QAAQ,GAAG,QAAQ,IAAI,OAAO,SAAS,CAAC,IAAI,EAAE,QAAQ,MAAM,CAAC;AAAA,IACtE;AAAA,IACA,CAAC,cAAc,QAAQ,UAAU,YAAY;AAAA,EAC/C;AAGA,QAAM,cAAc,YAAY,MAAM;AACpC,QAAI,aAAa,SAAS,QAAS;AACnC,QAAI;AACF,qBAAe,WAAW,kBAAkB;AAAA,IAC9C,QAAQ;AAAA,IAER;AACA,UAAM,SAAS,IAAI,gBAAgB,cAAc,SAAS,KAAK,EAAE;AACjE,WAAO,OAAO,QAAQ;AACtB,UAAM,KAAK,OAAO,SAAS;AAC3B,WAAO,QAAQ,KAAK,GAAG,QAAQ,IAAI,EAAE,KAAK,UAAU,EAAE,QAAQ,MAAM,CAAC;AAAA,EACvE,GAAG,CAAC,cAAc,QAAQ,UAAU,YAAY,CAAC;AAEjD,SAAO;AAAA,IACL,GAAG;AAAA,IACH,SAAS,aAAa,SAAS;AAAA,IAC/B;AAAA,IACA;AAAA,EACF;AACF;","names":[]}

package/dist/intents/use-destination-label.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What to title a screen, using the sidebar's own answer.
+ *
+ * A page is entitled to the name the merchant clicked to get there, and the
+ * naming is not simple: seven archetypes reach /dashboard/catalog under seven
+ * nouns, one row survives, and what that row is called depends on whether the
+ * archetypes behind it agree (a restaurant with a takeaway kitchen reads
+ * "Menu") or not (add a retail shelf and it reads "Catalog").
+ *
+ * So this does not re-derive it. It runs the same decision the sidebar runs,
+ * over the archetypes the current view is narrowed to. Naming the page from
+ * `intentConfig.primary` was the old answer and it was whichever archetype had
+ * last been visited — a restaurant's Menu opened a screen titled Plans.
+ *
+ * `itemId` is the nav item's id, the same one the sidebar builds from:
+ * 'catalog', 'orders', 'resources'.
+ */
+export declare function useDestinationLabel(itemId: string): string | undefined;

package/dist/intents/use-destination-label.js

@@ -0,0 +1,45 @@
+"use client";
+import { useMemo } from "react";
+import { usePathname } from "@withpotter/lib/use-pathname";
+import { useAuth } from "../auth-context";
+import { useIntentConfig } from "./use-intent-config";
+import { INTENT_NAV_DEFINITIONS } from "./intent-nav";
+import { decideSharedNav, navDecisionKey } from "./collapse-shared-nav";
+import { moduleLabelFor } from "./use-entity-label";
+import { useScopeLabels } from "./intent-scope";
+function useDestinationLabel(itemId) {
+  const { tenant } = useAuth();
+  const routeTitle = useScopeLabels()?.title;
+  const config = useIntentConfig();
+  const pathname = usePathname();
+  const moduleLabels = tenant?.settings?.moduleLabels;
+  return useMemo(() => {
+    if (routeTitle) return routeTitle;
+    const narrowed = new Set(config.activeKeys);
+    const definitions = INTENT_NAV_DEFINITIONS.filter(
+      (d) => narrowed.has(d.key)
+    );
+    const decisions = decideSharedNav(
+      definitions,
+      config.mode === "multi" && definitions.length > 1 ? "multi" : "single"
+    );
+    let fallback;
+    for (const definition of definitions) {
+      for (const item of definition.items) {
+        if (item.id !== itemId) continue;
+        const decision = decisions.get(navDecisionKey(definition.key, item.id));
+        if (!decision?.emit) continue;
+        const target = config.all.find((c) => c.key === definition.key)?.navigation.groups.flatMap((g) => g.items).find((i) => i.id === itemId)?.href.split("?")[0];
+        const label = moduleLabelFor(moduleLabels, itemId, target) ?? decision.label;
+        if (target && (pathname === target || pathname.startsWith(target + "/")))
+          return label;
+        fallback ??= label;
+      }
+    }
+    return fallback;
+  }, [config, itemId, moduleLabels, pathname, routeTitle]);
+}
+export {
+  useDestinationLabel
+};
+//# sourceMappingURL=use-destination-label.js.map

package/dist/intents/use-destination-label.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/intents/use-destination-label.ts"],"sourcesContent":["'use client';\n\nimport { useMemo } from 'react';\nimport { usePathname } from '@withpotter/lib/use-pathname';\nimport { useAuth } from '../auth-context';\nimport { useIntentConfig } from './use-intent-config';\nimport { INTENT_NAV_DEFINITIONS } from './intent-nav';\nimport { decideSharedNav, navDecisionKey } from './collapse-shared-nav';\nimport { moduleLabelFor } from './use-entity-label';\nimport { useScopeLabels } from './intent-scope';\n\n/**\n * What to title a screen, using the sidebar's own answer.\n *\n * A page is entitled to the name the merchant clicked to get there, and the\n * naming is not simple: seven archetypes reach /dashboard/catalog under seven\n * nouns, one row survives, and what that row is called depends on whether the\n * archetypes behind it agree (a restaurant with a takeaway kitchen reads\n * \"Menu\") or not (add a retail shelf and it reads \"Catalog\").\n *\n * So this does not re-derive it. It runs the same decision the sidebar runs,\n * over the archetypes the current view is narrowed to. Naming the page from\n * `intentConfig.primary` was the old answer and it was whichever archetype had\n * last been visited — a restaurant's Menu opened a screen titled Plans.\n *\n * `itemId` is the nav item's id, the same one the sidebar builds from:\n * 'catalog', 'orders', 'resources'.\n */\nexport function useDestinationLabel(itemId: string): string | undefined {\n  const { tenant } = useAuth();\n  // A composed screen is named by the route that mounts it.\n  const routeTitle = useScopeLabels()?.title;\n  const config = useIntentConfig();\n  const pathname = usePathname();\n\n  const moduleLabels = (tenant?.settings as Record<string, unknown> | undefined)\n    ?.moduleLabels as Record<string, string> | undefined;\n\n  return useMemo(() => {\n    if (routeTitle) return routeTitle;\n    const narrowed = new Set(config.activeKeys);\n    const definitions = INTENT_NAV_DEFINITIONS.filter((d) =>\n      narrowed.has(d.key),\n    );\n    const decisions = decideSharedNav(\n      definitions,\n      config.mode === 'multi' && definitions.length > 1 ? 'multi' : 'single',\n    );\n\n    /**\n     * An item id can lead to more than one SCREEN, so the id alone cannot name\n     * the page.\n     *\n     * `orders` is the case: take-bookings and rent-property open\n     * `/dashboard/bookings` under it, every other archetype opens\n     * `/dashboard/orders`. Taking the first emitted decision for the id gave a\n     * combined business a Kitchen Orders queue headed \"Bookings\", because\n     * take-bookings is declared first — the row and the page disagreeing about\n     * the same screen, one level up from where that was last fixed.\n     *\n     * So prefer the decision whose destination is the page we are actually on,\n     * and fall back to the first only when nothing resolves (a detail route\n     * below the list, say).\n     */\n    let fallback: string | undefined;\n\n    for (const definition of definitions) {\n      for (const item of definition.items) {\n        if (item.id !== itemId) continue;\n        const decision = decisions.get(navDecisionKey(definition.key, item.id));\n        if (!decision?.emit) continue;\n\n        const target = config.all\n          .find((c) => c.key === definition.key)\n          ?.navigation.groups.flatMap((g) => g.items)\n          .find((i) => i.id === itemId)\n          ?.href.split('?')[0];\n\n        // The merchant's own word outranks every archetype's, and it is stored\n        // against the destination — so it can only be resolved once we know\n        // which destination this row leads to.\n        const label =\n          moduleLabelFor(moduleLabels, itemId, target) ?? decision.label;\n\n        if (\n          target &&\n          (pathname === target || pathname.startsWith(target + '/'))\n        )\n          return label;\n        fallback ??= label;\n      }\n    }\n\n    return fallback;\n  }, [config, itemId, moduleLabels, pathname, routeTitle]);\n}\n"],"mappings":";AAEA,SAAS,eAAe;AACxB,SAAS,mBAAmB;AAC5B,SAAS,eAAe;AACxB,SAAS,uBAAuB;AAChC,SAAS,8BAA8B;AACvC,SAAS,iBAAiB,sBAAsB;AAChD,SAAS,sBAAsB;AAC/B,SAAS,sBAAsB;AAmBxB,SAAS,oBAAoB,QAAoC;AACtE,QAAM,EAAE,OAAO,IAAI,QAAQ;AAE3B,QAAM,aAAa,eAAe,GAAG;AACrC,QAAM,SAAS,gBAAgB;AAC/B,QAAM,WAAW,YAAY;AAE7B,QAAM,eAAgB,QAAQ,UAC1B;AAEJ,SAAO,QAAQ,MAAM;AACnB,QAAI,WAAY,QAAO;AACvB,UAAM,WAAW,IAAI,IAAI,OAAO,UAAU;AAC1C,UAAM,cAAc,uBAAuB;AAAA,MAAO,CAAC,MACjD,SAAS,IAAI,EAAE,GAAG;AAAA,IACpB;AACA,UAAM,YAAY;AAAA,MAChB;AAAA,MACA,OAAO,SAAS,WAAW,YAAY,SAAS,IAAI,UAAU;AAAA,IAChE;AAiBA,QAAI;AAEJ,eAAW,cAAc,aAAa;AACpC,iBAAW,QAAQ,WAAW,OAAO;AACnC,YAAI,KAAK,OAAO,OAAQ;AACxB,cAAM,WAAW,UAAU,IAAI,eAAe,WAAW,KAAK,KAAK,EAAE,CAAC;AACtE,YAAI,CAAC,UAAU,KAAM;AAErB,cAAM,SAAS,OAAO,IACnB,KAAK,CAAC,MAAM,EAAE,QAAQ,WAAW,GAAG,GACnC,WAAW,OAAO,QAAQ,CAAC,MAAM,EAAE,KAAK,EACzC,KAAK,CAAC,MAAM,EAAE,OAAO,MAAM,GAC1B,KAAK,MAAM,GAAG,EAAE,CAAC;AAKrB,cAAM,QACJ,eAAe,cAAc,QAAQ,MAAM,KAAK,SAAS;AAE3D,YACE,WACC,aAAa,UAAU,SAAS,WAAW,SAAS,GAAG;AAExD,iBAAO;AACT,qBAAa;AAAA,MACf;AAAA,IACF;AAEA,WAAO;AAAA,EACT,GAAG,CAAC,QAAQ,QAAQ,cAAc,UAAU,UAAU,CAAC;AACzD;","names":[]}

package/dist/intents/use-entity-label.d.ts

@@ -0,0 +1,32 @@
+import type { EntityLabel } from './types';
+/**
+ * The four nouns a business renames. Anything not in here is back-office
+ * furniture and keeps its platform name — see the note on precedence below.
+ */
+export type EntitySlot = 'item' | 'order' | 'booking' | 'resource';
+/**
+ * Destination → the module id the merchant's rename is stored under.
+ *
+ * A rename belongs to a SCREEN, and a nav item id does not identify one. Two
+ * different ids reach the catalogue (`catalog`, stored as `inventory`), and one
+ * id reaches two different screens: `orders` opens `/dashboard/orders` for a
+ * kitchen and `/dashboard/bookings` for a tee sheet, which are the `orders` and
+ * `bookings` modules respectively.
+ *
+ * Keying on the id gave a business that had renamed Inventory to "Properties"
+ * and Bookings to "Reservations" a sidebar reading "Catalog" and "Bookings"
+ * over pages reading "Properties" and "Reservations" — the rename reaching the
+ * page (which resolves through MODULE_KEY above) and not the row.
+ */
+export declare const MODULE_BY_PATH: Record<string, string>;
+/**
+ * The merchant's own word for a nav destination, if they have set one.
+ *
+ * `href` answers it where a destination is known. `navItemId` is the fallback,
+ * and is right for the fixed spine, whose ids ARE module ids.
+ */
+export declare function moduleLabelFor(moduleLabels: Record<string, string> | undefined, navItemId: string, href?: string): string | undefined;
+/** "Courts" → "Court". Good enough for the regular English plurals merchants
+ *  actually type; anything irregular is served by the config's own singular. */
+export declare function singularise(plural: string): string;
+export declare function useEntityLabel(slot: EntitySlot): EntityLabel;

package/dist/intents/use-entity-label.js

@@ -0,0 +1,75 @@
+"use client";
+import { useAuth } from "../auth-context";
+import { useIntentConfig } from "./use-intent-config";
+import { useScopeLabels } from "./intent-scope";
+const MODULE_KEY = {
+  item: "inventory",
+  order: "orders",
+  booking: "bookings",
+  resource: "resources"
+};
+const MODULE_BY_PATH = {
+  "/dashboard/catalog": "inventory",
+  "/dashboard/orders": "orders",
+  "/dashboard/bookings": "bookings",
+  "/dashboard/resources": "resources",
+  "/dashboard/customers": "customers",
+  "/dashboard/invoices": "invoices",
+  "/dashboard/subscriptions": "subscriptions"
+};
+function moduleLabelFor(moduleLabels, navItemId, href) {
+  if (!moduleLabels) return void 0;
+  const byPath = href ? MODULE_BY_PATH[href.split("?")[0]] : void 0;
+  return (byPath ? moduleLabels[byPath] : void 0) ?? moduleLabels[navItemId];
+}
+const GENERIC = {
+  item: { singular: "Item", plural: "Items" },
+  order: { singular: "Order", plural: "Orders" },
+  booking: { singular: "Booking", plural: "Bookings" },
+  resource: { singular: "Resource", plural: "Resources" }
+};
+function singularise(plural) {
+  if (/ies$/i.test(plural)) return plural.replace(/ies$/i, "y");
+  if (/(ches|shes|sses|xes)$/i.test(plural)) return plural.replace(/es$/i, "");
+  if (/s$/i.test(plural) && !/ss$/i.test(plural))
+    return plural.replace(/s$/i, "");
+  return plural;
+}
+function archetypeLabel(config, slot) {
+  if (config.mode !== "multi" || !config.isAllIntents)
+    return config.primary.entities[slot] ?? GENERIC[slot];
+  const labels = config.all.map((c) => c.entities[slot] ?? GENERIC[slot]);
+  const counted = /* @__PURE__ */ new Map();
+  for (const label of labels)
+    counted.set(label.plural, (counted.get(label.plural) ?? 0) + 1);
+  const [leader, votes] = [...counted].reduce(
+    (best, entry) => entry[1] > best[1] ? entry : best
+  );
+  return votes * 2 > labels.length ? labels.find((label) => label.plural === leader) ?? GENERIC[slot] : GENERIC[slot];
+}
+function useEntityLabel(slot) {
+  const { tenant } = useAuth();
+  const config = useIntentConfig();
+  const declared = useScopeLabels()?.vocabulary[slot];
+  if (declared) return { singular: declared[0], plural: declared[1] };
+  const fromArchetype = archetypeLabel(config, slot);
+  const moduleLabels = tenant?.settings?.moduleLabels;
+  const merchantPlural = moduleLabels?.[MODULE_KEY[slot]];
+  if (!merchantPlural || merchantPlural === fromArchetype.plural) {
+    return fromArchetype;
+  }
+  if (singularise(merchantPlural) === merchantPlural) {
+    return fromArchetype;
+  }
+  return {
+    singular: singularise(merchantPlural),
+    plural: merchantPlural
+  };
+}
+export {
+  MODULE_BY_PATH,
+  moduleLabelFor,
+  singularise,
+  useEntityLabel
+};
+//# sourceMappingURL=use-entity-label.js.map

package/dist/intents/use-entity-label.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/intents/use-entity-label.ts"],"sourcesContent":["'use client';\n\nimport { useAuth } from '../auth-context';\nimport { useIntentConfig } from './use-intent-config';\nimport { useScopeLabels } from './intent-scope';\nimport type { EntityLabel } from './types';\n\n/**\n * The four nouns a business renames. Anything not in here is back-office\n * furniture and keeps its platform name — see the note on precedence below.\n */\nexport type EntitySlot = 'item' | 'order' | 'booking' | 'resource';\n\n/** Which `settings.moduleLabels` key the merchant renames each slot under. */\nconst MODULE_KEY: Record<EntitySlot, string> = {\n  item: 'inventory',\n  order: 'orders',\n  booking: 'bookings',\n  resource: 'resources',\n};\n\n/**\n * Destination → the module id the merchant's rename is stored under.\n *\n * A rename belongs to a SCREEN, and a nav item id does not identify one. Two\n * different ids reach the catalogue (`catalog`, stored as `inventory`), and one\n * id reaches two different screens: `orders` opens `/dashboard/orders` for a\n * kitchen and `/dashboard/bookings` for a tee sheet, which are the `orders` and\n * `bookings` modules respectively.\n *\n * Keying on the id gave a business that had renamed Inventory to \"Properties\"\n * and Bookings to \"Reservations\" a sidebar reading \"Catalog\" and \"Bookings\"\n * over pages reading \"Properties\" and \"Reservations\" — the rename reaching the\n * page (which resolves through MODULE_KEY above) and not the row.\n */\nexport const MODULE_BY_PATH: Record<string, string> = {\n  '/dashboard/catalog': 'inventory',\n  '/dashboard/orders': 'orders',\n  '/dashboard/bookings': 'bookings',\n  '/dashboard/resources': 'resources',\n  '/dashboard/customers': 'customers',\n  '/dashboard/invoices': 'invoices',\n  '/dashboard/subscriptions': 'subscriptions',\n};\n\n/**\n * The merchant's own word for a nav destination, if they have set one.\n *\n * `href` answers it where a destination is known. `navItemId` is the fallback,\n * and is right for the fixed spine, whose ids ARE module ids.\n */\nexport function moduleLabelFor(\n  moduleLabels: Record<string, string> | undefined,\n  navItemId: string,\n  href?: string,\n): string | undefined {\n  if (!moduleLabels) return undefined;\n  const byPath = href ? MODULE_BY_PATH[href.split('?')[0]] : undefined;\n  return (byPath ? moduleLabels[byPath] : undefined) ?? moduleLabels[navItemId];\n}\n\n/** Last resort, for archetypes that never named a slot. */\nconst GENERIC: Record<EntitySlot, EntityLabel> = {\n  item: { singular: 'Item', plural: 'Items' },\n  order: { singular: 'Order', plural: 'Orders' },\n  booking: { singular: 'Booking', plural: 'Bookings' },\n  resource: { singular: 'Resource', plural: 'Resources' },\n};\n\n/** \"Courts\" → \"Court\". Good enough for the regular English plurals merchants\n *  actually type; anything irregular is served by the config's own singular. */\nexport function singularise(plural: string): string {\n  if (/ies$/i.test(plural)) return plural.replace(/ies$/i, 'y');\n  if (/(ches|shes|sses|xes)$/i.test(plural)) return plural.replace(/es$/i, '');\n  if (/s$/i.test(plural) && !/ss$/i.test(plural))\n    return plural.replace(/s$/i, '');\n  return plural;\n}\n\n/**\n * What this business calls one of its four renameable nouns.\n *\n * Precedence, highest first:\n *\n *   1. The merchant's own word — `settings.moduleLabels[key]`. A club that\n *      renamed the module to \"Courts\" gets Courts everywhere.\n *   2. The archetype's word — `entities[slot]` on the intent config. A\n *      restaurant gets Table, a short-let Property, an events business Venue.\n *   3. A neutral platform noun, for archetypes that do not model the slot.\n *\n * The industry config is deliberately NOT in this chain. Industry is inferred\n * (`useIndustryKey` falls back through a stale 'hospitality' default and an\n * intent guess), while the archetype is what the merchant actually picked. When\n * the two disagreed the industry used to win, which is how a bookings club with\n * a sidebar saying \"Services\" was told to \"Add your first product\". Industry\n * still owns the nouns no archetype models — collection, category — and those\n * are read straight from `getIndustryConfig`.\n *\n * Only these four slots take an ARCHETYPE's word. Payments, Analytics,\n * Marketing, Settings and Website keep their platform names on purpose: a\n * merchant running four archetypes needs one back office, not four.\n *\n * That is a rule about archetypes, not about the merchant. Anything they\n * rename in Settings is their word everywhere, Customers included — one word\n * typed once does not fragment a back office. Those renames resolve through\n * `useModuleLabel` / `moduleLabelFor` rather than here.\n */\n/**\n * The archetype's word, on a screen that covers more than one archetype.\n *\n * `primary` is the wrong source here: on an unscoped view it is whichever\n * archetype carried the last `?intent=`, so a combined restaurant's catalog\n * invited you to \"Add plan\" the moment you had visited Subscriptions. Where\n * every active archetype agrees on the noun the answer is obvious — a place\n * doing dine-in and takeaway has Menu Items either way. Where they disagree\n * there is no true word for the mixed list, and the neutral platform noun is\n * the honest one, matching the neutral nouns the sidebar collapses to.\n */\nfunction archetypeLabel(\n  config: ReturnType<typeof useIntentConfig>,\n  slot: EntitySlot,\n): EntityLabel {\n  if (config.mode !== 'multi' || !config.isAllIntents)\n    return config.primary.entities[slot] ?? GENERIC[slot];\n\n  const labels = config.all.map((c) => c.entities[slot] ?? GENERIC[slot]);\n\n  /**\n   * A majority carries the noun, matching the sidebar exactly.\n   *\n   * This required unanimity, and the sidebar's collapse no longer does — so a\n   * restaurant that also ticketed its Friday night read **Menu** on the row and\n   * **Items** on the page it opened. That split is the one thing this app\n   * treats as a bug wherever it appears; the two rules have to be the same\n   * rule.\n   *\n   * Strictly more than half, so a two-way tie stays a dispute and falls to the\n   * neutral noun, which is what the collapse does with it too.\n   */\n  const counted = new Map<string, number>();\n  for (const label of labels)\n    counted.set(label.plural, (counted.get(label.plural) ?? 0) + 1);\n\n  const [leader, votes] = [...counted].reduce((best, entry) =>\n    entry[1] > best[1] ? entry : best,\n  );\n\n  return votes * 2 > labels.length\n    ? (labels.find((label) => label.plural === leader) ?? GENERIC[slot])\n    : GENERIC[slot];\n}\n\nexport function useEntityLabel(slot: EntitySlot): EntityLabel {\n  const { tenant } = useAuth();\n  const config = useIntentConfig();\n  // A composed screen speaks the nouns its composer file declared.\n  const declared = useScopeLabels()?.vocabulary[slot];\n  if (declared) return { singular: declared[0], plural: declared[1] };\n\n  const fromArchetype = archetypeLabel(config, slot);\n\n  const moduleLabels = tenant?.settings?.moduleLabels as\n    Record<string, string> | undefined;\n  const merchantPlural = moduleLabels?.[MODULE_KEY[slot]];\n\n  if (!merchantPlural || merchantPlural === fromArchetype.plural) {\n    return fromArchetype;\n  }\n\n  /**\n   * A RENAME IS A NAV LABEL. IT IS ONLY A PLURAL IF IT LOOKS LIKE ONE.\n   *\n   * `moduleLabels` holds one string, and this treated it as the plural and\n   * derived the singular from it. That works for the word merchants usually\n   * type — \"Courts\", \"Stays\", \"Treatments\" — and breaks on the ones that name\n   * the SECTION rather than the things in it. A restaurant renaming its\n   * catalogue to \"Menu\" then got \"2 menu low on stock\" on the home and \"Which\n   * menu are running low?\" in the ask bar, because every caller lowercases\n   * this and drops it into a count. A restaurant has one menu and many items\n   * on it.\n   *\n   * `singularise` returning the word unchanged is exactly the test: it means\n   * the word carries no plural inflection we can recognise, so it cannot be\n   * trusted to complete \"2 ___\". The archetype's own pair is used for counted\n   * phrases instead, and the merchant's word still names the nav row — that\n   * comes through `moduleLabelFor`, which is a different path and unaffected.\n   */\n  if (singularise(merchantPlural) === merchantPlural) {\n    return fromArchetype;\n  }\n\n  return {\n    singular: singularise(merchantPlural),\n    plural: merchantPlural,\n  };\n}\n"],"mappings":";AAEA,SAAS,eAAe;AACxB,SAAS,uBAAuB;AAChC,SAAS,sBAAsB;AAU/B,MAAM,aAAyC;AAAA,EAC7C,MAAM;AAAA,EACN,OAAO;AAAA,EACP,SAAS;AAAA,EACT,UAAU;AACZ;AAgBO,MAAM,iBAAyC;AAAA,EACpD,sBAAsB;AAAA,EACtB,qBAAqB;AAAA,EACrB,uBAAuB;AAAA,EACvB,wBAAwB;AAAA,EACxB,wBAAwB;AAAA,EACxB,uBAAuB;AAAA,EACvB,4BAA4B;AAC9B;AAQO,SAAS,eACd,cACA,WACA,MACoB;AACpB,MAAI,CAAC,aAAc,QAAO;AAC1B,QAAM,SAAS,OAAO,eAAe,KAAK,MAAM,GAAG,EAAE,CAAC,CAAC,IAAI;AAC3D,UAAQ,SAAS,aAAa,MAAM,IAAI,WAAc,aAAa,SAAS;AAC9E;AAGA,MAAM,UAA2C;AAAA,EAC/C,MAAM,EAAE,UAAU,QAAQ,QAAQ,QAAQ;AAAA,EAC1C,OAAO,EAAE,UAAU,SAAS,QAAQ,SAAS;AAAA,EAC7C,SAAS,EAAE,UAAU,WAAW,QAAQ,WAAW;AAAA,EACnD,UAAU,EAAE,UAAU,YAAY,QAAQ,YAAY;AACxD;AAIO,SAAS,YAAY,QAAwB;AAClD,MAAI,QAAQ,KAAK,MAAM,EAAG,QAAO,OAAO,QAAQ,SAAS,GAAG;AAC5D,MAAI,yBAAyB,KAAK,MAAM,EAAG,QAAO,OAAO,QAAQ,QAAQ,EAAE;AAC3E,MAAI,MAAM,KAAK,MAAM,KAAK,CAAC,OAAO,KAAK,MAAM;AAC3C,WAAO,OAAO,QAAQ,OAAO,EAAE;AACjC,SAAO;AACT;AAyCA,SAAS,eACP,QACA,MACa;AACb,MAAI,OAAO,SAAS,WAAW,CAAC,OAAO;AACrC,WAAO,OAAO,QAAQ,SAAS,IAAI,KAAK,QAAQ,IAAI;AAEtD,QAAM,SAAS,OAAO,IAAI,IAAI,CAAC,MAAM,EAAE,SAAS,IAAI,KAAK,QAAQ,IAAI,CAAC;AActE,QAAM,UAAU,oBAAI,IAAoB;AACxC,aAAW,SAAS;AAClB,YAAQ,IAAI,MAAM,SAAS,QAAQ,IAAI,MAAM,MAAM,KAAK,KAAK,CAAC;AAEhE,QAAM,CAAC,QAAQ,KAAK,IAAI,CAAC,GAAG,OAAO,EAAE;AAAA,IAAO,CAAC,MAAM,UACjD,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,QAAQ;AAAA,EAC/B;AAEA,SAAO,QAAQ,IAAI,OAAO,SACrB,OAAO,KAAK,CAAC,UAAU,MAAM,WAAW,MAAM,KAAK,QAAQ,IAAI,IAChE,QAAQ,IAAI;AAClB;AAEO,SAAS,eAAe,MAA+B;AAC5D,QAAM,EAAE,OAAO,IAAI,QAAQ;AAC3B,QAAM,SAAS,gBAAgB;AAE/B,QAAM,WAAW,eAAe,GAAG,WAAW,IAAI;AAClD,MAAI,SAAU,QAAO,EAAE,UAAU,SAAS,CAAC,GAAG,QAAQ,SAAS,CAAC,EAAE;AAElE,QAAM,gBAAgB,eAAe,QAAQ,IAAI;AAEjD,QAAM,eAAe,QAAQ,UAAU;AAEvC,QAAM,iBAAiB,eAAe,WAAW,IAAI,CAAC;AAEtD,MAAI,CAAC,kBAAkB,mBAAmB,cAAc,QAAQ;AAC9D,WAAO;AAAA,EACT;AAoBA,MAAI,YAAY,cAAc,MAAM,gBAAgB;AAClD,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,UAAU,YAAY,cAAc;AAAA,IACpC,QAAQ;AAAA,EACV;AACF;","names":[]}

package/dist/intents/use-intent-config.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedIntentConfig } from './types';
+/**
+ * Resolves the active intent configuration for the current tenant.
+ *
+ * Resolution order:
+ *   1. tenant.settings.operatingModel profiles → derive active intents
+ *   2. tenant.settings.selectedIntents → backward compatibility when no operating model exists
+ *   3. If no intents, infer from tenant.settings.enabledBehaviors
+ *   4. If still nothing, return defaultCommerceConfig
+ *
+ * The tenant's operating shell (fulfillment/shipping visibility) is folded
+ * onto each config's orderDisplay here, so every consumer reads a single
+ * pre-merged config — no separate useOperatingModel hook or per-page merge.
+ *
+ * In multi-intent mode, the primary config is determined by:
+ *   1. ?intent= query param (if present, also persisted to sessionStorage)
+ *   2. sessionStorage (set by previous navigation)
+ *   3. First config (default)
+ */
+export declare function useIntentConfig(): ResolvedIntentConfig;