@capgo/capacitor-native-navigation 8.0.18 → 8.0.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +57 -36
  2. package/package.json +8 -3
package/README.md CHANGED
@@ -1,12 +1,24 @@
1
1
  # @capgo/capacitor-native-navigation
2
- <a href="https://capgo.app/"><img src="https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-native-navigation" alt="Capgo - Instant updates for Capacitor" /></a>
2
+
3
+ <a href="https://capgo.app/">
4
+ <img
5
+ src="https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-native-navigation"
6
+ alt="Capgo - Instant updates for Capacitor"
7
+ />
8
+ </a>
3
9
 
4
10
  <div align="center">
5
- <h2><a href="https://capgo.app/?ref=plugin_native_navigation">Get instant updates for your app with Capgo</a></h2>
6
- <h2><a href="https://capgo.app/consulting/?ref=plugin_native_navigation">Missing a feature? We can build the plugin for you</a></h2>
11
+ <h2>
12
+ <a href="https://capgo.app/?ref=plugin_native_navigation">Get instant updates for your app with Capgo</a>
13
+ </h2>
14
+ <h2>
15
+ <a href="https://capgo.app/consulting/?ref=plugin_native_navigation">
16
+ Missing a feature? We can build the plugin for you
17
+ </a>
18
+ </h2>
7
19
  </div>
8
20
 
9
- Native navigation chrome for Capacitor apps. Render a native navbar, native tabbar, and native transition shell over a single full-screen WebView while your framework keeps owning routes and content.
21
+ Native navbar, tabbar, safe-area handling, and WebView snapshot transitions for Capacitor apps. Your web framework keeps routing and page rendering while this plugin owns the platform surfaces users expect to feel native.
10
22
 
11
23
  ## Demo
12
24
 
@@ -14,44 +26,53 @@ Native navigation chrome for Capacitor apps. Render a native navbar, native tabb
14
26
 
15
27
  ### Native navigation tap flow
16
28
 
17
- <img src="./docs/demo-navigation.webp" alt="Animated native navigation tap flow showing tab selection, push transition, and native back" width="320" />
29
+ <img
30
+ src="./docs/demo-navigation.webp"
31
+ alt="Animated native navigation tap flow showing tab selection, push transition, and native back"
32
+ width="320"
33
+ />
18
34
 
19
35
  ### SVG icon descriptors
20
36
 
21
- <img src="./docs/demo-svg-icons.webp" alt="Animated native SVG icon demo showing inline SVG icons, native tint, labels, and tab selection" width="320" />
37
+ <img
38
+ src="./docs/demo-svg-icons.webp"
39
+ alt="Animated native SVG icon demo showing inline SVG icons, native tint, labels, and tab selection"
40
+ width="320"
41
+ />
22
42
 
23
43
  ### Native styling and zoom options
24
44
 
25
- <img src="./docs/demo-options.webp" alt="Animated native navigation options demo showing dynamic colors, selected labels, custom indicators, badges, system Liquid Glass, and zoom transitions" width="320" />
45
+ <img
46
+ src="./docs/demo-options.webp"
47
+ alt="Animated native navigation options demo showing dynamic colors, selected labels, custom indicators, badges, system Liquid Glass, and zoom transitions"
48
+ width="320"
49
+ />
26
50
 
27
- ## What It Does
51
+ ## Features
28
52
 
29
- - Renders native top navigation and bottom tab chrome from JavaScript state.
30
- - Emits native intent events such as `navbarBack`, `navbarItemTap`, and `tabSelect`.
31
- - Captures WebView snapshots for native-feeling push, back, root, tab, and zoom transition shells.
32
- - Supports native tab styling controls such as Material You dynamic colors, label visibility, indicators, ripples, badges, and selected icons.
33
- - Writes CSS variables so web content can scroll behind native bars without being hidden.
34
- - Works with React, Vue, Angular, Svelte, Solid, vanilla JS, and any router that can call imperative methods.
53
+ - Drive native top navigation and bottom tabs from JavaScript state.
54
+ - Use system-owned iOS navigation bars, tab bars, tab gestures, and Liquid Glass rendering.
55
+ - Emit native intent events such as `navbarBack`, `navbarItemTap`, and `tabSelect`.
56
+ - Capture WebView snapshots for native-feeling push, back, root, tab, and zoom transitions.
57
+ - Configure tab labels, selected icons, badges, indicators, ripples, tint colors, and dynamic colors.
58
+ - Write CSS inset variables so web content can scroll behind native bars without being hidden.
59
+ - Work with React, Vue, Angular, Svelte, Solid, vanilla JS, and any router that exposes imperative navigation.
35
60
 
36
- ## What It Does Not Do
61
+ ## How It Fits
37
62
 
38
- - It does not create one native WebView per route.
39
- - It does not render React/Vue/Svelte icon nodes natively. Icons must be serializable descriptors such as SVG strings, SF Symbols, or native resource names.
40
- - It does not replace your router. JS still owns route state and web content rendering.
63
+ - Your router still owns route state and page rendering.
64
+ - The app still uses one full-screen WebView.
65
+ - Icons must be serializable descriptors such as SVG strings, SF Symbols, or native resource names.
41
66
 
