@lilaquadrat/design-core 0.1.0

package/tooling/preview.plugin.ts

@@ -0,0 +1,134 @@
+import type { Plugin, UserConfig } from 'vite';
+
+const OUTPUT_DIR = 'dist/preview';
+const PREVIEW_ASSET_DIR = 'previewAssets';
+
+function escapeRegExp (input: string) {
+
+  return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+}
+
+/**
+ * drops the gallery fixture images from every build that is not the preview.
+ *
+ * the viewData fixtures import them statically, and vite emits an imported asset
+ * while transforming - so even though rolldown tree shakes preview.view.vue out
+ * of the app bundle, the images survive as orphans nobody references.
+ */
+export function dropPreviewAssets (): Plugin {
+
+  return {
+    name   : 'drop-preview-assets',
+    enforce: 'post',
+    apply  : 'build',
+    generateBundle (_options, bundle: Record<string, any>) {
+
+      Object.keys(bundle).forEach((fileName) => {
+
+        const single = bundle[fileName];
+
+        if(single.type !== 'asset') return;
+
+        const origins: string[] = [single.originalFileName, ...single.originalFileNames ?? []].filter(Boolean);
+
+        if(origins.some((origin) => origin.includes(PREVIEW_ASSET_DIR))) delete bundle[fileName];
+
+      });
+
+    }
+  };
+
+}
+
+/**
+ * build overrides for the shareable static gallery (yarn build:preview).
+ *
+ * everything here exists because the output is opened straight from disk, where
+ * each file is its own opaque origin.
+ */
+export function previewBuildOptions (base: UserConfig['build']): UserConfig['build'] {
+
+  return {
+    ...base,
+    /**
+     * inline fonts and images as data URIs: browsers block the font fetches a
+     * separate .woff would need
+     */
+    assetsInlineLimit: 512 * 1024,
+    rolldownOptions  : {
+      ...base?.rolldownOptions,
+      output: {
+        ...base?.rolldownOptions?.output,
+        // a single classic script: file:// blocks `type="module"` as cross origin
+        dir           : OUTPUT_DIR,
+        format        : 'iife',
+        codeSplitting : false,
+        entryFileNames: '[name].js',
+      }
+    }
+  };
+
+}
+
+/**
+ * folds the script and the stylesheet into index.html, so the preview is a self
+ * contained file that opens over file:// with no server.
+ */
+export default function previewBundle (): Plugin {
+
+  return {
+    name   : 'preview-bundle',
+    enforce: 'post',
+    apply  : 'build',
+    generateBundle (_options, bundle: Record<string, any>) {
+
+      const html = bundle['index.html'];
+
+      if(!html) return;
+
+      let source = html.source.toString();
+      let script = '';
+
+      Object.keys(bundle).forEach((fileName) => {
+
+        const single = bundle[fileName];
+
+        if(fileName === 'index.html') return;
+
+        if(single.type === 'chunk') {
+
+          // a literal </script> inside the code would end the tag early
+          script += single.code.replace(/<\/script>/gi, '<\\/script>');
+          source = source.replace(new RegExp(`<script[^>]*src="[^"]*${escapeRegExp(fileName)}"[^>]*></script>\\s*`), '');
+          delete bundle[fileName];
+          return;
+
+        }
+
+        if(fileName.endsWith('.css')) {
+
+          // replacer functions only: a replacement string would expand $& and
+          // $\` in the asset as substitution patterns
+          source = source.replace(new RegExp(`<link[^>]*href="[^"]*${escapeRegExp(fileName)}"[^>]*>`), () => `<style>${single.source}</style>`);
+          delete bundle[fileName];
+
+        }
+
+      });
+
+      source = source.replace(/<link[^>]*rel="modulepreload"[^>]*>\s*/g, '');
+      // the manifest is the one head asset a file:// origin cannot fetch
+      source = source.replace(/<link[^>]*rel="manifest"[^>]*>\s*/g, '');
+      Object.keys(bundle).filter((fileName) => fileName.endsWith('.webmanifest')).forEach((fileName) => delete bundle[fileName]);
+
+      /**
+       * at the end of the body, not in place: an inline script has no `defer`,
+       * so in the head it would run before #app exists
+       */
+      html.source = source.replace('</body>', () => `<script>${script}</script>\n</body>`);
+
+    }
+  };
+
+}

