@octane-xplat/macos-renderer 0.11.0 → 0.12.0

package/README.md

@@ -10,10 +10,11 @@ assets. The renderer owns views, layout, events, accessibility, and its hosted
 popups and sheets. It does not load web stylesheets or implement every
 NativeScript widget. See the [macOS harness](../../apps/macos/README.md) for
 the current component and service limits. The image-crop integration test compiles and mounts the public UI barrel.
-The full application harness has not been reverified by that test. A raw AppKit button
-`performClick` check also exposes an existing action-selector mismatch. Native
-click delivery needs separate repair and verification; the maintained consumer
-checks direct handler dispatch.
+The full application harness has not been reverified by that test. Registered
+action selectors match the assigned target/action strings, and the maintained
+consumer checks direct handler dispatch — but OS-level input delivery (a live
+AppKit `performClick`, control edits, gestures) has not been verified end to
+end.
 
 ## Configure an app
 
@@ -38,7 +39,7 @@ import { xplatMacOS } from '@octane-xplat/cli/macos/vite'
 export default defineConfig(({ mode }) => xplatMacOS(mode))
 ```
 
-The async preset bundles `src/main.mjs` into `dist/package-build/main.cjs`,
+The async preset bundles the packaged entry (`src/main.mjs` by default) into `dist/package-build/main.cjs`,
 selects macOS platform files, registers the universal renderer, aliases
 NativeScript compatibility imports, and externalizes only the native runtime
 and `node:` host imports. Unsupported host imports still fail CLI packaging.
@@ -47,7 +48,7 @@ No repository paths or harness fonts are needed.
 ```js
 import { xplatMacOS } from '@octane-xplat/cli/macos/vite'
 
-export default await xplatMacOS('production', { entry: 'src/main.mjs' })
+export default await xplatMacOS('production', { entry: 'src/main.ts' })
 ```
 
 Set these TypeScript options:
@@ -105,7 +106,7 @@ re-exports Octane's universal native runtime for compiler and hook imports.
 
 Use [the packaging guide](../../docs/start/toolchain.md#experimental-appkit-target)
 for `xplat.targets.macos` metadata, signing, and CLI commands. The
-[independent fixture](test/fixtures/main.mjs) demonstrates a complete host
+[independent fixture](test/fixtures/main.ts) demonstrates a complete host
 entry, including startup and shutdown, without importing the harness.
 
 ## Render local images and overlays
@@ -113,6 +114,8 @@ entry, including startup and shutdown, without importing the harness.
 Image sources can be base64 data URIs, local file paths, or `file://` URLs.
 An empty or unsupported source clears the old image. Remote URLs require a
 separate download; image loading does not perform synchronous network work.
+Uncached decodes resolve on a later run-loop turn, so a source change keeps
+the previous image until its replacement is ready.
 For centered contain-fit, pass `style={{ objectFit: 'contain' }}` to `Image`.
 This scales smaller images up while preserving their aspect ratio.
 
