@meginhufr/brua-web 0.3.0 → 0.4.0

package/dist/BruaPicture.svelte

@@ -1,30 +1,42 @@
 <!-- Brua for Svelte 5: the asset as a picture element (SPEC.md 7.2). The browser picks the format, density
      and color scheme, and follows dark mode live. Animations show their still. Import from "@meginhufr/brua-web/svelte".
      Given an id instead of an asset, the current release is read from the edge through the Brua set with
-     setBrua(); the last release it read shows at once, else the children until it has loaded, and when nothing is released under the id. -->
+     setBrua(); the last release it read shows at once, else the children until it has loaded. The error snippet, given the
+     reason, shows when there is no picture: nothing released, the edge unreachable, or the file failed; without it, the
+     children show then. -->
 <script>
   import { getContext } from "svelte";
   import { fillStyle, pictureModel } from "./picture.ts";
+  import { assetOrError } from "./brua.ts";
 
-  /** @type {{ asset?: import("./types.ts").AssetResponse, id?: string, brua?: import("./brua.ts").Brua, sizes?: string, loading?: "lazy" | "eager", class?: string, colorScheme?: "light" | "dark", objectFit?: "contain" | "cover" | "none", objectPosition?: string, children?: import("svelte").Snippet }} */
-  let { asset: given, id, brua = getContext("brua"), sizes, loading, class: imgClass, colorScheme, objectFit, objectPosition, children } = $props();
+  /** @type {{ asset?: import("./types.ts").AssetResponse, id?: string, brua?: import("./brua.ts").Brua, sizes?: string, loading?: "lazy" | "eager", class?: string, colorScheme?: "light" | "dark", objectFit?: "contain" | "cover" | "none", objectPosition?: string, children?: import("svelte").Snippet, error?: import("svelte").Snippet<[import("./types.ts").BruaImageError]> }} */
+  let { asset: given, id, brua = getContext("brua"), sizes, loading, class: imgClass, colorScheme, objectFit, objectPosition, children, error } = $props();
   // The last release the Brua read renders at once, so a remounted picture doesn't flash its children.
   let fetched = $state(id === undefined ? undefined : brua?.cachedAsset(id));
+  /** @type {import("./types.ts").BruaImageError | undefined} */
+  let reason = $state();
+  /** @type {string | undefined} */
+  let failed = $state();
 
   $effect(() => {
     if (given || id === undefined) return;
     if (!brua) throw new Error("BruaPicture with an id needs setBrua() in a parent, or a brua prop.");
     let live = true;
     fetched = brua.cachedAsset(id);
-    brua.asset(id).then((loaded) => { if (live) fetched = loaded; }, () => {});
+    reason = undefined;
+    assetOrError(brua, id).then((read) => { if (live) { fetched = read.asset; reason = read.error; } });
     return () => { live = false; };
   });
 
   let asset = $derived(given ?? fetched);
   let model = $derived(asset ? pictureModel(asset, { sizes, loading, className: imgClass, colorScheme, objectFit, objectPosition }) : undefined);
+  // The img's own error event: the file failed. Another file (a merge, another size) tries again.
+  let failure = $derived(model && failed === model.img.src ? { reason: "file", url: model.img.src } : !asset ? reason : undefined);
 </script>
 
