origam 2.37.0 → 2.37.2

package/CHANGELOG.md

@@ -18,6 +18,25 @@ This project follows [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [2.37.2] - 2026-10-19
+
+### Fixed — `OrigamImg` sous SSR : écart d'hydratation `aspect-ratio`, et image montée côté client jamais chargée (#1192)
+
+- **Écart d'hydratation** : sans prop `aspect-ratio`, `useAspectRatio` prend le ratio de la fenêtre (`innerWidth / innerHeight`), une valeur inconnue du serveur. Il était appliqué dès le premier rendu client d'une instance hydratée, d'où un `Hydration style mismatch`. Une instance qui hydrate l'applique désormais après `onMounted`. Une instance montée côté client l'applique tout de suite, comme avant. Un `aspect-ratio` explicite est inchangé.
+- **Image montée côté client jamais chargée** : `v-intersect` était lié avec le tuple `withDirectives` comme valeur. La directive lisait `.handler` sur un tableau, si bien que l'intersection ne déclenchait jamais le chargement. L'`<img>` restait en `display:none` + `loading="lazy"`, que Chromium ne charge pas. La directive est désormais liée en `v-intersect.once="{ handler, options }"`, et l'`<img>` passe en `loading="eager"` dès que son chargement est demandé.
+- La même forme de liaison subsiste dans d'autres composants : suivi en #1205.
+
+## [2.37.1] - 2026-10-19
+
+### Fixed — `OrigamImg` / `OrigamResponsive` : prop `tag`, `<img>` visible en SSR, fondu en rendu client seul (#1182)
+
+Un `<origam-img>` placé dans un `<p>` (contenu prose) produisait un `<div>` invalide dans un paragraphe, que le parseur HTML expulse : DOM serveur et client divergeaient. Et l'`<img>` était servie en `display:none` jusqu'au `load` côté client, donc invisible tant que le JS n'avait pas tourné.
+
+- **Nouvelle prop `tag`** (défaut `'div'`) sur `OrigamResponsive` et `OrigamImg` (transmise au Responsive et aux conteneurs placeholder / error / gradient). `tag="span"` garde un DOM valide dans un `<p>`.
+- **`<img>` visible dans le HTML serveur** : elle n'est plus masquée avant le `load`.
+- **Fondu conservé uniquement au montage client** (navigation SPA, `v-if` après hydratation). Une image hydratée depuis le HTML serveur s'affiche sans fondu et sans clignotement.
+- ⚠️ Changement de rendu assumé : en rendu serveur puis hydratation, l'image n'apparaît plus en fondu.
+
 ## [2.37.0] - 2026-10-19
 
 ### Added — module Nuxt : options `locale` transmises à `createOrigam` (#1181)

package/dist/src/components/Carousel/OrigamCarouselItem.vue

@@ -76,6 +76,7 @@ const props = defineProps({
   id: { type: String, required: false },
   class: { type: [String, Array, Object], required: false },
   style: { type: [String, Array, Object, Boolean, null], required: false, skipCheck: true },
+  tag: { type: String, required: false },
   padding: { type: [Boolean, Number, String], required: false },
   paddingTop: { type: [Boolean, Number, String], required: false },
   paddingLeft: { type: [Boolean, Number, String], required: false },

package/dist/src/components/Img/OrigamImg.vue

@@ -1,7 +1,7 @@
 <template>
 	<origam-responsive
 			:id="id"
-			v-intersect="intersect"
+			v-intersect.once="intersect"
 			:aria-label="alt"
 			:class="imgClasses"
 			:role="alt ? 'img' : undefined"
@@ -10,11 +10,11 @@
 	>
 		<template #additional>
 			<origam-transition
+					:appear="fadesIn"
 					:transition="transition"
-					appear
 			>
 				<img
-						v-show="isLoaded"
+						v-show="isPictureShown"
 						ref="image"
 						:alt="alt"
 						:class="imgPictureClasses"
@@ -46,25 +46,28 @@
 					:transition="transition"
 					appear
 			>
-				<div
+				<component
+						:is="tag"
 						v-if="(isLoading || (isError && !slots.error)) && slots.placeholder"
 						class="origam-img__placeholder"
 				>
 					<slot name="placeholder"/>
-				</div>
+				</component>
 			</origam-transition>
 			<origam-transition
 					:transition="transition"
 					appear
 			>
-				<div
+				<component
+						:is="tag"
 						v-if="isError && slots.error"
 						class="origam-img__error"
 				>
 					<slot name="error"/>
-				</div>
+				</component>
 			</origam-transition>
-			<div
+			<component
+					:is="tag"
 					v-if="gradient"
 					:style="imgGradientStyles"
 					class="origam-img__gradient"
@@ -133,6 +136,7 @@ const props = defineProps({
   id: { type: String, required: false },
   class: { type: [String, Array, Object], required: false },
   style: { type: [String, Array, Object, Boolean, null], required: false, skipCheck: true },
+  tag: { type: String, required: false, default: "div" },
   padding: { type: [Boolean, Number, String], required: false },
   paddingTop: { type: [Boolean, Number, String], required: false },
   paddingLeft: { type: [Boolean, Number, String], required: false },
@@ -219,7 +223,7 @@ const normalisedSrc = computed(() => {
 const aspectRatio = computed(() => {
   return normalisedSrc.value.aspectRatio || naturalWidth.value / naturalHeight.value || 0;
 });
-const responsiveProps = computed(() => pick(props, ["aspectRatio", "contentClass", "height", "maxHeight", "maxWidth", "minHeight", "minWidth", "width", "class", "style"]));
+const responsiveProps = computed(() => pick(props, ["tag", "aspectRatio", "contentClass", "height", "maxHeight", "maxWidth", "minHeight", "minWidth", "width", "class", "style"]));
 watch(() => props.src, () => {
   init(state.value !== IMG_STATE.IDLE);
 });
@@ -323,11 +327,11 @@ const markBooted = (val) => {
 };
 stop = watch(aspectRatio, markBooted);
 markBooted(aspectRatio.value);
-const intersect = computed(() => [{
+const intersect = computed(() => ({
   handler: init,
   options: props.options
-}, null, ["once"]]);
-const nativeLoading = computed(() => props.eager ? "eager" : "lazy");
+}));
+const nativeLoading = computed(() => props.eager || state.value !== IMG_STATE.IDLE ? "eager" : "lazy");
 const isLoaded = computed(() => {
   return state.value === IMG_STATE.LOADED;
 });
@@ -337,6 +341,10 @@ const isLoading = computed(() => {
 const isError = computed(() => {
   return state.value === IMG_STATE.ERROR;
 });
+const fadesIn = IN_BROWSER && !vm.vnode.el;
+const isPictureShown = computed(() => {
+  return fadesIn ? isLoaded.value : !isError.value;
+});
 const hasContent = computed(() => {
   return slots.default;
 });

package/dist/src/components/Responsive/OrigamResponsive.vue

@@ -1,17 +1,19 @@
 <template>
-	<div
+	<component
+			:is="tag"
 			:id="id"
 			:class="responsiveClasses"
 			:style="responsiveStyles"
 	>
 		<slot name="additional"/>
-		<div
+		<component
+				:is="tag"
 				v-if="slots.default"
 				:class="responsiveContentClasses"
 		>
 			<slot name="default"/>
-		</div>
-	</div>
+		</component>
+	</component>
 </template>
 
 <script lang="ts" setup>
@@ -36,6 +38,7 @@ const props = defineProps({
   id: { type: String, required: false },
   class: { type: [String, Array, Object], required: false },
   style: { type: [String, Array, Object, Boolean, null], required: false, skipCheck: true },
+  tag: { type: String, required: false, default: "div" },
   padding: { type: [Boolean, Number, String], required: false },
   paddingTop: { type: [Boolean, Number, String], required: false },
   paddingLeft: { type: [Boolean, Number, String], required: false },

package/dist/src/composables/Responsive/aspect.composable.cjs

@@ -8,6 +8,11 @@ var _vue = require("vue");
 var _commons = require("../../consts/Commons/commons.const.cjs");
 const isUsableRatio = value => Number.isFinite(value) && value > 0;
 function useAspectRatio(props) {
+  const isHydrating = _commons.IN_BROWSER && !!(0, _vue.getCurrentInstance)()?.vnode.el;
+  const isViewportReady = (0, _vue.shallowRef)(!isHydrating);
+  if (isHydrating) (0, _vue.onMounted)(() => {
+    isViewportReady.value = true;
+  });
   const ratio = (0, _vue.computed)(() => {
     if (props.aspectRatio) {
       const raw = String(props.aspectRatio).trim();
@@ -21,7 +26,7 @@ function useAspectRatio(props) {
       const value = Number(raw);
       return isUsableRatio(value) ? String(value) : void 0;
     }
-    if (!_commons.IN_BROWSER) return void 0;
+    if (!_commons.IN_BROWSER || !isViewportReady.value) return void 0;
     const viewport = window.innerWidth / window.innerHeight;
     return isUsableRatio(viewport) ? String(viewport) : void 0;
   });

package/dist/src/composables/Responsive/aspect.composable.d.ts

@@ -40,6 +40,19 @@
  * runtime, never a design-time default a theme would override, so there is
  * nothing for the token pipeline to carry.
  *
+ * Hydration (#1192)
+ * ─────────────────
+ * The viewport fallback is a CLIENT-ONLY value: the server cannot emit it.
+ * Applied from the first render of an instance that is being hydrated, it
+ * made the client's first render differ from the server HTML
+ * (`style="width:120px;"` vs `style="aspect-ratio:1.77…;width:120px;"`),
+ * i.e. a "Hydration style mismatch" that Vue does not rectify in
+ * production. So an instance hydrating server HTML (`vnode.el` already set
+ * when `setup()` runs) holds the fallback back until `onMounted`; the style
+ * is then patched by an ordinary reactive update. An instance created on
+ * the client (no server HTML to match) applies it at once, as before.
+ * An explicit `aspectRatio` is deterministic and is emitted by both sides.
+ *
  * Guarding the value
  * ──────────────────
  * The returned ratio rejects NaN, 0, negatives and Infinity. Any of them

package/dist/src/composables/Responsive/aspect.composable.js

@@ -1,7 +1,12 @@
-import { computed } from "vue";
+import { computed, getCurrentInstance, onMounted, shallowRef } from "vue";
 import { IN_BROWSER } from "../../consts/Commons/commons.const.js";
 const isUsableRatio = (value) => Number.isFinite(value) && value > 0;
 export function useAspectRatio(props) {
+  const isHydrating = IN_BROWSER && !!getCurrentInstance()?.vnode.el;
+  const isViewportReady = shallowRef(!isHydrating);
+  if (isHydrating) onMounted(() => {
+    isViewportReady.value = true;
+  });
   const ratio = computed(() => {
     if (props.aspectRatio) {
       const raw = String(props.aspectRatio).trim();
@@ -15,7 +20,7 @@ export function useAspectRatio(props) {
       const value = Number(raw);
       return isUsableRatio(value) ? String(value) : void 0;
     }
-    if (!IN_BROWSER) return void 0;
+    if (!IN_BROWSER || !isViewportReady.value) return void 0;
     const viewport = window.innerWidth / window.innerHeight;
     return isUsableRatio(viewport) ? String(viewport) : void 0;
   });

package/dist/src/interfaces/Responsive/responsive.interface.d.ts

@@ -1,10 +1,10 @@
 import type { IBorderProps } from '../Commons/border.interface';
-import type { ICommonsComponentProps } from '../Commons/commons.interface';
+import type { ICommonsComponentProps, ITagProps } from '../Commons/commons.interface';
 import type { IDimensionProps } from '../Commons/dimension.interface';
 import type { IMarginProps } from '../Commons/margin.interface';
 import type { IPaddingProps } from '../Commons/padding.interface';
 import type { IRoundedProps } from '../Commons/rounded.interface';
-export interface IResponsiveProps extends IDimensionProps, ICommonsComponentProps, IPaddingProps, IMarginProps, IBorderProps, IRoundedProps {
+export interface IResponsiveProps extends IDimensionProps, ICommonsComponentProps, ITagProps, IPaddingProps, IMarginProps, IBorderProps, IRoundedProps {
     aspectRatio?: string | number;
     contentClass?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "origam",
-  "version": "2.37.0",
+  "version": "2.37.2",
   "type": "module",
   "description": "origam — a Vue 3 design system with multi-theme design tokens, CSS-first components and TypeScript types.",
   "keywords": [