@eyesee/ui-components 0.1.0 → 0.1.2

package/README.md

@@ -1,37 +1,291 @@
-# @eyesee/ui-components
-
-Shared EyeSee React components and design tokens.
-
-## Usage
-
-Import the package styles once at the application entry point:
-
-```js
-import '@eyesee/ui-components/styles';
-```
-
-Apply `alias--main` and exactly one application profile class (`mapped--internal`
-or `mapped--external`) on an ancestor that also contains portal content,
-preferably `body`.
-
-`Modal` uses `#modal` when it exists and otherwise falls back to `document.body`.
-Use its `portalContainer` prop to provide a different host and
-`loadingFallback` to customize its Suspense fallback. `Tooltip` also accepts
-`portalContainer` and otherwise renders into `document.body`.
-
-The consuming application must install the package peer dependencies listed in
-`package.json`. `Notifications` requires a single rendered toast host from
-`react-toastify`; use the exported `Notifications` component and
-`useNotifications` hook.
-
-## Development
-
-```bash
-npm run storybook
-npm run build
-npm run build-storybook
-npm run pack:check
-```
-
-The Storybook toolbar switches between the Internal and External application
-style profiles.
+# @eyesee/ui-components
+
+Shared EyeSee React component library and design tokens.
+
+**Live Storybook:** https://qa-test-components.eyesee-collab.com
+
+---
+
+## Installation
+
+```bash
+npm install @eyesee/ui-components
+```
+
+### Peer dependencies
+
+Install these in your consuming application if not already present:
+
+```bash
+npm install react react-dom clsx react-hook-form react-toastify
+```
+
+---
+
+## Setup
+
+### 1. Import styles
+
+Import the stylesheet **once** at your application entry point (e.g. `main.jsx` or `App.jsx`):
+
+```js
+import '@eyesee/ui-components/styles';
+```
+
+### 2. Apply theme classes
+
+Add `alias--main` and exactly one profile class to a common ancestor element — ideally `<body>`. The profile class controls the visual theme of the library:
+
+| Class | Use for |
+|---|---|
+| `alias--main` | Always required |
+| `mapped--internal` | Internal EyeSee tools |
+| `mapped--external` | External-facing applications |
+
+```html
+<body class="alias--main mapped--internal">
+  ...
+</body>
+```
+
+Or in React:
+
+```jsx
+useEffect(() => {
+    document.body.classList.add('alias--main', 'mapped--internal');
+}, []);
+```
+
+The Storybook toolbar switches between the two profiles so you can preview both themes side by side.
+
+---
+
+## Usage
+
+All components are exported from the package root:
+
+```jsx
+import { Button, InputField, Modal, Toggle } from '@eyesee/ui-components';
+```
+
+Icons are exported from a separate entry point to keep bundles lean:
+
+```jsx
+import { PlusIcon, DeleteIcon, EditIcon } from '@eyesee/ui-components/icons';
+```
+
+---
+
+## Components
+
+### Layout & Feedback
+
+| Component | Description |
+|---|---|
+| `Modal` | Dialog overlay with title, description, icon, and footer slots |
+| `Infobox` | Inline status message with icon, title, and body text |
+| `ProgressBar` | Determinate progress indicator with optional label and percentage |
+| `ExpandableItem` | Collapsible `<details>`-based section with a summary title |
+
+### Navigation & Selection
+
+| Component | Description |
+|---|---|
+| `Tabs` | Tab group managing selection state; wraps `Tab` |
+| `Tab` | Individual tab rendered as a button or span |
+
+### Inputs & Form Fields
+
+| Component | Description |
+|---|---|
+| `InputField` | Single-line text input with label, icons, error, and info text |
+| `TextField` | Multi-line textarea with label, action buttons, error, and info text |
+| `SelectField` | Dropdown select with label and error support |
+| `Checkbox` | Checkbox with label, indeterminate state, and size variants |
+| `Radio` | Radio button with label and size variants |
+| `Toggle` | Switch (checkbox) with label and size variants |
+
+### Buttons & Actions
+
+| Component | Description |
+|---|---|
+| `Button` | Primary action button with optional dropdown menu |
+| `DropdownList` | Scrollable menu container; used by `Button` internally |
+
+### Display
+
+| Component | Description |
+|---|---|
+| `Avatar` | User avatar as initials or photo with size and corner variants |
+| `Badge` | Numeric or text badge in rectangle or pill shape |
+| `Pill` | Status indicator with icon and color/status variants |
+| `Tag` | Label chip with optional dismiss button |
+| `ListItem` | Row with title, description, trailing action icons, and slots |
+| `FileType` | File type icon indicator |
+| `ImagePlaceholder` | Placeholder shown while an image loads |
+| `ImageWithData` | Image with overlaid metadata |
+| `TextHoverable` | Text that reveals additional content on hover |
+| `Tooltip` | Floating label anchored to a trigger element |
+| `EllipsisTooltip` | Tooltip that only activates when text is truncated |
+
+### Notifications
+
+| Component | Description |
+|---|---|
+| `Notifications` | Toast notification card (title, text, type, actions) |
+| `useNotifications` | Hook for triggering toasts imperatively |
+
+Notifications require a single `<ToastContainer>` from `react-toastify` in your app:
+
+```jsx
+import { ToastContainer } from 'react-toastify';
+import { useNotifications } from '@eyesee/ui-components';
+
+function App() {
+    return (
+        <>
+            <ToastContainer />
+            <YourApp />
+        </>
+    );
+}
+
+function SomeComponent() {
+    const { notify } = useNotifications();
+
+    return (
+        <button onClick={() => notify({ title: 'Saved!', text: 'Your changes were saved.', type: 'success' })}>
+            Save
+        </button>
+    );
+}
+```
+
+---
+
+## Portals
+
+`Modal` and `Tooltip` render into a portal. By default they target `document.body`. Use the `portalContainer` prop to override the host element:
+
+```jsx
+<Modal visible portalContainer={document.getElementById('modal-root')} />
+```
+
+If a `#modal` element exists in the DOM, `Modal` will prefer it automatically. Both components accept a `loadingFallback` prop to customise the Suspense fallback shown while lazy-loaded content resolves.
+
+> **Important:** The `alias--main` and profile classes must be on an ancestor that also contains any portal containers, so that CSS custom properties are inherited correctly.
+
+---
+
+## Examples
+
+### Button with dropdown
+
+```jsx
+import { Button } from '@eyesee/ui-components';
+import { DeleteIcon, EditIcon } from '@eyesee/ui-components/icons';
+
+const options = [
+    { value: 'edit', label: 'Edit', icon: <EditIcon /> },
+    { value: 'delete', label: 'Delete', icon: <DeleteIcon /> },
+];
+
+<Button
+    text="Actions"
+    variant="primary"
+    options={options}
+    onClick={(option) => console.log(option.value)}
+/>
+```
+
+### Form fields
+
+```jsx
+import { InputField, TextField, Toggle } from '@eyesee/ui-components';
+
+<InputField
+    label="Email"
+    type="email"
+    required
+    value={email}
+    onChange={(e) => setEmail(e.target.value)}
+    error={errors.email}
+    infoText="We'll never share your email."
+/>
+
+<TextField
+    label="Notes"
+    rows={4}
+    value={notes}
+    onChange={(e) => setNotes(e.target.value)}
+    actions={[{ id: 'save', text: 'Save', onClick: handleSave }]}
+/>
+
+<Toggle
+    label="Enable notifications"
+    checked={enabled}
+    onChange={(e) => setEnabled(e.target.checked)}
+/>
+```
+
+### Modal with footer actions
+
+```jsx
+import { Modal, Button } from '@eyesee/ui-components';
+
+<Modal
+    visible={isOpen}
+    title="Delete item"
+    description="This action cannot be undone."
+    onClose={() => setIsOpen(false)}
+    footer={
+        <>
+            <Button text="Cancel" variant="neutral" type="outline" onClick={() => setIsOpen(false)} />
+            <Button text="Delete" variant="destructive" onClick={handleDelete} />
+        </>
+    }
+/>
+```
+
+### ListItem with trailing actions
+
+```jsx
+import { ListItem } from '@eyesee/ui-components';
+import { EditIcon, DeleteIcon } from '@eyesee/ui-components/icons';
+
+<ListItem
+    title="Project Alpha"
+    description="Last updated 2 days ago"
+    item={project}
+    trailing={[
+        { type: 'edit', icon: <EditIcon />, onClick: (item) => handleEdit(item) },
+        { type: 'delete', icon: <DeleteIcon />, onClick: (item) => handleDelete(item) },
+    ]}
+/>
+```
+
+---
+
+## Development
+
+```bash
+# Start Storybook dev server (port 6006)
+npm run storybook
+
+# Run unit tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Build the library
+npm run build
+
+# Build Storybook
+npm run build-storybook
+
+# Preview what gets published to npm
+npm run pack:check
+```
+
+See [UI_LIBRARY_RELEASE_GUIDE.md](./UI_LIBRARY_RELEASE_GUIDE.md) for versioning, release flow, and CI/CD details.

