@mk-kit/ui 0.56.0 → 0.58.0

package/types/mk-kit-ui-attention.d.ts

@@ -0,0 +1,223 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, OnDestroy, EnvironmentProviders } from '@angular/core';
+import * as _mk_kit_ui_core from '@mk-kit/ui/core';
+
+/** Options for {@link MkTabAttention}, set with {@link provideMkTabAttention}. */
+interface MkTabAttentionConfig {
+    /** Badge fill colour (any CSS colour). Default `#e53935`. */
+    badgeColor?: string;
+    /** Title blink period in ms while the tab is hidden. Default `1200`. */
+    blinkMs?: number;
+}
+declare const MK_TAB_ATTENTION_CONFIG: InjectionToken<MkTabAttentionConfig>;
+/** Register options for {@link MkTabAttention}. Optional — the defaults work. */
+declare function provideMkTabAttention(config: MkTabAttentionConfig): {
+    provide: InjectionToken<MkTabAttentionConfig>;
+    useValue: MkTabAttentionConfig;
+};
+/**
+ * Messenger-style tab attention: while unhandled work exists the favicon
+ * carries a red counter badge, and — only while the tab is hidden — the
+ * title alternates with "(N) label" so a pinned tab flashes in the tab strip.
+ * Focusing the tab stops the blinking (someone is looking) but keeps the
+ * badge until the count reaches zero. SSR-safe: every entry point bails
+ * without a `document`; the blink timer runs outside the Angular zone.
+ *
+ * ```ts
+ * private attention = inject(MkTabAttention);
+ * effect(() => this.attention.set(this.pending().length, 'new orders'));
+ * ```
+ */
+declare class MkTabAttention {
+    private readonly zone;
+    private readonly config;
+    private label;
+    private originalTitle;
+    private originalFavicon;
+    private blinkTimer;
+    private showingAttention;
+    private listening;
+    private readonly visibilityHandler;
+    /** The count currently shown (0 = nothing pending). */
+    readonly count: i0.WritableSignal<number>;
+    /** Update the pending count and the label used in the blinking title. */
+    set(count: number, label?: string): void;
+    /** Drop the badge and the blinking entirely and stop listening. */
+    clear(): void;
+    private sync;
+    private startBlink;
+    private stopBlink;
+    private toggleTitle;
+    private restoreTitle;
+    private faviconLink;
+    private setFavicon;
+    private restoreFavicon;
+    /** Coloured circle + white count, as an inline SVG data URI. */
+    private badgeFavicon;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MkTabAttention, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<MkTabAttention>;
+}
+
+/** One selectable alert sound. `url: null` = the synthesised chime. */
+interface MkSoundPreset {
+    id: string;
+    label: string;
+    url: string | null;
+}
+/** Options for {@link MkNotificationSound}. */
+interface MkNotificationSoundConfig {
+    /** Selectable sounds; the ids `custom` and `none` are reserved. Default: the chime only. */
+    presets?: MkSoundPreset[];
+    /** localStorage key for the on/off preference — a function so it can vary per tenant / user. */
+    storageKey?: () => string;
+    /** Output gain for file presets (0–1). Default `0.8`. */
+    volume?: number;
+}
+declare const MK_NOTIFICATION_SOUND_CONFIG: InjectionToken<MkNotificationSoundConfig>;
+/** Register presets / storage key for {@link MkNotificationSound}. Optional. */
+declare function provideMkNotificationSound(config: MkNotificationSoundConfig): {
+    provide: InjectionToken<MkNotificationSoundConfig>;
+    useValue: MkNotificationSoundConfig;
+};
+/** The always-available synthesised sound. */
+declare const MK_CHIME_PRESET: MkSoundPreset;
+/**
+ * Alert sounds for incoming work (orders, messages, tickets) with the
+ * browser's autoplay rules handled: an `AudioContext` stays suspended until a
+ * user gesture, so a sound fired by a WebSocket message would be silent. The
+ * context is unlocked when the user enables sound (a click) and lazily on the
+ * first interaction anywhere in the app. The default sound is synthesised
+ * (a short C–E–G chime) — nothing to ship, no CORS, lowest latency; file
+ * presets are fetched and decoded once and fall back to the chime when they
+ * fail. The on/off preference lives in localStorage under a configurable key.
+ *
+ * ```ts
+ * provideMkNotificationSound({ presets: [MK_CHIME_PRESET, { id: 'ding', label: 'Ding', url: '/assets/ding.wav' }] })
+ * sound.primeOnFirstInteraction();          // at app start
+ * sound.play(settings.newOrderSound);       // on an event, honours the device mute
+ * sound.preview('ding');                    // settings page test button
+ * ```
+ */
+declare class MkNotificationSound {
+    private readonly config;
+    private ctx;
+    private gesturePrimed;
+    /** Decoded file presets by url; null = fetch/decode failed. */
+    private readonly buffers;
+    /** The selectable presets (always includes the chime). */
+    get presets(): MkSoundPreset[];
+    private storageKey;
+    /** Whether the device has sound on. */
+    isEnabled(): boolean;
+    /** Whether the user ever answered the "enable sound?" question on this device. */
+    hasBeenAsked(): boolean;
+    /** Persist the preference; call from a click so audio unlocks at once. */
+    setEnabled(enabled: boolean): void;
+    /** Arm a one-time listener so the first pointer/key interaction unlocks audio. */
+    primeOnFirstInteraction(): void;
+    /** The default chime, if the device has sound on. */
+    chime(): void;
+    /**
+     * Play the sound configured for an event: a preset id, `custom` (with
+     * `customUrl`) or `none` (silent). Unknown ids and failed loads fall back
+     * to the chime. Honours the device mute.
+     */
+    play(soundId: string, customUrl?: string | null): void;
+    /** Same as `play()` but ignores the device mute — for settings test buttons. */
+    preview(soundId: string, customUrl?: string | null): void;
+    private playById;
+    private playUrl;
+    /** Ascending C5–E5–G5 chime (~0.75 s) with a bell-like timbre. */
+    private playChime;
+    private scheduleNote;
+    private unlock;
+    private ensureCtx;
+    private read;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MkNotificationSound, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<MkNotificationSound>;
+}
+
+/** Options for {@link provideMkSessionExpiry}. */
+interface MkSessionExpiryConfig {
+    /** Epoch ms when the session lapses, or `null` when there is none. Read reactively. */
+    expiresAt: () => number | null;
+    /** How long before the lapse the dialog appears. Default 2 minutes. */
+    warnBeforeMs?: number;
+    /** Extend the session (refresh the token). Resolve = extended, reject = nothing to extend. */
+    extend: () => Promise<unknown>;
+    /** End the session (sign out, navigate). */
+    onExpire: () => void;
+    /** Read reactively; `false` suspends the watcher (a kiosk / PIN mode, say). */
+    enabled?: () => boolean;
+}
+declare const MK_SESSION_EXPIRY_CONFIG: InjectionToken<MkSessionExpiryConfig>;
+/** Data handed to {@link MkSessionExpiryDialog}. */
+interface MkSessionExpiryDialogData {
+    expiresAt: number;
+    extend: () => Promise<unknown>;
+    onExpire: () => void;
+}
+/**
+ * Last call before a session ends: counts down and offers to extend.
+ * Reaching zero ends the session, so doing nothing still produces a definite,
+ * visible outcome. Opened by {@link MkSessionExpiry}; usable on its own.
+ */
+declare class MkSessionExpiryDialog implements OnDestroy {
+    protected readonly i18n: _mk_kit_ui_core.MkI18nStrings;
+    private readonly data;
+    private readonly ref;
+    private readonly zone;
+    protected readonly extending: i0.WritableSignal<boolean>;
+    private readonly remainingMs;
+    /** "1:04" — floored at zero. */
+    protected readonly countdown: i0.Signal<string>;
+    private readonly ticker;
+    ngOnDestroy(): void;
+    protected extend(): void;
+    protected signOut(): void;
+    private expire;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MkSessionExpiryDialog, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MkSessionExpiryDialog, "mk-session-expiry-dialog", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Watches `expiresAt()` and warns BEFORE the session lapses, so a session
+ * never ends silently: the dialog offers to extend, or signs out at zero.
+ * Re-arms itself whenever `expiresAt()` changes (every token rotation),
+ * runs the timer outside the Angular zone and only in the browser. Started
+ * automatically by {@link provideMkSessionExpiry}.
+ */
+declare class MkSessionExpiry {
+    private readonly config;
+    private readonly dialog;
+    private readonly zone;
+    private readonly injector;
+    private readonly isBrowser;
+    private timer;
+    private started;
+    /** Whether the dialog is currently open. */
+    readonly open: i0.WritableSignal<boolean>;
+    constructor();
+    /** Begin watching. Idempotent; called by the provider's initializer. */
+    start(): void;
+    private clear;
+    private schedule;
+    private warn;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MkSessionExpiry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<MkSessionExpiry>;
+}
+/**
+ * Register the session-expiry watcher; it starts with the application.
+ *
+ * ```ts
+ * provideMkSessionExpiry({
+ *   expiresAt: () => auth.tokenExpiresAt(),
+ *   extend: () => firstValueFrom(auth.refresh()),
+ *   onExpire: () => auth.logout(),
+ *   warnBeforeMs: 2 * 60_000,
+ * })
+ * ```
+ */
+declare function provideMkSessionExpiry(config: MkSessionExpiryConfig): EnvironmentProviders;
+
+export { MK_CHIME_PRESET, MK_NOTIFICATION_SOUND_CONFIG, MK_SESSION_EXPIRY_CONFIG, MK_TAB_ATTENTION_CONFIG, MkNotificationSound, MkSessionExpiry, MkSessionExpiryDialog, MkTabAttention, provideMkNotificationSound, provideMkSessionExpiry, provideMkTabAttention };
+export type { MkNotificationSoundConfig, MkSessionExpiryConfig, MkSessionExpiryDialogData, MkSoundPreset, MkTabAttentionConfig };

package/types/mk-kit-ui-core.d.ts

@@ -119,6 +119,60 @@ declare class MkThemeService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<MkThemeService>;
 }
 
