@payfit/unity-components 2.46.13 → 2.46.14

package/dist/esm/components/select-field/TanstackSelectField.d.ts

@@ -0,0 +1,124 @@
+import { ForwardedRef, JSX, ReactNode } from 'react';
+import { LabelProps } from '../label/Label.js';
+import { TanstackSelectProps } from '../select/TanstackSelect.js';
+interface FieldProps<T extends object> extends Pick<LabelProps, 'isRequired' | 'requiredVariant'>, TanstackSelectProps<T> {
+    /** The label for the select field. */
+    label: string;
+    /** Helper text to display below the select field. */
+    helperText?: ReactNode;
+    /** A contextual link to display below the select field. */
+    contextualLink?: ReactNode;
+}
+export type TanstackSelectFieldProps<T extends object> = FieldProps<T>;
+type TanstackSelectFieldComponent = (<TItems extends object>(props: TanstackSelectFieldProps<TItems> & {
+    ref?: ForwardedRef<HTMLDivElement>;
+}) => JSX.Element) & {
+    displayName?: string;
+};
+/**
+ * The `TanstackSelectField` component renders a complete select field (label, select, feedback)
+ * wired to the TanStack Form context. It manages state and accessibility via the
+ * context provided by `useTanstackUnityForm` and `<form.AppField name="…">`.
+ *
+ * Behavior:
+ * - Renders a full field structure including `TanstackFormLabel`, `TanstackFormHelperText`,
+ *   `TanstackSelect`, and `TanstackFormFeedbackText`.
+ * - Supports both static options (using `SelectOption` components) and dynamic options
+ *   (using the `items` prop with a render function).
+ * - Can be configured with search functionality via the `isSearchable` prop.
+ * - Displays validation feedback automatically based on the form's validation state.
+ *
+ * Accessibility:
+ * - Automatically wires `aria-labelledby`, `aria-describedby` (helper/feedback), and
+ *   `aria-details` using identifiers from the `a11y` context.
+ *
+ * Key props:
+ * - `label: string` — label text for the field.
+ * - `children: ReactNode | ((item: T) => ReactNode)` — static options or render function for dynamic items.
+ * - `items?: Iterable<T>` — array of items for dynamic rendering.
+ * - `isSearchable?: boolean` — enables search input in the select dropdown.
+ * - `helperText?: ReactNode` — helper text displayed below the field.
+ * - `contextualLink?: ReactNode` — optional contextual link, referenced via `aria-details`.
+ * - `isRequired?`, `requiredVariant?` — control the required indicator in the label.
+ * - `placeholder?: string` — placeholder text when no value is selected.
+ * - `placement?: 'top' | 'bottom'` — popover placement.
+ *
+ * Example (static options):
+ * ```tsx
+ * import { TanstackSelectField } from "@/components/select/TanstackSelectField"
+ * import { SelectOption } from "@/components/select/parts/SelectOption"
+ * import { useTanstackUnityForm } from "@/hooks/use-tanstack-form"
+ * import { z } from "zod"
+ *
+ * function Example() {
+ *   const schema = z.object({
+ *     fruit: z.string().min(1, 'Please select a fruit'),
+ *   })
+ *
+ *   const form = useTanstackUnityForm({
+ *     validators: { onBlur: schema },
+ *     defaultValues: { fruit: '' }
+ *   })
+ *
+ *   return (
+ *     <form>
+ *       <form.AppField name="fruit">
+ *         {() => (
+ *           <TanstackSelectField
+ *             label="Favorite Fruit"
+ *             helperText="Select your favorite fruit"
+ *             placeholder="Choose a fruit"
+ *           >
+ *             <SelectOption id="Apple">Apple</SelectOption>
+ *             <SelectOption id="Banana">Banana</SelectOption>
+ *             <SelectOption id="Orange">Orange</SelectOption>
+ *           </TanstackSelectField>
+ *         )}
+ *       </form.AppField>
+ *     </form>
+ *   )
+ * }
+ * ```
+ *
+ * Example (dynamic items with search):
+ * ```tsx
+ * function ExampleDynamic() {
+ *   const items = [
+ *     { id: 'Apple', name: 'Apple' },
+ *     { id: 'Banana', name: 'Banana' },
+ *     { id: 'Orange', name: 'Orange' },
+ *   ]
+ *
+ *   const schema = z.object({
+ *     fruit: z.string(),
+ *   })
+ *
+ *   const form = useTanstackUnityForm({
+ *     validators: { onBlur: schema },
+ *     defaultValues: { fruit: '' }
+ *   })
+ *
+ *   return (
+ *     <form>
+ *       <form.AppField name="fruit">
+ *         {() => (
+ *           <TanstackSelectField
+ *             label="Favorite Fruit"
+ *             isSearchable
+ *             items={items}
+ *           >
+ *             {item => <SelectOption id={item.id}>{item.name}</SelectOption>}
+ *           </TanstackSelectField>
+ *         )}
+ *       </form.AppField>
+ *     </form>
+ *   )
+ * }
+ * ```
+ * @remarks Migration from `SelectField` (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.
+ * - The field automatically manages validation state and displays error messages.
+ */
+declare const TanstackSelectField: TanstackSelectFieldComponent;
+export { TanstackSelectField };

