@wikex/admin-kit 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+Các thay đổi đáng chú ý của `@wikex/admin-kit` được ghi tại đây theo Semantic Versioning.
+
+## 0.2.0 - 2026-09-12
+
+- Thêm `createWikexStarter`: một factory cấu hình content schema, SEO, redirect, admin UI,
+  branding, route Live Preview và module registry từ một cấu hình dự án.
+- Chuyển cấu hình phát hành sang npm public; dự án consumer không cần `.npmrc` hay token.
+
+## 0.1.0 - 2026-09-12
+
+- Tách Payload admin shell dùng chung khỏi dự án Estate.
+- Thêm Live Preview editor, drawer thuộc tính và modal chọn block dùng chung.
+- Thêm typography editor với font family, line-height và resize trực tiếp.
+- Thêm Minimal UI skin, chuẩn hóa tiếng Việt và hướng dẫn kích thước ảnh.
+- Thêm adapter branding, block catalog và route registry theo từng dự án.

package/README.md

@@ -0,0 +1,167 @@
+# @wikex/admin-kit
+
+Admin shell dùng chung cho các website Payload CMS của Wikex.
+
+Package sở hữu:
+
+- navigation, header, đăng nhập, đổi theme và branding động;
+- Minimal UI skin và các bản vá layout Payload;
+- Live Preview editor, drawer thuộc tính, block picker và resize text;
+- font family, line-height và runtime áp dụng typography;
+- chuẩn hóa tiếng Việt và hướng dẫn kích thước upload ảnh.
+
+Schema, block catalog, route registry, dashboard và seed data vẫn thuộc ứng dụng sử dụng package vì chúng thay đổi theo từng dự án.
+
+`@wikex/admin-kit` phụ thuộc `@wikex/content-kit`, nên chỉ cần cài Admin Kit là có luôn
+schema Page/Post/Media, SEO, redirects, robots và sitemap chuẩn. Schema, block catalog và
+frontend renderer cụ thể vẫn thuộc dự án consumer.
+
+## Dùng trong workspace
+
+```json
+{
+  "dependencies": {
+    "@wikex/admin-kit": "workspace:*"
+  }
+}
+```
+
+```ts
+// next.config.ts
+const nextConfig = {
+  transpilePackages: ['@wikex/admin-kit'],
+}
+```
+
+```scss
+// Payload custom.scss
+@use '@wikex/admin-kit/styles';
+```
+
+```ts
+// Payload plugins
+import { adminExperiencePlugin, wikexAdminPlugin } from '@wikex/admin-kit'
+
+export const plugins = [
+  adminExperiencePlugin,
+  wikexAdminPlugin({
+    components: {
+      beforeDashboard: '@/components/BeforeDashboard',
+      provider: '@/components/LivePreviewResizer',
+    },
+  }),
+]
+```
+
+Live Preview provider của dự án là adapter khai báo route và component khả dụng:
+
+```tsx
+'use client'
+
+import { configureAdminBrand } from '@wikex/admin-kit/admin/brand'
+import LivePreviewEditor, { configureLivePreview } from '@wikex/admin-kit/live-preview'
+
+configureLivePreview({
+  getVisualEditorRoute,
+  pageBlocks,
+  postBlocks,
+})
+
+configureAdminBrand({
+  logo: { alt: projectName, height: 64, url: '/logo.svg', width: 64 },
+  siteName: projectName,
+})
+
+export default LivePreviewEditor
+```
+
+Project config và route resolver cũng dùng API chung, nhưng tên module/collection vẫn do
+từng website quyết định:
+
+```ts
+import { createVisualEditorRouteResolver, defineWikexProject } from '@wikex/admin-kit/project'
+
+export const project = defineWikexProject({
+  brand: {
+    description: 'Website doanh nghiệp',
+    logo: { height: 64, url: '/logo.svg', width: 64 },
+    name: 'Wikex Corporate',
+  },
+  id: 'wikex-corporate',
+  modules: ['website', 'services'],
+})
+
+export const getVisualEditorRoute = createVisualEditorRouteResolver({
+  collections: ['pages'],
+  globals: { footer: 'footer', header: 'header', homepage: 'content' },
+})
+```
+
+Xem consumer không thuộc lĩnh vực bất động sản tại `examples/corporate-demo`.
+
+Ứng dụng cần cung cấp các file font tại `public/fonts/google`, hoặc ghi đè các biến `--font-*` nếu dùng font riêng.
+
+## Cài vào dự án khác — một package, một cấu hình
+
+```bash
+pnpm add @wikex/admin-kit@0.2.0
+```
+
+Không cần `.npmrc`, GitLab token hay npm token ở dự án consumer. Các peer dependency
+Payload/Next/React phải đã có trong dự án.
+
+```ts
+// src/wikex.ts — server-only config, dùng một lần trong Payload config
+import { createWikexStarter } from '@wikex/admin-kit/starter'
+import { pageBlocks, postBlocks } from './blocks'
+
+export const wikex = createWikexStarter({
+  brand: {
+    description: 'Website công ty Acme',
+    logo: { height: 64, url: '/logo.svg', width: 64 },
+    name: 'Acme',
+  },
+  content: {
+    page: { blocks: pageBlocks, previewURL: '/' },
+    post: { blocks: postBlocks, previewURL: '/news' },
+    seo: {
+      siteName: 'Acme',
+      pathFor: ({ collection, slug }) =>
+        collection === 'pages' ? (slug === 'home' ? '/' : `/${slug}`) : `/news/${slug}`,
+    },
+  },
+  globals: { footer: 'footer', header: 'header' },
+  id: 'acme',
+  provider: '@/LivePreviewAdapter',
+})
+```
+
+```ts
+// payload.config.ts
+import { wikex } from './src/wikex'
+
+export default buildConfig({
+  collections: [Users, ...wikex.collections, ...projectCollections],
+  globals: projectGlobals,
+  plugins: wikex.plugins,
+})
+```
+
+Giữ `LivePreviewAdapter.tsx` nhỏ ở client vì block renderer của mỗi website là riêng.
+Adapter gọi `createWikexLivePreviewAdapter` từ `@wikex/admin-kit/starter/client` với
+branding, block picker và route resolver tương ứng; xem implementation hoàn chỉnh tại
+`examples/corporate-demo`.
+
+## Phát hành npm public
+
+Khi phát hành:
+
+1. tăng version theo SemVer và cập nhật `CHANGELOG.md`;
+2. chạy test/typecheck/build trong starter;
+3. tạo tag `admin-kit-v<version>` để GitLab CI publish npm;
+4. ở từng dự án consumer đổi `workspace:*` thành version cố định, ví dụ `0.2.0`;
+5. nâng version có chủ đích, không dùng `latest` trong production.
+
+GitLab CI cần một CI/CD variable bảo mật `NPM_TOKEN` có quyền publish scope `@wikex`.
+Đây là credential duy nhất của phía phát hành; người dùng package công khai không cần
+credential nào.

