@muxima-ui/core 1.2.0 → 1.4.0

package/types/muxima-ui-core-image-cropper.d.ts

@@ -0,0 +1,105 @@
+import * as _angular_core from '@angular/core';
+
+/** Rectângulo em píxeis. */
+interface MxRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Puxadores de redimensionar: cantos e lados. */
+type MxCropHandle = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
+/** Mantém o rectângulo dentro dos limites, sem mudar o tamanho (a não ser que não caiba). */
+declare function mxClampRect(r: MxRect, bounds: MxRect): MxRect;
+/** Maior rectângulo com a proporção dada, centrado nos limites (ocupa `fill` do espaço). */
+declare function mxCenteredRect(bounds: MxRect, ratio: number | null, fill?: number): MxRect;
+/**
+ * Redimensiona a partir de um puxador por (dx, dy), respeitando a proporção, o tamanho
+ * mínimo e os limites. O lado oposto ao puxador fica parado.
+ */
+declare function mxResizeRect(r: MxRect, handle: MxCropHandle, dx: number, dy: number, bounds: MxRect, ratio: number | null, min?: number): MxRect;
+
+/** Área recortada em píxeis da imagem original, com a rotação aplicada antes. */
+interface MxCropArea extends MxRect {
+    rotation: number;
+}
+/**
+ * Recortar uma imagem antes de a enviar: arrastar a área, redimensionar pelos cantos,
+ * zoom e rodar. Com teclado: setas movem a área, Alt + setas mudam o tamanho (Shift para
+ * passos maiores); cada mudança é anunciada.
+ *
+ * ```html
+ * <mx-image-cropper #c [src]="ficheiro" [aspectRatio]="1" round />
+ * <button mxButton (click)="c.toBlob().then(enviar)">Guardar</button>
+ * ```
+ *
+ * `src` aceita um URL ou um File. `toBlob()` devolve a imagem recortada na resolução original.
+ */
+declare class MxImageCropper {
+    readonly src: _angular_core.InputSignal<string | File | Blob | null>;
+    readonly alt: _angular_core.InputSignal<string>;
+    /** Largura / altura da área (1 = quadrado, 16/9...). null = livre. */
+    readonly aspectRatio: _angular_core.InputSignal<number | null>;
+    /** Máscara redonda (fotografias de perfil). toBlob devolve PNG com cantos transparentes. */
+    readonly round: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly controls: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly height: _angular_core.InputSignal<string>;
+    /** Tamanho mínimo da área no ecrã, em px. */
+    readonly minSize: _angular_core.InputSignalWithTransform<number, unknown>;
+    readonly zoom: _angular_core.ModelSignal<number>;
+    readonly rotation: _angular_core.ModelSignal<number>;
+    readonly helpText: _angular_core.InputSignal<string>;
+    readonly zoomText: _angular_core.InputSignal<string>;
+    readonly rotateLeftText: _angular_core.InputSignal<string>;
+    readonly rotateRightText: _angular_core.InputSignal<string>;
+    readonly resetText: _angular_core.InputSignal<string>;
+    /** Área recortada em píxeis da imagem original. */
+    readonly areaChange: _angular_core.OutputEmitterRef<MxCropArea>;
+    private readonly stage;
+    private readonly img;
+    private readonly announcer;
+    protected readonly helpId: string;
+    protected readonly handles: MxCropHandle[];
+    protected readonly url: _angular_core.WritableSignal<string | null>;
+    protected readonly natural: _angular_core.WritableSignal<{
+        w: number;
+        h: number;
+    }>;
+    private readonly stageSize;
+    protected readonly ready: _angular_core.WritableSignal<boolean>;
+    readonly box: _angular_core.WritableSignal<MxRect>;
+    protected readonly live: _angular_core.WritableSignal<string>;
+    private objectUrl;
+    private liveTimer?;
+    /** Escala que faz a imagem caber no palco, vezes o zoom. */
+    private readonly fit;
+    protected readonly scale: _angular_core.Signal<number>;
+    protected readonly zoomPct: _angular_core.Signal<number>;
+    /** Rectângulo da imagem no palco (onde a área pode estar). */
+    private readonly bounds;
+    /** Área em píxeis da imagem (rodada). */
+    readonly area: _angular_core.Signal<MxCropArea>;
+    protected readonly boxLabel: _angular_core.Signal<string>;
+    constructor();
+    private measure;
+    protected onLoad(): void;
+    /** Volta ao zoom 1, sem rotação, área centrada. */
+    reset(): void;
+    setZoom(z: number): void;
+    rotate(deg: number): void;
+    private say;
+    protected onKeydown(e: KeyboardEvent): void;
+    private drag;
+    protected startMove(e: PointerEvent): void;
+    protected startResize(e: PointerEvent, h: MxCropHandle): void;
+    /** Desenha o recorte num canvas na resolução original. */
+    toCanvas(): HTMLCanvasElement;
+    /** Recorte como Blob (PNG por omissão; com `round` é sempre PNG). */
+    toBlob(type?: string, quality?: number): Promise<Blob | null>;
+    toDataURL(type?: string, quality?: number): string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MxImageCropper, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MxImageCropper, "mx-image-cropper", ["mxImageCropper"], { "src": { "alias": "src"; "required": false; "isSignal": true; }; "alt": { "alias": "alt"; "required": false; "isSignal": true; }; "aspectRatio": { "alias": "aspectRatio"; "required": false; "isSignal": true; }; "round": { "alias": "round"; "required": false; "isSignal": true; }; "controls": { "alias": "controls"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "minSize": { "alias": "minSize"; "required": false; "isSignal": true; }; "zoom": { "alias": "zoom"; "required": false; "isSignal": true; }; "rotation": { "alias": "rotation"; "required": false; "isSignal": true; }; "helpText": { "alias": "helpText"; "required": false; "isSignal": true; }; "zoomText": { "alias": "zoomText"; "required": false; "isSignal": true; }; "rotateLeftText": { "alias": "rotateLeftText"; "required": false; "isSignal": true; }; "rotateRightText": { "alias": "rotateRightText"; "required": false; "isSignal": true; }; "resetText": { "alias": "resetText"; "required": false; "isSignal": true; }; }, { "zoom": "zoomChange"; "rotation": "rotationChange"; "areaChange": "areaChange"; }, never, never, true, never>;
+}
+
+export { MxImageCropper, mxCenteredRect, mxClampRect, mxResizeRect };
+export type { MxCropArea, MxCropHandle, MxRect };

package/types/muxima-ui-core-kanban.d.ts

@@ -0,0 +1,83 @@
+import * as _angular_core from '@angular/core';
+import { TemplateRef } from '@angular/core';
+import { CdkDrag, CdkDropList, CdkDragDrop } from '@angular/cdk/drag-drop';
+
+interface MxKanbanColumn<T = any> {
+    id: string;
+    title: string;
+    items: T[];
+    /** Máximo de cartões na coluna (WIP). Acima disso não se larga lá. */
+    limit?: number;
+}
+interface MxKanbanMove<T = any> {
+    item: T;
+    from: string;
+    to: string;
+    fromIndex: number;
+    toIndex: number;
+}
+/** Conteúdo do cartão: `<ng-template mxKanbanCard let-item let-column="column">`. */
+declare class MxKanbanCard {
+    readonly template: TemplateRef<any>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MxKanbanCard, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MxKanbanCard, "ng-template[mxKanbanCard]", never, {}, {}, never, never, true, never>;
+}
+/** Rodapé de cada coluna (ex.: botão "Adicionar"): `<ng-template mxKanbanColumnFooter let-column>`. */
+declare class MxKanbanColumnFooter {
+    readonly template: TemplateRef<any>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MxKanbanColumnFooter, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MxKanbanColumnFooter, "ng-template[mxKanbanColumnFooter]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Quadro Kanban: cartões em colunas, com arrastar e largar (rato e toque) e mover com
+ * o teclado. Num cartão: Espaço agarra, setas movem (cima e baixo na coluna, esquerda e
+ * direita entre colunas), Espaço larga e Esc cancela. Cada passo é anunciado.
+ *
+ * ```html
+ * <mx-kanban [(columns)]="quadro" [itemLabel]="titulo" (moved)="guardar($event)">
+ *   <ng-template mxKanbanCard let-tarefa>{{ tarefa.titulo }}</ng-template>
+ * </mx-kanban>
+ * ```
+ */
+declare class MxKanban<T = any> {
+    readonly columns: _angular_core.ModelSignal<MxKanbanColumn<T>[]>;
+    /** Chave única de cada cartão: nome do campo ou função. */
+    readonly itemKey: _angular_core.InputSignal<string | ((item: T) => unknown)>;
+    /** Nome do cartão nos anúncios. Por omissão o campo `title` ou `titulo`. */
+    readonly itemLabel: _angular_core.InputSignal<(item: T) => string>;
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    readonly headingLevel: _angular_core.InputSignal<number>;
+    readonly emptyText: _angular_core.InputSignal<string>;
+    readonly helpText: _angular_core.InputSignal<string>;
+    readonly moved: _angular_core.OutputEmitterRef<MxKanbanMove<T>>;
+    protected readonly cardTpl: _angular_core.Signal<MxKanbanCard | undefined>;
+    protected readonly footerTpl: _angular_core.Signal<MxKanbanColumnFooter | undefined>;
+    private readonly announcer;
+    private readonly host;
+    private readonly injector;
+    private readonly uid;
+    protected readonly helpId: string;
+    /** Cartão agarrado com o teclado: posição actual e de onde saiu. */
+    private readonly grabbed;
+    protected titleId(i: number): string;
+    protected listId(i: number): string;
+    keyOf(item: T): unknown;
+    protected labelOf(item: T): string;
+    protected isGrabbed(c: number, i: number): boolean;
+    protected isFull(col: MxKanbanColumn<T>): boolean;
+    protected canEnter(ci: number): (drag: CdkDrag, drop: CdkDropList) => boolean;
+    /** Move um cartão e devolve as colunas novas (sem mudar as antigas). */
+    private move;
+    protected onDrop(e: CdkDragDrop<number>): void;
+    private emitMove;
+    private focusCard;
+    private where;
+    protected onKeydown(event: KeyboardEvent, ci: number, ii: number): void;
+    protected onBlur(ci: number, ii: number): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MxKanban<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MxKanban<any>, "mx-kanban", ["mxKanban"], { "columns": { "alias": "columns"; "required": true; "isSignal": true; }; "itemKey": { "alias": "itemKey"; "required": false; "isSignal": true; }; "itemLabel": { "alias": "itemLabel"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "aria-label"; "required": false; "isSignal": true; }; "headingLevel": { "alias": "headingLevel"; "required": false; "isSignal": true; }; "emptyText": { "alias": "emptyText"; "required": false; "isSignal": true; }; "helpText": { "alias": "helpText"; "required": false; "isSignal": true; }; }, { "columns": "columnsChange"; "moved": "moved"; }, ["cardTpl", "footerTpl"], never, true, never>;
+}
+declare const MX_KANBAN: readonly [typeof MxKanban, typeof MxKanbanCard, typeof MxKanbanColumnFooter];
+
+export { MX_KANBAN, MxKanban, MxKanbanCard, MxKanbanColumnFooter };
+export type { MxKanbanColumn, MxKanbanMove };

package/types/muxima-ui-core-tour.d.ts

@@ -0,0 +1,163 @@
+import * as _angular_core from '@angular/core';
+import { ElementRef, TemplateRef } from '@angular/core';
+
+/** Onde fica o cartão em relação ao elemento destacado. */
+type MxTourPlacement = 'auto' | 'top' | 'bottom' | 'start' | 'end';
+/** Nome de um `mxTourAnchor`, um elemento, ou um ElementRef. */
+type MxTourTarget = string | Element | ElementRef<Element>;
+/** Contexto do modelo de conteúdo de um passo. */
+interface MxTourStepContext {
+    $implicit: MxTourStep;
+    index: number;
+    tour: MxTourRef;
+}
+/** Um passo da visita guiada. */
+interface MxTourStep {
+    /** Elemento a destacar. Sem alvo (ou se não existir), o cartão aparece ao centro. */
+    target?: MxTourTarget | null;
+    title: string;
+    /** Texto do passo. */
+    content?: string;
+    /** Conteúdo rico, em vez de `content`. */
+    template?: TemplateRef<MxTourStepContext>;
+    placement?: MxTourPlacement;
+    /** Espaço à volta do elemento destacado, em px. Por omissão 6. */
+    padding?: number;
+    /** Corre antes de mostrar o passo (ex.: abrir um separador). Pode devolver uma Promise. */
+    beforeShow?: () => void | Promise<unknown>;
+}
+interface MxTourLabels {
+    next: string;
+    previous: string;
+    done: string;
+    skip: string;
+    close: string;
+    /** Texto do progresso, por exemplo "Passo 2 de 5". */
+    progress: (current: number, total: number) => string;
+}
+declare const MX_TOUR_LABELS: MxTourLabels;
+interface MxTourOptions {
+    /** Passo inicial (base 0). */
+    startAt?: number;
+    labels?: Partial<MxTourLabels>;
+    /** false: sem Saltar, sem botão de fechar e sem Escape (a visita tem de ser feita até ao fim). */
+    dismissible?: boolean;
+    /** Mostra os pontos de progresso. Por omissão true. */
+    showDots?: boolean;
+}
+/** Como terminou a visita. */
+interface MxTourResult {
+    /** true se chegou ao fim com Concluir. */
+    completed: boolean;
+    /** Último passo mostrado (base 0). */
+    index: number;
+}
+/** Referência a uma visita em curso. */
+declare class MxTourRef {
+    readonly steps: readonly MxTourStep[];
+    private readonly onClose;
+    /** Passo actual (base 0). */
+    readonly index: _angular_core.WritableSignal<number>;
+    /** Resolve quando a visita fecha. */
+    readonly afterClosed: Promise<MxTourResult>;
+    readonly labels: MxTourLabels;
+    readonly dismissible: boolean;
+    readonly showDots: boolean;
+    private resolve;
+    private done;
+    constructor(steps: readonly MxTourStep[], options: MxTourOptions, onClose: (r: MxTourResult) => void);
+    get isOpen(): boolean;
+    get isLast(): boolean;
+    next(): void;
+    previous(): void;
+    goTo(index: number): void;
+    /** Fecha a visita; `completed` diz se foi até ao fim. */
+    close(completed?: boolean): void;
+}
+interface Box {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+/** Painel da visita: o destaque, o fundo escurecido e o cartão do passo. Uso interno. */
+declare class MxTourPanel {
+    protected readonly ref: MxTourRef;
+    private readonly tour;
+    protected readonly titleId: string;
+    protected readonly bodyId: string;
+    protected readonly progressId: string;
+    private readonly card;
+    private readonly zone;
+    private readonly cdr;
+    /** Passo que está desenhado (muda depois de beforeShow). */
+    protected readonly step: _angular_core.WritableSignal<MxTourStep | null>;
+    private readonly target;
+    protected readonly spot: _angular_core.WritableSignal<Box | null>;
+    protected readonly pos: _angular_core.WritableSignal<{
+        top: number;
+        left: number;
+    }>;
+    protected readonly placement: _angular_core.WritableSignal<"top" | "bottom" | "start" | "end">;
+    protected readonly ready: _angular_core.WritableSignal<boolean>;
+    private frame;
+    private resizeObserver?;
+    private showToken;
+    constructor();
+    private show;
+    private schedule;
+    private update;
+    protected onKeydown(event: KeyboardEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MxTourPanel, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MxTourPanel, "mx-tour-panel", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Visita guiada: destaca elementos da página, um passo de cada vez, com um cartão
+ * que explica cada um. O cartão é um diálogo modal: o foco fica nele, Escape fecha
+ * e, no fim, o foco volta para onde estava.
+ *
+ * ```html
+ * <input mxInput mxTourAnchor="pesquisa" aria-label="Pesquisar" />
+ * <button mxButton mxTourAnchor="nova">Nova factura</button>
+ * ```
+ *
+ * ```ts
+ * private readonly tour = inject(MxTour);
+ * mostrar() {
+ *   this.tour.start([
+ *     { title: 'Bem-vindo', content: 'Mostramos o essencial em 2 passos.' },
+ *     { target: 'pesquisa', title: 'Pesquisa', content: 'Procura clientes e facturas.' },
+ *     { target: 'nova', title: 'Nova factura', content: 'Começa aqui.' },
+ *   ]).afterClosed.then((r) => r.completed && guardarQueViu());
+ * }
+ * ```
+ */
+declare class MxTour {
+    private readonly injector;
+    private readonly anchors;
+    private overlayRef?;
+    /** A visita em curso, ou null. */
+    readonly active: _angular_core.WritableSignal<MxTourRef | null>;
+    readonly isOpen: _angular_core.Signal<boolean>;
+    /** Começa uma visita. Se já houver uma aberta, fecha-a primeiro. */
+    start(steps: readonly MxTourStep[], options?: MxTourOptions): MxTourRef;
+    /** Regista um elemento com um nome (usado por `mxTourAnchor`). */
+    register(name: string, element: Element): void;
+    unregister(name: string, element: Element): void;
+    /** Encontra o elemento de um alvo: nome de âncora, selector CSS, elemento ou ElementRef. */
+    resolve(target: MxTourTarget | null | undefined): Element | null;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MxTour, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MxTour>;
+}
+/** Dá um nome a um elemento para ser alvo de um passo: `mxTourAnchor="pesquisa"`. */
+declare class MxTourAnchor {
+    readonly name: _angular_core.InputSignal<string>;
+    private readonly tour;
+    private readonly el;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MxTourAnchor, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MxTourAnchor, "[mxTourAnchor]", ["mxTourAnchor"], { "name": { "alias": "mxTourAnchor"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { MX_TOUR_LABELS, MxTour, MxTourAnchor, MxTourPanel, MxTourRef };
+export type { MxTourLabels, MxTourOptions, MxTourPlacement, MxTourResult, MxTourStep, MxTourStepContext, MxTourTarget };

package/types/muxima-ui-core.d.ts

@@ -1,3 +1,3 @@
-declare const MUXIMA_VERSION = "1.2.0";
+declare const MUXIMA_VERSION = "1.4.0";
 
 export { MUXIMA_VERSION };