প্রকল্প সম্পর্কে

Pretext হলো একটি pure JavaScript/TypeScript লাইব্রেরি, যা multiline text পরিমাপ এবং line layout গণনার জন্য ব্যবহৃত হয়। এটি `getBoundingClientRect` এবং `offsetHeight`-এর মতো DOM measurement API এড়িয়ে যায়, কারণ এগুলো layout reflow বাধ্য করে। এর পরিবর্তে এটি browser-এর canvas `measureText`-কে ground truth হিসেবে ব্যবহার করে নিজেই measurement করে। ফলে virtualization, custom layout engine, canvas/SVG rendering এবং development-time overflow check-এ এটি কাজে লাগে। ## Installation ```sh npm install @chenglou/pretext ``` ## Main use cases ### 1. DOM স্পর্শ না করে paragraph height পরিমাপ ```ts import { prepare, layout } from '@chenglou/pretext' const prepared = prepare('AGI 春天到了. بدأت الرحلة 🚀', '16px Inter') const { height, lineCount } = layout(prepared, 320, 20) ``` `prepare()` একবারই কাজ করে: whitespace normalization, text segmentation, glue rule application এবং canvas-based measurement। এরপর `layout()` cached width-এর উপর একটি সস্তা pure-arithmetic operation, তাই resize-এ re-prepare ছাড়াই আবার চালানো যায়। `prepare()`-এর option-এর মধ্যে আছে `whiteSpace: 'pre-wrap'` (textarea-সদৃশ behavior), `wordBreak: 'keep-all'` (CSS-এর `word-break: keep-all`-এর মতো) এবং `letterSpacing` (CSS `letter-spacing`-এর জন্য)। ### 2. Manual line layout `prepareWithSegments()` custom layout-এর জন্য আরও সমৃদ্ধ structure দেয়। নিচের APIগুলো পাওয়া যায়: - `layoutWithLines()` — fixed max width-এ সব line return করে, যার মধ্যে text ও measured width থাকে। - `walkLineRanges()` — line string তৈরি না করেই প্রতি line-এ width এবং start/end cursor নিয়ে callback call করে। - `measureLineStats()` — allocation ছাড়াই line count এবং সবচেয়ে চওড়া line-এর width return করে। - `measureNaturalWidth()` — যখন width wrapping-এর কারণ নয়, তখন সবচেয়ে চওড়া forced line return করে। - `layoutNextLine()` / `layoutNextLineRange()` — iterator-style API, যা একবারে একটি line layout করে, সম্ভবত ভিন্ন ভিন্ন width-এ; float-এর চারপাশে text flow বা dynamic container-এর জন্য উপযোগী। - `materializeLineRange()` — একটি layout range-কে আবার full line string-এ রূপান্তর করে। এগুলো Canvas, SVG, WebGL এবং ভবিষ্যতে server-side environment-এ rendering সক্ষম করে। Repository-তে এবং chenglou.me/pretext-এ demo আছে। ## Rich inline helper `@chenglou/pretext/rich-inline`-এ একটি আলাদা helper আছে, যা mixed font, atomic item (যেমন chip ও mention) এবং pill chrome-এর জন্য caller-owned extra width সহ basic rich-text inline flow সমর্থন করে। এটি ইচ্ছাকৃতভাবে সংকীর্ণ: শুধু inline-only, শুধু `white-space: normal`, এবং এটি সাধারণ CSS inline formatting engine নয়। ## API glossary highlights - `PreparedText` হলো opaque fast-path handle; `PreparedTextWithSegments` হলো আরও সমৃদ্ধ manual-layout handle। - `LayoutCursor` segment/grapheme index ব্যবহার করে, raw string offset নয়। - খালি string-এ `layout()` `{ lineCount: 0, height: 0 }` return করে; browser খালি block-কে এক `line-height`-এ size করে, তাই caller clamp করতে চাইতে পারে। - Soft hyphen সমর্থিত: এগুলো optional break point হিসেবে কাজ করে এবং বেছে নিলে trailing `-` হিসেবে materialize হয়। - `clearCache()` shared internal cache clear করে; `setLocale()` ভবিষ্যতের preparation call-এর locale set করে। - সমৃদ্ধ handle-এ custom bidi-aware rendering-এর জন্য approximate `segLevels` থাকে, তবে Pretext সম্পূর্ণ Unicode Bidirectional Algorithm implement করে না। ## Caveats Pretext সম্পূর্ণ font rendering engine নয়। এটি সাধারণ CSS text setup target করে: - `white-space: normal` এবং `pre-wrap` - `word-break: normal` এবং `keep-all` - `overflow-wrap: break-word` - `line-break: auto` - numeric pixel value হিসেবে `letter-spacing` - Tab default `tab-size: 8` অনুসরণ করে উল্লেখযোগ্য limitation: - macOS-এ `layout()` accuracy-র জন্য `system-ui` এবং `-apple-system` unsafe; named font সুপারিশ করা হয়। - punctuation-এর পাশে emoji browser থেকে ভিন্নভাবে wrap হতে পারে। - কিছু font, যেমন Shantell Sans, long word-এ ভিন্ন line break দিতে পারে। - Runtime-এ `Intl.Segmenter`, Canvas 2D text measurement এবং Unicode property escape প্রয়োজন। - canvas `font` shorthand-এর বাইরের CSS font feature আলাদাভাবে model করা হয় না। সামগ্রিকভাবে, Pretext একটি focused library হিসেবে অবস্থান করে, যা multiline text measurement-এ web developer-দের browser layout query-র দ্রুত ও deterministic বিকল্প দেয়।