@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/core/product/options.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"options.mjs","names":[],"sources":["../../../src/core/product/options.ts"],"sourcesContent":["import { getLogger } from \"../logging\";\nimport type {\n  ProductInput,\n  ProductOptionValueFrom,\n  ProductVariantFrom,\n  ProductVariantInput,\n  SelectedOption,\n  VariantOptionState,\n  VariantOptionValueState,\n} from \"./state\";\nimport { VARIANT_SEARCH_PARAM } from \"./url\";\n\nconst log = getLogger(\"product\");\n\nconst INCLUSIVE_RANGE_END_OFFSET = 1;\n\nexport type DecodedVariantCache = Map<string, number[][]>;\n\ntype EncodedVariantConstraint = {\n  optionIndex: number;\n  valueIndex: number;\n};\n\n/**\n * Extracts selected product options from search params.\n *\n * Each query parameter is treated as an option name/value pair\n * (e.g. `?Color=Red&Size=M` → `[{name:\"Color\",value:\"Red\"},{name:\"Size\",value:\"M\"}]`).\n *\n * The `variant` param is reserved for numeric variant ids (Liquid parity) and is\n * never treated as an option name, even when listed in `allowedOptionNames`.\n *\n * When `allowedOptionNames` is provided, the search params are filtered to only\n * entries whose decoded param name exactly matches a product option name.\n * Passing an empty array filters out every option.\n *\n * Pass the result to `createProductFormStore` as `selectedOptions`. Used as a\n * fallback when the product has no `selectedOrFirstAvailableVariant`.\n *\n * @example\n * ```ts\n * // Loader (React Router / Remix)\n * const selectedOptions = getSelectedProductOptions({\n *   searchParams: new URL(request.url).searchParams,\n * });\n *\n * // Filter to known product option names when product data is available\n * const selectedOptions = getSelectedProductOptions({\n *   searchParams,\n *   allowedOptionNames: product.options.map((option) => option.name),\n * });\n * ```\n */\nexport function getSelectedProductOptions({\n  searchParams,\n  allowedOptionNames,\n}: {\n  searchParams: URLSearchParams;\n  allowedOptionNames?: readonly string[];\n}): SelectedOption[] {\n  const allowedOptionNameSet = allowedOptionNames ? new Set(allowedOptionNames) : null;\n  const selectedOptions: SelectedOption[] = [];\n\n  for (const [name, value] of searchParams.entries()) {\n    if (name === VARIANT_SEARCH_PARAM) continue;\n    if (allowedOptionNameSet && !allowedOptionNameSet.has(name)) continue;\n    selectedOptions.push({ name, value });\n  }\n\n  return selectedOptions;\n}\n\nfunction getAdjacentAndFirstSelectableVariants<TProduct extends ProductInput>(\n  product: TProduct,\n): ProductVariantFrom<TProduct>[] {\n  // Shopify returns a bounded set, not the whole matrix. Treat it as a concrete-variant cache.\n  const variants = new Map<string, ProductVariantFrom<TProduct>>();\n\n  for (const option of product.options) {\n    for (const value of option.optionValues) {\n      if (isConcreteProductVariant<TProduct>(value.firstSelectableVariant)) {\n        addVariant(variants, value.firstSelectableVariant, product.options);\n      }\n    }\n  }\n\n  for (const variant of product.adjacentVariants) {\n    if (isConcreteProductVariant<TProduct>(variant)) addVariant(variants, variant, product.options);\n  }\n\n  if (isConcreteProductVariant<TProduct>(product.selectedOrFirstAvailableVariant)) {\n    addVariant(variants, product.selectedOrFirstAvailableVariant, product.options);\n  }\n\n  return [...variants.values()];\n}\n\nexport function buildProductOptions<TProduct extends ProductInput>(\n  product: TProduct,\n  selectedOptions: SelectedOption[],\n  cache?: DecodedVariantCache,\n): VariantOptionState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[] {\n  const selectedOptionMap = selectedOptionsToMap(selectedOptions);\n  const optionValueIndex = buildOptionValueIndex(product);\n  const selectableVariants = getAdjacentAndFirstSelectableVariants(product);\n  const encodedOptionIndexes = buildEncodedOptionIndexes(product, selectableVariants);\n  const variants = mapVariants(product, selectableVariants);\n  const currentProductOptionValues = buildCurrentProductOptionValues(product, selectableVariants);\n\n  return product.options.map((option) => ({\n    name: option.name,\n    values: option.optionValues.map((value) =>\n      buildProductOptionValue({\n        cache,\n        currentProductOptionValues,\n        encodedOptionIndexes,\n        option,\n        optionValueIndex,\n        product,\n        selectedOptionMap,\n        value,\n        variants,\n      }),\n    ),\n  }));\n}\n\nexport function selectedOptionsToMap(selectedOptions: SelectedOption[]): Record<string, string> {\n  const map: Record<string, string> = Object.create(null);\n  for (const option of selectedOptions) {\n    map[option.name] = option.value;\n  }\n  return map;\n}\n\nfunction selectedOptionsKey(\n  selectedOptions: SelectedOption[],\n  productOptions: Array<{ name: string }>,\n): string {\n  return JSON.stringify(\n    selectedOptionsFromMap({ options: productOptions }, selectedOptionsToMap(selectedOptions)),\n  );\n}\n\nexport function selectedOptionsFromMap(\n  product: { options: Array<{ name: string }> },\n  selectedOptionMap: Record<string, string>,\n): SelectedOption[] {\n  const selectedOptions: SelectedOption[] = [];\n  for (const option of product.options) {\n    const value = selectedOptionMap[option.name];\n    if (value !== undefined) selectedOptions.push({ name: option.name, value });\n  }\n  return selectedOptions;\n}\n\nfunction mapVariants<TProduct extends ProductInput>(\n  product: TProduct,\n  selectableVariants: ProductVariantFrom<TProduct>[],\n): Map<string, ProductVariantFrom<TProduct>> {\n  const variants = new Map<string, ProductVariantFrom<TProduct>>();\n  for (const variant of selectableVariants) {\n    variants.set(selectedOptionsKey(variant.selectedOptions, product.options), variant);\n  }\n  return variants;\n}\n\nfunction addVariant<TVariant extends ProductVariantInput>(\n  variants: Map<string, TVariant>,\n  variant: TVariant,\n  productOptions: Array<{ name: string }>,\n): void {\n  variants.set(selectedOptionsKey(variant.selectedOptions, productOptions), variant);\n}\n\nfunction buildProductOptionValue<TProduct extends ProductInput>({\n  cache,\n  currentProductOptionValues,\n  encodedOptionIndexes,\n  option,\n  optionValueIndex,\n  product,\n  selectedOptionMap,\n  value,\n  variants,\n}: {\n  cache?: DecodedVariantCache;\n  currentProductOptionValues: Map<string, Set<string>>;\n  encodedOptionIndexes: Map<string, Map<string, number>>;\n  option: TProduct[\"options\"][number];\n  optionValueIndex: Map<string, Map<string, number>>;\n  product: TProduct;\n  selectedOptionMap: Record<string, string>;\n  value: ProductOptionValueFrom<TProduct>;\n  variants: Map<string, ProductVariantFrom<TProduct>>;\n}): VariantOptionValueState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>> {\n  const firstSelectableVariant = isConcreteProductVariant<TProduct>(value.firstSelectableVariant)\n    ? value.firstSelectableVariant\n    : null;\n  const selected = selectedOptionMap[option.name] === value.name;\n  const crossProduct = isCrossProductOptionValue(\n    product,\n    option.name,\n    value.name,\n    firstSelectableVariant,\n    currentProductOptionValues,\n  );\n  const targetOptionMap = buildTargetOptionMap({\n    currentProductOptionValues,\n    crossProduct,\n    firstSelectableVariant,\n    optionName: option.name,\n    selectedOptionMap,\n    valueName: value.name,\n  });\n  const targetSelectedOptions = selectedOptionsFromMap(product, targetOptionMap);\n  const key = selectedOptionsKey(targetSelectedOptions, product.options);\n  const variant = variants.get(key) ?? null;\n  const targetProductHandle = getTargetProductHandle(product, crossProduct, firstSelectableVariant);\n  const encodingConstraints = buildEncodingConstraints(\n    targetOptionMap,\n    product,\n    optionValueIndex,\n    encodedOptionIndexes.get(targetProductHandle),\n  );\n\n  return {\n    name: value.name,\n    swatch: value.swatch,\n    selected,\n    exists: resolveEncodedStatus(product.encodedVariantExistence, encodingConstraints, true, cache),\n    available: resolveEncodedStatus(\n      product.encodedVariantAvailability,\n      encodingConstraints,\n      variant?.availableForSale ?? false,\n      cache,\n    ),\n    variant,\n    selectedOptions: variant?.selectedOptions ?? targetSelectedOptions,\n    handle: getOptionValueHandle(selected, product.handle, variant, firstSelectableVariant),\n  };\n}\n\nfunction getOptionValueHandle<TVariant extends ProductVariantInput>(\n  selected: boolean,\n  productHandle: string,\n  variant: TVariant | null,\n  firstSelectableVariant: TVariant | null,\n): string {\n  if (selected) return productHandle;\n  return variant?.product?.handle ?? firstSelectableVariant?.product?.handle ?? productHandle;\n}\n\nfunction buildOptionValueIndex<TProduct extends ProductInput>(\n  product: TProduct,\n): Map<string, Map<string, number>> {\n  return new Map(\n    product.options.map((option) => [\n      option.name,\n      new Map(option.optionValues.map((value, index) => [value.name, index])),\n    ]),\n  );\n}\n\nfunction getTargetProductHandle<TVariant extends ProductVariantInput>(\n  product: ProductInput,\n  crossProduct: boolean,\n  firstSelectableVariant: TVariant | null,\n): string {\n  if (crossProduct && firstSelectableVariant?.product?.handle) {\n    return firstSelectableVariant.product.handle;\n  }\n  return product.handle;\n}\n\nfunction buildEncodedOptionIndexes<TProduct extends ProductInput>(\n  product: TProduct,\n  selectableVariants: ProductVariantFrom<TProduct>[],\n): Map<string, Map<string, number>> {\n  const indexes = new Map<string, Map<string, number>>();\n  for (const variant of selectableVariants) {\n    const productHandle = variant.product?.handle ?? product.handle;\n    addEncodedOptionIndex(indexes, productHandle, product.options, variant.selectedOptions);\n  }\n  return indexes;\n}\n\nfunction addEncodedOptionIndex(\n  indexes: Map<string, Map<string, number>>,\n  productHandle: string,\n  productOptions: Array<{ name: string }>,\n  selectedOptions: SelectedOption[],\n): void {\n  const index = indexes.get(productHandle) ?? new Map<string, number>();\n  const selectedOptionNames = new Set(selectedOptions.map((option) => option.name));\n\n  for (const option of productOptions) {\n    if (!selectedOptionNames.has(option.name) || index.has(option.name)) continue;\n    index.set(option.name, index.size);\n  }\n\n  indexes.set(productHandle, index);\n}\n\nfunction buildCurrentProductOptionValues<TProduct extends ProductInput>(\n  product: TProduct,\n  selectableVariants: ProductVariantFrom<TProduct>[],\n): Map<string, Set<string>> {\n  const optionValues = new Map<string, Set<string>>();\n  for (const variant of selectableVariants) {\n    if (!variantBelongsToProduct(product, variant)) continue;\n    for (const option of variant.selectedOptions) {\n      addCurrentProductOptionValue(optionValues, option.name, option.value);\n    }\n  }\n  return optionValues;\n}\n\nfunction addCurrentProductOptionValue(\n  optionValues: Map<string, Set<string>>,\n  optionName: string,\n  valueName: string,\n): void {\n  const values = optionValues.get(optionName) ?? new Set<string>();\n  values.add(valueName);\n  optionValues.set(optionName, values);\n}\n\nfunction isCrossProductOptionValue<TVariant extends ProductVariantInput>(\n  product: ProductInput,\n  optionName: string,\n  valueName: string,\n  firstSelectableVariant: TVariant | null,\n  currentProductOptionValues: Map<string, Set<string>>,\n): boolean {\n  if (!firstSelectableVariant || variantBelongsToProduct(product, firstSelectableVariant)) {\n    return false;\n  }\n  return !currentProductOptionValues.get(optionName)?.has(valueName);\n}\n\nfunction variantBelongsToProduct<TVariant extends ProductVariantInput>(\n  product: ProductInput,\n  variant: TVariant,\n): boolean {\n  return variant.product?.handle === undefined || variant.product.handle === product.handle;\n}\n\ntype TargetOptionMapInput<TVariant extends ProductVariantInput> = {\n  currentProductOptionValues: Map<string, Set<string>>;\n  crossProduct: boolean;\n  firstSelectableVariant: TVariant | null;\n  optionName: string;\n  selectedOptionMap: Record<string, string>;\n  valueName: string;\n};\n\nfunction buildTargetOptionMap<TVariant extends ProductVariantInput>({\n  currentProductOptionValues,\n  crossProduct,\n  firstSelectableVariant,\n  optionName,\n  selectedOptionMap,\n  valueName,\n}: TargetOptionMapInput<TVariant>): Record<string, string> {\n  if (crossProduct && firstSelectableVariant) {\n    return selectedOptionsToMap(firstSelectableVariant.selectedOptions);\n  }\n\n  const nextOptionMap = { ...selectedOptionMap, [optionName]: valueName };\n  if (currentProductOptionValues.size === 0) return nextOptionMap;\n  return filterOptionMap(nextOptionMap, currentProductOptionValues);\n}\n\nfunction filterOptionMap(\n  selectedOptionMap: Record<string, string>,\n  currentProductOptionValues: Map<string, Set<string>>,\n): Record<string, string> {\n  const filtered: Record<string, string> = Object.create(null);\n  for (const [optionName, values] of currentProductOptionValues) {\n    const value = selectedOptionMap[optionName];\n    if (value !== undefined && values.has(value)) filtered[optionName] = value;\n  }\n  return filtered;\n}\n\nfunction buildEncodingConstraints<TProduct extends ProductInput>(\n  selectedOptionMap: Record<string, string>,\n  product: TProduct,\n  optionValueIndex = buildOptionValueIndex(product),\n  encodedOptionIndex?: Map<string, number>,\n): EncodedVariantConstraint[] {\n  const constraints: EncodedVariantConstraint[] = [];\n\n  for (const [productOptionIndex, option] of product.options.entries()) {\n    const selectedValue = selectedOptionMap[option.name];\n    if (selectedValue === undefined) continue;\n    const optionIndex = encodedOptionIndex?.get(option.name) ?? productOptionIndex;\n    const valueIndex = optionValueIndex.get(option.name)?.get(selectedValue);\n    if (valueIndex === undefined) continue;\n    constraints.push({ optionIndex, valueIndex });\n  }\n\n  return constraints;\n}\n\nfunction resolveEncodedStatus(\n  encodedField: string | null | undefined,\n  constraints: EncodedVariantConstraint[],\n  fallback: boolean,\n  cache?: DecodedVariantCache,\n): boolean {\n  if (!encodedField) return fallback;\n  return isAnyEncodedVariantMatchingConstraints(constraints, encodedField, cache);\n}\n\nfunction isAnyEncodedVariantMatchingConstraints(\n  constraints: EncodedVariantConstraint[],\n  encodedVariantField: string,\n  cache?: DecodedVariantCache,\n): boolean {\n  if (constraints.length === 0) return false;\n\n  return getDecodedVariantCombinations(encodedVariantField, cache).some((combination) =>\n    combinationMatchesConstraints(combination, constraints),\n  );\n}\n\nfunction getDecodedVariantCombinations(\n  encodedVariantField: string,\n  cache?: DecodedVariantCache,\n): number[][] {\n  const cached = cache?.get(encodedVariantField);\n  if (cached) return cached;\n\n  const decoded = decodeEncodedVariant(encodedVariantField);\n  cache?.set(encodedVariantField, decoded);\n  return decoded;\n}\n\nfunction combinationMatchesConstraints(\n  combination: number[],\n  constraints: EncodedVariantConstraint[],\n): boolean {\n  return constraints.every(\n    ({ optionIndex, valueIndex }) => combination[optionIndex] === valueIndex,\n  );\n}\n\nfunction decodeEncodedVariant(encodedVariantField: string | null | undefined): number[][] {\n  if (!encodedVariantField) return [];\n  if (!encodedVariantField.startsWith(\"v1_\")) {\n    log.warn(`unsupported variant encoding: \"${encodedVariantField}\"`);\n    return [];\n  }\n  return decodeV1EncodedVariant(encodedVariantField.replace(/^v1_/, \"\"));\n}\n\nfunction decodeV1EncodedVariant(encodedVariantField: string): number[][] {\n  const tokenizer = /[ :,-]/g;\n  const state: DecodeV1State = {\n    currentOptionValue: [],\n    decodedOptions: [],\n    depth: 0,\n    index: 0,\n    rangeStart: null,\n  };\n  let token: RegExpExecArray | null;\n\n  while ((token = tokenizer.exec(encodedVariantField))) {\n    processDecodeV1Token(encodedVariantField, state, token, tokenizer);\n  }\n\n  pushFinalDecodeV1Value(encodedVariantField, state);\n\n  return state.decodedOptions;\n}\n\ntype DecodeV1State = {\n  currentOptionValue: number[];\n  decodedOptions: number[][];\n  depth: number;\n  index: number;\n  rangeStart: number | null;\n};\n\nfunction isConcreteProductVariant<TProduct extends ProductInput>(\n  variant: ProductVariantInput | null | undefined,\n): variant is ProductVariantFrom<TProduct> {\n  return variant !== null && variant !== undefined;\n}\n\nfunction processDecodeV1Token(\n  encodedVariantField: string,\n  state: DecodeV1State,\n  token: RegExpExecArray,\n  tokenizer: RegExp,\n): void {\n  const operation = token[0];\n  const optionValueIndex =\n    Number.parseInt(encodedVariantField.slice(state.index, token.index), 10) || 0;\n\n  pushDecodeV1Range(state, optionValueIndex);\n  state.currentOptionValue[state.depth] = optionValueIndex;\n\n  if (operation === \"-\") {\n    state.rangeStart = optionValueIndex;\n  } else if (operation === \":\") {\n    state.depth++;\n  } else {\n    processDecodeV1Separator(encodedVariantField, state, token, operation);\n  }\n\n  state.index = tokenizer.lastIndex;\n}\n\nfunction processDecodeV1Separator(\n  encodedVariantField: string,\n  state: DecodeV1State,\n  token: RegExpExecArray,\n  operation: string,\n): void {\n  if (shouldPushDecodeV1Option(encodedVariantField, token, operation)) {\n    state.decodedOptions.push([...state.currentOptionValue]);\n  }\n\n  if (operation !== \",\") return;\n\n  state.currentOptionValue.pop();\n  state.depth--;\n}\n\nfunction shouldPushDecodeV1Option(\n  encodedVariantField: string,\n  token: RegExpExecArray,\n  operation: string,\n): boolean {\n  return operation === \" \" || (operation === \",\" && encodedVariantField[token.index - 1] !== \",\");\n}\n\nfunction pushFinalDecodeV1Value(encodedVariantField: string, state: DecodeV1State): void {\n  const finalIndex = encodedVariantField.match(/\\d+$/g)?.[0];\n  if (finalIndex === undefined) return;\n\n  const finalValueIndex = Number.parseInt(finalIndex, 10);\n  if (state.rangeStart !== null) {\n    pushDecodeV1Range(state, finalValueIndex + INCLUSIVE_RANGE_END_OFFSET);\n    return;\n  }\n\n  state.currentOptionValue[state.depth] = finalValueIndex;\n  state.decodedOptions.push([...state.currentOptionValue]);\n}\n\nfunction pushDecodeV1Range(state: DecodeV1State, rangeEndExclusive: number): void {\n  const rangeStart = state.rangeStart;\n  if (rangeStart === null) return;\n\n  for (let value = rangeStart; value < rangeEndExclusive; value++) {\n    state.currentOptionValue[state.depth] = value;\n    state.decodedOptions.push([...state.currentOptionValue]);\n  }\n\n  state.rangeStart = null;\n}\n"],"mappings":"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"}
+{"version":3,"file":"options.mjs","names":[],"sources":["../../../src/core/product/options.ts"],"sourcesContent":["import { getLogger } from \"../logging\";\nimport type {\n  ProductInput,\n  ProductOptionValueFrom,\n  ProductVariantFrom,\n  ProductVariantInput,\n  SelectedOption,\n  VariantOptionState,\n  VariantOptionValueState,\n} from \"./state\";\nimport { VARIANT_SEARCH_PARAM } from \"./url\";\n\nconst log = getLogger(\"product\");\n\nconst INCLUSIVE_RANGE_END_OFFSET = 1;\n\nexport type DecodedVariantCache = Map<string, number[][]>;\n\ntype EncodedVariantConstraint = {\n  optionIndex: number;\n  valueIndex: number;\n};\n\n/**\n * Reads the customer's option selection from a product URL's search params.\n *\n * Each param becomes an option name and value. For example, `?Color=Red&Size=M`\n * becomes Color set to Red and Size set to M. The function always skips the `variant` param,\n * which holds a numeric variant ID in Liquid storefront URLs.\n *\n * Pass the result as the `selectedOptions` argument of your Storefront API product query, or as the starting selection of a product form store.\n *\n * @param input The search params to read and an optional list of allowed option names. With `allowedOptionNames`, the function keeps only params whose name exactly matches an allowed name, and an empty list keeps no params. Pass the product's option names to keep unrelated params out of the selection.\n *\n * @returns The selected options, in the order that they appear in the URL.\n *\n * @example\n * ```ts\n * // Loader (React Router / Remix)\n * const selectedOptions = getSelectedProductOptions({\n *   searchParams: new URL(request.url).searchParams,\n * });\n *\n * // Filter to known product option names when product data is available\n * const selectedOptions = getSelectedProductOptions({\n *   searchParams,\n *   allowedOptionNames: product.options.map((option) => option.name),\n * });\n * ```\n * @publicDocs\n */\nexport function getSelectedProductOptions({\n  searchParams,\n  allowedOptionNames,\n}: {\n  searchParams: URLSearchParams;\n  allowedOptionNames?: readonly string[];\n}): SelectedOption[] {\n  const allowedOptionNameSet = allowedOptionNames ? new Set(allowedOptionNames) : null;\n  const selectedOptions: SelectedOption[] = [];\n\n  for (const [name, value] of searchParams.entries()) {\n    if (name === VARIANT_SEARCH_PARAM) continue;\n    if (allowedOptionNameSet && !allowedOptionNameSet.has(name)) continue;\n    selectedOptions.push({ name, value });\n  }\n\n  return selectedOptions;\n}\n\nfunction getAdjacentAndFirstSelectableVariants<TProduct extends ProductInput>(\n  product: TProduct,\n): ProductVariantFrom<TProduct>[] {\n  // Shopify returns a bounded set, not the whole matrix. Treat it as a concrete-variant cache.\n  const variants = new Map<string, ProductVariantFrom<TProduct>>();\n\n  for (const option of product.options) {\n    for (const value of option.optionValues) {\n      if (isConcreteProductVariant<TProduct>(value.firstSelectableVariant)) {\n        addVariant(variants, value.firstSelectableVariant, product.options);\n      }\n    }\n  }\n\n  for (const variant of product.adjacentVariants) {\n    if (isConcreteProductVariant<TProduct>(variant)) addVariant(variants, variant, product.options);\n  }\n\n  if (isConcreteProductVariant<TProduct>(product.selectedOrFirstAvailableVariant)) {\n    addVariant(variants, product.selectedOrFirstAvailableVariant, product.options);\n  }\n\n  return [...variants.values()];\n}\n\nexport function buildProductOptions<TProduct extends ProductInput>(\n  product: TProduct,\n  selectedOptions: SelectedOption[],\n  cache?: DecodedVariantCache,\n): VariantOptionState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[] {\n  const selectedOptionMap = selectedOptionsToMap(selectedOptions);\n  const optionValueIndex = buildOptionValueIndex(product);\n  const selectableVariants = getAdjacentAndFirstSelectableVariants(product);\n  const encodedOptionIndexes = buildEncodedOptionIndexes(product, selectableVariants);\n  const variants = mapVariants(product, selectableVariants);\n  const currentProductOptionValues = buildCurrentProductOptionValues(product, selectableVariants);\n\n  return product.options.map((option) => ({\n    name: option.name,\n    values: option.optionValues.map((value) =>\n      buildProductOptionValue({\n        cache,\n        currentProductOptionValues,\n        encodedOptionIndexes,\n        option,\n        optionValueIndex,\n        product,\n        selectedOptionMap,\n        value,\n        variants,\n      }),\n    ),\n  }));\n}\n\nexport function selectedOptionsToMap(selectedOptions: SelectedOption[]): Record<string, string> {\n  const map: Record<string, string> = Object.create(null);\n  for (const option of selectedOptions) {\n    map[option.name] = option.value;\n  }\n  return map;\n}\n\nfunction selectedOptionsKey(\n  selectedOptions: SelectedOption[],\n  productOptions: Array<{ name: string }>,\n): string {\n  return JSON.stringify(\n    selectedOptionsFromMap({ options: productOptions }, selectedOptionsToMap(selectedOptions)),\n  );\n}\n\nexport function selectedOptionsFromMap(\n  product: { options: Array<{ name: string }> },\n  selectedOptionMap: Record<string, string>,\n): SelectedOption[] {\n  const selectedOptions: SelectedOption[] = [];\n  for (const option of product.options) {\n    const value = selectedOptionMap[option.name];\n    if (value !== undefined) selectedOptions.push({ name: option.name, value });\n  }\n  return selectedOptions;\n}\n\nfunction mapVariants<TProduct extends ProductInput>(\n  product: TProduct,\n  selectableVariants: ProductVariantFrom<TProduct>[],\n): Map<string, ProductVariantFrom<TProduct>> {\n  const variants = new Map<string, ProductVariantFrom<TProduct>>();\n  for (const variant of selectableVariants) {\n    variants.set(selectedOptionsKey(variant.selectedOptions, product.options), variant);\n  }\n  return variants;\n}\n\nfunction addVariant<TVariant extends ProductVariantInput>(\n  variants: Map<string, TVariant>,\n  variant: TVariant,\n  productOptions: Array<{ name: string }>,\n): void {\n  variants.set(selectedOptionsKey(variant.selectedOptions, productOptions), variant);\n}\n\nfunction buildProductOptionValue<TProduct extends ProductInput>({\n  cache,\n  currentProductOptionValues,\n  encodedOptionIndexes,\n  option,\n  optionValueIndex,\n  product,\n  selectedOptionMap,\n  value,\n  variants,\n}: {\n  cache?: DecodedVariantCache;\n  currentProductOptionValues: Map<string, Set<string>>;\n  encodedOptionIndexes: Map<string, Map<string, number>>;\n  option: TProduct[\"options\"][number];\n  optionValueIndex: Map<string, Map<string, number>>;\n  product: TProduct;\n  selectedOptionMap: Record<string, string>;\n  value: ProductOptionValueFrom<TProduct>;\n  variants: Map<string, ProductVariantFrom<TProduct>>;\n}): VariantOptionValueState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>> {\n  const firstSelectableVariant = isConcreteProductVariant<TProduct>(value.firstSelectableVariant)\n    ? value.firstSelectableVariant\n    : null;\n  const selected = selectedOptionMap[option.name] === value.name;\n  const crossProduct = isCrossProductOptionValue(\n    product,\n    option.name,\n    value.name,\n    firstSelectableVariant,\n    currentProductOptionValues,\n  );\n  const targetOptionMap = buildTargetOptionMap({\n    currentProductOptionValues,\n    crossProduct,\n    firstSelectableVariant,\n    optionName: option.name,\n    selectedOptionMap,\n    valueName: value.name,\n  });\n  const targetSelectedOptions = selectedOptionsFromMap(product, targetOptionMap);\n  const key = selectedOptionsKey(targetSelectedOptions, product.options);\n  const variant = variants.get(key) ?? null;\n  const targetProductHandle = getTargetProductHandle(product, crossProduct, firstSelectableVariant);\n  const encodingConstraints = buildEncodingConstraints(\n    targetOptionMap,\n    product,\n    optionValueIndex,\n    encodedOptionIndexes.get(targetProductHandle),\n  );\n\n  return {\n    name: value.name,\n    swatch: value.swatch,\n    selected,\n    exists: resolveEncodedStatus(product.encodedVariantExistence, encodingConstraints, true, cache),\n    available: resolveEncodedStatus(\n      product.encodedVariantAvailability,\n      encodingConstraints,\n      variant?.availableForSale ?? false,\n      cache,\n    ),\n    variant,\n    selectedOptions: variant?.selectedOptions ?? targetSelectedOptions,\n    handle: getOptionValueHandle(selected, product.handle, variant, firstSelectableVariant),\n  };\n}\n\nfunction getOptionValueHandle<TVariant extends ProductVariantInput>(\n  selected: boolean,\n  productHandle: string,\n  variant: TVariant | null,\n  firstSelectableVariant: TVariant | null,\n): string {\n  if (selected) return productHandle;\n  return variant?.product?.handle ?? firstSelectableVariant?.product?.handle ?? productHandle;\n}\n\nfunction buildOptionValueIndex<TProduct extends ProductInput>(\n  product: TProduct,\n): Map<string, Map<string, number>> {\n  return new Map(\n    product.options.map((option) => [\n      option.name,\n      new Map(option.optionValues.map((value, index) => [value.name, index])),\n    ]),\n  );\n}\n\nfunction getTargetProductHandle<TVariant extends ProductVariantInput>(\n  product: ProductInput,\n  crossProduct: boolean,\n  firstSelectableVariant: TVariant | null,\n): string {\n  if (crossProduct && firstSelectableVariant?.product?.handle) {\n    return firstSelectableVariant.product.handle;\n  }\n  return product.handle;\n}\n\nfunction buildEncodedOptionIndexes<TProduct extends ProductInput>(\n  product: TProduct,\n  selectableVariants: ProductVariantFrom<TProduct>[],\n): Map<string, Map<string, number>> {\n  const indexes = new Map<string, Map<string, number>>();\n  for (const variant of selectableVariants) {\n    const productHandle = variant.product?.handle ?? product.handle;\n    addEncodedOptionIndex(indexes, productHandle, product.options, variant.selectedOptions);\n  }\n  return indexes;\n}\n\nfunction addEncodedOptionIndex(\n  indexes: Map<string, Map<string, number>>,\n  productHandle: string,\n  productOptions: Array<{ name: string }>,\n  selectedOptions: SelectedOption[],\n): void {\n  const index = indexes.get(productHandle) ?? new Map<string, number>();\n  const selectedOptionNames = new Set(selectedOptions.map((option) => option.name));\n\n  for (const option of productOptions) {\n    if (!selectedOptionNames.has(option.name) || index.has(option.name)) continue;\n    index.set(option.name, index.size);\n  }\n\n  indexes.set(productHandle, index);\n}\n\nfunction buildCurrentProductOptionValues<TProduct extends ProductInput>(\n  product: TProduct,\n  selectableVariants: ProductVariantFrom<TProduct>[],\n): Map<string, Set<string>> {\n  const optionValues = new Map<string, Set<string>>();\n  for (const variant of selectableVariants) {\n    if (!variantBelongsToProduct(product, variant)) continue;\n    for (const option of variant.selectedOptions) {\n      addCurrentProductOptionValue(optionValues, option.name, option.value);\n    }\n  }\n  return optionValues;\n}\n\nfunction addCurrentProductOptionValue(\n  optionValues: Map<string, Set<string>>,\n  optionName: string,\n  valueName: string,\n): void {\n  const values = optionValues.get(optionName) ?? new Set<string>();\n  values.add(valueName);\n  optionValues.set(optionName, values);\n}\n\nfunction isCrossProductOptionValue<TVariant extends ProductVariantInput>(\n  product: ProductInput,\n  optionName: string,\n  valueName: string,\n  firstSelectableVariant: TVariant | null,\n  currentProductOptionValues: Map<string, Set<string>>,\n): boolean {\n  if (!firstSelectableVariant || variantBelongsToProduct(product, firstSelectableVariant)) {\n    return false;\n  }\n  return !currentProductOptionValues.get(optionName)?.has(valueName);\n}\n\nfunction variantBelongsToProduct<TVariant extends ProductVariantInput>(\n  product: ProductInput,\n  variant: TVariant,\n): boolean {\n  return variant.product?.handle === undefined || variant.product.handle === product.handle;\n}\n\ntype TargetOptionMapInput<TVariant extends ProductVariantInput> = {\n  currentProductOptionValues: Map<string, Set<string>>;\n  crossProduct: boolean;\n  firstSelectableVariant: TVariant | null;\n  optionName: string;\n  selectedOptionMap: Record<string, string>;\n  valueName: string;\n};\n\nfunction buildTargetOptionMap<TVariant extends ProductVariantInput>({\n  currentProductOptionValues,\n  crossProduct,\n  firstSelectableVariant,\n  optionName,\n  selectedOptionMap,\n  valueName,\n}: TargetOptionMapInput<TVariant>): Record<string, string> {\n  if (crossProduct && firstSelectableVariant) {\n    return selectedOptionsToMap(firstSelectableVariant.selectedOptions);\n  }\n\n  const nextOptionMap = { ...selectedOptionMap, [optionName]: valueName };\n  if (currentProductOptionValues.size === 0) return nextOptionMap;\n  return filterOptionMap(nextOptionMap, currentProductOptionValues);\n}\n\nfunction filterOptionMap(\n  selectedOptionMap: Record<string, string>,\n  currentProductOptionValues: Map<string, Set<string>>,\n): Record<string, string> {\n  const filtered: Record<string, string> = Object.create(null);\n  for (const [optionName, values] of currentProductOptionValues) {\n    const value = selectedOptionMap[optionName];\n    if (value !== undefined && values.has(value)) filtered[optionName] = value;\n  }\n  return filtered;\n}\n\nfunction buildEncodingConstraints<TProduct extends ProductInput>(\n  selectedOptionMap: Record<string, string>,\n  product: TProduct,\n  optionValueIndex = buildOptionValueIndex(product),\n  encodedOptionIndex?: Map<string, number>,\n): EncodedVariantConstraint[] {\n  const constraints: EncodedVariantConstraint[] = [];\n\n  for (const [productOptionIndex, option] of product.options.entries()) {\n    const selectedValue = selectedOptionMap[option.name];\n    if (selectedValue === undefined) continue;\n    const optionIndex = encodedOptionIndex?.get(option.name) ?? productOptionIndex;\n    const valueIndex = optionValueIndex.get(option.name)?.get(selectedValue);\n    if (valueIndex === undefined) continue;\n    constraints.push({ optionIndex, valueIndex });\n  }\n\n  return constraints;\n}\n\nfunction resolveEncodedStatus(\n  encodedField: string | null | undefined,\n  constraints: EncodedVariantConstraint[],\n  fallback: boolean,\n  cache?: DecodedVariantCache,\n): boolean {\n  if (!encodedField) return fallback;\n  return isAnyEncodedVariantMatchingConstraints(constraints, encodedField, cache);\n}\n\nfunction isAnyEncodedVariantMatchingConstraints(\n  constraints: EncodedVariantConstraint[],\n  encodedVariantField: string,\n  cache?: DecodedVariantCache,\n): boolean {\n  if (constraints.length === 0) return false;\n\n  return getDecodedVariantCombinations(encodedVariantField, cache).some((combination) =>\n    combinationMatchesConstraints(combination, constraints),\n  );\n}\n\nfunction getDecodedVariantCombinations(\n  encodedVariantField: string,\n  cache?: DecodedVariantCache,\n): number[][] {\n  const cached = cache?.get(encodedVariantField);\n  if (cached) return cached;\n\n  const decoded = decodeEncodedVariant(encodedVariantField);\n  cache?.set(encodedVariantField, decoded);\n  return decoded;\n}\n\nfunction combinationMatchesConstraints(\n  combination: number[],\n  constraints: EncodedVariantConstraint[],\n): boolean {\n  return constraints.every(\n    ({ optionIndex, valueIndex }) => combination[optionIndex] === valueIndex,\n  );\n}\n\nfunction decodeEncodedVariant(encodedVariantField: string | null | undefined): number[][] {\n  if (!encodedVariantField) return [];\n  if (!encodedVariantField.startsWith(\"v1_\")) {\n    log.warn(`unsupported variant encoding: \"${encodedVariantField}\"`);\n    return [];\n  }\n  return decodeV1EncodedVariant(encodedVariantField.replace(/^v1_/, \"\"));\n}\n\nfunction decodeV1EncodedVariant(encodedVariantField: string): number[][] {\n  const tokenizer = /[ :,-]/g;\n  const state: DecodeV1State = {\n    currentOptionValue: [],\n    decodedOptions: [],\n    depth: 0,\n    index: 0,\n    rangeStart: null,\n  };\n  let token: RegExpExecArray | null;\n\n  while ((token = tokenizer.exec(encodedVariantField))) {\n    processDecodeV1Token(encodedVariantField, state, token, tokenizer);\n  }\n\n  pushFinalDecodeV1Value(encodedVariantField, state);\n\n  return state.decodedOptions;\n}\n\ntype DecodeV1State = {\n  currentOptionValue: number[];\n  decodedOptions: number[][];\n  depth: number;\n  index: number;\n  rangeStart: number | null;\n};\n\nfunction isConcreteProductVariant<TProduct extends ProductInput>(\n  variant: ProductVariantInput | null | undefined,\n): variant is ProductVariantFrom<TProduct> {\n  return variant !== null && variant !== undefined;\n}\n\nfunction processDecodeV1Token(\n  encodedVariantField: string,\n  state: DecodeV1State,\n  token: RegExpExecArray,\n  tokenizer: RegExp,\n): void {\n  const operation = token[0];\n  const optionValueIndex =\n    Number.parseInt(encodedVariantField.slice(state.index, token.index), 10) || 0;\n\n  pushDecodeV1Range(state, optionValueIndex);\n  state.currentOptionValue[state.depth] = optionValueIndex;\n\n  if (operation === \"-\") {\n    state.rangeStart = optionValueIndex;\n  } else if (operation === \":\") {\n    state.depth++;\n  } else {\n    processDecodeV1Separator(encodedVariantField, state, token, operation);\n  }\n\n  state.index = tokenizer.lastIndex;\n}\n\nfunction processDecodeV1Separator(\n  encodedVariantField: string,\n  state: DecodeV1State,\n  token: RegExpExecArray,\n  operation: string,\n): void {\n  if (shouldPushDecodeV1Option(encodedVariantField, token, operation)) {\n    state.decodedOptions.push([...state.currentOptionValue]);\n  }\n\n  if (operation !== \",\") return;\n\n  state.currentOptionValue.pop();\n  state.depth--;\n}\n\nfunction shouldPushDecodeV1Option(\n  encodedVariantField: string,\n  token: RegExpExecArray,\n  operation: string,\n): boolean {\n  return operation === \" \" || (operation === \",\" && encodedVariantField[token.index - 1] !== \",\");\n}\n\nfunction pushFinalDecodeV1Value(encodedVariantField: string, state: DecodeV1State): void {\n  const finalIndex = encodedVariantField.match(/\\d+$/g)?.[0];\n  if (finalIndex === undefined) return;\n\n  const finalValueIndex = Number.parseInt(finalIndex, 10);\n  if (state.rangeStart !== null) {\n    pushDecodeV1Range(state, finalValueIndex + INCLUSIVE_RANGE_END_OFFSET);\n    return;\n  }\n\n  state.currentOptionValue[state.depth] = finalValueIndex;\n  state.decodedOptions.push([...state.currentOptionValue]);\n}\n\nfunction pushDecodeV1Range(state: DecodeV1State, rangeEndExclusive: number): void {\n  const rangeStart = state.rangeStart;\n  if (rangeStart === null) return;\n\n  for (let value = rangeStart; value < rangeEndExclusive; value++) {\n    state.currentOptionValue[state.depth] = value;\n    state.decodedOptions.push([...state.currentOptionValue]);\n  }\n\n  state.rangeStart = null;\n}\n"],"mappings":"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"}

