Upgrade from 0.2 to 1.0

Nuxt Photo 1.0 is a deliberate pre-1.0 hard cutover. It removes compatibility paths instead of carrying two ways to do the same job. Make these changes while upgrading from 0.2 to a 1.0 prerelease or stable 1.0 release.

Rename provider APIs

Rename the provider composable and shared defaults. There are no deprecated aliases.

- import { useLightboxProvider, LightboxDefaultsKey } from '@lupinum/nuxt-photo/app'
+ import { provideLightbox, PhotoDefaultsKey } from '@lupinum/nuxt-photo/app'

- const controller = useLightboxProvider(photos)
+ const controller = provideLightbox(photos)

useLightbox() remains the consumer composable and <LightboxProvider> remains the template provider.

Use the direct carousel props

Remove the options bag and slidesToScroll. Nuxt Photo now uses one slide per snap internally and exposes only the behavior it owns.

 <PhotoCarousel
   :photos="photos"
-  :options="{ loop: true, dragFree: false, slidesToScroll: 2 }"
+  loop
+  :drag-free="false"
 />

Carousel lightboxes are now opt-in. Add :lightbox="true" when a carousel should open the viewer. Use direction="rtl" when direction can change at runtime; otherwise the carousel inherits direction when it mounts.

Keep strict single photos

<Photo> always throws for invalid data. validation="drop" remains available only on collection components (PhotoAlbum, PhotoGroup, and PhotoCarousel), where the invalidPhotos event can make rejected input visible.

Known intrinsic width and height remain required. Nuxt Photo does not ship a browser-side dimension measurement helper; resolve dimensions in your CMS, upload pipeline, or build process.

Review image and localization behavior

• PhotoItem.placeholderSrc adds an optional low-quality preview. The preview resets when the resolved source changes and remains visible after load errors.
• PhotoAlbum.sizes accepts either a native HTML sizes string or the existing layout-aware object.
• Localize built-in labels with typed nuxtPhoto.labels module options or app.config.ts values. Indexed templates use {index} and slide status also uses {count}.
• provider: 'auto' quietly uses native images when @nuxt/image is absent. Explicit nuxt-image mode still reports a missing module.

Update programmatic control

Template refs on PhotoAlbum and PhotoGroup expose one LightboxHandle:

type LightboxHandle = {
  open(index?: number): Promise<void>
  openById(id: string): Promise<void>
  close(): Promise<void>
  readonly isOpen: boolean
}

Photo and PhotoCarousel intentionally do not expose controllers. When an album belongs to a group, its numeric indexes remain local to that album.

Treat lightbox capability as setup-time state

The lightbox prop decides whether a ready-made component creates a provider when it mounts. To add, remove, or replace that capability, remount the component with a new Vue key. Photo collections and transition options remain reactive.

Update advanced custom lightboxes

LightboxRoot now owns the transition layer. Remove the old public transition primitive:

The following before-and-after blocks are migration fragments, not complete components.

<LightboxRoot>
  <LightboxGhostImage class="my-transition-image" />
</LightboxRoot>

<LightboxRoot>
  <!-- Custom lightbox content -->
</LightboxRoot>

The viewport now owns media opacity. Remove the mediaOpacity slot binding and inline style:

<LightboxViewport v-slot="{ photos, viewportRef, mediaOpacity }">
  <div :ref="viewportRef" :style="{ opacity: mediaOpacity }">...</div>
</LightboxViewport>

<LightboxViewport v-slot="{ photos, viewportRef }">
  <div :ref="viewportRef">...</div>
</LightboxViewport>

Backdrop blur now accepts a complete CSS filter value:

.np-lightbox {
  --np-backdrop-filter: blur(16px);
}

Verify the migration

Search for removed names and old carousel configuration:

rg "useLightboxProvider|LightboxDefaults|slidesToScroll|PhotoCarousel.*options" .

Then run your app's Nuxt preparation, typecheck, build, and browser tests. Import only from @lupinum/nuxt-photo, @lupinum/nuxt-photo/app, or the documented Vue entry points; source-folder wildcard imports are not public.