@withpotter/lib 0.13.0-next.101

package/dist/fulfilment-nav.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/fulfilment-nav.ts"],"sourcesContent":["/**\n * The words for how orders reach people, in one place.\n *\n * THE WORD WAS FORKED. The page at `/dashboard/settings/shipping` is a\n * component called `DeliverySettingsPage` with the title \"Delivery\", and every\n * row that pointed at it said \"Shipping\" — the sidebar's Selling group, the\n * spine's Operations group, the platform-module list, the mobile Store screen\n * (which said \"Shipping & delivery\", both words at once), the help topic and\n * the capability reveal. A merchant clicked Shipping and landed on Delivery.\n *\n * Underneath, the two are not synonyms at all: they are SIBLINGS. A zone's\n * `method` is `delivery` (a rider of the merchant's own) or `shipping` (a\n * courier), and an order's `deliveryMethod` is pickup / delivery / shipping /\n * none. So \"Delivery\" was doing duty as both the parent — every way an order\n * moves — and one of its children.\n *\n * Delivery wins as the parent. It is the word merchants here use, it covers a\n * courier without straining, and \"shipping\" implies a parcel service in a\n * market where most orders go out on a bike. The child stops using it: the\n * two sections are \"Your riders\" and \"Couriers\". The stored values `delivery`\n * and `shipping` are untouched — those are API contract, not copy — and so are\n * the `shippable` / `hideShipping` behavior flags, which no merchant reads.\n *\n * Six files spelled this destination's label by hand, so renaming it meant\n * finding all six. They import from here now, and\n * `fulfilment-nav.test.ts` fails the build when a seventh types it out.\n *\n * The `href` on each row is deliberately still written out at the call site.\n * The route never drifted — all six agreed on it — and the sibling contract\n * guards read nav sources as TEXT: `tab-title-coverage` learns which routes\n * have a nav row by matching `href: '…'`, so folding the literal into a\n * constant made three settings screens report themselves nameless. The href\n * here is for the places that link without declaring a row.\n */\n\n/** Where orders go and what it costs. Zones, rates, collection. */\nexport const DELIVERY_NAV = {\n  href: '/dashboard/business/shipping',\n  label: 'Delivery',\n} as const;\n\n/**\n * The places the business operates FROM. Origins, counters, staff.\n *\n * \"Business locations\", not \"Locations\". The bare word is the most overloaded\n * noun in this settings tree — a service area is a location row, a shipping\n * zone names locations, a booking resource has one — so a merchant reading\n * \"Locations\" in the rail had no way to know which of those it opened. The\n * qualifier says whose: the branches the business itself operates from.\n */\nexport const LOCATIONS_NAV = {\n  href: '/dashboard/operations/locations',\n  label: 'Business locations',\n} as const;\n\n/**\n * RETIRED. A zone is the delivery footprint now.\n *\n * This named a list of country/state/city rows (`location_catalog`) that\n * carried geography and nothing else — a copy of the delivery zones a merchant\n * had already drawn, kept in step by hand, and free to disagree with them: the\n * checkout dropdown came from one and the price from the other.\n *\n * The zone is the one that does work. `public/locations/hierarchy` already\n * derived the dropdown from zones whenever this list was empty (which most\n * tenants' was), and `get-fulfilment-options` already refuses a delivery it\n * cannot match to a zone, offering collection instead. So this row asked\n * merchants to state their footprint a second time for nothing.\n *\n * Left as a comment rather than deleted silently, because the word will come\n * back otherwise: whatever names a delivery footprint next, it is a zone.\n */\n\n/**\n * The two methods, as a merchant reads them.\n *\n * Keyed on the stored value so a section heading and a zone's badge cannot\n * disagree about what `method: 'shipping'` is called.\n */\nexport const DELIVERY_METHOD_LABELS = {\n  delivery: 'Your riders',\n  shipping: 'Couriers',\n} as const;\n"],"mappings":"AAoCO,MAAM,eAAe;AAAA,EAC1B,MAAM;AAAA,EACN,OAAO;AACT;AAWO,MAAM,gBAAgB;AAAA,EAC3B,MAAM;AAAA,EACN,OAAO;AACT;AA0BO,MAAM,yBAAyB;AAAA,EACpC,UAAU;AAAA,EACV,UAAU;AACZ;","names":[]}

package/dist/go-live-gate.d.ts

