@12-apps/ui 6.39.6 → 6.39.8

package/dist/{chunk-JDFTIK4L.js → chunk-PELRSZFU.js}

@@ -1,6 +1,6 @@
 import {
   firstGhostSuggestion
-} from "./chunk-XBHQT4BQ.js";
+} from "./chunk-JXS56EW5.js";
 
 // src/components/form/Autocomplete/Autocomplete.keys.ts
 function canAcceptGhost(ctx) {
@@ -86,4 +86,4 @@ function handleAutocompleteKey(event, composition, ctx) {
 export {
   handleAutocompleteKey
 };
-//# sourceMappingURL=chunk-JDFTIK4L.js.map
+//# sourceMappingURL=chunk-PELRSZFU.js.map

package/dist/data-display/LazyImage.js

@@ -1,8 +1,8 @@
 import "../chunk-5ZFO7ROE.js";
 import {
   LazyImage
-} from "../chunk-LW2LQHIM.js";
-import "../chunk-HCT5ELST.js";
+} from "../chunk-BVF2BSWV.js";
+import "../chunk-GMUYCN33.js";
 import "../chunk-724ZONOL.js";
 import "../chunk-BEGTLELZ.js";
 import "../chunk-E2QIKJX2.js";

package/dist/form/Autocomplete.js

@@ -2,11 +2,11 @@ import "../chunk-2LXHUGYB.js";
 import {
   Autocomplete,
   Autocomplete_default
-} from "../chunk-PH36XEB3.js";
-import "../chunk-362OGE5J.js";
-import "../chunk-BN742L2M.js";
-import "../chunk-JDFTIK4L.js";
-import "../chunk-XBHQT4BQ.js";
+} from "../chunk-DQZCQV2C.js";
+import "../chunk-HBRKA67N.js";
+import "../chunk-H6AWKLOV.js";
+import "../chunk-PELRSZFU.js";
+import "../chunk-JXS56EW5.js";
 import "../chunk-CGO452DC.js";
 import "../chunk-GDN2LUTZ.js";
 import "../chunk-7FDU3FIN.js";

package/dist/types/components/data-display/LazyImage/LazyImage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LazyImage.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/LazyImage/LazyImage.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAoMxD;;;GAGG;AACH,eAAO,MAAM,SAAS,4CAoEpB,CAAC"}
+{"version":3,"file":"LazyImage.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/LazyImage/LazyImage.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAuNxD;;;GAGG;AACH,eAAO,MAAM,SAAS,4CAsEpB,CAAC"}

package/dist/types/components/data-display/LazyImage/LazyImage.hooks.d.ts

