@matthiaskrijgsman/mat-ui 0.0.40 → 0.0.42

package/README.md

@@ -33,7 +33,7 @@ pnpm install @matthiaskrijgsman/mat-ui
 
 ### Styles
 
-Import the mat-ui stylesheet in your CSS entry file:
+Import the mat-ui stylesheet in your CSS entry file. Be sure to do this **after** the Tailwind import.
 
 ```css
 @import "@matthiaskrijgsman/mat-ui/style";
@@ -49,141 +49,6 @@ function App() {
 }
 ```
 
-## Rich text editor (`InputLexical`)
-
-`InputLexical` is a [Lexical](https://lexical.dev)-powered rich text editor styled like the rest of the kit. It ships with two toolbar variants that share the exact same controls:
-
-- **`static`** (default) — a light toolbar fixed at the top of the editor.
-- **`floating`** — a dark bar that appears above the editor while it is focused, matching the editor width.
-
-Lexical and its plugins are **peer dependencies** — install them alongside the library:
-
-```bash
-pnpm add lexical @lexical/react @lexical/rich-text @lexical/list @lexical/link @lexical/selection @lexical/utils
-```
-
-### Basic usage
-
-The value is a **serialized Lexical editor state** (a JSON string). Pass the last `onChange` value back as `value` to restore content.
-
-```tsx
-import { useState } from "react";
-import { InputLexical } from "@matthiaskrijgsman/mat-ui";
-
-function Editor() {
-  const [value, setValue] = useState<string>();
-
-  return (
-    <InputLexical
-      label={"Description"}
-      placeholder={"Write something…"}
-      toolbar={"floating"}     // or "static" (default)
-      value={value}
-      onChange={setValue}
-      autogrow                 // grow with content…
-      minRows={4}              // …from a 4-row floor…
-      maxRows={12}             // …up to 12 rows, then scroll
-    />
-  );
-}
-```
-
-Sizing mirrors `InputTextArea`: `minRows` sets a height floor, `maxRows` caps the height (content beyond it scrolls), and `autogrow` lets the editor grow with its content between the two. Without `autogrow` the editor is fixed at `minRows`.
-
-### Extending the toolbar
-
-The toolbar is assembled from exported **building blocks**, so you can reorder, drop, or add controls via the `renderToolbar` slot. It receives `{ editor, state, tone }` and renders into whichever variant is active — the same render function drives both the static and floating bars.
-
-```tsx
-import {
-  InputLexical,
-  LexicalBlockTypeSelect,
-  LexicalFormatButtons,
-  LexicalListButtons,
-  LexicalLinkButton,
-  LexicalHistoryButtons,
-  LexicalToolbarDivider,
-} from "@matthiaskrijgsman/mat-ui";
-
-<InputLexical
-  renderToolbar={() => (
-    <>
-      <LexicalFormatButtons/>
-      <LexicalToolbarDivider/>
-      <LexicalListButtons/>
-      <LexicalLinkButton/>
-      <LexicalToolbarDivider/>
-      <LexicalHistoryButtons/>
-    </>
-  )}
-/>;
-```
-
-Building blocks read the active editor and formatting `state`/`tone` from context, so they work in either variant with no extra wiring. Dividers automatically flip orientation (and the whole toolbar collapses overflowing controls into a vertical `⋮` dropdown) when space runs out — return each control as a top-level child so it stays individually measurable.
-
-#### Custom controls
-
-Build your own control with `LexicalToolbarButton` plus Lexical's editor context. `useLexicalToolbar()` exposes the current `{ state, tone }`:
-
-```tsx
-import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";
-import { FORMAT_TEXT_COMMAND } from "lexical";
-import { IconStrikethrough } from "@tabler/icons-react";
-import { LexicalToolbarButton, useLexicalToolbar } from "@matthiaskrijgsman/mat-ui";
-
-const StrikethroughButton = () => {
-  const [editor] = useLexicalComposerContext();
-  const { tone } = useLexicalToolbar();
-  return (
-    <LexicalToolbarButton
-      Icon={IconStrikethrough}
-      tone={tone}
-      aria-label={"Strikethrough"}
-      onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "strikethrough")}
-    />
-  );
-};
-```
-
-#### Registering extra Lexical nodes
-
-The built-in set covers headings, lists, links, and quotes. For anything else (tables, mentions, code blocks, …) install the node's package yourself and pass the node via the `nodes` prop — it is registered alongside the built-in set:
-
-```bash
-pnpm add @lexical/code
-```
-
-```tsx
-import { CodeNode } from "@lexical/code";
-
-<InputLexical nodes={[CodeNode]} renderToolbar={/* … */} />;
-```
-
-> mat-ui does not bundle `lexical` or any `@lexical/*` package — they are peer dependencies, so a single shared copy is used. Only register a given node type once: don't pass a node that is already in the built-in set, or Lexical throws a duplicate-type error.
-
-#### Adding plugins (the `children` slot)
-
-A Lexical feature is usually a **node *plus* a plugin**. Register the node with `nodes`, then mount the plugin(s) as **children** — they run inside the editor alongside the built-ins (history, lists, links). Any `@lexical/react` plugin or your own works:
-
-```tsx
-import { TabIndentationPlugin } from "@lexical/react/LexicalTabIndentationPlugin";
-import { CodeHighlightPlugin } from "@lexical/react/LexicalCodeHighlightPlugin";
-
-<InputLexical nodes={[CodeNode]}>
-  <CodeHighlightPlugin />
-  <TabIndentationPlugin />
-  {/* …or your own plugin using useLexicalComposerContext() */}
-</InputLexical>;
-```
-
-Style custom nodes by merging theme classes over the defaults with the `theme` prop:
-
-```tsx
-<InputLexical nodes={[CodeNode]} theme={{ code: "my-code-block" }}>
-  <CodeHighlightPlugin />
-</InputLexical>;
-```
-
 ## Dark Theme
 
 mat-ui ships with built-in dark theme support. Add the `dark` class to the `<html>` element to activate it:
@@ -205,44 +70,140 @@ document.documentElement.classList.toggle('dark', prefersDark);
 
 All components adapt automatically — no additional props or configuration needed.
 
-## CSS Design Tokens
-
-mat-ui uses CSS custom properties (design tokens) for all component colors. These are defined on `:root` for light mode and overridden under `.dark` for dark mode. You can customize the look of any component by overriding these tokens in your own CSS.
+## Theming with design tokens
 
-### Overriding tokens
-
-Define your overrides after importing the mat-ui stylesheet:
+Every visual property in mat-ui — color, shape, type, elevation and size — is driven by CSS custom properties (design tokens) defined on `:root`. There is no Tailwind config to fork and no component props to thread: you retheme the whole kit by overriding tokens in your own CSS, after importing the stylesheet.
 
 ```css
 @import "@matthiaskrijgsman/mat-ui/style";
 
 :root {
-  /* Change the primary button to your brand color */
-  --color-button-primary-bg: #0ea5e9;
-  --color-button-primary-border: #0ea5e9;
-  --color-button-primary-bg-active: #0284c7;
-  --color-button-primary-border-active: #0284c7;
+  --color-button-primary-bg: #0ea5e9;   /* brand color */
+  --border-radius-input: 0px;            /* square corners everywhere */
+  --font-weight-button: 700;             /* bolder buttons */
 }
+```
+
+### How the tokens are organised
+
+Tokens fall into three families:
 
-/* Override dark theme values too */
-.dark {
-  --color-button-primary-bg: #38bdf8;
-  --color-button-primary-border: #38bdf8;
-  --color-button-primary-bg-active: #0ea5e9;
-  --color-button-primary-border-active: #0ea5e9;
+- **Structure** — typography (family, weight, size), border radius, border width, shadow, ring (focus/hover) width and transition timing. Theme-independent.
+- **Sizing** — the shared `sm | md | lg` control scale (height, padding, gap, icon size).
+- **Color** — every surface, border, text and state color. Defined on `:root` (light) and overridden under `.dark`.
+
+**Structure** and **color** tokens use a two-tier model:
+
+1. **Base scales** — a small set of primitives (e.g. `--font-weight-strong`, `--radius-xl`). Change one to shift the whole kit at once.
+2. **Semantic aliases** — per-component tokens that point at the base scale by default (e.g. `--font-weight-button: var(--font-weight-strong)`, `--border-radius-dropdown: var(--radius-xl)`). Override one to retheme a single component without touching anything else.
+
+So `--font-weight-strong: 700` makes every emphasised element heavier, while `--font-weight-button: 700` changes only buttons. Pick the tier that matches how broad your change is.
+
+> Dark mode: add the `dark` class to `<html>` (see [Dark Theme](#dark-theme)). Only **color** tokens differ between themes — structure and sizing are shared, so you never duplicate them under `.dark`.
+
+### Worked examples
+
+Square, flat, heavier — in four tokens:
+
+```css
+:root {
+  --border-radius-input: 0px;       /* inputs, selects, buttons */
+  --border-radius-panel: 0.25rem;   /* panels, modals */
+  --border-width-input: 2px;        /* all control & surface borders */
+  --font-weight-strong: 700;        /* buttons, badges, tabs, dropdown items… */
 }
 ```
 
-### Token reference
+Set the kit's typeface in one place:
 
-#### General
-
-| Token | Description | Light default |
-|-------|-------------|---------------|
-| `--color-input-focus-ring` | Focus ring color for buttons and inputs | `rgb(17 24 39 / 0.15)` |
-| `--border-radius-input` | Border radius for inputs and selects | `var(--radius-xl)` |
+```css
+:root {
+  --font-family-base: "Inter", system-ui, sans-serif;
+}
+```
 
-#### Control sizing
+---
+
+## Token reference
+
+### Structure — typography
+
+Font weights resolve through a three-step base scale; the semantic tokens below point at it by default.
+
+| Base token | Default |
+|------------|---------|
+| `--font-weight-normal` | `400` |
+| `--font-weight-medium` | `500` |
+| `--font-weight-strong` | `600` |
+
+| Semantic token | Applies to | Default |
+|----------------|-----------|---------|
+| `--font-weight-input-text` | Text typed into inputs, selects, textareas | `--font-weight-normal` |
+| `--font-weight-button` | `Button`, `ButtonIconSquare`, `ButtonIconRound`, file-input action text | `--font-weight-strong` |
+| `--font-weight-badge` | `Badge` | `--font-weight-strong` |
+| `--font-weight-tab` | `TabButtons` | `--font-weight-strong` |
+| `--font-weight-input-label` | `InputLabel` (label above inputs) | `--font-weight-medium` |
+| `--font-weight-input-description` | `InputDescription` | `--font-weight-medium` |
+| `--font-weight-input-error` | `InputError` | `--font-weight-medium` |
+| `--font-weight-input-option-label` | Inline labels on `InputCheck` / `InputRadio` / `InputToggle`, file tile names | `--font-weight-medium` |
+| `--font-weight-dropdown-item` | `DropdownButton`, `PanelLink` | `--font-weight-strong` |
+| `--font-weight-group-header` | Dropdown group labels, select group headers | `--font-weight-strong` |
+| `--font-weight-panel-field` | `PanelField` label | `--font-weight-medium` |
+| `--font-weight-panel-link` | `PanelLink` | `--font-weight-strong` |
+| `--font-weight-table-header` | `Table` header cells, `TableEmpty` title | `--font-weight-medium` |
+| `--font-weight-table-cell` | `Table` body cells | `--font-weight-normal` |
+
+| Token | Description | Default |
+|-------|-------------|---------|
+| `--font-family-base` | Typeface for all kit text (defaults to the host font) | `inherit` |
+| `--font-size-label` | Dropdown / select group label size | `var(--text-sm)` |
+| `--font-size-description` | `InputDescription` and `PanelField` label size | `var(--text-sm)` |
+| `--font-size-error` | `InputError` size | `var(--text-sm)` |
+
+> The text size of the input/button itself comes from the **control sizing** scale below (`--control-size-{size}-font-size`), not from these tokens.
+
+### Structure — border radius
+
+Semantic radius tokens map onto Tailwind's radius scale. Override a token to change one group; override the underlying `--radius-*` to change several at once.
+
+| Token | Applies to | Default |
+|-------|-----------|---------|
+| `--border-radius-input` | Text inputs, selects, textareas, file inputs, the Lexical editor box | `var(--radius-xl)` |
+| `--border-radius-button` | `Button`, `ButtonIconSquare` (and the file-input "Choose" button) | `var(--border-radius-input)` |
+| `--border-radius-panel` | `Panel`, `PanelStack`, `Modal`, `TableEmpty` icon frame | `var(--radius-2xl)` |
+| `--border-radius-dropdown` | `DropdownPanel`, Lexical floating toolbar | `var(--radius-xl)` |
+| `--border-radius-option` | Select option rows | `var(--radius-xl)` |
+| `--border-radius-menu-item` | `DropdownButton`, `PanelLink`, Lexical toolbar buttons | `var(--radius-lg)` |
+| `--border-radius-badge` | `Badge` | `var(--radius-lg)` |
+| `--border-radius-tab` | `TabButtons` container and pills | `var(--radius-xl)` |
+| `--border-radius-checkbox` | `InputCheck` box | `var(--radius-lg)` |
+| `--border-radius-control-inner` | Color swatch and picker bars in `InputColor` | `var(--radius-md)` |
+
+> `ButtonIconRound`, the toggle track/thumb, and radio dots are intentionally fully round (`rounded-full`) and are not tokenized.
+
+### Structure — border width & shadow
+
+| Token | Applies to | Default |
+|-------|-----------|---------|
+| `--border-width-input` | Border width of inputs, selects, buttons, panels, dropdowns, modals, check/radio | `1px` |
+| `--shadow-control` | Resting elevation of buttons, inputs, panels, tabs | `var(--shadow-sm)` |
+| `--shadow-dropdown` | `DropdownPanel` and the Lexical floating toolbar | `var(--shadow-lg)` |
+| `--shadow-overlay` | `Modal` and `SidebarModal` | `var(--shadow-xl)` |
+
+### Structure — ring & transition
+
+Controls share a consistent interaction model: a focus/hover "glow" ring, a thinner inset ring on press, and a single transition duration. The ring **color** comes from the per-component `--color-*-ring` tokens (see the color sections); these set its **width** and the animation timing.
+
+| Token | Applies to | Default |
+|-------|-----------|---------|
+| `--control-ring-width` | Ring width on hover, focus, focus-within, and the select/dropzone open state | `4px` |
+| `--control-ring-width-active` | Ring width on press (`:active`) | `1px` |
+| `--control-transition-duration` | Duration of hover/focus/press transitions on buttons, inputs, selects, the icon-button press scale, etc. | `150ms` |
+| `--control-transition-duration-fast` | Quicker color-only transitions (table row/header hover, clickable `Badge`) | `100ms` |
+
+> The resting state is always ringless (`ring-0`) and a few elements opt out of a focus ring entirely (dropdown items, tabs) — these are intentional and not tokenized.
+
+### Control sizing
 
 `Button`, `ButtonIconSquare`, `ButtonIconRound`, `Input`, `InputColor`, `InputTextArea`, `InputSelectNative`, `InputSelect`, `InputSelectSearchable`, and `InputSelectSearchableAsync` accept a `size?: 'sm' | 'md' | 'lg'` prop (default `'md'`) and read their dimensions from a single shared scale. Override these to adjust heights, padding, font size, and icon sizing consistently across all controls. Replace `{size}` with `sm`, `md`, or `lg`.
 
@@ -255,7 +216,13 @@ Define your overrides after importing the mat-ui stylesheet:
 | `--control-size-{size}-icon` | Icon glyph size inside controls | `1rem` · `1.25rem` · `1.5rem` |
 | `--control-size-{size}-icon-offset` | Distance from the input edge to a leading icon (used when an `Icon` prop is set on `Input`) | `1rem` · `1rem` · `1.25rem` |
 
-#### Buttons
+### Color — focus ring
+
+| Token | Description | Light default |
+|-------|-------------|---------------|
+| `--color-input-focus-ring` | Focus ring color for buttons and inputs | `rgb(17 24 39 / 0.15)` |
+
+### Color — buttons
 
 Each button variant (`primary`, `white`, `black`, `transparent`, `secondary`, `tertiary`) uses the same set of tokens. Replace `{variant}` with the variant name.
 
@@ -273,7 +240,7 @@ Each button variant (`primary`, `white`, `black`, `transparent`, `secondary`, `t
 | `--color-button-{variant}-border-disabled` | Border when disabled |
 | `--color-button-{variant}-text-disabled` | Text color when disabled |
 
-#### Inputs
+### Color — inputs
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
@@ -286,7 +253,7 @@ Each button variant (`primary`, `white`, `black`, `transparent`, `secondary`, `t
 | `--color-input-ring-error` | Ring color in error state | `rgb(220 38 38 / 0.2)` |
 | `--color-input-icon` | Leading icon color | `rgb(17 24 39 / 0.6)` |
 
-#### Input labels, descriptions & errors
+### Color — input labels, descriptions & errors
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
@@ -294,16 +261,16 @@ Each button variant (`primary`, `white`, `black`, `transparent`, `secondary`, `t
 | `--color-input-description-text` | Description text color | `#6b7280` |
 | `--color-input-error-text` | Error message text color | `#dc2626` |
 
-#### Input icon buttons
+### Color — input icon buttons
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
 | `--color-input-icon-button-ring` | Ring color for icon buttons inside inputs | `#e5e7eb` |
 | `--color-input-icon-button-icon` | Icon color for icon buttons inside inputs | `#6b7280` |
 
-#### File inputs
+### Color — file inputs
 
-`InputFileSingle` and `UploadFileTile` are composed from existing primitives (input tokens, `Button` for the inset "Choose" button, `ButtonIconSquare` for the remove (X) button) — no dedicated tokens of their own. `InputFileMultiple` adds:
+`InputFileSingle` and `UploadFileTile` are composed from existing primitives (input tokens, `Button` for the inset "Choose" button, `ButtonIconSquare` for the remove (X) button) — no dedicated color tokens of their own. `InputFileMultiple` adds:
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
@@ -311,11 +278,11 @@ Each button variant (`primary`, `white`, `black`, `transparent`, `secondary`, `t
 
 All three components also rely on the shared `--color-status-success` / `--color-status-error` tokens for the green check / red error icons in their upload-state slots.
 
-#### Color input
+### Color — color input
 
 `InputColor` reuses the standard input tokens — the color swatch in the field and the outline of the picker's saturation/value plane both derive from `--color-input-border`, and the field itself uses the same `--color-input-*` tokens as `Input`. The picker's hue/brightness gradients and indicator rings are intrinsic to the color-picking UI (not theme-based) and are intentionally not tokenized.
 
-#### Select options
+### Color — select options
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
@@ -327,7 +294,7 @@ All three components also rely on the shared `--color-status-success` / `--color
 | `--color-option-text-disabled` | Disabled option text color | `#9ca3af` |
 | `--color-input-select-placeholder` | Select placeholder text color | `#6b7280` |
 
-#### Select search bar
+### Color — select search bar
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
@@ -335,7 +302,7 @@ All three components also rely on the shared `--color-status-success` / `--color
 | `--color-select-search-bg` | Search input background | `rgb(255 255 255 / 0.5)` |
 | `--color-select-search-icon` | Search icon color | `#6b7280` |
 
-#### Toggle
+### Color — toggle
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
@@ -345,14 +312,15 @@ All three components also rely on the shared `--color-status-success` / `--color
 | `--color-toggle-track-off-border` | Track border when off | `#d1d5db` |
 | `--color-toggle-thumb-bg` | Thumb background | `#ffffff` |
 
-#### Checkbox & Radio
+### Color — checkbox & radio
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
 | `--color-check-border` | Checkbox/radio border | `#d1d5db` |
 | `--color-check-ring` | Checkbox/radio focus ring | `rgb(17 24 39 / 0.1)` |
+| `--color-check-checked-bg` | Checkbox/radio fill when checked | `#2563eb` |
 
-#### Dropdown menu
+### Color — dropdown menu
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
@@ -364,7 +332,7 @@ All three components also rely on the shared `--color-status-success` / `--color
 | `--color-dropdown-item-ring` | Item focus ring | `rgb(17 24 39 / 0.1)` |
 | `--color-dropdown-group-label` | Group label text color | `#6b7280` |
 
-#### Tab buttons
+### Color — tab buttons
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
@@ -375,7 +343,7 @@ All three components also rely on the shared `--color-status-success` / `--color
 | `--color-tab-active-bg` | Active tab background | `#ffffff` |
 | `--color-tab-active-border` | Active tab border | `#e5e7eb` |
 
-#### Panel
+### Color — panel
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
@@ -383,14 +351,14 @@ All three components also rely on the shared `--color-status-success` / `--color
 | `--color-panel-border` | Panel border | `#e5e7eb` |
 | `--color-panel-text` | Panel default text color (inherited by `PanelField`) | `#111827` |
 
-#### Modal & Sidebar modal
+### Color — modal & sidebar modal
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
 | `--color-modal-overlay` | Backdrop overlay color | `rgb(156 163 175 / 0.3)` |
 | `--color-modal-bg` | Modal content background | `#ffffff` |
 
-#### Table
+### Color — table
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
@@ -406,13 +374,13 @@ All three components also rely on the shared `--color-status-success` / `--color
 | `--color-table-resize-handle-hover` | Resize handle on hover | `#d1d5db` |
 | `--color-table-resize-handle-active` | Resize handle while dragging | `#2563eb` |
 
-#### Divider
+### Color — divider
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
 | `--color-divider` | Divider line color | `#e5e7eb` |
 
-#### Badge
+### Color — badge
 
 | Token | Description | Light default |
 |-------|-------------|---------------|
@@ -425,7 +393,7 @@ All three components also rely on the shared `--color-status-success` / `--color
 
 > Colored badges (red, blue, green, etc.) use Tailwind color utility classes and are not token-based. They adapt to dark mode automatically via Tailwind's `dark:` variants.
 
-#### Status
+### Color — status
 
 Shared color tokens for status/notification indicators. Currently used by `PanelLink`'s `status` prop, but available for any component.
 
@@ -435,3 +403,139 @@ Shared color tokens for status/notification indicators. Currently used by `Panel
 | `--color-status-warning` | Warning state | `#f59e0b` |
 | `--color-status-success` | Success state | `#16a34a` |
 | `--color-status-info` | Informational state | `#2563eb` |
+
+## Rich text editor (`InputLexical`)
+
+`InputLexical` is a [Lexical](https://lexical.dev)-powered rich text editor styled like the rest of the kit. It ships with two toolbar variants that share the exact same controls:
+
+- **`static`** (default) — a light toolbar fixed at the top of the editor.
+- **`floating`** — a dark bar that appears above the editor while it is focused, matching the editor width.
+
+Lexical and its plugins are **peer dependencies** — install them alongside the library:
+
+```bash
+pnpm add lexical @lexical/react @lexical/rich-text @lexical/list @lexical/link @lexical/selection @lexical/utils
+```
+
+### Basic usage
+
+The value is a **serialized Lexical editor state** (a JSON string). Pass the last `onChange` value back as `value` to restore content.
+
+```tsx
+import { useState } from "react";
+import { InputLexical } from "@matthiaskrijgsman/mat-ui";
+
+function Editor() {
+  const [value, setValue] = useState<string>();
+
+  return (
+    <InputLexical
+      label={"Description"}
+      placeholder={"Write something…"}
+      toolbar={"floating"}     // or "static" (default)
+      value={value}
+      onChange={setValue}
+      autogrow                 // grow with content…
+      minRows={4}              // …from a 4-row floor…
+      maxRows={12}             // …up to 12 rows, then scroll
+    />
+  );
+}
+```
+
+Sizing mirrors `InputTextArea`: `minRows` sets a height floor, `maxRows` caps the height (content beyond it scrolls), and `autogrow` lets the editor grow with its content between the two. Without `autogrow` the editor is fixed at `minRows`.
+
+### Extending the toolbar
+
+The toolbar is assembled from exported **building blocks**, so you can reorder, drop, or add controls via the `renderToolbar` slot. It receives `{ editor, state, tone }` and renders into whichever variant is active — the same render function drives both the static and floating bars.
+
+```tsx
+import {
+  InputLexical,
+  LexicalBlockTypeSelect,
+  LexicalFormatButtons,
+  LexicalListButtons,
+  LexicalLinkButton,
+  LexicalHistoryButtons,
+  LexicalToolbarDivider,
+} from "@matthiaskrijgsman/mat-ui";
+
+<InputLexical
+  renderToolbar={() => (
+    <>
+      <LexicalFormatButtons/>
+      <LexicalToolbarDivider/>
+      <LexicalListButtons/>
+      <LexicalLinkButton/>
+      <LexicalToolbarDivider/>
+      <LexicalHistoryButtons/>
+    </>
+  )}
+/>;
+```
+
+Building blocks read the active editor and formatting `state`/`tone` from context, so they work in either variant with no extra wiring. Dividers automatically flip orientation (and the whole toolbar collapses overflowing controls into a vertical `⋮` dropdown) when space runs out — return each control as a top-level child so it stays individually measurable.
+
+#### Custom controls
+
+Build your own control with `LexicalToolbarButton` plus Lexical's editor context. `useLexicalToolbar()` exposes the current `{ state, tone }`:
+
+```tsx
+import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";
+import { FORMAT_TEXT_COMMAND } from "lexical";
+import { IconStrikethrough } from "@tabler/icons-react";
+import { LexicalToolbarButton, useLexicalToolbar } from "@matthiaskrijgsman/mat-ui";
+
+const StrikethroughButton = () => {
+  const [editor] = useLexicalComposerContext();
+  const { tone } = useLexicalToolbar();
+  return (
+    <LexicalToolbarButton
+      Icon={IconStrikethrough}
+      tone={tone}
+      aria-label={"Strikethrough"}
+      onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "strikethrough")}
+    />
+  );
+};
+```
+
+#### Registering extra Lexical nodes
+
+The built-in set covers headings, lists, links, and quotes. For anything else (tables, mentions, code blocks, …) install the node's package yourself and pass the node via the `nodes` prop — it is registered alongside the built-in set:
+
+```bash
+pnpm add @lexical/code
+```
+
+```tsx
+import { CodeNode } from "@lexical/code";
+
+<InputLexical nodes={[CodeNode]} renderToolbar={/* … */} />;
+```
+
+> mat-ui does not bundle `lexical` or any `@lexical/*` package — they are peer dependencies, so a single shared copy is used. Only register a given node type once: don't pass a node that is already in the built-in set, or Lexical throws a duplicate-type error.
+
+#### Adding plugins (the `children` slot)
+
+A Lexical feature is usually a **node *plus* a plugin**. Register the node with `nodes`, then mount the plugin(s) as **children** — they run inside the editor alongside the built-ins (history, lists, links). Any `@lexical/react` plugin or your own works:
+
+```tsx
+import { TabIndentationPlugin } from "@lexical/react/LexicalTabIndentationPlugin";
+import { CodeHighlightPlugin } from "@lexical/react/LexicalCodeHighlightPlugin";
+
+<InputLexical nodes={[CodeNode]}>
+  <CodeHighlightPlugin />
+  <TabIndentationPlugin />
+  {/* …or your own plugin using useLexicalComposerContext() */}
+</InputLexical>;
+```
+
+Style custom nodes by merging theme classes over the defaults with the `theme` prop:
+
+```tsx
+<InputLexical nodes={[CodeNode]} theme={{ code: "my-code-block" }}>
+  <CodeHighlightPlugin />
+</InputLexical>;
+```
+

package/dist/index.d.ts

@@ -60,6 +60,7 @@ export { DropdownButton } from "./components/dropdown-menu/DropdownButton.tsx";
 export { DropdownButtonGroup } from "./components/dropdown-menu/DropdownButtonGroup.tsx";
 export { DropdownPanel } from "./components/dropdown-menu/DropdownPanel.tsx";
 export { DropdownMenu } from "./components/dropdown-menu/DropdownMenu.tsx";
+export { useDropdownDismiss, DropdownDismissContext } from "./components/dropdown-menu/use-dropdown-dismiss.ts";
 export { usePopover } from "./popover/use-popover.tsx";
 export { useSelectPopover } from "./popover/use-select-popover.tsx";
 export { PopoverBase } from "./popover/PopoverBase.tsx";