@blotch/angular-lynx 22.2.1 → 22.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blotch/angular-lynx",
-  "version": "22.2.1",
+  "version": "22.2.3",
   "description": "Angular renderer for the Lynx cross-platform native UI framework",
   "homepage": "https://github.com/Blotch-Smart-Frames/AngularLynx#readme",
   "bugs": {
@@ -12,11 +12,6 @@
     "url": "git+https://github.com/Blotch-Smart-Frames/AngularLynx.git",
     "directory": "packages/runtime"
   },
-  "files": [
-    "dist",
-    "schematics",
-    "README.md"
-  ],
   "sideEffects": false,
   "exports": {
     "./package.json": {
@@ -46,6 +41,16 @@
       "optional": true
     }
   },
+  "ng-update": {
+    "migrations": "./schematics/migrations.json",
+    "packageGroup": [
+      "@blotch/angular-lynx",
+      "@blotch/angular-lynx-build",
+      "@blotch/angular-lynx-testing-library",
+      "@blotch/rsbuild-plugin-angular-lynx",
+      "@blotch/angular-lynx-native"
+    ]
+  },
   "schematics": "./schematics/collection.json",
   "module": "fesm2022/blotch-angular-lynx.mjs",
   "typings": "types/blotch-angular-lynx.d.ts",

package/schematics/add-i18n/index.js

