Skip to Content
Design

Integrazione dei componenti

Contratto di integrazione pubblico per componenti condivisi, Pattern, Skin e Token di stile di Qokit.

Integrazione dei componenti

Qokit utilizza il modello "struttura condivisa + ricetta Skin". Gli integratori esterni si basano sui contratti semantici e di interazione dei componenti, completando l'adattamento visivo tramite Skin e Token.

2026-10-20 · Azioni indipendenti nelle schede di scelta visiva

Le opzioni di EditorVisualChoiceGroup accettano un accessory facoltativo per menu o editor del nome indipendenti. Il RadioGroup condiviso lo colloca accanto all’etichetta nativa, così la gestione della scheda non ne attiva la selezione. afterOptions inserisce dopo le opzioni un’azione di catalogo separata, come creare una scheda. Persistenza, permessi, validazione e focus dopo sostituzione o rimozione restano all’host. Le opzioni senza accessori mantengono struttura e comportamento.

17-10-2026 · Movimento condiviso del pannello del banco di lavoro

EditorWorkbenchChrome renderizza le corsie di inizio/fine iniettate attraverso BuilderWorkbenchFrame, lo stesso scheletro del pannello utilizzato da Creator e dalla modifica dei contenuti. Gli host forniscono contenuto, visibilità e preferenze di larghezza. Il desktop traccia e l'opacità/traslazione del pannello condividono --qk-sidebar-motion-duration e --qk-sidebar-motion-easing; il trascinamento disattiva le transizioni e il movimento ridotto si applica immediatamente.

I pannelli compressi rimangono montati per mantenere le bozze. Il frame condiviso applica immediatamente inert e aria-hidden, mentre il skin della piattaforma completa l'uscita prima di nascondere la visibilità. I pannelli compatti mantengono la loro geometria overlay durante tutta l'uscita; gli host non devono aggiungere hidden o display: none allo scheletro del pannello. I pannelli peek espliciti mantengono il loro comportamento esistente di rivelazione interattiva. Le scelte dell'intestazione rimangono disponibili negli stati aperto/chiuso; usa EditorPanelChoiceShortcuts.mobileMenu quando le destinazioni del telefono dovrebbero condividere un menu.

17-10-2026 · Predefiniti dell'editor misurati

useWorkspaceResponsiveProfile accetta onWidthChange(width) opzionale, segnalando la stessa larghezza disponibile dell'area di lavoro utilizzata per i profili responsive dopo la deduzione del padding inline. Usa una callback stabile per derivare predefiniti proporzionali senza aggiungere un altro observer. useEditorLayout applica sharedWidths.limits alle preferenze dell'host così come allo storage di larghezza condiviso; readEditorLayout accetta gli stessi limiti come suo quarto argomento opzionale. I chiamanti esistenti mantengono i loro limiti e comportamenti predefiniti.

2026-09-30 · Accessibilità di SelectionToolbar

SelectionToolbar.ariaLabel assegna facoltativamente un nome alla barra come regione. Il conteggio resta un messaggio di stato in tempo reale. Il sistema ospitante fornisce etichette localizzate e può usare actionContent per combinare i componenti condivisi EditorToolGroup e ActionMenu; controlli dei permessi e gestori delle azioni restano al sistema ospitante.

2026-09-10 · Badge di identità dello spazio di lavoro

ProjectSwitcherProject.badge accetta contenuto React facoltativo e non interattivo. Il badge appare accanto al nome di ogni elemento, nella riga del contesto corrente non presente nell’elenco e accanto al nome corrente in un trigger testuale. I trigger con sola icona restano compatti; quelli testuali della piattaforma nascondono il badge alle larghezze da telefono per lasciare spazio al nome dello spazio di lavoro. Il menu aperto continua a mostrarlo. L’host fornisce dati con l’ambito corretto, etichette localizzate e stili di presentazione; omettere il campo mantiene l’aspetto esistente.

2026-09-08 · EmptyState

EmptyState centra icon decorativo facoltativo, title, description facoltativa e action su una superficie trasparente. layout="section" è compatto per impostazione predefinita; layout="workspace" riserva più spazio. Inserire le azioni in action, con un fragment per più pulsanti; il contenitore gestisce spaziatura ed etichette lunghe. Il titolo è h2: usare lo slot title invece di strong. Le classi radice restano; sono supportati skin.vars e style. L’host mantiene testi localizzati, permessi, navigazione e creazione; ricerca ed errori conservano messaggi e azioni propri.

2026-09-08 · SidebarNavigation

SidebarNavigation precarica le route della stessa origine dopo 180 ms di passaggio del mouse o con il focus da tastiera. La navigazione fissa e a comparsa condivide un limite di 8 destinazioni ogni 30 secondi. Il precaricamento si sospende offline, nelle schede nascoste, con Save-Data o 2G; esclude download, link disabilitati, nuove finestre e ancore locali. Navigazione e protezione delle modifiche restano invariate.

2026-09-07 - AccountDropdown / SidebarProfile

AccountDropdown accetta compact e preferences opzionali: la modalità compatta nasconde identificatori e cronologia di creazione; il contenuto esistente resta predefinito. Appearance e Language accettano triggerRole="menuitem" nel menu account. La navigazione da tastiera ripristina il focus e le finestre della lingua annidate gestiscono Esc. SidebarNavigation.searchEnabled è true per impostazione predefinita; usare false per una navigazione breve e fissa. SidebarProfile con href, senza menu, apre la stessa destinazione in entrambe le modalità.

