89 lines
2.6 KiB
Markdown
89 lines
2.6 KiB
Markdown
# @wrnexus/native
|
|
|
|
> Cross-platform capabilities for browsers, Capacitor WebViews, and compiled native apps.
|
|
|
|
## Overview
|
|
|
|
`@wrnexus/native` exposes capabilities by name so application code can ask what the
|
|
current platform supports before presenting an action. Browser capabilities use Web
|
|
APIs; mobile capabilities use installed Capacitor plugins. `platform()` returns
|
|
`"server"` during SSR, `"browser"` on the web, and the Capacitor platform in a native
|
|
WebView.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
bun add @wrnexus/native
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Share a page when the platform supports it
|
|
|
|
```ts
|
|
import { native } from "@wrnexus/native";
|
|
|
|
export async function shareCurrentPage() {
|
|
if (!native.supports("share")) return false;
|
|
await native.run("share", {
|
|
title: document.title,
|
|
url: location.href,
|
|
});
|
|
return true;
|
|
}
|
|
```
|
|
|
|
### Register an application-specific capability
|
|
|
|
`register` returns an unregister function, which is useful for tests and temporary
|
|
feature modules.
|
|
|
|
```ts
|
|
import { native } from "@wrnexus/native";
|
|
|
|
const unregister = native.register("orders.scan", {
|
|
browser: {
|
|
supported: () => typeof window !== "undefined",
|
|
run: async ({ orderId }: { orderId: string }) => {
|
|
const code = window.prompt(`Scan code for order ${orderId}`);
|
|
return { code };
|
|
},
|
|
},
|
|
});
|
|
|
|
const result = await native.run<{ code: string | null }>("orders.scan", { orderId: "ord_42" });
|
|
unregister();
|
|
```
|
|
|
|
### Target browser or mobile behavior explicitly
|
|
|
|
```ts
|
|
import { native } from "@wrnexus/native";
|
|
|
|
const canUseMobileCamera = native.supports("camera", "mobile");
|
|
const position = await native.run(
|
|
"geolocation",
|
|
{ enableHighAccuracy: true },
|
|
{ target: "browser" },
|
|
);
|
|
```
|
|
|
|
## API
|
|
|
|
- `supports(name, target?)` checks availability without running the capability.
|
|
- `run(name, options?, runOptions?)` executes it or rejects with `NativeUnavailableError`.
|
|
- `register(name, capability)` adds or overrides a capability and returns cleanup.
|
|
- `registered()` lists capability names; `clearRegistry()` resets the registry.
|
|
- `isMobile()` and `platform()` report the current target safely during SSR.
|
|
|
|
Built-ins include `camera`, `clipboard.write`, `share`, `geolocation`, `network`,
|
|
`haptics`, storage, filesystem, notifications, and device information.
|
|
|
|
`defineNativeManifest` declares required capabilities and typed permissions, while
|
|
`PermissionManager` normalizes permission query/request flows across platform adapters.
|
|
|
|
## Requirements / Notes
|
|
|
|
Use `supports()` before showing optional controls. Mobile capabilities require their
|
|
matching Capacitor plugins to be installed and registered by the application.
|