Harvmaster/Native-Router-Vue
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add prettier. Format.

Browse Source
This commit is contained in:
Harvmaster
2026-07-22 02:12:05 +00:00
parent d28b09dc21
commit 18baa96848
45 changed files with 4520 additions and 2613 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/architecture.md
View File

@@ -26,14 +26,15 @@ Component gesture owners stop propagation before a containing navigator can clai
```ts
interface NativeRouteOptions {
navigator?: string
presentation?: 'push' | 'reveal' | 'slide' | 'fade' | 'modal' | 'sheet' | string
parent?: RouteLocationRaw | ((route) => RouteLocationRaw)
siblingGroup?: string
siblingOrder?: number
siblingHistory?: 'push' | 'replace'
cache?: boolean | 'pin'
gesture?: boolean | 'edge' | 'full'
navigator?: string;
presentation?:
"push" | "reveal" | "slide" | "fade" | "modal" | "sheet" | string;
parent?: RouteLocationRaw | ((route) => RouteLocationRaw);
siblingGroup?: string;
siblingOrder?: number;
siblingHistory?: "push" | "replace";
cache?: boolean | "pin";
gesture?: boolean | "edge" | "full";
}
```
@@ -42,15 +43,17 @@ interface NativeRouteOptions {
## Custom presentations
```ts
nativeRouter.registerPresentation(definePresentation({
name: 'scale-fade',
axis: 'x',
layerStyle({ role, progress }) {
return role === 'to'
? { opacity: progress, transform: `scale(${0.92 + progress * 0.08})` }
: { opacity: 1 - progress * 0.4 }
},
}))
nativeRouter.registerPresentation(
definePresentation({
name: "scale-fade",
axis: "x",
layerStyle({ role, progress }) {
return role === "to"
? { opacity: progress, transform: `scale(${0.92 + progress * 0.08})` }
: { opacity: 1 - progress * 0.4 };
},
}),
);
```
Applications can call `beginInteractive()`, `updateInteractive()`, and `finishInteractive()` to drive the same transaction engine from a bespoke recognizer.
@@ -72,16 +75,16 @@ import {
onNativeViewEvict,
useNativeViewActiveEffect,
useNativeViewLifecycle,
} from '@native-vue-router/core'
} from "@native-vue-router/core";
const view = useNativeViewLifecycle()
const view = useNativeViewLifecycle();
useNativeViewActiveEffect(() => {
const timer = startPolling()
return () => stopPolling(timer)
})
const timer = startPolling();
return () => stopPolling(timer);
});
onNativeViewEvict((reason) => saveDraft(view.route.value, reason))
onNativeViewEvict((reason) => saveDraft(view.route.value, reason));
```
`isActive` means the route is authoritative. `isVisible` also includes either side of an in-progress transition. Use `useNativeViewActiveEffect` for polling and other work that should pause in a cached tab, or `useNativeViewVisibleEffect` for work needed during the animation. Application data that must survive eviction belongs in an application store.

18
docs/challenges-and-tradeoffs.md
View File

@@ -193,12 +193,12 @@ Deployment infrastructure must still avoid long-lived caching for `sw.js` and th
## Summary of deliberate trade-offs
| Decision | Benefit | Cost |
| --- | --- | --- |
| Keep Vue Router authoritative | Guards, URLs, redirects, and ecosystem compatibility | Reconciliation complexity |
| Render a preview before commit | Truly interactive and cancellable navigation | Two live component trees and preview side effects |
| Maintain separate history and view ledgers | Correct back semantics plus tab caching | More state and invariants |
| Interrupt springs but finish semantic commits | No animation cooldown without corrupting history | Guard/history latency can remain |
| Require explicit route topology | Deterministic parent and sibling behavior | More route metadata |
| Bound mounted views | Predictable DOM and memory use | Component-local state can be evicted |
| Use progressive platform adapters | One core across PWA, Electron, and Capacitor | Browser/PWA guarantees remain weaker than native hosts |
| Decision | Benefit | Cost |
| --------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------ |
| Keep Vue Router authoritative | Guards, URLs, redirects, and ecosystem compatibility | Reconciliation complexity |
| Render a preview before commit | Truly interactive and cancellable navigation | Two live component trees and preview side effects |
| Maintain separate history and view ledgers | Correct back semantics plus tab caching | More state and invariants |
| Interrupt springs but finish semantic commits | No animation cooldown without corrupting history | Guard/history latency can remain |
| Require explicit route topology | Deterministic parent and sibling behavior | More route metadata |
| Bound mounted views | Predictable DOM and memory use | Component-local state can be evicted |
| Use progressive platform adapters | One core across PWA, Electron, and Capacitor | Browser/PWA guarantees remain weaker than native hosts |

6
docs/how-it-works.md
View File

@@ -19,9 +19,9 @@ Vue Router remains the authority for semantic navigation: route matching, URLs,
That separation produces two ledgers:
| Ledger | Owns | Source of truth for |
| --- | --- | --- |
| Vue Router | Current committed route and browser history | What URL the application is actually on |
| Ledger | Owns | Source of truth for |
| ------------------- | --------------------------------------------------- | ------------------------------------------------- |
| Vue Router | Current committed route and browser history | What URL the application is actually on |
| Native view runtime | Active, inactive, preview, and evicted view entries | What route surfaces can be rendered during motion |
The ledgers agree at rest. During a gesture they intentionally diverge: Vue Router still reports the committed `from` route while the native runtime also renders an uncommitted `to` route.

34
docs/principles-and-scalability.md
View File

@@ -54,13 +54,13 @@ Only the active route, previously visited inactive routes, and a transaction pre
During an interaction, animation work concerns two surfaces regardless of total route count:
| Resource | Growth behavior |
| --- | --- |
| Animated surfaces | Constant: `from` and `to` |
| Mounted inactive component trees | Bounded by `maxInactive` |
| Route descriptors/history keys | Grows with navigation history |
| Per-frame transaction state | Constant |
| Lazy route code | Loaded on first preview or navigation |
| Resource | Growth behavior |
| -------------------------------- | ------------------------------------- |
| Animated surfaces | Constant: `from` and `to` |
| Mounted inactive component trees | Bounded by `maxInactive` |
| Route descriptors/history keys | Grows with navigation history |
| Per-frame transaction state | Constant |
| Lazy route code | Loaded on first preview or navigation |
The current implementation uses linear searches through view entries for some reconciliation operations. This is appropriate for ordinary application histories and a small mounted cache. If the runtime is used for sessions with thousands of unique committed entries, a key/path index and descriptor compaction would be a sensible evolution without changing the public transaction model.
@@ -122,15 +122,17 @@ Ordered peers are passed to `NativeNavigator`. Their routes use `siblingOrder` t
Presentation definitions receive only the data needed to derive layer styles:
```ts
nativeRouter.registerPresentation(definePresentation({
name: 'scale-fade',
axis: 'x',
layerStyle({ role, progress }) {
return role === 'to'
? { opacity: progress, transform: `scale(${0.94 + progress * 0.06})` }
: { opacity: 1 - progress * 0.25 }
},
}))
nativeRouter.registerPresentation(
definePresentation({
name: "scale-fade",
axis: "x",
layerStyle({ role, progress }) {
return role === "to"
? { opacity: progress, transform: `scale(${0.94 + progress * 0.06})` }
: { opacity: 1 - progress * 0.25 };
},
}),
);
```
A presentation does not decide history or commit. Keeping motion separate from navigation semantics makes new visual styles safer to add.