@payfit/unity-components 2.1.4 → 2.2.0

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

@@ -0,0 +1,119 @@
+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;
+    /**
+     * 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;
+}
+/**
+ * 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
+ * - Focus is retained under a scope when in edit mode, to prevent users for leaving unfinished changes
+ * - Use `shouldModeChange` to intercept and conditionally prevent mode transitions
+ * - Use `successMessage` and `errorMessage` for accessible announcements via live regions
+ * @see {@link InlineFieldGroupProps} for all available props
+ * @see {@link InlineFieldGroupHandle} for imperative handle methods
+ * @see {@link InlineFieldGroupHeader} for the header component with action buttons
+ * @see {@link InlineFieldGroupReadView} for read mode content
+ * @see {@link InlineFieldGroupEditView} for edit mode form fields
+ * @see Source code in {@link https://github.com/PayFit/hr-apps/tree/master/libs/shared/unity/components/src/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>>;

package/dist/esm/components/inline-field-group/InlineFieldGroup.js

@@ -0,0 +1,185 @@
+import { jsx as x, jsxs as z } from "react/jsx-runtime";
+import { forwardRef as J, useRef as l, useState as V, useEffect as r, useCallback as P, useImperativeHandle as Q, useMemo as W } from "react";
+import { uyTv as X } from "@payfit/unity-themes";
+import { useStore as Y } from "@tanstack/react-form";
+import { useId as Z, useKeyboard as L, FocusScope as ee } from "react-aria";
+import { useIntl as te } from "react-intl";
+import { useFormContext as ie } from "../../hooks/tanstack-form-context.js";
+import { useInlineFieldGroupMode as re } from "./hooks/useInlineFieldGroupMode.js";
+import { InlineFieldGroupContext as oe } from "./InlineFieldGroup.context.js";
+const se = X({
+  slots: {
+    form: "uy:flex uy:flex-col uy:gap-300"
+  }
+}), D = (a) => {
+  if (!a.current) return;
+  const c = a.current.querySelector(
+    '[aria-invalid="true"]'
+  );
+  c && c.focus();
+}, k = 5e3, ne = J(
+  ({
+    children: a,
+    mode: c,
+    defaultMode: j,
+    onModeChange: q,
+    shouldModeChange: m,
+    isLoading: N,
+    className: K,
+    "aria-label": _,
+    successMessage: g,
+    errorMessage: d
+  }, O) => {
+    const s = Z(), A = `unity-InlineFieldGroup-${s}__header`, C = `unity-InlineFieldGroup-${s}__edit-view`, E = l(null), n = l(null), M = l(!0), [G, R] = V(""), [h, f] = V(""), p = te(), u = ie(), { mode: t, enterEditMode: b, exitEditMode: o } = re({
+      mode: c,
+      defaultMode: j,
+      onModeChange: q,
+      shouldModeChange: m
+    }), { isSubmitting: i, isValid: v, isSubmitSuccessful: S, submissionAttempts: y } = Y(u.store, (e) => ({
+      isSubmitting: e.isSubmitting,
+      isValid: e.isValid,
+      isSubmitSuccessful: e.isSubmitSuccessful,
+      submissionAttempts: e.submissionAttempts
+    })), F = l(i), T = l(y);
+    r(() => {
+      i && !F.current && (R(""), f(""));
+    }, [i]), r(() => {
+      if (y > T.current && !v) {
+        const I = d ?? p.formatMessage({
+          id: "unity:component:inline-field-group:validation-error",
+          defaultMessage: "Please fix the errors before saving."
+        });
+        f(I), D(n);
+      }
+    }, [y, v, d, p]), r(() => {
+      F.current && !i && S && (g && R(g), o());
+    }, [i, S, g, o]), r(() => {
+      if (F.current && !i && !S && v) {
+        const I = d ?? p.formatMessage({
+          id: "unity:component:inline-field-group:save-error",
+          defaultMessage: "An error occurred while saving. Please try again."
+        });
+        f(I);
+      }
+    }, [i, S, v, d, p]), r(() => {
+      F.current = i, T.current = y;
+    });
+    const $ = P(
+      (e) => {
+        e.preventDefault(), e.stopPropagation(), u.handleSubmit();
+      },
+      [u]
+    ), w = P(() => {
+      m !== void 0 && !m(t, "read") || (u.reset(), o());
+    }, [u, t, o, m]);
+    Q(
+      O,
+      () => ({
+        focusFirstInvalidField: () => {
+          D(n);
+        },
+        exitEditMode: o,
+        enterEditMode: b
+      }),
+      [o, b]
+    ), r(() => {
+      if (M.current) {
+        M.current = !1;
+        return;
+      }
+      if (t === "edit") {
+        if (n.current) {
+          const e = n.current.querySelectorAll(
+            'input, select, textarea, [tabindex]:not([tabindex="-1"])'
+          );
+          e.length > 0 && e[0].focus();
+        }
+      } else
+        E.current && E.current.focus();
+    }, [t]);
+    const { keyboardProps: B } = L({
+      onKeyDown: (e) => {
+        e.key === "Escape" && t === "edit" && (e.preventDefault(), w());
+      }
+    });
+    r(() => {
+      if (G) {
+        const e = setTimeout(() => {
+          R("");
+        }, k);
+        return () => {
+          clearTimeout(e);
+        };
+      }
+    }, [G]), r(() => {
+      if (h) {
+        const e = setTimeout(() => {
+          f("");
+        }, k);
+        return () => {
+          clearTimeout(e);
+        };
+      }
+    }, [h]);
+    const H = W(
+      () => ({
+        mode: t,
+        enterEditMode: b,
+        exitEditMode: w,
+        groupId: s,
+        headerId: A,
+        editViewId: C,
+        isLoading: N,
+        editButtonRef: E,
+        editViewRef: n
+      }),
+      [
+        t,
+        b,
+        w,
+        s,
+        A,
+        C,
+        N
+      ]
+    ), { form: U } = se();
+    return /* @__PURE__ */ x(oe.Provider, { value: H, children: /* @__PURE__ */ x(
+      "form",
+      {
+        ...B,
+        id: s,
+        className: U({ className: K }),
+        onSubmit: $,
+        "aria-label": _,
+        "aria-labelledby": _ ? void 0 : A,
+        children: /* @__PURE__ */ z(ee, { contain: t === "edit", children: [
+          a,
+          /* @__PURE__ */ x(
+            "div",
+            {
+              role: "status",
+              "aria-live": "polite",
+              "aria-atomic": "true",
+              className: "uy:sr-only",
+              children: G
+            }
+          ),
+          /* @__PURE__ */ x(
+            "div",
+            {
+              role: "alert",
+              "aria-live": "assertive",
+              "aria-atomic": "true",
+              className: "uy:sr-only",
+              children: h
+            }
+          )
+        ] })
+      }
+    ) });
+  }
+);
+ne.displayName = "InlineFieldGroup";
+export {
+  ne as InlineFieldGroup
+};