+/** One of the eight kit accents (the Momentum palette). */
+type MkAccentKey = 'indigo' | 'blue' | 'teal' | 'violet' | 'coral' | 'lime' | 'pink' | 'bumblebee';
+/** `fill` = bars, rings and buttons · `ink` = small accent text on a light ground. */
+interface MkAccent {
+    fill: string;
+    ink: string;
+    name: string;
+}
+/** High-saturation, distinct, energising accents — the set the `momentum` preset was designed around. */
+declare const MK_ACCENTS: Record<MkAccentKey, MkAccent>;
+/** Picker order. */
+declare const MK_ACCENT_ORDER: readonly MkAccentKey[];
+/** The swatch a picker shows for an accent (bumblebee is the black / yellow split). */
+declare function mkAccentSwatch(key: MkAccentKey): string;
+/** `#rrggbb` → `rgba(r,g,b,a)`. */
+declare function mkHexAlpha(hex: string, alpha: number): string;
+/**
+ * Runtime accent — the user picks one of {@link MK_ACCENTS} and every kit
+ * control recolours: the service writes the `--mk-primary` family
+ * (`primary`, `-hover`, `-active`, `-subtle`, `-subtle-hover`,
+ * `-subtle-text`), `--mk-focus-ring`, `--mk-selected-bg` / `-text` and three
+ * accent tokens of its own — `--mk-accent`, `--mk-accent-ink`,
+ * `--mk-accent-glow` — onto `<html>`, and mirrors the key as
+ * `data-mk-accent`. Hover / active are a touch darker in light and a touch
+ * lighter in dark (it follows {@link MkThemeService}). The choice persists
+ * in `localStorage` (`mk-kit-accent`); nothing is written until `set()` is
+ * called, so an app that never picks keeps the preset's own primary.
+ *
+ * ```ts
+ * readonly accent = inject(MkAccentService);
+ * accent.set('coral');           // every button, ring and chip turns coral
+ * accent.key();                  // 'coral'
+ * mkAccentSwatch(accent.key());  // for the picker
+ * ```
+ */
+declare class MkAccentService {
+    private readonly document;
+    private readonly theme;
+    private readonly isBrowser;
+    private readonly _key;
+    /** The chosen accent, or `null` while the preset's own primary is in use. */
+    readonly key: _angular_core.Signal<MkAccentKey | null>;
+    /** The chosen accent's definition (indigo when none is chosen). */
+    readonly accent: _angular_core.Signal<MkAccent>;
+    constructor();
+    /** Pick an accent; persisted. */
+    set(key: MkAccentKey): void;
+    /** Back to the preset's own primary; the stored choice is cleared. */
+    reset(): void;
+    private readInitial;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkAccentService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MkAccentService>;
+}
+
 /** Named viewport ranges, mobile-first: each starts at its min-width. */
 type MkBreakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
 /** Min-widths (px) at which each named breakpoint begins; `xs` is everything below `sm`. */
