Merge origin/main

Author: RezoR0xFF

docs/guide/layout.md

@@ -167,7 +167,7 @@ ui.row({ gap: 1 }, [
 
 Rezi clips rendering to each widget’s allocated rect. Overflow is handled per-widget:
 
-- `ui.text` supports `textOverflow: "clip" | "ellipsis"` (and `maxWidth`)
+- `ui.text` supports `textOverflow: "clip" | "ellipsis" | "middle"` (and `maxWidth`)
 - Containers clip their children to the padded/bordered content area
 
 Example: ellipsis truncation

docs/recipes/data-table.md

@@ -89,7 +89,7 @@ await app.start();
 ## Explanation
 
 - Filter state is kept in `state.filter` and applied before passing data to the table.
-- Sorting is handled by the table (it emits `onSort(column, direction)` and you store that in state).
+- Sorting is handled by the table (click a sortable header, or focus the header and press Enter; it emits `onSort(column, direction)` and you store that in state).
 - Selection is stored as row keys and updated via `onSelectionChange`.
 
 ## Related

docs/widgets/dropdown.md

@@ -23,11 +23,11 @@ ui.dropdown({
 ## Behavior
 
 - **Arrow keys** navigate items. **Enter** selects the highlighted item.
+- The current selection is visually highlighted.
 - **Mouse click** on an item selects it and fires the `onSelect` callback.
-- **Clicking outside** the dropdown closes it (via the layer backdrop).
+- **Clicking outside** the dropdown closes it (calls `onClose`).
 
 ## Notes
 
 - Use `anchorId` to position the dropdown relative to an element in the layout tree.
 - Render dropdowns inside `ui.layers(...)` so they stack above base UI.
-

docs/widgets/file-tree-explorer.md

@@ -36,6 +36,11 @@ ui.fileTreeExplorer({
 | `onContextMenu` | `(node) => void` | - | Context menu callback |
 | `renderNode` | `(node, depth, state) => VNode` | - | Custom renderer |
 
+## Behavior
+
+- **Arrow keys** navigate. **Enter** activates the focused node.
+- **Right click** on a node calls `onContextMenu(node)` when provided.
+
 ## Notes
 
 - `FileNode` includes `name`, `path`, `type`, and optional `children` and `status`.

docs/widgets/layer.md

@@ -18,7 +18,7 @@ ui.layer({
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `id` | `string` | **required** | Layer identifier |
-| `zIndex` | `number` | insertion order | Higher values render on top |
+| `zIndex` | `number` | insertion order | Higher values render on top (clamped for deterministic ordering) |
 | `backdrop` | `"none" \| "dim" \| "opaque"` | `"none"` | Backdrop behind the layer |
 | `modal` | `boolean` | `false` | Block input to lower layers |
 | `closeOnEscape` | `boolean` | `true` | Close on Escape key |
@@ -33,7 +33,9 @@ ui.layer({
 ## Notes
 
 - Use [`Layers`](layers.md) to manage stacking order and modals.
+- `zIndex` is truncated to an integer and clamped to the safe range (`±9,007,199,253`) so very large values don't break ordering.
 - `BackdropStyle` values: `"none"`, `"dim"`, `"opaque"`.
+- Backdrops are rendered behind the layer. `"dim"` uses a light shade pattern; `"opaque"` clears the area behind the layer to the theme background color.
 
 ## Related
 

docs/widgets/layers.md

@@ -17,6 +17,7 @@ ui.layers([
 - Child order defines z-order: later children render on top.
 - Use [`Layer`](layer.md) for explicit z-index or custom backdrops.
 - Layers enable deterministic hit testing and focus management across overlaps.
+- Backdrops (from [`Modal`](modal.md) and [`Layer`](layer.md)) render behind the active overlay(s) and stack in draw order.
 
 ## Related
 

docs/widgets/modal.md

@@ -29,7 +29,7 @@ ui.layers([
 | `title` | `string` | - | Optional modal header title |
 | `content` | `VNode` | **required** | Main modal body |
 | `actions` | `VNode[]` | `[]` | Action row (typically buttons) |
-| `width` | `number \| "auto"` | `"auto"` | Preferred modal width |
+| `width` | `number \| "auto"` | `~70%` | Preferred modal width |
 | `maxWidth` | `number` | - | Maximum width constraint |
 | `backdrop` | `"none" \| "dim" \| "opaque"` | `"dim"` | Backdrop style |
 | `closeOnBackdrop` | `boolean` | `true` | Close when clicking backdrop |
@@ -67,6 +67,8 @@ ui.modal({
 
 - Modals are rendered by conditionally including them in the tree (there is no `open` prop).
 - Render modals inside `ui.layers(...)` so they stack above base content.
+- Backdrops are rendered behind the modal. `"dim"` uses a light shade pattern; `"opaque"` clears the area behind the modal to the theme background color.
+- `width: "auto"` sizes to content/actions and is clamped by `maxWidth` and the viewport.
 
 ## Related
 

docs/widgets/panel-group.md

@@ -9,7 +9,6 @@ ui.panelGroup(
   {
     id: "panel-group",
     direction: "horizontal",
-    autoSaveId: "main-layout",
   },
   [
     ui.resizablePanel({ defaultSize: 25 }, [Sidebar()]),
@@ -24,12 +23,11 @@ ui.panelGroup(
 |------|------|---------|-------------|
 | `id` | `string` | **required** | Group identifier |
 | `direction` | `"horizontal" \| "vertical"` | **required** | Layout direction |
-| `autoSaveId` | `string` | - | App-level key for persisting layout (core does not persist) |
 
 ## Notes
 
-- `PanelGroup` distributes space evenly when sizes are not provided.
-- `ResizablePanel` size hints are preserved but not applied by core layout.
+- `PanelGroup` distributes space based on `ResizablePanel` size hints (with equal distribution when unspecified).
+- `ResizablePanel` size hints are interpreted as percentages of the group's width/height (based on `direction`).
 - Use [`SplitPane`](split-pane.md) for draggable resizing.
 
 ## Related

docs/widgets/resizable-panel.md

@@ -18,13 +18,13 @@ ui.panelGroup(
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `defaultSize` | `number` | auto | Initial size (percent or cells, based on parent) |
-| `minSize` | `number` | - | Minimum size |
-| `maxSize` | `number` | - | Maximum size |
+| `defaultSize` | `number` | auto | Initial size (percentage of the parent axis) |
+| `minSize` | `number` | - | Minimum size (percentage) |
+| `maxSize` | `number` | - | Maximum size (percentage) |
 | `collapsible` | `boolean` | `false` | Allow collapsing the panel |
 
 ## Notes
 
 - `ResizablePanel` should contain exactly one child widget.
-- `PanelGroup` distributes space evenly; size hints on `ResizablePanel` are preserved as metadata but not applied by core layout.
+- `PanelGroup` uses `defaultSize`/`minSize`/`maxSize` as sizing hints along its primary axis.
 - For draggable sizing, use [`SplitPane`](split-pane.md).

docs/widgets/split-pane.md

@@ -44,6 +44,16 @@ Dividers between panels can be dragged with the mouse to resize:
 
 The hit area for dividers extends 1 cell on each side of the divider for easier grabbing.
 
+### Collapse
+
+When `collapsible: true`:
+
+- A panel index in `collapsed` is laid out at its minimum size (`minSizes[index]` or `0`).
+- **Double-click** near a divider to toggle collapse:
+  - Click just to the **left/top** of a divider to target the panel on that side
+  - Click just to the **right/bottom** of a divider to target the other panel
+- Use `onCollapse(index, collapsed)` to update your `collapsed` list (controlled state).
+
 ## Notes
 
 - `sizes` length should match the number of child panels.