@blotch/angular-lynx 22.2.1 → 22.2.2

package/schematics/ng-add/index.js

@@ -0,0 +1,472 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const schematics_1 = require("@angular-devkit/schematics");
+const dependency_1 = require("@schematics/angular/utility/dependency");
+const json_file_1 = require("@schematics/angular/utility/json-file");
+const workspace_1 = require("@schematics/angular/utility/workspace");
+const versions_1 = require("./versions");
+/**
+ * Transforms a standard `ng new` Angular project into a Lynx-native application.
+ * The schematic replaces browser-specific bootstrap (main.ts, app.config.ts,
+ * app.component.ts) with Lynx equivalents, points `ng build`, `ng serve` and
+ * `ng test` at the AngularLynx builders and `ng generate` at its schematics,
+ * and optionally sets up Tailwind with the Lynx preset. Everything else stays
+ * as `ng new` left it: the app needs no build config besides angular.json.
+ * This is a one-shot destructive transform — the old browser-Angular files
+ * are deleted because they reference DOM APIs and HTML elements that don't
+ * exist on the Lynx runtime.
+ */
+exports.default = (options) => async (tree) => {
+    const workspace = await (0, workspace_1.getWorkspace)(tree);
+    const projectName = options.project ??
+        workspace.extensions['defaultProject'] ??
+        [...workspace.projects.keys()][0];
+    if (!projectName) {
+        throw new schematics_1.SchematicsException('No project found. Run this schematic inside an Angular workspace.');
+    }
+    const project = workspace.projects.get(projectName);
+    if (!project) {
+        throw new schematics_1.SchematicsException(`Project "${projectName}" not found in angular.json.`);
+    }
+    const sourceRoot = (project.sourceRoot ?? `${project.root}/src`);
+    const projectRoot = project.root;
+    const prefix = project.extensions['prefix'] ?? 'app';
+    // The tsconfig the app is built with. `ng new` points the build target's
+    // `tsConfig` at tsconfig.app.json.
+    const buildTsConfig = project.targets.get('build')?.options?.['tsConfig'];
+    const appTsconfig = typeof buildTsConfig === 'string'
+        ? buildTsConfig
+        : `${projectRoot ? projectRoot + '/' : ''}tsconfig.app.json`;
+    const rules = [
+        addTemplateFiles(projectRoot, sourceRoot),
+        replaceMainTs(sourceRoot),
+        replaceAppConfig(sourceRoot),
+        replaceApp(sourceRoot, prefix, projectName),
+        deleteOldAppFiles(sourceRoot),
+        excludeTestFilesFromAppBuild(appTsconfig),
+        includeTestFilesInSpecTsconfig(`${projectRoot ? projectRoot + '/' : ''}tsconfig.spec.json`),
+        useLynxBuilders(projectName),
+        useLynxSchematics(),
+        updatePackageScripts(),
+        addCoreDependencies(),
+    ];
+    // `"false"` is how `ng add ... --tailwind=false` arrives (see schema.ts).
+    if (options.tailwind !== false && options.tailwind !== 'false') {
+        rules.push(addTailwindConfig(projectRoot), updateStylesCss(sourceRoot), addTailwindDependencies());
+    }
+    return (0, schematics_1.chain)(rules);
+};
+const addTemplateFiles = (projectRoot, _sourceRoot) => (0, schematics_1.mergeWith)(
+// MergeStrategy.Overwrite is deliberate — `ng add` is meant to be
+// idempotent so re-running it should refresh the template files
+// (src/rspeedy-env.d.ts) to the package's current version. Default merge
+// strategy would error on file collisions.
+(0, schematics_1.apply)((0, schematics_1.url)('../files'), [(0, schematics_1.applyTemplates)({}), (0, schematics_1.move)(projectRoot || '/')]), schematics_1.MergeStrategy.Overwrite);
+const replaceMainTs = (sourceRoot) => {
+    return (tree) => {
+        // `ng new` generates a main.ts that calls bootstrapApplication from
+        // @angular/platform-browser. That platform implementation reaches into
+        // browser globals (document, history, navigator) which don't exist on
+        // Lynx, so we replace the bootstrap entrypoint with the AngularLynx
+        // equivalent that wires the Lynx renderer instead.
+        const mainPath = `${sourceRoot}/main.ts`;
+        const content = `import { bootstrapApplication } from '@blotch/angular-lynx';
+import { App } from './app/app';
+import { appConfig } from './app/app.config';
+
+bootstrapApplication(App, appConfig);
+`;
+        tree.overwrite(mainPath, content);
+    };
+};
+const replaceAppConfig = (sourceRoot) => {
+    return (tree) => {
+        // Two providers are required for any AngularLynx app:
+        //   1. provideZonelessChangeDetection() — Lynx doesn't carry zone.js, so
+        //      Angular must run in zoneless mode (signals + manual change detection
+        //      triggers are the only reactivity path).
+        //   2. provideRenderer() — registers the Lynx RendererFactory2 over
+        //      Angular's default DOM renderer so element creation calls go to
+        //      __CreateElement/__SetAttribute instead of document.createElement.
+        // provideRouter is included by default so the generated App has a working
+        // <router-outlet> for the user to hang their routes off.
+        const configPath = `${sourceRoot}/app/app.config.ts`;
+        const content = `import {
+  type ApplicationConfig,
+  provideZonelessChangeDetection,
+} from '@angular/core';
+import { provideRenderer, provideRouter } from '@blotch/angular-lynx';
+
+import { routes } from './app.routes';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideZonelessChangeDetection(),
+    provideRenderer(),
+    provideRouter(routes),
+  ],
+};
+`;
+        tree.overwrite(configPath, content);
+    };
+};
+const replaceApp = (sourceRoot, prefix, projectName) => {
+    return (tree) => {
+        // `ng new` before Angular 20 generated app.component.ts — delete it and
+        // create app.ts. The Angular 2025 style guide drops the `.component`
+        // suffix, and AngularLynx's component schematic follows the same
+        // convention so the bootstrap component should too.
+        const oldPath = `${sourceRoot}/app/app.component.ts`;
+        if (tree.exists(oldPath)) {
+            tree.delete(oldPath);
+        }
+        // LYNX_ELEMENTS is the directive bundle that registers <view>, <text>,
+        // <scroll-view>, etc. as Angular elements. Without it, the template would
+        // fail compilation because those tags aren't known HTML elements and the
+        // user hasn't yet added CUSTOM_ELEMENTS_SCHEMA (the build plugin injects
+        // it automatically but the type-checker still surfaces template errors).
+        const newPath = `${sourceRoot}/app/app.ts`;
+        const content = `import { Component, signal } from '@angular/core';
+import { RouterOutlet } from '@angular/router';
+import { LYNX_ELEMENTS } from '@blotch/angular-lynx';
+
+@Component({
+  selector: '${prefix}-root',
+  imports: [RouterOutlet, LYNX_ELEMENTS],
+  template: \`
+    <scroll-view scroll-orientation="vertical">
+      <view style="padding: 24px; align-items: center;">
+        <text style="font-size: 24px; font-weight: bold;">{{ title() }}</text>
+        <text style="font-size: 14px; margin-top: 8px; color: #666;">
+          Edit src/app/app.ts to get started
+        </text>
+        <router-outlet />
+      </view>
+    </scroll-view>
+  \`,
+})
+export class App {
+  title = signal('${projectName}');
+}
+`;
+        if (tree.exists(newPath)) {
+            tree.overwrite(newPath, content);
+        }
+        else {
+            tree.create(newPath, content);
+        }
+    };
+};
+const deleteOldAppFiles = (sourceRoot) => {
+    return (tree) => {
+        // Remove files generated by `ng new` that we don't need.
+        // The root component's template and styles are dead once we inline the
+        // template above, and its spec tests the browser template we replaced, so
+        // it would fail if left behind. Angular 20+ names them app.html, app.css
+        // and app.spec.ts; earlier versions used an `app.component.` prefix. We
+        // don't try to migrate the user's existing template/styles because this
+        // schematic is intended for fresh `ng new` projects — running it on an
+        // established app is unsupported.
+        for (const file of [
+            `${sourceRoot}/app/app.html`,
+            `${sourceRoot}/app/app.spec.ts`,
+            `${sourceRoot}/app/app.css`,
+            `${sourceRoot}/app/app.scss`,
+            `${sourceRoot}/app/app.component.html`,
+            `${sourceRoot}/app/app.component.spec.ts`,
+            `${sourceRoot}/app/app.component.css`,
+            `${sourceRoot}/app/app.component.scss`,
+        ]) {
+            if (tree.exists(file)) {
+                tree.delete(file);
+            }
+        }
+    };
+};
+const excludeTestFilesFromAppBuild = (tsconfigPath) => {
+    return (tree) => {
+        // `ng new` excludes `*.spec.ts` from the app build, but AngularLynx's
+        // component and add-testing schematics name tests `*.test.ts`. Left
+        // in, the Rsbuild plugin compiles every test file into the app, and a
+        // test importing the testing library (a devDependency the app bundle
+        // can't resolve) produces build errors.
+        if (!tree.exists(tsconfigPath)) {
+            return;
+        }
+        const tsconfig = new json_file_1.JSONFile(tree, tsconfigPath);
+        const exclude = tsconfig.get(['exclude']);
+        const patterns = Array.isArray(exclude) ? exclude : [];
+        if (!patterns.includes('src/**/*.test.ts')) {
+            tsconfig.modify(['exclude'], [...patterns, 'src/**/*.test.ts']);
+        }
+    };
+};
+const includeTestFilesInSpecTsconfig = (tsconfigPath) => {
+    return (tree) => {
+        // `ng test` compiles `*.test.ts` files alongside `ng new`'s `*.spec.ts`
+        // ones, and AngularLynx's schematics name tests `*.test.ts`. Listed in
+        // tsconfig.spec.json, editors type-check them with the test types
+        // (vitest/globals) instead of treating them as files of no project.
+        if (!tree.exists(tsconfigPath)) {
+            return;
+        }
+        const tsconfig = new json_file_1.JSONFile(tree, tsconfigPath);
+        const include = tsconfig.get(['include']);
+        if (Array.isArray(include) && !include.includes('src/**/*.test.ts')) {
+            tsconfig.modify(['include'], [...include, 'src/**/*.test.ts']);
+        }
+    };
+};
+/**
+ * Angular compiler options from `ng new`'s build target that the Lynx builder
+ * accepts (see @blotch/angular-lynx-build's builders/application/schema.json).
+ * @blotch/rsbuild-plugin-angular-lynx and `ng test` read them from
+ * angular.json; anything else, such as options only the browser builder
+ * knows, would fail the builder's option validation. `optimization` also picks
+ * the bundle's production or development mode.
+ */
+const ANGULAR_BUILD_OPTIONS = new Set([
+    'browser',
+    'tsConfig',
+    'polyfills',
+    'styles',
+    'assets',
+    'scripts',
+    'inlineStyleLanguage',
+    'fileReplacements',
+    'aot',
+    'optimization',
+    'sourceMap',
+    'outputHashing',
+    'i18nMissingTranslation',
+    'budgets',
+    'extractLicenses',
+    'outputPath',
+    'index',
+]);
+const keepAngularOptions = (options) => Object.fromEntries(Object.entries(options ?? {}).filter(([key]) => ANGULAR_BUILD_OPTIONS.has(key)));
+/**
+ * Options of Angular's dev server that the Lynx dev server accepts too (see
+ * @blotch/angular-lynx-build's builders/dev-server/schema.json).
+ */
+const DEV_SERVER_OPTIONS = new Set(['buildTarget', 'port', 'host']);
+const keepDevServerOptions = (options) => Object.fromEntries(Object.entries(options ?? {}).filter(([key]) => DEV_SERVER_OPTIONS.has(key)));
+/**
+ * `ng new`'s initial-bundle budget, sized for a web app's first download.
+ */
+const NG_NEW_INITIAL_BUDGET = { maximumWarning: '500kB', maximumError: '1MB' };
+/**
+ * The initial-bundle budget for a Lynx bundle. It carries more than a web
+ * app's first download: Angular runs on both of Lynx's threads, so the
+ * framework is in it twice, and a new app's bundle is already about 1 MB.
+ * Kept at roughly the same multiples of a new app as Angular's budget.
+ */
+const LYNX_INITIAL_BUDGET = { maximumWarning: '2MB', maximumError: '5MB' };
+/**
+ * A configuration's options with `ng new`'s initial-bundle budget resized for
+ * a Lynx bundle. Budgets the user set differently stay as they are.
+ */
+const withLynxBudgets = (options) => {
+    if (!Array.isArray(options['budgets'])) {
+        return options;
+    }
+    return {
+        ...options,
+        budgets: options['budgets'].map((budget) => budget['type'] === 'initial' &&
+            budget['maximumWarning'] === NG_NEW_INITIAL_BUDGET.maximumWarning &&
+            budget['maximumError'] === NG_NEW_INITIAL_BUDGET.maximumError
+            ? { ...budget, ...LYNX_INITIAL_BUDGET }
+            : budget),
+    };
+};
+/**
+ * Points `ng build`, `ng serve` and `ng test` at the AngularLynx builders.
+ * The first two run rspeedy with @blotch/rsbuild-plugin-angular-lynx added,
+ * and `ng build --platform ios|android` also produces the native app; the
+ * third runs Angular's unit-test builder set up for Lynx. The build target
+ * keeps `ng new`'s Angular compiler options, which the build plugin and
+ * `ng test` read, and gains the app's identity for native builds.
+ */
+const useLynxBuilders = (projectName) => (0, workspace_1.updateWorkspace)((workspace) => {
+    const project = workspace.projects.get(projectName);
+    const build = project.targets.get('build');
+    const configurations = Object.fromEntries(Object.entries(build?.configurations ?? {}).map(([name, options]) => [
+        name,
+        withLynxBudgets(keepAngularOptions(options)),
+    ]));
+    const buildDefinition = {
+        builder: '@blotch/angular-lynx-build:application',
+        options: {
+            ...keepAngularOptions(build?.options),
+            appName: projectName,
+            // A placeholder the user replaces before publishing: the stores
+            // identify the app by it, and it can't change after the first upload.
+            appId: `com.example.${projectName.toLowerCase().replace(/[^a-z0-9]/g, '') || 'app'}`,
+        },
+        configurations,
+        defaultConfiguration: build?.defaultConfiguration ?? 'production',
+    };
+    if (build) {
+        project.targets.delete('build');
+    }
+    project.targets.add({ name: 'build', ...buildDefinition });
+    // The Lynx dev server takes `buildTarget` like Angular's, so `ng new`'s
+    // configurations (production and development, each naming its build
+    // configuration) carry over, and `ng serve -c production` keeps working.
+    // Options only the browser dev server knows (ssl, proxyConfig, ...) are
+    // dropped: they would fail the builder's option validation.
+    // Without a serve target to keep, write the one `ng new` would have, for
+    // the build configurations that exist. Without a development one, serve
+    // the build target's default configuration rather than the dev server's
+    // default (`::development`), which would point at nothing.
+    const serve = project.targets.get('serve');
+    const serveConfigurations = Object.fromEntries(Object.entries(serve?.configurations ??
+        Object.fromEntries(['production', 'development']
+            .filter((name) => name in configurations)
+            .map((name) => [
+            name,
+            { buildTarget: `${projectName}:build:${name}` },
+        ]))).map(([name, options]) => [name, keepDevServerOptions(options)]));
+    const serveDefinition = serve
+        ? {
+            builder: '@blotch/angular-lynx-build:dev-server',
+            options: keepDevServerOptions(serve.options),
+            configurations: serveConfigurations,
+            defaultConfiguration: serve.defaultConfiguration,
+        }
+        : {
+            builder: '@blotch/angular-lynx-build:dev-server',
+            options: 'development' in serveConfigurations
+                ? {}
+                : { buildTarget: `${projectName}:build` },
+            configurations: serveConfigurations,
+            defaultConfiguration: 'development' in serveConfigurations ? 'development' : undefined,
+        };
+    if (serve) {
+        project.targets.delete('serve');
+    }
+    project.targets.add({ name: 'serve', ...serveDefinition });
+    // The Lynx unit-test builder is Angular's, set up for Lynx, so it takes
+    // the same options and `ng new`'s carry over (as do its own, when `ng add`
+    // runs again). Any other test builder (Karma, from older `ng new`
+    // versions) can't run Lynx code; its options don't apply.
+    const test = project.targets.get('test');
+    const keepTest = test?.builder === '@angular/build:unit-test' ||
+        test?.builder === '@blotch/angular-lynx-build:unit-test';
+    if (test) {
+        project.targets.delete('test');
+    }
+    project.targets.add({
+        name: 'test',
+        builder: '@blotch/angular-lynx-build:unit-test',
+        ...(keepTest && {
+            options: test.options,
+            configurations: test.configurations,
+            defaultConfiguration: test.defaultConfiguration,
+        }),
+    });
+});
+/**
+ * Makes `ng generate` reach AngularLynx's schematics first, so
+ * `ng generate component` makes a component with Lynx elements. Angular's own
+ * collection stays after it: AngularLynx only has the schematics that differ
+ * on Lynx, and `ng generate service`, `pipe`, `guard` and the rest come from
+ * Angular's as before.
+ */
+const useLynxSchematics = () => (0, workspace_1.updateWorkspace)((workspace) => {
+    const cli = (workspace.extensions['cli'] ?? {});
+    const collections = Array.isArray(cli['schematicCollections'])
+        ? cli['schematicCollections']
+        : // What Angular CLI uses when the list isn't set.
+            ['@schematics/angular'];
+    workspace.extensions['cli'] = {
+        ...cli,
+        schematicCollections: [
+            '@blotch/angular-lynx',
+            ...collections.filter((collection) => collection !== '@blotch/angular-lynx'),
+        ],
+    };
+});
+const updatePackageScripts = () => {
+    return (tree) => {
+        // `npm start` and `npm run build` go through the Angular CLI, which runs
+        // the AngularLynx builders set up by useLynxBuilders. `ng new` already
+        // writes these (and `npm test` as `ng test`); this keeps them for
+        // projects whose scripts called rspeedy directly.
+        const pkg = new json_file_1.JSONFile(tree, '/package.json');
+        pkg.modify(['scripts', 'start'], 'ng serve');
+        pkg.modify(['scripts', 'build'], 'ng build');
+    };
+};
+const addCoreDependencies = () => {
+    return (0, schematics_1.chain)([
+        // The `ng build`, `ng serve` and `ng test` builders, the one build
+        // dependency an AngularLynx app needs, as `@angular/build` is for a web
+        // app. They bring rspeedy, the rsbuild plugin that compiles Angular, the
+        // QR code plugin and the iOS and Android app builder with them. Taken at
+        // this package's own release, which they were tested with.
+        (0, dependency_1.addDependency)('@blotch/angular-lynx-build', (0, versions_1.ownVersionRange)(), {
+            type: dependency_1.DependencyType.Dev,
+            install: dependency_1.InstallBehavior.Auto,
+        }),
+        (0, dependency_1.addDependency)('@lynx-js/types', versions_1.VERSIONS.lynxTypes, {
+            type: dependency_1.DependencyType.Dev,
+            install: dependency_1.InstallBehavior.Auto,
+        }),
+    ]);
+};
+const addTailwindConfig = (projectRoot) => {
+    return (tree) => {
+        const configPath = `${projectRoot ? projectRoot + '/' : ''}tailwind.config.ts`;
+        const content = `import type { Config } from 'tailwindcss';
+import preset from '@lynx-js/tailwind-preset';
+
+const config: Config = {
+  content: ['./src/**/*.ts'],
+  presets: [preset],
+};
+
+export default config;
+`;
+        if (tree.exists(configPath)) {
+            tree.overwrite(configPath, content);
+        }
+        else {
+            tree.create(configPath, content);
+        }
+    };
+};
+const updateStylesCss = (sourceRoot) => {
+    return (tree) => {
+        const cssPath = `${sourceRoot}/styles.css`;
+        const scssPath = `${sourceRoot}/styles.scss`;
+        const targetPath = tree.exists(scssPath) ? scssPath : cssPath;
+        // Only @tailwind base + utilities — no @tailwind components. Lynx doesn't
+        // support all of Tailwind's component-layer reset rules (e.g. button
+        // resets that reference focus-visible, form input pseudo-classes), and
+        // bundling them in would generate CSS the runtime can't parse, producing
+        // diagnostic noise. The base layer ships with @lynx-js/tailwind-preset's
+        // own Lynx-compatible normalize rules.
+        const content = `@tailwind base;
+@tailwind utilities;
+`;
+        if (tree.exists(targetPath)) {
+            tree.overwrite(targetPath, content);
+        }
+        else {
+            tree.create(cssPath, content);
+        }
+    };
+};
+const addTailwindDependencies = () => {
+    return (0, schematics_1.chain)([
+        (0, dependency_1.addDependency)('tailwindcss', versions_1.VERSIONS.tailwindcss, {
+            type: dependency_1.DependencyType.Dev,
+            install: dependency_1.InstallBehavior.Auto,
+        }),
+        (0, dependency_1.addDependency)('@lynx-js/tailwind-preset', versions_1.VERSIONS.tailwindPreset, {
+            type: dependency_1.DependencyType.Dev,
+            install: dependency_1.InstallBehavior.Auto,
+        }),
+    ]);
+};

