odoro 1.0.9 → 2.1.0

package/templates/react-ts-server/_env.example

@@ -1,78 +1,76 @@
-# Copier ce fichier en `.env` et ajuster les valeurs.
+# Copy this file to `.env` and adjust the values.
 #
-# Toute variable manquante ou invalide arrete le serveur au demarrage, avec un
-# message qui les liste toutes d'un coup : mieux vaut un echec immediat qu'une
-# panne a la centieme requete.
+# Any missing or invalid variable stops the server at startup, with a message
+# listing them all at once: an immediate failure beats an outage on the
+# hundredth request.
 #
-# Ce fichier est versionne. `.env` ne l'est jamais.
+# This file is committed. `.env` never is.
 
 # ---------------------------------------------------------------------------
-# Base de donnees
+# Database
 # ---------------------------------------------------------------------------
 
-# PostgreSQL, et rien d'autre. Aucune base locale : l'URL pointe sur une base
-# hebergee, la votre ou celle provisionnee par `odoro db:create`.
+# PostgreSQL, and nothing else. No local database: the URL points at a hosted
+# one, yours or the one provisioned by `odoro db:create`.
 #
-#   postgres://utilisateur:motdepasse@hote:5432/base?sslmode=require
+#   postgres://user:password@host:5432/database?sslmode=require
 #
-# Tant qu'elle est absente, le client demarre et le serveur repond 503 sur
-# /api/ready en disant ce qui manque.
+# While it is missing, the client starts and the server answers 503 on
+# /api/ready saying what is absent.
 DATABASE_URL=
 
-# Replica de lecture, optionnel. Le routage vers lui reste explicite : jamais
-# de bascule automatique, le decalage de replication produit des defauts
-# incomprehensibles.
+# Read replica, optional. Routing to it stays explicit: never an automatic
+# switch, replication lag produces bugs nobody can make sense of.
 # DATABASE_REPLICA_URL=
 
-# Taille du pool de connexions. Laisser vide pour le defaut de l'environnement.
+# Connection pool size. Leave empty for the environment default.
 # DATABASE_POOL_MAX=
 
-# Desactive TLS. A ne poser que sur une base strictement locale a la machine,
-# jamais sur une base joignable par le reseau.
+# Disables TLS. Only ever set this for a database strictly local to the
+# machine, never for one reachable over the network.
 # DATABASE_TLS_DISABLED=false
 
 # ---------------------------------------------------------------------------
 # Session
 # ---------------------------------------------------------------------------
 
-# Au moins 32 caracteres. Un secret court se retrouve par force brute, et le
-# jour ou c'est arrive, toutes les sessions emises depuis le premier jour sont
-# forgeables.
+# At least 32 characters. A short secret falls to brute force, and the day that
+# happens, every session issued since day one can be forged.
 #
 #   node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
 SESSION_SECRET=
 
 # ---------------------------------------------------------------------------
-# Serveur
+# Server
 # ---------------------------------------------------------------------------
 
-# Environnement : development | test | production
+# Environment: development | test | production
 NODE_ENV=development
 
-# Port d'ecoute de l'API. Le client de developpement ecoute sur 5180 et lui
-# transmet les appels commencant par /api.
+# Listening port of the API. The development client listens on 5180 and
+# forwards the calls starting with /api to it.
 PORT=3001
 
-# URL publique du serveur, employee dans les liens des courriels.
+# Public URL of the server, used in the links of outgoing emails.
 APP_URL=http://localhost:3001
 
-# Origines autorisees, separees par des virgules. Vide = aucune origine
-# tierce. Jamais `*` avec des identifiants.
+# Allowed origins, comma separated. Empty = no third-party origin. Never `*`
+# together with credentials.
 ALLOWED_ORIGINS=
 
-# Plafond de la taille des corps de requete.
+# Cap on the size of request bodies.
 BODY_LIMIT=1mb
 
-# Delai au-dela duquel l'arret propre cesse d'attendre les requetes en cours.
+# Delay after which the graceful shutdown stops waiting for in-flight requests.
 SHUTDOWN_TIMEOUT=15s
 
-# Niveau de journalisation : fatal | error | warn | info | debug | trace
+# Log level: fatal | error | warn | info | debug | trace
 LOG_LEVEL=info
 
 # ---------------------------------------------------------------------------
