@multiplatform.one/forms 7.51.0 → 7.53.0

package/src/Form/index.tsx

@@ -325,14 +325,14 @@ export function Form<TFormData extends Record<string, any>, TFormValidator = any
               <TamaguiForm ref={setFormRef} onSubmit={handleSubmit} {...tamaguiFormProps}>
                 <YStack
                   data-mpo-form-layout=""
-                  data-gap={knobProps.gap.gap}
+                  data-gap={knobProps.fieldGap.gap}
                   data-size-token={knobProps.sizeToken}
                   width="100%"
                   minWidth={0}
                   // A readable column: fields and actions read as one group on a
                   // wide screen. `maxWidth` on the Form ejects (e.g. "100%").
                   maxWidth={(tamaguiFormProps.maxWidth as never) ?? FORM_READABLE_WIDTH}
-                  {...knobProps.gap}
+                  {...knobProps.fieldGap}
                   {...(tamaguiFormProps.flex != null
                     ? { flex: tamaguiFormProps.flex as never }
                     : {})}

package/src/FormGrid.tsx

@@ -27,7 +27,7 @@ export interface FormGridProps {
    */
   maxColumns?: FormGridColumns;
   /**
-   * Gap between fields. Defaults to the within-group role (`knobProps.gap`),
+   * Gap between fields. Defaults to the field rhythm (`knobProps.fieldGap`, LC-154),
    * never `sizeToken`. Number = px eject; token string allowed.
    */
   gap?: number | string;
@@ -52,7 +52,7 @@ function resolveWideColumns(
  */
 export function FormGrid({ columns = 1, maxColumns = 2, gap, children }: FormGridProps) {
   const { knobProps } = useResolvedKnobs();
-  const gapFragment = gap === undefined ? knobProps.gap : { gap };
+  const gapFragment = gap === undefined ? knobProps.fieldGap : { gap };
   const resolvedGap = gapFragment.gap;
   const wideColumns = resolveWideColumns(columns, maxColumns);
 

package/src/FormSection.tsx

@@ -13,8 +13,8 @@ export interface FormSectionProps {
    */
   maxWidth?: number | "fluid";
   /**
-   * Gap between fields inside the section. Defaults to the semantic
-   * within-group gap (`knobProps.gap`, DG-LAY-03) so the preset's scale
+   * Gap between fields inside the section. Defaults to the field rhythm
+   * (`knobProps.fieldGap`, LC-154; DG-LAY-03) so the preset's scale
    * restyles form rhythm; explicit values eject.
    */
   gap?: number | string;
@@ -30,7 +30,7 @@ export interface FormSectionProps {
 /**
  * Labeled form section with semantic gap rhythm.
  *
- * Field gap defaults to the within-group semantic gap (`knobProps.gap`);
+ * Field gap defaults to the field rhythm (`knobProps.fieldGap`, LC-154);
  * stack multiple sections with {@link FormSectionStack}, whose gap defaults
  * to the between-groups gap (`knobProps.gapLg`) — always one step larger, so
  * section rhythm stays larger than field rhythm on every scale
@@ -47,7 +47,7 @@ export function FormSection({
 }: FormSectionProps) {
   const useFieldset = fieldset && isWeb;
   const { knobProps } = useResolvedKnobs();
-  const resolvedGap = gap ?? knobProps.gap.gap;
+  const resolvedGap = gap ?? knobProps.fieldGap.gap;
 
   return (
     <YStack

package/src/fieldRhythm.spec.tsx

@@ -0,0 +1,48 @@
+/**
+ * LC-154 COMPACT-FORM-HEAD, field rhythm: a label sits closer to its own
+ * control than to the field above it. Field stacks take the `fieldGap` role
+ * ($4), one step wider than the label-to-control gap's floor ($2) and the
+ * row role ($3).
+ */
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { defaultKnobs, resolveKnobs, spacingRoles } from "@multiplatform.one/theme";
+import { cleanup } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { FieldLayout } from "./fieldLayout";
+import { FormGrid } from "./FormGrid";
+import { FormSection } from "./FormSection";
+
+afterEach(cleanup);
+
+const step = (token: string) => Number(token.replace(/^\$/, ""));
+
+describe("field rhythm (LC-154)", () => {
+  it("the fieldGap role is $4 and wider than the label gap and the row role", () => {
+    expect(spacingRoles.fieldGap).toBe("$4");
+    expect(step(spacingRoles.fieldGap)).toBeGreaterThan(step(spacingRoles.gap));
+    expect(step(spacingRoles.fieldGap)).toBeGreaterThan(step(spacingRoles.gapSm));
+    expect(resolveKnobs(defaultKnobs).knobProps.fieldGap).toEqual({ gap: "$4" });
+  });
+
+  it("FormGrid and FormSection stack fields at the field rhythm", () => {
+    const { container } = renderWithProviders(
+      <FormSection label="Details">
+        <FormGrid>
+          <FieldLayout label="Description" id="d">
+            <input id="d" />
+          </FieldLayout>
+          <FieldLayout label="Status" id="s">
+            <input id="s" />
+          </FieldLayout>
+        </FormGrid>
+      </FormSection>,
+    );
+    const gaps = [...container.querySelectorAll("[data-gap]")].map((el) =>
+      el.getAttribute("data-gap"),
+    );
+    expect(gaps).toContain("$4");
+    expect(gaps).not.toContain("$3");
+    const labelGap = container.querySelector("[data-label-gap]")?.getAttribute("data-label-gap");
+    expect(step(labelGap ?? "$9")).toBeLessThan(step("$4"));
+  });
+});

package/types/FieldGroup.d.ts

@@ -10,7 +10,7 @@ export interface FieldGroupProps {
      */
     columns?: FormGridColumns;
     /**
-     * Gap between fields. Defaults to the within-group role (`knobProps.gap`),
+     * Gap between fields. Defaults to the field rhythm (`knobProps.fieldGap`, LC-154),
      * never `sizeToken`.
      */
     gap?: number | string;

package/types/FormGrid.d.ts

@@ -14,7 +14,7 @@ export interface FormGridProps {
      */
     maxColumns?: FormGridColumns;
     /**
-     * Gap between fields. Defaults to the within-group role (`knobProps.gap`),
+     * Gap between fields. Defaults to the field rhythm (`knobProps.fieldGap`, LC-154),
      * never `sizeToken`. Number = px eject; token string allowed.
      */
     gap?: number | string;

package/types/FormSection.d.ts

@@ -9,8 +9,8 @@ export interface FormSectionProps {
      */
     maxWidth?: number | "fluid";
     /**
-     * Gap between fields inside the section. Defaults to the semantic
-     * within-group gap (`knobProps.gap`, DG-LAY-03) so the preset's scale
+     * Gap between fields inside the section. Defaults to the field rhythm
+     * (`knobProps.fieldGap`, LC-154; DG-LAY-03) so the preset's scale
      * restyles form rhythm; explicit values eject.
      */
     gap?: number | string;
@@ -25,7 +25,7 @@ export interface FormSectionProps {
 /**
  * Labeled form section with semantic gap rhythm.
  *
- * Field gap defaults to the within-group semantic gap (`knobProps.gap`);
+ * Field gap defaults to the field rhythm (`knobProps.fieldGap`, LC-154);
  * stack multiple sections with {@link FormSectionStack}, whose gap defaults
  * to the between-groups gap (`knobProps.gapLg`) — always one step larger, so
  * section rhythm stays larger than field rhythm on every scale