@laconius/cms 0.1.0

package/src/models.ts

@@ -0,0 +1,120 @@
+import type { MediaContainer } from '@laconius/core';
+
+/**
+ * CMS models, ported from Spartacus `core-libs/core/src/model/cms.model.ts` and
+ * `core-libs/core/src/cms/model/*` (Apache-2.0, see NOTICE). Divergences:
+ * - `enum` becomes a string union, so this module emits nothing at runtime.
+ * - `CmsStructure.components` is a record keyed by `uid`, not an array: Laconius looks components
+ *   up by uid at render time instead of feeding an NgRx entity reducer.
+ * - `robots` and the rest of the SEO emitters are dropped ([chapter 06](../../../docs/spec/06-cms-engine.md)).
+ */
+
+export type PageType = 'ContentPage' | 'ProductPage' | 'CategoryPage' | 'CatalogPage';
+
+/** The sentinel the backend answers to for the base site's homepage. */
+export const HOME_PAGE_CONTEXT = '__HOMEPAGE__';
+
+/** What identifies a page to OCC: a content-page label, or a product / category code. */
+export type PageContext = { id: string; type?: PageType };
+
+/** The component reference a slot carries. `key` is the *computed* registry key. */
+export type ContentSlotComponent = {
+  uid: string;
+  typeCode?: string;
+  /** `flexType` for `CMSFlexComponent`, `uid` for `JspIncludeComponent`, else `typeCode`. */
+  key: string;
+  properties?: Record<string, unknown>;
+};
+
+export type ContentSlot = {
+  position: string;
+  properties?: Record<string, unknown>;
+  components: ContentSlotComponent[];
+};
+
+export type CmsPageStructure = {
+  pageId?: string;
+  name?: string;
+  type?: string;
+  label?: string;
+  template?: string;
+  title?: string;
+  description?: string;
+  properties?: Record<string, unknown>;
+  /** Keyed by position. Order here is backend order — the warned fallback, not the contract. */
+  slots: Record<string, ContentSlot>;
+};
+
+/** What the page endpoint normalizes to: the structure plus whatever component data came inlined. */
+export type CmsStructure = {
+  page: CmsPageStructure;
+  components: Record<string, CmsComponent>;
+};
+
+/** Every component payload carries these; the rest is per type. */
+export interface CmsComponent {
+  uid?: string;
+  typeCode?: string;
+  name?: string;
+  modifiedTime?: string;
+  container?: string;
+  styleClasses?: string;
+  composition?: { inner?: string[] };
+  [key: string]: unknown;
+}
+
+export interface CmsLinkData extends CmsComponent {
+  linkName?: string;
+  url?: string;
+  external?: string | boolean;
+  contentPage?: string;
+  contentPageLabelOrId?: string;
+  target?: string | boolean;
+}
+
+export interface CmsBannerData extends CmsComponent {
+  headline?: string;
+  content?: string;
+  /** A single image, or a group keyed by format code. Absolutised on the way in. */
+  media?: MediaContainer;
+  urlLink?: string;
+  external?: string | boolean;
+  contentPage?: string;
+  product?: string;
+  category?: string;
+}
+
+export interface CmsParagraphData extends CmsComponent {
+  title?: string;
+  /** HTML. Stripped to plain text unless `cms.htmlRenderer` is configured. */
+  content?: string;
+}
+
+export interface CmsNavigationNode {
+  uid?: string;
+  title?: string;
+  children?: CmsNavigationNode[];
+  entries?: { itemId?: string; itemSuperType?: string; itemType?: string }[];
+}
+
+export interface CmsNavigationData extends CmsComponent {
+  navigationNode?: CmsNavigationNode;
+  styleClass?: string;
+  wrapAfter?: string;
+}
+
+/** `RotatingImagesComponent`: a space-separated list of banner uids. */
+export interface CmsCarouselData extends CmsComponent {
+  banners?: string;
+  effect?: string;
+}
+
+/**
+ * Where a CMS link points, resolved from the four mutually exclusive fields OCC uses. Laconius
+ * hands this to `cms.onNavigate`; no Laconius package navigates ([chapter 01](../../../docs/spec/01-packages.md)).
+ */
+export type CmsLinkTarget =
+  | { kind: 'url'; url: string; external: boolean }
+  | { kind: 'contentPage'; label: string }
+  | { kind: 'product'; code: string }
+  | { kind: 'category'; code: string };

