@astryxdesign/core 0.1.3 → 0.1.4-canary.02643db

package/src/MultiSelector/MultiSelector.doc.mjs

@@ -112,11 +112,17 @@ export const docs = {
           type: 'boolean',
           description: 'Disables the selector.',
         },
+        {
+          name: 'htmlName',
+          type: 'string',
+          description:
+            'The HTML name attribute for form submissions. Renders one hidden input per selected value, like a native multi-select.',
+        },
         {
           name: 'disabledMessage',
           type: 'string',
           description:
-            'Explains why the selector is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the trigger focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled MultiSelector in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+            'Explains why the selector is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the trigger focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled MultiSelector in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
         },
         {
           name: 'isLabelHidden',
@@ -233,6 +239,7 @@ export const docsZh = {
         hasSearch: '是否显示用于过滤选项的搜索输入。',
         searchPlaceholder: '搜索输入的占位文本。',
         isDisabled: '禁用选择器。',
+        htmlName: '用于表单提交的 HTML name 属性。为每个已选值渲染一个隐藏输入，类似原生多选。',
         disabledMessage:
           '解释选择器被禁用的原因。与 isDisabled 一起使用时，悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持触发器可聚焦（仍无法激活）。请使用此属性，而不是用 Tooltip 包裹被禁用的选择器。',
         isLabelHidden: '视觉上隐藏标签同时保持其可访问性。',
@@ -316,6 +323,11 @@ export const docsDense = {
         description:
           'Enable select-all when most users will want all or nearly all options selected.',
       },
+      {
+        guidance: true,
+        description:
+          'Use inside InputGroup only for a short prefix or suffix addon; prefer count or labels trigger display so the group stays single-line.',
+      },
       {
         guidance: false,
         description: 'Use for single-value selection; use Selector instead.',
@@ -352,6 +364,7 @@ export const docsDense = {
         hasSearch: 'show search input',
         searchPlaceholder: 'search placeholder',
         isDisabled: 'disables selector',
+        htmlName: 'HTML name attr; one hidden input per selected value.',
         disabledMessage:
           'why disabled; w/ isDisabled shows tooltip on hover/focus, trigger stays focusable via aria-disabled; use instead of Tooltip wrapper',
         isLabelHidden: 'visually hides label',

package/src/MultiSelector/MultiSelector.test.tsx

@@ -1042,4 +1042,37 @@ describe('MultiSelector', () => {
       expect(trigger).toHaveAttribute('tabIndex', '-1');
     });
   });
+  describe('form participation', () => {
+    it('submits one entry per selected value under htmlName', () => {
+      const {container} = render(
+        <form>
+          <MultiSelector
+            label="Fruit"
+            htmlName="fruit"
+            options={['Apple', 'Banana', 'Orange']}
+            value={['Apple', 'Orange']}
+            onChange={() => {}}
+          />
+        </form>,
+      );
+      const data = new FormData(container.querySelector('form')!);
+      expect(data.getAll('fruit')).toEqual(['Apple', 'Orange']);
+    });
+
+    it('is excluded from form data when disabled', () => {
+      const {container} = render(
+        <form>
+          <MultiSelector
+            label="Fruit"
+            htmlName="fruit"
+            options={['Apple']}
+            value={['Apple']}
+            onChange={() => {}}
+            isDisabled
+          />
+        </form>,
+      );
+      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+    });
+  });
 });

package/src/MultiSelector/MultiSelector.tsx

@@ -439,6 +439,13 @@ export interface MultiSelectorProps<
    */
   value: string[];
 
+  /**
+   * The HTML name attribute for form submissions. When set, hidden inputs
+   * carry one entry per selected value under this name, matching how a
+   * native multi-select serializes.
+   */
+  htmlName?: string;
+
   /**
    * Callback when selection changes.
    */
@@ -597,6 +604,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   renderOption,
   isDefaultOpen = false,
   'data-testid': testId,
+  htmlName,
   width,
   xstyle,
   className,
@@ -1280,6 +1288,18 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
             {renderTriggerContent()}
           </span>
         </button>
