@blobz/react 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# @blobz/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The React component library for Blobz. It renders deterministic, name-generated
+avatars and explicit custom faces.
+
+## Usage
+
+```tsx
+import { Avatar } from "@blobz/react";
+
+export function Profile() {
+  return (
+    <Avatar
+      name="Ada Lovelace"
+      palette={["#f2f1f4", "#7c6cf2"]}
+      frame="rounded"
+      size={64}
+    />
+  );
+}
+```
+
+The component forwards standard image props and its ref to the underlying
+`HTMLImageElement`:
+
+```tsx
+<Avatar
+  name={user.id}
+  alt={`${user.name}'s avatar`}
+  className="rounded-xl"
+  loading="lazy"
+  size="3rem"
+/>
+```
+
+Pass an empty `alt` string when the image is decorative.
+
+## Custom faces
+
+`CustomAvatar` renders a complete semantic definition without using a name to
+choose any facial feature:
+
+```tsx
+import { CustomAvatar } from "@blobz/react/custom";
+
+const definition = {
+  type: "custom",
+  version: 1,
+  frame: "circle",
+  palette: ["#ffffff", "#12b76a"],
+  choices: {
+    shape: "leaf",
+    eyes: "distorted",
+    look: "centre",
+    eyeSpacing: "medium",
+    mouth: "wide smile",
+    brows: "quizzical",
+    mirrored: false,
+    faceAngle: 2,
+    bodyTilt: -4,
+    facePosition: { x: 1, y: 0 },
+  },
+} as const;
+
+<CustomAvatar definition={definition} size={64} />;
+```

package/dist/avatar.d.ts

@@ -0,0 +1,23 @@
+import * as react from 'react';
+import { ComponentPropsWithRef, CSSProperties } from 'react';
+import { AvatarChoiceOverrides, AvatarFrame, AvatarPalette } from '@blobz/avatar-core';
+
+type AvatarSize = CSSProperties["width"];
+declare const createAvatarDataUri: (svg: string) => string;
+interface AvatarProps extends Omit<ComponentPropsWithRef<"img">, "alt" | "children" | "height" | "src" | "width"> {
+    /** Accessible image description. Pass an empty string for a decorative avatar. */
+    readonly alt?: string;
+    /** Zero-based selections used to pin individual facial features. */
+    readonly choices?: AvatarChoiceOverrides | null;
+    /** Shape of the avatar's outer crop. */
+    readonly frame?: AvatarFrame;
+    /** Stable value used to deterministically generate the face. */
+    readonly name: string | number;
+    /** Background and body colours, in that order. */
+    readonly palette?: AvatarPalette;
+    /** Square rendered size. Defaults to 80 pixels. */
+    readonly size?: AvatarSize;
+}
+declare function Avatar({ alt, choices, decoding, draggable, frame, name, palette, ref, size, style, ...imageProps }: AvatarProps): react.JSX.Element;
+
+export { Avatar, type AvatarProps, type AvatarSize, createAvatarDataUri };

package/dist/avatar.js

@@ -0,0 +1,46 @@
+import {
+  AvatarImage
+} from "./chunk-DU7BH2AL.js";
+
+// src/avatar.tsx
+import {
+  DEFAULT_AVATAR_PALETTE,
+  makeAvatar
+} from "@blobz/avatar-core";
+import { jsx } from "react/jsx-runtime";
+var createAvatarDataUri = (svg) => `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+function Avatar({
+  alt,
+  choices = null,
+  decoding = "async",
+  draggable = false,
+  frame = "rounded",
+  name,
+  palette = DEFAULT_AVATAR_PALETTE,
+  ref,
+  size = 80,
+  style,
+  ...imageProps
+}) {
+  const avatar = makeAvatar(name, palette, frame, choices);
+  return /* @__PURE__ */ jsx(
+    AvatarImage,
+    {
+      ...imageProps,
+      alt: alt ?? `Blob avatar for ${avatar.key}`,
+      decoding,
+      draggable,
+      fallbackAlt: `Blob avatar for ${avatar.key}`,
+      ref,
+      size,
+      source: "generated",
+      style,
+      svg: avatar.svg
+    }
+  );
+}
+export {
+  Avatar,
+  createAvatarDataUri
+};
+//# sourceMappingURL=avatar.js.map

