@misoto22/design 0.8.0 → 0.9.0

package/dist/agent/NativeSelect.md

@@ -4,7 +4,7 @@ The platform’s own picker, restyled where it can be.
 
 - Group: Forms
 - Import: `import { NativeSelect } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/native-select/
 - Related: select, field
 

package/dist/agent/NavItem.md

@@ -4,7 +4,7 @@ A row in a sidebar.
 
 - Group: Navigation
 - Import: `import { NavItem } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/nav-item/
 - Related: app-shell
 

package/dist/agent/NumberField.md

@@ -0,0 +1,72 @@
+# NumberField
+
+A number, typed or swept to.
+
+- Group: Forms
+- Import: `import { NumberField } from '@misoto22/design'`
+- Version: 0.9.0
+- Docs: https://ui.misoto22.com/components/number-field/
+- Related: input, slider, field
+
+## When to reach for it
+
+The number has a range and a sensible increment. A bare quantity is an Input with type="number"; a value judged by WHERE it sits on a track is a Slider.
+
+## Anatomy
+
+- **Field** (required) — A native number input wearing CONTROL_BASE, so it is the same box as Input, Textarea and Select — same padding, same focus, same disabled opacity. The native spinner buttons are hidden: they are three different controls in three browsers and none of them is this system’s.
+- **Scrub grip** — A horizontal-arrows glyph at the inline start, on unless scrub is false. Dragging it changes the value by one step every 4px, ten steps with Shift held, and it follows the reading direction — in an RTL page, more is to the left. Pointer only and aria-hidden, because the keyboard already has the arrow keys.
+- **Unit** — unit, drawn inside the end of the box and announced through aria-describedby. The slot is a fixed 3rem, so a unit longer than about four characters runs under a long number.
+
+## Best practices
+
+### Do
+
+- Reach for it when a value is TUNED rather than entered — a duration, a line height, an offset. The grip is the whole argument for this over an Input: a reader finds those by sweeping past the neighbouring values, not by typing candidates one at a time.
+- Wrap it in a Field. The root is a div and the id lands on the input inside it, so the label binds and clicks through exactly as it does for an Input — but only if there is a Field to do it.
+- Pass min, max and step. They are what the arrows step by, what one notch of a scrub is worth, and what the value is reconciled with when the field is left; without them the control is an Input with a grip on it.
+
+### Don’t
+
+- Do not expect the range to hold mid-keystroke. Clamping happens on blur, not on every character, because a minimum of 10 otherwise makes 50 unreachable — the 5 is clamped up before the 0 arrives. onValueChange can report a number outside the range; the value that SETTLES is always inside it.
+- Do not turn the grip off and expect a pointer to have another way through. There are no spinner buttons behind it — hiding those is the point — so scrub={false} leaves a mouse with typing and nothing else. Turn it off for a quantity that is chosen rather than swept to, and accept that trade knowingly.
+- Do not put the unit in the box and nowhere else past about four characters. The slot is fixed, so “requests” runs under the number; a long unit belongs in the Field’s label, where it is read rather than clipped.
+
+## Accessibility
+
+- It is a real <input type="number">, so the platform supplies the spinbutton role, the value, and the range it is announced against.
+- unit reaches assistive tech through aria-describedby, so “300” is not announced as a number with no dimension.
+- The grip is aria-hidden and not focusable: it commits nothing a keyboard cannot already reach, and announcing it would offer a reader a control that does nothing when they press it.
+- invalid and aria-invalid are read together, so a form library setting either one paints the same border.
+
+## Keyboard
+
+- ↑ / ↓ — Steps by one step, honouring min and max.
+- Enter — Reconciles what has been typed with the range and the step.
+- Escape — Abandons the edit and restores the last settled value.
+
+## NumberField
+
+A number, typed or swept to. `Input` with `type="number"` is a box that happens to reject letters. This is the control for a number that has a RANGE and a sensible increment: the arrows step it, the grip sweeps it, and `min`, `max` and `step` are honoured on the way out rather than merely announced. Reach for `Slider` instead when the position along the range is the information — a volume, a confidence, anything a reader judges by where the thumb sits. Reach for this when the digits are. A slider that also has to be exact is a `Slider` with `editable`, not one of these beside it. **Clamping happens when the field is left, not while it is being typed.** A minimum of 10 would otherwise make 50 unreachable: the `5` is clamped up to 10 before the `0` arrives. So `onValueChange` can report a number outside the range mid-keystroke, and the value that settles is always inside it. The native spinner buttons are hidden — they are three different controls in three browsers, and none of them is this system's. The grip replaces them for a pointer; the arrow keys were always the keyboard's answer.
+
+### Props
+
+- `value` — `number`.
+- `defaultValue` — `number`.
+- `onValueChange` — `(value: number) => void`. Fires with the parsed number. Raw `onChange` still fires with the event.
+- `min` — `number` default `Number.NEGATIVE_INFINITY`.
+- `max` — `number` default `Number.POSITIVE_INFINITY`.
+- `step` — `number` default `1`. The increment for the arrows and for one notch of a scrub.
+- `unit` — `string`. A unit drawn inside the end of the field — `%`, `px`, `ms`. The field reserves a fixed slot for it, so keep it to about four characters; a longer one runs under a long number. It is announced through `aria-describedby` as well as drawn, because a unit nobody hears turns "300" into a number with no dimension.
+- `scrub` — `boolean` default `true`. A grip at the start of the field that changes the value as it is dragged. On by default, and the reason to reach for this over `<Input type="number">`: a value that is being TUNED — a duration, a weight, an offset — is found by sweeping through neighbouring values, not by typing candidates one at a time. Shift multiplies the travel by ten. Pointer only, and `aria-hidden` for that reason: the same journey on a keyboard is the arrow keys on the field itself, which the platform already provides. Turn it off where the number is a quantity rather than a setting — a line item's quantity is chosen, not swept to.
+- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
+- `ref` — `Ref<HTMLInputElement>`.
+
+Also accepts: `Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'defaultValue' | 'min' | 'max' | 'step' | 'type'>`.
+
+## Examples
+
+```tsx
+<Field label="Line height"><NumberField defaultValue={1.5} min={1} max={3} step={0.1} /></Field>
+<Field label="Timeout"><NumberField defaultValue={30} min={0} max={600} unit="s" /></Field>
+```

