odoro 1.0.9 → 2.1.0

package/templates/react-ts-server/client/src/account.tsx

@@ -0,0 +1,267 @@
+/**
+ * The three account pages: sign in, register, profile.
+ *
+ * ## Why they live apart from `App.tsx`
+ *
+ * `App.tsx` holds the page you see before signing in, and it is meant to be
+ * read in one go. These three depend on the back end: they are the part to
+ * open when wiring the API, and the part to delete when the project does not
+ * need accounts.
+ *
+ * ## What the form does about errors
+ *
+ * It shows what the server said, and nothing else. The foundation answers in
+ * `problem+json`, where `detail` is a sentence written for a human — "This
+ * address already has an account." A status code in its place would be a
+ * number in front of someone who mistyped their email.
+ *
+ * @module
+ */
+
+import { buttonClasses } from '@odoro-cli/libs/ui'
+import { useState, type FormEvent, type ReactElement, type ReactNode } from 'react'
+
+import { useSession } from '@/auth'
+import { Link } from '@/router'
+
+/** The frame the three pages share. */
+function Panel({
+  title,
+  lead,
+  children,
+}: {
+  readonly title: string
+  readonly lead: string
+  readonly children: ReactNode
+}): ReactElement {
+  return (
+    <section className="o-px-6 o-py-24">
+      <div className="o-mx-auto o-w-full o-max-w-md">
+        <h1 className="o-text-3xl o-font-bold o-tracking-tight">{title}</h1>
+        <p className="o-mt-3 o-text-sm o-text-zinc-500 dark:o-text-zinc-400">{lead}</p>
+        <div className="o-mt-8">{children}</div>
+      </div>
+    </section>
+  )
+}
+
+/** A labelled field. */
+function Field({
+  label,
+  type,
+  value,
+  onChange,
+  autoComplete,
+  hint,
+}: {
+  readonly label: string
+  readonly type: string
+  readonly value: string
+  readonly onChange: (value: string) => void
+  readonly autoComplete: string
+  readonly hint?: string
+}): ReactElement {
+  return (
+    <label className="o-block o-mb-4">
+      <span className="o-block o-mb-1 o-text-sm o-font-medium">{label}</span>
+      <input
+        type={type}
+        value={value}
+        required
+        autoComplete={autoComplete}
+        onChange={(event) => onChange(event.target.value)}
+        className="o-w-full o-rounded-lg o-border o-border-zinc-200 dark:o-border-zinc-800 o-bg-transparent o-px-3 o-py-2 o-text-sm"
+      />
+      {hint === undefined ? null : (
+        <span className="o-mt-1 o-block o-text-xs o-text-zinc-500 dark:o-text-zinc-400">
+          {hint}
+        </span>
+      )}
+    </label>
+  )
+}
+
+/** The error of a submission, when there is one. */
+function Problem({ message }: { readonly message: string | null }): ReactElement | null {
+  if (message === null) return null
+  return (
+    <p
+      // `alert` so a screen reader announces it: a message that only appears
+      // visually leaves whoever does not see it waiting on a form that did
+      // nothing.
+      role="alert"
+      className="o-mb-4 o-rounded-lg o-border o-border-red-300 dark:o-border-red-900 o-px-3 o-py-2 o-text-sm o-text-red-700 dark:o-text-red-400"
+    >
+      {message}
+    </p>
+  )
+}
+
+/** Runs a submission, holding the pending state and the error. */
+function useSubmission(): {
+  busy: boolean
+  error: string | null
+  run: (action: () => Promise<void>) => (event: FormEvent) => void
+} {
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const run = (action: () => Promise<void>) => (event: FormEvent) => {
+    event.preventDefault()
+    setBusy(true)
+    setError(null)
+    action()
+      .catch((cause: unknown) => {
+        setError(cause instanceof Error ? cause.message : 'The request failed.')
+      })
+      .finally(() => setBusy(false))
+  }
+
+  return { busy, error, run }
+}
+
+/** Signing in. */
+export function SignIn(): ReactElement {
+  const { profile, signIn } = useSession()
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const { busy, error, run } = useSubmission()
+
+  if (profile != null) return <AlreadySignedIn name={profile.name} />
+
+  return (
+    <Panel title="Sign in" lead="The session is a cookie: nothing to keep in the page.">
+      <form onSubmit={run(() => signIn(email, password))}>
+        <Problem message={error} />
+        <Field
+          label="Email"
+          type="email"
+          value={email}
+          onChange={setEmail}
+          autoComplete="email"
+        />
+        <Field
+          label="Password"
+          type="password"
+          value={password}
+          onChange={setPassword}
+          autoComplete="current-password"
+        />
+        <button type="submit" disabled={busy} className={buttonClasses({ tone: 'primary' })}>
+          {busy ? 'Signing in…' : 'Sign in'}
+        </button>
+      </form>
+
+      <p className="o-mt-6 o-text-sm o-text-zinc-500 dark:o-text-zinc-400">
+        No account yet? <Link to="/register">Create one</Link>.
+      </p>
+    </Panel>
+  )
+}
+
+/** Registering. */
+export function Register(): ReactElement {
+  const { profile, register } = useSession()
+  const [email, setEmail] = useState('')
+  const [name, setName] = useState('')
+  const [password, setPassword] = useState('')
+  const { busy, error, run } = useSubmission()
+
+  if (profile != null) return <AlreadySignedIn name={profile.name} />
+
+  return (
+    <Panel
+      title="Create an account"
+      lead="The password is hashed with scrypt, and never leaves the server in clear."
+    >
+      <form onSubmit={run(() => register(email, name, password))}>
+        <Problem message={error} />
+        <Field label="Name" type="text" value={name} onChange={setName} autoComplete="name" />
+        <Field
+          label="Email"
+          type="email"
+          value={email}
+          onChange={setEmail}
+          autoComplete="email"
+        />
+        <Field
+          label="Password"
+          type="password"
+          value={password}
+          onChange={setPassword}
+          autoComplete="new-password"
+          hint="Twelve characters at least. Length is what holds; a mix of symbols is not."
+        />
+        <button type="submit" disabled={busy} className={buttonClasses({ tone: 'primary' })}>
+          {busy ? 'Creating…' : 'Create the account'}
+        </button>
+      </form>
+
+      <p className="o-mt-6 o-text-sm o-text-zinc-500 dark:o-text-zinc-400">
+        Already have one? <Link to="/sign-in">Sign in</Link>.
+      </p>
+    </Panel>
+  )
+}
+
+/** The profile of the signed-in account. */
+export function ProfilePage(): ReactElement {
+  const { profile, signOut } = useSession()
+
+  // Not asked yet: showing the signed-out page here would flash it at every
+  // reload, including to someone who is signed in.
+  if (profile === undefined) {
+    return <Panel title="Profile" lead="Reading the session…" children={null} />
+  }
+
+  if (profile === null) {
+    return (
+      <Panel title="Profile" lead="This page needs an account.">
+        <Link to="/sign-in" className={`o-no-underline ${buttonClasses({ tone: 'primary' })}`}>
+          Sign in
+        </Link>
+      </Panel>
+    )
+  }
+
+  return (
+    <Panel title={profile.name} lead="What the server knows about this account.">
+      <dl className="o-border-t o-border-zinc-200 dark:o-border-zinc-800">
+        {[
+          ['Email', profile.email],
+          ['Identifier', profile.id],
+          ['Created', new Date(profile.createdAt).toLocaleString()],
+        ].map(([label, value]) => (
+          <div
+            key={label}
+            className="o-flex o-gap-6 o-border-b o-border-zinc-200 dark:o-border-zinc-800 o-py-3"
+          >
+            <dt className="o-w-28 o-shrink-0 o-text-sm o-text-zinc-500 dark:o-text-zinc-400">
+              {label}
+            </dt>
+            <dd className="o-break-all o-font-mono o-text-sm">{value}</dd>
+          </div>
+        ))}
+      </dl>
+
+      <button
+        type="button"
+        onClick={() => void signOut()}
+        className={`o-mt-8 ${buttonClasses({ tone: 'secondary' })}`}
+      >
+        Sign out
+      </button>
+    </Panel>
+  )
+}
+
+/** Shown on the two forms when the visitor already has a session. */
+function AlreadySignedIn({ name }: { readonly name: string }): ReactElement {
+  return (
+    <Panel title={`Signed in as ${name}`} lead="Nothing to do here.">
+      <Link to="/profile" className={`o-no-underline ${buttonClasses({ tone: 'primary' })}`}>
+        See the profile
+      </Link>
+    </Panel>
+  )
+}

