nuxt-ui-tools 1.7.0 → 1.8.1

package/dist/runtime/file-preview/components/shell/file-preview-thumb.vue

@@ -0,0 +1,69 @@
+<script setup>
+import UIcon from "@nuxt/ui/components/Icon.vue";
+import { useObjectUrl } from "@vueuse/core";
+import { computed, ref } from "vue";
+import { isString } from "../../../shared/utils/predicate";
+const INLINE_THUMBNAIL_BYTES = 1.5 * 1024 * 1024;
+const props = defineProps({
+  item: { type: Object, required: true },
+  icon: { type: String, required: true },
+  current: { type: Boolean, required: true },
+  label: { type: String, required: true }
+});
+defineEmits(["select"]);
+const broken = ref(false);
+const display = computed(() => props.item.rendition ?? props.item);
+const localImage = computed(() => {
+  const { src } = display.value.file;
+  return display.value.kind === "image" && src instanceof Blob ? src : null;
+});
+const localUrl = useObjectUrl(localImage);
+const image = computed(() => {
+  const { file, kind, size } = display.value;
+  if (props.item.file.thumbnail) return props.item.file.thumbnail;
+  if (file.poster) return file.poster;
+  if (localUrl.value) return localUrl.value;
+  const small = size === null || size <= INLINE_THUMBNAIL_BYTES;
+  return kind === "image" && small && isString(file.src) ? file.src : null;
+});
+</script>
+
+<template>
+  <button
+    type="button"
+    :class="[
+  'relative grid h-11 w-16 shrink-0 place-items-center overflow-hidden rounded-md border bg-elevated text-muted transition',
+  current ? 'border-transparent outline-2 outline-offset-1 outline-primary' : 'border-default opacity-80 hover:opacity-100'
+]"
+    :aria-label="label"
+    :aria-current="current ? 'true' : void 0"
+    data-file-preview-thumb=""
+    @click="$emit('select')"
+  >
+    <img
+      v-if="image && !broken"
+      :src="image"
+      alt=""
+      loading="lazy"
+      class="size-full object-cover"
+      @error="broken = true"
+    />
+    <template v-else>
+      <UIcon :name="icon" class="size-4" aria-hidden="true" />
+      <span
+        v-if="item.extension"
+        class="absolute right-1 bottom-0.5 font-mono text-[8.5px] leading-none font-semibold uppercase"
+        aria-hidden="true"
+      >
+        {{ item.extension }}
+      </span>
+    </template>
+    <span
+      v-if="display.kind === 'video'"
+      class="absolute inset-0 grid place-items-center bg-black/25 text-white"
+      aria-hidden="true"
+    >
+      <UIcon name="i-lucide-play" class="size-3.5" />
+    </span>
+  </button>
+</template>

package/dist/runtime/file-preview/components/shell/file-preview-thumb.vue.d.ts

@@ -0,0 +1,14 @@
+import type { FilePreviewItem } from '../../types/index.js';
+type __VLS_Props = {
+    item: FilePreviewItem;
+    icon: string;
+    current: boolean;
+    label: string;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    select: () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onSelect?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/file-preview/components/shell/file-preview-tools.d.vue.ts

@@ -0,0 +1,13 @@
+declare var __VLS_7: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_7) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/file-preview/components/shell/file-preview-tools.vue

@@ -0,0 +1,10 @@
+<script setup>
+import { useFilePreviewShell } from "../../composables/use-file-preview-shell";
+const shell = useFilePreviewShell();
+</script>
+
+<template>
+  <Teleport v-if="shell.tools.value" :to="shell.tools.value">
+    <slot />
+  </Teleport>
+</template>

package/dist/runtime/file-preview/components/shell/file-preview-tools.vue.d.ts

@@ -0,0 +1,13 @@
+declare var __VLS_7: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_7) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/file-preview/composables/use-file-preview-api.d.ts

