@arraypress/extension-kit 1.12.0 → 1.13.0

package/README.md

@@ -713,6 +713,7 @@ A list with an Add button needs every key but `optionsRemoveLabel`; one with an
 | `testBuildDir(root, name)` | `.test-builds/<name>`, or under `$EXTENSION_TEST_BUILDS` (to test another build, or run two side by side). |
 | `storeFrame` | Store screenshots: `canvas`, `windowChrome` (and `windowChromeSvg`, from `frame/window.js`), `geometry`, `letterIcon`, `cursor`, `THEMES`, `W`×`H`. |
 | `storeShots({browser, dir, toolbarIcon})`, `storeShotHtml(shot)`, `contextMenuHtml(menu)`, `pngUrl(png)`, `PANEL_W`, `PANEL_HEADER_H` | The family's store screenshots in one style: a caption in sentence case over Chrome's light window with the extension pinned in the toolbar, real captures (taken at 2×) inside; what headless Chrome can't capture composed around the real extension UI: the popup page hung from the pressed toolbar button, the side panel page beside the page under a header with the extension's name, the right-click menu drawn as macOS draws Chrome's (the extension's real titles). `shoot(file, shot)` writes a 1280×800 PNG. |
+| `storePromoTile({browser, extension, file, line, glow?, name?, icon?})`, `promoTileHtml(tile)`, `PROMO_W`, `PROMO_H` | The store's small promo tile (440×280) in the family's one style: the extension's `icons/icon.svg` with a soft glow (its colour `glow`, default Chrome's blue), its English `extShortName` and one short `line`, on the store screenshots' light background. Writes the PNG and returns its path. |
 | `placeholderWarning`, `repositoryReminder`, `printReleaseChecks` | See About links. |
 | `findDisallowedClones({runJscpd})` | Run jscpd and return clones `.jscpd-allowlist.json` doesn't cover (the `extension-kit duplication` command). |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/extension-kit",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Shared pieces for Chrome extensions: Chrome's own page styles and components, a Chrome Sync settings store, the light/dark toolbar glyph, Chrome's on-device model, content-script helpers, About links, and build and test helpers.",
   "type": "module",
   "main": "src/index.js",

package/src/build/index.d.ts

@@ -6,6 +6,7 @@
  */
 export { clonesFromReport, disallowedClones, findDisallowedClones } from './duplication.js';
 export { placeholderWarning, printReleaseChecks, repositoryReminder } from './release-checks.js';
+export { PROMO_H, PROMO_W, promoTileHtml, storePromoTile } from './promo-tile.js';
 export * as storeFrame from './store-frame.js';
 export { PANEL_HEADER_H, PANEL_W, contextMenuHtml, pngUrl, storeShotHtml, storeShots } from './store-shots.js';
 export { HOOK_FILE, PANEL_OPENER, TEST_BUILDS_ENV, buildTestCopy, testBuildDir } from './test-build.js';

package/src/build/index.js

@@ -7,6 +7,7 @@
 
 export { clonesFromReport, disallowedClones, findDisallowedClones } from './duplication.js';
 export { placeholderWarning, printReleaseChecks, repositoryReminder } from './release-checks.js';
+export { PROMO_H, PROMO_W, promoTileHtml, storePromoTile } from './promo-tile.js';
 export * as storeFrame from './store-frame.js';
 export { PANEL_HEADER_H, PANEL_W, contextMenuHtml, pngUrl, storeShotHtml, storeShots } from './store-shots.js';
 export { HOOK_FILE, PANEL_OPENER, TEST_BUILDS_ENV, buildTestCopy, testBuildDir } from './test-build.js';

