@se-studio/project-build 1.0.51 → 1.0.53

package/skills/se-marketing-sites/create-component/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: create-cms-component
+description: Guide for creating new CMS-driven components in the SE Core Product monorepo. Use this skill when asked to create a new component, ensuring adherence to the 4-layer architecture.
+license: Private
+metadata:
+  author: se-core-product
+  version: "1.1.0"
+---
+
+# Creating CMS Components
+
+This guide explains how to build new CMS-driven components following the established architecture patterns in this codebase.
+
+## Architecture Overview
+
+All components follow a **four-layer architecture** and must remain **Server Components** by default.
+
+1.  **Layer 1: Core Component (Pure Presentation)**
+    *   Named export: `Core[ComponentName]`
+    *   CMS-agnostic rendering logic
+    *   Accepts `positionClassName` prop
+    *   **MUST be a Server Component** (no `'use client'`)
+    *   If interactivity is needed, import a Client Component here.
+
+2.  **Layer 2: Wrapper Component (Section Integration)**
+    *   Named export: `[ComponentName]`
+    *   Wraps Core with `<Section>`
+    *   Handles spacing & background
+
+3.  **Layer 3: Renderer (CMS Integration)**
+    *   Default export: `[ComponentName]` (short name)
+    *   Implements `ComponentRenderer`
+    *   Wraps with `UnusedChecker` for CMS validation
+
+4.  **Layer 4: Registration (Showcase & CMS)**
+    *   Named export: `[ComponentName]Registration`
+    *   Uses `defineComponent` helper
+    *   Provides metadata & mock data
+
+## Client Component Strategy
+
+**Rule: Isolate Client Logic.**
+
+Never make the entire component a Client Component just for a small interactive part.
+
+*   **BAD**: Adding `'use client'` to `MyComponent.tsx` (Layers 1-3).
+*   **GOOD**: Creating `MyComponentClient.tsx` (or `*Animator.tsx`) with `'use client'` and importing it into `CoreMyComponent`.
+
+### Why?
+*   **Performance**: Keeps the majority of the HTML generation on the server.
+*   **SEO**: Ensures content is fully rendered for crawlers.
+*   **Bundle Size**: Only sends necessary JS to the browser.
+
+### Pattern: The Client Wrapper
+
+If you need state (e.g., filters, toggles) or effects (e.g., animations), create a wrapper:
+
+1.  Create `MyComponentClient.tsx` (or `MyComponentAnimator.tsx`).
+2.  Add `'use client'` at the top.
+3.  Accept `children` or raw data props.
+4.  Import and use it in `CoreMyComponent`.
+
+## Quick Start Template
+
+Use this template for new components. Replace `MyNewComponent` with your component name.
+
+```typescript
+import type { IContentContext } from '@se-studio/core-data-types';
+import {
+  type CmsRendererConfig,
+  type ComponentRenderer,
+  convertText,
+  cn,
+  defineComponent,
+  RtfOrString,
+  UnusedChecker,
+} from '@se-studio/core-ui';
+import { SectionLinks } from '@/elements/SectionLinks';
+import { Section } from '@/framework/Section';
+import type { IComponent, IContent } from '@/lib/cms';
+import { getPreviewFieldIdProps } from '@/lib/cms';
+import { getSizingInformation } from '@/lib/SizingInformation';
+// If interactivity is needed:
+// import MyNewComponentClient from './MyNewComponentClient';
+
+// 1. Define which CMS fields this component uses
+const FIELD_KEYS = [
+  'id',
+  'index',
+  'heading',
+  'body',
+  'links',
+  'anchor',
+  'cmsLabel',
+] as const;
+
+type Fields = Pick<IComponent, (typeof FIELD_KEYS)[number]>;
+
+const USED_FIELDS = new Set([...FIELD_KEYS, 'componentType']);
+
+// 2. Layer 1: Core Component (Pure presentation, Server Component)
+export const CoreMyNewComponent: React.FC<
+  Fields & {
+    contentContext?: IContentContext;
+    rendererConfig?: CmsRendererConfig;
+    embedded?: boolean;
+    positionClassName?: string;
+  }
+> = ({
+  id,
+  index,
+  heading,
+  body,
+  links,
+  cmsLabel,
+  contentContext,
+  rendererConfig,
+  positionClassName,
+}) => {
+  const { Element, sizingInformation } = getSizingInformation(index);
+
+  return (
+    <div className={cn('space-y-6', positionClassName)}>
+      {heading && (
+        <Element
+          {...getPreviewFieldIdProps(id, 'heading')}
+          className={cn(sizingInformation.h1)}
+        >
+          {convertText(heading)}
+        </Element>
+      )}
+      {body && (
+        <RtfOrString
+          {...getPreviewFieldIdProps(id, 'body')}
+          content={body}
+          className={cn('rtf-standard')}
+          rendererConfig={rendererConfig}
+          contentContext={contentContext}
+        />
+      )}
+      {/* Example of isolated client logic usage: */}
+      {/* <MyNewComponentClient>
+            <InteractivePart />
+          </MyNewComponentClient> 
+      */}
+      {links && (
+        <SectionLinks
+          links={links}
+          trackingLocation={cmsLabel}
+          analyticsContext={contentContext?.analyticsContext}
+        />
+      )}
+    </div>
+  );
+};
+
+// 3. Layer 2: Wrapper Component (Section integration)
+const MyNewComponent: React.FC<
+  Fields &
+    Pick<IComponent, 'componentType'> & {
+      contentContext: IContentContext;
+      information: IContent;
+      rendererConfig: CmsRendererConfig;
+    }
+> = ({ information, componentType, ...rest }) => {
+  return (
+    <Section componentName={componentType} information={information}>
+      <CoreMyNewComponent
+        {...rest}
+        positionClassName="col-span-full laptop:col-start-2 laptop:col-span-10"
+      />
+    </Section>
+  );
+};
+
+// 4. Layer 3: Renderer Export (CMS integration)
+const MyNew: ComponentRenderer<IComponent> = ({
+  information,
+  contentContext,
+  rendererConfig,
+}) => {
+  const { componentType, ...rest } = information;
+
+  return (
+    <UnusedChecker componentName={componentType} allFields={rest} usedFields={USED_FIELDS}>
+      <MyNewComponent
+        rendererConfig={rendererConfig}
+        contentContext={contentContext}
+        information={information}
+        componentType={componentType}
+        {...rest}
+      />
+    </UnusedChecker>
+  );
+};
+
+export default MyNew;
+
+// 5. Layer 4: Registration
+export const MyNewRegistration = defineComponent({
+  name: 'My New Component', // Must match CMS componentType
+  renderer: MyNew,
+  usedFields: USED_FIELDS,
+  mock: {
+    heading: 'Sample Heading',
+    body: 'This is sample body text for the showcase.',
+  },
+});
+```
+
+## Implementation Checklist
+
+1.  **Create file**: `src/project/components/MyNewComponent.tsx`
+2.  **Define Fields**:
+    *   Set `FIELD_KEYS` with all used fields.
+    *   Create `Fields` type.
+    *   Create `USED_FIELDS` set (don't forget `'componentType'`).
+    *   Include standard fields: `id`, `index`, `anchor`, `cmsLabel`.
+3.  **Build Core Component**:
+    *   **ENSURE SERVER COMPONENT**: Do not use `'use client'`.
+    *   Export named `Core[Name]`.
+    *   Accept `positionClassName`.
+    *   Use `getSizingInformation(index)` for semantic headings.
+    *   Check field existence (`field &&`).
+    *   Use `convertText()` for strings.
+    *   Use `<RtfOrString>` for rich text.
+    *   Apply `getPreviewFieldIdProps()` for CMS preview.
+4.  **Handle Interactivity (If Needed)**:
+    *   Create separate `[Name]Client.tsx` or `[Name]Animator.tsx`.
+    *   Add `'use client'` to that file only.
+    *   Import and use in Core component.
+5.  **Build Wrapper Component**:
+    *   Wrap Core with `<Section>`.
+    *   Pass `componentName={componentType}` and `information`.
+    *   Set layout (e.g., `positionClassName="col-span-full"`).
+6.  **Build Renderer**:
+    *   Default export (short name).
+    *   Wrap with `<UnusedChecker>`.
+7.  **Define Registration**:
+    *   Export named `[Name]Registration`.
+    *   Use `defineComponent`.
+    *   **CRITICAL**: `name` must match CMS `componentType` exactly.
+    *   Provide mock data for showcase.
+8.  **Register Component**:
+    *   Add to `componentRegistrations` array in `src/lib/cms.ts`.

package/skills/se-marketing-sites/create-page/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: create-page-route
+description: Guide for creating new Next.js App Router pages and dynamic routes in the SE Core Product framework.
+license: Private
+metadata:
+  author: se-core-product
+  version: "1.0.0"
+---
+
+# Creating Pages and Routes
+
+This guide explains how to create new pages and handle routing in the SE Core Product Next.js framework. The system uses Next.js App Router with Contentful-driven dynamic routing.
+
+## Page Architecture
+
+### 1. Dynamic Catch-All Route (`[...slugs]`)
+
+Most CMS pages are handled by a single catch-all route at `app/(pages)/[...slugs]/page.tsx`. This component:
+1.  Receives the URL slug.
+2.  Fetches the page data from Contentful.
+3.  Renders the `<CmsContent>` component.
+
+### 2. Static Params Generation
+
+To enable Static Site Generation (SSG), the page exports `generateStaticParams`:
+
+```typescript
+import { getAllPageLinks } from '@/lib/cms';
+
+export async function generateStaticParams() {
+  const links = await getAllPageLinks();
+  return links
+    .filter(link => link.slug !== 'index')
+    .map(link => ({
+      slugs: link.href?.split('/').filter(Boolean)
+    }));
+}
+```
+
+## Creating a New Specialized Route
+
+Sometimes you need a route that behaves differently from standard CMS pages (e.g., a search page, a dashboard, or a specialized landing page).
+
+### Step 1: Create the Route Directory
+
+Create a new directory in `src/app` matching your desired URL structure.
+
+*   Example: `src/app/search/page.tsx` -> `/search`
+*   Example: `src/app/team/[slug]/page.tsx` -> `/team/john-doe`
+
+### Step 2: Implement the Page Component
+
+```typescript
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { CmsContent } from '@se-studio/core-ui';
+import { contentfulPageRest, getContentfulConfig } from '@/lib/cms';
+import { projectRendererConfig } from '@/lib/cms';
+
+interface PageProps {
+  params: { slug: string };
+  searchParams: { [key: string]: string | string[] | undefined };
+}
+
+export default async function Page({ params, searchParams }: PageProps) {
+  const { slug } = params;
+  const isPreview = searchParams.preview === 'true';
+
+  // 1. Fetch content
+  const response = await contentfulPageRest(
+    getContentfulConfig(isPreview),
+    slug,
+    { preview: isPreview }
+  );
+
+  if (!response.data) {
+    notFound();
+  }
+
+  // 2. Render content with CmsContent
+  // This automatically handles the recursive rendering of components
+  return (
+    <main>
+      <CmsContent
+        content={response.data}
+        config={projectRendererConfig}
+        contentContext={{
+            // Pass any required context
+            analyticsContext: { ... }
+        }}
+      />
+    </main>
+  );
+}
+```
+
+### Step 3: Add Metadata
+
+Always export metadata for SEO:
+
+```typescript
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const response = await contentfulPageRest(/* ... */);
+  const page = response.data;
+
+  if (!page) return {};
+
+  return {
+    title: page.seoTitle || page.title,
+    description: page.seoDescription,
+    // ... maps to Next.js metadata format
+  };
+}
+```
+
+## Custom Layouts
+
+If your new route needs a different layout (e.g., no header/footer), create a `layout.tsx` in your route directory.
+
+```typescript
+export default function CustomLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="custom-layout">
+      {children}
+    </div>
+  );
+}
+```
+
+## Troubleshooting
+
+*   **404 on new route**: Ensure you've re-run the dev server or build if you added a new dynamic route segment.
+*   **Static params missing**: Check if your new content is published in Contentful and reachable via `getAllPageLinks` (or your custom fetcher).
+*   **Preview mode not working**: Ensure you are passing `preview: true` to the fetcher functions when `searchParams.preview` is set.

package/skills/se-marketing-sites/handling-media/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: handling-media
+description: Guide for using images, videos, and animations in marketing sites using the ResponsiveVisual and VisualComponent systems.
+license: Private
+metadata:
+  author: se-core-product
+  version: "1.0.0"
+---
+
+# Handling Media
+
+This project uses a unified media system to handle images, videos, and animations efficiently.
+
+## Core Components
+
+### 1. `ResponsiveVisual` (or `VisualComponent`)
+
+This is the main component for rendering media from Contentful. It handles:
+*   Responsive image sources (desktop/mobile).
+*   Format optimization (WebP/AVIF).
+*   Video auto-play/looping.
+*   Lottie animations.
+*   Lazy loading & Priority hints.
+
+```typescript
+import VisualComponent from '@/framework/VisualComponent';
+// or
+import { Visual } from '@se-studio/core-ui';
+```
+
+## Usage Pattern
+
+### Basic Usage
+
+```typescript
+<VisualComponent
+  visual={field.visual}
+  className="w-full h-auto"
+/>
+```
+
+### Responsive Sizing (`visualSizes`)
+
+You **MUST** provide `visualSizes` to ensure the browser loads the correct image size. This uses the `sizes` attribute.
+
+```typescript
+import { calculateVisualSizes } from '@se-studio/core-ui';
+
+// Example: Full width on mobile, 50% width on laptop
+const sizes = calculateVisualSizes(1, { laptop: 0.5 });
+
+<VisualComponent
+  visual={visual}
+  visualSizes={sizes}
+/>
+```
+
+*   `1`: 100vw (Mobile default)
+*   `laptop: 0.5`: 50vw (Laptop breakpoint)
+
+### LCP Optimization (`calculateImagePriority`)
+
+For the Hero component (or whatever is at the top of the page), you must prioritize the image load to improve LCP (Largest Contentful Paint).
+
+Use `calculateImagePriority(index)` where `index` is the component's position on the page.
+
+```typescript
+import { calculateImagePriority } from '@se-studio/core-ui';
+
+<VisualComponent
+  visual={visual}
+  {...calculateImagePriority(index)}
+/>
+```
+
+If `index` is `0`, this sets `priority={true}` (or `fetchPriority="high"`). If `index > 0`, it defaults to lazy loading.
+
+### Analytics Tracking
+
+Pass `componentLabel` (usually `cmsLabel`) and `analyticsContext` to enable click tracking on media elements (if they are linked).
+
+```typescript
+<VisualComponent
+  visual={visual}
+  componentLabel={cmsLabel}
+  analyticsContext={contentContext.analyticsContext}
+/>
+```
+
+## Media Types
+
+The `IResponsiveVisual` type (from `@se-studio/core-data-types`) supports:
+
+1.  **Image**: Standard Contentful image asset.
+2.  **Video**: Hosted video file (mp4/webm). The component handles `<video>` tag rendering with autoplay/loop/muted attributes suitable for background videos.
+3.  **Animation**: Lottie JSON file. Renders using a Lottie player.
+
+The component automatically detects the type and renders the appropriate element.
+
+## Mobile Specific Visuals
+
+Contentful models often support a separate `mobileVisual` field. The `VisualComponent` handles switching between them using `<picture>` tags or CSS media queries internally.
+
+You typically pass the combined object or handle it via props if the component exposes both:
+
+```typescript
+// If your component merges them into one responsive object before rendering:
+<VisualComponent visual={combinedVisual} />
+```
+
+Or if using raw fields:
+
+```typescript
+<VisualComponent
+  visual={visual}
+  mobileVisual={mobileVisual}
+/>
+```

package/skills/se-marketing-sites/register-cms-features/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: register-cms-features
+description: Guide for registering new components, collections, and external integrations in the CMS configuration (src/lib/cms.ts).
+license: Private
+metadata:
+  author: se-core-product
+  version: "1.0.0"
+---
+
+# Registering CMS Features
+
+The file `src/lib/cms.ts` is the central registry for the application. It connects Contentful content types to their React implementations.
+
+## How Registration Works
+
+The system uses "Registration Objects" created via `defineComponent` or `defineCollection`. These objects contain:
+1.  **Name**: Matches the Contentful content type ID (or a mapped name).
+2.  **Renderer**: The React component to render.
+3.  **Used Fields**: Which fields from the content model are used.
+4.  **Mock Data**: Sample data for the styleguide/showcase.
+
+## Registering a New Component
+
+1.  **Import the Registration**:
+    At the top of `src/lib/cms.ts`, import your component's registration export.
+
+    ```typescript
+    import { MyNewComponentRegistration } from '@/project/components/MyNewComponent';
+    ```
+
+2.  **Add to `componentRegistrations`**:
+    Find the `componentRegistrations` array and add your component.
+
+    ```typescript
+    const componentRegistrations = [
+      HeroRegistration,
+      // ...
+      MyNewComponentRegistration, // Add this
+    ];
+    ```
+
+    *Order does not matter for functionality, but logical grouping is helpful.*
+
+## Registering a New Collection
+
+1.  **Import the Registration**:
+
+    ```typescript
+    import { MyCollectionRegistration } from '@/project/collections/MyCollection';
+    ```
+
+2.  **Add to `collectionRegistrations`**:
+
+    ```typescript
+    const collectionRegistrations = [
+      CardGridRegistration,
+      // ...
+      MyCollectionRegistration, // Add this
+    ];
+    ```
+
+## Adding External Components
+
+External components (like 3rd party forms or iframes) use a separate registry.
+
+1.  **Import**:
+    ```typescript
+    import { MyExternalWidgetRegistration } from '@/project/externalComponents/MyExternalWidget';
+    ```
+
+2.  **Add to `externalComponentRegistrations`**:
+    ```typescript
+    const externalComponentRegistrations = [
+        ExternalIFrameRegistration,
+        MyExternalWidgetRegistration,
+    ];
+    ```
+
+## Extending Type Definitions
+
+If you introduce new Color names, Button variants, or other enumerations, update the type definitions in `src/lib/cms.ts`:
+
+```typescript
+export type CmsColourName = NonNullable<TypeComponentFields['backgroundColour']>['values'];
+// Add or modify if types are not automatically generated from Contentful
+```
+
+**Note**: Most types are generated automatically into `@/generated/types` by the `type-gen` script. You typically don't need to manually edit types unless you are defining project-specific overrides.
+
+## The Showcase
+
+Registering a component automatically adds it to the CMS Showcase (usually available at `/cms-showcase` in development). This allows you to view the component in isolation using its mock data.
+
+*   Ensure your `mock` object in the registration is complete and realistic.
+*   The showcase helps verify that `usedFields` and `UnusedChecker` are working correctly.