@colixsystems/widget-sdk 0.218.0 → 0.219.1

package/dist/hooks.js

@@ -392,14 +392,15 @@ export function useUserPhoto() {
 }
 
 /**
- * Returns `true` when the host has sized this widget to fill the available
- * height of its layout slot — today that means a page-grid tile whose author
- * chose "Fill tile height" (or a widget type that fills by default, like
- * containers and media). When `true`, a widget that has a meaningful filled
- * form (Image, Chart, Map, Video, …) should switch from its intrinsic height
- * to a stretch style (`flex: 1` / `height: "100%"`); widgets with no useful
- * filled form may ignore it. Defaults to `false` everywhere the host has not
- * opted the widget into filling, so calling it is always safe.
+ * Returns `true` when the host has sized this widget to fill a box of
+ * definite height — a widget in the section a fit-to-screen page stretches to
+ * the bottom of the screen, or a widget given a fixed slot height. When
+ * `true`, a widget that has a meaningful filled form (Image, Chart, Map,
+ * Video, a chat or feed that scrolls its own content, …) should switch from
+ * its intrinsic height to a stretch style (`flex: 1` / `height: "100%"`) and
+ * scroll inside it; widgets with no useful filled form may ignore it.
+ * Defaults to `false` everywhere the host has not opted the widget into
+ * filling, so calling it is always safe.
  *
  * The SAME value is injected by the web Player host and the native export
  * host (widget-parity skill), so a widget's fill behaviour is identical on both
@@ -3775,7 +3776,7 @@ export class PermissionError extends Error {
   }
 }
 
-function toPermissionError(err) {
+export function toPermissionError(err) {
   // See the note in toDatastoreError — a client rejection is read from the
   // envelope below rather than matching this instanceof.
   if (err instanceof PermissionError) return err;
@@ -5172,149 +5173,6 @@ export function useFilestoreDelete() {
   return { remove, removing, error };
 }
 
-/**
- * Drive a BankID signing flow for one Filestore file. Returns
- * `{ status, qr, autoStartToken, message, signerName, signedAt, verdict,
- * loading, error, initiate, refresh, cancel, verify }`.
- *
- * `initiate()` opens a sign order against the file (the backend hashes its
- * bytes SERVER-SIDE and binds the digest into the BankID signature); `refresh()`
- * polls the order (surfacing a fresh animated-QR frame while pending — render
- * it with the `Image` primitive); `cancel()` aborts it; `verify()` re-runs the
- * offline verification and returns the verdict (`{ valid, content_status, … }`).
- * Reads `ctx.filestore.signatures.{initiate,status,cancel,verify}`. When
- * `fileId` is null/empty the hook collapses to a no-op.
- *
- * Pass `existingSignatureId` for a file that is ALREADY signed: the hook seeds
- * that order id (status `complete`) so the widget can show the signed state and
- * `verify()` it WITHOUT opening a new order — re-signing then requires an
- * explicit `initiate()`.
- */
-export function useFileSignature(fileId, existingSignatureId = null) {
-  const ctx = useWidgetContextOrThrow("useFileSignature");
-  if (!ctx.filestore || !ctx.filestore.signatures) {
-    throw new Error(
-      "useFileSignature: host did not inject a filestore client (ctx.filestore.signatures)",
-    );
-  }
-  const ready = Boolean(fileId);
-  const sigRef = useRef(ctx.filestore.signatures);
-  sigRef.current = ctx.filestore.signatures;
-  const fileIdRef = useRef(fileId);
-  fileIdRef.current = fileId;
-  // Seed the order from an already-completed signature so verify() works
-  // without initiating; initiate() (an explicit re-sign) overwrites it.
-  const orderRef = useRef(existingSignatureId || null);
-
-  const [status, setStatus] = useState(existingSignatureId ? "complete" : null);
-  const [qr, setQr] = useState(null);
-  const [autoStartToken, setAutoStartToken] = useState(null);
-  const [message, setMessage] = useState(null);
-  const [signerName, setSignerName] = useState(null);
-  const [signedAt, setSignedAt] = useState(null);
-  const [verdict, setVerdict] = useState(null);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState(null);
-
-  const initiate = useCallback(async () => {
-    if (!fileIdRef.current) return null;
-    setLoading(true);
-    setError(null);
-    setVerdict(null);
-    try {
-      const res = await sigRef.current.initiate(fileIdRef.current);
-      orderRef.current = res && res.signature_id ? res.signature_id : null;
-      setStatus(res && res.status ? res.status : "pending");
-      setQr(res && res.qr ? res.qr : null);
-      setAutoStartToken(res && res.auto_start_token ? res.auto_start_token : null);
-      setSignerName(null);
-      setSignedAt(null);
-      setMessage(null);
-      setLoading(false);
-      return res;
-    } catch (err) {
-      setError(toPermissionError(err));
-      setLoading(false);
-      throw toPermissionError(err);
-    }
-  }, []);
-
-  const refresh = useCallback(async () => {
-    const id = orderRef.current;
-    if (!id) return;
-    try {
-      const res = await sigRef.current.status(id);
-      if (res) {
-        if (res.status != null) setStatus(res.status);
-        if (res.qr !== undefined) setQr(res.qr || null);
-        if (res.message !== undefined) setMessage(res.message || null);
-        if (res.signer_name !== undefined) setSignerName(res.signer_name || null);
-        if (res.signed_at !== undefined) setSignedAt(res.signed_at || null);
-      }
-    } catch (err) {
-      setError(toPermissionError(err));
-    }
-  }, []);
-
-  const cancel = useCallback(async () => {
-    const id = orderRef.current;
-    if (!id) return;
-    try {
-      await sigRef.current.cancel(id);
-      setStatus("cancelled");
-      setQr(null);
-    } catch (err) {
-      throw toPermissionError(err);
-    }
-  }, []);
-
-  const verify = useCallback(async () => {
-    const id = orderRef.current;
-    if (!id) return null;
-    try {
-      const v = await sigRef.current.verify(id);
-      setVerdict(v);
-      return v;
-    } catch (err) {
-      setError(toPermissionError(err));
-      throw toPermissionError(err);
-    }
-  }, []);
-
-  if (!ready) {
-    return {
-      status: null,
-      qr: null,
-      autoStartToken: null,
-      message: null,
-      signerName: null,
-      signedAt: null,
-      verdict: null,
-      loading: false,
-      error: null,
-      initiate: async () => null,
-      refresh: async () => undefined,
-      cancel: async () => undefined,
-      verify: async () => null,
-    };
-  }
-  return {
-    status,
-    qr,
-    autoStartToken,
-    message,
-    signerName,
-    signedAt,
-    verdict,
-    loading,
-    error,
-    initiate,
-    refresh,
-    cancel,
-    verify,
-  };
-}
-
 /**
  * Batch "is this file signed?" lookup for a set of file ids. Returns
  * `{ signaturesByFileId, loading, error, refetch }` where `signaturesByFileId`

package/dist/index.d.ts

@@ -728,8 +728,8 @@ export interface WidgetContext<TProps = unknown> {
   };
   /**
    * REQ-LAY-08 — optional host layout hint backing `useFill()`. `true` when
-   * the host sized this widget to fill its layout slot's available height (a
-   * page-grid tile set to "Fill tile height", or a default-fill widget type).
+   * the host sized this widget to fill a box of definite height (a
+   * fit-to-screen page's stretched section, or a fixed slot height).
    * Absent / `false` everywhere the host has not opted the widget into filling.
    */
   fill?: boolean;
