@rovula/ui 0.1.7 → 0.1.8

package/src/components/Form/Field.tsx

@@ -0,0 +1,160 @@
+import React, { ComponentType, useId } from "react";
+import {
+  FieldPath,
+  FieldPathValue,
+  FieldValues,
+  RegisterOptions,
+  useController,
+} from "react-hook-form";
+
+type ControlledComponentProps = object;
+
+export type FieldProps<
+  TFieldValues extends FieldValues,
+  TName extends FieldPath<TFieldValues>,
+  TComponentProps extends ControlledComponentProps = ControlledComponentProps,
+> = {
+  name: TName;
+  component: ComponentType<TComponentProps>;
+  componentProps?: Omit<
+    TComponentProps,
+    "name" | "value" | "onChange" | "onBlur" | "ref" | "aria-invalid"
+  >;
+  rules?: Omit<
+    RegisterOptions<TFieldValues, TName>,
+    "disabled" | "setValueAs" | "valueAsDate" | "valueAsNumber"
+  >;
+  defaultValue?: FieldPathValue<TFieldValues, TName>;
+  disabled?: boolean;
+  shouldUnregister?: boolean;
+  id?: string;
+  describedBy?: string;
+  valuePropName?: string;
+  changePropName?: string;
+  blurPropName?: string | false;
+  refPropName?: string | false;
+  errorMessagePropName?: string | false;
+  invalidPropName?: string | false;
+  parseValue?: (
+    incomingValue: unknown,
+    rawPayload: unknown
+  ) => FieldPathValue<TFieldValues, TName>;
+  formatValue?: (
+    value: FieldPathValue<TFieldValues, TName>
+  ) => TComponentProps[keyof TComponentProps];
+  onChange?: (
+    value: FieldPathValue<TFieldValues, TName>,
+    rawPayload: unknown
+  ) => void;
+  onBlur?: () => void;
+};
+
+const extractChangedValue = (payload: unknown) => {
+  if (
+    payload &&
+    typeof payload === "object" &&
+    "target" in payload &&
+    payload.target &&
+    typeof payload.target === "object"
+  ) {
+    const target = payload.target as {
+      value?: unknown;
+      checked?: unknown;
+      type?: string;
+    };
+
+    if (target.type === "checkbox") {
+      return target.checked;
+    }
+
+    return target.value;
+  }
+
+  return payload;
+};
+
+export const Field = <
+  TFieldValues extends FieldValues,
+  TName extends FieldPath<TFieldValues>,
+  TComponentProps extends ControlledComponentProps = ControlledComponentProps,
+>({
+  name,
+  component: Component,
+  componentProps,
+  rules,
+  defaultValue,
+  disabled = false,
+  shouldUnregister = false,
+  id,
+  describedBy,
+  valuePropName = "value",
+  changePropName = "onChange",
+  blurPropName = "onBlur",
+  refPropName = "ref",
+  errorMessagePropName = "errorMessage",
+  invalidPropName = "error",
+  parseValue,
+  formatValue,
+  onChange,
+  onBlur,
+}: FieldProps<TFieldValues, TName, TComponentProps>) => {
+  const fieldId = useId();
+  const resolvedId = id || `${name.replace(/\./g, "-")}-${fieldId}`;
+  const {
+    field,
+    fieldState: { error, invalid },
+  } = useController<TFieldValues, TName>({
+    name,
+    rules,
+    disabled,
+    defaultValue,
+    shouldUnregister,
+  });
+
+  const handleChange = (rawPayload: unknown) => {
+    const extractedValue = extractChangedValue(rawPayload);
+    const parsedValue = parseValue
+      ? parseValue(extractedValue, rawPayload)
+      : (extractedValue as FieldPathValue<TFieldValues, TName>);
+
+    field.onChange(parsedValue);
+    onChange?.(parsedValue, rawPayload);
+  };
+
+  const handleBlur = () => {
+    field.onBlur();
+    onBlur?.();
+  };
+
+  const componentValue = formatValue
+    ? formatValue(field.value as FieldPathValue<TFieldValues, TName>)
+    : field.value;
+
+  const sharedProps: Record<string, unknown> = {
+    ...(componentProps as Record<string, unknown>),
+    id: resolvedId,
+    name: field.name,
+    disabled,
+    "aria-invalid": invalid || undefined,
+    "aria-describedby": describedBy,
+  };
+
+  sharedProps[valuePropName] = componentValue;
+  sharedProps[changePropName] = handleChange;
+  if (blurPropName) {
+    sharedProps[blurPropName] = handleBlur;
+  }
+  if (refPropName) {
+    sharedProps[refPropName] = field.ref;
+  }
+  if (errorMessagePropName) {
+    sharedProps[errorMessagePropName] = error?.message;
+  }
+  if (invalidPropName) {
+    sharedProps[invalidPropName] = invalid;
+  }
+
+  return <Component {...(sharedProps as TComponentProps)} />;
+};
+
+export default Field;

