Skip to content

docs(swatch,swatchgroup,table,tabs): docs migrations to storybook #2925

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Sep 18, 2024
Merged

docs(swatch,swatchgroup,table,tabs): docs migrations to storybook #2925

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
de242a1
docs(swatch): adds missing variants, expands test coverage
marissahuysentruyt Aug 27, 2024
2e39538
docs(swatchgroup): adds missing variants, test coverage
marissahuysentruyt Aug 27, 2024
1b4239b
docs(tabs): adds stories and test cases
marissahuysentruyt Aug 27, 2024
80aa6f6
docs(table): adds stories and test cases
marissahuysentruyt Aug 27, 2024
cb994a8
docs(swatch,swatchgroup,table): clean up
marissahuysentruyt Aug 28, 2024
0e74505
chore(tabs): add backticks to token reference in docs
marissahuysentruyt Sep 9, 2024
d350766
docs(swatch): update descriptions for controls
marissahuysentruyt Sep 9, 2024
81b24b5
docs(swatchgroup): add rounding none to roundinggroup
marissahuysentruyt Sep 9, 2024
0eb3e52
docs(tabs): update wording on docs page
marissahuysentruyt Sep 9, 2024
8348027
chore(table): table clean up
marissahuysentruyt Sep 9, 2024
7c23e81
docs(swatchgroup): refactor swatches and borders
marissahuysentruyt Sep 10, 2024
ac722fd
docs(swatch): fix no color/empty story and test
marissahuysentruyt Sep 10, 2024
003070c
docs(swatch,swatchgroup,tabs): pr fixes
marissahuysentruyt Sep 13, 2024
514792a
chore(tabs): use getRandomId to generate ids for tabs/tabitems
marissahuysentruyt Sep 13, 2024
33fb0fb
chore(table): fix sentence case in table cells
marissahuysentruyt Sep 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
195 changes: 194 additions & 1 deletion components/swatch/stories/swatch.stories.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,16 @@
import { disableDefaultModes } from "@spectrum-css/preview/modes";
import { isDisabled, isSelected, size } from "@spectrum-css/preview/types";
import { Sizes } from "@spectrum-css/preview/decorators";
import pkgJson from "../package.json";
import { SwatchGroup } from "./swatch.test.js";
import { Template, DisabledGroup, EmptyGroup, RoundingGroup, BorderGroup, SizingGroup } from "./template";

/**
* A swatch shows a small sample of a fill--such as a color, gradient, texture, or material--that is intended to be applied to an object.
*
* ## Usage notes
*
* Set `--spectrum-picked-color` to customize the swatch fill background color.
*/
export default {
title: "Swatch",
Expand All @@ -22,33 +28,220 @@ export default {
},
rounding: {
name: "Rounding",
description: "The amount of corner rounding for a swatch.",
defaultValue: "regular",
type: { name: "string" },
table: {
type: { summary: "string", required: true },
category: "Component",
defaultValue: { summary: "regular", },
},
options: ["none", "regular", "full"],
control: "select",
},
isDisabled,
isSelected,
borderStyle: {
name: "Border style",
type: { name: "string" },
table: {
type: { summary: "string", required: true },
category: "Component",
},
options: ["default", "none", "light"],
control: "select",
},
shape: {
name: "Swatch shape",
description: "Swatches can have a square or rectangle shape.",
defaultValue: "square",
type: { name: "string" },
table: {
type: { summary: "string" },
category: "Component",
defaultValue: { summary: "square", },
},
options: ["square", "rectangle"],
control: "inline-radio",
},
imageUrl: {
name: "Image url",
description: "The image preview within the swatch.",
type: { name: "string" },
table: {
type: { summary: "string" },
category: "Content",
},
control: { type: "file", accept: ".svg,.png,.jpg,.jpeg,.webc" },
},
gradient: {
name: "Gradient",
description: "The gradient preview within the swatch. Input a gradient example, such as <code>linear-gradient(red, blue)</code>.",
type: { name: "string" },
table: {
type: { summary: "string" },
category: "Component",
},
control: "text",
},
isMixedValue: {
name: "Mixed value",
description: "A swatch that represents multiple values that are not identical.",
type: { name: "boolean" },
table: {
type: { summary: "boolean" },
category: "Component",
},
control: "boolean",
},
},
args: {
rootClass: "spectrum-Swatch",
size: "m",
isSelected: false,
isDisabled: false,
rounding: "regular",
swatchColor: "rgb(174, 216, 230)"
swatchColor: "rgb(174, 216, 230)",
borderStyle: "default",
shape: "square",
isMixedValue: false,
},
parameters: {
packageJson: pkgJson,
},
};

