@graphcommerce/storyblok-ui 10.1.0-canary.4

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @graphcommerce/storyblok-ui
+
+## 10.1.0-canary.4
+
+### Patch Changes
+
+- [#2606](https://github.com/graphcommerce-org/graphcommerce/pull/2606) [`d30c568`](https://github.com/graphcommerce-org/graphcommerce/commit/d30c5681e018496ce44c349f69b122d143e894d2) - Performance improvements for Storyblok bridge ([@bramvanderholst](https://github.com/bramvanderholst))
+
+- [#2606](https://github.com/graphcommerce-org/graphcommerce/pull/2606) [`d30c568`](https://github.com/graphcommerce-org/graphcommerce/commit/d30c5681e018496ce44c349f69b122d143e894d2) - Added Storyblok pages to content sitemap ([@bramvanderholst](https://github.com/bramvanderholst))
+
+## 10.1.0-canary.3
+
+### Minor Changes
+
+- [#2603](https://github.com/graphcommerce-org/graphcommerce/pull/2603) [`7198061`](https://github.com/graphcommerce-org/graphcommerce/commit/71980613241a240fa29ba9894872b90c3d32c2b6) - ## Storyblok example
+
+  We're shipping `examples/magento-storyblok` — a full Storyblok CMS integration alongside the existing Hygraph example, so teams can pick the headless CMS that fits their workflow.
+
+  **What's in the box**
+
+  - Visual editing: live preview, click-to-edit on every blok, and SSR with client hydration
+  - Row components out of the box: hero banners, special banners, quotes, button link lists, service options, product grids, blog content, and USPs — all editable in the Storyblok Visual Editor
+  - Global config pattern for content shared across pages (footer links, social links, USPs) with live updates in the editor
+  - Type-safe integration: generated TypeScript types for every component schema via the Storyblok CLI
+  - `@graphcommerce/storyblok-ui` helpers: rich text renderer, asset component with video/image support, multilink resolution, product block resolution, and Visual Editor utilities
+
+  **Getting started**
+
+  - `yarn storyblok:bootstrap` seeds a new Storyblok space with all demo content (components, stories, assets) so a fresh install is editable in minutes
+  - `spaceId` lives in `graphcommerce.config.cjs` alongside your other config — no separate env juggling
+  - Components, stories, and assets are committed to the repo as the source of truth
+
+  **Also includes**
+
+  - Storyblok-aware Footer, Navigation, and PDP layouts wired to the global config
+  - Blog support with tag filtering and pagination
+  - Preview URL routing so the Visual Editor opens the right page for each story type ([@bramvanderholst](https://github.com/bramvanderholst))

package/Config.graphqls

@@ -0,0 +1,32 @@
+"""
+Settings for the Storyblok integration.
+"""
+input StoryblokConfig {
+  """
+  Your project's Storyblok space ID. Used as the target space for `storyblok:bootstrap`
+  (seeding a new space with the example content) and as the default space for pull/push commands.
+  """
+  spaceId: String!
+
+  """
+  Public preview access token for the Storyblok Content Delivery API. Found under
+  Settings → Access Tokens in the Storyblok space. Inlined into the client bundle —
+  do not use a private/management token here. Override per-environment with
+  `GC_STORYBLOK_ACCESS_TOKEN`.
+  """
+  accessToken: String!
+
+  """
+  Source Storyblok space ID to bootstrap from. Defaults to the GraphCommerce
+  example space (291439709879423) which contains demo content for this template.
+  Override only if you maintain your own example/template space.
+  """
+  sourceSpaceId: String
+}
+
+extend input GraphCommerceConfig {
+  """
+  Settings for the Storyblok integration.
+  """
+  storyblok: StoryblokConfig!
+}

package/components/Asset.tsx

@@ -0,0 +1,72 @@
+import type { ImageProps } from '@graphcommerce/image'
+import { Image } from '@graphcommerce/image'
+import type { SxProps, Theme } from '@mui/material'
+import { styled } from '@mui/material'
+import { memo } from 'react'
+import type { StoryblokAssetData } from '../types'
+import { isSvg, isVideo, parseDimensions } from '../utils'
+
+export type AssetProps = {
+  asset: StoryblokAssetData
+  sx?: SxProps<Theme>
+} & Omit<ImageProps, 'src' | 'width' | 'height' | 'alt' | 'sx'>
+
+const Video = styled('video')({})
+
+// Storyblok encodes image dimensions in the CDN URL (`/WxH/`), but its image
+// processor only runs for uploads made through the web UI. Assets uploaded via
+// the Management API — which is what the CLI's `assets push` (used by our
+// bootstrap script) does — never get that segment, so `parseDimensions`
+// returns null for them. next/image requires non-zero width/height or it
+// emits a 1w placeholder in srcset that some browsers pick inside the
+// Storyblok Visual Editor iframe, leaving images blank. These fallbacks
+// satisfy next/image; the rendered size is controlled by CSS (sx).
+//
+// In practice this only affects the bootstrapped demo content — assets
+// editors upload through the Storyblok UI get proper dimensions in the URL
+// and hit the `parseDimensions` path above.
+const FALLBACK_WIDTH = 500
+const FALLBACK_HEIGHT = 500
+
+function AssetBase(props: AssetProps) {
+  const { asset, sx = [], ...imgProps } = props
+
+  if (!asset.filename) return null
+
+  if (isVideo(asset.filename)) {
+    return (
+      <Video src={asset.filename} autoPlay muted loop playsInline disableRemotePlayback sx={sx} />
+    )
+  }
+
+  const dimensions = parseDimensions(asset.filename)
+
+  if (isSvg(asset.filename)) {
+    return (
+      <Image
+        src={asset.filename}
+        width={dimensions?.width ?? 0}
+        height={dimensions?.height ?? 0}
+        alt={asset.alt ?? ''}
+        unoptimized
+        {...imgProps}
+        sx={
+          dimensions ? sx : [{ width: '100%', height: 'auto' }, ...(Array.isArray(sx) ? sx : [sx])]
+        }
+      />
+    )
+  }
+
+  return (
+    <Image
+      src={asset.filename}
+      width={dimensions?.width ?? FALLBACK_WIDTH}
+      height={dimensions?.height ?? FALLBACK_HEIGHT}
+      alt={asset.alt ?? ''}
+      {...imgProps}
+      sx={sx}
+    />
+  )
+}
+
+export const Asset = memo(AssetBase)

package/components/RichText/RichText.tsx

@@ -0,0 +1,176 @@
+import type { SxProps, Theme } from '@mui/material'
+import { Fragment, type ReactElement, type ReactNode } from 'react'
+import type { StoryblokRichtextData } from '../../types'
+import { defaultRenderers } from './defaultRenderers'
+import { defaultSxRenderer } from './defaultSxRenderer'
+import type { AdditionalProps, Renderer, Renderers, RichTextNodeType, SxRenderer } from './types'
+
+const sxArr = (sx?: SxProps<Theme> | false): SxProps<Theme>[] => {
+  if (!sx) return []
+  return Array.isArray(sx) ? (sx as SxProps<Theme>[]) : [sx]
+}
+
+function computeSx(
+  { first, last, sxRenderer }: Pick<AdditionalProps, 'first' | 'last' | 'sxRenderer'>,
+  type: RichTextNodeType,
+): SxProps<Theme> {
+  return [
+    ...sxArr(sxRenderer.all),
+    ...sxArr(sxRenderer[type]),
+    ...sxArr(first && sxRenderer.first),
+    ...sxArr(last && sxRenderer.last),
+  ] as SxProps<Theme>
+}
+
+function resolveType(node: StoryblokRichtextData): RichTextNodeType | null {
+  if (node.type === 'heading') {
+    const level = (node.attrs?.level as number | undefined) ?? 1
+    return `h${level}` as RichTextNodeType
+  }
+  return node.type as RichTextNodeType
+}
+
+function RenderText(props: { node: StoryblokRichtextData } & AdditionalProps): ReactNode {
+  const { node, renderers, sxRenderer, first, last } = props
+  const text = node.text ?? ''
+
+  const parts = text.split('\n')
+  const withBreaks: ReactNode =
+    parts.length === 1 ? (
+      text
+    ) : (
+      <>
+        {parts.map((part, i) => (
+          <Fragment key={i}>
+            {part}
+            {i < parts.length - 1 ? <br /> : null}
+          </Fragment>
+        ))}
+      </>
+    )
+
+  const marks = node.marks ?? []
+  return marks.reduce<ReactNode>((child, mark) => {
+    const type = mark.type as RichTextNodeType
+    const MarkRenderer = renderers[type] as Renderer<Record<string, unknown>> | undefined
+    if (!MarkRenderer) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.error(mark)
+        throw new Error(`RichText: Unknown mark type: ${mark.type}`)
+      }
+      return child
+    }
+    const sx = computeSx({ first, last, sxRenderer }, type)
+    const attrs = (mark.attrs ?? {}) as Record<string, unknown>
+    return (
+      <MarkRenderer sx={sx} {...attrs}>
+        {child}
+      </MarkRenderer>
+    )
+  }, withBreaks)
+}
+
+function RenderNode(props: { node: StoryblokRichtextData } & AdditionalProps): ReactNode {
+  const { node } = props
+  if (node.type === 'text') return <RenderText {...props} />
+
+  const { renderers, sxRenderer, first, last } = props
+  const type = resolveType(node)
+  if (!type) return null
+
+  const NodeRenderer = renderers[type] as Renderer<Record<string, unknown>> | undefined
+  if (!NodeRenderer) {
+    if (process.env.NODE_ENV !== 'production') {
+      console.error(node)
+      throw new Error(`RichText: Unknown node type: ${node.type}`)
+    }
+    return null
+  }
+
+  const sx = computeSx({ first, last, sxRenderer }, type)
+  const attrs = (node.attrs ?? {}) as Record<string, unknown>
+  const children = node.content ? (
+    <RenderChildren childNodes={node.content} renderers={renderers} sxRenderer={sxRenderer} />
+  ) : null
+
+  return (
+    <NodeRenderer sx={sx} {...attrs}>
+      {children}
+    </NodeRenderer>
+  )
+}
+
+function RenderChildren(
+  props: { childNodes: StoryblokRichtextData[]; noMargin?: boolean } & Pick<
+    AdditionalProps,
+    'renderers' | 'sxRenderer'
+  >,
+): ReactElement {
+  const { childNodes, noMargin, renderers, sxRenderer } = props
+  return (
+    <>
+      {childNodes.map((node, key) => (
+        <RenderNode
+          // eslint-disable-next-line react/no-array-index-key
+          key={key}
+          node={node}
+          renderers={renderers}
+          sxRenderer={sxRenderer}
+          first={noMargin && key === 0}
+          last={noMargin && key === childNodes.length - 1}
+        />
+      ))}
+    </>
+  )
+}
+
+function mergeSxRenderer(base: SxRenderer, override?: SxRenderer): SxRenderer {
+  if (!override) return base
+  const keys = new Set([...Object.keys(base), ...Object.keys(override)])
+  const result: SxRenderer = {}
+  for (const key of keys) {
+    const k = key as keyof SxRenderer
+    const baseSx = base[k]
+    const overrideSx = override[k]
+    if (baseSx && overrideSx) {
+      result[k] = [...sxArr(baseSx), ...sxArr(overrideSx)] as SxProps<Theme>
+    } else {
+      result[k] = baseSx ?? overrideSx
+    }
+  }
+  return result
+}
+
+export type RichTextProps = {
+  content: StoryblokRichtextData
+  renderers?: Partial<Renderers>
+  /**
+   * Per-element theming. Keys are Storyblok node/mark types (e.g. `paragraph`, `h1`,
+   * `link`, `bold`). Merges with the built-in defaults.
+   *
+   * @example
+   * ```tsx
+   * <RichText
+   *   content={blok.copy}
+   *   sxRenderer={{
+   *     paragraph: (theme) => ({ columnGap: theme.spacings.md }),
+   *   }}
+   * />
+   * ```
+   */
+  sxRenderer?: SxRenderer
+  /** When true, preserves the first/last element's outer margins. Defaults to false (stripped). */
+  withMargin?: boolean
+}
+
+export function RichText({ content, renderers, sxRenderer, withMargin = false }: RichTextProps) {
+  if (!content?.content) return null
+  return (
+    <RenderChildren
+      childNodes={content.content}
+      renderers={{ ...defaultRenderers, ...renderers }}
+      sxRenderer={mergeSxRenderer(defaultSxRenderer, sxRenderer)}
+      noMargin={!withMargin}
+    />
+  )
+}

package/components/RichText/defaultRenderers.tsx

@@ -0,0 +1,86 @@
+import { sxx } from '@graphcommerce/next-ui'
+import { Box, Link, Typography } from '@mui/material'
+import { StoryblokComponent } from '@storyblok/react'
+import { Asset } from '../Asset'
+import type { Renderers } from './types'
+
+export const defaultRenderers: Renderers = {
+  paragraph: (props) => <Typography variant='body1' gutterBottom {...props} />,
+  h1: (props) => <Typography variant='h1' {...props} />,
+  h2: (props) => <Typography variant='h2' {...props} />,
+  h3: (props) => <Typography variant='h3' {...props} />,
+  h4: (props) => <Typography variant='h4' {...props} />,
+  h5: (props) => <Typography variant='h5' {...props} />,
+  h6: (props) => <Typography variant='h6' {...props} />,
+  blockquote: (props) => <Box component='blockquote' {...props} />,
+  bullet_list: (props) => <Box component='ul' {...props} />,
+  ordered_list: (props) => <Box component='ol' {...props} />,
+  list_item: (props) => <Box component='li' {...props} />,
+  code_block: ({ class: _class, ...props }) => (
+    <Box component='pre' sx={props.sx}>
+      <Box component='code'>{props.children}</Box>
+    </Box>
+  ),
+  horizontal_rule: (props) => <Box component='hr' {...props} />,
+  hard_break: () => <br />,
+  image: ({ src, alt, title, sx }) => (
+    <Box component='span' sx={sx}>
+      <Asset asset={{ filename: src ?? null, alt: alt ?? title ?? '' }} />
+    </Box>
+  ),
+  emoji: ({ emoji, name, fallbackImage, sx }) => {
+    if (emoji) {
+      return (
+        <Box component='span' sx={sx}>
+          {emoji}
+        </Box>
+      )
+    }
+    if (fallbackImage) {
+      return <Box component='img' src={fallbackImage} alt={name ?? ''} sx={sx} />
+    }
+    return null
+  },
+  blok: ({ body, sx }) => (
+    <Box sx={sx}>
+      {body?.map((item) => <StoryblokComponent key={String(item._uid)} blok={item} />)}
+    </Box>
+  ),
+  table: (props) => <Box component='table' {...props} />,
+  tableRow: (props) => <Box component='tr' {...props} />,
+  tableHeader: (props) => <Box component='th' {...props} />,
+  tableCell: (props) => <Box component='td' {...props} />,
+  bold: (props) => <Box component='strong' {...props} sx={sxx({ fontWeight: 'bold' }, props.sx)} />,
+  italic: (props) => <Box component='em' {...props} sx={sxx({ fontStyle: 'italic' }, props.sx)} />,
+  underline: (props) => <Box component='span' {...props} />,
+  strike: (props) => (
+    <Box component='s' {...props} sx={sxx({ textDecoration: 'line-through' }, props.sx)} />
+  ),
+  code: (props) => <Box component='code' {...props} />,
+  link: ({ href, anchor, target, linktype, story, ...props }) => {
+    const base =
+      linktype === 'story' ? (story?.url ?? story?.full_slug ?? href ?? '') : (href ?? '')
+    const finalHref = anchor ? `${base}#${anchor}` : base
+    return (
+      <Link
+        href={finalHref}
+        underline='hover'
+        target={target || undefined}
+        rel={target === '_blank' ? 'noopener noreferrer' : undefined}
+        {...props}
+      />
+    )
+  },
+  anchor: ({ id, ...props }) => <Box component='span' id={id} {...props} />,
+  styled: ({ class: className, ...props }) => (
+    <Box component='span' className={className} {...props} />
+  ),
+  superscript: (props) => <Box component='sup' {...props} />,
+  subscript: (props) => <Box component='sub' {...props} />,
+  textStyle: ({ color, sx, ...props }) => (
+    <Box component='span' sx={sxx(color ? { color } : {}, sx)} {...props} />
+  ),
+  highlight: ({ color, sx, ...props }) => (
+    <Box component='mark' sx={sxx(color ? { backgroundColor: color } : {}, sx)} {...props} />
+  ),
+}

package/components/RichText/defaultSxRenderer.ts

@@ -0,0 +1,69 @@
+import type { SxRenderer } from './types'
+
+export const defaultSxRenderer: SxRenderer = {
+  all: {
+    '&:empty': { display: 'none' },
+  },
+  first: { marginTop: 0 },
+  last: { marginBottom: 0 },
+  paragraph: {
+    marginBottom: '1em',
+    wordBreak: 'break-word',
+  },
+  h1: { marginTop: '0.5em', marginBottom: '0.5em' },
+  h2: { marginTop: '0.5em', marginBottom: '0.5em' },
+  h3: { marginTop: '0.5em', marginBottom: '0.5em' },
+  h4: { marginTop: '0.5em', marginBottom: '0.5em' },
+  h5: { marginTop: '0.5em', marginBottom: '0.5em' },
+  h6: { marginTop: '0.5em', marginBottom: '0.5em' },
+  blockquote: (theme) => ({
+    paddingLeft: theme.spacings.sm,
+    margin: `${theme.spacings.md} 0`,
+  }),
+  bullet_list: { marginBottom: '1em' },
+  ordered_list: { marginBottom: '1em' },
+  image: {
+    display: 'block',
+    width: '100%',
+    height: 'auto',
+    '& img': { display: 'block', width: '100%', height: 'auto' },
+  },
+  code_block: {
+    width: 'fit-content',
+    maxWidth: '100%',
+    padding: 5,
+    overflow: 'auto',
+  },
+  code: {
+    padding: '0.1em 0.3em',
+    borderRadius: 3,
+    fontSize: '0.9em',
+  },
+  table: (theme) => ({
+    display: 'table',
+    width: '100%',
+    borderSpacing: '2px',
+    borderCollapse: 'collapse',
+    marginTop: theme.spacings.md,
+    marginBottom: theme.spacings.sm,
+    '& thead, tbody': {
+      '& td': { padding: '10px 20px' },
+    },
+    '& thead tr td p': {
+      fontWeight: theme.typography.fontWeightBold,
+    },
+    '& tbody': {
+      display: 'table-row-group',
+      verticalAlign: 'center',
+      borderColor: 'inherit',
+      '& tr:nth-of-type(odd)': {
+        background: theme.vars.palette.background.paper,
+      },
+      '& td': {
+        [theme.breakpoints.up('sm')]: { minWidth: 150 },
+      },
+    },
+  }),
+  link: { wordBreak: 'break-word' },
+  underline: { textDecoration: 'underline' },
+}

package/components/RichText/index.ts

@@ -0,0 +1,4 @@
+export * from './RichText'
+export * from './types'
+export { defaultRenderers } from './defaultRenderers'
+export { defaultSxRenderer } from './defaultSxRenderer'

package/components/RichText/types.ts

@@ -0,0 +1,127 @@
+import type { SxProps, Theme } from '@mui/material'
+import type { ReactElement, ReactNode } from 'react'
+
+export type RichTextBlockType =
+  | 'paragraph'
+  | 'h1'
+  | 'h2'
+  | 'h3'
+  | 'h4'
+  | 'h5'
+  | 'h6'
+  | 'blockquote'
+  | 'bullet_list'
+  | 'ordered_list'
+  | 'list_item'
+  | 'code_block'
+  | 'horizontal_rule'
+  | 'hard_break'
+  | 'image'
+  | 'emoji'
+  | 'blok'
+  | 'table'
+  | 'tableRow'
+  | 'tableHeader'
+  | 'tableCell'
+
+export type RichTextMarkType =
+  | 'bold'
+  | 'italic'
+  | 'underline'
+  | 'strike'
+  | 'code'
+  | 'link'
+  | 'anchor'
+  | 'styled'
+  | 'superscript'
+  | 'subscript'
+  | 'textStyle'
+  | 'highlight'
+
+export type RichTextNodeType = RichTextBlockType | RichTextMarkType
+
+type RendererBase = { sx?: SxProps<Theme>; children?: ReactNode }
+
+export type LinkAttrs = {
+  href?: string
+  target?: string
+  anchor?: string
+  uuid?: string
+  linktype?: 'url' | 'story' | 'email' | 'asset'
+  story?: { url?: string; full_slug?: string }
+}
+
+export type ImageAttrs = {
+  src?: string
+  alt?: string
+  title?: string
+  copyright?: string
+}
+
+export type EmojiAttrs = { name?: string; emoji?: string; fallbackImage?: string }
+
+export type CodeBlockAttrs = { class?: string }
+
+export type StyledAttrs = { class?: string }
+
+export type TextStyleAttrs = { color?: string }
+
+export type HighlightAttrs = { color?: string }
+
+export type AnchorAttrs = { id?: string }
+
+export type BlokAttrs = {
+  id?: string
+  body?: { component?: string; _uid?: string; [k: string]: unknown }[]
+}
+
+export type Renderer<Attrs = Record<string, never>> = (
+  props: RendererBase & Attrs,
+) => ReactElement | null
+
+export type Renderers = {
+  paragraph: Renderer
+  h1: Renderer
+  h2: Renderer
+  h3: Renderer
+  h4: Renderer
+  h5: Renderer
+  h6: Renderer
+  blockquote: Renderer
+  bullet_list: Renderer
+  ordered_list: Renderer
+  list_item: Renderer
+  code_block: Renderer<CodeBlockAttrs>
+  horizontal_rule: Renderer
+  hard_break: Renderer
+  image: Renderer<ImageAttrs>
+  emoji: Renderer<EmojiAttrs>
+  blok: Renderer<BlokAttrs>
+  table: Renderer
+  tableRow: Renderer
+  tableHeader: Renderer
+  tableCell: Renderer
+  bold: Renderer
+  italic: Renderer
+  underline: Renderer
+  strike: Renderer
+  code: Renderer
+  link: Renderer<LinkAttrs>
+  anchor: Renderer<AnchorAttrs>
+  styled: Renderer<StyledAttrs>
+  superscript: Renderer
+  subscript: Renderer
+  textStyle: Renderer<TextStyleAttrs>
+  highlight: Renderer<HighlightAttrs>
+}
+
+export type SxRenderer = {
+  [k in RichTextNodeType | 'all' | 'first' | 'last']?: SxProps<Theme>
+}
+
+export type AdditionalProps = {
+  renderers: Renderers
+  sxRenderer: SxRenderer
+  first?: boolean
+  last?: boolean
+}

package/components/index.ts

@@ -0,0 +1,2 @@
+export * from './Asset'
+export * from './RichText'

package/index.ts

@@ -0,0 +1,4 @@
+export * from './components'
+export * from './lib'
+export * from './types'
+export * from './utils'

package/lib/editable.ts

@@ -0,0 +1,12 @@
+import { storyblokEditable as storyblokEditableBase, type SbBlokData } from '@storyblok/react'
+
+/**
+ * Wrapper around the upstream `storyblokEditable` that accepts auto-generated Storyblok content
+ * types. The generated types declare `[k: string]: unknown` whereas `SbBlokData` requires a
+ * narrower index signature, so a direct call wouldn't type-check; at runtime the helper only reads
+ * `_editable`, making the cast safe.
+ */
+export function storyblokEditable(blok: { [key: string]: unknown } | undefined | null) {
+  if (!blok) return {}
+  return storyblokEditableBase(blok as unknown as SbBlokData)
+}

package/lib/fetch.ts

@@ -0,0 +1,180 @@
+import type { ApolloClient } from '@graphcommerce/graphql'
+import {
+  getStoryblokApi,
+  type ISbStoriesParams,
+  type ISbStoryData,
+  type SbBlokData,
+} from '@storyblok/react'
+import { resolveStoryblokProducts } from './resolveProducts'
+
+export type StoryblokStory = ISbStoryData<SbBlokData & { body?: SbBlokData[] }>
+
+export type FetchStoryOpts = {
+  preview?: boolean
+  locale?: string
+  defaultLocale?: string
+  /**
+   * Storyblok component-field paths whose UUID references should be hydrated
+   * into full story objects in the response (e.g. `row_button_link_list.links`).
+   */
+  resolveRelations?: string | string[]
+}
+export type FetchStoriesParams = ISbStoriesParams & FetchStoryOpts
+
+const isDev = process.env.NODE_ENV === 'development'
+const STORIES_PER_PAGE = 100
+const MAX_PAGE_CONCURRENCY = 3
+const MAX_RETRIES = 3
+
+/** Extracts the language prefix from a locale string (e.g. `en_US` → `en`). */
+function langPrefix(locale?: string) {
+  return locale?.split(/[-_]/)[0].toLowerCase()
+}
+
+/** Default params applied to every Storyblok CDN request. */
+export const sbParams = (opts: FetchStoryOpts = {}) => {
+  const lang = langPrefix(opts.locale)
+  const defaultLang = langPrefix(opts.defaultLocale)
+  const isDefault = !lang || lang === defaultLang
+
+  const resolveRelations = Array.isArray(opts.resolveRelations)
+    ? opts.resolveRelations.join(',')
+    : opts.resolveRelations
+
+  return {
+    version: (opts.preview || isDev ? 'draft' : 'published') as 'draft' | 'published',
+    // Hydrate `multilink` fields with the linked story's basic info (name,
+    // slug, full_slug). Lighter than `resolve_relations` because it never
+    // includes the linked story's `content.body`.
+    resolve_links: 'story' as const,
+    ...(resolveRelations && { resolve_relations: resolveRelations }),
+    ...(isDev && { cv: Date.now() }),
+    ...(!isDefault && { language: lang }),
+  }
+}
+
+/**
+ * 404s are an expected outcome of "does this slug exist?" lookups, so they're swallowed silently.
+ * Anything else (network failure, auth, malformed response) gets logged in dev so it doesn't look
+ * indistinguishable from a missing story.
+ */
+function logFetchError(label: string, error: unknown) {
+  if (!isDev) return
+  const err = error as { status?: number; message?: string; response?: unknown }
+  if (err?.status === 404) return
+  console.error(`${label} failed [status=${err?.status}]:`, err?.message ?? error)
+  if (err?.response) console.error(`${label} response:`, err.response)
+  if (err?.status === 401) {
+    const api = getStoryblokApi()
+    const client = (api as unknown as { client?: { accessToken?: string; baseURL?: string } })
+      .client
+    console.error(`${label} 401 debug:`, {
+      tokenSet: Boolean(client?.accessToken),
+      tokenPrefix: client?.accessToken?.slice(0, 6),
+      tokenLength: client?.accessToken?.length,
+      baseURL: client?.baseURL,
+    })
+  }
+}
+
+/**
+ * Wraps a Storyblok request and retries on 429, honoring the Retry-After header. Other errors
+ * propagate so the caller's try/catch can decide what to do.
+ */
+async function fetchWithRetry<T>(request: () => Promise<T>, attempt = 0): Promise<T> {
+  try {
+    return await request()
+  } catch (error) {
+    const status = (error as { status?: number })?.status
+    if (status !== 429 || attempt >= MAX_RETRIES) throw error
+    const headers = (error as { headers?: Record<string, string | undefined> })?.headers
+    const retryAfter = Number(headers?.['retry-after']) || 1
+    await new Promise((resolve) => {
+      setTimeout(resolve, retryAfter * 1000)
+    })
+    return fetchWithRetry(request, attempt + 1)
+  }
+}
+
+function storiesRequest(params: FetchStoriesParams, page: number, perPage: number) {
+  const { preview, locale, defaultLocale, ...storyblokParams } = params
+  return fetchWithRetry(() =>
+    getStoryblokApi().get('cdn/stories', {
+      ...sbParams({ preview, locale, defaultLocale }),
+      ...storyblokParams,
+      per_page: perPage,
+      page,
+    }),
+  )
+}
+
+/**
+ * Fetch a single page of stories from the Storyblok CDN and expose the response meta so callers can
+ * render pagination controls. Use this for listing screens.
+ */
+export async function fetchStories(
+  params: FetchStoriesParams,
+): Promise<{ stories: StoryblokStory[]; total: number; perPage: number }> {
+  const perPage = params.per_page ?? STORIES_PER_PAGE
+  const page = params.page ?? 1
+  try {
+    const response = await storiesRequest(params, page, perPage)
+    return {
+      stories: response.data?.stories ?? [],
+      total: response.total ?? 0,
+      perPage,
+    }
+  } catch (error) {
+    logFetchError(`fetchStories(${JSON.stringify(params)})`, error)
+    return { stories: [], total: 0, perPage }
+  }
+}
+
+/**
+ * Fetch every story matching the given params by auto-paginating through all pages with bounded
+ * concurrency. Use this for getStaticPaths-style "give me every slug" queries where pagination
+ * controls aren't needed.
+ */
+export async function fetchAllStories(params: FetchStoriesParams): Promise<StoryblokStory[]> {
+  const perPage = params.per_page ?? STORIES_PER_PAGE
+  try {
+    const first = await storiesRequest(params, 1, perPage)
+    const stories: StoryblokStory[] = first.data?.stories ?? []
+    const totalPages = Math.ceil((first.total ?? stories.length) / perPage)
+    if (totalPages <= 1) return stories
+
+    const remaining = Array.from({ length: totalPages - 1 }, (_, i) => i + 2)
+    for (let i = 0; i < remaining.length; i += MAX_PAGE_CONCURRENCY) {
+      const chunk = remaining.slice(i, i + MAX_PAGE_CONCURRENCY)
+      const results = await Promise.all(chunk.map((p) => storiesRequest(params, p, perPage)))
+      for (const r of results) stories.push(...(r.data?.stories ?? []))
+    }
+    return stories
+  } catch (error) {
+    logFetchError(`fetchAllStories(${JSON.stringify(params)})`, error)
+    return []
+  }
+}
+
+/**
+ * Fetch a single story by slug. When `apolloClient` is provided, resolves product data for
+ * row_product bloks.
+ */
+export async function fetchStory(
+  slug: string,
+  opts?: FetchStoryOpts,
+  apolloClient?: ApolloClient,
+): Promise<{ data: { story: StoryblokStory } | null }> {
+  try {
+    const result = await fetchWithRetry(() =>
+      getStoryblokApi().get(`cdn/stories/${slug}`, sbParams(opts)),
+    )
+    if (apolloClient && result.data?.story?.content?.body) {
+      await resolveStoryblokProducts(result.data.story.content.body, apolloClient)
+    }
+    return result
+  } catch (error) {
+    logFetchError(`fetchStory('${slug}')`, error)
+    return { data: null }
+  }
+}

package/lib/getStoryblokStaticPaths.ts

@@ -0,0 +1,39 @@
+import type { GetStaticPathsResult } from 'next'
+import { fetchAllStories } from './fetch'
+
+type FilterQuery = Record<string, Record<string, string>>
+
+export type GetStoryblokStaticPathsOptions = {
+  /**
+   * Storyblok component name to filter by. Defaults to `'page'` so the result
+   * mirrors how the storefront routes content stories.
+   */
+  contentType?: string
+  /** Storyblok filter_query — see https://www.storyblok.com/docs/api/content-delivery/v2#filter-queries */
+  filterQuery?: FilterQuery
+  /** Override the page size of the underlying CDN request. */
+  pageSize?: number
+}
+
+/**
+ * Fetch all Storyblok stories matching the given filters and return them as
+ * Next.js static paths. Used by sitemap and `getStaticPaths` for content
+ * routes.
+ */
+export async function getStoryblokStaticPaths(
+  locale: string,
+  options: GetStoryblokStaticPathsOptions = {},
+): Promise<GetStaticPathsResult<{ url: string[] }>['paths']> {
+  const { contentType = 'page', filterQuery, pageSize = 100 } = options
+
+  const stories = await fetchAllStories({
+    per_page: pageSize,
+    content_type: contentType,
+    ...(filterQuery && { filter_query: filterQuery }),
+    locale,
+  })
+
+  return stories
+    .filter((story) => Boolean(story.full_slug))
+    .map((story) => ({ params: { url: story.full_slug.split('/') }, locale }))
+}

package/lib/index.ts

@@ -0,0 +1,7 @@
+export * from './editable'
+export * from './fetch'
+export * from './getStoryblokStaticPaths'
+export * from './multilinkHref'
+export * from './resolveProducts'
+export * from './usePreventEditorNavigation'
+export * from './useStoryblokState'

package/lib/multilinkHref.ts

@@ -0,0 +1,28 @@
+/**
+ * Storyblok `multilink` field shape, covering the properties we read across
+ * all link types (story / url / email / asset). All fields are optional
+ * because unset multilinks may serialize as an empty object.
+ */
+export type StoryblokMultilink = {
+  id?: string
+  url?: string
+  email?: string
+  cached_url?: string
+  linktype?: 'story' | 'url' | 'email' | 'asset'
+  story?: { name?: string; full_slug?: string; uuid?: string }
+}
+
+/**
+ * Extracts a usable href from a Storyblok `multilink` field. Accepts
+ * `cached_url` first (the editor-friendly short path), then `url`, then
+ * `email` (prefixed with `mailto:` if not already). Returns an empty string
+ * for unset or empty links so callers can pass it straight to `href` without
+ * a nullish check.
+ */
+export function multilinkHref(link?: StoryblokMultilink | null): string {
+  if (!link) return ''
+  if (link.cached_url) return link.cached_url
+  if (link.url) return link.url
+  if (link.email) return link.email.startsWith('mailto:') ? link.email : `mailto:${link.email}`
+  return ''
+}

package/lib/resolveProducts.ts

@@ -0,0 +1,88 @@
+import type { ApolloClient } from '@graphcommerce/graphql'
+import { ProductListDocument, type ProductListItemsFragment } from '@graphcommerce/magento-product'
+import type { SbBlokData } from '@storyblok/react'
+
+type RowProductBlok = SbBlokData & {
+  component: 'row_product'
+  magento_product_skus?: string
+  magento_category_id?: string
+  items?: ProductListItemsFragment['items']
+}
+
+function findRowProductBloks(bloks: SbBlokData[]): RowProductBlok[] {
+  const results: RowProductBlok[] = []
+  for (const blok of bloks) {
+    if (blok.component === 'row_product') {
+      results.push(blok as RowProductBlok)
+    }
+    for (const value of Object.values(blok)) {
+      if (Array.isArray(value) && value.length > 0 && value[0]?._uid) {
+        results.push(...findRowProductBloks(value as SbBlokData[]))
+      }
+    }
+  }
+  return results
+}
+
+/** Mutates row_product bloks in-place, attaching fetched product `items` directly onto each blok. */
+export async function resolveStoryblokProducts(
+  body: SbBlokData[] | undefined,
+  staticClient: ApolloClient,
+) {
+  if (!body) return
+
+  const bloks = findRowProductBloks(body)
+  if (bloks.length === 0) return
+
+  const skusByBlok = new Map<RowProductBlok, string[]>()
+  const allSkus = new Set<string>()
+
+  const categoryByBlok = new Map<RowProductBlok, string>()
+  const allCategoryIds = new Set<string>()
+
+  for (const blok of bloks) {
+    const skus = blok.magento_product_skus
+      ?.split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
+
+    if (skus?.length) {
+      skusByBlok.set(blok, skus)
+      skus.forEach((sku) => allSkus.add(sku))
+    } else if (blok.magento_category_id) {
+      categoryByBlok.set(blok, blok.magento_category_id)
+      allCategoryIds.add(blok.magento_category_id)
+    }
+  }
+
+  const skuItemsMap = new Map<string, NonNullable<ProductListItemsFragment['items']>[number]>()
+  if (allSkus.size > 0) {
+    const { data } = await staticClient.query({
+      query: ProductListDocument,
+      variables: { onlyItems: true, filters: { sku: { in: [...allSkus] } } },
+    })
+    for (const item of data?.products?.items ?? []) {
+      if (item?.sku) skuItemsMap.set(item.sku, item)
+    }
+  }
+
+  const categoryItemsMap = new Map<string, ProductListItemsFragment['items']>()
+  await Promise.all(
+    [...allCategoryIds].map(async (categoryId) => {
+      const { data } = await staticClient.query({
+        query: ProductListDocument,
+        variables: { onlyItems: true, filters: { category_uid: { eq: categoryId } } },
+      })
+      categoryItemsMap.set(categoryId, data?.products?.items ?? [])
+    }),
+  )
+
+  for (const [blok, skus] of skusByBlok) {
+    blok.items = skus
+      .map((sku) => skuItemsMap.get(sku))
+      .filter((item): item is NonNullable<typeof item> => item != null)
+  }
+  for (const [blok, categoryId] of categoryByBlok) {
+    blok.items = categoryItemsMap.get(categoryId) ?? []
+  }
+}

package/lib/usePreventEditorNavigation.ts

@@ -0,0 +1,27 @@
+import { useEffect } from 'react'
+
+/**
+ * Prevents link navigation while the page is loaded inside the Storyblok
+ * Visual Editor iframe (detected via the `_storyblok` query param). Editors
+ * expect a click on a blok to open the field editor, not follow the link.
+ *
+ * Storyblok's own `preventClicks` bridge option is broken upstream
+ * (storyblok/monoblok#82), hence this capture-phase workaround.
+ *
+ * Call this once from a component that renders on every page (e.g. a provider
+ * that wraps your app) so pages that don't use `useStoryblokState` — such as
+ * checkout or the global config page — are also covered.
+ */
+export function usePreventEditorNavigation() {
+  useEffect(() => {
+    if (typeof window === 'undefined') return undefined
+    if (!new URLSearchParams(window.location.search).has('_storyblok')) return undefined
+
+    const onClick = (event: MouseEvent) => {
+      const target = event.target as HTMLElement | null
+      if (target?.closest('a')) event.preventDefault()
+    }
+    document.addEventListener('click', onClick, { capture: true })
+    return () => document.removeEventListener('click', onClick, { capture: true })
+  }, [])
+}

package/lib/useStoryblokState.ts

@@ -0,0 +1,68 @@
+import { useApolloClient } from '@graphcommerce/graphql'
+import {
+  useStoryblokState as useStoryblokStateBase,
+  type ISbStoryData,
+  type SbBlokData,
+} from '@storyblok/react'
+import { useEffect, useRef, useState } from 'react'
+import { resolveStoryblokProducts } from './resolveProducts'
+
+export type UseStoryblokStateOptions = {
+  /**
+   * Skip the bridge subscription and client-side product resolution. Pass
+   * `true` outside the Storyblok Visual Editor — `initialStory` is already
+   * fully resolved by `fetchStory` in `getStaticProps`.
+   */
+  skip?: boolean
+}
+
+/**
+ * Wraps `useStoryblokState` and resolves product data for `row_product` bloks client-side. This
+ * enables live product previews in the Storyblok visual editor when `magento_product_skus` or
+ * `magento_category_id` fields are changed.
+ *
+ * The generic `T` lets the caller narrow the returned `content` to an auto-generated Storyblok
+ * content type. The runtime check guards against feeding in a story whose content isn't a `page`.
+ */
+export function useStoryblokState<T = SbBlokData>(
+  initialStory: ISbStoryData | null,
+  options: UseStoryblokStateOptions = {},
+): ISbStoryData<T> | null {
+  const { skip = false } = options
+  const story = useStoryblokStateBase(initialStory, { resolveLinks: 'story' })
+  const client = useApolloClient()
+  const [resolvedStory, setResolvedStory] = useState(story)
+  const prevStoryRef = useRef(story)
+
+  useEffect(() => {
+    if (skip) return
+    if (prevStoryRef.current === story) return
+    prevStoryRef.current = story
+
+    const body = (story?.content as { body?: unknown[] } | undefined)?.body
+    if (!body) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setResolvedStory(story)
+      return
+    }
+
+    const cloned = JSON.parse(JSON.stringify(story)) as typeof story
+    resolveStoryblokProducts((cloned!.content as { body: never }).body, client).then(() =>
+      setResolvedStory(cloned),
+    )
+  }, [skip, story, client])
+
+  const finalStory = skip ? initialStory : resolvedStory
+
+  if (!finalStory) return null
+  if (finalStory.content?.component === 'page') {
+    return finalStory as ISbStoryData<T>
+  }
+
+  if (process.env.NODE_ENV === 'development') {
+    throw new Error(
+      `useStoryblokState: expected story content of type 'page' but got '${finalStory.content?.component}' for slug '${finalStory.full_slug}'. Use the upstream @storyblok/react useStoryblokState for non-page content.`,
+    )
+  }
+  return null
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@graphcommerce/storyblok-ui",
+  "homepage": "https://www.graphcommerce.org/",
+  "repository": "github:graphcommerce-org/graphcommerce",
+  "version": "10.1.0-canary.4",
+  "sideEffects": false,
+  "prettier": "@graphcommerce/prettier-config-pwa",
+  "eslintConfig": {
+    "extends": "@graphcommerce/eslint-config-pwa",
+    "parserOptions": {
+      "project": "./tsconfig.json"
+    }
+  },
+  "peerDependencies": {
+    "@graphcommerce/eslint-config-pwa": "^10.1.0-canary.4",
+    "@graphcommerce/graphql": "^10.1.0-canary.4",
+    "@graphcommerce/image": "^10.1.0-canary.4",
+    "@graphcommerce/magento-product": "^10.1.0-canary.4",
+    "@graphcommerce/next-ui": "^10.1.0-canary.4",
+    "@graphcommerce/prettier-config-pwa": "^10.1.0-canary.4",
+    "@graphcommerce/typescript-config-pwa": "^10.1.0-canary.4",
+    "@mui/material": "^7.0.0",
+    "@storyblok/react": "^6.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "exports": {
+    ".": "./index.ts"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "exclude": ["**/node_modules", "**/.*/"],
+  "include": ["**/*.ts", "**/*.tsx"],
+  "extends": "@graphcommerce/typescript-config-pwa/nextjs.json"
+}

package/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Storyblok asset data. Matches the structure generated by the Storyblok CLI
+ * but defined here so the package is independent of generated types.
+ *
+ * Dimensions and asset type are parsed from the `filename` URL at render time
+ * since Storyblok encodes them in the URL path
+ * (`//a.storyblok.com/f/{space}/{width}x{height}/{hash}/{file}`).
+ */
+export interface StoryblokAssetData {
+  alt?: string | null
+  copyright?: string | null
+  fieldtype?: 'asset'
+  id?: number
+  filename: string | null
+  name?: string
+  title?: string | null
+  focus?: string | null
+  meta_data?: Record<string, unknown>
+  source?: string | null
+  is_external_url?: boolean
+  is_private?: boolean
+  src?: string
+  updated_at?: string
+  width?: number | null
+  height?: number | null
+  aspect_ratio?: number | null
+  public_id?: string | null
+  content_type?: string
+}
+
+/**
+ * Storyblok rich text node. Matches the structure generated by the Storyblok
+ * CLI and the Storyblok rich text field output.
+ */
+export interface StoryblokRichtextData {
+  type: string
+  content?: StoryblokRichtextData[]
+  marks?: StoryblokRichtextData[]
+  attrs?: Record<string, unknown>
+  text?: string
+}
+
+/**
+ * Utility type that strips the `[k: string]: unknown` index signature from
+ * Storyblok CLI-generated component types, giving you clean property access.
+ *
+ * @example
+ * ```ts
+ * import type { StoryblokRowHeroBanner } from '.storyblok/types/…/storyblok-components'
+ * type CleanHeroBanner = StoryblokBlokProps<StoryblokRowHeroBanner>
+ * // { asset?: StoryblokAsset; copy?: StoryblokRichtext; … }
+ * ```
+ */
+export type StoryblokBlokProps<T> = {
+  [K in keyof T as string extends K ? never : K]: T[K]
+}

package/utils.ts

@@ -0,0 +1,28 @@
+export const VIDEO_EXTENSIONS = new Set(['mp4', 'webm', 'ogg', 'mov', 'avi'])
+export const SVG_EXTENSIONS = new Set(['svg'])
+
+export function getExtension(filename: string): string {
+  const clean = filename.split('?')[0].split('#')[0]
+  const dot = clean.lastIndexOf('.')
+  return dot >= 0 ? clean.slice(dot + 1).toLowerCase() : ''
+}
+
+/**
+ * Storyblok encodes image dimensions in the asset URL:
+ * `//a.storyblok.com/f/{space}/{width}x{height}/{hash}/{filename}`
+ */
+export function parseDimensions(filename: string): { width: number; height: number } | null {
+  const match = filename.match(/\/(\d+)x(\d+)\//)
+  if (!match) return null
+  const width = Number(match[1])
+  const height = Number(match[2])
+  return width > 0 && height > 0 ? { width, height } : null
+}
+
+export function isVideo(filename: string): boolean {
+  return VIDEO_EXTENSIONS.has(getExtension(filename))
+}
+
+export function isSvg(filename: string): boolean {
+  return SVG_EXTENSIONS.has(getExtension(filename))
+}