@@ -0,0 +1,55 @@
+import type { HostReadinessKey, ReadinessBlocker, StorefrontReadiness } from '@withpotter/lib/api/types';
+/**
+ * The two questions the go-live gate asks, as functions rather than as
+ * conditions inside a component.
+ *
+ * They live here, pure and tested, because both of them fail in a direction
+ * that is much worse than the bug they exist to prevent, and neither failure
+ * is visible in review:
+ *
+ *   - block when the answer has not arrived, and every merchant on an older
+ *     backend is locked out of publishing their own shop
+ *   - interrupt on any blocker, and a shop that sells perfectly well gets a
+ *     dialog on every screen about its payout account
+ *
+ * `use-storefront-readiness` and `StoreCannotSellGate` both read from here so
+ * there is one answer rather than two that can drift apart. The dashboard has
+ * a habit of the second copy disagreeing with the first.
+ */
+/**
+ * Does anything stop this store going live?
+ *
+ * NOT-ASKED IS NOT NOT-READY. `null`/`undefined` means the check has not
+ * answered — it is still in flight, or the backend does not serve the route at
+ * all — and that must read as "do not stop them". A gate written the other way
+ * round refuses every publish on any API older than the readiness endpoint,
+ * which locks a merchant out of their own storefront in order to protect a
+ * checkout that was never broken. The gate blocks only on blockers it has
+ * actually been handed.
+ */
+export declare function blocksGoLive(readiness: StorefrontReadiness | null | undefined): boolean;
+/**
+ * Is this store unable to complete a sale right now?
+ *
+ * `reachable` ONLY, and the narrowness is the point. The other two blockers are
+ * serious and neither stops a customer buying: a shop with no payout account
+ * still takes the order (the money lands in Box's own account, which has its
+ * own worklist row), and one with no contact details still sells. Only an empty
+ * address book turns the checkout into a form that cannot be submitted —
+ * `GetLocationHierarchyUseCase` derives the country, state and city selects
+ * from active delivery zones, and web-render renders all three as selects with
+ * no free-text escape and city required.
+ *
+ * That is the difference between a setting somebody should get round to and a
+ * shop silently refusing every sale, and only the second earns an interruption.
+ */
+export declare function cannotCompleteSale(readiness: StorefrontReadiness | null | undefined): boolean;
+/**
+ * Is this a check the host box added rather than one the dashboard knows?
+ *
+ * A host check blocks going live like any other (`blocksGoLive` counts every
+ * blocker). It has no row of its own in the dashboard's tables, so the
+ * checklist draws it from the blocker's own title and path, or from the
+ * checklist step that carries the same key.
+ */
+export declare function isHostCheck(key: ReadinessBlocker['key'] | string): key is HostReadinessKey;

package/dist/go-live-gate.js

@@ -0,0 +1,17 @@
+function blocksGoLive(readiness) {
+  return (readiness?.blockers ?? []).length > 0;
+}
+function cannotCompleteSale(readiness) {
+  return (readiness?.blockers ?? []).some(
+    (blocker) => blocker.key === "reachable"
+  );
+}
+function isHostCheck(key) {
+  return key.startsWith("host_");
+}
+export {
+  blocksGoLive,
+  cannotCompleteSale,
+  isHostCheck
+};
+//# sourceMappingURL=go-live-gate.js.map

package/dist/go-live-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/go-live-gate.ts"],"sourcesContent":["import type {\n  HostReadinessKey,\n  ReadinessBlocker,\n  StorefrontReadiness,\n} from '@withpotter/lib/api/types';\n\n/**\n * The two questions the go-live gate asks, as functions rather than as\n * conditions inside a component.\n *\n * They live here, pure and tested, because both of them fail in a direction\n * that is much worse than the bug they exist to prevent, and neither failure\n * is visible in review:\n *\n *   - block when the answer has not arrived, and every merchant on an older\n *     backend is locked out of publishing their own shop\n *   - interrupt on any blocker, and a shop that sells perfectly well gets a\n *     dialog on every screen about its payout account\n *\n * `use-storefront-readiness` and `StoreCannotSellGate` both read from here so\n * there is one answer rather than two that can drift apart. The dashboard has\n * a habit of the second copy disagreeing with the first.\n */\n\n/**\n * Does anything stop this store going live?\n *\n * NOT-ASKED IS NOT NOT-READY. `null`/`undefined` means the check has not\n * answered — it is still in flight, or the backend does not serve the route at\n * all — and that must read as \"do not stop them\". A gate written the other way\n * round refuses every publish on any API older than the readiness endpoint,\n * which locks a merchant out of their own storefront in order to protect a\n * checkout that was never broken. The gate blocks only on blockers it has\n * actually been handed.\n */\nexport function blocksGoLive(\n  readiness: StorefrontReadiness | null | undefined,\n): boolean {\n  return (readiness?.blockers ?? []).length > 0;\n}\n\n/**\n * Is this store unable to complete a sale right now?\n *\n * `reachable` ONLY, and the narrowness is the point. The other two blockers are\n * serious and neither stops a customer buying: a shop with no payout account\n * still takes the order (the money lands in Box's own account, which has its\n * own worklist row), and one with no contact details still sells. Only an empty\n * address book turns the checkout into a form that cannot be submitted —\n * `GetLocationHierarchyUseCase` derives the country, state and city selects\n * from active delivery zones, and web-render renders all three as selects with\n * no free-text escape and city required.\n *\n * That is the difference between a setting somebody should get round to and a\n * shop silently refusing every sale, and only the second earns an interruption.\n */\nexport function cannotCompleteSale(\n  readiness: StorefrontReadiness | null | undefined,\n): boolean {\n  return (readiness?.blockers ?? []).some(\n    (blocker) => blocker.key === 'reachable',\n  );\n}\n\n/**\n * Is this a check the host box added rather than one the dashboard knows?\n *\n * A host check blocks going live like any other (`blocksGoLive` counts every\n * blocker). It has no row of its own in the dashboard's tables, so the\n * checklist draws it from the blocker's own title and path, or from the\n * checklist step that carries the same key.\n */\nexport function isHostCheck(\n  key: ReadinessBlocker['key'] | string,\n): key is HostReadinessKey {\n  return key.startsWith('host_');\n}\n"],"mappings":"AAmCO,SAAS,aACd,WACS;AACT,UAAQ,WAAW,YAAY,CAAC,GAAG,SAAS;AAC9C;AAiBO,SAAS,mBACd,WACS;AACT,UAAQ,WAAW,YAAY,CAAC,GAAG;AAAA,IACjC,CAAC,YAAY,QAAQ,QAAQ;AAAA,EAC/B;AACF;AAUO,SAAS,YACd,KACyB;AACzB,SAAO,IAAI,WAAW,OAAO;AAC/B;","names":[]}

