@colixsystems/widget-sdk 0.48.0 → 0.49.0

package/README.md

@@ -27,6 +27,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useRefresh(handler)` | `void` | `ctx.refresh.subscribe` — no scope. Subscribes the handler to the page-level refresh tick (pull-to-refresh on mobile). Handler may return a Promise — the host waits for `allSettled` before clearing the spinner. The three datastore hooks auto-subscribe their own `refetch`; widgets only call this directly to re-run non-datastore work. No-op on a host that doesn't implement refresh. |
 | **CORE** | `useClipboard()` | `{ copy, paste, hasContent }` | platform clipboard (web `navigator.clipboard` / native `expo-clipboard`); rejects with `ClipboardError` — no scope |
 | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` (falls back to a CustomEvent / console) — no scope |
+| **CORE** | `useGeolocation(options?)` | `{ latitude, longitude, accuracy, loading, error, getCurrentPosition }` | `ctx.device.geolocation` — no scope. Capture is IMPERATIVE: call `getCurrentPosition()` from a user gesture (a tap), never on mount. Resolves to `{ latitude, longitude, accuracy }`; rejects with `GeolocationError` (`.code` in `PERMISSION_DENIED \| UNAVAILABLE \| TIMEOUT \| UNSUPPORTED \| INTERNAL`). Identical on web (`navigator.geolocation`) and the Expo export (`expo-location`). |
 | **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
 | **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options?)` | `{ data, loading, error, refetch }` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
 | **DATASTORE** | `useDatastoreRecord(table, id)` | `{ data, loading, error, refetch }` | `records(table).get` — `datastore.read:<table>` |
@@ -50,7 +51,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.48.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.49.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.49.0
+
+**New `useGeolocation()` hook — read the device's current position (sc-1584).** A new CORE hook reading a newly-injected `ctx.device` slice (host-brokered device capabilities). Returns `{ latitude, longitude, accuracy, loading, error, getCurrentPosition }`. Capture is **imperative** — call `getCurrentPosition()` from a user gesture (a `Pressable.onPress`); browsers and the mobile OS gate the permission prompt on a gesture, so it NEVER fires on mount. The promise resolves to `{ latitude, longitude, accuracy }` and mirrors the same values onto the hook; `options` (`{ enableHighAccuracy, timeout, maximumAge }`) pass through to the host. Rejections surface as a structured `GeolocationError` (new named export) with a stable `.code` (`PERMISSION_DENIED` / `UNAVAILABLE` / `TIMEOUT` / `UNSUPPORTED` / `INTERNAL`). It needs **no manifest scope** and **no `requestedScopes` entry**. The web Player brokers it via `navigator.geolocation`; the Expo export via `expo-location` — so device access is identical on both platforms. The `ctx.device` slice is optional: a host that can't broker the sensor omits it and the hook degrades to an `UNSUPPORTED` error rather than throwing at render. `CONTRACT.version` → `1.36.0`. Additive — one new hook, one new optional context slice, one new error class; no existing export changed signature.
 
 ### What's new in 0.48.0
 
@@ -369,6 +374,7 @@ The "split-implementation + vetted package list" pivot.
 ### What was in 0.4.1
 
 - **`useDatastoreQuery` returns a stable `refetch` identity.** The hook no longer rebinds the underlying callback when the host's `WidgetContext` value (a fresh object identity on every render in Studio + PageRenderer) changes. Widgets that put `refetch` in a `useEffect` dep array no longer loop.
+- **Keep the `useDatastoreQuery` argument stable across renders.** The hook re-fetches whenever `[table, JSON.stringify(query)]` changes, so a query whose serialized value differs every render refetches forever and the widget is stuck on its loading state. The classic trap is a time-relative filter built with `new Date()` / `Date.now()` inline in the query (a "this week" / "today" range) — the timestamp advances each render, so the key is never the same twice. Compute the date/time bound once with `useMemo(() => …, [])` (round to the day if you only need day granularity) and pass the stable value in. The same applies to any per-render value (a freshly built object, `Math.random()`): memoize it before it enters the query.
 
 ### What's new in 0.4.0
 

package/dist/contract.cjs

@@ -637,6 +637,30 @@ const HOOKS = [
     requiredContextSlice: ["toast.showToast"],
     scopes: null,
   },
+  // sc-1584 — host-brokered device geolocation. Optional slice; the hook
+  // degrades to an UNSUPPORTED error rather than throwing at render.
+  {
+    name: "useGeolocation",
+    signature: "useGeolocation(options?)",
+    description:
+      "Read the device's current position. Returns { latitude, longitude, accuracy, loading, error, getCurrentPosition }. " +
+      "Capture is IMPERATIVE — call getCurrentPosition() from a user gesture (a tap); browsers and the mobile OS gate the " +
+      "permission prompt on a gesture, so it NEVER fires on mount. The promise resolves to { latitude, longitude, accuracy } " +
+      "and stores the same values on the hook; it rejects with a GeolocationError whose .code is one of PERMISSION_DENIED | " +
+      "UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL. options pass through to the host ({ enableHighAccuracy, timeout, " +
+      "maximumAge }). Identical on web (navigator.geolocation) and the Expo export (expo-location).",
+    returnShape: {
+      latitude: "number | null",
+      longitude: "number | null",
+      accuracy: "number | null  // metres, best-effort",
+      loading: "boolean",
+      error: "GeolocationError | null",
+      getCurrentPosition:
+        "() => Promise<{ latitude, longitude, accuracy }>  // rejects with GeolocationError",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -1083,6 +1107,19 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { showToast: "function" },
   },
+  // sc-1584 — host-brokered device capabilities. Optional: a host that can't
+  // broker a sensor omits the slice and useGeolocation() surfaces UNSUPPORTED.
+  // Both the web Player (navigator.geolocation) and the Expo export
+  // (expo-location) inject it, so device access is identical on both platforms.
+  device: {
+    description:
+      "Optional host-brokered device capabilities. " +
+      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> } }. " +
+      "Backs useGeolocation(). The web Player brokers it via navigator.geolocation; the Expo export via expo-location. " +
+      "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL).",
+    required: false,
+    fields: { geolocation: "object" },
+  },
 };
 
 const BUNDLE_EXPORT_CONTRACT = [
@@ -1778,7 +1815,7 @@ const CONTRACT = deepFreeze({
   //    `notifications.send:appUser` scope it gates on. No existing hook,
   //    primitive, manifest field, or token changed shape — minor bump on the
   //    pre-1.0 channel.
-  version: "1.35.0",
+  version: "1.36.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -637,6 +637,30 @@ const HOOKS = [
     requiredContextSlice: ["toast.showToast"],
     scopes: null,
   },
+  // sc-1584 — host-brokered device geolocation. Optional slice; the hook
+  // degrades to an UNSUPPORTED error rather than throwing at render.
+  {
+    name: "useGeolocation",
+    signature: "useGeolocation(options?)",
+    description:
+      "Read the device's current position. Returns { latitude, longitude, accuracy, loading, error, getCurrentPosition }. " +
+      "Capture is IMPERATIVE — call getCurrentPosition() from a user gesture (a tap); browsers and the mobile OS gate the " +
+      "permission prompt on a gesture, so it NEVER fires on mount. The promise resolves to { latitude, longitude, accuracy } " +
+      "and stores the same values on the hook; it rejects with a GeolocationError whose .code is one of PERMISSION_DENIED | " +
+      "UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL. options pass through to the host ({ enableHighAccuracy, timeout, " +
+      "maximumAge }). Identical on web (navigator.geolocation) and the Expo export (expo-location).",
+    returnShape: {
+      latitude: "number | null",
+      longitude: "number | null",
+      accuracy: "number | null  // metres, best-effort",
+      loading: "boolean",
+      error: "GeolocationError | null",
+      getCurrentPosition:
+        "() => Promise<{ latitude, longitude, accuracy }>  // rejects with GeolocationError",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -1083,6 +1107,19 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { showToast: "function" },
   },
+  // sc-1584 — host-brokered device capabilities. Optional: a host that can't
+  // broker a sensor omits the slice and useGeolocation() surfaces UNSUPPORTED.
+  // Both the web Player (navigator.geolocation) and the Expo export
+  // (expo-location) inject it, so device access is identical on both platforms.
+  device: {
+    description:
+      "Optional host-brokered device capabilities. " +
+      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> } }. " +
+      "Backs useGeolocation(). The web Player brokers it via navigator.geolocation; the Expo export via expo-location. " +
+      "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL).",
+    required: false,
+    fields: { geolocation: "object" },
+  },
 };
 
 const BUNDLE_EXPORT_CONTRACT = [
@@ -1778,7 +1815,7 @@ const CONTRACT = deepFreeze({
   //    `notifications.send:appUser` scope it gates on. No existing hook,
   //    primitive, manifest field, or token changed shape — minor bump on the
   //    pre-1.0 channel.
-  version: "1.35.0",
+  version: "1.36.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -336,6 +336,141 @@ export function useI18n() {
   return { t, locale };
 }
 
+/* ============================================================================
+ * DEVICE — ctx.device (host-brokered device capabilities)
+ *
+ * Sensor / hardware the host brokers for the widget — geolocation today. The
+ * host injects `ctx.device.<cap>` on BOTH platforms (web Player via
+ * navigator.geolocation; the Expo export via expo-location), so a widget reads
+ * the device identically on web and native (widget-parity skill). The slice is
+ * optional — a host that cannot broker a capability omits it and the hook
+ * surfaces an UNSUPPORTED error instead of throwing at render. Covers:
+ *   useGeolocation.
+ * ==========================================================================*/
+
+/**
+ * Error thrown by `useGeolocation().getCurrentPosition()` (and surfaced in the
+ * hook's `error` slot). Carries a stable `code` so widgets branch on the error
+ * class without parsing message strings.
+ *
+ * `code` is one of:
+ *   - "PERMISSION_DENIED" — the user (or OS) refused location access.
+ *   - "UNAVAILABLE"       — position could not be determined (no fix / sensor).
+ *   - "TIMEOUT"           — the request exceeded the host/option timeout.
+ *   - "UNSUPPORTED"       — this host does not broker geolocation.
+ *   - "INTERNAL"          — anything else.
+ */
+export class GeolocationError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "GeolocationError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+/**
+ * Coerce a thrown value into a GeolocationError with a stable `.code`. Maps the
+ * browser PositionError numeric codes (1/2/3) and the host clients' string
+ * codes onto one vocabulary.
+ */
+function toGeolocationError(err) {
+  if (err instanceof GeolocationError) return err;
+  const raw = err && err.code !== undefined ? err.code : null;
+  let code = "INTERNAL";
+  if (raw === 1 || raw === "PERMISSION_DENIED") code = "PERMISSION_DENIED";
+  else if (raw === 2 || raw === "UNAVAILABLE" || raw === "POSITION_UNAVAILABLE")
+    code = "UNAVAILABLE";
+  else if (raw === 3 || raw === "TIMEOUT") code = "TIMEOUT";
+  else if (raw === "UNSUPPORTED") code = "UNSUPPORTED";
+  const message =
+    (err && typeof err.message === "string" && err.message) ||
+    "Geolocation request failed";
+  return new GeolocationError(code, message, { cause: err });
+}
+
+/**
+ * Read the device's current position. Returns
+ *   `{ latitude, longitude, accuracy, loading, error, getCurrentPosition }`.
+ *
+ * Capture is IMPERATIVE — call `getCurrentPosition()` from a user gesture (a
+ * tap on a button). Browsers and the mobile OS gate the permission prompt on a
+ * user gesture, so the hook never fires on mount. The promise resolves to
+ * `{ latitude, longitude, accuracy }` and the same values are stored on the
+ * hook; it rejects with a `GeolocationError` carrying a stable `.code`.
+ *
+ * `options` pass through to the host (`{ enableHighAccuracy, timeout,
+ * maximumAge }`). The SAME hook drives both platforms: the web Player brokers
+ * it through `navigator.geolocation`, the Expo export through `expo-location`.
+ *
+ * Safe-by-default: on a host that does not inject `ctx.device.geolocation`,
+ * `getCurrentPosition()` rejects with `code: "UNSUPPORTED"` rather than
+ * throwing at render, so a widget can call the hook unconditionally.
+ */
+export function useGeolocation(options) {
+  const ctx = useWidgetContextOrThrow("useGeolocation");
+  const [coords, setCoords] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+
+  // `ctx` is a fresh identity every host render — hold the live client +
+  // options in refs so getCurrentPosition is a stable callback.
+  const clientRef = useRef(ctx.device && ctx.device.geolocation);
+  clientRef.current = ctx.device && ctx.device.geolocation;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const runRef = useRef(0);
+
+  const getCurrentPosition = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const client = clientRef.current;
+    if (!client || typeof client.getCurrentPosition !== "function") {
+      const e = new GeolocationError(
+        "UNSUPPORTED",
+        "This host does not provide device geolocation.",
+      );
+      if (runRef.current === myRun) {
+        setError(e);
+        setLoading(false);
+      }
+      throw e;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const pos = await client.getCurrentPosition(optionsRef.current);
+      const next = {
+        latitude:
+          pos && typeof pos.latitude === "number" ? pos.latitude : null,
+        longitude:
+          pos && typeof pos.longitude === "number" ? pos.longitude : null,
+        accuracy:
+          pos && typeof pos.accuracy === "number" ? pos.accuracy : null,
+      };
+      if (runRef.current !== myRun) return next;
+      setCoords(next);
+      setLoading(false);
+      return next;
+    } catch (err) {
+      const ge = toGeolocationError(err);
+      if (runRef.current === myRun) {
+        setError(ge);
+        setLoading(false);
+      }
+      throw ge;
+    }
+  }, []);
+
+  return {
+    latitude: coords ? coords.latitude : null,
+    longitude: coords ? coords.longitude : null,
+    accuracy: coords ? coords.accuracy : null,
+    loading,
+    error,
+    getCurrentPosition,
+  };
+}
+
 /* ============================================================================
  * DATASTORE CLIENT — ctx.datastore (@colixsystems/datastore-client)
  *

package/dist/index.d.ts

@@ -464,6 +464,16 @@ export interface WidgetContext<TProps = unknown> {
   toast?: {
     showToast(args: { kind?: string; message: string }): void;
   };
+  /** Optional host-brokered device capabilities; backs useGeolocation. */
+  device?: {
+    geolocation?: {
+      getCurrentPosition(options?: GeolocationOptions): Promise<{
+        latitude: number;
+        longitude: number;
+        accuracy: number;
+      }>;
+    };
+  };
 }
 
 /**
@@ -921,6 +931,60 @@ export function useRefresh(
   handler: () => void | Promise<unknown>,
 ): void;
 
+/** Pass-through options for `useGeolocation().getCurrentPosition(...)`. */
+export interface GeolocationOptions {
+  enableHighAccuracy?: boolean;
+  timeout?: number;
+  maximumAge?: number;
+}
+
+export interface GeolocationResult {
+  latitude: number | null;
+  longitude: number | null;
+  /** Best-effort accuracy in metres. */
+  accuracy: number | null;
+  loading: boolean;
+  error: GeolocationError | null;
+  /**
+   * Imperatively read the device position — call from a user gesture. Resolves
+   * to `{ latitude, longitude, accuracy }` and stores the same on the hook;
+   * rejects with a `GeolocationError`.
+   */
+  getCurrentPosition(): Promise<{
+    latitude: number;
+    longitude: number;
+    accuracy: number;
+  }>;
+}
+
+/**
+ * sc-1584 — read the device's current position. Capture is imperative (call
+ * `getCurrentPosition()` from a user gesture; it never fires on mount). The
+ * same hook drives both platforms — the web Player brokers it via
+ * `navigator.geolocation`, the Expo export via `expo-location`. Safe to call on
+ * a host that doesn't broker geolocation: `getCurrentPosition()` then rejects
+ * with `code: "UNSUPPORTED"`.
+ */
+export function useGeolocation(options?: GeolocationOptions): GeolocationResult;
+
+/**
+ * sc-1584 — error thrown by `useGeolocation().getCurrentPosition()` and
+ * surfaced in the hook's `error` slot. `code` is a stable categorisation.
+ */
+export class GeolocationError extends Error {
+  code:
+    | "PERMISSION_DENIED"
+    | "UNAVAILABLE"
+    | "TIMEOUT"
+    | "UNSUPPORTED"
+    | "INTERNAL";
+  constructor(
+    code: GeolocationError["code"],
+    message: string,
+    opts?: { cause?: unknown },
+  );
+}
+
 /**
  * Error class thrown by useDatastoreMutation callbacks (and surfaced by
  * useDatastoreQuery in its `error` slot). The `code` is a stable

package/dist/index.js

@@ -42,6 +42,8 @@ export {
   useNavigation,
   useChildRenderer,
   useRefresh,
+  useGeolocation,
+  GeolocationError,
   WidgetTree,
 } from "./hooks.js";
 // REQ-WSDK-PLATFORM §6 — Tier A hooks. Each ships in a per-platform file

package/dist/index.native.js

@@ -40,6 +40,8 @@ export {
   useNavigation,
   useChildRenderer,
   useRefresh,
+  useGeolocation,
+  GeolocationError,
   WidgetTree,
 } from "./hooks.js";
 // REQ-WSDK-PLATFORM §6 — Tier A hooks (native variants).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,7 +42,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js"
   },
   "engines": {
     "node": ">=18"