An open source design system that's fully customizable and agent ready
TypeScript
#!/usr/bin/env node
// Copyright (c) Meta Platforms, Inc. and affiliates.
//
// Automate uploading translation-context screenshots to Crowdin.
//
// DESIGN: This script uses ONLY declarative, per-target manual tag
// declarations — never `crowdin screenshot upload --auto-tag`. Every rect
// that ends up on a Crowdin screenshot originates from a strategy in
// lib/crowdin-strategies.mjs. This avoids the two main auto-tag failure
// modes we hit in earlier iterations:
// 1. Auto-tag matches irrelevant text that happens to render on the
// screenshot (e.g. "No results", "Search…" in an unrelated dropdown).
// 2. Auto-tag can't distinguish English text that maps to different
// catalog keys ("is" -> operator.is for strings, operator.equals for
// numbers).
//
// Pipeline:
// 1. Ensure a Storybook build exists at apps/storybook/dist (build if
// missing).
// 2. Validate every declared manualTag key exists in
// packages/core/locales/en.json (warn+skip unknowns).
// 3. Start a local static server, launch chromium.
// 4. For each target: navigate, interact, screenshot, measure each
// declared tag's rect using its named strategy. A rect the capture
// does not contain is reported unresolved, never tagged.
// 5. Upload the PNG to Crowdin (WITHOUT --auto-tag), then POST manual
// tags for the rects we measured.
//
// Usage:
// node internal/scripts/upload-crowdin-screenshots.mjs [flags]
//
// Flags:
// --dry-run Screenshot + measure but do NOT upload or POST tags.
// --validate Only validate declared keys against en.json (no
// browser, no network). Exits non-zero if any unknown.
// --skip-build Reuse existing storybook build.
// --skip-upload Screenshot + measure but don't call `crowdin` or POST.
// --rebuild Force storybook rebuild.
// --only=a,b,c Filter targets by name.
// --delete-first Delete existing Crowdin screenshot with the same
// filename before re-uploading (avoids duplicates if
// the CLI decides to create new IDs). Off by default.
// --replace-tags Before POSTing new tags, DELETE all existing tags on
// the (updated-in-place) screenshot. Prevents tag
// stacking when re-running the script — Crowdin's tag
// POST doesn't dedupe by key. Off by default.
import {chromium} from '@playwright/test';
import {execSync, spawnSync} from 'node:child_process';
import * as http from 'node:http';
import * as fs from 'node:fs';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {
buildMeasureSource,
MUTATING_STRATEGIES,
STRATEGY_NAMES,
toDevicePixelRect,
} from './lib/crowdin-strategies.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const REPO_ROOT = path.resolve(__dirname, '..', '..');
const STORYBOOK_DIST = path.join(REPO_ROOT, 'apps/storybook/dist');
const OUT_DIR = path.join(__dirname, 'output/crowdin-screenshots');
const EN_JSON = path.join(REPO_ROOT, 'packages/core/locales/en.json');
const PROJECT_ID = '914513';
const LABEL = 'i18n-context';
const DPR = 2;
const argv = process.argv.slice(2);
const args = new Set(argv);
const DRY_RUN = args.has('--dry-run');
const SKIP_BUILD = args.has('--skip-build');
const SKIP_UPLOAD = args.has('--skip-upload');
const VALIDATE_ONLY = args.has('--validate');
const DELETE_FIRST = args.has('--delete-first');
const REPLACE_TAGS = args.has('--replace-tags');
let ONLY = null;
{
const idx = argv.findIndex(a => a === '--only' || a.startsWith('--only='));
if (idx !== -1) {
const val = argv[idx].includes('=') ? argv[idx].split('=', 2)[1] : argv[idx + 1];
if (val) ONLY = new Set(val.split(',').map(s => s.trim()).filter(Boolean));
}
}
fs.mkdirSync(OUT_DIR, {recursive: true});
// ---------- helpers ----------
function log(...a) { console.log('[crowdin-screens]', ...a); }
function warn(...a) { console.warn('[crowdin-screens]', ...a); }
function run(cmd, opts = {}) {
return execSync(cmd, {stdio: 'inherit', ...opts});
}
function getToken() {
return execSync(
`security find-generic-password -a "$USER" -s CROWDIN_PERSONAL_TOKEN -w`,
{encoding: 'utf8'},
).trim();
}
// ---------- catalog ----------
function loadCatalogKeys() {
const raw = JSON.parse(fs.readFileSync(EN_JSON, 'utf8'));
const keys = new Set();
for (const k of Object.keys(raw)) {
// Catalog keys start with '@'. The stringIdMap uses the un-@ form.
keys.add(k.replace(/^@/, ''));
}
return keys;
}
// Map of un-@ catalog key → defaultMessage. Loaded once at module scope so
// t() can fall back to the catalog default when a tag's text arg is omitted.
function loadCatalogDefaults() {
const raw = JSON.parse(fs.readFileSync(EN_JSON, 'utf8'));
const out = new Map();
for (const k of Object.keys(raw)) {
const bare = k.replace(/^@/, '');
const msg = raw[k] && typeof raw[k].defaultMessage === 'string'
? raw[k].defaultMessage
: null;
if (msg != null) out.set(bare, msg);
}
return out;
}
const CATALOG_DEFAULTS = loadCatalogDefaults();
// ---------- Crowdin API ----------
async function crowdinFetch(pathAndQuery, {token, method = 'GET', body = null} = {}) {
const url = `https://api.crowdin.com/api/v2${pathAndQuery}`;
const headers = {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
};
const opts = {method, headers};
if (body != null) opts.body = JSON.stringify(body);
const res = await fetch(url, opts);
const text = await res.text();
if (!res.ok) {
throw new Error(`Crowdin ${method} ${pathAndQuery} → ${res.status}: ${text.slice(0, 400)}`);
}
return text ? JSON.parse(text) : null;
}
// Load identifier → stringId map for every astryx.* string. Cached across
// runs would be nice but not necessary — the project is small (<1000).
async function loadStringIdMap(token) {
const map = new Map();
let offset = 0;
const limit = 500;
while (true) {
// Filter by prefix "astryx." to reduce the payload; we tag nothing else.
const q = `/projects/${PROJECT_ID}/strings?filter=${encodeURIComponent('astryx.')}&scope=identifier&limit=${limit}&offset=${offset}`;
const data = await crowdinFetch(q, {token});
const items = data?.data ?? [];
for (const x of items) {
const s = x.data;
const ident = (s.identifier || '').replace(/^@/, '');
map.set(ident, s.id);
}
if (items.length < limit) break;
offset += limit;
}
return map;
}
// ---------- static server ----------
const MIME = {
'.html': 'text/html', '.js': 'application/javascript', '.mjs': 'application/javascript',
'.css': 'text/css', '.json': 'application/json', '.png': 'image/png',
'.svg': 'image/svg+xml', '.ico': 'image/x-icon', '.woff': 'font/woff',
'.woff2': 'font/woff2', '.ttf': 'font/ttf', '.map': 'application/json',
};
function serveStatic(dir) {
return new Promise((resolve, reject) => {
const server = http.createServer((req, res) => {
let urlPath = decodeURIComponent((req.url || '/').split('?')[0]);
if (urlPath === '/') urlPath = '/index.html';
const filePath = path.join(dir, urlPath);
if (!filePath.startsWith(dir) || !fs.existsSync(filePath) || fs.statSync(filePath).isDirectory()) {
res.writeHead(404); res.end('Not found'); return;
}
const ct = MIME[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
res.writeHead(200, {'Content-Type': ct});
fs.createReadStream(filePath).pipe(res);
});
server.on('error', reject);
server.listen(0, '127.0.0.1', () => {
const {port} = server.address();
resolve({
url: `http://127.0.0.1:${port}`,
close: () => new Promise(r => server.close(() => r())),
});
});
});
}
// ---------- targets ----------
// Every target declares an explicit `manualTags` array. Each entry:
// { key: 'astryx.foo.bar', strategy: 'option', args: ['Contains'] }
// The `strategy` is one of STRATEGY_NAMES (see lib/crowdin-strategies.mjs).
// `args` is a positional-arg array for the strategy.
//
// Bare `key` values must NOT include the leading '@' — the strategy map
// stores identifiers without it.
//
// The third+ positional arg is the "text to match" the strategy uses when
// probing the rendered DOM. For the vast majority of tags this text is
// identical to `en.json[key].defaultMessage`, so t() defaults it to that
// catalog value when omitted. Callers still pass an explicit text when it
// diverges from the catalog default — e.g. ICU-interpolated messages
// (`Sort by {label}` → `Sort by Name`), or placeholder catalog values that
// carry trailing ellipses the rendered DOM omits (`Enter value…` vs
// `Enter value`).
//
// Per-strategy convention for which arg slot is the "text" arg:
// visibleText / option / placeholder / ariaLabel / footerButton /
// srOnlyLabel / srOnlyReveal / textRun / liveRegionReveal → args[0]
// chipOperator → args[1] (args[0] = field name)
// filterInput → no text arg (kind string only)
const TEXT_ARG_INDEX = {
visibleText: 0,
option: 0,
placeholder: 0,
ariaLabel: 0,
chipOperator: 1,
filterInput: null,
footerButton: 0,
srOnlyLabel: 0,
srOnlyReveal: 0,
textRun: 0,
liveRegionReveal: 0,
};
function t(key, strategy, ...args) {
const idx = TEXT_ARG_INDEX[strategy];
if (idx != null && args[idx] === undefined) {
const def = CATALOG_DEFAULTS.get(key);
if (def != null) args[idx] = def;
}
return {key, strategy, args};
}
// Every palette capture starts by opening the modal behind the trigger.
async function openCommandPalette(page) {
await page.getByRole('button', {name: 'Open'}).click();
await page.waitForSelector('dialog[open]', {timeout: 3000});
await page.waitForTimeout(400);
}
const TARGETS = [
// ==========================================================================
// Static (non-popover) targets
// ==========================================================================
{
name: 'powersearch-filter-editor',
// ManyFilters renders 7 chips whose visible text embeds operator labels.
storyId: 'core-powersearch--many-filters',
viewport: {width: 900, height: 220},
interact: async () => {},
selector: null,
// Each chip's operator substring gets its own tightly-scoped rect via
// chipOperator(fieldName, opText). Story renders 7 chips: Status,
// Priority, Title, Assignee, Tags, Line count, Created. "Tags: include"
// uses an operator label with no direct catalog key (it's a string_list
// isAnyOf render variant), so we skip it here.
manualTags: [
t('astryx.powersearch.operator.isAnyOf', 'chipOperator', 'Status'),
t('astryx.powersearch.operator.is', 'chipOperator', 'Priority'),
t('astryx.powersearch.operator.contains', 'chipOperator', 'Title'),
t('astryx.powersearch.operator.isAnyOf', 'chipOperator', 'Assignee'),
t('astryx.powersearch.operator.greaterThan', 'chipOperator', 'Line count'),
t('astryx.powersearch.operator.after', 'chipOperator', 'Created'),
],
},
{
name: 'powersearch-value-editor',
// WithDateFilters → open the Created chip and transition to compact editor.
storyId: 'core-powersearch--with-date-filters',
viewport: {width: 900, height: 400},
interact: async page => {
const chip = page.getByRole('button', {name: /Created:\s*is after/i}).first();
await chip.waitFor({state: 'visible', timeout: 5000});
await chip.click();
const createdOption = page.getByRole('option', {name: 'Created'}).first();
await createdOption.waitFor({state: 'visible', timeout: 5000});
await createdOption.click();
await page.getByRole('button', {name: 'Apply'}).first().waitFor({timeout: 5000});
await page.waitForTimeout(400);
},
selector: null,
manualTags: [
// Operator selector in the compact editor shows "is after".
t('astryx.powersearch.operator.after', 'visibleText'),
// Date value input placeholder (from @astryx/core's DateTimeInput).
t('astryx.dateTimeInput.placeholder', 'placeholder'),
t('astryx.powersearch.editor.cancel', 'footerButton'),
t('astryx.powersearch.editor.apply', 'footerButton'),
],
},
{
name: 'chat-message-with-status',
storyId: 'core-chat--message-status',
viewport: {width: 700, height: 500},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.chat.status.sending', 'visibleText'),
t('astryx.chat.status.sent', 'visibleText'),
t('astryx.chat.status.delivered', 'visibleText'),
t('astryx.chat.status.read', 'visibleText'),
t('astryx.chat.status.failed', 'visibleText'),
],
},
{
name: 'powersearch-with-result-count',
storyId: 'core-powersearch--with-result-count',
viewport: {width: 900, height: 220},
interact: async () => {},
selector: null,
manualTags: [
// Story renders "1,234 results" (see WithResultCount fixture).
t('astryx.powersearch.resultCount', 'visibleText', '1,234 results'),
],
},
{
name: 'pagination-count',
storyId: 'core-pagination--count-variant',
viewport: {width: 700, height: 100},
interact: async () => {},
selector: null,
manualTags: [
// ICU "{from}–{to} of {total}" — story renders "1–20 of 200".
t('astryx.pagination.count', 'visibleText', '1–20 of 200'),
],
},
{
name: 'pagination-compact',
storyId: 'core-pagination--compact-variant',
viewport: {width: 500, height: 100},
interact: async () => {},
selector: null,
manualTags: [
// "Page {n} of {total}"
t('astryx.pagination.pageOfTotal', 'visibleText', 'Page 1 of 10'),
],
},
{
name: 'pagination-with-page-size',
storyId: 'core-pagination--with-page-size-selector',
viewport: {width: 900, height: 100},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.pagination.count', 'visibleText', '1–10 of 200'),
// "Items per page" is a visually-hidden <label> (isLabelHidden). The
// srOnlyReveal strategy injects a small visible label bubble next to
// the widget so translators see the actual English label text in the
// screenshot instead of just a bare combobox.
t('astryx.pagination.itemsPerPage', 'srOnlyReveal', undefined, 'below'),
],
},
// ==========================================================================
// Interactive operator-dropdown targets (v3 — WithPresetFilters story)
// ==========================================================================
{
name: 'powersearch-string-operators-open',
storyId: 'core-powersearchwithtable--with-preset-filters',
viewport: {width: 1000, height: 700},
interact: async page => {
await page.locator('[role="combobox"]').first().click();
await page.waitForTimeout(300);
await page.getByRole('option', {name: 'Title'}).first().click();
await page.waitForTimeout(400);
await page.locator('button[role="combobox"]').nth(1).click();
await page.waitForSelector('[role="listbox"]:not(:empty)', {timeout: 3000}).catch(() => {});
await page.waitForTimeout(400);
},
selector: null,
manualTags: [
t('astryx.powersearch.operator.contains', 'option'),
t('astryx.powersearch.operator.notContains', 'option'),
t('astryx.powersearch.operator.startsWith', 'option'),
t('astryx.powersearch.operator.notStartsWith', 'option'),
t('astryx.powersearch.operator.endsWith', 'option'),
t('astryx.powersearch.operator.notEndsWith', 'option'),
t('astryx.powersearch.operator.is', 'option'),
t('astryx.powersearch.operator.isNot', 'option'),
t('astryx.powersearch.valueEditor.enterValuePlaceholder', 'placeholder', 'Enter value'),
t('astryx.powersearch.editor.cancel', 'footerButton'),
t('astryx.powersearch.editor.apply', 'footerButton'),
],
},
{
name: 'powersearch-number-operators-open',
storyId: 'core-powersearchwithtable--with-preset-filters',
viewport: {width: 1000, height: 700},
interact: async page => {
await page.locator('[role="combobox"]').first().click();
await page.waitForTimeout(300);
await page.getByRole('option', {name: 'Publication Year'}).first().click();
await page.waitForTimeout(400);
await page.locator('button[role="combobox"]').nth(1).click();
await page.waitForSelector('[role="listbox"]:not(:empty)', {timeout: 3000}).catch(() => {});
await page.waitForTimeout(400);
},
selector: null,
// For number fields: "is" is the label for `equals`, "is not" for
// `notEquals`. Different string ids from the string field's is/isNot.
manualTags: [
t('astryx.powersearch.operator.equals', 'option'),
t('astryx.powersearch.operator.notEquals', 'option'),
t('astryx.powersearch.operator.greaterThan', 'option'),
t('astryx.powersearch.operator.lessThan', 'option'),
t('astryx.powersearch.operator.greaterThanOrEqual', 'option'),
t('astryx.powersearch.operator.lessThanOrEqual', 'option'),
t('astryx.powersearch.editor.cancel', 'footerButton'),
t('astryx.powersearch.editor.apply', 'footerButton'),
],
},
{
name: 'powersearch-enum-operators-open',
storyId: 'core-powersearchwithtable--with-preset-filters',
viewport: {width: 1000, height: 700},
interact: async page => {
await page.getByRole('button', {name: /^Genre: is/i}).first().click();
await page.waitForTimeout(400);
await page.getByRole('option', {name: 'Genre'}).first().click();
await page.waitForTimeout(400);
await page.locator('button[role="combobox"]').nth(1).click();
await page.waitForSelector('[role="listbox"]:not(:empty)', {timeout: 3000}).catch(() => {});
await page.waitForTimeout(400);
},
selector: null,
manualTags: [
t('astryx.powersearch.operator.is', 'option'),
t('astryx.powersearch.operator.isNot', 'option'),
t('astryx.powersearch.operator.isAnyOf', 'option'),
t('astryx.powersearch.operator.isNoneOf', 'option'),
t('astryx.powersearch.editor.cancel', 'footerButton'),
t('astryx.powersearch.editor.apply', 'footerButton'),
],
},
// ==========================================================================
// v4 targets — date / boolean / enum_list operator dropdowns
// ==========================================================================
{
name: 'powersearch-date-operators-open',
storyId: 'core-powersearchwithtable--with-mixed-filters',
viewport: {width: 1100, height: 750},
interact: async page => {
await page.getByRole('button', {name: /Published Date:\s*is after/i}).first().click();
await page.waitForTimeout(400);
await page.getByRole('option', {name: /^Published Date$/}).first().click();
await page.waitForTimeout(400);
await page.locator('button[role="combobox"]').nth(1).click();
await page.waitForSelector('[role="listbox"]:not(:empty)', {timeout: 3000}).catch(() => {});
await page.waitForTimeout(400);
},
selector: null,
manualTags: [
t('astryx.powersearch.operator.before', 'option'),
t('astryx.powersearch.operator.after', 'option'),
t('astryx.powersearch.operator.between', 'option'),
t('astryx.dateTimeInput.placeholder', 'placeholder'),
t('astryx.powersearch.editor.cancel', 'footerButton'),
t('astryx.powersearch.editor.apply', 'footerButton'),
],
},
{
name: 'powersearch-boolean-operators-chip',
storyId: 'core-powersearchwithtable--with-mixed-filters',
viewport: {width: 1100, height: 220},
// Boolean filter chips render the operator text directly on the filter
// bar (e.g. "In Stock: is true"). Because boolean OperatorValue is
// type='empty', PowerSearchEditPopover auto-closes on mount — the
// operator dropdown is never user-reachable. Tag isTrue/isFalse against
// the chip text on the bar instead, using chipOperator to isolate just
// the operator substring inside the chip.
interact: async () => {},
selector: null,
manualTags: [
t('astryx.powersearch.operator.isTrue', 'chipOperator', 'In Stock'),
t('astryx.powersearch.operator.isFalse', 'chipOperator', 'Discontinued'),
],
},
{
name: 'powersearch-enumlist-operators-open',
storyId: 'core-powersearchwithtable--with-mixed-filters',
viewport: {width: 1100, height: 750},
interact: async page => {
await page.getByRole('button', {name: /Themes:\s*is any of/i}).first().click();
await page.waitForTimeout(400);
await page.getByRole('option', {name: /^Themes$/}).first().click();
await page.waitForTimeout(400);
await page.locator('button[role="combobox"]').nth(1).click();
await page.waitForSelector('[role="listbox"]:not(:empty)', {timeout: 3000}).catch(() => {});
await page.waitForTimeout(400);
},
selector: null,
manualTags: [
t('astryx.powersearch.operator.isAnyOf', 'option'),
t('astryx.powersearch.operator.isNoneOf', 'option'),
t('astryx.powersearch.valueEditor.selectValuesPlaceholder', 'placeholder', 'Select values'),
t('astryx.powersearch.editor.cancel', 'footerButton'),
t('astryx.powersearch.editor.apply', 'footerButton'),
],
},
// ==========================================================================
// Value-editor placeholder targets
// ==========================================================================
{
name: 'powersearch-date-value-editor',
storyId: 'core-powersearchwithtable--with-mixed-filters',
viewport: {width: 1100, height: 750},
interact: async page => {
await page.getByRole('button', {name: /Published Date:\s*is after/i}).first().click();
await page.waitForTimeout(400);
await page.getByRole('option', {name: /^Published Date$/}).first().click();
await page.waitForTimeout(500);
},
selector: null,
manualTags: [
t('astryx.powersearch.operator.after', 'visibleText'),
t('astryx.dateTimeInput.placeholder', 'placeholder'),
t('astryx.powersearch.editor.cancel', 'footerButton'),
t('astryx.powersearch.editor.apply', 'footerButton'),
],
},
{
name: 'powersearch-entity-value-editor',
storyId: 'core-powersearchwithtable--with-mixed-filters',
viewport: {width: 1100, height: 750},
interact: async page => {
await page.getByRole('button', {name: /Author \(entity\):\s*is any of/i}).first().click();
await page.waitForTimeout(400);
await page.getByRole('option', {name: /^Author \(entity\)$/}).first().click();
await page.waitForTimeout(500);
await page.locator('input[placeholder="Search…"]').first().click({trial: false}).catch(() => {});
await page.waitForTimeout(300);
},
selector: null,
manualTags: [
t('astryx.powersearch.operator.isAnyOf', 'visibleText'),
t('astryx.powersearch.valueEditor.searchPlaceholder', 'placeholder', 'Search'),
t('astryx.powersearch.editor.cancel', 'footerButton'),
t('astryx.powersearch.editor.apply', 'footerButton'),
],
},
{
name: 'powersearch-string-value-editor',
storyId: 'core-powersearchwithtable--with-mixed-filters',
viewport: {width: 1100, height: 750},
interact: async page => {
await page.locator('[role="combobox"]').first().click();
await page.waitForTimeout(300);
await page.getByRole('option', {name: /^Title$/}).first().click();
await page.waitForTimeout(500);
},
selector: null,
manualTags: [
t('astryx.powersearch.operator.contains', 'visibleText'),
t('astryx.powersearch.valueEditor.enterValuePlaceholder', 'placeholder', 'Enter value'),
t('astryx.powersearch.editor.cancel', 'footerButton'),
t('astryx.powersearch.editor.apply', 'footerButton'),
],
},
{
name: 'powersearch-number-value-editor',
storyId: 'core-powersearchwithtable--with-mixed-filters',
viewport: {width: 1100, height: 750},
interact: async page => {
await page.locator('[role="combobox"]').first().click();
await page.waitForTimeout(300);
await page.getByRole('option', {name: /^Publication Year$/}).first().click();
await page.waitForTimeout(500);
},
selector: null,
manualTags: [
// Number-field default operator label is "is" (equals key).
t('astryx.powersearch.operator.equals', 'visibleText'),
t('astryx.powersearch.valueEditor.enterNumberPlaceholder', 'placeholder', 'Enter number'),
t('astryx.powersearch.editor.cancel', 'footerButton'),
t('astryx.powersearch.editor.apply', 'footerButton'),
],
},
{
name: 'powersearch-enum-value-editor',
storyId: 'core-powersearchwithtable--with-mixed-filters',
viewport: {width: 1100, height: 750},
interact: async page => {
await page.locator('[role="combobox"]').first().click();
await page.waitForTimeout(300);
await page.getByRole('option', {name: /^Themes$/}).first().click();
await page.waitForTimeout(500);
},
selector: null,
manualTags: [
t('astryx.powersearch.operator.isAnyOf', 'visibleText'),
t('astryx.powersearch.valueEditor.selectValuesPlaceholder', 'placeholder', 'Select values'),
t('astryx.powersearch.editor.cancel', 'footerButton'),
t('astryx.powersearch.editor.apply', 'footerButton'),
],
},
// ==========================================================================
// Dialog / AlertDialog targets
// ==========================================================================
{
name: 'dialog-close-button',
// Basic Dialog with a "Close" (×) button in DialogHeader. The story
// renders a trigger "Open Modal" that reveals the dialog on click.
storyId: 'core-dialog--default',
viewport: {width: 900, height: 700},
interact: async page => {
const btn = page.getByRole('button', {name: /Open Modal/i}).first();
await btn.waitFor({state: 'visible', timeout: 5000});
await btn.click();
// Wait for the Close button inside the dialog header.
await page.getByRole('button', {name: 'Close'}).first()
.waitFor({state: 'visible', timeout: 5000});
await page.waitForTimeout(300);
},
selector: null,
manualTags: [
t('astryx.dialog.close', 'srOnlyReveal', undefined, 'left'),
],
},
{
name: 'alertdialog-cancel',
// AlertDialog "Delete" variant: trigger is a "Delete item" button; on
// click the dialog shows a Cancel + Delete pair.
storyId: 'core-alertdialog--delete',
viewport: {width: 800, height: 500},
interact: async page => {
const btn = page.getByRole('button', {name: /Delete item/i}).first();
await btn.waitFor({state: 'visible', timeout: 5000});
await btn.click();
await page.getByRole('button', {name: 'Cancel'}).first()
.waitFor({state: 'visible', timeout: 5000});
await page.waitForTimeout(300);
},
selector: null,
manualTags: [
// Cancel is one of two footer buttons in the alertdialog (Cancel /
// Delete). footerButton scopes to dialog/popover containers, avoiding
// any stray "Cancel" elsewhere on the page.
t('astryx.alertDialog.cancel', 'footerButton'),
],
},
// ==========================================================================
// Banner targets
// ==========================================================================
{
name: 'banner-dismissable',
// The × button's aria-label now names its banner ("Dismiss <title>"), so
// this target tags dismissTitled with the string the story actually
// renders; the bare `banner.dismiss` survives as the button's tooltip.
storyId: 'core-banner--dismissable',
viewport: {width: 900, height: 200},
interact: async () => {},
selector: null,
manualTags: [
t(
'astryx.banner.dismissTitled',
'srOnlyReveal',
'Dismiss Your session will expire soon.',
'below',
),
],
},
{
name: 'banner-collapsible',
// Collapsible banner starts COLLAPSED — chevron reads "Expand".
storyId: 'core-banner--collapsible-content',
viewport: {width: 900, height: 250},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.banner.expand', 'srOnlyReveal', undefined, 'below'),
],
},
{
name: 'banner-collapsible-expanded',
// Same banner but starts EXPANDED — chevron reads "Collapse".
storyId: 'core-banner--collapsible-content-expanded',
viewport: {width: 900, height: 250},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.banner.collapse', 'srOnlyReveal', undefined, 'below'),
],
},
// ==========================================================================
// Table sort / selection / filter / row-expansion / grouped-rows targets
// ==========================================================================
{
name: 'table-sort-headers',
// The sort-direction strings (`Sort ascending`, `Sort descending`,
// `Clear sort`) are not the column header buttons' names, which are the
// column text. The three strings we care about live in the header
// context menu, which opens on right-click.
// Right-clicking the currently-sorted column (Name) reveals all three
// options in one popover.
storyId: 'core-tablesortable--single-sort',
viewport: {width: 1100, height: 500},
interact: async page => {
const header = page.getByRole('button', {name: 'Name', exact: true}).first();
await header.waitFor({state: 'visible', timeout: 5000});
await header.click({button: 'right'});
// Wait for context menu.
await page.locator('[role="menu"], [aria-label="Context menu"]').first()
.waitFor({state: 'visible', timeout: 3000}).catch(() => {});
await page.waitForTimeout(400);
},
selector: null,
manualTags: [
t('astryx.table.sort.ascending', 'visibleText'),
t('astryx.table.sort.descending', 'visibleText'),
t('astryx.table.sort.clear', 'visibleText'),
],
},
{
name: 'table-selection',
// Select-all / select-row labels are sr-only <label> elements
// (astryx-field-label at 1×1 px). srOnlyLabel walks up to the nearest
// visible ancestor — the checkbox itself — so translators see the
// control.
storyId: 'core-tableselection--default',
viewport: {width: 1100, height: 500},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.table.selection.selectAllRows', 'srOnlyReveal', undefined, 'below'),
t('astryx.table.selection.selectRow', 'srOnlyReveal', undefined, 'right'),
],
},
{
name: 'table-filter-panel',
// Filter popover: click the "Filter Role" header button to open a
// panel with an "All" placeholder-ish combobox and Reset / Apply
// footer buttons.
storyId: 'core-tablefiltering--selector-filter',
viewport: {width: 1100, height: 600},
interact: async page => {
const filterBtn = page.getByRole('button', {name: 'Filter Role'}).first();
await filterBtn.waitFor({state: 'visible', timeout: 5000});
await filterBtn.click();
// "Apply" appears when the panel is open.
await page.getByRole('button', {name: 'Apply'}).first()
.waitFor({state: 'visible', timeout: 3000}).catch(() => {});
await page.waitForTimeout(400);
},
selector: null,
manualTags: [
// "All" is rendered as a <span> inside a combobox trigger — no
// <input placeholder>, so use visibleText.
t('astryx.table.filter.allPlaceholder', 'visibleText'),
t('astryx.table.filter.reset', 'footerButton'),
t('astryx.table.filter.apply', 'footerButton'),
],
},
{
name: 'table-rowexpansion',
// The `inherited-columns` story shows a tree where the first row is
// expanded (aria-label="Collapse row") and its siblings are collapsed
// (aria-label="Expand row"). The header cell also shows
// aria-label="Expand all rows". This gives us three of the four keys
// in the four-way expand/collapse set. `collapseAllRows` only appears
// when EVERY row is expanded — skip it (would need extra interaction).
storyId: 'core-tablerowexpansion--inherited-columns',
viewport: {width: 1100, height: 500},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.tableRowExpansion.expandRow', 'srOnlyReveal', undefined, 'right'),
t('astryx.tableRowExpansion.collapseRow', 'srOnlyReveal', undefined, 'right'),
t('astryx.tableRowExpansion.expandAllRows', 'srOnlyReveal', undefined, 'below'),
],
},
{
name: 'table-groupedrows',
// The `initially-collapsed` variant has a mix — Design Systems and
// Growth start expanded (aria-label "Collapse group X") while Infra
// starts collapsed ("Expand group Infra"). Perfect for tagging both
// keys on one screenshot. The aria-labels are ICU templates with a
// {groupKey} slot, so we must match the fully-rendered text.
storyId: 'core-tablegroupedrows--initially-collapsed',
viewport: {width: 1100, height: 500},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.tableGroupedRows.collapseGroup', 'srOnlyReveal', 'Collapse group Design Systems', 'right'),
t('astryx.tableGroupedRows.expandGroup', 'srOnlyReveal', 'Expand group Infra', 'right'),
],
},
// ==========================================================================
// Catalog-coverage targets
//
// One target per story that renders strings the targets above do not
// already tag. A (key, story, strategy) triple is only valid when the
// story's own component is the one that REFERENCES the key — six
// components own a `Clear {label}`, so a text match alone is a
// coincidence. Strings reachable only inside a closed overlay are
// deliberately absent.
//
// These use the non-mutating strategies rather than srOnlyReveal: several
// injected bubbles on one target would overlap each other.
// ==========================================================================
{
name: 'transferlist-default',
storyId: 'lab-transferlist--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.transferList.addAll', 'visibleText'),
t('astryx.transferList.addOption', 'visibleText', "Add all"),
t('astryx.transferList.clear', 'visibleText'),
t('astryx.transferList.removeOption', 'ariaLabel', "Remove Name"),
t('astryx.transferList.reorderInstructions', 'srOnlyLabel'),
t('astryx.transferList.reorderOption', 'ariaLabel', "Reorder Name"),
t('astryx.transferListSelector.triggerLabel', 'visibleText', "Move fields between the panels. The selected order is the display order."),
],
},
{
name: 'dateinput-default',
storyId: 'core-dateinput--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.dateInput.closeCalendar', 'srOnlyLabel'),
t('astryx.dateInput.openCalendar', 'ariaLabel'),
t('astryx.dateInput.placeholder', 'placeholder'),
t('astryx.dateInput.toggleCalendarClose', 'srOnlyLabel'),
],
},
{
name: 'datetimeinput-default',
storyId: 'core-datetimeinput--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.dateTimeInput.openTimePicker', 'ariaLabel', "Open calendar"),
t('astryx.dateTimeInput.timePlaceholder', 'placeholder'),
],
},
{
name: 'listinput-loading',
storyId: 'lab-listinput--loading',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.listInput.removeItem', 'ariaLabel', "Remove tag 1"),
t('astryx.listInput.reorderItem', 'ariaLabel', "Reorder tag 1"),
],
},
{
name: 'pagination-default',
storyId: 'core-pagination--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.pagination.goToPage', 'ariaLabel', "Go to page 1"),
t('astryx.pagination.label', 'ariaLabel'),
t('astryx.pagination.next', 'ariaLabel'),
t('astryx.pagination.previous', 'ariaLabel'),
],
},
{
name: 'stepper-default',
storyId: 'core-stepper--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.step.goToStep', 'ariaLabel', "Go to step 1: Create workspace, completed"),
t('astryx.step.goToStepWithStatus', 'ariaLabel', "Go to step 1: Create workspace, completed"),
t('astryx.step.status.completed', 'srOnlyLabel'),
t('astryx.stepper.label', 'ariaLabel'),
],
},
{
name: 'carousel-default',
storyId: 'core-carousel--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.carousel.scrollLeft', 'ariaLabel'),
t('astryx.carousel.scrollRight', 'ariaLabel'),
t('astryx.carousel.slideLabel', 'ariaLabel', "Slide 1 of 8"),
],
},
{
name: 'listinput-empty-mailing-list',
storyId: 'lab-listinput--empty-mailing-list',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.listInput.addItem', 'visibleText', "Add a subscriber to get started."),
t('astryx.listInput.emptyDescription', 'visibleText', "Add a subscriber to get started."),
t('astryx.listInput.emptyTitle', 'visibleText', "No subscribers yet"),
],
},
{
name: 'calendar-default',
storyId: 'core-calendar--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.calendar.nextMonth', 'ariaLabel'),
t('astryx.calendar.previousMonth', 'ariaLabel'),
],
},
{
name: 'daterangeinput-default',
storyId: 'core-daterangeinput--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.dateRangeInput.placeholder', 'visibleText'),
],
},
{
name: 'fileinput-required',
storyId: 'core-fileinput--required',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.fileInput.placeholder', 'visibleText'),
],
},
{
name: 'markdown-default',
storyId: 'core-markdown--default',
// 800 tall leaves the task list below the fold, so it goes untagged.
viewport: {width: 1200, height: 1000},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.markdown.table', 'visibleText'),
t('astryx.markdown.taskList', 'srOnlyLabel'),
],
},
{
name: 'multiselector-empty-states',
storyId: 'core-multiselector--empty-states',
viewport: {width: 1200, height: 800},
// The options panel only exists once the trigger is clicked.
interact: async page => {
await page.locator('button:visible').first().click({timeout: 3000});
await page.waitForTimeout(500);
},
selector: null,
manualTags: [
t('astryx.multiSelector.empty', 'visibleText'),
t('astryx.multiSelector.selectPlaceholder', 'visibleText'),
],
},
{
name: 'multiselector-searchable-sections',
storyId: 'core-multiselector--searchable-sections',
viewport: {width: 1200, height: 800},
// The options panel only exists once the trigger is clicked.
interact: async page => {
await page.locator('button:visible').first().click({timeout: 3000});
await page.waitForTimeout(500);
},
selector: null,
manualTags: [
t('astryx.multiSelector.searchOptions', 'ariaLabel'),
t('astryx.multiSelector.searchPlaceholder', 'placeholder'),
],
},
{
name: 'numberinput-with-number-steppers',
storyId: 'core-numberinput--with-number-steppers',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.numberInput.decrementLabel', 'ariaLabel', "Decrement Quantity"),
t('astryx.numberInput.incrementLabel', 'ariaLabel', "Increment Quantity"),
],
},
{
name: 'selector-empty-states',
storyId: 'core-selector--empty-states',
viewport: {width: 1200, height: 800},
// The options panel only exists once the trigger is clicked.
interact: async page => {
await page.locator('button:visible').first().click({timeout: 3000});
await page.waitForTimeout(500);
},
selector: null,
manualTags: [
t('astryx.selector.empty', 'visibleText'),
t('astryx.selector.placeholder', 'visibleText'),
],
},
{
name: 'selector-searchable-with-sections',
storyId: 'core-selector--searchable-with-sections',
viewport: {width: 1200, height: 800},
// The options panel only exists once the trigger is clicked.
interact: async page => {
await page.locator('button:visible').first().click({timeout: 3000});
await page.waitForTimeout(500);
},
selector: null,
manualTags: [
t('astryx.selector.searchOptions', 'ariaLabel'),
t('astryx.selector.searchPlaceholder', 'placeholder'),
],
},
{
name: 'stepper-status-vertical',
storyId: 'core-stepper--status-vertical',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.step.optional', 'visibleText'),
t('astryx.step.status.error', 'srOnlyLabel'),
],
},
{
name: 'transferlist-searchable',
storyId: 'lab-transferlist--searchable',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.transferList.availableLabel', 'visibleText'),
t('astryx.transferList.searchLabel', 'placeholder', "Search 200 fields"),
],
},
{
name: 'avatargroup-default',
storyId: 'core-avatargroup--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.avatarGroup.label', 'ariaLabel'),
],
},
{
name: 'avatargroup-server-side-count',
storyId: 'core-avatargroup--server-side-count',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.avatarGroup.overflow', 'ariaLabel', "44 more"),
],
},
{
name: 'breadcrumbs-default',
storyId: 'core-breadcrumbs--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.breadcrumbs.label', 'ariaLabel'),
],
},
{
name: 'button-loading',
storyId: 'core-button--loading',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.button.loading', 'ariaLabel'),
],
},
{
name: 'calendar-with-selected-date',
storyId: 'core-calendar--with-selected-date',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.calendar.daySelected', 'ariaLabel', "Thursday, January 15, 2026, selected"),
],
},
{
name: 'chat-default',
storyId: 'core-chat--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.chatMessage.messageFrom', 'ariaLabel', "Message from user"),
],
},
{
name: 'chat-message-status',
storyId: 'core-chat--message-status',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.chatToolCalls.status.error', 'visibleText'),
],
},
{
name: 'citation-label',
storyId: 'core-citation--label',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.citation.label', 'ariaLabel', "Citation 1: React Documentation"),
],
},
{
name: 'codeblock-default',
storyId: 'core-codeblock--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.codeBlock.copyCode', 'ariaLabel'),
],
},
{
name: 'daterangeinput-with-warning-status',
storyId: 'core-daterangeinput--with-warning-status',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.dateInput.clear', 'ariaLabel', "Clear Date range"),
],
},
{
name: 'dropdownmenu-compact-drill-in-presentation',
storyId: 'core-dropdownmenu--compact-drill-in-presentation',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.dropdownMenu.back', 'ariaLabel'),
],
},
{
name: 'fileinput-multiple-files',
storyId: 'core-fileinput--multiple-files',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.fileInput.placeholderMultiple', 'visibleText'),
],
},
{
name: 'metadatalist-show-more',
storyId: 'core-metadatalist--show-more',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.metadataList.showMore', 'visibleText'),
],
},
{
name: 'moremenu-default',
storyId: 'core-moremenu--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.moreMenu.label', 'ariaLabel'),
],
},
{
name: 'multiselector-searchable',
storyId: 'core-multiselector--searchable',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.multiSelector.selectAll', 'srOnlyLabel'),
],
},
{
name: 'multiselector-default',
storyId: 'core-multiselector--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.multiSelector.selectionCount', 'visibleText', "2 selected"),
],
},
{
name: 'outline-compact',
storyId: 'core-outline--compact',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.outline.label', 'ariaLabel'),
],
},
{
name: 'pagination-compact-variant',
storyId: 'core-pagination--compact-variant',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.pagination.pageAnnounce', 'visibleText', "Page 1 of 10"),
],
},
{
name: 'pagination-dots-variant',
storyId: 'core-pagination--dots-variant',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.pagination.pageIndicators', 'ariaLabel'),
],
},
{
name: 'popover-default',
storyId: 'core-popover--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.popover.close', 'srOnlyLabel'),
],
},
{
name: 'powersearch-default',
storyId: 'core-powersearch--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.powersearch.label', 'ariaLabel'),
],
},
{
name: 'sidenav-with-header-menu',
storyId: 'core-sidenav--with-header-menu',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.sideNav.heading.openMenu', 'ariaLabel'),
],
},
{
name: 'sidenav-default',
storyId: 'core-sidenav--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.sideNav.label', 'ariaLabel'),
],
},
{
name: 'spinner-default',
storyId: 'core-spinner--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.spinner.loading', 'ariaLabel'),
],
},
{
name: 'stepper-status-all-states',
storyId: 'core-stepper--status-all-states',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.step.status.warning', 'srOnlyLabel'),
],
},
{
name: 'tablist-default',
storyId: 'core-tablist--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.tabList.label', 'ariaLabel'),
],
},
{
name: 'table-default',
storyId: 'core-table--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.table.label', 'ariaLabel'),
],
},
{
name: 'thumbnail-with-remove',
storyId: 'core-thumbnail--with-remove',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.thumbnail.remove', 'ariaLabel', "Remove photo.png — Removable thumbnail"),
],
},
{
name: 'timeinput-with-clear-button',
storyId: 'core-timeinput--with-clear-button',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.timeInput.clearLabel', 'ariaLabel', "Clear Start time"),
],
},
{
name: 'timeinput-native-picker-modes',
storyId: 'core-timeinput--native-picker-modes',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.timeInput.openPicker', 'ariaLabel', "Open nativePicker='always'"),
],
},
{
name: 'timeinput-default',
storyId: 'core-timeinput--default',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.timeInput.placeholder', 'placeholder'),
],
},
{
name: 'token-with-remove',
storyId: 'core-token--with-remove',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.token.remove', 'ariaLabel', "Remove Removable"),
],
},
{
name: 'treelist-fully-expanded',
storyId: 'core-treelist--fully-expanded',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.treeList.toggleChildren', 'ariaLabel'),
],
},
{
name: 'typeahead-status-variant-comparison',
storyId: 'core-typeahead--status-variant-comparison',
viewport: {width: 1200, height: 800},
interact: async () => {},
selector: null,
manualTags: [
t('astryx.typeahead.searchPlaceholder', 'placeholder'),
],
},
// ==========================================================================
// CommandPalette
// ==========================================================================
// Four moments of one flow on the BuiltInStrings story, which overrides no
// string. Each announcement replaces the one before it, so each needs its
// own capture.
{
name: 'commandpalette-bootstrap-empty',
storyId: 'core-commandpalette--built-in-strings',
viewport: {width: 900, height: 700},
interact: openCommandPalette,
selector: null,
manualTags: [
t('astryx.commandPalette.input.placeholder', 'placeholder'),
t('astryx.commandPalette.emptyBootstrap', 'visibleText'),
// Each hint is `<span><Kbd/>Navigate</span>`, so tag the text node.
t('astryx.commandPalette.footer.navigate', 'textRun'),
t('astryx.commandPalette.footer.select', 'textRun'),
t('astryx.commandPalette.footer.close', 'textRun'),
// aria-label only, but on surfaces a translator can see and identify.
t('astryx.commandPalette.label', 'ariaLabel'),
t('astryx.commandPalette.list.label', 'ariaLabel'),
],
},
{
name: 'commandpalette-no-results',
storyId: 'core-commandpalette--built-in-strings',
viewport: {width: 900, height: 700},
interact: async page => {
await openCommandPalette(page);
await page.locator('dialog[open] input').first().fill('zzz');
await page.waitForTimeout(1100);
},
selector: null,
manualTags: [
t('astryx.commandPalette.emptySearch', 'visibleText'),
// "No results for {query}" — the story's query is "zzz".
t(
'astryx.commandPalette.noResultsFor',
'liveRegionReveal',
'No results for zzz',
'.astryx-command-palette-input',
'below',
),
],
},
{
name: 'commandpalette-result-count',
storyId: 'core-commandpalette--built-in-strings',
viewport: {width: 900, height: 700},
interact: async page => {
await openCommandPalette(page);
await page.locator('dialog[open] input').first().fill('e');
await page.waitForTimeout(1100);
},
selector: null,
manualTags: [
// All three of the story's commands match "e".
t(
'astryx.commandPalette.resultCount',
'liveRegionReveal',
'3 results',
'.astryx-command-palette-input',
'below',
),
],
},
{
name: 'commandpalette-loading',
storyId: 'core-commandpalette--built-in-strings',
viewport: {width: 900, height: 700},
interact: async page => {
await openCommandPalette(page);
// Capture inside the story's 600ms in-flight window.
await page.locator('dialog[open] input').first().fill('e');
await page.waitForTimeout(120);
},
selector: null,
manualTags: [
t(
'astryx.commandPalette.loading',
'liveRegionReveal',
undefined,
'.astryx-command-palette-input',
'below',
),
],
},
];
// ---------- validation ----------
function validateAllTargets(catalogKeys) {
const errors = [];
const unknown = new Set();
for (const target of TARGETS) {
for (const tag of target.manualTags || []) {
if (!STRATEGY_NAMES.includes(tag.strategy)) {
errors.push(`${target.name}: unknown strategy "${tag.strategy}" for key ${tag.key}`);
}
if (!catalogKeys.has(tag.key)) {
unknown.add(`${target.name} :: ${tag.key}`);
}
}
}
return {errors, unknown: [...unknown]};
}
// ---------- storybook build ----------
async function ensureStorybookBuild() {
if (SKIP_BUILD && fs.existsSync(STORYBOOK_DIST)) {
log('Reusing existing storybook build at', STORYBOOK_DIST);
return;
}
if (fs.existsSync(path.join(STORYBOOK_DIST, 'iframe.html')) && !args.has('--rebuild')) {
log('Storybook build already exists at', STORYBOOK_DIST, '(skipping)');
return;
}
log('Building Storybook (pnpm --filter @astryxdesign/storybook build)…');
const t0 = Date.now();
run('pnpm --filter @astryxdesign/storybook build', {cwd: REPO_ROOT});
log(`Storybook built in ${((Date.now() - t0) / 1000).toFixed(1)}s`);
}
// ---------- main ----------
async function main() {
const totalT0 = Date.now();
// 1. Catalog validation (fast; always runs).
const catalogKeys = loadCatalogKeys();
const {errors, unknown} = validateAllTargets(catalogKeys);
if (errors.length) {
for (const e of errors) console.error('[crowdin-screens] ERROR', e);
process.exit(2);
}
if (unknown.length) {
warn(`⚠ ${unknown.length} declared key(s) NOT in en.json (will be skipped):`);
for (const u of unknown) warn(' ·', u);
}
if (VALIDATE_ONLY) {
log(`Validation complete. ${TARGETS.length} targets checked, ${unknown.length} unknown keys.`);
process.exit(unknown.length ? 1 : 0);
}
// 2. Storybook.
await ensureStorybookBuild();
if (!fs.existsSync(path.join(STORYBOOK_DIST, 'iframe.html'))) {
throw new Error(`Missing ${STORYBOOK_DIST}/iframe.html — storybook build failed`);
}
// 3. Browser + measurement.
const server = await serveStatic(STORYBOOK_DIST);
log('Static server:', server.url);
const browser = await chromium.launch({headless: true});
const captured = [];
const targets = ONLY ? TARGETS.filter(x => ONLY.has(x.name)) : TARGETS;
if (ONLY) {
log(`--only filter: ${targets.length}/${TARGETS.length}: ${targets.map(x => x.name).join(', ')}`);
const missing = [...ONLY].filter(n => !TARGETS.some(x => x.name === n));
if (missing.length) warn(`⚠ --only names not found in TARGETS: ${missing.join(', ')}`);
}
const measureFnSource = buildMeasureSource();
try {
for (const target of targets) {
const t0 = Date.now();
const ctx = await browser.newContext({viewport: target.viewport, deviceScaleFactor: DPR});
const page = await ctx.newPage();
const url = `${server.url}/iframe.html?id=${target.storyId}&viewMode=story`;
log(`→ ${target.name} :: ${url}`);
page.on('pageerror', e => warn(' [page error]', e.message));
await page.goto(url, {waitUntil: 'load'});
await page.waitForLoadState('networkidle', {timeout: 15000}).catch(() => {});
await page.waitForTimeout(500);
try {
await target.interact(page);
} catch (err) {
warn(` ⚠ interact() failed for ${target.name}: ${err.message} — screenshotting current state anyway`);
}
// Pre-screenshot pass: run any strategies that need to mutate the DOM
// (e.g. srOnlyReveal injects visible label bubbles) BEFORE the
// screenshot is captured. Strategies are idempotent: the same call
// during the measurement pass below returns the already-injected
// rect instead of duplicating.
const revealTags = (target.manualTags || []).filter(t =>
MUTATING_STRATEGIES.includes(t.strategy),
);
if (revealTags.length) {
for (const tag of revealTags) {
await page.evaluate(
({fnSource, strategy, args}) => {
const measure = eval(fnSource);
return measure(strategy, args);
},
{fnSource: measureFnSource, strategy: tag.strategy, args: tag.args},
);
}
}
const outPath = path.join(OUT_DIR, `${target.name}.png`);
// A viewport capture is the viewport at the device pixel ratio.
const imageWidth = target.viewport.width * DPR;
const imageHeight = target.viewport.height * DPR;
if (target.selector) {
await page.locator(target.selector).first().screenshot({path: outPath});
} else {
await page.screenshot({path: outPath, fullPage: false});
}
const size = fs.statSync(outPath).size;
log(` ✓ ${outPath} (${(size / 1024).toFixed(1)} KB, ${((Date.now() - t0) / 1000).toFixed(1)}s)`);
// Measure each declared tag's rect via its strategy.
const measured = [];
if (target.manualTags && target.manualTags.length) {
for (const tag of target.manualTags) {
if (!catalogKeys.has(tag.key)) {
measured.push({key: tag.key, position: null, reason: 'not-in-catalog'});
continue;
}
const rect = await page.evaluate(
({fnSource, strategy, args}) => {
const measure = eval(fnSource);
return measure(strategy, args);
},
{fnSource: measureFnSource, strategy: tag.strategy, args: tag.args},
);
if (!rect) {
measured.push({key: tag.key, position: null, reason: 'no-rect', strategy: tag.strategy, args: tag.args});
} else {
measured.push({
key: tag.key,
strategy: tag.strategy,
position: toDevicePixelRect(rect, DPR),
});
}
}
const hit = measured.filter(m => m.position).length;
log(` ↳ measured ${hit}/${measured.length} tag positions`);
for (const m of measured) {
if (!m.position) {
warn(` · skip ${m.key} (${m.reason}${m.strategy ? ` via ${m.strategy}` : ''})`);
} else if (DRY_RUN || SKIP_UPLOAD) {
// Print the rect against the image size on inspectable runs.
const p = m.position;
log(` · ${m.key} [${p.x},${p.y} ${p.width}×${p.height}] → ${p.x + p.width},${p.y + p.height} of ${imageWidth}×${imageHeight}`);
}
}
}
captured.push({name: target.name, path: outPath, size, measured});
await ctx.close();
}
} finally {
await browser.close();
await server.close();
}
// 4. Upload + tag.
if (SKIP_UPLOAD || DRY_RUN) {
log(`Skipping upload (${DRY_RUN ? '--dry-run' : '--skip-upload'}). ${captured.length} screenshots captured.`);
log(`Total: ${((Date.now() - totalT0) / 1000).toFixed(1)}s`);
return;
}
const token = getToken();
const env = {...process.env, CROWDIN_PERSONAL_TOKEN: token, CROWDIN_PROJECT_ID: PROJECT_ID};
log('Fetching Crowdin string-id map…');
const stringIdMap = await loadStringIdMap(token);
log(` loaded ${stringIdMap.size} astryx.* identifiers`);
for (const c of captured) {
// Optional: delete existing screenshot with the same filename before
// re-uploading, to guarantee we don't stack tags on a stale ID.
if (DELETE_FIRST) {
try {
const q = `/projects/${PROJECT_ID}/screenshots?limit=25&search=${encodeURIComponent(c.name)}`;
const list = await crowdinFetch(q, {token});
for (const x of list?.data ?? []) {
if (x?.data?.name === `${c.name}.png`) {
log(` ✂ deleting existing screenshot id=${x.data.id} (${c.name}.png)`);
await crowdinFetch(`/projects/${PROJECT_ID}/screenshots/${x.data.id}`, {token, method: 'DELETE'});
}
}
} catch (err) {
warn(` ⚠ delete-first failed for ${c.name}: ${err.message.slice(0, 300)}`);
}
}
const cmdArgs = [
'screenshot', 'upload', c.path,
// NOTE: --auto-tag intentionally OMITTED. All tags come from manualTags.
// -f / -d / -b would REQUIRE --auto-tag per the CLI's own validation,
// so we omit them too.
'--project-id', PROJECT_ID,
'--label', LABEL,
'-o', 'json',
];
log(`↑ crowdin screenshot upload ${c.name} (no auto-tag)`);
const res = spawnSyncCapture('crowdin', cmdArgs, {env, cwd: REPO_ROOT});
const short = (res.stdout || '').slice(0, 800);
if (res.status !== 0) {
warn(` ✗ exit=${res.status}`);
warn(' stdout:', short);
warn(' stderr:', (res.stderr || '').slice(0, 600));
continue;
}
log(' ✓ uploaded');
// POST manual tags.
if (!c.measured || !c.measured.length) continue;
try {
const q = `/projects/${PROJECT_ID}/screenshots?limit=25&search=${encodeURIComponent(c.name)}`;
const list = await crowdinFetch(q, {token});
const match = (list?.data ?? []).find(x => x?.data?.name === `${c.name}.png`);
if (!match) {
warn(` ⚠ could not resolve screenshot ID for ${c.name}`);
continue;
}
const screenshotId = match.data.id;
// Optional: clear existing tags on this screenshot before POSTing new
// ones. Tags don't dedupe on POST — running the script twice would
// stack duplicates at slightly-different-but-overlapping rects. Use
// --replace-tags to guarantee tag-set matches the current declared
// measurements exactly.
if (REPLACE_TAGS) {
try {
const existing = await crowdinFetch(
`/projects/${PROJECT_ID}/screenshots/${screenshotId}/tags?limit=100`,
{token},
);
const tags = existing?.data ?? [];
for (const t of tags) {
const tid = t?.data?.id;
if (tid == null) continue;
await crowdinFetch(
`/projects/${PROJECT_ID}/screenshots/${screenshotId}/tags/${tid}`,
{token, method: 'DELETE'},
);
}
if (tags.length) {
log(` ✗ deleted ${tags.length} existing tag(s) (--replace-tags)`);
}
} catch (err) {
warn(` ⚠ tag-clear failed for ${c.name}: ${err.message.slice(0, 300)}`);
}
}
const body = [];
const skipped = [];
for (const m of c.measured) {
if (!m.position) { skipped.push(`${m.key}(${m.reason || 'no-pos'})`); continue; }
const sid = stringIdMap.get(m.key);
if (!sid) { skipped.push(`${m.key}(no-string-id)`); continue; }
body.push({stringId: sid, position: m.position});
}
if (!body.length) {
warn(` ⚠ no manual tags to post; skipped=${skipped.join(',') || 'none'}`);
continue;
}
const postRes = await crowdinFetch(
`/projects/${PROJECT_ID}/screenshots/${screenshotId}/tags`,
{token, method: 'POST', body},
);
const postedCount = (postRes?.data ?? []).length;
log(` ↑ POSTed ${postedCount} tag(s) → screenshotId=${screenshotId}${skipped.length ? `, skipped=${skipped.join(',')}` : ''}`);
} catch (err) {
warn(` ✗ manual tagging failed for ${c.name}: ${err.message.slice(0, 300)}`);
}
}
log(`Total: ${((Date.now() - totalT0) / 1000).toFixed(1)}s`);
}
function spawnSyncCapture(cmd, argv, opts) {
return spawnSync(cmd, argv, {encoding: 'utf8', ...opts});
}
main().catch(e => { console.error(e); process.exit(1); });