package/dist/group-activity.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Activity, grouped the way somebody reads it.
+ *
+ * The feed rendered as a flat list of sentences with a relative time on the
+ * right, and three consecutive rows all said "5d ago". That is not a timeline;
+ * it is the same fact repeated next to different sentences, and it makes the
+ * list read as one undifferentiated block.
+ *
+ * Grouping by day gives it the shape it already had in the data and moves the
+ * time to a heading, where it is said once.
+ */
+export interface ActivityGroup<T> {
+    /** "Today", "Yesterday", or a date. Said once, above the rows. */
+    label: string;
+    /** Sort key, so groups stay newest-first without re-parsing the label. */
+    at: number;
+    entries: T[];
+}
+/**
+ * Named for the reader, not the calendar.
+ *
+ * "Today" and "Yesterday" are how somebody catching up actually thinks; a date
+ * only earns its place once the day stops having a name. Within the current
+ * year the year is dropped, because "12 Aug" is what a person says out loud.
+ */
+export declare function labelForDay(dayStart: number, now: number): string;
+/**
+ * Group newest-first, preserving the order entries arrived in.
+ *
+ * Entries with an unparseable timestamp are kept rather than dropped, under a
+ * heading that says so: losing a row because its date is malformed is worse
+ * than showing it without a day, and silently dropping history is exactly what
+ * an activity feed must never do.
+ */
+export declare function groupByDay<T extends {
+    createdAt: string;
+}>(entries: T[], now?: number): ActivityGroup<T>[];

package/dist/group-activity.js

@@ -0,0 +1,43 @@
+const DAY = 24 * 60 * 60 * 1e3;
+function startOfDay(t) {
+  const d = new Date(t);
+  d.setHours(0, 0, 0, 0);
+  return d.getTime();
+}
+function labelForDay(dayStart, now) {
+  const today = startOfDay(now);
+  if (dayStart === today) return "Today";
+  if (dayStart === today - DAY) return "Yesterday";
+  const d = new Date(dayStart);
+  const sameYear = d.getFullYear() === new Date(now).getFullYear();
+  return d.toLocaleDateString(void 0, {
+    day: "numeric",
+    month: "short",
+    ...sameYear ? {} : { year: "numeric" }
+  });
+}
+function groupByDay(entries, now = Date.now()) {
+  const byDay = /* @__PURE__ */ new Map();
+  const undated = [];
+  for (const entry of entries) {
+    const t = new Date(entry.createdAt).getTime();
+    if (Number.isNaN(t)) {
+      undated.push(entry);
+      continue;
+    }
+    const day = startOfDay(t);
+    const bucket = byDay.get(day);
+    if (bucket) bucket.push(entry);
+    else byDay.set(day, [entry]);
+  }
+  const groups = [...byDay.entries()].sort((a, b) => b[0] - a[0]).map(([at, rows]) => ({ at, label: labelForDay(at, now), entries: rows }));
+  if (undated.length > 0) {
+    groups.push({ at: -Infinity, label: "Undated", entries: undated });
+  }
+  return groups;
+}
+export {
+  groupByDay,
+  labelForDay
+};
+//# sourceMappingURL=group-activity.js.map