package/dist/agent/Pagination.md

@@ -4,7 +4,7 @@ Numbered pages, with the middle elided.
 
 - Group: Navigation
 - Import: `import { Pagination } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/pagination/
 - Related: breadcrumb
 

package/dist/agent/PieChart.md

@@ -4,7 +4,7 @@ Parts of one whole.
 
 - Group: Charts
 - Import: `import { PieChart } from '@misoto22/design/charts'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/pie-chart/
 - Related: radial-chart, bar-chart
 

package/dist/agent/Popover.md

@@ -4,7 +4,7 @@ A panel anchored to a control, holding content you can interact with.
 
 - Group: Overlays
 - Import: `import { Popover } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/popover/
 - Related: tooltip, dropdown-menu
 

package/dist/agent/Progress.md

@@ -4,7 +4,7 @@ A bar that fills, or sweeps when the end is unknown.
 
 - Group: Feedback
 - Import: `import { Progress } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/progress/
 - Related: spinner
 

package/dist/agent/RadarChart.md

@@ -4,7 +4,7 @@ A profile across several named dimensions.
 
 - Group: Charts
 - Import: `import { RadarChart } from '@misoto22/design/charts'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/radar-chart/
 - Related: line-chart, pie-chart
 

package/dist/agent/RadialChart.md

@@ -4,7 +4,7 @@ Values on an arc — a gauge, or a few totals against one scale.
 
 - Group: Charts
 - Import: `import { RadialChart } from '@misoto22/design/charts'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/radial-chart/
 - Related: pie-chart, bar-chart
 

package/dist/agent/RadioGroup.md

@@ -4,7 +4,7 @@ A set of mutually exclusive choices.
 
 - Group: Forms
 - Import: `import { RadioGroup } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/radio-group/
 - Related: checkbox, select
 

package/dist/agent/SankeyChart.md

@@ -4,7 +4,7 @@ Where a quantity goes as it moves through stages.
 
 - Group: Charts
 - Import: `import { SankeyChart } from '@misoto22/design/charts'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/sankey-chart/
 - Related: bar-chart
 

package/dist/agent/ScatterChart.md

@@ -4,7 +4,7 @@ Two measures against each other, one mark per observation.
 
 - Group: Charts
 - Import: `import { ScatterChart } from '@misoto22/design/charts'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/scatter-chart/
 - Related: line-chart, heatmap
 

package/dist/agent/ScrollArea.md

@@ -4,7 +4,7 @@ A box that scrolls, with a scrollbar that looks the same everywhere.
 
 - Group: Surfaces
 - Import: `import { ScrollArea } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/scroll-area/
 - Related: table
 

package/dist/agent/SearchableMenu.md

@@ -4,7 +4,7 @@ A menu of actions you can type into.
 
 - Group: Overlays
 - Import: `import { SearchableMenu } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/searchable-menu/
 - Related: dropdown-menu, command, combobox
 

package/dist/agent/Select.md

@@ -4,7 +4,7 @@ A choice from a list, styled the whole way down.
 
 - Group: Forms
 - Import: `import { Select } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/select/
 - Related: combobox, native-select, field
 

package/dist/agent/Separator.md

