@wp-typia/project-tools 0.11.1

package/templates/_shared/workspace/persistence-public/server.php.mustache

@@ -0,0 +1,252 @@
+<?php
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+require_once __DIR__ . '/inc/rest-shared.php';
+require_once __DIR__ . '/inc/rest-public.php';
+
+function {{phpPrefix}}_get_rest_build_dir() {
+	return dirname( __DIR__, 3 ) . '/build/blocks/{{slugKebabCase}}';
+}
+
+function {{phpPrefix}}_get_counter_table_name() {
+	global $wpdb;
+	return $wpdb->prefix . '{{phpPrefix}}_counters';
+}
+
+function {{phpPrefix}}_get_counter_lock_name( $post_id, $resource_key ) {
+	return 'wpt_pcl_' . md5(
+		'{{phpPrefix}}|' . (int) $post_id . '|' . (string) $resource_key
+	);
+}
+
+function {{phpPrefix}}_with_counter_lock( $post_id, $resource_key, $callback ) {
+	global $wpdb;
+
+	$lock_name = {{phpPrefix}}_get_counter_lock_name( $post_id, $resource_key );
+	$acquired  = (int) $wpdb->get_var(
+		$wpdb->prepare(
+			'SELECT GET_LOCK(%s, 5)',
+			$lock_name
+		)
+	);
+
+	if ( 1 !== $acquired ) {
+		return new WP_Error( 'counter_lock_timeout', 'Could not acquire the counter lock.', array( 'status' => 503 ) );
+	}
+
+	try {
+		return $callback();
+	} finally {
+		$wpdb->get_var(
+			$wpdb->prepare(
+				'SELECT RELEASE_LOCK(%s)',
+				$lock_name
+			)
+		);
+	}
+}
+
+function {{phpPrefix}}_maybe_install_storage() {
+	if ( 'custom-table' !== '{{dataStorageMode}}' ) {
+		return;
+	}
+
+	global $wpdb;
+	require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+	$table_name      = {{phpPrefix}}_get_counter_table_name();
+	$charset_collate = $wpdb->get_charset_collate();
+	$sql             = "CREATE TABLE {$table_name} (
+		post_id bigint(20) unsigned NOT NULL,
+		resource_key varchar(100) NOT NULL,
+		count bigint(20) unsigned NOT NULL DEFAULT 0,
+		updated_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
+		PRIMARY KEY  (post_id, resource_key)
+	) {$charset_collate};";
+
+	dbDelta( $sql );
+	$table_exists = $wpdb->get_var(
+		$wpdb->prepare(
+			'SHOW TABLES LIKE %s',
+			$table_name
+		)
+	);
+
+	if ( $table_name === $table_exists ) {
+		update_option( '{{phpPrefix}}_storage_version', '1.0.0' );
+	}
+}
+
+function {{phpPrefix}}_ensure_storage_installed() {
+	if ( 'custom-table' === '{{dataStorageMode}}' && '1.0.0' !== get_option( '{{phpPrefix}}_storage_version', '' ) ) {
+		{{phpPrefix}}_maybe_install_storage();
+	}
+}
+
+function {{phpPrefix}}_get_counter( $post_id, $resource_key ) {
+	global $wpdb;
+
+	if ( 'custom-table' === '{{dataStorageMode}}' ) {
+		$table_name = {{phpPrefix}}_get_counter_table_name();
+		$count      = $wpdb->get_var(
+			$wpdb->prepare(
+				// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- Table name comes from an internal helper.
+				"SELECT count FROM {$table_name} WHERE post_id = %d AND resource_key = %s",
+				$post_id,
+				$resource_key
+			)
+		);
+
+		return null === $count ? 0 : (int) $count;
+	}
+
+	$meta_key = '_' . '{{phpPrefix}}' . '_counter_' . sanitize_key( $resource_key );
+	return (int) get_post_meta( $post_id, $meta_key, true );
+}
+
+function {{phpPrefix}}_increment_counter( $post_id, $resource_key, $delta ) {
+	global $wpdb;
+
+	if ( 'custom-table' === '{{dataStorageMode}}' ) {
+		$table_name    = {{phpPrefix}}_get_counter_table_name();
+		$delta_value   = (int) $delta;
+		$initial_count = max( 0, $delta_value );
+		$result        = $wpdb->query(
+			$wpdb->prepare(
+				// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- Table name comes from an internal helper.
+				"INSERT INTO {$table_name} (post_id, resource_key, count, updated_at)
+				VALUES (%d, %s, %d, %s)
+				ON DUPLICATE KEY UPDATE
+					count = GREATEST(0, count + %d),
+					updated_at = VALUES(updated_at)",
+				$post_id,
+				$resource_key,
+				$initial_count,
+				current_time( 'mysql', true ),
+				$delta_value
+			)
+		);
+
+		if ( false === $result ) {
+			return new WP_Error( 'counter_update_failed', 'Failed to update the counter.', array( 'status' => 500 ) );
+		}
+
+		return {{phpPrefix}}_get_counter( $post_id, $resource_key );
+	}
+
+	return {{phpPrefix}}_with_counter_lock(
+		$post_id,
+		$resource_key,
+		function () use ( $delta, $post_id, $resource_key ) {
+			$meta_key   = '_' . '{{phpPrefix}}' . '_counter_' . sanitize_key( $resource_key );
+			$next_count = max( 0, {{phpPrefix}}_get_counter( $post_id, $resource_key ) + (int) $delta );
+			update_post_meta( $post_id, $meta_key, $next_count );
+			return $next_count;
+		}
+	);
+}
+
+function {{phpPrefix}}_build_state_response( $post_id, $resource_key, $count ) {
+	return array(
+		'postId'      => (int) $post_id,
+		'resourceKey' => (string) $resource_key,
+		'count'       => (int) $count,
+		'storage'     => '{{dataStorageMode}}',
+	);
+}
+
+function {{phpPrefix}}_handle_get_state( WP_REST_Request $request ) {
+	$payload = {{phpPrefix}}_validate_and_sanitize_request(
+		array(
+			'postId'      => $request->get_param( 'postId' ),
+			'resourceKey' => $request->get_param( 'resourceKey' ),
+		),
+		{{phpPrefix}}_get_rest_build_dir(),
+		'state-query',
+		'query'
+	);
+
+	if ( is_wp_error( $payload ) ) {
+		return $payload;
+	}
+
+	$count = {{phpPrefix}}_get_counter( (int) $payload['postId'], (string) $payload['resourceKey'] );
+	return rest_ensure_response(
+		{{phpPrefix}}_build_state_response(
+			(int) $payload['postId'],
+			(string) $payload['resourceKey'],
+			$count
+		)
+	);
+}
+
+function {{phpPrefix}}_handle_write_state( WP_REST_Request $request ) {
+	$payload = {{phpPrefix}}_validate_and_sanitize_request(
+		$request->get_json_params(),
+		{{phpPrefix}}_get_rest_build_dir(),
+		'write-state-request',
+		'body'
+	);
+
+	if ( is_wp_error( $payload ) ) {
+		return $payload;
+	}
+
+	$request_consumed = {{phpPrefix}}_consume_public_write_request_id(
+		(int) $payload['postId'],
+		(string) $payload['resourceKey'],
+		isset( $payload['publicWriteRequestId'] ) ? (string) $payload['publicWriteRequestId'] : ''
+	);
+
+	if ( is_wp_error( $request_consumed ) ) {
+		return $request_consumed;
+	}
+
+	$count = {{phpPrefix}}_increment_counter(
+		(int) $payload['postId'],
+		(string) $payload['resourceKey'],
+		isset( $payload['delta'] ) ? (int) $payload['delta'] : 1
+	);
+
+	if ( is_wp_error( $count ) ) {
+		{{phpPrefix}}_release_public_write_request_id(
+			(int) $payload['postId'],
+			(string) $payload['resourceKey'],
+			isset( $payload['publicWriteRequestId'] ) ? (string) $payload['publicWriteRequestId'] : ''
+		);
+		return $count;
+	}
+
+	return rest_ensure_response(
+		{{phpPrefix}}_build_state_response(
+			(int) $payload['postId'],
+			(string) $payload['resourceKey'],
+			$count
+		)
+	);
+}
+
+function {{phpPrefix}}_register_routes() {
+	register_rest_route(
+		'{{namespace}}/v1',
+		'/{{slugKebabCase}}/state',
+		array(
+			array(
+				'methods'             => WP_REST_Server::READABLE,
+				'callback'            => '{{phpPrefix}}_handle_get_state',
+				'permission_callback' => '__return_true',
+			),
+			array(
+				'methods'             => WP_REST_Server::CREATABLE,
+				'callback'            => '{{phpPrefix}}_handle_write_state',
+				'permission_callback' => '{{phpPrefix}}_can_write_publicly',
+			),
+		)
+	);
+}
+
+add_action( 'init', '{{phpPrefix}}_ensure_storage_installed' );
+add_action( 'rest_api_init', '{{phpPrefix}}_register_routes' );

