pgkiln 0.53.0 → 0.54.0

package/src/builder/gallery.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { FastifyInstance } from 'fastify';
-import { owner, ownerUrl } from '../db.ts';
+import { owner, ownerUrl, type Client } from '../db.ts';
 import { root } from '../env.ts';
 import { html, raw } from '../html.ts';
 import { icon } from '../icons.ts';
@@ -13,16 +13,21 @@ import { back, BASE, csrf, developer, flash, send, shell, type Req } from './ui.
 import { currentWorkspace, inWorkspaceSql, placeApp } from './workspaces.ts';
 import { workspacesChanged } from '../workspace-db.ts';
 
-// The App Gallery (sprint 61; APEX: App Gallery with Sample, Starter and Custom Apps).
+// The App Gallery (sprint 61, sprint 120; APEX: App Gallery with Sample, Starter, Utility and
+// Custom Apps).
 //
-//   Sample apps   applications shipped with pgkiln (examples/): an administrator installs
-//                 one with its schema, data and demo accounts, as `pgkiln migrate --example`;
+//   Sample apps   applications shipped with pgkiln: an administrator installs one with its
+//                 schema, data and demo account, either an example directory (`example`, as
+//                 `pgkiln migrate --example`) or one SQL file (`file`: examples/*.sql or
+//                 examples/gallery/samples/*.sql, run in one transaction as the owner);
 //   Starter apps  blueprints shipped with pgkiln (examples/gallery/starters/): Install opens
 //                 the blueprint's review, and the developer creates the application from it
 //                 in the current workspace (a new role and schema, like every new application);
+//   Utility apps  (sprint 120) blueprints too (examples/gallery/utilities/), of applications a
+//                 workspace uses rather than learns from, installed the same way;
 //   Custom apps   the workspace's boilerplate applications: Create application starts from one.
 //