package/src/build/promo-tile.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The Chrome Web Store's small promo tile (440×280) for the whole family, in one style: the
+ * extension's icon (drawn from its SVG, so it's sharp at any size) with a soft glow, its name
+ * and one short line, on the store screenshots' light background.
+ *
+ * {@link promoTileHtml} lays it out (pure); {@link storePromoTile} reads the icon and name from
+ * the extension folder and writes the PNG.
+ *
+ * @module build/promo-tile
+ */
+/** The promo tile's width. */
+export declare const PROMO_W = 440;
+/** The promo tile's height. */
+export declare const PROMO_H = 280;
+export type PromoTile = {
+    /**
+     * The icon: SVG markup, or an image's URL (a data: URL, say).
+     */
+    icon: string;
+    /**
+     * The extension's name (`extShortName`).
+     */
+    name: string;
+    /**
+     * One short line under it, sentence case (“Prices in your currency”).
+     */
+    line: string;
+    /**
+     * The colour of the glow under the icon, any CSS colour: the icon's own (default Chrome's blue).
+     */
+    glow?: string;
+};
+/**
+ * One promo tile.
+ *
+ * @typedef {object} PromoTile
+ * @property {string} icon The icon: SVG markup, or an image's URL (a data: URL, say).
+ * @property {string} name The extension's name (`extShortName`).
+ * @property {string} line One short line under it, sentence case (“Prices in your currency”).
+ * @property {string} [glow] The colour of the glow under the icon, any CSS colour: the icon's own (default Chrome's blue).
+ */
+/**
+ * The tile's page: the icon, the name and the line, centred, at 440×280.
+ *
+ * @param {PromoTile} tile - What it shows.
+ * @returns {string} A whole HTML document.
+ * @example
+ * promoTileHtml({ icon: svg, name: 'Better Prices', line: 'Prices in your currency', glow: '#146c2e' });
+ */
+export declare function promoTileHtml({ icon, name, line, glow }: PromoTile): string;
+/**
+ * Write an extension's promo tile: its `icons/icon.svg` and English `extShortName` (unless
+ * `icon` or `name` is given), drawn by {@link promoTileHtml} in a page of the given browser.
+ *
+ * @param {object} options - What and where.
+ * @param {import('playwright').Browser | import('playwright').BrowserContext} options.browser - A browser (or a context) to draw in.
+ * @param {string} options.extension - The extension's folder (`extension`, or `src` where a build bundles it).
+ * @param {string} options.file - The PNG to write (its folder is made if missing), e.g. `store/promo-440x280.png`.
+ * @param {string} options.line - The line under the name.
+ * @param {string} [options.glow] - The glow's colour (see {@link PromoTile}).
+ * @param {string} [options.name] - The name, if not the extension's `extShortName`.
+ * @param {string} [options.icon] - The icon, if not the extension's `icons/icon.svg`.
+ * @returns {Promise<string>} The file written.
+ * @example
+ * await storePromoTile({ browser, extension: 'extension', file: 'store/promo-440x280.png', line: 'Prices in your currency' });
+ */
+export declare function storePromoTile({ browser, extension, file, line, glow, name, icon }: {
+    browser: import('playwright').Browser | import('playwright').BrowserContext;
+    extension: string;
+    file: string;
+    line: string;
+    glow?: string;
+    name?: string;
+    icon?: string;
+}): Promise<string>;

package/src/build/promo-tile.js

