@payfit/unity-components 2.0.0 → 2.2.0

package/dist/esm/components/multi-select-field/TanstackMultiSelectField.d.ts

@@ -0,0 +1,92 @@
+import { ForwardedRef, ReactNode } from 'react';
+import { LabelProps } from '../label/Label.js';
+import { TanstackMultiSelectProps } from '../multi-select/TanstackMultiSelect.js';
+export type TanstackMultiSelectFieldProps<TItems = undefined> = TanstackMultiSelectProps<TItems> & Pick<LabelProps, 'isRequired' | 'requiredVariant'> & {
+    /** The label for the multi-select field. */
+    label: string;
+    /** Helper text to display below the multi-select field. */
+    helperText?: ReactNode;
+    /** A contextual link to display below the multi-select field. */
+    contextualLink?: ReactNode;
+};
+type TanstackMultiSelectFieldComponent = <TItems = undefined>(props: TanstackMultiSelectFieldProps<TItems> & {
+    ref?: ForwardedRef<HTMLButtonElement>;
+}) => React.JSX.Element;
+/**
+ * The `TanstackMultiSelectField` component renders a full field (label, multi-select, feedback)
+ * wired to the TanStack Form context. It manages state and accessibility via the
+ * context provided by `useTanstackUnityForm` and `<form.AppField name="…">`.
+  @example
+ * ```tsx
+ * import { TanstackMultiSelectField } from "@/components/multi-select-field/TanstackMultiSelectField"
+ * import { useTanstackUnityForm } from "@/hooks/use-tanstack-form"
+ * import { MultiSelectOption } from "@/components/multi-select/parts/MultiSelectOption"
+ *
+ * function Example() {
+ *  const schema = z.object({
+ *     fruits: z.set(z.string()).min(1, 'Select at least one fruit'),
+ *  })
+ *
+ *   const form = useTanstackUnityForm({ validators: {
+ *     onBlur: schema,
+ *   } })
+ *   return (
+ *     <form>
+ *       <form.AppField name="fruits">
+ *         {() => (
+ *           <TanstackMultiSelectField
+ *             label="Favorite Fruits"
+ *             helperText="Choose your favorites"
+ *             placeholder="Select fruits..."
+ *           >
+ *             <MultiSelectOption value="apple">Apple</MultiSelectOption>
+ *             <MultiSelectOption value="banana">Banana</MultiSelectOption>
+ *             <MultiSelectOption value="orange">Orange</MultiSelectOption>
+ *           </TanstackMultiSelectField>
+ *         )}
+ *       </form.AppField>
+ *     </form>
+ *   )
+ * }
+ * ```
+ * @example
+ * ```tsx
+ * interface Fruit { id: string; name: string }
+ * const fruits = new Set<Fruit>([...])
+ *
+ * function Example() {
+ *  const schema = z.object({
+ *     fruits: z.set(z.string()).min(1, 'Select at least one fruit'),
+ *  })
+ *
+ *   const form = useTanstackUnityForm({ validators: {
+ *     onBlur: schema,
+ *   } })
+ *   return (
+ *     <form>
+ *       <form.AppField name="fruits">
+ *         {() => (
+ *           <TanstackMultiSelectField
+ *             label="Favorite Fruits"
+ *             items={fruits}
+ *             getItemValue={fruit => fruit.id}
+ *             renderValue={items => Array.from(items).map(i => i.name).join(', ')}
+ *           >
+ *             {fruit => (
+ *               <MultiSelectOption value={fruit.id}>{fruit.name}</MultiSelectOption>
+ *             )}
+ *           </TanstackMultiSelectField>
+ *         )}
+ *       </form.AppField>
+ *     </form>
+ *   )
+ * }
+ * ```
+ * @remarks Migration from `MultiSelectField` (non‑TanStack):
+ * - Do not pass a `name` prop to the field: use `<form.AppField name="…">`.
+ * - `value`, `defaultValue`, `onChange`, and `isInvalid` are derived from the TanStack form context.
+ */
+export declare const TanstackMultiSelectField: TanstackMultiSelectFieldComponent & {
+    displayName: string;
+};
+export {};

package/dist/esm/components/multi-select-field/TanstackMultiSelectField.js

