Intégration des composants
Contrat d'intégration public pour les composants partagés, Patterns, Skin et Tokens de style de Qokit.
Intégration des composants
Qokit utilise un modèle « structure partagée + recette Skin ». Les intégrateurs externes dépendent du contrat sémantique et d'interaction des composants, et réalisent l'adaptation visuelle via les Skin et les Tokens.
2026-10-20 · Actions indépendantes des cartes de choix visuel
Les options de EditorVisualChoiceGroup acceptent un accessory facultatif pour des menus ou éditeurs de nom indépendants. Le RadioGroup partagé le place à côté du libellé natif afin que gérer une carte ne sélectionne pas son bouton radio. afterOptions ajoute une action de catalogue distincte, comme créer une carte, après les choix. L’hôte garde la persistance, les permissions, la validation et le focus après remplacement ou suppression. Sans accessoire, structure et comportement restent identiques.
2026-10-17 · Mouvement de panneau de poste de travail partagé
EditorWorkbenchChrome rend les voies injectées de début/fin via BuilderWorkbenchFrame, le même squelette de panneau utilisé par Creator et l'édition de contenu. Les hôtes fournissent le contenu, la visibilité et les préférences de largeur. Le bureau suit et l'opacité/translucidité du panneau partagent --qk-sidebar-motion-duration et --qk-sidebar-motion-easing ; le glissement désactive les transitions et la réduction du mouvement s'applique immédiatement.
Les panneaux réduits restent montés pour conserver les brouillons. Le cadre partagé applique immédiatement inert et aria-hidden, tandis que le thème de la plateforme complète la sortie avant de masquer la visibilité. Les panneaux compacts conservent leur géométrie de superposition tout au long de la sortie ; les hôtes ne doivent pas ajouter hidden ou display: none au shell du panneau. Les panneaux peek explicites conservent leur comportement de révélation interactive existant. Les choix d'en-tête restent disponibles dans les états ouvert/fermé ; utilisez EditorPanelChoiceShortcuts.mobileMenu lorsque les destinations téléphoniques doivent partager un menu.
2026-10-17 · Valeurs par défaut de l'éditeur mesuré
useWorkspaceResponsiveProfile accepte onWidthChange(width) optionnel, signalant la même largeur de zone de travail disponible utilisée pour les profils responsifs après déduction du remplissage interne. Utilisez une fonction de rappel stable pour dériver des valeurs par défaut proportionnelles sans ajouter un autre observateur. useEditorLayout applique sharedWidths.limits aux préférences de l'hôte ainsi qu'au stockage de largeur partagé ; readEditorLayout accepte les mêmes limites en tant que quatrième argument optionnel. Les appelants existants conservent leurs limites et comportements par défaut.
2026-09-30 · Accessibilité de SelectionToolbar
SelectionToolbar.ariaLabel permet de nommer la barre comme une région. Le compteur reste un message de statut annoncé en direct. L’hôte fournit les libellés localisés et peut utiliser actionContent pour associer les composants partagés EditorToolGroup et ActionMenu ; les contrôles des permissions et les gestionnaires restent sous sa responsabilité.
2026-09-10 · Badges d’identité d’espace de travail
ProjectSwitcherProject.badge accepte un contenu React facultatif et non interactif. Le badge apparaît près du nom de chaque élément, dans la ligne du contexte courant absent de la liste et près du nom courant d’un déclencheur textuel. Les déclencheurs uniquement composés d’une icône restent compacts ; les déclencheurs textuels de la plateforme masquent le badge aux largeurs de téléphone afin de préserver le nom de l’espace. Le menu ouvert continue de l’afficher. L’hôte fournit des données correctement délimitées, des libellés localisés et les styles de présentation ; omettre le champ conserve l’apparence existante.
2026-09-08 · EmptyState
EmptyState centre l’icon décoratif facultatif, title, description facultative et action sur une surface transparente. layout="section" est compact par défaut ; layout="workspace" réserve davantage d’espace. Placez les actions dans action, avec un fragment pour plusieurs boutons ; le conteneur gère espacement et libellés longs. Le titre est un h2 : ciblez le slot title plutôt que strong. Les classes racines sont conservées ; skin.vars et style sont pris en charge. L’hôte garde les textes localisés, permissions, navigation et création ; recherches et erreurs conservent leurs messages et actions.
2026-09-08 · SidebarNavigation
SidebarNavigation précharge les routes de même origine après 180 ms de survol ou lors du focus clavier. Les navigations fixe et contextuelle partagent une limite de 8 destinations par 30 secondes. Le préchargement est suspendu hors ligne, dans les onglets masqués, avec Save-Data ou en 2G ; téléchargements, liens désactivés, nouvelles fenêtres et ancres locales sont exclus. La navigation et la protection des modifications restent inchangées.
2026-09-07 - AccountDropdown / SidebarProfile
AccountDropdown accepte les options compact et preferences : le mode compact masque les identifiants et l’historique de création ; le contenu existant reste inchangé par défaut. Appearance et Language acceptent triggerRole="menuitem" dans le menu du compte. La navigation au clavier rétablit le focus et les dialogues de langue imbriqués gèrent Échap. SidebarNavigation.searchEnabled vaut true par défaut ; utilisez false pour une navigation courte et fixe. SidebarProfile avec href, sans menu, ouvre la même destination dans les deux modes.
2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace
Les formulaires partagent une échelle typographique et adaptent les textes longs ; formes arrondies et couleurs de marque restent. FormField nomme les groupes : controlId et l’id interne relient le libellé. SearchField rend le focus après effacement. Segmented et ControlMenu acceptent des options désactivées ; les éléments désactivés de ActionMenu n’ont pas de lien. Les boutons occupés conservent taille et indicateur. AdminEntityDialog valide les champs obligatoires, e-mails et JSON, cible les erreurs, bloque les enregistrements répétés et conserve les saisies après échec. EditorWorkspace offre ref.focusControl(element) pour révéler un panneau avant de cibler son champ. Le mouvement réduit désactive les transitions des contrôles. WorkspaceDialog fait défiler le contenu long en gardant titre et actions visibles ; les courts dialogues mobiles suivent la hauteur du contenu.
2026-09-07 · WorkspaceLocationSync / ProjectSwitcher
Après un changement de route, WorkspaceLocationSync ferme le sélecteur temporaire des espaces pour afficher directement les outils de destination. Les préférences de recherche et de sections sont conservées. Le nom du périmètre et son contexte occupent deux lignes ; les noms longs dans l’en-tête sont tronqués dans le bouton.
2026-09-07 · Navigation unifiée et surfaces arrondies Qokit
WorkspaceNavigationDock réutilise la navigation et les droits de l’hôte via items, fallback, className et onClickCapture, sans charger une autre session. La préférence existante pilote les modes déployé, icônes et masqué ; jusqu’à 860px, le tiroir reste disponible. PlatformHeader.leadingContext apparaît aussi dans EditorHeader. Les boutons en capsule et les surfaces arrondies sont conservés ; les bordures répétées disparaissent.
Sur ordinateur, un clic sur le menu masque la barre latérale ou rétablit son dernier mode visible. Faire glisser le menu ou le bord de la barre permet de passer entre les modes masqué, icônes et développé. Les flèches gauche/droite suivent le sens de lecture. Annuler le glissement conserve la préférence enregistrée ; sur mobile, le tiroir de navigation reste utilisé.
Monter WorkspaceLocationSync une fois sous Suspense dans le layout Next. useWorkspaceQueryState(key, defaultValue, validate) renvoie [value, setValue, ready] ; useWorkspaceQueryRecord(key, defaults, validators) restaure uniquement les filtres plats déclarés. Ne pas placer de secrets ni de brouillons dans les URL. WorkspacePage restaure des positions de défilement de session limitées ; les zones internes utilisent data-workspace-scroll-region et WorkspaceScrollRestoration. Les retours natifs annulables réutilisent la protection de sortie sans ajouter d’historique. AdminEntityDialog conserve les saisies après échec ou nouveau rendu ; l’hôte reste responsable des versions et résultats.
La typographie de gestion utilise des rôles fixes : titre de page 20px/650, titre de section 16px/600, texte et navigation 14px, libellés 13px, indications 12px. --qk-workspace-body-ink et --qk-workspace-active-ink dérivent des couleurs existantes.
Les boutons principaux arrondis conservent le bleu du Logo #4695D8 et utilisent du texte, des icônes et des indicateurs blancs dans les deux thèmes. Le survol reste légèrement éclairci. Les boutons secondaires et dangereux gardent leurs couleurs sémantiques.
Les menus déroulants et sélecteurs d’espace partagent --menu-option-font-size (14px) et --menu-option-font-weight (500), avec un interligne de 1.45 ; les options sélectionnées utilisent 600 et les métadonnées 12px/400. WorkspaceNavigationDock précharge les destinations de même origine au survol ou au focus clavier, avec une déduplication bornée. Les protections de sortie et les routes hôtes restent actives.
2026-09-07 - ColumnLayout
ColumnLayout remplit les fenêtres de gestion avec une navigation ancrée, un défilement indépendant et une barre de page fixe. WorkspacePage utilise des sections plates et des Tokens de rayon partagés. Jusqu’à 860px, la navigation reste un tiroir, inactif une fois fermé. Propriétés et comportements métier restent inchangés. Supprimez les marges extérieures doubles et limitez la largeur dans les formulaires.
Points d'entrée
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';| Point d'entrée | Usage |
|---|---|
@qokit/components/ui | Composants de base tels que Button, Card, Dialog, Menu, Pill |
@qokit/components/patterns | Combinaisons telles que Header, Footer, Espace de travail, Tableau, Ressources et Assistant IA |
@qokit/components/skins/platform | Recette visuelle de la plateforme et de l'espace de travail |
@qokit/components/skins/admin | Recette visuelle Admin |
@qokit/components/skins/site | Génération de la recette visuelle du site |
Limites des responsabilités publiques
PromptPanel accepte les attributs optionnels referenceReader et referenceCopy localisés. Le lecteur renvoie les contentExcerpt et truncated extraits via les méthodes asynchrones file(File, AbortSignal) et website(url, AbortSignal) ; l'authentification et l'accès à l'API sont gérés par l'hôte. Le composant gère la lecture, la prévisualisation, la nouvelle tentative et la suppression ; si une URL valide ne comporte pas de texte de prompt, referenceCopy.websitePrompt complète la requête, tandis qu'une erreur de format utilise referenceCopy.errors.url et bloque la lecture. Si l'URL n'a pas encore été lue ou est en cours de lecture, la soumission attend le dernier contenu et ne se produit qu'une seule fois ; les changements de saisie ou les échecs de lecture annulent les opérations en attente, et les nouvelles tentatives ne restaurent pas les anciennes soumissions. Le fichier doit être prêt avant la soumission. La lecture automatique de l'URL complète se déclenche lors du collage, de la perte de focus ou de l'appui sur Entrée ; l'URL initiale est également lue et réutilise les résultats en cours ou terminés ; en cas d'échec, une nouvelle tentative explicite est proposée. Modifier ou supprimer une URL annule la lecture précédente et efface les résultats. En l'absence de lecteur fourni, la soumission native se poursuit sans traitement asynchrone des références.
L'ingestion de références a été ajoutée en septembre 2026 en tant que capacité optionnelle et rétrocompatible du composant.
La structure des composants garantit :
- Le DOM et les balises sémantiques ;
- Les comportements ARIA, clavier, focus et disabled ;
- L'état et l'interaction de base ;
- Des classes par défaut stables ;
- Des emplacements nommés pour les Skin.
Les Skin peuvent :
- Ajouter des classes aux emplacements
root,header,body,item,action, etc. ; - Transmettre des variables CSS via
vars; - Utiliser les commutateurs de tonalité, de couche ou d'adaptation visuelle déjà exposés par le composant.
Les Skin ne doivent pas demander de données, modifier le DOM, détenir de règles métier ou contourner les comportements d'accessibilité.
Contenu des éléments générés
Les blocs personnalisés générés continuent d'utiliser les éléments html-* enregistrés dans le schéma v2, sans HTML exécutable ni nouveau type de bloc. Depuis septembre 2026, @qokit/site-schema fournit bindSiteModuleContent, updateSiteModuleBoundContent et forkSiteModuleContentBindings pour la liaison de contenu par langue. Les chemins de contenu sont conservés dans les modules, tandis que les textes destinés aux visiteurs sont stockés dans les mappages de contenu par langue ; les mises à jour suivent les transactions d'annulation et de sauvegarde. Lors de la copie ou du déplacement d'éléments entre blocs, les liaisons doivent être dérivées pour éviter de modifier la source.
extensionRequirements optionnel enregistre les besoins runtime non résolus et ne constitue ni un manifeste d'installation ni une autorisation d'accès. createSiteExtensionHandoff exporte des demandes de développement v1 non exécutables ; avant de publier un site exécutable, ces besoins doivent être résolus ou explicitement exclus après revue.
Contrôles de formulaire
Les formulaires partagés utilisent FormField pour associer les étiquettes, les descriptions, les métadonnées obligatoires, les erreurs et les ID de contrôle. Les contrôles de texte utilisent Input, le contenu multiligne utilise Textarea, et les contrôles de sélection utilisent Checkbox, RadioGroup et Switch ; les éléments existants Select et SearchField utilisent le même contrat de taille et d'état.
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 associe les étiquettes, les descriptions et les erreurs au contrôle enfant unique via id, aria-describedby, aria-invalid et required. N'entourez plus les contrôles partagés avec un élément <label> supplémentaire.
Input, Textarea, Select et SearchField prennent en charge trois tailles, sm, md et lg, correspondant respectivement à 40 px, 44 px et 48 px. Les contrôles sur une ligne utilisent par défaut la forme pill ; Textarea utilise toujours les coins arrondis partagés pour le multiligne. Les états interactifs et d'erreur proviennent tous des jetons partagés.
Durant la migration, l'ancien contrat .qk-field reste utilisable ; les nouvelles intégrations doivent utiliser les composants partagés et les emplacements de skin nommés.
Sélection dans les listes
Depuis septembre 2026, les listes peuvent combiner useWorkspaceSelectionMode({ enabled, resetKey, onClear }) et WorkspaceFilterToolbar.selection. Ce Hook est initialement inactif, se réinitialise lors des changements de portée ou de permissions, et distingue la vidange des ID sélectionnés de la sortie du mode lot ; la clé de portée doit inclure la collection, la langue, la pagination et les filtres.
Passez WorkspaceDataTable.selection uniquement lorsque le mode lot est actif ; les grilles et les contrôles de sélection sur mobile utilisent le même mode. La barre d'outils gère les actions de sélection générales, tandis que l'intégrateur fournit les textes localisés, les ID optionnels et les actions métier vérifiées par permission. L'élément optionnel actionContent peut porter des sémantiques ARIA supplémentaires, mais ne remplace pas les contrôles généraux ou les confirmations. Les listes en lecture seule n'affichent pas le mode lot ; les sélecteurs de fichiers et les revues de proposition conservent leurs sémantiques propres.
Ces nouvelles capacités sont optionnelles et rétrocompatibles ; la sélection dans les tableaux reste explicitement contrôlée par l'intégrateur.
Cartes de métriques
Nouvelles références API (anglais ; traduction à venir) · 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 et Footer de la plateforme
Logo affiche une image statique par défaut. motion="breathe" réserve son espace lorsqu’il est masqué, puis le révèle une seule fois en 4,8 secondes dès que la page est chargée et que la moitié au moins est visible. L’en-tête et le pied de page n’ajoutent aucun délai. motionVisibilityDelayMs ajoute éventuellement une durée de visibilité continue, nulle par défaut. motionOnceKey partage l’état de lecture entre les montages d’un même document ; l’en-tête et le pied de page ont des clés distinctes. Navigation, changement de thème et retour par défilement ne relancent rien ; un rechargement complet réinitialise cet état. Mouvement réduit, JavaScript désactivé ou observation de visibilité indisponible affichent le logo statique. motion="reveal" reste un alias.
PlatformHeader.autoHideOnScroll vaut false par défaut ; PublicPlatformHeader l’active. L’en-tête disparaît en descendant et revient en remontant ou près du haut. Les menus ouverts et le focus dans l’en-tête le gardent visible. Les en-têtes de l’espace de travail et de l’éditeur restent fixes.
PlatformHeader est la structure de Header sans état métier. PublicPlatformHeader combine au-dessus les entrées de marque, la navigation publique, la langue, le thème, la connexion, « Essayer maintenant » et le menu mobile ; l'état anonyme de la plateforme et le site de documentation réutilisent directement cette combinaison.
La navigation publique génère uniformément « Ressources / Tarifs / Actualités » via buildPublicHeaderNavItems(copy, links). L'intégrateur ne doit analyser que les URL internes au site, au site de documentation et à la plateforme de l'application courante, sans redéfinir l'ordre ou le texte du menu. Le Header plateforme connecté utilise également la même fonction de génération.
<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 structure sous-jacente navItems supporte toujours link, scroll et menu. menu supporte la fermeture par clic, clavier, Escape et clic extérieur sur bureau, tandis que MobileHeaderMenu le développe en groupe de liens sur mobile.
SiteFooter est la structure du Footer ; la plateforme et le site de documentation utilisent PublicPlatformFooter pour combiner uniformément le Shell externe, les entrées de marque, les liens, les contrôles de thème et de langue. L'intégration inter-domaine convertit les liens relatifs de la plateforme en adresses absolues via resolveCompanyHref.
<PublicPlatformFooter
brandHref="https://qokit.com"
copy={footerCopy}
resolveCompanyHref={(href) => `https://qokit.com${href}`}
/>Les applications métier ne doivent pas copier le DOM du Header/Footer ou le tableau de navigation publique ; pour différentes apparences visuelles, utilisez PlatformHeaderSkin, SiteFooterSkin ou le Skin plateforme correspondant.
Stratégie de compatibilité
- L'ajout de propriétés optionnelles et d'emplacements Skin est un changement rétrocompatible ;
- La suppression de propriétés, la modification de la sémantique par défaut ou le changement du comportement DOM/clavier sont des changements cassants ;
- Les changements cassants doivent figurer dans le Changelog et fournir des exemples de migration ;
- Ne dépendez pas des classes internes, répertoires ou structures de route non publics ;
- Lorsque deux points d'intégration ou plus nécessitent le même écrasement, celui-ci doit être promu en Skin ou Token public.
Édition en plein écran
EditorWorkspace associe une boîte de dialogue plein écran, la gestion du focus et des panneaux adaptatifs. dirty demande confirmation avant de perdre les modifications, busy bloque la fermeture pendant la sauvegarde et onSave gère Ctrl/Cmd+S. Les autorisations, les données, la sauvegarde et la publication relèvent de l’application.
view / onViewChange passent entre edit, focus et preview sans remplacer l’éditeur. preview fournit l’aperçu ; previewPanel réutilise un panneau. layout accepte writing, structure et canvas. storageKey mémorise les largeurs et les panneaux repliés, jamais le document.
onSaveAndClose renvoie true après confirmation de l’enregistrement, false en cas d’échec, handled si l’hôte a déjà navigué, ou pending si la validation attend une décision. L’échec garde l’éditeur ouvert. Réserver closeBehavior="collapse" aux hôtes qui conservent le brouillon. EditorSaveStatus affiche un état confirmé. EditorViewControls, EditorLeaveDialog et useEditorLayout peuvent aussi être composés séparément.
Migration clavier : Segmented occupe un seul arrêt Tab et utilise les flèches / Home / End. Dialog respecte Échap traité par une superposition enfant ; l’éditeur quitte ensuite la concentration ou l’aperçu avant de se fermer. LivePreviewToolbar.exitControl accepte les commandes de vue partagées. Enregistrement, publication et autorisations restent gérés par l’hôte.
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 place la commande du volet latéral dans l’en-tête. Utilisez un seul emplacement avec un volet gauche. SidebarNavigation conserve l’état, les raccourcis et le volet mobile ; sans emplacement, les commandes restent à leur place. Le bouton de l’en-tête ferme également le volet mobile ; le focus revient ensuite à ce même bouton.
EditorHeader
EditorHeader conserve le logo, le compte et le menu global dans l’éditeur actif. startControl et endControl commandent les panneaux latéraux, center les vues et actions l’enregistrement. PlatformHeader.editorActions réutilise la navigation responsive, la langue et le thème. onNavigate doit traiter les modifications non enregistrées avant d’exécuter son rappel. Sur écran étroit, l’en-tête occupe deux lignes ; les sous-menus traitent Escape en premier.
WorkspaceHeaderPortal.startControl et endControl placent les bascules de panneau de page gérée dans les emplacements correspondants de l'hôte. Les hôtes exposent startTarget et endTarget optionnels aux côtés du titre, du statut et des actions. La bibliothèque Files et l'espace de travail d'actif unique utilisent workAreaControls ; l'aperçu de l'actif conserve l'en-tête complet afin que son identité, l'action de retour et les destinations de panneau restent disponibles. ProjectWorkspace possède les choix de navigation/conversation gauche partagée pour Content et Files. Files enregistre ses dimensions de panneau de ressource mémorisées via useProjectResourcePanel, navigue via ProjectContentTools, et fournit uniquement son contrôle d'inspecteur droit via ProjectToolbar.endControl. La conversation utilise la même voie gauche et le compositeur intégré entre les zones de projet ; les tâches de ressource compacte, de conversation et d'inspecteur sont mutuellement exclusives.
EditorNavigationMenu
EditorNavigationMenu reprend toute la SidebarNavigation de l’hôte dans un panneau superposé, avec les permissions et le contexte du projet, sans déplacer le canevas. Langue et thème restent en bas ; les sous-menus traitent Échap en premier. Concentration et plein écran du navigateur sont indépendants. La navigation attend les sauvegardes en cours et protège les brouillons.
WorkspaceNavigationMenu / WorkspacePageHeader
La navigation globale utilise Command+\ sur Mac ou Control+\ sous Windows/Linux, y compris indépendamment dans Creator. T et Shift+T conservent leur rôle dans la disposition de l’éditeur. Les champs modifiables, la composition de texte, les répétitions et les événements déjà traités sont ignorés. Les indications du bouton et aria-keyshortcuts exposent la combinaison ; la navigation globale ne capture plus T seul.
Les espaces connectés utilisent PlatformHeader.workspaceActions pour partager le compte et la navigation à toutes les largeurs. WorkspacePageHeader harmonise titres et actions. WorkspaceNavigationMenu affiche la barre latérale courante avec ses droits et son contexte ; EditorNavigationMenu reste un alias compatible. Studio conserve sa barre d’outils. Les en-têtes publics gardent leur présentation.
WorkspaceNavigationGuard protège la navigation globale avec dirty, busy, error et onSave facultatif. Seul un enregistrement confirmé renvoyant true autorise le départ ; un échec conserve le brouillon. Language.onBeforeChange(apply) permet la même protection avant un changement de langue. Désactivez les champs pendant l’enregistrement.
La navigation de bureau propose une barre développée, des icônes et le masquage automatique. La barre latérale et le tiroir partagent la recherche et les groupes ouverts. Avec un pointeur précis, le survol du bord ouvre un aperçu après 300ms et le referme 320ms après la sortie ; un clic le maintient ouvert. Les commandes tactiles et clavier restent disponibles. Dialog utilise par défaut modal={true} et autoFocus={true} ; l’aperçu règle les deux sur false pour préserver le focus et le défilement.
EditorViewControls
Un seul bouton permet les deux sens : en édition, il affiche Concentration ; en concentration, Modifier. Cliquez ou appuyez sur T ; E revient directement à l’édition. Sur les en-têtes étroits, le bouton reste visible ; aperçu, plein écran et actions supplémentaires sont dans Plus.
EditorViewControls sépare Édition/Concentration du plein écran natif. L’aperçu devient un bouton indépendant et revient au mode précédent ; useEditorWorkMode conserve ce mode pour les actions de sortie personnalisées. Les valeurs edit/focus/preview restent valides. L’aperçu utilise désormais un button avec aria-pressed au lieu d’un radio dans le groupe des modes. Le plein écran nécessite un clic et inclut navigation et dialogues dans la racine de l’application ; son entrée est masquée si le navigateur ne le prend pas en charge.
Language / Appearance
Language et Appearance variant="menu" acceptent layout="row" pour afficher le libellé, la valeur actuelle et une flèche. La disposition compacte par défaut et la protection du changement de langue restent inchangées. SiteHeaderCopy.helpResources et contactSupport nomment les liens d’aide facultatifs de l’espace de travail.
requestWorkspaceNavigation
Les pages avec un bouton de panneau latéral masquent le bouton de menu supplémentaire de l’en-tête, même en mode replié et mobile. Les éditeurs et les pages sans panneau le conservent. Importez requestWorkspaceNavigation(returnFocusTarget?) et useWorkspaceNavigationState() depuis @qokit/components/patterns/WorkspaceNavigation : la requête bascule le tiroir enregistré et renvoie false s’il est absent. L’élément facultatif reprend le focus à la fermeture. Vérifiez .available avant d’ajouter un accès. Utilisez le bouton existant ou cette API plutôt que la position DOM du bouton supprimé.
WorkspacePanelReveal
La navigation globale utilise une icône de menu, les outils des icônes de panneaux directionnels. useWorkspacePanelReveal({ temporary: true }) ouvre temporairement les outils au clic ou au clavier en mode Concentration. toggle(trigger?) et close(true) conservent la disposition et le mode, puis rendent le focus. Le bord de l’écran ouvre la navigation globale ; les outils répondent près de leurs boutons. L’aperçu masque les boutons des panneaux et propose un retour explicite au mode d’édition précédent.
EditorViewControls / Mode d’affichage
EDITOR_VIEW_SHORTCUTS → Tooltip + aria-keyshortcuts
EditorHeader gère aussi EDITOR_TOOLBAR_SHORTCUTS : Command/Control+S active le EditorSaveButton visible, Shift+P ouvre EditorStatusAction shortcut="publish" et Shift+M le menu des outils. Les commandes utilisent les mêmes contrôles actifs qu’un clic ; publier exige toujours une action explicite dans le panneau. Seul l’en-tête actif et visible répond. Menus enfants, dialogues, composition et répétitions bloquent les raccourcis ; seul l’enregistrement fonctionne dans les champs éditables. Les indications et aria-keyshortcuts partagent leurs définitions. Un toolsControl personnalisé ajoute aria-keyshortcuts={EDITOR_TOOLBAR_SHORTCUTS.tools.aria} au déclencheur. ActionMenu.triggerKeyShortcuts ajoute l’attribut et l’indication sans enregistrer de commande globale.
Les panneaux utilisent Shift+A (ajouter), Shift+L (pages/calques), Shift+K (conversation), Shift+C (contenu), Shift+D (design), Shift+G (style global). CMS ajoute Shift+S (réglages), Shift+E (SEO), Shift+H (historique) si disponibles. Les métadonnées shortcut de EditorChoiceControl, EditorViewTabs et ActionMenu partagent les indications. EditorPanelChoiceShortcuts et EditorViewControls.compactActions conservent les actions dans les menus repliés, y compris sur téléphone. EditorPanelShortcuts.commands enregistre les actions existantes sans dupliquer les contrôles. Les restrictions masqué, inert, désactivé, aperçu et superposition restent applicables. Les barres latérales mobiles non modales du même espace permettent de changer de panneau ; menus et dialogues modaux bloquent les raccourcis. Les touches sans modificateur gardent leur comportement.
| Mode d’affichage | |
|---|---|
E | Modifier |
T | Modifier ↔ Concentration |
V | Aperçu / Revenir à l’édition |
F | Passer en plein écran / Quitter le plein écran |
Seul l’éditeur actif traite ces touches. La saisie, la composition IME, les touches maintenues et les boîtes de dialogue ou menus secondaires ouverts ne changent pas le mode.
PlatformHeader.workspaceNavigation
PlatformHeader.workspaceNavigation place la navigation globale avant le logo ; workspaceActions et editorActions conservent les actions du compte. Les espaces de travail réutilisent le bouton de barre latérale, et les éditeurs placent le bouton du panneau droit avant l’avatar. Sur écran étroit, navigation, marque, titre et avatar surplombent les outils et l’enregistrement. L’ordre du DOM suit la disposition ; l’aspect dépoli sans bordure est conservé.
2026-09-06 - EditorHeader.preview / EditorViewControls.returnView
EditorHeader.preview affiche seulement center comme barre de prévisualisation compacte sans bordure ; logo, compte, sauvegarde et panneaux restent montés mais masqués. Avec une LivePreviewToolbar séparée, masquez l’en-tête de l’éditeur et utilisez EditorViewControls.returnView (edit ou focus) pour retrouver le mode précédent. Gardez le retour accessible et le plein écran indépendant ; l’en-tête du site reste visible.
2026-09-06 · Builder / CMS
Builder et CMS partagent BuilderWorkspace, EditorCatalog et EditorComponentSettings pour les panneaux, les illustrations d’insertion et les réglages visuels. Les préréglages appliquent ensemble les options liées et préservent le contenu ; chaque application gère l’enregistrement et l’annulation. Les commandes suivent le thème de la plateforme et le contenu celui du site.
Pied de page rendu sur le serveur · 2026-09-07
SiteFooterLayout reçoit un locale explicite et un copy dans une seule langue. Les composants serveur rendent la structure partagée du pied de page ; les commandes de thème et de langue et la boîte de dialogue QR restent des composants client. Les interfaces existantes SiteFooter et PublicPlatformFooter restent prises en charge.
import { SiteFooterLayout } from '@qokit/components/patterns/SiteFooter';
<div className="qk-platform-footer-shell">
<SiteFooterLayout locale={locale} copy={footerCopy} />
</div>Résolvez les liens entre domaines dans copy.companyLinks sur le serveur. Utilisez controls pour personnaliser la zone de commandes interactives.
EditorHeader.titleControl / FloatingAssistant.presentation
EditorHeader.titleControl et EditorWorkspace.titleControl peuvent remplacer le titre par le menu partagé du projet. Conservez un title descriptif et la protection des modifications non enregistrées lors de la navigation. FloatingAssistant.presentation="embedded" affiche une région nommée dans le panneau hôte, sans bouton flottant ni voile ; la valeur par défaut reste floating. L’hôte gère la position et la visibilité ; l’assistant conserve la conversation et les autorisations.
2026-09-07 · WorkspaceAssembly
WorkspaceAssembly marque les cartes sortantes et les sections entrantes sans ajouter de boîte de mise en page. Pour les contrats de descendants directs, placez workspaceAssemblyAttributes(part, index, phase) sur le DOM existant. EditorHeader.assemble et BuilderWorkspacePanels.assemble fournissent les marques de l’éditeur.
Appelez await startWorkspaceAssembly(navigate, destinationPathname) uniquement après une création réussie : capture des éléments visibles, navigation unique et assemblage de la destination ou de son squelette en 720 ms maximum. La destination expose une marque entrante canvas ; useWorkspaceAssemblyPending() maintient le chargement monté jusqu’à la fin des captures, pendant le préchargement des données et du code. Mouvement réduit ou navigateur incompatible : navigation directe. Les transitions lentes ou interrompues libèrent les captures et poursuivent la navigation. Les marques seules n’animent ni édition, ni rechargement, ni historique. Le motif nettoie les styles temporaires ; l’hôte conserve erreurs, idempotence et chargement.
2026-09 · Espaces de gestion
WorkspacePage et WorkspaceLayout acceptent variant : overview, list, detail, settings ou editor. WorkspaceFormFooter dispose les propriétés actions, message, tone et busy fournies par l’hôte ; l’enregistrement reste à sa charge.
Les tableaux étroits (WorkspaceDataTable, AdminDataTable) affichent des fiches étiquetées avec sélection, en-têtes personnalisés et actions. Utilisez mobileLayout="scroll" pour les matrices comparatives. WorkspaceFilterToolbar place recherche et filtres avant tri et affichage. La barre latérale utilise h2, la page h1.
2026-09-08 · Task focus
useSidebarTaskFocus(active) masque temporairement la navigation pendant une tâche demandant de la concentration. À la sortie, il rétablit le mode précédent, sauf si l’utilisateur le modifie explicitement. Le masquage automatique conserve la préférence enregistrée.
Nouvelles références API (anglais ; traduction à venir)
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’adaptateur Web transmet aussi FloatingAssistantPanel.composerAttachments. Cet emplacement affiche les pièces jointes gérées par l’hôte dans le formulaire, avant la zone de texte. L’hôte contrôle leur position et leur envoi : le dépôt prépare la pièce jointe, le succès retire uniquement celle envoyée et les erreurs la conservent pour réessayer.
Conversation partagée (référence en anglais ; traduction à venir)
@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 compose InlineNotice pour présenter de manière compacte les états des tâches, les échecs, les solutions de repli et les confirmations de sauvegarde dans les conversations. Fournissez un title localisé et, au besoin, description, tone et action. Les deux lignes utilisent la taille de légende, un espacement réduit et une surface transparente ; la tonalité souligne le statut, tandis que le texte complémentaire reste atténué. Les valeurs par défaut role="status" et aria-atomic="true" annoncent toute la mise à jour ensemble ; utilisez role="alert" pour les échecs nécessitant une action. Le texte rédigé par l’assistant reste dans 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.
Nouvelles références API (anglais ; traduction à venir) · 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 statut,sort,controlsmétier, optionsadvanced,resetconditionnel,resultde ressource etsummarycomplémentaire.presentation:view, affichecontrolsetoptionstels que les colonnes visibles et la taille de page. La personnalisation des widgets de page appartient aux actions d'en-tête de page.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.
Utilisez query.result={{ label, count, total?, locale? }} pour le nom de ressource et le nombre de résultats. WorkspaceResultSummary affiche « Nom · nombre » et ajoute « / total » seulement si un total non filtré fiable diffère ; les nombres sont formatés selon la langue et isolés pour les textes bidirectionnels. Omettez result tant que le nombre est inconnu ; zéro est valide. N’ajoutez pas une autre ligne de nom et de nombre au-dessus de la même liste. AdminFilterBar.result accepte le même objet. Titres, sections pertinentes, pagination et nombres sélectionnés conservent leurs rôles ; query.summary sert aux autres unités, au contexte ou à la fraîcheur des données.
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.
Complément de référence API (anglais, traduction à venir) · 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.
Les options de sélection et de menu acceptent annotation pour ajouter un point aux couleurs du thème et son sens localisé au nom accessible. Le déclencheur de ControlMenu affiche aussi le point de l’option active ; triggerAnnotation: null le réserve au menu. Choisir de nouveau une option activée déjà sélectionnée appelle onReselect. Les options natives affichent l’annotation à côté du libellé ; hidden exclut un texte indicatif de la liste. L’hôte choisit la valeur annotée et l’action ; le contrôle partagé ne déduit pas l’héritage et n’écrit pas de données.
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
Placez CustomizableWidgetLayoutControls dans les actions d'en-tête de page après l'aide contextuelle et avant l'action principale, y compris sur mobile. Utilisez copy.customize localisé pour nommer explicitement l'action (par exemple, « Personnaliser les widgets »). Le même point d'entrée uniquement icône expose aria-pressed et aria-expanded, et devient copy.done pendant l'édition. customizeButtonRef expose optionnellement le déclencheur pour la restauration du focus hôte ; disabledCustomize désactive le point d'entrée sans changer sa géométrie. Fournissez onCollapseToggle et areWidgetsCollapsed uniquement pour les hôtes qui prennent en charge la réduction des widgets ; les omettre rend le point d'entrée de personnalisation seul.
CustomizableWidgetLibrary possède le titre commun de la bibliothèque, les actions de réinitialisation/fermeture, la disposition de défilement responsive, la mise au point initiale du bouton de fermeture et la gestion d'Escape. La fermeture retourne le focus au contrôle invoquant si le focus est toujours à l'intérieur de la bibliothèque ; les clics à l'extérieur conservent leur focus de destination. Les hôtes conservent les définitions de widgets, les commandes d'ajout/suppression/tri/redimensionnement, la persistance et la sémantique de réinitialisation. Les emplacements CMS et Admin class restent disponibles pour les hooks de domaine, mais ne doivent pas définir de surfaces de bibliothèque séparées ou de mises en page mobiles.
2026-10-17 · Déclencheurs ActionMenu riches
ActionMenu.renderTrigger peut réutiliser un contrôle riche tel que SelectableTile. Il reçoit aria-expanded, aria-haspopup, disabled, et onClick ; épandez-les sur le déclencheur réel. L'hôte conserve la sémantique de sélection et l'apparence du contrôle. Le positionnement en portail, la navigation au clavier du menu, la fermeture, le retour au focus et les feuilles mobiles optionnelles restent gérés par ActionMenu. Les déclencheurs de bouton et d'icône par défaut sont inchangés.
Contrôles de rayon et de plage
RangeNumber, de @qokit/components/ui/RangeNumber, associe un curseur natif à un Input numérique précis. Fournissez label, value, min, max, les options step et unit, ainsi que onChange. Une valeur indéfinie affiche un tiret de valeur mixte ; modifier une entrée définit un nombre borné. onCommit permet à l’hôte de regrouper les changements continus dans son historique d’annulation. disabled, navigation au clavier, densité compacte, RTL et styles de focus sont partagés ; la persistance reste à l’hôte. RangeNumberSkin expose les emplacements racine, curseur, entrée et unité.
EditorRadiusControl, de @qokit/components/patterns/EditorRadiusControl, réunit un aperçu de forme en direct, quatre entrées pour les coins physiques, RangeNumber et des formes prédéfinies facultatives. value et onChange utilisent le raccourci CSS border-radius ; l’hôte traduit cornerLabels et les noms des préréglages. En RTL, l’ordre reste haut gauche, haut droit, bas droit, bas gauche. max limite l’édition à des pixels bornés ; son absence préserve les unités CSS et les coins elliptiques. Un rayon mixte n’affiche aucune valeur unique avant le réglage conjoint des quatre coins. EditorRadiusControlSkin adapte les emplacements racine, schéma, aperçu et préréglages sans modifier état ni persistance.
2026-10-22 · Onglets actifs sur les écrans étroits
PillTabs accepte l’option scrollActiveTabIntoView, désactivée par défaut avec false. Pour les onglets horizontaux, elle révèle l’enfant direct actif PillTabLink ou PillTabButton lors de la sélection et du redimensionnement. Seule la barre défile ; la position de la page et le focus clavier restent inchangés. LTR et RTL utilisent une correction immédiate, y compris en mouvement réduit. Les onglets verticaux et les appels sans cette option conservent leur comportement.