neba 1.13.0 → 1.15.0

package/README.md

@@ -4,15 +4,13 @@
 
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jooy2/neba/blob/main/LICENSE) ![Programming Language Usage](https://img.shields.io/github/languages/top/jooy2/neba) ![Commit Count](https://img.shields.io/github/commit-activity/y/jooy2/neba) [![npm downloads](https://img.shields.io/npm/dm/neba.svg)](https://www.npmjs.com/package/neba) [![npm latest package](https://img.shields.io/npm/v/neba/latest.svg)](https://www.npmjs.com/package/neba) ![npm bundle size](https://img.shields.io/bundlephobia/min/neba) [![Followers](https://img.shields.io/github/followers/jooy2?style=social)](https://github.com/jooy2) ![Stars](https://img.shields.io/github/stars/jooy2/neba?style=social)
 
-### 📘 [**neba.cdget.com**](https://neba.cdget.com)
-
-[![Components](https://img.shields.io/badge/All_components-live_previews-444?style=for-the-badge)](https://neba.cdget.com/examples/overview)
-
 Live previews and full props for every component. This README is just the quick start.
 
+![Neba UI components arranged around the Neba mark: a search field, a settings card, radio buttons and checkboxes, buttons and chips, a segmented button and pagination, a success alert, a slider, a progress bar and a meter, an avatar stack, a badge and a rating](.github/showcase.png)
+
 ---
 
-**Neba UI is a React component library for building application interfaces.** About 130 components, from buttons and form fields through menus, dialogs, tables and charts. They are styled and accessible out of the box, and they agree with each other because they draw from one set of props.
+**Neba UI is a React component library for building application interfaces.** About 140 components, from buttons and form fields through menus, dialogs, tables and charts. They are styled and accessible out of the box, and they agree with each other because they draw from one set of props.
 
 You install one package, add one line to your CSS, and import components. There is nothing to configure, no theme object to assemble, and no per-component styling decisions to make before you can ship a screen.
 
@@ -21,8 +19,8 @@ You install one package, add one line to your CSS, and import components. There
 - **Accessible by construction**: real roles, labels, focus management and keyboard support, not `div`s with click handlers.
 - **Dark mode with no work**: follows the system, and can be forced either way per subtree.
 - **A design language, not a theme file**: a translucent acrylic surface with a hairline edge, one deliberate motion signature, and shadows that are opt-in.
-- **ESM only**, TypeScript declarations included, and genuinely tree-shakeable: every component compiles to its own module, and importing one costs about what one costs. A `Button` is ~5 kB gzipped including its Base UI parts, a `Chip` is ~3 kB, and a twelve-component app is ~70 kB; the whole library, all one hundred and seventy-five exports at once, is ~265 kB.
-- **Two runtime dependencies**: Base UI, and `highlight.js`, which only [CodeBlock](https://neba.cdget.com/components/display/code-block) reaches and only through a dynamic import, so it never lands in a bundle that did not ask for it. React 18 or 19, Node.js 18 or later.
+- **ESM only**, TypeScript declarations included, and genuinely tree-shakeable: every component compiles to its own module, and importing one costs about what one costs. A `Button` is ~5 kB gzipped including its Base UI parts, a `Chip` is ~3.5 kB, and a twelve-component app is ~70 kB; the whole library, all one hundred and eighty-five exports at once, is ~286 kB.
+- **Two runtime dependencies**: Base UI, and `highlight.js`, which only [CodeBlock](https://neba.cdget.com/components/display/code-block) reaches and only through a dynamic import, so it never lands in a bundle that did not ask for it. React 18 or 19, Node.js 18 or later. The [A2UI](https://neba.cdget.com/guide/a2ui) renderer at `neba/a2ui` has three more, and they are optional peers: a project that never imports that subpath never meets them.
 
 ## Documentation
 
@@ -36,6 +34,10 @@ Everything is documented at **[neba.cdget.com](https://neba.cdget.com)**, where
 | [**Design language**](https://neba.cdget.com/design/design-language) | Why a Neba surface looks and behaves the way it does. |
 | [**Prop conventions**](https://neba.cdget.com/design/prop-conventions) | The shared vocabulary every component draws from. |
 | [**Color**](https://neba.cdget.com/design/color) | The token families, and how to theme them. |
+| [**NebaProvider**](https://neba.cdget.com/guide/provider) | Defaults for a whole subtree, the colour scheme, and the direction. |
+| [**Hooks**](https://neba.cdget.com/guide/hooks) | The hooks the library exports, and what each one is for. |
+| [**Breakpoints**](https://neba.cdget.com/design/breakpoints) | The widths a responsive prop changes at, and which props take a map. |
+| [**Browser support**](https://neba.cdget.com/browser-support) | The oldest browser versions the library works in. |
 | [**Changelog**](https://neba.cdget.com/changelog) | What changed in each release, and the setup changes worth acting on. |
 
 ## Installation
@@ -92,7 +94,7 @@ Every component carries `'use client'`, so it can be imported straight into a Se
 
 The `neba` barrel and `neba/locales` are deliberately left unmarked, so a Server Component importing the barrel reaches the components behind it rather than a boundary of its own, and `registerMessages` stays a plain function. Bundlers that do not implement Server Components ignore the directive entirely.
 
-A few components provide context and are mounted once, near the root, only if you use them: `ToastProvider` (paired with the `useToast()` hook) and `TooltipProvider`.
+A few components provide context and are mounted once, near the root, only if you use them: `ToastProvider` (paired with the `useToast()` hook), `ConfirmProvider` (paired with `useConfirm()`, which throws without one) and `TooltipProvider`.
 
 Every component is also its own entry point, named after its folder:
 
@@ -121,7 +123,7 @@ Call it once, at module scope, before your first render. Then a `locale` prop tr
 <Dialog locale="ko" title="설정" showClose />
 ```
 
-A registered language costs about 2.8 kB gzipped and you pay only for the ones you name. Tags are matched by script, then by region, then by language: registering `ko` answers `ko-KR`, and `zhHans` registered as `zh-hans` answers `zh-CN` and a bare `zh`. Available: `ko`, `ja`, `zhHans`, `zhHant`, `es`, `pt`, `fr`, `de`, `it`, `nl`, `pl`, `ru`, `tr`, `ar`, `hi`, `id`, `vi`, `th`, each also its own entry point (`neba/locales/ko`).
+A registered language costs about 3.4 kB gzipped and you pay only for the ones you name. Tags are matched by script, then by region, then by language: registering `ko` answers `ko-KR`, and `zhHans` registered as `zh-hans` answers `zh-CN` and a bare `zh`. Available: `ko`, `ja`, `zhHans`, `zhHant`, `es`, `pt`, `fr`, `de`, `it`, `nl`, `pl`, `ru`, `tr`, `ar`, `hi`, `id`, `vi`, `th`, each also its own entry point (`neba/locales/ko`).
 
 Anything the platform already knows (month names, weekday names, AM/PM, number and date formats) comes from `Intl` and needs no registration. And every string a component invents also has a prop that overrides it, so a language Neba does not carry is never a dead end.
 
@@ -167,7 +169,7 @@ The reason a Neba screen looks composed rather than assembled is that the props
 | `density` | `default` `compact` | Padding only: never the height, never the type scale, so a compact control still lines up with a default one. |
 | `elevation` | `0` `1` `2` `3` | How far a surface floats off the page. `0` is the default and means no shadow at all. |
 
-Placement props are logical, not physical (`start`/`end` rather than `left`/`right`) so layouts flip correctly under RTL. The full rules are in [**Prop conventions**](https://neba.cdget.com/design/prop-conventions).
+`align` is logical (`start`/`end` rather than `left`/`right`), so it flips under RTL. `side` names a physical edge (`top`, `right`, `bottom` or `left`) and does not flip. The full rules are in [**Prop conventions**](https://neba.cdget.com/design/prop-conventions).
 
 ```tsx
 <Button size="sm" color="danger" variant="outline">Delete</Button>
@@ -176,37 +178,27 @@ Placement props are logical, not physical (`start`/`end` rather than `left`/`rig
 
 ### Components
 
-**Inputs**: Button, IconButton, ButtonGroup, SegmentedButton, Toggle, ToggleGroup, Form, Fieldset, FloatingActionButton (with FloatingAction), TextField, NumberField, OtpField, Select, Combobox, TreeSelect, Checkbox, RadioGroup, Switch, Slider, Rating, Menu (with submenus, checkbox and radio items), ContextMenu, Menubar, NavigationMenu, CommandPalette, FilePicker, Transfer, Pagination, BottomNavigation, FloatingBottomNavigation, ColorPicker, Calendar, DatePicker, TimePicker, DateTimePicker, DateRangePicker
-
-**Surfaces**: Box, Card, Accordion, Collapsible, Tabs, Carousel, Toolbar, Pill, Spoiler, HowToSteps, ChatBubble, Drawer, Popover, Mockup, WindowPane, HoverCard
-
-**Display**: Typography, TextLink, Blockquote, Highlight, Divider, Chip, Badge, Avatar, AppLogo, Icon, Image, Gallery, Shortcut, List, DataList, Table, DataTable, CodeBlock, Timeline, Breadcrumb, Anchor, TreeView, VisuallyHidden
-
-**Charts**: Statistic, Sparkline, LineChart, AreaChart, BarChart, PieChart, ScatterChart, TimelineChart, HeatmapChart, GaugeChart
-
-**Feedback**: Alert, Dialog, Confirm, Popconfirm, Toast, Tooltip, Overlay, Skeleton, Empty, ProgressLinear, ProgressCircular, ProgressBox, Meter, Tour
-
-**Layout**: PageLayout (with Header, Footer and Sidebar), Container, Grid (with GridContainer), Flex, Panes, Stack, Show, AspectRatio, Portal, ScrollZone, ScrollArea
-
-**Transitions**: AnimateFade, AnimateGrow, AnimateZoom, AnimateSlide, AnimateRotate, AnimateBlink, AnimateReveal, AnimateFloat, AnimateShake, AnimateAppear, AnimateSplit, AnimateTyping, AnimateScramble, AnimateCounter, AnimateLighting, AnimateMarquee, AnimateHeadline
-
-**Added in the last two releases**: Gallery, Flex, Show, Stack and the six new `Animate*` (Reveal, Float, Shake, Split, Counter, Scramble) in 1.12.0; Calendar, TreeSelect, Image, Confirm, Popconfirm and VisuallyHidden in 1.11.0. The [changelog](https://neba.cdget.com/changelog) has the rest.
-
-Each one has its own page (live previews, every prop, and the variations worth seeing) under [**All components**](https://neba.cdget.com/components/).
+The components come in eight groups: inputs, surfaces, display, charts, feedback, layout, transitions and agent. Each one has its own page (live previews, every prop, and the variations worth seeing) under [**All components**](https://neba.cdget.com/components/).
 
 ### Theming and dark mode
 
-Colours, radii, and surface strengths are CSS custom properties declared in the stylesheet you imported. Override any of them in your own CSS and the whole library follows:
+Colours, radii, and surface strengths are CSS custom properties declared in the stylesheet you imported. A colour family is five base values, and everything else in it is derived from them, so override those five in your own CSS and the whole library follows:
 
 ```css
 :root {
-  --neba-primary-fill: oklch(0.62 0.19 265);
+  --neba-primary-solid: oklch(50% 0.24 300);
+  --neba-primary-solid-hover: oklch(45.5% 0.232 300);
+  --neba-primary-solid-active: oklch(38% 0.204 300);
+  --neba-primary-on-solid: oklch(99% 0.004 300);
+  --neba-primary-accent: oklch(54% 0.26 300);
 }
 ```
 
+A derived token such as `--neba-primary-fill` is not meant to be overridden: it changes that one token and leaves the rest of the family on the old colour. [**Color**](https://neba.cdget.com/design/color) has the dark-theme values and scoped overrides.
+
 Dark mode responds to `prefers-color-scheme` on its own. To force it, put `.dark` or `[data-theme='dark']` (or `'light'`) on any ancestor: it applies to that subtree, so a dark panel on a light page is one attribute.
 
-Adding a whole new colour family is two edits: an entry in `NebaColor` and five tokens; everything else derives from them.
+Adding a whole new colour family to the library takes an entry in `NebaColor`, five base values in each theme block and the derived tokens that mix them. [**Color**](https://neba.cdget.com/design/color#adding-a-family) lists every edit.
 
 ## Development