@@ -0,0 +1,21 @@
+import type { InjectionKey } from 'vue';
+import type { FilePreviewApi } from '../types/index.js';
+export declare const filePreviewApiKey: InjectionKey<FilePreviewApi>;
+/**
+ * Creates a file preview API. Inside a Nuxt app the module already creates one for the whole app,
+ * exposed as `useNuxtApp().$filePreview` and `useFilePreview()`.
+ */
+export declare function createFilePreviewApi(): FilePreviewApi;
+/**
+ * Provides the file preview API to a subtree. Inside a Nuxt app it reuses the app-wide instance,
+ * so previews opened from actions outside setup render in this provider.
+ */
+export declare function provideFilePreview(): FilePreviewApi;
+/**
+ * Returns the file preview API.
+ *
+ * @example
+ * const filePreview = useFilePreview()
+ * filePreview.open(files, { index: 2 })
+ */
+export declare function useFilePreview(): FilePreviewApi;

package/dist/runtime/file-preview/composables/use-file-preview-api.js

@@ -0,0 +1,83 @@
+import { computed, inject, provide, ref, shallowRef } from "vue";
+import { createFilePreviewInstance } from "../utils/instance.js";
+import { mergeFilePreviewRenderers } from "../utils/renderers.js";
+export const filePreviewApiKey = Symbol(
+  "nuxt-ui-tools-file-preview-api"
+);
+export function createFilePreviewApi() {
+  const instances = shallowRef([]);
+  const custom = shallowRef([]);
+  const providers = ref(0);
+  const renderers = computed(() => mergeFilePreviewRenderers(custom.value));
+  let sequence = 0;
+  function find(id) {
+    return instances.value.find((instance) => instance.id === id) ?? null;
+  }
+  function remove(id) {
+    instances.value = instances.value.filter((instance) => instance.id !== id);
+  }
+  const open = (input, options = {}) => {
+    const existing = options.id ? find(options.id) : null;
+    if (existing) {
+      existing.handle.update(input);
+      if (options.index !== void 0) existing.handle.goTo(options.index);
+      existing.open.value = true;
+      return existing.handle;
+    }
+    sequence += 1;
+    const instance = createFilePreviewInstance({
+      id: options.id ?? `file-preview-${sequence}`,
+      input,
+      onDispose: remove,
+      options,
+      renderers: () => renderers.value
+    });
+    instances.value = [...instances.value, instance];
+    return instance.handle;
+  };
+  function close(id) {
+    const instance = id ? find(id) : instances.value.at(-1) ?? null;
+    if (!instance) return false;
+    instance.handle.close();
+    return true;
+  }
+  function register(renderer) {
+    custom.value = [renderer, ...custom.value.filter((entry) => entry.kind !== renderer.kind)];
+    return () => {
+      custom.value = custom.value.filter((entry) => entry !== renderer);
+    };
+  }
+  function attach() {
+    providers.value += 1;
+    let attached = true;
+    return () => {
+      if (!attached) return;
+      attached = false;
+      providers.value -= 1;
+    };
+  }
+  return {
+    attach,
+    close,
+    closeAll: () => {
+      for (const instance of instances.value) instance.handle.close();
+    },
+    instances: computed(() => instances.value),
+    isOpen: (id) => id ? find(id) !== null : instances.value.length > 0,
+    mounted: computed(() => providers.value > 0),
+    open,
+    register,
+    renderers
+  };
+}
+export function provideFilePreview() {
+  const api = inject(filePreviewApiKey, null) ?? createFilePreviewApi();
+  provide(filePreviewApiKey, api);
+  return api;
+}
+export function useFilePreview() {
+  const api = inject(filePreviewApiKey, null);
+  if (!api)
+    throw new Error("File preview API is not provided. Wrap your app with <UiFilePreviewProvider>.");
+  return api;
+}

package/dist/runtime/file-preview/composables/use-file-preview-shell.d.ts

