@kurot/ui 3.1.0 → 3.3.0

package/docs/bitmap-label.md

@@ -0,0 +1,47 @@
+# BitmapLabel
+
+Available in UI 3.2.0 with `@kurot/core ^2.2.0`. Core resolves its published
+@kurot/bitmap-font dependency from npm. UI 3.2.0 is published;
+published UI 3.1.0 does not contain this component. Core 2.1.1 does not contain
+its required BitmapText rendering.
+
+UI 3.3.0 retains this API and raises the package's Core minimum to ^2.3.0 for
+RichLabel. During automatic sizing it also uses maxWidth when neither a parent
+width nor an explicit width is present, so wrapped height matches rendering.
+Changing an authored width also invalidates automatic height after layout.
+UI 3.3.0 builds and tests against published Core 2.3.1 without local overrides.
+
+```ts
+import { BitmapLabel } from '@kurot/ui';
+
+const label = new BitmapLabel('1,234.56');
+label.font = 'number_font_fnt';
+label.multiline = false;
+label.height = 100;
+group.addChild(label);
+```
+
+`font` accepts a BitmapFont, a configured resource name, or undefined to clear.
+Names resolve through the Core resource singleton. Preloaded names resolve
+synchronously during commitProperties; unloaded names start resource.load.
+Successful name resolution dispatches Event.COMPLETE; failed or incorrectly
+typed resources dispatch IOErrorEvent.IO_ERROR with source/error data.
+Superseded asynchronous requests cannot overwrite a newer font assignment,
+including A-to-B-to-A changes. The resource cache or caller retains ownership.
+
+Text assignments dispatch PropertyEvent.PROPERTY_CHANGE for binding. The
+component participates in normal layout, measurement and invalidation and owns
+one BitmapText child. Parent width constraints affect wrapping; measurements do
+not leave temporary width/height constraints on that child. textWidth/textHeight
+report content under the width constraint before height clipping.
+
+Properties: text, font, textAlign, verticalAlign, letterSpacing, lineSpacing,
+multiline and smoothing, plus ordinary Component properties. Tint is the ordinary
+DisplayObject tint. Alignments position glyphs without scaling them. Set scaleX
+and scaleY for decorative number sizing. Default multiline=true; explicit false
+keeps the first hard-separated line unwrapped.
+
+This initial change exposes a native UI component and supports programmatic
+skins. The ui-document built-in catalog, CLI KUI tag registry, Editor and
+ui-runtime materializers do not yet adopt BitmapLabel. Those require coordinated
+consumer releases; do not assume an installed compiler accepts the XML tag.

package/docs/label-text-layout.md

@@ -1,9 +1,14 @@
 # Label text layout and fitting
 
-This contract applies to UI 3.1.0 with Core >= 2.1.0 within Core 2.x. The public
+Introduced in UI 3.1.0 with Core >= 2.1.0, this contract is unchanged in UI 3.2.0,
+which requires Core ^2.2.0. The public
 `TextFitMode` type is `none | shrink`. Native UI depends only on Core. KUI
-authoring uses ui-document 0.9.x and matching CLI/ui-runtime releases; older
-consumers must update their dependency ranges before using the new fields.
+authoring introduced fitting metadata in ui-document 0.9.0 and retains it in
+0.11.0. Published CLI 3.3.0 and ui-runtime 0.8.2 use ui-document `^0.11.0`.
+Runtime 0.8.0's `^0.9.0` and runtime 0.8.1's `^0.10.0` peer ranges exclude
+the current kernel. Label presets are expanded into native properties before
+rendering; their precedence does not change fitting behavior. See the
+[project style contract](../../ui-document/docs/project-styles.md).
 
 ## Lines and bounds
 

package/docs/rich-label.md