package/dist/esm/components/select-field/TanstackSelectField.js

@@ -0,0 +1,46 @@
+import { jsxs as d, jsx as r } from "react/jsx-runtime";
+import { forwardRef as f } from "react";
+import { TanstackFormFeedbackText as k } from "../form-field/parts/TanstackFormFeedbackText.js";
+import { TanstackFormHelperText as p } from "../form-field/parts/TanstackFormHelperText.js";
+import { TanstackFormLabel as F } from "../form-field/parts/TanstackFormLabel.js";
+import { TanstackFormField as T } from "../form-field/TanstackFormField.js";
+import { TanstackSelect as S } from "../select/TanstackSelect.js";
+const x = ({
+  label: a,
+  helperText: t,
+  contextualLink: e,
+  isRequired: o,
+  isDisabled: c,
+  isReadOnly: m,
+  requiredVariant: n,
+  renderValue: i,
+  ...l
+}, s) => /* @__PURE__ */ d(T, { children: [
+  /* @__PURE__ */ r(
+    F,
+    {
+      requiredVariant: n,
+      isRequired: o,
+      children: a
+    }
+  ),
+  t && /* @__PURE__ */ r(p, { children: t }),
+  /* @__PURE__ */ r(
+    S,
+    {
+      ref: s,
+      isDisabled: c,
+      isReadOnly: m,
+      renderValue: i,
+      ...l
+    }
+  ),
+  /* @__PURE__ */ r(k, {}),
+  e
+] }), u = f(function(t, e) {
+  return x(t, e);
+});
+u.displayName = "TanstackSelectField";
+export {
+  u as TanstackSelectField
+};

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

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

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

@@ -0,0 +1,26 @@
+import { within as o, userEvent as t, screen as s } from "storybook/test";
+const w = (n) => ({ selectOption: async ({
+  labelText: e,
+  optionName: a,
+  container: i = n.canvasElement
+}) => {
+  await n.step(
+    `Select option "${a}" in "${e}"`,
+    async () => {
+      const c = o(i).getByLabelText(e, {
+        exact: !1
+      });
+      if (!c)
+        throw new Error(`Select not found for label ${e}`);
+      await t.click(c, { delay: 100 }), await t.click(
+        s.getByRole("option", { name: a }),
+        {
+          delay: 100
+        }
+      ), await t.tab({ delay: 100 });
+    }
+  );
+} });
+export {
+  w as getTestingUtilsSelect
+};

package/dist/esm/components/select-list/SelectList.d.ts