@@ -4,7 +4,7 @@ A rule, in the three weights a monochrome page needs — with words in it when t
 
 - Group: Display
 - Import: `import { Separator } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/separator/
 
 ## When to reach for it

package/dist/agent/SequenceFigure.md

@@ -4,7 +4,7 @@ A call chain over time: who asks whom, in what order, and what comes back.
 
 - Group: Diagrams
 - Import: `import { SequenceFigure } from '@misoto22/design/diagrams'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/sequence-figure/
 - Related: workflow-figure, architecture-figure
 

package/dist/agent/Sheet.md

@@ -4,7 +4,7 @@ A panel docked to an edge of the viewport.
 
 - Group: Overlays
 - Import: `import { Sheet } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/sheet/
 - Related: dialog, popover
 

package/dist/agent/Sidebar.md

@@ -0,0 +1,193 @@
+# Sidebar
+
+A navigation rail down the side of an application.
+
+- Group: Navigation
+- Import: `import { Sidebar } from '@misoto22/design'`
+- Version: 0.9.0
+- Docs: https://ui.misoto22.com/components/sidebar/
+- Related: nav-item, collapsible, app-shell
+
+## When to reach for it
+
+A whole application’s navigation, in a column that stays. A list of links inside a page is NavItem on its own; a strip of panels is Tabs.
+
+## Anatomy
+
+- **Provider** (required) — SidebarProvider. It holds whether the rail is open and binds the shortcut that changes it, and it sits ABOVE both the rail and the content beside it — the page has to reserve the rail’s width, and a state that lived inside the rail could only ever be read downwards. It also supplies the tooltip provider a collapsed rail needs, so the icon state works without the app being told to wrap itself in one.
+- **Rail** (required) — Sidebar. A <nav>, not an <aside>: the element decides the landmark, and a rail of links announced as “complementary” is not the one a reader jumps to when they go looking for the navigation. Its width animates between --sidebar-w and --sidebar-w-icon while the column inside stays full width, so the rows do not reflow under the wipe.
+- **Header** — SidebarHeader. The brand, the workspace, the switcher — and where SidebarTrigger belongs. A control that hides a thing lives on the thing; out in an application’s masthead it is one more anonymous icon with nothing connecting it to the column it operates.
+- **Content** — SidebarContent. The scrolling middle, and the only part that scrolls.
+- **Group** — SidebarGroup: a heading, an optional count, an optional action, and rows behind a hairline. The heading is the same size as its rows and outranks them by weight and one step of ink — smaller than what it contains, it reads as a footnote over a list rather than as a title over its own contents.
+- **Row** — SidebarItem, which is NavItem plus the two things a rail adds: a trailing slot, and an answer for the state with no room for words. Collapsed, the label leaves the layout and becomes the row’s tooltip.
+- **Branch** — SidebarBranch: a row that opens onto more rows, behind the same hairline a group draws and one indent further in. It is the line between a place and a heading — a workspace that contains projects is a place containing places, and it carries an icon and a state the way its children do, which a Group has neither of. Two levels is what the indent has room for; a third in a 16rem column is a horizontal scrollbar with an outline in it.
+- **Footer** — SidebarFooter. The utilities a rail ends on, kept out of the index above it.
+- **Page** — SidebarInset, the column beside the rail. It is `min-w-0` — the half every hand-written version forgets, and the reason one wide table inside pushes the page past the viewport and takes the rail’s width with it. Under variant="inset" it is also the panel: the rail becomes the ground, and this draws the bordered --paper surface sitting on it.
+- **Drawer** — What the rail becomes under the provider’s breakpoint (768px by default): fixed against its own edge, over a scrim, and inert while closed. Nothing to render — the same <Sidebar> is both — but it is a different component to a reader, and the collapsible setting does not apply there.
+
+## Best practices
+
+### Do
+
+- Give every row an icon if the rail collapses to icons. The icon is the whole of what a collapsed row shows, and SidebarItem keeps the label drawn on a row without one rather than leaving a blank line — which is a rail that is half collapsed.
+- Choose collapsible by what the rows ARE. icon suits a fixed set a reader learns the shape of; offcanvas suits a long index nobody memorises, where a column of unrecognisable glyphs is worse than no column.
+- Reach for SidebarBranch when the thing is a PLACE that contains places, and for SidebarGroup when it is a heading over a set. A group has no icon and no state because it is not somewhere you can be; a branch has both because it is.
+- Put SidebarTrigger in the header. It is where the component expects it and where a reader looks for it, and it is the difference between a control that belongs to the rail and one that has wandered into the masthead.
+- Wrap the page in SidebarInset rather than a hand-written flex column. It carries min-w-0, which is what stops one wide table inside the page from pushing the whole layout past the viewport, and it is the other half of variant="inset".
+- Pass persist with a key when the rail is an application’s own. A reader who put the rail away did not mean “until the next page”. Only the docked state is kept: restoring an open drawer is a page that loads with its navigation over the top of itself.
+- Give the provider a ground for variant="floating" and variant="inset" — bg-(--stone) on the element holding it. Both draw a --paper panel, and a panel on the same colour as the thing behind it is a border with nothing on either side of it.
+
+### Don’t
+
+- Do not reach for it for navigation inside a page. This is an application landmark that owns a whole edge of the window; a set of links in a column is NavItem, and putting those in a rail gives a page two navigation landmarks competing for the same reader.
+- Do not pass shortcut and then bind Cmd+B yourself. Two handlers on one chord toggle twice and land back where they started, which reads as a rail that ignores its own shortcut. Pass shortcut={null} where the app owns it.
+- Do not nest a branch inside a branch. The indent is sized for two levels at this width, and a third takes the words with it — what a reader gets is an outline with a horizontal scrollbar under it.
+- Do not control open without onOpenChange. The trigger and the shortcut then both do nothing, and the state that looks broken is the one the caller froze.
+- Do not put a transform, filter or perspective on an element wrapping the provider. The drawer is fixed, and any of those makes that ancestor its containing block — so it opens inside the wrapper instead of against the edge of the window.
+- Do not build the phone drawer yourself around this. It already is one under breakpoint, with the scrim, the inert closed state and the close-on-navigate; a second one outside gives the page two drawers and one of them has no scrim.
+
+## Accessibility
+
+- label is required, and names the landmark. A page with two navigations in it announces two things called “navigation” unless each says which it is.
+- The trigger’s name says what it will DO and aria-expanded reports what is true now, so it is never the permanently ambiguous “Toggle sidebar”.
+- A collapsed row keeps its label as its accessible name, through a tooltip — an icon alone is a guess for a sighted reader and nothing at all for a screen reader.
+- A collapsed group keeps its heading as the group’s name even though the words are not drawn.
+- The current row carries aria-current="page", not only a darker ground.
+- The closed drawer is inert, not merely translated off-screen. Off-screen it still holds focus and is still read aloud, so a shut drawer puts its whole index between the reader and the page they were on.
+- The scrim is a button with a name, because tapping beside a drawer is how a drawer is closed — and a gesture that exists only for a pointer is one a keyboard cannot make.
+
+## Keyboard
+
+- ⌘B / Ctrl B — Opens and closes the rail.
+- Enter / Space — On a group heading, folds or unfolds it.
+- Tab — Moves through the rows in the order they are drawn.
+
+## useSidebar
+
+The rail's own state, for anything that has to answer to it. A page beside the rail needs it to reserve the right width; a control inside needs to know whether its label is being drawn. This one THROWS outside a provider, and the parts above do not, and the difference is who made the mistake. A part rendered on its own is somebody writing `<Sidebar>` to see what it looks like; a call to this hook is code asking for state that nothing is keeping, and returning a plausible default there is a layout that is wrong in one state and right in the other with nothing to say which.
+
+## SidebarProvider
+
+Holds whether the rail is open, and binds the shortcut that changes it. Separate from `Sidebar` itself because the answer is needed on BOTH sides of the layout: the rail draws itself from it, and the content beside the rail reserves width from it. A state that lived inside the rail could only ever be read downwards.
+
+### Props
+
+- `open` — `boolean`. Controlled open state. Leave off to let the provider own it.
+- `defaultOpen` — `boolean` default `true`.
+- `onOpenChange` — `(open: boolean) => void`.
+- `collapsible` — `SidebarCollapsible` default `'icon'`. What closing does to the rail. See SidebarProps.collapsible.
+- `shortcut` — `string | null` default `'b'`. The keyboard shortcut that toggles the rail, as a single letter. `b`, with the platform's own modifier, because that is what every editor and every application shell already uses for the same thing. Pass `null` to bind nothing — an app that already owns that chord should not have it taken twice, and a rail that cannot be closed does not need a shortcut for closing it.
+- `side` — `SidebarSide` default `'start'`. Which edge the rail is on. Logical: `end` is the right in LTR, the left in RTL.
+- `variant` — `SidebarVariant` default `'flush'`. How the rail meets the page. `flush` is a column with a hairline down its inner edge — the rail and the page are one surface divided by a line. `floating` lifts the rail off that surface as its own bordered panel with the page ground showing around it. `inset` is the same gesture the other way up: the rail sits on the page ground and `SidebarInset` draws the CONTENT as the panel. `floating` and `inset` both need a ground to sit on — put `bg-(--stone)` on the element holding the provider, or they are a panel on the same colour as the thing behind it.
+- `breakpoint` — `SidebarBreakpoint | null` default `'md'`. The step below which the rail becomes a drawer over the page. A rail is a column when there is a column's worth of room and an overlay when there is not; below this the rail is `fixed`, covers the page from its own edge, and closes onto a scrim. `null` pins it as a column at every width, for a layout that is never narrow — an embedded console, a preview frame. Named, not a number: the switch is a media query in the stylesheet, and a class built from a runtime number is a class the compiler never emitted. It also puts the rail on the same four steps as the page around it.
+- `persist` — `string | null` default `null`. A `localStorage` key under which the DOCKED state is remembered. A reader who put the rail away did not mean "until the next page". Only the docked state is kept: an open drawer is a thing a reader did to this screen, and restoring it on the next visit is a page that opens with its navigation over the top of itself. Read after mount, never during render — a value from storage in the first pass is a hydration mismatch, and the markup the server sent is the one the client has to agree with.
+- `contained` — `boolean` default `false`. The drawer covers its nearest positioned ancestor rather than the window. For a rail inside a bounded frame — a device preview, an embedded console, an example on a documentation page. `fixed` resolves against the viewport wherever the markup sits, so without this the drawer inside a 400px preview opens across the whole page it is previewed on. Give the frame `relative`.
+- `children` (required) — `ReactNode`.
+
+## Sidebar
+
+A navigation rail down the side of an application. A `<nav>`, not an `<aside>`. The element decides the landmark, and a rail of links announced as "complementary" is not the one a screen reader user jumps to when they go looking for the navigation. Composed rather than configured: a rail is a header, a scrolling middle and a footer, and every product wants different things in all three. What this owns is the part that is the same everywhere — the width, the edge, the scroll behaviour, and what happens when it closes. **Closing has three shapes**, and `collapsible` on the provider picks one. `icon` keeps the rail and drops the labels, which is right when the rows are a fixed set a reader learns the shape of. `offcanvas` takes the whole rail away, which is right when the rows are a long index nobody memorises. `none` is a rail that does not close. The trigger belongs INSIDE the rail — `SidebarHeader` places it — rather than out in an application's masthead. A control that hides a thing should live on the thing: in the masthead it is one more anonymous icon in a row of them, and nothing connects it to the column it operates. **Under the provider's `breakpoint` it is a drawer**, not a column: `fixed` against its own edge, over a scrim, and `inert` while closed. Merely translating it off-screen is not closed — it keeps focus and it is still read aloud, so a shut drawer puts its whole index between the reader and the page they were on. The scrim is a real button, because tapping beside a drawer is how a drawer is closed and that gesture has to exist for a keyboard too. `fixed` resolves against the viewport unless an ancestor has a `transform`, `filter` or `perspective`, which makes that ancestor the containing block instead. Do not put one on an element wrapping the provider, or the drawer opens inside it.
+
+### Props
+
+- `label` (required) — `string`. Names the landmark. Required: a page with two navigations in it announces two things called "navigation" unless each of them says which it is.
+- `scrimLabel` — `string` default `'Close the navigation'`. What the scrim behind the open drawer announces. It is a button — tapping beside a drawer closes it, and that has to be a control a keyboard and a screen reader can reach, not a decorated `<div>`.
+- `children` (required) — `ReactNode`.
+
+Also accepts: `Omit<ComponentProps<'nav'>, 'children'>`.
+
+## SidebarInset
+
+The page beside the rail. Every layout built on this component was writing the same `flex min-w-0 flex-1 flex-col` by hand, and `min-w-0` is the half everybody forgets: a flex child's floor is its content, so one wide table inside pushes the whole page past the viewport and takes the rail's width with it. It is also the other half of `variant="inset"`. There the rail is the ground and this is the panel — a bordered `--paper` surface with the ground showing around it — which is why the variant lives on the provider rather than on either piece: one setting, two components, and no way to set half of it. A `<div>`, not a `<main>`. What goes in here is usually a masthead AND the page under it, and only one of those is the main landmark.
+
+## SidebarHeader
+
+The block at the top of the rail: a brand, a workspace, a switcher. It is also where `SidebarTrigger` belongs, and the layout assumes one: anything passed as `children` takes the space and the trigger sits at the inline end of the row.
+
+## SidebarContent
+
+The scrolling middle. Everything that is a list of places goes here.
+
+## SidebarFooter
+
+The block at the bottom: the utilities, the account, the thing a rail ends on. A separate landmark from the content above it because it is a separate kind of thing — a reader scanning the index does not want Trash and Help in it.
+
+## SidebarSeparator
+
+A rule between blocks of rows, inset to the rail's own padding.
+
+## SidebarTrigger
+
+The control that opens and closes the rail. Its accessible name changes with what it will DO, and `aria-expanded` reports what is true now — a button permanently called "Toggle sidebar" tells a screen reader user nothing about which way it will go.
+
+### Props
+
+- `labels` — `{ open: string; close: string }` default `{ open: 'Open the sidebar', close: 'Close the sidebar' }`. What the button announces. Both states, because it says both things.
+
+Also accepts: `ComponentProps<'button'>`.
+
+## SidebarGroup
+
+A labelled block of rows, optionally foldable. The heading is the same SIZE as the rows beneath it and outranks them by weight and by ink. Both halves of that are corrections. Smaller, it inverted the hierarchy it exists to express — a group read as a footnote over a list rather than as a title over its own contents. In the MONO face, which is where it went next, ten of them stacked in a column read as a terminal listing: mono is this system's voice for code, metadata and figures, and a navigation heading is none of those. Rank belongs to weight and to a step up the ink ladder, which are the two signals that can outrank a row without changing what kind of thing it is. An open group draws a hairline down its rows. Fifty rows under seven headings have nothing in them saying which heading any given row belongs to — only the distance to the last one, which is gone the moment the list is scrolled. The whole block hides when the rail is collapsed to icons: a heading with no room for its own word is two or three letters and a number, and the rows are still there underneath as icons.
+
+### Props
+
+- `label` (required) — `string`. The heading over the rows.
+- `count` — `number`. How many rows are inside, printed on the far side of the heading.
+- `badge` — `ReactNode`. A mark that belongs to the GROUP — "Beta", "3 new". Beside the label, not out at the end with the count: it qualifies the words, and a qualifier that has drifted to the other side of the row reads as a second, unrelated fact.
+- `action` — `ReactNode`. A control on the heading row — a menu, an "add" button. Sits between the label and the count, and is NOT rendered inside the heading's own button: a control nested in a control is one the keyboard reaches by pressing the thing it is inside.
+- `collapsible` — `boolean` default `true`. Whether the group folds at all. A group of two rows usually should not.
+- `defaultOpen` — `boolean` default `true`.
+- `children` (required) — `ReactNode`.
+- `className` — `string`.
+
+## SidebarBranch
+
+A row that opens onto more rows. The thing a rail is for and the thing a flat list of groups cannot do: a workspace with projects in it, a folder with documents in it, a service with its environments. `SidebarGroup` is a HEADING over a set — it is not itself a place, and it has no icon and no state. This is a place that contains places, so it is a row like any other and it carries the same icon, trailing slot and hover as its children. The children sit behind the same hairline a group draws, one indent further in, so nesting reads as depth rather than as two unrelated lists. Two levels is what the indent has room for at this width; a third is a tree, and a tree in a 16rem column is a horizontal scrollbar with an outline in it. Collapsed to icons the row becomes its icon and the children are not drawn — there is nowhere for an indent to go, and a nested icon under an unnested one is two glyphs with no visible relationship.
+
+### Props
+
+- `label` (required) — `string`. The row's own words, and the name of the group it opens.
+- `icon` — `LucideIcon`. Drawn at the start of the row, and the whole of the row when collapsed.
+- `trailing` — `ReactNode`. A count or a state at the end of the row.
+- `defaultOpen` — `boolean` default `false`.
+- `open` — `boolean`.
+- `onOpenChange` — `(open: boolean) => void`.
+- `children` (required) — `ReactNode`.
+- `className` — `string`.
+
+## SidebarItem
+
+One row. `NavItem` with the two things a RAIL adds: a trailing slot, and an answer for the state where there is no room for words. Collapsed to icons the label is removed from the layout rather than hidden with CSS — a `sr-only` label still occupies the flex row's gap — and moves into a tooltip, because an icon on its own is a guess for everyone and unusable for a screen reader. A row with no `icon` keeps its label collapsed, since hiding it would leave a blank row: the icon is what makes the collapsed state legible, and a rail that collapses needs one on every row.
+
+### Props
+
+- `trailing` — `ReactNode`. A count or a state on the far side of the row. Hidden with the label.
+
+Also accepts: `NavItemProps`.
+
+## Types
+
+- `SidebarCollapsible` = `'icon' | 'offcanvas' | 'none'`
+- `SidebarSide` = `'start' | 'end'`
+- `SidebarVariant` = `'flush' | 'inset' | 'floating'`
+- `SidebarBreakpoint` = `'sm' | 'md' | 'lg' | 'xl'`
+
+## Examples
+
+```tsx
+<SidebarProvider>
+  <Sidebar label="Documentation">
+    <SidebarHeader>Acme</SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup label="Guide" count={2}>
+        <SidebarItem href="/start" icon={Home}>Getting started</SidebarItem>
+      </SidebarGroup>
+    </SidebarContent>
+  </Sidebar>
+</SidebarProvider>
+<SidebarBranch label="Acme HQ" icon={Building} defaultOpen>
+  <SidebarItem href="/hq" icon={Home}>Home</SidebarItem>
+  <SidebarItem href="/hq/tasks" icon={CheckSquare}>My tasks</SidebarItem>
+</SidebarBranch>
+```

package/dist/agent/Skeleton.md

@@ -4,7 +4,7 @@ The shape of the page, before the page.
 
 - Group: Feedback
 - Import: `import { Skeleton } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/skeleton/
 - Related: spinner, empty-state
 

