@webiny/mcp 0.0.0-unstable.f6dc066313

package/skills/website-builder/SKILL.md

@@ -0,0 +1,384 @@
+---
+name: webiny-website-builder
+context: webiny-extensions
+description: >
+  Building Website Builder editor components, theming, and CMS integration using
+  @webiny/website-builder-nextjs. Use this skill when the developer wants to create editor
+  components for the Website Builder, register components with createComponent, define
+  configurable inputs (text, number, boolean, color, select, file, slot, lexical),
+  set up component groups, customize the theme (CSS variables, createTheme, Tailwind bridge,
+  fonts), build Server Components that fetch CMS data, or understand the WB architecture
+  (Admin iframe + Next.js). Also use for anything related to the Website Builder starter kit.
+---
+
+# Website Builder
+
+## TL;DR
+
+The Webiny Website Builder uses a unique architecture: the Admin editor loads your Next.js app inside an iframe. All component code and styles live in your Next.js project -- Webiny only stores the page structure (which components and what input values). You build editor components with `@webiny/website-builder-nextjs`, register them via `createComponent()`, define configurable inputs, and manage theming through CSS custom properties and `createTheme()`.
+
+## Architecture
+
+```
++----------------------------------------------------------+
+|  Webiny Admin                                            |
+|  +----------------------------------------------------+  |
+|  |  Website Builder Editor                            |  |
+|  |                                                    |  |
+|  |   sidebar     +------------------------------+     |  |
+|  |   (inputs)    |  your Next.js app (iframe)   |     |  |
+|  |               |  real components             |     |  |
+|  |               |  real styles                 |     |  |
+|  |               +------------------------------+     |  |
+|  +----------------------------------------------------+  |
++----------------------------------------------------------+
+                        postMessage (SDK)
++----------------------------------------------------------+
+|  Your Next.js App (running separately)                   |
+|  @webiny/website-builder-nextjs SDK installed            |
++----------------------------------------------------------+
+```
+
+Key implications:
+- **No style clashes** -- your components, your styles, full ownership
+- **Genuine WYSIWYG** -- editors see your real app, not a simulation
+- **Framework-owned code** -- all React components live in your Next.js repo
+
+## Setup
+
+### Starter Kit
+
+```bash
+git clone https://github.com/webiny/website-builder-nextjs.git my-website
+cd my-website
+npm install
+```
+
+Ensure `@webiny/website-builder-nextjs` and `@webiny/sdk` versions in `package.json` match your Webiny version (`yarn webiny --version` in your Webiny project).
+
+### Environment Variables
+
+```dotenv
+# .env
+NEXT_PUBLIC_WEBSITE_BUILDER_API_KEY=your_wb_api_key
+NEXT_PUBLIC_WEBSITE_BUILDER_API_HOST=https://your-cloudfront-url.cloudfront.net
+NEXT_PUBLIC_WEBSITE_BUILDER_ADMIN_HOST=http://localhost:3001
+NEXT_PUBLIC_WEBSITE_BUILDER_API_TENANT=root
+```
+
+## Editor Components
+
+An editor component has two parts:
+1. **React component** -- renders the UI, receives configured values via `inputs` prop
+2. **Manifest** -- metadata (name, label, group, inputs) that tells the editor about the component
+
+### Creating a Component
+
+```tsx
+// src/editorComponents/Banner.tsx
+import React from "react";
+import { ComponentProps } from "@webiny/website-builder-nextjs";
+
+interface BannerInputs {
+    headline: string;
+    ctaLabel: string;
+    ctaUrl: string;
+}
+
+export function Banner({ inputs: { headline, ctaLabel, ctaUrl } }: ComponentProps<BannerInputs>) {
+    return (
+        <div className="bg-primary py-12 px-6 text-center text-white">
+            <h2 className="text-3xl font-bold mb-4">{headline}</h2>
+            {ctaLabel && ctaUrl && (
+                <a
+                    href={ctaUrl}
+                    className="inline-block bg-white text-primary font-semibold px-6 py-3 rounded-md"
+                >
+                    {ctaLabel}
+                </a>
+            )}
+        </div>
+    );
+}
+```
+
+### Registering Components
+
+The `editorComponents` array must be in a `"use client"` file:
+
+```tsx
+// src/editorComponents/index.tsx
+"use client";
+import { createComponent, createTextInput } from "@webiny/website-builder-nextjs";
+import { Banner } from "./Banner";
+
+export const editorComponents = [
+    createComponent(Banner, {
+        name: "Custom/Banner",
+        label: "Banner",
+        group: "custom",
+        inputs: [
+            createTextInput({
+                name: "headline",
+                label: "Headline",
+                description: "The main headline text.",
+                defaultValue: "Ready to get started?"
+            }),
+            createTextInput({
+                name: "ctaLabel",
+                label: "Button Label",
+                defaultValue: "Get started"
+            }),
+            createTextInput({
+                name: "ctaUrl",
+                label: "Button URL",
+                defaultValue: "/"
+            })
+        ]
+    })
+];
+```
+
+**Important:** The `"use client"` directive is required because component registration communicates with the editor via the browser. However, components imported here can still be Server Components if they don't have their own `"use client"` directive.
+
+### Component Name Convention
+
+Use a namespaced string: `"YourNamespace/ComponentName"`. Component names are stored in page documents -- treat them as **stable identifiers**; renaming breaks existing pages.
+
+## Input Types
+
+| Factory Function | Use Case |
+|---|---|
+| `createTextInput` | Single-line text, URLs, labels |
+| `createLongTextInput` | Multi-line text |
+| `createNumberInput` | Numeric values |
+| `createBooleanInput` | Toggle / checkbox |
+| `createColorInput` | Color picker |
+| `createDateInput` | Date / date-time picker |
+| `createSelectInput` | Dropdown with predefined options |
+| `createRadioInput` | Radio button group |
+| `createTagsInput` | List of tags |
+| `createObjectInput` | Nested object (group of sub-inputs) |
+| `createLexicalInput` | Rich text (Lexical editor) |
+| `createFileInput` | File / media picker |
+| `createSlotInput` | Slot for nesting other components |
+
+Each factory accepts: `name`, `label`, `description`, `defaultValue`, and type-specific options.
+
+## Component Groups
+
+Groups organize the editor's component palette:
+
+```typescript
+// src/contentSdk/groups.ts
+import { registerComponentGroup, type ComponentManifest } from "@webiny/website-builder-nextjs";
+
+export const registerComponentGroups = () => {
+    registerComponentGroup({
+        name: "basic",
+        label: "Basic",
+        description: "Components for simple content creation"
+    });
+    registerComponentGroup({
+        name: "custom",
+        label: "Custom",
+        description: "Assorted custom components",
+        filter: (component: ComponentManifest) => !component.group
+    });
+};
+```
+
+The `filter` option creates a catch-all group for components without an explicit `group`.
+
+## Theming
+
+The theme system has three files that work together:
+
+### 1. `theme.css` -- CSS Custom Properties
+
+```css
+/* src/theme/theme.css */
+@import "@webiny/website-builder-nextjs/lexical.css";
+
+:root {
+    --wb-theme-color-primary: #4632f5;
+    --wb-theme-color-secondary: #00ccb0;
+    --wb-theme-color-background: #ffffff;
+    --wb-theme-color-surface: #f9f9f9;
+    --wb-theme-color-text-base: #0a0a0a;
+    --wb-theme-color-text-muted: #6b7280;
+    --wb-theme-color-border: #e5e7eb;
+    --wb-theme-font-family: "Inter", sans-serif;
+}
+
+.wb-heading-1 {
+    font-weight: 700;
+    line-height: 1.2;
+    font-size: clamp(2rem, 1.5rem + 1.5vw, 3rem);
+}
+
+.wb-paragraph-1 {
+    font-weight: 400;
+    line-height: 1.6;
+    font-size: clamp(0.95rem, 0.9rem + 0.25vw, 1rem);
+}
+```
+
+### 2. `theme.ts` -- Theme Registration
+
+```typescript
+// src/theme/theme.ts
+import { createTheme } from "@webiny/website-builder-nextjs";
+
+declare const __THEME_CSS__: string;
+export const css = __THEME_CSS__;
+
+export const theme = createTheme({
+    css,
+    fonts: ["https://fonts.googleapis.com/css2?family=Inter:wght@100..900&display=swap"],
+    colors: [
+        { id: "color-primary", label: "Primary", value: "var(--wb-theme-color-primary)" },
+        { id: "color-secondary", label: "Secondary", value: "var(--wb-theme-color-secondary)" },
+        { id: "color-background", label: "Background", value: "var(--wb-theme-color-background)" },
+        { id: "color-text-base", label: "Text", value: "var(--wb-theme-color-text-base)" }
+    ],
+    typography: {
+        headings: [
+            { id: "heading1", label: "Heading 1", tag: "h1", className: "wb-heading-1" }
+        ],
+        paragraphs: [
+            { id: "paragraph1", label: "Paragraph 1", tag: "p", className: "wb-paragraph-1" }
+        ],
+        quotes: [
+            { id: "quote", label: "Quote", tag: "blockquote", className: "wb-blockquote-1" }
+        ],
+        lists: [
+            { id: "list1", label: "List 1", tag: "ul", className: "wb-unordered-list-1" }
+        ]
+    }
+});
+```
+
+- `colors` populates the editor's color picker
+- `typography` populates the editor's typography toolbar
+- `fonts` injects fonts into the editor iframe
+
+### 3. `tailwind.css` -- Tailwind Bridge
+
+```css
+/* src/theme/tailwind.css */
+@import "tailwindcss";
+
+@theme inline {
+    --font-sans: InterVariable, sans-serif;
+    --color-primary: var(--wb-theme-color-primary);
+    --color-secondary: var(--wb-theme-color-secondary);
+    --color-text-base: var(--wb-theme-color-text-base);
+}
+```
+
+This bridges WB CSS variables to Tailwind tokens, enabling `bg-primary`, `text-primary`, etc. in your components.
+
+### Changing Fonts (4 Files)
+
+When switching fonts, update all four places:
+
+| File | What to Update |
+|---|---|
+| `src/app/layout.tsx` | Font import and config (e.g., `import { Geist } from "next/font/google"`) |
+| `src/theme/tailwind.css` | `--font-sans` token |
+| `src/theme/theme.css` | `--wb-theme-font-family` variable |
+| `src/theme/theme.ts` | `fonts` array URL (must include same weight range as layout.tsx) |
+
+## Server Components Fetching CMS Data
+
+Build editor components that fetch data from the Headless CMS at render time:
+
+```tsx
+// src/editorComponents/ProductListing.tsx
+import React from "react";
+import { ComponentProps } from "@webiny/website-builder-nextjs";
+import { sdk } from "@/lib/webiny";
+import type { Product } from "@/lib/types";
+import type { CmsEntryData } from "@webiny/sdk";
+
+interface ProductListingInputs {
+    heading: string;
+    limit: string;
+}
+
+export async function ProductListing({
+    inputs: { heading, limit }
+}: ComponentProps<ProductListingInputs>) {
+    const parsedLimit = parseInt(limit, 10) || 6;
+
+    const result = await sdk.cms.listEntries<Product>({
+        modelId: "product",
+        limit: parsedLimit,
+        sort: ["values.name_ASC"]
+    });
+
+    if (!result.isOk()) {
+        return <div className="text-red-600">Failed to load products: {result.error.message}</div>;
+    }
+
+    const products: CmsEntryData<Product>[] = result.value.data;
+
+    return (
+        <section className="py-12 px-6">
+            {heading && <h2 className="text-3xl font-bold text-center mb-8">{heading}</h2>}
+            <ul className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3 max-w-5xl mx-auto">
+                {products.map(product => (
+                    <li key={product.id} className="border rounded-lg p-6">
+                        <h3 className="text-xl font-semibold">{product.values.name}</h3>
+                        <p className="text-lg font-bold mt-2">${product.values.price.toFixed(2)}</p>
+                    </li>
+                ))}
+            </ul>
+        </section>
+    );
+}
+```
+
+Register it (async Server Components work even though `index.tsx` is `"use client"`):
+
+```tsx
+createComponent(ProductListing, {
+    name: "Custom/ProductListing",
+    label: "Product Listing",
+    inputs: [
+        createTextInput({ name: "heading", label: "Section Heading", defaultValue: "Our Products" }),
+        createTextInput({ name: "limit", label: "Number of products", defaultValue: "6" })
+    ]
+})
+```
+
+To use the Headless CMS SDK, initialize it in `src/lib/webiny.ts` with a **Read API** key (see the `webiny-sdk` skill).
+
+## Data Flow
+
+```
+Editor -> saves page document to Webiny API
+           (document: component name + input values)
+
+Next.js request/build
+  -> contentSdk.getPage("/slug") -> returns page document
+  -> DocumentRenderer matches component name to React component
+  -> Component renders (Server Component may fetch CMS data)
+```
+
+## Quick Reference
+
+```
+SDK package:      @webiny/website-builder-nextjs
+Component type:   import { ComponentProps } from "@webiny/website-builder-nextjs";
+Registration:     createComponent(ReactComponent, { name, label, inputs })
+Input factories:  createTextInput, createNumberInput, createBooleanInput, etc.
+Theme:            createTheme({ css, fonts, colors, typography })
+Groups:           registerComponentGroup({ name, label, description })
+```
+
+## Related Skills
+
+- `webiny-sdk` -- Using the Headless CMS SDK inside Website Builder components
+- `project-structure` -- Webiny project setup and extension registration