maybe 0.1.0

Author: leeoniya

README.md

@@ -1,23 +1,28 @@
 ## ⏎ μWrap
 
-A [10x faster](#performance) and more accurate text wrapping util in [1.5KB (min)](https://github.com/leeoniya/uWrap/blob/main/dist/uWrap.iife.min.js) _(MIT Licensed)_
+A [10x faster](#performance) and more accurate text wrapping util in [< 2KB (min)](https://github.com/leeoniya/uWrap/blob/main/dist/uWrap.iife.min.js) _(MIT Licensed)_
 
 ---
 ### Introduction
 
-uWrap was made to efficiently predict varying row heights for list and grid [virtualization](https://www.patterns.dev/vanilla/virtual-lists/) - a strategy for performance optimization when rendering large datasets.
-Doing this both quickly and accurately turns out to be a non-trivial task, since Canvas2D provides no API for text wrapping, and `measureText()` is very expensive;
-rendering to the DOM is also out of the question due to poor performance.
-Additionally, font size, variable-width fonts, `letter-spacing`, explicit line breaks, and different `white-space` choices impact the exact number of lines in final result.
+uWrap exists to efficiently predict varying row heights for list and grid [virtualization](https://www.patterns.dev/vanilla/virtual-lists/), a technique for UI performance optimization when rendering large, scrollable datasets.
+Doing this both quickly and accurately turns out to be a non-trivial task since Canvas2D provides no API for text wrapping, and `measureText()` is quite expensive;
+measuring via DOM is also a non-starter due to poor performance.
+Additionally, font size, variable-width fonts, `letter-spacing`, explicit line breaks, and different `white-space` choices affect the number of wrapped lines.
+
+Notes:
+
+- Today, works most accurately with Latin charsets
+- Does not yet handle Windows-style `\r\n` explicit line breaks
+- Only `pre-line` wrapping strategy is implemented so far
 
 ---
 ### Performance
 
-[canvas-hypertxt](https://github.com/glideapps/canvas-hypertxt) looks to be the fastest similar utility.
-uWrap handily out-performs it in both CPU and memory usage by a wide margin while being significantly _more_ accurate.
+uWrap handily out-performs [canvas-hypertxt](https://github.com/glideapps/canvas-hypertxt) in both CPU and memory usage by a wide margin while being significantly _more_ accurate.
 
-The benchmark below wraps 100k random sentances within boxes of random widths between 50px and 250px.
-You can see this benchmark performed in the console on the [demo page](https://leeoniya.github.io/uWrap/demo/).
+The benchmark below wraps 100k random sentances in boxes of random widths between 50px and 250px.
+You can see this live in DevTools console of the [demo page](https://leeoniya.github.io/uWrap/demo/).
 
 <table>
   <tr>
@@ -70,18 +75,18 @@ let ctx = document.createElement('canvas').getContext('2d');
 ctx.font = "14px Inter, sans-serif";
 ctx.letterSpacing = '0.15px';
 
-// init wrapper
-let wrap = varPreLine(ctx);
+// init util fns
+const { count, test, split } = varPreLine(ctx);
 
-// sample text
+// example text
 let text = 'The quick brown fox jumps over the lazy dog.';
 
-// call wrapper with text to wrap, width of bounding container, and per-line callback
-let lineCount = 0;
-wrap(text, width, () => { count++; });
+// count lines
+let numLines = count(text, width);
 
-// or process the lines for rendering, etc..
+// test if text will wrap
+let willWrap = test(text, width);
 
-let lines = [];
-wrap(text, width, (idx0, idx1) => { lines.push(text.slice(idx0, idx1)); });
+// split lines (with optional limit)
+let lines = split(text, width, 3);
 ```

demo/index.html

@@ -87,16 +87,11 @@
 
       setTimeout(() => {
         console.time('uWrap 100k');
-        let wrap = varPreLine(ctx);
+        let { count } = varPreLine(ctx);
 
         for (let i = 0; i < strings.length; i++) {
           let text = strings[i];
-
-          let count = 0;
-          wrap(text, randInt(50, 250), (idx0, idx1) => { count++; });
-
-          // let lines = [];
-          // wrap(text, width, (idx0, idx1) => { lines.push(text.slice(idx0, idx1)); });
+          let c = count(text, randInt(50, 250));
         }
         console.timeEnd('uWrap 100k');
       }, 500);
@@ -120,15 +115,15 @@
       // ACCURACY OVERLAYS //
 
       setTimeout(() => {
-        const wrap = varPreLine(ctx);
+        const { each } = varPreLine(ctx);
 
         for (const el of document.querySelectorAll('.test')) {
           let text = el.textContent;
           let res = document.createElement('div');
           res.className = 'result';
 
           let t = [];
-          wrap(text, el.offsetWidth, (idx0, idx1) => { t.push(text.slice(idx0, idx1)); });
+          each(text, el.offsetWidth, (idx0, idx1) => { t.push(text.slice(idx0, idx1)); });
           res.textContent = t.join('\n');
           el.prepend(res);
         }
@@ -144,7 +139,6 @@
       //   }
       // }, 2000);
 
-
       // setTimeout(() => {
       //   for (const el of document.querySelectorAll('.test')) {
       //     let text = el.textContent;

dist/uWrap.d.ts

@@ -1,6 +1,24 @@
-/** may return false to halt wrapping */
+/** may return false to exit loop early */
 export type LineCallback = (idx0: number, idx1: number) => void | boolean;
 
-export type Wrapper = (text: string, width: number, cb: LineCallback) => void;
+/** invoke callback for each line with start/end idxs */
+export type Each  = (text: string, width: number, cb: LineCallback) => void;
 
+/** split into lines array */
+export type Split = (text: string, width: number, limit?: number) => string[];
+
+/** count lines */
+export type Count = (text: string, width: number) => number;
+
+/** test whether text will wrap (line count > 1) */
+export type Test = (text: string, width: number) => boolean;
+
+export interface uWrap {
+    each: Each;
+    split: Split;
+    count: Count;
+    test: Test;
+};
+
+/** wrap text with a variable width font using pre-line whitespace strategy */
 export function varPreLine(ctx: CanvasRenderingContext2D): Wrapper;

dist/uWrap.iife.js

@@ -121,7 +121,31 @@ var uWrap = (function (exports) {
           }
           cb(headIdx, to + 1);
       }
-      return each;
+      return {
+          each,
+          split: (text, width, limit = Infinity) => {
+              let out = [];
+              each(text, width, (idx0, idx1) => {
+                  out.push(text.slice(idx0, idx1));
+                  if (out.length === limit)
+                      return false;
+              });
+              return out;
+          },
+          count: (text, width) => {
+              let count = 0;
+              each(text, width, () => { count++; });
+              return count;
+          },
+          test: (text, width) => {
+              let count = 0;
+              each(text, width, () => {
+                  if (++count === 2)
+                      return false;
+              });
+              return count === 2;
+          },
+      };
   }
 
   exports.varPreLine = varPreLine;

dist/uWrap.iife.min.js

@@ -118,7 +118,31 @@ function varPreLine(ctx) {
         }
         cb(headIdx, to + 1);
     }
-    return each;
+    return {
+        each,
+        split: (text, width, limit = Infinity) => {
+            let out = [];
+            each(text, width, (idx0, idx1) => {
+                out.push(text.slice(idx0, idx1));
+                if (out.length === limit)
+                    return false;
+            });
+            return out;
+        },
+        count: (text, width) => {
+            let count = 0;
+            each(text, width, () => { count++; });
+            return count;
+        },
+        test: (text, width) => {
+            let count = 0;
+            each(text, width, () => {
+                if (++count === 2)
+                    return false;
+            });
+            return count === 2;
+        },
+    };
 }
 /*
 function isMonospace(ctx: CanvasRenderingContext2D) {

dist/uWrap.mjs

@@ -1,7 +1,7 @@
 {
   "name": "uwrap",
   "version": "0.1.0",
-  "description": "",
+  "description": "A very fast and accurate text and line wrapping util",
   "homepage": "https://github.com/leeoniya/uWrap#readme",
   "bugs": {
     "url": "https://github.com/leeoniya/uWrap/issues"
@@ -10,19 +10,37 @@
     "type": "git",
     "url": "git+https://github.com/leeoniya/uWrap.git"
   },
-  "license": "ISC",
+  "license": "MIT",
   "author": "",
   "type": "module",
-  "module": "./dist/uDSV.mjs",
-  "types": "./dist/uDSV.d.ts",
+  "module": "./dist/uWrap.mjs",
+  "types": "./dist/uWrap.d.ts",
+  "files": [
+    "package.json",
+    "README.md",
+    "LICENSE",
+    "dist"
+  ],
+  "keywords": [
+    "text",
+    "line",
+    "word",
+    "wrap",
+    "wrapping",
+    "split",
+    "virtualization",
+    "virtualize",
+    "canvas",
+    "measure"
+  ],
   "scripts": {
     "test": "node ./test/uWrap.test.mjs",
     "build": "rollup -c"
   },
   "devDependencies": {
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.2",
-    "rollup": "^4.37.0",
+    "rollup": "^4.39.0",
     "skia-canvas": "^2.0.2",
     "tslib": "^2.8.1"
   }

package.json

@@ -140,7 +140,32 @@ export function varPreLine(ctx: CanvasRenderingContext2D) {
     cb(headIdx, to + 1);
   }
 
-  return each;
+  return {
+    each,
+    split: (text: string, width: number, limit = Infinity) => {
+      let out: string[] = [];
+      each(text, width, (idx0: number, idx1: number) => {
+        out.push(text.slice(idx0, idx1));
+
+        if (out.length === limit)
+          return false;
+      });
+      return out;
+    },
+    count: (text: string, width: number) => {
+      let count = 0;
+      each(text, width, () => { count++; });
+      return count;
+    },
+    test: (text: string, width: number) => {
+      let count = 0;
+      each(text, width, () => {
+        if (++count === 2)
+          return false;
+      });
+      return count === 2;
+    },
+  };
 }
 
 /*