package/dist/group-activity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/group-activity.ts"],"sourcesContent":["/**\n * Activity, grouped the way somebody reads it.\n *\n * The feed rendered as a flat list of sentences with a relative time on the\n * right, and three consecutive rows all said \"5d ago\". That is not a timeline;\n * it is the same fact repeated next to different sentences, and it makes the\n * list read as one undifferentiated block.\n *\n * Grouping by day gives it the shape it already had in the data and moves the\n * time to a heading, where it is said once.\n */\nexport interface ActivityGroup<T> {\n  /** \"Today\", \"Yesterday\", or a date. Said once, above the rows. */\n  label: string;\n  /** Sort key, so groups stay newest-first without re-parsing the label. */\n  at: number;\n  entries: T[];\n}\n\nconst DAY = 24 * 60 * 60 * 1000;\n\nfunction startOfDay(t: number): number {\n  const d = new Date(t);\n  d.setHours(0, 0, 0, 0);\n  return d.getTime();\n}\n\n/**\n * Named for the reader, not the calendar.\n *\n * \"Today\" and \"Yesterday\" are how somebody catching up actually thinks; a date\n * only earns its place once the day stops having a name. Within the current\n * year the year is dropped, because \"12 Aug\" is what a person says out loud.\n */\nexport function labelForDay(dayStart: number, now: number): string {\n  const today = startOfDay(now);\n  if (dayStart === today) return 'Today';\n  if (dayStart === today - DAY) return 'Yesterday';\n\n  const d = new Date(dayStart);\n  const sameYear = d.getFullYear() === new Date(now).getFullYear();\n  return d.toLocaleDateString(undefined, {\n    day: 'numeric',\n    month: 'short',\n    ...(sameYear ? {} : { year: 'numeric' }),\n  });\n}\n\n/**\n * Group newest-first, preserving the order entries arrived in.\n *\n * Entries with an unparseable timestamp are kept rather than dropped, under a\n * heading that says so: losing a row because its date is malformed is worse\n * than showing it without a day, and silently dropping history is exactly what\n * an activity feed must never do.\n */\nexport function groupByDay<T extends { createdAt: string }>(\n  entries: T[],\n  now: number = Date.now(),\n): ActivityGroup<T>[] {\n  const byDay = new Map<number, T[]>();\n  const undated: T[] = [];\n\n  for (const entry of entries) {\n    const t = new Date(entry.createdAt).getTime();\n    if (Number.isNaN(t)) {\n      undated.push(entry);\n      continue;\n    }\n    const day = startOfDay(t);\n    const bucket = byDay.get(day);\n    if (bucket) bucket.push(entry);\n    else byDay.set(day, [entry]);\n  }\n\n  const groups = [...byDay.entries()]\n    .sort((a, b) => b[0] - a[0])\n    .map(([at, rows]) => ({ at, label: labelForDay(at, now), entries: rows }));\n\n  if (undated.length > 0) {\n    groups.push({ at: -Infinity, label: 'Undated', entries: undated });\n  }\n  return groups;\n}\n"],"mappings":"AAmBA,MAAM,MAAM,KAAK,KAAK,KAAK;AAE3B,SAAS,WAAW,GAAmB;AACrC,QAAM,IAAI,IAAI,KAAK,CAAC;AACpB,IAAE,SAAS,GAAG,GAAG,GAAG,CAAC;AACrB,SAAO,EAAE,QAAQ;AACnB;AASO,SAAS,YAAY,UAAkB,KAAqB;AACjE,QAAM,QAAQ,WAAW,GAAG;AAC5B,MAAI,aAAa,MAAO,QAAO;AAC/B,MAAI,aAAa,QAAQ,IAAK,QAAO;AAErC,QAAM,IAAI,IAAI,KAAK,QAAQ;AAC3B,QAAM,WAAW,EAAE,YAAY,MAAM,IAAI,KAAK,GAAG,EAAE,YAAY;AAC/D,SAAO,EAAE,mBAAmB,QAAW;AAAA,IACrC,KAAK;AAAA,IACL,OAAO;AAAA,IACP,GAAI,WAAW,CAAC,IAAI,EAAE,MAAM,UAAU;AAAA,EACxC,CAAC;AACH;AAUO,SAAS,WACd,SACA,MAAc,KAAK,IAAI,GACH;AACpB,QAAM,QAAQ,oBAAI,IAAiB;AACnC,QAAM,UAAe,CAAC;AAEtB,aAAW,SAAS,SAAS;AAC3B,UAAM,IAAI,IAAI,KAAK,MAAM,SAAS,EAAE,QAAQ;AAC5C,QAAI,OAAO,MAAM,CAAC,GAAG;AACnB,cAAQ,KAAK,KAAK;AAClB;AAAA,IACF;AACA,UAAM,MAAM,WAAW,CAAC;AACxB,UAAM,SAAS,MAAM,IAAI,GAAG;AAC5B,QAAI,OAAQ,QAAO,KAAK,KAAK;AAAA,QACxB,OAAM,IAAI,KAAK,CAAC,KAAK,CAAC;AAAA,EAC7B;AAEA,QAAM,SAAS,CAAC,GAAG,MAAM,QAAQ,CAAC,EAC/B,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,EAC1B,IAAI,CAAC,CAAC,IAAI,IAAI,OAAO,EAAE,IAAI,OAAO,YAAY,IAAI,GAAG,GAAG,SAAS,KAAK,EAAE;AAE3E,MAAI,QAAQ,SAAS,GAAG;AACtB,WAAO,KAAK,EAAE,IAAI,WAAW,OAAO,WAAW,SAAS,QAAQ,CAAC;AAAA,EACnE;AACA,SAAO;AACT;","names":[]}

