@ktortu/aaa

Bibliothèque de composants Angular headless + thémés par tokens CSS (--kt-*). Les composants sont des directives/composants accessibles (appui sur @angular/aria / CDK) ; leur apparence vit dans des feuilles CSS globales que vous importez à part.

Démo & documentation vivante : ktortu-aaa-demo.web.app

Convention de nommage

• Selectors (templates) : préfixe kt — [ktButton], <kt-text-field>, [ktDialogTitle]…
• Symboles TypeScript : préfixe Kt — classes/directives/pipes KtX (KtButton, KtSelect…), tokens KT_X (KT_BUTTON_CONFIG, KT_BREAKPOINTS…). Ce préfixe évite les collisions d'imports chez les consommateurs.
• Exception assumée : le namespace natif Temporal et ses alias de types (Timestamp, CalendarDate, WallTime, LocalDateTime, ZonedTimestamp) ne sont pas préfixés, pour rester ergonomiques côté dates.

Utilisation (TypeScript)

Chaque famille est importable depuis son point d'entrée @ktortu/aaa/<feature> ; les utilitaires transverses (breakpoints, viewport, sheet-drag, générateur d'id) depuis @ktortu/aaa/cdk.

import { Component } from '@angular/core';
import { KtButton } from '@ktortu/aaa/button';
import { KtTextField } from '@ktortu/aaa/forms';

@Component({
  selector: 'app-exemple',
  imports: [KtButton, KtTextField],
  template: `
    <kt-text-field label="E-mail" type="email" [(value)]="email" />
    <button ktButton mode="filled" color="primary">Enregistrer</button>
  `,
})
export class Exemple {
  email = '';
}

Points d'entrée TypeScript : @ktortu/aaa/button, /card, /dialog, /layout, /menu, /snackbar, /tabs, /tooltip, /forms, /icon (icônes), /cdk (breakpoints, viewport, sheet-drag, id-generator) et /i18n (traductions). La racine @ktortu/aaa ré-exporte tout par commodité, mais importer depuis le point d'entrée précis préserve le tree-shaking. Les thèmes sont des fichiers CSS (cf. §Styles), pas un point d'entrée TypeScript. Familles agrégées prêtes pour imports: : KtCardImports, KtMenuImports, KtDialogImports (ex. imports: [...KtCardImports]).

Layout & Sidenav (Shell)

