From 9472c6998029eaaa46b2c905d3c76de36bc8b8db Mon Sep 17 00:00:00 2001 From: Raluca Stan Date: Wed, 10 Jun 2026 11:28:41 +0200 Subject: [PATCH 1/4] Style engine: export public TypeScript types Re-export the `Style`, `StyleOptions`, and `GeneratedCSSRule` types from the package entry point so consumers of `@wordpress/style-engine` can type their usage of `compileCSS` and `getCSSRules`. These are the types that appear in the public function signatures; internal helper types remain unexported, matching the convention used by `rich-text` and `components`. Each exported type is documented at the export site so the autogenerated API docs render a description, and the README is regenerated accordingly. Co-Authored-By: Claude Opus 4.8 --- packages/style-engine/CHANGELOG.md | 4 ++++ packages/style-engine/README.md | 12 ++++++++++++ packages/style-engine/src/index.ts | 18 ++++++++++++++++++ packages/style-engine/src/types.ts | 12 ++++++++++++ 4 files changed, 46 insertions(+) diff --git a/packages/style-engine/CHANGELOG.md b/packages/style-engine/CHANGELOG.md index 8aa72b5d43efa0..1a29f4f0f26868 100644 --- a/packages/style-engine/CHANGELOG.md +++ b/packages/style-engine/CHANGELOG.md @@ -2,6 +2,10 @@ ## Unreleased +### Enhancements + +- Export the `Style`, `StyleOptions`, and `GeneratedCSSRule` TypeScript types so that consumers of the public API can type their usage of `compileCSS` and `getCSSRules`. + ## 2.48.0 (2026-06-10) ### Code Quality diff --git a/packages/style-engine/README.md b/packages/style-engine/README.md index a3e302fab4bb9a..001b7bcd1b1d79 100644 --- a/packages/style-engine/README.md +++ b/packages/style-engine/README.md @@ -241,6 +241,10 @@ _Changelog_ `6.1.0` Introduced in WordPress core. +### GeneratedCSSRule + +A single generated CSS rule, as returned by `getCSSRules`. + ### getCSSRules Returns a JSON representation of the generated CSS rules. @@ -276,6 +280,14 @@ _Returns_ - `StyleValue`: A CSS custom var value if the incoming style value is a preset value. +### Style + +A style object, for example the value of a block's `attributes.style` object or the top-level styles in `theme.json`. Passed to `compileCSS` and `getCSSRules` to generate CSS. + +### StyleOptions + +Options that adjust how styles are generated by `compileCSS` and `getCSSRules`. + ## Glossary diff --git a/packages/style-engine/src/index.ts b/packages/style-engine/src/index.ts index 102d5842e7a0be..d29fe061fc371b 100644 --- a/packages/style-engine/src/index.ts +++ b/packages/style-engine/src/index.ts @@ -14,6 +14,24 @@ import type { } from './types'; import { styleDefinitions } from './styles'; +/** + * A style object, for example the value of a block's `attributes.style` object + * or the top-level styles in `theme.json`. Passed to `compileCSS` and + * `getCSSRules` to generate CSS. + */ +export type { Style } from './types'; + +/** + * Options that adjust how styles are generated by `compileCSS` and + * `getCSSRules`. + */ +export type { StyleOptions } from './types'; + +/** + * A single generated CSS rule, as returned by `getCSSRules`. + */ +export type { GeneratedCSSRule } from './types'; + /** * Generates a stylesheet for a given style object and selector. * diff --git a/packages/style-engine/src/types.ts b/packages/style-engine/src/types.ts index e434053ba0820b..6c7fd47dac2dac 100644 --- a/packages/style-engine/src/types.ts +++ b/packages/style-engine/src/types.ts @@ -20,6 +20,11 @@ export interface BorderIndividualStyles< T extends BoxEdge > { width?: CSSProperties[ `border${ Capitalize< T > }Width` ]; } +/** + * A style object, for example the value of a block's `attributes.style` object + * or the top-level styles in `theme.json`. Passed to `compileCSS` and + * `getCSSRules` to generate CSS. + */ export interface Style { background?: { backgroundImage?: @@ -89,6 +94,10 @@ export interface CssRulesKeys { individual: string; } +/** + * Options that adjust how styles are generated by `compileCSS` and + * `getCSSRules`. + */ export interface StyleOptions { /** * CSS selector for the generated style. @@ -96,6 +105,9 @@ export interface StyleOptions { selector?: string; } +/** + * A single generated CSS rule, as returned by `getCSSRules`. + */ export interface GeneratedCSSRule { selector?: string; value: string | unknown; From d1f2120243f4eeb75ba3c93cabbda8f74c7c6fd7 Mon Sep 17 00:00:00 2001 From: Raluca Stan Date: Wed, 10 Jun 2026 13:07:50 +0200 Subject: [PATCH 2/4] Style engine: differentiate type doc comments per review feedback Use a concise summary at each export (which docgen renders into the README) and a fuller description at each type definition (which IDE tooling surfaces on hover), so the two are no longer identical. Matches the pattern used by the `rich-text` and `worker-threads` packages. Co-Authored-By: Claude Opus 4.8 --- packages/style-engine/README.md | 6 +++--- packages/style-engine/src/index.ts | 9 +++------ packages/style-engine/src/types.ts | 15 +++++++++------ 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/packages/style-engine/README.md b/packages/style-engine/README.md index 001b7bcd1b1d79..70d7e24558bdfa 100644 --- a/packages/style-engine/README.md +++ b/packages/style-engine/README.md @@ -243,7 +243,7 @@ _Changelog_ ### GeneratedCSSRule -A single generated CSS rule, as returned by `getCSSRules`. +A single CSS rule produced by `getCSSRules`. ### getCSSRules @@ -282,11 +282,11 @@ _Returns_ ### Style -A style object, for example the value of a block's `attributes.style` object or the top-level styles in `theme.json`. Passed to `compileCSS` and `getCSSRules` to generate CSS. +A block or theme style object accepted by `compileCSS` and `getCSSRules`. ### StyleOptions -Options that adjust how styles are generated by `compileCSS` and `getCSSRules`. +Options for `compileCSS` and `getCSSRules`. diff --git a/packages/style-engine/src/index.ts b/packages/style-engine/src/index.ts index d29fe061fc371b..66354fc421bdf0 100644 --- a/packages/style-engine/src/index.ts +++ b/packages/style-engine/src/index.ts @@ -15,20 +15,17 @@ import type { import { styleDefinitions } from './styles'; /** - * A style object, for example the value of a block's `attributes.style` object - * or the top-level styles in `theme.json`. Passed to `compileCSS` and - * `getCSSRules` to generate CSS. + * A block or theme style object accepted by `compileCSS` and `getCSSRules`. */ export type { Style } from './types'; /** - * Options that adjust how styles are generated by `compileCSS` and - * `getCSSRules`. + * Options for `compileCSS` and `getCSSRules`. */ export type { StyleOptions } from './types'; /** - * A single generated CSS rule, as returned by `getCSSRules`. + * A single CSS rule produced by `getCSSRules`. */ export type { GeneratedCSSRule } from './types'; diff --git a/packages/style-engine/src/types.ts b/packages/style-engine/src/types.ts index 6c7fd47dac2dac..bbe7acb4fb4b92 100644 --- a/packages/style-engine/src/types.ts +++ b/packages/style-engine/src/types.ts @@ -21,9 +21,10 @@ export interface BorderIndividualStyles< T extends BoxEdge > { } /** - * A style object, for example the value of a block's `attributes.style` object - * or the top-level styles in `theme.json`. Passed to `compileCSS` and - * `getCSSRules` to generate CSS. + * A style object — for example a block's `attributes.style` or the top-level + * styles in `theme.json`. Describes borders, spacing, typography, colors, + * dimensions and element styles, and is the input `compileCSS` and + * `getCSSRules` turn into CSS. */ export interface Style { background?: { @@ -95,8 +96,8 @@ export interface CssRulesKeys { } /** - * Options that adjust how styles are generated by `compileCSS` and - * `getCSSRules`. + * Options that adjust how styles are generated — notably the CSS `selector` to + * scope the output to. With no selector, declarations are returned inline. */ export interface StyleOptions { /** @@ -106,7 +107,9 @@ export interface StyleOptions { } /** - * A single generated CSS rule, as returned by `getCSSRules`. + * A single generated CSS rule: an optional `selector`, the `value`, and the + * `key` in React/JS style-attribute format (e.g. `paddingTop` rather than + * `padding-top`). */ export interface GeneratedCSSRule { selector?: string; From 4fb5a2761e88f70b688361a10e210c3429f0376c Mon Sep 17 00:00:00 2001 From: Raluca Stan Date: Wed, 10 Jun 2026 13:22:31 +0200 Subject: [PATCH 3/4] Style engine: include backgrounds in the Style type description The `Style` interface gained a top-level `background` key; reword its definition comment to mention backgrounds and phrase the property list as non-exhaustive ("such as") so it stays accurate as the type evolves. Co-Authored-By: Claude Opus 4.8 --- packages/style-engine/src/types.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/style-engine/src/types.ts b/packages/style-engine/src/types.ts index bbe7acb4fb4b92..a5d16b2b8f88eb 100644 --- a/packages/style-engine/src/types.ts +++ b/packages/style-engine/src/types.ts @@ -22,9 +22,9 @@ export interface BorderIndividualStyles< T extends BoxEdge > { /** * A style object — for example a block's `attributes.style` or the top-level - * styles in `theme.json`. Describes borders, spacing, typography, colors, - * dimensions and element styles, and is the input `compileCSS` and - * `getCSSRules` turn into CSS. + * styles in `theme.json`. Groups visual style properties such as color, + * typography, spacing, dimensions, borders, backgrounds and element styles, + * and is the input `compileCSS` and `getCSSRules` turn into CSS. */ export interface Style { background?: { From d5ba4038a3e67354046d60a91937467b39148672 Mon Sep 17 00:00:00 2001 From: Raluca Stan Date: Wed, 10 Jun 2026 13:37:04 +0200 Subject: [PATCH 4/4] Style engine: add @example usage to compileCSS and getCSSRules Document both functions with an @example JSDoc block so docgen renders a Usage example into the README's autogenerated API section. This makes the exported Style, StyleOptions and GeneratedCSSRule types learnable in context (selector vs. inline output, structured rules), with the example colocated with the code as a single source of truth rather than hand-written README prose. Outputs were verified against the package's behaviour. Co-Authored-By: Claude Opus 4.8 --- packages/style-engine/README.md | 32 ++++++++++++++++++++++++++++++ packages/style-engine/src/index.ts | 30 ++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) diff --git a/packages/style-engine/README.md b/packages/style-engine/README.md index 70d7e24558bdfa..14a964402f0c7b 100644 --- a/packages/style-engine/README.md +++ b/packages/style-engine/README.md @@ -228,6 +228,23 @@ _This package assumes that your code will run in an **ES2015+** environment. If Generates a stylesheet for a given style object and selector. +_Usage_ + +```js +import { compileCSS } from '@wordpress/style-engine'; + +// With a selector, a full stylesheet string is returned. +compileCSS( + { spacing: { padding: '10px', margin: '12px' } }, + { selector: '.my-block' } +); +// '.my-block { margin: 12px; padding: 10px; }' + +// Without a selector, inline declarations are returned. +compileCSS( { spacing: { padding: '10px', margin: '12px' } } ); +// 'margin: 12px; padding: 10px;' +``` + _Parameters_ - _style_ `Style`: Style object, for example, the value of a block's attributes.style object or the top level styles in theme.json @@ -249,6 +266,21 @@ A single CSS rule produced by `getCSSRules`. Returns a JSON representation of the generated CSS rules. +_Usage_ + +```js +import { getCSSRules } from '@wordpress/style-engine'; + +getCSSRules( + { spacing: { padding: '10px', margin: '12px' } }, + { selector: '.my-block' } +); +// [ +// { selector: '.my-block', key: 'margin', value: '12px' }, +// { selector: '.my-block', key: 'padding', value: '10px' }, +// ] +``` + _Parameters_ - _style_ `Style`: Style object, for example, the value of a block's attributes.style object or the top level styles in theme.json diff --git a/packages/style-engine/src/index.ts b/packages/style-engine/src/index.ts index 66354fc421bdf0..7468257ac855a8 100644 --- a/packages/style-engine/src/index.ts +++ b/packages/style-engine/src/index.ts @@ -37,6 +37,22 @@ export type { GeneratedCSSRule } from './types'; * @param style Style object, for example, the value of a block's attributes.style object or the top level styles in theme.json * @param options Options object with settings to adjust how the styles are generated. * + * @example + * ```js + * import { compileCSS } from '@wordpress/style-engine'; + * + * // With a selector, a full stylesheet string is returned. + * compileCSS( + * { spacing: { padding: '10px', margin: '12px' } }, + * { selector: '.my-block' } + * ); + * // '.my-block { margin: 12px; padding: 10px; }' + * + * // Without a selector, inline declarations are returned. + * compileCSS( { spacing: { padding: '10px', margin: '12px' } } ); + * // 'margin: 12px; padding: 10px;' + * ``` + * * @return A generated stylesheet or inline style declarations. */ export function compileCSS( style: Style, options: StyleOptions = {} ): string { @@ -91,6 +107,20 @@ export function compileCSS( style: Style, options: StyleOptions = {} ): string { * @param style Style object, for example, the value of a block's attributes.style object or the top level styles in theme.json * @param options Options object with settings to adjust how the styles are generated. * + * @example + * ```js + * import { getCSSRules } from '@wordpress/style-engine'; + * + * getCSSRules( + * { spacing: { padding: '10px', margin: '12px' } }, + * { selector: '.my-block' } + * ); + * // [ + * // { selector: '.my-block', key: 'margin', value: '12px' }, + * // { selector: '.my-block', key: 'padding', value: '10px' }, + * // ] + * ``` + * * @return A collection of objects containing the selector, if any, the CSS property key (camelcase) and parsed CSS value. */ export function getCSSRules(