create-tanqory-theme 0.0.0-stage → 0.2.3

package/templates/nova/src/sections/Header/Header.tsx

@@ -0,0 +1,478 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState, type CSSProperties, type KeyboardEvent as ReactKeyboardEvent, type MouseEvent as ReactMouseEvent } from 'react'
+import { type SettingsOf } from '@tanqory/theme-kit'
+import { Icon } from '../../styles/Icon'
+import { IconButton } from '../../components/base/IconButton'
+import { Input } from '../../components/base/Input'
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import { MobileNavDrawer } from '../../components/overlays/MobileNavDrawer'
+import { LocaleSelector } from '../../components/navigation/LocaleSelector'
+import { MarketSelector } from '../../components/overlays/MarketSelector'
+import { BrandLogo, brandName } from '../../components/navigation/BrandLogo'
+import { Menu } from '../../components/navigation/Menu'
+import { bestLabel, contrastRatio } from '../../styles/theme'
+import type { Collection, NovaCartSummary, NovaCustomer, NovaLocalization, NovaMarket, NovaMenu, NovaMenuItem, NovaShop } from '@tanqory/theme-kit'
+import { sectionRootProps } from '../../components/section/shared'
+import '../../components/section/shared.css'
+import './Header.css'
+import { headerSchema } from './schema'
+
+export type HeaderSettings = SettingsOf<typeof headerSchema>
+
+export interface HeaderData {
+  shop: NovaShop
+  /** The resolved `menu` handle. */
+  menu?: NovaMenu | null
+  cart?: NovaCartSummary
+  customer?: NovaCustomer
+  localization?: NovaLocalization | null
+  /**
+   * The store's collections — the mobile drawer lists them (after Home) when the
+   * menu has no items, so a phone shopper always has somewhere to go.
+   */
+  collections?: Collection[]
+  /**
+   * The page's first section is a hero / slideshow / video-hero WITH media —
+   * transparentOnHero only applies then (12A dependency). The adapter knows
+   * the page; the header does not guess.
+   */
+  overHero?: boolean
+}
+
+export interface HeaderHandlers {
+  onOpenSearch?: () => void
+  onOpenCart?: () => void
+  onOpenAccount?: () => void
+  /** The host opens its own region dialog instead of the built-in one. */
+  onOpenLocale?: () => void
+  /** Apply a market chosen in the built-in Region & language dialog (may be async; reject → error state). */
+  onChangeLocale?: (market: NovaMarket) => void | Promise<void>
+  onSearch?: (query: string) => void
+}
+
+export interface HeaderLabState {
+  /** Pin the stuck (scrolled) state — stories and visual tests. */
+  stuck?: boolean
+  /** Open a mega / simple panel by top-level index — stories and visual tests. */
+  openIndex?: number
+  /** Open the mobile drawer — stories and visual tests. */
+  drawerOpen?: boolean
+  /** Drawer level to open at (indexes into the menu). */
+  drawerPath?: number[]
+}
+
+export type HeaderProps = HeaderSettings & HeaderData & HeaderHandlers & HeaderLabState
+
+const MAX_MEGA_COLUMNS = 5
+/** Collections the drawer lists when the store's menu is empty. */
+const MAX_FALLBACK_COLLECTIONS = 8
+
+/**
+ * The drawer's rows when the store's menu has no items: Home, then the store's
+ * collections. The desktop bar shows no nav strip for an empty menu; the drawer
+ * (and its Sign in / Account foot) stays reachable on a phone either way.
+ */
+export function fallbackMenu(home: string, collections: readonly Collection[] = []): NovaMenu {
+  return {
+    handle: 'fallback',
+    title: home,
+    items: [
+      { title: home, url: '/' },
+      ...collections.slice(0, MAX_FALLBACK_COLLECTIONS).map((c) => ({ title: c.title, url: c.url || `/collections/${encodeURIComponent(c.handle)}` })),
+    ],
+  }
+}
+
+/** The legacy text colour: kept if it reads at 4.5:1 on the legacy background, else flipped to ink / white. */
+function legacyColors(bg?: string, fg?: string): CSSProperties | undefined {
+  if (!bg) return undefined
+  const text = fg && contrastRatio(bg, fg) >= 4.5 ? fg : bestLabel(bg)
+  return { '--nv-header-bg': bg, '--nv-header-fg': text } as CSSProperties
+}
+
+function useScrollState(sticky: HeaderSettings['sticky'], pinned?: boolean): { stuck: boolean; hidden: boolean } {
+  const [state, setState] = useState({ stuck: false, hidden: false })
+  useEffect(() => {
+    if (sticky === 'none' || typeof window === 'undefined') return
+    let last = window.scrollY
+    const onScroll = () => {
+      const y = window.scrollY
+      const hidden = sticky === 'on-scroll-up' && y > last && y > 120
+      setState({ stuck: y > 0, hidden })
+      last = y
+    }
+    onScroll()
+    window.addEventListener('scroll', onScroll, { passive: true })
+    return () => window.removeEventListener('scroll', onScroll)
+  }, [sticky])
+  return pinned === undefined ? state : { stuck: pinned, hidden: false }
+}
+
+/**
+ * "Nav never wraps to a second line: if items overflow at any width the
+ * header switches to the drawer." Measured, not guessed: whenever the width
+ * (or the content) changes the desktop layout renders first, the nav is
+ * measured before paint, and only then may the header collapse. Measuring
+ * only in the expanded state is what keeps this from oscillating.
+ */
+function useNavOverflow(root: React.RefObject<HTMLElement>, deps: unknown[]): [React.RefObject<HTMLUListElement>, boolean] {
+  const ref = useRef<HTMLUListElement>(null)
+  const [collapsed, setCollapsed] = useState(false)
+  const [width, setWidth] = useState(0)
+  useEffect(() => {
+    const el = root.current
+    if (!el || typeof ResizeObserver === 'undefined') return
+    const ro = new ResizeObserver(([entry]) => {
+      const w = Math.round(entry.contentRect.width)
+      setWidth((prev) => {
+        if (prev !== w) setCollapsed(false)
+        return w
+      })
+    })
+    ro.observe(el)
+    return () => ro.disconnect()
+  }, [root])
+  useEffect(() => setCollapsed(false), deps) // eslint-disable-line react-hooks/exhaustive-deps
+  // A web font arriving changes the nav's width without resizing the header:
+  // measured under the fallback font it may have collapsed, so measure again.
+  useEffect(() => {
+    const fonts = typeof document !== 'undefined' ? document.fonts : undefined
+    if (!fonts?.addEventListener) return
+    const again = () => setCollapsed(false)
+    fonts.addEventListener('loadingdone', again)
+    return () => fonts.removeEventListener('loadingdone', again)
+  }, [])
+  useLayoutEffect(() => {
+    const el = ref.current
+    if (collapsed || !el || el.clientWidth === 0) return
+    if (el.scrollWidth > el.clientWidth + 1) setCollapsed(true)
+  })
+  void width
+  return [ref, collapsed]
+}
+
+/** Run `effect` when `value` changes after the first render — never on mount. */
+function useChanged<T>(value: T, effect: () => void): void {
+  const prev = useRef(value)
+  useEffect(() => {
+    if (Object.is(prev.current, value)) return
+    prev.current = value
+    effect()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value])
+}
+
+export function Header(props: HeaderProps): JSX.Element {
+  const {
+    layout,
+    sticky,
+    menuStyle,
+    logo,
+    logoHeight,
+    transparentOnHero,
+    showSearch,
+    searchStyle,
+    showAccount,
+    showCart,
+    cartAction,
+    cartCount,
+    showLocale,
+    background,
+    bg,
+    fg,
+    shop,
+    menu,
+    cart,
+    customer,
+    localization,
+    collections,
+    overHero,
+    onOpenSearch,
+    onOpenCart,
+    onOpenAccount,
+    onOpenLocale,
+    onChangeLocale,
+    onSearch,
+    stuck: pinnedStuck,
+    openIndex,
+    drawerOpen,
+    drawerPath,
+  } = props
+  const { strings } = useNova()
+  const uid = useId()
+  const items = menu?.items ?? []
+  // An empty menu still opens a drawer (Home, the collections, Sign in / Account):
+  // without one a phone shopper had no way to reach the account from the header.
+  const drawerMenu = items.length > 0 ? menu : fallbackMenu(strings.home, collections)
+  const [open, setOpen] = useState<number | null>(openIndex ?? null)
+  const [drawer, setDrawer] = useState(Boolean(drawerOpen))
+  const triggers = useRef<(HTMLElement | null)[]>([])
+  const menuButton = useRef<HTMLButtonElement>(null)
+  const rootRef = useRef<HTMLElement>(null)
+  const { stuck, hidden } = useScrollState(sticky, pinnedStuck)
+  const [navRef, navOverflow] = useNavOverflow(rootRef, [items.length, layout, searchStyle, logo, shop.name, showLocale])
+
+  // Lab pins follow their prop only when it CHANGES after mount. Syncing on
+  // mount too raced the first interaction: React may flush that mount effect
+  // after a fast click and reset what the click just opened.
+  useChanged(openIndex, () => setOpen(openIndex ?? null))
+  useChanged(drawerOpen, () => setDrawer(Boolean(drawerOpen)))
+
+  const close = useCallback((returnFocus: boolean) => {
+    setOpen((cur) => {
+      if (returnFocus && cur !== null) triggers.current[cur]?.focus()
+      return null
+    })
+  }, [])
+
+  // Esc closes an open panel and returns focus to its trigger; a click outside closes it.
+  useEffect(() => {
+    if (open === null) return
+    const onKey = (e: KeyboardEvent) => e.key === 'Escape' && close(true)
+    const onDown = (e: MouseEvent) => {
+      if (rootRef.current && !rootRef.current.contains(e.target as Node)) close(false)
+    }
+    document.addEventListener('keydown', onKey)
+    document.addEventListener('mousedown', onDown)
+    return () => {
+      document.removeEventListener('keydown', onKey)
+      document.removeEventListener('mousedown', onDown)
+    }
+  }, [open, close])
+
+  const transparent = transparentOnHero && Boolean(overHero)
+  // Solid when stuck or when a dropdown opens.
+  const solid = !transparent || stuck || open !== null
+  const count = cart ? (cartCount === 'lines' ? cart.lineCount : cart.itemCount) : 0
+  const countLabel = fmt(strings.cartCount, { count })
+  const brandText = brandName(shop, logo)
+  const inlineSearch = showSearch && searchStyle === 'inline-field' && layout === 'logo-left'
+  const hasLocale = showLocale && localization && localization.available.length > 1
+
+  const brand = (
+    <a href="/" className="nv-header__brand" aria-label={shop.logo ? shop.name : undefined} title={!shop.logo && brandText.length > 18 ? brandText : undefined}>
+      <BrandLogo shop={shop} text={logo} imageClassName="nv-header__logo" textClassName="nv-header__wordmark" />
+    </a>
+  )
+
+  const renderPanel = (item: NovaMenuItem, i: number) => {
+    const children = item.items ?? []
+    if (!children.length) return null
+    const panelId = `${uid}-panel-${i}`
+    const isMega = menuStyle === 'mega' && children.some((c) => c.items?.length)
+    return (
+      <div id={panelId} className="nv-header__panel" data-style={isMega ? 'mega' : 'simple'} hidden={open !== i}>
+        {isMega ? (
+          <div className="nv-header__mega">
+            <div className="nv-header__mega-cols">
+              {children.slice(0, MAX_MEGA_COLUMNS).map((col, c) => (
+                <div key={`${col.title}-${c}`} className="nv-header__mega-col">
+                  {col.url ? (
+                    <a className="nv-header__mega-heading" href={col.url}>
+                      <bdi>{col.title}</bdi>
+                    </a>
+                  ) : (
+                    <p className="nv-header__mega-heading"><bdi>{col.title}</bdi></p>
+                  )}
+                  <Menu items={col.items ?? []} />
+                </div>
+              ))}
+            </div>
+            {item.url && (
+              <a className="nv-header__shop-all" href={item.url}>
+                {fmt(strings.shopAll, { title: item.title })}
+                <Icon name="arrow-right" size="sm" />
+              </a>
+            )}
+          </div>
+        ) : (
+          <Menu
+            items={children}
+            className="nv-header__simple"
+            trailing={
+              item.url && (
+                <li className="nv-header__simple-all">
+                  <a href={item.url}>{fmt(strings.shopAll, { title: item.title })}</a>
+                </li>
+              )
+            }
+          />
+        )}
+      </div>
+    )
+  }
+
+  const onTriggerKey = (e: ReactKeyboardEvent, i: number) => {
+    if (e.key === 'ArrowDown' && items[i].items?.length) {
+      e.preventDefault()
+      setOpen(i)
+      requestAnimationFrame(() => document.getElementById(`${uid}-panel-${i}`)?.querySelector<HTMLElement>('a')?.focus())
+    }
+  }
+
+  const nav = items.length > 0 && (
+    <nav className="nv-header__nav" aria-label={strings.primaryNav}>
+      <ul ref={navRef} className="nv-header__nav-list">
+        {items.map((item, i) => {
+          const hasPanel = Boolean(item.items?.length)
+          return (
+            <li key={`${item.title}-${i}`} className="nv-header__nav-item" data-open={open === i ? '' : undefined} onMouseEnter={() => hasPanel && setOpen(i)} onMouseLeave={() => hasPanel && setOpen(null)}>
+              {hasPanel ? (
+                <button
+                  ref={(el) => (triggers.current[i] = el)}
+                  type="button"
+                  className="nv-header__nav-link"
+                  aria-expanded={open === i}
+                  aria-controls={`${uid}-panel-${i}`}
+                  data-active={item.active ? '' : undefined}
+                  // A mouse already opened the panel on hover, so its click must not
+                  // toggle it shut again (the menu looked dead). A keyboard press
+                  // (detail 0) still toggles, as a disclosure button should.
+                  onClick={(e) => setOpen((cur) => (e.detail === 0 && cur === i ? null : i))}
+                  onKeyDown={(e) => onTriggerKey(e, i)}
+                >
+                  {item.title}
+                </button>
+              ) : item.url ? (
+                <a ref={(el) => (triggers.current[i] = el)} className="nv-header__nav-link" href={item.url} aria-current={item.active ? 'page' : undefined} data-active={item.active ? '' : undefined}>
+                  <bdi>{item.title}</bdi>
+                </a>
+              ) : (
+                <span className="nv-header__nav-link"><bdi>{item.title}</bdi></span>
+              )}
+              {hasPanel && renderPanel(item, i)}
+            </li>
+          )
+        })}
+      </ul>
+    </nav>
+  )
+
+  const textUtilities = layout === 'logo-center'
+  const searchButton = showSearch && !inlineSearch && (
+    textUtilities ? (
+      <button type="button" className="nv-header__text-util" onClick={onOpenSearch}>
+        {strings.search}
+      </button>
+    ) : (
+      <IconButton icon="search" label={strings.search} onClick={onOpenSearch} />
+    )
+  )
+  const accountButton = showAccount && (textUtilities ? (
+    <a className="nv-header__text-util" href="/account" onClick={onOpenAccount ? (e) => (e.preventDefault(), onOpenAccount()) : undefined}>
+      {strings.account}
+    </a>
+  ) : (
+    <IconButton icon="user" label={customer?.signedIn ? strings.myAccount : strings.account} onClick={onOpenAccount} />
+  ))
+  // Always a link to the cart page, so the cart (and checkout) is reachable before the browser bundle
+  // runs; with cartAction 'drawer' the click opens the drawer instead.
+  const openCart = cartAction === 'drawer' && onOpenCart ? (e: ReactMouseEvent<HTMLAnchorElement>) => (e.preventDefault(), onOpenCart()) : undefined
+  const cartControl = showCart && (
+    textUtilities ? (
+      <a className="nv-header__text-util nv-tabular" href="/cart" aria-label={countLabel} onClick={openCart}>
+        {strings.cart} ({count})
+      </a>
+    ) : (
+      <a className="nv-icon-btn" href="/cart" aria-label={countLabel} onClick={openCart}>
+        <Icon name="bag" size="md" />
+        {count > 0 && <span className="nv-icon-btn__count nv-tabular" aria-hidden>{count > 99 ? '99+' : count}</span>}
+      </a>
+    )
+  )
+  const localeButton =
+    hasLocale &&
+    localization &&
+    (onOpenLocale ? <LocaleSelector localization={localization} onOpen={onOpenLocale} variant="compact" /> : <MarketSelector localization={localization} onChange={onChangeLocale} variant="compact" placement="bottom-end" />)
+  const inlineField = inlineSearch && (
+    <form
+      className="nv-header__search"
+      role="search"
+      action="/search"
+      onSubmit={
+        onSearch
+          ? (e) => {
+              e.preventDefault()
+              onSearch(new FormData(e.currentTarget).get('q') as string)
+            }
+          : undefined
+      }
+    >
+      <label className="nv-visually-hidden" htmlFor={`${uid}-q`}>
+        {strings.search}
+      </label>
+      <Input id={`${uid}-q`} name="q" type="search" icon="search" placeholder={strings.searchPlaceholder} />
+    </form>
+  )
+
+  return (
+    <>
+      <a className="nv-skip-link" href="#main">
+        {strings.skipToContent}
+      </a>
+      <header
+        ref={rootRef}
+        {...sectionRootProps({ background }, 'header')}
+        className={sxJoin("nv-header", sx(legacyColors(bg, fg)))}
+        data-layout={layout}
+        data-sticky={sticky}
+        data-stuck={stuck ? '' : undefined}
+        data-hidden={hidden ? '' : undefined}
+        data-transparent={!solid ? '' : undefined}
+        data-logo-height={logoHeight}
+        data-collapsed={navOverflow ? '' : undefined}
+        data-legacy-color={bg ? '' : undefined}
+        data-menu-open={open !== null ? '' : undefined}
+      >
+        <div className="nv-header__bar">
+          {/* < 1024 (and whenever the nav overflows): Menu + Search · brand · Cart */}
+          <div className="nv-header__compact-start">
+            <IconButton ref={menuButton} icon="menu" label={strings.openMenu} aria-expanded={drawer} aria-haspopup="dialog" onClick={() => setDrawer(true)} />
+            {showSearch && <IconButton icon="search" label={strings.search} onClick={onOpenSearch} />}
+          </div>
+          {layout === 'logo-center' ? (
+            <>
+              <div className="nv-header__side nv-header__side--start">{searchButton}</div>
+              <div className="nv-header__brand-cell">{brand}</div>
+              <div className="nv-header__side nv-header__side--end">
+                {localeButton}
+                {accountButton}
+                {cartControl}
+              </div>
+              <div className="nv-header__nav-row">{nav}</div>
+            </>
+          ) : (
+            <>
+              <div className="nv-header__brand-cell">{brand}</div>
+              {nav}
+              <div className="nv-header__side nv-header__side--end">
+                {inlineField}
+                {localeButton}
+                {searchButton}
+                {accountButton}
+                {cartControl}
+              </div>
+            </>
+          )}
+          <div className="nv-header__compact-end">{cartControl}</div>
+        </div>
+      </header>
+      <MobileNavDrawer
+        open={drawer}
+        onClose={() => setDrawer(false)}
+        menu={drawerMenu}
+        shop={shop}
+        customer={customer}
+        localization={localization}
+        showAccount={showAccount}
+        showLocale={showLocale}
+        onOpenLocale={onOpenLocale}
+        onChangeLocale={onChangeLocale}
+        // Nova 13 · 2: the search entry on top — offered when the drawer is the store's fallback menu.
+        onSearch={items.length === 0 && showSearch && onOpenSearch ? () => (setDrawer(false), onOpenSearch()) : undefined}
+        initialPath={drawerPath}
+      />
+    </>
+  )
+}

