@colixsystems/widget-sdk 0.62.0 → 0.64.0

package/README.md

@@ -53,7 +53,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.62.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.64.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.64.0
+
+**`<DateTimePicker>` themes itself — legible on dark surfaces (sc-3370).** The primitive now derives its colours from the workspace theme on BOTH hosts instead of hardcoding them: the text uses `colors.onSurface`, the border uses `colors.border`, and on web the input's `color-scheme` follows the theme so the browser's built-in date UI (the `yyyy-mm-dd` edit segments and the calendar icon) stays legible on a dark surface. Previously the web input used `color: inherit` with no `color-scheme` and the native trigger set no text colour, so on a dark-themed app the field rendered dark-on-dark and unreadable — with no prop an author could set to fix it. **No prop changed**: the seven-prop contract (`value, onChange, mode, minimumDate, maximumDate, disabled, accessibilityLabel`) is unchanged, and you do NOT style the field yourself — never reach for raw CSS or `document`, which the widget linter rejects. `CONTRACT.version` → `1.43.0`. Behavioural fix, additive.
+
+### What's new in 0.63.0
+
+**New optional manifest field `rendersOwnChrome` (sc-3331).** A boolean (default `false`) that declares whether your widget renders its OWN section header — a heading (and optional subtitle), plus any primary action for its section — making it a self-contained section. Set it `true` when your widget draws its own title (from a `title`/`subtitle` prop with a real default, so the author can still retitle it in the Properties Panel), and the AppStudio app-builder will place the widget as the WHOLE section: it will NOT add a standalone heading or a duplicate action button above it, so the section is never double-titled. Leave it `false`/omitted for a content-only widget whose heading the page supplies. `CONTRACT.version` → `1.42.0`. Additive — existing manifests omit it and read `false`, so no widget needs changing.
 
 ### What's new in 0.62.0
 

package/dist/contract.cjs

