Components, DataViews and Admin Screens

{
	"name": "lumen-catalog",
	"version": "0.1.0",
	"private": true,
	"scripts": {
		"build": "wp-scripts build books=./src/admin/books/index.js --output-path=build/admin",
		"start": "wp-scripts start books=./src/admin/books/index.js --output-path=build/admin",
		"lint:js": "wp-scripts lint-js src/admin",
		"lint:style": "wp-scripts lint-style \"src/**/*.scss\""
	},
	"devDependencies": {
		"@wordpress/scripts": "37.0.0",
		"stylelint": "17.16.0"
	},
	"dependencies": {
		"@wordpress/components": "37.0.0",
		"@wordpress/core-data": "7.51.0",
		"@wordpress/data": "10.51.0",
		"@wordpress/dataviews": "17.2.0",
		"@wordpress/element": "8.3.0",
		"@wordpress/i18n": "6.24.0",
		"@wordpress/icons": "15.2.0",
		"@wordpress/notices": "5.51.0",
		"@wordpress/theme": "1.0.0"
	},
	"overrides": {
		"@wordpress/theme": {
			"stylelint": "$stylelint"
		}
	}
}

<?php
/**
 * Catalogue > Books: a React screen built with DataViews.
 *
 * @package Lumen\Catalog
 */

namespace Lumen\Catalog;

defined( 'ABSPATH' ) || exit;

/** Registers the submenu page and loads the built React app on it only. */
final class BooksScreen {

	public const SLUG   = 'lumen-catalog-books';
	public const HANDLE = 'lumen-catalog-books';

	/** @var string Hook suffix returned by add_submenu_page(). */
	private static $hook = '';

	/** Called from Plugin::boot() in admin requests. */
	public static function register(): void {
		// Priority 20: the parent "Catalogue" menu is added at the default priority 10.
		add_action( 'admin_menu', array( self::class, 'add_page' ), 20 );
		add_action( 'admin_enqueue_scripts', array( self::class, 'enqueue' ) );
	}

	/** Adds Catalogue > Books, first under Overview, for anyone who can edit books. */
	public static function add_page(): void {
		$title      = __( 'Books', 'lumen-catalog' );
		self::$hook = (string) add_submenu_page( 'lumen-catalog', $title, $title, 'edit_lp_books', self::SLUG, array( self::class, 'render' ), 1 );
	}

	/** Prints the mount point; React replaces its content. */
	public static function render(): void {
		printf(
			'<div class="wrap"><h1>%s</h1><div id="lumen-books-root"><p>%s</p></div></div>',
			esc_html( get_admin_page_title() ),
			esc_html__( 'Loading books…', 'lumen-catalog' )
		);
	}

	/** Enqueues the bundle with the dependencies wp-scripts computed, on this screen only. */
	public static function enqueue( string $hook_suffix ): void {
		if ( $hook_suffix !== self::$hook ) {
			return;
		}
		$url   = plugin_dir_url( __DIR__ ) . 'build/admin/';
		$asset = require plugin_dir_path( __DIR__ ) . 'build/admin/books.asset.php';

		wp_enqueue_script( self::HANDLE, $url . 'books.js', $asset['dependencies'], $asset['version'], array( 'in_footer' => true ) );
		wp_set_script_translations( self::HANDLE, 'lumen-catalog', plugin_dir_path( __DIR__ ) . 'languages' );
		// books.css holds the bundled DataViews styles; wp-components brings the wp-theme tokens.
		wp_enqueue_style( self::HANDLE, $url . 'books.css', array( 'wp-components' ), $asset['version'] );
	}
}

/** Entry point: mounts the Books app inside the ThemeProvider of the 7.1 design system. */
import { createRoot } from '@wordpress/element';
import { ThemeProvider } from '@wordpress/theme';
import BooksApp from './app';
import './books.scss';

