pgkiln 0.35.0 → 0.36.0

package/src/runtime/grid.ts

@@ -12,7 +12,8 @@ import { lovContains, lovOptions, type LovOption } from './items.ts';
 import { resolveRestRegion, restAllows, restGridCall, restWritable } from './rest-sources.ts';
 import { fillItems, linkAttrs } from './links.ts';
 import { detailsOf, masterColumnOf, masterItemOf, selectHref, selectRowOf } from './master-detail.ts';
-import { aggregateRows, AGGREGATES, buildSql, cell, columnFormats, headingOf, key, pageInfo, pagerNav, regionUrl, reportParams, reportState, visibleColumns, type ReportState } from './report.ts';
+import { aggregateRows, AGGREGATES, buildSql, cell, chartSection, columnFormats, groupBySection, headingOf, key, MAX_PAGE, pageInfo, pagerNav, regionUrl, reportParams, reportState, visibleColumns, type ReportState } from './report.ts';
+import { GRID_VIEWS, renderView, type View } from './report-views.ts';
 
 // Interactive grid: an editable report on one table (APEX's Interactive
 // Grid). The region's SELECT must include the table's primary key column.
@@ -27,7 +28,15 @@ import { aggregateRows, AGGREGATES, buildSql, cell, columnFormats, headingOf, ke
 //                            "delete": true, "links": [{"label": "Reviews", "page": 20, "items": {...}}]},
 //            "select_row": {"column": "deptno", "item": "P27_DEPTNO"},   (a master grid, see master-detail.ts)
 //            "master": {"item": "P27_DEPTNO", "column": "deptno"},      (a detail grid)
-//            "actions": true, "saved_reports": true, "public_reports": "ADMIN"}
+//            "actions": true, "saved_reports": true, "public_reports": "ADMIN",
+//            "views": ["row", "group", "chart"]}
+//
+// Views (APEX: Single Row View, Group By, Chart), ?r<id>_v=row|group|chart:
+// the single row view shows one row of the search as a form (r<id>_row=N, the
+// position from 1, or "new" for a new row) with the grid's own field names,
+// so the same grid_dml process saves it; group by and chart are the
+// interactive report's views (report-views.ts). config.views limits them
+// (left out: all three).
 //
 // Aggregates are computed in the database over every row of the search (not
 // only the page). The layout is the developer's default; each user arranges
@@ -145,20 +154,47 @@ function rowActionsOf(r: Region): { edit: RowLink | null; duplicate: boolean; de
   };
 }
 
