nextora-gutenberg-blocks

Nextora 블록

블록의 코드 계약(메타데이터, 등록, 편집기 UI, 동적 렌더, 뷰 스크립트, 빌드 출력 소비)을 담당합니다. 모양 규칙은 nextora-design-system이, 템플릿과 패턴은 nextora-site-composition이, 자식 테마 스캐폴딩은 nextora-child-themes가 소유합니다. 블록의 모양에 관한 요청이 있을 때마다 디자인 시스템 스킬을 로드하고, 블록이 프리셋이나 방문자 전환기를 따라야 할 때는 두 스킬을 모두 로드하세요.

먼저 다음 참조 문서를 로드하세요

작업에 필요한 부분만 이 파일의 상대 경로로 읽으세요:

파일	읽는 용도
references/block-contract.md	폴더 레이아웃, block.json 키, 등록자 동작, 카테고리 강제 변환, 생성기, esbuild/window.wp 심과 그 14개 핸들 종속 목록, save 의미 체계, 렌더 및 뷰 계약
references/editor-and-repeaters.md	두 가지 실제 목록 편집기(team-section과 자식 repeater.tsx), 정확한 커밋/취소 의미 체계, 리치 텍스트 및 미디어 헬퍼
../nextora-ecosystem/references/source-map.md	모든 규칙의 출처 및 재확인 방법, 루트 해석 용어
../nextora-ecosystem/references/quality-gates.md	데이터, 일관성, 에셋, 보안, i18n, 접근성 게이트 및 공유 다운스트림 수용 레시피(§8)

참조 문서에 인용된 값을 현재 값으로 간주하지 마세요. 편집하기 전에 대상 테마 자체 파일을 다시 읽으세요.

순서 있는 작업 흐름

1. 대상 및 블록의 호스트 테마 확인

실제 설치 또는 제공된 저장소에서 부모 테마 루트와 활성(자식) 테마 루트를 식별하세요 — get_template_directory() 및 get_stylesheet_directory(), 또는 style.css 헤더. 자식 블록은 자식이 등록하는 경우에만 존재합니다. 부모 등록자는 템플릿 디렉토리만 읽습니다. 실제 Nextora 소스 없이 Nextora 호환성을 주장하지 마세요.

2. 대상의 자체 증거 읽기

다음 순서로, 여기에 작성된 것보다 실제 값을 우선시하세요:

1. blocks/blocks.php — 등록자, glob, 가독성 검사 여부, 카테고리 필터, 각 블록 PHP 파일 로드 방식
2. blocks/*/block.json — 기존 이름, 카테고리, supports, 에셋 포인터
3. 가장 가까운 기존 블록의 edit.tsx, render.php, 선택적 view.ts, save.tsx, register-styles.php/register-editor.php
4. scripts/build-blocks.mjs — 정확한 진입 glob과 심
5. package.json + .nvmrc — 실제 존재하는 명령어와 Node 버전
6. theme.json — 블록이 참조해야 할 팔레트, 폰트, 그라디언트, 폰트 크기 및 간격 슬러그

3. 생성보다 재사용을 먼저 결정

요청된 편집 구조가 이미 존재하는 경우(다른 제목 필드, 다른 목록, 다른 토글) 기존 블록을 확장하세요. 요청된 동작 또는 편집 구조를 기존 블록, 코어 블록, 패턴 또는 블록 스타일 변형으로 표현할 수 없는 경우에만 블록을 생성하세요. 어떤 기존 블록을 재사용했는지, 또는 왜 적합한 것이 없었는지 명시하세요 — 그리고 이를 대화에서뿐만 아니라 전달물에도 명시하세요: 블록의 편집기 항목에 docblock을 추가하고 테마의 README에 한 줄을 추가하세요(거부한 가장 가까운 후보와 각각 부족한 점을 명시). 저장소만 읽는 기록자가 그 결정을 찾을 수 있어야 합니다.

4. 먼저 메타데이터 작성

apiVersion: 3, 네임스페이스/텍스트 도메인/카테고리(부모에서는 nextora + nextora, 자식에서는 <자식-슬러그>), 실제 기본값이 있는 타입 속성, 래퍼 모양을 위한 supports, 그리고 빌드된 파일을 가리키는 에셋 포인터: editorScript: "file:./index.js", render: "file:./render.php", viewScript: "file:./view.js". 메타데이터의 카테고리는 장식용입니다. PHP와 편집기 모두 네임스페이스 카테고리를 강제하므로 블록 배치를 위해 theme이나 다른 슬러그에 의존하지 마세요.

5. save 결정 후 편집기 구축

• 동적(PHP가 속성에서 렌더링): render + save: () => null.
• 중첩 블록 유지: save는 <InnerBlocks.Content />를 감싸는 useBlockProps.save()를 반환해야 합니다.
• 정적: 파서가 기대하는 대로 정확히 저장하세요.

그런 다음 edit.tsx를 기본 필드(보이는 텍스트는 RichText, 중첩 콘텐츠는 InnerBlocks, 첨부 파일은 미디어 API, URL은 코어 링크 컨트롤)와 설정용 InspectorControls/PanelBody(기존 패널 용어 재사용)를 사용하여 작성하세요. 반복 데이터는 references/editor-and-repeaters.md를 따르세요. UI 상태를 유지하지 마세요.

6. render.php 작성 (동적 블록)

루트에 get_block_wrapper_attributes(); 자체 data-*/스타일을 인수 배열에 병합; 컨텍스트별 이스케이프(esc_html, esc_attr, esc_url, wp_kses_post); 범위가 지정된 색상은 테마 헬퍼를 통해 해결; 모든 문자열은 대상 테마의 도메인으로 번역. render.php의 클래스 이름을 블록 스타일시트와 일치시키세요.

