@opsydyn/effect-three-foldkit 0.2.0 → 0.4.0

package/src/boxSelect.ts

@@ -0,0 +1,158 @@
+/**
+ * Box selection as a Foldkit submodel (roadmap, "Beyond parity" 5), after Drei's `Select`
+ * over three.js's `SelectionBox`: a shift-drag that begins on nothing draws a box, and
+ * its release selects what the box holds, through the core's pure `boxSelect`. The parent
+ * owns what is selected; the submodel owns only the box:
+ *
+ * - `Dragged` (each scene `Drag` gesture the box `claims`, made with `dragOf`) starts the box
+ *   where the press was and moves its far corner by the gesture's deltas;
+ * - `Ended` (the scene's `GestureEnd`, with the camera and what can be selected) reports
+ *   `Selected { keys }`, which replaces the selection as Drei's box does, and clears the
+ *   box;
+ * - `Cancelled` clears the box and selects nothing.
+ *
+ * `rectangle(model)` places the box on the canvas in CSS pixels, for an HTML outline, and
+ * `inside(model, camera, selectable)` says what the box holds so far, for highlighting
+ * while it is drawn (Drei selects as the box moves).
+ *
+ * @module
+ */
+import { boxSelect, type Camera, type Gesture, SceneSchema } from '@opsydyn/effect-three';
+import { Option, Schema } from 'effect';
+import { defineMessageUnion } from 'foldkit/message';
+import type { ReturnWithOutMessage } from 'foldkit/update';
+
+const Corner = Schema.Struct({ x: Schema.Finite, y: Schema.Finite });
+
+/** Something the box can select: its key, and the point that must fall inside. */
+const Selectable = Schema.Struct({ key: Schema.String, at: SceneSchema.Vec3 });
+
+/** A box being drawn: its corners in the canvas's normalised coordinates, −1 to 1, y up. */
+export const Box = Schema.Struct({
+  from: Corner,
+  to: Corner,
+  width: Schema.Finite,
+  height: Schema.Finite,
+});
+export type Box = typeof Box.Type;
+
+export const Model = Schema.Struct({ box: Schema.Option(Box) });
+export type Model = typeof Model.Type;
+
+export const Message = defineMessageUnion({
+  Dragged: {
+    x: Schema.Finite,
+    y: Schema.Finite,
+    deltaX: Schema.Finite,
+    deltaY: Schema.Finite,
+    width: Schema.Finite,
+    height: Schema.Finite,
+  },
+  Ended: { camera: SceneSchema.Camera, selectable: Schema.Array(Selectable) },
+  Cancelled: {},
+});
+export type Message = typeof Message.Type;
+
+export const OutMessage = defineMessageUnion({
+  /** The box was let go: the keys inside it, for the new selection. */
+  Selected: { keys: Schema.Array(Schema.String) },
+});
+export type OutMessage = typeof OutMessage.Type;
+
+/** No box drawn. */
+export const init = (): Model => ({ box: Option.none() });
+
+type Return = ReturnWithOutMessage<Model, Message, OutMessage>;
+
+/** The box with its far corner moved by a drag's CSS-pixel deltas (down positive). */
+const moved = (box: Box, deltaX: number, deltaY: number): Box => ({
+  ...box,
+  to: { x: box.to.x + (deltaX * 2) / box.width, y: box.to.y - (deltaY * 2) / box.height },
+});
+
+const dragged = (model: Model, message: Extract<Message, { _tag: 'Dragged' }>): Model => {
+  const { x, y, deltaX, deltaY, width, height } = message;
+  const start: Box = { from: { x, y }, to: { x, y }, width, height };
+  const box = Option.getOrElse(model.box, () => start);
+  return { box: Option.some(moved(box, deltaX, deltaY)) };
+};
+
+type Selectables = ReadonlyArray<typeof Selectable.Type>;
+
+const keysIn = (box: Box, camera: Camera, selectable: Selectables): ReadonlyArray<string> =>
+  boxSelect(camera, box, box.from, box.to, selectable);
+
+const ended = (model: Model, camera: Camera, selectable: Selectables): Return =>
+  Option.match(model.box, {
+    onNone: () => ({ model }),
+    onSome: (box) => ({
+      model: init(),
+      outMessage: OutMessage.Selected({ keys: keysIn(box, camera, selectable) }),
+    }),
+  });
+
+export const update = (model: Model, message: Message): Return =>
+  Message.match<Return>(message, {
+    Dragged: (drag) => ({ model: dragged(model, drag) }),
+    Ended: ({ camera, selectable }) => ended(model, camera, selectable),
+    Cancelled: () => ({ model: init() }),
+  });
+
+/** Whether a box is being drawn: the parent leaves the camera alone while it is. */
+export const drawing = (model: Model): boolean => Option.isSome(model.box);
+
+/** A scene `Drag` gesture: the only kind a box takes. */
+export type DragGesture = Extract<Gesture, { readonly _tag: 'Drag' }>;
+
+/** The primary button: a box starts only with it. */
+const primaryButton = 0;
+
+/** A primary-button shift-drag that began on nothing starts a box. */
+const startsBox = (drag: DragGesture): boolean =>
+  drag.button === primaryButton && drag.modifiers.shift && drag.key === undefined;
+
+/** Whether the box takes `drag`: every drag while one is drawn, and one that starts it. */
+export const claims = (model: Model, drag: DragGesture): boolean =>
+  drawing(model) || startsBox(drag);
+
+/** The `Dragged` Message for a drag the box claims. */
+export const dragOf = (gesture: DragGesture): Message =>
+  Message.Dragged({
+    x: gesture.x,
+    y: gesture.y,
+    deltaX: gesture.deltaX,
+    deltaY: gesture.deltaY,
+    width: gesture.width,
+    height: gesture.height,
+  });
+
+/** What the box holds so far, seen through `camera`: none while no box is drawn. */
+export const inside = (
+  model: Model,
+  camera: Camera,
+  selectable: Selectables,
+): ReadonlyArray<string> =>
+  Option.match(model.box, {
+    onNone: () => [],
+    onSome: (box) => keysIn(box, camera, selectable),
+  });
+
+/** A box on the canvas, in CSS pixels from its top left. */
+export type Rectangle = {
+  readonly left: number;
+  readonly top: number;
+  readonly width: number;
+  readonly height: number;
+};
+
+const onCanvas = (box: Box): Rectangle => {
+  const left = ((Math.min(box.from.x, box.to.x) + 1) / 2) * box.width;
+  const right = ((Math.max(box.from.x, box.to.x) + 1) / 2) * box.width;
+  const top = ((1 - Math.max(box.from.y, box.to.y)) / 2) * box.height;
+  const bottom = ((1 - Math.min(box.from.y, box.to.y)) / 2) * box.height;
+  return { left, top, width: right - left, height: bottom - top };
+};
+
+/** Where the box sits on the canvas, while one is drawn. */
+export const rectangle = (model: Model): Option.Option<Rectangle> =>
+  Option.map(model.box, onCanvas);

