@mark1russell7/site-pages 0.1.9 → 0.1.10

package/README.md

@@ -297,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/chrome.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The small helpers of a page in the browser: the element helper, the element lookup, the theme
+ * button and the copy button. This module imports no Node.js module, so a site can bundle it.
+ * Import it from `@mark1russell7/site-pages/chrome`, because the package root also has Node.js code.
+ */
+/** A child of `h`: a node or a text. The values `null`, `undefined` and `false` give no child. */
+export type Child = Node | string | null | undefined | false;
+/** The value of an attribute of `h`. The value `true` gives an empty attribute. */
+export type AttributeValue = string | number | boolean | null | undefined;
+/**
+ * This function makes an element with attributes and children. An attribute with the value
+ * `false`, `null` or `undefined` is not set. The attribute `class` sets the class name.
+ */
+export declare function h<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Readonly<Record<string, AttributeValue>>, ...children: readonly (Child | readonly Child[])[]): HTMLElementTagNameMap[K];
+/**
+ * This function gives the element with the ID. The page has each ID that the code asks for. Thus
+ * a missing ID is an error of the page, and the function throws an `Error`.
+ */
+export declare function byId<T extends HTMLElement = HTMLElement>(id: string): T;
+/** The themes of the theme button, in the sequence of the clicks. `auto` follows the setting of the system. */
+export declare const THEMES: readonly ["auto", "light", "dark"];
+/** A theme of the page. */
+export type Theme = (typeof THEMES)[number];
+/**
+ * This function gives the theme of the page from the attribute `data-theme` of the `html` element.
+ * Without the attribute, or with another value, the theme is `auto`.
+ */
+export declare function currentTheme(): Theme;
+/**
+ * This function sets the theme of the page, and keeps it in `localStorage` under `storageKey`.
+ * The theme `auto` removes the attribute `data-theme` and the stored value.
+ */
+export declare function applyTheme(theme: Theme, storageKey: string): void;
+/** This function sets the next theme after the current theme (auto, light, dark, auto), and gives it. */
+export declare function nextTheme(storageKey: string): Theme;
+/**
+ * This function makes a theme button. Each click sets the next theme. The text of the button is
+ * "Theme: auto", "Theme: light" or "Theme: dark", and its `aria-label` tells the same theme.
+ *
+ * @remarks Before the first paint, a script in the `head` of the page reads `storageKey` from
+ * `localStorage` and sets `data-theme`. Thus a dark page does not show white for a moment.
+ */
+export declare function setupTheme(button: HTMLButtonElement, storageKey: string): void;
+/**
+ * This function copies a text to the clipboard, and gives `true` when the copy is done. It uses
+ * the Clipboard API. When that API is not available or refuses, it uses `document.execCommand`.
+ */
+export declare function copyToClipboard(text: string): Promise<boolean>;
+/** The options of `copyText`. */
+export interface CopyTextOptions {
+  /** The text of the button after a copy. The default is "Copied". */
+  readonly copied?: string;
+  /** The text of the button after a failure. The default is "Copy failed". */
+  readonly failed?: string;
+  /** The time in milliseconds until the button shows its label again. The default is 1600. */
+  readonly ms?: number;
+}
+/**
+ * This function copies a text to the clipboard with `copyToClipboard`. The button tells the result
+ * for a short time, then it shows its label again. The function gives the result of the copy.
+ */
+export declare function copyText(button: HTMLButtonElement, text: string, options?: CopyTextOptions): Promise<boolean>;
+//# sourceMappingURL=chrome.d.ts.map

