haze-ui 1.16.1 → 1.17.0

package/README.md

@@ -190,7 +190,7 @@ render-prop are mutually exclusive.
 - With a typed form, `validate`'s value argument is the field's actual
   type (`PathValueOf<TValues, P>`), not `any`.
 
-#### `input`: declarative binding for haze-ui cores (typed prop forwarding)
+#### `input`: declarative binding for cores and raw DOM controls (typed prop forwarding)
 
 The ergonomic form for the controlled cores — pass the component and the
 rest of the JSX goes straight to it, type-checked against its own props:
@@ -243,6 +243,45 @@ checkbox-style core pairs with `valueToProps`). The differences from
   own `label`) is unreachable through `input` — use the render-prop or
   `as`/`asProps` for it.
 
+`input` also takes raw DOM bindings — no core required. The two raw
+forms are explicit about their `eventToValue` adapter, so the value
+channel is never guessed:
+
+```jsx
+// a native form element: the binding pairs the tag with its adapter,
+// and the rest of the JSX is type-checked against that element's own
+// HTML attributes (rows on a textarea, options as a select's children)
+<FormItem
+  form={form}
+  name="bio"
+  label="Bio"
+  input={{element: 'textarea', eventToValue: (e) => e.target.value}}
+  rows={4}
+/>
+
+// a DOM-element-shaped component: the top-level eventToValue is the
+// explicit opt-in from plain-value (core) to event-emitting (raw)
+<FormItem
+  form={form}
+  name="email"
+  label="Email"
+  input={NativeInput}
+  eventToValue={(e) => e.target.value}
+/>
+```
+
+- The element binding accepts `'input' | 'textarea' | 'select'` and
+  **requires** its `eventToValue` — `input={{element: 'input'}}` without
+  the adapter is a compile error (at runtime an untyped caller that
+  skips it still gets `e.target.value`, the DOM contract, never an Event
+  in the store).
+- The top-level `eventToValue` next to a component `input` switches that
+  binding to raw semantics, mirroring the `as` channel; forwarded props
+  still check against the component's own props.
+- The same reserved-prop rule applies: `id`, `onBlur`, `onChange`,
+  `value`/`checked`, aria-*, and FormItem's own names are never
+  forwarded on the raw channel either.
+
 #### `mode`: per-field validation timing (react-f0rm ≥ 0.6)
 
 Pass `mode` to validate one field on its own schedule instead of the

package/dist/form/FormItem.js

@@ -15,9 +15,9 @@ function c({ form: c, name: l, label: u, validate: d, mode: f, validateDebounce:
 		validateDebounce: p,
 		delayError: m,
 		rules: h
-	}), j = A.length > 0, M = x ?? ((e) => e);
+	}), j = A.length > 0, M = b && typeof b == "object" && "element" in b ? b : void 0, N = M?.eventToValue ?? x ?? (M ? (e) => e.target?.value : (e) => e);
 	if (b && typeof C == "function") throw Error("FormItem: `input` and the render-prop `children` are mutually exclusive — the input component is wired declaratively; remove the render-prop.");
