mfeflow 0.2.0 → 0.3.0

package/assets/features/analytics-clarity/feature.json

@@ -0,0 +1,64 @@
+{
+  "name": "analytics-clarity",
+  "version": "0.1.0",
+  "description": "Microsoft Clarity behind @mfeflow/analytics, next to Google Tag Manager. Clarity loads only after the visitor grants analytics consent in the banner analytics-gtm adds, and stops again if they withdraw it. The project id is the runtime config's clarityId.",
+  "requires": ["core", "tsconfig", "analytics-gtm"],
+  "files": [
+    {
+      "to": "src/analytics/clarity.ts",
+      "target": "shell",
+      "from": "files/clarity.ts"
+    },
+    {
+      "to": "src/analytics/clarity.test.ts",
+      "target": "shell",
+      "from": "files/clarity-test.ts",
+      "when": {
+        "feature:testing": true
+      }
+    }
+  ],
+  "transforms": [
+    {
+      "op": "add-boot-step",
+      "file": "src/bootstrap.tsx",
+      "target": "shell",
+      "call": "initClarityFromConfig",
+      "from": "./analytics/clarity",
+      "await": false
+    },
+    {
+      "op": "add-env-key",
+      "file": "src/config/schema.ts",
+      "target": "shell",
+      "key": "clarityId",
+      "scope": "runtime",
+      "schema": {
+        "zod": "z.string().regex(/^([a-z0-9]{8,12})?$/)",
+        "valibot": "v.pipe(v.string(), v.regex(/^([a-z0-9]{8,12})?$/))",
+        "arktype": "'/^([a-z0-9]{8,12})?$/'"
+      },
+      "value": "",
+      "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": "clarityId",
+      "scope": "runtime",
+      "schema": "z.string().regex(/^([a-z0-9]{8,12})?$/)",
+      "value": "",
+      "when": {
+        "feature:env-t3": false
+      }
+    }
+  ]
+}

package/assets/features/analytics-clarity/files/clarity-test.ts

@@ -0,0 +1,36 @@
+import { providerName, resetAnalyticsForTests, updateConsent } from '@mfeflow/analytics';
+import { afterEach, describe, expect, it } from 'vitest';
+import { startClarity } from './clarity';
+
+const clarityScript = () => document.querySelector('script[src*="clarity.ms/tag/"]');
+
+afterEach(() => {
+  Reflect.deleteProperty(globalThis, '__MFE_RUNTIME_CONFIG__');
+  Reflect.deleteProperty(globalThis, 'clarity');
+  document.head.innerHTML = '';
+  resetAnalyticsForTests();
+});
+
+describe('startClarity', () => {
+  it('stays off without a clarityId', async () => {
+    Reflect.set(globalThis, '__MFE_RUNTIME_CONFIG__', { clarityId: '' });
+    await startClarity();
+    expect(providerName()).toBe('noop');
+  });
+
+  it('stays off when the id is not a Clarity project id', async () => {
+    Reflect.set(globalThis, '__MFE_RUNTIME_CONFIG__', { clarityId: 'GTM-ABC123' });
+    await startClarity();
+    expect(providerName()).toBe('noop');
+  });
+
+  it('waits for consent, then loads the script once', async () => {
+    Reflect.set(globalThis, '__MFE_RUNTIME_CONFIG__', { clarityId: 'k3x9m2abcd' });
+    await startClarity();
+    await startClarity();
+    expect(providerName()).toBe('clarity');
+    expect(clarityScript()).toBeNull();
+    updateConsent({ analytics_storage: 'granted' });
+    expect(document.querySelectorAll('script[src*="clarity.ms/tag/k3x9m2abcd"]')).toHaveLength(1);
+  });
+});

package/assets/features/analytics-clarity/files/clarity.ts

