-
Notifications
You must be signed in to change notification settings - Fork 4.2k
Commit
Motivation ========== Actions and commands -------------------- In the context of Data Views, there has been a lot of recent work towards providing a set of actions operating on posts, templates, patterns (e.g. rename post, edit post, duplicate template), and ultimately other entities. These actions, however, aren't unique to Data Views, and indeed exist in several different contexts (e.g. Site Editor inner sidebar, new Admin "shell" sidebar, Pages index view, Post Editor), so the next step was to unify actions across packages (e.g. #60486, #60754). The first unification effort led to an abstraction around a hook, `usePostActions`, but the consensus now is to remove it and expose the actions directly (#61040). Meanwhile, it has been noted that there is a strong parallel between these _actions_ and the Command Palette's _commands_, which has its own API already. This isn't a 1:1 mapping, but we should determine what the overlap is. Actions and side effects ------------------------ There is a limit to how much we can unify, because the context in which actions are triggered will determine what secondary effects are desired. For example, trashing a post inside the post editor should result in the client navigating elsewhere (e.g. edit.php), but there should be no such effect when trashing from a Data View index. The current solution for this is to let consumers of the `PostActions` component pass a callback as `onActionPerformed`. It works but there's a risk that it's too flexible, so I kept wondering about what kind of generalisations we could make here before we opened this up as an API. Extensibility ------------- As tracked in #61084, our system -- what ever it turns to be -- needs to become extensible soon. Somewhere in our GitHub conversations there was a suggestion to set up an imperative API like `registerAction` that third parties could leverage. I think that's fair, though we'll need to determine what kind of registry we want (scope and plurality). An imperative API that can be called in an initialisation step rather than as a call inside the render tree (e.g. `<Provider value=...>` or `useRegisterAction(...)`) is more convenient for developers, but introduces indirection. In this scenario, how do we implement those aforementioned _contextual side effects_ (e.g. navigate to page)? The experiment ============== It was in this context that I had the terrible thought of leveraging wp.hooks to provide a private API (to dogfood in Gutenberg core packages). But, of course, hooks are keyed by strings, and so they are necessarily public -- i.e., a third party can call `applyFilters('privateFilter'`, even if `privateFilter` is not meant to be used outside of core. This branch changes that assumption: hook names *must* be strings, *except* if they match a small set of hard-coded symbols. These symbols are only accessible via the lock/unlock API powered by the `private-apis` package. Thus, core packages can communicate amongst each other via hooks that no third party can use. For example: - An action triggers `doAction` with a symbol corresponding to its name (e.g. `postActions.renamePost`). - A consumer of actions, like the Page index view (PagePages), triggers a more contextual action (e.g. `pagePages.renamePost`). - A different component hooks to one of these actions, according to the intended specificity, to trigger a side effect like navigation. See for yourself: upon `pagePages.editPost`, the necessary navigation to said post is triggered by a subscriber of that action. Assessment ========== Having tried it, I think this is a poor idea. "Private hooks" as a concept is a cool way to see how far `private-apis` can take us, but they seem like the wrong tool for the current problem. Still, I wanted to share the work, hence this verbose commit. I think our next steps should be: - Finish the actions refactor (#61040) - Impose constraints on ourselves to try to achieve our feature goals with less powerful constructs than `onActionPerformed`. I'm still convinced we haven't done enough work to generalise side effects. Consider it along with the commands API. - Try a more classic registry-based approach for actions (`registerAction`)
- Loading branch information
There are no files selected for viewing
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
/** | ||
* WordPress dependencies | ||
*/ | ||
import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis'; | ||
Check failure on line 4 in packages/hooks/src/lock-unlock.js GitHub Actions / Playwright - 1
Check failure on line 4 in packages/hooks/src/lock-unlock.js GitHub Actions / Playwright - 6
Check failure on line 4 in packages/hooks/src/lock-unlock.js GitHub Actions / Playwright - 7
Check failure on line 4 in packages/hooks/src/lock-unlock.js GitHub Actions / Playwright - 8
Check failure on line 4 in packages/hooks/src/lock-unlock.js GitHub Actions / Playwright - 2
Check failure on line 4 in packages/hooks/src/lock-unlock.js GitHub Actions / Build Release Artifact
Check failure on line 4 in packages/hooks/src/lock-unlock.js GitHub Actions / Playwright - 3
Check failure on line 4 in packages/hooks/src/lock-unlock.js GitHub Actions / Playwright - 5
Check failure on line 4 in packages/hooks/src/lock-unlock.js GitHub Actions / Playwright - 4
Check failure on line 4 in packages/hooks/src/lock-unlock.js GitHub Actions / Build JavaScript assets for PHP unit tests
Check failure on line 4 in packages/hooks/src/lock-unlock.js GitHub Actions / Check
|
||
export const { lock, unlock } = | ||
__dangerousOptInToUnstableAPIsOnlyForCoreModules( | ||
'I know using unstable features means my theme or plugin will inevitably break in the next version of WordPress.', | ||
'@wordpress/hooks' | ||
); |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
/** | ||
* Internal dependencies | ||
*/ | ||
import { lock } from './lock-unlock'; | ||
import { privateHooksMap } from './private-hooks'; | ||
|
||
export const privateApis = {}; | ||
|
||
lock( privateApis, { privateHooksMap } ); |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,27 @@ | ||
// Define a list of "private hooks" that only core packages can use. This is | ||
// implemented by producing Symbols from these hook names, the access to which | ||
// will be mediated by the lock/unlock interface. | ||
// | ||
// Note that the standard Hooks API only accepts valid strings as hook names, | ||
// but an exception will be made for Symbols on this list. | ||
// | ||
// @see validateHookName. | ||
const privateHooks = [ | ||
'postActions.renamePost', | ||
'pagePages.renamePost', | ||
'pagePages.editPost', | ||
]; | ||
|
||
// Used by consumers of the hooks API | ||
// | ||
// @example | ||
// ```js | ||
// const { privateHooksMap } = unlock( privateApis ); | ||
// const MY_HOOK = privateHooksMap.get( 'myHook' ); | ||
// doAction( MY_HOOK ); | ||
// ``` | ||
export const privateHooksMap = new Map( | ||
privateHooks.map( ( label ) => [ label, Symbol( label ) ] ) | ||
); | ||
|
||
export const privateHooksSet = new Set( privateHooksMap.values() ); |