@g9tm/lynxcontrols 0.0.0-stage → 1.4.0

package/rspeedy/index.mjs

@@ -0,0 +1,75 @@
+// @g9tm/lynxcontrols/rspeedy: the build plugin every app that renders G9 controls adds to its `lynx.config`.
+//
+// G9 colours are CSS custom properties (`--g9-*`, set on the provider root) used through `var(--g9-*)`, also in inline
+// styles (`g9Token('Primary')`). The Lynx engine ignores custom properties and `var()` in INLINE styles unless the page
+// config `enableCSSInlineVariables` is on, and the ReactLynx plugin has no option for it. Verified in a Lynxtron
+// 0.0.28 window on Windows (2026-10-05): with the flag, inline declarations, inline `var()` and inheritance all work;
+// without it the gallery rendered a black page with invisible text. This plugin turns the flag on through the template
+// plugin's `beforeEncode` hook. Plain Node ESM (it runs in the build, never in the Lynx bundle).
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/** The page-config flags G9 needs; exported for tests and for apps that wire the hook themselves. */
+export const g9PageConfig = Object.freeze({ enableCSSInlineVariables: true });
+
+/** The directory of package `name` visible from `from` (Node's node_modules walk), or null. */
+function packageDir(name, from) {
+  for (let dir = from; ; dir = dirname(dir)) {
+    const candidate = join(dir, 'node_modules', name);
+    if (existsSync(join(candidate, 'package.json'))) return realpathSync(candidate);
+    if (dirname(dir) === dir) return null;
+  }
+}
+
+/** The ESM entry of an installed package (`exports["."]` import/default, else `module`/`main`). */
+function entryOf(dir) {
+  const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+  let target = manifest.exports?.['.'] ?? manifest.exports;
+  while (target && typeof target === 'object') target = target.import ?? target.default ?? target.node;
+  return join(dir, typeof target === 'string' ? target : (manifest.module ?? manifest.main ?? 'index.js'));
+}
+
+/** Loads the template plugin the app's ReactLynx build uses (its hooks are per module instance). */
+export async function loadTemplatePlugin(context) {
+  const name = '@lynx-js/template-webpack-plugin';
+  // Hoisted installs: next to the app; strict installs (pnpm): next to the ReactLynx plugin, which depends on it.
+  const react = packageDir('@lynx-js/react-rsbuild-plugin', context);
+  const dir = packageDir(name, context) ?? (react ? packageDir(name, react) : null);
+  if (!dir) throw new Error(`pluginG9Lynx: ${name} is not installed (it comes with @lynx-js/react-rsbuild-plugin).`);
+  return (await import(pathToFileURL(entryOf(dir)).href)).LynxTemplatePlugin;
+}
+
+/** The rspack plugin: sets {@link g9PageConfig} on every template the compilation encodes. */
+export class G9PageConfigPlugin {
+  constructor(templatePlugin, pageConfig = g9PageConfig) {
+    this.templatePlugin = templatePlugin;
+    this.pageConfig = pageConfig;
+  }
+
+  apply(compiler) {
+    compiler.hooks.thisCompilation.tap('G9PageConfigPlugin', (compilation) => {
+      this.templatePlugin.getLynxTemplatePluginHooks(compilation).beforeEncode.tap('G9PageConfigPlugin', (args) => {
+        Object.assign(args.encodeData.sourceContent.config, this.pageConfig);
+        return args;
+      });
+    });
+  }
+}
+
+/**
+ * The rspeedy / Rsbuild plugin: `plugins: [pluginReactLynx(), pluginG9Lynx()]` in `lynx.config.ts`. Required for
+ * correct colours on every platform.
+ */
+export function pluginG9Lynx() {
+  return {
+    name: 'g9lynx:page-config',
+    async setup(api) {
+      const templatePlugin = await loadTemplatePlugin(api.context.rootPath);
+      api.modifyRspackConfig((config) => {
+        config.plugins = [...(config.plugins ?? []), new G9PageConfigPlugin(templatePlugin)];
+        return config;
+      });
+    },
+  };
+}

package/rspeedy/index.test.mjs

@@ -0,0 +1,52 @@
+// pluginG9Lynx() puts `enableCSSInlineVariables` into every template's page config (without it the engine ignores
+// inline CSS variables; Lynxtron window, 2026-10-05). The built gallery bundle is checked for the key by
+// `npm run check:bundle`, the packed consumer by `npm run check:consumer`; this file tests the wiring. Node's runner,
+// not Rstest: the Lynx test environment rewrites dynamic import(), which the plugin uses at build time.
+import assert from 'node:assert/strict';
+import { parse } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { G9PageConfigPlugin, g9PageConfig, loadTemplatePlugin, pluginG9Lynx } from './index.mjs';
+
+const repo = fileURLToPath(new URL('../../../', import.meta.url));
+
+function fakeBuild() {
+  const taps = [];
+  const compilation = {};
+  const templatePlugin = {
+    getLynxTemplatePluginHooks: (c) => {
+      assert.equal(c, compilation);
+      return { beforeEncode: { tap: (_name, fn) => taps.push(fn) } };
+    },
+  };
+  const compiler = { hooks: { thisCompilation: { tap: (_name, fn) => fn(compilation) } } };
+  return { taps, templatePlugin, compiler };
+}
+
+test('sets the page config on every encoded template, keeping the other keys', () => {
+  const build = fakeBuild();
+  new G9PageConfigPlugin(build.templatePlugin).apply(build.compiler);
+  const args = { encodeData: { sourceContent: { config: { enableNewGesture: true } } } };
+  assert.equal(build.taps[0](args), args);
+  assert.deepEqual(args.encodeData.sourceContent.config, { enableNewGesture: true, enableCSSInlineVariables: true });
+  assert.deepEqual(g9PageConfig, { enableCSSInlineVariables: true });
+});
+
+test("loads the app's own LynxTemplatePlugin (the hooks are per module instance)", async () => {
+  const plugin = await loadTemplatePlugin(repo);
+  assert.equal(typeof plugin.getLynxTemplatePluginHooks, 'function');
+  // The file-system root has no node_modules with the template plugin.
+  await assert.rejects(loadTemplatePlugin(parse(repo).root), /not installed/);
+});
+
+test('adds the rspack plugin through modifyRspackConfig', async () => {
+  let modify;
+  const api = { context: { rootPath: repo }, modifyRspackConfig: (fn) => (modify = fn) };
+  const plugin = pluginG9Lynx();
+  assert.equal(plugin.name, 'g9lynx:page-config');
+  await plugin.setup(api);
+  const config = modify({ plugins: ['existing'] });
+  assert.equal(config.plugins[0], 'existing');
+  assert.ok(config.plugins[1] instanceof G9PageConfigPlugin);
+  assert.equal(modify({}).plugins.length, 1);
+});