package/dist/core/product/product-form.d.mts

@@ -3,28 +3,42 @@ import { CartStore } from "../cart/cart.mjs";
 import { ProductInput, ProductOptionValueFrom, ProductOptionValueInput, ProductVariantFrom, ProductVariantInput, SelectedOption, VariantOptionState } from "./state.mjs";
 
 //#region src/core/product/product-form.d.ts
-/** Cart and line-item errors surfaced by a {@link ProductFormStore}. */
+/**
+ * Cart errors and warnings to show near the add-to-cart button.
+ *
+ * Each list starts with cart-level messages, followed by the messages for the cart line that holds the selected variant.
+ */
 interface ProductFormErrors {
+  /** User errors for the cart, then for the cart line that holds the selected variant. */
   userErrors: CartUserError[];
+  /** Warnings for the cart, then for the cart line that holds the selected variant. */
   warnings: CartWarning[];
+  /** Failed cart requests. Each entry has a message and, when available, an HTTP status. */
   networkErrors: CartNetworkEntry[];
 }
-/** Live state snapshot emitted by a {@link ProductFormStore}. */
+/** The product form's option state, selection, cart errors, and matching cart line. */
 interface ProductFormStoreState<TVariant extends ProductVariantInput = ProductVariantInput, TOptionValue extends ProductOptionValueInput = ProductOptionValueInput> {
+  /** Each product option and its values, with the selection, existence, and availability of each value. */
   options: VariantOptionState<TVariant, TOptionValue>[];
+  /** Option names and values in the current selection, which can be partial. */
   selectedOptions: SelectedOption[];
+  /** Variant that matches the current selection, or `null` when the selection is partial or your query didn't load that variant. */
   selectedVariant: TVariant | null;
+  /** Cart errors and warnings to show near the add-to-cart button. */
   errors: ProductFormErrors;
+  /** First cart line that holds the selected variant, or `null` when no cart line holds the variant. */
   matchedLineItem: CartLine | null;
 }
