@colixsystems/widget-sdk 0.266.1 → 0.267.1

package/README.md

@@ -50,7 +50,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useTranslate()` | `{ translate, translating, error, language, available }` | `ctx.i18n.translate` — no scope. Machine-translates **user-generated content** (record text, file names, API payloads) into the app user's language; `useI18n().t()` is still the answer for your own copy. `translate(str)` → `Promise<string>`, `translate(str[])` → `Promise<string[]>` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. |
 | **CORE** | `useLinkPreview(url)` | `{ preview, loading, error, available }` — `preview` is `{ url, title, description, site_name, image_url } \| null` | `ctx.linkPreviews.get` — no scope. A link's title, description, site name and image, fetched by the platform (the device never contacts the linked site). A page with nothing to show resolves with null fields, not an error — render the plain link. A non-http(s) `url` makes no request. Memoized for up to an hour across widgets; concurrent calls for one URL share a request. `error` is a `LinkPreviewError` (`VALIDATION` \| `AUTH_REQUIRED` \| `RATE_LIMITED` \| `NETWORK` \| `INTERNAL`). `available` is false on a host with no link-preview client |
 | **CORE** | `useStableQuery(buildQuery)` | `T \| undefined` (whatever `buildQuery()` returns) | No context slice, no scope. Keeps `buildQuery()`'s result at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so `useDatastoreQuery(tableId, useStableQuery(() => ({...})))` replaces a hand-rolled `useMemo` with an easy-to-get-wrong deps array. Never throws: a `buildQuery` that itself throws degrades to a stable `undefined`; a result that can't be diffed (e.g. circular) degrades to "always a new reference". |
-| **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options)` (optional: options) | `{ data, total, loading, fetching, error, refetch }` — `loading` only until the first result for the table; a changed query / refetch keeps `data` while `fetching`; `total` is the envelope's `meta.total` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
+| **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options)` (optional: options) | `{ data, total, loading, fetching, error, refetch }` — `loading` only until the first result for the table; a changed query / refetch keeps `data` while `fetching`; `total` is the envelope's `meta.total` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*`. `options` is `{ filter, filterMode, q, sort, limit, offset, includeCapabilities }`, applied on the server: see *Querying records*. |
 | **DATASTORE** | `useDatastoreFigure(table, { aggregate, column, filter })` (optional: options) | `{ value, text, truncated, loading, fetching, error, refetch }` | `records(table).list` (a count reads the envelope total; a sum or average up to 1000 rows) — `datastore.read:*`. One count / sum / average for a `<Stat>`, computed exactly as the built-in Stat widget does. |
 | **DATASTORE** | `useDatastoreRecord(table, id, options)` (optional: options) | `{ data, loading, fetching, error, refetch }` — a refetch of the same record keeps `data` while `fetching`; `{ includeCapabilities: true }` adds `data._capabilities` | `records(table).get` — `datastore.read:<table>` |
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
@@ -86,7 +86,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.266.1` — 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.267.1` — 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.267.1 (contract 1.217.0)
+
+**The record query options are documented where an author reads them.** A new *Querying records* section lists everything `useDatastoreQuery` sends to the server — `filter` and its operators, `filterMode`, `q`, `sort`, `limit` (50 by default, at most 1000) and `offset` — with `total` for paging and a searchable, paged list to start from. The `Query` type now declares `q`, `offset`, `filterMode` and both filter and sort shapes, and marks `cursor`, which the datastore never read, deprecated. No runtime change.
+
+### What's new in 0.267.0 (contract 1.217.0)
+
+**Every text field can raise the right keyboard.** The `TextInput` primitive (and `<TextField>`, which passes every `TextInput` prop through) now documents `keyboardType` — `"email-address"`, `"phone-pad"`, `"url"`, `"number-pad"`, `"decimal-pad"` — plus `autoCapitalize`, `autoCorrect`, `autoComplete` and `secureTextEntry`. They already worked on both hosts (react-native-web turns `keyboardType` into the input's `type` / `inputMode`); now the contract and the AI widget agent say to set them. A `useDatastoreSchema` column's `text_format` (`"EMAIL"` | `"PHONE"` | `"URL"` | a JSON format | `null`) is typed on `DatastoreSchemaColumn`, so a typed widget can pick the keyboard from it.
 
 ### What's new in 0.266.1 (contract 1.216.0)
 
@@ -3539,6 +3547,64 @@ export default function OpenTasks({ tableId, titleField, statusField }) {
 
 `useCanWrite(tableId)` answers "may I create a row here". It says nothing about changing an EXISTING row: gate a list's Edit / Delete on each row's `_capabilities` (read with `includeCapabilities: true`, see *What's new in 0.174.0*), and a single-record page on `useCanWrite(tableId, { recordId })` or `useDatastoreRecord(…, { includeCapabilities: true })`. Never call `useCanWrite` with a `recordId` per list row — that is one request per row. Either answer is a FLOOR, not the whole rule: a widget whose own logic is more specific ("only the assignee may edit this row") still hand-checks that in addition (`user.id === record[assigneeField]`).
 
+## Querying records
+
+`useDatastoreQuery(tableId, query)` hands `query` to the datastore, which filters, searches, sorts and pages the table before a row reaches the widget. Every key is optional. Build the object with `useStableQuery` so it does not refetch every render.
+
+| Option | What the server does with it |
+| --- | --- |
+| `filter` | Keeps the rows that match. A map `{ column: "op:value" }` (an array of expressions puts a range on one column), or an array `[{ column, operator, value }]`. |
+| `filterMode` | `"and"` (the default) keeps rows matching every condition; `"or"` keeps rows matching any. |
+| `q` | Free-text search: a case-insensitive substring match across every text column of the table (encrypted columns excepted). |
+| `sort` | `{ field, dir }` with `dir` `"asc"` or `"desc"`, or the string `"field:desc"`. One column; `created_at` and `updated_at` work too. |
+| `limit` | Rows per page: 50 when left out, at most 1000. |
+| `offset` | Rows to skip, for the next page. |
+| `includeCapabilities` | `true` stamps each row with `_capabilities`, what the signed-in user may do to it. |
+
+The filter operators are `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains` (a case-insensitive substring), `empty` and `nempty` (no value). In the array form a condition may carry `valueMode`: `"currentUser"` or `"currentUserGroup"` with `eq` or `neq` matches the signed-in user (or their groups) on a USER or USER_GROUP column, and `"relativeDate"` with an ordering operator reads `value` as "that many days ago".
+
+The result's `total` is how many rows match in all, not just this page: show "12 of 312" and page with `offset`. For a count, a sum or an average, use `useDatastoreFigure(tableId, { aggregate, column, filter })` instead of reading rows.
+
+**Narrow on the server, never over a fetched batch.** A widget that fetches `limit: 1000` and then filters or searches the rows in JavaScript only ever sees the first 1000; once the table grows past that, it misses rows without saying so. Send the search box's text as `q`, a chip's condition as `filter`, and page with `offset`. The checker warns about the batch pattern.
+
+```js
+import { useEffect, useState } from "react";
+import { Pressable, Text, TextInput, View, useDatastoreQuery, useStableQuery } from "@colixsystems/widget-sdk";
+
+const PAGE = 50;
+
+export default function ContactList({ tableId }) {
+  const [draft, setDraft] = useState("");
+  const [search, setSearch] = useState("");
+  const [status, setStatus] = useState("");
+  const [page, setPage] = useState(0);
+  useEffect(() => {
+    const wait = setTimeout(() => { setSearch(draft.trim()); setPage(0); }, 250);
+    return () => clearTimeout(wait);
+  }, [draft]);
+  const query = useStableQuery(() => ({
+    q: search,
+    filter: status ? { status: `eq:${status}` } : undefined,
+    sort: { field: "last_contacted", dir: "desc" },
+    limit: PAGE,
+    offset: page * PAGE,
+  }));
+  const { data, total, loading } = useDatastoreQuery(tableId, query);
+  const pick = (next) => { setStatus(next); setPage(0); };
+  return (
+    <View>
+      <TextInput value={draft} onChangeText={setDraft} placeholder="Search" />
+      <Pressable onPress={() => pick(status === "Won" ? "" : "Won")}><Text>Won</Text></Pressable>
+      {loading ? <Text>Loading…</Text> : data.map((row) => <Text key={row.id}>{row.name}</Text>)}
+      <Text>{total ?? 0} contacts</Text>
+      {(page + 1) * PAGE < (total ?? 0) ? (
+        <Pressable onPress={() => setPage(page + 1)}><Text>Next page</Text></Pressable>
+      ) : null}
+    </View>
+  );
+}
+```
+
 ## Cross-platform widgets (single-file vs split)
 
 Every widget runs in **both** the web Player and the exported native (Expo) app.

package/dist/contract.cjs

@@ -2028,13 +2028,16 @@ const HOOKS = [
       "widget can resolve a stored columnId to the column's name / dataType / " +
       "relation target at runtime (e.g. a form that renders inputs by column " +
       "type). Returns { schema, loading, error, refetch } where schema is " +
-      "{ id, name, columns: [{ id, name, dataType, required, relationType, " +
-      "targetTableId, isIdentification }] } (null until loaded). Reads only the " +
+      "{ id, name, columns: [{ id, name, data_type, required, relation_type, " +
+      "target_table_id, is_identification, text_format }] } (null until " +
+      "loaded; snake_case as the server sends it). `text_format` is " +
+      "\"EMAIL\" | \"PHONE\" | \"URL\" (or a JSON format, or null) and names the " +
+      "keyboard a field for that column should raise. Reads only the " +
       "structure, never row data; gated by the same datastore.read ACL as " +
       "record reads, so a public-grant table resolves for anonymous visitors.",
     returnShape: {
       schema:
-        "{ id, name, columns: [{ id, name, dataType, required, relationType, targetTableId, isIdentification }] } | null",
+        "{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification, text_format }] } | null",
       loading: "boolean",
       error: "DatastoreError | null",
       refetch: "() => Promise<void>",
@@ -3248,7 +3251,7 @@ const PRIMITIVES = [
   {
     name: "TextInput",
     description:
-      "Single-line or multi-line text field. Controlled — pass `value` + `onChangeText`. Set `multiline` for a textarea-style field (`numberOfLines` controls visible rows). See https://reactnative.dev/docs/textinput.",
+      "Single-line or multi-line text field. Controlled — pass `value` + `onChangeText`. Set `multiline` for a textarea-style field (`numberOfLines` controls visible rows). Pick the on-screen keyboard from what the field holds — the default alphabetic keyboard is wrong for most structured values: `keyboardType=\"email-address\"` for an email, `\"phone-pad\"` for a phone number, `\"url\"` for a link, `\"number-pad\"` for whole digits (a card or code), `\"decimal-pad\"` for an amount. For an email, link, username or code also pass `autoCapitalize=\"none\"` and `autoCorrect={false}`, so the keyboard never rewrites the value; `autoComplete` (\"email\", \"tel\", \"name\", \"one-time-code\") lets the device offer a saved value, and `secureTextEntry` masks a password. The same props reach the web: react-native-web turns `keyboardType` into the input's `type` / `inputMode`. A column's declared format (`text_format` on a `useDatastoreSchema` column: \"EMAIL\" | \"PHONE\" | \"URL\") names the keyboard for a field bound to it. See https://reactnative.dev/docs/textinput.",
     rnComponent: "TextInput",
     docsUrl: "https://reactnative.dev/docs/textinput",
   },
@@ -3607,7 +3610,7 @@ const PRIMITIVES = [
   {
     name: "TextField",
     description:
-      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field, or around the field and its icons. An icon goes INSIDE the field, never beside it: `leadingIcon` / `trailingIcon` take a lucide name (`<TextField trailingIcon="map-pin" … />`), and `onTrailingPress` with a `trailingAccessibilityLabel` makes the trailing one a button (a clear control, "use my location"). Never wrap a field in a bordered row of your own to put an icon or a button beside it: the field draws its own border, so that shows a box inside a box. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
+      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works (set `keyboardType` from what the field holds: `"email-address"`, `"phone-pad"`, `"url"`, `"number-pad"`, `"decimal-pad"`), and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field, or around the field and its icons. An icon goes INSIDE the field, never beside it: `leadingIcon` / `trailingIcon` take a lucide name (`<TextField trailingIcon="map-pin" … />`), and `onTrailingPress` with a `trailingAccessibilityLabel` makes the trailing one a button (a clear control, "use my location"). Never wrap a field in a bordered row of your own to put an icon or a button beside it: the field draws its own border, so that shows a box inside a box. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -6466,7 +6469,10 @@ const CONTRACT = deepFreeze({
   //    `useUsers().invite` takes `send_invitation` (false stores the invite
   //    unsent), invite rows carry `sent_at`, `not_sent` is a status, and
   //    `useInvites().resend` performs the first send.
-  version: "1.216.0",
+  // 1.217.0: additive (sc-4747) — `TextInput` documents `keyboardType`,
+  //    `autoCapitalize`, `autoCorrect`, `autoComplete`, `secureTextEntry`;
+  //    `useDatastoreSchema` columns document `text_format` (snake_case wire).
+  version: "1.217.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2025,13 +2025,16 @@ const HOOKS = [
       "widget can resolve a stored columnId to the column's name / dataType / " +
       "relation target at runtime (e.g. a form that renders inputs by column " +
       "type). Returns { schema, loading, error, refetch } where schema is " +
-      "{ id, name, columns: [{ id, name, dataType, required, relationType, " +
-      "targetTableId, isIdentification }] } (null until loaded). Reads only the " +
+      "{ id, name, columns: [{ id, name, data_type, required, relation_type, " +
+      "target_table_id, is_identification, text_format }] } (null until " +
+      "loaded; snake_case as the server sends it). `text_format` is " +
+      "\"EMAIL\" | \"PHONE\" | \"URL\" (or a JSON format, or null) and names the " +
+      "keyboard a field for that column should raise. Reads only the " +
       "structure, never row data; gated by the same datastore.read ACL as " +
       "record reads, so a public-grant table resolves for anonymous visitors.",
     returnShape: {
       schema:
-        "{ id, name, columns: [{ id, name, dataType, required, relationType, targetTableId, isIdentification }] } | null",
+        "{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification, text_format }] } | null",
       loading: "boolean",
       error: "DatastoreError | null",
       refetch: "() => Promise<void>",
@@ -3245,7 +3248,7 @@ const PRIMITIVES = [
   {
     name: "TextInput",
     description:
-      "Single-line or multi-line text field. Controlled — pass `value` + `onChangeText`. Set `multiline` for a textarea-style field (`numberOfLines` controls visible rows). See https://reactnative.dev/docs/textinput.",
+      "Single-line or multi-line text field. Controlled — pass `value` + `onChangeText`. Set `multiline` for a textarea-style field (`numberOfLines` controls visible rows). Pick the on-screen keyboard from what the field holds — the default alphabetic keyboard is wrong for most structured values: `keyboardType=\"email-address\"` for an email, `\"phone-pad\"` for a phone number, `\"url\"` for a link, `\"number-pad\"` for whole digits (a card or code), `\"decimal-pad\"` for an amount. For an email, link, username or code also pass `autoCapitalize=\"none\"` and `autoCorrect={false}`, so the keyboard never rewrites the value; `autoComplete` (\"email\", \"tel\", \"name\", \"one-time-code\") lets the device offer a saved value, and `secureTextEntry` masks a password. The same props reach the web: react-native-web turns `keyboardType` into the input's `type` / `inputMode`. A column's declared format (`text_format` on a `useDatastoreSchema` column: \"EMAIL\" | \"PHONE\" | \"URL\") names the keyboard for a field bound to it. See https://reactnative.dev/docs/textinput.",
     rnComponent: "TextInput",
     docsUrl: "https://reactnative.dev/docs/textinput",
   },
@@ -3604,7 +3607,7 @@ const PRIMITIVES = [
   {
     name: "TextField",
     description:
-      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field, or around the field and its icons. An icon goes INSIDE the field, never beside it: `leadingIcon` / `trailingIcon` take a lucide name (`<TextField trailingIcon="map-pin" … />`), and `onTrailingPress` with a `trailingAccessibilityLabel` makes the trailing one a button (a clear control, "use my location"). Never wrap a field in a bordered row of your own to put an icon or a button beside it: the field draws its own border, so that shows a box inside a box. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
+      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works (set `keyboardType` from what the field holds: `"email-address"`, `"phone-pad"`, `"url"`, `"number-pad"`, `"decimal-pad"`), and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field, or around the field and its icons. An icon goes INSIDE the field, never beside it: `leadingIcon` / `trailingIcon` take a lucide name (`<TextField trailingIcon="map-pin" … />`), and `onTrailingPress` with a `trailingAccessibilityLabel` makes the trailing one a button (a clear control, "use my location"). Never wrap a field in a bordered row of your own to put an icon or a button beside it: the field draws its own border, so that shows a box inside a box. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -6463,7 +6466,10 @@ const CONTRACT = deepFreeze({
   //    `useUsers().invite` takes `send_invitation` (false stores the invite
   //    unsent), invite rows carry `sent_at`, `not_sent` is a status, and
   //    `useInvites().resend` performs the first send.
-  version: "1.216.0",
+  // 1.217.0: additive (sc-4747) — `TextInput` documents `keyboardType`,
+  //    `autoCapitalize`, `autoCorrect`, `autoComplete`, `secureTextEntry`;
+  //    `useDatastoreSchema` columns document `text_format` (snake_case wire).
+  version: "1.217.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -3165,9 +3165,9 @@ export function useDatastoreRecord(table, recordId, options) {
 
 /**
  * Stateful table-schema resolver hook. Returns { schema, loading, error,
- * refetch } where `schema` is `{ id, name, columns: [{ id, name, dataType,
- * required, relationType, targetTableId, isIdentification }] }` (`null` until
- * loaded).
+ * refetch } where `schema` is `{ id, name, columns: [{ id, name, data_type,
+ * required, relation_type, target_table_id, is_identification, text_format }] }`
+ * (`null` until loaded) — the server's snake_case, verbatim.
  *
  * The host's datastore client exposes `schema(table)` which resolves to the
  * table's structural metadata — columns and their types, NOT row data. Use it

package/dist/index.d.ts

@@ -1074,10 +1074,23 @@ export function hasCornerRadius(
   radius: ResolvedCornerRadius | null | undefined,
 ): boolean;
 
+/** A record query the datastore applies on the server; see the README's "Querying records". */
 export interface Query {
-  filter?: Record<string, unknown>;
-  sort?: Array<{ field: string; dir: "asc" | "desc" }>;
+  /** `{ column: "op:value" }` (an array of expressions for a range), or `[{ column, operator, value, valueMode }]`. */
+  filter?:
+    | Record<string, string | string[]>
+    | Array<{ column: string; operator?: string; value?: unknown; valueMode?: string }>;
+  /** `"and"` (the default) keeps rows matching every condition, `"or"` rows matching any. */
+  filterMode?: "and" | "or";
+  /** A case-insensitive substring search across the table's text columns. */
+  q?: string;
+  /** `{ field, dir }` or `"field:desc"`; one column, so an array uses its first entry. */
+  sort?: string | { field: string; dir?: "asc" | "desc" } | Array<{ field: string; dir?: "asc" | "desc" }>;
+  /** Rows per page: 50 when omitted, at most 1000. */
   limit?: number;
+  /** Rows to skip, for the next page. */
+  offset?: number;
+  /** @deprecated The datastore ignores it; page with `offset`. */
   cursor?: string;
   /**
    * Stamp each row with `_capabilities` — what the signed-in user may do to
@@ -1667,6 +1680,19 @@ export interface DatastoreSchemaColumn {
   copy_via_column_id?: string | null;
   /** Set on a copy the server keeps: the related table's column it copies. */
   copy_of_column_id?: string | null;
+  /**
+   * STRING / TEXT columns only — the value's declared format. EMAIL, PHONE and
+   * URL name the keyboard a field for this column should raise
+   * (`keyboardType` "email-address" / "phone-pad" / "url").
+   */
+  text_format?:
+    | "EMAIL"
+    | "PHONE"
+    | "URL"
+    | "JSON_ARRAY"
+    | "JSON_OBJECT"
+    | "JSON_VALUE"
+    | null;
 }
 
 export interface DatastoreSchema {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.266.1",
+  "version": "0.267.1",
   "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/contract.js

@@ -2025,13 +2025,16 @@ const HOOKS = [
       "widget can resolve a stored columnId to the column's name / dataType / " +
       "relation target at runtime (e.g. a form that renders inputs by column " +
       "type). Returns { schema, loading, error, refetch } where schema is " +
-      "{ id, name, columns: [{ id, name, dataType, required, relationType, " +
-      "targetTableId, isIdentification }] } (null until loaded). Reads only the " +
+      "{ id, name, columns: [{ id, name, data_type, required, relation_type, " +
+      "target_table_id, is_identification, text_format }] } (null until " +
+      "loaded; snake_case as the server sends it). `text_format` is " +
+      "\"EMAIL\" | \"PHONE\" | \"URL\" (or a JSON format, or null) and names the " +
+      "keyboard a field for that column should raise. Reads only the " +
       "structure, never row data; gated by the same datastore.read ACL as " +
       "record reads, so a public-grant table resolves for anonymous visitors.",
     returnShape: {
       schema:
-        "{ id, name, columns: [{ id, name, dataType, required, relationType, targetTableId, isIdentification }] } | null",
+        "{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification, text_format }] } | null",
       loading: "boolean",
       error: "DatastoreError | null",
       refetch: "() => Promise<void>",
@@ -3245,7 +3248,7 @@ const PRIMITIVES = [
   {
     name: "TextInput",
     description:
-      "Single-line or multi-line text field. Controlled — pass `value` + `onChangeText`. Set `multiline` for a textarea-style field (`numberOfLines` controls visible rows). See https://reactnative.dev/docs/textinput.",
+      "Single-line or multi-line text field. Controlled — pass `value` + `onChangeText`. Set `multiline` for a textarea-style field (`numberOfLines` controls visible rows). Pick the on-screen keyboard from what the field holds — the default alphabetic keyboard is wrong for most structured values: `keyboardType=\"email-address\"` for an email, `\"phone-pad\"` for a phone number, `\"url\"` for a link, `\"number-pad\"` for whole digits (a card or code), `\"decimal-pad\"` for an amount. For an email, link, username or code also pass `autoCapitalize=\"none\"` and `autoCorrect={false}`, so the keyboard never rewrites the value; `autoComplete` (\"email\", \"tel\", \"name\", \"one-time-code\") lets the device offer a saved value, and `secureTextEntry` masks a password. The same props reach the web: react-native-web turns `keyboardType` into the input's `type` / `inputMode`. A column's declared format (`text_format` on a `useDatastoreSchema` column: \"EMAIL\" | \"PHONE\" | \"URL\") names the keyboard for a field bound to it. See https://reactnative.dev/docs/textinput.",
     rnComponent: "TextInput",
     docsUrl: "https://reactnative.dev/docs/textinput",
   },
@@ -3604,7 +3607,7 @@ const PRIMITIVES = [
   {
     name: "TextField",
     description:
-      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field, or around the field and its icons. An icon goes INSIDE the field, never beside it: `leadingIcon` / `trailingIcon` take a lucide name (`<TextField trailingIcon="map-pin" … />`), and `onTrailingPress` with a `trailingAccessibilityLabel` makes the trailing one a button (a clear control, "use my location"). Never wrap a field in a bordered row of your own to put an icon or a button beside it: the field draws its own border, so that shows a box inside a box. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
+      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works (set `keyboardType` from what the field holds: `"email-address"`, `"phone-pad"`, `"url"`, `"number-pad"`, `"decimal-pad"`), and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field, or around the field and its icons. An icon goes INSIDE the field, never beside it: `leadingIcon` / `trailingIcon` take a lucide name (`<TextField trailingIcon="map-pin" … />`), and `onTrailingPress` with a `trailingAccessibilityLabel` makes the trailing one a button (a clear control, "use my location"). Never wrap a field in a bordered row of your own to put an icon or a button beside it: the field draws its own border, so that shows a box inside a box. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -6463,7 +6466,10 @@ const CONTRACT = deepFreeze({
   //    `useUsers().invite` takes `send_invitation` (false stores the invite
   //    unsent), invite rows carry `sent_at`, `not_sent` is a status, and
   //    `useInvites().resend` performs the first send.
-  version: "1.216.0",
+  // 1.217.0: additive (sc-4747) — `TextInput` documents `keyboardType`,
+  //    `autoCapitalize`, `autoCorrect`, `autoComplete`, `secureTextEntry`;
+  //    `useDatastoreSchema` columns document `text_format` (snake_case wire).
+  version: "1.217.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,