@asnewyla/image 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @asnewyla/image
+
+Image display with org styling — aspect ratio, object-fit, token-based
+rounding, and a load-error fallback.
+
+## Install
+
+```bash
+npm install @asnewyla/image
+```
+
+## Usage
+
+```tsx
+import { Image } from '@asnewyla/image';
+
+<Image src="/hero.jpg" alt="Team at the launch event" />
+
+<Image
+  src="/avatar.png"
+  alt="Jordan's profile picture"
+  aspectRatio="1 / 1"
+  radius="full"
+  fallback="/default-avatar.png"
+/>
+
+// Decorative image — alt is still required, pass an empty string explicitly
+<Image src="/divider.svg" alt="" />
+```
+
+### Props
+
+| Prop | Type | Default |
+|---|---|---|
+| `src` | `string` | — |
+| `alt` | `string` (**required**) | — |
+| `aspectRatio` | `string` (any CSS `aspect-ratio` value, e.g. `"16 / 9"`) | — |
+| `fit` | `'cover' \| 'contain' \| 'fill' \| 'none' \| 'scale-down'` | `'cover'` |
+| `radius` | `'sm' \| 'md' \| 'lg' \| 'full'` | none (square corners) |
+| `fallback` | `string` (src to swap to if `src` fails to load) | — |
+
+`alt` has no default and isn't optional — TypeScript forces you to decide.
+For a genuinely decorative image, pass `alt=""` explicitly rather than
+omitting it.
+
+If `fallback` also fails to load, `Image` stops swapping — it doesn't loop.
+If `src` changes to a new value later, the fallback state resets and the new
+`src` gets its own attempt.
+
+### Theming
+
+`radius` reads from `@asnewyla/tokens` the same way `@asnewyla/button` does —
+optional import, works standalone with built-in fallbacks:
+
+```ts
+import '@asnewyla/tokens/tokens.css';
+```
+
+## License
+
+MIT

package/dist/index.css

@@ -0,0 +1,33 @@
+/* src/components/Image.css */
+.xd-image {
+  display: block;
+  max-width: 100%;
+}
+.xd-image[data-fit=cover] {
+  object-fit: cover;
+}
+.xd-image[data-fit=contain] {
+  object-fit: contain;
+}
+.xd-image[data-fit=fill] {
+  object-fit: fill;
+}
+.xd-image[data-fit=none] {
+  object-fit: none;
+}
+.xd-image[data-fit=scale-down] {
+  object-fit: scale-down;
+}
+.xd-image[data-radius=sm] {
+  border-radius: var(--xd-radius-sm, 0.25rem);
+}
+.xd-image[data-radius=md] {
+  border-radius: var(--xd-radius-md, 0.375rem);
+}
+.xd-image[data-radius=lg] {
+  border-radius: var(--xd-radius-lg, 0.625rem);
+}
+.xd-image[data-radius=full] {
+  border-radius: var(--xd-radius-full, 9999px);
+}
+/*# sourceMappingURL=index.css.map */

package/dist/index.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components/Image.css"],"sourcesContent":[".xd-image {\n  display: block;\n  max-width: 100%;\n}\n\n/* --- Fit --- */\n\n.xd-image[data-fit=\"cover\"] {\n  object-fit: cover;\n}\n\n.xd-image[data-fit=\"contain\"] {\n  object-fit: contain;\n}\n\n.xd-image[data-fit=\"fill\"] {\n  object-fit: fill;\n}\n\n.xd-image[data-fit=\"none\"] {\n  object-fit: none;\n}\n\n.xd-image[data-fit=\"scale-down\"] {\n  object-fit: scale-down;\n}\n\n/* --- Radius ---\n   Fallback values kept in sync with @asnewyla/tokens (soft dependency —\n   see PROJECT.md, Tokens dependency model). No data-radius attribute means\n   no rounding, matching the native <img> default. */\n\n.xd-image[data-radius=\"sm\"] {\n  border-radius: var(--xd-radius-sm, 0.25rem);\n}\n\n.xd-image[data-radius=\"md\"] {\n  border-radius: var(--xd-radius-md, 0.375rem);\n}\n\n.xd-image[data-radius=\"lg\"] {\n  border-radius: var(--xd-radius-lg, 0.625rem);\n}\n\n.xd-image[data-radius=\"full\"] {\n  border-radius: var(--xd-radius-full, 9999px);\n}\n"],"mappings":";AAAA,CAAC;AACC,WAAS;AACT,aAAW;AACb;AAIA,CAPC,QAOQ,CAAC;AACR,cAAY;AACd;AAEA,CAXC,QAWQ,CAAC;AACR,cAAY;AACd;AAEA,CAfC,QAeQ,CAAC;AACR,cAAY;AACd;AAEA,CAnBC,QAmBQ,CAAC;AACR,cAAY;AACd;AAEA,CAvBC,QAuBQ,CAAC;AACR,cAAY;AACd;AAOA,CAhCC,QAgCQ,CAAC;AACR,iBAAe,IAAI,cAAc,EAAE;AACrC;AAEA,CApCC,QAoCQ,CAAC;AACR,iBAAe,IAAI,cAAc,EAAE;AACrC;AAEA,CAxCC,QAwCQ,CAAC;AACR,iBAAe,IAAI,cAAc,EAAE;AACrC;AAEA,CA5CC,QA4CQ,CAAC;AACR,iBAAe,IAAI,gBAAgB,EAAE;AACvC;","names":[]}

