@mark1russell7/site-pages 0.1.8 → 0.1.10

package/README.md

@@ -66,9 +66,10 @@ A view fails for each of these problems:
 - The page shows no text.
 - The page writes a console error, or a script throws an exception.
 - A request to the site fails, or gets a status of 400 or more.
+- A script or a style sheet does not load, from any origin. An example is a module script that imports `node:perf_hooks`.
 - A check of the probe fails, or the probe makes no check.
 
-The probe is a JavaScript file. Its code is the body of an async function. These functions are available:
+The probe is a JavaScript file or a TypeScript file (`.ts`, `.mts` or `.cts`). Its code is the body of an async function. These functions are available:
 
 | Function | Operation |
 | --- | --- |
@@ -82,6 +83,8 @@ type("#editor", "Utilize the cache.");
 check("the linter finds a word", await until(() => $$(".finding").length === 1), $$(".finding").length);
 ```
 
+For a TypeScript probe, the check removes the types and the line `export {};` before it runs the probe. Thus the typecheck of the site examines the probe, and the site needs no build step for it. Each line stays at its position, so the line of an error is the line of the source. Declare the functions of the table with `declare const`, and add `export {};` at the end, so the file is a module. `probeScript` does the same operation for a script of your own.
+
 The check runs the probe on the first page, in the first scheme, at each width. The folder of `--shots` gets a screenshot of each view, `report.json` and `summary.md`. The exit code is 0 when each view passes, 1 when a view fails, and 2 for an incorrect command line.
 
 The check finds a browser in this order: `--browser`, `$SITE_CHECK_BROWSER`, the newest Chromium of Playwright, and then Chrome or Edge. The folder `src/check` imports only Node.js. Thus Node.js 22.18 or later can start `src/check/main.ts` with no install. The workflow `reusable-pages.yml` of the template uses it this way.
@@ -294,6 +297,39 @@ The class sets `overflow-x: auto` and the background color of the box. Set `--sc
 }
 ```
 
+## The page helpers
+
+The entry `@mark1russell7/site-pages/chrome` has small helpers for the script of a page. It imports no Node.js module, so a site can bundle it for the browser. The package root does not export these helpers. Thus a Node.js program that imports the root gets no DOM types.
+
+| Function | Operation |
+| --- | --- |
+| `h(tag, attrs, ...children)` | Makes an element. The attribute `class` sets the class name. `false`, `null` and `undefined` give no attribute and no child. |
+| `byId(id)` | Gives the element with the ID. It throws when the page has no such element. |
+| `setupTheme(button, storageKey)` | Makes a theme button: auto, light, dark, in turn. It sets `data-theme` on the `html` element and keeps the choice in `localStorage`. |
+| `currentTheme()`, `nextTheme(storageKey)`, `applyTheme(theme, storageKey)` | Read the theme, set the next theme, or set one theme. A site with its own button, for example a React component, uses them. |
+| `copyText(button, text, options)` | Copies a text. The button shows "Copied" or "Copy failed" for 1600 ms. |
+| `copyToClipboard(text)` | Copies a text with the Clipboard API, else with `document.execCommand`. It gives `true` after a copy. |
+
+```ts
+import { byId, copyText, h, setupTheme } from "@mark1russell7/site-pages/chrome";
+
+setupTheme(byId<HTMLButtonElement>("theme"), "my-site-theme");
+const copy = h("button", { type: "button", class: "copy" }, "Copy");
+copy.addEventListener("click", () => void copyText(copy, "pnpm add my-package"));
+byId("install").append(copy);
+```
+
+The theme `auto` removes `data-theme`, and the CSS of the site then obeys `prefers-color-scheme`. Put this script in the `head` of the page, with the same key. It sets the theme before the first paint, so a dark page does not show white for a moment:
+
+```html
+<script>
+  try {
+    const t = localStorage.getItem("my-site-theme");
+    if (t === "light" || t === "dark") document.documentElement.dataset.theme = t;
+  } catch {}
+</script>
+```
+
 ## A GitHub Pages workflow
 
 This workflow builds the site, adds the two pages, and deploys. It also starts every 3 hours, so the status page stays current without a push. A scheduled run builds the newest commit of `main` that passed CI.

package/build/{build-CD2wc7Yl.js → build-xJqNIzdO.js}

@@ -1,3 +1,4 @@
+import { stripTypeScriptTypes } from "node:module";
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, posix, resolve } from "node:path";
@@ -2336,6 +2337,21 @@ function renderStatusPage(data, options) {
 		script: STATUS_SCRIPT
 	}, options);
 }
+// src/check/probe.ts
+/**
+* The probe of `site-pages check` in TypeScript. A probe source can be TypeScript, so the typecheck of the site examines it.
+* The check removes its types before it runs the probe, so a site needs no build step for its probe.
+*/
+/** A probe file in TypeScript: `.ts`, `.mts` or `.cts`. */
+const TYPESCRIPT_PROBE = /\.[cm]?ts$/i;
+/**
+* This function gives the JavaScript of a probe in TypeScript. It removes the types, and the line `export {};` that makes the
+* file a module for the typecheck. Each line stays at its position, so the line of an error is the line of the source. Syntax
+* that is not only types (an `enum`, a `namespace`) causes an error.
+*/
+function probeScript(source) {
+	return stripTypeScriptTypes(source, { mode: "strip" }).replace(/^export \{\s*\};?[ \t]*$/m, "");
+}
 // src/build.ts
 /**
 * The `site-pages build` command. It reads the sources. Then it writes the JSON data and the two
@@ -2532,6 +2548,6 @@ async function runCli(argv, io) {
 		throw error;
 	}
 }
-export { npmPublishTimes as $, RoadmapParseError as A, statusClassOf as B, longDate as C, inlineMarkdown as D, escapeHtml as E, parseRoadmap as F, readReleases as G, ReleaseDataError as H, plainText as I, headCommit as J, globFiles as K, readStatusBoard as L, buildStatusBoard as M, linksOf as N, safeUrl as O, markdownTables as P, NPM_REGISTRY as Q, roadmapItems as R, dayRange as S, utcDay as T, mergeReleases as U, DEFAULT_CHANGELOGS as V, readChangelogs as W, isShallow as X, headingDate as Y, originRepository as Z, oldestFirst as _, runCli as a, firstSentence as at, BASE_CSS as b, openGroups as c, releaseBodyEntries as ct, slugOf as d, parseVersion as dt, GITHUB_API as et, statusLead as f, versionOfTag as ft, laneCenter as g, renderReleasesPage as h, parseBuildArgs as i, githubReleases as it, STATUS_CLASSES as j, OPEN_CLASSES as k, renderStatusPage as l, compareVersions as lt, releasesLead as m, UsageError as n, checkStateOf as nt, STATUS_SCRIPT as o, headingAnchor as ot, RELEASES_SCRIPT as p, gitTagDates as q, build as r, githubOpenWork as rt, classCounts as s, parseChangelog as st, HELP as t, GITHUB_GRAPHQL as tt, sectionsOf as u, kindOf as ut, releaseSummary as v, shortDate as w, pageShell as x, timelineLayout as y, splitRow as z };
+export { originRepository as $, safeUrl as A, roadmapItems as B, pageShell as C, utcDay as D, shortDate as E, linksOf as F, mergeReleases as G, statusClassOf as H, markdownTables as I, globFiles as J, readChangelogs as K, parseRoadmap as L, RoadmapParseError as M, STATUS_CLASSES as N, escapeHtml as O, buildStatusBoard as P, isShallow as Q, plainText as R, BASE_CSS as S, longDate as T, DEFAULT_CHANGELOGS as U, splitRow as V, ReleaseDataError as W, headCommit as X, gitTagDates as Y, headingDate as Z, renderReleasesPage as _, runCli as a, githubOpenWork as at, releaseSummary as b, STATUS_SCRIPT as c, headingAnchor as ct, renderStatusPage as d, compareVersions as dt, NPM_REGISTRY as et, sectionsOf as f, kindOf as ft, releasesLead as g, RELEASES_SCRIPT as h, parseBuildArgs as i, checkStateOf as it, OPEN_CLASSES as j, inlineMarkdown as k, classCounts as l, parseChangelog as lt, statusLead as m, versionOfTag as mt, UsageError as n, GITHUB_API as nt, TYPESCRIPT_PROBE as o, githubReleases as ot, slugOf as p, parseVersion as pt, readReleases as q, build as r, GITHUB_GRAPHQL as rt, probeScript as s, firstSentence as st, HELP as t, npmPublishTimes as tt, openGroups as u, releaseBodyEntries as ut, laneCenter as v, dayRange as w, timelineLayout as x, oldestFirst as y, readStatusBoard as z };
 
-//# sourceMappingURL=build-CD2wc7Yl.js.map
+//# sourceMappingURL=build-xJqNIzdO.js.map