@se-studio/project-build 1.0.131 → 1.0.133

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

@@ -1,295 +0,0 @@
----
-name: create-cms-collection
-description: Guide for creating new CMS-driven collections (component containers) in the SE Core Product monorepo. Use this skill when asked to create a new collection or "grid" component.
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.1.0"
----
-
-# Creating CMS Collections
-
-Collections are components that contain other components (usually referred to as "Cards" in this context). They follow the same **four-layer architecture** as standard components but use specialized helpers.
-
-## Architecture Overview
-
-Like components, collections **MUST be Server Components** by default. Complex interactions (carousels, filters) must be isolated.
-
-1.  **Layer 1: Core Collection**
-    *   Named export: `Core[CollectionName]`
-    *   Iterates over `contents` array
-    *   Renders children (Cards)
-    *   Handles layout (grid, list) - **Server-side only**
-    *   If a Carousel or Filter is needed, wraps children in a Client Component.
-
-2.  **Layer 2: Wrapper Collection**
-    *   Named export: `[CollectionName]`
-    *   Wraps Core with `<Section>`
-    *   Handles outer spacing & background
-
-3.  **Layer 3: Renderer**
-    *   Default export: `[CollectionName]`
-    *   Implements `CollectionRenderer`
-    *   Wraps with `UnusedChecker`
-
-4.  **Layer 4: Registration**
-    *   Named export: `[CollectionName]Registration`
-    *   Uses `defineCollection` (NOT `defineComponent`)
-    *   Defines `usedFields` for the collection itself
-    *   Defines `cardUsedFields` for the children components
-
-## Client Component Strategy
-
-**Rule: Isolate Client Logic (Carousels, Animations, Filters).**
-
-Never make the whole collection a Client Component.
-
-*   **BAD**: `'use client'` on `MyCollection.tsx`.
-*   **GOOD**: Create `MyCollectionClient.tsx` (e.g., `<CarouselClient>`) that accepts children.
-
-### Pattern: The Client Wrapper
-
-For a carousel:
-1.  **Server Component** (`CoreMyCollection`): Renders the loop of cards.
-2.  **Client Component** (`CarouselClient`): Imports the carousel library (swiper, embla), manages state.
-3.  **Usage**: Pass the server-rendered cards as `children` to the client wrapper.
-
-```tsx
-// CoreMyCollection.tsx (Server)
-<CarouselClient>
-  {contents.map(item => <Card content={item} />)}
-</CarouselClient>
-
-// CarouselClient.tsx (Client)
-'use client';
-export const CarouselClient = ({ children }) => {
-  return <Slider>{children}</Slider>; // Client logic here
-}
-```
-
-This ensures the card content is SEO-ready and server-rendered, while only the slider mechanism is client-side.
-
-## Quick Start Template
-
-Use this template for new collections. Replace `MyCollection` with your collection name.
-
-```typescript
-import type { IContentContext } from '@se-studio/core-data-types';
-import { isComponent } from '@se-studio/core-data-types';
-import {
-  type CmsRendererConfig,
-  type CollectionRenderer,
-  cn,
-  defineCollection,
-  getPreviewFieldProps,
-  RtfOrString,
-  UnusedChecker,
-} from '@se-studio/core-ui';
-import { SectionLinks } from '@/elements/SectionLinks';
-import { Section } from '@/framework/Section';
-import type { ICollection, IComponent, IContent } from '@/lib/cms';
-import { getSizingInformation } from '@/lib/SizingInformation';
-// import MyCollectionClient from './MyCollectionClient'; // If needed
-
-// 1. Define fields for the Collection itself
-const FIELD_KEYS = [
-  'id',
-  'index',
-  'heading',
-  'body',
-  'contents', // The children
-  'links',
-  'anchor',
-  'cmsLabel',
-] as const;
-
-type Fields = Pick<ICollection, (typeof FIELD_KEYS)[number]>;
-const USED_FIELDS = new Set([...FIELD_KEYS, 'collectionType']);
-
-// 2. Define fields used by the Child Cards
-// (If the children are generic components, this might just be 'id' and 'componentType')
-const CARD_FIELD_KEYS = [
-  'id',
-  'heading',
-  'body',
-  'visual',
-  'links',
-  'cmsLabel',
-] as const;
-const CARD_USED_FIELDS = new Set([...CARD_FIELD_KEYS, 'componentType']);
-
-// Helper to render individual cards (use ChildElement for card titles – items inside a collection)
-const CardWrapper: React.FC<{
-  content: IComponent;
-  index: number;
-  contentContext: IContentContext;
-  rendererConfig: CmsRendererConfig;
-}> = ({ content, index, contentContext, rendererConfig }) => {
-  const { ChildElement, sizingInformation } = getSizingInformation(1);
-  return (
-    <div className="p-6 bg-white rounded-lg shadow-sm">
-        {content.heading && (
-          <ChildElement className={cn(sizingInformation.h3, 'mb-2')}>
-            {content.heading}
-          </ChildElement>
-        )}
-        {/* ... */}
-    </div>
-  );
-};
-
-// 3. Layer 1: Core Collection (Server Component)
-const CoreMyCollection: React.FC<
-  Fields & {
-    contentContext: IContentContext;
-    rendererConfig: CmsRendererConfig;
-    positionClassName?: string;
-  }
-> = ({
-  id,
-  index,
-  heading,
-  body,
-  contents,
-  links,
-  cmsLabel,
-  contentContext,
-  rendererConfig,
-  positionClassName,
-}) => {
-  const { Element, sizingInformation } = getSizingInformation(index);
-
-  return (
-    <div className={cn('space-y-8', positionClassName)}>
-      <div className="text-center space-y-4">
-        {heading && (
-          <Element
-            {...getPreviewFieldProps(rendererConfig, id, 'heading')}
-            className={cn(sizingInformation.h2)}
-          >
-            {heading}
-          </Element>
-        )}
-        {body && (
-          <RtfOrString
-            {...getPreviewFieldProps(rendererConfig, id, 'body')}
-            content={body}
-            className="rtf-standard"
-            rendererConfig={rendererConfig}
-            contentContext={contentContext}
-          />
-        )}
-      </div>
-
-      {contents && contents.length > 0 && (
-        <ul className="grid grid-cols-1 laptop:grid-cols-3 gap-6">
-          {contents.filter(isComponent).map((item, i) => (
-            <li key={item.id}>
-              <CardWrapper
-                content={item}
-                index={i}
-                contentContext={contentContext}
-                rendererConfig={rendererConfig}
-              />
-            </li>
-          ))}
-        </ul>
-      )}
-
-      {links && (
-        <SectionLinks
-          links={links}
-          rendererConfig={rendererConfig}
-          trackingLocation={cmsLabel}
-          analyticsContext={contentContext.analyticsContext}
-          className="justify-center"
-        />
-      )}
-    </div>
-  );
-};
-
-// 4. Layer 2: Wrapper Collection
-const MyCollection: React.FC<
-  Fields & {
-    information: IContent;
-    contentContext: IContentContext;
-    rendererConfig: CmsRendererConfig;
-  }
-> = ({ information, ...rest }) => {
-  return (
-    <Section
-      componentName={information.collectionType}
-      information={information}
-      previewHelpers={rest.rendererConfig?.previewHelpers}
-    >
-      <CoreMyCollection
-        {...rest}
-        positionClassName="col-span-full"
-      />
-    </Section>
-  );
-};
-
-// 5. Layer 3: Renderer
-const MyCollectionRenderer: CollectionRenderer<ICollection> = ({
-  information,
-  contentContext,
-  rendererConfig,
-}) => {
-  const { collectionType, ...rest } = information;
-
-  return (
-    <UnusedChecker
-      componentName={collectionType}
-      allFields={rest}
-      usedFields={USED_FIELDS}
-    >
-      <MyCollection
-        information={information}
-        contentContext={contentContext}
-        rendererConfig={rendererConfig}
-        {...(rest as Fields)}
-      />
-    </UnusedChecker>
-  );
-};
-
-export default MyCollectionRenderer;
-
-// 6. Layer 4: Registration
-export const MyCollectionRegistration = defineCollection({
-  name: 'My Collection', // Must match CMS collectionType
-  renderer: MyCollectionRenderer,
-  usedFields: USED_FIELDS,
-  cardUsedFields: CARD_USED_FIELDS,
-  mock: {
-    heading: 'Sample Collection',
-    body: 'Collection description text',
-  },
-});
-```
-
-## Checklist for Collections
-
-1.  **Define Two Sets of Fields**:
-    *   `USED_FIELDS` for the collection container (heading, body, background).
-    *   `CARD_USED_FIELDS` for the items inside `contents`.
-2.  **Use `defineCollection`**:
-    *   Instead of `defineComponent`.
-    *   Pass both `usedFields` and `cardUsedFields`.
-3.  **Heading hierarchy**:
-    *   Use **Element** from `getSizingInformation(index)` for the collection's section heading (and a class from `sizingInformation`). Use **ChildElement** from `getSizingInformation(1)` for item/card titles. Render preHeading/postHeading as **&lt;p&gt;** with a typography class, never as heading tags.
-4.  **Preview helpers**:
-    *   Use `getPreviewFieldProps(rendererConfig, id, fieldId)` from `@se-studio/core-ui` for CMS preview (do not import from cms-server – avoids circular dependency). For responsive visuals use `getPreviewResponsiveVisualFieldProps(rendererConfig, id, 'visual', 'mobileVisual')`.
-    *   For collections that fetch data: use `rendererConfig?.fetchHelpers?.getRelatedArticles?.(information, contentContext, count)` instead of importing from cms-server.
-5.  **Handle `contents`**:
-    *   Check `if (contents && contents.length > 0)`.
-    *   Filter with `contents.filter(isComponent)`.
-    *   Map over the result to render items.
-6.  **Isolate Client Logic**:
-    *   **ENSURE SERVER COMPONENT** for the main file.
-    *   If a carousel/slider/filter is needed, move that logic to `[Name]Client.tsx`.
-    *   Pass server-rendered cards as `children` to the client wrapper.
-7.  **Register**:
-    *   Add to `collectionRegistrationsList` in `src/lib/registrations.ts`. The `name` is defined only in your `defineCollection(...)` call.

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

