@webx-ui/module-media 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 webx-ui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @webx-ui/module-media
+
+The file manager of a [WebX UI](https://github.com/webx-ui/webx-ui) admin panel: folders, files,
+uploads, previews and an image editor. Pairs with
+[`webx-ui/module-media`](https://packagist.org/packages/webx-ui/module-media) on the server.
+
+```bash
+pnpm add @webx-ui/module-media
+```
+
+```ts
+import { createAdmin } from '@webx-ui/admin'
+import { auth } from '@webx-ui/module-auth'
+import { media } from '@webx-ui/module-media'
+
+import '@webx-ui/core/style.css'
+import '@webx-ui/admin/style.css'
+import '@webx-ui/module-media/style.css'
+
+createAdmin({
+  basePath: '/cms',
+  modules: [media()],
+  plugins: [auth()],
+}).mount()
+```
+
+The section appears once both halves are installed — the server reports the module, and this
+lists its front end.
+
+## Picking a file from a form
+
+```ts
+import { openMediaPicker } from '@webx-ui/module-media'
+
+const file = await openMediaPicker({ accept: 'image' })
+// `undefined` when the dialog was closed.
+```
+
+Or as a field, which keeps the words this entity uses for the picture beside the reference to it:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { WxMediaField, type MediaValue } from '@webx-ui/module-media'
+
+const cover = ref<MediaValue | null>(null)
+</script>
+
+<template>
+  <wx-media-field v-model="cover" label="Cover" />
+</template>
+```
+
+`MediaValue` is `{ path, alt, title }`. **`alt` and `title` belong to the entity, not to the
+file** — one picture used by two articles needs two captions. The address is worked out from
+`path` when the page is drawn, so the library can move to another disk without touching a single
+article.
+
+## What it draws
+
+`WxMediaManager` is the section itself: a folder tree, a grid of cards with rubber-band
+selection, upload, search, a type filter and paging. `WxMediaPicker` is the same manager in a
+dialog — deliberately the same, because a picker that browses differently is a second thing to
+learn.
+
+Previews come from the server's thumbnail endpoint rather than from the files, so a grid of forty
+photographs is forty thumbnails.
+
+Editing a picture sends **operations** — crop, rotate, flip, resize — rather than the canvas's
+own result: the canvas works on a preview, and the server applies them to the original at full
+size, over the same key, so links already written into content keep working. Filters and
+adjustments are switched off until the server can be told about them.
+
+## API client
+
+```ts
+import { createMediaApi } from '@webx-ui/module-media'
+import { useAdmin } from '@webx-ui/admin'
+
+const api = createMediaApi(useAdmin())
+const page = await api.files({ q: 'sofa', type: 'image' })
+```
+
+## Licence
+
+MIT.

package/dist/DirectoryTree.d.ts

@@ -0,0 +1,21 @@
+import { MediaDirectory } from './types';
+/**
+ * The folders, on the left.
+ *
+ * The root carries a translated label rather than the title it was given in the database: it is
+ * the library itself, and an editor should not have to know it is a row.
+ */
+type __VLS_Props = {
+    directories: MediaDirectory[];
+};
+type __VLS_PublicProps = {
+    'selected'?: number | null;
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    move: (id: number, parentId: number) => any;
+    "update:selected": (value: number | null) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onMove?: ((id: number, parentId: number) => any) | undefined;
+    "onUpdate:selected"?: ((value: number | null) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/FileGrid.d.ts

@@ -0,0 +1,33 @@
+import { MediaApi } from './api';
+import { MediaFile } from './types';
+/**
+ * The files, as cards, with a rubber band over them.
+ *
+ * Previews come from the server's thumbnail endpoint rather than the files themselves: a grid of
+ * forty photographs is forty full-size images otherwise, and on a phone that is the difference
+ * between a screen and a wait.
+ */
+type __VLS_Props = {
+    files: MediaFile[];
+    api: MediaApi;
+    query?: string;
+    /** A picker takes one file; the manager selects to act on a batch. */
+    single?: boolean;
+};
+type __VLS_PublicProps = {
+    'selected'?: number[];
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:selected": (value: number[]) => any;
+    open: (file: MediaFile) => any;
+    rename: (file: MediaFile, name: string) => any;
+    edit: (file: MediaFile) => any;
+    remove: (file: MediaFile) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:selected"?: ((value: number[]) => any) | undefined;
+    onOpen?: ((file: MediaFile) => any) | undefined;
+    onRename?: ((file: MediaFile, name: string) => any) | undefined;
+    onEdit?: ((file: MediaFile) => any) | undefined;
+    onRemove?: ((file: MediaFile) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/MediaField.d.ts

@@ -0,0 +1,28 @@
+import { MediaKind, MediaValue } from './types';
+/**
+ * A picture on a form, with the words this entity uses for it.
+ *
+ * `alt` and `title` live here rather than on the file because one picture is used by two
+ * articles and needs two captions. What the field stores is the key and those words; the
+ * address is worked out when the page is drawn, so moving the library to another disk changes
+ * nothing here.
+ */
+type __VLS_Props = {
+    label?: string;
+    accept?: MediaKind | null;
+    /** Off for a decorative picture, where a caption is noise. */
+    captions?: boolean;
+};
+type __VLS_PublicProps = {
+    modelValue?: MediaValue | null;
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: MediaValue | null) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: MediaValue | null) => any) | undefined;
+}>, {
+    label: string;
+    accept: MediaKind | null;
+    captions: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/MediaManager.d.ts

@@ -0,0 +1,29 @@
+import { MediaFile, MediaKind } from './types';
+/**
+ * The library: folders on the left, files on the right, a row of icons over both.
+ *
+ * Everything the screen does is one request and a reload of the part that changed — there is no
+ * cache here on purpose. A library is edited by several people, and a panel that believes its
+ * own copy shows a folder that was emptied an hour ago.
+ *
+ * The width that decides the layout is this component's own, not the window's: the same manager
+ * is a page, half of a picker dialog, and a phone.
+ */
+type __VLS_Props = {
+    /** A picker hands one file back instead of managing the library. */
+    picking?: boolean;
+    /** Only these kinds can be chosen, when picking. */
+    accept?: MediaKind | null;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    pick: (file: MediaFile) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onPick?: ((file: MediaFile) => any) | undefined;
+}>, {
+    picking: boolean;
+    accept: MediaKind | null;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    root: HTMLDivElement;
+    picker: HTMLInputElement;
+}, HTMLDivElement>;
+export default _default;

package/dist/MediaPage.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, HTMLElement>;
+export default _default;

package/dist/MediaPicker.d.ts

@@ -0,0 +1,19 @@
+import { MediaKind } from './types';
+/**
+ * The library as a dialog, for a form that needs a picture.
+ *
+ * The same manager, not a second one: a picker that browses differently from the manager is a
+ * second thing to learn and a second thing to keep working.
+ */
+type __VLS_Props = {
+    accept?: MediaKind | null;
+    title?: string;
+    /** Opened to manage the library rather than to choose from it. */
+    manage?: boolean;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    title: string;
+    accept: MediaKind | null;
+    manage: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/MediaToolbar.d.ts

@@ -0,0 +1,38 @@
+import { MediaKind } from './types';
+/**
+ * One row of icons over the files.
+ *
+ * Actions rather than labelled buttons: the row has to survive a phone and a picker dialog half
+ * the width of a window, and a row of words does not. What each icon means is a tooltip away,
+ * and what is chosen is said in the icon's own label.
+ */
+type __VLS_Props = {
+    canUpload: boolean;
+    canManage: boolean;
+    selected: number;
+    /** Narrow screens get the folders behind a button instead of beside the files. */
+    compact: boolean;
+};
+type __VLS_PublicProps = {
+    'search'?: string;
+    'type'?: MediaKind | 'all';
+    'sort'?: string;
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    move: () => any;
+    remove: () => any;
+    upload: () => any;
+    folders: () => any;
+    "update:search": (value: string) => any;
+    "update:type": (value: MediaKind | "all") => any;
+    "update:sort": (value: string) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onMove?: (() => any) | undefined;
+    onRemove?: (() => any) | undefined;
+    onUpload?: (() => any) | undefined;
+    onFolders?: (() => any) | undefined;
+    "onUpdate:search"?: ((value: string) => any) | undefined;
+    "onUpdate:type"?: ((value: MediaKind | "all") => any) | undefined;
+    "onUpdate:sort"?: ((value: string) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLElement>;
+export default _default;

package/dist/MoveDialog.d.ts

@@ -0,0 +1,15 @@
+import { MediaDirectory } from './types';
+/**
+ * Where to put the selected files.
+ *
+ * A list of folders rather than a box to type in: an editor knows a folder by its name and its
+ * place in the tree, and has no reason to ever learn that it also has a number.
+ */
+type __VLS_Props = {
+    directories: MediaDirectory[];
+    /** The folder they are in now, which is not worth offering. */
+    from?: number | null;
+    count: number;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/NameDialog.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A name, asked for properly.
+ *
+ * `window.prompt` is not an option: a browser is free to refuse it — an embedded frame usually
+ * does — and then the button simply does nothing, which is exactly how "new folder" looked.
+ */
+type __VLS_Props = {
+    title: string;
+    label?: string;
+    value?: string;
+    confirmText?: string;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    label: string;
+    value: string;
+    confirmText: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    input: HTMLDivElement;
+}, any>;
+export default _default;

package/dist/api.d.ts

@@ -0,0 +1,23 @@
+import { AdminContext } from '@webx-ui/admin';
+import { EditOperations, FileQuery, MediaDirectory, MediaFile, MediaPage } from './types';
+export interface MediaApi {
+    directories(): Promise<MediaDirectory[]>;
+    createDirectory(parentId: number, title: string): Promise<MediaDirectory>;
+    renameDirectory(id: number, title: string): Promise<MediaDirectory>;
+    moveDirectory(id: number, parentId: number): Promise<MediaDirectory>;
+    /** Without `force` the server refuses a folder that holds anything, and says what it holds. */
+    deleteDirectory(id: number, force?: boolean): Promise<void>;
+    files(query?: FileQuery): Promise<MediaPage>;
+    file(id: number): Promise<MediaFile>;
+    upload(directoryId: number, files: File[], onProgress?: (percent: number) => void): Promise<MediaFile[]>;
+    rename(id: number, name: string): Promise<MediaFile>;
+    move(ids: number[], directoryId: number): Promise<number>;
+    remove(ids: number[]): Promise<number>;
+    removeOne(id: number): Promise<void>;
+    edit(id: number, operations: EditOperations): Promise<MediaFile>;
+    copy(id: number): Promise<MediaFile>;
+    restoreOriginal(id: number): Promise<MediaFile>;
+    /** The address of a preview at a size the server allows. */
+    thumb(file: MediaFile, width: number, height?: number, fit?: 'cover' | 'contain'): string | null;
+}
+export declare function createMediaApi(admin: AdminContext): MediaApi;

package/dist/i18n.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Put this package's English under the panel's dictionary, once per panel.
+ *
+ * The server's translations land on top of it when they arrive. What this prevents is the half
+ * second — or the whole session, in a panel assembled without a server — where a screen shows
+ * `manager.upload` instead of a word.
+ */
+export declare function useMediaMessages(): void;

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { AdminModule } from '@webx-ui/admin';
+import { mediaMessages } from './messages';
+export interface MediaOptions {
+    /** Where the section lives inside the panel. */
+    path?: string;
+}
+/**
+ * The file manager as a section of the panel.
+ *
+ * The id matches the module the server reports, which is what makes the entry appear in the
+ * navigation: a section shows up when both halves are installed, and stays out of the way when
+ * only one is.
+ */
+export declare function media(options?: MediaOptions): AdminModule;
+export { mediaMessages };
+export { createMediaApi, type MediaApi } from './api';
+export { openMediaLibrary, openMediaPicker, type MediaPickerOptions } from './openMediaPicker';
+export { default as WxMediaManager } from './MediaManager';
+export { default as WxMediaPage } from './MediaPage';
+export { default as WxMediaPicker } from './MediaPicker';
+export { default as WxMediaField } from './MediaField';
+export type { DirectoryNotEmpty, EditOperations, FileQuery, MediaDirectory, MediaFile, MediaKind, MediaPage, MediaValue, } from './types';