package/templates/react-ts-server/client/src/auth.tsx

@@ -0,0 +1,139 @@
+/**
+ * The session, client side.
+ *
+ * ## Why there is no token here
+ *
+ * The session lives in an `httpOnly` cookie that the browser sends on its own.
+ * This file never sees it, and that is the point: a value a script can read is
+ * a value the first injected script can steal.
+ *
+ * So the only question the interface can ask is "who am I", and the only way
+ * to ask it is `GET /api/auth/me`. That is one request at startup, and the
+ * answer is kept for the life of the page.
+ *
+ * ## Why the state has three values and not two
+ *
+ * `undefined` is "not asked yet", `null` is "asked, nobody". Collapsing them
+ * would flash the signed-out interface at every reload, before the answer
+ * arrives — including to someone who is signed in.
+ *
+ * @module
+ */
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react'
+
+/** A profile, as the API returns it. */
+export interface Profile {
+  readonly id: string
+  readonly email: string
+  readonly name: string
+  readonly createdAt: string
+}
+
+/** What the interface can do with the session. */
+export interface Session {
+  /** `undefined` while unknown, `null` when signed out. */
+  readonly profile: Profile | null | undefined
+  register(email: string, name: string, password: string): Promise<void>
+  signIn(email: string, password: string): Promise<void>
+  signOut(): Promise<void>
+}
+
+const SessionContext = createContext<Session | undefined>(undefined)
+
+/**
+ * A failed call, with the message the server gave.
+ *
+ * The foundation answers in `application/problem+json`: `title` says what
+ * happened, `detail` says why. Showing the HTTP status instead would put "409"
+ * in front of someone who typed an address that already has an account.
+ */
+async function call<T>(path: string, body?: unknown): Promise<T> {
+  const response = await fetch(path, {
+    method: body === undefined ? 'GET' : 'POST',
+    // The cookie is only sent if it is asked for. Without this, every call is
+    // anonymous and the session looks broken for no visible reason.
+    credentials: 'same-origin',
+    ...(body === undefined
+      ? {}
+      : { headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }),
+  })
+
+  if (response.status === 204) return undefined as T
+
+  const payload: unknown = await response.json().catch(() => undefined)
+
+  if (!response.ok) {
+    const problem = payload as { detail?: string; title?: string } | undefined
+    throw new Error(problem?.detail ?? problem?.title ?? 'The request failed.')
+  }
+
+  return payload as T
+}
+
+/** Provides the session to the whole tree. */
+export function SessionProvider({ children }: { children: ReactNode }): ReactElement {
+  const [profile, setProfile] = useState<Profile | null | undefined>(undefined)
+
+  useEffect(() => {
+    let alive = true
+    call<Profile>('/api/auth/me')
+      .then((me) => {
+        if (alive) setProfile(me)
+      })
+      .catch(() => {
+        // Not signed in, or the server has nothing to answer with. Either way
+        // the interface shows the signed-out state; it is not an incident.
+        if (alive) setProfile(null)
+      })
+    return () => {
+      alive = false
+    }
+  }, [])
+
+  const register = useCallback(async (email: string, name: string, password: string) => {
+    setProfile(await call<Profile>('/api/auth/register', { email, name, password }))
+  }, [])
+
+  const signIn = useCallback(async (email: string, password: string) => {
+    setProfile(await call<Profile>('/api/auth/login', { email, password }))
+  }, [])
+
+  const signOut = useCallback(async () => {
+    await call<void>('/api/auth/logout', {})
+    setProfile(null)
+  }, [])
+
+  const value = useMemo<Session>(
+    () => ({ profile, register, signIn, signOut }),
+    [profile, register, signIn, signOut],
+  )
+
+  return <SessionContext.Provider value={value}>{children}</SessionContext.Provider>
+}
+
+/**
+ * Reads the session.
+ *
+ * @throws {Error} Outside `SessionProvider` — which is a wiring mistake, and
+ *   is better said than silently returning "signed out".
+ *
+ * @example
+ * const { profile, signOut } = useSession()
+ */
+export function useSession(): Session {
+  const session = useContext(SessionContext)
+  if (session === undefined) {
+    throw new Error('useSession used outside SessionProvider.')
+  }
+  return session
+}