package/src/dom/webgl.ts

@@ -184,6 +184,21 @@ export const webglRendererFactory = (
         // Effects apply to the single full view only; views draw straight to the screen.
         renderer.render(scene, camera);
       },
+      renderOver: (scene, camera) => {
+        if (renderer.xr.isPresenting) return;
+        if (scissored) {
+          const { width, height } = renderer.getSize(drawingSize);
+          renderer.setScissorTest(false);
+          renderer.setViewport(0, 0, width, height);
+          scissored = false;
+        }
+        // As Drei's Hud: keep what is drawn, clear depth so the HUD is never hidden by it.
+        const autoClear = renderer.autoClear;
+        renderer.autoClear = false;
+        renderer.clearDepth();
+        renderer.render(scene, camera);
+        renderer.autoClear = autoClear;
+      },
       createTarget: (width, height) => createTarget(targets, width, height),
       createEnvironment: () => createRoom(renderer),
       configure: (settings) => {

package/src/dom/webgpu.ts

@@ -177,6 +177,21 @@ export const webgpuRendererFactory = (
         scissored = true;
         renderer.render(scene, camera);
       },
+      renderOver: (scene, camera) => {
+        if (renderer.xr.isPresenting) return;
+        if (scissored) {
+          const { width, height } = renderer.getSize(drawingSize);
+          renderer.setScissorTest(false);
+          renderer.setViewport(0, 0, width, height);
+          scissored = false;
+        }
+        // As Drei's Hud: keep what is drawn, clear depth so the HUD is never hidden by it.
+        const autoClear = renderer.autoClear;
+        renderer.autoClear = false;
+        renderer.clearDepth();
+        renderer.render(scene, camera);
+        renderer.autoClear = autoClear;
+      },
       createTarget: (width, height) => createTarget(targets, width, height),
       createEnvironment: () => createRoom(renderer),
       configure: (settings) => {

package/src/element.ts

@@ -59,6 +59,7 @@ export const sceneElement = CustomElement.define({
     'scene-drag': SceneSchema.DragDetail,
     'scene-drag-end': SceneSchema.DragDetail,
     'scene-gesture': SceneSchema.GestureDetail,
+    'scene-gesture-end': SceneSchema.GestureEndDetail,
     'scene-auto-rotated': SceneSchema.AutoRotatedDetail,
     'scene-collision': SceneSchema.CollisionDetail,
     'scene-contact-force': SceneSchema.ContactForceDetail,
@@ -92,6 +93,7 @@ export const domEventName = {
   Drag: 'scene-drag',
   DragEnd: 'scene-drag-end',
   Gesture: 'scene-gesture',
+  GestureEnd: 'scene-gesture-end',
   AutoRotated: 'scene-auto-rotated',
   Collision: 'scene-collision',
   ContactForce: 'scene-contact-force',

package/src/index.ts

@@ -44,7 +44,13 @@ export {
   type EnvironmentOptions,
   makeEnvironment,
 } from './environment.ts';
+export { inspectorView, type OnEdit } from './inspector.ts';
 export { makeSceneMount, type SceneMount } from './mount.ts';
+export * as BoxSelect from './boxSelect.ts';
+export * as MeasuringTape from './measuringTape.ts';
+export * as PivotControls from './pivotControls.ts';
+export * as TransformGizmo from './transformGizmo.ts';
+export * as ViewportGizmo from './viewportGizmo.ts';
 export { type OverlayView } from './overlayView.ts';
 export {
   type AutoRotatedDetail,
@@ -53,6 +59,7 @@ export {
   type ContactForceDetail,
   type DragDetail,
   type Gesture,
+  type GestureEndDetail,
   type HitDetail,
   type KeyDetail,
   type LabelMeasuredDetail,

package/src/inspector.ts

@@ -0,0 +1,112 @@
+/**
+ * An inspector panel for Foldkit views (roadmap, "Beyond parity" 4): the fields the
+ * core's `Inspector.fields` reads from a schema, drawn as a form. Each control reports
+ * an edit as the app's own Message, with the field's path and the new value; the app
+ * applies it with `Inspector.edit`, which the schema checks, and keeps the result (or
+ * shows why it was refused).
+ *
+ * Numbers, text and choices report when they change (on Enter or leaving the field),
+ * colours as they are picked, switches when clicked, and each of a vector's three
+ * numbers on its own. Kinds, absent parts and lists are shown, not edited.
+ *
+ * @module
+ */
+import type { FieldPath, FieldValue, InspectedField } from '@opsydyn/effect-three';
+import type { Html, HtmlBuilder } from 'foldkit/html';
+
+/** Turns an edit (where, and the new value) into the app's Message. */
+export type OnEdit<Message> = (path: FieldPath, value: FieldValue) => Message;
+
+const axisNames = ['x', 'y', 'z'] as const;
+
+/** The field's name for people: its property names, without list indices. */
+const nameOf = (field: InspectedField): string =>
+  field.path.filter((part) => typeof part === 'string').join(' ') || field.label;
+
+const hex = (colour: number): string => `#${colour.toString(16).padStart(6, '0')}`;
+
+const numberInput = <Message>(
+  h: HtmlBuilder<Message>,
+  label: string,
+  value: number,
+  report: (raw: string) => Message,
+): Html =>
+  h.input([
+    h.Type('number'),
+    h.Step('any'),
+    h.Value(String(value)),
+    h.AriaLabel(label),
+    h.OnChange(report),
+  ]);
+
+const controlOf = <Message>(
+  h: HtmlBuilder<Message>,
+  field: InspectedField,
+  onEdit: OnEdit<Message>,
+): Html => {
+  const name = nameOf(field);
+  switch (field._tag) {
+    case 'Number':
+      return numberInput(h, name, field.value, (raw) => onEdit(field.path, Number(raw)));
+    case 'Text':
+      return h.input([
+        h.Type('text'),
+        h.Value(field.value),
+        h.AriaLabel(name),
+        h.OnChange((raw) => onEdit(field.path, raw)),
+      ]);
+    case 'Toggle':
+      return h.input([
+        h.Type('checkbox'),
+        h.Checked(field.value),
+        h.AriaLabel(name),
+        h.OnClick(onEdit(field.path, !field.value)),
+      ]);
+    case 'Choice':
+      return h.select(
+        [h.AriaLabel(name), h.OnChange((raw) => onEdit(field.path, raw))],
+        field.options.map((option) =>
+          h.option([h.Value(option), h.Selected(option === field.value)], [option]),
+        ),
+      );
+    case 'Colour':
+      return h.input([
+        h.Type('color'),
+        h.Value(hex(field.value)),
+        h.AriaLabel(name),
+        h.OnInput((raw) => onEdit(field.path, Number.parseInt(raw.slice(1), 16))),
+      ]);
+    case 'Vector':
+      return h.span(
+        [h.Class('e3-inspector-vector')],
+        field.value.map((component, index) =>
+          numberInput(h, `${name} ${axisNames[index] ?? index}`, component, (raw) =>
+            onEdit([...field.path, index], Number(raw)),
+          ),
+        ),
+      );
+    case 'Fixed':
+      return h.span([h.Class('e3-inspector-fixed')], [field.text]);
+  }
+};
+
+/**
+ * The fields as a form: a row each, its name and its control, keyed by path. Style it
+ * with the classes `e3-inspector`, `e3-inspector-row`, `e3-inspector-name`,
+ * `e3-inspector-vector` and `e3-inspector-fixed`.
+ */
+export const inspectorView = <Message>(
+  h: HtmlBuilder<Message>,
+  fields: ReadonlyArray<InspectedField>,
+  onEdit: OnEdit<Message>,
+): Html =>
+  h.div(
+    [h.Class('e3-inspector')],
+    fields.map((field) =>
+      h.keyed('label')(
+        field.path.join('.'),
+        [h.Class('e3-inspector-row')],
+        [h.span([h.Class('e3-inspector-name')], [nameOf(field)]), controlOf(h, field, onEdit)],
+      ),
+    ),
+  );

package/src/measuringTape.ts

@@ -0,0 +1,124 @@
+/**
+ * A measuring tape as a Foldkit submodel (roadmap, "Beyond parity" 5): the core's pure
+ * `tape` with Messages for clicks and pointer moves on the scene, an OutMessage when a
+ * length is measured, and its length as HTML at the tape's middle. The parent decides
+ * when the tape is in use and which clicks are on the scene:
+ *
+ * - `Placed` (a click on the scene, with the point it hit) places an end, or starts a
+ *   new tape; placing the second reports `Measured { from, to, length }`;
+ * - `Pointed` (the pointer moving over the scene, or `null` off it) runs the tape to
+ *   the pointer while the second end is placed;
+ * - `Cleared` empties it; `ChoseSnap` rounds new ends to a step, or not.
+ *
+ * `nodes(model)` draws it for the scene and `label(model, h)` is the length for the
+ * view's `overlays`.
+ *
+ * @module
+ */
+import {
+  clearTape,
+  overlay,
+  placeTapeEnd,
+  pointTape,
+  SceneSchema,
+  type SceneNode,
+  tape,
+  tapeLength,
+  type TapeLook,
+  tapeMiddle,
+  tapeNodes,
+} from '@opsydyn/effect-three';
+import { Option, Schema } from 'effect';
+import type { HtmlBuilder } from 'foldkit/html';
+import { defineMessageUnion } from 'foldkit/message';
+import type { ReturnWithOutMessage } from 'foldkit/update';
+
+import type { OverlayView } from './overlayView.ts';
+
+export const Model = Schema.Struct({
+  /** The key its nodes and label are drawn under. */
+  key: Schema.String,
+  tape: SceneSchema.Tape,
+});
+export type Model = typeof Model.Type;
+
+export const Message = defineMessageUnion({
+  Placed: { point: SceneSchema.Vec3 },
+  Pointed: { point: Schema.NullOr(SceneSchema.Vec3) },
+  Cleared: {},
+  ChoseSnap: { snap: SceneSchema.Tape.fields.snap },
+});
+export type Message = typeof Message.Type;
+
+export const OutMessage = defineMessageUnion({
+  /** Both ends are placed: where, and how far apart. */
+  Measured: { from: SceneSchema.Vec3, to: SceneSchema.Vec3, length: Schema.Finite },
+});
+export type OutMessage = typeof OutMessage.Type;
+
+/** An empty tape drawn under `key`, snapping to `snap` when given. */
+export const init = (key: string, options: { readonly snap?: number | null } = {}): Model => ({
+  key,
+  tape: tape(options),
+});
+
+type Return = ReturnWithOutMessage<Model, Message, OutMessage>;
+
+/** The OutMessage for a tape that has just been measured, if it has. */
+const measured = (next: Model): Return =>
+  Option.match(
+    Option.all([Option.fromNullishOr(next.tape.from), Option.fromNullishOr(next.tape.to)]),
+    {
+      onNone: () => ({ model: next }),
+      onSome: ([from, to]) => ({
+        model: next,
+        outMessage: OutMessage.Measured({ from, to, length: tapeLength(next.tape) ?? 0 }),
+      }),
+    },
+  );
+
+export const update = (model: Model, message: Message): Return =>
+  Message.match<Return>(message, {
+    Placed: ({ point }) => measured({ ...model, tape: placeTapeEnd(model.tape, point) }),
+    Pointed: ({ point }) => ({ model: { ...model, tape: pointTape(model.tape, point) } }),
+    Cleared: () => ({ model: { ...model, tape: clearTape(model.tape) } }),
+    ChoseSnap: ({ snap }) => ({ model: { ...model, tape: { ...model.tape, snap } } }),
+  });
+
+/** The tape's length, while it has one (to the pointer while the second end is placed). */
+export const length = (model: Model): Option.Option<number> =>
+  Option.fromNullishOr(tapeLength(model.tape));
+
+/** The tape, for the parent's scene. */
+export const nodes = (model: Model, look: Partial<TapeLook> = {}): SceneNode =>
+  tapeNodes(model.key, model.tape, look);
+
+/** The label's class, when one is given. */
+const classOf = <Message>(h: HtmlBuilder<Message>, className: string | undefined) =>
+  Option.match(Option.fromNullishOr(className), {
+    onNone: () => [],
+    onSome: (name) => [h.Class(name)],
+  });
+
+/**
+ * The length at the tape's middle, for the view's `overlays`: two decimals and `unit`
+ * (`m` unless given), in an element with the class `className` (unstyled unless given).
+ * Pointer events pass through it to the scene.
+ */
+export const label = <Message>(
+  model: Model,
+  h: HtmlBuilder<Message>,
+  options: { readonly unit?: string; readonly className?: string } = {},
+): ReadonlyArray<OverlayView> =>
+  Option.match(Option.all([length(model), Option.fromNullishOr(tapeMiddle(model.tape))]), {
+    onNone: () => [],
+    onSome: ([measuredLength, middle]) => [
+      {
+        overlay: overlay({ key: `${model.key}:label`, position: middle, center: true }),
+        content: h.span(classOf(h, options.className), [
+          `${measuredLength.toFixed(2)} ${options.unit ?? 'm'}`,
+        ]),
+        pointerEvents: 'none',
+      },
+    ],
+  });

package/src/pivotControls.ts

@@ -0,0 +1,118 @@
+/**
+ * Pivot controls as a Foldkit submodel (roadmap, "Beyond parity" 5): the core's pure
+ * `pivotNodes`, `pressPivot` and `dragPivot` (after Drei's `PivotControls`) with
+ * Messages for the scene's pointer events and OutMessages for what the parent does with
+ * them, as `TransformGizmo` is for three's controls. The parent owns where its objects
+ * are; the submodel owns only the handles:
+ *
+ * - `Pressed` (a pointer down on one of its handles, with the point it hit and the
+ *   object's placement) takes hold;
+ * - `Dragged` reports `Moved { placement }` for the parent to apply (`snap` rounds turns
+ *   to ten degrees and scales to tenths, as Drei's shift does);
+ * - `Released` lets go and reports `Finished { placement }`, a step for history;
+ * - `Hovered` highlights a handle.
+ *
+ * `handleOf(model, key)` says whether a hit is on a handle, and `nodes(model, placement)`
+ * draws them.
+ *
+ * @module
+ */
+import {
+  dragPivot,
+  hoverPivot,
+  type Pivot,
+  pivot,
+  type PivotHandle,
+  pivotHandleOf,
+  pivotNodes,
+  type Placement,
+  pressPivot,
+  releasePivot,
+  SceneSchema,
+  type SceneNode,
+  type Vec3,
+} from '@opsydyn/effect-three';
+import { Option, Schema } from 'effect';
+import { defineMessageUnion } from 'foldkit/message';
+import type { ReturnWithOutMessage } from 'foldkit/update';
+
+export const Model = Schema.Struct({
+  /** The key its handles are drawn under: `${key}:arrow-x`, `${key}:slider-z` and so on. */
+  key: Schema.String,
+  pivot: SceneSchema.Pivot,
+  /** The placement the drag last reported, so `Released` can report where it ended. */
+  last: Schema.Option(SceneSchema.Placement),
+});
+export type Model = typeof Model.Type;
+
+const Handle = SceneSchema.PivotHandle;
+
+export const Message = defineMessageUnion({
+  Pressed: { handle: Handle, point: SceneSchema.Vec3, placement: SceneSchema.Placement },
+  Dragged: { origin: SceneSchema.Vec3, direction: SceneSchema.Vec3, snap: Schema.Boolean },
+  Released: {},
+  Hovered: { handle: Schema.NullOr(Handle) },
+});
+export type Message = typeof Message.Type;
+
+export const OutMessage = defineMessageUnion({
+  /** The object's placement now, during a drag. */
+  Moved: { placement: SceneSchema.Placement },
+  /** The drag is over, the object here: a step for history. */
+  Finished: { placement: SceneSchema.Placement },
+});
+export type OutMessage = typeof OutMessage.Type;
+
+/** Pivot controls drawn under `key`, with Drei's defaults or the options given. */
+export const init = (key: string, options: Parameters<typeof pivot>[0] = {}): Model => ({
+  key,
+  pivot: pivot(options),
+  last: Option.none(),
+});
+
+type Return = ReturnWithOutMessage<Model, Message, OutMessage>;
+
+const withPivot = (model: Model, next: Pivot): Model => ({ ...model, pivot: next });
+
+const finished = (model: Model): Return => ({
+  model: { ...withPivot(model, releasePivot(model.pivot)), last: Option.none() },
+  ...Option.match(model.last, {
+    onNone: () => ({}),
+    onSome: (placement) => ({ outMessage: OutMessage.Finished({ placement }) }),
+  }),
+});
+
+const dragged = (model: Model, origin: Vec3, direction: Vec3, snap: boolean): Return => {
+  const placement = Option.fromNullishOr(dragPivot(model.pivot, { origin, direction }, { snap }));
+  return Option.match(placement, {
+    onNone: () => ({ model }),
+    onSome: (placement) => ({
+      model: { ...model, last: Option.some(placement) },
+      outMessage: OutMessage.Moved({ placement }),
+    }),
+  });
+};
+
+export const update = (model: Model, message: Message): Return =>
+  Message.match<Return>(message, {
+    Pressed: ({ handle, point, placement }) => ({
+      model: {
+        ...withPivot(model, pressPivot(model.pivot, placement, handle, point)),
+        last: Option.none(),
+      },
+    }),
+    Dragged: ({ origin, direction, snap }) => dragged(model, origin, direction, snap),
+    Released: () => finished(model),
+    Hovered: ({ handle }) => ({ model: withPivot(model, hoverPivot(model.pivot, handle)) }),
+  });
+
+/** Whether a hit `key` is one of these controls' handles, and which. */
+export const handleOf = (model: Model, key: string): Option.Option<PivotHandle> =>
+  Option.fromNullishOr(pivotHandleOf(model.key, key));
+
+/** Whether a handle is held: the parent leaves the camera alone while it is. */
+export const held = (model: Model): boolean => model.pivot.grab !== null;
+
+/** The handles for `placement`, for the parent's scene. */
+export const nodes = (model: Model, placement: Placement): SceneNode =>
+  pivotNodes(model.key, model.pivot, placement);