From a34b46fee55ad988579fdd773f676ded37735487 Mon Sep 17 00:00:00 2001 From: Phillip Lovelace Date: Mon, 16 Oct 2023 13:51:14 -0700 Subject: [PATCH 1/3] docs(icon): updated documentation --- packages/sage-react/lib/Icon/Icon.story.jsx | 76 ----------- packages/sage-react/lib/Icon/Icon.story.mdx | 141 ++++++++++++++++++++ 2 files changed, 141 insertions(+), 76 deletions(-) delete mode 100644 packages/sage-react/lib/Icon/Icon.story.jsx create mode 100644 packages/sage-react/lib/Icon/Icon.story.mdx diff --git a/packages/sage-react/lib/Icon/Icon.story.jsx b/packages/sage-react/lib/Icon/Icon.story.jsx deleted file mode 100644 index d2382f16e0..0000000000 --- a/packages/sage-react/lib/Icon/Icon.story.jsx +++ /dev/null @@ -1,76 +0,0 @@ -import React from 'react'; -import { selectArgs } from '../story-support/helpers'; -import { SageClassnames, SageTokens } from '../configs'; -import { Icon } from './Icon'; - -export default { - title: 'Sage/Icon', - component: Icon, - // displays description on Docs tab - parameters: { - docs: { - description: { - component: 'The Icon component displays a standalone icon with customizable options.' - }, - }, - }, - argTypes: { - ...selectArgs({ - adjacentType: Icon.ADJACENT_TYPES, - cardColor: Icon.CARD_COLORS, - color: Icon.COLORS, - icon: SageTokens.ICONS, - size: Icon.SIZES - }), - }, - args: { - cardColor: null, - circular: false, - color: Icon.COLORS.GREY, - icon: Icon.ICONS.CHECK_CIRCLE, - label: 'Click me', - size: Icon.SIZES.MD - } -}; -const Template = (args) => ; - -export const Default = Template.bind({}); -export const AdjacentType = Template.bind({}); -AdjacentType.decorators = [ - (Story) => ( - <> -
- {Story()} -

- I am a Heading 2 type spec -

-
-

- Watch how the icon becomes more aligned when you set - the adjacentType property to match - the type spec to which it is adjacent. -

- - ) -]; -export const CustomBackgroundSize = Template.bind({}); -CustomBackgroundSize.args = { - cardColor: 'draft', - backgroundWidth: '96px', - backgroundHeight: '48px', - size: Icon.SIZES.LG -}; -export const CustomBackgroundSizeCircular = Template.bind({}); -CustomBackgroundSizeCircular.args = { - cardColor: 'draft', - circular: true, - backgroundHeight: '48px', - size: Icon.SIZES.LG -}; -export const NullIcon = Template.bind({}); -NullIcon.args = { - cardColor: 'draft', - circular: true, - backgroundHeight: '48px', - icon: Icon.ICONS.NULL, -}; diff --git a/packages/sage-react/lib/Icon/Icon.story.mdx b/packages/sage-react/lib/Icon/Icon.story.mdx new file mode 100644 index 0000000000..612a97f18d --- /dev/null +++ b/packages/sage-react/lib/Icon/Icon.story.mdx @@ -0,0 +1,141 @@ +import { Meta, Story, Canvas, ArgsTable } from "@storybook/addon-docs/blocks"; +import { Icon } from "./Icon"; + + + +# Icon + +The icon component displays a standalone icon with customizable options. + +## Properties + + + +## Default + + + + + + + +## Variants + +### Color + +To change the color of the icon, pass a color name to the `color` prop. Color values are [defined in Figma](https://www.figma.com/file/SHwMHKJXzMRn0tPZXEkfc5/%F0%9F%8E%A8-Sage-styles?type=design&node-id=3%3A1401&mode=design&t=Ri1acMQCzmfaaR9r-1) and include values like `primary-300`, `sage-300`, `red-300`, etc. + + + +
+ + + +
+
+
+ +### Size + +Size can be used to increase or decrease the size of the icon. The default size is `md`. + + + +
+ + + +
+
+
+ +### Card Color + +Icons can be placed on a background by setting the `cardColor` property. + + + +
+ + + +
+
+
+ +### Background Sizes + +Background sizes can be applied by setting the `size` property. + + + +
+ + + +
+
+
+ +### Custom Background Sizes + +Custom background sizes can be applied by setting the `backgroundWidth` and `backgroundHeight` properties. These values are applied as inline styles, so they can be any valid CSS value. The `backgroundWidth` property is required when using `backgroundHeight`. + + + +
+ + + +
+
+
+ +### Circular + +Icons can be made circular by setting the `circular` property to `true`. + + + +
+ + + +
+
+
+ +### Alignment Next to Type + +The `adjacentType` property can be used to align an icon next to a heading or paragraph. This is useful for placing an icon next to a heading or paragraph in a variety of forms. The effect is that the icon's `height` and `line-height` are updated to match the spec responsively. This can be used in combination with the different icon sizes and also be used with a vareity of layout techniques or components such as CSS flexbox (used below) or grid templates within `SageCardRow` or `SagePanelRow`. + + + +
+ +

