haze-ui 1.14.0 → 1.15.0

package/README.md

@@ -154,6 +154,59 @@ 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)
+
+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:
+
+```jsx
+<FormItem
+  form={form}
+  name="email"
+  label="Email"
+  input={InputCore}
+  placeholder="you@x.dev"
+  mode="onBlur"
+  validate={(v) => (v.includes('@') ? undefined : 'must be an email')}
+/>
+
+// JSX children forward too — a SelectCore's options:
+<FormItem form={form} name="role" label="Role" input={SelectCore}>
+  <option value="admin">Admin</option>
+  <option value="viewer">Viewer</option>
+</FormItem>
+
+// checkbox-style controls keep the valueToProps adapter:
+<FormItem
+  form={form}
+  name="subscribed"
+  label="Subscribe"
+  input={CheckboxCore}
+  valueToProps={(checked) => ({ checked })}
+/>
+```
+
+`input` wires the same id/aria/`onBlur`/`onChange`/value contract as `as`
+— every haze core (`InputCore`, `TextareaCore`, `SelectCore`,
+`TagInputCore`, `CheckboxCore`, `SwitchCore`, …) speaks the plain
+`{value, onChange}` pair, so the default adapters need nothing
+(`TagInputCore`'s `onChange` already emits the next `string[]`; a
+checkbox-style core pairs with `valueToProps`). The differences from
+`as`:
+
+- Forwarded props are **type-checked against the core's own props** —
+  `input={InputCore} size="xl"` is a compile error, while `asProps` is an
+  untyped bag.
+- JSX **children** forward to the core (a `SelectCore`'s `<option>`s);
+  the render-prop children and `input` are mutually exclusive (a
+  render-prop next to `input` throws — it's a migration leftover).
+- The wiring (`id`, `aria-invalid`, `aria-describedby`, `onBlur`,
+  `onChange`, `value`/`checked`) and FormItem's own prop names are
+  **reserved**: they are excluded from the forwarded type and always win
+  at runtime. A control prop that collides with one (e.g. CheckboxCore's
+  own `label`) is unreachable through `input` — use the render-prop or
+  `as`/`asProps` for it.
+
 #### `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

@@ -6,8 +6,8 @@ import { useId as r } from "react";
 import { useField as i } from "react-f0rm";
 //#region src/lib/form/FormItem.tsx
 var a = "haze-FormItem__item", o = "haze-FormItem__labelText", s = "haze-FormItem__errorText";
-function c({ form: c, name: l, label: u, validate: d, mode: f, validateDebounce: p, delayError: m, rules: h, className: g, renderError: _, as: v, asProps: y, eventToValue: b, valueToProps: x, children: S }) {
-	let C = `haze-field-${r()}`, w = `${C}-error`, { value: T, onChange: E, onBlur: D, errors: O } = i({
+function c({ form: c, name: l, label: u, validate: d, mode: f, validateDebounce: p, delayError: m, rules: h, className: g, renderError: _, as: v, asProps: y, input: b, eventToValue: x, valueToProps: S, children: C, ...w }) {
+	let T = `haze-field-${r()}`, E = `${T}-error`, { value: D, onChange: O, onBlur: k, errors: A } = i({
 		form: c,
 		name: l,
 		validate: d,
@@ -15,37 +15,48 @@ function c({ form: c, name: l, label: u, validate: d, mode: f, validateDebounce:
 		validateDebounce: p,
 		delayError: m,
 		rules: h
-	}), k = O.length > 0, A = b ?? ((e) => e);
+	}), j = A.length > 0, M = x ?? ((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;
 	return /* @__PURE__ */ n("div", {
 		className: e([a, g]),
 		children: [
 			u !== void 0 && /* @__PURE__ */ t("label", {
-				htmlFor: C,
+				htmlFor: T,
 				className: e(o),
 				children: u
 			}),
-			v ? /* @__PURE__ */ t(v, {
-				id: C,
-				"aria-invalid": k || void 0,
-				"aria-describedby": k ? w : void 0,
-				onBlur: D,
-				onChange: (e) => E(A(e)),
+			N ? /* @__PURE__ */ t(N, {
+				...w,
+				id: T,
+				"aria-invalid": j || void 0,
+				"aria-describedby": j ? E : void 0,
+				onBlur: k,
+				onChange: (e) => O(M(e)),
+				...S ? S(D) : { value: D },
+				children: C
+			}) : v ? /* @__PURE__ */ t(v, {
+				id: T,
+				"aria-invalid": j || void 0,
+				"aria-describedby": j ? E : void 0,
+				onBlur: k,
+				onChange: (e) => O(M(e)),
 				...y,
-				...x ? x(T) : { value: T }
-			}) : S({
-				id: C,
-				errorId: w,
-				invalid: k,
-				errors: O,
-				onBlur: D,
-				value: T,
-				onChange: E
+				...S ? S(D) : { value: D }
+			}) : C({
+				id: T,
+				errorId: E,
+				invalid: j,
+				errors: A,
+				onBlur: k,
+				value: D,
+				onChange: O
 			}),
-			k && /* @__PURE__ */ t("span", {
-				id: w,
+			j && /* @__PURE__ */ t("span", {
+				id: E,
 				role: "alert",
 				className: e(s),
-				children: _ ? _(O[0].message, w) : O[0].message
+				children: _ ? _(A[0].message, E) : A[0].message
 			})
 		]
 	});

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

@@ -62,7 +62,10 @@ export type FormItemAsProps = {
      * passing `{value}`. */
     valueToProps?: (value: any) => Record<string, any>;
 };
-export type FormItemProps<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name> = {
+/** FormItem's own, non-polymorphic props — everything the item itself
+ * consumes regardless of how the control is bound (render-prop, `as`
+ * or `input`). */
+export type FormItemOwnProps<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name> = {
     form: FormInstance<TValues>;
     name: P;
     label?: ReactNode;
@@ -95,14 +98,56 @@ export type FormItemProps<TValues extends Record<string, any> = any, P extends F
     /** Custom error renderer: when provided and the field has errors, the
      * built-in error span renders `renderError(errors[0].message, errorId)`
      * instead of the bare message. The span itself — id, `role='alert'`,
-     * styling — stays FormItem's, in both the `as` and children modes. */
+     * styling — stays FormItem's, in every control-binding mode. */
     renderError?: (error: string, id: string) => ReactNode;
     className?: string;
-} & FormItemAsProps & ({
+};
+/**
+ * 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
+ * (type level) and to document that they always win (runtime level):
+ * passing one anyway is a compile error, never a silent override.
+ */
+type FormItemWiredProps = {
+    id?: unknown;
+    onBlur?: unknown;
+    onChange?: unknown;
+    /** the value channel: `value` directly, or the prop `valueToProps`
+     * derives (e.g. `checked` for CheckboxCore) — either way FormItem's */
+    value?: unknown;
+    checked?: unknown;
+    '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 & {
+    /**
+     * 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.
+     */
+    input?: ComponentType<TInputProps>;
+} & Omit<TInputProps, keyof FormItemOwnProps<TValues, P> | keyof FormItemAsProps | keyof FormItemWiredProps | 'input'> & ({
     as: ComponentType<any>;
+    input?: never;
     children?: never;
 } | {
     as?: undefined;
+    input: ComponentType<TInputProps>;
+    /** 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?: undefined;
     children: (binding: FormItemBinding<TValues, P>) => ReactNode;
 });
 /**
@@ -141,8 +186,29 @@ export type FormItemProps<TValues extends Record<string, any> = any, P extends F
  * value lands as `{value}` or, with `valueToProps`, whatever props the
  * control wants (e.g. `{checked}` for CheckboxCore).
  *
+ * The ergonomic form for haze-ui cores is `input`: the rest of the JSX
+ * props — and JSX children, e.g. a `SelectCore`'s `<option>`s — are
+ * forwarded to the component, type-checked against its own props
+ * (`input` and the render-prop children are mutually exclusive):
+ *
+ * ```tsx
+ * <FormItem
+ *   form={form}
+ *   name='email'
+ *   input={InputCore}
+ *   placeholder='Email'
+ *   mode='onBlur'
+ * />
+ * ```
+ *
+ * The same wiring as `as` applies (id, aria, onBlur, onChange, value);
+ * wired and FormItem-owned prop names are reserved — a control prop that
+ * collides (CheckboxCore's `label`) needs the render-prop or
+ * `as`/`asProps` channel.
+ *
  * 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>({ form, name, label, validate, mode, validateDebounce, delayError, rules, className, renderError, as: As, asProps, eventToValue, valueToProps, children }: FormItemProps<TValues, P>): 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>>({ 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 {};

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

@@ -1,3 +1,3 @@
 export { default as FormItem } from './FormItem';
-export type { FieldValidator, FormItemAsProps, FormItemBinding, FormItemProps } from './FormItem';
+export type { FieldValidator, FormItemAsProps, FormItemBinding, FormItemOwnProps, FormItemProps } 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, FormItemProps, FormInstance, PathValueOf, } from './form';
+export type { FieldValidator, FormItemAsProps, FormItemBinding, FormItemOwnProps, FormItemProps, 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.14.0",
+  "version": "1.15.0",
   "type": "module",
   "description": "A React UI component library powered by react-use-control and Linaria",
   "main": "./dist/index.js",