2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace

I moduli condividono la scala tipografica e adattano testi lunghi, mantenendo forme arrotondate e colori del marchio. FormField nomina gruppi: controlId e l’id interna collegano l’etichetta. SearchField ripristina il focus dopo la cancellazione. Segmented e ControlMenu supportano opzioni disabilitate; le voci disabilitate di ActionMenu non hanno link. I pulsanti occupati mantengono dimensioni e indicatore. AdminEntityDialog convalida campi obbligatori, e-mail e JSON, focalizza errori, blocca salvataggi duplicati e conserva gli input dopo un errore. EditorWorkspace offre ref.focusControl(element) per mostrare pannelli nascosti prima di focalizzare. Il movimento ridotto disattiva le transizioni dei controlli. WorkspaceDialog scorre i contenuti lunghi mantenendo visibili titolo e azioni; i dialoghi mobili brevi si adattano al contenuto.

2026-09-07 · WorkspaceLocationSync / ProjectSwitcher

Dopo il cambio di percorso, WorkspaceLocationSync chiude il selettore temporaneo degli spazi e mostra gli strumenti della destinazione. Le preferenze di ricerca e sezione restano invariate. Nome dell’ambito e contesto occupano righe separate; i nomi lunghi nell’intestazione vengono troncati nel pulsante.

2026-09-07 · Navigazione unificata e superfici arrotondate Qokit

WorkspaceNavigationDock riutilizza navigazione e permessi dell’host tramite items, fallback, className e onClickCapture, senza caricare un’altra sessione. Mantiene la preferenza espansa, icone o nascosta; fino a 860px usa il pannello di navigazione. PlatformHeader.leadingContext compare anche in EditorHeader. Restano pulsanti a capsula e superfici arrotondate; si eliminano i bordi ripetuti.

Su desktop, un clic sul menu nasconde la barra laterale o ripristina la sua ultima modalità visibile. Trascinando il menu o il bordo della barra si passa tra nascosta, solo icone ed espansa. Le frecce sinistra/destra seguono la direzione di lettura. Annullare il trascinamento conserva la preferenza salvata; su mobile resta il pannello di navigazione.

Montare WorkspaceLocationSync una volta sotto Suspense nel layout Next. useWorkspaceQueryState(key, defaultValue, validate) restituisce [value, setValue, ready]; useWorkspaceQueryRecord(key, defaults, validators) ripristina solo filtri piatti dichiarati. Non inserire credenziali o bozze negli URL. WorkspacePage ripristina posizioni di scorrimento di sessione limitate; le aree interne usano data-workspace-scroll-region e WorkspaceScrollRestoration. La navigazione nativa annullabile riutilizza la protezione di uscita senza aggiungere cronologia. AdminEntityDialog conserva gli input dopo errori e nuovi rendering; versioni e risultati restano all’host.

La gestione usa ruoli tipografici fissi: titolo pagina 20px/650, sezione 16px/600, testo e navigazione 14px, etichette 13px, note 12px. --qk-workspace-body-ink e --qk-workspace-active-ink derivano dai colori esistenti.

I pulsanti principali arrotondati mantengono il blu del Logo #4695D8 e usano testo, icone e indicatori bianchi in entrambi i temi. Il passaggio del mouse mantiene il leggero schiarimento. I pulsanti secondari e pericolosi conservano i colori semantici.

Menu a discesa e selettori dello spazio condividono --menu-option-font-size (14px) e --menu-option-font-weight (500), con interlinea 1.45; le opzioni selezionate usano 600 e i metadati 12px/400. WorkspaceNavigationDock precarica le destinazioni della stessa origine al passaggio del mouse o al focus da tastiera, con deduplicazione limitata. Restano attive le protezioni in uscita e le rotte host.

2026-09-07 - ColumnLayout

ColumnLayout riempie la finestra di gestione con navigazione ancorata, scorrimento indipendente e barra della pagina fissa. WorkspacePage usa sezioni piatte e Token di raggio condivisi. Fino a 860px, la navigazione resta un pannello, non interattivo quando chiuso. Proprietà e logica applicativa non cambiano. Eliminate i margini esterni duplicati e limitate la larghezza all’interno dei moduli.

Punti di ingresso

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';
Punto di ingressoUtilizzo
@qokit/components/uiComponenti base come Button, Card, Dialog, Menu, Pill
@qokit/components/patternsCombinazioni come Header, Footer, workspace, tabelle, risorse e assistente AI
@qokit/components/skins/platformRicette visive per piattaforma e workspace
@qokit/components/skins/adminRicetta visiva Admin
@qokit/components/skins/siteGenerazione della ricetta visiva del sito

Confini delle responsabilità pubbliche

