pgkiln 0.53.0 → 0.55.0

package/src/builder/i18n.ts

@@ -0,0 +1,116 @@
+// (sprint 121, WS-7) The builder in more languages, like APEX's builder (Deutsch, English, Español, Français, …):
+// the builder's own texts are keyed messages in src/builder/i18n/<lang>.ts, the same mechanism as the runtime's
+// texts in src/i18n.ts. English (en.ts) defines the keys; every other language file is a Record of the same keys
+// (TypeScript refuses a missing or an unknown key, test/builder-i18n.test.ts checks the files and the source).
+//
+// A page gets its translator from the session: `const tx = tr(s)`, then `tx('rail.app_builder')`, or with
+// {placeholders}: `tx('ab.count', { n: 3 })`. The result is plain text: the html`` tag escapes it like any value.
+// `tx.rich()` puts markup (links) into a sentence: the message is escaped, Raw parameters are kept.
+// `tx.dyn()` takes a key made at run time (a region type's gallery label, a SQL Workshop tool) with a fallback.
+// A text that is not keyed yet simply stays English. Moving a screen over: docs/guide/12-development.md.
+//
+// The developer's choice: meta.developer.language (migration 127), copied into the session (__BLANG) at sign-in;
+// before signing in, the sign-in page's language links set a cookie (LANG_COOKIE). See language.ts.
+
+import type { FastifyRequest } from 'fastify';
+import { esc, raw, Raw } from '../html.ts';
+import type { Session } from '../session.ts';
+import { de } from './i18n/de.ts';
+import { en } from './i18n/en.ts';
+import { es } from './i18n/es.ts';
+import { fr } from './i18n/fr.ts';
+import { nl } from './i18n/nl.ts';
+import { pt } from './i18n/pt.ts';
+
+export type BuilderKey = keyof typeof en;
+export type BuilderMessages = Record<BuilderKey, string>;
+export type Params = Record<string, string | number | null | undefined>;
+
+/** The builder's languages, in the order of the language menu and the sign-in page's links (names in their own language). */
+export const BUILDER_LANGUAGES = [
+  ['de', 'Deutsch'], ['en', 'English'], ['es', 'Español'], ['fr', 'Français'], ['nl', 'Nederlands'], ['pt', 'Português'],
+] as const;
+export type BuilderLang = (typeof BUILDER_LANGUAGES)[number][0];
+
+const MESSAGES: Record<BuilderLang, Readonly<Record<string, string>>> = { en, de, es, fr, nl, pt };
+
+/** The cookie with the sign-in page's language on this device (the builder's path only). */
+export const LANG_COOKIE = 'pgkiln_blang';
+
+/** A known builder language code, or null: only the codes in BUILDER_LANGUAGES, exactly. */
+export const validBuilderLanguage = (v: unknown): BuilderLang | null =>
+  typeof v === 'string' && Object.hasOwn(MESSAGES, v) ? (v as BuilderLang) : null;
+
+/** The language of a developer's session (English when none was chosen). */
+export const builderLanguage = (s: Pick<Session, 'state'> | null | undefined): BuilderLang => validBuilderLanguage(s?.state?.__BLANG) ?? 'en';
+
+/** The language of a visitor's sign-in page (or a builder error page): the cookie, else English. */
+export const cookieLanguage = (req: FastifyRequest): BuilderLang =>
+  validBuilderLanguage((req.cookies as Record<string, string> | undefined)?.[LANG_COOKIE]) ?? 'en';
+
+export const languageName = (lang: BuilderLang) => BUILDER_LANGUAGES.find(([c]) => c === lang)![1];
+
+const fill = (text: string, params?: Params) =>
+  params ? text.replace(/\{(\w+)\}/g, (m, k: string) => (params[k] === undefined || params[k] === null ? m : String(params[k]))) : text;
+
+export interface BuilderTranslate {
+  (key: BuilderKey, params?: Params): string;
+  readonly lang: BuilderLang;
+  /** A key made at run time: its text in this language, else in English, else the fallback (never the raw key). */
+  dyn(key: string, fallback: string, params?: Params): string;
+  /** A sentence with markup: the message is escaped, string parameters too; Raw parameters (links) are kept. */
+  rich(key: BuilderKey, params: Record<string, string | number | Raw>): Raw;
+  /** An English label passed around as text (a breadcrumb, a page title) in this language, when it is a known one. */
+  label(text: string): string;
+}
+
+/**
+ * English labels that many builder pages pass to shell() as text (breadcrumbs, titles): translated there, so a
+ * page that isn't keyed yet still gets a translated breadcrumb trail for these.
+ */
+const LABELS: Record<string, BuilderKey> = {
+  'App Builder': 'rail.app_builder',
+  'SQL Workshop': 'rail.sql_workshop',
+  Home: 'rail.home',
+  'App Gallery': 'rail.gallery',
+  'Data Reporter': 'rail.reporter',
+  'Team Development': 'rail.team',
+  Search: 'common.search',
+  'Workspace home': 'wh.title',
+  'Workspace utilities': 'admin.utilities',
+  Dashboard: 'ab.tile.dashboard',
+  Import: 'ab.tile.import',
+  Developers: 'admin.developers',
+  Users: 'nav.users',
+  'Shared Components': 'app.tab.shared',
+  Settings: 'app.tab.settings',
+};
+
+/** A translator: the language's messages (`own`, for tests: a partial file), then English, then the key itself. */
+export function builderTranslator(lang: BuilderLang, own: Readonly<Record<string, string>> = MESSAGES[lang]): BuilderTranslate {
+  const text = (key: string): string | undefined => own[key] ?? (en as Record<string, string>)[key];
+  const tx = ((key: BuilderKey, params?: Params) => fill(text(key) ?? key, params)) as BuilderTranslate;
+  Object.defineProperty(tx, 'lang', { value: lang });
+  tx.dyn = (key, fallback, params) => fill(text(key) ?? fallback, params);
+  tx.rich = (key, params) =>
+    raw(esc(text(key) ?? key).replace(/\{(\w+)\}/g, (m, k: string) => {
+      const v = params[k];
+      return v === undefined ? m : v instanceof Raw ? v.value : esc(v);
+    }));
+  tx.label = (label) => (Object.hasOwn(LABELS, label) ? tx(LABELS[label]) : label);
+  return tx;
+}
+
+const CACHE = new Map<BuilderLang, BuilderTranslate>();
+/** The translator of a language (one per language, kept). */
+export const translatorFor = (lang: BuilderLang) => {
+  let t = CACHE.get(lang);
+  if (!t) CACHE.set(lang, (t = builderTranslator(lang)));
+  return t;
+};
+
+/** The translator of a developer's session. */
+export const tr = (s: Pick<Session, 'state'> | null | undefined) => translatorFor(builderLanguage(s));
+
+/** For tests and the coverage check: the message files. */
+export const builderMessages = (lang: BuilderLang): Readonly<Record<string, string>> => MESSAGES[lang];