package/dist/components/Button/Button.js

@@ -1,10 +1,10 @@
-import { jsxs as c, jsx as n } from "react/jsx-runtime";
+import { jsxs as m, jsx as n } from "react/jsx-runtime";
 import { useState as W, useRef as j } from "react";
-import m from "clsx";
+import c from "clsx";
 import { ChevronDownIcon as B } from "../icons-v2/ChevronDownIcon.js";
 import { ChevronUpIcon as L } from "../icons-v2/ChevronUpIcon.js";
 import R from "../../hooks/useClickOutside.js";
-import t from "./Button.module.scss.js";
+import e from "./Button.module.scss.js";
 import { ListItem as S } from "../ListItem/ListItem.js";
 import { DropdownList as A } from "../DropdownList/DropdownList.js";
 import { Tooltip as E } from "../Tooltip/Tooltip.js";
@@ -29,62 +29,63 @@ const Q = ({
 }) => {
   const [s, o] = W(!1), h = j(null);
   R(h, () => o(!1));
-  const x = (e) => {
-    i(e), o(!1);
-  }, D = a && !l && r.length === 0, k = a && !l, T = !!u, f = /* @__PURE__ */ c(
+  const x = (t) => {
+    i(t), o(!1);
+  }, D = a && !l && r.length === 0, k = a && !l, T = !!u, f = /* @__PURE__ */ m(
     "div",
     {
       ref: h,
       "data-button-wrapper": !0,
-      className: m(t.wrapper, d, C && t.fullWidth),
+      className: c(e.wrapper, d, C && e.fullWidth),
       ...y,
       children: [
-        /* @__PURE__ */ c(
+        /* @__PURE__ */ m(
           "button",
           {
             type: "button",
-            className: m(
-              t.button,
-              t[b],
-              t[g],
-              t[w],
-              r.length > 0 && t.hasDropdown,
-              D && t.iconOnly,
-              k && t.isIcon
+            className: c(
+              e.button,
+              e[b],
+              e[g],
+              e[w],
+              r.length > 0 && e.hasDropdown,
+              D && e.iconOnly,
+              k && e.isIcon
             ),
-            onClick: () => r.length > 0 ? o((e) => !e) : i(),
+            onClick: () => r.length > 0 ? o((t) => !t) : i(),
             "aria-expanded": s,
             "aria-haspopup": "menu",
             disabled: v,
             children: [
-              /* @__PURE__ */ c(
+              /* @__PURE__ */ m(
                 "span",
                 {
-                  className: m(
-                    t.buttonContent,
-                    r.length > 0 && t.buttonContentDropdown
+                  className: c(
+                    e.buttonContent,
+                    r.length > 0 && e.buttonContentDropdown
                   ),
                   children: [
-                    a && /* @__PURE__ */ n("span", { className: t.icon, children: a }),
-                    l && /* @__PURE__ */ n("span", { className: t.buttonText, children: l })
+                    a && /* @__PURE__ */ n("span", { className: e.icon, children: a }),
+                    l && /* @__PURE__ */ n("span", { className: e.buttonText, children: l })
                   ]
                 }
               ),
-              r.length > 0 && /* @__PURE__ */ n("span", { className: t.buttonArrow, children: s ? /* @__PURE__ */ n(L, { iconSize: p }) : /* @__PURE__ */ n(B, { iconSize: p }) })
+              r.length > 0 && /* @__PURE__ */ n("span", { className: e.buttonArrow, children: s ? /* @__PURE__ */ n(L, { iconSize: p }) : /* @__PURE__ */ n(B, { iconSize: p }) })
             ]
           }
         ),
-        s && r.length > 0 && /* @__PURE__ */ n(A, { align: N, children: r.map((e) => /* @__PURE__ */ n(
+        s && r.length > 0 && /* @__PURE__ */ n(A, { align: N, children: r.map((t) => /* @__PURE__ */ n(
           S,
           {
-            title: e.label,
-            controlItem: e == null ? void 0 : e.icon,
+            role: "menuitem",
+            title: t.label,
+            controlItem: t == null ? void 0 : t.icon,
             horizontalSpacing: "xs",
             verticalSpacing: "none",
-            ...e,
-            onClick: () => x(e)
+            ...t,
+            onClick: () => x(t)
           },
-          e.value
+          t.value
         )) })
       ]
     }

package/dist/components/Button/Button.module.scss.js

@@ -1,51 +1,53 @@
-const n = "_fullWidth_1l23j_1", t = "_button_1l23j_4", o = "_wrapper_1l23j_8", _ = "_buttonContent_1l23j_25", l = "_icon_1l23j_25", s = "_buttonArrow_1l23j_26", c = "_buttonText_1l23j_34", r = "_iconOnly_1l23j_58", u = "_buttonContentDropdown_1l23j_61", e = "_hasDropdown_1l23j_67", j = "_lg_1l23j_83", x = "_isIcon_1l23j_86", i = "_md_1l23j_90", a = "_sm_1l23j_97", b = "_xs_1l23j_104", d = "_xxs_1l23j_111", p = "_xxxs_1l23j_118", w = "_primary_1l23j_128", y = "_fill_1l23j_128", m = "_outline_1l23j_159", f = "_blank_1l23j_172", h = "_secondary_1l23j_219", C = "_neutral_1l23j_310", D = {
-  fullWidth: n,
-  button: t,
+const t = "_fullWidth_1bpdq_1", n = "_button_1bpdq_4", o = "_wrapper_1bpdq_8", _ = "_buttonContent_1bpdq_25", s = "_icon_1bpdq_25", d = "_buttonArrow_1bpdq_26", b = "_buttonText_1bpdq_34", c = "_iconOnly_1bpdq_58", p = "_buttonContentDropdown_1bpdq_61", r = "_hasDropdown_1bpdq_67", e = "_lg_1bpdq_83", l = "_isIcon_1bpdq_86", u = "_md_1bpdq_90", i = "_sm_1bpdq_97", q = "_xs_1bpdq_104", x = "_xxs_1bpdq_111", a = "_xxxs_1bpdq_118", w = "_primary_1bpdq_128", y = "_fill_1bpdq_128", m = "_outline_1bpdq_159", f = "_blank_1bpdq_172", h = "_secondary_1bpdq_219", C = "_destructive_1bpdq_310", D = "_neutral_1bpdq_401", g = {
+  fullWidth: t,
+  button: n,
   wrapper: o,
   buttonContent: _,
-  icon: l,
-  buttonArrow: s,
-  buttonText: c,
-  iconOnly: r,
-  buttonContentDropdown: u,
-  hasDropdown: e,
-  lg: j,
-  isIcon: x,
-  md: i,
-  sm: a,
-  xs: b,
-  xxs: d,
-  xxxs: p,
+  icon: s,
+  buttonArrow: d,
+  buttonText: b,
+  iconOnly: c,
+  buttonContentDropdown: p,
+  hasDropdown: r,
+  lg: e,
+  isIcon: l,
+  md: u,
+  sm: i,
+  xs: q,
+  xxs: x,
+  xxxs: a,
   primary: w,
   fill: y,
   outline: m,
   blank: f,
   secondary: h,
-  neutral: C
+  destructive: C,
+  neutral: D
 };
 export {
   f as blank,
-  t as button,
-  s as buttonArrow,
+  n as button,
+  d as buttonArrow,
   _ as buttonContent,
-  u as buttonContentDropdown,
-  c as buttonText,
-  D as default,
+  p as buttonContentDropdown,
+  b as buttonText,
+  g as default,
+  C as destructive,
   y as fill,
-  n as fullWidth,
-  e as hasDropdown,
-  l as icon,
-  r as iconOnly,
-  x as isIcon,
-  j as lg,
-  i as md,
-  C as neutral,
+  t as fullWidth,
+  r as hasDropdown,
+  s as icon,
+  c as iconOnly,
+  l as isIcon,
+  e as lg,
+  u as md,
+  D as neutral,
   m as outline,
   w as primary,
   h as secondary,
-  a as sm,
+  i as sm,
   o as wrapper,
-  b as xs,
-  d as xxs,
-  p as xxxs
+  q as xs,
+  x as xxs,
+  a as xxxs
 };

package/dist/components/Checkbox/Checkbox.js

@@ -1,51 +1,50 @@
 import { jsxs as z, jsx as r } from "react/jsx-runtime";
 import { useId as C } from "react";
-import t from "clsx";
+import n from "clsx";
 import o from "./Checkbox.module.scss.js";
 import { CheckmarkLargeIcon as I } from "../icons-v2/CheckmarkLargeIcon.js";
 import { MinusIcon as y } from "../icons-v2/MinusIcon.js";
 import { iconSizes as a } from "../icons-v2/constants.js";
-const N = (e) => e === "lg" ? "m" : "s", M = ({
+const N = (e) => e === "lg" ? "m" : "s", W = ({
   label: e,
   checked: c = !1,
-  indeterminate: m = !1,
-  onChange: p = () => {
+  indeterminate: t = !1,
+  onChange: m = () => {
   },
   disabled: i = !1,
-  size: x = "md",
-  id: d,
-  name: f,
-  value: h,
-  "aria-label": k
+  size: p = "md",
+  id: x,
+  name: d,
+  value: f,
+  "aria-label": h
 }) => {
-  const b = C(), l = d ?? b, s = N(x), u = a[s] ?? a.m, n = "var(--color--icon--on-color--on-color)";
+  const k = C(), b = x ?? k, s = N(p), u = a[s] ?? a.m, l = "var(--color--icon--on-color--on-color)";
   return /* @__PURE__ */ z(
     "label",
     {
-      className: t(o.checkboxWrapper, i && o.disabled),
+      className: n(o.checkboxWrapper, i && o.disabled),
       style: { "--checkbox-size": u },
-      htmlFor: l,
       children: [
         /* @__PURE__ */ r(
           "input",
           {
-            id: l,
+            id: b,
             type: "checkbox",
-            name: f,
-            value: h,
+            name: d,
+            value: f,
             className: o.input,
             checked: c,
             disabled: i,
-            "aria-label": k ?? (e ? void 0 : "checkbox"),
-            onChange: p
+            "aria-label": h ?? (e ? void 0 : "checkbox"),
+            onChange: m
           }
         ),
-        /* @__PURE__ */ r("span", { className: t(o.checkbox, c && o.filled), "aria-hidden": !0, children: c && (m ? /* @__PURE__ */ r(y, { iconSize: s, strokeColor: n }) : /* @__PURE__ */ r(I, { iconSize: s, strokeColor: n })) }),
+        /* @__PURE__ */ r("span", { className: n(o.checkbox, c && o.filled), "aria-hidden": !0, children: c && (t ? /* @__PURE__ */ r(y, { iconSize: s, strokeColor: l }) : /* @__PURE__ */ r(I, { iconSize: s, strokeColor: l })) }),
         e ? /* @__PURE__ */ r("span", { className: o.labelText, children: e }) : null
       ]
     }
   );
 };
 export {
-  M as Checkbox
+  W as Checkbox
 };

package/dist/components/DropdownList/DropdownList.js

@@ -1,37 +1,40 @@
-import { jsx as u } from "react/jsx-runtime";
-import f from "clsx";
+import { jsx as g } from "react/jsx-runtime";
+import w from "clsx";
 import r from "./DropdownList.module.scss.js";
-const h = ({
+const a = ({
   children: e,
-  align: n = "start",
-  className: s,
+  align: s = "start",
+  className: n,
   dir: o = "down",
   id: c,
-  maxWidth: p = "320px",
-  maxHeight: i,
-  onLoadMore: t
+  listRef: p,
+  maxWidth: i = "320px",
+  maxHeight: m,
+  onLoadMore: t,
+  style: d
 }) => {
-  const m = (d) => {
-    const l = d.currentTarget;
+  const f = (u) => {
+    const l = u.currentTarget;
     l.scrollHeight - l.scrollTop - l.clientHeight < 48 && (t == null || t());
   };
-  return /* @__PURE__ */ u(
+  return /* @__PURE__ */ g(
     "ul",
     {
+      ref: p,
       id: c,
-      className: f(
+      className: w(
         r.dropdown,
         o === "up" && r.dropdownUp,
-        n === "end" && r.alignEnd,
-        s
+        s === "end" && r.alignEnd,
+        n
       ),
       role: "menu",
-      style: { maxWidth: p, maxHeight: i },
-      onScroll: m,
+      style: { maxWidth: i, maxHeight: m, ...d },
+      onScroll: f,
       children: e
     }
   );
 };
 export {
-  h as DropdownList
+  a as DropdownList
 };