@colixsystems/widget-sdk 0.201.0 → 0.204.0

package/dist/index.d.ts

@@ -3441,6 +3441,120 @@ export const Tabs: (props: {
   testID?: string;
 }) => any;
 
+/**
+ * Themed collapsible sections. The surface comes from the theme's `card`
+ * scope and the headers and dividers from its `list` scope, so every
+ * collapsible section in the app matches. Each header announces whether its
+ * section is open, and a section's body mounts only while it is open.
+ *
+ * @example
+ *   <Accordion defaultValue="shipping">
+ *     <AccordionItem value="shipping" title="Shipping" subtitle="2-4 days">…</AccordionItem>
+ *     <AccordionItem value="returns" title="Returns">…</AccordionItem>
+ *   </Accordion>
+ */
+export const Accordion: (props: {
+  /** Several sections may be open at once; by default opening one closes the other. */
+  multiple?: boolean;
+  /** The open section key (an array of keys when `multiple`); makes it controlled. */
+  value?: string | string[] | null;
+  /** The initially open section(s) when uncontrolled. */
+  defaultValue?: string | string[] | null;
+  /** The open section(s) after a header press, in the same shape as `value`. */
+  onChange?: (next: string | string[] | null) => void;
+  children?: ReactNode;
+  /** Names the group of sections for assistive technology. */
+  accessibilityLabel?: string;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/** One section of an `<Accordion>`; on its own it is an accordion of one. */
+export const AccordionItem: (props: {
+  /** The key `value` / `defaultValue` / `onChange` name it by; give one whenever you name sections. */
+  value?: string;
+  title?: ReactNode;
+  subtitle?: ReactNode;
+  /** Beside the header and outside its toggle, so a button here does its own thing. */
+  trailing?: ReactNode;
+  disabled?: boolean;
+  /** Rule under the section (default true); the surface edge hides the last one's. */
+  divider?: boolean;
+  children?: ReactNode;
+  accessibilityLabel?: string;
+  style?: any;
+  /** Also tags the header (`<testID>-header`) and open body (`<testID>-panel`). */
+  testID?: string;
+}) => any;
+
+export type SpinnerSize = "sm" | "md" | "lg";
+
+/**
+ * Themed loading spinner. It wears the theme's `colors.loader`, stops turning
+ * under reduced motion, and is a labelled element in the busy state.
+ *
+ * @example
+ *   <Spinner />
+ *   <Spinner size="lg" label="Loading orders" />
+ */
+export const Spinner: (props: {
+  /** A named size, or a diameter in px. Defaults to "md". */
+  size?: SpinnerSize | number;
+  /** Overrides `colors.loader`, for contrast inside a control you fill yourself. */
+  color?: string;
+  /** Drawn under the ring. A string is also the accessibility label; a node stays exposed as content. */
+  label?: ReactNode;
+  /** The accessibility label, instead of `label` / the app's own "Loading…". */
+  accessibilityLabel?: string;
+  /** For hosts rendering outside a widget context; widgets omit it. */
+  theme?: any;
+  style?: any;
+  testID?: string;
+}) => any;
+
+export type SkeletonShape = "text" | "block" | "circle" | "listRow";
+
+/**
+ * Themed loading placeholder. Its colour and corners come from the theme's
+ * `loading` scope. The outermost Skeleton pulses as a whole (still under
+ * reduced motion), is the one loading region (`role="status"` + `aria-busy`
+ * on the web; a labelled accessible element in the busy state on native), and
+ * hides every bone inside it from assistive technology — pass children to
+ * group bones.
+ *
+ * @example
+ *   <Skeleton shape="listRow" count={4} />
+ *   <Skeleton style={{ flexDirection: "row", gap: 12 }}>
+ *     <Skeleton shape="circle" />
+ *     <Skeleton shape="text" lines={2} style={{ flex: 1 }} />
+ *   </Skeleton>
+ */
+export const Skeleton: (props: {
+  /** Defaults to "text". Ignored when children are passed. */
+  shape?: SkeletonShape;
+  /** `text` / `block`. Defaults to "100%". */
+  width?: number | string;
+  /** `text` / `block`. */
+  height?: number;
+  /** `circle` diameter. */
+  size?: number;
+  /** `text`: how many lines; the last one stops short. */
+  lines?: number;
+  /** `listRow`: how many rows. Defaults to 3. */
+  count?: number;
+  /** `listRow`: draw the leading avatar. Defaults to true. */
+  leading?: boolean;
+  radius?: number;
+  color?: string;
+  /** The region's accessibility label, instead of the app's own "Loading…". */
+  accessibilityLabel?: string;
+  /** For hosts rendering outside a widget context; widgets omit it. */
+  theme?: any;
+  style?: any;
+  testID?: string;
+  children?: ReactNode;
+}) => any;
+
 export type TextRole = "display" | "title" | "subtitle" | "body" | "caption" | "overline";
 export const TEXT_ROLES: readonly TextRole[];
 export const TEXT_TRANSFORMS: readonly string[];

package/dist/index.js

@@ -257,8 +257,12 @@ export {
 } from "./button-style.js";
 // The themed text-entry field; follows the theme's `muted` scope.
 export { TextField } from "./text-field.js";
+// Themed collapsible sections, drawn from the `card` and `list` scopes.
+export { Accordion, AccordionItem } from "./accordion.js";
 // A themed tab strip; follows the theme's `tabs` scope.
 export { Tabs } from "./tabs.js";
+// Themed loading states; follow the theme's `loading` scope.
+export { Spinner, Skeleton } from "./loading.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/index.native.js

@@ -250,8 +250,12 @@ export {
 } from "./button-style.js";
 // The themed text-entry field; follows the theme's `muted` scope.
 export { TextField } from "./text-field.native.js";
+// Themed collapsible sections, drawn from the `card` and `list` scopes.
+export { Accordion, AccordionItem } from "./accordion.native.js";
 // A themed tab strip; follows the theme's `tabs` scope.
 export { Tabs } from "./tabs.native.js";
+// Themed loading states; follow the theme's `loading` scope.
+export { Spinner, Skeleton } from "./loading.native.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/loading-tokens.js

@@ -0,0 +1,122 @@
+// The values `<Spinner>` and `<Skeleton>` paint with. Platform-free, like
+// tabs-tokens.js, so both hosts draw one loading look and tests can pin it.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { normaliseThemeComponents } from "./theme-components.js";
+
+// `md` and `lg` are the platform spinner's small and large.
+export const SPINNER_SIZES = Object.freeze({ sm: 16, md: 20, lg: 36 });
+export const DEFAULT_SPINNER_SIZE = "md";
+export const SPINNER_TURN_MS = 750;
+
+export const SKELETON_SHAPES = Object.freeze(["text", "block", "circle", "listRow"]);
+export const DEFAULT_SKELETON_SHAPE = "text";
+// One way of the pulse; a full breath is twice this.
+export const SKELETON_PULSE_MS = 900;
+export const SKELETON_PULSE_MIN_OPACITY = 0.5;
+export const SKELETON_TEXT_HEIGHT = 12;
+export const SKELETON_TEXT_GAP = 8;
+export const SKELETON_BLOCK_HEIGHT = 96;
+export const SKELETON_CIRCLE_SIZE = 40;
+export const SKELETON_LIST_ROWS = 3;
+
+// A paragraph's last line stops short, as real text does.
+const LAST_LINE_WIDTH = "60%";
+// A list row's title and subtitle.
+export const SKELETON_LIST_ROW_LINE_WIDTHS = Object.freeze(["45%", "30%"]);
+
+// Per-instance overrides a widget may pass, named as the theme tokens are.
+export const LOADING_TOKEN_NAMES = Object.freeze(["skeletonColor", "skeletonRadius"]);
+
+function isSet(value) {
+  return value !== undefined && value !== null && value !== "";
+}
+
+function pick(overrides, scope, name) {
+  if (overrides && isSet(overrides[name])) return overrides[name];
+  if (scope && isSet(scope[name])) return scope[name];
+  return undefined;
+}
+
+/**
+ * Resolve a skeleton's look: explicit override, then the theme's `loading`
+ * scope, then the theme tokens. The scope passes the contract's own bounds, so
+ * a hand-edited theme cannot reach a native style unvalidated.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @param {object} [overrides] — per-instance values keyed by LOADING_TOKEN_NAMES.
+ */
+export function resolveLoadingTokens(theme, overrides) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const colors = base.colors || DEFAULT_THEME_TOKENS.colors;
+  const radii = base.radii || DEFAULT_THEME_TOKENS.radii;
+  const scope = normaliseThemeComponents({
+    loading: base.components && base.components.loading,
+  }).loading;
+  return {
+    skeletonColor: pick(overrides, scope, "skeletonColor") ?? colors.surfaceMuted,
+    skeletonRadius: pick(overrides, scope, "skeletonRadius") ?? radii.sm,
+  };
+}
+
+/**
+ * A spinner's colour: the one a widget passed, else the theme's `loader`, the
+ * app's Loading Indicator colour, which each painted surface re-derives.
+ */
+export function resolveSpinnerColor(theme, color) {
+  if (isSet(color)) return color;
+  const colors = (theme && theme.colors) || DEFAULT_THEME_TOKENS.colors;
+  return colors.loader || DEFAULT_THEME_TOKENS.colors.loader;
+}
+
+/** A spinner's diameter: a named size, or the number a widget passed. */
+export function spinnerDiameter(size) {
+  if (typeof size === "number" && Number.isFinite(size) && size > 0) return size;
+  return SPINNER_SIZES[size] || SPINNER_SIZES[DEFAULT_SPINNER_SIZE];
+}
+
+export function spinnerStrokeWidth(diameter) {
+  return Math.max(2, Math.round(diameter / 8));
+}
+
+export function normaliseSkeletonShape(shape) {
+  return SKELETON_SHAPES.includes(shape) ? shape : DEFAULT_SKELETON_SHAPE;
+}
+
+/**
+ * The box one bone is drawn in.
+ *
+ * @param {"text"|"block"|"circle"} shape
+ * @param {{ width?: number|string, height?: number, size?: number }} dims
+ * @param {number} radius — the resolved `skeletonRadius`.
+ */
+export function skeletonBox(shape, dims, radius) {
+  const { width, height, size } = dims || {};
+  if (shape === "circle") {
+    const diameter = isSet(size) ? size : SKELETON_CIRCLE_SIZE;
+    return { width: diameter, height: diameter, borderRadius: diameter / 2 };
+  }
+  return {
+    width: isSet(width) ? width : "100%",
+    height: isSet(height)
+      ? height
+      : shape === "block"
+        ? SKELETON_BLOCK_HEIGHT
+        : SKELETON_TEXT_HEIGHT,
+    borderRadius: radius,
+  };
+}
+
+/** The width of each line of a `text` skeleton, top to bottom. */
+export function skeletonLineWidths(lines, width) {
+  const count = Math.max(1, Math.floor(Number(lines) || 1));
+  const full = isSet(width) ? width : "100%";
+  return Array.from({ length: count }, (_, i) =>
+    count > 1 && i === count - 1 ? LAST_LINE_WIDTH : full,
+  );
+}
+
+export function skeletonListRowCount(count) {
+  const n = Math.floor(Number(count));
+  return Number.isFinite(n) && n > 0 ? n : SKELETON_LIST_ROWS;
+}

package/dist/loading-view.js

@@ -0,0 +1,330 @@
+// The ONE implementation behind `<Spinner>` and `<Skeleton>`. The bindings
+// (`loading.js` / `loading.native.js`) differ only in their primitives.
+
+import React from "react";
+import { useHostTheme, useHostSharedText } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { CONTRACT } from "./contract.js";
+import { resolveListTokens, listRowFrame } from "./list-tokens.js";
+import { textRoleStyle } from "./text-roles.js";
+import { flattenStyle } from "./flatten-style.js";
+import {
+  resolveLoadingTokens,
+  resolveSpinnerColor,
+  spinnerDiameter,
+  spinnerStrokeWidth,
+  normaliseSkeletonShape,
+  skeletonBox,
+  skeletonLineWidths,
+  skeletonListRowCount,
+  SPINNER_TURN_MS,
+  SKELETON_PULSE_MS,
+  SKELETON_PULSE_MIN_OPACITY,
+  SKELETON_TEXT_GAP,
+  SKELETON_LIST_ROW_LINE_WIDTHS,
+} from "./loading-tokens.js";
+
+const LOADING_FALLBACK = CONTRACT.sharedTranslationKeys.loading.en;
+const FILL = { position: "absolute", top: 0, right: 0, bottom: 0, left: 0 };
+const TRACK_OPACITY = 0.2;
+const HIDDEN = { "aria-hidden": true, importantForAccessibility: "no-hide-descendants" };
+
+// A labelled element in the busy state, on both hosts.
+function busyRegion(label) {
+  return { accessible: true, accessibilityLabel: label, "aria-busy": true };
+}
+
+// The web needs a role to expose the label; native has none for `status`.
+const LOADING_REGION = { role: "status" };
+
+/**
+ * Bind the shared loading components to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Animated: any, Easing: any, AccessibilityInfo: any}} rn
+ * @param {{ useNativeDriver: boolean }} options — false where no native driver exists.
+ */
+export function makeLoading(rn, { useNativeDriver }) {
+  const { View, Text, Animated, Easing, AccessibilityInfo } = rn;
+
+  // One listener for every loading state on screen. Reduced until the host
+  // answers, so nothing moves for a user who asked it not to.
+  const motion = (() => {
+    let reduced = true;
+    let subscription = null;
+    const listeners = new Set();
+    const set = (value) => {
+      if (reduced === !!value) return;
+      reduced = !!value;
+      listeners.forEach((notify) => notify());
+    };
+    const subscribe = (notify) => {
+      listeners.add(notify);
+      if (listeners.size === 1) {
+        AccessibilityInfo.isReduceMotionEnabled().then(set, () => {});
+        subscription = AccessibilityInfo.addEventListener("reduceMotionChanged", set);
+      }
+      return () => {
+        listeners.delete(notify);
+        if (listeners.size > 0) return;
+        if (subscription && typeof subscription.remove === "function") subscription.remove();
+        subscription = null;
+      };
+    };
+    return { subscribe, isReduced: () => reduced };
+  })();
+
+  function useReducedMotion() {
+    return React.useSyncExternalStore(motion.subscribe, motion.isReduced, motion.isReduced);
+  }
+
+  // One running animation however many components draw from it. Nothing is
+  // allocated until the first loading state asks for it.
+  function sharedLoop(build, project) {
+    let value = null;
+    let output = null;
+    let users = 0;
+    let loop = null;
+    const animated = () => {
+      if (!value) {
+        value = new Animated.Value(0);
+        output = project(value);
+      }
+      return output;
+    };
+    const retain = () => {
+      animated();
+      users += 1;
+      if (users === 1) {
+        loop = Animated.loop(build(value));
+        loop.start();
+      }
+      return () => {
+        users -= 1;
+        if (users > 0) return;
+        loop.stop();
+        loop = null;
+        value.setValue(0);
+      };
+    };
+    return { animated, retain };
+  }
+
+  const turn = sharedLoop(
+    (value) =>
+      Animated.timing(value, {
+        toValue: 1,
+        duration: SPINNER_TURN_MS,
+        easing: Easing.linear,
+        useNativeDriver,
+      }),
+    (value) => value.interpolate({ inputRange: [0, 1], outputRange: ["0deg", "360deg"] }),
+  );
+
+  const breathe = (value, toValue) =>
+    Animated.timing(value, {
+      toValue,
+      duration: SKELETON_PULSE_MS,
+      easing: Easing.inOut(Easing.ease),
+      useNativeDriver,
+    });
+  const pulse = sharedLoop(
+    (value) => Animated.sequence([breathe(value, 1), breathe(value, 0)]),
+    (value) =>
+      value.interpolate({ inputRange: [0, 1], outputRange: [1, SKELETON_PULSE_MIN_OPACITY] }),
+  );
+
+  function useSharedLoop(loop, moving) {
+    React.useEffect(() => (moving ? loop.retain() : undefined), [loop, moving]);
+  }
+
+  function useLoadingTheme(explicitTheme) {
+    const hostTheme = useHostTheme();
+    // A host drawing outside a widget context passes its own theme.
+    return explicitTheme || hostTheme || DEFAULT_THEME_TOKENS;
+  }
+
+  function Spinner({
+    size,
+    color,
+    label,
+    accessibilityLabel,
+    theme: explicitTheme,
+    style,
+    testID,
+  }) {
+    const theme = useLoadingTheme(explicitTheme);
+    const loadingText = useHostSharedText("loading", LOADING_FALLBACK);
+    const moving = !useReducedMotion();
+    useSharedLoop(turn, moving);
+
+    const ink = resolveSpinnerColor(theme, color);
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    const diameter = spinnerDiameter(size);
+    const ring = {
+      ...FILL,
+      borderRadius: diameter / 2,
+      borderWidth: spinnerStrokeWidth(diameter),
+    };
+    const hasLabel = label !== undefined && label !== null && label !== "";
+    // A string caption is already the spinner's name; a node speaks for itself.
+    const named = typeof label === "string" && label !== "";
+
+    return React.createElement(
+      View,
+      {
+        ...busyRegion(accessibilityLabel || (named && label) || loadingText),
+        accessibilityRole: "progressbar",
+        style: [{ alignItems: "center", justifyContent: "center", gap: spacing.sm }, style],
+        testID,
+      },
+      React.createElement(
+        Animated.View,
+        {
+          ...HIDDEN,
+          style: [
+            { width: diameter, height: diameter },
+            moving ? { transform: [{ rotate: turn.animated() }] } : null,
+          ],
+        },
+        React.createElement(View, {
+          style: [ring, { borderColor: ink, opacity: TRACK_OPACITY }],
+        }),
+        React.createElement(View, {
+          style: [ring, { borderColor: "transparent", borderTopColor: ink }],
+        }),
+      ),
+      hasLabel
+        ? React.createElement(
+            Text,
+            {
+              ...(named ? HIDDEN : null),
+              style: textRoleStyle(
+                "caption",
+                theme.typography || DEFAULT_THEME_TOKENS.typography,
+                theme.colors || DEFAULT_THEME_TOKENS.colors,
+              ),
+            },
+            label,
+          )
+        : null,
+    );
+  }
+  Spinner.displayName = "Spinner";
+
+  // True inside a `<Skeleton>` that already is the loading region.
+  const RegionContext = React.createContext(false);
+
+  // A bone the widget sizes by aspect ratio must not keep the default height.
+  function boneBox(box, style) {
+    if (flattenStyle(style).aspectRatio === undefined) return box;
+    const { height: _defaultHeight, ...rest } = box;
+    return rest;
+  }
+
+  function boneStyle(box, tokens, style) {
+    return [boneBox(box, style), { backgroundColor: tokens.skeletonColor }, style];
+  }
+
+  function bone(shape, dims, tokens, key) {
+    return React.createElement(View, {
+      ...HIDDEN,
+      key,
+      style: boneStyle(skeletonBox(shape, dims, tokens.skeletonRadius), tokens),
+    });
+  }
+
+  function listRows(theme, tokens, { count, leading = true }) {
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    // The real rows' own frame, so nothing shifts when they arrive.
+    const list = resolveListTokens(theme);
+    const rows = skeletonListRowCount(count);
+    return Array.from({ length: rows }, (_, row) =>
+      React.createElement(
+        View,
+        {
+          key: row,
+          style: {
+            ...listRowFrame(list, spacing),
+            paddingVertical: list.rowPadding,
+            minHeight: list.rowMinHeight,
+            ...(!list.separated && row < rows - 1 && list.dividerWidth > 0
+              ? { borderBottomWidth: list.dividerWidth, borderColor: list.dividerColor }
+              : null),
+          },
+        },
+        leading ? bone("circle", null, tokens, "leading") : null,
+        React.createElement(
+          View,
+          { style: { flex: 1, gap: SKELETON_TEXT_GAP } },
+          ...SKELETON_LIST_ROW_LINE_WIDTHS.map((width) => bone("text", { width }, tokens, width)),
+        ),
+      ),
+    );
+  }
+
+  // What a skeleton of several bones holds; null when it is a single bone.
+  function composite(kind, props, theme, tokens) {
+    if (props.children !== undefined && props.children !== null) {
+      return { content: props.children, layout: null };
+    }
+    if (kind === "listRow") {
+      return {
+        content: listRows(theme, tokens, props),
+        layout: { gap: resolveListTokens(theme).gap },
+      };
+    }
+    if (kind !== "text" || !(props.lines > 1)) return null;
+    const { lines, width, height } = props;
+    return {
+      content: skeletonLineWidths(lines, width).map((lineWidth, i) =>
+        bone("text", { width: lineWidth, height }, tokens, i),
+      ),
+      layout: { gap: SKELETON_TEXT_GAP },
+    };
+  }
+
+  function Skeleton(props) {
+    const { shape, accessibilityLabel, theme: explicitTheme, style, testID } = props;
+    const theme = useLoadingTheme(explicitTheme);
+    const loadingText = useHostSharedText("loading", LOADING_FALLBACK);
+    const nested = React.useContext(RegionContext);
+    // The outermost skeleton pulses as one; the bones inside it never animate.
+    const moving = !useReducedMotion() && !nested;
+    useSharedLoop(pulse, moving);
+
+    const tokens = resolveLoadingTokens(theme, {
+      skeletonColor: props.color,
+      skeletonRadius: props.radius,
+    });
+    const kind = normaliseSkeletonShape(shape);
+    const group = composite(kind, props, theme, tokens);
+    const own = group
+      ? [group.layout, style]
+      : boneStyle(skeletonBox(kind, props, tokens.skeletonRadius), tokens, style);
+
+    if (nested) {
+      return React.createElement(
+        View,
+        { ...(group ? null : HIDDEN), style: own, testID },
+        group && group.content,
+      );
+    }
+    return React.createElement(
+      RegionContext.Provider,
+      { value: true },
+      React.createElement(
+        Animated.View,
+        {
+          ...busyRegion(accessibilityLabel || loadingText),
+          ...LOADING_REGION,
+          style: [own, moving ? { opacity: pulse.animated() } : null],
+          testID,
+        },
+        group && group.content,
+      ),
+    );
+  }
+  Skeleton.displayName = "Skeleton";
+
+  return { Spinner, Skeleton };
+}

package/dist/loading.js

@@ -0,0 +1,7 @@
+// `<Spinner>` and `<Skeleton>` (web). Binds ./loading-view.js to
+// react-native-web; see ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { makeLoading } from "./loading-view.js";
+
+export const { Spinner, Skeleton } = makeLoading(ReactNative, { useNativeDriver: false });

package/dist/loading.native.js

@@ -0,0 +1,10 @@
+// `<Spinner>` and `<Skeleton>` (native). Binds ./loading-view.js to React
+// Native's own primitives; only the import differs from ./loading.js.
+
+import { View, Text, Animated, Easing, AccessibilityInfo } from "react-native";
+import { makeLoading } from "./loading-view.js";
+
+export const { Spinner, Skeleton } = makeLoading(
+  { View, Text, Animated, Easing, AccessibilityInfo },
+  { useNativeDriver: true },
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.201.0",
+  "version": "0.204.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",