@multiplatform.one/forms 6.0.4 → 6.3.0

package/src/FieldLayout.stories.tsx

@@ -0,0 +1,184 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useForm } from "@tanstack/react-form";
+import { Input as TamaguiInput, Paragraph, YStack, XStack } from "tamagui";
+import { Button } from "./Button";
+import { Form } from "./Form";
+import { Field, FieldLayout } from "./fieldLayout";
+
+const meta: Meta<typeof FieldLayout> = {
+  title: "Forms/FieldLayout",
+  component: FieldLayout,
+  parameters: { status: { type: "beta" } },
+  argTypes: {
+    label: { control: "text" },
+    helperText: { control: "text" },
+    error: { control: "text" },
+    required: { control: "boolean" },
+    compactSpacing: { control: "boolean" },
+    size: { control: "select", options: ["$2", "$3", "$4", "$6"] },
+    id: { control: "text" },
+  },
+  args: {
+    id: "fl-input",
+    label: "Email address",
+    helperText: "We never share your email",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof FieldLayout>;
+
+export const Basic: Story = {
+  render: (args) => (
+    <YStack maxWidth={360}>
+      <FieldLayout {...args}>
+        <TamaguiInput id={args.id} placeholder="you@example.com" />
+      </FieldLayout>
+    </YStack>
+  ),
+};
+
+export const ErrorStates: Story = {
+  render: () => (
+    <YStack gap="$6" maxWidth={360}>
+      <FieldLayout
+        id="fl-err-string"
+        label="String error"
+        helperText="Helper should be hidden"
+        error="This field is invalid"
+      >
+        <TamaguiInput id="fl-err-string" />
+      </FieldLayout>
+      <FieldLayout
+        id="fl-err-bool"
+        label="Boolean error"
+        helperText="Helper should remain visible"
+        error={true}
+      >
+        <TamaguiInput id="fl-err-bool" />
+      </FieldLayout>
+      <FieldLayout
+        id="fl-err-empty"
+        label="Empty string error"
+        helperText="Empty string should act as no message"
+        error=""
+      >
+        <TamaguiInput id="fl-err-empty" />
+      </FieldLayout>
+    </YStack>
+  ),
+};
+
+export const AnatomyEdgeCases: Story = {
+  render: () => (
+    <YStack gap="$6" maxWidth={360}>
+      <FieldLayout id="fl-required" label="Required field" required>
+        <TamaguiInput id="fl-required" />
+      </FieldLayout>
+      <FieldLayout id="fl-nolabel" helperText="No label means compact $1 gap">
+        <TamaguiInput id="fl-nolabel" />
+      </FieldLayout>
+      <FieldLayout id="fl-compact" label="Compact spacing" compactSpacing helperText="Compact gap">
+        <TamaguiInput id="fl-compact" />
+      </FieldLayout>
+      <FieldLayout
+        id="fl-node-label"
+        label={
+          <XStack gap="$2" alignItems="center">
+            <Paragraph fontWeight="700">ReactNode</Paragraph>
+            <Paragraph size="$1">(custom node label)</Paragraph>
+          </XStack>
+        }
+      >
+        <TamaguiInput id="fl-node-label" />
+      </FieldLayout>
+      <FieldLayout
+        id="fl-long"
+        label="Long messages"
+        error="This error message is extremely long and keeps going to make sure long validation copy wraps correctly under the control without pushing the layout sideways or clipping any of its content at narrow widths"
+      >
+        <TamaguiInput id="fl-long" />
+      </FieldLayout>
+    </YStack>
+  ),
+};
+
+export const FieldWrapper: Story = {
+  render: () => {
+    const Example = () => {
+      const form = useForm({
+        defaultValues: { username: "initial-value" },
+        onSubmit: async ({ value }) => {
+          action("onSubmit")(value);
+        },
+      });
+      return (
+        <Form form={form}>
+          <YStack gap="$4" maxWidth={360}>
+            <Field form={form} name="username" defaultValue="initial-value">
+              {(field) => (
+                <FieldLayout
+                  id="field-username"
+                  label="Username"
+                  helperText="TanStack Field wrapper"
+                  field={field as any}
+                >
+                  <TamaguiInput
+                    id="field-username"
+                    value={String(field.state.value ?? "")}
+                    onChangeText={(text) => field.handleChange(text)}
+                  />
+                </FieldLayout>
+              )}
+            </Field>
+            <XStack gap="$2">
+              <Button action="submit">Submit</Button>
+              <Button onPress={() => form.reset()}>Reset</Button>
+            </XStack>
+          </YStack>
+        </Form>
+      );
+    };
+    return <Example />;
+  },
+};
+
+export const FieldRequiredValidator: Story = {
+  render: () => {
+    const Example = () => {
+      const form = useForm({
+        defaultValues: { nickname: "" },
+        onSubmit: async ({ value }) => {
+          action("onSubmit")(value);
+        },
+      });
+      return (
+        <Form form={form}>
+          <YStack gap="$4" maxWidth={360}>
+            <Field
+              form={form}
+              name="nickname"
+              validators={{
+                onSubmit: ({ value }: { value: unknown }) =>
+                  !value ? "Nickname is required" : undefined,
+              }}
+            >
+              {(field) => (
+                <FieldLayout id="field-nickname" label="Nickname" required field={field as any}>
+                  <TamaguiInput
+                    id="field-nickname"
+                    value={String(field.state.value ?? "")}
+                    onChangeText={(text) => field.handleChange(text)}
+                  />
+                </FieldLayout>
+              )}
+            </Field>
+            <Button action="submit">Submit</Button>
+          </YStack>
+        </Form>
+      );
+    };
+    return <Example />;
+  },
+};

package/src/Fieldset.stories.tsx

@@ -0,0 +1,70 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Input as TamaguiInput, YStack } from "tamagui";
+import { FieldLayout } from "./fieldLayout";
+import { Fieldset, FormSectionStack } from "./FormSection";
+
+function Field({ id, label, ...rest }: { id: string; label: string; secureTextEntry?: boolean }) {
+  return (
+    <FieldLayout id={id} label={label}>
+      <TamaguiInput id={id} placeholder={label} {...rest} />
+    </FieldLayout>
+  );
+}
+
+const meta: Meta<typeof Fieldset> = {
+  title: "Forms/Fieldset",
+  component: Fieldset,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Semantic fieldset + legend grouping for form fields. Alias of FormSection (same rhythm tokens). On web renders `<fieldset>`/`<legend>`; native keeps a heading label.",
+      },
+    },
+  },
+  argTypes: {
+    label: { control: "text" },
+    maxWidth: { control: "text" },
+    fieldset: { control: "boolean" },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Fieldset>;
+
+export const Default: Story = {
+  name: "Main",
+  render: () => (
+    <YStack maxWidth={480}>
+      <Fieldset label="Contact">
+        <Field id="full-name" label="Full name" />
+        <Field id="email" label="Email" />
+      </Fieldset>
+    </YStack>
+  ),
+};
+
+export const Stacked: Story = {
+  render: () => (
+    <YStack maxWidth={480}>
+      <FormSectionStack>
+        <Fieldset label="Account">
+          <Field id="username" label="Username" />
+          <Field id="password" label="Password" secureTextEntry />
+        </Fieldset>
+        <Fieldset label="Profile">
+          <Field id="display-name" label="Display name" />
+        </Fieldset>
+      </FormSectionStack>
+    </YStack>
+  ),
+};
+
+export const FluidWidth: Story = {
+  render: () => (
+    <Fieldset label="Wide section" maxWidth="fluid">
+      <Field id="notes" label="Notes" />
+    </Fieldset>
+  ),
+};

package/src/FloatingPanel/index.native.tsx

@@ -0,0 +1,228 @@
+/**
+ * FloatingPanel (native) — React Native Modal bottom sheet.
+ *
+ * The web implementation (./index.tsx) anchors a floating-ui panel to the
+ * trigger and falls back to a Tamagui `Sheet modal` on small viewports and
+ * native. On device (Expo Go, tamagui 2.0.0-rc.41) the modal Sheet's
+ * portal/animation machinery never presents — tapping a Select or Date
+ * trigger flips `open` and nothing appears. This native variant swaps the
+ * overlay for a core React Native `Modal`, which is a native view-controller
+ * presentation: no portal host, no animation driver, no DOM measurement.
+ *
+ * Same public API as ./index.tsx. Web bundles never load this file
+ * (tamagui-build emits it only into the *.native.js outputs).
+ *
+ * Semantics preserved from the sheet path:
+ * - tap trigger → sheet slides up from the bottom (full width, themed
+ *   surface, drag-handle affordance, safe-area padding)
+ * - selecting a value commits (the field's own onValueChange) and the field
+ *   closes the panel
+ * - backdrop tap and the Android back button dismiss WITHOUT committing
+ *
+ * Hit-testing / open-race notes:
+ * - Fabric + Tamagui XGroup steal the responder without firing onPress, so
+ *   this Pressable owns the open gesture and forces pointerEvents="none" on
+ *   the trigger tree. Interactive siblings (clear) MUST use `triggerEnd`.
+ * - If both this Pressable and a child onPress toggle `open` in the same
+ *   gesture, React batches setOpen(true) then setOpen(prev => !prev) → false
+ *   and the sheet never appears. Fields should not also toggle open on native.
+ * - Opening a Modal under the same finger can synthesize a backdrop press;
+ *   backdrop dismiss is armed only after Modal.onShow + a short delay.
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  KeyboardAvoidingView,
+  Modal,
+  Platform,
+  Pressable,
+  ScrollView as RNScrollView,
+  StyleSheet,
+  useWindowDimensions,
+  View as RNView,
+} from "react-native";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { View, YStack } from "tamagui";
+import { t } from "../shared/t";
+import type { FloatingPanelProps } from "./index";
+
+// Re-export the hook + constants so Select / Combobox / external consumers
+// resolve identically on native (their floating cores are unused on device
+// but must still import cleanly).
+export {
+  useFloatingPanel,
+  panelAnimationDuration,
+  panelGrowDuration,
+  panelTransition,
+  panelViewportPadding,
+} from "./useFloatingPanel";
+export type { UseFloatingPanelOptions, UseFloatingPanelReturn } from "./useFloatingPanel";
+export type { FloatingPanelProps } from "./index";
+
+/** Native never has a >sm web viewport; AdaptivePopup uses this to pick Sheet mode. */
+export function useViewportGtSm() {
+  return false;
+}
+
+const sheetMaxHeightRatio = 0.85;
+// Home-indicator / gesture-bar clearance (no react-native-safe-area-context
+// dependency in this package).
+const bottomInset = Platform.OS === "ios" ? 24 : 16;
+
+export function FloatingPanel({
+  open,
+  onOpenChange,
+  trigger,
+  triggerEnd,
+  children,
+  scrollable,
+  disabled,
+  contentPadding = "default",
+  header,
+  scrollViewProps,
+  triggerA11y,
+  sheetFill,
+}: FloatingPanelProps) {
+  const { knobProps } = useResolvedKnobs();
+  const { height: windowHeight } = useWindowDimensions();
+  const [backdropArmed, setBackdropArmed] = useState(false);
+  const armTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const close = useCallback(() => onOpenChange(false), [onOpenChange]);
+  const handleTriggerPress = useCallback(() => {
+    if (!disabled) onOpenChange(!open);
+  }, [disabled, onOpenChange, open]);
+
+  const handleBackdropPress = useCallback(() => {
+    if (backdropArmed) close();
+  }, [backdropArmed, close]);
+
+  const handleModalShow = useCallback(() => {
+    if (armTimerRef.current) clearTimeout(armTimerRef.current);
+    // One frame + small delay so the opening tap cannot dismiss immediately.
+    armTimerRef.current = setTimeout(() => setBackdropArmed(true), 280);
+  }, []);
+
+  useEffect(() => {
+    if (!open) {
+      setBackdropArmed(false);
+      if (armTimerRef.current) {
+        clearTimeout(armTimerRef.current);
+        armTimerRef.current = null;
+      }
+    }
+    return () => {
+      if (armTimerRef.current) clearTimeout(armTimerRef.current);
+    };
+  }, [open]);
+
+  const framePadding = contentPadding === "none" ? "$0" : knobProps.panelPadding.padding;
+  const frameGap = contentPadding === "none" ? undefined : knobProps.gapLg.gap;
+  const maxHeight = Math.round(windowHeight * sheetMaxHeightRatio);
+
+  const content = scrollable ? (
+    <RNScrollView
+      // sheetFill: the list scrollport fills the fixed-height sheet; default:
+      // content-sized (flexGrow 0) so small pickers hug their content.
+      style={sheetFill ? { flexGrow: 1, flexShrink: 1 } : { flexGrow: 0 }}
+      keyboardShouldPersistTaps="handled"
+      {...(scrollViewProps as any)}
+    >
+      {children}
+    </RNScrollView>
+  ) : (
+    children
+  );
+
+  return (
+    <>
+      <RNView style={{ flexDirection: "row", alignItems: "center", width: "100%" }}>
+        <Pressable
+          onPress={handleTriggerPress}
+          disabled={disabled}
+          accessibilityRole="button"
+          accessibilityState={{ disabled: !!disabled, expanded: !!open }}
+          {...(triggerA11y?.label ? { accessibilityLabel: triggerA11y.label } : undefined)}
+          {...(triggerA11y?.value
+            ? { accessibilityValue: { text: triggerA11y.value } }
+            : undefined)}
+          {...(triggerA11y?.hint ? { accessibilityHint: triggerA11y.hint } : undefined)}
+          // Stretch to the cell/row width — content-sized triggers (~70pt) make
+          // most of the edit box look tappable but miss the Pressable.
+          style={{
+            flex: 1,
+            minWidth: 0,
+            alignSelf: "stretch",
+            width: "100%",
+            opacity: disabled ? 0.5 : 1,
+          }}
+        >
+          {/* Own the hit target — see file header for why pointerEvents="none". */}
+          <RNView pointerEvents="none" collapsable={false} style={{ width: "100%" }}>
+            {trigger}
+          </RNView>
+        </Pressable>
+        {triggerEnd}
+      </RNView>
+      <Modal
+        visible={open}
+        transparent
+        animationType="slide"
+        statusBarTranslucent
+        onRequestClose={close}
+        onShow={handleModalShow}
+      >
+        <KeyboardAvoidingView
+          style={{ flex: 1, justifyContent: "flex-end" }}
+          behavior={Platform.OS === "ios" ? "padding" : undefined}
+        >
+          <Pressable
+            style={StyleSheet.absoluteFill}
+            onPress={handleBackdropPress}
+            accessibilityRole="button"
+            accessibilityLabel={t("Close")}
+          >
+            <View flex={1} backgroundColor="rgba(0,0,0,0.4)" />
+          </Pressable>
+          {/*
+            Sheet sits above the absoluteFill backdrop in z-order (later sibling).
+            Do NOT claim the responder on a wrapper here — that steals presses
+            from option rows / calendar days and blocks commit.
+          */}
+          <YStack
+            backgroundColor="$background"
+            borderTopLeftRadius="$6"
+            borderTopRightRadius="$6"
+            maxHeight={maxHeight}
+            // sheetFill opens at full sheet height (flexShrink keeps the
+            // keyboard from pushing the top of the sheet off-screen).
+            {...(sheetFill ? { height: maxHeight, flexShrink: 1 } : undefined)}
+            paddingTop="$2"
+            paddingBottom={bottomInset}
+            elevation="$4"
+            // VoiceOver escape gesture (two-finger Z) dismisses the sheet.
+            onAccessibilityEscape={close}
+          >
+            <View
+              alignSelf="center"
+              width={40}
+              height={4}
+              borderRadius={2}
+              backgroundColor="$color8"
+              marginBottom="$2"
+            />
+            <YStack
+              padding={framePadding}
+              gap={frameGap}
+              flexShrink={1}
+              {...(sheetFill ? { flex: 1, minHeight: 0 } : undefined)}
+            >
+              {header}
+              {content}
+            </YStack>
+          </YStack>
+        </KeyboardAvoidingView>
+      </Modal>
+    </>
+  );
+}