From 504d03513db2d57f6b2cc5b6083d89ad2b51ee23 Mon Sep 17 00:00:00 2001 From: Ashley Echols Date: Fri, 2 Aug 2024 12:02:44 -0500 Subject: [PATCH] docs: updates Empty States docs pages for Rails and React --- .../components/empty_state/_preview.html.erb | 2 +- .../components/empty_state/_props.html.erb | 6 +- .../_sage_empty_state.html.erb | 1 + .../stylesheets/components/_empty_state.scss | 1 - .../sage-react/lib/EmptyState/EmptyState.jsx | 36 +++++++- .../lib/EmptyState/EmptyState.story.jsx | 59 ------------ .../lib/EmptyState/EmptyState.story.mdx | 92 +++++++++++++++++++ 7 files changed, 132 insertions(+), 65 deletions(-) delete mode 100644 packages/sage-react/lib/EmptyState/EmptyState.story.jsx create mode 100644 packages/sage-react/lib/EmptyState/EmptyState.story.mdx diff --git a/docs/app/views/examples/components/empty_state/_preview.html.erb b/docs/app/views/examples/components/empty_state/_preview.html.erb index d311061d7a..cf18c50378 100644 --- a/docs/app/views/examples/components/empty_state/_preview.html.erb +++ b/docs/app/views/examples/components/empty_state/_preview.html.erb @@ -8,7 +8,7 @@ <% end %>

With Icon and Compact

-

Compact variants, with less top and bottom padding, are useful for smaller contexts.

+

Compact variants, with a smaller icon, are useful for smaller contexts.

