@se-studio/core-ui 0.0.0-next16-20260822103555

package/src/showcase/README.md

@@ -0,0 +1,269 @@
+# CMS Showcase Infrastructure
+
+The CMS Showcase is a developer tool designed to test and preview CMS components and collections with mock data. This directory contains the shared infrastructure used by multiple projects to implement their own showcase pages.
+
+## Architecture
+
+The showcase is split into several key parts:
+
+- `ShowcasePage.tsx`: The main container component that handles the layout, top bar, and panels.
+- `ShowcaseRenderPage.tsx`: The iframe content component that renders the actual CMS component or collection with mock data.
+- `mockFactory.ts`: Logic for generating mock data based on component/collection types and control state.
+- `components/`: UI components for the showcase interface (Sidebar, Controls, TopBar, etc.).
+- `types.ts`: TypeScript definitions for the showcase state and control options.
+
+## Styling Conventions
+
+**IMPORTANT:** Because this code is shared across multiple projects, it **must not** rely on project-specific Tailwind configurations.
+
+All styling in this directory uses **hardcoded Tailwind arbitrary values** to ensure consistent rendering regardless of the host project's `tailwind.config.ts`.
+
+- **Colors:** Use hex codes, e.g., `text-[#374151]`, `bg-[#f9fafb]`, `border-[#e5e7eb]`.
+- **Spacing/Size:** Use pixel values, e.g., `text-[11px]`, `w-[300px]`, `p-[16px]`.
+- **Fonts:** Use standard weights, e.g., `font-[500]`, `font-[600]`.
+
+**Consumer requirement:** the app’s Tailwind entry (`globals.css`) must scan this package, e.g. `@source "../../node_modules/@se-studio/core-ui/";`. Without that, showcase and media library class names never enter the CSS bundle.
+
+## Registration Pattern & `usedFields`
+
+The showcase uses the `usedFields` and `cardUsedFields` from the CMS registration system to determine which controls to show for a given component or collection. It also uses the `mock` and `cardMock` properties to generate realistic initial data.
+
+When you register a component using `defineComponent` or a collection using `defineCollection`, you provide a `Set<string>` of fields that the component actually uses. The `mockFactory` uses these sets to:
+1. Filter the generated mock data to only include relevant fields.
+2. Show or hide controls in the sidebar based on whether a field is "used".
+
+Example registration:
+
+```tsx
+export const HeroRegistration = defineComponent({
+  name: 'Hero', // Must match CMS componentType
+  renderer: Hero,
+  usedFields: new Set(['heading', 'preHeading', 'body', 'visual', 'links']),
+  mock: {
+    heading: 'Hero Heading',
+    body: 'Hero body text description.',
+    visual: { width: 1200, height: 600 },
+  },
+});
+```
+
+## Integration Guide
+
+To add a CMS Showcase to a project:
+
+1. Create a `page.tsx` for the main showcase interface:
+   ```tsx
+   import { ShowcasePage } from '@se-studio/core-ui';
+   import {
+     componentFieldsMap,
+     collectionFieldsMap,
+     projectRendererConfig,
+     // ... other props
+   } from '@/lib/cms';
+
+   export default async function Page({ searchParams }) {
+     return (
+       <ShowcasePage
+         searchParams={await searchParams}
+         rendererConfig={projectRendererConfig}
+         componentFieldsMap={componentFieldsMap}
+         collectionFieldsMap={collectionFieldsMap}
+         basePath="/cms/showcase"
+         // ... project-specific color options
+       />
+     );
+   }
+   ```
+
+2. Create a separate route for the preview iframe (e.g., `/cms/showcase/render/page.tsx`):
+   ```tsx
+   import { ShowcaseRenderPage } from '@se-studio/core-ui';
+   import {
+     componentFieldsMap,
+     collectionFieldsMap,
+     collectionCardFieldsMap,
+     componentMockMap,
+     collectionMockMap,
+     collectionCardMockMap,
+     projectRendererConfig
+   } from '@/lib/cms';
+
+   export default async function Page({ searchParams }) {
+     return (
+       <ShowcaseRenderPage
+         searchParams={await searchParams}
+         rendererConfig={projectRendererConfig}
+         componentFieldsMap={componentFieldsMap}
+         collectionFieldsMap={collectionFieldsMap}
+         collectionCardFieldsMap={collectionCardFieldsMap}
+         componentMockMap={componentMockMap}
+         collectionMockMap={collectionMockMap}
+         collectionCardMockMap={collectionCardMockMap}
+       />
+     );
+   }
+   ```
+
+3. Ensure your `cms.ts` exports all the maps built from registrations:
+   ```ts
+   // Build maps from registrations
+   const {
+     componentMap,
+     componentFieldsMap,
+     componentMockMap
+   } = buildComponentMaps(componentRegistrations);
+
+   const {
+     collectionMap,
+     collectionFieldsMap,
+     collectionCardFieldsMap,
+     collectionMockMap,
+     collectionCardMockMap
+   } = buildCollectionMaps(collectionRegistrations);
+
+   // Export maps for cms/showcase
+   export {
+     componentFieldsMap,
+     collectionFieldsMap,
+     collectionCardFieldsMap,
+     componentMockMap,
+     collectionMockMap,
+     collectionCardMockMap,
+   };
+   ```
+
+## Query parameters
+
+| Param | Effect |
+|-------|--------|
+| `type` | Component or collection type name |
+| `mode` | `component` (default) or `collection` |
+| `view` | `single` (default) or `all` |
+| `controls` | `true` opens the controls panel on load (closed by default) |
+| `clean` | `true` uses default control state only (no registration/curated mocks) |
+| `debug` | `true` / `1` shows developer chrome (e.g. “fixed frame” labels on viewport layouts) |
+| control keys | e.g. `heading`, `body`, `showVisual`, `backgroundColour` — override mock defaults |
+
+Example: `/cms/showcase?type=Feature+Split&controls=true`
+
+### Wiring `build*Maps` after this release
+
+`buildComponentMaps` / `buildCollectionMaps` now also return:
+
+- `componentShowcaseLayoutMap`
+- `collectionShowcaseLayoutMap`
+
+Existing destructures that only pick known keys keep working. To honour registration `showcaseLayout`, pass the maps into `ShowcasePage`:
+
+```ts
+const {
+  componentMap,
+  componentFieldsMap,
+  componentMockMap,
+  componentShowcaseLayoutMap,
+  excludedComponents,
+  // ...
+} = buildComponentMaps(componentRegistrations);
+
+const {
+  collectionMap,
+  collectionFieldsMap,
+  collectionMockMap,
+  collectionCardMockMap,
+  collectionCardFieldsMap,
+  collectionShowcaseLayoutMap,
+  excludedCollections,
+} = buildCollectionMaps(collectionRegistrations);
+
+// Showcase page:
+<ShowcasePage
+  componentShowcaseLayoutMap={componentShowcaseLayoutMap}
+  collectionShowcaseLayoutMap={collectionShowcaseLayoutMap}
+  ...
+/>
+```
+
+If you omit the maps, layout defaults to `document` (auto-height) for every type.
+
+## Controls support mapping
+
+The sidebar maps control keys to CMS `usedFields` (e.g. `showVisual` → `visual` / `backgroundVisual`, `showLinks` → `links`). Registration mocks may use plain string `body` / `additionalCopy`; the mock factory converts them to rich text. When a type uses `visual` but the mock has no image URL, a placehold.co placeholder is generated.
+
+**Video URLs:** curated `visual.url` values that point at Vimeo/YouTube pages are turned into **External video** visuals (not `next/image` Pictures). Prefer image CDN URLs for posters; use video page URLs only for video modules.
+
+## Iframe height behaviour
+
+Render iframes report content height via `postMessage` from `#showcase-measure-root` so short components shrink below the initial frame size. Single previews cap at 900px. Viewport-unit heroes (`svh` / `70vh` / inline `100svh` styles) are capped inside the iframe by `ShowcaseViewportGuard` so All-view and full-screen collections cannot explode to multi-megapixel heights. Production pages are unaffected.
+
+### `showcaseLayout` on registrations
+
+```ts
+defineComponent({
+  name: 'Dynamic hero',
+  showcaseLayout: 'compact', // document | viewport | compact
+  // ...
+});
+defineCollection({
+  name: 'Full Screen Slides',
+  showcaseLayout: 'viewport',
+  // ...
+});
+```
+
+| Mode | Parent iframe |
+|------|----------------|
+| `document` (default) | Auto-grow to content height |
+| `viewport` | Fixed frame (~640 mobile / ~720 desktop) + internal scroll |
+| `compact` | Shorter fixed frame (~400 / ~480) for full-bleed heroes |
+
+Pass maps from `buildComponentMaps` / `buildCollectionMaps` into `ShowcasePage`:
+
+```ts
+const { componentShowcaseLayoutMap, ... } = buildComponentMaps(...);
+const { collectionShowcaseLayoutMap, ... } = buildCollectionMaps(...);
+
+<ShowcasePage
+  componentShowcaseLayoutMap={componentShowcaseLayoutMap}
+  collectionShowcaseLayoutMap={collectionShowcaseLayoutMap}
+  ...
+/>
+```
+
+**Prefer component-level compact UIs** when `isCmsShowcase(contentContext)` is true (e.g. stack Full Screen Slides cards instead of sticky `100svh` scroll). The layout flag only controls the outer frame.
+
+### Related articles / people collections
+
+Types that call `fetchHelpers.getRelatedArticles` / `getRelatedPeople` will get **empty lists** from showcase mock `contents` (those are mock components, not CMS link entries). Use:
+
+```ts
+import {
+  isCmsShowcase,
+  articlesFromShowcaseContents,
+  peopleFromShowcaseContents,
+} from '@se-studio/core-ui';
+
+const articles =
+  result.data.length > 0
+    ? result.data
+    : isCmsShowcase(contentContext)
+      ? articlesFromShowcaseContents(information)
+      : result.data;
+// articles is IArticleLink[] — type: 'Internal link', internalType: 'Article',
+// with title, href, visuals[], lastModified, etc. suitable for CoreNewsCard-style UIs.
+```
+
+Keep `cardUsedFields` broad enough that mock factory does not strip `heading` / `visual` from card mocks.
+
+### Page-context components
+
+Components that read `contentContext.pageContext.article` (e.g. poster download blocks) render nothing in showcase unless the site provides a showcase stub when `isCmsShowcase()`. Alternatively set `showcaseExclude: true`.
+
+### View transitions on cms-dev
+
+If the site uses `next-view-transitions` / `useTransitionRouter` on public routes, wrap **`(cms-dev)`** layout with `<ViewTransitions>` as well, or showcase collections that use those links will crash.
+
+## Scroll-gated animations
+
+Some projects pause entrance animations until `ClientMonitor` sets `data-seen` on `[data-component]` sections (e.g. `animate-when-seen` + `animate-text-in`). Showcase routes under `/cms/*` do not mount `ClientMonitor`.
+
+`ShowcaseRenderPage` and `ShowcaseAllRenderPage` wrap output in `ShowcaseAnimationRoot`, which sets `data-seen` on a root element so showcase previews and screenshot capture render visible content immediately. Production page behaviour is unchanged.