PromptPanel accetta l'attributo referenceReader opzionale e l'attributo referenceCopy per la localizzazione. Il reader restituisce contentExcerpt estratti e i marker truncated tramite le funzioni asincrone file(File, AbortSignal) e website(url, AbortSignal); l'autenticazione e l'accesso API sono a carico dell'host. Il componente gestisce lettura, anteprima, ritentativo e rimozione; se un URL valido non ha testo segnaposto, referenceCopy.websitePrompt completa la richiesta, mentre in caso di formato errato viene usato referenceCopy.errors.url e la lettura viene bloccata. Se l'invio avviene mentre l'URL non è ancora stato letto o è in fase di lettura, si attende il contenuto più recente e si invia una sola volta; modifiche all'input o fallimenti della lettura annullano le operazioni in attesa di invio, e il ritentativo non ripristina i vecchi invii. I file devono essere pronti prima dell'invio. Gli URL completi vengono letti automaticamente su incolla, perdita di focus o pressione di Enter; anche l'URL iniziale viene letto e riutilizza i risultati in corso o completati; in caso di fallimento viene offerto un ritentativo esplicito. La modifica o la rimozione di un URL annulla la lettura precedente e cancella i risultati. Se non viene fornito un reader, si procede con l'invio nativo senza elaborazione asincrona dei riferimenti.

L'ingestione dei riferimenti è stata aggiunta a settembre 2026 come funzionalità opzionale e retrocompatibile del componente.

La struttura dei componenti garantisce:

  • Tag DOM e semantica;
  • Comportamento ARIA, tastiera, focus e disabled;
  • Stato e interazioni di base;
  • Class predefinite stabili;
  • Slot Skin nominati.

Lo Skin può:

  • Aggiungere class agli slot root, header, body, item, action, ecc.;
  • Trasmettere variabili CSS tramite vars;
  • Utilizzare i toggle di tono, layer o adattamento visivo già pubblicati dal componente.

Lo Skin non deve richiedere dati, modificare il DOM, contenere regole di business o aggirare i comportamenti di accessibilità.

Contenuto degli elementi generati

I blocchi personalizzati generati continuano a utilizzare gli elementi html-* registrati in Schema v2, senza HTML eseguibile o nuovi tipi di blocco. Da settembre 2026, @qokit/site-schema fornisce bindSiteModuleContent, updateSiteModuleBoundContent e forkSiteModuleContentBindings per il binding dei contenuti linguistici. I percorsi dei contenuti sono salvati nei moduli, il testo per i visitatori nella mappatura dei contenuti linguistici, e gli aggiornamenti seguono le transazioni di annullamento e salvataggio; quando si duplicano o si spostano elementi tra blocchi, è necessario derivare il binding per evitare di alterare l'origine.

Il campo extensionRequirements opzionale registra i requisiti runtime non risolti e non costituisce un manifesto di installazione né una concessione di permessi. createSiteExtensionHandoff esporta le richieste di sviluppo v1 non eseguibili; prima di pubblicare un sito eseguibile, questi requisiti devono essere risolti o esplicitamente esclusi dopo revisione.

Controlli di form

I form condivisi utilizzano FormField per associare etichette, descrizioni, metadati obbligatori, errori e ID dei controlli. I controlli di testo usano Input, i contenuti multiriga usano Textarea, i controlli di selezione usano Checkbox, RadioGroup e Switch; i componenti esistenti Select e SearchField utilizzano lo stesso contratto di dimensione e stato.

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 etichette, descrizioni ed errori all'unico controllo figlio tramite id, aria-describedby, aria-invalid e required. Non avvolgere ulteriormente i controlli condivisi con <label>.

Input, Textarea, Select e SearchField supportano tre dimensioni tramite sm, md e lg, corrispondenti a 40px, 44px e 48px. I controlli a riga singola usano di default la forma pill; Textarea usa sempre gli angoli arrotondati condivisi per il multiriga. Ogni stato di interazione ed errore deriva dai token condivisi.

Durante la migrazione è ancora possibile utilizzare il vecchio contratto .qk-field; le nuove integrazioni dovrebbero usare componenti condivisi e slot skin denominati.

Selezione in elenco

Da settembre 2026, gli elenchi possono utilizzare useWorkspaceSelectionMode({ enabled, resetKey, onClear }) in combinazione con WorkspaceFilterToolbar.selection. Questo Hook è inizialmente inattivo, si resetta quando cambiano ambito o permessi, e distingue tra svuotare gli ID selezionati e uscire dalla modalità batch; la chiave dell'ambito dovrebbe includere insieme, lingua, paginazione e filtri.

Passa WorkspaceDataTable.selection solo quando la modalità batch è attiva; griglie e controlli di selezione su mobile usano la stessa modalità. La toolbar gestisce le azioni di selezione generiche, mentre l'utilizzatore fornisce testo localizzato, ID opzionali e azioni di dominio verificate per i permessi. Il campo actionContent opzionale può trasportare semantica ARIA aggiuntiva, ma non sostituisce i controlli generici o le conferme. Gli elenchi in sola lettura non mostrano la modalità batch; i selettori di file e la revisione delle proposte mantengono la propria semantica.

Queste nuove funzionalità sono opzionali e retrocompatibili; la selezione nelle tabelle rimane sotto il controllo esplicito dell'utilizzatore.

Card delle metriche

Nuovi riferimenti API (inglese; traduzione in attesa) · 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" />;

Logo mostra un’immagine statica per impostazione predefinita. motion="breathe" ne riserva lo spazio mentre è nascosto e lo rivela una volta con un’animazione di respiro di 4,8 secondi quando la pagina è caricata e almeno metà è visibile. Intestazione e piè di pagina non aggiungono attese. motionVisibilityDelayMs consente un tempo aggiuntivo di visibilità continua, pari a zero per impostazione predefinita. motionOnceKey condivide il registro di riproduzione tra montaggi nello stesso documento; intestazione e piè di pagina usano chiavi separate. Navigazione, cambio tema e ritorno dello scorrimento non ripetono l’animazione; un ricaricamento completo la reimposta. Movimento ridotto, JavaScript disabilitato o osservazione della visibilità non disponibile mostrano il logo statico. motion="reveal" resta un alias.

