@viraui/react 2026.9.0 → 2026.9.1

package/dist/catalog.json

@@ -185,7 +185,7 @@
     {
       "id": "prose",
       "name": "Prose",
-      "summary": "Text-wall grouping region (articles, docs, privacy) with heading-aware em rhythm; reading column via parent Stack `maxWidth` sized for body Text `size`.",
+      "summary": "Text-wall grouping region (articles, docs, privacy) with heading-aware em rhythm, region `wrap` (default `pretty`), and reading column via parent Stack `maxWidth` sized for body Text `size`.",
       "agentDocs": "./specs/components/prose/meta.xml"
     },
     {
@@ -263,7 +263,7 @@
     {
       "id": "text",
       "name": "Text",
-      "summary": "Theme-aware body-copy primitive with tone, family, sizing, and readable-measure props (`maxWidth` / `lineHeight` / `balanced`).",
+      "summary": "Theme-aware body-copy primitive with tone, family, sizing, and readable-measure props (`maxWidth` / `lineHeight` / `wrap`).",
       "agentDocs": "./specs/components/text/meta.xml"
     },
     {
@@ -281,7 +281,7 @@
     {
       "id": "title",
       "name": "Title",
-      "summary": "Theme-aware heading and display typography with readable-measure props (`maxWidth` / `lineHeight` / `balanced`).",
+      "summary": "Theme-aware heading and display typography with readable-measure props (`maxWidth` / `lineHeight` / `wrap`).",
       "agentDocs": "./specs/components/title/meta.xml"
     },
     {

package/dist/components/prose/prose.css

@@ -1 +1 @@
-@layer viraui.preflight, viraui.components, viraui.overrides;@layer viraui.components{@property --vui-prose-align{syntax:"*";inherits:false;initial-value:start}@property --vui-prose-gap-blocks{syntax:"<length>";inherits:true;initial-value:2em}@property --vui-prose-gap-heading-start{syntax:"<length>";inherits:true;initial-value:1.3em}@property --vui-prose-gap-heading-end{syntax:"<length>";inherits:true;initial-value:.8em}.viraui__prose-module__Prose_8yO9h{--vui-prose-gap-blocks:2em;--vui-prose-gap-heading-start:1.3em;--vui-prose-gap-heading-end:0.8em;&[data-prose-gap=s]{--vui-prose-gap-blocks:1em;--vui-prose-gap-heading-start:0.7em;--vui-prose-gap-heading-end:0.3em}&[data-prose-gap=m]{--vui-prose-gap-blocks:1.5em;--vui-prose-gap-heading-start:1em;--vui-prose-gap-heading-end:0.6em}&[data-prose-has-align=true]{text-align:var(--vui-prose-align)}&>:is(h1,h2,h3,h4,h5,h6,hgroup,ul,ol,dd,p,figure,img,pre,table,fieldset,blockquote,picture,div):where(:not(:first-child)){margin-block:var(--vui-prose-gap-blocks)}&>:is(h1,h2,h3,h4,h5,h6)+*{margin-block-start:var(--vui-prose-gap-heading-start)}&>:is(h1,h2,h3,h4,h5,h6){margin-block-end:var(--vui-prose-gap-heading-end);text-box:trim-both cap alphabetic}}}
+@layer viraui.preflight, viraui.components, viraui.overrides;@layer viraui.components{@property --vui-prose-align{syntax:"*";inherits:false;initial-value:start}@property --vui-prose-wrap{syntax:"*";inherits:true;initial-value:pretty}@property --vui-prose-gap-blocks{syntax:"<length>";inherits:true;initial-value:2em}@property --vui-prose-gap-heading-start{syntax:"<length>";inherits:true;initial-value:1.3em}@property --vui-prose-gap-heading-end{syntax:"<length>";inherits:true;initial-value:.8em}.viraui__prose-module__Prose_8yO9h{--vui-prose-gap-blocks:2em;--vui-prose-gap-heading-start:1.3em;--vui-prose-gap-heading-end:0.8em;&[data-prose-gap=s]{--vui-prose-gap-blocks:1em;--vui-prose-gap-heading-start:0.7em;--vui-prose-gap-heading-end:0.3em}&[data-prose-gap=m]{--vui-prose-gap-blocks:1.5em;--vui-prose-gap-heading-start:1em;--vui-prose-gap-heading-end:0.6em}text-wrap:var(--vui-prose-wrap);&[data-prose-has-align=true]{text-align:var(--vui-prose-align)}&>:is(h1,h2,h3,h4,h5,h6,hgroup,ul,ol,dd,p,figure,img,pre,table,fieldset,blockquote,picture,div):where(:not(:first-child)){margin-block:var(--vui-prose-gap-blocks)}&>:is(h1,h2,h3,h4,h5,h6)+*{margin-block-start:var(--vui-prose-gap-heading-start)}&>:is(h1,h2,h3,h4,h5,h6){margin-block-end:var(--vui-prose-gap-heading-end);text-box:trim-both cap alphabetic}}}

package/dist/components/prose/prose.d.ts

@@ -25,6 +25,14 @@ export type ProseProps = React.ComponentPropsWithoutRef<'div'> & {
      * @defaultValue Inherits parent `text-align`.
      */
     align?: React.CSSProperties['textAlign'];
+    /**
+     * Controls CSS `text-wrap` on the Prose root (inherits to descendants unless a child overrides).
+     * Default `pretty` for orphan-aware article walls. Prefer `balance` only on short multi-line
+     * blocks that need even line lengths. Single-line metrics stay on child Text/Title `whiteSpace`.
+     *
+     * @defaultValue 'pretty'
+     */
+    wrap?: React.CSSProperties['textWrap'];
     /**
      * Replaces the default `div` root using Base UI render semantics.
      *

package/dist/components/prose/prose.js

@@ -4,10 +4,11 @@ import { clsx } from "../../core/clsx.js";
 import prose_module_default from "./prose.module.js";
 import { useRender } from "@base-ui/react/use-render";
 //#region src/components/prose/prose.tsx
-var Prose = ({ align, className, gap = "l", ref, render, style, ...otherProps }) => {
+var Prose = ({ align, className, gap = "l", ref, render, style, wrap = "pretty", ...otherProps }) => {
 	const hasAlign = align !== void 0;
 	const dynamicStyle = {
 		...hasAlign && { "--vui-prose-align": align },
+		"--vui-prose-wrap": wrap,
 		...style
 	};
 	return useRender({

package/dist/components/text/text.css

@@ -1,5 +1,5 @@
-@layer viraui.preflight, viraui.components, viraui.overrides;@layer viraui.components{@property --vui-text-align{syntax:"*";inherits:false;initial-value:start}@property --vui-text-max-width{syntax:"*";inherits:false;initial-value:none}@property --vui-text-literal-color{syntax:"<color>";inherits:false;initial-value:#0000}@property --vui-text-white-space{syntax:"*";inherits:false;initial-value:normal}@property --vui-text-letter-spacing{syntax:"normal | <length>";inherits:false;initial-value:normal}@property --vui-text-text-transform{syntax:"none | capitalize | uppercase | lowercase";inherits:false;initial-value:none}@property --vui-text-font-weight{syntax:"<number>";inherits:false;initial-value:400}@property --vui-text-font-width{syntax:"<number>";inherits:false;initial-value:100}@property --vui-text-font-opsz{syntax:"<number>";inherits:false;initial-value:16}@property --vui-text-trim{syntax:"*";inherits:false;initial-value:trim-both}@property --vui-text-trim-type{syntax:"*";inherits:false;initial-value:cap alphabetic}@property --vui-text-padding-inline-start{syntax:"<length>";inherits:false;initial-value:0}@property --vui-text-padding-inline-end{syntax:"<length>";inherits:false;initial-value:0}@property --vui-text-padding-block-start{syntax:"<length>";inherits:false;initial-value:0}@property --vui-text-padding-block-end{syntax:"<length>";inherits:false;initial-value:0}@property --vui-text-font-size{syntax:"<length>";inherits:false;initial-value:1rem}@property --vui-text-font-family{syntax:"*";inherits:false;initial-value:sans-serif}@property --vui-text-line-height{syntax:"normal | <number> | <length-percentage>";inherits:false;initial-value:normal}@property --__text-fluid{syntax:"<number>";inherits:false;initial-value:0}@property --__text-size-min{syntax:"<length>";inherits:false;initial-value:1rem}@property --__text-size-max{syntax:"<length>";inherits:false;initial-value:1rem}.viraui__text-module__Text_bS8kv{--__text-fluid:calc((100vi - 320px) / 1125px);--__text-size-min:var(--font-scale-body-s);--__text-size-max:var(--font-scale-body-m);--vui-text-font-size:clamp(
+@layer viraui.preflight, viraui.components, viraui.overrides;@layer viraui.components{@property --vui-text-align{syntax:"*";inherits:false;initial-value:start}@property --vui-text-max-width{syntax:"*";inherits:false;initial-value:none}@property --vui-text-literal-color{syntax:"<color>";inherits:false;initial-value:#0000}@property --vui-text-white-space{syntax:"*";inherits:false;initial-value:normal}@property --vui-text-wrap{syntax:"*";inherits:false;initial-value:pretty}@property --vui-text-letter-spacing{syntax:"normal | <length>";inherits:false;initial-value:normal}@property --vui-text-text-transform{syntax:"none | capitalize | uppercase | lowercase";inherits:false;initial-value:none}@property --vui-text-font-weight{syntax:"<number>";inherits:false;initial-value:400}@property --vui-text-font-width{syntax:"<number>";inherits:false;initial-value:100}@property --vui-text-font-opsz{syntax:"<number>";inherits:false;initial-value:16}@property --vui-text-trim{syntax:"*";inherits:false;initial-value:trim-both}@property --vui-text-trim-type{syntax:"*";inherits:false;initial-value:cap alphabetic}@property --vui-text-padding-inline-start{syntax:"<length>";inherits:false;initial-value:0}@property --vui-text-padding-inline-end{syntax:"<length>";inherits:false;initial-value:0}@property --vui-text-padding-block-start{syntax:"<length>";inherits:false;initial-value:0}@property --vui-text-padding-block-end{syntax:"<length>";inherits:false;initial-value:0}@property --vui-text-font-size{syntax:"<length>";inherits:false;initial-value:1rem}@property --vui-text-font-family{syntax:"*";inherits:false;initial-value:sans-serif}@property --vui-text-line-height{syntax:"normal | <number> | <length-percentage>";inherits:false;initial-value:normal}@property --__text-fluid{syntax:"<number>";inherits:false;initial-value:0}@property --__text-size-min{syntax:"<length>";inherits:false;initial-value:1rem}@property --__text-size-max{syntax:"<length>";inherits:false;initial-value:1rem}.viraui__text-module__Text_bS8kv{--__text-fluid:calc((100vi - 320px) / 1125px);--__text-size-min:var(--font-scale-body-s);--__text-size-max:var(--font-scale-body-m);--vui-text-font-size:clamp(
     var(--__text-size-min),
     calc(var(--__text-size-min) + (var(--__text-size-max) - var(--__text-size-min)) * var(--__text-fluid)),
     var(--__text-size-max)
-  );--vui-text-font-family:var(--font-family-body);--vui-text-line-height:var(--font-leading-m);margin:0;max-inline-size:var(--vui-text-max-width);font-family:var(--vui-text-font-family);font-size:var(--vui-text-font-size);line-height:var(--vui-text-line-height);letter-spacing:var(--vui-text-letter-spacing);text-transform:var(--vui-text-text-transform);white-space:var(--vui-text-white-space);word-break:break-word;font-weight:var(--vui-text-font-weight);font-stretch:calc(var(--vui-text-font-width) * 1%);font-optical-sizing:auto;font-variation-settings:"wght" var(--vui-text-font-weight),"wdth" var(--vui-text-font-width),"opsz" var(--vui-text-font-opsz);text-box:var(--vui-text-trim) var(--vui-text-trim-type);&[data-text-balanced=true]{text-wrap:balance}&[data-text-selection=false]{-webkit-user-select:none;user-select:none}&[data-text-has-align=true]{text-align:var(--vui-text-align)}&[data-text-has-padding=true]{padding:var(--vui-text-padding-block-start) var(--vui-text-padding-inline-end) var(--vui-text-padding-block-end) var(--vui-text-padding-inline-start)}&[data-text-family=mono]{--vui-text-font-family:var(--font-family-mono)}&[data-text-size="4xl"]{--__text-size-min:var(--font-scale-body-3xl);--__text-size-max:var(--font-scale-body-4xl)}&[data-text-size="3xl"]{--__text-size-min:var(--font-scale-body-2xl);--__text-size-max:var(--font-scale-body-3xl)}&[data-text-size="2xl"]{--__text-size-min:var(--font-scale-body-xl);--__text-size-max:var(--font-scale-body-2xl)}&[data-text-size=xl]{--__text-size-min:var(--font-scale-body-l);--__text-size-max:var(--font-scale-body-xl)}&[data-text-size=l]{--__text-size-min:var(--font-scale-body-m);--__text-size-max:var(--font-scale-body-l)}&[data-text-size=s]{--__text-size-min:var(--font-scale-body-s);--__text-size-max:var(--font-scale-body-s)}&[data-text-size=xs]{--__text-size-min:var(--font-scale-body-xs);--__text-size-max:var(--font-scale-body-xs)}& .viraui__text-module__Text_bS8kv:not([data-text-size]){font-size:inherit}& .viraui__text-module__Text_bS8kv:not([data-text-line-height]){line-height:inherit}&[data-text-fluid=false]{--vui-text-font-size:var(--__text-size-max)}@container root style(--effect-fluid-typography: initial){--vui-text-font-size:var(--__text-size-max)}&[data-text-weight=light]{--vui-text-font-weight:200}&[data-text-weight=semibold]{--vui-text-font-weight:600}&[data-text-weight=bold]{--vui-text-font-weight:800}&[data-text-tone=primary]{color:var(--global-primary)}&[data-text-tone=muted]{color:var(--global-muted)}&[data-text-tone=interactive]{color:var(--global-interactive-text)}&[data-text-tone=positive]{color:var(--highlight-green)}&[data-text-tone=informative]{color:var(--highlight-blue)}&[data-text-tone=danger]{color:var(--highlight-red)}&[data-text-tone=warning]{color:var(--highlight-yellow)}&[data-text-has-literal-color=true]{color:var(--vui-text-literal-color)}&[data-text-line-height=none]{--vui-text-line-height:0}&[data-text-line-height=xs]{--vui-text-line-height:var(--font-leading-xs)}&[data-text-line-height=s]{--vui-text-line-height:var(--font-leading-s)}&[data-text-line-height=m]{--vui-text-line-height:var(--font-leading-m)}&[data-text-line-height=l]{--vui-text-line-height:var(--font-leading-l)}}}
+  );--vui-text-font-family:var(--font-family-body);--vui-text-line-height:var(--font-leading-m);margin:0;max-inline-size:var(--vui-text-max-width);font-family:var(--vui-text-font-family);font-size:var(--vui-text-font-size);line-height:var(--vui-text-line-height);letter-spacing:var(--vui-text-letter-spacing);text-transform:var(--vui-text-text-transform);text-wrap:var(--vui-text-wrap);white-space:var(--vui-text-white-space);word-break:break-word;font-weight:var(--vui-text-font-weight);font-stretch:calc(var(--vui-text-font-width) * 1%);font-optical-sizing:auto;font-variation-settings:"wght" var(--vui-text-font-weight),"wdth" var(--vui-text-font-width),"opsz" var(--vui-text-font-opsz);text-box:var(--vui-text-trim) var(--vui-text-trim-type);&[data-text-selection=false]{-webkit-user-select:none;user-select:none}&[data-text-has-align=true]{text-align:var(--vui-text-align)}&[data-text-has-padding=true]{padding:var(--vui-text-padding-block-start) var(--vui-text-padding-inline-end) var(--vui-text-padding-block-end) var(--vui-text-padding-inline-start)}&[data-text-family=mono]{--vui-text-font-family:var(--font-family-mono)}&[data-text-size="4xl"]{--__text-size-min:var(--font-scale-body-3xl);--__text-size-max:var(--font-scale-body-4xl)}&[data-text-size="3xl"]{--__text-size-min:var(--font-scale-body-2xl);--__text-size-max:var(--font-scale-body-3xl)}&[data-text-size="2xl"]{--__text-size-min:var(--font-scale-body-xl);--__text-size-max:var(--font-scale-body-2xl)}&[data-text-size=xl]{--__text-size-min:var(--font-scale-body-l);--__text-size-max:var(--font-scale-body-xl)}&[data-text-size=l]{--__text-size-min:var(--font-scale-body-m);--__text-size-max:var(--font-scale-body-l)}&[data-text-size=s]{--__text-size-min:var(--font-scale-body-s);--__text-size-max:var(--font-scale-body-s)}&[data-text-size=xs]{--__text-size-min:var(--font-scale-body-xs);--__text-size-max:var(--font-scale-body-xs)}& .viraui__text-module__Text_bS8kv:not([data-text-size]){font-size:inherit}& .viraui__text-module__Text_bS8kv:not([data-text-line-height]){line-height:inherit}&[data-text-fluid=false]{--vui-text-font-size:var(--__text-size-max)}@container root style(--effect-fluid-typography: initial){--vui-text-font-size:var(--__text-size-max)}&[data-text-weight=light]{--vui-text-font-weight:200}&[data-text-weight=semibold]{--vui-text-font-weight:600}&[data-text-weight=bold]{--vui-text-font-weight:800}&[data-text-tone=primary]{color:var(--global-primary)}&[data-text-tone=muted]{color:var(--global-muted)}&[data-text-tone=interactive]{color:var(--global-interactive-text)}&[data-text-tone=positive]{color:var(--highlight-green)}&[data-text-tone=informative]{color:var(--highlight-blue)}&[data-text-tone=danger]{color:var(--highlight-red)}&[data-text-tone=warning]{color:var(--highlight-yellow)}&[data-text-has-literal-color=true]{color:var(--vui-text-literal-color)}&[data-text-line-height=none]{--vui-text-line-height:0}&[data-text-line-height=xs]{--vui-text-line-height:var(--font-leading-xs)}&[data-text-line-height=s]{--vui-text-line-height:var(--font-leading-s)}&[data-text-line-height=m]{--vui-text-line-height:var(--font-leading-m)}&[data-text-line-height=l]{--vui-text-line-height:var(--font-leading-l)}}}

package/dist/components/text/text.d.ts

@@ -85,7 +85,9 @@ export type TextProps = React.ComponentPropsWithoutRef<'span'> & {
      */
     maxWidth?: string;
     /**
-     * Controls white-space preservation and wrapping behavior.
+     * Controls white-space collapse/preserve (`white-space`).
+     * Prefer `whiteSpace="nowrap"` for single-line metrics/chrome (also collapses spaces).
+     * For wrapping algorithm / even line lengths use `wrap` (`text-wrap`) — not this prop.
      *
      * @defaultValue 'normal'
      */
@@ -105,13 +107,14 @@ export type TextProps = React.ComponentPropsWithoutRef<'span'> & {
      */
     transform?: React.CSSProperties['textTransform'];
     /**
-     * Enables balanced wrapping for block-like copy.
-     * Prefer on short wrapping UI paragraphs (hero lead, empty state, card blurb);
-     * omit when single-line or intentional ragged.
+     * Controls CSS `text-wrap` (wrapping algorithm / wrap on-off).
+     * Default `pretty` for orphan-aware UI copy. Prefer `balance` on short multi-line
+     * heads/blurbs that need even line lengths. Use `wrap="nowrap"` only when you need
+     * no wrap without changing white-space collapse; prefer `whiteSpace="nowrap"` for metrics.
      *
-     * @defaultValue false
+     * @defaultValue 'pretty'
      */
-    balanced?: boolean;
+    wrap?: React.CSSProperties['textWrap'];
     /**
      * Enables text selection on the rendered copy.
      *

package/dist/components/text/text.js

@@ -4,7 +4,7 @@ import { resolveAxisPadding } from "../../core/styles/resolve-axis-padding.js";
 import text_module_default from "./text.module.js";
 import { useRender } from "@base-ui/react/use-render";
 //#region src/components/text/text.tsx
-var Text = ({ align, balanced = false, selection = true, className, color, family = "body", fluid = false, fontWidth, hPadding, lineHeight, maxWidth, opticalSize, ref, render, size, style, tone, tracking, transform, trim = "both", trimType = "cap alphabetic", vPadding, weight = "regular", whiteSpace = "normal", ...otherProps }) => {
+var Text = ({ align, selection = true, className, color, family = "body", fluid = false, fontWidth, hPadding, lineHeight, maxWidth, opticalSize, ref, render, size, style, tone, tracking, transform, trim = "both", trimType = "cap alphabetic", vPadding, weight = "regular", whiteSpace = "normal", wrap = "pretty", ...otherProps }) => {
 	const hasAlign = align !== void 0;
 	const hasPadding = Boolean(hPadding || vPadding);
 	const dynamicStyle = {
@@ -12,6 +12,7 @@ var Text = ({ align, balanced = false, selection = true, className, color, famil
 		"--vui-text-max-width": maxWidth ?? "none",
 		"--vui-text-literal-color": color,
 		"--vui-text-white-space": whiteSpace,
+		"--vui-text-wrap": wrap,
 		"--vui-text-letter-spacing": tracking,
 		"--vui-text-text-transform": transform,
 		"--vui-text-trim": trim ? `trim-${trim}` : "none",
@@ -34,7 +35,6 @@ var Text = ({ align, balanced = false, selection = true, className, color, famil
 			"data-text-weight": typeof weight === "string" ? weight : "custom",
 			"data-text-tone": tone,
 			"data-text-line-height": lineHeight,
-			"data-text-balanced": balanced ? "true" : "false",
 			"data-text-selection": selection ? "true" : "false",
 			"data-text-fluid": fluid ? "true" : "false",
 			"data-text-has-align": hasAlign ? "true" : "false",

package/dist/components/title/title.css

@@ -1,5 +1,5 @@
-@layer viraui.preflight, viraui.components, viraui.overrides;@layer viraui.components{@property --vui-title-align{syntax:"*";inherits:false;initial-value:start}@property --vui-title-max-width{syntax:"*";inherits:false;initial-value:none}@property --vui-title-literal-color{syntax:"<color>";inherits:false;initial-value:#0000}@property --vui-title-white-space{syntax:"*";inherits:false;initial-value:normal}@property --vui-title-font-weight{syntax:"<number>";inherits:false;initial-value:500}@property --vui-title-font-width{syntax:"<number>";inherits:false;initial-value:100}@property --vui-title-font-opsz{syntax:"<number>";inherits:false;initial-value:16}@property --vui-title-trim{syntax:"*";inherits:false;initial-value:trim-both}@property --vui-title-trim-type{syntax:"*";inherits:false;initial-value:cap alphabetic}@property --vui-title-padding-inline-start{syntax:"<length>";inherits:false;initial-value:0}@property --vui-title-padding-inline-end{syntax:"<length>";inherits:false;initial-value:0}@property --vui-title-padding-block-start{syntax:"<length>";inherits:false;initial-value:0}@property --vui-title-padding-block-end{syntax:"<length>";inherits:false;initial-value:0}@property --vui-title-font-size{syntax:"<length>";inherits:false;initial-value:1rem}@property --vui-title-line-height{syntax:"normal | <number> | <length-percentage>";inherits:false;initial-value:normal}@property --vui-title-letter-spacing{syntax:"normal | <length>";inherits:false;initial-value:normal}@property --__title-letter-spacing{syntax:"normal | <length>";inherits:false;initial-value:normal}@property --vui-title-text-transform{syntax:"none | capitalize | uppercase | lowercase";inherits:false;initial-value:none}@property --vui-title-font-family{syntax:"*";inherits:false;initial-value:sans-serif}@property --__title-fluid{syntax:"<number>";inherits:false;initial-value:0}@property --__title-size-min{syntax:"<length>";inherits:false;initial-value:1rem}@property --__title-size-max{syntax:"<length>";inherits:false;initial-value:1rem}.viraui__title-module__Title_CXMUX{--__title-fluid:calc((100vi - 320px) / 1125px);--__title-size-min:var(--font-scale-h2);--__title-size-max:var(--font-scale-h1);--vui-title-font-size:clamp(
+@layer viraui.preflight, viraui.components, viraui.overrides;@layer viraui.components{@property --vui-title-align{syntax:"*";inherits:false;initial-value:start}@property --vui-title-max-width{syntax:"*";inherits:false;initial-value:none}@property --vui-title-literal-color{syntax:"<color>";inherits:false;initial-value:#0000}@property --vui-title-white-space{syntax:"*";inherits:false;initial-value:normal}@property --vui-title-wrap{syntax:"*";inherits:false;initial-value:pretty}@property --vui-title-font-weight{syntax:"<number>";inherits:false;initial-value:500}@property --vui-title-font-width{syntax:"<number>";inherits:false;initial-value:100}@property --vui-title-font-opsz{syntax:"<number>";inherits:false;initial-value:16}@property --vui-title-trim{syntax:"*";inherits:false;initial-value:trim-both}@property --vui-title-trim-type{syntax:"*";inherits:false;initial-value:cap alphabetic}@property --vui-title-padding-inline-start{syntax:"<length>";inherits:false;initial-value:0}@property --vui-title-padding-inline-end{syntax:"<length>";inherits:false;initial-value:0}@property --vui-title-padding-block-start{syntax:"<length>";inherits:false;initial-value:0}@property --vui-title-padding-block-end{syntax:"<length>";inherits:false;initial-value:0}@property --vui-title-font-size{syntax:"<length>";inherits:false;initial-value:1rem}@property --vui-title-line-height{syntax:"normal | <number> | <length-percentage>";inherits:false;initial-value:normal}@property --vui-title-letter-spacing{syntax:"normal | <length>";inherits:false;initial-value:normal}@property --__title-letter-spacing{syntax:"normal | <length>";inherits:false;initial-value:normal}@property --vui-title-text-transform{syntax:"none | capitalize | uppercase | lowercase";inherits:false;initial-value:none}@property --vui-title-font-family{syntax:"*";inherits:false;initial-value:sans-serif}@property --__title-fluid{syntax:"<number>";inherits:false;initial-value:0}@property --__title-size-min{syntax:"<length>";inherits:false;initial-value:1rem}@property --__title-size-max{syntax:"<length>";inherits:false;initial-value:1rem}.viraui__title-module__Title_CXMUX{--__title-fluid:calc((100vi - 320px) / 1125px);--__title-size-min:var(--font-scale-h2);--__title-size-max:var(--font-scale-h1);--vui-title-font-size:clamp(
     var(--__title-size-min),
     calc(var(--__title-size-min) + (var(--__title-size-max) - var(--__title-size-min)) * var(--__title-fluid)),
     var(--__title-size-max)
-  );--vui-title-font-family:var(--font-family-heading);--vui-title-line-height:var(--font-leading-m);--__title-letter-spacing:-0.03em;margin:0;max-inline-size:var(--vui-title-max-width);font-family:var(--vui-title-font-family);font-size:var(--vui-title-font-size);line-height:var(--vui-title-line-height);letter-spacing:var(--__title-letter-spacing);text-transform:var(--vui-title-text-transform);white-space:var(--vui-title-white-space);word-break:break-word;font-weight:var(--vui-title-font-weight);font-stretch:calc(var(--vui-title-font-width) * 1%);font-optical-sizing:auto;font-variation-settings:"wght" var(--vui-title-font-weight),"wdth" var(--vui-title-font-width),"opsz" var(--vui-title-font-opsz);text-box:var(--vui-title-trim) var(--vui-title-trim-type);display:inline-flex;&[data-title-has-align=true]{text-align:var(--vui-title-align)}&[data-title-has-tracking=true]{letter-spacing:var(--vui-title-letter-spacing)}&[data-title-balanced=true]{text-wrap:balance}&[data-title-selection=false]{-webkit-user-select:none;user-select:none}&[data-title-has-padding=true]{padding:var(--vui-title-padding-block-start) var(--vui-title-padding-inline-end) var(--vui-title-padding-block-end) var(--vui-title-padding-inline-start)}&[data-title-size=display]{--__title-size-min:var(--font-scale-h1);--__title-size-max:var(--font-scale-display)}&[data-title-size="2"]{--__title-size-min:var(--font-scale-h3);--__title-size-max:var(--font-scale-h2)}&[data-title-size="3"]{--__title-size-min:var(--font-scale-h4);--__title-size-max:var(--font-scale-h3)}&[data-title-size="4"]{--__title-size-min:var(--font-scale-h5);--__title-size-max:var(--font-scale-h4)}&[data-title-size="5"]{--__title-size-min:var(--font-scale-h6);--__title-size-max:var(--font-scale-h5);--__title-letter-spacing:-0.02em}&[data-title-size="6"]{--__title-size-min:var(--font-scale-body-m);--__title-size-max:var(--font-scale-h6);--__title-letter-spacing:-0.02em}&[data-title-fluid=false]{--vui-title-font-size:var(--__title-size-max)}@container root style(--effect-fluid-typography: initial){--vui-title-font-size:var(--__title-size-max)}&[data-title-has-literal-color=true]{color:var(--vui-title-literal-color)}&[data-title-line-height=none]{--vui-title-line-height:0}&[data-title-line-height=xs]{--vui-title-line-height:var(--font-leading-xs)}&[data-title-line-height=s]{--vui-title-line-height:var(--font-leading-s)}&[data-title-line-height=m]{--vui-title-line-height:var(--font-leading-m)}&[data-title-line-height=l]{--vui-title-line-height:var(--font-leading-l)}}}
+  );--vui-title-font-family:var(--font-family-heading);--vui-title-line-height:var(--font-leading-m);--__title-letter-spacing:-0.03em;margin:0;max-inline-size:var(--vui-title-max-width);font-family:var(--vui-title-font-family);font-size:var(--vui-title-font-size);line-height:var(--vui-title-line-height);letter-spacing:var(--__title-letter-spacing);text-transform:var(--vui-title-text-transform);text-wrap:var(--vui-title-wrap);white-space:var(--vui-title-white-space);word-break:break-word;font-weight:var(--vui-title-font-weight);font-stretch:calc(var(--vui-title-font-width) * 1%);font-optical-sizing:auto;font-variation-settings:"wght" var(--vui-title-font-weight),"wdth" var(--vui-title-font-width),"opsz" var(--vui-title-font-opsz);text-box:var(--vui-title-trim) var(--vui-title-trim-type);display:inline-flex;&[data-title-has-align=true]{text-align:var(--vui-title-align)}&[data-title-has-tracking=true]{letter-spacing:var(--vui-title-letter-spacing)}&[data-title-selection=false]{-webkit-user-select:none;user-select:none}&[data-title-has-padding=true]{padding:var(--vui-title-padding-block-start) var(--vui-title-padding-inline-end) var(--vui-title-padding-block-end) var(--vui-title-padding-inline-start)}&[data-title-size=display]{--__title-size-min:var(--font-scale-h1);--__title-size-max:var(--font-scale-display)}&[data-title-size="2"]{--__title-size-min:var(--font-scale-h3);--__title-size-max:var(--font-scale-h2)}&[data-title-size="3"]{--__title-size-min:var(--font-scale-h4);--__title-size-max:var(--font-scale-h3)}&[data-title-size="4"]{--__title-size-min:var(--font-scale-h5);--__title-size-max:var(--font-scale-h4)}&[data-title-size="5"]{--__title-size-min:var(--font-scale-h6);--__title-size-max:var(--font-scale-h5);--__title-letter-spacing:-0.02em}&[data-title-size="6"]{--__title-size-min:var(--font-scale-body-m);--__title-size-max:var(--font-scale-h6);--__title-letter-spacing:-0.02em}&[data-title-fluid=false]{--vui-title-font-size:var(--__title-size-max)}@container root style(--effect-fluid-typography: initial){--vui-title-font-size:var(--__title-size-max)}&[data-title-has-literal-color=true]{color:var(--vui-title-literal-color)}&[data-title-line-height=none]{--vui-title-line-height:0}&[data-title-line-height=xs]{--vui-title-line-height:var(--font-leading-xs)}&[data-title-line-height=s]{--vui-title-line-height:var(--font-leading-s)}&[data-title-line-height=m]{--vui-title-line-height:var(--font-leading-m)}&[data-title-line-height=l]{--vui-title-line-height:var(--font-leading-l)}}}

package/dist/components/title/title.d.ts

@@ -72,7 +72,9 @@ export type TitleProps = React.ComponentPropsWithoutRef<'span'> & {
      */
     maxWidth?: string;
     /**
-     * Controls white-space preservation and wrapping behavior.
+     * Controls white-space collapse/preserve (`white-space`).
+     * Prefer `whiteSpace="nowrap"` for single-line metrics/chrome (also collapses spaces).
+     * For wrapping algorithm / even line lengths use `wrap` (`text-wrap`) — not this prop.
      *
      * @defaultValue 'normal'
      */
@@ -94,13 +96,14 @@ export type TitleProps = React.ComponentPropsWithoutRef<'span'> & {
      */
     transform?: React.CSSProperties['textTransform'];
     /**
-     * Enables balanced wrapping for block-like titles.
-     * Prefer on short wrapping heads (hero, empty state, section);
-     * omit for single-line / `whiteSpace="nowrap"` metrics.
+     * Controls CSS `text-wrap` (wrapping algorithm / wrap on-off).
+     * Default `pretty` for orphan-aware titles. Prefer `balance` on short multi-line
+     * heads that need even line lengths. Use `wrap="nowrap"` only when you need no wrap
+     * without changing white-space collapse; prefer `whiteSpace="nowrap"` for metrics.
      *
-     * @defaultValue false
+     * @defaultValue 'pretty'
      */
-    balanced?: boolean;
+    wrap?: React.CSSProperties['textWrap'];
     /**
      * Enables text selection on the rendered copy.
      *

package/dist/components/title/title.js

@@ -4,7 +4,7 @@ import { resolveAxisPadding } from "../../core/styles/resolve-axis-padding.js";
 import title_module_default from "./title.module.js";
 import { useRender } from "@base-ui/react/use-render";
 //#region src/components/title/title.tsx
-var Title = ({ align, balanced = false, selection = true, className, color, fluid = true, fontWidth, hPadding, size = "1", lineHeight = "m", maxWidth, opticalSize, ref, render, style, tracking, transform, trim = "both", trimType = "cap alphabetic", vPadding, weight, whiteSpace = "normal", ...otherProps }) => {
+var Title = ({ align, selection = true, className, color, fluid = true, fontWidth, hPadding, size = "1", lineHeight = "m", maxWidth, opticalSize, ref, render, style, tracking, transform, trim = "both", trimType = "cap alphabetic", vPadding, weight, whiteSpace = "normal", wrap = "pretty", ...otherProps }) => {
 	const hasAlign = align !== void 0;
 	const hasPadding = Boolean(hPadding || vPadding);
 	const hasTracking = tracking !== void 0;
@@ -13,6 +13,7 @@ var Title = ({ align, balanced = false, selection = true, className, color, flui
 		"--vui-title-max-width": maxWidth ?? "none",
 		"--vui-title-literal-color": color,
 		"--vui-title-white-space": whiteSpace,
+		"--vui-title-wrap": wrap,
 		...hasTracking && { "--vui-title-letter-spacing": tracking },
 		"--vui-title-text-transform": transform,
 		"--vui-title-trim": trim ? `trim-${trim}` : "none",
@@ -32,7 +33,6 @@ var Title = ({ align, balanced = false, selection = true, className, color, flui
 			...otherProps,
 			"data-title-size": size,
 			"data-title-line-height": lineHeight,
-			"data-title-balanced": balanced ? "true" : "false",
 			"data-title-selection": selection ? "true" : "false",
 			"data-title-fluid": fluid ? "true" : "false",
 			"data-title-has-align": hasAlign ? "true" : "false",

package/dist/specs/components/prose/meta.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <meta id="prose" title="Prose" category="typography" shared_contract="prose">
-  <summary>Text-wall grouping region (articles, docs, privacy) with heading-aware em rhythm; reading column via parent Stack `maxWidth` sized for body Text `size`.</summary>
+  <summary>Text-wall grouping region (articles, docs, privacy) with heading-aware em rhythm, region `wrap` (default `pretty`), and reading column via parent Stack `maxWidth` sized for body Text `size`.</summary>
   <exports>
     <export name="Prose" />
   </exports>

package/dist/specs/components/prose/patterns.xml

@@ -36,7 +36,7 @@
   </Prose>
 </Stack>
 ]]></tsx>
-    <notes>Text-wall path: Prose for rhythm + Stack measure sized for body `size` (here `s` → narrower than `m`). Not for short card blurbs — those stay Text/Title props (`maxWidth` / `balanced`).</notes>
+    <notes>Text-wall path: Prose for rhythm + Stack measure sized for body `size` (here `s` → narrower than `m`). Not for short card blurbs — those stay Text/Title props (`maxWidth` / `wrap`).</notes>
   </example>
 
   <example title="Density and region align">

package/dist/specs/components/prose/props.xml

@@ -3,12 +3,12 @@
   <when_to_use>
     <item>Text walls — articles, docs, privacy/terms, long editorial — whose direct children are headings and blocks that need heading-aware vertical rhythm</item>
     <item>Article, docs, or changelog regions where Stack `rowGap` would make heading→body and body→body the same</item>
-    <item>Optional `gap` density (`s` / `m` / `l`) and region `align` (Title/Text that omit `align` inherit it)</item>
+    <item>Optional `gap` density (`s` / `m` / `l`), region `align` (Title/Text that omit `align` inherit it), and region `wrap` (default `pretty`; inherits to descendants)</item>
     <item>Reading column via parent Stack `maxWidth` sized for the body Text `size` (smaller → narrower; not one fixed `65ch`–`75ch`); edge-to-edge wall of text is not OK</item>
   </when_to_use>
   <when_not_to_use>
     <item>UI chrome spacing (cards, toolbars, form rows) — use Stack `rowGap` / `columnGap`</item>
-    <item>Short card/hero blurbs “for leading” — use Text/Title `lineHeight` / `maxWidth` / `balanced`</item>
+    <item>Short card/hero blurbs “for leading” — use Text/Title `lineHeight` / `maxWidth` / `wrap` instead</item>
     <item>Restyling type, lists, links, or tables — stay on Title / Text / consumer CSS</item>
     <item>Markdown parse or sanitize — Prose only spaces matching direct children</item>
   </when_not_to_use>
@@ -18,6 +18,9 @@
   <prop name="gap" kind="react">
     <description>Em density for heading-aware vertical rhythm (`s` &lt; `m` &lt; `l`).</description>
   </prop>
+  <prop name="wrap" kind="react">
+    <description>Controls CSS `text-wrap` on the Prose root (inherits to descendants unless a child overrides). Default `pretty` for orphan-aware article walls. Prefer `balance` only on short multi-line blocks that need even line lengths. Single-line metrics stay on child Text/Title `whiteSpace`.</description>
+  </prop>
   <prop name="ref" kind="react">
     <description>Ref forwarded to the rendered prose root element.</description>
   </prop>
@@ -36,4 +39,7 @@
   <prop name="gap-heading-start" kind="css">
     <description>Gap after a heading onto the next sibling (`--vui-prose-gap-heading-start`). Default `1.3em` (`l`).</description>
   </prop>
+  <prop name="wrap" kind="css">
+    <description>Text-wrap on the Prose root (`--vui-prose-wrap`; inherits). Prefer the `wrap` React prop; default `pretty`.</description>
+  </prop>
 </props>

package/dist/specs/components/prose/usage.xml

@@ -6,10 +6,11 @@
   <do>Keep a reading column: wrap Prose in Stack `maxWidth` in **`ch`** sized for the **body Text `size`** (smaller type → narrower; `m` mid band; large body → wider — not one fixed band for every article); prefer `ch` over rem; edge-to-edge wall of text is not OK</do>
   <do>Use `render={&lt;article /&gt;}` (or another landmark) when the region is the document landmark; name it if the landmark needs a name</do>
   <do>Leave type on Title/Text; Title inside Prose uses `lineHeight=&quot;s&quot;`; body leading via Text `lineHeight` per block (`m` / `l` / `s`); override `--vui-prose-gap-*` on the Prose root only when the em triple must change</do>
+  <do>Default Prose `wrap` is `pretty` (inherits to children). Prefer `wrap=&quot;balance&quot;` only when short multi-line blocks in the region need even line lengths; single-line metrics use child Text/Title `whiteSpace=&quot;nowrap&quot;`</do>
   <dont>Using Stack `rowGap` as article rhythm — one gap cannot split heading→body vs body→body</dont>
   <dont>Expecting default Title/Text `span` hosts to join rhythm — they are not heading/block tags</dont>
   <dont>Setting `as` — replace the root with `render` only</dont>
   <dont>Setting `align` on every Title/Text inside Prose when one Prose `align` covers the region</dont>
   <dont>Setting a widget `role` on Prose, or painting font/color/list/link chrome in Prose CSS</dont>
-  <dont>Wrapping a short UI blurb in Prose “for leading” — use Text/Title `lineHeight` / `maxWidth` / `balanced` instead</dont>
+  <dont>Wrapping a short UI blurb in Prose “for leading” — use Text/Title `lineHeight` / `maxWidth` / `wrap` instead</dont>
 </usage>

package/dist/specs/components/text/meta.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <meta id="text" title="Text" category="typography" shared_contract="text">
-  <summary>Theme-aware body-copy primitive with tone, family, sizing, and readable-measure props (`maxWidth` / `lineHeight` / `balanced`).</summary>
+  <summary>Theme-aware body-copy primitive with tone, family, sizing, and readable-measure props (`maxWidth` / `lineHeight` / `wrap`).</summary>
   <exports>
     <export name="Text" />
   </exports>

package/dist/specs/components/text/patterns.xml

@@ -6,15 +6,15 @@
   <example title="Auth muted lead (readable measure)">
     <tsx><![CDATA[
 <Stack vPadding={[0, 'l']} rowGap="xl" maxWidth="70ch">
-  <Title size="1" render={<h1 />} maxWidth="36ch" lineHeight="s" balanced>
+  <Title size="1" render={<h1 />} maxWidth="36ch" lineHeight="s" wrap="balance">
     Design systems that ship
   </Title>
-  <Text size="2xl" tone="muted" maxWidth="68ch" balanced>
+  <Text size="2xl" tone="muted" maxWidth="68ch" wrap="balance">
     Login to create custom ViraUI themes, access prompts and more.
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From `auth/login-view`. Cap ~10–12 words/line with `maxWidth` in `ch` scaled to size (`2xl` wider than `s`); `balanced` on short wrapping hero copy; `lineHeight="s"` on large Title. Prefer `ch` over rem. No CSS width/line-height.</notes>
+    <notes>From `auth/login-view`. Cap ~10–12 words/line with `maxWidth` in `ch` scaled to size (`2xl` wider than `s`); `wrap="balance"` on short even-rag hero copy (default `pretty` covers most body); `lineHeight="s"` on large Title. Prefer `ch` over rem. No CSS width/line-height.</notes>
   </example>
 
   <example title="Card section blurb">
@@ -23,12 +23,12 @@
   <Title size="6" render={<h2 />}>
     Payout Threshold
   </Title>
-  <Text tone="muted" size="s" maxWidth="45ch" balanced>
+  <Text tone="muted" size="s" maxWidth="45ch">
     Set the minimum balance required before a payout is triggered.
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From preview-grid `payout-threshold` (+ preferences / workspace-usage). Default pairing: Title + muted `size="s"` Text; short blurb prefers `maxWidth` in `ch` + `balanced`.</notes>
+    <notes>From preview-grid `payout-threshold` (+ preferences / workspace-usage). Default pairing: Title + muted `size="s"` Text; short blurb prefers `maxWidth` in `ch` (default `wrap="pretty"`).</notes>
   </example>
 
   <example title="Nested weight + tone">
@@ -52,16 +52,16 @@
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From preview-grid `payout-threshold`. `family="mono"` + muted xs for metric chrome — single-line; no `balanced`.</notes>
+    <notes>From preview-grid `payout-threshold`. `family="mono"` + muted xs for metric chrome — single-line; prefer `whiteSpace="nowrap"` when overflow risk; do not use `wrap="nowrap"` for metrics.</notes>
   </example>
 
   <example title="Form success paragraph">
     <tsx><![CDATA[
-<Text render={<p />} maxWidth="60ch" balanced>
+<Text render={<p />} maxWidth="60ch">
   Check your email — we sent a link to your@email.com
 </Text>
 ]]></tsx>
-    <notes>From `auth/login-form` acknowledged state. `render={<p />}` for block semantics; short wrap prefers `balanced` + `ch` measure.</notes>
+    <notes>From `auth/login-form` acknowledged state. `render={<p />}` for block semantics; short wrap relies on default `pretty` + `ch` measure.</notes>
   </example>
 
   <example title="Prose link">
@@ -76,15 +76,15 @@
   <example title="Empty-state centered">
     <tsx><![CDATA[
 <Stack hAlign="center" rowGap="m" maxWidth="36ch">
-  <Title align="center" size="5" render={<h3 />} balanced>
+  <Title align="center" size="5" render={<h3 />} wrap="balance">
     No Team Members
   </Title>
-  <Text size="s" align="center" maxWidth="40ch" tone="muted" balanced>
+  <Text size="s" align="center" maxWidth="40ch" tone="muted" wrap="balance">
     Invite your team to collaborate on this project.
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From preview-grid `empty-team`. Centered muted copy with `maxWidth` in `ch` + `balanced`; Stack owns column cap / centering.</notes>
+    <notes>From preview-grid `empty-team`. Centered muted copy with `maxWidth` in `ch` + `wrap="balance"` for even rag; Stack owns column cap / centering.</notes>
   </example>
 
   <example title="Claimable balance rows">

package/dist/specs/components/text/props.xml

@@ -2,7 +2,7 @@
 <props surface="text">
   <when_to_use>
     <item>Body copy with semantic tone (including brand `primary`) and token-backed typography</item>
-    <item>Readable UI measure (~10–12 words/line) via `maxWidth` / parent Stack `maxWidth` **scaled to `size`** (smaller → narrower), `lineHeight` matched to size, and `balanced` on short wrapping paragraphs</item>
+    <item>Readable UI measure (~10–12 words/line) via `maxWidth` / parent Stack `maxWidth` **scaled to `size`** (smaller → narrower), `lineHeight` matched to size, and `wrap` (default `pretty`; `balance` on short even-rag blurbs)</item>
     <item>Letter-spacing via `tracking` or text-transform via `transform` — prefer props over CSS on the Text root</item>
     <item>Helper, label, or inline copy inside other components</item>
     <item>Mono or body family text; size locked by default (`fluid` false → --font-scale-body-*); pass `fluid` for viewport clamp (also gated by theme `--effect-fluid-typography`)</item>
@@ -11,14 +11,11 @@
     <item>Headings or display typography — use Title</item>
     <item>Heading semantics without an appropriate render root</item>
     <item>Long-form heading-aware article rhythm — use Prose (keep a reading column)</item>
-    <item>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap: balance` / `width: 100%` when `tracking` / `transform` / `lineHeight` / `maxWidth` / `balanced` / parent Stack `fullWidth` cover the need</item>
+    <item>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap` / `width: 100%` when `tracking` / `transform` / `lineHeight` / `maxWidth` / `wrap` / parent Stack `fullWidth` cover the need</item>
   </when_not_to_use>
   <prop name="align" kind="react">
     <description>Aligns text using logical alignment values. Omit so `text-align` inherits from the parent.</description>
   </prop>
-  <prop name="balanced" kind="react">
-    <description>Enables balanced wrapping for block-like copy. Prefer on short wrapping UI paragraphs (hero lead, empty state, card blurb); omit when single-line or intentional ragged.</description>
-  </prop>
   <prop name="color" kind="react">
     <description>Applies a literal color escape hatch when semantic `tone` is not used.</description>
   </prop>
@@ -77,7 +74,10 @@
     <description>Selects a semantic weight keyword or a numeric weight (`font-weight` + `wght` axis).</description>
   </prop>
   <prop name="whiteSpace" kind="react">
-    <description>Controls white-space preservation and wrapping behavior.</description>
+    <description>Controls white-space collapse/preserve (`white-space`). Prefer `whiteSpace=&quot;nowrap&quot;` for single-line metrics/chrome (also collapses spaces). For wrapping algorithm / even line lengths use `wrap` (`text-wrap`) — not this prop.</description>
+  </prop>
+  <prop name="wrap" kind="react">
+    <description>Controls CSS `text-wrap` (wrapping algorithm / wrap on-off). Default `pretty` for orphan-aware UI copy. Prefer `balance` on short multi-line heads/blurbs that need even line lengths. Use `wrap=&quot;nowrap&quot;` only when you need no wrap without changing white-space collapse; prefer `whiteSpace=&quot;nowrap&quot;` for metrics.</description>
   </prop>
   <prop name="align" kind="css">
     <description>Text alignment on the root when the `align` prop is set; omitted inherits parent `text-align`.</description>
@@ -131,6 +131,9 @@
     <description>Text transform on the root. Prefer the `transform` React prop; set this hook only when theming beyond the prop.</description>
   </prop>
   <prop name="white-space" kind="css">
-    <description>White-space behavior on the root.</description>
+    <description>White-space behavior on the root (`--vui-text-white-space`). Prefer the `whiteSpace` React prop.</description>
+  </prop>
+  <prop name="wrap" kind="css">
+    <description>Text-wrap on the root (`--vui-text-wrap`). Prefer the `wrap` React prop; default `pretty`.</description>
   </prop>
 </props>

package/dist/specs/components/text/usage.xml

@@ -3,7 +3,7 @@
   <do>Body copy, helpers, and labels — semantic `tone` before literal `color` or raw theme vars</do>
   <do>Readable UI measure: aim ~10–12 words per line — `maxWidth` / Stack `maxWidth` **scales with `size`** (smaller type → narrower column; larger → wider); prefer **`ch`** in patterns/examples (not `rem`); never one fixed ch for every size; no full-bleed wrapping blurbs</do>
   <do>Match `lineHeight` to size/context (`m` default on root; `l` when open; `s` for dense chrome); omit `lineHeight`/`size` on nested Text so the outer Text owns type</do>
-  <do>Prefer `balanced` on short wrapping paragraphs (hero lead, empty state, card blurb); omit when single-line or intentional ragged</do>
+  <do>Default `wrap` is `pretty` (orphan-aware). Prefer `wrap=&quot;balance&quot;` on short multi-line blurbs that need even line lengths; use `whiteSpace=&quot;nowrap&quot;` for single-line metrics (not `wrap=&quot;nowrap&quot;` unless you must keep space collapse unchanged)</do>
   <do>Omit `align` so copy inherits parent `text-align`; pass `align` only to override</do>
   <do>Card / settings section blurb: Stack `rowGap` + Title heading + muted `size=&quot;s&quot;` Text — no invent CSS gap</do>
   <do>Settings row: Stack `direction=&quot;row&quot;` + Text label + Switch/Checkbox (or nest Text inside Switch `label`) — Surface for chrome</do>
@@ -16,7 +16,7 @@
   <do>Long articles / docs / privacy walls → Prose (not Text alone for heading-aware rhythm); still keep a reading column</do>
   <dont>Using Text for headings — use Title (`render` for h1–h6)</dont>
   <dont>Putting `data-no-link-style` on Text-as-a when the default underline hover is wanted</dont>
-  <dont>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap: balance` / `width: 100%` / `paddingBlock*` / `paddingInline*` when `tracking` / `transform` / `lineHeight` / `maxWidth` / `balanced` / Stack `fullWidth` / `hPadding`/`vPadding` tuples cover it</dont>
+  <dont>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap` / `width: 100%` / `paddingBlock*` / `paddingInline*` when `tracking` / `transform` / `lineHeight` / `maxWidth` / `wrap` / Stack `fullWidth` / `hPadding`/`vPadding` tuples cover it</dont>
   <dont>Setting body color with raw `--global-*` when `tone` covers the role</dont>
   <dont>Full-bleed marketing/UI paragraphs across a wide shell when a ~10–12-word measure fits</dont>
   <dont>Reusing a large-body shell (`~65ch`–`75ch` / wide rem) for small `size` copy — column width must track `size`</dont>

package/dist/specs/components/title/meta.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <meta id="title" title="Title" category="typography" shared_contract="title">
-  <summary>Theme-aware heading and display typography with readable-measure props (`maxWidth` / `lineHeight` / `balanced`).</summary>
+  <summary>Theme-aware heading and display typography with readable-measure props (`maxWidth` / `lineHeight` / `wrap`).</summary>
   <exports>
     <export name="Title" />
   </exports>

package/dist/specs/components/title/patterns.xml

@@ -5,11 +5,11 @@
 
   <example title="Auth hero heading (readable measure)">
     <tsx><![CDATA[
-<Title size="1" render={<h1 />} maxWidth="36ch" lineHeight="s" balanced>
+<Title size="1" render={<h1 />} maxWidth="36ch" lineHeight="s" wrap="balance">
   Ship real UI at the speed of thought.
 </Title>
 ]]></tsx>
-    <notes>From `auth/login-view`. Pair `size` with `render={<h1 />}`; cap measure in `ch`; `lineHeight="s"` + `balanced` on wrapping display. Prefer `ch` over rem. (Live app nests Typewriter inside; see typewriter patterns.)</notes>
+    <notes>From `auth/login-view`. Pair `size` with `render={<h1 />}`; cap measure in `ch`; `lineHeight="s"` + `wrap="balance"` on short even-rag display (default `pretty` covers most titles). Prefer `ch` over rem. (Live app nests Typewriter inside; see typewriter patterns.)</notes>
   </example>
 
   <example title="Card section heading">
@@ -18,21 +18,21 @@
   <Title size="6" render={<h2 />}>
     Preferences
   </Title>
-  <Text size="s" maxWidth="45ch" tone="muted" balanced>
+  <Text size="s" maxWidth="45ch" tone="muted">
     Manage your account settings and notifications.
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From preview-grid `preferences` (+ payout-threshold, notifications, …). Dense card titles use `size="6"` + `h2`; blurb keeps `ch` measure + `balanced`.</notes>
+    <notes>From preview-grid `preferences` (+ payout-threshold, notifications, …). Dense card titles use `size="6"` + `h2`; blurb keeps `ch` measure (default `wrap="pretty"`).</notes>
   </example>
 
   <example title="Empty-state heading">
     <tsx><![CDATA[
-<Title align="center" size="5" render={<h3 />} balanced>
+<Title align="center" size="5" render={<h3 />} wrap="balance">
   No Team Members
 </Title>
 ]]></tsx>
-    <notes>From preview-grid `empty-team`. Centered mid-size heading; prefer `balanced` when the title wraps; pair with muted Text below.</notes>
+    <notes>From preview-grid `empty-team`. Centered mid-size heading; prefer `wrap="balance"` when the title wraps and needs even rag; pair with muted Text below.</notes>
   </example>
 
   <example title="Display metric">
@@ -46,7 +46,7 @@
   </Text>
 </Stack>
 ]]></tsx>
-    <notes>From preview-grid `daily-activity-goal`. `size="display"` for hero numerals; `whiteSpace="nowrap"` keeps metric on one line — skip `balanced`.</notes>
+    <notes>From preview-grid `daily-activity-goal`. `size="display"` for hero numerals; `whiteSpace="nowrap"` keeps metric on one line — prefer that over `wrap="nowrap"`.</notes>
   </example>
 
   <example title="Balance display">
@@ -69,7 +69,7 @@
   <Title size="4" render={<h3 />}>
     Colors
   </Title>
-  <Text size="s" tone="muted" maxWidth="48ch" balanced>
+  <Text size="s" tone="muted" maxWidth="48ch">
     Preview of theme voice, contrast, and color rhythm across accents.
   </Text>
 </Stack>

package/dist/specs/components/title/props.xml

@@ -4,21 +4,18 @@
     <item>Headings and display text with title presets</item>
     <item>Semantic heading tags chosen explicitly through render</item>
     <item>Size and render paired together for most heading use cases</item>
-    <item>Readable wrapping titles: `maxWidth` (~10–12 words/line, **scaled to `size`** — smaller → narrower), `lineHeight` (`s` on large wrapping / inside Prose), and `balanced` on short multi-line heads</item>
+    <item>Readable wrapping titles: `maxWidth` (~10–12 words/line, **scaled to `size`** — smaller → narrower), `lineHeight` (`s` on large wrapping / inside Prose), and `wrap` (default `pretty`; `balance` on short even-rag heads)</item>
     <item>Letter-spacing via `tracking` or text-transform via `transform` — prefer props over CSS on the Title root</item>
     <item>Fluid clamp sizing across title appearance presets (theme `--effect-fluid-typography` or per-instance `fluid`; off → fixed at --font-scale-display / h-* for that size)</item>
   </when_to_use>
   <when_not_to_use>
     <item>Body copy — use Text</item>
     <item>Body or mono family typography</item>
-    <item>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap: balance` / `width: 100%` when `tracking` / `transform` / `lineHeight` / `maxWidth` / `balanced` / parent Stack `fullWidth` cover the need</item>
+    <item>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap` / `width: 100%` when `tracking` / `transform` / `lineHeight` / `maxWidth` / `wrap` / parent Stack `fullWidth` cover the need</item>
   </when_not_to_use>
   <prop name="align" kind="react">
     <description>Aligns text using logical alignment values. Omit so `text-align` inherits from the parent.</description>
   </prop>
-  <prop name="balanced" kind="react">
-    <description>Enables balanced wrapping for block-like titles. Prefer on short wrapping heads (hero, empty state, section); omit for single-line / `whiteSpace=&quot;nowrap&quot;` metrics.</description>
-  </prop>
   <prop name="color" kind="react">
     <description>Applies a literal color escape hatch.</description>
   </prop>
@@ -71,7 +68,10 @@
     <description>Overrides the size preset weight (`font-weight` + `wght` axis).</description>
   </prop>
   <prop name="whiteSpace" kind="react">
-    <description>Controls white-space preservation and wrapping behavior.</description>
+    <description>Controls white-space collapse/preserve (`white-space`). Prefer `whiteSpace=&quot;nowrap&quot;` for single-line metrics/chrome (also collapses spaces). For wrapping algorithm / even line lengths use `wrap` (`text-wrap`) — not this prop.</description>
+  </prop>
+  <prop name="wrap" kind="react">
+    <description>Controls CSS `text-wrap` (wrapping algorithm / wrap on-off). Default `pretty` for orphan-aware titles. Prefer `balance` on short multi-line heads that need even line lengths. Use `wrap=&quot;nowrap&quot;` only when you need no wrap without changing white-space collapse; prefer `whiteSpace=&quot;nowrap&quot;` for metrics.</description>
   </prop>
   <prop name="align" kind="css">
     <description>Title alignment on the root when the `align` prop is set; omitted inherits parent `text-align`.</description>
@@ -125,6 +125,9 @@
     <description>Text transform on the root. Prefer the `transform` React prop; set this hook only when theming beyond the prop.</description>
   </prop>
   <prop name="white-space" kind="css">
-    <description>White-space behavior on the root.</description>
+    <description>White-space behavior on the root (`--vui-title-white-space`). Prefer the `whiteSpace` React prop.</description>
+  </prop>
+  <prop name="wrap" kind="css">
+    <description>Text-wrap on the root (`--vui-title-wrap`). Prefer the `wrap` React prop; default `pretty`.</description>
   </prop>
 </props>

package/dist/specs/components/title/usage.xml

@@ -2,7 +2,7 @@
 <usage surface="title">
   <do>Headings and display type — pair `size` (visual preset) with `render={&lt;h1 /&gt;}`…`h6` for outline semantics (default root is `span`)</do>
   <do>Readable measure on wrapping titles: aim ~10–12 words per line — `maxWidth` / Stack `maxWidth` **scales with `size`** (smaller → narrower; larger → wider); prefer **`ch`** (not `rem`) in patterns/examples; large wrapping presets often `lineHeight=&quot;s&quot;`</do>
-  <do>Prefer `balanced` on short wrapping titles (hero, empty state, section head); omit when single-line / `whiteSpace=&quot;nowrap&quot;` metrics</do>
+  <do>Default `wrap` is `pretty`. Prefer `wrap=&quot;balance&quot;` on short multi-line heads that need even line lengths; use `whiteSpace=&quot;nowrap&quot;` for single-line metrics (not `wrap=&quot;nowrap&quot;` unless space collapse must stay unchanged)</do>
   <do>Omit `align` so the heading inherits parent `text-align`; pass `align` only to override</do>
   <do>Title inside Prose → `lineHeight=&quot;s&quot;`; long-form rhythm stays on Prose — not Stack `rowGap`</do>
   <do>Card / panel header: Stack `rowGap=&quot;xs&quot;` + Title + muted Text blurb — Surface for card chrome</do>
@@ -14,7 +14,7 @@
   <do>Title-as-prose-link (`render={&lt;a /&gt;}`) keeps preflight link chrome — omit `data-no-link-style`</do>
   <dont>Assuming `size` changes the HTML tag — choose `render` explicitly</dont>
   <dont>Using Title for long body paragraphs — use Text</dont>
-  <dont>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap: balance` / `width: 100%` / `paddingBlock*` / `paddingInline*` when props / Stack / `hPadding`/`vPadding` tuples cover it</dont>
-  <dont>Full-bleed wrapping headlines across a wide shell when a capped measure + `balanced` fits</dont>
+  <dont>Inventing CSS `letter-spacing` / `text-transform` / `line-height` / `max-width` / `text-wrap` / `width: 100%` / `paddingBlock*` / `paddingInline*` when props / Stack / `hPadding`/`vPadding` tuples cover it</dont>
+  <dont>Full-bleed wrapping headlines across a wide shell when a capped measure + `wrap` fits</dont>
   <dont>One fixed wide measure for every Title `size` — smaller presets need a narrower column for ~10–12 words/line</dont>
 </usage>

package/dist/specs/index.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<index package="@viraui/react" version="2026.9.0" generated="2026-10-15T06:47:40.657Z">
+<index package="@viraui/react" version="2026.9.1" generated="2026-10-15T08:18:55.911Z">
   <categories>
     <category id="layout" />
     <category id="action" />
@@ -312,7 +312,7 @@
     </units>
   </entry>
   <entry id="prose" category="typography" title="Prose">
-    <summary>Text-wall grouping region (articles, docs, privacy) with heading-aware em rhythm; reading column via parent Stack `maxWidth` sized for body Text `size`.</summary>
+    <summary>Text-wall grouping region (articles, docs, privacy) with heading-aware em rhythm, region `wrap` (default `pretty`), and reading column via parent Stack `maxWidth` sized for body Text `size`.</summary>
     <units>
       <unit kind="meta" href="components/prose/meta.xml" />
       <unit kind="a11y" href="components/prose/a11y.xml" />
@@ -442,7 +442,7 @@
     </units>
   </entry>
   <entry id="text" category="typography" title="Text">
-    <summary>Theme-aware body-copy primitive with tone, family, sizing, and readable-measure props (`maxWidth` / `lineHeight` / `balanced`).</summary>
+    <summary>Theme-aware body-copy primitive with tone, family, sizing, and readable-measure props (`maxWidth` / `lineHeight` / `wrap`).</summary>
     <units>
       <unit kind="meta" href="components/text/meta.xml" />
       <unit kind="a11y" href="components/text/a11y.xml" />
@@ -472,7 +472,7 @@
     </units>
   </entry>
   <entry id="title" category="typography" title="Title">
-    <summary>Theme-aware heading and display typography with readable-measure props (`maxWidth` / `lineHeight` / `balanced`).</summary>
+    <summary>Theme-aware heading and display typography with readable-measure props (`maxWidth` / `lineHeight` / `wrap`).</summary>
     <units>
       <unit kind="meta" href="components/title/meta.xml" />
       <unit kind="a11y" href="components/title/a11y.xml" />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viraui/react",
-  "version": "2026.9.0",
+  "version": "2026.9.1",
   "private": false,
   "files": [
     "dist"
@@ -28,7 +28,7 @@
   },
   "devDependencies": {
     "@base-ui/react": ">=1.8.0",
-    "@viraui/foundation": "2026.9.0",
+    "@viraui/foundation": "2026.9.1",
     "@viraui/icons": "2026.1.0",
     "@viraui/postcss-config": "2026.0.0",
     "@viraui/tsconfig": "2026.0.0",