-/** The reactive options array from a {@link ProductFormStoreState}, typed to a specific product. */
+/** Option state from the product form, typed to your product query. */
 type ProductFormOptions<TProduct extends ProductInput = ProductInput> = ProductFormStoreState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>["options"];
 /**
- * Result returned by {@link ProductFormStore.selectOption}.
+ * Result of selecting an option value. Build the next product URL from the selected options in the result.
+ *
+ * - `resolved`: the selection matches a variant that your query loaded.
+ * - `unresolved`: the selection is valid, but your query didn't load a matching variant.
+ * - `invalid`: the product has no such option name or value, or no variant combines the value with the rest of the selection.
  *
- * - `resolved` — a specific variant was matched for the full selection.
- * - `unresolved` — the selection is valid but not yet complete.
- * - `invalid` — the option name or value does not exist on the product.
+ * When a complete selection returns `unresolved`, query the exact variant from the Storefront API with the returned selected options.
  */
 type VariantSelectionResult<TVariant extends ProductVariantInput = ProductVariantInput> = {
   status: "resolved";
@@ -40,53 +54,86 @@ type VariantSelectionResult<TVariant extends ProductVariantInput = ProductVarian
   selectedVariant: null;
   reason: string;
 };
-/** A selection result that is not invalid — either resolved or unresolved. */
+/** A selection result with a `resolved` or `unresolved` status. Selection callbacks receive this result. */
 type ValidProductSelectionResult<TProduct extends ProductInput = ProductInput> = Exclude<VariantSelectionResult<ProductVariantFrom<TProduct>>, {
   status: "invalid";
 }>;