const container = document.getElementById( 'lumen-books-root' );
if ( container ) {
	createRoot( container ).render(
		<ThemeProvider color={ { primary: '#a3271f' } } cornerRadius="moderate">
			<BooksApp />
		</ThemeProvider>
	);
}

@import "@wordpress/dataviews/build-style/style.css";

// Tokens come from the wp-theme stylesheet (a wp-components dependency).
#lumen-books-root {
	margin-top: 16px;
	background: var(--wpds-color-background-surface-neutral-strong);
	border: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral-weak);
	border-radius: var(--wpds-border-radius-lg);
	overflow: hidden;
}

/** Field definitions shared by DataViews (the list) and DataForm (quick edit). */
import { __ } from '@wordpress/i18n';

const STATUSES = [
	{ value: 'publish', label: __( 'Published', 'lumen-catalog' ) },
	{ value: 'future', label: __( 'Scheduled', 'lumen-catalog' ) },
	{ value: 'draft', label: __( 'Draft', 'lumen-catalog' ) },
	{ value: 'pending', label: __( 'Pending review', 'lumen-catalog' ) },
	{ value: 'private', label: __( 'Private', 'lumen-catalog' ) },
	{ value: 'lp_out_of_print', label: __( 'Out of print', 'lumen-catalog' ) },
];
const NO_FILTER = { filterBy: false, enableSorting: false };
const ANY_OF = { filterBy: { operators: [ 'isAny' ] }, enableSorting: false };
const meta = ( key ) => ( {
	getValue: ( { item } ) => item.meta?.[ key ],
	setValue: ( { value } ) => ( { meta: { [ key ]: value } } ),
} );

export const getFields = ( genres ) => [
	{
		id: 'title',
		type: 'text',
		label: __( 'Title', 'lumen-catalog' ),
		getValue: ( { item } ) => item.title?.raw ?? item.title?.rendered ?? '',
		setValue: ( { value } ) => ( { title: value } ),
		enableHiding: false,
		filterBy: false,
		isValid: { required: true },
	},
	{ id: 'status', type: 'text', label: __( 'Status', 'lumen-catalog' ), elements: STATUSES, ...ANY_OF },
	{
		id: 'lp_genre',
		type: 'array',
		label: __( 'Genre', 'lumen-catalog' ),
		elements: genres.map( ( term ) => ( { value: term.id, label: term.name } ) ),
		render: ( { item } ) =>
			( item.lp_genre ?? [] ).map( ( id ) => genres.find( ( t ) => t.id === id )?.name ?? id ).join( ', ' ),
		...ANY_OF,
	},
	{
		id: 'lp_isbn',
		type: 'text',
		label: __( 'ISBN-13', 'lumen-catalog' ),
		placeholder: '978-1-23456-789-7',
		...meta( 'lp_isbn' ),
		...NO_FILTER,
		isValid: { pattern: '^(97[89]-[0-9]{1,5}-[0-9]{1,7}-[0-9]{1,7}-[0-9])?$' },
	},
	{ id: 'lp_pages', type: 'integer', label: __( 'Pages', 'lumen-catalog' ), ...meta( 'lp_pages' ), ...NO_FILTER, isValid: { min: 0, max: 5000 } },
	{ id: 'lp_published_on', type: 'date', label: __( 'Publication date', 'lumen-catalog' ), ...meta( 'lp_published_on' ), ...NO_FILTER },
	{ id: 'date', type: 'datetime', label: __( 'Added', 'lumen-catalog' ), filterBy: false, readOnly: true },
];

export const QUICK_EDIT_FORM = {
	layout: { type: 'regular', labelPosition: 'top' },
	fields: [
		'title',
		'status',
		{ id: 'edition', label: __( 'Edition', 'lumen-catalog' ), layout: { type: 'row', alignment: 'start' }, children: [ 'lp_isbn', 'lp_pages' ] },
		'lp_published_on',
	],
};