PlatformHeader.autoHideOnScroll è false per impostazione predefinita; PublicPlatformHeader lo abilita. L’intestazione si nasconde scorrendo verso il basso e ritorna risalendo o vicino all’inizio. Menu aperti e focus al suo interno la mantengono visibile. Le intestazioni di area di lavoro ed editor restano fisse.

PlatformHeader è la struttura dell'intestazione senza stato di business. PublicPlatformHeader combina su di essa ingressi del brand, navigazione pubblica, lingua, tema, accesso, "Prova ora" e menu mobile; la piattaforma in stato anonimo e il sito della documentazione riutilizzano direttamente questa combinazione.

La navigazione pubblica viene generata uniformemente tramite buildPublicHeaderNavItems(copy, links) per "Risorse / Prezzi / Notizie". L'integratore analizza solo gli URL interni dell'applicazione corrente, del sito della documentazione e della piattaforma, senza ridefinire l'ordine o il testo del menu. Anche l'intestazione della piattaforma dopo l'accesso utilizza la stessa funzione di generazione.

<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'
  }}
/>

La struttura sottostante navItems supporta ancora link, scroll e menu. menu sul desktop supporta la chiusura tramite click, tastiera, Escape e click esterno; su mobile MobileHeaderMenu si espande in gruppi di link.

SiteFooter è la struttura del Footer; la piattaforma e il sito della documentazione utilizzano PublicPlatformFooter per combinare uniformemente lo Shell esterno, l'ingresso del brand, i link, i controlli del tema e della lingua. L'integrazione cross-domain converte i link relativi della piattaforma in indirizzi assoluti tramite resolveCompanyHref.

<PublicPlatformFooter
  brandHref="https://qokit.com"
  copy={footerCopy}
  resolveCompanyHref={(href) => `https://qokit.com${href}`}
/>

Le applicazioni di business non devono duplicare il DOM di Header/Footer o l'array di navigazione pubblica; per diverse rappresentazioni visive utilizzare PlatformHeaderSkin, SiteFooterSkin o lo Skin della piattaforma corrispondente.

Strategia di compatibilità

  • L'aggiunta di proprietà opzionali e slot Skin è una modifica backward-compatible;
  • La rimozione di proprietà, la modifica della semantica predefinita o la modifica del comportamento DOM/tastiera sono modifiche distruttive;
  • Le modifiche distruttive devono essere registrate nel Changelog e fornire esempi di migrazione;
  • Non fare affidamento su class interne, directory o strutture di routing non pubblicate;
  • Quando due o più punti di integrazione richiedono la stessa sovrascrittura, questa dovrebbe essere promossa a Skin o Token pubblico.

Modifica a schermo intero

EditorWorkspace combina una finestra a schermo intero, la gestione del focus e pannelli adattivi. dirty conferma se scartare le modifiche, busy impedisce la chiusura durante il salvataggio e onSave gestisce Ctrl/Cmd+S. Permessi, dati, salvataggio e pubblicazione spettano all’applicazione.

view / onViewChange passano tra edit, focus e preview senza sostituire l’editor. preview fornisce l’anteprima; previewPanel riutilizza un pannello. layout supporta writing, structure e canvas. storageKey ricorda larghezze e pannelli chiusi, mai il documento.

onSaveAndClose restituisce true dopo il salvataggio confermato, false in caso di errore, handled se l’applicazione ha già navigato o pending se la validazione richiede una decisione. Gli errori mantengono aperto l’editor. Usare closeBehavior="collapse" solo se l’applicazione conserva la bozza. EditorSaveStatus mostra stati confermati. EditorViewControls, EditorLeaveDialog e useEditorLayout sono componibili anche negli spazi esistenti.

Migrazione tastiera: Segmented ha un solo arresto Tab e usa frecce / Home / End. Dialog rispetta Escape gestito da una sovrapposizione figlia; poi l’editor esce dalla concentrazione o dall’anteprima prima di chiudersi. LivePreviewToolbar.exitControl accetta i controlli condivisi. Salvataggio, pubblicazione e permessi restano gestiti dall’applicazione.

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 sposta il comando della barra laterale nell’intestazione. Usa un solo slot con una barra laterale sinistra. SidebarNavigation mantiene stato, scorciatoie e pannello mobile; senza slot conserva i controlli originali. Il pulsante nell’intestazione chiude anche il pannello mobile; alla chiusura il focus torna allo stesso pulsante.

EditorHeader

EditorHeader mantiene logo, account e menu globale nell’editor attivo. startControl e endControl controllano i pannelli laterali, center le viste e actions il salvataggio. PlatformHeader.editorActions riutilizza navigazione responsive, lingua e tema. onNavigate deve gestire le modifiche non salvate prima di eseguire il callback. Su schermi stretti, l’intestazione usa due righe; i sottomenu gestiscono Escape per primi.

