@ssgoi/qwik 7.1.2 → 7.1.3-beta.0

package/README.md

@@ -12,6 +12,17 @@ npm install @ssgoi/qwik
 
 Agent setup guide: https://ssgoi.dev/llms/qwik.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                     |
+| --------- | ----------------------- | ----------------------- |
+| Qwik City | `@ssgoi/qwik/qwik-city` | `useSsgoiRouteBoundary` |
+
+See the [framework guide](https://ssgoi.dev/docs/frameworks/qwik) for wiring and limits.
+
 ## Root
 
 Qwik configs contain functions, so pass a QRL factory.
@@ -39,20 +50,25 @@ export default component$(() => {
 
 ## Route boundary
 
-Mark route component roots:
+Use the experimental Qwik City helper on the page's own root:
 
 ```tsx
-export default component$(() => (
-  <section data-ssgoi-transition="/posts">Posts</section>
-));
-```
-
-Dynamic route:
+import { component$ } from "@builder.io/qwik";
+import { useSsgoiRouteBoundary } from "@ssgoi/qwik/qwik-city";
 
-```tsx
-<section data-ssgoi-transition={`/posts/${postId}`}>...</section>
+export default component$(() => {
+  const boundary = useSsgoiRouteBoundary();
+  return (
+    <section key={boundary.value.key} data-ssgoi-transition={boundary.value.id}>
+      Page
+    </section>
+  );
+});
 ```
 
+The key replaces the root when City reuses a parameterized page. A stable key
+can be passed for a persistent shell. Keep Slot ownership in the route/layout.
+
 ## Persistent layouts
 
 Put an outer marker in the persistent route layout and markers on child route

package/lib/qwik-city.qwik.cjs

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const qwik = require("@builder.io/qwik");
+const qwikCity = require("@builder.io/qwik-city");
+function useSsgoiRouteBoundary(routeKey) {
+  const location = qwikCity.useLocation();
+  return qwik.useComputed$(() => ({
+    id: location.url.pathname,
+    key: routeKey ?? location.url.pathname
+  }));
+}
+exports.useSsgoiRouteBoundary = useSsgoiRouteBoundary;

package/lib/qwik-city.qwik.mjs

@@ -0,0 +1,12 @@
+import { useComputed$ } from "@builder.io/qwik";
+import { useLocation } from "@builder.io/qwik-city";
+function useSsgoiRouteBoundary(routeKey) {
+  const location = useLocation();
+  return useComputed$(() => ({
+    id: location.url.pathname,
+    key: routeKey ?? location.url.pathname
+  }));
+}
+export {
+  useSsgoiRouteBoundary
+};

package/lib-types/routers/qwik-city.d.ts

@@ -0,0 +1,11 @@
+import { type Signal } from "@builder.io/qwik";
+export interface RouteBoundaryState {
+    id: string;
+    key: string | number;
+}
+/**
+ * @experimental Qwik City route boundary helper. The API may change.
+ * Apply id and key to the page's own DOM root. Keeping Slot ownership in the
+ * route avoids moving projected content between outgoing and incoming pages.
+ */
+export declare function useSsgoiRouteBoundary(routeKey?: string | number): Signal<RouteBoundaryState>;

package/lib-types/ssgoi-transition.d.ts

@@ -1,6 +1,6 @@
 export interface SsgoiTransitionProps {
-  id: string;
-  class?: string;
+    id: string;
+    class?: string;
 }
 /**
  * Marks a subtree as a Ssgoi page boundary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssgoi/qwik",
-  "version": "7.1.2",
+  "version": "7.1.3-beta.0",
   "description": "Qwik bindings for SSGOI - Native app-like page transitions for Qwik and Qwik City applications",
   "private": false,
   "sideEffects": false,
@@ -23,6 +23,11 @@
       "types": "./lib-types/view-transitions.d.ts",
       "import": "./lib/view-transitions.qwik.mjs",
       "require": "./lib/view-transitions.qwik.cjs"
+    },
+    "./qwik-city": {
+      "types": "./lib-types/routers/qwik-city.d.ts",
+      "import": "./lib/qwik-city.qwik.mjs",
+      "require": "./lib/qwik-city.qwik.cjs"
     }
   },
   "files": [
@@ -30,10 +35,11 @@
     "lib-types"
   ],
   "dependencies": {
-    "@ssgoi/core": "^7.1.2"
+    "@ssgoi/core": "^7.1.3-beta.0"
   },
   "peerDependencies": {
-    "@builder.io/qwik": "^1.20.0"
+    "@builder.io/qwik": "^1.20.0",
+    "@builder.io/qwik-city": "*"
   },
   "devDependencies": {
     "@builder.io/qwik": "^1.20.0",
@@ -45,7 +51,8 @@
     "typescript": "~5.8.3",
     "typescript-eslint": "^8.35.1",
     "vite": "^7.0.4",
-    "vite-tsconfig-paths": "^5.1.4"
+    "vite-tsconfig-paths": "^5.1.4",
+    "@builder.io/qwik-city": "^1.20.0"
   },
   "keywords": [
     "qwik",
@@ -79,6 +86,11 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "peerDependenciesMeta": {
+    "@builder.io/qwik-city": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "pnpm run build.lib && pnpm run build.types",
     "build.lib": "vite build --mode lib",