torch-glare 2.5.5 → 2.5.6

package/docs/components/data-views/index.md

@@ -39,7 +39,7 @@ import {
   useDataViewsFilters, useDataViewsPanel, useDataViewsPanelTabs,
   useActiveRow,                                // the row behind `activeId`
   Cell,                                        // paint one field the way the views paint it
-  markView, markHeader, markPanel,             // register a part of your own
+  markView, markHeader, markPanel, markEmpty,  // register a part of your own
   SkeletonBar, skeletonKeys,                   // the loading pieces every view is built from
   getByPath, formatPathLabel, defaultGetRowId, // read a value by dotted path
   buildCardRows, resolveBadgeVariant,
@@ -135,10 +135,35 @@ see the change, "new filter" and "new page" have already become one object.
 
 ## Empty and loading
 
-Neither is a part you render. When there is nothing to show, the view shows **nothing** — the table
-keeps its header band and has no rows; the board keeps its columns and has no cards. While
-`loading` is set, each view paints a **skeleton in its own shape**: the table shimmers rows at the
-real row height and column widths, the board shimmers cards inside its columns.
+**Loading is not a part you render.** While `loading` is set, each view paints a **skeleton in its
+own shape**: the table shimmers rows at the real row height and column widths, the board shimmers
+cards inside its columns.
+
+**Empty is opt-in.** By default the view simply shows nothing — the table keeps its header band and
+has no rows, the board keeps its columns and has no cards. That default is deliberate: a centred
+message in place of the view throws away the chrome, and it cannot tell "no results" from "not
+fetched yet".
+
+When you do want something there, render `DataViews.Empty` anywhere among the children. It is a
+passthrough with a marker — it holds no opinion about what an empty state looks like, it only tells
+the root to put its content where the view goes. The root swaps it in when the query has settled and
+returned nothing (`!loading && rows.length === 0`):
+
+```tsx
+<DataViews rows={rows} fields={fields} loading={loading}>
+  <DataViews.Table />
+  <DataViews.Empty>
+    <div className="flex flex-1 flex-col items-center justify-center gap-2">
+      <p>No invoices match these filters.</p>
+      <Button onClick={clearFilters}>Clear filters</Button>
+    </div>
+  </DataViews.Empty>
+</DataViews>
+```
+
+Your content is what receives the body slot's height, so give it `flex-1` if it should centre.
+Wrapping `DataViews.Empty` in a component of your own? Mark that wrapper with `markEmpty` so the
+root still recognises it, the same way `markView` / `markHeader` / `markPanel` work.
 
 ## Large datasets
 
@@ -183,6 +208,7 @@ and that is not built.
 | `DataViews.Board` | a kanban board | `groups` — it never groups rows itself | [`views`](./examples/views.md) |
 | `DataViews.Inbox` | a master list beside a detail pane | the pane, as `children` | [`inbox-routing`](./examples/inbox-routing.md) |
 | `DataViews.Tree` | a hierarchy, optionally beside a pane | `nodes` — it never builds one | [`tree-custom`](./examples/tree-custom.md) |
+| `DataViews.Empty` | your content, in place of the view, once a settled query returns no rows | the content — it holds no opinion about what empty looks like | — |
 
 Each takes `id`, `label` and `icon` to control how it appears in the switcher, so the same view can
 be registered twice with different data. Full props are under

package/docs/components/data-views/migration.md

@@ -56,11 +56,13 @@ Three parts of `DataViews` itself went in the same release.
 `rows`; whether there is more is derived from `rows.length < total`, so there is no `hasMore` prop.
 See the *Large datasets* section of the [DataViews doc](./index.md).
 
-**`DataViews.Empty`** — when there is nothing to show, the view shows nothing: the table keeps its
-header band and has no rows, the board keeps its columns and has no cards. A centred message in
-place of the view threw away the chrome, and it could not tell "no results" apart from "not fetched
-yet" — so the first load of every page announced that nothing matched before anything had been
-asked for.
+**`DataViews.Empty`** — *removed, then re-added as opt-in.* It was dropped because rendering a
+centred message in place of the view threw away the chrome, and it could not tell "no results" apart
+from "not fetched yet" — so the first load of every page announced that nothing matched before
+anything had been asked for. It is back on different terms: the default is still to show nothing,
+and `DataViews.Empty` now renders **only** once the query has settled with no rows
+(`!loading && rows.length === 0`). Nothing to migrate — omit it and behaviour is unchanged. See the
+*Empty and loading* section of the [DataViews doc](./index.md).
 
 **`DataViews.Loading`** — each view now paints its own skeleton, in its own shape, driven by the
 `loading` prop. A custom view registered with `markView` gets the same thing: read `loading` from

package/docs/components/drawer.md

@@ -433,7 +433,7 @@ There is **no automatic per-direction styling**. The anchor is set on the root w
 | Drag handle | on — `<DrawerPanel showHandle>` | off (the default) | off (the default) |
 | Frame / tray | usually off (`framed={false}`) for clean sheet | on (default) for the dark tray | on (default) |
 | Rounded corners | top corners only | all/left corners | top-left + bottom corners |
-| Notch side | top-left (`notchSide="left"`) | top-left | mirror to `notchSide="right"` |
+| Notch side | inline-start (`notchSide="start"`) | inline-start | mirror to `notchSide="end"` |
 | Best for | mobile sheets, action sheets, comments | create/edit forms, filters, detail panels | RTL panels, side navigation |
 
 ### Bottom (default)
@@ -509,7 +509,7 @@ A floating panel anchored to the right edge — the canonical home for create/ed
 
 ### Left (RTL / navigation)
 
-Mirror of the right recipe: `direction="left"`, anchor to the left edge, and if you use a notch, set `notchSide="right"` so the tab mirrors correctly.
+Mirror of the right recipe: `direction="left"`, anchor to the left edge, and if you use a notch, set `notchSide="end"` so the tab sits on the panel's trailing edge.
 
 ```tsx
 <Drawer direction="left">
@@ -517,7 +517,7 @@ Mirror of the right recipe: `direction="left"`, anchor to the left edge, and if
     <Button variant="PrimeStyle">Open left drawer</Button>
   </DrawerTrigger>
   <DrawerContent
-    notchSide="right"
+    notchSide="end"
     wrapperClassName="top-2 left-2 bottom-2 right-auto mt-0 h-auto w-[420px] max-w-[calc(100vw-16px)]"
     notch={
       <DrawerNotch>
@@ -589,7 +589,7 @@ brings its own background. This is where direction-specific styling is applied.
 |---|---|---|---|
 | `framed` | `boolean` | `true` | Show the dark "tray" frame (border + inset shadow) around the panel. Set `false` for clean bottom sheets. |
 | `notch` | `ReactNode` | — | A `DrawerNotch` tab rendered on the top edge. |
-| `notchSide` | `"left" \| "right"` | `"left"` | Which side the notch attaches to (and which corner stays square). Use `"right"` for left-anchored drawers. |
+| `notchSide` | `"start" \| "end"` | `"start"` | Which **inline** edge the notch attaches to (and which corner stays square). Logical, so it mirrors under `dir="rtl"` without you computing a direction. Use `"end"` for left-anchored drawers. |
 | `wrapperClassName` | `string` | — | Classes on the outer positioned element — this is how you anchor/size the panel per direction. |
 | `className` | `string` | — | Classes on the **dark tray**. Add a `gap-*` here when the tray holds more than one child. |
 | `trayClassName` | `string` | — | **Deprecated** — an alias for `className` (merged last, so it still wins). |
@@ -629,7 +629,7 @@ with each bringing its own background.
 | `DrawerDescription` | Muted supporting text (maps to Vaul `Drawer.Description`). |
 | `DrawerBadge` | Small uppercase status pill. `color`: `Blue \| Green \| Red \| Yellow \| Purple \| Gray` (default `Blue`). |
 | `DrawerFooter` | Bottom action area (`mt-auto`, stacked). |
-| `DrawerNotch` | The top-edge tab container. `side`: `"left" \| "right"`. |
+| `DrawerNotch` | The top-edge tab container. `side`: `"start" \| "end"` (default `"start"`); normally cloned in by `DrawerContent` from `notchSide`. |
 | `DrawerNotchClose` | Round close button for inside a notch. |
 | `DrawerNotchPill` | Pill button for inside a notch. `color`: `Yellow \| Blue \| Gray` (default `Yellow`). Styled `<button>` only — wire navigation yourself via `onClick` (see ["What 'Open in new tab' does"](#what-open-in-new-tab-does)). |
 | `DrawerNotchDivider` | Thin vertical divider between notch items. |

package/docs/components/form-builder.md

@@ -136,6 +136,7 @@ that.
 | `FormBuilder.Select` (`options`)                                            | `Select`                                                                              | `string`                                                     |
 | `FormBuilder.SearchableSelect` (`options`, async: `onSearchChange`/`onLoadMore`/`hasMore`) | `SearchableSelect`                                                      | `string`                                                     |
 | `FormBuilder.MultiSelect` / `.Tags` (`options`)                             | `BadgeField`                                                                          | `string[]`                                                   |
+| `FormBuilder.MultiSelect` / `.Tags` (`creatable`)                           | `BadgeField` with free text                                                           | `string[]` — values not in `options` survive                 |
 | `FormBuilder.RadioList` (`options`, each with optional `description`)       | boxed radio list                                                                      | `string`                                                     |
 | `FormBuilder.CheckboxGroup` (`options`, each with optional `description`)   | boxed checkbox list                                                                   | `string[]`                                                   |
 | `FormBuilder.RadioCards` (`options` with `description`)                     | `RadioCard`                                                                           | `string`                                                     |
@@ -214,7 +215,10 @@ country code.
 `FormBuilder.RadioList` (single-select, `string`) and `FormBuilder.CheckboxGroup` (multi-select,
 `string[]`) render their `options` as a boxed, divided list — control on the left, primary
 label, and an optional per-option `description` shown as a secondary label. The whole row is
-clickable. Multi-select is also available as `.MultiSelect` / `.Tags` (a tag-chip picker).
+clickable. Multi-select is also available as `.MultiSelect` / `.Tags` (a tag-chip picker). Add
+`creatable` to either and the user can type a value that is not in `options` and commit it with
+Enter or comma; pass `options={[]}` for a pure free-text list. (`createLabel` is a `BadgeField`
+prop — it is not forwarded, so the create row keeps its default label inside a form.)
 
 `FormBuilder.SwitchBox` (value `boolean`) is a switch wrapped in a `#f9f9f9` field box. It
 renders like any other field — the `label` sits in the normal label column — and the box holds
@@ -227,6 +231,10 @@ presentation, so it lives there.
 form** (via context), so it submits even when placed in a header / action bar that renders
 _outside_ the `<form>` — no manual `form={id}` wiring.
 
+It also takes `disabled`, for permission gating: someone with read access should still *see* a
+record, so a Save they may not use is disabled rather than removed — a missing button looks broken,
+a disabled one says "not yours to change". The server refuses the write either way.
+
 ## Moved to FormRenderer
 
 These all used to live here. They are chrome, so they now live on

package/docs/components/form-renderer.md

@@ -58,6 +58,7 @@ It renders in the form's header action pill (page) or the drawer header (drawer)
 | `FormRenderer.Back` / `.Next`               | Chevron step controls. The header's action bar prepends them for you.           |
 | `FormRenderer.Sidebar` / `.Tab`             | The display-only [detail-tabs](#detail-tabs-sidebar) view.                     |
 | `FormRenderer.Grid` / `.Row`                | Read-only display cells inside a detail tab.                                    |
+| `FormRenderer.NotchAction`                  | A pill in the drawer's notch. You own the label, so it translates.              |
 
 ### `FormRenderer.Section`
 
@@ -109,6 +110,10 @@ import { FormBuilder } from "@/components/FormBuilder";
 | `actions`                                                      | `ReactNode`                   | The form's action bar — rendered in the header action pill (page) or drawer header (drawer). Put the Save here: `actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}`. A bare `FormBuilder.Submit` auto-targets this form.                                                   |
 | `id`                                                           | `string`                      | `id` on the underlying `<form>`. Optional — FormRenderer generates and wires one otherwise.                                                                                                                                                                                      |
 | `open` / `onOpenChange` / `title` / `badge` / `onOpenInNewTab` | —                             | Drawer control (when `display="drawer"`). `title` / `badge` are strings that override `header.title` / `header.label`.                                                                                                                                                           |
+| `embedded`                                                     | `boolean`                     | Render without the rounded body card, for a host that already draws one. Defaults to `true` in a drawer.                                                                                                                                                                          |
+| `activeTab` / `onTabChange`                                    | `string` / `(tab) => void`    | Make the [detail-tabs](#detail-tabs-sidebar) rail controlled, so the tab can live in the URL (`?tab=audit`) and survive a reload. Omit both for the uncontrolled default. Inert in form mode.                                                                                     |
+| `activeStep` / `onStepChange`                                  | `number` / `(index) => void`  | External control of a `FormRenderer.Stepper`'s step, for a wizard owned by something other than form validity. In controlled mode internal advancement is suppressed and a click is *reported*, not applied. Omit both and the stepper behaves exactly as before.                  |
+| `drawer`                                                       | `{ side?; nested?; framed?; hideHeader?; bareBody?; description?; wrapperClassName?; className? }` | Drawer layout, forwarded to `FormDrawer` — see [Drawer layout](#drawer-layout). One object rather than eight flat props, since none of it means anything on a page.                                                |
 
 ## Drawer
 
@@ -129,6 +134,60 @@ import { FormBuilder } from "@/components/FormBuilder";
 </FormRenderer>
 ```
 
+### Drawer layout
+
+Everything about how the drawer is *shaped* goes in one `drawer` object, because none of it means
+anything on a page:
+
+| Key               | Type                          | Default         | What it does                                                                                       |
+| ----------------- | ----------------------------- | --------------- | -------------------------------------------------------------------------------------------------- |
+| `side`            | `'inline-end' \| 'bottom'`    | `'inline-end'`  | Which edge it slides from. `'bottom'` is a sheet and drops the notch — there is no inline edge to hang it from. The default follows document direction. |
+| `nested`          | `boolean`                     | `false`         | **Required** when this drawer opens inside another one, or the two roots fight over the overlay and the scroll lock. Throws without a parent Drawer. |
+| `framed`          | `boolean`                     | `true`          | The dark tray frame and the panel's border / inset shadow.                                          |
+| `hideHeader`      | `boolean`                     | `false`         | Skip the header bar, for a child that draws its own. Also drops the body's top padding.             |
+| `bareBody`        | `boolean`                     | `false`         | Skip the padded scroll wrapper, for a child that already scrolls and offsets for its own header.    |
+| `description`     | `string`                      | —               | Screen-reader-only description. vaul warns when a drawer has none.                                  |
+| `wrapperClassName`| `string`                      | per `side`      | Lands on the positioner — width, height, insets. Replaces the default sizing.                       |
+| `className`       | `string`                      | —               | Lands on the tray.                                                                                  |
+
+```tsx
+// A bottom sheet, opened from inside another drawer.
+<FormRenderer
+  display="drawer"
+  open={open}
+  onOpenChange={setOpen}
+  title="Quick add"
+  drawer={{ side: "bottom", nested: true, description: "Add a line item" }}
+  onSubmit={save}
+  actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
+>
+  {fields}
+</FormRenderer>
+```
+
+### `FormRenderer.NotchAction`
+
+Buttons in the drawer's notch, authored by you. `onOpenInNewTab` still works, but it hardcodes an
+English label and allows only one action — write `NotchAction` children instead and you own both.
+They render nothing where you write them; the renderer lifts them into the notch.
+
+```tsx
+<FormRenderer display="drawer" open={open} onOpenChange={setOpen} title={t("invoice")}>
+  <FormRenderer.NotchAction onClick={openFullPage}>
+    {t("openInNewTab")}
+    <i className="ri-arrow-right-up-line text-[12px]" />
+  </FormRenderer.NotchAction>
+  <FormRenderer.NotchAction color="Blue" onClick={print}>
+    {t("print")}
+  </FormRenderer.NotchAction>
+
+  {fields}
+</FormRenderer>
+```
+
+`color` matches `DrawerNotchPill` and defaults to `"Yellow"`. Ignored on a page-display form, and a
+`side: "bottom"` sheet has no notch to put them in.
+
 ## Stepper
 
 Drop a `FormRenderer.Stepper` in as the child. The Save lives in the header `actions` and
@@ -140,6 +199,10 @@ validates the current step, then advances (disabled on the last step). A step th
 validation **stays checked** in the rail — even after you navigate back — while a live validation
 error overrides it to red. You still pass just the Submit; the nav is wired for you:
 
+The rail **stays put while the fields scroll**. It is navigation, so it pins below the header rather
+than scrolling out of view with the form; a rail taller than the form body scrolls to its end first,
+as any sticky element does.
+
 ```tsx
 <FormRenderer
   onSubmit={save}
@@ -266,7 +329,14 @@ outside the `<form>`, wire the Save button to the form via `id` / `form={id}`:
 ```
 
 `FormDrawer` props: `open`, `onOpenChange`, `title`, `badge`, `variant`, `actions`,
-`onOpenInNewTab`, `children`, `summary`. It owns no form state.
+`onOpenInNewTab`, `notchActions`, `children`, `summary`, plus the layout flags listed under
+[Drawer layout](#drawer-layout) — `side`, `nested`, `framed`, `hideHeader`, `bareBody`,
+`description`, `wrapperClassName`, `className`. It owns no form state.
+
+`notchActions` is the notch's button slot. Going through `FormRenderer` you rarely set it directly —
+write `FormRenderer.NotchAction` children and they are lifted into it for you. Using `FormDrawer` on
+its own, pass the buttons here. When both `notchActions` and `onOpenInNewTab` are given, the former
+wins; `onOpenInNewTab` remains only for callers happy with its built-in English label.
 
 ### The title
 

package/docs/components/section-block.md

@@ -380,6 +380,12 @@ The layout has three stacked parts, and the order matters. Only the **scroller**
 horizontally; the header actions above it and the end-action below it stay put, which is
 what keeps `Add New` reachable on a wide table.
 
+The section body is itself the horizontal scrollport, so a table wider than the card scrolls
+**inside** it rather than being clipped or widening the page. One consequence worth knowing: a
+scrollport is the containing block for `position: sticky`, so a `Table`'s sticky header inside a
+section now resolves against a box that never scrolls vertically — i.e. it stops sticking. If you
+need a sticky header, give the table its own vertical scroller.
+
 ```tsx
 import { SectionBlock } from "@/components/SectionBlock";
 import { Button } from "@/components/Button";

package/docs/migration/changelog.md

@@ -28,6 +28,12 @@ npx torch-glare@latest add Button
 
 - **v2.5.5** — **breaking**: `DataViews.Filters.Summary` is removed with no shim; delete any
   `<DataViews.Filters.Summary />` (render your own from `useDataViewsFilters()` if you want one).
+  `DrawerContent.notchSide` / `DrawerNotch.side` become logical `"start" | "end"` (was
+  `"left" | "right"`), and `TreeFolder`'s drag wiring is internal — `dragHandlers`,
+  `TreeFolderRowDragHandlers`, `UseTreeFolderDnDResult`, `scrollContainerRef` and
+  `getRowDragHandlers` are gone. New, non-breaking: `BadgeField` `creatable` / `createLabel`,
+  `FormRenderer` `embedded` / controlled tabs and steps / `drawer` layout options /
+  `FormRenderer.NotchAction`, `FormBuilder.Submit` `disabled`, and `DataViews.Empty`.
   Also, every `FormBuilder.*` field takes a `hints` array, so one field can
   carry several alerts. The validation error renders first, your hints follow. See
   [FormBuilder](../components/form-builder.md#hints). Dropdown panels (`Select`,

package/docs/reference/hooks.md

@@ -20,6 +20,7 @@ Custom React hooks that provide reusable functionality for common UI patterns. A
 - **useClickOutside** - Detect clicks outside a referenced element
 - **useResize** - Handle element resizing with RTL support
 - **useTagSelection** - Manage tag selection state with keyboard navigation
+- **useHtmlDir** - Track the document's text direction from `<html dir>`
 
 ---
 
@@ -1498,3 +1499,25 @@ All hooks support:
 - Edge 90+
 
 **IntersectionObserver** (useActiveTreeItem): Requires polyfill for older browsers.
+
+---
+
+## useHtmlDir
+
+Tracks the document's text direction from `<html dir>`, re-reading it when it changes — a language
+switch, say. Returns `"ltr" | "rtl"`.
+
+```tsx
+import { useHtmlDir } from "@/hooks/useHtmlDir";
+
+const dir = useHtmlDir();
+```
+
+Most mirroring should be done in CSS with logical properties, which need no JS at all. Reach for
+this only where a library wants the direction as a **value**: several Radix primitives default to
+`"ltr"` when given no `dir` prop and no `DirectionProvider`, and vaul computes an inline transform
+from its `direction` prop, which a stylesheet cannot override mid-drag.
+
+| Returns | Notes |
+| --- | --- |
+| `"ltr" \| "rtl"` | SSR-safe — returns `"ltr"` when there is no `document`. Watches the attribute with a `MutationObserver`, so a runtime language switch updates every consumer. |

package/docs/reference/utilities.md

@@ -702,3 +702,25 @@ These utilities depend on the following external libraries:
 - [Tailwind CSS Documentation](https://tailwindcss.com)
 - [date-fns Format Reference](https://date-fns.org/docs/format)
 - [TypeScript Utility Types](https://www.typescriptlang.org/docs/handbook/utility-types.html)
+
+---
+
+## Scroller Utilities
+
+### horizontalScrollerStyles
+
+The design's 14px horizontal scroller as a class string: a thin track that thickens and turns blue
+on hover. Shared by `TableScroller` and `SectionBlock`'s body so the two cannot drift.
+
+```tsx
+import { horizontalScrollerStyles } from "@/utils/scroller";
+import { cn } from "@/utils/cn";
+
+<div className={cn(horizontalScrollerStyles, "rounded-lg")}>
+  <table className="w-max">…</table>
+</div>
+```
+
+It includes `overflow-x-auto overflow-y-hidden`, so the element it lands on becomes the scrollport —
+you do not add an overflow class yourself.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "torch-glare",
-  "version": "2.5.5",
+  "version": "2.5.6",
   "type": "module",
   "license": "MIT",
   "description": "A copy-in React component library (TypeScript + Radix UI + Tailwind CSS). Its CLI copies component source directly into your project — you own the code.",