package/schematics/ng-add/schema.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/schematics/ng-add/schema.json

@@ -14,10 +14,14 @@
       }
     },
     "tailwind": {
-      "type": "boolean",
+      "type": ["boolean", "string"],
+      "pattern": "^(true|false)$",
       "description": "Whether to add Tailwind CSS with @lynx-js/tailwind-preset.",
       "default": true,
-      "x-prompt": "Would you like to add Tailwind CSS with Lynx preset?"
+      "x-prompt": {
+        "message": "Would you like to add Tailwind CSS with Lynx preset?",
+        "type": "confirmation"
+      }
     }
   },
   "required": []

package/schematics/ng-add/versions.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ownVersionRange = exports.VERSIONS = void 0;
+const tslib_1 = require("tslib");
+const node_fs_1 = require("node:fs");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+/**
+ * Versions of the third-party packages the `ng add @blotch/angular-lynx`
+ * schematics install: the ones AngularLynx is tested with.
+ *
+ * Keep this map in sync when upgrading any Lynx or build-tooling dependency.
+ * It lists none of our own packages or Angular's: those come from
+ * {@link ownVersionRange} and the app's own `@angular/core`, so they can't go
+ * stale.
+ */
+exports.VERSIONS = {
+    /**
+     * @lynx-js/types — TypeScript type definitions for the Lynx runtime APIs
+     */
+    lynxTypes: '^4.3.0',
+    /**
+     * tailwindcss — utility-first CSS framework (optional, controlled by the `tailwind` schema option)
+     */
+    tailwindcss: '^3.4.19',
+    /**
+     * @lynx-js/tailwind-preset — Lynx-specific Tailwind preset with native design tokens
+     */
+    tailwindPreset: '^0.6.0',
+    /**
+     * vitest — fast unit test runner powered by Vite. Only added when the
+     * project has none; `ng new` already adds it.
+     */
+    vitest: '^5.0.0',
+    /**
+     * jsdom — DOM environment for running component tests. Only added when the
+     * project has none; `ng new` already adds it.
+     */
+    jsdom: '^30.0.0',
+};
+/**
+ * The range the schematics install our other packages at
+ * (@blotch/angular-lynx-build, the testing library): the version of
+ * @blotch/angular-lynx they shipped in. Every package is released at one
+ * version (see packages/release), so a range written out here would go stale
+ * at each release unless someone remembered to move it, as `^22.2.1` nearly
+ * shipped in 22.2.2. The E2E tests check that a new app gets this range.
+ *
+ * `../../package.json` is the runtime's package.json both in the repository
+ * and in the published package, where ng-packagr copies it into dist/ beside
+ * the schematics. (`../package.json` is schematics/package.json, which only
+ * marks the schematics as CommonJS.)
+ */
+const ownVersionRange = () => {
+    const { version } = JSON.parse((0, node_fs_1.readFileSync)(node_path_1.default.join(__dirname, '../../package.json'), 'utf8'));
+    return `^${version}`;
+};
+exports.ownVersionRange = ownVersionRange;

package/schematics/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}