WorkspaceHeaderPortal.startControl e endControl posizionano i toggle del pannello della pagina gestita negli slot corrispondenti dell'host. Gli host espongono startTarget e endTarget opzionali insieme a titolo, stato e azioni. La libreria Files e lo spazio di lavoro a singola risorsa utilizzano workAreaControls; l'anteprima delle risorse mantiene l'intestazione completa in modo che la sua identità, l'azione di ritorno e le destinazioni del pannello rimangano disponibili. ProjectWorkspace possiede le scelte condivise di navigazione/conversazione a sinistra per Contenuti e Files. Files registra le sue dimensioni ricordate del pannello delle risorse attraverso useProjectResourcePanel, porta la navigazione attraverso ProjectContentTools, e fornisce solo il suo controllo ispettivo destro attraverso ProjectToolbar.endControl. La conversazione utilizza la stessa corsia sinistra e il composer incorporato attraverso le aree di progetto; le attività di risorse compatte, conversazione e ispettive sono mutualmente esclusive.

EditorNavigationMenu

EditorNavigationMenu riutilizza l’intera SidebarNavigation dell’host in un pannello sovrapposto, mantenendo permessi e contesto del progetto senza spostare l’area di lavoro. Lingua e tema restano in basso; i sottomenu gestiscono Escape per primi. Concentrazione e schermo intero del browser sono indipendenti. La navigazione attende i salvataggi in corso e protegge le bozze.

WorkspaceNavigationMenu / WorkspacePageHeader

La navigazione globale usa Command+\ su Mac o Control+\ su Windows/Linux, anche in modo indipendente dentro Creator. T e Shift+T mantengono le funzioni di layout dell’editor. Campi modificabili, composizione del testo, ripetizioni ed eventi già gestiti vengono ignorati. I suggerimenti del pulsante e aria-keyshortcuts mostrano la combinazione; la navigazione globale non intercetta più T da solo.

Gli spazi autenticati usano PlatformHeader.workspaceActions per condividere account e navigazione a ogni larghezza. WorkspacePageHeader uniforma titoli e azioni. WorkspaceNavigationMenu mostra la barra laterale corrente con permessi e contesto; EditorNavigationMenu resta un alias compatibile. Studio mantiene la propria barra degli strumenti. Le intestazioni pubbliche conservano la loro presentazione.

WorkspaceNavigationGuard protegge la navigazione globale con dirty, busy, error e onSave facoltativo. Solo un salvataggio confermato che restituisce true consente di uscire; gli errori conservano la bozza. Language.onBeforeChange(apply) permette la stessa protezione prima di cambiare lingua. Disabilita i campi durante il salvataggio.

La navigazione desktop mantiene la barra espansa e le icone e aggiunge la scomparsa automatica. Barra e pannello condividono ricerca e gruppi aperti. Un puntatore preciso sul bordo apre un’anteprima dopo 300ms e la chiude 320ms dopo l’uscita; un clic la mantiene aperta. Restano disponibili i controlli touch e da tastiera. Dialog usa normalmente modal={true} e autoFocus={true}; l’anteprima imposta entrambi su false per mantenere focus e scorrimento.

EditorViewControls

Un pulsante cambia in entrambe le direzioni: durante la modifica mostra Concentrazione, durante la concentrazione Modifica. Fai clic o premi T; E torna direttamente alla modifica. Nelle intestazioni strette il pulsante resta visibile; anteprima, schermo intero e azioni aggiuntive sono in Altro.

EditorViewControls separa Modifica/Concentrazione dallo schermo intero nativo. L’anteprima è un comando indipendente che ritorna alla modalità precedente; useEditorWorkMode conserva tale modalità per le azioni di uscita personalizzate. I valori edit/focus/preview restano validi. L’anteprima usa ora un button con aria-pressed anziché un radio nel gruppo delle modalità. Lo schermo intero richiede un clic e include navigazione e finestre nella radice dell’applicazione; il comando viene nascosto se non supportato.

Language / Appearance

Language e Appearance variant="menu" supportano layout="row" per mostrare etichetta, valore attuale e freccia. Il layout compatto predefinito e la protezione del cambio lingua restano invariati. SiteHeaderCopy.helpResources e contactSupport definiscono facoltativamente i collegamenti di aiuto dello spazio di lavoro.

requestWorkspaceNavigation

Le pagine con un comando per la barra laterale omettono il pulsante di menu aggiuntivo nell’intestazione, anche nei layout compressi e mobili. Gli editor e le pagine senza barra laterale lo mantengono. Importare requestWorkspaceNavigation(returnFocusTarget?) e useWorkspaceNavigationState() da @qokit/components/patterns/WorkspaceNavigation: la richiesta alterna il pannello registrato e restituisce false se assente. L’elemento facoltativo riceve il focus alla chiusura. Controllare .available prima di mostrare un altro accesso. Usare il comando esistente o questa API anziché la posizione DOM del pulsante rimosso.

WorkspacePanelReveal

La navigazione globale usa un’icona di menu, gli strumenti icone di pannello direzionali. useWorkspacePanelReveal({ temporary: true }) apre temporaneamente gli strumenti con clic o tastiera in Concentrazione. toggle(trigger?) e close(true) mantengono layout e modalità e ripristinano il focus. Il bordo apre la navigazione globale; gli strumenti rispondono presso i propri pulsanti. L’anteprima nasconde i comandi dei pannelli e offre un ritorno esplicito alla modalità di modifica precedente.

EditorViewControls / Modalità di visualizzazione

EDITOR_VIEW_SHORTCUTS → Tooltip + aria-keyshortcuts

