@vtex/faststore 0.0.4 → 0.0.6

package/dist/particles/field/field.d.ts

@@ -19,24 +19,139 @@ export type FieldErrorProps = ComponentPropsWithRef<'div'> & {
    * fall back to Base UI's default: shown whenever the field's tracked validity is invalid.
    * Note `match={false}` does not suppress the error — it falls back to that default
    * invalid-driven behavior; callers needing a boolean should use `invalid ? true : 'customError'`.
+   * Only consulted on the unbound path — a bound `Field.Error` renders from the field contract's
+   * name and react-hook-form's error state instead.
    */
   match?: boolean | keyof ValidityState;
 };
 export type FieldValidityProps = {
   children: (state: FieldValidityState) => ReactNode;
 };
+/** One choice of a field whose value is picked from a list. Platform-owned; an author reorders the part, not the list. */
+export type FieldOption = Readonly<{
+  value: string;
+  label: string;
+}>;
+/** A rule member constrained to `value`, carrying its own message — react-hook-form's own shape for
+ * a constrained validation rule, declared here as our own type (Decision 5). */
+export type FieldRuleConstraint<T> = Readonly<{
+  value: T;
+  message: string;
+}>;
+/** A field-level validator: reads the live value, returns `true` (valid), a message, or `false`. */
+export type FieldValidator = (value: unknown) => boolean | string;
+/**
+ * The fieldset's validation rule for this field, handed to `useBoundField` and mapped internally to
+ * react-hook-form's `RegisterOptions` (`toRegisterOptions`) — nothing that imports this type from the
+ * barrel ever names a react-hook-form type (RFC `Dependencies`).
+ *
+ * These seven members are a starting point measured against every rule this repository authors
+ * today, not a closed contract: `RegisterOptions` carries more (`setValueAs`, `deps`, `valueAsNumber`,
+ * …), and a member is added here the day a field actually needs it — this is not a deliberately closed
+ * set to work around.
+ */
+export type FieldRule = Readonly<{
+  required?: boolean | string | FieldRuleConstraint<boolean>;
+  min?: number | string | FieldRuleConstraint<number | string>;
+  max?: number | string | FieldRuleConstraint<number | string>;
+  minLength?: number | FieldRuleConstraint<number>;
+  maxLength?: number | FieldRuleConstraint<number>;
+  pattern?: RegExp | FieldRuleConstraint<RegExp>;
+  validate?: FieldValidator | Readonly<Record<string, FieldValidator>>;
+}>;
+/**
+ * One field's identity and its static facts: the argument list `useController` needs, hoisted out of
+ * a prop-drill that composition made impossible. Not a mirror of state react-hook-form also holds —
+ * it carries NO live value, so it never changes while the shopper types, and the parts subscribe to
+ * react-hook-form for value, error, dirty and touched.
+ */
+export type FieldContract = Readonly<{
+  /** Full, namespaced react-hook-form field name, e.g. `shippingAddress.street`. */
+  name: string;
+  /** Resolved label text: the Control's `label` prop, else the platform's default. */
+  label?: string;
+  placeholder?: string;
+  /** Seed value, registered as react-hook-form's field-level `defaultValue`. */
+  defaultValue?: unknown;
+  rule?: FieldRule;
+  /** Only for a field whose value is picked from a list. Unread until `Field.Select` is added. */
+  options?: readonly FieldOption[];
+  disabled?: boolean;
+  readOnly?: boolean;
+  autoComplete?: string;
+  inputMode?: 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';
+}>;
+/** Supplies the field contract to everything below it. Renders no DOM. Never catalogued. */
+export type FieldBindingProps = FieldContract & {
+  children?: ReactNode;
+};
+/**
+ * Provided by a fieldset. Declares the one namespace every name registered through it belongs to, and
+ * registers a full field name, returning its unregister.
+ */
+export type FieldsetFieldRegistry = {
+  /**
+   * The namespace this fieldset owns — the prefix of every full name its own controls register. Declared
+   * by the provider, never inferred from a caller.
+   */
+  namespace: string;
+  /**
+   * Registers a full, namespaced field name and returns a release function. Refcounted by the provider,
+   * so two callers holding one name produce one entry, released when the last of them releases. The
+   * returned function releases at most once.
+   */
+  registerFieldName: (name: string) => () => void;
+};
+/** What `useFieldsetFieldNames` hands a fieldset: the value to provide, and the list to register. */
+export type FieldsetFieldNames = Readonly<{
+  /** Referentially stable while `namespace` is unchanged. Goes straight into the context provider. */
+  registry: FieldsetFieldRegistry;
+  /** Every full field name currently held, in first-registration order. Stable identity. */
+  getFieldNames: () => readonly string[];
+}>;
+/** New bound part. Reads the contract, binds through useBoundField, drives Checkbox.Root. */
+export type FieldCheckboxProps = {
+  readonly className?: string;
+  readonly children?: ReactNode;
+};
+/** Reads the field contract. Returns null when no binding is above the caller. */
+export declare function useField(): FieldContract | null;
+export declare function FieldBinding({ name, label, placeholder, defaultValue, rule, options, disabled, readOnly, autoComplete, inputMode, children }: FieldBindingProps): ReactNode;
+/** Exported so those tasks import it rather than redefine it. */
+export declare const FieldsetFieldContext: import("react").Context<FieldsetFieldRegistry | null>;
+/** Unchanged: the registry above the caller, or null. Now carrying a namespace. */
+export declare function useFieldsetContext(): FieldsetFieldRegistry | null;
+/**
+ * Registers `${namespace}.${key}` with the enclosing fieldset while the caller is mounted, and returns
+ * that full name. Throws during render when a registry is above the caller and declares a different
+ * namespace. Registers nothing and throws nothing when no registry is above. Holds no state: the
+ * refcount belongs to the provider.
+ */
+export declare function useFieldsetField(namespace: string, key: string): string;
+/**
+ * The field-name bookkeeping a fieldset provides. Refcounted, so two callers of one name collapse to one
+ * entry however they arrived — including a caller that reaches `registerFieldName` directly.
+ */
+export declare function useFieldsetFieldNames(namespace: string): FieldsetFieldNames;
+/**
+ * Throws during render when an ancestor fieldset is already providing field registration for this
+ * subtree. Every fieldset calls it in one line.
+ */
+export declare function useNoAncestorFieldset(componentName: string): void;
 export declare const FieldRootDefinition: ComponentDefinition<FieldRootProps>;
 export declare const FieldLabelDefinition: ComponentDefinition<import("react").DetailedHTMLProps<import("react").LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>>;
 export declare const FieldControlDefinition: ComponentDefinition<FieldControlProps>;
 export declare const FieldDescriptionDefinition: ComponentDefinition<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>>;
 export declare const FieldErrorDefinition: ComponentDefinition<FieldErrorProps>;
 export declare const FieldValidityDefinition: ComponentDefinition<FieldValidityProps>;