@@ -0,0 +1,13 @@
+import type { InjectionKey } from 'vue';
+import type { FilePreviewMarkdownRenderer, FilePreviewShellContext } from '../types/index.js';
+export declare const filePreviewShellKey: InjectionKey<FilePreviewShellContext>;
+export declare const filePreviewMarkdownKey: InjectionKey<FilePreviewMarkdownRenderer | null>;
+/** Whether a key press belongs to the focused control rather than to the preview. */
+export declare function isFilePreviewControlKey(event: KeyboardEvent): boolean;
+/** Shell of the preview the calling renderer is shown in. */
+export declare function useFilePreviewShell(): FilePreviewShellContext;
+/**
+ * Runs `handler` for the given keys while the preview has focus, except when a field, slider, menu,
+ * or embedded document owns the key.
+ */
+export declare function onFilePreviewKey(keys: readonly string[], handler: (event: KeyboardEvent) => void): void;

package/dist/runtime/file-preview/composables/use-file-preview-shell.js

@@ -0,0 +1,30 @@
+import { useEventListener } from "@vueuse/core";
+import { inject } from "vue";
+export const filePreviewShellKey = Symbol(
+  "nuxt-ui-tools-file-preview-shell"
+);
+export const filePreviewMarkdownKey = Symbol(
+  "nuxt-ui-tools-file-preview-markdown"
+);
+const KEY_OWNERS = 'input, textarea, select, iframe, [contenteditable="true"], [role="slider"], [role="menu"], [role="menuitem"]';
+export function isFilePreviewControlKey(event) {
+  if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.altKey) return true;
+  const target = event.target instanceof Element ? event.target : null;
+  if (!target) return false;
+  if (target.closest(KEY_OWNERS)) return true;
+  return (event.key === " " || event.key === "Enter") && target.closest("button, a") !== null;
+}
+export function useFilePreviewShell() {
+  const shell = inject(filePreviewShellKey, null);
+  if (!shell)
+    throw new Error("useFilePreviewShell() must be called inside a file preview renderer.");
+  return shell;
+}
+export function onFilePreviewKey(keys, handler) {
+  const shell = useFilePreviewShell();
+  useEventListener(shell.root, "keydown", (event) => {
+    if (!keys.includes(event.key) || isFilePreviewControlKey(event)) return;
+    event.preventDefault();
+    handler(event);
+  });
+}

package/dist/runtime/file-preview/composables/use-file-preview-source.d.ts

@@ -0,0 +1,17 @@
+import type { FilePreviewItem } from '../types/index.js';
+type FilePreviewSourceStatus = 'loading' | 'ready' | 'error';
+/**
+ * Resolves the shown file's source. URLs are used as they are, `Blob` sources become an object URL
+ * that is revoked when the file changes, and source functions run once per file for the life of
+ * the preview, then again on `retry()`.
+ */
+export declare function useFilePreviewSource(item: () => FilePreviewItem | null): {
+    blob: import("vue").ComputedRef<Blob | null>;
+    error: import("vue").ShallowRef<Error | null, Error | null>;
+    /** Whether `retry()` can fetch the source again, which only a source function can. */
+    retryable: import("vue").ComputedRef<boolean>;
+    retry: () => Promise<void>;
+    status: import("vue").Ref<FilePreviewSourceStatus, FilePreviewSourceStatus>;
+    url: import("vue").ComputedRef<string | null>;
+};
+export {};

package/dist/runtime/file-preview/composables/use-file-preview-source.js

