@blotch/angular-lynx 22.2.2 → 22.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blotch/angular-lynx",
-  "version": "22.2.2",
+  "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": {

package/schematics/add-i18n/index.js

@@ -4,22 +4,26 @@ 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 Lynx's SystemInfo.
+ * locale from the host app's `appLocale` global prop.
  *
- * Four-step setup, each step idempotent so re-running is safe:
- *   1. **angular.json `i18n` block** — declares the source locale so any
- *      `ng extract-i18n` runs produce the right XLIFF.
+ * 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 SystemInfo.language / appLocale and applies it to Angular's
- *      LOCALE_ID token.
+ *      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);
@@ -33,10 +37,14 @@ exports.default = (options) => async (tree) => {
     if (!project) {
         throw new schematics_1.SchematicsException(`Project "${projectName}" not found in angular.json.`);
     }
-    const sourceRoot = (project.sourceRoot ?? `${project.root}/src`);
+    // 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(),
@@ -72,6 +80,15 @@ const addI18nToAngularJson = (projectName) => {
         }
     };
 };
+/**
+ * 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`;

package/schematics/add-tailwind/index.js

@@ -42,15 +42,14 @@ exports.default = (options) => async (tree) => {
 const addTailwindConfig = (projectRoot) => {
     return (tree) => {
         const configPath = `${projectRoot ? projectRoot + '/' : ''}tailwind.config.ts`;
-        // content: ['./src/**/*.ts'] scans only .ts files — AngularLynx components
-        // inline their templates (no .html template files), so all class names
-        // live in TypeScript source. Including .html in the glob would just slow
-        // the watcher down without finding anything.
+        // 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/**/*.ts'],
+  content: ['./src/**/*.{html,ts}'],
   presets: [preset],
 };
 

package/schematics/migrations/accessibility-traits/index.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const workspace_1 = require("@schematics/angular/utility/workspace");
+/**
+ * The singular name, as an attribute, a binding (`[accessibility-trait]`,
+ * `[attr.accessibility-trait]`) or a string, but not part of a longer name
+ * such as `accessibility-traits`.
+ */
+const SINGULAR = /(?<![\w-])accessibility-trait(?![\w-])/g;
+/** Folders that hold no source of the app's own. */
+const SKIPPED_DIRS = new Set(['node_modules', 'dist']);
+/**
+ * Calls `visit` with the path of every template and TypeScript file under
+ * `dir`, skipping dependencies, build output and dot folders.
+ */
+const visitSources = (dir, visit) => {
+    for (const file of dir.subfiles) {
+        if (/\.(html|ts)$/.test(file) && !file.endsWith('.d.ts')) {
+            visit(dir.file(file).path);
+        }
+    }
+    for (const sub of dir.subdirs) {
+        if (!SKIPPED_DIRS.has(sub) && !sub.startsWith('.')) {
+            visitSources(dir.dir(sub), visit);
+        }
+    }
+};
+/**
+ * Renames `accessibility-trait` to `accessibility-traits` in the app's
+ * templates.
+ *
+ * `LYNX_ELEMENTS` declared the input in the singular, but iOS, Android and
+ * Harmony read only the plural, so the attribute did nothing. Now the input
+ * is `accessibility-traits`, and a `[accessibility-trait]` binding no longer
+ * compiles. This renames both the bindings and the static attributes, in
+ * `.html` templates and in the `.ts` files that hold inline ones.
+ */
+exports.default = () => async (tree) => {
+    const workspace = await (0, workspace_1.getWorkspace)(tree);
+    const roots = new Set([
+        '',
+        ...[...workspace.projects.values()].map((project) => project.root),
+    ]);
+    // The workspace root takes in the projects under it, so a file can come up
+    // from more than one root.
+    const files = new Set();
+    for (const root of roots) {
+        visitSources(tree.getDir(root), (path) => files.add(path));
+    }
+    for (const file of files) {
+        const text = tree.readText(file);
+        const updated = text.replace(SINGULAR, 'accessibility-traits');
+        if (updated !== text)
+            tree.overwrite(file, updated);
+    }
+};