package/src/builder/language.ts

@@ -0,0 +1,74 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import { owner } from '../db.ts';
+import { html, raw } from '../html.ts';
+import { icon } from '../icons.ts';
+import type { Session } from '../session.ts';
+import { BUILDER_LANGUAGES, LANG_COOKIE, tr, validBuilderLanguage, type BuilderLang } from './i18n.ts';
+import { back, BASE, csrf, developer, type Req } from './ui.ts';
+
+// (sprint 121, WS-7) Choosing the builder's language (APEX: the language links of the builder).
+//  - Signed in: the language menu in the status bar (footer) of every builder page posts to /builder/language
+//    (CSRF-checked); the choice is stored for the developer (meta.developer.language, migration 127) and in the
+//    session, so it holds in every later session and on every device.
+//  - Signed out: the sign-in page's language links (GET /builder/login?lang=de) set a cookie only (LANG_COOKIE),
+//    for the sign-in page; signing in after such a link stores it for the developer (routes.ts).
+// Only the codes of BUILDER_LANGUAGES are accepted; anything else is ignored (a link) or refused (400, the menu).
+// Nothing here may run at import time: ui.ts imports this module and this module imports ui.ts.
+
+export const langCookieOptions = () => ({ path: BASE, httpOnly: true, sameSite: 'lax' as const, maxAge: 365 * 24 * 3600, secure: process.env.COOKIE_SECURE === 'true' });
+
+/** Put the developer's stored language into a session that has none yet (a session from before this sprint). */
+export async function loadLanguage(s: Session) {
+  if (!s.username) return;
+  const r = await owner.one<{ language: string | null }>('select language from meta.developer where username = $1', [s.username]);
+  s.state.__BLANG = validBuilderLanguage(r?.language) ?? 'en';
+}
+
+/** Store a developer's choice (and set it for this session and the sign-in page of this device). */
+export async function chooseLanguage(reply: FastifyReply, s: Session, lang: BuilderLang) {
+  await owner.query('update meta.developer set language = $2 where username = $1', [s.username, lang]);
+  s.state.__BLANG = lang;
+  reply.setCookie(LANG_COOKIE, lang, langCookieOptions());
+}
+
+/** The language menu of the builder's status bar: a <details> menu of buttons in a form (no script needed). */
+export function languageMenu(s: Session) {
+  const tx = tr(s);
+  return html`<details class="menu ide-lang" data-lang-menu>
+    <summary title="${tx('status.language')}">${icon('globe')}<span class="sr-only">${tx('status.language')}: </span><span lang="${tx.lang}">${BUILDER_LANGUAGES.find(([c]) => c === tx.lang)![1]}</span></summary>
+    <div class="menu-panel">
+      <form method="post" action="${BASE}/language" class="menu-section menu-links ide-lang-form" aria-label="${tx('status.language')}">${csrf(s)}
+        <span class="small muted">${tx('status.language')}</span>
+        ${BUILDER_LANGUAGES.map(([code, name]) => html`<button name="language" value="${code}" lang="${code}"${code === tx.lang ? raw(' aria-current="true"') : ''}>${code === tx.lang ? icon('check') : html`<span class="ide-lang-pad" aria-hidden="true"></span>`}${name}</button>`)}
+      </form>
+    </div></details>`;
+}
+
+/** The sign-in page's language links (APEX: Deutsch, English, Español, …), keeping where to go after signing in. */
+export function signInLanguageLinks(current: BuilderLang, next: string, label: string) {
+  return html`<nav class="signin-langs" aria-label="${label}"><ul>${BUILDER_LANGUAGES.map(([code, name]) => {
+    const q = new URLSearchParams({ lang: code, ...(next !== `${BASE}/home` ? { next } : {}) });
+    return html`<li><a href="${BASE}/login?${q}" lang="${code}" hreflang="${code}"${code === current ? raw(' aria-current="true"') : ''}>${name}</a></li>`;
+  })}</ul></nav>`;
+}
+
+/** A builder address on this host to go back to (the referring page), else the App Builder. */
+const backTo = (req: FastifyRequest) => {
+  try {
+    const u = new URL(String(req.headers.referer ?? ''));
+    return u.host === req.headers.host && u.pathname.startsWith(BASE) ? u.pathname + u.search : BASE;
+  } catch {
+    return BASE;
+  }
+};
+
+export async function languageRoutes(app: FastifyInstance) {
+  app.post(`${BASE}/language`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const lang = validBuilderLanguage(req.body?.language);
+    if (!lang) return reply.code(400).send('Unknown language');
+    await chooseLanguage(reply, s, lang);
+    return back(reply, s, backTo(req));
+  });
+}

