From 2539d2e1d42dac1ac82754e3f6b75f6cb29ed318 Mon Sep 17 00:00:00 2001 From: Myrta Sakellariou Date: Thu, 9 Jan 2025 12:07:35 +0100 Subject: [PATCH 1/3] feat(documentation): styling shadowdom parts --- .../shadowdom-parts/exportparts.sample.html | 8 ++++ .../exportpartsSass.sample.scss | 10 ++++ .../shadowdom-parts/parts.sample.html | 4 ++ .../shadowdom-parts/partsSass.sample.scss | 11 +++++ .../shadowdom-parts/shadowdom-parts.docs.mdx | 46 +++++++++++++++++++ .../shadowdom-parts.stories.ts | 13 ++++++ 6 files changed, 92 insertions(+) create mode 100644 packages/documentation/src/stories/guidelines/shadowdom-parts/exportparts.sample.html create mode 100644 packages/documentation/src/stories/guidelines/shadowdom-parts/exportpartsSass.sample.scss create mode 100644 packages/documentation/src/stories/guidelines/shadowdom-parts/parts.sample.html create mode 100644 packages/documentation/src/stories/guidelines/shadowdom-parts/partsSass.sample.scss create mode 100644 packages/documentation/src/stories/guidelines/shadowdom-parts/shadowdom-parts.docs.mdx create mode 100644 packages/documentation/src/stories/guidelines/shadowdom-parts/shadowdom-parts.stories.ts diff --git a/packages/documentation/src/stories/guidelines/shadowdom-parts/exportparts.sample.html b/packages/documentation/src/stories/guidelines/shadowdom-parts/exportparts.sample.html new file mode 100644 index 0000000000..5e6e42b253 --- /dev/null +++ b/packages/documentation/src/stories/guidelines/shadowdom-parts/exportparts.sample.html @@ -0,0 +1,8 @@ + + + +
Header content
+
Footer content
+ + + diff --git a/packages/documentation/src/stories/guidelines/shadowdom-parts/exportpartsSass.sample.scss b/packages/documentation/src/stories/guidelines/shadowdom-parts/exportpartsSass.sample.scss new file mode 100644 index 0000000000..70c5eb48b9 --- /dev/null +++ b/packages/documentation/src/stories/guidelines/shadowdom-parts/exportpartsSass.sample.scss @@ -0,0 +1,10 @@ +grandparent-element { + parent-element { + custom-element::part(header) { + font-weight: bold; + } + custom-element::part(footer) { + color: gray; + } + } +} diff --git a/packages/documentation/src/stories/guidelines/shadowdom-parts/parts.sample.html b/packages/documentation/src/stories/guidelines/shadowdom-parts/parts.sample.html new file mode 100644 index 0000000000..513f12164e --- /dev/null +++ b/packages/documentation/src/stories/guidelines/shadowdom-parts/parts.sample.html @@ -0,0 +1,4 @@ + +
Header content
+
Footer content
+ diff --git a/packages/documentation/src/stories/guidelines/shadowdom-parts/partsSass.sample.scss b/packages/documentation/src/stories/guidelines/shadowdom-parts/partsSass.sample.scss new file mode 100644 index 0000000000..3c5db1d13e --- /dev/null +++ b/packages/documentation/src/stories/guidelines/shadowdom-parts/partsSass.sample.scss @@ -0,0 +1,11 @@ +custom-element::part(header) { + font-weight: bold; +} + +custom-element::part(footer):hover { + color: gray; +} + +custom-element::part(footer)::after { + content: 'Added after pseudo-element'; +} diff --git a/packages/documentation/src/stories/guidelines/shadowdom-parts/shadowdom-parts.docs.mdx b/packages/documentation/src/stories/guidelines/shadowdom-parts/shadowdom-parts.docs.mdx new file mode 100644 index 0000000000..8807bcd025 --- /dev/null +++ b/packages/documentation/src/stories/guidelines/shadowdom-parts/shadowdom-parts.docs.mdx @@ -0,0 +1,46 @@ +import { Meta, Source } from '@storybook/blocks'; +import * as ShadowdomPartsStories from './shadowdom-parts.stories'; +import parts from './parts.sample.html?raw'; +import partsSass from './partsSass.sample.scss?raw'; +import exportparts from './exportparts.sample.html?raw'; +import exportpartsSass from './exportpartsSass.sample.scss?raw'; + + + +# Styling Shadowdom Parts + +## Parts + +
+ The `part` attribute allows a shadow tree element to be exposed to its parent DOM. +
+ +To style an HTML shadow element, first set the `part` attribute on the element and assign it a name. Then, use the `::part` selector in your CSS to apply styles, referencing the name you specified in the `part` attribute. This allows you to style specific parts of a shadow DOM element from outside the shadow tree. + +It is possible to append pseudo-classes such as `:hover`, `::before`, `::after` etc. to the `::part` selector. However, structural pseudo-classes that rely on tree information cannot be appended. + +### Example + + + + + +## Exportparts + +
+

