Skip to content

Add usage guide with practical examples and integration patterns#21

Open
yuribodo wants to merge 1 commit into
chenglou:mainfrom
yuribodo:docs/usage-guide
Open

Add usage guide with practical examples and integration patterns#21
yuribodo wants to merge 1 commit into
chenglou:mainfrom
yuribodo:docs/usage-guide

Conversation

@yuribodo
Copy link
Copy Markdown

Summary

Comprehensive USAGE.md addressing the gap identified in #8: "demos look amazing, but unclear how to use without poking through the code."

The guide is organized by what you want to accomplish, not by function name:

  • Quickstart — 3 lines to measure text height
  • Choosing Your API — decision tree: layout() vs layoutWithLines() vs walkLineRanges() vs layoutNextLine()
  • Core Concepts — two-phase model, font strings, cursors
  • Height Prediction — vanilla JS + React hook with ResizeObserver
  • Canvas RenderinglayoutWithLines()ctx.fillText() loop
  • Shrink-Wrapping — binary search pattern from the Bubbles demo
  • Variable-Width Layout — text around images + two-column flow with cursors
  • Pre-Wrap Mode{ whiteSpace: 'pre-wrap' } for textareas
  • Performance — what to cache, when to re-prepare, batch patterns
  • Framework Integration — React, vanilla JS, and a note for Vue/Svelte/Angular
  • Tips — named fonts, font loading, lineHeight, edge cases

Does not duplicate the README's API glossary — references it instead. Added a one-line link from the README.

Closes #8

Test plan

  • bun run check passes
  • bun test passes (60/60)
  • All internal links resolve (README, DEVELOPMENT.md)
  • Code examples are self-contained and copy-pasteable
  • Review examples for accuracy against current API

Comprehensive USAGE.md covering quickstart, API decision tree, core
concepts (two-phase model, font strings, cursors), and practical
patterns: height prediction, Canvas rendering, shrink-wrapping, variable-
width layout, pre-wrap mode, and performance guidance. Includes React
hook and vanilla JS integration examples. Linked from README.

Closes chenglou#8
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

usage guide needed !

1 participant