@rcarls/rc-splitter 0.3.2 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -61
- package/dist/custom-elements.json +255 -27
- package/dist/{rc-splitter-BZgnDbmR.js → rc-splitter-CJTLxYi3.js} +265 -130
- package/dist/rc-splitter-CJTLxYi3.js.map +1 -0
- package/dist/rc-splitter-define.js +1 -1
- package/dist/rc-splitter.js +1 -1
- package/dist/types/packages/rc-splitter/src/rc-splitter.d.ts +68 -13
- package/package.json +1 -1
- package/dist/rc-splitter-BZgnDbmR.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# `@rcarls/rc-splitter`
|
|
2
2
|
|
|
3
|
-
Resizable pane splitter with pointer, keyboard, and collapse/restore controls
|
|
3
|
+
Resizable pane splitter with pointer, keyboard, and collapse/restore controls that follows the
|
|
4
|
+
[WAI-ARIA Window Splitter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/).
|
|
4
5
|
|
|
5
6
|
Docs: [https://richardcarls.github.io/rc-webcomponents/components/rc-splitter](https://richardcarls.github.io/rc-webcomponents/components/rc-splitter).
|
|
6
7
|
|
|
@@ -15,20 +16,21 @@ npm install @rcarls/rc-splitter
|
|
|
15
16
|
## Import
|
|
16
17
|
|
|
17
18
|
```js
|
|
18
|
-
import '@rcarls/rc-splitter';
|
|
19
|
-
import { RCSplitter } from '@rcarls/rc-splitter';
|
|
19
|
+
import '@rcarls/rc-splitter'; // side-effect: registers <rc-splitter>
|
|
20
|
+
import { RCSplitter } from '@rcarls/rc-splitter'; // named class export
|
|
20
21
|
```
|
|
21
22
|
|
|
22
23
|
---
|
|
23
24
|
|
|
24
25
|
## Basic usage
|
|
25
26
|
|
|
26
|
-
Place the primary pane in the default slot and the secondary pane in the `secondary` slot. The
|
|
27
|
+
Place the primary pane in the default slot and the secondary pane in the `secondary` slot. The
|
|
28
|
+
splitter takes up all available space in its container.
|
|
27
29
|
|
|
28
30
|
```html
|
|
29
31
|
<rc-splitter style="width: 100%; height: 400px;">
|
|
30
|
-
<div>Primary pane
|
|
31
|
-
<div slot="secondary">Secondary pane
|
|
32
|
+
<div>Primary pane; resizes when you drag the separator</div>
|
|
33
|
+
<div slot="secondary">Secondary pane; fills remaining space</div>
|
|
32
34
|
</rc-splitter>
|
|
33
35
|
```
|
|
34
36
|
|
|
@@ -47,72 +49,111 @@ Vertical orientation:
|
|
|
47
49
|
|
|
48
50
|
### Properties / attributes
|
|
49
51
|
|
|
50
|
-
| Property
|
|
51
|
-
|
|
52
|
-
| `label`
|
|
53
|
-
| `orientation`
|
|
54
|
-
| `mode`
|
|
55
|
-
| `step`
|
|
56
|
-
| `
|
|
57
|
-
| `
|
|
52
|
+
| Property | Attribute | Type | Default | Description |
|
|
53
|
+
| --------------- | ---------------- | ---------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
54
|
+
| `label` | `label` | `string` | `'Splitter'` | Accessible label applied to the primary pane and used by the separator handle via `aria-labelledby`. |
|
|
55
|
+
| `orientation` | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction. `horizontal` = left/right panes; `vertical` = top/bottom panes. Reflects to attribute. |
|
|
56
|
+
| `mode` | `mode` | `'length' \| 'percent' \| 'fixed'` | `'length'` | Unit and sizing behavior for `value`. `length` = pixels of the primary pane; `percent` = percentage of total container size; `fixed` = clampable px primary pane while the secondary pane flexes. |
|
|
57
|
+
| `step` | `step` | `number` | `1` | Keyboard step size in the current unit (px or %). Shift multiplies by 10×. |
|
|
58
|
+
| `min` | `min` | `number` | `0` | Minimum primary pane size in the current mode's units. |
|
|
59
|
+
| `max` | `max` | `number \| undefined` | `undefined` | Maximum primary pane size in the current mode's units. Defaults to the full container size. |
|
|
60
|
+
| `value` | `value` | `number` | `0` | Current primary pane size. Host writes update the separator position silently (no `rc-splitter-change`). |
|
|
61
|
+
| `defaultValue` | `default-value` | `number \| undefined` | `undefined` | Initial uncontrolled primary pane size, applied once the splitter has measured its container. |
|
|
62
|
+
| `fixed` | `fixed` | `boolean` | `false` | Disable resizing. This legacy boolean locks interaction and is distinct from `mode="fixed"`. |
|
|
63
|
+
| `collapsible` | `collapsible` | `boolean` | `false` | Render the separator's collapse/restore button and enable swipe collapse/restore. |
|
|
64
|
+
| `snapPoints` | `snap-points` | `string` | `''` | Ascending whitespace-separated anchors in the current mode's units. |
|
|
65
|
+
| `swipeVelocity` | `swipe-velocity` | `number` | `500` | Release velocity in px/s that selects the next anchor or collapse action. |
|
|
66
|
+
|
|
67
|
+
### Anchored settling
|
|
68
|
+
|
|
69
|
+
With `snap-points`, a slow release settles to the nearest anchor and a qualified
|
|
70
|
+
swipe settles to the next anchor in its direction. Without snap points, pointer
|
|
71
|
+
resizing remains continuous. A collapsible splitter can still swipe toward the
|
|
72
|
+
primary minimum to collapse and swipe back to restore its pre-collapse value.
|
|
58
73
|
|
|
59
|
-
|
|
74
|
+
```html
|
|
75
|
+
<rc-splitter mode="percent" snap-points="25 50 75" value="50">
|
|
76
|
+
<section>Primary</section>
|
|
77
|
+
<section slot="secondary">Secondary</section>
|
|
78
|
+
</rc-splitter>
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Call `snapTo(index, behavior?)` to select an anchor programmatically. `behavior`
|
|
82
|
+
is `'animated'` by default and also accepts `'instant'`.
|
|
60
83
|
|
|
61
|
-
|
|
62
|
-
|---|---|---|
|
|
63
|
-
| `--rc-splitter-separator-size` | `6px` | Thickness of the separator bar |
|
|
64
|
-
| `--rc-splitter-separator-handle-size` | `100%` | Length of the drag handle within the separator (set to a smaller value to create a centred grab handle) |
|
|
65
|
-
| `--rc-splitter-separator-color` | `ButtonFace` | Background color of the separator bar |
|
|
66
|
-
| `--rc-splitter-separator-border-inline-start` | `1px solid ButtonBorder` | Inline-start (left in LTR) border of the separator |
|
|
67
|
-
| `--rc-splitter-separator-border-inline-end` | `1px solid ButtonBorder` | Inline-end (right in LTR) border of the separator |
|
|
68
|
-
| `--rc-splitter-separator-border-block-start` | `1px solid ButtonBorder` | Block-start (top) border when `orientation="vertical"` |
|
|
69
|
-
| `--rc-splitter-separator-border-block-end` | `1px solid ButtonBorder` | Block-end (bottom) border when `orientation="vertical"` |
|
|
84
|
+
### CSS custom properties
|
|
70
85
|
|
|
71
|
-
|
|
86
|
+
| Property | Default | Description |
|
|
87
|
+
| --------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
88
|
+
| `--rc-splitter-separator-size` | `6px` | Thickness of the separator bar |
|
|
89
|
+
| `--rc-splitter-separator-handle-size` | `100%` | Length of the drag handle within the separator (set to a smaller value to create a centered grab handle) |
|
|
90
|
+
| `--rc-splitter-separator-color` | `color-mix(in srgb, ButtonBorder 35%, Canvas 65%)` | Background color of the separator bar |
|
|
91
|
+
| `--rc-splitter-keyline` | `1px solid ButtonBorder` | Shared fallback for the four separator border custom properties below |
|
|
92
|
+
| `--rc-splitter-handle-color` | `ButtonBorder` | Color of the dot grip indicators (default visual) |
|
|
93
|
+
| `--rc-splitter-handle-thickness` | `4px` | Cross-axis size of the visual indicator (dot column width or pill/line thickness) |
|
|
94
|
+
| `--rc-splitter-handle-border-radius` | `0` | Border-radius of the visual indicator; set to a large value (999px, for example) for a pill shape |
|
|
95
|
+
| `--rc-splitter-handle-pattern` | 3-dot radial-gradient | `background-image` for the visual indicator; set to `none` to use a solid fill via `--rc-splitter-handle-fill` instead |
|
|
96
|
+
| `--rc-splitter-handle-fill` | `transparent` | `background-color` of the visual indicator; effective when `--rc-splitter-handle-pattern` is `none` |
|
|
97
|
+
| `--rc-splitter-handle-hover-fill` | `transparent` | `background-color` of the visual indicator on hover; scoped to the indicator only, not the full strip |
|
|
98
|
+
| `--rc-splitter-handle-transition` | `0ms` | CSS transition duration/easing for the visual indicator's background-color changes |
|
|
99
|
+
| `--rc-splitter-snap-duration` | `200ms` | Duration of anchored settling; reduced motion makes it immediate |
|
|
100
|
+
| `--rc-splitter-collapse-button-size` | `20px` | Diameter of the collapse/expand toggle button |
|
|
101
|
+
| `--rc-splitter-collapse-button-offset` | `8px` | Distance from the start edge of the separator to the collapse button center |
|
|
102
|
+
| `--rc-splitter-collapse-button-bg` | `Canvas` | Collapse button background color |
|
|
103
|
+
| `--rc-splitter-collapse-button-hover-bg` | `ButtonFace` | Collapse button background color on hover |
|
|
104
|
+
| `--rc-splitter-collapse-button-border` | `ButtonBorder` | Collapse button border color |
|
|
105
|
+
| `--rc-splitter-collapse-button-color` | `ButtonText` | Collapse button icon color |
|
|
106
|
+
| `--rc-splitter-separator-border-inline-start` | `var(--rc-splitter-keyline)` | Inline-start (left in LTR) border of the separator |
|
|
107
|
+
| `--rc-splitter-separator-border-inline-end` | `var(--rc-splitter-keyline)` | Inline-end (right in LTR) border of the separator |
|
|
108
|
+
| `--rc-splitter-separator-border-block-start` | `var(--rc-splitter-keyline)` | Block-start (top) border when `orientation="vertical"` |
|
|
109
|
+
| `--rc-splitter-separator-border-block-end` | `var(--rc-splitter-keyline)` | Block-end (bottom) border when `orientation="vertical"` |
|
|
110
|
+
|
|
111
|
+
All color defaults use CSS system color keywords, adapting automatically to the user's color
|
|
112
|
+
scheme and forced-color modes.
|
|
72
113
|
|
|
73
114
|
### CSS parts
|
|
74
115
|
|
|
75
|
-
| Part
|
|
76
|
-
|
|
77
|
-
| `primary`
|
|
78
|
-
| `secondary`
|
|
79
|
-
| `separator`
|
|
116
|
+
| Part | Element | Description |
|
|
117
|
+
| ------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
118
|
+
| `primary` | `div#primary` | Primary pane container |
|
|
119
|
+
| `secondary` | `aside#secondary` | Secondary pane container |
|
|
120
|
+
| `separator` | `div#separator` | The separator bar |
|
|
80
121
|
| `separator-handle` | `div[role="separator"]` inside separator | The focusable drag handle (narrower than the bar if `--rc-splitter-separator-handle-size` is set) |
|
|
122
|
+
| `collapse-button` | `button` | The collapse/expand toggle button (only rendered when `collapsible` is set) |
|
|
81
123
|
|
|
82
124
|
### Slots
|
|
83
125
|
|
|
84
|
-
| Slot
|
|
85
|
-
|
|
86
|
-
|
|
|
87
|
-
| `secondary` | Secondary pane. Fills remaining space via `flex: 1`.
|
|
126
|
+
| Slot | Description |
|
|
127
|
+
| ----------- | ----------------------------------------------------------------------------------- |
|
|
128
|
+
| _(default)_ | Primary pane. Its inline-size (or block-size when vertical) is set by the splitter. |
|
|
129
|
+
| `secondary` | Secondary pane. Fills remaining space via `flex: 1`. |
|
|
88
130
|
|
|
89
131
|
### Events
|
|
90
132
|
|
|
91
|
-
| Event
|
|
92
|
-
|
|
93
|
-
| `rc-splitter-change` | Yes (composed) | No
|
|
133
|
+
| Event | Bubbles | Cancelable | Detail | When |
|
|
134
|
+
| -------------------- | -------------- | ---------- | -------------------------------------- | --------------------------------------------------------------- |
|
|
135
|
+
| `rc-splitter-change` | Yes (composed) | No | `{ value: number, valueText: string }` | Separator position changes (on every pointer move or key press) |
|
|
94
136
|
|
|
95
137
|
### Read-only getters
|
|
96
138
|
|
|
97
139
|
```ts
|
|
98
|
-
|
|
99
|
-
valueText: string // Human-readable value string (e.g. "240px" or "40%")
|
|
140
|
+
valueText: string; // Human-readable value string, for example "240px" or "40%"
|
|
100
141
|
```
|
|
101
142
|
|
|
102
143
|
---
|
|
103
144
|
|
|
104
|
-
## Keyboard
|
|
145
|
+
## Keyboard behavior
|
|
105
146
|
|
|
106
147
|
Focus the separator handle (click or Tab), then:
|
|
107
148
|
|
|
108
|
-
| Key
|
|
109
|
-
|
|
110
|
-
| `ArrowRight` / `ArrowDown` | Increase primary pane by `step` (horizontal: right; vertical: down)
|
|
111
|
-
| `ArrowLeft` / `ArrowUp`
|
|
112
|
-
| `Shift` + Arrow
|
|
113
|
-
| `Home`
|
|
114
|
-
| `End`
|
|
115
|
-
| `Enter`
|
|
149
|
+
| Key | Action |
|
|
150
|
+
| -------------------------- | ---------------------------------------------------------------------- |
|
|
151
|
+
| `ArrowRight` / `ArrowDown` | Increase primary pane by `step` (horizontal: right; vertical: down) |
|
|
152
|
+
| `ArrowLeft` / `ArrowUp` | Decrease primary pane by `step` |
|
|
153
|
+
| `Shift` + Arrow | Multiply step by 10× |
|
|
154
|
+
| `Home` | Jump to the effective minimum (`min`, default `0`) |
|
|
155
|
+
| `End` | Jump to the effective maximum (`max`, default the full container size) |
|
|
156
|
+
| `Enter` | Toggle between the effective minimum and the last non-collapsed size |
|
|
116
157
|
|
|
117
158
|
---
|
|
118
159
|
|
|
@@ -120,18 +161,18 @@ Focus the separator handle (click or Tab), then:
|
|
|
120
161
|
|
|
121
162
|
The separator handle implements the WAI-ARIA slider role pattern:
|
|
122
163
|
|
|
123
|
-
| Attribute
|
|
124
|
-
|
|
125
|
-
| `role="separator"` | Separator handle `div` |
|
|
126
|
-
| `aria-label`
|
|
127
|
-
| `aria-orientation` | Separator handle
|
|
128
|
-
| `aria-valuenow`
|
|
129
|
-
| `aria-valuemin`
|
|
130
|
-
| `aria-valuemax`
|
|
131
|
-
| `aria-valuetext`
|
|
132
|
-
| `aria-controls`
|
|
133
|
-
| `aria-labelledby`
|
|
134
|
-
| `tabindex="0"`
|
|
164
|
+
| Attribute | Where | Value |
|
|
165
|
+
| ------------------ | ---------------------- | ---------------------------------------------------- |
|
|
166
|
+
| `role="separator"` | Separator handle `div` | None |
|
|
167
|
+
| `aria-label` | Primary pane | Value of `label` property |
|
|
168
|
+
| `aria-orientation` | Separator handle | `"horizontal"` or `"vertical"` |
|
|
169
|
+
| `aria-valuenow` | Separator handle | Current numeric value |
|
|
170
|
+
| `aria-valuemin` | Separator handle | `0` |
|
|
171
|
+
| `aria-valuemax` | Separator handle | Container width or height in current mode units |
|
|
172
|
+
| `aria-valuetext` | Separator handle | Human-readable string, for example `"240px"` |
|
|
173
|
+
| `aria-controls` | Separator handle | `"primary"`, the ID of the primary pane |
|
|
174
|
+
| `aria-labelledby` | Separator handle | `"primary"`, using the primary pane as label context |
|
|
175
|
+
| `tabindex="0"` | Separator handle | Always focusable |
|
|
135
176
|
|
|
136
177
|
---
|
|
137
178
|
|
|
@@ -158,4 +199,5 @@ The separator handle implements the WAI-ARIA slider role pattern:
|
|
|
158
199
|
|
|
159
200
|
## Browser support
|
|
160
201
|
|
|
161
|
-
All modern browsers.
|
|
202
|
+
All modern browsers. It requires Web Components support (Chrome 67+, Firefox 63+, Safari 12.1+)
|
|
203
|
+
and `ResizeObserver` (Chrome 64+, Firefox 69+, Safari 13.1+).
|