-/** Options for {@link createProductFormStore}. */
+/** Options for creating a product form store. */
 type CreateProductFormStoreOptions = {
-  /** Fallback selection used when the product has no `selectedOrFirstAvailableVariant`. */selectedOptions?: SelectedOption[];
+  /** Selection to start from when the product has no selected or first available variant. */selectedOptions?: SelectedOption[];
 };
-/** Manages variant selection + cart integration for a product form. */
+/** Tracks the customer's option selection for one product and adds the selected variant to the cart. */
 interface ProductFormStore<TProduct extends ProductInput = ProductInput, TVariant extends ProductVariantInput = ProductVariantFrom<TProduct>> {
-  /** Returns the current state snapshot. */
+  /** Returns the current product form state. */
   getState(): ProductFormStoreState<TVariant, ProductOptionValueFrom<TProduct>>;
-  /** Registers a listener invoked on every state change. Returns an unsubscribe function. */
+  /** Calls the listener on every state change. Returns a function that unsubscribes the listener. */
   subscribe(listener: (state: ProductFormStoreState<TVariant, ProductOptionValueFrom<TProduct>>) => void): () => void;
-  /** Selects an option value and resolves the new variant. */
+  /**
+   * Selects an option value and returns the result.
+   *
+   * Resolved and unresolved selections update the state. An invalid selection leaves the state unchanged and returns a reason. Build the next product URL from the selected options in the result.
+   */
   selectOption(name: string, value: string): VariantSelectionResult<TVariant>;
-  /** Replaces the product data and re-derives state — use after a server-side product reload. */
+  /**
+   * Loads new product data into the store. Create the store once and call `hydrate()` each time the server reloads the product.
+   *
+   * The store keeps its subscribers. The new selection comes from the product's selected or first available variant, then from the selected options that you pass, then from the current selection.
+   */
   hydrate(product: TProduct, opts?: {
     selectedOptions?: SelectedOption[];
   }): void;
-  /** Restores the store to its initial product and selection state. */
+  /** Restores the product data and the selection that the store started with. */
   reset(): void;
-  /** Re-subscribes to the cart store and resyncs cart-derived state. Only needed to reuse the store after `destroy()` (e.g. React StrictMode effects). */
+  /** Reconnects the store to the cart after you call `destroy()`, such as in React Strict Mode effects. The store connects to the cart when you create it. */
   connect(): void;
-  /** Tears down the store — removes cart subscription and releases resources. */
+  /** Disconnects the store from the cart. Call `destroy()` when the product form unmounts. */
   destroy(): void;
-  /** Forwards a native `SubmitEvent` to the cart store's form handler (routed by the submitter's `value`, typically `add`), attaching selected variant data as event detail. */
+  /**
+   * Adds the selected variant to the cart from the product form's native submit event.
+   *
+   * The cart adds the variant when the clicked button has no value and the form includes a merchandise ID field. The cart uses the variant's title, image, and price to show the change before the server responds. The returned promise rejects when the event target isn't a form or the event has no submitter.
+   */
   handleFormSubmit(event: SubmitEvent): Promise<void>;
 }
