@multiplatform.one/forms 7.7.0 → 7.7.2

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>
+  ),
+};

package/src/Skeleton/skeletonStories.spec.tsx

@@ -0,0 +1,107 @@
+/**
+ * Mounts every Forms/Skeleton story and asserts what it exists to show. The
+ * theme hooks stay REAL: text-bone height comes from the size recipe and the
+ * pulse gates on knobProps.transition, so a stub would measure neither.
+ *
+ * Geometry is read off the CLASS, not `style`. Tamagui compiles width, height
+ * and radius into atomic classes (`_w-240px`, `_w-7037` for 70%), and only the
+ * pulse stays an inline style — so `el.style.width` is empty on every bone.
+ */
+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 "./Skeleton.stories";
+
+afterEach(cleanup);
+
+const meta = storiesModule.default;
+const { Basic, Variants, TextLines, Circles, LoadingRow, MotionOff, RadiusKnob } = 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>) }));
+}
+
+/** Every bone is a SkeletonFrame, which Tamagui names `is_Skeleton`. */
+function bones(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll<HTMLElement>(".is_Skeleton"));
+}
+
+const classesOf = (el: HTMLElement) => (el.getAttribute("class") ?? "").split(" ");
+const widthClass = (el: HTMLElement) => classesOf(el).find((c) => c.startsWith("_w-"));
+const heightClass = (el: HTMLElement) => classesOf(el).find((c) => c.startsWith("_h-"));
+
+const stories = { Basic, Variants, TextLines, Circles, LoadingRow, MotionOff, RadiusKnob } as const;
+
+describe("Forms/Skeleton stories", () => {
+  it("files under a Forms title so the gallery buckets it with the fields it fills in for", () => {
+    expect(meta.title).toBe("Forms/Skeleton");
+  });
+
+  it.each(Object.entries(stories))("%s mounts at least one bone", (_name, story) => {
+    expect(bones(mount(story as StoryLike).container).length).toBeGreaterThan(0);
+  });
+
+  it("Basic paints one bone at the meta width", () => {
+    const painted = bones(mount(Basic as StoryLike).container);
+    expect(painted.length).toBe(1);
+    expect(widthClass(painted[0])).toBe("_w-240px");
+  });
+
+  it("Variants shows all four, and the circular one is 1:1", () => {
+    const { container, getByText } = mount(Variants as StoryLike);
+    for (const name of ["text", "rounded", "rectangular", "circular"]) {
+      expect(getByText(name)).toBeTruthy();
+    }
+    const square = bones(container).find(
+      (el) => widthClass(el) === "_w-48px" && heightClass(el) === "_h-48px",
+    );
+    expect(square).toBeTruthy();
+  });
+
+  it("TextLines shortens the last line so a block reads as prose", () => {
+    const { container, getByText } = mount(TextLines as StoryLike);
+    expect(getByText("three lines, last at 70%")).toBeTruthy();
+    const widths = bones(container).map(widthClass);
+    // 70% and 40% are the two lastLineWidth values; 100% is every other line.
+    expect(widths).toContain("_w-7037");
+    expect(widths).toContain("_w-4037");
+    expect(widths).toContain("_w-10037");
+  });
+
+  it("Circles renders three, two of them at explicit sizes", () => {
+    const painted = bones(mount(Circles as StoryLike).container);
+    expect(painted.length).toBe(3);
+    const widths = painted.map(widthClass);
+    expect(widths).toContain("_w-32px");
+    expect(widths).toContain("_w-64px");
+  });
+
+  it("LoadingRow composes an avatar plus a name and two body lines", () => {
+    const painted = bones(mount(LoadingRow as StoryLike).container);
+    // 1 circle + 1 name bone + 2 body bones.
+    expect(painted.length).toBe(4);
+    expect(painted.map(widthClass)).toContain("_w-40px");
+  });
+
+  /** LC-20 / LC-68: the pulse is on with the knob and gone without it. */
+  it("MotionOff pulses the animated column and not the animate={false} one", () => {
+    const { container, getByText } = mount(MotionOff as StoryLike);
+    expect(getByText("animation knob on")).toBeTruthy();
+    expect(getByText("animation: none")).toBeTruthy();
+    const animations = bones(container).map((el) => el.style.animation);
+    expect(animations.some((a) => a.includes("skeleton-pulse"))).toBe(true);
+    expect(animations.some((a) => !a)).toBe(true);
+  });
+
+  it("RadiusKnob renders one column per radius stop", () => {
+    const { getByText } = mount(RadiusKnob as StoryLike);
+    for (const stop of ["none", "medium", "large"]) {
+      expect(getByText(`borderRadius: ${stop}`)).toBeTruthy();
+    }
+  });
+});

