Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Experiments: sharing private APIs with lock() and unlock() #46131

Merged
merged 23 commits into from
Jan 17, 2023

Commits on Dec 22, 2022

  1. Experiments: pivot towards lock()/unlock() based API

    This commit introduces a more convenient API for managing the
    private experiments.
    
    The idea is to "lock" private data inside public objects:
    
    ```js
    const { lock, unlock } = __dangerousOptInToUnstableAPIsOnlyForCoreModules(
    	'<CONSENT STRING>',
    	'@wordpress/blocks'
    );
    
    export const publicObject = {};
    lock( __experiments, "Shh, private data!" );
    
    publicObject
    // {}
    
    unlock( publicObject )
    // "Shh, private data!"
    ```
    
    The lock()/unlock() API makes it easier to implement private functions, components,
    selectors, actions etc. Instead of using a separate import system, it's enough to
    opt-in to the experiments and then `unlock()` the publicly available
    artifact. For example:
    
    ```js
    import { store } from '@wordpress/blocks';
    import { useSelect } from '@wordpress/data';
    import { unlock } from './experiments';
    
    function MyComponent() {
        const hasRole = useSelect( ( select ) => (
            unlock( select( store ) ).__experimentalHasContentRoleAttribute()
        ) );
    
        // ...
    }
    ```
    
    This makes `unlock()` a drop-in replacement that does not require
    reworking the current code structure around the experimental APIs.
    
    What's also nice is that the above implementation of private selectors
    (coming in a follow-up PR) is short, sweet, and fairly easy to grasp.
    For comparison, an implementation based on the former register/unlock
    API required quite a bit of mental gymnastics:
    
    ```js
    // Package wordpress/block-editor:
    export const { register, unlock } =
    	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
    		'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.',
    		'@wordpress/block-editor'
    	);
    
    const { __experimentalPrivateSelector } = unlock( dataExperiments );
    
    import {
    	__unstableSelectionHasUnmergeableBlock,
    } from './store/selectors';
    
    export const __experimentalAccessKey = register( {
    	__unstableSelectionHasUnmergeableBlock: __experimentalPrivateSelector(
    		store,
    		__unstableSelectionHasUnmergeableBlock
    	)
    } );
    
    // Package wordpress/edit-page
    export const { register, unlock } =
             __dangerousOptInToUnstableAPIsOnlyForCoreModules(
                     'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.',
                     '@wordpress/block-editor'
             );
    
    import { __experimentalAccessKey as blockEditorExperiments } from '@wordpress/block-editor';
    const { __unstableSelectionHasUnmergeableBlock } = unlock(__experimentalAccessKey);
    ```
    
    It also had an undesirable side-effect of requiring a separate import
    and a different treatment of the `__unstableSelectionHasUnmergeableBlock()`
    selector – which is to say a migration would be rather difficult.
    adamziel committed Dec 22, 2022
    Configuration menu
    Copy the full SHA
    982b862 View commit details
    Browse the repository at this point in the history
  2. Configuration menu
    Copy the full SHA
    bb2e1e0 View commit details
    Browse the repository at this point in the history
  3. Document the new API

    adamziel committed Dec 22, 2022
    Configuration menu
    Copy the full SHA
    48fd5a4 View commit details
    Browse the repository at this point in the history
  4. Add unit tests to demonstrate how to export private functions, functi…

    …on arguments, and react components
    adamziel committed Dec 22, 2022
    Configuration menu
    Copy the full SHA
    65750cf View commit details
    Browse the repository at this point in the history
  5. Configuration menu
    Copy the full SHA
    12bbcb6 View commit details
    Browse the repository at this point in the history
  6. Configuration menu
    Copy the full SHA
    2a706c3 View commit details
    Browse the repository at this point in the history
  7. Configuration menu
    Copy the full SHA
    3efd500 View commit details
    Browse the repository at this point in the history
  8. Configuration menu
    Copy the full SHA
    435ea50 View commit details
    Browse the repository at this point in the history
  9. Configuration menu
    Copy the full SHA
    75ec4fd View commit details
    Browse the repository at this point in the history
  10. Private experimental cross-module selectors and actions (#44521)

    Introduces a private selectors APIs in `@wordpress/data` via [the new `@wordpress/experimental`](#43386 (comment)) package:
    
    ```js
    // Package wordpress/block-data:
    import { unlock } from '../experiments';
    import { experiments as dataExperiments } from '@wordpress/data';
    const { registerPrivateActionsAndSelectors } = unlock( dataExperiments );
    
    import { store as blockEditorStore } from './store';
    import { __unstableSelectionHasUnmergeableBlock } from './store/selectors';
    registerPrivateActionsAndSelectors( store, {}, {
         __experimentalHasContentRoleAttribute
    } );
    
    // plain usage
    unlock( registry.select( blockEditorStore ) ).getContentLockingParent();
    
    // usage in React
    useSelect( ( select ) => ( {
      parent: privateOf( select( blockEditorStore ) ).__unstableSelectionHasUnmergeableBlock();
    } ) );
    ```
    adamziel committed Dec 22, 2022
    Configuration menu
    Copy the full SHA
    7f1b499 View commit details
    Browse the repository at this point in the history
  11. Configuration menu
    Copy the full SHA
    6933b2a View commit details
    Browse the repository at this point in the history
  12. 1 Configuration menu
    Copy the full SHA
    f8e199f View commit details
    Browse the repository at this point in the history
  13. Lint

    adamziel committed Dec 22, 2022
    1 Configuration menu
    Copy the full SHA
    cb11084 View commit details
    Browse the repository at this point in the history
  14. 1 Configuration menu
    Copy the full SHA
    8b5103c View commit details
    Browse the repository at this point in the history
  15. Rebuild docs

    adamziel committed Dec 22, 2022
    1 Configuration menu
    Copy the full SHA
    00a07b8 View commit details
    Browse the repository at this point in the history
  16. 1 Configuration menu
    Copy the full SHA
    ce9d2a2 View commit details
    Browse the repository at this point in the history

Commits on Dec 23, 2022

  1. Update packages/experiments/README.md

    Co-authored-by: Ramon <ramonjd@users.noreply.github.com>
    adamziel and ramonjd committed Dec 23, 2022
    Configuration menu
    Copy the full SHA
    9a01309 View commit details
    Browse the repository at this point in the history

Commits on Jan 16, 2023

  1. Lint

    adamziel committed Jan 16, 2023
    Configuration menu
    Copy the full SHA
    22369b7 View commit details
    Browse the repository at this point in the history
  2. Configuration menu
    Copy the full SHA
    eaff546 View commit details
    Browse the repository at this point in the history

Commits on Jan 17, 2023

  1. Update packages/experiments/src/implementation.js

    Co-authored-by: Robert Anderson <robert@noisysocks.com>
    adamziel and noisysocks committed Jan 17, 2023
    Configuration menu
    Copy the full SHA
    41582b7 View commit details
    Browse the repository at this point in the history
  2. Update packages/experiments/src/implementation.js

    Co-authored-by: Robert Anderson <robert@noisysocks.com>
    adamziel and noisysocks committed Jan 17, 2023
    Configuration menu
    Copy the full SHA
    c0ebbf8 View commit details
    Browse the repository at this point in the history
  3. Clarify the meaning of the second argument to __dangerousOptInToUnsta…

    …bleAPIsOnlyForCoreModules
    adamziel committed Jan 17, 2023
    Configuration menu
    Copy the full SHA
    583fd45 View commit details
    Browse the repository at this point in the history
  4. Assert that the public selector and actions still exist on the object…

    … returned by unlock().
    adamziel committed Jan 17, 2023
    Configuration menu
    Copy the full SHA
    954b353 View commit details
    Browse the repository at this point in the history