@@ -0,0 +1,77 @@
+# RichLabel
+
+Native API introduced in UI 3.3.0, requiring Core ^2.3.0. Core 2.3.1 is
+published and installed from npm for this release's build and verification.
+
+```ts
+import { RichLabel } from '@kurot/ui';
+
+const label = new RichLabel([
+	{ text: 'Warning: ', style: { size: 20, bold: true, textColor: 0xff9900 } },
+	{ text: 'read this before continuing.', style: { size: 20, italic: true } },
+]);
+label.maxWidth = 240;
+group.addChild(label);
+```
+
+## Content and ownership
+
+RichLabel extends Component independently, not Label. Its only content interface
+is `textFlow: ITextElement[]`, using Core's text/style records. Whole-component
+`text`, `fontFamily`, `size`, `bold`, `italic`, `textColor`, `textFit`, `minFontSize`
+and `textStyle` are not exposed. Label presets do not apply to this component.
+
+Runs can specify font family, size, bold, italic, text color, stroke color and
+stroke width. Unspecified fields use the native TextField defaults captured at
+construction. In particular, an unstyled run does not inherit the previous run.
+All runs are laid out continuously; a style boundary does not introduce a word
+boundary or a new line. No HTML or markdown parsing is performed.
+
+The component copies runs and their styles on assignment and on reads. Mutating
+an input array or a returned snapshot does not change the component. Reassign
+an edited snapshot to apply it. Assigning [] clears content; assignment dispatches
+PropertyEvent.PROPERTY_CHANGE for `textFlow` after the new content is installed.
+
+## Layout
+
+Ordinary Component geometry, layout constraints, visibility and alpha remain
+available, together with these text-layout properties:
+
+| Property               | Default   | Contract                                                                  |
+| ---------------------- | --------- | ------------------------------------------------------------------------- |
+| multiline              | true      | False shows the first hard-separated line without width wrapping.         |
+| wordWrap               | true      | Unicode line-break opportunities; false wraps between graphemes.          |
+| lineSpacing            | 0         | Finite, nonnegative distance between lines.                               |
+| textAlign              | left      | left, center or right.                                                    |
+| verticalAlign          | top       | top, middle or bottom.                                                    |
+| textWidth / textHeight | Read-only | Complete content metrics under the current width, before height clipping. |
+
+Measurement uses parent-assigned width first, then explicit width, then a
+configured maxWidth, otherwise unconstrained width. Automatic height includes
+every wrapped line and inter-line spacing. Each line uses the largest font size
+of its runs, rather than imposing the TextField base size. Hard line separators
+and trailing blank lines follow the Core text contract. Core 2.3.1 corrects the
+base size of unstyled blank runs between styled runs; the API minimum stays 2.3.0. Empty content measures
+0 × 0; Component minWidth/minHeight can still enlarge its layout bounds.
+
+Fixed height clips drawing without discarding content. Alignment positions the
+continuous text block within the assigned bounds. One native TextField renders
+through Canvas 2D and WebGL; measurement never temporarily resizes that field.
+Unchanged content metrics are cached until size/content invalidation or a width
+change.
+
+## Font readiness and integration
+
+Load project fonts before measuring where possible. If fonts become ready later,
+call `label.invalidateSize()` to clear both component and native text metrics,
+then allow normal layout validation. RichLabel does not load font files or
+install global font-loading listeners.
+
+This release supports native code and programmatic skins. The current
+ui-document catalog, CLI KUI registry, ui-runtime materializer and Editor do not
+yet provide RichLabel authoring or serialization. Their later integration must
+keep textFlow ownership and the separation from ordinary Label presets.
+
+See [Core text layout](../../core/docs/text-layout.md) for Unicode wrapping,
+single-line behavior and independent measurement. Run `pnpm test:text-labels`
+after building Core and UI for minified Canvas/WebGL browser verification.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurot/ui",
-	"version": "3.1.0",
+	"version": "3.3.0",
 	"description": "EUI-compatible UI component framework for the Kurot game engine — skin-based components, layouts, data binding, view states",
 	"author": "Kelvin <kyia.x52@gmail.com>",
 	"license": "MIT",
@@ -30,15 +30,17 @@
 		"benchmark:compare": "playwright test --config examples/benchmark/playwright.config.ts",
 		"benchmark:smoke": "UI_BENCHMARK_PROFILE=smoke playwright test --config examples/benchmark/playwright.config.ts",
 		"build:benchmark": "vite --config vite.config.ts build",
-		"prepublishOnly": "npm run clean && npm run build"
+		"prepublishOnly": "npm run clean && npm run build",
+		"test:text-labels": "playwright test test/browser --workers=1"
 	},
 	"peerDependencies": {
-		"@kurot/core": "^2.1.0"
+		"@kurot/core": "^2.3.0"
 	},
 	"devDependencies": {
-		"@kurot/core": "^2.1.0",
+		"@kurot/core": "^2.3.1",
 		"@playwright/test": "1.62.1",
 		"@types/node": "^22.0.0",
+		"esbuild": "^0.28.2",
 		"happy-dom": "^20.8.9",
 		"typescript": "^5.6.0",
 		"vite": "^8.0.8",