@carbonbits/sixr 1.4.0 → 1.5.0

package/dist/index.d.ts

@@ -1,41 +1,22 @@
+import { ButtonProps } from './button.js';
+export { Button, ButtonSize, ButtonVariant } from './button.js';
 export { Cart, CartProduct, CartProps } from './cart.js';
-import { InputHTMLAttributes, ReactNode } from 'react';
+import { ComponentPropsWithoutRef, ReactNode, FormHTMLAttributes } from 'react';
+import { Label } from '@radix-ui/react-label';
+import { Slot } from '@radix-ui/react-slot';
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { FieldValues, UseFormReturn, DefaultValues, Mode } from 'react-hook-form';
 export { Typography, TypographyElement, TypographyProps, TypographyTone, TypographyVariant, TypographyWeight } from './typography.js';
 
-/**
- * Structural shape of a zod schema — every zod schema satisfies it, and any
- * version of zod does. Declaring it this way rather than importing `ZodType`
- * keeps zod out of this module's public types, so consumers who only want an
- * input do not have to install zod to typecheck it.
- */
-type FieldSchema = {
-    safeParse: (value: unknown) => {
-        success: true;
-    } | {
-        success: false;
-        error: {
-            issues: readonly {
-                message: string;
-            }[];
-        };
-    };
-};
-/** Outcome of a single validation pass, handed to `onValidationChange`. */
-type FieldValidation = {
-    valid: boolean;
-    /** First issue reported by the schema, or `undefined` when valid. */
-    error?: string;
-};
-
-/** Props every specialised input shares. `type` is fixed by the wrapper. */
-type FieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, "onChange" | "value" | "defaultValue" | "type"> & {
+type InputFieldProps = Omit<ComponentPropsWithoutRef<"input">, "name" | "type"> & {
+    /** The form field this input edits — the key in the `Form`'s values. */
+    name: string;
     label?: string;
     /** Guidance under the field. Replaced by the error message while invalid. */
     hint?: ReactNode;
     /**
      * Error supplied by the caller — a server-side or cross-field failure. Takes
-     * precedence over the schema, so a form can hold a field invalid regardless
-     * of what `schema` makes of the value on its own.
+     * precedence over what the form's schema reports for this field.
      */
     error?: string;
     /** Renders the design's muted "Optional" marker at the end of the label. */
@@ -44,36 +25,115 @@ type FieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, "onChange" | "valu
     action?: ReactNode;
     /** Trailing in-field slot, for affordances like the design's password peek. */
     trailing?: ReactNode;
-    value?: string;
-    defaultValue?: string;
-    onChange?: (value: string) => void;
-    /**
-     * Any zod schema that accepts a string. Only `safeParse` is used, so a
-     * refined, transformed or preprocessed schema works as well as a plain one.
-     */
-    schema?: FieldSchema;
-    /**
-     * When the schema runs. `blur` — the default — avoids scolding someone
-     * mid-keystroke; once a field has gone invalid it revalidates on every
-     * keystroke so the message clears as soon as it is fixed.
-     */
-    validateOn?: "blur" | "change" | "never";
-    onValidationChange?: (state: FieldValidation) => void;
 };
 
 /**
  * An email address. Fixes `type="email"` and the keyboard and autofill hints
- * that go with it. Pair it with `emailSchema` from `@carbonbits/sixr/validation`
- * to validate inline; the schema stays opt-in so this bundle does not require
- * zod.
+ * that go with it. Validate it with `emailSchema` from
+ * `@carbonbits/sixr/validation` in the enclosing `Form`'s schema.
+ */
+type EmailInputProps = InputFieldProps;
+
+/**
+ * The structure behind every form field, with no styling of its own: an id
+ * shared by label and control, the error and description ids the control is
+ * described by, the field's validity, and — inside a `Form` — the
+ * react-hook-form bindings (`value`, `onChange`, `onBlur`, `ref`) that keep
+ * the control registered.
+ *
+ * Styled components compose these primitives with their own classes
+ * (`TextInput` and friends do), and a screen that needs a control the
+ * library does not ship — a select, a code entry, a toggle — composes them
+ * the same way. Everything here is a plain element or a Radix `Slot`, so the
+ * styling decisions stay with whoever renders the field.
+ *
+ * Outside a `Form` the primitives still wire label, control and messages
+ * together; the control just isn't registered anywhere and the error comes
+ * from the `error` prop alone.
  */
-type EmailInputProps = FieldProps;
+type FieldBindings = {
+    name: string;
+    value?: unknown;
+    onChange?: (event: unknown) => void;
+    onBlur?: () => void;
+    ref?: (instance: HTMLElement | null) => void;
+};
+type FieldContextValue = {
+    id: string;
+    name: string;
+    descriptionId: string;
+    messageId: string;
+    error: string | undefined;
+    invalid: boolean;
+    required: boolean;
+    disabled: boolean;
+    hasDescription: boolean;
+    setHasDescription: (present: boolean) => void;
+    bindings: FieldBindings;
+};
+type FieldRootProps = ComponentPropsWithoutRef<"div"> & {
+    /** The form field this wires up — the key in the `Form`'s values. */
+    name: string;
+    /** A caller-supplied error. Outranks whatever the form's schema reports. */
+    error?: string;
+    required?: boolean;
+    disabled?: boolean;
+    /** Render the child element as the root instead of a `div`. */
+    asChild?: boolean;
+    children: ReactNode;
+};
+type FieldLabelProps = ComponentPropsWithoutRef<typeof Label>;
+type FieldControlProps = ComponentPropsWithoutRef<typeof Slot>;
+type FieldDescriptionProps = ComponentPropsWithoutRef<"p"> & {
+    asChild?: boolean;
+};
+type FieldMessageProps = ComponentPropsWithoutRef<"p"> & {
+    asChild?: boolean;
+};
+
+/**
+ * A `<form>` on react-hook-form. The schema — any Standard Schema, which
+ * every zod 4 schema is — validates the whole form: on first blur per field,
+ * then on every change once a field has gone invalid, and again on submit.
+ * Fields register themselves through `FieldRoot` (and so through every
+ * input in this library), so a form is the schema, the inputs and a submit.
+ *
+ * `onSubmit` only runs with values the schema accepted, typed as its output.
+ * Throwing from it — or calling `form.setError("root", …)` — surfaces the
+ * message through `FormError`. While it is pending the fields are disabled
+ * and `SubmitButton` shows its spinner.
+ *
+ * Pass your own `form` (from `useFormInstance`) when a screen needs to reach
+ * the instance itself, for `setError`, `reset` or `watch`.
+ */
+type FormSchema = StandardSchemaV1<FieldValues, FieldValues>;
+type FormInput<Schema extends FormSchema> = StandardSchemaV1.InferInput<Schema>;
+type FormOutput<Schema extends FormSchema> = StandardSchemaV1.InferOutput<Schema>;
+type FormInstance<Schema extends FormSchema> = UseFormReturn<FormInput<Schema>, unknown, FormOutput<Schema>>;
+type UseFormInstanceOptions<Schema extends FormSchema> = {
+    schema?: Schema;
+    defaultValues?: DefaultValues<FormInput<Schema>>;
+    /** When a field first validates. `onTouched`: first blur, then every change. */
+    mode?: Mode;
+};
+type FormProps<Schema extends FormSchema = FormSchema> = Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit"> & UseFormInstanceOptions<Schema> & {
+    onSubmit: (values: FormOutput<Schema>, form: FormInstance<Schema>) => void | Promise<void>;
+    /** An instance from `useFormInstance`, when the screen needs it too. */
+    form?: FormInstance<Schema>;
+    children: ReactNode;
+};
+type FormErrorProps = {
+    /** A message to show in place of the form's own root error. */
+    children?: ReactNode;
+    className?: string;
+};
+type SubmitButtonProps = Omit<ButtonProps, "type" | "loading" | "asChild">;
 
 /**
  * A password. Fixes `type="password"` and owns the design's in-field peek
  * affordance, so the trailing slot is not exposed here — the toggle is it.
  */
