@colixsystems/widget-sdk 0.49.0 → 0.51.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:
 
@@ -51,7 +51,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`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**.
+`v0.51.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.51.0
+
+**`datastoreTemplate` tables can ship sample `rows` (sc-2070).** Each `WidgetDatastoreTemplateTable` now takes an optional `rows` array — sample data seeded into the table at install time so the widget renders with real content instead of an empty state. Each entry is an object keyed by column `name`; only the scalar/array column types are seedable (`STRING`, `TEXT`, `NUMBER`, `FLOAT`, `BOOL`, `DATE`, `STRING_ARRAY`, `INT_ARRAY`). RELATION, FILE, USER, and USER_GROUP columns are rejected at validation time (a sample row has no way to express their ids). A `null` value skips that cell; at most 25 rows per table. The "Seed data" action and every install path seed these rows in the same transaction that creates the tables. Additive — `rows` is optional and existing templates that omit it behave exactly as before.
 
 ### What's new in 0.49.0
 
@@ -102,7 +106,7 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ### What's new in 0.42.0
 
-**RELATION columns hydrate with a display label (sc-1181).** Record reads now return `{ id, label }` for ONE_TO_ONE / ONE_TO_MANY and `[{ id, label }, ...]` for MANY_TO_MANY (empty array when no links) — `label` is the value of the column pointed at by the new optional `display_column_id` on `DatastoreSchemaColumn`, or, when unset, the first STRING/TEXT column on the target table. Widgets should render `record.<rel>.label` (or `record.<rel>.map(r => r.label).join(", ")` for M:M) directly; `.id` is still there for the foreign-key case. The cell-formatting helpers in the built-in `DataList`, `TabbedDatalist`, and `FieldValue` widgets already walk arrays and prefer `label` over `name` / `id` — author widgets that need the same can copy that pattern. `CONTRACT.version` is unchanged.
+**RELATION columns hydrate with a display label (sc-1181).** Record reads now return `{ id, label }` for ONE_TO_ONE / ONE_TO_MANY and `[{ id, label }, ...]` for MANY_TO_MANY (empty array when no links) — `label` is the value of the column pointed at by the new optional `display_column_id` on `DatastoreSchemaColumn`, or, when unset, the first STRING/TEXT column on the target table. Widgets should render `record.<rel>.label` (or `record.<rel>.map(r => r.label).join(", ")` for M:M) directly; `.id` is still there for the foreign-key case. The cell-formatting helpers in the built-in `DataList` and `FieldValue` widgets already walk arrays and prefer `label` over `name` / `id` — author widgets that need the same can copy that pattern. `CONTRACT.version` is unchanged.
 
 ### What's new in 0.41.0
 
@@ -112,6 +116,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.

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

@@ -569,8 +569,11 @@ function toDatastoreError(err) {
  * resolves to the `{ data, meta }` list envelope VERBATIM (the client no
  * longer unwraps to a bare array), so we read `res.data` (defaulting to `[]`)
  * into component state. Author column values inside each row keep whatever
- * the author named them. We re-fetch when [table, JSON.stringify(query)]
- * changes. `refetch` re-runs the same call on demand.
+ * the author named them. `query.sort` accepts `"col:desc"` or `{ field, dir }`;
+ * `query.filter` accepts a `{ col: "op:value" }` map or a `[{ column,
+ * operator, value }]` array — the client normalises both to the wire form. We
+ * re-fetch when [table, JSON.stringify(query)] changes. `refetch` re-runs the
+ * same call on demand.
  *
  * When `table` is falsy (e.g. the user hasn't bound a `tableRef` property
  * yet), the hook resolves to { data: [], loading: false, error: null,

package/dist/index.d.ts

@@ -168,6 +168,15 @@ export interface WidgetDatastoreTemplateTable {
    */
   publicGrant?: { canRead?: boolean; canWrite?: boolean; canDelete?: boolean };
   columns: WidgetDatastoreTemplateColumn[];
+  /**
+   * Optional sample rows seeded into the table at install time so the widget
+   * renders with real data instead of an empty state. Each key is a column
+   * `name`; only non-relation/file/user columns are seedable (RELATION, FILE,
+   * USER, USER_GROUP are rejected). `null` skips that cell. Max 25 rows.
+   */
+  rows?: Array<
+    Record<string, string | number | boolean | string[] | number[] | null>
+  >;
 }
 
 export interface WidgetDatastoreTemplate {