+        {htmlName != null &&
+          value.map(v => (
+            <input
+              key={v}
+              type="hidden"
+              name={htmlName}
+              value={v}
+              // Disabled native controls are excluded from form submission;
+              // mirror that for the hidden carriers.
+              disabled={isDisabled}
+            />
+          ))}
         {isBusy && <Spinner size="sm" />}
         {hasClear && value.length > 0 && !isDisabled && (
           <button

package/src/PowerSearch/PowerSearch.doc.mjs

@@ -75,7 +75,7 @@ export const docs = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'status',
@@ -223,7 +223,7 @@ export const docsZh = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'status',

package/src/RadioList/RadioList.doc.mjs

@@ -74,11 +74,17 @@ export const docs = {
       description: 'Whether all radio items are disabled.',
       default: 'false',
     },
+    {
+      name: 'htmlName',
+      type: 'string',
+      description:
+        'The HTML name attribute shared by the radio inputs, useful for form submissions. When omitted, a unique internal name still groups the radios.',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the group is disabled. Applies to the whole-group disabled state (isDisabled), not per item. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the radios focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled RadioList in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the group is disabled. Applies to the whole-group disabled state (isDisabled), not per item. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the radios focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled RadioList in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isRequired',

package/src/RadioList/RadioList.test.tsx

@@ -576,4 +576,50 @@ describe('RadioList', () => {
       }
     });
   });
+  describe('form participation', () => {
+    it('submits the selected value under htmlName', () => {
+      const {container} = render(
+        <form>
+          <RadioList label="Preference" htmlName="pref" value="b" onChange={() => {}}>
+            <RadioListItem label="Option A" value="a" />
+            <RadioListItem label="Option B" value="b" />
+          </RadioList>
+        </form>,
+      );
+      const data = new FormData(container.querySelector('form')!);
+      expect(data.get('pref')).toBe('b');
+    });
+
+    it('is excluded from form data when disabled, even with a disabledMessage', () => {
+      const {container} = render(
+        <form>
+          <RadioList
+            label="Preference"
+            htmlName="pref"
+            value="a"
+            onChange={() => {}}
+            isDisabled
+            disabledMessage="Locked"
+          >
+            <RadioListItem label="Option A" value="a" />
+          </RadioList>
+        </form>,
+      );
+      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+    });
+
+    it('keeps working as an isolated group when htmlName is omitted', () => {
+      const {container} = render(
+        <form>
+          <RadioList label="Preference" value="a" onChange={() => {}}>
+            <RadioListItem label="Option A" value="a" />
+          </RadioList>
+        </form>,
+      );
+      // Auto-generated internal name still groups the radios, but the field
+      // name is not part of the public form contract.
+      const input = container.querySelector('input[type="radio"]')!;
+      expect(input.getAttribute('name')).toBeTruthy();
+    });
+  });
 });

package/src/RadioList/RadioList.tsx

@@ -111,6 +111,13 @@ export interface RadioListProps extends Omit<
    * @default false
    */
   isDisabled?: boolean;