@@ -172,13 +175,148 @@ demonstrates app-owned descriptors and packaged font bytes.
 registerFontFamily('Acme Sans', [{ weight: 400, descriptor: regularFace }])
 ```
 
+## Keep labels inside their rows
+
+Use a single-line label with tail ellipsis for a long tab title or suggestion.
+The application assigns the frame; AppKit redraws truncation as its width changes.
+The full string remains in the native value for copying through application code
+and accessibility; the renderer never replaces it with shortened text.
+
+```tsx
+export function TabTitle(props: { title: string; width: number }) {
+	return (
+		<label
+			text={props.title}
+			maxLines={1}
+			whiteSpace="nowrap"
+			textOverflow="ellipsis"
+			style={{ width: props.width, height: 28 }}
+		/>
+	)
+}
+```
+
+The supported subset is `whiteSpace="normal"` (word wrapping) or `"nowrap"`,
+`textOverflow="clip"` or `"ellipsis"`, and non-negative integer `maxLines`.
+`nowrap` takes precedence over a multiline limit; `maxLines={1}` also forces
+one line. For wrapping labels, ellipsis appears on the last visible line when
+the line limit or frame height is reached. `maxLines={0}` means unlimited
+lines. Other values fail with an explicit renderer error; CSS whitespace
+collapse/preservation modes are not implemented.
+
+```tsx
+export function Suggestion(props: { title: string }) {
+	return (
+		<label
+			text={props.title}
+			whiteSpace="normal"
+			maxLines={2}
+			textOverflow="ellipsis"
+			style={{ width: 240 }}
+		/>
+	)
+}
+```
+
+Updating or removing these props reapplies the native settings. Removed props
+restore normal wrapping, unlimited lines, and clipping. An explicit multiline
+limit (including zero) releases the renderer's implicit one-line height so
+AppKit can measure the text; an assigned `style.height` still controls the
+frame. With no line-limit prop, the existing default label height remains one
+font-based line unless the application supplies its own height or line height.
+
+```tsx
+export function UpdatingTitle(props: { title: string; compact: boolean }) {
+	return (
+		<label
+			text={props.title}
+			maxLines={props.compact ? 1 : 2}
+			textOverflow={props.compact ? 'ellipsis' : undefined}
+			style={{ width: 240 }}
+		/>
+	)
+}
+```
+
+## Container layout channels
+
+A container can arrange its content through direct props or an inline style
+object. Both declarations below make the same row with a 12-point gap and
+vertically centered content. The renderer recognizes these inputs on
+`flexboxlayout` and `stack`; other elements retain unsupported-style diagnostics.
+
+```tsx
+/** @jsxImportSource @octane-xplat/macos-renderer */
+export function Rows() {
+	return <stack>
+		<flexboxlayout flexDirection="row" gap={12} alignItems="center" justifyContent="start">
+			<label text="Name" /><label text="Value" />
+		</flexboxlayout>
+		<flexboxlayout style={{ flexDirection: 'row', gap: 12, alignItems: 'center', justifyContent: 'start' }}>
+			<label text="Name" /><label text="Value" />
+		</flexboxlayout>
+	</stack>
+}
+```
+
+Inline style wins over recognized classes, which win over direct props,
+regardless of prop order. Removing or setting an input to `null` or `undefined`
+restores the next source. With no source, defaults are column direction, zero
+gap, stretch alignment, and start justification. Here, removing `style.gap`
+restores `gap-2` (8 points); removing the class then restores `gap={4}`.
+
+```tsx
+/** @jsxImportSource @octane-xplat/macos-renderer */
+export function ConflictingRow({ inlineGap }: { inlineGap?: number }) {
+	return <flexboxlayout gap={4} className="flex-row gap-2 items-center justify-end"
+		style={{ gap: inlineGap }}>
+		<label text="Name" /><label text="Value" />
+	</flexboxlayout>
+}
+```
+
+The supported subset is direction `row`/`column`; nonnegative numeric gaps
+in points; alignment `start`, `end`, `center`, `stretch`, and horizontal
+`baseline`; justification `start`, `end`, `center`, and `space-between`.
+`flex-start`/`flex-end` are accepted aliases. `rowGap` applies to columns and
+`columnGap` to rows; within each channel, the matching axis gap wins over `gap`.
+The class forms are `flex-row`/`flex-col`, `gap-1/2/3/4/6`,
+`items-start/end/center/stretch/baseline`, and `justify-start/end/center/between`.
+
+```tsx
+/** @jsxImportSource @octane-xplat/macos-renderer */
+export function AxisGap() {
+	return <flexboxlayout style={{ flexDirection: 'row', gap: 4, columnGap: 12 }}>
+		<label text="Name" /><label text="Value" />
+	</flexboxlayout>
+}
+```
+
+This subset does not implement child `flexGrow`, `flexShrink`, `alignSelf`,
+`order`, wrapping, reverse directions, or `space-around`/`space-evenly`.
+Existing `flex-1`/`shrink-0` class approximations are not full child-flex
+semantics. Attached parent-placement metadata remains a direct prop contract:
+container channel normalization does not move `row`, `col`, spans, or absolute
+placement into styles. Keep those values on the child host.
+
+```tsx
+/** @jsxImportSource @octane-xplat/macos-renderer */
+export function PositionedRow() {
+	return <absolutelayout>
+		<flexboxlayout left={20} top={12} style={{ width: 240, height: 40, flexDirection: 'row', gap: 12 }}>
+			<label text="Name" /><label text="Value" />
+		</flexboxlayout>
+	</absolutelayout>
+}
+```
+
 ## Development bundles
 
 Call `xplatMacOS(mode, { packaged: false, hmr: true, entry: 'src/App.macos.tsx' })`
 for the component bundle. It retains renderer and Octane imports so the
 CLI-managed shell can share their live instances across edits. Build the
 shell with `packaged: true`, and populate `__xplatDevModules` with the renderer
-and Octane modules. The [independent development shell](test/fixtures/dev-shell.mjs)
+and Octane modules. The [independent development shell](test/fixtures/dev-shell.ts)
 shows the module mapping and retained-root HMR lifecycle.
 
 ```js
