@colixsystems/widget-sdk 0.246.0 → 0.248.0

package/dist/drag-kit-view.js

@@ -0,0 +1,310 @@
+// The drag machinery `<SortableList>` and `<Board>` share: the move handle
+// that owns the gesture, the session that measures, tracks and settles a
+// drag, and the announcement a move makes. Built from `Animated` and
+// `PanResponder`, the one drag mechanism both hosts run the same way.
+
+import React from "react";
+import { Icon } from "./icon.js";
+import { fillLabel, isDragGesture } from "./sortable-logic.js";
+import { HANDLE_ICON_SIZE, handleStyle } from "./sortable-tokens.js";
+
+const h = React.createElement;
+const ACTIVATE_KEYS = new Set(["Enter", " ", "Spacebar"]);
+const SPRING = Object.freeze({ friction: 8, tension: 80, useNativeDriver: false });
+const VISUALLY_HIDDEN = Object.freeze({
+  position: "absolute",
+  width: 1,
+  height: 1,
+  overflow: "hidden",
+  opacity: 0,
+});
+
+/** A node's window rectangle, or null when it cannot be measured. */
+export function measureNode(node) {
+  return new Promise((resolve) => {
+    if (!node || typeof node.measureInWindow !== "function") {
+      resolve(null);
+      return;
+    }
+    node.measureInWindow((x, y, width, height) => resolve({ x, y, width, height }));
+  });
+}
+
+/**
+ * Bind the shared drag machinery to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Animated: any, PanResponder: any,
+ *   Platform: any, AccessibilityInfo: any, Menu: any, handleSurface: object|null,
+ *   onOutsideScroll?: ((root: any, handler: () => void) => () => void)|null}} rn —
+ *   `handleSurface` is the host's extra handle style (the web keeps a touch
+ *   drag from scrolling the page with it); `onOutsideScroll(root, handler)`
+ *   calls `handler` when anything outside `root` scrolls, and returns its
+ *   unsubscribe. A device's handle keeps the page still, so it passes none.
+ */
+export function makeDragKit(rn) {
+  const { View, Text, Animated, PanResponder, Platform, AccessibilityInfo, Menu, handleSurface, onOutsideScroll } = rn;
+  const isWeb = Platform.OS === "web";
+
+  // Everything the responder reads comes through `latest`, so a prop that
+  // changes after the first render (a permission that loads) is honoured.
+  function useHandleResponder(latest) {
+    const responder = React.useRef(null);
+    const dragging = React.useRef(false);
+    if (responder.current === null) {
+      responder.current = PanResponder.create({
+        // Only an item that may move renders a handle, so it always claims.
+        onStartShouldSetPanResponder: () => true,
+        onMoveShouldSetPanResponder: () => true,
+        // A scroll beneath must not take the gesture from a held item.
+        onPanResponderTerminationRequest: () => false,
+        onPanResponderGrant: () => {
+          dragging.current = false;
+        },
+        onPanResponderMove: (event, gesture) => {
+          if (!dragging.current) {
+            if (!isDragGesture(gesture.dx, gesture.dy)) return;
+            dragging.current = true;
+            latest.current.onDragStart(gesture);
+          }
+          latest.current.onDragMove(gesture);
+        },
+        onPanResponderRelease: (event, gesture) => {
+          const wasDragging = dragging.current;
+          dragging.current = false;
+          if (wasDragging) latest.current.onDragEnd(gesture);
+          else if (typeof latest.current.onPress === "function") latest.current.onPress();
+        },
+        // A gesture the system takes away is a cancel, never a drop.
+        onPanResponderTerminate: () => {
+          if (!dragging.current) return;
+          dragging.current = false;
+          latest.current.onDragCancel();
+        },
+      });
+    }
+    return responder.current;
+  }
+
+  /**
+   * The grip an item is dragged by. A tap (or Enter / Space) opens its move
+   * options; the arrow keys move it a step on the web.
+   */
+  const Handle = React.forwardRef(function Handle(props, ref) {
+    const latest = React.useRef(props);
+    latest.current = props;
+    const responder = useHandleResponder(latest);
+    const onKeyDown = (event) => {
+      if (ACTIVATE_KEYS.has(event.key)) {
+        event.preventDefault();
+        if (typeof latest.current.onPress === "function") latest.current.onPress();
+        return;
+      }
+      if (latest.current.onKey(event.key)) event.preventDefault();
+    };
+    // A reader's browse mode sends a bare click (detail 0); a mouse press
+    // (detail >= 1) already opened the menu through the responder.
+    const onClick = (event) => {
+      if (event && event.detail === 0 && typeof latest.current.onPress === "function") latest.current.onPress();
+    };
+    return h(
+      View,
+      {
+        ref,
+        ...responder.panHandlers,
+        accessible: true,
+        // `role` makes it a keyboard tab stop on the web.
+        role: "button",
+        accessibilityRole: "button",
+        accessibilityLabel: props.accessibilityLabel,
+        accessibilityHint: props.accessibilityHint,
+        accessibilityActions: props.accessibilityActions,
+        onAccessibilityAction: props.onAccessibilityAction,
+        "aria-haspopup": props["aria-haspopup"],
+        "aria-expanded": props["aria-expanded"],
+        onKeyDown: isWeb ? onKeyDown : undefined,
+        onClick: isWeb ? onClick : undefined,
+        testID: props.testID,
+        style: [handleStyle(), handleSurface],
+      },
+      h(Icon, { name: "grip-vertical", size: HANDLE_ICON_SIZE, color: props.color }),
+    );
+  });
+  Handle.displayName = "DragHandle";
+
+  /**
+   * An item's handle inside its move options: the same moves as a menu for a
+   * tap or Enter, as accessibility actions for a screen reader, and as a drag.
+   */
+  function moveHandle({ itemKey, name, actions, run, onKey, session, handles, color, words, testID }) {
+    const label = fillLabel(words.handle, { item: name });
+    const handle = h(Handle, {
+      ref: (node) => (node ? handles.current.set(itemKey, node) : handles.current.delete(itemKey)),
+      color,
+      accessibilityLabel: label,
+      accessibilityHint: words.hint,
+      accessibilityActions: actions.map((action) => ({ name: action.name, label: action.label })),
+      onAccessibilityAction: (event) => run(event.nativeEvent.actionName),
+      onKey,
+      onDragStart: (gesture) => session.start(itemKey, gesture),
+      onDragMove: session.move,
+      onDragEnd: session.end,
+      onDragCancel: session.cancel,
+      testID: testID ? `${testID}-handle-${itemKey}` : undefined,
+    });
+    return h(Menu, {
+      trigger: handle,
+      accessibilityLabel: label,
+      items: actions.map((action) => ({ key: action.name, label: action.label, onPress: () => run(action.name) })),
+      testID: testID ? `${testID}-menu-${itemKey}` : undefined,
+    });
+  }
+
+  // After a keyboard or menu move, the moved item's handle keeps the focus.
+  function useFocusAfterMove(handles) {
+    const pending = React.useRef(null);
+    React.useEffect(() => {
+      const key = pending.current;
+      if (key === null || !isWeb) return;
+      pending.current = null;
+      const node = handles.current.get(key);
+      if (node && typeof node.focus === "function") node.focus();
+    });
+    return pending;
+  }
+
+  // The handle's look without its gesture, for the lifted copy.
+  function HandleMark({ color }) {
+    return h(View, { style: handleStyle() }, h(Icon, { name: "grip-vertical", size: HANDLE_ICON_SIZE, color }));
+  }
+
+  /**
+   * A move's result, said aloud: a polite live region on the web, the
+   * platform's screen-reader announcement on a device.
+   */
+  function useAnnouncer() {
+    const [message, setMessage] = React.useState("");
+    const announce = (text) => {
+      if (isWeb) setMessage(text);
+      else if (AccessibilityInfo && typeof AccessibilityInfo.announceForAccessibility === "function") {
+        AccessibilityInfo.announceForAccessibility(text);
+      }
+    };
+    const region = isWeb ? h(Text, { "aria-live": "polite", style: VISUALLY_HIDDEN }, message) : null;
+    return [announce, region];
+  }
+
+  // A page scrolled under a held item leaves its measured frames stale, so
+  // the drag is called off, as an open menu closes.
+  function useCancelOnOutsideScroll(active, latest, cancel) {
+    const cancelRef = React.useRef(cancel);
+    cancelRef.current = cancel;
+    React.useEffect(() => {
+      if (typeof onOutsideScroll !== "function" || !active) return undefined;
+      const root = latest.current.rootRef ? latest.current.rootRef.current : null;
+      return onOutsideScroll(root, () => cancelRef.current());
+    }, [active, latest]);
+  }
+
+  /**
+   * One drag at a time: measure when it starts, follow the pointer, then
+   * settle the lifted copy onto its slot or spring it back.
+   *
+   * `config` is read fresh on every call: `measure(key)` resolves the
+   * frames, `track(data, gesture)` names the target, `drop(data, target)`
+   * commits a real change and returns where the copy lands (or null to
+   * spring it back), `axis` "y" locks a list's copy to its column,
+   * `onCancel()` runs when a drag is called off, and `rootRef` is the
+   * component, whose own scrolling the drag already follows.
+   */
+  function useDragSession(config) {
+    const latest = React.useRef(config);
+    latest.current = config;
+    const pan = React.useRef(null);
+    if (pan.current === null) pan.current = new Animated.ValueXY({ x: 0, y: 0 });
+    const session = React.useRef(null);
+    const mounted = React.useRef(true);
+    const [drag, setDrag] = React.useState(null);
+    React.useEffect(() => {
+      mounted.current = true;
+      return () => {
+        mounted.current = false;
+        session.current = null;
+      };
+    }, []);
+
+    // Only the drag that is settling ends: a spring stopped by a new drag
+    // still calls back, and must not clear the drag that stopped it.
+    const settle = (key, toValue) => {
+      Animated.spring(pan.current, { ...SPRING, toValue }).start(() => {
+        if (!mounted.current) return;
+        setDrag((current) => (current && current.key === key && current.settling ? null : current));
+      });
+    };
+    const follow = (own, gesture) => {
+      const x = latest.current.axis === "y" ? 0 : gesture.dx;
+      pan.current.setValue({ x, y: gesture.dy });
+      const target = latest.current.track(own.data, gesture);
+      if (!latest.current.sameTarget(target, own.target)) {
+        own.target = target;
+        setDrag((current) => (current && current.key === own.key ? { ...current, target } : current));
+      }
+      if (typeof latest.current.afterMove === "function") latest.current.afterMove(own.data, gesture);
+    };
+    const springBack = (own) => {
+      setDrag((current) =>
+        current && current.key === own.key ? { ...current, target: own.data.resting, settling: true } : current,
+      );
+      settle(own.key, { x: 0, y: 0 });
+    };
+
+    const start = (key, gesture) => {
+      const own = { key, data: null, target: null, gesture };
+      session.current = own;
+      latest.current.measure(key).then((data) => {
+        // Released, or another drag began, while the frames were measured.
+        if (!mounted.current || session.current !== own || !data) return;
+        own.data = data;
+        own.target = data.resting;
+        pan.current.setValue({ x: 0, y: 0 });
+        setDrag({ key, data, target: data.resting, settling: false });
+        follow(own, own.gesture);
+      });
+    };
+    const move = (gesture) => {
+      const own = session.current;
+      if (!own) return;
+      own.gesture = gesture;
+      if (own.data) follow(own, gesture);
+    };
+    const end = (gesture) => {
+      const own = session.current;
+      session.current = null;
+      if (!own || !own.data) return;
+      const target = latest.current.track(own.data, gesture);
+      const landing = latest.current.drop(own.data, target);
+      if (!landing) {
+        springBack(own);
+        return;
+      }
+      setDrag((current) => (current && current.key === own.key ? { ...current, target, settling: true } : current));
+      settle(own.key, landing);
+    };
+    const cancel = () => {
+      const own = session.current;
+      session.current = null;
+      if (typeof latest.current.onCancel === "function") latest.current.onCancel();
+      if (own && own.data) springBack(own);
+    };
+    // A narrow board scrolled under a still pointer: re-aim at the new spot.
+    const retrack = () => {
+      const own = session.current;
+      if (own && own.data) follow(own, own.gesture);
+    };
+
+    useCancelOnOutsideScroll(drag !== null && !drag.settling, latest, cancel);
+
+    return { drag, pan: pan.current, start, move, end, cancel, retrack };
+  }
+
+  return { HandleMark, moveHandle, useAnnouncer, useDragSession, useFocusAfterMove };
+}

