컴포넌트 통합
Qokit 공유 컴포넌트, Pattern, Skin 및 스타일 Token의 공개 통합 계약입니다.
컴포넌트 통합
Qokit은 "공유 스켈레톤 + Skin 레시피" 모델을 사용합니다. 외부 통합 담당자는 컴포넌트의 의미론적 및 상호작용 계약을 의존하고, Skin과 Token을 통해 시각적 적응을 완료합니다.
2026-10-20 · 시각적 선택 카드의 독립 작업
EditorVisualChoiceGroup 옵션은 독립적인 카드 메뉴나 이름 편집기를 위한 선택적 accessory 를 받습니다. 공유 RadioGroup 은 이를 기본 레이블 옆에 배치하므로 카드 관리 작업이 라디오 선택을 바꾸지 않습니다. afterOptions 는 카드 생성 같은 별도 카탈로그 작업을 선택 항목 뒤에 배치합니다. 저장, 권한, 검증과 카드 교체·삭제 후 포커스는 호스트가 관리합니다. 부가 작업이 없는 옵션은 기존 구조와 동작을 유지합니다.
2026-10-17 · 공유 작업대 패널 모션
EditorWorkbenchChrome은 Creator 및 콘텐츠 편집에서 사용되는 동일한 패널 골격인 BuilderWorkbenchFrame을 통해 주입된 시작/끝 차선을 렌더링합니다. 호스트는 콘텐츠, 가시성 및 너비 선호도를 제공합니다. 데스크톱은 추적 및 패널 불투명도/변위를 --qk-sidebar-motion-duration 및 --qk-sidebar-motion-easing과 공유하며, 드래그하면 전환이 비활성화되고 감소된 모션은 즉시 전환됩니다.
축소된 패널은 초안을 유지하기 위해 마운트된 상태로 남습니다. 공유 프레임은 inert 및 aria-hidden을 즉시 적용하고, 플랫폼 스킨은 가시성을 숨기기 전에 종료 작업을 완료합니다. 컴팩트 패널은 종료 내내 오버레이 기하 구조를 유지하며, 호스트는 패널 셸에 hidden 또는 display: none을 추가해서는 안 됩니다. 명시적인 피크 패널은 기존 대화식 표시 동작을 유지합니다. 헤더 선택은 열림/닫힘 상태 전반에 걸쳐 사용 가능하며, 전화 목적지가 메뉴를 공유해야 할 경우 EditorPanelChoiceShortcuts.mobileMenu을 사용하십시오.
2026-10-17 · 측정된 에디터 기본값
useWorkspaceResponsiveProfile은 인라인 패딩을 공제한 후 반응형 프로필에 사용되는 동일한 사용 가능한 작업 영역 너비를 보고하는 선택적 onWidthChange(width)을 허용합니다. 다른 관찰자를 추가하지 않고 비율 기반 기본값을 도출하려면 안정적인 콜백을 사용하십시오. useEditorLayout은 호스트 선호도와 공유 너비 저장소 모두에 sharedWidths.limits을 적용하며, readEditorLayout은 선택적 네 번째 인수로 동일한 제한을 허용합니다. 기존 호출자는 기본 경계와 동작을 유지합니다.
2026-09-30 · SelectionToolbar 접근성
SelectionToolbar.ariaLabel은 선택적으로 도구 모음 영역의 이름을 지정합니다. 개수는 실시간 상태 메시지로 유지됩니다. 호스트는 현지화된 레이블을 제공하고 actionContent로 공유 EditorToolGroup과 ActionMenu를 구성할 수 있습니다. 권한 검사와 작업 처리는 호스트가 담당합니다.
2026-09-10 · 워크스페이스 식별 배지
ProjectSwitcherProject.badge는 선택적인 비대화형 React 콘텐츠를 받습니다. 각 항목 이름, 목록에 없는 현재 컨텍스트 행, 텍스트 트리거의 현재 이름 옆에 표시됩니다. 아이콘 전용 트리거는 간결하게 유지되고, 플랫폼 텍스트 트리거는 휴대전화 너비에서 워크스페이스 이름을 보존하도록 배지를 숨깁니다. 열린 메뉴에서는 배지를 계속 표시합니다. 호스트는 올바른 범위의 데이터, 현지화된 레이블과 표시 스타일을 제공하며, 필드를 생략하면 기존 모양이 유지됩니다.
2026-09-08 · EmptyState
EmptyState는 선택적 장식 icon, title, 선택적 description 및 action을 투명한 표면 중앙에 배치합니다. layout="section"은 간결한 기본값이고 layout="workspace"는 빈 업무 영역에 더 넓은 공간을 확보합니다. 작업은 action에 직접 넣고 여러 버튼은 fragment로 묶습니다. 공통 컨테이너가 간격과 긴 레이블을 처리합니다. 제목은 h2이며 strong 대신 title skin 슬롯을 사용하세요. 기존 루트 클래스를 유지하고 skin.vars와 style을 지원합니다. 번역 문구, 권한, 탐색, 생성 처리는 호스트가 담당하며 검색 결과와 오류는 고유 메시지와 작업을 유지합니다.
2026-09-08 · SidebarNavigation
SidebarNavigation은 마우스가 180밀리초 머물거나 키보드 포커스를 받으면 동일 출처 경로를 미리 가져옵니다. 고정 및 팝업 탐색은 30초당 최대 8개 대상을 공유합니다. 오프라인, 숨겨진 탭, Save-Data 또는 2G에서는 중단하며 다운로드, 비활성 링크, 새 창 및 같은 페이지 앵커는 제외합니다. 탐색과 저장하지 않은 변경 보호는 유지됩니다.
2026-09-07 - AccountDropdown / SidebarProfile
AccountDropdown에 선택적 compact와 preferences를 추가했습니다. 간결한 모드는 식별자와 제작 기록을 숨기며 기본값은 기존 내용을 유지합니다. 계정 메뉴의 Appearance와 Language는 triggerRole="menuitem"을 지원합니다. 키보드 탐색은 포커스를 복원하고 중첩된 언어 대화상자가 Esc를 직접 처리합니다. SidebarNavigation.searchEnabled의 기본값은 true이며 짧고 고정된 탐색에는 false를 사용할 수 있습니다. 메뉴 없이 href를 갖는 SidebarProfile은 펼침 및 아이콘 모드에서 같은 대상을 엽니다.
2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace
양식의 글자 크기를 통일하고 긴 문구를 줄바꿈하며 알약 모양과 브랜드 색상을 유지합니다. FormField는 그룹 이름을 제공하고 controlId와 내부 입력 id로 레이블을 연결합니다. SearchField는 지운 뒤 초점을 돌려줍니다. Segmented와 ControlMenu는 비활성 옵션을 지원하며 비활성 ActionMenu 항목은 링크가 없습니다. 처리 중인 버튼은 크기와 표시기를 유지합니다. AdminEntityDialog는 필수 항목, 이메일과 JSON을 검증하고 오류에 초점을 맞추며 중복 저장을 막고 실패 시 입력을 유지합니다. EditorWorkspace의 ref.focusControl(element)는 숨겨진 패널을 표시한 뒤 초점을 맞춥니다. 동작 줄이기는 컨트롤 전환을 끕니다. WorkspaceDialog는 제목과 작업을 표시한 채 긴 내용만 스크롤하며 모바일의 짧은 대화 상자는 내용 높이에 맞춥니다。
2026-09-07 · WorkspaceLocationSync / ProjectSwitcher
경로 전환이 완료되면 WorkspaceLocationSync가 임시 공간 선택 패널을 닫고 대상 페이지의 도구를 표시합니다. 검색 및 섹션 설정은 유지됩니다. 사이드바의 범위 이름과 맥락은 별도 줄에 표시하며, 헤더의 긴 이름은 버튼 안에서 줄임표로 표시합니다.
2026-09-07 · 통합 탐색과 Qokit의 둥근 표면
WorkspaceNavigationDock은 items, fallback, className, onClickCapture로 호스트의 탐색과 권한을 재사용하며 별도 세션을 불러오지 않습니다. 펼침·아이콘·숨김 설정을 공유하고 860px 이하에서는 서랍 메뉴를 사용합니다. PlatformHeader.leadingContext는 EditorHeader에도 표시됩니다. 캡슐 버튼과 둥근 표면은 유지하고 중복 테두리를 제거합니다.
데스크톱에서 메뉴를 클릭하면 사이드바를 완전히 숨기거나 마지막 표시 모드로 복원합니다. 메뉴 또는 사이드바 가장자리를 드래그하면 숨김, 아이콘만 표시, 펼침 상태로 전환됩니다. 왼쪽/오른쪽 화살표 키는 읽기 방향을 따릅니다. 드래그를 취소하면 저장된 설정이 유지되며, 모바일에서는 탐색 서랍을 사용합니다.
Next 레이아웃의 Suspense 아래에 WorkspaceLocationSync를 한 번 배치합니다. useWorkspaceQueryState(key, defaultValue, validate)는 [value, setValue, ready]를 반환하며 useWorkspaceQueryRecord(key, defaults, validators)는 선언된 평면 필터만 복원합니다. 인증 정보나 초안을 URL에 저장하지 마세요. WorkspacePage는 제한된 세션 스크롤 위치를 복원하고 내부 영역은 data-workspace-scroll-region과 WorkspaceScrollRestoration을 사용합니다. 취소 가능한 브라우저 뒤로·앞으로 탐색은 기록 추가 없이 이탈 보호를 사용합니다. AdminEntityDialog는 저장 실패와 부모 재렌더링 후에도 입력을 유지하며 버전과 저장 결과는 호스트가 관리합니다.
관리 화면은 페이지 제목 20px/650, 구역 제목 16px/600, 본문과 탐색 14px, 라벨 13px, 보조 설명 12px를 사용합니다. --qk-workspace-body-ink와 --qk-workspace-active-ink는 기존 플랫폼 색상에서 파생됩니다.
알약 모양의 기본 버튼은 Logo 파랑 #4695D8을 유지하며 밝고 어두운 테마 모두 글자, 아이콘, 로딩 표시기를 흰색으로 표시합니다. 마우스를 올렸을 때 약간 밝아지는 효과를 유지합니다. 보조 버튼과 위험 작업은 각 의미에 맞는 색상을 유지합니다.
드롭다운과 작업 공간 전환기는 --menu-option-font-size (14px), --menu-option-font-weight (500), 줄 높이 1.45를 공유합니다. 선택 항목은 굵기 600, 보조 정보는 12px/400을 사용합니다. WorkspaceNavigationDock은 마우스 호버나 키보드 포커스 시 동일 출처의 목적지를 미리 불러오며 중복 기록 수를 제한합니다. 기존 이탈 보호와 호스트 경로는 유지됩니다.
2026-09-07 - ColumnLayout
ColumnLayout은 고정 탐색 영역, 독립적인 콘텐츠 스크롤 영역, 상단에 유지되는 페이지 도구 모음으로 데스크톱 관리 화면을 채웁니다. WorkspacePage는 평평한 구역과 공통 모서리 Token을 사용합니다. 860px 이하에서는 탐색 서랍을 유지하며 닫힌 서랍은 조작할 수 없습니다. 속성과 업무 동작은 그대로입니다. 중복된 바깥 여백을 제거하고 읽기 너비는 양식 안에서 제한하세요.
가져오기 진입점
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';| 진입점 | 용도 |
|---|---|
@qokit/components/ui | Button, Card, Dialog, Menu, Pill 등 기본 컴포넌트 |
@qokit/components/patterns | Header, Footer, 작업 영역, 테이블, 리소스 및 AI 어시스턴트 등 조합 |
@qokit/components/skins/platform | 플랫폼 및 작업 영역 시각 레시피 |
@qokit/components/skins/admin | Admin 시각 레시피 |
@qokit/components/skins/site | 생성 사이트 시각 레시피 |
공용 책임 경계
PromptPanel은 선택적 referenceReader 및 현지화된 referenceCopy 속성을 허용합니다. 리더는 비동기 file(File, AbortSignal) 및 website(url, AbortSignal)를 통해 추출된 contentExcerpt 및 truncated 태그를 반환하며, 인증 및 API 접근은 호스트가 담당합니다. 컴포넌트는 읽기, 미리보기, 재시도 및 제거를 관리합니다. 유효한 URL에 프롬프트 텍스트가 없는 경우 referenceCopy.websitePrompt가 요청을 보완하며, 형식 오류는 referenceCopy.errors.url를 사용하고 읽기를 차단합니다. URL이 아직 읽히지 않았거나 읽는 중일 때 제출하면 최신 내용을 기다려 한 번만 제출합니다. 입력 변경이나 읽기 실패 시 대기 중인 제출 작업이 취소되며, 재시도는 이전 제출을 복원하지 않습니다. 파일은 준비된 후에만 제출할 수 있습니다. 전체 URL은 붙여넣기, 포커스 해제 또는 Enter 키 입력 시 자동으로 읽히며, 초기 URL도 읽혀 진행 중이거나 완료된 결과를 재사용합니다. 실패 시 명확한 재시도 옵션을 제공합니다. URL 편집 또는 제거 시 이전 읽기를 취소하고 결과를 지웁니다. 리더가 제공되지 않으면 비동기 참조 처리 없이 네이티브 제출을 계속합니다.
참조 수집은 2026년 9월에 선택적이고 하위 호환되는 컴포넌트 기능으로 추가되었습니다.
스켈레톤 컴포넌트는 다음을 보장합니다:
- DOM 및 의미론적 태그;
- ARIA, 키보드, 포커스 및 disabled 동작;
- 상태 및 기본 상호작용;
- 안정적인 기본 class;
- 명명된 Skin 슬롯.
Skin은 다음을 수행할 수 있습니다:
root,header,body,item,action등의 슬롯에 class 추가;vars를 통해 CSS 변수 전달;- 컴포넌트가 이미 공개한 tone, layer 또는 시각적 적응 스위치 사용.
Skin은 데이터를 요청하거나, DOM을 변경하거나, 비즈니스 규칙을 보유하거나, 접근성 동작을 우회해서는 안 됩니다.
생성된 요소 콘텐츠
생성된 사용자 정의 블록은 Schema v2에서 등록된 html-* 요소를 계속 사용하며, 실행 가능한 HTML이나 새로운 블록 유형은 사용하지 않습니다. 2026년 9월부터 @qokit/site-schema는 언어 콘텐츠 바인딩을 위해 bindSiteModuleContent, updateSiteModuleBoundContent, forkSiteModuleContentBindings를 제공합니다. 콘텐츠 경로는 모듈에 저장되고, 방문자 문구는 언어 콘텐츠 매핑에 저장되며, 업데이트는 되돌리기 및 저장 트랜잭션을 따릅니다. 요소를 복사하거나 블록 간 이동할 때 바인딩을 파생시켜 출처 변경을 방지해야 합니다.
선택적인 extensionRequirements는 미해결된 런타임 요구 사항을 기록하며, 설치 매니페스트나 권한 부여가 아닙니다. createSiteExtensionHandoff는 실행 불가능한 v1 개발 요청을 내보냅니다. 실행 가능한 사이트를 게시하기 전에 이러한 요구 사항을 해결하거나 검토 후 명확하게 제외해야 합니다.
폼 컨트롤
공유 폼은 라벨, 설명, 필수 메타데이터, 오류 및 컨트롤 ID를 연결하기 위해 FormField를 사용합니다. 텍스트 컨트롤은 Input을 사용하고, 다중 줄 콘텐츠는 Textarea를, 선택 컨트롤은 Checkbox, RadioGroup, Switch를 사용합니다. 기존 Select 및 SearchField는 동일한 크기 및 상태 계약을 사용합니다.
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는 id, aria-describedby, aria-invalid, required를 통해 라벨, 설명 및 오류를 유일한 하위 컨트롤에 연결합니다. 공유 컨트롤을 추가적인 <label>로 감싸지 마십시오.
Input, Textarea, Select, SearchField는 40px, 44px, 48px에 해당하는 sm, md, lg 세 가지 크기를 지원합니다. 한 줄 컨트롤은 기본적으로 pill 모양을 사용하며, Textarea는 항상 공유 다중 줄 둥근 모서리를 사용합니다. 각 상호작용 및 오류 상태는 공유 토큰에서 가져옵니다.
마이그레이션 기간 동안에도 이전 .qk-field 계약을 사용할 수 있습니다. 새로운 통합은 공유 컴포넌트와 명명된 스킨 슬롯을 사용해야 합니다.
목록 선택
2026년 9월부터 목록은 useWorkspaceSelectionMode({ enabled, resetKey, onClear })과 WorkspaceFilterToolbar.selection을 함께 사용할 수 있습니다. 이 Hook은 초기에 비활성화되며, 범위나 권한이 변경될 때 재설정되고, 선택된 ID 지우기와 일괄 모드 종료를 구분합니다. 범위 키에는 컬렉션, 언어, 페이지네이션 및 필터가 포함되어야 합니다.
일괄 모드가 활성화된 경우에만 WorkspaceDataTable.selection을 전달하며, 그리드와 모바일 체크박스 컨트롤은 동일한 모드를 사용합니다. 툴바는 일반적인 선택 작업을 담당하며, 사용자는 현지화된 문구, 선택적 ID 및 권한이 확인된 도메인 작업을 제공합니다. 선택적인 actionContent는 추가적인 ARIA 시맨틱을 담을 수 있지만, 일반적인 컨트롤이나 확인 절차를 대체하지는 않습니다. 읽기 전용 목록에는 일괄 모드가 표시되지 않으며, 파일 선택기와 제안 검토는 각각의 시맨틱을 유지합니다.
이러한 새로운 기능은 선택적이고 하위 호환됩니다. 표 선택은 여전히 사용자가 명시적으로 제어합니다.
지표 카드
추가 API 참조 (영어, 번역 예정) · 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 및 Footer
Logo는 기본적으로 정적 이미지를 표시합니다. motion="breathe"는 숨겨진 동안 크기를 유지하고, 페이지가 로드되고 절반 이상 보이면 4.8초 호흡 애니메이션으로 한 번 나타납니다. 머리글과 바닥글에는 추가 대기가 없습니다. motionVisibilityDelayMs는 연속 가시 시간을 추가할 수 있으며 기본값은 0입니다. motionOnceKey는 같은 문서의 재마운트 간 재생 기록을 공유하며 머리글과 바닥글에 별도 키를 사용합니다. 탐색, 테마 변경, 다시 스크롤해도 재생하지 않고 전체 새로고침 시 초기화됩니다. 동작 줄이기, JavaScript 비활성화 또는 가시성 관찰을 사용할 수 없으면 정적 로고를 표시합니다. motion="reveal"은 별칭으로 유지됩니다.
PlatformHeader.autoHideOnScroll의 기본값은 false이며 PublicPlatformHeader가 활성화합니다. 아래로 스크롤하면 숨고 위로 스크롤하거나 상단에 가까워지면 나타납니다. 열린 머리글 메뉴나 내부 포커스가 있으면 계속 표시합니다. 작업 공간과 편집기 머리글은 고정됩니다.
PlatformHeader는 비즈니스 상태가 없는 Header 스켈레톤입니다. PublicPlatformHeader는 브랜드 진입점, 공용 내비게이션, 언어, 테마, 로그인, "지금 체험하기" 및 모바일 메뉴를 그 위에 조합하며, 플랫폼 익명 상태와 문서 사이트는 이 조합을 직접 공유합니다.
공용 내비게이션은 buildPublicHeaderNavItems(copy, links)를 통해 "리소스 / 가격 / 뉴스"를 일괄 생성합니다. 통합 담당자는 현재 애플리케이션의 사이트 내부, 문서 사이트 및 플랫폼 URL만 해석해야 하며, 메뉴 순서나 문구를 중복 정의해서는 안 됩니다. 로그인 후의 플랫폼 Header도 동일한 생성 함수를 사용합니다.
<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는 여전히 link, scroll 및 menu를 지원합니다. menu는 데스크탑에서 클릭, 키보드, Escape 및 외부 클릭으로 닫기를 지원하며, 모바일에서는 MobileHeaderMenu가 링크 그룹으로 확장합니다.
SiteFooter는 Footer 스켈레톤입니다. 플랫폼과 문서 사이트는 PublicPlatformFooter를 사용하여 외부 Shell, 브랜드 진입점, 링크, 테마 및 언어 컨트롤을 일괄 조합합니다. 도메인 간 통합은 resolveCompanyHref를 통해 상대 플랫폼 링크를 절대 주소로 변환합니다.
<PublicPlatformFooter
brandHref="https://qokit.com"
copy={footerCopy}
resolveCompanyHref={(href) => `https://qokit.com${href}`}
/>비즈니스 애플리케이션은 Header, Footer DOM 또는 공용 내비게이션 배열을 복제해서는 안 되며, 다른 시각적 표현이 필요한 경우 PlatformHeaderSkin, SiteFooterSkin 또는 해당 플랫폼 Skin을 사용하십시오.
호환 전략
- 추가된 선택적 속성과 Skin 슬롯은 하위 호환 변경으로 간주됩니다;
- 속성 삭제, 기본 의미론적 수정 또는 DOM/키보드 동작 변경은 파괴적 변경으로 간주됩니다;
- 파괴적 변경은 반드시 Changelog에 포함되어야 하며, 마이그레이션 예제를 제공해야 합니다;
- 공개되지 않은 내부 class, 디렉토리 또는 라우팅 구조에 의존하지 마십시오;
- 두 개 이상의 진입점에서 동일한 덮어쓰기가 필요한 경우, 공개 Skin 또는 Token으로 승격해야 합니다.
전체 화면 편집
EditorWorkspace는 전체 화면 대화 상자, 포커스 관리, 반응형 패널을 제공합니다. dirty는 변경 사항을 버릴지 확인하고, busy는 저장 중 닫기를 막으며, onSave는 Ctrl/Cmd+S를 처리합니다. 권한, 데이터, 저장 및 게시는 호스트 앱이 담당합니다.
view / onViewChange는 본문 편집기를 교체하지 않고 edit, focus, preview를 전환합니다. preview는 미리 보기를 제공하고 previewPanel은 기존 패널을 재사용합니다. layout은 writing, structure, canvas를 지원합니다. storageKey는 패널 너비와 접힘 설정만 기억하며 본문을 저장하지 않습니다.
onSaveAndClose는 저장 성공 확인 후 true, 실패 시 false, 호스트가 이동한 경우 handled, 업무 검증에 사용자 결정이 필요한 경우 pending을 반환합니다. 실패하면 편집기를 유지합니다. closeBehavior="collapse"는 호스트가 초안을 보관할 때만 사용합니다. EditorSaveStatus는 확인된 상태를 표시합니다. EditorViewControls, EditorLeaveDialog, useEditorLayout도 기존 작업 공간에 조합할 수 있습니다.
키보드 변경: Segmented는 Tab 정지점 하나를 사용하며 방향키 / Home / End로 선택합니다. Dialog는 하위 오버레이의 Escape 처리를 존중합니다. 그다음 편집기는 집중 또는 미리 보기를 종료한 뒤 닫기를 처리합니다. LivePreviewToolbar.exitControl은 공통 보기 컨트롤을 받습니다. 저장, 게시, 권한은 계속 호스트가 관리합니다.
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은 기존 사이드바 전환 버튼을 작업 공간 헤더에 배치합니다. 왼쪽 사이드바와 슬롯을 하나씩 사용합니다. 상태, 단축키, 모바일 서랍은 계속 SidebarNavigation이 관리하며 슬롯이 없으면 기존 위치를 유지합니다. 모바일 서랍도 헤더 버튼으로 닫으며, 닫은 후 같은 버튼으로 포커스가 돌아갑니다.
EditorHeader
EditorHeader는 활성 편집기에 호스트의 로고, 계정 및 전역 메뉴를 유지합니다. startControl과 endControl은 양쪽 패널, center는 보기 명령, actions는 저장 작업을 배치합니다. PlatformHeader.editorActions는 반응형 탐색, 언어 및 테마 컨트롤을 재사용합니다. onNavigate는 콜백을 실행하기 전에 저장하지 않은 변경 사항을 처리해야 합니다. 좁은 화면에서는 헤더가 두 줄로 표시되며 하위 메뉴가 Escape를 먼저 처리합니다.
WorkspaceHeaderPortal.startControl 및 endControl은 호스트의 일치하는 슬롯에 관리된 페이지 패널 토글을 배치합니다. 호스트는 제목, 상태 및 작업과 함께 선택적 startTarget 및 endTarget을 노출합니다. 파일 라이브러리 및 단일 자산 작업 공간은 workAreaControls을 사용하며, 자산 미리보기는 전체 헤더를 유지하여 정체성, 반환 작업 및 패널 목적지를 계속 사용할 수 있게 합니다. ProjectWorkspace은 콘텐츠 및 파일에 대한 공유 왼쪽 탐색/대화 선택권을 소유합니다. 파일은 useProjectResourcePanel을 통해 기억된 리소스 패널 차원을 등록하고, ProjectContentTools을 통해 탐색을 포털하며, ProjectToolbar.endControl을 통해 오른쪽 검사기 제어만 제공합니다. 대화는 프로젝트 영역 전반에 걸쳐 동일한 왼쪽 차선 및 임베디드 작문가를 사용합니다. 컴팩트 리소스, 대화 및 검사기 작업은 상호 배타적입니다.
EditorNavigationMenu
EditorNavigationMenu는 호스트의 전체 SidebarNavigation을 겹쳐 표시하여 캔버스를 이동하지 않고 권한과 프로젝트 정보를 유지합니다. 언어와 테마는 하단에 배치하며 하위 메뉴가 Escape를 먼저 처리합니다. 집중 모드와 브라우저 전체 화면은 독립적입니다. 이동은 진행 중인 저장을 기다리고 초안을 보호합니다.
WorkspaceNavigationMenu / WorkspacePageHeader
전역 탐색은 Mac에서 Command+\, Windows/Linux에서 Control+\를 사용하며 Creator 안에서도 독립적으로 작동합니다. T와 Shift+T는 편집기 레이아웃 동작을 유지합니다. 편집 가능한 대상, 문자 조합 중인 입력, 반복 및 이미 처리된 이벤트는 무시합니다. 버튼 안내와 aria-keyshortcuts가 키 조합을 표시하며, 전역 탐색은 단독 T를 더 이상 사용하지 않습니다.
로그인한 작업 공간은 PlatformHeader.workspaceActions로 모든 화면 너비에서 계정 및 탐색 영역을 공유합니다. WorkspacePageHeader는 제목과 작업을 통일합니다. WorkspaceNavigationMenu는 권한과 맥락을 유지한 현재 사이드바를 표시하며 EditorNavigationMenu는 호환 별칭으로 남습니다. Studio는 전용 도구 모음을 유지합니다. 공개 페이지 헤더의 표현은 유지됩니다.
WorkspaceNavigationGuard는 dirty, busy, error와 선택적 onSave로 전역 탐색을 보호합니다. 저장 성공이 확인되어 true를 반환해야 이동하며 실패하면 초안을 유지합니다. Language.onBeforeChange(apply)로 언어 변경에도 같은 보호를 적용할 수 있습니다. 저장 중에는 양식 필드를 비활성화합니다.
데스크톱 탐색은 펼침과 아이콘 모드를 유지하며 자동 숨기기를 추가합니다. 사이드바와 서랍은 검색 및 그룹 상태를 공유합니다. 정밀 포인터가 가장자리에 300ms 머무르면 임시로 열리고, 벗어난 뒤 320ms 후 닫힙니다. 클릭하면 열린 상태를 유지합니다. 터치와 키보드 조작 버튼도 유지합니다. Dialog의 기본값은 modal={true}와 autoFocus={true}이며, 임시 미리보기에서는 둘 다 false로 설정하여 입력 포커스와 스크롤을 유지합니다.
EditorViewControls
하나의 버튼으로 양방향 전환합니다. 편집 중에는 집중, 집중 중에는 편집을 표시합니다. 클릭하거나 T를 누르며, E는 바로 편집으로 돌아갑니다. 좁은 헤더에서도 전환 버튼은 유지하고 미리 보기, 전체 화면과 추가 작업은 더 보기 메뉴에 둡니다.
EditorViewControls는 편집/집중 모드와 기본 전체 화면을 별도로 제어합니다. 미리 보기는 독립적인 전환이며 닫으면 이전 편집 모드로 돌아갑니다. 사용자 지정 종료 동작은 useEditorWorkMode로 해당 모드를 유지합니다. edit/focus/preview 값은 계속 지원됩니다. 미리 보기는 모드 그룹의 radio 대신 aria-pressed가 있는 button을 사용합니다. 전체 화면은 클릭으로 시작하고 앱 루트에 탐색과 대화 상자를 포함하며, 지원되지 않으면 숨깁니다.
Language / Appearance
Language와 Appearance variant="menu"는 레이블, 현재 값, 화살표를 표시하는 layout="row"를 지원합니다. 기본 간결한 레이아웃과 언어 변경 보호는 유지됩니다. SiteHeaderCopy.helpResources와 contactSupport로 작업 공간 도움말 링크 이름을 선택적으로 지정합니다.
requestWorkspaceNavigation
사이드바 전환 버튼이 있는 페이지는 접힌 상태와 모바일에서도 헤더의 중복 메뉴 버튼을 표시하지 않습니다. 편집기와 사이드바가 없는 페이지에는 유지합니다. @qokit/components/patterns/WorkspaceNavigation에서 requestWorkspaceNavigation(returnFocusTarget?)와 useWorkspaceNavigationState()를 가져옵니다. 요청은 등록된 서랍을 전환하며 사용 가능한 서랍이 없으면 false를 반환합니다. 선택 요소는 닫은 후 포커스를 받습니다. 다른 진입점을 표시하기 전에 .available을 확인하세요. 제거된 버튼의 DOM 위치 대신 기존 버튼이나 이 API를 사용하세요.
WorkspacePanelReveal
전역 탐색에는 메뉴 아이콘을, 편집 도구에는 좌우 패널 아이콘을 사용합니다. useWorkspacePanelReveal({ temporary: true })는 집중 모드에서 클릭과 키보드로 도구를 임시로 엽니다. toggle(trigger?)와 close(true)는 배치와 작업 모드를 유지하고 닫은 뒤 포커스를 돌려줍니다. 화면 가장자리는 전역 탐색을 열고 도구는 자체 버튼 근처에서 반응합니다. 미리보기는 패널 버튼을 숨기며 명시적인 편집 복귀 동작으로 이전 모드를 복원합니다.
EditorViewControls / 보기 모드
EDITOR_VIEW_SHORTCUTS → Tooltip + aria-keyshortcuts
EditorHeader는 EDITOR_TOOLBAR_SHORTCUTS도 관리합니다. Command/Control+S는 표시된 EditorSaveButton을 실행하고, Shift+P는 EditorStatusAction shortcut="publish"을, Shift+M은 편집 도구 메뉴를 엽니다. 클릭과 동일한 활성 컨트롤을 사용하며, 게시는 패널에서 명시적으로 실행해야 합니다. 활성 상태로 표시된 헤더만 응답합니다. 하위 메뉴, 대화 상자, 조합 입력 및 반복 이벤트에서는 작동하지 않으며 입력 필드에서는 저장만 허용합니다. 힌트와 aria-keyshortcuts는 정의를 공유합니다. 사용자 지정 toolsControl은 트리거에 aria-keyshortcuts={EDITOR_TOOLBAR_SHORTCUTS.tools.aria}를 지정합니다. ActionMenu.triggerKeyShortcuts는 속성과 힌트만 추가하며 전역 명령은 등록하지 않습니다.
패널 명령은 Shift+A(추가), Shift+L(페이지/레이어), Shift+K(대화), Shift+C(콘텐츠), Shift+D(디자인), Shift+G(전체 스타일)입니다. CMS는 사용 가능한 경우 Shift+S(설정), Shift+E(SEO), Shift+H(기록)를 제공합니다. EditorChoiceControl, EditorViewTabs, ActionMenu에 shortcut 메타데이터를 전달하면 힌트를 공유합니다. EditorPanelChoiceShortcuts와 휴대폰용 EditorViewControls.compactActions은 메뉴로 접혀도 원래 동작을 유지합니다. EditorPanelShortcuts.commands는 컨트롤을 복제하지 않고 기존 동작을 등록합니다. 숨김, inert, 비활성, 미리보기 및 오버레이 제한은 유지됩니다. 같은 작업 공간의 비모달 모바일 사이드바에서는 패널 전환이 가능하지만 메뉴와 모달 대화 상자는 단축키를 차단합니다. 보조키 없는 기존 키 동작은 유지됩니다.
| 보기 모드 | |
|---|---|
E | 편집 |
T | 편집 ↔ 집중 |
V | 미리 보기 / 편집으로 돌아가기 |
F | 전체 화면 열기 / 전체 화면 종료 |
활성 편집기만 응답합니다. 텍스트 입력, IME 조합, 키 길게 누르기, 하위 대화 상자나 메뉴가 열린 상태에서는 모드가 전환되지 않습니다.
PlatformHeader.workspaceNavigation
PlatformHeader.workspaceNavigation은 전역 탐색을 로고 앞에 배치하고 workspaceActions와 editorActions는 계정 작업을 유지합니다. 작업 공간은 기존 사이드바 버튼을 재사용하며 편집기의 오른쪽 패널 버튼은 아바타 앞에 배치합니다. 좁은 화면에서는 탐색, 브랜드, 제목, 아바타가 윗줄에, 편집 도구와 저장이 아랫줄에 표시됩니다. DOM 순서도 배치에 맞추며 테두리 없는 반투명 효과를 유지합니다.
2026-09-06 - EditorHeader.preview / EditorViewControls.returnView
EditorHeader.preview는 center만 테두리 없는 간결한 미리보기 도구 모음으로 표시합니다. 로고, 계정, 저장, 패널 컨트롤은 마운트된 채 숨겨집니다. 별도의 LivePreviewToolbar를 쓰면 편집기 헤더를 숨기고 EditorViewControls.returnView(edit 또는 focus)로 이전 모드를 복원합니다. 접근 가능한 돌아가기와 독립적인 전체 화면 조작을 유지하며 사이트 자체의 헤더는 표시합니다.
2026-09-06 · Builder / CMS
Builder와 CMS는 패널, 삽입 그림, 표시 설정에 BuilderWorkspace, EditorCatalog, EditorComponentSettings를 함께 사용합니다. 프리셋은 관련 설정을 한 번에 적용하고 기존 콘텐츠를 보존하며, 저장과 실행 취소는 각 호스트가 담당합니다. 작업 영역 컨트롤은 플랫폼 테마를, 콘텐츠는 사이트 테마를 따릅니다.
서버에서 렌더링하는 푸터 · 2026-09-07
SiteFooterLayout에 명시적인 locale과 단일 언어의 copy를 전달합니다. 서버 컴포넌트가 공통 푸터 구조를 렌더링하며 테마 및 언어 컨트롤과 QR 대화 상자는 클라이언트 컴포넌트로 유지됩니다. 기존 SiteFooter 및 PublicPlatformFooter 인터페이스도 계속 지원됩니다.
import { SiteFooterLayout } from '@qokit/components/patterns/SiteFooter';
<div className="qk-platform-footer-shell">
<SiteFooterLayout locale={locale} copy={footerCopy} />
</div>도메인 간 링크는 서버에서 copy.companyLinks에 설정합니다. controls로 대화형 컨트롤 슬롯을 사용자 지정할 수 있습니다.
EditorHeader.titleControl / FloatingAssistant.presentation
EditorHeader.titleControl과 EditorWorkspace.titleControl로 제목을 공통 프로젝트 메뉴로 바꿀 수 있습니다. 설명이 담긴 title과 탐색 시 저장하지 않은 변경 사항 보호를 유지합니다. FloatingAssistant.presentation="embedded"는 플로팅 버튼이나 배경 오버레이 없이 호스트 패널 안에 이름 있는 영역을 표시합니다. 기본값은 floating입니다. 호스트는 위치와 표시 여부를, 어시스턴트는 대화 상태와 권한을 관리합니다.
2026-09-07 · WorkspaceAssembly
WorkspaceAssembly는 레이아웃 상자를 추가하지 않고 나가는 카드와 들어오는 영역을 표시합니다. 직접 자식 구조가 필요하면 기존 DOM에 workspaceAssemblyAttributes(part, index, phase)를 지정합니다. EditorHeader.assemble과 BuilderWorkspacePanels.assemble은 편집기 표시를 제공합니다.
생성이 성공한 뒤에만 await startWorkspaceAssembly(navigate, destinationPathname)를 호출합니다. 보이는 조각을 캡처하고 한 번 이동한 뒤 목적지 또는 해당 로딩 골격을 최대 720ms 안에 조립합니다. 목적지는 진입용 canvas 표시가 필요합니다. useWorkspaceAssemblyPending()으로 캡처 배치가 끝날 때까지 로딩 화면을 유지하며 데이터와 코드를 미리 불러옵니다. 동작 줄이기 설정이나 미지원 브라우저에서는 바로 이동합니다. 느리거나 중단된 전환은 캡처를 해제하고 이동을 계속합니다. 표시만으로 편집, 새로 고침, 방문 기록 이동에 애니메이션이 생기지 않습니다. 공통 패턴은 임시 스타일을 정리하고 호스트는 생성 오류, 멱등성, 로딩 상태를 관리합니다.
2026-09 · 관리 작업 공간
WorkspacePage와 WorkspaceLayout의 variant는 overview, list, detail, settings, editor를 지원합니다. WorkspaceFormFooter는 호스트가 제공하는 actions, message, tone, busy를 배치하며 데이터 저장은 호스트가 담당합니다.
좁은 WorkspaceDataTable과 AdminDataTable은 선택, 사용자 지정 머리글, 작업을 유지하는 레이블 기반 레코드를 기본 표시합니다. 비교 표에는 mobileLayout="scroll"을 사용합니다. WorkspaceFilterToolbar는 검색과 필터 뒤에 정렬과 보기 제어를 배치합니다. 사이드바는 h2, 페이지는 h1을 사용합니다.
2026-09-08 · Task focus
useSidebarTaskFocus(active)는 집중 작업 중 탐색 메뉴를 일시적으로 숨깁니다. 종료 시 이전 표시 방식으로 복원하되 사용자가 직접 변경한 모드를 우선합니다. 자동 숨김은 저장된 설정을 변경하지 않습니다.
추가 API 참조 (영어, 번역 예정)
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.
Web 어댑터는 FloatingAssistantPanel.composerAttachments도 전달합니다. 이 슬롯은 메시지 폼 안의 텍스트 입력란 앞에 호스트가 관리하는 첨부를 표시합니다. 호스트가 배치와 전송 상태를 관리하며, 드롭은 전송 대기 첨부만 추가합니다. 성공 시 전송한 첨부만 지우고 실패 시 재시도를 위해 유지합니다.
공유 대화 구성 요소 (영어 참조, 번역 대기)
@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는 InlineNotice를 조합해 대화 안에 작업 상태, 실패, 대체 처리, 저장 확인을 간결하게 표시합니다. 현지화된 title과 선택 항목인 description, tone, action을 제공합니다. 두 줄 모두 캡션 글자 크기, 좁은 간격, 투명한 표면을 사용하며, 색조로 상태를 강조하고 보조 텍스트는 은은하게 표시합니다. 기본값인 role="status"와 aria-atomic="true"는 전체 업데이트를 함께 읽습니다. 사용자 조치가 필요한 실패에는 role="alert"를 사용합니다. 어시스턴트가 작성한 본문은 계속 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.
추가 API 참조 (영어, 번역 예정) · 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, 상태filters,sort, 도메인controls,advanced옵션, 조건부reset, 리소스result및 보조summary.presentation:view, 표시되는controls및options(예: 표시된 열 및 페이지 크기) 등을 보여줍니다. 페이지 위젯 사용자 정의는 페이지 헤더 작업에 속합니다.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.
리소스 이름과 결과 수에는 query.result={{ label, count, total?, locale? }} 를 사용합니다. 공유 WorkspaceResultSummary 는 “이름 · 개수”를 표시하며 신뢰할 수 있는 필터 전 총수가 다를 때만 “/ 전체”를 추가합니다. 숫자는 UI 언어에 맞게 서식 지정하고 양방향 텍스트에서 분리합니다. 개수를 모르면 result 를 생략하며 0은 유효합니다. 같은 목록 위에 이름과 개수 행을 중복하지 마세요. AdminFilterBar.result 도 같은 객체를 받습니다. 페이지 제목, 의미 있는 구역 제목, 페이지 이동, 선택 개수는 각 역할을 유지하고 다른 단위, 검색 맥락, 갱신 정보에는 query.summary 를 사용합니다.
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.
추가 API 참조 (영어, 번역 예정) · 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.
선택 및 메뉴 옵션은 annotation으로 테마 색상의 점을 추가하고 현지화된 의미를 접근 가능한 이름에 포함할 수 있습니다. ControlMenu 트리거에도 활성 옵션의 점이 표시되며 triggerAnnotation: null은 메뉴 안에만 표시합니다. 활성화된 선택 항목을 다시 고르면 onReselect가 호출됩니다. 기본 선택 옵션은 레이블 옆에 설명을 표시하고 hidden은 자리표시자를 목록에서 제외합니다. 표시할 값과 선택 동작은 호스트가 결정하며 공유 컨트롤은 상속을 추론하거나 데이터를 쓰지 않습니다.
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
CustomizableWidgetLayoutControls을 컨텍스트 도움말 이후 및 주요 작업 이전에 페이지 헤더 작업에 배치하십시오(모바일 포함). 액션을 명시적으로 명명하기 위해 지역화된 copy.customize을 사용하십시오(예: "위젯 사용자 정의"). 동일한 아이콘 전용 진입점은 aria-pressed 및 aria-expanded을 노출하며, 편집 중에는 copy.done이 됩니다. customizeButtonRef은 호스트 포커스 복구를 위한 트리거를 선택적으로 노출하며, disabledCustomize은 기하 구조를 변경하지 않고 진입점을 비활성화합니다. 위젯 축소를 지원하는 호스트에만 onCollapseToggle 및 areWidgetsCollapsed을 공급하십시오. 이를 생략하면 사용자 정의 진입점만 렌더링됩니다.
CustomizableWidgetLibrary은 공통 라이브러리 제목, 재설정/닫기 작업, 반응형 스크롤 레이아웃, 초기 닫기 버튼 포커스 및 Escape 처리를 소유합니다. 닫기를 실행하면 포커스가 여전히 라이브러리 내부에 있을 때 호출된 컨트롤로 포커스가 반환되며, 외부 클릭은 목적지 포커스를 유지합니다. 호스트는 위젯 정의, 추가/제거/순서/크기 조정 명령, 지속성 및 재설정 의미론을 유지합니다. CMS 및 Admin 클래스 슬롯은 도메인 훅을 위해 계속 사용 가능하지만, 별도의 라이브러리 표면이나 모바일 레이아웃을 정의해서는 안 됩니다.
2026-10-17 · 풍부한 ActionMenu 트리거
ActionMenu.renderTrigger은(는) SelectableTile과 같은 풍부한 컨트롤을 재사용할 수 있습니다. aria-expanded, aria-haspopup, disabled, 그리고 onClick를 받아 실제 트리거에 스프레드합니다. 호스트는 컨트롤의 선택 시맨틱스와 외관을 유지합니다. 포털 위치 지정, 메뉴 키보드 탐색, 닫기, 포커스 복귀 및 선택적 모바일 시트는 ActionMenu이(가) 관리합니다. 기본 버튼 및 아이콘 트리거는 변경되지 않았습니다.
모서리 반경 및 범위 컨트롤
@qokit/components/ui/RangeNumber의 RangeNumber는 기본 범위 슬라이더와 정확한 숫자 Input을 결합합니다. label, value, min, max, 선택적 step과 unit, onChange를 전달합니다. 정의되지 않은 값은 혼합 값을 나타내는 대시로 표시하며, 어느 입력이든 변경하면 범위 내의 단일 숫자가 설정됩니다. onCommit으로 연속 변경을 호스트의 기존 실행 취소 기록에 묶을 수 있습니다. disabled, 키보드 탐색, 조밀한 배치, RTL 및 포커스 스타일은 공유하고 저장은 호스트가 담당합니다. RangeNumberSkin은 루트, 슬라이더, 입력 및 단위 슬롯을 제공합니다.
@qokit/components/patterns/EditorRadiusControl의 EditorRadiusControl은 실시간 도형 미리 보기, 네 물리적 모서리 입력, RangeNumber 및 선택적 도형 프리셋을 결합합니다. value와 onChange는 CSS border-radius 축약형을 사용하며 호스트가 cornerLabels와 프리셋 이름을 번역합니다. RTL에서도 순서는 왼쪽 위, 오른쪽 위, 오른쪽 아래, 왼쪽 아래입니다. max를 지정하면 제한된 픽셀 값만 편집하고, 생략하면 CSS 단위와 타원형 모서리 구문을 유지합니다. 혼합 반경은 네 모서리를 함께 설정하기 전까지 단일 숫자를 표시하지 않습니다. 선택적 EditorRadiusControlSkin은 상태나 저장 방식을 바꾸지 않고 루트, 도식, 미리 보기 및 프리셋 슬롯을 조정합니다.
2026-10-22 · 좁은 화면의 활성 탐색 탭
PillTabs는 기본값이 false인 선택적 scrollActiveTabIntoView를 지원합니다. 가로 탭에서는 선택하거나 크기를 변경할 때 활성 직계 자식 PillTabLink 또는 PillTabButton을 보이게 합니다. 탭 줄만 스크롤하며 페이지 위치와 키보드 포커스는 유지합니다. LTR과 RTL을 지원하고 동작 줄이기 설정에서도 즉시 보정합니다. 세로 탭이나 옵션을 생략한 호출은 기존 동작을 유지합니다.