@laconius/cms 0.1.0

package/src/adapter.ts

@@ -0,0 +1,159 @@
+import {
+  absolutizeMedia,
+  getMediaBaseUrl,
+  type Converter,
+  type LaconiusRuntime,
+} from '@laconius/core';
+
+import type { CmsComponent, CmsStructure, PageContext } from './models';
+import { HOME_PAGE_CONTEXT } from './models';
+import { normalizeCmsPage, type OccCmsPage } from './normalizer';
+
+/** OCC's own ceiling for one `componentIds` request. */
+export const MAX_COMPONENTS_PER_REQUEST = 50;
+
+/** How long ids collect before a batch goes out. One frame is enough to catch a whole slot. */
+const BATCH_WINDOW_MS = 10;
+
+export type CmsAdapter = {
+  loadPage(runtime: LaconiusRuntime, context: PageContext): Promise<CmsStructure>;
+  loadComponents(
+    runtime: LaconiusRuntime,
+    ids: string[],
+    context?: PageContext,
+  ): Promise<CmsComponent[]>;
+};
+
+/**
+ * `users/{userId}/cms/*` is the default; `capabilities.userScopedCms: false` selects the legacy
+ * unscoped form through the endpoint's `legacy` scope ([chapter 03](../../../docs/spec/03-occ-layer.md)).
+ */
+function scopeFor(runtime: LaconiusRuntime): string {
+  return runtime.config.capabilities?.userScopedCms === false ? 'legacy' : 'default';
+}
+
+/**
+ * OCC queries pages by a combination of type, label and code: a `ContentPage` by
+ * `pageLabelOrId`, everything else by `code`. The homepage sentinel sends no params at all —
+ * that is how the backend is asked for "whatever the base site's homepage is".
+ */
+function pageParams(context: PageContext): Record<string, string | undefined> {
+  if (context.id === HOME_PAGE_CONTEXT) return {};
+  return {
+    pageType: context.type,
+    ...(context.type === 'ContentPage' || !context.type
+      ? { pageLabelOrId: context.id }
+      : { code: context.id }),
+  };
+}
+
+/** Product and category pages scope their components; content pages do not. */
+function componentParams(context?: PageContext): Record<string, string | undefined> {
+  if (context?.type === 'ProductPage') return { productCode: context.id };
+  if (context?.type === 'CategoryPage') return { categoryCode: context.id };
+  if (context?.type === 'CatalogPage') return { catalogCode: context.id };
+  return {};
+}
+
+export const defaultCmsAdapter: CmsAdapter = {
+  async loadPage(runtime, context) {
+    const scope = scopeFor(runtime);
+    // The homepage sentinel is not an id: `cms/pages/__HOMEPAGE__` is a 400, and `cmsPage` is
+    // configured by default, so without this the sentinel branch of `pageParams` is unreachable.
+    const useById =
+      context.id !== HOME_PAGE_CONTEXT &&
+      !context.type &&
+      runtime.client.endpoints.isConfigured('cmsPage', scope);
+    const payload = await runtime.client.request<OccCmsPage>({
+      endpoint: useById ? 'cmsPage' : 'cmsPages',
+      scope,
+      urlParams: useById ? { id: context.id } : undefined,
+      queryParams: useById ? undefined : pageParams(context),
+    });
+    const structure = runtime.converters.convert<OccCmsPage, CmsStructure>(payload, 'cmsPage');
+    return absolutizeMedia(structure, getMediaBaseUrl(runtime.config));
+  },
+
+  async loadComponents(runtime, ids, context) {
+    const response = await runtime.client.request<{ component?: unknown[] }>({
+      endpoint: 'cmsComponents',
+      scope: scopeFor(runtime),
+      queryParams: {
+        componentIds: ids.join(','),
+        pageSize: ids.length,
+        currentPage: 0,
+        ...componentParams(context),
+      },
+    });
+    const components = runtime.converters.convertAll<unknown, CmsComponent>(
+      response?.component,
+      'cmsComponent',
+    );
+    return absolutizeMedia(components, getMediaBaseUrl(runtime.config));
+  },
+};
+
+export function cmsAdapter(runtime: LaconiusRuntime): CmsAdapter {
+  return { ...defaultCmsAdapter, ...runtime.config.backend.adapters?.cms };
+}
+
+type Pending = {
+  uid: string;
+  resolve: (component: CmsComponent) => void;
+  reject: (error: unknown) => void;
+};
+
+let queue: Pending[] = [];
+let timer: ReturnType<typeof setTimeout> | undefined;
+
+/**
+ * Debounce-batched component loading, chunked at OCC's limit.
+ *
+ * A slot with twelve unloaded components issues one request, not twelve — the reason Spartacus
+ * batches too. The batch is keyed by nothing: components are page-independent once the page
+ * context is applied, and the queue only ever lives for one frame.
+ */
+export function loadCmsComponent(
+  runtime: LaconiusRuntime,
+  uid: string,
+  context?: PageContext,
+): Promise<CmsComponent> {
+  return new Promise<CmsComponent>((resolve, reject) => {
+    queue.push({ uid, resolve, reject });
+    timer ??= setTimeout(() => {
+      const batch = queue;
+      queue = [];
+      timer = undefined;
+      void flush(runtime, batch, context);
+    }, BATCH_WINDOW_MS);
+  });
+}
+
+async function flush(
+  runtime: LaconiusRuntime,
+  batch: Pending[],
+  context?: PageContext,
+): Promise<void> {
+  const ids = [...new Set(batch.map((entry) => entry.uid))];
+  for (let index = 0; index < ids.length; index += MAX_COMPONENTS_PER_REQUEST) {
+    const chunk = ids.slice(index, index + MAX_COMPONENTS_PER_REQUEST);
+    const waiting = batch.filter((entry) => chunk.includes(entry.uid));
+    try {
+      const components = await cmsAdapter(runtime).loadComponents(runtime, chunk, context);
+      const byUid = new Map(components.map((component) => [component.uid, component]));
+      for (const entry of waiting) {
+        const component = byUid.get(entry.uid);
+        if (component) entry.resolve(component);
+        else entry.reject(new Error(`[laconius] CMS component "${entry.uid}" was not returned.`));
+      }
+    } catch (error) {
+      for (const entry of waiting) entry.reject(error);
+    }
+  }
+}
+
+/** Converters are registered by explicit spread, so a default can be dropped by not spreading it. */
+export const defaultCmsConverters = {
+  cmsPage: [normalizeCmsPage as Converter<OccCmsPage, CmsStructure>],
+  cmsComponent: [] as Converter<unknown, CmsComponent>[],
+};