package/dist/file-upload-view.js

@@ -12,7 +12,7 @@ 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 { DRAWS_FIELD_FRAME, errorMessage, hasNote, isShown, isText, spokenLabel } from "./form-control-logic.js";
 import { makeFieldFrame } from "./form-control-view.js";
 import { fileKey, formatFileSize, pickPayload, planPick } from "./file-upload-logic.js";
 
@@ -124,6 +124,7 @@ export function makeFileUpload(rn, extras) {
       helper,
       error,
       disabled = false,
+      required = false,
       buttonLabel = multiple ? "Choose files" : "Choose file",
       buttonVariant = "outlined",
       uploadingLabel = "Uploading…",
@@ -141,6 +142,7 @@ export function makeFileUpload(rn, extras) {
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
     const t = resolveFormControlTokens(theme);
     const sharedRemove = useHostSharedText("remove", "Remove");
+    const requiredWord = useHostSharedText("required", "Required");
     const [ownFiles, setOwnFiles] = React.useState([]);
     const [rejection, setRejection] = React.useState(null);
     const [focused, setFocused] = React.useState(false);
@@ -165,6 +167,13 @@ export function makeFileUpload(rn, extras) {
     const invalid = isShown(error) || rejection !== null;
     const helperShown = supported ? helper : unsupportedMessage;
     const noted = hasNote({ helper: helperShown, error: shownError });
+    // Named by its field label, the picker still says what it does.
+    const fieldName = spokenLabel(undefined, label, required ? requiredWord : null);
+    const pickerName = isShown(accessibilityLabel)
+      ? accessibilityLabel
+      : fieldName && isText(buttonLabel)
+        ? `${fieldName}, ${buttonLabel}`
+        : fieldName;
 
     const commit = (next) => {
       if (!controlled) setOwnFiles(next);
@@ -249,7 +258,7 @@ export function makeFileUpload(rn, extras) {
             onPick: receive,
             onFocus: () => setFocused(true),
             onBlur: () => setFocused(false),
-            accessibilityLabel,
+            accessibilityLabel: pickerName,
             "aria-invalid": invalid || undefined,
             "aria-describedby": noted ? noteId : undefined,
           },
@@ -308,6 +317,7 @@ export function makeFileUpload(rn, extras) {
         error: shownError,
         noteId,
         alertOnError: true,
+        required,
         style: containerStyle,
       },
       DropZone
@@ -317,5 +327,6 @@ export function makeFileUpload(rn, extras) {
   }
 
   FileUpload.displayName = "FileUpload";
+  FileUpload[DRAWS_FIELD_FRAME] = true;
   return FileUpload;
 }

package/dist/filter-bar-logic.js

@@ -0,0 +1,143 @@
+// The `<FilterBar>` rules that need no renderer: which facets are applied,
+// what their chips read, how one edit changes the filter value, and whether
+// the bar fits on one toolbar row at its measured width. Both hosts share
+// them, and the node suite tests them.
+
+import { widthTier } from "./container-width.js";
+
+/** The room the search field keeps before the facets give way to a sheet. */
+export const FILTER_SEARCH_MIN_WIDTH = 160;
+/** The width of one compact facet or sort dropdown on the toolbar row. */
+export const FILTER_FACET_WIDTH = 150;
+
+/** Whether a facet value filters anything: a non-empty list or a value. */
+export function isApplied(value) {
+  if (Array.isArray(value)) return value.length > 0;
+  return value !== undefined && value !== null && value !== "";
+}
+
+/**
+ * The facets the bar can draw: a string `key`, a `label` and an `options`
+ * list, each option `{ value, label }`. Anything else is left out, and a
+ * repeated key keeps its first facet.
+ *
+ * @param {unknown} facets
+ */
+export function usableFacets(facets) {
+  if (!Array.isArray(facets)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const facet of facets) {
+    if (!facet || typeof facet.key !== "string" || facet.key.length === 0) continue;
+    if (seen.has(facet.key)) continue;
+    seen.add(facet.key);
+    out.push({
+      ...facet,
+      label: typeof facet.label === "string" ? facet.label : facet.key,
+      options: Array.isArray(facet.options) ? facet.options.filter(Boolean) : [],
+      multiple: facet.multiple === true,
+    });
+  }
+  return out;
+}
+
+function valueMap(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+/** The facets with a value applied, in the order they are given. */
+export function appliedFacets(facets, value) {
+  const own = valueMap(value);
+  return facets.filter((facet) => isApplied(own[facet.key]));
+}
+
+/**
+ * The filter value with one facet set; an empty value removes the facet's
+ * key, so a cleared filter never lingers as `null` or `[]`.
+ *
+ * @param {Record<string, unknown>} value
+ * @param {string} key
+ * @param {unknown} next
+ */
+export function withFacet(value, key, next) {
+  const rest = { ...valueMap(value) };
+  delete rest[key];
+  return isApplied(next) ? { ...rest, [key]: next } : rest;
+}
+
+function sameFacetValue(a, b) {
+  if (Array.isArray(a) || Array.isArray(b)) {
+    const left = Array.isArray(a) ? a : [];
+    const right = Array.isArray(b) ? b : [];
+    return left.length === right.length && left.every((v) => right.includes(v));
+  }
+  return a === b;
+}
+
+/** Whether two filter values apply the same facets, ignoring list order. */
+export function sameFilters(a, b) {
+  const left = valueMap(a);
+  const right = valueMap(b);
+  const keys = new Set(
+    [...Object.keys(left), ...Object.keys(right)].filter(
+      (key) => isApplied(left[key]) || isApplied(right[key]),
+    ),
+  );
+  for (const key of keys) {
+    if (!sameFacetValue(left[key], right[key])) return false;
+  }
+  return true;
+}
+
+function optionLabel(facet, value) {
+  const option = facet.options.find((own) => own.value === value);
+  return option && typeof option.label === "string" ? option.label : String(value);
+}
+
+/** An applied facet's chip: "Status: Open", or "Tags: Red, Blue". */
+export function chipLabel(facet, value) {
+  const picked = Array.isArray(value) ? value : [value];
+  return `${facet.label}: ${picked.map((own) => optionLabel(facet, own)).join(", ")}`;
+}
+
+/** A compact facet dropdown's placeholder: "Status: Any". */
+export function facetPlaceholder(facet, anyText) {
+  return `${facet.label}: ${anyText}`;
+}
+
+/**
+ * Copy with a `{name}` slot filled, or a function of the value. Lets the
+ * widget translate "Remove {label}" as one string.
+ *
+ * @param {string|((value: any) => string)} template
+ * @param {string} slot
+ * @param {string|number} value
+ */
+export function fillText(template, slot, value) {
+  if (typeof template === "function") return String(template(value));
+  return String(template).split(`{${slot}}`).join(String(value));
+}
+
+/** The narrow bar's button: "Filters", or "Filters · 2" while two apply. */
+export function filtersButtonText(text, count) {
+  return count > 0 ? `${text} · ${count}` : text;
+}
+
+/**
+ * How the bar lays out at a measured width: `"row"`, search and every
+ * dropdown on one toolbar line, or `"sheet"`, the search field and one
+ * Filters button opening the facets. Narrow is always a sheet; a wider bar
+ * falls back to it only when its dropdowns would not fit beside the search.
+ * Unmeasured (0) is a row, the wide form, as `widthTier` reads it.
+ *
+ * @param {{ width: number, dropdowns: number, gap: number, search: boolean }} bar
+ * @returns {"row"|"sheet"}
+ */
+export function filterBarLayout({ width, dropdowns, gap, search }) {
+  const tier = widthTier(width);
+  if (tier === "narrow") return "sheet";
+  if (!(width > 0) || dropdowns === 0) return "row";
+  const needed =
+    (search ? FILTER_SEARCH_MIN_WIDTH + gap : 0) + dropdowns * FILTER_FACET_WIDTH + (dropdowns - 1) * gap;
+  return needed > width ? "sheet" : "row";
+}