package/dist/avatar.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/avatar.tsx"],"sourcesContent":["import {\n\ttype AvatarChoiceOverrides,\n\ttype AvatarFrame,\n\ttype AvatarPalette,\n\ttype AvatarResult,\n\tDEFAULT_AVATAR_PALETTE,\n\tmakeAvatar,\n} from \"@blobz/avatar-core\";\nimport type { ComponentPropsWithRef, CSSProperties } from \"react\";\nimport { AvatarImage } from \"./avatar-image\";\n\nexport type AvatarSize = CSSProperties[\"width\"];\n\nexport const createAvatarDataUri = (svg: string): string =>\n\t`data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;\n\nexport interface AvatarProps\n\textends Omit<\n\t\tComponentPropsWithRef<\"img\">,\n\t\t\"alt\" | \"children\" | \"height\" | \"src\" | \"width\"\n\t> {\n\t/** Accessible image description. Pass an empty string for a decorative avatar. */\n\treadonly alt?: string;\n\t/** Zero-based selections used to pin individual facial features. */\n\treadonly choices?: AvatarChoiceOverrides | null;\n\t/** Shape of the avatar's outer crop. */\n\treadonly frame?: AvatarFrame;\n\t/** Stable value used to deterministically generate the face. */\n\treadonly name: string | number;\n\t/** Background and body colours, in that order. */\n\treadonly palette?: AvatarPalette;\n\t/** Square rendered size. Defaults to 80 pixels. */\n\treadonly size?: AvatarSize;\n}\n\nexport function Avatar({\n\talt,\n\tchoices = null,\n\tdecoding = \"async\",\n\tdraggable = false,\n\tframe = \"rounded\",\n\tname,\n\tpalette = DEFAULT_AVATAR_PALETTE,\n\tref,\n\tsize = 80,\n\tstyle,\n\t...imageProps\n}: AvatarProps) {\n\tconst avatar: AvatarResult = makeAvatar(name, palette, frame, choices);\n\n\treturn (\n\t\t<AvatarImage\n\t\t\t{...imageProps}\n\t\t\talt={alt ?? `Blob avatar for ${avatar.key}`}\n\t\t\tdecoding={decoding}\n\t\t\tdraggable={draggable}\n\t\t\tfallbackAlt={`Blob avatar for ${avatar.key}`}\n\t\t\tref={ref}\n\t\t\tsize={size}\n\t\t\tsource=\"generated\"\n\t\t\tstyle={style}\n\t\t\tsvg={avatar.svg}\n\t\t/>\n\t);\n}\n"],"mappings":";;;;;AAAA;AAAA,EAKC;AAAA,EACA;AAAA,OACM;AA4CL;AAtCK,IAAM,sBAAsB,CAAC,QACnC,oCAAoC,mBAAmB,GAAG,CAAC;AAqBrD,SAAS,OAAO;AAAA,EACtB;AAAA,EACA,UAAU;AAAA,EACV,WAAW;AAAA,EACX,YAAY;AAAA,EACZ,QAAQ;AAAA,EACR;AAAA,EACA,UAAU;AAAA,EACV;AAAA,EACA,OAAO;AAAA,EACP;AAAA,EACA,GAAG;AACJ,GAAgB;AACf,QAAM,SAAuB,WAAW,MAAM,SAAS,OAAO,OAAO;AAErE,SACC;AAAA,IAAC;AAAA;AAAA,MACC,GAAG;AAAA,MACJ,KAAK,OAAO,mBAAmB,OAAO,GAAG;AAAA,MACzC;AAAA,MACA;AAAA,MACA,aAAa,mBAAmB,OAAO,GAAG;AAAA,MAC1C;AAAA,MACA;AAAA,MACA,QAAO;AAAA,MACP;AAAA,MACA,KAAK,OAAO;AAAA;AAAA,EACb;AAEF;","names":[]}

package/dist/chunk-DU7BH2AL.js

