@dloizides/ui-forms 1.8.0 → 1.9.1

package/dist/index.mjs

@@ -36,6 +36,40 @@ function resolveFieldMarker(required, optional) {
   if (optional) return "optional";
   return "none";
 }
+var FIELD_STACK_MARGIN_BOTTOM = 16;
+var FIELD_STACK_LABEL_MARGIN_BOTTOM = 4;
+var FIELD_STACK_CHILD_MARGIN_TOP = 4;
+var FIELD_CONTRACT_GAP = 6;
+var fieldSpacingStyles = StyleSheet.create({
+  stackContainer: { marginBottom: FIELD_STACK_MARGIN_BOTTOM },
+  stackLabel: { marginBottom: FIELD_STACK_LABEL_MARGIN_BOTTOM },
+  stackChild: { marginTop: FIELD_STACK_CHILD_MARGIN_TOP },
+  /**
+   * The gap model sets NO margins — not even zeroed ones. An explicit `marginBottom: 0` here would
+   * defeat a caller who legitimately wants to push one field down via `containerStyle`, because
+   * `containerStyle` composes AFTER this and a zero is indistinguishable from "unset" to a reader.
+   */
+  gapContainer: { gap: FIELD_CONTRACT_GAP },
+  none: {}
+});
+function resolveFieldSpacing(explicit, insideGrid) {
+  if (explicit !== void 0) return explicit;
+  return insideGrid ? "gap" : "stack";
+}
+function fieldSpacingStyleSet(spacing) {
+  if (spacing === "gap") {
+    return {
+      container: fieldSpacingStyles.gapContainer,
+      label: fieldSpacingStyles.none,
+      child: fieldSpacingStyles.none
+    };
+  }
+  return {
+    container: fieldSpacingStyles.stackContainer,
+    label: fieldSpacingStyles.stackLabel,
+    child: fieldSpacingStyles.stackChild
+  };
+}
 var FIELD_FONT_SIZE = 13;
 var FIELD_FONT_WEIGHT = "600";
 var CONTROL_FONT_SIZE = 11;