package/templates/react-ts-server/client/src/background.tsx

@@ -0,0 +1,66 @@
+/**
+ * The decorative background of the page.
+ *
+ * ## Why it is not in `App.tsx`
+ *
+ * It is the only piece of the page that depends on what was ticked at
+ * creation: with the engine, this file is replaced by a version that opens an
+ * animated WebGL surface; without it, it is the gradient below.
+ *
+ * Keeping it apart avoids having two `App.tsx` files to maintain — one per
+ * case — which would diverge at the first change of wording. `App.tsx` places
+ * `<Background />` and asks for nothing more.
+ *
+ * ## Why the sizes are inline styles
+ *
+ * The style system **emits no arbitrary-value class**: `o-h-[42rem]` produces
+ * no rule at all, and a missing class paints nothing. The container ended up
+ * zero pixels tall, so did both glows, and the background was nowhere to be
+ * seen — with nothing to report it.
+ *
+ * The utilities cover the values on the scale; anything off the scale is
+ * written as a style, where it is safe.
+ *
+ * @module
+ */
+
+import type { ReactElement } from 'react'
+
+/** Two brand glows, heavily diluted, behind the top of the page. */
+export function Background(): ReactElement {
+  return (
+    <div
+      aria-hidden="true"
+      className="o-pointer-events-none o-absolute o-inset-x-0 o-top-0 o-overflow-hidden"
+      style={{ height: '42rem' }}
+    >
+      <div
+        className="o-absolute o-rounded-full"
+        style={{
+          left: '50%',
+          top: '-18rem',
+          width: '46rem',
+          height: '46rem',
+          transform: 'translateX(-50%)',
+          filter: 'blur(64px)',
+          opacity: 0.3,
+          background:
+            'radial-gradient(closest-side, var(--o-palette-brand-500), transparent)',
+        }}
+      />
+      <div
+        className="o-absolute o-rounded-full"
+        style={{
+          right: '-10rem',
+          top: '6rem',
+          width: '30rem',
+          height: '30rem',
+          filter: 'blur(64px)',
+          opacity: 0.18,
+          background:
+            'radial-gradient(closest-side, var(--o-palette-brand-400), transparent)',
+        }}
+      />
+    </div>
+  )
+}