@@ -1948,11 +1948,13 @@ export interface UserPhotoApi {
 export function useUserPhoto(): UserPhotoApi;
 
 /**
- * REQ-LAY-08 — returns `true` when the host has sized this widget to fill its
- * layout slot's available height (a page-grid tile set to "Fill tile height",
- * or a default-fill widget type — containers + media). Widgets that can
- * stretch (Image, Chart, Map, Video, …) should switch to a fill style
- * (`flex: 1` / `height: "100%"`) when this is `true`; others may ignore it.
+ * REQ-LAY-08 — returns `true` when the host has sized this widget to fill a
+ * box of definite height (a widget in the section a fit-to-screen page
+ * stretches to the bottom of the screen, or one given a fixed slot height).
+ * Widgets that can stretch (Image, Chart, Map, Video, a chat or feed that
+ * scrolls itself, …) should switch to a fill style (`flex: 1` /
+ * `height: "100%"`) and scroll inside it when this is `true`; others may
+ * ignore it.
  * Defaults to `false`, so calling it is always safe, and the same value is
  * injected on web and native so fill behaviour is identical on both platforms.
  */
@@ -4567,3 +4569,237 @@ export function pressableLift(state?: {
 export function styleGroup(
   name: string,
 ): { dataSet: Record<string, string> } | undefined;
+
+/* ---------------------------------------------------------------------------
+ * Signing files with BankID, and signing rounds. All read `ctx.filestore`.
+ * Rows are snake_case verbatim.
+ * ------------------------------------------------------------------------- */
+
+/** Why a name cannot be shown on a signed document; `characters` lists what cannot be shown. */
+export interface SignatureNameRefusal {
+  reason: "empty" | "too_long" | "unsupported_characters" | "mixed_scripts";
+  characters: string[];
+}
+
+/** What a sign order answers when started, polled or cancelled. */
+export interface FileSignOrderAnswer {
+  status: "pending" | "complete" | "failed" | "cancelled";
+  signature_id?: string;
+  qr?: string | null;
+  auto_start_token?: string | null;
+  hint_code?: string | null;
+  message?: string;
+  signer_name?: string | null;
+  signed_at?: string | null;
+  name_refusal?: SignatureNameRefusal;
+}
+
+export interface FileSignatureVerdict {
+  valid: boolean;
+  checks: Record<string, boolean>;
+  reason: string | null;
+  signer_name: string | null;
+  personal_number: string | null;
+  signed_at: string | null;
+  content_status: "unchanged" | "changed" | "unavailable";
+  signed_by_others_since: number | null;
+  seal: Record<string, unknown>;
+}
+
+/**
+ * Drive a BankID signing flow for one file. Pass `existingSignatureId` for a
+ * file the user has already signed to show that state and `verify()` it
+ * without opening a new order. A null `fileId` makes every action a no-op.
+ */
+export function useFileSignature(
+  fileId: string | null | undefined,
+  existingSignatureId?: string | null,
+): {
+  status: "pending" | "complete" | "failed" | "cancelled" | null;
+  /** PNG data-URL of the animated BankID QR code while there is one to scan. */
+  qr: string | null;
+  /** Opens BankID on this device; null once the user has signed or the order has ended. */
+  autoStartToken: string | null;
+  message: string | null;
+  signerName: string | null;
+  signedAt: string | null;
+  /** Where the order stands. "sealing": signed, and being added to the document. */
+  hintCode: string | null;
+  /** Set when the order failed because the signer's name cannot be shown. */
+  nameRefusal: SignatureNameRefusal | null;
+  verdict: FileSignatureVerdict | null;
+  loading: boolean;
+  error: PermissionError | null;
+  initiate(): Promise<FileSignOrderAnswer | null>;
+  refresh(): Promise<void>;
+  /** Resolves to what became of the order, which is not always "cancelled". */
+  cancel(): Promise<FileSignOrderAnswer | undefined>;
+  verify(): Promise<FileSignatureVerdict | null>;
+};
+
+export interface FileSignatureSummary {
+  signature_id: string;
+  subject_file_id: string;
+  signer_name: string | null;
+  signed_at: string | null;
+}
+
+/** The signed-in user's own latest signature per file they have signed; other files are absent. */
+export function useFileSignatures(fileIds: string[] | null | undefined): {
+  signaturesByFileId: Record<string, FileSignatureSummary>;
+  loading: boolean;
+  error: Error | null;
+  refetch(): Promise<void>;
+};
+
+export interface FileRosterEntry {
+  app_user_id: string;
+  name: string;
+  signed: boolean;
+  signature_id: string | null;
+  signer_name: string | null;
+  signed_at: string | null;
+}
+
+/**
+ * Who is expected to sign a file, for someone who manages the file's folder:
+ * everyone who can open the folder, or the signers of the file's signing round
+ * in the order of their places on the signature page. `error` is set for a user who does not manage the folder.
+ */
+export function useFileRoster(
+  fileId: string | null | undefined,
+  options?: { limit?: number; offset?: number; enabled?: boolean },
+): {
+  roster: FileRosterEntry[];
+  total: number;
+  signedCount: number;
+  loading: boolean;
+  error: Error | null;
+  refetch(): Promise<void>;
+};
+
+/** One entry of a refused signing-round action: which signer, and why. */
+export interface SigningRefusalEntry {
+  field?: string;
+  message: string;
+  code?: string;
+  app_user_id?: string;
+  reason?: SignatureNameRefusal["reason"];
+  characters?: string[];
+}
+
+/** A refusal: the server's `code` and `message`, the refused signers, and the seconds to wait. */
+export type SigningRoundError = PermissionError & {
+  errors: SigningRefusalEntry[];
+  retryAfter: number | null;
+};
+
+export interface SigningRoundPlace {
+  position: number;
+  signed: boolean;
+  signed_at: string | null;
+}
+
+export interface SigningRoundSummary {
+  id: string;
+  status: "DRAFT" | "OPEN" | "COMPLETED";
+  signer_count: number;
+  /** For someone who manages the folder; null for a signer. */
+  signed_count: number | null;
+  /** The user's own place when they are one of the signers. */
+  my_place: SigningRoundPlace | null;
+  /** The round is open and the user's place is unsigned. Signers sign in any order. */
+  can_sign: boolean;
+}
+
+export interface FileSigningOverview {
+  file_id: string;
+  can_manage: boolean;
+  /**
+   * The user manages the folder, the file is a shared PDF and has no round.
+   * About the file and the user only: offer "prepare" when this AND
+   * `roundsEnabled` are true. Preparing can still be refused.
+   */
+  can_prepare: boolean;
+  /** Null without a round, and for a user who is neither a manager nor one of its signers. */
+  round: SigningRoundSummary | null;
+  /** "signing_round": the file cannot be changed. "signed": its content cannot be replaced. */
+  locked: "signing_round" | "signed" | null;
+}
+
+/**
+ * What the signed-in user may know about the signing round of each file, in
+ * one batched read. A file the user cannot see has no entry. `roundsEnabled`
+ * is false when the workspace cannot start signing rounds, null until known.
+ */
+export function useSigningRounds(fileIds: string[] | null | undefined): {
+  byFileId: Record<string, FileSigningOverview>;
+  roundsEnabled: boolean | null;
+  loading: boolean;
+  error: SigningRoundError | null;
+  refresh(): Promise<void>;
+};
+
+export interface SigningRoundSigner {
+  name: string;
+  position: number;
+  /** Present for every place when the user manages the folder; otherwise for their own place only. */
+  app_user_id?: string;
+  signed?: boolean;
+  signed_at?: string | null;
+  /** The name BankID verified on this place. Managers only. */
+  signed_as?: string | null;
+}
+
+export interface SigningRound {
+  id: string;
+  file_id: string;
+  status: "DRAFT" | "OPEN" | "COMPLETED" | "CANCELLED";
+  prepared_size_bytes: number;
+  original_version: number | null;
+  created_by_id?: string | null;
+  created_at: string;
+  updated_at: string;
+  confirmed_at: string | null;
+  completed_at: string | null;
+  cancelled_at: string | null;
+  /** When an unconfirmed draft stops being usable; null once confirmed. */
+  expires_at: string | null;
+  signers: SigningRoundSigner[];
+}
+
+export interface SigningRoundPreparedFile {
+  url: string;
+  sha256: string;
+  expires_at: string;
+  size_bytes: number;
+}
+
+/**
+ * One file's current signing round and the actions of someone who manages the
+ * file's folder. `confirm()` opens the round for the document `preparedFile()`
+ * last returned and rejects with code `PREVIEW_REQUIRED` without it. A refused
+ * action sets `error` and rejects with it; code `SIGNING_ROUNDS_NOT_ENABLED`
+ * means the workspace cannot start signing rounds.
+ *
+ * One action runs at a time: while `busy` is true another one rejects at once
+ * with code `ACTION_IN_PROGRESS` and is not queued. `round` is never a
+ * cancelled round; `cancel()` resolves to the round it ended. When `fileId`
+ * or the signed-in user changes, `round` is null and `loading` true until the
+ * new answer arrives.
+ */
+export function useSigningRound(fileId: string | null | undefined): {
+  round: SigningRound | null;
+  loading: boolean;
+  error: SigningRoundError | null;
+  refresh(): Promise<void>;
+  /** `signerIds` in the order their places appear on the signature page. Resolves to the DRAFT. */
+  prepare(signerIds: string[]): Promise<SigningRound>;
+  preparedFile(): Promise<SigningRoundPreparedFile>;
+  /** Resolves to the OPEN round. */
+  confirm(): Promise<SigningRound>;
+  /** Resolves to the round it ended, with status "CANCELLED". */
+  cancel(): Promise<SigningRound>;
+  /** An action is running; another one is refused with `ACTION_IN_PROGRESS`. */
+  busy: boolean;
+};

package/dist/index.js

@@ -48,7 +48,6 @@ export {
   useFilestoreCreateFolder,
   useFilestoreCopy,
   useFilestoreDelete,
-  useFileSignature,
   useFileSignatures,
   useFileRoster,
   useFolderPermissions,
@@ -131,6 +130,7 @@ export {
   useInactiveUsers,
 } from "./stats-hooks.js";
 // sc-11025 — one source, bound to how each platform says the app is in front.
+export { useFileSignature, useSigningRounds, useSigningRound } from "./signing-hooks.js";
 export { useOnlineMembers, useOnlineVisibility } from "./presence.js";
 // sc-6607 — `<Overlay>` is one shared component (./overlay-view.js) bound to
 // each platform's primitives, so a widget's modal escapes its container box

package/dist/index.native.js

@@ -48,7 +48,6 @@ export {
   useFilestoreCreateFolder,
   useFilestoreCopy,
   useFilestoreDelete,
-  useFileSignature,
   useFileSignatures,
   useFileRoster,
   useFolderPermissions,
@@ -129,6 +128,7 @@ export {
   useInactiveUsers,
 } from "./stats-hooks.js";
 // sc-11025 — see the note on the web mirror in ./index.js.
+export { useFileSignature, useSigningRounds, useSigningRound } from "./signing-hooks.js";
 export { useOnlineMembers, useOnlineVisibility } from "./presence.native.js";
 // sc-6607 — see the note on the web mirror in ./index.js.
 export { Overlay } from "./overlay.native.js";