itmar-block-packages 1.4.3 → 1.6.0

package/README.md

@@ -14,6 +14,12 @@ import {関数名又はコンポーネント名} from "itmar-block-packages"
 npm i @wordpress/scripts@^27.6.0 --save-dev
 
 ## 更新履歴
+= 1.6.0 =  
+- fetchZipToAddressを新設  
+
+= 1.5.0 =  
+- useTargetBlocksを新設  
+
 = 1.4.3 =  
 - UpdateAllPostsBlockAttributesコンポーネントのRestAPIによる更新の不具合を修正
 
@@ -943,3 +949,185 @@ WordPressのRestAPIで使用するrest_baseに相当する文字列
 />
 ```
 
+## インナーブロックを取得・操作する関数
+### `useTargetBlocks`
+
+`useTargetBlocks` は、**Gutenberg ブロックエディタ上で同じ親ブロック内にある特定の名前・属性を持つブロックを取得する React フック**です。  
+ネストされたブロックの検索にも対応しています。
+
+
+
+#### 🧩 概要
+
+このカスタムフックは、次のような用途に使えます：
+
+- 同じ親ブロックの中から特定のブロックを配列で取得
+- 属性値でフィルタして一致する **1件のブロック**を取得
+- ネストされたブロックも含めて取得（オプション）
+
+---
+
+#### ✅ 使い方
+
+##### 基本構文
+
+```js
+const result = useTargetBlocks(clientId, blockName, attributeFilter?, includeNested?);
+```
+
+| 引数 | 型 | 説明 |
+|------|----|------|
+| `clientId` | `string` | 呼び出し元（自分自身）の `clientId`。`useBlockEditContext()` などで取得 |
+| `blockName` | `string` | 対象ブロック名（例: `'itmar/design-text-ctrl'`） |
+| `attributeFilter` | `object|null` | オプション：指定した属性に一致するブロックを1件だけ取得（例: `{ inputName: 'address' }`） |
+| `includeNested` | `boolean` | オプション：`true` でネストされたブロックも対象に含める（デフォルト: `false`） |
+
+---
+
+#### 🧪 使用例
+
+##### 1. 全ての `itmar/design-text-ctrl` ブロックを取得（自分を除く）
+
+```js
+import { useBlockEditContext } from '@wordpress/block-editor';
+import { useTargetBlocks } from '@your-scope/use-target-blocks';
+
+const MyComponent = () => {
+  const { clientId } = useBlockEditContext();
+
+  const blocks = useTargetBlocks(clientId, 'itmar/design-text-ctrl');
+
+  return <div>対象ブロック数: {blocks.length}</div>;
+};
+```
+
+---
+
+##### 2. `inputName: 'address'` を持つブロックを1件だけ取得
+
+```js
+const targetBlock = useTargetBlocks(clientId, 'itmar/design-text-ctrl', {
+  inputName: 'address',
+});
+
+if (targetBlock) {
+  console.log('Address block found:', targetBlock.clientId);
+}
+```
+
+---
+
+##### 3. ネストされたブロックも含めて検索
+
+```js
+const nestedBlock = useTargetBlocks(
+  clientId,
+  'itmar/design-text-ctrl',
+  { inputName: 'address' },
+  true // ネスト含める
+);
+```
+
+---
+
+#### 📁 内部で使用しているもの
+
+- `@wordpress/data`
+- `@wordpress/block-editor`
+- `useSelect`, `getBlockRootClientId`, `getBlock`, `getBlocks`
+
+---
+
+#### 🔁 補助関数：`flattenBlocks`
+
+ネストされたブロックを平坦化するためのユーティリティも内蔵：
+
+```js
+const flattenBlocks = (blocks) => {
+  return blocks.reduce((acc, block) => {
+    acc.push(block);
+    if (block.innerBlocks?.length > 0) {
+      acc.push(...flattenBlocks(block.innerBlocks));
+    }
+    return acc;
+  }, []);
+};
+```
+
+---
+
+#### 🛡️ 注意事項
+
+- このフックは **Gutenberg ブロックエディタ内でのみ使用可能**です。
+- `useTargetBlocks()` は **React フック**です。関数やイベントハンドラ内部では直接呼び出せません。
+
+---
+
+## 日本郵便番号から住所を取得するユーティリティ関数
+### `fetchZipToAddress`
+`fetchZipToAddress` は、[zipcloud](https://zipcloud.ibsnet.co.jp) API を使用して、日本の郵便番号から都道府県・市区町村・町域の住所を非同期で取得する JavaScript 関数です。  
+Gutenberg ブロック開発やフロントエンドフォーム処理において、郵便番号による住所補完機能を簡単に実装できます。
+
+
+#### 使用例（React / jQuery 共通）
+
+```js
+const addressObj = await fetchZipToAddress("1600022");
+if (addressObj) {
+  const fullAddress = addressObj.address1 + addressObj.address2 + addressObj.address3;
+  console.log(fullAddress); // 例: 東京都新宿区新宿
+}
+```
+
+---
+
+#### 🔐 バリデーション仕様
+
+- 郵便番号は「**ハイフンなしの7桁の数字**」形式のみ許可されます（例: `1234567`）。
+- 無効な形式や一致しない郵便番号、通信エラー時には `null` を返します。
+- エラーはすべて `alert()` によってユーザーに通知されます。
+
+---
+
+#### 🔁 返り値の形式（成功時）
+
+```json
+{
+  "zipcode": "1600022",
+  "prefcode": "13",
+  "address1": "東京都",
+  "address2": "新宿区",
+  "address3": "新宿",
+  ...
+}
+```
+
+---
+
+#### 🌐 使用API
+
+本ライブラリは以下の外部APIを使用しています：
+
+- **zipcloud（日本郵便公式APIラッパー）**
+  - URL: [https://zipcloud.ibsnet.co.jp](https://zipcloud.ibsnet.co.jp)
+  - ドキュメント: [https://zipcloud.ibsnet.co.jp/doc/api](https://zipcloud.ibsnet.co.jp/doc/api)
+
+#### ⚠️ ご注意
+
+- この API は外部サービス（zipcloud）に依存しており、アクセス過多による制限や仕様変更の可能性があります。
+- 本ライブラリを利用する場合は、[zipcloud利用規約](https://zipcloud.ibsnet.co.jp/doc/rule) を必ずご確認・順守してください。
+
+---
+
+#### 🧩 WordPress / Gutenberg との統合例
+
+```js
+const handleZipSearch = async () => {
+  const result = await fetchZipToAddress(zipValue);
+  if (result) {
+    setAttributes({ inputValue: result.address1 + result.address2 + result.address3 });
+  }
+};
+```
+
+

package/build/index.asset.php

@@ -1 +1 @@
-<?php return array('dependencies' => array('react', 'react-dom', 'wp-api-fetch', 'wp-block-editor', 'wp-blocks', 'wp-components', 'wp-data', 'wp-element', 'wp-i18n', 'wp-primitives'), 'version' => '6a3fc8bf3518f0a96b3a');
+<?php return array('dependencies' => array('react', 'react-dom', 'wp-api-fetch', 'wp-block-editor', 'wp-blocks', 'wp-components', 'wp-data', 'wp-element', 'wp-i18n', 'wp-primitives'), 'version' => 'ed8c3612fe1e63ebdc2a');