@@ -221,10 +359,16 @@ From this repository:
 
 ```sh
 pnpm --filter @octane-xplat/macos-renderer test
+pnpm --filter @octane-xplat/macos-renderer test:overflow
 pnpm --filter @octane-xplat/macos-renderer test:packed
 pnpm --filter @xplat/macos test:fonts
+pnpm --filter @xplat/macos test:layout-channels
 ```
 
+The overflow check runs an AppKit fixture with long and short strings, assigned
+frame resizing, multiline limits, attributed line height, and prop removals. It
+asserts native values and measurements; it does not inspect rendered pixels.
+
 The packed check uses the renderer and CLI tarballs in a temporary app outside
 the checkout. It checks declarations and production compilation on every
 host; on Apple Silicon macOS it also packages and launches the app and verifies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/macos-renderer",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Experimental AppKit renderer for Octane on macOS",
   "license": "MIT",
   "repository": {
@@ -39,8 +39,9 @@
     "octane": ">=0.6.3 <1"
   },
   "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "test:packed": "node test/packed-consumer.mjs",
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "test:overflow": "node ../../scripts/probe.mjs run test/fixtures/text-overflow.macos.tsrx --target macos",
+    "test:packed": "node --experimental-strip-types test/packed-consumer.ts",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   }
 }

package/src/appearance.ts

@@ -0,0 +1,56 @@
+/** App-wide effective appearance. AppKit resolves both system mode and an
+ * explicit NSApplication.appearance override; colors remain app-owned. */
+export function installAppearanceBridge(bridge: Record<string, any>): void {
+	// Preserve an installed producer across module reloads and host customization.
+	if (bridge.getColorScheme && bridge.onAppearanceChange) {
+		return
+	}
+
+	const listeners = new Set<() => void>()
+	let observer: any
+	let application: any
+	let Observer: any
+
+	bridge.getColorScheme = () => {
+		const appearance = NSApplication.sharedApplication.effectiveAppearance
+		return appearance?.bestMatchFromAppearancesWithNames?.([
+			'NSAppearanceNameAqua',
+			'NSAppearanceNameDarkAqua',
+		]) === 'NSAppearanceNameDarkAqua'
+			? 'dark'
+			: 'light'
+	}
+
+	bridge.onAppearanceChange = (listener: () => void) => {
+		if (!observer) {
+			// extend binds the inherited NSObject KVO selector in node-api.
+			Observer ??= NSObject.extend({
+				observeValueForKeyPathOfObjectChangeContext(keyPath: string) {
+					if (keyPath === 'effectiveAppearance') {
+						listeners.forEach((callback) => callback())
+					}
+				},
+			})
+
+			application = NSApplication.sharedApplication
+			observer = Observer.new()
+			application.addObserverForKeyPathOptionsContext(observer, 'effectiveAppearance', 0, null)
+		}
+
+		listeners.add(listener)
+		let active = true
+		return () => {
+			if (!active) {
+				return
+			}
+
+			active = false
+			listeners.delete(listener)
+			if (listeners.size === 0 && observer) {
+				application.removeObserverForKeyPath(observer, 'effectiveAppearance')
+				observer = undefined
+				application = undefined
+			}
+		}
+	}
+}