@blotch/angular-lynx 22.2.1 → 22.2.3

package/schematics/component/schema.json

@@ -2,58 +2,135 @@
   "$schema": "http://json-schema.org/draft-07/schema",
   "$id": "SchematicsAngularLynxComponent",
   "title": "AngularLynx component schematic",
+  "description": "Generates a component with Angular's component schematic, then makes it a Lynx one: its template uses Lynx elements and it imports LYNX_ELEMENTS. The options are Angular's (a test keeps them in step); left out, they take the defaults angular.json sets for @schematics/angular:component, then Angular's.",
   "type": "object",
   "additionalProperties": false,
-  "description": "Generates a standalone Angular component with Lynx element template.",
   "properties": {
-    "name": {
-      "type": "string",
-      "description": "The name of the component.",
-      "$default": {
-        "$source": "argv",
-        "index": 0
-      },
-      "x-prompt": "What name would you like to use for the component?"
-    },
     "path": {
       "type": "string",
       "format": "path",
-      "description": "The path at which to create the component, relative to the source root.",
+      "$default": {
+        "$source": "workingDirectory"
+      },
+      "description": "The path where the component files should be created, relative to the current workspace. If not provided, a folder with the same name as the component will be created in the project's `src/app` directory.",
       "visible": false
     },
     "project": {
       "type": "string",
-      "description": "The name of the project.",
+      "description": "The name of the project where the component should be added. If not specified, the CLI will determine the project from the current directory.",
       "$default": {
         "$source": "projectName"
       }
     },
-    "prefix": {
+    "name": {
       "type": "string",
-      "description": "The selector prefix to use. Defaults to the project prefix from angular.json."
+      "description": "The name for the new component. This will be used to create the component's class, template, and stylesheet files. For example, if you provide `my-component`, the files will be named `my-component.ts`, `my-component.html`, and `my-component.css`.",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What name would you like to use for the component?"
+    },
+    "displayBlock": {
+      "description": "Adds `:host { display: block; }` to the component's stylesheet, ensuring the component renders as a block-level element. This is useful for layout purposes.",
+      "type": "boolean",
+      "alias": "b"
     },
     "inlineStyle": {
+      "description": "Include the component's styles directly in the `component.ts` file. By default, a separate stylesheet file (e.g., `my-component.css`) is created.",
       "type": "boolean",
-      "description": "Include styles inline in the component.ts file.",
-      "default": true,
-      "alias": "s"
+      "alias": "s",
+      "x-user-analytics": "ep.ng_inline_style"
     },
     "inlineTemplate": {
+      "description": "Include the component's HTML template directly in the `component.ts` file. By default, a separate template file (e.g., `my-component.html`) is created.",
+      "type": "boolean",
+      "alias": "t",
+      "x-user-analytics": "ep.ng_inline_template"
+    },
+    "standalone": {
+      "description": "Generate a standalone component. Standalone components are self-contained and don't need to be declared in an NgModule. They can be used independently or imported directly into other standalone components.",
+      "type": "boolean",
+      "x-user-analytics": "ep.ng_standalone"
+    },
+    "viewEncapsulation": {
+      "description": "Sets the view encapsulation mode for the component. This determines how the component's styles are scoped and applied.",
+      "enum": ["Emulated", "None", "ShadowDom"],
+      "type": "string",
+      "alias": "v"
+    },
+    "changeDetection": {
+      "description": "Configures the change detection strategy for the component.",
+      "enum": ["Eager", "OnPush"],
+      "type": "string",
+      "alias": "c"
+    },
+    "prefix": {
+      "type": "string",
+      "description": "A prefix to be added to the component's selector. For example, if the prefix is `app` and the component name is `my-component`, the selector will be `app-my-component`.",
+      "alias": "p",
+      "oneOf": [
+        {
+          "maxLength": 0
+        },
+        {
+          "minLength": 1,
+          "format": "html-selector"
+        }
+      ]
+    },
+    "style": {
+      "description": "Specify the type of stylesheet to be created for the component, or `none` to skip creating a stylesheet.",
+      "type": "string",
+      "enum": ["css", "scss", "sass", "less", "none"],
+      "x-user-analytics": "ep.ng_style"
+    },
+    "type": {
+      "type": "string",
+      "description": "Append a custom type to the component's filename. For example, if you set the type to `container`, the file will be named `my-component.container.ts`."
+    },
+    "addTypeToClassName": {
       "type": "boolean",
-      "description": "Include template inline in the component.ts file.",
-      "default": true,
-      "alias": "t"
+      "description": "When true, the 'type' option will be appended to the generated class name. When false, only the file name will include the type."
     },
     "skipTests": {
       "type": "boolean",
-      "description": "Do not generate a spec file.",
-      "default": false
+      "description": "Skip the generation of unit test files `spec.ts`."
     },
     "flat": {
       "type": "boolean",
-      "description": "Create the component files at the top level of the path, without a subdirectory.",
-      "default": false
+      "description": "Create the component files directly in the project's `src/app` directory instead of creating a new folder for them."
+    },
+    "skipImport": {
+      "type": "boolean",
+      "description": "Do not automatically import the new component into its closest NgModule."
+    },
+    "selector": {
+      "type": "string",
+      "format": "html-selector",
+      "description": "The HTML selector to use for this component. If not provided, a selector will be generated based on the component name (e.g., `app-my-component`)."
+    },
+    "skipSelector": {
+      "type": "boolean",
+      "description": "Skip the generation of an HTML selector for the component."
+    },
+    "module": {
+      "type": "string",
+      "description": "Specify the NgModule where the component should be declared. If not provided, the CLI will attempt to find the closest NgModule in the component's path.",
+      "alias": "m"
+    },
+    "export": {
+      "type": "boolean",
+      "description": "Automatically export the component from the specified NgModule, making it accessible to other modules in the application."
+    },
+    "exportDefault": {
+      "type": "boolean",
+      "description": "Use a default export for the component in its TypeScript file instead of a named export."
+    },
+    "ngHtml": {
+      "type": "boolean",
+      "description": "Generate component template files with an '.ng.html' file extension instead of '.html'."
     }
   },
-  "required": ["name"]
+  "required": ["name", "project"]
 }