package/templates/basic/src/block.json.mustache

@@ -0,0 +1,51 @@
+{
+	"$schema": "https://schemas.wp.org/trunk/block.json",
+	"apiVersion": 3,
+	"name": "{{namespace}}/{{slug}}",
+	"version": "{{blockMetadataVersion}}",
+	"title": "{{title}}",
+	"category": "{{category}}",
+	"icon": "{{icon}}",
+	"description": "{{description}}",
+	"keywords": ["{{keyword}}", "typia", "block"],
+	"example": {
+		"attributes": {
+			"content": "Example content",
+			"alignment": "center",
+			"isVisible": true
+		}
+	},
+	"supports": {
+		"html": false
+	},
+	"textdomain": "{{textDomain}}",
+	"editorScript": "file:./index.js",
+	"editorStyle": "file:./index.css",
+	"style": "file:./style-index.css",
+	"attributes": {
+		"content": {
+			"type": "string",
+			"default": ""
+		},
+		"alignment": {
+			"type": "string",
+			"enum": ["left", "center", "right", "justify"],
+			"default": "left"
+		},
+		"className": {
+			"type": "string",
+			"default": ""
+		},
+		"isVisible": {
+			"type": "boolean",
+			"default": true
+		},
+		"id": {
+			"type": "string"
+		},
+		"schemaVersion": {
+			"type": "number",
+			"default": 1
+		}
+	}
+}

