Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(react-color-picker): updated the spec and the migration #33918

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs(react-color-picker): updated the spec and the migration #33918

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions packages/react-components/react-color-picker-preview/library/docs/MIGRATION.md
View file
Original file line number Diff line number Diff line change
@@ -11,11 +11,11 @@
#### Supported Props
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🕵🏾‍♀️ visual regressions to review in the fluentuiv9 Visual Regression Report

Avatar Converged 2 screenshots
Image Name Diff(in Pixels) Image Type
Avatar Converged.badgeMask.normal.chromium.png 5 Changed
Avatar Converged.badgeMask - RTL.normal.chromium.png 3 Changed


- `color`
- `onChange`

#### Props no longer supported with an equivalent functionality in ColorPicker V9:

- `className` => Slot system supports it by default. We don't need to provide it explicitly.
- `onChange` => Use `onColorChange` instead.
- `styles` => Use style customization through `className` instead.
- `theme`

@@ -43,9 +43,10 @@

#### New props

- `channel`
- `defaultColor`
- `shape`
- `orient`
- `vertical`

#### Props supported

@@ -69,10 +70,9 @@
| v8 `ColorPicker` | v9 `ColorPicker` |
| ---------------- | -------------------------- |
| `value` | `color` |
| `onChange` | `onChange` |
| `onChange` | `onColorChange` |
| `maxValue` | |
| `minValue` | |
| `shape ` | |
| `type` | |
| `isAlpha` | `AlphaSlider` component |
| `overlayColor` | In `AlphaSlider` component |
90 changes: 30 additions & 60 deletions packages/react-components/react-color-picker-preview/library/docs/Spec.md
View file
Original file line number Diff line number Diff line change
@@ -74,24 +74,22 @@ import {
ColorArea,
ColorSliderProps,
AlphaSlider,
HueSlider,
ColorSlider,
ColorPickerOnSelectEventHandler,
} from '@fluentui/react-color-picker-preview';

export const Default = () => {
const [selectedColor, setSelectedColor] = React.useState('rgba(0, 255, 170, 1)');
const handleChange: ColorPickerProps['onChange'] = (_, data) => {
setSelectedColor(data.selectedColorHex);
};
const [selectedColor, setSelectedColor] = React.useState({ h: 109, s: 1, v: 0.9, a: 1 });
const handleChange: ColorPickerProps['onChange'] = (_, data) => setSelectedColor(data.selectedColorHex);

return (
<>
<ColorPicker color={selectedColor} onChange={handleChange}>
<ColorArea />
<AlphaSlider />
<HueSlider />
<ColorSlider />
</ColorPicker>
<div style={{ backgroundColor: `${selectedColor}` }} />
<div style={{ backgroundColor: tinycolor(color).toRgbString() }} />
</>
);
};
@@ -132,51 +130,18 @@ For custom sizes users might want to customize it via CSS.

### ColorPicker

| Property | Values | Default | Purpose |
| ---------- | ------------------- | --------- | -------------------------------------- |
| color | `HSV` | | Sets color value in HSV format |
| onChange | `function` | undefined | Callback called when color is selected |
| shape | `square`, `rounded` | `rounded` | Sets shape |
| step | `number` | 1 | Step for arrow navigation |
| customStep | `number` | 3 | Fast navigation |
Comment on lines -140 to -141
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Those are supported by default. And customStep idea was for faster navigation but because we use native inputs it's supported from the box.

| Property | Values | Default | Purpose |
| ------------- | ------------------- | --------- | -------------------------------------- |
| color | `HSV` | | Sets color value in HSV format |
| onColorChange | `function` | undefined | Callback called when color is selected |
| shape | `square`, `rounded` | `rounded` | Sets shape |

Color has an `HSV` type because the correct functioning of the component requires coordinates. In some parts of the ColorArea, the color is the same, and therefore it should be calculated using coordinates. Color manipulations will be done on the user end in the desired format.

`onChange` event returns data which contains a new color.

Input fields with color values will be in `renderUtils`. It will contain default ColorPicker which has all colors represented and a preview swatch. This functionality is similar to V8.