package/templates/nova/src/sections/Header/index.ts

@@ -0,0 +1,32 @@
+import { defineSection, menuFor, resolveSettings } from '@tanqory/theme-kit'
+import { isHeroWithMedia } from '../data'
+import { Header } from './Header'
+import { presets } from './presets'
+import { headerSchema } from './schema'
+
+export default defineSection({
+  id: 'header',
+  schema: headerSchema,
+  component: Header,
+  category: 'layout',
+  zone: 'header',
+  title: 'Header',
+  description: 'Logo, navigation, search and cart at the top of every page.',
+  icon: '▭',
+  presets,
+  data: (node, store, { actions, page }) => {
+      const r = resolveSettings(headerSchema, node.settings)
+      // Settings › Customer accounts › "Show sign-in links" off hides the account icon and the drawer's Sign in.
+      return { ...r.settings, showAccount: r.settings.showAccount && store.shop.signInLinks !== false, shop: store.shop, menu: menuFor(store, r.handles.menu), cart: store.cart, customer: store.customer, localization: store.localization, collections: store.newestCollections, overHero: page.firstBodySection ? isHeroWithMedia(page.firstBodySection, store) : false,
+      onOpenSearch: actions.search.open,
+      onOpenCart: actions.cart.open,
+      onOpenAccount: () => actions.navigate('/account'),
+      onSearch: actions.search.go,
+      onChangeLocale: (market: { countryCode?: string; code?: string; languageCode?: string }) => {
+        const next = { countryCode: market.countryCode ?? market.code ?? '', languageCode: market.languageCode }
+        if (actions.localization.changeLocale) actions.localization.changeLocale(next, store.localization?.current)
+        else actions.localization.changeCountry(next.countryCode)
+      },
+    }
+  },
+})

