Skip to content

Commit e670fbe

Browse files
committed
chore: adding docs notes and todos to 2nd gen
1 parent 540aa52 commit e670fbe

File tree

5 files changed

+209
-103
lines changed

5 files changed

+209
-103
lines changed

first-gen/packages/badge/src/badge-overrides.css

Lines changed: 0 additions & 11 deletions
This file was deleted.

second-gen/packages/core/components/badge/Badge.base.ts

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,9 @@ export type FixedValues = (typeof FIXED_VALUES)[number];
5757

5858
/**
5959
* @element sp-badge-base
60-
* @property {BadgeVariant} variant - The variant of the badge.
61-
* @property {FixedValues} fixed - The fixed position of the badge.
62-
* @property {string[]} customStyles - The custom styles of the badge.
60+
* @attribute {ElementSize} size - The size of the badge.
61+
* @attribute {BadgeVariant} variant - The variant of the badge.
62+
* @attribute {FixedValues} fixed - The fixed position of the badge.
6363
*/
6464
export abstract class BadgeBase extends SizedMixin(
6565
ObserveSlotText(ObserveSlotPresence(SpectrumElement, '[slot="icon"]'), ''),
@@ -73,6 +73,9 @@ export abstract class BadgeBase extends SizedMixin(
7373
@property({ type: String, reflect: true })
7474
public fixed?: FixedValues;
7575

76+
/**
77+
* @internal Used for rendering gap when the badge has an icon.
78+
*/
7679
protected get hasIcon(): boolean {
7780
return this.slotContentIsPresent;
7881
}

second-gen/packages/swc/components/badge/Badge.ts

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
* governing permissions and limitations under the License.
1111
*/
1212

13-
import { CSSResultArray, html, TemplateResult } from 'lit';
13+
import { CSSResultArray, html, PropertyValues, TemplateResult } from 'lit';
1414
import { property } from 'lit/decorators.js';
1515
import { classMap } from 'lit/directives/class-map.js';
1616
import { when } from 'lit/directives/when.js';
@@ -55,18 +55,14 @@ export type { FixedValues } from '@swc/core/components/badge';
5555
* @github https://github.com/adobe/spectrum-web-components/tree/main/...
5656
* @figma https://www.figma.com/design/Mngz9H7WZLbrCvGQf3GnsY/S2-%2F-Desktop?node-id=36806-6551
5757
*
58-
* @property {BadgeVariant} variant - The variant of the badge.
59-
* @property {boolean} subtle - Whether the badge is subtle.
60-
* @property {boolean} outline - Whether the badge is outlined.
61-
* @property {FixedValues} fixed - The fixed position of the badge.
62-
* @property {string[]} customStyles - The custom styles of the badge.
58+
* @attribute {BadgeVariant} variant - The variant of the badge.
59+
* @attribute {boolean} subtle - Whether the badge is subtle.
60+
* @attribute {boolean} outline - Whether the badge is outlined.
61+
* @attribute {FixedValues} fixed - The fixed position of the badge.
6362
*
6463
* @slot - Text label of the badge
6564
* @slot icon - Optional icon that appears to the left of the label
6665
*
67-
* @csspart label - The text content area of the badge
68-
* @csspart icon - The icon area of the badge (when present)
69-
*
7066
* @example
7167
* <swc-badge variant="positive">New</swc-badge>
7268
*
@@ -122,4 +118,23 @@ export class Badge extends BadgeBase {
122118
</div>
123119
`;
124120
}
121+
122+
protected override update(changedProperties: PropertyValues): void {
123+
super.update(changedProperties);
124+
if (window.__swc?.DEBUG) {
125+
if (
126+
this.outline &&
127+
!BADGE_VARIANTS_SEMANTIC.includes(this.variant)
128+
) {
129+
window.__swc.warn(
130+
this,
131+
`<${this.localName}> element only supports the outline styling if the variant is a semantic color variant.`,
132+
'https://opensource.adobe.com/spectrum-web-components/components/badge/#variants',
133+
{
134+
issues: [...BADGE_VARIANTS_SEMANTIC],
135+
}
136+
);
137+
}
138+
}
139+
}
125140
}

second-gen/packages/swc/components/badge/stories/badge.stories.ts

Lines changed: 178 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@
1010
* governing permissions and limitations under the License.
1111
*/
1212

13-
import { html } from 'lit';
13+
import { html, nothing, TemplateResult } from 'lit';
14+
import { styleMap } from 'lit/directives/style-map.js';
1415
import type { Meta, StoryObj } from '@storybook/web-components';
1516

1617
import {
@@ -22,122 +23,220 @@ import {
2223

2324
import '@swc/components/badge';
2425

26+
/** @todo Pull this up into a utility function for all components to leverage */
27+
function capitalize(str?: string): string {
28+
if (typeof str !== 'string') {
29+
return '';
30+
}
31+
return str.charAt(0).toUpperCase() + str.slice(1);
32+
}
33+
34+
/** @todo Pull this up into a decorator for all stories to leverage */
35+
const CONTAINER = (content: TemplateResult<1>[]) =>
36+
html`<div
37+
style=${styleMap({
38+
display: 'flex',
39+
gap: 'var(--spectrum-spacing-200)',
40+
'flex-wrap': 'wrap',
41+
'justify-content': 'center',
42+
// Used 80ch because that's generally considered the maximum readable width for text in a web page.
43+
'max-inline-size': '80ch',
44+
})}
45+
>
46+
${content}
47+
</div>`;
48+
49+
/**
50+
* Badges are for showing a small amount of color-categorized metadata. They're ideal for getting a user's attention. There are two additional styles - subtle fill and outline - in addition to the default, bold fill style.
51+
*
52+
* Because outline and subtle fill styles draw a similar level of attention, choose only one to use consistently within a single product. Bold fill can be paired with either style, and is reserved for high-attention badging only.
53+
*/
2554
const meta: Meta = {
2655
title: 'Components/Badge',
2756
component: 'swc-badge',
2857
argTypes: {
29-
variant: {
30-
control: { type: 'select' },
31-
options: BADGE_VARIANTS,
32-
},
33-
fixed: {
34-
control: { type: 'select' },
35-
options: [undefined, ...FIXED_VALUES],
36-
},
3758
size: {
59+
name: 'Size',
3860
control: { type: 'select' },
3961
options: ['s', 'm', 'l', 'xl'],
4062
},
63+
variant: {
64+
name: 'Variant',
65+
control: { type: 'select' },
66+
options: BADGE_VARIANTS,
67+
},
4168
subtle: {
69+
name: 'Subtle',
4270
control: { type: 'boolean' },
4371
},
4472
outline: {
73+
name: 'Outline',
4574
control: { type: 'boolean' },
4675
},
76+
fixed: {
77+
name: 'Fixed',
78+
control: { type: 'select' },
79+
options: [...FIXED_VALUES],
80+
},
81+
label: {
82+
name: 'Label',
83+
control: { type: 'text' },
84+
table: { category: 'Slots' },
85+
},
86+
icon: {
87+
name: 'Icon',
88+
control: { type: 'text' },
89+
table: { category: 'Slots' },
90+
},
4791
},
4892
args: {
93+
label: 'Badge',
94+
// updating this to make the options more readable as a demo
95+
size: 'l',
4996
variant: 'informative',
5097
subtle: false,
5198
outline: false,
5299
},
100+
parameters: {
101+
design: {
102+
type: 'figma',
103+
url: 'https://www.figma.com/design/Mngz9H7WZLbrCvGQf3GnsY/S2-%2F-Desktop?node-id=36806-6551',
104+
},
105+
},
106+
tags: ['migrated'],
53107
};
54108

55109
export default meta;
56110
type Story = StoryObj;
111+
type StoryArgs = StoryObj['args'];
112+
113+
/**
114+
* @param args - The arguments for the badge as sourced from the storybook args.
115+
* @returns A lightweight template for to render a single badge with bindings to the args.
116+
* @todo could also surface a knob to select an icon from our icon library and use that instead of the string.
117+
* @todo is there stronger typing we can use for the args?
118+
*/
119+
const BASE_TEMPLATE = (args: StoryArgs = {}) => html`
120+
<swc-badge
121+
variant="${args.variant}"
122+
size="${args.size || 'm'}"
123+
.fixed=${args.fixed}
124+
.subtle=${args.subtle}
125+
.outline=${args.outline}
126+
>
127+
${args.icon ? html`<span slot="icon">${args.icon}</span>` : nothing}
128+
${args.label}
129+
</swc-badge>
130+
`;
57131

132+
/**
133+
* Badges can contain label, icon, or label and icon. Text wrapping is also included when a `max-inline-size` is applied to the badge.
134+
*/
58135
export const Default: Story = {
59136
args: {
60-
variant: 'informative',
137+
size: 'm',
61138
},
62-
render: (args) => html`
63-
<swc-badge
64-
variant="${args.variant}"
65-
size="${args.size || 'm'}"
66-
.fixed=${args.fixed}
67-
>
68-
Badge
69-
</swc-badge>
70-
`,
139+
render: BASE_TEMPLATE,
71140
};
72141

73-
export const SemanticVariants: Story = {
74-
render: () => html`
75-
<div style="display: flex; gap: 8px; flex-wrap: wrap;">
76-
${BADGE_VARIANTS_SEMANTIC.map(
77-
(variant) => html`
78-
<swc-badge variant="${variant}">${variant}</swc-badge>
79-
`
80-
)}
81-
</div>
82-
`,
142+
/**
143+
* Badges can be rendered with or without an icon. Icons can be passed to the component using the `icon` slot and can be sourced from either the Spectrum icon library or a custom icon library as needed.
144+
*/
145+
export const WithIcon: Story = {
146+
args: {
147+
icon: '✓',
148+
},
149+
render: BASE_TEMPLATE,
150+
// Removes the story from the side navigation while keeping in the docs view
151+
tags: ['!dev'],
83152
};
84153

85-
export const ColorVariants: Story = {
86-
render: () => html`
87-
<div style="display: flex; gap: 8px; flex-wrap: wrap;">
88-
${BADGE_VARIANTS_COLOR.map(
89-
(variant) => html`
90-
<swc-badge variant="${variant}">${variant}</swc-badge>
91-
`
92-
)}
93-
</div>
94-
`,
154+
/**
155+
* Semantic variants allow you to render the badge with a descriptive name that maps to a design-system-aligned color. This is the preferred way to assign color to a badge because it will align more consistently with other components in your UI with the same meaning.
156+
*/
157+
export const SemanticVariants: Story = {
158+
render: (args) =>
159+
CONTAINER(
160+
BADGE_VARIANTS_SEMANTIC.map((variant) =>
161+
BASE_TEMPLATE({
162+
...args,
163+
variant,
164+
label: capitalize(variant),
165+
})
166+
)
167+
),
168+
tags: ['!dev'],
95169
};
96170

97-
export const Sizes: Story = {
98-
render: () => html`
99-
<div style="display: flex; gap: 8px; align-items: center;">
100-
<swc-badge size="s">Small</swc-badge>
101-
<swc-badge size="m">Medium</swc-badge>
102-
<swc-badge size="l">Large</swc-badge>
103-
<swc-badge size="xl">Extra Large</swc-badge>
104-
</div>
105-
`,
171+
/**
172+
* The `outline` style is only valid for semantic color variants.
173+
*/
174+
export const Outline: Story = {
175+
argTypes: {
176+
variant: {
177+
control: { type: 'select' },
178+
options: BADGE_VARIANTS_SEMANTIC,
179+
},
180+
},
181+
render: (args) =>
182+
CONTAINER(
183+
BADGE_VARIANTS_SEMANTIC.map((variant) =>
184+
BASE_TEMPLATE({
185+
...args,
186+
variant,
187+
label: capitalize(variant),
188+
outline: true,
189+
})
190+
)
191+
),
192+
tags: ['!dev'],
106193
};
107194

108-
export const WithIcon: Story = {
109-
render: () => html`
110-
<swc-badge variant="positive">
111-
<span slot="icon"></span>
112-
With icon
113-
</swc-badge>
114-
`,
195+
/**
196+
* Color variants are available for the badge component and provide a more granular access to the full color palette in the design system.
197+
*/
198+
export const ColorVariants: Story = {
199+
render: (args) =>
200+
CONTAINER(
201+
BADGE_VARIANTS_COLOR.map((variant) =>
202+
BASE_TEMPLATE({
203+
...args,
204+
variant,
205+
label: capitalize(variant),
206+
})
207+
)
208+
),
209+
tags: ['!dev'],
115210
};
116211

117-
export const Subtle: Story = {
118-
render: () => html`
119-
<div style="display: flex; gap: 8px; flex-wrap: wrap;">
120-
${BADGE_VARIANTS.map(
121-
(variant) => html`
122-
<swc-badge variant="${variant}" subtle>
123-
${variant}
124-
</swc-badge>
125-
`
126-
)}
127-
</div>
128-
`,
212+
export const Sizes: Story = {
213+
render: (args) =>
214+
CONTAINER(
215+
['s', 'm', 'l', 'xl'].map((size) =>
216+
BASE_TEMPLATE({
217+
...args,
218+
size,
219+
label: capitalize(size),
220+
})
221+
)
222+
),
223+
tags: ['!dev'],
129224
};
130225

131-
export const Outline: Story = {
132-
render: () => html`
133-
<div style="display: flex; gap: 8px; flex-wrap: wrap;">
134-
${BADGE_VARIANTS_SEMANTIC.map(
135-
(variant) => html`
136-
<swc-badge variant="${variant}" outline>
137-
${variant}
138-
</swc-badge>
139-
`
140-
)}
141-
</div>
142-
`,
226+
/**
227+
* The `subtle` style is available for all variants. It is useful when you want to reduce the visual prominence of the badge while still mapping to the design system color palette.
228+
*/
229+
export const Subtle: Story = {
230+
render: (args) =>
231+
CONTAINER(
232+
BADGE_VARIANTS.map((variant) =>
233+
BASE_TEMPLATE({
234+
...args,
235+
variant,
236+
label: capitalize(variant),
237+
subtle: true,
238+
})
239+
)
240+
),
241+
tags: ['!dev'],
143242
};

0 commit comments

Comments
 (0)