@angadie/chittie-react 0.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Asyncdot Engineering
+
+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.
+
+Portions of this software are vendored from MIT-licensed projects and retain
+their original copyright notices; see VENDOR.md.
+
+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,104 @@
+# @angadie/chittie-react
+
+Pure JSX receipt authoring → ESC/POS bytes. **RN-safe**: no `react-dom`, no HTML host elements — components render straight onto the [`chittie-core`](../chittie-core) builder, so the same `<Printer>` tree works on web and React Native.
+
+> Most apps install [`@angadie/chittie`](../chittie) (which re-exports this). Install this directly only if you don't want the builder re-export.
+
+## Install
+
+```bash
+pnpm add @angadie/chittie-react react
+```
+
+## Usage
+
+```tsx
+import { Printer, Text, Row, Line, Cut, render } from '@angadie/chittie-react';
+
+const bytes = render(
+  <Printer width={48}>
+    <Text align="center" bold size={{ width: 2, height: 2 }}>SHOP</Text>
+    <Line />
+    <Row left="Item" right="Rs. 100" />
+    <Cut />
+  </Printer>
+);
+// bytes: Uint8Array — hand to any transport
+```
+
+`render(element, options?)` returns a `Uint8Array`. It is synchronous and pure.
+
+## Components
+
+| Component | Props | Emits |
+|---|---|---|
+| `<Printer>` | `width` (columns, default 48) | the root; sets line width |
+| `<Text>` | `align`, `bold`, `underline`, `invert`, `size` ({width,height} multipliers), `inline` | text (or image — see below) + newline |
+| `<Row>` | `left`, `right` | a two-column justified row |
+| `<Line>` | — | a horizontal rule |
+| `<Br>` | `lines` | blank line(s) |
+| `<Cut>` | `partial` | paper cut |
+| `<Cashdraw>` | `device` | cash-drawer kick pulse |
+| `<Barcode>` | `value`, `symbology`, `height` | a barcode |
+| `<QRCode>` | `value`, `size`, `model` | a QR code |
+| `<Image>` | `image` (ImageData), `align`, `dither`, `threshold`, `width`, `height` | a raster image (logo, etc.) |
+
+### `<Image>` — logos and bitmaps
+
+Pass `ImageData` (from a `<canvas>`, a decoded PNG, or a rasterizer). Dimensions are auto-padded to multiples of 8 (the ESC/POS raster requirement), so any size works. Use `dither="threshold"` for crisp line-art/logos, or `floydsteinberg`/`atkinson` for photos.
+
+```tsx
+const logo = canvas.getContext('2d')!.getImageData(0, 0, canvas.width, canvas.height);
+render(
+  <Printer width={48}>
+    <Image image={logo} align="center" dither="threshold" />
+    <Text align="center" bold>ARTISAN HAUS</Text>
+  </Printer>
+);
+```
+
+User-defined wrapper components are supported — `render` walks function components and fragments.
+
+## Custom components
+
+Compose your own components — they're plain functions returning chittie elements. `render` invokes them and walks their output, so `.map()`, fragments, and conditionals all work:
+
+```tsx
+const LineItem = ({ name, qty, price }: Item) => (
+  <Row left={`${qty}x ${name}`} right={`Rs. ${qty * price}`} />
+);
+
+function Receipt({ items }: { items: Item[] }) {
+  return (
+    <Printer width={48}>
+      <Text align="center" bold>MY SHOP</Text>
+      <Line />
+      {items.map((it) => <LineItem key={it.id} {...it} />)}
+      {items.length === 0 && <Text align="center">No items</Text>}
+      <Cut />
+    </Printer>
+  );
+}
+
+// a whole receipt can be ONE component — render resolves it down to <Printer>
+render(<Receipt items={cart} />);
+```
+
+**Constraints** (it's a pure renderer, not the React reconciler):
+- Components must be pure `props → elements`. **No hooks** (`useState`/`useEffect`/`useContext`) and no `react-dom` — there's no component tree, state, or lifecycle, by design (a receipt is a one-shot render).
+- `<Text>` accepts only **text** (strings/numbers). Nesting a component (`<Text><Row/></Text>`) **throws a clear error** — put `<Row>`, `<Image>`, etc. as siblings. (Fragments wrapping text are fine.)
+
+## Non-Latin scripts (Sinhala / Tamil / …)
+
+`<Text>` content that a code page can't represent is auto-rasterized **when you pass a rasterizer**; otherwise `render` throws (never a silent `?`). See [`@angadie/chittie-text`](../chittie-text).
+
+```tsx
+render(<Printer><Text>ආයුබෝවන්</Text></Printer>, {
+  rasterizer: myRasterizer,  // TextRasterizer
+  codepage: 'cp437',         // what counts as "encodable as text"
+});
+```
+
+## License
+
+MIT.

package/dist/index.d.mts

@@ -0,0 +1,132 @@
+import { ReactElement, ReactNode } from "react";
+import { Codepage, Codepage as Codepage$1, RasterOptions, TextRasterizer, TextRasterizer as TextRasterizer$1 } from "@angadie/chittie-text";
+import ReceiptPrinterEncoder, { BarcodeSymbology, DitherAlgorithm } from "@angadie/chittie-core";
+
+//#region src/components.d.ts
+type Alignment = 'left' | 'center' | 'right';
+/** Character magnification (width/height multipliers, e.g. 2 = double). */
+type TextScale = {
+  width: number;
+  height: number;
+};
+/**
+ * Pure recursive text extraction — no react-dom, no DOM. Strings/numbers pass
+ * through; fragments are transparent. A component element is a mistake (it would
+ * be silently dropped — its print() never runs from here), so we throw loudly.
+ */
+declare function toText(node: ReactNode): string;
+interface PrinterProps {
+  /** Printer model passed to the encoder, e.g. 'epson'. */
+  type?: string;
+  /** Characters per line (default 48 / 80mm). */
+  width?: number;
+  children?: ReactNode;
+}
+/** Root element — render() reads its props; it has no print() of its own. */
+declare const Printer: (_props: PrinterProps) => null;
+interface TextProps {
+  align?: Alignment;
+  bold?: boolean;
+  underline?: boolean | number;
+  invert?: boolean;
+  size?: TextScale;
+  /** If true, don't append a newline after the text. */
+  inline?: boolean;
+  children?: ReactNode;
+}
+declare const Text: (_props: TextProps) => null;
+interface RowProps {
+  left?: ReactNode;
+  right?: ReactNode;
+  children?: ReactNode;
+}
+declare const Row: (_props: RowProps) => null;
+declare const Line: (_props: {
+  children?: ReactNode;
+}) => null;
+interface BrProps {
+  lines?: number;
+  children?: ReactNode;
+}
+declare const Br: (_props: BrProps) => null;
+interface CutProps {
+  partial?: boolean;
+  children?: ReactNode;
+}
+declare const Cut: (_props: CutProps) => null;
+interface CashdrawProps {
+  device?: number;
+  children?: ReactNode;
+}
+declare const Cashdraw: (_props: CashdrawProps) => null;
+interface BarcodeProps {
+  value: string;
+  symbology?: BarcodeSymbology | number;
+  height?: number;
+  children?: ReactNode;
+}
+declare const Barcode: (_props: BarcodeProps) => null;
+interface QRCodeProps {
+  value: string;
+  size?: number;
+  model?: number;
+  children?: ReactNode;
+}
+declare const QRCode: (_props: QRCodeProps) => null;
+interface ImageProps {
+  /** Pixel data (from a <canvas>, decoded PNG, or a rasterizer). */
+  image: ImageData;
+  /** Output width/height in dots; default the image's own (padded to /8). */
+  width?: number;
+  height?: number;
+  align?: Alignment;
+  /** Dithering: 'threshold' (crisp line-art/logos) | 'bayer' | 'floydsteinberg' | 'atkinson' (photos). */
+  dither?: DitherAlgorithm;
+  threshold?: number;
+  children?: ReactNode;
+}
+declare const Image: (_props: ImageProps) => null;
+//#endregion
+//#region src/render.d.ts
+interface RenderOptions {
+  /** Characters per line; overridden by <Printer width>. */
+  columns?: number;
+  /** Printable width in dots; defaults to columns × 12 (203 DPI, font A). */
+  dotWidth?: number;
+  /** Supply to print non-encodable scripts (Sinhala/Tamil/…) as images. */
+  rasterizer?: TextRasterizer$1;
+  /** Code page used to decide what's encodable as text (default cp437). */
+  codepage?: Codepage$1;
+}
+/** Common thermal printer profiles: characters/line + printable dot width (203 DPI). */
+declare const PRINTER_PROFILES: {
+  readonly '58mm': {
+    readonly columns: 32;
+    readonly dotWidth: 384;
+  };
+  readonly '80mm': {
+    readonly columns: 48;
+    readonly dotWidth: 576;
+  };
+};
+/**
+ * Render a <Printer> element tree to ESC/POS bytes by driving the vendored
+ * builder. Pure: no react-dom, no DOM host elements.
+ */
+declare function render(element: ReactElement, options?: RenderOptions): Uint8Array;
+//#endregion
+//#region src/printable.d.ts
+/** The vendored builder instance the components drive. */
+type Encoder = InstanceType<typeof ReceiptPrinterEncoder>;
+/** Render-time context threaded to every component's print(). */
+interface RenderContext {
+  columns: number;
+  /** Printable width in dots (e.g. 384 for 58mm, 576 for 80mm) — used when rasterizing. */
+  dotWidth: number;
+  /** When set, <Text>/<Row> with non-encodable scripts (Sinhala/Tamil/…) is rasterized. */
+  rasterizer?: TextRasterizer$1;
+  /** Code page used to decide what's encodable as text (default cp437). */
+  codepage?: Codepage$1;
+}
+//#endregion
+export { type Alignment, Barcode, type BarcodeProps, Br, type BrProps, Cashdraw, type CashdrawProps, type Codepage, Cut, type CutProps, type Encoder, Image, type ImageProps, Line, PRINTER_PROFILES, Printer, type PrinterProps, QRCode, type QRCodeProps, type RasterOptions, type RenderContext, type RenderOptions, Row, type RowProps, Text, type TextProps, type TextRasterizer, type TextScale, render, toText };

package/dist/index.mjs

@@ -0,0 +1,157 @@
+import { Children, Fragment, isValidElement } from "react";
+import { needsRaster, padTo8, rasterizeRow, smartText } from "@angadie/chittie-text";
+import ReceiptPrinterEncoder from "@angadie/chittie-core";
+//#region src/components.ts
+/**
+* Pure recursive text extraction — no react-dom, no DOM. Strings/numbers pass
+* through; fragments are transparent. A component element is a mistake (it would
+* be silently dropped — its print() never runs from here), so we throw loudly.
+*/
+function toText(node) {
+	if (node == null || typeof node === "boolean") return "";
+	if (typeof node === "string") return node;
+	if (typeof node === "number" || typeof node === "bigint") return String(node);
+	if (Array.isArray(node)) return node.map(toText).join("");
+	if (isValidElement(node)) {
+		if (node.type === Fragment) return toText(node.props.children);
+		throw new Error("chittie: <Text> (and <Row>) accept only string/number text, not components. Put <Row>, <Image>, etc. as siblings — not nested inside <Text>.");
+	}
+	return "";
+}
+const printable = (fn) => {
+	const comp = (_props) => null;
+	comp.print = fn;
+	return comp;
+};
+/** Root element — render() reads its props; it has no print() of its own. */
+const Printer = (_props) => null;
+const Text = printable((e, p, ctx) => {
+	if (p.align) e.align(p.align);
+	if (p.bold) e.bold(true);
+	if (p.underline) e.underline(p.underline);
+	if (p.invert) e.invert(true);
+	if (p.size) e.size(p.size.width, p.size.height);
+	smartText(e, toText(p.children), {
+		rasterizer: ctx.rasterizer,
+		codepage: ctx.codepage,
+		raster: {
+			bold: p.bold,
+			fontSize: p.size ? p.size.height * 24 : void 0,
+			maxWidth: ctx.dotWidth
+		}
+	});
+	if (!p.inline) e.newline();
+	if (p.size) e.size(1, 1);
+	if (p.invert) e.invert(false);
+	if (p.underline) e.underline(false);
+	if (p.bold) e.bold(false);
+	if (p.align) e.align("left");
+});
+const Row = printable((e, p, ctx) => {
+	const left = toText(p.left);
+	const right = toText(p.right);
+	if (needsRaster(left, ctx.codepage) || needsRaster(right, ctx.codepage)) {
+		if (!ctx.rasterizer) throw new Error("chittie: <Row> contains non-encodable text (e.g. Sinhala/Tamil). Pass a rasterizer to render(), or use code-page text.");
+		const img = rasterizeRow(ctx.rasterizer, left, right, { dotWidth: ctx.dotWidth });
+		e.image(img, img.width, img.height);
+		return;
+	}
+	const rightW = Math.min(right.length, ctx.columns);
+	const leftW = Math.max(0, ctx.columns - rightW);
+	e.table([{
+		width: leftW,
+		align: "left"
+	}, {
+		width: rightW,
+		align: "right"
+	}], [[left, right]]);
+});
+const Line = printable((e) => {
+	e.rule();
+});
+const Br = printable((e, p) => {
+	e.newline(p.lines ?? 1);
+});
+const Cut = printable((e, p) => {
+	e.cut(p.partial ? "partial" : "full");
+});
+const Cashdraw = printable((e, p) => {
+	e.pulse(p.device);
+});
+const Barcode = printable((e, p) => {
+	e.barcode(p.value, p.symbology ?? "code128", p.height);
+});
+const QRCode = printable((e, p) => {
+	e.qrcode(p.value, p.model, p.size);
+});
+const Image = printable((e, p) => {
+	const img = padTo8(p.image);
+	if (p.align) e.align(p.align);
+	e.image(img, p.width ?? img.width, p.height ?? img.height, p.dither, p.threshold);
+	if (p.align) e.align("left");
+});
+//#endregion
+//#region src/printable.ts
+function isPrintable(type) {
+	return (typeof type === "function" || typeof type === "object") && type !== null && typeof type.print === "function";
+}
+//#endregion
+//#region src/render.ts
+/**
+* Resolve a custom function-component root down to the <Printer> element it
+* returns, so a whole receipt can be authored as one component:
+* `render(<MyReceipt items={…} />)`. Stops at <Printer> or any printable.
+*/
+function resolveRoot(element) {
+	let current = element;
+	for (let i = 0; i < 100; i++) {
+		if (!isValidElement(current)) break;
+		const type = current.type;
+		if (type === Printer || isPrintable(type) || typeof type !== "function") break;
+		current = type(current.props);
+	}
+	return isValidElement(current) ? current : element;
+}
+/** Common thermal printer profiles: characters/line + printable dot width (203 DPI). */
+const PRINTER_PROFILES = {
+	"58mm": {
+		columns: 32,
+		dotWidth: 384
+	},
+	"80mm": {
+		columns: 48,
+		dotWidth: 576
+	}
+};
+/**
+* Render a <Printer> element tree to ESC/POS bytes by driving the vendored
+* builder. Pure: no react-dom, no DOM host elements.
+*/
+function render(element, options = {}) {
+	const props = resolveRoot(element).props ?? {};
+	const columns = props.width ?? options.columns ?? 48;
+	const dotWidth = options.dotWidth ?? columns * 12;
+	const encoder = new ReceiptPrinterEncoder({ columns });
+	encoder.initialize();
+	walk(props.children, encoder, {
+		columns,
+		dotWidth,
+		rasterizer: options.rasterizer,
+		codepage: options.codepage
+	});
+	return encoder.encode();
+}
+function walk(node, encoder, ctx) {
+	for (const child of Children.toArray(node)) {
+		if (!isValidElement(child)) continue;
+		const type = child.type;
+		if (isPrintable(type)) {
+			type.print(encoder, child.props ?? {}, ctx);
+			continue;
+		}
+		if (typeof type === "function") walk(type(child.props), encoder, ctx);
+		else walk(child.props.children, encoder, ctx);
+	}
+}
+//#endregion
+export { Barcode, Br, Cashdraw, Cut, Image, Line, PRINTER_PROFILES, Printer, QRCode, Row, Text, render, toText };

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@angadie/chittie-react",
+  "version": "0.1.0",
+  "description": "Pure JSX receipt authoring → ESC/POS bytes. RN-safe (no react-dom, no HTML host elements). Renders onto chittie-core.",
+  "license": "MIT",
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@angadie/chittie-core": "0.1.0",
+    "@angadie/chittie-text": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "devDependencies": {
+    "@canvas/image-data": "^1.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx spikes/jsx.spike.tsx"
+  }
+}