package/templates/basic/src/edit.tsx.mustache

@@ -0,0 +1,128 @@
+/**
+ * Editor component for {{title}} Block
+ */
+
+import { BlockEditProps } from '@wordpress/blocks';
+import {
+  InspectorControls,
+  RichText,
+  useBlockProps,
+} from '@wordpress/block-editor';
+import { Notice, PanelBody, TextControl } from '@wordpress/components';
+import { __ } from '@wordpress/i18n';
+import currentManifest from './typia.manifest.json';
+import {
+  InspectorFromManifest,
+  type ManifestDocument,
+  useEditorFields,
+  useTypedAttributeUpdater,
+} from '@wp-typia/block-runtime/inspector';
+import { {{pascalCase}}Attributes } from './types';
+import {
+  sanitize{{pascalCase}}Attributes,
+  validate{{pascalCase}}Attributes,
+} from './validators';
+import { useTypiaValidation } from './hooks';
+
+type EditProps = BlockEditProps<{{pascalCase}}Attributes>;
+
+function Edit({ attributes, setAttributes }: EditProps) {
+  const isVisible = attributes.isVisible !== false;
+  const blockProps = useBlockProps({
+    className: isVisible ? undefined : 'is-hidden',
+  });
+  const editorFields = useEditorFields(currentManifest as ManifestDocument, {
+    hidden: ['id', 'schemaVersion'],
+    manual: ['content'],
+    labels: {
+      alignment: __('Alignment', '{{textDomain}}'),
+      className: __('CSS Class', '{{textDomain}}'),
+      content: __('Content', '{{textDomain}}'),
+      isVisible: __('Visible', '{{textDomain}}'),
+    },
+  });
+  const classNameField = editorFields.getField('className');
+  const { errorMessages, isValid } = useTypiaValidation(
+    attributes,
+    validate{{pascalCase}}Attributes
+  );
+  const validateEditorUpdate = (nextAttributes: {{pascalCase}}Attributes) => {
+    try {
+      return {
+        data: sanitize{{pascalCase}}Attributes(nextAttributes),
+        errors: [],
+        isValid: true as const,
+      };
+    } catch {
+      return validate{{pascalCase}}Attributes(nextAttributes);
+    }
+  };
+  const { updateField } = useTypedAttributeUpdater(
+    attributes,
+    setAttributes,
+    validateEditorUpdate
+  );
+
+  return (
+    <>
+      <InspectorControls>
+        <InspectorFromManifest
+          attributes={attributes}
+          fieldLookup={editorFields}
+          onChange={updateField}
+          paths={['alignment', 'isVisible']}
+          title={__('Settings', '{{textDomain}}')}
+        >
+          <TextControl
+            label={__('Content', '{{textDomain}}')}
+            value={attributes.content || ''}
+            onChange={(value) => updateField('content', value)}
+            help={__('Mirrors the main block content.', '{{textDomain}}')}
+          />
+
+          <TextControl
+            label={classNameField?.label || __('CSS Class', '{{textDomain}}')}
+            value={attributes.className || ''}
+            onChange={(value) => updateField('className', value)}
+            help={__('Add an optional CSS class name.', '{{textDomain}}')}
+          />
+        </InspectorFromManifest>
+
+        {!isValid && (
+          <PanelBody title={__('Validation Errors', '{{textDomain}}')} initialOpen>
+            {errorMessages.map((error, index) => (
+              <div key={index} style={{ color: '#cc1818', fontSize: '12px' }}>
+                • {error}
+              </div>
+            ))}
+          </PanelBody>
+        )}
+      </InspectorControls>
+
+      <div {...blockProps}>
+        <div className="{{cssClassName}}__content">
+          <RichText
+            tagName="p"
+            value={attributes.content || ''}
+            onChange={(value) => updateField('content', value)}
+            placeholder={__('Add your content...', '{{textDomain}}')}
+          />
+        </div>
+        {!isValid && (
+          <Notice status="error" isDismissible={false}>
+            <p>
+              <strong>{__('Validation Errors', '{{textDomain}}')}</strong>
+            </p>
+            <ul style={{ margin: 0, paddingLeft: '1em' }}>
+              {errorMessages.map((error, index) => (
+                <li key={index}>{error}</li>
+              ))}
+            </ul>
+          </Notice>
+        )}
+      </div>
+    </>
+  );
+}
+
+export default Edit;

