CodexModule.php

Go to the documentation of this file.

<?php
namespace MediaWiki\ResourceLoader;
 
use ExtensionRegistry;
use InvalidArgumentException;
use MediaWiki\Config\Config;
use MediaWiki\Html\Html;
use MediaWiki\Html\HtmlJsCode;
use MediaWiki\MainConfigNames;
 
class CodexModule extends FileModule {
    protected const CODEX_MODULE_DIR = 'resources/lib/codex/modules/';
    private const CODEX_MODULE_DEPENDENCIES = [ 'vue' ];
 
    private static ?array $themeMap = null;
 
    private static array $codexFilesCache = [];
 
    private array $codexComponents = [];
 
    private bool $isStyleOnly = false;
    private bool $isScriptOnly = false;
    private bool $codexFullLibrary = false;
    private bool $setupComplete = false;
 
    public function __construct( array $options = [], $localBasePath = null, $remoteBasePath = null ) {
        if ( isset( $options[ 'codexComponents' ] ) ) {
            if ( !is_array( $options[ 'codexComponents' ] ) || count( $options[ 'codexComponents' ] ) === 0 ) {
                throw new InvalidArgumentException(
                    "All 'codexComponents' properties in your module definition file " .
                    'must either be omitted or be an array with at least one component name'
                );
            }
 
            $this->codexComponents = $options[ 'codexComponents' ];
        }
 
        if ( isset( $options['codexFullLibrary'] ) ) {
            if ( isset( $options[ 'codexComponents' ] ) ) {
                throw new InvalidArgumentException(
                    'ResourceLoader modules using the CodexModule class cannot ' .
                    "use both 'codexFullLibrary' and 'codexComponents' options. " .
                    "Instead, use 'codexFullLibrary' to load the entire library" .
                    "or 'codexComponents' to load a subset of components."
                );
            }
 
            $this->codexFullLibrary = $options[ 'codexFullLibrary' ];
        }
 
        if ( isset( $options[ 'codexStyleOnly' ] ) ) {
            $this->isStyleOnly = $options[ 'codexStyleOnly' ];
        }
 
        if ( isset( $options[ 'codexScriptOnly' ] ) ) {
            $this->isScriptOnly = $options[ 'codexScriptOnly' ];
        }
 
        // Normalize $options[ 'dependencies' ] to always make it an array. It could be unset, or
        // it could be a string.
        $options[ 'dependencies' ] = (array)( $options[ 'dependencies' ] ?? [] );
 
        // Unlike when the entire @wikimedia/codex module is depended on, when the codexComponents
        // option is used, Vue is not automatically included, though it is required. Add it and
        // other dependencies here.
        if ( !$this->isStyleOnly && count( $this->codexComponents ) > 0 ) {
            $options[ 'dependencies' ] = array_unique( array_merge(
                $options[ 'dependencies' ],
                self::CODEX_MODULE_DEPENDENCIES
            ) );
        }
 
        if ( in_array( '@wikimedia/codex', $options[ 'dependencies' ] ) ) {
            throw new InvalidArgumentException(
                'ResourceLoader modules using the CodexModule class cannot ' .
                "list the '@wikimedia/codex' module as a dependency. " .
                "Instead, use 'codexComponents' to require a subset of components."
            );
        }
 
        parent::__construct( $options, $localBasePath, $remoteBasePath );
    }
 
    public static function getIcons( Context $context, Config $config, array $iconNames = [] ): array {
        global $IP;
        static $allIcons = null;
        if ( $allIcons === null ) {
            $allIcons = json_decode( file_get_contents( "$IP/resources/lib/codex-icons/codex-icons.json" ), true );
        }
        return array_intersect_key( $allIcons, array_flip( $iconNames ) );
    }
 
    // These 3 public methods are the entry points to this class; depending on the
    // circumstances any one of these might be called first.
 
    public function getPackageFiles( Context $context ) {
        $this->setupCodex( $context );
        return parent::getPackageFiles( $context );
    }
 
    public function getStyleFiles( Context $context ) {
        $this->setupCodex( $context );
        return parent::getStyleFiles( $context );
    }
 
    public function getDefinitionSummary( Context $context ) {
        $this->setupCodex( $context );
        return parent::getDefinitionSummary( $context );
    }
 
    public function getFlip( Context $context ) {
        // Never flip styles for Codex modules, because we already provide separate style files
        // for LTR vs RTL
        return false;
    }
 
