feat(createImage/Image): create new composable and component

apps/docs/src/examples/components/aspect-ratio/ResponsiveImage.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+  import { AspectRatio, Image } from '@vuetify/v0'
+
+  defineProps<{
+    src: string
+    alt: string
+    ratio: number | string
+  }>()
+</script>
+
+<template>
+  <AspectRatio
+    class="w-full bg-surface-tint rounded overflow-hidden relative"
+    :ratio
+  >
+    <Image.Root :src>
+      <Image.Img
+        :alt
+        class="w-full h-full object-cover"
+      />
+
+      <Image.Placeholder class="absolute inset-0 flex items-center justify-center">
+        <div class="w-full h-full bg-surface-tint animate-pulse" />
+      </Image.Placeholder>
+
+      <Image.Fallback class="absolute inset-0 flex items-center justify-center bg-error-container text-on-error-container text-sm">
+        Failed to load
+      </Image.Fallback>
+    </Image.Root>
+  </AspectRatio>
+</template>

apps/docs/src/examples/components/aspect-ratio/basic.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+  import { AspectRatio } from '@vuetify/v0'
+  import { shallowRef } from 'vue'
+
+  const ratios = [
+    { label: '1 / 1', value: '1 / 1' },
+    { label: '4 / 3', value: '4 / 3' },
+    { label: '16 / 9', value: '16 / 9' },
+    { label: '21 / 9', value: '21 / 9' },
+  ]
+
+  const active = shallowRef('16 / 9')
+</script>
+
+<template>
+  <div class="space-y-4">
+    <div class="flex gap-2">
+      <button
+        v-for="r in ratios"
+        :key="r.value"
+        class="px-3 py-1 border rounded text-sm"
+        :class="active === r.value ? 'bg-primary text-on-primary' : 'bg-surface'"
+        @click="active = r.value"
+      >
+        {{ r.label }}
+      </button>
+    </div>
+
+    <AspectRatio
+      class="w-full bg-surface-tint rounded overflow-hidden"
+      :ratio="active"
+    >
+      <div class="w-full h-full flex items-center justify-center text-on-surface-variant text-sm">
+        {{ active }}
+      </div>
+    </AspectRatio>
+  </div>
+</template>

apps/docs/src/examples/components/aspect-ratio/responsive.vue

@@ -0,0 +1,18 @@
+<script setup lang="ts">
+  import ResponsiveImage from './ResponsiveImage.vue'
+</script>
+
+<template>
+  <div class="grid grid-cols-1 sm:grid-cols-2 gap-4">
+    <ResponsiveImage
+      alt="Landscape photo"
+      :ratio="16 / 9"
+      src="https://picsum.photos/seed/ar-1/800/450"
+    />
+    <ResponsiveImage
+      alt="Square photo"
+      :ratio="1"
+      src="https://picsum.photos/seed/ar-2/400/400"
+    />
+  </div>
+</template>

apps/docs/src/examples/components/image/BlurUpImage.vue

@@ -0,0 +1,34 @@
+<script setup lang="ts">
+  import { Image } from '@vuetify/v0'
+
+  defineProps<{
+    src: string
+    placeholder: string
+    alt: string
+  }>()
+</script>
+
+<template>
+  <Image.Root
+    class="w-full aspect-4/3 bg-surface-tint rounded overflow-hidden relative"
+    lazy
+    root-margin="200px"
+    :src
+  >
+    <Image.Img
+      :alt
+      class="w-full h-full object-cover opacity-0 transition-opacity duration-500 data-[state=loaded]:opacity-100"
+      height="300"
+      width="400"
+    />
+
+    <Image.Placeholder class="absolute inset-0">
+      <img
+        :alt
+        aria-hidden="true"
+        class="w-full h-full object-cover scale-105 blur-xl"
+        :src="placeholder"
+      >
+    </Image.Placeholder>
+  </Image.Root>
+</template>

apps/docs/src/examples/components/image/PictureImage.vue

@@ -0,0 +1,49 @@
+<script setup lang="ts">
+  import { Image } from '@vuetify/v0'
+
+  defineProps<{
+    src: string
+    sources: { srcset: string, type: string }[]
+    alt: string
+    width: number
+    height: number
+  }>()
+</script>
+
+<template>
+  <Image.Root
+    renderless
+    :src
+  >
+    <picture class="block w-full aspect-4/3 bg-surface-tint rounded overflow-hidden relative">
+      <source
+        v-for="source in sources"
+        :key="source.type"
+        :srcset="source.srcset"
+        :type="source.type"
+      >
+
+      <Image.Img
+        v-slot="{ attrs }"
+        :alt
+        :height
+        renderless
+        :width
+      >
+        <img
+          v-bind="attrs"
+          :alt="attrs.alt"
+          class="w-full h-full object-cover"
+        >
+      </Image.Img>
+
+      <Image.Placeholder class="absolute inset-0 flex items-center justify-center bg-surface-tint">
+        <span class="text-on-surface-variant text-sm">Loading...</span>
+      </Image.Placeholder>
+
+      <Image.Fallback class="absolute inset-0 flex items-center justify-center bg-error-container text-on-error-container text-sm">
+        Image failed to load
+      </Image.Fallback>
+    </picture>
+  </Image.Root>
+</template>

apps/docs/src/examples/components/image/basic.vue

