@designbasekorea/wordpress-ui 0.1.6 → 0.1.8

package/docs/WORDPRESS-ADMIN-GUIDE.md

@@ -2,7 +2,7 @@
 
 이 문서는 `@designbasekorea/wordpress-ui`를 WordPress 플러그인과 테마의 관리자 화면에 적용하는 표준 가이드입니다.
 
-이 가이드의 기준 배포 버전은 `0.1.6`입니다. `@designbasekorea/ui-wc@0.8.7`과
+이 가이드의 기준 배포 버전은 `0.1.8`입니다. `@designbasekorea/ui-wc@0.8.8`과
 같은 세트를 사용하세요. 플러그인 또는 테마의 lockfile과
 vendor 산출물도 같은 버전으로 맞추고, 버전을 올릴 때마다 아래 검증 명령을 다시
 실행합니다.
@@ -63,7 +63,7 @@ WordPress plugin/theme
 ### 2.1 Node 프로젝트에 설치
 
 ```bash
-npm install @designbasekorea/wordpress-ui@0.1.6
+npm install @designbasekorea/wordpress-ui@0.1.8
 ```
 
 WordPress 서버가 npm을 실행하는 것이 아닙니다. 라이브러리를 설치한 뒤 플러그인 또는 테마 빌드 과정에서 배포에 필요한 파일을 포함해야 합니다.
