@mk-kit/ui 0.34.0

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

@@ -0,0 +1,108 @@
+import * as _angular_platform_browser from '@angular/platform-browser';
+import { SafeHtml } from '@angular/platform-browser';
+import * as _angular_core from '@angular/core';
+import { EnvironmentProviders } from '@angular/core';
+import { MkSize } from '@mk-kit/ui/core';
+
+/**
+ * Icon — renders a registered SVG by `name`, or your own projected `<svg>`.
+ * The glyph inherits the current text colour (`currentColor`) and scales to the
+ * `size` box, so it composes cleanly inside buttons, inputs and menus.
+ *
+ * Decorative by default (`aria-hidden`); pass `label` to expose it as an image
+ * to assistive tech.
+ *
+ * ```html
+ * <mk-icon name="search" />
+ * <mk-icon name="trash" size="lg" label="Delete" />
+ * <button mkButton iconOnly aria-label="Menu"><mk-icon name="menu" /></button>
+ * <mk-icon><svg viewBox="0 0 24 24">…custom…</svg></mk-icon>
+ * ```
+ */
+declare class MkIcon {
+    private readonly registry;
+    /** Name of a registered icon (see {@link MkIconRegistry}). */
+    readonly name: _angular_core.InputSignal<string>;
+    /** Size: `sm`/`md`/`lg`, or a pixel number for a custom dimension. */
+    readonly size: _angular_core.InputSignal<number | MkSize>;
+    /** Accessible name. When set the icon becomes `role="img"`; otherwise hidden. */
+    readonly label: _angular_core.InputSignal<string>;
+    /** CSS length for the icon box (width = height = font-size). */
+    protected readonly dimension: _angular_core.Signal<string>;
+    /** Sanitized SVG for the named icon, or `null` (falls back to projection). */
+    protected readonly svg: _angular_core.Signal<_angular_platform_browser.SafeHtml | null>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkIcon, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkIcon, "mk-icon", never, { "name": { "alias": "name"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+
+/**
+ * IconRegistry — the name → SVG store behind `<mk-icon name="…">`. The built-in
+ * {@link MK_DEFAULT_ICONS} set is registered on construction; add your own SVGs
+ * (from a sprite, a design export, anything) with {@link register} /
+ * {@link registerIcons}.
+ *
+ * SVG markup is trusted verbatim (bypassed through `DomSanitizer`), so only
+ * register icons from sources you control — never user input.
+ *
+ * ```ts
+ * const reg = inject(MkIconRegistry);
+ * reg.register('logo', '<svg viewBox="0 0 24 24">…</svg>');
+ * reg.registerIcons({ save: '<svg…>', share: '<svg…>' });
+ * ```
+ */
+declare class MkIconRegistry {
+    private readonly sanitizer;
+    private readonly icons;
+    private readonly aliases;
+    constructor();
+    /** Register (or overwrite) a single named icon from raw SVG markup. */
+    register(name: string, svg: string): this;
+    /** Register many icons at once from a `{ name: svg }` map. */
+    registerIcons(icons: Readonly<Record<string, string>>): this;
+    /**
+     * Register alternative names that resolve to existing icons — e.g. map
+     * Material Symbols ligature names onto the built-in set
+     * (`{ delete: 'trash', expand_more: 'chevron-down' }`). A real icon
+     * registered under an alias name always wins over the alias.
+     */
+    registerAliases(aliases: Readonly<Record<string, string>>): this;
+    /** Sanitized SVG for a name (aliases resolved), or `null` when unknown. */
+    get(name: string): SafeHtml | null;
+    /** Whether an icon with this name (or alias) is registered. */
+    has(name: string): boolean;
+    /** All registered icon names (useful for a picker / catalogue). */
+    names(): string[];
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkIconRegistry, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MkIconRegistry>;
+}
+
+/** Name → SVG markup map of the default icons. */
+declare const MK_DEFAULT_ICONS: Readonly<Record<string, string>>;
+
+/**
+ * Material Symbols ligature names → built-in mk icon names. Lets templates
+ * written against `<mat-icon>delete</mat-icon>` conventions keep their icon
+ * names when migrating: `<mk-icon name="delete" />` renders the `trash`
+ * glyph once {@link provideMkMaterialIcons} is installed.
+ *
+ * Several Material names intentionally collapse onto one mk glyph (all the
+ * calendar variants → `calendar`, the delete variants → `trash`, …). Names
+ * not listed here have no sensible built-in equivalent — register your own
+ * SVG under the Material name via `MkIconRegistry.register`.
+ */
+declare const MK_MATERIAL_ICON_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Installs the Material Symbols name aliases into the {@link MkIconRegistry},
+ * so `<mk-icon name="delete" />`, `name="expand_more"`, `name="visibility"`
+ * etc. resolve to the built-in set. Add it to your bootstrap providers when
+ * migrating an app off `<mat-icon>` ligatures:
+ *
+ * ```ts
+ * bootstrapApplication(App, {
+ *   providers: [provideMkMaterialIcons()],
+ * });
+ * ```
+ */
+declare function provideMkMaterialIcons(): EnvironmentProviders;
+
+export { MK_DEFAULT_ICONS, MK_MATERIAL_ICON_ALIASES, MkIcon, MkIconRegistry, provideMkMaterialIcons };

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

@@ -0,0 +1,549 @@
+import * as _angular_core from '@angular/core';
+import { OnDestroy, TemplateRef } from '@angular/core';
+import * as _mk_kit_ui_core from '@mk-kit/ui/core';
+import { MkDropEvent } from '@mk-kit/ui/dnd';
+
+/** How the picture is scaled inside its frame (`object-fit`). */
+type MkImageFit = 'cover' | 'contain';
+/** Corner rounding applied to the frame of an {@link MkImage}. */
+type MkImageRounded = 'none' | 'md' | 'lg' | 'circle';
+/** Load lifecycle of an {@link MkImage}. */
+type MkImageState = 'loading' | 'loaded' | 'error';
+/**
+ * Image — an enhanced image block. While the picture loads it shows a skeleton
+ * shimmer, and when loading fails it swaps to a localised fallback panel
+ * (icon + text, never colour alone). The picture is wrapped in a `<figure>`
+ * with an optional `<figcaption>`, and changing `src` restarts the whole load
+ * cycle.
+ *
+ * ```html
+ * <mk-image
+ *   src="/photos/harbour.jpg"
+ *   alt="Harbour at dawn"
+ *   aspectRatio="16 / 9"
+ *   caption="The old harbour, photographed at dawn"
+ *   (loaded)="onLoaded()"
+ *   (errored)="onErrored()"
+ * />
+ *
+ * <!-- The hero: eager, high priority, and sized per breakpoint so a phone
+ *      does not download the desktop file. -->
+ * <mk-image
+ *   src="/photos/hero-1600.jpg"
+ *   srcset="/photos/hero-800.jpg 800w, /photos/hero-1600.jpg 1600w"
+ *   sizes="100vw"
+ *   alt=""
+ *   aspectRatio="16 / 9"
+ *   priority
+ * />
+ * ```
+ *
+ * `aspectRatio` is what keeps this from shifting layout: the frame reserves
+ * its box before the picture arrives, so nothing below it moves.
+ */
+declare class MkImage {
+    /** Localised strings (override globally via `provideMkI18n`). */
+    protected readonly i18n: _mk_kit_ui_core.MkI18nStrings;
+    /** Image URL. Changing it resets the block to its loading state. */
+    readonly src: _angular_core.InputSignal<string>;
+    /** Alt text, always reflected onto the `<img>`. Keep `''` for decorative images. */
+    readonly alt: _angular_core.InputSignal<string>;
+    /** Any CSS `aspect-ratio` value for the frame, e.g. `'1 / 1'` or `'16 / 9'`. */
+    readonly aspectRatio: _angular_core.InputSignal<string>;
+    /** How the picture fills the frame. */
+    readonly fit: _angular_core.InputSignal<MkImageFit>;
+    /** Corner rounding of the frame. */
+    readonly rounded: _angular_core.InputSignal<MkImageRounded>;
+    /** Caption rendered in a `<figcaption>` below the picture. */
+    readonly caption: _angular_core.InputSignal<string>;
+    /** Defer fetching until near the viewport (`loading="lazy"` vs `"eager"`). */
+    readonly lazy: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Mark this as the page's LCP image: fetched eagerly at high priority and
+     * decoded synchronously, and `lazy` is ignored. Use it on exactly ONE image
+     * per page — the hero. Marking several is worse than marking none, because
+     * they then compete for the same bandwidth the real LCP image needs.
+     *
+     * This does NOT emit a `<link rel=preload>`; the tag has to be in the HTML
+     * the server sends to beat the preload scanner, which a component rendered
+     * later cannot guarantee. Pair it with a preload hint for a background or
+     * late-rendered hero.
+     */
+    readonly priority: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Responsive candidates, passed through verbatim to the `<img>`. Serving a
+     * 2048px file into a 600px slot is one of the most common LCP mistakes, and
+     * this is the fix; pair with {@link sizes}.
+     */
+    readonly srcset: _angular_core.InputSignal<string>;
+    /** `sizes` attribute — how wide the image renders at each breakpoint. */
+    readonly sizes: _angular_core.InputSignal<string>;
+    /** Emits once the picture has finished loading. */
+    readonly loaded: _angular_core.OutputEmitterRef<void>;
+    /** Emits when the picture fails to load and the fallback panel is shown. */
+    readonly errored: _angular_core.OutputEmitterRef<void>;
+    /** `loading` attribute: priority always wins over `lazy`. */
+    protected readonly loadingAttr: _angular_core.Signal<"eager" | "lazy">;
+    /** Load lifecycle; snaps back to `'loading'` whenever `src` changes. */
+    protected readonly state: _angular_core.WritableSignal<MkImageState>;
+    protected onLoad(): void;
+    protected onError(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkImage, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkImage, "mk-image", ["mkImage"], { "src": { "alias": "src"; "required": true; "isSignal": true; }; "alt": { "alias": "alt"; "required": false; "isSignal": true; }; "aspectRatio": { "alias": "aspectRatio"; "required": false; "isSignal": true; }; "fit": { "alias": "fit"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; "caption": { "alias": "caption"; "required": false; "isSignal": true; }; "lazy": { "alias": "lazy"; "required": false; "isSignal": true; }; "priority": { "alias": "priority"; "required": false; "isSignal": true; }; "srcset": { "alias": "srcset"; "required": false; "isSignal": true; }; "sizes": { "alias": "sizes"; "required": false; "isSignal": true; }; }, { "loaded": "loaded"; "errored": "errored"; }, never, never, true, never>;
+}
+
+/** A single image shown by {@link MkLightboxService}. */
+interface MkLightboxItem {
+    /** Image URL. */
+    src: string;
+    /** Alternative text for the image. */
+    alt?: string;
+    /** Optional caption rendered below the image. */
+    caption?: string;
+}
+/** Data injected into {@link MkLightbox} via `MK_OVERLAY_DATA`. */
+interface MkLightboxData {
+    /** The images to page through. */
+    items: readonly MkLightboxItem[];
+    /** Index of the image shown first (already clamped into range). */
+    startIndex: number;
+}
+/**
+ * Fullscreen image lightbox — opens a set of images in a modal overlay with
+ * looping previous/next navigation, captions, a counter, keyboard support
+ * (Arrow keys, Home/End, Escape) and focus trapping, all powered by
+ * {@link MkOverlayService}.
+ *
+ * ```ts
+ * private readonly lightbox = inject(MkLightboxService);
+ *
+ * viewPhoto(index: number): void {
+ *   this.lightbox.open(
+ *     [
+ *       { src: '/photos/1.jpg', alt: 'Harbour at dawn', caption: 'Dawn' },
+ *       { src: '/photos/2.jpg', alt: 'Old town square' },
+ *     ],
+ *     index,
+ *   );
+ * }
+ * ```
+ */
+declare class MkLightboxService {
+    private readonly overlay;
+    private readonly i18n;
+    /**
+     * Open the lightbox over the page. Does nothing when `items` is empty.
+     * `startIndex` is clamped into `[0, items.length - 1]`.
+     */
+    open(items: readonly MkLightboxItem[], startIndex?: number): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkLightboxService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MkLightboxService>;
+}
+
+/**
+ * Internal overlay component backing {@link MkLightboxService}. Renders the
+ * current image near-fullscreen over the overlay scrim with a caption bar,
+ * an `imageOf` counter, a close button and looping previous/next navigation.
+ *
+ * Keyboard: `ArrowLeft`/`ArrowRight` navigate, `Home`/`End` jump to the first
+ * or last image. `Escape` and backdrop clicks are handled by the overlay
+ * itself (`closeOnEscape` / `closeOnBackdropClick`), so they are deliberately
+ * not re-handled here.
+ *
+ * Open it via the service — not by placing `<mk-lightbox>` in a template:
+ *
+ * ```ts
+ * inject(MkLightboxService).open(items, 2);
+ * ```
+ */
+declare class MkLightbox {
+    private readonly ref;
+    private readonly data;
+    /** Localised strings (override globally via `provideMkI18n`). */
+    protected readonly i18n: _mk_kit_ui_core.MkI18nStrings;
+    /** The images being paged through. */
+    protected readonly items: readonly MkLightboxItem[];
+    /** Total number of images. */
+    protected readonly total: number;
+    /** Index of the currently displayed image. */
+    protected readonly index: _angular_core.WritableSignal<number>;
+    /** The currently displayed item. */
+    protected readonly current: _angular_core.Signal<MkLightboxItem>;
+    /** Localised "Image i of n" counter text. */
+    protected readonly counter: _angular_core.Signal<string>;
+    /** `true` while the current image is still loading. */
+    protected readonly loading: _angular_core.WritableSignal<boolean>;
+    /** `true` when the current image failed to load. */
+    protected readonly failed: _angular_core.WritableSignal<boolean>;
+    /** Show the previous image, wrapping from the first to the last. */
+    protected previous(): void;
+    /** Show the next image, wrapping from the last back to the first. */
+    protected next(): void;
+    /** Jump to `index`, resetting the loading/error state. */
+    protected goTo(index: number): void;
+    /** Close the surrounding overlay. */
+    protected close(): void;
+    /** Current image finished loading — hide the spinner. */
+    protected onLoad(): void;
+    /** Current image failed — show the localised failure message instead. */
+    protected onError(): void;
+    /**
+     * Host keydown handler. Escape is intentionally not handled here — the
+     * overlay's `closeOnEscape` already closes the lightbox.
+     */
+    protected onKeydown(event: Event): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkLightbox, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkLightbox, "mk-lightbox", never, {}, {}, never, never, true, never>;
+}
+
+/** A single picture inside an {@link MkImageGallery}. */
+interface MkGalleryItem {
+    /** Full-size image URL (what the lightbox opens). */
+    src: string;
+    /** Optional smaller thumbnail URL for the tile; falls back to `src`. */
+    thumb?: string;
+    /** Alt text; also drives the tile's accessible label. */
+    alt?: string;
+    /** Optional caption forwarded to the lightbox. */
+    caption?: string;
+}
+/** Tile arrangement of an {@link MkImageGallery}. */
+type MkImageGalleryLayout = 'grid' | 'masonry' | 'strip';
+/** Payload of the {@link MkImageGallery.itemClick} output. */
+interface MkGalleryItemClick {
+    /** The clicked picture. */
+    item: MkGalleryItem;
+    /** Its index within `items`. */
+    index: number;
+}
+/**
+ * Image gallery — a wall of clickable picture tiles built on {@link MkImage}.
+ * Choose a uniform `grid`, a natural-ratio `masonry` flow, or a snap-scrolling
+ * horizontal `strip`. Clicking a tile opens the shared {@link MkLightboxService}
+ * at that picture (full-size `src`, not the thumb) and always emits
+ * `itemClick`. With `max` set, only the first `max` tiles render and the last
+ * one carries a "+N" overflow scrim that opens the rest in the lightbox.
+ *
+ * ```html
+ * <mk-image-gallery
+ *   [items]="[
+ *     { src: '/photos/1.jpg', thumb: '/thumbs/1.jpg', alt: 'Harbour at dawn' },
+ *     { src: '/photos/2.jpg', alt: 'Old town square', caption: 'Kraków' },
+ *   ]"
+ *   [columns]="4"
+ *   [max]="8"
+ *   aspectRatio="4 / 3"
+ *   (itemClick)="onItemClick($event)"
+ * />
+ * ```
+ */
+declare class MkImageGallery {
+    private readonly lightboxService;
+    /** Localised strings (override globally via `provideMkI18n`). */
+    protected readonly i18n: _mk_kit_ui_core.MkI18nStrings;
+    /** Pictures to show. */
+    readonly items: _angular_core.InputSignal<readonly MkGalleryItem[]>;
+    /** Tile arrangement. */
+    readonly layout: _angular_core.InputSignal<MkImageGalleryLayout>;
+    /** Grid/masonry column count; also sets the visible tile count of a strip. */
+    readonly columns: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** When set, show only the first `max` tiles plus a "+N" overflow tile. */
+    readonly max: _angular_core.InputSignal<number | null>;
+    /** Open the shared lightbox on tile click. */
+    readonly lightbox: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** CSS aspect-ratio of grid/strip tiles (masonry keeps natural ratios). */
+    readonly aspectRatio: _angular_core.InputSignal<string>;
+    /** Corner rounding of the tiles. */
+    readonly rounded: _angular_core.InputSignal<MkImageRounded>;
+    /** Emits on every tile click (also when the lightbox opens). */
+    readonly itemClick: _angular_core.OutputEmitterRef<MkGalleryItemClick>;
+    /** Tiles actually rendered — the first `max` when `max` is set. */
+    protected readonly visibleItems: _angular_core.Signal<readonly MkGalleryItem[]>;
+    /** How many pictures the trailing "+N" tile stands for (0 = no overflow). */
+    protected readonly overflowCount: _angular_core.Signal<number>;
+    /** Frame ratio forwarded to the tiles (`'auto'` in masonry). */
+    protected readonly tileAspectRatio: _angular_core.Signal<string>;
+    /**
+     * Accessible label of tile `index`: `viewImage(alt)` when the picture has
+     * alt text, else positional `imageOf(...)`; the overflow tile appends "+N".
+     */
+    protected tileLabel(index: number): string;
+    protected onTileClick(index: number): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkImageGallery, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkImageGallery, "mk-image-gallery", ["mkImageGallery"], { "items": { "alias": "items"; "required": true; "isSignal": true; }; "layout": { "alias": "layout"; "required": false; "isSignal": true; }; "columns": { "alias": "columns"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "lightbox": { "alias": "lightbox"; "required": false; "isSignal": true; }; "aspectRatio": { "alias": "aspectRatio"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; }, { "itemClick": "itemClick"; }, never, never, true, never>;
+}
+
+/**
+ * Base cover scale for an image in a viewport — the smallest scale at which
+ * `imgW × imgH` fully covers `vpW × vpH` (object-fit: cover). Returns `1`
+ * for degenerate (non-positive) dimensions.
+ */
+declare function mkCoverScale(imgW: number, imgH: number, vpW: number, vpH: number): number;
+/**
+ * Clamp a pan offset (CSS px, measured from the viewport centre to the image
+ * centre) so the image scaled by `scale` still covers the viewport — no empty
+ * edges. When the scaled image is not larger than the viewport on an axis the
+ * offset collapses to `0` (centred).
+ */
+declare function mkClampPan(x: number, y: number, imgW: number, imgH: number, vpW: number, vpH: number, scale: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Source rect (in natural image pixels) of the crop region visible through
+ * the viewport. `scale` maps natural pixels to CSS pixels (cover scale ×
+ * zoom); `panX`/`panY` are the CSS-px offsets of the image centre from the
+ * viewport centre. The rect is clamped inside the image bounds.
+ */
+declare function mkCropRect(imgNaturalW: number, imgNaturalH: number, vpW: number, vpH: number, scale: number, panX: number, panY: number): {
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+};
+type CropStatus = 'loading' | 'loaded' | 'error';
+/**
+ * ImageCropper — pan-and-zoom crop control for avatars, covers and media uploads.
+ * The image covers a fixed-aspect viewport (object-fit-cover style); the user
+ * drags to pan, scrolls / pinch-zooms via the slider or `+`/`−` controls, and
+ * `crop()` renders the visible region to a data-URL on an offscreen canvas.
+ *
+ * Pan is always clamped so the image keeps covering the viewport, a
+ * rule-of-thirds grid appears while dragging, and `round` overlays a circular
+ * scrim for avatar crops (the exported bitmap stays rectangular). The crop
+ * area is keyboard operable: Arrow keys pan by 10px (1px with Shift), `+`/`-`
+ * zoom.
+ *
+ * ```html
+ * <mk-image-cropper #cropper src="/assets/photo.jpg" [aspect]="1" round />
+ * <button mkButton (click)="avatar = cropper.crop({ size: 512 })">Save</button>
+ * ```
+ */
+declare class MkImageCropper implements OnDestroy {
+    private readonly isBrowser;
+    /** Localised strings (override globally via `provideMkI18n`). */
+    protected readonly i18n: _mk_kit_ui_core.MkI18nStrings;
+    private readonly viewportRef;
+    private readonly imageRef;
+    /** Image URL or data-URL to crop. */
+    readonly src: _angular_core.InputSignal<string>;
+    /**
+     * Aspect ratio (width / height) of the crop viewport, e.g. `1` for a
+     * square or `16 / 9`. `null` makes the viewport fill its container.
+     */
+    readonly aspect: _angular_core.InputSignal<number | null>;
+    /**
+     * Circular mask overlay for avatar crops. Purely visual — the exported
+     * bitmap from `crop()` stays rectangular.
+     */
+    readonly round: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Lowest allowed zoom factor. */
+    readonly minZoom: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Highest allowed zoom factor. */
+    readonly maxZoom: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Disable panning and zooming. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * `crossorigin` for the internal `<img>`. Set to `'anonymous'` when
+     * cropping CORS-enabled remote images — without it the canvas is tainted
+     * and `crop()` returns `null`. Same-origin and data-URL sources don't
+     * need it.
+     */
+    readonly crossOrigin: _angular_core.InputSignal<"anonymous" | "use-credentials" | null>;
+    /** Accessible name for the crop area (defaults to the i18n `zoom` label). */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /** Emits on any pan or zoom change. */
+    readonly changed: _angular_core.OutputEmitterRef<void>;
+    /** Emits when the image fails to load. */
+    readonly imageError: _angular_core.OutputEmitterRef<void>;
+    /** Two-way zoom factor, clamped to `[minZoom, maxZoom]`. */
+    readonly zoom: _angular_core.ModelSignal<number>;
+    private readonly natW;
+    private readonly natH;
+    private readonly vpW;
+    private readonly vpH;
+    private readonly panX;
+    private readonly panY;
+    protected readonly status: _angular_core.WritableSignal<CropStatus>;
+    protected readonly dragging: _angular_core.WritableSignal<boolean>;
+    private dragStart;
+    private resizeObserver?;
+    private readonly coverScale;
+    private readonly totalScale;
+    /** CSS transform applied to the image element. */
+    protected readonly imageTransform: _angular_core.Signal<string>;
+    constructor();
+    ngOnDestroy(): void;
+    /** Centre the image and reset zoom to 1 (clamped to `minZoom`). */
+    reset(): void;
+    /**
+     * Draw the visible crop region to an offscreen canvas and return it as a
+     * data-URL (longest edge capped at `options.size ?? 1024`). Returns `null`
+     * when the image is not loaded or the canvas is unavailable (SSR, jsdom).
+     */
+    /**
+     * The visible crop region in natural image pixels — what `crop()` would
+     * rasterise, without touching a canvas. Use it when the backend performs
+     * the actual crop from the master image (no client-side quality loss).
+     * Returns `null` until the image has loaded and the viewport is measured.
+     */
+    cropRect(): {
+        sx: number;
+        sy: number;
+        sw: number;
+        sh: number;
+    } | null;
+    crop(options?: {
+        type?: string;
+        quality?: number;
+        size?: number;
+    }): string | null;
+    protected onImageLoad(event: Event): void;
+    protected onImageError(): void;
+    protected onPointerDown(event: PointerEvent): void;
+    protected onPointerMove(event: PointerEvent): void;
+    protected onPointerUp(): void;
+    private readonly onWheel;
+    protected onRangeInput(event: Event): void;
+    protected stepZoom(direction: 1 | -1): void;
+    /**
+     * Zoom towards the viewport centre: the pan offset scales with the zoom
+     * ratio so the image point at the centre stays put, then re-clamps.
+     */
+    protected zoomTo(next: number): void;
+    protected onKeydown(event: KeyboardEvent): void;
+    private clampZoom;
+    private panTo;
+    /** Capture the viewport's CSS size (initial render + every resize). */
+    private measure;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkImageCropper, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkImageCropper, "mk-image-cropper", ["mkImageCropper"], { "src": { "alias": "src"; "required": true; "isSignal": true; }; "aspect": { "alias": "aspect"; "required": false; "isSignal": true; }; "round": { "alias": "round"; "required": false; "isSignal": true; }; "minZoom": { "alias": "minZoom"; "required": false; "isSignal": true; }; "maxZoom": { "alias": "maxZoom"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "crossOrigin": { "alias": "crossOrigin"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "zoom": { "alias": "zoom"; "required": false; "isSignal": true; }; }, { "changed": "changed"; "imageError": "imageError"; "zoom": "zoomChange"; }, never, never, true, never>;
+}
+
+/** A single asset displayed as a tile in {@link MkMediaGallery}. */
+interface MkMediaItem {
+    /** Stable identity used for tracking, selection and reorder events. */
+    id: string;
+    /** Full-size image URL (used for the thumbnail when `thumb` is omitted). */
+    src: string;
+    /** Optional dedicated thumbnail URL shown in the grid. */
+    thumb?: string;
+    /** Display name shown under the thumbnail; also names the selection checkbox. */
+    name: string;
+    /** Alternative text describing the image; falls back to `name` for labels. */
+    alt?: string;
+    /** Optional caption/meta line shown under the name (e.g. "1.2 MB · JPG"). */
+    meta?: string;
+}
+/** Emitted by {@link MkMediaGallery} after a tile has been reordered. */
+interface MkMediaReorderEvent {
+    /** Index the item was dragged from. */
+    from: number;
+    /** Index the item was dropped at. */
+    to: number;
+    /** The full item array after the move (same reference as the updated model). */
+    items: MkMediaItem[];
+}
+/**
+ * Marks an `<ng-template>` as the per-tile action bar for {@link MkMediaGallery}.
+ * The template's implicit context is the {@link MkMediaItem}, so consumers can
+ * destructure it with `let-item`. The gallery renders it into each tile's
+ * top-right action bar (revealed on hover / focus-within, always visible on
+ * touch devices); the consumer supplies the buttons and their handlers.
+ *
+ * ```html
+ * <mk-media-gallery [items]="assets()">
+ *   <ng-template mkMediaActions let-item>
+ *     <button mkButton size="sm" variant="ghost" (click)="edit(item)">Edit</button>
+ *   </ng-template>
+ * </mk-media-gallery>
+ * ```
+ */
+declare class MkMediaActions {
+    /** The projected action-bar template, rendered once per tile. */
+    readonly template: TemplateRef<{
+        $implicit: MkMediaItem;
+    }>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkMediaActions, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkMediaActions, "[mkMediaActions]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Media gallery — a management grid of image tiles for admin media libraries.
+ * Each tile shows a square thumbnail (a labelled preview button emitting
+ * {@link itemClick}), the item's name and optional meta line, an optional
+ * selection checkbox (two-way `selection` model of selected ids) and an
+ * optional consumer-projected action bar ({@link MkMediaActions}).
+ *
+ * With `reorderable`, tiles become draggable via the dnd group's
+ * `[mkDropList]` / `[mkDrag]` directives — pointer and keyboard dragging
+ * (WCAG 2.1.1) both included. Each drop immutably updates the two-way `items`
+ * model and emits {@link reordered}.
+ *
+ * Clicking a tile always means "open/preview" — selection only toggles through
+ * the checkbox, never on tile click.
+ *
+ * ```html
+ * <mk-media-gallery
+ *   [(items)]="assets"
+ *   [(selection)]="selectedIds"
+ *   selectable
+ *   reorderable
+ *   [columns]="5"
+ *   (itemClick)="openPreview($event)"
+ *   (reordered)="persistOrder($event)"
+ * >
+ *   <ng-template mkMediaActions let-item>
+ *     <button mkButton size="sm" variant="ghost" (click)="edit(item)">Edit</button>
+ *     <button mkButton size="sm" variant="ghost" tone="danger" (click)="remove(item)">
+ *       Delete
+ *     </button>
+ *   </ng-template>
+ * </mk-media-gallery>
+ * ```
+ */
+declare class MkMediaGallery {
+    /** Localized strings (region label, checkbox/preview labels, empty state). */
+    protected readonly i18n: _mk_kit_ui_core.MkI18nStrings;
+    /** The gallery's items (two-way). Replaced immutably on every reorder drop. */
+    readonly items: _angular_core.ModelSignal<MkMediaItem[]>;
+    /** Ids of the currently selected items (two-way). */
+    readonly selection: _angular_core.ModelSignal<string[]>;
+    /** Show a selection checkbox on every tile. */
+    readonly selectable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Allow drag-and-drop (pointer + keyboard) reordering of the tiles. */
+    readonly reorderable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Number of grid columns. */
+    readonly columns: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Accessible name of the gallery region. Defaults to `i18n.mediaLibrary`. */
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    /** Emitted when a tile's preview button is activated (click/Enter/Space). */
+    readonly itemClick: _angular_core.OutputEmitterRef<MkMediaItem>;
+    /** Emitted after a drop has updated the `items` model. */
+    readonly reordered: _angular_core.OutputEmitterRef<MkMediaReorderEvent>;
+    /** Optional consumer-projected per-tile action bar (`$implicit` = item). */
+    protected readonly actions: _angular_core.Signal<MkMediaActions | undefined>;
+    /** Whether the item with `id` is currently selected. */
+    protected isSelected(id: string): boolean;
+    /** Sync the two-way `selection` model with the checkbox's native state. */
+    protected onCheckboxChange(item: MkMediaItem, event: Event): void;
+    /** Emit {@link itemClick} for the tile's preview button. */
+    protected onPreviewClick(item: MkMediaItem): void;
+    /**
+     * Apply a drop from the dnd module: move the item on a copy of `items`,
+     * write the copy back to the two-way model and emit {@link reordered}.
+     */
+    protected onDrop(event: MkDropEvent<MkMediaItem>): void;
+    /**
+     * Keep events from the tile's nested controls (checkbox, action buttons)
+     * inside those controls: without this, Space/Enter on the checkbox or an
+     * action button would bubble to the surrounding `[mkDrag]` host and pick the
+     * tile up instead, and a pointer press would start a drag session. Native
+     * behavior is untouched — only propagation stops.
+     */
+    protected stopEvent(event: Event): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkMediaGallery, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkMediaGallery, "mk-media-gallery", ["mkMediaGallery"], { "items": { "alias": "items"; "required": false; "isSignal": true; }; "selection": { "alias": "selection"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; "reorderable": { "alias": "reorderable"; "required": false; "isSignal": true; }; "columns": { "alias": "columns"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, { "items": "itemsChange"; "selection": "selectionChange"; "itemClick": "itemClick"; "reordered": "reordered"; }, ["actions"], never, true, never>;
+}
+
+export { MkImage, MkImageCropper, MkImageGallery, MkLightbox, MkLightboxService, MkMediaActions, MkMediaGallery, mkClampPan, mkCoverScale, mkCropRect };
+export type { MkGalleryItem, MkGalleryItemClick, MkImageFit, MkImageGalleryLayout, MkImageRounded, MkImageState, MkLightboxData, MkLightboxItem, MkMediaItem, MkMediaReorderEvent };