    public function supportsURLLoading() {
        // We need to override this explicitly. The parent method might return true if there are
        // no 'packageFiles' set in the module definition and they're all generated by us.
        // It's possible that this "should" return true in some circumstances (e.g. style-only use
        // of CodexModule combined with non-packageFiles scripts), but those are edge cases that
        // we're choosing not to support here.
        return false;
    }
 
    private function getTheme( Context $context ): string {
        if ( self::$themeMap === null ) {
            // Initialize self::$themeMap
            $skinCodexThemes = ExtensionRegistry::getInstance()->getAttribute( 'SkinCodexThemes' );
            self::$themeMap = [ 'default' => 'wikimedia-ui' ] + $skinCodexThemes;
        }
        // @phan-suppress-next-line PhanTypeArraySuspiciousNullable
        return self::$themeMap[ $context->getSkin() ] ?? self::$themeMap[ 'default' ];
    }
 
    private function getManifestFilePath( Context $context ): string {
        $themeManifestNames = [
            'wikimedia-ui' => [
                'ltr' => 'manifest.json',
                'rtl' => 'manifest-rtl.json',
            ],
            'wikimedia-ui-legacy' => [
                'ltr' => 'manifest-legacy.json',
                'rtl' => 'manifest-legacy-rtl.json',
            ],
            'experimental' => [
                'ltr' => 'manifest-experimental.json',
                'rtl' => 'manifest-experimental-rtl.json',
            ]
        ];
 
        $theme = $this->getTheme( $context );
        $direction = $context->getDirection();
        if ( !isset( $themeManifestNames[ $theme ] ) ) {
            throw new InvalidArgumentException( "Unknown Codex theme $theme" );
        }
        $manifestFile = $themeManifestNames[ $theme ][ $direction ];
        $manifestFilePath = MW_INSTALL_PATH . '/' . static::CODEX_MODULE_DIR . $manifestFile;
        return $manifestFilePath;
    }
 
    private function getCodexFiles( Context $context ): array {
        $manifestFilePath = $this->getManifestFilePath( $context );
 
        if ( isset( self::$codexFilesCache[ $manifestFilePath ] ) ) {
            return self::$codexFilesCache[ $manifestFilePath ];
        }
 
        $manifest = json_decode( file_get_contents( $manifestFilePath ), true );
        $files = [];
        $components = [];
        foreach ( $manifest as $key => $val ) {
            $files[ $val[ 'file' ] ] = [
                'styles' => $val[ 'css' ] ?? [],
                // $val['imports'] is expressed as manifest keys, transform those to file names
                'dependencies' => array_map( static function ( $manifestKey ) use ( $manifest ) {
                    // @phan-suppress-next-line PhanTypeArraySuspiciousNullable
                    return $manifest[ $manifestKey ][ 'file' ];
                }, $val[ 'imports' ] ?? [] )
            ];
 
            $isComponent = isset( $val[ 'isEntry' ] ) && $val[ 'isEntry' ];
            if ( $isComponent ) {
                $fileInfo = pathinfo( $val[ 'file' ] );
                // $fileInfo[ 'filename' ] is the file name without the extension.
                // This is the component name (e.g. CdxButton.cjs -> CdxButton).
                $components[ $fileInfo[ 'filename' ] ] = $val[ 'file' ];
            }
        }
 
        self::$codexFilesCache[ $manifestFilePath ] = [ 'files' => $files, 'components' => $components ];
        return self::$codexFilesCache[ $manifestFilePath ];
    }
 
    private function setupCodex( Context $context ) {
        if ( $this->setupComplete ) {
            return;
        }
 
        // If we are tree-shaking, add component-specific JS/CSS files
        if ( count( $this->codexComponents ) > 0 ) {
            $this->addComponentFiles( $context );
        }
 
        // If we want to load the entire Codex library (no tree shaking)
        if ( $this->codexFullLibrary ) {
            $this->loadFullCodexLibrary( $context );
 
        }
 
        $this->setupComplete = true;
    }
 
    private function resolveDependencies( array $requestedFiles, array $codexFiles ) {
        $scripts = [];
        $styles = [];
 
        $gatherDependencies = static function ( $file ) use ( &$scripts, &$styles, $codexFiles, &$gatherDependencies ) {
            foreach ( $codexFiles[ 'files' ][ $file ][ 'dependencies' ] as $dep ) {
                if ( !in_array( $dep, $scripts ) ) {
                    $gatherDependencies( $dep );
                }
            }
            $scripts[] = $file;
            $styles = array_merge( $styles, $codexFiles[ 'files' ][ $file ][ 'styles' ] );
        };
 
        foreach ( $requestedFiles as $requestedFile ) {
            $gatherDependencies( $requestedFile );
        }
 
        return [ 'scripts' => $scripts, 'styles' => $styles ];
    }
 