package/src/builder/launchpad.ts

@@ -4,7 +4,8 @@ import { html, type Raw } from '../html.ts';
 import { icon } from '../icons.ts';
 import type { Session } from '../session.ts';
 import { back, BASE, csrf, designerUrl, developer, flash, send, shell, type Req } from './ui.ts';
-import { SQL_TOOLS, TOOL_GROUPS } from './sql-tools.ts';
+import { SQL_TOOLS, TOOL_GROUPS, toolDescription, toolLabel } from './sql-tools.ts';
+import { tr } from './i18n.ts';
 import { SYSTEM_SCHEMAS } from './object-browser.ts';
 import { currentWorkspace, inWorkspaceSql, workshopDb } from './workspaces.ts';
 import { isAdmin } from './locks.ts';
@@ -28,10 +29,11 @@ export async function pinsOf(s: Session): Promise<Pin[]> {
 
 /** A pin toggle (a small form): pinned → unpin, else pin. */
 export function pinButton(s: Session, p: Pin, pinned: boolean, backTo: string): Raw {
+  const tx = tr(s);
   return html`<form method="post" action="${BASE}/pins" class="pin-form">${csrf(s)}
     <input type="hidden" name="href" value="${p.href}"><input type="hidden" name="label" value="${p.label}"><input type="hidden" name="icon" value="${p.icon}">
     <input type="hidden" name="pin" value="${pinned ? '0' : '1'}"><input type="hidden" name="back" value="${backTo}">
-    <button class="pin-btn${pinned ? ' is-pinned' : ''}" title="${pinned ? 'Unpin' : 'Pin to the SQL Workshop home'}" aria-pressed="${pinned ? 'true' : 'false'}">${icon('pin')}<span class="sr-only">${pinned ? 'Unpin' : 'Pin'} ${p.label}</span></button></form>`;
+    <button class="pin-btn${pinned ? ' is-pinned' : ''}" title="${tx(pinned ? 'sw.unpin' : 'sw.pin_title')}" aria-pressed="${pinned ? 'true' : 'false'}">${icon('pin')}<span class="sr-only">${tx(pinned ? 'sw.unpin_what' : 'sw.pin_what', { what: p.label })}</span></button></form>`;
 }
 
 /** The Launchpad part of the SQL Workshop home. */
@@ -39,18 +41,21 @@ export async function launchpad(s: Session, admin: boolean): Promise<Raw> {
   const pins = await pinsOf(s);
   const pinned = new Set(pins.map((p) => p.href));
   const tools = SQL_TOOLS.filter((t) => admin || !t.admin);
+  const tx = tr(s);
+  // a pin keeps the tool's English name (pins are stored with their label); the card shows it in the builder's language
   const card = (t: (typeof SQL_TOOLS)[number]) => html`<li class="lp-tool">
-    <a href="${t.href}">${icon(t.icon)}<span><strong>${t.label}</strong><small class="muted">${t.description}</small></span></a>
+    <a href="${t.href}">${icon(t.icon)}<span><strong>${toolLabel(tx, t)}</strong><small class="muted">${toolDescription(tx, t)}</small></span></a>
     ${pinButton(s, { href: t.href, label: t.label, icon: t.icon }, pinned.has(t.href), `${BASE}/sql`)}</li>`;
+  const group = (g: string, label: string) => tx.dyn(`sql.group.${g}`, label);
   return html`<section class="lp-pins" aria-labelledby="lp-pins-title">
-      <h2 id="lp-pins-title">Pinned &amp; recently visited</h2>
+      <h2 id="lp-pins-title">${tx('sw.pinned')}</h2>
       ${pins.length ? html`<ul class="lp-chips">${pins.map((p) => html`<li><a href="${p.href}">${icon(p.icon)}<span>${p.label}</span></a>${pinButton(s, p, true, `${BASE}/sql`)}</li>`)}</ul>`
-        : html`<p class="muted small">Pin a tool, an object or a saved worksheet with ${icon('pin')} to keep it here.</p>`}
-      <ul class="lp-chips lp-recent" data-lp-recent aria-label="Recently visited" hidden></ul>
+        : html`<p class="muted small">${tx.rich('sw.pin_hint', { pin: icon('pin') })}</p>`}
+      <ul class="lp-chips lp-recent" data-lp-recent aria-label="${tx('sw.recent')}" hidden></ul>
     </section>
     <div class="lp-groups">
-      <div class="lp-tabs" role="tablist" aria-label="Tools" hidden>${TOOL_GROUPS.map(([g, label], i) => html`<button type="button" role="tab" aria-selected="${i === 0 ? 'true' : 'false'}" aria-controls="lp-${g}" data-lp-tab="${g}">${label}</button>`)}</div>
-      ${TOOL_GROUPS.map(([g, label]) => html`<section class="lp-group" id="lp-${g}" data-lp-group="${g}" aria-label="${label}"><h2>${label}</h2><ul class="lp-list">${tools.filter((t) => t.group === g).map(card)}</ul></section>`)}
+      <div class="lp-tabs" role="tablist" aria-label="${tx('wh.tools')}" hidden>${TOOL_GROUPS.map(([g, label], i) => html`<button type="button" role="tab" aria-selected="${i === 0 ? 'true' : 'false'}" aria-controls="lp-${g}" data-lp-tab="${g}">${group(g, label)}</button>`)}</div>
+      ${TOOL_GROUPS.map(([g, label]) => html`<section class="lp-group" id="lp-${g}" data-lp-group="${g}" aria-label="${group(g, label)}"><h2>${group(g, label)}</h2><ul class="lp-list">${tools.filter((t) => t.group === g).map(card)}</ul></section>`)}
     </div>`;
 }
 

package/src/builder/object-browser.ts

@@ -158,7 +158,7 @@ export async function objectBrowserRoutes(app: FastifyInstance) {
         <a class="create-source" href="${BASE}/sql/load">${icon('upload')}<span><b>Load data</b><small class="muted">A table from a file</small></span></a></div>
         <p class="muted">Select an object in the tree, or filter it by name.</p>`);
 
