@paul-portfolio/react 0.2.0 → 0.4.0

package/dist/Avatar.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cx } from './cx';
-export function Avatar({ src, alt, size, fallback }) {
+export function Avatar({ src, alt, size = 'md', fallback }) {
     return (_jsx("div", { className: cx('avatar', size && `avatar--${size}`), children: src ? (_jsx("img", { src: src, alt: alt })) : (_jsx("span", { className: "avatar--fallback", children: fallback })) }));
 }

package/dist/Chip.d.ts

@@ -1,10 +1,17 @@
-import type { HTMLAttributes } from 'react';
-type ChipProps = HTMLAttributes<HTMLSpanElement> & {
+import type { HTMLAttributes, MouseEvent } from 'react';
+type ChipProps = Omit<HTMLAttributes<HTMLSpanElement>, 'onClick'> & {
     label: string;
+    /** Background color (any CSS color). Text flips to white when set. */
+    color?: string;
     size?: 'sm' | 'md';
+    /** Stretch to fill the container (e.g. a grid cell). */
+    fullWidth?: boolean;
     clickable?: boolean;
     removable?: boolean;
+    /** When set, the label becomes a real button. */
+    onClick?: (e: MouseEvent<HTMLButtonElement>) => void;
     onRemove?: () => void;
+    title?: string;
 };
-export declare function Chip({ label, size, clickable, removable, onClick, onRemove, className, ...props }: ChipProps): import("react").JSX.Element;
+export declare function Chip({ label, color, size, fullWidth, clickable, removable, onClick, onRemove, title, className, ...props }: ChipProps): import("react").JSX.Element;
 export {};

package/dist/Chip.js

@@ -1,8 +1,20 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from './cx';
-export function Chip({ label, size, clickable, removable, onClick, onRemove, className, ...props }) {
-    return (_jsxs("span", { className: cx('chip', size && size !== 'md' && `chip--${size}`, clickable && 'chip--clickable', removable && 'chip--removable', className), onClick: onClick, ...props, children: [label, removable && (_jsx("button", { type: "button", className: "chip__remove", "aria-label": "Remove", onClick: (e) => {
-                    e.stopPropagation();
-                    onRemove?.();
-                } }))] }));
+export function Chip({ label, color, size, fullWidth, clickable, removable, onClick, onRemove, title, className, ...props }) {
+    const showRemove = removable || !!onRemove;
+    const interactive = clickable || !!onClick;
+    const classes = cx('chip', size && size !== 'md' && `chip--${size}`, interactive && 'chip--clickable', showRemove && 'chip--removable', fullWidth && 'chip--full-width', className);
+    const style = color
+        ? { backgroundColor: color, color: '#fff' }
+        : undefined;
+    const remove = showRemove ? (_jsx("button", { type: "button", className: "chip__remove", "aria-label": `Remove ${label}`, onClick: (e) => {
+            e.stopPropagation();
+            onRemove?.();
+        }, children: _jsx("span", { "aria-hidden": "true", children: "\u00D7" }) })) : null;
+    // A clickable chip puts the label in its own button so it's keyboard
+    // reachable, with the remove button as a sibling (no button-in-button).
+    if (onClick) {
+        return (_jsxs("span", { className: classes, style: style, title: title, ...props, children: [_jsx("button", { type: "button", className: "chip__label", onClick: onClick, children: label }), remove] }));
+    }
+    return (_jsxs("span", { className: classes, style: style, title: title, ...props, children: [label, remove] }));
 }

package/dist/InfoTip.d.ts

@@ -1,13 +1,19 @@
+import type { ReactNode } from 'react';
 type InfoTipProps = {
-    /** The explanatory text shown in the tooltip. */
-    content: string;
+    /** The explanation shown in the popover. Text or rich nodes. */
+    content: ReactNode;
     side?: 'top' | 'bottom' | 'left' | 'right';
     /** Accessible name for the trigger. Defaults to "More information". */
     label?: string;
+    /** Max width of the popover in px. */
+    maxWidth?: number;
+    /** Delay before showing, in ms. */
+    delay?: number;
 };
 /**
- * A small "i" glyph that reveals a tooltip on hover or focus. A convenience
- * wrapper over Tooltip for the very common "explain this label" case.
+ * A small "i" glyph that reveals a popover on hover or focus. Built on Tooltip,
+ * so it renders at a fixed position (never clipped) and accepts rich content —
+ * the common "explain this label" case, with room for a few lines of detail.
  */
-export declare function InfoTip({ content, side, label }: InfoTipProps): import("react").JSX.Element;
+export declare function InfoTip({ content, side, label, maxWidth, delay, }: InfoTipProps): import("react").JSX.Element;
 export {};

package/dist/InfoTip.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Tooltip } from './Tooltip';
 /**
- * A small "i" glyph that reveals a tooltip on hover or focus. A convenience
- * wrapper over Tooltip for the very common "explain this label" case.
+ * A small "i" glyph that reveals a popover on hover or focus. Built on Tooltip,
+ * so it renders at a fixed position (never clipped) and accepts rich content —
+ * the common "explain this label" case, with room for a few lines of detail.
  */
-export function InfoTip({ content, side = 'top', label = 'More information' }) {
-    return (_jsx(Tooltip, { content: content, side: side, children: _jsx("span", { className: "info-tip", role: "img", "aria-label": label, tabIndex: 0, children: "i" }) }));
+export function InfoTip({ content, side = 'top', label = 'More information', maxWidth, delay, }) {
+    return (_jsx(Tooltip, { content: content, side: side, maxWidth: maxWidth, delay: delay, children: _jsx("span", { className: "info-tip", role: "img", "aria-label": label, tabIndex: 0, children: "i" }) }));
 }

package/dist/Modal.d.ts

@@ -3,6 +3,13 @@ type ModalProps = {
     open: boolean;
     onClose: () => void;
     title?: string;
+    /** Accessible name when there's no title to point at. */
+    'aria-label'?: string;
+    /** Id of an element that labels the dialog (wins over title). */
+    'aria-labelledby'?: string;
+    /** Id of an element that describes the dialog. */
+    'aria-describedby'?: string;
+    className?: string;
     children: ReactNode;
 };
 declare function Header({ children }: {
@@ -14,7 +21,7 @@ declare function Body({ children }: {
 declare function Footer({ children }: {
     children: ReactNode;
 }): import("react").JSX.Element;
-export declare function Modal({ open, onClose, title, children }: ModalProps): import("react").ReactPortal | null;
+export declare function Modal({ open, onClose, title, className, children, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, 'aria-describedby': ariaDescribedby, }: ModalProps): import("react").ReactPortal | null;
 export declare namespace Modal {
     export { Header };
     export { Body };

package/dist/Modal.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useId } from 'react';
+import { useEffect, useId, useRef } from 'react';
 import { createPortal } from 'react-dom';
+import { cx } from './cx';
 function Header({ children }) {
     return _jsx("div", { className: "modal__header", children: children });
 }
@@ -10,21 +11,51 @@ function Body({ children }) {
 function Footer({ children }) {
     return _jsx("div", { className: "modal__footer", children: children });
 }
-export function Modal({ open, onClose, title, children }) {
+const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+export function Modal({ open, onClose, title, className, children, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, 'aria-describedby': ariaDescribedby, }) {
     const titleId = useId();
+    const dialogRef = useRef(null);
+    // Move focus into the dialog on open and restore it on close, and trap Tab
+    // so keyboard focus can't wander behind the modal.
     useEffect(() => {
         if (!open)
             return;
+        const previouslyFocused = document.activeElement;
+        const dialog = dialogRef.current;
+        dialog?.focus();
         function handleKey(e) {
-            if (e.key === 'Escape')
+            if (e.key === 'Escape') {
                 onClose();
+                return;
+            }
+            if (e.key !== 'Tab' || !dialog)
+                return;
+            const focusables = Array.from(dialog.querySelectorAll(FOCUSABLE));
+            if (focusables.length === 0) {
+                e.preventDefault();
+                return;
+            }
+            const first = focusables[0];
+            const last = focusables[focusables.length - 1];
+            if (e.shiftKey && document.activeElement === first) {
+                e.preventDefault();
+                last.focus();
+            }
+            else if (!e.shiftKey && document.activeElement === last) {
+                e.preventDefault();
+                first.focus();
+            }
         }
         document.addEventListener('keydown', handleKey);
-        return () => document.removeEventListener('keydown', handleKey);
+        return () => {
+            document.removeEventListener('keydown', handleKey);
+            previouslyFocused?.focus?.();
+        };
     }, [open, onClose]);
     if (!open)
         return null;
-    return createPortal(_jsx("div", { className: "modal__backdrop", onClick: onClose, children: _jsxs("div", { role: "dialog", "aria-modal": "true", "aria-labelledby": title ? titleId : undefined, className: "modal", onClick: (e) => e.stopPropagation(), children: [title && (_jsx("div", { id: titleId, className: "modal__title", children: title })), children] }) }), document.body);
+    const labelledby = ariaLabelledby ?? (title ? titleId : undefined);
+    return createPortal(_jsx("div", { className: "modal__backdrop", onClick: onClose, children: _jsxs("div", { ref: dialogRef, role: "dialog", "aria-modal": "true", "aria-label": !labelledby ? ariaLabel : undefined, "aria-labelledby": labelledby, "aria-describedby": ariaDescribedby, tabIndex: -1, className: cx('modal__content', className), onClick: (e) => e.stopPropagation(), children: [title && (_jsx("div", { id: titleId, className: "modal__header", children: title })), children] }) }), document.body);
 }
 Modal.Header = Header;
 Modal.Body = Body;

package/dist/Skeleton.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cx } from './cx';
 export function Skeleton({ variant, width, height }) {
-    const style = variant === 'rect'
+    const style = width || height
         ? {
             '--skeleton-w': width,
             '--skeleton-h': height,

package/dist/Textarea.d.ts

@@ -1,11 +1,16 @@
 import { type TextareaHTMLAttributes } from 'react';
 /**
- * Multi-line text field. Mirrors Input's label/error/helper API so the two
- * feel the same in a form.
+ * Multi-line text field. Mirrors Input's label/error/helper API, and adds an
+ * optional hidden label, a required marker, and a live character counter when
+ * paired with maxLength.
  */
 export declare const Textarea: import("react").ForwardRefExoticComponent<TextareaHTMLAttributes<HTMLTextAreaElement> & {
     label?: string;
     error?: string;
     helper?: string;
+    /** Visually hide the label while keeping it available to screen readers. */
+    hideLabel?: boolean;
+    /** Show a live "used / max" character count. Needs maxLength to be set. */
+    showCount?: boolean;
     disabled?: boolean;
 } & import("react").RefAttributes<HTMLTextAreaElement>>;

package/dist/Textarea.js

@@ -1,13 +1,27 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useId } from 'react';
+import { forwardRef, useId, useState, } from 'react';
 import { cx } from './cx';
 /**
- * Multi-line text field. Mirrors Input's label/error/helper API so the two
- * feel the same in a form.
+ * Multi-line text field. Mirrors Input's label/error/helper API, and adds an
+ * optional hidden label, a required marker, and a live character counter when
+ * paired with maxLength.
  */
-export const Textarea = forwardRef(function Textarea({ label, error, helper, disabled, className, ...props }, ref) {
+export const Textarea = forwardRef(function Textarea({ label, error, helper, hideLabel = false, showCount = false, required, disabled, maxLength, value, defaultValue, onChange, className, ...props }, ref) {
     const id = useId();
     const helperId = `${id}-helper`;
+    const countId = `${id}-count`;
     const helperText = error || helper;
-    return (_jsxs("div", { className: "input__wrapper", children: [label && (_jsx("label", { className: "input__label", htmlFor: id, children: label })), _jsx("textarea", { ref: ref, id: id, className: cx('textarea', error && 'textarea--error', className), disabled: disabled, "aria-invalid": error ? true : undefined, "aria-describedby": helperText ? helperId : undefined, ...props }), helperText && (_jsx("span", { id: helperId, className: cx('input__helper', error && 'input__helper--error'), children: helperText }))] }));
+    // Count is derived from a controlled value, or tracked locally otherwise.
+    const controlled = value !== undefined;
+    const [localCount, setLocalCount] = useState(() => String(defaultValue ?? '').length);
+    const count = controlled ? String(value ?? '').length : localCount;
+    const withCount = showCount && maxLength != null;
+    const describedBy = [helperText ? helperId : null, withCount ? countId : null]
+        .filter(Boolean)
+        .join(' ') || undefined;
+    return (_jsxs("div", { className: "input__wrapper", children: [label && (_jsxs("label", { className: hideLabel ? 'sr-only' : 'input__label', htmlFor: id, children: [label, required && (_jsx("span", { "aria-hidden": "true", children: " *" }))] })), _jsx("textarea", { ref: ref, id: id, className: cx('textarea', error && 'textarea--error', className), disabled: disabled, required: required, maxLength: maxLength, value: value, defaultValue: defaultValue, "aria-invalid": error ? true : undefined, "aria-describedby": describedBy, onChange: (e) => {
+                    if (!controlled)
+                        setLocalCount(e.target.value.length);
+                    onChange?.(e);
+                }, ...props }), withCount && (_jsxs("span", { id: countId, className: "textarea__count", "aria-live": "polite", children: [count, " / ", maxLength] })), helperText && (_jsx("span", { id: helperId, className: cx('input__helper', error && 'input__helper--error'), children: helperText }))] }));
 });

package/dist/Tooltip.d.ts

@@ -1,8 +1,19 @@
 import { type ReactNode } from 'react';
+type TooltipSide = 'top' | 'bottom' | 'left' | 'right';
 type TooltipProps = {
-    content: string;
-    side?: 'top' | 'bottom' | 'left' | 'right';
+    /** Content shown in the floating label. Text or rich nodes. */
+    content: ReactNode;
+    side?: TooltipSide;
+    /** Delay before showing, in ms. Avoids flashing on a quick mouse pass. */
+    delay?: number;
+    /** Max width of the bubble in px. */
+    maxWidth?: number;
     children: ReactNode;
 };
-export declare function Tooltip({ content, side, children }: TooltipProps): import("react").JSX.Element;
+/**
+ * A tooltip that renders at a fixed screen position, so it's never clipped by
+ * an overflow:hidden ancestor (grids, cards, chips) and needs no portal. Shows
+ * on hover and focus after `delay` ms; Escape dismisses it.
+ */
+export declare function Tooltip({ content, side, delay, maxWidth, children }: TooltipProps): import("react").JSX.Element;
 export {};

package/dist/Tooltip.js

@@ -1,8 +1,63 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState, useId } from 'react';
+import { useState, useRef, useCallback, useId, } from 'react';
 import { cx } from './cx';
-export function Tooltip({ content, side = 'top', children }) {
-    const [visible, setVisible] = useState(false);
+const GAP = 8;
+/**
+ * A tooltip that renders at a fixed screen position, so it's never clipped by
+ * an overflow:hidden ancestor (grids, cards, chips) and needs no portal. Shows
+ * on hover and focus after `delay` ms; Escape dismisses it.
+ */
+export function Tooltip({ content, side = 'top', delay = 500, maxWidth, children }) {
     const id = useId();
-    return (_jsxs("span", { onMouseEnter: () => setVisible(true), onMouseLeave: () => setVisible(false), "aria-describedby": id, style: { position: 'relative', display: 'inline-block' }, children: [children, _jsx("span", { id: id, role: "tooltip", className: cx('tooltip', `tooltip--${side}`, visible && 'tooltip--visible'), children: content })] }));
+    const [visible, setVisible] = useState(false);
+    const [rect, setRect] = useState(null);
+    const timer = useRef(null);
+    const show = useCallback((el) => {
+        setRect(el.getBoundingClientRect());
+        if (timer.current)
+            clearTimeout(timer.current);
+        timer.current = setTimeout(() => setVisible(true), delay);
+    }, [delay]);
+    const hide = useCallback(() => {
+        if (timer.current)
+            clearTimeout(timer.current);
+        setVisible(false);
+    }, []);
+    const style = rect
+        ? { position: 'fixed', ...place(rect, side), maxWidth }
+        : undefined;
+    return (_jsxs("span", { className: "tooltip__anchor", style: { display: 'inline-flex' }, onMouseEnter: (e) => show(e.currentTarget), onMouseLeave: hide, onFocus: (e) => show(e.currentTarget), onBlur: hide, onKeyDown: (e) => {
+            if (e.key === 'Escape' && visible)
+                hide();
+        }, "aria-describedby": visible ? id : undefined, children: [children, visible && rect && (_jsx("span", { id: id, role: "tooltip", className: cx('tooltip', `tooltip--${side}`, 'tooltip--visible'), style: style, children: content }))] }));
+}
+/** Screen coordinates + transform to anchor the bubble on a side of the rect. */
+function place(rect, side) {
+    switch (side) {
+        case 'bottom':
+            return {
+                left: rect.left + rect.width / 2,
+                top: rect.bottom + GAP,
+                transform: 'translateX(-50%)',
+            };
+        case 'left':
+            return {
+                left: rect.left - GAP,
+                top: rect.top + rect.height / 2,
+                transform: 'translate(-100%, -50%)',
+            };
+        case 'right':
+            return {
+                left: rect.right + GAP,
+                top: rect.top + rect.height / 2,
+                transform: 'translateY(-50%)',
+            };
+        case 'top':
+        default:
+            return {
+                left: rect.left + rect.width / 2,
+                top: rect.top - GAP,
+                transform: 'translate(-50%, -100%)',
+            };
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paul-portfolio/react",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "React components for the Paul Design System",
   "license": "MIT",
   "repository": {