@meginhufr/brua-web 0.2.0 → 0.3.0

package/dist/BruaPicture.svelte

@@ -4,10 +4,10 @@
      setBrua(); the last release it read shows at once, else the children until it has loaded, and when nothing is released under the id. -->
 <script>
   import { getContext } from "svelte";
-  import { pictureModel } from "./picture.ts";
+  import { fillStyle, pictureModel } from "./picture.ts";
 
-  /** @type {{ asset?: import("./types.ts").AssetResponse, id?: string, brua?: import("./brua.ts").Brua, sizes?: string, loading?: "lazy" | "eager", class?: string, colorScheme?: "light" | "dark", children?: import("svelte").Snippet }} */
-  let { asset: given, id, brua = getContext("brua"), sizes, loading, class: imgClass, colorScheme, 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 }} */
+  let { asset: given, id, brua = getContext("brua"), sizes, loading, class: imgClass, colorScheme, objectFit, objectPosition, children } = $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));
 
@@ -21,7 +21,7 @@
   });
 
   let asset = $derived(given ?? fetched);
-  let model = $derived(asset ? pictureModel(asset, { sizes, loading, className: imgClass, colorScheme }) : undefined);
+  let model = $derived(asset ? pictureModel(asset, { sizes, loading, className: imgClass, colorScheme, objectFit, objectPosition }) : undefined);
 </script>
 
 {#if model}
@@ -40,6 +40,7 @@
       loading={model.img.loading}
       decoding={model.img.decoding}
       class={model.img.className}
+      style={fillStyle(model.img)}
     />
   </picture>
 {:else if children}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export type { AssetResponse, AssetVariant, ClientState } from "./types.ts";
 export { selectUrl, selectVariant } from "./select.ts";
-export { pictureHtml, pictureModel, type PictureOptions, type PictureModel, type PictureSource, type PictureImage } from "./picture.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";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { selectUrl, selectVariant } from "./select.js";
-export { pictureHtml, pictureModel } from "./picture.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";

package/dist/picture.d.ts

@@ -9,6 +9,13 @@ export interface PictureOptions {
      * the dark files go behind a media query and the browser follows the system setting.
      */
     colorScheme?: "light" | "dark";
+    /**
+     * How the img fills its box: "contain" or "cover" overrides the asset's own fit, and "none" leaves the fit and
+     * the position to the page's CSS. Left out, the asset's fit is used.
+     */
+    objectFit?: "contain" | "cover" | "none";
+    /** Where the img sits in its box, as "x% y%"; left out, the asset's position. */
+    objectPosition?: string;
 }
 /** A `<source>` of the picture: one format, optionally one color scheme. */
 export interface PictureSource {
@@ -29,6 +36,9 @@ export interface PictureImage {
     loading: "lazy" | "eager";
     decoding: "async";
     className?: string;
+    /** The object-fit and object-position the img is drawn with, when the asset or the call site gives a fill. */
+    objectFit?: "contain" | "cover";
+    objectPosition?: string;
 }
 /** What a picture element for the asset consists of; the HTML renderer and the framework components build from it. */
 export interface PictureModel {
@@ -41,5 +51,7 @@ export interface PictureModel {
  * without client hints and switches live with the color scheme. Animations aren't rendered; their stills are.
  */
 export declare function pictureModel(asset: AssetResponse, options?: PictureOptions): PictureModel;
+/** The img's fill as a style attribute's value. */
+export declare function fillStyle(img: PictureImage): string | undefined;
 /** The picture as an HTML string, for innerHTML or server-rendered pages. */
 export declare function pictureHtml(asset: AssetResponse, options?: PictureOptions): string;

package/dist/picture.js

@@ -1,3 +1,4 @@
+import { objectFitOf, objectPositionOf } from "./sizing.js";
 const SVG = "image/svg+xml";
 /** Formats offered as <source> elements, best first; anything else becomes the <img> fallback. */
 const SOURCE_TYPES = ["image/avif", "image/webp"];
@@ -51,9 +52,25 @@ export function pictureModel(asset, options = {}) {
             loading: options.loading ?? "lazy",
             decoding: "async",
             className: options.className,
+            ...fill(asset, options),
         },
     };
 }
+/**
+ * The fill to put on the img: the call site's or the asset's, cleaned to what CSS takes. A response from before the
+ * fill, with no override either, gets none, so the page draws it as it always has.
+ */
+function fill(asset, options) {
+    if (options.objectFit === "none")
+        return {};
+    if (asset.objectFit === undefined && asset.objectPosition === undefined && options.objectFit === undefined && options.objectPosition === undefined)
+        return {};
+    return { objectFit: objectFitOf(asset, options.objectFit), objectPosition: objectPositionOf(asset, options.objectPosition) };
+}
+/** The img's fill as a style attribute's value. */
+export function fillStyle(img) {
+    return img.objectFit === undefined ? undefined : `object-fit: ${img.objectFit}; object-position: ${img.objectPosition}`;
+}
 /** The picture as an HTML string, for innerHTML or server-rendered pages. */
 export function pictureHtml(asset, options = {}) {
     const { sources, img } = pictureModel(asset, options);
@@ -69,6 +86,7 @@ export function pictureHtml(asset, options = {}) {
         loading: img.loading,
         decoding: img.decoding,
         class: img.className,
+        style: fillStyle(img),
     }));
     return `<picture>${rendered.join("")}</picture>`;
 }

