@eyesee/ui-components 0.8.0 → 0.10.0

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[];
+};

package/dist/components/ListItem/useListItems.js

@@ -1,58 +1,59 @@
 import { useCallback as L, useMemo as M } from "react";
-const o = (l, n) => typeof l == "function" ? l(n) : l, q = ({
-  items: l = [],
+const f = (u, n) => typeof u == "function" ? u(n) : u;
+function q({
+  items: u = [],
   controlItem: n = null,
-  customItem: d = null,
-  trailing: f = [],
+  customItem: o = null,
+  trailing: d = [],
   trailingDisplay: b = "hover",
   itemTitleKey: x = "name",
   itemDescriptionKey: k = "description",
   activeItemId: r = null,
-  onItemSelect: u,
+  onItemSelect: l,
   verticalSpacing: p = "xs",
   horizontalSpacing: C = "xs",
   variant: N = "fill"
-}) => {
+}) {
   const h = L(
     (s) => {
-      u == null || u(s);
+      l == null || l(s);
     },
-    [u]
+    [l]
   );
   return { listItems: M(
-    () => (l || []).map((s) => ({
+    () => (u || []).map((s) => ({
       id: s == null ? void 0 : s.id,
       title: (s == null ? void 0 : s[x]) ?? null,
       description: (s == null ? void 0 : s[k]) ?? null,
       item: s,
-      controlItem: o(n, s),
-      customItem: o(d, s),
+      controlItem: f(n, s),
+      customItem: f(o, s),
       internalNumber: s == null ? void 0 : s.internalNumber,
-      trailing: o(f, s),
+      trailing: f(d, s),
       trailingDisplay: b,
       verticalSpacing: p,
       horizontalSpacing: C,
       variant: N,
       active: r != null && (s == null ? void 0 : s.id) === r,
-      ...u && { onClick: () => h(s) }
+      ...l && { onClick: () => h(s) }
     })),
     [
       n,
+      o,
       d,
-      f,
       b,
-      l,
+      u,
       x,
       k,
       r,
-      u,
+      l,
       h,
       p,
       C,
       N
     ]
   ) };
-};
+}
 export {
   q as useListItems
 };