@colixsystems/widget-sdk 0.126.0 → 0.127.0

package/README.md

@@ -70,7 +70,21 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.126.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.127.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.127.0 (contract 1.99.0)
+
+**Widgets can do maths now — five pure-JS packages join the vetted import allowlist (sc-7191).** The list had 31 entries and exactly one non-UI utility (`date-fns`), so anything numeric a widget needed had to be hand-rolled in a sibling file. Two gaps in particular:
+
+- `decimal.js` — exact decimal arithmetic. The platform has payments, invoicing and VAT, and a total accumulated in IEEE-754 floats drifts from what the backend actually charged. `new Decimal(a).plus(b).toFixed(2)` does not.
+- `d3-scale` + `d3-shape` + `d3-array` — the scale, path-generator and domain maths a bespoke chart needs. `d3-shape` emits path strings you hand straight to the already-vetted `react-native-svg`'s `<Path d={…} />`, so a custom line/area/donut chart is ONE source file that renders identically in the Player and the Expo export.
+- `simple-statistics` — mean/median/quantile/regression/correlation, for summarising a datastore table without shipping a maths framework.
+
+All five are `platforms: ["web", "native"]` with no native module, so this is **full parity**, not a §8 native-only case. Each is host-shimmed in the Player and pinned in the export for the same reason `date-fns` is: an AI-agent widget is transpiled rather than bundled, so its bare import has to resolve at runtime on both hosts.
+
+`mathjs` was considered and deliberately left off — 9.4 MB unpacked with nine transitive dependencies, and a web-vetted package is bundled into the Studio.
+
+Additive: no existing entry, hook, primitive or `propertySchema` type changed shape. `CONTRACT.version` → `1.99.0`.
 
 ### What's new in 0.126.0 (contract 1.98.0)
 

package/dist/contract.cjs

@@ -2677,6 +2677,41 @@ const VETTED_IMPORTS = [
     description:
       "Device motion hardware on the Expo export: Accelerometer, Gyroscope, Magnetometer, DeviceMotion, Barometer, Pedometer and LightSensor, each read as an addListener subscription with setUpdateInterval — always remove the subscription on unmount, a sensor left running drains the battery. Expo SDK 56 ships 56.0.x. Native-only on purpose: the package's own web build derives acceleration from deviceorientation ANGLES rather than real motion, so a shake or tilt threshold tuned on one host would read differently on the other. Author it in widget.native.jsx and pair it with a widget.web.jsx reading window.DeviceMotionEvent (accelerationIncludingGravity / rotationRate), the browser API the same hardware exposes. Both hosts need a user gesture before readings start, and iOS Safari additionally needs an explicit DeviceMotionEvent.requestPermission() grant — so gate the reading behind a Pressable, never start it on mount.",
   },
+  {
+    specifier: "decimal.js",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Arbitrary-precision decimal arithmetic. Reach for it whenever a widget computes MONEY: JavaScript numbers are binary floats, so a price total, a VAT line or a discount accumulated in `+`/`*` drifts by fractions of a cent and disagrees with what the backend charged. `new Decimal(a).plus(b).toFixed(2)` does not. Pure JS with zero dependencies, identical on both platforms. Not for general maths — it is slower than a number and only earns its cost where exactness is the point.",
+  },
+  {
+    specifier: "d3-scale",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Maps data values to pixel positions — `scaleLinear`, `scaleTime`, `scaleBand`, `scaleOrdinal`, plus the `.ticks()` an axis is labelled from. The maths half of a custom chart; pair it with d3-shape for the path and react-native-svg to draw. Pure JS (its only deps are other d3 modules), so one implementation covers both platforms.",
+  },
+  {
+    specifier: "d3-shape",
+    platforms: ["web", "native"],
+    category: "drawing",
+    description:
+      "SVG path generators — `line`, `area`, `arc`, `pie`, `curve*`. Each returns a path string you hand to the vetted react-native-svg's `<Path d={…} />`, so a bespoke line/area/donut chart renders identically in the Player and the Expo export from ONE source file. Pure JS.",
+  },
+  {
+    specifier: "d3-array",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Array statistics and binning — `extent`, `min`/`max`, `bisect`, `bin`, `group`, `rollup`. Chiefly how you compute the domain d3-scale expects from a dataset. Pure JS.",
+  },
+  {
+    specifier: "simple-statistics",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Descriptive statistics and simple models — mean/median/mode, standard deviation, quantiles, linear regression, correlation. Small and pure JS, so a widget can summarise a datastore table without shipping a maths framework. For exact decimal arithmetic (money) use decimal.js instead: this operates on JS numbers.",
+  },
 ];
 
 // sc-1064: CORE React infrastructure specifiers the host RESOLVES at runtime
