@multiplatform.one/forms 6.1.0 → 6.4.0

package/src/fields/SearchInput/index.tsx

@@ -0,0 +1,192 @@
+/**
+ * SearchInput — the ONE search box (census item 6).
+ *
+ * Same control anatomy the table toolbar, DataTableSearch, and
+ * FrappeListView each hand-rolled: Input + leading magnifier + clear
+ * button inside a single input box, with a debounced onSearch. Those
+ * sites should consume this instead of re-composing it.
+ */
+import { MagnifyingGlassIcon, XIcon } from "@phosphor-icons/react";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import type { ReactNode } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { SizeTokens } from "tamagui";
+import { View } from "tamagui";
+import { t } from "../../shared/t";
+import { Input } from "../Input";
+import type { InputProps } from "../Input";
+
+export interface SearchInputProps {
+  /** Controlled value. Omit for uncontrolled use with defaultValue. */
+  value?: string;
+  defaultValue?: string;
+  /** Fires on every keystroke (and on clear) with the raw text. */
+  onChange?: (text: string) => void;
+  /** Fires after debounceMs of typing silence; immediately on clear/Enter. */
+  onSearch?: (text: string) => void;
+  /** Fires when the clear affordance or Escape empties the box. */
+  onClear?: () => void;
+  /** Debounce for onSearch in ms. 0 fires synchronously. */
+  debounceMs?: number;
+  placeholder?: string;
+  /** Show the clear (X) button when there is text. Escape always clears. */
+  clearable?: boolean;
+  disabled?: boolean;
+  size?: SizeTokens;
+  /** Compact sizing (toolbar embedding). */
+  compact?: boolean;
+  /** Borderless/background-less (flush toolbar bands). */
+  chromeless?: boolean;
+  label?: ReactNode;
+  "aria-label"?: string;
+  /** Leading icon size in px. Defaults from the size token. */
+  iconSize?: number;
+  inputProps?: InputProps["inputProps"];
+}
+
+const iconSizeForToken: Record<string, number> = {
+  $1: 12,
+  $2: 14,
+  $3: 16,
+  $4: 16,
+  $5: 18,
+  $6: 20,
+};
+
+export function SearchInput({
+  value,
+  defaultValue,
+  onChange,
+  onSearch,
+  onClear,
+  debounceMs = 300,
+  placeholder = t("Search..."),
+  clearable = true,
+  disabled,
+  size,
+  compact,
+  chromeless,
+  label,
+  "aria-label": ariaLabel,
+  iconSize,
+  inputProps,
+}: SearchInputProps) {
+  const { knobProps } = useResolvedKnobs({ size, compact });
+  const isControlled = value !== undefined;
+  const [internalText, setInternalText] = useState(defaultValue ?? "");
+  const text = isControlled ? value : internalText;
+
+  const timerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const onSearchRef = useRef(onSearch);
+  onSearchRef.current = onSearch;
+
+  useEffect(
+    () => () => {
+      if (timerRef.current !== undefined) clearTimeout(timerRef.current);
+    },
+    [],
+  );
+
+  const fireSearch = useCallback((next: string) => {
+    if (timerRef.current !== undefined) clearTimeout(timerRef.current);
+    timerRef.current = undefined;
+    onSearchRef.current?.(next);
+  }, []);
+
+  const scheduleSearch = useCallback(
+    (next: string) => {
+      if (debounceMs <= 0) {
+        fireSearch(next);
+        return;
+      }
+      if (timerRef.current !== undefined) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => fireSearch(next), debounceMs);
+    },
+    [debounceMs, fireSearch],
+  );
+
+  const handleChangeText = useCallback(
+    (next: string) => {
+      if (!isControlled) setInternalText(next);
+      onChange?.(next);
+      scheduleSearch(next);
+    },
+    [isControlled, onChange, scheduleSearch],
+  );
+
+  const onClearRef = useRef(onClear);
+  onClearRef.current = onClear;
+
+  const handleClear = useCallback(() => {
+    if (!isControlled) setInternalText("");
+    onChange?.("");
+    fireSearch("");
+    onClearRef.current?.();
+  }, [isControlled, onChange, fireSearch]);
+
+  const resolvedIconSize = iconSize ?? iconSizeForToken[size ?? knobProps.sizeToken] ?? 16;
+
+  const clearButton =
+    clearable && !disabled && text ? (
+      <View
+        role="button"
+        tabIndex={0}
+        padding="$1"
+        borderRadius={knobProps.borderRadius.borderRadius}
+        cursor="pointer"
+        hoverStyle={{ backgroundColor: "$color4" }}
+        pressStyle={{ backgroundColor: "$color5" }}
+        focusVisibleStyle={{ outlineWidth: 2, outlineStyle: "solid", outlineColor: "$color8" }}
+        onPress={handleClear}
+        onKeyDown={
+          ((e: KeyboardEvent) => {
+            if (e.key === "Enter" || e.key === " ") {
+              e.preventDefault();
+              e.stopPropagation();
+              handleClear();
+            }
+          }) as unknown as () => void
+        }
+        aria-label={t("Clear search")}
+      >
+        <XIcon size={resolvedIconSize - 2} />
+      </View>
+    ) : undefined;
+
+  // `value` is Omit-ed from InputProps["inputProps"] (Input's Area is
+  // uncontrolled via defaultValue), but nothing Input sets after the
+  // spread overrides `value`, so passing it here makes the Area
+  // controlled — required for clear/Escape to visually empty the box.
+  const areaProps = {
+    role: "searchbox",
+    "aria-label": ariaLabel ?? "Search",
+    enterKeyHint: "search",
+    value: text,
+    onKeyDown: (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        handleClear();
+      } else if (e.key === "Enter") {
+        fireSearch(text);
+      }
+    },
+    onSubmitEditing: () => fireSearch(text),
+    ...inputProps,
+  } as unknown as InputProps["inputProps"];
+
+  return (
+    <Input
+      label={label}
+      size={size}
+      compact={compact}
+      chromeless={chromeless}
+      disabled={disabled}
+      onChangeText={handleChangeText}
+      placeholder={placeholder}
+      leftIcon={<MagnifyingGlassIcon size={resolvedIconSize} />}
+      rightIcon={clearButton}
+      rightIconInteractive
+      inputProps={areaProps}
+    />
+  );
+}

