@microsoft/fabric-slicers 0.0.0-stage → 3.1.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/CHANGELOG +32 -0
- package/LICENSE +21 -0
- package/README.md +183 -2
- package/dist/index.d.ts +80 -0
- package/dist/index.js +1465 -0
- package/package.json +29 -3
package/CHANGELOG
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `@microsoft/fabric-slicers` will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## 3.1.0 - 2026-10-09
|
|
9
|
+
|
|
10
|
+
- Use shared slicers for DataGrid column filtering
|
|
11
|
+
- [Slicer] Interaction manager integration for List and drop down slicer
|
|
12
|
+
- Improve list slicer keyboard navigation and Range Home/End behavior
|
|
13
|
+
- Support external selections in list and dropdown slicers
|
|
14
|
+
- [Slicer] Preserve formatting when editing range inputs
|
|
15
|
+
- Use integer steps for whole-number range slicers
|
|
16
|
+
- [Slicer] Adding fade for list slicer
|
|
17
|
+
- Support host-managed selection and embedded RangeSlicer controls
|
|
18
|
+
- Fix RangeSlicer Home key at fractional minimums
|
|
19
|
+
- [Slicer] Editing clear button for range slicer
|
|
20
|
+
- Rename fabric slicers to Microsoft scope
|
|
21
|
+
- Add range slicer interaction events
|
|
22
|
+
- [Slicer] List slicer search bar focus bug fix
|
|
23
|
+
- [Slicers] Add the Dropdown slicer
|
|
24
|
+
- Add dynamic range slicer bins and automatic steps
|
|
25
|
+
- Add basic histogram to numeric range slicers
|
|
26
|
+
- [Slicers] Bug fix for clear button causing layout shift
|
|
27
|
+
- [Slicers 2/2] Add editable range inputs
|
|
28
|
+
- [Slicers] List slicer implementation
|
|
29
|
+
- [Slicers 1/2] Add a data-backed range slider
|
|
30
|
+
- Slicers adding basic contracts and skeleton implementation
|
|
31
|
+
- Scaffold ListSlicer package
|
|
32
|
+
- Set the Slicers package version to 1.0.0 for release.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
Copyright (c) Microsoft Corporation.
|
|
2
|
+
|
|
3
|
+
MIT License
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,184 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @microsoft/fabric-slicers
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
React slicer components for Fabric Apps - Analytics.
|
|
4
|
+
|
|
5
|
+
## Quick Reference
|
|
6
|
+
|
|
7
|
+
> **Use when**: You need categorical selection or a numeric range control.
|
|
8
|
+
> **Components**: `ListSlicer`, `DropdownSlicer`, `RangeSlicer`.
|
|
9
|
+
> **Selection**: Starts with all values or the full range selected unless supplied by the host. All slicers accept `selection` to restore or synchronize local state and emit interaction events for host-managed filtering.
|
|
10
|
+
> **Peer dependencies**: React 18 or 19, React DOM, and `@griffel/react`.
|
|
11
|
+
|
|
12
|
+
## Installation
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install @microsoft/fabric-slicers @microsoft/fabric-visuals-core @griffel/react
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Public API
|
|
19
|
+
|
|
20
|
+
Import components and types from `@microsoft/fabric-slicers`. All three components share these props:
|
|
21
|
+
|
|
22
|
+
| Prop | Type | Required | Description |
|
|
23
|
+
|------|------|----------|-------------|
|
|
24
|
+
| `data` | `DataTable \| readonly SlicerValue[]` | yes | A table or flat collection of values. |
|
|
25
|
+
| `column` | `string` | yes | Table column to display; also the fallback title for flat data. |
|
|
26
|
+
| `title` | `string` | no | Overrides the column's display name or name. |
|
|
27
|
+
| `theme` | `VisualTheme` | no | Color, typography, and border overrides. Defaults to shared design tokens. |
|
|
28
|
+
| `displayOptions` | `SlicerDisplayOptions` | no | Shared `hideHeader` and `frameless` options, extended by each slicer. |
|
|
29
|
+
| `selection` | Component-specific | no | Restore or synchronize host-provided selection. See [External selections](#external-selections). |
|
|
30
|
+
| `onInteraction` | `InteractionEventCallback` | no | Selection and clear events for host-managed filtering. |
|
|
31
|
+
|
|
32
|
+
`DataTable`, `VisualTheme`, and `InteractionEventCallback` come from `@microsoft/fabric-visuals-core`.
|
|
33
|
+
`SlicerValue` supports strings, finite numbers, booleans, valid dates, `null`, and `undefined`.
|
|
34
|
+
`isSlicerValue` validates untyped data cells or interaction values against that contract.
|
|
35
|
+
Table column formats apply to displayed values.
|
|
36
|
+
|
|
37
|
+
## List slicer
|
|
38
|
+
|
|
39
|
+
`ListSlicer` displays unique values with search, checkboxes, and scrolling.
|
|
40
|
+
Select all applies to search matches; Clear restores every value.
|
|
41
|
+
Provide a bounded container to control its size.
|
|
42
|
+
The search focus ring surrounds the entire search field, including its icon, in both list and dropdown slicers.
|
|
43
|
+
|
|
44
|
+
```tsx
|
|
45
|
+
import { ListSlicer } from '@microsoft/fabric-slicers';
|
|
46
|
+
import type { DataTable } from '@microsoft/fabric-visuals-core';
|
|
47
|
+
|
|
48
|
+
const data: DataTable = {
|
|
49
|
+
columns: [{ name: 'genre', displayName: 'Genre' }],
|
|
50
|
+
rows: [['Action'], ['Adventure'], ['Role-playing']],
|
|
51
|
+
};
|
|
52
|
+
|
|
53
|
+
<div style={{ width: 300, height: 320 }}>
|
|
54
|
+
<ListSlicer data={data} column="genre" />
|
|
55
|
+
</div>;
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Props type: `ListSlicerInputParams`. Its optional `displayOptions` uses `ListSlicerDisplayOptions`:
|
|
59
|
+
|
|
60
|
+
| Option | Default | Description |
|
|
61
|
+
|--------|---------|-------------|
|
|
62
|
+
| `showSearch` | `true` | Show the search input. |
|
|
63
|
+
| `hideHeader` | `false` | Hide the title and Clear button when the host supplies its own header. |
|
|
64
|
+
| `frameless` | `false` | Remove the body's border, background, and padding when embedded in a host surface. |
|
|
65
|
+
|
|
66
|
+
### Host-owned list filtering
|
|
67
|
+
|
|
68
|
+
Embed `ListSlicer` with `selection` and `onInteraction` when the host owns filtering.
|
|
69
|
+
Use `displayOptions: { hideHeader: true, frameless: true }` when the host provides the surrounding
|
|
70
|
+
surface and Clear action, as DataGrid does. Raw values are retained internally for selection and
|
|
71
|
+
interaction events; formatted labels are presentation-only.
|
|
72
|
+
|
|
73
|
+
### Keyboard navigation
|
|
74
|
+
|
|
75
|
+
Select all and the matching values share one Tab stop, separate from Search.
|
|
76
|
+
Initial entry focuses Select all. Tab and Shift+Tab leave the checkboxes; returning
|
|
77
|
+
restores the last focused checkbox, falling back to Select all if that value is no longer present.
|
|
78
|
+
The same navigation works in the dropdown's shared selection list.
|
|
79
|
+
|
|
80
|
+
| Key | Action |
|
|
81
|
+
|-----|--------|
|
|
82
|
+
| Up / Down arrow | Move between Select all and the matching values without changing selection. Stops at either end. |
|
|
83
|
+
| Home / End | Focus Select all / the last matching value, including values outside the rendered virtual window. |
|
|
84
|
+
| Space / Enter | Toggle the focused value or Select all. |
|
|
85
|
+
|
|
86
|
+
Unmodified arrows and Home/End provide navigation based on the [documented Power BI slicer shortcuts](https://learn.microsoft.com/en-us/power-bi/create-reports/desktop-accessibility-keyboard-shortcuts#slicer).
|
|
87
|
+
Shift+Arrow range selection is intentionally unsupported to keep keyboard handling simple;
|
|
88
|
+
use Space or Enter to toggle individual values. Modified navigation keys are left to the browser.
|
|
89
|
+
The shared Tab stop and inclusion of Select all are explicit interaction choices here, not specified by that documentation.
|
|
90
|
+
Search retains normal text-editing keys, and Escape still closes an open dropdown and returns focus to its trigger.
|
|
91
|
+
|
|
92
|
+
## Dropdown slicer
|
|
93
|
+
|
|
94
|
+
`DropdownSlicer` opens a searchable selection list from a compact summary button.
|
|
95
|
+
It shows All, None, up to two selected labels, or a count such as "4 of 5".
|
|
96
|
+
Selection persists when closed; search resets on reopening.
|
|
97
|
+
|
|
98
|
+
```tsx
|
|
99
|
+
import { DropdownSlicer } from '@microsoft/fabric-slicers';
|
|
100
|
+
|
|
101
|
+
<DropdownSlicer
|
|
102
|
+
data={['North', 'South', 'East', 'West']}
|
|
103
|
+
column="region"
|
|
104
|
+
title="Region"
|
|
105
|
+
displayOptions={{ showSearch: false }}
|
|
106
|
+
/>;
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Props type: `DropdownSlicerInputParams`. It accepts the same `selection` and `displayOptions` as List slicer.
|
|
110
|
+
|
|
111
|
+
## Range slicer
|
|
112
|
+
|
|
113
|
+
`RangeSlicer` provides a histogram, two-handle slider, and editable minimum/maximum inputs.
|
|
114
|
+
Only finite numbers define the range. Clear restores the full range and clears input errors.
|
|
115
|
+
|
|
116
|
+
```tsx
|
|
117
|
+
import { RangeSlicer } from '@microsoft/fabric-slicers';
|
|
118
|
+
|
|
119
|
+
<RangeSlicer
|
|
120
|
+
data={[96400, 155825, 428650, 1284900]}
|
|
121
|
+
column="revenue"
|
|
122
|
+
title="Revenue"
|
|
123
|
+
displayOptions={{ showHistogram: false }}
|
|
124
|
+
/>;
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Props type: `RangeSlicerInputParams`. Additional options:
|
|
128
|
+
|
|
129
|
+
| Prop | Default | Description |
|
|
130
|
+
|------|---------|-------------|
|
|
131
|
+
| `displayOptions.showHistogram` | `true` | Show the value distribution above the slider. |
|
|
132
|
+
| `displayOptions.hideHeader` | `false` | Hide the title and Clear button when the host supplies its own header. The range retains its accessible name. |
|
|
133
|
+
| `displayOptions.frameless` | `false` | Remove the body's border, background, and padding when embedded in a host surface. Input borders remain visible. |
|
|
134
|
+
| `step` | Automatic | Positive slider increment; does not restrict typed values. |
|
|
135
|
+
| `disabled` | `false` | Disable interaction. |
|
|
136
|
+
|
|
137
|
+
Home/End changes only the focused handle and keeps focus there, with either automatic or explicit steps:
|
|
138
|
+
the minimum handle moves to the domain minimum / current maximum, and the maximum handle moves to
|
|
139
|
+
the current minimum / domain maximum. Handles can meet without crossing; typed off-step bounds remain exact.
|
|
140
|
+
|
|
141
|
+
## External selections
|
|
142
|
+
|
|
143
|
+
All slicers accept an optional `selection` prop to restore a saved selection or synchronize it while mounted.
|
|
144
|
+
Omit it to manage selection locally (initially all values or the full range).
|
|
145
|
+
Supply `null` to reset to all values or the full range, including newly arriving data.
|
|
146
|
+
Host updates do not emit interaction events. Local selection controls and Clear continue to work;
|
|
147
|
+
the next supplied selection update replaces that local state.
|
|
148
|
+
Keep selection arrays immutable and retain their reference on unrelated rerenders to preserve local edits.
|
|
149
|
+
|
|
150
|
+
| Component | Selection type | Meaning |
|
|
151
|
+
|-----------|----------------|---------|
|
|
152
|
+
| `ListSlicer`, `DropdownSlicer` | `readonly SlicerValue[] \| null` | Raw selected values. `[]` selects none. |
|
|
153
|
+
| `RangeSlicer` | `SlicerRange \| null` | Inclusive `[minimum, maximum]` bounds. Infinities leave that side unbounded. |
|
|
154
|
+
|
|
155
|
+
```tsx
|
|
156
|
+
<ListSlicer data={['Action', 'Adventure', 'Role-playing']} column="genre" selection={['Action', 'Adventure']} />;
|
|
157
|
+
<DropdownSlicer data={['North', 'South', 'East', 'West']} column="region" selection={['North']} />;
|
|
158
|
+
<RangeSlicer data={[0, 20, 80, 100]} column="revenue" selection={[20, Infinity]} />;
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### Interactions
|
|
162
|
+
|
|
163
|
+
Optional `onInteraction` uses `InteractionEventCallback` from `@microsoft/fabric-visuals-core`.
|
|
164
|
+
List and Dropdown slicers emit one `select` event per checkbox or search-scoped Select all change,
|
|
165
|
+
with a `set` predicate containing `column` as its name and the complete raw selected values.
|
|
166
|
+
An empty array selects nothing. Selecting all values or clearing emits `[{ action: 'clear' }]`.
|
|
167
|
+
|
|
168
|
+
Range slicers emit `select` on drag release, keyboard changes, or valid input commits (Enter/blur).
|
|
169
|
+
Unchanged, invalid, or cancelled edits do not emit.
|
|
170
|
+
|
|
171
|
+
Range selections contain one inclusive `range` predicate using `column` and raw numeric bounds.
|
|
172
|
+
Domain endpoints emit `min: -Infinity` or `max: Infinity` to leave that side unbounded.
|
|
173
|
+
Encode infinities explicitly when serializing; `JSON.stringify` converts them to `null`.
|
|
174
|
+
|
|
175
|
+
Clear or returning to the full range emits `[{ action: 'clear' }]`.
|
|
176
|
+
|
|
177
|
+
## Theming
|
|
178
|
+
|
|
179
|
+
Without `theme`, slicers use shared design tokens and host token overrides.
|
|
180
|
+
Pass a `VisualTheme` to override colors and typography without resetting selection.
|
|
181
|
+
|
|
182
|
+
## Development
|
|
183
|
+
|
|
184
|
+
See [DEV_README.md](./DEV_README.md) for build, lint, and test commands.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import { ReactElement } from 'react';
|
|
2
|
+
import { DataTable, VisualTheme, InteractionEventCallback } from '@microsoft/fabric-visuals-core';
|
|
3
|
+
|
|
4
|
+
/** Supported raw slicer values. Null and undefined share one blank entry in list and dropdown slicers. */
|
|
5
|
+
type SlicerValue = string | number | boolean | Date | null | undefined;
|
|
6
|
+
/** Display options shared by all slicers. */
|
|
7
|
+
interface SlicerDisplayOptions {
|
|
8
|
+
/** Hide the title and Clear button. Defaults to false. */
|
|
9
|
+
hideHeader?: boolean;
|
|
10
|
+
/** Remove the body frame and padding when the host provides the surrounding surface. Defaults to false. */
|
|
11
|
+
frameless?: boolean;
|
|
12
|
+
}
|
|
13
|
+
/** Shared inputs for all slicers. Without a host selection, slicers start with all values selected. */
|
|
14
|
+
interface SlicerInputParams {
|
|
15
|
+
/** Structured tabular data or a flat collection of slicer values. */
|
|
16
|
+
data: DataTable | readonly SlicerValue[];
|
|
17
|
+
/** Optional theme overrides. Defaults to shared design tokens. */
|
|
18
|
+
theme?: VisualTheme;
|
|
19
|
+
/** Name of the DataTable column represented by the slicer and used in emitted interaction events. */
|
|
20
|
+
column: string;
|
|
21
|
+
/** Visible title. Defaults to the DataTable column display name, then column. */
|
|
22
|
+
title?: string;
|
|
23
|
+
displayOptions?: SlicerDisplayOptions;
|
|
24
|
+
/** Callback for slicer selection and clear interaction events. */
|
|
25
|
+
onInteraction?: InteractionEventCallback;
|
|
26
|
+
}
|
|
27
|
+
/** Display options shared by the list and dropdown selection panels. */
|
|
28
|
+
interface ListSlicerDisplayOptions extends SlicerDisplayOptions {
|
|
29
|
+
/** Show the search input. Defaults to true. */
|
|
30
|
+
showSearch?: boolean;
|
|
31
|
+
}
|
|
32
|
+
/** Inputs for the list slicer. */
|
|
33
|
+
interface ListSlicerInputParams extends SlicerInputParams {
|
|
34
|
+
displayOptions?: ListSlicerDisplayOptions;
|
|
35
|
+
/**
|
|
36
|
+
* Raw selected values to restore or synchronize without emitting events.
|
|
37
|
+
* Null resets to all, including future values. An empty array selects none.
|
|
38
|
+
* Omitted leaves selection locally managed; supplying values does not disable local edits.
|
|
39
|
+
*/
|
|
40
|
+
selection?: readonly SlicerValue[] | null;
|
|
41
|
+
}
|
|
42
|
+
/** Inputs for the dropdown slicer. */
|
|
43
|
+
interface DropdownSlicerInputParams extends ListSlicerInputParams {
|
|
44
|
+
}
|
|
45
|
+
/** Lower and upper bounds, inclusive. */
|
|
46
|
+
type SlicerRange = [number, number];
|
|
47
|
+
/** Display options for the numeric range slicer. */
|
|
48
|
+
interface RangeSlicerDisplayOptions extends SlicerDisplayOptions {
|
|
49
|
+
/** Show the value distribution above the slider. Defaults to true; false also skips histogram computation. */
|
|
50
|
+
showHistogram?: boolean;
|
|
51
|
+
/** Positive safe integer overriding the histogram bin count. Omitted or invalid values use automatic binning. */
|
|
52
|
+
binCount?: number;
|
|
53
|
+
}
|
|
54
|
+
/** Numeric range slicer. Keep column fixed; data may refresh when the host supplies selection. */
|
|
55
|
+
interface RangeSlicerInputParams extends SlicerInputParams {
|
|
56
|
+
displayOptions?: RangeSlicerDisplayOptions;
|
|
57
|
+
/**
|
|
58
|
+
* Host filter bounds to restore or synchronize without emitting events.
|
|
59
|
+
* Bounds may be infinite or outside the current data domain; only their displayed values are clamped.
|
|
60
|
+
* Null resets to the full range. Omitted leaves selection locally managed.
|
|
61
|
+
*/
|
|
62
|
+
selection?: SlicerRange | null;
|
|
63
|
+
/**
|
|
64
|
+
* Finite positive keyboard and pointer increment. Omitted or invalid values use precision- and formatter-aware automatic steps,
|
|
65
|
+
* restricted to whole-number increments when all finite data values are integers. Typed values are not restricted by the step.
|
|
66
|
+
*/
|
|
67
|
+
step?: number;
|
|
68
|
+
disabled?: boolean;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
declare function ListSlicer(props: ListSlicerInputParams): ReactElement;
|
|
72
|
+
|
|
73
|
+
declare function DropdownSlicer(props: DropdownSlicerInputParams): ReactElement;
|
|
74
|
+
|
|
75
|
+
declare function RangeSlicer({ data, column, title, theme, step, disabled, displayOptions, onInteraction, selection, }: RangeSlicerInputParams): ReactElement;
|
|
76
|
+
|
|
77
|
+
/** Narrows unvalidated data cells and interaction values to supported slicer values. */
|
|
78
|
+
declare function isSlicerValue(value: DataTable['rows'][number][number]): value is SlicerValue;
|
|
79
|
+
|
|
80
|
+
export { DropdownSlicer, type DropdownSlicerInputParams, ListSlicer, type ListSlicerDisplayOptions, type ListSlicerInputParams, RangeSlicer, type RangeSlicerDisplayOptions, type RangeSlicerInputParams, type SlicerDisplayOptions, type SlicerInputParams, type SlicerRange, type SlicerValue, isSlicerValue };
|