@colixsystems/widget-sdk 0.247.0 → 0.248.0

package/dist/form-view.js

@@ -0,0 +1,268 @@
+// The ONE implementation behind the form layout components: `<Form>`,
+// `<FieldRow>`, `<FormSection>`, `<FormActions>` and `<FormField>`. The
+// bindings (`form.js` / `form.native.js`) differ only in where the primitives
+// and `<Grid>` come from, so the hosts lay a form out the same way.
+//
+// Fields share lines through `<Grid columns>`, the SDK's one grid layout, and
+// a form measures itself with `useContainerWidth`. The rules that need no
+// renderer live in ./form-layout-logic.js.
+
+import React from "react";
+import { useContainerWidth, useHostSharedText, useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { resolveGridGap } from "./grid-logic.js";
+import { resolveFormControlTokens } from "./form-control-tokens.js";
+import { drawsOwnFrame, errorMessage, hasNote, isShown, isText, spokenLabel } from "./form-control-logic.js";
+import { makeFieldFrame } from "./form-control-view.js";
+import { textRoleStyle } from "./text-roles.js";
+import {
+  DEFAULT_FORM_GAP,
+  actionsStack,
+  fieldRowColumns,
+  formColumns,
+  formMaxWidth,
+  formRuns,
+  handedFieldProps,
+} from "./form-layout-logic.js";
+
+const h = React.createElement;
+
+function useThemeTokens() {
+  return useHostTheme() || DEFAULT_THEME_TOKENS;
+}
+
+/**
+ * Bind the shared form layout to one platform's primitives and `<Grid>`.
+ *
+ * @param {{View: any, Text: any, Pressable: any, Platform: any, Grid: any}} rn
+ */
+export function makeForm(rn) {
+  const { View, Text, Platform, Grid } = rn;
+  const web = Boolean(Platform) && Platform.OS === "web";
+  const FieldFrame = makeFieldFrame(rn);
+  // The enclosing form's measured width, column count and gap.
+  const FormLayout = React.createContext(null);
+
+  // Outside a `<Form>` a part measures its own unpadded box instead.
+  function useLayout(gap) {
+    const theme = useThemeTokens();
+    const form = React.useContext(FormLayout);
+    const [ownWidth, onLayout] = useContainerWidth();
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    if (form) {
+      const space = gap === undefined ? form.space : resolveGridGap(gap, spacing);
+      return { ...form, space, onLayout: undefined, theme };
+    }
+    const space = resolveGridGap(gap ?? DEFAULT_FORM_GAP, spacing);
+    return { width: ownWidth, columns: formColumns("auto", ownWidth), space, onLayout, theme };
+  }
+
+  function takesWholeLine(child) {
+    if (!React.isValidElement(child)) return true;
+    if (child.type === FormField) {
+      if (child.props.span === "full") return true;
+      const inner = React.Children.toArray(child.props.children);
+      return inner.length === 1 && React.isValidElement(inner[0]) && inner[0].props.multiline === true;
+    }
+    return !(drawsOwnFrame(child) && child.props.multiline !== true);
+  }
+
+  // Fields share lines in a Grid; anything else takes a line of its own.
+  function renderRuns(children, layout) {
+    const items = React.Children.toArray(children);
+    const sectionGap = layout.theme.spacing ? layout.theme.spacing.sm : DEFAULT_THEME_TOKENS.spacing.sm;
+    return formRuns(items.map(takesWholeLine)).map((run) => {
+      if (run.full) {
+        const index = run.indices[0];
+        const child = items[index];
+        // A section after other content stands further apart from it.
+        if (index > 0 && React.isValidElement(child) && child.type === FormSection) {
+          return React.cloneElement(child, { style: [{ marginTop: sectionGap }, child.props.style] });
+        }
+        return child;
+      }
+      const cells = run.indices.map((i) => items[i]);
+      const first = cells[0];
+      return h(
+        Grid,
+        { key: `fields${React.isValidElement(first) ? first.key : run.indices[0]}`, columns: layout.columns, gap: layout.space },
+        ...cells,
+      );
+    });
+  }
+
+  /**
+   * @param {object} props
+   * @param {"auto"|number} [props.columns] — the most fields to a line when
+   *   wide (1–3); "auto" is three. Medium holds at most two, narrow one.
+   * @param {number|null} [props.maxWidth] — the cap the form centres within;
+   *   1000 by default, `null` for none.
+   * @param {string|number} [props.gap] — a theme spacing name or pixels.
+   */
+  function Form({ children, columns = "auto", maxWidth, gap, style, testID, accessibilityLabel }) {
+    const theme = useThemeTokens();
+    const [width, onLayout] = useContainerWidth();
+    const space = resolveGridGap(gap ?? DEFAULT_FORM_GAP, theme.spacing || DEFAULT_THEME_TOKENS.spacing);
+    const lineColumns = formColumns(columns, width);
+    const layout = React.useMemo(
+      () => ({ width, columns: lineColumns, space, theme }),
+      [width, lineColumns, space, theme],
+    );
+    const cap = formMaxWidth(maxWidth);
+    // Not role "form": the web host renders that as a <form>, which submits on Enter.
+    const named = accessibilityLabel ? { role: "group", accessibilityLabel } : null;
+    return h(
+      View,
+      {
+        testID,
+        ...named,
+        // All three, or a capped form sits flush left or shrink-wraps.
+        style: [{ width: "100%", alignSelf: "center" }, cap ? { maxWidth: cap } : null, style],
+      },
+      h(
+        View,
+        { onLayout, style: { gap: space } },
+        h(FormLayout.Provider, { value: layout }, ...renderRuns(children, layout)),
+      ),
+    );
+  }
+
+  /** Short related fields on one line; stacked when narrow. */
+  function FieldRow({ children, gap, style, testID }) {
+    const layout = useLayout(gap);
+    const items = React.Children.toArray(children);
+    const space = gap === undefined ? layout.space : resolveGridGap(gap, layout.theme.spacing);
+    return h(
+      View,
+      { testID, style: [{ alignSelf: "stretch" }, style] },
+      h(
+        View,
+        { onLayout: layout.onLayout },
+        h(Grid, { columns: fieldRowColumns(items.length, layout.width), gap: space }, ...items),
+      ),
+    );
+  }
+
+  /** A titled group of fields, laid out as the form around it lays its own. */
+  function FormSection({ title, description, children, gap, style, testID }) {
+    const layout = useLayout(gap);
+    const { theme } = layout;
+    const t = resolveFormControlTokens(theme);
+    const heading = title
+      ? h(
+          Text,
+          {
+            accessibilityRole: "header",
+            style: textRoleStyle("subtitle", theme.typography, theme.colors),
+          },
+          title,
+        )
+      : null;
+    const about = description
+      ? h(Text, { style: { color: t.helperColor, fontFamily: t.fontFamily, fontSize: t.labelSize } }, description)
+      : null;
+    return h(
+      View,
+      { testID, style: [{ alignSelf: "stretch" }, style] },
+      h(
+        View,
+        { onLayout: layout.onLayout, style: { gap: layout.space } },
+        heading || about ? h(View, { style: { gap: t.gap } }, heading, about) : null,
+        ...renderRuns(children, layout),
+      ),
+    );
+  }
+
+  /**
+   * The form's buttons, in normal flow after its fields. Pass the secondary
+   * first and the primary last: a row at the trailing edge, primary last;
+   * narrow, a full-width stack in the same order, primary nearest the thumb.
+   */
+  function FormActions({ children, style, testID }) {
+    const layout = useLayout();
+    const { spacing } = layout.theme;
+    const stacked = actionsStack(layout.width);
+    const items = React.Children.toArray(children).map((child) =>
+      stacked && React.isValidElement(child)
+        ? React.cloneElement(child, { style: [child.props.style, { alignSelf: "stretch" }] })
+        : child,
+    );
+    const arrangement = stacked
+      ? { gap: spacing.sm }
+      : { flexDirection: "row", flexWrap: "wrap", justifyContent: "flex-end", alignItems: "center", gap: spacing.sm };
+    return h(
+      View,
+      { testID, style: [{ alignSelf: "stretch" }, style] },
+      h(View, { onLayout: layout.onLayout, style: arrangement }, ...items),
+    );
+  }
+
+  // A device has no group name or aria-describedby: name the control itself.
+  function namedForDevice(only, name, hint) {
+    if (web || !only || !React.isValidElement(only) || !isShown(name)) return null;
+    if (isShown(only.props.accessibilityLabel)) return null;
+    const hinted = isText(hint) && only.props.accessibilityHint === undefined ? { accessibilityHint: String(hint) } : null;
+    return React.cloneElement(only, { accessibilityLabel: name, ...hinted });
+  }
+
+  /**
+   * A label, required mark, helper and error round any control. A control
+   * that frames itself (`<TextField>`, `<Select>`, `<RadioGroup>`,
+   * `<PeoplePicker>`, `<FileUpload>`) is handed them instead, so one label
+   * is drawn; a prop the control sets itself wins.
+   *
+   * @param {object} props
+   * @param {"full"} [props.span] — take the form's whole line.
+   */
+  function FormField({ label, required = false, helper, error, disabled = false, children, style, testID }) {
+    const theme = useThemeTokens();
+    const t = resolveFormControlTokens(theme);
+    const requiredWord = useHostSharedText("required", "Required");
+    const noteId = React.useId();
+    const items = React.Children.toArray(children);
+    const only = items.length === 1 ? items[0] : null;
+    if (only && drawsOwnFrame(only)) {
+      const field = { label, required: required || undefined, helper, error, disabled: disabled || undefined, testID };
+      const handed = handedFieldProps(field, only.props);
+      const containerStyle = style ? [only.props.containerStyle, style] : only.props.containerStyle;
+      const control = React.cloneElement(only, { ...handed, containerStyle });
+      // The control keeps its own testID; the field's then marks a wrapper.
+      return testID && handed.testID === undefined ? h(View, { testID }, control) : control;
+    }
+    const noted = hasNote({ helper, error });
+    const name = spokenLabel(undefined, label, required ? requiredWord : null);
+    const named = namedForDevice(only, name, errorMessage(error) || helper);
+    return h(
+      FieldFrame,
+      {
+        t,
+        label,
+        required,
+        helper,
+        error: errorMessage(error),
+        disabled,
+        noteId,
+        // Unnamed, the device reads the label alone, so it carries the word.
+        spokenRequired: web || named ? undefined : requiredWord,
+        style,
+      },
+      h(
+        View,
+        {
+          testID,
+          role: "group",
+          accessibilityLabel: named ? undefined : name,
+          ...(noted ? { "aria-describedby": noteId } : null),
+        },
+        ...(named ? [named] : items),
+      ),
+    );
+  }
+
+  Form.displayName = "Form";
+  FieldRow.displayName = "FieldRow";
+  FormSection.displayName = "FormSection";
+  FormActions.displayName = "FormActions";
+  FormField.displayName = "FormField";
+  return { Form, FieldRow, FormSection, FormActions, FormField };
+}

package/dist/form.js

@@ -0,0 +1,15 @@
+// `<Form>`, `<FieldRow>`, `<FormSection>`, `<FormActions>` and `<FormField>`
+// (web). Binds ./form-view.js to the web primitives and the web `<Grid>`; see
+// ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { makeForm } from "./form-view.js";
+import { Grid } from "./grid.js";
+
+export const { Form, FieldRow, FormSection, FormActions, FormField } = makeForm({
+  View: ReactNative.View,
+  Text: ReactNative.Text,
+  Pressable: ReactNative.Pressable,
+  Platform: ReactNative.Platform,
+  Grid,
+});

package/dist/form.native.js

@@ -0,0 +1,9 @@
+// `<Form>`, `<FieldRow>`, `<FormSection>`, `<FormActions>` and `<FormField>`
+// (native). Binds ./form-view.js to React Native's own primitives and the
+// native `<Grid>`; only the imports differ from ./form.js.
+
+import { View, Text, Pressable, Platform } from "react-native";
+import { makeForm } from "./form-view.js";
+import { Grid } from "./grid.native.js";
+
+export const { Form, FieldRow, FormSection, FormActions, FormField } = makeForm({ View, Text, Pressable, Platform, Grid });