@@ -0,0 +1,168 @@
+"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 extract_i18n_target_1 = require("../utility/extract-i18n-target");
+/**
+ * Wires Angular's `@angular/localize` package into an AngularLynx app and
+ * provides the Lynx-aware `provideLocale()` provider that reads the active
+ * locale from the host app's `appLocale` global prop.
+ *
+ * Five-step setup, each step idempotent so re-running is safe:
+ *   1. **angular.json `i18n` block** — declares the source locale, which
+ *      `ng extract-i18n` labels the messages with and `provideLocale()`
+ *      falls back to.
+ *   2. **`@angular/localize/init` polyfill** — must run before the app boots
+ *      so the global `$localize` function exists when components are
+ *      instantiated.
+ *   3. **tsconfig `types`** — adds @angular/localize so $localize is typed
+ *      and TypeScript doesn't flag it as an undefined global.
+ *   4. **provideLocale() in app.config** — registers the runtime provider
+ *      that reads `appLocale` (the apps `ng build --platform` makes send the
+ *      phone's language) and applies it to Angular's LOCALE_ID token.
+ *   5. **`extract-i18n` target** — makes `ng extract-i18n` work, writing
+ *      JSON to `src/locale`.
+ */
+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.`);
+    }
+    // Relative to the workspace root, as angular.json's paths are: the
+    // extract-i18n target's outputPath is one, so a root project's must be
+    // `src`, not `/src`.
+    const sourceRoot = project.sourceRoot ?? (project.root ? `${project.root}/src` : 'src');
+    const projectRoot = project.root;
+    return (0, schematics_1.chain)([
+        addI18nToAngularJson(projectName),
+        addExtractI18nTarget(projectName, sourceRoot),
+        addLocalizeTypes(projectRoot),
+        updateAppConfig(sourceRoot),
+        addLocalizeDependency(),
+    ]);
+};
+const addI18nToAngularJson = (projectName) => {
+    return (tree) => {
+        const angularJson = new json_file_1.JSONFile(tree, '/angular.json');
+        const existingI18n = angularJson.get(['projects', projectName, 'i18n']);
+        if (!existingI18n) {
+            angularJson.modify(['projects', projectName, 'i18n'], {
+                sourceLocale: 'en-US',
+            });
+        }
+        // `@angular/localize/init` must be in `polyfills`, not a regular import.
+        // It patches the global `$localize` function before the app boots — if
+        // it's loaded lazily via a normal import, some translated strings can be
+        // called before the patch is in place and throw at runtime.
+        const polyfillsPath = [
+            'projects',
+            projectName,
+            'architect',
+            'build',
+            'options',
+            'polyfills',
+        ];
+        const polyfills = angularJson.get(polyfillsPath) ?? [];
+        if (!polyfills.includes('@angular/localize/init')) {
+            angularJson.modify(polyfillsPath, [
+                ...polyfills,
+                '@angular/localize/init',
+            ]);
+        }
+    };
+};
+/**
+ * Gives the project an `extract-i18n` target (see useLynxExtractI18n) that
+ * writes JSON for `loadTranslations()`. `ng add` already wrote one with
+ * Angular's defaults (XLIFF at the workspace root), so this sets the format
+ * and path on it, unless the app set them itself.
+ */
+const addExtractI18nTarget = (projectName, sourceRoot) => (0, workspace_1.updateWorkspace)((workspace) => {
+    (0, extract_i18n_target_1.useLynxExtractI18n)(workspace.projects.get(projectName), (0, extract_i18n_target_1.jsonMessagesOptions)(sourceRoot));
+});
+const addLocalizeTypes = (projectRoot) => {
+    return (tree) => {
+        const tsconfigPath = `${projectRoot ? projectRoot + '/' : ''}tsconfig.app.json`;
+        if (!tree.exists(tsconfigPath)) {
+            return;
+        }
+        const tsconfig = new json_file_1.JSONFile(tree, tsconfigPath);
+        const types = tsconfig.get(['compilerOptions', 'types']) ?? [];
+        if (!types.includes('@angular/localize')) {
+            tsconfig.modify(['compilerOptions', 'types'], [...types, '@angular/localize']);
+        }
+    };
+};
+const updateAppConfig = (sourceRoot) => {
+    return (tree) => {
+        const configPath = `${sourceRoot}/app/app.config.ts`;
+        if (!tree.exists(configPath)) {
+            return;
+        }
+        let content = tree.readText(configPath);
+        // Idempotency guard: if the user has already imported provideLocale
+        // (either from a previous run or by hand), bail out — re-running would
+        // duplicate the import and the providers entry, breaking the file.
+        if (content.includes('provideLocale')) {
+            return;
+        }
+        // Two paths for adding the symbol to imports:
+        //   - If `@blotch/angular-lynx` is already imported (the common case
+        //     after `ng add @blotch/angular-lynx`), append provideLocale to the
+        //     existing destructured import list. We split on `,` and rebuild so
+        //     trailing commas and whitespace are normalized regardless of the
+        //     user's formatting preferences.
+        //   - Otherwise prepend a brand-new import line at the top of the file.
+        //     This branch shouldn't normally fire (add-i18n is meant to run on
+        //     projects that already went through ng-add), but it keeps the
+        //     schematic self-contained if someone runs it standalone.
+        if (content.includes("from '@blotch/angular-lynx'")) {
+            content = content.replace(/import\s*\{([^}]*)\}\s*from\s*['"]@blotch\/angular-lynx['"]/, (match, imports) => {
+                const importList = imports
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter(Boolean);
+                importList.push('provideLocale');
+                return `import { ${importList.join(', ')} } from '@blotch/angular-lynx'`;
+            });
+        }
+        else {
+            content =
+                `import { provideLocale } from '@blotch/angular-lynx';\n` + content;
+        }
+        // Insert provideLocale() as the FIRST provider so it runs before
+        // anything that might call $localize during construction (e.g. a service
+        // that formats a date with a localized pattern at module load time).
+        // The regex matches `providers: [` and inserts on a new line right
+        // after, preserving the user's indentation/style for the rest of the array.
+        content = content.replace(/providers:\s*\[/, 'providers: [\n    provideLocale(),');
+        tree.overwrite(configPath, content);
+    };
+};
+const addLocalizeDependency = () => {
+    return (tree) => {
+        // @angular/localize must match the rest of Angular, so it takes the app's
+        // own @angular/core range, as Angular Material's `ng add` does for the
+        // Angular packages it adds. A range written out here would install the
+        // wrong major once the app moves to the next Angular.
+        const pkg = new json_file_1.JSONFile(tree, '/package.json');
+        const coreRange = pkg.get(['dependencies', '@angular/core']) ??
+            pkg.get(['devDependencies', '@angular/core']);
+        if (typeof coreRange !== 'string') {
+            throw new schematics_1.SchematicsException("package.json doesn't list @angular/core, so add-i18n can't tell which @angular/localize version matches the app's Angular.");
+        }
+        return (0, dependency_1.addDependency)('@angular/localize', coreRange, {
+            type: dependency_1.DependencyType.Dev,
+            install: dependency_1.InstallBehavior.Auto,
+        });
+    };
+};

package/schematics/add-i18n/schema.js

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

package/schematics/add-tailwind/index.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const schematics_1 = require("@angular-devkit/schematics");
+const dependency_1 = require("@schematics/angular/utility/dependency");
+const workspace_1 = require("@schematics/angular/utility/workspace");
+const versions_1 = require("../ng-add/versions");
+/**
+ * Adds Tailwind CSS to an existing AngularLynx project. This is split out
+ * from `ng-add` because users may opt out of Tailwind at scaffold time
+ * (`ng add @blotch/angular-lynx --tailwind=false`) but later change their
+ * minds — running this schematic later is the supported recovery path.
+ *
+ * Three steps, each idempotent:
+ *   1. **tailwind.config.ts** — written with `@lynx-js/tailwind-preset` as
+ *      the only preset. The preset narrows Tailwind's class output to the
+ *      subset Lynx's CSS engine can parse (no logical properties, no
+ *      `:has()` selectors, no advanced color functions).
+ *   2. **styles.css/scss** — replaced with the Tailwind base + utilities
+ *      layer directives (no components layer; see ng-add for why).
+ *   3. **package.json deps** — adds tailwindcss + the Lynx preset.
+ */
+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;
+    return (0, schematics_1.chain)([
+        addTailwindConfig(projectRoot),
+        updateStylesCss(sourceRoot),
+        addTailwindDependencies(),
+    ]);
+};
+const addTailwindConfig = (projectRoot) => {
+    return (tree) => {
+        const configPath = `${projectRoot ? projectRoot + '/' : ''}tailwind.config.ts`;
+        // The build runs Tailwind with this `content`, so it has to take in both
+        // inline templates (.ts) and the .html templates `ng generate component`
+        // writes by default, as in Angular's own Tailwind setup.
+        const content = `import type { Config } from 'tailwindcss';
+import preset from '@lynx-js/tailwind-preset';
+
+const config: Config = {
+  content: ['./src/**/*.{html,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`;
+        // Prefer styles.scss if it exists (the user picked SCSS at `ng new` time)
+        // — overwriting it with .css content would break their other imports.
+        const targetPath = tree.exists(scssPath) ? scssPath : cssPath;
+        // Only @tailwind base + utilities — no @tailwind components. Lynx's CSS
+        // engine doesn't parse many component-layer reset rules (focus-visible
+        // pseudo-class, form input pseudo-classes), which would produce
+        // diagnostic noise at build time. The base layer ships with the Lynx
+        // preset's own compatibility-safe 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/add-tailwind/schema.js

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

package/schematics/add-testing/index.js

@@ -0,0 +1,80 @@
+"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("../ng-add/versions");
+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.`);
+    }
+    return (0, schematics_1.chain)([
+        useLynxTestBuilder(projectName),
+        updatePackageScripts(),
+        addTestingDependencies(),
+    ]);
+};
+/**
+ * Tests run with `ng test`, through the AngularLynx unit-test builder (which
+ * `ng add` already sets up; this covers projects set up before it). It sets
+ * up the testing library's Lynx environment itself when the package is
+ * installed, so the project needs no Vitest config or setup file of its own.
+ */
+const useLynxTestBuilder = (projectName) => (0, workspace_1.updateWorkspace)((workspace) => {
+    const project = workspace.projects.get(projectName);
+    const test = project.targets.get('test');
+    if (test?.builder === '@blotch/angular-lynx-build:unit-test') {
+        return;
+    }
+    if (test) {
+        project.targets.delete('test');
+    }
+    project.targets.add({
+        name: 'test',
+        builder: '@blotch/angular-lynx-build:unit-test',
+    });
+});
+const updatePackageScripts = () => {
+    return (tree) => {
+        // `ng test` watches by default when run in a terminal, so the separate
+        // watch script this schematic used to add is gone with Vitest's.
+        const pkg = new json_file_1.JSONFile(tree, '/package.json');
+        pkg.modify(['scripts', 'test'], 'ng test');
+        if (pkg.get(['scripts', 'test:watch']) === 'vitest') {
+            pkg.remove(['scripts', 'test:watch']);
+        }
+    };
+};
+const addTestingDependencies = () => {
+    return (0, schematics_1.chain)([
+        // At this package's own release, like the builders `ng add` installs.
+        (0, dependency_1.addDependency)('@blotch/angular-lynx-testing-library', (0, versions_1.ownVersionRange)(), {
+            type: dependency_1.DependencyType.Dev,
+            install: dependency_1.InstallBehavior.Auto,
+        }),
+        // `ng new` already adds vitest and jsdom: keep the project's versions
+        // rather than replacing them (the default), which silently downgraded
+        // every new project. The testing library works with Vitest 4 and 5 and
+        // jsdom 25 to 30. The E2E tests run `npm test` in a fresh `ng new`
+        // project to keep it that way.
+        (0, dependency_1.addDependency)('vitest', versions_1.VERSIONS.vitest, {
+            type: dependency_1.DependencyType.Dev,
+            install: dependency_1.InstallBehavior.Auto,
+            existing: dependency_1.ExistingBehavior.Skip,
+        }),
+        (0, dependency_1.addDependency)('jsdom', versions_1.VERSIONS.jsdom, {
+            type: dependency_1.DependencyType.Dev,
+            install: dependency_1.InstallBehavior.Auto,
+            existing: dependency_1.ExistingBehavior.Skip,
+        }),
+    ]);
+};

package/schematics/add-testing/schema.js

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

package/schematics/collection.json

@@ -11,7 +11,7 @@
       "schema": "./add-tailwind/schema.json"
     },
     "add-testing": {
-      "description": "Adds AngularLynx Testing Library with Vitest to an existing project",
+      "description": "Adds the AngularLynx Testing Library, which `ng test` sets up for rendering components on Lynx",
       "factory": "./add-testing/index",
       "schema": "./add-testing/schema.json"
     },
@@ -21,10 +21,15 @@
       "schema": "./add-i18n/schema.json"
     },
     "component": {
-      "description": "Generates a standalone Angular component with Lynx element template",
+      "description": "Generates a component with Angular's component schematic, with a Lynx element template and LYNX_ELEMENTS imported",
       "factory": "./component/index",
       "schema": "./component/schema.json",
       "aliases": ["c"]
+    },
+    "eject": {
+      "description": "Writes the generated iOS and Android projects into ios/ and android/ for native changes (one-way)",
+      "factory": "./eject/index",
+      "schema": "./eject/schema.json"
     }
   }
 }

package/schematics/component/index.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@angular-devkit/core");
+const schematics_1 = require("@angular-devkit/schematics");
+/**
+ * `ng generate component` for Lynx (`ng add` makes it the one
+ * `ng generate component` runs). Angular's own component schematic generates
+ * the files, so every option, file name and angular.json default works as it
+ * does in any Angular app. Then the component becomes a Lynx one:
+ *
+ *   1. **Its template uses Lynx elements**: `<view><text>…</text></view>`
+ *      instead of `<p>…</p>`, which Lynx has no element for.
+ *   2. **It imports LYNX_ELEMENTS**, the directives that declare Lynx's
+ *      elements to Angular, so the template type-checks in the editor and
+ *      under `ng test`, as it does in the app build.
+ *   3. **Its test renders it on Lynx** when the project has
+ *      @blotch/angular-lynx-testing-library: a `*.test.ts` that renders the
+ *      component through the Lynx renderer, in place of Angular's TestBed
+ *      spec, which renders it with the DOM renderer. Without the library,
+ *      Angular's spec stays: `ng test` runs both.
+ */
+exports.default = (options) => async (tree) => {
+    const before = createdFiles(tree);
+    return (0, schematics_1.chain)([
+        (0, schematics_1.externalSchematic)('@schematics/angular', 'component', withoutUnset(options)),
+        (tree) => {
+            const created = [...createdFiles(tree)].filter((file) => !before.has(file));
+            const componentFile = created.find((file) => file.endsWith('.ts') && !file.endsWith('.spec.ts'));
+            if (!componentFile) {
+                return;
+            }
+            for (const file of created) {
+                if (file.endsWith('.html')) {
+                    tree.overwrite(file, lynxTemplate(tree.readText(file)));
+                }
+            }
+            tree.overwrite(componentFile, lynxComponent(tree.readText(componentFile)));
+            const specFile = created.find((file) => file.endsWith('.spec.ts'));
+            if (specFile && hasTestingLibrary(tree)) {
+                tree.delete(specFile);
+                tree.create(specFile.replace(/\.spec\.ts$/, '.test.ts'), lynxTest(tree.readText(componentFile), componentFile, options.name));
+            }
+        },
+    ]);
+};
+/**
+ * The options the user (or angular.json's defaults for this schematic) set.
+ * Leaving the rest out lets Angular CLI apply angular.json's defaults for
+ * `@schematics/angular:component` (e.g. `style: scss` from
+ * `ng new --style scss`), then Angular's own, as `ng generate component`
+ * does without AngularLynx.
+ */
+const withoutUnset = (options) => Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined));
+/**
+ * The files created so far in this run.
+ */
+const createdFiles = (tree) => new Set(tree.actions
+    .filter((action) => action.kind === 'c')
+    .map((action) => action.path));
+/**
+ * Angular's placeholder paragraph (`<p>name works!</p>`, in a template file
+ * or inline), as Lynx elements. Lynx has no `<p>`: text goes in `<text>`,
+ * inside a `<view>` for layout.
+ */
+const lynxTemplate = (source) => source.replace(/^([ \t]*)<p>\s*([\s\S]*?)\s*<\/p>/m, (_match, indent, text) => `${indent}<view>\n${indent}  <text>${text}</text>\n${indent}</view>`);
+/**
+ * The generated component, with a Lynx template if it's inline, and
+ * LYNX_ELEMENTS among its imports. A component declared in an NgModule
+ * (`--standalone false`) has no `imports` of its own; its module would import
+ * them, so it's left as Angular generates it.
+ */
+const lynxComponent = (source) => {
+    const component = lynxTemplate(source);
+    if (!/^\s*imports: \[\],$/m.test(component)) {
+        return component;
+    }
+    return component
+        .replace(/^(\s*)imports: \[\],$/m, '$1imports: [LYNX_ELEMENTS],')
+        .replace(/^(import .* from '@angular\/core';)$/m, "$1\nimport { LYNX_ELEMENTS } from '@blotch/angular-lynx';");
+};
+const hasTestingLibrary = (tree) => {
+    if (!tree.exists('/package.json')) {
+        return false;
+    }
+    const packageJson = tree.readJson('/package.json');
+    return [packageJson.dependencies, packageJson.devDependencies].some((dependencies) => dependencies?.['@blotch/angular-lynx-testing-library'] !== undefined);
+};
+/**
+ * A test that renders the component on Lynx with the testing library and
+ * finds its placeholder text, in place of Angular's TestBed spec.
+ */
+const lynxTest = (component, componentFile, name) => {
+    const className = /export (?:default )?class (\w+)/.exec(component)[1];
+    const isDefault = /export default class/.test(component);
+    const importPath = `./${componentFile.split('/').pop().replace(/\.ts$/, '')}`;
+    // The text Angular's template says: the name's last segment, dasherized.
+    const text = `${core_1.strings.dasherize(name.split('/').pop())} works!`;
+    return `import { render } from '@blotch/angular-lynx-testing-library';
+import { describe, expect, it } from 'vitest';
+
+import ${isDefault ? className : `{ ${className} }`} from '${importPath}';
+
+describe('${className}', () => {
+  it('should render', async () => {
+    const { getByText } = await render(${className});
+    expect(getByText('${text}')).toBeTruthy();
+  });
+});
+`;
+};

package/schematics/component/schema.js

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