@eyesee/ui-components 0.8.0 → 0.9.0

package/README.md

@@ -76,6 +76,8 @@ Icons are exported from a separate entry point to keep bundles lean:
 import { PlusIcon, DeleteIcon, EditIcon } from '@eyesee/ui-components/icons';
 ```
 
+The package ships TypeScript declaration files generated from JSDoc. In Cursor, VS Code, or any editor with a TypeScript language service, hover a component and use autocomplete to see its props, types, defaults, and descriptions.
+
 ---
 
 ## Components

package/dist/components/Avatar/Avatar.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @typedef {keyof typeof AVATAR_COLOR_PALETTE} AvatarColorKey
+ */
+/**
+ * All props are optional. Invalid `type`, `size`, and `corners` fall back silently.
+ *
+ * @typedef {object} AvatarProps
+ *
+ * @property {'default'|'photo'} [type='default']
+ *   `'default'` shows initials; `'photo'` renders `<img>` when `src` is set.
+ *   Default `'default'`.
+ * @property {'3xs'|'2xs'|'xs'|'s'|'m'|'l'} [size='2xs']
+ *   Visual size token. Default `'2xs'`.
+ * @property {'round'|'square'} [corners='round']
+ *   Border radius variant. Default `'round'`.
+ * @property {string} [initials='JD']
+ *   Up to two characters, uppercased. Default `'JD'`.
+ * @property {string} [src]
+ *   Image URL when `type` is `'photo'`.
+ * @property {string} [alt='']
+ *   Alt text for the photo. Default `''`.
+ * @property {AvatarColorKey} [color]
+ *   Key from `AVATAR_COLOR_PALETTE`. Unrecognized values default to `'purple'`.
+ * @property {string} [className]
+ *   Extra class on the root `<div>`.
+ */
+/**
+ * Avatar with initials or photo. Invalid enum props fall back to defaults.
+ *
+ * ## Props
+ *
+ * All optional.
+ *
+ * **type** `'default' | 'photo'` — default `'default'`
+ * `'default'` shows initials; `'photo'` renders `<img>` when `src` is set.
+ *
+ * **size** `'3xs' | '2xs' | 'xs' | 's' | 'm' | 'l'` — default `'2xs'`
+ * Visual size token.
+ *
+ * **corners** `'round' | 'square'` — default `'round'`
+ * Border radius variant.
+ *
+ * **initials** `string` — default `'JD'`
+ * Up to two characters, uppercased.
+ *
+ * **src** `string` — no default
+ * Image URL when `type` is `'photo'`.
+ *
+ * **alt** `string` — default `''`
+ * Alt text for the photo.
+ *
+ * **color** `AvatarColorKey` — default `'purple'`
+ * Key from `AVATAR_COLOR_PALETTE` (`'purple'`, `'turquoise'`, `'red'`, `'green'`, `'yellow'`, `'orange'`, `'greenyellow'`, `'pink'`, `'blue'`).
+ *
+ * **className** `string` — no default
+ * Extra class on the root `<div>`.
+ *
+ * @param {AvatarProps} props
+ * @returns {import('react').ReactElement}
+ *
+ * @example <caption>Default</caption>
+ * import { Avatar } from '@eyesee/ui-components';
+ *
+ * <Avatar type="default" size="2xs" corners="round" initials="JD" color="purple" />
+ *
+ * @example <caption>Photo</caption>
+ * import { Avatar } from '@eyesee/ui-components';
+ *
+ * <Avatar
+ *   type="photo"
+ *   size="2xs"
+ *   corners="round"
+ *   src="https://example.com/avatar.jpg"
+ *   alt="Avatar photo"
+ *   color="purple"
+ * />
+ *
+ * @example <caption>All variants</caption>
+ * import { Avatar } from '@eyesee/ui-components';
+ *
+ * <Avatar type="default" corners="round" size="m" initials="JD" color="purple" />
+ * <Avatar type="photo" corners="square" size="s" src="https://example.com/avatar.jpg" color="blue" />
+ */
+export function Avatar({ type, size, corners, initials, src, alt, color, className, }: AvatarProps): import("react").ReactElement;
+export const AVATAR_SIZES: readonly ["3xs", "2xs", "xs", "s", "m", "l"];
+export const AVATAR_CORNERS: readonly ["round", "square"];
+export const AVATAR_TYPES: readonly ["default", "photo"];
+export namespace AVATAR_COLOR_PALETTE {
+    let purple: "var(--color--background--avatar--purple)";
+    let turquoise: "var(--color--background--avatar--turquoise)";
+    let red: "var(--color--background--avatar--red)";
+    let green: "var(--color--background--avatar--green)";
+    let yellow: "var(--color--background--avatar--yellow)";
+    let orange: "var(--color--background--avatar--orange)";
+    let greenyellow: "var(--color--background--avatar--greenyellow)";
+    let pink: "var(--color--background--avatar--pink)";
+    let blue: "var(--color--background--avatar--blue)";
+}
+/** @type {(keyof typeof AVATAR_COLOR_PALETTE)[]} */
+export const AVATAR_COLOR_PALETTE_KEYS: (keyof typeof AVATAR_COLOR_PALETTE)[];
+export type AvatarColorKey = keyof typeof AVATAR_COLOR_PALETTE;
+/**
+ * All props are optional. Invalid `type`, `size`, and `corners` fall back silently.
+ */
+export type AvatarProps = {
+    /**
+     * `'default'` shows initials; `'photo'` renders `<img>` when `src` is set.
+     * Default `'default'`.
+     */
+    type?: "default" | "photo";
+    /**
+     * Visual size token. Default `'2xs'`.
+     */
+    size?: "3xs" | "2xs" | "xs" | "s" | "m" | "l";
+    /**
+     * Border radius variant. Default `'round'`.
+     */
+    corners?: "round" | "square";
+    /**
+     * Up to two characters, uppercased. Default `'JD'`.
+     */
+    initials?: string;
+    /**
+     * Image URL when `type` is `'photo'`.
+     */
+    src?: string;
+    /**
+     * Alt text for the photo. Default `''`.
+     */
+    alt?: string;
+    /**
+     * Key from `AVATAR_COLOR_PALETTE`. Unrecognized values default to `'purple'`.
+     */
+    color?: AvatarColorKey;
+    /**
+     * Extra class on the root `<div>`.
+     */
+    className?: string;
+};

package/dist/components/Avatar/Avatar.js

@@ -26,17 +26,18 @@ const b = (
 ), T = (
   /** @type {(keyof typeof AVATAR_COLOR_PALETTE)[]} */
   Object.keys(y)
-), _ = ({
+);
+function _({
   type: o = "default",
   size: e = "2xs",
   corners: n = "round",
-  initials: s = "JD",
+  initials: c = "JD",
   src: t,
-  alt: c = "",
+  alt: s = "",
   color: l,
   className: u
-}) => {
-  const d = b.includes(e) ? e : "2xs", i = k.includes(n) ? n : "round", v = m.includes(o) ? o : "default", p = String(s || "").trim().slice(0, 2).toUpperCase(), g = T.includes(l) ? l : "purple";
+}) {
+  const d = b.includes(e) ? e : "2xs", i = k.includes(n) ? n : "round", v = m.includes(o) ? o : "default", p = String(c || "").trim().slice(0, 2).toUpperCase(), g = T.includes(l) ? l : "purple";
   return /* @__PURE__ */ a(
     "div",
     {
@@ -47,10 +48,10 @@ const b = (
         u
       ),
       style: { backgroundColor: g },
-      children: v === "photo" && t ? /* @__PURE__ */ a("img", { className: r.photo, src: t, alt: c }) : /* @__PURE__ */ a("span", { className: r.initials, children: p })
+      children: v === "photo" && t ? /* @__PURE__ */ a("img", { className: r.photo, src: t, alt: s }) : /* @__PURE__ */ a("span", { className: r.initials, children: p })
     }
   );
-};
+}
 export {
   y as AVATAR_COLOR_PALETTE,
   T as AVATAR_COLOR_PALETTE_KEYS,

package/dist/components/Badge/Badge.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @typedef {object} BadgeProps
+ *
+ * @property {string} [label]
+ *   Label (e.g. `"+100"`). Renders nothing when empty or null.
+ * @property {'rectangle'|'pill'} [shape='rectangle']
+ *   Corner style. Default `'rectangle'`.
+ * @property {'neutral'|'warning'|'error'} [state='neutral']
+ *   Colour variant. Default `'neutral'`.
+ */
+/**
+ * Compact count / overflow badge. Renders nothing when `label` is empty.
+ *
+ * ## Props
+ *
+ * **label** `string` — no default
+ * Label (e.g. `"+100"`). Renders nothing when empty or null.
+ *
+ * **shape** `'rectangle' | 'pill'` — default `'rectangle'`
+ * Rectangle uses subtle radius; pill uses full radius.
+ *
+ * **state** `'neutral' | 'warning' | 'error'` — default `'neutral'`
+ * Background and text colours from design tokens.
+ *
+ * @param {BadgeProps} props
+ * @returns {import('react').ReactElement|null}
+ *
+ * @example <caption>Default</caption>
+ * import { Badge } from '@eyesee/ui-components';
+ *
+ * <Badge label="+100" shape="rectangle" state="neutral" />
+ *
+ * @example <caption>All shapes and states</caption>
+ * import { Badge } from '@eyesee/ui-components';
+ *
+ * <Badge label="+100" shape="rectangle" state="neutral" />
+ * <Badge label="+100" shape="pill" state="warning" />
+ * <Badge label="+100" shape="rectangle" state="error" />
+ *
+ * @example <caption>On image (context)</caption>
+ * import { Badge } from '@eyesee/ui-components';
+ *
+ * <Badge label="+12" shape="rectangle" state="neutral" />
+ */
+export function Badge({ label, shape, state }: BadgeProps): import("react").ReactElement | null;
+export type BadgeProps = {
+    /**
+     * Label (e.g. `"+100"`). Renders nothing when empty or null.
+     */
+    label?: string;
+    /**
+     * Corner style. Default `'rectangle'`.
+     */
+    shape?: "rectangle" | "pill";
+    /**
+     * Colour variant. Default `'neutral'`.
+     */
+    state?: "neutral" | "warning" | "error";
+};

package/dist/components/Badge/Badge.js

@@ -1,11 +1,11 @@
-import { jsx as l } from "react/jsx-runtime";
+import { jsx as s } from "react/jsx-runtime";
 import { getBadgeStyles as a } from "./badgeVariants.js";
-import c from "./Badge.module.scss.js";
-const g = ({ label: r, shape: o = "rectangle", state: e = "neutral" }) => {
+import u from "./Badge.module.scss.js";
+function m({ label: r, shape: o = "rectangle", state: e = "neutral" }) {
   if (r == null || r === "") return null;
-  const { backgroundColor: t, color: n, borderRadius: s } = a(o, e);
-  return /* @__PURE__ */ l("span", { className: c.badge, style: { backgroundColor: t, color: n, borderRadius: s }, children: r });
-};
+  const { backgroundColor: t, color: n, borderRadius: l } = a(o, e);
+  return /* @__PURE__ */ s("span", { className: u.badge, style: { backgroundColor: t, color: n, borderRadius: l }, children: r });
+}
 export {
-  g as Badge
+  m as Badge
 };

package/dist/components/Badge/badgeVariants.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @param {'rectangle'|'pill'} shape
+ * @param {'neutral'|'warning'|'error'} state
+ * @returns {{ backgroundColor: string; color: string; borderRadius: string }}
+ */
+export function getBadgeStyles(shape: "rectangle" | "pill", state: "neutral" | "warning" | "error"): {
+    backgroundColor: string;
+    color: string;
+    borderRadius: string;
+};
+/**
+ * Image overflow / count badge from Figma (Components for DEV).
+ * `shape`: rectangle (4px) | pill (full radius)
+ * `state`: neutral | warning | error
+ */
+export const SHAPES: string[];
+export const STATES: string[];

package/dist/components/Button/Button.d.ts

@@ -0,0 +1,299 @@
+/**
+ * @callback ButtonClickHandler
+ * @param {ButtonOption} [option] Chosen dropdown item. Omitted on a plain click.
+ * @returns {void}
+ */
+/**
+ * Dropdown row. Extra fields are spread onto {@link ListItem}.
+ *
+ * @typedef {object} ButtonOption
+ * @property {string}          value  - Unique React key.
+ * @property {string}          label  - Row text.
+ * @property {React.ReactNode} [icon] - Leading icon (`ListItem.controlItem`).
+ */
+/**
+ * Extra {@link Tooltip} props. Used only when `tooltipContent` is set.
+ *
+ * @typedef {object} ButtonTooltipProps
+ * @property {'top'|'bottom'|'left'|'right'} [position='bottom']
+ * @property {'dark'|'light'}                [variant='light']
+ */
+/**
+ * All props are optional. Rest props go to the wrapper `<div>`.
+ *
+ * @typedef {object} ButtonProps
+ *
+ * @property {string}            [text]
+ *   Label. Omit with `icon` (no dropdown) for icon-only.
+ * @property {React.ReactNode}   [icon]
+ *   Leading icon. Default `null`.
+ *
+ * @property {'lg'|'md'|'sm'|'xs'|'xxs'|'xxxs'} [size='md']
+ *   Height and padding. Default `'md'`.
+ * @property {'primary'|'secondary'|'neutral'|'destructive'} [variant='primary']
+ *   Colour. Default `'primary'`.
+ * @property {'fill'|'outline'|'blank'} [type='fill']
+ *   Visual style, not HTML `type`. Default `'fill'`.
+ * @property {boolean}           [fullWidth=false]
+ *   Stretch to 100% width. Default `false`.
+ * @property {string}            [className]
+ *   Extra class on the wrapper `<div>`.
+ *
+ * @property {boolean}           [disabled=false]
+ *   Native disabled. Blocks clicks and dropdown. Default `false`.
+ * @property {boolean}           [pressed=false]
+ *   Toggle / selected look (`aria-pressed`). Default `false`.
+ *
+ * @property {ButtonClickHandler} [onClick]
+ *   Plain click: no args. Dropdown: fired with the chosen option, not on
+ *   open/close. Default `() => {}`.
+ *
+ * @property {ButtonOption[]}    [options=[]]
+ *   Non-empty → {@link ListItem} dropdown. Default `[]`.
+ * @property {'start'|'end'}     [dropdownAlign='start']
+ *   `'start'` left edges, `'end'` right edges. Default `'start'`.
+ * @property {React.ReactNode}   [dropdownCustomContent]
+ *   Custom dropdown body. Enables dropdown even if `options` is empty.
+ *   Default `null`.
+ * @property {'s'|'m'|'l'|'xl'|'xxl'|'4xl'} [iconSize='m']
+ *   Dropdown chevron size only. Default `'m'`.
+ *
+ * @property {React.ReactNode}   [tooltipContent]
+ *   Wraps the button in {@link Tooltip} when set. Default `null`.
+ * @property {string}            [tooltipTitle]
+ *   Tooltip heading.
+ * @property {ButtonTooltipProps} [tooltipProps]
+ *   Extra {@link Tooltip} props. Default `{ position: 'bottom', variant: 'light' }`.
+ *
+ * @see {@link Tooltip}
+ * @see {@link ListItem}
+ * @see {@link DropdownList}
+ */
+/**
+ * Action button. Dropdown when `options` or `dropdownCustomContent` is set.
+ *
+ * ## Props
+ *
+ * All optional. Rest props go to the wrapper `<div>`.
+ *
+ * **text** `string` — no default
+ * Button label. Omit with `icon` (no dropdown) for icon-only.
+ *
+ * **icon** `ReactNode` — default `null`
+ * Leading icon.
+ *
+ * **size** `'lg' | 'md' | 'sm' | 'xs' | 'xxs' | 'xxxs'` — default `'md'`
+ * Height and padding.
+ *
+ * **variant** `'primary' | 'secondary' | 'neutral' | 'destructive'` — default `'primary'`
+ * Colour.
+ *
+ * **type** `'fill' | 'outline' | 'blank'` — default `'fill'`
+ * Visual style (not HTML `type`).
+ *
+ * **fullWidth** `boolean` — default `false`
+ * Stretch to 100% width.
+ *
+ * **className** `string` — no default
+ * Extra class on the wrapper `<div>`.
+ *
+ * **disabled** `boolean` — default `false`
+ * Native disabled. Blocks clicks and dropdown.
+ *
+ * **pressed** `boolean` — default `false`
+ * Toggle / selected look (`aria-pressed`).
+ *
+ * **onClick** `(option?: ButtonOption) => void` — default `() => {}`
+ * Plain click: no args. Dropdown: fired with the chosen option, not on open/close.
+ *
+ * **options** `ButtonOption[]` — default `[]`
+ * Non-empty → {@link ListItem} dropdown. Extra item fields go to ListItem.
+ * - `value` `string` — required. Unique React key.
+ * - `label` `string` — required. Row text.
+ * - `icon` `ReactNode` — optional. Leading icon.
+ *
+ * **dropdownAlign** `'start' | 'end'` — default `'start'`
+ * `'start'` left edges, `'end'` right edges.
+ *
+ * **dropdownCustomContent** `ReactNode` — default `null`
+ * Custom dropdown body. Enables dropdown even if `options` is empty.
+ *
+ * **iconSize** `'s' | 'm' | 'l' | 'xl' | 'xxl' | '4xl'` — default `'m'`
+ * Dropdown chevron size only.
+ *
+ * **tooltipContent** `ReactNode` — default `null`
+ * Wraps the button in {@link Tooltip} when set.
+ *
+ * **tooltipTitle** `string` — no default
+ * Tooltip heading.
+ *
+ * **tooltipProps** `ButtonTooltipProps` — default `{ position: 'bottom', variant: 'light' }`
+ * Extra {@link Tooltip} props. Used only when `tooltipContent` is set.
+ * - `position` `'top' | 'bottom' | 'left' | 'right'` — default `'bottom'`
+ * - `variant` `'dark' | 'light'` — default `'light'`
+ *
+ * @param {ButtonProps} props
+ * @returns {import('react').ReactElement}
+ *
+ * @example <caption>Default</caption>
+ * import { Button } from '@eyesee/ui-components';
+ *
+ * <Button text="Button" />
+ *
+ * @example <caption>With icon</caption>
+ * import { Button } from '@eyesee/ui-components';
+ * import { PlusIcon } from '@eyesee/ui-components/icons';
+ *
+ * <Button text="Button" icon={<PlusIcon />} />
+ *
+ * @example <caption>Icon-only with tooltip</caption>
+ * import { Button } from '@eyesee/ui-components';
+ * import { PlusIcon } from '@eyesee/ui-components/icons';
+ *
+ * <Button icon={<PlusIcon />} tooltipContent="Add item" />
+ *
+ * @example <caption>Dropdown</caption>
+ * import { Button } from '@eyesee/ui-components';
+ *
+ * <Button
+ *   text="Button"
+ *   options={[
+ *     { value: 'edit', label: 'Edit' },
+ *     { value: 'delete', label: 'Delete' },
+ *     { value: 'export', label: 'Export' },
+ *   ]}
+ * />
+ *
+ * @example <caption>Pressed</caption>
+ * import { Button } from '@eyesee/ui-components';
+ *
+ * <Button text="Button" pressed />
+ *
+ * @example <caption>Fill, outline, blank, disabled</caption>
+ * import { Button } from '@eyesee/ui-components';
+ *
+ * <Button text="Button" type="fill" />
+ * <Button text="Button" type="outline" />
+ * <Button text="Button" type="blank" />
+ * <Button text="Button" disabled />
+ *
+ * @example <caption>Full width</caption>
+ * import { Button } from '@eyesee/ui-components';
+ *
+ * <Button text="Button" fullWidth />
+ *
+ * @example <caption>Dropdown with custom content</caption>
+ * import { Button, ListItem } from '@eyesee/ui-components';
+ *
+ * <Button
+ *   text="Actions"
+ *   dropdownCustomContent={
+ *     <>
+ *       <ListItem role="menuitem" title="Edit" horizontalSpacing="xs" verticalSpacing="none" />
+ *       <ListItem role="menuitem" title="Duplicate" horizontalSpacing="xs" verticalSpacing="none" />
+ *       <ListItem role="menuitem" title="Delete" horizontalSpacing="xs" verticalSpacing="none" />
+ *     </>
+ *   }
+ * />
+ */
+export function Button({ text, options, onClick, className, iconSize, size, variant, type, pressed, icon, tooltipContent, tooltipTitle, disabled, fullWidth, dropdownAlign, tooltipProps, dropdownCustomContent, ...props }: ButtonProps): import("react").ReactElement;
+export type ButtonClickHandler = (option?: ButtonOption) => void;
+/**
+ * Dropdown row. Extra fields are spread onto {@link ListItem}.
+ */
+export type ButtonOption = {
+    /**
+     * - Unique React key.
+     */
+    value: string;
+    /**
+     * - Row text.
+     */
+    label: string;
+    /**
+     * - Leading icon (`ListItem.controlItem`).
+     */
+    icon?: React.ReactNode;
+};
+/**
+ * Extra {@link Tooltip} props. Used only when `tooltipContent` is set.
+ */
+export type ButtonTooltipProps = {
+    position?: "top" | "bottom" | "left" | "right";
+    variant?: "dark" | "light";
+};
+/**
+ * All props are optional. Rest props go to the wrapper `<div>`.
+ */
+export type ButtonProps = {
+    /**
+     * Label. Omit with `icon` (no dropdown) for icon-only.
+     */
+    text?: string;
+    /**
+     * Leading icon. Default `null`.
+     */
+    icon?: React.ReactNode;
+    /**
+     * Height and padding. Default `'md'`.
+     */
+    size?: "lg" | "md" | "sm" | "xs" | "xxs" | "xxxs";
+    /**
+     * Colour. Default `'primary'`.
+     */
+    variant?: "primary" | "secondary" | "neutral" | "destructive";
+    /**
+     * Visual style, not HTML `type`. Default `'fill'`.
+     */
+    type?: "fill" | "outline" | "blank";
+    /**
+     * Stretch to 100% width. Default `false`.
+     */
+    fullWidth?: boolean;
+    /**
+     * Extra class on the wrapper `<div>`.
+     */
+    className?: string;
+    /**
+     * Native disabled. Blocks clicks and dropdown. Default `false`.
+     */
+    disabled?: boolean;
+    /**
+     * Toggle / selected look (`aria-pressed`). Default `false`.
+     */
+    pressed?: boolean;
+    /**
+     * Plain click: no args. Dropdown: fired with the chosen option, not on
+     * open/close. Default `() => {}`.
+     */
+    onClick?: ButtonClickHandler;
+    /**
+     * Non-empty → {@link ListItem} dropdown. Default `[]`.
+     */
+    options?: ButtonOption[];
+    /**
+     * `'start'` left edges, `'end'` right edges. Default `'start'`.
+     */
+    dropdownAlign?: "start" | "end";
+    /**
+     * Custom dropdown body. Enables dropdown even if `options` is empty.
+     * Default `null`.
+     */
+    dropdownCustomContent?: React.ReactNode;
+    /**
+     * Dropdown chevron size only. Default `'m'`.
+     */
+    iconSize?: "s" | "m" | "l" | "xl" | "xxl" | "4xl";
+    /**
+     * Wraps the button in {@link Tooltip} when set. Default `null`.
+     */
+    tooltipContent?: React.ReactNode;
+    /**
+     * Tooltip heading.
+     */
+    tooltipTitle?: string;
+    /**
+     * Extra {@link Tooltip} props. Default `{ position: 'bottom', variant: 'light' }`.
+     */
+    tooltipProps?: ButtonTooltipProps;
+};

package/dist/components/Button/Button.js

@@ -8,7 +8,7 @@ import { ListItem as U } from "../ListItem/ListItem.js";
 import { DropdownList as q } from "../DropdownList/DropdownList.js";
 import { Tooltip as z } from "../Tooltip/Tooltip.js";
 import e from "./Button.module.scss.js";
-const Y = ({
+function Y({
   text: l,
   options: p = [],
   onClick: u = () => {
@@ -28,7 +28,7 @@ const Y = ({
   tooltipProps: k = { position: "bottom", variant: "light" },
   dropdownCustomContent: s = null,
   ...B
-}) => {
+}) {
   const [o, i] = L(!1), b = R(null);
   E(b, () => i(!1));
   const T = (n) => {
@@ -95,7 +95,7 @@ const Y = ({
     }
   );
   return C ? /* @__PURE__ */ r(z, { title: g, content: d, ...k, children: I }) : I;
-};
+}
 export {
   Y as Button
 };