@designbasekorea/wordpress-ui

WordPress 플러그인·테마 관리자 화면 안에서 Designbase UI를 쓰기 위한 패키지입니다. WordPress 전역 프레임(#adminmenu, #wpadminbar, 다른 플러그인 화면)은 바꾸지 않습니다.

• 기본 런타임은 React 없는 Web Component입니다.
• REST·AJAX·Settings API·capability·nonce·데이터는 소비 플러그인이 소유합니다.
• @designbasekorea/ui-wc를 직접 import하지 마세요. 공개 API는 이 패키지입니다.

현재 배포 버전은 0.1.9입니다. @designbasekorea/[email protected]에 의존합니다.

관리자용 primitive에는 checkbox/radio/toggle을 포함해 range slider, date picker, color picker, dropzone/file uploader, progress/progressbar, toast, tooltip, popover가 포함되어 있습니다. db-card와 db-form은 관리자 surface에서 제외했으며, 상세한 속성·이벤트·WordPress 보안 패턴은 플러그인 개발용 가이드를 참고하세요.

설치

npm install @designbasekorea/[email protected]

WordPress 서버가 npm을 실행하는 것은 아닙니다. 설치한 뒤 dist/와 wordpress-ui.php를 플러그인/테마 vendor에 포함하고, 해당 관리자 화면에만 enqueue합니다.

화면 구조

모든 화면은 .wrap.designbase-wp-admin 안에서만 렌더링합니다. 스타일은 이 root 아래로 scope됩니다.

.wrap.designbase-wp-admin
└─ db-admin-shell          title = 플러그인명 (사이드바 로고 슬롯)
   ├─ db-sidebar           items = 메뉴 (섹션 제목으로 플러그인명을 넣지 않음)
   └─ main
      ├─ db-page-header    화면 제목·설명·primary action
      └─ db-container      shell이 나머지 자식을 자동으로 감쌈
         ├─ db-section
         ├─ db-search-bar / db-select / db-table / db-empty-state …

플러그인명은 사이드바 헤더 로고입니다. title/brand(vanilla) 또는 sidebarTitle(React)로 넣습니다. 메뉴 위 작은 섹션 라벨로 쓰지 않습니다.

Vanilla / PHP (권장)

필요한 화면에만 dist/styles.css와 dist/browser.iife.js를 enqueue합니다. designbase_wordpress_ui_enqueue()는 runtime을 head에 넣습니다. db-sidebar와 db-page-header는 JS가 customElements.define한 뒤에야 그려지므로, footer에 두면 빈 레이아웃이 보였다가 늦게 나타납니다. 플러그인은 화면 allowlist만 하고, 로딩 위치는 helper 기본값을 유지하세요.

플러그인 자체 admin.js는 footer에 두되 myplugin-wordpress-ui-browser에 의존하게 합니다.

require_once __DIR__ . '/vendor/wordpress-ui/wordpress-ui.php';

add_action('admin_enqueue_scripts', static function (string $hook_suffix): void {
    if ($hook_suffix !== 'toplevel_page_myplugin') {
        return;
    }

    designbase_wordpress_ui_enqueue([
        'handle' => 'myplugin-wordpress-ui',
        'base_url' => plugins_url('vendor/wordpress-ui', __FILE__),
        'base_path' => __DIR__ . '/vendor/wordpress-ui',
        'version' => '0.1.9',
    ]);
});

<?php
$items = [
    [
        'id' => 'dashboard',
        'label' => __('대시보드', 'myplugin'),
        'href' => admin_url('admin.php?page=myplugin'),
        'icon' => 'dashboard',
        'active' => (($_GET['page'] ?? '') === 'myplugin'),
    ],
    [
        'id' => 'settings',
        'label' => __('설정', 'myplugin'),
        'href' => admin_url('admin.php?page=myplugin-settings'),
        'icon' => 'settings',
        'active' => (($_GET['page'] ?? '') === 'myplugin-settings'),
    ],
];
?>
<div class="wrap designbase-wp-admin">
    <db-admin-shell
        title="My Plugin"
        items="<?php echo esc_attr(wp_json_encode($items)); ?>"
    >
        <db-page-header
            title="<?php esc_attr_e('페이지 목록', 'myplugin'); ?>"
            description="<?php esc_attr_e('페이지를 관리하세요.', 'myplugin'); ?>"
            variant="minimal"
        >
            <a slot="actions" class="button button-primary" href="<?php echo esc_url(admin_url('admin.php?page=myplugin-new')); ?>">
                <?php esc_html_e('새 페이지', 'myplugin'); ?>
            </a>
        </db-page-header>

        <db-section title="<?php esc_attr_e('최근 페이지', 'myplugin'); ?>">
            <db-table
                columns='<?php echo esc_attr(wp_json_encode([
                    ['key' => 'title', 'header' => __('제목', 'myplugin')],
                    ['key' => 'status', 'header' => __('상태', 'myplugin')],
                ])); ?>'
                data='<?php echo esc_attr(wp_json_encode($rows ?? [])); ?>'
                row-key="id"
            ></db-table>
        </db-section>
    </db-admin-shell>