@@ -0,0 +1,51 @@
+import { useObjectUrl } from "@vueuse/core";
+import { computed, ref, shallowRef, watch } from "vue";
+import { isFunction, isString } from "../../shared/utils/predicate.js";
+const resolved = /* @__PURE__ */ new WeakMap();
+export function useFilePreviewSource(item) {
+  const value = shallowRef(null);
+  const status = ref("loading");
+  const error = shallowRef(null);
+  const blob = computed(() => value.value instanceof Blob ? value.value : null);
+  const objectUrl = useObjectUrl(blob);
+  const url = computed(() => isString(value.value) ? value.value : objectUrl.value ?? null);
+  let attempt = 0;
+  function settle(next) {
+    value.value = next;
+    error.value = null;
+    status.value = "ready";
+  }
+  async function resolve(options) {
+    attempt += 1;
+    const current = attempt;
+    const file = item();
+    if (!file) return;
+    const src = file.file.src;
+    if (isString(src) || src instanceof Blob) return settle(src);
+    const known = options.force ? void 0 : resolved.get(file);
+    if (known !== void 0) return settle(known);
+    value.value = null;
+    error.value = null;
+    status.value = "loading";
+    try {
+      const next = await src();
+      if (current !== attempt) return;
+      resolved.set(file, next);
+      settle(next);
+    } catch (cause) {
+      if (current !== attempt) return;
+      error.value = cause instanceof Error ? cause : new Error(String(cause));
+      status.value = "error";
+    }
+  }
+  watch(item, () => resolve({ force: false }), { immediate: true });
+  return {
+    blob,
+    error,
+    /** Whether `retry()` can fetch the source again, which only a source function can. */
+    retryable: computed(() => isFunction(item()?.file.src)),
+    retry: () => resolve({ force: true }),
+    status,
+    url
+  };
+}

package/dist/runtime/file-preview/composables/use-file-preview-text.d.ts

@@ -0,0 +1,14 @@
+import type { FilePreviewRendererProps } from '../types/index.js';
+/** Text previews read at most this many bytes, then cancel the read. */
+export declare const FILE_PREVIEW_TEXT_LIMIT: number;
+type FilePreviewTextStatus = 'loading' | 'ready' | 'error';
+/** Reads a text file for a renderer: from its bytes when it is a `Blob`, otherwise with `fetch`. */
+export declare function useFilePreviewText(props: Pick<FilePreviewRendererProps, 'url' | 'blob'>): {
+    error: import("vue").ShallowRef<Error | null, Error | null>;
+    notice: import("vue").ComputedRef<string | null>;
+    status: import("vue").Ref<FilePreviewTextStatus, FilePreviewTextStatus>;
+    text: import("vue").Ref<string, string>;
+    total: import("vue").Ref<number | null, number | null>;
+    truncated: import("vue").Ref<boolean, boolean>;
+};
+export {};

package/dist/runtime/file-preview/composables/use-file-preview-text.js