@@ -1,250 +0,0 @@
----
-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,
-  getPreviewFieldProps,
-  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 { 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
-          {...getPreviewFieldProps(rendererConfig, id, 'heading')}
-          className={cn(sizingInformation.h1)}
-        >
-          {convertText(heading)}
-        </Element>
-      )}
-      {body && (
-        <RtfOrString
-          {...getPreviewFieldProps(rendererConfig, 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}
-          rendererConfig={rendererConfig}
-          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}
-      previewHelpers={rest.rendererConfig?.previewHelpers}
-    >
-      <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.
-    *   Use `getPreviewFieldProps(rendererConfig, id, fieldId)` from `@se-studio/core-ui` for CMS preview (do not import from cms-server – avoids circular dependency). For responsive visuals use `getPreviewResponsiveVisualFieldProps(rendererConfig, id, 'visual', 'mobileVisual')`.
-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 `componentRegistrationsList` in `src/lib/registrations.ts`. The `name` is defined only in your `defineComponent(...)` call; do not duplicate it as a Record key.

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

@@ -1,129 +0,0 @@
----
-name: create-page-route
-description: Guide for creating new Next.js App Router pages and dynamic routes in the SE Core Product framework. Use when creating CMS-driven pages, adding route segments, or setting up routing.
-license: Private
-metadata:
-  author: se-core-product
-  version: "2.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.
-
-Reference apps: **example-se2026**, **example-brightline**, **example-om1**.
-
-## Page Architecture
-
-### 1. (cms-routes) Route Group
-
-All CMS-driven pages live under `src/app/(cms-routes)/`. The layout enables dynamic params:
-
-```tsx
-// layout.tsx
-export const dynamicParams = true;
-
-export default function CmsRoutesLayout({ children }: { children: React.ReactNode }) {
-  return children;
-}
-```
-
-### 2. Route Structure
-
-| Path | File | Purpose |
-|------|------|---------|
-| `/` | `page.ts` | Home (slug: `index`) |
-| `/{slug}/` | `[level1]/page.ts` | Single-level page |
-| `/{slug1}/{slug2}/...` | `[level1]/[...slugs]/page.ts` | Multi-level pages |
-| `/articles/` | `articles/page.ts` | Articles index (uses ARTICLES_BASE from constants) |
-| `/articles/{type}/` | `articles/[articleType]/page.ts` | Article type index |
-| `/articles/{type}/{tag}/` | `articles/[articleType]/[tag]/page.ts` | Article type + tag index |
-| `/articles/{type}/{tag}/{article}/` | `articles/[articleType]/[tag]/[...slugs]/page.ts` | Individual article |
-| `/tags/`, `/tags/{tag}/` | `tags/` | Tag index (if enabled) |
-| `/people/`, `/people/{person}/` | `people/` | People (if enabled) |
-
-Base paths (e.g. `/articles` vs `/learning-hub`) come from `@/lib/constants`.
-
-### 3. appShared Pattern
-
-Route files are thin wrappers. Data-fetching and rendering logic lives in `src/appShared/`:
-
-- `pageShared.tsx` – `generatePage`, `generatePageMetadata`
-- `articleShared.tsx` – articles
-- `articleTypeShared.tsx`, `articleTypesIndexShared.tsx`, `articleTypeTagShared.tsx` – article indices
-- `customTypeShared.tsx` – custom types
-- `personShared.tsx`, `tagShared.tsx`, `tagsIndexShared.tsx`, `teamIndexShared.tsx`
-
-## Route Page Template
-
-Each route page extracts params and delegates to the appropriate appShared function:
-
-```typescript
-import type { ResolvingMetadata } from 'next';
-import { generatePage, generatePageMetadata } from '@/appShared/pageShared';
-
-export function generateStaticParams() {
-  return [];
-}
-
-async function extractDetails(props: PageProps<'/[level1]'>) {
-  const params = await props.params;
-  const { level1 } = params;
-  return { slug: level1, path: `/${level1}/` };
-}
-
-export async function generateMetadata(props: PageProps<'/[level1]'>, parent: ResolvingMetadata) {
-  const { slug, path } = await extractDetails(props);
-  return generatePageMetadata(slug, path, true, parent);
-}
-
-export default async function (props: PageProps<'/[level1]'>) {
-  const { slug, path } = await extractDetails(props);
-  return generatePage(slug, path, true);
-}
-```
-
-For the home page (`/`), use slug `'index'` and path `'/'` directly.
-
-## CmsContent Usage
-
-The appShared modules render content with:
-
-```tsx
-<CmsContent
-  contents={page.contents}
-  rendererConfig={projectRendererConfig}
-  pageContext={{ page }}
-/>
-```
-
-- `contents` – array of page/article contents (not the full page object)
-- `rendererConfig` – from `@/lib/cms-server`
-- `pageContext` – provides page/article/customType to child components
-
-For route files that only need `converterContext` or `buildInformation` (e.g. `generateStaticParams`, sitemap, path computation), import from `@/lib/converter-context` when that module exists, so you don't pull in cms-server.
-
-## Creating a Specialized Route
-
-For a route that behaves differently from standard CMS pages (e.g. search, dashboard):
-
-1. Create the route under `(cms-routes)` or a separate route group.
-2. Either create a new appShared module (if the pattern is reusable) or implement inline.
-3. Use `getPageWithErrors`, `getArticleWithErrors`, etc. from `@/lib/cms-server`.
-4. Use `projectRendererConfig` from `@/lib/cms-server`.
-5. Render with `CmsContent` using `contents`, `rendererConfig`, and `pageContext`.
-
-## Custom Layouts
-
-If a route needs a different layout (e.g. no header/footer), create `layout.tsx` in that route directory.
-
-## Troubleshooting
-
-- **404 on new route**: Re-run the dev server or build after adding a dynamic route segment.
-- **Static params missing**: Dynamic routes use `generateStaticParams() { return []; }` for on-demand rendering.
-- **Preview mode**: Handled by `draftOnly` in `@/lib/server-config`; appShared modules use it automatically.
-
-## See Also
-
-- **cms-routes-and-appshared** – Full route structure and appShared pattern
-- **lib-cms-structure** – lib directory layout and cms-server usage