@opsydyn/effect-three-foldkit 0.2.0 → 0.4.0

package/src/transformGizmo.ts

@@ -0,0 +1,131 @@
+/**
+ * A transform gizmo as a Foldkit submodel (roadmap, "Beyond parity" 5): the core's pure
+ * gizmo (`gizmoNodes`, `pressGizmo`, `dragGizmo`, after three's `TransformControls`)
+ * with Messages for the scene's pointer events and OutMessages for what the parent does
+ * with them. The parent owns where its objects are; the submodel owns only the gizmo:
+ *
+ * - `Pressed` (a press on one of its handles, with the object's placement and the
+ *   camera) takes hold;
+ * - `Dragged` reports `Moved { placement }` for the parent to apply;
+ * - `Released` lets go and reports `Finished { placement }`, the moment to record a step
+ *   of history;
+ * - `Hovered` highlights a handle; `ChoseMode` and `ChoseSpace` switch them.
+ *
+ * `handleOf(model, key)` says whether a hit is on a handle, and `nodes(model, placement,
+ * camera)` draws them, for the parent's scene and view.
+ *
+ * @module
+ */
+import {
+  type Camera,
+  dragGizmo,
+  type Gizmo,
+  gizmo,
+  type GizmoHandle,
+  gizmoHandleOf,
+  gizmoNodes,
+  hoverGizmo,
+  type Placement,
+  pressGizmo,
+  releaseGizmo,
+  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}:x`, `${key}:xy` and so on. */
+  key: Schema.String,
+  gizmo: SceneSchema.Gizmo,
+  /** 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 = Schema.Literals(['x', 'y', 'z', 'xy', 'yz', 'xz', 'xyz']);
+
+export const Message = defineMessageUnion({
+  Pressed: {
+    handle: Handle,
+    origin: SceneSchema.Vec3,
+    direction: SceneSchema.Vec3,
+    placement: SceneSchema.Placement,
+    camera: SceneSchema.Camera,
+  },
+  Dragged: { origin: SceneSchema.Vec3, direction: SceneSchema.Vec3 },
+  Released: {},
+  Hovered: { handle: Schema.NullOr(Handle) },
+  ChoseMode: { mode: Schema.Literals(['translate', 'rotate', 'scale']) },
+  ChoseSpace: { space: Schema.Literals(['world', 'local']) },
+});
+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;
+
+/** A gizmo drawn under `key`, with the core's defaults or the options given. */
+export const init = (key: string, options: Parameters<typeof gizmo>[0] = {}): Model => ({
+  key,
+  gizmo: gizmo(options),
+  last: Option.none(),
+});
+
+type Return = ReturnWithOutMessage<Model, Message, OutMessage>;
+
+const withGizmo = (model: Model, next: Gizmo): Model => ({ ...model, gizmo: next });
+
+const finished = (model: Model): Return => ({
+  model: { ...withGizmo(model, releaseGizmo(model.gizmo)), last: Option.none() },
+  ...Option.match(model.last, {
+    onNone: () => ({}),
+    onSome: (placement) => ({ outMessage: OutMessage.Finished({ placement }) }),
+  }),
+});
+
+const dragged = (model: Model, origin: Vec3, direction: Vec3): Return => {
+  const placement = Option.fromNullishOr(dragGizmo(model.gizmo, { origin, direction }));
+  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, origin, direction, placement, camera }) => ({
+      model: {
+        ...withGizmo(
+          model,
+          pressGizmo(model.gizmo, placement, handle, { origin, direction }, camera),
+        ),
+        last: Option.none(),
+      },
+    }),
+    Dragged: ({ origin, direction }) => dragged(model, origin, direction),
+    Released: () => finished(model),
+    Hovered: ({ handle }) => ({ model: withGizmo(model, hoverGizmo(model.gizmo, handle)) }),
+    ChoseMode: ({ mode }) => ({ model: withGizmo(model, { ...model.gizmo, mode }) }),
+    ChoseSpace: ({ space }) => ({ model: withGizmo(model, { ...model.gizmo, space }) }),
+  });
+
+/** Whether a hit `key` is one of this gizmo's handles, and which. */
+export const handleOf = (model: Model, key: string): Option.Option<GizmoHandle> =>
+  Option.fromNullishOr(gizmoHandleOf(model.key, key));
+
+/** Whether the gizmo is held: the parent leaves the camera alone while it is. */
+export const held = (model: Model): boolean => model.gizmo.grab !== null;
+
+/** The handles for `placement`, seen from `camera`, for the parent's scene. */
+export const nodes = (model: Model, placement: Placement, camera: Camera): SceneNode =>
+  gizmoNodes(model.key, model.gizmo, placement, camera);

package/src/view.ts

@@ -44,6 +44,9 @@ export type DragDetail = typeof SceneSchema.DragDetail.Type;
  */
 export type Gesture = typeof SceneSchema.Gesture.Type;
 
+/** Detail of the end of a gesture that moved: the press's button, modifiers, mesh and view. */
+export type GestureEndDetail = typeof SceneSchema.GestureEndDetail.Type;
+
 /** Detail of collision events: the two bodies' keys, and whether they began touching. */
 export type CollisionDetail = typeof SceneSchema.CollisionDetail.Type;
 
@@ -119,6 +122,11 @@ export type ViewConfig<Message> = {
    * the camera stays in the Model.
    */
   readonly onGesture?: (gesture: Gesture) => Message;
+  /**
+   * A gesture that moved has ended (released, or the pointer left): finish what it drew,
+   * such as a `BoxSelect` box. Not after a press that never moved.
+   */
+  readonly onGestureEnd?: (detail: GestureEndDetail) => Message;
   /**
    * A gesture is about to begin on a camera turning by itself (`autoRotate`): keep where
    * it got to with `autoRotated(model.camera, detail)` (a view's camera when `view` names
@@ -239,6 +247,7 @@ export const view = <Message>(
     Option.map(given(config.onGesture), (toMessage) =>
       element.OnSceneGesture((detail) => toMessage(detail.gesture)),
     ),
+    Option.map(given(config.onGestureEnd), element.OnSceneGestureEnd),
     Option.map(given(config.onPerformanceChange), element.OnScenePerformance),
     Option.map(given(config.onError), element.OnSceneError),
     Option.map(given(config.onReconciled), element.OnSceneReconciled),

package/src/viewportGizmo.ts

@@ -0,0 +1,119 @@
+/**
+ * A viewport gizmo as a Foldkit submodel (roadmap, "Beyond parity" 5), after Drei's
+ * `GizmoHelper` with `GizmoViewport`: the core's `viewportGizmoNodes` in a scene's
+ * `hud`, its heads highlighted under the pointer, and a press on one turning the camera
+ * to look from that axis. The parent owns the camera; the submodel owns the highlight:
+ *
+ * - `Entered` and `Left` (the scene's pointer enter and leave, with the hit key)
+ *   highlight a head, and clear it;
+ * - `Pressed` (a pointer down, with the hit key and the camera) reports
+ *   `Turned { camera }`, the camera looking from that head's axis, for the parent to
+ *   keep. A camera with `damping` eases round to it, as Drei's tween does.
+ *
+ * `hud(model, camera)` is the scene's HUD with the gizmo in it; `nodes` the gizmo alone,
+ * for a HUD with more in it.
+ *
+ * @module
+ */
+import {
+  type Camera,
+  cameraAlong,
+  hud as describeHud,
+  type Hud,
+  type HudAlignment,
+  SceneSchema,
+  type SceneNode,
+  type ViewAxis,
+  viewportAxisOf,
+  viewportGizmoNodes,
+} from '@opsydyn/effect-three';
+import { Option, Schema } from 'effect';
+import { defineMessageUnion } from 'foldkit/message';
+import type { ReturnWithOutMessage } from 'foldkit/update';
+
+const Axis = Schema.Literals(['x', 'y', 'z', '-x', '-y', '-z']);
+
+export const Model = Schema.Struct({
+  /** The key its nodes are drawn under: `${key}:x`, `${key}:-y` and so on. */
+  key: Schema.String,
+  /** The head under the pointer. */
+  hovered: Schema.NullOr(Axis),
+  /** Leaves out the negative heads. */
+  hideNegativeAxes: Schema.Boolean,
+});
+export type Model = typeof Model.Type;
+
+export const Message = defineMessageUnion({
+  Entered: { key: Schema.String },
+  Left: { key: Schema.String },
+  Pressed: { key: Schema.String, camera: SceneSchema.Camera },
+});
+export type Message = typeof Message.Type;
+
+export const OutMessage = defineMessageUnion({
+  /** The camera, looking from the axis of the head pressed. */
+  Turned: { camera: SceneSchema.Camera },
+});
+export type OutMessage = typeof OutMessage.Type;
+
+/** A gizmo drawn under `key`, every head shown unless `hideNegativeAxes`. */
+export const init = (
+  key: string,
+  options: { readonly hideNegativeAxes?: boolean } = {},
+): Model => ({
+  key,
+  hovered: null,
+  hideNegativeAxes: options.hideNegativeAxes ?? false,
+});
+
+type Return = ReturnWithOutMessage<Model, Message, OutMessage>;
+
+/** Which head a hit `key` is on, if it is one of this gizmo's. */
+export const axisOf = (model: Model, key: string): Option.Option<ViewAxis> =>
+  Option.fromNullishOr(viewportAxisOf(model.key, key));
+
+const entered = (model: Model, key: string): Model =>
+  Option.match(axisOf(model, key), {
+    onNone: () => model,
+    onSome: (axis) => ({ ...model, hovered: axis }),
+  });
+
+/** Leaving a head clears the highlight; leaving anything else changes nothing. */
+const left = (model: Model, key: string): Model =>
+  Option.match(axisOf(model, key), {
+    onNone: () => model,
+    onSome: () => ({ ...model, hovered: null }),
+  });
+
+const pressed = (model: Model, key: string, camera: Camera): Return =>
+  Option.match(axisOf(model, key), {
+    onNone: () => ({ model }),
+    onSome: (axis) => ({
+      model,
+      outMessage: OutMessage.Turned({ camera: cameraAlong(camera, axis) }),
+    }),
+  });
+
+export const update = (model: Model, message: Message): Return =>
+  Message.match<Return>(message, {
+    Entered: ({ key }) => ({ model: entered(model, key) }),
+    Left: ({ key }) => ({ model: left(model, key) }),
+    Pressed: ({ key, camera }) => pressed(model, key, camera),
+  });
+
+/** The gizmo for `camera`, for a HUD. */
+export const nodes = (model: Model, camera: Camera): SceneNode =>
+  viewportGizmoNodes(model.key, camera, {
+    hovered: model.hovered,
+    hideNegativeAxes: model.hideNegativeAxes,
+  });
+
+/** A HUD holding only the gizmo, 80 pixels in from the bottom right unless placed. */
+export const hud = (
+  model: Model,
+  camera: Camera,
+  placement: {
+    readonly alignment?: HudAlignment;
+    readonly margin?: readonly [number, number];
+  } = {},
+): Hud => describeHud({ ...placement, children: [nodes(model, camera)] });