@hanzo/commerce 6.2.3 → 6.3.0

package/service/impls/standalone/standalone-service.ts

@@ -49,6 +49,7 @@ class StandaloneService
   private _promo: Promo | null = null
 
   private _options : StandaloneServiceOptions
+  private _currentFamily: Family | undefined = undefined
   private _currentItem: ActualLineItem | undefined = undefined
 
   constructor(
@@ -78,10 +79,12 @@ class StandaloneService
       StandaloneService, 
         '_selectedPaths' | 
         '_currentItem' |
+        '_currentFamily' |
         '_promo'
     >(this, {
       _selectedPaths : observable.deep,
       _currentItem: observable.shallow,
+      _currentFamily: observable.shallow,
       _promo: observable,
     })
 
@@ -95,8 +98,11 @@ class StandaloneService
       selectedFamilies: computed, 
       hasSelection: computed, 
       setCurrentItem: action,
+      setCurrentFamily: action,
       currentItem: computed,
+      currentFamily: computed,
       item: computed,
+      family: computed,
       selectedPaths: computed,
       appliedPromo: computed,
       setAppliedPromo: action,
@@ -154,7 +160,7 @@ class StandaloneService
     let error: string | undefined = undefined
 
     try {
-      if (node.subNodes && atEnd && node.terminal) {
+      if (node.subNodes && atEnd && node.outermost) {
         role = 'multi-family'
         families = node.subNodes.map((sub) => {
           const familyId = skuPath + sep.tok + sub.skuToken
@@ -167,7 +173,7 @@ class StandaloneService
       }
       else if (!node.subNodes && (atEnd || possibleSKU)) {
         const _skuPath = (possibleSKU) ? getParentPath(skuPath) : skuPath
-        if (parent?.terminal) {
+        if (parent?.outermost) {
           role = 'family-in-multi-family'  
           const fam = this._familyMap.get(_skuPath)
           if (!fam) {
@@ -364,12 +370,13 @@ class StandaloneService
         }
       }
       return undefined
-    })();
+    })(); // necessary semi
 
+    this.setCurrentFamily(this._currentItem ? this._currentItem.familyId : undefined)
     return !!this._currentItem
   }
 
-  /* ObsLineItemRef */
+  /* for ObsLineItemRef */
   get item(): LineItem | undefined {
     return this._currentItem
   }
@@ -378,6 +385,36 @@ class StandaloneService
     return this._currentItem
   }
 
+  setCurrentFamily(id: string | undefined): boolean {
+
+    if (id === undefined || id.length === 0) {
+      this._currentFamily = undefined
+      return true
+    }
+
+    const fam = this._familyMap.get(id)
+    this._currentFamily = fam // undef ok
+
+    if (
+      this._currentFamily && 
+      this._currentItem && 
+      this._currentItem.familyId !== this._currentFamily.id
+    ) {
+      this._currentItem = undefined
+    }
+
+    return !!this._currentFamily
+  }
+
+  get currentFamily(): Family | undefined {
+    return this._currentFamily
+  }
+
+    /* for ObsFamilyRef */
+  get family(): Family | undefined {
+    return this._currentFamily
+  }
+
   selectPaths(sel: SelectedPaths): Family[] {
     runInAction (() => {
       this._selectedPaths = this._processAndValidate(sel) 

package/types/category-node.ts

@@ -4,19 +4,31 @@ interface CategoryNode {
   skuToken: string             // a token in the sku
   label: string;
     /** 
-     * If this node has subnodes, marks it as a "last user-visible" / "outermost" Category. 
-     * Normally, a node without subnodes (one that has products and is a family), is by definition terminal. 
-     * If it *has* subnodes, but its subNodes are to be treated as sibling families
-     * of a Category, rather rather sub Categories, this is specified by setting terminal=true.
+     * Explicitly marks this node as a "last user-visible" / "outermost" Category. 
+     * Normally, a node is "outermost" when it has no subnodes 
+     * (and thus is a family with products -- "single-family")
+     * But if it *has* subnodes, and its subNodes are actually sibling families
+     * of a Category, it must be marked as "outermost" ("multi-family")
      * */
-  terminal?: boolean;
+  outermost?: boolean;
   img? : string | ReactNode  // icon is required 
   imgAR? : number           // helps with svgs
 
-  /** Short desc of what subNodes refer to.
-   * For example, if this node's label is 'Lux Credit', 
-   * it's subNodesLabel would be 'Level',
-   * refering to membership 'levels' ('black', 'elite', etc)
+  /** 
+   * One word prompt that describes the 'meaning' of 
+   * the subnodes. 
+   * For example, if a node is 'Lux Credit', 
+   * it's subNodesLabel might be 'Level', so some UI's
+   * might be configured to render 'Level: Black'
+   * 
+   * or something like...
+   * 
+   * <Tabs title={parentNode.label + ': ' + parentNode.subNodesLabel} values={families.map((f) => (f.shortName))} />
+   * 
+   * ...which renders
+   *        
+   * Lux Credit Levels:
+   * Black   Elite   Founder   Sovereign 
   */
   subNodesLabel?: string   
   subNodes?: CategoryNode[]

package/types/commerce-service.ts

@@ -1,10 +1,10 @@
 import type { LineItem, ObsLineItemRef } from './line-item'
 import type { CategoryNode, SelectedPaths, CategoryNodeRole } from './category-node'
-import type Family from './family'
+import type { Family, ObsFamilyRef} from './family'
 import type Promo from './promo'
 
 
-interface CommerceService extends ObsLineItemRef {
+interface CommerceService extends ObsLineItemRef, ObsFamilyRef {
 
     /** Items in cart */
   get cartItems(): LineItem[]
@@ -97,23 +97,22 @@ interface CommerceService extends ObsLineItemRef {
 
       /**
      * For convenience, so widgets can share state.
-     * "current" is unrelated to what is "selected",
-     * ie, facets' values 
-     *  */ 
-  setCurrentItem(sku: string | undefined): boolean // valid sku and was set.
-    /**
-     * For convenience, so widgets can share state.
-     * "current" is unrelated to what is "selected",
-     * ie, facets' values 
+     * "current" is unrelated to what branches and items are 
+     * "selected" (with CategoryNode's and paths)
      * 
-     * note: for ObsLineItemRef, there is also
+     *  SEE ALSO: from ObsLineItemRef and ObsFamilyRef, there are also
      *  get item(): LineItem | undefined
-     * which simply delegates to this function
+     *  get family(): Family | undefined
+     * 
+     *  These simply delegate to these functions
      *  */ 
+  setCurrentItem(sku: string | undefined): boolean // valid sku and was set.
   get currentItem(): LineItem | undefined
+  setCurrentFamily(id: string | undefined): boolean // valid id and was set.
+  get currentFamily(): Family | undefined
 
+    // utility
   getFamily(id: string): Family | undefined
-
 }
 
 

package/types/family.ts

@@ -15,6 +15,12 @@ interface Family {
   products: Product[] 
 }
 
+
+interface ObsFamilyRef {
+  get family(): Family | undefined
+}
+
 export {
-  type Family as default
+  type Family, 
+  type ObsFamilyRef
 }

package/types/index.ts

@@ -1,13 +1,14 @@
 
-export type { default as Family } from './family'
 export type { default as CommerceService } from './commerce-service'
+export type { default as MultiFamilySelectorProps } from './multi-family-selector-props'
 export type { default as Product } from './product'
 export type { default as Promo } from './promo'
 export type { default as TokenSeparators } from './token-separators'
 
+export * from './category-node'
 export * from './checkout'
+export * from './family'
 export * from './item-selector'
 export * from './line-item'
-export * from './category-node'
-export * from './string-mutator'
 export * from './selection-ui-specifier'
+export * from './string-mutator'

package/types/item-selector.ts

@@ -6,27 +6,62 @@ interface ItemSelector {
   selectSku: (sku: string) => void 
 }
 
+  /** default: 'text' */
+type ItemButton = 'text' | 'image-and-text' | 'image' 
+
+  // NOTE: if a field is added here, it should also
+  // be added to util/item-selector-options-accessor.ts
 type ItemSelectorOptions = {
+
+    /** 
+     * default: short
+     * 'short': product.shortTitle if defined
+     * 'long': always us product.title, even if .shortTitle is defined
+     * 'none': do not show title AND BYLINE
+     * 
+     * (NOTE: *not* the same as buttonType = 'none')
+     */
+  familyTitle?: 'none' | 'long' | 'short'
+
+    /** only if title shown 
+     * default: false */
+  showFamilyByline?: boolean
+
     /** 
      * Whether the item label includes the Family name.
      * eg, 'Minted Bar, 1oz' vs '1oz'
      * default: false.
      */
-  showFamily?: boolean
+  showFamilyInOption?: boolean
+    /** default: true if it exists */
+  showByline?: boolean
+
+    /** default: true */
+  showPrice?: boolean
+
     /**
      * Show the current item quantity along with title and price.
      * default: false
      */
   showQuantity?: boolean   
 
-    /** default: true */
-  showPrice?: boolean
-
-    /** default: false */
-  imageButtons?: boolean  
+  buttonType?: ItemButton  
 
-    /** default: false */
+    /** (button selector only) default: false */
   horizButtons?: boolean  
+
+    /** (carousel selector only) 
+     * affects sort.  See below.
+     * default: false */
+  showSlider?: boolean
+
+    /** 
+     * Sort by cost. 
+     * If it's a carousel selector and 'showSlider' is true, 
+     * defaults to 'asc', unless another value is explicitly specified.
+     * Otherwise, defaults to 'none' 
+     * */
+  sort?: 'none' | 'asc' | 'desc' 
 }
 
 interface _ItemSelectorCompProps {
@@ -37,8 +72,10 @@ interface _ItemSelectorCompProps {
      * eg, Carousel options.
      */
   ext?: any
-    /** List selectors will scroll.  Used internally */
-  scrollable: boolean
+    /** List selectors will scroll.  
+     * Used internally
+     * default: false */
+  scrollable? : boolean
   options?: ItemSelectorOptions
 
   mobile?: boolean 

package/types/multi-family-selector-props.ts

@@ -0,0 +1,20 @@
+import type { Dimensions } from '@hanzo/ui/types'
+
+import type { Family } from './family'
+import type { ItemSelectorOptions } from './item-selector'
+import type { MultiFamilySelectorOptions } from './selection-ui-specifier'
+import type { CategoryNode } from './category-node'
+import type { LineItem } from './line-item'
+
+interface MultiFamilySelectorProps {
+  families: Family[]
+  parent: CategoryNode
+  clx?: string
+  itemClx?: string
+  itemOptions?: ItemSelectorOptions
+  selectorOptions?: MultiFamilySelectorOptions 
+  mediaConstraint?: Dimensions
+  mobile?: boolean
+}
+
+export { type MultiFamilySelectorProps as default }

package/types/selection-ui-specifier.ts

@@ -1,36 +1,52 @@
 import type { ItemSelectorOptions } from './item-selector'
-type SelectorType = 'buttons' | 'carousel' 
 
-interface FamilyCarouselSlideOptions extends ItemSelectorOptions {
-    /** 
-     * default: short
-     * 'short': product.shortTitle if defined
-     * 'long': always us product.title, even if .shortTitle is defined
-     * 'none': do not show title AND BYLINE
-     */
-  title?: 'none' | 'long' | 'short'
-    /** default: true */ 
-  showByline?: boolean
+type SingleFamilySelector = 'buttons' | 'carousel' 
+type MultiFamilySelector = 'family-carousel' | 'all-variants-carousel'
+
+type MultiFamilySelectorOptions = {
+      /** 
+       * Show title of parent node of families.
+       * eg,
+       *   Lux Credit
+       *   Black Card
+       * 
+       * vs just Black Card
+       * 
+       * ( parent CategoryNode.label)
+       * 
+       * (goes to one line if only one family)
+       * default: true 
+       * */ 
+    showParentTitle?: boolean   
+
+      /** parent CategoryNode.subNodesLabel 
+       * 
+       * default: 'none'
+      */
+    parentByline?: 'none' | 'own-line' | 'comma-sep' | 'colon-sep'  
+
+      /** show horiz image buttons of
+       * all sibling items below item info
+       * default: true*/
+    showItemSwatches?: boolean
 }
 
 interface SelectionUISpecifier {
   multiFamily?: {
-    familySelector: 'carousel'
-      /** default: true */ 
-    showParentTitle: boolean 
-    slide: {
-      type: 'buttons'
-      options?: FamilyCarouselSlideOptions
-    }
+    type: MultiFamilySelector
+    selectorOptions?: MultiFamilySelectorOptions
+    itemOptions?: ItemSelectorOptions
   }
   singleFamily?: {
-    type: SelectorType
+    type: SingleFamilySelector
     options?: ItemSelectorOptions
   } 
 }
 
 export {
   type SelectionUISpecifier,
-  type FamilyCarouselSlideOptions,
-  type SelectorType
+  type ItemSelectorOptions,
+  type SingleFamilySelector,
+  type MultiFamilySelector,
+  type MultiFamilySelectorOptions
 }

package/util/index.ts

@@ -66,3 +66,6 @@ export { default as ProductMediaAccessor } from './product-media-accessor'
 export * from './selection-ui-specifiers'
 
 export { getErrorMessage } from './error'
+
+export { default as accessItemOptions } from './item-selector-options-accessor'
+export { default as accessMultiSelectorOptions } from './multi-family-selector-options-accessor'

package/util/item-selector-options-accessor.ts

@@ -0,0 +1,32 @@
+import type { ItemSelectorOptions } from '../types'
+
+export default (options: ItemSelectorOptions | undefined = {}): Required<ItemSelectorOptions> => {
+
+  const familyTitle = 'familyTitle' in options ? options.familyTitle! : 'short'
+  const showFamilyByline = 'showFamilyByline' in options ? options.showFamilyByline! : false
+
+  const showFamilyInOption = 'showFamilyInOption' in options ? options.showFamilyInOption! : false
+  const showByline = 'showByline' in options ? options.showByline! : true
+
+  const showPrice = 'showPrice' in options ? options.showPrice! : true
+  const showQuantity = 'showQuantity' in options ? options.showQuantity! : false
+
+  const buttonType = 'buttonType' in options ? options.buttonType! : 'text'
+  const horizButtons = 'horizButtons' in options ? options.horizButtons! : false
+  const showSlider = 'showSlider' in options ? options.showSlider! : true
+
+  const sort = 'sort' in options ? options.sort! : 'none'
+
+  return {
+    showFamilyInOption,
+    familyTitle,
+    showFamilyByline,
+    showByline,
+    showPrice,
+    showQuantity,
+    buttonType,
+    horizButtons,
+    showSlider,
+    sort,
+  }
+}

package/util/multi-family-selector-options-accessor.ts

@@ -0,0 +1,15 @@
+import type { MultiFamilySelectorOptions } from '../types'
+
+export default (options: MultiFamilySelectorOptions | undefined = {}): Required<MultiFamilySelectorOptions> => {
+
+  const showParentTitle = 'showParentTitle' in options ? options.showParentTitle! : true
+  const showItemSwatches = 'showItemSwatches' in options ? options.showItemSwatches! : true
+
+  const parentByline = 'parentByline' in options ? options.parentByline! : 'none'
+
+  return {
+    showParentTitle,
+    showItemSwatches,
+    parentByline,
+  }
+}

package/util/selection-ui-specifiers.ts

@@ -3,11 +3,7 @@ import sep from '../service/sep'
 
 const DEFAULT = {
   multiFamily: {
-    familySelector: 'carousel',
-    showParentTitle: false, 
-    slide: { 
-      type: 'buttons' 
-    }
+    type: 'all-variants-carousel'
   },
   singleFamily: { type: 'carousel' }
 } satisfies SelectionUISpecifier

package/components/item-selector/carousel.tsx

@@ -1,162 +0,0 @@
-'use client'
-import React, { useCallback, useEffect, useRef } from 'react'
-import { reaction } from 'mobx'
-import { observer } from 'mobx-react-lite'
-
-import { cn } from '@hanzo/ui/util'
-import type { Dimensions } from '@hanzo/ui/types'
-
-import {
-  type CarouselOptions,
-  type CarouselApi,
-  Carousel,
-  CarouselContent,
-  CarouselItem,
-  CarouselPrevious,
-  CarouselNext,
-  ApplyTypography,
-  MediaStack
-} from '@hanzo/ui/primitives'
-
-import type { ItemSelectorProps, LineItem } from '../../types'
-import { formatCurrencyValue } from '../../util'
-
-import QuantityIndicator from '../quantity-indicator'
-
-const DEFAULT_CONSTRAINT = {w: 250, h: 250}
-
-interface CarouselItemSelectorPropsExt {
-  constrainTo: Dimensions
-  options?: CarouselOptions 
-    /** Do not show Family and / or Item title and Price */
-  imageOnly?: boolean
-}
-
-const ItemSlide: React.FC<{
-  item: LineItem,
-  constrainTo: Dimensions
-  imageOnly: boolean
-  showFamily: boolean
-  showPrice: boolean
-  showQuantity: boolean
-  clx?: string
-}> = ({
-  item,
-  constrainTo,
-  showFamily,
-  imageOnly,
-  showPrice,
-  showQuantity,
-  clx=''
-}) => {
-
-  return (
-    <CarouselItem className={cn('p-2 flex flex-col justify-center items-center', clx)}>
-      {!imageOnly && (
-        <ApplyTypography className='flex flex-col items-center !gap-2 [&>*]:!m-0'>
-          {showFamily && (<h4>{item.familyTitle}</h4>)}
-          <h6>{item.optionLabel}</h6>
-          {item.byline && (<p>{item.byline}</p>)}
-        </ApplyTypography>
-      )}
-      <MediaStack media={item} constrainTo={constrainTo} clx='my-4' />
-      {!imageOnly && (showPrice || showQuantity) && (
-        <ApplyTypography className='flex flex-row items-center !gap-2 [&>*]:!m-0'>
-          {showPrice && (<p>{formatCurrencyValue(item.price)}</p>)}
-          {showQuantity && (
-            <QuantityIndicator 
-              item={item} 
-              clx='h-[26px] ml-1' 
-              iconClx='fill-foreground'
-              digitClx='not-typography font-semibold text-primary-fg leading-none font-sans text-xs' 
-            />
-          )}
-        </ApplyTypography>
-      )}
-    </CarouselItem>
-  ) 
-}
-
-const CarouselItemSelector: React.FC<ItemSelectorProps> = observer(({ 
-  items,
-  selectSku,
-  selectedItemRef: itemRef,
-  scrollable, // ignored
-  clx='',
-  itemClx='',
-  options={},
-  ext={
-    options: {loop: true},
-    constrainTo: DEFAULT_CONSTRAINT,
-    imageOnly: false 
-  } satisfies CarouselItemSelectorPropsExt
-}) => {
-
-  const showFamily = 'showFamily' in options ? options.showFamily! : false
-  const showPrice = 'showPrice' in options ? options.showPrice! : true
-  const showQuantity = 'showQuantity' in options ? options.showQuantity! : false
-
-  const carouselOptions = 'options' in ext ? ext.options : undefined
-  const constrainTo = 'constrainTo' in ext ? ext.constrainTo : DEFAULT_CONSTRAINT
-  const imageOnly = 'imageOnly' in ext ? ext.imageOnly : false
-
-  const elbaApiRef = useRef<CarouselApi | undefined>(undefined)
-  const dontRespondRef = useRef<boolean>(false)
-
-  const setApi = (api: CarouselApi) => {elbaApiRef.current = api}
-
-  const onSelect = useCallback((emblaApi: CarouselApi) => {
-    if (dontRespondRef.current) {
-      dontRespondRef.current = false
-      return
-    }
-    const index = emblaApi.selectedScrollSnap()
-    if (index !== -1) {
-      selectSku(items[index].sku)
-    }
-    dontRespondRef.current = false
-  }, [])
-
-  useEffect(() => {
-    return reaction(
-      () => ({item: itemRef.item}),
-      ({item}) => {
-        if (elbaApiRef.current) {
-          const index = items.findIndex((el) => (el.sku === item?.sku))  
-          if (index !== -1) {
-            dontRespondRef.current = true
-            elbaApiRef.current.scrollTo(index) 
-          }
-        }
-      }  
-    )
-  }, [])
-
-  return ( 
-    <Carousel options={carouselOptions} className={cn('w-full px-2', clx)} onCarouselSelect={onSelect} setApi={setApi}>
-      <CarouselContent>
-      {items.map((item) => (
-        <ItemSlide 
-          key={item.sku} 
-          item={item}
-          {...{
-            showFamily,
-            showPrice,
-            showQuantity,
-            constrainTo,
-            imageOnly
-          }}
-          clx={itemClx}
-        />
-      ))}
-      </CarouselContent>
-      <CarouselPrevious className='left-1'/>
-      <CarouselNext className='right-1'/>
-    </Carousel>
-  )
-})
-
-export {
-  type CarouselItemSelectorPropsExt,
-  CarouselItemSelector as default 
-}