/**
* The medium size is the default and most frequently used option. By default, a swatch has a square shape.
*/
export const Default = SwatchGroup.bind({});
Default.args = {};

// ********* DOCS ONLY ********* //
/**
* The medium size is the default. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page.
*/
export const Sizing = (args, context) => Sizes({
Template: SizingGroup,
withHeading: false,
...args,
}, context);
Sizing.tags = ["!dev"];
Sizing.parameters = {
chromatic: { disableSnapshot: true },
};

/**
* A swatch in a disabled state shows that the swatch exists, but is not available in that circumstance. Even though swatches can have a disabled state, hide unavailable swatches when possible to reduce visual clutter and ease cognitive load. Only show disabled swatches if hiding them would cause confusion to your users.
*/
export const Disabled = (args, context) => Sizes({
Template: DisabledGroup,
withHeading: false,
...args,
}, context);
Disabled.args = {
isDisabled: true,
};
Disabled.tags = ["!dev"];
Disabled.parameters = {
chromatic: { disableSnapshot: true },
};

/**
* Default rounding and full rounding are usually used when a swatch is presented by itself near other components. A rounding of “none” is used in a swatch group to help minimize the Hermann grid illusion that happens at the intersections of white space in the group.
*/
export const Rounding = RoundingGroup.bind({});
Rounding.tags = ["!dev"];
Rounding.args = {
swatchColor: "rgba(174, 216, 230, 0.25)",
};
Rounding.parameters = {
chromatic: { disableSnapshot: true },
};

/**
* A swatch can have a selected state to allow for selection. This is often used in a [swatch group](?path=/docs/components-swatch-group--docs).
*/
export const Selected = Template.bind({});
Selected.args = {
isSelected: true,
};
Selected.tags = ["!dev"];
Selected.parameters = {
chromatic: { disableSnapshot: true },
};

/**
* By default, swatches have a border. However, when swatches are used within a swatch group, there are additional border considerations.
* - When color swatches are used in a [swatch group](?path=/docs/components-swatch-group--docs), they typically have the `.spectrum-Swatch--noBorder` class.
* - When and only when color swatches used in a swatch group have low contrast (below 3:1 contrast with the background), those swatches will have a less prominent border compared to the swatch component when used by itself. They individually use the `.spectrum-Swatch--lightBorder` class.
*/
export const Border = BorderGroup.bind({});
Border.tags = ["!dev"];
Border.parameters = {
chromatic: { disableSnapshot: true },
};

/**
* Swatches can also have a rectangle shape with an aspect ratio of 2:1. The square shape is the default and is used in swatch groups (e.g., a palette of colors).
*/
export const Shape = Template.bind({});
Shape.args = {
shape: "rectangle",
swatchColor: "rgba(174, 216, 230, 0.25)",
};
Shape.tags = ["!dev"];
Shape.parameters = {
chromatic: { disableSnapshot: true },
};
Shape.storyName = "Shape - rectangle";

/**
* A swatch will appear "empty" when its preview is undefined, for instance when the image or gradient is undefined, or when a swatch color is transparent. The `.is-nothing` class is applied to the swatch in these cases. Implementations should ensure that the default border style is applied when a swatch is empty.
*/
export const Empty = (args, context) => Sizes({
Template: EmptyGroup,
withHeading: false,
...args,
}, context);
Empty.args = {
swatchColor: "transparent",
};
Empty.tags = ["!dev"];
Empty.parameters = {
chromatic: { disableSnapshot: true },
};