-{#if model}
+{#if failure}
+  {#if error}{@render error(failure)}{:else if children}{@render children()}{/if}
+{:else if model}
   <picture>
     {#each model.sources as source (source.type + (source.media ?? ""))}
       <source type={source.type} media={source.media} srcset={source.srcset} sizes={source.sizes} />
@@ -41,6 +53,7 @@
       decoding={model.img.decoding}
       class={model.img.className}
       style={fillStyle(model.img)}
+      onerror={() => (failed = model.img.src)}
     />
   </picture>
 {:else if children}

package/dist/brua.d.ts

@@ -1,4 +1,4 @@
-import type { AssetResponse } from "./types.ts";
+import type { AssetResponse, BruaImageError } from "./types.ts";
 export interface BruaOptions {
     /** The organization's asset prefix on the edge, such as https://cdn.brua.dev/assets/{org}. */
     base: string;
@@ -28,3 +28,11 @@ export interface Brua {
     prefetch(ids: string[]): Promise<void>;
 }
 export declare function createBrua(options: BruaOptions): Brua;
+/**
+ * The asset with this id, or why there is none: not released, or the edge can't be reached with no release known. The
+ * framework components show their error view from it.
+ */
+export declare function assetOrError(brua: Brua, id: string): Promise<{
+    asset?: AssetResponse;
+    error?: BruaImageError;
+}>;

package/dist/brua.js

@@ -58,3 +58,16 @@ export function createBrua(options) {
     };
     return brua;
 }
+/**
+ * The asset with this id, or why there is none: not released, or the edge can't be reached with no release known. The
+ * framework components show their error view from it.
+ */
+export async function assetOrError(brua, id) {
+    try {
+        const asset = await brua.asset(id);
+        return asset ? { asset } : { error: { reason: "notReleased" } };
+    }
+    catch (cause) {
+        return { error: { reason: "unreachable", cause } };
+    }
+}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export type { AssetResponse, AssetVariant, ClientState } from "./types.ts";
+export type { AssetResponse, AssetVariant, BruaImageError, ClientState } from "./types.ts";
 export { selectUrl, selectVariant } from "./select.ts";
 export { fillStyle, pictureHtml, pictureModel, type PictureOptions, type PictureModel, type PictureSource, type PictureImage } from "./picture.ts";
 export { objectFitOf, objectPositionOf, targetWidth, type ObjectFit } from "./sizing.ts";
 export { browserClientState, defaultClientState, watchClientState, type ClientOptions } from "./client.ts";
-export { createBrua, type Brua, type BruaOptions } from "./brua.ts";
+export { assetOrError, createBrua, type Brua, type BruaOptions } from "./brua.ts";

package/dist/index.js

@@ -2,4 +2,4 @@ export { selectUrl, selectVariant } from "./select.js";
 export { fillStyle, pictureHtml, pictureModel } from "./picture.js";
 export { objectFitOf, objectPositionOf, targetWidth } from "./sizing.js";
 export { browserClientState, defaultClientState, watchClientState } from "./client.js";
-export { createBrua } from "./brua.js";
+export { assetOrError, createBrua } from "./brua.js";

package/dist/react.d.ts

@@ -2,7 +2,7 @@ import { type ReactElement, type ReactNode } from "react";
 import { type PictureOptions } from "./picture.ts";
 import { type ClientOptions } from "./client.ts";
 import { type Brua, type BruaOptions } from "./brua.ts";
-import type { AssetResponse } from "./types.ts";
+import type { AssetResponse, BruaImageError } from "./types.ts";
 export type BruaProviderProps = {
     children?: ReactNode;
 } & ({
@@ -15,6 +15,14 @@ export declare function BruaProvider(props: BruaProviderProps): ReactElement;
  * undefined until it has loaded, and when nothing is released under the id. Loads only in the browser; a server render shows the fallback.
  */
 export declare function useBruaAsset(id: string | undefined, brua?: Brua): AssetResponse | undefined;
+/**
+ * The asset's current release for an id, as useBruaAsset gives it, or the error when there is none: not released, or
+ * the edge can't be reached with no release known. Both undefined while it loads.
+ */
+export declare function useBruaAssetState(id: string | undefined, brua?: Brua): {
+    asset?: AssetResponse;
+    error?: BruaImageError;
+};
 export interface BruaPictureProps extends PictureOptions {
     /** The asset as your backend embedded it: a snapshot of one release. */
     asset?: AssetResponse;
@@ -22,14 +30,16 @@ export interface BruaPictureProps extends PictureOptions {
     id?: string;
     /** The Brua to read the id through, instead of the provider's. */
     brua?: Brua;
-    /** What shows until the id has loaded, and when nothing is released under it. */
+    /** What shows until the id has loaded, and on failure when no error view is given. */
     fallback?: ReactNode;
+    /** What shows when there is no picture, with the reason: nothing released, the edge unreachable, or the file failed. */
+    error?: ReactNode | ((error: BruaImageError) => ReactNode);
 }
 /**
  * The asset as a picture element (SPEC.md 7.2): the browser picks the format, density and color scheme,
  * and follows dark mode live. Animations show their still.
  */
-export declare function BruaPicture({ asset, id, brua, fallback, sizes, loading, className, colorScheme, objectFit, objectPosition }: BruaPictureProps): ReactElement | null;
+export declare function BruaPicture({ asset, id, brua, fallback, error, sizes, loading, className, colorScheme, objectFit, objectPosition }: BruaPictureProps): ReactElement | null;
 /**
  * One variant URL for the asset, chosen for this browser and kept current as its appearance, motion setting
  * or pixel density changes: for a CSS background, a canvas or an animation player. Renders light at 1x on

package/dist/react.js

@@ -3,7 +3,7 @@ import { createContext, createElement, useContext, useEffect, useMemo, useState
 import { pictureModel } from "./picture.js";
 import { selectUrl } from "./select.js";
 import { defaultClientState, watchClientState } from "./client.js";
-import { createBrua } from "./brua.js";
+import { assetOrError, createBrua } from "./brua.js";
 const BruaContext = createContext(undefined);
 /** Where the app's assets are read from by id: wrap the app once, then <BruaPicture id="…"> anywhere below. */
 export function BruaProvider(props) {
@@ -17,33 +17,45 @@ export function BruaProvider(props) {
  * undefined until it has loaded, and when nothing is released under the id. Loads only in the browser; a server render shows the fallback.
  */
 export function useBruaAsset(id, brua) {
+    return useBruaAssetState(id, brua).asset;
+}
+/**
+ * The asset's current release for an id, as useBruaAsset gives it, or the error when there is none: not released, or
+ * the edge can't be reached with no release known. Both undefined while it loads.
+ */
+export function useBruaAssetState(id, brua) {
     const fromContext = useContext(BruaContext);
     const client = brua ?? fromContext;
     // The last release the Brua read renders at once, so a remounted picture doesn't flash its fallback.
-    const [asset, setAsset] = useState(() => (id === undefined ? undefined : client?.cachedAsset(id)));
+    const [state, setState] = useState(() => ({ asset: id === undefined ? undefined : client?.cachedAsset(id) }));
     if (id !== undefined && !client)
         throw new Error("useBruaAsset needs a <BruaProvider> above it, or a Brua passed in.");
     useEffect(() => {
         if (id === undefined || !client)
             return;
         let live = true;
-        setAsset(client.cachedAsset(id));
-        client.asset(id).then((loaded) => { if (live)
-            setAsset(loaded); }, () => { });
+        setState({ asset: client.cachedAsset(id) });
+        assetOrError(client, id).then((read) => { if (live)
+            setState(read); });
         return () => { live = false; };
     }, [client, id]);
-    return id === undefined ? undefined : asset;
+    return id === undefined ? {} : state;
 }
 /**
  * The asset as a picture element (SPEC.md 7.2): the browser picks the format, density and color scheme,
  * and follows dark mode live. Animations show their still.
  */
-export function BruaPicture({ asset, id, brua, fallback = null, sizes, loading, className, colorScheme, objectFit, objectPosition }) {
-    const fetched = useBruaAsset(asset ? undefined : id, brua);
-    const shown = asset ?? fetched;
+export function BruaPicture({ asset, id, brua, fallback = null, error, sizes, loading, className, colorScheme, objectFit, objectPosition }) {
+    const fetched = useBruaAssetState(asset ? undefined : id, brua);
+    const [failed, setFailed] = useState();
+    const shown = asset ?? fetched.asset;
+    const failure = (reason) => (error === undefined ? fallback : typeof error === "function" ? error(reason) : error);
     if (!shown)
-        return fallback;
+        return fetched.error ? failure(fetched.error) : fallback;
     const { sources, img } = pictureModel(shown, { sizes, loading, className, colorScheme, objectFit, objectPosition });
+    // The img's own error event: the file failed. Another file (a merge, another size) tries again.
+    if (failed === img.src)
+        return failure({ reason: "file", url: img.src });
     return createElement("picture", null, ...sources.map((s) => createElement("source", { key: `${s.type}${s.media ?? ""}`, type: s.type, media: s.media, srcSet: s.srcset, sizes: s.sizes })), createElement("img", {
         src: img.src,
         srcSet: img.srcset,
@@ -56,6 +68,7 @@ export function BruaPicture({ asset, id, brua, fallback = null, sizes, loading,
         decoding: img.decoding,
         className: img.className,
         style: img.objectFit === undefined ? undefined : { objectFit: img.objectFit, objectPosition: img.objectPosition },
+        onError: () => setFailed(img.src),
     }));
 }
 /**

package/dist/types.d.ts

@@ -13,6 +13,19 @@ export interface AssetResponse {
     /** Where it sits in the box, as CSS object-position: "50% 35%", the point a cover crop keeps in view. */
     objectPosition?: string;
 }
+/**
+ * Why a picture has none to show, with the same reasons on every platform's SDK: nothing is released under the id (the
+ * edge answered 404, usually draw nothing), the edge can't be reached and no release is known, or the file failed.
+ */
+export type BruaImageError = {
+    reason: "notReleased";
+} | {
+    reason: "unreachable";
+    cause: unknown;
+} | {
+    reason: "file";
+    url: string;
+};
 /** Value fields are plain strings, not unions, so new values from the API never break decoding (SPEC.md 14). */
 export interface AssetVariant {
     type: string;

package/dist/vue.d.ts

@@ -1,7 +1,7 @@
 import { type ComputedRef, type InjectionKey, type MaybeRef, type MaybeRefOrGetter, type PropType, type Ref } from "vue";
 import { type ClientOptions } from "./client.ts";
 import { type Brua, type BruaOptions } from "./brua.ts";
-import type { AssetResponse } from "./types.ts";
+import type { AssetResponse, BruaImageError } from "./types.ts";
 export declare const bruaKey: InjectionKey<Brua>;
 /** Where the app's assets are read from by id: call once in the root component, then <BruaPicture id="…"> anywhere below. */
 export declare function provideBrua(options: Brua | BruaOptions): Brua;
@@ -10,10 +10,19 @@ export declare function provideBrua(options: Brua | BruaOptions): Brua;
  * undefined until it has loaded, and when nothing is released under the id. A server render shows the fallback.
  */
 export declare function useBruaAsset(id: MaybeRefOrGetter<string | undefined>, brua?: Brua): Ref<AssetResponse | undefined>;
+/**
+ * The asset's current release for an id, as useBruaAsset gives it, or the error when there is none: not released, or
+ * the edge can't be reached with no release known. Both undefined while it loads.
+ */
+export declare function useBruaAssetState(id: MaybeRefOrGetter<string | undefined>, brua?: Brua): Ref<{
+    asset?: AssetResponse;
+    error?: BruaImageError;
+}>;
 /**
  * The asset as a picture element (SPEC.md 7.2): the browser picks the format, density and color scheme,
  * and follows dark mode live. Animations show their still. Attributes such as class go on the img.
- * The default slot shows until an id has loaded, and when nothing is released under it.
+ * The default slot shows until an id has loaded; the error slot, given the reason as `error`, when there is no picture:
+ * nothing released, the edge unreachable, or the file failed. Without an error slot the default one shows then.
  */
 export declare const BruaPicture: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** The asset as your backend embedded it: a snapshot of one release. */

package/dist/vue.js

@@ -3,7 +3,7 @@ import { computed, defineComponent, h, inject, onBeforeUnmount, onMounted, provi
 import { fillStyle, pictureModel } from "./picture.js";
 import { selectUrl } from "./select.js";
 import { defaultClientState, watchClientState } from "./client.js";
-import { createBrua } from "./brua.js";
+import { assetOrError, createBrua } from "./brua.js";
 export const bruaKey = Symbol("brua");
 /** Where the app's assets are read from by id: call once in the root component, then <BruaPicture id="…"> anywhere below. */
 export function provideBrua(options) {
@@ -16,28 +16,37 @@ export function provideBrua(options) {
  * undefined until it has loaded, and when nothing is released under the id. A server render shows the fallback.
  */
 export function useBruaAsset(id, brua) {
+    const state = useBruaAssetState(id, brua);
+    return computed(() => state.value.asset);
+}
+/**
+ * The asset's current release for an id, as useBruaAsset gives it, or the error when there is none: not released, or
+ * the edge can't be reached with no release known. Both undefined while it loads.
+ */
+export function useBruaAssetState(id, brua) {
     const client = brua ?? inject(bruaKey, undefined);
-    const asset = ref();
+    const state = ref({});
     watchEffect((onCleanup) => {
         const wanted = toValue(id);
         if (wanted === undefined) {
-            asset.value = undefined;
+            state.value = {};
             return;
         }
         if (!client)
             throw new Error("useBruaAsset needs provideBrua() in a parent, or a Brua passed in.");
         let live = true;
         onCleanup(() => { live = false; });
-        asset.value = client.cachedAsset(wanted);
-        client.asset(wanted).then((loaded) => { if (live)
-            asset.value = loaded; }, () => { });
+        state.value = { asset: client.cachedAsset(wanted) };
+        assetOrError(client, wanted).then((read) => { if (live)
+            state.value = read; });
     });
-    return asset;
+    return state;
 }
 /**
  * The asset as a picture element (SPEC.md 7.2): the browser picks the format, density and color scheme,
  * and follows dark mode live. Animations show their still. Attributes such as class go on the img.
- * The default slot shows until an id has loaded, and when nothing is released under it.
+ * The default slot shows until an id has loaded; the error slot, given the reason as `error`, when there is no picture:
+ * nothing released, the edge unreachable, or the file failed. Without an error slot the default one shows then.
  */
 export const BruaPicture = defineComponent({
     name: "BruaPicture",
@@ -60,14 +69,19 @@ export const BruaPicture = defineComponent({
         objectPosition: { type: String, required: false },
     },
     setup(props, { attrs, slots }) {
-        const fetched = useBruaAsset(() => (props.asset ? undefined : props.id), props.brua);
+        const fetched = useBruaAssetState(() => (props.asset ? undefined : props.id), props.brua);
+        const failed = ref();
+        const failure = (error) => (slots.error ?? slots.default)?.({ error }) ?? null;
         return () => {
-            const asset = props.asset ?? fetched.value;
+            const asset = props.asset ?? fetched.value.asset;
             if (!asset)
-                return slots.default?.() ?? null;
+                return fetched.value.error ? failure(fetched.value.error) : slots.default?.() ?? null;
             const { sources, img } = pictureModel(asset, {
                 sizes: props.sizes, loading: props.loading, colorScheme: props.colorScheme, objectFit: props.objectFit, objectPosition: props.objectPosition,
             });
+            // The img's own error event: the file failed. Another file (a merge, another size) tries again.
+            if (failed.value === img.src)
+                return failure({ reason: "file", url: img.src });
             return h("picture", [
                 ...sources.map((s) => h("source", { key: `${s.type}${s.media ?? ""}`, type: s.type, media: s.media, srcset: s.srcset, sizes: s.sizes })),
                 h("img", {
@@ -83,6 +97,7 @@ export const BruaPicture = defineComponent({
                     decoding: img.decoding,
                     // The fill first, so a style the page gives the component still wins.
                     style: [fillStyle(img), attrs.style],
+                    onError: () => { failed.value = img.src; },
                 }),
             ]);
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meginhufr/brua-web",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Brua for the web: AssetResponse types, the variant selection rule, <picture> rendering, and components for React, Vue and Svelte.",
   "author": "Meginhufr AS <hello@brua.dev> (https://brua.dev)",
   "license": "MIT",