@colixsystems/widget-sdk 0.237.0 → 0.239.0

package/dist/file-upload-view.js

@@ -0,0 +1,321 @@
+// The ONE implementation behind `<FileUpload>`. It is built on `<FilePicker>`,
+// which owns opening each platform's file dialog, and draws the themed field
+// around it: the button, the chosen files with their size and a remove
+// control, and the uploading, error and disabled states. It uploads nothing
+// itself; the caller passes `onPick` to `useFilestoreUpload().upload`.
+//
+// The bindings differ in their primitives and in one extra: the web binding
+// passes a `DropZone`, so files can also be dropped onto the field there.
+
+import React from "react";
+import { useHostSharedText, useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { Icon } from "./icon.js";
+import { focusHaloStyle, resolveFormControlTokens } from "./form-control-tokens.js";
+import { errorMessage, hasNote, isShown, isText } from "./form-control-logic.js";
+import { makeFieldFrame } from "./form-control-view.js";
+import { fileKey, formatFileSize, pickPayload, planPick } from "./file-upload-logic.js";
+
+const h = React.createElement;
+// The remove control's real size; a web host ignores hitSlop.
+const REMOVE_TARGET = 36;
+const HIDDEN = {
+  "aria-hidden": true,
+  importantForAccessibility: "no-hide-descendants",
+  accessibilityElementsHidden: true,
+};
+
+/**
+ * Bind the shared file upload to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any, Platform: any, FilePicker: any, Button: any, Spinner: any}} rn
+ * @param {{DropZone?: any}} [extras] — the web's drop target; absent on native.
+ */
+export function makeFileUpload(rn, extras) {
+  const { View, Text, Pressable, Platform, FilePicker, Button, Spinner } = rn;
+  const DropZone = (extras && extras.DropZone) || null;
+  const FieldFrame = makeFieldFrame(rn);
+
+  // Keyboard focus is a web concern; a device's reader moves on by itself.
+  function focusNode(node) {
+    if (Platform.OS !== "web" || !node) return false;
+    const target =
+      node.tabIndex >= 0 || typeof node.querySelector !== "function"
+        ? node
+        : node.querySelector("input");
+    if (!target || typeof target.focus !== "function") return false;
+    target.focus();
+    return true;
+  }
+
+  function FileRow({ t, file, index, blocked, removeLabel, onRemove, removeRef, testID }) {
+    const size = formatFileSize(file && file.size);
+    const name = file && typeof file.name === "string" && file.name ? file.name : "file";
+    return h(
+      View,
+      {
+        testID: testID ? `${testID}-file-${index}` : undefined,
+        style: {
+          flexDirection: "row",
+          alignItems: "center",
+          gap: t.rowGap,
+          paddingLeft: t.paddingHorizontal,
+          minHeight: REMOVE_TARGET,
+        },
+      },
+      h(View, HIDDEN, h(Icon, { name: "file", size: 16, color: t.placeholderColor })),
+      h(
+        Text,
+        {
+          numberOfLines: 1,
+          style: { flexShrink: 1, color: t.textColor, fontFamily: t.fontFamily, fontSize: t.labelSize },
+        },
+        name,
+      ),
+      size
+        ? h(
+            Text,
+            { style: { color: t.helperColor, fontFamily: t.fontFamily, fontSize: t.helperSize } },
+            size,
+          )
+        : null,
+      h(View, { style: { flex: 1 } }),
+      h(
+        Pressable,
+        {
+          ref: removeRef,
+          onPress: () => onRemove(index),
+          disabled: blocked,
+          accessibilityRole: "button",
+          accessibilityLabel: `${removeLabel} ${name}`,
+          "aria-disabled": blocked,
+          testID: testID ? `${testID}-remove-${index}` : undefined,
+          style: ({ pressed }) => [
+            {
+              width: REMOVE_TARGET,
+              height: REMOVE_TARGET,
+              alignItems: "center",
+              justifyContent: "center",
+              borderRadius: t.radius,
+            },
+            pressed ? { opacity: 0.7 } : null,
+            blocked ? { opacity: t.disabledOpacity } : null,
+          ],
+        },
+        h(Icon, { name: "x", size: 16, color: t.placeholderColor }),
+      ),
+    );
+  }
+
+  /**
+   * @param {object} props — see `FileUploadProps` in index.d.ts.
+   */
+  function FileUpload(props) {
+    const {
+      accept,
+      multiple = false,
+      files,
+      onFilesChange,
+      onPick,
+      onRemove,
+      onReject,
+      uploading = false,
+      label,
+      helper,
+      error,
+      disabled = false,
+      buttonLabel = multiple ? "Choose files" : "Choose file",
+      buttonVariant = "outlined",
+      uploadingLabel = "Uploading…",
+      emptyLabel = multiple ? "No files chosen" : "No file chosen",
+      dropLabel = multiple ? "or drop files here" : "or drop a file here",
+      rejectedMessage = "That file type isn't accepted here.",
+      singleFileMessage = "Only one file can be added here, so the first was kept.",
+      unsupportedMessage = "Choosing files isn't available here.",
+      removeAccessibilityLabel,
+      accessibilityLabel,
+      style,
+      containerStyle,
+      testID,
+    } = props;
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const t = resolveFormControlTokens(theme);
+    const sharedRemove = useHostSharedText("remove", "Remove");
+    const [ownFiles, setOwnFiles] = React.useState([]);
+    const [rejection, setRejection] = React.useState(null);
+    const [focused, setFocused] = React.useState(false);
+    const [dragging, setDragging] = React.useState(false);
+    const noteId = React.useId();
+    const pickerRef = React.useRef(null);
+    const removeRefs = React.useRef([]);
+    const pendingFocus = React.useRef(null);
+
+    // The newest message shows: a new `error` replaces an older refusal.
+    const [seenError, setSeenError] = React.useState(error);
+    if (error !== seenError) {
+      setSeenError(error);
+      if (isShown(error)) setRejection(null);
+    }
+
+    const supported = FilePicker.isSupported !== false;
+    const blocked = disabled || uploading || !supported;
+    const controlled = Array.isArray(files);
+    const chosen = controlled ? files.filter(Boolean) : ownFiles;
+    const shownError = rejection || errorMessage(error);
+    const invalid = isShown(error) || rejection !== null;
+    const helperShown = supported ? helper : unsupportedMessage;
+    const noted = hasNote({ helper: helperShown, error: shownError });
+
+    const commit = (next) => {
+      if (!controlled) setOwnFiles(next);
+      if (typeof onFilesChange === "function") onFilesChange(next);
+    };
+
+    const receive = (picked) => {
+      if (blocked) return;
+      const { added, rejected, extra, next } = planPick(chosen, picked, accept, multiple);
+      setRejection(
+        rejected.length > 0 ? rejectedMessage : extra.length > 0 ? singleFileMessage : null,
+      );
+      if (typeof onReject === "function") {
+        if (rejected.length > 0) onReject(rejected, "type");
+        if (extra.length > 0) onReject(extra, "count");
+      }
+      if (added.length === 0) return;
+      commit(next);
+      if (typeof onPick === "function") onPick(pickPayload(added, multiple));
+    };
+
+    const remove = (index) => {
+      if (blocked) return;
+      const file = chosen[index];
+      setRejection(null);
+      pendingFocus.current = { file, index };
+      commit(chosen.filter((_, i) => i !== index));
+      if (typeof onRemove === "function") onRemove(file, index);
+    };
+
+    // The pressed remove button is gone: focus its neighbour, else the picker.
+    React.useEffect(() => {
+      const pending = pendingFocus.current;
+      if (!pending || chosen[pending.index] === pending.file) return;
+      pendingFocus.current = null;
+      const neighbour = Math.min(pending.index, chosen.length - 1);
+      if (!focusNode(neighbour >= 0 ? removeRefs.current[neighbour] : null)) {
+        focusNode(pickerRef.current);
+      }
+    });
+
+    const status = uploading
+      ? null
+      : DropZone && !blocked
+        ? dropLabel
+        : chosen.length === 0
+          ? emptyLabel
+          : null;
+    const statusText = { color: t.placeholderColor, fontFamily: t.fontFamily, fontSize: t.labelSize };
+
+    const field = h(
+      View,
+      {
+        testID,
+        style: [
+          {
+            flexDirection: "row",
+            alignItems: "center",
+            flexWrap: "wrap",
+            gap: t.rowGap,
+            minHeight: t.height,
+            padding: t.rowGap,
+            borderWidth: 1,
+            borderStyle: DropZone ? "dashed" : "solid",
+            borderColor: invalid ? t.errorColor : t.borderColor,
+            borderRadius: t.radius,
+            backgroundColor: t.background,
+          },
+          dragging && !blocked ? { borderColor: t.focusColor, borderStyle: "solid" } : null,
+          style,
+        ],
+      },
+      h(
+        View,
+        { ref: pickerRef, style: focusHaloStyle(t, focused && !blocked, t.radius) },
+        h(
+          FilePicker,
+          {
+            accept,
+            multiple,
+            disabled: blocked,
+            onPick: receive,
+            onFocus: () => setFocused(true),
+            onBlur: () => setFocused(false),
+            accessibilityLabel,
+            "aria-invalid": invalid || undefined,
+            "aria-describedby": noted ? noteId : undefined,
+          },
+          h(Button, {
+            title: buttonLabel,
+            icon: uploading ? undefined : "upload",
+            variant: buttonVariant,
+            testID: testID ? `${testID}-button` : undefined,
+          }),
+        ),
+      ),
+      uploading
+        ? h(
+            View,
+            { style: { flexDirection: "row", alignItems: "center", gap: t.gap } },
+            h(Spinner, { size: "sm", accessibilityLabel: isText(uploadingLabel) ? String(uploadingLabel) : undefined }),
+            h(Text, { ...HIDDEN, style: statusText }, uploadingLabel),
+          )
+        : null,
+      isShown(status)
+        ? h(Text, { style: [statusText, { flexShrink: 1 }, blocked ? { opacity: t.disabledOpacity } : null] }, status)
+        : null,
+    );
+
+    const list =
+      chosen.length > 0
+        ? h(
+            View,
+            { style: [{ gap: 2 }, disabled ? { opacity: t.disabledOpacity } : null] },
+            ...chosen.map((file, index) =>
+              h(FileRow, {
+                key: fileKey(file, index),
+                t,
+                file,
+                index,
+                blocked,
+                removeLabel: isShown(removeAccessibilityLabel) ? removeAccessibilityLabel : sharedRemove,
+                onRemove: remove,
+                removeRef: (node) => {
+                  removeRefs.current[index] = node;
+                },
+                testID,
+              }),
+            ),
+          )
+        : null;
+
+    const body = h(View, { style: { gap: t.gap } }, field, list);
+
+    return h(
+      FieldFrame,
+      {
+        t,
+        label,
+        helper: helperShown,
+        error: shownError,
+        noteId,
+        alertOnError: true,
+        style: containerStyle,
+      },
+      DropZone
+        ? h(DropZone, { disabled: blocked, onFiles: receive, onActiveChange: setDragging }, body)
+        : body,
+    );
+  }
+
+  FileUpload.displayName = "FileUpload";
+  return FileUpload;
+}

package/dist/file-upload.js

@@ -0,0 +1,62 @@
+// `<FileUpload>` (web). Binds ./file-upload-view.js to react-native-web and
+// the web `<FilePicker>`, and adds the one web extra: files dropped onto the
+// field are taken as if picked. Keyboard and screen-reader users have the
+// button, which is the whole control on native.
+
+import React from "react";
+import { View, Text, Pressable, Platform } from "react-native-web";
+import { makeFileUpload } from "./file-upload-view.js";
+import { FilePicker } from "./filepicker.js";
+import { Button } from "./button.js";
+import { Spinner } from "./loading.js";
+
+const DROP_ZONE_STYLE = { display: "flex", flexDirection: "column", minWidth: 0 };
+
+function carriesFiles(event) {
+  const types = event.dataTransfer && event.dataTransfer.types;
+  return Boolean(types) && Array.from(types).includes("Files");
+}
+
+/**
+ * The field's drop target. A drop is always claimed, even while disabled,
+ * so the browser never navigates away to the dropped file.
+ */
+function DropZone({ disabled, onFiles, onActiveChange, children }) {
+  // Entering a child fires dragleave on the parent; count the depth.
+  const depth = React.useRef(0);
+  return React.createElement(
+    "div",
+    {
+      style: DROP_ZONE_STYLE,
+      onDragEnter: (event) => {
+        if (!carriesFiles(event)) return;
+        event.preventDefault();
+        depth.current += 1;
+        if (!disabled) onActiveChange(true);
+      },
+      onDragOver: (event) => {
+        if (!carriesFiles(event)) return;
+        event.preventDefault();
+        event.dataTransfer.dropEffect = disabled ? "none" : "copy";
+      },
+      onDragLeave: (event) => {
+        if (!carriesFiles(event)) return;
+        depth.current = Math.max(0, depth.current - 1);
+        if (depth.current === 0) onActiveChange(false);
+      },
+      onDrop: (event) => {
+        if (!carriesFiles(event)) return;
+        event.preventDefault();
+        depth.current = 0;
+        onActiveChange(false);
+        if (!disabled) onFiles(Array.from(event.dataTransfer.files || []));
+      },
+    },
+    children,
+  );
+}
+
+export const FileUpload = makeFileUpload(
+  { View, Text, Pressable, Platform, FilePicker, Button, Spinner },
+  { DropZone },
+);

package/dist/file-upload.native.js

@@ -0,0 +1,11 @@
+// `<FileUpload>` (native). Binds ./file-upload-view.js to React Native and the
+// native `<FilePicker>` (the OS document picker). No drop target: React Native
+// has no events for files dragged onto an app, so the button is the control.
+
+import { View, Text, Pressable, Platform } from "react-native";
+import { makeFileUpload } from "./file-upload-view.js";
+import { FilePicker } from "./filepicker.native.js";
+import { Button } from "./button.native.js";
+import { Spinner } from "./loading.native.js";
+
+export const FileUpload = makeFileUpload({ View, Text, Pressable, Platform, FilePicker, Button, Spinner });

package/dist/filepicker.js

@@ -21,6 +21,9 @@
 //              `<label>` so the click reaches the hidden input
 //              everywhere — no manual ref / `.click()` plumbing needed.
 //   accessibilityLabel: string?     — written to the wrapper label.
+//   onFocus / onBlur:   () => void   — the hidden input's focus, so a
+//              caller can draw a focus ring on its visible trigger.
+//   aria-describedby / aria-invalid — tie the picker to a field's note.
 
 import React, { useRef, useCallback } from "react";
 
@@ -54,6 +57,10 @@ export function FilePicker({
   onPick,
   children,
   accessibilityLabel,
+  onFocus,
+  onBlur,
+  "aria-describedby": describedBy,
+  "aria-invalid": invalid,
 }) {
   const inputRef = useRef(null);
 
@@ -84,6 +91,10 @@ export function FilePicker({
       multiple,
       disabled,
       onChange: handleChange,
+      onFocus,
+      onBlur,
+      "aria-describedby": describedBy,
+      "aria-invalid": invalid || undefined,
       style: HIDDEN_INPUT_STYLE,
     }),
     children,

package/dist/filepicker.native.js

@@ -6,7 +6,8 @@
 // `<input type="file">` because react-native-web has no equivalent of the
 // system file picker; this native variant calls the OS document picker
 // directly. Both honour the same public contract — `accept` / `multiple`
-// / `disabled` / `onPick` / `children` / `accessibilityLabel`.
+// / `disabled` / `onPick` / `children` / `accessibilityLabel` / `onFocus`
+// / `onBlur` / `aria-describedby` / `aria-invalid`.
 //
 // `onPick` receives the same shape on both platforms:
 //   - web → the browser's `File` object (a `Blob` with name + type).
@@ -73,6 +74,10 @@ export function FilePicker({
   onPick,
   children,
   accessibilityLabel,
+  onFocus,
+  onBlur,
+  "aria-describedby": describedBy,
+  "aria-invalid": invalid,
 }) {
   const type = useMemo(() => _mapAccept(accept), [accept]);
 
@@ -103,10 +108,14 @@ export function FilePicker({
     Pressable,
     {
       onPress: handlePress,
+      onFocus,
+      onBlur,
       disabled,
       accessibilityRole: "button",
       accessibilityLabel,
       accessibilityState: { disabled },
+      "aria-describedby": describedBy,
+      "aria-invalid": invalid || undefined,
     },
     React.createElement(View, { style: disabled ? { opacity: 0.5 } : undefined }, children),
   );

package/dist/form-control-view.js

@@ -26,6 +26,8 @@ export function makeFieldFrame(rn) {
    * @param {() => void} [props.onLabelPress] — a text label then acts for the control.
    * @param {boolean} [props.noteDisabled] — dim the note alone, when the
    *   control dims itself and `disabled` would dim it twice.
+   * @param {boolean} [props.alertOnError] — an error interrupts, as an alert,
+   *   for one that follows an action rather than typing.
    */
   function FieldFrame({
     t,
@@ -36,6 +38,7 @@ export function makeFieldFrame(rn) {
     noteId,
     onLabelPress,
     noteDisabled,
+    alertOnError,
     style,
     children,
   }) {
@@ -79,7 +82,11 @@ export function makeFieldFrame(rn) {
             {
               nativeID: noteId,
               // Announced where the host can: the web and Android.
-              ...(message ? { accessibilityLiveRegion: "polite" } : null),
+              ...(message
+                ? alertOnError
+                  ? { accessibilityRole: "alert", accessibilityLiveRegion: "assertive" }
+                  : { accessibilityLiveRegion: "polite" }
+                : null),
               style: {
                 color: message ? t.errorColor : t.helperColor,
                 fontFamily: t.fontFamily,