    private function addComponentFiles( Context $context ) {
        $remoteBasePath = $this->getConfig()->get( MainConfigNames::ResourceBasePath );
        $codexFiles = $this->getCodexFiles( $context );
 
        $requestedFiles = array_map( static function ( $component ) use ( $codexFiles ) {
            if ( !isset( $codexFiles[ 'components' ][ $component ] ) ) {
                throw new InvalidArgumentException(
                    "\"$component\" is not an export of Codex and cannot be included in the \"codexComponents\" array."
                );
            }
            return $codexFiles[ 'components' ][ $component ];
        }, $this->codexComponents );
 
        [ 'scripts' => $scripts, 'styles' => $styles ] = $this->resolveDependencies( $requestedFiles, $codexFiles );
 
        // Add the CSS files to the module's package file (unless this is a script-only module)
        if ( !$this->isScriptOnly ) {
            foreach ( $styles as $fileName ) {
                $this->styles[] = new FilePath( static::CODEX_MODULE_DIR .
                    $fileName, MW_INSTALL_PATH, $remoteBasePath );
            }
        }
 
        // Add the JS files to the module's package file (unless this is a style-only module).
        if ( !$this->isStyleOnly ) {
            $exports = [];
            foreach ( $this->codexComponents as $component ) {
                $componentFile = $codexFiles[ 'components' ][ $component ];
                $exports[ $component ] = new HtmlJsCode(
                    'require( ' . Html::encodeJsVar( "./_codex/$componentFile" ) . ' )'
                );
            }
 
            // Add a synthetic top-level "exports" file
            $syntheticExports = Html::encodeJsVar( HtmlJsCode::encodeObject( $exports ) );
 
            // Proxy the synthetic exports object so that we can throw a useful error if a component
            // is not defined in the module definition
            $proxiedSyntheticExports = <<<JAVASCRIPT
            module.exports = new Proxy( $syntheticExports, {
                get( target, prop ) {
                    if ( !( prop in target ) ) {
                        throw new Error(
                            `Codex component "\${prop}" ` +
                            'is not listed in the "codexComponents" array ' +
                            'of the "{$this->getName()}" module in your module definition file'
                        );
                    }
                    return target[ prop ];
                }
            } );
            JAVASCRIPT;
 
            $this->packageFiles[] = [
                'name' => 'codex.js',
                'content' => $proxiedSyntheticExports
            ];
 
            // Add each of the referenced scripts to the package
            foreach ( $scripts as $fileName ) {
                $this->packageFiles[] = [
                    'name' => "_codex/$fileName",
                    'file' => new FilePath( static::CODEX_MODULE_DIR . $fileName, MW_INSTALL_PATH, $remoteBasePath )
                ];
            }
        }
    }
 
    private function loadFullCodexLibrary( Context $context ) {
        $remoteBasePath = $this->getConfig()->get( MainConfigNames::ResourceBasePath );
 
        // Add all Codex JS files to the module's package
        if ( !$this->isStyleOnly ) {
            $this->packageFiles[] = [
                'name' => 'codex.js',
                'file' => new FilePath( 'resources/lib/codex/codex.umd.cjs', MW_INSTALL_PATH, $remoteBasePath )
            ];
        }
 
        // Add all Codex CSS files to the module's package
        if ( !$this->isScriptOnly ) {
            // Theme-specific + direction style files
            $themeStyles = [
                'wikimedia-ui' => [
                    'ltr' => 'resources/lib/codex/codex.style.css',
                    'rtl' => 'resources/lib/codex/codex.style-rtl.css'
                ],
                'wikimedia-ui-legacy' => [
                    'ltr' => 'resources/lib/codex/codex.style-legacy.css',
                    'rtl' => 'resources/lib/codex/codex.style-legacy-rtl.css'
                ],
                'experimental' => [
                    'ltr' => 'resources/lib/codex/codex.style-experimental.css',
                    'rtl' => 'resources/lib/codex/codex.style-experimental-rtl.css'
                ]
            ];
 
            $theme = $this->getTheme( $context );
            $direction = $context->getDirection();
            $styleFile = $themeStyles[ $theme ][ $direction ];
            $this->styles[] = new FilePath(
                $styleFile,
                MW_INSTALL_PATH,
                $remoteBasePath
            );
        }
    }
}