@docouno/devkit 0.0.0-stage → 0.3.0

package/templates/react-web/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "devkit-react-web",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": "^24.22.1"
+  },
+  "scripts": {
+    "check": "devkit-verify && npm run format:check && npm run lint && npm run typecheck && npm test",
+    "format:check": "prettier --check src tsconfig.json tsconfig.test.json eslint.config.mjs prettier.config.mjs vitest.config.mjs index.html vite.config.mjs",
+    "lint": "eslint --no-ignore --max-warnings 0 src eslint.config.mjs prettier.config.mjs vitest.config.mjs vite.config.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
+    "test": "vitest run --config vitest.config.mjs",
+    "fix": "prettier --write src tsconfig.json tsconfig.test.json eslint.config.mjs prettier.config.mjs vitest.config.mjs index.html vite.config.mjs && eslint --no-ignore --max-warnings 0 --fix src eslint.config.mjs prettier.config.mjs vitest.config.mjs vite.config.mjs && prettier --write src tsconfig.json tsconfig.test.json eslint.config.mjs prettier.config.mjs vitest.config.mjs index.html vite.config.mjs",
+    "build": "npm run typecheck && vite build",
+    "dev": "vite --host 0.0.0.0 --port 5173 --strictPort"
+  },
+  "devDependencies": {
+    "@docouno/env": "0.3.0",
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "24.19.2",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitejs/plugin-react": "6.1.2",
+    "eslint": "10.13.0",
+    "jsdom": "30.1.3",
+    "prettier": "3.9.10",
+    "typescript": "6.0.3",
+    "vite": "8.3.5",
+    "vitest": "5.0.5"
+  },
+  "devkit": {
+    "sourceDirectories": [
+      "src"
+    ],
+    "typecheckConfigs": [
+      "tsconfig.json",
+      "tsconfig.test.json"
+    ],
+    "boundaries": {
+      "forbidCrossAppImports": true
+    }
+  },
+  "dependencies": {
+    "react": "19.3.1",
+    "react-dom": "19.3.1"
+  }
+}

package/templates/react-web/prettier.config.mjs

@@ -0,0 +1 @@
+export { default } from '@docouno/env/prettier';

package/templates/react-web/src/ClientApp.test.tsx

@@ -0,0 +1,41 @@
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, expect, it } from 'vitest';
+import { ClientApp } from './ClientApp.js';
+
+afterEach(cleanup);
+
+it('works locally without requiring a backend', () => {
+  render(<ClientApp platform="web" />);
+  fireEvent.change(screen.getByLabelText('Name'), { target: { value: ' Ada ' } });
+  expect(screen.getByTestId('local-greeting').textContent).toBe('Hello, Ada!');
+  fireEvent.click(screen.getByRole('button', { name: 'Increment' }));
+  expect(screen.getByTestId('count').textContent).toBe('Clicks: 1');
+  expect(screen.queryByRole('button', { name: 'Ask API' })).toBeNull();
+});
+
+it('uses the supplied API and renders its response', async () => {
+  let requested = '';
+  render(
+    <ClientApp
+      platform="desktop"
+      api={{
+        greet: (name) => {
+          requested = name;
+          return Promise.resolve({ message: 'Hello from API!' });
+        },
+      }}
+    />,
+  );
+  fireEvent.change(screen.getByLabelText('Name'), { target: { value: 'Ada' } });
+  fireEvent.click(screen.getByRole('button', { name: 'Ask API' }));
+  expect(await screen.findByText('Hello from API!')).toBeDefined();
+  expect(requested).toBe('Ada');
+});
+
+it('shows an API failure without substituting a local response', async () => {
+  render(
+    <ClientApp platform="web" api={{ greet: () => Promise.reject(new Error('Unavailable')) }} />,
+  );
+  fireEvent.click(screen.getByRole('button', { name: 'Ask API' }));
+  expect((await screen.findByRole('alert')).textContent).toBe('Unavailable');
+});

package/templates/react-web/src/ClientApp.tsx