@@ -0,0 +1,48 @@
+import { jsxs as s, jsx as o } from "react/jsx-runtime";
+import { forwardRef as p } from "react";
+import { TanstackFormFeedbackText as d } from "../form-field/parts/TanstackFormFeedbackText.js";
+import { TanstackFormHelperText as f } from "../form-field/parts/TanstackFormHelperText.js";
+import { TanstackFormLabel as k } from "../form-field/parts/TanstackFormLabel.js";
+import { TanstackFormField as F } from "../form-field/TanstackFormField.js";
+import { TanstackMultiSelect as T } from "../multi-select/TanstackMultiSelect.js";
+const u = ({
+  label: r,
+  helperText: t,
+  contextualLink: m,
+  isRequired: a,
+  isDisabled: e,
+  isReadOnly: c,
+  requiredVariant: i,
+  ...l
+}, n) => /* @__PURE__ */ s(F, { children: [
+  /* @__PURE__ */ o(
+    k,
+    {
+      requiredVariant: i,
+      isRequired: a,
+      children: r
+    }
+  ),
+  t && /* @__PURE__ */ o(f, { children: t }),
+  /* @__PURE__ */ o(
+    T,
+    {
+      ref: n,
+      ...{
+        isDisabled: e,
+        isReadOnly: c
+      },
+      "aria-label": r,
+      ...l
+    }
+  ),
+  /* @__PURE__ */ o(d, {}),
+  m
+] }), x = p(
+  // @ts-expect-error - forwardRef struggles with generic components
+  u
+);
+x.displayName = "TanstackMultiSelectField";
+export {
+  x as TanstackMultiSelectField
+};

package/dist/esm/components/multi-select-field/test-utils.d.ts

@@ -0,0 +1,17 @@
+import { PlayCtx } from '../../types/testing.js';
+/**
+ * Factory to get multi-select testing utils
+ * @param context the story context
+ */
+export declare const getTestingUtilsMultiSelect: (context: PlayCtx) => {
+    selectOption: ({ labelText, optionNames, container, }: {
+        labelText: string;
+        optionNames: string[];
+        container?: HTMLElement;
+    }) => Promise<void>;
+    assertSelectedOptions: ({ labelText, expectedDisplayValue, container, }: {
+        labelText: string;
+        expectedDisplayValue: string;
+        container?: HTMLElement;
+    }) => Promise<void>;
+};

package/dist/esm/components/multi-select-field/test-utils.js

@@ -0,0 +1,45 @@
+import { within as i, expect as l, userEvent as a, screen as r } from "storybook/test";
+const y = (s) => ({ selectOption: async ({
+  labelText: t,
+  optionNames: e,
+  container: o = s.canvasElement
+}) => {
+  await s.step(
+    `Select options "${e.join(", ")}" in "${t}"`,
+    async () => {
+      const n = i(o).getByLabelText(t, {
+        exact: !1
+      });
+      if (!n)
+        throw new Error(`Multi-select not found for label ${t}`);
+      await a.click(n, { delay: 100 });
+      for (const c of e)
+        await a.click(
+          r.getByRole("option", { name: c }),
+          {
+            delay: 100
+          }
+        );
+      await a.keyboard("{Escape}", { delay: 100 });
+    }
+  );
+}, assertSelectedOptions: async ({
+  labelText: t,
+  expectedDisplayValue: e,
+  container: o = s.canvasElement
+}) => {
+  await s.step(
+    `Assert selected options "${e}" in "${t}"`,
+    async () => {
+      const n = i(o).getByLabelText(t, {
+        exact: !1
+      });
+      if (!n)
+        throw new Error(`Multi-select not found for label ${t}`);
+      await l(n).toHaveTextContent(e);
+    }
+  );
+} });
+export {
+  y as getTestingUtilsMultiSelect
+};

package/dist/esm/components/nav/parts/RawNavItem.js

