feat(#29): add GS1 Composite barcodes (CC-A, CC-B, CC-C)

- encodeGS1Composite() — supplemental 2D component for 1D barcodes
- CC-A: MicroPDF417 (2 col), CC-B: MicroPDF417 (3 col), CC-C: PDF417
- AI data validation via GS1-128 parser
- 7 tests added

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: productdevbook

src/encoders/gs1-composite.ts

@@ -0,0 +1,76 @@
+/**
+ * GS1 Composite Component encoder
+ * Adds supplemental 2D component to a primary 1D barcode
+ *
+ * CC-A: MicroPDF417-based, small capacity
+ * CC-B: MicroPDF417-based, medium capacity
+ * CC-C: PDF417-based, large capacity
+ *
+ * The composite component encodes additional GS1 AI data
+ * that doesn't fit in the primary linear barcode.
+ */
+
+import { InvalidInputError } from "../errors";
+import { encodeMicroPDF417 } from "./micropdf417";
+import { encodePDF417 } from "./pdf417/index";
+import { parseAIString } from "./gs1-128";
+
+export type CompositeType = "CC-A" | "CC-B" | "CC-C";
+
+export interface GS1CompositeResult {
+  /** The 2D composite component matrix */
+  composite: boolean[][];
+  /** Composite type used */
+  type: CompositeType;
+  /** Number of rows in composite */
+  rows: number;
+  /** Width in modules */
+  cols: number;
+}
+
+/**
+ * Encode GS1 Composite Component
+ * Input: AI string in parenthesized format
+ *
+ * @param data - GS1 AI data for composite (e.g., "(17)260101(10)BATCH01")
+ * @param type - Composite type: CC-A (small), CC-B (medium), CC-C (large)
+ * @returns Composite component matrix
+ */
+export function encodeGS1Composite(data: string, type: CompositeType = "CC-A"): GS1CompositeResult {
+  if (data.length === 0) {
+    throw new InvalidInputError("GS1 Composite: data must not be empty");
+  }
+
+  // Validate AI format if parenthesized
+  if (data.includes("(")) {
+    parseAIString(data); // throws on invalid
+  }
+
+  // Encode based on composite type
+  switch (type) {
+    case "CC-A":
+    case "CC-B": {
+      // MicroPDF417-based
+      const columns = type === "CC-A" ? 2 : 3;
+      const result = encodeMicroPDF417(data, { columns });
+      return {
+        composite: result.matrix,
+        type,
+        rows: result.rows,
+        cols: result.cols,
+      };
+    }
+    case "CC-C": {
+      // PDF417-based
+      const result = encodePDF417(data, { ecLevel: 2, columns: 4 });
+      return {
+        composite: result.matrix,
+        type,
+        rows: result.rows,
+        cols: result.cols,
+      };
+    }
+    default:
+      throw new InvalidInputError(`Invalid composite type: ${type}`);
+  }
+}

src/index.ts

@@ -73,6 +73,8 @@ export { encodeGS1128 } from "./encoders/gs1-128";
 export { encodeIdentcode, encodeLeitcode } from "./encoders/deutsche-post";
 export { encodePOSTNET, encodePLANET } from "./encoders/postnet";
 export { encodePlessey } from "./encoders/plessey";
+export { encodeGS1Composite } from "./encoders/gs1-composite";
+export type { CompositeType, GS1CompositeResult } from "./encoders/gs1-composite";
 export {
   encodeGS1DataBarOmni,
   encodeGS1DataBarLimited,

test/encoders-gs1-composite.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { encodeGS1Composite } from "../src/encoders/gs1-composite";
+
+describe("GS1 Composite", () => {
+  it("encodes CC-A (MicroPDF417, 2 columns)", () => {
+    const result = encodeGS1Composite("(17)260101(10)BATCH01", "CC-A");
+    expect(result.type).toBe("CC-A");
+    expect(result.rows).toBeGreaterThan(0);
+    expect(result.composite.length).toBe(result.rows);
+  });
+
+  it("encodes CC-B (MicroPDF417, 3 columns)", () => {
+    const result = encodeGS1Composite("(17)260101(10)BATCH01", "CC-B");
+    expect(result.type).toBe("CC-B");
+    expect(result.rows).toBeGreaterThan(0);
+  });
+
+  it("encodes CC-C (PDF417)", () => {
+    const result = encodeGS1Composite("(17)260101(10)BATCH01(21)SERIAL001", "CC-C");
+    expect(result.type).toBe("CC-C");
+    expect(result.rows).toBeGreaterThan(0);
+  });
+
+  it("default type is CC-A", () => {
+    const result = encodeGS1Composite("(10)LOT123");
+    expect(result.type).toBe("CC-A");
+  });
+
+  it("produces boolean matrix", () => {
+    const result = encodeGS1Composite("(10)TEST");
+    for (const row of result.composite) {
+      for (const cell of row) {
+        expect(typeof cell).toBe("boolean");
+      }
+    }
+  });
+
+  it("throws on empty", () => {
+    expect(() => encodeGS1Composite("")).toThrow();
+  });
+
+  it("different data produces different output", () => {
+    const a = encodeGS1Composite("(10)AAA");
+    const b = encodeGS1Composite("(10)BBB");
+    const aStr = a.composite.map((r) => r.map((c) => (c ? "1" : "0")).join("")).join("");
+    const bStr = b.composite.map((r) => r.map((c) => (c ? "1" : "0")).join("")).join("");
+    expect(aStr).not.toBe(bStr);
+  });
+});