@payfit/unity-components 3.1.14 → 3.1.16

package/dist/esm/modules/tanstack-form/components/inline-field/parts/InlineFieldEditView.d.ts

@@ -0,0 +1,106 @@
+import { ReactNode } from 'react';
+export interface InlineFieldEditViewProps {
+    /**
+     * The form field to display in edit mode.
+     */
+    children?: ReactNode;
+    /**
+     * Optional callback fired when the cancel button is clicked.
+     * This is called before canceling and is useful for analytics or side effects.
+     * The form will be reset and edit mode exited automatically.
+     */
+    onCancel?: () => void;
+    /**
+     * Optional callback fired when the save button is clicked.
+     * This is called before form submission and is useful for analytics or side effects.
+     * Note: Form submission is handled via the form's onSubmit configuration.
+     */
+    onSave?: () => void;
+    /**
+     * Custom label for the save button.
+     * @default "Save" (translated)
+     */
+    saveLabel?: string;
+    /**
+     * Custom label for the cancel button.
+     * @default "Cancel" (translated)
+     */
+    cancelLabel?: string;
+    /**
+     * Helper text to display below the field.
+     * Useful for providing additional context or instructions.
+     */
+    helperText?: ReactNode;
+    /**
+     * Error message to announce when save or validation fails.
+     * If not provided, generic validation errors are announced.
+     */
+    errorMessage?: string;
+}
+/**
+ * InlineFieldEditView displays form fields only when the parent InlineField is in edit mode.
+ * Wrap form field components in this component to show them when editing.
+ * The component integrates with TanStack Form for validation and state management,
+ * automatically handling form submission, cancellation, and validation errors.
+ * It includes save and cancel icon buttons, keyboard navigation (Escape to cancel),
+ * and accessibility announcements via live regions.
+ * @example Basic usage with a text field
+ * ```tsx
+ * import { useTanstackUnityForm } from '@payfit/unity-components'
+ *
+ * function Example() {
+ *   const form = useTanstackUnityForm({
+ *     defaultValues: { email: 'john@example.com' }
+ *   })
+ *
+ *   return (
+ *     <form.AppForm>
+ *       <form.AppField name="email">
+ *         {field => (
+ *           <field.InlineField>
+ *             <field.InlineFieldReadView>
+ *               <div className="flex items-center gap-2">
+ *                 <Text>{form.state.values.email}</Text>
+ *                 <field.InlineFieldEditTrigger />
+ *               </div>
+ *             </field.InlineFieldReadView>
+ *             <field.InlineFieldEditView>
+ *               <field.TextField label="Email" isRequired />
+ *             </field.InlineFieldEditView>
+ *           </field.InlineField>
+ *         )}
+ *       </form.AppField>
+ *     </form.AppForm>
+ *   )
+ * }
+ * ```
+ * @example With custom messages and callbacks
+ * ```tsx
+ * <field.InlineFieldEditView
+ *   successMessage="Email updated successfully!"
+ *   errorMessage="Failed to update email. Please try again."
+ *   helperText="Enter a valid email address"
+ *   onSave={() => trackAnalytics('email_save_clicked')}
+ *   onCancel={() => trackAnalytics('email_edit_cancelled')}
+ * >
+ *   <field.TextField label="Email" isRequired />
+ * </field.InlineFieldEditView>
+ * ```
+ * @remarks
+ * - Must be used as a child of InlineField
+ * - Automatically exits edit mode on successful form submission
+ * - Press Escape to cancel editing and reset form values
+ * - Focus is retained within the edit view (FocusScope) while editing
+ * - The save button is disabled until the form has changes (isDirty)
+ * - Validation errors are announced via screen reader live regions
+ * - Content remains in the DOM but is hidden with `hidden`, `aria-hidden`, and `inert` attributes in read mode
+ * @see {@link InlineFieldEditViewProps} for all available props
+ * @see {@link InlineField} for the parent container component
+ * @see {@link InlineFieldReadView} for the corresponding read mode component
+ * @see Source code in {@link https://github.com/PayFit/hr-apps/tree/master/libs/shared/unity/components/src/core/components/inline-field GitHub}
+ * @see Developer docs in {@link https://unity-components.payfit.io/?path=/docs/forms-reference-inlinefield--docs unity-components.payfit.io}
+ */
+export declare function InlineFieldEditView({ children, onCancel, onSave, saveLabel, cancelLabel, helperText, errorMessage, }: InlineFieldEditViewProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace InlineFieldEditView {
+    var displayName: string;
+}

package/dist/esm/modules/tanstack-form/components/inline-field/parts/InlineFieldEditView.js

@@ -0,0 +1,117 @@
+import { CircularIconButton as e } from "../../../../../core/components/icon-button/CircularIconButton.js";
+import { useFormContext as t } from "../../../hooks/tanstack-form-context.js";
+import { TanstackFormFeedbackText as n } from "../../form-field/parts/TanstackFormFeedbackText.js";
+import { TanstackFormField as r } from "../../form-field/TanstackFormField.js";
+import { TanstackFormHelperText as i } from "../../form-field/parts/TanstackFormHelperText.js";
+import { useInlineField as a } from "../InlineField.context.js";
+import { useCallback as o, useEffect as s, useRef as c, useState as l } from "react";
+import { uyTv as u } from "@payfit/unity-themes";
+import { jsx as d, jsxs as f } from "react/jsx-runtime";
+import { Group as p } from "react-aria-components/Group";
+import { useIntl as m } from "react-intl";
+import { FocusScope as h } from "react-aria/FocusScope";
+import { useSelector as g } from "@tanstack/react-store";
+import { useKeyboard as _ } from "react-aria/useKeyboard";
+//#region src/modules/tanstack-form/components/inline-field/parts/InlineFieldEditView.tsx
+var v = u({ slots: { base: "uy:flex uy:flex-row uy:gap-100 uy:items-start" } });
+function y({ children: u, onCancel: y, onSave: b, saveLabel: x, cancelLabel: S, helperText: C, errorMessage: w }) {
+	let T = a(), E = m(), D = t(), { isDirty: O, isSubmitting: k, submissionAttempts: A, isValid: j, isSubmitSuccessful: M } = g(D.store, (e) => ({
+		isDirty: e.isDirty,
+		isSubmitting: e.isSubmitting,
+		isValid: e.isValid,
+		isSubmitSuccessful: e.isSubmitSuccessful,
+		submissionAttempts: e.submissionAttempts
+	})), N = c(k), P = c(A), [F, I] = l(""), L = T?.mode === "edit";
+	s(() => {
+		k && !N.current && I("");
+	}, [k]), s(() => {
+		N.current && !k && M && T?.exitEditMode();
+	}, [
+		k,
+		M,
+		T
+	]), s(() => {
+		if (N.current && !k && !M && j) {
+			let e = w ?? E.formatMessage({
+				id: "unity:component:inline-field:save-error",
+				defaultMessage: "An error occurred while saving. Please try again."
+			});
+			I(e);
+		}
+	}, [
+		k,
+		M,
+		j,
+		w,
+		E
+	]), s(() => {
+		N.current = k, P.current = A;
+	}, [k, A]);
+	let { base: R } = v(), z = o((e) => {
+		e.preventDefault(), e.stopPropagation(), D.handleSubmit();
+	}, [D]), B = o(() => {
+		D.reset(), T?.exitEditMode(), I("");
+	}, [D, T]), { keyboardProps: V } = _({ onKeyDown: (e) => {
+		e.key === "Escape" && T?.mode === "edit" && (e.preventDefault(), y?.(), B());
+	} });
+	return /* @__PURE__ */ f("div", {
+		className: R(),
+		ref: T?.editViewRef,
+		hidden: !L,
+		"aria-hidden": !L,
+		...!L && { inert: "" },
+		children: [/* @__PURE__ */ d(h, {
+			contain: !0,
+			restoreFocus: !0,
+			children: /* @__PURE__ */ d("form", {
+				...V,
+				className: "uy:flex uy:flex-1 uy:min-w-0",
+				onSubmit: z,
+				id: T?.editViewId,
+				children: /* @__PURE__ */ f(r, { children: [
+					C && /* @__PURE__ */ d(i, { children: C }),
+					/* @__PURE__ */ f("div", {
+						className: "uy:flex",
+						children: [u, /* @__PURE__ */ f(p, {
+							className: "uy:flex uy:gap-50 uy:items-center uy:ml-100",
+							"aria-busy": T?.isLoading,
+							children: [/* @__PURE__ */ d(e, {
+								asElement: "button",
+								icon: "CloseOutlined",
+								onPress: () => {
+									y?.(), B();
+								},
+								isDisabled: T?.isLoading,
+								title: S ?? E.formatMessage({
+									id: "unity:component:inline-field:cancel",
+									defaultMessage: "Cancel"
+								})
+							}), /* @__PURE__ */ d(e, {
+								asElement: "button",
+								icon: "CheckOutlined",
+								type: "submit",
+								isLoading: T?.isLoading || k,
+								isDisabled: !O || T?.isLoading || k,
+								title: x ?? E.formatMessage({
+									id: "unity:component:inline-field:save",
+									defaultMessage: "Save"
+								}),
+								onPress: b
+							})]
+						})]
+					}),
+					/* @__PURE__ */ d(n, {})
+				] })
+			})
+		}), /* @__PURE__ */ d("div", {
+			role: "alert",
+			"aria-live": "assertive",
+			"aria-atomic": "true",
+			className: "uy:sr-only",
+			children: F
+		})]
+	});
+}
+y.displayName = "InlineFieldEditView";
+//#endregion
+export { y as InlineFieldEditView };

package/dist/esm/modules/tanstack-form/components/inline-field/parts/InlineFieldReadView.d.ts

@@ -0,0 +1,75 @@
+import { ReactNode } from 'react';
+export interface InlineFieldReadViewProps {
+    /**
+     * Content to display in read mode.
+     * Typically includes the read-only value and an InlineFieldEditTrigger.
+     */
+    children: ReactNode;
+    /**
+     * Success message to announce when save succeeds.
+     * If not provided, no success announcement is made.
+     */
+    successMessage?: string;
+}
+/**
+ * InlineFieldReadView displays content only when the parent InlineField is in read mode.
+ * Wrap read-only content and the edit trigger button in this component.
+ * The component automatically hides its content when the parent switches to edit mode,
+ * using semantic HTML attributes for accessibility.
+ * @example Basic usage with read-only value
+ * ```tsx
+ * import { useTanstackUnityForm } from '@payfit/unity-components'
+ *
+ * function Example() {
+ *   const form = useTanstackUnityForm({
+ *     defaultValues: { email: 'john@example.com' }
+ *   })
+ *
+ *   return (
+ *     <form.AppForm>
+ *       <form.AppField name="email">
+ *         {field => (
+ *           <field.InlineField>
+ *             <field.InlineFieldReadView>
+ *               <div className="flex items-center gap-2">
+ *                 <Text>{form.state.values.email}</Text>
+ *                 <field.InlineFieldEditTrigger />
+ *               </div>
+ *             </field.InlineFieldReadView>
+ *             <field.InlineFieldEditView>
+ *               <field.TextField label="Email" />
+ *             </field.InlineFieldEditView>
+ *           </field.InlineField>
+ *         )}
+ *       </form.AppField>
+ *     </form.AppForm>
+ *   )
+ * }
+ * ```
+ * @example With formatted display
+ * ```tsx
+ * <field.InlineFieldReadView>
+ *   <div className="flex items-center justify-between">
+ *     <div>
+ *       <Label>Email</Label>
+ *       <Text>{form.state.values.email}</Text>
+ *     </div>
+ *     <field.InlineFieldEditTrigger />
+ *   </div>
+ * </field.InlineFieldReadView>
+ * ```
+ * @remarks
+ * - Must be used as a child of InlineField
+ * - Content remains in the DOM but is hidden with `hidden`, `aria-hidden`, and `inert` attributes in edit mode
+ * - Use this component to wrap both the read-only value and the InlineFieldEditTrigger
+ * @see {@link InlineFieldReadViewProps} for all available props
+ * @see {@link InlineField} for the parent container component
+ * @see {@link InlineFieldEditView} for the corresponding edit mode component
+ * @see {@link InlineFieldEditTrigger} for the button to enter edit mode
+ * @see Source code in {@link https://github.com/PayFit/hr-apps/tree/master/libs/shared/unity/components/src/core/components/inline-field GitHub}
+ * @see Developer docs in {@link https://unity-components.payfit.io/?path=/docs/forms-reference-inlinefield--docs unity-components.payfit.io}
+ */
+export declare function InlineFieldReadView({ children, successMessage, }: InlineFieldReadViewProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace InlineFieldReadView {
+    var displayName: string;
+}

package/dist/esm/modules/tanstack-form/components/inline-field/parts/InlineFieldReadView.js

@@ -0,0 +1,53 @@
+import { useFormContext as e } from "../../../hooks/tanstack-form-context.js";
+import { useInlineField as t } from "../InlineField.context.js";
+import { useEffect as n, useRef as r, useState as i } from "react";
+import { jsx as a, jsxs as o } from "react/jsx-runtime";
+import { useSelector as s } from "@tanstack/react-store";
+//#region src/modules/tanstack-form/components/inline-field/parts/InlineFieldReadView.tsx
+var c = 5e3;
+function l({ children: l, successMessage: u }) {
+	let d = t(), [f, p] = i(""), { isSubmitting: m, submissionAttempts: h, isSubmitSuccessful: g } = s(e().store, (e) => ({
+		isSubmitting: e.isSubmitting,
+		isSubmitSuccessful: e.isSubmitSuccessful,
+		submissionAttempts: e.submissionAttempts
+	})), _ = r(m), v = d?.mode === "read";
+	return n(() => {
+		_.current && !m && g && u && p(u);
+	}, [
+		m,
+		g,
+		u,
+		d
+	]), n(() => {
+		if (u && !d?.isLoading && v && g) {
+			p(u);
+			let e = setTimeout(() => {
+				p("");
+			}, c);
+			return () => {
+				clearTimeout(e);
+			};
+		}
+	}, [
+		u,
+		d,
+		v,
+		g
+	]), n(() => {
+		m && !_.current && p("");
+	}, [m]), /* @__PURE__ */ o("div", {
+		hidden: !v,
+		"aria-hidden": !v,
+		...!v && { inert: "" },
+		children: [l, /* @__PURE__ */ a("div", {
+			role: "status",
+			"aria-live": "polite",
+			"aria-atomic": "true",
+			className: "uy:sr-only",
+			children: f
+		})]
+	});
+}
+l.displayName = "InlineFieldReadView";
+//#endregion
+export { l as InlineFieldReadView };

package/dist/esm/modules/tanstack-form/components/inline-field-group/InlineFieldGroup.context.js

@@ -0,0 +1,6 @@
+import { createContext as e } from "react";
+//#region src/modules/tanstack-form/components/inline-field-group/InlineFieldGroup.context.tsx
+var t = e(void 0);
+t.displayName = "InlineFieldGroupContext";
+//#endregion
+export { t as InlineFieldGroupContext };

package/dist/esm/modules/tanstack-form/components/inline-field-group/InlineFieldGroup.d.ts

@@ -0,0 +1,149 @@
+import { default as React, PropsWithChildren } from 'react';
+import { InlineFieldGroupMode } from './InlineFieldGroup.context.js';
+/**
+ * Imperative handle for InlineFieldGroup component.
+ * Provides methods for programmatic control when needed for advanced use cases.
+ */
+export interface InlineFieldGroupHandle {
+    /**
+     * Focuses the first invalid field in the edit view.
+     * Useful for custom validation error handling.
+     */
+    focusFirstInvalidField: () => void;
+    /**
+     * Exits edit mode programmatically.
+     */
+    exitEditMode: () => void;
+    /**
+     * Enters edit mode programmatically.
+     */
+    enterEditMode: () => void;
+}
+export interface InlineFieldGroupProps extends PropsWithChildren {
+    /**
+     * Controlled mode value. When provided, the component operates in controlled mode.
+     */
+    mode?: InlineFieldGroupMode;
+    /**
+     * Default mode value for uncontrolled mode.
+     * @default 'read'
+     */
+    defaultMode?: InlineFieldGroupMode;
+    /**
+     * Callback fired when mode changes.
+     */
+    onModeChange?: (mode: InlineFieldGroupMode) => void;
+    /**
+     * Callback to intercept and potentially prevent mode changes.
+     * Return `false` to prevent the mode transition.
+     * Return `true` or `undefined` to allow the transition.
+     */
+    shouldModeChange?: (fromMode: InlineFieldGroupMode, toMode: InlineFieldGroupMode) => boolean | undefined;
+    /**
+     * Whether the component is in a loading state (e.g., during async save).
+     */
+    isLoading?: boolean;
+    /**
+     * Optional className for custom styling
+     */
+    className?: string;
+    /**
+     * Optional aria-label for the form element.
+     * If not provided, aria-labelledby will reference the header title.
+     */
+    'aria-label'?: string;
+    /**
+     * Indicates whether the component or element should track and respond to focus containment.
+     * When set to true, the focus is constrained within the component, preventing focus from
+     * moving outside its boundaries.
+     * @default false
+     */
+    containFocus?: boolean;
+    /**
+     * Success message to announce when save succeeds.
+     * If not provided, no success announcement is made.
+     */
+    successMessage?: string;
+    /**
+     * Error message to announce when save or validation fails.
+     * If not provided, generic validation errors are announced.
+     */
+    errorMessage?: string;
+    /**
+     * Custom label for the edit button.
+     * @default "Edit" (translated)
+     */
+    editLabel?: string;
+    /**
+     * Custom label for the save button.
+     * @default "Save" (translated)
+     */
+    saveLabel?: string;
+    /**
+     * Custom label for the cancel button.
+     * @default "Cancel" (translated)
+     */
+    cancelLabel?: string;
+    /**
+     * Optional callback fired when the edit button is clicked.
+     * This is called before entering edit mode and is useful for analytics or side effects.
+     */
+    onEditPress?: () => void;
+    /**
+     * Optional callback fired when the save button is clicked.
+     * This is called before form submission and is useful for analytics or side effects.
+     * Note: Form submission is handled via the form's onSubmit configuration.
+     */
+    onSavePress?: () => void;
+    /**
+     * Optional callback fired when the cancel button is clicked.
+     * This is called before canceling and is useful for analytics or side effects.
+     * The form will be reset and edit mode exited automatically.
+     */
+    onCancelPress?: () => void;
+}
+/**
+ * InlineFieldGroup enables group-level inline editing with read/edit mode switching.
+ * It integrates with TanStack Form for validation and state management, providing
+ * a complete pattern for displaying data in read mode and editing it in edit mode.
+ * The component handles the full edit lifecycle: mode transitions, form submission,
+ * validation error handling, and accessibility announcements.
+ * @example
+ * ```tsx
+ * import { useTanstackUnityForm } from '@payfit/unity-components'
+ *
+ * function ContactForm() {
+ *   const form = useTanstackUnityForm({
+ *     defaultValues: { email: 'user@example.com', phone: '+1234567890' },
+ *     onSubmit: async ({ value }) => {
+ *       await saveContact(value)
+ *     }
+ *   })
+ *
+ *   return (
+ *     <form.AppForm>
+ *       <form.InlineFieldGroup successMessage="Contact saved!">
+ *         <form.InlineFieldGroupHeader title="Contact Information" />
+ *         <form.InlineFieldGroupReadView>
+ *           <DefinitionList>
+ *             <DefinitionItem term="Email" description={form.state.values.email} />
+ *           </DefinitionList>
+ *         </form.InlineFieldGroupReadView>
+ *         <form.InlineFieldGroupEditView legend="Edit contact">
+ *           <form.AppField name="email">
+ *             {field => <field.TextField label="Email" />}
+ *           </form.AppField>
+ *         </form.InlineFieldGroupEditView>
+ *       </form.InlineFieldGroup>
+ *     </form.AppForm>
+ *   )
+ * }
+ * ```
+ * @remarks
+ * - The component automatically exits edit mode on successful form submission
+ * - Press Escape to cancel editing and reset form values
+ * - Focus moves to the first form field when entering edit mode
+ * - Focus returns to the edit button when exiting edit mode (only if focus hasn'../../../../core/components/inline-field-group GitHub}
+ * @see Developer docs in {@link https:/unity-components.payfit.io/?path=/docs/forms-reference-inlinefieldgroup--docs unity-components.payfit.io}
+ */
+export declare const InlineFieldGroup: React.ForwardRefExoticComponent<InlineFieldGroupProps & React.RefAttributes<InlineFieldGroupHandle>>;