@wp-typia/project-tools 0.11.1

package/templates/_shared/compound/core/scripts/add-compound-child.ts.mustache

@@ -0,0 +1,559 @@
+/* eslint-disable no-console */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PARENT_BLOCK_NAME = '{{namespace}}/{{slugKebabCase}}';
+const PARENT_BLOCK_NAMESPACE = '{{namespace}}';
+const PARENT_BLOCK_SLUG = '{{slugKebabCase}}';
+const PARENT_BLOCK_TITLE = {{titleJson}};
+const PARENT_TYPE_NAME = '{{pascalCase}}';
+const PARENT_STYLE_IMPORT = '../{{slugKebabCase}}/style.scss';
+const PROJECT_ROOT = process.cwd();
+const TEXT_DOMAIN = '{{textDomain}}';
+
+const ALLOWED_CHILD_MARKER = '// add-child: insert new allowed child block names here';
+const BLOCK_CONFIG_MARKER = '// add-child: insert new block config entries here';
+const CHILD_PLACEHOLDER = 'Add supporting details for this internal item.';
+const BLOCK_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+type StarterManifestDocument = {
+	attributes: Record< string, unknown >;
+	manifestVersion: 2;
+	sourceType: string;
+};
+
+function parseArgs() {
+	const args = process.argv.slice( 2 );
+	const parsed: {
+		slug?: string;
+		title?: string;
+	} = {};
+
+	for ( let index = 0; index < args.length; index += 1 ) {
+		const arg = args[ index ];
+		if ( arg === '--slug' ) {
+			const value = args[ index + 1 ];
+			if ( ! value || value.startsWith( '--' ) ) {
+				throw new Error( '--slug requires a value.' );
+			}
+			parsed.slug = value;
+			index += 1;
+			continue;
+		}
+
+		if ( arg === '--title' ) {
+			const value = args[ index + 1 ];
+			if ( ! value || value.startsWith( '--' ) ) {
+				throw new Error( '--title requires a value.' );
+			}
+			parsed.title = value;
+			index += 1;
+			continue;
+		}
+	}
+
+	return parsed;
+}
+
+function toKebabCase( input: string ): string {
+	return input
+		.trim()
+		.replace( /([a-z0-9])([A-Z])/g, '$1-$2' )
+		.replace( /[^A-Za-z0-9]+/g, '-' )
+		.replace( /^-+|-+$/g, '' )
+		.replace( /-{2,}/g, '-' )
+		.toLowerCase();
+}
+
+function toPascalCase( input: string ): string {
+	return toKebabCase( input )
+		.split( '-' )
+		.filter( Boolean )
+		.map( ( segment ) => segment.charAt( 0 ).toUpperCase() + segment.slice( 1 ) )
+		.join( '' );
+}
+
+function toTitleCase( input: string ): string {
+	return toKebabCase( input )
+		.split( '-' )
+		.filter( Boolean )
+		.map( ( segment ) => segment.charAt( 0 ).toUpperCase() + segment.slice( 1 ) )
+		.join( ' ' );
+}
+
+function resolveValidatedNamespace( value: string ): string {
+	const normalizedNamespace = toKebabCase( value );
+
+	if ( ! BLOCK_SLUG_PATTERN.test( normalizedNamespace ) ) {
+		throw new Error( 'Use a block namespace with lowercase letters, numbers, and hyphens only.' );
+	}
+
+	return normalizedNamespace;
+}
+
+function resolveValidatedBlockSlug( value: string ): string {
+	const normalizedSlug = toKebabCase( value );
+
+	if ( ! BLOCK_SLUG_PATTERN.test( normalizedSlug ) ) {
+		throw new Error( 'Use a child slug with lowercase letters, numbers, and hyphens only.' );
+	}
+
+	return normalizedSlug;
+}
+
+function buildBlockCssClassName( namespace: string, slug: string ): string {
+	const normalizedSlug = resolveValidatedBlockSlug( slug );
+	const normalizedNamespace =
+		namespace.trim().length > 0
+			? resolveValidatedNamespace( namespace )
+			: '';
+
+	return normalizedNamespace.length > 0
+		? `wp-block-${ normalizedNamespace }-${ normalizedSlug }`
+		: `wp-block-${ normalizedSlug }`;
+}
+
+function escapeForRegExp( value: string ): string {
+	return value.replace( /[.*+?^${}()|[\]\\]/g, '\\$&' );
+}
+
+function createStringStarterAttribute(
+	defaultValue: string,
+	maxLength: number
+): Record< string, unknown > {
+	return {
+		ts: {
+			items: null,
+			kind: 'string',
+			properties: null,
+			required: true,
+			union: null,
+		},
+		typia: {
+			constraints: {
+				exclusiveMaximum: null,
+				exclusiveMinimum: null,
+				format: null,
+				maxItems: null,
+				maxLength,
+				maximum: null,
+				minItems: null,
+				minLength: 1,
+				minimum: null,
+				multipleOf: null,
+				pattern: null,
+				typeTag: null,
+			},
+			defaultValue,
+			hasDefault: true,
+		},
+		wp: {
+			defaultValue,
+			enum: null,
+			hasDefault: true,
+			type: 'string',
+		},
+	};
+}
+
+function createCompoundChildStarterManifest(
+	childTypeName: string,
+	childTitle: string,
+	bodyPlaceholder = CHILD_PLACEHOLDER
+): StarterManifestDocument {
+	return {
+		attributes: {
+			body: createStringStarterAttribute( bodyPlaceholder, 280 ),
+			title: createStringStarterAttribute( childTitle, 80 ),
+		},
+		manifestVersion: 2,
+		sourceType: childTypeName,
+	};
+}
+
+function stringifyStarterManifest( document: StarterManifestDocument ): string {
+	return `${ JSON.stringify( document, null, '\t' ) }\n`;
+}
+
+function insertBeforeMarker( filePath: string, marker: string, insertionLines: string[] ) {
+	const source = fs.readFileSync( filePath, 'utf8' );
+	const markerPattern = new RegExp(
+		`^(?<indent>\\s*)${ escapeForRegExp( marker ) }\\s*$`,
+		'm'
+	);
+	const markerMatch = source.match( markerPattern );
+
+	if ( ! markerMatch ) {
+		throw new Error( `Unable to update ${ filePath }: marker not found.` );
+	}
+
+	const indent = markerMatch.groups?.indent ?? '';
+	const markerLine = markerMatch[ 0 ];
+	const insertion = insertionLines
+		.map( ( line ) => ( line.length > 0 ? `${ indent }${ line }` : line ) )
+		.join( '\n' );
+
+	fs.writeFileSync(
+		filePath,
+		source.replace( markerPattern, `${ insertion }\n${ markerLine }` ),
+		'utf8'
+	);
+}
+
+function renderBlockJson(
+	childBlockName: string,
+	childFolderSlug: string,
+	childTitle: string
+): string {
+	const childCssClassName = buildBlockCssClassName( PARENT_BLOCK_NAMESPACE, childFolderSlug );
+
+	return `${ JSON.stringify(
+		{
+			$schema: 'https://schemas.wp.org/trunk/block.json',
+			apiVersion: 3,
+			name: childBlockName,
+			version: '{{blockMetadataVersion}}',
+			title: childTitle,
+			category: '{{compoundChildCategory}}',
+			icon: '{{compoundChildIcon}}',
+			description: `Internal item block used by ${ PARENT_BLOCK_TITLE }.`,
+			parent: [ PARENT_BLOCK_NAME ],
+			example: {},
+			supports: {
+				html: false,
+				inserter: false,
+				reusable: false,
+			},
+			attributes: {
+				title: {
+					type: 'string',
+					source: 'html',
+					selector: `.${ childCssClassName }__title`,
+					default: childTitle,
+				},
+				body: {
+					type: 'string',
+					source: 'html',
+					selector: `.${ childCssClassName }__body`,
+					default: CHILD_PLACEHOLDER,
+				},
+			},
+			textdomain: TEXT_DOMAIN,
+			editorScript: 'file:./index.js',
+		},
+		null,
+		'\t'
+	) }\n`;
+}
+
+function renderTypesFile( childTypeName: string, childTitle: string ): string {
+	return `import { tags } from 'typia';
+
+export interface ${ childTypeName } {
+\ttitle: string &
+\t\ttags.MinLength< 1 > &
+\t\ttags.MaxLength< 80 > &
+\t\ttags.Default< ${ JSON.stringify( childTitle ) } >;
+\tbody: string &
+\t\ttags.MinLength< 1 > &
+\t\ttags.MaxLength< 280 > &
+\t\ttags.Default< ${ JSON.stringify( CHILD_PLACEHOLDER ) } >;
+}
+`;
+}
+
+function renderStarterManifestFile(
+	childTypeName: string,
+	childTitle: string
+): string {
+	return stringifyStarterManifest(
+		createCompoundChildStarterManifest(
+			childTypeName,
+			childTitle,
+			CHILD_PLACEHOLDER
+		)
+	);
+}
+
+function renderHooksFile(): string {
+	return `import { useMemo } from '@wordpress/element';
+
+import {
+\tcreateUseTypiaValidationHook,
+\tformatValidationError,
+\tformatValidationErrors,
+\ttype TypiaValidationError,
+\ttype ValidationResult,
+\ttype ValidationState,
+} from '@wp-typia/block-runtime/validation';
+
+export {
+\tformatValidationError,
+\tformatValidationErrors,
+\ttype TypiaValidationError,
+\ttype ValidationResult,
+\ttype ValidationState,
+} from '@wp-typia/block-runtime/validation';
+
+export const useTypiaValidation = createUseTypiaValidationHook( {
+\tuseMemo,
+} );
+`;
+}
+
+function renderValidatorsFile(
+	childTypeName: string,
+	childInterfaceName: string
+): string {
+	return `import typia from 'typia';
+import currentManifest from './typia.manifest.json';
+import {
+\ttype ManifestDefaultsDocument,
+} from '@wp-typia/block-runtime/defaults';
+import {
+\tcreateScaffoldValidatorToolkit,
+} from '@wp-typia/block-runtime/validation';
+
+import type { ${ childTypeName } } from './types';
+
+const validate = typia.createValidate< ${ childTypeName } >();
+const assert = typia.createAssert< ${ childTypeName } >();
+const is = typia.createIs< ${ childTypeName } >();
+const random = typia.createRandom< ${ childTypeName } >();
+const clone = typia.misc.createClone< ${ childTypeName } >();
+const prune = typia.misc.createPrune< ${ childTypeName } >();
+const scaffoldValidators = createScaffoldValidatorToolkit< ${ childTypeName } >( {
+\tmanifest: currentManifest as ManifestDefaultsDocument,
+\tvalidate,
+\tassert,
+\tis,
+\trandom,
+\tclone,
+\tprune,
+} );
+
+export const validate${ childInterfaceName } = scaffoldValidators.validateAttributes;
+
+export const validators = scaffoldValidators.validators;
+
+export const sanitize${ childInterfaceName } = scaffoldValidators.sanitizeAttributes;
+
+export const createAttributeUpdater = scaffoldValidators.createAttributeUpdater;
+`;
+}
+
+function renderEditFile(
+	childFolderSlug: string,
+	childTypeName: string,
+	childInterfaceName: string,
+	childTitle: string
+): string {
+	const childCssClassName = buildBlockCssClassName( PARENT_BLOCK_NAMESPACE, childFolderSlug );
+
+	return `import { RichText, useBlockProps } from '@wordpress/block-editor';
+import { Notice } from '@wordpress/components';
+import { __ } from '@wordpress/i18n';
+
+import { useTypiaValidation } from './hooks';
+import type { ${ childTypeName } } from './types';
+import {
+\tcreateAttributeUpdater,
+\tvalidate${ childInterfaceName },
+} from './validators';
+
+export default function Edit( {
+\tattributes,
+\tsetAttributes,
+}: {
+\tattributes: ${ childTypeName };
+\tsetAttributes: ( attrs: Partial< ${ childTypeName } > ) => void;
+} ) {
+\tconst updateAttribute = createAttributeUpdater( attributes, setAttributes );
+\tconst { errorMessages, isValid } = useTypiaValidation(
+\t\tattributes,
+\t\tvalidate${ childInterfaceName }
+\t);
+
+\treturn (
+\t\t<div { ...useBlockProps( { className: '${ childCssClassName }' } ) }>
+\t\t\t<RichText
+\t\t\t\ttagName="h4"
+\t\t\t\tclassName="${ childCssClassName }__title"
+\t\t\t\tvalue={ attributes.title ?? '' }
+\t\t\t\tonChange={ ( title ) => updateAttribute( 'title', title ) }
+\t\t\t\tplaceholder={ __( ${ JSON.stringify( childTitle ) }, '${ TEXT_DOMAIN }' ) }
+\t\t\t/>
+\t\t\t<RichText
+\t\t\t\ttagName="p"
+\t\t\t\tclassName="${ childCssClassName }__body"
+\t\t\t\tvalue={ attributes.body ?? '' }
+\t\t\t\tonChange={ ( body ) => updateAttribute( 'body', body ) }
+\t\t\t\tplaceholder={ __( ${ JSON.stringify( CHILD_PLACEHOLDER ) }, '${ TEXT_DOMAIN }' ) }
+\t\t\t/>
+\t\t\t{ ! isValid && (
+\t\t\t\t<Notice status="error" isDismissible={ false }>
+\t\t\t\t\t<ul>
+\t\t\t\t\t\t{ errorMessages.map( ( error, index ) => (
+\t\t\t\t\t\t\t<li key={ index }>{ error }</li>
+\t\t\t\t\t\t) ) }
+\t\t\t\t\t</ul>
+\t\t\t\t</Notice>
+\t\t\t) }
+\t\t</div>
+\t);
+}
+`;
+}
+
+function renderSaveFile( childFolderSlug: string, childTypeName: string ): string {
+	const childCssClassName = buildBlockCssClassName( PARENT_BLOCK_NAMESPACE, childFolderSlug );
+
+	return `import { RichText, useBlockProps } from '@wordpress/block-editor';
+
+import type { ${ childTypeName } } from './types';
+
+export default function Save( {
+\tattributes,
+}: {
+\tattributes: ${ childTypeName };
+} ) {
+\treturn (
+\t\t<div { ...useBlockProps.save( { className: '${ childCssClassName }' } ) }>
+\t\t\t<RichText.Content
+\t\t\t\ttagName="h4"
+\t\t\t\tclassName="${ childCssClassName }__title"
+\t\t\t\tvalue={ attributes.title }
+\t\t\t/>
+\t\t\t<RichText.Content
+\t\t\t\ttagName="p"
+\t\t\t\tclassName="${ childCssClassName }__body"
+\t\t\t\tvalue={ attributes.body }
+\t\t\t/>
+\t\t</div>
+\t);
+}
+`;
+}
+
+function renderIndexFile( childTypeName: string, childFolderSlug: string ): string {
+	return `import { registerBlockType } from '@wordpress/blocks';
+import type { BlockConfiguration } from '@wordpress/blocks';
+import {
+\tbuildScaffoldBlockRegistration,
+\ttype ScaffoldBlockMetadata,
+} from '@wp-typia/block-runtime/blocks';
+
+import Edit from './edit';
+import Save from './save';
+import metadata from './block.json';
+import '${ PARENT_STYLE_IMPORT }';
+
+import type { ${ childTypeName } } from './types';
+
+const registration = buildScaffoldBlockRegistration<
+\tBlockConfiguration< ${ childTypeName } >
+>( metadata as ScaffoldBlockMetadata, {
+\tedit: Edit,
+\tsave: Save,
+} );
+
+registerBlockType< ${ childTypeName } >(
+\tregistration.name,
+\tregistration.settings
+);
+`;
+}
+
+function main() {
+	const { slug, title } = parseArgs();
+	const normalizedSlug = slug ? resolveValidatedBlockSlug( slug ) : '';
+
+	if ( normalizedSlug.length === 0 ) {
+		throw new Error( 'Use a child slug with lowercase letters, numbers, and hyphens only.' );
+	}
+
+	const childTitle = title?.trim().length ? title.trim() : toTitleCase( normalizedSlug );
+	const childFolderSlug = `${ PARENT_BLOCK_SLUG }-${ normalizedSlug }`;
+	const childBlockName = `${ PARENT_BLOCK_NAME }-${ normalizedSlug }`;
+	const childTypeSuffix = toPascalCase( normalizedSlug );
+	const childTypeName = `${ PARENT_TYPE_NAME }${ childTypeSuffix }Attributes`;
+	const childInterfaceName = `${ PARENT_TYPE_NAME }${ childTypeSuffix }`;
+	const childDir = path.join( PROJECT_ROOT, 'src', 'blocks', childFolderSlug );
+	const childrenFile = path.join(
+		PROJECT_ROOT,
+		'src',
+		'blocks',
+		PARENT_BLOCK_SLUG,
+		'children.ts'
+	);
+	const blockConfigFile = path.join( PROJECT_ROOT, 'scripts', 'block-config.ts' );
+
+	if ( fs.existsSync( childDir ) ) {
+		throw new Error( `Child block already exists: ${ childFolderSlug }` );
+	}
+
+	if ( ! fs.existsSync( childrenFile ) || ! fs.existsSync( blockConfigFile ) ) {
+		throw new Error(
+			'This command expects a compound scaffold with src/blocks/<parent>/children.ts and scripts/block-config.ts.'
+		);
+	}
+
+	fs.mkdirSync( childDir, { recursive: true } );
+
+	fs.writeFileSync(
+		path.join( childDir, 'block.json' ),
+		renderBlockJson( childBlockName, childFolderSlug, childTitle ),
+		'utf8'
+	);
+	fs.writeFileSync( path.join( childDir, 'types.ts' ), renderTypesFile( childTypeName, childTitle ), 'utf8' );
+	fs.writeFileSync(
+		path.join( childDir, 'typia.manifest.json' ),
+		renderStarterManifestFile( childTypeName, childTitle ),
+		'utf8'
+	);
+	fs.writeFileSync( path.join( childDir, 'hooks.ts' ), renderHooksFile(), 'utf8' );
+	fs.writeFileSync(
+		path.join( childDir, 'validators.ts' ),
+		renderValidatorsFile( childTypeName, childInterfaceName ),
+		'utf8'
+	);
+	fs.writeFileSync(
+		path.join( childDir, 'edit.tsx' ),
+		renderEditFile( childFolderSlug, childTypeName, childInterfaceName, childTitle ),
+		'utf8'
+	);
+	fs.writeFileSync(
+		path.join( childDir, 'save.tsx' ),
+		renderSaveFile( childFolderSlug, childTypeName ),
+		'utf8'
+	);
+	fs.writeFileSync(
+		path.join( childDir, 'index.tsx' ),
+		renderIndexFile( childTypeName, childFolderSlug ),
+		'utf8'
+	);
+
+	insertBeforeMarker(
+		childrenFile,
+		ALLOWED_CHILD_MARKER,
+		[ `'${ childBlockName }',` ]
+	);
+	insertBeforeMarker(
+		blockConfigFile,
+		BLOCK_CONFIG_MARKER,
+		[
+			'{',
+			`\tslug: '${ childFolderSlug }',`,
+			`\tattributeTypeName: '${ childTypeName }',`,
+			`\ttypesFile: 'src/blocks/${ childFolderSlug }/types.ts',`,
+			'},',
+		]
+	);
+
+	console.log( `✅ Added compound child block ${ childBlockName }` );
+	console.log(
+		'Run `sync-types` next to generate block.json metadata, manifests, schemas, and PHP validators for the new child block.'
+	);
+}
+
+main();

