@webx-ui/core 0.12.0 → 0.14.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=\"M4.5 9.5A8 8 0 1 1 4 13.5\"/><path d=\"M9.5 9.5h-5v-5\"/>";
+    readonly 'rotate-right': "<path d=\"M19.5 9.5A8 8 0 1 0 20 13.5\"/><path d=\"M14.5 9.5h5v-5\"/>";
+    readonly 'flip-horizontal': "<path d=\"M12 3.5v17\" stroke-dasharray=\"2.5 2.5\"/><path d=\"M9.5 7.5v9L4 14.5v-5z\" fill=\"currentColor\" stroke=\"none\"/><path d=\"M14.5 7.5v9l5.5-2v-5z\"/>";
+    readonly 'flip-vertical': "<path d=\"M3.5 12h17\" stroke-dasharray=\"2.5 2.5\"/><path d=\"M7.5 9.5h9L14.5 4h-5z\" fill=\"currentColor\" stroke=\"none\"/><path d=\"M7.5 14.5h9L14.5 20h-5z\"/>";
     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,76 @@
+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";
+    filters: boolean;
+    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;
+    outputLabel: string;
+    outputHint: string;
+    widthLabel: string;
+    heightLabel: string;
+    adjustLabel: string;
+    brightnessLabel: string;
+    contrastLabel: string;
+    saturationLabel: string;
+    monoLabel: 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/filters.d.ts

@@ -0,0 +1,23 @@
+import { ImageEditorAdjustments } from './types';
+/** Nothing done to the picture: the reading every slider starts at. */
+export declare const NEUTRAL: ImageEditorAdjustments;
+export declare function isNeutral(adjust: ImageEditorAdjustments): boolean;
+/**
+ * The adjustments as a CSS `filter` — the same string the `<img>` is shown through and
+ * the canvas is drawn under, which is what keeps the preview honest.
+ *
+ * Order matters and is the order a reader expects: lighten, then stretch the contrast,
+ * then the colour, and black-and-white last so that it wins over whatever the saturation
+ * slider was left at.
+ */
+export declare function filterString(adjust: ImageEditorAdjustments): string;
+/**
+ * The same arithmetic by hand, for a browser whose canvas has no `filter`.
+ *
+ * Safari only learned `ctx.filter` in 16.4, and where it is missing it is missing
+ * silently: the picture on screen is adjusted, the file that comes out is not. Doing the
+ * pass ourselves is the difference between a wrong file and a slow one.
+ *
+ * Written over the pixels in place, in the order `filterString` composes them.
+ */
+export declare function applyAdjustments(pixels: Uint8ClampedArray, adjust: ImageEditorAdjustments): void;

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

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

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

@@ -0,0 +1,158 @@
+/** 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;
+}
+/**
+ * The adjustments, as percentages of what the picture already is: 100 leaves it alone.
+ * They are the four a photograph for a website actually wants, and no more — a preset is
+ * a name for a set of these numbers, and can be built on top without the editor knowing.
+ */
+export interface ImageEditorAdjustments {
+    brightness: number;
+    contrast: number;
+    saturation: number;
+    /** Black and white, which overrules whatever the saturation is set to. */
+    mono: boolean;
+}
+/** 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;
+    /** The adjustments as they stood, and the CSS `filter` that says the same thing. */
+    adjustments: ImageEditorAdjustments;
+    /** Empty when the picture was left alone. A server can apply the same numbers. */
+    filter: string;
+}
+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 fields that scale the cut-out down before it is written. */
+    resizable?: boolean;
+    /**
+     * Offers the adjustments: brightness, contrast, saturation and black-and-white, behind
+     * one button. Off by default, so an editor asked for as a cropper stays one.
+     */
+    filters?: 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 row: its caption, the tip on that caption, and the two fields. */
+    outputLabel?: string;
+    outputHint?: string;
+    widthLabel?: string;
+    heightLabel?: string;
+    /** The adjustments: the button, and the four things inside its panel. */
+    adjustLabel?: string;
+    brightnessLabel?: string;
+    contrastLabel?: string;
+    saturationLabel?: string;
+    monoLabel?: 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/Progress/Progress.d.ts

@@ -29,8 +29,8 @@ declare const __VLS_component: import('vue').DefineComponent<ProgressProps, {},
     max: number;
     indeterminate: boolean;
     formatter: (value: number, max: number) => string;
-    thickness: number;
     showValue: boolean;
+    thickness: number;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
 declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
 export default _default;

package/dist/components/Slider/Slider.d.ts

@@ -19,8 +19,8 @@ declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {},
     range: boolean;
     min: number;
     step: number;
+    minStepsBetweenThumbs: number;
     showValue: boolean;
     marks: Record<number, string>;
-    minStepsBetweenThumbs: number;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 export default _default;

package/dist/components/Text/Text.d.ts

@@ -14,9 +14,9 @@ declare const __VLS_component: import('vue').DefineComponent<TextProps, {}, {},
     tone: import('./types').TextTone;
     align: import('./types').TextAlign;
     truncate: boolean | number;
+    mono: boolean;
     weight: import('./types').TextWeight;
     italic: boolean;
-    mono: boolean;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
 export default _default;

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';