package/dist/index.d.mts

@@ -0,0 +1,21 @@
+import * as react from 'react';
+import { ImgHTMLAttributes } from 'react';
+
+type ImageFit = 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+type ImageRadius = 'sm' | 'md' | 'lg' | 'full';
+type ImageProps = Omit<ImgHTMLAttributes<HTMLImageElement>, 'alt'> & {
+    alt: string;
+    aspectRatio?: string;
+    fit?: ImageFit;
+    radius?: ImageRadius;
+    fallback?: string;
+};
+declare const Image: react.ForwardRefExoticComponent<Omit<ImgHTMLAttributes<HTMLImageElement>, "alt"> & {
+    alt: string;
+    aspectRatio?: string;
+    fit?: ImageFit;
+    radius?: ImageRadius;
+    fallback?: string;
+} & react.RefAttributes<HTMLImageElement>>;
+
+export { Image, type ImageFit, type ImageProps, type ImageRadius };

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import * as react from 'react';
+import { ImgHTMLAttributes } from 'react';
+
+type ImageFit = 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+type ImageRadius = 'sm' | 'md' | 'lg' | 'full';
+type ImageProps = Omit<ImgHTMLAttributes<HTMLImageElement>, 'alt'> & {
+    alt: string;
+    aspectRatio?: string;
+    fit?: ImageFit;
+    radius?: ImageRadius;
+    fallback?: string;
+};
+declare const Image: react.ForwardRefExoticComponent<Omit<ImgHTMLAttributes<HTMLImageElement>, "alt"> & {
+    alt: string;
+    aspectRatio?: string;
+    fit?: ImageFit;
+    radius?: ImageRadius;
+    fallback?: string;
+} & react.RefAttributes<HTMLImageElement>>;
+
+export { Image, type ImageFit, type ImageProps, type ImageRadius };

package/dist/index.js

