@eyesee/ui-components 0.7.0 → 0.9.0

package/dist/components/ImageWithData/ImageWithData.js

@@ -3,7 +3,7 @@ import { useState as z } from "react";
 import n from "clsx";
 import { Checkbox as F } from "../Checkbox/Checkbox.js";
 import { tagPropsFromTag as R, badgePropsFromTag as _, pillPropsFromTag as j } from "../ImagePlaceholder/utilsImgPh.js";
-import { ASPECT_RATIOS as f, TAG_TYPES as b, OVERLAYS as B, TEXT_POSITIONS as x, LINES as D } from "../ImagePlaceholder/constantsImgPh.js";
+import { ASPECT_RATIOS as h, TAG_TYPES as b, OVERLAYS as B, TEXT_POSITIONS as x, LINES as D } from "../ImagePlaceholder/constantsImgPh.js";
 import { ImageOffIcon as W } from "../icons-v2/ImageOffIcon.js";
 import { XIcon as X } from "../icons-v2/XIcon.js";
 import e from "./ImageWithData.module.scss.js";
@@ -12,7 +12,7 @@ import { EllipsisTooltip as Y } from "../EllipsisTooltip/EllipsisTooltip.js";
 import { Tag as G } from "../Tag/Tag.js";
 import { Badge as V } from "../Badge/Badge.js";
 import { Pill as q } from "../Pill/Pill.js";