+
+  /**
+   * The HTML name attribute shared by the radio inputs in the group.
+   * Useful for form submissions; when omitted, a unique internal name is
+   * generated so the group still roves correctly.
+   */
+  htmlName?: string;
   /**
    * Explains why the radio group is disabled. Applies to the whole-group
    * disabled state (`isDisabled`), not individual items. When set together with
@@ -199,9 +206,11 @@ export function RadioList({
   className,
   style,
   'data-testid': dataTestId,
+  htmlName,
   children,
 }: RadioListProps) {
-  const name = useId();
+  const autoName = useId();
+  const name = htmlName ?? autoName;
   const inputID = useId();
   const labelID = useId();
   const descriptionID = useId();

package/src/RadioList/RadioListItem.tsx

@@ -254,6 +254,10 @@ export function RadioListItem({
         checked={isChecked}
         disabled={isDisabled && !keepsFocusableForMessage}
         aria-disabled={keepsFocusableForMessage ? 'true' : undefined}
+        // A focusable-disabled radio is not natively disabled, so detach it
+        // from the form instead: it keeps its name (grouping) but is excluded
+        // from submission, matching a natively disabled control.
+        form={keepsFocusableForMessage ? '' : undefined}
         required={context.isRequired}
         onChange={() => {
           if (isDisabled) {

package/src/Section/Section.test.tsx

@@ -38,9 +38,7 @@ describe('Section', () => {
   });
 
   it('renders with variant="muted"', () => {
-    const {container} = render(
-      <Section variant="muted">Content</Section>,
-    );
+    const {container} = render(<Section variant="muted">Content</Section>);
     const inner = container.firstElementChild!.firstElementChild!;
     expect(inner.className).toContain('astryx-section');
     expect(inner.className).toContain('muted');
@@ -109,9 +107,7 @@ describe('Section', () => {
   });
 
   it('renders variant in astryx class names', () => {
-    const {container} = render(
-      <Section variant="muted">Content</Section>,
-    );
+    const {container} = render(<Section variant="muted">Content</Section>);
     const inner = container.firstElementChild!.firstElementChild!;
     expect(inner.className).toContain('astryx-section');
     expect(inner.className).toContain('muted');
@@ -120,9 +116,7 @@ describe('Section', () => {
   it('accepts xstyle prop without error', () => {
     // xstyle is a StyleXStyles type; in tests stylex.create returns objects
     // that may not produce runtime styles, but the prop should be accepted
-    const {container} = render(
-      <Section xstyle={undefined}>Content</Section>,
-    );
+    const {container} = render(<Section xstyle={undefined}>Content</Section>);
     expect(container.firstElementChild).toBeInTheDocument();
   });
 
@@ -163,7 +157,7 @@ describe('Section', () => {
         <Section data-testid="inner">Inner</Section>
       </Section>,
     );
-    // Outer section's inner div should set --xds-section-padding
+    // Outer section's inner div should set --astryx-section-padding
     const outerInner = container.firstElementChild!.firstElementChild!;
     expect(outerInner.className).toBeDefined();
     // Inner section should render without error

package/src/SegmentedControl/SegmentedControl.doc.mjs

@@ -69,7 +69,7 @@ export const docs = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the control is disabled. Applies to the whole-group disabled state (isDisabled), not per segment. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the control focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled SegmentedControl in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the control is disabled. Applies to the whole-group disabled state (isDisabled), not per segment. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the control focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled SegmentedControl in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'children',

package/src/Selector/Selector.doc.mjs

@@ -86,11 +86,17 @@ export const docs = {
       description: 'Disables the selector.',
       default: 'false',
     },
+    {
+      name: 'htmlName',
+      type: 'string',
+      description:
+        'The HTML name attribute for form submissions. Renders a hidden input carrying the selected value, like a native select.',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the selector is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the trigger focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled Selector in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the selector is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the trigger focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled Selector in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isLabelHidden',
@@ -346,6 +352,11 @@ export const docsDense = {
         description:
           'Set a meaningful placeholder that hints at the expected selection (e.g. "Choose a country" not "Select...").',
       },
+      {
+        guidance: true,
+        description:
+          'Use inside InputGroup only when the selector needs a short prefix or suffix addon.',
+      },
       {
         guidance: false,
         description:

package/src/Selector/Selector.test.tsx

@@ -839,4 +839,34 @@ describe('Selector', () => {
       expect(trigger).toHaveAttribute('tabIndex', '-1');
     });
   });
+  describe('form participation', () => {
+    it('submits the selected value under htmlName', () => {
+      const {container} = render(
+        <form>
+          <Selector label="Fruit" htmlName="fruit" options={OPTIONS} value="Banana" />
+        </form>,
+      );
+      const data = new FormData(container.querySelector('form')!);
+      expect(data.get('fruit')).toBe('Banana');
+    });
+
+    it('submits an empty string when nothing is selected', () => {
+      const {container} = render(
+        <form>
+          <Selector label="Fruit" htmlName="fruit" options={OPTIONS} />
+        </form>,
+      );
+      const data = new FormData(container.querySelector('form')!);
+      expect(data.get('fruit')).toBe('');
+    });
+
+    it('is excluded from form data when disabled', () => {
+      const {container} = render(
+        <form>
+          <Selector label="Fruit" htmlName="fruit" options={OPTIONS} value="Banana" isDisabled />
+        </form>,
+      );
+      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+    });
+  });
 });

package/src/Selector/Selector.tsx

@@ -483,6 +483,13 @@ interface SelectorPropsBase<
    */
   isDefaultOpen?: boolean;
 
