Style Engine: Export public TypeScript types (#79079)

* 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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: ralucaStan

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

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
@@ -241,10 +258,29 @@ _Changelog_
 
 `6.1.0` Introduced in WordPress core.
 
+### GeneratedCSSRule
+
+A single CSS rule produced by `getCSSRules`.
+
 ### 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
@@ -276,6 +312,14 @@ _Returns_
 
 -   `StyleValue`: A CSS custom var value if the incoming style value is a preset value.
 
+### Style
+
+A block or theme style object accepted by `compileCSS` and `getCSSRules`.
+
+### StyleOptions
+
+Options for `compileCSS` and `getCSSRules`.
+
 <!-- END TOKEN(Autogenerated API docs) -->
 
 ## Glossary

packages/style-engine/src/index.ts

@@ -14,6 +14,21 @@ import type {
 } from './types';
 import { styleDefinitions } from './styles';
 
+/**
+ * A block or theme style object accepted by `compileCSS` and `getCSSRules`.
+ */
+export type { Style } from './types';
+
+/**
+ * Options for `compileCSS` and `getCSSRules`.
+ */
+export type { StyleOptions } from './types';
+
+/**
+ * A single CSS rule produced by `getCSSRules`.
+ */
+export type { GeneratedCSSRule } from './types';
+
 /**
  * Generates a stylesheet for a given style object and selector.
  *
@@ -22,6 +37,22 @@ import { styleDefinitions } from './styles';
  * @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 {
@@ -76,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(

packages/style-engine/src/types.ts

@@ -20,6 +20,12 @@ export interface BorderIndividualStyles< T extends BoxEdge > {
 	width?: CSSProperties[ `border${ Capitalize< T > }Width` ];
 }
 
+/**
+ * A style object — for example a block's `attributes.style` or the top-level
+ * 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?: {
 		backgroundImage?:
@@ -89,13 +95,22 @@ export interface CssRulesKeys {
 	individual: string;
 }
 
+/**
+ * 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 {
 	/**
 	 * CSS selector for the generated style.
 	 */
 	selector?: string;
 }
 
+/**
+ * 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;
 	value: string | unknown;