@paul-portfolio/react 0.1.17 → 0.2.0

package/README.md

@@ -0,0 +1,166 @@
+# @paul-portfolio/react
+
+React components for the Paul Design System. Thin, accessible components styled
+by [`@paul-portfolio/css`](https://www.npmjs.com/package/@paul-portfolio/css) —
+the components render semantic markup with class names, and the CSS package
+supplies the looks via design tokens.
+
+## Install
+
+```bash
+npm install @paul-portfolio/react @paul-portfolio/css @paul-portfolio/tokens
+```
+
+`@paul-portfolio/css` and `@paul-portfolio/tokens` are peer dependencies, along
+with `react` and `react-dom` (>=18).
+
+## Setup
+
+Import the token variables and the component styles once, near the root of your
+app:
+
+```ts
+import "@paul-portfolio/tokens/tokens.css";
+import "@paul-portfolio/css/components.css";
+```
+
+Then use the components:
+
+```tsx
+import { Button } from "@paul-portfolio/react";
+
+export function Example() {
+  return <Button variant="primary">Save</Button>;
+}
+```
+
+## Components
+
+### Button
+
+Variants (`primary`, `secondary`, `outline`, `ghost`, `danger`), sizes (`xs`,
+`sm`, `md`, `lg`), `loading`, and an `href` form that renders an `<a>`.
+
+```tsx
+<Button variant="outline" size="sm" onClick={save}>Save</Button>
+<Button href="/docs" variant="ghost">Docs</Button>
+```
+
+### IconButton
+
+A square, icon-only button. Requires `aria-label` since there's no visible text.
+Sizes `sm` and `md`.
+
+```tsx
+<IconButton aria-label="Close" onClick={close}>✕</IconButton>
+```
+
+### Input / Textarea
+
+Labelled fields with `error` and `helper` text. `Input` takes a `size`
+(`sm`/`md`); `Textarea` resizes vertically.
+
+```tsx
+<Input label="Email" type="email" error={emailError} />
+<Textarea label="Bio" helper="Max 200 characters" />
+```
+
+### Switch
+
+An on/off toggle. Controlled via `checked` + `onCheckedChange`. Give it an
+`aria-label`.
+
+```tsx
+<Switch checked={on} onCheckedChange={setOn} aria-label="Notifications" />
+```
+
+### Chip
+
+A compact tag, optionally removable and colorable.
+
+```tsx
+<Chip label="Design" onRemove={() => remove("design")} />
+```
+
+### Modal
+
+An accessible dialog with focus trap, Escape-to-close, and a backdrop. Controlled
+via `open` + `onClose`.
+
+```tsx
+<Modal open={open} onClose={close} aria-label="Settings">
+  <h2>Settings</h2>
+</Modal>
+```
+
+### Tooltip / InfoTip
+
+`Tooltip` wraps any element and shows text on hover. `InfoTip` is the common
+"small i that explains a label" shortcut, built on `Tooltip`.
+
+```tsx
+<Tooltip content="Copied to clipboard"><IconButton aria-label="Copy">⧉</IconButton></Tooltip>
+<InfoTip content="We never share your email." />
+```
+
+### Card
+
+A surface with optional `Card.Header`, `Card.Body`, and `Card.Footer`.
+
+```tsx
+<Card>
+  <Card.Header>Plan</Card.Header>
+  <Card.Body>Pro — $12/mo</Card.Body>
+</Card>
+```
+
+### Badge / Avatar / Skeleton / Spinner
+
+- **Badge** — a small status label.
+- **Avatar** — a rounded user image with initials fallback.
+- **Skeleton** — a shimmer placeholder for content that's still loading.
+- **Spinner** — an indeterminate loading spinner (`sm`/`md`/`lg`), announced as a
+  status region.
+
+```tsx
+<Badge>New</Badge>
+<Avatar name="Ada Lovelace" src={url} />
+<Skeleton width="12rem" />
+<Spinner label="Loading results" />
+```
+
+### Divider
+
+A thin separator rule, `horizontal` (default) or `vertical`.
+
+```tsx
+<Divider />
+<Divider orientation="vertical" />
+```
+
+### VisuallyHidden
+
+Renders content that's available to screen readers but hidden visually.
+
+```tsx
+<VisuallyHidden>Loading</VisuallyHidden>
+```
+
+### cx
+
+A tiny classname joiner used internally, exported for convenience.
+
+```ts
+cx("card", isActive && "card--active"); // "card card--active"
+```
+
+## Accessibility
+
+Every component ships with an axe test in the package's suite. Components that
+have no visible text (IconButton, Switch, Spinner) require or default an
+accessible name, and interactive components expose the right roles and ARIA
+state.
+
+## License
+
+MIT © Paul Sumido

package/dist/Divider.d.ts

@@ -0,0 +1,10 @@
+import { type HTMLAttributes } from 'react';
+type DividerProps = HTMLAttributes<HTMLHRElement> & {
+    orientation?: 'horizontal' | 'vertical';
+};
+/**
+ * A thin rule that separates content. Renders an <hr> (implicit
+ * role="separator"); pass orientation="vertical" for use inside a flex row.
+ */
+export declare function Divider({ orientation, className, ...props }: DividerProps): import("react").JSX.Element;
+export {};

package/dist/Divider.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from './cx';
+/**
+ * A thin rule that separates content. Renders an <hr> (implicit
+ * role="separator"); pass orientation="vertical" for use inside a flex row.
+ */
+export function Divider({ orientation = 'horizontal', className, ...props }) {
+    return (_jsx("hr", { className: cx('divider', orientation === 'vertical' && 'divider--vertical', className), "aria-orientation": orientation, ...props }));
+}

package/dist/IconButton.d.ts

@@ -0,0 +1,12 @@
+import { type ButtonHTMLAttributes, type ReactNode } from 'react';
+/**
+ * A square, icon-only button. Always needs an aria-label because there's no
+ * visible text to name it.
+ */
+export declare const IconButton: import("react").ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & {
+    /** Required: describes the action for screen readers, since the button
+     *  holds only an icon. */
+    'aria-label': string;
+    size?: 'sm' | 'md';
+    children: ReactNode;
+} & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/IconButton.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { cx } from './cx';
+/**
+ * A square, icon-only button. Always needs an aria-label because there's no
+ * visible text to name it.
+ */
+export const IconButton = forwardRef(function IconButton({ size, className, children, type, ...props }, ref) {
+    return (_jsx("button", { ref: ref, type: type ?? 'button', className: cx('icon-btn', size && size !== 'md' && `icon-btn--${size}`, className), ...props, children: children }));
+});

package/dist/InfoTip.d.ts

@@ -0,0 +1,13 @@
+type InfoTipProps = {
+    /** The explanatory text shown in the tooltip. */
+    content: string;
+    side?: 'top' | 'bottom' | 'left' | 'right';
+    /** Accessible name for the trigger. Defaults to "More information". */
+    label?: string;
+};
+/**
+ * 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.
+ */
+export declare function InfoTip({ content, side, label }: InfoTipProps): import("react").JSX.Element;
+export {};

package/dist/InfoTip.js

@@ -0,0 +1,9 @@
+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.
+ */
+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" }) }));
+}

