@wp-typia/project-tools 0.11.1

package/templates/_shared/compound/persistence/src/blocks/{{slugKebabCase}}/data.ts.mustache

@@ -0,0 +1,192 @@
+import {
+	useEndpointMutation,
+	useEndpointQuery,
+	type UseEndpointMutationOptions,
+	type UseEndpointQueryOptions,
+} from '@wp-typia/rest/react';
+
+import type {
+	{{pascalCase}}StateQuery,
+	{{pascalCase}}StateResponse,
+	{{pascalCase}}WriteStateRequest,
+} from './api-types';
+import {
+	resolveRestNonce,
+	stateEndpoint,
+	writeStateEndpoint,
+} from './api';
+
+{{#isAuthenticatedPersistencePolicy}}
+function buildWriteCallOptions( restNonce?: string ) {
+	const nonce = resolveRestNonce( restNonce );
+
+	return nonce
+		? {
+				requestOptions: {
+					headers: {
+						'X-WP-Nonce': nonce,
+					},
+				},
+			}
+		: undefined;
+}
+{{/isAuthenticatedPersistencePolicy}}
+
+interface WriteStateMutationContext< Context > {
+	previous:
+		| {{pascalCase}}StateResponse
+		| undefined;
+	userContext: Context | undefined;
+}
+
+export interface Use{{pascalCase}}StateQueryOptions<
+	Selected = {{pascalCase}}StateResponse,
+> extends Omit<
+	UseEndpointQueryOptions<
+		{{pascalCase}}StateQuery,
+		{{pascalCase}}StateResponse,
+		Selected
+	>,
+	'resolveCallOptions'
+> {
+	{{#isAuthenticatedPersistencePolicy}}
+	restNonce?: string;
+	{{/isAuthenticatedPersistencePolicy}}
+}
+
+export interface UseWrite{{pascalCase}}StateMutationOptions<
+	Context = unknown,
+> extends Omit<
+	UseEndpointMutationOptions<
+		{{pascalCase}}WriteStateRequest,
+		{{pascalCase}}StateResponse,
+		WriteStateMutationContext< Context >
+	>,
+	'invalidate' | 'onError' | 'onMutate'{{#isAuthenticatedPersistencePolicy}} | 'resolveCallOptions'{{/isAuthenticatedPersistencePolicy}}
+> {
+	onError?: (
+		error: unknown,
+		request: {{pascalCase}}WriteStateRequest,
+		client: import('@wp-typia/rest/react').EndpointDataClient,
+		context: Context | undefined
+	) => void | Promise<void>;
+	onMutate?: (
+		request: {{pascalCase}}WriteStateRequest,
+		client: import('@wp-typia/rest/react').EndpointDataClient
+	) => Context | Promise<Context>;
+	{{#isAuthenticatedPersistencePolicy}}
+	restNonce?: string;
+	{{/isAuthenticatedPersistencePolicy}}
+}
+
+export function use{{pascalCase}}StateQuery<
+	Selected = {{pascalCase}}StateResponse,
+>(
+	request: {{pascalCase}}StateQuery,
+	options: Use{{pascalCase}}StateQueryOptions< Selected > = {}
+) {
+	{{#isAuthenticatedPersistencePolicy}}
+	const {
+		restNonce,
+		...queryOptions
+	} = options;
+
+	return useEndpointQuery( stateEndpoint, request, {
+		...queryOptions,
+		resolveCallOptions: () => buildWriteCallOptions( restNonce ),
+	} );
+	{{/isAuthenticatedPersistencePolicy}}
+	{{^isAuthenticatedPersistencePolicy}}
+	return useEndpointQuery( stateEndpoint, request, options );
+	{{/isAuthenticatedPersistencePolicy}}
+}
+
+export function useWrite{{pascalCase}}StateMutation<
+	Context = unknown,
+>(
+	options: UseWrite{{pascalCase}}StateMutationOptions< Context > = {}
+) {
+	const {
+		onError,
+		onMutate,
+		{{#isAuthenticatedPersistencePolicy}}
+		restNonce,
+		{{/isAuthenticatedPersistencePolicy}}
+		...mutationOptions
+	} = options;
+
+	return useEndpointMutation( writeStateEndpoint, {
+		...mutationOptions,
+		invalidate: ( _data, request ) => ( {
+			endpoint: stateEndpoint,
+			request: {
+				postId: request.postId,
+				resourceKey: request.resourceKey,
+			},
+		} ),
+		onError: async ( error, request, client, context ) => {
+			if ( context?.previous ) {
+				client.setData(
+					stateEndpoint,
+					{
+						postId: request.postId,
+						resourceKey: request.resourceKey,
+					},
+					context.previous
+				);
+			}
+
+			await onError?.( error, request, client, context?.userContext );
+		},
+		onMutate: async ( request, client ) => {
+			const queryRequest = {
+				postId: request.postId,
+				resourceKey: request.resourceKey,
+			} satisfies {{pascalCase}}StateQuery;
+			const previous = client.getData(
+				stateEndpoint,
+				queryRequest
+			);
+
+			if ( previous !== undefined ) {
+				client.setData(
+					stateEndpoint,
+					queryRequest,
+					( current ) => {
+						if ( ! current ) {
+							return current;
+						}
+
+						return {
+							...current,
+							count: Math.max(
+								0,
+								current.count + ( request.delta ?? 1 )
+							),
+						};
+					}
+				);
+			}
+
+			let userContext: Context | undefined;
+			try {
+				userContext = onMutate
+					? await onMutate( request, client )
+					: undefined;
+			} catch ( error ) {
+				if ( previous !== undefined ) {
+					client.setData( stateEndpoint, queryRequest, previous );
+				}
+				throw error;
+			}
+
+			return {
+				previous,
+				userContext,
+			};
+		},
+		{{#isAuthenticatedPersistencePolicy}}
+		resolveCallOptions: () => buildWriteCallOptions( restNonce ),
+		{{/isAuthenticatedPersistencePolicy}}
+	} );
+}

package/templates/_shared/compound/persistence/src/blocks/{{slugKebabCase}}/edit.tsx.mustache

@@ -0,0 +1,123 @@
+import { __ } from '@wordpress/i18n';
+import {
+	InspectorControls,
+	InnerBlocks,
+	RichText,
+	useBlockProps,
+} from '@wordpress/block-editor';
+import {
+	Notice,
+	PanelBody,
+	TextControl,
+	ToggleControl,
+} from '@wordpress/components';
+
+import {
+	ALLOWED_CHILD_BLOCKS,
+	DEFAULT_CHILD_TEMPLATE,
+} from './children';
+import { useTypiaValidation } from './hooks';
+import type { {{pascalCase}}Attributes } from './types';
+import {
+	createAttributeUpdater,
+	validate{{pascalCase}}Attributes,
+} from './validators';
+
+export default function Edit( {
+	attributes,
+	setAttributes,
+}: {
+	attributes: {{pascalCase}}Attributes;
+	setAttributes: ( attrs: Partial< {{pascalCase}}Attributes > ) => void;
+} ) {
+	const { errorMessages, isValid } = useTypiaValidation(
+		attributes,
+		validate{{pascalCase}}Attributes
+	);
+	const updateAttribute = createAttributeUpdater( attributes, setAttributes );
+	const blockProps = useBlockProps( {
+		className: '{{cssClassName}}',
+	} );
+
+	return (
+		<>
+			<InspectorControls>
+				<PanelBody title={ __( 'Compound Settings', '{{textDomain}}' ) }>
+					<ToggleControl
+						label={ __( 'Show dividers between items', '{{textDomain}}' ) }
+						checked={ attributes.showDividers ?? true }
+						onChange={ ( value ) => updateAttribute( 'showDividers', value ) }
+					/>
+					<ToggleControl
+						label={ __( 'Show persisted count', '{{textDomain}}' ) }
+						checked={ attributes.showCount ?? true }
+						onChange={ ( value ) => updateAttribute( 'showCount', value ) }
+					/>
+					<TextControl
+						label={ __( 'Button label', '{{textDomain}}' ) }
+						value={ attributes.buttonLabel ?? 'Persist Count' }
+						onChange={ ( buttonLabel ) => updateAttribute( 'buttonLabel', buttonLabel ) }
+					/>
+					<TextControl
+						label={ __( 'Resource key', '{{textDomain}}' ) }
+						value={ attributes.resourceKey ?? '' }
+						onChange={ ( resourceKey ) => updateAttribute( 'resourceKey', resourceKey ) }
+						help={ __( 'Stable key used by the persisted counter endpoint.', '{{textDomain}}' ) }
+					/>
+					<Notice status="info" isDismissible={ false }>
+						{ __( 'Storage mode: {{dataStorageMode}}', '{{textDomain}}' ) }
+					</Notice>
+					<Notice status="info" isDismissible={ false }>
+						{ __( 'Persistence policy: {{persistencePolicy}}', '{{textDomain}}' ) }
+					</Notice>
+				</PanelBody>
+				{ ! isValid && (
+					<PanelBody title={ __( 'Validation Errors', '{{textDomain}}' ) } initialOpen>
+						{ errorMessages.map( ( error, index ) => (
+							<Notice key={ index } status="error" isDismissible={ false }>
+								{ error }
+							</Notice>
+						) ) }
+					</PanelBody>
+				) }
+			</InspectorControls>
+			<div { ...blockProps }>
+				<RichText
+					tagName="h3"
+					className="{{cssClassName}}__heading"
+					value={ attributes.heading }
+					onChange={ ( heading ) => updateAttribute( 'heading', heading ) }
+					placeholder={ __( {{titleJson}}, '{{textDomain}}' ) }
+				/>
+				<RichText
+					tagName="p"
+					className="{{cssClassName}}__intro"
+					value={ attributes.intro ?? '' }
+					onChange={ ( intro ) => updateAttribute( 'intro', intro ) }
+					placeholder={ __(
+						'Add and reorder internal items inside this compound block.',
+						'{{textDomain}}'
+					) }
+				/>
+				{ ! isValid && (
+					<Notice status="error" isDismissible={ false }>
+						<ul>
+							{ errorMessages.map( ( error, index ) => <li key={ index }>{ error }</li> ) }
+						</ul>
+					</Notice>
+				) }
+				<p className="{{cssClassName}}__meta">
+					{ __( 'Resource key:', '{{textDomain}}' ) } { attributes.resourceKey || '—' }
+				</p>
+				<div className="{{cssClassName}}__items">
+					<InnerBlocks
+						allowedBlocks={ ALLOWED_CHILD_BLOCKS }
+						renderAppender={ InnerBlocks.ButtonBlockAppender }
+						template={ DEFAULT_CHILD_TEMPLATE }
+						templateLock={ false }
+					/>
+				</div>
+			</div>
+		</>
+	);
+}

package/templates/_shared/compound/persistence/src/blocks/{{slugKebabCase}}/hooks.ts.mustache

@@ -0,0 +1,11 @@
+export {
+	formatValidationError,
+	formatValidationErrors,
+	useTypiaValidation,
+} from '../../hooks';
+
+export type {
+	TypiaValidationError,
+	ValidationResult,
+	ValidationState,
+} from '../../hooks';

package/templates/_shared/compound/persistence/src/blocks/{{slugKebabCase}}/interactivity.ts.mustache

@@ -0,0 +1,132 @@
+import { getContext, store } from '@wordpress/interactivity';
+import { generatePublicWriteRequestId } from '@wp-typia/block-runtime/identifiers';
+
+import { fetchState, writeState } from './api';
+import type { {{pascalCase}}Context, {{pascalCase}}State } from './types';
+
+function hasExpiredPublicWriteToken(
+	context: {{pascalCase}}Context
+): boolean {
+	return (
+		context.persistencePolicy === 'public' &&
+		typeof context.publicWriteExpiresAt === 'number' &&
+		context.publicWriteExpiresAt > 0 &&
+		Date.now() >= context.publicWriteExpiresAt * 1000
+	);
+}
+
+function getWriteBlockedMessage(
+	context: {{pascalCase}}Context
+): string {
+	return context.persistencePolicy === 'authenticated'
+		? 'Sign in to persist this counter.'
+		: 'Reload the page to refresh this write token.';
+}
+
+const { actions, state } = store( '{{slugKebabCase}}', {
+	state: {
+		canWrite: false,
+		count: 0,
+		error: undefined,
+		isHydrated: false,
+		isLoading: false,
+		isSaving: false,
+	} as {{pascalCase}}State,
+
+	actions: {
+		async loadCounter() {
+			const context = getContext< {{pascalCase}}Context >();
+			if ( context.postId <= 0 || ! context.resourceKey ) {
+				return;
+			}
+
+			state.isLoading = true;
+			state.error = undefined;
+
+			try {
+				const result = await fetchState( {
+					postId: context.postId,
+					resourceKey: context.resourceKey,
+				} );
+				if ( ! result.isValid || ! result.data ) {
+					state.error = result.errors[ 0 ]?.expected ?? 'Unable to load counter';
+					return;
+				}
+				context.count = result.data.count;
+				context.storage = result.data.storage;
+				state.count = result.data.count;
+			} catch ( error ) {
+				state.error =
+					error instanceof Error ? error.message : 'Unknown loading error';
+			} finally {
+				state.isLoading = false;
+			}
+		},
+		async increment() {
+			const context = getContext< {{pascalCase}}Context >();
+			if ( context.postId <= 0 || ! context.resourceKey ) {
+				return;
+			}
+			if ( hasExpiredPublicWriteToken( context ) ) {
+				context.canWrite = false;
+				state.canWrite = false;
+				state.error = getWriteBlockedMessage( context );
+				return;
+			}
+			if ( ! context.canWrite || ! state.canWrite ) {
+				state.error = getWriteBlockedMessage( context );
+				return;
+			}
+
+			state.isSaving = true;
+			state.error = undefined;
+
+			try {
+				const result = await writeState( {
+					delta: 1,
+					postId: context.postId,
+					publicWriteRequestId:
+						context.persistencePolicy === 'public'
+							? generatePublicWriteRequestId()
+							: undefined,
+					publicWriteToken:
+						context.persistencePolicy === 'public' &&
+						typeof context.publicWriteToken === 'string' &&
+						context.publicWriteToken.length > 0
+							? context.publicWriteToken
+							: undefined,
+					resourceKey: context.resourceKey,
+				}, context.restNonce );
+				if ( ! result.isValid || ! result.data ) {
+					state.error = result.errors[ 0 ]?.expected ?? 'Unable to update counter';
+					return;
+				}
+				context.count = result.data.count;
+				context.storage = result.data.storage;
+				state.count = result.data.count;
+			} catch ( error ) {
+				state.error =
+					error instanceof Error ? error.message : 'Unknown update error';
+			} finally {
+				state.isSaving = false;
+			}
+		},
+	},
+
+	callbacks: {
+		init() {
+			const context = getContext< {{pascalCase}}Context >();
+			context.canWrite =
+				context.canWrite && ! hasExpiredPublicWriteToken( context );
+			state.canWrite = context.canWrite;
+			state.count = context.count;
+		},
+		mounted() {
+			state.isHydrated = true;
+			if ( typeof document !== 'undefined' ) {
+				document.documentElement.dataset[ '{{slugCamelCase}}Hydrated' ] = 'true';
+			}
+			void actions.loadCounter();
+		},
+	},
+} );

package/templates/_shared/compound/persistence/src/blocks/{{slugKebabCase}}/render.php.mustache

@@ -0,0 +1,158 @@
+<?php
+/**
+ * Dynamic render entry for the {{title}} compound parent block.
+ *
+ * @package {{pascalCase}}
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+$validator_path = __DIR__ . '/typia-validator.php';
+if ( ! file_exists( $validator_path ) ) {
+	return '';
+}
+
+$validator = require $validator_path;
+if ( ! is_object( $validator ) || ! method_exists( $validator, 'apply_defaults' ) || ! method_exists( $validator, 'validate' ) ) {
+	return '';
+}
+
+$normalized         = $validator->apply_defaults( is_array( $attributes ) ? $attributes : array() );
+$validation         = $validator->validate( $normalized );
+$resource_key       = isset( $normalized['resourceKey'] ) ? (string) $normalized['resourceKey'] : '';
+$heading           = isset( $normalized['heading'] ) ? (string) $normalized['heading'] : '{{title}}';
+$intro             = isset( $normalized['intro'] ) ? (string) $normalized['intro'] : '';
+$button_label      = isset( $normalized['buttonLabel'] ) ? (string) $normalized['buttonLabel'] : 'Persist Count';
+$show_count        = ! empty( $normalized['showCount'] );
+$show_dividers     = ! empty( $normalized['showDividers'] );
+$post_id           = is_object( $block ) && isset( $block->context['postId'] )
+	? (int) $block->context['postId']
+	: (int) get_queried_object_id();
+$storage_mode      = '{{dataStorageMode}}';
+$persistence_policy = '{{persistencePolicy}}';
+$can_write         = false;
+$notice_message    = 'authenticated' === $persistence_policy
+	? __( 'Sign in to persist this counter.', '{{textDomain}}' )
+	: __( 'Reload the page to refresh this write token.', '{{textDomain}}' );
+
+if ( empty( $validation['valid'] ) || '' === $resource_key ) {
+	return '';
+}
+
+$context = array(
+	'buttonLabel'       => $button_label,
+	'canWrite'          => false,
+	'count'             => 0,
+	'persistencePolicy' => $persistence_policy,
+	'postId'            => (int) $post_id,
+	'resourceKey'       => $resource_key,
+	'showCount'         => $show_count,
+	'storage'           => $storage_mode,
+);
+
+if ( 'authenticated' === $persistence_policy ) {
+	$can_write = $post_id > 0 && is_user_logged_in();
+	if ( $can_write ) {
+		$context['restNonce'] = wp_create_nonce( 'wp_rest' );
+	}
+} elseif ( $post_id > 0 && function_exists( '{{phpPrefix}}_create_public_write_token' ) ) {
+	$public_write = {{phpPrefix}}_create_public_write_token( (int) $post_id, $resource_key );
+	if ( is_array( $public_write ) ) {
+		$token      = isset( $public_write['token'] ) ? (string) $public_write['token'] : '';
+		$expires_at = isset( $public_write['expiresAt'] ) ? (int) $public_write['expiresAt'] : 0;
+
+		if ( '' !== $token ) {
+			$context['publicWriteToken'] = $token;
+			$can_write                   = true;
+		}
+
+		if ( $expires_at > 0 ) {
+			$context['publicWriteExpiresAt'] = $expires_at;
+		}
+	}
+}
+
+$context['canWrite'] = $can_write;
+
+$allowed_inner_html = wp_kses_allowed_html( 'post' );
+
+foreach ( $allowed_inner_html as &$allowed_attributes ) {
+	if ( ! is_array( $allowed_attributes ) ) {
+		continue;
+	}
+
+	$allowed_attributes['data-wp-bind--disabled'] = true;
+	$allowed_attributes['data-wp-bind--hidden'] = true;
+	$allowed_attributes['data-wp-bind--value'] = true;
+	$allowed_attributes['data-wp-class'] = true;
+	$allowed_attributes['data-wp-class--active'] = true;
+	$allowed_attributes['data-wp-context'] = true;
+	$allowed_attributes['data-wp-init'] = true;
+	$allowed_attributes['data-wp-interactive'] = true;
+	$allowed_attributes['data-wp-on--click'] = true;
+	$allowed_attributes['data-wp-on--mouseenter'] = true;
+	$allowed_attributes['data-wp-on--mouseleave'] = true;
+	$allowed_attributes['data-wp-run--mounted'] = true;
+	$allowed_attributes['data-wp-style--width'] = true;
+	$allowed_attributes['data-wp-text'] = true;
+}
+unset( $allowed_attributes );
+
+$sanitized_content = wp_kses( $content, $allowed_inner_html );
+
+$wrapper_attributes = get_block_wrapper_attributes(
+	array(
+		'class'                => '{{cssClassName}}',
+		'data-show-dividers'   => $show_dividers ? 'true' : 'false',
+		'data-wp-context'      => wp_json_encode( $context ),
+		'data-wp-init'         => 'callbacks.init',
+		'data-wp-interactive'  => '{{slugKebabCase}}',
+		'data-wp-run--mounted' => 'callbacks.mounted',
+	)
+);
+?>
+
+<div <?php echo $wrapper_attributes; ?>>
+	<h3 class="{{cssClassName}}__heading"><?php echo esc_html( $heading ); ?></h3>
+	<?php if ( '' !== $intro ) : ?>
+		<p class="{{cssClassName}}__intro"><?php echo esc_html( $intro ); ?></p>
+	<?php endif; ?>
+	<?php if ( ! $can_write ) : ?>
+		<p class="{{cssClassName}}__notice">
+			<?php echo esc_html( $notice_message ); ?>
+		</p>
+	<?php endif; ?>
+	<p
+		class="{{cssClassName}}__error"
+		role="status"
+		aria-live="polite"
+		aria-atomic="true"
+		data-wp-bind--hidden="!state.error"
+		data-wp-text="state.error"
+		hidden
+	></p>
+	<?php if ( $show_count ) : ?>
+		<div class="{{cssClassName}}__counter">
+			<span
+				class="{{cssClassName}}__count"
+				role="status"
+				aria-live="polite"
+				aria-atomic="true"
+				data-wp-text="state.count"
+			>0</span>
+			<button
+				type="button"
+				<?php echo $can_write ? '' : 'disabled'; ?>
+				data-wp-bind--disabled="!context.canWrite"
+				data-wp-on--click="actions.increment"
+			>
+				<?php echo esc_html( $button_label ); ?>
+			</button>
+		</div>
+	<?php endif; ?>
+	<div class="{{cssClassName}}__items">
+		<?php echo $sanitized_content; ?>
+	</div>
+</div>

package/templates/_shared/compound/persistence/src/blocks/{{slugKebabCase}}/save.tsx.mustache

@@ -0,0 +1,3 @@
+export default function Save() {
+	return null;
+}

package/templates/_shared/compound/persistence/src/blocks/{{slugKebabCase}}/types.ts.mustache

@@ -0,0 +1,56 @@
+import type {
+	TypiaValidationError,
+	ValidationResult,
+} from '@wp-typia/block-runtime/validation';
+import { tags } from 'typia';
+
+export type {
+	TypiaValidationError,
+	ValidationResult,
+} from '@wp-typia/block-runtime/validation';
+
+export interface {{pascalCase}}Attributes {
+	heading: string &
+		tags.MinLength< 1 > &
+		tags.MaxLength< 80 > &
+		tags.Default< {{titleJson}} >;
+	intro?: string &
+		tags.MinLength< 1 > &
+		tags.MaxLength< 180 > &
+		tags.Default< 'Add and reorder internal items inside this compound block.' >;
+	showDividers?: boolean & tags.Default< true >;
+	showCount?: boolean & tags.Default< true >;
+	buttonLabel?: string &
+		tags.MinLength< 1 > &
+		tags.MaxLength< 40 > &
+		tags.Default< 'Persist Count' >;
+	resourceKey?: string &
+		tags.MinLength< 1 > &
+		tags.MaxLength< 100 > &
+		tags.Default< 'primary' >;
+}
+
+export interface {{pascalCase}}Context {
+	buttonLabel: string;
+	canWrite: boolean;
+	count: number;
+	persistencePolicy: 'authenticated' | 'public';
+	postId: number;
+	publicWriteExpiresAt?: number;
+	publicWriteToken?: string;
+	resourceKey: string;
+	restNonce?: string;
+	showCount: boolean;
+	storage: 'post-meta' | 'custom-table';
+}
+
+export interface {{pascalCase}}State {
+	canWrite: boolean;
+	count: number;
+	error?: string;
+	isHydrated: boolean;
+	isLoading: boolean;
+	isSaving: boolean;
+}
+
+export type {{pascalCase}}ValidationResult = ValidationResult< {{pascalCase}}Attributes >;