package/dist/haptic.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Trigger haptic feedback on supported devices (iOS Safari, Android Chrome).
+ * Falls back silently on unsupported platforms.
+ */
+export declare function haptic(style?: 'light' | 'medium' | 'heavy'): void;

package/dist/haptic.js

@@ -0,0 +1,16 @@
+function haptic(style = "light") {
+  if (typeof navigator === "undefined" || !navigator.vibrate) return;
+  const patterns = {
+    light: 10,
+    medium: 20,
+    heavy: 40
+  };
+  try {
+    navigator.vibrate(patterns[style]);
+  } catch {
+  }
+}
+export {
+  haptic
+};
+//# sourceMappingURL=haptic.js.map

package/dist/haptic.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/haptic.ts"],"sourcesContent":["/**\n * Trigger haptic feedback on supported devices (iOS Safari, Android Chrome).\n * Falls back silently on unsupported platforms.\n */\nexport function haptic(style: 'light' | 'medium' | 'heavy' = 'light') {\n  if (typeof navigator === 'undefined' || !navigator.vibrate) return;\n\n  const patterns: Record<string, number> = {\n    light: 10,\n    medium: 20,\n    heavy: 40,\n  };\n\n  try {\n    navigator.vibrate(patterns[style]);\n  } catch {\n    // Silently fail — vibrate not supported\n  }\n}\n"],"mappings":"AAIO,SAAS,OAAO,QAAsC,SAAS;AACpE,MAAI,OAAO,cAAc,eAAe,CAAC,UAAU,QAAS;AAE5D,QAAM,WAAmC;AAAA,IACvC,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,OAAO;AAAA,EACT;AAEA,MAAI;AACF,cAAU,QAAQ,SAAS,KAAK,CAAC;AAAA,EACnC,QAAQ;AAAA,EAER;AACF;","names":[]}

package/dist/help-topics.d.ts

@@ -0,0 +1,77 @@
+import type { ContentBehavior } from './template-types';
+/**
+ * Help, assembled the same way the nav is.
+ *
+ * Box's dashboard is not one product — it's whatever this business's
+ * behaviors add up to. So a generic help centre is wrong here for the same
+ * reason a generic sidebar would be: a padel club has no shipping questions,
+ * and a fashion brand has no check-in questions. Showing them anyway is how a
+ * help centre teaches merchants that most of it isn't for them, which is how
+ * they stop reading it.
+ *
+ * Topics are gated on `requiredBehavior` exactly like nav items and roles, off
+ * the same `resolveEnabledBehaviors` seam. Everything ungated is universal.
+ *
+ * Content rule: every topic answers a question a merchant would actually ask,
+ * in their words, with steps that match surfaces that exist today. If a topic
+ * can't point at a real screen, it doesn't belong here.
+ */
+export interface HelpTopic {
+    id: string;
+    /** The question, phrased the way a merchant would ask it. */
+    question: string;
+    /** Short answer shown under the question when expanded. */
+    answer: string;
+    /** Concrete steps. Kept short — a wall of steps is a doc, not an answer. */
+    steps?: string[];
+    /** Where to go and do it. Must be a route that exists. */
+    action?: {
+        label: string;
+        href: string;
+    };
+    /**
+     * Routes this topic is the *lead* answer for when help is opened from them.
+     *
+     * `action.href` can't decide this on its own: four topics point at
+     * /dashboard/payments, so ranking by href length made ties fall to
+     * declaration order and every merchant arriving from Payments was told how
+     * to start taking payments — including ones who have been paid for a year.
+     * Leading is a separate claim from "this is where you go to do it".
+     */
+    leadFor?: string[];
+    /** Only shown when the business has one of these behaviors. */
+    requiredBehavior?: ContentBehavior[];
+    /** Extra words the search should match (synonyms merchants actually type). */
+    keywords?: string[];
+    group: HelpGroup;
+}
+export type HelpGroup = 'Money' | 'Selling' | 'Bookings' | 'Invoicing' | 'Your site' | 'Your team' | 'Your account';
+export declare const HELP_GROUP_ORDER: HelpGroup[];
+export declare const HELP_TOPICS: HelpTopic[];
+/** Topics that apply to a business with these behaviors. */
+export declare function resolveHelpTopics(behaviors: ContentBehavior[]): HelpTopic[];
+/**
+ * Search across the question, the answer and the merchant's own synonyms.
+ *
+ * Ranked rather than all-or-nothing. The old rule (every term must appear)
+ * only worked for one- and two-word queries; anything phrased as a question
+ * returned nothing at all — "my customer wants a refund" scored zero while the
+ * refund topic sat right there. Rare words outrank common ones, and a match in
+ * the question outranks one buried in an answer.
+ *
+ * Deliberately not clever beyond this. Seventeen short topics is not enough
+ * text to rank reliably over, so callers must keep a way to reach a person
+ * visible at all times rather than treating a thin result list as coverage.
+ */
+export declare function searchHelpTopics(topics: HelpTopic[], query: string): HelpTopic[];
+/**
+ * The topic most relevant to a dashboard path, so opening help from a screen
+ * starts on that screen's question rather than at the top of a list.
+ *
+ * `leadFor` decides first, because several topics legitimately point at the
+ * same screen and "where you go to do it" is a weaker claim than "this is the
+ * question people have here". Only when nothing claims the route does this
+ * fall back to the deepest `action.href`, which is the old behaviour and still
+ * right for screens with exactly one topic.
+ */
+export declare function topicForPath(topics: HelpTopic[], path: string | null): HelpTopic | null;

package/dist/help-topics.js

@@ -0,0 +1,308 @@
+import { DELIVERY_NAV } from "./fulfilment-nav";
+import { TEAM_PAGE } from "./team-page";
+const HELP_GROUP_ORDER = [
+  "Money",
+  "Selling",
+  "Bookings",
+  "Invoicing",
+  "Your site",
+  "Your team",
+  "Your account"
+];
+const HELP_TOPICS = [
+  // ── Money ───────────────────────────────────────────────────────────
+  {
+    id: "get-paid",
+    group: "Money",
+    question: "How do I start taking payments?",
+    answer: "You add a bank account once. After that, money customers pay you settles to that account instead of sitting with Box.",
+    steps: [
+      "Open Bank account under Money.",
+      "Choose Add bank account.",
+      "Enter the account the money should land in, and check the name matches your business."
+    ],
+    action: { label: "Bank account", href: "/dashboard/payments/payouts" },
+    leadFor: ["/dashboard/payments/payouts"],
+    keywords: ["payout", "bank", "paystack", "settlement", "account"]
+  },
+  {
+    id: "when-paid",
+    group: "Money",
+    question: "When does money actually reach my bank?",
+    answer: 'A payment shows up in Box as soon as it clears. Payouts to your bank follow your provider\u2019s settlement schedule, so the two dates are usually not the same day. Payments shows both, so you can tell "paid" from "paid out".',
+    action: { label: "See your payments", href: "/dashboard/payments" },
+    // Payments is where "why hasn't it landed yet" gets asked, and it's the
+    // only question on that screen a merchant who is already set up still has.
+    leadFor: ["/dashboard/payments"],
+    keywords: [
+      "payout",
+      "settlement",
+      "bank",
+      "late",
+      // The words merchants actually use for this. Without "paid" the topic
+      // lost "when will I get paid" to the manual-transfer topic, which does
+      // carry it.
+      "paid",
+      "money",
+      "received",
+      "waiting"
+    ]
+  },
+  {
+    id: "record-transfer",
+    group: "Money",
+    question: "Someone paid me by transfer. How do I record it?",
+    answer: "Confirm it on the order yourself. Box keeps the record so your totals and the customer\u2019s history stay right, even when the money never went through checkout.",
+    steps: [
+      "Open the order.",
+      "Check the money is actually in your account first.",
+      "Choose Confirm payment."
+    ],
+    action: { label: "Go to orders", href: "/dashboard/orders" },
+    leadFor: ["/dashboard/orders"],
+    keywords: ["transfer", "cash", "manual", "bank", "offline", "paid"]
+  },
+  {
+    id: "refund",
+    group: "Money",
+    question: "How do I refund someone?",
+    answer: "Refund from the order itself, so the refund is attached to what was bought rather than floating loose in your payments. Refund only appears once the payment has settled, because there is nothing to give back before that.",
+    steps: [
+      "Open the order.",
+      "Choose Refund, at the top.",
+      "Full or partial, then confirm."
+    ],
+    action: { label: "Go to orders", href: "/dashboard/orders" },
+    keywords: ["refund", "return", "money back", "cancel"]
+  },
+  // ── Selling ─────────────────────────────────────────────────────────
+  {
+    id: "first-product",
+    group: "Selling",
+    question: "How do I add my first product?",
+    answer: "A name, a price and a photo is enough to start selling. Everything else can be filled in later without taking the product down.",
+    action: { label: "Add a product", href: "/dashboard/catalog" },
+    leadFor: ["/dashboard/catalog"],
+    requiredBehavior: ["sellable"],
+    keywords: ["product", "item", "add", "catalog", "stock", "listing"]
+  },
+  {
+    id: "stock",
+    group: "Selling",
+    question: "Can Box stop me selling something I\u2019ve run out of?",
+    answer: "Yes. Give a product a stock count and checkout stops offering it once it hits zero, so you don\u2019t sell what you can\u2019t ship.",
+    action: { label: "Open inventory", href: "/dashboard/catalog" },
+    requiredBehavior: ["sellable"],
+    keywords: ["stock", "inventory", "sold out", "quantity", "oversell"]
+  },
+  {
+    id: "shipping-rates",
+    group: "Selling",
+    question: "How do I charge for delivery?",
+    answer: "Set your delivery rates once and checkout applies them automatically based on where the customer is.",
+    action: {
+      label: `${DELIVERY_NAV.label} settings`,
+      href: "/dashboard/settings/shipping"
+    },
+    requiredBehavior: ["shippable"],
+    keywords: ["delivery", "shipping", "rate", "dispatch", "courier", "fee"]
+  },
+  {
+    id: "discount",
+    group: "Selling",
+    question: "How do I run a discount?",
+    answer: "Create a code with the amount off and when it expires. Customers enter it at checkout and Box applies it for you.",
+    action: { label: "Open marketing", href: "/dashboard/marketing" },
+    requiredBehavior: ["sellable"],
+    keywords: ["discount", "promo", "coupon", "sale", "code", "off"]
+  },
+  // ── Bookings ────────────────────────────────────────────────────────
+  {
+    id: "take-bookings",
+    group: "Bookings",
+    question: "How do people book a time with me?",
+    answer: "Your opening hours decide what customers can pick. Box only offers times you are actually open and nothing that is already taken, so you don\u2019t get double-booked.",
+    action: { label: "Open your calendar", href: "/dashboard/calendar" },
+    leadFor: ["/dashboard/calendar"],
+    requiredBehavior: ["bookable"],
+    keywords: ["booking", "appointment", "slot", "calendar", "reserve", "time"]
+  },
+  {
+    id: "reschedule",
+    group: "Bookings",
+    question: "A customer wants to move their booking.",
+    answer: "Reschedule it from the booking itself. The customer gets the new time, and the old slot goes back into your availability.",
+    action: { label: "Open your calendar", href: "/dashboard/calendar" },
+    requiredBehavior: ["bookable"],
+    keywords: ["reschedule", "move", "change", "cancel", "booking"]
+  },
+  // ── Invoicing ───────────────────────────────────────────────────────
+  {
+    id: "send-invoice",
+    group: "Invoicing",
+    question: "How do I invoice a customer?",
+    answer: "Build the invoice, send it, and Box tracks whether it has been paid so you\u2019re not chasing from memory.",
+    action: { label: "Open invoices", href: "/dashboard/invoices" },
+    requiredBehavior: ["billable"],
+    keywords: ["invoice", "bill", "quote", "payment link", "owing"]
+  },
+  // ── Your site ───────────────────────────────────────────────────────
+  {
+    id: "edit-site",
+    group: "Your site",
+    question: "How do I change how my site looks?",
+    answer: "Edit it directly. What you see while editing is what customers see, so there is no separate preview to keep in sync.",
+    action: { label: "Open your website", href: "/dashboard/business" },
+    keywords: ["website", "design", "theme", "editor", "brand", "colour"]
+  },
+  {
+    id: "custom-domain",
+    group: "Your site",
+    question: "How do I use my own domain name?",
+    answer: "Point your domain at Box, then confirm it here. DNS changes can take a few hours to spread, and that wait is normal rather than something you broke.",
+    action: { label: "Domain settings", href: "/dashboard/settings/domains" },
+    keywords: ["domain", "dns", "url", "www", "custom", "address"]
+  },
+  // ── Your team ───────────────────────────────────────────────────────
+  {
+    id: "invite-team",
+    group: "Your team",
+    question: "How do I let someone else help run this?",
+    answer: "Invite them by email and pick what they do here. Their role decides which parts of the dashboard they see.",
+    action: { label: "Open your team", href: TEAM_PAGE },
+    leadFor: ["/dashboard/settings/team"],
+    keywords: ["team", "staff", "invite", "member", "add", "colleague"]
+  },
+  {
+    id: "hide-money",
+    group: "Your team",
+    question: "Can I let staff work without seeing my money?",
+    answer: "Yes, and that is the default. Money is a separate switch on every invite, off unless you turn it on, so no role hands out payouts by accident.",
+    action: { label: "Open your team", href: TEAM_PAGE },
+    keywords: ["permission", "money", "hide", "payout", "access", "role"]
+  },
+  // ── Your account ────────────────────────────────────────────────────
+  {
+    id: "multiple-businesses",
+    group: "Your account",
+    question: "Can I run more than one business here?",
+    answer: "Yes. Each business has its own products, orders and site. One login reaches all of them, and you switch from the top of the sidebar.",
+    action: { label: "See your businesses", href: "/dashboard/workspaces" },
+    keywords: ["workspace", "business", "multiple", "switch", "second"]
+  },
+  {
+    id: "change-plan",
+    group: "Your account",
+    question: "How do I change or cancel my plan?",
+    answer: "Plans are per business, so each business has its own. Change or cancel from the business it belongs to.",
+    action: { label: "Plan & billing", href: "/dashboard/settings/billing" },
+    keywords: ["plan", "billing", "upgrade", "cancel", "subscription", "price"]
+  }
+];
+function resolveHelpTopics(behaviors) {
+  const enabled = new Set(behaviors);
+  return HELP_TOPICS.filter(
+    (t) => !t.requiredBehavior?.length || t.requiredBehavior.some((b) => enabled.has(b))
+  );
+}
+const STOP_WORDS = new Set(
+  "a an and are as at be but by can cant do does doesnt for from get give got has have how i if in is it its me my not of on or our so that the their them then there they this to want wants was we what when where which who why will with you your".split(" ")
+);
+const SYNONYMS = {
+  cash: "transfer",
+  shop: "catalog product",
+  store: "catalog product",
+  item: "product",
+  goods: "product",
+  slot: "booking",
+  appointment: "booking",
+  reserve: "booking",
+  staff: "team role",
+  worker: "team role",
+  employee: "team role",
+  site: "website",
+  page: "website"
+};
+function stem(word) {
+  return word.replace(/[^a-z0-9]/g, "").replace(/(ing|ed|es|s)$/, "");
+}
+function queryTerms(query) {
+  const words = query.toLowerCase().split(/\s+/).map((w) => w.replace(/[^a-z0-9]/g, "")).filter((w) => w.length > 1 && !STOP_WORDS.has(w));
+  const out = /* @__PURE__ */ new Set();
+  for (const w of words) {
+    out.add(stem(w));
+    const syn = SYNONYMS[w];
+    if (syn) for (const s of syn.split(" ")) out.add(stem(s));
+  }
+  return [...out];
+}
+function wordSet(parts) {
+  return new Set(
+    parts.filter(Boolean).join(" ").toLowerCase().split(/[^a-z0-9]+/).map(stem).filter(Boolean)
+  );
+}
+const indexCache = /* @__PURE__ */ new WeakMap();
+function indexOf(topics) {
+  const cached = indexCache.get(topics);
+  if (cached) return cached;
+  const docs = topics.map((topic) => ({
+    topic,
+    title: wordSet([topic.question, topic.group, ...topic.keywords ?? []]),
+    body: wordSet([topic.answer, ...topic.steps ?? []])
+  }));
+  const seen = /* @__PURE__ */ new Map();
+  for (const d of docs) {
+    for (const w of /* @__PURE__ */ new Set([...d.title, ...d.body])) {
+      seen.set(w, (seen.get(w) ?? 0) + 1);
+    }
+  }
+  const weight = /* @__PURE__ */ new Map();
+  for (const [w, df] of seen) weight.set(w, Math.log(1 + docs.length / df));
+  const built = { docs, weight };
+  indexCache.set(topics, built);
+  return built;
+}
+function searchHelpTopics(topics, query) {
+  if (!query.trim()) return topics;
+  const terms = queryTerms(query);
+  if (!terms.length) return topics;
+  const { docs, weight } = indexOf(topics);
+  return docs.map((d) => {
+    let score = 0;
+    for (const term of terms) {
+      const w = weight.get(term) ?? 0;
+      if (d.title.has(term)) score += 3 * w;
+      else if (d.body.has(term)) score += w;
+    }
+    return { topic: d.topic, score };
+  }).filter((r) => r.score > 0).sort((a, b) => b.score - a.score).map((r) => r.topic);
+}
+function isUnder(path, base) {
+  return path === base || path.startsWith(base.replace(/\/$/, "") + "/");
+}
+function topicForPath(topics, path) {
+  if (!path) return null;
+  const claimed = topics.filter((t) => t.leadFor?.some((base) => isUnder(path, base))).sort((a, b) => bestLeadDepth(b, path) - bestLeadDepth(a, path));
+  if (claimed[0]) return claimed[0];
+  const matches = topics.filter(
+    (t) => t.action && isUnder(path, t.action.href)
+  );
+  return matches.sort(
+    (a, b) => (b.action?.href.length ?? 0) - (a.action?.href.length ?? 0)
+  )[0] ?? null;
+}
+function bestLeadDepth(topic, path) {
+  let best = 0;
+  for (const base of topic.leadFor ?? []) {
+    if (isUnder(path, base) && base.length > best) best = base.length;
+  }
+  return best;
+}
+export {
+  HELP_GROUP_ORDER,
+  HELP_TOPICS,
+  resolveHelpTopics,
+  searchHelpTopics,
+  topicForPath
+};
+//# sourceMappingURL=help-topics.js.map