@@ -0,0 +1,47 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/components/Image.tsx
+function ImageInner({
+  alt,
+  aspectRatio,
+  fit = "cover",
+  radius,
+  fallback,
+  src,
+  className,
+  style,
+  onError,
+  ...restProps
+}, ref) {
+  const [hasErrored, setHasErrored] = react.useState(false);
+  react.useEffect(() => {
+    setHasErrored(false);
+  }, [src]);
+  const resolvedSrc = hasErrored && fallback ? fallback : src;
+  const handleError = (e) => {
+    setHasErrored(true);
+    onError?.(e);
+  };
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "img",
+    {
+      ref,
+      src: resolvedSrc,
+      alt,
+      "data-fit": fit,
+      "data-radius": radius || void 0,
+      className: ["xd-image", className].filter(Boolean).join(" "),
+      style: aspectRatio !== void 0 ? { aspectRatio, ...style } : style,
+      onError: handleError,
+      ...restProps
+    }
+  );
+}
+var Image = react.forwardRef(ImageInner);
+
+exports.Image = Image;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components/Image.tsx"],"names":["useState","useEffect","jsx","forwardRef"],"mappings":";;;;;;AAoBA,SAAS,UAAA,CACP;AAAA,EACE,GAAA;AAAA,EACA,WAAA;AAAA,EACA,GAAA,GAAM,OAAA;AAAA,EACN,MAAA;AAAA,EACA,QAAA;AAAA,EACA,GAAA;AAAA,EACA,SAAA;AAAA,EACA,KAAA;AAAA,EACA,OAAA;AAAA,EACA,GAAG;AACL,CAAA,EACA,GAAA,EACA;AACA,EAAA,MAAM,CAAC,UAAA,EAAY,aAAa,CAAA,GAAIA,eAAS,KAAK,CAAA;AAGlD,EAAAC,eAAA,CAAU,MAAM;AACd,IAAA,aAAA,CAAc,KAAK,CAAA;AAAA,EACrB,CAAA,EAAG,CAAC,GAAG,CAAC,CAAA;AAER,EAAA,MAAM,WAAA,GAAc,UAAA,IAAc,QAAA,GAAW,QAAA,GAAW,GAAA;AAExD,EAAA,MAAM,WAAA,GAAyD,CAAC,CAAA,KAAM;AACpE,IAAA,aAAA,CAAc,IAAI,CAAA;AAClB,IAAA,OAAA,GAAU,CAAC,CAAA;AAAA,EACb,CAAA;AAEA,EAAA,uBACEC,cAAA;AAAA,IAAC,KAAA;AAAA,IAAA;AAAA,MACC,GAAA;AAAA,MACA,GAAA,EAAK,WAAA;AAAA,MACL,GAAA;AAAA,MACA,UAAA,EAAU,GAAA;AAAA,MACV,eAAa,MAAA,IAAU,MAAA;AAAA,MACvB,SAAA,EAAW,CAAC,UAAA,EAAY,SAAS,EAAE,MAAA,CAAO,OAAO,CAAA,CAAE,IAAA,CAAK,GAAG,CAAA;AAAA,MAC3D,OAAO,WAAA,KAAgB,MAAA,GAAY,EAAE,WAAA,EAAa,GAAG,OAAM,GAAI,KAAA;AAAA,MAC/D,OAAA,EAAS,WAAA;AAAA,MACR,GAAG;AAAA;AAAA,GACN;AAEJ;AAEO,IAAM,KAAA,GAAQC,iBAAW,UAAU","file":"index.js","sourcesContent":["import {\n  type ForwardedRef,\n  type ImgHTMLAttributes,\n  forwardRef,\n  useEffect,\n  useState,\n} from 'react';\nimport './Image.css';\n\nexport type ImageFit = 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';\nexport type ImageRadius = 'sm' | 'md' | 'lg' | 'full';\n\nexport type ImageProps = Omit<ImgHTMLAttributes<HTMLImageElement>, 'alt'> & {\n  alt: string;\n  aspectRatio?: string;\n  fit?: ImageFit;\n  radius?: ImageRadius;\n  fallback?: string;\n};\n\nfunction ImageInner(\n  {\n    alt,\n    aspectRatio,\n    fit = 'cover',\n    radius,\n    fallback,\n    src,\n    className,\n    style,\n    onError,\n    ...restProps\n  }: ImageProps,\n  ref: ForwardedRef<HTMLImageElement>,\n) {\n  const [hasErrored, setHasErrored] = useState(false);\n\n  // biome-ignore lint/correctness/useExhaustiveDependencies: src triggers the reset intentionally, it isn't read in the body\n  useEffect(() => {\n    setHasErrored(false);\n  }, [src]);\n\n  const resolvedSrc = hasErrored && fallback ? fallback : src;\n\n  const handleError: React.ReactEventHandler<HTMLImageElement> = (e) => {\n    setHasErrored(true);\n    onError?.(e);\n  };\n\n  return (\n    <img\n      ref={ref}\n      src={resolvedSrc}\n      alt={alt}\n      data-fit={fit}\n      data-radius={radius || undefined}\n      className={['xd-image', className].filter(Boolean).join(' ')}\n      style={aspectRatio !== undefined ? { aspectRatio, ...style } : style}\n      onError={handleError}\n      {...restProps}\n    />\n  );\n}\n\nexport const Image = forwardRef(ImageInner);\n"]}

package/dist/index.mjs