-# Files d'attente et cache
+# Queues and cache
 # ---------------------------------------------------------------------------
 
-# Optionnel. Absente, le cache vit en memoire et les taches s'executent en
-# ligne — ce qui convient a une instance unique, et pas au-dela.
+# Optional. Absent, the cache lives in memory and the jobs run inline — which
+# suits a single instance, and nothing beyond.
 # REDIS_URL=

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

@@ -0,0 +1,118 @@
+/**
+ * The decorative background, as a WebGL surface.
+ *
+ * This version replaces the static gradient because the engine was picked at
+ * creation. The rest of the page is unchanged: it places `<Background />` and
+ * does not know what is behind it.
+ *
+ * ## What the engine brings that a gradient cannot
+ *
+ * **An arbiter.** The surface is asked of the engine manager, which refuses it
+ * if the browser has no WebGL, if too many contexts are already open, or if
+ * the device would not keep up. The refusal is a value, not an exception: the
+ * gradient is shown instead, and the page holds.
+ *
+ * **Reduced motion.** Under that preference nothing is mounted: the background
+ * brought only its motion, and the graphics card has no business waking up for
+ * a visitor who asked for calm.
+ *
+ * **The theme colours.** The hues are read from the tokens, not written into
+ * the shader. A light / dark switch re-reads them, and changing
+ * `--o-palette-brand-500` repaints the background without touching this file.
+ *
+ * ## Why inline styles
+ *
+ * This file is laid down whatever the rest: a project that unticked the
+ * libraries has no `o-*` classes, and a missing class paints nothing — the
+ * background would then be zero pixels tall, with nothing to report it. So the
+ * few placement rules are written where they are safe.
+ *
+ * @module
+ */
+
+import {
+  AURORA_FRAGMENT,
+  readTokenColour,
+  useMotionState,
+  useShaderSurface,
+  type ShaderColour,
+} from '@odoro-cli/engine'
+import { useEffect, useMemo, useState, type ReactElement } from 'react'
+
+/** The tokens read to tint the glow. */
+const HUES = ['--o-palette-brand-500', '--o-palette-brand-300', '--o-theme-bg'] as const
+
+/** The gradient served while the surface is not there — or forever. */
+function Gradient(): ReactElement {
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        inset: 0,
+        opacity: 0.28,
+        filter: 'blur(64px)',
+        background:
+          'radial-gradient(60% 60% at 50% 0%, var(--o-palette-brand-500, #3b82f6), transparent)',
+      }}
+    />
+  )
+}
+
+/** An animated glow behind the top of the page. */
+export function Background(): ReactElement {
+  const { quality, reduced } = useMotionState()
+  const [host, setHost] = useState<HTMLElement | null>(null)
+  const [hues, setHues] = useState<readonly ShaderColour[]>([])
+
+  // Re-read when the host appears and when the theme switches — the latter
+  // goes through the motion policy, which is renewed on every state.
+  useEffect(() => {
+    if (host === null) return
+    setHues(HUES.map((token) => readTokenColour(token, host)))
+  }, [host, reduced, quality])
+
+  const uniforms = useMemo(() => {
+    const [a, b, c] = hues
+    if (a === undefined || b === undefined || c === undefined) return undefined
+    // The theme background dominates, the brand is only a reflection: these
+    // three colours go into a mix, and two brand hues out of three would give
+    // a full-page glow rather than a halo.
+    return { uColorA: c, uColorB: c, uColorC: a, uSpeed: 0.1, uScale: 1.4, uOctaves: 3 }
+  }, [hues])
+
+  const { ref, ready, refused } = useShaderSurface<HTMLDivElement>({
+    fragment: AURORA_FRAGMENT,
+    uniforms: uniforms ?? {},
+    name: 'home-background',
+  })
+
+  const fallback = !ready || refused !== undefined || uniforms === undefined
+
+  return (
+    <div
+      aria-hidden="true"
+      ref={(element) => {
+        setHost(element)
+        ref.current = element
+      }}
+      style={{
+        position: 'absolute',
+        insetInline: 0,
+        top: 0,
+        height: '42rem',
+        overflow: 'hidden',
+        pointerEvents: 'none',
+        // A decorative background is noticed when you look for it, not before.
+        // At full strength the glow comes in front of the title it is supposed
+        // to carry; at a fifth, it underlines it.
+        opacity: 0.2,
+        // The bottom dissolves into the page: a surface that stops dead draws
+        // a horizontal line that nothing justifies.
+        maskImage: 'linear-gradient(to bottom, black 45%, transparent)',
+        WebkitMaskImage: 'linear-gradient(to bottom, black 45%, transparent)',
+      }}
+    >
+      {fallback ? <Gradient /> : null}
+    </div>
+  )
+}

