@lettermark/react 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @lettermark/react
+
+> Scalable SVG avatar fallback for React — initials, deterministic colors, image fallback chain.
+
+[![npm version](https://img.shields.io/npm/v/@lettermark/react.svg)](https://www.npmjs.com/package/@lettermark/react)
+[![minzipped size](https://img.shields.io/bundlephobia/minzip/@lettermark/react)](https://bundlephobia.com/package/@lettermark/react)
+[![license](https://img.shields.io/npm/l/@lettermark/react.svg)](https://github.com/tomaszbilka/lettermark/blob/main/LICENSE)
+
+React component built on [`lettermark`](https://www.npmjs.com/package/lettermark) core — drop-in avatar fallback for user lists, nav bars and profile placeholders. No CSS file to import.
+
+## Features
+
+- **Grapheme-correct initials** — powered by `Intl.Segmenter` via core; emoji, flags and CJK names stay intact.
+- **Deterministic, WCAG-safe colors** — same name → same color; foreground picked for AA contrast (≥ 4.5:1).
+- **SSR-safe** — identical server and client markup for initials; no hydration mismatch from color or text logic.
+- **Lightweight** — ~0.9 kB gzipped; React is a peer dependency (not bundled into your app).
+
+## Install
+
+```bash
+npm install @lettermark/react
+# peer: react >=18, react-dom >=18 (already in your app)
+```
+
+`lettermark` is installed automatically as a dependency. React is **not** bundled — your app supplies it via `peerDependencies`.
+
+## Quick start
+
+```tsx
+import { Lettermark } from "@lettermark/react";
+
+export function UserAvatar({ name }: { name: string }) {
+  return <Lettermark name={name} size={40} />;
+}
+```
+
+With image fallback:
+
+```tsx
+<Lettermark name="Jan Kowalski" src={user.avatarUrl} size={48} shape="rounded" loading="lazy" />
+```
+
+Initials render immediately; the image overlays on load. On error, initials stay visible.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | — | Source for initials and color |
+| `src` | `string?` | — | Image URL; falls back to initials on error |
+| `size` | `number \| string?` | fluid | `40` → px, `"3rem"` → CSS; omit → `100%` of parent (parent needs explicit dimensions; root uses `aspect-ratio: 1/1`) |
+| `shape` | `'circle' \| 'square' \| 'rounded' \| 'squircle'` | `'circle'` | Avatar shape |
+| `color` | `string?` | auto | Fixed background hex |
+| `palette` | `string[]?` | auto | Brand colors — picked deterministically |
+| `className` / `style` | — | — | Root styling |
+| `classNames` | `{ root?, image?, initials? }` | — | Per-element classes (Tailwind-friendly) |
+| `alt` | `string?` | `name` | Accessible label (`aria-label`) |
+| `title` | `string?` | — | Native tooltip |
+| `as` | `ElementType` | `'span'` | Polymorphic root (`button`, `div`, …) |
+| `loading` | `img loading` | — | Passed to `<img>` (`"lazy"` / `"eager"`) |
+| `fallback` | `ReactNode?` | — | Replaces initials SVG when no image is shown (`src` still takes priority when it loads) |
+| `length` | `1 \| 2 \| 3` | `2` | Max initials (from core) |
+| `locale` | `string?` | — | `Intl.Segmenter` locale |
+| `fontSize` | `number?` | auto | Override SVG font size on 100×100 canvas |
+
+Spread props (`onClick`, etc.) go to the root element.
+
+## Examples
+
+**Fluid — fills parent container:**
+
+```tsx
+<div style={{ width: 64, height: 64 }}>
+  <Lettermark name="Jan Kowalski" />
+</div>
+```
+
+**Next.js App Router:**
+
+```tsx
+"use client";
+
+import { Lettermark } from "@lettermark/react";
+
+<Lettermark name={user.name} size={40} src={user.avatarUrl} />;
+```
+
+**Button avatar:**
+
+```tsx
+<Lettermark as="button" name="Jan Kowalski" size={32} type="button" onClick={openProfile} />
+```
+
+**Custom fallback:**
+
+```tsx
+<Lettermark name="" fallback={<span>?</span>} size={40} />
+```
+
+## License
+
+[MIT](https://github.com/tomaszbilka/lettermark/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+import * as react0 from "react";
+import { CSSProperties, ComponentPropsWithoutRef, ElementType, ReactNode } from "react";
+
+//#region src/lettermark.d.ts
+type LettermarkShape = "circle" | "square" | "rounded" | "squircle";
+interface LettermarkClassNames {
+  root?: string;
+  image?: string;
+  initials?: string;
+}
+type Size = number | string | undefined;
+interface LettermarkOwnProps {
+  /** Full name — source for initials and deterministic color. */
+  name: string;
+  /** Optional image URL; falls back to initials on load error. */
+  src?: string;
+  /** Fixed px, CSS units, or omit for fluid (100% of parent). */
+  size?: Size;
+  shape?: LettermarkShape;
+  /** Fixed background color (hex). Overrides auto-generated hue. */
+  color?: string;
+  /** Brand palette — background picked deterministically from these colors. */
+  palette?: string[];
+  className?: string;
+  style?: CSSProperties;
+  classNames?: LettermarkClassNames;
+  /** Accessible label; defaults to `name`. */
+  alt?: string;
+  /** Native tooltip with the full name. */
+  title?: string;
+  loading?: ComponentPropsWithoutRef<"img">["loading"];
+  /** Custom content when no image is shown; replaces default initials SVG. */
+  fallback?: ReactNode;
+  length?: 1 | 2 | 3;
+  locale?: string;
+  fontSize?: number;
+}
+type LettermarkProps<C extends ElementType = "span"> = LettermarkOwnProps & {
+  as?: C;
+} & Omit<ComponentPropsWithoutRef<C>, keyof LettermarkOwnProps | "as" | "children">;
+declare function Lettermark<C extends ElementType = "span">({
+  as,
+  name,
+  src,
+  size,
+  shape,
+  color,
+  palette,
+  className,
+  style,
+  classNames,
+  alt,
+  title,
+  loading,
+  fallback,
+  length,
+  locale,
+  fontSize,
+  ...rest
+}: LettermarkProps<C>): react0.JSX.Element;
+//#endregion
+export { Lettermark, type LettermarkClassNames, type LettermarkOwnProps, type LettermarkProps, type LettermarkShape };

package/dist/index.js

@@ -0,0 +1 @@
+import{getLettermark as e}from"lettermark";import{useState as t}from"react";import{jsx as n,jsxs as r}from"react/jsx-runtime";const i={square:0,rounded:16,squircle:28},a={circle:`50%`,square:`0`,rounded:`16%`,squircle:`28%`};function o(e){return typeof e==`number`?`${e}px`:typeof e==`string`?e:`100%`}function s({shape:e,background:t,foreground:a,fontSize:o,initials:s,className:c}){return r(`svg`,{viewBox:`0 0 100 100`,className:c,style:{display:`block`,width:`100%`,height:`100%`},"aria-hidden":`true`,focusable:`false`,children:[e===`circle`?n(`circle`,{cx:`50`,cy:`50`,r:`50`,fill:t}):n(`rect`,{width:`100`,height:`100`,rx:i[e],fill:t}),n(`text`,{x:`50`,y:`50`,dy:`0.36em`,textAnchor:`middle`,fill:a,fontSize:o,fontFamily:`inherit`,fontWeight:600,children:s})]})}function c({as:i,name:c,src:l,size:u,shape:d=`circle`,color:f,palette:p,className:m,style:h,classNames:g,alt:_,title:v,loading:y,fallback:b,length:x,locale:S,fontSize:C,...w}){let T=i??`span`,[E,D]=t(null),[O,k]=t(null),{initials:A,background:j,foreground:M,fontSize:N}=e(c,{length:x,locale:S,fontSize:C,palette:p??(f?[f]:void 0)}),P=b!=null&&(!l||O===l),F=b==null,I=!!l&&O!==l,L=!!l&&E===l,R={display:`inline-block`,width:o(u),height:o(u),aspectRatio:u===void 0?`1 / 1`:void 0,position:`relative`,overflow:`hidden`,borderRadius:a[d],...h};return r(T,{role:`img`,"aria-label":_??c,title:v,"data-shape":d,className:g?.root??m,style:R,...w,children:[F&&n(s,{shape:d,background:j,foreground:M,fontSize:N,initials:A,className:g?.initials}),P&&b,I&&n(`img`,{src:l,alt:``,loading:y,onLoad:()=>D(l??null),onError:()=>k(l??null),className:g?.image,style:{position:`absolute`,inset:0,width:`100%`,height:`100%`,objectFit:`cover`,opacity:L?1:0}},l)]})}export{c as Lettermark};

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@lettermark/react",
+  "version": "0.1.0",
+  "description": "Scalable SVG avatar fallback component for React — initials, deterministic colors, image fallback chain.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "react",
+    "react-component",
+    "avatar",
+    "avatar-fallback",
+    "initials",
+    "monogram",
+    "lettermark",
+    "placeholder",
+    "fallback",
+    "svg"
+  ],
+  "author": "tomaszbilka",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tomaszbilka/lettermark.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/tomaszbilka/lettermark/issues"
+  },
+  "homepage": "https://github.com/tomaszbilka/lettermark/tree/main/packages/react#readme",
+  "dependencies": {
+    "lettermark": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}