-// The list is examples/gallery/gallery.json.
+// The list is examples/gallery/gallery.json; requests only ever name a key of it.
 
 interface Sample {
   key: string;
@@ -44,64 +49,94 @@ interface Starter {
 const GALLERY = join(root, 'examples', 'gallery');
 const KEY = /^[a-z][a-z0-9-]{0,40}$/;
 
-function catalog(): { samples: Sample[]; starters: Starter[] } {
+const list = <T>(v: unknown): T[] => (Array.isArray(v) ? v : []);
+
+function catalog(): { samples: Sample[]; starters: Starter[]; utilities: Starter[] } {
   try {
     const c = JSON.parse(readFileSync(join(GALLERY, 'gallery.json'), 'utf8'));
-    return { samples: Array.isArray(c.samples) ? c.samples : [], starters: Array.isArray(c.starters) ? c.starters : [] };
+    return { samples: list(c.samples), starters: list(c.starters), utilities: list(c.utilities) };
   } catch {
-    return { samples: [], starters: [] };
+    return { samples: [], starters: [], utilities: [] };
   }
 }
 
+/** The blueprint files a kind of entry may name: starters/x.json or utilities/x.json. */
+const BLUEPRINT_FILE = { starters: /^starters\/[a-z0-9-]+\.json$/, utilities: /^utilities\/[a-z0-9-]+\.json$/ } as const;
+/** The SQL files a sample may name: examples/x.sql or examples/gallery/samples/x.sql. */
+const SAMPLE_FILE = /^(samples\/)?[a-z0-9-]+\.sql$/;
+
 /** A file of the gallery: only names from the catalogue, never a path from the request. */
 const galleryFile = (rel: string) => readFileSync(join(rel.includes('/') ? GALLERY : join(root, 'examples'), rel), 'utf8');
 
-type Tab = 'samples' | 'starters' | 'custom';
+type Tab = 'samples' | 'starters' | 'utilities' | 'custom';
+const TABS: readonly [Tab, string][] = [['samples', 'Sample Apps'], ['starters', 'Starter Apps'], ['utilities', 'Utility Apps'], ['custom', 'Custom Apps']];
 
 export async function galleryRoutes(app: FastifyInstance) {
   app.get(`${BASE}/gallery`, async (req: Req, reply) => {
     const s = await developer(req, reply);
     if (!s) return;
-    const tab: Tab = (['samples', 'starters', 'custom'] as const).find((t) => t === req.query?.tab) ?? 'samples';
+    const tab: Tab = TABS.map(([t]) => t).find((t) => t === req.query?.tab) ?? 'samples';
+    const q = typeof req.query?.q === 'string' ? req.query.q.trim().slice(0, 100) : '';
     const admin = await isAdmin(s.username);
-    const { samples, starters } = catalog();
+    const ws = currentWorkspace(s);
+    const { samples, starters, utilities } = catalog();
+    // an installed sample: Edit only in its own workspace
     const installed = new Map(
-      (await owner.query<{ alias: string; id: number }>('select alias, id from meta.app where alias = any($1)', [samples.map((x) => x.alias)])).rows.map((r) => [r.alias, r.id]),
+      (await owner.query<{ alias: string; id: number; here: boolean }>(`select a.alias, a.id, ${inWorkspaceSql('a', 2)} as here from meta.app a where a.alias = any($1)`,
+        [samples.map((x) => x.alias), ws])).rows.map((r) => [r.alias, r]),
     );
     const custom = (await owner.query<{ id: number; name: string; description: string | null }>(
       `select a.id, a.name, null::text as description from meta.app a where a.app_type = 'boilerplate' and ${inWorkspaceSql('a', 1)} order by lower(a.name), a.id`,
-      [currentWorkspace(s)],
+      [ws],
     )).rows;
+    // (sprint 120) the search also works without JavaScript: ?q= leaves out what doesn't match
+    // (like the script's filter: every word of the search in the title or description)
+    const words = q.toLowerCase().split(/\s+/).filter(Boolean);
+    const matches = (x: { title?: string; name?: string; description?: string | null }) => {
+      const text = `${x.title ?? x.name ?? ''} ${x.description ?? ''}`.toLowerCase();
+      return words.every((w) => text.includes(w));
+    };
+    const counts: Record<Tab, number> = { samples: samples.length, starters: starters.length, utilities: utilities.length, custom: custom.length };
     const card = (ic: string, title: string, by: string, text: string, action: unknown) =>
       html`<article class="gal-card" data-filter-row><div class="gal-head"><span class="gal-icon">${icon(ic)}</span><div><h2>${title}</h2><span class="muted small">${by}</span></div></div>
         <p>${text}</p><div class="gal-foot">${action}</div></article>`;
-    const tabs = html`<nav class="gal-tabs segmented" aria-label="Kinds of applications">${([['samples', 'Sample Apps'], ['starters', 'Starter Apps'], ['custom', 'Custom Apps']] as const).map(([t, l]) =>
-      html`<a href="${BASE}/gallery?tab=${t}"${tab === t ? raw(' aria-current="page"') : ''}>${l}</a>`)}</nav>`;
+    const tabs = html`<nav class="gal-tabs segmented" aria-label="Kinds of applications">${TABS.map(([t, l]) =>
+      html`<a href="${BASE}/gallery?tab=${t}${q ? `&q=${encodeURIComponent(q)}` : ''}"${tab === t ? raw(' aria-current="page"') : ''}>${l} <span class="gal-count">${counts[t]}</span></a>`)}</nav>`;
+    const blueprintCard = (kind: 'starters' | 'utilities') => (x: Starter) => card(x.icon, x.title, 'pgkiln', x.description,
+      html`<form method="post" action="${BASE}/gallery/${kind}/${x.key}">${csrf(s)}<button class="btn btn-hot btn-sm">Install</button></form>`);
     const cards =
       tab === 'samples'
-        ? samples.map((x) => card(x.icon, x.title, 'pgkiln', x.description,
-            installed.has(x.alias)
-              ? html`<span class="tag tag-ok">Installed</span><a class="btn btn-sm" href="/a/${x.alias}" target="_blank" rel="noopener">Run</a><a class="btn btn-sm" href="${BASE}/apps/${installed.get(x.alias)}">Edit</a>`
-              : admin
-                ? html`<form method="post" action="${BASE}/gallery/samples/${x.key}">${csrf(s)}<button class="btn btn-hot btn-sm" data-confirm="Install ${x.title}? It adds its own schema, data and demo accounts with known passwords: not for a production instance.">Install</button></form>`
-                : html`<span class="muted small">An administrator installs it.</span>`))
-        : tab === 'starters'
-          ? starters.map((x) => card(x.icon, x.title, 'pgkiln', x.description,
-              html`<form method="post" action="${BASE}/gallery/starters/${x.key}">${csrf(s)}<button class="btn btn-hot btn-sm">Install</button></form>`))
-          : custom.map((x) => card('copy', x.name, 'This workspace', x.description ?? 'A boilerplate application: a new application starts with its pages, shared components and settings.',
+        ? samples.filter(matches).map((x) => {
+            const it = installed.get(x.alias);
+            return card(x.icon, x.title, 'pgkiln', x.description,
+              it
+                ? html`<span class="tag tag-ok">Installed</span><a class="btn btn-sm" href="/a/${x.alias}" target="_blank" rel="noopener">Run</a>${it.here
+                    ? html`<a class="btn btn-sm" href="${BASE}/apps/${it.id}">Edit</a>`
+                    : html`<span class="muted small">in another workspace</span>`}`
+                : admin
+                  ? html`<form method="post" action="${BASE}/gallery/samples/${x.key}">${csrf(s)}<button class="btn btn-hot btn-sm" data-confirm="Install ${x.title}? It adds its own schema, data and demo accounts with known passwords: not for a production instance.">Install</button></form>`
+                  : html`<span class="muted small">An administrator installs it.</span>`);
+          })
+        : tab === 'starters' || tab === 'utilities'
+          ? (tab === 'starters' ? starters : utilities).filter(matches).map(blueprintCard(tab))
+          : custom.filter(matches).map((x) => card('copy', x.name, 'This workspace', x.description ?? 'A boilerplate application: a new application starts with its pages, shared components and settings.',
               html`<a class="btn btn-hot btn-sm" href="${BASE}/create?boilerplate=${x.id}">Create from it</a><a class="btn btn-sm" href="${BASE}/apps/${x.id}">Edit</a>`));
-    const empty = tab === 'custom'
-      ? html`<p class="muted">No custom apps yet: make an application of type <em>Boilerplate</em> (Application settings → Application type) and it appears here.</p>`
-      : html`<p class="muted">The gallery is empty.</p>`;
+    const empty = q && counts[tab]
+      ? html`<p class="muted">No app matches <strong>${q}</strong>. <a href="${BASE}/gallery?tab=${tab}">Show all</a></p>`
+      : tab === 'custom'
+        ? html`<p class="muted">No custom apps yet: make an application of type <em>Boilerplate</em> (Application settings → Application type) and it appears here.</p>`
+        : html`<p class="muted">The gallery is empty.</p>`;
     const intro = {
-      samples: 'Applications that show what pgkiln can do, with their own data and demo accounts. Install them on a development or demo instance.',
+      samples: 'Applications that show what pgkiln can do, each with its own schema, data and demo account: the showcase, the tutorial, one app per feature area and the UX Pattern Catalog. An administrator installs them on a development or demo instance.',
       starters: 'Small, ready-to-use applications. Install shows what will be created (tables, pages, sample data) before anything happens; the application gets its own role and schema in this workspace.',
+      utilities: 'Applications a workspace uses rather than learns from: shared lookup lists, release notes, announcements. Like starter apps, Install shows what will be created first, and the application gets its own role and schema in this workspace.',
       custom: 'The boilerplate applications of this workspace: start a new application from one.',
     }[tab];
     const main = html`<div class="gal">
       <div class="gal-bar">
-        <div class="ab-search gal-search" role="search"><label class="sr-only" for="gal-q">Search apps</label>${icon('search')}
-          <input id="gal-q" type="search" placeholder="Search apps" autocomplete="off" data-filter-list=".gal [data-filter-row]"></div>
+        <form class="ab-search gal-search" role="search" method="get" action="${BASE}/gallery"><label class="sr-only" for="gal-q">Search apps</label>${icon('search')}
+          <input type="hidden" name="tab" value="${tab}">
+          <input id="gal-q" name="q" type="search" placeholder="Search apps" autocomplete="off" value="${q}" data-filter-list=".gal [data-filter-row]"></form>
         ${tabs}
       </div>
       <h1 class="sr-only">App Gallery</h1>
@@ -120,19 +155,30 @@ export async function galleryRoutes(app: FastifyInstance) {
     if (!x) return reply.code(404).send('Not found');
     try {
       if (await owner.one('select 1 as ok from meta.app where alias = $1', [x.alias])) throw new Error(`an application with the alias ${x.alias} exists already.`);
-      if (x.example && KEY.test(x.example)) await migrate({ root, databaseUrl: ownerUrl, example: x.example, log: () => {} });
-      else if (x.file && /^[a-z0-9-]+\.sql$/.test(x.file)) await owner.query(galleryFile(x.file));
-      else throw new Error('the gallery entry names nothing to install.');
-      const made = await owner.one<{ id: number; db_role: string | null }>('select id, db_role from meta.app where alias = $1', [x.alias]);
-      if (!made) throw new Error(`the scripts ran, but there is no application ${x.alias}.`);
-      // into the current workspace (an isolated one gets the application's role too)
       const ws = currentWorkspace(s);
-      if (ws > 1)
-        await owner.tx(async (c) => {
+      // into the current workspace (an isolated one gets the application's role too)
+      const place = async (c: Client) => {
+        const made = (await c.query('select id, db_role from meta.app where alias = $1', [x.alias])).rows[0] as { id: number; db_role: string | null } | undefined;
+        if (!made) throw new Error(`the scripts ran, but there is no application ${x.alias}.`);
+        if (ws > 1) {
           if (made.db_role && (await c.query('select 1 from meta.workspace where id = $1 and isolated', [ws])).rowCount)
             await c.query('insert into meta.workspace_role (workspace_id, role_name) values ($1, $2) on conflict do nothing', [ws, made.db_role]);
           await placeApp(c, made.id, ws);
+        }
+        return made;
+      };
+      let made: { id: number; db_role: string | null };
+      if (x.example && KEY.test(x.example)) {
+        await migrate({ root, databaseUrl: ownerUrl, example: x.example, log: () => {} });
+        made = await owner.tx(place);
+      } else if (x.file && SAMPLE_FILE.test(x.file)) {
+        // (sprint 120) the file and the placement in one transaction: a failing script leaves nothing behind
+        const sql = galleryFile(x.file);
+        made = await owner.tx(async (c) => {
+          await c.query(sql);
+          return place(c);
         });
+      } else throw new Error('the gallery entry names nothing to install.');
       await workspacesChanged();
       await logActivity({ appId: made.id, username: s.username, event: 'gallery', ip: clientIp(req), detail: `installed sample app ${x.key}` });
       flash(s, `${x.title} installed (/a/${x.alias}).`);
@@ -143,12 +189,13 @@ export async function galleryRoutes(app: FastifyInstance) {
     }
   });
 
-  // a starter app: its blueprint's review (nothing is created before the developer confirms there)
-  app.post(`${BASE}/gallery/starters/:key`, async (req: Req, reply) => {
-    const s = await developer(req, reply);
-    if (!s) return;
-    const x = KEY.test(req.params.key) ? catalog().starters.find((c) => c.key === req.params.key) : undefined;
-    if (!x || !/^starters\/[a-z0-9-]+\.json$/.test(x.file)) return reply.code(404).send('Not found');
-    return openBlueprint(s, reply, x.title, JSON.stringify(JSON.parse(galleryFile(x.file)), null, 2));
-  });
+  // a starter or utility app: its blueprint's review (nothing is created before the developer confirms there)
+  for (const kind of ['starters', 'utilities'] as const)
+    app.post(`${BASE}/gallery/${kind}/:key`, async (req: Req, reply) => {
+      const s = await developer(req, reply);
+      if (!s) return;
+      const x = KEY.test(req.params.key) ? catalog()[kind].find((c) => c.key === req.params.key) : undefined;
+      if (!x || typeof x.file !== 'string' || !BLUEPRINT_FILE[kind].test(x.file)) return reply.code(404).send('Not found');
+      return openBlueprint(s, reply, x.title, JSON.stringify(JSON.parse(galleryFile(x.file)), null, 2));
+    });
 }

package/src/runtime/charts.ts

@@ -230,7 +230,10 @@ function column(labels: string[], series: Series[]) {
         const col = html`<span class="col s${si + 1}${v < 0 ? ' neg' : ''} ${css.cls(`bottom:${pct(bottom)};height:${pct(top - bottom)}`)}"></span>`;
         return multi && link ? mark('span', i, si, 'col-slot', `${l} · ${s.name}: ${fmt.format(v)}`, col, false) : html`<span class="col-slot">${col}</span>`;
       })}${!multi && labels.length <= 12
-        ? html`<span class="col-value ${css.cls(`bottom:${pct(Math.max(y(series[0].values[i]), zero))}`)}">${compact.format(series[0].values[i])}</span>`
+        // (sprint 120) inside a drill link the value is drawn by CSS (attr()), so the link's name is its tip alone
+        ? link
+          ? html`<span class="col-value ${css.cls(`bottom:${pct(Math.max(y(series[0].values[i]), zero))}`)}" aria-hidden="true" data-value="${compact.format(series[0].values[i])}"></span>`
+          : html`<span class="col-value ${css.cls(`bottom:${pct(Math.max(y(series[0].values[i]), zero))}`)}" aria-hidden="true">${compact.format(series[0].values[i])}</span>`
         : ''}`;
       return multi ? html`<div class="col-group" role="img" data-tip="${tip(l, series, i)}" tabindex="0" aria-label="${tip(l, series, i)}">${inner}</div>` : mark('div', i, 0, 'col-group', tip(l, series, i), inner);
     })}</div>

package/src/runtime/regions.ts

@@ -465,7 +465,7 @@ async function regionShell(ctx: PageContext, r: Region, hidden: Set<string>, bod
     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>
+      <div class="region-body"${scrollable(r)}>${body}</div>
       ${buttons ? html`<footer class="region-footer">${buttons}</footer>` : ''}
     </dialog>`;
 
@@ -473,17 +473,20 @@ async function regionShell(ctx: PageContext, r: Region, hidden: Set<string>, bod
   if (r.template === 'collapsible')
     return html`<section class="${cls}" id="R${r.id}"${staticAttr}${hiddenAttr} aria-labelledby="${titleId}">
       <details open><summary class="region-header">${header}</summary>
-        <div class="region-body">${body}</div>
+        <div class="region-body"${scrollable(r)}>${body}</div>
         ${!buttonsOnTop && buttons ? html`<footer class="region-footer">${buttons}</footer>` : ''}
       </details></section>`;
 
   return html`<section class="${cls}" id="R${r.id}"${staticAttr}${hiddenAttr}${r.title ? raw(` aria-labelledby="${titleId}"`) : ''}>
     ${r.title || (buttonsOnTop && buttons) ? html`<header class="region-header">${header}</header>` : ''}
-    <div class="region-body">${body}</div>
+    <div class="region-body"${scrollable(r)}>${body}</div>
     ${!buttonsOnTop && buttons ? html`<footer class="region-footer">${buttons}</footer>` : ''}
   </section>`;
 }
 
+/** (sprint 120) A body that scrolls (template option to-scroll) can be reached and scrolled from the keyboard. */
+const scrollable = (r: Region) => (r.template_options?.includes('to-scroll') ? raw(' tabindex="0"') : '');
+
 /**
  * (099) A region whose buttons have positions (APEX: Button Position): create, edit, change, copy, help and up in
  * the header; previous, close and delete at the left end of the bottom bar, next at its right end; the others
@@ -506,9 +509,9 @@ async function slottedShell(ctx: PageContext, r: Region, hidden: Set<string>, bo
   const header = html`<h2 id="${titleId}">${r.title}</h2>${top}`;
   if (r.template === 'collapsible')
     return html`<section class="${cls}" id="R${r.id}"${staticAttr}${hiddenAttr} aria-labelledby="${titleId}">
-      <details open><summary class="region-header">${header}</summary><div class="region-body">${body}</div>${footer}</details></section>`;
+      <details open><summary class="region-header">${header}</summary><div class="region-body"${scrollable(r)}>${body}</div>${footer}</details></section>`;
   return html`<section class="${cls}" id="R${r.id}"${staticAttr}${hiddenAttr}${r.title ? raw(` aria-labelledby="${titleId}"`) : ''}>
     ${r.title || top ? html`<header class="region-header">${header}</header>` : ''}
-    <div class="region-body">${body}</div>${footer}
+    <div class="region-body"${scrollable(r)}>${body}</div>${footer}
   </section>`;
 }