mfeflow 0.1.0 → 0.3.0

package/assets/features/event-bus/files/announce.tsx.eta

@@ -0,0 +1,10 @@
+import { useEffect, type ReactNode } from 'react';
+import { announceReady } from './events';
+
+/** Tells the other remotes that <%= it.app.name %> is on the page, each time it mounts. */
+export function Announce({ children }: { children: ReactNode }) {
+  useEffect(() => {
+    announceReady();
+  }, []);
+  return <>{children}</>;
+}

package/assets/features/event-bus/files/contracts-events.ts

@@ -0,0 +1,11 @@
+/**
+ * Every event the platform can carry, by versioned name: <domain>.<event>.v<major>, like
+ * cart.item-added.v1. Types only: nothing here runs, so any remote can read it.
+ *
+ * Add an event by adding a line. Change a payload in a way old listeners cannot read by adding
+ * a new version (cart.item-added.v2) and publishing both until every listener has moved.
+ */
+export interface Events {
+  /** A remote is on the page. The sample event: every remote announces itself, every other one can listen. */
+  'mfe.ready.v1': { mfe: string };
+}

package/assets/features/event-bus/files/contracts-package.json.eta

@@ -0,0 +1,10 @@
+{
+  "name": "<%= it.scope %>/contracts",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./events": "./src/events/index.ts",
+    "./routes/*": "./src/routes/*.ts"
+  }
+}

package/assets/features/event-bus/files/contracts-readme.md

@@ -0,0 +1,10 @@
+# contracts
+
+What the micro-frontends agree on, and nothing else. A remote never imports another remote; it
+imports this.
+
+- `src/events`: the events remotes publish and listen to, as types.
+- `src/routes`: each remote's public paths, as plain data (added by `route-factory`).
+
+Keep it to types and plain data with no imports, so reading it costs a remote nothing at run time
+and it never pulls in another remote's code.

package/assets/features/event-bus/files/events-test.ts.eta

@@ -0,0 +1,18 @@
+import { publish, resetEventBusForTests } from '@mfeflow/event-bus';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { announceReady, onOtherRemoteReady } from './events';
+
+afterEach(resetEventBusForTests);
+
+describe('the <%= it.app.name %> events', () => {
+  it('hears another remote and not itself', () => {
+    const heard = vi.fn();
+    const stop = onOtherRemoteReady(heard);
+    announceReady();
+    publish('mfe.ready.v1', { mfe: 'somewhere-else' });
+    expect(heard).toHaveBeenCalledExactlyOnceWith('somewhere-else');
+    stop();
+    publish('mfe.ready.v1', { mfe: 'later' });
+    expect(heard).toHaveBeenCalledOnce();
+  });
+});

package/assets/features/event-bus/files/events.ts.eta

@@ -0,0 +1,20 @@
+import { publish, subscribe } from '@mfeflow/event-bus';
+import type { Events } from '<%= it.scope %>/contracts/events';
+
+// The platform's event map is the contracts package's. This one declaration merges it in.
+declare module '@mfeflow/event-bus' {
+  // oxlint-disable-next-line typescript/no-empty-interface -- merges the contracts into the platform map
+  interface EventMap extends Events {}
+}
+
+/** Tells the other remotes that <%= it.app.name %> is on the page. */
+export function announceReady(): void {
+  publish('mfe.ready.v1', { mfe: '<%= it.app.name %>' });
+}
+
+/** Calls `handler` with the name of each other remote that announces itself. Returns the function that stops it. */
+export function onOtherRemoteReady(handler: (mfe: string) => void): () => void {
+  return subscribe('mfe.ready.v1', ({ mfe }) => {
+    if (mfe !== '<%= it.app.name %>') handler(mfe);
+  });
+}

package/assets/features/event-bus/files/shell-events-test.ts.eta

@@ -0,0 +1,22 @@
+import { publish, resetEventBusForTests, subscribe } from '@mfeflow/event-bus';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { configureShellEvents } from './events';
+
+afterEach(resetEventBusForTests);
+
+describe('the shell event bus', () => {
+  it('carries the contracts events between remotes', () => {
+    const heard = vi.fn();
+    subscribe('mfe.ready.v1', heard);
+    publish('mfe.ready.v1', { mfe: 'cart' });
+    expect(heard).toHaveBeenCalledExactlyOnceWith({ mfe: 'cart' });
+  });
+
+  it('replays the latest announcement to a remote that mounts late', () => {
+    configureShellEvents();
+    publish('mfe.ready.v1', { mfe: 'cart' });
+    const late = vi.fn();
+    subscribe('mfe.ready.v1', late);
+    expect(late).toHaveBeenCalledExactlyOnceWith({ mfe: 'cart' });
+  });
+});

