@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/core/logging/types.d.mts

@@ -6,33 +6,50 @@
  * level methods can receive Hydrogen entries. Hydrogen never depends on a
  * specific logging library.
  */
-/** Log severities, ordered. `silent` disables all output. */
+/** The log severities, from lowest to highest. Set `silent` to turn off all output. */
 type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "silent";
 /**
- * Structured details attached to a log entry. `scope` names the Hydrogen
- * subsystem (`cart`, `analytics`, `shop-pay`, ...). `error` carries the caught
- * value when the entry reports a failure.
+ * Structured details attached to a log entry. Extra fields pass through to the logger.
+ *
+ * @publicDocs
  */
 type LogContext = {
-  scope?: string;
+  /** The Hydrogen subsystem that wrote the entry, such as `cart` or `analytics`. */scope?: string; /** The caught value when the entry reports a failure. */
   error?: unknown;
   [key: string]: unknown;
 };
-type LogFn = (message: string, context?: LogContext) => void;
 /**
- * Sink that receives Hydrogen log entries. Pass your own logger to
- * `configureLogging`, or rely on the built-in console logger.
+ * Writes one log entry at the severity of the logger method.
+ */
+type LogFn =
+/**
+ * @param message - The entry text, without a prefix.
+ * @param context - Structured details about the entry, including the subsystem scope.
+ * @returns Nothing. Hydrogen ignores the return value.
+ */
+(message: string, context?: LogContext) => void;
+/**
+ * A logger that receives Hydrogen's log entries. Pass your logger to `configureLogging`. Without
+ * one, Hydrogen writes to the console.
+ *
+ * Messages arrive without a prefix, and the context scope names the subsystem. The built-in
+ * console logger formats entries as `[hydrogen:<level>:<scope>] <message>`. The console logger
+ * writes trace entries with `console.debug` and fatal entries with `console.error`.
  *
- * Messages arrive unprefixed; `context.scope` identifies the subsystem so
- * custom sinks control their own formatting. The built-in console logger
- * formats entries as `[hydrogen:<level>:<scope>] <message>`.
+ * When a custom logger throws, Hydrogen reports the failure through the console logger and continues the operation that logged the entry. Catch network errors inside a custom logger to keep a monitoring outage from writing a console error for every entry.
  */
 interface HydrogenLogger {
+  /** Receives trace entries, the lowest severity. */
   trace: LogFn;
+  /** Receives debug entries. */
   debug: LogFn;
+  /** Receives info entries. Info is the default minimum severity. */
   info: LogFn;
+  /** Receives warning entries. */
   warn: LogFn;
+  /** Receives error entries. */
   error: LogFn;
+  /** Receives fatal entries, the highest severity. */
   fatal: LogFn;
 }
 //#endregion

package/dist/core/logging/types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.mjs","names":[],"sources":["../../../src/core/logging/types.ts"],"sourcesContent":["/**\n * Logging contract for `@shopify/hydrogen` runtime failures.\n *\n * The interface is intentionally minimal and structural: any logger with these\n * level methods can receive Hydrogen entries. Hydrogen never depends on a\n * specific logging library.\n */\n\n/** Log severities, ordered. `silent` disables all output. */\nexport type LogLevel = \"trace\" | \"debug\" | \"info\" | \"warn\" | \"error\" | \"fatal\" | \"silent\";\n\n/**\n * Structured details attached to a log entry. `scope` names the Hydrogen\n * subsystem (`cart`, `analytics`, `shop-pay`, ...). `error` carries the caught\n * value when the entry reports a failure.\n */\nexport type LogContext = {\n  scope?: string;\n  error?: unknown;\n  [key: string]: unknown;\n};\n\ntype LogFn = (message: string, context?: LogContext) => void;\n\n/**\n * Sink that receives Hydrogen log entries. Pass your own logger to\n * `configureLogging`, or rely on the built-in console logger.\n *\n * Messages arrive unprefixed; `context.scope` identifies the subsystem so\n * custom sinks control their own formatting. The built-in console logger\n * formats entries as `[hydrogen:<level>:<scope>] <message>`.\n */\nexport interface HydrogenLogger {\n  trace: LogFn;\n  debug: LogFn;\n  info: LogFn;\n  warn: LogFn;\n  error: LogFn;\n  fatal: LogFn;\n}\n\nexport const DEFAULT_LOG_LEVEL: LogLevel = \"info\";\n\nconst LOG_LEVEL_VALUES: Record<LogLevel, number> = {\n  trace: 10,\n  debug: 20,\n  info: 30,\n  warn: 40,\n  error: 50,\n  fatal: 60,\n  silent: Number.POSITIVE_INFINITY,\n};\n\n/** Severity actually emitted by a log entry (everything except `silent`). */\nexport type LogSeverity = Exclude<LogLevel, \"silent\">;\n\nexport function isLevelEnabled(level: LogSeverity, threshold: LogLevel): boolean {\n  return LOG_LEVEL_VALUES[level] >= LOG_LEVEL_VALUES[threshold];\n}\n"],"mappings":";AAyCA,MAAa,oBAA8B;AAE3C,MAAM,mBAA6C;CACjD,OAAO;CACP,OAAO;CACP,MAAM;CACN,MAAM;CACN,OAAO;CACP,OAAO;CACP,QAAQ,OAAO;CAChB;AAKD,SAAgB,eAAe,OAAoB,WAA8B;AAC/E,QAAO,iBAAiB,UAAU,iBAAiB"}
+{"version":3,"file":"types.mjs","names":[],"sources":["../../../src/core/logging/types.ts"],"sourcesContent":["/**\n * Logging contract for `@shopify/hydrogen` runtime failures.\n *\n * The interface is intentionally minimal and structural: any logger with these\n * level methods can receive Hydrogen entries. Hydrogen never depends on a\n * specific logging library.\n */\n\n/** The log severities, from lowest to highest. Set `silent` to turn off all output. */\nexport type LogLevel = \"trace\" | \"debug\" | \"info\" | \"warn\" | \"error\" | \"fatal\" | \"silent\";\n\n/**\n * Structured details attached to a log entry. Extra fields pass through to the logger.\n *\n * @publicDocs\n */\nexport type LogContext = {\n  /** The Hydrogen subsystem that wrote the entry, such as `cart` or `analytics`. */\n  scope?: string;\n  /** The caught value when the entry reports a failure. */\n  error?: unknown;\n  [key: string]: unknown;\n};\n\n/**\n * Writes one log entry at the severity of the logger method.\n */\ntype LogFn =\n  /**\n   * @param message - The entry text, without a prefix.\n   * @param context - Structured details about the entry, including the subsystem scope.\n   * @returns Nothing. Hydrogen ignores the return value.\n   */\n  (message: string, context?: LogContext) => void;\n\n/**\n * A logger that receives Hydrogen's log entries. Pass your logger to `configureLogging`. Without\n * one, Hydrogen writes to the console.\n *\n * Messages arrive without a prefix, and the context scope names the subsystem. The built-in\n * console logger formats entries as `[hydrogen:<level>:<scope>] <message>`. The console logger\n * writes trace entries with `console.debug` and fatal entries with `console.error`.\n *\n * When a custom logger throws, Hydrogen reports the failure through the console logger and continues the operation that logged the entry. Catch network errors inside a custom logger to keep a monitoring outage from writing a console error for every entry.\n */\nexport interface HydrogenLogger {\n  /** Receives trace entries, the lowest severity. */\n  trace: LogFn;\n  /** Receives debug entries. */\n  debug: LogFn;\n  /** Receives info entries. Info is the default minimum severity. */\n  info: LogFn;\n  /** Receives warning entries. */\n  warn: LogFn;\n  /** Receives error entries. */\n  error: LogFn;\n  /** Receives fatal entries, the highest severity. */\n  fatal: LogFn;\n}\n\nexport const DEFAULT_LOG_LEVEL: LogLevel = \"info\";\n\nconst LOG_LEVEL_VALUES: Record<LogLevel, number> = {\n  trace: 10,\n  debug: 20,\n  info: 30,\n  warn: 40,\n  error: 50,\n  fatal: 60,\n  silent: Number.POSITIVE_INFINITY,\n};\n\n/** The severity of a log entry. Every level except `silent`. */\nexport type LogSeverity = Exclude<LogLevel, \"silent\">;\n\nexport function isLevelEnabled(level: LogSeverity, threshold: LogLevel): boolean {\n  return LOG_LEVEL_VALUES[level] >= LOG_LEVEL_VALUES[threshold];\n}\n"],"mappings":";AA4DA,MAAa,oBAA8B;AAE3C,MAAM,mBAA6C;CACjD,OAAO;CACP,OAAO;CACP,MAAM;CACN,MAAM;CACN,OAAO;CACP,OAAO;CACP,QAAQ,OAAO;CAChB;AAKD,SAAgB,eAAe,OAAoB,WAA8B;AAC/E,QAAO,iBAAiB,UAAU,iBAAiB"}