@@ -0,0 +1,41 @@
+// src/avatar-image.tsx
+import { jsx } from "react/jsx-runtime";
+var createAvatarDataUri = (svg) => `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+function AvatarImage({
+  alt,
+  decoding = "async",
+  draggable = false,
+  fallbackAlt,
+  ref,
+  size = 80,
+  source,
+  style,
+  svg,
+  ...imageProps
+}) {
+  const numericSize = typeof size === "number" ? size : void 0;
+  return (
+    // biome-ignore lint/performance/noImgElement: Blobz renders an in-memory SVG data URI that image optimizers cannot improve.
+    /* @__PURE__ */ jsx(
+      "img",
+      {
+        ...imageProps,
+        alt: alt ?? fallbackAlt,
+        "data-blobz-avatar": "",
+        "data-blobz-source": source,
+        decoding,
+        draggable,
+        height: numericSize,
+        ref,
+        src: createAvatarDataUri(svg),
+        style: { height: size, width: size, ...style },
+        width: numericSize
+      }
+    )
+  );
+}
+
+export {
+  AvatarImage
+};
+//# sourceMappingURL=chunk-DU7BH2AL.js.map

package/dist/chunk-DU7BH2AL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/avatar-image.tsx"],"sourcesContent":["import type { ComponentPropsWithRef, CSSProperties } from \"react\";\n\nexport type AvatarSize = CSSProperties[\"width\"];\n\nexport interface AvatarImageProps\n\textends Omit<\n\t\tComponentPropsWithRef<\"img\">,\n\t\t\"alt\" | \"children\" | \"height\" | \"src\" | \"width\"\n\t> {\n\treadonly alt?: string;\n\treadonly fallbackAlt: string;\n\treadonly size?: AvatarSize;\n\treadonly source: \"custom\" | \"generated\";\n\treadonly svg: string;\n}\n\nexport const createAvatarDataUri = (svg: string): string =>\n\t`data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;\n\nexport function AvatarImage({\n\talt,\n\tdecoding = \"async\",\n\tdraggable = false,\n\tfallbackAlt,\n\tref,\n\tsize = 80,\n\tsource,\n\tstyle,\n\tsvg,\n\t...imageProps\n}: AvatarImageProps) {\n\tconst numericSize = typeof size === \"number\" ? size : undefined;\n\n\treturn (\n\t\t// biome-ignore lint/performance/noImgElement: Blobz renders an in-memory SVG data URI that image optimizers cannot improve.\n\t\t<img\n\t\t\t{...imageProps}\n\t\t\talt={alt ?? fallbackAlt}\n\t\t\tdata-blobz-avatar=\"\"\n\t\t\tdata-blobz-source={source}\n\t\t\tdecoding={decoding}\n\t\t\tdraggable={draggable}\n\t\t\theight={numericSize}\n\t\t\tref={ref}\n\t\t\tsrc={createAvatarDataUri(svg)}\n\t\t\tstyle={{ height: size, width: size, ...style }}\n\t\t\twidth={numericSize}\n\t\t/>\n\t);\n}\n"],"mappings":";AAmCE;AAnBK,IAAM,sBAAsB,CAAC,QACnC,oCAAoC,mBAAmB,GAAG,CAAC;AAErD,SAAS,YAAY;AAAA,EAC3B;AAAA,EACA,WAAW;AAAA,EACX,YAAY;AAAA,EACZ;AAAA,EACA;AAAA,EACA,OAAO;AAAA,EACP;AAAA,EACA;AAAA,EACA;AAAA,EACA,GAAG;AACJ,GAAqB;AACpB,QAAM,cAAc,OAAO,SAAS,WAAW,OAAO;AAEtD;AAAA;AAAA,IAEC;AAAA,MAAC;AAAA;AAAA,QACC,GAAG;AAAA,QACJ,KAAK,OAAO;AAAA,QACZ,qBAAkB;AAAA,QAClB,qBAAmB;AAAA,QACnB;AAAA,QACA;AAAA,QACA,QAAQ;AAAA,QACR;AAAA,QACA,KAAK,oBAAoB,GAAG;AAAA,QAC5B,OAAO,EAAE,QAAQ,MAAM,OAAO,MAAM,GAAG,MAAM;AAAA,QAC7C,OAAO;AAAA;AAAA,IACR;AAAA;AAEF;","names":[]}

package/dist/custom-avatar.d.ts

@@ -0,0 +1,18 @@
+import * as react from 'react';
+import { CSSProperties, ComponentPropsWithRef } from 'react';
+import { CustomAvatarDefinition } from '@blobz/avatar-core';
+
+type AvatarSize = CSSProperties["width"];
+
+type CustomAvatarValue = CustomAvatarDefinition;
+interface CustomAvatarProps extends Omit<ComponentPropsWithRef<"img">, "alt" | "children" | "height" | "src" | "width"> {
+    /** Accessible image description. Pass an empty string for a decorative avatar. */
+    readonly alt?: string;
+    /** Complete, serializable face definition. */
+    readonly definition: CustomAvatarDefinition;
+    /** Square rendered size. Defaults to 80 pixels. */
+    readonly size?: AvatarSize;
+}
+declare function CustomAvatar({ alt, decoding, definition, draggable, ref, size, style, ...imageProps }: CustomAvatarProps): react.JSX.Element;
+
+export { CustomAvatar, type CustomAvatarProps, type CustomAvatarValue };

package/dist/custom-avatar.js

