@colixsystems/widget-sdk 0.244.0 → 0.246.0

package/dist/file-image-logic.js

@@ -0,0 +1,162 @@
+// The pure rules behind `<FileImage>` and `<Avatar fileId>`: which rung of a
+// stored file's size ladder to load, how the box is shaped, and the load state
+// machine that retries an expired signed URL once. Renderer-free, so the node
+// suite can pin every decision.
+
+export const FILE_IMAGE_VARIANTS = Object.freeze(["thumbnail", "card", "large", "hero", "original"]);
+export const DEFAULT_FILE_IMAGE_VARIANT = "large";
+export const FILE_IMAGE_FALLBACKS = Object.freeze(["icon", "blank"]);
+export const FILE_IMAGE_RESIZE_MODES = Object.freeze(["cover", "contain", "stretch", "center"]);
+export const DEFAULT_FILE_IMAGE_ASPECT_RATIO = 4 / 3;
+export const FILE_IMAGE_RETRIES = 1;
+export const FILE_IMAGE_ICON_MAX = 24;
+
+const ASPECT_RATIO_BOUNDS = Object.freeze({ min: 0.1, max: 10 });
+const ICON_MIN = 12;
+const ICON_SHARE = 0.6;
+// The thumbnail rung's edge; an avatar this small at 2x density fits in it.
+const THUMBNAIL_EDGE_PX = 128;
+
+function clamp(n, { min, max }) {
+  return Math.min(max, Math.max(min, n));
+}
+
+function usableUrl(value) {
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+
+function positive(n) {
+  return typeof n === "number" && Number.isFinite(n) && n > 0;
+}
+
+export function normaliseFileImageVariant(variant) {
+  return FILE_IMAGE_VARIANTS.includes(variant) ? variant : DEFAULT_FILE_IMAGE_VARIANT;
+}
+
+export function normaliseFileImageFallback(fallback) {
+  return FILE_IMAGE_FALLBACKS.includes(fallback) ? fallback : "icon";
+}
+
+export function normaliseFileImageResizeMode(mode) {
+  return FILE_IMAGE_RESIZE_MODES.includes(mode) ? mode : "cover";
+}
+
+/**
+ * The URL a variant loads: its rung of the size ladder, else the original
+ * (a file projected before the ladder shipped has no `urls`).
+ *
+ * @param {{ thumbnail?: string, card?: string, large?: string, hero?: string } | null} urls
+ * @param {string | null} url — the original's signed URL.
+ * @param {string} variant
+ */
+export function pickFileImageUrl(urls, url, variant) {
+  const kind = normaliseFileImageVariant(variant);
+  const rung = kind !== "original" && urls && typeof urls === "object" ? usableUrl(urls[kind]) : null;
+  return rung || usableUrl(url);
+}
+
+/** The rung an avatar of `px` loads: enough pixels for a 2x screen. */
+export function avatarFileVariant(px) {
+  return positive(px) && px * 2 <= THUMBNAIL_EDGE_PX ? "thumbnail" : "card";
+}
+
+/**
+ * The box's width / height: the caller's, else the loaded picture's own, else
+ * a photo's 4:3 until it arrives. Clamped, so a bad value never reaches a
+ * native style.
+ *
+ * @param {number | undefined} aspectRatio
+ * @param {{ width: number, height: number } | null} intrinsic
+ */
+export function fileImageAspectRatio(aspectRatio, intrinsic) {
+  if (positive(aspectRatio)) return clamp(aspectRatio, ASPECT_RATIO_BOUNDS);
+  if (intrinsic && positive(intrinsic.width) && positive(intrinsic.height)) {
+    return clamp(intrinsic.width / intrinsic.height, ASPECT_RATIO_BOUNDS);
+  }
+  return DEFAULT_FILE_IMAGE_ASPECT_RATIO;
+}
+
+/** A caller who sets the height (or a flex share) sizes the box themselves. */
+export function callerSizesHeight(style) {
+  return Boolean(style) && (style.height != null || style.flex != null || style.aspectRatio != null);
+}
+
+/**
+ * The corner radius: px, a theme radius name, or the theme's `md`.
+ *
+ * @param {number | string | undefined} radius
+ * @param {Record<string, number>} radii — the theme's radii.
+ */
+export function fileImageRadius(radius, radii) {
+  if (typeof radius === "number" && Number.isFinite(radius)) return Math.max(0, radius);
+  if (radius === "none") return 0;
+  if (typeof radius === "string" && radii && Object.hasOwn(radii, radius)) return radii[radius];
+  return radii && Number.isFinite(radii.md) ? radii.md : 0;
+}
+
+/**
+ * The loaded picture's pixel size, from either host's load event: React Native
+ * reports `nativeEvent.source`, the web the decoded element's natural size.
+ */
+export function intrinsicSizeOf(event) {
+  const native = event && event.nativeEvent;
+  if (!native) return null;
+  const source = native.source;
+  if (source && positive(source.width) && positive(source.height)) {
+    return { width: source.width, height: source.height };
+  }
+  const element = native.target;
+  if (element && positive(element.naturalWidth) && positive(element.naturalHeight)) {
+    return { width: element.naturalWidth, height: element.naturalHeight };
+  }
+  return null;
+}
+
+/** The fallback glyph: a share of the box, never more than 24 px. */
+export function fileImageIconSize(layout) {
+  if (!layout || !positive(layout.width) || !positive(layout.height)) return FILE_IMAGE_ICON_MAX;
+  const share = Math.round(Math.min(layout.width, layout.height) * ICON_SHARE);
+  return clamp(share, { min: ICON_MIN, max: FILE_IMAGE_ICON_MAX });
+}
+
+/** A picture that has not loaded yet. */
+export function initialImageLoad() {
+  return { phase: "loading", attempt: 0, size: null };
+}
+
+/**
+ * The load state machine. `error` retries through `refetch` once when the
+ * source can mint a fresh signed URL (`canRetry`), then gives up; `refetched`
+ * reloads with whatever URL the refetch produced.
+ *
+ * @param {{ phase: "loading"|"loaded"|"retrying"|"failed", attempt: number, size: object|null }} state
+ * @param {{ type: "load", size?: object|null } | { type: "error", canRetry: boolean } | { type: "refetched" }} event
+ */
+export function nextImageLoad(state, event) {
+  switch (event && event.type) {
+    case "load":
+      return { ...state, phase: "loaded", size: event.size || state.size };
+    case "error":
+      if (state.phase === "failed" || state.phase === "retrying") return state;
+      return event.canRetry && state.attempt < FILE_IMAGE_RETRIES
+        ? { ...state, phase: "retrying", attempt: state.attempt + 1 }
+        : { ...state, phase: "failed" };
+    case "refetched":
+      return state.phase === "retrying" ? { ...state, phase: "loading" } : state;
+    default:
+      return state;
+  }
+}
+
+/**
+ * What the box shows: `resolving` (a placeholder, no URL yet), `loading` (the
+ * picture loading under the placeholder), `loaded`, or `failed` (the fallback).
+ *
+ * @param {{ uri: string|null, resolving: boolean, phase: string }} input
+ */
+export function fileImageStatus({ uri, resolving, phase }) {
+  if (phase === "failed") return "failed";
+  if (phase === "retrying") return "resolving";
+  if (!uri) return resolving ? "resolving" : "failed";
+  return phase === "loaded" ? "loaded" : "loading";
+}

package/dist/file-image-source.js

@@ -0,0 +1,71 @@
+// The ONE loading path behind `<FileImage>` and `<Avatar fileId>`: resolve the
+// picture's URL, track its load, and retry an expired signed URL once through
+// `useFilestoreFile`'s own `refetch`, never a second fetch of our own.
+//
+// The caller keys the component on the file id (or URL), so a new source
+// starts from a fresh load state.
+
+import React from "react";
+import { useFilestoreFile } from "./hooks.js";
+import {
+  fileImageStatus,
+  initialImageLoad,
+  intrinsicSizeOf,
+  nextImageLoad,
+  pickFileImageUrl,
+} from "./file-image-logic.js";
+
+function useImageLoad({ uri, resolving, refetch }) {
+  const [load, setLoad] = React.useState(initialImageLoad);
+  const loadRef = React.useRef(load);
+  loadRef.current = load;
+  const refetchRef = React.useRef(refetch);
+  refetchRef.current = refetch;
+  const mountedRef = React.useRef(true);
+  React.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  // Stable handlers: the web Image restarts its request when they change.
+  const onLoad = React.useCallback((event) => {
+    setLoad((state) => nextImageLoad(state, { type: "load", size: intrinsicSizeOf(event) }));
+  }, []);
+  const onError = React.useCallback(() => {
+    const retry = refetchRef.current;
+    const next = nextImageLoad(loadRef.current, { type: "error", canRetry: typeof retry === "function" });
+    loadRef.current = next;
+    setLoad(next);
+    if (next.phase !== "retrying") return;
+    const settle = () => {
+      if (mountedRef.current) setLoad((state) => nextImageLoad(state, { type: "refetched" }));
+    };
+    Promise.resolve(retry()).then(settle, settle);
+  }, []);
+
+  return {
+    uri,
+    status: fileImageStatus({ uri, resolving, phase: load.phase }),
+    attempt: load.attempt,
+    size: load.size,
+    onLoad,
+    onError,
+  };
+}
+
+/**
+ * A stored file's picture at `variant`'s rung of the size ladder.
+ *
+ * @returns {{ uri: string|null, status: "resolving"|"loading"|"loaded"|"failed", attempt: number, size: object|null, onLoad: Function, onError: Function }}
+ */
+export function useStoredFileImage(fileId, variant) {
+  const { url, urls, loading, refetch } = useFilestoreFile(fileId || null);
+  return useImageLoad({ uri: pickFileImageUrl(urls, url, variant), resolving: loading, refetch });
+}
+
+/** A picture at a URL the caller already has; nothing to refetch. */
+export function useLinkedImage(uri) {
+  return useImageLoad({ uri: pickFileImageUrl(null, uri, "original"), resolving: false, refetch: null });
+}

package/dist/file-image-view.js

@@ -0,0 +1,119 @@
+// The ONE implementation behind `<FileImage>`: a stored file's (or a URL's)
+// picture with a themed placeholder while it loads and a fallback, never a
+// broken image, when it cannot. The bindings (`file-image.js` /
+// `file-image.native.js`) differ only in their primitives.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { Icon } from "./icon.js";
+import { flattenStyle } from "./flatten-style.js";
+import { useLinkedImage, useStoredFileImage } from "./file-image-source.js";
+import {
+  callerSizesHeight,
+  fileImageAspectRatio,
+  fileImageIconSize,
+  fileImageRadius,
+  normaliseFileImageFallback,
+  normaliseFileImageResizeMode,
+} from "./file-image-logic.js";
+
+const h = React.createElement;
+const FILL = { position: "absolute", top: 0, right: 0, bottom: 0, left: 0 };
+const CENTRED = { alignItems: "center", justifyContent: "center" };
+const HIDDEN = { "aria-hidden": true, importantForAccessibility: "no-hide-descendants" };
+
+function suffixed(testID, part) {
+  return testID ? `${testID}-${part}` : undefined;
+}
+
+/**
+ * Bind `<FileImage>` to one platform's primitives and that host's Skeleton.
+ *
+ * @param {{View: any, Image: any}} rn
+ * @param {any} Skeleton
+ */
+export function makeFileImage(rn, Skeleton) {
+  const { View, Image } = rn;
+
+  function Fallback({ kind, colors, label, testID }) {
+    const [layout, setLayout] = React.useState(null);
+    const onLayout = React.useCallback((event) => setLayout(event.nativeEvent.layout), []);
+    const named = label ? { accessible: true, accessibilityRole: "image", accessibilityLabel: label } : HIDDEN;
+    return h(
+      View,
+      { ...named, onLayout, style: [FILL, CENTRED, { backgroundColor: colors.surfaceMuted }], testID },
+      kind === "icon" ? h(Icon, { name: "image", size: fileImageIconSize(layout), color: colors.onSurfaceMuted }) : null,
+    );
+  }
+
+  function Picture({ image, props }) {
+    const { accessibilityLabel, aspectRatio, fallback, radius, resizeMode, style, testID } = props;
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const own = flattenStyle(style);
+    const corner = fileImageRadius(radius, theme.radii);
+    const box = {
+      width: "100%",
+      overflow: "hidden",
+      borderRadius: corner,
+      ...(callerSizesHeight(own) ? null : { aspectRatio: fileImageAspectRatio(aspectRatio, image.size) }),
+    };
+    const label = typeof accessibilityLabel === "string" ? accessibilityLabel : "";
+    const { status } = image;
+    return h(
+      View,
+      { style: [box, style], testID },
+      status === "loading" || status === "loaded"
+        ? h(Image, {
+            key: image.attempt,
+            source: { uri: image.uri },
+            resizeMode: normaliseFileImageResizeMode(resizeMode),
+            // The placeholder carries the name until the picture has loaded.
+            accessibilityLabel: (status === "loaded" && label) || undefined,
+            onLoad: image.onLoad,
+            onError: image.onError,
+            style: FILL,
+            testID: suffixed(testID, "image"),
+          })
+        : null,
+      status === "resolving" || status === "loading"
+        ? h(Skeleton, {
+            shape: "block",
+            width: "100%",
+            height: "100%",
+            radius: corner,
+            accessibilityLabel: label || undefined,
+            style: FILL,
+            testID: suffixed(testID, "loading"),
+          })
+        : null,
+      status === "failed"
+        ? h(Fallback, {
+            kind: normaliseFileImageFallback(fallback),
+            colors: theme.colors,
+            label,
+            testID: suffixed(testID, "fallback"),
+          })
+        : null,
+    );
+  }
+
+  function StoredPicture({ props }) {
+    return h(Picture, { image: useStoredFileImage(props.fileId, props.variant), props });
+  }
+
+  function LinkedPicture({ props }) {
+    return h(Picture, { image: useLinkedImage(props.uri), props });
+  }
+
+  function FileImage(props) {
+    const { fileId, uri } = props;
+    if (typeof fileId === "string" && fileId !== "") {
+      return h(StoredPicture, { key: `file:${fileId}`, props });
+    }
+    return h(LinkedPicture, { key: `uri:${uri || ""}`, props });
+  }
+  FileImage.displayName = "FileImage";
+
+  return { FileImage };
+}

package/dist/file-image.js

@@ -0,0 +1,8 @@
+// `<FileImage>` (web). Binds ./file-image-view.js to react-native-web and the
+// web `<Skeleton>`; see ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { Skeleton } from "./loading.js";
+import { makeFileImage } from "./file-image-view.js";
+
+export const { FileImage } = makeFileImage({ View: ReactNative.View, Image: ReactNative.Image }, Skeleton);

package/dist/file-image.native.js

@@ -0,0 +1,8 @@
+// `<FileImage>` (native). Binds ./file-image-view.js to React Native and the
+// native `<Skeleton>`; only the imports differ from ./file-image.js.
+
+import { View, Image } from "react-native";
+import { Skeleton } from "./loading.native.js";
+import { makeFileImage } from "./file-image-view.js";
+
+export const { FileImage } = makeFileImage({ View, Image }, Skeleton);

package/dist/form-control-logic.js

@@ -2,6 +2,8 @@
 // named, when the frame is needed, and the keys a non-button role answers.
 // No renderer here, so the node suite can test them and both hosts share them.
 
+import { nextOptionIndex } from "./form-control-tokens.js";
+
 export function isShown(value) {
   return value !== undefined && value !== null && value !== false && value !== "";
 }
@@ -53,3 +55,24 @@ export function spaceActivates(onPress) {
     if (!event.repeat) onPress();
   };
 }