package/RELEASING.md

@@ -0,0 +1,59 @@
+# Phát hành Admin Kit
+
+Package không tự publish khi merge. Chỉ người có quyền registry mới thực hiện phát hành.
+
+## Kiểm tra trước khi phát hành
+
+Từ thư mục gốc workspace:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm generate:types
+pnpm exec tsc --noEmit
+pnpm exec tsc --noEmit -p examples/corporate-demo/tsconfig.json
+pnpm lint
+pnpm exec vitest run --config ./vitest.config.mts --exclude tests/int/api.int.spec.ts
+pnpm build
+```
+
+Kiểm tra nội dung package:
+
+```bash
+cd packages/admin-kit
+npm pack --dry-run
+```
+
+## Version
+
+- `patch`: sửa lỗi, không đổi API.
+- `minor`: thêm tính năng tương thích ngược.
+- `major`: thay đổi adapter/API bắt buộc dự án consumer phải sửa.
+
+Cập nhật `version` trong `package.json` và ghi thay đổi vào `CHANGELOG.md` trước khi publish.
+
+## npm public
+
+Pipeline `.gitlab-ci.yml` publish vào `https://registry.npmjs.org/`. Thêm một GitLab
+CI/CD Variable tên `NPM_TOKEN`, masked và protected, chứa npm granular access token có
+quyền publish scope `@wikex` (và bypass 2FA nếu npm account bật 2FA cho publish).
+
+Token chỉ tồn tại ở CI; consumer cài package công khai không cần `.npmrc` hay token.
+
+Lần đầu kết nối source repository, chạy từ thư mục gốc:
+
+```bash
+bash scripts/connect-gitlab.sh
+```
+
+Script không ghi đè một remote `origin` khác nếu đã tồn tại.
+
+Tạo tag trùng với version package để phát hành:
+
+```bash
+git tag admin-kit-v0.2.0
+git push origin admin-kit-v0.2.0
+```
+
+Job phát hành kiểm tra tag phải đúng mẫu `admin-kit-v<version>` trước khi upload package.
+Vì Admin Kit phụ thuộc Content Kit, release `content-kit-v<version>` trước, rồi mới tạo
+tag Admin Kit dùng version Content Kit đó.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@wikex/admin-kit",
+  "version": "0.2.0",
+  "description": "Reusable Payload CMS admin shell, visual editor and typography tools for Wikex projects",
+  "license": "UNLICENSED",
+  "private": false,
+  "type": "module",
+  "sideEffects": [
+    "**/*.scss"
+  ],
+  "files": [
+    "src",
+    "CHANGELOG.md",
+    "README.md",
+    "RELEASING.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@wikex/content-kit": "^0.1.0"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./admin/before-login": "./src/admin/BeforeLogin.tsx",
+    "./admin/brand": "./src/admin/Brand.tsx",
+    "./admin/header": "./src/admin/Header.tsx",
+    "./admin/logout-button": "./src/admin/LogoutButton.tsx",
+    "./admin/nav": "./src/admin/Nav.tsx",
+    "./admin/theme-toggle": "./src/admin/ThemeToggle.tsx",
+    "./admin/view-site": "./src/admin/ViewSite.tsx",
+    "./live-preview": "./src/live-preview/index.ts",
+    "./project": "./src/project.ts",
+    "./rich-text": "./src/rich-text/index.ts",
+    "./rich-text/client": "./src/rich-text/client.tsx",
+    "./starter": "./src/starter.ts",
+    "./starter/client": "./src/starter/client.tsx",
+    "./styles": "./src/styles/admin.scss",
+    "./text-style-runtime": "./src/TextStyleRuntime.tsx",
+    "./text-styles": "./src/textStyles.ts"
+  },
+  "peerDependencies": {
+    "@lexical/react": ">=0.41.0",
+    "@lexical/selection": ">=0.41.0",
+    "@payloadcms/richtext-lexical": ">=3.88.0",
+    "@payloadcms/ui": ">=3.88.0",
+    "lexical": ">=0.41.0",
+    "lucide-react": ">=0.563.0",
+    "next": ">=16.3.3",
+    "payload": ">=3.88.0",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  }
+}