@@ -0,0 +1,28 @@
+<script setup lang="ts">
+  import { Image } from '@vuetify/v0'
+</script>
+
+<template>
+  <div class="flex items-center justify-center">
+    <Image.Root
+      class="w-100 h-75 bg-surface-tint rounded overflow-hidden relative"
+      src="https://picsum.photos/seed/v0-image/400/300"
+    >
+      <Image.Img
+        alt="Random photo"
+        class="w-full h-full object-cover"
+        height="300"
+        loading="lazy"
+        width="400"
+      />
+
+      <Image.Placeholder class="absolute inset-0 flex items-center justify-center">
+        <div class="w-full h-full bg-surface-tint animate-pulse" />
+      </Image.Placeholder>
+
+      <Image.Fallback class="absolute inset-0 flex items-center justify-center bg-error-container text-on-error-container text-sm">
+        Image failed to load
+      </Image.Fallback>
+    </Image.Root>
+  </div>
+</template>

apps/docs/src/examples/components/image/observer.vue

@@ -0,0 +1,43 @@
+<script setup lang="ts">
+  import BlurUpImage from './BlurUpImage.vue'
+
+  const photos = [
+    {
+      id: 1,
+      src: 'https://picsum.photos/seed/blur-1/400/300',
+      placeholder: 'https://picsum.photos/seed/blur-1/20/15',
+      alt: 'Photo 1',
+    },
+    {
+      id: 2,
+      src: 'https://picsum.photos/seed/blur-2/400/300',
+      placeholder: 'https://picsum.photos/seed/blur-2/20/15',
+      alt: 'Photo 2',
+    },
+    {
+      id: 3,
+      src: 'https://picsum.photos/seed/blur-3/400/300',
+      placeholder: 'https://picsum.photos/seed/blur-3/20/15',
+      alt: 'Photo 3',
+    },
+  ]
+</script>
+
+<template>
+  <div class="h-100 overflow-auto border border-divider rounded p-4">
+    <p class="text-sm text-on-surface-variant mb-4">
+      A low-quality placeholder shows first; the full image fades in once it
+      loads. Scroll to trigger the next image.
+    </p>
+
+    <div class="flex flex-col gap-100">
+      <BlurUpImage
+        v-for="photo in photos"
+        :key="photo.id"
+        :alt="photo.alt"
+        :placeholder="photo.placeholder"
+        :src="photo.src"
+      />
+    </div>
+  </div>
+</template>

apps/docs/src/examples/components/image/picture.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+  import PictureImage from './PictureImage.vue'
+</script>
+
+<template>
+  <PictureImage
+    alt="Format-negotiated photo"
+    :height="300"
+    :sources="[
+      { srcset: 'https://picsum.photos/seed/picture/400/300.webp', type: 'image/webp' },
+    ]"
+    src="https://picsum.photos/seed/picture/400/300"
+    :width="400"
+  />
+</template>

apps/docs/src/examples/composables/use-image/LazyImage.vue

@@ -0,0 +1,33 @@
+<script setup lang="ts">
+  import { toRef } from 'vue'
+  import { useLazyImage } from './useLazyImage'
+
+  const props = defineProps<{
+    src: string
+    alt: string
+  }>()
+
+  const { target, source, isLoaded, status, onLoad, onError } = useLazyImage(
+    toRef(() => props.src),
+  )
+</script>
+
+<template>
+  <div ref="target" class="w-full aspect-4/3 bg-surface-tint rounded overflow-hidden relative">
+    <img
+      v-show="isLoaded"
+      :alt
+      class="w-full h-full object-cover"
+      :src="source"
+      @error="onError"
+      @load="onLoad"
+    >
+
+    <span
+      v-if="!isLoaded"
+      class="absolute inset-0 flex items-center justify-center text-on-surface-variant text-sm"
+    >
+      {{ status }}
+    </span>
+  </div>
+</template>

apps/docs/src/examples/composables/use-image/RetryableImage.vue

@@ -0,0 +1,68 @@
+<script setup lang="ts">
+  import { useImage } from '@vuetify/v0'
+  import { mdiImageBrokenVariant } from '@mdi/js'
+  import { shallowRef, toRef } from 'vue'
+
+  const props = defineProps<{
+    src: string
+    alt: string
+  }>()
+
+  const BROKEN = 'https://invalid.example/missing.jpg'
+  const attempts = shallowRef(0)
+  const currentSrc = shallowRef(BROKEN)
+
+  const { source, isLoaded, isError, onLoad, onError, retry } = useImage({
+    src: toRef(() => currentSrc.value),
+  })
+
+  function onRetry () {
+    attempts.value++
+    // Simulate a flaky network: each retry has a 25% chance of succeeding.
+    // On success, swap the broken URL for the real one — the src change
+    // triggers a fresh fetch. Otherwise call retry() to re-attempt the
+    // existing (broken) URL.
+    if (Math.random() < 0.25) {
+      currentSrc.value = props.src
+    } else {
+      retry()
+    }
+  }
+</script>
+
+<template>
+  <div class="w-full aspect-4/3 bg-surface-tint rounded overflow-hidden relative flex flex-col items-center justify-center gap-2">
+    <img
+      v-show="isLoaded"
+      :alt
+      class="w-full h-full object-cover"
+      :src="source"
+      @error="onError"
+      @load="onLoad"
+    >
+
+    <template v-if="isError">
+      <svg
+        aria-label="Image failed to load"
+        class="size-24 text-on-surface-variant"
+        role="img"
+        viewBox="0 0 24 24"
+      >
+        <path :d="mdiImageBrokenVariant" fill="currentColor" />
+      </svg>
+      <span v-if="attempts > 0" class="text-xs text-on-surface-variant">
+        Attempt {{ attempts + 1 }}
+      </span>
+      <button
+        class="px-3 py-1 bg-primary text-on-primary rounded text-sm"
+        @click="onRetry"
+      >
+        Retry
+      </button>
+    </template>
+
+    <span v-else-if="!isLoaded" class="text-on-surface-variant text-sm">
+      Loading...
+    </span>
+  </div>
+</template>