+  /**
+   * The HTML name attribute for form submissions. When set, a hidden input
+   * carries the selected value under this name, matching how a native
+   * select serializes.
+   */
+  htmlName?: string;
+
   /**
    * Test ID for testing frameworks.
    */
@@ -564,6 +571,7 @@ export function Selector<T extends SelectorOptionType>(
     status,
     labelTooltip,
     startIcon,
+    htmlName,
     renderOption,
     hasSearch = false,
     searchPlaceholder = 'Search...',
@@ -991,6 +999,16 @@ export function Selector<T extends SelectorOptionType>(
             {selectedItem?.label ?? placeholder}
           </span>
         </button>
+        {htmlName != null && (
+          <input
+            type="hidden"
+            name={htmlName}
+            value={value ?? ''}
+            // Disabled native controls are excluded from form submission;
+            // mirror that for the hidden carrier.
+            disabled={isDisabled}
+          />
+        )}
         {isBusy && <Spinner size="sm" />}
         {hasClear && value != null && !isDisabled && (
           <button

package/src/Slider/Slider.doc.mjs

@@ -95,11 +95,17 @@ export const docs = {
       description: 'Whether the slider is disabled.',
       default: 'false',
     },
+    {
+      name: 'htmlName',
+      type: 'string',
+      description:
+        'The HTML name attribute for form submissions. Renders hidden inputs carrying the current value (two entries in range mode).',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the slider is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the thumb focusable via aria-disabled (value changes stay blocked). Use this instead of wrapping a disabled Slider in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the slider is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the thumb focusable via aria-disabled (value changes stay blocked). Use this instead of wrapping a disabled Slider in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isOptional',
@@ -244,11 +250,16 @@ export const docsZh = {
       description: '是否禁用滑块。',
       default: 'false',
     },
+    {
+      name: 'htmlName',
+      type: 'string',
+      description: '用于表单提交的 HTML name 属性。渲染携带当前值的隐藏输入（范围模式下为两个条目）。',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the slider is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the thumb focusable via aria-disabled (value changes stay blocked). Use this instead of wrapping a disabled Slider in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the slider is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the thumb focusable via aria-disabled (value changes stay blocked). Use this instead of wrapping a disabled Slider in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isOptional',
@@ -338,6 +349,7 @@ export const docsDense = {
     marks: 'Tick marks at specified positions w/ optional labels.',
     minStepsBetweenThumbs: 'Min steps between thumbs in range mode; prevents overlap.',
     isDisabled: 'Whether slider is disabled.',
+    htmlName: 'HTML name attr; hidden inputs carry the value (two in range mode).',
     isOptional: 'Whether field is optional.',
     isRequired: 'Whether field is required.',
     isLabelHidden: 'Visually hide label.',

package/src/Slider/Slider.test.tsx

@@ -535,4 +535,34 @@ describe('Slider', () => {
       expect(screen.getByRole('slider')).toHaveAttribute('tabindex', '-1');
     });
   });
+  describe('form participation', () => {
+    it('submits the value under htmlName', () => {
+      const {container} = render(
+        <form>
+          <Slider label="Volume" htmlName="volume" value={50} />
+        </form>,
+      );
+      const data = new FormData(container.querySelector('form')!);
+      expect(data.get('volume')).toBe('50');
+    });
+
+    it('submits both range values under the same name', () => {
+      const {container} = render(
+        <form>
+          <Slider label="Price" htmlName="price" value={[20, 80] as [number, number]} />
+        </form>,
+      );
+      const data = new FormData(container.querySelector('form')!);
+      expect(data.getAll('price')).toEqual(['20', '80']);
+    });
+
+    it('is excluded from form data when disabled', () => {
+      const {container} = render(
+        <form>
+          <Slider label="Volume" htmlName="volume" value={50} isDisabled />
+        </form>,
+      );
+      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+    });
+  });
 });

package/src/Slider/Slider.tsx

@@ -111,6 +111,12 @@ export interface SliderBaseProps extends Omit<
   valueDisplay?: 'tooltip' | 'text' | 'none';
   /** Tick marks at specified positions with optional labels. */
   marks?: {value: number; label?: string}[];
+  /**
+   * The HTML name attribute for form submissions. When set, the slider
+   * renders hidden inputs carrying the current value (two in range mode,
+   * matching how paired native range inputs submit).
+   */
+  htmlName?: string;
   /** Test ID for the root element. */
   'data-testid'?: string;
 }
@@ -363,6 +369,7 @@ export function Slider({ref, ...props}: SliderProps) {
     step = 1,
     orientation = 'horizontal',
     formatValue,
+    htmlName,
     valueDisplay = 'tooltip',
     marks,
     width,
@@ -803,6 +810,19 @@ export function Slider({ref, ...props}: SliderProps) {
           }),
           stylex.props(styles.sliderRow),
         )}>