This is an H2 headline.

+
+
+ +

+ This is paragraph text. This is paragraph text. This is paragraph text. + This is paragraph text. +

+
+
+
From ad585e6027bda31077e551e1b9129a0449dd69f2 Mon Sep 17 00:00:00 2001 From: Phillip Lovelace Date: Tue, 17 Oct 2023 13:03:00 -0700 Subject: [PATCH 2/3] docs(icon): add descriptions for props table --- packages/sage-react/lib/Icon/Icon.jsx | 30 +++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/packages/sage-react/lib/Icon/Icon.jsx b/packages/sage-react/lib/Icon/Icon.jsx index f656f2eaf5..cd955a7e41 100644 --- a/packages/sage-react/lib/Icon/Icon.jsx +++ b/packages/sage-react/lib/Icon/Icon.jsx @@ -95,14 +95,44 @@ Icon.defaultProps = { }; Icon.propTypes = { + /** + * Improves alignment for icons that are placed beside type. + **/ adjacentType: PropTypes.oneOf(Object.values(Icon.ADJACENT_TYPES)), + /** + * Allows a custom height for the icon background. + **/ backgroundHeight: PropTypes.string, + /** + * Allows a custom width for the icon background. + **/ backgroundWidth: PropTypes.string, + /** + * Rather than just changing the icon color with the color property, this option adds a padded background behind the icon in one of the brand status color options. + **/ cardColor: PropTypes.oneOf(Object.values(Icon.CARD_COLORS)), + /** + * Optionally, when an icon has a background color, present the shape inside a circle (as opposed to default square with rounded corners. + **/ circular: PropTypes.bool, + /** + * Allows a custom class name to be added to the icon. + **/ className: PropTypes.string, + /** + * Which color to use to render the icon. + **/ color: PropTypes.oneOf(Object.values(Icon.COLORS)), + /** + * Which icon to display. + **/ icon: PropTypes.oneOf(Object.values(Icon.ICONS)).isRequired, + /** + * An optional accessible label to use for the icon. + **/ label: PropTypes.string, + /** + * Adjusts the size of the icon. + **/ size: PropTypes.oneOf(Object.values(Icon.SIZES)), }; From 245beeb5772535ea390441796022413670a03073 Mon Sep 17 00:00:00 2001 From: Phillip Lovelace Date: Tue, 17 Oct 2023 13:15:04 -0700 Subject: [PATCH 3/3] fix(icon): hello linter my old friend --- packages/sage-react/lib/Icon/Icon.jsx | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/packages/sage-react/lib/Icon/Icon.jsx b/packages/sage-react/lib/Icon/Icon.jsx index cd955a7e41..7d90e3204e 100644 --- a/packages/sage-react/lib/Icon/Icon.jsx +++ b/packages/sage-react/lib/Icon/Icon.jsx @@ -97,42 +97,44 @@ Icon.defaultProps = { Icon.propTypes = { /** * Improves alignment for icons that are placed beside type. - **/ + */ adjacentType: PropTypes.oneOf(Object.values(Icon.ADJACENT_TYPES)), /** * Allows a custom height for the icon background. - **/ + */ backgroundHeight: PropTypes.string, /** * Allows a custom width for the icon background. - **/ + */ backgroundWidth: PropTypes.string, /** - * Rather than just changing the icon color with the color property, this option adds a padded background behind the icon in one of the brand status color options. - **/ + * Rather than just changing the icon color with the color property, this option + * adds a padded background behind the icon in one of the brand status color options. + */ cardColor: PropTypes.oneOf(Object.values(Icon.CARD_COLORS)), /** - * Optionally, when an icon has a background color, present the shape inside a circle (as opposed to default square with rounded corners. - **/ + * Optionally, when an icon has a background color, present the shape + * inside a circle (as opposed to default square with rounded corners. + */ circular: PropTypes.bool, /** * Allows a custom class name to be added to the icon. - **/ + */ className: PropTypes.string, /** * Which color to use to render the icon. - **/ + */ color: PropTypes.oneOf(Object.values(Icon.COLORS)), /** * Which icon to display. - **/ + */ icon: PropTypes.oneOf(Object.values(Icon.ICONS)).isRequired, /** * An optional accessible label to use for the icon. - **/ + */ label: PropTypes.string, /** * Adjusts the size of the icon. - **/ + */ size: PropTypes.oneOf(Object.values(Icon.SIZES)), };