@wp-typia/project-tools 0.20.2 → 0.21.0

package/dist/runtime/cli-add-workspace-assets.js

@@ -1,10 +1,13 @@
 import fs from "node:fs";
 import { promises as fsp } from "node:fs";
 import path from "node:path";
+import { syncBlockMetadata, } from "@wp-typia/block-runtime/metadata-core";
+import ts from "typescript";
 import { resolveWorkspaceProject, } from "./workspace-project.js";
-import { readWorkspaceInventory, appendWorkspaceInventoryEntries } from "./workspace-inventory.js";
-import { toTitleCase } from "./string-case.js";
-import { assertBindingSourceDoesNotExist, assertEditorPluginDoesNotExist, assertPatternDoesNotExist, assertValidEditorPluginSlot, assertValidGeneratedSlug, getWorkspaceBootstrapPath, normalizeBlockSlug, patchFile, quoteTsString, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { readWorkspaceInventory, appendWorkspaceInventoryEntries, } from "./workspace-inventory.js";
+import { toPascalCase, toTitleCase } from "./string-case.js";
+import { findPhpFunctionRange, hasPhpFunctionDefinition, quotePhpString, replacePhpFunctionDefinition, } from "./php-utils.js";
+import { assertBindingSourceDoesNotExist, assertEditorPluginDoesNotExist, assertPatternDoesNotExist, assertValidEditorPluginSlot, assertValidGeneratedSlug, getWorkspaceBootstrapPath, normalizeBlockSlug, patchFile, quoteTsString, resolveWorkspaceBlock, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
 const PATTERN_BOOTSTRAP_CATEGORY = "register_block_pattern_category";
 const BINDING_SOURCE_SERVER_GLOB = "/src/bindings/*/server.php";
 const BINDING_SOURCE_EDITOR_SCRIPT = "build/bindings/index.js";
@@ -13,58 +16,7 @@ const EDITOR_PLUGIN_EDITOR_SCRIPT = "build/editor-plugins/index.js";
 const EDITOR_PLUGIN_EDITOR_ASSET = "build/editor-plugins/index.asset.php";
 const EDITOR_PLUGIN_EDITOR_STYLE = "build/editor-plugins/style-index.css";
 const EDITOR_PLUGIN_EDITOR_STYLE_RTL = "build/editor-plugins/style-index-rtl.css";
-function escapeRegex(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-}
-function quotePhpString(value) {
-    return `'${value.replace(/\\/gu, "\\\\").replace(/'/gu, "\\'")}'`;
-}
-function findPhpFunctionRange(source, functionName) {
-    const signaturePattern = new RegExp(`function\\s+${escapeRegex(functionName)}\\s*\\(`, "u");
-    const signatureMatch = signaturePattern.exec(source);
-    if (!signatureMatch || signatureMatch.index === undefined) {
-        return null;
-    }
-    const functionStart = signatureMatch.index;
-    const openBraceIndex = source.indexOf("{", functionStart);
-    if (openBraceIndex === -1) {
-        return null;
-    }
-    let depth = 0;
-    for (let index = openBraceIndex; index < source.length; index += 1) {
-        const character = source[index];
-        if (character === "{") {
-            depth += 1;
-            continue;
-        }
-        if (character !== "}") {
-            continue;
-        }
-        depth -= 1;
-        if (depth === 0) {
-            let functionEnd = index + 1;
-            while (functionEnd < source.length && /[\r\n]/u.test(source[functionEnd] ?? "")) {
-                functionEnd += 1;
-            }
-            return {
-                end: functionEnd,
-                start: functionStart,
-            };
-        }
-    }
-    return null;
-}
-function replacePhpFunctionDefinition(source, functionName, replacement) {
-    const functionRange = findPhpFunctionRange(source, functionName);
-    if (!functionRange) {
-        return null;
-    }
-    return [
-        source.slice(0, functionRange.start),
-        replacement,
-        source.slice(functionRange.end),
-    ].join("");
-}
+const BINDING_ATTRIBUTE_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/u;
 function buildPatternConfigEntry(patternSlug) {
     return [
         "\t{",
@@ -73,15 +25,47 @@ function buildPatternConfigEntry(patternSlug) {
         "\t},",
     ].join("\n");
 }
-function buildBindingSourceConfigEntry(bindingSourceSlug) {
+function buildBindingSourceConfigEntry(bindingSourceSlug, target) {
     return [
         "\t{",
+        ...(target ? [`\t\tattribute: ${quoteTsString(target.attributeName)},`] : []),
+        ...(target ? [`\t\tblock: ${quoteTsString(target.blockSlug)},`] : []),
         `\t\teditorFile: ${quoteTsString(`src/bindings/${bindingSourceSlug}/editor.ts`)},`,
         `\t\tserverFile: ${quoteTsString(`src/bindings/${bindingSourceSlug}/server.php`)},`,
         `\t\tslug: ${quoteTsString(bindingSourceSlug)},`,
         "\t},",
     ].join("\n");
 }
+function assertValidBindingAttributeName(attributeName) {
+    const trimmed = attributeName.trim();
+    if (!trimmed) {
+        throw new Error("`wp-typia add binding-source` requires --attribute <attribute> to include a value when --block is provided.");
+    }
+    if (!BINDING_ATTRIBUTE_NAME_PATTERN.test(trimmed)) {
+        throw new Error(`Binding attribute "${attributeName}" must start with a letter and use only letters, numbers, underscores, or hyphens.`);
+    }
+    return trimmed;
+}
+function resolveBindingTargetBlockSlug(blockName, namespace) {
+    const trimmed = blockName.trim();
+    if (!trimmed) {
+        throw new Error("`wp-typia add binding-source` requires --block <block-slug|namespace/block-slug> to include a value when --attribute is provided.");
+    }
+    const blockNameSegments = trimmed.split("/");
+    if (blockNameSegments.length > 2) {
+        throw new Error(`Binding target block "${trimmed}" must use <block-slug> or <namespace/block-slug> format.`);
+    }
+    if (blockNameSegments.some((segment) => segment.trim() === "")) {
+        throw new Error(`Binding target block "${trimmed}" must use <block-slug> or <namespace/block-slug> format without empty path segments.`);
+    }
+    const [maybeNamespace, maybeSlug] = blockNameSegments.length === 2
+        ? blockNameSegments
+        : [undefined, blockNameSegments[0]];
+    if (maybeNamespace && maybeNamespace !== namespace) {
+        throw new Error(`Binding target block "${trimmed}" uses namespace "${maybeNamespace}". Expected "${namespace}".`);
+    }
+    return normalizeBlockSlug(maybeSlug ?? "");
+}
 function buildEditorPluginConfigEntry(editorPluginSlug, slot) {
     return [
         "\t{",
@@ -91,13 +75,6 @@ function buildEditorPluginConfigEntry(editorPluginSlug, slot) {
         "\t},",
     ].join("\n");
 }
-function toPascalCaseFromSlug(slug) {
-    return normalizeBlockSlug(slug)
-        .split("-")
-        .filter(Boolean)
-        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
-        .join("");
-}
 function buildPatternSource(patternSlug, namespace, textDomain) {
     const patternTitle = toTitleCase(patternSlug);
     return `<?php
@@ -116,12 +93,36 @@ register_block_pattern(
 );
 `;
 }
-function buildBindingSourceServerSource(bindingSourceSlug, phpPrefix, namespace, textDomain) {
+function buildBindingSourceServerSource(bindingSourceSlug, phpPrefix, namespace, textDomain, target) {
     const bindingSourceTitle = toTitleCase(bindingSourceSlug);
     const bindingSourcePhpId = bindingSourceSlug.replace(/-/g, "_");
     const bindingSourceValueFunctionName = `${phpPrefix}_${bindingSourcePhpId}_binding_source_values`;
     const bindingSourceResolveFunctionName = `${phpPrefix}_${bindingSourcePhpId}_resolve_binding_source_value`;
+    const bindingSourceSupportedAttributesFunctionName = `${phpPrefix}_${bindingSourcePhpId}_supported_binding_attributes`;
     const starterValue = `${bindingSourceTitle} starter value`;
+    const supportedAttributesSource = target
+        ? `
+if ( ! function_exists( '${bindingSourceSupportedAttributesFunctionName}' ) ) {
+\tfunction ${bindingSourceSupportedAttributesFunctionName}( array $supported_attributes ) : array {
+\t\tif ( ! in_array( ${quotePhpString(target.attributeName)}, $supported_attributes, true ) ) {
+\t\t\t$supported_attributes[] = ${quotePhpString(target.attributeName)};
+\t\t}
+
+\t\treturn $supported_attributes;
+\t}
+}
+`
+        : "";
+    const supportedAttributesHook = target
+        ? `
+if ( function_exists( '${bindingSourceSupportedAttributesFunctionName}' ) ) {
+\tadd_filter(
+\t\t${quotePhpString(`block_bindings_supported_attributes_${namespace}/${target.blockSlug}`)},
+\t\t${quotePhpString(bindingSourceSupportedAttributesFunctionName)}
+\t);
+}
+`
+        : "";
     return `<?php
 if ( ! defined( 'ABSPATH' ) ) {
 \treturn;
@@ -150,6 +151,7 @@ if ( ! function_exists( '${bindingSourceResolveFunctionName}' ) ) {
 \t\treturn is_string( $value ) ? $value : '';
 \t}
 }
+${supportedAttributesSource}
 
 register_block_bindings_source(
 \t${quotePhpString(`${namespace}/${bindingSourceSlug}`)},
@@ -158,11 +160,22 @@ register_block_bindings_source(
 \t\t'get_value_callback' => ${quotePhpString(bindingSourceResolveFunctionName)},
 \t)
 );
-`;
+${supportedAttributesHook}`;
 }
-function buildBindingSourceEditorSource(bindingSourceSlug, namespace, textDomain) {
+function buildBindingSourceEditorSource(bindingSourceSlug, namespace, textDomain, target) {
     const bindingSourceTitle = toTitleCase(bindingSourceSlug);
     const starterValue = `${bindingSourceTitle} starter value`;
+    const bindingSourceName = `${namespace}/${bindingSourceSlug}`;
+    const targetSource = target
+        ? `
+export const BINDING_SOURCE_TARGET = {
+\tattribute: ${quoteTsString(target.attributeName)},
+\tblock: ${quoteTsString(`${namespace}/${target.blockSlug}`)},
+\tfield: ${quoteTsString(bindingSourceSlug)},
+\tsource: ${quoteTsString(bindingSourceName)},
+} as const;
+`
+        : "";
     return `import { registerBlockBindingsSource } from '@wordpress/blocks';
 import { __ } from '@wordpress/i18n';
 
@@ -175,13 +188,14 @@ interface BindingSourceRegistration {
 const BINDING_SOURCE_VALUES: Record<string, string> = {
 \t${quoteTsString(bindingSourceSlug)}: ${quoteTsString(starterValue)},
 };
+${targetSource}
 
 function resolveBindingSourceValue( field: string ): string {
 \treturn BINDING_SOURCE_VALUES[ field ] ?? '';
 }
 
 registerBlockBindingsSource( {
-\tname: ${quoteTsString(`${namespace}/${bindingSourceSlug}`)},
+\tname: ${quoteTsString(bindingSourceName)},
 \tlabel: __( ${quoteTsString(bindingSourceTitle)}, ${quoteTsString(textDomain)} ),
 \tgetFieldsList() {
 \t\treturn [
@@ -210,8 +224,99 @@ registerBlockBindingsSource( {
 } );
 `;
 }
+function resolveBindingTarget(options, namespace) {
+    const hasBlock = options.blockName !== undefined && options.blockName.trim().length > 0;
+    const hasAttribute = options.attributeName !== undefined && options.attributeName.trim().length > 0;
+    if (!hasBlock && !hasAttribute) {
+        return undefined;
+    }
+    if (!hasBlock || !hasAttribute) {
+        throw new Error("`wp-typia add binding-source` requires --block and --attribute to be provided together.");
+    }
+    return {
+        attributeName: assertValidBindingAttributeName(options.attributeName ?? ""),
+        blockSlug: resolveBindingTargetBlockSlug(options.blockName ?? "", namespace),
+    };
+}
+function formatBindingAttributeTypeMember(attributeName) {
+    const propertyName = /^[A-Za-z_$][\w$]*$/u.test(attributeName)
+        ? attributeName
+        : JSON.stringify(attributeName);
+    return [
+        "\t/**",
+        "\t * Starter string attribute declared for WordPress Block Bindings.",
+        "\t */",
+        `\t${propertyName}?: string;`,
+    ].join("\n");
+}
+function getInterfaceDeclaration(source, interfaceName) {
+    const sourceFile = ts.createSourceFile("types.ts", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    let declaration;
+    const visit = (node) => {
+        if (ts.isInterfaceDeclaration(node) && node.name.text === interfaceName) {
+            declaration = node;
+            return true;
+        }
+        return ts.forEachChild(node, (child) => (visit(child) ? true : undefined)) ?? false;
+    };
+    visit(sourceFile);
+    return declaration ? { declaration, sourceFile } : undefined;
+}
+function getPropertyNameText(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
+        return name.text;
+    }
+    return undefined;
+}
+function interfaceHasAttributeMember(declaration, attributeName) {
+    return declaration.members.some((member) => ts.isPropertySignature(member) &&
+        member.name !== undefined &&
+        getPropertyNameText(member.name) === attributeName);
+}
+function insertBindingAttributeTypeMember(source, declaration, attributeName) {
+    let closeBracePosition = declaration.end - 1;
+    while (closeBracePosition > declaration.pos && source[closeBracePosition] !== "}") {
+        closeBracePosition -= 1;
+    }
+    if (source[closeBracePosition] !== "}") {
+        throw new Error("Unable to locate the target interface closing brace.");
+    }
+    const lineEnding = source.includes("\r\n") ? "\r\n" : "\n";
+    const beforeCloseBrace = source.slice(0, closeBracePosition);
+    const afterCloseBrace = source.slice(closeBracePosition);
+    const memberSource = formatBindingAttributeTypeMember(attributeName)
+        .split("\n")
+        .join(lineEnding);
+    const prefix = beforeCloseBrace.endsWith(lineEnding) ? "" : lineEnding;
+    return `${beforeCloseBrace}${prefix}${memberSource}${lineEnding}${afterCloseBrace}`;
+}
+async function ensureBindingTargetBlockAttributeType(projectDir, block, target) {
+    if (!block.attributeTypeName) {
+        throw new Error(`Workspace block "${block.slug}" must include attributeTypeName in scripts/block-config.ts before it can receive binding-source targets.`);
+    }
+    const typesPath = path.join(projectDir, block.typesFile);
+    const source = await fsp.readFile(typesPath, "utf8");
+    const targetInterface = getInterfaceDeclaration(source, block.attributeTypeName);
+    if (!targetInterface) {
+        throw new Error(`Unable to locate interface ${block.attributeTypeName} in ${block.typesFile}.`);
+    }
+    let nextSource = source;
+    if (!interfaceHasAttributeMember(targetInterface.declaration, target.attributeName)) {
+        nextSource = insertBindingAttributeTypeMember(source, targetInterface.declaration, target.attributeName);
+        await fsp.writeFile(typesPath, nextSource, "utf8");
+    }
+    await syncBlockMetadata({
+        blockJsonFile: path.join("src", "blocks", block.slug, "block.json"),
+        jsonSchemaFile: path.join("src", "blocks", block.slug, "typia.schema.json"),
+        manifestFile: path.join("src", "blocks", block.slug, "typia.manifest.json"),
+        openApiFile: path.join("src", "blocks", block.slug, "typia.openapi.json"),
+        projectRoot: projectDir,
+        sourceTypeName: block.attributeTypeName,
+        typesFile: block.typesFile,
+    });
+}
 function buildEditorPluginTypesSource(editorPluginSlug) {
-    const typeName = `${toPascalCaseFromSlug(editorPluginSlug)}SidebarModel`;
+    const typeName = `${toPascalCase(editorPluginSlug)}EditorPluginModel`;
     return `export interface ${typeName} {
 \tprimaryActionLabel: string;
 \tsummary: string;
@@ -219,22 +324,22 @@ function buildEditorPluginTypesSource(editorPluginSlug) {
 `;
 }
 function buildEditorPluginDataSource(editorPluginSlug, slot) {
-    const typeName = `${toPascalCaseFromSlug(editorPluginSlug)}SidebarModel`;
+    const typeName = `${toPascalCase(editorPluginSlug)}EditorPluginModel`;
     const pluginTitle = toTitleCase(editorPluginSlug);
-    const modelFactoryName = `get${toPascalCaseFromSlug(editorPluginSlug)}SidebarModel`;
-    const enabledFactoryName = `is${toPascalCaseFromSlug(editorPluginSlug)}Enabled`;
+    const modelFactoryName = `get${toPascalCase(editorPluginSlug)}EditorPluginModel`;
+    const enabledFactoryName = `is${toPascalCase(editorPluginSlug)}Enabled`;
     return `import type { ${typeName} } from './types';
 
 export const EDITOR_PLUGIN_SLOT = ${quoteTsString(slot)} as const;
 export const REQUIRED_CAPABILITY = 'edit_posts' as const;
 
-const DEFAULT_SIDEBAR_MODEL: ${typeName} = {
+const DEFAULT_EDITOR_PLUGIN_MODEL: ${typeName} = {
 \tprimaryActionLabel: ${quoteTsString(`Review ${pluginTitle}`)},
 \tsummary: ${quoteTsString(`Replace this summary with your ${pluginTitle} workflow state.`)},
 };
 
 export function ${modelFactoryName}(): ${typeName} {
-\treturn DEFAULT_SIDEBAR_MODEL;
+\treturn DEFAULT_EDITOR_PLUGIN_MODEL;
 }
 
 export function ${enabledFactoryName}(): boolean {
@@ -242,11 +347,52 @@ export function ${enabledFactoryName}(): boolean {
 }
 `;
 }
-function buildEditorPluginSidebarSource(editorPluginSlug, textDomain) {
-    const pascalName = toPascalCaseFromSlug(editorPluginSlug);
-    const modelFactoryName = `get${pascalName}SidebarModel`;
+function buildEditorPluginSurfaceSource(editorPluginSlug, slot, textDomain) {
+    const pascalName = toPascalCase(editorPluginSlug);
+    const modelFactoryName = `get${pascalName}EditorPluginModel`;
     const enabledFactoryName = `is${pascalName}Enabled`;
-    const componentName = `${pascalName}Sidebar`;
+    const componentName = `${pascalName}Surface`;
+    if (slot === "document-setting-panel") {
+        return `import { Button } from '@wordpress/components';
+import { PluginDocumentSettingPanel } from '@wordpress/editor';
+import { __ } from '@wordpress/i18n';
+
+import { ${modelFactoryName}, ${enabledFactoryName} } from './data';
+import './style.scss';
+
+export interface ${componentName}Props {
+\tsurfaceName: string;
+\ttitle: string;
+}
+
+export function ${componentName}( {
+\tsurfaceName,
+\ttitle,
+}: ${componentName}Props ) {
+\tif ( ! ${enabledFactoryName}() ) {
+\t\treturn null;
+\t}
+
+\tconst editorPluginModel = ${modelFactoryName}();
+
+\treturn (
+\t\t<PluginDocumentSettingPanel
+\t\t\tclassName="wp-typia-editor-plugin-shell"
+\t\t\tname={ surfaceName }
+\t\t\ttitle={ title }
+\t\t>
+\t\t\t<p>{ editorPluginModel.summary }</p>
+\t\t\t<Button variant="secondary">
+\t\t\t\t{ editorPluginModel.primaryActionLabel }
+\t\t\t</Button>
+\t\t\t<p className="wp-typia-editor-plugin-shell__hint">
+\t\t\t\t{ __( 'Use data.ts to add post type, capability, or editor context guards before showing this panel.', ${quoteTsString(textDomain)} ) }
+\t\t\t</p>
+\t\t</PluginDocumentSettingPanel>
+\t);
+}
+`;
+    }
     return `import { Button, PanelBody } from '@wordpress/components';
 import { PluginSidebar, PluginSidebarMoreMenuItem } from '@wordpress/editor';
 import { __ } from '@wordpress/i18n';
@@ -255,34 +401,34 @@ import { ${modelFactoryName}, ${enabledFactoryName} } from './data';
 import './style.scss';
 
 export interface ${componentName}Props {
-\tpluginName: string;
+\tsurfaceName: string;
 \ttitle: string;
 }
 
 export function ${componentName}( {
-\tpluginName,
+\tsurfaceName,
 \ttitle,
 }: ${componentName}Props ) {
 \tif ( ! ${enabledFactoryName}() ) {
 \t\treturn null;
 \t}
 
-\tconst sidebarModel = ${modelFactoryName}();
+\tconst editorPluginModel = ${modelFactoryName}();
 
 \treturn (
 \t\t<>
-\t\t\t<PluginSidebarMoreMenuItem target={ pluginName }>
+\t\t\t<PluginSidebarMoreMenuItem target={ surfaceName }>
 \t\t\t\t{ title }
 \t\t\t</PluginSidebarMoreMenuItem>
-\t\t\t<PluginSidebar name={ pluginName } title={ title }>
+\t\t\t<PluginSidebar name={ surfaceName } title={ title }>
 \t\t\t\t<div className="wp-typia-editor-plugin-shell">
 \t\t\t\t\t<PanelBody
 \t\t\t\t\t\tinitialOpen
 \t\t\t\t\t\ttitle={ __( 'Document workflow', ${quoteTsString(textDomain)} ) }
 \t\t\t\t\t>
-\t\t\t\t\t\t<p>{ sidebarModel.summary }</p>
+\t\t\t\t\t\t<p>{ editorPluginModel.summary }</p>
 \t\t\t\t\t\t<Button variant="secondary">
-\t\t\t\t\t\t\t{ sidebarModel.primaryActionLabel }
+\t\t\t\t\t\t\t{ editorPluginModel.primaryActionLabel }
 \t\t\t\t\t\t</Button>
 \t\t\t\t\t</PanelBody>
 \t\t\t\t</div>
@@ -293,24 +439,26 @@ export function ${componentName}( {
 `;
 }
 function buildEditorPluginEntrySource(editorPluginSlug, namespace, textDomain) {
-    const pascalName = toPascalCaseFromSlug(editorPluginSlug);
-    const componentName = `${pascalName}Sidebar`;
+    const pascalName = toPascalCase(editorPluginSlug);
+    const componentName = `${pascalName}Surface`;
     const pluginName = `${namespace}-${editorPluginSlug}`;
+    const surfaceName = `${pluginName}-surface`;
     const pluginTitle = toTitleCase(editorPluginSlug);
     return `import { registerPlugin } from '@wordpress/plugins';
 import { __ } from '@wordpress/i18n';
 
 import { REQUIRED_CAPABILITY } from './data';
-import { ${componentName} } from './Sidebar';
+import { ${componentName} } from './Surface';
 
 const EDITOR_PLUGIN_NAME = ${quoteTsString(pluginName)};
+const EDITOR_PLUGIN_SURFACE_NAME = ${quoteTsString(surfaceName)};
 const EDITOR_PLUGIN_TITLE = __( ${quoteTsString(pluginTitle)}, ${quoteTsString(textDomain)} );
 
 registerPlugin( EDITOR_PLUGIN_NAME, {
 \ticon: 'admin-generic',
 \trender: () => (
 \t\t<${componentName}
-\t\t\tpluginName={ EDITOR_PLUGIN_NAME }
+\t\t\tsurfaceName={ EDITOR_PLUGIN_SURFACE_NAME }
 \t\t\ttitle={ EDITOR_PLUGIN_TITLE }
 \t\t/>
 \t),
@@ -327,6 +475,11 @@ function buildEditorPluginStyleSource() {
 .wp-typia-editor-plugin-shell p {
 \tmargin: 0 0 12px;
 }
+
+.wp-typia-editor-plugin-shell__hint {
+\tcolor: #757575;
+\tfont-size: 12px;
+}
 `;
 }
 function buildBindingSourceIndexSource(bindingSourceSlugs) {
@@ -445,7 +598,6 @@ function ${bindingEditorEnqueueFunctionName}() {
             /add_action\(\s*["']init["']\s*,\s*["'][^"']+_load_textdomain["']\s*\);\s*\n/u,
             /\?>\s*$/u,
         ];
-        const hasPhpFunctionDefinition = (functionName) => new RegExp(`function\\s+${escapeRegex(functionName)}\\s*\\(`, "u").test(nextSource);
         const insertPhpSnippet = (snippet) => {
             for (const anchor of insertionAnchors) {
                 const candidate = nextSource.replace(anchor, (match) => `${snippet}\n${match}`);
@@ -464,10 +616,10 @@ function ${bindingEditorEnqueueFunctionName}() {
             }
             nextSource = `${nextSource.trimEnd()}\n${snippet}\n`;
         };
-        if (!hasPhpFunctionDefinition(bindingRegistrationFunctionName)) {
+        if (!hasPhpFunctionDefinition(nextSource, bindingRegistrationFunctionName)) {
             insertPhpSnippet(bindingRegistrationFunction);
         }
-        if (!hasPhpFunctionDefinition(bindingEditorEnqueueFunctionName)) {
+        if (!hasPhpFunctionDefinition(nextSource, bindingEditorEnqueueFunctionName)) {
             insertPhpSnippet(bindingEditorEnqueueFunction);
         }
         if (!nextSource.includes(bindingRegistrationHook)) {
@@ -528,7 +680,6 @@ function ${enqueueFunctionName}() {
             /add_action\(\s*["']init["']\s*,\s*["'][^"']+_load_textdomain["']\s*\);\s*\n/u,
             /\?>\s*$/u,
         ];
-        const hasPhpFunctionDefinition = (functionName) => new RegExp(`function\\s+${escapeRegex(functionName)}\\s*\\(`, "u").test(nextSource);
         const insertPhpSnippet = (snippet) => {
             for (const anchor of insertionAnchors) {
                 const candidate = nextSource.replace(anchor, (match) => `${snippet}\n${match}`);
@@ -547,7 +698,7 @@ function ${enqueueFunctionName}() {
             }
             nextSource = `${nextSource.trimEnd()}\n${snippet}\n`;
         };
-        if (!hasPhpFunctionDefinition(enqueueFunctionName)) {
+        if (!hasPhpFunctionDefinition(nextSource, enqueueFunctionName)) {
             insertPhpSnippet(enqueueFunction);
         }
         else {
@@ -657,7 +808,7 @@ async function writeEditorPluginRegistry(projectDir, editorPluginSlug) {
  * Defaults to `process.cwd()`.
  * @param options.editorPluginName Human-entered editor-plugin name that will be
  * normalized and validated before files are written.
- * @param options.slot Optional editor plugin shell slot. Defaults to `PluginSidebar`.
+ * @param options.slot Optional editor plugin shell slot. Defaults to `sidebar`.
  * @returns A promise that resolves with the normalized `editorPluginSlug`, chosen
  * `slot`, and owning `projectDir` after the scaffold files and inventory entry
  * are written successfully.
@@ -666,7 +817,7 @@ async function writeEditorPluginRegistry(projectDir, editorPluginSlug) {
  */
 export async function runAddEditorPluginCommand({ cwd = process.cwd(), editorPluginName, slot, }) {
     const workspace = resolveWorkspaceProject(cwd);
-    const editorPluginSlug = assertValidGeneratedSlug("Editor plugin name", normalizeBlockSlug(editorPluginName), "wp-typia add editor-plugin <name> [--slot <PluginSidebar>]");
+    const editorPluginSlug = assertValidGeneratedSlug("Editor plugin name", normalizeBlockSlug(editorPluginName), "wp-typia add editor-plugin <name> [--slot <sidebar|document-setting-panel>]");
     const resolvedSlot = assertValidEditorPluginSlot(slot);
     const inventory = readWorkspaceInventory(workspace.projectDir);
     assertEditorPluginDoesNotExist(workspace.projectDir, editorPluginSlug, inventory);
@@ -677,7 +828,7 @@ export async function runAddEditorPluginCommand({ cwd = process.cwd(), editorPlu
     const webpackConfigPath = path.join(workspace.projectDir, "webpack.config.js");
     const editorPluginDir = path.join(workspace.projectDir, "src", "editor-plugins", editorPluginSlug);
     const entryFilePath = path.join(editorPluginDir, "index.tsx");
-    const sidebarFilePath = path.join(editorPluginDir, "Sidebar.tsx");
+    const surfaceFilePath = path.join(editorPluginDir, "Surface.tsx");
     const dataFilePath = path.join(editorPluginDir, "data.ts");
     const typesFilePath = path.join(editorPluginDir, "types.ts");
     const styleFilePath = path.join(editorPluginDir, "style.scss");
@@ -698,7 +849,7 @@ export async function runAddEditorPluginCommand({ cwd = process.cwd(), editorPlu
         await ensureEditorPluginBuildScriptAnchors(workspace);
         await ensureEditorPluginWebpackAnchors(workspace);
         await fsp.writeFile(entryFilePath, buildEditorPluginEntrySource(editorPluginSlug, workspace.workspace.namespace, workspace.workspace.textDomain), "utf8");
-        await fsp.writeFile(sidebarFilePath, buildEditorPluginSidebarSource(editorPluginSlug, workspace.workspace.textDomain), "utf8");
+        await fsp.writeFile(surfaceFilePath, buildEditorPluginSurfaceSource(editorPluginSlug, resolvedSlot, workspace.workspace.textDomain), "utf8");
         await fsp.writeFile(dataFilePath, buildEditorPluginDataSource(editorPluginSlug, resolvedSlot), "utf8");
         await fsp.writeFile(typesFilePath, buildEditorPluginTypesSource(editorPluginSlug), "utf8");
         await fsp.writeFile(styleFilePath, buildEditorPluginStyleSource(), "utf8");
@@ -768,42 +919,75 @@ export async function runAddPatternCommand({ cwd = process.cwd(), patternName, }
  * Add one block binding source scaffold to an official workspace project.
  *
  * @param options Command options for the binding-source scaffold workflow.
+ * @param options.attributeName Optional generated block attribute to declare as
+ * bindable. Must be provided together with `blockName`.
+ * @param options.blockName Optional generated block slug or full block name to
+ * receive the bindable attribute wiring. Must be provided together with
+ * `attributeName`.
  * @param options.bindingSourceName Human-entered binding source name that will
  * be normalized and validated before files are written.
  * @param options.cwd Working directory used to resolve the nearest official
  * workspace. Defaults to `process.cwd()`.
  * @returns A promise that resolves with the normalized `bindingSourceSlug` and
- * owning `projectDir` after the server/editor files and inventory entry have
- * been written successfully.
+ * owning `projectDir` after the server/editor files, optional target block
+ * metadata, and inventory entry have been written successfully.
  * @throws {Error} When the command is run outside an official workspace, when
- * the slug is invalid, or when a conflicting file or inventory entry exists.
+ * the slug is invalid, when a binding target is incomplete or unknown, or when
+ * a conflicting file or inventory entry exists.
  */
-export async function runAddBindingSourceCommand({ bindingSourceName, cwd = process.cwd(), }) {
+export async function runAddBindingSourceCommand({ attributeName, bindingSourceName, blockName, cwd = process.cwd(), }) {
     const workspace = resolveWorkspaceProject(cwd);
-    const bindingSourceSlug = assertValidGeneratedSlug("Binding source name", normalizeBlockSlug(bindingSourceName), "wp-typia add binding-source <name>");
+    const bindingSourceSlug = assertValidGeneratedSlug("Binding source name", normalizeBlockSlug(bindingSourceName), "wp-typia add binding-source <name> [--block <block-slug|namespace/block-slug> --attribute <attribute>]");
     const inventory = readWorkspaceInventory(workspace.projectDir);
     assertBindingSourceDoesNotExist(workspace.projectDir, bindingSourceSlug, inventory);
+    const target = resolveBindingTarget({
+        attributeName,
+        blockName,
+    }, workspace.workspace.namespace);
+    const targetBlock = target ? resolveWorkspaceBlock(inventory, target.blockSlug) : undefined;
     const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
     const bootstrapPath = getWorkspaceBootstrapPath(workspace);
     const bindingsIndexPath = resolveBindingSourceRegistryPath(workspace.projectDir);
     const bindingSourceDir = path.join(workspace.projectDir, "src", "bindings", bindingSourceSlug);
     const serverFilePath = path.join(bindingSourceDir, "server.php");
     const editorFilePath = path.join(bindingSourceDir, "editor.ts");
+    const blockJsonPath = target
+        ? path.join(workspace.projectDir, "src", "blocks", target.blockSlug, "block.json")
+        : undefined;
+    const targetGeneratedMetadataPaths = target
+        ? [
+            path.join(workspace.projectDir, "src", "blocks", target.blockSlug, "typia.manifest.json"),
+            path.join(workspace.projectDir, "src", "blocks", target.blockSlug, "typia.openapi.json"),
+            path.join(workspace.projectDir, "src", "blocks", target.blockSlug, "typia.schema.json"),
+            path.join(workspace.projectDir, "src", "blocks", target.blockSlug, "typia-validator.php"),
+        ]
+        : [];
     const mutationSnapshot = {
-        fileSources: await snapshotWorkspaceFiles([blockConfigPath, bootstrapPath, bindingsIndexPath]),
+        fileSources: await snapshotWorkspaceFiles([
+            blockConfigPath,
+            bootstrapPath,
+            bindingsIndexPath,
+            ...(blockJsonPath ? [blockJsonPath] : []),
+            ...(targetBlock ? [path.join(workspace.projectDir, targetBlock.typesFile)] : []),
+            ...targetGeneratedMetadataPaths,
+        ]),
         snapshotDirs: [],
         targetPaths: [bindingSourceDir],
     };
     try {
         await fsp.mkdir(bindingSourceDir, { recursive: true });
         await ensureBindingSourceBootstrapAnchors(workspace);
-        await fsp.writeFile(serverFilePath, buildBindingSourceServerSource(bindingSourceSlug, workspace.workspace.phpPrefix, workspace.workspace.namespace, workspace.workspace.textDomain), "utf8");
-        await fsp.writeFile(editorFilePath, buildBindingSourceEditorSource(bindingSourceSlug, workspace.workspace.namespace, workspace.workspace.textDomain), "utf8");
+        await fsp.writeFile(serverFilePath, buildBindingSourceServerSource(bindingSourceSlug, workspace.workspace.phpPrefix, workspace.workspace.namespace, workspace.workspace.textDomain, target), "utf8");
+        await fsp.writeFile(editorFilePath, buildBindingSourceEditorSource(bindingSourceSlug, workspace.workspace.namespace, workspace.workspace.textDomain, target), "utf8");
+        if (target && targetBlock) {
+            await ensureBindingTargetBlockAttributeType(workspace.projectDir, targetBlock, target);
+        }
         await writeBindingSourceRegistry(workspace.projectDir, bindingSourceSlug);
         await appendWorkspaceInventoryEntries(workspace.projectDir, {
-            bindingSourceEntries: [buildBindingSourceConfigEntry(bindingSourceSlug)],
+            bindingSourceEntries: [buildBindingSourceConfigEntry(bindingSourceSlug, target)],
         });
         return {
+            ...(target ? { attributeName: target.attributeName, blockSlug: target.blockSlug } : {}),
             bindingSourceSlug,
             projectDir: workspace.projectDir,
         };