@@ -0,0 +1,95 @@
+import { JSX, Ref } from 'react';
+import { ListBoxProps as AriaListBoxProps } from 'react-aria-components/ListBox';
+/**
+ * Props for the SelectList component.
+ * @template TType - The type of items in the list
+ */
+export interface SelectListProps<TType extends object = object> extends Omit<AriaListBoxProps<TType>, 'className' | 'style' | 'selectedKeys' | 'onSelectionChange' | 'children'> {
+    /**
+     * An iterable data structure containing items to render in the list.
+     */
+    items: Iterable<TType>;
+    /**
+     * Render function for each item. Receives an item and should generally returns a `SelectListOption` component.
+     */
+    children: (item: TType) => React.ReactElement;
+    /**
+     * The current selected keys of the list. Pass a `Set` of keys to control the selection state.
+     */
+    value: AriaListBoxProps<TType>['selectedKeys'];
+    /**
+     * Callback function invoked when the user selection changes. Use this to update the controlled `value` prop.
+     * @param keys - The new selection as a `Selection` type (Set of keys or "all")
+     */
+    onChange: AriaListBoxProps<TType>['onSelectionChange'];
+    /**
+     * Controls whether to display a search input at the top of the list. Set to `true` to always show the search bar, or `false` to never show it. When undefined, the search bar appears automatically when there are 10 or more items.
+     * @default undefined - Auto-shows when items >= 10
+     */
+    showSearch?: boolean;
+    /**
+     * Additional CSS classes to apply to the list container. Use this to customize height or other container styles.
+     */
+    className?: string;
+    /**
+     * Enables selected-first sorting, which moves selected items into a dedicated section at the top of the list. Selected items can be deselected directly from this section.
+     * @default false
+     */
+    sortSelectedFirst?: boolean;
+    /**
+     * Accessible label for the selected items section. This label is screen-reader only and provides context for the separated selected items.
+     * @default "Selected"
+     */
+    selectedSectionLabel?: string;
+    /**
+     *
+     */
+    isLoading?: boolean;
+}
+type SelectListComponent = {
+    <TType extends object>(props: SelectListProps<TType> & {
+        ref?: Ref<HTMLDivElement>;
+    }): JSX.Element;
+    displayName: string;
+};
+/**
+ * Provides a high-performance, accessible list for selecting items with built-in virtualization, search, and sorting capabilities.
+ * Use this component to allow users to select one or multiple items from a list of options. The component automatically handles large datasets through virtualization, provides built-in search functionality when needed, and can optionally organize selected items into a dedicated section at the top for better visibility.
+ * @param {SelectListProps} props - Regular props from React Aria's ListBox, plus selection, search, and sorting configuration
+ * @example
+ * ```tsx
+ * import { SelectList, SelectListOption } from '@payfit/unity-components'
+ *
+ * function FruitSelector() {
+ *   const [selected, setSelected] = useState(new Set())
+ *   const fruits = [
+ *     { id: 'apple', label: 'Apple' },
+ *     { id: 'banana', label: 'Banana' }
+ *   ]
+ *
+ *   return (
+ *     <SelectList
+ *       items={fruits}
+ *       value={selected}
+ *       onChange={setSelected}
+ *       selectionMode="multiple"
+ *     >
+ *       {item => <SelectListOption id={item.id}>{item.label}</SelectListOption>}
+ *     </SelectList>
+ *   )
+ * }
+ * ```
+ * @remarks
+ * - List items are automatically virtualized for optimal performance with large datasets (hundreds or thousands of items)
+ * - Search bar appears automatically when the list contains 10 or more items, or can be controlled via the `showSearch` prop
+ * - Set `sortSelectedFirst` to `true` to move selected items into a dedicated section at the top of the list
+ * - The component requires the dynamic API pattern: provide both `items` array and a render function as `children`
+ * - Selection state is fully controlled via the `value` and `onChange` props following React's controlled component pattern
+ * - Supports both flat item lists and grouped sections using `SelectListOptGroup`
+ * @see {@link SelectListProps} for all available props
+ * @see Source code in {@link https://github.com/PayFit/hr-apps/tree/master/libs/shared/unity/components/src/components/select-list GitHub}
+ * @see Design specs in {@link https://www.figma.com/design/poaMyU7abAgL9VRhx4ygyy/Unity-DS-%3E-Components-Library Figma}
+ * @see Developer docs in {@link https://unity-components.payfit.io/?path=/docs/data-selectlist unity-components.payfit.io}
+ */
+declare const SelectList: SelectListComponent;
+export { SelectList };