@@ -0,0 +1,26 @@
+import { addProvider } from '@mfeflow/analytics/providers';
+import { createClarityProvider } from '@mfeflow/analytics/clarity';
+import { fetchRuntimeConfig } from '@mfeflow/runtime';
+
+/**
+ * Adds Clarity next to the other analytics providers, from the runtime config's `clarityId`. With no id it
+ * does nothing. Even with one, Clarity requests nothing until the visitor grants analytics consent.
+ */
+export async function startClarity(): Promise<void> {
+  const config = await fetchRuntimeConfig().catch((error: unknown) => {
+    console.warn('[analytics] the runtime config did not load, so Clarity stays off', error);
+    return undefined;
+  });
+  const clarityId = config?.clarityId;
+  if (typeof clarityId !== 'string' || clarityId === '') return;
+  try {
+    addProvider(createClarityProvider({ projectId: clarityId }));
+  } catch (error) {
+    console.warn('[analytics] Clarity not started', error);
+  }
+}
+
+/** The boot step: never holds up the first render. */
+export function initClarityFromConfig(): void {
+  void startClarity();
+}

package/assets/features/analytics-gtm/files/init.ts

@@ -1,4 +1,4 @@
-import { initAnalytics } from '@mfeflow/analytics';
+import { addProvider } from '@mfeflow/analytics/providers';
 import { createGtmProvider } from '@mfeflow/analytics/gtm';
 import { fetchRuntimeConfig } from '@mfeflow/runtime';
 