-    const main = html`<h1 class="u-mb1">SQL Workshop</h1>${workshopTabs('objects')}
+    const main = html`<h1 class="u-mb1">SQL Workshop</h1>${workshopTabs('objects', s)}
       <div class="ob-head">
         <form method="get" class="ob-schema">${filter ? html`<input type="hidden" name="q" value="${filter}">` : ''}
           <label class="label" for="ob-schema">Schema</label>

package/src/builder/plugins.ts

@@ -84,7 +84,7 @@ async function page(s: Session, a: any, selected: string | undefined, result?: {
         </div>`)
     : '';
 
-  return html`${appHeader(a, 'shared')}
+  return html`${appHeader(a, 'shared', s)}
     ${result ? region(`Result: install SQL of ${result.name}`, resultsHtml('install', result.run)) : ''}
     ${detail}
     ${region('Plug-ins', html`<p class="muted u-mt0">Region, item, dynamic action and process types that bring their own code: JavaScript and CSS as

package/src/builder/querybuilder.ts

@@ -365,6 +365,6 @@ export async function queryBuilderRoutes(app: FastifyInstance) {
           <form method="post" action="${BASE}/sql">${csrf(s)}<input type="hidden" name="sql" value="${built.sql}">
             <div class="buttons"><button class="btn btn-hot">${icon('play')} Run in the SQL Worksheet</button></div></form>`)}`
       : '';
-    return send(reply, s, shell(s, 'Query Builder', [['SQL Workshop', `${BASE}/sql`], ['Query Builder']], html`<h1 class="u-mb1">SQL Workshop</h1>${workshopTabs('query')}${form}${output}`, 'sql'));
+    return send(reply, s, shell(s, 'Query Builder', [['SQL Workshop', `${BASE}/sql`], ['Query Builder']], html`<h1 class="u-mb1">SQL Workshop</h1>${workshopTabs('query', s)}${form}${output}`, 'sql'));
   });
 }

