pgkiln 0.41.0 → 0.43.0

package/src/builder/appwizard.ts

@@ -5,11 +5,17 @@ import { html, raw, type Raw } from '../html.ts';
 import { icon } from '../icons.ts';
 import { LoadError } from '../dataload.ts';
 import type { Session } from '../session.ts';
-import { aliasFor, check, createdHtml, ITEM, type Created } from './appfromfile.ts';
+import { aliasFor, check, ITEM, type Created } from './appfromfile.ts';
 import { addDashboard, parseBook } from './appsheets.ts';
-import { checkNewApp, createApp, createAppError, reservedSchema, type CheckedApp } from './newapp.ts';
+import { finishGeneratedApp, checkNewApp, createApp, createAppError, featuresFrom, FEATURES, reservedSchema, startFromBoilerplate, DEFAULT_APP_ICON, type CheckedApp, type Features } from './newapp.ts';
 import { currentWorkspace } from './workspaces.ts';
-import { BASE, csrf, developer, input, region, select, send, shell, type Body, type Req } from './ui.ts';
+import { back, BASE, csrf, developer, flash, input, region, select, send, shell, type Body, type Req } from './ui.ts';
+import { iconPicker } from './forms.ts';
+import { inWorkspaceSql } from './workspaces.ts';
+import { BASE_STYLES } from '../runtime/styles.ts';
+import { LANGUAGE_NAMES } from '../i18n.ts';
+import { secretKeyConfigured } from '../secrets.ts';
+import { appPublicKey } from '../push.ts';
 
 // Two more ways into the create application wizard:
 // - From pasted data (APEX: Create App from a File → Copy and Paste): CSV or
@@ -38,6 +44,10 @@ interface Relation {
   pk: string | null;
   /** the planner's estimate (null: never analyzed) */
   rows: string | null;
+  /** (sprint 73) a date or timestamp column for a calendar */
+  calendar: boolean;
+  /** (sprint 73) a table with a foreign key to this one, for master-detail */
+  detail: boolean;
 }
 
 /** The tables, partitioned tables, views and materialized views of a schema (not partitions). */
