Skip to content
Merged
Changes from 3 commits
Commits
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
68 changes: 68 additions & 0 deletions packages/block-editor/src/components/block-lock/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Block Lock

The `Block Lock` module provides UI components and hooks for managing block locking in the WordPress editor. This includes locking block movement, editing, and removal.

These are private components of the `@wordpress/block-editor` package. They are not exported publicly and are meant to be consumed from within the package only.

## Components

### `BlockLockMenuItem`
A menu item component that allows users to lock or unlock a block via a modal.

#### Props
- `clientId` (string): The unique identifier of the block.

### `BlockLockModal`
A modal component that provides detailed lock options for a block.

#### Props
- `clientId` (string): The unique identifier of the block.
- `onClose` (function): Callback function triggered when the modal is closed.

### `BlockLockToolbar`
A toolbar button component that provides a lock/unlock button for a block.

#### Props
- `clientId` (string): The unique identifier of the block.

## Hook

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The ## Hook section is a bit of a one-off, no other component README here has one, and the hooks that are documented (use-block-display-information, use-block-drop-zone) each live in their own folder with their own README.

Since useBlockLock ships from block-lock/index.js rather than its own folder, I don't think there's a clear precedent.

Happy to leave it as-is.


### `useBlockLock`
A custom hook that returns lock status and permissions for a given block.

#### Parameters
- `clientId` (string): The unique identifier of the block.

#### Returns
An object containing:
- `isEditLocked` (boolean): Whether editing the block is locked.
- `isMoveLocked` (boolean): Whether moving the block is locked.
- `isRemoveLocked` (boolean): Whether removing the block is locked.
- `canLock` (boolean): Whether the block type allows locking.
- `isLocked` (boolean): Whether any of the block's lock features are applied.

## Usage

```jsx
/**
* Internal dependencies
*/
import { BlockLockMenuItem, BlockLockToolbar } from '../block-lock';

function MyBlockControls( { clientId } ) {
return (
<>
<BlockLockToolbar clientId={ clientId } />
<BlockLockMenuItem clientId={ clientId } />
</>
);
}
```

## Implementation Details
- The `BlockLockMenuItem` and `BlockLockToolbar` components toggle the `BlockLockModal`.
- The modal allows users to specify which lock features to apply.
- The `useBlockLock` hook determines the lock state and permissions based on the block's settings and editor state.

This module enhances block editing control by allowing users to enforce restrictions on movement, editing, and removal.

Loading