package/src/config.ts

@@ -0,0 +1,119 @@
+import type { LaconiusConfigChunk } from '@laconius/core';
+import type { ComponentType } from 'react';
+
+import { defaultCmsConverters, type CmsAdapter } from './adapter';
+import {
+  CmsBanner,
+  CmsBannerCarousel,
+  CmsLink,
+  CmsNavigation,
+  CmsParagraph,
+} from './defaults';
+import type { CmsLinkTarget } from './models';
+
+/** The registry value. Spartacus' `guards`, `i18nKeys`, `deferLoading` and `childRoutes` are dropped. */
+export type CmsComponentMapping = { component: ComponentType<any> };
+
+declare module '@laconius/ui' {
+  /** The CMS defaults are replaceable through the UI registry like every other component. */
+  interface LaconiusUiComponents {
+    Banner: unknown;
+    Link: unknown;
+    Paragraph: unknown;
+    NavigationList: unknown;
+    Carousel: unknown;
+  }
+}
+
+declare module '@laconius/core' {
+  interface LaconiusCmsConfig {
+    /**
+     * Backend type code -> component. The key space is **open**, unlike `ui.components`: these
+     * keys are whatever the content catalog contains
+     * ([ADR-0007](../../../docs/adr/0007-two-registries-two-contracts.md)).
+     */
+    components?: Record<string, CmsComponentMapping>;
+    /** Slot order per page template. Client configuration, not backend data. */
+    layouts?: Record<string, { slots: string[] }>;
+    /** Where a pressed CMS link goes. Without it, the default components warn and do nothing. */
+    onNavigate?: (target: CmsLinkTarget) => void;
+  }
+
+  interface LaconiusEndpoints {
+    cmsPages: string | Record<string, string>;
+    cmsPage: string | Record<string, string>;
+    cmsComponents: string | Record<string, string>;
+    cmsComponent: string | Record<string, string>;
+  }
+
+  interface LaconiusConverters {
+    cmsPage: unknown;
+    cmsComponent: unknown;
+  }
+
+  interface LaconiusAdapters {
+    cms: CmsAdapter;
+  }
+}
+
+/**
+ * The `default` scope is the user-scoped form, mandatory from 221121.7; `legacy` is selected by
+ * `capabilities.userScopedCms: false` ([chapter 03](../../../docs/spec/03-occ-layer.md)).
+ */
+export const defaultCmsEndpoints = {
+  cmsPages: {
+    default: 'users/${userId}/cms/pages',
+    legacy: 'cms/pages',
+  },
+  cmsPage: {
+    default: 'users/${userId}/cms/pages/${id}',
+    legacy: 'cms/pages/${id}',
+  },
+  cmsComponents: {
+    default: 'users/${userId}/cms/components?fields=DEFAULT',
+    legacy: 'cms/components?fields=DEFAULT',
+  },
+  cmsComponent: {
+    default: 'users/${userId}/cms/components/${id}',
+    legacy: 'cms/components/${id}',
+  },
+};
+
+/**
+ * Tier-1 content types. `@laconius/product`, `@laconius/cart` and `@laconius/user` register the
+ * ones that read their domain data, through this same chunk.
+ */
+export const defaultCmsComponents: Record<string, CmsComponentMapping> = {
+  SimpleBannerComponent: { component: CmsBanner },
+  BannerComponent: { component: CmsBanner },
+  SimpleResponsiveBannerComponent: { component: CmsBanner },
+  CMSLinkComponent: { component: CmsLink },
+  CMSParagraphComponent: { component: CmsParagraph },
+  CMSTabParagraphComponent: { component: CmsParagraph },
+  NavigationComponent: { component: CmsNavigation },
+  FooterNavigationComponent: { component: CmsNavigation },
+  CategoryNavigationComponent: { component: CmsNavigation },
+  RotatingImagesComponent: { component: CmsBannerCarousel },
+};
+
+/**
+ * Slot order for the stock templates, ported from
+ * `core-libs/storefront/recipes/config/layout-config.ts:32` minus the web chrome slots (header,
+ * navigation, footer) — the app's chrome is native. `app-site.impex` adds its own templates at M7.
+ */
+export const defaultCmsLayouts: Record<string, { slots: string[] }> = {
+  LandingPage2Template: {
+    slots: ['Section1', 'Section2A', 'Section2B', 'Section2C', 'Section3', 'Section4', 'Section5'],
+  },
+  ContentPage1Template: { slots: ['Section2A', 'Section2B'] },
+  CategoryPageTemplate: { slots: ['Section1', 'Section2', 'Section3'] },
+  ProductDetailsPageTemplate: { slots: ['Summary', 'Tabs', 'UpSelling', 'CrossSelling'] },
+  SearchResultsListPageTemplate: { slots: ['Section2', 'SearchResultsListSlot', 'Section4'] },
+  CartPageTemplate: { slots: ['TopContent', 'CenterRightContentSlot', 'EmptyCartMiddleContent'] },
+};
+
+export const defaultCmsConfig: LaconiusConfigChunk = {
+  backend: { occ: { endpoints: defaultCmsEndpoints } },
+  cms: { components: defaultCmsComponents, layouts: defaultCmsLayouts },
+  converters: defaultCmsConverters,
+};

