@iyulab/components 1.38.0 → 1.40.0

package/skills/iyulab-components/references/components/split-panel.md

@@ -15,7 +15,7 @@ Resizable two-panel layout. Drag the splitter to adjust panel sizes.
 </u-split-panel>
 
 <!-- Vertical split -->
-<u-split-panel orientation="vertical" default-ratio="[30,70]">
+<u-split-panel orientation="vertical" default-ratio="30,70" style="height: 400px;">
   <div>Top panel</div>
   <div>Bottom panel</div>
 </u-split-panel>
@@ -30,6 +30,27 @@ Resizable two-panel layout. Drag the splitter to adjust panel sizes.
 
 ---
 
+## Sizing
+
+**Give the host a height.** This is a shell: `:host` is `height: 100%` with `overflow: hidden`,
+so the panels divide whatever height the host has — and an unconstrained host has none to divide.
+
+```html
+<u-split-panel style="height: 400px">…</u-split-panel>
+```
+
+⚠ Leave the height off — or nest the component in a container that has no height of its own — and
+it collapses to a thin strip (measured: 18px, with 900px-tall panel content), the content is
+clipped by `overflow: hidden`, and there is no scrollbar to reach it. No error, nothing in the
+console. Every example below assumes a height on the host for this reason.
+
+A height-bearing ancestor works the same way (measured):
+
+```css
+.page             { height: 100%; display: flex; flex-direction: column; }
+.page u-split-panel { flex: 1 1 auto; min-height: 0; }
+```
+
 ## Slots
 
 | Name | Description |
@@ -42,7 +63,7 @@ Resizable two-panel layout. Drag the splitter to adjust panel sizes.
 | Property | Type | Default | Reflect | Description |
 |----------|------|---------|---------|-------------|
 | `orientation` | `'horizontal'\|'vertical'` | `'horizontal'` | ✓ | Split direction |
-| `defaultRatio` | `number[]` | `[]` | ✓ | Initial size ratios (e.g. `[30, 70]`) |
+| `defaultRatio` | `number[]` | `[]` | ✓ | Initial size ratios. Attribute form is comma-separated, without brackets: `default-ratio="30,70"`. Ratios are shares of the space between the handles |
 | `ratio` | `number[]` | `[]` | ✓ | Current size ratios |
 | `disabled` | `boolean` | `false` | ✓ | Prevent resizing |
 | `lazy` | `boolean` | `false` | ✓ | Show preview while dragging, commit on release |
@@ -55,11 +76,28 @@ Resizable two-panel layout. Drag the splitter to adjust panel sizes.
 | `shift` | Dragging in progress |
 | `shift-end` | Drag ends |
 
+## Keyboard & Accessibility
+
+Each handle is a focusable `role="separator"` following the WAI-ARIA APG *Window Splitter*
+pattern. Its value is the share of the panel **before** it (`aria-valuenow`, `0` to the combined
+share of the two panels it sits between — `100` with two panels), and it is named by the
+`resizePanels` locale message.
+
+| Key | Effect |
+|-----|--------|
+| `←` / `→` (horizontal) · `↑` / `↓` (vertical) | Shrink / grow the panel before the handle by 5% |
+| `Home` / `End` | Give the panel before the handle its smallest / largest size |
+| `Enter` | Collapse the panel before the handle; press again to restore its previous size |
+
+In a right-to-left layout `←` still moves the handle left. A keyboard change fires `shift-start`,
+`shift` and `shift-end` in turn, so listening to `shift-end` alone covers both pointer and keyboard.
+
 ## CSS Custom Properties
 
 | Property | Description |
 |----------|-------------|
-| `--splitter-size` | Splitter handle thickness |
+| `--splitter-size` | Thickness of the visible line (default `4px`) |
+| `--splitter-hit-size` | Thickness of the area that takes the pointer (default `24px`, WCAG 2.5.8). It occupies layout space between the panels, so it never covers a panel's scrollbar. The handle is the larger of the two; set it to `var(--splitter-size)` for a flush handle |
 | `--splitter-color` | Splitter default color |
 | `--splitter-color-hover` | Splitter color on hover |
 | `--splitter-color-active` | Splitter color while dragging |