package/src/TextStyleRuntime.tsx

@@ -0,0 +1,90 @@
+'use client'
+
+import { useEffect } from 'react'
+
+import {
+  EDITABLE_PREVIEW_SELECTOR,
+  getEditableElementStyleKey,
+  getTextStyleCSS,
+  normalizeTextStyleMap,
+} from './textStyles'
+
+type OriginalStyle = {
+  boxSizing: string
+  fontFamily: string
+  lineHeight: string
+  marginLeft: string
+  marginRight: string
+  maxWidth: string
+  width: string
+}
+
+export const TextStyleRuntime = ({ styles }: { styles?: unknown }) => {
+  useEffect(() => {
+    const normalizedStyles = normalizeTextStyleMap(styles)
+    const originals = new Map<HTMLElement, OriginalStyle>()
+    let applyFrame = 0
+
+    const applyStyles = () => {
+      const fields = new Set(
+        document.querySelectorAll<HTMLElement>(`[data-wikex-field],${EDITABLE_PREVIEW_SELECTOR}`),
+      )
+
+      for (const element of fields) {
+        const fieldPath = element.dataset.wikexField || getEditableElementStyleKey(element)
+        if (!fieldPath || !normalizedStyles[fieldPath]) continue
+
+        if (!originals.has(element)) {
+          originals.set(element, {
+            boxSizing: element.style.boxSizing,
+            fontFamily: element.style.fontFamily,
+            lineHeight: element.style.lineHeight,
+            marginLeft: element.style.marginLeft,
+            marginRight: element.style.marginRight,
+            maxWidth: element.style.maxWidth,
+            width: element.style.width,
+          })
+        }
+
+        const style = getTextStyleCSS(normalizedStyles[fieldPath])
+        element.style.boxSizing = style.boxSizing || ''
+        element.style.fontFamily = style.fontFamily || ''
+        element.style.lineHeight = style.lineHeight || ''
+        element.style.marginLeft = style.marginLeft || ''
+        element.style.marginRight = style.marginRight || ''
+        element.style.maxWidth = style.maxWidth || ''
+        element.style.width = style.width || ''
+      }
+    }
+
+    const scheduleApplyStyles = () => {
+      if (applyFrame) return
+
+      applyFrame = window.requestAnimationFrame(() => {
+        applyFrame = 0
+        applyStyles()
+      })
+    }
+
+    applyStyles()
+    const observer = new MutationObserver(scheduleApplyStyles)
+    observer.observe(document.body, { childList: true, subtree: true })
+
+    return () => {
+      observer.disconnect()
+      window.cancelAnimationFrame(applyFrame)
+      for (const [element, original] of originals) {
+        if (!element.isConnected) continue
+        element.style.boxSizing = original.boxSizing
+        element.style.fontFamily = original.fontFamily
+        element.style.lineHeight = original.lineHeight
+        element.style.marginLeft = original.marginLeft
+        element.style.marginRight = original.marginRight
+        element.style.maxWidth = original.maxWidth
+        element.style.width = original.width
+      }
+    }
+  }, [styles])
+
+  return null
+}