@@ -7,7 +7,7 @@ const B = i({
   slots: {
     base: [
       "uy:group uy:cursor-pointer uy:grid uy:w-full uy:grid-cols-[auto_1fr_auto] uy:items-center uy:py-100 uy:px-150 uy:gap-100 uy:rounded-75 uy:outline-0 uy:transition-all",
-      "uy:hover:bg-surface-neutral-hover uy:active:bg-surface-neutral-active uy:data-[pressed]:bg-surface-neutral-pressed",
+      "uy:hover:bg-surface-neutral-low-hover uy:active:bg-surface-neutral-low-active uy:data-[pressed]:bg-surface-neutral-low-pressed",
       "uy:focus:outline-0 uy:data-[focus-visible]:outline-none uy:data-[focus-visible]:ring-2 uy:data-[focus-visible]:ring-utility-focus-ring uy:data-[focus-visible]:ring-offset-2"
     ],
     prefix: "uy:p-25 uy:empty:hidden uy:text-content-neutral-low",
@@ -34,7 +34,7 @@ const B = i({
   variants: {
     isActive: {
       true: {
-        base: "uy:bg-surface-neutral-active",
+        base: "uy:bg-surface-neutral-low-active",
         prefix: "uy:text-content-neutral",
         label: "uy:typography-body-strong"
       },
@@ -49,8 +49,8 @@ const B = i({
   ({
     children: y,
     level: r = 0,
-    prefix: n,
-    suffix: l,
+    prefix: l,
+    suffix: n,
     onPress: c,
     href: t,
     isCurrent: f,
@@ -91,9 +91,9 @@ const B = i({
         isDisabled: s,
         "data-level": r,
         children: [
-          n && /* @__PURE__ */ u("span", { className: g, children: n({ isCurrent: e ?? !1 }) }),
+          l && /* @__PURE__ */ u("span", { className: g, children: l({ isCurrent: e ?? !1 }) }),
           /* @__PURE__ */ u("span", { className: x, children: y }),
-          l && /* @__PURE__ */ u("span", { className: N, children: l })
+          n && /* @__PURE__ */ u("span", { className: N, children: n })
         ]
       }
     ) });

package/dist/esm/components/navigation-card/NavigationCard.context.d.ts

@@ -0,0 +1,31 @@
+export interface NavigationCardContextValue {
+    id: string;
+    labelId: string;
+    descriptionId: string;
+}
+export declare const NavigationCardContext: import('react').Context<NavigationCardContextValue>;
+/**
+ * Accesses the NavigationCard context to retrieve accessibility IDs for proper ARIA relationships.
+ * Use this hook when building custom subcomponents that need to connect to the parent NavigationCard's accessibility structure.
+ * @returns {NavigationCardContextValue} An object containing id, labelId, and descriptionId for ARIA attributes
+ * @example
+ * ```tsx
+ * import { useNavigationCardContext } from '@payfit/unity-components'
+ *
+ * function CustomNavigationCardContent() {
+ *   const { labelId, descriptionId } = useNavigationCardContext()
+ *   return (
+ *     <div>
+ *       <span id={labelId}>Custom Label</span>
+ *       <span id={descriptionId}>Custom Description</span>
+ *     </div>
+ *   )
+ * }
+ * ```
+ * @remarks
+ * - This hook must be called within a NavigationCard component
+ * - The context provides unique IDs for accessibility attributes
+ * - Use the provided IDs to maintain proper ARIA labeling relationships
+ * @see {@link NavigationCardContextValue} for the returned value structure
+ */
+export declare function useNavigationCardContext(): NavigationCardContextValue;

package/dist/esm/components/navigation-card/NavigationCard.context.js

@@ -0,0 +1,13 @@
+import { createContext as t, useContext as e } from "react";
+const o = t({
+  id: "",
+  labelId: "",
+  descriptionId: ""
+});
+function i() {
+  return e(o);
+}
+export {
+  o as NavigationCardContext,
+  i as useNavigationCardContext
+};

package/dist/esm/components/navigation-card/NavigationCard.d.ts

@@ -0,0 +1,46 @@
+import { NavigationCardProps } from './NavigationCard.types.js';
+/**
+ * The NavigationCard is a clickable card component for navigating between sections or pages in your application.
+ * Use navigation cards to create intuitive and appealing navigation patterns that guide users through different areas of your app.
+ * The component supports both link and button behaviors, and can be customized with flexible spacing options.
+ * @param {NavigationCardProps} props - Props including standard link/button props, padding, gap, prefix, and suffix
+ * @example
+ * ```tsx
+ * import {
+ *   RawNavigationCard,
+ *   NavigationCardLabel,
+ *   NavigationCardDescription
+ * } from '@payfit/unity-components'
+ * import { Icon } from '@payfit/unity-icons'
+ *
+ * function Example() {
+ *   return (
+ *     <RawNavigationCard
+ *       href="/dashboard"
+ *       prefix={<Icon name="dashboard" />}
+ *     >
+ *       <NavigationCardLabel>Dashboard</NavigationCardLabel>
+ *       <NavigationCardDescription>
+ *         View your company overview
+ *       </NavigationCardDescription>
+ *     </RawNavigationCard>
+ *   )
+ * }
+ * ```
+ * @remarks
+ * - Use `asElement="a"` (default) for navigation links or `asElement="button"` for actions
+ * - Control spacing with `padding` (all sides), `paddingBlock` (vertical), `paddingInline` (horizontal), or individual sides via object notation
+ * - Adjust gap between prefix, body, and suffix with the `gap` prop
+ * - Default spacing values: `padding="$300"` (24px) and `gap="$150"` (12px)
+ * - Compose with `NavigationCardLabel` and `NavigationCardDescription` for proper accessibility
+ * - The component automatically handles focus states, hover effects, and disabled styling
+ * - For Tanstack Router integration, use the `NavigationCard` from `@payfit/unity-components/integrations/tanstack-router`
+ * @see {@link NavigationCardProps} for all available props
+ * @see Source code in {@link https://github.com/PayFit/hr-apps/tree/master/libs/shared/unity/components/src/components/navigation-card GitHub}
+ * @see Design specs {@link https://www.figma.com/design/poaMyU7abAgL9VRhx4ygyy/Unity-DS-%3E-Components-Library?node-id=14505-64292 Figma}
+ * @see Design docs in {@link https://www.payfit.design/ Payfit.design}
+ * @see Developer docs in {@link https://unity-components.payfit.io/?path=/docs/navigation-navigationcard--docs unity-components.payfit.io}
+ */
+declare const RawNavigationCard: import('react').ForwardRefExoticComponent<NavigationCardProps & import('react').RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
+export { RawNavigationCard };
+export type { NavigationCardProps } from './NavigationCard.types.js';

package/dist/esm/components/navigation-card/NavigationCard.js

@@ -0,0 +1,62 @@
+import { jsx as r, jsxs as h } from "react/jsx-runtime";
+import { forwardRef as C, useMemo as P } from "react";
+import { useId as $ } from "react-aria";
+import { Link as w, Button as I } from "react-aria-components";
+import { processPaddingProp as R } from "../../utils/spacing.js";
+import { NavigationCardContext as j } from "./NavigationCard.context.js";
+import { navigationCard as L } from "./NavigationCard.variants.js";
+const k = C(
+  ({
+    children: m,
+    asElement: f = "a",
+    prefix: t,
+    suffix: d,
+    padding: o = "$300",
+    paddingBlock: n,
+    paddingInline: s,
+    gap: c = "$150",
+    ...i
+  }, b) => {
+    const e = $(), l = f === "a" || "href" in i, v = i, a = {
+      id: `unity-navigation-card-${e}`,
+      labelId: i["aria-labelledby"] ?? `unity-navigation-card-label-${e}`,
+      descriptionId: i["aria-describedby"] ?? `unity-navigation-card-description-${e}`
+    }, {
+      base: y,
+      prefix: u,
+      body: p,
+      suffix: x
+    } = P(() => {
+      const g = R(
+        o,
+        n,
+        s
+      );
+      return L({
+        ...g,
+        gap: c
+      });
+    }, [o, n, s, c]), N = l ? w : I;
+    return /* @__PURE__ */ r(j.Provider, { value: a, children: /* @__PURE__ */ h(
+      N,
+      {
+        "data-dd-privacy": "allow",
+        id: a.id,
+        "aria-labelledby": a.labelId,
+        "aria-describedby": a.descriptionId,
+        ...v,
+        ref: b,
+        className: y(),
+        children: [
+          t && /* @__PURE__ */ r("div", { className: u(), children: t }),
+          /* @__PURE__ */ r("div", { className: p(), children: m }),
+          d && /* @__PURE__ */ r("div", { className: x(), children: d })
+        ]
+      }
+    ) });
+  }
+);
+k.displayName = "RawNavigationCard";
+export {
+  k as RawNavigationCard
+};

package/dist/esm/components/navigation-card/NavigationCard.types.d.ts

@@ -0,0 +1,37 @@
+import { PropsWithChildren } from 'react';
+import { ButtonProps as AriaButtonProps, LinkProps as AriaLinkProps } from 'react-aria-components';
+import { PaddingObject, SpacingToken } from '../../utils/spacing.js';
+type NavigationCardAsLinkProps = Omit<AriaLinkProps, 'style' | 'className'>;
+type NavigationCardAsButtonProps = Omit<AriaButtonProps, 'style' | 'className'>;
+/**
+ * Props for the NavigationCard component.
+ */
+export type NavigationCardProps = PropsWithChildren<(NavigationCardAsLinkProps | NavigationCardAsButtonProps) & {
+    /** Render as either a link or button element */
+    asElement?: 'a' | 'button';
+    /** Content to display before the main body (e.g., icon, avatar) */
+    prefix?: React.ReactNode;
+    /** Content to display after the main body (e.g., badge, chevron) */
+    suffix?: React.ReactNode;
+    /**
+     * Padding for all directions, or an object specifying individual sides.
+     * @default '$300'
+     */
+    padding?: SpacingToken | PaddingObject;
+    /**
+     * Padding for block direction (top & bottom).
+     * Overrides `padding` for vertical spacing.
+     */
+    paddingBlock?: SpacingToken;
+    /**
+     * Padding for inline direction (left & right).
+     * Overrides `padding` for horizontal spacing.
+     */
+    paddingInline?: SpacingToken;
+    /**
+     * Gap between prefix, body, and suffix elements.
+     * @default '$150'
+     */
+    gap?: SpacingToken;
+}>;
+export {};