@colixsystems/widget-sdk 0.237.0 → 0.239.0

package/dist/index.d.ts

@@ -39,6 +39,9 @@ export type WidgetPropertyType =
   // REQ-WDG-PAGEREF: page picker that emits a bare AppPage UUID; a widget
   // reads it and navigates via useNavigation().goTo(pageId, params).
   | "pageRef"
+  // REQ-BLD-19: section picker for the widget's own page → bare node id; a
+  // widget scrolls to it via useNavigation().scrollToSection(id).
+  | "sectionRef"
   // REQ-WDG-RICHTEXT: rich-text (HTML string) edited via a Tiptap editor.
   | "richText"
   // REQ-WDG-ASSET: file/asset picker → bare File UUID (Asset Manager picker).
@@ -841,6 +844,7 @@ export interface WidgetContext<TProps = unknown> {
   navigation: {
     goTo(pageId: string, params?: Record<string, string>): void;
     goToStartPage(): void;
+    scrollToSection(sectionId: string): void;
     goBack(): void;
     push(pageId: string, params?: Record<string, unknown>): void;
     replace(pageId: string, params?: Record<string, unknown>): void;
@@ -2210,12 +2214,15 @@ export function useFitScreenInsets(): FitScreenInsets;
  * The host-provided navigation surface. `goTo(pageId, params?)` navigates
  * to an internal app page; `goBack()` pops the stack. `goToStartPage()`
  * opens the signed-in user's own start page, which can differ per user.
+ * `scrollToSection(sectionId)` scrolls this page to one of its sections (the
+ * id comes from a `sectionRef` prop); an unknown section is a no-op.
  * Missing methods degrade to no-ops on the Studio canvas preview where no
  * live router is mounted. For external URLs use the `Linking` primitive.
  */
 export function useNavigation(): {
   goTo(pageId: string, params?: Record<string, unknown>): void;
   goToStartPage(): void;
+  scrollToSection(sectionId: string): void;
   goBack(): void;
   push(pageId: string, params?: Record<string, unknown>): void;
   replace(pageId: string, params?: Record<string, unknown>): void;
@@ -3711,8 +3718,18 @@ export interface ListRowTokens {
 /**
  * Themed list container. Spaces and insets its `<ListRow>` children the way the
  * app's look says, and hands its overrides down to every row.
+ *
+ * @example
+ *   // A list of cards: the app's card look outside, its list look inside.
+ *   <List variant="card">
+ *     {orders.map((o) => <ListRow key={o.id} title={o.name} subtitle={o.status} onPress={() => open(o)} />)}
+ *   </List>
  */
 export const List: (props: ListRowTokens & {
+  /** "card" draws every row as its own card (Theme Settings > Cards). Defaults to "plain". */
+  variant?: "plain" | "card";
+  /** The widget's own row look, used only where Theme Settings > Lists leaves a value unset. */
+  defaults?: ListRowTokens;
   style?: any;
   testID?: string;
   children?: ReactNode;
@@ -3736,6 +3753,13 @@ export const ListRow: (props: ListRowTokens & {
   trailing?: ReactNode;
   /** Makes the row a button with a press state. */
   onPress?: () => void;
+  /**
+   * The row's own buttons (remove, move, sign), after `trailing`. On a row
+   * with `onPress` they stay outside its tap target, each its own button.
+   */
+  actions?: ReactNode;
+  /** As `<List defaults>`, for this row. */
+  defaults?: ListRowTokens;
   selected?: boolean;
   disabled?: boolean;
   /** Defaults to true; pass false on the last row. */
@@ -4059,22 +4083,10 @@ export interface SelectOption<V extends string | number = string | number> {
   testID?: string;
 }
 
-/**
- * Themed single-choice picker. The trigger is the input field, a button that
- * opens a dialog; its options open at screen level (through `Overlay`) in a
- * sheet painted from the `popover` scope, so no container clips them and a
- * long list scrolls. Each option has the option role; the list is a listbox
- * on the web only. Other props land on the trigger.
- *
- * @example
- *   <Select label="Status" value={status} onValueChange={setStatus}
- *     options={[{ value: "open", label: "Open" }, { value: "done", label: "Done" }]} />
- */
-export const Select: <V extends string | number = string | number>(
-  props: FormControlProps & FormFieldOverrides & {
+/** What every `<Select>` takes, in either mode. */
+export type SelectBaseProps<V extends string | number = string | number> = FormControlProps &
+  FormFieldOverrides & {
     options: Array<SelectOption<V>>;
-    value?: V | null;
-    onValueChange?: (value: V, option: SelectOption<V>) => void;
     /** Shown while nothing is chosen. Default "Select". */
     placeholder?: string;
     /** The sheet's heading. Defaults to a text `label`. */
@@ -4086,7 +4098,46 @@ export const Select: <V extends string | number = string | number>(
     style?: any;
     containerStyle?: any;
     [prop: string]: any;
-  },
+  };
+
+/**
+ * Themed picker for one value of a known list, or several with `multiple`.
+ * The trigger is the input field, a button that opens a dialog; its options
+ * open at screen level (through `Overlay`) in a sheet painted from the
+ * `popover` scope, so no container clips them and a long list scrolls. Each
+ * option has the option role; the list is a listbox on the web only
+ * (multiselectable with `multiple`). Other props land on the trigger.
+ *
+ * With `multiple` each option carries a tick box and toggles a draft; the
+ * sheet's Done button commits it through `onValuesChange`, and closing it any
+ * other way (backdrop, Escape, Android back) keeps the previous choice. The
+ * trigger shows the picked labels as small chips while they fit on its line,
+ * else "N selected".
+ *
+ * @example
+ *   <Select label="Status" value={status} onValueChange={setStatus}
+ *     options={[{ value: "open", label: "Open" }, { value: "done", label: "Done" }]} />
+ *   <Select multiple label="Tags" values={tags} onValuesChange={setTags}
+ *     options={[{ value: "red", label: "Red" }, { value: "blue", label: "Blue" }]} />
+ */
+export const Select: <V extends string | number = string | number>(
+  props:
+    | (SelectBaseProps<V> & {
+        multiple?: false;
+        value?: V | null;
+        onValueChange?: (value: V, option: SelectOption<V>) => void;
+      })
+    | (SelectBaseProps<V> & {
+        multiple: true;
+        /** The picked values; any order. */
+        values?: V[] | null;
+        /** Called on Done with the new values in listed order, only when they changed. */
+        onValuesChange?: (values: V[], options: Array<SelectOption<V>>) => void;
+        /** The trigger's text when the chips do not fit. Default `${count} selected`. */
+        selectedCountText?: (count: number) => string;
+        /** The sheet's confirm button. Default "Done". */
+        doneText?: string;
+      }),
 ) => any;
 
 /**
@@ -4263,6 +4314,101 @@ export const ChipGroup: (props: {
   testID?: string;
 }) => any;
 
+/**
+ * A file as `<FilePicker>` and `<FileUpload>` hand it over: the browser's
+ * `File` on the web, expo-file-system's `File` on the Expo export. Pass it to
+ * `upload(file)` from `useFilestoreUpload` as it is.
+ */
+export interface PickedFile {
+  name: string;
+  type?: string;
+  size?: number;
+  [key: string]: any;
+}
+
+/**
+ * The system file picker. Its children are the visible trigger. Web wraps a
+ * hidden file input; native opens the OS document picker. `isSupported` is
+ * false on a host with no picker. For an upload field use `<FileUpload>`.
+ */
+export const FilePicker: ((props: {
+  /** An HTML accept value: "image/*", ".pdf", "application/pdf". */
+  accept?: string;
+  multiple?: boolean;
+  disabled?: boolean;
+  /** One file, or an array when `multiple`. */
+  onPick?: (picked: PickedFile | PickedFile[]) => void;
+  /** The picker's keyboard focus, for a trigger that draws its own ring. */
+  onFocus?: () => void;
+  onBlur?: () => void;
+  accessibilityLabel?: string;
+  /** The id of the note that describes the picker, such as a field's error. */
+  "aria-describedby"?: string;
+  "aria-invalid"?: boolean;
+  children?: ReactNode;
+}) => any) & { isSupported: boolean };
+
+/**
+ * Themed file chooser on `<FilePicker>`: a button (the `button` scope) in the
+ * input field (the `muted` scope), the chosen files with their size and a
+ * remove control, and the form controls' `label` / `helper` / `error` /
+ * `disabled`. On the web a file can also be dropped onto the field; native
+ * has no file drop, so the button is the control there. A file `accept` rules
+ * out is not added and shows an error. It uploads nothing: upload in
+ * `onPick` with `useFilestoreUpload` and pass `uploading` while it runs, which
+ * shows an indeterminate `<Spinner>` and locks the field.
+ *
+ * @example
+ *   const { upload, uploading } = useFilestoreUpload({ spaceType: "project" });
+ *   const [photos, setPhotos] = useState([]);
+ *   <FileUpload label="Photos" accept="image/*" multiple uploading={uploading}
+ *     files={photos} onFilesChange={setPhotos}
+ *     onPick={(picked) => Promise.all(picked.map((f) => upload(f))).then(() => setPhotos([]))} />
+ */
+export const FileUpload: (props: FormControlProps & {
+  accept?: string;
+  /** A new pick joins the list instead of replacing the file. Default false. */
+  multiple?: boolean;
+  /**
+   * The listed files; pass with `onFilesChange` to own the list. A list the
+   * field keeps itself still shows a file after its upload, so own it to clear it.
+   */
+  files?: PickedFile[];
+  /** After every pick, drop and removal. */
+  onFilesChange?: (files: PickedFile[]) => void;
+  /** Once per pick or drop, with only the new files (an array when `multiple`). */
+  onPick?: (picked: PickedFile | PickedFile[]) => void;
+  onRemove?: (file: PickedFile, index: number) => void;
+  /**
+   * Files that were not added: `"type"` for ones `accept` ruled out, `"count"`
+   * for the files beyond the first dropped on a field without `multiple`.
+   */
+  onReject?: (files: PickedFile[], reason: "type" | "count") => void;
+  /** Shows the uploading state and locks the field. */
+  uploading?: boolean;
+  /** Default "Choose file", or "Choose files" when `multiple`. */
+  buttonLabel?: string;
+  /** Default "outlined". */
+  buttonVariant?: "primary" | "secondary" | "outlined";
+  /** Default "Uploading…". */
+  uploadingLabel?: string;
+  /** Shown while nothing is chosen, where no drop is possible. */
+  emptyLabel?: string;
+  /** Web only: the drop hint beside the button. */
+  dropLabel?: string;
+  /** The error a ruled-out file shows. */
+  rejectedMessage?: string;
+  /** Shown when several files reach a field without `multiple`. */
+  singleFileMessage?: string;
+  /** Replaces the helper on a host with no file picker. */
+  unsupportedMessage?: string;
+  /** Prefixed to each file's name. Defaults to the app's own "Remove". */
+  removeAccessibilityLabel?: string;
+  /** The field. */
+  style?: any;
+  containerStyle?: any;
+}) => any;
+
 /**
  * Themed collapsible sections. The surface comes from the theme's `card`
  * scope and the headers and dividers from its `list` scope, so every

package/dist/index.js

@@ -291,6 +291,8 @@ export { Modal } from "./modal.js";
 export { ConfirmDialog } from "./confirm-dialog.js";
 // Themed filter chips, tags and pills; follow the theme's `chip` scope.
 export { Chip, ChipGroup } from "./chip.js";
+// A themed file chooser on `<FilePicker>`; follows the theme's `muted` scope.
+export { FileUpload } from "./file-upload.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/index.native.js

@@ -284,6 +284,8 @@ export { Modal } from "./modal.native.js";
 export { ConfirmDialog } from "./confirm-dialog.native.js";
 // Themed filter chips, tags and pills; follow the theme's `chip` scope.
 export { Chip, ChipGroup } from "./chip.native.js";
+// A themed file chooser on `<FilePicker>`; follows the theme's `muted` scope.
+export { FileUpload } from "./file-upload.native.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/list-tokens.js

@@ -27,43 +27,60 @@ 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];
+// The ways `<List>` can draw its rows: flush bands / tiles, or one card each.
+export const LIST_VARIANTS = Object.freeze(["plain", "card"]);
+
+/** A `variant` value as `<List>` reads it; anything unknown is "plain". */
+export function listVariant(value) {
+  return LIST_VARIANTS.includes(value) ? value : "plain";
+}
+
+function pick(name, ...layers) {
+  for (const layer of layers) {
+    if (layer && isSet(layer[name])) return layer[name];
+  }
   return undefined;
 }
 
+function boundedList(values) {
+  return values ? normaliseThemeComponents({ list: values }).list : undefined;
+}
+
 /**
  * Resolve one list's row values: explicit override, then the theme's `list`
- * scope, then the theme tokens. Both layers pass the contract's own bounds, so
- * a hand-edited or planned value cannot reach a native style unvalidated.
+ * scope, then the widget's own `defaults`, then the theme tokens. Every layer
+ * passes the contract's own bounds, so a hand-edited or planned value cannot
+ * reach a native style unvalidated.
  * Unthemed, a row is the flush band with a 1px hairline the Data List drew;
  * a `gap` makes separate tiles on the surface, outlined by the divider.
  *
  * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
  * @param {object} [overrides] — per-list values keyed by LIST_TOKEN_NAMES.
+ * @param {object} [defaults] — a widget's own row look, keyed the same way,
+ *   used only where the theme's Lists settings leave a value unset.
  */
-export function resolveListTokens(theme, overrides) {
+export function resolveListTokens(theme, overrides, defaults) {
   const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
   const fallback = DEFAULT_THEME_TOKENS;
   const colors = base.colors || fallback.colors;
   const spacing = base.spacing || fallback.spacing;
   const scope = base.components && base.components.list;
-  const own = normaliseThemeComponents({ list: overrides }).list;
+  const layers = [boundedList(overrides), scope, boundedList(defaults)];
+  const value = (name) => pick(name, ...layers);
 
-  const gap = pick(own, scope, "gap") ?? 0;
+  const gap = value("gap") ?? 0;
   const separated = gap > 0;
-  const background = pick(own, scope, "background") ?? (separated ? colors.surface : undefined);
+  const background = value("background") ?? (separated ? colors.surface : undefined);
   return {
-    rowPadding: pick(own, scope, "rowPadding") ?? spacing.md,
-    rowMinHeight: pick(own, scope, "rowMinHeight") ?? LIST_ROW_MIN_HEIGHT,
+    rowPadding: value("rowPadding") ?? spacing.md,
+    rowMinHeight: value("rowMinHeight") ?? LIST_ROW_MIN_HEIGHT,
     gap,
     separated,
     // A flush band has square ends; a divider would curve into round ones.
-    radius: separated ? pick(own, scope, "radius") ?? 0 : 0,
+    radius: separated ? value("radius") ?? 0 : 0,
     background,
-    dividerColor: pick(own, scope, "dividerColor") ?? colors.border,
-    dividerWidth: pick(own, scope, "dividerWidth") ?? 1,
+    dividerColor: value("dividerColor") ?? colors.border,
+    dividerWidth: value("dividerWidth") ?? 1,
     selectedBackground: colors.primarySoft || colors.surfaceMuted,
     selectedAccent: colors.primary,
     pressedBackground: mixHex(colors.onSurface, background || colors.surface, 0.94),
@@ -97,3 +114,26 @@ export function listRowFrame(tokens, spacing, selected = false) {
   const inset = tokens.rowPadding + listSideEdgeWidth(tokens) - LIST_SELECTED_BAR_WIDTH;
   return { ...frame, paddingLeft: Math.max(0, inset) };
 }
+
+/**
+ * The row frame of a card-style list. The card scope paints the surface
+ * (fill, border, radius, padding, shadow, gradient); the list scope keeps
+ * only what is inside it: the height and the slots' arrangement.
+ *
+ * @param {ReturnType<typeof resolveListTokens>} tokens
+ * @param {{ md: number }} spacing — the theme's spacing scale.
+ * @param {boolean} [pressable] — a tap target keeps the 44px floor.
+ */
+export function listCardRowFrame(tokens, spacing, pressable = false) {
+  return {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: spacing.md,
+    minHeight: pressable ? Math.max(tokens.rowMinHeight, LIST_ROW_MIN_HEIGHT) : tokens.rowMinHeight,
+  };
+}
+
+/** The space between the cards of a card-style list: the Lists gap, else `spacing.sm`. */
+export function listCardGap(tokens, spacing) {
+  return tokens.gap > 0 ? tokens.gap : spacing.sm;
+}