package/src/Wheel/Wheel.stories.tsx

@@ -0,0 +1,232 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Preset } from "@multiplatform.one/theme";
+import { useState } from "react";
+import { Paragraph, XStack, YStack } from "tamagui";
+import { Wheel } from "./index";
+
+const numbers = Array.from({ length: 24 }, (_, i) => i);
+const pad2 = (n: number) => String(n).padStart(2, "0");
+const hours = numbers.map((h) => ({ value: h, label: pad2(h) }));
+const minutes = Array.from({ length: 60 }, (_, m) => ({ value: m, label: pad2(m) }));
+const periods = [
+  { value: "AM", label: "AM" },
+  { value: "PM", label: "PM" },
+];
+const currencyNames = { usd: "US Dollar", eur: "Euro", inr: "Rupee", jpy: "Yen" } as const;
+
+const meta: Meta<typeof Wheel> = {
+  title: "Forms/Wheel",
+  component: Wheel,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "iOS UIPickerView / Flutter CupertinoPicker cylinder. Drag, flick or arrow-key to bring an item through the centre band. TimePicker and DatePicker paint columns of these; `highlightEdges` joins adjacent columns into one selection band.",
+      },
+    },
+  },
+  argTypes: {
+    visibleItems: { control: "select", options: [3, 5, 7] },
+    loop: { control: "boolean" },
+    disabled: { control: "boolean" },
+    width: { control: "number" },
+    itemHeight: { control: "number" },
+    highlightEdges: { control: "select", options: ["all", "start", "end", "none"] },
+    size: { control: "select", options: ["$6", "$8", "$9"] },
+  },
+  args: {
+    items: hours,
+    value: 9,
+    visibleItems: 5,
+    loop: false,
+    disabled: false,
+    highlightEdges: "all",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Wheel>;
+
+export const Basic: Story = {
+  render: (args) => {
+    const Example = () => {
+      const [value, setValue] = useState<number>((args.value as number) ?? 9);
+      return (
+        <YStack gap="$3" alignItems="flex-start">
+          <Wheel
+            {...args}
+            value={value}
+            onChange={(next) => {
+              setValue(next as number);
+              action("onChange")(next);
+            }}
+            aria-label="Hour"
+          />
+          <Paragraph size="$3">selected: {pad2(value)}</Paragraph>
+        </YStack>
+      );
+    };
+    return <Example />;
+  },
+};
+
+/** Plain values (no `{ value, label }` wrapper) render their own `String(item)`. */
+export const PlainValues: Story = {
+  render: () => (
+    <Wheel
+      items={["Small", "Medium", "Large", "Extra large"]}
+      value="Medium"
+      width={140}
+      onChange={action("onChange")}
+      aria-label="Size"
+    />
+  ),
+};
+
+/**
+ * `visibleItems` is the cylinder depth. 3 is a compact inline row, 7 the full
+ * iOS sheet; the value must stay odd so an item sits dead centre.
+ */
+export const VisibleItems: Story = {
+  render: () => (
+    <XStack gap="$6" alignItems="flex-start">
+      {([3, 5, 7] as const).map((count) => (
+        <YStack key={count} gap="$2" alignItems="center">
+          <Paragraph size="$2">visibleItems={count}</Paragraph>
+          <Wheel items={hours} value={9} visibleItems={count} aria-label={`Hour ${count}`} />
+        </YStack>
+      ))}
+    </XStack>
+  ),
+};
+
+/**
+ * `loop` wraps at the ends instead of rubber-banding. Hours and minutes loop;
+ * a bounded set like AM/PM must not, or the user can scroll past the last row
+ * into a value that was never offered.
+ */
+export const LoopingAndBounded: Story = {
+  render: () => (
+    <XStack gap="$6" alignItems="flex-start">
+      <YStack gap="$2" alignItems="center">
+        <Paragraph size="$2">loop</Paragraph>
+        <Wheel items={minutes} value={30} loop onChange={action("onChange")} aria-label="Minute" />
+      </YStack>
+      <YStack gap="$2" alignItems="center">
+        <Paragraph size="$2">bounded</Paragraph>
+        <Wheel
+          items={periods}
+          value="AM"
+          loop={false}
+          width={72}
+          onChange={action("onChange")}
+          aria-label="AM/PM"
+        />
+      </YStack>
+    </XStack>
+  ),
+};
+
+/**
+ * Multi-column joining: the row of columns reads as ONE selection band because
+ * the first declares `start`, the last `end`, and everything between `none`.
+ * This is the arrangement TimePicker ships.
+ */
+export const JoinedColumns: Story = {
+  render: () => (
+    <XStack width={320}>
+      <Wheel items={hours} value={9} loop flex={1} highlightEdges="start" aria-label="Hour" />
+      <Wheel items={minutes} value={30} loop flex={1} highlightEdges="none" aria-label="Minute" />
+      <Wheel items={periods} value="AM" flex={1} highlightEdges="end" aria-label="AM/PM" />
+    </XStack>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <XStack gap="$6" alignItems="flex-start">
+      <YStack gap="$2" alignItems="center">
+        <Paragraph size="$2">enabled</Paragraph>
+        <Wheel items={hours} value={9} aria-label="Hour enabled" />
+      </YStack>
+      <YStack gap="$2" alignItems="center">
+        <Paragraph size="$2">disabled</Paragraph>
+        <Wheel items={hours} value={9} disabled aria-label="Hour disabled" />
+      </YStack>
+    </XStack>
+  ),
+};
+
+/**
+ * `renderItem` owns the row; the wheel keeps geometry and selection. It is
+ * handed the VALUE, not the `{ value, label }` wrapper — so a story that wants
+ * a display string looks it up itself.
+ */
+export const CustomRenderItem: Story = {
+  render: () => (
+    <Wheel
+      items={Object.keys(currencyNames)}
+      value="inr"
+      width={200}
+      onChange={action("onChange")}
+      aria-label="Currency"
+      renderItem={(item, _index, isSelected) => (
+        <Paragraph size="$5" fontWeight={isSelected ? "700" : "400"}>
+          {currencyNames[item as keyof typeof currencyNames]}
+        </Paragraph>
+      )}
+    />
+  ),
+};
+
+/** Edge cases the geometry has to survive: empty, single item, very long labels. */
+export const EdgeCases: Story = {
+  render: () => (
+    <XStack gap="$6" alignItems="flex-start" flexWrap="wrap">
+      <YStack gap="$2" alignItems="center">
+        <Paragraph size="$2">empty</Paragraph>
+        <Wheel items={[]} aria-label="Empty" />
+      </YStack>
+      <YStack gap="$2" alignItems="center">
+        <Paragraph size="$2">single item</Paragraph>
+        <Wheel items={[{ value: "only", label: "Only" }]} value="only" aria-label="Single" />
+      </YStack>
+      <YStack gap="$2" alignItems="center">
+        <Paragraph size="$2">long labels</Paragraph>
+        <Wheel
+          items={[
+            { value: "a", label: "Asia/Kolkata" },
+            { value: "b", label: "America/Argentina/Buenos_Aires" },
+            { value: "c", label: "Europe/Isle_of_Man" },
+          ]}
+          value="b"
+          width={200}
+          aria-label="Timezone"
+        />
+      </YStack>
+    </XStack>
+  ),
+};
+
+/**
+ * MOTION-RIDES-KNOB (LC-68): at `animation: "none"` a keyboard snap must JUMP,
+ * not tween. Arrow-key both wheels and watch the difference.
+ */
+export const MotionOff: Story = {
+  render: () => (
+    <XStack gap="$6" alignItems="flex-start">
+      <YStack gap="$2" alignItems="center">
+        <Paragraph size="$2">animation: medium</Paragraph>
+        <Wheel items={hours} value={9} loop aria-label="Hour animated" />
+      </YStack>
+      <Preset overrides={{ animation: "none" }}>
+        <YStack gap="$2" alignItems="center">
+          <Paragraph size="$2">animation: none</Paragraph>
+          <Wheel items={hours} value={9} loop aria-label="Hour static" />
+        </YStack>
+      </Preset>
+    </XStack>
+  ),
+};