@@ -0,0 +1,87 @@
+/**
+ * The Chrome Web Store's small promo tile (440×280) for the whole family, in one style: the
+ * extension's icon (drawn from its SVG, so it's sharp at any size) with a soft glow, its name
+ * and one short line, on the store screenshots' light background.
+ *
+ * {@link promoTileHtml} lays it out (pure); {@link storePromoTile} reads the icon and name from
+ * the extension folder and writes the PNG.
+ *
+ * @module build/promo-tile
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { esc } from '../frame/window.js';
+import { THEMES } from './store-frame.js';
+
+/** The promo tile's width. */
+export const PROMO_W = 440;
+/** The promo tile's height. */
+export const PROMO_H = 280;
+
+/** The glow under the icon when none is given: Chrome's blue. */
+const GLOW = '#0b57d0';
+
+/**
+ * One promo tile.
+ *
+ * @typedef {object} PromoTile
+ * @property {string} icon The icon: SVG markup, or an image's URL (a data: URL, say).
+ * @property {string} name The extension's name (`extShortName`).
+ * @property {string} line One short line under it, sentence case (“Prices in your currency”).
+ * @property {string} [glow] The colour of the glow under the icon, any CSS colour: the icon's own (default Chrome's blue).
+ */
+
+/**
+ * The tile's page: the icon, the name and the line, centred, at 440×280.
+ *
+ * @param {PromoTile} tile - What it shows.
+ * @returns {string} A whole HTML document.
+ * @example
+ * promoTileHtml({ icon: svg, name: 'Better Prices', line: 'Prices in your currency', glow: '#146c2e' });
+ */
+export function promoTileHtml({ icon, name, line, glow = GLOW }) {
+  const art = icon.trimStart().startsWith('<') ? icon : `<img src="${icon}" alt="">`;
+  return `<!doctype html><html><head><meta charset="utf-8"><style>
+    html, body { margin: 0; }
+    body { width: ${PROMO_W}px; height: ${PROMO_H}px; overflow: hidden; display: grid; place-items: center; background: linear-gradient(160deg, ${THEMES.light.bg}, #dde3ea); -webkit-font-smoothing: antialiased; font-family: system-ui; }
+    .wrap { display: flex; flex-direction: column; align-items: center; gap: 12px; }
+    .icon { width: 112px; height: 112px; filter: drop-shadow(0 6px 14px color-mix(in srgb, ${glow} 28%, transparent)); }
+    .icon svg, .icon img { display: block; width: 100%; height: 100%; }
+    h1 { margin: 0; font: 600 30px/1.1 system-ui; color: #1f1f1f; letter-spacing: -.3px; }
+    p { margin: 0; font: 400 17px system-ui; color: #444746; }
+  </style></head><body><div class="wrap"><div class="icon">${art}</div><h1>${esc(name)}</h1><p>${esc(line)}</p></div></body></html>`;
+}
+
+/**
+ * Write an extension's promo tile: its `icons/icon.svg` and English `extShortName` (unless
+ * `icon` or `name` is given), drawn by {@link promoTileHtml} in a page of the given browser.
+ *
+ * @param {object} options - What and where.
+ * @param {import('playwright').Browser | import('playwright').BrowserContext} options.browser - A browser (or a context) to draw in.
+ * @param {string} options.extension - The extension's folder (`extension`, or `src` where a build bundles it).
+ * @param {string} options.file - The PNG to write (its folder is made if missing), e.g. `store/promo-440x280.png`.
+ * @param {string} options.line - The line under the name.
+ * @param {string} [options.glow] - The glow's colour (see {@link PromoTile}).
+ * @param {string} [options.name] - The name, if not the extension's `extShortName`.
+ * @param {string} [options.icon] - The icon, if not the extension's `icons/icon.svg`.
+ * @returns {Promise<string>} The file written.
+ * @example
+ * await storePromoTile({ browser, extension: 'extension', file: 'store/promo-440x280.png', line: 'Prices in your currency' });
+ */
+export async function storePromoTile({ browser, extension, file, line, glow, name, icon }) {
+  const svg = icon ?? await readFile(path.join(extension, 'icons', 'icon.svg'), 'utf8');
+  const title = name ?? JSON.parse(await readFile(path.join(extension, '_locales', 'en', 'messages.json'), 'utf8')).extShortName.message;
+  const context = 'newContext' in browser ? await browser.newContext({ viewport: { width: PROMO_W, height: PROMO_H }, deviceScaleFactor: 1 }) : null;
+  const page = context ? await context.newPage() : await /** @type {import('playwright').BrowserContext} */ (browser).newPage();
+  try {
+    await page.setViewportSize({ width: PROMO_W, height: PROMO_H });
+    await page.setContent(promoTileHtml({ icon: svg, name: String(title), line, glow }), { waitUntil: 'load' });
+    await page.evaluate(() => Promise.all([...document.images].map((img) => img.decode().catch(() => undefined))));
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, await page.screenshot({ type: 'png', scale: 'css', clip: { x: 0, y: 0, width: PROMO_W, height: PROMO_H } }));
+    return file;
+  } finally {
+    await (context ?? page).close();
+  }
+}