package/dist/esm/components/select-list/SelectList.js

@@ -0,0 +1,82 @@
+import { jsx as e, jsxs as s, Fragment as E } from "react/jsx-runtime";
+import { forwardRef as F, useMemo as m } from "react";
+import { uyTv as R } from "@payfit/unity-themes";
+import { useFilter as T, Autocomplete as H } from "react-aria-components/Autocomplete";
+import { ListBox as M, Collection as O } from "react-aria-components/ListBox";
+import { Separator as _ } from "react-aria-components/Separator";
+import { Virtualizer as y } from "react-aria-components/Virtualizer";
+import { DEFAULT_SEARCH_THRESHOLD as j, VIRTUALIZATION_CONFIG as d } from "./constants.js";
+import { useControlledSelection as k } from "./hooks/useControlledSelection.js";
+import { useSelectedFirstSorting as D } from "./hooks/useSelectedFirstSorting.js";
+import { SelectedItemsSection as U } from "./parts/SelectedItemsSection.js";
+import { SelectListEmptyState as V } from "./parts/SelectListEmptyState.js";
+import { SelectListSearchInput as z } from "./parts/SelectListSearchInput.js";
+const G = R({
+  slots: {
+    wrapper: "uy:bg-surface-neutral uy:p-100 uy:overscroll-contain",
+    base: "uy:flex uy:w-full uy:gap-100 uy:h-500 uy:border uy:border-solid uy:rounded-75 uy:py-100 uy:border-border-form-enabled uy:bg-surface-form-enabled uy:px-150 uy:typography-body uy:focus-within:outline-none uy:focus-within:ring-2 uy:focus-within:ring-utility-focus-ring uy:focus-within:ring-offset-2 uy:active:border-border-form-active",
+    inputContainer: "uy:sticky uy:top-0 uy:bg-surface-neutral",
+    separator: "uy:h-[1px] uy:bg-border-neutral uy:w-full uy:mt-100",
+    list: "uy:overflow-y-auto uy:mt-100 uy:h-[300px]",
+    selectedListBox: "uy:bg-surface-neutral uy:border-b uy:border-border-neutral uy:py-100 uy:data-[empty=true]:border-0 uy:data-[is-last=true]:border-0 uy:data-[is-last=true]:py-0"
+  }
+});
+function K({
+  items: r,
+  children: p,
+  value: f,
+  onChange: h,
+  className: b,
+  showSearch: a = !1,
+  sortSelectedFirst: g = !1,
+  selectedSectionLabel: S = "Selected",
+  ...o
+}, I) {
+  const { contains: L } = T({ sensitivity: "base" }), { wrapper: x, inputContainer: v, list: w, separator: C, selectedListBox: A } = G(), [i, l] = k(
+    f,
+    h
+  ), N = m(() => (Array.isArray(r) ? r.length : Array.from(r).length) >= j || a, [r, a]), t = D(
+    r,
+    i,
+    g
+  ), n = m(() => t.remainingItems ? !t.remainingItems[Symbol.iterator]().next().done : !1, [t.remainingItems]), u = /* @__PURE__ */ e(
+    U,
+    {
+      items: t.selectedItems,
+      selectedKeys: i,
+      onSelectionChange: l,
+      selectionMode: o.selectionMode,
+      selectionBehavior: o.selectionBehavior,
+      label: S,
+      className: A(),
+      "data-is-last": !n
+    }
+  ), c = /* @__PURE__ */ e(
+    M,
+    {
+      ...o,
+      className: w({ className: b }),
+      items: t.remainingItems,
+      selectedKeys: i,
+      onSelectionChange: l,
+      renderEmptyState: V,
+      children: /* @__PURE__ */ e(O, { items: t.remainingItems, children: p })
+    }
+  );
+  return /* @__PURE__ */ e("div", { ref: I, className: x(), children: N ? /* @__PURE__ */ s(H, { filter: L, children: [
+    /* @__PURE__ */ s("div", { className: v(), "data-dd-privacy": "mask", children: [
+      /* @__PURE__ */ e(z, {}),
+      /* @__PURE__ */ e(_, { className: C() })
+    ] }),
+    u,
+    n && /* @__PURE__ */ e(y, { ...d, children: c })
+  ] }) : /* @__PURE__ */ s(E, { children: [
+    u,
+    n && /* @__PURE__ */ e(y, { ...d, children: c })
+  ] }) });
+}
+const Z = F(K);
+Z.displayName = "SelectList";
+export {
+  Z as SelectList
+};

