Changeset 53282

Timestamp:

04/26/2022 02:46:37 PM (3 years ago)

Author:

hellofromTonya

Message:

Themes: Add internal-only theme.json's webfonts handler (stopgap).

Adds _wp_theme_json_webfonts_handler() for handling fontFace declarations in a theme's theme.json file to generate the @font-face styles for both the editor and front-end.

Design notes:

• It is not a public API, but rather an internal, Core-only handler.
• It is a stopgap implementation that will be replaced when the public Webfonts API is introduced in Core.
• The code design is intentional, albeit funky, with the purpose of avoiding backwards-compatibility issues when the public Webfonts API is introduced in Core.
  • It hides the inter-workings.
  • Does not exposing API ins and outs for external consumption.
  • Only works for theme.json.
  • Does not provide registration or enqueuing access for plugins.

For more context on the decision to include this stopgap and the Webfonts API, see:

• Core's PR 40493 ​https://github.com/WordPress/gutenberg/pull/40493
• Gutenberg's tracking issue 40472 ​https://github.com/WordPress/gutenberg/issues/40472

Props aristath, hellofromTonya, peterwilsoncc, costdev, jffng, zieladam, gziolo, bph, jonoaldersonwp, desrosj.

See #55567, #46370.

Location:

trunk

Files:

• src/wp-includes/default-filters.php (modified) (1 diff)
• src/wp-includes/script-loader.php (modified) (1 diff)
• tests/phpunit/data/themedir1/empty-fontface-theme (added)
• tests/phpunit/data/themedir1/empty-fontface-theme/functions.php (added)
• tests/phpunit/data/themedir1/empty-fontface-theme/index.php (added)
• tests/phpunit/data/themedir1/empty-fontface-theme/style.css (added)
• tests/phpunit/data/themedir1/empty-fontface-theme/templates (added)
• tests/phpunit/data/themedir1/empty-fontface-theme/templates/index.html (added)
• tests/phpunit/data/themedir1/empty-fontface-theme/theme.json (added)
• tests/phpunit/data/themedir1/webfonts-theme (added)
• tests/phpunit/data/themedir1/webfonts-theme/functions.php (added)
• tests/phpunit/data/themedir1/webfonts-theme/index.php (added)
• tests/phpunit/data/themedir1/webfonts-theme/style.css (added)
• tests/phpunit/data/themedir1/webfonts-theme/templates (added)
• tests/phpunit/data/themedir1/webfonts-theme/templates/index.html (added)
• tests/phpunit/data/themedir1/webfonts-theme/theme.json (added)
• tests/phpunit/tests/theme/themeDir.php (modified) (1 diff)
• tests/phpunit/tests/webfonts (added)
• tests/phpunit/tests/webfonts/wpThemeJsonWebfontsHandler.php (added)

trunk/src/wp-includes/default-filters.php

@@ -352 +352 @@
 add_action( 'after_switch_theme', '_wp_sidebars_changed' );
 add_action( 'wp_print_styles', 'print_emoji_styles' );
+add_action( 'plugins_loaded', '_wp_theme_json_webfonts_handler' );
 
 if ( isset( $_GET['replytocom'] ) ) {

trunk/src/wp-includes/script-loader.php

@@ -3028 +3028 @@
     add_action( 'enqueue_block_assets', $callback );
 }