package/src/normalizer.ts

@@ -0,0 +1,159 @@
+import type {
+  CmsComponent,
+  CmsLinkTarget,
+  CmsStructure,
+  ContentSlot,
+  ContentSlotComponent,
+} from './models';
+
+const CMS_FLEX_COMPONENT_TYPE = 'CMSFlexComponent';
+const JSP_INCLUDE_COMPONENT_TYPE = 'JspIncludeComponent';
+
+/**
+ * The registry key, **computed** — not `typeCode`
+ * (`core-libs/core/src/occ/adapters/cms/converters/occ-cms-page-normalizer.ts:151`). Miss this and
+ * every account page renders blank, because those pages are all `CMSFlexComponent`.
+ */
+export function getComponentKey(component: {
+  typeCode?: string;
+  flexType?: string;
+  uid?: string;
+}): string {
+  if (component.typeCode === CMS_FLEX_COMPONENT_TYPE) return component.flexType ?? '';
+  if (component.typeCode === JSP_INCLUDE_COMPONENT_TYPE) return component.uid ?? '';
+  return component.typeCode ?? '';
+}
+
+type OccComponent = {
+  uid?: string;
+  typeCode?: string;
+  flexType?: string;
+  properties?: Record<string, unknown>;
+  modifiedtime?: string;
+  modifiedTime?: string;
+  [key: string]: unknown;
+};
+
+type OccSlot = {
+  position?: string;
+  properties?: Record<string, unknown>;
+  components?: { component?: OccComponent | OccComponent[] };
+};
+
+export type OccCmsPage = {
+  uid?: string;
+  name?: string;
+  typeCode?: string;
+  label?: string;
+  template?: string;
+  title?: string;
+  description?: string;
+  properties?: Record<string, unknown>;
+  contentSlots?: { contentSlot?: OccSlot | OccSlot[] };
+};
+
+function asArray<T>(value: T | T[] | undefined): T[] {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * Flattens the OCC page payload into `{ page, components }`.
+ *
+ * Slot *order* here is backend order, which the layout config overrides
+ * ([chapter 06](../../../docs/spec/06-cms-engine.md)). Component `properties` stay on the slot
+ * entry and are stripped from the component payload, as in Spartacus.
+ */
+export function normalizeCmsPage(source: OccCmsPage | undefined): CmsStructure {
+  const slots: Record<string, ContentSlot> = {};
+  const components: Record<string, CmsComponent> = {};
+
+  for (const slot of asArray(source?.contentSlots?.contentSlot)) {
+    if (!slot.position) continue;
+    const entries: ContentSlotComponent[] = [];
+
+    for (const occComponent of asArray(slot.components?.component)) {
+      if (!occComponent.uid) continue;
+      entries.push({
+        uid: occComponent.uid,
+        typeCode: occComponent.typeCode,
+        key: getComponentKey(occComponent),
+        properties: occComponent.properties,
+      });
+
+      const { properties: _properties, modifiedtime, ...rest } = occComponent;
+      components[occComponent.uid] = {
+        ...(rest as CmsComponent),
+        // OCC is out of sync with its own model here, and answers `modifiedtime`.
+        modifiedTime: (occComponent.modifiedTime ?? modifiedtime) as string | undefined,
+      };
+    }
+
+    slots[slot.position] = {
+      position: slot.position,
+      properties: slot.properties,
+      components: entries,
+    };
+  }
+
+  return {
+    page: {
+      pageId: source?.uid,
+      name: source?.name,
+      type: source?.typeCode,
+      label: source?.label,
+      template: source?.template,
+      title: source?.title,
+      description: source?.description,
+      properties: source?.properties,
+      slots,
+    },
+    components,
+  };
+}
+
+/**
+ * The four mutually exclusive link fields OCC uses, in Spartacus' own precedence
+ * (`cms-components/content/banner/banner.component.ts:64`). `external` arrives as the string
+ * `'true'` about as often as a boolean.
+ */
+export function resolveLinkTarget(data: {
+  url?: string;
+  urlLink?: string;
+  external?: string | boolean;
+  contentPage?: string;
+  contentPageLabelOrId?: string;
+  product?: string;
+  category?: string;
+}): CmsLinkTarget | undefined {
+  const url = data.urlLink ?? data.url;
+  if (url) {
+    return { kind: 'url', url, external: data.external === true || data.external === 'true' };
+  }
+  const label = data.contentPage ?? data.contentPageLabelOrId;
+  if (label) return { kind: 'contentPage', label };
+  if (data.product) return { kind: 'product', code: data.product };
+  if (data.category) return { kind: 'category', code: data.category };
+  return undefined;
+}
+
+/**
+ * The default HTML story: strip tags, decode the five named entities OCC actually emits, collapse
+ * whitespace. Laconius ships no parser — rich text is `cms.htmlRenderer`
+ * ([chapter 06](../../../docs/spec/06-cms-engine.md)).
+ */
+export function stripHtml(html: string | undefined): string {
+  if (!html) return '';
+  return html
+    .replace(/<br\s*\/?>|<\/(p|div|li|h[1-6])>/gi, '\n')
+    .replace(/<[^>]*>/g, '')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}

package/src/page.tsx

@@ -0,0 +1,228 @@
+import { useLaconiusConfig } from '@laconius/core';
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+import { StyleSheet, Text, View, type StyleProp, type ViewStyle } from 'react-native';
+
+import type {
+  CmsComponent,
+  CmsStructure,
+  ContentSlotComponent,
+  PageContext,
+} from './models';
+import { getComponentKey } from './normalizer';
+import { useCmsComponent, useCmsPage } from './queries';
+
+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}`);
+}
+
+type PageValue = { structure: CmsStructure; context: PageContext };
+
+const PageStructureContext = createContext<PageValue | undefined>(undefined);
+const ComponentContext = createContext<
+  { uid: string; typeCode?: string; data: CmsComponent } | undefined
+>(undefined);
+
+/**
+ * The whole component contract: typed data through a hook, never props
+ * ([ADR-0007](../../../docs/adr/0007-two-registries-two-contracts.md)). Props would make a
+ * registered replacement depend on what Laconius happens to pass it, and substitutability dies.
+ */
+export function useCmsComponentData<T extends CmsComponent>(): T {
+  const entry = useContext(ComponentContext);
+  if (!entry) {
+    throw new Error(
+      '[laconius] useCmsComponentData must be used inside a component rendered by the CMS registry.',
+    );
+  }
+  return entry.data as T;
+}
+
+/** The uid of the component being rendered, for components that key their own state on it. */
+export function useCmsComponentUid(): string {
+  const entry = useContext(ComponentContext);
+  if (!entry) {
+    throw new Error(
+      '[laconius] useCmsComponentUid must be used inside a component rendered by the CMS registry.',
+    );
+  }
+  return entry.uid;
+}
+
+/** The page a `<CmsSlot>` reads from, and the context its components are scoped to. */
+export function useCmsPageStructure(): PageValue | undefined {
+  return useContext(PageStructureContext);
+}
+
+export type CmsPageProviderProps = {
+  context: PageContext;
+  children: ReactNode;
+};
+
+/**
+ * Fetches a page and provides it to the `<CmsSlot>`s inside. Suspends: wrap it in `<Suspense>`
+ * and an error boundary.
+ *
+ * A native screen that only *hosts* CMS slots — a PDP, the cart — mounts this around its own
+ * layout and places slots where it wants them.
+ */
+export function CmsPageProvider({ context, children }: CmsPageProviderProps) {
+  const { data } = useCmsPage(context);
+  const value = useMemo(() => ({ structure: data, context }), [data, context]);
+  return <PageStructureContext.Provider value={value}>{children}</PageStructureContext.Provider>;
+}
+
+export type CmsSlotProps = {
+  position: string;
+  style?: StyleProp<ViewStyle>;
+  /** Rendered when the slot is absent or empty. */
+  fallback?: ReactNode;
+};
+
+export function CmsSlot({ position, style, fallback = null }: CmsSlotProps) {
+  const page = useCmsPageStructure();
+  const slot = page?.structure.page.slots[position];
+
+  if (!page) {
+    warnOnce(
+      `<CmsSlot position="${position}"> rendered outside a page. Wrap the screen in <CmsPageProvider> or <CmsPage>.`,
+    );
+    return <>{fallback}</>;
+  }
+  if (!slot || slot.components.length === 0) return <>{fallback}</>;
+
+  return (
+    <View style={style}>
+      {slot.components.map((entry) => (
+        <CmsComponentOutlet key={entry.uid} entry={entry} />
+      ))}
+    </View>
+  );
+}
+
+export type CmsPageProps = {
+  /** A content-page label, e.g. `/about-us`. Passed as a prop: no Laconius package routes. */
+  pageLabel?: string;
+  /** For a page that is not a content page. Takes precedence over `pageLabel`. */
+  context?: PageContext;
+  style?: StyleProp<ViewStyle>;
+  slotStyle?: StyleProp<ViewStyle>;
+};
+
+/**
+ * A whole page, top to bottom, in the slot order of `cms.layouts[template]`. It renders no scroll
+ * container: the screen owns scrolling, safe areas and refresh control.
+ */
+export function CmsPage({ pageLabel, context, style, slotStyle }: CmsPageProps) {
+  const resolved = useMemo<PageContext>(
+    () => context ?? { id: pageLabel ?? '/', type: 'ContentPage' },
+    [context, pageLabel],
+  );
+  return (
+    <CmsPageProvider context={resolved}>
+      <CmsPageSlots style={style} slotStyle={slotStyle} />
+    </CmsPageProvider>
+  );
+}
+
+function CmsPageSlots({
+  style,
+  slotStyle,
+}: {
+  style?: StyleProp<ViewStyle>;
+  slotStyle?: StyleProp<ViewStyle>;
+}) {
+  const config = useLaconiusConfig();
+  const page = useCmsPageStructure();
+  const template = page?.structure.page.template;
+  const configured = template ? config.cms?.layouts?.[template]?.slots : undefined;
+
+  if (!page) return null;
+  if (!configured && template) {
+    // Slot order is client configuration; backend key order is a fallback, not the contract.
+    warnOnce(
+      `No cms.layouts entry for template "${template}"; falling back to the backend slot order.`,
+    );
+  }
+  const positions = configured ?? Object.keys(page.structure.page.slots);
+
+  return (
+    <View style={style}>
+      {positions.map((position) => (
+        <CmsSlot key={position} position={position} style={slotStyle} />
+      ))}
+    </View>
+  );
+}
+
+/** Renders one slot entry through the registry, loading its data if the page did not inline it. */
+export function CmsComponentOutlet({ entry }: { entry: ContentSlotComponent }) {
+  const config = useLaconiusConfig();
+  const page = useCmsPageStructure();
+  const inlined = page?.structure.components[entry.uid];
+  const query = useCmsComponent(entry.uid, {
+    context: page?.context,
+    enabled: !inlined,
+  });
+  const data = inlined ?? query.data;
+  const mapping = config.cms?.components?.[entry.key];
+
+  if (!mapping) return <UnregisteredComponent typeCode={entry.key} uid={entry.uid} />;
+  if (!data) return null;
+
+  const Component = mapping.component;
+  return (
+    <ComponentContext.Provider value={{ uid: entry.uid, typeCode: entry.typeCode, data }}>
+      <Component />
+    </ComponentContext.Provider>
+  );
+}
+
+/**
+ * Renders a component addressed only by uid — what a carousel does with the banner uids it holds.
+ * The registry key comes from the loaded payload, not from a slot entry.
+ */
+export function CmsComponentByUid({ uid }: { uid: string }) {
+  const page = useCmsPageStructure();
+  const inlined = page?.structure.components[uid];
+  const query = useCmsComponent(uid, { context: page?.context, enabled: !inlined });
+  const data = inlined ?? query.data;
+  if (!data) return null;
+  return <CmsComponentOutlet entry={{ uid, typeCode: data.typeCode, key: getComponentKey(data) }} />;
+}
+
+/**
+ * Dev: a visible placeholder plus one warning per type. Prod: silent skip.
+ *
+ * Spartacus only warns, which is survivable on the web where the gap is visible in a layout. On
+ * native an unregistered type is invisible — the prototype hit it on its first run, against the
+ * stock homepage's `ProductCarouselComponent`.
+ */
+function UnregisteredComponent({ typeCode, uid }: { typeCode: string; uid: string }) {
+  if (process.env.NODE_ENV === 'production') return null;
+  warnOnce(`No CMS component registered for "${typeCode}". Add it to cms.components.`);
+  return (
+    <View style={placeholderStyles.root}>
+      <Text style={placeholderStyles.text}>
+        {typeCode || '(no type code)'}
+        {'\n'}
+        {uid}
+      </Text>
+    </View>
+  );
+}
+
+const placeholderStyles = StyleSheet.create({
+  root: {
+    padding: 12,
+    margin: 4,
+    borderWidth: 1,
+    borderStyle: 'dashed',
+    borderColor: '#B00020',
+    borderRadius: 4,
+  },
+  text: { fontSize: 12, color: '#B00020' },
+});

package/src/queries.ts

@@ -0,0 +1,56 @@
+import { getRuntime, laconiusQueryKey } from '@laconius/core';
+import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/react-query';
+
+import { cmsAdapter, loadCmsComponent } from './adapter';
+import type { CmsComponent, CmsNavigationData, PageContext } from './models';
+
+/**
+ * `queryOptions` factories, so an app can `prefetchQuery` a page without forking Laconius.
+ *
+ * The page key is **per page**, deliberately unlike Spartacus, which collapses every content page
+ * under one `ContentPage` key (`core-libs/core/src/cms/utils/cms-utils.ts:29-31`).
+ */
+export const cmsQueries = {
+  page: (context: PageContext) =>
+    queryOptions({
+      queryKey: laconiusQueryKey('cms', 'page', context),
+      queryFn: () => {
+        const runtime = getRuntime();
+        return cmsAdapter(runtime).loadPage(runtime, context);
+      },
+    }),
+  component: (uid: string, context?: PageContext) =>
+    queryOptions({
+      queryKey: laconiusQueryKey('cms', 'component', uid),
+      queryFn: () => loadCmsComponent(getRuntime(), uid, context),
+    }),
+};
+
+/**
+ * Suspends. There is no blocking guard: Spartacus' `CmsPageGuard` becomes a non-blocking fetch
+ * plus a suspending screen, so the native chrome is on screen while the page loads.
+ */
+export function useCmsPage(context: PageContext) {
+  return useSuspenseQuery(cmsQueries.page(context));
+}
+
+/** One component by uid. Requests made in the same frame go out as one batched call. */
+export function useCmsComponent<T extends CmsComponent>(
+  uid: string,
+  options: { context?: PageContext; enabled?: boolean } = {},
+) {
+  return useQuery({
+    ...cmsQueries.component(uid, options.context),
+    enabled: options.enabled ?? true,
+    select: (component) => component as T,
+  });
+}
+
+/**
+ * The `navigationNode` tree of a `NavigationComponent` / `FooterNavigationComponent` /
+ * `CategoryNavigationComponent`, for apps rendering their own chrome from CMS navigation.
+ */
+export function useCmsNavigation(uid: string) {
+  const query = useCmsComponent<CmsNavigationData>(uid);
+  return { ...query, node: query.data?.navigationNode };
+}