@se-studio/skills 1.0.1

package/skills/se-marketing-sites-cms-routes-and-appshared/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: cms-routes-and-appshared
+description: Guide for the (cms-routes) route group and appShared pattern. Use when setting up or migrating CMS-driven routing, creating new route segments, or refactoring page structure.
+license: Private
+metadata:
+  author: se-core-product
+  version: "1.0.0"
+---
+
+# CMS Routes and appShared Pattern
+
+Reference apps: **example-se2026**, **example-brightline**, **example-om1**. (example-om1 uses `resources/`, `team/`, `topics/` instead of `articles/`, `people/`, `tags/`.)
+
+## Route Group: (cms-routes)
+
+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;
+}
+```
+
+## 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) |
+| `/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 come from `@/lib/constants` (e.g. ARTICLES_BASE = `/learning-hub` or `/articles`).
+
+## appShared Modules
+
+Route files are thin wrappers. Logic lives in `src/appShared/`:
+
+| Module | Exports | Used by |
+|--------|---------|---------|
+| `pageShared.tsx` | `generatePage`, `generatePageMetadata` | `/`, `[level1]`, `[level1]/[...slugs]` |
+| `articleShared.tsx` | `generateArticlePage`, `generateArticleMetadata` | Article detail |
+| `articleTypeShared.tsx` | `generateArticleTypePage`, `generateArticleTypeMetadata` | Article type index |
+| `articleTypesIndexShared.tsx` | `generateArticleTypesIndexPage`, `generateArticleTypesIndexMetadata` | Articles index |
+| `articleTypeTagShared.tsx` | `generateArticleTypeTagPage`, `generateArticleTypeTagMetadata` | Article type + tag index |
+| `customTypeShared.tsx` | `generateCustomTypePage`, `generateCustomTypeMetadata` | Custom types |
+| `personShared.tsx` | `generatePersonPage`, `generatePersonMetadata` | Person page |
+| `tagShared.tsx` | `generateTagPage`, `generateTagMetadata` | Tag index |
+| `tagsIndexShared.tsx` | `generateTagsIndexPage`, `generateTagsIndexMetadata` | Tags index |
+| `teamIndexShared.tsx` | `generateTeamIndexPage`, `generateTeamIndexMetadata` | People index |
+
+## Route Page Pattern
+
+Each route page:
+
+1. Exports `generateStaticParams() { return []; }` for dynamic routes
+2. Defines `extractDetails(props)` to derive slug/path from params
+3. Exports `generateMetadata(props, parent)` calling the shared metadata function
+4. Exports default async function calling the shared page 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 article routes, use `converterContext.urlCalculators.article`, `articleType`, `articleTypeTag` to compute the path. Import `converterContext` from `@/lib/converter-context` when that module exists (so route files don't pull in cms-server); otherwise from `@/lib/cms-server`.
+
+## See Also
+
+- **create-page** – Creating new pages and routes
+- **lib-cms-structure** – lib directory layout

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

@@ -0,0 +1,295 @@
+---
+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

@@ -0,0 +1,250 @@
+---
+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.