package/tooling/ssr-test/index.mjs

@@ -0,0 +1,391 @@
+/**
+ * SSR preflight for a design.
+ *
+ * Renders every page a design can produce through the real ssr build - the same
+ * dist/server/server-entry.js that gets published - and fails if anything in it
+ * throws, warns, or comes back empty.
+ *
+ * It exists because the production renderer is forgiving in the worst way:
+ * RenderClass.renderSingle collects the renders with Promise.allSettled and only
+ * console.errors a rejected one, so a page that blows up during SSR is silently
+ * published as an empty shell. This suite is the gate before that happens.
+ *
+ * Offline by design: everything comes from the build output and the fixtures
+ * bundle, nothing talks to an api.
+ */
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+const DEFAULT_PATHS = {
+  serverEntry : 'dist/server/server-entry.js',
+  manifest    : 'dist/server/.vite/ssr-manifest.json',
+  template    : 'dist/server/index.server.html',
+  mailTemplate: 'dist/server/index.mail.html',
+};
+/**
+ * the app logs its startup through mixins/logger, which is console.log - only
+ * warnings and errors are interesting here
+ */
+const VUE_WARN = '[Vue warn]';
+
+/**
+ * mirrors RenderClass.createGenericContext: the shape the STUDIO renderer hands
+ * to render(), minus the parts that only matter for asset urls.
+ */
+function createContext (content, options = {}) {
+
+  return {
+    data        : content,
+    layout      : options.layout,
+    settings    : {
+      name   : content.company ? `${content.company}-${content.project}` : 'preflight',
+      company: content.company ?? 'preflight',
+      project: content.project ?? 'preflight',
+      mode   : content.settings?.mode ?? 'presentation',
+    },
+    tags        : content.tags,
+    cdn         : '',
+    renderTarget: options.renderTarget ?? 'web',
+  };
+
+}
+
+/**
+ * turns a fixture into a site the renderer can address: a filename to look up
+ * and a url that resolves to it, exactly as Publish.action stores one.
+ */
+function createSite (name, content, options = {}) {
+  const target = options.target ?? content.target;
+  const filename = target === 'mail'
+    ? ['mail']
+    : content.settings?.filename ?? [name];
+  const site = {
+    ...content,
+    id      : content.id ?? name,
+    state   : content.state ?? 'publish',
+    settings: {
+      mode : 'presentation',
+      title: name,
+      ...content.settings,
+      filename,
+    },
+  };
+
+  if (target) site.target = target;
+
+  return { name, site, url: site.settings.url || filename[0] };
+
+}
+
+/**
+ * vue reports a failed serverPrefetch and an unresolved component through the
+ * console rather than by rejecting, so the console is part of the assertion.
+ */
+async function captureConsole (run) {
+
+  const captured = { errors: [], warnings: [] };
+  const originalError = console.error;
+  const originalWarn = console.warn;
+
+  console.error = (...args) => captured.errors.push(args.map(stringify).join(' '));
+  console.warn = (...args) => captured.warnings.push(args.map(stringify).join(' '));
+
+  try {
+
+    const result = await run();
+
+    return { result, captured };
+
+  } finally {
+
+    console.error = originalError;
+    console.warn = originalWarn;
+
+  }
+
+}
+
+function stringify (value) {
+
+  if (value instanceof Error) return `${value.message}\n${value.stack}`;
+  if (typeof value === 'string') return value;
+
+  try {
+
+    return JSON.stringify(value);
+
+  } catch {
+
+    return String(value);
+
+  }
+
+}
+
+function assembleDocument (template, rendered) {
+
+  return template
+    .replace('<!--preload-links-->', rendered.preloadLinks)
+    .replace('<!--ssr-outlet-->', rendered.html)
+    .replace('<!--pinia-state-->', `<script>window.__INITIAL_STATE__ = ${rendered.initialState}</script>`);
+
+}
+
+/**
+ * every marker a module could plausibly put on its root element. the class is a
+ * convention, not a contract - a handful of modules render no wrapper at all -
+ * so a miss is reported, never asserted.
+ */
+function moduleMarkers (type, overrides = {}) {
+
+  if (overrides[type]) return overrides[type];
+
+  const base = type.replace(/-module$/, '');
+
+  return [`lila-${base}-module`, `${base}-module`, `lila-${base}`];
+
+}
+
+/**
+ * splits captured console output into what the suite must fail on and what the
+ * project has declared as expected - a page that needs data only the backend
+ * has (a structure declaration, a payment provider) complains offline, and that
+ * complaint is not a regression.
+ */
+function splitAllowed (messages, allowed) {
+
+  const unexpected = [];
+  const expected = [];
+
+  messages.forEach((single) => {
+
+    if (allowed.some((pattern) => pattern.test(single))) {
+
+      expected.push(single);
+
+    } else {
+
+      unexpected.push(single);
+
+    }
+
+  });
+
+  return { unexpected, expected };
+
+}
+
+function assertRendered (name, rendered, captured, options = {}) {
+
+  const allowed = options.allowedConsole ?? [];
+  const errors = splitAllowed(captured.errors, allowed);
+  const warnings = splitAllowed(
+    captured.warnings.filter((single) => single.includes(VUE_WARN)),
+    allowed,
+  );
+
+  assert.ok(rendered, `${name}: render returned nothing`);
+  assert.equal(
+    errors.unexpected.length,
+    0,
+    `${name}: console.error during render\n${errors.unexpected.join('\n')}`,
+  );
+  assert.equal(
+    warnings.unexpected.length,
+    0,
+    `${name}: vue warnings during render\n${warnings.unexpected.join('\n')}`,
+  );
+
+  if (options.onExpected && (errors.expected.length || warnings.expected.length)) {
+
+    options.onExpected([...errors.expected, ...warnings.expected]);
+
+  }
+  assert.equal(typeof rendered.html, 'string', `${name}: html is not a string`);
+
+  const contentMarker = options.contentMarker ?? 'lila-content-module';
+
+  if (contentMarker) {
+
+    assert.ok(
+      rendered.html.includes(contentMarker),
+      `${name}: ${contentMarker} did not render - the page would publish as an empty shell`,
+    );
+
+  }
+
+  assert.doesNotThrow(
+    () => JSON.parse(rendered.initialState),
+    `${name}: initialState is not valid json, hydration would fail`,
+  );
+
+}
+
+async function loadRenderer (root, paths) {
+
+  const serverEntry = resolve(root, paths.serverEntry);
+  const renderer = await import(serverEntry);
+
+  assert.equal(typeof renderer.render, 'function', `${paths.serverEntry} does not export render()`);
+
+  return renderer;
+
+}
+
+async function loadJson (root, path) {
+
+  return JSON.parse(await readFile(resolve(root, path), 'utf-8'));
+
+}
+
+/**
+ * registers the whole preflight against node:test.
+ *
+ * @param {object} options
+ * @param {string} [options.root] project root, defaults to process.cwd()
+ * @param {object} options.fixtures the built fixtures bundle: { viewData, modules, mailModules }
+ * @param {object} [options.paths] overrides for the build output locations
+ * @param {boolean} [options.variants] also render every registered variant on its own, default true
+ * @param {RegExp[]} [options.allowedConsole] console output the project expects offline, reported instead of failed
+ * @param {Record<string, string[]>} [options.markers] root markers for modules whose class does not follow from their type
+ */
+export async function runSsrSuite (options) {
+
+  const root = options.root ?? process.cwd();
+  const paths = { ...DEFAULT_PATHS, ...options.paths };
+  const fixtures = options.fixtures;
+  const withVariants = options.variants !== false;
+  const allowedConsole = options.allowedConsole ?? [];
+  const markers = options.markers ?? {};
+  const renderer = await loadRenderer(root, paths);
+  const manifest = await loadJson(root, paths.manifest);
+  const template = await readFile(resolve(root, paths.template), 'utf-8');
+
+  async function render (entry, renderOptions = {}) {
+
+    return captureConsole(() => renderer.render(
+      entry.url,
+      createContext(entry.site, renderOptions),
+      renderOptions.contextData ?? null,
+      renderOptions.recipient ?? null,
+      renderOptions.list ?? null,
+      manifest,
+      { cdnUrl: '' },
+    ));
+
+  }
+
+  describe('ssr: viewData renders as its own site', () => {
+
+    Object.entries(fixtures.viewData ?? {}).forEach(([name, content]) => {
+
+      it(name, async (t) => {
+
+        if (!Array.isArray(content?.modules)) {
+
+          t.diagnostic(`${name} is not page content (no modules array) - skipped`);
+          return;
+
+        }
+
+        const entry = createSite(name, content);
+        const { result, captured } = await render(entry);
+
+        assertRendered(name, result, captured, {
+          allowedConsole,
+          onExpected: (messages) => t.diagnostic(`${name}: expected offline complaints\n${messages.join('\n')}`),
+        });
+
+        const document = assembleDocument(template, result);
+
+        assert.ok(
+          !document.includes('<!--ssr-outlet-->'),
+          `${name}: the html template still holds its placeholder`,
+        );
+
+        content.modules.forEach((single) => {
+
+          if (!single?.type) return;
+
+          const found = moduleMarkers(single.type, markers).some((marker) => result.html.includes(marker));
+
+          if (!found) t.diagnostic(`${name}: no root marker found for ${single.type}`);
+
+        });
+
+      });
+
+    });
+
+  });
+
+  describe('ssr: every module renders with no data at all', () => {
+
+    (fixtures.modules ?? []).forEach((single) => {
+
+      const type = `${single.name}-module`;
+
+      it(type, async () => {
+
+        const entry = createSite(`empty-${single.name}`, {
+          modules: [{ type, uuid: `empty-${single.name}` }],
+        });
+        const { result, captured } = await render(entry);
+
+        assertRendered(type, result, captured, { allowedConsole });
+
+      });
+
+      if (!withVariants) return;
+
+      (single.variants ?? []).forEach((variant) => {
+
+        if (!variant?.key) return;
+
+        it(`${type} [${variant.key}]`, async () => {
+
+          const entry = createSite(`empty-${single.name}-${variant.key}`, {
+            modules: [{ type, uuid: `empty-${single.name}-${variant.key}`, variant: [variant.key] }],
+          });
+          const { result, captured } = await render(entry);
+
+          assertRendered(`${type} [${variant.key}]`, result, captured, { allowedConsole });
+
+        });
+
+      });
+
+    });
+
+  });
+
+  if (!fixtures.mailModules?.length) return;
+
+  describe('ssr: every mail module renders with no data at all', () => {
+
+    fixtures.mailModules.forEach((single) => {
+
+      const type = `${single.name}-module`;
+
+      it(type, async () => {
+
+        const entry = createSite(`empty-mail-${single.name}`, {
+          target : 'mail',
+          modules: [{ type, uuid: `empty-mail-${single.name}` }],
+        }, { target: 'mail' });
+        const { result, captured } = await render(entry);
+
+        assertRendered(type, result, captured, { allowedConsole });
+
+      });
+
+    });
+
+  });
+
+}
+
+export default runSsrSuite;
+export { createSite, createContext, assembleDocument, captureConsole };

package/tooling/stylelint.config.mjs

@@ -0,0 +1,24 @@
+/** @type {import('stylelint').Config} */
+export default {
+  'extends': [
+    'stylelint-config-html',
+    'stylelint-config-recommended-vue'
+  ],
+  'plugins': [
+    'stylelint-order'
+  ],
+  'overrides': [
+    {
+      'files'       : ['*.vue', '**/*.vue'],
+      'customSyntax': 'postcss-html'
+    },
+    {
+      'files'       : ['*.less', '**/*.less'],
+      'customSyntax': 'postcss-less'
+    }
+  ],
+  'rules': {
+    'media-query-no-invalid'               : null,
+    'declaration-property-value-no-unknown': null
+  }
+}