@colixsystems/widget-sdk 0.136.0 → 0.138.0

package/README.md

@@ -46,7 +46,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
 | **DATASTORE** | `useBoundColumns(tableId, shape, props)` | `{ columns, resolved, missing, loading, error }` | `schema(tableId)` (built on `useDatastoreSchema`) — `datastore.read:<table>`. Resolves author-bound column NAMES from `props` by exact name → case-insensitive name → first unclaimed column matching `shape[key].dataType`, so a column an author renamed after install still resolves instead of `record[props.titleField]` reading `undefined`. `columns` holds the resolved NAME (`record[columns.titleField]`); `resolved` holds the full `Column`; `missing` lists non-`optional` keys that never resolved. Falsy `tableId` collapses to `{ columns: {}, resolved: {}, missing: Object.keys(shape), loading: false, error: null }`. |
 | **DATASTORE** | `useInterpretDraft(tableId)` | `{ interpret, interpreting, error, result, available }` | `interpret(tableId, body)` — `datastore.read:<table>`. Turns ONE sentence a user typed ("walk at 11 am tomorrow") into DRAFT column values so a form can prefill itself. IMPERATIVE: call `interpret(text, { fields?, timeZone? })` from an event handler, never on mount. It DRAFTS and writes nothing — show the values for review, then submit through `useDatastoreMutation().create`. Resolves to `{ values, unresolved }`; `values` is keyed by column NAME (the shape `create()` takes) and `unresolved` names the fields the sentence did not state. Only text / number / boolean / date / datetime / array columns are drafted — `FILE`, `RELATION`, `USER` and `USER_GROUP` carry ids and are never guessed. Fails closed to an empty draft. **Every call spends the workspace's AI credits** and is rate-limited per actor, so call it once per user action (never on mount or in a render loop); once the workspace runs out the call is refused with a generic 429 — an app user is deliberately **not** told the workspace's billing state, since they have never heard of an AI credit and cannot buy one. Never surface a raw error to the person filling the form: say drafting is unavailable and keep every field editable by hand. `available` is false where the host brokers no interpreter. |
-| **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*` |
+| **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*`. **To CLEAR a cell, pass it empty** — `update(id, { when: null })` (also `""` or `[]`) empties that cell and it reads back as `null` (`[]` on an array column). There is no separate clear call, so never write a sentinel such as `0` or a placeholder date to mean "no value". `false` and `0` are values, not clears, and a REQUIRED column cannot be cleared. |
 | **DATASTORE** | `useDatastoreSubscription(table, handlers, options)` (optional: options) | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
 | **DATASTORE** | `useCanWrite(tableId, options)` (optional: options) | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "may this caller write", reading the same table-ACL answer the write endpoint enforces — so a table granting Create to Everyone answers `true` for a logged-out visitor, and this hook alone is the right gate for a widget meant to work without signing in. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. |
@@ -70,7 +70,38 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.136.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.137.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.138.0 (contract 1.107.0)
+
+**Every file upload from the Expo export works again.** Expo's `fetch` implements the WEB FormData spec, so a part must be a string or a Blob — but `useCamera`, `useImageEditor` and `<FilePicker>` all handed back React Native's legacy `{ uri, name, type }` triple, which it rejects with `Unsupported FormDataPart implementation` before a byte leaves the device. Web was unaffected because a browser `File` **is** a Blob, so it only ever reproduced on device. All three now hand back expo-file-system's `File`, carrying the same `uri` / `name` / `type` / `size` — so no widget needs a change.
+
+**`useFilestoreUpload` keeps the filename, and `fileName` works on both hosts.** A Blob appended with no filename is stored as `blob`. The name travels as `append()`'s third argument for a real Blob, and is set ON the part otherwise — expo-file-system's `File` is **not** `instanceof Blob` at runtime (`implements Blob` is TypeScript-only), and Expo reads the name off the part. `upload(file, { fileName })` overrides it. The native producers set `type` the same way, because the `File` derives it from the cache URI and leaves it empty when that URI has no extension.
+
+### What's new in 0.137.0 (contract 1.106.0)
+
+**A `datastoreTemplate` column marked `encrypted` is now actually encrypted in the workspace that installs you (sc-7557).** The field was documented nowhere and honoured nowhere: install built its column rows one way, the republish/upgrade migration built them another way, and neither carried the flag — so a column you declared confidential was created as an ordinary plaintext column and nothing told you or your installer. Both paths now share one projection, so the flag lands on install and on upgrade alike.
+
+```js
+datastoreTemplate: {
+  tables: [
+    {
+      suffix: "Patients",
+      columns: [
+        { name: "Name", dataType: "STRING", required: true },
+        { name: "Ssn", dataType: "STRING", required: true, encrypted: true },
+      ],
+      rows: [{ Name: "Ada Lovelace", Ssn: "600101-1234" }],
+    },
+  ],
+}
+```
+
+- **Your widget code does not change.** It reads and writes plaintext through `useDatastoreQuery` / `useDatastoreMutation` exactly as it does for any other column — the platform encrypts on write (AES-256-GCM under a per-workspace subkey) and decrypts for end users.
+- **Studio users see `🔒`, not the value.** That is the point of the flag: the people authoring the app cannot read what their end users store. The column also cannot be searched, filtered or sorted on — ciphertext is opaque.
+- **Sample `rows` are encrypted too.** They used to be written straight into the value table; a plaintext row under an encrypted column would have been read back as a corrupt envelope.
+- **Not valid on `RELATION`.** Its value is a foreign key the backend has to resolve, so it can never be opaque — declaring it is now a publish error, as is a non-boolean `encrypted`.
+- **An upgrade adds a new encrypted column, but never flips a live one.** Turning encryption on over existing plaintext (or off over existing ciphertext) would strand what is already stored, so a changed flag on a column that already exists is reported back to you rather than applied.
 
 ### What's new in 0.136.0 (contract 1.105.0)
 