package/src/defaults.tsx

@@ -0,0 +1,281 @@
+import { useLaconiusConfig, type MediaContainer } from '@laconius/core';
+import { Media, Text, useStyles, useTheme, useUiComponent, type Theme } from '@laconius/ui';
+import { useCallback } from 'react';
+import {
+  FlatList,
+  Pressable,
+  StyleSheet,
+  View,
+  type StyleProp,
+  type TextStyle,
+  type ViewStyle,
+} from 'react-native';
+
+import type {
+  CmsBannerData,
+  CmsCarouselData,
+  CmsLinkData,
+  CmsLinkTarget,
+  CmsNavigationData,
+  CmsNavigationNode,
+  CmsParagraphData,
+} from './models';
+import { resolveLinkTarget, stripHtml } from './normalizer';
+import { CmsComponentByUid, useCmsComponentData } from './page';
+
+const warned = new Set<string>();
+
+function warnOnce(message: string): void {
+  if (process.env.NODE_ENV === 'production' || warned.has(message)) return;
+  warned.add(message);
+  console.warn(`[laconius] ${message}`);
+}
+
+/**
+ * Where a CMS link goes. No Laconius package imports `expo-router` or navigates
+ * ([chapter 01](../../../docs/spec/01-packages.md)), so the app hands the engine one function and
+ * keeps its own routing.
+ */
+export function useCmsNavigate(): (target: CmsLinkTarget | undefined) => void {
+  const config = useLaconiusConfig();
+  const onNavigate = config.cms?.onNavigate;
+  return useCallback(
+    (target) => {
+      if (!target) return;
+      if (!onNavigate) {
+        warnOnce('A CMS link was pressed but cms.onNavigate is not configured; nothing happened.');
+        return;
+      }
+      onNavigate(target);
+    },
+    [onNavigate],
+  );
+}
+
+/** HTML with no DOM: the configured renderer, or tags stripped to a `<Text>`. */
+export function CmsHtml({ html, style }: { html?: string; style?: StyleProp<TextStyle> }) {
+  const config = useLaconiusConfig();
+  const Renderer = config.cms?.htmlRenderer;
+  if (!html) return null;
+  if (Renderer) return <Renderer html={html} />;
+  return <Text style={style}>{stripHtml(html)}</Text>;
+}
+
+/* ------------------------------------------------------------------ presentational primitives */
+
+export type BannerProps = {
+  title?: string;
+  subtitle?: string;
+  media?: MediaContainer;
+  onPress?: () => void;
+  style?: StyleProp<ViewStyle>;
+  styles?: { container?: StyleProp<ViewStyle>; title?: StyleProp<TextStyle> };
+};
+
+export function Banner({ title, subtitle, media, onPress, style, styles }: BannerProps) {
+  const sheet = useStyles(createStyles);
+  const body = (
+    <View style={[sheet.banner, styles?.container, style]}>
+      {media ? <Media media={media} mediaRole="product" aspectRatio="banner" decorative={!title} /> : null}
+      {title ? (
+        <Text variant="subheading" style={[sheet.bannerTitle, styles?.title]}>
+          {title}
+        </Text>
+      ) : null}
+      {subtitle ? <Text muted>{stripHtml(subtitle)}</Text> : null}
+    </View>
+  );
+  if (!onPress) return body;
+  return (
+    <Pressable onPress={onPress} accessibilityRole="button" accessibilityLabel={title}>
+      {body}
+    </Pressable>
+  );
+}
+
+export type LinkProps = {
+  label: string;
+  onPress?: () => void;
+  style?: StyleProp<ViewStyle>;
+};
+
+export function Link({ label, onPress, style }: LinkProps) {
+  const sheet = useStyles(createStyles);
+  return (
+    <Pressable
+      onPress={onPress}
+      style={[sheet.link, style]}
+      accessibilityRole="link"
+      accessibilityLabel={label}
+      hitSlop={8}
+    >
+      <Text variant="label">{label}</Text>
+    </Pressable>
+  );
+}
+
+export type ParagraphProps = {
+  title?: string;
+  /** HTML, as OCC stores it. */
+  content?: string;
+  style?: StyleProp<ViewStyle>;
+};
+
+export function Paragraph({ title, content, style }: ParagraphProps) {
+  const sheet = useStyles(createStyles);
+  return (
+    <View style={[sheet.paragraph, style]}>
+      {title ? <Text variant="subheading">{title}</Text> : null}
+      <CmsHtml html={content} />
+    </View>
+  );
+}
+
+export type NavigationListProps = {
+  node?: CmsNavigationNode;
+  onSelect?: (node: CmsNavigationNode) => void;
+  style?: StyleProp<ViewStyle>;
+};
+
+/**
+ * One level of a navigation tree. Deeper trees are app chrome — a drawer, a tab bar — built from
+ * `useCmsNavigation(uid)`, which is why this default stays a flat list.
+ */
+export function NavigationList({ node, onSelect, style }: NavigationListProps) {
+  const sheet = useStyles(createStyles);
+  const children = node?.children ?? [];
+  if (children.length === 0) return null;
+  return (
+    <View style={[sheet.navigation, style]}>
+      {children.map((child, index) => (
+        <Link
+          key={child.uid ?? index}
+          label={child.title ?? ''}
+          onPress={onSelect ? () => onSelect(child) : undefined}
+        />
+      ))}
+    </View>
+  );
+}
+
+export type CarouselProps<T> = {
+  items: T[];
+  renderItem: (item: T, index: number) => React.ReactElement | null;
+  itemWidth?: number;
+  title?: string;
+  style?: StyleProp<ViewStyle>;
+};
+
+/** A horizontal `FlatList` with snapping. The first thing to cut if it proves expensive. */
+export function Carousel<T>({ items, renderItem, itemWidth, title, style }: CarouselProps<T>) {
+  const theme = useTheme();
+  const sheet = useStyles(createStyles);
+  return (
+    <View style={style}>
+      {title ? (
+        <Text variant="subheading" style={sheet.carouselTitle}>
+          {title}
+        </Text>
+      ) : null}
+      <FlatList
+        horizontal
+        data={items}
+        keyExtractor={(_item, index) => String(index)}
+        renderItem={({ item, index }) => (
+          <View style={itemWidth === undefined ? undefined : { width: itemWidth }}>
+            {renderItem(item, index)}
+          </View>
+        )}
+        showsHorizontalScrollIndicator={false}
+        snapToInterval={itemWidth}
+        decelerationRate="fast"
+        contentContainerStyle={{ gap: theme.spacing.md, paddingHorizontal: theme.spacing.md }}
+      />
+    </View>
+  );
+}
+
+/* ------------------------------------------------------------------------- the CMS wrappers */
+
+export function CmsBanner() {
+  const data = useCmsComponentData<CmsBannerData>();
+  const navigate = useCmsNavigate();
+  const target = resolveLinkTarget(data);
+  const Component = useUiComponent<BannerProps>('Banner', Banner);
+  return (
+    <Component
+      title={data.headline ? stripHtml(data.headline) : undefined}
+      subtitle={data.content}
+      media={data.media}
+      onPress={target ? () => navigate(target) : undefined}
+    />
+  );
+}
+
+export function CmsLink() {
+  const data = useCmsComponentData<CmsLinkData>();
+  const navigate = useCmsNavigate();
+  const target = resolveLinkTarget(data);
+  const Component = useUiComponent<LinkProps>('Link', Link);
+  return (
+    <Component
+      label={data.linkName ?? data.name ?? ''}
+      onPress={target ? () => navigate(target) : undefined}
+    />
+  );
+}
+
+export function CmsParagraph() {
+  const data = useCmsComponentData<CmsParagraphData>();
+  const Component = useUiComponent<ParagraphProps>('Paragraph', Paragraph);
+  return <Component title={data.title} content={data.content} />;
+}
+
+export function CmsNavigation() {
+  const data = useCmsComponentData<CmsNavigationData>();
+  const navigate = useCmsNavigate();
+  const Component = useUiComponent<NavigationListProps>('NavigationList', NavigationList);
+  return (
+    <Component
+      node={data.navigationNode}
+      onSelect={(node) => navigate(entryTarget(node))}
+    />
+  );
+}
+
+/**
+ * A navigation node points at a page through its first entry: `itemId` plus an `itemSuperType`
+ * that says what kind of thing it is.
+ */
+function entryTarget(node: CmsNavigationNode): CmsLinkTarget | undefined {
+  const entry = node.entries?.[0];
+  if (!entry?.itemId) return undefined;
+  if (entry.itemSuperType === 'AbstractPage') return { kind: 'contentPage', label: entry.itemId };
+  if (entry.itemSuperType === 'Product') return { kind: 'product', code: entry.itemId };
+  if (entry.itemSuperType === 'Category') return { kind: 'category', code: entry.itemId };
+  return undefined;
+}
+
+export function CmsBannerCarousel() {
+  const data = useCmsComponentData<CmsCarouselData>();
+  const Component = useUiComponent<CarouselProps<string>>('Carousel', Carousel);
+  const uids = (data.banners ?? '').split(' ').filter(Boolean);
+  if (uids.length === 0) return null;
+  return (
+    <Component
+      items={uids}
+      itemWidth={280}
+      renderItem={(uid) => <CmsComponentByUid uid={uid} />}
+    />
+  );
+}
+
+const createStyles = (theme: Theme) =>
+  StyleSheet.create({
+    banner: { gap: theme.spacing.sm, padding: theme.spacing.md },
+    bannerTitle: { marginTop: theme.spacing.xs },
+    link: { paddingVertical: theme.spacing.sm, minHeight: 44, justifyContent: 'center' },
+    paragraph: { gap: theme.spacing.sm, padding: theme.spacing.md },
+    navigation: { paddingHorizontal: theme.spacing.md },
+    carouselTitle: { paddingHorizontal: theme.spacing.md, marginBottom: theme.spacing.sm },
+  });

