@wearenotch/ui-react 0.3.2 → 0.6.0

package/README.md

@@ -0,0 +1,101 @@
+# @wearenotch/ui-react
+
+React components for the Notch Design System.
+
+## Install
+
+```bash
+pnpm add @wearenotch/ui-react @wearenotch/tokens
+# or
+npm install @wearenotch/ui-react @wearenotch/tokens
+```
+
+`react` and `react-dom` (**>=19**) are peer dependencies.
+
+> **On React 18?** Pin to the `0.3.x` line: `"@wearenotch/ui-react": "~0.3.2"`. Versions `0.4.0+` require React 19 — see the [migration note](#migrating-from-03x-react-18) below.
+
+## Usage
+
+Import the tokens stylesheet **once** in your app entry, then use components anywhere:
+
+```tsx
+// app entry (e.g. src/main.tsx)
+import '@wearenotch/tokens/css';
+import '@wearenotch/ui-react/css';
+```
+
+```tsx
+import { Button, Input, FormField } from '@wearenotch/ui-react';
+
+export function SignIn() {
+  return (
+    <form>
+      <FormField label="Email" htmlFor="email">
+        <Input id="email" type="email" />
+      </FormField>
+      <Button variant="primary" type="submit">Sign in</Button>
+    </form>
+  );
+}
+```
+
+## Dark mode
+
+Dark mode is CSS-only — toggle the `data-theme` attribute on `<html>`:
+
+```ts
+document.documentElement.setAttribute('data-theme', 'dark');
+```
+
+No JavaScript color switching, no provider — every component reads tokens that respond to `data-theme="dark"`.
+
+## Components
+
+35 components covering primitives, forms, feedback, navigation, layout, and data display:
+
+**Primitives** Button, IconButton, Badge, Tag, Avatar, Spinner, Skeleton, Tooltip
+**Forms** Input, Textarea, Select, MultiSelect, Checkbox, Switch, Slider, FormField, FileUpload, DatePicker, RichTextEditor
+**Feedback** Alert, Notification, ProgressBar, EmptyState
+**Navigation** Tabs, Accordion, Breadcrumbs, Pagination, Stepper
+**Layout** Card, Modal, List, Carousel
+**Data display** Table, Chart
+
+## Conventions
+
+- All components forward refs where applicable and spread unknown HTML attributes onto their root element.
+- Sizes use `sm | md | lg`.
+- Form controls expose `value` / `onChange` and accept `id`, `name`, `disabled`, etc.
+- Every interactive component has an accessible name — pass a visible label or `aria-label`.
+
+## Storybook
+
+Browse all components and variants:
+
+```bash
+pnpm --filter @notch/storybook dev
+# http://localhost:6006
+```
+
+## Migrating from 0.3.x (React 18)
+
+Version `0.4.0` bumps the React peer dependency to `>=19.0.0` and adopts the React 19 ref-as-prop pattern internally. **No code changes are required in consumer apps** — `*Props` interfaces are unchanged. The break is purely at the peer dependency level.
+
+To migrate:
+
+1. Upgrade your app to React 19 (`react`, `react-dom`, `@types/react`, `@types/react-dom`).
+2. Bump `@wearenotch/ui-react` to `^0.4.0`.
+3. If you were doing `forwardRef`-style ref forwarding around our components, that still works — `ref` is now a regular prop and is forwarded automatically.
+
+If you can't upgrade React yet, stay on `~0.3.2`. We will not backport new features to `0.3.x`, but security fixes will land there if needed.
+
+## Scripts
+
+```bash
+pnpm --filter @wearenotch/ui-react build       # build dist/
+pnpm --filter @wearenotch/ui-react test        # run vitest
+pnpm --filter @wearenotch/ui-react type-check  # tsc --noEmit
+```
+
+## License
+
+MIT