diff --git a/packages/react-components/react-message-bar-preview/etc/react-message-bar-preview.api.md b/packages/react-components/react-message-bar-preview/etc/react-message-bar-preview.api.md index beb5a9bb592f52..22f1ecdc03c679 100644 --- a/packages/react-components/react-message-bar-preview/etc/react-message-bar-preview.api.md +++ b/packages/react-components/react-message-bar-preview/etc/react-message-bar-preview.api.md @@ -89,9 +89,12 @@ export type MessageBarGroupState = ComponentState & Pick & Pick, 'layout'> & { - intent?: 'info' | 'success' | 'warning' | 'error'; + intent?: MessageBarIntent; politeness?: 'assertive' | 'polite'; }; diff --git a/packages/react-components/react-message-bar-preview/src/components/MessageBar/MessageBar.types.ts b/packages/react-components/react-message-bar-preview/src/components/MessageBar/MessageBar.types.ts index 383262e1199e48..3488ba0456ae17 100644 --- a/packages/react-components/react-message-bar-preview/src/components/MessageBar/MessageBar.types.ts +++ b/packages/react-components/react-message-bar-preview/src/components/MessageBar/MessageBar.types.ts @@ -11,12 +11,20 @@ export type MessageBarContextValues = { messageBar: MessageBarContextValue; }; +export type MessageBarIntent = 'info' | 'success' | 'warning' | 'error'; + /** * MessageBar Props */ export type MessageBarProps = ComponentProps & Pick, 'layout'> & { - intent?: 'info' | 'success' | 'warning' | 'error'; + /** + * Default designs announcement presets + */ + intent?: MessageBarIntent; + /** + * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions + */ politeness?: 'assertive' | 'polite'; }; diff --git a/packages/react-components/react-message-bar-preview/src/components/MessageBarActions/MessageBarActions.types.ts b/packages/react-components/react-message-bar-preview/src/components/MessageBarActions/MessageBarActions.types.ts index 112c3a27e5f191..47162346a5b6b0 100644 --- a/packages/react-components/react-message-bar-preview/src/components/MessageBarActions/MessageBarActions.types.ts +++ b/packages/react-components/react-message-bar-preview/src/components/MessageBarActions/MessageBarActions.types.ts @@ -4,6 +4,9 @@ import type { MessageBarContextValue } from '../../contexts/messageBarContext'; export type MessageBarActionsSlots = { root: Slot<'div'>; + /** + * Generally the 'Dismiss' button for the MessageBar + */ containerAction?: Slot<'div'>; }; diff --git a/packages/react-components/react-message-bar-preview/src/index.ts b/packages/react-components/react-message-bar-preview/src/index.ts index 03ef9aa77eca80..5772df9c6b940f 100644 --- a/packages/react-components/react-message-bar-preview/src/index.ts +++ b/packages/react-components/react-message-bar-preview/src/index.ts @@ -6,7 +6,7 @@ export { messageBarClassNames, } from './MessageBar'; -export type { MessageBarProps, MessageBarSlots, MessageBarState } from './MessageBar'; +export type { MessageBarProps, MessageBarSlots, MessageBarState, MessageBarIntent } from './MessageBar'; export { MessageBarTitle, diff --git a/packages/react-components/react-message-bar-preview/stories/MessageBar/Animation.stories.tsx b/packages/react-components/react-message-bar-preview/stories/MessageBar/Animation.stories.tsx index 2f0378d969af85..6620c1bd25c62a 100644 --- a/packages/react-components/react-message-bar-preview/stories/MessageBar/Animation.stories.tsx +++ b/packages/react-components/react-message-bar-preview/stories/MessageBar/Animation.stories.tsx @@ -8,10 +8,12 @@ import { MessageBarBody, MessageBarGroup, MessageBarGroupProps, + MessageBarIntent, } from '@fluentui/react-message-bar-preview'; const useStyles = makeStyles({ container: { + ...shorthands.padding(tokens.spacingHorizontalMNudge), display: 'flex', flexDirection: 'column', marginTop: '10px', @@ -22,17 +24,17 @@ const useStyles = makeStyles({ }, }); -const intents = ['info', 'warning', 'error', 'success'] as const; +const intents: MessageBarIntent[] = ['info', 'warning', 'error', 'success']; interface Entry { - intent: (typeof intents)[number]; + intent: MessageBarIntent; id: number; } export const Animation = () => { const styles = useStyles(); const counterRef = React.useRef(0); - const [animate, setAnimate] = React.useState('exit-only'); + const [animate, setAnimate] = React.useState('both'); const [messages, setMessages] = React.useState([]); const prepend = () => { const intentPos = Math.floor(Math.random() * intents.length); @@ -60,8 +62,8 @@ export const Animation = () => { setAnimate(value as MessageBarGroupProps['animate'])}> - + @@ -80,3 +82,15 @@ export const Animation = () => { ); }; + +Animation.parameters = { + docs: { + description: { + story: [ + 'Enter animations are also handled within the `MessageBarGroup`. However avoid entry animations for MessageBar', + 'components on page load. However, MessageBar components that are mounted during the lifecycle of an', + 'app can use enter animations.', + ].join('\n'), + }, + }, +}; diff --git a/packages/react-components/react-message-bar-preview/stories/MessageBar/Default.stories.tsx b/packages/react-components/react-message-bar-preview/stories/MessageBar/Default.stories.tsx index c6c7034034318f..fe785f03cf77c1 100644 --- a/packages/react-components/react-message-bar-preview/stories/MessageBar/Default.stories.tsx +++ b/packages/react-components/react-message-bar-preview/stories/MessageBar/Default.stories.tsx @@ -3,21 +3,15 @@ import { Button, Link } from '@fluentui/react-components'; import { DismissRegular } from '@fluentui/react-icons'; import { MessageBar, MessageBarActions, MessageBarTitle, MessageBarBody } from '@fluentui/react-message-bar-preview'; -const intents = ['info', 'warning', 'error', 'success'] as const; - export const Default = () => ( -
- {intents.map(intent => ( - - - Descriptive title - Message providing information to the user with actionable insights. Link - - } />}> - - - - - ))} -
+ + + Descriptive title + Message providing information to the user with actionable insights. Link + + } />}> + + + + ); diff --git a/packages/react-components/react-message-bar-preview/stories/MessageBar/Dismiss.stories.tsx b/packages/react-components/react-message-bar-preview/stories/MessageBar/Dismiss.stories.tsx index da6f35d2bf44b6..91e988654f4b0b 100644 --- a/packages/react-components/react-message-bar-preview/stories/MessageBar/Dismiss.stories.tsx +++ b/packages/react-components/react-message-bar-preview/stories/MessageBar/Dismiss.stories.tsx @@ -7,10 +7,12 @@ import { MessageBarTitle, MessageBarBody, MessageBarGroup, + MessageBarIntent, } from '@fluentui/react-message-bar-preview'; const useStyles = makeStyles({ container: { + ...shorthands.padding(tokens.spacingHorizontalMNudge), display: 'flex', flexDirection: 'column', marginTop: '10px', @@ -21,10 +23,10 @@ const useStyles = makeStyles({ }, }); -const intents = ['info', 'warning', 'error', 'success'] as const; +const intents: MessageBarIntent[] = ['info', 'warning', 'error', 'success']; interface Entry { - intent: (typeof intents)[number]; + intent: MessageBarIntent; id: number; } @@ -72,3 +74,15 @@ export const Dismiss = () => { ); }; + +Dismiss.parameters = { + docs: { + description: { + story: [ + 'MessageBar components should be used in a `MessageBarGroup` when possible to enable exit animations.', + 'Once inside a `MessageBarGroup` component, the default exit animation will trigger automatically when the', + 'component is unmounted from DOM.', + ].join('\n'), + }, + }, +}; diff --git a/packages/react-components/react-message-bar-preview/stories/MessageBar/Intent.stories.tsx b/packages/react-components/react-message-bar-preview/stories/MessageBar/Intent.stories.tsx new file mode 100644 index 00000000000000..48454533faa803 --- /dev/null +++ b/packages/react-components/react-message-bar-preview/stories/MessageBar/Intent.stories.tsx @@ -0,0 +1,41 @@ +import * as React from 'react'; +import { Button, Link } from '@fluentui/react-components'; +import { DismissRegular } from '@fluentui/react-icons'; +import { + MessageBar, + MessageBarActions, + MessageBarTitle, + MessageBarBody, + MessageBarIntent, +} from '@fluentui/react-message-bar-preview'; + +const intents: MessageBarIntent[] = ['info', 'warning', 'error', 'success']; + +export const Intent = () => ( +
+ {intents.map(intent => ( + + + {intent} + Message providing information to the user with actionable insights. Link + + } />}> + + + + + ))} +
+); + +Intent.parameters = { + docs: { + description: { + story: [ + 'MessageBar components come built-in with preset intents that determine the design and aria live announcment,', + "While it is recommended to use the preset intents, it's possible to configure the aria live politeness", + 'with the `politeness` prop.', + ].join('\n'), + }, + }, +}; diff --git a/packages/react-components/react-message-bar-preview/stories/MessageBar/ManualLayout.stories.tsx b/packages/react-components/react-message-bar-preview/stories/MessageBar/ManualLayout.stories.tsx index 34c942a80a7add..3209d95f9896a0 100644 --- a/packages/react-components/react-message-bar-preview/stories/MessageBar/ManualLayout.stories.tsx +++ b/packages/react-components/react-message-bar-preview/stories/MessageBar/ManualLayout.stories.tsx @@ -30,3 +30,14 @@ export const ManualLayout = () => { ); }; + +ManualLayout.parameters = { + docs: { + description: { + story: [ + "It's possible to opt out of automatic reflow with the `layout` prop. This can be useful if an application", + 'has an existing responsive design mechanism.', + ].join('\n'), + }, + }, +}; diff --git a/packages/react-components/react-message-bar-preview/stories/MessageBar/MessageBarBestPractices.md b/packages/react-components/react-message-bar-preview/stories/MessageBar/MessageBarBestPractices.md index 08ff8ddeeb5f86..a9ed5bdfb0c5aa 100644 --- a/packages/react-components/react-message-bar-preview/stories/MessageBar/MessageBarBestPractices.md +++ b/packages/react-components/react-message-bar-preview/stories/MessageBar/MessageBarBestPractices.md @@ -2,4 +2,14 @@ ### Do +- Use MessageBar components inside MesssageBarGroup +- Include a dismiss button as the container action +- Reduce number of actions in the MessageBar +- Use preset intents + ### Don't + +- Use enter animations on page load +- Use manual layout if possible - this is a built in feature +- Use long messages for content - keep content to under 100 characters +- Customize announcement politeness - check with your a11y champ diff --git a/packages/react-components/react-message-bar-preview/stories/MessageBar/MessageBarDescription.md b/packages/react-components/react-message-bar-preview/stories/MessageBar/MessageBarDescription.md index e69de29bb2d1d6..150d4b100d1892 100644 --- a/packages/react-components/react-message-bar-preview/stories/MessageBar/MessageBarDescription.md +++ b/packages/react-components/react-message-bar-preview/stories/MessageBar/MessageBarDescription.md @@ -0,0 +1,3 @@ +Communicates important information about the state of the entire application or surface. +For example, the status of a page, panel, dialog or card. The information shouldn't require someone +to take immediate action, but should persist until the user performs one of the required actions. diff --git a/packages/react-components/react-message-bar-preview/stories/MessageBar/Reflow.stories.tsx b/packages/react-components/react-message-bar-preview/stories/MessageBar/Reflow.stories.tsx index 58982e5894df6a..3a1cc3e9272d35 100644 --- a/packages/react-components/react-message-bar-preview/stories/MessageBar/Reflow.stories.tsx +++ b/packages/react-components/react-message-bar-preview/stories/MessageBar/Reflow.stories.tsx @@ -57,3 +57,14 @@ export const Reflow = () => { ); }; + +Reflow.parameters = { + docs: { + description: { + story: [ + 'The `MessageBar` will reflow by default once the body content wraps to a second line. This changes the layout', + 'of the actions in the MessageBar. ', + ].join('\n'), + }, + }, +}; diff --git a/packages/react-components/react-message-bar-preview/stories/MessageBar/index.stories.tsx b/packages/react-components/react-message-bar-preview/stories/MessageBar/index.stories.tsx index 4791dd2c83a592..ce7a2aa06b7e18 100644 --- a/packages/react-components/react-message-bar-preview/stories/MessageBar/index.stories.tsx +++ b/packages/react-components/react-message-bar-preview/stories/MessageBar/index.stories.tsx @@ -1,17 +1,21 @@ -import { MessageBar } from '@fluentui/react-message-bar-preview'; +import { MessageBar, MessageBarGroup } from '@fluentui/react-message-bar-preview'; import descriptionMd from './MessageBarDescription.md'; import bestPracticesMd from './MessageBarBestPractices.md'; export { Default } from './Default.stories'; +export { Intent } from './Intent.stories'; export { Dismiss } from './Dismiss.stories'; +export { Animation } from './Animation.stories'; export { Reflow } from './Reflow.stories'; export { ManualLayout } from './ManualLayout.stories'; -export { Animation } from './Animation.stories'; export default { title: 'Preview Components/MessageBar', component: MessageBar, + subcomponents: { + MessageBarGroup, + }, parameters: { docs: { description: {