@@ -45,7 +55,9 @@ export async function schemaRelations(schema: string): Promise<Relation[]> {
   return (
     await owner.query<Relation>(
       `select c.relname, case when c.relkind in ('v', 'm') then 'view' else 'table' end as kind,
-              meta.wizard_pk(c.oid) as pk, case when c.reltuples >= 0 then c.reltuples::bigint end as rows
+              meta.wizard_pk(c.oid) as pk, case when c.reltuples >= 0 then c.reltuples::bigint end as rows,
+              meta.wizard_defaults('calendar', c.oid) ->> 'start' is not null as calendar,
+              meta.wizard_pk(c.oid) is not null and meta.wizard_defaults('master_detail', c.oid) ->> 'detail' is not null as detail
          from pg_class c join pg_namespace n on n.oid = c.relnamespace
         where n.nspname = $1 and c.relkind in ('r', 'p', 'v', 'm') and not c.relispartition
         order by c.relkind in ('v', 'm'), c.relname`,
@@ -60,10 +72,40 @@ const appSchemas = async () =>
     (r) => r.nspname,
   );
 
-/** Create the application on existing tables and views, in one transaction. */
-export async function buildAppFromTables(checked: CheckedApp, relations: Relation[], chart: boolean): Promise<Created> {
-  if (!relations.length) throw new LoadError('Choose at least one table or view.');
-  if (relations.length > MAX_TABLES) throw new LoadError(`Choose at most ${MAX_TABLES} tables and views.`);
+/** (sprint 73) The page types of the Create Application wizard (APEX: Add Page), per table. */
+export const PAGE_KINDS: Record<string, string> = {
+  report_form: 'Interactive report with form',
+  facets: 'Faceted search',
+  cards: 'Cards',
+  calendar: 'Calendar',
+  master_detail: 'Master detail',
+  grid: 'Interactive grid',
+  report: 'Report',
+  '': 'No page',
+};
+/** More rows than this: an interactive grid (paged) instead of a report and form by default. */
+export const LARGE_TABLE = 100_000;
+
+/** The page types a table or view can have. */
+export function kindsFor(r: Relation): string[] {
+  const keyed = r.kind === 'table' && !!r.pk;
+  return Object.keys(PAGE_KINDS).filter((k) =>
+    k === 'report_form' || k === 'grid' ? keyed : k === 'master_detail' ? keyed && r.detail : k === 'calendar' ? r.calendar : true,
+  );
+}
+/** The proposed page type: a report and form; a grid for a large table; a report for a view or a table without a single-column key. */
+export const defaultKind = (r: Relation) => (r.kind === 'table' && r.pk ? (Number(r.rows ?? 0) > LARGE_TABLE ? 'grid' : 'report_form') : 'report');
+
+export interface Plan {
+  rel: Relation;
+  kind: string;
+}
+
+/** Create the application on existing tables and views (each with its page type) and the features, in one transaction. */
+export async function buildAppFromTables(checked: CheckedApp, plans: Plan[], chart: boolean, features: Partial<Features> = {}): Promise<Created> {
+  plans = plans.filter((p) => p.kind);
+  if (plans.length > MAX_TABLES) throw new LoadError(`Choose at most ${MAX_TABLES} tables and views.`);
+  for (const p of plans) if (!kindsFor(p.rel).includes(p.kind)) throw new LoadError(`${p.rel.relname} can't have the page type ${PAGE_KINDS[p.kind] ?? p.kind}.`);
   return owner.tx(async (c) => {
     const app = await createApp(c, checked).catch((e) => {
       throw new LoadError(createAppError(e, checked.alias));
@@ -72,33 +114,48 @@ export async function buildAppFromTables(checked: CheckedApp, relations: Relatio
     const notes: string[] = [];
     const tables: string[] = [];
     let next = 2;
-    for (const r of relations) {
+    const generate = (kind: string, T: string, page: number, options: Record<string, unknown>) =>
+      c.query('select meta.generate_page($1, $2, $3::regclass, $4, $5::jsonb)', [checked.alias, kind, T, page, JSON.stringify(options)]);
+    for (const { rel: r, kind } of plans) {
       const T = `${pg.escapeIdentifier(checked.schema)}.${pg.escapeIdentifier(r.relname)}`;
       tables.push(T);
-      const label = (await c.query('select meta.wizard_label($1) as l', [r.relname])).rows[0].l as string;
-      if (r.kind === 'table' && r.pk) {
-        await c.query('select meta.generate_page($1, $2, $3::regclass, $4, $5::jsonb)', [checked.alias, 'report_form', T, next, JSON.stringify({ form_page: next + 1, label })]);
-        pages.push({ page: next, label }, { page: next + 1, label: `${label} form` });
+      // (097) Employees for the report and the menu, Employee for the form
+      const { plural, singular } = (await c.query('select meta.wizard_table_label($1::regclass) as plural, meta.wizard_table_label($1::regclass, false) as singular', [T])).rows[0];
+      const withForm = !!r.pk && r.kind === 'table';
+      if (kind === 'report_form' || (withForm && ['facets', 'cards', 'calendar'].includes(kind))) {
+        await generate(kind, T, next, { form_page: next + 1 });
+        pages.push({ page: next, label: `${plural} (${PAGE_KINDS[kind].toLowerCase()})` }, { page: next + 1, label: `${singular} form` });
         next += 2;
+      } else if (kind !== 'report') {
+        await generate(kind, T, next, {});
+        pages.push({ page: next, label: `${plural} (${PAGE_KINDS[kind].toLowerCase()})` });
+        next += 1;
       } else {
         // a report of the rows (no form: a view, or no single-column primary key)
-        const page = (await c.query(`select meta.wizard_new_page(a, $2, $3, a.home_page) as id from meta.app a where a.alias = $1`, [checked.alias, next, label])).rows[0].id;
+        const page = (await c.query(`select meta.wizard_new_page(a, $2, $3, a.home_page) as id from meta.app a where a.alias = $1`, [checked.alias, next, plural])).rows[0].id;
         await c.query(
-          `insert into meta.region (page_id, seq, title, type, source)
-           select $1, 10, $2, 'report', format(E'select %s\\n  from %s', string_agg(quote_ident(column_name), ', ' order by ordinal), meta.wizard_qname($3::regclass))
-             from meta.wizard_catalog($3::regclass) where kind <> 'binary'`,
-          [page, label, T],
+          `insert into meta.region (page_id, seq, title, type, source, config)
+           select $1, 10, $2, 'report', w ->> 'source',
+                  jsonb_build_object('headings', w -> 'headings')
+                  || case when jsonb_array_length(w -> 'hidden') > 0 then jsonb_build_object('hidden', w -> 'hidden') else '{}' end
+                  || case when w -> 'formats' <> '{}' then jsonb_build_object('formats', w -> 'formats') else '{}' end
+             from meta.wizard_report($3::regclass) w`,
+          [page, plural, T],
         );
-        await c.query(`select meta.wizard_nav(a, $2, 'table', $3) from meta.app a where a.alias = $1`, [checked.alias, label, next]);
-        pages.push({ page: next, label: `${label} (report)` });
+        await c.query(`select meta.wizard_nav(a, $2, 'table', $3) from meta.app a where a.alias = $1`, [checked.alias, plural, next]);
+        pages.push({ page: next, label: `${plural} (report)` });
         next += 1;
       }
     }
-    if (chart) {
-      const dash = await addDashboard(c, checked.alias, tables, next);
+    if (chart && tables.length) {
+      const skipped: string[] = [];
+      const dash = await addDashboard(c, checked.alias, tables, next, skipped);
       if (dash) pages.push(dash);
       else notes.push('No dashboard: no table has a foreign key, or a text, yes/no or date column whose statistics show a few values that repeat (ANALYZE the tables first).');
+      if (skipped.length)
+        notes.push(`Not on the dashboard: ${skipped.map((t) => t.replace(/^.*\./, '').replace(/"/g, '')).join(', ')} (row level security: the application's role may see none of the rows).`);
     }
+    await finishGeneratedApp(c, app.id, { description: checked.description, features, notes });
     return { app: { id: app.id, alias: checked.alias, existingAccount: app.existingAccount }, pages, notes };
   });
 }
@@ -159,75 +216,163 @@ export async function appWizardRoutes(app: FastifyInstance) {
     return reply.redirect(`${BASE}/create/file/${r!.id}?h=${headers ? '1' : '0'}`, 303);
   });
 
-  // ---------------------------------------------------------------- existing tables
-  const tablesForm = async (s: Session, schema: string, b: Body | null, message: Raw | '' = '') => {
-    const schemas = await appSchemas();
-    const known = schemas.includes(schema);
-    const relations = known ? await schemaRelations(schema) : [];
-    const v = (k: string, d: string) => (b ? String(b[k] ?? '') : d);
-    const chosen = (r: Relation, i: number) => (b ? b[`t_${i}`] === r.relname : r.kind === 'table');
-    return html`<h1>Create an application from existing tables</h1>
-      <p class="muted">Pick the tables and views of a schema. The application gets the schema as its parsing schema and a database role app_&lt;alias&gt; with access to the schema's tables; each table gets an interactive report with a modal form (a view, or a table without a single-column primary key, gets a report), and a navigation entry.</p>
-      ${message}
-      ${region('Schema', html`<form method="get" action="${BASE}/create/tables">
-        <div class="form-grid">${select('schema', 'Schema', schema, [['', '- choose a schema -'], ...schemas.map((x): [string, string] => [x, x])])}</div>
-        <div class="buttons"><button class="btn">${icon('search')} Show its tables</button></div></form>`)}
-      ${known
-        ? html`<div class="u-spacer"></div><form method="post" action="${BASE}/create/tables">${csrf(s)}<input type="hidden" name="schema" value="${schema}">
-          ${region(`Tables and views of ${schema}`, relations.length
-            ? html`<ul class="aw-tables">${relations.map(
-                (r, i) => html`<li><label class="check"><input type="checkbox" name="t_${i}" value="${r.relname}"${chosen(r, i) ? raw(' checked') : ''}> ${r.relname}</label>
-                  <small class="muted">${r.kind === 'view' ? 'view: a report' : `${r.rows === null ? '' : `about ${r.rows} row(s), `}${r.pk ? 'a report and form' : 'no single-column primary key: a report'}`}</small></li>`,
-              )}</ul>`
-            : html`<p class="muted">This schema has no tables or views.</p>`)}
-          <div class="u-spacer"></div>
-          ${region('Application', html`<div class="form-grid">
-            ${input('name', 'Name', v('name', schema.replace(/_/g, ' ').replace(/^./, (x) => x.toUpperCase())), { required: true })}
-            ${input('alias', 'Alias (URL)', v('alias', await aliasFor(schema)), { required: true, help: 'lowercase, e.g. inventory → /a/inventory' })}
-            ${select('authentication', 'Authentication', v('authentication', 'app_users'), [['app_users', 'App users (login page)'], ['none', 'None (public)']])}
-            ${input('admin_user', 'First user', v('admin_user', ''), { placeholder: 'e.g. your name', help: 'Gets the admin role. An existing account in Users is reused.' })}
-            ${input('admin_password', 'Password', '', { type: 'password', auto: 'new-password', help: 'For a new account; at least 8 characters.' })}
-          </div>`)}
-          <div class="u-spacer"></div>
-          ${region('Pages', html`${check('chart', 'Dashboard: a chart per table with the number of rows per parent row (a foreign key) or per value of a column whose values repeat', b ? b.chart === 'true' : true)}`)}
-          <div class="buttons"><a class="btn" href="${BASE}/create">Cancel</a><button class="btn btn-hot">Create application</button></div>
-        </form>`
-        : schema
-          ? html`<div class="alert alert-error" role="alert">Choose one of the schemas in the list.</div>`
-          : ''}`;
-  };
+  // ---------------------------------------------------------------- the Create Application wizard
+  // (sprint 73) One page like APEX's: name, icon and description; appearance; the pages (with a schema:
+  // a page type per table and view); features; settings; a boilerplate under Advanced. Choosing a schema
+  // reloads the page with its tables (a GET form of its own, so nothing typed is sent in a URL).
+  app.get(`${BASE}/create`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const schema = typeof req.query.schema === 'string' ? req.query.schema : '';
+    return createPage(s, reply, schema, null);
+  });
 
+  // the earlier address of "From existing tables"
   app.get(`${BASE}/create/tables`, async (req: Req, reply) => {
     const s = await developer(req, reply);
     if (!s) return;
     const schema = typeof req.query.schema === 'string' ? req.query.schema : '';
-    return page(s, reply, 'Create application from existing tables', 'Existing tables', await tablesForm(s, schema, null));
+    return createPage(s, reply, schema, null);
   });
 
-  app.post(`${BASE}/create/tables`, async (req: Req, reply) => {
+  const create = async (req: Req, reply: FastifyReply, fromTables = false) => {
     const s = await developer(req, reply);
     if (!s) return;
     const b = req.body ?? {};
     const schema = String(b.schema ?? '');
     const failed = async (message: string) => {
       reply.code(422);
-      return page(s, reply, 'Create application from existing tables', 'Existing tables',
-        await tablesForm(s, schema, b, html`<div class="alert alert-error" role="alert">${message}</div>`));
+      return createPage(s, reply, schema, b, html`<div class="alert alert-error" role="alert">${message}</div>`);
     };
     let built: Created;
+    let pushKey = false;
     try {
-      if (!schema || reservedSchema(schema) || !(await appSchemas()).includes(schema)) throw new LoadError('Choose one of the schemas in the list.');
+      if (schema && (reservedSchema(schema) || !(await appSchemas()).includes(schema))) throw new LoadError('Choose one of the schemas in the list.');
       const checked = await checkNewApp({ ...b, schema }, currentWorkspace(s)).catch((e) => {
         throw new LoadError((e as Error).message);
       });
-      // only names of this schema's tables and views count (looked up again, never used as SQL)
-      const relations = await schemaRelations(schema);
-      const picked = new Set(Object.entries(b).filter(([k]) => /^t_\d+$/.test(k)).map(([, x]) => String(x)));
-      built = await buildAppFromTables(checked, relations.filter((r) => picked.has(r.relname)), b.chart === 'true');
+      const features = featuresFrom(b, b.features === '1');
+      const boilerplate = /^\d{1,9}$/.test(b.boilerplate ?? '') ? Number(b.boilerplate) : null;
+      if (boilerplate && !(await boilerplates(s)).some((x) => x.id === boilerplate)) throw new LoadError('Choose a boilerplate application (an application of type Boilerplate).');
+      // the tables of the form: only names of this schema's tables and views count (looked up again, never used as SQL)
+      const relations = schema ? await schemaRelations(schema) : [];
+      const plans: Plan[] = [];
+      for (const [k, v] of Object.entries(b)) {
+        const m = /^t_(\d+)$/.exec(k);
+        const rel = m && relations.find((r) => r.relname === String(v));
+        if (!rel) continue;
+        // a page type per table; a ticked table of the earlier form gets the proposed one
+        const kind = b[`k_${m![1]}`] === undefined ? defaultKind(rel) : String(b[`k_${m![1]}`]);
+        if (kind) plans.push({ rel, kind });
+      }
+      const askedTables = fromTables || b.tables === '1' || Object.keys(b).some((k) => /^t_\d+$/.test(k));
+      if (askedTables && !plans.length) throw new LoadError('Choose at least one table or view.');
+      if (plans.length && boilerplate) throw new LoadError('A boilerplate application brings its own pages: choose no tables, or no boilerplate.');
+      if (plans.length) built = await buildAppFromTables(checked, plans, b.chart === 'true', features);
+      else {
+        built = await owner.tx(async (c) => {
+          const made = await createApp(c, checked).catch((e) => {
+            throw new LoadError(createAppError(e, checked.alias));
+          });
+          const notes: string[] = [];
+          if (boilerplate) await startFromBoilerplate(c, made.id, checked, boilerplate);
+          else await finishGeneratedApp(c, made.id, { description: checked.description, features, notes });
+          return { app: { id: made.id, alias: checked.alias, existingAccount: made.existingAccount }, pages: [], notes };
+        });
+      }
+      pushKey = features.push;
     } catch (e) {
       if (e instanceof LoadError || (e as { code?: string }).code) return failed((e as Error).message);
       throw e;
     }
-    return page(s, reply, 'Create application from existing tables', 'Existing tables', createdHtml(built, String(b.admin_user ?? '').trim(), `${BASE}/create/tables`));
-  });
+    // the push key of the new application, after the commit
+    if (pushKey && secretKeyConfigured()) await appPublicKey(built.app.id).catch(() => undefined);
+    // (sprint 73, APEX: straight to the new application's home) the result as a message on its page
+    const pages = built.pages.length ? ` with ${built.pages.length} page(s) besides Home` : '';
+    const account = built.app.existingAccount ? ` The existing account ${String(b.admin_user ?? '').trim()} got the admin role (its password was not changed).` : '';
+    flash(s, `Application ${built.app.alias} created${pages}.${account}${built.notes.length ? ` ${built.notes.join(' ')}` : ''}`);
+    return back(reply, s, `${BASE}/apps/${built.app.id}`);
+  };
+  app.post(`${BASE}/apps`, (req: Req, reply) => create(req, reply));
+  app.post(`${BASE}/create/tables`, (req: Req, reply) => create(req, reply, true));
+}
+
+/** The workspace's boilerplate applications (Advanced → Start from). */
+const boilerplates = async (s: Session) =>
+  (await owner.query<{ id: number; name: string }>(`select id, name from meta.app a where app_type = 'boilerplate' and ${inWorkspaceSql('a', 1)} order by lower(name), id`, [currentWorkspace(s)])).rows;
+
+/** Other ways to start (APEX: the Create Application wizard's sources). */
+const SOURCES: [string, string, string, string][] = [
+  ['create/file', 'upload', 'From a file', 'CSV, Excel, JSON or XML: a table per sheet with its rows'],
+  ['create/paste', 'file', 'From pasted data', 'Rows copied from a spreadsheet, or CSV text'],
+  ['blueprints', 'layers', 'From a blueprint', 'Tables, pages, menu and sample rows described once (or drafted by AI)'],
+  ['gallery', 'grid', 'From the App Gallery', 'A starter application'],
+];
+
+async function createPage(s: Session, reply: FastifyReply, schema: string, b: Body | null, message: Raw | '' = '') {
+  const schemas = await appSchemas();
+  const known = schemas.includes(schema);
+  const relations = known ? await schemaRelations(schema) : [];
+  const bp = await boilerplates(s);
+  const v = (k: string, d: string) => (b ? String(b[k] ?? '') : d);
+  const features = featuresFrom(b ?? {}, !!b && b.features === '1');
+  // (sprint 73) the name proposed from the schema is selected on first focus, so typing replaces it (app.js data-select-once)
+  const suggested = known ? schema.replace(/_/g, ' ').replace(/^./, (x) => x.toUpperCase()) : '';
+  const kindOf = (r: Relation, i: number) => (b ? (b[`t_${i}`] === r.relname ? (b[`k_${i}`] === undefined ? defaultKind(r) : String(b[`k_${i}`])) : '') : defaultKind(r));
+  const rows = (r: Relation) => (r.rows === null ? 'not analyzed' : `about ${Number(r.rows).toLocaleString('en')} row(s)`);
+  const main = html`<div class="ab-narrow create-app">
+    <h1>Create an application</h1>
+    <nav class="create-sources" aria-label="Other ways to start">${SOURCES.map(
+      ([path, ic, label, help]) => html`<a class="create-source" href="${BASE}/${path}">${icon(ic)}<span><b>${label}</b><small class="muted">${help}</small></span></a>`,
+    )}</nav>
+    ${message}
+    ${schema && !known && !message ? html`<div class="alert alert-error" role="alert">Choose one of the schemas in the list.</div>` : ''}
+    ${region('Data', html`<form method="get" action="${BASE}/create" class="create-schema">
+      <div class="form-grid">${select('schema', 'Pages on the tables of', schema, [['', '- a new, empty schema (Home only) -'], ...schemas.map((x): [string, string] => [x, x])],
+        'The application\'s parsing schema. Choose a schema to get a page per table and view; a new schema is named after the alias.')}</div>
+      <div class="buttons"><button class="btn">${icon('search')} Show its tables</button></div></form>`)}
+    <form method="post" action="${BASE}/apps" data-progress="Creating the application and its pages…">${csrf(s)}
+      <input type="hidden" name="schema" value="${known ? schema : ''}"><input type="hidden" name="features" value="1">
+      ${known ? html`<input type="hidden" name="tables" value="1">` : ''}
+      ${region('Application', html`<div class="form-grid">
+        <div class="field"><label class="label" for="f_name">Name</label>
+          <input id="f_name" name="name" value="${v('name', suggested)}" required data-select-once></div>
+        ${input('description', 'Description', v('description', ''), { placeholder: 'One line for the home and About pages' })}
+        ${iconPicker('f_icon', 'icon', 'Icon', v('icon', DEFAULT_APP_ICON))}
+      </div>`)}
+      ${region('Appearance', html`<div class="form-grid">
+        ${select('base', 'Theme style', v('base', 'iris'), [['iris', 'Iris (light body, dark header and menu)'], ['lavender', 'Lavender (rounded, indigo)'], ['standard', 'Standard (blue, navy header)']])}
+        ${select('nav', 'Navigation', v('nav', 'side'), [['side', 'Side menu'], ['top', 'Top menu']])}
+        ${input('accent', 'Accent colour', v('accent', BASE_STYLES.iris.accent), { type: 'color', help: 'Of the theme style; the default stores nothing.' })}
+      </div>`)}
+      ${region('Pages', html`<ul class="aw-pages">
+        <li><span class="aw-page-kind">${icon('home')} Home</span><span class="muted">a hero with the name and icon, and a card per page</span></li>
+        ${known
+          ? relations.length
+            ? relations.map((r, i) => html`<li><input type="hidden" name="t_${i}" value="${r.relname}">
+                <label class="aw-page-kind" for="f_k_${i}">${icon(r.kind === 'view' ? 'eye' : 'table')} ${r.relname}</label>
+                <select id="f_k_${i}" name="k_${i}">${kindsFor(r).map((k) => html`<option value="${k}"${k === kindOf(r, i) ? raw(' selected') : ''}>${PAGE_KINDS[k]}</option>`)}</select>
+                <small class="muted">${r.kind === 'view' ? 'view' : rows(r)}${r.kind === 'table' && !r.pk ? ', no single-column key: no form' : ''}${Number(r.rows ?? 0) > LARGE_TABLE ? ': a paged grid' : ''}</small></li>`)
+            : html`<li class="muted">${schema} has no tables or views.</li>`
+          : html`<li class="muted">Choose a schema under Data for a page per table, or add pages with the page wizards later.</li>`}
+      </ul>
+      ${known ? check('chart', 'Dashboard: a chart per table with the number of rows per parent row (a foreign key) or per value of a column whose values repeat', b ? b.chart === 'true' : true) : ''}`)}
+      ${region('Features', html`<div class="aw-features">${FEATURES.map(([k, label, help]) => check(`f_${k}`, label, features[k], help))}</div>`)}
+      ${region('Settings', html`<div class="form-grid">
+        ${input('alias', 'Alias (URL)', v('alias', known ? await aliasFor(schema) : ''), { required: true, help: 'lowercase, e.g. inventory → /a/inventory' })}
+        ${select('authentication', 'Authentication', v('authentication', 'app_users'), [['app_users', 'App users (login page)'], ['none', 'None (public)']])}
+        ${input('admin_user', 'First user', v('admin_user', ''), { placeholder: 'e.g. your name', help: 'Gets the admin role. An existing account in Users is reused.' })}
+        ${input('admin_password', 'Password', '', { type: 'password', auto: 'new-password', help: 'For a new account; at least 8 characters.' })}
+        ${select('language', 'Language', v('language', 'en'), Object.entries(LANGUAGE_NAMES).map(([code, name]): [string, string] => [code, `${name} (${code})`]))}
+      </div>`)}
+      ${!known && bp.length
+        ? html`<details class="region region-standard aw-advanced"><summary class="region-header"><h2>Advanced</h2></summary><div class="region-body"><div class="form-grid">
+            ${select('boilerplate', 'Start from', v('boilerplate', ''), [['', '- a blank application -'], ...bp.map((x): [string, string] => [String(x.id), `${x.name} (boilerplate)`])],
+              'A boilerplate application\'s pages, shared components and settings are copied; the new application keeps its own name, alias, role and authentication.')}
+          </div></div></details>`
+        : ''}
+      <div class="buttons"><a class="btn" href="${BASE}">Cancel</a><button class="btn btn-hot">Create application</button></div>
+    </form>
+  </div>`;
+  return send(reply, s, shell(s, 'Create application', [['App Builder', BASE], ['Create']], main));
 }

package/src/builder/arrange.ts

@@ -22,6 +22,19 @@ const options = (kind: string, field: string) => COMPONENTS[kind].fields.find((f
 export const REGION_TYPES = () => options('region', 'type');
 export const ITEM_TYPES = () => options('item', 'type');
 export const BUTTON_ACTIONS = () => options('button', 'action');
+/** (099) display positions of regions and button positions (slots) of region buttons; body and region are the defaults (null) */
+export const POSITIONS = () => options('region', 'position');
+export const SLOTS = () => options('button', 'slot');
+export const POSITION_LABELS: Record<string, string> = {
+  banner: 'Banner', breadcrumb: 'Breadcrumb bar', left: 'Left column', body: 'Body', right: 'Right column', footer: 'Footer',
+};
+export const SLOT_LABELS: Record<string, string> = {
+  region: 'Region buttons', create: 'Create', edit: 'Edit', change: 'Change', copy: 'Copy', help: 'Help', up: 'Up',
+  previous: 'Previous', close: 'Close', delete: 'Delete', next: 'Next',
+};
+/** The button positions in a region's header and in its bottom bar (previous, close, delete at the left; next at the right). */
+export const TOP_SLOTS = ['create', 'edit', 'change', 'copy', 'help', 'up'];
+export const BOTTOM_SLOTS = ['previous', 'close', 'delete', 'next'];
 
 /** Gallery names and icons. */
 export const REGION_LABELS: Record<string, [string, string]> = {
@@ -58,9 +71,10 @@ const NEW_REGION_SOURCE: Record<string, string | null> = {
 // ---------------------------------------------------------------- snapshots (undo / redo)
 
 interface Snap {
-  region: { id: number; seq: number; columns: number }[];
+  // position and slot (099) are missing from snapshots taken before them: those leave them as they are
+  region: { id: number; seq: number; columns: number; position?: string | null }[];
   item: { id: number; seq: number; region_id: number | null }[];
-  button: { id: number; seq: number; region_id: number | null }[];
+  button: { id: number; seq: number; region_id: number | null; slot?: string | null }[];
 }
 interface History {
   pid: number;
@@ -74,19 +88,22 @@ type Q = { query: (sql: string, params?: unknown[]) => Promise<{ rows: any[]; ro
 
 async function snapshot(c: Q, pid: number): Promise<Snap> {
   // one after the other: a transaction's client runs one query at a time
-  const region = await c.query('select id, seq, columns from meta.region where page_id = $1 order by id', [pid]);
+  const region = await c.query('select id, seq, columns, position from meta.region where page_id = $1 order by id', [pid]);
   const item = await c.query('select id, seq, region_id from meta.item where page_id = $1 order by id', [pid]);
-  const button = await c.query('select id, seq, region_id from meta.button where page_id = $1 order by id', [pid]);
+  const button = await c.query('select id, seq, region_id, slot from meta.button where page_id = $1 order by id', [pid]);
   return { region: region.rows, item: item.rows, button: button.rows };
 }
 
 /** Puts the layout of a snapshot back; components deleted since are skipped, regions that are gone become "no region". */
 async function restore(c: Q, pid: number, snap: Snap) {
   const regions = new Set((await c.query('select id from meta.region where page_id = $1', [pid])).rows.map((r) => r.id));
-  for (const r of snap.region) await c.query('update meta.region set seq = $3, columns = $4 where id = $1 and page_id = $2', [r.id, pid, r.seq, r.columns]);
-  for (const kind of ['item', 'button'] as const)
-    for (const r of snap[kind])
-      await c.query(`update ${COMPONENTS[kind].table} set seq = $3, region_id = $4 where id = $1 and page_id = $2`, [r.id, pid, r.seq, r.region_id !== null && regions.has(r.region_id) ? r.region_id : null]);
+  for (const r of snap.region)
+    await c.query('update meta.region set seq = $3, columns = $4, position = case when $5 then $6 else position end where id = $1 and page_id = $2', [r.id, pid, r.seq, r.columns, 'position' in r, r.position ?? null]);
+  for (const r of snap.item)
+    await c.query('update meta.item set seq = $3, region_id = $4 where id = $1 and page_id = $2', [r.id, pid, r.seq, r.region_id !== null && regions.has(r.region_id) ? r.region_id : null]);
+  for (const r of snap.button)
+    await c.query('update meta.button set seq = $3, region_id = $4, slot = case when $5 then $6 else slot end where id = $1 and page_id = $2',
+      [r.id, pid, r.seq, r.region_id !== null && regions.has(r.region_id) ? r.region_id : null, 'slot' in r, r.slot ?? null]);
 }
 
 function history(s: Session, pid: number): History {
@@ -128,17 +145,29 @@ async function targetRegion(c: Q, pid: number, value: string): Promise<number |
 /**
  * Moves a region, item or button. `dir` moves it one place up or down among
  * its neighbours; otherwise it goes before `before` (an id in the target
- * container, or '' for the end) in `region` (items and buttons; '' = page level).
+ * container, or '' for the end) in `region` (items and buttons; '' = page level),
+ * `position` (regions: a display position, '' = body) and `slot` (buttons: a
+ * button position, '' = with the region's other buttons).
  * Sequences in the target container are renumbered 10, 20, 30…
  */
-export async function moveComponent(c: Q, pid: number, kind: LayoutKind, id: number, o: { dir?: string; region?: string; before?: string }) {
+export async function moveComponent(c: Q, pid: number, kind: LayoutKind, id: number, o: { dir?: string; region?: string; before?: string; position?: string; slot?: string }) {
   const table = COMPONENTS[kind].table;
   const row = (await c.query(`select * from ${table} where id = $1 and page_id = $2`, [id, pid])).rows[0];
   if (!row) throw new LayoutError(404, `${COMPONENTS[kind].label} not found on this page.`);
   let region: number | null = kind === 'region' ? null : row.region_id;
   if (kind !== 'region' && o.region !== undefined && !o.dir) region = await targetRegion(c, pid, o.region);
-  const scope = kind === 'region' ? '' : ' and region_id is not distinct from $2';
-  const list: number[] = (await c.query(`select id from ${table} where page_id = $1${scope} order by seq, id`, kind === 'region' ? [pid] : [pid, region])).rows.map((r) => r.id);
+  // the container: a region's display position; a button's region and position in it (page-level buttons have none)
+  let place: string = kind === 'region' ? (row.position ?? 'body') : kind === 'button' && region !== null ? (row.slot ?? 'region') : '';
+  if (kind === 'region' && o.position !== undefined && !o.dir) place = o.position || 'body';
+  if (kind === 'button' && o.slot !== undefined && !o.dir) place = o.slot || 'region';
+  if (kind === 'button' && region === null) place = '';
+  if (kind === 'region' && !POSITIONS().includes(place)) throw new LayoutError(400, 'Unknown position.');
+  if (kind === 'button' && place && !SLOTS().includes(place)) throw new LayoutError(400, 'Unknown button position.');
+  const scope = kind === 'region' ? " and coalesce(position, 'body') = $2"
+    : kind === 'button' ? " and region_id is not distinct from $2 and (region_id is null or coalesce(slot, 'region') = $3)"
+    : ' and region_id is not distinct from $2';
+  const params = kind === 'region' ? [pid, place] : kind === 'button' ? [pid, region, place] : [pid, region];
+  const list: number[] = (await c.query(`select id from ${table} where page_id = $1${scope} order by seq, id`, params)).rows.map((r) => r.id);
   const others = list.filter((x) => x !== id);
   let at: number;
   if (o.dir === 'up' || o.dir === 'down') {
@@ -154,8 +183,10 @@ export async function moveComponent(c: Q, pid: number, kind: LayoutKind, id: num
     if (at < 0) throw new LayoutError(400, 'The place to move to is not in that region.');
   }
   others.splice(at, 0, id);
+  const stored = place === 'body' || place === 'region' || place === '' ? null : place;
   for (const [i, x] of others.entries()) {
-    if (kind === 'region') await c.query(`update ${table} set seq = $3 where id = $1 and page_id = $2`, [x, pid, (i + 1) * 10]);
+    if (kind === 'region') await c.query(`update ${table} set seq = $3, position = case when id = $4 then $5::text else position end where id = $1 and page_id = $2`, [x, pid, (i + 1) * 10, id, stored]);
+    else if (kind === 'button') await c.query(`update ${table} set seq = $3, region_id = case when id = $4 then $5::int else region_id end, slot = case when id = $4 then $6::text else slot end where id = $1 and page_id = $2`, [x, pid, (i + 1) * 10, id, region, stored]);
     else await c.query(`update ${table} set seq = $3, region_id = case when id = $4 then $5::int else region_id end where id = $1 and page_id = $2`, [x, pid, (i + 1) * 10, id, region]);
   }
 }
@@ -171,7 +202,7 @@ export async function spanRegion(c: Q, pid: number, id: number, o: { columns?: s
 }
 
 /** A new component from the gallery, with a working default; placed like moveComponent. Returns its id. */
-export async function createComponent(c: Q, pid: number, kind: LayoutKind, type: string, o: { region?: string; before?: string }) {
+export async function createComponent(c: Q, pid: number, kind: LayoutKind, type: string, o: { region?: string; before?: string; position?: string; slot?: string }) {
   const page = (await c.query('select page_no from meta.page where id = $1', [pid])).rows[0];
   if (!page) throw new LayoutError(404, 'Page not found.');
   let id: number;
@@ -196,10 +227,62 @@ export async function createComponent(c: Q, pid: number, kind: LayoutKind, type:
       id = (await c.query(`insert into meta.button (page_id, region_id, seq, name, label, action) values ($1, $2, 999999, $3, 'New button', $4) returning id`, [pid, region, name, type])).rows[0].id;
     }
   }
-  await moveComponent(c, pid, kind, id, { region: o.region ?? '', before: o.before ?? '' });
+  await moveComponent(c, pid, kind, id, { region: o.region ?? '', before: o.before ?? '', position: o.position ?? '', slot: o.slot ?? '' });
   return id;
 }
 
+/** A copy of a row of a page component table with some columns changed; returns its id. */
+async function copyRow(c: Q, kind: LayoutKind, id: number, over: Record<string, unknown>): Promise<number> {
+  const table = COMPONENTS[kind].table;
+  return (await c.query(
+    `insert into ${table} select (jsonb_populate_record(null::${table}, to_jsonb(x) || jsonb_build_object('id', nextval('${table}_id_seq')) || $2::jsonb)).* from ${table} x where id = $1 returning id`,
+    [id, JSON.stringify(over)],
+  )).rows[0].id;
+}
+
+/** NAME, or NAME_2, NAME_3… when the page has an item (or button) of that name already. */
+async function freeName(c: Q, kind: 'item' | 'button', pid: number, name: string) {
+  const taken = new Set((await c.query(`select name from ${COMPONENTS[kind].table} where page_id = $1`, [pid])).rows.map((r) => r.name));
+  let out = name;
+  for (let i = 2; taken.has(out); i++) out = `${name}_${i}`;
+  return out;
+}
+
+/**
+ * (sprint 77, APEX: Duplicate and Copy to other Page in the rendering tree's menu) A copy of a region (with its
+ * items and buttons), an item or a button: on the same page right after the original, or at the end of another
+ * page of the same application (items named P<n>_ get that page's number; components of a region go to page level
+ * there). Item and button names are made unique on the page. Returns the copy's id.
+ */
+export async function duplicateComponent(c: Q, pid: number, kind: LayoutKind, id: number, toPid: number = pid) {
+  const table = COMPONENTS[kind].table;
+  const row = (await c.query(`select * from ${table} where id = $1 and page_id = $2`, [id, pid])).rows[0];
+  if (!row) throw new LayoutError(404, `${COMPONENTS[kind].label} not found on this page.`);
+  const pages = (await c.query('select t.page_no from meta.page t join meta.page f on f.app_id = t.app_id where t.id = $1 and f.id = $2', [toPid, pid])).rows;
+  if (!pages.length) throw new LayoutError(400, 'That page is not in this application.');
+  const same = toPid === pid;
+  const rename = (name: string) => (same ? name : name.replace(/^P\d+_/, `P${pages[0].page_no}_`));
+  const copyChild = async (k: 'item' | 'button', x: any, regionId: number | null) =>
+    copyRow(c, k, x.id, { page_id: toPid, region_id: regionId, name: await freeName(c, k, toPid, rename(x.name)), ...(k === 'button' && regionId === null ? { slot: null } : {}) });
+  // where the copy goes: after the original in its container, or at the end of the other page
+  let place: { region?: string; position?: string; slot?: string; before: string } = { before: '' };
+  if (same) {
+    const scope = kind === 'region' ? " and coalesce(position, 'body') = coalesce($2, 'body')" : ' and region_id is not distinct from $2';
+    const list: number[] = (await c.query(`select id from ${table} where page_id = $1${scope} order by seq, id`, [pid, kind === 'region' ? row.position : row.region_id])).rows.map((r) => r.id);
+    const next = list[list.indexOf(id) + 1];
+    place = { region: String(row.region_id ?? ''), position: row.position ?? '', slot: row.slot ?? '', before: next ? String(next) : '' };
+  } else place = { region: '', position: row.position ?? '', slot: '', before: '' };
+  let copy: number;
+  if (kind === 'region') {
+    const staticId = row.static_id && !same && !(await c.query('select 1 from meta.region where page_id = $1 and static_id = $2', [toPid, row.static_id])).rowCount ? row.static_id : null;
+    copy = await copyRow(c, 'region', id, { page_id: toPid, static_id: staticId });
+    for (const k of ['item', 'button'] as const)
+      for (const x of (await c.query(`select id, name from ${COMPONENTS[k].table} where region_id = $1 order by seq, id`, [id])).rows) await copyChild(k, x, copy);
+  } else copy = await copyChild(kind, row, same ? row.region_id : null);
+  await moveComponent(c, toPid, kind, copy, place);
+  return copy;
+}
+
 // ---------------------------------------------------------------- routes
 
 const wantsJson = (req: Req) => String(req.headers.accept ?? '').includes('application/json');
@@ -245,7 +328,7 @@ export async function arrangeRoutes(app: FastifyInstance) {
     const kind = b.kind;
     const id = int(b.id);
     if (!isKind(kind) || id === null) throw new LayoutError(400, 'Unknown component.');
-    await recorded(s, pid, `Move ${await describe(kind, id)}`, (c) => moveComponent(c, pid, kind, id, { dir: b.dir, region: b.region, before: b.before }));
+    await recorded(s, pid, `Move ${await describe(kind, id)}`, (c) => moveComponent(c, pid, kind, id, { dir: b.dir, region: b.region, before: b.before, position: b.position, slot: b.slot }));
     return { sel: `${kind}-${id}`, message: `${COMPONENTS[kind].label} moved.` };
   });
 
@@ -262,11 +345,44 @@ export async function arrangeRoutes(app: FastifyInstance) {
   route('create', async (s, pid, b) => {
     const kind = b.kind;
     if (!isKind(kind)) throw new LayoutError(400, 'Unknown component type.');
-    const id = await owner.tx((c) => createComponent(c, pid, kind, b.type ?? '', { region: b.region, before: b.before }));
+    const id = await owner.tx((c) => createComponent(c, pid, kind, b.type ?? '', { region: b.region, before: b.before, position: b.position, slot: b.slot }));
     keep(s, { pid, undo: [], redo: [] }); // earlier layout steps no longer line up with the new component
     return { sel: `${kind}-${id}`, message: `${COMPONENTS[kind].label} created; set its properties on the right.` };
   });
 
+  // (sprint 77) the rendering tree's menu: Duplicate, Copy to other Page
+  route('duplicate', async (s, pid, b) => {
+    const kind = b.kind;
+    const id = int(b.id);
+    if (!isKind(kind) || id === null) throw new LayoutError(400, 'Unknown component.');
+    const copy = await owner.tx((c) => duplicateComponent(c, pid, kind, id));
+    keep(s, { pid, undo: [], redo: [] });
+    return { sel: `${kind}-${copy}`, message: `${COMPONENTS[kind].label} duplicated.` };
+  });
+
+  app.post(`${BASE}/pages/:pid/layout/copy`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const b = (req.body ?? {}) as Record<string, string | undefined>;
+    const pid = int(req.params.pid);
+    const to = int(b.page);
+    const kind = b.kind;
+    const id = int(b.id);
+    try {
+      if (pid === null || !(await owner.one('select 1 as ok from meta.page where id = $1', [pid]))) throw new LayoutError(404, 'Page not found');
+      if (!isKind(kind) || id === null || to === null) throw new LayoutError(400, 'Unknown component or page.');
+      const copy = await owner.tx((c) => duplicateComponent(c, pid, kind, id, to));
+      if (to === pid) keep(s, { pid, undo: [], redo: [] });
+      flash(s, `${COMPONENTS[kind].label} copied.`);
+      await saveState(s);
+      const location = `${BASE}/pages/${to}?c=${kind}-${copy}`;
+      return wantsJson(req) ? reply.send({ ok: true, location }) : reply.redirect(location, 303);
+    } catch (e) {
+      if (!(e instanceof LayoutError)) throw e;
+      return wantsJson(req) ? reply.code(e.status).send({ ok: false, error: e.message }) : reply.code(e.status).type('text/plain').send(e.message);
+    }
+  });
+
   for (const op of ['undo', 'redo'] as const)
     route(op, async (s, pid) => {
       const h = history(s, pid);