@@ -144,7 +144,7 @@ require_once __DIR__ . '/vendor/wordpress-ui/wordpress-ui.php';
 
 final class MyPlugin_Admin_Assets
 {
-    private const UI_VERSION = '0.1.6';
+    private const UI_VERSION = '0.1.8';
 
     public static function init(): void
     {
@@ -256,11 +256,42 @@ add_action('admin_enqueue_scripts', static function (string $hook_suffix): void
 - `admin_enqueue_scripts`에서만 관리자 자산을 등록합니다.
 - 현재 화면이 허용된 화면일 때만 `styles.css`와 `browser.iife.js`를 enqueue합니다.
 - WordPress 전역 관리자 화면에 자산을 무조건 enqueue하지 않습니다.
-- `browser.iife.js`는 `styles.css`보다 먼저 또는 함께 등록되어야 하며, 플러그인 JS는 `myplugin-wordpress-ui-browser`에 의존합니다.
+- `browser.iife.js`는 `styles.css`와 함께 등록하고, **head에서 blocking**으로 로드합니다. footer/`defer`면 `db-*`가 빈 태그로 보이다가 늦게 그려집니다.
+- 플러그인 admin.js는 footer에 두되 handle `…-wordpress-ui-browser`에 의존합니다.
 - 버전은 패키지 버전, 플러그인 버전 또는 `filemtime()` 중 하나로 일관되게 관리합니다.
 - 사용자가 접근하지 못하는 화면에 자산을 enqueue하지 않습니다. 단, 자산 노출 자체가 민감한 정보를 포함하지 않는지도 별도로 검토합니다.
 - 최종 HTML에서 CDN, unpkg, jsDelivr, 외부 icon font를 요청하지 않습니다.
 
+### 3.4 첫 페인트 — 사이드바·헤더가 늦게 보이는 이유
+
+`db-admin-shell`, `db-sidebar`, `db-page-header`는 Web Component입니다. `browser.iife.js`가
+`customElements.define`하기 전까지는 브라우저가 빈 unknown element로 그립니다.
+
+바로 보이게 하려면 **플러그인에서 스켈레톤을 따로 만들 필요는 없습니다.** 패키지 helper가
+runtime을 head에 넣고, CSS는 `:not(:defined)`인 `db-*`를 숨깁니다. 플러그인이 할 일은
+해당 화면에만 enqueue하는 것입니다.
+
+```php
+designbase_wordpress_ui_enqueue([
+    'handle' => 'myplugin-wordpress-ui',
+    'base_url' => $base_url,
+    'base_path' => $base_path,
+    'version' => self::UI_VERSION,
+    // 기본값 false. footer로 옮기면 사이드바/헤더가 늦게 나타납니다.
+    // 'in_footer' => false,
+]);
+```
+
+직접 `wp_enqueue_script`를 쓸 때도 다섯 번째 인자를 `false`(head)로 둡니다.
+
+```php
+wp_enqueue_script('myplugin-wordpress-ui-browser', $src, [], $version, false);
+```
+
+몇 초나 걸리는 경우는 보통 runtime이 footer에 있거나, 플러그인 번들이 wordpress-ui를
+감싼 채 defer/비동기로 늦게 실행되는 경우입니다. wordpress-ui는 별도 파일로 head에
+두고, 플러그인 JS만 footer에서 이벤트·REST를 붙이세요.
+
 ## 4. HTML/vanilla 적용
 
 WordPress 플러그인과 테마의 기본 선택지는 vanilla/PHP입니다. React가 없어도 동일한 Designbase 스타일과 ui-wc Web Component를 사용할 수 있습니다.
@@ -423,7 +454,7 @@ select?.addEventListener('db-change', (event) => {
 React는 선택 사항입니다. Gutenberg나 기존 React 앱과 연결해야 하는 화면에서만 사용하고, 일반적인 PHP admin page에는 vanilla entry를 권장합니다.
 
 ```bash
-npm install @designbasekorea/wordpress-ui@0.1.6 react react-dom
+npm install @designbasekorea/wordpress-ui@0.1.8 react react-dom
 ```
 
 ```tsx
@@ -501,7 +532,7 @@ React adapter의 책임은 관리자 shell과 ui-wc primitives 조합입니다.
 
 - `AdminShell`: `sidebarTitle`(사이드바 로고)과 `sidebarItems`(메뉴). 내부에서 `.designbase-wp-admin` root를 만듭니다.
 - `AdminPage`, `AdminPageContent`: 페이지 폭과 밀도
-- `AdminPageHeader`: title, description, breadcrumb, action. 모바일에서는 메뉴 버튼을 붙입니다.
+- `AdminPageHeader`: title, description, breadcrumb, action. 태블릿 이하에서는 제목 왼쪽에 사이드바 열기/닫기 버튼을 붙입니다. 기본값은 닫힘입니다.
 - `Section`, `Table`, `SearchBar`, `Select`, `Tabs`, `EmptyState`, `Modal` 등: 같은 패키지의 React primitives. `AdminSection` / `AdminDataTable` / `AdminFilterBar` 같은 별도 래퍼는 없습니다.
 
 이 컴포넌트들은 REST 요청, 페이지네이션 API, nonce 갱신, capability 검사를 대신하지 않습니다. React state와 서버 데이터의 생명주기는 플러그인/테마 앱이 소유합니다.
@@ -781,7 +812,7 @@ body { ... }
 
 - input/select/button이 브라우저 기본 모양으로 보임: `styles.css`가 빠졌거나 root 밖에 렌더링된 경우가 많습니다.
 - 아이콘이 네모 또는 빈 공간으로 보임: font 파일 경로, CSS font-family, 배포 파일 누락을 확인합니다.
-- `db-*` element가 평범한 빈 element처럼 보임: `browser.iife.js`가 로드되지 않았거나 custom element 등록 전에 markup이 실행된 경우입니다.
+- `db-*` element가 평범한 빈 element처럼 보였다가 늦게 채워짐: `browser.iife.js`가 footer/`defer`로 로드되고 있을 가능성이 큽니다. helper 기본값(head)을 쓰거나 `in_footer => false`인지 확인합니다.
 - WordPress 다른 화면까지 모양이 바뀜: root 밖의 전역 selector가 존재하는지 확인합니다.
 - sidebar 모바일 toggle이 작동하지 않음: `data-dbwp-sidebar-toggle` 대상 ID, browser runtime, `aria-expanded`를 확인합니다.
 

package/examples/vanilla.html

@@ -5,6 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>wordpress-ui vanilla example</title>
     <link rel="stylesheet" href="../dist/styles.css">
+    <script src="../dist/browser.iife.js"></script>
 </head>
 <body>
     <div class="wrap designbase-wp-admin">
@@ -53,6 +54,5 @@
             </db-section>
         </db-admin-shell>
     </div>
-    <script src="../dist/browser.iife.js"></script>
 </body>
 </html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designbasekorea/wordpress-ui",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "WordPress 관리자용 Designbase UI primitives와 plugin shell patterns",
   "type": "module",
   "main": "dist/index.cjs",
@@ -74,7 +74,7 @@
         "build-storybook": "storybook build"
     },
   "dependencies": {
-    "@designbasekorea/ui-wc": "0.8.7"
+    "@designbasekorea/ui-wc": "0.8.8"
   },
   "peerDependencies": {
     "react": ">=18.0.0 <20.0.0",

package/wordpress-ui.php

@@ -19,6 +19,9 @@ if (!function_exists('designbase_wordpress_ui_enqueue')) {
      *     @type string $base_url  Public URL of the package root.
      *     @type string $base_path Filesystem path of the package root.
      *     @type string $version   Optional cache version.
+     *     @type bool   $in_footer When true, print the runtime in the footer.
+     *                             Default false so custom elements upgrade before
+     *                             plugin markup is parsed (avoids empty sidebar/header).
      * }
      * @return bool
      */
@@ -33,6 +36,7 @@ if (!function_exists('designbase_wordpress_ui_enqueue')) {
             'base_url' => '',
             'base_path' => '',
             'version' => '',
+            'in_footer' => false,
         ]);
 
         $base_url = untrailingslashit((string) $args['base_url']);
@@ -58,7 +62,19 @@ if (!function_exists('designbase_wordpress_ui_enqueue')) {
         }
 
         wp_enqueue_style($handle, $base_url . '/dist/styles.css', [], $version);
-        wp_enqueue_script($handle . '-browser', $base_url . '/dist/browser.iife.js', [], $version, true);
+        // Unscoped on purpose: the bundled CSS cannot target `body.wp-toolbar`
+        // after it is prefixed with `.designbase-wp-admin`.
+        wp_add_inline_style(
+            $handle,
+            '.wp-toolbar .designbase-wp-admin{--dbwp-chrome-offset:32px}@media screen and (max-width:782px){.wp-toolbar .designbase-wp-admin{--dbwp-chrome-offset:46px}}'
+        );
+        wp_enqueue_script(
+            $handle . '-browser',
+            $base_url . '/dist/browser.iife.js',
+            [],
+            $version,
+            !empty($args['in_footer'])
+        );
 
         return true;
     }