orynn 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,400 @@
+import * as react from 'react';
+import { ComponentType, SyntheticEvent, SelectHTMLAttributes, ReactNode, ChangeEvent, InputHTMLAttributes, FormEvent } from 'react';
+
+/**
+ * Per-field validation config. V1 ships `required` / `minLength` / `maxLength`.
+ * Future rule keys (regex, email, min, max, validate, ...) are added here without
+ * a breaking change.
+ */
+interface FieldValidation {
+    required?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    /** Per-rule message overrides, e.g. `{ required: "Name is required" }`. */
+    messages?: Partial<Record<string, string>>;
+}
+/** A single validation failure. Shape is frozen — new fields must stay optional. */
+interface FieldError {
+    /** Rule that failed: `"required"`, `"minLength"`, `"custom"`, `"async"`, ... */
+    rule: string;
+    message: string;
+    /** Reserved for cross-field / nested errors. Unused in V1. */
+    path?: string;
+}
+/**
+ * Validation output. Key = field name. The reserved key `"$form"` holds
+ * form-level / cross-field errors.
+ */
+type ValidationResult = Record<string, FieldError[]>;
+/** Reserved key in {@link ValidationResult} for form-level errors. */
+declare const FORM_ERROR_KEY: "$form";
+/** What triggered a validation run. */
+type ValidationTrigger = "change" | "blur" | "submit";
+interface ValidationContext {
+    /** Field whose change/blur triggered this run, if any. */
+    changedField?: string;
+    trigger: ValidationTrigger;
+}
+/**
+ * The single seam through which all validation flows. V1's default resolver is
+ * rule-based and synchronous; the `Promise` return type keeps async, schema, and
+ * cross-field validation additive.
+ */
+type ValidationResolver = (values: Record<string, unknown>, config: FieldsetConfig, context: ValidationContext) => ValidationResult | Promise<ValidationResult>;
+/**
+ * A single rule implementation. Returns an error message string on failure, or
+ * `null` on success. `allValues` is passed so cross-field rules need no
+ * signature change later.
+ */
+type RuleFn = (value: unknown, param: unknown, allValues: Record<string, unknown>) => string | null;
+
+/** A single selectable option in a {@link DropdownFieldConfig}. */
+interface DropdownOption {
+    label: string;
+    value: string;
+    disabled?: boolean;
+}
+/** Number of columns at each responsive breakpoint. */
+interface ColumnSpec {
+    desktop: number;
+    tablet: number;
+    mobile: number;
+}
+/** Fields common to every field type. */
+interface BaseFieldConfig {
+    /** Unique key within the fieldset; also the key in the values object. */
+    name: string;
+    label?: string;
+    description?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    readOnly?: boolean;
+    defaultValue?: unknown;
+    validation?: FieldValidation;
+    /** Field-level column span, overriding the fieldset's `columns`. */
+    layout?: Partial<ColumnSpec>;
+    /** Escape hatch: spread verbatim onto the underlying control. */
+    props?: Record<string, unknown>;
+}
+/** Native `<input>` field. `inputType` maps to the DOM `type` attribute. */
+interface InputFieldConfig extends BaseFieldConfig {
+    type: "input";
+    inputType?: "text" | "email" | "password" | "number" | "tel" | "url";
+}
+/** Native `<select>` field. */
+interface DropdownFieldConfig extends BaseFieldConfig {
+    type: "dropdown";
+    options: DropdownOption[];
+}
+/**
+ * Maps a field `type` string to its config shape. Consumers register custom
+ * field types by augmenting this interface:
+ *
+ * ```ts
+ * declare module "orynn" {
+ *   interface FieldConfigRegistry {
+ *     rating: RatingFieldConfig;
+ *   }
+ * }
+ * ```
+ */
+interface FieldConfigRegistry {
+    input: InputFieldConfig;
+    dropdown: DropdownFieldConfig;
+}
+/** Discriminated union of every registered field config. */
+type FieldConfig = FieldConfigRegistry[keyof FieldConfigRegistry];
+/** The `type` discriminant of any registered field. */
+type FieldType = keyof FieldConfigRegistry;
+/** Top-level configuration passed to `<Fieldset config={...} />`. */
+interface FieldsetConfig {
+    fields: FieldConfig[];
+    /** Rendered in a `<legend>` when present. */
+    legend?: string;
+    /** Columns per breakpoint. Defaults to `{ desktop: 3, tablet: 2, mobile: 1 }`. */
+    columns?: Partial<ColumnSpec>;
+    /** Grid gap; a number is treated as pixels. */
+    gap?: string | number;
+    id?: string;
+}
+
+/**
+ * The contract every control receives from `Fieldset`. This is the stability
+ * boundary between the orchestrator and the controls: as long as this holds,
+ * either side can change freely.
+ */
+interface ControlProps<TValue = unknown> {
+    id: string;
+    name: string;
+    value: TValue;
+    /** Value-first; the DOM event is the optional second argument. */
+    onChange: (value: TValue, event?: SyntheticEvent) => void;
+    onBlur: () => void;
+    onFocus: () => void;
+    disabled?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    invalid?: boolean;
+    /** Space-separated id list to place on the control's `aria-describedby`. */
+    describedById?: string;
+    /** The full field config, for type-specific data (e.g. dropdown `options`). */
+    config: FieldConfig;
+}
+/** A React component that satisfies {@link ControlProps}. */
+type ControlComponent<TValue = any> = ComponentType<ControlProps<TValue>>;
+/** A registry entry for one field `type`. */
+interface FieldRegistration<TValue = any> {
+    component: ControlComponent<TValue>;
+    /** Value used when neither the config nor the form supplies one. */
+    defaultValue?: TValue;
+    /** Normalize an incoming value before it reaches the control. */
+    parseValue?: (raw: unknown) => TValue;
+    /** Normalize an outgoing value before it reaches `onChange`. */
+    formatValue?: (value: TValue) => unknown;
+    /**
+     * Type-specific config validation. Return an error string to reject a field
+     * config (thrown in development), or `null` when it is valid. Keeps per-type
+     * knowledge out of the core normalizer.
+     */
+    validateConfig?: (config: BaseFieldConfig & {
+        type: string;
+    }) => string | null;
+}
+/** Read-only view of a field registry. */
+interface FieldRegistry {
+    register(type: string, registration: FieldRegistration): void;
+    get(type: string): FieldRegistration | undefined;
+    has(type: string): boolean;
+    /** All registered type strings, for error messages. */
+    types(): string[];
+}
+
+/** Error prop accepted by controls: one message or many. */
+type ErrorProp = string | string[] | undefined;
+/** Context handed to `<Field>`'s render function. */
+interface FieldRenderContext {
+    /** Resolved control id (generated when not supplied). */
+    id: string;
+    /** Value for the control's `aria-describedby`, or `undefined`. */
+    describedById: string | undefined;
+    invalid: boolean;
+    required: boolean | undefined;
+    disabled: boolean | undefined;
+}
+/**
+ * Low-level layout + a11y wrapper. Renders label, description and error region
+ * and wires the ARIA relationships. `Input` and `Dropdown` are built on it, and
+ * it is exported for custom control authors.
+ */
+interface FieldProps {
+    label?: ReactNode;
+    description?: ReactNode;
+    error?: ErrorProp;
+    required?: boolean;
+    disabled?: boolean;
+    /** Control id; generated with `useId` when omitted. */
+    id?: string;
+    className?: string;
+    children: ReactNode | ((ctx: FieldRenderContext) => ReactNode);
+}
+/** Props shared by the standalone controls. */
+interface SharedControlProps {
+    label?: ReactNode;
+    description?: ReactNode;
+    error?: ErrorProp;
+}
+interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "onChange" | "value" | "type">, SharedControlProps {
+    value?: string;
+    onChange?: (value: string, event?: ChangeEvent<HTMLInputElement>) => void;
+    type?: "text" | "email" | "password" | "number" | "tel" | "url";
+}
+interface DropdownProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "onChange" | "value">, SharedControlProps {
+    options: DropdownOption[];
+    value?: string;
+    onChange?: (value: string, event?: ChangeEvent<HTMLSelectElement>) => void;
+    /** Renders a non-selectable prompt option when the value is empty. */
+    placeholder?: string;
+}
+interface FieldsetProps<TValues extends Record<string, unknown> = Record<string, unknown>> {
+    config: FieldsetConfig;
+    /** Controlled values. Omit and use `defaultValue` for uncontrolled. */
+    value?: TValues;
+    defaultValue?: Partial<TValues>;
+    onChange?: (values: TValues) => void;
+    onValidationChange?: (result: ValidationResult) => void;
+    /** Replace validation wholesale. Defaults to the built-in rule resolver. */
+    resolver?: ValidationResolver;
+    /** Override the field registry for this instance. */
+    registry?: FieldRegistry;
+    /** When to validate. `"blur"` (default) also always validates on submit. */
+    validateOn?: ValidationTrigger;
+    /** Disable every field (rendered as a native `<fieldset disabled>`). */
+    disabled?: boolean;
+    className?: string;
+    id?: string;
+}
+
+/**
+ * A labelled single-select built on the native `<select>` element (accessible
+ * and keyboard-navigable out of the box). Works with or without `<Fieldset>`.
+ */
+declare const Dropdown: react.ForwardRefExoticComponent<DropdownProps & react.RefAttributes<HTMLSelectElement>>;
+
+/**
+ * Layout + accessibility wrapper for a single control. Renders the label,
+ * optional description, and an error region, and wires the ARIA relationships
+ * (`htmlFor`, `aria-describedby`, `aria-invalid`, `aria-required`).
+ *
+ * Pass a render function as `children` to receive the resolved ids:
+ *
+ * ```tsx
+ * <Field label="Name" error={error}>
+ *   {({ id, describedById, invalid }) => (
+ *     <input id={id} aria-describedby={describedById} aria-invalid={invalid} />
+ *   )}
+ * </Field>
+ * ```
+ */
+declare function Field(props: FieldProps): react.JSX.Element;
+
+/**
+ * A labelled text input. Controlled when `value` is passed, uncontrolled
+ * otherwise (`defaultValue` flows through to the native element). Works with or
+ * without `<Fieldset>`.
+ */
+declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
+
+/**
+ * Renders a form (or a form section) from a `FieldsetConfig`. Controlled when
+ * `value` is passed, uncontrolled otherwise. Renders a native `<fieldset>` — so
+ * `disabled` cascades to every control — and does not render its own `<form>`;
+ * wrap it in one and use `useFieldsetState().handleSubmit` for submission.
+ */
+declare function Fieldset<TValues extends Record<string, unknown> = Record<string, unknown>>(props: FieldsetProps<TValues>): react.JSX.Element;
+
+/** Form-level validation roll-up. */
+type FieldStatus = "idle" | "validating" | "valid" | "invalid";
+/** The complete state a fieldset tracks. New keys must be additive. */
+interface FieldsetState {
+    values: Record<string, unknown>;
+    /** Field has been blurred at least once. */
+    touched: Record<string, boolean>;
+    /** Field value differs from its initial value. */
+    dirty: Record<string, boolean>;
+    errors: ValidationResult;
+    status: FieldStatus;
+}
+
+/** A validated `FieldsetConfig` with every default resolved. */
+interface NormalizedFieldsetConfig {
+    fields: FieldConfig[];
+    columns: ColumnSpec;
+    /** CSS length for the grid gap, or `undefined` to use the token default. */
+    gap: string | undefined;
+    legend: string | undefined;
+    id: string | undefined;
+}
+/**
+ * Validate a `FieldsetConfig` and resolve its defaults. Structural problems
+ * throw in development with an actionable message; in production the checks are
+ * stripped and normalization is defensive.
+ *
+ * Pass `registry` (as `<Fieldset>` does) to also validate each field's `type`
+ * and run type-specific config checks.
+ */
+declare function normalizeConfig(config: FieldsetConfig, registry?: FieldRegistry): NormalizedFieldsetConfig;
+
+type Values = Record<string, unknown>;
+interface UseFieldsetStateOptions<TValues extends Values = Values> {
+    /** Controlled values. Omit and pass `defaultValue` for uncontrolled. */
+    value?: TValues;
+    defaultValue?: Partial<TValues>;
+    onChange?: (values: TValues) => void;
+    /** Called after a full validation pass (`validate()` / submit), not per blur. */
+    onValidationChange?: (result: ValidationResult) => void;
+    resolver?: ValidationResolver;
+    registry?: FieldRegistry;
+    /** `"blur"` (default) also always validates on submit. */
+    validateOn?: ValidationTrigger;
+}
+/** Everything a renderer needs for one field. Handlers are referentially stable. */
+interface FieldSlice {
+    name: string;
+    value: unknown;
+    errors: FieldError[];
+    touched: boolean;
+    dirty: boolean;
+    setValue: (value: unknown) => void;
+    markTouched: () => void;
+}
+interface UseFieldsetStateReturn<TValues extends Values = Values> {
+    config: NormalizedFieldsetConfig;
+    state: FieldsetState;
+    values: TValues;
+    errors: ValidationResult;
+    touched: Record<string, boolean>;
+    dirty: Record<string, boolean>;
+    status: FieldStatus;
+    isValid: boolean;
+    setFieldValue: (name: string, value: unknown) => void;
+    setValues: (values: TValues) => void;
+    reset: (next?: Partial<TValues>) => void;
+    validate: () => Promise<ValidationResult>;
+    handleSubmit: (onValid: (values: TValues) => void, onInvalid?: (result: ValidationResult) => void) => (event?: FormEvent) => void;
+    getFieldProps: (name: string) => FieldSlice;
+}
+/**
+ * The form engine behind `<Fieldset>`, usable directly when you want to own the
+ * markup. Manages values (controlled or uncontrolled), touched/dirty tracking,
+ * and validation through a pluggable resolver.
+ */
+declare function useFieldsetState<TValues extends Values = Values>(config: FieldsetConfig, options?: UseFieldsetStateOptions<TValues>): UseFieldsetStateReturn<TValues>;
+
+/**
+ * Create an isolated field registry. Use this to give a `<Fieldset>` its own set
+ * of field types without touching the module-global {@link defaultRegistry}
+ * (recommended on the server, where mutating a shared registry per request would
+ * leak between requests).
+ *
+ * @experimental The registry API may change before 1.0.
+ */
+declare function createRegistry(): FieldRegistry;
+/**
+ * The module-global registry used by `<Fieldset>` when no `registry` prop is
+ * passed. Seeded with the built-in `input` and `dropdown` fields.
+ *
+ * @experimental
+ */
+declare const defaultRegistry: FieldRegistry;
+/**
+ * Register a field type on the {@link defaultRegistry}. Call this once at
+ * application start-up, not per render or per request.
+ *
+ * @experimental
+ */
+declare function registerField(type: string, registration: FieldRegistration): void;
+
+/** A synchronous resolver — the built-in resolver's precise return type. */
+type SyncResolver = (values: Record<string, unknown>, config: FieldsetConfig, context: ValidationContext) => ValidationResult;
+/**
+ * The default, rule-based {@link ValidationResolver}. For every field with a
+ * `validation` block, each key (other than `messages`) is looked up in the rule
+ * registry and run against the field's current value. All fields are validated
+ * on every call; callers decide which errors to surface.
+ *
+ * Synchronous today. Async, schema-based, and cross-field resolvers plug in at
+ * the same seam without an API change.
+ */
+declare function createRuleResolver(): SyncResolver;
+/** Shared default instance. */
+declare const defaultResolver: ValidationResolver;
+
+/**
+ * Register a validation rule for the built-in resolver. A field opts in by
+ * adding a key of the same name to its `validation` config.
+ *
+ * @experimental The rule API may change before 1.0.
+ */
+declare function registerRule(name: string, fn: RuleFn): void;
+
+export { type BaseFieldConfig, type ColumnSpec, type ControlComponent, type ControlProps, Dropdown, type DropdownFieldConfig, type DropdownOption, type DropdownProps, type ErrorProp, FORM_ERROR_KEY, Field, type FieldConfig, type FieldConfigRegistry, type FieldError, type FieldProps, type FieldRegistration, type FieldRegistry, type FieldRenderContext, type FieldSlice, type FieldStatus, type FieldType, type FieldValidation, Fieldset, type FieldsetConfig, type FieldsetProps, type FieldsetState, Input, type InputFieldConfig, type InputProps, type NormalizedFieldsetConfig, type RuleFn, type SyncResolver, type UseFieldsetStateOptions, type UseFieldsetStateReturn, type ValidationContext, type ValidationResolver, type ValidationResult, type ValidationTrigger, createRegistry, createRuleResolver, defaultRegistry, defaultResolver, normalizeConfig, registerField, registerRule, useFieldsetState };