@scattered-light/loomiere-base-ui 0.6.0 → 0.7.0

package/dist/design-system/components/Splitter/README.md

@@ -0,0 +1,42 @@
+# Splitter
+
+Loomiere component, not part of Base UI. Two or more panels and a handle between them. Not a Base UI part. It follows the window splitter pattern: the handle is a separator you drag or move with the arrow keys. Each panel's size is --sl-splitter-panel-size, so a drag can update the line without rendering the tree again. The parent gives the root its height. One panel has no size and fills what the others leave (the last panel, when every panel has a size). Px and percent mix, so a workstation can pin its sides in pixels while a list keeps a percent. Arrow keys move one key step, 5% of the splitter; Shift uses the larger step. Home and End jump to that panel's min and max. Enter collapses a collapsible panel and restores the size it had. Double-click resets to the default size. In RTL, Left and Right swap. A panel collapsed to nothing is hidden, so its contents leave the tab order. data-orientation is on the root, the panel and the handle. data-dragging is on the root and the handle while the pointer is down. data-collapsed is on a collapsed panel and on the handle that resizes it. data-disabled is on the handle. data-grip draws the grip. data-fill marks the panel that takes the leftover space. The line is one stroke. The part you grab sits on the next panel's inline-start, not centered, so it does not cover the previous panel's scrollbar. A fine pointer gets a11y.min-target (24px). A coarse pointer gets the 44px touch target. The focus ring is drawn on that grab area: a ring around the 1px line reads as a second hairline. Collapse animates with duration.normal. A drag does not animate. Reduced motion is the shared reset, which finishes every transition at once.
+
+Use `Loomiere.Splitter`, this package's component: it puts the class names on for you (`import { Splitter } from '@scattered-light/loomiere-base-ui'`, or from `@scattered-light/loomiere-base-ui/custom`).
+
+Not a Base UI part, so there is no base-ui.com page for it.
+
+## Classes
+
+| Class | Data attributes it answers to |
+|---|---|
+| `Splitter` | `data-orientation`: `horizontal`, `vertical`; `data-dragging` |
+| `SplitterPanel` | `data-orientation`: `horizontal`, `vertical`; `data-fill`; `data-collapsed` |
+| `ScrollAreaScrollbar` |   |
+| `SplitterHandle` | `data-orientation`: `horizontal`, `vertical`; `data-dragging`; `data-collapsed`; `data-grip`; `data-disabled` |
+
+Base UI sets the state attributes (`data-checked`, `data-open`, `data-disabled`...) itself. Set `data-size`, `data-emphasis`, `data-variant` and `data-color` yourself; `data-color` takes any palette name (`primary`, `secondary`, `error`...) and repaints the part in it.
+
+## Example
+
+From the Splitter stories (`Default`):
+
+```tsx
+export const Default: Story = {
+  render: () => (
+    <div style={frame}>
+      <Splitter.Root orientation="horizontal">
+        <Splitter.Panel id="list" defaultSize="35%" minSize="20%" maxSize="60%">
+          <div style={pane}>List</div>
+        </Splitter.Panel>
+        <Splitter.Handle aria-label="Resize list" />
+        <Splitter.Panel id="detail">
+          <div style={pane}>Detail</div>
+        </Splitter.Panel>
+      </Splitter.Root>
+    </div>
+  ),
+};
+```
+
+The preview also shows `Vertical`, `Workstation`, `Nested`.