-type PasswordInputProps = Omit<FieldProps, "trailing"> & {
+type PasswordInputProps = Omit<InputFieldProps, "trailing"> & {
     /** Show the "Show"/"Hide" toggle. On by default, as the design has it. */
     revealable?: boolean;
     /** Labels for the toggle, for localisation. */
@@ -84,10 +144,11 @@ type PasswordInputProps = Omit<FieldProps, "trailing"> & {
 };
 
 /**
- * A phone number. Fixes `type="tel"` and the numeric keypad. Pair it with
- * `phoneSchema` from `@carbonbits/sixr/validation` to validate inline.
+ * A phone number. Fixes `type="tel"` and the numeric keypad. Validate it with
+ * `phoneSchema` from `@carbonbits/sixr/validation` in the enclosing `Form`'s
+ * schema.
  */
-type PhoneInputProps = FieldProps;
+type PhoneInputProps = InputFieldProps;
 
 /**
  * Plain free text: names, job titles, one-time codes. Anything with a format
@@ -95,9 +156,9 @@ type PhoneInputProps = FieldProps;
  * component (`EmailInput`, `PhoneInput`, `PasswordInput`), which fixes the
  * keyboard, autocomplete and input type that format needs.
  */
-type TextInputProps = FieldProps & {
+type TextInputProps = InputFieldProps & {
     /** Renders the value in the design's monospace face, as the code entry does. */
     mono?: boolean;
 };
 
-export type { EmailInputProps, FieldProps, FieldSchema, FieldValidation, PasswordInputProps, PhoneInputProps, TextInputProps };
+export { ButtonProps, type EmailInputProps, type FieldBindings, type FieldContextValue, type FieldControlProps, type FieldDescriptionProps, type FieldLabelProps, type FieldMessageProps, type FieldRootProps, type FormErrorProps, type FormInput, type FormInstance, type FormOutput, type FormProps, type FormSchema, type InputFieldProps, type PasswordInputProps, type PhoneInputProps, type SubmitButtonProps, type TextInputProps, type UseFormInstanceOptions };

package/dist/index.js

@@ -1,3 +1,4 @@
+export { Button } from './chunk-HDTW4FRT.js';
 export { Cart } from './chunk-BHSOSXTU.js';
 export { Typography } from './chunk-NZHHNVXZ.js';
 //# sourceMappingURL=index.js.map