package/schematics/migrations/dev-logs-gitignore/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const dev_logs_gitignore_1 = require("../../utility/dev-logs-gitignore");
+/**
+ * Adds `.dev-logs`, where `ng serve` writes `LynxLogger`'s output, to the
+ * workspace's `.gitignore`. `ng add` now adds it to new apps; apps made before
+ * left it to the app, as the debugging guide said.
+ */
+exports.default = () => (0, dev_logs_gitignore_1.ignoreDevLogs)();

package/schematics/migrations/extract-i18n-target/index.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const workspace_1 = require("@schematics/angular/utility/workspace");
+const extract_i18n_target_1 = require("../../utility/extract-i18n-target");
+/**
+ * Gives every AngularLynx app in the workspace an `extract-i18n` target.
+ *
+ * Angular CLI can't pick an extractor for the Lynx build builder by itself,
+ * and neither `ng add` nor `add-i18n` wrote a target, so `ng extract-i18n`
+ * failed with "Cannot determine project or target for command." Now both
+ * write one with the AngularLynx extract-i18n builder. This gives an app made
+ * before the target those schematics would write today: `add-i18n`'s (JSON
+ * in `src/locale`) when the app has an `i18n` block in angular.json, and
+ * `ng add`'s (Angular's defaults) otherwise. A target the app added by hand
+ * with Angular's builder, as the i18n guide showed, switches to the Lynx one,
+ * which also handles imported images, and its options stay as they are: the
+ * app already extracts the format it chose.
+ */
+exports.default = () => (0, workspace_1.updateWorkspace)((workspace) => {
+    for (const project of workspace.projects.values()) {
+        if (project.targets.get('build')?.builder !==
+            '@blotch/angular-lynx-build:application') {
+            continue;
+        }
+        const sourceRoot = project.sourceRoot ?? (project.root ? `${project.root}/src` : 'src');
+        const isNew = !project.targets.has('extract-i18n');
+        (0, extract_i18n_target_1.useLynxExtractI18n)(project, isNew && project.extensions['i18n']
+            ? (0, extract_i18n_target_1.jsonMessagesOptions)(sourceRoot)
+            : {});
+    }
+});