package/dist/esm/components/select-list/SelectList.types.d.ts

@@ -0,0 +1,29 @@
+import { Key } from 'react-aria-components/Breadcrumbs';
+/**
+ * Type for items that have an id and can be selected
+ */
+export interface SelectableItem {
+    id: Key;
+    [key: string]: unknown;
+}
+/**
+ * Type for sections that contain selectable items
+ */
+export interface SectionWithChildren<TChild extends SelectableItem> {
+    children: TChild[];
+    [key: string]: unknown;
+}
+/**
+ * Helper types for processing results from flat items
+ */
+export interface ProcessedFlatDynamicContent<TType> {
+    selectedItems: TType[];
+    remainingItems: TType[];
+}
+/**
+ * Helper types for processing results from nested items
+ */
+export interface ProcessedDynamicContent<TType> {
+    selectedItems: TType[];
+    remainingSections: TType[];
+}

package/dist/esm/components/select-list/constants.d.ts

@@ -0,0 +1,36 @@
+import { ListLayout } from 'react-aria-components/Virtualizer';
+/**
+ * Configuration for list virtualization.
+ * @remarks
+ * - `estimatedRowHeight` should ideally reference a design token
+ * - `estimatedHeadingHeight` should ideally reference a design token
+ * - These values affect scroll behavior and performance
+ */
+export declare const VIRTUALIZATION_CONFIG: {
+    readonly layout: typeof ListLayout;
+    readonly layoutOptions: {
+        /**
+         * Estimated height of each list item in pixels.
+         * Used for virtualization calculations.
+         */
+        readonly estimatedRowHeight: number;
+        /**
+         * Estimated height of section headings in pixels.
+         * Used for virtualization calculations.
+         */
+        readonly estimatedHeadingHeight: number;
+        /**
+         * Gap between items in pixels
+         */
+        readonly gap: 0;
+        /**
+         * Padding around the list in pixels
+         */
+        readonly padding: 0;
+    };
+};
+/**
+ * Default threshold for showing search input.
+ * Search is shown automatically when item count exceeds this value.
+ */
+export declare const DEFAULT_SEARCH_THRESHOLD = 10;

package/dist/esm/components/select-list/constants.js

@@ -0,0 +1,29 @@
+import * as t from "@payfit/unity-themes/tokens/common/spacings.json";
+import { ListLayout as s } from "react-aria-components/Virtualizer";
+const a = (o) => parseInt(o.replace("px", "").trim(), 10), i = a(t.spacing[500].$value), n = a(t.spacing[400].$value), p = {
+  layout: s,
+  layoutOptions: {
+    /**
+     * Estimated height of each list item in pixels.
+     * Used for virtualization calculations.
+     */
+    estimatedRowHeight: i,
+    /**
+     * Estimated height of section headings in pixels.
+     * Used for virtualization calculations.
+     */
+    estimatedHeadingHeight: n,
+    /**
+     * Gap between items in pixels
+     */
+    gap: 0,
+    /**
+     * Padding around the list in pixels
+     */
+    padding: 0
+  }
+}, r = 10;
+export {
+  r as DEFAULT_SEARCH_THRESHOLD,
+  p as VIRTUALIZATION_CONFIG
+};