+
+/**
+ * Runs the theme.json webfonts handler.
+ *
+ * Using `WP_Theme_JSON_Resolver`, it gets the fonts defined
+ * in the `theme.json` for the current selection and style
+ * variations, validates the font-face properties, generates
+ * the '@font-face' style declarations, and then enqueues the
+ * styles for both the editor and front-end.
+ *
+ * Design Notes:
+ * This is not a public API, but rather an internal handler.
+ * A future public Webfonts API will replace this stopgap code.
+ *
+ * This code design is intentional.
+ *    a. It hides the inner-workings.
+ *    b. It does not expose API ins or outs for consumption.
+ *    c. It only works with a theme's `theme.json`.
+ *
+ * Why?
+ *    a. To avoid backwards-compatibility issues when
+ *       the Webfonts API is introduced in Core.
+ *    b. To make `fontFace` declarations in `theme.json` work.
+ *
+ * @link  https://github.com/WordPress/gutenberg/issues/40472
+ *
+ * @since 6.0.0
+ * @access private
+ */
+function _wp_theme_json_webfonts_handler() {
+    // Webfonts to be processed.
+    $registered_webfonts = array();
+
+    /**
+     * Gets the webfonts from theme.json.
+     *
+     * @since 6.0.0
+     *
+     * @return array Array of defined webfonts.
+     */
+    $fn_get_webfonts_from_theme_json = static function() {
+        // Get settings from theme.json.
+        $settings = WP_Theme_JSON_Resolver::get_merged_data()->get_settings();
+
+        // If in the editor, add webfonts defined in variations.
+        if ( is_admin() || ( defined( 'REST_REQUEST' ) && REST_REQUEST ) ) {
+            $variations = WP_Theme_JSON_Resolver::get_style_variations();
+            foreach ( $variations as $variation ) {
+                // Skip if fontFamilies are not defined in the variation.
+                if ( empty( $variation['settings']['typography']['fontFamilies'] ) ) {
+                    continue;
+                }
+
+                // Initialize the array structure.
+                if ( empty( $settings['typography'] ) ) {
+                    $settings['typography'] = array();
+                }
+                if ( empty( $settings['typography']['fontFamilies'] ) ) {
+                    $settings['typography']['fontFamilies'] = array();
+                }
+                if ( empty( $settings['typography']['fontFamilies']['theme'] ) ) {
+                    $settings['typography']['fontFamilies']['theme'] = array();
+                }
+
+                // Combine variations with settings. Remove duplicates.
+                $settings['typography']['fontFamilies']['theme'] = array_merge( $settings['typography']['fontFamilies']['theme'], $variation['settings']['typography']['fontFamilies']['theme'] );
+                $settings['typography']['fontFamilies']          = array_unique( $settings['typography']['fontFamilies'] );
+            }
+        }
+
+        // Bail out early if there are no settings for webfonts.
+        if ( empty( $settings['typography']['fontFamilies'] ) ) {
+            return array();
+        }
+
+        $webfonts = array();
+
+        // Look for fontFamilies.
+        foreach ( $settings['typography']['fontFamilies'] as $font_families ) {
+            foreach ( $font_families as $font_family ) {
+
+                // Skip if fontFace is not defined.
+                if ( empty( $font_family['fontFace'] ) ) {
+                    continue;
+                }
+
+                // Skip if fontFace is not an array of webfonts.
+                if ( ! is_array( $font_family['fontFace'] ) ) {
+                    continue;
+                }
+
+                $webfonts = array_merge( $webfonts, $font_family['fontFace'] );
+            }
+        }
+
+        return $webfonts;
+    };
+
+    /**
+     * Transforms each 'src' into an URI by replacing 'file:./'
+     * placeholder from theme.json.
+     *
+     * The absolute path to the webfont file(s) cannot be defined in
+     * theme.json. `file:./` is the placeholder which is replaced by
+     * the theme's URL path to the theme's root.
+     *
+     * @since 6.0.0
+     *
+     * @param array $src Webfont file(s) `src`.
+     * @return array Webfont's `src` in URI.
+     */
+    $fn_transform_src_into_uri = static function( array $src ) {
+        foreach ( $src as $key => $url ) {
+            // Tweak the URL to be relative to the theme root.
+            if ( ! str_starts_with( $url, 'file:./' ) ) {
+                continue;
+            }
+
+            $src[ $key ] = get_theme_file_uri( str_replace( 'file:./', '', $url ) );
+        }
+
+        return $src;
+    };
+
+    /**
+     * Converts the font-face properties (i.e. keys) into kebab-case.
+     *
+     * @since 6.0.0
+     *
+     * @param array $font_face Font face to convert.
+     * @return array Font faces with each property in kebab-case format.
+     */
+    $fn_convert_keys_to_kebab_case = static function( array $font_face ) {
+        foreach ( $font_face as $property => $value ) {
+            $kebab_case               = _wp_to_kebab_case( $property );
+            $font_face[ $kebab_case ] = $value;
+            if ( $kebab_case !== $property ) {
+                unset( $font_face[ $property ] );
+            }
+        }
+
+        return $font_face;
+    };
+
+    /**
+     * Validates a webfont.
+     *
+     * @since 6.0.0
+     *
+     * @param array $webfont The webfont arguments.
+     * @return array|false The validated webfont arguments, or false if the webfont is invalid.
+     */
+    $fn_validate_webfont = static function( $webfont ) {
+        $webfont = wp_parse_args(
+            $webfont,
+            array(
+                'font-family'  => '',
+                'font-style'   => 'normal',
+                'font-weight'  => '400',
+                'font-display' => 'fallback',
+                'src'          => array(),
+            )
+        );
+
+        // Check the font-family.
+        if ( empty( $webfont['font-family'] ) || ! is_string( $webfont['font-family'] ) ) {
+            trigger_error( __( 'Webfont font family must be a non-empty string.', 'gutenberg' ) );
+
+            return false;
+        }
+
+        // Check that the `src` property is defined and a valid type.
+        if ( empty( $webfont['src'] ) || ( ! is_string( $webfont['src'] ) && ! is_array( $webfont['src'] ) ) ) {
+            trigger_error( __( 'Webfont src must be a non-empty string or an array of strings.', 'gutenberg' ) );
+
+            return false;
+        }
+
+        // Validate the `src` property.
+        foreach ( (array) $webfont['src'] as $src ) {
+            if ( ! is_string( $src ) || '' === trim( $src ) ) {
+                trigger_error( __( 'Each webfont src must be a non-empty string.', 'gutenberg' ) );
+
+                return false;
+            }
+        }
+
+        // Check the font-weight.
+        if ( ! is_string( $webfont['font-weight'] ) && ! is_int( $webfont['font-weight'] ) ) {
+            trigger_error( __( 'Webfont font weight must be a properly formatted string or integer.', 'gutenberg' ) );
+
+            return false;
+        }
+
+        // Check the font-display.
+        if ( ! in_array( $webfont['font-display'], array( 'auto', 'block', 'fallback', 'swap' ), true ) ) {
+            $webfont['font-display'] = 'fallback';
+        }
+
+        $valid_props = array(
+            'ascend-override',
+            'descend-override',
+            'font-display',
+            'font-family',
+            'font-stretch',
+            'font-style',
+            'font-weight',
+            'font-variant',
+            'font-feature-settings',
+            'font-variation-settings',
+            'line-gap-override',
+            'size-adjust',
+            'src',
+            'unicode-range',
+        );
+
+        foreach ( $webfont as $prop => $value ) {
+            if ( ! in_array( $prop, $valid_props, true ) ) {
+                unset( $webfont[ $prop ] );
+            }
+        }
+
+        return $webfont;
+    };
+
+    /**
+     * Registers webfonts declared in theme.json.
+     *
+     * @since 6.0.0
+     *
+     * @uses $registered_webfonts To access and update the registered webfonts registry (passed by reference).
+     * @uses $fn_get_webfonts_from_theme_json To run the function that gets the webfonts from theme.json.
+     * @uses $fn_convert_keys_to_kebab_case To run the function that converts keys into kebab-case.
+     * @uses $fn_validate_webfont To run the function that validates each font-face (webfont) from theme.json.
+     */
+    $fn_register_webfonts = static function() use ( &$registered_webfonts, $fn_get_webfonts_from_theme_json, $fn_convert_keys_to_kebab_case, $fn_validate_webfont, $fn_transform_src_into_uri ) {
+        $registered_webfonts = array();
+
+        foreach ( $fn_get_webfonts_from_theme_json() as $webfont ) {
+            if ( ! is_array( $webfont ) ) {
+                continue;
+            }
+
+            $webfont = $fn_convert_keys_to_kebab_case( $webfont );
+
+            $webfont = $fn_validate_webfont( $webfont );
+
+            $webfont['src'] = $fn_transform_src_into_uri( (array) $webfont['src'] );
+
+            // Skip if not valid.
+            if ( empty( $webfont ) ) {
+                continue;
+            }
+
+            $registered_webfonts[] = $webfont;
+        }
+    };
+
+    /**
+     * Orders 'src' items to optimize for browser support.
+     *
+     * @since 6.0.0
+     *
+     * @param array $webfont Webfont to process.
+     * @return array Ordered `src` items.
+     */
+    $fn_order_src = static function( array $webfont ) {
+        $src         = array();
+        $src_ordered = array();
+
+        foreach ( $webfont['src'] as $url ) {
+            // Add data URIs first.
+            if ( str_starts_with( trim( $url ), 'data:' ) ) {
+                $src_ordered[] = array(
+                    'url'    => $url,
+                    'format' => 'data',
+                );
+                continue;
+            }
+            $format         = pathinfo( $url, PATHINFO_EXTENSION );
+            $src[ $format ] = $url;
+        }
+
+        // Add woff2.
+        if ( ! empty( $src['woff2'] ) ) {
+            $src_ordered[] = array(
+                'url'    => sanitize_url( $src['woff2'] ),
+                'format' => 'woff2',
+            );
+        }
+
+        // Add woff.
+        if ( ! empty( $src['woff'] ) ) {
+            $src_ordered[] = array(
+                'url'    => sanitize_url( $src['woff'] ),
+                'format' => 'woff',
+            );
+        }
+
+        // Add ttf.
+        if ( ! empty( $src['ttf'] ) ) {
+            $src_ordered[] = array(
+                'url'    => sanitize_url( $src['ttf'] ),
+                'format' => 'truetype',
+            );
+        }
+
+        // Add eot.
+        if ( ! empty( $src['eot'] ) ) {
+            $src_ordered[] = array(
+                'url'    => sanitize_url( $src['eot'] ),
+                'format' => 'embedded-opentype',
+            );
+        }
+
+        // Add otf.
+        if ( ! empty( $src['otf'] ) ) {
+            $src_ordered[] = array(
+                'url'    => sanitize_url( $src['otf'] ),
+                'format' => 'opentype',
+            );
+        }
+        $webfont['src'] = $src_ordered;
+
+        return $webfont;
+    };
+
+    /**
+     * Compiles the 'src' into valid CSS.
+     *
+     * @since 6.0.0
+     *
+     * @param string $font_family Font family.
+     * @param array  $value       Value to process.
+     * @return string The CSS.
+     */
+    $fn_compile_src = static function( $font_family, array $value ) {
+        $src = "local($font_family)";
+
+        foreach ( $value as $item ) {
+
+            if (
+                str_starts_with( $item['url'], site_url() ) ||
+                str_starts_with( $item['url'], home_url() )
+            ) {
+                $item['url'] = wp_make_link_relative( $item['url'] );
+            }
+
+            $src .= ( 'data' === $item['format'] )
+                ? ", url({$item['url']})"
+                : ", url('{$item['url']}') format('{$item['format']}')";
+        }
+
+        return $src;
+    };
+
+    /**
+     * Compiles the font variation settings.
+     *
+     * @since 6.0.0
+     *
+     * @param array $font_variation_settings Array of font variation settings.
+     * @return string The CSS.
+     */
+    $fn_compile_variations = static function( array $font_variation_settings ) {
+        $variations = '';
+
+        foreach ( $font_variation_settings as $key => $value ) {
+            $variations .= "$key $value";
+        }
+
+        return $variations;
+    };
+
+    /**
+     * Builds the font-family's CSS.
+     *
+     * @since 6.0.0
+     *
+     * @uses $fn_compile_src To run the function that compiles the src.
+     * @uses $fn_compile_variations To run the function that compiles the variations.
+     *
+     * @param array $webfont Webfont to process.
+     * @return string This font-family's CSS.
+     */
+    $fn_build_font_face_css = static function( array $webfont ) use ( $fn_compile_src, $fn_compile_variations ) {
+        $css = '';
+
+        // Wrap font-family in quotes if it contains spaces.
+        if (
+            str_contains( $webfont['font-family'], ' ' ) &&
+            ! str_contains( $webfont['font-family'], '"' ) &&
+            ! str_contains( $webfont['font-family'], "'" )
+        ) {
+            $webfont['font-family'] = '"' . $webfont['font-family'] . '"';
+        }
+
+        foreach ( $webfont as $key => $value ) {
+            /*
+             * Skip "provider", since it's for internal API use,
+             * and not a valid CSS property.
+             */
+            if ( 'provider' === $key ) {
+                continue;
+            }
+
+            // Compile the "src" parameter.
+            if ( 'src' === $key ) {
+                $value = $fn_compile_src( $webfont['font-family'], $value );
+            }
+
+            // If font-variation-settings is an array, convert it to a string.
+            if ( 'font-variation-settings' === $key && is_array( $value ) ) {
+                $value = $fn_compile_variations( $value );
+            }
+
+            if ( ! empty( $value ) ) {
+                $css .= "$key:$value;";
+            }
+        }
+
+        return $css;
+    };
+
+    /**
+     * Gets the '@font-face' CSS styles for locally-hosted font files.
+     *
+     * @since 6.0.0
+     *
+     * @uses $registered_webfonts To access and update the registered webfonts registry (passed by reference).
+     * @uses $fn_order_src To run the function that orders the src.
+     * @uses $fn_build_font_face_css To run the function that builds the font-face CSS.
+     *
+     * @return string The `@font-face` CSS.
+     */
+    $fn_get_css = static function() use ( &$registered_webfonts, $fn_order_src, $fn_build_font_face_css ) {
+        $css = '';
+
+        foreach ( $registered_webfonts as $webfont ) {
+            // Order the webfont's `src` items to optimize for browser support.
+            $webfont = $fn_order_src( $webfont );
+
+            // Build the @font-face CSS for this webfont.
+            $css .= '@font-face{' . $fn_build_font_face_css( $webfont ) . '}';
+        }
+
+        return $css;
+    };
+
+    /**
+     * Generates and enqueues webfonts styles.
+     *
+     * @since 6.0.0
+     *
+     * @uses $fn_get_css To run the function that gets the CSS.
+     */
+    $fn_generate_and_enqueue_styles = static function() use ( $fn_get_css ) {
+        // Generate the styles.
+        $styles = $fn_get_css();
+
+        // Bail out if there are no styles to enqueue.
+        if ( '' === $styles ) {
+            return;
+        }
+
+        // Enqueue the stylesheet.
+        wp_register_style( 'wp-webfonts', '' );
+        wp_enqueue_style( 'wp-webfonts' );
+
+        // Add the styles to the stylesheet.
+        wp_add_inline_style( 'wp-webfonts', $styles );
+    };
+
+    /**
+     * Generates and enqueues editor styles.
+     *
+     * @since 6.0.0
+     *
+     * @uses $fn_get_css To run the function that gets the CSS.
+     */
+    $fn_generate_and_enqueue_editor_styles = static function() use ( $fn_get_css ) {
+        // Generate the styles.
+        $styles = $fn_get_css();
+
+        // Bail out if there are no styles to enqueue.
+        if ( '' === $styles ) {
+            return;
+        }
+
+        wp_add_inline_style( 'wp-block-library', $styles );
+    };
+
+    add_action( 'wp_loaded', $fn_register_webfonts );
+    add_action( 'wp_enqueue_scripts', $fn_generate_and_enqueue_styles );
+    add_action( 'admin_init', $fn_generate_and_enqueue_editor_styles );
+}

trunk/tests/phpunit/tests/theme/themeDir.php

@@ -166 +166 @@
             'Block Theme [0.4.0]',
             'Block Theme [1.0.0] in subdirectory',
+            'Webfonts theme',
+            'Empty `fontFace` in theme.json - no webfonts defined',
         );