package/dist/esm/components/inline-field-group/hooks/useInlineFieldGroupMode.d.ts

@@ -0,0 +1,46 @@
+import { InlineFieldGroupMode } from '../InlineFieldGroup.context.js';
+export interface UseInlineFieldGroupModeProps {
+    /**
+     * 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;
+}
+export interface UseInlineFieldGroupModeReturn {
+    /** Current mode value */
+    mode: InlineFieldGroupMode;
+    /** Switch to edit mode */
+    enterEditMode: () => void;
+    /** Exit edit mode (return to read mode) */
+    exitEditMode: () => void;
+    /** Check if component is in controlled mode */
+    isControlled: boolean;
+}
+/**
+ * Hook to manage the mode state (read/edit) for InlineFieldGroup.
+ * Supports both controlled and uncontrolled modes, following the pattern
+ * established by NavGroup.tsx
+ * @param props - Configuration for the mode hook
+ * @param props.mode - Controlled mode value. When provided, the component operates in controlled mode.
+ * @param props.defaultMode - Default mode value for uncontrolled mode.
+ * @param props.onModeChange - Callback fired when mode changes.
+ * @param props.shouldModeChange - Callback to intercept and potentially prevent mode changes.
+ * Return `false` to prevent the mode transition.
+ * Return `true` or `undefined` to allow the transition.
+ * @returns Mode state and handlers
+ */
+export declare function useInlineFieldGroupMode({ mode: controlledMode, defaultMode, onModeChange, shouldModeChange, }: UseInlineFieldGroupModeProps): UseInlineFieldGroupModeReturn;

package/dist/esm/components/inline-field-group/hooks/useInlineFieldGroupMode.js