package/dist/Spinner.d.ts

@@ -0,0 +1,12 @@
+import { type HTMLAttributes } from 'react';
+type SpinnerProps = HTMLAttributes<HTMLSpanElement> & {
+    size?: 'sm' | 'md' | 'lg';
+    /** Accessible name announced to screen readers. Defaults to "Loading". */
+    label?: string;
+};
+/**
+ * An indeterminate loading spinner. Renders as a live status region so
+ * assistive tech announces that something is loading.
+ */
+export declare function Spinner({ size, label, className, ...props }: SpinnerProps): import("react").JSX.Element;
+export {};

package/dist/Spinner.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from './cx';
+/**
+ * An indeterminate loading spinner. Renders as a live status region so
+ * assistive tech announces that something is loading.
+ */
+export function Spinner({ size, label = 'Loading', className, ...props }) {
+    return (_jsx("span", { role: "status", "aria-label": label, className: cx('spinner', size && size !== 'md' && `spinner--${size}`, className), ...props }));
+}

package/dist/Switch.d.ts

@@ -0,0 +1,13 @@
+import { type ButtonHTMLAttributes } from 'react';
+/**
+ * An on/off toggle. Controlled via `checked` + `onCheckedChange`. Exposes
+ * role="switch" with aria-checked so assistive tech reads its state. Give it
+ * an aria-label (or aria-labelledby) since it has no text of its own.
+ */
+export declare const Switch: import("react").ForwardRefExoticComponent<Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onChange"> & {
+    /** Whether the switch is on. Controlled. */
+    checked: boolean;
+    /** Called with the next value when toggled. */
+    onCheckedChange?: (checked: boolean) => void;
+    disabled?: boolean;
+} & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/Switch.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { cx } from './cx';
+/**
+ * An on/off toggle. Controlled via `checked` + `onCheckedChange`. Exposes
+ * role="switch" with aria-checked so assistive tech reads its state. Give it
+ * an aria-label (or aria-labelledby) since it has no text of its own.
+ */
+export const Switch = forwardRef(function Switch({ checked, onCheckedChange, disabled, className, ...props }, ref) {
+    return (_jsx("button", { ref: ref, type: "button", role: "switch", "aria-checked": checked, disabled: disabled, onClick: () => onCheckedChange?.(!checked), className: cx('switch', checked && 'switch--on', className), ...props, children: _jsx("span", { className: "switch__thumb" }) }));
+});