package/src/index.ts

@@ -0,0 +1,82 @@
+export {
+  HOME_PAGE_CONTEXT,
+  type CmsBannerData,
+  type CmsCarouselData,
+  type CmsComponent,
+  type CmsLinkData,
+  type CmsLinkTarget,
+  type CmsNavigationData,
+  type CmsNavigationNode,
+  type CmsPageStructure,
+  type CmsParagraphData,
+  type CmsStructure,
+  type ContentSlot,
+  type ContentSlotComponent,
+  type PageContext,
+  type PageType,
+} from './models';
+
+export {
+  getComponentKey,
+  normalizeCmsPage,
+  resolveLinkTarget,
+  stripHtml,
+  type OccCmsPage,
+} from './normalizer';
+
+export {
+  MAX_COMPONENTS_PER_REQUEST,
+  defaultCmsAdapter,
+  defaultCmsConverters,
+  loadCmsComponent,
+  type CmsAdapter,
+} from './adapter';
+
+export {
+  cmsQueries,
+  useCmsComponent,
+  useCmsNavigation,
+  useCmsPage,
+} from './queries';
+
+export {
+  CmsComponentByUid,
+  CmsComponentOutlet,
+  CmsPage,
+  CmsPageProvider,
+  CmsSlot,
+  useCmsComponentData,
+  useCmsComponentUid,
+  useCmsPageStructure,
+  type CmsPageProps,
+  type CmsPageProviderProps,
+  type CmsSlotProps,
+} from './page';
+
+export {
+  Banner,
+  Carousel,
+  CmsBanner,
+  CmsBannerCarousel,
+  CmsHtml,
+  CmsLink,
+  CmsNavigation,
+  CmsParagraph,
+  Link,
+  NavigationList,
+  Paragraph,
+  useCmsNavigate,
+  type BannerProps,
+  type CarouselProps,
+  type LinkProps,
+  type NavigationListProps,
+  type ParagraphProps,
+} from './defaults';
+
+export {
+  defaultCmsComponents,
+  defaultCmsConfig,
+  defaultCmsEndpoints,
+  defaultCmsLayouts,
+  type CmsComponentMapping,
+} from './config';