feat: expand floating parameters

Author: rauhryan

ops.ts

@@ -163,12 +163,24 @@ export function pack(
           o += 4;
           view.setFloat32(o, f.y ?? 0, true);
           o += 4;
+          view.setFloat32(o, f.expand?.width ?? 0, true);
+          o += 4;
+          view.setFloat32(o, f.expand?.height ?? 0, true);
+          o += 4;
           view.setUint32(o, f.parent ?? 0, true);
           o += 4;
           view.setUint32(
             o,
-            (f.attachTo ?? 0) | ((f.attachPoints ?? 0) << 8) |
-              ((f.zIndex ?? 0) << 16),
+            (f.attachTo ?? 0) |
+              ((f.attachPoints?.element ?? 0) << 8) |
+              ((f.attachPoints?.parent ?? 0) << 16) |
+              ((f.pointerCaptureMode ?? 0) << 24),
+            true,
+          );
+          o += 4;
+          view.setUint32(
+            o,
+            (f.clipTo ?? 0) | (((f.zIndex ?? 0) & 0xffff) << 8),
             true,
           );
           o += 4;
@@ -264,13 +276,45 @@ export interface OpenElement {
   floating?: {
     x?: number;
     y?: number;
+    expand?: { width?: number; height?: number };
     parent?: number;
     attachTo?: number;
-    attachPoints?: number;
+    attachPoints?: { element?: number; parent?: number };
+    pointerCaptureMode?: number;
+    clipTo?: number;
     zIndex?: number;
   };
 }
 
+export const ATTACH_POINT = {
+  LEFT_TOP: 0,
+  LEFT_CENTER: 1,
+  LEFT_BOTTOM: 2,
+  CENTER_TOP: 3,
+  CENTER_CENTER: 4,
+  CENTER_BOTTOM: 5,
+  RIGHT_TOP: 6,
+  RIGHT_CENTER: 7,
+  RIGHT_BOTTOM: 8,
+} as const;
+
+export const ATTACH_TO = {
+  NONE: 0,
+  PARENT: 1,
+  ELEMENT_WITH_ID: 2,
+  ROOT: 3,
+} as const;
+
+export const POINTER_CAPTURE_MODE = {
+  CAPTURE: 0,
+  PASSTHROUGH: 1,
+} as const;
+
+export const CLIP_TO = {
+  NONE: 0,
+  ATTACHED_PARENT: 1,
+} as const;
+
 export interface Text {
   directive: typeof OP_TEXT;
   content: string;

specs/renderer-spec.md

@@ -609,10 +609,36 @@ The `open()` constructor currently accepts the following property groups in its
 - **`cornerRadius`** — per-corner radius values, producing rounded box-drawing
   characters
 - **`clip`** — clip region configuration for scroll containers
-- **`floating`** — floating-element configuration (offset, parent reference,
-  attach points, z-index)
+- **`floating`** — floating-element configuration (offset, expansion, parent
+  reference, attach target, structured attach points, pointer capture mode, clip
+  target, z-index)
 - **`scroll`** — scroll container configuration
 
+The current floating surface is:
+
+```ts
+floating?: {
+  x?: number;
+  y?: number;
+  expand?: { width?: number; height?: number };
+  parent?: number;
+  attachTo?: number;
+  attachPoints?: {
+    element?: number;
+    parent?: number;
+  };
+  pointerCaptureMode?: number;
+  clipTo?: number;
+  zIndex?: number;
+}
+```
+
+This shape extends the earlier floating surface in two ways. First,
+`attachPoints` is structured as separate element and parent anchor values
+instead of a single packed enum. Second, the surface exposes additional Clay
+floating controls that were previously unavailable at the TypeScript layer:
+`expand`, `pointerCaptureMode`, and `clipTo`.
+
 The `text()` constructor currently accepts: `color`, `fontSize`,
 `letterSpacing`, `lineHeight`, and attribute flags (`bold`, `italic`,
 `underline`, `strikethrough`).

src/clayterm.c

@@ -546,13 +546,19 @@ void reduce(struct Clayterm *ct, uint32_t *buf, int len, int mode, int row) {
       if (mask & PROP_FLOATING) {
         decl.floating.offset.x = rdf(buf, len, &i);
         decl.floating.offset.y = rdf(buf, len, &i);
+        decl.floating.expand.width = rdf(buf, len, &i);
+        decl.floating.expand.height = rdf(buf, len, &i);
         decl.floating.parentId = rd(buf, len, &i);
 
         uint32_t fc = rd(buf, len, &i);
         decl.floating.attachTo = fc & 0xff;
         decl.floating.attachPoints.element = (fc >> 8) & 0xff;
         decl.floating.attachPoints.parent = (fc >> 16) & 0xff;
-        decl.floating.zIndex = (int16_t)((fc >> 24) & 0xff);
+        decl.floating.pointerCaptureMode = (fc >> 24) & 0xff;
+
+        uint32_t fd = rd(buf, len, &i);
+        decl.floating.clipTo = fd & 0xff;
+        decl.floating.zIndex = (int16_t)(fd >> 8);
       }
 
       Clay__ConfigureOpenElement(decl);

test/term.test.ts

@@ -1,6 +1,15 @@
 import { beforeEach, describe, expect, it } from "./suite.ts";
 import { createTerm, type Term } from "../term.ts";
-import { close, fixed, grow, open, rgba, text } from "../ops.ts";
+import {
+  ATTACH_POINT,
+  ATTACH_TO,
+  close,
+  fixed,
+  grow,
+  open,
+  rgba,
+  text,
+} from "../ops.ts";
 import { print } from "./print.ts";
 
 const decode = (bytes: Uint8Array) => new TextDecoder().decode(bytes);
@@ -191,6 +200,50 @@ describe("term", () => {
     });
   });
 
+  it("renders a floating frame with structured attach points", () => {
+    let out = print(
+      decode(
+        term.render([
+          open("root", {
+            layout: { width: fixed(40), height: fixed(10), direction: "ttb" },
+          }),
+          open("frame", {
+            layout: {
+              width: fixed(12),
+              height: fixed(5),
+              direction: "ttb",
+              padding: { left: 1, top: 1 },
+            },
+            border: {
+              color: rgba(255, 255, 255),
+              left: 1,
+              right: 1,
+              top: 1,
+              bottom: 1,
+            },
+            floating: {
+              x: 3,
+              y: 1,
+              attachTo: ATTACH_TO.ROOT,
+              attachPoints: {
+                element: ATTACH_POINT.CENTER_CENTER,
+                parent: ATTACH_POINT.CENTER_CENTER,
+              },
+            },
+          }),
+          text("box"),
+          close(),
+          close(),
+        ]).output,
+      ),
+      40,
+      10,
+    );
+
+    expect(out).toContain("│box       │");
+    expect(out).toContain("┌──────────┐");
+  });
+
   describe("row offset", () => {
     it("renders two frames at the offset position", async () => {
       let term = await createTerm({ width: 20, height: 5 });

test/validate.test.ts

@@ -78,6 +78,39 @@ describe("validate", () => {
   it("rejects fractional color", () => {
     expect(validate([text("hi", { color: 1.5 })])).toBe(false);
   });
+
+  it("accepts structured floating attach points", () => {
+    expect(validate([
+      open("x", {
+        floating: {
+          attachPoints: { element: 4, parent: 4 },
+        },
+      }),
+      close(),
+    ])).toBe(true);
+  });
+
+  it("accepts floating expand and clipping fields", () => {
+    expect(validate([
+      open("x", {
+        floating: {
+          expand: { width: 2, height: 3 },
+          pointerCaptureMode: 1,
+          clipTo: 1,
+          zIndex: 1024,
+        },
+      }),
+      close(),
+    ])).toBe(true);
+  });
+
+  it("rejects numeric floating attachPoints legacy shape", () => {
+    expect(validate([
+      // deno-lint-ignore no-explicit-any
+      open("x", { floating: { attachPoints: 4 as any } }),
+      close(),
+    ])).toBe(false);
+  });
 });
 
 describe("validated", () => {

validate.ts

@@ -83,9 +83,18 @@ const Clip = Type.Object({
 const Floating = Type.Object({
   x: Type.Optional(Type.Number()),
   y: Type.Optional(Type.Number()),
+  expand: Type.Optional(Type.Object({
+    width: Type.Optional(Type.Number()),
+    height: Type.Optional(Type.Number()),
+  })),
   parent: Type.Optional(Type.Integer({ minimum: 0 })),
   attachTo: Type.Optional(u8),
-  attachPoints: Type.Optional(u8),
+  attachPoints: Type.Optional(Type.Object({
+    element: Type.Optional(u8),
+    parent: Type.Optional(u8),
+  })),
+  pointerCaptureMode: Type.Optional(u8),
+  clipTo: Type.Optional(u8),
   zIndex: Type.Optional(u16),
 });