docs: add verified package usage examples

2026-07-13 20:51:04 +05:30
parent 7a1c6c0041
commit 4ce087b238
67 changed files with 592 additions and 136 deletions
@@ -1,17 +1,85 @@
 # @wrnexus/native

-Cross-platform capabilities for browsers, Capacitor WebViews, and compiled native apps.
+> 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";

-if (native.supports("share")) await native.run("share", { title: "WrNexus", url: location.href });
+export async function shareCurrentPage() {
+  if (!native.supports("share")) return false;
+  await native.run("share", {
+    title: document.title,
+    url: location.href,
+  });
+  return true;
+}
 ```

-Built-ins include `camera`, `clipboard.write`, `share`, `geolocation`, `network`,
-`haptics`, storage, filesystem, notifications, and device information. Browser
-capabilities use Web APIs; mobile capabilities use installed Capacitor plugins.
+### Register an application-specific capability

-`platform()` returns `server` during SSR, `browser` on the web, and the Capacitor
-platform in a native WebView. Unsupported operations reject with
-`NativeUnavailableError`; use `supports()` before presenting optional UI.
+`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.
+
+## Requirements / Notes
+
+Use `supports()` before showing optional controls. Mobile capabilities require their
+matching Capacitor plugins to be installed and registered by the application.