@connectedxm/zpl-generator 0.0.19 → 0.0.21

package/README.md

@@ -329,38 +329,33 @@ const zpl = generate(badgeWithData);
 
 ### Accurate Text Wrapping
 
-For precise text layout with proportional fonts, measure word widths and provide them:
+For precise auto-shrink sizing with proportional fonts, measure each word of
+the **rendered** value (after `transformation`/`maxCharacters` — use the
+exported `applyTextTransformation`) and provide `wordWidths` on the text
+field. Tokenize with the exported `tokenizeWords` so words line up with the
+generator's wrap simulation. Widths are measured at the field's `fontHeight`;
+the generator scales them when searching for a fitting height.
 
-```typescript
-import { countLines } from 'cxm-zpl-generator';
-
-// Measure word widths (e.g., using canvas or font metrics)
-const wordWidths: WordWidth[] = [
-    { word: 'Hello', width: 50, spaceWidth: 10 },
-    { word: 'World', width: 60, spaceWidth: 10 },
-];
-
-const fieldBlock: FieldBlock = {
-    type: 'field',
-    name: 'text',
-    x: 0,
-    y: 0,
-    data: 'Hello World',
-    font: 'A',
-    fontHeight: 20,
-    maxWidth: 100,
-    maxLines: 5,
-    lineSpacing: 0,
-    alignment: TextAlignment.Left,
-    fontOrientation: FontOrientation.NoRotation,
-    hangingIndent: 0,
-    verticalAlignment: VerticalAlignment.End,
-    wordWidths, // Provide measured widths
-};
+Line counting priority: `wordWidths` (exact `^FB` word-wrap simulation, used
+only when the measured words match the rendered value) → `measuredWidth`
+(continuous-stream estimate) → `charsPerLine` heuristic.
 
-// countLines can be used to preview line count
-const lines = countLines(fieldBlock);
-console.log(`Text will occupy ${lines} lines`);
+```typescript
+import {
+  applyTextTransformation,
+  tokenizeWords,
+  generate,
+  WordWidth,
+} from "@connectedxm/zpl-generator";
+
+// In the consumer, after resolving the field's value:
+const printed = applyTextTransformation(field, rawValue);
+const spaceWidth = measure(" "); // e.g. canvas measureText at field.fontHeight
+const wordWidths: WordWidth[] = tokenizeWords(printed)
+  .flat()
+  .map((word) => ({ word, width: measure(word), spaceWidth }));
+
+const sizedField = { ...field, wordWidths };
 ```
 
 ### Validating JSON Configuration