package/schematics/migrations/tailwind-html-templates/index.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const workspace_1 = require("@schematics/angular/utility/workspace");
+/** The Tailwind config files the build looks for. */
+const CONFIG_FILES = [
+    'tailwind.config.ts',
+    'tailwind.config.js',
+    'tailwind.config.mjs',
+    'tailwind.config.cjs',
+];
+/**
+ * The `content` glob that `ng add` and `add-tailwind` wrote, in either quote.
+ */
+const TS_ONLY_GLOB = /(['"])\.\/src\/\*\*\/\*\.ts\1/g;
+/**
+ * Adds `.html` templates to the Tailwind `content` glob the schematics wrote.
+ *
+ * The build used to scan the modules it bundled instead of `content`, so the
+ * glob didn't matter, and classes used only in `.html` templates got no CSS.
+ * Now the build runs Tailwind with `content`, as Angular's own Tailwind setup
+ * does, and the schematics write `./src/**\/*.{html,ts}`. This brings the
+ * glob of an app made before up to date. A glob the app changed is left
+ * alone.
+ */
+exports.default = () => async (tree) => {
+    const workspace = await (0, workspace_1.getWorkspace)(tree);
+    // The schematics write the config at the project root, which is the
+    // workspace root for an app made by `ng new`.
+    const roots = new Set([
+        '',
+        ...[...workspace.projects.values()].map((project) => project.root),
+    ]);
+    for (const root of roots) {
+        for (const name of CONFIG_FILES) {
+            const file = root ? `${root}/${name}` : name;
+            if (!tree.exists(file))
+                continue;
+            const text = tree.readText(file);
+            const updated = text.replace(TS_ONLY_GLOB, (_glob, quote) => `${quote}./src/**/*.{html,ts}${quote}`);
+            if (updated !== text)
+                tree.overwrite(file, updated);
+        }
+    }
+};

package/schematics/migrations.json

@@ -1,4 +1,25 @@
 {
   "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
-  "schematics": {}
+  "schematics": {
+    "tailwind-html-templates": {
+      "version": "22.2.3",
+      "description": "Adds .html templates to the Tailwind content glob, which the build now reads",
+      "factory": "./migrations/tailwind-html-templates/index"
+    },
+    "accessibility-traits": {
+      "version": "22.2.3",
+      "description": "Renames accessibility-trait, which Lynx ignores, to accessibility-traits",
+      "factory": "./migrations/accessibility-traits/index"
+    },
+    "extract-i18n-target": {
+      "version": "22.2.3",
+      "description": "Adds the extract-i18n target that ng extract-i18n needs, with the AngularLynx builder",
+      "factory": "./migrations/extract-i18n-target/index"
+    },
+    "dev-logs-gitignore": {
+      "version": "22.2.3",
+      "description": "Adds .dev-logs, where ng serve writes LynxLogger's output, to .gitignore",
+      "factory": "./migrations/dev-logs-gitignore/index"
+    }
+  }
 }

package/schematics/ng-add/index.js

@@ -4,14 +4,18 @@ 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 dev_logs_gitignore_1 = require("../utility/dev-logs-gitignore");
+const extract_i18n_target_1 = require("../utility/extract-i18n-target");
 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.
+ * app.component.ts) with Lynx equivalents, points `ng build`, `ng serve`,
+ * `ng test` and `ng extract-i18n` at the AngularLynx builders and
+ * `ng generate` at its schematics, git-ignores the `.dev-logs` file that
+ * `ng serve` writes `LynxLogger`'s output to, 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.
@@ -48,6 +52,7 @@ exports.default = (options) => async (tree) => {
         useLynxBuilders(projectName),
         useLynxSchematics(),
         updatePackageScripts(),
+        (0, dev_logs_gitignore_1.ignoreDevLogs)(),
         addCoreDependencies(),
     ];
     // `"false"` is how `ng add ... --tailwind=false` arrives (see schema.ts).
@@ -280,12 +285,14 @@ const withLynxBudgets = (options) => {
     };
 };
 /**
- * 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.
+ * Points `ng build`, `ng serve`, `ng test` and `ng extract-i18n` 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 other
+ * two run Angular's unit-test and extract-i18n builders set up for Lynx. The
+ * build target keeps `ng new`'s Angular compiler options, which the build
+ * plugin, `ng test` and `ng extract-i18n` read, and gains the app's identity
+ * for native builds.
  */
 const useLynxBuilders = (projectName) => (0, workspace_1.updateWorkspace)((workspace) => {
     const project = workspace.projects.get(projectName);
@@ -365,6 +372,7 @@ const useLynxBuilders = (projectName) => (0, workspace_1.updateWorkspace)((works
             defaultConfiguration: test.defaultConfiguration,
         }),
     });
+    (0, extract_i18n_target_1.useLynxExtractI18n)(project);
 });
 /**
  * Makes `ng generate` reach AngularLynx's schematics first, so
@@ -422,7 +430,7 @@ const addTailwindConfig = (projectRoot) => {
 import preset from '@lynx-js/tailwind-preset';
 
 const config: Config = {
-  content: ['./src/**/*.ts'],
+  content: ['./src/**/*.{html,ts}'],
   presets: [preset],
 };
 