+
+const OPTION_NAVIGATION_KEYS = ["ArrowDown", "ArrowUp", "Home", "End"];
+
+/**
+ * The keys one row of an option list answers (a `<Select>` option, a `<Menu>`
+ * item): arrows, Home and End move focus past disabled rows, Space activates.
+ *
+ * @param {{options: Array<{disabled?: boolean}>, index: number,
+ *   focusAt: (index: number) => void, activate: () => void}} row
+ */
+export function optionKeyDown({ options, index, focusAt, activate }) {
+  const space = spaceActivates(activate);
+  return (event) => {
+    if (OPTION_NAVIGATION_KEYS.includes(event.key)) {
+      event.preventDefault();
+      focusAt(nextOptionIndex(options, index, event.key));
+      return;
+    }
+    space(event);
+  };
+}

package/dist/form-control-tokens.js

@@ -6,6 +6,7 @@
 
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { resolveTextFieldTokens } from "./text-field-tokens.js";
+import { resolvePopoverTokens } from "./popover-tokens.js";
 
 // The smallest target a finger can hit reliably, as the field's own floor.
 export const CONTROL_MIN_TARGET = 44;
@@ -15,10 +16,6 @@ export const HALO_WIDTH = 2;
 export const HALO_GAP = 2;
 export const DISABLED_OPACITY = 0.5;
 