</div>

db-admin-shell 계약:

| 속성 | 역할 | | --- | --- | | title 또는 brand | 사이드바 헤더의 플러그인명 | | items | 메뉴 배열 JSON. 권한·active·href는 소비자가 계산 | | sections | 메뉴를 실제 그룹으로 나눌 때만 사용. 그룹 제목에 플러그인명을 넣지 않음 | | 자식 db-page-header | 화면 헤더로 유지 | | 나머지 자식 | db-container로 감쌈 |

메뉴를 그룹으로 나눌 필요가 없으면 items만 넘기세요.

React (선택)

Gutenberg나 기존 React 앱에서만 사용합니다. 일반 PHP 관리자 화면에는 vanilla를 권장합니다.

import '@designbasekorea/wordpress-ui/styles.css';
import {
    AdminPage,
    AdminPageContent,
    AdminPageHeader,
    AdminShell,
    Button,
    Section,
    Table,
} from '@designbasekorea/wordpress-ui/react';

const sidebarItems = [
    { id: 'dashboard', label: '대시보드', href: '?page=myplugin', icon: 'dashboard', active: true },
    { id: 'settings', label: '설정', href: '?page=myplugin-settings', icon: 'settings' },
];

export function MyPluginAdmin() {
    return (
        <AdminShell sidebarTitle="My Plugin" sidebarItems={sidebarItems}>
            <AdminPageHeader
                title="페이지 목록"
                description="페이지를 검색하고 상태를 관리합니다."
                actions={<Button variant="primary" size="s">새 페이지</Button>}
            />
            <AdminPage>
                <AdminPageContent>
                    <Section title="최근 페이지" fullWidth>
                        <Table
                            columns={JSON.stringify([
                                { key: 'title', header: '제목' },
                                { key: 'status', header: '상태' },
                            ])}
                            data={JSON.stringify([])}
                            rowKey="id"
                            emptyMessage="콘텐츠가 없습니다."
                        />
                    </Section>
                </AdminPageContent>
            </AdminPage>
        </AdminShell>
    );
}

React 관리자 패턴:

• AdminShell — sidebarTitle(로고) + sidebarItems(메뉴). AdminWrapper를 포함합니다.
• AdminPageHeader — db-page-header + 태블릿 이하 제목 왼쪽 사이드바 토글
• AdminPage / AdminPageContent — 페이지 폭
• 그 외 UI는 primitives입니다. Section, Table, SearchBar, Select, EmptyState, Tabs, Modal 등. AdminSection / AdminDataTable 같은 별도 래퍼는 없습니다.

엔트리포인트

| import | 용도 | | --- | --- | | @designbasekorea/wordpress-ui/browser | React 없이 db-*와 db-admin-shell 등록. PHP는 dist/browser.iife.js | | @designbasekorea/wordpress-ui/styles.css | 테마 토큰 + ui-wc + shell + 아이콘 폰트. 별도 theme.css/CDN 아이콘 불필요 | | @designbasekorea/wordpress-ui/components 또는 패키지 루트 | TypeScript에서 DbButton, DbAdminShell 등 클래스 | | @designbasekorea/wordpress-ui/react | React façade |

import '@designbasekorea/wordpress-ui/browser';
import '@designbasekorea/wordpress-ui/styles.css';
import { DbButton, DbAdminShell } from '@designbasekorea/wordpress-ui';

아이콘은 Designbase 이름을 씁니다.

<i class="icon-dashboard" aria-hidden="true"></i>

로컬 확인

cd packages/wordpress-ui
npm run build
npm run verify
npm run storybook   # http://localhost:6008

적용 규칙·enqueue·REST/nonce는 WordPress 관리자 적용 가이드를 참고하세요.

플러그인 개발자가 컴포넌트 목록과 폼·이벤트·보안 패턴을 빠르게 확인하려면 WordPress 플러그인 개발용 가이드를 참고하세요.