package/src/builder/quicksql.ts

@@ -52,7 +52,7 @@ export async function quickSqlRoutes(app: FastifyInstance) {
         <div class="buttons"><button class="btn" name="action" value="save">${icon('file')} Save as script</button>
           <button class="btn btn-hot" name="action" value="run">${icon('play')} Run</button></div>`)}
     </form>`;
-    return send(reply, s, shell(s, 'Quick SQL', [['SQL Workshop', `${BASE}/sql`], ['Quick SQL']], html`<h1 class="u-mb1">SQL Workshop</h1>${workshopTabs('quicksql')}${main}`, 'sql'));
+    return send(reply, s, shell(s, 'Quick SQL', [['SQL Workshop', `${BASE}/sql`], ['Quick SQL']], html`<h1 class="u-mb1">SQL Workshop</h1>${workshopTabs('quicksql', s)}${main}`, 'sql'));
   };
 
   app.get(`${BASE}/sql/quick`, async (req: Req, reply) => {

package/src/builder/rest-modules.ts

@@ -101,7 +101,7 @@ function tree(m: ModRow, sel: { t?: string; m?: string } = {}) {
 
 /** The page frame: tabs, the module's tree beside the content. */
 function frame(s: Session, m: ModRow, title: string, crumbs: [string, string?][], sel: { t?: string; m?: string }, body: Raw) {
-  const main = html`<h1 class="u-mb1">SQL Workshop</h1>${workshopTabs('rest')}${restNav('modules')}
+  const main = html`<h1 class="u-mb1">SQL Workshop</h1>${workshopTabs('rest', s)}${restNav('modules')}
     <h2 class="u-mb1 wrap-anywhere">${m.title} <span class="muted small">${m.app_name} · /a/${m.app_alias}/rest/${m.name}/${m.enabled ? '' : ' · disabled'}</span></h2>
     <div class="rm-layout">${region('Module', tree(m, sel))}<div class="rm-main">${body}</div></div>`;
   return shell(s, title, [['SQL Workshop', `${BASE}/sql`], ['RESTful Services', MODULES], ...crumbs], main, 'sql');
@@ -136,7 +136,7 @@ async function listPage(s: Session, b: Record<string, unknown> = {}, problems: s
     </div>
     <div class="field"><label class="label" for="f_description">Description</label><input id="f_description" name="description" value="${v('description')}"></div>
     <div class="buttons"><button class="btn btn-hot"${apps.length ? '' : raw(' disabled')}>${icon('plus')} Create module</button></div></form>`;
-  const main = html`<h1 class="u-mb1">SQL Workshop</h1>${workshopTabs('rest')}${restNav('modules')}
+  const main = html`<h1 class="u-mb1">SQL Workshop</h1>${workshopTabs('rest', s)}${restNav('modules')}
     <p class="muted">RESTful Services modules: a module is a base path of an application, its templates are URIs with <code>:parameters</code>, and each template has handlers per method with their source: a collection query, a single row, SQL, a PL/pgSQL block or a media resource. Handlers run as the application's database role with the caller as <code>meta.app_user()</code>, so its grants and row level security apply; parameters are bound, never pasted into the SQL. Every module has an OpenAPI document. Modules belong to their application: they travel with its export (also in Shared Components › RESTful Services).</p>
     ${region('Modules', table)}${region('Create a module', form)}`;
   return shell(s, 'RESTful Services: Modules', [['SQL Workshop', `${BASE}/sql`], ['RESTful Services', `${BASE}/sql/rest`], ['Modules']], main, 'sql');