From f1541ceead666beb61c9768a43458f3733cbc693 Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Thu, 5 Mar 2026 03:16:00 +0900
Subject: [PATCH 1/2] Storybook: Deduplicate injected package stylesheets

Extract shared ref-counted style injection into useSharedStyle hook,
used by both WithRTL and WithGlobalCSS decorators.
---
 .../decorators/utils/use-shared-style.ts      | 57 +++++++++++++++++++
 storybook/decorators/with-global-css.jsx      | 12 ++--
 storybook/decorators/with-rtl.jsx             | 41 ++++++-------
 3 files changed, 80 insertions(+), 30 deletions(-)
 create mode 100644 storybook/decorators/utils/use-shared-style.ts

diff --git a/storybook/decorators/utils/use-shared-style.ts b/storybook/decorators/utils/use-shared-style.ts
new file mode 100644
index 00000000000000..297d4b0566e8fc
--- /dev/null
+++ b/storybook/decorators/utils/use-shared-style.ts
@@ -0,0 +1,57 @@
+import { useLayoutEffect } from '@wordpress/element';
+
+interface StyleEntry {
+	element: HTMLStyleElement;
+	refCount: number;
+}
+
+const styleRefs = new Map< string, StyleEntry >();
+
+/**
+ * Injects a `<style>` element into the document head, ref-counted by `key`.
+ *
+ * When multiple Storybook story instances need the same stylesheet (e.g. on
+ * the Docs tab where several stories render simultaneously), this hook ensures
+ * only a single `<style>` element is created. It is removed from the DOM when
+ * the last consumer unmounts.
+ *
+ * @param options
+ * @param options.key     A unique identifier for the stylesheet. Callers with
+ *                        the same key share one `<style>` element. Pass an
+ *                        empty string to skip injection.
+ * @param options.cssText The CSS text to inject. Pass an empty string to skip
+ *                        injection.
+ */
+export function useSharedStyle( {
+	key,
+	cssText,
+}: {
+	key: string;
+	cssText: string;
+} ): void {
+	useLayoutEffect( () => {
+		if ( ! key || ! cssText ) {
+			return;
+		}
+
+		let entry = styleRefs.get( key );
+
+		if ( entry ) {
+			entry.refCount++;
+		} else {
+			const style = document.createElement( 'style' );
+			style.textContent = cssText;
+			document.head.appendChild( style );
+			entry = { element: style, refCount: 1 };
+			styleRefs.set( key, entry );
+		}
+
+		return () => {
+			entry.refCount--;
+			if ( entry.refCount === 0 ) {
+				entry.element.remove();
+				styleRefs.delete( key );
+			}
+		};
+	}, [ key, cssText ] );
+}
diff --git a/storybook/decorators/with-global-css.jsx b/storybook/decorators/with-global-css.jsx
index d053c03c7b1a5e..f59ea3335b0ddb 100644
--- a/storybook/decorators/with-global-css.jsx
+++ b/storybook/decorators/with-global-css.jsx
@@ -1,7 +1,7 @@
 import clsx from 'clsx';
-import { useEffect } from '@wordpress/element';
 import basicStyles from '../global-basic.scss?inline';
 import wordPressStyles from '../global-wordpress.scss?inline';
+import { useSharedStyle } from './utils/use-shared-style';
 
 /**
  * A Storybook decorator to inject global CSS.
@@ -42,12 +42,10 @@ export const WithGlobalCSS = ( Story, context ) => {
 	const { lazyStyles, externalStyles, classes } =
 		config[ context.globals.css ];
 
-	useEffect( () => {
-		const style = document.createElement( 'style' );
-		style.textContent = lazyStyles.join( '\n' );
-		document.head.appendChild( style );
-		return () => document.head.removeChild( style );
-	}, [ context.globals.css, lazyStyles ] );
+	useSharedStyle( {
+		key: 'global:' + context.globals.css,
+		cssText: lazyStyles.join( '\n' ),
+	} );
 
 	return (
 		<div className={ clsx( classes ) }>
diff --git a/storybook/decorators/with-rtl.jsx b/storybook/decorators/with-rtl.jsx
index ae1e594c4c38b9..1efbaaaa898529 100644
--- a/storybook/decorators/with-rtl.jsx
+++ b/storybook/decorators/with-rtl.jsx
@@ -2,17 +2,13 @@
  * WordPress dependencies
  */
 import { addFilter, removeFilter } from '@wordpress/hooks';
-import {
-	useEffect,
-	useLayoutEffect,
-	useRef,
-	useState,
-} from '@wordpress/element';
+import { useEffect, useRef, useState } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
 import CONFIG from '../package-styles/config';
+import { useSharedStyle } from './utils/use-shared-style';
 
 export const WithRTL = ( Story, context ) => {
 	const [ rerenderKey, setRerenderKey ] = useState( 0 );
@@ -41,23 +37,22 @@ export const WithRTL = ( Story, context ) => {
 		return () => removeFilter( 'i18n.gettext_with_context', 'storybook' );
 	}, [ context.globals.direction ] );
 