package/assets/features/event-bus/files/shell-events.ts.eta

@@ -0,0 +1,19 @@
+import { configureEvent } from '@mfeflow/event-bus';
+import type { Events } from '<%= it.scope %>/contracts/events';
+
+// The platform's event map is the contracts package's. This one declaration merges it in.
+declare module '@mfeflow/event-bus' {
+  // oxlint-disable-next-line typescript/no-empty-interface -- merges the contracts into the platform map
+  interface EventMap extends Events {}
+}
+
+/**
+ * How the platform's events behave, set once at boot. The shell imports the bus here, which makes
+ * it the one that provides the copy every remote shares.
+ */
+export function configureShellEvents(): void {
+  // "This remote is up" is a fact about the page, not a moment: a remote that mounts later still
+  // hears the latest announcement. Only the last one is kept. Leave replay off for events that
+  // are things that happened, like cart.item-added.v1.
+  configureEvent('mfe.ready.v1', { replay: true });
+}

package/assets/features/forms/feature.json

@@ -0,0 +1,90 @@
+{
+  "name": "forms",
+  "version": "0.1.0",
+  "description": "Forms with react-hook-form, validated by a schema (zod, valibot or arktype, through the Standard Schema resolver). Each remote gets an example form with its own schema; nothing is shared between remotes and nothing is added to the shell.",
+  "requires": ["core", "tsconfig"],
+  "prompts": [
+    {
+      "name": "validator",
+      "type": "select",
+      "message": "Which schema library?",
+      "choices": ["zod", "valibot", "arktype"],
+      "default": "zod"
+    }
+  ],
+  "files": [
+    {
+      "to": "src/forms/schema.ts",
+      "target": "remotes",
+      "from": "files/schema.zod.ts",
+      "when": {
+        "validator": "zod"
+      }
+    },
+    {
+      "to": "src/forms/schema.ts",
+      "target": "remotes",
+      "from": "files/schema.valibot.ts",
+      "when": {
+        "validator": "valibot"
+      }
+    },
+    {
+      "to": "src/forms/schema.ts",
+      "target": "remotes",
+      "from": "files/schema.arktype.ts",
+      "when": {
+        "validator": "arktype"
+      }
+    },
+    {
+      "to": "src/forms/ContactForm.tsx",
+      "target": "remotes",
+      "from": "files/ContactForm.tsx"
+    },
+    {
+      "to": "src/forms/ContactForm.test.tsx",
+      "target": "remotes",
+      "from": "files/ContactForm-test.tsx",
+      "when": {
+        "feature:testing": true
+      }
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "react-hook-form",
+      "range": "7.91.0",
+      "target": "remotes"
+    },
+    {
+      "name": "@hookform/resolvers",
+      "range": "7.0.1",
+      "target": "remotes"
+    },
+    {
+      "name": "zod",
+      "range": "4.6.7",
+      "target": "remotes",
+      "when": {
+        "validator": "zod"
+      }
+    },
+    {
+      "name": "valibot",
+      "range": "1.5.0",
+      "target": "remotes",
+      "when": {
+        "validator": "valibot"
+      }
+    },
+    {
+      "name": "arktype",
+      "range": "2.2.9",
+      "target": "remotes",
+      "when": {
+        "validator": "arktype"
+      }
+    }
+  ]
+}

package/assets/features/forms/files/ContactForm-test.tsx