-function isSet(value) {
-  return value !== undefined && value !== null && value !== "";
-}
-
 /**
  * Resolve one form control from the workspace theme.
  *
@@ -30,7 +27,6 @@ export function resolveFormControlTokens(theme, overrides) {
   const colors = base.colors || DEFAULT_THEME_TOKENS.colors;
   const spacing = base.spacing || DEFAULT_THEME_TOKENS.spacing;
   const typography = base.typography || DEFAULT_THEME_TOKENS.typography;
-  const popover = (base.components && base.components.popover) || {};
   const field = resolveTextFieldTokens(base, overrides);
   return {
     ...field,
@@ -45,14 +41,33 @@ export function resolveFormControlTokens(theme, overrides) {
     rowGap: spacing.sm,
     disabledOpacity: DISABLED_OPACITY,
     errorColor: colors.danger,
-    popover: {
-      background: isSet(popover.background) ? popover.background : colors.surface,
-      textColor: isSet(popover.textColor) ? popover.textColor : colors.onSurface,
-      borderColor: isSet(popover.borderColor) ? popover.borderColor : colors.border,
-    },
+    popover: resolvePopoverTokens(base),
   };
 }
 
+/**
+ * One row of an option list: a `<Select>` option, a `<Menu>` item.
+ *
+ * @param {object} t — resolved form-control tokens.
+ * @param {{pressed?: boolean, disabled?: boolean, justifyContent?: string}} state
+ */
+export function optionRowStyle(t, { pressed, disabled, justifyContent = "flex-start" }) {
+  return [
+    {
+      flexDirection: "row",
+      alignItems: "center",
+      justifyContent,
+      gap: t.rowGap,
+      minHeight: CONTROL_MIN_TARGET,
+      paddingHorizontal: t.paddingHorizontal,
+      paddingVertical: t.paddingVertical,
+      borderRadius: t.radius,
+    },
+    pressed ? { opacity: 0.7 } : null,
+    disabled ? { opacity: t.disabledOpacity } : null,
+  ];
+}
+
 /**
  * The ring drawn AROUND a filled control (a checkbox, a switch), whose own
  * border cannot show focus once it is the accent. Its width is always