@@ -0,0 +1,79 @@
+import { computed, onScopeDispose, ref, shallowRef, watch } from "vue";
+import { useUiToolsLocale } from "../../i18n/use-locale.js";
+import { formatFileSize } from "../../shared/utils/file.js";
+export const FILE_PREVIEW_TEXT_LIMIT = 512 * 1024;
+async function readBlob(blob) {
+  return {
+    text: await blob.slice(0, FILE_PREVIEW_TEXT_LIMIT).text(),
+    total: blob.size,
+    truncated: blob.size > FILE_PREVIEW_TEXT_LIMIT
+  };
+}
+async function readUrl(url, signal) {
+  const response = await fetch(url, { signal });
+  if (!response.ok) throw new Error(`${response.status} ${response.statusText}`.trim());
+  const header = Number(response.headers.get("content-length"));
+  const total = Number.isFinite(header) && header > 0 ? header : null;
+  if (!response.body) {
+    const text2 = await response.text();
+    return {
+      text: text2.slice(0, FILE_PREVIEW_TEXT_LIMIT),
+      total,
+      truncated: text2.length > FILE_PREVIEW_TEXT_LIMIT
+    };
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let text = "";
+  let received = 0;
+  for (; ; ) {
+    const chunk = await reader.read();
+    if (chunk.done) break;
+    const room = FILE_PREVIEW_TEXT_LIMIT - received;
+    received += chunk.value.byteLength;
+    if (chunk.value.byteLength > room) {
+      text += decoder.decode(chunk.value.subarray(0, room));
+      await reader.cancel();
+      return { text, total, truncated: true };
+    }
+    text += decoder.decode(chunk.value, { stream: true });
+  }
+  return { text: text + decoder.decode(), total: total ?? received, truncated: false };
+}
+export function useFilePreviewText(props) {
+  const { code, t } = useUiToolsLocale();
+  const text = ref("");
+  const truncated = ref(false);
+  const total = ref(null);
+  const status = ref("loading");
+  const error = shallowRef(null);
+  let controller = null;
+  async function load() {
+    controller?.abort();
+    const current = new AbortController();
+    controller = current;
+    status.value = "loading";
+    error.value = null;
+    try {
+      const result = props.blob ? await readBlob(props.blob) : await readUrl(props.url, current.signal);
+      if (current.signal.aborted) return;
+      text.value = result.text.replace(/^/u, "");
+      truncated.value = result.truncated;
+      total.value = result.total;
+      status.value = "ready";
+    } catch (cause) {
+      if (current.signal.aborted) return;
+      error.value = cause instanceof Error ? cause : new Error(String(cause));
+      status.value = "error";
+    }
+  }
+  watch(() => [props.url, props.blob], load, { immediate: true });
+  onScopeDispose(() => controller?.abort());
+  const notice = computed(
+    () => truncated.value ? t("filePreview.truncated", {
+      size: formatFileSize(FILE_PREVIEW_TEXT_LIMIT, code.value),
+      total: total.value === null ? "\u2014" : formatFileSize(total.value, code.value)
+    }) : null
+  );
+  return { error, notice, status, text, total, truncated };
+}

package/dist/runtime/file-preview/index.d.ts

@@ -0,0 +1,5 @@
+export { createFilePreviewApi, filePreviewApiKey, provideFilePreview, useFilePreview, } from './composables/use-file-preview-api.js';
+export { onFilePreviewKey, useFilePreviewShell } from './composables/use-file-preview-shell.js';
+export { FILE_PREVIEW_TEXT_LIMIT, useFilePreviewText } from './composables/use-file-preview-text.js';
+export { builtInFilePreviewRenderers, defineFilePreviewRenderer, detectFilePreviewKind, matchFilePreview, } from './utils/renderers.js';
+export type * from './types';

package/dist/runtime/file-preview/index.js

@@ -0,0 +1,14 @@
+export {
+  createFilePreviewApi,
+  filePreviewApiKey,
+  provideFilePreview,
+  useFilePreview
+} from "./composables/use-file-preview-api.js";
+export { onFilePreviewKey, useFilePreviewShell } from "./composables/use-file-preview-shell.js";
+export { FILE_PREVIEW_TEXT_LIMIT, useFilePreviewText } from "./composables/use-file-preview-text.js";
+export {
+  builtInFilePreviewRenderers,
+  defineFilePreviewRenderer,
+  detectFilePreviewKind,
+  matchFilePreview
+} from "./utils/renderers.js";

package/dist/runtime/file-preview/plugins/file-preview-api.d.ts

@@ -0,0 +1,11 @@
+/**
+ * One file preview API for the whole app: components reach it with `useFilePreview()`, and code
+ * running outside setup (actions, stores) with `useNuxtApp().$filePreview`.
+ * `<UiFilePreviewProvider>` renders the previews it opens.
+ */
+declare const _default: import("#app/nuxt").Plugin<{
+    filePreview: import("..").FilePreviewApi;
+}> & import("#app/nuxt").ObjectPlugin<{
+    filePreview: import("..").FilePreviewApi;
+}>;
+export default _default;

package/dist/runtime/file-preview/plugins/file-preview-api.js

@@ -0,0 +1,10 @@
+import { defineNuxtPlugin } from "#app";
+import { createFilePreviewApi, filePreviewApiKey } from "../composables/use-file-preview-api.js";
+export default defineNuxtPlugin({
+  name: "nuxt-ui-tools:file-preview-api",
+  setup(nuxtApp) {
+    const filePreview = createFilePreviewApi();
+    nuxtApp.vueApp.provide(filePreviewApiKey, filePreview);
+    return { provide: { filePreview } };
+  }
+});

package/dist/runtime/file-preview/types/api.d.ts

@@ -0,0 +1,74 @@
+import type { ComputedRef, Ref, ShallowRef } from 'vue';
+import type { MaybePromise } from '../../shared/types/utils.js';
+import type { FilePreviewFile, FilePreviewInput, FilePreviewItem } from './file.js';
+import type { FilePreviewModeInput, FilePreviewRendererDefinition } from './renderer.js';
+export interface FilePreviewOptions {
+    /** Opening the same id again updates and keeps the existing preview instead of stacking one. */
+    id?: string;
+    /** File shown first in a gallery. */
+    index?: number;
+    /**
+     * Container, or a responsive value such as `fullscreen md:drawer`. Without it, each file's
+     * renderer suggests one and the largest wins, so navigating a gallery never swaps containers.
+     */
+    mode?: FilePreviewModeInput;
+    /** `strip` shows thumbnails, `counter` only the position. Phones always show the counter. */
+    gallery?: 'strip' | 'counter';
+    /** Wraps from the last file to the first. */
+    loop?: boolean;
+    /** Page PDFs open at, passed as the `#page=` open parameter. */
+    pdf?: {
+        page?: number;
+    };
+    onChange?: (file: FilePreviewFile, index: number) => void;
+    onClose?: () => void;
+}
+export interface FilePreviewHandle {
+    readonly id: string;
+    readonly index: Readonly<Ref<number>>;
+    next: () => void;
+    previous: () => void;
+    goTo: (index: number) => void;
+    /** Replaces the files. The position is kept when it still exists. */
+    update: (input: FilePreviewInput | readonly FilePreviewInput[]) => void;
+    close: () => void;
+    /** Resolves once the preview has closed and left the screen. */
+    readonly closed: Promise<void>;
+}
+export interface FilePreviewInstance {
+    readonly id: string;
+    readonly files: ShallowRef<readonly FilePreviewItem[]>;
+    readonly index: Ref<number>;
+    readonly open: Ref<boolean>;
+    readonly options: FilePreviewOptions;
+    readonly handle: FilePreviewHandle;
+    /** Called by the provider once the closing animation ends. */
+    dispose: () => void;
+}
+/** Turns markdown into sanitized HTML for the markdown renderer's preview view. */
+export type FilePreviewMarkdownRenderer = (source: string) => MaybePromise<string>;
+export interface FilePreviewApi {
+    /**
+     * Opens one file or a gallery and returns right away with controls.
+     *
+     * @example
+     * const { $filePreview } = useNuxtApp()
+     * $filePreview.open({ src: document.url, name: document.fileName })
+     */
+    open: (input: FilePreviewInput | readonly FilePreviewInput[], options?: FilePreviewOptions) => FilePreviewHandle;
+    /** Closes the preview with this id, or the top-most one. Returns whether one was open. */
+    close: (id?: string) => boolean;
+    closeAll: () => void;
+    isOpen: (id?: string) => boolean;
+    /**
+     * Adds a renderer, checked before the built-in ones. Registering a built-in kind replaces it.
+     * Returns a function that removes it again.
+     */
+    register: (renderer: FilePreviewRendererDefinition) => () => void;
+    readonly instances: ComputedRef<readonly FilePreviewInstance[]>;
+    readonly renderers: ComputedRef<readonly FilePreviewRendererDefinition[]>;
+    /** Whether a `<UiFilePreviewProvider>` is mounted to render previews. */
+    readonly mounted: ComputedRef<boolean>;
+    /** Called by the provider. Returns the function it calls when it unmounts. */
+    attach: () => () => void;
+}

package/dist/runtime/file-preview/types/file.d.ts

@@ -0,0 +1,77 @@
+import type { MaybePromise } from '../../shared/types/utils.js';
+/** Text shown in the preview chrome. A getter keeps it translated when the language changes. */
+export type FilePreviewText = string | (() => string);
+/** Kinds the package renders out of the box. Custom renderers may add their own kind names. */
+export type FilePreviewBuiltInKind = 'image' | 'video' | 'audio' | 'pdf' | 'text' | 'csv' | 'markdown' | 'office' | 'archive' | 'other';
+export type FilePreviewKind = FilePreviewBuiltInKind | (string & {});
+/** A usable source: a URL (remote, `data:`, or `blob:`) or the bytes themselves. */
+export type FilePreviewSourceValue = string | Blob;
+/**
+ * Where the file comes from. A function runs only when the file is shown, so short-lived signed
+ * URLs are requested on demand; it runs again when the user presses Retry after an error.
+ */
+export type FilePreviewSource = FilePreviewSourceValue | (() => MaybePromise<FilePreviewSourceValue>);
+export interface FilePreviewDetail {
+    label: FilePreviewText;
+    value: FilePreviewText;
+}
+/** Extra header action, such as "Open in registry". */
+export interface FilePreviewAction {
+    label: FilePreviewText;
+    icon?: string;
+    /** Link target. External URLs open in a new tab. */
+    to?: string;
+    onSelect?: (file: FilePreviewFile) => MaybePromise<void>;
+}
+/** Caption or subtitle track for video previews. */
+export interface FilePreviewTrack {
+    src: string;
+    srcLang: string;
+    label: string;
+    kind?: TextTrackKind;
+    default?: boolean;
+}
+export interface FilePreviewFile {
+    src: FilePreviewSource;
+    /** Stable identity inside a gallery. Defaults to the file position. */
+    id?: string;
+    /** Display name. Defaults to `File.name`, then the last URL segment. */
+    name?: string;
+    /** MIME type. Wins over extension sniffing to pick the renderer. */
+    mime?: string;
+    /** Forces a renderer, custom kinds included. */
+    kind?: FilePreviewKind;
+    size?: number;
+    updatedAt?: string | number | Date;
+    /** Small image for the gallery strip. */
+    thumbnail?: string;
+    /** Video poster or audio cover. */
+    poster?: string;
+    /**
+     * Preview made by a server for a file browsers cannot render, such as a PDF for a DOCX or a JPEG
+     * for a HEIC photo. The preview shows the rendition and downloads keep the original.
+     */
+    rendition?: FilePreviewFile;
+    details?: readonly FilePreviewDetail[];
+    /**
+     * `false` hides the download action, a string downloads that URL instead, and a function replaces
+     * the download entirely. By default the resolved source is downloaded under the file name.
+     */
+    download?: boolean | string | ((file: FilePreviewFile) => MaybePromise<void>);
+    actions?: readonly FilePreviewAction[];
+    tracks?: readonly FilePreviewTrack[];
+}
+/** What `open()` accepts for each file: a URL, a `File` or `Blob`, or a full descriptor. */
+export type FilePreviewInput = FilePreviewSourceValue | FilePreviewFile;
+/** A file normalized once when the preview opens. Renderers receive it as `file`. */
+export interface FilePreviewItem {
+    key: string;
+    file: FilePreviewFile;
+    name: string;
+    mime: string | null;
+    extension: string | null;
+    size: number | null;
+    updatedAt: Date | null;
+    kind: FilePreviewKind;
+    rendition: FilePreviewItem | null;
+}

package/dist/runtime/file-preview/types/index.d.ts

@@ -0,0 +1,4 @@
+export type * from './api';
+export type * from './file';
+export type * from './renderer';
+export type * from './shell';