Skip to content

Move entity-provider.js exports into hooks/index.ts so they are added to the docs #63528

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.

Sign up for GitHub

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

Merged
merged 3 commits into from
Jul 17, 2024
Merged

Move entity-provider.js exports into hooks/index.ts so they are added to the docs #63528

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
43ab67e
Reapply changes to fix bad rebase.
ryanwelcher Jul 16, 2024
40e1c9f
Update import for entity-provider.js tests.
ryanwelcher Jul 16, 2024
803d96b
Create a common EntityContext and import to appropriate places.
ryanwelcher Jul 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions packages/core-data/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -976,6 +976,47 @@ The following set of react hooks available to import from the `@wordpress/core-d

<!-- START TOKEN(Autogenerated hooks|src/hooks/index.ts) -->

### useEntityBlockEditor

Hook that returns block content getters and setters for the nearest provided entity of the specified type.

The return value has the shape `[ blocks, onInput, onChange ]`. `onInput` is for block changes that don't create undo levels or dirty the post, non-persistent changes, and `onChange` is for persistent changes. They map directly to the props of a `BlockEditorProvider` and are intended to be used with it, or similar components or hooks.

_Parameters_

- _kind_ `string`: The entity kind.
- _name_ `string`: The entity name.
- _options_ `Object`:
- _options.id_ `[string]`: An entity ID to use instead of the context-provided one.

_Returns_

- `[unknown[], Function, Function]`: The block array and setters.

### useEntityId

Hook that returns the ID for the nearest provided entity of the specified type.

_Parameters_

- _kind_ `string`: The entity kind.
- _name_ `string`: The entity name.

### useEntityProp

Hook that returns the value and a setter for the specified property of the nearest provided entity of the specified type.

_Parameters_

- _kind_ `string`: The entity kind.
- _name_ `string`: The entity name.
- _prop_ `string`: The property name.
- _\_id_ `[string]`: An entity ID to use instead of the context-provided one.

_Returns_

- `[*, Function, *]`: An array where the first item is the property value, the second is the setter and the third is the full value object from REST API containing more information like `raw`, `rendered` and `protected` props.

### useEntityRecord

Resolves the specified entity record.
Expand Down
212 changes: 1 addition & 211 deletions packages/core-data/src/entity-provider.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,7 @@
/**
* WordPress dependencies
*/
import {
createContext,
useContext,
useCallback,
useMemo,
} from '@wordpress/element';
import { useSelect, useDispatch } from '@wordpress/data';
import { parse, __unstableSerializeAndClean } from '@wordpress/blocks';

/**
* Internal dependencies
*/
import { STORE_NAME } from './name';
import { updateFootnotesFromMeta } from './footnotes';

const EMPTY_ARRAY = [];
import { createContext, useContext, useMemo } from '@wordpress/element';

const EntityContext = createContext( {} );
Copy link
Contributor Author

@ryanwelcher ryanwelcher Jul 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Mamaduka @youknowriad I just wanted to call this out as there was a single EntityContext being used across the hooks and to move the useEntityId hook into it's own file, I needed to create the same there.

I don't see any errors/failures but wanted to be sure that doing this won't cause any unexpected outcome.

Copy link
Contributor

@youknowriad youknowriad Jul 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, that's a mistake, it should use the exact same EntityContext in all the files. You can do so by creating an entity-context file and importing it in all the files.

Copy link
Contributor Author

@ryanwelcher ryanwelcher Jul 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated with latest commit. Thanks for confirming, it felt like that was a bad idea :)


Expand Down Expand Up @@ -51,198 +36,3 @@ export default function EntityProvider( { kind, type: name, id, children } ) {
</EntityContext.Provider>
);
}

/**
* Hook that returns the ID for the nearest
* provided entity of the specified type.
*
* @param {string} kind The entity kind.
* @param {string} name The entity name.
*/
export function useEntityId( kind, name ) {
const context = useContext( EntityContext );
return context?.[ kind ]?.[ name ];
}

/**
* Hook that returns the value and a setter for the
* specified property of the nearest provided
* entity of the specified type.
*
* @param {string} kind The entity kind.
* @param {string} name The entity name.
* @param {string} prop The property name.
* @param {string} [_id] An entity ID to use instead of the context-provided one.
*
* @return {[*, Function, *]} An array where the first item is the
* property value, the second is the
* setter and the third is the full value
* object from REST API containing more
* information like `raw`, `rendered` and
* `protected` props.
*/
export function useEntityProp( kind, name, prop, _id ) {
const providerId = useEntityId( kind, name );
const id = _id ?? providerId;

const { value, fullValue } = useSelect(
( select ) => {
const { getEntityRecord, getEditedEntityRecord } =
select( STORE_NAME );
const record = getEntityRecord( kind, name, id ); // Trigger resolver.
const editedRecord = getEditedEntityRecord( kind, name, id );
return record && editedRecord
? {
value: editedRecord[ prop ],
fullValue: record[ prop ],
}
: {};
},
[ kind, name, id, prop ]
);
const { editEntityRecord } = useDispatch( STORE_NAME );
const setValue = useCallback(
( newValue ) => {
editEntityRecord( kind, name, id, {
[ prop ]: newValue,
} );
},
[ editEntityRecord, kind, name, id, prop ]
);

return [ value, setValue, fullValue ];
}

const parsedBlocksCache = new WeakMap();

/**
* Hook that returns block content getters and setters for
* the nearest provided entity of the specified type.
*
* The return value has the shape `[ blocks, onInput, onChange ]`.
* `onInput` is for block changes that don't create undo levels
* or dirty the post, non-persistent changes, and `onChange` is for
* persistent changes. They map directly to the props of a
* `BlockEditorProvider` and are intended to be used with it,
* or similar components or hooks.
*
* @param {string} kind The entity kind.
* @param {string} name The entity name.
* @param {Object} options
* @param {string} [options.id] An entity ID to use instead of the context-provided one.
*
* @return {[unknown[], Function, Function]} The block array and setters.
*/
export function useEntityBlockEditor( kind, name, { id: _id } = {} ) {
const providerId = useEntityId( kind, name );
const id = _id ?? providerId;
const { getEntityRecord, getEntityRecordEdits } = useSelect( STORE_NAME );
const { content, editedBlocks, meta } = useSelect(
( select ) => {
if ( ! id ) {
return {};
}
const { getEditedEntityRecord } = select( STORE_NAME );
const editedRecord = getEditedEntityRecord( kind, name, id );
return {
editedBlocks: editedRecord.blocks,
content: editedRecord.content,
meta: editedRecord.meta,
};
},
[ kind, name, id ]
);
const { __unstableCreateUndoLevel, editEntityRecord } =
useDispatch( STORE_NAME );

const blocks = useMemo( () => {
if ( ! id ) {
return undefined;
}

if ( editedBlocks ) {
return editedBlocks;
}

if ( ! content || typeof content !== 'string' ) {
return EMPTY_ARRAY;
}

// If there's an edit, cache the parsed blocks by the edit.
// If not, cache by the original enity record.
const edits = getEntityRecordEdits( kind, name, id );
const isUnedited = ! edits || ! Object.keys( edits ).length;
const cackeKey = isUnedited ? getEntityRecord( kind, name, id ) : edits;
let _blocks = parsedBlocksCache.get( cackeKey );

if ( ! _blocks ) {
_blocks = parse( content );
parsedBlocksCache.set( cackeKey, _blocks );
}

return _blocks;
}, [
kind,
name,
id,
editedBlocks,
content,
getEntityRecord,
getEntityRecordEdits,
] );

const updateFootnotes = useCallback(
( _blocks ) => updateFootnotesFromMeta( _blocks, meta ),
[ meta ]
);

const onChange = useCallback(
( newBlocks, options ) => {
const noChange = blocks === newBlocks;
if ( noChange ) {
return __unstableCreateUndoLevel( kind, name, id );
}
const { selection, ...rest } = options;

// We create a new function here on every persistent edit
// to make sure the edit makes the post dirty and creates
// a new undo level.
const edits = {
selection,
content: ( { blocks: blocksForSerialization = [] } ) =>
__unstableSerializeAndClean( blocksForSerialization ),
...updateFootnotes( newBlocks ),
};

editEntityRecord( kind, name, id, edits, {
isCached: false,
...rest,
} );
},
[
kind,
name,
id,
blocks,
updateFootnotes,
__unstableCreateUndoLevel,
editEntityRecord,
]
);

const onInput = useCallback(
( newBlocks, options ) => {
const { selection, ...rest } = options;
const footnotesChanges = updateFootnotes( newBlocks );
const edits = { selection, ...footnotesChanges };

editEntityRecord( kind, name, id, edits, {
isCached: true,
...rest,
} );
},
[ kind, name, id, updateFootnotes, editEntityRecord ]
);

return [ blocks, onInput, onChange ];
}
3 changes: 3 additions & 0 deletions packages/core-data/src/hooks/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,6 @@ export {
default as useResourcePermissions,
__experimentalUseResourcePermissions,
} from './use-resource-permissions';
export { default as useEntityBlockEditor } from './use-entity-block-editor';
export { default as useEntityId } from './use-entity-id';
export { default as useEntityProp } from './use-entity-prop';
Loading