package/src/admin/BeforeLogin.tsx

@@ -0,0 +1,19 @@
+'use client'
+
+import React from 'react'
+
+import { useAdminBrand } from './useAdminBrand'
+
+const BeforeLogin: React.FC = () => {
+  const { siteName } = useAdminBrand()
+
+  return (
+    <div className="admin-login-intro">
+      <span className="admin-login-intro__eyebrow">{siteName} · Trung tâm nội dung</span>
+      <h1>Chào mừng trở lại.</h1>
+      <p>Đăng nhập để quản lý nội dung, hình ảnh và xuất bản của {siteName}.</p>
+    </div>
+  )
+}
+
+export default BeforeLogin

package/src/admin/Brand.tsx

@@ -0,0 +1,74 @@
+'use client'
+
+import Image from 'next/image'
+import React from 'react'
+
+import { useAdminBrand } from './useAdminBrand'
+
+export type AdminBrandAsset = {
+  alt: string
+  height: number
+  url: string
+  width: number
+}
+
+const BrandLogo = ({
+  asset,
+  className,
+  height,
+  maxWidth,
+}: {
+  asset: AdminBrandAsset
+  className?: string
+  height: number
+  maxWidth: number
+  siteName: string
+}) => (
+  <span
+    className={['brand-logo', className].filter(Boolean).join(' ')}
+    style={{ alignItems: 'center', display: 'inline-flex', height, maxWidth }}
+  >
+    <Image
+      alt=""
+      height={asset.height}
+      src={asset.url}
+      style={{ height: '100%', maxWidth: '100%', objectFit: 'contain', width: 'auto' }}
+      unoptimized
+      width={asset.width}
+    />
+  </span>
+)
+
+export const AdminIcon: React.FC = () => {
+  const brand = useAdminBrand()
+
+  return (
+    <span className="aurea-brand aurea-brand--icon">
+      <BrandLogo
+        asset={brand.logo}
+        className="aurea-brand__image"
+        height={32}
+        maxWidth={32}
+        siteName={brand.siteName}
+      />
+    </span>
+  )
+}
+
+export const AdminLogo: React.FC = () => {
+  const brand = useAdminBrand()
+
+  return (
+    <span aria-label={brand.siteName} className="aurea-brand aurea-brand--logo" role="img">
+      <BrandLogo
+        asset={brand.logo}
+        className="aurea-brand__image"
+        height={42}
+        maxWidth={190}
+        siteName={brand.siteName}
+      />
+    </span>
+  )
+}
+
+export { configureAdminBrand, useAdminBrand, type AdminBrandSettings } from './useAdminBrand'

package/src/admin/Header.tsx