@@ -0,0 +1,35 @@
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { ContactForm } from './ContactForm';
+import type { ContactValues } from './schema';
+
+function fill(label: string, value: string) {
+  fireEvent.change(screen.getByLabelText(label), { target: { value } });
+}
+
+describe('ContactForm', () => {
+  it('shows what is wrong and does not submit', async () => {
+    const onSubmit = vi.fn();
+    render(<ContactForm onSubmit={onSubmit} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Send' }));
+    expect((await screen.findAllByRole('alert')).length).toBe(3);
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('submits the values once, even when the button is clicked twice', async () => {
+    const onSubmit = vi.fn(
+      (_values: ContactValues) => new Promise<void>((resolve) => setTimeout(resolve, 50)),
+    );
+    render(<ContactForm onSubmit={onSubmit} />);
+    fill('Name', 'Asha');
+    fill('Email', 'asha@example.com');
+    fill('Message', 'Hello, this is long enough.');
+    const button = screen.getByRole('button', { name: 'Send' });
+    fireEvent.click(button);
+    fireEvent.click(button);
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledTimes(1);
+    });
+    expect(onSubmit.mock.calls[0]?.[0]).toMatchObject({ name: 'Asha', email: 'asha@example.com' });
+  });
+});

package/assets/features/forms/files/ContactForm.tsx

@@ -0,0 +1,50 @@
+import { standardSchemaResolver } from '@hookform/resolvers/standard-schema';
+import { useForm } from 'react-hook-form';
+import { contactSchema, type ContactValues } from './schema';
+
+interface ContactFormProps {
+  /** Called with the validated values. The button stays disabled until the promise settles, so a double click sends once. */
+  onSubmit: (values: ContactValues) => void | Promise<void>;
+}
+
+/**
+ * An example to copy from. Load it where you need it with `lazy(() => import('./forms/ContactForm').then((m) => ({ default: m.ContactForm })))`,
+ * so the form library and the schema stay out of the remote's first load.
+ */
+export function ContactForm({ onSubmit }: ContactFormProps) {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useForm<ContactValues>({
+    resolver: standardSchemaResolver(contactSchema),
+    defaultValues: { name: '', email: '', message: '' },
+  });
+  return (
+    <form
+      noValidate
+      onSubmit={(event) => {
+        void handleSubmit(onSubmit)(event);
+      }}
+    >
+      <label>
+        Name
+        <input {...register('name')} aria-invalid={errors.name ? 'true' : 'false'} />
+      </label>
+      {errors.name ? <p role="alert">{errors.name.message}</p> : null}
+      <label>
+        Email
+        <input type="email" {...register('email')} aria-invalid={errors.email ? 'true' : 'false'} />
+      </label>
+      {errors.email ? <p role="alert">{errors.email.message}</p> : null}
+      <label>
+        Message
+        <textarea {...register('message')} aria-invalid={errors.message ? 'true' : 'false'} />
+      </label>
+      {errors.message ? <p role="alert">{errors.message.message}</p> : null}
+      <button type="submit" disabled={isSubmitting}>
+        Send
+      </button>
+    </form>
+  );
+}

package/assets/features/forms/files/schema.arktype.ts

@@ -0,0 +1,9 @@
+import { type } from 'arktype';
+
+export const contactSchema = type({
+  name: 'string > 0',
+  email: 'string.email',
+  message: 'string >= 10',
+});
+
+export type ContactValues = typeof contactSchema.infer;

package/assets/features/forms/files/schema.valibot.ts

@@ -0,0 +1,9 @@
+import * as v from 'valibot';
+
+export const contactSchema = v.object({
+  name: v.pipe(v.string(), v.minLength(1, 'Enter your name')),
+  email: v.pipe(v.string(), v.email('Enter a valid email address')),
+  message: v.pipe(v.string(), v.minLength(10, 'Say a little more (at least 10 characters)')),
+});
+
+export type ContactValues = v.InferOutput<typeof contactSchema>;

package/assets/features/forms/files/schema.zod.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+
+export const contactSchema = z.object({
+  name: z.string().min(1, 'Enter your name'),
+  email: z.email('Enter a valid email address'),
+  message: z.string().min(10, 'Say a little more (at least 10 characters)'),
+});
+
+export type ContactValues = z.infer<typeof contactSchema>;

package/assets/features/http/feature.json

@@ -0,0 +1,81 @@
+{
+  "name": "http",
+  "version": "0.1.0",
+  "description": "A fetch client over your url-factory endpoints (@mfeflow/http): src/api/client.ts in every app, with retries for idempotent requests, timeouts and typed errors. The API base URL is the runtime config's apiUrl.",
+  "requires": ["core", "tsconfig", "url-factory"],
+  "files": [
+    {
+      "to": "src/api/client.ts",
+      "target": "shell",
+      "from": "files/client.ts"
+    },
+    {
+      "to": "src/api/client.ts",
+      "target": "remotes",
+      "from": "files/client.ts"
+    },
+    {
+      "to": "src/api/client.test.ts",
+      "target": "shell",
+      "from": "files/client-test.ts",
+      "when": {
+        "feature:testing": true
+      }
+    },
+    {
+      "to": "src/api/client.test.ts",
+      "target": "remotes",
+      "from": "files/client-test.ts",
+      "when": {
+        "feature:testing": true
+      }
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@mfeflow/http",
+      "range": "latest",
+      "target": "shell"
+    },
+    {
+      "name": "@mfeflow/http",
+      "range": "latest",
+      "target": "remotes"
+    }
+  ],
+  "transforms": [
+    {
+      "op": "add-env-key",
+      "file": "src/config/schema.ts",
+      "target": "shell",
+      "key": "apiUrl",
+      "scope": "runtime",
+      "schema": {
+        "zod": "z.string().min(1)",
+        "valibot": "v.pipe(v.string(), v.minLength(1))",
+        "arktype": "'string > 0'"
+      },
+      "value": "/api",
+      "configFiles": [
+        "public/config/runtime-config.dev.json",
+        "public/config/runtime-config.staging.json",
+        "public/config/runtime-config.prod.json"
+      ],
+      "when": {
+        "feature:env-t3": true
+      }
+    },
+    {
+      "op": "add-env-key",
+      "file": "public/config/runtime-config.json",
+      "target": "shell",
+      "key": "apiUrl",
+      "scope": "runtime",
+      "schema": "z.string().min(1)",
+      "value": "/api",
+      "when": {
+        "feature:env-t3": false
+      }
+    }
+  ]
+}

package/assets/features/http/files/client-test.ts

@@ -0,0 +1,19 @@
+import { isHttpError } from '@mfeflow/http';
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+import { server } from '../mocks/server';
+import { api } from './client';
+
+describe('the api client', () => {
+  it('reads an endpoint through the mock server', async () => {
+    expect(await api.get('health')).toEqual({ ok: true });
+  });
+
+  it('turns a failure into an HttpError with the status', async () => {
+    server.use(
+      http.get('*/api/health', () => HttpResponse.json({ error: 'down' }, { status: 404 })),
+    );
+    const error = await api.get('health').catch((e: unknown) => e);
+    expect(isHttpError(error) && error.status).toBe(404);
+  });
+});

package/assets/features/http/files/client.ts

@@ -0,0 +1,20 @@
+import { createHttpClient } from '@mfeflow/http';
+import { apiUrl, type endpoints } from './endpoints';
+
+// What each endpoint answers with, by the name in ./endpoints. Add a line per endpoint you call.
+interface Responses {
+  health: { ok: boolean };
+}
+
+/**
+ * One client per app over the endpoints in ./endpoints. The base URL is the runtime config's
+ * `apiUrl`. Idempotent requests retry on a network error, a timeout and a 502, 503 or 504; a
+ * failure is an HttpError with the status and body, and no URL in its message.
+ *
+ *   const { ok } = await api.get('health');
+ */
+export const api = createHttpClient<typeof endpoints, Responses>({
+  url: apiUrl,
+  // Return the signed-in user's token; no header is sent while this returns undefined.
+  // getToken: () => session.accessToken(),
+});

package/assets/features/i18n/feature.json

@@ -0,0 +1,139 @@
+{
+  "name": "i18n",
+  "version": "0.1.0",
+  "description": "Translations with @mfeflow/i18n: the shell starts one i18next instance and sets lang and dir; each remote loads its own messages from its own deploy, so a translation ships with the remote that uses it. Sample messages in English and Arabic (right to left) and a language switcher you own.",
+  "requires": ["core", "tsconfig"],
+  "files": [
+    {
+      "to": "src/i18n/config.ts",
+      "target": "shell",
+      "from": "files/shell-config.ts"
+    },
+    {
+      "to": "src/i18n/init.ts",
+      "target": "shell",
+      "from": "files/shell-init.ts"
+    },
+    {
+      "to": "src/i18n/Languages.tsx",
+      "target": "shell",
+      "from": "files/Languages.tsx"
+    },
+    {
+      "to": "src/i18n/LanguageSwitcher.tsx",
+      "target": "shell",
+      "from": "files/LanguageSwitcher.tsx"
+    },
+    {
+      "to": "src/i18n/init.test.ts",
+      "target": "shell",
+      "from": "files/shell-init-test.ts",
+      "when": {
+        "feature:testing": true
+      }
+    },
+    {
+      "to": "src/i18n/LanguageSwitcher.test.tsx",
+      "target": "shell",
+      "from": "files/language-switcher-test.tsx",
+      "when": {
+        "feature:testing": true
+      }
+    },
+    {
+      "to": "src/i18n/config.ts",
+      "target": "remotes",
+      "from": "files/remote-config.ts"
+    },
+    {
+      "to": "src/i18n/load.ts",
+      "target": "remotes",
+      "from": "files/remote-load.ts"
+    },
+    {
+      "to": "src/i18n/I18n.tsx",
+      "target": "remotes",
+      "from": "files/remote-I18n.tsx.eta",
+      "template": true
+    },
+    {
+      "to": "src/i18n/messages/en.json",
+      "target": "remotes",
+      "from": "files/remote-en.json.eta",
+      "template": true
+    },
+    {
+      "to": "src/i18n/messages/ar.json",
+      "target": "remotes",
+      "from": "files/remote-ar.json.eta",
+      "template": true
+    },
+    {
+      "to": "src/i18n/I18n.test.tsx",
+      "target": "remotes",
+      "from": "files/remote-I18n-test.tsx.eta",
+      "template": true,
+      "when": {
+        "feature:testing": true
+      }
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@mfeflow/i18n",
+      "range": "latest",
+      "target": "shell"
+    },
+    {
+      "name": "i18next",
+      "range": "26.5.12",
+      "target": "shell"
+    },
+    {
+      "name": "react-i18next",
+      "range": "17.1.9",
+      "target": "shell"
+    },
+    {
+      "name": "@mfeflow/i18n",
+      "range": "latest",
+      "target": "remotes"
+    },
+    {
+      "name": "i18next",
+      "range": "26.5.12",
+      "target": "remotes"
+    },
+    {
+      "name": "react-i18next",
+      "range": "17.1.9",
+      "target": "remotes"
+    }
+  ],
+  "transforms": [
+    {
+      "op": "add-boot-step",
+      "file": "src/bootstrap.tsx",
+      "target": "shell",
+      "call": "initShellI18n",
+      "from": "./i18n/init",
+      "await": true
+    },
+    {
+      "op": "wrap-provider",
+      "file": "src/App.tsx",
+      "target": "shell",
+      "component": "Languages",
+      "from": "./i18n/Languages",
+      "function": "App"
+    },
+    {
+      "op": "wrap-provider",
+      "file": "src/exposed/App.tsx",
+      "target": "remotes",
+      "component": "I18n",
+      "from": "../i18n/I18n",
+      "function": "App"
+    }
+  ]
+}

package/assets/features/i18n/files/LanguageSwitcher.tsx

@@ -0,0 +1,28 @@
+import { useLanguage, useMfeTranslation } from '@mfeflow/i18n/react';
+import { loadShellMessages } from './config';
+
+/** Your component: move it into the header or restyle it. Changing the language also sets <html lang dir>. */
+export function LanguageSwitcher() {
+  const { t } = useMfeTranslation('shell', loadShellMessages);
+  const { language, languages, setLanguage } = useLanguage();
+  return (
+    <label
+      className="language-switcher"
+      style={{ position: 'fixed', left: '1rem', bottom: '1rem' }}
+    >
+      {t('language')}{' '}
+      <select
+        value={language}
+        onChange={(event) => {
+          void setLanguage(event.target.value);
+        }}
+      >
+        {languages.map((option) => (
+          <option key={option.code} value={option.code}>
+            {option.label}
+          </option>
+        ))}
+      </select>
+    </label>
+  );
+}

package/assets/features/i18n/files/Languages.tsx

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+import { LanguageSwitcher } from './LanguageSwitcher';
+
+/** Wraps the shell and shows the language switcher. The instance itself starts in the boot step. */
+export function Languages({ children }: { children: ReactNode }) {
+  return (
+    <>
+      {children}
+      <LanguageSwitcher />
+    </>
+  );
+}

package/assets/features/i18n/files/language-switcher-test.tsx

@@ -0,0 +1,19 @@
+import { fireEvent, screen, waitFor } from '@testing-library/react';
+import { resetPlatform, renderWithPlatform } from '@mfeflow/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+import { initShellI18n } from './init';
+import { LanguageSwitcher } from './LanguageSwitcher';
+
+afterEach(resetPlatform);
+
+describe('LanguageSwitcher', () => {
+  it('switches the language and the page direction', async () => {
+    await initShellI18n();
+    renderWithPlatform(<LanguageSwitcher />);
+    fireEvent.change(screen.getByRole('combobox'), { target: { value: 'ar' } });
+    await waitFor(() => {
+      expect(document.documentElement.dir).toBe('rtl');
+    });
+    expect(screen.getByText('اللغة')).toBeDefined();
+  });
+});