@@ -0,0 +1,45 @@
+import { forwardRef, useState, useEffect } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/components/Image.tsx
+function ImageInner({
+  alt,
+  aspectRatio,
+  fit = "cover",
+  radius,
+  fallback,
+  src,
+  className,
+  style,
+  onError,
+  ...restProps
+}, ref) {
+  const [hasErrored, setHasErrored] = useState(false);
+  useEffect(() => {
+    setHasErrored(false);
+  }, [src]);
+  const resolvedSrc = hasErrored && fallback ? fallback : src;
+  const handleError = (e) => {
+    setHasErrored(true);
+    onError?.(e);
+  };
+  return /* @__PURE__ */ jsx(
+    "img",
+    {
+      ref,
+      src: resolvedSrc,
+      alt,
+      "data-fit": fit,
+      "data-radius": radius || void 0,
+      className: ["xd-image", className].filter(Boolean).join(" "),
+      style: aspectRatio !== void 0 ? { aspectRatio, ...style } : style,
+      onError: handleError,
+      ...restProps
+    }
+  );
+}
+var Image = forwardRef(ImageInner);
+
+export { Image };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components/Image.tsx"],"names":[],"mappings":";;;;AAoBA,SAAS,UAAA,CACP;AAAA,EACE,GAAA;AAAA,EACA,WAAA;AAAA,EACA,GAAA,GAAM,OAAA;AAAA,EACN,MAAA;AAAA,EACA,QAAA;AAAA,EACA,GAAA;AAAA,EACA,SAAA;AAAA,EACA,KAAA;AAAA,EACA,OAAA;AAAA,EACA,GAAG;AACL,CAAA,EACA,GAAA,EACA;AACA,EAAA,MAAM,CAAC,UAAA,EAAY,aAAa,CAAA,GAAI,SAAS,KAAK,CAAA;AAGlD,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,aAAA,CAAc,KAAK,CAAA;AAAA,EACrB,CAAA,EAAG,CAAC,GAAG,CAAC,CAAA;AAER,EAAA,MAAM,WAAA,GAAc,UAAA,IAAc,QAAA,GAAW,QAAA,GAAW,GAAA;AAExD,EAAA,MAAM,WAAA,GAAyD,CAAC,CAAA,KAAM;AACpE,IAAA,aAAA,CAAc,IAAI,CAAA;AAClB,IAAA,OAAA,GAAU,CAAC,CAAA;AAAA,EACb,CAAA;AAEA,EAAA,uBACE,GAAA;AAAA,IAAC,KAAA;AAAA,IAAA;AAAA,MACC,GAAA;AAAA,MACA,GAAA,EAAK,WAAA;AAAA,MACL,GAAA;AAAA,MACA,UAAA,EAAU,GAAA;AAAA,MACV,eAAa,MAAA,IAAU,MAAA;AAAA,MACvB,SAAA,EAAW,CAAC,UAAA,EAAY,SAAS,EAAE,MAAA,CAAO,OAAO,CAAA,CAAE,IAAA,CAAK,GAAG,CAAA;AAAA,MAC3D,OAAO,WAAA,KAAgB,MAAA,GAAY,EAAE,WAAA,EAAa,GAAG,OAAM,GAAI,KAAA;AAAA,MAC/D,OAAA,EAAS,WAAA;AAAA,MACR,GAAG;AAAA;AAAA,GACN;AAEJ;AAEO,IAAM,KAAA,GAAQ,WAAW,UAAU","file":"index.mjs","sourcesContent":["import {\n  type ForwardedRef,\n  type ImgHTMLAttributes,\n  forwardRef,\n  useEffect,\n  useState,\n} from 'react';\nimport './Image.css';\n\nexport type ImageFit = 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';\nexport type ImageRadius = 'sm' | 'md' | 'lg' | 'full';\n\nexport type ImageProps = Omit<ImgHTMLAttributes<HTMLImageElement>, 'alt'> & {\n  alt: string;\n  aspectRatio?: string;\n  fit?: ImageFit;\n  radius?: ImageRadius;\n  fallback?: string;\n};\n\nfunction ImageInner(\n  {\n    alt,\n    aspectRatio,\n    fit = 'cover',\n    radius,\n    fallback,\n    src,\n    className,\n    style,\n    onError,\n    ...restProps\n  }: ImageProps,\n  ref: ForwardedRef<HTMLImageElement>,\n) {\n  const [hasErrored, setHasErrored] = useState(false);\n\n  // biome-ignore lint/correctness/useExhaustiveDependencies: src triggers the reset intentionally, it isn't read in the body\n  useEffect(() => {\n    setHasErrored(false);\n  }, [src]);\n\n  const resolvedSrc = hasErrored && fallback ? fallback : src;\n\n  const handleError: React.ReactEventHandler<HTMLImageElement> = (e) => {\n    setHasErrored(true);\n    onError?.(e);\n  };\n\n  return (\n    <img\n      ref={ref}\n      src={resolvedSrc}\n      alt={alt}\n      data-fit={fit}\n      data-radius={radius || undefined}\n      className={['xd-image', className].filter(Boolean).join(' ')}\n      style={aspectRatio !== undefined ? { aspectRatio, ...style } : style}\n      onError={handleError}\n      {...restProps}\n    />\n  );\n}\n\nexport const Image = forwardRef(ImageInner);\n"]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@asnewyla/image",
+  "version": "0.2.0",
+  "description": "Image display with org styling, aspect ratio, and load-error fallback",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xavierDelaFuente/xd-components.git",
+    "directory": "packages/image"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./styles.css": "./dist/index.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "keywords": [
+    "react",
+    "image",
+    "accessible"
+  ],
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.4.0",
+    "@testing-library/react": "^16.0.0",
+    "@testing-library/user-event": "^14.5.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "jsdom": "^24.0.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "tsup": "^8.1.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "type-check": "tsc --noEmit"
+  }
+}