@blotch/angular-lynx 22.2.6 → 22.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blotch/angular-lynx",
-  "version": "22.2.6",
+  "version": "22.2.7",
   "description": "Angular renderer for the Lynx cross-platform native UI framework",
   "homepage": "https://github.com/Blotch-Smart-Frames/AngularLynx#readme",
   "bugs": {

package/schematics/ng-add/index.js

@@ -5,6 +5,7 @@ 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 pnpm_builds_1 = require("../utility/pnpm-builds");
 const tailwind_1 = require("../utility/tailwind");
 const extract_i18n_target_1 = require("../utility/extract-i18n-target");
 const versions_1 = require("./versions");
@@ -14,9 +15,11 @@ const versions_1 = require("./versions");
  * 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
- * CSS (4, or 3 with the Lynx preset). Everything else stays as `ng new` left
- * it: the app needs no build config besides angular.json.
+ * `ng serve` writes `LynxLogger`'s output to, denies the install scripts of
+ * Angular's build tools in a pnpm app (which current pnpm fails installs
+ * over), and optionally sets up Tailwind CSS (4, or 3 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.
@@ -54,6 +57,7 @@ exports.default = (options) => async (tree) => {
         useLynxSchematics(),
         updatePackageScripts(),
         (0, dev_logs_gitignore_1.ignoreDevLogs)(),
+        (0, pnpm_builds_1.denyAngularBuildScripts)(),
         addCoreDependencies(),
     ];
     // `"false"` is how `ng add ... --tailwind=false` arrives (see schema.ts).

package/schematics/utility/pnpm-builds.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.denyAngularBuildScripts = exports.withAngularBuildsDenied = void 0;
+const workspace_1 = require("@schematics/angular/utility/workspace");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * The dependencies of a new Angular app that have install scripts: Angular's
+ * build tools. `esbuild` and `@parcel/watcher` are `@angular/build`'s,
+ * `lmdb` is an optional one of it, and `msgpackr-extract` comes with `lmdb`.
+ *
+ * None of the scripts has anything to do. Each package gets its native binary
+ * from a prebuilt package for the platform, one of its optional dependencies.
+ * esbuild's script only checks that binary; @parcel/watcher's builds one from
+ * source only when asked to, and lmdb's and msgpackr-extract's only when no
+ * prebuilt one fits. Angular's own pnpm workspace denies all four.
+ */
+const ANGULAR_BUILD_SCRIPTS = [
+    '@parcel/watcher',
+    'esbuild',
+    'lmdb',
+    'msgpackr-extract',
+];
+const WORKSPACE_FILE = '/pnpm-workspace.yaml';
+/**
+ * The value pnpm writes for a dependency whose build it's waiting for someone
+ * to allow or deny. It denies the build, but still fails the install.
+ */
+const UNDECIDED = /^(['"]?)set this to true or false\1$/;
+/**
+ * `@parcel/watcher` needs quotes in YAML, since `@` can't start a plain key.
+ */
+const yamlKey = (name) => (name.startsWith('@') ? `'${name}'` : name);
+/**
+ * The `allowBuilds` entries this sets, indented by `indent`.
+ */
+const entries = (names, indent) => names.map((name) => `${indent}${yamlKey(name)}: false`);
+/**
+ * What a pnpm-workspace.yaml without `allowBuilds` gets, with a comment that
+ * says why it's there.
+ */
+const ALLOW_BUILDS_BLOCK = [
+    "# Angular's build tools come with their binaries prebuilt, so their install",
+    '# scripts have nothing to do. pnpm fails installs until each script is',
+    '# allowed (true) or denied (false).',
+    'allowBuilds:',
+    ...entries(ANGULAR_BUILD_SCRIPTS, '  '),
+];
+/** An `allowBuilds` key at the top level, in any style. */
+const ALLOW_BUILDS_KEY = /^allowBuilds[ \t]*:/;
+/** An `allowBuilds` key whose entries follow on their own lines. */
+const ALLOW_BUILDS_BLOCK_KEY = /^allowBuilds[ \t]*:[ \t]*(#.*)?$/;
+/** One entry of a block mapping: its indent, quote, key and value. */
+const ENTRY = /^([ \t]+)(['"]?)([^'"\s#][^'":#]*?)\2[ \t]*:[ \t]*(.*?)[ \t]*$/;
+/**
+ * pnpm-workspace.yaml's text with Angular's build scripts denied in
+ * `allowBuilds`. Entries the app already decided on stay; ones pnpm left
+ * undecided become `false`. Undefined when `allowBuilds` is written in a
+ * style this doesn't edit, such as `allowBuilds: { esbuild: true }`.
+ */
+const withAngularBuildsDenied = (text) => {
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    const lines = text.split(/\r?\n/);
+    const start = lines.findIndex((line) => ALLOW_BUILDS_KEY.test(line));
+    if (start === -1) {
+        // Keep a blank line between the app's settings and the new block.
+        const body = text.trimEnd();
+        return [...(body ? [body, ''] : []), ...ALLOW_BUILDS_BLOCK, ''].join(eol);
+    }
+    if (!ALLOW_BUILDS_BLOCK_KEY.test(lines[start])) {
+        return undefined;
+    }
+    // The block runs over the indented lines after the key; new entries go
+    // after its last one, with its indent.
+    let end = start + 1;
+    let indent = '  ';
+    const decided = new Set();
+    for (let index = start + 1; index < lines.length; index++) {
+        const line = lines[index];
+        if (line.trim() === '' || /^[ \t]+#/.test(line)) {
+            continue;
+        }
+        if (!/^[ \t]/.test(line)) {
+            break;
+        }
+        end = index + 1;
+        const match = ENTRY.exec(line);
+        if (!match) {
+            continue;
+        }
+        const [, entryIndent, quote, name, value] = match;
+        indent = entryIndent;
+        if (UNDECIDED.test(value)) {
+            lines[index] = `${entryIndent}${quote}${name}${quote}: false`;
+        }
+        decided.add(name);
+    }
+    const missing = ANGULAR_BUILD_SCRIPTS.filter((name) => !decided.has(name));
+    lines.splice(end, 0, ...entries(missing, indent));
+    return lines.join(eol);
+};
+exports.withAngularBuildsDenied = withAngularBuildsDenied;
+/**
+ * The pnpm version in package.json's `packageManager` field (`pnpm@12.15.0`,
+ * maybe with a `+sha512...` hash), which `ng new --package-manager pnpm`
+ * writes. Undefined when the app uses pnpm at an unknown version; null when
+ * it uses another package manager.
+ */
+const pnpmVersionOf = async (tree) => {
+    const { packageManager } = tree.exists('/package.json')
+        ? tree.readJson('/package.json')
+        : {};
+    if (typeof packageManager === 'string') {
+        const [name, version] = packageManager.split('@');
+        return name === 'pnpm' ? version : null;
+    }
+    // Without the field, the same signs Angular CLI goes by: angular.json's
+    // `cli.packageManager`, else the lockfile.
+    const workspace = await (0, workspace_1.getWorkspace)(tree);
+    const cli = workspace.extensions['cli'];
+    if (typeof cli?.packageManager === 'string') {
+        return cli.packageManager === 'pnpm' ? undefined : null;
+    }
+    return tree.exists('/pnpm-lock.yaml') || tree.exists(WORKSPACE_FILE)
+        ? undefined
+        : null;
+};
+/**
+ * The version `pnpm --version` prints here, the way Angular's own workspace
+ * schematic reads it for `packageManager`. Undefined when pnpm doesn't run.
+ */
+const installedPnpmVersion = () => {
+    try {
+        return (0, node_child_process_1.execSync)('pnpm --version', {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Whether this pnpm reads `allowBuilds`, which it does from 10.26. Older
+ * pnpm doesn't fail an install over build scripts, and pnpm 9 and early
+ * pnpm 10 fail on a pnpm-workspace.yaml without `packages`, so they're better
+ * left without one.
+ */
+const readsAllowBuilds = (version) => {
+    const [major = 0, minor = 0] = version.split('.').map(Number);
+    return major > 10 || (major === 10 && minor >= 26);
+};
+/**
+ * The pnpm-workspace.yaml of a pnpm workspace above this one, as when the
+ * app was made inside a monorepo. pnpm takes its settings from there, and a
+ * file of the app's own would split the app off into a workspace of its own.
+ */
+const enclosingWorkspaceFile = () => {
+    for (let dir = process.cwd();; dir = (0, node_path_1.dirname)(dir)) {
+        const file = (0, node_path_1.join)(dir, 'pnpm-workspace.yaml');
+        if ((0, node_fs_1.existsSync)(file)) {
+            return file;
+        }
+        if ((0, node_path_1.dirname)(dir) === dir) {
+            return undefined;
+        }
+    }
+};
+/**
+ * Denies the install scripts of Angular's build tools in a pnpm app's
+ * pnpm-workspace.yaml, in `allowBuilds`.
+ *
+ * pnpm 11 and later fail `pnpm install` and `pnpm add` while any
+ * dependency's build script is neither allowed nor denied there
+ * (`strictDepBuilds`). `ng new` and `ng add` install with `--ignore-scripts`,
+ * so they pass, and the app's first `pnpm add` fails. pnpm 11 reads its
+ * settings only from pnpm-workspace.yaml, not package.json.
+ *
+ * Apps on npm, Yarn or bun, and on pnpm older than 10.26, are left alone.
+ */
+const denyAngularBuildScripts = () => async (tree, context) => {
+    const pinned = await pnpmVersionOf(tree);
+    if (pinned === null) {
+        return;
+    }
+    const version = pinned ?? installedPnpmVersion();
+    if (version === undefined || !readsAllowBuilds(version)) {
+        return;
+    }
+    if (!tree.exists(WORKSPACE_FILE)) {
+        const enclosing = enclosingWorkspaceFile();
+        if (enclosing) {
+            context.logger.warn(`This app is in the pnpm workspace of ${enclosing}. Add this to it, or pnpm will fail installs over Angular's build scripts:\n${ALLOW_BUILDS_BLOCK.join('\n')}`);
+            return;
+        }
+    }
+    const text = tree.exists(WORKSPACE_FILE) ? tree.readText(WORKSPACE_FILE) : '';
+    const updated = (0, exports.withAngularBuildsDenied)(text);
+    if (updated === undefined) {
+        context.logger.warn(`pnpm-workspace.yaml's allowBuilds isn't a block mapping, so it was left as it is. Set these in it, or pnpm will fail installs over Angular's build scripts: ${ANGULAR_BUILD_SCRIPTS.map((name) => `${name}: false`).join(', ')}.`);
+    }
+    else if (!tree.exists(WORKSPACE_FILE)) {
+        tree.create(WORKSPACE_FILE, updated);
+    }
+    else if (updated !== text) {
+        tree.overwrite(WORKSPACE_FILE, updated);
+    }
+};
+exports.denyAngularBuildScripts = denyAngularBuildScripts;

package/types/blotch-angular-lynx.d.ts

@@ -4323,6 +4323,100 @@ export declare class LynxSessionStorage {
   static ɵfac: i0.ɵɵFactoryDeclaration<LynxSessionStorage, never>;
   static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
+/**
+ * What {@link LynxLocalStorage} and {@link LynxSecureStorage} share: a
+ * key-value store of JSON values with an async API, kept by a native module
+ * of the apps `ng build --platform` makes, by `localStorage` on the web, and
+ * in memory elsewhere.
+ */
+declare abstract class PersistentStorage {
+  #private;
+  /**
+   * @param module - The native module's name in `NativeModules`.
+   * @param webPrefix - What this store's keys start with in `localStorage`.
+   */
+  constructor(module: string, webPrefix: string);
+  /**
+   * Resolves with the value stored under `key`, or `null` if there's none.
+   */
+  getItem<T = unknown>(key: string): Promise<T | null>;
+  /**
+   * Stores `value` under `key`, as JSON: an object, an array, a string, a
+   * number, a boolean or `null`. Resolves once it's stored.
+   */
+  setItem<T = unknown>(key: string, value: T): Promise<void>;
+  /**
+   * Removes the value stored under `key`, if there is one.
+   */
+  removeItem(key: string): Promise<void>;
+  /**
+   * Removes every value in this store.
+   */
+  clear(): Promise<void>;
+}
+/**
+ * A key-value store that keeps its values after the app closes, like the
+ * browser's `localStorage`. Values are JSON (objects, arrays, strings,
+ * numbers, booleans) and every method returns a promise.
+ *
+ * - **iOS:** `UserDefaults`, in a suite of its own.
+ * - **Android:** `SharedPreferences`, in a file of its own.
+ * - **Web:** the page's `localStorage`, with each key starting with
+ *   `angular-lynx:`.
+ *
+ * For tokens and other secrets, use {@link LynxSecureStorage}.
+ *
+ * Only the apps `ng build --platform` makes have the native module behind
+ * it, `AngularLynxLocalStorage`. Elsewhere, such as in Lynx Explorer and
+ * tests, it keeps values in memory, so they last until the app closes.
+ *
+ * @usageNotes
+ * ```typescript
+ * const storage = inject(LynxLocalStorage);
+ *
+ * await storage.setItem('settings', { units: 'metric' });
+ * const settings = await storage.getItem<Settings>('settings');
+ * await storage.removeItem('settings');
+ * ```
+ */
+export declare class LynxLocalStorage extends PersistentStorage {
+  constructor();
+  static ɵfac: i0.ɵɵFactoryDeclaration<LynxLocalStorage, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/**
+ * A key-value store for secrets such as tokens, which keeps its values after
+ * the app closes, encrypted by the platform. It has the same methods as
+ * {@link LynxLocalStorage}.
+ *
+ * - **iOS:** the Keychain, readable once the phone has been unlocked after it
+ *   starts, and never copied to another device. The Keychain keeps its items
+ *   when the app is deleted, so a reinstalled app finds them again.
+ * - **Android:** `SharedPreferences`, each value encrypted with AES-GCM by a
+ *   key the Android Keystore holds. The file is left out of backups, which
+ *   can't take the key with them.
+ * - **Web:** the page's `localStorage`, with each key starting with
+ *   `angular-lynx-secure:`. Browsers have no store for secrets, and web
+ *   sign-in libraries keep their tokens there too.
+ *
+ * Only the apps `ng build --platform` makes have the native module behind
+ * it, `AngularLynxSecureStorage`. Elsewhere, such as in Lynx Explorer and
+ * tests, it keeps values in memory, so they last until the app closes.
+ *
+ * @usageNotes
+ * ```typescript
+ * const storage = inject(LynxSecureStorage);
+ *
+ * await storage.setItem('session', session);
+ * const session = await storage.getItem<Session>('session');
+ * await storage.removeItem('session');
+ * ```
+ */
+export declare class LynxSecureStorage extends PersistentStorage {
+  constructor();
+  static ɵfac: i0.ɵɵFactoryDeclaration<LynxSecureStorage, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
 /**
  * Wraps the global `SystemInfo` object as an Angular injectable,
  * providing device and platform information from the Lynx runtime.
@@ -4710,6 +4804,44 @@ export declare class LynxWebAuthSession {
  * 5. Error handler (routes to _ReportError + __lynxLastError)
  */
 export declare const provideRenderer: () => EnvironmentProviders;
+/**
+ * The Lynx elements a component's host can be, besides the `<view>` every
+ * host is by default.
+ */
+type HostElementTag = 'view' | 'text' | 'image' | 'scroll-view' | 'svg' | 'blur-view';
+/**
+ * Makes a component's host element a Lynx element other than `<view>`, such
+ * as a `<text>`. Call it once, next to the component:
+ *
+ * ```ts
+ * @Component({
+ *   selector: 'app-title',
+ *   host: { class: 'text-2xl font-semibold' },
+ *   template: '<ng-content />',
+ * })
+ * export class AppTitle {}
+ *
+ * registerHostElement(AppTitle, 'text');
+ * ```
+ *
+ * Every host is a `<view>` otherwise, a real element between the parent and
+ * the component's template. A component that shows text then needs a
+ * `<text>` inside its host, and a class the app writes on the component
+ * (`<app-title class="mb-2">`) lands on the host, which Angular gives every
+ * static attribute, as well as on whatever element the component passes it
+ * to: a margin there applies twice. With a `<text>` host, the component is
+ * one element, the way a component's `<span>` or `<p>` would be on the web.
+ *
+ * The registration covers each element name in the selector, wherever a
+ * template uses the component. Content projected into a `<text>` host follows
+ * `<text>`'s rules: raw text, and nested `<text>` that runs inline.
+ */
+export declare const registerHostElement: (component: Type<unknown>, element: HostElementTag) => void;
+/**
+ * The Lynx element to create for a tag: the registered host element for a
+ * component's tag, or the tag itself.
+ */
+declare const hostElementOf: (tag: string) => string;
 /**
  * Keeps the app on the screen it was showing when a hot update re-bootstraps
  * it. Called with the old app's injector before it's destroyed, it saves the
@@ -4988,6 +5120,14 @@ declare const handlers: {
    * module proxies (relayedModule() below) send their calls here.
    */
   callModule: (kind: ModuleKind, name: string, method: string, args: unknown[]) => unknown;
+  /**
+   * Calls a native module method that answers through a callback, passed
+   * after `args`, and resolves with the first value it passes back. Unlike a
+   * function sent through callModule, the callback stays on this thread, so
+   * the call leaves nothing registered on either thread: the storage
+   * services make one of these per read and write.
+   */
+  callNativeModuleAsync: (name: string, method: string, args: unknown[]) => Promise<unknown>;
   registerJSModule: (name: string, module: unknown) => void;
   /**
    * The OS version, for LynxSystemInfo on the main thread: native Lynx builds
@@ -5139,4 +5279,4 @@ declare global {
     catchmouseleave: MouseEvent;
   }
 }
-export type { AccessibilityTrait, AccessibilityTraitStates, BackgroundFnHandle, BaseLynxAnimation, BaseLynxElement, DataProcessorDefinition, DevToolsStats, DynamicColorRole, DynamicColorScheme, DynamicColors, ExposureEventDetail, FlingGestureEvent, GestureCallback, GestureCallbackWithState, GestureEvent, GlobalData, GlobalExposureEvent, InitData, InitDataRaw, LongPressGestureEvent, LynxAnimationOptions, LynxFontEntry, LynxFontFaceConfig, LynxFontStatus, LynxTraceOptions, MainThread, MainThreadFnHandle, NativeModuleMap, NativeModuleProxy, ObserverFrameRateOptions, PanGestureEvent, PinchGestureEvent, PortalConfig, PrefetchCacheTarget, PrefetchPriority, PrefetchRequest, PrefetchResultDetail, ResourcePrefetchData, ResourcePrefetchResult, RotationGestureEvent, SessionStorageSubscription, TapGestureEvent, WebAuthSessionErrorCode, WebAuthSessionOptions };
+export type { AccessibilityTrait, AccessibilityTraitStates, BackgroundFnHandle, BaseLynxAnimation, BaseLynxElement, DataProcessorDefinition, DevToolsStats, DynamicColorRole, DynamicColorScheme, DynamicColors, ExposureEventDetail, FlingGestureEvent, GestureCallback, GestureCallbackWithState, GestureEvent, GlobalData, GlobalExposureEvent, HostElementTag, InitData, InitDataRaw, LongPressGestureEvent, LynxAnimationOptions, LynxFontEntry, LynxFontFaceConfig, LynxFontStatus, LynxTraceOptions, MainThread, MainThreadFnHandle, NativeModuleMap, NativeModuleProxy, ObserverFrameRateOptions, PanGestureEvent, PinchGestureEvent, PortalConfig, PrefetchCacheTarget, PrefetchPriority, PrefetchRequest, PrefetchResultDetail, ResourcePrefetchData, ResourcePrefetchResult, RotationGestureEvent, SessionStorageSubscription, TapGestureEvent, WebAuthSessionErrorCode, WebAuthSessionOptions };