@ssgoi/angular 7.1.2 → 7.1.3-beta.0

package/README.md

@@ -12,6 +12,17 @@ npm install @ssgoi/angular
 
 Agent setup guide: https://ssgoi.dev/llms.txt
 
+## Router helpers
+
+Install this framework package once; router helpers are optional subpaths.
+These router helpers are experimental APIs and may change.
+
+| Router         | Import                  | API                  |
+| -------------- | ----------------------- | -------------------- |
+| Angular Router | `@ssgoi/angular/router` | `SsgoiRouteBoundary` |
+
+See the [framework guide](https://ssgoi.dev/docs/frameworks/angular) for wiring and limits.
+
 ## Setup
 
 Create one SSGOI root above the router outlet.
@@ -45,22 +56,24 @@ export class AppComponent {
 
 ## Route boundary
 
-Mark the root element of each routed component.
+Use the experimental standalone directive on the routed page's single DOM root:
 
 ```ts
+import { Component } from "@angular/core";
+import { SsgoiRouteBoundary } from "@ssgoi/angular/router";
+
 @Component({
-  selector: "app-post",
   standalone: true,
-  template: `
-    <article data-ssgoi-transition="/posts/42">
-      <!-- page -->
-    </article>
-  `,
+  imports: [SsgoiRouteBoundary],
+  template: `<article *ssgoiRouteBoundary="let route">{{ route.id }}</article>`,
 })
 export class PostComponent {}
 ```
 
-The id must match the config route patterns.
+It recreates the embedded view on pathname changes, including parameterized
+routes that reuse the same component. Query-only navigation preserves it. Use
+`key: 'shell'` for a persistent region. Keep RouterOutlet in the application;
+custom reuse caches and auxiliary outlet coordination are not handled.
 
 ## Config
 

package/dist/README.md

@@ -12,6 +12,17 @@ npm install @ssgoi/angular
 
 Agent setup guide: https://ssgoi.dev/llms.txt
 
+## Router helpers
+
+Install this framework package once; router helpers are optional subpaths.
+These router helpers are experimental APIs and may change.
+
+| Router         | Import                  | API                  |
+| -------------- | ----------------------- | -------------------- |
+| Angular Router | `@ssgoi/angular/router` | `SsgoiRouteBoundary` |
+
+See the [framework guide](https://ssgoi.dev/docs/frameworks/angular) for wiring and limits.
+
 ## Setup
 
 Create one SSGOI root above the router outlet.
@@ -45,22 +56,24 @@ export class AppComponent {
 
 ## Route boundary
 
-Mark the root element of each routed component.
+Use the experimental standalone directive on the routed page's single DOM root:
 
 ```ts
+import { Component } from "@angular/core";
+import { SsgoiRouteBoundary } from "@ssgoi/angular/router";
+
 @Component({
-  selector: "app-post",
   standalone: true,
-  template: `
-    <article data-ssgoi-transition="/posts/42">
-      <!-- page -->
-    </article>
-  `,
+  imports: [SsgoiRouteBoundary],
+  template: `<article *ssgoiRouteBoundary="let route">{{ route.id }}</article>`,
 })
 export class PostComponent {}
 ```
 
-The id must match the config route patterns.
+It recreates the embedded view on pathname changes, including parameterized
+routes that reuse the same component. Query-only navigation preserves it. Use
+`key: 'shell'` for a persistent region. Keep RouterOutlet in the application;
+custom reuse caches and auxiliary outlet coordination are not handled.
 
 ## Config
 

package/dist/fesm2022/ssgoi-angular-router.mjs

@@ -0,0 +1,90 @@
+import * as i0 from '@angular/core';
+import { inject, TemplateRef, ViewContainerRef, Renderer2, Input, Directive } from '@angular/core';
+import { ActivatedRoute, Router, NavigationEnd, createUrlTreeFromSnapshot } from '@angular/router';
+
+/**
+ * @experimental Angular Router integration. The API may change.
+ * Use on a routed page's single DOM root, e.g. <article *ssgoiRouteBoundary>.
+ * Recreates the embedded view when its route key changes, including reused
+ * parameterized routes. It does not replace RouterOutlet or a RouteReuseStrategy.
+ */
+class SsgoiRouteBoundary {
+    ssgoiRouteBoundary;
+    ssgoiRouteBoundaryKey;
+    route = inject(ActivatedRoute);
+    router = inject(Router);
+    template = inject(TemplateRef);
+    container = inject(ViewContainerRef);
+    renderer = inject(Renderer2);
+    view;
+    element;
+    key;
+    subscription;
+    initialized = false;
+    ngOnInit() {
+        this.initialized = true;
+        this.renderBoundary();
+        // Read committed snapshots once per successful navigation. Ancestor URL
+        // streams may emit separately while the router advances its route tree.
+        this.subscription = this.router.events.subscribe((event) => {
+            if (event instanceof NavigationEnd)
+                this.renderBoundary();
+        });
+    }
+    ngOnChanges() {
+        if (this.initialized)
+            this.renderBoundary();
+    }
+    ngOnDestroy() {
+        this.subscription?.unsubscribe();
+    }
+    renderBoundary() {
+        const route = this.route.snapshot;
+        const pathname = this.router.serializeUrl(createUrlTreeFromSnapshot(route, [], null, null));
+        const boundary = typeof this.ssgoiRouteBoundary === "function"
+            ? this.ssgoiRouteBoundary({ pathname, route })
+            : { id: pathname };
+        const key = this.ssgoiRouteBoundaryKey ?? boundary.key ?? boundary.id;
+        if (!this.view || key !== this.key) {
+            this.container.clear();
+            this.view = this.container.createEmbeddedView(this.template, {
+                $implicit: boundary,
+            });
+            const roots = this.view.rootNodes.filter((node) => node.nodeType === 1);
+            if (roots.length !== 1) {
+                this.container.clear();
+                this.view = undefined;
+                throw new Error("SSGOI: *ssgoiRouteBoundary requires exactly one DOM root.");
+            }
+            this.element = roots[0];
+            this.key = key;
+        }
+        else {
+            this.view.context.$implicit = boundary;
+        }
+        this.renderer.setAttribute(this.element, "data-ssgoi-transition", boundary.id);
+        this.view.markForCheck();
+    }
+    static ngTemplateContextGuard(_directive, context) {
+        return true;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.9", ngImport: i0, type: SsgoiRouteBoundary, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "20.3.9", type: SsgoiRouteBoundary, isStandalone: true, selector: "[ssgoiRouteBoundary]", inputs: { ssgoiRouteBoundary: "ssgoiRouteBoundary", ssgoiRouteBoundaryKey: "ssgoiRouteBoundaryKey" }, usesOnChanges: true, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.9", ngImport: i0, type: SsgoiRouteBoundary, decorators: [{
+            type: Directive,
+            args: [{ selector: "[ssgoiRouteBoundary]", standalone: true }]
+        }], propDecorators: { ssgoiRouteBoundary: [{
+                type: Input
+            }], ssgoiRouteBoundaryKey: [{
+                type: Input
+            }] } });
+
+/** @experimental Angular Router integration. The API may change. */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { SsgoiRouteBoundary };
+//# sourceMappingURL=ssgoi-angular-router.mjs.map

package/dist/fesm2022/ssgoi-angular-router.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssgoi-angular-router.mjs","sources":["../../router/src/ssgoi-route-boundary.ts","../../router/public-api.ts","../../router/ssgoi-angular-router.ts"],"sourcesContent":["import {\n  Directive,\n  Input,\n  Renderer2,\n  TemplateRef,\n  ViewContainerRef,\n  inject,\n  type EmbeddedViewRef,\n  type OnChanges,\n  type OnDestroy,\n  type OnInit,\n} from \"@angular/core\";\nimport {\n  ActivatedRoute,\n  NavigationEnd,\n  Router,\n  createUrlTreeFromSnapshot,\n  type ActivatedRouteSnapshot,\n} from \"@angular/router\";\n\nexport interface RouteBoundaryState {\n  id: string;\n  key?: string | number;\n}\n\nexport interface AngularRouteLocation {\n  pathname: string;\n  route: ActivatedRouteSnapshot;\n}\n\ntype BoundaryContext = { $implicit: RouteBoundaryState };\ntype ResolveBoundary = (location: AngularRouteLocation) => RouteBoundaryState;\n\n/**\n * @experimental Angular Router integration. The API may change.\n * Use on a routed page's single DOM root, e.g. <article *ssgoiRouteBoundary>.\n * Recreates the embedded view when its route key changes, including reused\n * parameterized routes. It does not replace RouterOutlet or a RouteReuseStrategy.\n */\n@Directive({ selector: \"[ssgoiRouteBoundary]\", standalone: true })\nexport class SsgoiRouteBoundary implements OnInit, OnChanges, OnDestroy {\n  @Input() ssgoiRouteBoundary?: ResolveBoundary | \"\";\n  @Input() ssgoiRouteBoundaryKey?: string | number;\n\n  private readonly route = inject(ActivatedRoute);\n  private readonly router = inject(Router);\n  private readonly template = inject<TemplateRef<BoundaryContext>>(TemplateRef);\n  private readonly container = inject(ViewContainerRef);\n  private readonly renderer = inject(Renderer2);\n  private view?: EmbeddedViewRef<BoundaryContext>;\n  private element?: HTMLElement;\n  private key?: string | number;\n  private subscription?: { unsubscribe(): void };\n  private initialized = false;\n\n  ngOnInit(): void {\n    this.initialized = true;\n    this.renderBoundary();\n    // Read committed snapshots once per successful navigation. Ancestor URL\n    // streams may emit separately while the router advances its route tree.\n    this.subscription = this.router.events.subscribe((event) => {\n      if (event instanceof NavigationEnd) this.renderBoundary();\n    });\n  }\n\n  ngOnChanges(): void {\n    if (this.initialized) this.renderBoundary();\n  }\n\n  ngOnDestroy(): void {\n    this.subscription?.unsubscribe();\n  }\n\n  private renderBoundary(): void {\n    const route = this.route.snapshot;\n    const pathname = this.router.serializeUrl(\n      createUrlTreeFromSnapshot(route, [], null, null),\n    );\n    const boundary =\n      typeof this.ssgoiRouteBoundary === \"function\"\n        ? this.ssgoiRouteBoundary({ pathname, route })\n        : { id: pathname };\n    const key = this.ssgoiRouteBoundaryKey ?? boundary.key ?? boundary.id;\n\n    if (!this.view || key !== this.key) {\n      this.container.clear();\n      this.view = this.container.createEmbeddedView(this.template, {\n        $implicit: boundary,\n      });\n      const roots = this.view.rootNodes.filter((node) => node.nodeType === 1);\n      if (roots.length !== 1) {\n        this.container.clear();\n        this.view = undefined;\n        throw new Error(\n          \"SSGOI: *ssgoiRouteBoundary requires exactly one DOM root.\",\n        );\n      }\n      this.element = roots[0];\n      this.key = key;\n    } else {\n      this.view.context.$implicit = boundary;\n    }\n    this.renderer.setAttribute(\n      this.element,\n      \"data-ssgoi-transition\",\n      boundary.id,\n    );\n    this.view.markForCheck();\n  }\n\n  static ngTemplateContextGuard(\n    _directive: SsgoiRouteBoundary,\n    context: unknown,\n  ): context is BoundaryContext {\n    return true;\n  }\n}\n","/** @experimental Angular Router integration. The API may change. */\nexport { SsgoiRouteBoundary } from \"./src/ssgoi-route-boundary\";\nexport type {\n  AngularRouteLocation,\n  RouteBoundaryState,\n} from \"./src/ssgoi-route-boundary\";\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":"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"}

package/dist/router/index.d.ts

@@ -0,0 +1,46 @@
+import * as i0 from '@angular/core';
+import { OnInit, OnChanges, OnDestroy } from '@angular/core';
+import { ActivatedRouteSnapshot } from '@angular/router';
+
+interface RouteBoundaryState {
+    id: string;
+    key?: string | number;
+}
+interface AngularRouteLocation {
+    pathname: string;
+    route: ActivatedRouteSnapshot;
+}
+type BoundaryContext = {
+    $implicit: RouteBoundaryState;
+};
+type ResolveBoundary = (location: AngularRouteLocation) => RouteBoundaryState;
+/**
+ * @experimental Angular Router integration. The API may change.
+ * Use on a routed page's single DOM root, e.g. <article *ssgoiRouteBoundary>.
+ * Recreates the embedded view when its route key changes, including reused
+ * parameterized routes. It does not replace RouterOutlet or a RouteReuseStrategy.
+ */
+declare class SsgoiRouteBoundary implements OnInit, OnChanges, OnDestroy {
+    ssgoiRouteBoundary?: ResolveBoundary | "";
+    ssgoiRouteBoundaryKey?: string | number;
+    private readonly route;
+    private readonly router;
+    private readonly template;
+    private readonly container;
+    private readonly renderer;
+    private view?;
+    private element?;
+    private key?;
+    private subscription?;
+    private initialized;
+    ngOnInit(): void;
+    ngOnChanges(): void;
+    ngOnDestroy(): void;
+    private renderBoundary;
+    static ngTemplateContextGuard(_directive: SsgoiRouteBoundary, context: unknown): context is BoundaryContext;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SsgoiRouteBoundary, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SsgoiRouteBoundary, "[ssgoiRouteBoundary]", never, { "ssgoiRouteBoundary": { "alias": "ssgoiRouteBoundary"; "required": false; }; "ssgoiRouteBoundaryKey": { "alias": "ssgoiRouteBoundaryKey"; "required": false; }; }, {}, never, never, true, never>;
+}
+
+export { SsgoiRouteBoundary };
+export type { AngularRouteLocation, RouteBoundaryState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssgoi/angular",
-  "version": "7.1.2",
+  "version": "7.1.3-beta.0",
   "description": "Angular bindings for SSGOI - Native app-like page transitions for Angular applications",
   "private": false,
   "type": "module",
@@ -20,14 +20,19 @@
     },
     "./package.json": {
       "default": "./package.json"
+    },
+    "./router": {
+      "types": "./dist/router/index.d.ts",
+      "default": "./dist/fesm2022/ssgoi-angular-router.mjs"
     }
   },
   "dependencies": {
-    "@ssgoi/core": "^7.1.2"
+    "@ssgoi/core": "^7.1.3-beta.0"
   },
   "peerDependencies": {
     "@angular/common": "^20.0.0",
-    "@angular/core": "^20.0.0"
+    "@angular/core": "^20.0.0",
+    "@angular/router": "*"
   },
   "devDependencies": {
     "@angular-eslint/builder": "^20.3.0",
@@ -35,15 +40,20 @@
     "@angular-eslint/eslint-plugin-template": "^20.3.0",
     "@angular-eslint/schematics": "^20.3.0",
     "@angular-eslint/template-parser": "^20.3.0",
-    "@angular/common": "^20.3.4",
-    "@angular/compiler": "^20.3.4",
-    "@angular/compiler-cli": "^20.3.4",
-    "@angular/core": "^20.3.4",
+    "@angular/common": "20.3.9",
+    "@angular/compiler": "20.3.9",
+    "@angular/compiler-cli": "20.3.9",
+    "@angular/core": "20.3.9",
     "@typescript-eslint/eslint-plugin": "^8.46.0",
     "@typescript-eslint/parser": "^8.46.0",
     "eslint": "^9.37.0",
     "ng-packagr": "^20.3.0",
-    "typescript": "~5.8.3"
+    "typescript": "~5.8.3",
+    "@angular/router": "20.3.9",
+    "@angular/platform-browser": "20.3.9",
+    "@angular/platform-browser-dynamic": "20.3.9",
+    "vitest": "^3.2.4",
+    "jsdom": "^26.1.0"
   },
   "keywords": [
     "angular",
@@ -71,10 +81,16 @@
     "node": ">=18.0.0"
   },
   "sideEffects": false,
+  "peerDependenciesMeta": {
+    "@angular/router": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "ng-packagr -p ng-package.json",
     "watch": "ng-packagr -p ng-package.json --watch",
     "lint": "eslint .",
-    "lint:fix": "eslint . --fix"
+    "lint:fix": "eslint . --fix",
+    "test:run": "vitest run"
   }
 }