package/src/components/Form/FieldMessage.tsx

@@ -0,0 +1,38 @@
+import React, { HTMLAttributes } from "react";
+import { FieldPath, FieldValues, useFormContext } from "react-hook-form";
+import { cn } from "@/utils/cn";
+
+export type FieldMessageProps<
+  TFieldValues extends FieldValues,
+  TName extends FieldPath<TFieldValues>,
+> = HTMLAttributes<HTMLParagraphElement> & {
+  name: TName;
+};
+
+export const FieldMessage = <
+  TFieldValues extends FieldValues,
+  TName extends FieldPath<TFieldValues>,
+>({
+  name,
+  className,
+  ...props
+}: FieldMessageProps<TFieldValues, TName>) => {
+  const { getFieldState, formState } = useFormContext<TFieldValues>();
+  const { error } = getFieldState(name, formState);
+
+  if (!error?.message) {
+    return null;
+  }
+
+  return (
+    <p
+      {...props}
+      className={cn("text-sm text-input-error mt-1", className)}
+      role="alert"
+    >
+      {error.message}
+    </p>
+  );
+};
+
+export default FieldMessage;

package/src/components/Form/Form.docs.mdx

@@ -0,0 +1,67 @@
+import { Meta, Title, Subtitle, Description, Heading, Unstyled, Canvas, Story, Markdown } from "@storybook/blocks";
+import * as FormStories from "./Form.stories";
+import FormReadme from "./README.md";
+
+<Meta title="Components/Form/Guide" of={FormStories} />
+
+<Title>Form Guide</Title>
+<Subtitle>How to use Form, Field, and custom input mapping</Subtitle>
+<Description>
+  This page summarizes practical usage of the Form system in this package.
+  For full examples, open stories under <code>Components/Form</code>.
+</Description>
+
+<Heading>Quick Start</Heading>
+<Unstyled>
+  <ul>
+    <li>Set defaults at <code>Form.defaultValues</code>.</li>
+    <li>Use <code>Field</code> to bind UI components to react-hook-form.</li>
+    <li>Use <code>validationSchema</code> or <code>resolver</code> for validation.</li>
+    <li>For custom components, map prop names and parse/format values as needed.</li>
+    <li>
+      Use <code>ref</code>/<code>controllerRef</code> for imperative actions:{" "}
+      <code>submit</code>, <code>getValues</code>, <code>setValue</code>,{" "}
+      <code>trigger</code>, and <code>reset</code>.
+    </li>
+  </ul>
+</Unstyled>
+
+<Heading>Most Used Field Mapping Props</Heading>
+<Unstyled>
+  <ul>
+    <li><code>valuePropName</code>: form value to component value prop.</li>
+    <li><code>changePropName</code>: component change callback prop.</li>
+    <li><code>formatValue</code>: form state to component payload.</li>
+    <li><code>parseValue</code>: component payload to form state.</li>
+  </ul>
+</Unstyled>
+
+<Heading>Validation Note</Heading>
+<Description>
+  If you use <code>mode=&quot;onTouched&quot;</code>, your input must call
+  <code>onBlur</code> correctly when focus leaves the field.
+</Description>
+
+<Heading>Examples</Heading>
+<Canvas>
+  <Story of={FormStories.BasicYupLogin} />
+</Canvas>
+
+<Canvas>
+  <Story of={FormStories.MixedUiKitControls} />
+</Canvas>
+
+<Canvas>
+  <Story of={FormStories.HigherLayerCodeControl} />
+</Canvas>
+
+<Heading>Async Dropdown (id in form state)</Heading>
+<Description>
+  Prefer storing primitive ids in form state, then map to option objects for UI
+  rendering via <code>formatValue</code>/<code>parseValue</code> or
+  <code>useOptionBridge</code>.
+</Description>
+
+<Heading>Full Markdown Doc</Heading>
+<Markdown>{FormReadme}</Markdown>
+