-	useLayoutEffect( () => {
-		const stylesToUse = [];
-
-		CONFIG.forEach( ( item ) => {
-			if ( item.componentIdMatcher.test( context.componentId ) ) {
-				stylesToUse.push( ...item[ context.globals.direction ] );
-			}
-		} );
-
-		const style = document.createElement( 'style' );
-		style.textContent = stylesToUse.join( '\n' );
-		document.head.appendChild( style );
-
-		return () => {
-			document.head.removeChild( style );
-		};
-	}, [ context.componentId, context.globals.direction ] );
+	const matchedIndices = [];
+	const stylesToUse = [];
+
+	CONFIG.forEach( ( item, index ) => {
+		if ( item.componentIdMatcher.test( context.componentId ) ) {
+			matchedIndices.push( index );
+			stylesToUse.push( ...item[ context.globals.direction ] );
+		}
+	} );
+
+	useSharedStyle( {
+		key: matchedIndices.length
+			? matchedIndices.join( ',' ) + ':' + context.globals.direction
+			: '',
+		cssText: stylesToUse.join( '\n' ),
+	} );
 
 	return (
 		<div ref={ ref } key={ rerenderKey }>

From 88aba00e7751c320089cd10fac589d420f465103 Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Fri, 6 Mar 2026 01:34:56 +0900
Subject: [PATCH 2/2] Simplify useSharedStyle API

---
 .../decorators/utils/use-shared-style.ts      | 36 +++++++------------
 storybook/decorators/with-global-css.jsx      |  5 +--
 storybook/decorators/with-rtl.jsx             | 11 ++----
 3 files changed, 15 insertions(+), 37 deletions(-)

diff --git a/storybook/decorators/utils/use-shared-style.ts b/storybook/decorators/utils/use-shared-style.ts
index 297d4b0566e8fc..bbde04b5a1c532 100644
--- a/storybook/decorators/utils/use-shared-style.ts
+++ b/storybook/decorators/utils/use-shared-style.ts
@@ -8,33 +8,21 @@ interface StyleEntry {
 const styleRefs = new Map< string, StyleEntry >();
 
 /**
- * Injects a `<style>` element into the document head, ref-counted by `key`.
+ * Injects a `<style>` element into the document head, ref-counted so that
+ * multiple consumers sharing the same CSS text use a single `<style>` element
+ * (e.g. on the Docs tab where several stories render simultaneously). The
+ * element is removed from the DOM when the last consumer unmounts.
  *
- * When multiple Storybook story instances need the same stylesheet (e.g. on
- * the Docs tab where several stories render simultaneously), this hook ensures
- * only a single `<style>` element is created. It is removed from the DOM when
- * the last consumer unmounts.
- *
- * @param options
- * @param options.key     A unique identifier for the stylesheet. Callers with
- *                        the same key share one `<style>` element. Pass an
- *                        empty string to skip injection.
- * @param options.cssText The CSS text to inject. Pass an empty string to skip
- *                        injection.
+ * @param cssText The CSS text to inject. Pass an empty string to skip
+ *                injection.
  */
-export function useSharedStyle( {
-	key,
-	cssText,
-}: {
-	key: string;
-	cssText: string;
-} ): void {
+export function useSharedStyle( cssText: string ): void {
 	useLayoutEffect( () => {
-		if ( ! key || ! cssText ) {
+		if ( ! cssText ) {
 			return;
 		}
 
-		let entry = styleRefs.get( key );
+		let entry = styleRefs.get( cssText );
 
 		if ( entry ) {
 			entry.refCount++;
@@ -43,15 +31,15 @@ export function useSharedStyle( {
 			style.textContent = cssText;
 			document.head.appendChild( style );
 			entry = { element: style, refCount: 1 };
-			styleRefs.set( key, entry );
+			styleRefs.set( cssText, entry );
 		}
 
 		return () => {
 			entry.refCount--;
 			if ( entry.refCount === 0 ) {
 				entry.element.remove();
-				styleRefs.delete( key );
+				styleRefs.delete( cssText );
 			}
 		};
-	}, [ key, cssText ] );
+	}, [ cssText ] );
 }
diff --git a/storybook/decorators/with-global-css.jsx b/storybook/decorators/with-global-css.jsx
index f59ea3335b0ddb..c4c3d158ff0e35 100644
--- a/storybook/decorators/with-global-css.jsx
+++ b/storybook/decorators/with-global-css.jsx
@@ -42,10 +42,7 @@ export const WithGlobalCSS = ( Story, context ) => {
 	const { lazyStyles, externalStyles, classes } =
 		config[ context.globals.css ];
 
-	useSharedStyle( {
-		key: 'global:' + context.globals.css,
-		cssText: lazyStyles.join( '\n' ),
-	} );
+	useSharedStyle( lazyStyles.join( '\n' ) );
 
 	return (
 		<div className={ clsx( classes ) }>
diff --git a/storybook/decorators/with-rtl.jsx b/storybook/decorators/with-rtl.jsx
index 1efbaaaa898529..7b143543efca00 100644
--- a/storybook/decorators/with-rtl.jsx
+++ b/storybook/decorators/with-rtl.jsx
@@ -37,22 +37,15 @@ export const WithRTL = ( Story, context ) => {
 		return () => removeFilter( 'i18n.gettext_with_context', 'storybook' );
 	}, [ context.globals.direction ] );
 
-	const matchedIndices = [];
 	const stylesToUse = [];
 
-	CONFIG.forEach( ( item, index ) => {
+	CONFIG.forEach( ( item ) => {
 		if ( item.componentIdMatcher.test( context.componentId ) ) {
-			matchedIndices.push( index );
 			stylesToUse.push( ...item[ context.globals.direction ] );
 		}
 	} );
 
-	useSharedStyle( {
-		key: matchedIndices.length
-			? matchedIndices.join( ',' ) + ':' + context.globals.direction
-			: '',
-		cssText: stylesToUse.join( '\n' ),
-	} );
+	useSharedStyle( stylesToUse.join( '\n' ) );
 
 	return (
 		<div ref={ ref } key={ rerenderKey }>