@colixsystems/widget-sdk 0.170.0 → 0.173.1

package/dist/detail-parts-view.js

@@ -0,0 +1,392 @@
+// The ONE implementation behind the `<Badge>`, `<Avatar>`, `<Progress>`,
+// `<Stat>` and `<Divider>` SDK components and the stock widgets of the same
+// names. The bindings (`detail-parts.js` / `detail-parts.native.js`) differ
+// only in where the primitives come from, so the hosts cannot drift.
+//
+// Meaning is never carried by colour alone: a badge always prints its label, a
+// progress its percent (unless the caller hides it), a stat's delta its sign.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { lucideGlyph, Icon } from "./icon.js";
+import { initialsFor } from "./initials.js";
+import {
+  avatarPixelSize,
+  badgeTint,
+  clampPercent,
+  dividerSpacing,
+  dividerThickness,
+  hasStatValue,
+  progressColor,
+  statDeltaColor,
+  statFontSize,
+} from "./detail-parts-tokens.js";
+
+const RING_SIZE_PX = 72;
+const RING_STROKE_PX = 8;
+const h = React.createElement;
+
+// Outside a widget host (a test, a preview) the defaults still paint.
+function useDetailTheme() {
+  return useHostTheme() || DEFAULT_THEME_TOKENS;
+}
+
+function glyph(name, size, color) {
+  const Glyph = lucideGlyph(name);
+  return Glyph ? h(Glyph, { size, color }) : null;
+}
+
+// A count badge may be a number; an empty one still shows it is a badge.
+function badgeText(label) {
+  if (typeof label === "number" && Number.isFinite(label)) return String(label);
+  return typeof label === "string" && label !== "" ? label : "Badge";
+}
+
+function captionText(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+/**
+ * Bind the detail parts to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Image: any, Svg: any, Circle: any}} rn
+ */
+export function makeDetailParts(rn) {
+  const { View, Text, Image, Svg, Circle } = rn;
+
+  function Badge({ label, tone = "neutral", icon, style, testID }) {
+    const { colors, spacing, radii, typography } = useDetailTheme();
+    const tint = badgeTint(colors, tone);
+    const text = badgeText(label);
+    const pill = {
+      // A pill hugs its label instead of stretching across a column.
+      alignSelf: "flex-start",
+      flexDirection: "row",
+      alignItems: "center",
+      gap: spacing.xs,
+      borderRadius: radii.pill,
+      paddingVertical: spacing.xs,
+      paddingHorizontal: spacing.sm,
+      backgroundColor: tint.backgroundColor,
+    };
+    const labelStyle = {
+      color: tint.color,
+      fontSize: typography.sizes.xs,
+      fontWeight: "600",
+      fontFamily: typography.fontFamily,
+    };
+    return h(
+      View,
+      { style: [pill, style], testID },
+      glyph(icon, typography.sizes.xs, tint.color),
+      h(Text, { style: labelStyle }, text),
+    );
+  }
+  Badge.displayName = "Badge";
+
+  function Avatar({ name, url, size = "md", shape = "circle", accessibilityLabel, style, testID }) {
+    const { colors, radii, typography } = useDetailTheme();
+    const px = avatarPixelSize(size);
+    const box = {
+      alignSelf: "flex-start",
+      width: px,
+      height: px,
+      borderRadius: shape === "rounded" ? radii.md : px / 2,
+      backgroundColor: colors.surfaceMuted,
+    };
+    const source = typeof url === "string" ? url.trim() : "";
+    const label = accessibilityLabel || captionText(name) || "Avatar";
+    if (source) {
+      return h(Image, {
+        source: { uri: source },
+        accessibilityLabel: label,
+        resizeMode: "cover",
+        style: [box, style],
+        testID,
+      });
+    }
+    const initials = initialsFor(name);
+    const fallback = { alignItems: "center", justifyContent: "center" };
+    const content = initials
+      ? h(
+          Text,
+          {
+            style: {
+              color: colors.onSurfaceMuted,
+              fontWeight: "600",
+              fontFamily: typography.fontFamily,
+              fontSize: Math.round(px * 0.4),
+            },
+          },
+          initials,
+        )
+      : h(Icon, { name: "user", size: Math.round(px * 0.55), color: colors.onSurfaceMuted });
+    return h(View, { style: [box, fallback, style], accessibilityLabel: label, testID }, content);
+  }
+  Avatar.displayName = "Avatar";
+
+  function ProgressRing({ percent, fill, showValue, caption, theme }) {
+    const { colors, spacing, typography } = theme;
+    const radius = (RING_SIZE_PX - RING_STROKE_PX) / 2;
+    const circumference = 2 * Math.PI * radius;
+    const centre = RING_SIZE_PX / 2;
+    const ring = { cx: centre, cy: centre, r: radius, strokeWidth: RING_STROKE_PX, fill: "none" };
+    return h(
+      View,
+      { style: { alignItems: "center" } },
+      h(
+        View,
+        { style: { width: RING_SIZE_PX, height: RING_SIZE_PX } },
+        h(
+          Svg,
+          { width: RING_SIZE_PX, height: RING_SIZE_PX },
+          h(Circle, { ...ring, stroke: colors.surfaceMuted }),
+          h(Circle, {
+            ...ring,
+            stroke: fill,
+            strokeLinecap: "round",
+            strokeDasharray: `${circumference} ${circumference}`,
+            strokeDashoffset: circumference * (1 - percent / 100),
+            rotation: -90,
+            originX: centre,
+            originY: centre,
+          }),
+        ),
+        showValue
+          ? h(
+              View,
+              {
+                style: {
+                  position: "absolute",
+                  top: 0,
+                  left: 0,
+                  right: 0,
+                  bottom: 0,
+                  alignItems: "center",
+                  justifyContent: "center",
+                },
+              },
+              h(
+                Text,
+                {
+                  style: {
+                    fontSize: typography.sizes.md,
+                    fontWeight: "700",
+                    color: colors.onSurface,
+                    fontFamily: typography.fontFamily,
+                  },
+                },
+                `${Math.round(percent)}%`,
+              ),
+            )
+          : null,
+      ),
+      caption
+        ? h(
+            Text,
+            {
+              style: {
+                marginTop: spacing.xs,
+                fontSize: typography.sizes.sm,
+                color: colors.onSurfaceMuted,
+                fontFamily: typography.fontFamily,
+              },
+            },
+            caption,
+          )
+        : null,
+    );
+  }
+
+  function ProgressBar({ percent, fill, showValue, caption, theme }) {
+    const { colors, spacing, radii, typography } = theme;
+    const small = { fontSize: typography.sizes.sm, fontFamily: typography.fontFamily };
+    const header =
+      caption || showValue
+        ? h(
+            View,
+            {
+              style: {
+                flexDirection: "row",
+                alignItems: "center",
+                justifyContent: "flex-end",
+                marginBottom: spacing.xs,
+              },
+            },
+            caption
+              ? h(Text, { style: { ...small, flex: 1, color: colors.onSurfaceMuted } }, caption)
+              : null,
+            showValue
+              ? h(
+                  Text,
+                  {
+                    style: {
+                      ...small,
+                      marginLeft: spacing.xs,
+                      fontWeight: "600",
+                      color: colors.onSurface,
+                    },
+                  },
+                  `${Math.round(percent)}%`,
+                )
+              : null,
+          )
+        : null;
+    const track = {
+      width: "100%",
+      height: spacing.sm,
+      borderRadius: radii.pill,
+      backgroundColor: colors.surfaceMuted,
+      overflow: "hidden",
+    };
+    return h(
+      View,
+      { style: { width: "100%" } },
+      header,
+      h(
+        View,
+        { style: track },
+        h(View, {
+          style: {
+            height: "100%",
+            borderRadius: radii.pill,
+            width: `${percent}%`,
+            backgroundColor: fill,
+          },
+        }),
+      ),
+    );
+  }
+
+  function Progress({ value = 0, variant = "bar", label, showValue = true, tone = "primary", style, testID }) {
+    const theme = useDetailTheme();
+    const percent = clampPercent(value);
+    const parts = {
+      percent,
+      fill: progressColor(theme.colors, tone),
+      showValue: showValue !== false,
+      caption: captionText(label),
+      theme,
+    };
+    return h(
+      View,
+      {
+        style: [{ width: "100%" }, style],
+        // The aria props, not accessibilityValue: react-native-web drops that one.
+        role: "progressbar",
+        "aria-valuemin": 0,
+        "aria-valuemax": 100,
+        "aria-valuenow": Math.round(percent),
+        testID,
+      },
+      variant === "ring" ? h(ProgressRing, parts) : h(ProgressBar, parts),
+    );
+  }
+  Progress.displayName = "Progress";
+
+  function Stat({
+    value,
+    label,
+    icon,
+    delta,
+    deltaTone = "neutral",
+    emptyValue = "—",
+    color,
+    fontSize,
+    style,
+    testID,
+  }) {
+    const { colors, spacing, typography } = useDetailTheme();
+    const empty = !hasStatValue(value);
+    const shown = empty ? (typeof emptyValue === "string" ? emptyValue : "") : String(value);
+    const size = statFontSize(fontSize, typography);
+    const valueColor = empty ? colors.onSurfaceMuted : color || colors.onSurface;
+    const deltaText = captionText(delta);
+    const caption = typeof label === "string" ? label : "";
+    return h(
+      View,
+      { style: [{ alignItems: "flex-start" }, style], testID },
+      h(
+        View,
+        { style: { flexDirection: "row", alignItems: "center", gap: spacing.xs } },
+        glyph(icon, Math.max(12, Math.round(size * 0.75)), valueColor),
+        h(
+          Text,
+          {
+            style: {
+              fontWeight: "700",
+              fontFamily: typography.headingFontFamily,
+              fontSize: size,
+              color: valueColor,
+            },
+          },
+          shown,
+        ),
+        deltaText
+          ? h(
+              Text,
+              {
+                style: {
+                  fontSize: typography.sizes.sm,
+                  fontWeight: "600",
+                  fontFamily: typography.fontFamily,
+                  color: statDeltaColor(colors, deltaTone),
+                },
+              },
+              deltaText,
+            )
+          : null,
+      ),
+      caption
+        ? h(
+            Text,
+            {
+              style: {
+                marginTop: spacing.xs,
+                fontSize: typography.sizes.sm,
+                color: colors.onSurfaceMuted,
+                fontFamily: typography.fontFamily,
+              },
+            },
+            caption,
+          )
+        : null,
+    );
+  }
+  Stat.displayName = "Stat";
+
+  function Divider({ label, thickness = 1, spacing = "md", color, style, testID }) {
+    const theme = useDetailTheme();
+    const caption = captionText(label);
+    const rule = {
+      height: dividerThickness(thickness),
+      backgroundColor: color || theme.colors.border,
+    };
+    const root = { width: "100%", paddingVertical: theme.spacing[dividerSpacing(spacing)] };
+    const body = caption
+      ? h(
+          View,
+          { style: { flexDirection: "row", alignItems: "center" } },
+          h(View, { style: [{ flex: 1 }, rule] }),
+          h(
+            Text,
+            {
+              style: {
+                marginHorizontal: theme.spacing.sm,
+                fontSize: theme.typography.sizes.sm,
+                color: theme.colors.onSurfaceMuted,
+                fontFamily: theme.typography.fontFamily,
+              },
+            },
+            caption,
+          ),
+          h(View, { style: [{ flex: 1 }, rule] }),
+        )
+      : h(View, { style: [{ width: "100%" }, rule] });
+    return h(View, { style: [root, style], testID }, body);
+  }
+  Divider.displayName = "Divider";
+
+  return { Badge, Avatar, Progress, Stat, Divider };
+}

package/dist/detail-parts.js

@@ -0,0 +1,15 @@
+// `<Badge>`, `<Avatar>`, `<Progress>`, `<Stat>`, `<Divider>` (web). Binds
+// ./detail-parts-view.js to react-native-web; see ./primitives.js for why not
+// the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import Svg, { Circle } from "react-native-svg";
+import { makeDetailParts } from "./detail-parts-view.js";
+
+export const { Badge, Avatar, Progress, Stat, Divider } = makeDetailParts({
+  View: ReactNative.View,
+  Text: ReactNative.Text,
+  Image: ReactNative.Image,
+  Svg,
+  Circle,
+});

package/dist/detail-parts.native.js

@@ -0,0 +1,15 @@
+// `<Badge>`, `<Avatar>`, `<Progress>`, `<Stat>`, `<Divider>` (native). Binds
+// ./detail-parts-view.js to React Native; only the imports differ from
+// ./detail-parts.js.
+
+import { View, Text, Image } from "react-native";
+import Svg, { Circle } from "react-native-svg";
+import { makeDetailParts } from "./detail-parts-view.js";
+
+export const { Badge, Avatar, Progress, Stat, Divider } = makeDetailParts({
+  View,
+  Text,
+  Image,
+  Svg,
+  Circle,
+});

package/dist/index.d.ts

@@ -160,9 +160,10 @@ export interface WidgetInputDescriptor {
  *   - At most 24 columns per table. Same reason.
  *
  * RELATION columns reference siblings within the same template via
- * `targetSuffix` — that suffix MUST belong to a table declared earlier
- * in the array. There is intentionally no way to reference a table
- * outside the widget's own template.
+ * `targetSuffix` — that suffix MUST belong to a table in the same array,
+ * declared anywhere in it; tables may relate to each other both ways.
+ * There is intentionally no way to reference a table outside the
+ * widget's own template.
  */
 export interface WidgetDatastoreTemplateColumn {
   name: string;
@@ -896,6 +897,13 @@ export interface DirectoryResult {
  */
 export function useDirectory(query?: DirectoryQuery): DirectoryResult;
 
+/**
+ * The emitter for an event the manifest declares. A sibling's wired input
+ * reads the payload, and a page action the author binds to the event (Run
+ * action, Navigate) runs with it — fired from one control, only that control
+ * runs it. Never declare an event named `onPress`: that binding makes the
+ * whole widget one tap target.
+ */
 export function useWidgetEvent(name: string): (payload?: unknown) => void;
 
 /**
@@ -2601,7 +2609,48 @@ export const ListRow: (props: ListRowTokens & {
   accessibilityLabel?: string;
   style?: any;
   testID?: string;
-  /** Replaces the title block, e.g. for a multi-column row. */
+  /**
+   * Replaces the title block, e.g. for a multi-column row. A single `View`
+   * child spans the row between `leading` and `trailing`; anything else
+   * (several cells, say) sits in the row as given.
+   */
+  children?: ReactNode;
+}) => any;
+
+/**
+ * A table's column labels. Shares `<ListRow>`'s horizontal padding, gap and
+ * side edges (from the same Theme Settings > Lists values), so a label given
+ * the same flex as its row cell sits exactly over that column. Pass it the
+ * same overrides as the `<List>`. Make it the rows' `ScrollView`'s first,
+ * sticky child so it shares their width beside a scrollbar.
+ *
+ * @example
+ *   <ScrollView stickyHeaderIndices={[0]}>
+ *     <ListHeader style={{ backgroundColor: theme.colors.surface }}>
+ *       <Text style={[overline, { flex: 2, minWidth: 0 }]}>Name</Text>
+ *       <Text style={[overline, { flex: 1, minWidth: 0 }]}>Status</Text>
+ *     </ListHeader>
+ *     <List>
+ *       {rows.map((r) => (
+ *         <ListRow key={r.id} onPress={() => open(r)}>
+ *           <Text numberOfLines={1} style={[body, { flex: 2, minWidth: 0 }]}>{r.name}</Text>
+ *           <Text numberOfLines={1} style={[body, { flex: 1, minWidth: 0 }]}>{r.status}</Text>
+ *         </ListRow>
+ *       ))}
+ *     </List>
+ *   </ScrollView>
+ */
+export const ListHeader: (props: Pick<ListRowTokens, "rowPadding" | "gap" | "dividerColor" | "dividerWidth"> & {
+  /** A spacer as wide as the rows' `leading`, so the columns still line up. */
+  leading?: ReactNode;
+  /** A spacer (or label) as wide as the rows' `trailing`. */
+  trailing?: ReactNode;
+  /** The divider under the labels. Defaults to true. */
+  divider?: boolean;
+  accessibilityLabel?: string;
+  style?: any;
+  testID?: string;
+  /** The column labels, shaped exactly like the rows' `children`. */
   children?: ReactNode;
 }) => any;
 
@@ -2616,6 +2665,82 @@ export const EmptyState: (props: {
   children?: ReactNode;
 }) => any;
 
+/**
+ * Themed status pill: a record's state (Active, Paid, Overdue) beside the
+ * thing it describes. The label always renders; the tone only tints it.
+ *
+ * @example
+ *   <Badge label={row.status} tone="success" />
+ */
+export const Badge: (props: {
+  label?: string | number;
+  tone?: "neutral" | "info" | "success" | "warning" | "danger";
+  /** A lucide icon name shown before the label. */
+  icon?: string;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/** Themed picture of a person, falling back to initials, then a glyph. */
+export const Avatar: (props: {
+  /** Drives the initials and the accessibility label. */
+  name?: string;
+  /** An absolute image URL. */
+  url?: string;
+  /** A size token, or a number of px (clamped to 16-160). */
+  size?: "sm" | "md" | "lg" | "xl" | number;
+  shape?: "circle" | "rounded";
+  accessibilityLabel?: string;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/** Themed completion bar or ring for real progress toward a known goal. */
+export const Progress: (props: {
+  /** Percent complete; clamped to 0-100. */
+  value?: number;
+  variant?: "bar" | "ring";
+  label?: string;
+  /** Render the percent as text. Default true. */
+  showValue?: boolean;
+  tone?: "primary" | "success" | "warning" | "danger";
+  style?: any;
+  testID?: string;
+}) => any;
+
+/** Themed headline figure. Displays a value you computed; it fetches nothing. */
+export const Stat: (props: {
+  /** The figure. Empty (null, blank, NaN) prints `emptyValue` instead. */
+  value?: string | number | null;
+  label?: string;
+  /** A lucide icon name beside the figure. */
+  icon?: string;
+  delta?: string;
+  deltaTone?: "neutral" | "positive" | "negative";
+  /** Printed when `value` is empty. Default "—". */
+  emptyValue?: string;
+  color?: string;
+  /** The figure's size in px (12-96); defaults to the theme's xxl. */
+  fontSize?: number;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/** Themed rule splitting two groups inside one surface; optionally captioned. */
+export const Divider: (props: {
+  label?: string;
+  /** Line thickness in px, 1-8. */
+  thickness?: number;
+  spacing?: "sm" | "md" | "lg";
+  /** Defaults to the theme's border colour. */
+  color?: string;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/** A person's initials: "Ada Lovelace" → "AL"; "" when the name has no letters. */
+export function initialsFor(name: unknown): string;
+
 /**
  * Themed card surface. With no props it takes the app's card look (Theme
  * Settings > Cards). Props override one card; `style` takes the `card*` style

package/dist/index.js

@@ -196,7 +196,10 @@ export {
 } from "./emoji-reactions.js";
 export { insertAtCaret, pushRecentEmoji } from "./emoji-picker-tokens.js";
 // Themed list building blocks; rows follow the theme's `list` scope.
-export { List, ListRow, EmptyState } from "./list.js";
+export { List, ListRow, ListHeader, EmptyState } from "./list.js";
+// Themed detail parts; the stock Badge/Avatar/Progress/Stat/Divider wrap these.
+export { Badge, Avatar, Progress, Stat, Divider } from "./detail-parts.js";
+export { initialsFor } from "./initials.js";
 // The one card surface: the theme's `card` scope, a gradient fill, margin.
 export { Card } from "./card.js";
 export {

package/dist/index.native.js

@@ -189,7 +189,10 @@ export {
 } from "./emoji-reactions.js";
 export { insertAtCaret, pushRecentEmoji } from "./emoji-picker-tokens.js";
 // Themed list building blocks; rows follow the theme's `list` scope.
-export { List, ListRow, EmptyState } from "./list.native.js";
+export { List, ListRow, ListHeader, EmptyState } from "./list.native.js";
+// Themed detail parts; the stock Badge/Avatar/Progress/Stat/Divider wrap these.
+export { Badge, Avatar, Progress, Stat, Divider } from "./detail-parts.native.js";
+export { initialsFor } from "./initials.js";
 // The one card surface: the theme's `card` scope, a gradient fill, margin.
 export { Card } from "./card.native.js";
 export {

package/dist/initials.js

@@ -0,0 +1,17 @@
+// The ONE initials rule, for `<Avatar>` and every built-in that falls back to a
+// person's initials. Two rules would print different letters for one person.
+//
+// Returns "" when the name yields no letters, so each caller keeps its own
+// fallback (a "?", a person glyph).
+
+/** "Ada Lovelace" → "AL", "Ada" → "A", "  " → "". */
+export function initialsFor(name) {
+  const parts =
+    typeof name === "string" ? name.trim().split(/\s+/).filter(Boolean) : [];
+  if (parts.length === 0) return "";
+  // Array.from, not slice: a multi-byte first character must not be halved.
+  const first = Array.from(parts[0])[0];
+  if (parts.length === 1) return first.toUpperCase();
+  const last = Array.from(parts[parts.length - 1])[0];
+  return (first + last).toUpperCase();
+}

package/dist/list-tokens.js

@@ -9,6 +9,9 @@ import { normaliseThemeComponents } from "./theme-components.js";
 // A row with no themed height still meets the 44px touch-target floor.
 export const LIST_ROW_MIN_HEIGHT = 44;
 
+// The accent bar a selected row carries on its leading edge.
+export const LIST_SELECTED_BAR_WIDTH = 3;
+
 // The per-row overrides a widget may pass, named as the theme tokens are.
 export const LIST_TOKEN_NAMES = Object.freeze([
   "rowPadding",
@@ -66,3 +69,31 @@ export function resolveListTokens(theme, overrides) {
     pressedBackground: mixHex(colors.onSurface, background || colors.surface, 0.94),
   };
 }
+
+/** The width of a row's side edges: a tile's outline, none on a flush band. */
+export function listSideEdgeWidth(tokens) {
+  return tokens.separated ? tokens.dividerWidth : 0;
+}
+
+/**
+ * The horizontal geometry `<ListRow>` and `<ListHeader>` share: the direction,
+ * the gap between leading, body and trailing, and the inset. Both draw from
+ * this one function, so a header cell sits over its row cell by construction.
+ *
+ * @param {ReturnType<typeof resolveListTokens>} tokens
+ * @param {{ md: number }} spacing — the theme's spacing scale.
+ * @param {boolean} [selected] — the row carries the accent bar.
+ */
+export function listRowFrame(tokens, spacing, selected = false) {
+  const frame = {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: spacing.md,
+    paddingHorizontal: tokens.rowPadding,
+  };
+  if (!selected) return frame;
+  // The bar replaces the side edge and takes its width out of the inset,
+  // so a row's cells do not move when it is selected.
+  const inset = tokens.rowPadding + listSideEdgeWidth(tokens) - LIST_SELECTED_BAR_WIDTH;
+  return { ...frame, paddingLeft: Math.max(0, inset) };
+}