{"name":"text-fill","entry":"component","title":"TextFill","description":"A controlled character sweep from muted text through vermilion into ink. Drive progress with a slider, scroll, or a video timeline.","category":"UI","capabilities":["controls"],"needsRemotion":false,"registryDependencies":["@jbm/tokens"],"install":"npx shadcn@latest add @jbm/text-fill","installName":"text-fill","page":"https://jbm-ui.bns.studio/c/text-fill","registryItem":"https://jbm-ui.bns.studio/r/text-fill.json","sourcePath":"registry/jbm/ui/text-fill.tsx","files":[{"source":"registry/jbm/ui/text-fill.tsx","target":"src/jbm/ui/text-fill.tsx","import":"@/jbm/ui/text-fill","type":"registry:ui"}],"endpoints":{"markdown":"https://jbm-ui.bns.studio/catalog/text-fill.md","json":"https://jbm-ui.bns.studio/catalog/text-fill.json"},"snippet":"import { TextFill } from \"@/jbm/ui/text-fill\"\n\n<TextFill text=\"Una idea toma forma.\" progress={0.5} style={{ fontSize: 40 }} />\n// progress: 0–1, controlled; no internal timer.","api":[{"export":"TextFill","kind":"component","summary":"Inline span that colors each grapheme by `progress`: characters ahead of the sweep stay dim, a short accent wave (about three characters) leads, and settled characters turn to text color. Pure React with no timers, browser globals, or Remotion; the full text is also rendered once in a visually hidden span for assistive technology, and the colored copy is aria-hidden.","props":[{"name":"text","type":"string","required":true,"default":null,"description":"The sentence to sweep. Split into words (whitespace preserved, words never break mid-word unless they overflow) and graphemes via Intl.Segmenter."},{"name":"progress","type":"number","required":true,"default":null,"description":"Fill progress from 0 (all dim) to 1 (all text color). Clamped to 0–1; non-finite values render as 0. Drive from a slider, scroll position, or a timeline."},{"name":"dimColor","type":"string","required":false,"default":"color.line","description":"Color of characters the sweep has not reached yet."},{"name":"accentColor","type":"string","required":false,"default":"color.accent","description":"Color of the leading wave between dim and settled characters; keep the vermilion accent."},{"name":"textColor","type":"string","required":false,"default":"color.ink","description":"Final color of settled characters, and of every character at progress 1."},{"name":"reducedMotion","type":"boolean","required":false,"default":"false","description":"When true, renders the complete text in textColor regardless of progress."},{"name":"style","type":"CSSProperties","required":false,"default":null,"description":"Inline styles merged over the defaults (Geist sans, weight 800, line-height 1.15, pre-wrap); set fontSize here."},{"name":"className","type":"string","required":false,"default":null,"description":"Class name on the outer span."}],"passthrough":[]}],"stage":{"mode":"fluid","reason":"Inline text: width follows the container and height follows the wrapped lines at the inherited font size × 1.15 line-height. Nothing is fixed; set fontSize through style or a parent."},"examples":[{"title":"Half-filled sentence","code":"import { TextFill } from \"@/jbm/ui/text-fill\"\n\n<TextFill text=\"Una idea toma forma.\" progress={0.5} style={{ fontSize: 40 }} />\n// progress: 0–1, controlled; no internal timer."},{"title":"Drive it from a Remotion timeline","code":"import { TextFill } from \"@/jbm/ui/text-fill\"\nimport { useProgress } from \"@/jbm/motion/hooks\" // install @jbm/motion-hooks separately\n\n// Render inside a Remotion <Composition> or <Player>: hooks run in the component body.\nexport function FillingText() {\n  const progress = useProgress(0.2, 1, 2)\n  return <TextFill text=\"Letra por letra.\" progress={progress} style={{ fontSize: 72 }} />\n}"}],"qa":["Drag the progress slider through 0, about 0.5, and 1: all dim at 0, a dim → vermilion → ink gradient near the sweep front mid-way, and solid ink at 1 with no lingering accent.","Check wrapping on a narrow screen: words stay whole and whitespace is preserved; very long words wrap anywhere instead of overflowing.","With a screen reader, the sentence is read once from the hidden copy, not character by character.","Set reducedMotion and confirm the full ink text renders at any progress.","Try text with emoji or combining marks; each grapheme should color as one unit."],"related":[{"name":"tokens","relation":"installs"},{"name":"scroll-text-fill","relation":"installed-by"},{"name":"burbuja","relation":"installed-by"},{"name":"motion-hooks","relation":"example-import"}],"setup":{"namespace":"@jbm","componentsJson":{"registries":{"@jbm":"https://jbm-ui.bns.studio/r/{name}.json"}},"command":"npx shadcn@latest add @jbm/<name>","target":"src/jbm/","importAlias":"@/jbm/…","tsconfigPaths":{"@/*":["./src/*"]}},"rules":["Install through the @jbm namespace: each registry item JSON (/r/<name>.json) carries its files' contents and each guide is served at /docs/<slug>.md, so agents never need the source repository (it is public on GitHub for people browsing the code).","Files install to src/jbm/ and import as @/jbm/…, which needs the @/* → ./src/* path alias in tsconfig.json.","Items marked needsRemotion require the remotion package and must render inside a Remotion composition or Player; every other item works in any React page.","Use one vermilion accent per composition; accent2 is for annotations only and soft is for dark surfaces only.","Stages are 1920×1080 landscape and 1080×1920 vertical with declared safe areas; each item's stage field declares its size in stage pixels, and scenes compose from YAML-shaped specs with @jbm/scene-spec."],"links":{"catalog":"https://jbm-ui.bns.studio/catalog.json","llms":"https://jbm-ui.bns.studio/llms.txt"}}