@webx-ui/core 0.12.0 → 0.13.0

package/dist/components/Icon/icons.d.ts

@@ -19,6 +19,10 @@ export declare const builtinIcons: {
     readonly search: "<circle cx=\"11\" cy=\"11\" r=\"6.5\"/><path d=\"m16 16 4.5 4.5\"/>";
     readonly filter: "<path d=\"M4 5.5h16l-6.2 7.2v5.1l-3.6 2v-7.1z\"/>";
     readonly crop: "<path d=\"M6.5 2.5v13a2 2 0 0 0 2 2h13\"/><path d=\"M2.5 6.5h13a2 2 0 0 1 2 2v13\"/>";
+    readonly 'rotate-left': "<path d=\"M19.4 13.8A7.5 7.5 0 1 0 12 5\"/><path d=\"M14.3 2.9 12 5l2.3 2.1\"/>";
+    readonly 'rotate-right': "<path d=\"M4.6 13.8A7.5 7.5 0 1 1 12 5\"/><path d=\"M9.7 2.9 12 5l-2.3 2.1\"/>";
+    readonly 'flip-horizontal': "<path d=\"M12 3v18\" stroke-dasharray=\"3 3\"/><path d=\"M9.2 7.2v9.6L3.6 12z\"/><path d=\"M14.8 7.2v9.6L20.4 12z\"/>";
+    readonly 'flip-vertical': "<path d=\"M3 12h18\" stroke-dasharray=\"3 3\"/><path d=\"M7.2 9.2h9.6L12 3.6z\"/><path d=\"M7.2 14.8h9.6L12 20.4z\"/>";
     readonly refresh: "<path d=\"M4 12a8 8 0 0 1 13.7-5.6L20 8.5\"/><path d=\"M20 4.5v4h-4\"/><path d=\"M20 12a8 8 0 0 1-13.7 5.6L4 15.5\"/><path d=\"M4 19.5v-4h4\"/>";
     readonly upload: "<path d=\"M12 16V4m0 0-4.5 4.5M12 4l4.5 4.5\"/><path d=\"M4 15v3.5A1.5 1.5 0 0 0 5.5 20h13a1.5 1.5 0 0 0 1.5-1.5V15\"/>";
     readonly download: "<path d=\"M12 4v12m0 0-4.5-4.5M12 16l4.5-4.5\"/><path d=\"M4 15v3.5A1.5 1.5 0 0 0 5.5 20h13a1.5 1.5 0 0 0 1.5-1.5V15\"/>";

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

@@ -0,0 +1,67 @@
+import { ImageEditorCrop, ImageEditorProps, ImageEditorRatio, ImageEditorRatioOption, ImageEditorResult } from './types';
+/**
+ * Draws the result and hands it over. Exposed, so a page with a footer of its own can
+ * ask for it without the editor carrying one.
+ */
+declare function apply(): Promise<ImageEditorResult | undefined>;
+declare const _default: import('vue').DefineComponent<ImageEditorProps, {
+    /** Draws the result, emits `save` and answers with it. */
+    apply: typeof apply;
+    /** Back to the whole picture, the right way up. */
+    reset: () => void;
+    crop: import('vue').ComputedRef<ImageEditorCrop>;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    crop: (crop: ImageEditorCrop) => any;
+    error: (error: unknown) => any;
+    cancel: () => any;
+    load: (size: {
+        width: number;
+        height: number;
+    }) => any;
+    save: (result: ImageEditorResult) => any;
+}, string, import('vue').PublicProps, Readonly<ImageEditorProps> & Readonly<{
+    onCrop?: ((crop: ImageEditorCrop) => any) | undefined;
+    onError?: ((error: unknown) => any) | undefined;
+    onCancel?: (() => any) | undefined;
+    onLoad?: ((size: {
+        width: number;
+        height: number;
+    }) => any) | undefined;
+    onSave?: ((result: ImageEditorResult) => any) | undefined;
+}>, {
+    disabled: boolean;
+    footer: boolean;
+    background: string;
+    format: "auto" | "image/jpeg" | "image/png" | "image/webp";
+    resizable: boolean;
+    minSize: number;
+    maxWidth: number;
+    saveLabel: string;
+    cancelLabel: string;
+    ratio: ImageEditorRatio;
+    fileName: string;
+    aspect: number;
+    ratios: (ImageEditorRatio | ImageEditorRatioOption)[];
+    rotatable: boolean;
+    flippable: boolean;
+    maxHeight: number;
+    quality: number;
+    crossOrigin: "anonymous" | "use-credentials" | "";
+    resetLabel: string;
+    rotateLeftLabel: string;
+    rotateRightLabel: string;
+    flipHorizontalLabel: string;
+    flipVerticalLabel: string;
+    ratioLabel: string;
+    cropLabel: string;
+    widthLabel: string;
+    freeLabel: string;
+    originalLabel: string;
+    errorText: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    stage: HTMLDivElement;
+    frame: HTMLDivElement;
+    image: HTMLImageElement;
+    cropBox: HTMLDivElement;
+}, HTMLDivElement>;
+export default _default;

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

@@ -0,0 +1,46 @@
+import { ImageEditorCrop } from './types';
+/** The eight grips, named after the compass the way every editor names them. */
+export type CropHandle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+export interface CropBounds {
+    width: number;
+    height: number;
+}
+export declare function clamp(value: number, min: number, max: number): number;
+/** `1.7778` → `16:9`. Falls back to a decimal for a ratio that is nobody's convention. */
+export declare function ratioLabelFor(value: number): string;
+/** The whole picture, or the largest rectangle of `ratio` in the middle of it. */
+export declare function fullCrop(bounds: CropBounds, ratio?: number): ImageEditorCrop;
+/**
+ * The largest rectangle of `ratio` that fits inside `crop`, kept where `crop` was — used
+ * when the ratio changes and when a turn leaves the old crop the wrong shape.
+ */
+export declare function fitRatio(crop: ImageEditorCrop, ratio: number, bounds: CropBounds): ImageEditorCrop;
+/** Dragged from inside: the crop slides, and stops at the edges of the picture. */
+export declare function moveCrop(start: ImageEditorCrop, dx: number, dy: number, bounds: CropBounds): ImageEditorCrop;
+/**
+ * Dragged by a grip.
+ *
+ * The opposite corner — or the opposite edge, for the four in the middle — is the anchor
+ * and does not move; everything else follows the pointer. With a ratio the rectangle is
+ * brought back to that ratio before it is fitted inside the picture, so a locked crop
+ * cannot be nudged out of shape by dragging it into a corner.
+ */
+export declare function resizeCrop(handle: CropHandle, point: {
+    x: number;
+    y: number;
+}, start: ImageEditorCrop, bounds: CropBounds, { ratio, min }?: {
+    ratio?: number;
+    min?: number;
+}): ImageEditorCrop;
+/**
+ * The crop follows the picture through a quarter turn, so what was framed stays framed.
+ * `bounds` is the space *before* the turn; the space after it has its sides swapped.
+ */
+export declare function turnCrop(crop: ImageEditorCrop, bounds: CropBounds, direction: 1 | -1): ImageEditorCrop;
+/** The same, for a mirroring. */
+export declare function mirrorCrop(crop: ImageEditorCrop, bounds: CropBounds, axis: 'x' | 'y'): ImageEditorCrop;
+/** The largest whole-pixel size of the same shape that fits within the caps. */
+export declare function fitInside(width: number, height: number, maxWidth?: number, maxHeight?: number): {
+    width: number;
+    height: number;
+};

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

@@ -0,0 +1,3 @@
+export { default as WxImageEditor } from './ImageEditor';
+export { ratioLabelFor } from './crop';
+export type * from './types';

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/index.d.ts

@@ -42,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';