@colixsystems/widget-sdk 0.48.0 → 0.50.0

package/README.md

@@ -1,6 +1,6 @@
 # @colixsystems/widget-sdk
 
-Common widget interface for [AppStudio](https://github.com/appstudio). This package is **core only** — it implements the contract that every widget (built-in or third-party, web or native) speaks: a `WidgetManifest`, a `WidgetContext`, a property schema, the primitives + rendering surface, the helper hooks, events, theme/i18n, and the static linter that gates submissions. **It owns no HTTP and depends on none of the data SDK packages.**
+Common widget interface for AppStudio. This package is **core only** — it implements the contract that every widget (built-in or third-party, web or native) speaks: a `WidgetManifest`, a `WidgetContext`, a property schema, the primitives + rendering surface, the helper hooks, events, theme/i18n, and the static linter that gates submissions. **It owns no HTTP and depends on none of the data SDK packages.**
 
 The data layer lives in **four separate domain-client packages**, each instantiated by the host and **injected into `WidgetContext`**. Widgets never import those packages — they reach the data surface only through this SDK's hooks, which read the injected client instances:
 
@@ -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
 
@@ -107,6 +112,10 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 **`useI18n().t()` no longer leaks the host's `{{t:key}}` miss placeholder.** Resolution steps 1–2 (per-widget and shared namespaces) already treated a `{{t:…}}` return from the host as a miss, but the final raw-key step did not — on the web Player (whose host resolver returns the placeholder form on a miss and ignores the fallback argument) a key absent from the tenant dictionary rendered as literal `{{t:key}}` text instead of degrading to `fallback ?? key`. The same guard now applies to all three steps. **The public contract is unchanged** — this is the behaviour `useI18n` always documented. `CONTRACT.version` is unchanged.
 
+### What's new in 0.50.0
+
+**`<DateTimePicker>` — tap the formatted date to open the picker (sc-1878).** The displayed date is now the affordance to change it on both hosts: on web, clicking the `<input>` text (or focusing it and pressing Enter / Space) calls `showPicker()` so the calendar opens from the text, not only the small built-in calendar icon; on native, the primitive renders an accessible, tappable formatted-date trigger that opens `@react-native-community/datetimepicker` on press (the RN library is imperative on Android, so the primitive owns the open/closed state — this also fixes the dialog auto-opening on mount). Both builds gained an `accessibilityLabel` prop that names the field for screen readers / test tooling. **The value contract is unchanged** — same `mode` values and ISO 8601 wire format on `value` / `onChange`; `CONTRACT.version` is unchanged.
+
 ### What's new in 0.40.1
 
 **`<DateTimePicker>` actually renders on web (sc-1118).** The primitive was a single source that wrapped `@react-native-community/datetimepicker`, but that library ships iOS / Android only and has no react-native-web mapping — on the web Player and Studio the primitive rendered nothing, so date columns in the built-in **Form Input** / **Form Builder** widgets showed a label and required-asterisk with no input beneath them. The implementation is now split: native (`./datetimepicker.native.js`) still wraps the RN library; web (`./datetimepicker.js`) renders the browser's native `<input type="date|time|datetime-local">` directly. **The public contract is unchanged** — same component name, same `{ value, onChange, mode, minimumDate, maximumDate, disabled }` props, same ISO 8601 wire format on the value and the `onChange` callback. `CONTRACT.version` is unchanged.
@@ -369,6 +378,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/datetimepicker-format.js

@@ -0,0 +1,53 @@
+// REQ-WSDK-PLATFORM §6 — pure date/ISO helpers for the native `<DateTimePicker>`.
+//
+// Split out of datetimepicker.native.js so the formatting contract can be
+// unit-tested without importing react-native / the RN datetimepicker library
+// (neither is installed in this package's node tree). No React, no RN here —
+// just Date math and string shaping.
+
+export function parseToDate(value) {
+  if (value == null || value === "") return new Date();
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? new Date() : value;
+  if (typeof value === "string") {
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? new Date() : d;
+  }
+  return new Date();
+}
+
+export function formatToIso(date, mode) {
+  if (!(date instanceof Date) || Number.isNaN(date.getTime())) return null;
+  if (mode === "date") {
+    // Local-date ISO (yyyy-mm-dd) — calendar dates are timezone-free so a
+    // "May 28" picked in Stockholm doesn't read as "May 27" in NYC.
+    const y = date.getFullYear();
+    const m = String(date.getMonth() + 1).padStart(2, "0");
+    const d = String(date.getDate()).padStart(2, "0");
+    return `${y}-${m}-${d}`;
+  }
+  if (mode === "time") {
+    // Local-time ISO (hh:mm) — time-of-day is timezone-free for the same reason.
+    const h = String(date.getHours()).padStart(2, "0");
+    const mm = String(date.getMinutes()).padStart(2, "0");
+    return `${h}:${mm}`;
+  }
+  // datetime — full UTC ISO so the wire format round-trips through a DATE column.
+  return date.toISOString();
+}
+
+// The label shown on the tappable trigger. Empty value → a mode-specific
+// placeholder so the field reads as "tap to pick" rather than blank.
+export function formatDisplayLabel(value, mode) {
+  const effectiveMode = mode === "time" || mode === "datetime" ? mode : "date";
+  if (value == null || value === "") {
+    if (effectiveMode === "time") return "Select time";
+    if (effectiveMode === "datetime") return "Select date & time";
+    return "Select date";
+  }
+  if (effectiveMode === "date") return String(value).slice(0, 10);
+  if (effectiveMode === "time") return String(value).slice(0, 5);
+  // datetime — render the stored UTC ISO in the user's local clock.
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return String(value);
+  return `${formatToIso(d, "date")} ${formatToIso(d, "time")}`;
+}

package/dist/datetimepicker.js

@@ -102,9 +102,33 @@ export function DateTimePicker({
       ? _isoToInputValue(maximumDate, effectiveMode)
       : undefined;
 
+  // sc-1878 — clicking the formatted date text (or focusing it and pressing
+  // Enter / Space) opens the native calendar, not just the small built-in
+  // calendar icon. `showPicker()` requires a user gesture; click/keydown both
+  // qualify. Guarded: not every browser/build exposes it, and calling it while
+  // the picker is already open throws — neither should break the field.
+  const openPicker = (target) => {
+    if (disabled || !target || typeof target.showPicker !== "function") return;
+    try {
+      target.showPicker();
+    } catch {
+      // Already open, or blocked outside a user gesture — leave the input as-is.
+    }
+  };
+
+  const handleClick = (event) => openPicker(event.currentTarget);
+
+  const handleKeyDown = (event) => {
+    if (event.key === "Enter" || event.key === " " || event.key === "Spacebar") {
+      event.preventDefault();
+      openPicker(event.currentTarget);
+    }
+  };
+
   // Inline styles match the SDK's other web-only primitives — the host's
   // form widgets wrap this in their own labelled field, so the input just
-  // needs to look like a normal text input.
+  // needs to look like a normal text input. `cursor: pointer` signals the
+  // whole field is the click affordance (sc-1878).
   const style = {
     boxSizing: "border-box",
     width: "100%",
@@ -119,12 +143,15 @@ export function DateTimePicker({
     borderColor: "rgba(0, 0, 0, 0.16)",
     borderRadius: 6,
     outline: "none",
+    cursor: disabled ? "default" : "pointer",
   };
 
   return React.createElement("input", {
     type: inputType,
     value: inputValue,
     onChange: handleChange,
+    onClick: handleClick,
+    onKeyDown: handleKeyDown,
     min,
     max,
     disabled: !!disabled,

package/dist/datetimepicker.native.js

@@ -1,65 +1,52 @@
-// REQ-WSDK-PLATFORM §6 — `<DateTimePicker>` SDK primitive.
+// REQ-WSDK-PLATFORM §6 — `<DateTimePicker>` SDK primitive (native).
 //
-// Cross-platform date / time / datetime picker. Wraps
-// `@react-native-community/datetimepicker` (works on both web and native:
-// on web it renders the browser's native `<input type="date|time">`
-// surface through react-native-web's mapping). The wire format is ISO
-// 8601 strings — the same format the datastore speaks, so widget authors
-// never round-trip through `new Date()`.
+// Wraps `@react-native-community/datetimepicker`. That library is imperative
+// on Android — rendering it shows the dialog immediately and re-mounting is
+// the only way to reopen it — so the primitive owns a small open/closed state
+// and renders a tappable, formatted-date trigger (sc-1878). Tapping the
+// formatted date (the trigger is an accessible button, reachable by keyboard /
+// screen-reader) opens the picker; choosing a value closes it and emits the
+// ISO string. This mirrors the web build, where clicking the `<input>` text
+// calls `showPicker()` — both hosts: tap the date, the picker opens.
 //
-// Props:
+// Props (mirrors datetimepicker.js):
 //   value: string | null   — ISO 8601 (`2026-05-28` for date mode,
-//                            `2026-05-28T14:30:00.000Z` for datetime).
-//                            `null` defaults to "now".
+//                            `14:30` for time mode,
+//                            `2026-05-28T14:30:00.000Z` for datetime mode).
+//                            `null` / "" shows the placeholder, opens at "now".
 //   onChange: (iso: string) => void
 //   mode:    "date" | "time" | "datetime"  — default "date"
 //   minimumDate / maximumDate: string | null  — ISO bounds
 //   disabled: boolean
-//
-// The author writes:
-//   const [day, setDay] = useState(null);
-//   <DateTimePicker value={day} onChange={setDay} mode="date" />
-//
-// …and `day` ends up as an ISO string suitable for storing directly into
-// a DATE column. The previous pattern of importing the RN library
-// directly and managing `Date` objects in widget state is gone — the
-// primitive normalizes both ends.
+//   accessibilityLabel: string | undefined  — names the trigger button so the
+//                            shared form-field renderer's column label reaches
+//                            screen readers / test tooling, matching the web
+//                            input's `aria-label`.
 
-import React, { useMemo } from "react";
+import React, { useMemo, useState } from "react";
 // eslint-disable-next-line no-restricted-syntax
 import RNDateTimePicker from "@react-native-community/datetimepicker";
+import { Pressable, Text, StyleSheet } from "react-native";
+import {
+  parseToDate,
+  formatToIso,
+  formatDisplayLabel,
+} from "./datetimepicker-format.js";
 
-function _parseToDate(value) {
-  if (value == null || value === "") return new Date();
-  if (value instanceof Date) return Number.isNaN(value.getTime()) ? new Date() : value;
-  if (typeof value === "string") {
-    const d = new Date(value);
-    return Number.isNaN(d.getTime()) ? new Date() : d;
-  }
-  return new Date();
-}
-
-function _formatToIso(date, mode) {
-  if (!(date instanceof Date) || Number.isNaN(date.getTime())) return null;
-  if (mode === "date") {
-    // Local-date ISO (yyyy-mm-dd) — calendar dates should be timezone-free
-    // so a "May 28" picked in Stockholm doesn't read as "May 27" in NYC.
-    const y = date.getFullYear();
-    const m = String(date.getMonth() + 1).padStart(2, "0");
-    const d = String(date.getDate()).padStart(2, "0");
-    return `${y}-${m}-${d}`;
-  }
-  if (mode === "time") {
-    // Local-time ISO (hh:mm) — time-of-day is timezone-free for the same
-    // reason. Authors who want a full datetime get mode="datetime".
-    const h = String(date.getHours()).padStart(2, "0");
-    const mm = String(date.getMinutes()).padStart(2, "0");
-    return `${h}:${mm}`;
-  }
-  // datetime — full UTC ISO so the wire format round-trips through the
-  // datastore's DATE column unchanged.
-  return date.toISOString();
-}
+const styles = StyleSheet.create({
+  trigger: {
+    minHeight: 44,
+    paddingVertical: 8,
+    paddingHorizontal: 12,
+    borderWidth: 1,
+    borderColor: "rgba(0, 0, 0, 0.16)",
+    borderRadius: 6,
+    justifyContent: "center",
+  },
+  triggerDisabled: { opacity: 0.5 },
+  label: { fontSize: 16 },
+  placeholder: { fontSize: 16, opacity: 0.5 },
+});
 
 export function DateTimePicker({
   value,
@@ -68,35 +55,65 @@ export function DateTimePicker({
   minimumDate,
   maximumDate,
   disabled,
+  accessibilityLabel,
 }) {
   const effectiveMode = mode === "time" || mode === "datetime" ? mode : "date";
-  const dateValue = useMemo(() => _parseToDate(value), [value]);
+  const [open, setOpen] = useState(false);
+  const dateValue = useMemo(() => parseToDate(value), [value]);
   const min = useMemo(
-    () => (minimumDate ? _parseToDate(minimumDate) : undefined),
+    () => (minimumDate ? parseToDate(minimumDate) : undefined),
     [minimumDate],
   );
   const max = useMemo(
-    () => (maximumDate ? _parseToDate(maximumDate) : undefined),
+    () => (maximumDate ? parseToDate(maximumDate) : undefined),
     [maximumDate],
   );
 
-  const handleChange = (_event, picked) => {
+  const isEmpty = value == null || value === "";
+
+  const handleChange = (event, picked) => {
+    // Android fires "dismissed" when the user cancels; close without emitting.
+    setOpen(false);
+    if (event?.type === "dismissed") return;
     if (typeof onChange !== "function") return;
     if (!(picked instanceof Date)) return;
-    const iso = _formatToIso(picked, effectiveMode);
+    const iso = formatToIso(picked, effectiveMode);
     if (iso != null) onChange(iso);
   };
 
-  // The RN library's `mode` accepts "date" / "time"; for "datetime" we
-  // ask for "datetime" on iOS / Android and let the picker's
-  // implementation handle it. react-native-web's mapping interprets
-  // "datetime" as `<input type="datetime-local">`.
-  return React.createElement(RNDateTimePicker, {
-    value: dateValue,
-    mode: effectiveMode,
-    minimumDate: min,
-    maximumDate: max,
-    disabled: !!disabled,
-    onChange: handleChange,
-  });
+  const trigger = React.createElement(
+    Pressable,
+    {
+      onPress: () => { if (!disabled) setOpen(true); },
+      disabled: !!disabled,
+      accessibilityRole: "button",
+      accessibilityLabel,
+      accessibilityState: { disabled: !!disabled },
+      style: [styles.trigger, disabled && styles.triggerDisabled],
+    },
+    React.createElement(
+      Text,
+      { style: isEmpty ? styles.placeholder : styles.label },
+      formatDisplayLabel(value, effectiveMode),
+    ),
+  );
+
+  if (!open) return trigger;
+
+  // The RN library's `mode` is "date" / "time"; iOS also honours "datetime",
+  // Android falls back to date-only for it (a pre-existing limit, unchanged
+  // here). The web build uses datetimepicker.js, so this file is never web.
+  return React.createElement(
+    React.Fragment,
+    null,
+    trigger,
+    React.createElement(RNDateTimePicker, {
+      value: dateValue,
+      mode: effectiveMode,
+      minimumDate: min,
+      maximumDate: max,
+      disabled: !!disabled,
+      onChange: handleChange,
+    }),
+  );
 }

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/dist/lucideIconNames.cjs

@@ -1452,6 +1452,7 @@ const LUCIDE_ICON_NAMES = [
   "Worm",
   "WrapText",
   "Wrench",
+  "X",
   "Youtube",
   "Zap",
   "ZapOff",

package/dist/lucideIconNames.js

@@ -1452,6 +1452,7 @@ export const LUCIDE_ICON_NAMES = [
   "Worm",
   "WrapText",
   "Wrench",
+  "X",
   "Youtube",
   "Zap",
   "ZapOff",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.48.0",
+  "version": "0.50.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 src/__tests__/datetimepicker.test.js"
   },
   "engines": {
     "node": ">=18"
@@ -51,11 +51,6 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/colixwestin/appstudio.git",
-    "directory": "packages/widget-sdk"
-  },
   "peerDependencies": {
     "react": ">=18.0.0",
     "react-native": "*",