package/schematics/eject/index.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const schematics_1 = require("@angular-devkit/schematics");
+const workspace_1 = require("@schematics/angular/utility/workspace");
+const node_fs_1 = require("node:fs");
+const node_module_1 = require("node:module");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+/**
+ * A real dynamic import. The schematics compile to CommonJS, where TypeScript
+ * rewrites `import()` into `require()`, and the native builder is ESM-only
+ * (the same reason Angular CLI keeps its own `loadEsmModule`).
+ */
+const importEsm = new Function('specifier', 'return import(specifier)');
+/**
+ * Loads the native builder that `ng build --platform` uses, so the ejected
+ * project is exactly the one it would have generated. It is a dependency of
+ * @blotch/angular-lynx-build rather than of the app, so it is resolved from
+ * there: pnpm doesn't link it into the app's own node_modules.
+ */
+const loadNative = async (workspaceRoot) => {
+    const fromApp = (0, node_module_1.createRequire)(node_path_1.default.join(workspaceRoot, 'package.json'));
+    let buildersPackageJson;
+    try {
+        buildersPackageJson = (0, node_fs_1.realpathSync)(fromApp.resolve('@blotch/angular-lynx-build/package.json'));
+    }
+    catch {
+        throw new schematics_1.SchematicsException('@blotch/angular-lynx-build is not installed. Install it first: npm install --save-dev @blotch/angular-lynx-build');
+    }
+    const packageJsonPath = (0, node_module_1.createRequire)(buildersPackageJson).resolve('@blotch/angular-lynx-native/package.json');
+    const entry = JSON.parse((0, node_fs_1.readFileSync)(packageJsonPath, 'utf8')).exports['.']
+        .import;
+    return (await importEsm((0, node_url_1.pathToFileURL)(node_path_1.default.join(node_path_1.default.dirname(packageJsonPath), entry)).href));
+};
+/**
+ * `ng generate @blotch/angular-lynx:eject`: writes the native projects that
+ * `ng build --platform` generates into `ios/` and `android/`, for apps that
+ * need native changes the builder options don't cover. The builder then
+ * builds those folders as they are.
+ *
+ * One-way on purpose, like Expo's bare workflow: once a project is ejected,
+ * keeping it in step with Lynx, Xcode and Google Play is the app's job.
+ */
+exports.default = (options) => async (tree, context) => {
+    const workspace = await (0, workspace_1.getWorkspace)(tree);
+    const projectName = options.project ?? [...workspace.projects.keys()][0];
+    const project = projectName
+        ? workspace.projects.get(projectName)
+        : undefined;
+    if (!projectName || !project) {
+        throw new schematics_1.SchematicsException(`Project "${options.project ?? ''}" not found in angular.json.`);
+    }
+    const projectRoot = project.root;
+    const platforms = !options.platform || options.platform === 'all'
+        ? ['ios', 'android']
+        : [options.platform];
+    for (const platform of platforms) {
+        const dir = node_path_1.default.posix.join(projectRoot || '', platform);
+        if (tree.getDir(dir).subfiles.length > 0 ||
+            tree.getDir(dir).subdirs.length > 0) {
+            throw new schematics_1.SchematicsException(`${dir}/ already exists. Delete it first to eject ${platform} again.`);
+        }
+    }
+    // The schematic runs from the workspace root, where Angular CLI resolved
+    // this package too.
+    const workspaceRoot = process.cwd();
+    const native = await loadNative(workspaceRoot);
+    const app = (project.targets.get('build')?.options ?? {});
+    const packageVersion = tree.exists('/package.json')
+        ? JSON.parse(tree.readText('/package.json')).version
+        : undefined;
+    for (const platform of platforms) {
+        const files = native.renderEjectedProject({
+            platform,
+            projectRoot: node_path_1.default.join(workspaceRoot, projectRoot),
+            projectName,
+            packageVersion,
+            app,
+            generatorVersion: native.PACKAGE_VERSION,
+        });
+        for (const [file, content] of files) {
+            tree.create(node_path_1.default.posix.join(projectRoot || '', platform, file), content);
+        }
+        context.logger.info(`Ejected ${platform}/. \`ng build --platform ${platform}\` now builds it as it is: edit it freely, but angular.json app options no longer apply to it, and Lynx, Xcode and Google Play upgrades are yours to make.`);
+    }
+};

package/schematics/eject/schema.js

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

package/schematics/eject/schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "SchematicsAngularLynxEject",
+  "title": "AngularLynx eject schematic",
+  "type": "object",
+  "additionalProperties": false,
+  "description": "Writes the generated iOS and Android projects into ios/ and android/, where you own and edit them. One-way: angular.json app options stop applying to an ejected project.",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The project to eject.",
+      "$default": {
+        "$source": "projectName"
+      }
+    },
+    "platform": {
+      "type": "string",
+      "enum": ["ios", "android", "all"],
+      "default": "all",
+      "description": "Which native project to eject."
+    }
+  },
+  "required": []
+}

package/schematics/files/src/rspeedy-env.d.ts.template

@@ -1 +1 @@
-/// <reference types="@lynx-js/rspeedy/client" />
+/// <reference types="@blotch/angular-lynx-build/client" />

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

@@ -0,0 +1,25 @@
+{
+  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
+  "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"
+    }
+  }
+}