♻️ use string literals for floating options

Author: rauhryan

ops.ts

@@ -171,16 +171,16 @@ export function pack(
           o += 4;
           view.setUint32(
             o,
-            (f.attachTo ?? 0) |
-              ((f.attachPoints?.element ?? 0) << 8) |
-              ((f.attachPoints?.parent ?? 0) << 16) |
-              ((f.pointerCaptureMode ?? 0) << 24),
+            encodeAttachTo(f.attachTo) |
+              (encodeAttachPoint(f.attachPoints?.element) << 8) |
+              (encodeAttachPoint(f.attachPoints?.parent) << 16) |
+              (encodePointerCaptureMode(f.pointerCaptureMode) << 24),
             true,
           );
           o += 4;
           view.setUint32(
             o,
-            (f.clipTo ?? 0) | (((f.zIndex ?? 0) & 0xffff) << 8),
+            encodeClipTo(f.clipTo) | (((f.zIndex ?? 0) & 0xffff) << 8),
             true,
           );
           o += 4;
@@ -278,42 +278,77 @@ export interface OpenElement {
     y?: number;
     expand?: { width?: number; height?: number };
     parent?: number;
-    attachTo?: number;
-    attachPoints?: { element?: number; parent?: number };
-    pointerCaptureMode?: number;
-    clipTo?: number;
+    attachTo?: AttachTo;
+    attachPoints?: { element?: AttachPoint; parent?: AttachPoint };
+    pointerCaptureMode?: PointerCaptureMode;
+    clipTo?: ClipTo;
     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 type AttachPoint =
+  | "left-top"
+  | "left-center"
+  | "left-bottom"
+  | "center-top"
+  | "center-center"
+  | "center-bottom"
+  | "right-top"
+  | "right-center"
+  | "right-bottom";
+
+export type AttachTo = "none" | "parent" | "element" | "root";
+
+export type PointerCaptureMode = "capture" | "passthrough";
+
+export type ClipTo = "none" | "attached-parent";
+
+const ATTACH_POINT: Record<AttachPoint, number> = {
+  "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,
+};
+
+const ATTACH_TO: Record<AttachTo, number> = {
+  none: 0,
+  parent: 1,
+  element: 2,
+  root: 3,
+};
+
+const POINTER_CAPTURE_MODE: Record<PointerCaptureMode, number> = {
+  capture: 0,
+  passthrough: 1,
+};
+
+const CLIP_TO: Record<ClipTo, number> = {
+  none: 0,
+  "attached-parent": 1,
+};
+
+function encodeAttachPoint(value: AttachPoint | undefined): number {
+  return value === undefined ? 0 : ATTACH_POINT[value];
+}
+
+function encodeAttachTo(value: AttachTo | undefined): number {
+  return value === undefined ? 0 : ATTACH_TO[value];
+}
+
+function encodePointerCaptureMode(
+  value: PointerCaptureMode | undefined,
+): number {
+  return value === undefined ? 0 : POINTER_CAPTURE_MODE[value];
+}
+
+function encodeClipTo(value: ClipTo | undefined): number {
+  return value === undefined ? 0 : CLIP_TO[value];
+}
 
 export interface Text {
   directive: typeof OP_TEXT;

specs/renderer-spec.md

@@ -622,22 +622,44 @@ floating?: {
   y?: number;
   expand?: { width?: number; height?: number };
   parent?: number;
-  attachTo?: number;
+  attachTo?: "none" | "parent" | "element" | "root";
   attachPoints?: {
-    element?: number;
-    parent?: number;
+    element?:
+      | "left-top"
+      | "left-center"
+      | "left-bottom"
+      | "center-top"
+      | "center-center"
+      | "center-bottom"
+      | "right-top"
+      | "right-center"
+      | "right-bottom";
+    parent?:
+      | "left-top"
+      | "left-center"
+      | "left-bottom"
+      | "center-top"
+      | "center-center"
+      | "center-bottom"
+      | "right-top"
+      | "right-center"
+      | "right-bottom";
   };
-  pointerCaptureMode?: number;
-  clipTo?: number;
+  pointerCaptureMode?: "capture" | "passthrough";
+  clipTo?: "none" | "attached-parent";
   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 `floating` object configures Clay floating layout behavior. `x` and `y`
+provide the floating offset. `expand` expands the floating bounds. `parent`
+identifies the target element when `attachTo` is `"element"`. `attachTo` selects
+whether the element is attached to no target, its parent, an element, or the
+layout root. `attachPoints.element` describes the anchor on the floating
+element, and `attachPoints.parent` describes the anchor on the attached target.
+`pointerCaptureMode` controls whether the floating element captures pointer
+input or lets it pass through, `clipTo` controls inherited clipping, and
+`zIndex` controls floating order.
 
 The `text()` constructor currently accepts: `color`, `fontSize`,
 `letterSpacing`, `lineHeight`, and attribute flags (`bold`, `italic`,

test/term.test.ts

@@ -1,15 +1,6 @@
 import { beforeEach, describe, expect, it } from "./suite.ts";
 import { createTerm, type Term } from "../term.ts";
-import {
-  ATTACH_POINT,
-  ATTACH_TO,
-  close,
-  fixed,
-  grow,
-  open,
-  rgba,
-  text,
-} from "../ops.ts";
+import { close, fixed, grow, open, rgba, text } from "../ops.ts";
 import { print } from "./print.ts";
 
 const decode = (bytes: Uint8Array) => new TextDecoder().decode(bytes);
@@ -224,10 +215,10 @@ describe("term", () => {
             floating: {
               x: 3,
               y: 1,
-              attachTo: ATTACH_TO.ROOT,
+              attachTo: "root",
               attachPoints: {
-                element: ATTACH_POINT.CENTER_CENTER,
-                parent: ATTACH_POINT.CENTER_CENTER,
+                element: "center-center",
+                parent: "center-center",
               },
             },
           }),

test/validate.test.ts

@@ -83,7 +83,7 @@ describe("validate", () => {
     expect(validate([
       open("x", {
         floating: {
-          attachPoints: { element: 4, parent: 4 },
+          attachPoints: { element: "center-center", parent: "center-center" },
         },
       }),
       close(),
@@ -95,16 +95,21 @@ describe("validate", () => {
       open("x", {
         floating: {
           expand: { width: 2, height: 3 },
-          pointerCaptureMode: 1,
-          clipTo: 1,
+          pointerCaptureMode: "passthrough",
+          clipTo: "attached-parent",
           zIndex: 1024,
         },
       }),
       close(),
     ])).toBe(true);
   });
 
-  it("rejects numeric floating attachPoints legacy shape", () => {
+  it("rejects numeric floating enum values", () => {
+    expect(validate([
+      // deno-lint-ignore no-explicit-any
+      open("x", { floating: { attachTo: 3 as any } }),
+      close(),
+    ])).toBe(false);
     expect(validate([
       // deno-lint-ignore no-explicit-any
       open("x", { floating: { attachPoints: 4 as any } }),

validate.ts

@@ -80,6 +80,35 @@ const Clip = Type.Object({
   vertical: Type.Optional(Type.Boolean()),
 });
 
+const AttachPoint = Type.Union([
+  Type.Literal("left-top"),
+  Type.Literal("left-center"),
+  Type.Literal("left-bottom"),
+  Type.Literal("center-top"),
+  Type.Literal("center-center"),
+  Type.Literal("center-bottom"),
+  Type.Literal("right-top"),
+  Type.Literal("right-center"),
+  Type.Literal("right-bottom"),
+]);
+
+const AttachTo = Type.Union([
+  Type.Literal("none"),
+  Type.Literal("parent"),
+  Type.Literal("element"),
+  Type.Literal("root"),
+]);
+
+const PointerCaptureMode = Type.Union([
+  Type.Literal("capture"),
+  Type.Literal("passthrough"),
+]);
+
+const ClipTo = Type.Union([
+  Type.Literal("none"),
+  Type.Literal("attached-parent"),
+]);
+
 const Floating = Type.Object({
   x: Type.Optional(Type.Number()),
   y: Type.Optional(Type.Number()),
@@ -88,13 +117,13 @@ const Floating = Type.Object({
     height: Type.Optional(Type.Number()),
   })),
   parent: Type.Optional(Type.Integer({ minimum: 0 })),
-  attachTo: Type.Optional(u8),
+  attachTo: Type.Optional(AttachTo),
   attachPoints: Type.Optional(Type.Object({
-    element: Type.Optional(u8),
-    parent: Type.Optional(u8),
+    element: Type.Optional(AttachPoint),
+    parent: Type.Optional(AttachPoint),
   })),
-  pointerCaptureMode: Type.Optional(u8),
-  clipTo: Type.Optional(u8),
+  pointerCaptureMode: Type.Optional(PointerCaptureMode),
+  clipTo: Type.Optional(ClipTo),
   zIndex: Type.Optional(u16),
 });