package/build/chrome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chrome.d.ts","names":[],"sources":["../src/chrome.ts"],"mappings":";;;;;;YAQY,QAAQ;;YAGR;;;;;wBAMI,EAAE,gBAAgB,uBAChC,KAAK,GACL,QAAO,SAAS,eAAe,qBAC5B,oBAAoB,iBAAiB,aACvC,sBAAsB;;;;;wBAkBT,KAAK,UAAU,cAAc,aAAa,aAAa;;qBAO1D;;YAGD,gBAAgB;;;;;wBAMZ,gBAAgB;;;;;wBAShB,WAAW,OAAO,OAAO;;wBAazB,UAAU,qBAAqB;;;;;;;;wBAa/B,WAAW,QAAQ,mBAAmB;;;;;wBAahC,gBAAgB,eAAe;;iBA0BpC;;WAEN;;WAEA;;WAEA;;;;;;wBAOW,SAAS,QAAQ,mBAAmB,cAAc,UAAS,kBAAuB"}

package/build/chrome.js

@@ -0,0 +1,117 @@
+// src/chrome.ts
+/**
+* This function makes an element with attributes and children. An attribute with the value
+* `false`, `null` or `undefined` is not set. The attribute `class` sets the class name.
+*/
+function h(tag, attrs = {}, ...children) {
+	const el = document.createElement(tag);
+	for (const [name, value] of Object.entries(attrs)) {
+		if (value === false || value === null || value === void 0) continue;
+		if (name === "class") el.className = String(value);
+		else el.setAttribute(name, value === true ? "" : String(value));
+	}
+	for (const child of children.flat()) {
+		if (child === null || child === void 0 || child === false) continue;
+		el.append(child);
+	}
+	return el;
+}
+/**
+* This function gives the element with the ID. The page has each ID that the code asks for. Thus
+* a missing ID is an error of the page, and the function throws an `Error`.
+*/
+function byId(id) {
+	const el = document.getElementById(id);
+	if (el === null) throw new Error(`The page has no element "${id}".`);
+	return el;
+}
+/** The themes of the theme button, in the sequence of the clicks. `auto` follows the setting of the system. */
+const THEMES = [
+	"auto",
+	"light",
+	"dark"
+];
+/**
+* This function gives the theme of the page from the attribute `data-theme` of the `html` element.
+* Without the attribute, or with another value, the theme is `auto`.
+*/
+function currentTheme() {
+	const theme = document.documentElement.dataset["theme"];
+	return theme === "light" || theme === "dark" ? theme : "auto";
+}
+/**
+* This function sets the theme of the page, and keeps it in `localStorage` under `storageKey`.
+* The theme `auto` removes the attribute `data-theme` and the stored value.
+*/
+function applyTheme(theme, storageKey) {
+	const root = document.documentElement;
+	if (theme === "auto") delete root.dataset["theme"];
+	else root.dataset["theme"] = theme;
+	try {
+		if (theme === "auto") localStorage.removeItem(storageKey);
+		else localStorage.setItem(storageKey, theme);
+	} catch {}
+}
+/** This function sets the next theme after the current theme (auto, light, dark, auto), and gives it. */
+function nextTheme(storageKey) {
+	const next = THEMES[(THEMES.indexOf(currentTheme()) + 1) % THEMES.length] ?? "auto";
+	applyTheme(next, storageKey);
+	return next;
+}
+/**
+* This function makes a theme button. Each click sets the next theme. The text of the button is
+* "Theme: auto", "Theme: light" or "Theme: dark", and its `aria-label` tells the same theme.
+*
+* @remarks Before the first paint, a script in the `head` of the page reads `storageKey` from
+* `localStorage` and sets `data-theme`. Thus a dark page does not show white for a moment.
+*/
+function setupTheme(button, storageKey) {
+	const show = (theme) => {
+		button.textContent = `Theme: ${theme}`;
+		button.setAttribute("aria-label", `Color theme: ${theme}. Select to change.`);
+	};
+	show(currentTheme());
+	button.addEventListener("click", () => show(nextTheme(storageKey)));
+}
+/**
+* This function copies a text to the clipboard, and gives `true` when the copy is done. It uses
+* the Clipboard API. When that API is not available or refuses, it uses `document.execCommand`.
+*/
+async function copyToClipboard(text) {
+	try {
+		await navigator.clipboard.writeText(text);
+		return true;
+	} catch {}
+	try {
+		const area = document.createElement("textarea");
+		area.value = text;
+		area.setAttribute("readonly", "");
+		area.style.position = "fixed";
+		area.style.opacity = "0";
+		document.body.append(area);
+		area.select();
+		try {
+			return document.execCommand("copy");
+		} finally {
+			area.remove();
+		}
+	} catch {
+		return false;
+	}
+}
+/**
+* This function copies a text to the clipboard with `copyToClipboard`. The button tells the result
+* for a short time, then it shows its label again. The function gives the result of the copy.
+*/
+async function copyText(button, text, options = {}) {
+	const label = button.textContent;
+	const ok = await copyToClipboard(text);
+	button.textContent = ok ? options.copied ?? "Copied" : options.failed ?? "Copy failed";
+	window.setTimeout(() => {
+		button.textContent = label;
+	}, options.ms ?? 1600);
+	return ok;
+}
+export { THEMES, applyTheme, byId, copyText, copyToClipboard, currentTheme, h, nextTheme, setupTheme };
+
+//# sourceMappingURL=chrome.js.map

