@colixsystems/widget-sdk 0.197.0 → 0.198.0

package/dist/index.d.ts

@@ -187,6 +187,12 @@ 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;
+  /**
+   * With `inheritAcl: true` only: rows inherit read access alone. Members of
+   * the parent row read every child and may add children, but change or
+   * delete only the rows they created (pair with `grantCreatorPermissions`).
+   */
+  inheritAclReadOnly?: boolean;
   /**
    * ONE_TO_ONE / ONE_TO_MANY only: what deleting the referenced row does to
    * this table's rows. `CASCADE` deletes them too; `SET_NULL` (the default)
@@ -202,6 +208,26 @@ export interface WidgetDatastoreTemplateColumn {
    * the backend must resolve); publishing one is rejected.
    */
   encrypted?: boolean;
+  /**
+   * Written when a create omits the column. `"@currentUser"` (USER) stamps
+   * the signed-in user and `"@now"` (DATE / DATETIME) the current date or
+   * time. Other types take a literal of their own type. FILE, RELATION and
+   * USER_GROUP columns take none, because ids belong to the installing
+   * workspace.
+   */
+  defaultValue?: unknown;
+  /**
+   * With a `"@currentUser"` or `"@now"` default only: the server always
+   * stamps it. Any value a client sends for the column is ignored on create
+   * and on update, so an author column cannot be forged.
+   */
+  defaultLocked?: boolean;
+  /**
+   * Write-once: a create sets the column as usual (the value sent, or the
+   * default), and any value sent for it on update is ignored. Not valid on a
+   * `MANY_TO_MANY` relation, whose links live outside the row.
+   */
+  immutable?: boolean;
 }
 
 export interface WidgetDatastoreTemplateTable {
@@ -367,7 +393,7 @@ export interface WidgetManifest {
    * under a per-widget namespace (`widget.<id>.<key>`), so `useI18n().t(key)`
    * resolves the namespaced key automatically — the author never types the
    * prefix. Non-destructive (admin edits win; absent languages are not
-   * created) and persists across uninstalls. Caps: ≤100 keys, key matches
+   * created) and persists across uninstalls. Caps: ≤200 keys, key matches
    * /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/, value ≤1 KB.
    */
   translations?: Record<string, { en: string } & Record<string, string>>;
@@ -639,6 +665,35 @@ export interface IdentificationClient {
  */
 export interface NotificationsClient {
   send(body: SendNotificationRequest): Promise<NotificationRow>;
+  /**
+   * sc-10268 — the signed-in user's per-record mutes; backs `useRecordMute`
+   * and `useRecordMutes`.
+   * Optional: a host without it leaves the hook reading not muted.
+   */
+  mutes?: {
+    get(ref: { table_id: string; record_id: string }): Promise<RecordMuteWire>;
+    set(body: {
+      table_id: string;
+      record_id: string;
+      muted_until: string | null;
+    }): Promise<RecordMuteWire>;
+    clear(ref: { table_id: string; record_id: string }): Promise<void>;
+    /** Backs `useRecordMutes`: one page of the user's active mutes. */
+    list(query: {
+      table_id: string;
+      limit?: number;
+      offset?: number;
+    }): Promise<{
+      data: Array<{ record_id: string; muted_until: string | null }>;
+      meta: { total: number; limit: number; offset: number };
+    }>;
+  };
+}
+
+/** The mute wire shape, snake_case verbatim. */
+export interface RecordMuteWire {
+  muted: boolean;
+  muted_until: string | null;
 }
 
 export interface WidgetContext<TProps = unknown> {
@@ -988,6 +1043,11 @@ export interface DirectoryQuery {
    * `useGroups()` row. Pair with a group picker to build "members of group X".
    */
   group_id?: string;
+  /**
+   * Only these users (1 to 100 ids): resolve the names behind ids you already
+   * hold — message senders, members — without loading the whole roster.
+   */
+  ids?: string[];
   limit?: number;
   offset?: number;
 }
@@ -1145,6 +1205,45 @@ export interface SendNotificationApi {
  */
 export function useSendNotification(): SendNotificationApi;
 
+export interface RecordMuteApi {
+  muted: boolean;
+  /** ISO time the mute ends; null when muted until unmuted, or not muted. */
+  mutedUntil: string | null;
+  loading: boolean;
+  error: NotificationError | null;
+  /** An ISO time or a Date; null or omitted mutes until `unmute()`. */
+  mute(until?: string | Date | null): Promise<void>;
+  unmute(): Promise<void>;
+  refetch(): Promise<void>;
+}
+
+/**
+ * sc-10268 — the signed-in user's mute of one datastore record's
+ * notifications. While muted, `notifications.notifyRecordSubjects` on the
+ * record sends them nothing. A record they cannot read fails with
+ * `RECORD_NOT_FOUND`; a falsy id returns a stable not-muted result.
+ */
+export function useRecordMute(
+  tableId: string | null | undefined,
+  recordId: string | null | undefined,
+): RecordMuteApi;
+
+export interface RecordMutesApi {
+  /** True while the record's mute is active; false once a timed mute lapses. */
+  isMuted(recordId: string | null | undefined): boolean;
+  loading: boolean;
+  error: NotificationError | null;
+  refetch(): Promise<void>;
+}
+
+/**
+ * sc-10268 — which records of one table the signed-in user has muted, in one
+ * read for a whole list. A `useRecordMute` write on the table shows at once.
+ */
+export function useRecordMutes(
+  tableId: string | null | undefined,
+): RecordMutesApi;
+
 export interface WorkspaceCurrency {
   /** The ISO code this workspace charges its app users in. */
   currency: string;
@@ -1704,6 +1803,35 @@ export function useNavigation(): {
  */
 export function useRouteParams(): Record<string, unknown>;
 
+/**
+ * sc-10268 — puts `count` on the menu entry or tab of the page this widget is
+ * on. The host sums the page's widgets and keeps the last count after the
+ * widget leaves the screen; 0 clears this widget's share.
+ */
+/**
+ * sc-10268 — `{ uri }` an `<Image>` can show for a picked file before it is
+ * uploaded. Null for no file, or a host that cannot preview one.
+ */
+export function useFilePreview(file: unknown): { uri: string | null };
+
+export function usePageBadge(count: number | null | undefined): {
+  supported: boolean;
+};
+
+/**
+ * sc-10268 — Android's back button for a widget with pages of its own.
+ * `handler` runs on a back press while the widget's screen is in view; return
+ * true when it went back a step, false to let the app go back. Pass null while
+ * there is nothing to go back from. `supported` is false on the web, which has
+ * no hardware back, so keep a visible back control too.
+ *
+ * @example
+ *   useHardwareBack(openThread ? () => { closeThread(); return true; } : null);
+ */
+export function useHardwareBack(handler: (() => boolean) | null | undefined): {
+  supported: boolean;
+};
+
 /**
  * REQ-NAV-05 — the PAGE's resolved context. When the page declares typed
  * parameters, the host resolves them ONCE before any widget renders: `params`
@@ -2068,7 +2196,7 @@ export interface CameraOptions {
   quality?: number;
 }
 
-/** A photo taken or picked through `useCamera()`, normalised across hosts. */
+/** A photo (or, from `pick({ videos: true })`, a video) taken or picked through `useCamera()`, normalised across hosts. */
 export interface CameraAsset {
   /** Displayable source — `<Image source={{ uri }} />` / `<img src>`. */
   uri: string;
@@ -2079,6 +2207,8 @@ export interface CameraAsset {
   height: number | null;
   /** Bytes, when the host reports it. */
   size: number | null;
+  /** A video's length in milliseconds when the host reports it; null for a photo. */
+  durationMs: number | null;
   /**
    * 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.
@@ -2096,8 +2226,13 @@ export interface CameraResult {
   supported: boolean;
   /** Open the camera. Resolves null if the user dismisses it. */
   capture(): Promise<CameraAsset | null>;
-  /** Open the photo library. Resolves null if the user dismisses it. */
-  pick(): Promise<CameraAsset | null>;
+  /**
+   * Open the photo library. Resolves null if the user dismisses it.
+   * `{ multiple: true }` resolves an array of up to 10; `{ videos: true }`
+   * offers videos beside photos (play one with `<Video>`).
+   */
+  pick(options: { multiple: true; videos?: boolean }): Promise<CameraAsset[] | null>;
+  pick(options?: { multiple?: false; videos?: boolean }): Promise<CameraAsset | null>;
   /** Clear `asset` and `error`, releasing the held asset. */
   reset(): void;
 }
@@ -2412,6 +2547,10 @@ export class NotificationError extends Error {
     | "FORBIDDEN"
     | "RECIPIENT_NOT_FOUND"
     | "RATE_LIMITED"
+    | "RECORD_NOT_FOUND"
+    | "INVALID_MUTED_UNTIL"
+    | "INVALID_RECORD_REF"
+    | "NOTIFICATIONS_UNAVAILABLE"
     | "INTERNAL"
     | string;
   constructor(
@@ -2904,6 +3043,35 @@ export const Gradient: (props: {
   children?: ReactNode;
 }) => any;
 
+/**
+ * sc-10268 — plays a video file inline with the platform's own controls, the
+ * first frame showing before playback. Web uses the browser's `<video>`;
+ * native uses expo-video's VideoView. It fills the box `style` gives it.
+ *
+ * @example
+ *   <Video
+ *     source={file.url}
+ *     contentFit="cover"
+ *     style={{ width: 240, height: 180, borderRadius: theme.radii.md, overflow: "hidden" }}
+ *     onError={() => setPlayable(false)}
+ *   />
+ */
+export const Video: (props: {
+  /** A playable URL; null renders an empty box. */
+  source: string | null;
+  /** Play, seek and fullscreen controls. Defaults to true. */
+  controls?: boolean;
+  /** Starts playing muted, as browsers allow only muted autoplay. */
+  autoPlay?: boolean;
+  /** Letterboxed ("contain", the default) or cropped to fill ("cover"). */
+  contentFit?: "contain" | "cover";
+  style?: any;
+  accessibilityLabel?: string;
+  testID?: string;
+  /** The file could not be played on this host. */
+  onError?: () => void;
+}) => any;
+
 /**
  * sc-6607 — screen-level overlay. Renders OUTSIDE the widget's layout box on
  * both hosts (web portals it to the document root, native uses the OS modal),
@@ -3054,9 +3222,14 @@ export const Badge: (props: {
 }) => any;
 
 /** Themed picture of a person, falling back to initials, then a glyph. */
+/** The stable colour `<Avatar seed>` paints for a seed, or null for none. */
+export function avatarColorFor(seed: string | null | undefined): string | null;
+
 export const Avatar: (props: {
   /** Drives the initials and the accessibility label. */
   name?: string;
+  /** A stable id (a user id): tints the monogram with that person's colour. */
+  seed?: string;
   /** An absolute image URL. */
   url?: string;
   /** A size token, or a number of px (clamped to 16-160). */

package/dist/index.js

@@ -46,6 +46,7 @@ export {
   useFilestoreFolders,
   useFilestoreCreateFolder,
   useFilestoreCopy,
+  useFilestoreDelete,
   useFileSignature,
   useFileSignatures,
   useFileRoster,
@@ -66,6 +67,8 @@ export {
   usePayments,
   useWorkspaceCurrency,
   useSendNotification,
+  useRecordMute,
+  useRecordMutes,
   useTheme,
   useWidgetStyle,
   useI18n,
@@ -78,6 +81,9 @@ export {
   useFill,
   useNavigation,
   useRouteParams,
+  usePageBadge,
+  useHardwareBack,
+  useFilePreview,
   usePageContext,
   useWidgetRoute,
   useChildRenderer,
@@ -160,6 +166,7 @@ export {
   DateTimePicker,
   FilePicker,
   Gradient,
+  Video,
 } from "./primitives.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
 // sc-3696: the trailing six are the theme-derivation helpers both hosts resolve
@@ -215,6 +222,7 @@ export { List, ListRow, ListHeader, EmptyState } from "./list.js";
 // Themed detail parts; the stock Badge/Avatar/Progress/Stat/Divider wrap these.
 export { Badge, Avatar, Progress, Stat, Divider } from "./detail-parts.js";
 export { initialsFor } from "./initials.js";
+export { avatarColorFor } from "./avatar-color.js";
 // The one card surface: the theme's `card` scope, a gradient fill, margin.
 export { Card } from "./card.js";
 export {

package/dist/index.native.js

@@ -46,6 +46,7 @@ export {
   useFilestoreFolders,
   useFilestoreCreateFolder,
   useFilestoreCopy,
+  useFilestoreDelete,
   useFileSignature,
   useFileSignatures,
   useFileRoster,
@@ -66,6 +67,8 @@ export {
   usePayments,
   useWorkspaceCurrency,
   useSendNotification,
+  useRecordMute,
+  useRecordMutes,
   useTheme,
   useWidgetStyle,
   useI18n,
@@ -78,6 +81,9 @@ export {
   useFill,
   useNavigation,
   useRouteParams,
+  usePageBadge,
+  useHardwareBack,
+  useFilePreview,
   usePageContext,
   useWidgetRoute,
   useChildRenderer,
@@ -153,6 +159,7 @@ export {
   DateTimePicker,
   FilePicker,
   Gradient,
+  Video,
 } from "./primitives.native.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
 // sc-3696: the trailing six are the theme-derivation helpers both hosts resolve
@@ -208,6 +215,7 @@ export { List, ListRow, ListHeader, EmptyState } from "./list.native.js";
 // Themed detail parts; the stock Badge/Avatar/Progress/Stat/Divider wrap these.
 export { Badge, Avatar, Progress, Stat, Divider } from "./detail-parts.native.js";
 export { initialsFor } from "./initials.js";
+export { avatarColorFor } from "./avatar-color.js";
 // The one card surface: the theme's `card` scope, a gradient fill, margin.
 export { Card } from "./card.native.js";
 export {

package/dist/initials.js

@@ -4,14 +4,15 @@
 // Returns "" when the name yields no letters, so each caller keeps its own
 // fallback (a "?", a person glyph).
 
-/** "Ada Lovelace" → "AL", "Ada" → "A", "  " → "". */
+/** "Ada Lovelace" → "AL", "Börje" → "BÖ", "  " → "". */
 export function initialsFor(name) {
   const parts =
     typeof name === "string" ? name.trim().split(/\s+/).filter(Boolean) : [];
   if (parts.length === 0) return "";
   // Array.from, not slice: a multi-byte first character must not be halved.
   const first = Array.from(parts[0])[0];
-  if (parts.length === 1) return first.toUpperCase();
+  // sc-10268: one word still gets two letters, as the Studio's member lists show.
+  if (parts.length === 1) return Array.from(parts[0]).slice(0, 2).join("").toUpperCase();
   const last = Array.from(parts[parts.length - 1])[0];
   return (first + last).toUpperCase();
 }

package/dist/manifest.cjs

@@ -46,7 +46,8 @@ const VALID_PLATFORMS = new Set(["web", "native"]);
 // backend/src/core/services/l10n.service.js). The locale pattern mirrors that
 // service's LANG_CODE_RE so a manifest can't declare a locale the dictionary
 // would reject.
-const TRANSLATIONS_MAX_KEYS = 100;
+// One page of the dictionary's widget namespace (l10n MAX_KEYS_PER_PAGE).
+const TRANSLATIONS_MAX_KEYS = 200;
 const TRANSLATION_VALUE_MAX_BYTES = 1024;
 const TRANSLATION_KEY_RE = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
 const TRANSLATION_LOCALE_RE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/;

package/dist/manifest.js

@@ -60,7 +60,8 @@ const ACTION_TIMEOUT_MAX_MS = 5 * 60 * 1000;
 // backend/src/core/services/l10n.service.js). The locale pattern mirrors that
 // service's LANG_CODE_RE so a manifest can't declare a locale the dictionary
 // would reject.
-const TRANSLATIONS_MAX_KEYS = 100;
+// One page of the dictionary's widget namespace (l10n MAX_KEYS_PER_PAGE).
+const TRANSLATIONS_MAX_KEYS = 200;
 const TRANSLATION_VALUE_MAX_BYTES = 1024;
 const TRANSLATION_KEY_RE = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
 const TRANSLATION_LOCALE_RE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/;

package/dist/overlay-view.js

@@ -6,7 +6,7 @@
 // (`overflow: hidden` cards, scroll containers) clip it and where React Native
 // has no `position: "fixed"` at all. `<Overlay>` fixes that for both hosts at
 // once by rendering into React Native's `Modal`, which leaves the parent's
-// layout on BOTH platforms — react-native-web portals it to `document.body`,
+// layout on BOTH platforms — the web binding portals it to `document.body`,
 // native hands it to the OS — while keeping the children in the widget's own
 // React tree, so their state, hooks and WidgetContext all survive.
 //
@@ -74,10 +74,7 @@ export function makeOverlay(rn) {
       {
         visible: true,
         transparent: true,
-        // Not animated on purpose: the web host arms the overlay's dialog role
-        // and its Escape handler when the entrance animation ENDS, so a fade
-        // leaves a window where the keyboard cannot dismiss it — and a dropped
-        // animation event would leave it un-dismissable for good.
+        // Not animated: a sheet must answer the tap that opened it at once.
         animationType: "none",
         onRequestClose: requestClose,
       },

package/dist/overlay.js

@@ -1,13 +1,20 @@
 // sc-6607 — `<Overlay>` (web). Binds the shared implementation in
-// ./overlay-view.js to react-native-web's primitives.
+// ./overlay-view.js to react-native-web's primitives, with ./web-modal.js in
+// place of react-native-web's `Modal`, which breaks under React StrictMode.
 //
 // The import is `react-native-web` rather than the bare `react-native`
 // specifier for the rolldown optional-peer-dep reason spelled out at the top of
-// ./primitives.js. react-native-web's `Modal` portals its subtree into a
-// `document.body` container at `position: fixed`, which is exactly what makes
-// the overlay escape the widget's clipping ancestors.
+// ./primitives.js. The modal layer portals its subtree into a `document.body`
+// container at `position: fixed`, which is exactly what makes the overlay
+// escape the widget's clipping ancestors.
 
 import * as ReactNative from "react-native-web";
 import { makeOverlay } from "./overlay-view.js";
+import { WebModal } from "./web-modal.js";
 
-export const Overlay = makeOverlay(ReactNative);
+export const Overlay = makeOverlay({
+  Modal: WebModal,
+  View: ReactNative.View,
+  Pressable: ReactNative.Pressable,
+  StyleSheet: ReactNative.StyleSheet,
+});

package/dist/primitives.js

@@ -80,3 +80,5 @@ export { FilePicker } from "./filepicker.js";
 // `linear-gradient` on a View; the native build (./gradient.native.js) delegates
 // to expo-linear-gradient through the same angle projection.
 export { Gradient } from "./gradient.js";
+// sc-10268 — `<Video>` (web): the browser's <video>, inline with controls.
+export { Video } from "./video.js";

package/dist/primitives.native.js

@@ -40,3 +40,5 @@ export { FilePicker } from "./filepicker.native.js";
 // expo-linear-gradient (pinned unconditionally in every export); the web build
 // (./gradient.js) paints the equivalent CSS `linear-gradient`.
 export { Gradient } from "./gradient.native.js";
+// sc-10268 — `<Video>` (native): expo-video's VideoView.
+export { Video } from "./video.native.js";

package/dist/video.js

@@ -0,0 +1,51 @@
+// sc-10268 — `<Video>` (web).
+//
+// Plays a video file inline: the browser's own <video> element with its own
+// controls. The native counterpart (./video.native.js) is expo-video's
+// VideoView over the same props, so a widget plays video on both hosts with
+// no platform split.
+//
+// `preload="metadata"` plus a `#t=` fragment paints the first frame as the
+// thumbnail; Safari draws nothing before playback without the fragment.
+
+import React from "react";
+import * as ReactNative from "react-native-web";
+
+const FIRST_FRAME = "#t=0.001";
+const FITS = { contain: "contain", cover: "cover" };
+
+export function Video({
+  source,
+  controls = true,
+  autoPlay = false,
+  contentFit = "contain",
+  style,
+  accessibilityLabel,
+  testID,
+  onError,
+}) {
+  const uri = typeof source === "string" && source ? source : null;
+  return React.createElement(
+    ReactNative.View,
+    { style, testID },
+    uri
+      ? React.createElement("video", {
+          src: uri.includes("#") ? uri : `${uri}${FIRST_FRAME}`,
+          controls: Boolean(controls),
+          // Browsers only autoplay muted video.
+          autoPlay: Boolean(autoPlay),
+          muted: Boolean(autoPlay),
+          playsInline: true,
+          preload: "metadata",
+          "aria-label": accessibilityLabel,
+          onError: onError ? () => onError() : undefined,
+          style: {
+            width: "100%",
+            height: "100%",
+            objectFit: FITS[contentFit] || FITS.contain,
+            display: "block",
+          },
+        })
+      : null,
+  );
+}

package/dist/video.native.js

@@ -0,0 +1,61 @@
+// sc-10268 — `<Video>` (native).
+//
+// expo-video's VideoView (AVPlayer on iOS, ExoPlayer on Android), pinned in
+// every export (BASE_DEPENDENCIES in
+// backend/src/core/services/export-dependencies.ts), so Metro always resolves
+// it. The web counterpart (./video.js) is the browser's <video> over the same
+// props; keep the two in lockstep.
+
+import React, { useEffect } from "react";
+import { View, StyleSheet } from "react-native";
+import { VideoView, useVideoPlayer } from "expo-video";
+
+const FITS = { contain: "contain", cover: "cover" };
+
+export function Video({
+  source,
+  controls = true,
+  autoPlay = false,
+  contentFit = "contain",
+  style,
+  accessibilityLabel,
+  testID,
+  onError,
+}) {
+  const uri = typeof source === "string" && source ? source : null;
+  // A bare string keeps the source stable, so the player is not recreated
+  // every render; null is an idle player.
+  const player = useVideoPlayer(uri);
+  // An effect rather than the setup callback, so turning autoPlay on later
+  // still starts it. Muted, as the web host must be to autoplay.
+  useEffect(() => {
+    if (!uri || !autoPlay) return;
+    try {
+      player.muted = true;
+      player.play();
+    } catch (_) {
+      // A released player has nothing to start.
+    }
+  }, [player, uri, autoPlay]);
+  useEffect(() => {
+    if (!onError) return undefined;
+    const subscription = player.addListener("statusChange", (event) => {
+      if (event && event.status === "error") onError();
+    });
+    return () => subscription.remove();
+  }, [player, onError]);
+  return React.createElement(
+    View,
+    { style, testID },
+    uri
+      ? React.createElement(VideoView, {
+          player,
+          nativeControls: Boolean(controls),
+          contentFit: FITS[contentFit] || FITS.contain,
+          allowsFullscreen: true,
+          accessibilityLabel,
+          style: StyleSheet.absoluteFill,
+        })
+      : null,
+  );
+}