-/** Returns the selected variant, or `null` when the selection is partial or the variant wasn't part of the query result. */
+/**
+ * Returns the variant that matches the customer's current option selection.
+ *
+ * Show the product's price range until the selection resolves to a variant. When every option has a selection and the function returns `null`, query the exact variant from the Storefront API.
+ *
+ * @param options The `options` array from the product form state.
+ * @returns The matching variant, or `null` when the selection is partial or your query didn't load that variant.
+ * @publicDocs
+ */
 declare function getSelectedVariant<TVariant extends ProductVariantInput>(options: VariantOptionState<TVariant, ProductOptionValueInput>[]): TVariant | null;
-/** Guards whether the current selection can be added to cart — a variant must be resolved and available, and the product must not require a selling plan. */
+/**
+ * Checks whether the customer can add the current selection to the cart. Use the result to enable or disable the add-to-cart button.
+ *
+ * @param product The product from your query. A product that requires a selling plan always returns `false`.
+ * @param options The `options` array from the product form state.
+ * @returns `true` when the selection resolves to a variant that's available for sale and the product doesn't require a selling plan.
+ * @publicDocs
+ */
 declare function canAddToCart<TProduct extends ProductInput>(product: TProduct, options: VariantOptionState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[]): boolean;
 /**
- * Finds the first cart line whose merchandise ID matches.
- * When selling plans are used, the same merchandise ID can appear on multiple
- * cart lines — this returns the first match. Future attribute-based matching
- * will narrow to the exact line.
+ * Finds the cart line that holds a variant. Use the line to show the quantity that's already in the cart.
+ *
+ * When several cart lines hold the variant with different selling plans or attributes, the function returns the first line.
+ *
+ * @param lines The cart lines, such as `data.lines.nodes` from the cart state.
+ * @param merchandiseId The variant ID to look for.
+ * @returns The first cart line that holds the variant, or `null` when no cart line holds the variant.
+ * @publicDocs
  */
 declare function findCartLineByMerchandiseId(lines: CartLine[], merchandiseId: string): CartLine | null;
 /**
- * Creates a reactive store that manages variant selection and cart integration for a product form.
+ * Creates a store that tracks the customer's option selection for one product and adds the selected variant to the cart.
  *
- * The store subscribes to the {@link CartStore} to keep error and line-item
- * state in sync. Call `destroy()` when the form unmounts to clean up the
- * subscription.
+ * The store resolves variants from the product data that you pass and leaves the URL to you. Build the product URL from the result of `selectOption()`. Call `destroy()` when the product form unmounts. The product provider from `createProductComponents` creates and destroys the store for you.
  *
+ * @param product The product from your Storefront API query.
+ * @param cartStore The cart store that the form adds variants to and reads cart errors from.
+ * @param options The selection to start from when the product has no selected or first available variant.
+ * @returns A product form store. The starting selection comes from the product's selected or first available variant, or else from the selection in the options.
  * @example
  * ```ts
  * const store = createProductFormStore(product, cartStore);
@@ -97,6 +144,7 @@ declare function findCartLineByMerchandiseId(lines: CartLine[], merchandiseId: s
  *
  * store.selectOption("Color", "Red");
  * ```
+ * @publicDocs
  */
 declare function createProductFormStore<TProduct extends ProductInput>(product: TProduct, cartStore: CartStore, options?: CreateProductFormStoreOptions): ProductFormStore<TProduct, ProductVariantFrom<TProduct>>;
 //#endregion

package/dist/core/product/product-form.mjs

@@ -2,32 +2,53 @@ import { createObservable } from "../observable.mjs";
 import { buildProductOptions, selectedOptionsFromMap, selectedOptionsToMap } from "./options.mjs";
 
 //#region src/core/product/product-form.ts
-/** Returns the selected variant, or `null` when the selection is partial or the variant wasn't part of the query result. */
+/**
+* Returns the variant that matches the customer's current option selection.
+*
+* Show the product's price range until the selection resolves to a variant. When every option has a selection and the function returns `null`, query the exact variant from the Storefront API.
+*
+* @param options The `options` array from the product form state.
+* @returns The matching variant, or `null` when the selection is partial or your query didn't load that variant.
+* @publicDocs
+*/
 function getSelectedVariant(options) {
 	return options[0]?.values.find((v) => v.selected)?.variant ?? null;
 }
