@sdcorejs/angular 19.0.1 → 20.0.0

package/components/code-editor/index.d.ts

@@ -1 +1,24 @@
-export * from './src/code-editor.component';
+import * as _angular_core from '@angular/core';
+import { SafeHtml } from '@angular/platform-browser';
+
+type CodeLanguage = 'html' | 'typescript' | 'json' | 'css' | 'scss';
+declare class SdCodeEditor {
+    #private;
+    valueModel: _angular_core.ModelSignal<any>;
+    language: _angular_core.InputSignal<CodeLanguage>;
+    maxHeight: _angular_core.InputSignal<string>;
+    viewed: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    copied: _angular_core.WritableSignal<boolean>;
+    textValue: _angular_core.WritableSignal<string>;
+    prismLang: _angular_core.Signal<CodeLanguage | "markup">;
+    private _lastEmittedValue;
+    constructor();
+    highlightedCode: _angular_core.Signal<SafeHtml>;
+    onTextChange(newText: string): void;
+    copyToClipboard(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdCodeEditor, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdCodeEditor, "sd-code-editor", never, { "valueModel": { "alias": "model"; "required": false; "isSignal": true; }; "language": { "alias": "language"; "required": false; "isSignal": true; }; "maxHeight": { "alias": "maxHeight"; "required": false; "isSignal": true; }; "viewed": { "alias": "viewed"; "required": false; "isSignal": true; }; }, { "valueModel": "modelChange"; }, never, never, true, never>;
+}
+
+export { SdCodeEditor };
+export type { CodeLanguage };

package/components/document-builder/index.d.ts

@@ -1,4 +1,252 @@
-export * from './src/components';
-export * from './src/document-builder.model';
-export * from './src/document-builder.component';
-export * from './src/plugins/ck-comment/ck-comment.plugin.model';
+import * as i0 from '@angular/core';
+import { EventEmitter } from '@angular/core';
+import { ModelRange, EditorConfig, ModelDocumentSelection, EventInfo, ViewDataTransfer, ClassicEditor, Plugin, Widget, ContextualBalloon } from 'ckeditor5';
+import { I18nParams } from '@sdcorejs/angular/i18n';
+
+/**
+ * Comment status based on text changes
+ */
+type CkCommentStatus = 'normal' | 'modified' | 'broken';
+/**
+ * Color configuration for comment markers
+ */
+interface CkCommentColors {
+    marker?: string;
+    markerSelected?: string;
+    markerPending?: string;
+    markerModified?: string;
+    markerBroken?: string;
+}
+/**
+ * Comment data structure for CkCommentPlugin
+ */
+interface CkComment<T = any> {
+    id: string | number;
+    startPath: number[];
+    endPath: number[];
+    originalText: string;
+    currentText: string;
+    status: CkCommentStatus;
+    data?: T;
+}
+/**
+ * Config for CkCommentPlugin
+ */
+interface CkCommentConfig {
+    onPendingComment?: (comment: CkComment) => void;
+    onAddComment?: (comment: CkComment) => void;
+    onSelectComment?: (id: string | number) => void;
+    onRemoveComment?: (id: string | number) => void;
+    onChange?: (comments: CkComment[]) => void;
+    onCancelPending?: () => void;
+    onError?: (error: {
+        code: string;
+        message: string;
+        data?: any;
+    }) => void;
+    searchRange?: number;
+    debug?: boolean;
+    colors?: CkCommentColors;
+    maxTextLength?: number;
+    allowCreating?: boolean;
+}
+/**
+ * Data returned when user selects text for comment
+ */
+interface CkCommentSelection {
+    range: ModelRange;
+    startPath: number[];
+    endPath: number[];
+    text: string;
+}
+
+/** Plain translator cho CKEditor plugin — tránh truyền thẳng I18nService (private fields mất `this` qua config). */
+interface DocumentBuilderI18n {
+    t(key: string, params?: I18nParams): string;
+}
+type DocumentBuilderOption = EditorConfig & {
+    getOption?: () => SdDocumentBuilderOption;
+    _i18n?: DocumentBuilderI18n;
+};
+interface SdDocumentBuilderOption {
+    onDropVariable?: (variable: SdDocumentBuilderVariable) => boolean | Promise<boolean | SdDocumentBuilderVariable>;
+    onAfterDropVariable?: (variable: SdDocumentBuilderVariable) => void;
+    onPasteVariable?: (display: string) => SdDocumentBuilderVariable | null | Promise<SdDocumentBuilderVariable | null>;
+    comment?: CkCommentConfig;
+    onSelection?: (selection: ModelDocumentSelection, $event: EventInfo<string, unknown>) => void;
+    onOrientation?: (orientation: 'PORTRAIT' | 'LANDSCAPE') => void;
+    onPaste?: (data: SdPasteEventData) => void | Promise<void>;
+    orientation?: 'PORTRAIT' | 'LANDSCAPE';
+}
+interface SdDocumentBuilderVariable<T = any> {
+    id: string;
+    uuid?: string;
+    value: string;
+    display: string;
+    bindingValue?: string;
+    data?: T;
+}
+interface SdDocumentBuilderHeading {
+    id: string;
+    text: string;
+    level: number;
+    type: string;
+}
+interface SdPasteEventData {
+    html?: string;
+    text: string;
+    source: 'word' | 'excel' | 'google-docs' | 'web' | 'unknown';
+    dataTransfer: ViewDataTransfer;
+}
+
+declare class SdHeaderFooterBuilder {
+    #private;
+    Editor: typeof ClassicEditor;
+    set model(value: string | undefined | null);
+    modelChange: EventEmitter<string>;
+    config: EditorConfig & {
+        _i18n?: DocumentBuilderI18n;
+    };
+    onReady(editor: ClassicEditor): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdHeaderFooterBuilder, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SdHeaderFooterBuilder, "sd-header-footer-builder", never, { "model": { "alias": "model"; "required": false; }; }, { "modelChange": "modelChange"; }, never, never, true, never>;
+}
+
+declare class VariablePlugin extends Plugin {
+    #private;
+    static get pluginName(): "VariablePlugin";
+    static get requires(): (typeof Widget)[];
+    init(): void;
+    /**
+     * Lấy tất cả variables trong document.
+     * @returns Danh sách tất cả variables (bao gồm bindingValue nếu đã binding)
+     */
+    all<T = any>(): SdDocumentBuilderVariable<T>[];
+    /**
+     * Scroll tới vị trí của variable theo uuid.
+     * @param uuid - uuid của variable (FE tự sinh sau mỗi lần drop)
+     */
+    scroll(uuid: string): void;
+    /**
+     * Gán giá trị cho TẤT CẢ variable có cùng id trong document.
+     * Nếu value rỗng → tự động gọi clearValue(id).
+     * @param id    - id của variable definition
+     * @param value - giá trị binding cần hiển thị
+     * @returns số instance đã được cập nhật
+     */
+    bindValue(id: string, value: string): number;
+    /**
+     * Xóa binding value của TẤT CẢ variable có cùng id.
+     * @param id - id của variable definition
+     * @returns số instance đã được cập nhật
+     */
+    clearValue(id: string): number;
+    /**
+     * Batch bind nhiều variables theo map { id → value }.
+     * Toàn bộ thực hiện trong 1 model.change() → 1 undo step duy nhất.
+     * @param map - { [id]: boundValue }
+     */
+    bindValues(map: Record<string, string>): void;
+    /**
+     * Batch clear binding của nhiều variables.
+     * @param ids - danh sách id cần clear; nếu không truyền/rỗng → clear TẤT CẢ
+     */
+    clearValues(ids?: string[]): void;
+    /** Xóa toàn bộ binding values trong document. Shorthand của clearValues(). */
+    clearAllValues(): void;
+}
+
+declare class CkCommentPlugin extends Plugin {
+    #private;
+    static get pluginName(): string;
+    static get requires(): (typeof ContextualBalloon)[];
+    static readonly PENDING_MARKER_ID = "__pending_comment__";
+    static readonly DEFAULT_SEARCH_RANGE = 5;
+    static readonly DEFAULT_MAX_TEXT_LENGTH = 1000;
+    static readonly DEFAULT_COLORS: CkCommentColors;
+    init(): void;
+    /**
+     * Thiết lập config với callbacks
+     */
+    setConfig(config: CkCommentConfig): void;
+    /**
+     * Thêm comment và tạo marker
+     */
+    addComment(comment: CkComment): boolean;
+    /**
+     * Xóa comment theo id
+     */
+    removeComment(id: string | number): boolean;
+    /**
+     * Chọn comment theo id - chỉ thêm class highlight, không bôi đen text
+     */
+    selectComment(id: string | number, scrollIntoView?: boolean): void;
+    /**
+     * Thiết lập tất cả comments (khôi phục từ dữ liệu)
+     */
+    setComments(comments: CkComment[]): void;
+    /**
+     * Lấy tất cả comments
+     */
+    get comments(): CkComment[];
+    /**
+     * Thiết lập pending highlight cho selection (khi user đang nhập nội dung comment)
+     */
+    setPendingSelection(startPath: number[], endPath: number[]): boolean;
+    /**
+     * Xóa pending highlight và fire onCancelPending callback
+     */
+    clearPendingSelection(): void;
+}
+
+declare class SdDocumentBuilder {
+    #private;
+    option: SdDocumentBuilderOption;
+    disabled: boolean;
+    set _disabled(val: boolean | '' | undefined | null);
+    contentChange: EventEmitter<string>;
+    Editor: typeof ClassicEditor;
+    config: DocumentBuilderOption;
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    onReady(editor: ClassicEditor): void;
+    setContent: (html: string) => void;
+    getContent: () => string;
+    setOrientation: (orientation: "PORTRAIT" | "LANDSCAPE") => void;
+    getOrientation: () => "PORTRAIT" | "LANDSCAPE";
+    scrollToTop(): void;
+    heading: {
+        /**
+         * Lấy tất cả headings trong document
+         * @returns Danh sách tất cả headings
+         */
+        all: () => SdDocumentBuilderHeading[];
+        /**
+         * Scroll tới vị trí của heading
+         * @param id - ID của heading cần scroll tới
+         */
+        scroll: (id: string) => void;
+    };
+    getCommentPluginAPI(): CkCommentPlugin | null;
+    getVariablePluginAPI(): VariablePlugin | null;
+    /**
+     * Xuất file Word có Header/Footer
+     * @param fileName Tên file
+     * @param headerText Nội dung Header (hoặc HTML)
+     * '<p style="text-align: center; font-weight: bold;">CÔNG TY CỔ PHẦN CÔNG NGHỆ ABC</p>'
+     * @param footerText Nội dung Footer (hoặc HTML)
+     * '<p style="text-align: right; font-size: 10pt;">Trang <span style="mso-field-code: PAGE"></span> / <span style="mso-field-code: NUMPAGES"></span></p>'
+     */
+    exportDocx(args: {
+        fileName?: string;
+        header?: string;
+        footer?: string;
+    }): void;
+    hightSelectRange: (range: ModelRange) => void;
+    removeHighlightSeclectRange: () => void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdDocumentBuilder, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SdDocumentBuilder, "sd-document-builder", never, { "option": { "alias": "option"; "required": true; }; "_disabled": { "alias": "disabled"; "required": false; }; }, { "contentChange": "contentChange"; }, never, never, true, never>;
+}
+
+export { SdDocumentBuilder, SdHeaderFooterBuilder };
+export type { CkComment, CkCommentColors, CkCommentConfig, CkCommentSelection, CkCommentStatus, DocumentBuilderI18n, DocumentBuilderOption, SdDocumentBuilderHeading, SdDocumentBuilderOption, SdDocumentBuilderVariable, SdPasteEventData };

package/components/editor/index.d.ts

@@ -1,3 +1,128 @@
-export * from './src/configurations';
-export * from './src/models';
-export * from './src/editor.component';
+import * as _angular_core from '@angular/core';
+import { InjectionToken } from '@angular/core';
+import { EditorConfig, ClassicEditor } from 'ckeditor5';
+import { I18nService } from '@sdcorejs/angular/i18n';
+import { FormGroup } from '@angular/forms';
+import { SdCustomValidator, SdFormControl } from '@sdcorejs/angular/forms/models';
+
+interface SdEditorUploadFileDetail {
+    idOrKey: string;
+    cdn: string;
+    name?: string;
+}
+type SdEditorUploadFileFuncUpload = (files: File[]) => Promise<SdEditorUploadFileDetail[]>;
+interface ISdEditorConfiguration {
+    key?: string;
+    upload: SdEditorUploadFileFuncUpload;
+}
+declare const SD_EDITOR_CONFIGURATION: InjectionToken<ISdEditorConfiguration>;
+
+interface SdEditorImageUploadValidation {
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    maxSizeMB?: number;
+    allowedFormats?: string[];
+}
+interface SdEditorImageConfig {
+    /**
+     * Chế độ tải lên hình ảnh.
+     * 'immediate': Upload ngay khi chọn ảnh.
+     * 'deferred': Lưu tạm ảnh blob, khi submit thì viewChild component sd-editor rồi gọi upload() để tự động map lại src lấy từ uploadFn,
+     * @default 'deferred'
+     */
+    uploadMode?: 'deferred' | 'immediate';
+    /**
+     * Hàm xử lý tải lên file
+     * Nếu thuộc tính này được khai báo, tính năng tải lên hình ảnh trong editor sẽ tự động được kích hoạt.
+     * @param files Danh sách các tệp (File) cần tải lên.
+     * @returns Promise chứa mảng thông tin chi tiết của các tệp sau khi tải lên thành công.
+     */
+    uploadFn?: (files: File[]) => Promise<SdEditorUploadFileDetail[]>;
+    /**
+     * Validation hình ảnh trước khi tiến hành tải lên.
+     */
+    validation?: SdEditorImageUploadValidation;
+    /**
+     * Số lượng luồng tải lên (API calls) tối đa được thực thi đồng thời.
+     * Ví dụ: Nếu có 10 API cần tải lên, hệ thống sẽ đưa vào hàng đợi và xử lý song song dựa trên giới hạn này để tránh nghẽn mạng và rateLimit phía BE.
+     * @default 2
+     */
+    maxConcurrentUploads?: number;
+    /**
+     * Số lượng file được gom nhóm (batch) trong mỗi lần gọi hàm `uploadFn`.
+     * Nếu Backend hỗ trợ multi-file, có thể thiết lập số này lớn hơn để gửi nhiều file trong cùng một payload.
+     * Ví dụ: Nếu chọn 10 file và `batchSize = 5`, hệ thống sẽ chỉ gọi 2 API, mỗi lần gửi 5 file.
+     * * @default 2
+     */
+    batchSize?: number;
+    /**
+     * Số lượng hình ảnh tối đa người dùng được phép chọn trong một lần thao tác.
+     */
+    maxImagesPerSelection?: number;
+    /**
+     * Kích hoạt chế độ tải chậm (lazy load) cho hình ảnh để tối ưu hóa hiệu suất
+     * @default true
+     */
+    lazyLoad?: boolean;
+}
+
+interface SdEditorOption {
+    imageConfig?: SdEditorImageConfig;
+    _i18n?: I18nService;
+}
+type EditorOption = EditorConfig & {
+    getOption?: () => SdEditorOption;
+};
+
+declare class SdEditor {
+    #private;
+    readonly option: _angular_core.InputSignal<SdEditorOption>;
+    readonly height: _angular_core.InputSignal<string>;
+    readonly maxHeight: _angular_core.InputSignal<string>;
+    readonly maxlength: _angular_core.InputSignal<number | undefined>;
+    readonly label: _angular_core.InputSignal<string | undefined>;
+    readonly helperText: _angular_core.InputSignal<string | undefined>;
+    readonly required: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly hideInlineError: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly inlineError: _angular_core.InputSignal<string | undefined>;
+    readonly placeholder: _angular_core.InputSignal<string | undefined>;
+    readonly validator: _angular_core.InputSignal<SdCustomValidator | undefined>;
+    readonly form: _angular_core.InputSignalWithTransform<FormGroup<any> | undefined, any>;
+    readonly key: _angular_core.InputSignal<string | undefined>;
+    readonly autoIdInput: _angular_core.InputSignal<string | null | undefined>;
+    readonly autoId: _angular_core.Signal<string | undefined>;
+    readonly dataDisabled: _angular_core.Signal<"true" | "false">;
+    readonly dataEmpty: _angular_core.Signal<"true" | "false">;
+    readonly name: _angular_core.InputSignal<string>;
+    readonly valueModel: _angular_core.ModelSignal<string>;
+    readonly sdChange: _angular_core.OutputEmitterRef<string>;
+    readonly sdBlur: _angular_core.OutputEmitterRef<FocusEvent>;
+    readonly sdFocus: _angular_core.OutputEmitterRef<FocusEvent>;
+    readonly _textLength: _angular_core.WritableSignal<number>;
+    readonly formControl: SdFormControl;
+    readonly isOverLimit: _angular_core.Signal<boolean>;
+    get errorMessage(): string | undefined;
+    readonly Editor: typeof ClassicEditor;
+    readonly editorConfig: _angular_core.Signal<EditorOption>;
+    constructor();
+    onReady: (editor: ClassicEditor) => void;
+    focusEditor: () => void | undefined;
+    /**
+     * Xử lý tải lên các file và trả về nội dung dữ liệu cuối cùng.
+     * * @description
+     * - Đối với các file upload chế độ 'deferred' (chỉ xử lý khi submit), cần @ViewChild component và gọi hàm upload() này.
+     * - Hỗ trợ two-way binding.
+     * - Hàm hỗ trợ trả ra data cuối cùng.
+     * * @returns {Promise<string>} Nội dung cuối cùng được trích xuất từ sd-editor.
+     */
+    upload: () => Promise<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdEditor, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdEditor, "sd-editor", never, { "option": { "alias": "option"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "maxHeight": { "alias": "maxHeight"; "required": false; "isSignal": true; }; "maxlength": { "alias": "maxlength"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "helperText": { "alias": "helperText"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "hideInlineError": { "alias": "hideInlineError"; "required": false; "isSignal": true; }; "inlineError": { "alias": "inlineError"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "validator": { "alias": "validator"; "required": false; "isSignal": true; }; "form": { "alias": "form"; "required": false; "isSignal": true; }; "key": { "alias": "key"; "required": false; "isSignal": true; }; "autoIdInput": { "alias": "autoId"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "valueModel": { "alias": "model"; "required": false; "isSignal": true; }; }, { "valueModel": "modelChange"; "sdChange": "sdChange"; "sdBlur": "sdBlur"; "sdFocus": "sdFocus"; }, never, never, true, never>;
+}
+
+export { SD_EDITOR_CONFIGURATION, SdEditor };
+export type { EditorOption, ISdEditorConfiguration, SdEditorImageConfig, SdEditorImageUploadValidation, SdEditorOption, SdEditorUploadFileDetail, SdEditorUploadFileFuncUpload };