@xoong/cli 0.0.39 → 0.0.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xoong/cli",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "The xoong command line: sync (OpenAPI to typed operations), doctor, check (lint screens), dev, build (strict-CSP static output), render and i18n.",
   "type": "module",
   "bin": {
@@ -17,9 +17,9 @@
   "dependencies": {
     "parse5": "^8.1.0",
     "yaml": "^2.8.0",
-    "@xoong/server": "0.0.39",
-    "@xoong/core": "0.0.39",
-    "@xoong/i18n": "0.0.39"
+    "@xoong/server": "0.0.41",
+    "@xoong/core": "0.0.41",
+    "@xoong/i18n": "0.0.41"
   },
   "files": [
     "src"

package/src/build.js

@@ -10,6 +10,8 @@
  *   - TypeScript is stripped (erasable syntax only) and .ts files are written as .js;
  *   - `--base` prefixes root-absolute URLs for an app served under a path;
  *   - nothing is minified or bundled; every file is the one you wrote (readable in the browser's tools).
+ * HTML files that are not pages (partials, fixtures, drafts) are kept out of the start list with `--exclude <glob>` (repeatable) or `"build": { "exclude": [...] }` in
+ * xoong.config.json (paths relative to the root; see exclude.js). A file that a page references is still published.
  * What cannot be seen (a fetch() of a data file, an image named in JavaScript) is added with `--include <file-or-folder>`.
  */
 import { readFile, writeFile, mkdir, readdir, stat, copyFile, realpath } from 'node:fs/promises';
@@ -18,6 +20,7 @@ import { gzipSync } from 'node:zlib';
 import { parse } from 'parse5';
 import { findPackages, packagePath, stripTypes } from '@xoong/server/node';
 import { loadConfig } from './dev.js';
+import { excluder } from './exclude.js';
 import { buildImportMap } from '@xoong/server';
 
 const SCRIPT_EXT = new Set(['.js', '.mjs', '.ts', '.mts']);
@@ -28,10 +31,10 @@ const isLocal = (u) => !!u && !/^([a-z][a-z0-9+.-]*:|\/\/|#)/i.test(u);
 export const CSP = "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; font-src 'self'; base-uri 'none'; form-action 'self'";
 
 /**
- * @param {{ root?: string, out?: string, base?: string, include?: string[] }} [options]
+ * @param {{ root?: string, out?: string, base?: string, include?: string[], exclude?: string[] }} [options]
  * @returns {Promise<{ out: string, files: { path: string, bytes: number, gzip: number }[], warnings: string[], csp: string }>}
  */
-export async function build({ root = '.', out = 'dist', base = '', include = [], packages: extra } = {}) {
+export async function build({ root = '.', out = 'dist', base = '', include = [], exclude, packages: extra } = {}) {
   const rootDir = await realpath(resolve(root)); // real path: packages are found by theirs, so an app inside a symlinked package must compare equal
   // the output folder may not exist yet: resolve the part that does
   const realOut = async (p) => { try { return await realpath(p); } catch { const up = dirname(p); return up === p ? p : join(await realOut(up), basename(p)); } };
@@ -175,10 +178,12 @@ export async function build({ root = '.', out = 'dist', base = '', include = [],
 
   // pages first, then whatever they pull in
   const pages = [];
+  const skip = excluder([...(exclude ?? []), ...(((await loadConfig(rootDir)).build ?? {}).exclude ?? [])]);
   const walk = async (dir) => {
     for (const name of await readdir(dir)) {
       if (name === 'node_modules' || name.startsWith('.') || resolve(dir, name) === outDir) continue;
       const p = join(dir, name);
+      if (skip(relative(rootDir, p))) continue;
       if ((await stat(p)).isDirectory()) await walk(p); else if (/\.html?$/i.test(name)) pages.push(urlOf(p));
     }
   };

package/src/check.js

@@ -27,7 +27,8 @@
  *   XO252 <xo-form op> operation has no simple request fields to generate a form from
  */
 import { readFile, readdir, stat } from 'node:fs/promises';
-import { join, extname } from 'node:path';
+import { excluder } from './exclude.js';
+import { join, extname, relative } from 'node:path';
 import { parse } from 'parse5';
 import { nearest } from '@xoong/core/closest';
 import { XO_ATTRIBUTES, XO_ELEMENTS, XO_UI_ATTRIBUTES, XO_UI_ELEMENTS, XO_CONTROL_ATTRIBUTES, XO_CONTROL_ELEMENTS } from '@xoong/core/syntax';
@@ -317,9 +318,11 @@ export function checkScript(source, table, file = '<input>') {
 }
 
 /** Collect .html files from files and folders (skips node_modules and dot folders). */
-export async function collectHtml(paths) {
+export async function collectHtml(paths, { exclude } = {}) {
   const out = [];
+  const skip = excluder(exclude);
   const visit = async (p) => {
+    if (skip(relative('.', p))) return;
     const s = await stat(p);
     if (s.isDirectory()) {
       for (const name of await readdir(p)) if (!['node_modules', 'dist', 'build', 'coverage'].includes(name) && !name.startsWith('.')) await visit(join(p, name));
@@ -330,8 +333,8 @@ export async function collectHtml(paths) {
 }
 
 /** @returns {Promise<{ findings: Finding[], files: number }>} */
-export async function checkFiles(paths, table) {
-  const files = await collectHtml(paths);
+export async function checkFiles(paths, table, options = {}) {
+  const files = await collectHtml(paths, options);
   const findings = [];
   for (const file of files) {
     const source = await readFile(file, 'utf8');

package/src/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // @ts-check
 import { sync, doctor } from './commands.js';
-import { startDev, parseProxyFlags } from './dev.js';
+import { startDev, parseProxyFlags, loadConfig } from './dev.js';
 import { checkFiles, formatFindings } from './check.js';
 import { scaffold } from './scaffold.js';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
@@ -12,9 +12,9 @@ const HELP = `xoong <command>
   sync <openapi.json|yaml|url> [--out .xoong] [--hints hints.json]   generate operations.json and api.d.ts
   doctor <openapi.json|yaml|url> [--hints hints.json] [--all]   audit the OpenAPI document for xoong
   new <folder> --spec <openapi.json|yaml|url> [--title "My app"] [--link <xoong checkout>]   create a project with a first screen
-  check <file|folder>... [--operations .xoong/operations.json] [--format text|json]   check HTML screens
+  check <file|folder>... [--operations .xoong/operations.json] [--format text|json] [--exclude glob]...   check HTML screens
   render <page.html> --api <url> [--url /users/7] [--operations .xoong/operations.json] [--out file]   prerender a page (a route, with --url) with its data (needs @xoong/ssr)
-  build [--root .] [--out dist] [--base /admin] [--include path]...   static output for strict-CSP hosting (no import map, no inline code)
+  build [--root .] [--out dist] [--base /admin] [--include path]... [--exclude glob]...   static output for strict-CSP hosting (no import map, no inline code)
   i18n extract <html|js files or folders>... [--out catalogs/en.json]   list xo-t keys with their source text
   i18n check <catalog.json> --source <en.json>   missing keys, wrong placeholders, invalid messages
   dev [--root .] [--port 5173] [--proxy /api=http://localhost:8080] [--spa]   serve the app (static, proxy, .ts)
@@ -45,8 +45,9 @@ try {
     let table;
     try { table = JSON.parse(await readFile(opsFile, 'utf8')); } catch { throw new Error(`xoong: cannot read ${opsFile}. Run \`xoong sync <openapi>\` first, or pass --operations <file>`); }
     const format = flag('--format', 'text');
-    const targets = rest.filter((v, i) => !v.startsWith('--') && !['--operations', '--format'].includes(rest[i - 1]));
-    const { findings, files } = await checkFiles(targets, table);
+    const targets = rest.filter((v, i) => !v.startsWith('--') && !['--operations', '--format', '--exclude'].includes(rest[i - 1]));
+    const exclude = [...rest.flatMap((v, i) => (rest[i - 1] === '--exclude' ? [v] : [])), ...(((await loadConfig('.')).check ?? {}).exclude ?? [])];
+    const { findings, files } = await checkFiles(targets, table, { exclude });
     console.log(format === 'json' ? JSON.stringify(findings, null, 2) : formatFindings(findings, { files }));
     process.exitCode = findings.some((f) => f.level === 'error') ? 1 : 0;
   } else if (cmd === 'render' && rest[0] && flag('--api')) {
@@ -75,11 +76,12 @@ try {
     console.log(problems.length ? `${problems.length} problems` : 'ok');
     process.exitCode = problems.length ? 1 : 0;
   } else if (cmd === 'build') {
-    const unknown = rest.filter((v, i) => v.startsWith('-') && !['--root', '--out', '--base', '--include'].includes(v) && true);
-    if (unknown.length) throw new Error(`xoong build: unknown option ${unknown.join(', ')} (known: --root, --out, --base, --include)`);
+    const unknown = rest.filter((v, i) => v.startsWith('-') && !['--root', '--out', '--base', '--include', '--exclude'].includes(v) && true);
+    if (unknown.length) throw new Error(`xoong build: unknown option ${unknown.join(', ')} (known: --root, --out, --base, --include, --exclude)`);
     const { build, CSP } = await import('./build.js');
     const include = rest.flatMap((v, i) => (rest[i - 1] === '--include' ? [v] : []));
-    const r = await build({ root: flag('--root', '.'), out: flag('--out', 'dist'), base: flag('--base', ''), include });
+    const exclude = rest.flatMap((v, i) => (rest[i - 1] === '--exclude' ? [v] : []));
+    const r = await build({ root: flag('--root', '.'), out: flag('--out', 'dist'), base: flag('--base', ''), include, exclude });
     const total = r.files.reduce((n, f) => n + f.bytes, 0);
     const gz = r.files.reduce((n, f) => n + f.gzip, 0);
     console.log(`built ${r.files.length} files into ${r.out} (${(total / 1024).toFixed(1)} KB, ${(gz / 1024).toFixed(1)} KB gzip)`);

package/src/exclude.js

@@ -0,0 +1,21 @@
+// @ts-check
+/**
+ * A tiny glob for `--exclude` and `exclude` in xoong.config.json: paths relative to the project root, `/` separators.
+ *   `*` any characters except `/`   `**` any characters including `/`   `?` one character   a trailing `/` means the folder and everything in it.
+ * A pattern without a `/` matches that name at any depth (`*.draft.html`, `partials`). A folder that matches is skipped with all it holds.
+ * @param {string[] | undefined} patterns
+ * @returns {(relativePath: string) => boolean}
+ */
+export function excluder(patterns) {
+  const list = (patterns ?? []).map((p) => String(p).trim().replaceAll('\\', '/').replace(/^\.\//, '')).filter(Boolean);
+  const regexes = list.map((p) => {
+    if (p.endsWith('/')) p += '**';
+    if (!p.includes('/')) p = `**/${p}`;
+    const source = p.replace(/[.+^${}()|[\]]/g, '\\$&').replace(/\*\*\//g, '\u0000').replace(/\*\*/g, '\u0001').replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]').replace(/\u0000/g, '(?:.*/)?').replace(/\u0001/g, '.*');
+    return new RegExp(`^${source}$`);
+  });
+  return (relativePath) => {
+    const path = relativePath.replaceAll('\\', '/').replace(/^\.\//, '');
+    return regexes.some((r) => r.test(path));
+  };
+}

package/src/html-data.js

@@ -35,6 +35,7 @@ export const ATTRIBUTE_DOCS = {
   'xo-open': 'Open the <xo-dialog> matched by this selector, for example `#add`.',
   'xo-close': 'Close the <xo-dialog> this element is in.',
   'xo-menu-trigger': 'On the button of <xo-menu> that opens it (the first button when none is marked).',
+  'xo-consent-open': 'On any element: a click shows the <xo-consent> bar again (cookie settings).',
   'xo-tooltip': 'On any element: a short description shown on hover and focus (and hidden on Escape). It is a description, not the accessible name.',
   'xo-tab': 'On a section inside <xo-tabs>: the tab label. The section id is the tab key (its position when it has none).',
 };
@@ -50,7 +51,7 @@ export const ELEMENT_DOCS = {
   'xo-carousel': ['A row of slides you move through (@xoong/controls): cards, a banner, a gallery. The children are the slides; they sit in a scroll container with scroll snap, so swiping is native. WAI-ARIA carousel pattern, slides out of view are inert.', [['items', 'Slides visible at once (default 1; 1.15 lets the next peek). Also --xo-carousel-items in CSS.'], ['dots', 'A button per position; a slide with data-thumb="url" shows that picture instead.'], ['counter', 'Show "1 / 5".'], ['no-arrows', 'Hide the previous and next buttons.'], ['loop', 'Next at the end returns to the first slide.'], ['autoplay', 'Move on by itself every n milliseconds (pauses on hover and focus; off with reduced motion; adds a pause button).'], ['label', 'Accessible name of the carousel.']]],
   'xo-tags': ['A free-text tag input (@xoong/controls): type and press Enter or a comma to add a chip; Backspace removes the last. Value: an array of strings.', [['name', 'Form field path.'], ['placeholder', 'Hint text of the empty field.']]],
   'xo-richtext': ['A rich text editor form control (@xoong/richtext): toolbar, headings, bold, italic, lists, quote, links. The value is sanitised HTML (p, h2, h3, strong, em, ul, ol, li, blockquote, br, a, img). `xo-pick-media` (cancelable) asks the app for an image.', [['name', 'Form field path.'], ['tools', 'Space-separated tools: undo redo style bold italic underline ul ol quote link image (h2 as a toggle).'], ['toolbar', '`full` or `compact` forces a toolbar size; by default the editor\'s own width decides (full from 580px).'], ['media', 'Show the image tool; it fires xo-pick-media.'], ['placeholder', 'Hint text of the empty editor.'], ['label', 'Accessible name of the editor.'], ['maxlength', 'Maximum number of text characters.']]],
-  'xo-switch': ['One setting on or off (@xoong/controls, WAI-ARIA switch). A form control with a boolean value; `change` fires when the person toggles it.', [['name', 'Form field path.'], ['checked', 'Start on.'], ['label', 'Accessible name.'], ['size', '`sm` for the compact switch.'], ['busy', 'A save is running: aria-busy, clicks ignored.'], ['disabled', 'Not available.'], ['readonly', 'Shown but not changeable.']]],
+  'xo-switch': ['One setting on or off (@xoong/controls, WAI-ARIA switch). A form control with a boolean value; the text inside is the visible label (`label.xo-switch-row`); `change` fires when the person toggles it.', [['name', 'Form field path.'], ['checked', 'Start on.'], ['label', 'Accessible name.'], ['size', '`sm` for the compact switch.'], ['busy', 'A save is running: aria-busy, clicks ignored.'], ['disabled', 'Not available.'], ['readonly', 'Shown but not changeable.']]],
   'xo-date': ['A date field with a calendar popover (@xoong/controls). The value is ISO `YYYY-MM-DD` (with `range`: `{ start, end }`); the field shows the locale format and accepts typing.', [['name', 'Form field path.'], ['label', 'Accessible name.'], ['min', 'Earliest date, `YYYY-MM-DD`.'], ['max', 'Latest date, `YYYY-MM-DD`.'], ['range', 'Pick a start and an end (Clear and Apply in the calendar).'], ['week-start', 'First day of the week, 1 = Monday ... 7 = Sunday (default: the locale).'], ['placeholder', 'Hint text of the empty field.']]],
   'xo-time': ['A time of day as two selects, hour and minute (@xoong/controls). The value is `HH:mm` or empty.', [['name', 'Form field path.'], ['label', 'Accessible name of the group.'], ['step', 'Minutes between choices (default 5).'], ['min', 'Earliest time, `HH:mm`.'], ['max', 'Latest time, `HH:mm`.']]],
   'xo-slider': ['A number on a track (@xoong/controls, a native range input). `input` while dragging, `change` on release.', [['name', 'Form field path.'], ['label', 'Accessible name.'], ['min', 'Lowest value (default 0).'], ['max', 'Highest value (default 100).'], ['step', 'Step (default 1).'], ['labels', 'Comma-separated names of the stops, read by screen readers (`Low,Medium,High`).']]],
@@ -58,6 +59,13 @@ export const ELEMENT_DOCS = {
   'xo-password': ['A password field with a show/hide button (@xoong/controls).', [['name', 'Form field path.'], ['label', 'Accessible name.'], ['autocomplete', '`new-password` or `current-password`, for password managers.'], ['placeholder', 'Hint text of the empty field.']]],
   'xo-copy': ['A read-only value with a Copy button (@xoong/controls); fires `copied`.', [['value', 'The text to show and copy.'], ['label', 'Accessible name of the field.']]],
   'xo-image': ['An image that loads lazily, keeps its space (no layout jump), shows a placeholder while loading and a fallback on error (@xoong/controls). `data-state`: empty, loading, loaded, error.', [['src', 'The image URL (in an xo-view: `src="{cover.url}"`).'], ['alt', 'Required: the text for the image, or `alt=""` when it is decorative.'], ['width', 'Intrinsic width, reserves the space with height.'], ['height', 'Intrinsic height.'], ['ratio', 'Aspect ratio to reserve instead of width/height: `16/9`, `1.5`.'], ['fit', '`cover` (default) or `contain`.'], ['position', 'object-position, e.g. `top`.'], ['srcset', 'Responsive sources, passed to the img.'], ['sizes', 'Display sizes for srcset.'], ['priority', 'The image above the fold: loads at once with high priority (not lazy).'], ['loading', '`lazy` (default) or `eager`.'], ['fallback', 'A src to use once when the image fails.']]],
+  'xo-theme-toggle': ['A button that switches between the light and the dark theme (@xoong/controls): sets `data-theme` on <html>, saves the choice, follows the system until chosen. Fires `xo-theme-change`.', [['storage', 'localStorage key (default `xoong-theme`).']]],
+  'xo-accordion': ['A stack of native <details> as an accordion (@xoong/controls); `single` allows one open at a time; arrows move between summaries. Fires `xo-accordion-change`.', [['single', 'Only one section open at a time.']]],
+  'xo-popover': ['A small panel opened by a button (@xoong/controls): Escape or an outside click closes it and the focus returns to the trigger. `xo-popover-open` / `xo-popover-close`.', [['anchor', 'Selector of the trigger (default: the element before it).'], ['label', 'Accessible name of the panel.'], ['open', 'Open at the start.']]],
+  'xo-consent': ['A cookie consent bar that remembers the choice (@xoong/controls). The text inside is the message. Fires `xo-consent` with the choices.', [['categories', 'Comma-separated categories: `analytics,marketing`.'], ['storage', 'localStorage key (default `xoong-consent`).'], ['label', 'Accessible name of the bar.']]],
+  'xo-file': ['A file field with a drop zone (@xoong/controls). The value is a File (an array with `multiple`). Refused files fire `xo-file-reject`.', [['name', 'Form field path.'], ['label', 'Accessible name.'], ['accept', 'Allowed types: `image/*`, `.pdf`.'], ['max-size', 'Largest file: bytes or `2MB`.'], ['multiple', 'Several files.'], ['hint', 'Text under the prompt.']]],
+  'xo-command': ['A command palette (@xoong/controls): Ctrl/Cmd+K, type to filter, arrows, Enter. The children (links, buttons with `data-group`) are the commands. Fires `xo-command-run`.', [['shortcut', 'The key used with Ctrl/Cmd (default `k`).'], ['label', 'Accessible name of the dialog.']]],
+  'xo-chart': ['A bar or line chart drawn from data, with a table of the same numbers (@xoong/controls).', [['type', '`bar` (default) or `line`.'], ['label', 'Accessible name of the chart.'], ['data', 'JSON: `[{"label":"Mon","value":12}]` or `[12, 18]`; or set `el.rows`.'], ['unit', 'Appended to values: `k`, `%`.'], ['heading', 'Label column of the table.'], ['value-heading', 'Value column of the table.']]],
   'xo-dialog': ['A modal on the native <dialog>. Open it with xo-open, close it with xo-close or by submitting a form inside.', []],
 };