-const ae = ({
+function ae({
   id: T,
   url: k,
   text: s,
@@ -21,7 +21,7 @@ const ae = ({
   overlay: i,
   isChecked: v,
   onChecked: d,
-  aspectRatio: I = f["1/1"],
+  aspectRatio: I = h["1/1"],
   lines: S = D[1],
   number: p = null,
   disabled: m = !1,
@@ -29,8 +29,8 @@ const ae = ({
   onClose: E,
   icon: g,
   onIconClick: P
-}) => {
-  const [c, y] = z(!1), h = () => {
+}) {
+  const [c, y] = z(!1), u = () => {
     switch (r == null ? void 0 : r.type) {
       case "pill":
         return /* @__PURE__ */ o(q, { ...j(r) });
@@ -41,7 +41,7 @@ const ae = ({
       default:
         return null;
     }
-  }, u = !s || t === x.outside ? "8px" : "8px 8px 0 0", A = Number(S), O = n(e.contentText, e.contentTextClamped), w = { WebkitLineClamp: A }, l = C || m;
+  }, f = !s || t === x.outside ? "8px" : "8px 8px 0 0", A = Number(S), O = n(e.contentText, e.contentTextClamped), w = { WebkitLineClamp: A }, l = C || m;
   return /* @__PURE__ */ a("div", { className: n(e.imagePlaceholder, m && e.disabled), children: [
     /* @__PURE__ */ a(
       "div",
@@ -51,14 +51,14 @@ const ae = ({
           i === "checkbox" && e.clickable,
           i === "checkbox" && !c && e.checkboxSelectable
         ),
-        style: { borderRadius: u },
+        style: { borderRadius: f },
         onClick: i === "checkbox" && !c && !m ? d : void 0,
         children: [
           /* @__PURE__ */ o(
             "div",
             {
               className: e.imageFrame,
-              style: { aspectRatio: f[I], borderRadius: u },
+              style: { aspectRatio: h[I], borderRadius: f },
               children: c ? /* @__PURE__ */ o("div", { className: e.imageError, children: /* @__PURE__ */ o(
                 W,
                 {
@@ -76,7 +76,7 @@ const ae = ({
               )
             }
           ),
-          !s && b.has(r == null ? void 0 : r.type) ? /* @__PURE__ */ o("div", { className: e.tagInImage, children: h() }) : null,
+          !s && b.has(r == null ? void 0 : r.type) ? /* @__PURE__ */ o("div", { className: e.tagInImage, children: u() }) : null,
           B.has(i) && /* @__PURE__ */ a("div", { className: e.overlay, onClick: (L) => L.stopPropagation(), children: [
             i === "checkbox" && !c ? /* @__PURE__ */ o(
               F,
@@ -114,7 +114,7 @@ const ae = ({
       }
     ),
     s ? /* @__PURE__ */ a("div", { className: n(e.belowImage, e[t]), children: [
-      b.has(r == null ? void 0 : r.type) ? /* @__PURE__ */ o("div", { children: h() }) : null,
+      b.has(r == null ? void 0 : r.type) ? /* @__PURE__ */ o("div", { children: u() }) : null,
       /* @__PURE__ */ a("div", { className: e.content, children: [
         /* @__PURE__ */ o(
           Y,
@@ -130,7 +130,7 @@ const ae = ({
       ] })
     ] }) : null
   ] }, T);
-};
+}
 export {
   ae as default
 };

package/dist/components/Infobox/Infobox.d.ts

@@ -0,0 +1,90 @@
+/**
+ * All props are optional.
+ *
+ * @typedef {object} InfoboxProps
+ *
+ * @property {string}          [title='']
+ *   Heading text. Default `''`.
+ * @property {string}          [text='']
+ *   Body copy below the heading (or inline when no title). Default `''`.
+ * @property {'fill'|'outline'} [color='fill']
+ *   Visual style. Default `'fill'`.
+ * @property {'success'|'error'|'primary'|'warning'} [status='success']
+ *   Semantic status colour. Default `'success'`.
+ * @property {React.ReactNode} [icon=null]
+ *   Optional custom leading icon. Default `null`.
+ * @property {boolean}         [fullWidth=false]
+ *   Stretch to parent width. Default `false`.
+ */
+/**
+ * Informational block with semantic status colours.
+ *
+ * ## Props
+ *
+ * All optional.
+ *
+ * **title** `string` — default `''`
+ * Heading text.
+ *
+ * **text** `string` — default `''`
+ * Body copy below the heading (or inline when no title).
+ *
+ * **color** `'fill' | 'outline'` — default `'fill'`
+ * Visual style.
+ *
+ * **status** `'success' | 'error' | 'primary' | 'warning'` — default `'success'`
+ * Semantic status colour.
+ *
+ * **icon** `ReactNode` — default `null`
+ * Optional custom leading icon.
+ *
+ * **fullWidth** `boolean` — default `false`
+ * Stretch to parent width.
+ *
+ * @param {InfoboxProps} props
+ * @returns {import('react').ReactElement}
+ *
+ * @example <caption>Default</caption>
+ * import { Infobox } from '@eyesee/ui-components';
+ *
+ * <Infobox status="success" color="fill" />
+ *
+ * @example <caption>All variants</caption>
+ * import { Infobox } from '@eyesee/ui-components';
+ *
+ * <Infobox status="success" color="fill" />
+ * <Infobox status="success" color="outline" />
+ * <Infobox status="error" color="fill" />
+ * <Infobox status="primary" color="outline" />
+ * <Infobox status="warning" color="fill" />
+ */
+export function Infobox({ title, text, color, status, icon, fullWidth, }: InfoboxProps): import("react").ReactElement;
+/**
+ * All props are optional.
+ */
+export type InfoboxProps = {
+    /**
+     * Heading text. Default `''`.
+     */
+    title?: string;
+    /**
+     * Body copy below the heading (or inline when no title). Default `''`.
+     */
+    text?: string;
+    /**
+     * Visual style. Default `'fill'`.
+     */
+    color?: "fill" | "outline";
+    /**
+     * Semantic status colour. Default `'success'`.
+     */
+    status?: "success" | "error" | "primary" | "warning";
+    /**
+     * Optional custom leading icon. Default `null`.
+     */
+    icon?: React.ReactNode;
+    /**
+     * Stretch to parent width. Default `false`.
+     */
+    fullWidth?: boolean;
+};

package/dist/components/Infobox/Infobox.js

@@ -1,16 +1,16 @@
 import { jsxs as a, jsx as e } from "react/jsx-runtime";
 import x from "clsx";
-import { getInfoboxStyles as p, INFOBOX_STATUSES as h, INFOBOX_COLORS as N } from "./infoboxVariants.js";
+import { getInfoboxStyles as p, INFOBOX_STATUSES as h, INFOBOX_COLORS as u } from "./infoboxVariants.js";
 import s from "./Infobox.module.scss.js";
-const y = ({
+function y({
   title: o = "",
   text: t = "",
   color: c = "fill",
   status: i = "success",
   icon: n = null,
   fullWidth: r = !1
-}) => {
-  const f = h.includes(i) ? i : "success", m = N.includes(c) ? c : "fill", d = p(m, f), l = !!o;
+}) {
+  const f = h.includes(i) ? i : "success", m = u.includes(c) ? c : "fill", d = p(m, f), l = !!o;
   return /* @__PURE__ */ a(
     "div",
     {
@@ -27,7 +27,7 @@ const y = ({
       ]
     }
   );
-};
+}
 export {
   y as Infobox
 };

package/dist/components/Infobox/infoboxVariants.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @param {'fill'|'outline'} color
+ * @param {'success'|'error'|'primary'|'warning'} status
+ * @returns {Record<string, string>}
+ */
+export function getInfoboxStyles(color: "fill" | "outline", status: "success" | "error" | "primary" | "warning"): Record<string, string>;
+export const INFOBOX_STATUSES: string[];
+export const INFOBOX_COLORS: string[];

package/dist/components/ListItem/ListItem.d.ts

@@ -0,0 +1,311 @@
+/**
+ * @callback ListItemClickHandler
+ * @returns {void}
+ */
+/**
+ * @callback ListItemTrailingIconClickHandler
+ * @param {any} item Row `item` object.
+ * @returns {void}
+ */
+/**
+ * Trailing action icon slot.
+ *
+ * @typedef {object} ListItemIcon
+ * @property {string}                          type  - Unique React key (`icon-${type}`).
+ * @property {React.ReactNode}                 icon  - Icon element.
+ * @property {ListItemTrailingIconClickHandler} [onClick]
+ *   Fired with the row `item`. Propagation stopped so the row `onClick` does not run.
+ * @property {'always'|'hover'}                [trailingDisplay]
+ *   Overrides row `trailingDisplay` for this icon.
+ * @property {'always'|'hover'}                [trailingDisplayOnSelectedItem='always']
+ *   Visibility when the row is `active`. Default `'always'`.
+ * @property {boolean}                         [disabled=false]
+ *   Skips `onClick` and hover styles for this slot only. Default `false`.
+ */
+/**
+ * All props are optional.
+ *
+ * @typedef {object} ListItemProps
+ *
+ * @property {any}              [item=null]
+ *   Raw data object. Passed to each trailing icon `onClick`. Default `null`.
+ * @property {React.ReactNode}  [controlItem=null]
+ *   Leading control slot (e.g. {@link Checkbox}). Default `null`.
+ * @property {React.ReactNode}  [customItem=null]
+ *   Secondary leading slot (e.g. {@link Avatar}, {@link Pill}). Default `null`.
+ * @property {string}           [title=null]
+ *   Primary label. Truncated via {@link EllipsisTooltip}. Default `null`.
+ * @property {string}           [description=null]
+ *   Secondary label below `title`. Default `null`.
+ * @property {ListItemIcon[]}   [trailing=[]]
+ *   Trailing action icons. Default `[]`.
+ * @property {'always'|'hover'} [trailingDisplay='hover']
+ *   Row-level trailing icon visibility. Default `'hover'`.
+ * @property {boolean}          [active=false]
+ *   Selected row (`data-active`). Default `false`.
+ * @property {ListItemClickHandler} [onClick]
+ *   Row click. Suppressed when `disabled`.
+ * @property {'none'|'xs'|'sm'|'md'|'lg'} [verticalSpacing='xs']
+ *   Vertical padding. `'none'` → `0`. Default `'xs'`.
+ * @property {'none'|'xs'|'sm'|'md'|'lg'} [horizontalSpacing='xs']
+ *   Horizontal padding. `'none'` → `0`. Default `'xs'`.
+ * @property {'fill'|'outline'} [variant='fill']
+ *   Row background style. Default `'fill'`.
+ * @property {boolean}          [disabled=false]
+ *   Suppresses row and trailing clicks. Default `false`.
+ * @property {string}           [role]
+ *   ARIA role on the root. Use `'menuitem'` inside {@link Button} dropdowns.
+ *
+ * @see {@link EllipsisTooltip}
+ * @see {@link useListItems}
+ */
+/**
+ * Presentational list row. Selection logic lives in the parent or {@link useListItems}.
+ *
+ * ## Props
+ *
+ * All optional.
+ *
+ * **item** `any` — default `null`
+ * Raw data object. Passed to each trailing icon `onClick`.
+ *
+ * **controlItem** `ReactNode` — default `null`
+ * Leading control slot (e.g. {@link Checkbox}).
+ *
+ * **customItem** `ReactNode` — default `null`
+ * Secondary leading slot (e.g. {@link Avatar}, {@link Pill}).
+ *
+ * **title** `string` — default `null`
+ * Primary label. Truncated via {@link EllipsisTooltip}.
+ *
+ * **description** `string` — default `null`
+ * Secondary label below `title`.
+ *
+ * **trailing** `ListItemIcon[]` — default `[]`
+ * Trailing action icons.
+ * - `type` `string` — required. Unique React key.
+ * - `icon` `ReactNode` — required. Icon element.
+ * - `onClick` `(item) => void` — optional. Receives row `item`.
+ * - `trailingDisplay` `'always' | 'hover'` — optional. Overrides row default.
+ * - `trailingDisplayOnSelectedItem` `'always' | 'hover'` — default `'always'`.
+ * - `disabled` `boolean` — default `false`.
+ *
+ * **trailingDisplay** `'always' | 'hover'` — default `'hover'`
+ * Row-level trailing icon visibility.
+ *
+ * **active** `boolean` — default `false`
+ * Selected row (`data-active`).
+ *
+ * **onClick** `() => void` — no default
+ * Row click. Suppressed when `disabled`.
+ *
+ * **verticalSpacing** `'none' | 'xs' | 'sm' | 'md' | 'lg'` — default `'xs'`
+ * Vertical padding. `'none'` collapses to `0`.
+ *
+ * **horizontalSpacing** `'none' | 'xs' | 'sm' | 'md' | 'lg'` — default `'xs'`
+ * Horizontal padding. `'none'` collapses to `0`.
+ *
+ * **variant** `'fill' | 'outline'` — default `'fill'`
+ * Row background style.
+ *
+ * **disabled** `boolean` — default `false`
+ * Suppresses row and trailing clicks.
+ *
+ * **role** `string` — no default
+ * ARIA role on the root. Use `'menuitem'` inside {@link Button} dropdowns.
+ *
+ * @param {ListItemProps} props
+ * @returns {import('react').ReactElement}
+ *
+ * @example <caption>Default</caption>
+ * import { ListItem } from '@eyesee/ui-components';
+ *
+ * <ListItem title="Item label" />
+ *
+ * @example <caption>With description</caption>
+ * import { ListItem } from '@eyesee/ui-components';
+ *
+ * <ListItem title="Item label" description="Secondary detail text" />
+ *
+ * @example <caption>Active (selected)</caption>
+ * import { ListItem } from '@eyesee/ui-components';
+ *
+ * <ListItem title="Selected item" description="This row is currently active" active />
+ *
+ * @example <caption>With trailing icons – always visible</caption>
+ * import { ListItem } from '@eyesee/ui-components';
+ * import { EditIcon, DeleteIcon } from '@eyesee/ui-components/icons';
+ *
+ * <ListItem
+ *   title="Item with icons"
+ *   description="Edit or delete this item"
+ *   trailingDisplay="always"
+ *   trailing={[
+ *     { type: 'edit', icon: <EditIcon iconSize="s" strokeColor="currentColor" /> },
+ *     { type: 'delete', icon: <DeleteIcon iconSize="s" strokeColor="currentColor" /> },
+ *   ]}
+ * />
+ *
+ * @example <caption>With trailing icons – reveal on hover</caption>
+ * import { ListItem } from '@eyesee/ui-components';
+ * import { EditIcon, DeleteIcon } from '@eyesee/ui-components/icons';
+ *
+ * <ListItem
+ *   title="Hover to reveal icons"
+ *   description="Action icons appear on mouse-over"
+ *   trailingDisplay="hover"
+ *   trailing={[
+ *     { type: 'edit', icon: <EditIcon iconSize="s" strokeColor="currentColor" /> },
+ *     { type: 'delete', icon: <DeleteIcon iconSize="s" strokeColor="currentColor" /> },
+ *   ]}
+ * />
+ *
+ * @example <caption>With leading avatar</caption>
+ * import { ListItem, Avatar } from '@eyesee/ui-components';
+ *
+ * <ListItem
+ *   customItem={<Avatar initials="LA" color="green" />}
+ *   title="Lina Adams"
+ *   description="Design team"
+ *   variant="outline"
+ * />
+ *
+ * @example <caption>With leading control</caption>
+ * import { ListItem, Checkbox } from '@eyesee/ui-components';
+ *
+ * <ListItem
+ *   controlItem={<Checkbox checked={false} onChange={() => {}} size="md" />}
+ *   title="Enable notifications"
+ *   description="Receive updates for this list"
+ * />
+ *
+ * @example <caption>With custom status</caption>
+ * import { ListItem, Pill } from '@eyesee/ui-components';
+ * import { EditIcon, DeleteIcon } from '@eyesee/ui-components/icons';
+ *
+ * <ListItem
+ *   customItem={
+ *     <Pill
+ *       label="In review"
+ *       backgroundColor="var(--color--background--secondary--subtle)"
+ *       color="var(--color--text--secondary--default)"
+ *     />
+ *   }
+ *   title="Project Beta"
+ *   description="Awaiting approval"
+ *   variant="outline"
+ *   trailingDisplay="always"
+ *   trailing={[
+ *     { type: 'edit', icon: <EditIcon iconSize="s" strokeColor="currentColor" /> },
+ *     { type: 'delete', icon: <DeleteIcon iconSize="s" strokeColor="currentColor" /> },
+ *   ]}
+ * />
+ *
+ * @example <caption>Outline variant</caption>
+ * import { ListItem } from '@eyesee/ui-components';
+ * import { EditIcon, DeleteIcon } from '@eyesee/ui-components/icons';
+ *
+ * <ListItem
+ *   title="Outline list item"
+ *   description="Border appears on interaction and active state"
+ *   variant="outline"
+ *   trailingDisplay="always"
+ *   trailing={[
+ *     { type: 'edit', icon: <EditIcon iconSize="s" strokeColor="currentColor" /> },
+ *     { type: 'delete', icon: <DeleteIcon iconSize="s" strokeColor="currentColor" /> },
+ *   ]}
+ * />
+ */
+export function ListItem({ item, controlItem, customItem, title, description, trailing, trailingDisplay, active, onClick, verticalSpacing, horizontalSpacing, variant, disabled, role, }: ListItemProps): import("react").ReactElement;
+export type ListItemClickHandler = () => void;
+export type ListItemTrailingIconClickHandler = (item: any) => void;
+/**
+ * Trailing action icon slot.
+ */
+export type ListItemIcon = {
+    /**
+     * - Unique React key (`icon-${type}`).
+     */
+    type: string;
+    /**
+     * - Icon element.
+     */
+    icon: React.ReactNode;
+    /**
+     * Fired with the row `item`. Propagation stopped so the row `onClick` does not run.
+     */
+    onClick?: ListItemTrailingIconClickHandler;
+    /**
+     * Overrides row `trailingDisplay` for this icon.
+     */
+    trailingDisplay?: "always" | "hover";
+    /**
+     * Visibility when the row is `active`. Default `'always'`.
+     */
+    trailingDisplayOnSelectedItem?: "always" | "hover";
+    /**
+     * Skips `onClick` and hover styles for this slot only. Default `false`.
+     */
+    disabled?: boolean;
+};
+/**
+ * All props are optional.
+ */
+export type ListItemProps = {
+    /**
+     * Raw data object. Passed to each trailing icon `onClick`. Default `null`.
+     */
+    item?: any;
+    /**
+     * Leading control slot (e.g. {@link Checkbox}). Default `null`.
+     */
+    controlItem?: React.ReactNode;
+    /**
+     * Secondary leading slot (e.g. {@link Avatar}, {@link Pill}). Default `null`.
+     */
+    customItem?: React.ReactNode;
+    /**
+     * Primary label. Truncated via {@link EllipsisTooltip}. Default `null`.
+     */
+    title?: string;
+    /**
+     * Secondary label below `title`. Default `null`.
+     */
+    description?: string;
+    /**
+     * Trailing action icons. Default `[]`.
+     */
+    trailing?: ListItemIcon[];
+    /**
+     * Row-level trailing icon visibility. Default `'hover'`.
+     */
+    trailingDisplay?: "always" | "hover";
+    /**
+     * Selected row (`data-active`). Default `false`.
+     */
+    active?: boolean;
+    /**
+     * Row click. Suppressed when `disabled`.
+     */
+    onClick?: ListItemClickHandler;
+    /**
+     * Vertical padding. `'none'` → `0`. Default `'xs'`.
+     */
+    verticalSpacing?: "none" | "xs" | "sm" | "md" | "lg";
+    /**
+     * Horizontal padding. `'none'` → `0`. Default `'xs'`.
+     */
+    horizontalSpacing?: "none" | "xs" | "sm" | "md" | "lg";
+    /**
+     * Row background style. Default `'fill'`.
+     */
+    variant?: "fill" | "outline";
+    /**
+     * Suppresses row and trailing clicks. Default `false`.
+     */
+    disabled?: boolean;
+    /**
+     * ARIA role on the root. Use `'menuitem'` inside {@link Button} dropdowns.
+     */
+    role?: string;
+};

package/dist/components/ListItem/ListItem.js

@@ -2,7 +2,7 @@ import { jsxs as x, jsx as e, Fragment as b } from "react/jsx-runtime";
 import A from "clsx";
 import { EllipsisTooltip as y } from "../EllipsisTooltip/EllipsisTooltip.js";
 import a from "./ListItem.module.scss.js";
-const F = ({
+function F({
   item: v = null,
   controlItem: r = null,
   customItem: n = null,
@@ -17,11 +17,11 @@ const F = ({
   variant: D = "fill",
   disabled: d = !1,
   role: w
-}) => {
-  const o = (t == null ? void 0 : t.length) > 0, h = !!i, u = !!s, N = [
+}) {
+  const o = (t == null ? void 0 : t.length) > 0, u = !!i, h = !!s, N = [
     r && "auto",
     n && "auto",
-    (h || u) && "minmax(0, 3fr)",
+    (u || h) && "minmax(0, 3fr)",
     o && "auto"
   ].filter(Boolean).join(" ");
   return /* @__PURE__ */ x(
@@ -42,8 +42,8 @@ const F = ({
         r && /* @__PURE__ */ e("div", { onClick: (l) => l.stopPropagation(), children: r }),
         n && /* @__PURE__ */ e(b, { children: n }),
         /* @__PURE__ */ x("div", { className: a.textWrapper, children: [
-          h && /* @__PURE__ */ e(y, { showArrow: !0, content: i, className: a.title, children: i }),
-          u && /* @__PURE__ */ e(y, { showArrow: !0, content: s, className: a.description, children: s })
+          u && /* @__PURE__ */ e(y, { showArrow: !0, content: i, className: a.title, children: i }),
+          h && /* @__PURE__ */ e(y, { showArrow: !0, content: s, className: a.description, children: s })
         ] }),
         o && /* @__PURE__ */ e("div", { className: a.trailing, children: t.map((l) => {
           const k = (l == null ? void 0 : l.trailingDisplay) || c, j = (l == null ? void 0 : l.trailingDisplayOnSelectedItem) || "always", g = d || (l == null ? void 0 : l.disabled);
@@ -65,7 +65,7 @@ const F = ({
       ]
     }
   );
-};
+}
 export {
   F as ListItem
 };

package/dist/components/ListItem/useListItems.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Builds a memoised `listItems` array from raw data for {@link ListItem}.
+ *
+ * `controlItem`, `customItem`, and `trailing` accept a static value or
+ * `(item) => value` for heterogeneous lists.
+ *
+ * @param {UseListItemsOptions} options
+ * @returns {UseListItemsReturn}
+ *
+ * @example <caption>Selectable list</caption>
+ * import { ListItem, useListItems } from '@eyesee/ui-components';
+ *
+ * const items = [
+ *   { id: 1, name: 'Alpha', description: 'First' },
+ *   { id: 2, name: 'Beta', description: 'Second' },
+ * ];
+ * const { listItems } = useListItems({
+ *   items,
+ *   activeItemId: 1,
+ *   onItemSelect: (item) => console.log(item),
+ * });
+ *
+ * {listItems.map(({ id, ...props }) => (
+ *   <ListItem key={id} {...props} />
+ * ))}
+ *
+ * @example <caption>Per-row trailing icons</caption>
+ * import { ListItem, useListItems } from '@eyesee/ui-components';
+ * import { DeleteIcon } from '@eyesee/ui-components/icons';
+ *
+ * const { listItems } = useListItems({
+ *   items: [{ id: 'a', name: 'Row A' }],
+ *   trailing: (item) => [
+ *     {
+ *       type: 'delete',
+ *       icon: <DeleteIcon iconSize="s" strokeColor="currentColor" />,
+ *       onClick: () => console.log('delete', item.id),
+ *     },
+ *   ],
+ * });
+ */
+export function useListItems({ items, controlItem, customItem, trailing, trailingDisplay, itemTitleKey, itemDescriptionKey, activeItemId, onItemSelect, verticalSpacing, horizontalSpacing, variant, }: UseListItemsOptions): UseListItemsReturn;
+export type UseListItemsValueResolver<T> = (item: any) => T;
+export type UseListItemsSelectHandler = (item: any) => void;
+export type ListItemIcon = import("./ListItem").ListItemIcon;
+/**
+ * Props spread onto {@link ListItem}, plus `id` for React keys.
+ */
+export type UseListItemsListItemProps = import("./ListItem").ListItemProps & {
+    id?: string | number;
+    internalNumber?: string | number;
+};
+export type UseListItemsOptions = {
+    /**
+     * Data objects. Each needs `id` for keys and active matching. Default `[]`.
+     */
+    items?: any[];
+    /**
+     * Leading control per row, or static node. Default `null`.
+     */
+    controlItem?: React.ReactNode | UseListItemsValueResolver<React.ReactNode>;
+    /**
+     * Custom leading slot per row, or static node. Default `null`.
+     */
+    customItem?: React.ReactNode | UseListItemsValueResolver<React.ReactNode>;
+    /**
+     * Trailing icons per row, or static array. Default `[]`.
+     */
+    trailing?: ListItemIcon[] | UseListItemsValueResolver<ListItemIcon[]>;
+    /**
+     * Row-level trailing visibility. Default `'hover'`.
+     */
+    trailingDisplay?: "always" | "hover";
+    /**
+     * Key on each item for `title`. Default `'name'`.
+     */
+    itemTitleKey?: string;
+    /**
+     * Key on each item for `description`. Default `'description'`.
+     */
+    itemDescriptionKey?: string;
+    /**
+     * Selected item `id`. Matching rows get `active: true`. Default `null`.
+     */
+    activeItemId?: string | number | null;
+    /**
+     * Row click; adds `onClick` to each list item when set.
+     */
+    onItemSelect?: UseListItemsSelectHandler;
+    /**
+     * Passed to every {@link ListItem}. Default `'xs'`.
+     */
+    verticalSpacing?: "none" | "xs" | "sm" | "md" | "lg";
+    /**
+     * Passed to every {@link ListItem}. Default `'xs'`.
+     */
+    horizontalSpacing?: "none" | "xs" | "sm" | "md" | "lg";
+    /**
+     * Passed to every {@link ListItem}. Default `'fill'`.
+     */
+    variant?: "fill" | "outline";
+};
+export type UseListItemsReturn = {
+    /**
+     * Memoised {@link ListItem} props.
+     */
+    listItems: UseListItemsListItemProps[];
+};