@@ -0,0 +1,75 @@
+import { useEffect, useRef, useState } from 'react';
+
+export interface ClientApi {
+  greet(name: string): Promise<{ message: string }>;
+}
+
+type RemoteState = { phase: 'idle' | 'loading' } | { phase: 'ready' | 'error'; message: string };
+
+export function ClientApp({ api, platform }: { api?: ClientApi; platform: string }) {
+  const [name, setName] = useState('world');
+  const [count, setCount] = useState(0);
+  const [remote, setRemote] = useState<RemoteState>({ phase: 'idle' });
+  const request = useRef(0);
+  useEffect(
+    () => () => {
+      request.current += 1;
+    },
+    [],
+  );
+
+  function requestGreeting() {
+    if (!api) {
+      return;
+    }
+    const current = ++request.current;
+    setRemote({ phase: 'loading' });
+    api.greet(name).then(
+      (reply) => {
+        if (request.current === current) {
+          setRemote({ phase: 'ready', message: reply.message });
+        }
+      },
+      (error: unknown) => {
+        if (request.current === current) {
+          setRemote({
+            phase: 'error',
+            message: error instanceof Error ? error.message : 'API request failed.',
+          });
+        }
+      },
+    );
+  }
+
+  return (
+    <main>
+      <p className="eyebrow">Devkit · {platform}</p>
+      <h1>A small app, ready to change.</h1>
+      <p>One interface for local interaction and an optional API connection.</p>
+      <section className="card" aria-label="Local interaction">
+        <label htmlFor="name">Name</label>
+        <input
+          id="name"
+          value={name}
+          maxLength={80}
+          onChange={(event) => setName(event.target.value)}
+        />
+        <output data-testid="local-greeting">Hello, {name.trim() || 'world'}!</output>
+        <button type="button" onClick={() => setCount((value) => value + 1)}>
+          Increment
+        </button>
+        <span data-testid="count">Clicks: {count}</span>
+      </section>
+      {api && (
+        <section className="api-panel" aria-label="API greeting">
+          <h2>API connection</h2>
+          <button type="button" onClick={requestGreeting} disabled={remote.phase === 'loading'}>
+            {remote.phase === 'loading' ? 'Requesting…' : 'Ask API'}
+          </button>
+          {remote.phase === 'ready' && <p role="status">{remote.message}</p>}
+          {remote.phase === 'error' && <p role="alert">{remote.message}</p>}
+        </section>
+      )}
+    </main>
+  );
+}

package/templates/react-web/src/api.test.ts

@@ -0,0 +1,24 @@
+import { expect, it } from 'vitest';
+import { greet } from './api.js';
+
+it('encodes the greeting request and validates the response', async () => {
+  let requested = '';
+  const fetcher: typeof fetch = (input) => {
+    requested = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+    return Promise.resolve(new Response(JSON.stringify({ message: 'Hello, Ada & Bob!' })));
+  };
+  await expect(greet('Ada & Bob', fetcher)).resolves.toEqual({ message: 'Hello, Ada & Bob!' });
+  expect(requested).toBe('/api/greeting?name=Ada+%26+Bob');
+});
+
+it('rejects HTTP and malformed response failures', async () => {
+  await expect(
+    greet('Ada', () => Promise.resolve(new Response('down', { status: 503 }))),
+  ).rejects.toThrow('503');
+  await expect(greet('Ada', () => Promise.resolve(new Response('<html>')))).rejects.toThrow(
+    'invalid JSON',
+  );
+  await expect(greet('Ada', () => Promise.resolve(new Response('{"message":42}')))).rejects.toThrow(
+    'invalid greeting',
+  );
+});

package/templates/react-web/src/api.ts

@@ -0,0 +1,29 @@
+export async function greet(
+  name: string,
+  fetcher: typeof fetch = fetch,
+): Promise<{ message: string }> {
+  const query = new URLSearchParams({ name });
+  const response = await fetcher(`/api/greeting?${query.toString()}`, {
+    headers: { accept: 'application/json' },
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!response.ok) {
+    throw new Error(`API request failed (${response.status}).`);
+  }
+  let value: unknown;
+  try {
+    value = await response.json();
+  } catch {
+    throw new Error('API returned invalid JSON.');
+  }
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    !('message' in value) ||
+    typeof value.message !== 'string' ||
+    !value.message
+  ) {
+    throw new Error('API returned an invalid greeting.');
+  }
+  return { message: value.message };
+}

package/templates/react-web/src/main.tsx

