Integrasi Komponen
Kontrak integrasi publik untuk Komponen Bersama, Pattern, Skin, dan Token Gaya Qokit.
Integrasi Komponen
Qokit menggunakan model "Kerangka Bersama + Resep Skin". Pihak integrasi eksternal bergantung pada kontrak semantik dan interaksi komponen, menyelesaikan adaptasi visual melalui Skin dan Token.
2026-10-20 · Tindakan mandiri pada kartu pilihan visual
Opsi EditorVisualChoiceGroup menerima accessory opsional untuk menu kartu atau editor nama yang mandiri. RadioGroup bersama menempatkannya di samping label asli agar pengelolaan kartu tidak mengaktifkan pilihan radionya. afterOptions menambahkan tindakan katalog terpisah, seperti membuat kartu, setelah opsi. Host tetap mengelola penyimpanan, izin, validasi, dan fokus setelah kartu diganti atau dihapus. Opsi tanpa aksesori mempertahankan struktur dan perilakunya.
2026-10-17 · Gerakan panel workbench bersama
EditorWorkbenchChrome merender jalur awal/akhir yang disuntikkan melalui BuilderWorkbenchFrame, kerangka panel yang sama yang digunakan oleh Creator dan pengeditan konten. Host menyediakan konten, visibilitas, dan preferensi lebar. Desktop melacak dan opacity/translasi panel berbagi --qk-sidebar-motion-duration dan --qk-sidebar-motion-easing; menggeser menonaktifkan transisi, dan gerakan berkurang beralih segera.
Panel yang dilipat tetap dimount untuk mempertahankan draf. Frame bersama segera menerapkan inert dan aria-hidden, sementara skin platform menyelesaikan keluar sebelum menyembunyikan visibilitas. Panel kompak mempertahankan geometri overlay mereka sepanjang keluar; host tidak boleh menambahkan hidden atau display: none ke shell panel. Panel peek eksplisit mempertahankan perilaku reveal interaktif mereka yang sudah ada. Pilihan header tetap tersedia di seluruh keadaan terbuka/tertutup; gunakan EditorPanelChoiceShortcuts.mobileMenu ketika tujuan telepon harus berbagi menu.
2026-10-17 · Default editor terukur
useWorkspaceResponsiveProfile menerima opsi onWidthChange(width), melaporkan lebar area kerja yang tersedia yang sama yang digunakan untuk profil responsif setelah padding inline dikurangkan. Gunakan callback stabil untuk menurunkan default proporsional tanpa menambahkan observer lain. useEditorLayout menerapkan sharedWidths.limits ke preferensi host serta penyimpanan lebar bersama; readEditorLayout menerima batas yang sama sebagai argumen opsional keempatnya. Pemanggil yang ada mempertahankan batas dan perilaku default mereka.
2026-09-30 · Aksesibilitas SelectionToolbar
SelectionToolbar.ariaLabel dapat memberi nama bilah alat sebagai wilayah. Jumlah tetap menjadi pesan status langsung. Host menyediakan label yang dilokalkan dan dapat memakai actionContent untuk menggabungkan komponen bersama EditorToolGroup dan ActionMenu; pemeriksaan izin dan penangan tindakan tetap menjadi tanggung jawab host.
2026-09-10 · Lencana identitas ruang kerja
ProjectSwitcherProject.badge menerima konten React opsional yang tidak interaktif. Lencana ditampilkan di samping nama setiap item, pada baris konteks saat ini yang tidak tercantum, dan di samping nama saat ini pada pemicu teks. Pemicu khusus ikon tetap ringkas; pemicu teks platform menyembunyikan lencana pada lebar ponsel agar nama ruang kerja tetap tersedia. Menu yang terbuka tetap menampilkan lencana. Host menyediakan data dengan cakupan yang benar, label yang dilokalkan, dan gaya presentasi; jika bidang ini dihilangkan, tampilan lama tetap dipertahankan.
2026-09-08 · EmptyState
EmptyState memusatkan icon dekoratif opsional, title, description opsional, dan action pada permukaan transparan. layout="section" ringkas secara bawaan; layout="workspace" menyediakan ruang lebih luas. Letakkan aksi langsung dalam action, gunakan fragment untuk beberapa tombol; wadah mengatur jarak dan label panjang. Judul berupa h2: gunakan slot title, bukan strong. Kelas akar tetap dipertahankan; skin.vars dan style didukung. Host mengelola teks lokal, izin, navigasi, dan pembuatan; hasil pencarian dan kesalahan tetap memiliki pesan dan aksi sendiri.
2026-09-08 · SidebarNavigation
SidebarNavigation memuat awal rute dengan asal yang sama setelah penunjuk berhenti 180 ms atau saat fokus keyboard. Navigasi tetap dan popup berbagi batas 8 tujuan per 30 detik. Pemuatan awal berhenti saat offline, tab tersembunyi, Save-Data atau 2G; unduhan, tautan nonaktif, jendela baru dan jangkar halaman yang sama dikecualikan. Navigasi dan perlindungan perubahan tetap berlaku.
2026-09-07 - AccountDropdown / SidebarProfile
AccountDropdown menerima opsi compact dan preferences: mode ringkas menyembunyikan pengenal dan riwayat pembuatan; secara default konten lama dipertahankan. Appearance dan Language menerima triggerRole="menuitem" dalam menu akun. Navigasi keyboard memulihkan fokus dan dialog bahasa bertingkat menangani Escape sendiri. SidebarNavigation.searchEnabled bernilai true secara default; gunakan false untuk navigasi singkat dan tetap. SidebarProfile dengan href tanpa menu membuka tujuan yang sama dalam mode terbuka dan ikon.
2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace
Formulir berbagi skala huruf dan membungkus teks panjang, mempertahankan bentuk pil dan warna merek. FormField menamai grup: controlId dan id di dalam menghubungkan label. SearchField mengembalikan fokus setelah dihapus. Segmented dan ControlMenu mendukung opsi nonaktif; item ActionMenu nonaktif tidak memiliki tautan. Tombol sibuk mempertahankan ukuran dan indikator. AdminEntityDialog memvalidasi kolom wajib, email, dan JSON, memfokuskan kesalahan, mencegah penyimpanan ganda, dan mempertahankan input saat gagal. EditorWorkspace menyediakan ref.focusControl(element) untuk menampilkan panel tersembunyi sebelum memfokuskan. Pengurangan gerak menonaktifkan transisi kontrol. WorkspaceDialog menggulir konten panjang dengan judul dan tindakan tetap terlihat; dialog seluler pendek mengikuti tinggi konten.
2026-09-07 · WorkspaceLocationSync / ProjectSwitcher
Setelah perpindahan rute selesai, WorkspaceLocationSync menutup pemilih ruang sementara agar alat tujuan langsung terlihat. Preferensi pencarian dan bagian tetap tersimpan. Nama cakupan dan konteks ditampilkan pada baris terpisah; nama panjang di header dipotong di dalam tombol.
2026-09-07 · Navigasi terpadu dan permukaan membulat Qokit
WorkspaceNavigationDock memakai kembali navigasi dan izin host melalui items, fallback, className, dan onClickCapture, tanpa memuat sesi tambahan. Preferensi terbuka, ikon, atau tersembunyi tetap dibagikan; hingga 860px menggunakan laci navigasi. PlatformHeader.leadingContext juga muncul di EditorHeader. Tombol kapsul dan permukaan membulat tetap dipertahankan, sedangkan bingkai berulang dihapus.
Di desktop, mengeklik menu menyembunyikan bilah sisi atau memulihkan mode tampilan terakhirnya. Menyeret menu atau tepi bilah sisi beralih antara tersembunyi, hanya ikon, dan diperluas. Tombol panah kiri/kanan mengikuti arah baca. Membatalkan seretan mempertahankan preferensi tersimpan; perangkat seluler tetap menggunakan panel navigasi.
Pasang WorkspaceLocationSync sekali di bawah Suspense dalam layout Next. useWorkspaceQueryState(key, defaultValue, validate) mengembalikan [value, setValue, ready]; useWorkspaceQueryRecord(key, defaults, validators) hanya memulihkan filter datar yang dinyatakan. Jangan menyimpan kredensial atau draf dalam URL. WorkspacePage memulihkan posisi gulir sesi dengan batas penyimpanan; area dalam menggunakan data-workspace-scroll-region dan WorkspaceScrollRestoration. Navigasi mundur/maju asli yang dapat dibatalkan memakai perlindungan keluar tanpa menambah riwayat. AdminEntityDialog mempertahankan input setelah kegagalan dan render ulang; versi dan hasil simpan tetap milik host.
Tipografi pengelolaan memakai peran tetap: judul halaman 20px/650, bagian 16px/600, teks dan navigasi 14px, label 13px, keterangan 12px. --qk-workspace-body-ink dan --qk-workspace-active-ink berasal dari warna yang ada.
Tombol utama berbentuk pil mempertahankan biru Logo #4695D8 dengan teks, ikon, dan indikator pemuatan putih pada kedua tema. Hover tetap sedikit lebih terang. Tombol sekunder dan bahaya mempertahankan warna semantiknya.
Dropdown dan pemilih ruang kerja memakai --menu-option-font-size (14px) serta --menu-option-font-weight (500), dengan tinggi baris 1.45; pilihan aktif memakai 600 dan metadata 12px/400. WorkspaceNavigationDock memuat tujuan dengan origin yang sama saat kursor diarahkan atau fokus keyboard, dengan deduplikasi terbatas. Perlindungan saat keluar dan rute host tetap berlaku.
2026-09-07 - ColumnLayout
ColumnLayout memenuhi jendela pengelolaan dengan navigasi tetap, area gulir terpisah, dan bilah alat halaman yang melekat di atas. WorkspacePage memakai bagian datar dan Token radius bersama. Pada 860px ke bawah, navigasi tetap berupa laci yang tidak interaktif saat ditutup. Properti dan perilaku bisnis tidak berubah. Hapus margin luar ganda dan batasi lebar baca di dalam formulir.
Titik Impor
import { Button, Card, Dialog, IconButton } from '@qokit/components/ui';
import { PlatformHeader, SiteFooter } from '@qokit/components/patterns';
import { platformButtonSkin } from '@qokit/components/skins/platform';
import { siteCardSkin } from '@qokit/components/skins/site';| Titik Impor | Kegunaan |
|---|---|
@qokit/components/ui | Komponen dasar seperti Button, Card, Dialog, Menu, Pill, dll. |
@qokit/components/patterns | Kombinasi seperti Header, Footer, Workspace, Tabel, Sumber Daya, dan Asisten AI |
@qokit/components/skins/platform | Resep visual Platform dan Workspace |
@qokit/components/skins/admin | Resep visual Admin |
@qokit/components/skins/site | Menghasilkan resep visual Situs |
Batas Tanggung Jawab Publik
PromptPanel menerima properti referenceReader opsional dan referenceCopy yang dilokalkan. Reader mengembalikan contentExcerpt yang diekstrak dan truncated tag melalui file(File, AbortSignal) dan website(url, AbortSignal) asinkron; autentikasi dan akses API ditangani oleh host. Manajemen komponen menangani pembacaan, pratinjau, percobaan ulang, dan penghapusan; jika URL valid tidak memiliki teks isyarat, referenceCopy.websitePrompt melengkapi permintaan, format yang salah menggunakan referenceCopy.errors.url dan memblokir pembacaan. Pengiriman saat URL belum dibaca atau sedang dibaca akan menunggu konten terbaru dan hanya mengirim satu kali; perubahan input atau kegagalan pembacaan membatalkan operasi yang tertunda, dan percobaan ulang tidak memulihkan pengiriman lama. File harus siap sebelum pengiriman. URL lengkap secara otomatis dibaca saat ditempelkan, kehilangan fokus, atau menekan Enter; URL awal juga dibaca dan menggunakan hasil yang sedang berjalan atau telah selesai; kegagalan menyediakan percobaan ulang yang jelas. Mengedit atau menghapus URL membatalkan pembacaan lama dan menghapus hasil. Jika reader tidak disediakan, pengiriman native dilanjutkan tanpa pemrosesan referensi asinkron.
Ingesti referensi ditambahkan pada September 2026 sebagai kemampuan komponen opsional dan kompatibel ke belakang.
Komponen Kerangka menjamin:
- Tag DOM dan semantik;
- Perilaku ARIA, keyboard, fokus, dan disabled;
- Status dan interaksi dasar;
- Class default yang stabil;
- Slot Skin bernama.
Skin dapat:
- Menambahkan class untuk slot seperti
root,header,body,item, danaction; - Meneruskan variabel CSS melalui
vars; - Menggunakan sakelar tone, layer, atau adaptasi visual yang telah dipublikasikan oleh komponen.
Skin tidak boleh meminta data, mengubah DOM, memegang aturan bisnis, atau melewati perilaku aksesibilitas.
Konten Elemen yang Dihasilkan
Blok kustom yang dihasilkan terus menggunakan elemen html-* terdaftar dalam Schema v2, tanpa HTML yang dapat dieksekusi atau tipe blok baru. Sejak September 2026, @qokit/site-schema menyediakan bindSiteModuleContent, updateSiteModuleBoundContent, dan forkSiteModuleContentBindings untuk pengikatan konten bahasa. Jalur konten disimpan dalam modul, salinan pengunjung disimpan dalam pemetaan konten bahasa, pembaruan mengikuti pembatalan dan transaksi penyimpanan; menyalin atau memindahkan elemen antar blok harus menurunkan pengikatan untuk menghindari perubahan sumber.
extensionRequirements opsional mencatat kebutuhan runtime yang belum terselesaikan, bukan sebagai daftar instalasi atau pemberian izin. createSiteExtensionHandoff mengekspor permintaan pengembangan v1 yang tidak dapat dieksekusi; kebutuhan ini harus diselesaikan atau dikecualikan secara eksplisit melalui tinjauan sebelum mempublikasikan situs yang dapat berjalan.
Kontrol Formulir
Formulir bersama menggunakan FormField untuk mengaitkan label, deskripsi, metadata wajib, kesalahan, dan ID kontrol. Kontrol teks menggunakan Input, konten multi-baris menggunakan Textarea, kontrol pilihan menggunakan Checkbox, RadioGroup, dan Switch; Select dan SearchField yang ada menggunakan kontrak ukuran dan status yang sama.
import { FormField, Input } from '@qokit/components/ui';
<FormField label="Site name" description="Up to 60 characters" error={errors.name} required>
<Input name="name" value={name} onChange={handleChange} />
</FormField>;FormField mengaitkan label, deskripsi, dan kesalahan ke kontrol anak tunggal melalui id, aria-describedby, aria-invalid, dan required. Jangan lagi membungkus kontrol bersama dengan <label> tambahan.
Input, Textarea, Select, dan SearchField mendukung tiga ukuran sm, md, dan lg, sesuai dengan 40px, 44px, dan 48px. Kontrol satu baris secara default menggunakan bentuk pill; Textarea selalu menggunakan sudut bulat multi-baris bersama. Setiap status interaksi dan kesalahan berasal dari Token bersama.
Selama migrasi, kontrak .qk-field lama masih dapat digunakan; integrasi baru harus menggunakan komponen bersama dan slot Skin bernama.
Pemilihan Daftar
Sejak September 2026, daftar dapat menggunakan useWorkspaceSelectionMode({ enabled, resetKey, onClear }) bersama dengan WorkspaceFilterToolbar.selection. Hook ini awalnya tidak aktif, mereset saat cakupan atau izin berubah, dan membedakan antara mengosongkan ID yang dipilih dan keluar dari mode batch; kunci cakupan harus mencakup koleksi, bahasa, paginasi, dan filter.
Hanya kirimkan WorkspaceDataTable.selection saat mode batch aktif, grid dan kontrol centang seluler menggunakan mode yang sama. Toolbar bertanggung jawab atas operasi pemilihan umum, pengguna menyediakan salinan terlokalisasi, ID opsional, dan operasi domain yang diperiksa izinnya. actionContent opsional dapat membawa semantik ARIA tambahan, tetapi tidak menggantikan kontrol umum atau konfirmasi. Daftar hanya-baca tidak menampilkan mode batch, pemilih file dan tinjauan proposal mempertahankan semantik mereka sendiri.
Kemampuan baru ini opsional dan kompatibel ke belakang; pemilihan tabel tetap dikendalikan secara eksplisit oleh pengguna.
Kartu Metrik
Referensi API tambahan (bahasa Inggris; terjemahan menyusul) · 2026-10
DataCard provides a title and optional headerAction, body content with an optional emphasized value, and optional footerText and footerAction. Pass other body content as children. density="default" has a 144px minimum height and 20px padding; density="compact" has a 112px minimum height and 16px padding. Cards grow when content needs more room. variant selects the shared Card surface: surface, muted, or state. Choose these shared sizes instead of overriding height, padding, or value typography in route CSS.
Use shared UI controls in action slots. Keep the card root non-interactive when it has actions; a whole-card action cannot contain nested buttons or links. MetricCard composes the same skeleton and retains label, detail, semantic tone, and optional visuals.
import { DataCard, MetricCard } from '@qokit/components/patterns';
import { Button } from '@qokit/components/ui';
<DataCard
title="Published"
value={24}
headerAction={<Button size="sm" variant="ghost">View</Button>}
footerText="Up 3 from last week"
footerAction={<Button size="sm" variant="secondary">Details</Button>}
density="compact"
/>;
<MetricCard density="compact" label="Published" value={24} tone="success" />;Header dan Footer Platform
Logo menampilkan gambar statis secara bawaan. motion="breathe" mempertahankan ukuran saat tersembunyi lalu menampilkan logo sekali dengan animasi napas 4,8 detik setelah halaman dimuat dan setidaknya separuh logo terlihat. Header dan footer tidak menambah waktu tunggu. motionVisibilityDelayMs dapat menambah durasi keterlihatan terus-menerus, dengan nilai bawaan nol. motionOnceKey berbagi catatan pemutaran saat dipasang ulang dalam dokumen yang sama; header dan footer memakai kunci terpisah. Navigasi, perubahan tema, dan menggulir kembali tidak memutar ulang; pemuatan ulang penuh meresetnya. Pengurangan gerakan, JavaScript nonaktif, atau pengamatan visibilitas yang tidak tersedia menampilkan logo statis. motion="reveal" tetap menjadi alias.
PlatformHeader.autoHideOnScroll bernilai false secara bawaan; PublicPlatformHeader mengaktifkannya. Header menghilang saat menggulir ke bawah dan kembali saat ke atas atau dekat bagian atas. Menu header terbuka dan fokus di dalam header membuatnya tetap terlihat. Header ruang kerja dan editor tetap diam.
PlatformHeader adalah kerangka Header tanpa status bisnis. PublicPlatformHeader menggabungkan entri merek, navigasi publik, bahasa, tema, login, "Coba Sekarang", dan menu mobile di atasnya; status anonim platform dan situs dokumentasi langsung berbagi kombinasi ini.
Navigasi publik dihasilkan secara terpusat melalui buildPublicHeaderNavItems(copy, links) sebagai "Sumber Daya / Harga / Berita". Pihak integrasi hanya perlu memproses URL internal situs, situs dokumentasi, dan platform yang sedang diterapkan, tidak boleh mendefinisikan ulang urutan menu atau teks. Header platform setelah login juga menggunakan fungsi generasi yang sama.
<PublicPlatformHeader
copy={headerCopy}
links={{
brandHref: '/',
resourceCenterHref: '/resources',
userManualHref: 'https://docs.qokit.com/manual',
developerDocsHref: 'https://docs.qokit.com/developers',
changelogHref: 'https://docs.qokit.com/changelog',
pricingHref: '/pricing',
newsHref: '/news',
loginHref: '/login',
studioHref: '/studio'
}}
/>navItems di lapisan bawah masih mendukung link, scroll, dan menu. menu mendukung penutupan melalui klik, keyboard, Escape, dan klik di luar pada desktop, sementara pada mobile dikembangkan menjadi kelompok tautan oleh MobileHeaderMenu.
SiteFooter adalah kerangka Footer; platform dan situs dokumentasi menggunakan PublicPlatformFooter untuk menggabungkan Shell luar, entri merek, tautan, kontrol tema, dan bahasa secara seragam. Integrasi lintas domain mengubah tautan relatif platform menjadi alamat absolut melalui resolveCompanyHref.
<PublicPlatformFooter
brandHref="https://qokit.com"
copy={footerCopy}
resolveCompanyHref={(href) => `https://qokit.com${href}`}
/>Aplikasi bisnis tidak boleh menyalin DOM Header, Footer, atau array navigasi publik; jika memerlukan tampilan visual yang berbeda, gunakan PlatformHeaderSkin, SiteFooterSkin, atau Skin platform yang sesuai.
Strategi Kompatibilitas
- Penambahan properti opsional dan slot Skin merupakan perubahan yang kompatibel ke belakang;
- Penghapusan properti, modifikasi semantik default, atau perubahan perilaku DOM/keyboard merupakan perubahan breaking;
- Perubahan breaking harus dicantumkan dalam Changelog dan menyertakan contoh migrasi;
- Jangan bergantung pada class internal, direktori, atau struktur rute yang belum dipublikasikan;
- Jika lebih dari satu titik integrasi memerlukan penimpaan yang sama, hal tersebut harus ditingkatkan menjadi Skin atau Token publik.
Penyuntingan layar penuh
EditorWorkspace memadukan dialog layar penuh, pengelolaan fokus, dan panel responsif. dirty meminta konfirmasi sebelum membuang perubahan, busy mencegah penutupan saat menyimpan, dan onSave menangani Ctrl/Cmd+S. Aplikasi induk mengelola izin, data, penyimpanan, dan penerbitan.
view / onViewChange beralih antara edit, focus, dan preview tanpa mengganti editor. preview menyediakan pratinjau; previewPanel memakai panel yang ada. layout mendukung writing, structure, dan canvas. storageKey mengingat lebar dan panel yang dilipat, bukan dokumen.
onSaveAndClose mengembalikan true setelah penyimpanan dikonfirmasi, false saat gagal, handled jika aplikasi sudah berpindah, atau pending jika validasi membutuhkan keputusan. Kegagalan membuat editor tetap terbuka. Gunakan closeBehavior="collapse" hanya jika aplikasi mempertahankan draf. EditorSaveStatus menampilkan status terkonfirmasi. EditorViewControls, EditorLeaveDialog, dan useEditorLayout juga dapat digabungkan secara terpisah.
Perubahan keyboard: Segmented memiliki satu perhentian Tab dan memakai panah / Home / End. Dialog menghormati Escape yang ditangani lapisan anak; editor lalu keluar dari fokus atau pratinjau sebelum ditutup. LivePreviewToolbar.exitControl menerima kontrol tampilan bersama. Penyimpanan, penerbitan, dan izin tetap dikelola aplikasi.
import { EditorWorkspace } from '@qokit/components/patterns';
<EditorWorkspace
open={open}
title={title}
dirty={dirty}
busy={saving}
onClose={closeEditor}
onSave={saveDraft}
onSaveAndClose={saveDraft}
saveState={saveState}
layout="writing"
storageKey="article"
preview={preview}
navigation={structure}
inspector={properties}
actions={saveActions}
>
{editor}
</EditorWorkspace>SidebarToggleSlot
SidebarToggleSlot menempatkan tombol bilah samping di header ruang kerja. Gunakan satu slot dengan satu bilah samping kiri. SidebarNavigation tetap mengelola status, pintasan, dan panel seluler; tanpa slot, kontrol tetap di posisi semula. Tombol di header juga menutup panel seluler; setelah ditutup, fokus kembali ke tombol yang sama.
EditorHeader
EditorHeader mempertahankan logo, akun, dan menu global aplikasi dalam editor aktif. startControl dan endControl mengontrol panel samping, center memuat perintah tampilan, dan actions memuat tindakan simpan. PlatformHeader.editorActions menggunakan kembali navigasi responsif, bahasa, dan tema. onNavigate harus menangani perubahan yang belum disimpan sebelum menjalankan callback. Pada layar sempit, header memakai dua baris; submenu menangani Escape terlebih dahulu.
WorkspaceHeaderPortal.startControl dan endControl menempatkan toggle panel halaman terkelola di slot yang sesuai dari host. Host mengekspos opsi startTarget dan endTarget di samping judul, status, dan tindakan. Perpustakaan Files dan ruang kerja aset tunggal menggunakan workAreaControls; pratinjau aset mempertahankan header penuh sehingga identitas, tindakan kembali, dan tujuan panel tetap tersedia. ProjectWorkspace memiliki pilihan navigasi/konversasi kiri bersama untuk Konten dan Files. Files mendaftarkan dimensi panel sumber daya yang diingat melalui useProjectResourcePanel, memortal navigasi melalui ProjectContentTools, dan hanya menyediakan kontrol inspector kanan melalui ProjectToolbar.endControl. Percakapan menggunakan jalur kiri yang sama dan komposer tertanam di seluruh area proyek; tugas sumber daya kompak, percakapan, dan inspector bersifat saling eksklusif.
EditorNavigationMenu
EditorNavigationMenu menggunakan seluruh SidebarNavigation aplikasi dalam panel lapisan dengan izin dan konteks proyek tanpa menggeser kanvas. Bahasa dan tema berada di bawah; submenu menangani Escape terlebih dahulu. Fokus dan layar penuh browser berdiri sendiri. Navigasi menunggu penyimpanan yang berlangsung dan melindungi draf.
WorkspaceNavigationMenu / WorkspacePageHeader
Navigasi global memakai Command+\ di Mac atau Control+\ di Windows/Linux, termasuk secara mandiri di Creator. T dan Shift+T tetap mengatur tata letak editor. Target yang dapat diedit, komposisi teks, pengulangan, dan kejadian yang sudah ditangani diabaikan. Petunjuk tombol dan aria-keyshortcuts menampilkan kombinasinya; navigasi global tidak lagi memakai T tunggal.
Ruang kerja setelah masuk memakai PlatformHeader.workspaceActions untuk berbagi area akun dan navigasi pada setiap lebar. WorkspacePageHeader menyatukan judul dan tindakan. WorkspaceNavigationMenu menampilkan bilah samping saat ini beserta izin dan konteksnya; EditorNavigationMenu tetap menjadi alias yang kompatibel. Studio mempertahankan bilah alatnya. Header publik mempertahankan tampilannya.
WorkspaceNavigationGuard melindungi navigasi global melalui dirty, busy, error, dan onSave opsional. Pengguna hanya boleh keluar setelah penyimpanan terkonfirmasi mengembalikan true; kegagalan mempertahankan draf. Language.onBeforeChange(apply) memungkinkan perlindungan yang sama sebelum mengganti bahasa. Nonaktifkan bidang formulir saat menyimpan.
Navigasi desktop mempertahankan mode diperluas dan ikon serta menambahkan sembunyi otomatis. Bilah sisi dan panel berbagi pencarian dan status grup. Penunjuk presisi di tepi membuka pratinjau setelah 300ms dan menutupnya 320ms setelah meninggalkan tepi; klik mempertahankannya terbuka. Kontrol sentuh dan papan ketik tetap tersedia. Dialog memakai modal={true} dan autoFocus={true} secara bawaan; pratinjau mengatur keduanya ke false agar fokus masukan dan gulir tetap terjaga.
EditorViewControls
Satu tombol beralih dua arah: saat mengedit menampilkan Fokus, saat fokus menampilkan Edit. Klik atau tekan T; E langsung kembali ke edit. Pada header sempit, tombol tetap terlihat; pratinjau, layar penuh dan tindakan tambahan berada di Lainnya.
EditorViewControls memisahkan Edit/Fokus dari layar penuh bawaan. Pratinjau menjadi sakelar terpisah dan kembali ke mode sebelumnya; useEditorWorkMode mempertahankan mode tersebut untuk tindakan keluar khusus. Nilai edit/focus/preview tetap didukung. Pratinjau kini memakai button dengan aria-pressed, bukan radio dalam grup mode. Layar penuh memerlukan klik, mencakup navigasi dan dialog pada akar aplikasi, dan disembunyikan jika tidak didukung.
Language / Appearance
Language dan Appearance variant="menu" mendukung layout="row" untuk menampilkan label, nilai saat ini, dan panah. Tata letak ringkas bawaan dan perlindungan perubahan bahasa tetap berlaku. SiteHeaderCopy.helpResources dan contactSupport dapat memberi nama tautan bantuan ruang kerja.
requestWorkspaceNavigation
Halaman dengan tombol bilah samping tidak menampilkan tombol menu tambahan di header, termasuk saat diciutkan dan pada tata letak seluler. Editor dan halaman tanpa bilah samping tetap menampilkannya. Impor requestWorkspaceNavigation(returnFocusTarget?) dan useWorkspaceNavigationState() dari @qokit/components/patterns/WorkspaceNavigation: permintaan mengalihkan panel terdaftar dan mengembalikan false jika tidak tersedia. Elemen opsional menerima fokus saat ditutup. Periksa .available sebelum menampilkan akses lain. Gunakan tombol yang ada atau API ini, bukan posisi DOM tombol yang dihapus.
WorkspacePanelReveal
Navigasi global memakai ikon menu, alat memakai ikon panel berarah. useWorkspacePanelReveal({ temporary: true }) membuka alat sementara dengan klik atau keyboard dalam Fokus. toggle(trigger?) dan close(true) mempertahankan tata letak serta mode dan mengembalikan fokus saat ditutup. Tepi layar membuka navigasi global; alat merespons dekat tombolnya. Pratinjau menyembunyikan tombol panel dan menyediakan tindakan eksplisit untuk kembali ke mode penyuntingan sebelumnya.
EditorViewControls / Mode tampilan
EDITOR_VIEW_SHORTCUTS → Tooltip + aria-keyshortcuts
EditorHeader juga mengelola EDITOR_TOOLBAR_SHORTCUTS: Command/Control+S menjalankan EditorSaveButton yang terlihat, Shift+P membuka EditorStatusAction shortcut="publish", dan Shift+M membuka menu alat. Perintah memakai kontrol aktif yang sama seperti klik; penerbitan tetap memerlukan tindakan tegas di panel. Hanya header aktif yang terlihat yang merespons. Submenu, dialog, komposisi teks, dan kejadian berulang memblokir pintasan; kolom masukan hanya mengizinkan simpan. Petunjuk dan aria-keyshortcuts berbagi definisi. toolsControl khusus menetapkan aria-keyshortcuts={EDITOR_TOOLBAR_SHORTCUTS.tools.aria} pada pemicu. ActionMenu.triggerKeyShortcuts menambahkan atribut dan petunjuk tanpa mendaftarkan perintah global.
Panel memakai Shift+A (tambah), Shift+L (halaman/lapisan), Shift+K (percakapan), Shift+C (konten), Shift+D (desain), Shift+G (gaya global). CMS menambahkan Shift+S (pengaturan), Shift+E (SEO), Shift+H (riwayat) jika tersedia. Metadata shortcut di EditorChoiceControl, EditorViewTabs, dan ActionMenu berbagi petunjuk. EditorPanelChoiceShortcuts dan EditorViewControls.compactActions mempertahankan tindakan saat dilipat ke menu, termasuk di ponsel. EditorPanelShortcuts.commands mendaftarkan tindakan yang ada tanpa menggandakan kontrol. Batas tersembunyi, inert, nonaktif, pratinjau, dan overlay tetap berlaku. Bilah ponsel nonmodal di ruang kerja yang sama mengizinkan pergantian panel; menu dan dialog modal memblokir pintasan. Tombol tanpa pengubah tetap berperilaku seperti sebelumnya.
| Mode tampilan | |
|---|---|
E | Edit |
T | Edit ↔ Fokus |
V | Pratinjau / Kembali menyunting |
F | Buka layar penuh / Keluar layar penuh |
Hanya editor aktif yang merespons. Pengetikan, komposisi IME, tombol yang ditahan, serta dialog atau menu turunan yang terbuka tidak mengubah mode.
PlatformHeader.workspaceNavigation
PlatformHeader.workspaceNavigation menempatkan navigasi global sebelum logo; workspaceActions dan editorActions tetap memuat tindakan akun. Ruang kerja memakai tombol bilah samping yang ada, dan editor menempatkan tombol panel kanan sebelum avatar. Pada layar sempit, navigasi, merek, judul, dan avatar berada di atas alat penyuntingan dan Simpan. Urutan DOM mengikuti tata letak; efek kaca buram tanpa batas tetap dipertahankan.
2026-09-06 - EditorHeader.preview / EditorViewControls.returnView
EditorHeader.preview hanya menampilkan center sebagai bilah pratinjau ringkas tanpa garis tepi; logo, akun, simpan, dan panel tetap terpasang tetapi tersembunyi. Dengan LivePreviewToolbar terpisah, sembunyikan header editor dan gunakan EditorViewControls.returnView (edit atau focus) untuk kembali ke mode sebelumnya. Pertahankan akses kembali dan layar penuh independen; header situs tetap terlihat.
2026-09-06 · Builder / CMS
Builder dan CMS berbagi BuilderWorkspace, EditorCatalog, dan EditorComponentSettings untuk panel, ilustrasi penyisipan, dan pengaturan tampilan. Preset menerapkan pengaturan terkait sekaligus tanpa mengubah konten; penyimpanan dan urungkan ditangani aplikasi masing-masing. Kontrol mengikuti tema platform, sedangkan konten mengikuti tema situs.
Footer yang dirender di server · 2026-09-07
SiteFooterLayout menerima locale eksplisit dan copy dalam satu bahasa. Komponen server merender struktur footer bersama; kontrol tema dan bahasa serta dialog QR tetap berupa komponen klien. Antarmuka SiteFooter dan PublicPlatformFooter yang ada tetap didukung.
import { SiteFooterLayout } from '@qokit/components/patterns/SiteFooter';
<div className="qk-platform-footer-shell">
<SiteFooterLayout locale={locale} copy={footerCopy} />
</div>Siapkan tautan lintas domain dalam copy.companyLinks di server. Gunakan controls untuk menyesuaikan slot kontrol interaktif.
EditorHeader.titleControl / FloatingAssistant.presentation
EditorHeader.titleControl dan EditorWorkspace.titleControl dapat mengganti judul dengan menu proyek bersama. Pertahankan title yang deskriptif dan perlindungan perubahan yang belum disimpan saat navigasi. FloatingAssistant.presentation="embedded" menampilkan area bernama di panel host tanpa tombol mengambang atau latar penutup; default tetap floating. Host mengatur posisi dan visibilitas; asisten mengelola status percakapan dan izin.
2026-09-07 · WorkspaceAssembly
WorkspaceAssembly menandai kartu keluar dan bagian masuk tanpa menambah kotak tata letak. Untuk kontrak anak langsung, pasang workspaceAssemblyAttributes(part, index, phase) pada DOM yang ada. EditorHeader.assemble dan BuilderWorkspacePanels.assemble menyediakan penanda editor.
Panggil await startWorkspaceAssembly(navigate, destinationPathname) hanya setelah pembuatan berhasil: ambil cuplikan bagian terlihat, navigasikan sekali, lalu susun tujuan atau kerangka pemuatannya dalam maksimal 720 ms. Tujuan memerlukan penanda masuk canvas; useWorkspaceAssemblyPending() mempertahankan layar pemuatan hingga cuplikan selesai, sambil memuat data dan kode lebih awal. Pengurangan gerakan atau peramban tanpa dukungan memakai navigasi langsung. Transisi lambat atau terputus melepaskan cuplikan dan melanjutkan navigasi. Penanda tidak menganimasikan penyuntingan, pemuatan ulang, atau riwayat. Pola membersihkan gaya sementara; host menangani galat pembuatan, idempotensi, dan pemuatan.
2026-09 · Ruang kerja administrasi
WorkspacePage dan WorkspaceLayout menerima variant: overview, list, detail, settings, atau editor. WorkspaceFormFooter menata actions, message, tone, dan busy dari aplikasi induk; penyimpanan tetap tanggung jawab aplikasi.
Tabel sempit (WorkspaceDataTable, AdminDataTable) menampilkan rekaman berlabel dengan pilihan, kepala tabel khusus, dan tindakan. Gunakan mobileLayout="scroll" untuk matriks perbandingan. WorkspaceFilterToolbar menempatkan pencarian dan filter sebelum urutan dan tampilan. Bilah samping memakai h2; halaman memakai h1.
2026-09-08 · Task focus
useSidebarTaskFocus(active) menyembunyikan navigasi sementara selama tugas yang memerlukan fokus. Saat keluar, tampilan sebelumnya dipulihkan kecuali pengguna mengubah mode secara eksplisit. Penyembunyian otomatis tidak menimpa preferensi tersimpan.
Referensi API tambahan (bahasa Inggris; terjemahan menyusul)
EditorHeader.contextMode="title" displays the editor's own titleControl instead of the host workspace picker. The default "host" behavior is unchanged; navigation, brand, account controls and leave guards retain their existing ownership. Hosts supply responsive placement for their title control.
EditorViewControls.focusInMenu shows a labelled preview action and moves focus mode into the shared menu. Its default remains false; view shortcuts and returning from preview keep the existing behavior.
EditorViewControls.toolsControl replaces the fallback menu with a host-owned tools control. Hosts retain its accessible trigger, menu state and actions; view buttons and keyboard shortcuts keep their existing behavior. Creator uses this slot for its complete editor tools menu beside Add, Layers and Preview.
EditorViewControls.responsiveLabels displays text beside focus and preview icons above 720px, reserving space for both focus labels. At phone widths the labels are hidden while accessible names and tooltips remain. EditorSaveButton.showStatusLabel displays saved/saving status or a retry action when state is provided; it reserves label space across states. Both options default to false.
ResizablePanels.middlePanelProps forwards section attributes such as inert to the middle panel, matching the existing side-panel attribute slots. An editor can keep its canvas mounted while preventing keyboard and pointer interaction when a compact conversation view covers it. Hosts still control panel visibility and restore focus when switching views; the prop does not unmount content.
ProjectSwitcher.currentWorkspaceId optionally marks the parent workspace independently of currentProjectId; only the current location receives the selected surface. IDs must match the supplied projects items. onActionSelect(action, event) lets the host guard shortcut navigation after the menu closes; omitted callbacks retain normal link behavior. Creation shortcuts use ordinary menu surfaces. Optional SiteHeaderCopy.projectSwitcherCreate and projectSwitcherWebsites label creation and the current workspace's website group without renaming the Creator product.
AccountDropdown.usageSummary is an optional slot below the account identity for host-supplied credit balances, plan usage and links to details. It also accepts ({ environmentInfo }) => ReactNode to place the shared ID disclosure and copy controls in the summary without duplicating them below. Links use role="menuitem" and retain menu keyboard behavior and navigation guards. The platform header shows credits and plan usage in two columns, with ID details expanding below; the sidebar account retains appearance and language. Failed reads never appear as zero, and reopening the menu refreshes the data.
PublicPlatformHeader.workspaceAction optionally supplies { href, label } for an authenticated visitor's return link. It replaces the desktop login icon and stays visible beside the mobile menu; the mobile menu then omits anonymous account actions. Session detection belongs to the host. The platform home uses a lightweight local session check, updates after focus/storage changes, and keeps ?view=public on its brand link so explicit website visits survive refresh.
contextAfter places editor-specific scope controls after the host project picker, preserving their DOM and keyboard order. The host retains project navigation and leave guards; the editor owns page and content-language selection. Hosts may adapt the responsive layout to put this context on its own row.
WorkspaceNavigationMenu.footerLinks supplies direct icon links alongside the sidebar display control. footerMenus accepts ordered WorkspaceNavigationFooterMenu entries, each with a label, icon and link items (with optional separatorBefore). The platform uses one menu for Website Home, Pricing, Templates and News, and a book-icon Help & Support menu for the user manual and contact support. The single footerMenu prop remains supported when footerMenus is omitted. Desktop menus open upward with ActionMenu placement="top" portal; mobile uses bottom sheets. The controls form one row when expanded and a column in icon mode; on mobile the sidebar control closes the navigation drawer. Each icon retains an accessible name and tooltip. profile adds the user name, plan and account menu without duplicating an existing sidebar account. Omitting footer links and menus retains the existing preferences and fullscreen actions.
Set a footer menu item's newTab to open a reference destination with target="_blank" and rel="noopener noreferrer". The skeleton adds a trailing arrow and localized screen-reader notice; other items keep current-page navigation. Website Home, Pricing, Templates, News, the manual and contact support use new tabs so the workspace stays open. An explicit public-home visit preserves ?view=public to bypass the signed-in landing redirect, including after refresh.
Editor tool palettes can use Dialog with keepMounted to preserve search and form state while closed. Closed dialogs immediately become inert, hidden from assistive technology, and leave the focus stack, including during a visual exit transition; the default still unmounts their content. Pair nonmodal palettes with DialogPanel to reuse the global overlay surface. Toolbar accepts a DOM ref for bounded positioning while retaining its shared arrow-key navigation.
useFloatingSurface from @qokit/components/patterns/FloatingTools supports defaultHeight: 'auto' for content-sized palettes. Keep the host body shrinkable with internal scrolling; the hook caps the surface to its workspace bounds and observes size changes. Moving an automatic palette stores its position without freezing the measured height. Resizing explicitly stores a fixed height, including across reloads; reset() or Home on a movement/resize handle restores automatic sizing. Numeric defaultHeight retains the existing fixed-height behavior.
FloatingToolPanel composes the shared DialogPanel, TreeToggle, pin button, tooltip and close button. Place it inside a nonmodal Dialog; the host controls pinned, collapsed, their callbacks and document operations. Pinning keeps the palette open after an operation; it does not lock its position. The title and header whitespace accept useFloatingSurface().dragHandle, while buttons, menus and inputs never initiate dragging or folding. Double-click the title or whitespace to fold; the explicit fold button supports keyboard and touch. Folding hides the body without unmounting it, preserving searches and tree state. Pass the same collapsed value to useFloatingSurface to retain the expanded height while moving the folded header. Optional actions and skin slots reuse the same structure; styles stay in the shared stylesheet.
Optional FloatingToolPanel.viewKey adds a short opacity transition when the active tool changes, without replacing its body instance. Ordinary parameter updates do not animate. Opening, closing, unfolding and pin feedback share the existing motion Tokens and respect reduced motion. Dragging stays direct; useFloatingSurface coalesces pointer movement to one geometry update per animation frame and saves the final position on release. Browsers without discrete display transitions close immediately.
Unified editors pass focus={false} to omit the separate Focus control. primaryActions accepts shared tool buttons before Preview; onTogglePanels handles T, and onToggleAllPanels handles Shift+T. Creator uses T to cycle from visible panels to floating launchers to fully hidden and back to the last visible layout; ordinary launcher clicks still open their panel. Shift+T directly hides everything and restores the exact preceding state. Both sidebar shortcuts are inactive in Preview and respect editable targets and active overlays. Existing hosts keep Edit/Focus behavior by default.
useWorkspacePanelVisibility().togglePanels hides the visible editor panels or restores their preceding layout. Desktop and compact layouts are remembered independently, and forceCollapsed (for example during Preview) does not overwrite that memory. The host owns global navigation visibility and any edge launchers.
For floating editor panels, pass skin: platformWorkspacePanelRevealSkin from @qokit/components/skins/platform and spread the returned panelProps onto the existing panel. The skin applies only while revealed; the docked panel and its mounted content remain intact. ResizablePanels merges startPanelProps, middlePanelProps, and endPanelProps class names with its own skin slots. Pair focus controls with Toolbar and platformFloatingToolbarSkin for shared keyboard navigation and compact spacing. Both skins share the global DialogPanel surface (background, shadow and blur); panel corners use the card radius and toolbar corners use the control radius. Hosts own positioning and available space, not a separate overlay palette.
useWorkspacePanelEdgeDrag is an opt-in hook for an existing workspace root ref. Mark its focusable borders with data-workspace-panel-edge="start" or "end"; ResizablePanels supplies these attributes on its own separators. The host provides each side's mode (expanded, icons, hidden), saved width and bounds through getState, applies onChange, and returns a rollback callback from onBegin. onResizing should suspend layout transitions; onFinish restores focus to the resulting control, and onReset restores the host's default width. One captured mouse or touch gesture crosses all three states, with RTL direction handling and cancellation on Escape, pointer cancellation or window changes. Arrow keys resize or step states, Shift increases the step, Home/double-click resets, and End expands to the allowed maximum. This hook adds no visual controls or stored content. Hosts can pair hidden borders with useWorkspacePanelReveal for temporary shortcut access while retaining their normal click actions; hosts without the hook keep existing resizer behavior.
FloatingAssistant.headerActionsTarget optionally accepts an HTMLElement in the host heading. The assistant portals its existing conversation history and new-conversation controls into that element and omits its internal header. Without a target, the original header remains. The host owns the heading and placement; the assistant retains action handlers, accessibility labels and conversation state. The Web adapter forwards this slot.
FeatureHint is exported from @qokit/components/patterns/FeatureHint. Use it for contextual first-use guidance attached to a real control. Provide a versioned id, a stable user scopeKey, an anchor: HTMLElement, an active eligibility signal, localized title, description, dismissLabel, and action: { label, onClick }. Set completed when the user discovers the capability independently. A null scope or unavailable anchor suppresses the hint.
The shared component allows one hint at a time, waits briefly for a visible target, follows scrolling and resizing, supports RTL, and keeps content inside the viewport. It does not add a backdrop, steal focus, or perform the action automatically. Escape, the close button, or clicking elsewhere dismisses it; Tab from the target reaches the action. The target receives a temporary highlight and accessible description. Seen hints are remembered in the current browser per scope and version, with an in-memory fallback if storage is unavailable; this is not cross-device progress. Hosts own permissions, review-state suppression and the actual action. skin, className and style adapt presentation.
AssistantContextCard is exported from @qokit/components/patterns/FloatingAssistant. Place it in composerContext to summarize the current editing target. Its typed contract includes title, description, scope, preview, parameters: { id, label, value }[], optional controls, status and notice, plus actions, onLocate and clearAction. Pass localized labels and formatted values, including units, from the host.
The card renders a read-only definition list, an optional controls slot for a few common adjustments, and a live status region. Reuse the host’s existing editing controls and commands in this slot; keep complete settings behind an explicit action that opens the existing inspector. Hosts retain ownership of selection, permissions, save, undo and AI requests. Conversation, canvas editing and inspector editing can operate together, with independent panel visibility. Selecting an object updates the card and an already open inspector without opening a closed panel or moving focus. Removing a conversation reference preserves canvas selection and direct editing; keep the conversation entry independent of this card and of floating-tool visibility. Changing the target or a parameter updates this live card without appending chat messages. Both draft and project conversations can use the same component. className, style and AssistantContextCardSkin support visual adaptation; styles are loaded with the component.
FloatingAssistantPanel.composerContext 接收输入框上方的实时上下文区域。提供此插槽时,顶部旧的 activeContext 摘要隐藏,activeContext.promptPlaceholder 仍供输入框使用。实时参数属于当前编辑状态,不应追加到历史消息列表;Web 适配器透传此插槽。
Hosts can set hoverReveal={false} to disable navigation previews from the trigger and window edge while retaining explicit controls and drag resizing; the default remains true.
WorkspaceNavigationDock prefetches same-origin destinations on mouse hover or keyboard focus, with bounded deduplication.
Adaptor Web juga meneruskan FloatingAssistantPanel.composerAttachments. Slot ini menampilkan lampiran yang dikelola host di dalam formulir pesan, sebelum kolom teks. Host mengatur posisi dan pengiriman: menjatuhkan hanya menyiapkan lampiran, keberhasilan menghapus hanya lampiran yang dikirim, dan kegagalan mempertahankannya untuk dicoba lagi.
Percakapan bersama (referensi Inggris; terjemahan menyusul)
@qokit/components/patterns/Conversation exports ConversationPanel, ConversationMessages, ConversationMessage, ConversationSuggestions and ConversationComposer. Creator generation, draft refinement and the embedded project assistant use these structures and the same token-based stylesheet. Hosts own requests, history, permissions, selected objects and review/apply actions.
ConversationFeedback menyusun InlineNotice untuk menampilkan status tugas, kegagalan, penanganan cadangan, dan konfirmasi penyimpanan secara ringkas dalam percakapan. Berikan title yang dilokalkan serta description, tone, dan action jika diperlukan. Kedua baris memakai ukuran teks keterangan, jarak rapat, dan permukaan transparan; warna menonjolkan status sementara teks pendukung tetap redup. Nilai bawaan role="status" dan aria-atomic="true" membacakan seluruh pembaruan sekaligus; gunakan role="alert" untuk kegagalan yang memerlukan tindakan. Teks yang ditulis asisten tetap berada di ConversationText.
Place the scrollable ConversationMessages and the fixed ConversationComposer directly inside the panel. Supply a localized label for the messages region and inputProps for the controlled textarea. The composer accepts attachments, notice and actions slots, plus formProps and formRef; it creates the form, so do not nest it in another form. Enter inserts a newline; Cmd/Ctrl+Enter requests submission with composition and disabled/busy guards. Preserve user input while a request is running when the host supports it.
PromptPanel.presentation="conversation" reuses the composer while retaining reference reading, upload/menu controls and serialized form fields. The default "prompt" preserves the landing-page prompt behavior. FloatingAssistant.presentation="embedded" uses the shared panel, messages, suggestions and composer; floating assistants retain their compact presentation.
Referensi API tambahan (bahasa Inggris; terjemahan menyusul) · 2026-10
2026-10-10 · Pagination dot display
Pagination from @qokit/components/ui accepts pageDisplay="dots" for compact visual choosers. Combine it with layout="centered" for centered arrows and 6px indicators with 32px-wide click targets. Dot colors, hover and keyboard focus use shared theme Tokens; PaginationSkin.dot adapts the indicator slot. Hosts supply currentPage, totalPages, onPageChange and localized navigation labels. pageLabel names each dot; its fallback combines ariaLabel with the page and total. Browsing pages only invokes the host callback. The default "numbers" display retains numeric pagination and formatPageNumber.
2026-10-10 · ActionMenu search header
ActionMenu.dropdownHeader accepts host-owned content before the actions in both dropdown and mobile sheet presentations. onOpenChange reports opening and dismissal so hosts can reset transient search state. Search hosts supply localized copy, filtering and initial input focus; ArrowDown from the input should focus the first enabled result, then the shared menu handles result navigation, selection and Escape.
2026-10-09 · Inline ColorPicker
ColorPicker from @qokit/components/ui/ColorPicker accepts presentation="inline" to expand its editor beneath the field trigger. It renders a named group in the document flow, keeps the surrounding workspace available, and retains palette, HEX, opacity, gradient and reset capabilities. Hosts should reserve a full row for the field. Changes to the controlled value, including undo and reset, update the open inline editor; leaving the field finishes the current edit. The default "popover" presentation retains its portal, outside-click dismissal and Escape behavior.
2026-10-07 · WorkspacePanelGrid
WorkspacePanelGrid from @qokit/components/patterns/WorkspaceLayout places independent detail panels below the shortest available column. It responds to content and container size changes without moving or remounting child nodes; DOM and keyboard order remain unchanged. Narrow containers use one column. Keep continuous panels in one grid rather than separate rows. Metrics, tables, paired fields and ordered workflows retain their own layouts.
Each direct child is a panel. Use data-workspace-panel-span="full" or a numeric column span on that child's root for wider panels. The optional skin has a root slot and variables; --qk-workspace-panel-grid-gap controls shared spacing, and --qk-workspace-panel-grid-max-columns defaults to 2. Without JavaScript or ResizeObserver, panels retain the responsive ordinary grid.
2026-10-08 · Shared list toolbar groups
WorkspaceFilterToolbar now has one container-responsive contract across Projects, CMS and Admin:
query:search,filtersstatus,sort,controlsdomain, opsiadvanced,resetbersyarat,resultsumber daya, dansummarytambahan.presentation:view, tampilkancontrolsdanoptionsseperti kolom yang terlihat dan ukuran halaman. Kustomisasi widget halaman berada di tindakan header halaman.actions: persistent operations, followed by the optionalselectioncontrol at the logical end. UseToolbarButtonswithiconand localizedcompactLabelfor refresh and other familiar actions.
The shared component measures its own available width. Controls show icons with labels above 960px and accessible icon buttons at or below 960px. At or below 640px, search occupies the first row and tool groups wrap in query → presentation → actions order. Routes must not override group widths or hide individual labels. ControlMenu and ViewMenu inherit this presentation without a route-specific responsive flag.
Gunakan query.result={{ label, count, total?, locale? }} untuk nama sumber daya dan jumlah hasil. WorkspaceResultSummary menampilkan “Nama · jumlah” dan menambahkan “/ total” hanya jika total tanpa filter yang tepercaya berbeda; angka diformat sesuai bahasa UI dan diisolasi dalam teks dua arah. Hilangkan result sampai jumlah diketahui; nol adalah hasil yang valid. Jangan tambahkan baris nama dan jumlah lain di atas daftar yang sama. AdminFilterBar.result menerima objek yang sama. Judul halaman, bagian yang bermakna, paginasi, dan jumlah terpilih tetap memiliki peran masing-masing; gunakan query.summary untuk satuan lain, konteks pencarian, atau pembaruan.
Give overflow a localized label to move advanced and display options into More when compact. query.compactItems and presentation.compactItems supply complete menu choices replacing their corresponding controls; controlled values and callbacks remain in the host. Permanent menu actions use overflow.items. Selection and refresh stay outside More. Select and Done share the end slot, hit target and reserved idle toolbar height, including wrapped mobile rows.
This replaces the old flat toolbar API: migrate search, filters, sort, reset and secondaryControls into query; migrate view and display controls into presentation; move persistent endActions to actions. The former adaptive / inline-wrap CSS modes and WorkspaceFilterControlGroup capsule are removed; use these three semantic groups rather than compatibility aliases.
2026-10-10 · EditorItemDisclosure
EditorItemDisclosure from @qokit/components/patterns/EditorItemCollection accepts title, summary, open, onOpenChange, leading, actions and children for editing within a list. Sibling items remain visible. Escape collapses the item and restores trigger focus; opening does not scroll or autofocus. useEditorItemDisclosure scopes single-item expansion with scopeKey and restores adjacent focus after deletion. EditorItemCollection uses the same interaction; hosts still own content, ordering, persistence and undo. The existing EditorFocusedItem export remains available for flows that require a separate detail view.
Referensi API tambahan (bahasa Inggris; terjemahan menyusul) · 2026-10
2026-10-15 · Shared inspector choices
EditorStyleChoice uses the shared EditorChoiceControl for finite settings. In auto mode, two or three illustrated options use a segmented group; larger illustrated sets use a portalled ControlMenu showing the current icon and name. Text-only choices retain a native Select. Existing custom values remain selectable.
Opsi pilihan dan menu mendukung annotation untuk menambahkan titik berwarna tema dan memasukkan makna terlokalisasi ke nama aksesibel. Pemicu ControlMenu juga menampilkan titik opsi aktif; triggerAnnotation: null membatasinya ke dalam menu. Memilih ulang opsi terpilih yang aktif memanggil onReselect. Opsi bawaan menampilkan anotasi di samping label; hidden mengecualikan placeholder dari daftar. Host menentukan nilai yang ditandai dan tindakannya; kontrol bersama tidak menyimpulkan pewarisan atau menulis data.
Use presentation="visual" for labeled diagram choices and presentation="toolbar" for familiar tools such as four-way text alignment. The toolbar has separate targets without a shared capsule. Native radios, shared menu keyboard handling, visible focus, disabled states and theme Tokens are retained. Hosts own labels, allowed values, persistence and undo. id identifies the control; ControlMenu also accepts triggerId and disabled.
Inspector menus, inputs, collapsed summaries and reset actions share a 32px mouse field height, restored to 40px on narrow screens and coarse pointers. Field icons use 16px and diagram choices keep an 8px gap. EditorComponentSettings reuses these choices for columns, density, image fit and aspect ratio, while composition layouts retain detailed previews. If saving briefly disables native radios, the shared skeleton restores focus to the selected option for continuous arrow-key editing.
Inspector labels and diagram captions use the 12px caption scale; values, actions and section titles use the 13px field scale. Visual choices have no decorative outer border: a soft selected surface and centered caption identify the current option, while keyboard focus retains its ring. Font specimens in the inspector use a compact, bounded scale.
2026-10-15 · Responsive workspace tables
WorkspaceDataTable reflows mobileLayout="records" into two columns of labeled facts, with the primary identity and sticky end actions spanning the record. Names and identifiers can use two lines. Column labels and selection remain accessible. Comparison tables using mobileLayout="scroll" retain their columns.
When a host toolbar already provides sorting or other header actions, set mobileHeader="labels" to remove duplicate header controls from the mobile layout and tab order. Column names remain available to assistive technology; desktop headers are unchanged. The default "controls" preserves custom header controls on mobile.
2026-10-14 · Independent editor panels
resolveWorkspaceResponsiveProfile and useWorkspaceResponsiveProfile from WorkspacePanels, and EditorWorkbenchChrome, accept the optional panelPolicy="independent". With BuilderWorkbenchFrame and the platform editor skin, both panels remain docked above the mobile threshold. Shared styles temporarily compress displayed widths while retaining remembered sizes, and the canvas fits the remaining space. Effective work areas at or below 720px retain mobile task switching.
Hosts own panel visibility. When supplying a measured profile, use the same policy for the measurement hook and Chrome. Omitting panelPolicy retains the default "adaptive" policy with its existing desktop, two-column and overlay layouts.
Editor workspace integration
workspaceNavigation connects the host's shared business navigation through EditorWorkbenchChrome: desktop navigation reserves space beside the content, while mobile uses the shared drawer. It is separate from the document structure panel navigation and retains the host's permissions and unsaved-change protection.
EditorSaveButton.showIcon keeps the save glyph beside its label. iconOnly reduces the control to an icon while retaining an accessible action and status name and tooltip. Editor hosts can use useCompactWorkspaceHeader() to show icons and labels in roomy layouts and icons alone in compact layouts. EditorStatusAction.iconOnly follows the same rule while retaining its issue count.
2026-10-15 · EditorControlGroup title actions
The headerActions slot on EditorControlGroup remains visible in both expanded and collapsed groups, for actions such as content visibility beside a group title. Pointer and keyboard interactions with these actions do not toggle the group. summaryActions still appears only when collapsed. Hosts own action names, state and persistence; icon actions must use the shared IconButton with a localized accessible name.
2026-10-14 · Management groups and summaries
WorkspaceSectionGroup, WorkspaceSection, WorkspaceFieldGrid and WorkspaceFacts are exported from @qokit/components/patterns/WorkspaceLayout. Headings and descriptions sit above their content panels on both desktop and mobile, sharing the starting edge. Use the default stacked layout; legacy layout="split" callers also render stacked. Apply qk-workspace-section-group__form to forms within a group to share spacing and save-area alignment. WorkspaceSection accepts optional icon, actions and description slots, keeping headings outside the content panel.
WorkspaceFieldGrid arranges independent short fields in at most two columns according to available width. WorkspaceFacts renders a semantic definition list with stable id, label, value, and optional unit, description, emphasis and tone. columns supports 2, 3 or 4 columns and adapts to narrow containers. Set mobileColumns={2} for short numeric summaries that should retain two columns on phones; the default is one. It is unboxed so summaries can share an existing content panel. Each component supports its named Skin, className and style. Hosts retain form state, permissions, submission, conflicts and recovery; these components do not make requests.
2026-10-14 · Management content panels and disclosures
WorkspaceContentPanel and WorkspaceSection.kind support summary, form, records, and actions. Section toolbar stays outside the content surface; supporting and footer provide compact metadata and end operations. titleId preserves existing heading anchors. The default panel container does not override a host's named container.
Use WorkspacePanelBlock, WorkspacePanelMeta, and WorkspaceRecordRow for subordinate groups, metadata, and repeated records. A record accepts title, description, meta, status, actions, and full-width detail children. Facts always align at the top. Hosts retain business fields, permissions, table columns, and submission boundaries.
WorkspaceActionRow accepts an optional action label or quiet empty/loading status, alongside description and actions. Action identity uses 14px semibold text, status uses 14px regular text, and descriptions use 12px. Copy and controls share a center line on desktop and stack at narrow widths. Card surfaces do not override descendant strong typography or spacing.
WorkspaceDisclosure accepts title, optional status, and children; WorkspaceDisclosureGroup accepts Accordion items and controlled expansion props. They start closed unless the host specifies an initial item, and open at most one sibling. Enter/Space toggles; Escape closes and returns focus to its trigger, handling inner disclosures before their parent. Hidden panels retain their DOM and input state. Optional headingLevel supplies section heading semantics; Skin and class slots only adapt appearance. Import these components from @qokit/components/patterns/WorkspaceLayout.
CustomizableWidgetLayoutControls / CustomizableWidgetLibrary
Tempatkan CustomizableWidgetLayoutControls di tindakan header halaman setelah bantuan kontekstual dan sebelum tindakan utama, termasuk pada seluler. Gunakan copy.customize yang dilokalisasi untuk menamai tindakan secara eksplisit (misalnya, "Sesuaikan widget"). Entri hanya ikon yang sama mengekspos aria-pressed dan aria-expanded, dan menjadi copy.done saat pengeditan. customizeButtonRef secara opsional mengekspos pemicu untuk pemulihan fokus host; disabledCustomize menonaktifkan entri tanpa mengubah geometrinya. Berikan onCollapseToggle dan areWidgetsCollapsed hanya untuk host yang mendukung pelipatan widget; jika dihilangkan, entri kustomisasi akan ditampilkan sendiri.
CustomizableWidgetLibrary memiliki judul perpustakaan umum, tindakan reset/tutup, tata letak gulir responsif, fokus tombol tutup awal, dan penanganan Escape. Menutup mengembalikan fokus ke kontrol yang memanggilnya ketika fokus masih berada di dalam perpustakaan; klik di luar mempertahankan fokus tujuannya. Host menyimpan definisi widget, perintah tambah/hapus/pesan/resize, persistensi, dan semantik reset. Slot kelas CMS dan Admin tetap tersedia untuk hook domain, tetapi tidak boleh menentukan permukaan perpustakaan atau tata letak seluler terpisah.
2026-10-17 · Pemicu ActionMenu yang Kaya
ActionMenu.renderTrigger dapat menggunakan kontrol kaya seperti SelectableTile. Kontrol ini menerima aria-expanded, aria-haspopup, disabled, dan onClick; sebarkan nilai-nilai tersebut ke pemicu aktualnya. Host tetap mempertahankan semantik pemilihan dan tampilan dari kontrol tersebut. Penyesuaian posisi portal, navigasi keyboard menu, penutupan, pengembalian fokus, dan lembaran mobile opsional tetap menjadi tanggung jawab ActionMenu. Pemicu tombol dan ikon default tidak berubah.
Kontrol radius dan rentang
RangeNumber dari @qokit/components/ui/RangeNumber memasangkan penggeser rentang bawaan dengan Input angka yang tepat. Berikan label, value, min, max, opsi step dan unit, serta onChange. Nilai yang tidak ditentukan menampilkan tanda hubung nilai campuran; perubahan pada salah satu input menetapkan satu angka dalam batas. onCommit memungkinkan aplikasi mengelompokkan perubahan berkelanjutan dalam riwayat urungkan yang ada. disabled, navigasi papan ketik, kepadatan ringkas, RTL, dan gaya fokus digunakan bersama; penyimpanan tetap milik aplikasi. RangeNumberSkin menyediakan slot akar, penggeser, input, dan satuan.
EditorRadiusControl dari @qokit/components/patterns/EditorRadiusControl menggabungkan pratinjau bentuk langsung, empat input sudut fisik, RangeNumber, dan preset bentuk opsional. value dan onChange menggunakan singkatan CSS border-radius; aplikasi melokalkan cornerLabels dan nama preset. Pada RTL urutannya tetap kiri atas, kanan atas, kanan bawah, kiri bawah. max membatasi penyuntingan ke nilai piksel berbatas; menghilangkannya mempertahankan satuan CSS dan sintaks sudut elips. Radius campuran tidak menampilkan satu angka sampai keempat sudut diatur bersama. EditorRadiusControlSkin opsional menyesuaikan slot akar, diagram, pratinjau, dan preset tanpa mengubah status atau penyimpanan.
2026-10-22 · Tab navigasi aktif pada layar sempit
PillTabs menerima opsi scrollActiveTabIntoView dengan nilai bawaan false. Pada tab horizontal, anak langsung yang aktif, PillTabLink atau PillTabButton, ditampilkan saat dipilih atau ukurannya berubah. Hanya baris tab yang bergulir; posisi halaman dan fokus papan ketik tetap. LTR dan RTL didukung dengan koreksi langsung, termasuk saat gerakan dikurangi. Tab vertikal dan pemanggil tanpa opsi ini mempertahankan perilakunya.