package/templates/nova/src/sections/Header/presets.ts

@@ -0,0 +1,10 @@
+import type { SectionPreset } from '@tanqory/theme-kit'
+/** What "Add section" offers as starting points. */
+export const presets: readonly SectionPreset[] = [
+  // Default storefront header for most catalogues
+  {"name": "header-standard", "label": "Standard", "settings": {"layout": "logo-left", "sticky": "always", "menuStyle": "mega", "searchStyle": "icon", "background": "surface"}, "blocks": []},
+  // Brand-forward stores with short menus
+  {"name": "header-centered", "label": "Centered boutique", "settings": {"layout": "logo-center", "sticky": "on-scroll-up", "menuStyle": "simple", "logoHeight": "large"}, "blocks": []},
+  // Immersive campaign home pages
+  {"name": "header-over-hero", "label": "Over hero", "settings": {"layout": "logo-left", "transparentOnHero": true, "sticky": "always"}, "blocks": []},
+]

package/templates/nova/src/sections/Header/schema.ts

@@ -0,0 +1,32 @@
+import { defineSchema, field } from '@tanqory/theme-kit'
+import { BACKGROUND } from '../../components/section/shared'
+
+/**
+ * 12A · 01 header — "invisible by default": logo left, primary nav centred,
+ * icon utilities right, one hairline below, sticky and condensing to 56px.
+ * Menus with two levels open a text-only mega panel. Nothing the merchant
+ * sets introduces a free colour in the default path (bg / fg are
+ * LEGACY-HIDDEN: saved values keep rendering, contrast is corrected).
+ */
+export const headerSchema = defineSchema(
+  { kind: 'section', name: 'header', family: '12A' },
+  {
+    layout: field.select(['logo-left', 'logo-center'], 'logo-left'),
+    sticky: field.select(['always', 'on-scroll-up', 'none'], 'always'),
+    menu: field.resource('menu', 'main-menu'),
+    menuStyle: field.select(['simple', 'mega'], 'mega'),
+    logo: field.text(''),
+    logoHeight: field.select(['small', 'medium', 'large'], 'medium'),
+    transparentOnHero: field.boolean(false),
+    showSearch: field.boolean(true),
+    searchStyle: field.select(['icon', 'inline-field'], 'icon'),
+    showAccount: field.boolean(true),
+    showCart: field.boolean(true),
+    cartAction: field.select(['drawer', 'page'], 'drawer'),
+    cartCount: field.select(['items', 'lines'], 'items'),
+    showLocale: field.boolean(false),
+    background: field.select(BACKGROUND, 'surface'),
+    bg: field.color('', { legacyHidden: true, semantic: 'background' }),
+    fg: field.color('', { legacyHidden: true, semantic: 'text' }),
+  },
+)