package/dist/Textarea.d.ts

@@ -0,0 +1,11 @@
+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.
+ */
+export declare const Textarea: import("react").ForwardRefExoticComponent<TextareaHTMLAttributes<HTMLTextAreaElement> & {
+    label?: string;
+    error?: string;
+    helper?: string;
+    disabled?: boolean;
+} & import("react").RefAttributes<HTMLTextAreaElement>>;

package/dist/Textarea.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useId } 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.
+ */
+export const Textarea = forwardRef(function Textarea({ label, error, helper, disabled, className, ...props }, ref) {
+    const id = useId();
+    const helperId = `${id}-helper`;
+    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 }))] }));
+});

package/dist/index.d.ts

@@ -1,11 +1,17 @@
 export { Button } from './Button';
+export { IconButton } from './IconButton';
 export { Card } from './Card';
 export { Chip } from './Chip';
 export { Input } from './Input';
+export { Textarea } from './Textarea';
+export { Switch } from './Switch';
 export { Modal } from './Modal';
 export { Tooltip } from './Tooltip';
+export { InfoTip } from './InfoTip';
 export { Avatar } from './Avatar';
 export { Badge } from './Badge';
 export { Skeleton } from './Skeleton';
+export { Spinner } from './Spinner';
+export { Divider } from './Divider';
 export { VisuallyHidden } from './VisuallyHidden';
 export { cx } from './cx';

package/dist/index.js

@@ -1,11 +1,17 @@
 export { Button } from './Button';
+export { IconButton } from './IconButton';
 export { Card } from './Card';
 export { Chip } from './Chip';
 export { Input } from './Input';
+export { Textarea } from './Textarea';
+export { Switch } from './Switch';
 export { Modal } from './Modal';
 export { Tooltip } from './Tooltip';
+export { InfoTip } from './InfoTip';
 export { Avatar } from './Avatar';
 export { Badge } from './Badge';
 export { Skeleton } from './Skeleton';
+export { Spinner } from './Spinner';
+export { Divider } from './Divider';
 export { VisuallyHidden } from './VisuallyHidden';
 export { cx } from './cx';

package/package.json

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