From 4cf4ec3f0d35bf9dabfb8f33c976e3626085e36d Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Tue, 23 Jul 2024 12:18:56 -0500 Subject: [PATCH] JSON Schema Docgen Rework (#63868) Co-authored-by: ajlende Co-authored-by: scruffian Co-authored-by: t-hamano --- bin/api-docs/gen-theme-reference.mjs | 422 +++++++++--------- .../theme-json-reference/theme-json-living.md | 312 ++++++------- 2 files changed, 377 insertions(+), 357 deletions(-) diff --git a/bin/api-docs/gen-theme-reference.mjs b/bin/api-docs/gen-theme-reference.mjs index a447948d4593c4..6dc7791e288b9e 100644 --- a/bin/api-docs/gen-theme-reference.mjs +++ b/bin/api-docs/gen-theme-reference.mjs @@ -7,38 +7,31 @@ /** * External dependencies */ -import path from 'path'; -import fs from 'fs'; -import url from 'url'; +import fs from 'node:fs/promises'; import $RefParser from '@apidevtools/json-schema-ref-parser'; -const __dirname = path.dirname( url.fileURLToPath( import.meta.url ) ); - /** - * Path to root project directory. - * - * @type {string} + * @typedef {import('@apidevtools/json-schema-ref-parser').JSONSchema} JSONSchema */ -const ROOT_DIR = path.resolve( __dirname, '../..' ); /** * Path to theme json schema file. * - * @type {string} + * @type {URL} */ -const THEME_JSON_SCHEMA_FILE = path.resolve( - ROOT_DIR, - path.join( 'schemas', 'json', 'theme.json' ) +const THEME_JSON_SCHEMA_URL = new URL( + '../../schemas/json/theme.json', + import.meta.url ); /** * Path to docs file. * - * @type {string} + * @type {URL} */ -const THEME_JSON_REF_DOC = path.resolve( - ROOT_DIR, - 'docs/reference-guides/theme-json-reference/theme-json-living.md' +const REFERENCE_DOC_URL = new URL( + '../../docs/reference-guides/theme-json-reference/theme-json-living.md', + import.meta.url ); /** @@ -56,229 +49,248 @@ const START_TOKEN = ''; const END_TOKEN = ''; /** - * Regular expression using tokens for matching in doc file. - * Note: `.` does not match new lines, so [^] is used. - * - * @type {RegExp} + * @typedef {(schema: JSONSchema) => boolean} PredicateFunction */ -const TOKEN_PATTERN = new RegExp( START_TOKEN + '[^]*' + END_TOKEN ); -const themejson = await $RefParser.dereference( THEME_JSON_SCHEMA_FILE ); +/** + * @typedef {(schema: JSONSchema) => string} SerializerFunction + */ /** - * Convert object keys to an array. - * Gracefully handles non-object values. + * Create a serializer function for a type. Supports merging one level of anyOf and oneOf subschemas. * - * @param {*} maybeObject - * @return {Array} Object keys + * @see {@link https://json-schema.org/understanding-json-schema/reference/combining.html} + * + * @param {PredicateFunction} predicate Type predicate function to match a type. + * @param {SerializerFunction} serializer Serializer function to format a type. + * @return {SerializerFunction} Serializer function for the give type. */ -const keys = ( maybeObject ) => { - if ( typeof maybeObject !== 'object' ) { - return []; - } - return Object.keys( maybeObject ); -}; +function createSerializer( predicate, serializer ) { + return ( schema ) => { + const schemas = predicate( schema ) + ? [ schema ] + : schema.anyOf || schema.oneOf || []; + const formatted = schemas.filter( predicate ).map( serializer ); + return [ ...new Set( formatted ) ].join( ', ' ); + }; +} /** - * Convert settings properties to markup. + * Serialize primitive types. * - * @param {Object} struct - * @return {string} markup + * @type {SerializerFunction} */ -const getSettingsPropertiesMarkup = ( struct ) => { - if ( ! ( 'properties' in struct ) ) { - return ''; - } - const props = struct.properties; - const ks = keys( props ); - if ( ks.length < 1 ) { - return ''; - } - - let markup = '| Property | Type | Default | Props |\n'; - markup += '| --- | --- | --- |--- |\n'; - ks.forEach( ( key ) => { - const def = 'default' in props[ key ] ? props[ key ].default : ''; - let type = props[ key ].type || ''; - let ps = - props[ key ].type === 'array' - ? keys( props[ key ].items.properties ).sort().join( ', ' ) - : ''; - - /* - * Handle`oneOf` type definitions - extract the type and properties. - * See: https://json-schema.org/understanding-json-schema/reference/combining#oneOf - */ - if ( props[ key ].oneOf && Array.isArray( props[ key ].oneOf ) ) { - if ( ! type ) { - type = props[ key ].oneOf - .map( ( item ) => item.type ) - .join( ', ' ); - } - - if ( ! ps ) { - ps = props[ key ].oneOf - .map( ( item ) => - item?.type === 'object' && item?.properties - ? '_{' + - keys( item.properties ).sort().join( ', ' ) + - '}_' - : '' - ) - .join( ' ' ); - } - } - - markup += `| ${ key } | ${ type } | ${ def } | ${ ps } |\n`; - } ); - - return markup; -}; +const serializePrimitiveTypes = createSerializer( + ( schema ) => + schema.type && ! [ 'object', 'array' ].includes( schema.type ), + ( schema ) => `\`${ schema.type }\`` +); /** - * Convert style properties to markup. + * Serialize object types. * - * @param {Object} struct - * @return {string} markup + * @type {SerializerFunction} */ -const getStylePropertiesMarkup = ( struct ) => { - if ( ! ( 'properties' in struct ) ) { - return ''; - } - const props = struct.properties; - const ks = keys( props ); - if ( ks.length < 1 ) { - return ''; - } - - let markup = '| Property | Type | Props |\n'; - markup += '| --- | --- |--- |\n'; - ks.forEach( ( key ) => { - const ps = - props[ key ].type === 'object' - ? keys( props[ key ].properties ).sort().join( ', ' ) - : ''; - const type = formatType( props[ key ] ); - markup += `| ${ key } | ${ type } | ${ ps } |\n`; - } ); - - return markup; -}; +const serializeObjectTypes = createSerializer( + ( schema ) => schema.properties, + ( schema ) => `\`{ ${ Object.keys( schema.properties ).join( ', ' ) } }\`` +); /** - * Parses a section for description and properties and - * returns a marked up version. + * Serialize object array types. * - * @param {string} title - * @param {Object} data - * @param {string} type settings|style - * @return {string} markup + * @type {SerializerFunction} */ -const getSectionMarkup = ( title, data, type ) => { - const markupFn = - type === 'settings' - ? getSettingsPropertiesMarkup - : getStylePropertiesMarkup; - - return ` -### ${ title } - -${ data.description } - -${ markupFn( data ) } ---- -`; -}; - -let autogen = ''; +const serializeObjectArrayTypes = createSerializer( + ( schema ) => schema.items && schema.items.properties, + ( schema ) => + `\`[ { ${ Object.keys( schema.items.properties ).join( ', ' ) } } ]\`` +); /** - * Format list of types. + * Serialize primitive array types. * - * @param {Object} prop - * @return {string} type + * @type {SerializerFunction} */ -const formatType = ( prop ) => { - let type = prop.type || ''; +const serializePrimitiveArrayTypes = createSerializer( + ( schema ) => + schema.items && + schema.items.type && + ! [ 'object', 'array' ].includes( schema.items.type ), + ( schema ) => `\`[ ${ schema.items.type } ]\`` +); - if ( prop.hasOwnProperty( 'anyOf' ) || prop.hasOwnProperty( 'oneOf' ) ) { - const propTypes = prop.anyOf || prop.oneOf; - const types = []; +/** + * Generate types from schema. + * + * @param {JSONSchema} schema JSON schema + * @return {string} serialized types + */ +function generateTypes( schema ) { + return [ + serializePrimitiveTypes( schema ), + serializeObjectTypes( schema ), + serializePrimitiveArrayTypes( schema ), + serializeObjectArrayTypes( schema ), + ] + .filter( Boolean ) + .join( ', ' ); +} - propTypes.forEach( ( item ) => { - if ( item.type ) { - types.push( item.type ); +/** + * Generate documentation from theme.json schema. + * + * @param {JSONSchema} themeJson theme.json JSON schema + * @return {string} generated documentation + */ +function generateDocs( themeJson ) { + /** Markdown content. */ + let md = ''; + + /* --------------- * + * Settings * + * --------------- */ + md += '## settings\n\n'; + md += `${ themeJson.properties.settings.description }\n\n`; + const settings = [ + // Top-level only properties. + ...Object.entries( themeJson.properties.settings.allOf[ 1 ].properties ) + .filter( ( [ property ] ) => property !== 'blocks' ) + .map( ( [ property, subschema ] ) => [ + property, + { + ...subschema, + description: `${ subschema.description }\n\n**Note:** Top-level only property. Not available in blocks.`, + }, + ] ), + // Top-level and blocks properties. + ...themeJson.properties.settings.allOf[ 0 ].allOf.flatMap( + ( subschema ) => Object.entries( subschema.properties ) + ), + ]; + for ( const [ section, schema ] of settings ) { + md += `### ${ section }\n\n`; + md += `${ schema.description }\n\n`; + if ( schema.properties ) { + md += '| Property | Description | Type | Default |\n'; + md += '| -------- | ----------- | ---- | ------- |\n'; + const properties = Object.entries( schema.properties ); + for ( const [ property, subschema ] of properties ) { + const description = + subschema.description?.split( '\n', 1 )[ 0 ] ?? ''; + const types = generateTypes( subschema ); + const defaultValue = + 'default' in subschema + ? `\`${ JSON.stringify( subschema.default ) }\`` + : ''; + md += `| ${ property } | ${ description } | ${ types } | ${ defaultValue } |\n`; } - } ); - - type = [ ...new Set( types ) ].join( ', ' ); + md += '\n'; + } + md += `---\n\n`; } - return type; -}; + /* --------------- * + * Styles * + * --------------- */ + md += '## styles\n\n'; + md += `${ themeJson.properties.styles.description }\n\n`; + const styles = Object.entries( + themeJson.properties.styles.allOf[ 0 ].properties + ); + for ( const [ section, schema ] of styles ) { + md += `### ${ section }\n\n`; + md += `${ schema.description }\n\n`; + if ( schema.properties ) { + md += '| Property | Description | Type |\n'; + md += '| -------- | ----------- | ---- |\n'; + const properties = Object.entries( schema.properties ); + for ( const [ property, subschema ] of properties ) { + // Assuming that the first line of a description is a summary. + const description = + subschema.description?.split( '\n', 1 )[ 0 ] ?? ''; + const types = generateTypes( subschema ); + md += `| ${ property } | ${ description } | ${ types } |\n`; + } + md += '\n'; + } + md += `---\n\n`; + } -// Settings -const settings = Object.entries( themejson.definitions ) - .filter( ( [ settingsKey ] ) => - /^settings\w+Properties$/.test( settingsKey ) - ) - .reduce( - ( settingsObj, [ , { properties } ] ) => - Object.assign( settingsObj, properties ), - {} + /* --------------- * + * customTemplates * + * --------------- */ + md += '## customTemplates\n\n'; + md += `${ themeJson.properties.customTemplates.description }\n\n`; + md += '| Property | Description | Type |\n'; + md += '| -------- | ----------- | ---- |\n'; + const customTemplatesProperties = Object.entries( + themeJson.properties.customTemplates.items.properties ); -const settingSections = keys( settings ); -autogen += '## Settings' + '\n\n'; -settingSections.forEach( ( section ) => { - autogen += getSectionMarkup( section, settings[ section ], 'settings' ); -} ); + for ( const [ property, subschema ] of customTemplatesProperties ) { + const { description } = subschema; + const types = generateTypes( subschema ); + md += `| ${ property } | ${ description } | ${ types } |\n`; + } + md += '\n'; + + /* --------------- * + * templateParts * + * --------------- */ + md += '## templateParts\n\n'; + md += `${ themeJson.properties.templateParts.description }\n\n`; + md += '| Property | Description | Type |\n'; + md += '| -------- | ----------- | ---- |\n'; + const templatePartsProperties = Object.entries( + themeJson.properties.templateParts.items.properties + ); + for ( const [ property, subschema ] of templatePartsProperties ) { + const { description } = subschema; + const types = generateTypes( subschema ); + md += `| ${ property } | ${ description } | ${ types } |\n`; + } + md += '\n'; -// Styles -const styles = themejson.definitions.stylesProperties.properties; -const styleSections = keys( styles ); -autogen += '## Styles' + '\n\n'; -styleSections.forEach( ( section ) => { - autogen += getSectionMarkup( section, styles[ section ], 'styles' ); -} ); + /* --------------- * + * patterns * + * --------------- */ + md += '## patterns\n\n'; + md += themeJson.properties.patterns.description + '\n\n'; + md += `Type: ${ generateTypes( themeJson.properties.patterns ) }.\n`; -const templateTableGeneration = ( themeJson, context ) => { - let content = ''; - content += '## ' + context + '\n\n'; - content += themeJson.properties[ context ].description + '\n\n'; - content += - 'Type: `' + themeJson.properties[ context ].items.type + '`.\n\n'; - content += '| Property | Description | Type |\n'; - content += '| --- | --- | --- |\n'; - keys( themeJson.properties[ context ].items.properties ).forEach( - ( key ) => { - content += `| ${ key } | ${ themeJson.properties[ context ].items.properties[ key ].description } | ${ themeJson.properties[ context ].items.properties[ key ].type } |\n`; + return md; +} + +/** + * Main function. + */ +async function main() { + const themeJson = await $RefParser.dereference( + THEME_JSON_SCHEMA_URL.pathname, + { + parse: { binary: false, text: false, yaml: false }, + resolve: { external: false }, } ); - content += '\n\n'; - - return content; -}; -// customTemplates -autogen += templateTableGeneration( themejson, 'customTemplates' ); + const themeJsonReference = await fs.readFile( REFERENCE_DOC_URL, { + encoding: 'utf8', + flag: 'r', + } ); -// templateParts -autogen += templateTableGeneration( themejson, 'templateParts' ); + const generatedDocs = generateDocs( themeJson ); + const updatedThemeJsonReference = themeJsonReference.replace( + // `.` does not match new lines, but `[^]` will. + new RegExp( `${ START_TOKEN }[^]*${ END_TOKEN }` ), + `${ START_TOKEN }\n${ generatedDocs }\n${ END_TOKEN }` + ); -// Patterns -autogen += '## Patterns' + '\n\n'; -autogen += themejson.properties.patterns.description + '\n'; -autogen += 'Type: `' + themejson.properties.patterns.type + '`.\n\n'; + await fs.writeFile( REFERENCE_DOC_URL, updatedThemeJsonReference, { + encoding: 'utf8', + } ); +} -// Read existing file to wrap auto generated content. -let docsContent = fs.readFileSync( THEME_JSON_REF_DOC, { - encoding: 'utf8', - flag: 'r', +main().catch( ( error ) => { + console.error( error ); + process.exit( 1 ); } ); - -// Replace auto generated part with new generated docs. -autogen = START_TOKEN + '\n' + autogen + '\n' + END_TOKEN; -docsContent = docsContent.replace( TOKEN_PATTERN, autogen ); - -// Write back out. -fs.writeFileSync( THEME_JSON_REF_DOC, docsContent, { encoding: 'utf8' } ); diff --git a/docs/reference-guides/theme-json-reference/theme-json-living.md b/docs/reference-guides/theme-json-reference/theme-json-living.md index 0b9e3e9d187766..95f2e047dd0e31 100644 --- a/docs/reference-guides/theme-json-reference/theme-json-living.md +++ b/docs/reference-guides/theme-json-reference/theme-json-living.md @@ -21,8 +21,23 @@ For example, a schema for WordPress 5.8 is available at https://schemas.wp See [Developing with theme.json](/docs/how-to-guides/themes/global-settings-and-styles.md#developing-with-themejson) for how to use the JSON schema in your editor. -## Settings +## settings +Settings for the block editor and individual blocks. These include things like: +- Which customization options should be available to the user. +- The default colors, font sizes... available to the user. +- CSS custom properties and class names used in styles. +- And the default layout of the editor (widths and available alignments). + +### useRootPaddingAwareAlignments + +Enables root padding (the values from `styles.spacing.padding`) to be applied to the contents of full-width blocks instead of the root block. + +Please note that when using this setting, `styles.spacing.padding` should always be set as an object with `top`, `right`, `bottom`, `left` values declared separately. + +**Note:** Top-level only property. Not available in blocks. + +--- ### appearanceTools @@ -36,17 +51,16 @@ Setting that enables the following UI tools: - spacing: blockGap, margin, padding - typography: lineHeight - --- ### background Settings related to background. -| Property | Type | Default | Props | -| --- | --- | --- |--- | -| backgroundImage | boolean | false | | -| backgroundSize | boolean | false | | +| Property | Description | Type | Default | +| -------- | ----------- | ---- | ------- | +| backgroundImage | Allow users to set a background image. | `boolean` | `false` | +| backgroundSize | Allow users to set values related to the size of a background image, including size, position, and repeat controls. | `boolean` | `false` | --- @@ -54,12 +68,12 @@ Settings related to background. Settings related to borders. -| Property | Type | Default | Props | -| --- | --- | --- |--- | -| color | boolean | false | | -| radius | boolean | false | | -| style | boolean | false | | -| width | boolean | false | | +| Property | Description | Type | Default | +| -------- | ----------- | ---- | ------- | +| color | Allow users to set custom border colors. | `boolean` | `false` | +| radius | Allow users to set custom border radius. | `boolean` | `false` | +| style | Allow users to set custom border styles. | `boolean` | `false` | +| width | Allow users to set custom border widths. | `boolean` | `false` | --- @@ -67,23 +81,23 @@ Settings related to borders. Settings related to colors. -| Property | Type | Default | Props | -| --- | --- | --- |--- | -| background | boolean | true | | -| custom | boolean | true | | -| customDuotone | boolean | true | | -| customGradient | boolean | true | | -| defaultDuotone | boolean | true | | -| defaultGradients | boolean | true | | -| defaultPalette | boolean | true | | -| duotone | array | | colors, name, slug | -| gradients | array | | gradient, name, slug | -| link | boolean | false | | -| palette | array | | color, name, slug | -| text | boolean | true | | -| heading | boolean | true | | -| button | boolean | true | | -| caption | boolean | true | | +| Property | Description | Type | Default | +| -------- | ----------- | ---- | ------- | +| background | Allow users to set background colors. | `boolean` | `true` | +| custom | Allow users to select custom colors. | `boolean` | `true` | +| customDuotone | Allow users to create custom duotone filters. | `boolean` | `true` | +| customGradient | Allow users to create custom gradients. | `boolean` | `true` | +| defaultDuotone | Allow users to choose filters from the default duotone filter presets. | `boolean` | `true` | +| defaultGradients | Allow users to choose colors from the default gradients. | `boolean` | `true` | +| defaultPalette | Allow users to choose colors from the default palette. | `boolean` | `true` | +| duotone | Duotone presets for the duotone picker. | `[ { name, slug, colors } ]` | | +| gradients | Gradient presets for the gradient picker. | `[ { name, slug, gradient } ]` | | +| link | Allow users to set link colors in a block. | `boolean` | `false` | +| palette | Color palette presets for the color picker. | `[ { name, slug, color } ]` | | +| text | Allow users to set text colors in a block. | `boolean` | `true` | +| heading | Allow users to set heading colors in a block. | `boolean` | `true` | +| button | Allow users to set button colors in a block. | `boolean` | `true` | +| caption | Allow users to set caption colors in a block. | `boolean` | `true` | --- @@ -91,12 +105,12 @@ Settings related to colors. Settings related to dimensions. -| Property | Type | Default | Props | -| --- | --- | --- |--- | -| aspectRatio | boolean | false | | -| defaultAspectRatios | boolean | true | | -| aspectRatios | array | | name, ratio, slug | -| minHeight | boolean | false | | +| Property | Description | Type | Default | +| -------- | ----------- | ---- | ------- | +| aspectRatio | Allow users to set an aspect ratio. | `boolean` | `false` | +| defaultAspectRatios | Allow users to choose aspect ratios from the default set of aspect ratios. | `boolean` | `true` | +| aspectRatios | Allow users to define aspect ratios for some blocks. | `[ { name, slug, ratio } ]` | | +| minHeight | Allow users to set custom minimum height. | `boolean` | `false` | --- @@ -104,12 +118,12 @@ Settings related to dimensions. Settings related to layout. -| Property | Type | Default | Props | -| --- | --- | --- |--- | -| contentSize | string | | | -| wideSize | string | | | -| allowEditing | boolean | true | | -| allowCustomContentAndWideSize | boolean | true | | +| Property | Description | Type | Default | +| -------- | ----------- | ---- | ------- | +| contentSize | Sets the max-width of the content. | `string` | | +| wideSize | Sets the max-width of wide (`.alignwide`) content. Also used as the maximum viewport when calculating fluid font sizes | `string` | | +| allowEditing | Disable the layout UI controls. | `boolean` | `true` | +| allowCustomContentAndWideSize | Enable or disable the custom content and wide size controls. | `boolean` | `true` | --- @@ -117,10 +131,10 @@ Settings related to layout. Settings related to the lightbox. -| Property | Type | Default | Props | -| --- | --- | --- |--- | -| enabled | boolean | | | -| allowEditing | boolean | | | +| Property | Description | Type | Default | +| -------- | ----------- | ---- | ------- | +| enabled | Defines whether the lightbox is enabled or not. | `boolean` | | +| allowEditing | Defines whether to show the Lightbox UI in the block editor. If set to `false`, the user won't be able to change the lightbox settings in the block editor. | `boolean` | | --- @@ -128,9 +142,9 @@ Settings related to the lightbox. Settings related to position. -| Property | Type | Default | Props | -| --- | --- | --- |--- | -| sticky | boolean | false | | +| Property | Description | Type | Default | +| -------- | ----------- | ---- | ------- | +| sticky | Allow users to set sticky position. | `boolean` | `false` | --- @@ -138,10 +152,10 @@ Settings related to position. Settings related to shadows. -| Property | Type | Default | Props | -| --- | --- | --- |--- | -| defaultPresets | boolean | true | | -| presets | array | | name, shadow, slug | +| Property | Description | Type | Default | +| -------- | ----------- | ---- | ------- | +| defaultPresets | Allow users to choose shadows from the default shadow presets. | `boolean` | `true` | +| presets | Shadow presets for the shadow picker. | `[ { name, slug, shadow } ]` | | --- @@ -149,16 +163,16 @@ Settings related to shadows. Settings related to spacing. -| Property | Type | Default | Props | -| --- | --- | --- |--- | -| blockGap | boolean, null | null | | -| margin | boolean | false | | -| padding | boolean | false | | -| units | array | px,em,rem,vh,vw,% | | -| customSpacingSize | boolean | true | | -| defaultSpacingSizes | boolean | true | | -| spacingSizes | array | | name, size, slug | -| spacingScale | object | | | +| Property | Description | Type | Default | +| -------- | ----------- | ---- | ------- | +| blockGap | Enables `--wp--style--block-gap` to be generated from styles.spacing.blockGap. | `boolean`, `null` | `null` | +| margin | Allow users to set a custom margin. | `boolean` | `false` | +| padding | Allow users to set a custom padding. | `boolean` | `false` | +| units | List of units the user can use for spacing values. | `[ string ]` | `["px","em","rem","vh","vw","%"]` | +| customSpacingSize | Allow users to set custom space sizes. | `boolean` | `true` | +| defaultSpacingSizes | Allow users to choose space sizes from the default space size presets. | `boolean` | `true` | +| spacingSizes | Space size presets for the space size selector. | `[ { name, slug, size } ]` | | +| spacingScale | Settings to auto-generate space size presets for the space size selector. | `{ operator, increment, steps, mediumStep, unit }` | | --- @@ -166,23 +180,23 @@ Settings related to spacing. Settings related to typography. -| Property | Type | Default | Props | -| --- | --- | --- |--- | -| defaultFontSizes | boolean | true | | -| customFontSize | boolean | true | | -| fontStyle | boolean | true | | -| fontWeight | boolean | true | | -| fluid | object, boolean | false | _{maxViewportWidth, minFontSize, minViewportWidth}_ | -| letterSpacing | boolean | true | | -| lineHeight | boolean | false | | -| textAlign | boolean | true | | -| textColumns | boolean | false | | -| textDecoration | boolean | true | | -| writingMode | boolean | false | | -| textTransform | boolean | true | | -| dropCap | boolean | true | | -| fontSizes | array | | fluid, name, size, slug | -| fontFamilies | array | | fontFace, fontFamily, name, slug | +| Property | Description | Type | Default | +| -------- | ----------- | ---- | ------- | +| defaultFontSizes | Allow users to choose font sizes from the default font size presets. | `boolean` | `true` | +| customFontSize | Allow users to set custom font sizes. | `boolean` | `true` | +| fontStyle | Allow users to set custom font styles. | `boolean` | `true` | +| fontWeight | Allow users to set custom font weights. | `boolean` | `true` | +| fluid | Enables fluid typography and allows users to set global fluid typography parameters. | `boolean`, `{ minFontSize, maxViewportWidth, minViewportWidth }` | `false` | +| letterSpacing | Allow users to set custom letter spacing. | `boolean` | `true` | +| lineHeight | Allow users to set custom line height. | `boolean` | `false` | +| textAlign | Allow users to set the text align. | `boolean` | `true` | +| textColumns | Allow users to set the number of text columns. | `boolean` | `false` | +| textDecoration | Allow users to set custom text decorations. | `boolean` | `true` | +| writingMode | Allow users to set the writing mode. | `boolean` | `false` | +| textTransform | Allow users to set custom text transforms. | `boolean` | `true` | +| dropCap | Enable drop cap. | `boolean` | `true` | +| fontSizes | Font size presets for the font size selector. | `[ { name, slug, size, fluid } ]` | | +| fontFamilies | Font family presets for the font family selector. | `[ { name, slug, fontFamily, fontFace } ]` | | --- @@ -190,22 +204,23 @@ Settings related to typography. Generate custom CSS custom properties of the form `--wp--custom--{key}--{nested-key}: {value};`. `camelCased` keys are transformed to `kebab-case` as to follow the CSS property naming schema. Keys at different depth levels are separated by `--`, so keys should not include `--` in the name. - --- -## Styles +## styles + +Organized way to set CSS properties. Styles in the top-level will be added in the `body` selector. ### background Background styles. -| Property | Type | Props | -| --- | --- |--- | -| backgroundImage | string, object | | -| backgroundPosition | string, object | | -| backgroundRepeat | string, object | | -| backgroundSize | string, object | | -| backgroundAttachment | string, object | | +| Property | Description | Type | +| -------- | ----------- | ---- | +| backgroundImage | Sets the `background-image` CSS property. | `string`, `{ ref }`, `{ url }` | +| backgroundPosition | Sets the `background-position` CSS property. | `string`, `{ ref }` | +| backgroundRepeat | Sets the `background-repeat` CSS property. | `string`, `{ ref }` | +| backgroundSize | Sets the `background-size` CSS property. | `string`, `{ ref }` | +| backgroundAttachment | Sets the `background-attachment` CSS property. | `string`, `{ ref }` | --- @@ -213,16 +228,16 @@ Background styles. Border styles. -| Property | Type | Props | -| --- | --- |--- | -| color | string, object | | -| radius | string, object | | -| style | string, object | | -| width | string, object | | -| top | object | color, style, width | -| right | object | color, style, width | -| bottom | object | color, style, width | -| left | object | color, style, width | +| Property | Description | Type | +| -------- | ----------- | ---- | +| color | Sets the `border-color` CSS property. | `string`, `{ ref }` | +| radius | Sets the `border-radius` CSS property. | `string`, `{ ref }`, `{ topLeft, topRight, bottomLeft, bottomRight }` | +| style | Sets the `border-style` CSS property. | `string`, `{ ref }` | +| width | Sets the `border-width` CSS property. | `string`, `{ ref }` | +| top | | `{ color, style, width }` | +| right | | `{ color, style, width }` | +| bottom | | `{ color, style, width }` | +| left | | `{ color, style, width }` | --- @@ -230,11 +245,11 @@ Border styles. Color styles. -| Property | Type | Props | -| --- | --- |--- | -| background | string, object | | -| gradient | string, object | | -| text | string, object | | +| Property | Description | Type | +| -------- | ----------- | ---- | +| background | Sets the `background-color` CSS property. | `string`, `{ ref }` | +| gradient | Sets the `background` CSS property. | `string`, `{ ref }` | +| text | Sets the `color` CSS property. | `string`, `{ ref }` | --- @@ -242,17 +257,16 @@ Color styles. Sets custom CSS to apply styling not covered by other theme.json properties. - --- ### dimensions Dimensions styles. -| Property | Type | Props | -| --- | --- |--- | -| aspectRatio | string, object | | -| minHeight | string, object | | +| Property | Description | Type | +| -------- | ----------- | ---- | +| aspectRatio | Sets the `aspect-ratio` CSS property. | `string`, `{ ref }` | +| minHeight | Sets the `min-height` CSS property. | `string`, `{ ref }` | --- @@ -260,9 +274,9 @@ Dimensions styles. CSS and SVG filter styles. -| Property | Type | Props | -| --- | --- |--- | -| duotone | string, object | | +| Property | Description | Type | +| -------- | ----------- | ---- | +| duotone | Sets the duotone filter. | `string`, `{ ref }` | --- @@ -270,12 +284,12 @@ CSS and SVG filter styles. Outline styles. -| Property | Type | Props | -| --- | --- |--- | -| color | string, object | | -| offset | string, object | | -| style | string, object | | -| width | string, object | | +| Property | Description | Type | +| -------- | ----------- | ---- | +| color | Sets the `outline-color` CSS property. | `string`, `{ ref }` | +| offset | Sets the `outline-offset` CSS property. | `string`, `{ ref }` | +| style | Sets the `outline-style` CSS property. | `string`, `{ ref }` | +| width | Sets the `outline-width` CSS property. | `string`, `{ ref }` | --- @@ -283,18 +297,17 @@ Outline styles. Box shadow styles. - --- ### spacing Spacing styles. -| Property | Type | Props | -| --- | --- |--- | -| blockGap | string, object | | -| margin | object | bottom, left, right, top | -| padding | object | bottom, left, right, top | +| Property | Description | Type | +| -------- | ----------- | ---- | +| blockGap | Sets the `--wp--style--block-gap` CSS custom property when settings.spacing.blockGap is true. | `string`, `{ ref }` | +| margin | Margin styles. | `{ top, right, bottom, left }` | +| padding | Padding styles. | `{ top, right, bottom, left }` | --- @@ -302,51 +315,46 @@ Spacing styles. Typography styles. -| Property | Type | Props | -| --- | --- |--- | -| fontFamily | string, object | | -| fontSize | string, object | | -| fontStyle | string, object | | -| fontWeight | string, object | | -| letterSpacing | string, object | | -| lineHeight | string, object | | -| textAlign | string, object | | -| textColumns | string, object | | -| textDecoration | string, object | | -| writingMode | string, object | | -| textTransform | string, object | | +| Property | Description | Type | +| -------- | ----------- | ---- | +| fontFamily | Sets the `font-family` CSS property. | `string`, `{ ref }` | +| fontSize | Sets the `font-size` CSS property. | `string`, `{ ref }` | +| fontStyle | Sets the `font-style` CSS property. | `string`, `{ ref }` | +| fontWeight | Sets the `font-weight` CSS property. | `string`, `{ ref }` | +| letterSpacing | Sets the `letter-spacing` CSS property. | `string`, `{ ref }` | +| lineHeight | Sets the `line-height` CSS property. | `string`, `{ ref }` | +| textAlign | Sets the `text-align` CSS property. | `string`, `{ ref }` | +| textColumns | Sets the `column-count` CSS property. | `string`, `{ ref }` | +| textDecoration | Sets the `text-decoration` CSS property. | `string`, `{ ref }` | +| writingMode | Sets the `writing-mode` CSS property. | `string`, `{ ref }` | +| textTransform | Sets the `text-transform` CSS property. | `string`, `{ ref }` | --- + ## customTemplates Additional metadata for custom templates defined in the templates folder. -Type: `object`. - | Property | Description | Type | -| --- | --- | --- | -| name | Filename, without extension, of the template in the templates folder. | string | -| title | Title of the template, translatable. | string | -| postTypes | List of post types that can use this custom template. | array | - +| -------- | ----------- | ---- | +| name | Filename, without extension, of the template in the templates folder. | `string` | +| title | Title of the template, translatable. | `string` | +| postTypes | List of post types that can use this custom template. | `[ string ]` | ## templateParts Additional metadata for template parts defined in the parts folder. -Type: `object`. - | Property | Description | Type | -| --- | --- | --- | -| name | Filename, without extension, of the template in the parts folder. | string | -| title | Title of the template, translatable. | string | -| area | The area the template part is used for. Block variations for `header` and `footer` values exist and will be used when the area is set to one of those. | string | - +| -------- | ----------- | ---- | +| name | Filename, without extension, of the template in the parts folder. | `string` | +| title | Title of the template, translatable. | `string` | +| area | The area the template part is used for. Block variations for `header` and `footer` values exist and will be used when the area is set to one of those. | `string` | -## Patterns +## patterns An array of pattern slugs to be registered from the Pattern Directory. -Type: `array`. +Type: `[ string ]`.