@ktortu/aaa 0.9.9 → 0.10.0

package/types/ktortu-aaa-icon.d.ts

@@ -0,0 +1,158 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Provider } from '@angular/core';
+
+/**
+ * Définition d'une police d'icônes **à ligatures** enregistrée dans le registre (cf.
+ * {@link KtIconConfig}). Le registre ne charge AUCUNE police : il se contente d'associer un alias
+ * court à la famille CSS réelle (à vous de charger le fichier de police, façon « apportez la vôtre »).
+ */
+interface KtIconFont {
+    /** Famille de police CSS réelle (ex. `'Material Symbols Rounded'`). Valeur `font-family` brute :
+        si elle commence par un chiffre ou contient des caractères spéciaux, la citer vous-même. */
+    family: string;
+    /** Graisse par défaut de cette police (ex. `300` ou `'normal'`). @default hérité de `--kt-icon-font-weight` */
+    weight?: string | number;
+    /** `font-variation-settings` par défaut (polices variables, ex. `"'FILL' 0, 'wght' 300"`). @default `normal` */
+    variationSettings?: string;
+}
+/**
+ * Défauts applicables à toutes les icônes `[ktIcon]` (registre de polices + police par défaut),
+ * fournis via {@link provideKtIcon}. Fourni en `Partial` : on ne déclare que ce qu'on veut.
+ */
+interface KtIconConfig {
+    /** Registre `alias → police`. L'alias est ensuite choisi sur la primitive via `[font]`. */
+    fonts: Record<string, KtIconFont>;
+    /** Alias utilisé quand aucune police n'est précisée sur la primitive (`[font]` absent). */
+    defaultFont: string;
+}
+/**
+ * Interface d'**enregistrement des alias de POLICE** à augmenter côté application pour typer l'input
+ * `[font]` et obtenir son **autocomplétion** dans les templates. Vide par défaut : sans augmentation,
+ * `[font]` accepte n'importe quelle chaîne (dégradation gracieuse, zéro config).
+ *
+ * Nommée `KtIconFontRegistry` (et non `KtIconRegistry`) à dessein : le nom générique reste réservé à
+ * un futur registre de **noms d'icônes** (SVG), qui bénéficiera du même mécanisme.
+ *
+ * @example Recette à source unique (le même objet type ET fournit le registre) :
+ * ```ts
+ * // app-icons.ts
+ * export const APP_ICON_FONTS = {
+ *   material: { family: 'Material Symbols Outlined' },
+ *   rounded: { family: 'Material Symbols Rounded', variationSettings: "'FILL' 0, 'wght' 300" },
+ * } as const;
+ *
+ * declare module '@ktortu/aaa/icon' {
+ *   // Injecte les clés de APP_ICON_FONTS comme alias connus → autocomplétion de [font].
+ *   // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+ *   interface KtIconFontRegistry extends Record<keyof typeof APP_ICON_FONTS, unknown> {}
+ * }
+ *
+ * // app.config.ts
+ * providers: [provideKtIcon({ fonts: APP_ICON_FONTS, defaultFont: 'material' })];
+ * ```
+ */
+interface KtIconFontRegistry {
+}
+/**
+ * Alias de police connus : l'union des clés de {@link KtIconFontRegistry} une fois augmentée, sinon
+ * `string` (registre vide → chaîne libre). Le tuple `[…] extends […]` évite la distribution du
+ * conditionnel sur l'union.
+ */
+type KtIconFontAlias = [keyof KtIconFontRegistry] extends [never] ? string : keyof KtIconFontRegistry;
+declare const KT_ICON_CONFIG: InjectionToken<Partial<KtIconConfig>>;
+/**
+ * Fournit un registre de polices d'icônes (alias → famille) et l'alias par défaut, pour un
+ * sous-arbre ou l'application entière. Combiné à l'augmentation de {@link KtIconFontRegistry}, il
+ * offre l'autocomplétion typée de l'input `[font]`.
+ *
+ * `defaultFont` est **contraint aux clés de `fonts`** passées dans le même appel : un typo devient
+ * une erreur de compilation (pas de repli silencieux de toutes les icônes sur la police globale).
+ *
+ * @example
+ * ```ts
+ * providers: [
+ *   provideKtIcon({
+ *     fonts: {
+ *       material: { family: 'Material Symbols Outlined' },
+ *       rounded: { family: 'Material Symbols Rounded' },
+ *     },
+ *     defaultFont: 'material', // 'rouded' → erreur TS
+ *   }),
+ * ];
+ * ```
+ */
+declare function provideKtIcon<F extends Record<string, KtIconFont>>(config: {
+    fonts?: F;
+    defaultFont?: keyof F & string;
+}): Provider;
+/**
+ * Primitive d'icône **autonome** : pose une icône seule (en-tête, item de liste, badge d'état…),
+ * là où le bouton et les champs ne suffisent pas. Directive présentationnelle — **jamais focusable
+ * ni cliquable** (pour une icône cliquable, utilisez `ktButton iconOnly`).
+ *
+ * Sélecteur d'attribut `[ktIcon]` (camelCase) ; l'hôte reçoit la classe stable `.kt-icon` (cible du
+ * style et du harness). Ne pas confondre avec le slot de projection `[kt-icon]` (kebab) de
+ * `kt-nav-item`, qui est un autre mécanisme.
+ *
+ * Deux régimes, comme dans le reste de la lib :
+ * - **Ligature** (`[ktIcon]="nom"`) : le nom devient un glyphe via une police d'icônes à ligatures
+ *   (défaut `--kt-icon-font` → Material Symbols Outlined). Choisissez une autre police enregistrée
+ *   via `[font]`.
+ * - **Projection** (set à classes, ex. Font Awesome, ou SVG en ligne) : laissez `ktIcon` vide et
+ *   projetez votre markup dans l'élément ; la primitive ne fait que l'habiller (taille, couleur
+ *   héritée, alignement). Le contenu projeté **ne doit jamais être focusable** (l'hôte décoratif
+ *   porte `aria-hidden` : un descendant focusable violerait WCAG 4.1.2).
+ *
+ * Accessibilité : **décorative par défaut** (`aria-hidden`). Fournissez `[ariaLabel]` (ou un
+ * `aria-label` natif) pour une icône **porteuse de sens** (bascule en `role="img"`).
+ *
+ * @example
+ * ```html
+ * <!-- Ligature autonome, taille et couleur héritées du contexte ; `fill` = version remplie -->
+ * <span ktIcon="home"></span>
+ * <span ktIcon="favorite" fill size="2rem" style="color: var(--kt-primary)"></span>
+ *
+ * <!-- Set à classes (Font Awesome) : projection, ktIcon reste vide -->
+ * <span ktIcon><i class="fa-solid fa-user"></i></span>
+ *
+ * <!-- Icône porteuse de sens (nommée pour les lecteurs d'écran) -->
+ * <span ktIcon="error" ariaLabel="Erreur" style="color: var(--kt-danger)"></span>
+ * ```
+ */
+declare class KtIcon {
+    private readonly config;
+    private readonly auditEnabled;
+    private readonly platformId;
+    private readonly host;
+    private readonly nativeAriaLabel;
+    /** Nom de l'icône (ligature). Laisser vide pour projeter un set à classes / un SVG. @default '' */
+    readonly ktIcon: _angular_core.InputSignal<string>;
+    /** Alias de police d'icônes du registre (cf. {@link provideKtIcon}). @default `KtIconConfig.defaultFont` */
+    readonly font: _angular_core.InputSignal<string | undefined>;
+    /** Nom accessible : le fournir rend l'icône **porteuse de sens** (`role="img"`). Aligné sur `ktButton`.
+        @default undefined (icône décorative ; un `aria-label` natif reste toutefois préservé) */
+    readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
+    /** Taille de l'icône (longueur CSS, ex. `'24px'`, `'2rem'`, `'1.5em'`). @default `1.25em` (héritée du contexte) */
+    readonly size: _angular_core.InputSignal<string | undefined>;
+    /** Version **remplie** plutôt que contour, pour les polices variables à axe `FILL` (Material Symbols).
+        Force `FILL` à 1 en préservant les autres axes (graisse…) ; sans effet sur une police sans cet axe.
+        Nécessite une police chargée **avec l'axe FILL ajustable** (ex. Google Fonts :
+        `…Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200`).
+        @default false (contour) */
+    readonly fill: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Nom rendu en ligature : coupé, `null` si vide (aucun `::before`, laisse place à la projection). */
+    protected readonly renderedName: _angular_core.Signal<string | null>;
+    /** Libellé accessible résolu : input prioritaire, sinon `aria-label` natif préservé, sinon `null` (décorative). */
+    protected readonly accessibleLabel: _angular_core.Signal<string | null>;
+    /** Police résolue depuis le registre : alias explicite, sinon police par défaut du provider. */
+    private readonly resolvedFont;
+    protected readonly resolvedFamily: _angular_core.Signal<string | null>;
+    protected readonly resolvedWeight: _angular_core.Signal<string | null>;
+    protected readonly resolvedVariation: _angular_core.Signal<string | null>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KtIcon, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<KtIcon, "[ktIcon]", never, { "ktIcon": { "alias": "ktIcon"; "required": false; "isSignal": true; }; "font": { "alias": "font"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "fill": { "alias": "fill"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { KT_ICON_CONFIG, KtIcon, provideKtIcon };
+export type { KtIconConfig, KtIconFont, KtIconFontAlias, KtIconFontRegistry };

package/types/ktortu-aaa-layout.d.ts

@@ -77,11 +77,21 @@ declare class KtToolbarComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<KtToolbarComponent, "kt-toolbar", never, {}, {}, never, ["*"], true, never>;
 }
 
+/**
+ * Item de navigation : projette une icône dans son slot dédié + un libellé.
+ *
+ * Le slot d'icône accepte :
+ * - la directive `[ktIcon]` (primitive d'icône `@ktortu/aaa/icon`), forme canonique.
+ * - l'attribut de projection `kt-icon` (historique/legacy).
+ *
+ * Note : la classe `.kt-icon` (posée à l'exécution par la directive) n'est PAS un critère de
+ * projection valable (ng-content matche la forme statique du template) — d'où le sélecteur d'attribut.
+ */
 declare class KtNavItemComponent {
     label: _angular_core.InputSignal<string>;
     protected readonly layout: KtLayoutService;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<KtNavItemComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<KtNavItemComponent, "kt-nav-item", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; }, {}, never, ["[kt-icon]", "*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<KtNavItemComponent, "kt-nav-item", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; }, {}, never, ["[ktIcon], [kt-icon]", "*"], true, never>;
 }
 
 /**

package/types/ktortu-aaa.d.ts

@@ -5,6 +5,7 @@ export * from '@ktortu/aaa/dialog';
 export * from '@ktortu/aaa/disclosure';
 export * from '@ktortu/aaa/forms';
 export * from '@ktortu/aaa/i18n';
+export * from '@ktortu/aaa/icon';
 export * from '@ktortu/aaa/menu';
 export * from '@ktortu/aaa/snackbar';
 export * from '@ktortu/aaa/tabs';