package/templates/_shared/compound/core/scripts/block-config.ts.mustache

@@ -0,0 +1,13 @@
+export const BLOCKS = [
+	{
+		attributeTypeName: '{{pascalCase}}Attributes',
+		slug: '{{slugKebabCase}}',
+		typesFile: 'src/blocks/{{slugKebabCase}}/types.ts',
+	},
+	{
+		slug: '{{slugKebabCase}}-item',
+		attributeTypeName: '{{pascalCase}}ItemAttributes',
+		typesFile: 'src/blocks/{{slugKebabCase}}-item/types.ts',
+	},
+	// add-child: insert new block config entries here
+] as const;

package/templates/_shared/compound/core/scripts/sync-types-to-block-json.ts.mustache

@@ -0,0 +1,53 @@
+/* eslint-disable no-console */
+import path from 'node:path';
+
+import { syncBlockMetadata } from '@wp-typia/block-runtime/metadata-core';
+
+import { BLOCKS } from './block-config';
+
+function parseCliOptions( argv: string[] ) {
+	const options = {
+		check: false,
+	};
+
+	for ( const argument of argv ) {
+		if ( argument === '--check' ) {
+			options.check = true;
+			continue;
+		}
+
+		throw new Error( `Unknown sync-types flag: ${ argument }` );
+	}
+
+	return options;
+}
+
+async function main() {
+	const options = parseCliOptions( process.argv.slice( 2 ) );
+
+	for ( const block of BLOCKS ) {
+		const baseDir = path.join( 'src', 'blocks', block.slug );
+		const result = await syncBlockMetadata( {
+			blockJsonFile: path.join( baseDir, 'block.json' ),
+			jsonSchemaFile: path.join( baseDir, 'typia.schema.json' ),
+			manifestFile: path.join( baseDir, 'typia.manifest.json' ),
+			openApiFile: path.join( baseDir, 'typia.openapi.json' ),
+			sourceTypeName: block.attributeTypeName,
+			typesFile: block.typesFile,
+		}, {
+			check: options.check,
+		} );
+
+		console.log(
+			options.check
+				? `✅ ${ block.slug }: block.json, typia.manifest.json, typia-validator.php, typia.schema.json, and typia.openapi.json are already up to date with the TypeScript types!`
+				: `✅ ${ block.slug }: block.json, typia.manifest.json, typia-validator.php, typia.schema.json, and typia.openapi.json were generated from TypeScript types!`
+		);
+		console.log( '📝 Generated attributes:', result.attributeNames );
+	}
+}
+
+main().catch( ( error ) => {
+	console.error( '❌ Type sync failed:', error );
+	process.exit( 1 );
+} );