@meddleware/frontend-config 0.0.0-rename.0 → 0.0.1

package/src/playwright.js

@@ -0,0 +1,62 @@
+// @ts-check
+// Playwright config for browser tests of a BUILT app, gallery or VitePress site. A repo's playwright.config.ts becomes
+//   import { definePlaywrightConfig } from '@meddleware/frontend-config/playwright'
+//   export default definePlaywrightConfig({ port: 4281 })
+//
+// Browsers: Chromium locally (fast); all five projects in CI — Chromium, Firefox, WebKit and a Pixel 7 / iPhone 14 viewport
+// (Chromium and WebKit engines). Override with E2E_BROWSERS=chromium|all (or the `browsers` option).
+// Screenshot capture (`npm run shots`, SHOTS=1) is for looking, not asserting: screens specs only run when asked, and then alone.
+import { defineConfig, devices } from '@playwright/test'
+
+/** @typedef {'chromium' | 'all'} BrowserSet */
+
+/**
+ * @param {object} options
+ * @param {number} options.port Preview server port (unique per repo, so repos can run side by side).
+ * @param {'app' | 'gallery' | 'vitepress'} [options.kind] What is served. `app`: `npm run build` then `vite preview`.
+ *   `gallery`: `npm run build:gallery` then `vite preview --config vite.gallery.config.ts`. `vitepress`: `vitepress preview docs`
+ *   (the site must already be built, so the repo's `test:e2e` script builds first).
+ * @param {string} [options.command] Full server command; replaces the one `kind` implies.
+ * @param {BrowserSet} [options.browsers] Browser set; default from E2E_BROWSERS, else `all` in CI and `chromium` otherwise.
+ * @param {string} [options.testDir]
+ * @param {import('@playwright/test').PlaywrightTestConfig} [options.extra] Merged over the defaults.
+ */
+export function definePlaywrightConfig({ port, kind = 'app', command, browsers, testDir = './e2e', extra = {} }) {
+  const server = {
+    app: `npm run build && npx vite preview --port ${port} --strictPort`,
+    gallery: `npm run build:gallery && npx vite preview --config vite.gallery.config.ts --port ${port} --strictPort`,
+    vitepress: `npx vitepress preview docs --port ${port}`,
+  }[kind]
+  const requested = browsers ?? process.env.E2E_BROWSERS ?? (process.env.CI && !process.env.SHOTS ? 'all' : 'chromium')
+  const all = requested === 'all'
+  const projects = [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    ...(all
+      ? [
+          { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+          { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+          { name: 'mobile-chrome', use: { ...devices['Pixel 7'] } },
+          { name: 'mobile-safari', use: { ...devices['iPhone 14'] } },
+        ]
+      : []),
+  ]
+  return defineConfig({
+    testDir,
+    // A screenshot run loads only the screens specs; a normal run never loads them. (Tests are attributed to the file that calls
+    // `test()`, which for `defineShots` is shots.js, so a `playwright test e2e/screens.spec.ts` file filter would find none.)
+    ...(process.env.SHOTS ? { testMatch: '**/screens.spec.ts' } : { testIgnore: ['**/screens.spec.ts'] }),
+    fullyParallel: true,
+    forbidOnly: !!process.env.CI,
+    retries: process.env.CI ? 1 : 0,
+    reporter: process.env.CI ? [['list'], ['html', { open: 'never' }]] : 'list',
+    use: { baseURL: `http://localhost:${port}`, viewport: { width: 1280, height: 900 }, trace: 'retain-on-failure' },
+    webServer: {
+      command: command ?? server,
+      url: `http://localhost:${port}/`,
+      reuseExistingServer: !process.env.CI,
+      timeout: 180_000,
+    },
+    projects,
+    ...extra,
+  })
+}

package/src/postcss.js

@@ -0,0 +1,7 @@
+// @ts-check
+// Autoprefixer over the CSS a build ships, targeting the repo's browserslist (which should extend
+// `@meddleware/frontend-config/browserslist-config`). A repo's postcss.config.js becomes
+//   export { default } from '@meddleware/frontend-config/postcss'
+import autoprefixer from 'autoprefixer'
+
+export default { plugins: [autoprefixer()] }

package/src/shots.js

@@ -0,0 +1,33 @@
+// @ts-check
+// Screenshot matrix for LOOKING at the UI (not assertions): one PNG per state × viewport × theme × season, written to SHOTS_OUT
+// (default test-results/shots). Excluded from `npm run test:e2e` (definePlaywrightConfig ignores screens specs unless SHOTS is
+// set); nothing is compared against a baseline (baselines drift across machines and fonts). Compare runs by eye: shoot before
+// and after a change and read both sets.
+import { test } from '@playwright/test'
+import { VIEWPORTS, applyLook, looks, offline } from './look.js'
+
+/** @typedef {(page: import('@playwright/test').Page) => Promise<void>} State */
+
+/**
+ * Register one test per state × look. Call once, at the top level of an `e2e/screens.spec.ts`.
+ * @param {Record<string, State>} states
+ * @param {{ out?: string }} [options]
+ */
+export function defineShots(states, options = {}) {
+  const out = options.out ?? process.env.SHOTS_OUT ?? 'test-results/shots'
+  for (const { viewport, theme, season } of looks()) {
+    for (const [name, go] of Object.entries(states)) {
+      test(`${name} · ${viewport} · ${theme} · ${season}`, async ({ page }) => {
+        await page.setViewportSize(VIEWPORTS[viewport])
+        await page.emulateMedia({ colorScheme: /** @type {'light' | 'dark'} */ (theme), reducedMotion: 'reduce' })
+        await offline(page)
+        await go(page)
+        await applyLook(page, theme, season)
+        // chromium keeps the plain name; other browsers get a suffix so runs never overwrite each other
+        const project = test.info().project.name
+        const tag = project === 'chromium' ? '' : `.${project}`
+        await page.screenshot({ path: `${out}/${name}.${viewport}.${theme}.${season}${tag}.png`, fullPage: true })
+      })
+    }
+  }
+}

package/src/stylelint.js

@@ -0,0 +1,107 @@
+// @ts-check
+// Stylelint over CSS and the <style> blocks of Vue SFCs: the standard config tuned for a token-driven codebase, no hex colours,
+// token-only values for colour and layering, accessibility rules (@double-great/stylelint-a11y) and browser-support linting
+// against the shared browserslist (stylelint-no-unsupported-browser-features). A repo's stylelint.config.js becomes
+//   import { stylelintConfig } from '@meddleware/frontend-config/stylelint'
+//   export default stylelintConfig()
+import { fileURLToPath } from 'node:url'
+import postcssHtml from 'postcss-html'
+
+// Resolve plugins and the base config from THIS package, not the consumer's directory, so they are found however the consumer's
+// package manager lays out node_modules (stylelint otherwise resolves names relative to the consumer's config file).
+/** @param {string} name */
+const here = (name) => fileURLToPath(import.meta.resolve(name))
+
+/** Colour-bearing properties: a literal colour here bypasses the design tokens (and so the seasons). */
+const COLOUR_PROPERTIES = ['/color$/', 'fill', 'stroke', 'outline-color', 'text-decoration-color', 'caret-color', 'accent-color']
+
+/** Values that carry no colour of their own, so they are allowed where a token is expected. */
+const NEUTRAL_VALUES = ['transparent', 'inherit', 'currentColor', 'currentcolor', 'none', 'initial', 'unset', 'revert', 'auto', '0']
+
+/**
+ * @param {object} [options]
+ * @param {'error' | 'warning' | false} [options.tokens] Severity of the token-only rule. Default `error`; a repo with
+ *   literals still to fix starts at `warning` and moves to `error` in the same release as the fixes.
+ * @param {'error' | 'warning'} [options.compat] Severity of unsupported-browser-feature findings. Default `error`.
+ * @param {string[]} [options.browsers] Browsers to check against. Default: the repo's browserslist (the shared support promise).
+ * @param {Record<string, unknown>} [options.rules] Rule overrides.
+ */
+export function stylelintConfig({ tokens = 'error', compat = 'error', browsers, rules = {} } = {}) {
+  return {
+    extends: [here('stylelint-config-standard')],
+    plugins: [
+      here('stylelint-no-unsupported-browser-features'),
+      here('@double-great/stylelint-a11y'),
+      here('stylelint-declaration-strict-value'),
+    ],
+    overrides: [{ files: ['**/*.vue', '**/*.html'], customSyntax: postcssHtml }],
+    rules: {
+      // The design system leans heavily on custom properties and deliberate ordering; these standard rules are too noisy for
+      // a token-driven codebase.
+      'custom-property-empty-line-before': null,
+      'declaration-empty-line-before': null,
+      'comment-empty-line-before': null,
+      'rule-empty-line-before': null,
+      'at-rule-empty-line-before': null,
+      'no-descending-specificity': null,
+      // BEM-style class names (block__element--modifier) are intentional.
+      'selector-class-pattern': null,
+      // Some presentational SFCs use compact single-line multi-declaration rules.
+      'declaration-block-single-line-max-declarations': null,
+      // Preserve camelCase CSS keyword values (for example text-rendering: optimizeLegibility).
+      'value-keyword-case': null,
+      // Vue SFC scoped-style pseudo-classes.
+      'selector-pseudo-class-no-unknown': [true, { ignorePseudoClasses: ['deep', 'slotted', 'global'] }],
+      // Private panel vars use a leading-underscore convention (--_bg, --_text).
+      'custom-property-pattern': null,
+      // Vendor-prefixed properties are emitted by autoprefixer at build time; the hand-written -webkit-/-moz-
+      // font-smoothing pair is intentional.
+      'property-no-vendor-prefix': null,
+      'value-no-vendor-prefix': null,
+
+      // Colours come from the design tokens, never a literal.
+      'color-no-hex': true,
+
+      ...(tokens
+        ? {
+            'scale-unlimited/declaration-strict-value': [
+              [...COLOUR_PROPERTIES, 'z-index'],
+              { ignoreValues: NEUTRAL_VALUES, disableFix: true, severity: tokens },
+            ],
+          }
+        : {}),
+
+      // Browser support against the shared browserslist. Partial support is accepted: the feature degrades, it does not break.
+      // Three more degrade harmlessly and are ignored on purpose: `resize` (touch Safari has no resizable fields), non-standard
+      // `cursor` values (a pointer-device nicety), and the extended system font keywords (every use has a fallback stack).
+      'plugin/no-unsupported-browser-features': [
+        true,
+        {
+          severity: compat,
+          ignorePartialSupport: true,
+          ignore: ['css-resize', 'css3-cursors', 'extended-system-fonts'],
+          ...(browsers ? { browsers } : {}),
+        },
+      ],
+
+      // Accessibility.
+      // (`a11y/media-prefers-reduced-motion` is off: @meddleware/ui's reset applies one global reduced-motion rule to every app,
+      // so a per-rule media query is redundant noise.)
+      'a11y/media-prefers-reduced-motion': null,
+      'a11y/no-outline-none': true,
+      // (`a11y/selector-pseudo-class-focus` is off: it asks for a `:focus` twin of every `:hover`, but the reset gives every focusable
+      // element a visible `:focus-visible` ring and `a11y/no-outline-none` below stops anything removing it, so a hover-only cosmetic
+      // needs no twin.)
+      'a11y/selector-pseudo-class-focus': null,
+      'a11y/content-property-no-static-value': true,
+      'a11y/font-size-is-readable': true,
+      'a11y/no-obsolete-attribute': true,
+      'a11y/no-obsolete-element': true,
+      'a11y/no-text-align-justify': true,
+
+      ...rules,
+    },
+  }
+}
+
+export default stylelintConfig()

package/src/vite.js

@@ -0,0 +1,87 @@
+// @ts-check
+// Vite build target derived from the repo's browserslist, so the shipped JS and CSS are transformed for exactly the browsers the
+// support promise names (instead of `esnext`, or Vite's own default). In vite.config.ts:
+//   import { viteTarget } from '@meddleware/frontend-config/vite'
+//   export default defineConfig({ build: { target: viteTarget() } })
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import browserslistToEsbuild from 'browserslist-to-esbuild'
+
+/** @param {string | string[]} [queries] Browserslist queries; default: the repo's own configuration. */
+export function viteTarget(queries) {
+  return browserslistToEsbuild(queries)
+}
+
+/** Resolve a package file from the app's own directory, where `@meddleware/ui` and the tokens are installed. */
+function resolveFromApp(/** @type {string} */ specifier) {
+  return createRequire(join(process.cwd(), 'noop.js')).resolve(specifier)
+}
+
+/**
+ * The colour mode and the browser chrome, before the first paint: a Vite plugin for an app's `index.html`.
+ *
+ * - Serves `@meddleware/ui`'s `theme-init.js` at `/theme-init.js` (dev) and emits it into the build, and loads it as the first,
+ *   render-blocking script in `<head>`. It applies the saved (or default) colour mode and the season to `<html>` before anything
+ *   paints, so a page never flashes the wrong theme while its JavaScript loads. It is a same-origin file, so the CSP needs no hash
+ *   and no `'unsafe-inline'`.
+ * - Adds `<meta name="color-scheme" content="light dark">` (native controls and scrollbars follow the theme) and the browser-chrome
+ *   `theme-color` for each colour mode, from the design tokens' page background.
+ *
+ * ```ts
+ * plugins: [vue(), themeInit({ default: 'dark' })]
+ * ```
+ *
+ * @param {object} [options]
+ * @param {'light' | 'dark' | 'system'} [options.default] The mode a first visit gets (a saved choice always wins). Default `system`.
+ * @param {string} [options.scriptPath] The script to serve (default: `@meddleware/ui/theme-init.js` as installed in the app).
+ * @param {{ light: string, dark: string }} [options.colors] The `theme-color` values (default: the tokens' page backgrounds).
+ * @returns {import('vite').Plugin}
+ */
+export function themeInit({ default: mode = 'system', scriptPath, colors } = {}) {
+  const read = () => readFileSync(scriptPath ?? resolveFromApp('@meddleware/ui/theme-init.js'), 'utf8')
+  const chrome = () => {
+    if (colors) return colors
+    const { semantic } = JSON.parse(readFileSync(resolveFromApp('@meddleware/design-tokens/tokens.json'), 'utf8'))
+    return { light: semantic.light.bg, dark: semantic.dark.bg }
+  }
+  return {
+    name: 'meddleware:theme-init',
+    configureServer(server) {
+      server.middlewares.use('/theme-init.js', (_req, res) => {
+        res.setHeader('content-type', 'text/javascript')
+        res.end(read())
+      })
+    },
+    generateBundle() {
+      this.emitFile({ type: 'asset', fileName: 'theme-init.js', source: read() })
+    },
+    transformIndexHtml() {
+      const { light, dark } = chrome()
+      return [
+        { tag: 'script', attrs: { src: '/theme-init.js', 'data-default': mode }, injectTo: 'head-prepend' },
+        { tag: 'meta', attrs: { name: 'color-scheme', content: 'light dark' }, injectTo: 'head' },
+        { tag: 'meta', attrs: { name: 'theme-color', content: light, media: '(prefers-color-scheme: light)' }, injectTo: 'head' },
+        { tag: 'meta', attrs: { name: 'theme-color', content: dark, media: '(prefers-color-scheme: dark)' }, injectTo: 'head' },
+      ]
+    },
+  }
+}
+
+/**
+ * The end-to-end build mode registers a mock wallet and a stub chain client in the app (`@meddleware/wallet-adapter/testing`), which must
+ * never reach a production build. The app's entry loads it only when `import.meta.env.MODE === 'e2e' && import.meta.env.VITE_E2E === '1'`
+ * (both static, so every other build drops the block); this makes `VITE_E2E=1` outside `--mode e2e` a build error instead of a silent no-op.
+ *
+ * ```ts
+ * export default defineConfig(({ mode }) => { assertE2eOnlyInE2eMode(mode, process.env); return { … } })
+ * ```
+ *
+ * @param {string} mode Vite's mode.
+ * @param {Record<string, string | undefined>} env The environment (default: the process's).
+ */
+export function assertE2eOnlyInE2eMode(mode, env = process.env) {
+  if (env.VITE_E2E && mode !== 'e2e') {
+    throw new Error(`VITE_E2E is set but the build mode is "${mode}": the end-to-end build is \`vite build --mode e2e\`, and nothing else may include the test wallet.`)
+  }
+}

package/src/vitest.js

@@ -0,0 +1,52 @@
+// @ts-check
+// Vitest settings for a repo whose code imports the Meddleware UI libraries. Those packages ship ES modules that import their own `.css`
+// files (each component brings its CSS), and Node cannot import a `.css` file. Vitest runs `node_modules` dependencies through Node by
+// default, so the import fails: the libraries have to go through Vite instead, which also gives them the SAME copy of Vue as the code
+// under test (a second copy breaks reactivity across the boundary, which is why tests used to mock `@meddleware/ui`).
+//
+//   // vitest.config.ts (and, in a jsdom test that renders a dialog: beforeAll(installDialogShim))
+//   import { inlineMeddleware } from '@meddleware/frontend-config/vitest'
+//   export default defineConfig({
+//     plugins: [vue()],
+//     resolve: { dedupe: ['vue', '@vue/test-utils'] },
+//     test: { server: { deps: { inline: inlineMeddleware } } },
+//   })
+
+/**
+ * Packages to process through Vite in tests: the ones that import CSS or `.vue` files. Vitest matches these against the module's resolved
+ * file path (`…/node_modules/@meddleware/ui/dist/…`), not the package name, so the patterns match the path.
+ */
+export const inlineMeddleware = [/[\\/]@meddleware[\\/](ui|wallet-adapter|walrus-storage-kit|design-tokens)[\\/]/]
+
+/**
+ * jsdom does not implement `<dialog>` modality (`showModal`, `close`, `returnValue`). This minimal shim models the parts `UiDialog` relies on:
+ * the `open` attribute, `returnValue`, and a `close` event on closing. Call it once (`beforeAll(installDialogShim)`) in a jsdom test that
+ * renders a dialog; the browser's real behaviour (top layer, inert background) is checked by the Playwright suites, not jsdom.
+ */
+export function installDialogShim() {
+  if (typeof HTMLDialogElement === 'undefined') return // a node-environment test file: there is no DOM to patch
+  const proto = /** @type {HTMLDialogElement & { _rv?: string }} */ (HTMLDialogElement.prototype)
+  if (typeof proto.showModal === 'function') return
+  if (!('returnValue' in proto)) {
+    Object.defineProperty(proto, 'returnValue', {
+      configurable: true,
+      get: /** @this {{ _rv?: string }} */ function () {
+        return this._rv ?? ''
+      },
+      set: /** @this {{ _rv?: string }} */ function (/** @type {string} */ v) {
+        this._rv = v
+      },
+    })
+  }
+  proto.showModal = /** @this {HTMLDialogElement} */ function () {
+    this.returnValue = ''
+    this.setAttribute('open', '')
+  }
+  proto.show = proto.showModal
+  proto.close = /** @this {HTMLDialogElement} */ function (returnValue) {
+    if (!this.hasAttribute('open')) return
+    if (returnValue !== undefined) this.returnValue = returnValue
+    this.removeAttribute('open')
+    this.dispatchEvent(new Event('close'))
+  }
+}

package/src/wallet.js

@@ -0,0 +1,38 @@
+// @ts-check
+// Playwright side of the shared mock wallet (`@meddleware/wallet-adapter/testing`, registered by an app's e2e build): connect it
+// through the app's own wallet dialog, or give it a signer that lives in Node, so a key never enters the page.
+
+/** The address the mock wallet connects with (`MOCK_ADDRESS` in wallet-adapter's testing module). */
+export const E2E_ADDRESS = `0x${'a'.repeat(64)}`
+
+/**
+ * Connect the mock wallet as a visitor would: open the wallet dialog, choose the wallet, and wait for the dialog to close.
+ * @param {import('@playwright/test').Page} page
+ * @param {{ wallet?: string, trigger?: string | RegExp }} [options] The wallet's name in the picker; the name of the button that opens the dialog.
+ */
+export async function connectMockWallet(page, { wallet = 'Test Wallet', trigger = 'Connect wallet' } = {}) {
+  await page.getByRole('button', { name: trigger }).first().click()
+  const dialog = page.getByRole('dialog')
+  await dialog.getByRole('button', { name: wallet }).click()
+  await dialog.waitFor({ state: 'hidden' })
+}
+
+/**
+ * @typedef {object} NodeSigner
+ * @property {(transactionJson: string, chain: string) => Promise<{ bytes: string, signature: string }>} [signTransaction]
+ *   Build and sign a transaction (`Transaction.from(json)`); resolves base64 bytes and signature.
+ * @property {(message: string) => Promise<{ signature: string }>} [signPersonalMessage] Sign a personal message (base64 bytes).
+ */
+
+/**
+ * Let the page's mock wallet sign in this Node process. Call it before `page.goto`: the functions are exposed to every page load, and
+ * `installE2eWallet` uses them when they exist.
+ * @param {import('@playwright/test').Page} page
+ * @param {NodeSigner} signer
+ * @param {{ address?: string }} [options] The address the wallet connects with: the signer's own, so the transaction's sender and its signature agree.
+ */
+export async function exposeSigner(page, signer, { address } = {}) {
+  if (address) await page.addInitScript((a) => Object.assign(window, { __e2eWalletAddress: a }), address)
+  if (signer.signTransaction) await page.exposeFunction('__e2eSignTransaction', signer.signTransaction)
+  if (signer.signPersonalMessage) await page.exposeFunction('__e2eSignPersonalMessage', signer.signPersonalMessage)
+}