@@ -0,0 +1,87 @@
+'use client'
+
+import { Link, useAuth, useConfig, useNav } from '@payloadcms/ui'
+import { Menu, Settings2 } from 'lucide-react'
+import { formatAdminURL } from 'payload/shared'
+import React from 'react'
+
+import { AdminIcon } from './Brand'
+import AdminThemeToggle from './ThemeToggle'
+import AdminViewSite from './ViewSite'
+
+type AdminUser = {
+  email?: string
+  name?: string
+}
+
+const getInitials = (name?: string, email?: string) => {
+  const source = name?.trim() || email?.split('@')[0] || 'AD'
+
+  return source
+    .split(/\s+/)
+    .slice(0, 2)
+    .map((part) => part.charAt(0).toUpperCase())
+    .join('')
+}
+
+const AdminHeader = () => {
+  const { user } = useAuth<AdminUser>()
+  const { setNavOpen } = useNav()
+  const {
+    config: {
+      admin: { routes: adminRoutes },
+      routes: { admin: adminRoute },
+    },
+  } = useConfig()
+
+  const userLabel = user?.name?.trim() || user?.email?.split('@')[0] || 'Quản trị viên'
+  const initials = getInitials(user?.name, user?.email)
+
+  return (
+    <header className="minimal-admin-header">
+      <div className="minimal-admin-header__left">
+        <button
+          aria-label="Mở menu quản trị"
+          className="minimal-admin-header__menu"
+          onClick={() => setNavOpen(true)}
+          type="button"
+        >
+          <Menu aria-hidden="true" />
+        </button>
+        <Link
+          aria-label="Về dashboard"
+          className="minimal-admin-header__mobile-brand"
+          href={adminRoute}
+          prefetch={false}
+        >
+          <AdminIcon />
+        </Link>
+      </div>
+
+      <div className="minimal-admin-header__actions">
+        <AdminViewSite />
+        <AdminThemeToggle />
+        <Link
+          aria-label={`Mở tài khoản ${userLabel}`}
+          className="minimal-admin-header__settings"
+          href={formatAdminURL({ adminRoute, path: adminRoutes.account })}
+          prefetch={false}
+          title="Cài đặt tài khoản"
+        >
+          <Settings2 aria-hidden="true" />
+        </Link>
+        <Link
+          aria-label={`Mở tài khoản ${userLabel}`}
+          className="minimal-admin-header__account"
+          href={formatAdminURL({ adminRoute, path: adminRoutes.account })}
+          prefetch={false}
+          title={userLabel}
+        >
+          <span>{initials}</span>
+        </Link>
+      </div>
+    </header>
+  )
+}
+
+export default AdminHeader

package/src/admin/LogoutButton.tsx

@@ -0,0 +1,41 @@
+'use client'
+
+import { Link, useConfig, useTranslation } from '@payloadcms/ui'
+import { LogOut } from 'lucide-react'
+import { formatAdminURL } from 'payload/shared'
+import React from 'react'
+
+type AdminLogoutButtonProps = {
+  tabIndex?: number
+}
+
+const AdminLogoutButton: React.FC<AdminLogoutButtonProps> = ({ tabIndex = 0 }) => {
+  const {
+    config: {
+      admin: {
+        routes: { logout: logoutRoute },
+      },
+      routes: { admin: adminRoute },
+    },
+  } = useConfig()
+  const { t } = useTranslation()
+  const label = t('authentication:logOut')
+
+  return (
+    <Link
+      aria-label={label}
+      className="admin-sign-out"
+      href={formatAdminURL({ adminRoute, path: logoutRoute })}
+      prefetch={false}
+      tabIndex={tabIndex}
+      title={label}
+    >
+      <span aria-hidden="true" className="admin-sign-out__icon">
+        <LogOut strokeWidth={2} />
+      </span>
+      <span className="admin-sign-out__label">{label}</span>
+    </Link>
+  )
+}
+
+export default AdminLogoutButton

package/src/admin/Nav.tsx

@@ -0,0 +1,35 @@
+import { getNavGroups } from '@payloadcms/ui/shared'
+import type { ServerProps, StaticLabel } from 'payload'
+import React from 'react'
+
+import { AdminNavClient, type AdminNavGroup } from './NavClient'
+
+const localizeLabel = (label: StaticLabel, language: string): string => {
+  if (typeof label === 'string') return label
+
+  return label[language] || Object.values(label)[0] || ''
+}
+
+const AdminNav = ({ i18n, payload, permissions, visibleEntities }: ServerProps) => {
+  if (!permissions || !visibleEntities) return null
+
+  const groups: AdminNavGroup[] = getNavGroups(
+    permissions,
+    visibleEntities,
+    payload.config,
+    i18n,
+  ).map((group) => ({
+    items: group.entities.map((entity) => ({
+      label: localizeLabel(entity.label, i18n.language),
+      slug: entity.slug,
+      type: entity.type,
+    })),
+    label: group.label,
+  }))
+
+  return <AdminNavClient groups={groups} />
+}
+
+export default AdminNav
+
+export { AdminNavClient, type AdminNavGroup } from './NavClient'