package/dist/core/money/format.d.mts

@@ -2,11 +2,13 @@ import { FormatMoneyOptions, FormattedMoney, FormattedMoneyRange, MoneyV2 } from
 
 //#region src/core/money/format.d.ts
 /**
- * Format a MoneyV2 value or a same-currency range of MoneyV2 values for display.
+ * Formats a price or a price range for display. Pass a `MoneyV2` price, or an array of `MoneyV2` prices in one currency for a range, with the active market's locale.
  *
- * Returns an object that stringifies to the locale-formatted price via
- * toString(). Structured fields on single prices are computed lazily when
- * accessed, so the common string path stays cheap.
+ * The returned object converts to the formatted string in template literals and string concatenation. For custom price layouts, read the parts of the formatted price. A range shows the lowest and highest prices. When every price in the range matches, the output shows one price.
+ *
+ * The function throws an error when an amount isn't numeric, when a range is empty, or when the prices in a range use different currencies.
+ *
+ * @publicDocs
  */
 declare function formatMoney(money: MoneyV2, options: FormatMoneyOptions): FormattedMoney;
 declare function formatMoney(money: readonly MoneyV2[], options: FormatMoneyOptions): FormattedMoneyRange;

package/dist/core/money/format.mjs

@@ -6,7 +6,10 @@ import { getFormatter } from "./cache.mjs";
 * Used to extract "19.99" from a formatted string like "$19.99" (or
 * "-19.99" from "-$19.99") by filtering out currency symbols and other
 * non-numeric parts. The minus sign is kept so negative amounts such as