@@ -6,7 +6,8 @@ export declare const resolveLazyImageProps: (props: LazyImageProps) => ResolvedL
 export declare const imgPassThrough: (props: ResolvedLazyImageProps) => Record<string, unknown>;
 /**
  * Owns whether the real image has been requested yet and how it went: the
- * observer above, the load/error handlers, and the retry timer.
+ * observer above, the load/error handlers, the retry timer, and how long the
+ * placeholder stays up.
  */
 export declare const useLazyImage: (props: ResolvedLazyImageProps) => {
     state: LazyImageState;
@@ -14,8 +15,10 @@ export declare const useLazyImage: (props: ResolvedLazyImageProps) => {
     effectiveLoadingState: "placeholder" | "none" | "spinner" | "skeleton";
     handleImageLoad: (event: React.SyntheticEvent<HTMLImageElement>) => void;
     handleImageError: (event: React.SyntheticEvent<HTMLImageElement>) => void;
+    handlePlaceholderError: () => void;
     showImage: boolean;
     showLoading: boolean;
+    showPlaceholder: boolean;
 };
 export {};
 //# sourceMappingURL=LazyImage.hooks.d.ts.map

package/dist/types/components/data-display/LazyImage/LazyImage.hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LazyImage.hooks.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/LazyImage/LazyImage.hooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAmD,MAAM,OAAO,CAAC;AAIxE,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExE,KAAK,sBAAsB,GACvB,QAAQ,GACR,cAAc,GACd,WAAW,GACX,gBAAgB,GAChB,MAAM,GACN,WAAW,GACX,QAAQ,GACR,gBAAgB,GAChB,cAAc,GACd,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,eAAe,GACf,cAAc,GACd,IAAI,GACJ,MAAM,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,cAAc,GACjD,QAAQ,CAAC,IAAI,CAAC,cAAc,EAAE,sBAAsB,CAAC,CAAC,CAAC;AA4BzD,eAAO,MAAM,qBAAqB,GAAI,OAAO,cAAc,KAAG,sBACkB,CAAC;AAajF,eAAO,MAAM,cAAc,GAAI,OAAO,sBAAsB,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CACH,CAAC;AAgEnF;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,sBAAsB;;;;6BAkC9C,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC;8BAQtC,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC;;;CA4BjD,CAAC"}
+{"version":3,"file":"LazyImage.hooks.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/LazyImage/LazyImage.hooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAmD,MAAM,OAAO,CAAC;AAIxE,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExE,KAAK,sBAAsB,GACvB,QAAQ,GACR,cAAc,GACd,WAAW,GACX,gBAAgB,GAChB,MAAM,GACN,WAAW,GACX,QAAQ,GACR,gBAAgB,GAChB,cAAc,GACd,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,eAAe,GACf,cAAc,GACd,IAAI,GACJ,MAAM,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,cAAc,GACjD,QAAQ,CAAC,IAAI,CAAC,cAAc,EAAE,sBAAsB,CAAC,CAAC,CAAC;AA4BzD,eAAO,MAAM,qBAAqB,GAAI,OAAO,cAAc,KAAG,sBACkB,CAAC;AAajF,eAAO,MAAM,cAAc,GAAI,OAAO,sBAAsB,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CACH,CAAC;AA0InF;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,sBAAsB;;;;6BAgB9C,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC;8BAStC,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC;;;;;CAgCjD,CAAC"}

package/dist/types/components/data-display/LazyImage/LazyImage.types.d.ts

@@ -28,7 +28,17 @@ export interface LazyImageProps extends React.ImgHTMLAttributes<HTMLImageElement
      */
     height?: number | string;
     /**
-     * Placeholder image URL to show while loading
+     * A low-resolution image URL shown while the real image loads. Only
+     * `loadingState="placeholder"` draws it; under any other loading state it is
+     * ignored. It shows from mount, lazy or not, until the real image has loaded
+     * and faded in (at once when `fadeIn` is off) or has finally failed. The real
+     * image is drawn over it and cropped by `objectFit`, so the box takes the
+     * placeholder's shape until the fade ends. A placeholder that fails to load is
+     * dropped, as if none were set, and is never reported to `onError`; neither
+     * does its load reach `onLoad`.
+     *
+     * Give LazyImage a `width` (or `"100%"`) in placeholder mode: with none, the
+     * placeholder shows at its own, usually tiny, size.
      */
     placeholder?: string;
     /**
@@ -39,8 +49,12 @@ export interface LazyImageProps extends React.ImgHTMLAttributes<HTMLImageElement
      * Loading state type
      * - 'skeleton': Shows a skeleton loader
      * - 'spinner': Shows a loading spinner
-     * - 'placeholder': Shows placeholder image
+     * - 'placeholder': Shows the `placeholder` image, in the box's flow, until the
+     *   real image has faded in over it; nothing when no `placeholder` is set.
+     *   Set a `width` (or `"100%"`), or the placeholder shows at its own size.
      * - 'none': No loading indicator
+     *
+     * `placeholder` applies only to 'placeholder'.
      * @default 'skeleton'
      */
     loadingState?: LazyImageLoadingState;
@@ -151,7 +165,9 @@ export interface LazyImageProps extends React.ImgHTMLAttributes<HTMLImageElement
      * Inline CSS for the `<img>` (its `style`), not MUI's `sx`: theme values and
      * nested selectors such as `'&:hover'` do not apply. The image's box clips
      * anything painted outside the image, such as a shadow, so put those on a
-     * wrapping element.
+     * wrapping element. While a placeholder is up (`loadingState="placeholder"`),
+     * the image is laid over it, so its `position`, `inset`, `width` and `height`
+     * are fixed until the placeholder retires; the rest applies throughout.
      */
     sx?: React.CSSProperties;
     /**

package/dist/types/components/data-display/LazyImage/LazyImage.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LazyImage.types.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/LazyImage/LazyImage.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"LazyImage.types.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/LazyImage/LazyImage.types.ts"],"names":[],"mappings":"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"}

package/dist/types/components/form/Autocomplete/Autocomplete.helpers.d.ts

@@ -19,9 +19,22 @@ export declare function filterSuggestions<T>(suggestions: T[], query: string, ma
  * Shared by the ghost-text effect and ArrowRight completion.
  */
 export declare function firstGhostSuggestion<T>(list: T[], inputValue: string, getLabel: (item: T) => string, getSuggestionType: (item: T) => SuggestionType | undefined): T | undefined;
+/** One run of a highlighted label: plain text, or text the query matched. */
+export interface HighlightSegment {
+    text: string;
+    match: boolean;
+}
 /**
- * Wrap query matches in `<mark>` for the default suggestion renderer. Skipped for
- * fuzzy mode (non-contiguous matches) and empty queries. Returns HTML.
+ * Split `label` into the runs the query matches and the runs between them, in
+ * order, for the default suggestion renderer to wrap the matches in `<mark>`.
+ * Every occurrence of the query matches, case-insensitively and literally (regex
+ * metacharacters are escaped). Fuzzy mode (non-contiguous matches) and an empty
+ * query yield the whole label as one unmatched run.
+ *
+ * Returns TEXT, never markup: a label is caller data (in a consumer, a user's
+ * own display name), so the renderer must hand each run to React as a text
+ * child, which escapes it. Building an HTML string here and injecting it is how
+ * a label of `<img onerror=…>` once ran script in the host page.
  */
-export declare function highlightLabel(label: string, query: string, matchMode: MatchMode): string;
+export declare function highlightLabel(label: string, query: string, matchMode: MatchMode): HighlightSegment[];
 //# sourceMappingURL=Autocomplete.helpers.d.ts.map

package/dist/types/components/form/Autocomplete/Autocomplete.helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Autocomplete.helpers.d.ts","sourceRoot":"","sources":["../../../../../src/components/form/Autocomplete/Autocomplete.helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,gCAAgC;AAChC,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,CAAC;AAE5D,mFAAmF;AACnF,eAAO,MAAM,aAAa,GAAI,CAAC,EAAG,MAAM,CAAC,KAAG,MAO3C,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,eAAe,GAAI,CAAC,EAAG,MAAM,CAAC,KAAG,MAO7C,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,GAAI,CAAC,EAAG,MAAM,CAAC,KAAG,cAAc,GAAG,SAMvE,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,aAAa,GAAI,CAAC,EAAG,MAAM,CAAC,KAAG,MAAM,GAAG,SAMpD,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,IAI7C,CAAC;AAwBF,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,WAAW,EAAE,CAAC,EAAE,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAC5B,CAAC,EAAE,CAGL;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,IAAI,EAAE,CAAC,EAAE,EACT,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,EAC7B,iBAAiB,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,cAAc,GAAG,SAAS,GACzD,CAAC,GAAG,SAAS,CAMf;AAOD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,MAAM,CAIzF"}
+{"version":3,"file":"Autocomplete.helpers.d.ts","sourceRoot":"","sources":["../../../../../src/components/form/Autocomplete/Autocomplete.helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,gCAAgC;AAChC,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,CAAC;AAE5D,mFAAmF;AACnF,eAAO,MAAM,aAAa,GAAI,CAAC,EAAG,MAAM,CAAC,KAAG,MAO3C,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,eAAe,GAAI,CAAC,EAAG,MAAM,CAAC,KAAG,MAO7C,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,GAAI,CAAC,EAAG,MAAM,CAAC,KAAG,cAAc,GAAG,SAMvE,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,aAAa,GAAI,CAAC,EAAG,MAAM,CAAC,KAAG,MAAM,GAAG,SAMpD,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,IAI7C,CAAC;AAwBF,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,WAAW,EAAE,CAAC,EAAE,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAC5B,CAAC,EAAE,CAGL;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,IAAI,EAAE,CAAC,EAAE,EACT,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,EAC7B,iBAAiB,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,cAAc,GAAG,SAAS,GACzD,CAAC,GAAG,SAAS,CAMf;AAOD,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,gBAAgB,EAAE,CAQrG"}

package/dist/types/components/form/Autocomplete/Autocomplete.parts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Autocomplete.parts.d.ts","sourceRoot":"","sources":["../../../../../src/components/form/Autocomplete/Autocomplete.parts.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"Autocomplete.parts.d.ts","sourceRoot":"","sources":["../../../../../src/components/form/Autocomplete/Autocomplete.parts.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.39.6",
+  "version": "6.39.8",
   "license": "MIT",
   "packageManager": "pnpm@10.34.5",
   "type": "module",

package/src/components/data-display/LazyImage/LazyImage.hooks.ts

@@ -115,8 +115,8 @@ const useVisibility = (
   }, [lazy, src, rootMargin, threshold, isVisible, onLoadStart, onVisible, containerRef]);
 };
 
-/** A pending retry has to be cancelled on unmount, or it sets state on a dead component. */
-const useRetryTimeout = () => {
+/** A pending timer has to be cancelled on unmount, or it sets state on a dead component. */
+const useTimeoutRef = () => {
   const ref = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
 
   useEffect(
@@ -132,25 +132,59 @@ const useRetryTimeout = () => {
 };
 
 /**
- * Owns whether the real image has been requested yet and how it went: the
- * observer above, the load/error handlers, and the retry timer.
+ * Whether the placeholder image is up. It is a loading state: only
+ * `loadingState="placeholder"` with a `placeholder` set draws it, from mount
+ * until the real image settles — its `load` plus the fade, or its final error.
+ * A placeholder that fails to load retires at once, as if none were set.
  */
-export const useLazyImage = (props: ResolvedLazyImageProps) => {
-  const { src, placeholder, lazy, loadingState, showSpinner } = props;
-  const { onLoad, onError, retryOnError, maxRetries, retryDelay } = props;
+const usePlaceholderPhase = (
+  props: ResolvedLazyImageProps,
+  loadingState: NonNullable<LazyImageProps['loadingState']>,
+) => {
+  const { placeholder, fadeIn, fadeInDuration } = props;
+  // Only this mode draws a placeholder. Otherwise the real image settling
+  // retires the phase at once — batched into the load's own render, with no
+  // timer — so a placeholder switched on afterwards never covers a loaded image.
+  const active = loadingState === 'placeholder' && Boolean(placeholder);
+  const [retired, setRetired] = useState(false);
+  const fadeTimeoutRef = useTimeoutRef();
 
-  const containerRef = useRef<HTMLDivElement>(null);
-  const retryTimeoutRef = useRetryTimeout();
+  const retire = useCallback(() => setRetired(true), []);
 
-  // Handle deprecated showSpinner prop
-  const effectiveLoadingState = showSpinner ? 'spinner' : loadingState;
+  // The real image fades in over the placeholder, so it goes when the fade ends.
+  const retireAfterFade = useCallback(() => {
+    if (!active || !fadeIn) {
+      setRetired(true);
+      return;
+    }
+    clearTimeout(fadeTimeoutRef.current);
+    fadeTimeoutRef.current = setTimeout(() => setRetired(true), fadeInDuration);
+  }, [active, fadeIn, fadeInDuration, fadeTimeoutRef]);
+
+  return {
+    showPlaceholder: active && !retired,
+    retirePlaceholder: retire,
+    retirePlaceholderAfterFade: retireAfterFade,
+  };
+};
 
+/**
+ * The real image's state, and when it is requested: at once when not lazy,
+ * else the first time the container nears the viewport. The main <img> only
+ * ever carries the real src — a placeholder is drawn by its own element, so its
+ * load and error are never the image's.
+ */
+const useImageSource = (
+  props: ResolvedLazyImageProps,
+  containerRef: React.RefObject<HTMLDivElement | null>,
+) => {
+  const { src, lazy } = props;
   const [state, setState] = useState<LazyImageState>({
     isLoading: true,
     hasError: false,
     isVisible: !lazy, // If not lazy, load immediately
     retryCount: 0,
-    currentSrc: lazy ? placeholder || null : src,
+    currentSrc: lazy ? null : src,
   });
 
   const markVisible = useCallback(
@@ -168,18 +202,43 @@ export const useLazyImage = (props: ResolvedLazyImageProps) => {
     setState((prev) => ({ ...prev, currentSrc: src, isLoading: true, hasError: false }));
   }, [state.isVisible, src, state.currentSrc]);
 
+  return [state, setState] as const;
+};
+
+/**
+ * Owns whether the real image has been requested yet and how it went: the
+ * observer above, the load/error handlers, the retry timer, and how long the
+ * placeholder stays up.
+ */
+export const useLazyImage = (props: ResolvedLazyImageProps) => {
+  const { src, loadingState, showSpinner } = props;
+  const { onLoad, onError, retryOnError, maxRetries, retryDelay } = props;
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const retryTimeoutRef = useTimeoutRef();
+  const [state, setState] = useImageSource(props, containerRef);
+
+  // Handle deprecated showSpinner prop
+  const effectiveLoadingState = showSpinner ? 'spinner' : loadingState;
+  const { showPlaceholder, retirePlaceholder, retirePlaceholderAfterFade } = usePlaceholderPhase(
+    props,
+    effectiveLoadingState,
+  );
+
   const handleImageLoad = useCallback(
     (event: React.SyntheticEvent<HTMLImageElement>) => {
       setState((prev) => ({ ...prev, isLoading: false, hasError: false, retryCount: 0 }));
+      retirePlaceholderAfterFade();
       onLoad?.(event);
     },
-    [onLoad],
+    [onLoad, retirePlaceholderAfterFade],
   );
 
   const handleImageError = useCallback(
     (event: React.SyntheticEvent<HTMLImageElement>) => {
       if (!retryOnError || state.retryCount >= maxRetries) {
         setState((prev) => ({ ...prev, isLoading: false, hasError: true }));
+        retirePlaceholder();
         onError?.(event);
         return;
       }
@@ -192,7 +251,7 @@ export const useLazyImage = (props: ResolvedLazyImageProps) => {
         }));
       }, retryDelay);
     },
-    [onError, retryOnError, state.retryCount, maxRetries, retryDelay, src],
+    [onError, retryOnError, state.retryCount, maxRetries, retryDelay, src, retirePlaceholder],
   );
 
   return {
@@ -201,8 +260,11 @@ export const useLazyImage = (props: ResolvedLazyImageProps) => {
     effectiveLoadingState,
     handleImageLoad,
     handleImageError,
+    handlePlaceholderError: retirePlaceholder,
     showImage: Boolean(state.currentSrc) && !state.hasError,
-    showLoading:
-      state.isLoading && (!state.currentSrc || effectiveLoadingState !== 'placeholder'),
+    // In placeholder mode the placeholder outlasts `isLoading`: it stays under
+    // the real image until the fade has ended.
+    showLoading: effectiveLoadingState === 'placeholder' ? showPlaceholder : state.isLoading,
+    showPlaceholder,
   };
 };

package/src/components/data-display/LazyImage/LazyImage.md

@@ -43,6 +43,24 @@ function App() {
 />
 ```
 
+The placeholder is a loading state, and only `loadingState="placeholder"` draws
+it — under `skeleton`, `spinner` or `none` the `placeholder` prop is ignored.
+
+- It shows from mount, lazy or not, until the real image settles: its `load`
+  plus `fadeInDuration` (at once when `fadeIn` is off), or its final error once
+  any retries are spent.
+- It sits in the box's flow and gives the box its size. The real image is drawn
+  over it, cropped by `objectFit`, and fades in on top; when the placeholder
+  goes, the real image takes the flow. So a placeholder whose shape differs
+  from the real image's gives the box its shape until the fade ends.
+- A placeholder that fails to load is dropped at once, as if none were set.
+- `onLoad` and `onError` are the real image's only: the placeholder's load
+  never calls `onLoad`, and its failure never calls `onError`.
+- An empty `src` keeps the placeholder up; no empty `<img>` is rendered.
+
+**Give it a width.** With no `width` the placeholder shows at its own size,
+which for a low-res placeholder is usually tiny. Set one, or `width="100%"`.
+
 ### With Error Fallback
 
 ```tsx
@@ -170,8 +188,8 @@ wrapping element, rounded to match the image:
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `lazy` | `boolean` | `true` | Enable lazy loading |
-| `loadingState` | `'skeleton' \| 'spinner' \| 'placeholder' \| 'none'` | `'skeleton'` | Type of loading indicator |
-| `placeholder` | `string` | - | Placeholder image URL |
+| `loadingState` | `'skeleton' \| 'spinner' \| 'placeholder' \| 'none'` | `'skeleton'` | Type of loading indicator. `'placeholder'` shows the `placeholder` image until the real image has faded in over it; set a `width` (or `"100%"`) with it |
+| `placeholder` | `string` | - | Low-res image shown while loading, only under `loadingState="placeholder"` (ignored otherwise). See [With Placeholder](#with-placeholder) |
 | `rootMargin` | `string` | `'100px'` | Intersection Observer margin |
 | `threshold` | `number \| number[]` | `0` | Intersection Observer threshold |
 
@@ -263,11 +281,13 @@ wrapping element, rounded to match the image:
   height={48}
 />
 
-// For hero images with low-res placeholders
+// For hero images with low-res placeholders — give it a width, or the
+// placeholder shows at its own, tiny, size
 <LazyImage
   src="hero-hd.jpg"
   placeholder="hero-lowres.jpg"
   alt="Hero image"
+  width="100%"
   loadingState="placeholder"
 />
 ```

package/src/components/data-display/LazyImage/LazyImage.tsx

@@ -133,40 +133,59 @@ const SpinnerIndicator: React.FC<IndicatorProps> = ({ props }) => {
   );
 };
 
-const PlaceholderIndicator: React.FC<IndicatorProps & { hasSrc: boolean }> = ({
+/**
+ * The placeholder sits in the box's flow and gives the box its size: the box's
+ * own when one is set, the placeholder's when not. The real image is drawn over
+ * it (`OVER_PLACEHOLDER`) until it has faded in. Its load and error are not the
+ * image's, so neither reaches the caller; a failing one just retires.
+ */
+const PlaceholderIndicator: React.FC<IndicatorProps & { onError: () => void }> = ({
   props,
   metrics,
-  hasSrc,
+  onError,
 }) => {
-  // Once a src has been chosen the real <img> is on screen, so the placeholder
-  // would only stack behind it.
-  if (!props.placeholder || hasSrc) return null;
+  if (!props.placeholder) return null;
 
   return (
     <StyledImage
       src={props.placeholder}
       alt={`${props.alt} (loading)`}
       style={metrics}
+      decoding={props.decoding}
+      loading={props.lazy ? 'lazy' : props.loading}
+      onError={onError}
       data-testid={`${props['data-testid']}-placeholder`}
     />
   );
 };
 
 const LoadingIndicator: React.FC<
-  IndicatorProps & { kind: NonNullable<LazyImageProps['loadingState']>; hasSrc: boolean }
-> = ({ kind, hasSrc, ...rest }) => {
+  IndicatorProps & { kind: NonNullable<LazyImageProps['loadingState']>; onPlaceholderError: () => void }
+> = ({ kind, onPlaceholderError, ...rest }) => {
   switch (kind) {
     case 'skeleton':
       return <SkeletonIndicator {...rest} />;
     case 'spinner':
       return <SpinnerIndicator {...rest} />;
     case 'placeholder':
-      return <PlaceholderIndicator {...rest} hasSrc={hasSrc} />;
+      return <PlaceholderIndicator {...rest} onError={onPlaceholderError} />;
     default:
       return null;
   }
 };
 
+/**
+ * The real image while the placeholder is up: laid over it and cropped by
+ * `objectFit`, so the box never grows to hold both. It takes the flow back
+ * when the placeholder goes.
+ */
+const OVER_PLACEHOLDER: React.CSSProperties = {
+  position: 'absolute',
+  inset: 0,
+  width: '100%',
+  height: '100%',
+};
+
 const ErrorFallback: React.FC<IndicatorProps> = ({ props, metrics }) => {
   const theme = useTheme();
   const { alt, fallback, width, height, borderRadius } = props;
@@ -214,8 +233,10 @@ export const LazyImage = React.memo<LazyImageProps>(function LazyImage(rawProps)
     effectiveLoadingState,
     handleImageLoad,
     handleImageError,
+    handlePlaceholderError,
     showImage,
     showLoading,
+    showPlaceholder,
   } = useLazyImage(props);
 
   const { width, height, borderRadius, alt } = props;
@@ -246,7 +267,7 @@ export const LazyImage = React.memo<LazyImageProps>(function LazyImage(rawProps)
           kind={effectiveLoadingState}
           props={props}
           metrics={metrics}
-          hasSrc={Boolean(state.currentSrc)}
+          onPlaceholderError={handlePlaceholderError}
         />
       )}
 
@@ -261,7 +282,7 @@ export const LazyImage = React.memo<LazyImageProps>(function LazyImage(rawProps)
           isLoaded={!state.isLoading}
           decoding={props.decoding}
           loading={props.lazy ? 'lazy' : props.loading}
-          style={{ ...metrics, ...props.sx }}
+          style={{ ...metrics, ...props.sx, ...(showPlaceholder && OVER_PLACEHOLDER) }}
           aria-label={props['aria-label'] || alt}
           aria-describedby={props['aria-describedby']}
           role={props.role}

package/src/components/data-display/LazyImage/LazyImage.types.ts

@@ -34,7 +34,17 @@ export interface LazyImageProps extends React.ImgHTMLAttributes<HTMLImageElement
   height?: number | string;
 
   /**
-   * Placeholder image URL to show while loading
+   * A low-resolution image URL shown while the real image loads. Only
+   * `loadingState="placeholder"` draws it; under any other loading state it is
+   * ignored. It shows from mount, lazy or not, until the real image has loaded
+   * and faded in (at once when `fadeIn` is off) or has finally failed. The real
+   * image is drawn over it and cropped by `objectFit`, so the box takes the
+   * placeholder's shape until the fade ends. A placeholder that fails to load is
+   * dropped, as if none were set, and is never reported to `onError`; neither
+   * does its load reach `onLoad`.
+   *
+   * Give LazyImage a `width` (or `"100%"`) in placeholder mode: with none, the
+   * placeholder shows at its own, usually tiny, size.
    */
   placeholder?: string;
 
@@ -47,8 +57,12 @@ export interface LazyImageProps extends React.ImgHTMLAttributes<HTMLImageElement
    * Loading state type
    * - 'skeleton': Shows a skeleton loader
    * - 'spinner': Shows a loading spinner
-   * - 'placeholder': Shows placeholder image
+   * - 'placeholder': Shows the `placeholder` image, in the box's flow, until the
+   *   real image has faded in over it; nothing when no `placeholder` is set.
+   *   Set a `width` (or `"100%"`), or the placeholder shows at its own size.
    * - 'none': No loading indicator
+   *
+   * `placeholder` applies only to 'placeholder'.
    * @default 'skeleton'
    */
   loadingState?: LazyImageLoadingState;
@@ -180,7 +194,9 @@ export interface LazyImageProps extends React.ImgHTMLAttributes<HTMLImageElement
    * Inline CSS for the `<img>` (its `style`), not MUI's `sx`: theme values and
    * nested selectors such as `'&:hover'` do not apply. The image's box clips
    * anything painted outside the image, such as a shadow, so put those on a
-   * wrapping element.
+   * wrapping element. While a placeholder is up (`loadingState="placeholder"`),
+   * the image is laid over it, so its `position`, `inset`, `width` and `height`
+   * are fixed until the placeholder retires; the rest applies throughout.
    */
   sx?: React.CSSProperties;
 

package/src/components/form/Autocomplete/Autocomplete.helpers.ts

@@ -104,12 +104,30 @@ function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/** One run of a highlighted label: plain text, or text the query matched. */
+export interface HighlightSegment {
+  text: string;
+  match: boolean;
+}
+
 /**
- * Wrap query matches in `<mark>` for the default suggestion renderer. Skipped for
- * fuzzy mode (non-contiguous matches) and empty queries. Returns HTML.
+ * Split `label` into the runs the query matches and the runs between them, in
+ * order, for the default suggestion renderer to wrap the matches in `<mark>`.
+ * Every occurrence of the query matches, case-insensitively and literally (regex
+ * metacharacters are escaped). Fuzzy mode (non-contiguous matches) and an empty
+ * query yield the whole label as one unmatched run.
+ *
+ * Returns TEXT, never markup: a label is caller data (in a consumer, a user's
+ * own display name), so the renderer must hand each run to React as a text
+ * child, which escapes it. Building an HTML string here and injecting it is how
+ * a label of `<img onerror=…>` once ran script in the host page.
  */
-export function highlightLabel(label: string, query: string, matchMode: MatchMode): string {
-  if (!query || matchMode === 'fuzzy') return label;
+export function highlightLabel(label: string, query: string, matchMode: MatchMode): HighlightSegment[] {
+  if (!query || matchMode === 'fuzzy') return [{ text: label, match: false }];
+  // The capturing group makes `split` keep each match, at the odd indices.
   const regex = new RegExp(`(${escapeRegExp(query)})`, 'gi');
-  return label.replace(regex, '<mark>$1</mark>');
+  return label
+    .split(regex)
+    .map((text, index) => ({ text, match: index % 2 === 1 }))
+    .filter((segment) => segment.text !== '');
 }

package/src/components/form/Autocomplete/Autocomplete.parts.tsx

@@ -194,7 +194,8 @@ export function DefaultSuggestion<T>({
 }): React.JSX.Element {
   const label = getLabel(item);
   const description = getDescription?.(item);
-  const displayLabel = highlightLabel(label, state.query, matchMode);
+  // Each run is a React text child, so the label is escaped however it reads.
+  const segments = highlightLabel(label, state.query, matchMode);
   return (
     <Box
       sx={{
@@ -202,13 +203,26 @@ export function DefaultSuggestion<T>({
         alignItems: 'center',
         gap: 1,
         width: '100%',
-        // Bold the matched prefix (not a yellow <mark> highlight).
+        // Bold every run the query matched, in any match mode but fuzzy — not
+        // only a prefix, even under `startsWith` (not a yellow <mark> highlight).
         '& mark': { backgroundColor: 'transparent', color: 'inherit', fontWeight: 700 },
       }}
     >
       {suggestionTypeIcon(getSuggestionType(item))}
       <ListItemText
-        primary={<span dangerouslySetInnerHTML={{ __html: displayLabel }} />}
+        primary={
+          <span>
+            {segments.map((segment, index) =>
+              // The runs are derived from one label and never reorder, so the
+              // position is a stable key.
+              segment.match ? (
+                <mark key={index}>{segment.text}</mark>
+              ) : (
+                <React.Fragment key={index}>{segment.text}</React.Fragment>
+              ),
+            )}
+          </span>
+        }
         secondary={description}
       />
     </Box>