+        {htmlName != null &&
+          values.map((v, i) => (
+            <input
+              // Positional identity: index 0 is the start thumb, 1 the end.
+              key={i === 0 ? 'start' : 'end'}
+              type="hidden"
+              name={htmlName}
+              value={String(v)}
+              // Disabled native controls are excluded from form submission;
+              // mirror that for the hidden carrier.
+              disabled={isDisabled}
+            />
+          ))}
         <div
           ref={mergeRefs(ref, trackRef, disabledMessageTooltip.ref)}
           {...(isRange ? {role: 'group', 'aria-label': label} : undefined)}

package/src/Spinner/Spinner.tsx

@@ -70,6 +70,7 @@ const styles = stylex.create({
   canvas: {
     backfaceVisibility: 'hidden',
     display: 'block',
+    willChange: 'transform',
     // Slow the rotation dramatically under reduced-motion rather than freezing
     // it (a frozen spinner reads as broken), matching ProgressBar's approach.
     // The role="status" + "Loading" label still convey busy state (obs-6).

package/src/Switch/Switch.doc.mjs

@@ -62,11 +62,17 @@ export const docs = {
       description: 'Whether the switch is disabled.',
       default: 'false',
     },
+    {
+      name: 'htmlName',
+      type: 'string',
+      description:
+        'The HTML name attribute for the underlying checkbox input, useful for form submissions (submits "on" when the switch is on).',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the switch is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the switch focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled Switch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the switch is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the switch focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled Switch in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isOptional',
@@ -203,11 +209,16 @@ export const docsZh = {
       description: '开关是否被禁用。',
       default: 'false',
     },
+    {
+      name: 'htmlName',
+      type: 'string',
+      description: '底层复选框输入的 HTML name 属性，用于表单提交（开启时提交 "on"）。',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the switch is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the switch focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled Switch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the switch is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the switch focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled Switch in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isOptional',
@@ -309,6 +320,7 @@ export const docsDense = {
     isLabelHidden: 'Visually hides label; still accessible to screen readers.',
     description: 'Description text below label.',
     isDisabled: 'Whether switch is disabled.',
+    htmlName: 'HTML name attr for the checkbox; submits "on" when on.',
     isOptional: 'Whether field is optional; mutually exclusive w/ isRequired.',
     isRequired: 'Whether switch is required; mutually exclusive w/ isOptional.',
     status: 'Status indicator w/ type + message; colored message box, sets aria-invalid on error.',

package/src/Switch/Switch.test.tsx

@@ -470,4 +470,42 @@ describe('Switch', () => {
       expect(screen.getByRole('switch')).toBeDisabled();
     });
   });
+  describe('form participation', () => {
+    it('submits under htmlName when on', () => {
+      const {container} = render(
+        <form>
+          <Switch label="Notify" htmlName="notify" value={true} onChange={() => {}} />
+        </form>,
+      );
+      const data = new FormData(container.querySelector('form')!);
+      expect(data.get('notify')).toBe('on');
+    });
+
+    it('is excluded from form data when disabled, even with a disabledMessage', () => {
+      const {container} = render(
+        <form>
+          <Switch
+            label="Notify"
+            htmlName="notify"
+            value={true}
+            onChange={() => {}}
+            isDisabled
+            disabledMessage="Locked"
+          />
+        </form>,
+      );
+      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+    });
+
+    it('submits nothing when off or when htmlName is omitted', () => {
+      const {container} = render(
+        <form>
+          <Switch label="Off" htmlName="off" value={false} onChange={() => {}} />
+          <Switch label="Unnamed" value={true} onChange={() => {}} />
+        </form>,
+      );
+      const data = new FormData(container.querySelector('form')!);
+      expect([...data.keys()]).toEqual([]);
+    });
+  });
 });