EditorHeader gestisce anche EDITOR_TOOLBAR_SHORTCUTS: Command/Control+S attiva il EditorSaveButton visibile, Shift+P apre EditorStatusAction shortcut="publish" e Shift+M apre il menu degli strumenti. I comandi usano gli stessi controlli abilitati dei clic; pubblicare richiede un’azione esplicita nel pannello. Risponde solo l’intestazione attiva e visibile. Sottomenu, finestre di dialogo, composizione e ripetizioni bloccano le scorciatoie; nei campi modificabili è consentito solo salvare. Suggerimenti e aria-keyshortcuts condividono le definizioni. Un toolsControl personalizzato imposta aria-keyshortcuts={EDITOR_TOOLBAR_SHORTCUTS.tools.aria} sul pulsante. ActionMenu.triggerKeyShortcuts aggiunge attributo e suggerimento senza registrare comandi globali.

I pannelli usano Shift+A (aggiungi), Shift+L (pagine/livelli), Shift+K (conversazione), Shift+C (contenuto), Shift+D (design), Shift+G (stile globale). CMS aggiunge Shift+S (impostazioni), Shift+E (SEO), Shift+H (cronologia), se disponibili. I metadati shortcut di EditorChoiceControl, EditorViewTabs e ActionMenu condividono i suggerimenti. EditorPanelChoiceShortcuts e EditorViewControls.compactActions mantengono le azioni nei menu compressi, anche sui telefoni. EditorPanelShortcuts.commands registra azioni esistenti senza duplicare controlli. Restano i vincoli nascosto, inert, disabilitato, anteprima e sovrapposizioni. Le barre mobili non modali dello stesso spazio consentono di cambiare pannello; menu e dialoghi modali bloccano le scorciatoie. I tasti senza modificatori mantengono il comportamento esistente.

Modalità di visualizzazione
EModifica
TModifica ↔ Concentrazione
VAnteprima / Torna alla modifica
FApri schermo intero / Esci da schermo intero

Risponde solo l’editor attivo. La digitazione, la composizione IME, i tasti tenuti premuti e le finestre di dialogo o i menu secondari aperti non cambiano modalità.

PlatformHeader.workspaceNavigation

PlatformHeader.workspaceNavigation colloca la navigazione globale prima del logo; workspaceActions ed editorActions mantengono le azioni dell’account. Gli spazi riutilizzano il pulsante della barra laterale e gli editor collocano il pulsante del pannello destro prima dell’avatar. Sugli schermi stretti, navigazione, marchio, titolo e avatar precedono la riga degli strumenti e di Salva. L’ordine DOM segue la disposizione; resta l’effetto vetro satinato senza bordi.

2026-09-06 - EditorHeader.preview / EditorViewControls.returnView

EditorHeader.preview mostra solo center come barra di anteprima compatta senza bordi; logo, account, salvataggio e pannelli restano montati ma nascosti. Con una LivePreviewToolbar separata è possibile nascondere l’intestazione dell’editor e usare EditorViewControls.returnView (edit o focus) per ripristinare la modalità precedente. Mantenere ritorno accessibile e schermo intero indipendente; l’intestazione del sito resta visibile.

2026-09-06 · Builder / CMS

Builder e CMS condividono BuilderWorkspace, EditorCatalog ed EditorComponentSettings per pannelli, illustrazioni di inserimento e impostazioni visive. I preset applicano insieme le impostazioni collegate e preservano i contenuti; ogni applicazione gestisce salvataggio e annullamento. I controlli seguono il tema della piattaforma e i contenuti quello del sito.

SiteFooterLayout riceve un locale esplicito e un copy in una sola lingua. I componenti server renderizzano la struttura condivisa del footer; i controlli per tema e lingua e la finestra QR restano componenti client. Le interfacce esistenti SiteFooter e PublicPlatformFooter continuano a essere supportate.

import { SiteFooterLayout } from '@qokit/components/patterns/SiteFooter';

<div className="qk-platform-footer-shell">
  <SiteFooterLayout locale={locale} copy={footerCopy} />
</div>

Risolvi i collegamenti tra domini in copy.companyLinks sul server. Usa controls per personalizzare lo spazio dei controlli interattivi.

EditorHeader.titleControl / FloatingAssistant.presentation

EditorHeader.titleControl e EditorWorkspace.titleControl possono sostituire il titolo con il menu condiviso del progetto. Mantenere un title descrittivo e la protezione delle modifiche non salvate durante la navigazione. FloatingAssistant.presentation="embedded" mostra una regione denominata nel pannello ospitante senza pulsante flottante o sfondo sovrapposto; il valore predefinito resta floating. Il contenitore gestisce posizione e visibilità; l’assistente conserva conversazione e autorizzazioni.

2026-09-07 · WorkspaceAssembly

WorkspaceAssembly contrassegna schede in uscita e sezioni in entrata senza aggiungere un contenitore. Per i vincoli sui figli diretti, applica workspaceAssemblyAttributes(part, index, phase) al DOM esistente. EditorHeader.assemble e BuilderWorkspacePanels.assemble forniscono i marcatori dell’editor.

