From cfc3f181a3c9fd879b981e1a386c2c1ef5e666bc Mon Sep 17 00:00:00 2001
From: Lea Verou <lea@verou.me>
Date: Wed, 23 Apr 2025 11:52:23 -0400
Subject: [PATCH] Fix broken demo, improve passthrough CSS (#879)

Fixes several issues for components using the `display: contents` technique:
- Introduce `--display` CSS property to make it possible to override internal display value of base part.
- Ensure `display: contents` is always applied with `!important` to avoid rendering glitches like the one here
- Ensure non-inherited custom properties are also inherited
- Ensure the `hidden` attribute still works.
---
 docs/docs/tokens/focus.md                    |  1 +
 src/components/button/button.css             |  8 ++-----
 src/components/button/button.ts              |  4 +++-
 src/components/details/details.css           |  5 +---
 src/components/details/details.ts            |  4 +++-
 src/components/progress-bar/progress-bar.css |  4 +---
 src/components/progress-bar/progress-bar.ts  |  4 +++-
 src/components/radio-button/radio-button.css |  7 +-----
 src/components/radio-button/radio-button.ts  |  4 +++-
 src/styles/shadow/passthrough.css            | 25 ++++++++++++++++++++
 10 files changed, 43 insertions(+), 23 deletions(-)
 create mode 100644 src/styles/shadow/passthrough.css

diff --git a/docs/docs/tokens/focus.md b/docs/docs/tokens/focus.md
index d1dbac7b0..f0550947f 100644
--- a/docs/docs/tokens/focus.md
+++ b/docs/docs/tokens/focus.md
@@ -27,6 +27,7 @@ See your theme's focus ring in action by navigating this form example with your
 <style>
   form > * + * {
     display: block;
+    --display: block;
     width: fit-content;
     margin-block-start: var(--wa-space-m);
   }
diff --git a/src/components/button/button.css b/src/components/button/button.css
index 6eb489774..b69975925 100644
--- a/src/components/button/button.css
+++ b/src/components/button/button.css
@@ -1,11 +1,7 @@
 :host {
-  display: contents;
-  position: relative;
-}
+  --display: inline-flex;
 
-:where([part~='base']) {
-  all: inherit;
-  display: inline-flex;
+  position: relative;
 }
 
 /*
diff --git a/src/components/button/button.ts b/src/components/button/button.ts
index 1ba684c61..75a5e59d0 100644
--- a/src/components/button/button.ts
+++ b/src/components/button/button.ts
@@ -7,6 +7,7 @@ import { MirrorValidator } from '../../internal/validators/mirror-validator.js';
 import { watch } from '../../internal/watch.js';
 import { WebAwesomeFormAssociatedElement } from '../../internal/webawesome-form-associated-element.js';
 import nativeStyles from '../../styles/native/button.css';
+import passthroughStyles from '../../styles/shadow/passthrough.css';
 import appearanceStyles from '../../styles/utilities/appearance.css';
 import sizeStyles from '../../styles/utilities/size.css';
 import variantStyles from '../../styles/utilities/variants.css';
@@ -39,6 +40,7 @@ import styles from './button.css';
  * @csspart caret - The button's caret icon, a `<wa-icon>` element.
  * @csspart spinner - The spinner that shows when the button is in the loading state.
  *
+ * @cssproperty --display - Set to `none` to hide the element, or any other valid `display` value to override the internal `display` value of the `base` part.
  * @cssproperty --background-color - The button's background color when the button is not being interacted with.
  * @cssproperty --background-color-active - The button's background color when active.
  * @cssproperty --background-color-hover - The button's background color on hover.
@@ -51,7 +53,7 @@ import styles from './button.css';
  */
 @customElement('wa-button')
 export default class WaButton extends WebAwesomeFormAssociatedElement {
-  static shadowStyle = [variantStyles, appearanceStyles, sizeStyles, nativeStyles, styles];
+  static shadowStyle = [passthroughStyles, variantStyles, appearanceStyles, sizeStyles, nativeStyles, styles];
   static rectProxy = 'button';
 
   static get validators() {
diff --git a/src/components/details/details.css b/src/components/details/details.css
index f3ef01529..f69eba797 100644
--- a/src/components/details/details.css
+++ b/src/components/details/details.css
@@ -1,13 +1,10 @@
 :host {
   --show-duration: 200ms;
   --hide-duration: 200ms;
-
-  display: contents !important;
+  --display: block;
 }
 
 details {
-  all: inherit;
-  display: block;
   overflow-anchor: none;
 }
 
diff --git a/src/components/details/details.ts b/src/components/details/details.ts
index 5c34adeed..e9e6d596f 100644
--- a/src/components/details/details.ts
+++ b/src/components/details/details.ts
@@ -9,6 +9,7 @@ import { getTargetElement, waitForEvent } from '../../internal/event.js';
 import { watch } from '../../internal/watch.js';
 import WebAwesomeElement from '../../internal/webawesome-element.js';
 import nativeStyles from '../../styles/native/details.css';
+import passthroughStyles from '../../styles/shadow/passthrough.css';
 import appearanceStyles from '../../styles/utilities/appearance.css';
 import { LocalizeController } from '../../utilities/localize.js';
 import '../icon/icon.js';
@@ -43,10 +44,11 @@ import styles from './details.css';
  * @cssproperty --spacing - The amount of space around and between the details' content. Expects a single value.
  * @cssproperty [--show-duration=200ms] - The show duration to use when applying built-in animation classes.
  * @cssproperty [--hide-duration=200ms] - The hide duration to use when applying built-in animation classes.
+ * @cssproperty --display - Set to `none` to hide the element, or any other valid `display` value to override the internal `display` value of the `base` part.
  */
 @customElement('wa-details')
 export default class WaDetails extends WebAwesomeElement {
-  static shadowStyle = [appearanceStyles, nativeStyles, styles];
+  static shadowStyle = [passthroughStyles, appearanceStyles, nativeStyles, styles];
 
   private detailsObserver: MutationObserver;
   private readonly localize = new LocalizeController(this);
diff --git a/src/components/progress-bar/progress-bar.css b/src/components/progress-bar/progress-bar.css
index 57c4bb211..748cec40d 100644
--- a/src/components/progress-bar/progress-bar.css
+++ b/src/components/progress-bar/progress-bar.css
@@ -1,7 +1,7 @@
 :host {
   --indicator-color: var(--wa-color-brand-fill-loud);
+  --display: flex;
 
-  display: contents;
   height: 1.25rem;
   border-radius: var(--wa-border-radius-pill);
   background-color: var(--wa-color-neutral-fill-normal);
@@ -9,8 +9,6 @@
 }
 
 .progress-bar {
-  all: inherit;
-  display: flex;
   position: relative;
   overflow: hidden;
 }
diff --git a/src/components/progress-bar/progress-bar.ts b/src/components/progress-bar/progress-bar.ts
index 5d3370d4c..9190ea97d 100644
--- a/src/components/progress-bar/progress-bar.ts
+++ b/src/components/progress-bar/progress-bar.ts
@@ -4,6 +4,7 @@ import { customElement, property } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 import { clamp } from '../../internal/math.js';
 import WebAwesomeElement from '../../internal/webawesome-element.js';
+import passthroughStyles from '../../styles/shadow/passthrough.css';
 import { LocalizeController } from '../../utilities/localize.js';
 import styles from './progress-bar.css';
 
@@ -20,10 +21,11 @@ import styles from './progress-bar.css';
  * @csspart label - The progress bar's label.
  *
  * @cssproperty --indicator-color - The color of the indicator.
+ * @cssproperty --display - Set to `none` to hide the element, or any other valid `display` value to override the internal `display` value of the `base` part.
  */
 @customElement('wa-progress-bar')
 export default class WaProgressBar extends WebAwesomeElement {
-  static shadowStyle = styles;
+  static shadowStyle = [passthroughStyles, styles];
   private readonly localize = new LocalizeController(this);
 
   /** The current progress as a percentage, 0 to 100. */
diff --git a/src/components/radio-button/radio-button.css b/src/components/radio-button/radio-button.css
index 1319aca64..321b450a9 100644
--- a/src/components/radio-button/radio-button.css
+++ b/src/components/radio-button/radio-button.css
@@ -1,10 +1,5 @@
 :host {
-  display: contents;
-}
-
-:where([part~='base']) {
-  all: inherit;
-  display: inline-flex;
+  --display: inline-flex;
 }
 
 .prefix,
diff --git a/src/components/radio-button/radio-button.ts b/src/components/radio-button/radio-button.ts
index b0582d026..7ce97efe3 100644
--- a/src/components/radio-button/radio-button.ts
+++ b/src/components/radio-button/radio-button.ts
@@ -6,6 +6,7 @@ import { HasSlotController } from '../../internal/slot.js';
 import { watch } from '../../internal/watch.js';
 import { WebAwesomeFormAssociatedElement } from '../../internal/webawesome-form-associated-element.js';
 import nativeStyles from '../../styles/native/button.css';
+import passthroughStyles from '../../styles/shadow/passthrough.css';
 import appearanceStyles from '../../styles/utilities/appearance.css';
 import sizeStyles from '../../styles/utilities/size.css';
 import variantStyles from '../../styles/utilities/variants.css';
@@ -45,10 +46,11 @@ import styles from './radio-button.css';
  * @csspart prefix - The container that wraps the prefix.
  * @csspart label - The container that wraps the radio button's label.
  * @csspart suffix - The container that wraps the suffix.
+ * @cssproperty --display - Set to `none` to hide the element, or any other valid `display` value to override the internal `display` value of the `base` part.
  */
 @customElement('wa-radio-button')
 export default class WaRadioButton extends WebAwesomeFormAssociatedElement {
-  static shadowStyle = [variantStyles, appearanceStyles, sizeStyles, nativeStyles, styles];
+  static shadowStyle = [passthroughStyles, variantStyles, appearanceStyles, sizeStyles, nativeStyles, styles];
   static rectProxy = 'input';
 
   private readonly hasSlotController = new HasSlotController(this, '[default]', 'prefix', 'suffix');
diff --git a/src/styles/shadow/passthrough.css b/src/styles/shadow/passthrough.css
new file mode 100644
index 000000000..f217a5514
--- /dev/null
+++ b/src/styles/shadow/passthrough.css
@@ -0,0 +1,25 @@
+/**
+ * Styles for elements that need to use display: contents on the host to enable styling with regular CSS properties (see #207, #259).
+ * To use, make sure that the element that needs to inherit properties set on the host has a part of base or a class of .styling-host.
+ */
+@property --display {
+  syntax: '*';
+  inherits: false;
+}
+
+:host {
+  display: contents !important;
+}
+
+:where([part~='base'], .styling-host) {
+  all: inherit;
+
+  /* Add any non-inherited custom properties here, as all: inherit won't cover them */
+  --display: inherit;
+
+  display: var(--display, inline);
+}
+
+:host([hidden]) {
+  display: none !important;
+}