package/skills/iyulab-components/references/components/tab-panel.md

@@ -32,6 +32,24 @@ Tab-based content switcher. Pair each `u-tab` with a `u-panel` of the same `valu
 
 ## u-tab-panel
 
+### Sizing
+
+`u-tab-panel` is a flex shell with no height of its own, so it behaves two ways — both intended:
+
+- **No height** — it grows with the active panel's content; nothing is clipped and no scrollbar
+  appears (measured: a 900px panel under a `top` tab bar gives a 935px-tall component — the 34px bar
+  plus the content).
+- **A height, or a height-bearing parent** — the **content area** becomes the scroll region and the
+  tab bar keeps its place (measured: 300px tall → a 265px content area with 635px to scroll).
+
+```html
+<u-tab-panel style="height: 300px">…</u-tab-panel>
+```
+
+The tab bar scrolls on its own axis when the tabs overflow it — horizontally for `placement="top"`
+and `"bottom"`, vertically for `"left"` and `"right"` — so a long tab list never pushes the content
+out of the component.
+
 ### Slots
 
 | Name | Description |

package/skills/iyulab-components/references/utilities/overlay-manager.md

@@ -4,7 +4,20 @@
 import { OverlayManager } from '@iyulab/components';
 ```
 
-Internal static manager for the overlay stack. Used by `UOverlayElement` (`u-dialog`, `u-drawer`) to track open overlays, assign z-index, and manage body scroll locking.
+Internal static manager that **owns the layer scale for every stacking surface**. Used by `UOverlayElement` (`u-dialog`, `u-drawer`) to track open overlays, assign z-index, and manage body scroll locking — and read by `Toast` for the notification layer.
+
+## Layer scale
+
+Stacking is a contract, not a negotiation between components. Two bands exist, and the notification band is **always above** the overlay band:
+
+| Band | Value | Owned by |
+|------|-------|----------|
+| Overlay | `9999 + depth`, capped at `9999 + 1000` | `UOverlayElement` subclasses (`u-dialog`, `u-drawer`, custom overlays) |
+| **Notification** | `OverlayManager.notificationZIndex` | `Toast` |
+
+Overlay z-index comes from **how many overlays are open at once** (stack depth), not from how many have ever been opened. That is what bounds the band — and a bounded band is what lets the notification layer sit above it by construction. More than 1000 simultaneous overlays share the top value: they stop stacking relative to each other, but notifications stay above them.
+
+> **Do not hardcode a z-index for a surface that must appear above overlays.** Read `OverlayManager.notificationZIndex` so the value follows the scale.
 
 > **Note:** You generally do not need to use `OverlayManager` directly. It is called automatically by overlay components. Only use it if you are building a custom overlay component that extends `UOverlayElement`.
 
@@ -12,10 +25,11 @@ Internal static manager for the overlay stack. Used by `UOverlayElement` (`u-dia
 
 | Member | Type / Returns | Description |
 |--------|----------------|-------------|
-| `OverlayManager.add(overlay, lockBody?)` | `void` | Register an overlay; increments z-index; optionally locks body scroll |
+| `OverlayManager.add(overlay, lockBody?)` | `void` | Register an overlay; assigns a z-index from the overlay band by stack depth; optionally locks body scroll |
 | `OverlayManager.remove(overlay, lockBody?)` | `void` | Unregister an overlay; releases scroll lock if no overlays remain |
 | `OverlayManager.isTopmost(overlay)` | `boolean` | Returns `true` if the overlay is the topmost in the stack (used for ESC key handling) |
 | `OverlayManager.size` | `number` | Number of currently open overlays |
+| `OverlayManager.notificationZIndex` | `number` | z-index of the notification layer — guaranteed above the whole overlay band. Use this for toasts, snackbars, and anything else that must remain visible over an open modal |
 | `OverlayManager.trapStack` | `FocusTrap[]` | Shared focus-trap stack (used internally by focus-trap library) |
 
 ## Example (custom overlay)