package/dist/agent/Slider.md

@@ -4,7 +4,7 @@ A value chosen along a range.
 
 - Group: Forms
 - Import: `import { Slider } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/slider/
 - Related: progress
 
@@ -14,6 +14,7 @@ A value chosen along a range.
 - **Range** — The --accent fill from the minimum to the thumb, or between the two thumbs of a range.
 - **Thumb** — One per entry in the value array — so the number of thumbs comes from the value, not from a prop, and a slider given neither value nor defaultValue falls back to the primitive’s own default of one thumb at the minimum. Each is a 16px circle with an invisible 44px hit area from a before pseudo-element.
 - **Value readout** — Only with showValue: a mono row above the track, the names on the start edge and the formatted values on the end, each joined by an en dash and in the thumbs’ own order — so a two-ended range reads “Minimum – Maximum” over “10 – 90”.
+- **Editable readout** — What editable turns those figures into: one box per thumb, showing format’s output at rest and the bare number while it has focus, so a reader still sees “$1,200” and a typist is never asked to type a currency symbol back. Each is named separately from its thumb — two controls announcing “Quality” is one control announced twice.
 
 ## Best practices
 
@@ -21,11 +22,12 @@ A value chosen along a range.
 
 - Pass defaultValue or value whenever there is more than one end to it. The thumb count comes from that array, so a price filter left to the default is a single thumb sitting at the minimum.
 - Pass an array of two names for a two-thumb range: every thumb after the first falls back to names[0], so both ends of a price filter otherwise announce themselves as “Minimum”.
-- Put an Input beside it when the exact number matters. A slider cannot be typed into, and someone who needs 37 rather than roughly 40 is dragging a 16px thumb across a hundred steps to get it.
+- Turn on editable when the exact number matters. A slider on its own cannot be typed into, and someone who needs 37 rather than roughly 40 is dragging a 16px thumb across a hundred steps to get it — the box in the readout is the way out, and it replaces the second Input this used to ask for.
 
 ### Don’t
 
 - format becomes each thumb’s aria-valuetext, which REPLACES the number rather than decorating it — so a formatter that rounds hard or drops the unit is what a screen reader gets instead of the value.
+- editable typing is bounded by the NEIGHBOURING thumb as well as by min and max, and it has to be: 90 typed into the lower end of a range sitting at 70 would otherwise cross the two thumbs over. So a number can be accepted and then land somewhere else, and the box shows where it landed.
 - Do not disable a slider to make it read-only: the whole control dims and stops taking the pointer, and Radix drops the thumb out of the tab order, so the value becomes unreachable rather than uneditable.
 - Do not pass two names to a one-thumb slider: the heading prints one name per THUMB, so the second is drawn nowhere and announced nowhere.
 - A Field’s label above it does not name it and does not click through: the role is on the THUMB and the root is a <span>, so the label prop here is the only name a reader hears. The hint and the error do reach the thumb.
@@ -45,12 +47,13 @@ A value chosen along a range.
 
 ## Slider
 
-A value chosen along a range. Radix owns the keyboard contract — arrows step, Page keys jump, Home and End reach the ends — and the ARIA that reports the value. What is here is the look, and the labelling, which is the part a slider most often gets wrong: a thumb that announces "42" and nothing else leaves a screen reader user with a number and no idea what it measures. A 44px hit area sits invisibly around the 16px thumb, because a thumb sized for the design is well under any pointer-target guideline. Inside a `Field`, the hint, the error and the requirement land on the THUMB, which is the element carrying `role="slider"` — on the root they would sit on a `<span>` with no role and announce nothing. The NAME still comes from `label` here: a field's label above a slider points at that same roleless root, so it neither names the control nor clicks through to it.
+A value chosen along a range. Radix owns the keyboard contract — arrows step, Page keys jump, Home and End reach the ends — and the ARIA that reports the value. What is here is the look, and the labelling, which is the part a slider most often gets wrong: a thumb that announces "42" and nothing else leaves a screen reader user with a number and no idea what it measures. A 44px hit area sits invisibly around the 16px thumb, because a thumb sized for the design is well under any pointer-target guideline. `editable` is the answer to the thing a slider cannot do. Reach for it whenever the exact figure is the point — a budget, a timeout, a price — and leave it off when the value is genuinely approximate, because a box invites precision the setting may not have. Inside a `Field`, the hint, the error and the requirement land on the THUMB, which is the element carrying `role="slider"` — on the root they would sit on a `<span>` with no role and announce nothing. The NAME still comes from `label` here: a field's label above a slider points at that same roleless root, so it neither names the control nor clicks through to it.
 
 ### Props
 
 - `label` (required) — `string | [string, string]`. Names the control. Required: a slider with no name announces only a number, and a number with no noun is not information. A range slider (two thumbs) needs one name per thumb — pass an array.
 - `showValue` — `boolean` default `false`. Prints the current value beside the label. A two-thumb range prints both names and both values, in the same order — the heading used to print the first name over a pair of numbers, which read as "Minimum" over "10 – 90".
+- `editable` — `boolean` default `false`. Turns that readout into a box the number can be typed into, and implies `showValue`. A slider is a control for a NEIGHBOURHOOD; someone who needs 1,150 rather than roughly 1,200 is dragging a 16px thumb across a hundred steps to get it. This is the way out, in the place the value already is, rather than a second field beside the track that has to be kept in step by hand. The box shows `format`'s output at rest and the bare number while it has focus, so a reader still sees "$1,200" and a typist is never asked to type a currency symbol back.
 - `format` — `(value: number) => string`. Renders the value with a unit or a currency, e.g. `(n) => n + '%'`. Reaches assistive tech as well as the readout: it becomes each thumb's `aria-valuetext`, so a thumb showing "$1,200" announces that rather than the bare number. Left off, the platform announces the value itself.
 
 Also accepts: `ComponentProps<typeof SliderPrimitive.Root>`.
@@ -59,4 +62,5 @@ Also accepts: `ComponentProps<typeof SliderPrimitive.Root>`.
 
 ```tsx
 <Slider label="Quality" defaultValue={[80]} max={100} step={5} showValue format={(n) => `${n}%`} />