Chiama await startWorkspaceAssembly(navigate, destinationPathname) solo dopo la creazione riuscita: acquisisce le parti visibili, naviga una volta e compone la destinazione o lo scheletro corrispondente entro 720 ms. La destinazione richiede un marcatore in entrata canvas; useWorkspaceAssemblyPending() mantiene montato il caricamento fino al completamento delle acquisizioni, precaricando dati e codice. Movimento ridotto o browser non supportati usano la navigazione diretta. Le transizioni lente o interrotte rilasciano le acquisizioni e proseguono. I marcatori non animano modifiche, ricaricamenti o cronologia. Il pattern pulisce gli stili temporanei; l’host gestisce errori, idempotenza e caricamento.

2026-09 · Aree di gestione

WorkspacePage e WorkspaceLayout accettano variant: overview, list, detail, settings o editor. WorkspaceFormFooter dispone actions, message, tone e busy forniti dall’host; il salvataggio resta all’host.

Le tabelle strette (WorkspaceDataTable, AdminDataTable) mostrano record etichettati con selezione, intestazioni personalizzate e azioni. Usare mobileLayout="scroll" per matrici comparative. WorkspaceFilterToolbar dispone ricerca e filtri prima di ordinamento e vista. La barra laterale usa h2; la pagina usa h1.

2026-09-08 · Task focus

useSidebarTaskFocus(active) nasconde temporaneamente la navigazione durante un’attività che richiede concentrazione. All’uscita ripristina la vista precedente, salvo una modifica esplicita dell’utente. La preferenza salvata resta invariata.

Nuovi riferimenti API (inglese; traduzione in attesa)

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.

L’adattatore Web inoltra anche FloatingAssistantPanel.composerAttachments. Lo slot mostra gli allegati gestiti dall’host nel modulo del messaggio, prima del campo di testo. L’host controlla posizione e invio: il rilascio prepara l’allegato, il successo rimuove solo quello inviato e gli errori lo conservano per riprovare.

Conversazione condivisa (riferimento inglese; traduzione in attesa)

@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 compone InlineNotice per mostrare in modo compatto stati delle attività, errori, soluzioni alternative e conferme di salvataggio nelle conversazioni. Fornisci un title localizzato e, facoltativamente, description, tone e action. Entrambe le righe usano il corpo della didascalia, una spaziatura ridotta e una superficie trasparente; il tono evidenzia lo stato, mentre il testo di supporto resta attenuato. I valori predefiniti role="status" e aria-atomic="true" annunciano insieme l’intero aggiornamento; usa role="alert" per gli errori che richiedono un intervento. Il testo scritto dall’assistente rimane in 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.

Nuovi riferimenti API (inglese; traduzione in attesa) · 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 di stato, sort, controls di dominio, opzioni advanced, reset condizionale, result della risorsa e summary ausiliario.
  • presentation: view, visualizza controls e options come colonne visibili e dimensione della pagina. La personalizzazione del widget della pagina appartiene alle azioni dell'intestazione della pagina.
  • actions: persistent operations, followed by the optional selection control at the logical end. Use ToolbarButtons with icon and localized compactLabel for 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.

Usare query.result={{ label, count, total?, locale? }} per il nome della risorsa e il numero di risultati. WorkspaceResultSummary mostra “Nome · numero” e aggiunge “/ totale” solo se un totale affidabile senza filtri è diverso; formatta i numeri secondo la lingua UI e li isola nel testo bidirezionale. Omettere result finché il numero non è noto; zero è valido. Non aggiungere un’altra riga di nome e numero sopra lo stesso elenco. AdminFilterBar.result accetta lo stesso oggetto. Titoli, sezioni significative, paginazione e conteggi selezionati mantengono i propri ruoli; usare query.summary per altre unità, contesto o aggiornamento.

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.

Riferimento API aggiuntivo (inglese, traduzione in attesa) · 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.

Le opzioni di selezione e menu supportano annotation per aggiungere un punto nel colore del tema e includerne il significato localizzato nel nome accessibile. Anche il pulsante di ControlMenu mostra il punto dell’opzione attiva; triggerAnnotation: null lo mantiene solo nel menu. Scegliere di nuovo un’opzione abilitata già selezionata richiama onReselect. Le opzioni native mostrano l’annotazione accanto all’etichetta; hidden esclude un segnaposto dall’elenco. L’host decide il valore annotato e l’azione; il controllo condiviso non deduce l’ereditarietà né scrive dati.

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

Posiziona CustomizableWidgetLayoutControls nelle azioni dell'intestazione della pagina dopo l'aiuto contestuale e prima dell'azione primaria, incluso su mobile. Usa copy.customize localizzato per nominare esplicitamente l'azione (ad esempio, "Personalizza widget"). Lo stesso punto di accesso solo icona espone aria-pressed e aria-expanded, e diventa copy.done durante la modifica. customizeButtonRef espone opzionalmente il trigger per il ripristino dello stato attivo dell'host; disabledCustomize disabilita il punto di accesso senza cambiarne la geometria. Fornisci onCollapseToggle e areWidgetsCollapsed solo per gli host che supportano la compressione dei widget; omettendoli viene reso solo il punto di accesso alla personalizzazione.

CustomizableWidgetLibrary possiede l'intestazione comune della libreria, le azioni di reset/chiusura, il layout di scorrimento responsive, lo stato attivo iniziale del pulsante di chiusura e la gestione di Escape. La chiusura restituisce lo stato attivo al controllo invocante quando lo stato attivo è ancora all'interno della libreria; i clic esterni mantengono la loro destinazione dello stato attivo. Gli host mantengono le definizioni dei widget, i comandi aggiungi/rimuovi/ordina/ridimensiona, la persistenza e la semantica di reset. Gli slot di classe CMS e Admin rimangono disponibili per hook di dominio, ma non devono definire superfici della libreria separate o layout mobili.