@@ -780,6 +834,16 @@ interface MkI18nStrings {
     translationEditorReset: string;
     translationEditorExport: string;
     translationEditorKeys: string;
+    /** Session-expiry dialog (`@mk-kit/ui/attention`). */
+    sessionExpiryTitle: string;
+    sessionExpiryExtend: string;
+    sessionExpiryExtending: string;
+    sessionExpiryLogout: string;
+    sessionExpiryBody: (countdown: string) => string;
+    /** Barcode scanner (`@mk-kit/ui/media/scanner`). */
+    scannerTitle: string;
+    scannerHint: string;
+    scannerCameraError: string;
     /** Announced when a filterable list updates (autocomplete, multi-select, command palette). */
     resultsCount: (count: number) => string;
     /** Pagination: previous page control. */
@@ -1348,5 +1412,5 @@ declare function mkSignalErrorsToValidationErrors(errors: readonly MkSignalValid
  */
 declare function mkSignalErrorMessage(errors: readonly MkSignalValidationError[] | null | undefined, strings: MkValidationStrings, overrides?: MkErrorMessages): string | null;
 
-export { MK_BREAKPOINTS, MK_DEFAULT_BREAKPOINTS, MK_DEFAULT_DATE_NAMES, MK_DEFAULT_I18N, MK_DEFAULT_VALIDATION, MK_I18N, MK_OVERLAY_DATA, MK_OVERLAY_ROOT, MkAnchoredPanel, MkBreakpointService, MkFieldContext, MkFocusTrap, MkLiveAnnouncer, MkOverlayRef, MkOverlayService, MkThemeService, mkBodyLevelAncestor, mkFirstErrorMessage, mkGetFocusable, mkIsResponsive, mkMergeI18n, mkSignalErrorMessage, mkSignalErrorsToValidationErrors, mkValidatorChange, provideMkI18n };
-export type { MkAriaLivePoliteness, MkBlockEditorStrings, MkBreakpoint, MkBreakpoints, MkContrastPreference, MkDensity, MkErrorMessages, MkI18nOverrides, MkI18nStrings, MkOverlayConfig, MkOverlayRootFn, MkResolvedContrast, MkResolvedTheme, MkResponsive, MkSignalValidationError, MkSize, MkSortAnnounceDirection, MkThemePreference, MkTone, MkValidationStrings, MkValidatorChangeRef, MkVariant };
+export { MK_ACCENTS, MK_ACCENT_ORDER, MK_BREAKPOINTS, MK_DEFAULT_BREAKPOINTS, MK_DEFAULT_DATE_NAMES, MK_DEFAULT_I18N, MK_DEFAULT_VALIDATION, MK_I18N, MK_OVERLAY_DATA, MK_OVERLAY_ROOT, MkAccentService, MkAnchoredPanel, MkBreakpointService, MkFieldContext, MkFocusTrap, MkLiveAnnouncer, MkOverlayRef, MkOverlayService, MkThemeService, mkAccentSwatch, mkBodyLevelAncestor, mkFirstErrorMessage, mkGetFocusable, mkHexAlpha, mkIsResponsive, mkMergeI18n, mkSignalErrorMessage, mkSignalErrorsToValidationErrors, mkValidatorChange, provideMkI18n };
+export type { MkAccent, MkAccentKey, MkAriaLivePoliteness, MkBlockEditorStrings, MkBreakpoint, MkBreakpoints, MkContrastPreference, MkDensity, MkErrorMessages, MkI18nOverrides, MkI18nStrings, MkOverlayConfig, MkOverlayRootFn, MkResolvedContrast, MkResolvedTheme, MkResponsive, MkSignalValidationError, MkSize, MkSortAnnounceDirection, MkThemePreference, MkTone, MkValidationStrings, MkValidatorChangeRef, MkVariant };

package/types/mk-kit-ui-media-scanner.d.ts

@@ -0,0 +1,74 @@
+import * as _angular_core from '@angular/core';
+import { AfterViewInit, OnDestroy } from '@angular/core';
+import * as _mk_kit_ui_core from '@mk-kit/ui/core';
+import { MkOverlayRef } from '@mk-kit/ui/core';
+
+/** Symbologies the scanner reads; names follow `Html5QrcodeSupportedFormats`. */
+type MkBarcodeFormat = 'QR_CODE' | 'EAN_13' | 'EAN_8' | 'CODE_128' | 'CODE_39' | 'UPC_A' | 'UPC_E' | 'DATA_MATRIX' | 'ITF' | 'CODABAR';
+declare const MK_BARCODE_DEFAULT_FORMATS: MkBarcodeFormat[];
+/**
+ * Camera barcode / QR reader. Starts the rear camera when it appears, emits
+ * `scanned` once with the first decoded text and stops. The decoder
+ * (`html5-qrcode`, an optional peer dependency) is loaded on demand, so pages
+ * that only *offer* scanning ship nothing extra until a scan starts. Use
+ * inline, or through {@link MkBarcodeScannerDialog}.
+ *
+ * ```html
+ * <mk-barcode-scanner (scanned)="onCode($event)" (failed)="show($event)" />
+ * ```
+ */
+declare class MkBarcodeScanner implements AfterViewInit, OnDestroy {
+    protected readonly i18n: _mk_kit_ui_core.MkI18nStrings;
+    private readonly readerEl;
+    /** Symbologies to decode. Default: QR + the retail 1-D codes. */
+    readonly formats: _angular_core.InputSignal<MkBarcodeFormat[]>;
+    /** Frames per second offered to the decoder. Default 10. */
+    readonly fps: _angular_core.InputSignal<number>;
+    /** Show the built-in hint line above the viewfinder. Default `true`. */
+    readonly hint: _angular_core.InputSignal<boolean>;
+    /** Keep scanning after a hit instead of stopping. Default `false`. */
+    readonly continuous: _angular_core.InputSignal<boolean>;
+    /** Decoded text. */
+    readonly scanned: _angular_core.OutputEmitterRef<string>;
+    /** The camera could not start (permission, no device, insecure context). */
+    readonly failed: _angular_core.OutputEmitterRef<string>;
+    protected readonly error: _angular_core.WritableSignal<string | null>;
+    protected readonly scanning: _angular_core.WritableSignal<boolean>;
+    private scanner;
+    private destroyed;
+    private lastHit;
+    ngAfterViewInit(): Promise<void>;
+    ngOnDestroy(): void;
+    /** Stop the camera and release it. Safe to call twice. */
+    stop(): Promise<void>;
+    private onHit;
+    private fail;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkBarcodeScanner, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkBarcodeScanner, "mk-barcode-scanner", never, { "formats": { "alias": "formats"; "required": false; "isSignal": true; }; "fps": { "alias": "fps"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "continuous": { "alias": "continuous"; "required": false; "isSignal": true; }; }, { "scanned": "scanned"; "failed": "failed"; }, never, never, true, never>;
+}
+
+/** Optional data for {@link MkBarcodeScannerDialog}. */
+interface MkBarcodeScannerDialogData {
+    title?: string;
+    formats?: MkBarcodeFormat[];
+}
+/**
+ * The scanner in a dialog: resolves with the decoded text, or `null` when
+ * cancelled. Open it with `MkDialogService`:
+ *
+ * ```ts
+ * const code = await dialog.open<MkBarcodeScannerDialog, string | null>(MkBarcodeScannerDialog, { size: 'sm' }).afterClosed;
+ * if (code) this.search.setValue(code);
+ * ```
+ */
+declare class MkBarcodeScannerDialog {
+    protected readonly i18n: _mk_kit_ui_core.MkI18nStrings;
+    protected readonly data: MkBarcodeScannerDialogData | null;
+    protected readonly ref: MkOverlayRef<string | null, unknown>;
+    protected readonly defaultFormats: MkBarcodeFormat[];
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkBarcodeScannerDialog, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkBarcodeScannerDialog, "mk-barcode-scanner-dialog", never, {}, {}, never, never, true, never>;
+}
+
+export { MK_BARCODE_DEFAULT_FORMATS, MkBarcodeScanner, MkBarcodeScannerDialog };
+export type { MkBarcodeFormat, MkBarcodeScannerDialogData };

package/types/mk-kit-ui.d.ts

@@ -15,6 +15,7 @@ export * from '@mk-kit/ui/status';
 export * from '@mk-kit/ui/data';
 export * from '@mk-kit/ui/kanban';
 export * from '@mk-kit/ui/translate';
+export * from '@mk-kit/ui/attention';
 export * from '@mk-kit/ui/feedback';
 export * from '@mk-kit/ui/rich-text';
 export * from '@mk-kit/ui/block-editor';