+<Slider label="Monthly budget" defaultValue={[1200]} max={5000} step={50} editable format={(n) => `$${n}`} />
 ```

package/dist/agent/Sparkline.md

@@ -4,7 +4,7 @@ A run of numbers at the size of a word.
 
 - Group: Data
 - Import: `import { Sparkline } from '@misoto22/design/charts'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/sparkline/
 - Related: line-chart, table
 

package/dist/agent/Spinner.md

@@ -4,7 +4,7 @@ The one “working” indicator — a ring, never a shimmer.
 
 - Group: Feedback
 - Import: `import { Spinner } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/spinner/
 - Related: skeleton, progress
 

package/dist/agent/StatusDot.md

@@ -4,7 +4,7 @@ The dot beside a status word.
 
 - Group: Display
 - Import: `import { StatusDot } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/status-dot/
 - Related: status-pill
 

package/dist/agent/StatusPill.md

@@ -4,7 +4,7 @@ A live state, named: a dot plus an uppercase mono label.
 
 - Group: Display
 - Import: `import { StatusPill } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/status-pill/
 - Related: status-dot, badge
 

package/dist/agent/Steps.md

@@ -4,7 +4,7 @@ A numbered sequence, as a rail — one thing after another, with a rule through
 
 - Group: Display
 - Import: `import { Steps } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/steps/
 - Related: diagram, article
 