+/** The views a user may switch to besides the grid itself (config.views; left out: all three). */
+export function gridViews(r: Region): View[] {
+  const listed = r.config.views;
+  const all = GRID_VIEWS.filter((v) => v !== 'report');
+  return Array.isArray(listed) ? all.filter((v) => listed.includes(v)) : all;
+}
+
 export async function renderGrid(ctx: PageContext, r: Region): Promise<Raw> {
   const c = ctx.client!;
   const t = ctx.locale.t;
   const tr = ctx.locale.tr;
   if (!(r.table_name || r.rest_source) || !r.pk_column) return html`<div class="alert alert-error">Grid regions need a table (or a REST data source with key columns) and a primary key column.</div>`;
   const base = reportState(ctx, r);
-  const st = { ...base, size: Math.max(1, Math.min(200, Number(r.config.page_size) || 25)), breakCol: null, view: 'report' as const };
+  const views = gridViews(r);
+  const view: View = views.includes(base.view) ? base.view : 'report';
+  const pageSize = Math.max(1, Math.min(200, Number(r.config.page_size) || 25));
+  // the single row view: one row of the search at a time (r<id>_row=N from 1), or a new row (r<id>_row=new)
+  const rowParam = ctx.params.get(key(r, 'row'));
+  const adding = view === 'row' && rowParam === 'new';
+  const rowNo = view === 'row' && !adding ? Math.max(1, Math.min(MAX_PAGE, parseInt(rowParam ?? '1', 10) || 1)) : 0;
+  const st = view === 'row'
+    ? { ...base, size: 1, page: rowNo || 1, breakCol: null, view: 'report' as const }
+    : { ...base, size: pageSize, breakCol: null, view: 'report' as const };
   const aggs = gridAggregates(r, st);
   let res: pg.QueryResult<any[]>;
   let writable: Set<string>;
   let agg: Awaited<ReturnType<typeof aggregateRows>> = null;
   try {
     writable = await writableColumns(c, r);
-    res = await savepoint(c, async () => c.query({ ...(await buildSql(ctx, r, st, 'page')), rowMode: 'array' }));
+    const query = async () => savepoint(c, async () => c.query({ ...(await buildSql(ctx, r, st, 'page')), rowMode: 'array' }));
+    res = await query();
+    // a position past the end (rows deleted, a narrower search): the last row
+    if (view === 'row' && !res.rows.length && st.page > 1) {
+      st.page = 1;
+      res = await query();
+      const total = Number(res.rows[0]?.[res.fields.findIndex((f) => f.name === '__total')]);
+      if (Number.isFinite(total) && total > 1) {
+        st.page = Math.min(total, MAX_PAGE);
+        res = await query();
+      }
+    }
   } catch (e) {
     return html`<div class="alert alert-error" role="alert">${await publicError(ctx, e, `grid "${r.title ?? r.id}"`)}</div>`;
   }
@@ -167,7 +203,7 @@ export async function renderGrid(ctx: PageContext, r: Region): Promise<Raw> {
   const info = pageInfo(r, st, res.rows, totalIdx);
   const pkIdx = fields.findIndex((f) => f.name === r.pk_column);
   if (pkIdx === -1) return html`<div class="alert alert-error">The grid query must select the primary key column ${r.pk_column}.</div>`;
-  if (aggs.length)
+  if (aggs.length && view === 'report')
     try {
       agg = await aggregateRows(ctx, r, { ...st, aggregates: aggs }, (col) => NUMERIC.has(fields.find((f) => f.name === col)?.dataTypeID ?? 0));
     } catch (e) {
@@ -248,6 +284,13 @@ export async function renderGrid(ctx: PageContext, r: Region): Promise<Raw> {
     : html`<th scope="col" class="${leadCls(k)}"><span class="sr-only">${t('grid.row_actions')}</span></th>`,
   );
 
+  // the single row view of a position in the search (from 1), or of a new row
+  const rowUrl = (n: number | 'new') => regionUrl(ctx, r, (p) => {
+    p.set(key(r, 'v'), 'row');
+    p.set(key(r, 'row'), String(n));
+    for (const k of ['p', 'k', 'dup']) p.delete(key(r, k));
+  });
+
   const rowItems = (row: unknown[], items: Record<string, string> | undefined) =>
     fillItems(items, (col) => {
       const i = fields.findIndex((f) => f.name.toLowerCase() === col.toLowerCase());
@@ -284,6 +327,7 @@ export async function renderGrid(ctx: PageContext, r: Region): Promise<Raw> {
           ${editLink ? html`<a ${linkAttrs(ctx, editLink.page, rowItems(row, editLink.items))}>${icon('edit')} ${editLink.label ? tr(editLink.label) : t('report.edit')}</a>` : ''}
           ${canDuplicate ? html`<a href="${regionUrl(ctx, r, (q) => q.set(key(r, 'dup'), pk))}" data-grid-dup="${i}" data-grid-leave>${icon('plus')} ${t('grid.duplicate')}</a>` : ''}
           ${canDelete ? html`<label for="${g}_${i}_del" data-grid-del>${icon('close')} ${t('grid.delete_toggle')}</label>` : ''}
+          ${views.includes('row') ? html`<a href="${rowUrl(info.from + i)}" data-grid-leave>${t('grid.view_row')}</a>` : ''}
           ${extraLinks.map((l) => html`<a ${linkAttrs(ctx, l.page, rowItems(row, l.items))}>${tr(l.label!)}</a>`)}
         </div></details></td>`;
     });
@@ -326,6 +370,62 @@ export async function renderGrid(ctx: PageContext, r: Region): Promise<Raw> {
     postedNew.push(newRow(nextNew++, values));
   }
 
+  // The single row view: one row as a form, with the grid's field names (row 0, or new row 0)
+  const field = (p: Placed<(typeof cols)[number]>, control: Raw | string, editable: boolean) => {
+    const lbl = html`${label(p.col.name)}${p.col.required && editable ? html`<span class="req" aria-hidden="true">*</span>` : ''}`;
+    return editable
+      ? html`<label class="field grid-field"${hiddenAttr(p)}><span class="label">${lbl}</span>${control}</label>`
+      : html`<div class="field grid-field"${hiddenAttr(p)}><span class="label">${lbl}</span><div class="grid-value">${control}</div></div>`;
+  };
+  const recordNav = () => {
+    const total = info.total;
+    const at = info.from;
+    const link = (n: number, text: string, rel = '') => html`<a class="btn" href="${rowUrl(n)}"${rel ? raw(` rel="${rel}"`) : ''} data-grid-leave>${text}</a>`;
+    return html`<nav class="pager grid-record-nav" aria-label="${t('report.pagination')}">
+      ${at > 1 || adding ? link(1, `« ${t('grid.first')}`) : ''}
+      ${at > 1 ? link(at - 1, `‹ ${t('report.previous')}`, 'prev') : ''}
+      <span>${adding ? t('grid.new_row') : total !== null ? t('grid.row_of', { row: at, total }) : t('grid.row', { row: at })}</span>
+      ${!adding && info.more ? link(at + 1, `${t('report.next')} ›`, 'next') : ''}
+      ${total !== null && total > 0 && (adding || at < total) ? link(total, `${t('grid.last')} »`) : ''}
+    </nav>`;
+  };
+  const record = (row: unknown[]) => {
+    const pk = toState(row[pkIdx]) ?? '';
+    const pi = postedByPk.get(pk);
+    const orig: Record<string, string> = {};
+    const fieldsHtml = placed.map((p) => {
+      const col = p.col;
+      const dbValue = toState(row[col.idx]) ?? '';
+      orig[col.ci] = dbValue;
+      if (!col.editable) return field(p, cell(row[col.idx], col.typeOid, fmtOf(col.name)), false);
+      const value = pi !== undefined ? (col.typeOid === 16 ? (pv(`${g}_${pi}_c${col.ci}`) === 'true' ? 'true' : 'false') : (pv(`${g}_${pi}_c${col.ci}`) ?? dbValue)) : dbValue;
+      return field(p, control(col, `${g}_0_c${col.ci}`, value, label(col.name)), true);
+    });
+    const deleted = pi !== undefined && pv(`${g}_${pi}_del`) === 'true';
+    const links = [
+      editLink ? html`<a class="btn" ${linkAttrs(ctx, editLink.page, rowItems(row, editLink.items))}>${icon('edit')} ${editLink.label ? tr(editLink.label) : t('report.edit')}</a>` : '',
+      ...extraLinks.map((l) => html`<a class="btn" ${linkAttrs(ctx, l.page, rowItems(row, l.items))}>${tr(l.label!)}</a>`),
+    ];
+    return html`<div class="grid-record${deleted ? ' deleted' : ''}" data-row="0">
+      <div class="form-grid">${fieldsHtml}</div>
+      ${deletable ? html`<label class="check grid-sel"><input type="checkbox" name="${g}_0_del" value="true"${deleted ? raw(' checked') : ''}> ${t('grid.delete_toggle')}</label>` : ''}
+      ${links.some(Boolean) ? html`<div class="buttons">${links}</div>` : ''}
+      ${savable ? html`<input type="hidden" name="${g}_0_pk" value="${pk}"><input type="hidden" name="${g}_0_cs" value="${rowToken(ctx, r, pk)}"><input type="hidden" name="${g}_0_orig" value="${JSON.stringify(orig)}">` : ''}
+    </div>
+    ${recordNav()}`;
+  };
+  const newRecord = () => {
+    if (!insertable) return html`<p class="empty">${t('report.no_data')}</p>`;
+    const fieldsHtml = placed.flatMap((p) => {
+      const col = p.col;
+      if (masterCol && col.name === masterCol) return [field(p, masterValue, false)];
+      if (!writable.has(col.name)) return [];
+      return [field(p, control({ ...col, editable: true }, `${g}_n0_c${col.ci}`, pv(`${g}_n0_c${col.ci}`) ?? '', label(col.name)), true)];
+    });
+    return html`<div class="grid-record grid-new" data-new-row="0"><div class="form-grid">${fieldsHtml}</div></div>
+    ${recordNav()}`;
+  };
+
   // the aggregates under their columns (over all rows of the search, not only this page)
   const footer = agg && cols.length
     ? (() => {
@@ -344,10 +444,50 @@ export async function renderGrid(ctx: PageContext, r: Region): Promise<Raw> {
   const searchForm = `rs${r.id}`;
   ctx.detached.push(
     html`<form id="${searchForm}" method="get" action="${ctx.base}/${ctx.page.page_no}">${[...ctx.params.entries()]
-      .filter(([k]) => ![key(r, 'q'), key(r, 'p'), key(r, 'dup'), 'clear', 'cs'].includes(k))
+      .filter(([k]) => ![key(r, 'q'), key(r, 'p'), key(r, 'dup'), key(r, 'row'), 'clear', 'cs'].includes(k))
       .map(([k, v]) => html`<input type="hidden" name="${k}" value="${v}">`)}</form>`,
   );
-  const menu = r.config.actions === false ? '' : await actionsMenu(ctx, r, cols, placed, layout, ownLayout, aggs);
+  const menu = r.config.actions === false ? '' : await actionsMenu(ctx, r, base, cols, placed, layout, ownLayout, aggs, views, view === 'row' ? null : rowUrl(info.from || 1));
+
+  // Grid / Single row / Group by / Chart: once the user has set up group by or chart, or is in the single
+  // row view (opened from the Actions or row actions menu), so a plain grid looks as it always did
+  const shownViews = GRID_VIEWS.filter((v) => v === 'report' || v === view || (views.includes(v) && ((v === 'group' && base.groupBy.columns.length) || (v === 'chart' && base.chart))));
+  const switcher = shownViews.length > 1
+    ? html`<nav class="seg view-switch" aria-label="${t('report.view')}">${shownViews.map((v) => html`<a href="${v === 'row' ? rowUrl(view === 'report' ? info.from || 1 : 1) : regionUrl(ctx, r, (p) => {
+        if (v === 'report') p.delete(key(r, 'v'));
+        else p.set(key(r, 'v'), v);
+        p.delete(key(r, 'row'));
+        // back to the grid: the page with the row the single row view showed
+        if (v === 'report' && view === 'row' && info.from) p.set(key(r, 'p'), String(Math.ceil(info.from / pageSize)));
+        else p.delete(key(r, 'p'));
+      })}" data-grid-leave${v === view ? raw(' aria-current="true"') : ''}>${t(v === 'report' ? 'grid.view_grid' : v === 'row' ? 'grid.view_row' : `report.view_${v}`)}</a>`)}</nav>`
+    : '';
+  const toolbar = (buttons: Raw | '') => html`<div class="report-toolbar grid-toolbar">
+      <div class="search" role="search">
+        <input type="search" name="${key(r, 'q')}" value="${st.search}" placeholder="${t('report.search_placeholder')}" form="${searchForm}" aria-label="${t('report.search')} ${r.title ?? ''}">
+        <button class="btn" form="${searchForm}">${t('report.go')}</button>
+        ${menu}
+      </div>
+      <div class="buttons">${buttons}</div>
+    </div>`;
+  // Save posts the page's report and grid state along, so a failed save shows the same view and a
+  // successful one comes back to it (routes.ts: gridReturn)
+  const saveBtn = () => {
+    const state = statePart(ctx).toString();
+    return html`<button type="submit" class="btn btn-hot" name="__request" value="${saveRequest(r)}"${state ? html` formaction="${ctx.base}/${ctx.page.page_no}?${state}"` : ''}>${t('grid.save')}</button>`;
+  };
+  const gridAttrs = raw(`${details.length ? ` data-grid-details="${details.map((d) => d.id).join(',')}"` : ''}`);
+  if (view === 'group' || view === 'chart')
+    return html`<div class="grid grid-view" data-grid="${g}" data-region="${r.id}"${gridAttrs}>
+      ${toolbar('')}${switcher}${await renderView(ctx, r, { ...base, view })}
+    </div>`;
+  if (view === 'row')
+    return html`<div class="grid grid-view" data-grid="${g}" data-region="${r.id}"${gridAttrs}>
+      ${toolbar(html`${insertable && !adding ? html`<a class="btn" href="${rowUrl('new')}" data-grid-leave>${icon('plus')} ${t('grid.add_row')}</a>` : ''}
+        ${savable && (adding ? insertable : info.rows.length) ? saveBtn() : ''}`)}
+      ${switcher}
+      ${adding ? newRecord() : info.rows.length ? record(info.rows[0]) : html`<p class="empty">${r.config.empty ?? t('report.no_data')}</p>`}
+    </div>`;
   const chips = aggs.filter((a) => a.own).map((a) => html`<span class="chip">${t(`agg.${a.fn}`)}: <b>${label(a.column)}</b>
       <a href="${regionUrl(ctx, r, (p) => {
         const rest = p.getAll(key(r, 'a')).filter((x) => x !== a.raw);
@@ -355,18 +495,10 @@ export async function renderGrid(ctx: PageContext, r: Region): Promise<Raw> {
         rest.forEach((x) => p.append(key(r, 'a'), x));
       })}" aria-label="${t('report.remove')}" data-grid-leave>×</a></span>`);
 
-  return html`<div class="grid${frozenAny ? ' grid-has-frozen' : ''}" data-grid="${g}" data-region="${r.id}"${r.config.actions === false ? '' : raw(' data-arrange')}${details.length ? raw(` data-grid-details="${details.map((d) => d.id).join(',')}"`) : ''}>
-    <div class="report-toolbar grid-toolbar">
-      <div class="search" role="search">
-        <input type="search" name="${key(r, 'q')}" value="${st.search}" placeholder="${t('report.search_placeholder')}" form="${searchForm}" aria-label="${t('report.search')} ${r.title ?? ''}">
-        <button class="btn" form="${searchForm}">${t('report.go')}</button>
-        ${menu}
-      </div>
-      <div class="buttons">
-        ${insertable ? html`<button type="button" class="btn" data-grid-add="${g}">${icon('plus')} ${t('grid.add_row')}</button>` : ''}
-        ${savable ? html`<button type="submit" class="btn btn-hot" name="__request" value="${saveRequest(r)}">${t('grid.save')}</button>` : ''}
-      </div>
-    </div>
+  return html`<div class="grid${frozenAny ? ' grid-has-frozen' : ''}" data-grid="${g}" data-region="${r.id}"${r.config.actions === false ? '' : raw(' data-arrange')}${gridAttrs}>
+    ${toolbar(html`${insertable ? html`<button type="button" class="btn" data-grid-add="${g}">${icon('plus')} ${t('grid.add_row')}</button>` : ''}
+      ${savable ? saveBtn() : ''}`)}
+    ${switcher}
     ${chips.length ? html`<div class="chips">${chips}</div>` : ''}
     <div class="table-wrap"><table class="report report-reflow grid-table" data-frozen="${placed.filter((p) => p.frozen).length}" data-leads="${leads.length}">
       <thead><tr>${leadHeads}${header}</tr></thead>
@@ -380,8 +512,8 @@ export async function renderGrid(ctx: PageContext, r: Region): Promise<Raw> {
 
 /** The grid's Actions menu: columns (order, shown, width, frozen), aggregates, saved reports, reset. */
 async function actionsMenu(
-  ctx: PageContext, r: Region, cols: (GridColumn & { ci: number })[], placed: Placed<GridColumn & { ci: number }>[],
-  layout: GridLayout, ownLayout: boolean, aggs: ReturnType<typeof gridAggregates>,
+  ctx: PageContext, r: Region, st: ReportState, cols: (GridColumn & { ci: number })[], placed: Placed<GridColumn & { ci: number }>[],
+  layout: GridLayout, ownLayout: boolean, aggs: ReturnType<typeof gridAggregates>, views: View[], singleRow: string | null,
 ) {
   const t = ctx.locale.t;
   const label = (name: string) => headingOf(r, name, ctx.locale.tr);
@@ -391,13 +523,17 @@ async function actionsMenu(
   const layoutForm = `rl${r.id}`;
   const resetForm = `rr${r.id}`;
   const aggForm = `ra${r.id}`;
+  const groupForm = `rg${r.id}`;
+  const chartForm = `rk${r.id}`;
   ctx.detached.push(html`<form id="${layoutForm}" method="post" action="${base}/layout">${csrf}<input type="hidden" name="params" value="${here}"><input type="hidden" name="n" value="${placed.length}"></form>`);
   ctx.detached.push(html`<form id="${resetForm}" method="post" action="${base}/layout/reset">${csrf}<input type="hidden" name="params" value="${here}"></form>`);
-  ctx.detached.push(
-    html`<form id="${aggForm}" method="get" action="${ctx.base}/${ctx.page.page_no}">${[...ctx.params.entries()]
-      .filter(([k]) => ![key(r, 'p'), key(r, 'dup'), 'clear', 'cs'].includes(k))
-      .map(([k, v]) => html`<input type="hidden" name="${k}" value="${v}">`)}</form>`,
-  );
+  // Aggregate, Group by and Chart: GET forms that keep the rest of the page's state
+  for (const id of [aggForm, ...(views.includes('group') ? [groupForm] : []), ...(views.includes('chart') ? [chartForm] : [])])
+    ctx.detached.push(
+      html`<form id="${id}" method="get" action="${ctx.base}/${ctx.page.page_no}">${[...ctx.params.entries()]
+        .filter(([k]) => ![key(r, 'p'), key(r, 'dup'), key(r, 'row'), 'clear', 'cs'].includes(k))
+        .map(([k, v]) => html`<input type="hidden" name="${k}" value="${v}">`)}</form>`,
+    );
   const columnRows = placed.map((p, i) => html`<tr>
       <th scope="row">${label(p.col.name)}<input type="hidden" name="col_${i}" value="${p.col.name}" form="${layoutForm}"></th>
       <td><input type="checkbox" name="show_${i}" value="true" form="${layoutForm}"${p.hidden ? '' : raw(' checked')} aria-label="${t('grid.show_column', { column: label(p.col.name) })}"></td>
@@ -431,6 +567,9 @@ async function actionsMenu(
         </div>
         ${aggs.some((a) => !a.own) ? html`<small class="help">${t('grid.default_aggregates', { list: aggs.filter((a) => !a.own).map((a) => `${t(`agg.${a.fn}`)} ${label(a.column)}`).join(', ') })}</small>` : ''}
       </div>
+      ${views.includes('row') && singleRow ? html`<div class="menu-section menu-links"><a href="${singleRow}" data-grid-leave>${t('grid.view_row')}</a></div>` : ''}
+      ${views.includes('group') ? groupBySection(ctx, r, st, cols.map((c) => c.name), groupForm) : ''}
+      ${views.includes('chart') ? chartSection(ctx, r, st, cols.map((c) => c.name), chartForm) : ''}
       ${saved ?? ''}
     </div>
   </details>`;
@@ -447,6 +586,11 @@ export function statePart(ctx: PageContext, drop?: Region) {
   return out;
 }
 
+/** After a grid's Save: the report and grid parameters the request came with (the formaction), for the redirect. */
+export function gridReturn(ctx: PageContext, request: string) {
+  return /^GRID_SAVE_\d+$/.test(request) ? statePart(ctx).toString() : '';
+}
+
 /** Actions → Saved reports of a grid: its parameters plus the column layout (r<id>_lay). */
 async function gridSavedReports(ctx: PageContext, r: Region, layout: GridLayout) {
   if (ctx.user === 'nobody' || r.config.saved_reports === false) return null;

package/src/runtime/lists.ts

@@ -36,7 +36,7 @@ export interface ListNode {
   children: ListNode[];
 }
 
-export const LIST_TEMPLATES = ['links', 'badges', 'cards', 'tabs'] as const;
+export const LIST_TEMPLATES = ['links', 'badges', 'cards', 'tabs', 'wizard_progress'] as const;
 export type ListTemplate = (typeof LIST_TEMPLATES)[number];
 /** Most rows a list query may give. */
 export const LIST_MAX_ROWS = 500;
@@ -228,6 +228,16 @@ export async function renderListRegion(ctx: PageContext, r: Region): Promise<Raw
       return html`<ul class="cards list-cards">${flat(nodes).map((n) => html`<li><a ${linkAttrs(n, 'card list-card')}><span class="list-card-head">${icon(n.icon ?? 'chevron')}<h3>${n.label}</h3>${badge(n)}</span>${n.description ? html`<p class="muted">${n.description}</p>` : ''}</a></li>`)}</ul>`;
     case 'tabs':
       return html`<nav class="list-tabs" aria-label="${label}"><ul class="rds-list">${nodes.filter((n) => n.href).map((n) => html`<li><a ${linkAttrs(n, `rds-tab${n.inTrail ? ' is-current' : ''}`)}>${icon(n.icon)}<span>${n.label}</span>${badge(n)}</a></li>`)}</ul></nav>`;
+    case 'wizard_progress': {
+      // (088) the steps of a wizard (APEX: Wizard Progress): the current one (the page in the trail), the ones before it done
+      const steps = flat(nodes);
+      const at = steps.findIndex((n) => n.inTrail);
+      return html`<nav class="wizard-progress" aria-label="${label}"><ol>${steps.map((n, i) => {
+        const state = i === at ? 'current' : at >= 0 && i < at ? 'done' : 'todo';
+        const text = html`<span class="wizard-step-no" aria-hidden="true">${state === 'done' ? icon('check') : i + 1}</span><span class="wizard-step-label">${n.label}</span>`;
+        return html`<li class="wizard-step is-${state}"${state === 'current' ? html` aria-current="step"` : ''}>${state === 'done' && n.href ? html`<a ${linkAttrs(n, '')}>${text}</a>` : text}</li>`;
+      })}</ol></nav>`;
+    }
     default:
       return html`<nav aria-label="${label}">${linksMarkup(nodes)}</nav>`;
   }

package/src/runtime/password-reset.ts

@@ -0,0 +1,171 @@
+import { createHash, randomBytes } from 'node:crypto';
+import type { FastifyInstance } from 'fastify';
+import { passwordProblem } from '../accounts.ts';
+import { runtime } from '../db.ts';
+import { html, type Raw } from '../html.ts';
+import { documentShell } from '../layout.ts';
+import type { App } from '../metadata.ts';
+import { clientIp, getSession, logActivity, saveState, type Session } from '../session.ts';
+import { publicUrl } from '../sso.ts';
+import type { Locale } from './locale.ts';
+import { pwaHead } from './pwa.ts';
+import { appWithLocale, rootAttrs, simplePage, type Req } from './routes.ts';
+import { passwordResetAvailable } from './signin.ts';
+
+// "Forgot password?" for app users (migration 087). The request answers the
+// same whether or not an account matched; the database keeps only a SHA-256
+// hash of the token and queues the mail through the application's mail
+// service (meta.request_password_reset). The link is single-use and expires
+// after 30 minutes; opening it moves the token into the session and drops
+// it from the address bar. Setting the new password ends every session and
+// "keep me signed in" token of the account.
+//
+//   GET/POST /a/<alias>/password/forgot   ask for a link
+//   GET      /a/<alias>/password/reset?token=…  open the link
+//   GET/POST /a/<alias>/password/reset    choose the new password
+
+const RESET = '__RESET';
+/** Requests per address and window, whatever was typed in (the database also allows 3 per account per hour). */
+const MAX_PER_IP = 5;
+const WINDOW_MINUTES = 15;
+
+const sha256 = (s: string) => createHash('sha256').update(s).digest('hex');
+
+function card(app: App, locale: Locale, title: string, body: Raw) {
+  return documentShell(
+    `${title} · ${app.name}`,
+    html`<main class="login">
+      <div class="card login-card">
+        <h1>${title}</h1>
+        ${body}
+        <a class="login-forgot" href="/a/${app.alias}/login">${locale.t('reset.back')}</a>
+      </div>
+    </main>`,
+    'login-body',
+    {},
+    pwaHead(app),
+    rootAttrs(locale),
+  );
+}
+
+const forgotPage = (app: App, locale: Locale, session: Session, message?: Raw) => {
+  const t = locale.t;
+  return card(app, locale, t('reset.title'), html`${message ?? html`<p class="muted">${t('reset.intro')}</p>`}
+    <form method="post" action="/a/${app.alias}/password/forgot" class="login-form">
+      <input type="hidden" name="__csrf" value="${session.csrf_token}">
+      <div class="field"><label class="label" for="login">${t('reset.login_label')}</label><input id="login" name="login" autocomplete="username" autofocus required maxlength="200"></div>
+      <button class="btn btn-hot">${t('reset.send')}</button>
+    </form>`);
+};
+
+const newPasswordPage = (app: App, locale: Locale, session: Session, username: string, error?: string) => {
+  const t = locale.t;
+  return card(app, locale, t('reset.new_title'), html`${error ? html`<div class="alert alert-error" role="alert">${error}</div>` : ''}
+    <form method="post" action="/a/${app.alias}/password/reset" class="login-form">
+      <input type="hidden" name="__csrf" value="${session.csrf_token}">
+      <div class="field"><label class="label" for="username">${t('login.username')}</label><input id="username" name="username" value="${username}" autocomplete="username" readonly></div>
+      <div class="field"><label class="label" for="new_password">${t('password.new')}</label><input id="new_password" name="new_password" type="password" autocomplete="new-password" required maxlength="200" autofocus></div>
+      <div class="field"><label class="label" for="confirm_password">${t('password.confirm')}</label><input id="confirm_password" name="confirm_password" type="password" autocomplete="new-password" required maxlength="200"></div>
+      <button class="btn btn-hot">${t('password.change')}</button>
+    </form>`);
+};
+
+/** The mail: plain text, and the same as HTML with the link as a link. #USER# is filled in by the database. */
+function resetMail(app: App, locale: Locale, link: string) {
+  const t = locale.t;
+  const text = t('reset.mail_body', { app: app.name, link });
+  const esc = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+  const body = text.split(/\n{2,}/).map((para) => `<p>${esc(para).replace(esc(link), `<a href="${esc(link)}">${esc(link)}</a>`).replace(/\n/g, '<br>')}</p>`).join('\n');
+  return { subject: t('reset.mail_subject', { app: app.name }), text, html: `<!doctype html><html><body>${body}</body></html>` };
+}
+
+export function passwordResetRoutes(app: FastifyInstance) {
+  /** The application (with its locale) and session, when it offers password resets; else a 404 page. */
+  const start = async (req: Req, reply: Parameters<typeof simplePage>[0]) => {
+    const loaded = await appWithLocale(req, req.params.alias);
+    if (!loaded || !(await passwordResetAvailable(loaded.app))) {
+      simplePage(reply, 404, (loaded?.locale.t ?? ((k: string) => k))('error.not_found'), loaded ? loaded.locale.t('login.method_unavailable') : req.params.alias, loaded ? `/a/${loaded.app.alias}/login` : undefined, loaded?.locale);
+      return null;
+    }
+    const session = await getSession(req, reply, loaded.app.id, `/a/${loaded.app.alias}`);
+    return { ...loaded, session };
+  };
+
+  app.get('/a/:alias/password/forgot', async (req: Req, reply) => {
+    const s = await start(req, reply);
+    if (!s) return;
+    const body = forgotPage(s.app, s.locale, s.session);
+    await saveState(s.session);
+    return reply.type('text/html').send(body);
+  });
+
+  app.post('/a/:alias/password/forgot', async (req: Req, reply) => {
+    const s = await start(req, reply);
+    if (!s) return;
+    const { app: a, locale, session } = s;
+    const t = locale.t;
+    if (req.body?.__csrf !== session.csrf_token)
+      return reply.code(403).type('text/html').send(forgotPage(a, locale, session, html`<div class="alert alert-error" role="alert">${t('login.expired_session')}</div>`));
+    const ip = clientIp(req);
+    const login = String(req.body?.login ?? '').slice(0, 200).replace(/\0/g, '');
+    const recent = await runtime.one<{ n: number }>(
+      `select count(*)::int as n from meta.activity_log where app_id = $1 and event = 'password_reset_request' and ip = $2 and at > now() - make_interval(mins => $3)`,
+      [a.id, ip, WINDOW_MINUTES],
+    );
+    if ((recent?.n ?? 0) >= MAX_PER_IP)
+      return reply.code(429).type('text/html').send(forgotPage(a, locale, session, html`<div class="alert alert-error" role="alert">${t('login.throttled', { minutes: WINDOW_MINUTES })}</div>`));
+    await logActivity({ appId: a.id, username: login.slice(0, 100), event: 'password_reset_request', ip });
+    if (login.trim()) {
+      const token = randomBytes(32).toString('base64url');
+      const mail = resetMail(a, locale, `${publicUrl()}/a/${a.alias}/password/reset?token=${token}`);
+      await runtime.query('select meta.request_password_reset($1, $2, $3, $4, $5, $6, $7)', [a.id, login, sha256(token), ip, mail.subject, mail.text, mail.html]);
+    }
+    // the same answer whether or not an account matched
+    return reply.type('text/html').send(card(a, locale, t('reset.title'), html`<div class="alert alert-success" role="status">${t('reset.sent')}</div>`));
+  });
+
+  app.get<{ Params: { alias: string }; Querystring: { token?: string } }>('/a/:alias/password/reset', async (req, reply) => {
+    const s = await start(req as Req, reply);
+    if (!s) return;
+    const { app: a, locale, session } = s;
+    // the link: keep the token in the session and take it out of the address bar (and history); a redirect
+    // without content, so no page with the token in its address loads anything (the Referer stays clean)
+    const token = typeof req.query.token === 'string' ? req.query.token.slice(0, 100) : null;
+    if (token !== null) {
+      session.state[RESET] = sha256(token);
+      await saveState(session);
+      return reply.redirect(`/a/${a.alias}/password/reset`, 303);
+    }
+    const hash = session.state[RESET];
+    const user = hash ? (await runtime.one<{ u: string | null }>('select meta.password_reset_user($1, $2) as u', [a.id, hash]))?.u : null;
+    if (!user) return reply.code(410).type('text/html').send(invalidPage(a, locale));
+    return reply.type('text/html').send(newPasswordPage(a, locale, session, user));
+  });
+
+  app.post('/a/:alias/password/reset', async (req: Req, reply) => {
+    const s = await start(req, reply);
+    if (!s) return;
+    const { app: a, locale, session } = s;
+    const t = locale.t;
+    const hash = session.state[RESET];
+    const user = hash ? (await runtime.one<{ u: string | null }>('select meta.password_reset_user($1, $2) as u', [a.id, hash]))?.u : null;
+    if (!user) return reply.code(410).type('text/html').send(invalidPage(a, locale));
+    const b = req.body ?? {};
+    const again = (msg: string, code = 422) => reply.code(code).type('text/html').send(newPasswordPage(a, locale, session, user, msg));
+    if (b.__csrf !== session.csrf_token) return again(t('login.expired_session'), 403);
+    if (b.new_password !== b.confirm_password) return again(t('password.mismatch'));
+    const problem = await passwordProblem(b.new_password, { username: user, t });
+    if (problem) return again(problem);
+    const done = (await runtime.one<{ u: string | null }>('select meta.reset_password($1, $2, $3) as u', [a.id, hash, String(b.new_password).slice(0, 200)]))?.u;
+    if (!done) return reply.code(410).type('text/html').send(invalidPage(a, locale));
+    delete session.state[RESET];
+    session.state.__FLASH = t('reset.done');
+    await saveState(session);
+    await logActivity({ appId: a.id, username: done, event: 'password_reset', ip: clientIp(req) });
+    return reply.redirect(`/a/${a.alias}/login`, 303);
+  });
+
+  const invalidPage = (a: App, locale: Locale) =>
+    card(a, locale, locale.t('reset.new_title'), html`<div class="alert alert-error" role="alert">${locale.t('reset.invalid')}</div>
+      <a class="btn" href="/a/${a.alias}/password/forgot">${locale.t('reset.send')}</a>`);
+}

package/src/runtime/pwa.ts

@@ -3,6 +3,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { deflateSync } from 'node:zlib';
 import { root } from '../env.ts';
+import { staticVersion } from '../static-version.ts';
 import { html, type Raw } from '../html.ts';
 import { documentShell } from '../layout.ts';
 import { loadApp, type App } from '../metadata.ts';
@@ -116,7 +117,9 @@ const icons = new Map<string, Buffer>(); // generated tiles by name|colour|size
 
 // ------------------------------------------------------------------ routes
 
-const SW = readFileSync(join(root, 'public', 'sw.js'), 'utf8');
+// read again when pgkiln's static files change (static-version.ts)
+let sw = { version: '', text: '' };
+const swText = (version: string) => (sw.version === version ? sw.text : (sw = { version, text: readFileSync(join(root, 'public', 'sw.js'), 'utf8') }).text);
 
 export async function pwaRoutes(app: FastifyInstance) {
   const pwaApp = async (alias: string) => {
@@ -171,12 +174,13 @@ export async function pwaRoutes(app: FastifyInstance) {
     if (!a) return reply.code(404).send('// not an installable application');
     const base = `/a/${a.alias}`;
     // the settings the worker needs, as a JSON literal (no user input in it)
-    const config = JSON.stringify({ base, offlinePages: a.pwa_offline_pages, offlineSubmit: a.pwa_offline_submit, version: SW_VERSION });
+    const version = staticVersion();
+    const config = JSON.stringify({ base, offlinePages: a.pwa_offline_pages, offlineSubmit: a.pwa_offline_submit, version });
     return reply
       .type('text/javascript; charset=utf-8')
       .header('cache-control', 'no-cache')
       .header('service-worker-allowed', `${base}/`)
-      .send(`const PGKILN = ${config};\n${SW}`);
+      .send(`const PGKILN = ${config};\n${swText(version)}`);
   });
 
   app.get<{ Params: { alias: string } }>('/a/:alias/offline', async (req, reply) => {
@@ -205,11 +209,4 @@ export async function pwaRoutes(app: FastifyInstance) {
   });
 }
 
-// changes whenever pgkiln's static files change (a new service worker then replaces the old one)
-const SW_VERSION = (() => {
-  let h = 0;
-  for (const f of ['public/app.css', 'public/app.js', 'public/icons.svg', 'public/sw.js'])
-    for (const ch of readFileSync(join(root, f), 'utf8')) h = (Math.imul(h, 31) + ch.charCodeAt(0)) | 0;
-  return (h >>> 0).toString(36);
-})();
 

package/src/runtime/regions.ts

@@ -33,6 +33,7 @@ import { templateClasses } from './template-options.ts';
 import { renderPluginRegion } from './plugins.ts';
 import { renderUrlRegion } from './url-region.ts';
 import { renderSearch } from './search.ts';
+import { renderLoginRegion } from './signin.ts';
 
 // ---------------------------------------------------------------- buttons
 
@@ -359,6 +360,9 @@ async function renderBody(ctx: PageContext, r: Region, hidden: Set<string>): Pro
     case 'search':
       body = await renderSearch(ctx, r);
       break;
+    case 'login':
+      body = await renderLoginRegion(ctx);
+      break;
     case 'dynamic':
       // A SELECT returning HTML (like APEX "PL/SQL Dynamic Content"). The
       // developer's SQL produces trusted markup; escape data with meta.html_escape().
@@ -395,6 +399,35 @@ async function regionShell(ctx: PageContext, r: Region, hidden: Set<string>, bod
       ${!buttonsOnTop && buttons ? html`<footer class="region-footer">${buttons}</footer>` : ''}
     </section>`;
 
+  // (088) a large banner: an icon, the title, the text and the buttons
+  if (r.template === 'hero') {
+    const heroIcon = typeof r.config?.icon === 'string' ? icon(r.config.icon) : '';
+    return html`<section class="${cls}" id="R${r.id}"${staticAttr}${hiddenAttr} aria-labelledby="${titleId}">
+      ${heroIcon ? html`<span class="region-hero-icon">${heroIcon}</span>` : ''}
+      <div class="region-hero-text"><h2 id="${titleId}">${r.title}</h2>${body}</div>
+      ${buttons ? html`<div class="region-hero-buttons">${buttons}</div>` : ''}
+    </section>`;
+  }
+  // (088) the title and buttons on one line, without a card
+  if (r.template === 'title_bar')
+    return html`<section class="${cls}" id="R${r.id}"${staticAttr}${hiddenAttr} aria-labelledby="${titleId}">
+      <div class="region-title-bar"><h2 id="${titleId}">${r.title}</h2>${buttons ? html`<div class="region-title-buttons">${buttons}</div>` : ''}</div>
+      ${body}
+    </section>`;
+  // (088) the buttons (and any text) only
+  if (r.template === 'buttons_container')
+    return html`<section class="${cls}" id="R${r.id}"${staticAttr}${hiddenAttr} aria-label="${r.title}">
+      ${body}${buttons ? html`<div class="region-buttons">${buttons}</div>` : ''}
+    </section>`;
+  // (088) hidden until opened: a dynamic action "Open region", or a link to #R<id> (CSS :target without JavaScript)
+  if (r.template === 'inline_dialog' || r.template === 'inline_drawer')
+    return html`<dialog class="${cls}" id="R${r.id}"${staticAttr} aria-labelledby="${titleId}" data-inline-region>
+      <header class="region-header"><h2 id="${titleId}">${r.title}</h2>
+        <a class="region-dialog-close icon-button" href="#" role="button" data-region-close aria-label="${ctx.locale.t('common.dismiss')}">${icon('close')}</a></header>
+      <div class="region-body">${body}</div>
+      ${buttons ? html`<footer class="region-footer">${buttons}</footer>` : ''}
+    </dialog>`;
+
   const header = html`<h2 id="${titleId}">${r.title}</h2>${buttonsOnTop ? buttons : ''}`;
   if (r.template === 'collapsible')
     return html`<section class="${cls}" id="R${r.id}"${staticAttr}${hiddenAttr} aria-labelledby="${titleId}">

package/src/runtime/render.ts

@@ -242,6 +242,21 @@ export async function chrome(ctx: PageContext, main: Raw, title: string) {
       'data-dialog': '1',
     }, html`${pageStyle(ctx)}${pwaHead(ctx.app)}${mapHead(ctx)}${staticHead(ctx)}`, root);
 
+  // (087) a minimal page (a login page, for one): no header and navigation; the application's
+  // login page gets the sign-in page's backdrop
+  if (ctx.page.page_template === 'minimal') {
+    const login = ctx.app.login_page === ctx.page.page_no;
+    return documentShell(
+      `${title} · ${ctx.app.name}`,
+      html`<main class="t-minimal-main${login ? ' login' : ''}" id="main">${main}</main>
+      ${devbarHtml(ctx)}`,
+      `t-minimal${login ? ' login-body' : ''}`,
+      { 'data-base': ctx.base, 'data-page': String(ctx.page.page_no), ...pwaBody(ctx.app, ctx.user) },
+      html`${pageStyle(ctx)}${pwaHead(ctx.app)}${mapHead(ctx)}${staticHead(ctx)}`,
+      root,
+    );
+  }
+
   const signedIn = ctx.user !== 'nobody';
   const topNav = ctx.app.theme?.nav === 'top';
   const nav = await navTree(ctx, topNav);