@@ -3721,7 +3756,19 @@ const CONTRACT = deepFreeze({
   //    capability is the direction §8 forbids. The slice is OPTIONAL, so a host
   //    that brokers nothing degrades the hook to supported:false rather than
   //    throwing. Minor bump on the pre-1.0 channel.
-  version: "1.98.0",
+  // 1.99.0: additive (sc-7191) — the vetted import allowlist gains five PURE-JS
+  //    packages, the first non-UI maths available to a widget: `decimal.js`
+  //    (exact decimal arithmetic — the platform has payments, invoicing and
+  //    VAT, and float money math disagrees with what the backend charged),
+  //    `d3-scale` + `d3-shape` + `d3-array` (the scale/path/domain maths a
+  //    bespoke chart needs, drawn through the already-vetted react-native-svg),
+  //    and `simple-statistics`. All five are `["web", "native"]` with no native
+  //    module, so this is full parity, not a §8 native-only case. Each is
+  //    host-shimmed in widgetLoader.js and pinned in the export for the same
+  //    reason date-fns is: an AI-agent widget is transpiled, never bundled, so
+  //    its bare import must resolve at runtime on both hosts. No existing entry
+  //    changed shape — minor bump on the pre-1.0 channel.
+  version: "1.99.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2677,6 +2677,41 @@ const VETTED_IMPORTS = [
     description:
       "Device motion hardware on the Expo export: Accelerometer, Gyroscope, Magnetometer, DeviceMotion, Barometer, Pedometer and LightSensor, each read as an addListener subscription with setUpdateInterval — always remove the subscription on unmount, a sensor left running drains the battery. Expo SDK 56 ships 56.0.x. Native-only on purpose: the package's own web build derives acceleration from deviceorientation ANGLES rather than real motion, so a shake or tilt threshold tuned on one host would read differently on the other. Author it in widget.native.jsx and pair it with a widget.web.jsx reading window.DeviceMotionEvent (accelerationIncludingGravity / rotationRate), the browser API the same hardware exposes. Both hosts need a user gesture before readings start, and iOS Safari additionally needs an explicit DeviceMotionEvent.requestPermission() grant — so gate the reading behind a Pressable, never start it on mount.",
   },
+  {
+    specifier: "decimal.js",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Arbitrary-precision decimal arithmetic. Reach for it whenever a widget computes MONEY: JavaScript numbers are binary floats, so a price total, a VAT line or a discount accumulated in `+`/`*` drifts by fractions of a cent and disagrees with what the backend charged. `new Decimal(a).plus(b).toFixed(2)` does not. Pure JS with zero dependencies, identical on both platforms. Not for general maths — it is slower than a number and only earns its cost where exactness is the point.",
+  },
+  {
+    specifier: "d3-scale",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Maps data values to pixel positions — `scaleLinear`, `scaleTime`, `scaleBand`, `scaleOrdinal`, plus the `.ticks()` an axis is labelled from. The maths half of a custom chart; pair it with d3-shape for the path and react-native-svg to draw. Pure JS (its only deps are other d3 modules), so one implementation covers both platforms.",
+  },
+  {
+    specifier: "d3-shape",
+    platforms: ["web", "native"],
+    category: "drawing",
+    description:
+      "SVG path generators — `line`, `area`, `arc`, `pie`, `curve*`. Each returns a path string you hand to the vetted react-native-svg's `<Path d={…} />`, so a bespoke line/area/donut chart renders identically in the Player and the Expo export from ONE source file. Pure JS.",
+  },
+  {
+    specifier: "d3-array",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Array statistics and binning — `extent`, `min`/`max`, `bisect`, `bin`, `group`, `rollup`. Chiefly how you compute the domain d3-scale expects from a dataset. Pure JS.",
+  },
+  {
+    specifier: "simple-statistics",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Descriptive statistics and simple models — mean/median/mode, standard deviation, quantiles, linear regression, correlation. Small and pure JS, so a widget can summarise a datastore table without shipping a maths framework. For exact decimal arithmetic (money) use decimal.js instead: this operates on JS numbers.",
+  },
 ];
 
 // sc-1064: CORE React infrastructure specifiers the host RESOLVES at runtime
@@ -3721,7 +3756,19 @@ const CONTRACT = deepFreeze({
   //    capability is the direction §8 forbids. The slice is OPTIONAL, so a host
   //    that brokers nothing degrades the hook to supported:false rather than
   //    throwing. Minor bump on the pre-1.0 channel.
-  version: "1.98.0",
+  // 1.99.0: additive (sc-7191) — the vetted import allowlist gains five PURE-JS
+  //    packages, the first non-UI maths available to a widget: `decimal.js`
+  //    (exact decimal arithmetic — the platform has payments, invoicing and
+  //    VAT, and float money math disagrees with what the backend charged),
+  //    `d3-scale` + `d3-shape` + `d3-array` (the scale/path/domain maths a
+  //    bespoke chart needs, drawn through the already-vetted react-native-svg),
+  //    and `simple-statistics`. All five are `["web", "native"]` with no native
+  //    module, so this is full parity, not a §8 native-only case. Each is
+  //    host-shimmed in widgetLoader.js and pinned in the export for the same
+  //    reason date-fns is: an AI-agent widget is transpiled, never bundled, so
+  //    its bare import must resolve at runtime on both hosts. No existing entry
+  //    changed shape — minor bump on the pre-1.0 channel.
+  version: "1.99.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/dev-shims.js

@@ -117,6 +117,14 @@ const HOST_EXTERNAL_SPECIFIERS = [
   // bundle shares one RN-web (StyleSheet/context) instead of inlining a second
   // copy. On native, Metro resolves the real react-native in the export.
   "react-native",
+  // sc-7191: the vetted pure-JS maths set. Externalised for the same reason as
+  // date-fns — an AI-agent widget is transpiled, never bundled, so the host
+  // must resolve the bare import at runtime.
+  "decimal.js",
+  "d3-scale",
+  "d3-shape",
+  "d3-array",
+  "simple-statistics",
 ];
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.126.0",
+  "version": "0.127.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/dev-shims.js

@@ -117,6 +117,14 @@ const HOST_EXTERNAL_SPECIFIERS = [
   // bundle shares one RN-web (StyleSheet/context) instead of inlining a second
   // copy. On native, Metro resolves the real react-native in the export.
   "react-native",
+  // sc-7191: the vetted pure-JS maths set. Externalised for the same reason as
+  // date-fns — an AI-agent widget is transpiled, never bundled, so the host
+  // must resolve the bare import at runtime.
+  "decimal.js",
+  "d3-scale",
+  "d3-shape",
+  "d3-array",
+  "simple-statistics",
 ];
 
 /**