package/dist/agent/Switch.md

@@ -4,7 +4,7 @@ A setting that takes effect immediately.
 
 - Group: Forms
 - Import: `import { Switch } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/switch/
 - Related: checkbox
 

package/dist/agent/Table.md

@@ -4,7 +4,7 @@ A ruled data table — alignment, sorting and rules all per column.
 
 - Group: Data
 - Import: `import { Table } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/table/
 - Related: card, figure-band
 
@@ -85,6 +85,8 @@ Also accepts: `Omit<ThHTMLAttributes<HTMLTableCellElement>, 'align'>`.
 
 ## TD
 
+A body cell. TOP-aligned, and that is a choice about which kind of table is the common one here: a cell holding a paragraph. Top is what lines the first lines of a row up with each other, and centring a two-word term against a four-line description puts the term in the middle of nothing. It is the wrong default for the other kind — a row of one-line values with a control in it. A 36px button next to 16px of text makes a 52px row, and every other cell then hangs at the top of it with twenty pixels of nothing underneath, which reads as a column that has slipped. Pass `className="align-middle"` on those rows; the data-table template does.
+
 ### Props
 
 - `align` — `TableAlign` default `'start'`. Which edge the cell's contents sit against. Match the column's header.

package/dist/agent/Tabs.md

@@ -4,7 +4,7 @@ One strip, several panels.
 
 - Group: Navigation
 - Import: `import { Tabs } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/tabs/
 - Related: accordion
 

package/dist/agent/Tag.md

@@ -4,7 +4,7 @@ A subject label — a topic, a technology, a filter facet — that filters with
 
 - Group: Display
 - Import: `import { Tag } from '@misoto22/design'`
-- Version: 0.8.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/tag/
 - Related: badge, status-pill