A `part` is visible only to its direct parent

+

+ Parts are not accessible from any ancestors other than their direct parent. However, it is + possible to make a `part` globally available by defining it within the `exportparts` attribute + of the component. +

+
+ +The `exportparts` attribute allows specific parts of a shadow DOM element to be globally accessible, +meaning they can be styled from any ancestor outside the shadowtree. + +### Example + + + + diff --git a/packages/documentation/src/stories/guidelines/shadowdom-parts/shadowdom-parts.stories.ts b/packages/documentation/src/stories/guidelines/shadowdom-parts/shadowdom-parts.stories.ts new file mode 100644 index 0000000000..15d1e2f98a --- /dev/null +++ b/packages/documentation/src/stories/guidelines/shadowdom-parts/shadowdom-parts.stories.ts @@ -0,0 +1,13 @@ +import { StoryObj } from '@storybook/web-components'; +import { MetaExtended } from '@root/types'; + +const meta: MetaExtended = { + id: 'ba379b2d-689f-4003-8f6f-011af341549b', + title: 'Guidelines/Styling Shadowdom Parts', +}; + +export default meta; + +type Story = StoryObj; + +export const Default: Story = {}; From a1651e957b1756a0d19b0a568f5f8a8268a7369d Mon Sep 17 00:00:00 2001 From: Myrta Sakellariou Date: Thu, 9 Jan 2025 12:09:14 +0100 Subject: [PATCH 2/3] add changeset --- .changeset/twenty-fans-prove.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/twenty-fans-prove.md diff --git a/.changeset/twenty-fans-prove.md b/.changeset/twenty-fans-prove.md new file mode 100644 index 0000000000..4e2328ab29 --- /dev/null +++ b/.changeset/twenty-fans-prove.md @@ -0,0 +1,5 @@ +--- +'@swisspost/design-system-documentation': minor +--- + +Added guidelines page on styling shadowdom parts. From d6b2a098f80130b543396b5396211ab938fe2768 Mon Sep 17 00:00:00 2001 From: Myrta Sakellariou Date: Fri, 10 Jan 2025 18:10:19 +0100 Subject: [PATCH 3/3] review comments update --- .../shadowdom-parts/exportparts.sample.html | 8 ---- .../exportpartsSass.sample.scss | 10 ---- .../shadowdom-parts/partsSass.sample.scss | 6 +-- .../shadowdom-parts/pseudoParts.sample.html | 4 ++ .../pseudoPartsSass.sample.scss | 17 +++++++ .../shadowdom-parts/shadowdom-parts.docs.mdx | 46 ++++++++++--------- 6 files changed, 46 insertions(+), 45 deletions(-) delete mode 100644 packages/documentation/src/stories/guidelines/shadowdom-parts/exportparts.sample.html delete mode 100644 packages/documentation/src/stories/guidelines/shadowdom-parts/exportpartsSass.sample.scss create mode 100644 packages/documentation/src/stories/guidelines/shadowdom-parts/pseudoParts.sample.html create mode 100644 packages/documentation/src/stories/guidelines/shadowdom-parts/pseudoPartsSass.sample.scss diff --git a/packages/documentation/src/stories/guidelines/shadowdom-parts/exportparts.sample.html b/packages/documentation/src/stories/guidelines/shadowdom-parts/exportparts.sample.html deleted file mode 100644 index 5e6e42b253..0000000000 --- a/packages/documentation/src/stories/guidelines/shadowdom-parts/exportparts.sample.html +++ /dev/null @@ -1,8 +0,0 @@ - - - -
Header content
-
Footer content
- - - diff --git a/packages/documentation/src/stories/guidelines/shadowdom-parts/exportpartsSass.sample.scss b/packages/documentation/src/stories/guidelines/shadowdom-parts/exportpartsSass.sample.scss deleted file mode 100644 index 70c5eb48b9..0000000000 --- a/packages/documentation/src/stories/guidelines/shadowdom-parts/exportpartsSass.sample.scss +++ /dev/null @@ -1,10 +0,0 @@ -grandparent-element { - parent-element { - custom-element::part(header) { - font-weight: bold; - } - custom-element::part(footer) { - color: gray; - } - } -} diff --git a/packages/documentation/src/stories/guidelines/shadowdom-parts/partsSass.sample.scss b/packages/documentation/src/stories/guidelines/shadowdom-parts/partsSass.sample.scss index 3c5db1d13e..5692328030 100644 --- a/packages/documentation/src/stories/guidelines/shadowdom-parts/partsSass.sample.scss +++ b/packages/documentation/src/stories/guidelines/shadowdom-parts/partsSass.sample.scss @@ -2,10 +2,6 @@ custom-element::part(header) { font-weight: bold; } -custom-element::part(footer):hover { +custom-element::part(footer) { color: gray; } - -custom-element::part(footer)::after { - content: 'Added after pseudo-element'; -} diff --git a/packages/documentation/src/stories/guidelines/shadowdom-parts/pseudoParts.sample.html b/packages/documentation/src/stories/guidelines/shadowdom-parts/pseudoParts.sample.html new file mode 100644 index 0000000000..513f12164e --- /dev/null +++ b/packages/documentation/src/stories/guidelines/shadowdom-parts/pseudoParts.sample.html @@ -0,0 +1,4 @@ + +
Header content
+
Footer content
+ diff --git a/packages/documentation/src/stories/guidelines/shadowdom-parts/pseudoPartsSass.sample.scss b/packages/documentation/src/stories/guidelines/shadowdom-parts/pseudoPartsSass.sample.scss new file mode 100644 index 0000000000..39b546b8ab --- /dev/null +++ b/packages/documentation/src/stories/guidelines/shadowdom-parts/pseudoPartsSass.sample.scss @@ -0,0 +1,17 @@ +custom-element::part(header):hover { + text-decoration: underline; +} + +custom-element::part(footer):active { + color: darkgray; +} + +custom-element::part(header)::before { + content: '>> '; + color: red; +} + +custom-element::part(footer)::after { + content: ' <<'; + color: lightgray; +} diff --git a/packages/documentation/src/stories/guidelines/shadowdom-parts/shadowdom-parts.docs.mdx b/packages/documentation/src/stories/guidelines/shadowdom-parts/shadowdom-parts.docs.mdx index 8807bcd025..1016efdc56 100644 --- a/packages/documentation/src/stories/guidelines/shadowdom-parts/shadowdom-parts.docs.mdx +++ b/packages/documentation/src/stories/guidelines/shadowdom-parts/shadowdom-parts.docs.mdx @@ -2,22 +2,22 @@ import { Meta, Source } from '@storybook/blocks'; import * as ShadowdomPartsStories from './shadowdom-parts.stories'; import parts from './parts.sample.html?raw'; import partsSass from './partsSass.sample.scss?raw'; -import exportparts from './exportparts.sample.html?raw'; -import exportpartsSass from './exportpartsSass.sample.scss?raw'; +import pseudoParts from './pseudoParts.sample.html?raw'; +import pseudoPartsSass from './pseudoPartsSass.sample.scss?raw'; -# Styling Shadowdom Parts - -## Parts +# Styling Shadow DOM Parts
- The `part` attribute allows a shadow tree element to be exposed to its parent DOM. + Any web component element within the Shadow DOM that has a `part` attribute can be styled by its + direct parent DOM using the `::part` pseudo-element.
-To style an HTML shadow element, first set the `part` attribute on the element and assign it a name. Then, use the `::part` selector in your CSS to apply styles, referencing the name you specified in the `part` attribute. This allows you to style specific parts of a shadow DOM element from outside the shadow tree. +To style a shadow element with a `part` attribute: -It is possible to append pseudo-classes such as `:hover`, `::before`, `::after` etc. to the `::part` selector. However, structural pseudo-classes that rely on tree information cannot be appended. +- Identify the reference name assigned to the element's `part` attribute (e.g. `)`. +- Use the `::part` selector followed by the reference name (e.g. `::part(reference-name)`) to target and apply CSS styles. ### Example @@ -25,22 +25,24 @@ It is possible to append pseudo-classes such as `:hover`, `::before`, `::after` -## Exportparts - -
-

A `part` is visible only to its direct parent

-

- Parts are not accessible from any ancestors other than their direct parent. However, it is - possible to make a `part` globally available by defining it within the `exportparts` attribute - of the component. -

-
+## Pseudo-classes & pseudo-elements -The `exportparts` attribute allows specific parts of a shadow DOM element to be globally accessible, -meaning they can be styled from any ancestor outside the shadowtree. +The `::part` selector supports the addition of pseudo-classes such as `:hover` and pseudo-elements like `::before` and `::after`. This enables precise styling for states and structural modifications of shadow DOM elements. ### Example - + + + + +## Limitations + +### Structural pseudo-classes + +Structural pseudo-classes, such as `:nth-child` and `:first-child`, which depend on tree structure +and sibling relationships, cannot be applied to elements targeted by the `::part` selector. This restriction ensures that internal structure remains encapsulated and isn't exposed beyond the intended scope. + +### Nested `::part` selectors - +Each `part` must be directly exposed since styling cannot cascade through nested `::part` selectors. +The `::part selector` only targets the element associated with the specified part attribute. As a result, using nesting part selectors like `::part(header)::part(footer)` is not supported.