7. 동작 및 스타일 연결

블록이 프론트엔드 동작이 필요한 경우에만 view.ts를 추가하세요: 상태 속성으로 보호된 멱등성 초기화, 로딩 → 준비 전환, 예약된 레이아웃 공간, 축소된 동작 및 JS 없음 경로. 프론트엔드 CSS는 블록의 style.css(또는 뷰 스크립트의 CSS 가져오기)에 작성하고 style/editorStyle을 통해 참조; 인스펙터 및 캔버스 미리보기 CSS는 블록 범위 내로 유지하고 wp-admin 크롬에는 적용하지 마세요.

8. 빌드 후 실제 표면에서 확인

테마 루트에서 대상의 자체 스크립트 실행(npm run build:blocks, npm run build, 또는 자식의 npm run build:blocks). index.js, index.asset.php, view.js 또는 view.css를 직접 편집하지 마세요. 그런 다음 ../nextora-ecosystem/references/quality-gates.md와 그 §8 블록 레시피 및 references/block-contract.md §11의 블록별 단계를 적용하세요.

엄격한 제한

• 두 번째 React 런타임 없음, 포괄적인 @wordpress/scripts 파이프라인 없음, 두 번째 번들러 없음. 테마의 esbuild 설정을 재사용하세요.
• 목록에 없는 @wordpress/* 가져오기를 추가하면 빌드는 되지만 정의되지 않은 window.wp.* 전역 변수를 읽을 수 있습니다: 에셋 매니페스트는 고정된 14개 패키지 핸들 세트만 나열합니다. 가져오기 전에 전역 변수와 그 핸들을 확인하거나 가져오기를 피하세요.
• 블록이 사용하지 않는 라이브러리를 추가하지 마세요. 이미 package.json에 있는 라이브러리는 범위이므로 API에 의존하기 전에 잠금 파일을 읽으세요.
• deprecated 항목 또는 일회성 마이그레이션 없이 유지되는 속성 모양을 변경하지 마세요. 편집기 헬퍼를 편리하게 만들기 위해 인덱스 키 목록 스키마를 ID 키 스키마로(또는 그 반대로) 변환하지 마세요.
• 블록 요청을 충족시키기 위해 REST 라우트, 캐싱, 원격 측정, 관리 페이지 또는 관련 없는 추상화를 추가하지 마세요.
• 스킬 또는 문서를 제공하는 동안 소스 테마를 수정하지 마세요.

완료 확인

• 대상 테마 및 블록 호스트가 자체 파일에서 식별됨; 읽지 않은 소스에 근거한 주장 없음.
• 재사용 결정이 명시되었거나 블록이 새로워야 하는 구체적인 이유가 제시됨.
• block.json이 실제 네임스페이스/카테고리/텍스트 도메인 쌍을 지정하고 빌드된 에셋만 가리킴; 블록이 인서터에서 네임스페이스 카테고리 아래에 나타남.
• save가 블록의 저장 종류와 일치하며, 저장 → 다시 로드 → 블록 검증 경고 없이 다시 저장하여 확인됨.
• 보이는 텍스트, 중첩 콘텐츠, 미디어 및 URL이 기본 편집 컨트롤을 사용함; 항목 편집기는 단일 대화상자; UI 상태가 유지되지 않음.
• render.php가 컨텍스트별로 이스케이프하고 대상 도메인에서 번역함; 범위 색상이 테마 헬퍼를 통해 해결되고 빈 값은 테마 기본값을 따름.
• 뷰 동작이 멱등적이고 레이아웃을 예약하며 축소된 동작 및 JS 없음을 존중함.
• 빌드 출력이 대상의 자체 스크립트로 다시 생성됨; 생성된 파일을 수동으로 건드리지 않음.
• 관련 §8 수용 단계가 실행되었거나, 확인되지 않은 표면이 명확히 보고됨.

경계

마크다운 지침 및 소스 기반 참조 문서만 사용. 이 스킬은 런타임 스크립트, 생성기, 복사된 테마 트리, 패키지 관리 또는 설치 자동화를 제공하지 않으며, 부모 또는 자식 테마 소스를 수정하지 않습니다.