@@ -0,0 +1,27 @@
+import { useState as m, useCallback as i } from "react";
+function x({
+  mode: d,
+  defaultMode: c = "read",
+  onModeChange: s,
+  shouldModeChange: o
+}) {
+  const [l, u] = m(c), t = d !== void 0, n = t ? d : l, e = i(
+    (r) => {
+      o && o(n, r) === !1 || (t || u(r), s?.(r));
+    },
+    [t, n, s, o]
+  ), a = i(() => {
+    e("edit");
+  }, [e]), f = i(() => {
+    e("read");
+  }, [e]);
+  return {
+    mode: n,
+    enterEditMode: a,
+    exitEditMode: f,
+    isControlled: t
+  };
+}
+export {
+  x as useInlineFieldGroupMode
+};

package/dist/esm/components/inline-field-group/parts/InlineFieldGroupEditView.d.ts

@@ -0,0 +1,64 @@
+import { PropsWithChildren, ReactNode } from 'react';
+export interface InlineFieldGroupEditViewProps extends PropsWithChildren {
+    /**
+     * Optional className for custom styling
+     */
+    className?: string;
+    /**
+     * Legend text for the fieldset. Should describe the group of fields.
+     * This is required for accessibility but will be visually hidden.
+     */
+    legend?: ReactNode;
+}
+/**
+ * InlineFieldGroupEditView displays form fields only when the parent InlineFieldGroup is in edit mode.
+ * Wrap form field components in this component to show them when editing.
+ * The component uses a semantic `<fieldset>` with a visually hidden `<legend>` for accessibility.
+ * It automatically disables all fields during loading states and hides content in read mode.
+ * @example Basic usage with form fields
+ * ```tsx
+ * import { useTanstackUnityForm } from '@payfit/unity-components'
+ *
+ * function Example() {
+ *   const form = useTanstackUnityForm({
+ *     defaultValues: { email: 'john@example.com', phone: '+33123456789' }
+ *   })
+ *
+ *   return (
+ *     <form.AppForm>
+ *       <form.InlineFieldGroup>
+ *         <form.InlineFieldGroupHeader title="Contact" />
+ *         <form.InlineFieldGroupReadView>
+ *           <DefinitionList>
+ *             <DefinitionItem term="Email" description={form.state.values.email} />
+ *           </DefinitionList>
+ *         </form.InlineFieldGroupReadView>
+ *         <form.InlineFieldGroupEditView legend="Edit contact information">
+ *           <form.AppField name="email">
+ *             {field => <field.TextField label="Email" isRequired />}
+ *           </form.AppField>
+ *           <form.AppField name="phone">
+ *             {field => <field.PhoneNumberField label="Phone" />}
+ *           </form.AppField>
+ *         </form.InlineFieldGroupEditView>
+ *       </form.InlineFieldGroup>
+ *     </form.AppForm>
+ *   )
+ * }
+ * ```
+ * @remarks
+ * - Must be used as a child of InlineFieldGroup
+ * - Set the `legend` prop to describe the group of fields for screen readers
+ * - The fieldset is disabled automatically when the parent's `isLoading` prop is true
+ * - Uses `aria-busy` to indicate loading state to assistive technologies
+ * - Content remains in the DOM but is hidden with `hidden` and `inert` attributes in read mode
+ * @see {@link InlineFieldGroupEditViewProps} for all available props
+ * @see {@link InlineFieldGroup} for the parent container component
+ * @see {@link InlineFieldGroupReadView} for the corresponding read mode component
+ * @see Source code in {@link https://github.com/PayFit/hr-apps/tree/master/libs/shared/unity/components/src/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 function InlineFieldGroupEditView({ children, className, legend, }: InlineFieldGroupEditViewProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace InlineFieldGroupEditView {
+    var displayName: string;
+}

package/dist/esm/components/inline-field-group/parts/InlineFieldGroupEditView.js

@@ -0,0 +1,56 @@
+import { jsxs as h, jsx as e } from "react/jsx-runtime";
+import { useContext as g } from "react";
+import { uyTv as w } from "@payfit/unity-themes";
+import { useIntl as x } from "react-intl";
+import { Button as v } from "../../button/Button.js";
+import { InlineFieldGroupContext as I } from "../InlineFieldGroup.context.js";
+const N = w({
+  slots: {
+    fieldset: "uy:border-0 uy:p-0 uy:m-0",
+    legend: "uy:sr-only",
+    fieldsContainer: "uy:flex uy:flex-col uy:gap-250",
+    hiddenButtons: "uy:sr-only"
+  }
+});
+function b({
+  children: d,
+  className: s,
+  legend: o
+}) {
+  const l = x(), t = g(I);
+  if (!t)
+    throw new Error(
+      "InlineFieldGroupEditView must be used within InlineFieldGroup"
+    );
+  const { mode: r, editViewId: a, isLoading: n, editViewRef: u } = t, i = r === "edit", {
+    fieldset: m,
+    legend: f,
+    fieldsContainer: c,
+    hiddenButtons: p
+  } = N(), y = l.formatMessage({
+    id: "unity:component:inline-field-group:save",
+    defaultMessage: "Save"
+  });
+  return /* @__PURE__ */ h(
+    "fieldset",
+    {
+      ref: u,
+      id: a,
+      className: m({ className: s }),
+      disabled: n,
+      hidden: !i,
+      "aria-hidden": !i,
+      "aria-busy": n,
+      ...!i && { inert: "" },
+      children: [
+        /* @__PURE__ */ e("legend", { className: f(), children: o }),
+        /* @__PURE__ */ e("div", { className: c(), children: d }),
+        /* @__PURE__ */ e("div", { className: p(), children: /* @__PURE__ */ e(v, { type: "submit", variant: "primary", children: y }) })
+      ]
+    }
+  );
+}
+b.displayName = "InlineFieldGroupEditView";
+export {
+  b as InlineFieldGroupEditView
+};