package/templates/basic/src/editor.scss.mustache

@@ -0,0 +1,8 @@
+/**
+ * {{title}} Block Editor Styles
+ */
+
+.{{cssClassName}} {
+	outline: 1px dashed #ddd;
+	outline-offset: -1px;
+}

package/templates/basic/src/hooks.ts.mustache

@@ -0,0 +1,18 @@
+import { useMemo } from '@wordpress/element';
+import {
+	createUseTypiaValidationHook,
+	formatValidationError,
+	formatValidationErrors,
+} from '@wp-typia/block-runtime/validation';
+
+export {
+	formatValidationError,
+	formatValidationErrors,
+	type TypiaValidationError,
+	type ValidationResult,
+	type ValidationState,
+} from '@wp-typia/block-runtime/validation';
+
+export const useTypiaValidation = createUseTypiaValidationHook( {
+	useMemo,
+} );

package/templates/basic/src/index.tsx.mustache

@@ -0,0 +1,45 @@
+/**
+ * WordPress {{title}} Block
+ *
+ * Typia-powered type-safe block
+ */
+
+import { registerBlockType } from '@wordpress/blocks';
+import type { BlockConfiguration } from '@wordpress/blocks';
+import type { BlockSupports } from '@wp-typia/block-types/blocks/supports';
+import { __ } from '@wordpress/i18n';
+import {
+  buildScaffoldBlockRegistration,
+  type ScaffoldBlockMetadata,
+} from '@wp-typia/block-runtime/blocks';
+
+// Import components
+import Edit from './edit';
+import Save from './save';
+import metadata from './block.json';
+import './editor.scss';
+import './style.scss';
+
+// Import types
+import { {{pascalCase}}Attributes } from './types';
+import { validators } from './validators';
+
+const scaffoldSupports = {
+  html: false,
+  multiple: true,
+  align: ['wide', 'full'],
+} satisfies BlockSupports;
+
+// Register the block
+const registration = buildScaffoldBlockRegistration<
+  BlockConfiguration<{{pascalCase}}Attributes>
+>(metadata as ScaffoldBlockMetadata, {
+  supports: scaffoldSupports,
+  example: {
+    attributes: validators.random(),
+  },
+  edit: Edit,
+  save: Save,
+});
+
+registerBlockType<{{pascalCase}}Attributes>(registration.name, registration.settings);

package/templates/basic/src/save.tsx.mustache

@@ -0,0 +1,30 @@
+/**
+ * Save/Frontend component for {{title}} Block
+ */
+
+import { RichText, useBlockProps } from '@wordpress/block-editor';
+import { {{pascalCase}}Attributes } from './types';
+
+interface SaveProps {
+  attributes: {{pascalCase}}Attributes;
+}
+
+export default function Save({ attributes }: SaveProps) {
+  const isVisible = attributes.isVisible !== false;
+  const blockProps = useBlockProps.save({
+    className: isVisible ? undefined : 'is-hidden',
+    hidden: isVisible ? undefined : true,
+    'aria-hidden': isVisible ? undefined : 'true',
+  });
+
+  return (
+    <div {...blockProps}>
+      <div
+        className="{{cssClassName}}__content"
+        data-align={attributes.alignment || 'left'}
+      >
+        <RichText.Content tagName="p" value={attributes.content} />
+      </div>
+    </div>
+  );
+}

package/templates/basic/src/style.scss.mustache