package/src/fields/Select/Select.spec.tsx

@@ -5,6 +5,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { Button } from "../../Button";
 import { Form } from "../../Form";
+import { __resetDevWarnSeen } from "../../shared/devWarn";
 import { Select, type SelectOption } from "./index";
 
 const mockOptions: SelectOption[] = [
@@ -102,6 +103,32 @@ describe("Select Components", () => {
         expect(label?.textContent).toContain("Required Select");
         expect(label?.textContent).toContain("*");
       });
+
+      it("fires canonical onChange and the deprecated onValueChange alias once when dismissing a chip", async () => {
+        const onChange = vi.fn();
+        const onValueChange = vi.fn();
+        const result = renderWithProviders(
+          <Select
+            label="Multi Select"
+            name="multi"
+            options={mockOptions}
+            multiple
+            dismissible
+            value={["option1", "option2"]}
+            onChange={onChange}
+            onValueChange={onValueChange}
+          />,
+        );
+        const dismiss = result.container.querySelector('[aria-label="Remove"]');
+        expect(dismiss).toBeTruthy();
+        await act(async () => {
+          if (dismiss) fireEvent.click(dismiss);
+        });
+        expect(onChange).toHaveBeenCalledTimes(1);
+        expect(onChange).toHaveBeenCalledWith(["option2"]);
+        expect(onValueChange).toHaveBeenCalledTimes(1);
+        expect(onValueChange).toHaveBeenCalledWith(["option2"]);
+      });
     });
 
     describe("with form context", () => {
@@ -224,4 +251,32 @@ describe("Select Components", () => {
       expect(result.findTextElement("Option 1")).toBeDefined();
     });
   });