2026-10-17 · Trigger di ActionMenu ricchi

ActionMenu.renderTrigger può riutilizzare un controllo ricco come SelectableTile. Riceve aria-expanded, aria-haspopup, disabled e onClick; espandili sul trigger effettivo. L'host mantiene la semantica di selezione e l'aspetto del controllo. Il posizionamento del portale, la navigazione da tastiera del menu, la chiusura, il ritorno del focus e i fogli mobili opzionali rimangono di proprietà di ActionMenu. I trigger predefiniti per pulsante e icona sono invariati.

Controlli di raggio e intervallo

RangeNumber di @qokit/components/ui/RangeNumber abbina un cursore nativo a un Input numerico preciso. Fornire label, value, min, max, gli opzionali step e unit, e onChange. Un valore non definito mostra un trattino per valori misti; modificare un ingresso imposta un numero entro i limiti. onCommit consente all’applicazione di raggruppare modifiche continue nella cronologia di annullamento. disabled, navigazione da tastiera, densità compatta, RTL e stili di messa a fuoco sono condivisi; la persistenza resta all’applicazione. RangeNumberSkin espone slot per radice, cursore, ingresso e unità.

EditorRadiusControl di @qokit/components/patterns/EditorRadiusControl combina un’anteprima della forma in tempo reale, quattro ingressi per gli angoli fisici, RangeNumber e forme predefinite opzionali. value e onChange usano la sintassi abbreviata CSS border-radius; l’applicazione traduce cornerLabels e i nomi delle preimpostazioni. In RTL l’ordine resta alto sinistra, alto destra, basso destra, basso sinistra. max limita la modifica a pixel delimitati; ometterlo conserva unità CSS e angoli ellittici. Un raggio misto non mostra un unico numero finché i quattro angoli non vengono impostati insieme. EditorRadiusControlSkin adatta radice, diagramma, anteprima e preimpostazioni senza cambiare stato o persistenza.

2026-10-22 · Schede attive sugli schermi stretti

PillTabs accetta l’opzione scrollActiveTabIntoView, con valore predefinito false. Nelle schede orizzontali rende visibile il figlio diretto attivo PillTabLink o PillTabButton durante selezione e ridimensionamento. Scorre solo la barra delle schede; posizione della pagina e focus della tastiera restano invariati. Supporta LTR e RTL con correzione immediata, anche con movimento ridotto. Schede verticali e chiamate senza l’opzione conservano il comportamento.

In questa pagina

Integrazione dei componenti2026-10-20 · Azioni indipendenti nelle schede di scelta visiva17-10-2026 · Movimento condiviso del pannello del banco di lavoro17-10-2026 · Predefiniti dell'editor misurati2026-09-30 · Accessibilità di SelectionToolbar2026-09-10 · Badge di identità dello spazio di lavoro2026-09-08 · EmptyState2026-09-08 · SidebarNavigation2026-09-07 - AccountDropdown / SidebarProfile2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace2026-09-07 · WorkspaceLocationSync / ProjectSwitcher2026-09-07 · Navigazione unificata e superfici arrotondate Qokit2026-09-07 - ColumnLayoutPunti di ingressoConfini delle responsabilità pubblicheContenuto degli elementi generatiControlli di formSelezione in elencoCard delle metricheNuovi riferimenti API (inglese; traduzione in attesa) · 2026-10Intestazione e Footer della piattaformaStrategia di compatibilitàModifica a schermo interoSidebarToggleSlotEditorHeaderEditorNavigationMenuWorkspaceNavigationMenu / WorkspacePageHeaderEditorViewControlsLanguage / AppearancerequestWorkspaceNavigationWorkspacePanelRevealEditorViewControls / Modalità di visualizzazionePlatformHeader.workspaceNavigation2026-09-06 - EditorHeader.preview / EditorViewControls.returnView2026-09-06 · Builder / CMSFooter renderizzato sul server · 2026-09-07EditorHeader.titleControl / FloatingAssistant.presentation2026-09-07 · WorkspaceAssembly2026-09 · Aree di gestione2026-09-08 · Task focusNuovi riferimenti API (inglese; traduzione in attesa)Conversazione condivisa (riferimento inglese; traduzione in attesa)Nuovi riferimenti API (inglese; traduzione in attesa) · 2026-102026-10-10 · Pagination dot display2026-10-10 · ActionMenu search header2026-10-09 · Inline ColorPicker2026-10-07 · WorkspacePanelGrid2026-10-08 · Shared list toolbar groups2026-10-10 · EditorItemDisclosureRiferimento API aggiuntivo (inglese, traduzione in attesa) · 2026-102026-10-15 · Shared inspector choices2026-10-15 · Responsive workspace tables2026-10-14 · Independent editor panelsEditor workspace integration2026-10-15 · EditorControlGroup title actions2026-10-14 · Management groups and summaries2026-10-14 · Management content panels and disclosuresCustomizableWidgetLayoutControls / CustomizableWidgetLibrary2026-10-17 · Trigger di ActionMenu ricchiControlli di raggio e intervallo2026-10-22 · Schede attive sugli schermi stretti