@@ -14,7 +14,7 @@ export async function startAnalytics(): Promise<void> {
   const gtmId = config?.gtmId;
   if (typeof gtmId !== 'string' || gtmId === '') return;
   try {
-    initAnalytics(createGtmProvider({ containerId: gtmId }));
+    addProvider(createGtmProvider({ containerId: gtmId }));
   } catch (error) {
     console.warn('[analytics] not started', error);
   }

package/assets/features/commit-prompt/feature.json

@@ -0,0 +1,27 @@
+{
+  "name": "commit-prompt",
+  "version": "0.1.0",
+  "description": "An interactive Conventional Commits prompt (czg): pnpm commit asks for the type, scope and message, then runs git commit. No emoji. Works with git-hooks, whose commitlint hook checks the same message.",
+  "requires": ["core"],
+  "files": [
+    {
+      "to": "cz.config.js",
+      "target": "root",
+      "from": "files/cz.config.js"
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "czg",
+      "range": "1.14.0",
+      "target": "root",
+      "dev": true
+    }
+  ],
+  "scripts": [
+    {
+      "name": "commit",
+      "command": "czg"
+    }
+  ]
+}

package/assets/features/commit-prompt/files/cz.config.js

@@ -0,0 +1,27 @@
+// `pnpm commit` asks for each part of a Conventional Commit, then runs `git commit`.
+// The types are the ones commitlint's conventional config accepts, so the git-hooks check passes.
+export default {
+  useEmoji: false,
+  // commitlint's conventional config rejects a capitalised subject, so the prompt lowercases it.
+  upperCaseSubject: false,
+  allowCustomScopes: true,
+  allowEmptyScopes: true,
+  allowBreakingChanges: ['feat', 'fix'],
+  maxHeaderLength: 100,
+  // Offered as a list; anything else can be typed. Add your apps and areas.
+  scopes: ['deps', 'ci'],
+  skipQuestions: ['footerPrefix'],
+  types: [
+    { value: 'feat', name: 'feat:     A new feature' },
+    { value: 'fix', name: 'fix:      A bug fix' },
+    { value: 'docs', name: 'docs:     Documentation only' },
+    { value: 'style', name: 'style:    Formatting, no change to behaviour' },
+    { value: 'refactor', name: 'refactor: Neither a fix nor a feature' },
+    { value: 'perf', name: 'perf:     Makes it faster' },
+    { value: 'test', name: 'test:     Add or fix tests' },
+    { value: 'build', name: 'build:    Build system or dependencies' },
+    { value: 'ci', name: 'ci:       CI configuration' },
+    { value: 'chore', name: 'chore:    Anything else that is not in src or tests' },
+    { value: 'revert', name: 'revert:   Revert an earlier commit' },
+  ],
+};

package/assets/features/data-react-query/feature.json

@@ -0,0 +1,89 @@
+{
+  "name": "data-react-query",
+  "version": "0.1.0",
+  "description": "Server state with TanStack Query as a shared singleton: the shell owns the QueryClient and its provider, every remote calls useQuery against the same cache, and each remote prefixes its query keys with its own name. The example query uses the http client when http is installed.",
+  "requires": ["core", "tsconfig"],
+  "files": [
+    {
+      "to": "src/query/Query.tsx",
+      "target": "shell",
+      "from": "files/shell-Query.tsx"
+    },
+    {
+      "to": "src/query/Query.test.tsx",
+      "target": "shell",
+      "from": "files/shell-Query-test.tsx",
+      "when": {
+        "feature:testing": true
+      }
+    },
+    {
+      "to": "src/query/Query.tsx",
+      "target": "remotes",
+      "from": "files/remote-Query.tsx"
+    },
+    {
+      "to": "src/query/keys.ts",
+      "target": "remotes",
+      "from": "files/keys.ts.eta",
+      "template": true
+    },
+    {
+      "to": "src/query/useHealth.ts",
+      "target": "remotes",
+      "from": "files/useHealth.http.ts.eta",
+      "template": true,
+      "when": {
+        "feature:http": true
+      }
+    },
+    {
+      "to": "src/query/useHealth.ts",
+      "target": "remotes",
+      "from": "files/useHealth.fetch.ts.eta",
+      "template": true,
+      "when": {
+        "feature:http": false
+      }
+    },
+    {
+      "to": "src/query/Query.test.tsx",
+      "target": "remotes",
+      "from": "files/remote-Query-test.tsx.eta",
+      "template": true,
+      "when": {
+        "feature:testing": true
+      }
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@tanstack/react-query",
+      "range": "5.105.0",
+      "target": "shell"
+    },
+    {
+      "name": "@tanstack/react-query",
+      "range": "5.105.0",
+      "target": "remotes"
+    }
+  ],
+  "transforms": [
+    {
+      "op": "wrap-provider",
+      "file": "src/App.tsx",
+      "target": "shell",
+      "component": "Query",
+      "from": "./query/Query",
+      "function": "App"
+    },
+    {
+      "op": "wrap-provider",
+      "file": "src/exposed/App.tsx",
+      "target": "remotes",
+      "component": "Query",
+      "from": "../query/Query",
+      "function": "App"
+    }
+  ]
+}

package/assets/features/data-react-query/files/keys.ts.eta

@@ -0,0 +1,8 @@
+/**
+ * Every query key of this remote starts with its name, so it never meets another remote's key in the shared cache,
+ * and `queryClient.invalidateQueries({ queryKey: queryKeys.all })` refreshes just this remote.
+ */
+export const queryKeys = {
+  all: ['<%= it.app.name %>'] as const,
+  health: () => [...queryKeys.all, 'health'] as const,
+};

package/assets/features/data-react-query/files/remote-Query-test.tsx.eta

@@ -0,0 +1,39 @@
+import { render, screen } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { describe, expect, it } from 'vitest';
+import { queryKeys } from './keys';
+import { Query } from './Query';
+import { useHealth } from './useHealth';
+
+function Health() {
+  const { data } = useHealth();
+  return <p>{data ? `ok: ${String(data.ok)}` : 'loading'}</p>;
+}
+
+describe('the <%= it.app.name %> queries', () => {
+  it('start with the remote name', () => {
+    expect(queryKeys.health()[0]).toBe('<%= it.app.name %>');
+  });
+
+  it('run on their own, without the shell', async () => {
+    render(
+      <Query>
+        <Health />
+      </Query>,
+    );
+    expect(await screen.findByText('ok: true')).toBeDefined();
+  });
+
+  it('use the shell client when there is one', async () => {
+    const shell = new QueryClient();
+    render(
+      <QueryClientProvider client={shell}>
+        <Query>
+          <Health />
+        </Query>
+      </QueryClientProvider>,
+    );
+    await screen.findByText('ok: true');
+    expect(shell.getQueryData(queryKeys.health())).toEqual({ ok: true });
+  });
+});

package/assets/features/data-react-query/files/remote-Query.tsx

@@ -0,0 +1,15 @@
+import { useContext, type ReactNode } from 'react';
+import { QueryClient, QueryClientContext, QueryClientProvider } from '@tanstack/react-query';
+
+let standalone: QueryClient | undefined;
+
+/**
+ * Inside the shell this does nothing: the shell's client is already in context. When the remote runs on its own
+ * (`pnpm dev` in its folder) there is no shell, so it provides a client of its own.
+ */
+export function Query({ children }: { children: ReactNode }) {
+  const inShell = useContext(QueryClientContext) !== undefined;
+  if (inShell) return children;
+  standalone ??= new QueryClient();
+  return <QueryClientProvider client={standalone}>{children}</QueryClientProvider>;
+}

package/assets/features/data-react-query/files/shell-Query-test.tsx

@@ -0,0 +1,21 @@
+import { render, screen } from '@testing-library/react';
+import { useQuery } from '@tanstack/react-query';
+import { describe, expect, it } from 'vitest';
+import { Query, queryClient } from './Query';
+
+function Value() {
+  const { data } = useQuery({ queryKey: ['shell', 'answer'], queryFn: () => Promise.resolve(42) });
+  return <p>{data ?? 'loading'}</p>;
+}
+
+describe('Query', () => {
+  it('gives the app one cache', async () => {
+    render(
+      <Query>
+        <Value />
+      </Query>,
+    );
+    expect(await screen.findByText('42')).toBeDefined();
+    expect(queryClient.getQueryData(['shell', 'answer'])).toBe(42);
+  });
+});

package/assets/features/data-react-query/files/shell-Query.tsx

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+/**
+ * The page's one cache. Remotes call `useQuery` against it because `@tanstack/react-query` is a shared
+ * singleton, so they find this client through context. Tune the defaults here.
+ */
+export const queryClient = new QueryClient({
+  defaultOptions: { queries: { staleTime: 30_000, retry: 1, refetchOnWindowFocus: false } },
+});
+
+export function Query({ children }: { children: ReactNode }) {
+  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+}

package/assets/features/data-react-query/files/useHealth.fetch.ts.eta

@@ -0,0 +1,15 @@
+import { useQuery } from '@tanstack/react-query';
+import { queryKeys } from './keys';
+
+/** An example query with plain fetch. With the `http` feature this file uses its client instead. */
+export function useHealth() {
+  return useQuery({
+    queryKey: queryKeys.health(),
+    queryFn: async ({ signal }) => {
+      const response = await fetch(new URL('/api/health', location.origin), { signal });
+      if (!response.ok) throw new Error(`health check failed (${String(response.status)})`);
+      const body: unknown = await response.json();
+      return { ok: typeof body === 'object' && body !== null && Reflect.get(body, 'ok') === true };
+    },
+  });
+}

package/assets/features/data-react-query/files/useHealth.http.ts.eta

@@ -0,0 +1,11 @@
+import { useQuery } from '@tanstack/react-query';
+import { api } from '../api/client';
+import { queryKeys } from './keys';
+
+/** An example query: the API's health check through the http client, cancelled when the component unmounts. */
+export function useHealth() {
+  return useQuery({
+    queryKey: queryKeys.health(),
+    queryFn: ({ signal }) => api.get('health', { signal }),
+  });
+}

package/assets/features/env-t3/feature.json

@@ -394,6 +394,27 @@
       "when": {
         "feature:http": true
       }
+    },
+    {
+      "op": "add-env-key",
+      "file": "src/config/schema.ts",
+      "target": "shell",
+      "key": "clarityId",
+      "scope": "runtime",
+      "schema": {
+        "zod": "z.string().regex(/^([a-z0-9]{8,12})?$/)",
+        "valibot": "v.pipe(v.string(), v.regex(/^([a-z0-9]{8,12})?$/))",
+        "arktype": "'/^([a-z0-9]{8,12})?$/'"
+      },
+      "value": "",
+      "configFiles": [
+        "public/config/runtime-config.dev.json",
+        "public/config/runtime-config.staging.json",
+        "public/config/runtime-config.prod.json"
+      ],
+      "when": {
+        "feature:analytics-clarity": 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>;