package/build/chrome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chrome.js","names":[],"sources":["../src/chrome.ts"],"sourcesContent":["/// <reference lib=\"dom\" />\n/**\n * The small helpers of a page in the browser: the element helper, the element lookup, the theme\n * button and the copy button. This module imports no Node.js module, so a site can bundle it.\n * Import it from `@mark1russell7/site-pages/chrome`, because the package root also has Node.js code.\n */\n\n/** A child of `h`: a node or a text. The values `null`, `undefined` and `false` give no child. */\nexport type Child = Node | string | null | undefined | false;\n\n/** The value of an attribute of `h`. The value `true` gives an empty attribute. */\nexport type AttributeValue = string | number | boolean | null | undefined;\n\n/**\n * This function makes an element with attributes and children. An attribute with the value\n * `false`, `null` or `undefined` is not set. The attribute `class` sets the class name.\n */\nexport function h<K extends keyof HTMLElementTagNameMap>(\n  tag: K,\n  attrs: Readonly<Record<string, AttributeValue>> = {},\n  ...children: readonly (Child | readonly Child[])[]\n): HTMLElementTagNameMap[K] {\n  const el = document.createElement(tag);\n  for (const [name, value] of Object.entries(attrs)) {\n    if (value === false || value === null || value === undefined) continue;\n    if (name === \"class\") el.className = String(value);\n    else el.setAttribute(name, value === true ? \"\" : String(value));\n  }\n  for (const child of children.flat()) {\n    if (child === null || child === undefined || child === false) continue;\n    el.append(child);\n  }\n  return el;\n}\n\n/**\n * This function gives the element with the ID. The page has each ID that the code asks for. Thus\n * a missing ID is an error of the page, and the function throws an `Error`.\n */\nexport function byId<T extends HTMLElement = HTMLElement>(id: string): T {\n  const el = document.getElementById(id);\n  if (el === null) throw new Error(`The page has no element \"${id}\".`);\n  return el as T;\n}\n\n/** The themes of the theme button, in the sequence of the clicks. `auto` follows the setting of the system. */\nexport const THEMES: readonly [\"auto\", \"light\", \"dark\"] = [\"auto\", \"light\", \"dark\"];\n\n/** A theme of the page. */\nexport type Theme = (typeof THEMES)[number];\n\n/**\n * This function gives the theme of the page from the attribute `data-theme` of the `html` element.\n * Without the attribute, or with another value, the theme is `auto`.\n */\nexport function currentTheme(): Theme {\n  const theme = document.documentElement.dataset[\"theme\"];\n  return theme === \"light\" || theme === \"dark\" ? theme : \"auto\";\n}\n\n/**\n * This function sets the theme of the page, and keeps it in `localStorage` under `storageKey`.\n * The theme `auto` removes the attribute `data-theme` and the stored value.\n */\nexport function applyTheme(theme: Theme, storageKey: string): void {\n  const root = document.documentElement;\n  if (theme === \"auto\") delete root.dataset[\"theme\"];\n  else root.dataset[\"theme\"] = theme;\n  try {\n    if (theme === \"auto\") localStorage.removeItem(storageKey);\n    else localStorage.setItem(storageKey, theme);\n  } catch {\n    // A browser with no storage keeps the theme until the page closes.\n  }\n}\n\n/** This function sets the next theme after the current theme (auto, light, dark, auto), and gives it. */\nexport function nextTheme(storageKey: string): Theme {\n  const next = THEMES[(THEMES.indexOf(currentTheme()) + 1) % THEMES.length] ?? \"auto\";\n  applyTheme(next, storageKey);\n  return next;\n}\n\n/**\n * This function makes a theme button. Each click sets the next theme. The text of the button is\n * \"Theme: auto\", \"Theme: light\" or \"Theme: dark\", and its `aria-label` tells the same theme.\n *\n * @remarks Before the first paint, a script in the `head` of the page reads `storageKey` from\n * `localStorage` and sets `data-theme`. Thus a dark page does not show white for a moment.\n */\nexport function setupTheme(button: HTMLButtonElement, storageKey: string): void {\n  const show = (theme: Theme): void => {\n    button.textContent = `Theme: ${theme}`;\n    button.setAttribute(\"aria-label\", `Color theme: ${theme}. Select to change.`);\n  };\n  show(currentTheme());\n  button.addEventListener(\"click\", () => show(nextTheme(storageKey)));\n}\n\n/**\n * This function copies a text to the clipboard, and gives `true` when the copy is done. It uses\n * the Clipboard API. When that API is not available or refuses, it uses `document.execCommand`.\n */\nexport async function copyToClipboard(text: string): Promise<boolean> {\n  try {\n    await navigator.clipboard.writeText(text);\n    return true;\n  } catch {\n    // An insecure page has no Clipboard API, and a browser can refuse the copy. The old command is the fallback.\n  }\n  try {\n    const area = document.createElement(\"textarea\");\n    area.value = text;\n    area.setAttribute(\"readonly\", \"\");\n    area.style.position = \"fixed\";\n    area.style.opacity = \"0\";\n    document.body.append(area);\n    area.select();\n    try {\n      return document.execCommand(\"copy\");\n    } finally {\n      area.remove();\n    }\n  } catch {\n    return false;\n  }\n}\n\n/** The options of `copyText`. */\nexport interface CopyTextOptions {\n  /** The text of the button after a copy. The default is \"Copied\". */\n  readonly copied?: string;\n  /** The text of the button after a failure. The default is \"Copy failed\". */\n  readonly failed?: string;\n  /** The time in milliseconds until the button shows its label again. The default is 1600. */\n  readonly ms?: number;\n}\n\n/**\n * This function copies a text to the clipboard with `copyToClipboard`. The button tells the result\n * for a short time, then it shows its label again. The function gives the result of the copy.\n */\nexport async function copyText(button: HTMLButtonElement, text: string, options: CopyTextOptions = {}): Promise<boolean> {\n  const label = button.textContent;\n  const ok = await copyToClipboard(text);\n  button.textContent = ok ? (options.copied ?? \"Copied\") : (options.failed ?? \"Copy failed\");\n  window.setTimeout(() => {\n    button.textContent = label;\n  }, options.ms ?? 1600);\n  return ok;\n}\n"],"mappings":";;;;;AAiBA,SAAgB,EACd,KACA,QAAkD,CAAC,GACnD,GAAG,UACuB;CAC1B,MAAM,KAAK,SAAS,cAAc,GAAG;CACrC,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,KAAK,GAAG;EACjD,IAAI,UAAU,SAAS,UAAU,QAAQ,UAAU,KAAA,GAAW;EAC9D,IAAI,SAAS,SAAS,GAAG,YAAY,OAAO,KAAK;OAC5C,GAAG,aAAa,MAAM,UAAU,OAAO,KAAK,OAAO,KAAK,CAAC;CAChE;CACA,KAAK,MAAM,SAAS,SAAS,KAAK,GAAG;EACnC,IAAI,UAAU,QAAQ,UAAU,KAAA,KAAa,UAAU,OAAO;EAC9D,GAAG,OAAO,KAAK;CACjB;CACA,OAAO;AACT;;;;;AAMA,SAAgB,KAA0C,IAAe;CACvE,MAAM,KAAK,SAAS,eAAe,EAAE;CACrC,IAAI,OAAO,MAAM,MAAM,IAAI,MAAM,4BAA4B,GAAG,GAAG;CACnE,OAAO;AACT;;AAGA,MAAa,SAA6C;CAAC;CAAQ;CAAS;AAAM;;;;;AASlF,SAAgB,eAAsB;CACpC,MAAM,QAAQ,SAAS,gBAAgB,QAAQ;CAC/C,OAAO,UAAU,WAAW,UAAU,SAAS,QAAQ;AACzD;;;;;AAMA,SAAgB,WAAW,OAAc,YAA0B;CACjE,MAAM,OAAO,SAAS;CACtB,IAAI,UAAU,QAAQ,OAAO,KAAK,QAAQ;MACrC,KAAK,QAAQ,WAAW;CAC7B,IAAI;EACF,IAAI,UAAU,QAAQ,aAAa,WAAW,UAAU;OACnD,aAAa,QAAQ,YAAY,KAAK;CAC7C,QAAQ,CAER;AACF;;AAGA,SAAgB,UAAU,YAA2B;CACnD,MAAM,OAAO,QAAQ,OAAO,QAAQ,aAAa,CAAC,IAAI,KAAK,OAAO,WAAW;CAC7E,WAAW,MAAM,UAAU;CAC3B,OAAO;AACT;;;;;;;;AASA,SAAgB,WAAW,QAA2B,YAA0B;CAC9E,MAAM,QAAQ,UAAuB;EACnC,OAAO,cAAc,UAAU;EAC/B,OAAO,aAAa,cAAc,gBAAgB,MAAM,oBAAoB;CAC9E;CACA,KAAK,aAAa,CAAC;CACnB,OAAO,iBAAiB,eAAe,KAAK,UAAU,UAAU,CAAC,CAAC;AACpE;;;;;AAMA,eAAsB,gBAAgB,MAAgC;CACpE,IAAI;EACF,MAAM,UAAU,UAAU,UAAU,IAAI;EACxC,OAAO;CACT,QAAQ,CAER;CACA,IAAI;EACF,MAAM,OAAO,SAAS,cAAc,UAAU;EAC9C,KAAK,QAAQ;EACb,KAAK,aAAa,YAAY,EAAE;EAChC,KAAK,MAAM,WAAW;EACtB,KAAK,MAAM,UAAU;EACrB,SAAS,KAAK,OAAO,IAAI;EACzB,KAAK,OAAO;EACZ,IAAI;GACF,OAAO,SAAS,YAAY,MAAM;EACpC,UAAU;GACR,KAAK,OAAO;EACd;CACF,QAAQ;EACN,OAAO;CACT;AACF;;;;;AAgBA,eAAsB,SAAS,QAA2B,MAAc,UAA2B,CAAC,GAAqB;CACvH,MAAM,QAAQ,OAAO;CACrB,MAAM,KAAK,MAAM,gBAAgB,IAAI;CACrC,OAAO,cAAc,KAAM,QAAQ,UAAU,WAAa,QAAQ,UAAU;CAC5E,OAAO,iBAAiB;EACtB,OAAO,cAAc;CACvB,GAAG,QAAQ,MAAM,IAAI;CACrB,OAAO;AACT"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/site-pages",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "A release timeline page and a live status page for the site of a GitHub repository: JSON data and standalone HTML, made at deploy time.",
   "keywords": [
     "github-pages",
@@ -31,6 +31,10 @@
       "types": "./build/index.d.ts",
       "import": "./build/index.js"
     },
+    "./chrome": {
+      "types": "./build/chrome.d.ts",
+      "import": "./build/chrome.js"
+    },
     "./scroll-cue.css": "./styles/scroll-cue.css",
     "./package.json": "./package.json"
   },