@igne-agency/react-web-ui 0.5.0 → 0.6.0

package/dist/components/text-field/text-input.d.ts

@@ -1,8 +1,9 @@
 import { type InputProps as BaseInputProps } from "@base-ui/react/input";
-import { type ComponentProps, type ReactNode } from "react";
+import { useRender } from "@base-ui/react/use-render";
+import { type ComponentProps, type ComponentPropsWithRef, type ReactElement, type ReactNode } from "react";
 import { Field, type FieldProps, type FieldState } from "../field/index.ts";
 import { InputError, type InputErrorProps, InputLabel, type InputLabelProps, InputPending, type InputPendingProps } from "../field/input-parts.tsx";
-export type TextInputRootProps = Omit<FieldProps, "label" | "description"> & Readonly<{
+export type TextInputRootProps = Omit<FieldProps, "label" | "description" | "optionalLabel"> & Readonly<{
     value: string;
     onValueChange: (value: string) => void;
     disabled?: boolean;
@@ -19,9 +20,9 @@ export type TextInputRootProps = Omit<FieldProps, "label" | "description"> & Rea
  * state onto every part.
  *
  * @example
- * <TextInput.Root value={value} onValueChange={setValue} optionalLabel="optional">…</TextInput.Root>
+ * <TextInput.Root value={value} onValueChange={setValue}>…</TextInput.Root>
  */
-declare const TextInputRoot: ({ value, onValueChange, disabled, readOnly, requiredness, optionalLabel, errors, dirty, touched, pending, maxLength, state, className, children, }: TextInputRootProps) => ReactNode;
+declare const TextInputRoot: ({ value, onValueChange, disabled, readOnly, requiredness, errors, dirty, touched, pending, maxLength, state, className, children, }: TextInputRootProps) => ReactNode;
 export type TextInputLabelProps = InputLabelProps;
 /**
  * The bordered box holding the control and its inlays.
@@ -59,61 +60,90 @@ export type TextInputInputProps = Omit<BaseInputProps, "value" | "defaultValue"
  * <TextInput.Input type="email" />
  */
 declare const TextInputInput: ({ type, className, ...props }: TextInputInputProps) => ReactNode;
-export type TextInputClearProps = Readonly<{
-    /** Accessible name and tooltip hint, such as "Clear". */
-    label: string;
-    className?: string;
-    /** The icon the button shows. */
-    children: ReactNode;
+/** The props of a button part: the button's own, but the click, which the part owns. */
+type InlayButtonProps = Omit<ComponentPropsWithRef<"button">, "onClick" | "type" | "children">;
+export type TextInputClearProps = InlayButtonProps & Readonly<{
+    /** The button to render, such as `<IconButton label="Clear"><CloseIcon /></IconButton>`. */
+    render: useRender.RenderProp;
+}>;
+/**
+ * The button that empties the control, shown once it holds a value. It renders
+ * whichever button it is given.
+ *
+ * @example
+ * <TextInput.Clear render={<IconButton label="Clear" variant="tertiary" size="sm"><CloseIcon /></IconButton>} />
+ */
+declare const TextInputClear: ({ render, className, ...props }: TextInputClearProps) => ReactNode;
+export type TextInputActionProps = Omit<ComponentPropsWithRef<"button">, "children"> & Readonly<{
+    /** The button to render, such as `<Button variant="tertiary" size="sm">Search</Button>`. */
+    render: useRender.RenderProp;
 }>;
 /**
- * The icon-only button that empties the control, shown once it holds a value.
+ * Any button inside the group, in the place an inlay that acts takes, such as
+ * a search field's trailing "Search" button. It renders whichever button it is
+ * given, disabled while the field is.
  *
  * @example
- * <TextInput.Clear label="Clear"><CloseIcon /></TextInput.Clear>
+ * <TextInput.Action render={<Button variant="tertiary" size="sm" type="submit">Search</Button>} />
  */
-declare const TextInputClear: ({ label, className, children, }: TextInputClearProps) => ReactNode;
-export type TextInputCopyProps = Readonly<{
-    /** Accessible name and tooltip hint, such as "Copy". */
-    label: string;
-    /** Accessible name and announcement while the confirmation shows, such as "Copied". */
+declare const TextInputAction: ({ render, className, ...props }: TextInputActionProps) => ReactElement;
+/** Where a copy stands: not tried, landed, or refused and selected instead. */
+export type TextInputCopyOutcome = "idle" | "copied" | "failed";
+/** The state a `Copy` part renders from, also set as `data-outcome`. */
+export type TextInputCopyState = Readonly<{
+    outcome: TextInputCopyOutcome;
+}>;
+export type TextInputCopyProps = InlayButtonProps & Readonly<{
+    /** Announced once the value is on the clipboard, such as "Copied". */
     copiedLabel: string;
-    /** Accessible name and announcement once copying failed and the text is selected instead. */
+    /** Announced once copying failed and the text is selected instead. */
     failedLabel: string;
-    /** The icon while the confirmation shows. Left out, the button keeps its own. */
-    copiedIcon?: ReactNode;
-    /** The icon once copying failed. Left out, the button keeps its own. */
-    failedIcon?: ReactNode;
-    className?: string;
-    /** The icon the button shows. */
-    children: ReactNode;
+    /** The button to render, or a function of the copy's state that returns one. */
+    render: useRender.RenderProp<TextInputCopyState>;
 }>;
 /**
- * The icon-only button that copies the value to the clipboard, shown once it
- * holds one, and announces whether the copy landed.
+ * The button that copies the value to the clipboard, shown once it holds one,
+ * and announces whether the copy landed. It renders whichever button it is
+ * given, and a render function can follow the outcome.
  *
  * @example
- * <TextInput.Copy label="Copy" copiedLabel="Copied" failedLabel="Copy failed, text selected"><CopyIcon /></TextInput.Copy>
+ * <TextInput.Copy
+ * 	copiedLabel="Copied"
+ * 	failedLabel="Copy failed, text selected"
+ * 	render={(props, { outcome }) => (
+ * 		<IconButton {...props} label="Copy" variant="tertiary" size="sm">
+ * 			{outcome === "copied" ? <CheckIcon /> : <CopyIcon />}
+ * 		</IconButton>
+ * 	)}
+ * />
  */
-declare const TextInputCopy: ({ label, copiedLabel, failedLabel, copiedIcon, failedIcon, className, children, }: TextInputCopyProps) => ReactNode;
-export type TextInputRevealProps = Readonly<{
+declare const TextInputCopy: ({ copiedLabel, failedLabel, render, className, ...props }: TextInputCopyProps) => ReactNode;
+/** The state a `Reveal` part renders from, also set as `data-revealed`. */
+export type TextInputRevealState = Readonly<{
+    revealed: boolean;
+}>;
+export type TextInputRevealProps = InlayButtonProps & Readonly<{
     /** Whether the concealed value shows as text. */
     revealed: boolean;
     onRevealedChange: (revealed: boolean) => void;
-    /** Accessible name and tooltip hint, such as "Show password". */
-    label: string;
-    className?: string;
-    /** The icon the button shows. */
-    children: ReactNode;
+    /** The button to render, or a function of `revealed` that returns one. */
+    render: useRender.RenderProp<TextInputRevealState>;
 }>;
 /**
- * The icon-only toggle that shows a concealed value, such as a password, as
- * text. The caller switches the `Input`'s `type` with `revealed`.
+ * The toggle that shows a concealed value, such as a password, as text. The
+ * caller switches the `Input`'s `type` with `revealed`, and names the button for
+ * what a press will do.
  *
  * @example
- * <TextInput.Reveal revealed={revealed} onRevealedChange={setRevealed} label="Show password"><VisibilityIcon /></TextInput.Reveal>
+ * <TextInput.Reveal
+ * 	revealed={revealed}
+ * 	onRevealedChange={setRevealed}
+ * 	render={
+ * 		<Button variant="tertiary" size="sm">{revealed ? "Hide" : "Show"}</Button>
+ * 	}
+ * />
  */
-declare const TextInputReveal: ({ revealed, onRevealedChange, label, className, children, }: TextInputRevealProps) => ReactNode;
+declare const TextInputReveal: ({ revealed, onRevealedChange, render, className, ...props }: TextInputRevealProps) => ReactNode;
 /**
  * The value's length against `Root`'s `maxLength`, toned as it nears the limit.
  * Renders nothing without a `maxLength`.
@@ -133,6 +163,7 @@ export type TextInputParts = Readonly<{
     Inlay: typeof TextInputInlay;
     Affix: typeof TextInputAffix;
     Input: typeof TextInputInput;
+    Action: typeof TextInputAction;
     Clear: typeof TextInputClear;
     Copy: typeof TextInputCopy;
     Reveal: typeof TextInputReveal;
@@ -144,19 +175,24 @@ export type TextInputParts = Readonly<{
 /**
  * The parts of a text input: the field frame, a group carrying the border and
  * its inlays, and the bare control inside it. A `Bar` is a strip of inlays along
- * the bottom edge of the group, for a control the inlays cannot sit beside. For
+ * the bottom edge of the group, for a control the inlays cannot sit beside, and
+ * an `Action` is any button placed in the group. For
  * the ordinary case, use the `TextField` shorthand, which is assembled from
  * exactly these parts. An `Affix` is decoration, so its meaning belongs in the
  * label or description too. `Error` renders the errors `Root` was given.
  *
  * @example
- * <TextInput.Root value={value} onValueChange={setValue} errors={errors} optionalLabel="optional">
- * 	<TextInput.Label>Email</TextInput.Label>
+ * <TextInput.Root value={value} onValueChange={setValue} errors={errors} requiredness="optional">
+ * 	<TextInput.Label>Email <Field.Requiredness optionalLabel="optional" /></TextInput.Label>
  * 	<TextInput.Group>
  * 		<TextInput.Input type="email" />
- * 		<TextInput.Clear label="Clear">
- * 			<CloseIcon />
- * 		</TextInput.Clear>
+ * 		<TextInput.Clear
+ * 			render={
+ * 				<IconButton label="Clear" variant="tertiary" size="sm">
+ * 					<CloseIcon />
+ * 				</IconButton>
+ * 			}
+ * 		/>
  * 	</TextInput.Group>
  * 	<TextInput.Error />
  * </TextInput.Root>