@microsoft/fabric-slicers 0.0.0-stage → 3.0.1
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 +10 -0
- package/LICENSE +21 -0
- package/README.md +144 -2
- package/dist/index.d.ts +69 -0
- package/dist/index.js +1296 -0
- package/package.json +29 -3
package/CHANGELOG
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
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.0.1 - 2026-09-08
|
|
9
|
+
|
|
10
|
+
- Add the initial package scaffold.
|
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,145 @@
|
|
|
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. State is local; `RangeSlicer` emits 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 display options, extended by each slicer. |
|
|
29
|
+
| `onInteraction` | `InteractionEventCallback` | no | Selection and clear events. Currently emitted by `RangeSlicer` only. |
|
|
30
|
+
|
|
31
|
+
`DataTable`, `VisualTheme`, and `InteractionEventCallback` come from `@microsoft/fabric-visuals-core`.
|
|
32
|
+
`SlicerValue` supports strings, finite numbers, booleans, valid dates, `null`, and `undefined`.
|
|
33
|
+
Table column formats apply to displayed values.
|
|
34
|
+
|
|
35
|
+
## List slicer
|
|
36
|
+
|
|
37
|
+
`ListSlicer` displays unique values with search, checkboxes, and scrolling.
|
|
38
|
+
Select all applies to search matches; Clear restores every value.
|
|
39
|
+
Provide a bounded container to control its size.
|
|
40
|
+
The search focus ring surrounds the entire search field, including its icon, in both list and dropdown slicers.
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
import { ListSlicer } from '@microsoft/fabric-slicers';
|
|
44
|
+
import type { DataTable } from '@microsoft/fabric-visuals-core';
|
|
45
|
+
|
|
46
|
+
const data: DataTable = {
|
|
47
|
+
columns: [{ name: 'genre', displayName: 'Genre' }],
|
|
48
|
+
rows: [['Action'], ['Adventure'], ['Role-playing']],
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
<div style={{ width: 300, height: 320 }}>
|
|
52
|
+
<ListSlicer data={data} column="genre" />
|
|
53
|
+
</div>;
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Props type: `ListSlicerInputParams`. Its optional `displayOptions` uses `ListSlicerDisplayOptions`:
|
|
57
|
+
|
|
58
|
+
| Option | Default | Description |
|
|
59
|
+
|--------|---------|-------------|
|
|
60
|
+
| `showSearch` | `true` | Show the search input. |
|
|
61
|
+
|
|
62
|
+
## Dropdown slicer
|
|
63
|
+
|
|
64
|
+
`DropdownSlicer` opens a searchable selection list from a compact summary button.
|
|
65
|
+
It shows All, None, up to two selected labels, or a count such as "4 of 5".
|
|
66
|
+
Selection persists when closed; search resets on reopening.
|
|
67
|
+
|
|
68
|
+
```tsx
|
|
69
|
+
import { DropdownSlicer } from '@microsoft/fabric-slicers';
|
|
70
|
+
|
|
71
|
+
<DropdownSlicer
|
|
72
|
+
data={['North', 'South', 'East', 'West']}
|
|
73
|
+
column="region"
|
|
74
|
+
title="Region"
|
|
75
|
+
displayOptions={{ showSearch: false }}
|
|
76
|
+
/>;
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Props type: `DropdownSlicerInputParams`. It accepts the same `displayOptions` as List slicer.
|
|
80
|
+
|
|
81
|
+
## Range slicer
|
|
82
|
+
|
|
83
|
+
`RangeSlicer` provides a histogram, two-handle slider, and editable minimum/maximum inputs.
|
|
84
|
+
Only finite numbers define the range. Clear restores the full range and clears input errors.
|
|
85
|
+
|
|
86
|
+
```tsx
|
|
87
|
+
import { RangeSlicer } from '@microsoft/fabric-slicers';
|
|
88
|
+
|
|
89
|
+
<RangeSlicer
|
|
90
|
+
data={[96400, 155825, 428650, 1284900]}
|
|
91
|
+
column="revenue"
|
|
92
|
+
title="Revenue"
|
|
93
|
+
displayOptions={{ showHistogram: false }}
|
|
94
|
+
/>;
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Props type: `RangeSlicerInputParams`. Additional options:
|
|
98
|
+
|
|
99
|
+
| Prop | Default | Description |
|
|
100
|
+
|------|---------|-------------|
|
|
101
|
+
| `displayOptions.showHistogram` | `true` | Show the value distribution above the slider. |
|
|
102
|
+
| `displayOptions.hideHeader` | `false` | Hide the title and Clear button when the host supplies its own header. The range retains its accessible name. |
|
|
103
|
+
| `displayOptions.frameless` | `false` | Remove the body's border, background, and padding when embedded in a host surface. Input borders remain visible. |
|
|
104
|
+
| `selection` | Local state | Restore or synchronize host-provided inclusive bounds without emitting events. `null` resets the full range; infinities map to domain endpoints. |
|
|
105
|
+
| `step` | Automatic | Positive slider increment; does not restrict typed values. |
|
|
106
|
+
| `disabled` | `false` | Disable interaction. |
|
|
107
|
+
|
|
108
|
+
The histogram uses an automatic data-driven bin count and highlights the selected range.
|
|
109
|
+
Set `displayOptions.binCount` to a positive safe integer to override it; invalid counts use automatic bins.
|
|
110
|
+
Set `showHistogram: false` to hide it and skip bin computation and validation.
|
|
111
|
+
|
|
112
|
+
Set `title` to override the heading or `disabled` to prevent interaction.
|
|
113
|
+
When `step` is omitted or invalid, the slider chooses a precision- and formatter-aware increment;
|
|
114
|
+
an explicit finite positive `step` overrides it.
|
|
115
|
+
Typed values can be any finite number within the current bounds, independent of the slider step.
|
|
116
|
+
|
|
117
|
+
Automatic steps start at `(maximum - minimum) / 100`, round up to a 1, 2, or 5 times a power of ten,
|
|
118
|
+
and increase when neighboring stops have identical formatted labels.
|
|
119
|
+
Slider interaction uses the original domain and native step-based rounding.
|
|
120
|
+
The exact endpoints remain reachable with Home and End even when native step rounding would miss them.
|
|
121
|
+
|
|
122
|
+
### Interactions
|
|
123
|
+
|
|
124
|
+
Optional `onInteraction` uses `InteractionEventCallback` from `@microsoft/fabric-visuals-core`.
|
|
125
|
+
It emits `select` on drag release, keyboard changes, or valid input commits (Enter/blur).
|
|
126
|
+
Unchanged, invalid, or cancelled edits do not emit.
|
|
127
|
+
|
|
128
|
+
Selections contain one inclusive `range` predicate using `column` and raw numeric bounds.
|
|
129
|
+
Domain endpoints emit `min: -Infinity` or `max: Infinity` to leave that side unbounded.
|
|
130
|
+
Encode infinities explicitly when serializing; `JSON.stringify` converts them to `null`.
|
|
131
|
+
|
|
132
|
+
Clear or returning to the full range emits `[{ action: 'clear' }]`.
|
|
133
|
+
Selection stays local unless the host supplies `selection` to restore or synchronize it; the host applies events to other visuals.
|
|
134
|
+
With `selection`, refreshed data clamps the displayed handles to the available domain without changing the host's predicate or emitting events.
|
|
135
|
+
For example, `[20, Infinity]` displays as `[20, 100]` for a `[0, 100]` domain; `null` displays the full domain.
|
|
136
|
+
Otherwise keep `data` and `column` fixed while mounted; remount to change them.
|
|
137
|
+
|
|
138
|
+
## Theming
|
|
139
|
+
|
|
140
|
+
Without `theme`, slicers use shared design tokens and host token overrides.
|
|
141
|
+
Pass a `VisualTheme` to override colors and typography without resetting selection.
|
|
142
|
+
|
|
143
|
+
## Development
|
|
144
|
+
|
|
145
|
+
See [DEV_README.md](./DEV_README.md) for build, lint, and test commands.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import { ReactElement } from 'react';
|
|
2
|
+
import { DataTable, VisualTheme, InteractionEventCallback } from '@microsoft/fabric-visuals-core';
|
|
3
|
+
|
|
4
|
+
/** Supported raw slicer values. */
|
|
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
|
+
}
|
|
11
|
+
/** Shared inputs for all slicers. Every slicer starts with all values selected, with no filter applied. */
|
|
12
|
+
interface SlicerInputParams {
|
|
13
|
+
/** Structured tabular data or a flat collection of slicer values. */
|
|
14
|
+
data: DataTable | readonly SlicerValue[];
|
|
15
|
+
/** Optional theme overrides. Defaults to shared design tokens. */
|
|
16
|
+
theme?: VisualTheme;
|
|
17
|
+
/** Name of the DataTable column represented by the slicer and used in emitted interaction events. */
|
|
18
|
+
column: string;
|
|
19
|
+
/** Visible title. Defaults to the DataTable column display name, then column. */
|
|
20
|
+
title?: string;
|
|
21
|
+
displayOptions?: SlicerDisplayOptions;
|
|
22
|
+
/** Callback for slicer selection and clear interaction events. */
|
|
23
|
+
onInteraction?: InteractionEventCallback;
|
|
24
|
+
}
|
|
25
|
+
/** Display options shared by the list and dropdown selection panels. */
|
|
26
|
+
interface ListSlicerDisplayOptions extends SlicerDisplayOptions {
|
|
27
|
+
/** Show the search input. Defaults to true. */
|
|
28
|
+
showSearch?: boolean;
|
|
29
|
+
}
|
|
30
|
+
/** Inputs for the list slicer. */
|
|
31
|
+
interface ListSlicerInputParams extends SlicerInputParams {
|
|
32
|
+
displayOptions?: ListSlicerDisplayOptions;
|
|
33
|
+
}
|
|
34
|
+
/** Inputs for the dropdown slicer. */
|
|
35
|
+
interface DropdownSlicerInputParams extends SlicerInputParams {
|
|
36
|
+
displayOptions?: ListSlicerDisplayOptions;
|
|
37
|
+
}
|
|
38
|
+
/** Lower and upper bounds, inclusive. */
|
|
39
|
+
type SlicerRange = [number, number];
|
|
40
|
+
/** Display options for the numeric range slicer. */
|
|
41
|
+
interface RangeSlicerDisplayOptions extends SlicerDisplayOptions {
|
|
42
|
+
/** Show the value distribution above the slider. Defaults to true; false also skips histogram computation. */
|
|
43
|
+
showHistogram?: boolean;
|
|
44
|
+
/** Positive safe integer overriding the histogram bin count. Omitted or invalid values use automatic binning. */
|
|
45
|
+
binCount?: number;
|
|
46
|
+
/** Remove the body frame and padding when the host provides the surrounding surface. */
|
|
47
|
+
frameless?: boolean;
|
|
48
|
+
}
|
|
49
|
+
/** Numeric range slicer. Keep column fixed; data may refresh when the host supplies selection. */
|
|
50
|
+
interface RangeSlicerInputParams extends SlicerInputParams {
|
|
51
|
+
displayOptions?: RangeSlicerDisplayOptions;
|
|
52
|
+
/**
|
|
53
|
+
* Host filter bounds to restore or synchronize without emitting events.
|
|
54
|
+
* Bounds may be infinite or outside the current data domain; only their displayed values are clamped.
|
|
55
|
+
* Null resets to the full range. Omitted leaves selection locally managed.
|
|
56
|
+
*/
|
|
57
|
+
selection?: SlicerRange | null;
|
|
58
|
+
/** Finite positive keyboard and pointer increment. Omitted or invalid values use precision- and formatter-aware automatic steps. */
|
|
59
|
+
step?: number;
|
|
60
|
+
disabled?: boolean;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
declare function ListSlicer(props: ListSlicerInputParams): ReactElement;
|
|
64
|
+
|
|
65
|
+
declare function DropdownSlicer(props: DropdownSlicerInputParams): ReactElement;
|
|
66
|
+
|
|
67
|
+
declare function RangeSlicer({ data, column, title, theme, step, disabled, displayOptions, onInteraction, selection, }: RangeSlicerInputParams): ReactElement;
|
|
68
|
+
|
|
69
|
+
export { DropdownSlicer, type DropdownSlicerInputParams, ListSlicer, type ListSlicerDisplayOptions, type ListSlicerInputParams, RangeSlicer, type RangeSlicerDisplayOptions, type RangeSlicerInputParams, type SlicerDisplayOptions, type SlicerInputParams, type SlicerRange, type SlicerValue };
|