@@ -445,7 +476,7 @@ When you take the `useCanWrite`-only route, omit the USER column for a guest (`i
 
 **Dismissing the picker resolves `null`, not an error.** Backing out is the most common outcome, so it is deliberately not a rejection — your happy path needs no `try/catch`. A genuine failure (permission refused, no host broker) rejects with a structured `CameraError` (new named export) carrying a stable `.code` (`PERMISSION_DENIED` / `UNSUPPORTED` / `INTERNAL`).
 
-**One upload path on both hosts.** The resolved asset is normalised to `{ uri, name, mimeType, width, height, size, file }`, where `uri` is directly displayable (`<Image source={{ uri }} />`) and `file` is already the right upload part for the platform — a `File` on web, a `{ uri, name, type }` triple on native. So the same three lines work everywhere:
+**One upload path on both hosts.** The resolved asset is normalised to `{ uri, name, mimeType, width, height, size, file }`, where `uri` is directly displayable (`<Image source={{ uri }} />`) and `file` is already the right upload part for the platform — a Blob on both hosts: a browser `File` on web, expo-file-system's `File` on native. (It must be a Blob: Expo's fetch implements the web FormData spec and rejects React Native's legacy `{ uri, name, type }` part.) So the same three lines work everywhere:
 
 ```js
 const fd = new FormData();
@@ -1470,7 +1501,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `onLayout={(e) => setWidth(e.nativeEvent.layout.width)}` on the root `View` (a React Native primitive, so it behaves identically on both hosts), render nothing size-dependent while `width === 0`, and compute every threshold from the measured value: a widget gets no declared breakpoint prop, but it can always measure. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces above ~720px measured width** (`flexDirection: width >= 720 ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget.
 - **Compose forms — pair fields into rows, don't stack one per row.** Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column (sc-7274) — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them. When a field carries an icon beside it (a search glyph, a clear button), the border belongs on the WRAPPER row and the `TextInput` inside it goes borderless and transparent with `flex: 1, minWidth: 0` (the `minWidth: 0` stops a long value pushing the border past its container) — React Native has no `:focus-within`, so drive the wrapper's `borderColor` between `colors.border` and `colors.primary` from the input's own `onFocus` / `onBlur`. A border left on the input rings only its own `<input>` box on web, leaving the icon outside the ring; never absolutely-position the icon over the field to work around it.
 - **Respond to touch.** Give every `Pressable` the lift via the function-style `style={(state) => [base, ...pressableLift(state)]}` — see "Answer the touch" above. Never dim with `opacity`, which reads as the surface disabling itself.
-- **Drag and drop — show what is being dragged.** A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`.
+- **Drag and drop — show what is being dragged.** A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`. **A board (kanban, pipeline) drops onto ANOTHER column**, which needs four more things: the board's root renders the one proxy (a column clips whatever leaves it); you hit-test the drop yourself — `measureInWindow` every column and the board when the drag starts and compare the gesture's window `moveX` (never `onLayout` frames, which are relative to a padded or scrolled parent) — highlighting exactly one target; the drop WRITES (`update(id, { [statusField]: value })` through `useDatastoreMutation`, optimistic until `refetch()`, a toast and a spring-back on failure); and three or more columns go in a `horizontal` `ScrollView` below `isNarrowWidth`, with the grip claiming the gesture (`onStartShouldSetPanResponder`, `onPanResponderTerminationRequest: () => false`) and carrying `touchAction: 'none'` on web so a finger drag moves the card instead of scrolling the page. And because `useRef(PanResponder.create(...))` runs ONCE, everything its callbacks read — the `useCanWrite` flag included, which starts `false` — goes through a ref refreshed every render (`latest.current.canDrag`); the publish gate `widget.staleResponder` rejects a value read directly.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme. The label never repeats the icon as a character — with a `Plus` icon the button says "Add item", never "+ Add item" (that renders a doubled plus).
 - **Use imagery deliberately.** Render pictures with the `Image` primitive (`source` takes a URL or `{ uri }`); resolve workspace assets via `useAsset()`. Give every image a sized, `radii`-clipped container so it never renders as a raw rectangle, and never hardcode a credentialed image URL — expose an `image`-type property instead. The frame is your decision, never the picture's: size it for the role (a 40–56 square avatar, a 72–96 square row thumbnail, a `16 / 9` card cover, a 160–240 tall band) and let `resizeMode="cover"` crop the photo into it — photos arrive at every size and ratio, so one left to its own proportions breaks the layout. Keep `contain` for art whose whole subject must stay visible (a logo, a diagram), inside a fixed frame.
 - **Design the empty, loading, and error states.** A blank box on a fresh install reads as broken — show a short helper line when a list is empty, a calm loading line, and a single human sentence in `colors.danger` on error.

package/dist/contract.cjs

@@ -886,8 +886,11 @@ const HOOKS = [
       "from the host context, builds a multipart FormData with the " +
       "snake_case fields the backend reads verbatim (`space_type`, " +
       "`owner_id`, `folder_id`, plus the binary `file`), and POSTs through " +
-      "ctx.filestore.files.upload. `upload(file, { folderId?, compress? })` " +
-      "resolves to the created file row or throws the wire error. Branch " +
+      "ctx.filestore.files.upload. `upload(file, { folderId?, compress?, fileName? })` " +
+      "resolves to the created file row or throws the wire error. `file` must be a BLOB — a browser File on web, " +
+      "expo-file-system's File on native (what FilePicker / useCamera / useImageEditor hand back); Expo's fetch rejects " +
+      "React Native's legacy { uri, name, type } part with \"Unsupported FormDataPart implementation\". The stored name " +
+      "comes from the Blob's `.name` unless `fileName` overrides it. Branch " +
       "on `err.status`: 403 means the destination denied the add and says " +
       "so, because the caller can see that position — for a public space " +
       "that means an operator has not switched upload access on yet; 404 " +
@@ -907,7 +910,7 @@ const HOOKS = [
       "'project' for content restricted to signed-in workspace users, " +
       "'personal' for a file private to the uploading app user.",
     returnShape: {
-      upload: "(file, { folderId?, compress? }) => Promise<FilestoreFile>",
+      upload: "(file, { folderId?, compress?, fileName? }) => Promise<FilestoreFile>",
       uploading: "boolean",
       error: "Error | null",
       lastUploaded: "FilestoreFile | null",
@@ -1668,7 +1671,8 @@ const HOOKS = [
       "{ uri, name, mimeType, width, height, size, file }, or NULL when the user dismisses the picker — dismissal is the " +
       "common case and is deliberately NOT an error, so no try/catch is needed on the happy path. They reject with a " +
       "CameraError whose .code is one of PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `asset.file` is already the right " +
-      "upload part for the host (a File on web, { uri, name, type } on native): append it to a FormData as `file` and pass " +
+      "upload part for the host — a BLOB on both (a File on web, expo-file-system's File on native), because Expo's fetch " +
+      "implements the web FormData spec and rejects React Native's legacy { uri, name, type } part outright: append it to a FormData as `file` and pass " +
       "that to ctx.assets.upload(fd) — one code path on both platforms. reset() clears the asset and releases it. Check " +
       "`supported` before rendering a camera button. options: { allowsEditing, quality } are HINTS the host honours where it " +
       "can — the Expo export applies both, the web camera applies quality only, so never depend on a cropped result. " +
@@ -2153,7 +2157,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected.",
   },
   translations: {
     type: "object",
@@ -3926,7 +3930,24 @@ const CONTRACT = deepFreeze({
   //    template declaring neither behaves exactly as before, and a role nobody
   //    binds writes no grant rather than failing the install. Minor bump on the
   //    pre-1.0 channel.
-  version: "1.105.0",
+  //
+  // 1.107.0: fix + additive — every FILE UPLOAD from the Expo export failed
+  //    with "Unsupported FormDataPart implementation". Expo's fetch implements
+  //    the WEB FormData spec, so a part must be a string or a Blob, but all
+  //    three native producers (`useCamera`, `useImageEditor`, `<FilePicker>`)
+  //    handed back React Native's legacy `{ uri, name, type }` triple, which it
+  //    rejects before a byte leaves the device. Web was unaffected because a
+  //    browser `File` IS a Blob. All three now hand back expo-file-system's
+  //    `File`, the shape Expo's fetch accepts, exposing the same
+  //    `uri` / `name` / `type` / `size`, so a widget reading those is
+  //    unaffected — each producer shadows the name + type the cache URI
+  //    would otherwise impose. `useFilestoreUpload` additionally carries the
+  //    multipart FILENAME (a bare Blob would be stored as "blob") and accepts a
+  //    `fileName` override: as append()'s third argument for a real Blob, and
+  //    ON the part otherwise, since expo-file-system's File is NOT
+  //    `instanceof Blob` at runtime and Expo reads the name off the part.
+  //    One upload path on both hosts, as before.
+  version: "1.107.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -886,8 +886,11 @@ const HOOKS = [
       "from the host context, builds a multipart FormData with the " +
       "snake_case fields the backend reads verbatim (`space_type`, " +
       "`owner_id`, `folder_id`, plus the binary `file`), and POSTs through " +
-      "ctx.filestore.files.upload. `upload(file, { folderId?, compress? })` " +
-      "resolves to the created file row or throws the wire error. Branch " +
+      "ctx.filestore.files.upload. `upload(file, { folderId?, compress?, fileName? })` " +
+      "resolves to the created file row or throws the wire error. `file` must be a BLOB — a browser File on web, " +
+      "expo-file-system's File on native (what FilePicker / useCamera / useImageEditor hand back); Expo's fetch rejects " +
+      "React Native's legacy { uri, name, type } part with \"Unsupported FormDataPart implementation\". The stored name " +
+      "comes from the Blob's `.name` unless `fileName` overrides it. Branch " +
       "on `err.status`: 403 means the destination denied the add and says " +
       "so, because the caller can see that position — for a public space " +
       "that means an operator has not switched upload access on yet; 404 " +
@@ -907,7 +910,7 @@ const HOOKS = [
       "'project' for content restricted to signed-in workspace users, " +
       "'personal' for a file private to the uploading app user.",
     returnShape: {
-      upload: "(file, { folderId?, compress? }) => Promise<FilestoreFile>",
+      upload: "(file, { folderId?, compress?, fileName? }) => Promise<FilestoreFile>",
       uploading: "boolean",
       error: "Error | null",
       lastUploaded: "FilestoreFile | null",
@@ -1668,7 +1671,8 @@ const HOOKS = [
       "{ uri, name, mimeType, width, height, size, file }, or NULL when the user dismisses the picker — dismissal is the " +
       "common case and is deliberately NOT an error, so no try/catch is needed on the happy path. They reject with a " +
       "CameraError whose .code is one of PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `asset.file` is already the right " +
-      "upload part for the host (a File on web, { uri, name, type } on native): append it to a FormData as `file` and pass " +
+      "upload part for the host — a BLOB on both (a File on web, expo-file-system's File on native), because Expo's fetch " +
+      "implements the web FormData spec and rejects React Native's legacy { uri, name, type } part outright: append it to a FormData as `file` and pass " +
       "that to ctx.assets.upload(fd) — one code path on both platforms. reset() clears the asset and releases it. Check " +
       "`supported` before rendering a camera button. options: { allowsEditing, quality } are HINTS the host honours where it " +
       "can — the Expo export applies both, the web camera applies quality only, so never depend on a cropped result. " +
@@ -2153,7 +2157,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected.",
   },
   translations: {
     type: "object",
@@ -3926,7 +3930,24 @@ const CONTRACT = deepFreeze({
   //    template declaring neither behaves exactly as before, and a role nobody
   //    binds writes no grant rather than failing the install. Minor bump on the
   //    pre-1.0 channel.
-  version: "1.105.0",
+  //
+  // 1.107.0: fix + additive — every FILE UPLOAD from the Expo export failed
+  //    with "Unsupported FormDataPart implementation". Expo's fetch implements
+  //    the WEB FormData spec, so a part must be a string or a Blob, but all
+  //    three native producers (`useCamera`, `useImageEditor`, `<FilePicker>`)
+  //    handed back React Native's legacy `{ uri, name, type }` triple, which it
+  //    rejects before a byte leaves the device. Web was unaffected because a
+  //    browser `File` IS a Blob. All three now hand back expo-file-system's
+  //    `File`, the shape Expo's fetch accepts, exposing the same
+  //    `uri` / `name` / `type` / `size`, so a widget reading those is
+  //    unaffected — each producer shadows the name + type the cache URI
+  //    would otherwise impose. `useFilestoreUpload` additionally carries the
+  //    multipart FILENAME (a bare Blob would be stored as "blob") and accepts a
+  //    `fileName` override: as append()'s third argument for a real Blob, and
+  //    ON the part otherwise, since expo-file-system's File is NOT
+  //    `instanceof Blob` at runtime and Expo reads the name off the part.
+  //    One upload path on both hosts, as before.
+  version: "1.107.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/filepicker.native.js

@@ -10,15 +10,20 @@
 //
 // `onPick` receives the same shape on both platforms:
 //   - web → the browser's `File` object (a `Blob` with name + type).
-//   - native → `{ uri, name, type, size }` — React Native's
-//     FormData-friendly file part. `useFilestoreUpload` appends whichever
-//     verbatim into the multipart body; the React Native fetch
-//     implementation reads `uri` and streams the bytes.
+//   - native → expo-file-system's `File` — ALSO a `Blob`, and carrying the
+//     same `uri` / `name` / `type` / `size` the old React Native
+//     `{ uri, name, type, size }` part did, so a widget reading those is
+//     unaffected. It must be a Blob: Expo's fetch implements the WEB
+//     FormData spec and rejects the RN triple outright ("Unsupported
+//     FormDataPart implementation"), which failed every native upload.
+//     `useFilestoreUpload` appends whichever verbatim into the multipart body.
 
 import React, { useCallback, useMemo } from "react";
 import { Pressable, View } from "react-native";
 // eslint-disable-next-line no-restricted-syntax
 import { getDocumentAsync } from "expo-document-picker";
+// eslint-disable-next-line no-restricted-syntax
+import { File as FsFile } from "expo-file-system";
 
 // Map an HTML `accept` string (the web contract — "image/*", "audio/*",
 // "image/png,image/jpeg", …) to expo-document-picker's `type` arg, which
@@ -38,17 +43,28 @@ function _mapAccept(accept) {
 }
 
 // expo-document-picker returns `{ canceled, assets: [{ uri, name,
-// mimeType, size }] }`. Normalise each asset to the FormData-friendly
-// `{ uri, name, type, size }` shape useFilestoreUpload appends into the
-// multipart body — `type` is the field React Native's FormData reads
-// for the part's content-type, mirroring the browser File's `.type`.
+// mimeType, size }] }`. The part handed to onPick is expo-file-system's
+// File, exposing the same uri / name / type / size the old plain object
+// did. It must NOT be the old object: Expo's fetch refuses that shape, so
+// keeping it as a fallback would only defer the failure.
 function _asset(picked) {
-  return {
-    uri: picked.uri,
-    name: picked.name || "upload",
-    type: picked.mimeType || "application/octet-stream",
-    size: typeof picked.size === "number" ? picked.size : undefined,
-  };
+  const file = new FsFile(picked.uri);
+  // Both are read off the PART when the multipart is serialised (the third
+  // `append` argument is ignored for a non-Blob), and both are derived from
+  // the cache URI — which may be renamed, percent-encoded, or extensionless.
+  // The picker's own values are the ones the user and the backend expect.
+  _shadow(file, "name", picked.name || "upload");
+  _shadow(file, "type", picked.mimeType || "application/octet-stream");
+  return file;
+}
+
+function _shadow(file, key, value) {
+  if (!value || file[key] === value) return;
+  try {
+    Object.defineProperty(file, key, { value, configurable: true });
+  } catch {
+    /* non-configurable: whatever the platform derived stands */
+  }
 }
 
 export function FilePicker({

package/dist/hooks.js

@@ -3571,13 +3571,14 @@ export function useFilestoreFile(fileId) {
  * same way the read hooks do (tenant for PROJECT, app user for PERSONAL)
  * and posts a multipart FormData to `ctx.filestore.files.upload`.
  *
- * `upload(file, { folderId? })` accepts whatever the host's FormData
- * implementation reads as a binary file part — on the web Player a
- * browser `File`, on the Expo export the React Native shape
- * `{ uri, name, type }` returned by `<FilePicker>` (which wraps
- * `expo-document-picker` natively and a hidden DOM `<input type="file">`
- * on web). FormData serialises both verbatim, so the same hook code path
- * feeds the multipart on both platforms.
+ * `upload(file, { folderId?, fileName? })` takes a BLOB on both hosts — a
+ * browser `File` on the web Player, expo-file-system's `File` (also a Blob)
+ * on the Expo export, as `<FilePicker>`, `useCamera()` and `useImageEditor()`
+ * all hand back. It must be a Blob: Expo's fetch implements the web FormData
+ * spec and rejects React Native's legacy `{ uri, name, type }` part with
+ * "Unsupported FormDataPart implementation", which failed every native
+ * upload. `fileName` overrides the stored name, which otherwise comes from
+ * the Blob's own `.name`.
  *
  * The destination can refuse the add two ways (sc-6977). BRANCH ON
  * `err.status`: 403 means the caller may know why — most often a public space
@@ -3636,7 +3637,27 @@ export function useFilestoreUpload(options) {
       // sc-5402: only the opt-out is sent, so the backend stays the single
       // source of the default (it compresses images to WebP).
       if (compress === false) form.append("compress", "false");
-      form.append("file", file);
+      // The multipart FILENAME is what the backend stores as the file's name
+      // (multer's `originalname`), and a Blob with no third argument lands as
+      // "blob". Both hosts' parts carry `.name` — a browser File, and
+      // expo-file-system's File on native — so pass it through explicitly.
+      const partName =
+        (overrides && typeof overrides.fileName === "string" && overrides.fileName) ||
+        (typeof file.name === "string" && file.name ? file.name : null);
+      // The three-argument append is SPEC'd for a Blob only — a compliant
+      // FormData throws on anything else, and Expo's ignores the name. So a
+      // non-Blob part (expo-file-system's File: `implements Blob` is erased at
+      // runtime) carries its name ON itself, which is where Expo reads it.
+      const isBlob = typeof Blob !== "undefined" && file instanceof Blob;
+      if (partName && !isBlob && file.name !== partName) {
+        try {
+          Object.defineProperty(file, "name", { value: partName, configurable: true });
+        } catch {
+          /* non-configurable: the part's own name stands */
+        }
+      }
+      if (partName && isBlob) form.append("file", file, partName);
+      else form.append("file", file);
       setUploading(true);
       setError(null);
       try {

package/dist/index.d.ts

@@ -186,6 +186,15 @@ export interface WidgetDatastoreTemplateColumn {
   relationType?: "ONE_TO_ONE" | "ONE_TO_MANY" | "MANY_TO_MANY";
   /** REQ-ACL-RELINHERIT: opt this RELATION column into row-level ACL inheritance. */
   inheritAcl?: boolean;
+  /**
+   * REQ-DDL-ENCRYPT: store this column's values encrypted at rest (AES-256-GCM
+   * under a per-workspace subkey). The widget still reads and writes plaintext
+   * — the platform encrypts on write and decrypts for end users — but studio
+   * users see `🔒` instead of the value, and the column cannot be searched,
+   * filtered or sorted on. Not valid on `RELATION` (its value is a foreign key
+   * the backend must resolve); publishing one is rejected.
+   */
+  encrypted?: boolean;
 }
 
 export interface WidgetDatastoreTemplateTable {
@@ -1665,7 +1674,8 @@ export interface CameraAsset {
   /** Bytes, when the host reports it. */
   size: number | null;
   /**
-   * Ready-to-upload part — a `File` on web, `{ uri, name, type }` on native.
+   * Ready-to-upload part — a Blob on both hosts: a `File` on web,
+   * expo-file-system's `File` on native. Expo's fetch rejects any other shape.
    * Append it to a FormData and hand that to `ctx.assets.upload(...)`.
    */
   file: unknown;
@@ -1740,7 +1750,7 @@ export interface EditedImage {
   size: number | null;
   /** Present only when `base64` was requested. */
   base64?: string;
-  /** Ready-to-upload part — a `File` on web, `{ uri, name, type }` on native. */
+  /** Ready-to-upload part — a Blob on both: a `File` on web, expo-file-system's `File` on native. */
   file: unknown;
 }
 

package/package.json

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