-* refunds and discounts don't render as positive.
+* refunds and discounts don't render as positive. Literals stay in the set
+* because RTL locales such as he-IL and ar-EG emit the bidi marks that bind
+* the minus sign to the digits as literals. Only the literal next to the
+* currency part, the spacer between number and symbol, is dropped.
 */
 const NUMERIC_PART_TYPES = new Set([
 	"decimal",
@@ -26,8 +29,8 @@ function normalizeCurrencyCode(currencyCode) {
 	return currencyCode.toUpperCase();
 }
 /**
-* Intl accepts well-formed three-letter currency codes. Non-standard but
-* well-formed codes render as codes; malformed codes such as USDC throw.
+* Intl accepts well-formed three-letter currency codes and renders unknown ones as codes.
+* Intl throws for malformed codes such as USDC. The formatter formats those as decimals.
 */
 function isWellFormedCurrencyCode(currencyCode) {
 	return WELL_FORMED_CURRENCY_CODE.test(currencyCode);
@@ -70,7 +73,9 @@ function appendUnsupportedCurrencyCode(formatted, currencyCode) {
 	return `${formatted} ${currencyCode}`;
 }
 function extractNumericAmount(parts) {
-	return parts.filter((part) => NUMERIC_PART_TYPES.has(part.type)).map((part) => part.value).join("");
+	const currency = parts.findIndex((part) => part.type === "currency");
+	const isCurrencySpacer = (part, index) => currency !== -1 && part.type === "literal" && Math.abs(index - currency) === 1;
+	return parts.filter((part, index) => NUMERIC_PART_TYPES.has(part.type) && !isCurrencySpacer(part, index)).map((part) => part.value).join("");
 }
 function findCurrencyPart(parts) {
 	return parts.find((part) => part.type === "currency")?.value ?? "";
@@ -82,12 +87,12 @@ function formatRange(formatter, min, max) {
 function isMoneyRange(money) {
 	return Array.isArray(money);
 }
-function buildRangeOptions(currencyCode, supported, options, amounts) {
-	const wholeRange = amounts.every(hasTrailingZeros);
+function buildRangeOptions(currencyCode, supported, options, min, max) {
+	const wholeRange = hasTrailingZeros(min) && hasTrailingZeros(max);
 	return buildFormatOptions(currencyCode, supported, {
 		...options,
-		withoutTrailingZeros: options.withoutTrailingZeros ?? (wholeRange && !hasExplicitFractionDigits(options))
-	}, amounts[0] ?? 0);
+		withoutTrailingZeros: wholeRange && (options.withoutTrailingZeros ?? !hasExplicitFractionDigits(options))
+	}, min);
 }
 function sortMoneyRangeEntries(entries) {
 	const sorted = [];
@@ -230,13 +235,18 @@ var FormattedMoneyRangeValue = class {
 			return;
 		}
 		const supported = isWellFormedCurrencyCode(first.currencyCode);
-		const formatted = formatRange(getFormatter(options.locale, buildRangeOptions(first.currencyCode, supported, options, entries.map((entry) => entry.amount))), first.amount, last.amount);
+		const formatted = formatRange(getFormatter(options.locale, buildRangeOptions(first.currencyCode, supported, options, first.amount, last.amount)), first.amount, last.amount);
 		this.localizedString = supported || options.withoutCurrency === true ? formatted : appendUnsupportedCurrencyCode(formatted, first.currencyCode);
 	}
 	toString() {
 		return this.localizedString;
 	}
 };
+/**
+* @param money A price, or an array of prices in one currency for a range.
+* @param options Locale and display settings.
+* @returns The formatted price or range, which converts to a string in template literals.
+*/
 function formatMoney(money, options) {
 	return isMoneyRange(money) ? new FormattedMoneyRangeValue(money, options) : new FormattedMoneyValue(money, options);
 }

package/dist/core/money/format.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"format.mjs","names":["#amount","#options","#currencyCode","#supported","#defaultFormatter","#amountString","#currencySymbol","#currencyNarrowSymbol","#currencyName","#parts","#withoutTrailingZeros","#withoutTrailingZerosAndCurrency","#formatterParts"],"sources":["../../../src/core/money/format.ts"],"sourcesContent":["import { getFormatter } from \"./cache\";\nimport type { FormatMoneyOptions, FormattedMoney, FormattedMoneyRange, MoneyV2 } from \"./types\";\n\n/**\n * Intl.NumberFormat part types that make up the raw numeric amount.\n * Used to extract \"19.99\" from a formatted string like \"$19.99\" (or\n * \"-19.99\" from \"-$19.99\") by filtering out currency symbols and other\n * non-numeric parts. The minus sign is kept so negative amounts such as\n * refunds and discounts don't render as positive.\n */\nconst NUMERIC_PART_TYPES = new Set([\n  \"decimal\",\n  \"fraction\",\n  \"group\",\n  \"integer\",\n  \"literal\",\n  \"minusSign\",\n]);\nconst WELL_FORMED_CURRENCY_CODE = /^[a-z]{3}$/i;\n\ntype RangeFormatter = Intl.NumberFormat & {\n  formatRange?: (start: number, end: number) => string;\n};\n\ntype MoneyRangeEntry = {\n  money: MoneyV2;\n  amount: number;\n  currencyCode: string;\n};\n\nfunction parseAmount(money: MoneyV2): number {\n  const parsed = parseFloat(money.amount);\n  if (Number.isNaN(parsed)) {\n    throw new Error(\n      `formatMoney: \"${money.amount}\" is not a valid numeric amount for currency ${money.currencyCode}`,\n    );\n  }\n  return parsed;\n}\n\nfunction normalizeCurrencyCode(currencyCode: string): string {\n  return currencyCode.toUpperCase();\n}\n\n/**\n * Intl accepts well-formed three-letter currency codes. Non-standard but\n * well-formed codes render as codes; malformed codes such as USDC throw.\n */\nfunction isWellFormedCurrencyCode(currencyCode: string): boolean {\n  return WELL_FORMED_CURRENCY_CODE.test(currencyCode);\n}\n\nfunction hasTrailingZeros(amount: number): boolean {\n  return amount % 1 === 0;\n}\n\nfunction shouldStripTrailingZeros(amount: number, options: FormatMoneyOptions): boolean {\n  return options.withoutTrailingZeros === true && hasTrailingZeros(amount);\n}\n\nfunction hasExplicitFractionDigits(options: FormatMoneyOptions): boolean {\n  return options.minimumFractionDigits != null || options.maximumFractionDigits != null;\n}\n\nfunction decimalFractionOptions(options: FormatMoneyOptions): Intl.NumberFormatOptions {\n  return {\n    minimumFractionDigits: options.minimumFractionDigits ?? 2,\n    maximumFractionDigits: options.maximumFractionDigits ?? 2,\n  };\n}\n\nfunction buildFormatOptions(\n  currencyCode: string,\n  supported: boolean,\n  options: FormatMoneyOptions,\n  amount: number,\n): Intl.NumberFormatOptions {\n  const withoutCurrency = options.withoutCurrency === true || !supported;\n  const trailingZeros = shouldStripTrailingZeros(amount, options);\n\n  if (withoutCurrency) {\n    return trailingZeros\n      ? { minimumFractionDigits: 0, maximumFractionDigits: 0 }\n      : decimalFractionOptions(options);\n  }\n\n  return {\n    style: \"currency\",\n    currency: currencyCode,\n    ...(options.currencyDisplay && { currencyDisplay: options.currencyDisplay }),\n    ...(trailingZeros && {\n      minimumFractionDigits: 0,\n      maximumFractionDigits: 0,\n    }),\n    ...(!trailingZeros &&\n      options.minimumFractionDigits != null && {\n        minimumFractionDigits: options.minimumFractionDigits,\n      }),\n    ...(!trailingZeros &&\n      options.maximumFractionDigits != null && {\n        maximumFractionDigits: options.maximumFractionDigits,\n      }),\n  };\n}\n\nfunction appendUnsupportedCurrencyCode(formatted: string, currencyCode: string): string {\n  return `${formatted} ${currencyCode}`;\n}\n\nfunction extractNumericAmount(parts: Intl.NumberFormatPart[]): string {\n  return parts\n    .filter((part) => NUMERIC_PART_TYPES.has(part.type))\n    .map((part) => part.value)\n    .join(\"\");\n}\n\nfunction findCurrencyPart(parts: Intl.NumberFormatPart[]): string {\n  return parts.find((part) => part.type === \"currency\")?.value ?? \"\";\n}\n\nfunction formatRange(formatter: Intl.NumberFormat, min: number, max: number): string {\n  const rangeFormatter = formatter as RangeFormatter;\n  return rangeFormatter.formatRange\n    ? rangeFormatter.formatRange(min, max)\n    : `${formatter.format(min)} - ${formatter.format(max)}`;\n}\n\nfunction isMoneyRange(money: MoneyV2 | readonly MoneyV2[]): money is readonly MoneyV2[] {\n  return Array.isArray(money);\n}\n\nfunction buildRangeOptions(\n  currencyCode: string,\n  supported: boolean,\n  options: FormatMoneyOptions,\n  amounts: number[],\n): Intl.NumberFormatOptions {\n  const wholeRange = amounts.every(hasTrailingZeros);\n  const rangeOptions = {\n    ...options,\n    withoutTrailingZeros:\n      options.withoutTrailingZeros ?? (wholeRange && !hasExplicitFractionDigits(options)),\n  };\n\n  return buildFormatOptions(currencyCode, supported, rangeOptions, amounts[0] ?? 0);\n}\n\nfunction sortMoneyRangeEntries(entries: MoneyRangeEntry[]): MoneyRangeEntry[] {\n  const sorted: MoneyRangeEntry[] = [];\n\n  for (const entry of entries) {\n    const index = sorted.findIndex((candidate) => entry.amount < candidate.amount);\n    if (index === -1) {\n      sorted.push(entry);\n    } else {\n      sorted.splice(index, 0, entry);\n    }\n  }\n\n  return sorted;\n}\n\n/**\n * All structured fields are computed lazily on first access and cached.\n * localizedString is the exception — it's computed eagerly in the constructor\n * so that the common `${price}` path never touches the getter machinery.\n */\nclass FormattedMoneyValue implements FormattedMoney {\n  readonly #amount: number;\n  readonly #options: FormatMoneyOptions;\n  readonly #currencyCode: string;\n  readonly #supported: boolean;\n  readonly localizedString: string;\n\n  readonly #defaultFormatter: Intl.NumberFormat;\n  #formatterParts?: Intl.NumberFormatPart[];\n  #parts?: Intl.NumberFormatPart[];\n  #amountString?: string;\n  #currencySymbol?: string;\n  #currencyNarrowSymbol?: string;\n  #currencyName?: string;\n  #withoutTrailingZeros?: string;\n  #withoutTrailingZerosAndCurrency?: string;\n\n  constructor(money: MoneyV2, options: FormatMoneyOptions) {\n    this.#amount = parseAmount(money);\n    this.#options = options;\n    this.#currencyCode = normalizeCurrencyCode(money.currencyCode);\n    this.#supported = isWellFormedCurrencyCode(money.currencyCode);\n    this.#defaultFormatter = getFormatter(\n      options.locale,\n      buildFormatOptions(this.#currencyCode, this.#supported, options, this.#amount),\n    );\n\n    const formatted = this.#defaultFormatter.format(this.#amount);\n    this.localizedString =\n      this.#supported || options.withoutCurrency === true\n        ? formatted\n        : appendUnsupportedCurrencyCode(formatted, this.#currencyCode);\n  }\n\n  get amount(): string {\n    this.#amountString ??= extractNumericAmount(this.formatterParts);\n    return this.#amountString;\n  }\n\n  get numericAmount(): number {\n    return this.#amount;\n  }\n\n  get currencySymbol(): string {\n    this.#currencySymbol ??= this.#supported ? findCurrencyPart(this.parts) : this.#currencyCode;\n    return this.#currencySymbol;\n  }\n\n  get currencyNarrowSymbol(): string {\n    this.#currencyNarrowSymbol ??= this.#supported\n      ? findCurrencyPart(\n          getFormatter(this.#options.locale, {\n            style: \"currency\",\n            currency: this.#currencyCode,\n            currencyDisplay: \"narrowSymbol\",\n            ...(this.#options.minimumFractionDigits != null && {\n              minimumFractionDigits: this.#options.minimumFractionDigits,\n            }),\n            ...(this.#options.maximumFractionDigits != null && {\n              maximumFractionDigits: this.#options.maximumFractionDigits,\n            }),\n          }).formatToParts(this.#amount),\n        )\n      : this.#currencyCode;\n    return this.#currencyNarrowSymbol;\n  }\n\n  get currencyName(): string {\n    this.#currencyName ??= this.#supported\n      ? findCurrencyPart(\n          getFormatter(this.#options.locale, {\n            style: \"currency\",\n            currency: this.#currencyCode,\n            currencyDisplay: \"name\",\n            ...(this.#options.minimumFractionDigits != null && {\n              minimumFractionDigits: this.#options.minimumFractionDigits,\n            }),\n            ...(this.#options.maximumFractionDigits != null && {\n              maximumFractionDigits: this.#options.maximumFractionDigits,\n            }),\n          }).formatToParts(this.#amount),\n        ) || this.#currencyCode\n      : this.#currencyCode;\n    return this.#currencyName;\n  }\n\n  get parts(): Intl.NumberFormatPart[] {\n    if (!this.#parts) {\n      this.#parts =\n        this.#supported || this.#options.withoutCurrency === true\n          ? this.formatterParts\n          : [\n              ...this.formatterParts,\n              { type: \"literal\" as const, value: \" \" },\n              { type: \"currency\" as const, value: this.#currencyCode },\n            ];\n    }\n\n    return this.#parts;\n  }\n\n  get withoutTrailingZeros(): string {\n    if (!this.#withoutTrailingZeros) {\n      const options = { ...this.#options, withoutTrailingZeros: true };\n      const formatter = getFormatter(\n        options.locale,\n        buildFormatOptions(this.#currencyCode, this.#supported, options, this.#amount),\n      );\n      const formatted = formatter.format(this.#amount);\n      this.#withoutTrailingZeros =\n        this.#supported || this.#options.withoutCurrency === true\n          ? formatted\n          : appendUnsupportedCurrencyCode(formatted, this.#currencyCode);\n    }\n\n    return this.#withoutTrailingZeros;\n  }\n\n  get withoutTrailingZerosAndCurrency(): string {\n    if (!this.#withoutTrailingZerosAndCurrency) {\n      const options = { ...this.#options, withoutCurrency: true, withoutTrailingZeros: true };\n      this.#withoutTrailingZerosAndCurrency = getFormatter(\n        options.locale,\n        buildFormatOptions(this.#currencyCode, this.#supported, options, this.#amount),\n      ).format(this.#amount);\n    }\n\n    return this.#withoutTrailingZerosAndCurrency;\n  }\n\n  private get formatterParts(): Intl.NumberFormatPart[] {\n    this.#formatterParts ??= this.#defaultFormatter.formatToParts(this.#amount);\n    return this.#formatterParts;\n  }\n\n  toString(): string {\n    return this.localizedString;\n  }\n}\n\nclass FormattedMoneyRangeValue implements FormattedMoneyRange {\n  readonly localizedString: string;\n  readonly min: MoneyV2;\n  readonly max: MoneyV2;\n  readonly currencyCode: string;\n\n  constructor(range: readonly MoneyV2[], options: FormatMoneyOptions) {\n    if (range.length === 0) {\n      throw new Error(\"formatMoney: money range must contain at least one value\");\n    }\n\n    const entries = sortMoneyRangeEntries(\n      range.map((money) => ({\n        money,\n        amount: parseAmount(money),\n        currencyCode: normalizeCurrencyCode(money.currencyCode),\n      })),\n    );\n\n    const [first] = entries;\n    if (!first) {\n      throw new Error(\"formatMoney: money range must contain at least one value\");\n    }\n\n    const mismatched = entries.find((entry) => entry.currencyCode !== first.currencyCode);\n    if (mismatched) {\n      throw new Error(\n        `formatMoney: range values must share one currency, received ${first.currencyCode} and ${mismatched.currencyCode}`,\n      );\n    }\n\n    const last = entries[entries.length - 1] ?? first;\n    this.min = first.money;\n    this.max = last.money;\n    this.currencyCode = first.currencyCode;\n\n    if (first.amount === last.amount) {\n      this.localizedString = new FormattedMoneyValue(first.money, {\n        ...options,\n        withoutTrailingZeros: options.withoutTrailingZeros ?? !hasExplicitFractionDigits(options),\n      }).localizedString;\n      return;\n    }\n\n    const supported = isWellFormedCurrencyCode(first.currencyCode);\n    const formatter = getFormatter(\n      options.locale,\n      buildRangeOptions(\n        first.currencyCode,\n        supported,\n        options,\n        entries.map((entry) => entry.amount),\n      ),\n    );\n\n    const formatted = formatRange(formatter, first.amount, last.amount);\n    this.localizedString =\n      supported || options.withoutCurrency === true\n        ? formatted\n        : appendUnsupportedCurrencyCode(formatted, first.currencyCode);\n  }\n\n  toString(): string {\n    return this.localizedString;\n  }\n}\n\n/**\n * Format a MoneyV2 value or a same-currency range of MoneyV2 values for display.\n *\n * Returns an object that stringifies to the locale-formatted price via\n * toString(). Structured fields on single prices are computed lazily when\n * accessed, so the common string path stays cheap.\n */\nexport function formatMoney(money: MoneyV2, options: FormatMoneyOptions): FormattedMoney;\nexport function formatMoney(\n  money: readonly MoneyV2[],\n  options: FormatMoneyOptions,\n): FormattedMoneyRange;\n\n// This is the implementation of the formatMoney function overloading the other two.\n// It checks if the input is a range and creates the appropriate object.\nexport function formatMoney(\n  money: MoneyV2 | readonly MoneyV2[],\n  options: FormatMoneyOptions,\n): FormattedMoney | FormattedMoneyRange {\n  return isMoneyRange(money)\n    ? new FormattedMoneyRangeValue(money, options)\n    : new FormattedMoneyValue(money, options);\n}\n"],"mappings":"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"}
+{"version":3,"file":"format.mjs","names":["#amount","#options","#currencyCode","#supported","#defaultFormatter","#amountString","#currencySymbol","#currencyNarrowSymbol","#currencyName","#parts","#withoutTrailingZeros","#withoutTrailingZerosAndCurrency","#formatterParts"],"sources":["../../../src/core/money/format.ts"],"sourcesContent":["import { getFormatter } from \"./cache\";\nimport type { FormatMoneyOptions, FormattedMoney, FormattedMoneyRange, MoneyV2 } from \"./types\";\n\n/**\n * Intl.NumberFormat part types that make up the raw numeric amount.\n * Used to extract \"19.99\" from a formatted string like \"$19.99\" (or\n * \"-19.99\" from \"-$19.99\") by filtering out currency symbols and other\n * non-numeric parts. The minus sign is kept so negative amounts such as\n * refunds and discounts don't render as positive. Literals stay in the set\n * because RTL locales such as he-IL and ar-EG emit the bidi marks that bind\n * the minus sign to the digits as literals. Only the literal next to the\n * currency part, the spacer between number and symbol, is dropped.\n */\nconst NUMERIC_PART_TYPES = new Set([\n  \"decimal\",\n  \"fraction\",\n  \"group\",\n  \"integer\",\n  \"literal\",\n  \"minusSign\",\n]);\nconst WELL_FORMED_CURRENCY_CODE = /^[a-z]{3}$/i;\n\ntype RangeFormatter = Intl.NumberFormat & {\n  formatRange?: (start: number, end: number) => string;\n};\n\ntype MoneyRangeEntry = {\n  money: MoneyV2;\n  amount: number;\n  currencyCode: string;\n};\n\nfunction parseAmount(money: MoneyV2): number {\n  const parsed = parseFloat(money.amount);\n  if (Number.isNaN(parsed)) {\n    throw new Error(\n      `formatMoney: \"${money.amount}\" is not a valid numeric amount for currency ${money.currencyCode}`,\n    );\n  }\n  return parsed;\n}\n\nfunction normalizeCurrencyCode(currencyCode: string): string {\n  return currencyCode.toUpperCase();\n}\n\n/**\n * Intl accepts well-formed three-letter currency codes and renders unknown ones as codes.\n * Intl throws for malformed codes such as USDC. The formatter formats those as decimals.\n */\nfunction isWellFormedCurrencyCode(currencyCode: string): boolean {\n  return WELL_FORMED_CURRENCY_CODE.test(currencyCode);\n}\n\nfunction hasTrailingZeros(amount: number): boolean {\n  return amount % 1 === 0;\n}\n\nfunction shouldStripTrailingZeros(amount: number, options: FormatMoneyOptions): boolean {\n  return options.withoutTrailingZeros === true && hasTrailingZeros(amount);\n}\n\nfunction hasExplicitFractionDigits(options: FormatMoneyOptions): boolean {\n  return options.minimumFractionDigits != null || options.maximumFractionDigits != null;\n}\n\nfunction decimalFractionOptions(options: FormatMoneyOptions): Intl.NumberFormatOptions {\n  return {\n    minimumFractionDigits: options.minimumFractionDigits ?? 2,\n    maximumFractionDigits: options.maximumFractionDigits ?? 2,\n  };\n}\n\nfunction buildFormatOptions(\n  currencyCode: string,\n  supported: boolean,\n  options: FormatMoneyOptions,\n  amount: number,\n): Intl.NumberFormatOptions {\n  const withoutCurrency = options.withoutCurrency === true || !supported;\n  const trailingZeros = shouldStripTrailingZeros(amount, options);\n\n  if (withoutCurrency) {\n    return trailingZeros\n      ? { minimumFractionDigits: 0, maximumFractionDigits: 0 }\n      : decimalFractionOptions(options);\n  }\n\n  return {\n    style: \"currency\",\n    currency: currencyCode,\n    ...(options.currencyDisplay && { currencyDisplay: options.currencyDisplay }),\n    ...(trailingZeros && {\n      minimumFractionDigits: 0,\n      maximumFractionDigits: 0,\n    }),\n    ...(!trailingZeros &&\n      options.minimumFractionDigits != null && {\n        minimumFractionDigits: options.minimumFractionDigits,\n      }),\n    ...(!trailingZeros &&\n      options.maximumFractionDigits != null && {\n        maximumFractionDigits: options.maximumFractionDigits,\n      }),\n  };\n}\n\nfunction appendUnsupportedCurrencyCode(formatted: string, currencyCode: string): string {\n  return `${formatted} ${currencyCode}`;\n}\n\nfunction extractNumericAmount(parts: Intl.NumberFormatPart[]): string {\n  const currency = parts.findIndex((part) => part.type === \"currency\");\n  const isCurrencySpacer = (part: Intl.NumberFormatPart, index: number) =>\n    currency !== -1 && part.type === \"literal\" && Math.abs(index - currency) === 1;\n\n  return parts\n    .filter((part, index) => NUMERIC_PART_TYPES.has(part.type) && !isCurrencySpacer(part, index))\n    .map((part) => part.value)\n    .join(\"\");\n}\n\nfunction findCurrencyPart(parts: Intl.NumberFormatPart[]): string {\n  return parts.find((part) => part.type === \"currency\")?.value ?? \"\";\n}\n\nfunction formatRange(formatter: Intl.NumberFormat, min: number, max: number): string {\n  const rangeFormatter = formatter as RangeFormatter;\n  return rangeFormatter.formatRange\n    ? rangeFormatter.formatRange(min, max)\n    : `${formatter.format(min)} - ${formatter.format(max)}`;\n}\n\nfunction isMoneyRange(money: MoneyV2 | readonly MoneyV2[]): money is readonly MoneyV2[] {\n  return Array.isArray(money);\n}\n\nfunction buildRangeOptions(\n  currencyCode: string,\n  supported: boolean,\n  options: FormatMoneyOptions,\n  min: number,\n  max: number,\n): Intl.NumberFormatOptions {\n  const wholeRange = hasTrailingZeros(min) && hasTrailingZeros(max);\n  const rangeOptions = {\n    ...options,\n    withoutTrailingZeros:\n      wholeRange && (options.withoutTrailingZeros ?? !hasExplicitFractionDigits(options)),\n  };\n\n  return buildFormatOptions(currencyCode, supported, rangeOptions, min);\n}\n\nfunction sortMoneyRangeEntries(entries: MoneyRangeEntry[]): MoneyRangeEntry[] {\n  const sorted: MoneyRangeEntry[] = [];\n\n  for (const entry of entries) {\n    const index = sorted.findIndex((candidate) => entry.amount < candidate.amount);\n    if (index === -1) {\n      sorted.push(entry);\n    } else {\n      sorted.splice(index, 0, entry);\n    }\n  }\n\n  return sorted;\n}\n\n/**\n * All structured fields are computed lazily on first access and cached.\n * localizedString is the exception — it's computed eagerly in the constructor\n * so that the common `${price}` path never touches the getter machinery.\n */\nclass FormattedMoneyValue implements FormattedMoney {\n  readonly #amount: number;\n  readonly #options: FormatMoneyOptions;\n  readonly #currencyCode: string;\n  readonly #supported: boolean;\n  readonly localizedString: string;\n\n  readonly #defaultFormatter: Intl.NumberFormat;\n  #formatterParts?: Intl.NumberFormatPart[];\n  #parts?: Intl.NumberFormatPart[];\n  #amountString?: string;\n  #currencySymbol?: string;\n  #currencyNarrowSymbol?: string;\n  #currencyName?: string;\n  #withoutTrailingZeros?: string;\n  #withoutTrailingZerosAndCurrency?: string;\n\n  constructor(money: MoneyV2, options: FormatMoneyOptions) {\n    this.#amount = parseAmount(money);\n    this.#options = options;\n    this.#currencyCode = normalizeCurrencyCode(money.currencyCode);\n    this.#supported = isWellFormedCurrencyCode(money.currencyCode);\n    this.#defaultFormatter = getFormatter(\n      options.locale,\n      buildFormatOptions(this.#currencyCode, this.#supported, options, this.#amount),\n    );\n\n    const formatted = this.#defaultFormatter.format(this.#amount);\n    this.localizedString =\n      this.#supported || options.withoutCurrency === true\n        ? formatted\n        : appendUnsupportedCurrencyCode(formatted, this.#currencyCode);\n  }\n\n  get amount(): string {\n    this.#amountString ??= extractNumericAmount(this.formatterParts);\n    return this.#amountString;\n  }\n\n  get numericAmount(): number {\n    return this.#amount;\n  }\n\n  get currencySymbol(): string {\n    this.#currencySymbol ??= this.#supported ? findCurrencyPart(this.parts) : this.#currencyCode;\n    return this.#currencySymbol;\n  }\n\n  get currencyNarrowSymbol(): string {\n    this.#currencyNarrowSymbol ??= this.#supported\n      ? findCurrencyPart(\n          getFormatter(this.#options.locale, {\n            style: \"currency\",\n            currency: this.#currencyCode,\n            currencyDisplay: \"narrowSymbol\",\n            ...(this.#options.minimumFractionDigits != null && {\n              minimumFractionDigits: this.#options.minimumFractionDigits,\n            }),\n            ...(this.#options.maximumFractionDigits != null && {\n              maximumFractionDigits: this.#options.maximumFractionDigits,\n            }),\n          }).formatToParts(this.#amount),\n        )\n      : this.#currencyCode;\n    return this.#currencyNarrowSymbol;\n  }\n\n  get currencyName(): string {\n    this.#currencyName ??= this.#supported\n      ? findCurrencyPart(\n          getFormatter(this.#options.locale, {\n            style: \"currency\",\n            currency: this.#currencyCode,\n            currencyDisplay: \"name\",\n            ...(this.#options.minimumFractionDigits != null && {\n              minimumFractionDigits: this.#options.minimumFractionDigits,\n            }),\n            ...(this.#options.maximumFractionDigits != null && {\n              maximumFractionDigits: this.#options.maximumFractionDigits,\n            }),\n          }).formatToParts(this.#amount),\n        ) || this.#currencyCode\n      : this.#currencyCode;\n    return this.#currencyName;\n  }\n\n  get parts(): Intl.NumberFormatPart[] {\n    if (!this.#parts) {\n      this.#parts =\n        this.#supported || this.#options.withoutCurrency === true\n          ? this.formatterParts\n          : [\n              ...this.formatterParts,\n              { type: \"literal\" as const, value: \" \" },\n              { type: \"currency\" as const, value: this.#currencyCode },\n            ];\n    }\n\n    return this.#parts;\n  }\n\n  get withoutTrailingZeros(): string {\n    if (!this.#withoutTrailingZeros) {\n      const options = { ...this.#options, withoutTrailingZeros: true };\n      const formatter = getFormatter(\n        options.locale,\n        buildFormatOptions(this.#currencyCode, this.#supported, options, this.#amount),\n      );\n      const formatted = formatter.format(this.#amount);\n      this.#withoutTrailingZeros =\n        this.#supported || this.#options.withoutCurrency === true\n          ? formatted\n          : appendUnsupportedCurrencyCode(formatted, this.#currencyCode);\n    }\n\n    return this.#withoutTrailingZeros;\n  }\n\n  get withoutTrailingZerosAndCurrency(): string {\n    if (!this.#withoutTrailingZerosAndCurrency) {\n      const options = { ...this.#options, withoutCurrency: true, withoutTrailingZeros: true };\n      this.#withoutTrailingZerosAndCurrency = getFormatter(\n        options.locale,\n        buildFormatOptions(this.#currencyCode, this.#supported, options, this.#amount),\n      ).format(this.#amount);\n    }\n\n    return this.#withoutTrailingZerosAndCurrency;\n  }\n\n  private get formatterParts(): Intl.NumberFormatPart[] {\n    this.#formatterParts ??= this.#defaultFormatter.formatToParts(this.#amount);\n    return this.#formatterParts;\n  }\n\n  toString(): string {\n    return this.localizedString;\n  }\n}\n\nclass FormattedMoneyRangeValue implements FormattedMoneyRange {\n  readonly localizedString: string;\n  readonly min: MoneyV2;\n  readonly max: MoneyV2;\n  readonly currencyCode: string;\n\n  constructor(range: readonly MoneyV2[], options: FormatMoneyOptions) {\n    if (range.length === 0) {\n      throw new Error(\"formatMoney: money range must contain at least one value\");\n    }\n\n    const entries = sortMoneyRangeEntries(\n      range.map((money) => ({\n        money,\n        amount: parseAmount(money),\n        currencyCode: normalizeCurrencyCode(money.currencyCode),\n      })),\n    );\n\n    const [first] = entries;\n    if (!first) {\n      throw new Error(\"formatMoney: money range must contain at least one value\");\n    }\n\n    const mismatched = entries.find((entry) => entry.currencyCode !== first.currencyCode);\n    if (mismatched) {\n      throw new Error(\n        `formatMoney: range values must share one currency, received ${first.currencyCode} and ${mismatched.currencyCode}`,\n      );\n    }\n\n    const last = entries[entries.length - 1] ?? first;\n    this.min = first.money;\n    this.max = last.money;\n    this.currencyCode = first.currencyCode;\n\n    if (first.amount === last.amount) {\n      this.localizedString = new FormattedMoneyValue(first.money, {\n        ...options,\n        withoutTrailingZeros: options.withoutTrailingZeros ?? !hasExplicitFractionDigits(options),\n      }).localizedString;\n      return;\n    }\n\n    const supported = isWellFormedCurrencyCode(first.currencyCode);\n    const formatter = getFormatter(\n      options.locale,\n      buildRangeOptions(first.currencyCode, supported, options, first.amount, last.amount),\n    );\n\n    const formatted = formatRange(formatter, first.amount, last.amount);\n    this.localizedString =\n      supported || options.withoutCurrency === true\n        ? formatted\n        : appendUnsupportedCurrencyCode(formatted, first.currencyCode);\n  }\n\n  toString(): string {\n    return this.localizedString;\n  }\n}\n\n/**\n * Formats a price or a price range for display. Pass a `MoneyV2` price, or an array of `MoneyV2` prices in one currency for a range, with the active market's locale.\n *\n * The returned object converts to the formatted string in template literals and string concatenation. For custom price layouts, read the parts of the formatted price. A range shows the lowest and highest prices. When every price in the range matches, the output shows one price.\n *\n * The function throws an error when an amount isn't numeric, when a range is empty, or when the prices in a range use different currencies.\n *\n * @publicDocs\n */\nexport function formatMoney(money: MoneyV2, options: FormatMoneyOptions): FormattedMoney;\nexport function formatMoney(\n  money: readonly MoneyV2[],\n  options: FormatMoneyOptions,\n): FormattedMoneyRange;\n\n// This is the implementation of the formatMoney function overloading the other two.\n// It checks if the input is a range and creates the appropriate object.\n/**\n * @param money A price, or an array of prices in one currency for a range.\n * @param options Locale and display settings.\n * @returns The formatted price or range, which converts to a string in template literals.\n */\nexport function formatMoney(\n  money: MoneyV2 | readonly MoneyV2[],\n  options: FormatMoneyOptions,\n): FormattedMoney | FormattedMoneyRange {\n  return isMoneyRange(money)\n    ? new FormattedMoneyRangeValue(money, options)\n    : new FormattedMoneyValue(money, options);\n}\n"],"mappings":"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"}

package/dist/core/money/types.d.mts

@@ -1,45 +1,61 @@
 //#region src/core/money/types.d.ts
 /**
- * Matches the Storefront API's MoneyV2 shape.
- * Uses `string` for currencyCode instead of the generated CurrencyCode enum
- * so the utility also accepts Customer Account API currencies (e.g. USDC)
- * that may not be in the Storefront API's enum.
+ * A price with an amount and a currency code, in the `MoneyV2` shape that the Storefront API and Customer Account API return.
+ * The currency code accepts any string, including Customer Account API currencies such as USDC
+ * that the Storefront API currency enum doesn't list.
  */
 type MoneyV2 = {
-  amount: string;
+  /** Decimal amount as a string, such as `19.99`. `formatMoney` throws an error when the amount doesn't parse as a number. */amount: string;
+  /**
+   * Currency code, such as `USD`, in any letter case.
+   *
+   * A code that isn't three letters formats as a decimal amount followed by the code, such as `19.00 USDC`. An unrecognized three-letter code appears as the code, such as `XYZ 19.00`.
+   */
   currencyCode: string;
 };
+/** Locale and display settings for a formatted price or price range. */
 type FormatMoneyOptions = {
-  /** BCP 47 locale string. e.g. 'en-US', 'fr-CA', 'ja-JP'. */locale: string; /** Omit the currency symbol/code from the output. */
-  withoutCurrency?: boolean; /** Strip trailing fractional zeros. '$19.00' → '$19'. */
-  withoutTrailingZeros?: boolean; /** Override Intl minimumFractionDigits. */
-  minimumFractionDigits?: number; /** Override Intl maximumFractionDigits. */
+  /**
+   * BCP 47 locale, such as `en-US`, `fr-CA`, or `ja-JP`.
+   *
+   * In market-aware storefronts, pass the active market's locale. A hardcoded `en-US` formats every market as US English.
+   */
+  locale: string; /** Pass `true` to leave out the currency symbol or code. Defaults to `false`. */
+  withoutCurrency?: boolean;
+  /**
+   * Pass `true` to drop the fraction digits of a whole amount, such as `$19.00` to `$19`. Amounts with a fraction keep their digits.
+   *
+   * Defaults to `false`. For a range, defaults to `true` when every price is a whole amount and you set neither fraction digit option.
+   */
+  withoutTrailingZeros?: boolean; /** Fewest fraction digits to show. Defaults to the currency's standard number of digits, such as 0 for JPY. Output without a currency symbol defaults to 2. */
+  minimumFractionDigits?: number; /** Most fraction digits to show. Defaults to the currency's standard number of digits, such as 0 for JPY. Output without a currency symbol defaults to 2. */
   maximumFractionDigits?: number;
   /**
-   * Intl.NumberFormat currencyDisplay option.
-   * 'symbol' (default) | 'narrowSymbol' | 'code' | 'name'
+   * How the currency appears: `symbol`, `narrowSymbol`, `code`, or `name`. Defaults to `symbol`.
    *
-   * 'narrowSymbol' is useful for disambiguating $ across CAD/AUD/USD.
+   * In the `en-US` locale, the `symbol` value tells dollar currencies apart, such as `CA$5.00`. The `narrowSymbol` value shows `$5.00` for every dollar currency.
    */
   currencyDisplay?: Intl.NumberFormatOptions["currencyDisplay"];
 };
+/** A formatted price, with structured parts for custom price layouts. */
 type FormattedMoney = {
-  /** The full locale-formatted string. Also returned by toString(). */localizedString: string; /** Just the numeric portion, no currency. '19.99' or '1,299.00'. */
-  amount: string; /** Currency symbol from Intl. '$', '€', '¥', 'CA$', etc. */
-  currencySymbol: string; /** Narrow symbol. '$' even for CAD. Empty string if unavailable. */
-  currencyNarrowSymbol: string; /** Full currency name. 'US dollars', 'Canadian dollars'. */
-  currencyName: string; /** The raw numeric amount as a number. parseFloat(money.amount). */
-  numericAmount: number; /** The raw Intl.NumberFormat parts array. */
-  parts: Intl.NumberFormatPart[]; /** Formatted string with trailing zeros removed. '$19.00' → '$19'. */
-  withoutTrailingZeros: string; /** Amount without currency and without trailing zeros. '19.00' → '19'. */
-  withoutTrailingZerosAndCurrency: string; /** Returns localizedString so the object works in template literals and string concatenation. */
+  /** Formatted price, such as `$1,299.00`. */localizedString: string; /** Formatted number without the currency, such as `1,299.00` or `-19.99`. */
+  amount: string; /** Currency part of the formatted price, such as `$`, `€`, or `CA$`. Follows the `currencyDisplay` option. For a code that isn't three letters, holds the code. For other codes, empty when `withoutCurrency` is `true`. */
+  currencySymbol: string; /** Narrow currency symbol, such as `$` for both USD and CAD. For a code that isn't three letters, holds the code. */
+  currencyNarrowSymbol: string; /** Currency name in the locale's language, such as `US dollars`. Falls back to the currency code. */
+  currencyName: string; /** Amount as a number. */
+  numericAmount: number; /** Typed pieces of the formatted price, such as the currency, integer, and fraction, for custom layouts. */
+  parts: Intl.NumberFormatPart[]; /** Formatted price without the fraction digits of a whole amount, such as `$19`. */
+  withoutTrailingZeros: string; /** Formatted amount without the currency and without the fraction digits of a whole amount, such as `19`. */
+  withoutTrailingZerosAndCurrency: string; /** Returns the formatted price. Template literals and string concatenation call the method for you. */
   toString(): string;
 };
+/** A formatted price range, with its lowest and highest prices. */
 type FormattedMoneyRange = {
-  /** The full locale-formatted range string. Also returned by toString(). */localizedString: string; /** Lowest value in the input range after sorting. */
-  min: MoneyV2; /** Highest value in the input range after sorting. */
-  max: MoneyV2; /** Shared currency code for every range member. */
-  currencyCode: string; /** Returns localizedString so the object works in template literals and string concatenation. */
+  /** The formatted range, such as `$10 – $19`. */localizedString: string; /** Lowest price in the input. */
+  min: MoneyV2; /** Highest price in the input. */
+  max: MoneyV2; /** Currency code that every price in the range shares, in uppercase. */
+  currencyCode: string; /** Returns the formatted range. Template literals and string concatenation call the method for you. */
   toString(): string;
 };
 //#endregion

package/dist/core/predictive-search/form.d.mts

@@ -1,31 +1,61 @@
 //#region src/core/predictive-search/form.d.ts
-/** Props returned by {@link PredictiveSearchFormRegister} for the query input. */
+/**
+ * Attributes to spread on the search input of a predictive search form.
+ *
+ * @publicDocs
+ */
 interface PredictiveSearchQueryInputAttributes {
+  /** Sends the search term as the `q` URL parameter when the form submits. */
   name: "q";
+  /** Renders the input as a search field. */
   type: "search";
+  /** Turns off browser autocomplete. */
   autoComplete: "off";
+  /** Turns off automatic capitalization of the search term. */
   autoCapitalize: "off";
+  /** Turns off spell checking. */
   spellCheck: false;
 }
-/** Props returned by {@link getPredictiveSearchFormAttributes} for the search form. */
+/** Attributes to spread on a predictive search form. */
 interface PredictiveSearchFormAttributes {
+  /** Search page path that receives the submitted search term. Defaults to `/search`. */
   action: string;
+  /** Submits the form as a GET request, which puts the search term in the URL. */
   method: "get";
+  /** Marks the form as a search landmark for assistive technology. */
   role: "search";
 }
 /**
- * Register function returned by predictive search form bindings.
+ * Returns the attributes for the search input of a predictive search form.
  *
- * Predictive search forms only register the Storefront API query input.
+ * Pass `query`. Any other field name throws an error. The attribute keys use React casing. In DOM code, set each value on the matching lowercase property, such as `autocomplete`.
  */
 type PredictiveSearchFormRegister = {
   (field: "query"): PredictiveSearchQueryInputAttributes;
 };
-/** Creates a {@link PredictiveSearchFormRegister} for framework-neutral form fields. */
+/**
+ * Creates a function that returns the attributes for the search input of a predictive search form. Use the function in DOM code or in UI frameworks without Hydrogen bindings. In React and Vue, use `usePredictiveSearchForm`.
+ *
+ * @returns A function that takes `query` and returns the search input attributes.
+ *
+ * @publicDocs
+ */
 declare function createPredictiveSearchFormRegister(): PredictiveSearchFormRegister;
-/** Returns progressive-enhancement attributes for a predictive search form. */
+/**
+ * Returns the attributes for a predictive search form that works without JavaScript.
+ *
+ * @param action Search page path that the form submits to. Defaults to `/search`.
+ * @returns Attributes that submit the search term to the search page as a GET request.
+ * @publicDocs
+ */
 declare function getPredictiveSearchFormAttributes(action?: string): PredictiveSearchFormAttributes;
-/** Reads the search term from form data submitted by a predictive search form. Returns an empty string when the `"q"` field is absent or not a string. */
+/**
+ * Reads the search term from a submitted predictive search form.
+ *
+ * @param formData Form data from the submitted search form.
+ * @returns The search term, or an empty string when the form data has no `q` text value.
+ * @publicDocs
+ */
 declare function readPredictiveSearchFormTerm(formData: FormData): string;
 //#endregion
 export { PredictiveSearchFormAttributes, PredictiveSearchFormRegister, PredictiveSearchQueryInputAttributes, createPredictiveSearchFormRegister, getPredictiveSearchFormAttributes, readPredictiveSearchFormTerm };

package/dist/core/predictive-search/form.mjs

@@ -1,5 +1,11 @@
 //#region src/core/predictive-search/form.ts
-/** Creates a {@link PredictiveSearchFormRegister} for framework-neutral form fields. */
+/**
+* Creates a function that returns the attributes for the search input of a predictive search form. Use the function in DOM code or in UI frameworks without Hydrogen bindings. In React and Vue, use `usePredictiveSearchForm`.
+*
+* @returns A function that takes `query` and returns the search input attributes.
+*
+* @publicDocs
+*/
 function createPredictiveSearchFormRegister() {
 	return registerPredictiveSearchFormField;
 }
@@ -13,7 +19,13 @@ function registerPredictiveSearchFormField(field) {
 		spellCheck: false
 	};
 }
-/** Returns progressive-enhancement attributes for a predictive search form. */
+/**
+* Returns the attributes for a predictive search form that works without JavaScript.
+*
+* @param action Search page path that the form submits to. Defaults to `/search`.
+* @returns Attributes that submit the search term to the search page as a GET request.
+* @publicDocs
+*/
 function getPredictiveSearchFormAttributes(action = "/search") {
 	return {
 		action,
@@ -21,7 +33,13 @@ function getPredictiveSearchFormAttributes(action = "/search") {
 		role: "search"
 	};
 }
-/** Reads the search term from form data submitted by a predictive search form. Returns an empty string when the `"q"` field is absent or not a string. */
+/**
+* Reads the search term from a submitted predictive search form.
+*
+* @param formData Form data from the submitted search form.
+* @returns The search term, or an empty string when the form data has no `q` text value.
+* @publicDocs
+*/
 function readPredictiveSearchFormTerm(formData) {
 	const value = formData.get("q");
 	return typeof value === "string" ? value : "";

package/dist/core/predictive-search/form.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"form.mjs","names":[],"sources":["../../../src/core/predictive-search/form.ts"],"sourcesContent":["import { PREDICTIVE_SEARCH_QUERY_PARAM } from \"./constants\";\n\n/** Props returned by {@link PredictiveSearchFormRegister} for the query input. */\nexport interface PredictiveSearchQueryInputAttributes {\n  name: \"q\";\n  type: \"search\";\n  autoComplete: \"off\";\n  autoCapitalize: \"off\";\n  spellCheck: false;\n}\n\n/** Props returned by {@link getPredictiveSearchFormAttributes} for the search form. */\nexport interface PredictiveSearchFormAttributes {\n  action: string;\n  method: \"get\";\n  role: \"search\";\n}\n\n/**\n * Register function returned by predictive search form bindings.\n *\n * Predictive search forms only register the Storefront API query input.\n */\nexport type PredictiveSearchFormRegister = {\n  (field: \"query\"): PredictiveSearchQueryInputAttributes;\n};\n\n/** Creates a {@link PredictiveSearchFormRegister} for framework-neutral form fields. */\nexport function createPredictiveSearchFormRegister(): PredictiveSearchFormRegister {\n  return registerPredictiveSearchFormField;\n}\n\nfunction registerPredictiveSearchFormField(field: string): PredictiveSearchQueryInputAttributes {\n  if (field !== \"query\") {\n    throw new Error(`Unknown predictive search form field: \"${field}\".`);\n  }\n\n  return {\n    name: \"q\",\n    type: \"search\",\n    autoComplete: \"off\",\n    autoCapitalize: \"off\",\n    spellCheck: false,\n  };\n}\n\n/** Returns progressive-enhancement attributes for a predictive search form. */\nexport function getPredictiveSearchFormAttributes(\n  action: string = \"/search\",\n): PredictiveSearchFormAttributes {\n  return {\n    action,\n    method: \"get\",\n    role: \"search\",\n  };\n}\n\n/** Reads the search term from form data submitted by a predictive search form. Returns an empty string when the `\"q\"` field is absent or not a string. */\nexport function readPredictiveSearchFormTerm(formData: FormData): string {\n  const value = formData.get(PREDICTIVE_SEARCH_QUERY_PARAM);\n  return typeof value === \"string\" ? value : \"\";\n}\n"],"mappings":";;AA4BA,SAAgB,qCAAmE;AACjF,QAAO;;AAGT,SAAS,kCAAkC,OAAqD;AAC9F,KAAI,UAAU,QACZ,OAAM,IAAI,MAAM,0CAA0C,MAAM,IAAI;AAGtE,QAAO;EACL,MAAM;EACN,MAAM;EACN,cAAc;EACd,gBAAgB;EAChB,YAAY;EACb;;;AAIH,SAAgB,kCACd,SAAiB,WACe;AAChC,QAAO;EACL;EACA,QAAQ;EACR,MAAM;EACP;;;AAIH,SAAgB,6BAA6B,UAA4B;CACvE,MAAM,QAAQ,SAAS,QAAkC;AACzD,QAAO,OAAO,UAAU,WAAW,QAAQ"}
+{"version":3,"file":"form.mjs","names":[],"sources":["../../../src/core/predictive-search/form.ts"],"sourcesContent":["import { PREDICTIVE_SEARCH_QUERY_PARAM } from \"./constants\";\n\n/**\n * Attributes to spread on the search input of a predictive search form.\n *\n * @publicDocs\n */\nexport interface PredictiveSearchQueryInputAttributes {\n  /** Sends the search term as the `q` URL parameter when the form submits. */\n  name: \"q\";\n  /** Renders the input as a search field. */\n  type: \"search\";\n  /** Turns off browser autocomplete. */\n  autoComplete: \"off\";\n  /** Turns off automatic capitalization of the search term. */\n  autoCapitalize: \"off\";\n  /** Turns off spell checking. */\n  spellCheck: false;\n}\n\n/** Attributes to spread on a predictive search form. */\nexport interface PredictiveSearchFormAttributes {\n  /** Search page path that receives the submitted search term. Defaults to `/search`. */\n  action: string;\n  /** Submits the form as a GET request, which puts the search term in the URL. */\n  method: \"get\";\n  /** Marks the form as a search landmark for assistive technology. */\n  role: \"search\";\n}\n\n/**\n * Returns the attributes for the search input of a predictive search form.\n *\n * Pass `query`. Any other field name throws an error. The attribute keys use React casing. In DOM code, set each value on the matching lowercase property, such as `autocomplete`.\n */\nexport type PredictiveSearchFormRegister = {\n  (field: \"query\"): PredictiveSearchQueryInputAttributes;\n};\n\n/**\n * Creates a function that returns the attributes for the search input of a predictive search form. Use the function in DOM code or in UI frameworks without Hydrogen bindings. In React and Vue, use `usePredictiveSearchForm`.\n *\n * @returns A function that takes `query` and returns the search input attributes.\n *\n * @publicDocs\n */\nexport function createPredictiveSearchFormRegister(): PredictiveSearchFormRegister {\n  return registerPredictiveSearchFormField;\n}\n\nfunction registerPredictiveSearchFormField(field: string): PredictiveSearchQueryInputAttributes {\n  if (field !== \"query\") {\n    throw new Error(`Unknown predictive search form field: \"${field}\".`);\n  }\n\n  return {\n    name: \"q\",\n    type: \"search\",\n    autoComplete: \"off\",\n    autoCapitalize: \"off\",\n    spellCheck: false,\n  };\n}\n\n/**\n * Returns the attributes for a predictive search form that works without JavaScript.\n *\n * @param action Search page path that the form submits to. Defaults to `/search`.\n * @returns Attributes that submit the search term to the search page as a GET request.\n * @publicDocs\n */\nexport function getPredictiveSearchFormAttributes(\n  action: string = \"/search\",\n): PredictiveSearchFormAttributes {\n  return {\n    action,\n    method: \"get\",\n    role: \"search\",\n  };\n}\n\n/**\n * Reads the search term from a submitted predictive search form.\n *\n * @param formData Form data from the submitted search form.\n * @returns The search term, or an empty string when the form data has no `q` text value.\n * @publicDocs\n */\nexport function readPredictiveSearchFormTerm(formData: FormData): string {\n  const value = formData.get(PREDICTIVE_SEARCH_QUERY_PARAM);\n  return typeof value === \"string\" ? value : \"\";\n}\n"],"mappings":";;;;;;;;AA8CA,SAAgB,qCAAmE;AACjF,QAAO;;AAGT,SAAS,kCAAkC,OAAqD;AAC9F,KAAI,UAAU,QACZ,OAAM,IAAI,MAAM,0CAA0C,MAAM,IAAI;AAGtE,QAAO;EACL,MAAM;EACN,MAAM;EACN,cAAc;EACd,gBAAgB;EAChB,YAAY;EACb;;;;;;;;;AAUH,SAAgB,kCACd,SAAiB,WACe;AAChC,QAAO;EACL;EACA,QAAQ;EACR,MAAM;EACP;;;;;;;;;AAUH,SAAgB,6BAA6B,UAA4B;CACvE,MAAM,QAAQ,SAAS,QAAkC;AACzD,QAAO,OAAO,UAAU,WAAW,QAAQ"}

package/dist/core/predictive-search/queries.d.mts

@@ -92,61 +92,49 @@ declare const DEFAULT_QUERY_FRAGMENT: StorefrontQueryString<{
   text: string;
 }, never, "\n  fragment PredictiveSearchQueryFragment on SearchQuerySuggestion {\n    text\n  }\n">;
 /**
- * Additional GraphQL fragments that select extra fields on each predictive search result type.
+ * GraphQL fragments that add fields to each type of predictive search result.
  *
- * Each fragment must be named and typed as follows, or
- * `makePredictiveSearchQueries` throws:
- *
- * - `product`: `fragment PredictiveSearchProductFragment on Product`
- * - `collection`: `fragment PredictiveSearchCollectionFragment on Collection`
- * - `page`: `fragment PredictiveSearchPageFragment on Page`
- * - `article`: `fragment PredictiveSearchArticleFragment on Article`
- * - `query`: `fragment PredictiveSearchQueryFragment on SearchQuerySuggestion`
- *
- * Hydrogen's own fields (used for URL generation, tracking, and display) are
- * always selected; custom fragments are merged alongside them.
+ * Each fragment needs the name and type that its option lists, or `makePredictiveSearchQueries` throws an error.
+ * Results keep Hydrogen's built-in fields for links, tracking, and display.
  */
 type PredictiveSearchFragments = {
-  readonly product?: AnyStorefrontQueryString;
-  readonly collection?: AnyStorefrontQueryString;
-  readonly page?: AnyStorefrontQueryString;
-  readonly article?: AnyStorefrontQueryString;
+  /** Adds fields to product results. Start the fragment with `fragment PredictiveSearchProductFragment on Product`. */readonly product?: AnyStorefrontQueryString; /** Adds fields to collection results. Start the fragment with `fragment PredictiveSearchCollectionFragment on Collection`. */
+  readonly collection?: AnyStorefrontQueryString; /** Adds fields to page results. Start the fragment with `fragment PredictiveSearchPageFragment on Page`. */
+  readonly page?: AnyStorefrontQueryString; /** Adds fields to article results. Start the fragment with `fragment PredictiveSearchArticleFragment on Article`. */
+  readonly article?: AnyStorefrontQueryString; /** Adds fields to query suggestions. Start the fragment with `fragment PredictiveSearchQueryFragment on SearchQuerySuggestion`. */
   readonly query?: AnyStorefrontQueryString;
 };
-/** Options for {@link makePredictiveSearchQueries}. */
+/** Options for a custom predictive search query. */
 type CreatePredictiveSearchQueriesOptions<TFragments extends PredictiveSearchFragments = PredictiveSearchFragments> = {
-  /** Extra fields to select per result type. Hydrogen's built-in fields are always included. */readonly fragments?: TFragments;
+  /** Fragments that add fields to each result type. Results keep Hydrogen's built-in fields. */readonly fragments?: TFragments;
 };
 type FragmentForOptions<TOptions, TKey extends keyof PredictiveSearchFragments, TDefault extends AnyStorefrontQueryString> = TOptions extends {
   readonly fragments: infer TFragments;
 } ? TFragments extends Record<TKey, infer TFragment extends AnyStorefrontQueryString> ? TFragment : TDefault : TDefault;
 type PredictiveSearchQueryFragmentsForOptions<TOptions> = [FragmentForOptions<TOptions, "product", typeof DEFAULT_PRODUCT_FRAGMENT>, FragmentForOptions<TOptions, "collection", typeof DEFAULT_COLLECTION_FRAGMENT>, FragmentForOptions<TOptions, "page", typeof DEFAULT_PAGE_FRAGMENT>, FragmentForOptions<TOptions, "article", typeof DEFAULT_ARTICLE_FRAGMENT>, FragmentForOptions<TOptions, "query", typeof DEFAULT_QUERY_FRAGMENT>];
 type PredictiveSearchQuerySourceForOptions<TOptions> = ComposedSource<SourceOf<typeof PREDICTIVE_SEARCH_QUERY>, PredictiveSearchQueryFragmentsForOptions<TOptions>>;
+/** Type of a custom predictive search query, with result types from your fragments. */
 type PredictiveSearchQueryForOptions<TOptions> = StorefrontQueryString<InferResult<PredictiveSearchQuerySourceForOptions<TOptions>>, InferVariables<PredictiveSearchQuerySourceForOptions<TOptions>>, PredictiveSearchQuerySourceForOptions<TOptions>>;
-/** Resolves the query map shape from {@link CreatePredictiveSearchQueriesOptions}, preserving full type inference from custom fragments. */
+/** Type of the object that makePredictiveSearchQueries returns, with result types from your fragments. */
 type PredictiveSearchQueriesForOptions<TOptions> = {
   readonly predictiveSearch: PredictiveSearchQueryForOptions<TOptions>;
 };
 /**
- * Composes the predictive search GraphQL query document from the built-in
- * base query and either custom or default fragments.
- *
- * Custom fragments are validated at runtime against their expected names
- * and target GraphQL types. See {@link PredictiveSearchFragments} for the
- * naming contract.
+ * Builds a predictive search query that adds the fields from your fragments to the results.
  *
- * The returned object's `predictiveSearch` key carries the composed query
- * with full type inference from the provided fragments.
+ * Pass the query to `queryPredictiveSearch`, or pass the same fragments to `createPredictiveSearchServerHandlers`. TypeScript types the results from your fragments.
+ * The function throws an error when a fragment doesn't use its required name and type.
  *
  * @throws {Error} When a custom fragment does not match its required name or target type.
+ * @publicDocs
  */
 declare function makePredictiveSearchQueries<const TOptions extends CreatePredictiveSearchQueriesOptions>(options: TOptions): PredictiveSearchQueriesForOptions<TOptions>;
 declare function makePredictiveSearchQueries(): PredictiveSearchQueriesForOptions<undefined>;
 /**
- * Internal default query object built from Hydrogen's default fragments;
- * used when `query` is omitted.
+ * Hydrogen's built-in predictive search query, under `predictiveSearch`.
+ * queryPredictiveSearch uses the query when you omit the `query` option.
  *
- * Build custom query documents with {@link makePredictiveSearchQueries}.
+ * To add fields to the results, use makePredictiveSearchQueries.
  */
 declare const predictiveSearchQueries: PredictiveSearchQueriesForOptions<undefined>;
 //#endregion

package/dist/core/predictive-search/queries.mjs

@@ -71,14 +71,18 @@ function resolveFragments(fragments) {
 		fragments?.query ?? DEFAULT_QUERY_FRAGMENT
 	];
 }
+/**
+* @param options Fragments that add fields to each result type.
+* @returns An object with the query under `predictiveSearch`.
+*/
 function makePredictiveSearchQueries(options) {
 	return { predictiveSearch: gql(PREDICTIVE_SEARCH_QUERY, resolveFragments(options?.fragments)) };
 }
 /**
-* Internal default query object built from Hydrogen's default fragments;
-* used when `query` is omitted.
+* Hydrogen's built-in predictive search query, under `predictiveSearch`.
+* queryPredictiveSearch uses the query when you omit the `query` option.
 *
-* Build custom query documents with {@link makePredictiveSearchQueries}.
+* To add fields to the results, use makePredictiveSearchQueries.
 */
 const predictiveSearchQueries = makePredictiveSearchQueries();