@openzeppelin/ui-components 3.0.1 → 3.1.0

package/dist/index.cjs

@@ -38,7 +38,7 @@ let sonner = require("sonner");
 let next_themes = require("next-themes");
 
 //#region src/version.ts
-const VERSION = "3.0.1";
+const VERSION = "3.1.0";
 
 //#endregion
 //#region src/components/ui/accordion.tsx
@@ -2952,6 +2952,312 @@ function AddressField({ id, label, placeholder, helperText, control, name, width
 }
 AddressField.displayName = "AddressField";
 
+//#endregion
+//#region src/components/fields/TextAreaField.tsx
+/**
+* Multi-line text input field component specifically designed for React Hook Form integration.
+*
+* Architecture flow:
+* 1. Form schemas are generated from contract functions using adapters
+* 2. TransactionForm renders the overall form structure with React Hook Form
+* 3. DynamicFormField selects the appropriate field component based on field type
+* 4. BaseField provides consistent layout and hook form integration
+* 5. This component handles textarea-specific rendering and validation
+*
+* The component includes:
+* - Integration with React Hook Form
+* - Resizable multi-line text input
+* - Character limit support
+* - Customizable validation through adapter integration
+* - Automatic error handling and reporting
+* - Full accessibility support with ARIA attributes
+* - Keyboard navigation with Escape to clear
+*/
+function TextAreaField({ id, label, placeholder, helperText, control, name, width = "full", validation, rows = 4, maxLength, validateTextArea, readOnly }) {
+	const isRequired = !!validation?.required;
+	const errorId = `${id}-error`;
+	const descriptionId = `${id}-description`;
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: `flex flex-col gap-2 ${width === "full" ? "w-full" : width === "half" ? "w-1/2" : "w-1/3"}`,
+		children: [label && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(Label, {
+			htmlFor: id,
+			children: [
+				label,
+				" ",
+				isRequired && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					className: "text-destructive",
+					children: "*"
+				})
+			]
+		}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_hook_form.Controller, {
+			control,
+			name,
+			rules: { validate: (value) => {
+				if (value === void 0 || value === null || value === "") return validation?.required ? "This field is required" : true;
+				if (validateTextArea && value) {
+					const validation$1 = validateTextArea(value);
+					if (validation$1 !== true && typeof validation$1 === "string") return validation$1;
+				}
+				if (maxLength && typeof value === "string" && value.length > maxLength) return `Maximum length is ${maxLength} characters`;
+				return true;
+			} },
+			disabled: readOnly,
+			render: ({ field, fieldState: { error, isTouched } }) => {
+				const hasError = !!error;
+				const shouldShowError = hasError && isTouched;
+				const validationClasses = require_ErrorMessage.getValidationStateClasses(error, isTouched);
+				const accessibilityProps = getAccessibilityProps({
+					id,
+					hasError,
+					isRequired,
+					hasHelperText: !!helperText
+				});
+				return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Textarea, {
+						...field,
+						id,
+						placeholder,
+						rows,
+						maxLength,
+						className: validationClasses,
+						value: field.value ?? "",
+						disabled: readOnly,
+						...accessibilityProps,
+						"aria-describedby": `${helperText ? descriptionId : ""} ${hasError ? errorId : ""}`,
+						onKeyDown: handleEscapeKey((value) => {
+							if (typeof field.onChange === "function") field.onChange(value);
+						}, field.value)
+					}),
+					maxLength && typeof field.value === "string" && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "text-muted-foreground text-right text-xs",
+						children: [
+							field.value.length,
+							"/",
+							maxLength
+						]
+					}),
+					helperText && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						id: descriptionId,
+						className: "text-muted-foreground text-sm",
+						children: helperText
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_ErrorMessage.ErrorMessage, {
+						error,
+						id: errorId,
+						message: shouldShowError ? error?.message : void 0
+					})
+				] });
+			}
+		})]
+	});
+}
+TextAreaField.displayName = "TextAreaField";
+
+//#endregion
+//#region src/components/fields/AddressListField/labels.ts
+/** Default English labels for {@link AddressListField}. */
+const DEFAULT_ADDRESS_LIST_FIELD_LABELS = {
+	addAddresses: "Add addresses",
+	addAddressCount: (count) => `Add ${count} address${count === 1 ? "" : "es"}`,
+	invalidPrefix: "Invalid:",
+	invalidMore: (extraCount) => `(+${extraCount} more)`,
+	maxItemsReached: (maxItems) => `Maximum of ${maxItems} addresses reached.`,
+	addressesAdded: (count) => `${count} address${count === 1 ? "" : "es"} added`,
+	removeAddress: (index) => `Remove address ${index + 1}`,
+	previewReadyToAdd: (count) => `${count} ready to add`,
+	previewInvalid: (count) => `${count} invalid`,
+	previewAlreadyListed: (count) => `${count} already listed`,
+	previewDuplicateInPaste: (count) => `${count} duplicate in paste`,
+	bulkNothingAdded: "No addresses were added. Check formatting and try again.",
+	bulkAdded: (count) => `Added ${count} address${count === 1 ? "" : "es"}`,
+	bulkInvalidFormats: (count) => `${count} invalid format${count === 1 ? "" : "s"}`,
+	bulkAlreadyListed: (count) => `${count} already listed`,
+	bulkDuplicatesInPaste: (count) => `${count} duplicate${count === 1 ? "" : "s"} in paste`
+};
+/** Merges {@link DEFAULT_ADDRESS_LIST_FIELD_LABELS} with optional overrides. */
+function resolveAddressListFieldLabels(overrides) {
+	return {
+		...DEFAULT_ADDRESS_LIST_FIELD_LABELS,
+		...overrides
+	};
+}
+/** Builds the inline helper preview shown while the user types in the draft textarea. */
+function buildAddressListPreviewSummary(classification, labels) {
+	if (!classification) return null;
+	const skipped = classification.invalid.length + classification.alreadyListed.length + classification.duplicatesInInput.length;
+	if (classification.accepted.length === 0 && skipped === 0) return null;
+	const parts = [];
+	if (classification.accepted.length > 0) parts.push(labels.previewReadyToAdd(classification.accepted.length));
+	if (classification.invalid.length > 0) parts.push(labels.previewInvalid(classification.invalid.length));
+	if (classification.alreadyListed.length > 0) parts.push(labels.previewAlreadyListed(classification.alreadyListed.length));
+	if (classification.duplicatesInInput.length > 0) parts.push(labels.previewDuplicateInPaste(classification.duplicatesInInput.length));
+	return parts.join(" · ");
+}
+/** Formats post-add feedback after the user commits parsed addresses to the list. */
+function formatAddressBulkSummary(classification, addedCount, labels) {
+	if (addedCount === 0 && classification.accepted.length === 0) {
+		if (classification.invalid.length + classification.alreadyListed.length + classification.duplicatesInInput.length === 0) return null;
+		return labels.bulkNothingAdded;
+	}
+	const parts = [];
+	if (addedCount > 0) parts.push(labels.bulkAdded(addedCount));
+	if (classification.invalid.length > 0) parts.push(labels.bulkInvalidFormats(classification.invalid.length));
+	if (classification.alreadyListed.length > 0) parts.push(labels.bulkAlreadyListed(classification.alreadyListed.length));
+	if (classification.duplicatesInInput.length > 0) parts.push(labels.bulkDuplicatesInPaste(classification.duplicatesInInput.length));
+	if (parts.length === 0) return null;
+	return parts.join(". ") + ".";
+}
+
+//#endregion
+//#region src/components/fields/AddressListField/AddressListField.tsx
+/**
+* Multi-address list field for bulk paste workflows.
+*
+* Architecture flow:
+* 1. App or wizard steps hold the committed address list in local or form state
+* 2. AddressListField renders a draft textarea plus the committed list rows
+* 3. Parsing and classification run via `@openzeppelin/ui-utils` helpers
+* 4. Optional {@link AddressingCapability} validates candidates before add
+* 5. {@link AddressDisplay} renders each committed row with copy and explorer links
+*
+* The component includes:
+* - Delimiter-aware bulk paste (newlines, commas, semicolons)
+* - Live preview of accepted, invalid, duplicate, and already-listed candidates
+* - Optional `maxItems` cap with disabled input at the limit
+* - Removable list rows with accessible remove buttons
+* - Caller-controlled copy for placeholders and format hints
+* - Optional `labels` overrides for built-in button and status strings
+*
+* @example
+* ```tsx
+* const [addresses, setAddresses] = useState<string[]>([]);
+*
+* <AddressListField
+*   value={addresses}
+*   onChange={setAddresses}
+*   placeholder="Paste addresses (one per line or comma-separated)"
+*   formatHint="Each entry is validated before it is added."
+*   addressing={capabilities}
+* />
+* ```
+*/
+function AddressListField({ value, onChange, placeholder, formatHint, addressing, getExplorerUrl, label, helperText, maxItems, disabled = false, maxInvalidPreview = 3, className, labels: labelOverrides }) {
+	const fieldId = (0, react.useId)();
+	const labels = (0, react.useMemo)(() => resolveAddressListFieldLabels(labelOverrides), [labelOverrides]);
+	const atLimit = maxItems != null && value.length >= maxItems;
+	const inputDisabled = disabled || atLimit;
+	const [feedback, setFeedback] = (0, react.useState)(null);
+	const { control, reset, watch } = (0, react_hook_form.useForm)({
+		defaultValues: { input: "" },
+		mode: "onChange"
+	});
+	const rawInput = watch("input");
+	const classification = (0, react.useMemo)(() => {
+		if (!rawInput.trim()) return null;
+		return (0, _openzeppelin_ui_utils.classifyAddressCandidates)((0, _openzeppelin_ui_utils.parseDelimitedAddressInput)(rawInput), value, addressing, maxItems);
+	}, [
+		rawInput,
+		value,
+		addressing,
+		maxItems
+	]);
+	const previewSummary = (0, react.useMemo)(() => buildAddressListPreviewSummary(classification, labels), [classification, labels]);
+	const inlineHelperText = rawInput.trim() ? previewSummary ?? void 0 : feedback ?? void 0;
+	const handleAdd = (0, react.useCallback)(() => {
+		if (!classification || classification.accepted.length === 0 || atLimit) return;
+		onChange([...value, ...classification.accepted]);
+		reset({ input: "" });
+		setFeedback(formatAddressBulkSummary(classification, classification.accepted.length, labels));
+	}, [
+		classification,
+		atLimit,
+		onChange,
+		value,
+		reset,
+		labels
+	]);
+	const handleRemove = (0, react.useCallback)((index) => {
+		onChange(value.filter((_, currentIndex) => currentIndex !== index));
+		setFeedback(null);
+	}, [onChange, value]);
+	const acceptedCount = classification?.accepted.length ?? 0;
+	const addButtonLabel = acceptedCount > 0 ? labels.addAddressCount(acceptedCount) : labels.addAddresses;
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: (0, _openzeppelin_ui_utils.cn)("space-y-3", className),
+		children: [
+			/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: "space-y-1",
+				children: [helperText ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+					className: "text-xs text-muted-foreground",
+					children: helperText
+				}) : null, /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+					className: "text-xs text-muted-foreground",
+					children: formatHint
+				})]
+			}),
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)(TextAreaField, {
+				id: `address-list-field-${fieldId}`,
+				name: "input",
+				label: label ?? "",
+				placeholder,
+				helperText: inlineHelperText,
+				control,
+				rows: 4,
+				validation: { required: false },
+				readOnly: inputDisabled
+			}),
+			classification && classification.invalid.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("p", {
+				className: "text-xs text-destructive",
+				children: [
+					labels.invalidPrefix,
+					" ",
+					classification.invalid.slice(0, maxInvalidPreview).join(", "),
+					classification.invalid.length > maxInvalidPreview ? ` ${labels.invalidMore(classification.invalid.length - maxInvalidPreview)}` : ""
+				]
+			}),
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Button, {
+				type: "button",
+				size: "sm",
+				disabled: inputDisabled || acceptedCount === 0,
+				onClick: () => handleAdd(),
+				children: addButtonLabel
+			}),
+			atLimit && maxItems != null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+				className: "text-xs text-muted-foreground",
+				children: labels.maxItemsReached(maxItems)
+			}),
+			value.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: "space-y-1",
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+					className: "text-xs text-muted-foreground",
+					children: labels.addressesAdded(value.length)
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					className: "max-h-44 space-y-1 overflow-y-auto rounded-md border border-border/70 p-1",
+					children: value.map((address, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "flex items-center justify-between rounded bg-muted p-2",
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(AddressDisplay, {
+							address,
+							variant: "inline",
+							truncateWhenLabeled: true,
+							showCopyButton: true,
+							explorerUrl: getExplorerUrl?.(address) ?? void 0
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Button, {
+							type: "button",
+							variant: "ghost",
+							size: "sm",
+							className: "size-7 shrink-0 p-0 text-muted-foreground hover:text-destructive",
+							onClick: () => handleRemove(index),
+							disabled,
+							"aria-label": labels.removeAddress(index),
+							children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.X, { className: "size-3.5" })
+						})]
+					}, `${address}-${index}`))
+				})]
+			})
+		]
+	});
+}
+
 //#endregion
 //#region src/components/fields/address-suggestion/address-suggestion-context.tsx
 /**
@@ -5744,105 +6050,6 @@ function SelectGroupedField({ id, label, placeholder = "Select an option", helpe
 }
 SelectGroupedField.displayName = "SelectGroupedField";
 
-//#endregion
-//#region src/components/fields/TextAreaField.tsx
-/**
-* Multi-line text input field component specifically designed for React Hook Form integration.
-*
-* Architecture flow:
-* 1. Form schemas are generated from contract functions using adapters
-* 2. TransactionForm renders the overall form structure with React Hook Form
-* 3. DynamicFormField selects the appropriate field component based on field type
-* 4. BaseField provides consistent layout and hook form integration
-* 5. This component handles textarea-specific rendering and validation
-*
-* The component includes:
-* - Integration with React Hook Form
-* - Resizable multi-line text input
-* - Character limit support
-* - Customizable validation through adapter integration
-* - Automatic error handling and reporting
-* - Full accessibility support with ARIA attributes
-* - Keyboard navigation with Escape to clear
-*/
-function TextAreaField({ id, label, placeholder, helperText, control, name, width = "full", validation, rows = 4, maxLength, validateTextArea }) {
-	const isRequired = !!validation?.required;
-	const errorId = `${id}-error`;
-	const descriptionId = `${id}-description`;
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-		className: `flex flex-col gap-2 ${width === "full" ? "w-full" : width === "half" ? "w-1/2" : "w-1/3"}`,
-		children: [label && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(Label, {
-			htmlFor: id,
-			children: [
-				label,
-				" ",
-				isRequired && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-					className: "text-destructive",
-					children: "*"
-				})
-			]
-		}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_hook_form.Controller, {
-			control,
-			name,
-			rules: { validate: (value) => {
-				if (value === void 0 || value === null || value === "") return validation?.required ? "This field is required" : true;
-				if (validateTextArea && value) {
-					const validation$1 = validateTextArea(value);
-					if (validation$1 !== true && typeof validation$1 === "string") return validation$1;
-				}
-				if (maxLength && typeof value === "string" && value.length > maxLength) return `Maximum length is ${maxLength} characters`;
-				return true;
-			} },
-			render: ({ field, fieldState: { error, isTouched } }) => {
-				const hasError = !!error;
-				const shouldShowError = hasError && isTouched;
-				const validationClasses = require_ErrorMessage.getValidationStateClasses(error, isTouched);
-				const accessibilityProps = getAccessibilityProps({
-					id,
-					hasError,
-					isRequired,
-					hasHelperText: !!helperText
-				});
-				return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
-					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Textarea, {
-						...field,
-						id,
-						placeholder,
-						rows,
-						maxLength,
-						className: validationClasses,
-						value: field.value ?? "",
-						...accessibilityProps,
-						"aria-describedby": `${helperText ? descriptionId : ""} ${hasError ? errorId : ""}`,
-						onKeyDown: handleEscapeKey((value) => {
-							if (typeof field.onChange === "function") field.onChange(value);
-						}, field.value)
-					}),
-					maxLength && typeof field.value === "string" && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-						className: "text-muted-foreground text-right text-xs",
-						children: [
-							field.value.length,
-							"/",
-							maxLength
-						]
-					}),
-					helperText && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-						id: descriptionId,
-						className: "text-muted-foreground text-sm",
-						children: helperText
-					}),
-					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_ErrorMessage.ErrorMessage, {
-						error,
-						id: errorId,
-						message: shouldShowError ? error?.message : void 0
-					})
-				] });
-			}
-		})]
-	});
-}
-TextAreaField.displayName = "TextAreaField";
-
 //#endregion
 //#region src/components/fields/TextField.tsx
 /**
@@ -6441,6 +6648,7 @@ exports.AccordionTrigger = AccordionTrigger;
 exports.AddressDisplay = AddressDisplay;
 exports.AddressField = AddressField;
 exports.AddressLabelProvider = AddressLabelProvider;
+exports.AddressListField = AddressListField;
 exports.AddressSuggestionProvider = AddressSuggestionProvider;
 exports.Alert = Alert;
 exports.AlertDescription = AlertDescription;
@@ -6462,6 +6670,7 @@ exports.CardFooter = CardFooter;
 exports.CardHeader = CardHeader;
 exports.CardTitle = CardTitle;
 exports.Checkbox = Checkbox;
+exports.DEFAULT_ADDRESS_LIST_FIELD_LABELS = DEFAULT_ADDRESS_LIST_FIELD_LABELS;
 exports.DateRangePicker = DateRangePicker;
 exports.DateTimeField = DateTimeField;
 exports.Dialog = Dialog;
@@ -6567,10 +6776,12 @@ exports.ViewContractStateButton = ViewContractStateButton;
 exports.WizardLayout = WizardLayout;
 exports.WizardNavigation = WizardNavigation;
 exports.WizardStepper = WizardStepper;
+exports.buildAddressListPreviewSummary = buildAddressListPreviewSummary;
 exports.buttonVariants = buttonVariants;
 exports.computeChildTouched = computeChildTouched;
 exports.createFocusManager = createFocusManager;
 exports.createValidationResult = require_ErrorMessage.createValidationResult;
+exports.formatAddressBulkSummary = formatAddressBulkSummary;
 exports.formatValidationError = require_ErrorMessage.formatValidationError;
 exports.getAccessibilityProps = getAccessibilityProps;
 exports.getDescribedById = getDescribedById;
@@ -6584,6 +6795,7 @@ exports.handleToggleKeys = handleToggleKeys;
 exports.handleValidationError = require_ErrorMessage.handleValidationError;
 exports.hasFieldError = require_ErrorMessage.hasFieldError;
 exports.isDuplicateMapKey = require_ErrorMessage.isDuplicateMapKey;
+exports.resolveAddressListFieldLabels = resolveAddressListFieldLabels;
 exports.useAddressLabel = useAddressLabel;
 exports.useAddressSuggestions = useAddressSuggestions;
 exports.useDuplicateKeyIndexes = useDuplicateKeyIndexes;