/** The Books screen: DataViews over /wp/v2/lp_book through the core-data store. */
import { useMemo, useState } from '@wordpress/element';
import { useDispatch, useSelect } from '@wordpress/data';
import { store as coreStore, useEntityRecords } from '@wordpress/core-data';
import { store as noticesStore } from '@wordpress/notices';
import { Button, Flex, SnackbarList } from '@wordpress/components';
import { DataViews } from '@wordpress/dataviews/wp';
import { __, _n, sprintf } from '@wordpress/i18n';
import { pencil, trash } from '@wordpress/icons';
import { getFields } from './fields';
import QuickEdit from './quick-edit';

const DEFAULT_VIEW = {
	...{ type: 'table', search: '', page: 1, perPage: 20, filters: [], titleField: 'title' },
	sort: { field: 'date', direction: 'desc' },
	fields: [ 'status', 'lp_genre', 'lp_isbn', 'lp_pages', 'date' ],
};
const DEFAULT_LAYOUTS = {
	table: { layout: { styles: { lp_pages: { align: 'end' } } } },
	grid: { fields: [ 'lp_genre', 'lp_isbn' ], layout: { badgeFields: [ 'status' ] } },
	list: { fields: [ 'status', 'lp_isbn' ] },
	activity: { fields: [ 'status' ] },
};

// Translates the DataViews view into REST query arguments.
function toQuery( view ) {
	const query = {
		context: 'edit',
		per_page: view.perPage,
		page: view.page,
		search: view.search || undefined,
		orderby: view.sort?.field,
		order: view.sort?.direction,
		status: 'publish,future,draft,pending,private,lp_out_of_print',
		_fields: 'id,title,status,date,meta,lp_genre',
	};
	for ( const { field, value } of view.filters ?? [] ) {
		if ( value?.length && ( field === 'status' || field === 'lp_genre' ) ) {
			query[ field ] = value.join( ',' );
		}
	}
	return query;
}

function ConfirmTrash( { items, closeModal, onActionPerformed } ) {
	const { deleteEntityRecord } = useDispatch( coreStore );
	const { createSuccessNotice, createErrorNotice } = useDispatch( noticesStore );
	const onConfirm = async () => {
		const opts = { throwOnError: true };
		try {
			// Without force: true the posts go to the trash.
			await Promise.all( items.map( ( item ) => deleteEntityRecord( 'postType', 'lp_book', item.id, {}, opts ) ) );
			createSuccessNotice( __( 'Moved to trash.', 'lumen-catalog' ), { type: 'snackbar' } );
			onActionPerformed?.( items );
		} catch ( error ) {
			createErrorNotice( error.message, { type: 'snackbar' } );
		}
		closeModal?.();
	};
	return (
		<Flex justify="flex-end">
			<Button __next40pxDefaultSize variant="tertiary" onClick={ closeModal }>{ __( 'Cancel', 'lumen-catalog' ) }</Button>
			<Button __next40pxDefaultSize variant="primary" isDestructive onClick={ onConfirm }>{ __( 'Move to trash', 'lumen-catalog' ) }</Button>
		</Flex>
	);
}

const ACTIONS = [
	{ id: 'quick-edit', label: __( 'Quick edit', 'lumen-catalog' ), icon: pencil, isPrimary: true, RenderModal: QuickEdit },
	{
		id: 'trash',
		label: __( 'Move to trash', 'lumen-catalog' ),
		icon: trash,
		supportsBulk: true,
		modalHeader: ( items ) =>
			sprintf(
				/* translators: %d: number of books. */
				_n( 'Trash %d book?', 'Trash %d books?', items.length, 'lumen-catalog' ),
				items.length
			),
		RenderModal: ConfirmTrash,
	},
];

