@webiny/mcp 6.0.0 → 6.1.0-beta.1

package/skills/admin/admin-architect/SKILL.md

@@ -0,0 +1,389 @@
+---
+name: webiny-admin-architect
+context: webiny-extensions
+description: >
+  Admin-side architecture patterns for Webiny extensions. Use this skill when building
+  frontend features with headless features (UseCase/Repository/Gateway), presentation
+  features (Presenter/ViewModel/hooks/components), MobX-based presenters, RegisterFeature,
+  and Admin BuildParams. Covers the admin/ directory structure for both features/ and
+  presentation/ layers.
+---
+
+# Admin Architecture Patterns
+
+## TL;DR
+
+Admin extensions are React components that register headless features (business logic with no UI) and presentation features (MobX presenters, React hooks, components). Headless features live in `admin/features/` and follow **UseCase → Repository → Gateway** layering. Presentation features live in `admin/presentation/` and add a **Presenter** (MobX view model) layer on top. Both use `createFeature` and `createAbstraction` from `webiny/admin`.
+
+**All features — both headless and presentation — MUST provide a `resolve` function** in `createFeature`. This is how the `useFeature` hook accesses resolved instances from the DI container. Without `resolve`, the feature cannot be consumed from React.
+
+## Admin Directory Structure
+
+```
+admin/
+├── Extension.tsx         # Admin entry point (React component)
+├── features/             # Headless features (business logic, no UI)
+│   └── EnableThing/
+│       ├── abstractions.ts
+│       ├── EnableThingUseCase.ts
+│       ├── EnableThingRepository.ts
+│       ├── EnableThingGateway.ts
+│       └── feature.ts
+└── presentation/         # Presentation layer (hooks, components, presenters)
+    └── CurrentThing/
+        ├── abstractions.ts   # Presenter + ViewModel interfaces
+        ├── CurrentThingPresenter.ts    # MobX-based view model
+        ├── useCurrentThing.ts          # React hook for consumers
+        ├── feature.ts                  # createFeature registration
+        └── components/                 # React UI components
+```
+
+## Admin Extension Entry Point
+
+The Admin entry point is a React component that registers features, providers, UI decorators, and config:
+
+```tsx
+// src/admin/Extension.tsx
+import React from "react";
+import { AdminConfig, RegisterFeature } from "webiny/admin";
+import { CurrentThingFeature } from "./presentation/CurrentThing/feature.js";
+import { EnableThingFeature } from "./features/EnableThing/index.js";
+import { CurrentThingProvider } from "./presentation/CurrentThing/CurrentThingProvider.js";
+import { ThingListView } from "./presentation/ThingListView/ThingListView.js";
+
+export const Extension = () => {
+  return (
+    <>
+      {/* Register headless features (use cases, repositories, gateways) */}
+      <RegisterFeature feature={EnableThingFeature} />
+
+      {/* Register presentation features (presenters, view models) */}
+      <RegisterFeature feature={CurrentThingFeature} />
+
+      {/* Providers and UI components */}
+      <CurrentThingProvider />
+      <ThingListView />
+
+      {/* Admin config (menus, routes, etc.) */}
+      <AdminConfig>{/* Menu items, route definitions, etc. */}</AdminConfig>
+    </>
+  );
+};
+```
+
+## Headless Features (`features/`)
+
+Headless features contain business logic with no UI — use cases, repositories, and gateways. They follow the same layering as API features but use `webiny/admin` imports.
+
+### Abstractions
+
+```ts
+// src/admin/features/EnableThing/abstractions.ts
+import { createAbstraction } from "webiny/admin";
+
+export interface IEnableThingUseCase {
+  execute(id: string): Promise<void>;
+}
+
+export const EnableThingUseCase = createAbstraction<IEnableThingUseCase>("EnableThingUseCase");
+
+export namespace EnableThingUseCase {
+  export type Interface = IEnableThingUseCase;
+}
+
+export interface IEnableThingRepository {
+  execute(id: string): Promise<void>;
+}
+
+export const EnableThingRepository =
+  createAbstraction<IEnableThingRepository>("EnableThingRepository");
+
+export namespace EnableThingRepository {
+  export type Interface = IEnableThingRepository;
+}
+
+export interface IEnableThingGateway {
+  enableThing(id: string): Promise<boolean>;
+}
+
+export const EnableThingGateway = createAbstraction<IEnableThingGateway>("EnableThingGateway");
+
+export namespace EnableThingGateway {
+  export type Interface = IEnableThingGateway;
+}
+```
+
+### Feature Registration
+
+Headless features **must** provide a `resolve` function that returns the resolved use case (or multiple exports). This is what makes the feature consumable via `useFeature()` in the presentation layer:
+
+```ts
+// src/admin/features/EnableThing/feature.ts
+import { createFeature } from "webiny/admin";
+import { EnableThingUseCase as UseCase } from "./abstractions.js";
+import { EnableThingUseCase } from "./EnableThingUseCase.js";
+import { EnableThingRepository } from "./EnableThingRepository.js";
+import { EnableThingGateway } from "./EnableThingGateway.js";
+
+export const EnableThingFeature = createFeature({
+  name: "EnableThing",
+  register(container) {
+    container.register(EnableThingUseCase);
+    container.register(EnableThingRepository).inSingletonScope();
+    container.register(EnableThingGateway).inSingletonScope();
+  },
+  resolve(container) {
+    return {
+      useCase: container.resolve(UseCase)
+    };
+  }
+});
+```
+
+## The `useFeature` Hook — Bridging DI and React
+
+`useFeature` is the standard way to access headless features from React. It resolves the feature from the DI container and returns whatever `resolve` returned:
+
+```tsx
+import { useFeature } from "webiny/admin";
+import { EnableThingFeature } from "~/features/EnableThing/feature.js";
+
+// In a presentation hook or component:
+const { useCase } = useFeature(EnableThingFeature);
+await useCase.execute(id);
+```
+
+Presentation hooks wrap `useFeature` to provide a clean, typed API to React components:
+
+```tsx
+// src/admin/presentation/EnableThing/useEnableThing.ts
+import { useFeature } from "webiny/admin";
+import { EnableThingFeature } from "~/features/EnableThing/feature.js";
+
+export function useEnableThing() {
+  const { useCase } = useFeature(EnableThingFeature);
+
+  return {
+    enableThing: useCase.execute.bind(useCase)
+  };
+}
+```
+
+### Common `useFeature` patterns
+
+**Multiple features in one hook:**
+
+```tsx
+export function useAuthentication() {
+  const { useCase: logInUseCase } = useFeature(LogInFeature);
+  const { useCase: logOutUseCase } = useFeature(LogOutFeature);
+
+  return {
+    login: logInUseCase.execute.bind(logInUseCase),
+    logout: logOutUseCase.execute.bind(logOutUseCase)
+  };
+}
+```
+
+**MobX reactive state synced to React:**
+
+```tsx
+export function useIdentity() {
+  const { identityContext } = useFeature(IdentityContextFeature);
+
+  const [identity, setIdentity] = useState(identityContext.getIdentity());
+
+  useEffect(() => {
+    return autorun(() => {
+      setIdentity(identityContext.getIdentity());
+    });
+  }, [identityContext]);
+
+  return { identity, isAuthenticated: identity.isAuthenticated };
+}
+```
+
+## Presentation Features (`presentation/`)
+
+Presentation features contain the UI layer — a **Presenter** (MobX view model) that produces a ViewModel for React, plus hooks and components. The Presenter typically depends on a **headless feature abstraction** (use case or service) for data and actions — it does NOT duplicate the repository/gateway layering.
+
+### Typical Pattern: Presenter depends on a headless feature
+
+The Presenter injects a headless feature's use case or service as a DI dependency:
+
+```ts
+// src/admin/presentation/CurrentThing/abstractions.ts
+import { createAbstraction } from "webiny/admin";
+import type { MyEntity } from "~/shared/MyEntity.js";
+
+export interface ICurrentThingVm {
+  loading: boolean;
+  entity: MyEntity | undefined;
+  error: Error | undefined;
+}
+
+export interface ICurrentThingPresenter {
+  vm: ICurrentThingVm;
+  init(): void;
+}
+
+export const CurrentThingPresenter =
+  createAbstraction<ICurrentThingPresenter>("CurrentThingPresenter");
+
+export namespace CurrentThingPresenter {
+  export type Interface = ICurrentThingPresenter;
+  export type ViewModel = ICurrentThingVm;
+}
+```
+
+```ts
+// src/admin/presentation/CurrentThing/feature.ts
+import { createFeature } from "webiny/admin";
+import { CurrentThingPresenter as PresenterAbstraction } from "./abstractions.js";
+import { CurrentThingPresenter } from "./CurrentThingPresenter.js";
+
+export const CurrentThingFeature = createFeature({
+  name: "CurrentThing",
+  register(container) {
+    container.register(CurrentThingPresenter);
+  },
+  resolve(container) {
+    return {
+      presenter: container.resolve(PresenterAbstraction)
+    };
+  }
+});
+```
+
+The Presenter implementation injects the headless feature's abstraction (e.g., a use case):
+
+```ts
+// src/admin/presentation/CurrentThing/CurrentThingPresenter.ts
+import { GetThingUseCase } from "~/features/GetThing/abstractions.js";
+
+class CurrentThingPresenterImpl implements CurrentThingPresenter.Interface {
+  vm: CurrentThingPresenter.ViewModel = { loading: false, entity: undefined, error: undefined };
+
+  constructor(private getThingUseCase: GetThingUseCase.Interface) {}
+
+  async init() {
+    this.vm.loading = true;
+    const result = await this.getThingUseCase.execute();
+    // ... update vm
+  }
+}
+
+export default CurrentThingPresenter.createImplementation({
+  implementation: CurrentThingPresenterImpl,
+  dependencies: [GetThingUseCase]
+});
+```
+
+### One-off Pattern: Presenter with its own repository/gateway
+
+On rare occasions, when a presentation feature does not contain reusable business logic (no headless feature to depend on), the presentation feature can contain its own repository and gateway alongside the presenter:
+
+```ts
+// src/admin/presentation/Dashboard/feature.ts — one-off, no headless feature
+import { createFeature } from "webiny/admin";
+import { DashboardPresenter as PresenterAbstraction } from "./abstractions.js";
+import { DashboardPresenter } from "./DashboardPresenter.js";
+import { DashboardRepository } from "./DashboardRepository.js";
+import { DashboardGateway } from "./DashboardGateway.js";
+
+export const DashboardFeature = createFeature({
+  name: "Dashboard",
+  register(container) {
+    container.register(DashboardPresenter);
+    container.register(DashboardRepository).inSingletonScope();
+    container.register(DashboardGateway).inSingletonScope();
+  },
+  resolve(container) {
+    return {
+      presenter: container.resolve(PresenterAbstraction)
+    };
+  }
+});
+```
+
+> **Prefer the typical pattern.** Only use the one-off pattern when the business logic is truly presentation-specific and will never be reused by other features.
+
+## Reading Admin BuildParams
+
+There are two ways to read build parameters on the Admin side:
+
+### 1. Via `useBuildParams()` hook — in React hooks and components
+
+```tsx
+import { useBuildParams } from "webiny/admin/build-params";
+
+const MyComponent = () => {
+  const buildParams = useBuildParams();
+  // Returns T | null — always handle null
+  const dashboardUrl = buildParams.get<string>("DASHBOARD_URL");
+
+  return dashboardUrl ? <a href={dashboardUrl}>Dashboard</a> : null;
+};
+```
+
+### 2. Via `BuildParams` DI abstraction — in Presenters, Repositories, Gateways
+
+When you need build params inside a DI-managed class (Presenter, Repository, etc.), inject `BuildParams` as a dependency:
+
+```ts
+import { BuildParams } from "webiny/admin/build-params";
+
+class MyPresenterImpl implements MyPresenter.Interface {
+  constructor(private buildParams: BuildParams.Interface) {}
+
+  get vm() {
+    const apiUrl = this.buildParams.get<string>("MY_API_URL");
+    // ...
+  }
+}
+
+export default MyPresenter.createImplementation({
+  implementation: MyPresenterImpl,
+  dependencies: [BuildParams]
+});
+```
+
+> **Note:** `buildParams.get<T>()` returns `T | null` — always handle the null case.
+
+> BuildParam _declarations_ (`<Admin.BuildParam>`) live in the top-level extension component — see the **webiny-full-stack-architect** skill.
+
+## Core APIs
+
+### `createAbstraction<T>(name: string)`
+
+Creates a typed DI token for admin-side abstractions.
+
+| Import  | `import { createAbstraction } from "webiny/admin"` |
+| ------- | -------------------------------------------------- |
+| Returns | `Abstraction<T>`                                   |
+
+### `createFeature(def)`
+
+Creates a feature definition for the admin runtime.
+
+| Import                    | `import { createFeature } from "webiny/admin"`                   |
+| ------------------------- | ---------------------------------------------------------------- |
+| `def.name`                | Unique feature name (convention: `"AppName/FeatureName"`)        |
+| `def.register(container)` | Called at startup with the DI `Container` instance               |
+| `def.resolve(container)`  | **Required.** Resolves abstractions for `useFeature()` consumers |
+
+## Key Rules
+
+1. **Abstractions first** — any new business logic MUST be encapsulated in `createAbstraction` + `createFeature`.
+2. **Namespace convention** — every abstraction exports `namespace MyAbstraction { export type Interface = ...; }`.
+3. **`resolve` is mandatory** — every `createFeature` (headless or presentation) MUST provide a `resolve` function. This is how `useFeature()` accesses resolved instances from DI.
+4. **Headless vs Presentation** — business logic (use cases, repos, gateways) goes in `features/`; UI layer (presenters, hooks, components) goes in `presentation/`.
+5. **Scoping** — use cases = transient (default), repositories/gateways = singleton (`.inSingletonScope()`).
+6. **`useFeature` is the bridge** — presentation hooks call `useFeature(SomeFeature)` to get resolved exports, then wrap them for React consumption.
+7. **Import extensions** — always use `.js` extensions in import paths (ESM).
+
+## Related Skills
+
+- **webiny-full-stack-architect** — Top-level component, shared domain layer, BuildParam declarations
+- **webiny-dependency-injection** — The `createImplementation` DI pattern and injectable services
+- **webiny-admin-ui-extensions** — Admin UI customization, decorators, theming, forms, and config

