@webx-ui/core 0.11.0 → 0.13.0

package/dist/components/ImageEditor/types.d.ts

@@ -0,0 +1,128 @@
+/** A rectangle of the picture, in the pixels of the image *after* its quarter turns. */
+export interface ImageEditorCrop {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * A ratio the crop can be locked to: a number (width ÷ height), `free` for no lock, or
+ * `original` for whatever the picture itself is.
+ */
+export type ImageEditorRatio = number | 'free' | 'original';
+export interface ImageEditorRatioOption {
+    value: ImageEditorRatio;
+    /** Derived from the number when it is left out — `1.7778` reads as `16:9`. */
+    label?: string;
+}
+/** What the editor hands over. Nothing is uploaded; this is a blob and its measurements. */
+export interface ImageEditorResult {
+    blob: Blob;
+    /** The same bytes named, ready to be posted straight to a server. */
+    file: File;
+    /** MIME type of the blob. */
+    type: string;
+    width: number;
+    height: number;
+    /**
+     * The crop, in the pixels of the turned picture — turn by `rotation`, mirror by the
+     * flips, then cut this out, and a server arrives at the same picture.
+     */
+    crop: ImageEditorCrop;
+    /** Quarter turns, clockwise: 0, 90, 180 or 270. */
+    rotation: number;
+    flipX: boolean;
+    flipY: boolean;
+}
+export interface ImageEditorProps {
+    /** The picture: a URL, or the `File` an upload field just handed you. */
+    src: string | Blob;
+    /**
+     * Name for the file in the result. Taken from `src` when it is a URL or a `File`, and
+     * its extension is put right to match the format actually written.
+     */
+    fileName?: string;
+    /**
+     * Locks the crop to one ratio and takes the picker away — `1` for an avatar. The
+     * ratios offered stay if `ratios` is given as well.
+     */
+    aspect?: number;
+    /** The ratios offered. Empty hides the picker and leaves the crop free. */
+    ratios?: (ImageEditorRatio | ImageEditorRatioOption)[];
+    /** Which of them the editor opens on. Defaults to the first. */
+    ratio?: ImageEditorRatio;
+    /** Quarter turns, left and right. */
+    rotatable?: boolean;
+    /** Mirroring, across and down. */
+    flippable?: boolean;
+    /** Offers the output size — the field that scales the cut-out down before it is written. */
+    resizable?: boolean;
+    /** Largest output, in pixels. A bigger crop is scaled down to fit inside it. */
+    maxWidth?: number;
+    maxHeight?: number;
+    /** Smallest crop, in the picture's own pixels. */
+    minSize?: number;
+    /**
+     * What to write. `auto` keeps the source's format where it is one a browser can write
+     * (JPEG, PNG, WebP) and falls back to JPEG.
+     */
+    format?: 'auto' | 'image/jpeg' | 'image/png' | 'image/webp';
+    /** 0 to 1, for the formats that have a quality. */
+    quality?: number;
+    /**
+     * Painted behind the picture when the format has no transparency, since transparent
+     * turns black in a JPEG.
+     */
+    background?: string;
+    /**
+     * `crossorigin` for the `<img>`. Anonymous by default: a canvas that has drawn a
+     * picture from a host which sent no CORS header cannot be read back, so the export
+     * would fail — this way it fails at loading, where it can be seen.
+     */
+    crossOrigin?: 'anonymous' | 'use-credentials' | '';
+    /** The editor's own Cancel and Save. Off when the panel around it has its own. */
+    footer?: boolean;
+    disabled?: boolean;
+    saveLabel?: string;
+    cancelLabel?: string;
+    resetLabel?: string;
+    rotateLeftLabel?: string;
+    rotateRightLabel?: string;
+    flipHorizontalLabel?: string;
+    flipVerticalLabel?: string;
+    /** Accessible name of the ratio picker, and of the crop box itself. */
+    ratioLabel?: string;
+    cropLabel?: string;
+    /** The output-size field. */
+    widthLabel?: string;
+    freeLabel?: string;
+    originalLabel?: string;
+    /** Shown in place of the picture when it will not load. */
+    errorText?: string;
+}
+export interface ImageEditorEmits {
+    /** The picture, cut and turned. */
+    save: [result: ImageEditorResult];
+    cancel: [];
+    /** The picture loaded, at this size. */
+    load: [size: {
+        width: number;
+        height: number;
+    }];
+    /** It did not load, or could not be written. */
+    error: [error: unknown];
+    /** The crop moved or was resized, in the pixels of the turned picture. */
+    crop: [crop: ImageEditorCrop];
+}
+/**
+ * What `openImageEditor` takes: the editor's own props, and the panel it arrives in.
+ *
+ * A type rather than an interface so that it can be handed to `createModal`, which asks
+ * for something a bag of props can be made of.
+ */
+export type ImageEditorModalProps = ImageEditorProps & {
+    /** Heading of the panel. */
+    title?: string;
+    /** Width of the panel: a number in pixels, or any CSS length. */
+    width?: number | string;
+};

package/dist/components/Kanban/Kanban.d.ts

@@ -6,7 +6,7 @@ declare const _default: <T extends KanbanCard = KanbanCard>(__VLS_props: NonNull
         readonly "onUpdate:collapsed"?: ((value: KanbanId[]) => any) | undefined;
         readonly "onColumn-move"?: ((move: import('./types').KanbanColumnMove<T>) => any) | undefined;
         readonly "onAdd-column"?: (() => any) | undefined;
-    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onAdd" | "onMove" | "onUpdate:collapsed" | "onColumn-move" | "onAdd-column"> & ({
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onMove" | "onAdd" | "onUpdate:collapsed" | "onColumn-move" | "onAdd-column"> & ({
         collapsed?: KanbanId[];
     } & KanbanProps<T>) & Partial<{}>> & import('vue').PublicProps;
     expose(exposed: import('vue').ShallowUnwrapRef<{

package/dist/components/Tooltip/Tooltip.d.ts

@@ -31,9 +31,9 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_PublicProps,
     align: import('./types').TooltipAlign;
     offset: number;
     teleport: boolean;
+    arrow: boolean;
     delay: number;
     maxWidth: number | string;
-    arrow: boolean;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
 export default _default;

package/dist/components/Upload/Upload.d.ts

@@ -54,13 +54,13 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_PublicProps,
     multiple: boolean;
     disabled: boolean;
     max: number;
+    removable: boolean;
     accept: string;
     maxSize: number;
     buttonOnly: boolean;
     buttonText: string;
     hint: string;
     gallery: boolean;
-    removable: boolean;
     beforeAdd: (file: File) => boolean | Promise<boolean>;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
     input: HTMLInputElement;

package/dist/components/index.d.ts

@@ -34,6 +34,7 @@ export * from './Dropdown';
 export * from './DropdownItem';
 export * from './Empty';
 export * from './EntityCard';
+export * from './FileCard';
 export * from './Footer';
 export * from './Form';
 export * from './FormItem';
@@ -41,6 +42,7 @@ export * from './Header';
 export * from './Heading';
 export * from './Icon';
 export * from './Image';
+export * from './ImageEditor';
 export * from './Indicator';
 export * from './Input';
 export * from './InputNumber';

package/dist/composables/imageEditor.d.ts

@@ -0,0 +1,19 @@
+import { ImageEditorModalProps, ImageEditorResult } from '../components/ImageEditor/types';
+/**
+ * Opens the picture in a panel and answers with what came out of it.
+ *
+ * ```ts
+ * const edited = await openImageEditor({ src: file.url, aspect: 16 / 9 })
+ * if (!edited) return
+ * await upload(edited.file)
+ * ```
+ *
+ * Nothing is uploaded and nothing is replaced: the answer is a blob, its measurements and
+ * the crop it was cut from, and the screen that asked decides where all that goes. Closed
+ * without saving — the ✕, escape, Cancel — it answers `undefined`, which is not an error.
+ *
+ * It is [`createModal`](/guide/modals) over `WxImageEditor` in a dialog, and worth reading
+ * as the example: one line names the component, the type of its answer and the event that
+ * carries it, and every call site is a single `await`.
+ */
+export declare const openImageEditor: (props?: ImageEditorModalProps | undefined, options?: import('./useModal').ModalOptions) => import('./useModal').ModalPromise<ImageEditorResult>;

package/dist/composables/useModal.d.ts

@@ -58,8 +58,11 @@ export declare function openModal<T = unknown>(component: Component, options?: M
  *
  * const product = await productBrowser({ multiple: false })
  * ```
+ *
+ * `P` is any object — an `interface` of props included, which a `Record<string, unknown>`
+ * would have turned away for want of an index signature.
  */
-export declare function createModal<T = unknown, P extends Record<string, unknown> = Record<string, never>>(component: Component, defaults?: ModalOptions): (props?: P, options?: ModalOptions) => ModalPromise<T>;
+export declare function createModal<T = unknown, P extends object = Record<string, never>>(component: Component, defaults?: ModalOptions): (props?: P, options?: ModalOptions) => ModalPromise<T>;
 /**
  * The handle of the modal a component is being shown in. Outside one it answers all the
  * same, with `isModal: false` and calls that do nothing — so a component can be written

package/dist/index.d.ts

@@ -6,4 +6,5 @@ export { useElementWidth } from './composables/useElementWidth';
 export { useToast, toast, toastQueue, dismissToast, removeToast, clearToasts, type ToastApi, type ToastHandle, type ToastOptions, type ToastRecord, type ToastType, type ToastAction, } from './composables/useToast';
 export { openModal, createModal, useModal, connectModals, modalKey, type ModalHandle, type ModalOptions, type ModalPromise, } from './composables/useModal';
 export { confirm, type ConfirmOptions } from './composables/confirm';
+export { openImageEditor } from './composables/imageEditor';
 export { useResponsiveShell, shellLayoutFor, type ResponsiveShell, type ResponsiveShellOptions, type ShellLayout, } from './composables/useResponsiveShell';