+export declare const FieldCheckboxDefinition: ComponentDefinition<FieldCheckboxProps>;
 export declare function FieldRoot({ disabled, invalid, name, className, children, ...props }: FieldRootProps): import("react/jsx-runtime").JSX.Element;
 export declare function FieldLabel({ className, children, ...props }: FieldLabelProps): import("react/jsx-runtime").JSX.Element;
 export declare function FieldControl({ className, ...props }: FieldControlProps): import("react/jsx-runtime").JSX.Element;
 export declare function FieldDescription({ className, children, ...props }: FieldDescriptionProps): import("react/jsx-runtime").JSX.Element;
 export declare function FieldError({ className, children, ...props }: FieldErrorProps): import("react/jsx-runtime").JSX.Element;
 export declare function FieldValidity({ children }: FieldValidityProps): import("react/jsx-runtime").JSX.Element;
+export declare function FieldCheckbox({ className, children }: FieldCheckboxProps): ReactNode;
 declare const Field$1: {
   Root: typeof FieldRoot;
   Label: typeof FieldLabel;
@@ -44,6 +159,7 @@ declare const Field$1: {
   Description: typeof FieldDescription;
   Error: typeof FieldError;
   Validity: typeof FieldValidity;
+  Checkbox: typeof FieldCheckbox;
 };
 //#endregion
 export { Field$1 as Field };