-	let N = b;
+	let P = M ? M.element : b;
 	return /* @__PURE__ */ n("div", {
 		className: e([a, g]),
 		children: [
@@ -26,13 +26,13 @@ function c({ form: c, name: l, label: u, validate: d, mode: f, validateDebounce:
 				className: e(o),
 				children: u
 			}),
-			N ? /* @__PURE__ */ t(N, {
+			P ? /* @__PURE__ */ t(P, {
 				...w,
 				id: T,
 				"aria-invalid": j || void 0,
 				"aria-describedby": j ? E : void 0,
 				onBlur: k,
-				onChange: (e) => O(M(e)),
+				onChange: (e) => O(N(e)),
 				...S ? S(D) : { value: D },
 				children: C
 			}) : v ? /* @__PURE__ */ t(v, {
@@ -40,7 +40,7 @@ function c({ form: c, name: l, label: u, validate: d, mode: f, validateDebounce:
 				"aria-invalid": j || void 0,
 				"aria-describedby": j ? E : void 0,
 				onBlur: k,
-				onChange: (e) => O(M(e)),
+				onChange: (e) => O(N(e)),
 				...y,
 				...S ? S(D) : { value: D }
 			}) : C({

package/dist/types/form/FormItem.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentType, ReactNode } from 'react';
+import type { ComponentPropsWithoutRef, ComponentType, ReactNode } from 'react';
 import type { FieldError, FieldPath, FieldRules, Name, ValidationMode, FormInstance, PathValueOf } from 'react-f0rm';
 /**
  * Field-level validator, structurally compatible with react-f0rm's
@@ -52,16 +52,36 @@ export type FormItemAsProps = {
      * value props, so `value`/`valueToProps` win conflicts — the same
      * precedence react-f0rm's `Field` uses. */
     asProps?: Record<string, any>;
-    /** Converts what the `as` component passes to its `onChange` into the
-     * field value. Defaults to identity — haze cores' `onChange` emits the
-     * next plain value; pass `(e) => e.target.value` when `as` is a raw
-     * DOM-element component. */
+    /** Converts what the control passes to its `onChange` into the field
+     * value. Defaults to identity — haze cores' `onChange` emits the next
+     * plain value; pass `(e) => e.target.value` when the control is
+     * DOM-element-shaped (a raw `as` component, or a raw component on the
+     * `input` channel, where passing the adapter is also the explicit
+     * opt-in from core to raw semantics). */
     eventToValue?: (e: any) => any;
     /** Derives the value props for the `as` component from the field value —
      * e.g. `(checked) => ({checked})` for `CheckboxCore`. Defaults to
      * passing `{value}`. */
     valueToProps?: (value: any) => Record<string, any>;
 };
+/**
+ * The raw DOM form elements `FormItem`'s `input` channel accepts by tag
+ * name. Their `onChange` emits a DOM event, not a plain value, so the
+ * binding always carries its own `eventToValue` adapter — see
+ * `FormItemRawElementBinding`.
+ */
+export type FormItemRawElement = 'input' | 'textarea' | 'select';
+/**
+ * Raw-DOM binding for `FormItem`'s `input` channel — the explicit raw
+ * counterpart of passing a core component: a native form element by tag
+ * name, paired with the `eventToValue` adapter that extracts the next
+ * value from the DOM event. Every other JSX prop forwards to the
+ * element, type-checked against that element's own HTML attributes.
+ */
+export type FormItemRawElementBinding<TRawElement extends FormItemRawElement = FormItemRawElement> = {
+    element: TRawElement;
+    eventToValue: (e: any) => any;
+};
 /** FormItem's own, non-polymorphic props — everything the item itself
  * consumes regardless of how the control is bound (render-prop, `as`
  * or `input`). */
@@ -104,7 +124,7 @@ export type FormItemOwnProps<TValues extends Record<string, any> = any, P extend
 };
 /**
  * Props FormItem wires itself onto an `input`/`as` control — the bridge's
- * own contract. Used to keep them out of `input`'s forwarded rest props
+ * own contract. Used to keep them out of the forwarded rest props
  * (type level) and to document that they always win (runtime level):
  * passing one anyway is a compile error, never a silent override.
  */
@@ -119,35 +139,64 @@ type FormItemWiredProps = {
     'aria-invalid'?: unknown;
     'aria-describedby'?: unknown;
 };
-export type FormItemProps<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name, TInputProps extends Record<string, any> = Record<never, never>> = FormItemOwnProps<TValues, P> & FormItemAsProps & {
+/**
+ * Prop names the bridge owns or wires — excluded from the forwarded rest
+ * props on every channel (core component, raw element, `as`).
+ */
+type FormItemReservedProps<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name> = keyof FormItemOwnProps<TValues, P> | keyof FormItemAsProps | keyof FormItemWiredProps | 'input';
+export type FormItemProps<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name, TInputProps extends Record<string, any> = Record<never, never>, TRawElement extends FormItemRawElement = never> = FormItemOwnProps<TValues, P> & Omit<FormItemAsProps, 'eventToValue'> & {
     /**
-     * Declarative binding for haze-ui cores: pass the component
-     * (`InputCore`, `TextareaCore`, `TagInputCore`, `SelectCore`,
-     * `CheckboxCore`, …) and FormItem wires `id`, `aria-invalid`,
-     * `aria-describedby`, `onBlur`, `onChange` and the value channel
-     * itself. Every other prop — and JSX children (a `SelectCore`'s
-     * `<option>`s) — is forwarded to the component, fully type-checked
-     * against its own props. Cores' `onChange` emits the next plain value
-     * (identity `eventToValue`); checkbox-style controls pair with
-     * `valueToProps={(checked) => ({checked})}`. Props FormItem owns or
-     * wires (label, className, id, aria-*, onBlur, onChange, value,
-     * checked, …) are reserved and cannot be forwarded — use the
-     * render-prop or `as`/`asProps` for a colliding control prop.
+     * Declarative binding for the field control, in two forms:
+     *
+     * - a component (`InputCore`, `TextareaCore`, `TagInputCore`,
+     *   `SelectCore`, `CheckboxCore`, …, or any DOM-element-shaped
+     *   component): FormItem wires `id`, `aria-invalid`,
+     *   `aria-describedby`, `onBlur`, `onChange` and the value channel
+     *   itself. Haze cores' `onChange` emits the next plain value
+     *   (identity `eventToValue`); checkbox-style controls pair with
+     *   `valueToProps={(checked) => ({checked})}`. A DOM-element-shaped
+     *   component opts into raw semantics by passing `eventToValue`
+     *   (e.g. `(e) => e.target.value`) — the adapter's presence is the
+     *   explicit switch from value-direct to event-emitting.
+     * - a `FormItemRawElementBinding` — `{element: 'input' |
+     *   'textarea' | 'select', eventToValue}` — for a native DOM
+     *   element: same wiring, value extracted from the DOM event by the
+     *   required adapter (the top-level `eventToValue` is not this
+     *   form's slot).
+     *
+     * Every other prop — and JSX children (a `SelectCore`'s
+     * `<option>`s) — is forwarded to the control, fully type-checked
+     * against its own props (the component's, or the raw element's HTML
+     * attributes). Props FormItem owns or wires (label, className, id,
+     * aria-*, onBlur, onChange, value, checked, …) are reserved and
+     * cannot be forwarded — use the render-prop or `as`/`asProps` for a
+     * colliding control prop.
      */
-    input?: ComponentType<TInputProps>;
-} & Omit<TInputProps, keyof FormItemOwnProps<TValues, P> | keyof FormItemAsProps | keyof FormItemWiredProps | 'input'> & ({
+    input?: ComponentType<TInputProps> | FormItemRawElementBinding<TRawElement>;
+} & ([TRawElement] extends [never] ? Omit<TInputProps, FormItemReservedProps<TValues, P>> : Omit<ComponentPropsWithoutRef<TRawElement>, FormItemReservedProps<TValues, P>>) & ({
     as: ComponentType<any>;
     input?: never;
     children?: never;
+    eventToValue?: FormItemAsProps['eventToValue'];
 } | {
     as?: undefined;
     input: ComponentType<TInputProps>;
+    eventToValue?: FormItemAsProps['eventToValue'];
     /** JSX children forward to the control (SelectCore's options);
      * the render-prop form is mutually exclusive with `input`. */
     children?: 'children' extends keyof TInputProps ? TInputProps['children'] : undefined;
+} | {
+    as?: undefined;
+    input: FormItemRawElementBinding<TRawElement>;
+    /** the raw element binding carries its own `eventToValue` — the
+     * top-level prop is not accepted next to it */
+    eventToValue?: never;
+    /** JSX children forward to the element (a select's options). */
+    children?: ReactNode;
 } | {
     as?: undefined;
     input?: undefined;
+    eventToValue?: never;
     children: (binding: FormItemBinding<TValues, P>) => ReactNode;
 });
 /**
@@ -206,9 +255,32 @@ export type FormItemProps<TValues extends Record<string, any> = any, P extends F
  * collides (CheckboxCore's `label`) needs the render-prop or
  * `as`/`asProps` channel.
  *
+ * `input` also accepts raw DOM bindings — no core required:
+ *
+ * ```tsx
+ * // a native element: the binding carries its own eventToValue, and the
+ * // rest of the JSX is type-checked against that element's attributes
+ * <FormItem
+ *   form={form}
+ *   name='email'
+ *   input={{element: 'input', eventToValue: (e) => e.target.value}}
+ *   type='email'
+ *   placeholder='Email'
+ * />
+ *
+ * // a DOM-element-shaped component: the top-level eventToValue is the
+ * // explicit opt-in from plain-value (core) to event-emitting (raw)
+ * <FormItem
+ *   form={form}
+ *   name='email'
+ *   input={NativeInput}
+ *   eventToValue={(e) => e.target.value}
+ * />
+ * ```
+ *
  * When the field has errors, the first error's message is rendered into a
  * `<span id={errorId} role='alert'>` next to the control; with no errors
  * no extra element is rendered.
  */
-export default function FormItem<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name, TInputProps extends Record<string, any> = Record<never, never>>({ form, name, label, validate, mode, validateDebounce, delayError, rules, className, renderError, as: As, asProps, input: Input, eventToValue, valueToProps, children, ...inputProps }: FormItemProps<TValues, P, TInputProps>): import("react").JSX.Element;
+export default function FormItem<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name, TInputProps extends Record<string, any> = Record<never, never>, TRawElement extends FormItemRawElement = never>({ form, name, label, validate, mode, validateDebounce, delayError, rules, className, renderError, as: As, asProps, input: Input, eventToValue, valueToProps, children, ...inputProps }: FormItemProps<TValues, P, TInputProps, TRawElement>): import("react").JSX.Element;
 export {};

package/dist/types/form/index.d.ts

@@ -1,3 +1,3 @@
 export { default as FormItem } from './FormItem';
-export type { FieldValidator, FormItemAsProps, FormItemBinding, FormItemOwnProps, FormItemProps } from './FormItem';
+export type { FieldValidator, FormItemAsProps, FormItemBinding, FormItemOwnProps, FormItemProps, FormItemRawElement, FormItemRawElementBinding } from './FormItem';
 export type { FormInstance, PathValueOf } from 'react-f0rm';

package/dist/types/index.d.ts

@@ -182,6 +182,6 @@ export type { DiffViewerProps, DiffLine } from './components/DiffViewer';
 export { LogViewer } from './components/LogViewer';
 export type { LogViewerProps, LogEntry, LogLevel } from './components/LogViewer';
 export { FormItem } from './form';
-export type { FieldValidator, FormItemAsProps, FormItemBinding, FormItemOwnProps, FormItemProps, FormInstance, PathValueOf, } from './form';
+export type { FieldValidator, FormItemAsProps, FormItemBinding, FormItemOwnProps, FormItemProps, FormItemRawElement, FormItemRawElementBinding, FormInstance, PathValueOf, } from './form';
 export { useControl } from 'react-use-control';
 export type { Control, ControlOrValue } from 'react-use-control';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haze-ui",
-  "version": "1.16.1",
+  "version": "1.17.0",
   "type": "module",
   "description": "A React UI component library powered by react-use-control and Linaria",
   "main": "./dist/index.js",