+
+  describe("DEV select-too-few-options", () => {
+    let warnSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+      __resetDevWarnSeen();
+      warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+      warnSpy.mockRestore();
+      __resetDevWarnSeen();
+    });
+
+    it("warns when single-select has ≤5 options", () => {
+      renderWithProviders(<Select options={mockOptions} id="short" />);
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("select-too-few-options"));
+    });
+
+    it("does not warn when options.length > 5", () => {
+      const many: SelectOption[] = Array.from({ length: 6 }, (_, i) => ({
+        value: `v${i}`,
+        label: `Label ${i}`,
+      }));
+      renderWithProviders(<Select options={many} id="long" />);
+      expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("select-too-few-options"));
+    });
+  });
 });

package/src/fields/Select/Select.stories.tsx

@@ -3,6 +3,7 @@ import { action } from "@multiplatform.one/storybook";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { useForm } from "@tanstack/react-form";
 import { CaretDownIcon, CaretUpIcon } from "@phosphor-icons/react";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
 import { Adapt, Paragraph, Select as TamaguiSelect, Sheet, XStack, YStack } from "tamagui";
 import { Button } from "../../Button";
 import { Form } from "../../Form";
@@ -28,17 +29,23 @@ const meta: Meta<typeof Select> = {
     size: { control: "select", options: ["$2", "$3", "$4"] },
     value: { control: "text" },
     options: { control: "object" },
+    multiple: { control: "boolean" },
+    dismissible: { control: "boolean" },
   },
 };
 
 export default meta;
 type Story = StoryObj<typeof Select>;
 