package/dist/react.d.ts

@@ -29,7 +29,7 @@ export interface BruaPictureProps extends PictureOptions {
  * 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 }: BruaPictureProps): ReactElement | null;
+export declare function BruaPicture({ asset, id, brua, fallback, 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

@@ -38,12 +38,12 @@ export function useBruaAsset(id, brua) {
  * 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 }) {
+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;
     if (!shown)
         return fallback;
-    const { sources, img } = pictureModel(shown, { sizes, loading, className, colorScheme });
+    const { sources, img } = pictureModel(shown, { sizes, loading, className, colorScheme, objectFit, objectPosition });
     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,
@@ -55,6 +55,7 @@ export function BruaPicture({ asset, id, brua, fallback = null, sizes, loading,
         loading: img.loading,
         decoding: img.decoding,
         className: img.className,
+        style: img.objectFit === undefined ? undefined : { objectFit: img.objectFit, objectPosition: img.objectPosition },
     }));
 }
 /**

package/dist/sizing.d.ts

@@ -0,0 +1,12 @@
+import type { AssetResponse } from "./types.ts";
+export type ObjectFit = "contain" | "cover";
+/** The fit to draw with: the call site's override, else the asset's, else contain. Unknown values are contain. */
+export declare function objectFitOf(asset: Pick<AssetResponse, "objectFit">, override?: string): ObjectFit;
+/** Where the picture sits in its box, as "x% y%": the call site's, else the asset's, else the centre. */
+export declare function objectPositionOf(asset: Pick<AssetResponse, "objectPosition">, override?: string): string;
+/**
+ * How wide the picture is drawn in a box of this size, in CSS pixels or points, for the selection rule's
+ * `targetWidth`. Contain, or a box without a height yet, draws it at the box width; cover at the larger of the box
+ * width and the box height times the asset's proportions.
+ */
+export declare function targetWidth(asset: Pick<AssetResponse, "width" | "height" | "objectFit">, boxWidth: number, boxHeight?: number, objectFit?: string): number;

package/dist/sizing.js

@@ -0,0 +1,21 @@
+const POSITION = /^(100|[1-9]?[0-9])% (100|[1-9]?[0-9])%$/;
+/** The fit to draw with: the call site's override, else the asset's, else contain. Unknown values are contain. */
+export function objectFitOf(asset, override) {
+    const fit = override ?? asset.objectFit;
+    return fit === "cover" ? "cover" : "contain";
+}
+/** Where the picture sits in its box, as "x% y%": the call site's, else the asset's, else the centre. */
+export function objectPositionOf(asset, override) {
+    const position = override ?? asset.objectPosition;
+    return position !== undefined && POSITION.test(position) ? position : "50% 50%";
+}
+/**
+ * How wide the picture is drawn in a box of this size, in CSS pixels or points, for the selection rule's
+ * `targetWidth`. Contain, or a box without a height yet, draws it at the box width; cover at the larger of the box
+ * width and the box height times the asset's proportions.
+ */
+export function targetWidth(asset, boxWidth, boxHeight, objectFit) {
+    if (objectFitOf(asset, objectFit) !== "cover" || boxHeight === undefined || boxHeight <= 0 || asset.height <= 0)
+        return boxWidth;
+    return Math.max(boxWidth, boxHeight * (asset.width / asset.height));
+}