@@ -0,0 +1,40 @@
+/**
+ * {{title}} Block Styles
+ */
+
+.{{cssClassName}} {
+	padding: 20px;
+	border: 1px solid #ddd;
+	border-radius: 4px;
+	background-color: #fff;
+	box-shadow: 0 1px 3px rgba(0, 0, 0, 0.05);
+
+	&.is-hidden {
+		display: none;
+	}
+
+	&__content {
+		font-size: 16px;
+		line-height: 1.6;
+		color: #333;
+
+		// Alignment styles
+		&[data-align="center"] {
+			text-align: center;
+		}
+
+		&[data-align="right"] {
+			text-align: right;
+		}
+
+		&[data-align="justify"] {
+			text-align: justify;
+		}
+	}
+
+	// Hover state
+	&:hover {
+		box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);
+		transition: box-shadow 0.2s ease;
+	}
+}

package/templates/basic/src/types.ts.mustache

@@ -0,0 +1,56 @@
+import type { TextAlignment } from "@wp-typia/block-types/block-editor/alignment";
+import type {
+  TypiaValidationError,
+  ValidationResult,
+} from "@wp-typia/block-runtime/validation";
+import { tags } from "typia";
+
+export type { TypiaValidationError, ValidationResult } from "@wp-typia/block-runtime/validation";
+
+/**
+ * Block attributes interface
+ * Typia tags define runtime validation rules
+ */
+export interface {{pascalCase}}Attributes {
+  /**
+   * Main block content
+   */
+  content: string & 
+    tags.MinLength<1> & 
+    tags.MaxLength<1000> & 
+    tags.Default<"">;
+
+  /**
+   * Alignment
+   */
+  alignment?: TextAlignment & 
+    tags.Default<"left">;
+
+  /**
+   * Visibility toggle
+   */
+  isVisible?: boolean & 
+    tags.Default<true>;
+
+  /**
+   * Custom CSS class
+   */
+  className?: string & 
+    tags.MaxLength<100> & 
+    tags.Default<"">;
+
+  /**
+   * Generated runtime ID
+   */
+  id?: string & 
+    tags.Format<"uuid">;
+
+  /**
+   * Block version for migrations
+   */
+  schemaVersion?: number & 
+    tags.Type<"uint32"> & 
+    tags.Default<1>;
+}
+
+export type {{pascalCase}}ValidationResult = ValidationResult<{{pascalCase}}Attributes>;

package/templates/basic/src/validators.ts.mustache

@@ -0,0 +1,26 @@
+import currentManifest from "./typia.manifest.json";
+import { {{pascalCase}}Attributes, {{pascalCase}}ValidationResult } from "./types";
+import { generateBlockId } from "@wp-typia/block-runtime/identifiers";
+import { createTemplateValidatorToolkit } from "./validator-toolkit";
+
+const scaffoldValidators = createTemplateValidatorToolkit<{{pascalCase}}Attributes>({
+  manifest: currentManifest,
+  finalize: (normalized) => ({
+    ...normalized,
+    id: normalized.id && normalized.id.length > 0 ? normalized.id : generateBlockId(),
+  }),
+});
+
+export const validate{{pascalCase}}Attributes =
+  scaffoldValidators.validateAttributes as (
+    attributes: unknown,
+  ) => {{pascalCase}}ValidationResult;
+
+export const validators = scaffoldValidators.validators;
+
+export const sanitize{{pascalCase}}Attributes =
+  scaffoldValidators.sanitizeAttributes as (
+    attributes: Partial<{{pascalCase}}Attributes>,
+  ) => {{pascalCase}}Attributes;
+
+export const createAttributeUpdater = scaffoldValidators.createAttributeUpdater;

package/templates/compound/src/blocks/{{slugKebabCase}}/block.json.mustache

@@ -0,0 +1,37 @@
+{
+	"$schema": "https://schemas.wp.org/trunk/block.json",
+	"apiVersion": 3,
+	"name": "{{namespace}}/{{slugKebabCase}}",
+	"version": "{{blockMetadataVersion}}",
+	"title": {{titleJson}},
+	"category": "{{category}}",
+	"icon": "{{icon}}",
+	"description": "{{description}}",
+	"example": {},
+	"supports": {
+		"html": false,
+		"anchor": true,
+		"className": true
+	},
+	"attributes": {
+		"heading": {
+			"type": "string",
+			"source": "html",
+			"selector": ".{{cssClassName}}__heading",
+			"default": {{titleJson}}
+		},
+		"intro": {
+			"type": "string",
+			"source": "html",
+			"selector": ".{{cssClassName}}__intro",
+			"default": "Add and reorder internal items inside this compound block."
+		},
+		"showDividers": {
+			"type": "boolean",
+			"default": true
+		}
+	},
+	"textdomain": "{{textDomain}}",
+	"editorScript": "file:./index.js",
+	"style": "file:./style-index.css"
+}