+// DG-CTRL-01: Select fixtures carry >5 options — shorter lists belong in a
+// RadioGroup/ToggleGroup and trip the `select-too-few-options` guardrail.
 const sampleOptions: SelectOption[] = [
   { value: "option1", label: "Option 1" },
   { value: "option2", label: "Option 2" },
   { value: "option3", label: "Option 3" },
   { value: "option4", label: "Option 4" },
+  { value: "option5", label: "Option 5" },
+  { value: "option6", label: "Option 6" },
 ];
 
 const roleOptions: SelectOption[] = [
@@ -46,6 +53,8 @@ const roleOptions: SelectOption[] = [
   { value: "user", label: "User" },
   { value: "guest", label: "Guest" },
   { value: "moderator", label: "Moderator" },
+  { value: "editor", label: "Editor" },
+  { value: "viewer", label: "Viewer" },
 ];
 
 const countryOptions: SelectOption[] = [
@@ -94,6 +103,8 @@ export const Main: StoryObj<typeof Select> = {
               label="Priority"
               name="priority"
               options={[
+                { value: "none", label: "No Priority" },
+                { value: "trivial", label: "Trivial" },
                 { value: "low", label: "Low Priority" },
                 { value: "medium", label: "Medium Priority" },
                 { value: "high", label: "High Priority" },
@@ -145,6 +156,17 @@ export const Basic: Story = {
   },
 };
 
+export const Multiple: Story = {
+  args: {
+    label: "Options",
+    multiple: true,
+    dismissible: true,
+    options: sampleOptions,
+    placeholder: "Select options",
+  },
+  render: (args) => <Select {...args} />,
+};
+
 export const Disabled: Story = {
   args: {
     label: "Disabled Field",
@@ -181,7 +203,9 @@ export const Sizes: Story = {
 export const DynamicOptions: StoryObj<typeof Select> = {
   render: () => {
     const DynamicExample = () => {
-      const [category, setCategory] = useState("");
+      // Rest on a picked category so the dependent select is populated at
+      // rest (an empty/2-option Select trips `select-too-few-options`).
+      const [category, setCategory] = useState("fruits");
 
       const getOptions = (category: string): SelectOption[] => {
         switch (category) {
@@ -190,12 +214,54 @@ export const DynamicOptions: StoryObj<typeof Select> = {
               { value: "apple", label: "Apple" },
               { value: "banana", label: "Banana" },
               { value: "orange", label: "Orange" },
+              { value: "mango", label: "Mango" },
+              { value: "grape", label: "Grape" },
+              { value: "pear", label: "Pear" },
             ];
           case "vegetables":
             return [
               { value: "carrot", label: "Carrot" },
               { value: "broccoli", label: "Broccoli" },
               { value: "spinach", label: "Spinach" },
+              { value: "potato", label: "Potato" },
+              { value: "onion", label: "Onion" },
+              { value: "pepper", label: "Pepper" },
+            ];
+          case "grains":
+            return [
+              { value: "rice", label: "Rice" },
+              { value: "wheat", label: "Wheat" },
+              { value: "oats", label: "Oats" },
+              { value: "barley", label: "Barley" },
+              { value: "quinoa", label: "Quinoa" },
+              { value: "millet", label: "Millet" },
+            ];
+          case "dairy":
+            return [
+              { value: "milk", label: "Milk" },
+              { value: "yogurt", label: "Yogurt" },
+              { value: "cheese", label: "Cheese" },
+              { value: "butter", label: "Butter" },
+              { value: "cream", label: "Cream" },
+              { value: "kefir", label: "Kefir" },
+            ];
+          case "proteins":
+            return [
+              { value: "chicken", label: "Chicken" },
+              { value: "fish", label: "Fish" },
+              { value: "beef", label: "Beef" },
+              { value: "tofu", label: "Tofu" },
+              { value: "lentils", label: "Lentils" },
+              { value: "eggs", label: "Eggs" },
+            ];
+          case "beverages":
+            return [
+              { value: "water", label: "Water" },
+              { value: "coffee", label: "Coffee" },
+              { value: "tea", label: "Tea" },
+              { value: "juice", label: "Juice" },
+              { value: "smoothie", label: "Smoothie" },
+              { value: "kombucha", label: "Kombucha" },
             ];
           default:
             return [];
@@ -205,6 +271,10 @@ export const DynamicOptions: StoryObj<typeof Select> = {
       const categoryOptions = [
         { value: "fruits", label: "Fruits" },
         { value: "vegetables", label: "Vegetables" },
+        { value: "grains", label: "Grains" },
+        { value: "dairy", label: "Dairy" },
+        { value: "proteins", label: "Proteins" },
+        { value: "beverages", label: "Beverages" },
       ];
 
       return (
@@ -213,6 +283,7 @@ export const DynamicOptions: StoryObj<typeof Select> = {
             label="Category"
             name="category"
             options={categoryOptions}
+            value={category}
             placeholder="Select a category"
             onValueChange={(val) => setCategory(Array.isArray(val) ? (val[0] ?? "") : val)}
           />
@@ -237,6 +308,7 @@ export const Comparison: StoryObj<typeof Select> = {
     const ComparisonExample = () => {
       const [customValue, setCustomValue] = useState<string>();
       const [tamaguiValue, setTamaguiValue] = useState<string>();
+      const { knobProps } = useResolvedKnobs();
       return (
         <XStack gap="$4" alignItems="flex-start" padding="$4">
           <YStack gap="$2" width={320}>
@@ -271,14 +343,16 @@ export const Comparison: StoryObj<typeof Select> = {
               </TamaguiSelect.Trigger>
               {/* biome-ignore lint/suspicious/noExplicitAny: Tamagui Adapt breakpoint type */}
               <Adapt when={"sm" as any} platform="touch">
-                <Sheet modal dismissOnSnapToBottom>
+                {/* LC-24: root transition drives the position slide; without it
+                    the sheet teleports open/closed. */}
+                <Sheet modal dismissOnSnapToBottom transition={knobProps.transition}>
                   <Sheet.Frame>
                     <Sheet.ScrollView>
                       <Adapt.Contents />
                     </Sheet.ScrollView>
                   </Sheet.Frame>
                   <Sheet.Overlay
-                    transition="lazy"
+                    transition={knobProps.transition}
                     enterStyle={{ opacity: 0 }}
                     exitStyle={{ opacity: 0 }}
                   />
@@ -326,3 +400,8 @@ export const Comparison: StoryObj<typeof Select> = {
     return <ComparisonExample />;
   },
 };
+
+/** Loading placeholder — the skeleton mirrors the trigger anatomy (LC-20 / DG-ST-02). */
+export const SkeletonState: Story = {
+  args: { label: "Country", options: countryOptions, skeleton: true },
+};