package/dist/esm/components/select-list/helpers.d.ts

@@ -0,0 +1,42 @@
+import { Key } from 'react-aria-components/Breadcrumbs';
+import { ProcessedDynamicContent, ProcessedFlatDynamicContent, SectionWithChildren, SelectableItem } from './SelectList.types.js';
+/**
+ * Type guard to check if an object has a children array property,
+ * indicating it's a section containing selectable items.
+ * @param obj - Object to check
+ * @returns True if object is a section with children array
+ */
+export declare function hasSectionChildren<TChild extends SelectableItem>(obj: unknown): obj is SectionWithChildren<TChild>;
+/**
+ * Type guard to check if items array contains nested sections or flat items
+ * by inspecting the first item in the iterable.
+ * Uses iterator directly to avoid converting entire iterable to array.
+ */
+export declare function isNestedStructure<TChild extends SelectableItem>(items: Iterable<unknown>): items is Iterable<SectionWithChildren<TChild>>;
+/**
+ * Processes a flat array of items, partitioning them into selected
+ * and unselected groups based on the provided selected keys.
+ * @param items - Flat iterable of items to process
+ * @param selectedKeys - Set of currently selected item keys
+ * @returns Object with selectedItems and remainingItems arrays
+ */
+export declare function processSelectedItemsForFlatDynamicItems<TItem extends SelectableItem>(items: Iterable<TItem>, selectedKeys: Set<Key>): ProcessedFlatDynamicContent<TItem>;
+/**
+ * Extracts all selectable child items from a nested section structure,
+ * flattening the hierarchy into a single array.
+ * @param items - Iterable of sections containing child items
+ * @returns Object with flat array of all child items
+ */
+export declare function extractAllSelectableItems<TSection extends SectionWithChildren<TChild>, TChild extends SelectableItem>(items: Iterable<TSection>): {
+    allItems: TChild[];
+};
+/**
+ * Processes a nested structure (sections with children), extracting selected
+ * items and creating modified sections with selected items removed.
+ * @param items - Iterable of sections containing child items
+ * @param selectedKeys - Set of currently selected item keys
+ * @returns Object with selectedItems array and modified sections array
+ */
+export declare function processSelectedItemsForNestedDynamicItems<TSection extends SectionWithChildren<TChild>, TChild extends SelectableItem & {
+    label: string;
+}>(items: Iterable<TSection>, selectedKeys: Set<Key>): ProcessedDynamicContent<TChild | TSection>;

package/dist/esm/components/select-list/helpers.js

@@ -0,0 +1,48 @@
+import { partition as l } from "./utils/partition.js";
+function c(r) {
+  return typeof r == "object" && r !== null && "children" in r && Array.isArray(r.children);
+}
+function d(r) {
+  const t = r[Symbol.iterator]().next();
+  return t.done ? !1 : c(t.value);
+}
+function u(r, n) {
+  const t = Array.from(r), [i, s] = l(
+    t,
+    (e) => n.has(e.id)
+  );
+  return { selectedItems: i, remainingItems: s };
+}
+function m(r) {
+  const n = [];
+  return Array.from(r).forEach((t) => {
+    c(t) && t.children.forEach((i) => {
+      n.push(i);
+    });
+  }), { allItems: n };
+}
+function h(r, n) {
+  const { allItems: t } = m(r), i = t.filter((e) => n.has(e.id)), s = Array.from(r).map((e) => {
+    if (c(e)) {
+      const o = e.children.filter(
+        (a) => !n.has(a.id)
+      );
+      return {
+        ...e,
+        children: o
+      };
+    }
+    return e;
+  }).filter((e) => c(e) && e.children.length > 0);
+  return {
+    selectedItems: i,
+    remainingSections: s
+  };
+}
+export {
+  m as extractAllSelectableItems,
+  c as hasSectionChildren,
+  d as isNestedStructure,
+  u as processSelectedItemsForFlatDynamicItems,
+  h as processSelectedItemsForNestedDynamicItems
+};

