@multiplatform.one/forms 6.1.0 → 6.4.0

package/src/fields/Rating/Rating.stories.tsx

@@ -78,12 +78,39 @@ export const Standalone: Story = {
   args: {
     label: "Rating",
     helperText: "Rate your experience",
-    value: 3,
+    // Rating `value` is a 0..1 fraction of maxStars (0.6 * 5 = 3 stars).
+    // `3` rendered all five stars filled (round(3*5)=15 >= 5).
+    value: 0.6,
     maxStars: 5,
   },
   render: (args) => <Rating {...args} starIcon={StarIcon} />,
 };
 
+/**
+ * Bare contract (UX-009 / Axiom 13 ONE BODY): no `starIcon` — the package
+ * default star renders and stars stay keyboard-operable (roving tab stop,
+ * Enter/Space, arrows).
+ */
+export const Bare: Story = {
+  render: () => {
+    const BareExample = () => {
+      const [value, setValue] = useState(0.6);
+      return (
+        <Rating
+          label="Rating"
+          helperText="No starIcon prop — package default star"
+          value={value}
+          onChange={(v) => {
+            setValue(v);
+            action("onChange")(v);
+          }}
+        />
+      );
+    };
+    return <BareExample />;
+  },
+};
+
 export const Basic: Story = {
   args: {
     label: "Rating",
@@ -200,3 +227,8 @@ export const Interactive: Story = {
     return <InteractiveExample />;
   },
 };
+
+/** Loading placeholder — the skeleton mirrors the star row anatomy (LC-20 / DG-ST-02). */
+export const SkeletonState: Story = {
+  render: () => <Rating label="Rating" skeleton starIcon={StarIcon} />,
+};

package/src/fields/Rating/index.tsx

@@ -1,10 +1,21 @@
 import type { KnobProps } from "@multiplatform.one/theme";
-import type { ComponentType, ReactNode } from "react";
-import { useMemo } from "react";
-import type { LabelProps, SizeTokens } from "tamagui";
-import type { TransitionProp } from "tamagui";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { StarIcon as DefaultStarIcon } from "@phosphor-icons/react";
+import type { ComponentType, KeyboardEvent, ReactNode } from "react";
+import { useMemo, useRef, useState } from "react";
+import type { LabelProps, SizeTokens, TransitionProp } from "tamagui";
 import { getVariable, isWeb, styled, useTheme, View, XStack } from "tamagui";
 import Svg, { Path } from "react-native-svg";
+import { Skeleton } from "../../Skeleton";
+import { Field, FieldLayout } from "../../fieldLayout";
+import { t } from "../../shared/t";
+import {
+  getFieldError,
+  mergeFieldHandler,
+  useFormField,
+  useResolvedValidators,
+} from "../../shared/utils";
+import type { AnyFormApi } from "../../types";
 
 function starPath(size: number, innerRatio = 0.382): string {
   const cx = size / 2;
@@ -59,19 +70,16 @@ const cssTimings: Record<string, string> = {
   gentle: "ease-in-out 450ms",
 };
 
-function getTransitionStyle(transition: TransitionProp | undefined) {
-  if (!isWeb) return undefined;
-  const timing = transition
-    ? (cssTimings[transition as string] ?? cssTimings.quick)
-    : cssTimings.quick;
-  return { transition: `transform ${timing}` };
+/** LC-25: discrete fill jumps tween; omit when animation knob is none or scrubbing. */
+function getTransitionStyle(transition: TransitionProp | undefined, live: boolean) {
+  if (!isWeb || live || !transition) return undefined;
+  const timing = cssTimings[transition as string] ?? cssTimings.quick;
+  return {
+    transition: [`transform ${timing}`, `opacity ${timing}`, `color ${timing}`].join(", "),
+  };
 }
-import { Skeleton } from "../../Skeleton";
-import { Field, FieldLayout } from "../../fieldLayout";
 
 const StarWrapper = styled(View, {
-  // Native uses Tamagui's animation prop (reanimated driver)
-  ...(!isWeb && { animation: "quick" }),
   variants: {
     filled: {
       true: {
@@ -85,13 +93,6 @@ const StarWrapper = styled(View, {
     },
   } as const,
 });
-import {
-  getFieldError,
-  mergeFieldHandler,
-  useFormField,
-  useResolvedValidators,
-} from "../../shared/utils";
-import type { AnyFormApi } from "../../types";
 
 function StarRow({
   filledStars,
@@ -118,6 +119,53 @@ function StarRow({
   required?: boolean;
   hasError?: boolean;
 }) {
+  const { disabledState, control } = useResolvedKnobs();
+  const [scrubFilled, setScrubFilled] = useState<number | null>(null);
+  const scrubbing = scrubFilled != null;
+  const displayFilled = scrubFilled ?? filledStars;
+  // LC-25: discrete star jumps tween via knob transition (default "quick").
+  // During pointer scrub, omit transition so fill tracks the pointer 1:1.
+  const motionTransition = (knobProps.transition as TransitionProp | undefined) || "quick";
+  const live = scrubbing;
+
+  // DG-A11Y keyboard operability: one roving tab stop (ToggleGroup pattern —
+  // a group of N buttons is one Tab entry, arrows move within). The stop
+  // follows the committed value star, or the focused star while inside.
+  const starRefs = useRef<Array<HTMLElement | null>>([]);
+  const [focusedStar, setFocusedStar] = useState<number | null>(null);
+  const tabStopStar = focusedStar ?? Math.min(Math.max(filledStars, 1), maxStars);
+  const focusStar = (starNumber: number) => {
+    starRefs.current[starNumber - 1]?.focus?.();
+  };
+  const handleStarKeyDown = (event: KeyboardEvent, starNumber: number) => {
+    const key = event.key;
+    if (key === "Enter" || key === " " || event.code === "Space") {
+      event.preventDefault();
+      event.stopPropagation();
+      if (!readOnly) onStarPress(starNumber);
+    } else if (key === "ArrowRight" || key === "ArrowUp") {
+      event.preventDefault();
+      focusStar(Math.min(starNumber + 1, maxStars));
+    } else if (key === "ArrowLeft" || key === "ArrowDown") {
+      event.preventDefault();
+      focusStar(Math.max(starNumber - 1, 1));
+    } else if (key === "Home") {
+      event.preventDefault();
+      focusStar(1);
+    } else if (key === "End") {
+      event.preventDefault();
+      focusStar(maxStars);
+    }
+  };
+
+  const starFromPointer = (clientX: number, row: HTMLElement | null) => {
+    if (!row) return null;
+    const rect = row.getBoundingClientRect();
+    if (rect.width <= 0) return null;
+    const ratio = Math.min(1, Math.max(0, (clientX - rect.left) / rect.width));
+    return Math.max(1, Math.ceil(ratio * maxStars));
+  };
+
   return (
     <XStack
       {...knobProps.gap}
@@ -125,18 +173,60 @@ function StarRow({
       aria-required={required || undefined}
       aria-invalid={hasError || undefined}
       aria-readonly={readOnly || undefined}
+      data-rating-row
+      data-rating-live={live ? "true" : undefined}
+      {...(isWeb && !disabled && !readOnly
+        ? {
+            onPointerMove: ((e: any) => {
+              const row = e.currentTarget as HTMLElement;
+              const next = starFromPointer(e.clientX, row);
+              if (next == null) return;
+              setScrubFilled(next);
+            }) as any,
+            onPointerLeave: (() => {
+              setScrubFilled(null);
+            }) as any,
+          }
+        : {})}
     >
       {Array.from({ length: maxStars }, (_, i) => {
         const starNumber = i + 1;
-        const isFilled = starNumber <= filledStars;
+        const isFilled = starNumber <= displayFilled;
         return (
           <StarWrapper
             key={starNumber}
+            ref={(node: any) => {
+              starRefs.current[i] = node;
+            }}
             onPress={() => !readOnly && onStarPress(starNumber)}
-            cursor={disabled || readOnly ? "default" : "pointer"}
-            opacity={disabled ? 0.5 : 1}
+            cursor={readOnly ? "default" : "pointer"}
+            // LC-40 DISABLED-VISIBLE: stars are text-free chrome — dim via the
+            // recipe (read-only stays full-contrast, only pointer changes).
+            {...(disabled ? disabledState.chromeKnobProps : undefined)}
             filled={isFilled}
-            style={getTransitionStyle(knobProps.transition)}
+            role="button"
+            aria-label={t("{{star}} of {{max}} stars", { star: starNumber, max: maxStars })}
+            aria-disabled={disabled || undefined}
+            aria-pressed={isFilled}
+            // Keyboard operability (DG-A11Y-01): roving tabindex + Enter/Space
+            // activation + arrow-key movement; disabled drops out of the tab
+            // order (unexplained-disable house pattern, same as native).
+            {...(isWeb && !disabled
+              ? {
+                  tabIndex: starNumber === tabStopStar ? 0 : -1,
+                  onFocus: () => setFocusedStar(starNumber),
+                  onBlur: () => setFocusedStar(null),
+                  onKeyDown: ((e: KeyboardEvent) =>
+                    handleStarKeyDown(e, starNumber)) as unknown as () => void,
+                }
+              : {})}
+            focusVisibleStyle={control.focusVisibleKnobProps}
+            // RN only exposes plain Views to the a11y tree when `accessible` is set
+            {...(!isWeb ? { accessible: true } : {})}
+            data-rating-star={isFilled ? "filled" : "empty"}
+            data-rating-index={starNumber}
+            {...(!isWeb && !live ? { transition: motionTransition } : {})}
+            style={getTransitionStyle(live ? undefined : motionTransition, live)}
           >
             <StarIcon
               size={24}
@@ -168,7 +258,13 @@ export interface RatingProps {
   disabled?: boolean;
   readOnly?: boolean;
   maxStars?: number;
-  starIcon: ComponentType<{ size: number; weight: "fill" | "regular"; color: string }>;
+  /**
+   * Star glyph renderer. Optional — bare use falls back to the package star
+   * (Phosphor `StarIcon`, the house icon set) so the contract is usable
+   * without any icon wiring (Axiom 13 ONE BODY). Pointy themes keep the
+   * built-in sharp-pointed star.
+   */
+  starIcon?: ComponentType<{ size: number; weight: "fill" | "regular"; color: string }>;
   /** Force sharp-pointed stars. Defaults to `true` when the theme knob `borderRadius` is `"none"`. */
   pointy?: boolean;
   /** When true, renders a skeleton placeholder instead of the rating */
@@ -202,7 +298,9 @@ export function Rating({
 }: RatingProps) {
   const { resolvedForm, knobProps, id } = useFormField({ form: formProp, id: idProp, compact });
   const resolvedPointy = pointy ?? knobProps.pointy;
-  const ResolvedStarIcon = resolvedPointy ? PointyStar : starIcon;
+  // Sane bare default (UX-009): an omitted starIcon renders the package star
+  // instead of an invalid element crash on rounded themes.
+  const ResolvedStarIcon = resolvedPointy ? PointyStar : (starIcon ?? DefaultStarIcon);
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
   const filledStars = useMemo(() => Math.round(value * maxStars), [value, maxStars]);
 
@@ -246,6 +344,9 @@ export function Rating({
         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}
       >
         <StarRow
           knobProps={knobProps}
@@ -286,6 +387,8 @@ export function Rating({
             size={size}
             knobProps={knobProps}
             onBlur={mergeFieldHandler(field, "handleBlur", onBlur)}
+            // LC-40: see standalone branch — FieldLayout carries dimWhole.
+            disabled={disabled}
           >
             <StarRow
               knobProps={knobProps}

package/src/fields/SearchInput/SearchInput.spec.tsx

@@ -0,0 +1,147 @@
+import { fireEvent } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { SearchInput } from "./index";
+
+describe("SearchInput", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("renders a searchbox with placeholder and leading icon", () => {
+    const result = renderWithProviders(<SearchInput placeholder="Search things" />);
+    const input = result.container.querySelector("input");
+    expect(input?.getAttribute("placeholder")).toBe("Search things");
+    expect(input?.getAttribute("role")).toBe("searchbox");
+    expect(input?.getAttribute("aria-label")).toBe("Search");
+    expect(result.container.querySelector("svg")).toBeTruthy();
+  });
+
+  it("fires onChange per keystroke and onSearch after debounce", () => {
+    const onChange = vi.fn();
+    const onSearch = vi.fn();
+    const result = renderWithProviders(
+      <SearchInput onChange={onChange} onSearch={onSearch} debounceMs={300} />,
+    );
+    const input = result.container.querySelector("input");
+    if (!input) throw new Error("input not found");
+    fireEvent.change(input, { target: { value: "abc" } });
+    expect(onChange).toHaveBeenCalledWith("abc");
+    expect(onSearch).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(299);
+    expect(onSearch).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(onSearch).toHaveBeenCalledWith("abc");
+    expect(onSearch).toHaveBeenCalledTimes(1);
+  });
+
+  it("collapses rapid keystrokes into one onSearch", () => {
+    const onSearch = vi.fn();
+    const result = renderWithProviders(<SearchInput onSearch={onSearch} debounceMs={300} />);
+    const input = result.container.querySelector("input");
+    if (!input) throw new Error("input not found");
+    fireEvent.change(input, { target: { value: "a" } });
+    vi.advanceTimersByTime(100);
+    fireEvent.change(input, { target: { value: "ab" } });
+    vi.advanceTimersByTime(100);
+    fireEvent.change(input, { target: { value: "abc" } });
+    vi.advanceTimersByTime(300);
+    expect(onSearch).toHaveBeenCalledTimes(1);
+    expect(onSearch).toHaveBeenCalledWith("abc");
+  });
+
+  it("debounceMs=0 fires onSearch synchronously", () => {
+    const onSearch = vi.fn();
+    const result = renderWithProviders(<SearchInput onSearch={onSearch} debounceMs={0} />);
+    const input = result.container.querySelector("input");
+    if (!input) throw new Error("input not found");
+    fireEvent.change(input, { target: { value: "now" } });
+    expect(onSearch).toHaveBeenCalledWith("now");
+  });
+
+  it("shows clear button only when there is text; clearing empties and fires immediately", () => {
+    const onChange = vi.fn();
+    const onSearch = vi.fn();
+    const result = renderWithProviders(<SearchInput onChange={onChange} onSearch={onSearch} />);
+    const input = result.container.querySelector("input");
+    if (!input) throw new Error("input not found");
+    expect(result.container.querySelector("[aria-label='Clear search']")).toBeNull();
+    fireEvent.change(input, { target: { value: "abc" } });
+    const clear = result.container.querySelector("[aria-label='Clear search']");
+    if (!clear) throw new Error("clear button not rendered");
+    fireEvent.click(clear);
+    expect(onChange).toHaveBeenLastCalledWith("");
+    // clear fires onSearch immediately, no debounce wait
+    expect(onSearch).toHaveBeenCalledWith("");
+    expect((input as HTMLInputElement).value).toBe("");
+    // pending "abc" debounce was cancelled
+    vi.advanceTimersByTime(1000);
+    expect(onSearch).not.toHaveBeenCalledWith("abc");
+  });
+
+  it("onClear fires on the clear affordance and on Escape, not on typed emptiness", () => {
+    // Consumers (DataTableToolbar) hang side effects like clearFilters off
+    // explicit clear intent; backspacing to "" must not trigger it.
+    const onClear = vi.fn();
+    const result = renderWithProviders(<SearchInput onClear={onClear} />);
+    const input = result.container.querySelector("input");
+    if (!input) throw new Error("input not found");
+    fireEvent.change(input, { target: { value: "abc" } });
+    fireEvent.change(input, { target: { value: "" } });
+    vi.advanceTimersByTime(1000);
+    expect(onClear).not.toHaveBeenCalled();
+    fireEvent.change(input, { target: { value: "abc" } });
+    const clear = result.container.querySelector("[aria-label='Clear search']");
+    if (!clear) throw new Error("clear button not rendered");
+    fireEvent.click(clear);
+    expect(onClear).toHaveBeenCalledTimes(1);
+    fireEvent.change(input, { target: { value: "again" } });
+    fireEvent.keyDown(input, { key: "Escape" });
+    expect(onClear).toHaveBeenCalledTimes(2);
+  });
+
+  it("clear button is keyboard-reachable (tabIndex + Enter)", async () => {
+    const onSearch = vi.fn();
+    const result = renderWithProviders(<SearchInput defaultValue="abc" onSearch={onSearch} />);
+    const clear = result.container.querySelector("[aria-label='Clear search']");
+    if (!clear) throw new Error("clear button not rendered");
+    expect(clear.getAttribute("tabindex")).toBe("0");
+    fireEvent.keyDown(clear, { key: "Enter" });
+    expect(onSearch).toHaveBeenCalledWith("");
+  });
+
+  it("Escape clears, Enter flushes the pending search", () => {
+    const onSearch = vi.fn();
+    const result = renderWithProviders(<SearchInput onSearch={onSearch} debounceMs={300} />);
+    const input = result.container.querySelector("input");
+    if (!input) throw new Error("input not found");
+    fireEvent.change(input, { target: { value: "abc" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(onSearch).toHaveBeenCalledWith("abc");
+    fireEvent.keyDown(input, { key: "Escape" });
+    expect(onSearch).toHaveBeenLastCalledWith("");
+    expect((input as HTMLInputElement).value).toBe("");
+  });
+
+  it("controlled mode reflects the value prop", () => {
+    const result = renderWithProviders(<SearchInput value="hello" onChange={() => {}} />);
+    const input = result.container.querySelector("input");
+    expect((input as HTMLInputElement).value).toBe("hello");
+  });
+
+  it("clearable=false hides the clear button", () => {
+    const result = renderWithProviders(<SearchInput defaultValue="abc" clearable={false} />);
+    expect(result.container.querySelector("[aria-label='Clear search']")).toBeNull();
+  });
+
+  it("disabled hides the clear button and blocks input", () => {
+    const result = renderWithProviders(<SearchInput defaultValue="abc" disabled />);
+    expect(result.container.querySelector("[aria-label='Clear search']")).toBeNull();
+    const input = result.container.querySelector("input");
+    expect(input?.getAttribute("aria-disabled")).toBe("true");
+  });
+});

package/src/fields/SearchInput/SearchInput.stories.tsx

@@ -0,0 +1,127 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useState } from "react";
+import { Paragraph, YStack } from "tamagui";
+import { SearchInput } from "./index";
+
+const meta: Meta<typeof SearchInput> = {
+  title: "Forms/SearchInput",
+  component: SearchInput,
+  parameters: { status: { type: "beta" } },
+  argTypes: {
+    placeholder: { control: "text" },
+    debounceMs: { control: "number" },
+    clearable: { control: "boolean" },
+    disabled: { control: "boolean" },
+    compact: { control: "boolean" },
+    chromeless: { control: "boolean" },
+    size: { control: "select", options: ["$2", "$3", "$4", "$5"] },
+    defaultValue: { control: "text" },
+    label: { control: "text" },
+  },
+  args: {
+    placeholder: "Search...",
+    debounceMs: 300,
+    clearable: true,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof SearchInput>;
+
+export const Main: Story = {
+  render: (args) => (
+    <YStack maxWidth={400}>
+      <SearchInput
+        {...args}
+        onChange={(text) => action("onChange")(text)}
+        onSearch={(text) => action("onSearch")(text)}
+      />
+    </YStack>
+  ),
+};
+
+export const Debounced: Story = {
+  render: () => {
+    const Example = () => {
+      const [live, setLive] = useState("");
+      const [searched, setSearched] = useState("");
+      return (
+        <YStack gap="$3" maxWidth={400}>
+          <SearchInput debounceMs={500} onChange={setLive} onSearch={setSearched} />
+          <Paragraph size="$2" color="$color10">
+            typing: {live || "(empty)"}
+          </Paragraph>
+          <Paragraph size="$2" color="$color10">
+            searched (500ms debounce): {searched || "(empty)"}
+          </Paragraph>
+        </YStack>
+      );
+    };
+    return <Example />;
+  },
+};
+
+export const Controlled: Story = {
+  render: () => {
+    const Example = () => {
+      const [value, setValue] = useState("preset query");
+      return (
+        <YStack gap="$3" maxWidth={400}>
+          <SearchInput
+            value={value}
+            onChange={setValue}
+            onSearch={(text) => action("onSearch")(text)}
+          />
+          <Paragraph size="$2" color="$color10">
+            value: {value || "(empty)"}
+          </Paragraph>
+        </YStack>
+      );
+    };
+    return <Example />;
+  },
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <YStack gap="$4" maxWidth={400}>
+      <SearchInput size="$2" placeholder="Small" />
+      <SearchInput size="$3" placeholder="Medium (default)" />
+      <SearchInput size="$4" placeholder="Large" />
+    </YStack>
+  ),
+};
+
+export const ToolbarCompact: Story = {
+  name: "Toolbar (compact + chromeless)",
+  render: () => (
+    <YStack
+      maxWidth={400}
+      backgroundColor="$color3"
+      borderWidth={1}
+      borderColor="$borderColor"
+      padding="$2"
+    >
+      <SearchInput compact chromeless size="$3" onSearch={(text) => action("onSearch")(text)} />
+    </YStack>
+  ),
+};
+
+export const NotClearable: Story = {
+  args: { clearable: false, defaultValue: "locked in" },
+  render: (args) => (
+    <YStack maxWidth={400}>
+      <SearchInput {...args} />
+    </YStack>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { disabled: true, defaultValue: "cannot touch" },
+  render: (args) => (
+    <YStack maxWidth={400}>
+      <SearchInput {...args} />
+    </YStack>
+  ),
+};