Integração de Componentes
Contrato de integração pública para componentes compartilhados, Patterns, Skins e Tokens de Estilo do Qokit.
Integração de Componentes
O Qokit utiliza o modelo "estrutura compartilhada + receita de Skin". Integradores externos dependem dos contratos semânticos e de interação dos componentes, completando a adaptação visual através de Skins e Tokens.
2026-10-20 · Ações independentes nos cartões de seleção visual
As opções de EditorVisualChoiceGroup aceitam um accessory opcional para menus ou editores de nome independentes. O RadioGroup compartilhado o posiciona ao lado do rótulo nativo, para que gerenciar um cartão não selecione seu botão de opção. afterOptions inclui uma ação separada do catálogo, como criar um cartão, após as opções. Persistência, permissões, validação e foco após substituição ou remoção pertencem ao hospedeiro. Opções sem acessórios preservam estrutura e comportamento.
17/10/2026 · Movimento compartilhado do painel da bancada
EditorWorkbenchChrome renderiza faixas de início/fim injetadas através de BuilderWorkbenchFrame, o mesmo esqueleto de painel usado pelo Creator e pela edição de conteúdo. Os hosts fornecem conteúdo, visibilidade e preferências de largura. O desktop rastreia e a opacidade/translação do painel compartilham --qk-sidebar-motion-duration e --qk-sidebar-motion-easing; arrastar desativa transições e o movimento reduzido muda imediatamente.
Painéis colapsados permanecem montados para manter rascunhos. O quadro compartilhado aplica imediatamente inert e aria-hidden, enquanto a skin da plataforma completa a saída antes de ocultar a visibilidade. Painéis compactos retêm sua geometria de sobreposição durante toda a saída; os hosts não devem adicionar hidden ou display: none à shell do painel. Painéis de inspeção explícitos retêm seu comportamento existente de revelação interativa. As escolhas do cabeçalho permanecem disponíveis nos estados aberto/fechado; use EditorPanelChoiceShortcuts.mobileMenu quando os destinos de telefone devem compartilhar um menu.
17/10/2026 · Padrões medidos do editor
useWorkspaceResponsiveProfile aceita onWidthChange(width) opcional, relatando a mesma largura disponível da área de trabalho usada para perfis responsivos após a dedução do preenchimento interno. Use um callback estável para derivar padrões proporcionais sem adicionar outro observador. useEditorLayout aplica sharedWidths.limits às preferências do host, bem como ao armazenamento de largura compartilhado; readEditorLayout aceita os mesmos limites como seu quarto argumento opcional. Chamadores existentes retêm seus limites e comportamento padrão.
2026-09-30 · Acessibilidade de SelectionToolbar
SelectionToolbar.ariaLabel pode nomear a barra como uma região. A contagem continua sendo uma mensagem de status ao vivo. O aplicativo hospedeiro fornece rótulos localizados e pode usar actionContent para combinar os componentes compartilhados EditorToolGroup e ActionMenu; as verificações de permissão e os manipuladores de ações permanecem no hospedeiro.
2026-09-10 · Selos de identidade do espaço de trabalho
ProjectSwitcherProject.badge aceita conteúdo React opcional e não interativo. O selo aparece ao lado do nome de cada item, na linha do contexto atual que não esteja listado e ao lado do nome atual em um acionador textual. Acionadores somente com ícone continuam compactos; acionadores textuais da plataforma ocultam o selo em larguras de celular para preservar o nome do espaço. O menu aberto ainda exibe o selo. O host fornece dados com escopo correto, rótulos localizados e estilos de apresentação; omitir o campo mantém a aparência existente.
2026-09-08 · EmptyState
EmptyState centraliza o icon decorativo opcional, title, description opcional e action em uma superfície transparente. layout="section" é compacto por padrão; layout="workspace" reserva mais espaço. Insira as ações em action, usando um fragment para vários botões; o contêiner cuida do espaçamento e de rótulos longos. O título é h2: use o slot title em vez de strong. As classes raiz permanecem; há suporte a skin.vars e style. O hospedeiro mantém textos localizados, permissões, navegação e criação; buscas e erros preservam suas mensagens e ações.
2026-09-08 · SidebarNavigation
SidebarNavigation pré-carrega rotas da mesma origem após 180 ms de permanência do mouse ou ao receber foco do teclado. A navegação fixa e a flutuante compartilham o limite de 8 destinos por 30 segundos. O pré-carregamento pausa offline, em abas ocultas, com Save-Data ou 2G; exclui downloads, links desativados, novas janelas e âncoras da mesma página. A navegação e a proteção de alterações permanecem.
2026-09-07 - AccountDropdown / SidebarProfile
AccountDropdown aceita compact e preferences opcionais: o modo compacto oculta identificadores e histórico de criação; o padrão mantém o conteúdo existente. Appearance e Language aceitam triggerRole="menuitem" no menu da conta. A navegação pelo teclado restaura o foco, e diálogos de idioma aninhados tratam Escape. SidebarNavigation.searchEnabled é true por padrão; use false para navegação curta e fixa. SidebarProfile com href, sem menu, abre o mesmo destino nos modos expandido e de ícones.
2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace
Formulários compartilham escala tipográfica e quebram textos longos, mantendo formas de pílula e cores da marca. FormField nomeia grupos: controlId e a id interna vinculam o rótulo. SearchField devolve o foco após limpar. Segmented e ControlMenu aceitam opções desativadas; itens desativados de ActionMenu não têm link. Botões ocupados mantêm tamanho e indicador. AdminEntityDialog valida campos obrigatórios, e-mail e JSON, foca erros, impede salvamentos duplicados e preserva entradas após falhas. EditorWorkspace oferece ref.focusControl(element) para revelar painéis ocultos antes de focar. Movimento reduzido desativa transições dos controles. WorkspaceDialog rola conteúdo longo mantendo cabeçalho e ações visíveis; diálogos móveis curtos se ajustam ao conteúdo.
2026-09-07 · WorkspaceLocationSync / ProjectSwitcher
Após a mudança de rota, WorkspaceLocationSync fecha o seletor temporário de espaços e mostra as ferramentas do destino. As preferências de busca e seções são mantidas. O nome do escopo e seu contexto ficam em linhas separadas; nomes longos no cabeçalho são truncados dentro do botão.
2026-09-07 · Navegação unificada e superfícies arredondadas Qokit
WorkspaceNavigationDock reutiliza navegação e permissões do host com items, fallback, className e onClickCapture, sem carregar outra sessão. A preferência existente define expansão, ícones ou ocultação; até 860px permanece o menu lateral. PlatformHeader.leadingContext também aparece em EditorHeader. Botões em cápsula e superfícies arredondadas são preservados; bordas repetidas são removidas.
No desktop, clicar no menu oculta a barra lateral ou restaura seu último modo visível. Arrastar o menu ou a borda da barra alterna entre oculta, apenas ícones e expandida. As setas esquerda/direita seguem a direção de leitura. Cancelar o arraste preserva a preferência salva; no celular, permanece o painel de navegação.
Monte WorkspaceLocationSync uma vez sob Suspense no layout Next. useWorkspaceQueryState(key, defaultValue, validate) retorna [value, setValue, ready]; useWorkspaceQueryRecord(key, defaults, validators) restaura apenas filtros planos declarados. Não coloque credenciais nem rascunhos em URLs. WorkspacePage restaura posições limitadas de rolagem da sessão; áreas internas usam data-workspace-scroll-region e WorkspaceScrollRestoration. A navegação nativa cancelável reutiliza a proteção de saída sem adicionar histórico. AdminEntityDialog mantém entradas após falhas e novas renderizações; versões e resultados continuam sob responsabilidade do host.
A gestão usa papéis tipográficos fixos: título da página 20px/650, seção 16px/600, texto e navegação 14px, rótulos 13px, notas 12px. --qk-workspace-body-ink e --qk-workspace-active-ink derivam das cores existentes.
Os botões principais em pílula mantêm o azul do Logo #4695D8 e usam texto, ícones e indicadores brancos nos dois temas. O cursor mantém o leve clareamento. Botões secundários e de perigo conservam suas cores semânticas.
Menus suspensos e seletores de espaço compartilham --menu-option-font-size (14px) e --menu-option-font-weight (500), com altura de linha 1.45; opções selecionadas usam 600 e metadados 12px/400. WorkspaceNavigationDock pré-carrega destinos da mesma origem ao passar o mouse ou receber foco do teclado, com deduplicação limitada. As proteções de saída e as rotas do host continuam ativas.
2026-09-07 - ColumnLayout
ColumnLayout preenche a janela de gestão com navegação ancorada, rolagem independente e barra de página fixa. WorkspacePage usa seções planas e Tokens de raio compartilhados. Até 860px, a navegação continua em um painel, inativo quando fechado. Propriedades e comportamento de negócio não mudam. Remova margens externas duplicadas e limite a largura dentro dos formulários.
Ponto de Entrada
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';| Ponto de Entrada | Uso |
|---|---|
@qokit/components/ui | Componentes básicos como Button, Card, Dialog, Menu, Pill |
@qokit/components/patterns | Combinações como Header, Footer, Workspace, Tabela, Recursos e Assistente de IA |
@qokit/components/skins/platform | Receita visual da Plataforma e Workspace |
@qokit/components/skins/admin | Receita visual do Admin |
@qokit/components/skins/site | Receita visual gerada para o site |
Limites de Responsabilidade Pública
PromptPanel aceita as propriedades opcionais referenceReader e referenceCopy para localização. O leitor extrai contentExcerpt e marca truncated via as funções assíncronas file(File, AbortSignal) e website(url, AbortSignal); autenticação e acesso à API são de responsabilidade do host. O componente gerencia leitura, pré-visualização, novas tentativas e remoção; quando a URL válida não possui texto de dica, referenceCopy.websitePrompt complementa a solicitação, e erros de formato usam referenceCopy.errors.url e bloqueiam a leitura. Enviar enquanto a URL ainda não foi lida ou está sendo lida aguarda o conteúdo mais recente e envia apenas uma vez; mudanças na entrada ou falhas na leitura cancelam a ação pendente, e novas tentativas não recuperam envios antigos. O arquivo deve estar pronto antes do envio. URLs completas são lidas automaticamente ao colar, perder o foco ou pressionar Enter; URLs iniciais também são lidas e reutilizam resultados em andamento ou concluídos; falhas oferecem uma nova tentativa clara. Editar ou remover URLs cancela leituras antigas e limpa os resultados. Sem um leitor fornecido, o envio nativo continua, sem tratamento assíncrono de referências.
A ingestão de referências foi adicionada em setembro de 2026 como uma capacidade opcional e compatível com versões anteriores do componente.
A estrutura do componente garante:
- DOM e etiquetas semânticas;
- Comportamento de ARIA, teclado, foco e disabled;
- Estado e interação básica;
- Classes padrão estáveis;
- Slots nomeados de Skin.
O Skin pode:
- Adicionar classes aos slots
root,header,body,item,action, etc.; - Transmitir variáveis CSS via
vars; - Usar os interruptores de tom, layer ou adaptação visual já divulgados pelo componente.
O Skin não deve solicitar dados, alterar o DOM, manter regras de negócio ou contornar comportamentos de acessibilidade.
Conteúdo de Elementos Gerados
Blocos personalizados gerados continuam usando o elemento html-* registrado no Schema v2, sem HTML executável ou novos tipos de bloco. Desde setembro de 2026, @qokit/site-schema fornece bindSiteModuleContent, updateSiteModuleBoundContent e forkSiteModuleContentBindings para vinculação de conteúdo por idioma. Caminhos de conteúdo são salvos no módulo, textos de visitantes no mapa de conteúdo por idioma; atualizações seguem transações de desfazer e salvar; ao copiar ou mover elementos entre blocos, os vínculos devem ser derivados para evitar alterações na origem.
Opcionalmente, extensionRequirements registra necessidades de tempo de execução não resolvidas, não sendo um manifesto de instalação ou concessão de permissões. createSiteExtensionHandoff exporta solicitações de desenvolvimento v1 não executáveis; antes de publicar um site funcional, essas necessidades devem ser resolvidas ou explicitamente excluídas após revisão.
Controles de Formulário
Formulários compartilhados usam FormField para associar rótulos, descrições, metadados obrigatórios, erros e IDs de controles. Controles de texto usam Input, conteúdo multilinha usa Textarea, controles de seleção usam Checkbox, RadioGroup e Switch; Select e SearchField existentes usam o mesmo contrato de tamanho e estado.
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 associa rótulos, descrições e erros ao único controle filho via id, aria-describedby, aria-invalid e required. Não envolva controles compartilhados com <label> adicionais.
Input, Textarea, Select e SearchField suportam os três tamanhos sm, md e lg, correspondentes a 40px, 44px e 48px. Controles de linha única usam por padrão a forma pill; Textarea usa sempre o arredondamento multilinha compartilhado. Cada estado de interação e erro vem de Tokens compartilhados.
Durante a migração, o antigo contrato .qk-field ainda pode ser usado; novas integrações devem usar componentes compartilhados e slots de Skin nomeados.
Seleção em Listas
Desde setembro de 2026, listas podem usar useWorkspaceSelectionMode({ enabled, resetKey, onClear }) junto com WorkspaceFilterToolbar.selection. Esse Hook inicia inativo, reseta quando escopo ou permissões mudam, e distingue limpar IDs selecionados de sair do modo em lote; chaves de escopo devem incluir coleção, idioma, paginação e filtros.
Passe WorkspaceDataTable.selection apenas quando o modo em lote estiver ativo; grades e controles de seleção mobile usam o mesmo padrão. A barra de ferramentas cuida das ações de seleção gerais, enquanto o consumidor fornece textos localizados, IDs opcionais e ações de domínio verificadas por permissão. actionContent opcional pode carregar semântica ARIA adicional, mas não substitui controles gerais ou confirmações. Listas somente leitura não exibem modo em lote; seletores de arquivos e revisões de propostas mantêm sua própria semântica.
Essas novas capacidades são opcionais e compatíveis com versões anteriores; a seleção em tabelas ainda é controlada explicitamente pelo consumidor.
Cartões de Métricas
Novas referências de API (inglês; tradução pendente) · 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 e Footer da Plataforma
Logo exibe uma imagem estática por padrão. motion="breathe" reserva espaço enquanto está oculto e revela o logo uma vez, com uma animação de respiração de 4,8 segundos, quando a página termina de carregar e pelo menos metade está visível. Cabeçalho e rodapé não adicionam espera. motionVisibilityDelayMs pode exigir um período contínuo de visibilidade e vale zero por padrão. motionOnceKey compartilha o registro de reprodução entre remontagens no mesmo documento; cabeçalho e rodapé usam chaves separadas. Navegação, troca de tema e retorno da rolagem não repetem a animação; recarregar toda a página a reinicia. Movimento reduzido, JavaScript desativado ou ausência de observação de visibilidade exibem o logo estático. motion="reveal" permanece como alias.
PlatformHeader.autoHideOnScroll é false por padrão; PublicPlatformHeader o ativa. O cabeçalho se oculta ao rolar para baixo e retorna ao subir ou perto do topo. Menus abertos e foco no cabeçalho o mantêm visível. Cabeçalhos do espaço de trabalho e do editor ficam fixos.
PlatformHeader é a estrutura do Header sem estado de negócio. O PublicPlatformHeader combina sobre ele entradas de marca, navegação pública, idioma, tema, login, "Experimente Agora" e menu móvel; o estado anônimo da plataforma e o site de documentação reutilizam diretamente esta combinação.
A navegação pública é gerada uniformemente via buildPublicHeaderNavItems(copy, links) como "Recursos / Preços / Notícias". Os integradores devem analisar apenas URLs internos do aplicativo atual, do site de documentação e da plataforma, não devendo redefinir a ordem ou o texto do menu. O Header da plataforma após o login também usa a mesma função de geração.
<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'
}}
/>A estrutura subjacente navItems ainda suporta link, scroll e menu. O menu no desktop suporta fechar por clique, teclado, Escape e clique externo; no mobile, o MobileHeaderMenu expande para grupos de links.
O SiteFooter é a estrutura do Footer; a plataforma e o site de documentação usam PublicPlatformFooter para combinar uniformemente o Shell externo, entrada de marca, links, controles de tema e idioma. A integração cross-domain converte links relativos da plataforma em endereços absolutos via resolveCompanyHref.
<PublicPlatformFooter
brandHref="https://qokit.com"
copy={footerCopy}
resolveCompanyHref={(href) => `https://qokit.com${href}`}
/>Aplicações de negócio não devem copiar o DOM do Header/Footer ou o array de navegação pública; para diferentes apresentações visuais, use PlatformHeaderSkin, SiteFooterSkin ou o Skin da plataforma correspondente.
Estratégia de Compatibilidade
- Novas propriedades opcionais e slots de Skin são consideradas mudanças compatíveis com versões anteriores;
- Exclusão de propriedades, modificação da semântica padrão ou alteração do comportamento de DOM/teclado são consideradas mudanças destrutivas;
- Mudanças destrutivas devem entrar no Changelog e fornecer exemplos de migração;
- Não dependa de classes internas, diretórios ou estruturas de rota não publicadas;
- Quando dois ou mais pontos de integração exigirem a mesma sobrescrita, deve-se elevá-la a um Skin ou Token público.
Edição em tela cheia
EditorWorkspace reúne um diálogo em tela cheia, gerenciamento de foco e painéis responsivos. dirty confirma o descarte de alterações, busy impede o fechamento durante o salvamento e onSave atende a Ctrl/Cmd+S. A aplicação cuida de permissões, dados, salvamento e publicação.
view / onViewChange alternam entre edit, focus e preview sem substituir o editor. preview fornece a prévia; previewPanel reutiliza um painel. layout aceita writing, structure e canvas. storageKey lembra larguras e painéis recolhidos, nunca o documento.
onSaveAndClose retorna true após confirmar o salvamento, false em caso de falha, handled se o aplicativo já navegou ou pending se a validação exige uma decisão. A falha mantém o editor aberto. Use closeBehavior="collapse" somente quando o aplicativo preserva o rascunho. EditorSaveStatus mostra estados confirmados. EditorViewControls, EditorLeaveDialog e useEditorLayout também podem ser combinados em espaços existentes.
Migração de teclado: Segmented tem uma parada de Tab e usa setas / Home / End. Dialog respeita Escape tratado por uma sobreposição filha; depois o editor sai do foco ou da prévia antes de fechar. LivePreviewToolbar.exitControl aceita os controles de visualização compartilhados. Salvamento, publicação e permissões continuam sob responsabilidade do aplicativo.
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 coloca o controle da barra lateral no cabeçalho. Use um único slot com uma barra lateral esquerda. SidebarNavigation mantém o estado, os atalhos e o painel móvel; sem slot, os controles ficam no lugar original. O botão do cabeçalho também fecha o painel móvel; ao fechar, o foco volta para esse mesmo botão.
EditorHeader
EditorHeader mantém o logo, a conta e o menu global do host no editor ativo. startControl e endControl controlam os painéis laterais, center as visualizações e actions o salvamento. PlatformHeader.editorActions reutiliza a navegação responsiva, o idioma e o tema. onNavigate deve tratar alterações não salvas antes de executar o callback. Em telas estreitas, o cabeçalho usa duas linhas; os submenus processam Escape primeiro.
WorkspaceHeaderPortal.startControl e endControl colocam alternâncias de painel de página gerenciada nos slots correspondentes do host. Os hosts expõem startTarget e endTarget opcionais junto com título, status e ações. A biblioteca de Arquivos e o espaço de trabalho de ativo único usam workAreaControls; a visualização de ativos mantém o cabeçalho completo para que sua identidade, ação de retorno e destinos do painel permaneçam disponíveis. ProjectWorkspace possui as escolhas compartilhadas de navegação/conversa à esquerda para Conteúdo e Arquivos. Os Arquivos registram suas dimensões lembradas do painel de recursos através de useProjectResourcePanel, portais de navegação através de ProjectContentTools, e fornece apenas seu controle de inspetor direito através de ProjectToolbar.endControl. A conversa usa a mesma faixa esquerda e compositor embutido entre áreas de projeto; tarefas compactas de recurso, conversa e inspetor são mutuamente exclusivas.
EditorNavigationMenu
EditorNavigationMenu reutiliza toda a SidebarNavigation do aplicativo em um painel sobreposto, mantendo permissões e contexto do projeto sem deslocar a área de edição. Idioma e tema ficam na parte inferior; os submenus tratam Escape primeiro. Foco e tela cheia do navegador são independentes. A navegação aguarda os salvamentos em andamento e protege os rascunhos.
WorkspaceNavigationMenu / WorkspacePageHeader
A navegação global usa Command+\ no Mac ou Control+\ no Windows/Linux, inclusive de forma independente no Creator. T e Shift+T continuam controlando o layout do editor. Campos editáveis, composição de texto, repetições e eventos já tratados são ignorados. As dicas do botão e aria-keyshortcuts mostram a combinação; a navegação global não captura mais T isoladamente.
Os espaços autenticados usam PlatformHeader.workspaceActions para compartilhar conta e navegação em todas as larguras. WorkspacePageHeader padroniza títulos e ações. WorkspaceNavigationMenu mostra a barra lateral atual com permissões e contexto; EditorNavigationMenu continua como alias compatível. O Studio mantém sua barra de ferramentas. Os cabeçalhos públicos preservam sua apresentação.
WorkspaceNavigationGuard protege a navegação global com dirty, busy, error e onSave opcional. Só um salvamento confirmado que retorna true permite sair; falhas preservam o rascunho. Language.onBeforeChange(apply) permite a mesma proteção antes de mudar o idioma. Desative os campos durante o salvamento.
A navegação no computador mantém a barra expandida e os ícones e adiciona ocultação automática. A barra e o painel compartilham busca e estado dos grupos. Com ponteiro preciso, passar pela borda abre uma prévia após 300ms e a fecha 320ms após sair; clicar a mantém aberta. Os controles de toque e teclado continuam disponíveis. Dialog usa modal={true} e autoFocus={true} por padrão; a prévia define ambos como false para preservar o foco e a rolagem.
EditorViewControls
Um botão alterna nos dois sentidos: durante a edição mostra Foco; no foco mostra Editar. Clique ou pressione T; E volta diretamente à edição. Em cabeçalhos estreitos, o botão fica visível; prévia, tela cheia e ações adicionais ficam em Mais.
EditorViewControls separa Edição/Foco da tela cheia nativa. A prévia é um controle independente que retorna ao modo anterior; useEditorWorkMode preserva esse modo para saídas personalizadas. Os valores edit/focus/preview continuam válidos. A prévia agora usa um button com aria-pressed em vez de um radio no grupo de modos. A tela cheia exige um clique e inclui navegação e diálogos na raiz do aplicativo; sem suporte, a ação fica oculta.
Language / Appearance
Language e Appearance variant="menu" aceitam layout="row" para mostrar rótulo, valor atual e seta. O layout compacto padrão e a proteção na troca de idioma permanecem inalterados. SiteHeaderCopy.helpResources e contactSupport nomeiam opcionalmente os links de ajuda do espaço de trabalho.
requestWorkspaceNavigation
Páginas com controle da barra lateral omitem o botão de menu adicional no cabeçalho, inclusive nos layouts recolhido e móvel. Editores e páginas sem barra lateral o mantêm. Importe requestWorkspaceNavigation(returnFocusTarget?) e useWorkspaceNavigationState() de @qokit/components/patterns/WorkspaceNavigation: a solicitação alterna o painel registrado e retorna false quando não há um disponível. O elemento opcional recebe o foco ao fechar. Verifique .available antes de mostrar outro acesso. Use o controle existente ou esta API, sem depender da posição DOM do botão removido.
WorkspacePanelReveal
A navegação global usa um ícone de menu; as ferramentas usam ícones direcionais de painel. useWorkspacePanelReveal({ temporary: true }) abre ferramentas temporariamente por clique ou teclado no Foco. toggle(trigger?) e close(true) mantêm o layout e o modo e devolvem o foco. A borda abre a navegação global; as ferramentas respondem junto aos próprios botões. A prévia oculta os controles de painel e oferece retorno explícito ao modo de edição anterior.
EditorViewControls / Modo de exibição
EDITOR_VIEW_SHORTCUTS → Tooltip + aria-keyshortcuts
EditorHeader também gerencia EDITOR_TOOLBAR_SHORTCUTS: Command/Control+S aciona o EditorSaveButton visível, Shift+P abre EditorStatusAction shortcut="publish" e Shift+M abre o menu de ferramentas. Os comandos usam os mesmos controles habilitados dos cliques; publicar exige uma ação explícita no painel. Só o cabeçalho ativo e visível responde. Submenus, diálogos, composição e eventos repetidos bloqueiam os atalhos; em campos editáveis, apenas salvar é permitido. As dicas e aria-keyshortcuts compartilham definições. Um toolsControl personalizado adiciona aria-keyshortcuts={EDITOR_TOOLBAR_SHORTCUTS.tools.aria} ao acionador. ActionMenu.triggerKeyShortcuts adiciona o atributo e a dica sem registrar um comando global.
Os painéis usam Shift+A (adicionar), Shift+L (páginas/camadas), Shift+K (conversa), Shift+C (conteúdo), Shift+D (design) e Shift+G (estilo global). O CMS adiciona Shift+S (configurações), Shift+E (SEO) e Shift+H (histórico), quando disponíveis. Os metadados shortcut em EditorChoiceControl, EditorViewTabs e ActionMenu compartilham dicas. EditorPanelChoiceShortcuts e EditorViewControls.compactActions mantêm as ações nos menus recolhidos, inclusive no celular. EditorPanelShortcuts.commands registra ações existentes sem duplicar controles. Continuam válidas as restrições de ocultação, inert, desabilitação, prévia e sobreposição. Barras móveis não modais do mesmo espaço permitem trocar painéis; menus e diálogos modais bloqueiam os atalhos. Teclas sem modificador mantêm o comportamento atual.
| Modo de exibição | |
|---|---|
E | Editar |
T | Editar ↔ Foco |
V | Prévia / Voltar à edição |
F | Entrar em tela cheia / Sair da tela cheia |
Somente o editor ativo responde. Digitação, composição IME, teclas mantidas e diálogos ou menus secundários abertos não alteram o modo.
PlatformHeader.workspaceNavigation
PlatformHeader.workspaceNavigation posiciona a navegação global antes do logotipo; workspaceActions e editorActions mantêm as ações da conta. Os espaços reutilizam o controle da barra lateral, e os editores posicionam o controle do painel direito antes do avatar. Em telas estreitas, navegação, marca, título e avatar ficam acima das ferramentas e de Salvar. A ordem do DOM acompanha o layout; o efeito fosco sem bordas é preservado.
2026-09-06 - EditorHeader.preview / EditorViewControls.returnView
EditorHeader.preview mostra apenas center como barra de prévia compacta e sem bordas; logotipo, conta, salvar e painéis continuam montados, mas ocultos. Com uma LivePreviewToolbar separada, o cabeçalho do editor pode ser ocultado e EditorViewControls.returnView (edit ou focus) restaura o modo anterior. Mantenha retorno acessível e tela cheia independente; o cabeçalho do site continua visível.
2026-09-06 · Builder / CMS
Builder e CMS compartilham BuilderWorkspace, EditorCatalog e EditorComponentSettings para painéis, ilustrações de inserção e ajustes visuais. As predefinições aplicam os ajustes relacionados juntos e preservam o conteúdo; cada aplicativo gerencia salvar e desfazer. Os controles seguem o tema da plataforma, e o conteúdo segue o tema do site.
Rodapé renderizado no servidor · 2026-09-07
SiteFooterLayout recebe um locale explícito e um copy de um único idioma. Os componentes de servidor renderizam a estrutura compartilhada do rodapé; os controles de tema e idioma e o diálogo QR continuam sendo componentes de cliente. As interfaces existentes SiteFooter e PublicPlatformFooter continuam compatíveis.
import { SiteFooterLayout } from '@qokit/components/patterns/SiteFooter';
<div className="qk-platform-footer-shell">
<SiteFooterLayout locale={locale} copy={footerCopy} />
</div>Resolva os links entre domínios em copy.companyLinks no servidor. Use controls para personalizar o espaço de controles interativos.
EditorHeader.titleControl / FloatingAssistant.presentation
EditorHeader.titleControl e EditorWorkspace.titleControl podem substituir o título pelo menu compartilhado do projeto. Mantenha um title descritivo e a proteção de alterações não salvas na navegação. FloatingAssistant.presentation="embedded" exibe uma região nomeada no painel hospedeiro, sem botão flutuante nem sobreposição de fundo; o padrão continua sendo floating. O hospedeiro controla posição e visibilidade; o assistente mantém a conversa e as permissões.
2026-09-07 · WorkspaceAssembly
WorkspaceAssembly marca cartões de saída e seções de entrada sem criar uma caixa de layout. Quando o contrato exige filhos diretos, aplique workspaceAssemblyAttributes(part, index, phase) ao DOM existente. EditorHeader.assemble e BuilderWorkspacePanels.assemble fornecem as marcas do editor.
Chame await startWorkspaceAssembly(navigate, destinationPathname) somente após criar com sucesso: captura as partes visíveis, navega uma vez e monta o destino ou seu esqueleto em até 720 ms. O destino precisa de uma marca de entrada canvas; useWorkspaceAssemblyPending() mantém a superfície de carregamento montada até concluir as capturas, enquanto dados e código são pré-carregados. Movimento reduzido ou falta de suporte levam à navegação direta. Transições lentas ou interrompidas liberam as capturas e continuam. As marcas não animam edições, recargas ou histórico. O padrão limpa estilos temporários; o host mantém erros, idempotência e carregamento.
2026-09 · Áreas de administração
WorkspacePage e WorkspaceLayout aceitam variant: overview, list, detail, settings ou editor. WorkspaceFormFooter organiza actions, message, tone e busy do aplicativo hospedeiro, que continua responsável por salvar os dados.
Tabelas estreitas (WorkspaceDataTable, AdminDataTable) exibem registros rotulados com seleção, cabeçalhos personalizados e ações. Use mobileLayout="scroll" para matrizes comparativas. WorkspaceFilterToolbar posiciona busca e filtros antes da ordenação e visualização. A barra lateral usa h2; a página usa h1.
2026-09-08 · Task focus
useSidebarTaskFocus(active) oculta temporariamente a navegação durante uma tarefa de concentração. Ao sair, restaura a exibição anterior, salvo alteração explícita do usuário. A ocultação automática não substitui a preferência salva.
Novas referências de API (inglês; tradução pendente)
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.
O adaptador Web também encaminha FloatingAssistantPanel.composerAttachments. O espaço exibe anexos geridos pelo aplicativo dentro do formulário, antes do campo de texto. O aplicativo controla a posição e o envio: soltar prepara o anexo, o sucesso remove apenas o enviado e falhas o preservam para tentar novamente.
Conversa compartilhada (referência em inglês; tradução pendente)
@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 combina InlineNotice para apresentar de forma compacta o status de tarefas, falhas, alternativas e confirmações de salvamento nas conversas. Forneça um title localizado e, opcionalmente, description, tone e action. As duas linhas usam o tamanho de legenda, espaçamento reduzido e superfície transparente; o tom destaca o status, enquanto o texto de apoio permanece discreto. Os valores padrão role="status" e aria-atomic="true" anunciam toda a atualização em conjunto; use role="alert" para falhas que exigem uma ação. O texto escrito pelo assistente permanece em 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.
Novas referências de API (inglês; tradução pendente) · 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,filtersde status,sort,controlsdo domínio, opçõesadvanced,resetcondicional,resultdo recurso esummaryauxiliar.presentation:view, exibecontrolseoptionscomo colunas visíveis e tamanho da página. A personalização do widget de página pertence às ações do cabeçalho da página.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.
Use query.result={{ label, count, total?, locale? }} para o nome do recurso e a quantidade de resultados. WorkspaceResultSummary exibe “Nome · quantidade” e acrescenta “/ total” apenas quando um total confiável sem filtros for diferente; os números seguem o idioma da interface e são isolados para texto bidirecional. Omita result até conhecer a quantidade; zero é válido. Não adicione outra linha de nome e quantidade sobre a mesma lista. AdminFilterBar.result aceita o mesmo objeto. Títulos, seções relevantes, paginação e contagens selecionadas mantêm suas funções; use query.summary para outras unidades, contexto ou atualização.
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.
Referência adicional de API (inglês; tradução pendente) · 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.
Opções de seleção e menu aceitam annotation para adicionar um ponto na cor do tema e incluir seu significado localizado no nome acessível. O acionador de ControlMenu também mostra o ponto da opção ativa; triggerAnnotation: null mantém a marca apenas no menu. Selecionar novamente uma opção habilitada já selecionada chama onReselect. Opções nativas mostram a anotação ao lado do rótulo; hidden exclui um espaço reservado da lista. O host decide o valor anotado e a ação; o controle compartilhado não deduz herança nem grava dados.
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
Coloque CustomizableWidgetLayoutControls nas ações do cabeçalho da página após a ajuda contextual e antes da ação principal, incluindo no mobile. Use copy.customize localizado para nomear a ação explicitamente (por exemplo, "Personalizar widgets"). A mesma entrada apenas com ícone expõe aria-pressed e aria-expanded, e torna-se copy.done durante a edição. customizeButtonRef expõe opcionalmente o gatilho para restauração de foco do host; disabledCustomize desativa a entrada sem alterar sua geometria. Forneça onCollapseToggle e areWidgetsCollapsed apenas para hosts que suportam colapso de widgets; omiti-los renderiza apenas a entrada de personalização.
CustomizableWidgetLibrary possui o cabeçalho comum da biblioteca, ações de reset/fechar, layout de rolagem responsivo, foco inicial do botão fechar e tratamento de Escape. Fechar retorna o foco ao controle invocador quando o foco ainda está dentro da biblioteca; cliques externos mantêm seu foco de destino. Os hosts mantêm definições de widgets, comandos de adicionar/remover/ordenar/redimensionar, persistência e semântica de reset. Slots das classes CMS e Admin permanecem disponíveis para hooks de domínio, mas não devem definir superfícies de biblioteca separadas ou layouts móveis.
17/10/2026 · Gatilhos de ActionMenu ricos
ActionMenu.renderTrigger pode reutilizar um controle rico como SelectableTile. Ele recebe aria-expanded, aria-haspopup, disabled e onClick; espalhe esses valores no gatilho real. O host mantém a semântica de seleção e a aparência do controle. Posicionamento em portal, navegação por teclado do menu, fechamento, retorno do foco e folhas móveis opcionais permanecem sob responsabilidade do ActionMenu. Os gatilhos padrão de botão e ícone não foram alterados.
Controles de raio e intervalo
RangeNumber, de @qokit/components/ui/RangeNumber, combina um controle deslizante nativo com um Input numérico exato. Informe label, value, min, max, os opcionais step e unit, e onChange. Um valor indefinido mostra um traço de valor misto; alterar qualquer entrada define um número dentro dos limites. onCommit permite agrupar alterações contínuas no histórico de desfazer do aplicativo. disabled, navegação por teclado, densidade compacta, RTL e estilos de foco são compartilhados; a persistência pertence ao aplicativo. RangeNumberSkin expõe espaços para raiz, controle deslizante, entrada e unidade.
EditorRadiusControl, de @qokit/components/patterns/EditorRadiusControl, reúne uma prévia ao vivo da forma, quatro entradas de cantos físicos, RangeNumber e formas predefinidas opcionais. value e onChange usam a sintaxe abreviada CSS border-radius; o aplicativo traduz cornerLabels e os nomes das predefinições. Em RTL, a ordem permanece superior esquerdo, superior direito, inferior direito, inferior esquerdo. max limita a edição a pixels delimitados; sua omissão preserva unidades CSS e cantos elípticos. Um raio misto não exibe um único valor até que os quatro cantos sejam ajustados juntos. EditorRadiusControlSkin adapta raiz, diagrama, prévia e predefinições sem alterar estado ou persistência.
2026-10-22 · Abas ativas em telas estreitas
PillTabs aceita a opção scrollActiveTabIntoView, com padrão false. Em abas horizontais, revela o filho direto ativo PillTabLink ou PillTabButton ao selecionar ou redimensionar. Apenas a faixa de abas rola; a posição da página e o foco do teclado permanecem. Há suporte a LTR e RTL com correção imediata, inclusive com movimento reduzido. Abas verticais e chamadas sem a opção mantêm seu comportamento.