package/dist/types.d.ts

@@ -8,6 +8,10 @@ export interface AssetResponse {
     alt: string;
     lang?: string;
     variants: AssetVariant[];
+    /** How a layout's box of another shape holds the asset, as CSS object-fit: "contain" or "cover". */
+    objectFit?: string;
+    /** Where it sits in the box, as CSS object-position: "50% 35%", the point a cover crop keeps in view. */
+    objectPosition?: string;
 }
 /** Value fields are plain strings, not unions, so new values from the API never break decoding (SPEC.md 14). */
 export interface AssetVariant {

package/dist/vue.d.ts

@@ -45,6 +45,16 @@ export declare const BruaPicture: import("vue").DefineComponent<import("vue").Ex
         type: PropType<"light" | "dark">;
         required: false;
     };
+    /** "contain" or "cover" to override the asset's fit, or "none" to leave the fit to the page's CSS. */
+    objectFit: {
+        type: PropType<"contain" | "cover" | "none">;
+        required: false;
+    };
+    /** Where the img sits in its box, as "x% y%", instead of the asset's position. */
+    objectPosition: {
+        type: StringConstructor;
+        required: false;
+    };
 }>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
     [key: string]: any;
 }> | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
@@ -79,6 +89,16 @@ export declare const BruaPicture: import("vue").DefineComponent<import("vue").Ex
         type: PropType<"light" | "dark">;
         required: false;
     };
+    /** "contain" or "cover" to override the asset's fit, or "none" to leave the fit to the page's CSS. */
+    objectFit: {
+        type: PropType<"contain" | "cover" | "none">;
+        required: false;
+    };
+    /** Where the img sits in its box, as "x% y%", instead of the asset's position. */
+    objectPosition: {
+        type: StringConstructor;
+        required: false;
+    };
 }>> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 /**
  * One variant URL for the asset, chosen for this browser and kept current as its appearance, motion setting

package/dist/vue.js

@@ -1,6 +1,6 @@
 // Brua for Vue 3: provideBrua, <BruaPicture>, useBruaAsset and useBruaUrl. Import from "@meginhufr/brua-web/vue".
 import { computed, defineComponent, h, inject, onBeforeUnmount, onMounted, provide, ref, toValue, unref, watchEffect, } from "vue";
-import { pictureModel } from "./picture.js";
+import { fillStyle, pictureModel } from "./picture.js";
 import { selectUrl } from "./select.js";
 import { defaultClientState, watchClientState } from "./client.js";
 import { createBrua } from "./brua.js";
@@ -54,6 +54,10 @@ export const BruaPicture = defineComponent({
         loading: { type: String, required: false },
         /** "light" or "dark" to show that scheme's files only, for apps that switch themes themselves. */
         colorScheme: { type: String, required: false },
+        /** "contain" or "cover" to override the asset's fit, or "none" to leave the fit to the page's CSS. */
+        objectFit: { type: String, required: false },
+        /** Where the img sits in its box, as "x% y%", instead of the asset's position. */
+        objectPosition: { type: String, required: false },
     },
     setup(props, { attrs, slots }) {
         const fetched = useBruaAsset(() => (props.asset ? undefined : props.id), props.brua);
@@ -61,7 +65,9 @@ export const BruaPicture = defineComponent({
             const asset = props.asset ?? fetched.value;
             if (!asset)
                 return slots.default?.() ?? null;
-            const { sources, img } = pictureModel(asset, { sizes: props.sizes, loading: props.loading, colorScheme: props.colorScheme });
+            const { sources, img } = pictureModel(asset, {
+                sizes: props.sizes, loading: props.loading, colorScheme: props.colorScheme, objectFit: props.objectFit, objectPosition: props.objectPosition,
+            });
             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", {
@@ -75,6 +81,8 @@ export const BruaPicture = defineComponent({
                     lang: img.lang,
                     loading: img.loading,
                     decoding: img.decoding,
+                    // The fill first, so a style the page gives the component still wins.
+                    style: [fillStyle(img), attrs.style],
                 }),
             ]);
         };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@meginhufr/brua-web",
-  "version": "0.2.0",
+  "version": "0.3.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",
   "homepage": "https://brua.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Meginhufr/brua-web.git"
+    "url": "git+https://github.com/Meginhufr/brua-web.git"
   },
   "type": "module",
   "sideEffects": false,