/**
* When a swatch represents multiple values that are not identical, the preview shows a `gray-50` fill and a dash UI icon.
*/
export const MixedValue = Template.bind({});
MixedValue.args = {
isMixedValue: true,
};
MixedValue.tags = ["!dev"];
MixedValue.parameters = {
chromatic: { disableSnapshot: true },
};

export const Gradient = Template.bind({});
Gradient.args = {
gradient: "linear-gradient(to right, rgba(0, 0, 0, 1) 0%, rgba(0, 0, 0, 0) 100%)",
};
Gradient.tags = ["!dev"];
Gradient.parameters = {
chromatic: { disableSnapshot: true },
};

export const Image = Template.bind({});
Image.args = {
imageUrl: "example-ava@2x.png",
};
Image.tags = ["!dev"];
Image.parameters = {
chromatic: { disableSnapshot: true },
};

// ********* VRT ONLY ********* //
export const WithForcedColors = SwatchGroup.bind({});
WithForcedColors.tags = ["!autodocs", "!dev"];
Expand Down
38 changes: 36 additions & 2 deletions components/swatch/stories/swatch.test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,45 @@ export const SwatchGroup = Variants({
testHeading: "Full rounding",
rounding: "full"
},
{
testHeading: "Light border",
borderStyle: "lightBorder",
},
{
testHeading: "No border",
borderStyle: "noBorder",
rounding: "none",
Comment on lines +27 to +29
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When this test case goes through the "no color" state, how can I override the no border styles? The no color should always have a border, but this test case is specifically for "no border," so would we be looking at a CSS change for the is-nothing class to add a border there?

},
{
testHeading: "Shape: rectangle",
shape: "rectangle",
},
{
testHeading: "Gradient",
gradient: "linear-gradient(to right, rgba(0, 0, 0, 88%), rgb(174, 216, 230))",
swatchColor: "rgba(174, 216, 230, 0.3)",
},
{
testHeading: "Image",
imageUrl: "example-ava@2x.png",
},
{
testHeading: "Mixed value",
isMixedValue: true,
},
],
stateData: [
{
testHeading: "No color",
swatchColor: undefined
testHeading: "Disabled",
isDisabled: true,
},
{
testHeading: "No color/empty",
swatchColor: undefined,
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I could also just add borderStyle: "default" to the no-color test state. That would override all borders, which seems like a somewhat acceptable compromise. However, the trade off is the light border story, in the no-color state, will have the default border.

Is this a question for design?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re: this and your other no-color question above: How do you feel about potentially pulling "no color" out from the stateData and putting it with the testData? Would that allow you to control the borders a bit better?

I believe you said that light border should only be used in the case where the swatch color has low contrast with its background? So in that case I wouldn't show no-color and light-border together in Storybook (ditto with the no border), but I'm unsure if we'd need to prevent those classnames applying their styles simultaneously in the CSS, that feels more like an implementation detail that can be included in the documentation.

I didn't see any guidance about no-color needing to have a border in the internal docs, but it certainly could be a helpful thing to add here in Storybook while you're working on it!

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We did talk briefly in our group pairing about this test. I didn't opt for the ignore: ["No border"] option we mentioned, and went with the borderStyle: "default" in the no-color test case. Let me know what you think of my reasoning.

Looking ahead to swatch in S2, the empty swatch does have the default border, and none of the examples for swatch or swatchgroup have the noBorder option. I think that noBorder option in S1 is really what is throwing off this no-color test case.

I could definitely just pull it out of stateData, and move it to testData. Does it make more sense there? I'm honestly not sure. Since this "noColor" option is also triggered if the swatch color is transparent, maybe we should move it to the test cases.

Screenshot 2024-09-10 at 2 47 15 PM

In this commit, I favored a little preparation for S2 and to avoid the lightBorder and noBorder situations:
Screenshot 2024-09-10 at 2 20 16 PM
Screenshot 2024-09-10 at 2 19 40 PM

What do you think though? Maybe this is something to bring up with the larger group?

imageUrl: "",
gradient: "",
isMixedValue: false,
borderStyle: "default",
},
{
testHeading: "Selected",
Expand Down
Loading
Loading