```tsx
import { ColorPicker } from '@fluentui/react-color-picker-preview';

const COLOR = { h: 0, s: 1, v: 1 };

export const Default = () => {
const [selectedColor, setSelectedColor] = React.useState(COLOR);
const handleChange: ColorPickerOnSelectEventHandler = (_, data) => {
setSelectedColor({ ...data.color, a: data.color.a ?? 1 });
};

return (
<>
<ColorPicker color={color} onColorChange={handleChange}>
<ColorSlider />
<AlphaSlider />
<ColorArea />
</ColorPicker>
<InputHexField color={color} onChange={handleChange} />
<InputRgbField color={color} onChange={handleChange} />
<ColorSwatch color={color}>
<div style={{ backgroundColor: `${selectedColor}` }} />
</>
);
};
```
Comment on lines -147 to -174
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All the examples of inputs are in the storybook now

`onColorChange` event returns data which contains a new color.

![ColorPicker](./assets/color-picker-layout.jpg)

Validation of color fields will be in `utils`. Validation should not allow entering incorrect values to the input fields.

For color manipulation and conversion [tinycolor](https://www.npmjs.com/package/@ctrl/tinycolor) library will be used.

| Slots | Values | Default | Description |
@@ -188,7 +153,7 @@ For color manipulation and conversion [tinycolor](https://www.npmjs.com/package/
| Property | Values | Default | Purpose |
| ------------ | ------------------- | --------- | --------------------------------------- |
| color | `HSV` | | Sets color value in HSV format |
| defauleColor | `HSV` | | Sets color for uncontrollable ColorArea |
| defaultColor | `HSV` | | Sets color for uncontrollable ColorArea |
| onChange | `function` | undefined | Callback called when color is selected |
| shape | `square`, `rounded` | `rounded` | Sets shape |

@@ -201,13 +166,14 @@ For color manipulation and conversion [tinycolor](https://www.npmjs.com/package/

### ColorSlider

| Property | Values | Default | Purpose |
| ------------ | ------------------------ | ------------ | ----------------------------------------- |
| color | `HSV` | | Sets color value in HSV format |
| defauleColor | `HSV` | | Sets color for uncontrollable ColorSlider |
| onChange | `function` | undefined | Callback called when color is selected |
| orient | `horizontal`, `vertical` | `horizontal` | Orientation of a slider |
| shape | `square`, `rounded` | `rounded` | Sets shape |
| Property | Values | Default | Purpose |
| ------------ | ---------------------------- | --------- | ----------------------------------------- |
| channel | `hue`, `saturation`, `value` | `hue` | Sets color channel |
| color | `HSV` | | Sets color value in HSV format |
| defaultColor | `HSV` | | Sets color for uncontrollable ColorSlider |
| onChange | `function` | undefined | Callback called when color is selected |
| shape | `square`, `rounded` | `rounded` | Sets shape |
| vertical | `boolean` | `false` | Orientation of a slider |

| Slots | Values | Default | Description |
| ------ | ------- | ------- | ---------------------------------------------------------------- |
@@ -218,7 +184,10 @@ For color manipulation and conversion [tinycolor](https://www.npmjs.com/package/

### AlphaSlider

AlphaSlider has the same props and slots as ColorSlider.
AlphaSlider has the same props and slots as ColorSlider except `transparent` prop.
| Property | Values | Default | Purpose |
| ------------ | ---------------------------- | --------- | ----------------------------------------- |
| transparent | `boolean` | `false` | The `transparency` property determines how the alpha channel is interpreted |

## Structure

@@ -309,11 +278,12 @@ States:

In a `horizontal` orientation top/right arrows move to the right, bottom/left arrows move to the left.

| Key | Result |
| -------------------- | -------------------------------------------------------------- |
| Arrows | Color thumb is focused. Color is selected |
| `Home/End/PgUp/PgDn` | Can be used another configuration for the step to move faster. |
| `Tab` | Navigation between color sliders and Color Area |
| Key | Result |
| ----------- | ----------------------------------------------- |
| Arrows | Color thumb is focused. Color is selected |
| `PgUp/PgDn` | Can be used for faster navigation |
| `Home/End` | Navigates to the beginning or end of a Slider |
| `Tab` | Navigation between color sliders and Color Area |

##### Color/Alpha Slider