<%= sage_component SageEmptyState, { icon: "bold", title: "Title for state, compact variety", diff --git a/docs/app/views/examples/components/empty_state/_props.html.erb b/docs/app/views/examples/components/empty_state/_props.html.erb index 58f63932ff..8ea699b93d 100644 --- a/docs/app/views/examples/components/empty_state/_props.html.erb +++ b/docs/app/views/examples/components/empty_state/_props.html.erb @@ -1,6 +1,6 @@ <%= md('`center_vertical`') %> - <%= md('If true, the empty state will be adjust to be visually centered inside the entire page context.') %> + <%= md('If true, the empty state will be visually centered inside the entire page context.') %> <%= md('Boolean') %> <%= md('`false`') %> @@ -17,8 +17,8 @@ <%= md('`nil`') %> - <%= md('`scope`') %> - <%= md('The layout of the component adjusts depending on this context setting: + <%= md('`size`') %> + <%= md('The size of the icon adjusts depending on this context setting: - `nil` (default) sets up a "feature"-level layout for use on whole page empty states and is intended to fill the stage. - `"compact"` similar to the default above, this compacts the spacing a little more for smaller contexts. diff --git a/docs/lib/sage_rails/app/views/sage_components/_sage_empty_state.html.erb b/docs/lib/sage_rails/app/views/sage_components/_sage_empty_state.html.erb index 0ed9ad29e5..7f4070f492 100644 --- a/docs/lib/sage_rails/app/views/sage_components/_sage_empty_state.html.erb +++ b/docs/lib/sage_rails/app/views/sage_components/_sage_empty_state.html.erb @@ -26,6 +26,7 @@ end style="--color-background-icon: <%= component.icon_background || SageTokens::COLOR_PALETTE[:MERCURY_30] %>" > <%= sage_component SageIcon, { + color: "white", icon: component.icon, size: variant == 'compact' ? 'xl' : '3xl', css_classes: "sage-empty-state__icon" diff --git a/packages/sage-assets/lib/stylesheets/components/_empty_state.scss b/packages/sage-assets/lib/stylesheets/components/_empty_state.scss index 202525f14f..7a95b5727a 100644 --- a/packages/sage-assets/lib/stylesheets/components/_empty_state.scss +++ b/packages/sage-assets/lib/stylesheets/components/_empty_state.scss @@ -71,7 +71,6 @@ $-empty-state-icon-compact-size: rem(56px); .sage-empty-state__icon { display: inline-flex; - color: sage-color(white); inline-size: $-empty-state-icon-size; block-size: $-empty-state-icon-size; } diff --git a/packages/sage-react/lib/EmptyState/EmptyState.jsx b/packages/sage-react/lib/EmptyState/EmptyState.jsx index 73db0e9042..eb56246d4b 100644 --- a/packages/sage-react/lib/EmptyState/EmptyState.jsx +++ b/packages/sage-react/lib/EmptyState/EmptyState.jsx @@ -46,8 +46,9 @@ export const EmptyState = ({ style={{ '--color-background-icon': backgroundColor || SageTokens.COLOR_PALETTE.MERCURY_30 }} > @@ -107,15 +108,48 @@ EmptyState.defaultProps = { }; EmptyState.propTypes = { + /** + * Slot into which buttons or other actions can be placed. + */ actions: PropTypes.node, + /** + * If true, the Empty State will be visually centered inside the entire page context. + */ centerVertical: PropTypes.bool, + /** + * The content to be rendered within the Empty State. + */ children: PropTypes.node, + /** + * Adds a graphic above the content. + */ graphic: PropTypes.node, + /** + * Adds an icon above the content. + */ icon: PropTypes.oneOf(Object.values(SageTokens.ICONS)), + /** + * Sets the background color of the icon container. Defaults to Mercury 30 + */ backgroundColor: PropTypes.string, + /** + * The size and context of the Empty State. + */ size: PropTypes.oneOf(Object.values(EmptyState.SIZES)), + /** + * Sets the text for the Empty State. + */ text: PropTypes.oneOfType([PropTypes.string, PropTypes.node]), + /** + * Sets the title for the Empty State. + */ title: PropTypes.oneOfType([PropTypes.string, PropTypes.node]), + /** + * Sets which HTML heading tag to use on the title. + */ titleTag: PropTypes.oneOf(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']), + /** + * Slot into which video cards or other media can be placed. + */ video: PropTypes.node, }; diff --git a/packages/sage-react/lib/EmptyState/EmptyState.story.jsx b/packages/sage-react/lib/EmptyState/EmptyState.story.jsx deleted file mode 100644 index 98e3d4f021..0000000000 --- a/packages/sage-react/lib/EmptyState/EmptyState.story.jsx +++ /dev/null @@ -1,59 +0,0 @@ -import React from 'react'; -import { selectArgs } from '../story-support/helpers'; -import { Button } from '../Button'; -import { SageTokens } from '../configs'; -import { EmptyState } from './EmptyState'; - -export default { - title: 'Sage/EmptyState', - component: EmptyState, - // displays description on Docs tab - parameters: { - docs: { - description: { - component: 'The Empty State is displayed for main application features that have never been interacted with before. The Empty State is also used for smaller features in the app that primarily focus on data entry and have no data to show.' - }, - }, - }, - argTypes: { - ...selectArgs({ - icon: SageTokens.ICONS, - size: EmptyState.SIZES - }) - }, - args: { - actions: ( - - ), - icon: SageTokens.ICONS.GEAR, - text: 'Text Here', - title: 'Title Here' - } -}; - -const Template = (args) => ; - -export const Default = Template.bind({}); - -export const CompactSize = Template.bind({}); -CompactSize.args = { - icon: null, - graphic: (), - size: EmptyState.SIZES.PAGE, - text: ( -

- Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Elit arcu volutpat cursus ultricies ac, ultricies. - Platea sed nibh molestie ut. -

- ), - title: 'Create your first Email Campaign', - titleTag: 'h1', - children: null, - actions: ( - <> - - - - ) -}; diff --git a/packages/sage-react/lib/EmptyState/EmptyState.story.mdx b/packages/sage-react/lib/EmptyState/EmptyState.story.mdx new file mode 100644 index 0000000000..ba47b8f595 --- /dev/null +++ b/packages/sage-react/lib/EmptyState/EmptyState.story.mdx @@ -0,0 +1,92 @@ +import { Meta, Story, Canvas, ArgsTable } from '@storybook/addon-docs/blocks'; +import { Button } from '../Button'; +import { SageTokens } from '../configs'; +import { EmptyState } from './EmptyState'; + + + +# Empty State + +The Empty State is displayed for main application features that have never been interacted with before. The Empty State is also used for smaller features in the app that primarily focus on data entry and have no data to show. + +## Accessibility + +Ensure images or graphics that are used in the Empty State component *do not* include alt text so that the image remains decorative and invisible to screen readers. + +## Properties + + + +## Size + +The Empty State component has two sizes: default and `compact`. The default size is meant to be used for whole-page empty states and is intended to fill the stage. The compact size features a smaller icon and is intended to fill empty states for smaller contexts. + +### Default + + + + + + + + )} + icon={SageTokens.ICONS.PEN} + title="Create your first Email Campaign" + titleTag="h1" + text={(

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. + Elit arcu volutpat cursus ultricies ac, ultricies. + Platea sed nibh molestie ut. +

)} + /> + + + +### Compact + + + + + + + + )} + icon={SageTokens.ICONS.PEN} + size={EmptyState.SIZES.COMPACT} + title="Create your first Email Campaign" + titleTag="h1" + text={(

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. + Elit arcu volutpat cursus ultricies ac, ultricies. + Platea sed nibh molestie ut. +

)} + /> + + + +### With Graphic + + + + + + + + )} + graphic={()} + title="Create your first Email Campaign" + titleTag="h1" + text={(

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. + Elit arcu volutpat cursus ultricies ac, ultricies. + Platea sed nibh molestie ut. +

)} + /> + + \ No newline at end of file