@multiplatform.one/forms 7.6.3 → 7.7.1

package/src/InputParts/InputParts.stories.tsx

@@ -0,0 +1,230 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import {
+  EnvelopeIcon,
+  EyeIcon,
+  MagnifyingGlassIcon,
+  WarningCircleIcon,
+} from "@phosphor-icons/react";
+import { useState } from "react";
+import { Paragraph, YStack } from "tamagui";
+import { Input as InputParts } from "./index";
+
+const meta: Meta<typeof InputParts> = {
+  title: "Forms/InputParts",
+  component: InputParts,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "The unstyled anatomy the Input field is assembled from, for consumers who need a shape the field does not offer. `InputParts.Box` is the bordered frame that owns the focus ring; `Area` is the text-entry itself and never rings; `Icon`, `Button` and `Section` are the slots either side of it; `Label`, `Info` and `Meta` are the chrome above and below. Reach for the `Input` FIELD first — this is the escape hatch.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof InputParts>;
+
+/**
+ * The whole anatomy at once: Label above, Box holding a leading Icon and the
+ * Area, Meta reserving the caption line underneath.
+ */
+export const Anatomy: Story = {
+  render: () => (
+    <InputParts width={320}>
+      <InputParts.Label htmlFor="anatomy-email">Email</InputParts.Label>
+      <InputParts.Box>
+        <InputParts.Icon adornment="leading">
+          <EnvelopeIcon />
+        </InputParts.Icon>
+        <InputParts.Area
+          id="anatomy-email"
+          placeholder="you@example.com"
+          onChangeText={action("onChangeText")}
+        />
+      </InputParts.Box>
+      <InputParts.Meta helperText="We only use this to send receipts." />
+    </InputParts>
+  ),
+};
+
+/**
+ * RING-ON-BOX (LC-71): the Box carries the focus ring so adornments sit inside
+ * it; the Area's own outline is killed. Tab into the field and the whole frame
+ * rings once, not the text run.
+ */
+export const FocusRingOnTheBox: Story = {
+  render: () => (
+    <YStack gap="$4" width={320}>
+      <Paragraph size="$2">Tab in — the border box rings, the input does not.</Paragraph>
+      <InputParts>
+        <InputParts.Box>
+          <InputParts.Icon adornment="leading">
+            <MagnifyingGlassIcon />
+          </InputParts.Icon>
+          <InputParts.Area placeholder="Search" onChangeText={action("onChangeText")} />
+        </InputParts.Box>
+      </InputParts>
+    </YStack>
+  ),
+};
+
+/** Leading and trailing slots. The trailing end-cap is square by size recipe. */
+export const Adornments: Story = {
+  render: () => (
+    <YStack gap="$4" width={320}>
+      <InputParts>
+        <InputParts.Box>
+          <InputParts.Icon adornment="leading">
+            <MagnifyingGlassIcon />
+          </InputParts.Icon>
+          <InputParts.Area placeholder="Leading icon" />
+        </InputParts.Box>
+      </InputParts>
+      <InputParts>
+        <InputParts.Box>
+          <InputParts.Area placeholder="Trailing icon" />
+          <InputParts.Icon adornment="trailing">
+            <EnvelopeIcon />
+          </InputParts.Icon>
+        </InputParts.Box>
+      </InputParts>
+      <InputParts>
+        <InputParts.Box>
+          <InputParts.Icon adornment="leading">
+            <MagnifyingGlassIcon />
+          </InputParts.Icon>
+          <InputParts.Area placeholder="Both ends" />
+          <InputParts.Icon adornment="trailing">
+            <EnvelopeIcon />
+          </InputParts.Icon>
+        </InputParts.Box>
+      </InputParts>
+    </YStack>
+  ),
+};
+
+/**
+ * `InputParts.Button` is the pressable end-cap — a reveal toggle, a clear, a
+ * copy. It squares off to the control height so the frame stays rectangular.
+ */
+export const TrailingButton: Story = {
+  render: () => {
+    const Example = () => {
+      const [secure, setSecure] = useState(true);
+      return (
+        <InputParts width={320}>
+          <InputParts.Label htmlFor="parts-password">Password</InputParts.Label>
+          <InputParts.Box paddingInlineEnd={0}>
+            <InputParts.Area
+              id="parts-password"
+              placeholder="••••••••"
+              secureTextEntry={secure}
+              onChangeText={action("onChangeText")}
+            />
+            <InputParts.Button
+              glyphRing
+              type="button"
+              aria-label={secure ? "Show password" : "Hide password"}
+              onPress={() => {
+                setSecure((prev) => !prev);
+                action("togglePasswordVisibility")(!secure);
+              }}
+            >
+              <InputParts.Icon aria-hidden>
+                <EyeIcon />
+              </InputParts.Icon>
+            </InputParts.Button>
+          </InputParts.Box>
+          <InputParts.Meta helperText={secure ? "Hidden" : "Visible"} />
+        </InputParts>
+      );
+    };
+    return <Example />;
+  },
+};
+
+/**
+ * STABLE GROUND (Axiom 8 / DG-FORM-04): `Meta` owns ONE caption slot. The error
+ * replaces the helper in place, so surfacing it shifts nothing below.
+ */
+export const MetaReservesOneLine: Story = {
+  render: () => (
+    <YStack gap="$5" width={320}>
+      <InputParts>
+        <InputParts.Label>Helper</InputParts.Label>
+        <InputParts.Box>
+          <InputParts.Area placeholder="Valid" />
+        </InputParts.Box>
+        <InputParts.Meta helperText="Two to thirty characters." />
+      </InputParts>
+      <InputParts>
+        <InputParts.Label>Error replaces it</InputParts.Label>
+        <InputParts.Box>
+          <InputParts.Area placeholder="Invalid" aria-invalid />
+          <InputParts.Icon adornment="trailing" color="$red10">
+            <WarningCircleIcon aria-hidden />
+          </InputParts.Icon>
+        </InputParts.Box>
+        <InputParts.Meta
+          helperText="Two to thirty characters."
+          displayError="Enter at least two characters."
+        />
+      </InputParts>
+    </YStack>
+  ),
+};
+
+/** `Info` is the caption primitive `Meta` picks; use it directly for prose. */
+export const Info: Story = {
+  render: () => (
+    <InputParts width={320}>
+      <InputParts.Label>Display name</InputParts.Label>
+      <InputParts.Box>
+        <InputParts.Area placeholder="Ada Lovelace" />
+      </InputParts.Box>
+      <InputParts.Info>Shown next to everything you publish.</InputParts.Info>
+    </InputParts>
+  ),
+};
+
+/** `TextArea` is the multi-line Area: same focus wiring, no ring of its own. */
+export const MultiLine: Story = {
+  render: () => (
+    <InputParts width={360}>
+      <InputParts.Label htmlFor="parts-notes">Notes</InputParts.Label>
+      <InputParts.Box alignItems="flex-start" height="auto" paddingVertical="$2">
+        <InputParts.TextArea
+          id="parts-notes"
+          rows={4}
+          placeholder="Anything the team should know"
+          onChangeText={action("onChangeText")}
+        />
+      </InputParts.Box>
+      <InputParts.Meta helperText="Markdown is not parsed here." />
+    </InputParts>
+  ),
+};
+
+/** Disabled chrome lives on the Box, not on the Area. */
+export const DisabledBox: Story = {
+  render: () => (
+    <YStack gap="$4" width={320}>
+      <InputParts>
+        <InputParts.Box>
+          <InputParts.Area placeholder="Enabled" />
+        </InputParts.Box>
+      </InputParts>
+      <InputParts>
+        <InputParts.Box disabled>
+          <InputParts.Icon adornment="leading">
+            <EnvelopeIcon />
+          </InputParts.Icon>
+          <InputParts.Area placeholder="Disabled" disabled />
+        </InputParts.Box>
+      </InputParts>
+    </YStack>
+  ),
+};

package/src/InputParts/index.tsx

@@ -27,6 +27,8 @@ import {
 import {
   ensureCompositeFocusRing,
   ensureFocusVisibleRing,
+  FOCUS_RING_CLIPPED_OFFSET,
+  FOCUS_RING_HALO_OFFSET,
   isTouchSurface,
   recipeFamilies,
   resolveGlyphPaint,
@@ -219,7 +221,9 @@ export function boxRingMode(
 }
 
 export function boxRingOffset(mode: "inset" | "outset" | undefined): number {
-  return mode === "outset" ? 2 : -2;
+  // Both branches are LC-71 §4 sanctioned offsets: the clipping inset when the
+  // Box clips its adornments, the shape halo when it does not (MPO-92).
+  return mode === "outset" ? FOCUS_RING_HALO_OFFSET : FOCUS_RING_CLIPPED_OFFSET;
 }
 
 export const inputPartsRingCss = `/* LC-71: ring on Box (adornments inside); Area never outlines.
@@ -781,6 +785,13 @@ const InputAreaImpl = InputFrame.styleable<{
     focusVisibleStyle: focusVisibleStyleProp,
     className: classNameProp,
     inputMode: inputModeProp,
+    flex: flexProp,
+    width: widthProp,
+    minWidth: minWidthProp,
+    maxWidth: maxWidthProp,
+    height: heightProp,
+    minHeight: minHeightProp,
+    maxHeight: maxHeightProp,
     ...props
   } = areaProps as typeof areaProps & {
     focusStyle?: Record<string, unknown>;
@@ -788,6 +799,13 @@ const InputAreaImpl = InputFrame.styleable<{
     className?: string;
     inputMode?: InputModeValue;
     type?: string;
+    flex?: number | string;
+    width?: number | string;
+    minWidth?: number | string;
+    maxWidth?: number | string;
+    height?: number | string;
+    minHeight?: number | string;
+    maxHeight?: number | string;
   };
   const { knobProps } = useResolvedKnobs();
   const theme = useTheme();
@@ -799,6 +817,11 @@ const InputAreaImpl = InputFrame.styleable<{
   // number-pad↔numeric, decimal-pad↔decimal, email-address↔email.
   const resolvedInputMode = inputModeProp ?? mapKeyboardTypeToInputMode(keyboardType);
   const resolvedKeyboardType = keyboardType ?? mapInputModeToKeyboardType(resolvedInputMode);
+  // Duration (and any Area with a numeric width / flex 0) must not sit inside
+  // a flex:1 wrapper — that wrapper grows with the Box, then Section's
+  // justifyContent:center floats the cluster in the leftover space. OTP still
+  // pins width on Box, not Area, so it keeps the grow wrapper.
+  const hugWidth = flexProp === 0 || typeof widthProp === "number";
 
   return (
     // LC-06/LC-10 (UX-P12): in a table cell the flex wrapper and the raw
@@ -806,7 +829,20 @@ const InputAreaImpl = InputFrame.styleable<{
     // (min-width:auto floors flex items at it); width 100% makes the input
     // adopt the flexed width instead of its size-attribute default. Explicit
     // consumer widths (OTP digit boxes) still win via the later spread.
-    <View flex={1} {...(inTableCell ? { minWidth: 0 } : undefined)}>
+    <View
+      flex={hugWidth ? 0 : 1}
+      {...(hugWidth && typeof widthProp === "number"
+        ? {
+            width: widthProp,
+            minWidth: minWidthProp ?? widthProp,
+            maxWidth: maxWidthProp ?? widthProp,
+          }
+        : undefined)}
+      {...(heightProp != null
+        ? { height: heightProp, minHeight: minHeightProp ?? 0, maxHeight: maxHeightProp }
+        : undefined)}
+      {...(inTableCell ? { minWidth: 0 } : undefined)}
+    >
       <InputFrame
         aria-describedby={fieldDescribedBy}
         {...nativeA11yProps}
@@ -837,7 +873,25 @@ const InputAreaImpl = InputFrame.styleable<{
                   : undefined
         }
         {...props}
+        {...(flexProp != null ? { flex: flexProp } : undefined)}
+        {...(widthProp != null
+          ? { width: widthProp, minWidth: minWidthProp, maxWidth: maxWidthProp }
+          : undefined)}
+        {...(heightProp != null
+          ? { height: heightProp, minHeight: minHeightProp, maxHeight: maxHeightProp }
+          : undefined)}
         {...webAreaAttrs(classNameProp)}
+        {...(isWeb && typeof heightProp === "number"
+          ? {
+              // Beat the UA / `$true` 44px min on <input> when a recipe height is set
+              // (Duration size:$3 is 36; a 44 input overflows the box).
+              style: {
+                height: heightProp,
+                minHeight: typeof minHeightProp === "number" ? minHeightProp : 0,
+                maxHeight: typeof maxHeightProp === "number" ? maxHeightProp : heightProp,
+              },
+            }
+          : undefined)}
         {...AREA_NO_OUTLINE}
         focusStyle={{ ...focusStyleProp, ...AREA_NO_OUTLINE }}
         focusVisibleStyle={{ ...focusVisibleStyleProp, ...AREA_NO_OUTLINE }}

package/src/InputParts/inputPartsStories.spec.tsx

@@ -0,0 +1,122 @@
+/**
+ * Mounts every Forms/InputParts story and asserts the anatomy each one exists
+ * to show. The theme hooks stay REAL: Box height, icon size and the caption
+ * type ramp all come out of useResolvedKnobs, so a stub would measure a
+ * geometry the gallery never paints.
+ */
+import { cleanup } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import type { ReactElement } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import * as storiesModule from "./InputParts.stories";
+
+afterEach(cleanup);
+
+const meta = storiesModule.default;
+const {
+  Anatomy,
+  FocusRingOnTheBox,
+  Adornments,
+  TrailingButton,
+  MetaReservesOneLine,
+  Info,
+  MultiLine,
+  DisabledBox,
+} = storiesModule;
+
+type StoryLike = { render?: (args: Record<string, unknown>) => ReactElement };
+
+function mount(story: StoryLike) {
+  if (!story.render) throw new Error("story has no render");
+  return renderWithProviders(story.render({ ...(meta.args as Record<string, unknown>) }));
+}
+
+const stories = {
+  Anatomy,
+  FocusRingOnTheBox,
+  Adornments,
+  TrailingButton,
+  MetaReservesOneLine,
+  Info,
+  MultiLine,
+  DisabledBox,
+} as const;
+
+describe("Forms/InputParts stories", () => {
+  it("files under its own Forms title, separate from the Input field's", () => {
+    expect(meta.title).toBe("Forms/InputParts");
+    expect(meta.title).not.toBe("Forms/Input");
+  });
+
+  it.each(Object.entries(stories))("%s mounts something interactive", (_name, story) => {
+    const { container } = mount(story as StoryLike);
+    expect(container.querySelector("input, textarea, button")).toBeTruthy();
+  });
+
+  it("Anatomy wires the label to the control it names", () => {
+    const { container } = mount(Anatomy as StoryLike);
+    const input = container.querySelector("#anatomy-email");
+    expect(input).toBeTruthy();
+    expect(container.querySelector("label[for='anatomy-email']")).toBeTruthy();
+  });
+
+  it("Anatomy renders the helper caption under the box", () => {
+    const { getByText } = mount(Anatomy as StoryLike);
+    expect(getByText("We only use this to send receipts.")).toBeTruthy();
+  });
+
+  it("Adornments builds three boxes: leading, trailing, and both", () => {
+    const { container } = mount(Adornments as StoryLike);
+    const placeholders = Array.from(container.querySelectorAll("input")).map((i) =>
+      i.getAttribute("placeholder"),
+    );
+    expect(placeholders).toEqual(["Leading icon", "Trailing icon", "Both ends"]);
+  });
+
+  it("TrailingButton exposes a labelled reveal toggle beside the field", () => {
+    const { container } = mount(TrailingButton as StoryLike);
+    const button = container.querySelector("[aria-label='Show password']");
+    expect(button).toBeTruthy();
+    expect(container.querySelector("#parts-password")).toBeTruthy();
+  });
+
+  /**
+   * STABLE GROUND: Meta owns ONE caption slot. The error REPLACES the helper,
+   * so the errored field must not show both lines.
+   */
+  it("MetaReservesOneLine replaces the helper with the error rather than stacking them", () => {
+    const { container, getByText } = mount(MetaReservesOneLine as StoryLike);
+    expect(getByText("Enter at least two characters.")).toBeTruthy();
+    // The valid field keeps its helper; the errored one does not add a second line.
+    const helpers = Array.from(container.querySelectorAll("*")).filter(
+      (el) => el.children.length === 0 && el.textContent === "Two to thirty characters.",
+    );
+    expect(helpers.length).toBe(1);
+  });
+
+  it("MetaReservesOneLine announces the error to assistive tech", () => {
+    const { container } = mount(MetaReservesOneLine as StoryLike);
+    const alert = container.querySelector("[role='alert']");
+    expect(alert?.textContent).toBe("Enter at least two characters.");
+  });
+
+  it("Info renders caption prose without a Meta wrapper", () => {
+    const { getByText, container } = mount(Info as StoryLike);
+    expect(getByText("Shown next to everything you publish.")).toBeTruthy();
+    expect(container.querySelector("[role='alert']")).toBeNull();
+  });
+
+  it("MultiLine mounts a textarea, not a single-line input", () => {
+    const { container } = mount(MultiLine as StoryLike);
+    expect(container.querySelector("textarea#parts-notes")).toBeTruthy();
+  });
+
+  it("DisabledBox disables only the second field, leaving the first usable", () => {
+    const { container } = mount(DisabledBox as StoryLike);
+    const inputs = Array.from(container.querySelectorAll("input"));
+    expect(inputs.length).toBe(2);
+    expect(inputs[0].disabled).toBe(false);
+    expect(inputs[1].disabled).toBe(true);
+  });
+});

package/src/Skeleton/Skeleton.stories.tsx

@@ -0,0 +1,148 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Preset } from "@multiplatform.one/theme";
+import { Paragraph, XStack, YStack } from "tamagui";
+import { Skeleton, SkeletonCircle, SkeletonText } from "./index";
+
+const meta: Meta<typeof Skeleton> = {
+  title: "Forms/Skeleton",
+  component: Skeleton,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "The placeholder every field paints while its value is loading — what `skeleton` on Input, Select, CheckboxGroup and the rest resolves to. A flat blob: it takes the radius knob but never draws a border, and its pulse rides the animation knob, so `animation: none` stops it dead rather than dimming it.",
+      },
+    },
+  },
+  argTypes: {
+    variant: { control: "select", options: ["text", "circular", "rectangular", "rounded"] },
+    animate: { control: "boolean" },
+    width: { control: "text" },
+    height: { control: "text" },
+  },
+  args: {
+    variant: "text",
+    animate: true,
+    width: 240,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Skeleton>;
+
+export const Basic: Story = {
+  render: (args) => <Skeleton {...args} />,
+};
+
+/** The four variants. `text` and `circular` carry their own height. */
+export const Variants: Story = {
+  render: () => (
+    <YStack gap="$4">
+      {(["text", "rounded", "rectangular"] as const).map((variant) => (
+        <YStack key={variant} gap="$2">
+          <Paragraph size="$2">{variant}</Paragraph>
+          <Skeleton variant={variant} width={240} height={variant === "text" ? undefined : 48} />
+        </YStack>
+      ))}
+      <YStack gap="$2">
+        <Paragraph size="$2">circular</Paragraph>
+        <Skeleton variant="circular" width={48} height={48} />
+      </YStack>
+    </YStack>
+  ),
+};
+
+/**
+ * `SkeletonText` stacks lines and shortens the last one, which is what makes a
+ * block of bones read as a paragraph rather than a table.
+ */
+export const TextLines: Story = {
+  render: () => (
+    <YStack gap="$6" width={320}>
+      <YStack gap="$2">
+        <Paragraph size="$2">one line</Paragraph>
+        <SkeletonText />
+      </YStack>
+      <YStack gap="$2">
+        <Paragraph size="$2">three lines, last at 70%</Paragraph>
+        <SkeletonText lines={3} />
+      </YStack>
+      <YStack gap="$2">
+        <Paragraph size="$2">five lines, last at 40%</Paragraph>
+        <SkeletonText lines={5} lastLineWidth="40%" />
+      </YStack>
+    </YStack>
+  ),
+};
+
+/** `SkeletonCircle` sizes itself one height step above the control ramp. */
+export const Circles: Story = {
+  render: () => (
+    <XStack gap="$4" alignItems="center">
+      <SkeletonCircle />
+      <SkeletonCircle size={32} />
+      <SkeletonCircle size={64} />
+    </XStack>
+  ),
+};
+
+/** What a loading row actually looks like: avatar, name, two lines of body. */
+export const LoadingRow: Story = {
+  render: () => (
+    <XStack gap="$3" width={360} alignItems="flex-start">
+      <SkeletonCircle size={40} />
+      <YStack flex={1} gap="$2">
+        <Skeleton variant="text" width="45%" />
+        <SkeletonText lines={2} />
+      </YStack>
+    </XStack>
+  ),
+};
+
+/**
+ * MOTION-RIDES-KNOB (LC-68 / LC-20): the pulse is on when the animation knob
+ * is, and gone when it is not. `animate={false}` is the same off switch at the
+ * call site — neither leaves a half-speed shimmer behind.
+ */
+export const MotionOff: Story = {
+  render: () => (
+    <XStack gap="$6" alignItems="flex-start">
+      <YStack gap="$2" width={180}>
+        <Paragraph size="$2">animation knob on</Paragraph>
+        <SkeletonText lines={3} />
+      </YStack>
+      <YStack gap="$2" width={180}>
+        <Paragraph size="$2">animate={"{false}"}</Paragraph>
+        <SkeletonText lines={3} animate={false} />
+      </YStack>
+      <Preset overrides={{ animation: "none" }}>
+        <YStack gap="$2" width={180}>
+          <Paragraph size="$2">animation: none</Paragraph>
+          <SkeletonText lines={3} />
+        </YStack>
+      </Preset>
+    </XStack>
+  ),
+};
+
+/**
+ * R-CLAMP / R-PILL: a text bone squares off at `borderRadius: none`, and a
+ * circle stays round at every radius value because it declares R-PILL.
+ */
+export const RadiusKnob: Story = {
+  render: () => (
+    <XStack gap="$6" alignItems="flex-start">
+      {(["none", "medium", "large"] as const).map((borderRadius) => (
+        <Preset key={borderRadius} overrides={{ borderRadius }}>
+          <YStack gap="$2" width={160}>
+            <Paragraph size="$2">borderRadius: {borderRadius}</Paragraph>
+            <Skeleton variant="text" width={140} />
+            <Skeleton variant="rounded" width={140} height={40} />
+            <SkeletonCircle size={40} />
+          </YStack>
+        </Preset>
+      ))}
+    </XStack>
+  ),
+};