@@ -0,0 +1,15 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { ClientApp } from './ClientApp.js';
+import { greet } from './api.js';
+import './style.css';
+const element = document.getElementById('root');
+if (!element) {
+  throw new Error('Missing application root.');
+}
+const api = import.meta.env.VITE_API_ENABLED === 'true' ? { greet } : undefined;
+createRoot(element).render(
+  <StrictMode>
+    <ClientApp platform="web" {...(api ? { api } : {})} />
+  </StrictMode>,
+);

package/templates/react-web/src/style.css

@@ -0,0 +1,71 @@
+:root {
+  font-family: system-ui, sans-serif;
+  color: #17233a;
+  background: #f4f7fb;
+  font-synthesis: none;
+}
+
+body {
+  margin: 0;
+}
+main {
+  max-width: 44rem;
+  margin: 4rem auto;
+  padding: 0 1.5rem;
+}
+h1 {
+  font-size: clamp(2rem, 5vw, 3rem);
+  line-height: 1.1;
+}
+h2 {
+  font-size: 1.25rem;
+}
+p {
+  line-height: 1.6;
+}
+.eyebrow {
+  color: #3159a6;
+  font-weight: 650;
+}
+.card,
+.api-panel {
+  display: grid;
+  gap: 1rem;
+  margin-top: 2rem;
+  padding: 1.5rem;
+  border: 1px solid #dce3ef;
+  border-radius: 1rem;
+  background: white;
+}
+input,
+button {
+  font: inherit;
+  padding: 0.75rem 1rem;
+  border-radius: 0.5rem;
+}
+input {
+  border: 1px solid #8391a9;
+}
+button {
+  justify-self: start;
+  border: none;
+  background: #3159a6;
+  color: white;
+  cursor: pointer;
+}
+button:disabled {
+  opacity: 0.65;
+  cursor: wait;
+}
+input:focus-visible,
+button:focus-visible {
+  outline: 3px solid #8eafe8;
+  outline-offset: 3px;
+}
+output {
+  font-size: 1.4rem;
+  font-weight: 600;
+}
+[role='alert'] {
+  color: #a5222a;
+}

package/templates/react-web/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@docouno/env/tsconfig/browser.json",
+  "compilerOptions": {
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx"]
+}

package/templates/react-web/tsconfig.test.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@docouno/env/tsconfig/browser.json",
+  "compilerOptions": {
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}

package/templates/react-web/variants/shared/files/src/main.tsx

@@ -0,0 +1,15 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { ClientApp } from '__DEVKIT_CLIENT_PACKAGE__';
+import { greet } from './api.js';
+import '__DEVKIT_CLIENT_PACKAGE__/style.css';
+const element = document.getElementById('root');
+if (!element) {
+  throw new Error('Missing application root.');
+}
+const api = import.meta.env.VITE_API_ENABLED === 'true' ? { greet } : undefined;
+createRoot(element).render(
+  <StrictMode>
+    <ClientApp platform="web" {...(api ? { api } : {})} />
+  </StrictMode>,
+);

package/templates/react-web/variants/shared/variant.json

@@ -0,0 +1,3 @@
+{
+  "remove": ["src/ClientApp.tsx", "src/ClientApp.test.tsx", "src/style.css"]
+}

package/templates/react-web/vite.config.mjs

@@ -0,0 +1,14 @@
+import { env } from 'node:process';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+export default defineConfig({
+  plugins: [react()],
+  cacheDir: 'node_modules/.cache/devkit-vite',
+  resolve: { dedupe: ['react', 'react-dom'] },
+  server: {
+    host: '0.0.0.0',
+    port: 5173,
+    strictPort: true,
+    ...(env.DEVKIT_API_TARGET ? { proxy: { '/api': env.DEVKIT_API_TARGET } } : {}),
+  },
+});

package/templates/react-web/vitest.config.mjs

@@ -0,0 +1,19 @@
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vitest/config';
+import RunnableTestsReporter from '@docouno/env/vitest-reporter';
+
+export default defineConfig({
+  plugins: [react()],
+  cacheDir: 'node_modules/.cache/devkit-vitest',
+  resolve: { dedupe: ['react', 'react-dom'] },
+  test: {
+    environment: 'jsdom',
+    include: ['src/**/*.test.{ts,tsx}'],
+    globals: false,
+    passWithNoTests: false,
+    reporters: ['default', new RunnableTestsReporter()],
+    restoreMocks: true,
+    clearMocks: true,
+    maxWorkers: 2,
+  },
+});