export default function BooksApp() {
	const [ view, setView ] = useState( DEFAULT_VIEW );
	const query = useMemo( () => toQuery( view ), [ view ] );
	const { records, isResolving, totalItems, totalPages } = useEntityRecords( 'postType', 'lp_book', query );
	const { records: genres } = useEntityRecords( 'taxonomy', 'lp_genre', { per_page: 100, _fields: 'id,name' } );
	const fields = useMemo( () => getFields( genres ?? [] ), [ genres ] );
	const notices = useSelect( ( select ) => select( noticesStore ).getNotices(), [] );
	const { removeNotice } = useDispatch( noticesStore );

	return (
		<>
			<DataViews
				data={ records ?? [] }
				fields={ fields }
				view={ view }
				onChangeView={ setView }
				actions={ ACTIONS }
				defaultLayouts={ DEFAULT_LAYOUTS }
				isLoading={ isResolving }
				paginationInfo={ { totalItems: totalItems ?? 0, totalPages: totalPages ?? 0 } }
				getItemId={ ( item ) => String( item.id ) }
				searchLabel={ __( 'Search books', 'lumen-catalog' ) }
				empty={ <p>{ __( 'No books match these filters.', 'lumen-catalog' ) }</p> }
			/>
			<SnackbarList notices={ notices.filter( ( n ) => n.type === 'snackbar' ) } onRemove={ removeNotice } />
		</>
	);
}

/** Quick edit: a DataForm in the action modal, saved with saveEntityRecord(). */
import { useMemo, useState } from '@wordpress/element';
import { useDispatch, useSelect } from '@wordpress/data';
import { store as coreStore } from '@wordpress/core-data';
import { store as noticesStore } from '@wordpress/notices';
import { Button, Flex } from '@wordpress/components';
import { DataForm, useFormValidity } from '@wordpress/dataviews/wp';
import { __ } from '@wordpress/i18n';
import { getFields, QUICK_EDIT_FORM } from './fields';

const FIELDS = getFields( [] );

export default function QuickEdit( { items: [ book ], closeModal, onActionPerformed } ) {
	const [ edits, setEdits ] = useState( {} );
	const [ isSaving, setIsSaving ] = useState( false );
	const { saveEntityRecord } = useDispatch( coreStore );
	const { createSuccessNotice, createErrorNotice } = useDispatch( noticesStore );
	const canEdit = useSelect(
		( select ) => select( coreStore ).canUser( 'update', { kind: 'postType', name: 'lp_book', id: book.id } ),
		[ book.id ]
	);
	// Meta edits arrive one key at a time; merge them so none is lost.
	const merge = ( a, b ) => ( { ...a, ...b, meta: { ...a.meta, ...b.meta } } );
	const data = useMemo( () => merge( book, edits ), [ book, edits ] );
	const { validity, isValid } = useFormValidity( data, FIELDS, QUICK_EDIT_FORM );

	const onSubmit = async ( event ) => {
		event.preventDefault();
		setIsSaving( true );
		try {
			await saveEntityRecord( 'postType', 'lp_book', { id: book.id, ...edits }, { throwOnError: true } );
			createSuccessNotice( __( 'Book updated.', 'lumen-catalog' ), { type: 'snackbar' } );
			onActionPerformed?.( [ book ] );
			closeModal?.();
		} catch ( error ) {
			createErrorNotice( error.message, { type: 'snackbar' } );
			setIsSaving( false );
		}
	};

	return (
		<form onSubmit={ onSubmit }>
			<DataForm
				data={ data }
				fields={ FIELDS }
				form={ QUICK_EDIT_FORM }
				validity={ validity }
				onChange={ ( change ) => setEdits( ( prev ) => merge( prev, change ) ) }
			/>
			<Flex justify="flex-end" style={ { marginTop: 24 } }>
				<Button __next40pxDefaultSize variant="tertiary" onClick={ closeModal }>{ __( 'Cancel', 'lumen-catalog' ) }</Button>
				<Button __next40pxDefaultSize variant="primary" type="submit" isBusy={ isSaving } accessibleWhenDisabled
					disabled={ ! isValid || ! canEdit || isSaving || ! Object.keys( edits ).length }>
					{ __( 'Save', 'lumen-catalog' ) }
				</Button>
			</Flex>
		</form>
	);
}