Le module de layout (point d'entrée @ktortu/aaa/layout) fournit la structure principale de l'application. Note : Le composant nécessite le service KtLayoutService. Pour garantir l'isolation (si vous avez plusieurs layouts indépendants), ce service n'est pas fourni à la racine. Vous devez le déclarer dans le tableau providers de votre composant (providers: [KtLayoutService]).

<kt-layout desktopCloseBehavior="rail">
  <kt-sidenav>
    <!-- Contenu du menu -->
    <button ktSidenavToggle #btn="ktSidenavToggle">{{ btn.isRail() ? 'Agrandir' : 'Réduire' }}</button>
  </kt-sidenav>
  <kt-toolbar>
    <button ktSidenavToggle class="hide-on-desktop">Menu</button>
  </kt-toolbar>

  <main>Contenu principal de la page</main>
</kt-layout>

• desktopCloseBehavior : Configurable sur kt-layout ('hidden' par défaut, ou 'rail' pour ne garder que les icônes).
• ktSidenavToggle : Directive qui expose son état dynamiquement (isRail, isHidden, isExpanded, etc.) si elle est assignée à une variable locale (#btn="ktSidenavToggle").
• Responsive : Sur mobile, la kt-sidenav devient automatiquement un tiroir (drawer) et masque le contenu derrière un overlay.

Formulaires & Signal Forms

Les contrôles dédiés (kt-text-field, kt-number-field, kt-select, kt-checkbox, champs temporels…) implémentent le contrat Signal Forms (FormValueControl) : on les lie via [(value)] ou via le directive [formField] d'@angular/forms/signals. Ils n'implémentent PAS ControlValueAccessor ; pour les intégrer à des ReactiveForms existants, passez par le pont officiel d'Angular (compatForm / SignalFormControl, @angular/forms/signals) et liez avec [formField] plutôt que formControlName.

Pour un contrôle natif quelconque, le chrome de champ générique (KtField + KtFieldControl) l'enveloppe : <kt-field label="…"><input ktFieldControl [(value)]="…" /></kt-field>.

Configuration

Les valeurs par défaut sont surchargeables par token d'injection (KT_*_CONFIG, type Partial<…>) ou via les helpers provideKt* :

import { KT_BUTTON_CONFIG } from '@ktortu/aaa/button';
import { provideKtBreakpoints } from '@ktortu/aaa/cdk';
import { provideKtDialog, provideKtDialogDefaults } from '@ktortu/aaa/dialog';

providers: [
  { provide: KT_BUTTON_CONFIG, useValue: { size: 'lg' } },
  provideKtBreakpoints({ tablet: 768, desktop: 1200 }),
  provideKtDialogDefaults({ maxWidth: '40rem' }), // config CDK du dialog
  provideKtDialog({ sheetCloseButton: true }), // options maison du dialog
];

Le dialog a deux providers, complémentaires et sans recouvrement : provideKtDialogDefaults() porte la config @angular/cdk/dialog (plancher a11y, largeurs, classes) ; provideKtDialog() porte les options propres à la lib (KT_DIALOG_CONFIG).

Bouton de fermeture des bottom-sheets

sheetCloseButton ajoute une croix auto-rendue en haut de la carte, hors flux (cible tactile 44 px, WCAG 2.5.5). Désactivée par défaut — pour une raison de compatibilité, pas d'ergonomie.

[ktDialogHeader] ne rend aucune croix : c'est une simple rangée flex, où l'on POSE la sienne (<button ktButton iconOnly icon="close" ktDialogClose>). Mais comme c'est la composition usuelle, activer l'option par défaut ferait apparaître une deuxième croix chez ces consommateurs-là sans qu'ils aient rien changé. Le conteneur avertit en mode dev si les deux coexistent hors barre d'actions.

Recommandée, donc, sur toute sheet qui ne pose pas déjà son propre bouton de fermeture en tête.

Surchargeable par ouverture, comme presentation :

export const injectShareSheet = () =>
  shareSheet.injectOpener(ShareSheet, { presentation: 'sheet', sheetCloseButton: true });

La position s'ajuste en CSS seul (propriétés logiques, donc correctes en RTL) : --dialog-close-inset-block-start, --dialog-close-inset-inline-end, --dialog-close-size, --dialog-close-icon-size, --dialog-close-color, --dialog-close-bg, --dialog-close-glyph. Chacune retombe sur une couche partagée --kt-sheet-close-*, pour harmoniser d'un coup ce bouton et celui du Select compact.

L'option sheetHandle: false retire la poignée décorative (ADR-0005). Elle remplace le panelClass kt-dialog--no-handle, déprécié mais toujours honoré.

Styles (CSS)

L'apparence vit dans des feuilles CSS globales thémées par des tokens --kt-* : importez le CSS de la lib en plus des composants.

Mise en place minimale

Importez la feuille agrégée (socle + styles de base de tous les composants, ordre de cascade garanti) :

/* dans votre styles.css global */
@import '@ktortu/aaa/styles.css';

…ou via angular.json :

"styles": [
  "node_modules/@ktortu/aaa/styles.css",
  "src/styles.css"
]

Le Dialog et la Snackbar s'appuient sur l'overlay du CDK : ajoutez aussi @import '@angular/cdk/overlay-prebuilt.css';. La Snackbar annonce via le LiveAnnouncer — ajoutez également @import '@angular/cdk/a11y-prebuilt.css'; (masque l'élément d'annonce).

Thèmes (optionnels, à la carte)

Les thèmes ne sont pas inclus dans styles.css. Importez ceux que vous voulez, après :

@import '@ktortu/aaa/styles.css';
@import '@ktortu/aaa/themes/theme-material.css';

Thèmes disponibles (@ktortu/aaa/themes/theme-<id>.css) : material, material-you, primer, carbon, fluent, ant, bootstrap, catppuccin, architecte, vegetal, cyberpunk, aurora.

Un thème = des redéclarations de tokens --kt-*. Surcharger un seul --kt-* (ex. --kt-primary) rebrande toute la lib.

Import à la carte (socle + composants choisis)

Pour n'embarquer que ce qui vous intéresse, importez le socle (requis) puis un fichier par composant. Chaque bundle inclut déjà ses propres tokens — pas besoin d'importer les *-tokens séparément.

@import '@ktortu/aaa/foundation.css'; /* REQUIS — socle de tokens --kt-*, à mettre en premier */
@import '@ktortu/aaa/menu.css'; /* puis uniquement les composants utilisés */
@import '@ktortu/aaa/button.css';

Bundles disponibles :

| Import | Contenu | | ---------------------------- | ------------------------------------------------------------ | | @ktortu/aaa/foundation.css | socle de tokens --kt-* (requis, à importer en premier) | | @ktortu/aaa/layout.css | layout global (kt-layout, kt-sidenav, kt-toolbar) | | @ktortu/aaa/button.css | bouton (ktButton) | | @ktortu/aaa/card.css | carte (ktCard + marqueurs) | | @ktortu/aaa/menu.css | menu (ktMenu, ktMenuItem, …) | | @ktortu/aaa/tooltip.css | tooltip (ktTooltip) | | @ktortu/aaa/dialog.css | dialog (requiert aussi l'overlay CDK) | | @ktortu/aaa/snackbar.css | snackbar (requiert l'overlay CDK + a11y-prebuilt.css) | | @ktortu/aaa/forms.css | base des formulaires (champs, chips, switch) | | @ktortu/aaa/tabs.css | onglets | | @ktortu/aaa/icon.css | icônes (ktIcon) |

foundation.css doit toujours être importé en premier (les bundles composant en dérivent). Si vous utilisez plusieurs composants, l'agrégat @ktortu/aaa/styles.css fait tout cela dans le bon ordre.

Les formulaires « riches » (Select, MultiSelect, Field, Chips) embarquent leur CSS via les composants eux-mêmes (styleUrl) : rien à importer en plus pour ceux-ci.

Note icônes remplies : L'utilisation de [fill] ou fill sur un ktIcon exige de charger une police dont l'axe FILL est ajustable (ex. Material Symbols avec l'axe dans la requête URL).

Développement

ng build @ktortu/aaa     # build de la lib -> dist/ktortu/aaa
ng test                  # tests unitaires (Vitest)
ng serve demo            # app de démo / documentation vivante (port 4210)

Publication

cd dist/ktortu/aaa
npm publish