package/templates/react-ts-server/_variants/without-libs/client/src/App.tsx

@@ -0,0 +1,380 @@
+/**
+ * The whole page, in one file.
+ *
+ * ## Without the libraries
+ *
+ * They were not picked at creation: no `o-*` classes, no tokens, no router.
+ * The design is that of the full version — same pill bar, same title, same
+ * cards — carried by `styles.css` in plain CSS.
+ *
+ * To add them later: `npm i @odoro-cli/libs`, then import
+ * `@odoro-cli/libs/styles.css` in `main.tsx` before this stylesheet.
+ *
+ * @module
+ */
+
+import { useEffect, useState, type ReactElement } from 'react'
+
+import { Background } from '@/background'
+
+/* -------------------------------------------------------------------------- */
+/*  Brand                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/** The brand mark, at the requested size. */
+function Mark({ size = '1.75rem' }: { readonly size?: string }): ReactElement {
+  return (
+    <svg
+      viewBox="0 0 100 100"
+      fill="none"
+      aria-hidden="true"
+      style={{ width: size, height: size, flexShrink: 0 }}
+    >
+      <path
+        d="M20.25 20.25H50a29.75 29.75 0 1 1-29.75 29.75Z"
+        stroke="currentColor"
+        strokeWidth="10.5"
+        strokeLinejoin="miter"
+      />
+    </svg>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Navigation bar                                                             */
+/* -------------------------------------------------------------------------- */
+
+/** The bar: the brand in a pill, and the link to the site. */
+function Nav(): ReactElement {
+  return (
+    <header className="nav">
+      <div className="nav-content">
+        <span className="pill brand">
+          <span className="brand-mark">
+            <Mark />
+          </span>
+          <span className="brand-word">ODORO</span>
+        </span>
+
+        <div className="nav-end">
+          <a
+            href="https://odoro.dev"
+            target="_blank"
+            rel="noreferrer"
+            className="pill pill-link"
+          >
+            odoro.dev
+          </a>
+          <ThemeToggle />
+        </div>
+      </div>
+    </header>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Theme                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/** The three states of the toggle. */
+type Theme = 'system' | 'light' | 'dark'
+
+/** Where the choice is stored. The script in `index.html` reads the same key. */
+const THEME_KEY = 'odoro-theme'
+
+/** The order of the cycle, on click. */
+const CYCLE: readonly Theme[] = ['system', 'light', 'dark']
+
+/**
+ * Applies the theme to the root of the document.
+ *
+ * `system` removes the attribute rather than setting a third value: the
+ * stylesheet listens to `data-theme`, and its absence hands control back to
+ * the browser preference.
+ */
+function applyTheme(theme: Theme): void {
+  if (theme === 'system') delete document.documentElement.dataset.theme
+  else document.documentElement.dataset.theme = theme
+}
+
+/** The stored theme, or `system`. */
+function storedTheme(): Theme {
+  try {
+    const value = localStorage.getItem(THEME_KEY)
+    if (value === 'light') return 'light'
+    if (value === 'dark') return 'dark'
+    return 'system'
+  } catch {
+    // Storage refused — private window, cookies blocked. The system theme is
+    // still a valid answer.
+    return 'system'
+  }
+}
+
+/** The three glyphs, drawn inline. */
+function Glyph({ theme }: { readonly theme: Theme }): ReactElement {
+  const common = {
+    viewBox: '0 0 24 24',
+    fill: 'none',
+    stroke: 'currentColor',
+    strokeWidth: 1.8,
+    strokeLinecap: 'round' as const,
+    strokeLinejoin: 'round' as const,
+    'aria-hidden': true,
+    style: { width: '1.15rem', height: '1.15rem' },
+  }
+
+  if (theme === 'light') {
+    return (
+      <svg {...common}>
+        <circle cx="12" cy="12" r="4" />
+        <path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" />
+      </svg>
+    )
+  }
+
+  if (theme === 'dark') {
+    return (
+      <svg {...common}>
+        <path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8Z" />
+      </svg>
+    )
+  }
+
+  return (
+    <svg {...common}>
+      <rect x="2" y="4" width="20" height="13" rx="2" />
+      <path d="M8 21h8M12 17v4" />
+    </svg>
+  )
+}
+
+/** The theme toggle: system, light, dark. */
+function ThemeToggle(): ReactElement {
+  const [theme, setTheme] = useState<Theme>(() => storedTheme())
+
+  useEffect(() => {
+    applyTheme(theme)
+    try {
+      if (theme === 'system') localStorage.removeItem(THEME_KEY)
+      else localStorage.setItem(THEME_KEY, theme)
+    } catch {
+      // The theme stays applied for the session, even without storage.
+    }
+  }, [theme])
+
+  return (
+    <button
+      type="button"
+      aria-label={`Theme: ${theme}`}
+      title={`Theme: ${theme}`}
+      className="pill toggle"
+      onClick={() => {
+        setTheme((current) => CYCLE[(CYCLE.indexOf(current) + 1) % CYCLE.length] ?? 'system')
+      }}
+    >
+      <Glyph theme={theme} />
+    </button>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Sections                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/** Three facts, not three slogans. */
+const FACTS = ['Zero configuration', 'Strict TypeScript', 'Hot reloading']
+
+/** What the product window shows. */
+const SNIPPET = `export function App() {
+  return (
+    <h1 className="hero-title">
+      Your first page.
+    </h1>
+  )
+}`
+
+/** A miniature browser window. */
+function Window(): ReactElement {
+  return (
+    <div className="window">
+      <div className="window-bar">
+        <span className="window-dots" aria-hidden="true">
+          <span />
+          <span />
+          <span />
+        </span>
+        <span className="window-path">src/App.tsx</span>
+      </div>
+      <pre className="window-code">{SNIPPET}</pre>
+    </div>
+  )
+}
+
+/** The hero: the promise, the actions, and the product window. */
+function Hero(): ReactElement {
+  return (
+    <section className="hero">
+      <div className="content">
+        <span className="brand-dot">
+          <Mark size="0.9rem" />
+          Generated by odoro create
+        </span>
+
+        <h1 className="hero-title">
+          Your first page, <span className="accent">already alive</span>.
+        </h1>
+
+        <p className="hero-eyebrow">
+          The development server, the build and the hot reloading all come from{' '}
+          <code>odoro</code>. The style system is yours.
+        </p>
+
+        <div className="hero-actions">
+          <a href="#pillars" className="button button-primary">
+            See what is included
+          </a>
+          <a
+            href="https://odoro.dev/docs"
+            target="_blank"
+            rel="noreferrer"
+            className="button button-secondary"
+          >
+            Documentation
+          </a>
+        </div>
+
+        <div className="facts">
+          {FACTS.map((fact) => (
+            <span key={fact} className="fact">
+              {fact}
+            </span>
+          ))}
+        </div>
+
+        <div className="hero-window">
+          <Window />
+        </div>
+      </div>
+    </section>
+  )
+}
+
+/** What the project already has at hand. */
+const PILLARS = [
+  {
+    title: 'Build',
+    text: 'A development server with hot reloading, and a production build.',
+  },
+  {
+    title: 'TypeScript',
+    text: 'Strict types, path aliases, and checking without emitting.',
+  },
+  {
+    title: 'Over to you',
+    text: 'No style system imposed: yours takes all the room.',
+  },
+]
+
+/** The pillars section. */
+function Pillars(): ReactElement {
+  return (
+    <section id="pillars" className="section">
+      <div className="content">
+        <h2 className="overline">What is already here</h2>
+        <div className="grid">
+          {PILLARS.map((pillar, index) => (
+            <article key={pillar.title} className="card">
+              <span className="card-number">{String(index + 1).padStart(2, '0')}</span>
+              <h3>{pillar.title}</h3>
+              <p>{pillar.text}</p>
+            </article>
+          ))}
+        </div>
+      </div>
+    </section>
+  )
+}
+
+/** The command people copy the most. */
+const COMMAND = 'npm i @odoro-cli/libs'
+
+/** The closing: one command, and the door to the documentation. */
+function Closing(): ReactElement {
+  const [copied, setCopied] = useState(false)
+
+  return (
+    <section className="section section-centered">
+      <div className="content-narrow">
+        <h2 className="closing-title">Add the style system whenever you like.</h2>
+        <p className="closing-eyebrow">
+          The tokens, the utilities and the components live in a separate package. This
+          project runs without them, and takes them in without breaking anything.
+        </p>
+
+        <div className="command">
+          <code>{COMMAND}</code>
+          <button
+            type="button"
+            className="button button-ghost"
+            onClick={() => {
+              // The clipboard can be refused — outside a secure context, or
+              // permission withdrawn. The failure does not break the page: the
+              // label simply does not change.
+              void navigator.clipboard
+                ?.writeText(COMMAND)
+                .then(() => {
+                  setCopied(true)
+                  setTimeout(() => {
+                    setCopied(false)
+                  }, 1600)
+                })
+                .catch(() => undefined)
+            }}
+          >
+            {copied ? 'Copied' : 'Copy'}
+          </button>
+        </div>
+
+        <a
+          href="https://odoro.dev/docs/installation"
+          target="_blank"
+          rel="noreferrer"
+          className="quiet-link"
+        >
+          Read the walkthrough
+        </a>
+      </div>
+    </section>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Root                                                                       */
+/* -------------------------------------------------------------------------- */
+
+/** Root of the application. */
+export function App(): ReactElement {
+  return (
+    // The background sits here and not in the content: anchored lower, it
+    // started below the bar and left a darker strip behind it.
+    <div className="app-shell app-shell-background">
+      <Background />
+      <Nav />
+      <main className="main">
+        <Hero />
+        <Pillars />
+        <Closing />
+      </main>
+      <footer className="footer">
+        <span className="brand">
+          <span className="brand-mark">
+            <Mark size="1.1rem" />
+          </span>
+          <span className="brand-word">ODORO</span>
+        </span>
+        <span>Built with Odoro.</span>
+      </footer>
+    </div>
+  )
+}

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

@@ -0,0 +1,24 @@
+/**
+ * The decorative background of the page.
+ *
+ * Two glows in the brand colour, heavily diluted. Nothing moves: it is a
+ * gradient, not an animation.
+ *
+ * If the engine was picked, this file is replaced by a version that opens an
+ * animated WebGL surface. `App.tsx` places `<Background />` and asks for
+ * nothing more.
+ *
+ * @module
+ */
+
+import type { ReactElement } from 'react'
+
+/** Two brand glows behind the top of the page. */
+export function Background(): ReactElement {
+  return (
+    <div className="background" aria-hidden="true">
+      <div className="background-glow background-glow-top" />
+      <div className="background-glow background-glow-right" />
+    </div>
+  )
+}

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

@@ -0,0 +1,39 @@
+/**
+ * The prerendering entry point.
+ *
+ * Without a router there is only one page: the list of routes comes down to
+ * the root. The rest is identical — `odoro build` renders this HTML at build
+ * time, and `src/main.tsx` hydrates it on load.
+ *
+ * To do without: remove `prerender` from `odoro.config.ts`, then this file.
+ *
+ * @module
+ */
+
+import { StrictMode } from 'react'
+import { renderToString } from 'react-dom/server'
+
+import { App } from '@/App'
+
+/** The routes rendered at build time. */
+export const routes = ['/']
+
+/**
+ * Renders the page.
+ *
+ * @returns The HTML of the container, and the tags to add to the head.
+ */
+export function render(): { html: string; head: string } {
+  return {
+    // `StrictMode` on both sides: a tree rendered without it here and with it
+    // in the browser does not always produce the same markup, and hydration
+    // would report a difference that is not one.
+    html: renderToString(
+      <StrictMode>
+        <App />
+      </StrictMode>,
+    ),
+    head:
+      '<meta name="description" content="An Odoro project: in-house engine, generated styles.">',
+  }
+}