package/dist/esm/components/select-list/hooks/useControlledSelection.d.ts

@@ -0,0 +1,24 @@
+import { Key } from 'react-aria-components/Breadcrumbs';
+import { Selection } from 'react-aria-components/GridList';
+/**
+ * Hook to manage controlled/uncontrolled selection state.
+ * Follows React's controlled component pattern.
+ * @param value - Controlled value (undefined for uncontrolled mode)
+ * @param onChange - Callback when selection changes
+ * @returns Tuple of [currentSelection, handleSelectionChange]
+ * @example
+ * ```tsx
+ * // Controlled mode
+ * const [selection, setSelection] = useControlledSelection(
+ *   selectedKeys,
+ *   handleChange
+ * )
+ *
+ * // Uncontrolled mode
+ * const [selection, setSelection] = useControlledSelection(
+ *   undefined,
+ *   handleChange
+ * )
+ * ```
+ */
+export declare function useControlledSelection(value: 'all' | Iterable<Key> | undefined, onChange?: (keys: Selection) => void): [Selection, (keys: Selection) => void];

package/dist/esm/components/select-list/hooks/useControlledSelection.js

@@ -0,0 +1,16 @@
+import { useState as i, useMemo as S, useCallback as a } from "react";
+function m(e, o) {
+  const [l, s] = i(/* @__PURE__ */ new Set()), t = e !== void 0, c = S(
+    () => t ? e === "all" ? "all" : e instanceof Set ? e : new Set(e) : l,
+    [t, e, l]
+  ), r = a(
+    (n) => {
+      t || s(n === "all" ? /* @__PURE__ */ new Set() : n), o?.(n);
+    },
+    [t, o]
+  );
+  return [c, r];
+}
+export {
+  m as useControlledSelection
+};

package/dist/esm/components/select-list/hooks/useSelectedFirstSorting.d.ts

@@ -0,0 +1,23 @@
+import { Selection } from 'react-aria-components/GridList';
+interface ProcessedItems<TType> {
+    selectedItems: TType[];
+    remainingItems: Iterable<TType> | undefined;
+}
+/**
+ * Hook to process items for selected-first sorting.
+ * Separates selected items into a dedicated section at the top.
+ * @param items - The items to process (flat or nested structure)
+ * @param selectedKeys - Currently selected keys
+ * @param enabled - Whether selected-first sorting is enabled
+ * @returns Processed items with selected items separated
+ * @example
+ * ```tsx
+ * const processed = useSelectedFirstSorting(
+ *   items,
+ *   selectedKeys,
+ *   sortSelectedFirst
+ * )
+ * ```
+ */
+export declare function useSelectedFirstSorting<TType extends object>(items: Iterable<TType> | undefined, selectedKeys: Selection, enabled: boolean): ProcessedItems<TType>;
+export {};

package/dist/esm/components/select-list/hooks/useSelectedFirstSorting.js

@@ -0,0 +1,31 @@
+import { useMemo as m } from "react";
+import { isNestedStructure as c, processSelectedItemsForNestedDynamicItems as i, processSelectedItemsForFlatDynamicItems as o } from "../helpers.js";
+function d(e, s, n) {
+  const r = m(() => s === "all" ? /* @__PURE__ */ new Set() : s, [s]);
+  return m(() => {
+    if (!n || !e || r.size === 0)
+      return { selectedItems: [], remainingItems: e };
+    if (c(e)) {
+      const t = i(
+        e,
+        r
+      );
+      return {
+        selectedItems: t.selectedItems,
+        remainingItems: t.remainingSections
+      };
+    } else {
+      const t = o(
+        e,
+        r
+      );
+      return {
+        selectedItems: t.selectedItems,
+        remainingItems: t.remainingItems
+      };
+    }
+  }, [e, r, n]);
+}
+export {
+  d as useSelectedFirstSorting
+};