@payfit/unity-components 2.46.13 → 2.46.14

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

@@ -0,0 +1,46 @@
+import { InlineFieldMode } from '../InlineField.context.js';
+export interface UseInlineFieldModeProps {
+    /**
+     * Controlled mode value. When provided, the component operates in controlled mode.
+     */
+    mode?: InlineFieldMode;
+    /**
+     * Default mode value for uncontrolled mode.
+     * @default 'read'
+     */
+    defaultMode?: InlineFieldMode;
+    /**
+     * Callback fired when mode changes.
+     */
+    onModeChange?: (mode: InlineFieldMode) => 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: InlineFieldMode, toMode: InlineFieldMode) => boolean | undefined;
+}
+export interface UseInlineFieldModeReturn {
+    /** Current mode value */
+    mode: InlineFieldMode;
+    /** 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 InlineField.
+ * 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 useInlineFieldMode({ mode: controlledMode, defaultMode, onModeChange, shouldModeChange, }: UseInlineFieldModeProps): UseInlineFieldModeReturn;

package/dist/esm/components/inline-field/hooks/useInlineFieldMode.js

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

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

@@ -0,0 +1,59 @@
+export interface InlineFieldEditTriggerProps {
+    /**
+     * Custom label for the edit button.
+     * @default "Edit" (translated)
+     */
+    editLabel?: string;
+}
+/**
+ * InlineFieldEditTrigger renders an icon button that switches the InlineField to edit mode.
+ * It automatically displays only when the parent InlineField is in read mode.
+ * The button uses a pencil icon and handles entering edit mode when clicked.
+ * @example Basic usage
+ * ```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 Custom edit label
+ * ```tsx
+ * <field.InlineFieldEditTrigger editLabel="Modify" />
+ * ```
+ * @remarks
+ * - Must be used as a child of InlineField
+ * - Automatically disabled when InlineField is in edit mode
+ * - Uses `aria-controls` and `aria-expanded` for accessibility
+ * - Typically placed alongside the read-only value in InlineFieldReadView
+ * @see {@link InlineFieldEditTriggerProps} for all available props
+ * @see {@link InlineField} for the parent container component
+ * @see {@link InlineFieldReadView} for the read mode container
+ * @see Source code in {@link https://github.com/PayFit/hr-apps/tree/master/libs/shared/unity/components/src/components/inline-field GitHub}
+ * @see Developer docs in {@link https://unity-components.payfit.io/?path=/docs/forms-reference-inlinefield--docs unity-components.payfit.io}
+ */
+declare const InlineFieldEditTrigger: {
+    ({ editLabel }: InlineFieldEditTriggerProps): import("react/jsx-runtime").JSX.Element | null;
+    displayName: string;
+};
+export { InlineFieldEditTrigger };

package/dist/esm/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/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/components/inline-field/parts/InlineFieldEditView.js

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

package/dist/esm/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/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/components/inline-field/parts/InlineFieldReadView.js

@@ -0,0 +1,58 @@
+import { jsxs as a, jsx as c } from "react/jsx-runtime";
+import { useState as p, useRef as S, useEffect as r } from "react";
+import { useSelector as b } from "@tanstack/react-store";
+import { useFormContext as R } from "../../../hooks/tanstack-form-context.js";
+import { useInlineField as A } from "../InlineField.context.js";
+const I = 5e3;
+function x({
+  children: l,
+  successMessage: i
+}) {
+  const n = A(), [d, s] = p(""), f = R(), { isSubmitting: e, submissionAttempts: E, isSubmitSuccessful: m } = b(
+    f.store,
+    (t) => ({
+      isSubmitting: t.isSubmitting,
+      isSubmitSuccessful: t.isSubmitSuccessful,
+      submissionAttempts: t.submissionAttempts
+    })
+  ), u = S(e), o = n?.mode === "read";
+  return r(() => {
+    u.current && !e && m && i && s(i);
+  }, [e, m, i, n]), r(() => {
+    if (i && !n?.isLoading && o && m) {
+      s(i);
+      const t = setTimeout(() => {
+        s("");
+      }, I);
+      return () => {
+        clearTimeout(t);
+      };
+    }
+  }, [i, n, o, m]), r(() => {
+    e && !u.current && s("");
+  }, [e]), /* @__PURE__ */ a(
+    "div",
+    {
+      hidden: !o,
+      "aria-hidden": !o,
+      ...!o && { inert: "" },
+      children: [
+        l,
+        /* @__PURE__ */ c(
+          "div",
+          {
+            role: "status",
+            "aria-live": "polite",
+            "aria-atomic": "true",
+            className: "uy:sr-only",
+            children: d
+          }
+        )
+      ]
+    }
+  );
+}
+x.displayName = "InlineFieldReadView";
+export {
+  x as InlineFieldReadView
+};

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

@@ -0,0 +1,35 @@
+import { RefObject } from 'react';
+export type InlineFieldGroupMode = 'read' | 'edit';
+export interface InlineFieldGroupContextValue {
+    /** Current mode: read or edit */
+    mode: InlineFieldGroupMode;
+    /** Switch to edit mode */
+    enterEditMode: () => void;
+    /** Exit edit mode (cancel or save) */
+    exitEditMode: () => void;
+    /** Unique ID for the field group (for aria attributes) */
+    groupId: string;
+    /** ID for the header title (for aria-labelledby) */
+    headerId: string;
+    /** ID for the edit view container (for aria-controls) */
+    editViewId: string;
+    /** Whether the component is in a loading state */
+    isLoading?: boolean;
+    /** Ref to the edit button for focus management */
+    editButtonRef?: RefObject<HTMLButtonElement>;
+    /** Ref to the edit view container for focus management */
+    editViewRef?: RefObject<HTMLFieldSetElement>;
+    /** Custom label for the edit button */
+    editLabel?: string;
+    /** Custom label for the save button */
+    saveLabel?: string;
+    /** Custom label for the cancel button */
+    cancelLabel?: string;
+    /** Callback fired when edit button is clicked */
+    onEditPress?: () => void;
+    /** Callback fired when save button is clicked */
+    onSavePress?: () => void;
+    /** Callback fired when cancel button is clicked */
+    onCancelPress?: () => void;
+}
+export declare const InlineFieldGroupContext: import('react').Context<InlineFieldGroupContextValue | undefined>;

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

@@ -0,0 +1,6 @@
+import { createContext as e } from "react";
+const o = e(void 0);
+o.displayName = "InlineFieldGroupContext";
+export {
+  o as InlineFieldGroupContext
+};