diff --git a/change/@fluentui-react-rating-preview-94bd847c-77c5-4f2e-8000-acbceb63aa7e.json b/change/@fluentui-react-rating-preview-94bd847c-77c5-4f2e-8000-acbceb63aa7e.json
new file mode 100644
index 0000000000000..3bba7ab4006e4
--- /dev/null
+++ b/change/@fluentui-react-rating-preview-94bd847c-77c5-4f2e-8000-acbceb63aa7e.json
@@ -0,0 +1,7 @@
+{
+ "type": "patch",
+ "comment": "chore: Updating doc stories and API.",
+ "packageName": "@fluentui/react-rating-preview",
+ "email": "ololubek@microsoft.com",
+ "dependentChangeType": "patch"
+}
diff --git a/packages/react-components/react-rating-preview/docs/Spec.md b/packages/react-components/react-rating-preview/docs/Spec.md
index 89a7ab9c60165..cb25931e86dfb 100644
--- a/packages/react-components/react-rating-preview/docs/Spec.md
+++ b/packages/react-components/react-rating-preview/docs/Spec.md
@@ -1,63 +1,104 @@
-# @fluentui/react-rating-preview Spec
+# @fluentui/react-rating Spec
## Background
-_Description and use cases of this component_
+A `Rating` component allows users to provide a rating for a particular item.
+
+This component displays a set of stars or other symbols that represent the rating value. Users can interact with the component to select a rating by clicking on the stars or using touch gestures.
## Prior Art
-_Include background research done for this component_
+### Open UI
+
+### Comparison of v8 and v0
-- _Link to Open UI research_
-- _Link to comparison of v7 and v0_
-- _Link to GitHub epic issue for the converged component_
+The existing components are:
+
+- v8
+ - `Rating`
+- v0
## Sample Code
-_Provide some representative example code that uses the proposed API for the component_
+Basic example:
-## Variants
+```jsx
+import { Rating } from '@fluentui/react-rating';
-_Describe visual or functional variants of this control, if applicable. For example, a slider could have a 2D variant._
+function App() {
+ return ;
+}
+```
## API
-_List the **Props** and **Slots** proposed for the component. Ideally this would just be a link to the component's `.types.ts` file_
+### Slots
+
+#### Rating slots
+
+- `root` - The root slot of the `Rating` is the container that will contain the slots that make up a `Rating`. The default html element is a `div`.
+- `ratingLabel` - This slot will render the value of the `Rating`. The default html element is a `label`.
+- `ratingCountLabel`- This slot will render the total number of ratings. The default html element is a `label`.
+
+#### RatingItem slots
+
+- `root` - The root slot of the `RatingItem`. The default element is `span`.
+- `selectedIcon` - Icon displayed when `Rating` value is greater than or equal to the `RatingItem` value.
+- `selectedFilledIcon` - Icon displayed when `Rating` value is less than the `RatingItem` value. Outline style gray
+- `selectedUnfilledIcon` - Icon displayed when `Rating` value is less than the `RatingItem` value. Outline style white.
+- `halfValueInput` - Input slot for when `precision` prop is active and need to render half values of `RatingItem`.
+- `fullValueInput` - Default input slot to render selected `RatingItem`
+
+### Props
+
+See API at [Rating.types.tsx](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-rating-preview/src/components/Rating/Rating.types.ts).
## Structure
-- _**Public**_
-- _**Internal**_
-- _**DOM** - how the component will be rendered as HTML elements_
+```html
+
+
+
+
+
+
+
+
+
+
+
+```
## Migration
-_Describe what will need to be done to upgrade from the existing implementations:_
-
-- _Migration from v8_
-- _Migration from v0_
+See [MIGRATION.md](./MIGRATION.md).
## Behaviors
-_Explain how the component will behave in use, including:_
+### States
+
+- **Display** - The `Rating` will use the following priority:
+
+ - The `appearance` prop will dictate whether an unfilled `RatingItem` has a neutral white background or a gray background. Typically used for readOnly
+ - The `mode` prop will be used to set the type of `Rating`.
+ - The `max` prop sets how many `RatingItems` there are in the `Rating`
+ - Setting the `size` prop will allow the user to specify the size of the element.
+ - You can pass in filled and regular versions of icons to `iconFilled` and `iconOutline` slots to render custom `RatingItems`.
+
+### Interaction
+
+The Rating can be interactive or non-iteractive depending on the use case
+
+- **Keyboard** - Can use arrow keys.
+- **Mouse**
+
+ - Click: Selects a `RatingItem`
+ - Hover: Fills up to the hovered `RatingItem`
-- _Component States_
-- _Interaction_
- - _Keyboard_
- - _Cursor_
- - _Touch_
- - _Screen readers_
+- **Touch**
+ - Press: Selects a `RatingItem`
+ - Drag: No behavior
## Accessibility
-Base accessibility information is included in the design document. After the spec is filled and review, outcomes from it need to be communicated to design and incorporated in the design document.
-
-- Decide whether to use **native element** or folow **ARIA** and provide reasons
-- Identify the **[ARIA](https://www.w3.org/TR/wai-aria-practices-1.2/) pattern** and, if the component is listed there, follow its specification as possible.
-- Identify accessibility **variants**, the `role` ([ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#role_definitions)) of the component, its `slots` and `aria-*` props.
-- Describe the **keyboard navigation**: Tab Oder and Arrow Key Navigation. Describe any other keyboard **shortcuts** used
-- Specify texts for **state change announcements** - [ARIA live regions
- ](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) (number of available items in dropdown, error messages, confirmations, ...)
-- Identify UI parts that appear on **hover or focus** and specify keyboard and screen reader interaction with them
-- List cases when **focus** needs to be **trapped** in sections of the UI (for dialogs and popups or for hierarchical navigation)
-- List cases when **focus** needs to be **moved programatically** (if parts of the UI are appearing/disappearing or other cases)
+- Tbd. Needs some sort of labelling for the `RatingItem` when interactive and for the whole `Rating` component when readOnly
diff --git a/packages/react-components/react-rating-preview/etc/react-rating-preview.api.md b/packages/react-components/react-rating-preview/etc/react-rating-preview.api.md
index 4c7773131404f..94301558d5510 100644
--- a/packages/react-components/react-rating-preview/etc/react-rating-preview.api.md
+++ b/packages/react-components/react-rating-preview/etc/react-rating-preview.api.md
@@ -20,7 +20,7 @@ export const Rating: ForwardRefComponent;
export const ratingClassNames: SlotClassNames;
// @public (undocumented)
-export type RatingContextValue = Pick;
+export type RatingContextValue = Pick;
// @public (undocumented)
export type RatingContextValues = {
@@ -49,7 +49,7 @@ export type RatingItemSlots = {
};
// @public
-export type RatingItemState = ComponentState & Required> & Pick & {
+export type RatingItemState = ComponentState & Required> & Pick & {
iconFillWidth: number;
};
@@ -60,17 +60,16 @@ export type RatingOnChangeData = {
// @public
export type RatingProps = ComponentProps & {
- appearance?: 'filled' | 'outline';
- compact?: boolean;
+ color?: 'brand' | 'marigold' | 'neutral';
defaultValue?: number;
iconFilled?: React_2.ReactElement;
iconOutline?: React_2.ReactElement;
max?: number;
+ mode?: 'interactive' | 'read-only' | 'read-only-compact';
name?: string;
onChange?: (ev: React_2.SyntheticEvent | Event, data: RatingOnChangeData) => void;
- precision?: boolean;
- readOnly?: boolean;
- size?: 'small' | 'medium' | 'large';
+ step?: 0.5 | 1;
+ size?: 'small' | 'medium' | 'large' | 'extra-large';
value?: number;
};
@@ -85,7 +84,7 @@ export type RatingSlots = {
};
// @public
-export type RatingState = ComponentState & Required> & {
+export type RatingState = ComponentState & Required> & {
hoveredValue?: number | undefined;
};
diff --git a/packages/react-components/react-rating-preview/src/components/Rating/Rating.types.ts b/packages/react-components/react-rating-preview/src/components/Rating/Rating.types.ts
index ca974682f2945..0bfd260e09eda 100644
--- a/packages/react-components/react-rating-preview/src/components/Rating/Rating.types.ts
+++ b/packages/react-components/react-rating-preview/src/components/Rating/Rating.types.ts
@@ -12,15 +12,10 @@ export type RatingSlots = {
*/
export type RatingProps = ComponentProps & {
/**
- * Controls the appearance of unselected rating items.
- * @default outline (filled if readOnly is set)
+ * Controls the appearance of the Rating.
+ * @default neutral
*/
- appearance?: 'filled' | 'outline';
- /**
- * Sets whether to render a full or compact Rating
- * @default false
- */
- compact?: boolean;
+ color?: 'brand' | 'marigold' | 'neutral';
/**
* Default value of the Rating
*/
@@ -39,6 +34,11 @@ export type RatingProps = ComponentProps & {
* @default 5
*/
max?: number;
+ /**
+ * The mode of the rating.
+ * @default 'interactive'
+ */
+ mode?: 'interactive' | 'read-only' | 'read-only-compact';
/**
* Name for the Radio inputs. If not provided, one will be automatically generated
*/
@@ -49,19 +49,14 @@ export type RatingProps = ComponentProps & {
onChange?: (ev: React.SyntheticEvent | Event, data: RatingOnChangeData) => void;
/**
* Sets the precision to allow half-filled shapes in Rating
- * @default false
- */
- precision?: boolean;
- /**
- * Sets Rating to be read only
- * @default false
+ * @default 1
*/
- readOnly?: boolean;
+ step?: 0.5 | 1;
/**
* Sets the size of the Rating items.
* @default medium
*/
- size?: 'small' | 'medium' | 'large';
+ size?: 'small' | 'medium' | 'large' | 'extra-large';
/**
* The value of the rating
*/
@@ -82,27 +77,13 @@ export type RatingOnChangeData = {
* State used in rendering Rating
*/
export type RatingState = ComponentState &
- Required<
- Pick<
- RatingProps,
- 'appearance' | 'compact' | 'iconFilled' | 'iconOutline' | 'name' | 'precision' | 'readOnly' | 'size' | 'value'
- >
- > & {
+ Required> & {
hoveredValue?: number | undefined;
};
export type RatingContextValue = Pick<
RatingState,
- | 'appearance'
- | 'compact'
- | 'iconFilled'
- | 'iconOutline'
- | 'name'
- | 'precision'
- | 'readOnly'
- | 'size'
- | 'value'
- | 'hoveredValue'
+ 'color' | 'iconFilled' | 'iconOutline' | 'mode' | 'name' | 'step' | 'size' | 'value' | 'hoveredValue'
>;
export type RatingContextValues = {
diff --git a/packages/react-components/react-rating-preview/src/components/Rating/useRating.tsx b/packages/react-components/react-rating-preview/src/components/Rating/useRating.tsx
index 676dc051331f5..9d4c58e87d36c 100644
--- a/packages/react-components/react-rating-preview/src/components/Rating/useRating.tsx
+++ b/packages/react-components/react-rating-preview/src/components/Rating/useRating.tsx
@@ -23,15 +23,14 @@ import { StarFilled, StarRegular } from '@fluentui/react-icons';
export const useRating_unstable = (props: RatingProps, ref: React.Ref): RatingState => {
const generatedName = useId('rating-');
const {
- appearance = props.readOnly ? 'filled' : 'outline',
- compact = false,
+ color = 'neutral',
iconFilled = ,
iconOutline = ,
max = 5,
+ mode = 'interactive',
name = generatedName,
onChange,
- precision = false,
- readOnly = false,
+ step = 1,
size = 'medium',
} = props;
@@ -51,21 +50,20 @@ export const useRating_unstable = (props: RatingProps, ref: React.Ref {
- return !compact ? (
- Array.from(Array(max), (_, i) => )
- ) : (
+ return mode === 'read-only-compact' ? (
+ ) : (
+ Array.from(Array(max), (_, i) => )
);
- }, [compact, max]);
+ }, [mode, max]);
const state: RatingState = {
- appearance,
- compact,
+ color,
iconFilled,
iconOutline,
+ mode,
name,
- precision,
- readOnly,
+ step,
size,
value,
hoveredValue,
@@ -92,7 +90,7 @@ export const useRating_unstable = (props: RatingProps, ref: React.Ref {
if (isRatingRadioItem(ev.target)) {
const newValue = parseFloat(ev.target.value);
diff --git a/packages/react-components/react-rating-preview/src/components/RatingItem/RatingItem.types.ts b/packages/react-components/react-rating-preview/src/components/RatingItem/RatingItem.types.ts
index 33486badbbff6..fd56d44484a11 100644
--- a/packages/react-components/react-rating-preview/src/components/RatingItem/RatingItem.types.ts
+++ b/packages/react-components/react-rating-preview/src/components/RatingItem/RatingItem.types.ts
@@ -44,6 +44,6 @@ export type RatingItemProps = ComponentProps> & {
*/
export type RatingItemState = ComponentState &
Required> &
- Pick & {
+ Pick & {
iconFillWidth: number;
};
diff --git a/packages/react-components/react-rating-preview/src/components/RatingItem/useRatingItem.tsx b/packages/react-components/react-rating-preview/src/components/RatingItem/useRatingItem.tsx
index ba451c501f058..c96b41ef39764 100644
--- a/packages/react-components/react-rating-preview/src/components/RatingItem/useRatingItem.tsx
+++ b/packages/react-components/react-rating-preview/src/components/RatingItem/useRatingItem.tsx
@@ -22,7 +22,7 @@ export const useRatingItem_unstable = (props: RatingItemProps, ref: React.Ref= value) {
+ if ((context && context.mode === 'read-only-compact') || displayedRatingValue >= value) {
iconFillWidth = 1;
} else if (displayedRatingValue >= value - 0.5) {
iconFillWidth = 0.5;
@@ -52,7 +52,7 @@ export const useRatingItem_unstable = (props: RatingItemProps, ref: React.Ref {
- const { appearance, compact, hoveredValue, iconFilled, iconOutline, name, precision, readOnly, size, value } = state;
+ const { color, hoveredValue, iconFilled, iconOutline, mode, name, step, size, value } = state;
const rating = React.useMemo(
() => ({
- appearance,
- compact,
+ color,
hoveredValue,
iconFilled,
iconOutline,
+ mode,
name,
- precision,
- readOnly,
+ step,
size,
value,
}),
- [appearance, compact, hoveredValue, iconFilled, iconOutline, name, precision, readOnly, size, value],
+ [color, hoveredValue, iconFilled, iconOutline, mode, name, step, size, value],
);
return { rating };
diff --git a/packages/react-components/react-rating-preview/stories/Rating/RatingColor.stories.tsx b/packages/react-components/react-rating-preview/stories/Rating/RatingColor.stories.tsx
new file mode 100644
index 0000000000000..fa2bdb1002ee8
--- /dev/null
+++ b/packages/react-components/react-rating-preview/stories/Rating/RatingColor.stories.tsx
@@ -0,0 +1,32 @@
+import * as React from 'react';
+import { Rating } from '@fluentui/react-rating-preview';
+import { makeStyles, shorthands } from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+ root: {
+ display: 'flex',
+ flexDirection: 'column',
+ ...shorthands.gap('10px'),
+ },
+});
+
+export const Color = () => {
+ const styles = useStyles();
+ return (
+
+
+
+
+
+
+
+ );
+};
+
+Color.parameters = {
+ docs: {
+ description: {
+ story: 'You can specify the appearance of the Rating component with the "color" prop.',
+ },
+ },
+};
diff --git a/packages/react-components/react-rating-preview/stories/Rating/RatingCompact.stories.tsx b/packages/react-components/react-rating-preview/stories/Rating/RatingCompact.stories.tsx
deleted file mode 100644
index dd337f0019265..0000000000000
--- a/packages/react-components/react-rating-preview/stories/Rating/RatingCompact.stories.tsx
+++ /dev/null
@@ -1,14 +0,0 @@
-import * as React from 'react';
-import { Rating } from '@fluentui/react-rating-preview';
-
-export const Compact = () => {
- return ;
-};
-
-Compact.parameters = {
- docs: {
- description: {
- story: 'You can use a compact Rating as a representation of the total Rating count.',
- },
- },
-};
diff --git a/packages/react-components/react-rating-preview/stories/Rating/RatingDescription.md b/packages/react-components/react-rating-preview/stories/Rating/RatingDescription.md
index e69de29bb2d1d..12bc99b2b1096 100644
--- a/packages/react-components/react-rating-preview/stories/Rating/RatingDescription.md
+++ b/packages/react-components/react-rating-preview/stories/Rating/RatingDescription.md
@@ -0,0 +1,3 @@
+A `Rating` component allows users to provide a rating for a particular item.
+
+`Rating` displays a set of stars or other symbols that represent the rating value. It can also display the value represented by the `Rating`, as well as the number of users who have given a rating. Users can interact with the component to select a rating by clicking on the stars or using touch gestures.
diff --git a/packages/react-components/react-rating-preview/stories/Rating/RatingMax.stories.tsx b/packages/react-components/react-rating-preview/stories/Rating/RatingMax.stories.tsx
index ba460c71ef203..8fe6613175fea 100644
--- a/packages/react-components/react-rating-preview/stories/Rating/RatingMax.stories.tsx
+++ b/packages/react-components/react-rating-preview/stories/Rating/RatingMax.stories.tsx
@@ -2,7 +2,7 @@ import * as React from 'react';
import { Rating } from '@fluentui/react-rating-preview';
export const Max = () => {
- return ;
+ return ;
};
Max.parameters = {
diff --git a/packages/react-components/react-rating-preview/stories/Rating/RatingMode.stories.tsx b/packages/react-components/react-rating-preview/stories/Rating/RatingMode.stories.tsx
new file mode 100644
index 0000000000000..d5fdc86b13c53
--- /dev/null
+++ b/packages/react-components/react-rating-preview/stories/Rating/RatingMode.stories.tsx
@@ -0,0 +1,51 @@
+import * as React from 'react';
+import { Rating } from '@fluentui/react-rating-preview';
+import { Label, makeStyles, shorthands } from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+ root: {
+ display: 'flex',
+ flexDirection: 'column',
+ ...shorthands.gap('10px'),
+ },
+});
+
+export const Mode = () => {
+ const styles = useStyles();
+ return (
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ );
+};
+
+Mode.parameters = {
+ docs: {
+ description: {
+ story: 'You can specify the mode of the Rating component with the "mode" prop.',
+ },
+ },
+};
diff --git a/packages/react-components/react-rating-preview/stories/Rating/RatingReadOnly.stories.tsx b/packages/react-components/react-rating-preview/stories/Rating/RatingReadOnly.stories.tsx
deleted file mode 100644
index c1075e16406dc..0000000000000
--- a/packages/react-components/react-rating-preview/stories/Rating/RatingReadOnly.stories.tsx
+++ /dev/null
@@ -1,14 +0,0 @@
-import * as React from 'react';
-import { Rating } from '@fluentui/react-rating-preview';
-
-export const ReadOnly = () => {
- return ;
-};
-
-ReadOnly.parameters = {
- docs: {
- description: {
- story: 'A readonly Rating can be used for display purposes, and is not functional.',
- },
- },
-};
diff --git a/packages/react-components/react-rating-preview/stories/Rating/RatingShape.stories.tsx b/packages/react-components/react-rating-preview/stories/Rating/RatingShape.stories.tsx
index 257014132981c..aabff90da720c 100644
--- a/packages/react-components/react-rating-preview/stories/Rating/RatingShape.stories.tsx
+++ b/packages/react-components/react-rating-preview/stories/Rating/RatingShape.stories.tsx
@@ -15,7 +15,7 @@ export const Shape = () => {
const styles = useStyles();
return (
);
};
@@ -24,7 +25,7 @@ export const Size = () => {
Size.parameters = {
docs: {
description: {
- story: 'A Rating can be small, medium, or large. You can specify the size with the "size" prop.',
+ story: 'A Rating can be small, medium, large, or xlarge. You can specify the size with the "size" prop.',
},
},
};
diff --git a/packages/react-components/react-rating-preview/stories/Rating/RatingPrecision.stories.tsx b/packages/react-components/react-rating-preview/stories/Rating/RatingStep.stories.tsx
similarity index 61%
rename from packages/react-components/react-rating-preview/stories/Rating/RatingPrecision.stories.tsx
rename to packages/react-components/react-rating-preview/stories/Rating/RatingStep.stories.tsx
index 96b7c90db0145..f1b0aa409ef97 100644
--- a/packages/react-components/react-rating-preview/stories/Rating/RatingPrecision.stories.tsx
+++ b/packages/react-components/react-rating-preview/stories/Rating/RatingStep.stories.tsx
@@ -1,14 +1,14 @@
import * as React from 'react';
import { Rating } from '@fluentui/react-rating-preview';
-export const Precision = () => {
- return ;
+export const Step = () => {
+ return ;
};
-Precision.parameters = {
+Step.parameters = {
docs: {
description: {
- story: 'You can specify half values in the Rating with the "precision" prop.',
+ story: 'You can specify half values in the Rating with the "step" prop.',
},
},
};
diff --git a/packages/react-components/react-rating-preview/stories/Rating/index.stories.tsx b/packages/react-components/react-rating-preview/stories/Rating/index.stories.tsx
index fec05cef2371b..0847cafd3bd96 100644
--- a/packages/react-components/react-rating-preview/stories/Rating/index.stories.tsx
+++ b/packages/react-components/react-rating-preview/stories/Rating/index.stories.tsx
@@ -4,10 +4,10 @@ import descriptionMd from './RatingDescription.md';
import bestPracticesMd from './RatingBestPractices.md';
export { Default } from './RatingDefault.stories';
-export { Compact } from './RatingCompact.stories';
+export { Color } from './RatingColor.stories';
export { Max } from './RatingMax.stories';
-export { Precision } from './RatingPrecision.stories';
-export { ReadOnly } from './RatingReadOnly.stories';
+export { Mode } from './RatingMode.stories';
+export { Step } from './RatingStep.stories';
export { Size } from './RatingSize.stories';
export { Shape } from './RatingShape.stories';