42
67
  ## Compatibility
43
68
 
44
- | Plugin version | Capacitor compatibility | Maintained |
45
- | -------------- | ----------------------- | ---------- |
46
- | v8.\*.\* | v8.\*.\* | Yes |
47
- | v7.\*.\* | v7.\*.\* | On demand |
48
- | v6.\*.\* | v6.\*.\* | On demand |
69
+ `@capgo/capacitor-native-navigation` targets Capacitor 8 and Node.js 22+.
49
70
 
50
71
  ## Install
51
72
 
52
73
  ```bash
53
- bun add @capgo/capacitor-native-navigation
54
- bunx cap sync
74
+ npm install @capgo/capacitor-native-navigation
75
+ npx cap sync
55
76
  ```
56
77
 
57
78
  ## Minimal Usage
@@ -105,8 +126,8 @@ await NativeNavigation.setTabbar({
105
126
  ],
106
127
  });
107
128
 
108
- NativeNavigation.addListener('tabSelect', ({ id }) => {
109
- router.navigate(id);
129
+ await NativeNavigation.addListener('tabSelect', ({ id }) => {
130
+ router.navigate(`/${id}`);
110
131
  });
111
132
  ```
112
133
 
@@ -308,7 +329,7 @@ const icon = {
308
329
  width: 24,
309
330
  height: 24,
310
331
  template: true,
311
- src: 'fallback_asset_name',
332
+ src: 'shared_asset_name',
312
333
  ios: {
313
334
  svg: '<svg viewBox="0 0 24 24"><path d="M3 10.5 12 3l9 7.5"/></svg>',
314
335
  sfSymbol: 'house.fill',
@@ -326,9 +347,9 @@ Inline SVG supports the icon-focused subset used by common sets such as Lucide a
326
347
 
327
348
  ## Platform Notes
328
349
 
329
- - iOS uses UIKit `UINavigationBar` and `UITabBar`. iOS 26+ hosts the tabbar in a real `UITabBarController` so Apple owns the system Liquid Glass background; earlier versions use native translucent/material fallback styling.
330
- - Android uses an AppCompat `Toolbar` and a floating native tab capsule with edge-to-edge placement.
331
- - Web fallback does not draw native bars; it mirrors inset variables and events for development.
350
+ - iOS uses UIKit `UINavigationBar`, `UITabBar`, and `UITabBarController` so the system owns tab interaction, Liquid Glass rendering, and safe-area behavior.
351
+ - Android uses an AppCompat `Toolbar` and a native bottom tab surface with edge-to-edge placement.
352
+ - Web mirrors inset variables and events for local development.
332
353
 
333
354
  ## Example App
334
355
 
@@ -336,11 +357,11 @@ The `example-app/` folder is a vanilla JS Capacitor demo linked with `file:..`.
336
357
 
337
358
  ```bash
338
359
  cd example-app
339
- bun install
340
- bun run build
341
- bunx cap add ios
342
- bunx cap add android
343
- bunx cap sync
360
+ npm install
361
+ npm run build
362
+ npx cap add ios
363
+ npx cap add android
364
+ npx cap sync
344
365
  ```
345
366
 
346
367
  ## API
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@capgo/capacitor-native-navigation",
3
- "version": "8.0.18",
4
- "description": "Capacitor plugin for native navbar, tabbar, and route transition chrome over a WebView.",
3
+ "version": "8.0.20",
4
+ "description": "Capacitor plugin for native navbar, tabbar, safe-area handling, and WebView snapshot transitions.",
5
5
  "main": "dist/plugin.cjs.js",
6
6
  "module": "dist/esm/index.js",
7
7
  "types": "dist/esm/index.d.ts",
@@ -52,7 +52,12 @@
52
52
  "watch": "tsc --watch",
53
53
  "prepublishOnly": "bun run build",
54
54
  "check:wiring": "node scripts/check-capacitor-plugin-wiring.mjs",
55
- "demo:readme": "bun scripts/generate-readme-demos.mjs"
55
+ "demo:readme": "bun scripts/generate-readme-demos.mjs",
56
+ "example:build": "bun run build && cd example-app && bun install && bun run build",
57
+ "example:capgo:deploy": "bun run example:build && bun scripts/deploy-example-capgo.mjs",
58
+ "example:sync": "bun run example:build && cd example-app && bunx cap sync",
59
+ "example:ios": "bun run example:build && cd example-app && ([ -d ios ] || bunx cap add ios) && bunx cap sync ios && bunx cap run ios",
60
+ "example:android": "bun run example:build && cd example-app && ([ -d android ] || bunx cap add android) && bunx cap sync android && bunx cap run android"
56
61
  },
57
62
  "devDependencies": {
58
63
  "@capacitor/android": "^8.0.0",