package/dist/esm/components/inline-field-group/parts/InlineFieldGroupHeader.d.ts

@@ -0,0 +1,95 @@
+import { ReactNode } from 'react';
+export interface InlineFieldGroupHeaderProps {
+    /**
+     * The title to display in the header.
+     * This will be used for aria-labelledby on the form element.
+     */
+    title: ReactNode;
+    /**
+     * 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;
+    /**
+     * Additional custom actions to render alongside the default buttons.
+     * These will be displayed between the title and the edit/save/cancel buttons.
+     */
+    customActions?: ReactNode;
+    /**
+     * 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;
+}
+/**
+ * InlineFieldGroupHeader renders the title and contextual action buttons for an InlineFieldGroup.
+ * It automatically switches between Edit button (read mode) and Save/Cancel buttons (edit mode)
+ * based on the parent InlineFieldGroup's current mode.
+ * The Save button integrates with TanStack Form and remains disabled until the form has changes.
+ * Cancel resets the form and returns to read mode.
+ * @example Basic usage
+ * ```tsx
+ * import { useTanstackUnityForm } from '@payfit/unity-components'
+ *
+ * function Example() {
+ *   const form = useTanstackUnityForm({ defaultValues: { name: 'John' } })
+ *
+ *   return (
+ *     <form.AppForm>
+ *       <form.InlineFieldGroup>
+ *         <form.InlineFieldGroupHeader title="Contact Information" />
+ *         <form.InlineFieldGroupReadView>...</form.InlineFieldGroupReadView>
+ *         <form.InlineFieldGroupEditView legend="Edit">...</form.InlineFieldGroupEditView>
+ *       </form.InlineFieldGroup>
+ *     </form.AppForm>
+ *   )
+ * }
+ * ```
+ * @example Custom button labels and actions
+ * ```tsx
+ * <form.InlineFieldGroupHeader
+ *   title="Contact Information"
+ *   editLabel="Modify"
+ *   saveLabel="Confirm"
+ *   cancelLabel="Discard"
+ *   customActions={<Button onPress={handleDelete}>Delete</Button>}
+ *   onSavePress={() => trackAnalytics('save_clicked')}
+ * />
+ * ```
+ * @remarks
+ * - Must be used as a child of InlineFieldGroup
+ * - The title serves as the accessible label for the form via `aria-labelledby`
+ * - The Edit button uses `aria-expanded` and `aria-controls` for accessibility
+ * - Use `customActions` to add buttons that appear in both read and edit modes
+ * - Use `onEditPress`, `onSavePress`, `onCancelPress` for analytics or side effects
+ * @see {@link InlineFieldGroupHeaderProps} for all available props
+ * @see {@link InlineFieldGroup} for the parent container component
+ * @see Source code in {@link https://github.com/PayFit/hr-apps/tree/master/libs/shared/unity/components/src/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 function InlineFieldGroupHeader({ title, editLabel, saveLabel, cancelLabel, customActions, onEditPress, onSavePress, onCancelPress, }: InlineFieldGroupHeaderProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace InlineFieldGroupHeader {
+    var displayName: string;
+}