@codingfactory/mediables-vue 2.4.22 → 2.5.0

package/dist/types/collection.d.ts

@@ -14,7 +14,7 @@ export interface UploadProgress {
     /** Upload progress percentage (0-100) */
     progress: number;
     /** Current upload status */
-    status: 'pending' | 'queued' | 'uploading' | 'processing' | 'completed' | 'error';
+    status: 'pending' | 'queued' | 'uploading' | 'attaching' | 'processing' | 'completed' | 'error';
     /** Error message if status is 'error' */
     error?: string | undefined;
     /** Uploaded media item (available when status is 'completed') */

package/dist/types/mediaLibraryPicker.d.ts

@@ -0,0 +1,182 @@
+import type { VNode } from 'vue';
+import type { StorageAdapter } from './adapter';
+import type { Media } from './media';
+export type MediaKind = 'image' | 'video' | 'audio' | 'document' | (string & {});
+export type MediaSort = 'newest' | 'oldest';
+export type MediaSelectionMode = 'single' | 'multiple';
+export type MediaLibraryUploadBehavior = 'adapter' | 'delegate';
+export type MediaLibraryView = {
+    scope: 'library';
+} | {
+    scope: 'album';
+    albumId: string;
+    albumName?: string;
+};
+export interface MediaLibraryFilters {
+    query?: string;
+    kinds?: MediaKind[];
+    sort?: MediaSort;
+}
+export interface MediaUploadTarget {
+    type: 'library' | 'album';
+    albumId?: string;
+}
+export interface MediaLibraryRequestConfig {
+    params?: Record<string, unknown>;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
+export interface MediaLibraryHttpClient {
+    get<T>(url: string, config?: MediaLibraryRequestConfig): Promise<T>;
+    post<T>(url: string, body?: unknown, config?: MediaLibraryRequestConfig): Promise<T>;
+    put?<T>(url: string, body?: unknown, config?: MediaLibraryRequestConfig): Promise<T>;
+    patch?<T>(url: string, body?: unknown, config?: MediaLibraryRequestConfig): Promise<T>;
+    delete?<T>(url: string, config?: MediaLibraryRequestConfig): Promise<T>;
+}
+export interface MediaLibraryPickerDeps {
+    httpClient: MediaLibraryHttpClient;
+    uploadAdapter?: StorageAdapter;
+    resolveThumbnailUrl?: (media: Media, variant?: 'sm' | 'md' | 'lg') => string | Promise<string>;
+}
+export interface MediaSessionPolicy {
+    key: string;
+    ttlMinutes?: number;
+    restoreSelection?: boolean;
+    restoreView?: boolean;
+    restoreUploadsMeta?: boolean;
+}
+export type SelectedItemStatus = 'ready' | 'hydrating' | 'missing' | 'forbidden' | 'uploading' | 'failed' | 'file_lost';
+export interface SelectedMediaItem {
+    id: string;
+    media: Media | null;
+    status: SelectedItemStatus;
+    statusMessage?: string;
+    countsTowardMax: boolean;
+}
+export interface MediaLibraryHydratedRecord {
+    id: string;
+    status: 'ready' | 'missing' | 'forbidden';
+    media?: Media;
+}
+export interface MediaLibraryResponsePagination {
+    next_cursor: string | null;
+    previous_cursor: string | null;
+    has_more: boolean;
+    per_page: number | null;
+    count: number | null;
+}
+export interface MediaLibraryResponseMeta {
+    cursor: string | null;
+    has_more: boolean;
+    pagination?: MediaLibraryResponsePagination;
+}
+export interface MediaLibraryResponse {
+    data: Media[];
+    meta: MediaLibraryResponseMeta;
+    hydrated: MediaLibraryHydratedRecord[];
+}
+export interface MediaLibraryApiEnvelope {
+    success?: boolean;
+    message?: string;
+    data?: unknown;
+    meta?: unknown;
+    hydrated?: unknown;
+}
+export interface MediaLibraryAlbum {
+    id: string;
+    name: string;
+    description?: string;
+    mediaCount?: number;
+}
+export interface MediaLibraryPickerMetric {
+    name: string;
+    payload?: Record<string, unknown>;
+    timestamp: string;
+}
+export interface MediaLibraryUploadRequestPayload {
+    files: File[];
+    view: MediaLibraryView;
+    filters: MediaLibraryFilters;
+    sessionId: string;
+}
+export type MediaLibraryPickerErrorCode = 'query_failed' | 'load_more_failed' | 'refresh_failed' | 'upload_failed' | 'upload_partial_failure' | 'selection_invalid' | 'permission_denied' | 'hydration_failed' | 'session_restore_failed' | 'configuration_error' | 'album_create_failed';
+export interface MediaLibraryPickerError {
+    code: MediaLibraryPickerErrorCode;
+    message: string;
+    retriable: boolean;
+    cause?: unknown;
+}
+export interface MediaLibraryPickerLabels {
+    title?: string;
+    searchPlaceholder?: string;
+    viewLibrary?: string;
+    browseAlbums?: string;
+    createAlbum?: string;
+    createAlbumNameLabel?: string;
+    emptyLibrary?: string;
+    emptyAlbum?: string;
+    networkError?: string;
+    retry?: string;
+    selectedCount?: (count: number) => string;
+    confirmAction?: string;
+    cancel?: string;
+    dismiss?: string;
+    uploadLabel?: string;
+    albumUnavailableTitle?: string;
+    albumUnavailableBody?: string;
+    goToLibrary?: string;
+}
+export interface MediaLibraryPickerProps {
+    deps: MediaLibraryPickerDeps;
+    modelValue?: string[];
+    defaultSelectedIds?: string[];
+    selectionMode?: MediaSelectionMode;
+    maxSelection?: number;
+    preserveSelectionOnViewChange?: boolean;
+    initialView?: MediaLibraryView;
+    initialFilters?: MediaLibraryFilters;
+    enableUpload?: boolean;
+    uploadBehavior?: MediaLibraryUploadBehavior;
+    enablePreview?: boolean;
+    enableAlbumCreation?: boolean;
+    allowedMediaKinds?: MediaKind[];
+    accept?: string;
+    validateSelection?: (items: SelectedMediaItem[]) => string | null;
+    uploadTarget?: MediaUploadTarget;
+    autoSelectUploaded?: boolean;
+    createAlbumDefaultVisibility?: 'private' | 'authenticated' | 'public';
+    sessionPolicy?: MediaSessionPolicy;
+    labels?: MediaLibraryPickerLabels;
+    testIdPrefix?: string;
+    telemetry?: (metric: MediaLibraryPickerMetric) => void;
+}
+export interface MediaLibraryConfirmPayload {
+    orderedIds: string[];
+    items: SelectedMediaItem[];
+    view: MediaLibraryView;
+    filters: MediaLibraryFilters;
+    dirty: boolean;
+    sessionId: string;
+}
+export interface MediaLibrarySelectionChangePayload {
+    orderedIds: string[];
+    items: SelectedMediaItem[];
+    dirty: boolean;
+}
+export interface MediaLibraryViewChangePayload {
+    from: MediaLibraryView;
+    to: MediaLibraryView;
+    reason: 'user' | 'restore' | 'permission-unavailable' | 'inline-album-created';
+    restoredFromSession: boolean;
+}
+export type PickerCancelReason = 'user' | 'backdrop' | 'escape' | 'host-close' | 'route-change';
+export interface MediaLibraryPickerSlots {
+    toolbar?: () => VNode[];
+    empty?: (ctx: {
+        view: MediaLibraryView;
+        filters: MediaLibraryFilters;
+    }) => VNode[];
+    previewMeta?: (ctx: {
+        media: Media;
+    }) => VNode[];
+}

package/dist/types/mediaLibraryState.d.ts

@@ -0,0 +1,29 @@
+import type { ComputedRef, Ref } from 'vue';
+import type { UploadProgress } from './collection';
+import type { Media } from './media';
+import type { MediaLibraryAlbum, MediaLibraryFilters, MediaLibraryPickerError, MediaLibraryView, SelectedMediaItem } from './mediaLibraryPicker';
+export interface MediaLibraryQueryState {
+    items: Ref<Media[]>;
+    cursor: Ref<string | null>;
+    hasMore: Ref<boolean>;
+    loading: Ref<boolean>;
+    loadingMore: Ref<boolean>;
+    permissionDenied: Ref<boolean>;
+    error: Ref<MediaLibraryPickerError | null>;
+}
+export interface MediaLibrarySelectionState {
+    items: Ref<SelectedMediaItem[]>;
+    orderedIds: ComputedRef<string[]>;
+}
+export interface MediaLibraryUploadState {
+    queue: ComputedRef<UploadProgress[]>;
+    isUploading: ComputedRef<boolean>;
+}
+export interface MediaLibraryControllerState {
+    view: Ref<MediaLibraryView>;
+    filters: Ref<MediaLibraryFilters>;
+    albums: Ref<MediaLibraryAlbum[]>;
+    query: MediaLibraryQueryState;
+    selection: MediaLibrarySelectionState;
+    upload: MediaLibraryUploadState;
+}

package/docs/media-library-api.md

@@ -0,0 +1,76 @@
+# Media Library API
+
+`MediaLibraryPicker` reads media through a host-provided `httpClient`. For blow.glass, the host implements the contract in `socialkit/Modules/Media` at `GET /api/v1/media/library`.
+
+## Request
+
+`GET /api/v1/media/library`
+
+Query parameters:
+
+- `view[scope]`: `library | album`
+- `view[album_id]`: required when `scope=album`
+- `query`: optional search string
+- `kinds[]`: optional `image | video | audio | document`
+- `sort`: `newest | oldest`
+- `created_after`: optional ISO datetime
+- `uploaded_by_me`: optional boolean
+- `cursor`: optional opaque cursor
+- `per_page`: optional `1-100`, default `40`
+- `hydrate_ids[]`: optional UUID list, max `50`
+
+## Success Response
+
+```json
+{
+  "data": [
+    {
+      "uuid": "01981b2d-1111-4f75-8d0a-123456789abc",
+      "file_name": "furnace-progress.jpg",
+      "mime_type": "image/jpeg",
+      "size": 204800,
+      "disk": "public",
+      "collection_name": "images",
+      "original_url": "https://example.test/storage/furnace-progress.jpg",
+      "url": "https://example.test/storage/furnace-progress.jpg",
+      "thumbnail_url": "https://example.test/storage/conversions/furnace-progress-thumb.jpg",
+      "preview_url": "https://example.test/storage/conversions/furnace-progress-preview.jpg",
+      "caption": null,
+      "alt_text": null,
+      "created_at": "2026-04-12T12:34:56+00:00",
+      "updated_at": "2026-04-12T12:34:56+00:00"
+    }
+  ],
+  "meta": {
+    "cursor": "eyJjIjoiMjAyNi0wNC0xMlQxMjozNDo1Ni4xMjM0NTYrMDA6MDAiLCJpIjoiMDE5ODFiMmQtMTExMS00Zjc1LThkMGEtMTIzNDU2Nzg5YWJjIn0=",
+    "has_more": true
+  },
+  "hydrated": [
+    {
+      "id": "01981b2d-1111-4f75-8d0a-123456789abc",
+      "status": "ready",
+      "media": {
+        "uuid": "01981b2d-1111-4f75-8d0a-123456789abc"
+      }
+    },
+    {
+      "id": "01981b2d-2222-4f75-8d0a-123456789abc",
+      "status": "missing"
+    }
+  ]
+}
+```
+
+## Cursor Contract
+
+- The cursor is base64-encoded JSON with:
+  - `c`: ISO datetime with microseconds
+  - `i`: media UUID
+- `sort=newest` uses `(created_at DESC, uuid DESC)`
+- `sort=oldest` uses `(created_at ASC, uuid ASC)`
+
+## Host Notes
+
+- Host apps should inject a thin client that returns parsed bodies, not Axios responses.
+- Upload flows should reuse `StorageAdapter` and `useMediaUploadQueue`.
+- The picker assumes `media.deleted_at IS NULL` is enforced by the backend query layer, including joined album queries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codingfactory/mediables-vue",
-  "version": "2.4.22",
+  "version": "2.5.0",
   "publishConfig": {
     "access": "public"
   },
@@ -16,7 +16,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "docs/video-subsystem"
+    "docs/video-subsystem",
+    "docs/media-library-api.md"
   ],
   "exports": {
     ".": {
@@ -48,6 +49,7 @@
     "docs:preview": "redocly preview-docs docs/openapi.yaml"
   },
   "peerDependencies": {
+    "@tanstack/vue-virtual": "^3.10.8",
     "@ionic/vue": "^8.0.0",
     "@pixi/extract": "^7.2.4",
     "@pixi/filter-color-replace": "^5.1.1",
@@ -84,6 +86,7 @@
   "dependencies": {
     "@capacitor/haptics": "^7.0.2",
     "@capacitor/status-bar": "^7.0.2",
+    "@tanstack/vue-virtual": "^3.10.8",
     "@ionic/vue": "^8.0.0",
     "@material/material-color-utilities": "^0.3.0",
     "@vueuse/core": "^12.0.0",