test(fresco): bootstrap the JS component test baseline (#3232)

Author: ubugeeei

npm/fresco/CONTRIBUTING-tests.md

@@ -0,0 +1,54 @@
+# Fresco JS test baseline
+
+`pnpm test` runs `node:test` suites (via `vp exec tsx --test 'src/**/*.test.ts'`).
+`pnpm check` includes `tsgo --noEmit`, which gates the compile-only type tests.
+
+## The three-part standard
+
+Every suite in `npm/fresco/src` follows three rules (see #3228):
+
+1. **Render-snapshot tests assert the mounted output tree.** Mount through the
+   real renderer and compare `FrescoNode` trees (or `treeToRenderNodes` /
+   `renderToString` output) against inline expected structures with
+   `assert.deepEqual`. Never assert on source text, and avoid giant snapshots:
+   keep expected trees small enough to read inline.
+2. **Type-level tests cover public props/emits.** Compile-only `*.test-d.ts`
+   files (see `src/components/types.test-d.ts`) pair positive cases with
+   `@ts-expect-error` negatives; `tsgo` fails when either direction regresses.
+3. **Behavior tests cover keyboard/focus ownership.** Drive keys through
+   `dispatchKey`/`typeChars` (the same `lastKeyEvent` ref the interactive event
+   loop writes) and assert focus against the `FocusManager` contract.
+
+## The native seam
+
+There is no mock of `@vizejs/fresco-native`. The JS layer is pure up to the
+byte boundary that crosses into Rust: `renderer.ts` imports only types from the
+native package, and `app.ts` loads it lazily and only in interactive mode.
+Tests therefore run the shipped code end-to-end:
+
+- `mountFresco` (in `src/testing/mount.ts`) mounts components with the same
+  provide set `createApp` installs (app context, focus manager, screen reader
+  flag, streams, cursor) and exposes the live mounted tree.
+- `treeToRenderNodes(root)` returns the exact flat payload the native
+  `renderTree` call would paint; assert on it for style/appearance mapping.
+- `renderToString(root)` covers the plain-text output path.
+
+If a future test needs a runtime native API, add a typed seam instead of
+importing the binding: keep the fake at the narrowest boundary possible.
+
+## Adding a component test
+
+1. Create `src/components/YourComponent.test.ts` (colocated, `node:test`).
+2. Mount with `mountComponent(YourComponent, props, slot?, options?)`.
+3. Assert the tree with `toTreeSnapshot(firstChild(mounted))` against an
+   inline expected object, or read targeted props off `firstChild(mounted)`.
+   Note: Boolean-declared props default to `false` and appear on emitted host
+   nodes; assert them explicitly.
+4. For interaction, pass `focused: true` (or use `useFocus` ids) and drive
+   `await dispatchKey({ key: "enter" })` / `await typeChars("abc")`; reactive
+   updates need `await nextTick()` before re-reading the tree.
+5. Always `mounted.unmount()` so composable lifecycles (focus unregister,
+   watcher disposal) are exercised.
+6. Extend `src/components/types.test-d.ts` with the component's public
+   props/emits, including at least one `@ts-expect-error` negative per prop
+   group.

npm/fresco/package.json

@@ -47,16 +47,20 @@
   "scripts": {
     "build": "vp pack",
     "dev": "vp pack --watch",
-    "check": "vp check src vite.config.ts",
+    "check": "vp check src vite.config.ts && tsgo --noEmit -p tsconfig.json",
     "check:fix": "vp check --fix src vite.config.ts",
-    "fmt": "vp fmt --write src vite.config.ts"
+    "check:types": "tsgo --noEmit -p tsconfig.json",
+    "fmt": "vp fmt --write src vite.config.ts",
+    "test": "vp exec tsx --test 'src/**/*.test.ts'"
   },
   "dependencies": {
     "@vizejs/fresco-native": "workspace:*"
   },
   "devDependencies": {
     "@types/node": "catalog:typescript",
+    "@typescript/native-preview": "catalog:typescript",
     "@vue/runtime-core": "catalog:vue-stable",
+    "tsx": "catalog:typescript",
     "typescript": "catalog:typescript",
     "vite-plus": "catalog:vite-stack"
   },

npm/fresco/src/app.ts

@@ -13,7 +13,7 @@ import {
   type Ref,
   type VNode,
 } from "@vue/runtime-core";
-import type { InputEventNapi } from "@vizejs/fresco-native";
+import type { InputEventNapi, ModifiersNapi } from "@vizejs/fresco-native";
 import {
   SCREEN_READER_KEY,
   isScreenReaderEnabledByDefault,
@@ -824,7 +824,7 @@ export function createApp(rootComponent: AppRoot, options: AppOptions = {}): App
     }
 
     if (event.eventType === "key") {
-      const modifiers = event.modifiers ?? {};
+      const modifiers: Partial<ModifiersNapi> = event.modifiers ?? {};
       lastKeyEvent.value = {
         type: "key",
         key: event.key ?? undefined,

npm/fresco/src/components/Box.test.ts

@@ -0,0 +1,133 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { h } from "@vue/runtime-core";
+
+import { firstChild, mountComponent, toTreeSnapshot } from "../testing/mount.js";
+import { Box } from "./Box.js";
+
+// Box declares Boolean props, so Vue defaults them to false and the render
+// function forwards them onto the host node; they are inert downstream
+// (treeToRenderNodes drops falsy appearance) but part of the output tree.
+const boxDefaults = { borderDimColor: false, "aria-hidden": false };
+
+void test("renders a box node and forwards children", () => {
+  const mounted = mountComponent(Box, {}, () => h("text", { text: "inside" }));
+
+  assert.deepEqual(toTreeSnapshot(firstChild(mounted)), {
+    type: "box",
+    props: { style: {}, ...boxDefaults },
+    children: [{ type: "text", props: { text: "inside" } }],
+  });
+  mounted.unmount();
+});
+
+void test("maps layout props onto the style object", () => {
+  const mounted = mountComponent(Box, {
+    flexDirection: "column",
+    justifyContent: "center",
+    alignItems: "flex-end",
+    flexGrow: 1,
+    flexShrink: 0,
+    width: 40,
+    height: "50%",
+    minWidth: 5,
+    gap: 2,
+    overflow: "hidden",
+  });
+
+  assert.deepEqual(firstChild(mounted).props.style, {
+    flexDirection: "column",
+    justifyContent: "center",
+    alignItems: "flex-end",
+    flexGrow: 1,
+    flexShrink: 0,
+    width: "40",
+    height: "50%",
+    minWidth: "5",
+    gap: 2,
+    overflow: "hidden",
+  });
+  mounted.unmount();
+});
+
+void test("expands padding and margin axis shorthands per side", () => {
+  const mounted = mountComponent(Box, {
+    padding: 1,
+    paddingX: 2,
+    paddingTop: 3,
+    marginY: 4,
+    marginLeft: 5,
+  });
+
+  assert.deepEqual(firstChild(mounted).props.style, {
+    padding: 1,
+    paddingTop: 3,
+    paddingRight: 2,
+    // paddingBottom stays unset: per-side keys materialize only when that
+    // side or its axis shorthand is given; the base padding covers the rest.
+    paddingLeft: 2,
+    marginTop: 4,
+    marginBottom: 4,
+    marginLeft: 5,
+  });
+  mounted.unmount();
+});
+
+void test("normalizes border style names and prefers the Ink alias", () => {
+  const withBorder = (props: Record<string, unknown>) => {
+    const mounted = mountComponent(Box, props);
+    const border = firstChild(mounted).props.border;
+    mounted.unmount();
+    return border;
+  };
+
+  assert.equal(withBorder({ border: "single" }), "single");
+  assert.equal(withBorder({ border: "round" }), "rounded");
+  assert.equal(withBorder({ border: "bold" }), "heavy");
+  assert.equal(withBorder({ borderStyle: "double", border: "single" }), "double");
+  assert.equal(withBorder({}), undefined);
+});
+
+void test("resolves color aliases with Fresco names winning", () => {
+  const mounted = mountComponent(Box, {
+    fg: "cyan",
+    color: "red",
+    backgroundColor: "blue",
+    borderColor: "green",
+  });
+
+  const props = firstChild(mounted).props;
+  assert.equal(props.fg, "cyan");
+  assert.equal(props.bg, "blue");
+  assert.equal(props.borderColor, "green");
+  mounted.unmount();
+});
+
+void test("hides aria-hidden subtrees only in screen reader mode", () => {
+  const visible = mountComponent(Box, { "aria-hidden": true }, () => h("text", { text: "x" }));
+  assert.equal(firstChild(visible).type, "box");
+  assert.equal(firstChild(visible).props["aria-hidden"], true);
+  visible.unmount();
+
+  const hidden = mountComponent(Box, { "aria-hidden": true }, () => h("text", { text: "x" }), {
+    screenReader: true,
+  });
+  assert.deepEqual(toTreeSnapshot(firstChild(hidden)), { type: "text" });
+  hidden.unmount();
+});
+
+void test("replaces children with the aria-label in screen reader mode", () => {
+  const mounted = mountComponent(
+    Box,
+    { "aria-label": "status panel" },
+    () => h("text", { text: "42%" }),
+    { screenReader: true },
+  );
+
+  assert.deepEqual(toTreeSnapshot(firstChild(mounted)), {
+    type: "box",
+    props: { style: {}, "aria-label": "status panel", ...boxDefaults },
+    children: [{ type: "text", props: { text: "status panel" } }],
+  });
+  mounted.unmount();
+});

npm/fresco/src/components/Box.ts

@@ -228,16 +228,18 @@ export const Box = defineComponent({
     color: String,
     bg: String,
     backgroundColor: String,
-    "aria-label": String,
-    "aria-hidden": Boolean,
-    "aria-role": String as PropType<BoxProps["aria-role"]>,
-    "aria-state": Object as PropType<BoxProps["aria-state"]>,
+    // Declared camelCase so the runtime props object (which Vue camelizes)
+    // matches these keys; templates and h() may still pass "aria-label" etc.
+    ariaLabel: String,
+    ariaHidden: Boolean,
+    ariaRole: String as PropType<BoxProps["aria-role"]>,
+    ariaState: Object as PropType<BoxProps["aria-state"]>,
   },
   setup(props, { slots }) {
     const isScreenReaderEnabled = useIsScreenReaderEnabled();
 
     return () => {
-      if (isScreenReaderEnabled && props["aria-hidden"]) return null;
+      if (isScreenReaderEnabled && props.ariaHidden) return null;
 
       const style: Record<string, unknown> = {};
 
@@ -302,8 +304,8 @@ export const Box = defineComponent({
       if (props.overflowY) style.overflowY = props.overflowY;
 
       const children =
-        isScreenReaderEnabled && props["aria-label"]
-          ? [h("text", { text: props["aria-label"] })]
+        isScreenReaderEnabled && props.ariaLabel
+          ? [h("text", { text: props.ariaLabel })]
           : slots.default?.();
 
       return h(
@@ -320,10 +322,10 @@ export const Box = defineComponent({
           borderBackgroundColor: props.borderBackgroundColor,
           fg: props.fg ?? props.color,
           bg: props.bg ?? props.backgroundColor,
-          "aria-label": props["aria-label"],
-          "aria-hidden": props["aria-hidden"],
-          "aria-role": props["aria-role"],
-          "aria-state": props["aria-state"],
+          "aria-label": props.ariaLabel,
+          "aria-hidden": props.ariaHidden,
+          "aria-role": props.ariaRole,
+          "aria-state": props.ariaState,
         },
         children,
       );