Make WordPress Core

Changeset 55719


Ignore:
Timestamp:
05/03/2023 11:55:50 PM (19 months ago)
Author:
johnbillion
Message:

Docs: Correct and improve inline docs relating to the style engine.

See #57840

Location:
trunk/src/wp-includes
Files:
6 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/style-engine.php

    r54156 r55719  
    1111 */
    1212
    13 
    1413/**
    1514 * Global public interface method to generate styles from a single style object, e.g.,
     
    2019 * Example usage:
    2120 *
    22  * $styles = wp_style_engine_get_styles( array( 'color' => array( 'text' => '#cccccc' ) ) );
    23  * // Returns `array( 'css' => 'color: #cccccc', 'declarations' => array( 'color' => '#cccccc' ), 'classnames' => 'has-color' )`.
     21 *     $styles = wp_style_engine_get_styles( array( 'color' => array( 'text' => '#cccccc' ) ) );
     22 *
     23 * Returns:
     24 *
     25 *     array( 'css' => 'color: #cccccc', 'declarations' => array( 'color' => '#cccccc' ), 'classnames' => 'has-color' )
    2426 *
    2527 * @access public
     
    3234 *     @type string|null $context                    An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is `null`.
    3335 *                                                   When set, the style engine will attempt to store the CSS rules, where a selector is also passed.
    34  *     @type bool        $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
     36 *     @type bool        $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to `var( --wp--preset--* )` values. Default `false`.
    3537 *     @type string      $selector                   Optional. When a selector is passed, the value of `$css` in the return value will comprise a full CSS rule `$selector { ...$css_declarations }`,
    3638 *                                                   otherwise, the value will be a concatenated string of CSS declarations.
    3739 * }
    38  *
    3940 * @return array {
    4041 *     @type string   $css          A CSS ruleset or declarations block formatted to be placed in an HTML `style` attribute or tag.
    41  *     @type string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
     42 *     @type string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`.
    4243 *     @type string   $classnames   Classnames separated by a space.
    4344 * }
     
    7576/**
    7677 * Returns compiled CSS from a collection of selectors and declarations.
    77  * Useful for returning a compiled stylesheet from any collection of  CSS selector + declarations.
     78 * Useful for returning a compiled stylesheet from any collection of CSS selector + declarations.
    7879 *
    7980 * Example usage:
    80  * $css_rules = array( array( 'selector' => '.elephant-are-cool', 'declarations' => array( 'color' => 'gray', 'width' => '3em' ) ) );
    81  * $css       = wp_style_engine_get_stylesheet_from_css_rules( $css_rules );
    82  * // Returns `.elephant-are-cool{color:gray;width:3em}`.
     81 *
     82 *     $css_rules = array( array( 'selector' => '.elephant-are-cool', 'declarations' => array( 'color' => 'gray', 'width' => '3em' ) ) );
     83 *     $css       = wp_style_engine_get_stylesheet_from_css_rules( $css_rules );
     84 *
     85 * Returns:
     86 *
     87 *     .elephant-are-cool{color:gray;width:3em}
    8388 *
    8489 * @since 6.1.0
     
    8994 *     @type array ...$0 {
    9095 *         @type string   $selector     A CSS selector.
    91  *         @type string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
     96 *         @type string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`.
    9297 *     }
    9398 * }
     
    100105 *     @type bool        $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined.
    101106 * }
    102  *
    103107 * @return string A string of compiled CSS declarations, or empty string.
    104108 */
     
    147151 *     @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined.
    148152 * }
    149  *
    150153 * @return string A compiled CSS string.
    151154 */
  • trunk/src/wp-includes/style-engine/class-wp-style-engine-css-declarations.php

    r54481 r55719  
    2525     * @since 6.1.0
    2626     *
    27      * @var array
     27     * @var string[]
    2828     */
    2929    protected $declarations = array();
     
    3737     * @since 6.1.0
    3838     *
    39      * @param string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
     39     * @param string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`.
    4040     */
    4141    public function __construct( $declarations = array() ) {
     
    5050     * @param string $property The CSS property.
    5151     * @param string $value    The CSS value.
    52      *
    5352     * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
    5453     */
     
    7978     *
    8079     * @param string $property The CSS property.
    81      *
    8280     * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
    8381     */
     
    9290     * @since 6.1.0
    9391     *
    94      * @param array $declarations An array of declarations.
    95      *
     92     * @param string[] $declarations An array of declarations.
    9693     * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
    9794     */
     
    108105     * @since 6.1.0
    109106     *
    110      * @param array $properties An array of properties.
    111      *
     107     * @param string[] $properties An array of properties.
    112108     * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
    113109     */
     
    124120     * @since 6.1.0
    125121     *
    126      * @return array
     122     * @return string[] The declarations array.
    127123     */
    128124    public function get_declarations() {
     
    138134     * @param string $value    The value to be filtered.
    139135     * @param string $spacer   The spacer between the colon and the value. Defaults to an empty string.
    140      *
    141136     * @return string The filtered declaration or an empty string.
    142137     */
     
    154149     * @since 6.1.0
    155150     *
    156      * @param bool   $should_prettify Whether to add spacing, new lines and indents.
    157      * @param number $indent_count    The number of tab indents to apply to the rule. Applies if `prettify` is `true`.
    158      *
     151     * @param bool $should_prettify Whether to add spacing, new lines and indents.
     152     * @param int  $indent_count    The number of tab indents to apply to the rule. Applies if `prettify` is `true`.
    159153     * @return string The CSS declarations.
    160154     */
     
    182176     *
    183177     * @param string $property The CSS property.
    184      *
    185178     * @return string The sanitized property name.
    186179     */
  • trunk/src/wp-includes/style-engine/class-wp-style-engine-css-rule.php

    r54481 r55719  
    4444     *
    4545     * @param string                                    $selector     The CSS selector.
    46      * @param string[]|WP_Style_Engine_CSS_Declarations $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ),
     46     * @param string[]|WP_Style_Engine_CSS_Declarations $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`,
    4747     *                                                                or a WP_Style_Engine_CSS_Declarations object.
    4848     */
     
    5858     *
    5959     * @param string $selector The CSS selector.
    60      *
    6160     * @return WP_Style_Engine_CSS_Rule Returns the object to allow chaining of methods.
    6261     */
     
    7372     * @param array|WP_Style_Engine_CSS_Declarations $declarations An array of declarations (property => value pairs),
    7473     *                                                             or a WP_Style_Engine_CSS_Declarations object.
    75      *
    7674     * @return WP_Style_Engine_CSS_Rule Returns the object to allow chaining of methods.
    7775     */
     
    119117     * @since 6.1.0
    120118     *
    121      * @param bool   $should_prettify Whether to add spacing, new lines and indents.
    122      * @param number $indent_count    The number of tab indents to apply to the rule. Applies if `prettify` is `true`.
    123      *
     119     * @param bool $should_prettify Whether to add spacing, new lines and indents.
     120     * @param int  $indent_count    The number of tab indents to apply to the rule. Applies if `prettify` is `true`.
    124121     * @return string
    125122     */
  • trunk/src/wp-includes/style-engine/class-wp-style-engine-css-rules-store.php

    r54481 r55719  
    5252     *
    5353     * @param string $store_name The name of the store.
    54      *
    5554     * @return WP_Style_Engine_CSS_Rules_Store|void
    5655     */
     
    9594     *
    9695     * @param string $name The store name.
    97      *
    9896     * @return void
    9997     */
     
    131129     *
    132130     * @param string $selector The CSS selector.
    133      *
    134      * @return WP_Style_Engine_CSS_Rule|void Returns a WP_Style_Engine_CSS_Rule object, or null if the selector is empty.
     131     * @return WP_Style_Engine_CSS_Rule|void Returns a WP_Style_Engine_CSS_Rule object, or void if the selector is empty.
    135132     */
    136133    public function add_rule( $selector ) {
     
    156153     *
    157154     * @param string $selector The CSS selector.
    158      *
    159155     * @return void
    160156     */
  • trunk/src/wp-includes/style-engine/class-wp-style-engine-processor.php

    r54481 r55719  
    4242     *
    4343     * @param WP_Style_Engine_CSS_Rules_Store $store The store to add.
    44      *
    4544     * @return WP_Style_Engine_Processor Returns the object to allow chaining methods.
    4645     */
     
    6665     *
    6766     * @param WP_Style_Engine_CSS_Rule|WP_Style_Engine_CSS_Rule[] $css_rules A single, or an array of, WP_Style_Engine_CSS_Rule objects from a store or otherwise.
    68      *
    6967     * @return WP_Style_Engine_Processor Returns the object to allow chaining methods.
    7068     */
     
    9795     *     @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined.
    9896     * }
    99      *
    10097     * @return string The computed CSS.
    10198     */
  • trunk/src/wp-includes/style-engine/class-wp-style-engine.php

    r55175 r55719  
    1717 * This class is final and should not be extended.
    1818 * This class is for internal Core usage and is not supposed to be used by extenders (plugins and/or themes).
    19  * This is a low-level API that may need to do breaking changes. Please, use wp_style_engine_get_styles instead.
     19 * This is a low-level API that may need to do breaking changes. Please, use wp_style_engine_get_styles() instead.
    2020 *
    2121 * @access private
     
    230230
    231231    /**
    232      * Util: Extracts the slug in kebab case from a preset string, e.g., "heavenly-blue" from 'var:preset|color|heavenlyBlue'.
     232     * Util: Extracts the slug in kebab case from a preset string, e.g., `heavenly-blue` from `var:preset|color|heavenlyBlue`.
    233233     *
    234234     * @since 6.1.0
     
    236236     * @param string $style_value  A single CSS preset value.
    237237     * @param string $property_key The CSS property that is the second element of the preset string. Used for matching.
    238      *
    239238     * @return string The slug, or empty string if not found.
    240239     */
     
    248247
    249248    /**
    250      * Util: Generates a CSS var string, e.g., var(--wp--preset--color--background) from a preset string such as `var:preset|space|50`.
    251      *
    252      * @since 6.1.0
    253      *
    254      * @param string   $style_value  A single css preset value.
    255      * @param string[] $css_vars     An associate array of css var patterns used to generate the var string.
    256      *
    257      * @return string The css var, or an empty string if no match for slug found.
     249     * Util: Generates a CSS var string, e.g., `var(--wp--preset--color--background)` from a preset string such as `var:preset|space|50`.
     250     *
     251     * @since 6.1.0
     252     *
     253     * @param string   $style_value  A single CSS preset value.
     254     * @param string[] $css_vars     An associate array of CSS var patterns used to generate the var string.
     255     * @return string The CSS var, or an empty string if no match for slug found.
    258256     */
    259257    protected static function get_css_var_value( $style_value, $css_vars ) {
    260         foreach ( $css_vars as  $property_key => $css_var_pattern ) {
     258        foreach ( $css_vars as $property_key => $css_var_pattern ) {
    261259            $slug = static::get_slug_from_preset_value( $style_value, $property_key );
    262260            if ( static::is_valid_style_value( $slug ) ) {
     
    277275     *
    278276     * @param string $style_value A single CSS preset value.
    279      *
    280277     * @return bool
    281278     */
     
    291288     * @param string   $store_name       A valid store key.
    292289     * @param string   $css_selector     When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
    293      * @param string[] $css_declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
    294      *
    295      * @return void.
     290     * @param string[] $css_declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`.
     291     * @return void
    296292     */
    297293    public static function store_css_rule( $store_name, $css_selector, $css_declarations ) {
     
    308304     *
    309305     * @param string $store_name A store key.
    310      *
    311      * @return WP_Style_Engine_CSS_Rules_Store
     306     * @return WP_Style_Engine_CSS_Rules_Store|null
    312307     */
    313308    public static function get_store( $store_name ) {
     
    325320     *     Optional. An array of options. Default empty array.
    326321     *
    327      *     @type bool        $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
     322     *     @type bool        $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to `var( --wp--preset--* )` values. Default false.
    328323     *     @type string      $selector                   Optional. When a selector is passed, the value of `$css` in the return value will comprise a full CSS rule `$selector { ...$css_declarations }`,
    329324     *                                                   otherwise, the value will be a concatenated string of CSS declarations.
    330325     * }
    331      *
    332326     * @return array {
    333      *     @type string   $classnames   Classnames separated by a space.
    334      *     @type string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
     327     *     @type string[] $classnames   Array of class names.
     328     *     @type string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`.
    335329     * }
    336330     */
     
    365359
    366360    /**
    367      * Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., '`var:preset|<PRESET_TYPE>|<PRESET_SLUG>`'.
    368      *
    369      * @since 6.1.0
    370      *
    371      * @param array $style_value      A single raw style value or css preset property from the $block_styles array.
    372      * @param array $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
    373      *
    374      * @return array|string[] An array of CSS classnames, or empty array.
     361     * Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`.
     362     *
     363     * @since 6.1.0
     364     *
     365     * @param string $style_value      A single raw style value or CSS preset property from the `$block_styles` array.
     366     * @param array  $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
     367     * @return string[] An array of CSS classnames, or empty array if there are none.
    375368     */
    376369    protected static function get_classnames( $style_value, $style_definition ) {
     
    408401     * @since 6.1.0
    409402     *
    410      * @param array $style_value      A single raw style value from $block_styles array.
     403     * @param mixed $style_value      A single raw style value from $block_styles array.
    411404     * @param array $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
    412405     * @param array $options          {
    413406     *     Optional. An array of options. Default empty array.
    414407     *
    415      *     @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
     408     *     @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g.,
     409     *                                            `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to `var( --wp--preset--* )` values.
     410     *                                            Default false.
    416411     * }
    417      *
    418      * @return string[] An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
     412     * @return string[] An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`.
    419413     */
    420414    protected static function get_css_declarations( $style_value, $style_definition, $options = array() ) {
     
    474468     * Style value parser that returns a CSS definition array comprising style properties
    475469     * that have keys representing individual style properties, otherwise known as longhand CSS properties.
    476      * e.g., "$style_property-$individual_feature: $value;", which could represent the following:
    477      * "border-{top|right|bottom|left}-{color|width|style}: {value};" or,
    478      * "border-image-{outset|source|width|repeat|slice}: {value};"
    479      *
    480      * @since 6.1.0
    481      *
    482      * @param array $style_value                    A single raw style value from $block_styles array.
     470     *
     471     * Example:
     472     *
     473     *     "$style_property-$individual_feature: $value;"
     474     *
     475     * Which could represent the following:
     476     *
     477     *     "border-{top|right|bottom|left}-{color|width|style}: {value};"
     478     *
     479     * or:
     480     *
     481     *     "border-image-{outset|source|width|repeat|slice}: {value};"
     482     *
     483     * @since 6.1.0
     484     *
     485     * @param array $style_value                    A single raw style value from `$block_styles` array.
    483486     * @param array $individual_property_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA representing an individual property of a CSS property, e.g., 'top' in 'border-top'.
    484487     * @param array $options                        {
    485488     *     Optional. An array of options. Default empty array.
    486489     *
    487      *     @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
     490     *     @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to `var( --wp--preset--* )` values. Default false.
    488491     * }
    489      *
    490      * @return string[] An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
     492     * @return string[] An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`.
    491493     */
    492494    protected static function get_individual_property_css_declarations( $style_value, $individual_property_definition, $options = array() ) {
     
    527529
    528530    /**
    529      * Returns compiled CSS from css_declarations.
    530      *
    531      * @since 6.1.0
    532      *
    533      * @param string[] $css_declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
     531     * Returns compiled CSS from CSS declarations.
     532     *
     533     * @since 6.1.0
     534     *
     535     * @param string[] $css_declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`.
    534536     * @param string   $css_selector     When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
    535      *
    536537     * @return string A compiled CSS string.
    537538     */
     
    560561     *     Optional. An array of options. Default empty array.
    561562     *
    562      *     @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
    563      *     @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined.
     563     *     @type string|null $context  An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'.
     564     *                                 When set, the style engine will attempt to store the CSS rules.
     565     *     @type bool        $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
     566     *     @type bool        $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined.
    564567     * }
    565      *
    566568     * @return string A compiled stylesheet from stored CSS rules.
    567569     */
Note: See TracChangeset for help on using the changeset viewer.