@@ -56,27 +90,25 @@ var labelVariantStyles = StyleSheet.create({
 function resolveLabelVariantStyle(variant) {
   return variant === "control" ? labelVariantStyles.control : labelVariantStyles.field;
 }
-var CONTAINER_MARGIN_BOTTOM = 16;
-var LABEL_MARGIN_BOTTOM = 4;
+var FormGridContext = React.createContext(null);
+var GapOwnedContext = React.createContext(false);
+var FormGridProvider = FormGridContext.Provider;
+var GapOwnedProvider = GapOwnedContext.Provider;
+function useFormGridMetrics() {
+  return React.useContext(FormGridContext);
+}
+function useIsGapOwned() {
+  return React.useContext(GapOwnedContext);
+}
 var ERROR_FONT_SIZE = 12;
-var ERROR_MARGIN_TOP = 4;
 var HINT_FONT_SIZE = 12;
-var HINT_MARGIN_TOP = 4;
 var OPTIONAL_MARK_FONT_WEIGHT = "400";
 var styles = StyleSheet.create({
-  container: {
-    marginBottom: CONTAINER_MARGIN_BOTTOM
-  },
-  label: {
-    marginBottom: LABEL_MARGIN_BOTTOM
-  },
   hintText: {
-    fontSize: HINT_FONT_SIZE,
-    marginTop: HINT_MARGIN_TOP
+    fontSize: HINT_FONT_SIZE
   },
   errorText: {
-    fontSize: ERROR_FONT_SIZE,
-    marginTop: ERROR_MARGIN_TOP
+    fontSize: ERROR_FONT_SIZE
   },
   optionalMark: {
     fontWeight: OPTIONAL_MARK_FONT_WEIGHT
@@ -112,9 +144,12 @@ var Field = ({
   labelVariant,
   labelStyle,
   containerStyle,
+  spacing,
   testID
 }) => {
   const { theme } = useUi();
+  const gapOwned = useIsGapOwned();
+  const spacingStyles = fieldSpacingStyleSet(resolveFieldSpacing(spacing, gapOwned));
   const { colors, semantic } = theme;
   const errorColor = semantic.error["500"];
   const hasError = hasFieldError(error);
@@ -136,7 +171,7 @@ var Field = ({
   );
   const describedById = joinDescribedBy(hasHint ? hintId : void 0, hasError ? errorId : void 0);
   const control = typeof children === "function" ? children({ describedById, hasError }) : children;
-  return /* @__PURE__ */ jsxs(View, { style: [styles.container, containerStyle], testID, children: [
+  return /* @__PURE__ */ jsxs(View, { style: [spacingStyles.container, containerStyle], testID, children: [
     hasLabel ? /* @__PURE__ */ jsx(
       FieldLabel,
       {
@@ -145,16 +180,107 @@ var Field = ({
         optionalLabel,
         optionalMarkStyle: [styles.optionalMark, themeStyles.optionalMark],
         requiredMarkStyle: themeStyles.requiredMark,
-        style: [styles.label, resolveLabelVariantStyle(labelVariant), themeStyles.label, labelStyle]
+        style: [spacingStyles.label, resolveLabelVariantStyle(labelVariant), themeStyles.label, labelStyle]
       }
     ) : null,
     control,
-    hasHint ? /* @__PURE__ */ jsx(Text, { nativeID: hintId, style: [styles.hintText, themeStyles.hintText], children: hint }) : null,
-    hasError ? /* @__PURE__ */ jsx(Text, { nativeID: errorId, role: "alert", style: [styles.errorText, themeStyles.errorText], children: error }) : null
+    hasHint ? /* @__PURE__ */ jsx(Text, { nativeID: hintId, style: [styles.hintText, spacingStyles.child, themeStyles.hintText], children: hint }) : null,
+    hasError ? /* @__PURE__ */ jsx(Text, { nativeID: errorId, role: "alert", style: [styles.errorText, spacingStyles.child, themeStyles.errorText], children: error }) : null
   ] });
 };
-var ACTIONS_GAP = 12;
+var FORM_GRID_DEFAULT_GAP = 12;
+var FORM_GRID_DEFAULT_MIN_WIDTH = 220;
+var FORM_GRID_DEFAULT_BASIS = 260;
 var styles2 = StyleSheet.create({
+  grid: {
+    flexDirection: "row",
+    flexWrap: "wrap"
+  }
+});
+var FormGrid = ({
+  children,
+  gap = FORM_GRID_DEFAULT_GAP,
+  minWidth = FORM_GRID_DEFAULT_MIN_WIDTH,
+  basis = FORM_GRID_DEFAULT_BASIS,
+  style,
+  testID
+}) => {
+  const metrics = React.useMemo(() => ({ minWidth, basis }), [minWidth, basis]);
+  return /* @__PURE__ */ jsx(FormGridProvider, { value: metrics, children: /* @__PURE__ */ jsx(GapOwnedProvider, { value: true, children: /* @__PURE__ */ jsx(View, { style: [styles2.grid, { gap }, style], testID, children }) }) });
+};
+var GROW = 1;
+var NO_GROW = 0;
+var FormCell = ({
+  children,
+  minWidth,
+  basis,
+  grow = true,
+  style,
+  testID
+}) => {
+  const metrics = useFormGridMetrics();
+  const resolvedMinWidth = minWidth ?? metrics?.minWidth ?? FORM_GRID_DEFAULT_MIN_WIDTH;
+  const resolvedBasis = basis ?? metrics?.basis ?? FORM_GRID_DEFAULT_BASIS;
+  const cellStyle = {
+    minWidth: resolvedMinWidth,
+    flexBasis: resolvedBasis,
+    flexGrow: grow ? GROW : NO_GROW
+  };
+  return /* @__PURE__ */ jsx(View, { style: [cellStyle, style], testID, children });
+};
+var SECTION_GAP = 10;
+var DESCRIPTION_FONT_SIZE = 12;
+var styles3 = StyleSheet.create({
+  section: {
+    gap: SECTION_GAP
+  },
+  description: {
+    fontSize: DESCRIPTION_FONT_SIZE
+  }
+});
+var sectionSeq = 0;
+function useSectionLegendId() {
+  const [id] = React.useState(() => {
+    sectionSeq += 1;
+    return `form-section-legend-${String(sectionSeq)}`;
+  });
+  return id;
+}
+var FormSection = ({
+  title,
+  description,
+  children,
+  labelVariant,
+  titleStyle,
+  style,
+  testID
+}) => {
+  const { theme } = useUi();
+  const { colors } = theme;
+  const legendId = useSectionLegendId();
+  const hasTitle = typeof title === "string" && title !== "";
+  const hasDescription = typeof description === "string" && description !== "";
+  const a11y = { "aria-labelledby": hasTitle ? legendId : void 0 };
+  return (
+    // The section spaces its children with `gap`, so it owns their vertical rhythm exactly as a
+    // `FormGrid` owns a row's — without this a `Field` placed directly in a section would stack its
+    // 16px margin on the section's gap and recreate the F3 bug one level up.
+    /* @__PURE__ */ jsx(GapOwnedProvider, { value: true, children: /* @__PURE__ */ jsxs(View, { role: "group", style: [styles3.section, style], testID, ...a11y, children: [
+      hasTitle ? /* @__PURE__ */ jsx(
+        Text,
+        {
+          nativeID: legendId,
+          style: [resolveLabelVariantStyle(labelVariant), { color: colors.text }, titleStyle],
+          children: title
+        }
+      ) : null,
+      hasDescription ? /* @__PURE__ */ jsx(Text, { style: [styles3.description, { color: colors.textSecondary }], children: description }) : null,
+      children
+    ] }) })
+  );
+};
+var ACTIONS_GAP = 12;
+var styles4 = StyleSheet.create({
   container: {
     flexDirection: "row",
     justifyContent: "flex-end",
@@ -174,7 +300,7 @@ var FormActions = ({
   saveTestID = "save-button",
   cancelTestID = "cancel-button",
   testID
-}) => /* @__PURE__ */ jsxs(View, { style: [styles2.container, containerStyle], testID, children: [
+}) => /* @__PURE__ */ jsxs(View, { style: [styles4.container, containerStyle], testID, children: [
   typeof onCancel === "function" ? /* @__PURE__ */ jsx(
     Button,
     {
@@ -297,6 +423,16 @@ function useThemedInput(options = {}) {
   };
 }
 var IS_WEB2 = Platform.OS === "web";
+function webFieldA11y({ describedById, hasError = false, required = false }) {
+  if (!IS_WEB2) {
+    return {};
+  }
+  return {
+    "aria-invalid": hasError ? true : void 0,
+    "aria-describedby": describedById,
+    "aria-required": required ? true : void 0
+  };
+}
 var ThemedTextInput = React.forwardRef(function ThemedTextInput2({ hasError = false, describedById, requiredField = false, onFocus, onBlur, style, placeholderTextColor, ...rest }, ref) {
   const {
     style: themedStyle,
@@ -304,11 +440,7 @@ var ThemedTextInput = React.forwardRef(function ThemedTextInput2({ hasError = fa
     focusBind,
     hoverBind
   } = useThemedInput({ hasError, onFocus, onBlur });
-  const webA11y = IS_WEB2 ? {
-    "aria-invalid": hasError ? true : void 0,
-    "aria-describedby": describedById,
-    "aria-required": requiredField ? true : void 0
-  } : {};
+  const webA11y = webFieldA11y({ describedById, hasError, required: requiredField });
   return /* @__PURE__ */ jsx(
     TextInput,
     {
@@ -327,7 +459,7 @@ var INPUT_PADDING_V = 10;
 var INPUT_PADDING_H = 12;
 var INPUT_BORDER_RADIUS = 8;
 var INPUT_BORDER_WIDTH = 1;
-var styles3 = StyleSheet.create({
+var styles5 = StyleSheet.create({
   input: {
     paddingVertical: INPUT_PADDING_V,
     paddingHorizontal: INPUT_PADDING_H,
@@ -349,7 +481,7 @@ var FormField = ({
     describedById,
     hasError,
     requiredField: required,
-    style: styles3.input,
+    style: styles5.input,
     testID: "form-field-input",
     ...textInputProps
   }
@@ -387,18 +519,22 @@ function withAlpha2(hex, alpha) {
   const isValid = !Number.isNaN(r) && !Number.isNaN(g) && !Number.isNaN(b);
   return isValid ? `rgba(${r}, ${g}, ${b}, ${alpha})` : hex;
 }
-var styles4 = StyleSheet.create({
+var styles6 = StyleSheet.create({
   chipContainer: {
     flexDirection: "row",
     flexWrap: "wrap",
-    // Each chip's bottom gutter also hangs off the LAST row, stacking on `Field`'s container
-    // margin (8 + 16 = 24) and dropping the block below the `FormField` beside it. Cancelling it
-    // is standard gutter compensation: inner rows keep their 8px, the block ends at Field's 16.
-    marginBottom: -CHIP_GUTTER
-  },
-  chipWrapper: {
-    marginRight: CHIP_GUTTER,
-    marginBottom: CHIP_GUTTER
+    // `gap`, NOT per-chip margins plus a compensating negative container margin.
+    //
+    // The old form was `chipWrapper { marginRight: 8, marginBottom: 8 }` with
+    // `chipContainer { marginBottom: -8 }`. Its comment blamed `Field`'s 16px container margin —
+    // that was WRONG, and worth recording: F3 was briefed on the belief that the -8 compensated for
+    // `Field` and had to move in lockstep with it. It did not. -8 cancelled the CHIP's own gutter
+    // hanging off the last row, identically whether `Field` contributed 16, 0, or anything else.
+    //
+    // The pair is still the wrong tool: it holds only while the two constants agree, and it leaves
+    // a real negative margin any measuring parent inherits. `gap` produces the byte-identical box
+    // and is correct under BOTH of `Field`'s spacing models, not just the one it was tuned against.
+    gap: CHIP_GUTTER
   },
   chip: {
     paddingHorizontal: 12,
@@ -450,12 +586,11 @@ function OutlineChip({
       "aria-pressed": ariaPressed,
       disabled,
       hitSlop: CHIP_HIT_SLOP,
-      style: styles4.chipWrapper,
       testID,
       onHoverIn: () => setHovered(true),
       onHoverOut: () => setHovered(false),
       onPress,
-      children: /* @__PURE__ */ jsx(View, { style: [styles4.chipOutline, { borderColor, backgroundColor }], children: /* @__PURE__ */ jsx(Text, { style: [styles4.chipText, styles4.chipTextOutline, { color: textColor }], children: option.label }) })
+      children: /* @__PURE__ */ jsx(View, { style: [styles6.chipOutline, { borderColor, backgroundColor }], children: /* @__PURE__ */ jsx(Text, { style: [styles6.chipText, styles6.chipTextOutline, { color: textColor }], children: option.label }) })
     }
   );
 }
@@ -481,18 +616,12 @@ function SolidChip({
       "aria-pressed": ariaPressed,
       disabled,
       hitSlop: CHIP_HIT_SLOP,
-      style: styles4.chipWrapper,
       testID,
       onPress,
-      children: /* @__PURE__ */ jsx(View, { style: [styles4.chip, { borderColor: colors.border, backgroundColor }], children: /* @__PURE__ */ jsx(Text, { style: [styles4.chipText, { color: textColor }], children: option.label }) })
+      children: /* @__PURE__ */ jsx(View, { style: [styles6.chip, { borderColor: colors.border, backgroundColor }], children: /* @__PURE__ */ jsx(Text, { style: [styles6.chipText, { color: textColor }], children: option.label }) })
     }
   );
 }
-var IS_WEB3 = Platform.OS === "web";
-function groupA11yProps(describedById, hasError) {
-  if (!IS_WEB3) return {};
-  return { "aria-invalid": hasError ? true : void 0, "aria-describedby": describedById };
-}
 var ChipSelector = ({
   label,
   options,
@@ -502,6 +631,7 @@ var ChipSelector = ({
   disabled = false,
   variant = "solid",
   containerStyle,
+  spacing,
   required = false,
   error,
   testID,
@@ -544,10 +674,21 @@ var ChipSelector = ({
     const key = String(option.value);
     return variant === "outline" ? /* @__PURE__ */ jsx(OutlineChip, { ...chipProps }, key) : /* @__PURE__ */ jsx(SolidChip, { ...chipProps }, key);
   }
-  return /* @__PURE__ */ jsx(Field, { containerStyle, error, label, required, testID, children: ({ describedById, hasError }) => /* @__PURE__ */ jsx(View, { style: styles4.chipContainer, ...groupA11yProps(describedById, hasError), children: options.map(renderChip) }) });
+  return /* @__PURE__ */ jsx(
+    Field,
+    {
+      containerStyle,
+      error,
+      label,
+      required,
+      spacing,
+      testID,
+      children: ({ describedById, hasError }) => /* @__PURE__ */ jsx(View, { style: styles6.chipContainer, ...webFieldA11y({ describedById, hasError }), children: options.map(renderChip) })
+    }
+  );
 };
-var DESCRIPTION_FONT_SIZE = 12;
-var styles5 = StyleSheet.create({
+var DESCRIPTION_FONT_SIZE2 = 12;
+var styles7 = StyleSheet.create({
   container: {
     flexDirection: "row",
     justifyContent: "space-between",
@@ -561,7 +702,7 @@ var styles5 = StyleSheet.create({
     fontWeight: "600"
   },
   description: {
-    fontSize: DESCRIPTION_FONT_SIZE,
+    fontSize: DESCRIPTION_FONT_SIZE2,
     marginTop: 2
   }
 });
@@ -587,13 +728,13 @@ var FormSwitch = ({
     View,
     {
       style: [
-        styles5.container,
+        styles7.container,
         containerStyle
       ],
       children: [
-        /* @__PURE__ */ jsxs(View, { style: styles5.textColumn, children: [
-          /* @__PURE__ */ jsx(Text, { style: [styles5.label, themeStyles.label], children: label }),
-          hasDescription ? /* @__PURE__ */ jsx(Text, { style: [styles5.description, themeStyles.description], children: description }) : null
+        /* @__PURE__ */ jsxs(View, { style: styles7.textColumn, children: [
+          /* @__PURE__ */ jsx(Text, { style: [styles7.label, themeStyles.label], children: label }),
+          hasDescription ? /* @__PURE__ */ jsx(Text, { style: [styles7.description, themeStyles.description], children: description }) : null
         ] }),
         /* @__PURE__ */ jsx(
           Switch,
@@ -618,7 +759,7 @@ var BOX_SIZE = 20;
 var BOX_RADIUS = 5;
 var CHECK_FONT_SIZE = 14;
 var DISABLED_OPACITY = 0.5;
-var styles6 = StyleSheet.create({
+var styles8 = StyleSheet.create({
   container: {
     flexDirection: "row",
     alignItems: "flex-start",
@@ -700,14 +841,14 @@ var FormCheckbox = ({
       disabled,
       onPress: toggle,
       role: "checkbox",
-      style: [styles6.container, containerStyle, disabled ? { opacity: DISABLED_OPACITY } : null],
+      style: [styles8.container, containerStyle, disabled ? { opacity: DISABLED_OPACITY } : null],
       testID,
       ...keyboardProps,
       children: [
-        /* @__PURE__ */ jsx(View, { style: [styles6.box, value ? themeStyles.boxOn : themeStyles.boxOff], children: value ? /* @__PURE__ */ jsx(Text, { style: [styles6.check, { color: colors.surface }], accessibilityElementsHidden: true, children: "\u2713" }) : null }),
-        /* @__PURE__ */ jsxs(View, { style: styles6.textColumn, children: [
-          /* @__PURE__ */ jsx(Text, { style: [styles6.label, themeStyles.label], children: label }),
-          hasHint ? /* @__PURE__ */ jsx(Text, { style: [styles6.hint, themeStyles.hint], children: hintText }) : null
+        /* @__PURE__ */ jsx(View, { style: [styles8.box, value ? themeStyles.boxOn : themeStyles.boxOff], children: value ? /* @__PURE__ */ jsx(Text, { style: [styles8.check, { color: colors.surface }], accessibilityElementsHidden: true, children: "\u2713" }) : null }),
+        /* @__PURE__ */ jsxs(View, { style: styles8.textColumn, children: [
+          /* @__PURE__ */ jsx(Text, { style: [styles8.label, themeStyles.label], children: label }),
+          hasHint ? /* @__PURE__ */ jsx(Text, { style: [styles8.hint, themeStyles.hint], children: hintText }) : null
         ] })
       ]
     }
@@ -788,13 +929,13 @@ var controlStyles = StyleSheet.create({
   optionText: { fontSize: OPTION_FONT },
   error: { fontSize: ERROR_FONT, marginTop: ERROR_GAP }
 });
-var IS_WEB4 = typeof document !== "undefined";
+var IS_WEB3 = typeof document !== "undefined";
 var ESCAPE_KEY = "Escape";
 var ACTIVE_WEIGHT = "700";
 var IDLE_WEIGHT = "400";
 function useDismiss(anchorRef, menuRef, onDismiss) {
   useEffect(() => {
-    if (!IS_WEB4) return void 0;
+    if (!IS_WEB3) return void 0;
     const onMouseDown = (event) => {
       const anchorNode = anchorRef.current;
       const menuNode = menuRef.current;
@@ -1113,6 +1254,6 @@ function DateRangeControl({
   ] });
 }
 
-export { AnchoredMenu, ChipSelector, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, Field, FormActions, FormCheckbox, FormField, FormSwitch, SelectControl, ThemedTextInput, TypeaheadControl, controlStyles, isUnmatched, suggestOptions, useThemedInput };
+export { AnchoredMenu, ChipSelector, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, Field, FormActions, FormCell, FormCheckbox, FormField, FormGrid, FormSection, FormSwitch, SelectControl, ThemedTextInput, TypeaheadControl, controlStyles, isUnmatched, suggestOptions, useThemedInput };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map