-/** Guards whether the current selection can be added to cart — a variant must be resolved and available, and the product must not require a selling plan. */
+/**
+* Checks whether the customer can add the current selection to the cart. Use the result to enable or disable the add-to-cart button.
+*
+* @param product The product from your query. A product that requires a selling plan always returns `false`.
+* @param options The `options` array from the product form state.
+* @returns `true` when the selection resolves to a variant that's available for sale and the product doesn't require a selling plan.
+* @publicDocs
+*/
 function canAddToCart(product, options) {
 	if (product.requiresSellingPlan) return false;
 	const variant = getSelectedVariant(options);
 	return variant !== null && variant.availableForSale;
 }
 /**
-* Finds the first cart line whose merchandise ID matches.
-* When selling plans are used, the same merchandise ID can appear on multiple
-* cart lines — this returns the first match. Future attribute-based matching
-* will narrow to the exact line.
+* Finds the cart line that holds a variant. Use the line to show the quantity that's already in the cart.
+*
+* When several cart lines hold the variant with different selling plans or attributes, the function returns the first line.
+*
+* @param lines The cart lines, such as `data.lines.nodes` from the cart state.
+* @param merchandiseId The variant ID to look for.
+* @returns The first cart line that holds the variant, or `null` when no cart line holds the variant.
+* @publicDocs
 */
 function findCartLineByMerchandiseId(lines, merchandiseId) {
 	return lines.find((l) => l.merchandise?.id === merchandiseId) ?? null;
 }
 /**
-* Creates a reactive store that manages variant selection and cart integration for a product form.
+* Creates a store that tracks the customer's option selection for one product and adds the selected variant to the cart.
 *
-* The store subscribes to the {@link CartStore} to keep error and line-item
-* state in sync. Call `destroy()` when the form unmounts to clean up the
-* subscription.
+* The store resolves variants from the product data that you pass and leaves the URL to you. Build the product URL from the result of `selectOption()`. Call `destroy()` when the product form unmounts. The product provider from `createProductComponents` creates and destroys the store for you.
 *
+* @param product The product from your Storefront API query.
+* @param cartStore The cart store that the form adds variants to and reads cart errors from.
+* @param options The selection to start from when the product has no selected or first available variant.
+* @returns A product form store. The starting selection comes from the product's selected or first available variant, or else from the selection in the options.
 * @example
 * ```ts
 * const store = createProductFormStore(product, cartStore);
@@ -38,6 +59,7 @@ function findCartLineByMerchandiseId(lines, merchandiseId) {
 *
 * store.selectOption("Color", "Red");
 * ```
+* @publicDocs
 */
 function createProductFormStore(product, cartStore, options = {}) {
 	const decodedVariantCache = /* @__PURE__ */ new Map();

package/dist/core/product/product-form.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"product-form.mjs","names":[],"sources":["../../../src/core/product/product-form.ts"],"sourcesContent":["import type { CartStore } from \"../cart/cart\";\nimport type {\n  CartLine,\n  CartNetworkEntry,\n  CartState,\n  CartUserError,\n  CartWarning,\n} from \"../cart/state\";\nimport { createObservable } from \"../observable\";\nimport {\n  buildProductOptions,\n  type DecodedVariantCache,\n  selectedOptionsFromMap,\n  selectedOptionsToMap,\n} from \"./options\";\nimport type {\n  ProductInput,\n  ProductOptionValueFrom,\n  ProductOptionValueInput,\n  ProductVariantFrom,\n  ProductVariantInput,\n  SelectedOption,\n  VariantOptionState,\n} from \"./state\";\n\n// ---------------------------------------------------------------------------\n// Public types\n// ---------------------------------------------------------------------------\n\n/** Cart and line-item errors surfaced by a {@link ProductFormStore}. */\nexport interface ProductFormErrors {\n  userErrors: CartUserError[];\n  warnings: CartWarning[];\n  networkErrors: CartNetworkEntry[];\n}\n\n/** Live state snapshot emitted by a {@link ProductFormStore}. */\nexport interface ProductFormStoreState<\n  TVariant extends ProductVariantInput = ProductVariantInput,\n  TOptionValue extends ProductOptionValueInput = ProductOptionValueInput,\n> {\n  options: VariantOptionState<TVariant, TOptionValue>[];\n  selectedOptions: SelectedOption[];\n  selectedVariant: TVariant | null;\n  errors: ProductFormErrors;\n  matchedLineItem: CartLine | null;\n}\n\n/** The reactive options array from a {@link ProductFormStoreState}, typed to a specific product. */\nexport type ProductFormOptions<TProduct extends ProductInput = ProductInput> =\n  ProductFormStoreState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[\"options\"];\n\n/**\n * Result returned by {@link ProductFormStore.selectOption}.\n *\n * - `resolved` — a specific variant was matched for the full selection.\n * - `unresolved` — the selection is valid but not yet complete.\n * - `invalid` — the option name or value does not exist on the product.\n */\nexport type VariantSelectionResult<TVariant extends ProductVariantInput = ProductVariantInput> =\n  | {\n      status: \"resolved\";\n      selectedOptions: SelectedOption[];\n      selectedVariant: TVariant;\n    }\n  | {\n      status: \"unresolved\";\n      selectedOptions: SelectedOption[];\n      selectedVariant: null;\n    }\n  | {\n      status: \"invalid\";\n      selectedOptions: SelectedOption[];\n      selectedVariant: null;\n      reason: string;\n    };\n\n/** A selection result that is not invalid — either resolved or unresolved. */\nexport type ValidProductSelectionResult<TProduct extends ProductInput = ProductInput> = Exclude<\n  VariantSelectionResult<ProductVariantFrom<TProduct>>,\n  { status: \"invalid\" }\n>;\n\n/** Options for {@link createProductFormStore}. */\nexport type CreateProductFormStoreOptions = {\n  /** Fallback selection used when the product has no `selectedOrFirstAvailableVariant`. */\n  selectedOptions?: SelectedOption[];\n};\n\n/** Manages variant selection + cart integration for a product form. */\nexport interface ProductFormStore<\n  TProduct extends ProductInput = ProductInput,\n  TVariant extends ProductVariantInput = ProductVariantFrom<TProduct>,\n> {\n  /** Returns the current state snapshot. */\n  getState(): ProductFormStoreState<TVariant, ProductOptionValueFrom<TProduct>>;\n  /** Registers a listener invoked on every state change. Returns an unsubscribe function. */\n  subscribe(\n    listener: (state: ProductFormStoreState<TVariant, ProductOptionValueFrom<TProduct>>) => void,\n  ): () => void;\n  /** Selects an option value and resolves the new variant. */\n  selectOption(name: string, value: string): VariantSelectionResult<TVariant>;\n  /** Replaces the product data and re-derives state — use after a server-side product reload. */\n  hydrate(product: TProduct, opts?: { selectedOptions?: SelectedOption[] }): void;\n  /** Restores the store to its initial product and selection state. */\n  reset(): void;\n  /** Re-subscribes to the cart store and resyncs cart-derived state. Only needed to reuse the store after `destroy()` (e.g. React StrictMode effects). */\n  connect(): void;\n  /** Tears down the store — removes cart subscription and releases resources. */\n  destroy(): void;\n  /** Forwards a native `SubmitEvent` to the cart store's form handler (routed by the submitter's `value`, typically `add`), attaching selected variant data as event detail. */\n  handleFormSubmit(event: SubmitEvent): Promise<void>;\n}\n\n// ---------------------------------------------------------------------------\n// Utilities\n// ---------------------------------------------------------------------------\n\n/** Returns the selected variant, or `null` when the selection is partial or the variant wasn't part of the query result. */\nexport function getSelectedVariant<TVariant extends ProductVariantInput>(\n  options: VariantOptionState<TVariant, ProductOptionValueInput>[],\n): TVariant | null {\n  return options[0]?.values.find((v) => v.selected)?.variant ?? null;\n}\n\n/** Guards whether the current selection can be added to cart — a variant must be resolved and available, and the product must not require a selling plan. */\nexport function canAddToCart<TProduct extends ProductInput>(\n  product: TProduct,\n  options: VariantOptionState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[],\n): boolean {\n  if (product.requiresSellingPlan) return false;\n  const variant = getSelectedVariant(options);\n  return variant !== null && variant.availableForSale;\n}\n\n/**\n * Finds the first cart line whose merchandise ID matches.\n * When selling plans are used, the same merchandise ID can appear on multiple\n * cart lines — this returns the first match. Future attribute-based matching\n * will narrow to the exact line.\n */\nexport function findCartLineByMerchandiseId(\n  lines: CartLine[],\n  merchandiseId: string,\n): CartLine | null {\n  return lines.find((l) => l.merchandise?.id === merchandiseId) ?? null;\n}\n\n// ---------------------------------------------------------------------------\n// Internal context\n// ---------------------------------------------------------------------------\n\ntype ProductFormStoreContext<TProduct extends ProductInput> = {\n  observable: ReturnType<\n    typeof createObservable<\n      ProductFormStoreState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>\n    >\n  >;\n  cartStore: CartStore;\n  currentProduct: TProduct;\n  initialProduct: TProduct;\n  initialSelectedOptions: SelectedOption[];\n  decodedVariantCache: DecodedVariantCache;\n  destroyed: boolean;\n  unsubCart: () => void;\n};\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Creates a reactive store that manages variant selection and cart integration for a product form.\n *\n * The store subscribes to the {@link CartStore} to keep error and line-item\n * state in sync. Call `destroy()` when the form unmounts to clean up the\n * subscription.\n *\n * @example\n * ```ts\n * const store = createProductFormStore(product, cartStore);\n *\n * store.subscribe((state) => {\n *   console.log(\"selected variant:\", state.selectedVariant);\n * });\n *\n * store.selectOption(\"Color\", \"Red\");\n * ```\n */\nexport function createProductFormStore<TProduct extends ProductInput>(\n  product: TProduct,\n  cartStore: CartStore,\n  options: CreateProductFormStoreOptions = {},\n): ProductFormStore<TProduct, ProductVariantFrom<TProduct>> {\n  const decodedVariantCache: DecodedVariantCache = new Map();\n  const initialSelectedOptions = resolveSelectedOptions(product, options.selectedOptions);\n\n  const variantState = buildVariantState(product, initialSelectedOptions, decodedVariantCache);\n\n  const context: ProductFormStoreContext<TProduct> = {\n    observable: createObservable(deriveFullState(variantState, cartStore.getState())),\n    cartStore,\n    currentProduct: product,\n    initialProduct: product,\n    initialSelectedOptions,\n    decodedVariantCache,\n    destroyed: false,\n    unsubCart: () => {},\n  };\n\n  context.unsubCart = cartStore.subscribe(() => {\n    if (context.destroyed) return;\n    syncFromCart(context);\n  });\n\n  return {\n    getState: () => context.observable.state,\n    subscribe: (listener) => context.observable.subscribe(listener),\n    selectOption: (name, value) => selectOption(context, name, value),\n    hydrate: (nextProduct, opts) => hydrate(context, nextProduct, opts),\n    reset: () => reset(context),\n    connect: () => connect(context),\n    destroy: () => destroy(context),\n    handleFormSubmit: (event) => handleFormSubmit(context, event),\n  };\n}\n\n// ---------------------------------------------------------------------------\n// State builders\n// ---------------------------------------------------------------------------\n\ntype VariantOnlyState<TProduct extends ProductInput> = {\n  options: VariantOptionState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[];\n  selectedOptions: SelectedOption[];\n};\n\nfunction buildVariantState<TProduct extends ProductInput>(\n  product: TProduct,\n  selectedOptions: SelectedOption[],\n  cache: DecodedVariantCache,\n): VariantOnlyState<TProduct> {\n  return {\n    options: buildProductOptions(product, selectedOptions, cache),\n    selectedOptions,\n  };\n}\n\nfunction deriveFullState<TProduct extends ProductInput>(\n  variant: VariantOnlyState<TProduct>,\n  cartState: CartState,\n): ProductFormStoreState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>> {\n  const selectedVariant = getSelectedVariant(variant.options);\n  const matchedLineItem = selectedVariant\n    ? findCartLineByMerchandiseId(cartState.data.lines.nodes, selectedVariant.id)\n    : null;\n\n  const lineErrors = matchedLineItem ? cartState.errors.lines.get(matchedLineItem.id) : undefined;\n\n  return {\n    options: variant.options,\n    selectedOptions: variant.selectedOptions,\n    selectedVariant,\n    errors: {\n      userErrors: [...cartState.errors.cart.userErrors, ...(lineErrors?.userErrors ?? [])],\n      warnings: [...cartState.errors.cart.warnings, ...(lineErrors?.warnings ?? [])],\n      networkErrors: cartState.errors.network,\n    },\n    matchedLineItem,\n  };\n}\n\nfunction resolveSelectedOptions<TProduct extends ProductInput>(\n  product: TProduct,\n  requested?: SelectedOption[],\n): SelectedOption[] {\n  return product.selectedOrFirstAvailableVariant?.selectedOptions ?? requested ?? [];\n}\n\n// ---------------------------------------------------------------------------\n// Actions\n// ---------------------------------------------------------------------------\n\nfunction selectOption<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  name: string,\n  value: string,\n): VariantSelectionResult<ProductVariantFrom<TProduct>> {\n  const { options, selectedOptions } = context.observable.state;\n  const option = options.find((o) => o.name === name);\n  const optionValue = option?.values.find((v) => v.name === value);\n\n  if (!option || !optionValue) {\n    return invalid(selectedOptions, `Unknown option \"${name}\" value \"${value}\".`);\n  }\n\n  if (!optionValue.exists) {\n    return invalid(\n      selectedOptions,\n      `Option \"${name}\" value \"${value}\" does not resolve to a product variant.`,\n    );\n  }\n\n  const nextSelectedOptionMap = {\n    ...selectedOptionsToMap(selectedOptions),\n    [name]: value,\n  };\n  const nextSelectedOptions = selectedOptionsFromMap(context.currentProduct, nextSelectedOptionMap);\n\n  return applySelection(\n    context,\n    optionValue.variant\n      ? {\n          status: \"resolved\",\n          selectedOptions: optionValue.variant.selectedOptions,\n          selectedVariant: optionValue.variant as ProductVariantFrom<TProduct>,\n        }\n      : {\n          status: \"unresolved\",\n          selectedOptions: nextSelectedOptions,\n          selectedVariant: null,\n        },\n  );\n}\n\nfunction hydrate<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  product: TProduct,\n  opts: { selectedOptions?: SelectedOption[] } = {},\n): void {\n  context.currentProduct = product;\n  context.decodedVariantCache.clear();\n  const selectedOptions =\n    product.selectedOrFirstAvailableVariant?.selectedOptions ??\n    opts.selectedOptions ??\n    context.observable.state.selectedOptions;\n  const variantState = buildVariantState(product, selectedOptions, context.decodedVariantCache);\n  context.observable.setState(deriveFullState(variantState, context.cartStore.getState()));\n}\n\nfunction reset<TProduct extends ProductInput>(context: ProductFormStoreContext<TProduct>): void {\n  context.currentProduct = context.initialProduct;\n  context.decodedVariantCache.clear();\n  const variantState = buildVariantState(\n    context.initialProduct,\n    context.initialSelectedOptions,\n    context.decodedVariantCache,\n  );\n  context.observable.setState(deriveFullState(variantState, context.cartStore.getState()));\n}\n\nfunction connect<TProduct extends ProductInput>(context: ProductFormStoreContext<TProduct>): void {\n  context.unsubCart();\n  context.destroyed = false;\n  context.unsubCart = context.cartStore.subscribe(() => {\n    if (context.destroyed) return;\n    syncFromCart(context);\n  });\n  syncFromCart(context);\n}\n\nfunction destroy<TProduct extends ProductInput>(context: ProductFormStoreContext<TProduct>): void {\n  context.destroyed = true;\n  context.unsubCart();\n  context.decodedVariantCache.clear();\n}\n\nfunction buildAddToCartDetail<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n): Record<string, unknown> | undefined {\n  const { selectedVariant } = context.observable.state;\n  if (!selectedVariant) return undefined;\n\n  return {\n    products: [\n      {\n        id: selectedVariant.id,\n        title: selectedVariant.title,\n        product: selectedVariant.product\n          ? { title: selectedVariant.product.title, handle: selectedVariant.product.handle }\n          : undefined,\n        selectedOptions: selectedVariant.selectedOptions,\n        image: selectedVariant.image,\n        price: selectedVariant.price,\n      },\n    ],\n  };\n}\n\nasync function handleFormSubmit<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  event: SubmitEvent,\n): Promise<void> {\n  const eventDetail = buildAddToCartDetail(context);\n  await context.cartStore.handleFormSubmit(event, eventDetail);\n}\n\nfunction applySelection<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  result: Exclude<VariantSelectionResult<ProductVariantFrom<TProduct>>, { status: \"invalid\" }>,\n): VariantSelectionResult<ProductVariantFrom<TProduct>> {\n  const variantState = buildVariantState(\n    context.currentProduct,\n    result.selectedOptions,\n    context.decodedVariantCache,\n  );\n  context.observable.setState(deriveFullState(variantState, context.cartStore.getState()));\n  return result;\n}\n\nfunction hasCartDerivedFieldsChanged<TVariant extends ProductVariantInput>(\n  prev: ProductFormStoreState<TVariant, ProductOptionValueInput>,\n  next: ProductFormStoreState<TVariant, ProductOptionValueInput>,\n): boolean {\n  return (\n    prev.matchedLineItem !== next.matchedLineItem ||\n    prev.selectedVariant !== next.selectedVariant ||\n    prev.errors.userErrors !== next.errors.userErrors ||\n    prev.errors.warnings !== next.errors.warnings ||\n    prev.errors.networkErrors !== next.errors.networkErrors\n  );\n}\n\nfunction syncFromCart<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n): void {\n  const prev = context.observable.state;\n  const next = deriveFullState(\n    { options: prev.options, selectedOptions: prev.selectedOptions },\n    context.cartStore.getState(),\n  );\n\n  if (hasCartDerivedFieldsChanged(prev, next)) {\n    context.observable.setState(next);\n  }\n}\n\nfunction invalid<TVariant extends ProductVariantInput>(\n  selectedOptions: SelectedOption[],\n  reason: string,\n): VariantSelectionResult<TVariant> {\n  return {\n    status: \"invalid\",\n    selectedOptions,\n    selectedVariant: null,\n    reason,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"product-form.mjs","names":[],"sources":["../../../src/core/product/product-form.ts"],"sourcesContent":["import type { CartStore } from \"../cart/cart\";\nimport type {\n  CartLine,\n  CartNetworkEntry,\n  CartState,\n  CartUserError,\n  CartWarning,\n} from \"../cart/state\";\nimport { createObservable } from \"../observable\";\nimport {\n  buildProductOptions,\n  type DecodedVariantCache,\n  selectedOptionsFromMap,\n  selectedOptionsToMap,\n} from \"./options\";\nimport type {\n  ProductInput,\n  ProductOptionValueFrom,\n  ProductOptionValueInput,\n  ProductVariantFrom,\n  ProductVariantInput,\n  SelectedOption,\n  VariantOptionState,\n} from \"./state\";\n\n// ---------------------------------------------------------------------------\n// Public types\n// ---------------------------------------------------------------------------\n\n/**\n * Cart errors and warnings to show near the add-to-cart button.\n *\n * Each list starts with cart-level messages, followed by the messages for the cart line that holds the selected variant.\n */\nexport interface ProductFormErrors {\n  /** User errors for the cart, then for the cart line that holds the selected variant. */\n  userErrors: CartUserError[];\n  /** Warnings for the cart, then for the cart line that holds the selected variant. */\n  warnings: CartWarning[];\n  /** Failed cart requests. Each entry has a message and, when available, an HTTP status. */\n  networkErrors: CartNetworkEntry[];\n}\n\n/** The product form's option state, selection, cart errors, and matching cart line. */\nexport interface ProductFormStoreState<\n  TVariant extends ProductVariantInput = ProductVariantInput,\n  TOptionValue extends ProductOptionValueInput = ProductOptionValueInput,\n> {\n  /** Each product option and its values, with the selection, existence, and availability of each value. */\n  options: VariantOptionState<TVariant, TOptionValue>[];\n  /** Option names and values in the current selection, which can be partial. */\n  selectedOptions: SelectedOption[];\n  /** Variant that matches the current selection, or `null` when the selection is partial or your query didn't load that variant. */\n  selectedVariant: TVariant | null;\n  /** Cart errors and warnings to show near the add-to-cart button. */\n  errors: ProductFormErrors;\n  /** First cart line that holds the selected variant, or `null` when no cart line holds the variant. */\n  matchedLineItem: CartLine | null;\n}\n\n/** Option state from the product form, typed to your product query. */\nexport type ProductFormOptions<TProduct extends ProductInput = ProductInput> =\n  ProductFormStoreState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[\"options\"];\n\n/**\n * Result of selecting an option value. Build the next product URL from the selected options in the result.\n *\n * - `resolved`: the selection matches a variant that your query loaded.\n * - `unresolved`: the selection is valid, but your query didn't load a matching variant.\n * - `invalid`: the product has no such option name or value, or no variant combines the value with the rest of the selection.\n *\n * When a complete selection returns `unresolved`, query the exact variant from the Storefront API with the returned selected options.\n */\nexport type VariantSelectionResult<TVariant extends ProductVariantInput = ProductVariantInput> =\n  | {\n      status: \"resolved\";\n      selectedOptions: SelectedOption[];\n      selectedVariant: TVariant;\n    }\n  | {\n      status: \"unresolved\";\n      selectedOptions: SelectedOption[];\n      selectedVariant: null;\n    }\n  | {\n      status: \"invalid\";\n      selectedOptions: SelectedOption[];\n      selectedVariant: null;\n      reason: string;\n    };\n\n/** A selection result with a `resolved` or `unresolved` status. Selection callbacks receive this result. */\nexport type ValidProductSelectionResult<TProduct extends ProductInput = ProductInput> = Exclude<\n  VariantSelectionResult<ProductVariantFrom<TProduct>>,\n  { status: \"invalid\" }\n>;\n\n/** Options for creating a product form store. */\nexport type CreateProductFormStoreOptions = {\n  /** Selection to start from when the product has no selected or first available variant. */\n  selectedOptions?: SelectedOption[];\n};\n\n/** Tracks the customer's option selection for one product and adds the selected variant to the cart. */\nexport interface ProductFormStore<\n  TProduct extends ProductInput = ProductInput,\n  TVariant extends ProductVariantInput = ProductVariantFrom<TProduct>,\n> {\n  /** Returns the current product form state. */\n  getState(): ProductFormStoreState<TVariant, ProductOptionValueFrom<TProduct>>;\n  /** Calls the listener on every state change. Returns a function that unsubscribes the listener. */\n  subscribe(\n    listener: (state: ProductFormStoreState<TVariant, ProductOptionValueFrom<TProduct>>) => void,\n  ): () => void;\n  /**\n   * Selects an option value and returns the result.\n   *\n   * Resolved and unresolved selections update the state. An invalid selection leaves the state unchanged and returns a reason. Build the next product URL from the selected options in the result.\n   */\n  selectOption(name: string, value: string): VariantSelectionResult<TVariant>;\n  /**\n   * Loads new product data into the store. Create the store once and call `hydrate()` each time the server reloads the product.\n   *\n   * The store keeps its subscribers. The new selection comes from the product's selected or first available variant, then from the selected options that you pass, then from the current selection.\n   */\n  hydrate(product: TProduct, opts?: { selectedOptions?: SelectedOption[] }): void;\n  /** Restores the product data and the selection that the store started with. */\n  reset(): void;\n  /** Reconnects the store to the cart after you call `destroy()`, such as in React Strict Mode effects. The store connects to the cart when you create it. */\n  connect(): void;\n  /** Disconnects the store from the cart. Call `destroy()` when the product form unmounts. */\n  destroy(): void;\n  /**\n   * Adds the selected variant to the cart from the product form's native submit event.\n   *\n   * The cart adds the variant when the clicked button has no value and the form includes a merchandise ID field. The cart uses the variant's title, image, and price to show the change before the server responds. The returned promise rejects when the event target isn't a form or the event has no submitter.\n   */\n  handleFormSubmit(event: SubmitEvent): Promise<void>;\n}\n\n// ---------------------------------------------------------------------------\n// Utilities\n// ---------------------------------------------------------------------------\n\n/**\n * Returns the variant that matches the customer's current option selection.\n *\n * Show the product's price range until the selection resolves to a variant. When every option has a selection and the function returns `null`, query the exact variant from the Storefront API.\n *\n * @param options The `options` array from the product form state.\n * @returns The matching variant, or `null` when the selection is partial or your query didn't load that variant.\n * @publicDocs\n */\nexport function getSelectedVariant<TVariant extends ProductVariantInput>(\n  options: VariantOptionState<TVariant, ProductOptionValueInput>[],\n): TVariant | null {\n  return options[0]?.values.find((v) => v.selected)?.variant ?? null;\n}\n\n/**\n * Checks whether the customer can add the current selection to the cart. Use the result to enable or disable the add-to-cart button.\n *\n * @param product The product from your query. A product that requires a selling plan always returns `false`.\n * @param options The `options` array from the product form state.\n * @returns `true` when the selection resolves to a variant that's available for sale and the product doesn't require a selling plan.\n * @publicDocs\n */\nexport function canAddToCart<TProduct extends ProductInput>(\n  product: TProduct,\n  options: VariantOptionState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[],\n): boolean {\n  if (product.requiresSellingPlan) return false;\n  const variant = getSelectedVariant(options);\n  return variant !== null && variant.availableForSale;\n}\n\n/**\n * Finds the cart line that holds a variant. Use the line to show the quantity that's already in the cart.\n *\n * When several cart lines hold the variant with different selling plans or attributes, the function returns the first line.\n *\n * @param lines The cart lines, such as `data.lines.nodes` from the cart state.\n * @param merchandiseId The variant ID to look for.\n * @returns The first cart line that holds the variant, or `null` when no cart line holds the variant.\n * @publicDocs\n */\nexport function findCartLineByMerchandiseId(\n  lines: CartLine[],\n  merchandiseId: string,\n): CartLine | null {\n  return lines.find((l) => l.merchandise?.id === merchandiseId) ?? null;\n}\n\n// ---------------------------------------------------------------------------\n// Internal context\n// ---------------------------------------------------------------------------\n\ntype ProductFormStoreContext<TProduct extends ProductInput> = {\n  observable: ReturnType<\n    typeof createObservable<\n      ProductFormStoreState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>\n    >\n  >;\n  cartStore: CartStore;\n  currentProduct: TProduct;\n  initialProduct: TProduct;\n  initialSelectedOptions: SelectedOption[];\n  decodedVariantCache: DecodedVariantCache;\n  destroyed: boolean;\n  unsubCart: () => void;\n};\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Creates a store that tracks the customer's option selection for one product and adds the selected variant to the cart.\n *\n * The store resolves variants from the product data that you pass and leaves the URL to you. Build the product URL from the result of `selectOption()`. Call `destroy()` when the product form unmounts. The product provider from `createProductComponents` creates and destroys the store for you.\n *\n * @param product The product from your Storefront API query.\n * @param cartStore The cart store that the form adds variants to and reads cart errors from.\n * @param options The selection to start from when the product has no selected or first available variant.\n * @returns A product form store. The starting selection comes from the product's selected or first available variant, or else from the selection in the options.\n * @example\n * ```ts\n * const store = createProductFormStore(product, cartStore);\n *\n * store.subscribe((state) => {\n *   console.log(\"selected variant:\", state.selectedVariant);\n * });\n *\n * store.selectOption(\"Color\", \"Red\");\n * ```\n * @publicDocs\n */\nexport function createProductFormStore<TProduct extends ProductInput>(\n  product: TProduct,\n  cartStore: CartStore,\n  options: CreateProductFormStoreOptions = {},\n): ProductFormStore<TProduct, ProductVariantFrom<TProduct>> {\n  const decodedVariantCache: DecodedVariantCache = new Map();\n  const initialSelectedOptions = resolveSelectedOptions(product, options.selectedOptions);\n\n  const variantState = buildVariantState(product, initialSelectedOptions, decodedVariantCache);\n\n  const context: ProductFormStoreContext<TProduct> = {\n    observable: createObservable(deriveFullState(variantState, cartStore.getState())),\n    cartStore,\n    currentProduct: product,\n    initialProduct: product,\n    initialSelectedOptions,\n    decodedVariantCache,\n    destroyed: false,\n    unsubCart: () => {},\n  };\n\n  context.unsubCart = cartStore.subscribe(() => {\n    if (context.destroyed) return;\n    syncFromCart(context);\n  });\n\n  return {\n    getState: () => context.observable.state,\n    subscribe: (listener) => context.observable.subscribe(listener),\n    selectOption: (name, value) => selectOption(context, name, value),\n    hydrate: (nextProduct, opts) => hydrate(context, nextProduct, opts),\n    reset: () => reset(context),\n    connect: () => connect(context),\n    destroy: () => destroy(context),\n    handleFormSubmit: (event) => handleFormSubmit(context, event),\n  };\n}\n\n// ---------------------------------------------------------------------------\n// State builders\n// ---------------------------------------------------------------------------\n\ntype VariantOnlyState<TProduct extends ProductInput> = {\n  options: VariantOptionState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>>[];\n  selectedOptions: SelectedOption[];\n};\n\nfunction buildVariantState<TProduct extends ProductInput>(\n  product: TProduct,\n  selectedOptions: SelectedOption[],\n  cache: DecodedVariantCache,\n): VariantOnlyState<TProduct> {\n  return {\n    options: buildProductOptions(product, selectedOptions, cache),\n    selectedOptions,\n  };\n}\n\nfunction deriveFullState<TProduct extends ProductInput>(\n  variant: VariantOnlyState<TProduct>,\n  cartState: CartState,\n): ProductFormStoreState<ProductVariantFrom<TProduct>, ProductOptionValueFrom<TProduct>> {\n  const selectedVariant = getSelectedVariant(variant.options);\n  const matchedLineItem = selectedVariant\n    ? findCartLineByMerchandiseId(cartState.data.lines.nodes, selectedVariant.id)\n    : null;\n\n  const lineErrors = matchedLineItem ? cartState.errors.lines.get(matchedLineItem.id) : undefined;\n\n  return {\n    options: variant.options,\n    selectedOptions: variant.selectedOptions,\n    selectedVariant,\n    errors: {\n      userErrors: [...cartState.errors.cart.userErrors, ...(lineErrors?.userErrors ?? [])],\n      warnings: [...cartState.errors.cart.warnings, ...(lineErrors?.warnings ?? [])],\n      networkErrors: cartState.errors.network,\n    },\n    matchedLineItem,\n  };\n}\n\nfunction resolveSelectedOptions<TProduct extends ProductInput>(\n  product: TProduct,\n  requested?: SelectedOption[],\n): SelectedOption[] {\n  return product.selectedOrFirstAvailableVariant?.selectedOptions ?? requested ?? [];\n}\n\n// ---------------------------------------------------------------------------\n// Actions\n// ---------------------------------------------------------------------------\n\nfunction selectOption<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  name: string,\n  value: string,\n): VariantSelectionResult<ProductVariantFrom<TProduct>> {\n  const { options, selectedOptions } = context.observable.state;\n  const option = options.find((o) => o.name === name);\n  const optionValue = option?.values.find((v) => v.name === value);\n\n  if (!option || !optionValue) {\n    return invalid(selectedOptions, `Unknown option \"${name}\" value \"${value}\".`);\n  }\n\n  if (!optionValue.exists) {\n    return invalid(\n      selectedOptions,\n      `Option \"${name}\" value \"${value}\" does not resolve to a product variant.`,\n    );\n  }\n\n  const nextSelectedOptionMap = {\n    ...selectedOptionsToMap(selectedOptions),\n    [name]: value,\n  };\n  const nextSelectedOptions = selectedOptionsFromMap(context.currentProduct, nextSelectedOptionMap);\n\n  return applySelection(\n    context,\n    optionValue.variant\n      ? {\n          status: \"resolved\",\n          selectedOptions: optionValue.variant.selectedOptions,\n          selectedVariant: optionValue.variant as ProductVariantFrom<TProduct>,\n        }\n      : {\n          status: \"unresolved\",\n          selectedOptions: nextSelectedOptions,\n          selectedVariant: null,\n        },\n  );\n}\n\nfunction hydrate<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  product: TProduct,\n  opts: { selectedOptions?: SelectedOption[] } = {},\n): void {\n  context.currentProduct = product;\n  context.decodedVariantCache.clear();\n  const selectedOptions =\n    product.selectedOrFirstAvailableVariant?.selectedOptions ??\n    opts.selectedOptions ??\n    context.observable.state.selectedOptions;\n  const variantState = buildVariantState(product, selectedOptions, context.decodedVariantCache);\n  context.observable.setState(deriveFullState(variantState, context.cartStore.getState()));\n}\n\nfunction reset<TProduct extends ProductInput>(context: ProductFormStoreContext<TProduct>): void {\n  context.currentProduct = context.initialProduct;\n  context.decodedVariantCache.clear();\n  const variantState = buildVariantState(\n    context.initialProduct,\n    context.initialSelectedOptions,\n    context.decodedVariantCache,\n  );\n  context.observable.setState(deriveFullState(variantState, context.cartStore.getState()));\n}\n\nfunction connect<TProduct extends ProductInput>(context: ProductFormStoreContext<TProduct>): void {\n  context.unsubCart();\n  context.destroyed = false;\n  context.unsubCart = context.cartStore.subscribe(() => {\n    if (context.destroyed) return;\n    syncFromCart(context);\n  });\n  syncFromCart(context);\n}\n\nfunction destroy<TProduct extends ProductInput>(context: ProductFormStoreContext<TProduct>): void {\n  context.destroyed = true;\n  context.unsubCart();\n  context.decodedVariantCache.clear();\n}\n\nfunction buildAddToCartDetail<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n): Record<string, unknown> | undefined {\n  const { selectedVariant } = context.observable.state;\n  if (!selectedVariant) return undefined;\n\n  return {\n    products: [\n      {\n        id: selectedVariant.id,\n        title: selectedVariant.title,\n        product: selectedVariant.product\n          ? { title: selectedVariant.product.title, handle: selectedVariant.product.handle }\n          : undefined,\n        selectedOptions: selectedVariant.selectedOptions,\n        image: selectedVariant.image,\n        price: selectedVariant.price,\n      },\n    ],\n  };\n}\n\nasync function handleFormSubmit<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  event: SubmitEvent,\n): Promise<void> {\n  const eventDetail = buildAddToCartDetail(context);\n  await context.cartStore.handleFormSubmit(event, eventDetail);\n}\n\nfunction applySelection<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n  result: Exclude<VariantSelectionResult<ProductVariantFrom<TProduct>>, { status: \"invalid\" }>,\n): VariantSelectionResult<ProductVariantFrom<TProduct>> {\n  const variantState = buildVariantState(\n    context.currentProduct,\n    result.selectedOptions,\n    context.decodedVariantCache,\n  );\n  context.observable.setState(deriveFullState(variantState, context.cartStore.getState()));\n  return result;\n}\n\nfunction hasCartDerivedFieldsChanged<TVariant extends ProductVariantInput>(\n  prev: ProductFormStoreState<TVariant, ProductOptionValueInput>,\n  next: ProductFormStoreState<TVariant, ProductOptionValueInput>,\n): boolean {\n  return (\n    prev.matchedLineItem !== next.matchedLineItem ||\n    prev.selectedVariant !== next.selectedVariant ||\n    prev.errors.userErrors !== next.errors.userErrors ||\n    prev.errors.warnings !== next.errors.warnings ||\n    prev.errors.networkErrors !== next.errors.networkErrors\n  );\n}\n\nfunction syncFromCart<TProduct extends ProductInput>(\n  context: ProductFormStoreContext<TProduct>,\n): void {\n  const prev = context.observable.state;\n  const next = deriveFullState(\n    { options: prev.options, selectedOptions: prev.selectedOptions },\n    context.cartStore.getState(),\n  );\n\n  if (hasCartDerivedFieldsChanged(prev, next)) {\n    context.observable.setState(next);\n  }\n}\n\nfunction invalid<TVariant extends ProductVariantInput>(\n  selectedOptions: SelectedOption[],\n  reason: string,\n): VariantSelectionResult<TVariant> {\n  return {\n    status: \"invalid\",\n    selectedOptions,\n    selectedVariant: null,\n    reason,\n  };\n}\n\n/**\n * Creates a store that tracks the customer's option selection for one product and adds the selected variant to the cart.\n *\n * The store resolves variants from the product data that you pass and leaves the URL to you. Build the product URL from the result of `selectOption()`. Call `destroy()` when the product form unmounts. The product provider from `createProductComponents` creates and destroys the store for you.\n *\n * @example\n * ```ts\n * const store = createProductFormStore(product, cartStore);\n *\n * store.subscribe((state) => {\n *   console.log(\"selected variant:\", state.selectedVariant);\n * });\n *\n * store.selectOption(\"Color\", \"Red\");\n * ```\n * @publicDocs\n */\nexport type CreateProductFormStoreForDocs =\n  /**\n   * @param product - The product from your Storefront API query.\n   * @param cartStore - The cart store that the form adds variants to and reads cart errors from.\n   * @param options - The selection to start from when the product has no selected or first available variant.\n   * @returns A product form store. The starting selection comes from the product's selected or first available variant, or else from the selection in the options.\n   */\n  (\n    product: ProductInput,\n    cartStore: CartStore,\n    options?: CreateProductFormStoreOptions,\n  ) => ProductFormStore;\n"],"mappings":"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"}