diff --git a/components/assetcard/stories/assetcard.mdx b/components/assetcard/stories/assetcard.mdx deleted file mode 100644 index d6edaaa0201..00000000000 --- a/components/assetcard/stories/assetcard.mdx +++ /dev/null @@ -1,66 +0,0 @@ -import { - ArgTypes, - Canvas, - Meta, - Description, - Title, - Subtitle, -} from "@storybook/blocks"; -import { - ComponentDetails, - TaggedReleases, - PropertiesTable, -} from "@spectrum-css/preview/blocks"; -import * as AssetCardStories from "./assetcard.stories"; - - - - -<Subtitle of={AssetCardStories} /> -<ComponentDetails /> - -<Description of={AssetCardStories} /> - -## Portrait - -<Canvas of={AssetCardStories.Portrait} /> - -## Landscape - -<Canvas of={AssetCardStories.Landscape} /> - -## Square - -<Canvas of={AssetCardStories.Square} /> - -## Optional Content - -<Canvas of={AssetCardStories.OptionalContent} /> - -## Highlight Selection - -<Canvas of={AssetCardStories.HighlightSelection} /> - -## Checkbox Selection - -<Canvas of={AssetCardStories.CheckboxSelection} /> - -## Ordered Selection - -<Canvas of={AssetCardStories.OrderedSelection} /> - -## Drop Target - -<Canvas of={AssetCardStories.DropTarget} /> - -## Properties - -The component accepts the following inputs (properties): - -<ArgTypes /> - -<PropertiesTable /> - -## Tagged releases - -<TaggedReleases /> diff --git a/components/assetcard/stories/assetcard.stories.js b/components/assetcard/stories/assetcard.stories.js index e44d5a1ca18..8e815b21809 100644 --- a/components/assetcard/stories/assetcard.stories.js +++ b/components/assetcard/stories/assetcard.stories.js @@ -8,6 +8,10 @@ import { Template } from "./template.js"; /** * The asset card component allows users to select and manage assets and their metadata in a grid. + * + * ## Usage notes + * Set the `--spectrum-assetcard-asset-size` custom property to the size at which you want to display the asset. + * */ export default { title: "Asset card", @@ -89,7 +93,6 @@ export default { packageJson, metadata, }, - tags: ["!autodocs"], }; export const Default = AssetCardGroup.bind({}); @@ -98,8 +101,13 @@ Default.args = { exampleImage: "portrait", content: ["Image"], }; +Default.tags = ["!autodocs"]; // ********* DOCS ONLY ********* // +/** + * Inside the tile, an asset card displays the preview of the item it represents. The preview has different styles, depending on the type of item. + * + * The default asset card is also referred to as "portrait." */ export const Portrait = Template.bind({}); Portrait.args = { title: "Portrait asset", @@ -110,6 +118,7 @@ Portrait.tags = ["!dev"]; Portrait.parameters = { chromatic: { disableSnapshot: true }, }; +Portrait.storyName = "Default"; export const Landscape = Template.bind({}); Landscape.args = { @@ -131,6 +140,9 @@ Square.parameters = { chromatic: { disableSnapshot: true }, }; +/** + * Asset cards have two optional content areas for extra information: `.spectrum-AssetCard-content` and `.spectrum-AssetCard-headerContent`. These content areas can include time stamps, non-interactive rating indicators, colored labels, badges, and more. + */ export const OptionalContent = Template.bind({}); OptionalContent.args = { title: "MVI_0123.mp4", @@ -141,7 +153,11 @@ OptionalContent.tags = ["!dev"]; OptionalContent.parameters = { chromatic: { disableSnapshot: true }, }; +OptionalContent.storyName = "Optional content"; +/** + * Sometimes it may not make sense to use checkboxes to indicate selection. In those rare cases, show a highlighted state when a user is inspecting one or more cards. + */ export const HighlightSelection = Template.bind({}); HighlightSelection.args = { title: "Highlight selection", @@ -153,7 +169,11 @@ HighlightSelection.tags = ["!dev"]; HighlightSelection.parameters = { chromatic: { disableSnapshot: true }, }; +HighlightSelection.storyName = "Selection - highlight"; +/** + * Some cards allow selection, on which the user can take an action. Both single-select and multi-select cards have checkboxes on the top left of the card (or in the top right for RTL languages). + */ export const CheckboxSelection = Template.bind({}); CheckboxSelection.args = { title: "Checkbox selection", @@ -165,7 +185,11 @@ CheckboxSelection.tags = ["!dev"]; CheckboxSelection.parameters = { chromatic: { disableSnapshot: true }, }; +CheckboxSelection.storyName = "Selection - checkbox"; +/** + * In cases where it’s important for users to know the order in which they have selected multiple cards — for example, to add video clips to a sequence — use ordered selection. Ordered selection must be multi-selectable. + */ export const OrderedSelection = Template.bind({}); OrderedSelection.args = { title: "Ordered selection", @@ -177,6 +201,7 @@ OrderedSelection.tags = ["!dev"]; OrderedSelection.parameters = { chromatic: { disableSnapshot: true }, }; +OrderedSelection.storyName = "Selection - ordered"; export const DropTarget = Template.bind({}); DropTarget.args = { @@ -190,6 +215,7 @@ DropTarget.tags = ["!dev"]; DropTarget.parameters = { chromatic: { disableSnapshot: true }, }; +DropTarget.storyName = "Drop target"; // ********* VRT ONLY ********* // export const WithForcedColors = AssetCardGroup.bind({}); diff --git a/components/avatar/stories/avatar.mdx b/components/avatar/stories/avatar.mdx deleted file mode 100644 index f25de9a1cf6..00000000000 --- a/components/avatar/stories/avatar.mdx +++ /dev/null @@ -1,64 +0,0 @@ -import { - ArgTypes, - Canvas, - Meta, - Description, - Title, - Subtitle, -} from "@storybook/blocks"; -import { - ComponentDetails, - TaggedReleases, - PropertiesTable, -} from "@spectrum-css/preview/blocks"; -import * as AvatarStories from "./avatar.stories"; - -<Meta of={AvatarStories} title="Docs" /> - -<Title of={AvatarStories} /> -<Subtitle of={AvatarStories} /> -<ComponentDetails /> - -<Description of={AvatarStories} /> - -<Canvas of={AvatarStories.Default} /> - -## Sizes - -Avatar is available in many sizes using the required `.spectrum-Avatar--size<number>` class. The available size classes are: - -- `spectrum-Avatar--size50` -- `spectrum-Avatar--size75` -- `spectrum-Avatar--size100` -- `spectrum-Avatar--size200` -- `spectrum-Avatar--size300` -- `spectrum-Avatar--size400` -- `spectrum-Avatar--size500` -- `spectrum-Avatar--size600` -- `spectrum-Avatar--size700` - -<Canvas of={AvatarStories.SizeOptions} /> - -## No Link - -An avatar image is wrapped in a link that uses the `.spectrum-Avatar-link` class by default, however, an avatar may also be used without a link. - -<Canvas of={AvatarStories.NoLink} /> - -## Disabled - -When disabled, the avatar should only be used without a link. - -<Canvas of={AvatarStories.Disabled} /> - -## Properties - -The component accepts the following inputs (properties): - -<ArgTypes /> - -<PropertiesTable /> - -## Tagged releases - -<TaggedReleases /> diff --git a/components/avatar/stories/avatar.stories.js b/components/avatar/stories/avatar.stories.js index f07d44e149d..3f87e56e02b 100644 --- a/components/avatar/stories/avatar.stories.js +++ b/components/avatar/stories/avatar.stories.js @@ -7,12 +7,7 @@ import { AvatarGroup } from "./avatar.test.js"; import { Template } from "./template.js"; /** - * An image representing a user. Note that a div wrapper is required for avatar: - * ``` - * <div class="spectrum-Avatar spectrum-Avatar--size50"> - * <img class="spectrum-Avatar-image" src="img/example-ava.jpg" alt="Avatar"> - * </div> - * ``` + * An image representing a user. */ export default { title: "Avatar", @@ -65,25 +60,49 @@ export default { packageJson, metadata, }, - tags: ["!autodocs"], }; +/** + * Note that a `div` wrapper is required for avatar: + * ``` + * <div class="spectrum-Avatar spectrum-Avatar--size50"> + * <img class="spectrum-Avatar-image" src="img/example-ava.jpg" alt="Avatar"> + * </div> + * ``` + */ export const Default = AvatarGroup.bind({}); Default.args = {}; // ********* DOCS ONLY ********* // -export const SizeOptions = (args, context) => Sizes({ +/** Avatar sizes scale exponentially, based on the Spectrum type scale. These range from size-50 to size-700, with the default size for an avatar being `100`. An avatar can also be customized to fit appropriately for your context. + * + * Avatar is available in many sizes using the required `.spectrum-Avatar--size<number>` class. The available size classes are: + +- `spectrum-Avatar--size50` +- `spectrum-Avatar--size75` +- `spectrum-Avatar--size100` +- `spectrum-Avatar--size200` +- `spectrum-Avatar--size300` +- `spectrum-Avatar--size400` +- `spectrum-Avatar--size500` +- `spectrum-Avatar--size600` +- `spectrum-Avatar--size700` +*/ +export const Sizing = (args, context) => Sizes({ Template, withHeading: false, withBorder: false, ...args }, context); -SizeOptions.tags = ["!dev"]; -SizeOptions.args = Default.args; -SizeOptions.parameters = { +Sizing.tags = ["!dev"]; +Sizing.args = Default.args; +Sizing.parameters = { chromatic: { disableSnapshot: true }, }; +/** + * An avatar image is wrapped in a link that uses the `.spectrum-Avatar-link` class by default, however, an avatar may also be used without a link. + */ export const NoLink = Template.bind({}); NoLink.tags = ["!dev"]; NoLink.args = { @@ -94,7 +113,10 @@ NoLink.args = { NoLink.parameters = { chromatic: { disableSnapshot: true }, }; +NoLink.storyName = "No link"; +/** + * When disabled, the avatar should only be used without a link.*/ export const Disabled = Template.bind({}); Disabled.tags = ["!dev"]; Disabled.args = { diff --git a/components/avatar/stories/avatar.test.js b/components/avatar/stories/avatar.test.js index 870ea74c0d0..35536a2e46f 100644 --- a/components/avatar/stories/avatar.test.js +++ b/components/avatar/stories/avatar.test.js @@ -10,6 +10,7 @@ export const AvatarGroup = Variants({ }, { testHeading: "Disabled", isDisabled: true, + hasLink: false, }, { testHeading: "Focused", isFocused: true, diff --git a/components/badge/stories/badge.mdx b/components/badge/stories/badge.mdx deleted file mode 100644 index e6587039ca1..00000000000 --- a/components/badge/stories/badge.mdx +++ /dev/null @@ -1,55 +0,0 @@ -import { - ArgTypes, - Canvas, - Meta, - Description, - Title, - Subtitle, -} from "@storybook/blocks"; -import { - ComponentDetails, - TaggedReleases, - PropertiesTable, -} from "@spectrum-css/preview/blocks"; - -import * as BadgeStories from "./badge.stories"; - -<Meta of={BadgeStories} title="Docs" /> - -<Title of={BadgeStories} /> -<Subtitle of={BadgeStories} /> -<ComponentDetails /> - -<Description of={BadgeStories} /> - -## Default - -Badges can contain label, icon, or label and icon. Text wrapping is also included when a `max-width` is applied to the badge. - -<Canvas of={BadgeStories.Default} /> - -## Semantic - -<Canvas of={BadgeStories.SemanticVariants} /> - -## Non-semantic - -<Canvas of={BadgeStories.NonSemanticVariants} /> - -## Fixed edge - -The border radius is 0 along the fixed edge of the component. The actual component position is not represented on this page. - -<Canvas of={BadgeStories.FixedVariants} /> - -## Properties - -The component accepts the following inputs (properties): - -<ArgTypes /> - -<PropertiesTable /> - -## Tagged releases - -<TaggedReleases /> diff --git a/components/badge/stories/badge.stories.js b/components/badge/stories/badge.stories.js index dc3e0d28b24..8815afc9d6d 100644 --- a/components/badge/stories/badge.stories.js +++ b/components/badge/stories/badge.stories.js @@ -1,3 +1,4 @@ +import { Sizes } from "@spectrum-css/preview/decorators/utilities.js"; import { default as IconStories } from "@spectrum-css/icon/stories/icon.stories.js"; import { ArgGrid } from "@spectrum-css/preview/decorators"; import { disableDefaultModes } from "@spectrum-css/preview/modes"; @@ -5,14 +6,12 @@ import { size } from "@spectrum-css/preview/types"; import metadata from "../metadata/metadata.json"; import packageJson from "../package.json"; import { BadgeGroup } from "./badge.test.js"; -import { Template } from "./template.js"; +import { ContentOptions, Template } from "./template.js"; /** * A badge element displays a small amount of color-categorized metadata; ideal for getting a user's attention. Some notes about badge: - * - Badge t-shirt sizes correspond to icon sizes - * - Label and icon elements must be nested inside a parent container of class .spectrum-Badge in order to achieve the correct layout and wrapping behavior. - * - Layout of Badge is applied with a display of `inline-flex`, allowing badge to display as inline while the child elements for the label and icon utilize flexbox for layout. - * - Fixed positioning impacts the border radius of the badge component + * - Label and icon elements must be nested inside a parent container of class `.spectrum-Badge` in order to achieve the correct layout and wrapping behavior. + * - The layout of badge is achieved by applying a display of `inline-flex`, allowing badge to display as inline, while the label and/or icon child elements can utilize flexbox for layout. */ export default { title: "Badge", @@ -34,13 +33,14 @@ export default { }, iconSet: { table: { disable: true } }, variant: { - name: "Background color variants", + name: "Variants", + description: "Changes the badge's background color. The variant list includes both semantic and non-semantic options.", type: { name: "string" }, table: { type: { summary: "string" }, category: "Component", }, - options: ["neutral", "accent", "informative", "positive", "negative", "gray", "red", "orange", "yellow", "chartreuse", "celery", "green", "seafoam", "cyan", "blue", "indigo", "purple", "fuchsia", "magenta"], + options: ["neutral", "accent", "informative", "positive", "negative", "notice", "gray", "red", "orange", "yellow", "chartreuse", "celery", "green", "seafoam", "cyan", "blue", "indigo", "purple", "fuchsia", "magenta"], control: "select", }, fixed: { @@ -69,9 +69,11 @@ export default { packageJson, metadata, }, - tags: ["!autodocs"], }; +/** + * Badges can contain label, icon, or label and icon. Text wrapping is also included when a `max-inline-size` is applied to the badge. + */ export const Default = BadgeGroup.bind({}); Default.args = { iconName: "Info", @@ -82,7 +84,7 @@ Default.args = { export const SemanticVariants = (args, context) => ArgGrid({ Template, argKey: "variant", - options: ["neutral", "accent", "informative", "positive", "negative"], + options: ["neutral", "accent", "informative", "positive", "negative", "notice"], withBorder: false, ...args, }, context); @@ -91,6 +93,7 @@ SemanticVariants.tags = ["!dev"]; SemanticVariants.parameters = { chromatic: { disableSnapshot: true }, }; +SemanticVariants.storyName = "Semantic"; export const NonSemanticVariants = (args, context) => ArgGrid({ Template, @@ -104,7 +107,11 @@ NonSemanticVariants.tags = ["!dev"]; NonSemanticVariants.parameters = { chromatic: { disableSnapshot: true }, }; +NonSemanticVariants.storyName = "Non-semantic"; +/** + * Fixed positioning impacts the border radius of the badge component. The border radius is 0 along the fixed edge of the component. The actual component position is not represented on this page. + */ export const FixedVariants = (args, context) => ArgGrid({ Template, argKey: "fixed", @@ -117,6 +124,22 @@ FixedVariants.tags = ["!dev"]; FixedVariants.parameters = { chromatic: { disableSnapshot: true }, }; +FixedVariants.storyName = "Fixed-edge"; + +/** + * Badge t-shirt sizes correspond to icon sizes. + */ +export const Sizing = (args, context) => Sizes({ + Template: ContentOptions, + withBorder: false, + withHeading: false, + ...args, +}, context); +Sizing.args = Default.args; +Sizing.parameters = { + chromatic: { disableSnapshot: true }, +}; +Sizing.tags = ["!dev"]; // ********* VRT ONLY ********* // export const WithForcedColors = BadgeGroup.bind({}); diff --git a/components/badge/stories/badge.test.js b/components/badge/stories/badge.test.js index d1068ec340a..b226b07b700 100644 --- a/components/badge/stories/badge.test.js +++ b/components/badge/stories/badge.test.js @@ -17,7 +17,7 @@ export const BadgeGroup = Variants({ Template: Badges, sizeDirection: "row", testData: [ - ...["neutral", "accent", "informative", "positive", "negative"].map((variant) => + ...["neutral", "accent", "informative", "positive", "negative", "notice"].map((variant) => ({ testHeading: capitalize(variant), wrapperStyles: { diff --git a/components/badge/stories/template.js b/components/badge/stories/template.js index 0d0833020fc..529d9328a1b 100644 --- a/components/badge/stories/template.js +++ b/components/badge/stories/template.js @@ -1,3 +1,4 @@ +import { Container } from "@spectrum-css/preview/decorators"; import { Template as Icon } from "@spectrum-css/icon/stories/template.js"; import { getRandomId } from "@spectrum-css/preview/decorators"; import { html } from "lit"; @@ -52,3 +53,13 @@ export const Template = ({ </div> `; }; + +/* Displays icon-only, text-only, and icon-and-text badge options. */ +export const ContentOptions = (args, context) => Container({ + withBorder: false, + content: [ + Template(args, context), + Template({ ...args, iconName: undefined }, context), + Template({ ...args, label: undefined }, context), + ] +});