@multiplatform.one/forms 6.0.4 → 6.3.0

package/src/fields/Checkbox/CheckboxGroup.stories.tsx

@@ -0,0 +1,251 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useForm } from "@tanstack/react-form";
+import { Paragraph, YStack } from "tamagui";
+import { Button } from "../../Button";
+import { Form } from "../../Form";
+import { CheckboxGroup } from "./CheckboxGroup";
+
+const meta: Meta<typeof CheckboxGroup> = {
+  title: "Forms/CheckboxGroup",
+  component: CheckboxGroup,
+  parameters: { status: { type: "beta" } },
+  argTypes: {
+    label: { control: "text" },
+    helperText: { control: "text" },
+    error: { control: "text" },
+    required: { control: "boolean" },
+    disabled: { control: "boolean" },
+    readOnly: { control: "boolean" },
+    skeleton: { control: "boolean" },
+    compact: { control: "boolean" },
+    orientation: { control: "select", options: ["vertical", "horizontal"] },
+    size: { control: "select", options: ["$2", "$3", "$4"] },
+  },
+  args: {
+    label: "Features",
+    helperText: "Select all that apply",
+    options: [
+      { value: "notifications", label: "Push Notifications" },
+      { value: "emails", label: "Email Updates" },
+      { value: "sms", label: "SMS Alerts" },
+    ],
+    defaultValue: ["emails"],
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof CheckboxGroup>;
+
+export const Basic: Story = {
+  render: (args) => (
+    <YStack maxWidth={400}>
+      <CheckboxGroup {...args} onValueChange={action("onValueChange")} />
+    </YStack>
+  ),
+};
+
+/**
+ * Selection-card mode: checkbox in a leading slot, bold label to its right,
+ * muted `option.description` under the label; the whole card toggles.
+ */
+export const CardMode: Story = {
+  render: (args) => (
+    <YStack maxWidth={400}>
+      <CheckboxGroup
+        {...args}
+        card
+        label="Payment methods"
+        helperText={undefined}
+        options={[
+          {
+            value: "card",
+            label: "Credit or debit card",
+            description: "Visa, Mastercard, and American Express.",
+          },
+          {
+            value: "bank",
+            label: "Bank transfer",
+            description: "Direct transfer from your bank account.",
+          },
+          {
+            value: "wallet",
+            label: "Digital wallet",
+            description: "Apple Pay, Google Pay, or PayPal.",
+          },
+        ]}
+        defaultValue={["card"]}
+        onChange={action("onChange")}
+      />
+    </YStack>
+  ),
+};
+
+export const States: Story = {
+  render: () => (
+    <YStack gap="$6" maxWidth={400}>
+      <CheckboxGroup
+        label="Group disabled"
+        disabled
+        options={[
+          { value: "a", label: "Alpha" },
+          { value: "b", label: "Beta" },
+        ]}
+        defaultValue={["a"]}
+      />
+      <CheckboxGroup
+        label="Group read-only"
+        readOnly
+        options={[
+          { value: "a", label: "Alpha" },
+          { value: "b", label: "Beta" },
+        ]}
+        defaultValue={["a"]}
+      />
+      <CheckboxGroup
+        label="String error"
+        error="Pick at least one"
+        helperText="Helper should be hidden by the error"
+        options={[
+          { value: "a", label: "Alpha" },
+          { value: "b", label: "Beta" },
+        ]}
+      />
+      <CheckboxGroup
+        label="Boolean error"
+        error={true}
+        helperText="Helper should stay visible"
+        options={[
+          { value: "a", label: "Alpha" },
+          { value: "b", label: "Beta" },
+        ]}
+      />
+    </YStack>
+  ),
+};
+
+export const SkeletonState: Story = {
+  render: () => (
+    <YStack gap="$6" maxWidth={400}>
+      <CheckboxGroup
+        label="Loading vertical"
+        skeleton
+        options={[
+          { value: "a", label: "Alpha" },
+          { value: "b", label: "Beta" },
+          { value: "c", label: "Gamma" },
+        ]}
+      />
+      <CheckboxGroup label="Loading horizontal (default count)" skeleton orientation="horizontal" />
+    </YStack>
+  ),
+};
+
+export const OptionEdgeCases: Story = {
+  render: () => (
+    <YStack gap="$6" maxWidth={400}>
+      <Paragraph size="$2">empty options</Paragraph>
+      <CheckboxGroup label="Empty" options={[]} />
+      <Paragraph size="$2">single option</Paragraph>
+      <CheckboxGroup label="Single" options={[{ value: "only", label: "Only option" }]} />
+      <Paragraph size="$2">duplicate values</Paragraph>
+      <CheckboxGroup
+        label="Duplicates"
+        options={[
+          { value: "dup", label: "First duplicate" },
+          { value: "dup", label: "Second duplicate" },
+          { value: "unique", label: "Unique" },
+        ]}
+      />
+      <Paragraph size="$2">disabled option inside enabled group</Paragraph>
+      <CheckboxGroup
+        label="Partially disabled"
+        options={[
+          { value: "on", label: "Enabled option" },
+          { value: "off", label: "Disabled option", disabled: true },
+          { value: "on2", label: "Another enabled" },
+        ]}
+        defaultValue={["off"]}
+      />
+      <Paragraph size="$2">all options disabled</Paragraph>
+      <CheckboxGroup
+        label="All disabled"
+        options={[
+          { value: "a", label: "Alpha", disabled: true },
+          { value: "b", label: "Beta", disabled: true },
+        ]}
+      />
+      <Paragraph size="$2">unknown selected value</Paragraph>
+      <CheckboxGroup
+        label="Unknown selection"
+        options={[
+          { value: "a", label: "Alpha" },
+          { value: "b", label: "Beta" },
+        ]}
+        defaultValue={["ghost"]}
+      />
+      <Paragraph size="$2">long labels</Paragraph>
+      <CheckboxGroup
+        label="Long labels"
+        options={[
+          {
+            value: "long",
+            label:
+              "This option label is extremely long and should wrap gracefully next to its checkbox without pushing it out of alignment or clipping",
+          },
+          { value: "short", label: "Short" },
+        ]}
+      />
+    </YStack>
+  ),
+};
+
+export const HorizontalWrap: Story = {
+  render: () => (
+    <YStack maxWidth={320} borderWidth={1} borderColor="$borderColor" padding="$2">
+      <CheckboxGroup
+        label="Horizontal in narrow container"
+        orientation="horizontal"
+        options={[
+          { value: "one", label: "Option one" },
+          { value: "two", label: "Option two" },
+          { value: "three", label: "Option three" },
+          { value: "four", label: "Option four" },
+          { value: "five", label: "Option five" },
+        ]}
+      />
+    </YStack>
+  ),
+};
+
+export const RequiredForm: Story = {
+  render: () => {
+    const Example = () => {
+      const form = useForm({
+        defaultValues: { permissions: [] as string[] },
+        onSubmit: async ({ value }) => {
+          action("onSubmit")(value);
+        },
+      });
+      return (
+        <Form form={form}>
+          <YStack gap="$4" maxWidth={400}>
+            <CheckboxGroup
+              label="Permissions"
+              name="permissions"
+              required
+              options={[
+                { value: "read", label: "Read" },
+                { value: "write", label: "Write" },
+                { value: "admin", label: "Admin" },
+              ]}
+              helperText="Submit empty to trigger required error"
+            />
+            <Button action="submit">Submit</Button>
+          </YStack>
+        </Form>
+      );
+    };
+    return <Example />;
+  },
+};

package/src/fields/Checkbox/CheckboxGroup.tsx

@@ -1,27 +1,39 @@
 import type { ReactNode } from "react";
-import { useCallback } from "react";
+import { useCallback, useState } from "react";
 import type {
   CheckedState,
   CheckboxProps as TamaguiCheckboxProps,
+  FontSizeTokens,
   LabelProps,
   SizeTokens,
 } from "tamagui";
-import { XStack, YStack } from "tamagui";
+import { View, XStack, YStack } from "tamagui";
 import { Field, FieldLayout } from "../../fieldLayout";
 import { Skeleton } from "../../Skeleton";
 import type { AnyFormApi } from "../../types";
 import {
+  clampRadiusForControl,
   getFieldError,
   mergeFieldHandler,
   useFormField,
   useResolvedValidators,
 } from "../../shared/utils";
-import { Checkbox } from "./Checkbox";
+import { Checkbox, getCheckboxInlineGap } from "./Checkbox";
+import {
+  CheckboxCardContent,
+  CheckboxCardDescription,
+  CheckboxCardFrame,
+  CheckboxCardLabel,
+  getCardDescriptionSize,
+  getCheckboxCardLayout,
+} from "./CheckboxCard";
 
 export interface CheckboxGroupOption {
   label: string;
   value: string;
   disabled?: boolean;
+  /** Muted secondary line under the label; rendered in `card` mode. */
+  description?: string;
 }
 
 export interface CheckboxGroupProps {
@@ -39,6 +51,12 @@ export interface CheckboxGroupProps {
   id?: string;
   value?: string[];
   defaultValue?: string[];
+  /**
+   * Canonical change handler, consistent with the rest of the field family.
+   * Prefer this over `onValueChange`.
+   */
+  onChange?: (value: string[]) => void;
+  /** @deprecated Use `onChange` instead. */
   onValueChange?: (value: string[]) => void;
   onBlur?: (...args: any[]) => void;
   options?: CheckboxGroupOption[];
@@ -48,6 +66,12 @@ export interface CheckboxGroupProps {
   skeleton?: boolean;
   /** When true, uses compact sizing */
   compact?: boolean;
+  /**
+   * When true, renders each option as a selection card (LC-22): checkbox in a
+   * leading slot, bold label to its right, muted `option.description` under
+   * the label; the whole card toggles.
+   */
+  card?: boolean;
 }
 
 export function CheckboxGroup({
@@ -65,6 +89,7 @@ export function CheckboxGroup({
   id: idProp,
   value,
   defaultValue,
+  onChange,
   onValueChange,
   onBlur,
   options,
@@ -73,24 +98,48 @@ export function CheckboxGroup({
   children,
   skeleton,
   compact,
+  card,
 }: CheckboxGroupProps) {
-  const { resolvedForm, knobProps, id } = useFormField({
+  // Canonical `onChange` and the alias `onValueChange` both fire from the
+  // single emit site below (same reconciliation as Switch).
+  const handleValueChange = (newValues: string[]) => {
+    onChange?.(newValues);
+    onValueChange?.(newValues);
+  };
+  const { resolvedForm, knobProps, disabledState, id } = useFormField({
     form: formProp,
     id: idProp,
     compact,
   });
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
+  // Uncontrolled state for standalone use (no form, no value prop) — without
+  // this, defaultValue-only groups are inert because currentValues is
+  // recomputed from props on every render.
+  const [internalValues, setInternalValues] = useState<string[]>(defaultValue ?? []);
 
   if (skeleton) {
+    // Mirror the real anatomy (LC-20 SKELETON-MIRRORS-ANATOMY): each row is a
+    // 20px control square at the same clamped radius the real Checkbox uses,
+    // then a label bar separated by the real box↔label gap. Label widths are
+    // DETERMINISTIC per index (never %, never random): a percentage width
+    // inside an auto-width horizontal row resolves against a width computed
+    // without it, so the bar paints past the row's edge and fuses with the
+    // next item's square.
     const optionCount = options?.length ?? 3;
     const Container = orientation === "horizontal" ? XStack : YStack;
+    const inlineGap = getCheckboxInlineGap(knobProps.space);
+    const controlRadius = clampRadiusForControl(knobProps.borderRadius.borderRadius, 2);
+    const labelWidths = [88, 64, 76];
     return (
       <FieldLayout id={id} label={label} size={size} knobProps={knobProps}>
         <Container gap="$2">
           {Array.from({ length: optionCount }, (_, i) => (
-            <XStack key={i} gap="$2" alignItems="center">
-              <Skeleton variant="rounded" width={20} height={20} />
-              <Skeleton variant="text" width="50%" height={14} />
+            <XStack key={i} gap={inlineGap} alignItems="center">
+              {/* Mirror the 44px pressable target box around the 20px glyph */}
+              <View width={44} height={44} alignItems="center" justifyContent="center">
+                <Skeleton variant="rounded" width={20} height={20} borderRadius={controlRadius} />
+              </View>
+              <Skeleton variant="text" width={labelWidths[i % labelWidths.length]} height={14} />
             </XStack>
           ))}
         </Container>
@@ -114,16 +163,91 @@ export function CheckboxGroup({
 
     const Container = orientation === "horizontal" ? XStack : YStack;
 
+    if (card) {
+      const layout = getCheckboxCardLayout(knobProps.space);
+      const descriptionSize = getCardDescriptionSize(size || knobProps.sizeToken);
+      return (
+        <Container gap="$2">
+          {options.map((option, index) => {
+            // Include the index so duplicate option values don't produce
+            // duplicate React keys / DOM ids.
+            const itemId = `${id}-${index}-${option.value}`;
+            const labelId = `${itemId}-label`;
+            const descriptionId = option.description ? `${itemId}-description` : undefined;
+            const isChecked = currentValues.includes(option.value);
+            const isDisabled = disabled || option.disabled;
+            const emit = (newValues: string[]) => {
+              handleChange?.(newValues);
+              handleValueChange(newValues);
+            };
+            return (
+              <CheckboxCardFrame
+                key={`${index}-${option.value}`}
+                active={isChecked}
+                {...layout}
+                borderRadius={knobProps.borderRadius.borderRadius}
+                // LC-40: selection cards dim as chrome (label rides the card).
+                {...(isDisabled ? disabledState.chromeKnobProps : undefined)}
+                // Whole card toggles. Clicking the checkbox itself fires both
+                // this and the checkbox's own handler; both compute the same
+                // next value from the same render, so the double emit is
+                // idempotent (same pattern as the compound FocusGroup.Item).
+                onPress={() => {
+                  if (isDisabled || readOnly) return;
+                  emit(toggleValue(currentValues, option.value, !isChecked));
+                }}
+              >
+                <Checkbox
+                  id={itemId}
+                  checked={isChecked}
+                  onCheckedChange={(checked) => {
+                    if (isDisabled || readOnly) return;
+                    emit(toggleValue(currentValues, option.value, checked));
+                  }}
+                  disabled={isDisabled}
+                  readOnly={readOnly}
+                  size={size}
+                  checkboxProps={{
+                    ...checkboxProps,
+                    "aria-labelledby": labelId,
+                    ...(descriptionId && { "aria-describedby": descriptionId }),
+                  }}
+                />
+                <CheckboxCardContent>
+                  {/* fontWeight after size: the size variant's font weight
+                      would otherwise override the styled bold default */}
+                  <CheckboxCardLabel
+                    id={labelId}
+                    size={(size || knobProps.sizeToken) as FontSizeTokens}
+                    fontWeight="600"
+                  >
+                    {option.label}
+                  </CheckboxCardLabel>
+                  {option.description ? (
+                    <CheckboxCardDescription id={descriptionId} size={descriptionSize}>
+                      {option.description}
+                    </CheckboxCardDescription>
+                  ) : null}
+                </CheckboxCardContent>
+              </CheckboxCardFrame>
+            );
+          })}
+        </Container>
+      );
+    }
+
     return (
       <Container gap="$2">
-        {options.map((option) => {
-          const itemId = `${id}-${option.value}`;
+        {options.map((option, index) => {
+          // Include the index so duplicate option values don't produce
+          // duplicate React keys / DOM ids.
+          const itemId = `${id}-${index}-${option.value}`;
           const isChecked = currentValues.includes(option.value);
           const isDisabled = disabled || option.disabled;
 
           return (
             <Checkbox
-              key={option.value}
+              key={`${index}-${option.value}`}
               label={option.label}
               id={itemId}
               checked={isChecked}
@@ -131,7 +255,7 @@ export function CheckboxGroup({
                 if (isDisabled || readOnly) return;
                 const newValues = toggleValue(currentValues, option.value, checked);
                 handleChange?.(newValues);
-                onValueChange?.(newValues);
+                handleValueChange(newValues);
               }}
               disabled={isDisabled}
               readOnly={readOnly}
@@ -145,7 +269,7 @@ export function CheckboxGroup({
   };
 
   if (!resolvedForm || !name) {
-    const currentValues = value ?? defaultValue ?? [];
+    const currentValues = value ?? internalValues;
     return (
       <FieldLayout
         id={id}
@@ -157,8 +281,11 @@ export function CheckboxGroup({
         size={size}
         knobProps={knobProps}
         onBlur={onBlur}
+        // LC-40: FieldLayout owns the dimWhole assembly dim (keepLabel pins
+        // the sibling label/helper readable) — it needs the disabled state.
+        disabled={disabled}
       >
-        {renderItems(currentValues, onValueChange)}
+        {renderItems(currentValues, setInternalValues)}
       </FieldLayout>
     );
   }
@@ -186,6 +313,8 @@ export function CheckboxGroup({
             size={size}
             knobProps={knobProps}
             onBlur={mergeFieldHandler(field, "handleBlur", onBlur)}
+            // LC-40: see standalone branch — FieldLayout carries dimWhole.
+            disabled={disabled}
           >
             {renderItems(currentValues, (newValues) => {
               field.handleChange(newValues as any);

package/src/fields/Checkbox/Checkboxes.stories.tsx

@@ -0,0 +1,145 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useState } from "react";
+import { Paragraph, XStack, YStack } from "tamagui";
+import { CheckboxGroup } from "./CheckboxGroup";
+import { Checkboxes } from "./index";
+
+const meta: Meta = {
+  title: "Forms/Checkboxes",
+  parameters: { status: { type: "beta" } },
+};
+
+export default meta;
+type Story = StoryObj;
+
+function CompoundExample({ card = true }: { card?: boolean }) {
+  const [values, setValues] = useState<Record<string, boolean>>({
+    analytics: true,
+    updates: false,
+    marketing: false,
+  });
+  const entries: Array<[string, string, string]> = [
+    ["analytics", "Product analytics", "Usage metrics that help us improve the product."],
+    ["updates", "Release updates", "A short note whenever a new version ships."],
+    ["marketing", "Marketing emails", "Occasional tips, offers, and product news."],
+  ];
+  return (
+    <YStack gap="$4" maxWidth={400}>
+      <Checkboxes
+        values={values}
+        onValuesChange={(next) => {
+          setValues(next as typeof values);
+          action("onValuesChange")(next);
+        }}
+      >
+        <Checkboxes.Title>Notification Preferences</Checkboxes.Title>
+        <Checkboxes.FocusGroup orientation="vertical">
+          <Checkboxes.Group>
+            {entries.map(([value, label, description]) => (
+              <Checkboxes.Group.Item key={value}>
+                <Checkboxes.FocusGroup.Item value={value}>
+                  {card ? (
+                    <Checkboxes.Card>
+                      <Checkboxes.Checkbox>
+                        <Checkboxes.Checkbox.Indicator />
+                      </Checkboxes.Checkbox>
+                      <Checkboxes.Card.Content>
+                        <Checkboxes.Card.Label>{label}</Checkboxes.Card.Label>
+                        <Checkboxes.Card.Description>{description}</Checkboxes.Card.Description>
+                      </Checkboxes.Card.Content>
+                    </Checkboxes.Card>
+                  ) : (
+                    <XStack gap="$2" alignItems="center">
+                      <Checkboxes.Checkbox>
+                        <Checkboxes.Checkbox.Indicator />
+                      </Checkboxes.Checkbox>
+                      <Paragraph>{label}</Paragraph>
+                    </XStack>
+                  )}
+                </Checkboxes.FocusGroup.Item>
+              </Checkboxes.Group.Item>
+            ))}
+          </Checkboxes.Group>
+        </Checkboxes.FocusGroup>
+      </Checkboxes>
+      <Paragraph size="$2">
+        Selected:{" "}
+        {Object.entries(values)
+          .filter(([, v]) => v)
+          .map(([k]) => k)
+          .join(", ") || "none"}
+      </Paragraph>
+    </YStack>
+  );
+}
+
+export const CardMode: Story = {
+  render: () => <CompoundExample card />,
+};
+
+export const PlainMode: Story = {
+  render: () => <CompoundExample card={false} />,
+};
+
+/**
+ * Side-by-side comparison of the compound `Checkboxes` API and the
+ * options-driven `CheckboxGroup` API with equivalent data, for verifying
+ * their knob/state behaviour stays aligned.
+ */
+export const ComparisonWithCheckboxGroup: Story = {
+  render: () => {
+    const Example = () => {
+      const [compound, setCompound] = useState<Record<string, boolean>>({
+        a: true,
+        b: false,
+        c: false,
+      });
+      return (
+        <XStack gap="$8" alignItems="flex-start" flexWrap="wrap">
+          <YStack gap="$3" width={280}>
+            <Paragraph size="$2" color="$placeholderColor">
+              Checkboxes (compound)
+            </Paragraph>
+            <Checkboxes
+              values={compound}
+              onValuesChange={(next) => setCompound(next as typeof compound)}
+            >
+              <Checkboxes.FocusGroup orientation="vertical">
+                <Checkboxes.Group>
+                  {(["a", "b", "c"] as const).map((value) => (
+                    <Checkboxes.Group.Item key={value}>
+                      <Checkboxes.FocusGroup.Item value={value}>
+                        <XStack gap="$2" alignItems="center">
+                          <Checkboxes.Checkbox>
+                            <Checkboxes.Checkbox.Indicator />
+                          </Checkboxes.Checkbox>
+                          <Paragraph>Option {value.toUpperCase()}</Paragraph>
+                        </XStack>
+                      </Checkboxes.FocusGroup.Item>
+                    </Checkboxes.Group.Item>
+                  ))}
+                </Checkboxes.Group>
+              </Checkboxes.FocusGroup>
+            </Checkboxes>
+          </YStack>
+          <YStack gap="$3" width={280}>
+            <Paragraph size="$2" color="$placeholderColor">
+              CheckboxGroup (options)
+            </Paragraph>
+            <CheckboxGroup
+              label="Options"
+              options={[
+                { value: "a", label: "Option A" },
+                { value: "b", label: "Option B" },
+                { value: "c", label: "Option C" },
+              ]}
+              defaultValue={["a"]}
+            />
+          </YStack>
+        </XStack>
+      );
+    };
+    return <Example />;
+  },
+};