package/skills/admin/ui-extensions/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: webiny-admin-ui-extensions
+context: webiny-extensions
+description: >
+  Customizing the Webiny Admin UI -- white-labeling, custom data list columns, page-type forms,
+  and Lexical editor plugins. Use this skill when the developer wants to change branding (logo,
+  title, theme colors), add custom columns to content entry list views, create custom forms
+  for Website Builder page types, or extend the Lexical rich text editor. Covers AdminConfig,
+  ContentEntryListConfig, Browser.Table.Column, Bind, useForm, and form validation.
+---
+
+# Admin UI Extensions
+
+## TL;DR
+
+Admin extensions customize the Webiny Admin application. There are three main categories: **white-labeling** (logos, titles, theme colors), **custom data list columns** (adding columns to content entry tables), and **custom page-type forms** (custom form fields for Website Builder page types). All are React components registered via `<Admin.Extension>` in `webiny.config.tsx`.
+
+## White-Labeling
+
+### Theme Colors
+
+```tsx
+// extensions/AdminBranding/AdminTheme.tsx
+import React from "react";
+import { AdminConfig } from "webiny/admin/configs";
+
+const { Theme } = AdminConfig;
+
+const AdminTheme = () => {
+  return (
+    <AdminConfig.Public>
+      <Theme.Color palette={"primary"} color={"purple"} />
+      <Theme.Color palette={"secondary"} color={"green"} />
+    </AdminConfig.Public>
+  );
+};
+
+export default AdminTheme;
+```
+
+- `palette` -- `"primary"`, `"secondary"`, `"neutral"`, etc.
+- `color` -- any CSS color value: named colors, hex (`"#6B46C1"`), or RGB.
+
+### Logo and Title
+
+```tsx
+// extensions/AdminBranding/AdminTitleLogo.tsx
+import React from "react";
+import { AdminConfig } from "webiny/admin/configs";
+import squareLogo from "./logo.png";
+import horizontalLogo from "./logo.png";
+
+const { Title, Logo } = AdminConfig;
+
+const AdminTitleLogo = () => {
+  return (
+    <AdminConfig.Public>
+      <Title value={"ACME Corp"} />
+      <Logo
+        squareLogo={<img src={squareLogo} alt={"ACME Corp"} />}
+        horizontalLogo={<img src={horizontalLogo} alt={"ACME Corp"} />}
+      />
+    </AdminConfig.Public>
+  );
+};
+
+export default AdminTitleLogo;
+```
+
+Register both:
+
+```tsx
+<Admin.Extension src={"/extensions/AdminBranding/AdminTheme.tsx"} />
+<Admin.Extension src={"/extensions/AdminBranding/AdminTitleLogo.tsx"} />
+```
+
+### Available AdminConfig Components
+
+| Component                                        | Purpose                         |
+| ------------------------------------------------ | ------------------------------- |
+| `<Theme.Color palette="..." color="..." />`      | Set theme color palette         |
+| `<Title value="..." />`                          | Set the Admin app title         |
+| `<Logo squareLogo={...} horizontalLogo={...} />` | Set square and horizontal logos |
+
+All must be wrapped in `<AdminConfig.Public>`.
+
+## Custom Data List Columns
+
+Add custom columns to the content entry list view in the Admin UI. Columns can be restricted to specific content models.
+
+### Full Example: Email Columns for Contact Submissions
+
+```tsx
+// extensions/contactSubmission/EmailEntryListColumn.tsx
+import React from "react";
+import { ContentEntryListConfig } from "webiny/admin/cms/entry/list";
+
+const { Browser } = ContentEntryListConfig;
+
+// Custom cell component for the Email Type column
+interface ContactSubmissionTableRow {
+  values: {
+    emailType: "work" | "personal";
+  };
+}
+
+export const EmailTypeCell = () => {
+  const { useTableRow, isFolderRow } = ContentEntryListConfig.Browser.Table.Column;
+  const { row } = useTableRow<ContactSubmissionTableRow>();
+
+  if (isFolderRow(row)) {
+    return <>{"-"}</>;
+  }
+
+  const emailType = row.data.values.emailType;
+  return emailType === "work" ? <>{"Business"}</> : <>{"Personal"}</>;
+};
+
+// Main extension component
+const EmailEntryListColumn = () => {
+  return (
+    <ContentEntryListConfig>
+      {/* Simple column using path (no custom cell needed) */}
+      <Browser.Table.Column
+        name={"email"}
+        after={"name"}
+        path={"values.email"}
+        header={"Email"}
+        modelIds={["contactSubmission"]}
+      />
+      {/* Custom cell column */}
+      <Browser.Table.Column
+        name={"emailType"}
+        after={"email"}
+        header={"Email Type"}
+        modelIds={["contactSubmission"]}
+        cell={<EmailTypeCell />}
+      />
+    </ContentEntryListConfig>
+  );
+};
+
+export default EmailEntryListColumn;
+```
+
+Register:
+
+```tsx
+<Admin.Extension src={"/extensions/contactSubmission/EmailEntryListColumn.tsx"} />
+```
+
+### Column Props Reference
+
+| Prop       | Type           | Description                                                               |
+| ---------- | -------------- | ------------------------------------------------------------------------- |
+| `name`     | `string`       | Unique column identifier                                                  |
+| `header`   | `string`       | Column header text                                                        |
+| `path`     | `string`       | Dot-path to the data field (e.g., `"values.email"`) -- for simple columns |
+| `cell`     | `ReactElement` | Custom React component for complex rendering                              |
+| `modelIds` | `string[]`     | Restrict column to specific content models                                |
+| `after`    | `string`       | Position this column after another column by name                         |
+
+### Custom Cell Hooks
+
+Inside a custom `cell` component:
+
+- `useTableRow<T>()` -- access the full row data, typed with your interface
+- `isFolderRow(row)` -- check if the current row is a folder (return placeholder content)
+
+## Custom Page-Type Forms
+
+Create custom forms for Website Builder page types using Webiny's form components:
+
+```tsx
+// extensions/customPageTypes/RetailPageForm.tsx
+import React from "react";
+import { Grid, Input, Select } from "webiny/admin/ui";
+import { pagePathFromTitle } from "webiny/admin/website-builder";
+import type { FormApi } from "webiny/admin/form";
+import { Bind, UnsetOnUnmount, useForm, validation } from "webiny/admin/form";
+
+const generatePath = (form: FormApi) => () => {
+  const title = form.getValue("properties.title");
+  const language = form.getValue("extensions.language");
+
+  const titlePath = pagePathFromTitle(title ?? "");
+  const parts = [language, titlePath].filter(Boolean);
+
+  form.setValue("properties.path", `/${parts.join("/")}`);
+};
+
+export const RetailPageForm = () => {
+  const form = useForm();
+
+  return (
+    <>
+      <Grid.Column span={12}>
+        <UnsetOnUnmount name={"properties.title"}>
+          <Bind name={"properties.title"} validators={[validation.create("required")]}>
+            <Input label={"Title"} onBlur={generatePath(form)} />
+          </Bind>
+        </UnsetOnUnmount>
+      </Grid.Column>
+      <Grid.Column span={12}>
+        <UnsetOnUnmount name={"extensions.language"}>
+          <Bind
+            name={"extensions.language"}
+            validators={[validation.create("required")]}
+            afterChange={generatePath(form)}
+          >
+            <Select
+              placeholder={"Select a language"}
+              label={"Language"}
+              options={[
+                { label: "English", value: "en" },
+                { label: "German", value: "de" },
+                { label: "French", value: "fr" }
+              ]}
+            />
+          </Bind>
+        </UnsetOnUnmount>
+      </Grid.Column>
+      <Grid.Column span={12}>
+        <UnsetOnUnmount name={"properties.path"}>
+          <Bind name={"properties.path"} validators={[validation.create("required")]}>
+            <Input label={"Path"} />
+          </Bind>
+        </UnsetOnUnmount>
+      </Grid.Column>
+    </>
+  );
+};
+```
+
+### Form Components Reference
+
+| Component / Hook | Import                | Purpose                                             |
+| ---------------- | --------------------- | --------------------------------------------------- |
+| `Bind`           | `"webiny/admin/form"` | Bind a form field to a name path                    |
+| `useForm()`      | `"webiny/admin/form"` | Access the form API (`getValue`, `setValue`)        |
+| `validation`     | `"webiny/admin/form"` | Create validators (`validation.create("required")`) |
+| `UnsetOnUnmount` | `"webiny/admin/form"` | Clear the field value when the component unmounts   |
+| `Grid.Column`    | `"webiny/admin/ui"`   | Layout grid column (`span={12}` for full width)     |
+| `Input`          | `"webiny/admin/ui"`   | Text input field                                    |
+| `Select`         | `"webiny/admin/ui"`   | Dropdown select with options                        |
+| `FormApi`        | `"webiny/admin/form"` | Type for the form API object                        |
+
+## Lexical Editor Plugins
+
+Admin extensions can also add custom plugins to the Lexical rich text editor used in both the Headless CMS and the Website Builder. These are registered as `<Admin.Extension>` and use imports from `"webiny/admin/lexical"`, `"webiny/admin/cms/lexical"`, and `"webiny/admin/website-builder/lexical"`.
+
+## Quick Reference
+
+```
+White-label import:  import { AdminConfig } from "webiny/admin/configs";
+Data list import:    import { ContentEntryListConfig } from "webiny/admin/cms/entry/list";
+Form imports:        import { Bind, useForm, validation } from "webiny/admin/form";
+UI imports:          import { Grid, Input, Select } from "webiny/admin/ui";
+Register:            <Admin.Extension src={"/extensions/MyAdminExtension.tsx"} />
+Develop:             yarn webiny watch admin
+Deploy:              yarn webiny deploy admin
+```
+
+## Related Skills
+
+- `webiny-project-structure` -- How to register Admin extensions
+- `webiny-full-stack-architect` -- Full-stack extension skeleton and registration
+- `webiny-admin-architect` -- Admin-side architecture patterns (headless + presentation features)