package/templates/react-ts-server/client/src/entry-server.tsx

@@ -0,0 +1,92 @@
+/**
+ * The prerendering entry point.
+ *
+ * ## What it does, and why it exists
+ *
+ * `odoro build` renders each of the routes below to HTML, at build time, and
+ * writes one complete document per route. The site stays a set of static files
+ * — nothing runs in production — but a search engine, a link preview or a
+ * screen reader find text in the very first response, instead of an empty
+ * container.
+ *
+ * `src/main.tsx` then takes over: seeing a container already filled, it
+ * hydrates instead of rebuilding.
+ *
+ * ## Adding a route
+ *
+ * A single line in `routes`. The path becomes a directory in `dist/`:
+ * `/pricing` gives `dist/pricing/index.html`, which any host serves with no
+ * configuration.
+ *
+ * ## Doing without
+ *
+ * Remove `prerender` from `odoro.config.ts`. This file can then go: nothing
+ * else imports it.
+ *
+ * @module
+ */
+
+import { StrictMode } from 'react'
+import { renderToString } from 'react-dom/server'
+
+import { App } from '@/App'
+import { SessionProvider } from '@/auth'
+
+/** The routes rendered at build time. */
+export const routes = ['/', '/about']
+
+/** What a page brings to the head of the document. */
+const TITLES: Readonly<Record<string, { title: string; description: string }>> = {
+  '/': {
+    title: 'Odoro',
+    description: 'An Odoro project: in-house engine, generated styles, built-in router.',
+  },
+  '/about': {
+    title: 'About — Odoro',
+    description: 'What this project ships, and what each package does in it.',
+  },
+}
+
+/** Escapes what goes into an HTML attribute. */
+function escape(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+/**
+ * Renders a route.
+ *
+ * @param url The requested path.
+ * @returns The HTML of the container, and the tags to add to the head.
+ */
+export function render(url: string): { html: string; head: string } {
+  const meta = TITLES[url] ?? TITLES['/']
+
+  const head = [
+    `<title>${escape(meta?.title ?? 'Odoro')}</title>`,
+    `<meta name="description" content="${escape(meta?.description ?? '')}">`,
+    `<meta property="og:title" content="${escape(meta?.title ?? 'Odoro')}">`,
+    `<meta property="og:description" content="${escape(meta?.description ?? '')}">`,
+  ].join('\n    ')
+
+  return {
+    // `StrictMode` is present on both sides: a tree rendered without it here
+    // and with it in the browser does not always produce the same markup, and
+    // hydration then reports a difference that is not one.
+    html: renderToString(
+      <StrictMode>
+        {/* The same tree as in the browser. The provider asks the server
+            nothing here — its request lives in an effect, and effects do not
+            run while prerendering — but a page that reads the session must
+            find it, or the whole prerender fails on that one page. */}
+        <SessionProvider>
+          <App url={url} />
+        </SessionProvider>
+      </StrictMode>,
+    ),
+    head,
+  }
+}

package/templates/react-ts-server/client/src/main.tsx

@@ -1,18 +1,30 @@
 import { StrictMode } from 'react'
-import { createRoot } from 'react-dom/client'
+import { createRoot, hydrateRoot } from 'react-dom/client'
 
 import { App } from '@/App'
+import { SessionProvider } from '@/auth'
 
 import '@odoro-cli/libs/styles.css'
 import '@/styles.css'
 
 const container = document.getElementById('root')
 if (container === null) {
-  throw new Error('Element racine "#root" introuvable dans index.html.')
+  throw new Error('Root element "#root" not found in index.html.')
 }
 
-createRoot(container).render(
+const tree = (
   <StrictMode>
-    <App />
-  </StrictMode>,
+    <SessionProvider>
+      <App />
+    </SessionProvider>
+  </StrictMode>
 )
+
+// A container that is already filled comes from prerendering: it has to be
+// **hydrated**, that is, taken over as it stands with the events attached.
+// Rebuilding it would throw away the page the visitor already sees only to draw
+// it again identically — a flicker, and the whole benefit of prerendering lost.
+//
+// Empty, it is an ordinary render.
+if (container.firstElementChild === null) createRoot(container).render(tree)
+else hydrateRoot(container, tree)