@@ -0,0 +1,40 @@
+import {
+  AvatarImage
+} from "./chunk-DU7BH2AL.js";
+
+// src/custom-avatar.tsx
+import {
+  createCustomAvatar
+} from "@blobz/avatar-core";
+import { jsx } from "react/jsx-runtime";
+function CustomAvatar({
+  alt,
+  decoding = "async",
+  definition,
+  draggable = false,
+  ref,
+  size = 80,
+  style,
+  ...imageProps
+}) {
+  const avatar = createCustomAvatar(definition);
+  return /* @__PURE__ */ jsx(
+    AvatarImage,
+    {
+      ...imageProps,
+      alt,
+      decoding,
+      draggable,
+      fallbackAlt: "Custom blob avatar",
+      ref,
+      size,
+      source: "custom",
+      style,
+      svg: avatar.svg
+    }
+  );
+}
+export {
+  CustomAvatar
+};
+//# sourceMappingURL=custom-avatar.js.map

package/dist/custom-avatar.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/custom-avatar.tsx"],"sourcesContent":["import {\n\ttype CustomAvatarDefinition,\n\ttype CustomAvatarResult,\n\tcreateCustomAvatar,\n} from \"@blobz/avatar-core\";\nimport type { ComponentPropsWithRef } from \"react\";\nimport { AvatarImage, type AvatarSize } from \"./avatar-image\";\n\nexport type CustomAvatarValue = CustomAvatarDefinition;\n\nexport interface CustomAvatarProps\n\textends Omit<\n\t\tComponentPropsWithRef<\"img\">,\n\t\t\"alt\" | \"children\" | \"height\" | \"src\" | \"width\"\n\t> {\n\t/** Accessible image description. Pass an empty string for a decorative avatar. */\n\treadonly alt?: string;\n\t/** Complete, serializable face definition. */\n\treadonly definition: CustomAvatarDefinition;\n\t/** Square rendered size. Defaults to 80 pixels. */\n\treadonly size?: AvatarSize;\n}\n\nexport function CustomAvatar({\n\talt,\n\tdecoding = \"async\",\n\tdefinition,\n\tdraggable = false,\n\tref,\n\tsize = 80,\n\tstyle,\n\t...imageProps\n}: CustomAvatarProps) {\n\tconst avatar: CustomAvatarResult = createCustomAvatar(definition);\n\n\treturn (\n\t\t<AvatarImage\n\t\t\t{...imageProps}\n\t\t\talt={alt}\n\t\t\tdecoding={decoding}\n\t\t\tdraggable={draggable}\n\t\t\tfallbackAlt=\"Custom blob avatar\"\n\t\t\tref={ref}\n\t\t\tsize={size}\n\t\t\tsource=\"custom\"\n\t\t\tstyle={style}\n\t\t\tsvg={avatar.svg}\n\t\t/>\n\t);\n}\n"],"mappings":";;;;;AAAA;AAAA,EAGC;AAAA,OACM;AAgCL;AAbK,SAAS,aAAa;AAAA,EAC5B;AAAA,EACA,WAAW;AAAA,EACX;AAAA,EACA,YAAY;AAAA,EACZ;AAAA,EACA,OAAO;AAAA,EACP;AAAA,EACA,GAAG;AACJ,GAAsB;AACrB,QAAM,SAA6B,mBAAmB,UAAU;AAEhE,SACC;AAAA,IAAC;AAAA;AAAA,MACC,GAAG;AAAA,MACJ;AAAA,MACA;AAAA,MACA;AAAA,MACA,aAAY;AAAA,MACZ;AAAA,MACA;AAAA,MACA,QAAO;AAAA,MACP;AAAA,MACA,KAAK,OAAO;AAAA;AAAA,EACb;AAEF;","names":[]}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@blobz/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "React components for generated and custom Blobz avatars.",
+  "keywords": [
+    "avatar",
+    "blob",
+    "react",
+    "svg"
+  ],
+  "homepage": "https://blobz.lirena.in",
+  "bugs": {
+    "url": "https://github.com/lirena00/blobz/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lirena00/blobz.git",
+    "directory": "packages/react"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/avatar.d.ts",
+      "import": "./dist/avatar.js",
+      "default": "./dist/avatar.js"
+    },
+    "./custom": {
+      "types": "./dist/custom-avatar.d.ts",
+      "import": "./dist/custom-avatar.js",
+      "default": "./dist/custom-avatar.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/avatar.tsx src/custom-avatar.tsx --format esm --dts --clean --sourcemap --external react --external @blobz/avatar-core",
+    "check-types": "tsc --noEmit",
+    "prepublishOnly": "bun run check-types && bun run test && bun run build",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@blobz/avatar-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@blobz/config": "0.0.0",
+    "@types/node": "^26.4.1",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}