@multiplatform.one/forms 6.0.0

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

@@ -0,0 +1,202 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { StarIcon } from "@phosphor-icons/react";
+import { useForm } from "@tanstack/react-form";
+import { useState } from "react";
+import { Text, YStack } from "tamagui";
+import { Button } from "../../Button";
+import { Form } from "../../Form";
+import { Rating } from "./index";
+
+const meta: Meta<typeof Rating> = {
+  title: "Forms/Rating",
+  component: Rating,
+  parameters: {
+    docs: {
+      description: {
+        component: "A star rating field component with form integration.",
+      },
+    },
+  },
+  argTypes: {
+    label: { control: "text" },
+    helperText: { control: "text" },
+    error: { control: "text" },
+    required: { control: "boolean" },
+    disabled: { control: "boolean" },
+    size: { control: "select", options: ["$2", "$3", "$4"] },
+    value: {
+      control: { type: "number", min: 0, max: 5 },
+      description: "Rating value (0-1 fraction)",
+    },
+    maxStars: { control: "number", description: "Number of stars" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Rating>;
+
+export const Main: Story = {
+  name: "Main",
+  render: () => {
+    const FormExample = () => {
+      const form = useForm({
+        defaultValues: {
+          quality: 0.6,
+          service: 0.8,
+        },
+        onSubmit: async ({ value }) => {
+          action("onSubmit")(value);
+        },
+      });
+
+      return (
+        <Form form={form} maxWidth={400}>
+          <YStack gap="$4">
+            <Rating
+              label="Quality"
+              name="quality"
+              helperText="Rate the product quality"
+              starIcon={StarIcon}
+            />
+            <Rating
+              label="Service"
+              name="service"
+              helperText="Rate the customer service"
+              starIcon={StarIcon}
+            />
+            <Button action="submit">Submit Review</Button>
+          </YStack>
+        </Form>
+      );
+    };
+    return <FormExample />;
+  },
+};
+
+export const Standalone: Story = {
+  args: {
+    label: "Rating",
+    helperText: "Rate your experience",
+    value: 3,
+    maxStars: 5,
+  },
+  render: (args) => <Rating {...args} starIcon={StarIcon} />,
+};
+
+export const Basic: Story = {
+  args: {
+    label: "Rating",
+    helperText: "Rate your experience",
+    value: 0.6,
+    starIcon: StarIcon,
+    onChange: action("onChange"),
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    label: "Rating",
+    helperText: "This rating is disabled",
+    value: 0.6,
+    disabled: true,
+    starIcon: StarIcon,
+    onChange: action("onChange"),
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    label: "Rating",
+    helperText: "Rate your experience",
+    value: 0,
+    required: true,
+    error: "A rating is required",
+    starIcon: StarIcon,
+    onChange: action("onChange"),
+  },
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <YStack gap="$4" maxWidth={300}>
+      <Text fontWeight="bold">Size $2</Text>
+      <Rating
+        label="Small"
+        value={0.6}
+        size="$2"
+        starIcon={StarIcon}
+        onChange={action("onChange")}
+      />
+      <Text fontWeight="bold">Size $3</Text>
+      <Rating
+        label="Medium"
+        value={0.6}
+        size="$3"
+        starIcon={StarIcon}
+        onChange={action("onChange")}
+      />
+      <Text fontWeight="bold">Size $4</Text>
+      <Rating
+        label="Large"
+        value={0.6}
+        size="$4"
+        starIcon={StarIcon}
+        onChange={action("onChange")}
+      />
+    </YStack>
+  ),
+};
+
+export const Pointy: Story = {
+  render: () => {
+    const PointyExample = () => {
+      const [value, setValue] = useState(0.6);
+      return (
+        <YStack gap="$4" maxWidth={300}>
+          <Rating
+            label="Pointy (explicit prop)"
+            helperText="Sharp-pointed stars via the pointy prop"
+            value={value}
+            onChange={setValue}
+            starIcon={StarIcon}
+            pointy
+          />
+          <Rating
+            label="Regular"
+            helperText="Default star icon"
+            value={value}
+            onChange={setValue}
+            starIcon={StarIcon}
+            pointy={false}
+          />
+        </YStack>
+      );
+    };
+    return <PointyExample />;
+  },
+};
+
+export const Interactive: Story = {
+  render: () => {
+    const InteractiveExample = () => {
+      const [value, setValue] = useState(0.4);
+      return (
+        <YStack gap="$4" maxWidth={300}>
+          <Rating
+            label="How would you rate this?"
+            helperText={`${Math.round(value * 5)} out of 5 stars`}
+            value={value}
+            onChange={(v) => {
+              setValue(v);
+              action("onChange")(v);
+            }}
+            starIcon={StarIcon}
+          />
+          <Rating label="Disabled" value={0.8} disabled starIcon={StarIcon} />
+        </YStack>
+      );
+    };
+    return <InteractiveExample />;
+  },
+};

package/src/fields/Rating/index.tsx

@@ -0,0 +1,312 @@
+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 { getVariable, isWeb, styled, useTheme, View, XStack } from "tamagui";
+import Svg, { Path } from "react-native-svg";
+
+function starPath(size: number, innerRatio = 0.382): string {
+  const cx = size / 2;
+  const cy = size / 2;
+  const outerR = size / 2 - 1;
+  const innerR = outerR * innerRatio;
+  const parts: string[] = [];
+  for (let i = 0; i < 5; i++) {
+    const outerA = -Math.PI / 2 + (i * 2 * Math.PI) / 5;
+    const innerA = outerA + Math.PI / 5;
+    parts.push(
+      `${cx + outerR * Math.cos(outerA)},${cy + outerR * Math.sin(outerA)}`,
+      `${cx + innerR * Math.cos(innerA)},${cy + innerR * Math.sin(innerA)}`,
+    );
+  }
+  return `M${parts.join("L")}Z`;
+}
+
+function PointyStar({
+  size,
+  weight,
+  color,
+}: {
+  size: number;
+  weight: "fill" | "regular";
+  color: string;
+}) {
+  const d = starPath(size);
+  return (
+    <Svg width={size} height={size} viewBox={`0 0 ${size} ${size}`}>
+      <Path
+        d={d}
+        fill={weight === "fill" ? color : "none"}
+        stroke={color}
+        strokeWidth={1.5}
+        strokeLinejoin="miter"
+        strokeMiterlimit={10}
+      />
+    </Svg>
+  );
+}
+
+// CSS timing strings for web transitions (mirrors theme animation config)
+const cssTimings: Record<string, string> = {
+  bouncy: "ease-in 200ms",
+  lazy: "ease-in 600ms",
+  slow: "ease-in 500ms",
+  medium: "ease-in-out 250ms",
+  quick: "ease-in 100ms",
+  tooltip: "ease-in 400ms",
+  snappy: "ease-out 80ms",
+  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}` };
+}
+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: {
+        scale: 1.1,
+        rotate: "72deg",
+      },
+      false: {
+        scale: 1,
+        rotate: "0deg",
+      },
+    },
+  } as const,
+});
+import {
+  getFieldError,
+  mergeFieldHandler,
+  useFormField,
+  useResolvedValidators,
+} from "../../shared/utils";
+import type { AnyFormApi } from "../../types";
+
+function StarRow({
+  filledStars,
+  maxStars,
+  disabled,
+  readOnly,
+  onStarPress,
+  knobProps,
+  StarIcon,
+  filledColor,
+  emptyColor,
+  required,
+  hasError,
+}: {
+  filledStars: number;
+  maxStars: number;
+  disabled: boolean;
+  readOnly?: boolean;
+  onStarPress: (starIndex: number) => void;
+  knobProps: KnobProps;
+  StarIcon: ComponentType<{ size: number; weight: "fill" | "regular"; color: string }>;
+  filledColor: string;
+  emptyColor: string;
+  required?: boolean;
+  hasError?: boolean;
+}) {
+  return (
+    <XStack
+      {...knobProps.gap}
+      alignItems="center"
+      aria-required={required || undefined}
+      aria-invalid={hasError || undefined}
+      aria-readonly={readOnly || undefined}
+    >
+      {Array.from({ length: maxStars }, (_, i) => {
+        const starNumber = i + 1;
+        const isFilled = starNumber <= filledStars;
+        return (
+          <StarWrapper
+            key={starNumber}
+            onPress={() => !readOnly && onStarPress(starNumber)}
+            cursor={disabled || readOnly ? "default" : "pointer"}
+            opacity={disabled ? 0.5 : 1}
+            filled={isFilled}
+            style={getTransitionStyle(knobProps.transition)}
+          >
+            <StarIcon
+              size={24}
+              weight={isFilled ? "fill" : "regular"}
+              color={isFilled ? filledColor : emptyColor}
+            />
+          </StarWrapper>
+        );
+      })}
+    </XStack>
+  );
+}
+
+export interface RatingProps {
+  name?: string;
+  form?: AnyFormApi;
+  validators?: Record<string, unknown>;
+  label?: ReactNode;
+  labelProps?: Omit<LabelProps, "htmlFor" | "ref">;
+  helperText?: string;
+  error?: string | boolean;
+  required?: boolean;
+  size?: SizeTokens;
+  id?: string;
+  value?: number;
+  defaultValue?: number;
+  onChange?: (value: number) => void;
+  onBlur?: (...args: any[]) => void;
+  disabled?: boolean;
+  readOnly?: boolean;
+  maxStars?: number;
+  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 */
+  skeleton?: boolean;
+  /** When true, uses compact sizing */
+  compact?: boolean;
+}
+
+export function Rating({
+  name,
+  form: formProp,
+  validators,
+  label,
+  labelProps,
+  helperText,
+  error,
+  required,
+  size,
+  id: idProp,
+  value = 0,
+  defaultValue,
+  onChange,
+  onBlur,
+  disabled,
+  readOnly,
+  maxStars = 5,
+  starIcon,
+  pointy,
+  skeleton,
+  compact,
+}: RatingProps) {
+  const { resolvedForm, knobProps, id } = useFormField({ form: formProp, id: idProp, compact });
+  const resolvedPointy = pointy ?? knobProps.pointy;
+  const ResolvedStarIcon = resolvedPointy ? PointyStar : starIcon;
+  const resolvedValidators = useResolvedValidators(required, validators, label, name);
+  const filledStars = useMemo(() => Math.round(value * maxStars), [value, maxStars]);
+
+  // Resolve color tokens to actual CSS values for Phosphor icons
+  const theme = useTheme();
+  const filledColor = getVariable(theme.color10?.get("web") ?? theme.color?.get("web"));
+  const emptyColor = getVariable(theme.color7?.get("web") ?? theme.color?.get("web"));
+
+  const handleStarPress = (
+    starIndex: number,
+    currentFilled: number,
+    onValueChange?: (v: number) => void,
+  ) => {
+    if (disabled || readOnly) return;
+    const newFilled = starIndex === currentFilled ? 0 : starIndex;
+    onValueChange?.(newFilled / maxStars);
+  };
+
+  // Render skeleton placeholder
+  if (skeleton) {
+    return (
+      <FieldLayout id={id} label={label} size={size} knobProps={knobProps}>
+        <XStack {...knobProps.gap} alignItems="center">
+          {Array.from({ length: maxStars }, (_, i) => (
+            <Skeleton key={i} variant="rounded" width={24} height={24} />
+          ))}
+        </XStack>
+      </FieldLayout>
+    );
+  }
+
+  if (!resolvedForm || !name) {
+    return (
+      <FieldLayout
+        id={id}
+        label={label}
+        labelProps={labelProps}
+        error={error}
+        helperText={helperText}
+        required={required}
+        size={size}
+        knobProps={knobProps}
+        onBlur={onBlur}
+      >
+        <StarRow
+          knobProps={knobProps}
+          filledStars={filledStars}
+          maxStars={maxStars}
+          disabled={!!disabled}
+          readOnly={readOnly}
+          onStarPress={(i) => handleStarPress(i, filledStars, onChange)}
+          StarIcon={ResolvedStarIcon}
+          filledColor={filledColor}
+          emptyColor={emptyColor}
+          required={required}
+          hasError={!!error}
+        />
+      </FieldLayout>
+    );
+  }
+
+  return (
+    <Field
+      form={resolvedForm}
+      name={name}
+      defaultValue={defaultValue}
+      validators={resolvedValidators}
+    >
+      {(field) => {
+        const resolvedError = getFieldError(field, error);
+        const fieldValue = (field.state.value as number) ?? 0;
+        const fieldFilledStars = Math.round(fieldValue * maxStars);
+        return (
+          <FieldLayout
+            id={id}
+            label={label}
+            labelProps={labelProps}
+            error={resolvedError}
+            helperText={helperText}
+            required={required}
+            size={size}
+            knobProps={knobProps}
+            onBlur={mergeFieldHandler(field, "handleBlur", onBlur)}
+          >
+            <StarRow
+              knobProps={knobProps}
+              filledStars={fieldFilledStars}
+              maxStars={maxStars}
+              disabled={!!disabled}
+              onStarPress={(i) =>
+                handleStarPress(i, fieldFilledStars, (v) => {
+                  field.handleChange(v as any);
+                  onChange?.(v);
+                })
+              }
+              StarIcon={ResolvedStarIcon}
+              filledColor={filledColor}
+              emptyColor={emptyColor}
+              required={required}
+              hasError={!!resolvedError}
+            />
+          </FieldLayout>
+        );
+      }}
+    </Field>
+  );
+}