package/schematics/utility/dev-logs-gitignore.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ignoreDevLogs = void 0;
+/** An entry that already ignores `.dev-logs`, anchored or not. */
+const DEV_LOGS_ENTRY = /^\/?\.dev-logs\/?\s*$/m;
+/**
+ * Adds `.dev-logs` to the workspace's `.gitignore`. `ng serve` writes
+ * `LynxLogger`'s output to that file, in the folder it runs from, and it
+ * shouldn't be committed. The entry has no leading slash, so it matches
+ * wherever the file is.
+ *
+ * A workspace without a `.gitignore` (`ng new --skip-git`) is left alone,
+ * and so is one that ignores the file already.
+ */
+const ignoreDevLogs = () => (tree) => {
+    const file = '/.gitignore';
+    if (!tree.exists(file))
+        return;
+    const text = tree.readText(file);
+    if (DEV_LOGS_ENTRY.test(text))
+        return;
+    const separator = text === '' || text.endsWith('\n') ? '' : '\n';
+    tree.overwrite(file, `${text}${separator}\n# LynxLogger's output while \`ng serve\` runs\n.dev-logs\n`);
+};
+exports.ignoreDevLogs = ignoreDevLogs;

package/schematics/utility/extract-i18n-target.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonMessagesOptions = exports.useLynxExtractI18n = void 0;
+const LYNX_EXTRACT_I18N_BUILDER = '@blotch/angular-lynx-build:extract-i18n';
+/**
+ * Angular's extract-i18n builders. The Lynx builder hands its options to
+ * `@angular/build:extract-i18n`, and `@angular-devkit/build-angular`'s takes
+ * the same ones, so a target of either works with it unchanged.
+ */
+const ANGULAR_EXTRACT_I18N_BUILDERS = [
+    '@angular/build:extract-i18n',
+    '@angular-devkit/build-angular:extract-i18n',
+];
+/**
+ * Points a project's `extract-i18n` target at the AngularLynx builder, so
+ * `ng extract-i18n` works. Angular CLI picks an extractor by itself only for
+ * a project built with one of Angular's own builders; for the Lynx build
+ * builder it fails with "Cannot determine project or target for command."
+ * Angular's extractor would fail anyway on the first imported image, which
+ * the Lynx builder sets it up for.
+ *
+ * `options` are set where the target doesn't set them already, so a format
+ * or path the app chose stays. A target of Angular's switches builder; a
+ * target with any other builder is the app's own choice, and stays as it is.
+ */
+const useLynxExtractI18n = (project, options = {}) => {
+    const target = project.targets.get('extract-i18n');
+    if (!target) {
+        project.targets.add({
+            name: 'extract-i18n',
+            builder: LYNX_EXTRACT_I18N_BUILDER,
+            ...(Object.keys(options).length > 0 && { options }),
+        });
+        return;
+    }
+    if (target.builder !== LYNX_EXTRACT_I18N_BUILDER &&
+        !ANGULAR_EXTRACT_I18N_BUILDERS.includes(target.builder)) {
+        return;
+    }
+    target.builder = LYNX_EXTRACT_I18N_BUILDER;
+    const missing = Object.entries(options).filter(([name]) => !(name in (target.options ?? {})));
+    if (missing.length > 0) {
+        target.options = { ...target.options, ...Object.fromEntries(missing) };
+    }
+};
+exports.useLynxExtractI18n = useLynxExtractI18n;
+/**
+ * The options `add-i18n` gives the `extract-i18n` target: the messages go as
+ * JSON to `<sourceRoot>/locale/messages.json`, where Angular's i18n guide
+ * keeps translation files. Angular's default format is XLIFF, but an app on
+ * Lynx loads its translations at runtime with `loadTranslations()`, which
+ * takes the JSON file's `translations` object as it is.
+ */
+const jsonMessagesOptions = (sourceRoot) => ({
+    format: 'json',
+    outputPath: `${sourceRoot}/locale`,
+});
+exports.jsonMessagesOptions = jsonMessagesOptions;