@@ -823,7 +823,7 @@ const PRIMITIVES = [
   {
     name: "DateTimePicker",
     description:
-      'Cross-platform date / time / datetime picker. `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" />`. The value prop and the onChange callback both speak ISO 8601 strings (the datastore wire format) — authors never round-trip through `new Date()`. Web renders the browser\'s native `<input type="date|time|datetime-local">` directly (react-native-web has no mapping for the RN datetimepicker library); native uses @react-native-community/datetimepicker.',
+      'Cross-platform date / time / datetime picker. `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" />`. The value prop and the onChange callback both speak ISO 8601 strings (the datastore wire format) — authors never round-trip through `new Date()`. Web renders the browser\'s native `<input type="date|time|datetime-local">` directly (react-native-web has no mapping for the RN datetimepicker library); native uses @react-native-community/datetimepicker. The field themes itself from the workspace theme — text uses `colors.onSurface`, the border `colors.border`, and on web `color-scheme` follows the theme so the browser\'s built-in date UI stays legible on a dark surface; never style it with raw CSS or `document`.',
     rnComponent: "@react-native-community/datetimepicker",
     docsUrl: "https://github.com/react-native-datetimepicker/datetimepicker",
   },
@@ -971,6 +971,13 @@ const MANIFEST_SCHEMA = {
       "never auto-applies style — the widget owns placement.",
     default: {},
   },
+  rendersOwnChrome: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when the widget renders its OWN section header — a heading (and optional subtitle), plus any primary action for its section — making it a self-contained section. The AppStudio app-builder reads this when it places an already-installed widget: it lays the widget out as the WHOLE section and does NOT add a standalone heading or a duplicate action button above it, so the section is never double-titled. Set it to match what the component actually renders; leave it false (or omit) for a content-only widget whose heading the page supplies.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -1908,7 +1915,18 @@ const CONTRACT = deepFreeze({
   //    no in-code `|| "fallback"`. Backed by a host-only subpath export
   //    (`@colixsystems/widget-sdk/host` -> resolveProps); the author-facing entry
   //    is unchanged. No existing behaviour changes — minor bump.
-  version: "1.41.0",
+  // 1.42.0 (sc-3331) — new OPTIONAL manifest field `rendersOwnChrome` (boolean,
+  //    default false): declares that the widget renders its own section header,
+  //    so the app-builder places it as a whole section without stacking a
+  //    heading above it. Additive — existing manifests omit it and read false.
+  // 1.43.0 (sc-3370) — the `<DateTimePicker>` primitive now themes itself from
+  //    the workspace theme on both hosts: text uses `colors.onSurface`, the
+  //    border `colors.border`, and the web input's `color-scheme` follows the
+  //    theme so the browser's built-in date UI stays legible on a dark surface.
+  //    Previously it hardcoded `color: inherit` / an unset scheme (web) and an
+  //    uncoloured trigger (native), rendering dark-on-dark. No prop changed —
+  //    behavioural fix, additive.
+  version: "1.43.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -823,7 +823,7 @@ const PRIMITIVES = [
   {
     name: "DateTimePicker",
     description:
-      'Cross-platform date / time / datetime picker. `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" />`. The value prop and the onChange callback both speak ISO 8601 strings (the datastore wire format) — authors never round-trip through `new Date()`. Web renders the browser\'s native `<input type="date|time|datetime-local">` directly (react-native-web has no mapping for the RN datetimepicker library); native uses @react-native-community/datetimepicker.',
+      'Cross-platform date / time / datetime picker. `<DateTimePicker value={iso} onChange={iso => …} mode="date" | "time" | "datetime" />`. The value prop and the onChange callback both speak ISO 8601 strings (the datastore wire format) — authors never round-trip through `new Date()`. Web renders the browser\'s native `<input type="date|time|datetime-local">` directly (react-native-web has no mapping for the RN datetimepicker library); native uses @react-native-community/datetimepicker. The field themes itself from the workspace theme — text uses `colors.onSurface`, the border `colors.border`, and on web `color-scheme` follows the theme so the browser\'s built-in date UI stays legible on a dark surface; never style it with raw CSS or `document`.',
     rnComponent: "@react-native-community/datetimepicker",
     docsUrl: "https://github.com/react-native-datetimepicker/datetimepicker",
   },
@@ -971,6 +971,13 @@ const MANIFEST_SCHEMA = {
       "never auto-applies style — the widget owns placement.",
     default: {},
   },
+  rendersOwnChrome: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when the widget renders its OWN section header — a heading (and optional subtitle), plus any primary action for its section — making it a self-contained section. The AppStudio app-builder reads this when it places an already-installed widget: it lays the widget out as the WHOLE section and does NOT add a standalone heading or a duplicate action button above it, so the section is never double-titled. Set it to match what the component actually renders; leave it false (or omit) for a content-only widget whose heading the page supplies.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -1908,7 +1915,18 @@ const CONTRACT = deepFreeze({
   //    no in-code `|| "fallback"`. Backed by a host-only subpath export
   //    (`@colixsystems/widget-sdk/host` -> resolveProps); the author-facing entry
   //    is unchanged. No existing behaviour changes — minor bump.
-  version: "1.41.0",
+  // 1.42.0 (sc-3331) — new OPTIONAL manifest field `rendersOwnChrome` (boolean,
+  //    default false): declares that the widget renders its own section header,
+  //    so the app-builder places it as a whole section without stacking a
+  //    heading above it. Additive — existing manifests omit it and read false.
+  // 1.43.0 (sc-3370) — the `<DateTimePicker>` primitive now themes itself from
+  //    the workspace theme on both hosts: text uses `colors.onSurface`, the
+  //    border `colors.border`, and the web input's `color-scheme` follows the
+  //    theme so the browser's built-in date UI stays legible on a dark surface.
+  //    Previously it hardcoded `color: inherit` / an unset scheme (web) and an
+  //    uncoloured trigger (native), rendering dark-on-dark. No prop changed —
+  //    behavioural fix, additive.
+  version: "1.43.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/datetimepicker-format.js

@@ -1,9 +1,9 @@
-// REQ-WSDK-PLATFORM §6 — pure date/ISO helpers for the native `<DateTimePicker>`.
+// REQ-WSDK-PLATFORM §6 — pure, RN-free helpers for the `<DateTimePicker>`.
 //
-// Split out of datetimepicker.native.js so the formatting contract can be
+// Split out of the primitive so the formatting + theming 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.
+// just Date math, string shaping, and a colour-luminance test.
 
 export function parseToDate(value) {
   if (value == null || value === "") return new Date();
@@ -51,3 +51,22 @@ export function formatDisplayLabel(value, mode) {
   if (Number.isNaN(d.getTime())) return String(value);
   return `${formatToIso(d, "date")} ${formatToIso(d, "time")}`;
 }
+
+// Perceived-luminance test for a hex colour (`#rgb` or `#rrggbb`). The web
+// picker uses it to choose a matching `color-scheme` so the browser's built-in
+// date UI (edit segments + calendar icon) stays legible on a dark themed
+// surface. Anything unparseable is treated as light so a light theme is never
+// darkened.
+export function isDarkColor(hex) {
+  if (typeof hex !== "string") return false;
+  let h = hex.trim().replace(/^#/, "");
+  if (h.length === 3) {
+    h = h.split("").map((c) => c + c).join("");
+  }
+  if (h.length !== 6 || /[^0-9a-fA-F]/.test(h)) return false;
+  const r = parseInt(h.slice(0, 2), 16);
+  const g = parseInt(h.slice(2, 4), 16);
+  const b = parseInt(h.slice(4, 6), 16);
+  const luminance = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+  return luminance < 0.5;
+}

package/dist/datetimepicker.js

@@ -25,6 +25,9 @@
 //                            readers can locate the input by its label.
 
 import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { isDarkColor } from "./datetimepicker-format.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 
 const MODE_TO_INPUT_TYPE = {
   date: "date",
@@ -80,6 +83,7 @@ export function DateTimePicker({
   disabled,
   accessibilityLabel,
 }) {
+  const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
   const effectiveMode = mode === "time" || mode === "datetime" ? mode : "date";
   const inputType = MODE_TO_INPUT_TYPE[effectiveMode];
   const inputValue = _isoToInputValue(value, effectiveMode);
@@ -128,7 +132,13 @@ export function DateTimePicker({
   // 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. `cursor: pointer` signals the
-  // whole field is the click affordance (sc-1878).
+  // whole field is the click affordance (sc-1878). Colours come from the
+  // theme so the field is legible on any surface (sc-3370); `colorScheme`
+  // steers the browser's built-in date UI (edit segments + calendar icon).
+  // The scheme keys off the theme's TEXT colour (onSurface, which the host
+  // already picked to contrast the surface) rather than re-deriving dark-vs-
+  // light from the surface with a second luminance formula that could disagree
+  // with the host: light text ⇒ dark surface ⇒ dark scheme.
   const style = {
     boxSizing: "border-box",
     width: "100%",
@@ -136,11 +146,12 @@ export function DateTimePicker({
     padding: "8px 12px",
     fontSize: 16,
     fontFamily: "inherit",
-    color: "inherit",
+    color: theme.colors.onSurface,
     backgroundColor: "transparent",
+    colorScheme: isDarkColor(theme.colors.onSurface) ? "light" : "dark",
     borderWidth: 1,
     borderStyle: "solid",
-    borderColor: "rgba(0, 0, 0, 0.16)",
+    borderColor: theme.colors.border,
     borderRadius: 6,
     outline: "none",
     cursor: disabled ? "default" : "pointer",

package/dist/datetimepicker.native.js

@@ -32,6 +32,8 @@ import {
   formatToIso,
   formatDisplayLabel,
 } from "./datetimepicker-format.js";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 
 const styles = StyleSheet.create({
   trigger: {
@@ -39,7 +41,6 @@ const styles = StyleSheet.create({
     paddingVertical: 8,
     paddingHorizontal: 12,
     borderWidth: 1,
-    borderColor: "rgba(0, 0, 0, 0.16)",
     borderRadius: 6,
     justifyContent: "center",
   },
@@ -57,6 +58,7 @@ export function DateTimePicker({
   disabled,
   accessibilityLabel,
 }) {
+  const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
   const effectiveMode = mode === "time" || mode === "datetime" ? mode : "date";
   const [open, setOpen] = useState(false);
   const dateValue = useMemo(() => parseToDate(value), [value]);
@@ -89,11 +91,21 @@ export function DateTimePicker({
       accessibilityRole: "button",
       accessibilityLabel,
       accessibilityState: { disabled: !!disabled },
-      style: [styles.trigger, disabled && styles.triggerDisabled],
+      // Themed border + text so the trigger is legible on any surface (sc-3370).
+      style: [
+        styles.trigger,
+        { borderColor: theme.colors.border },
+        disabled && styles.triggerDisabled,
+      ],
     },
     React.createElement(
       Text,
-      { style: isEmpty ? styles.placeholder : styles.label },
+      {
+        style: [
+          isEmpty ? styles.placeholder : styles.label,
+          { color: theme.colors.onSurface },
+        ],
+      },
       formatDisplayLabel(value, effectiveMode),
     ),
   );

package/dist/hooks.js

@@ -91,6 +91,17 @@ export function useTheme() {
   return ctx.workspace.theme;
 }
 
+// @internal — reads the host theme WITHOUT throwing when no provider is
+// mounted (returns undefined instead), unlike useTheme() which asserts a
+// widget context. Low-level primitives (DateTimePicker) read it so they stay
+// renderable anywhere, applying their own default tokens on the undefined
+// case. Not part of the public widget hook surface — not re-exported from
+// index.js.
+export function useHostTheme() {
+  const ctx = useContext(HostWidgetContext);
+  return ctx && ctx.workspace ? ctx.workspace.theme : undefined;
+}
+
 /**
  * REQ-THEME-13 — returns the author-set per-widget style values: the object the
  * host delivers under `props.style`, keyed by the style-field names the widget
@@ -2823,16 +2834,37 @@ function toPaymentError(err) {
  *       anything yourself (no `Linking.openURL`, no `checkout_url` to
  *       handle). The mock provider auto-confirms (`status: "PAID"`, no
  *       redirect). Rejects with a `PaymentError`.
- *   getPayment(paymentId) → Promise<payment> — poll the terminal status.
- *
- * Because the web redirect reloads the app on return, confirm completion
- * from server-authoritative state (the Mollie webhook flips the charge /
- * your datastore record) — re-read your bound record on mount, or poll
- * `getPayment(id)` after the mock/native flow resolves. Requires the
- * `payments.charge:appUser` scope in the manifest's `requestedScopes`. The
- * charge settles to the workspace owner; the app user confirms the amount
- * in hosted Checkout. No card data touches the widget — never collect card
- * fields yourself.
+ *   getPayment(paymentId) → Promise<payment> — read the current status
+ *       (`PENDING` | `PAID` | `FAILED`), scoped server-side to the caller.
+ *
+ * THE PAYER IS ALWAYS A SIGNED-IN APP USER — charging requires it, and a paid
+ * widget lives on a page behind login. So read the buyer's identity from
+ * `useUser()` (`{ id, email, displayName }`) and connect the record you write
+ * to `user.id`. Do NOT re-collect the name / email `useUser()` already gives
+ * you as required inputs; pre-filling an editable field from it, or asking for
+ * genuinely new details (phone, address, notes), is fine.
+ *
+ * CONFIRM FROM SERVER STATE, NOT MEMORY — and handle success, failure, AND
+ * cancel. On web `requestPayment` triggers a full-page redirect, so the app
+ * reloads on return and any in-memory "done" flag is gone. One pattern works on
+ * both platforms:
+ *   1. On mount, read `useRouteParams()`. After the web redirect it carries
+ *      `payment` (`"success"` | `"cancel"`) and, on success, `payment_id`.
+ *      `"cancel"` → the user backed out: show a "payment cancelled" state, do
+ *      NOT treat it as paid. `"success"` + `payment_id` → poll `getPayment(id)`
+ *      until it leaves `PENDING`, then branch: `PAID` → confirm / write the
+ *      record; `FAILED` → show a failure state.
+ *   2. Also poll the `id` that `requestPayment` RESOLVES with — the mock
+ *      provider and the native in-app-browser flow return here without a reload,
+ *      so route params are absent and this branch reconciles instead.
+ * Poll a bounded number of times (e.g. every ~1.5s for up to ~30s) because the
+ * Mollie webhook may land a moment after the redirect; if it is still `PENDING`
+ * when you give up, show a "still processing" state rather than "paid".
+ *
+ * Requires the `payments.charge:appUser` scope in the manifest's
+ * `requestedScopes`. The charge settles to the workspace owner; the app user
+ * confirms the amount in hosted Checkout. No card data touches the widget —
+ * never collect card fields yourself.
  */
 export function usePayments() {
   const ctx = useWidgetContextOrThrow("usePayments");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.62.0",
+  "version": "0.64.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",