Access caret transformation, selection transformations, and range for the input component fixes #114

Author: bbohlender

docs/getting-started/components-and-properties.md

@@ -291,6 +291,23 @@ The `Input` component extends the `Text` component and allows the user to change
 </Root>
 ```
 
+The `Input` component also exposes a ref that provides access to various properties and methods for controlling the input programmatically. This ref can be used to focus or blur the input, access the current value, and get information about the selection and caret position.
+
+<details>
+<summary>View all properties exposed in the Input ref</summary>
+
+| Property                 | Description                                                      |
+| ------------------------ | ---------------------------------------------------------------- |
+| current                  | A signal containing the current value of the input               |
+| focus                    | Method to programmatically focus the input                       |
+| blur                     | Method to programmatically remove focus from the input           |
+| element                  | A signal containing the underlying HTML element                  |
+| selectionRange           | A signal containing the current selection range [start, end]     |
+| caretTransformation      | A signal containing information about the caret's transformation (position and height) |
+| selectionTransformations | A signal containing the transformations for all selection (boxes)  |
+
+</details>
+
 <details>
 <summary>View all properties specific to the `Input` component</summary>
 

packages/react/src/input.tsx

@@ -1,5 +1,5 @@
 import { forwardRef, ReactNode, RefAttributes, useEffect, useMemo, useRef } from 'react'
-import { Object3D } from 'three'
+import { Object3D, Vector2Tuple } from 'three'
 import { useParent } from './context.js'
 import { AddHandlers, R3FEventMap, usePropertySignals } from './utils.js'
 import {
@@ -9,6 +9,8 @@ import {
   createInput,
   initialize,
   unsubscribeSubscriptions,
+  CaretTransformation,
+  SelectionTransformation,
 } from '@pmndrs/uikit/internals'
 import { ComponentInternals, useComponentInternals } from './ref.js'
 import { ReadonlySignal, signal } from '@preact/signals-core'
@@ -21,6 +23,9 @@ export type InputInternals = ComponentInternals<BaseInputProperties<R3FEventMap>
   focus: () => void
   blur: () => void
   element: ReadonlySignal<HTMLInputElement | HTMLTextAreaElement | undefined>
+  selectionRange: ReadonlySignal<Vector2Tuple | undefined>
+  caretTransformation: ReadonlySignal<CaretTransformation | undefined>
+  selectionTransformations: ReadonlySignal<Array<SelectionTransformation>>
 }
 
 export type InputProperties = BaseInputProperties<R3FEventMap> & {
@@ -68,8 +73,19 @@ export const Input: (props: InputProperties & RefAttributes<InputRef>) => ReactN
         blur: internals.blur,
         current: internals.valueSignal,
         element: internals.element,
+        selectionRange: internals.selectionRange,
+        caretTransformation: internals.caretTransformation,
+        selectionTransformations: internals.selectionTransformations,
       }),
-      [internals.focus, internals.blur, internals.valueSignal, internals.element],
+      [
+        internals.focus,
+        internals.blur,
+        internals.valueSignal,
+        internals.element,
+        internals.caretTransformation,
+        internals.selectionRange,
+        internals.selectionTransformations,
+      ],
     ),
   )
 

packages/react/src/portal.tsx

@@ -9,6 +9,7 @@ import {
   Raycaster,
   Vector2,
   Vector3,
+  OrthographicCamera,
 } from 'three'
 import { Image } from './image.js'
 import { InjectState, RootState, reconciler, useFrame, useStore, context } from '@react-three/fiber'
@@ -32,9 +33,9 @@ export const privateKeys = [
   'viewport',
 ]
 
-type Camera = THREE.OrthographicCamera | THREE.PerspectiveCamera
-const isOrthographicCamera = (def: Camera): def is THREE.OrthographicCamera =>
-  def && (def as THREE.OrthographicCamera).isOrthographicCamera
+type Camera = OrthographicCamera | PerspectiveCamera
+const isOrthographicCamera = (def: Camera): def is OrthographicCamera =>
+  def && (def as OrthographicCamera).isOrthographicCamera
 
 type BasePortalProperties = Omit<ImageProperties<R3FEventMap>, 'src' | 'objectFit'>
 

packages/uikit/src/caret.ts

@@ -1,5 +1,5 @@
 import { Signal, computed, effect, signal } from '@preact/signals-core'
-import { Matrix4, Vector3Tuple } from 'three'
+import { Matrix4, Vector2Tuple } from 'three'
 import { ClippingRect } from './clipping.js'
 import { ElementType, OrderInfo, computedOrderInfo } from './order.js'
 import { PanelProperties, createInstancedPanel } from './panel/instanced-panel.js'
@@ -12,6 +12,11 @@ import {
 } from './panel/index.js'
 import { MergedProperties, computedInheritableProperty } from './properties/index.js'
 
+export type CaretTransformation = {
+  position: Vector2Tuple
+  height: number
+}
+
 export type CaretWidthProperties = {
   caretWidth?: number
 }
@@ -66,7 +71,7 @@ function getCaretMaterialConfig() {
 export function createCaret(
   propertiesSignal: Signal<MergedProperties>,
   matrix: Signal<Matrix4 | undefined>,
-  caretPosition: Signal<Vector3Tuple | undefined>,
+  caretTransformation: Signal<CaretTransformation | undefined>,
   isVisible: Signal<boolean>,
   parentOrderInfo: Signal<OrderInfo | undefined>,
   parentClippingRect: Signal<ClippingRect | undefined> | undefined,
@@ -80,16 +85,16 @@ export function createCaret(
     defaultPanelDependencies,
     parentOrderInfo,
   )
-  const blinkingCaretPosition = signal<Vector3Tuple | undefined>(undefined)
+  const blinkingCaretTransformation = signal<CaretTransformation | undefined>(undefined)
   initializers.push(() =>
     effect(() => {
-      const pos = caretPosition.value
+      const pos = caretTransformation.value
       if (pos == null) {
-        blinkingCaretPosition.value = undefined
+        blinkingCaretTransformation.value = undefined
       }
-      blinkingCaretPosition.value = pos
+      blinkingCaretTransformation.value = pos
       const ref = setInterval(
-        () => (blinkingCaretPosition.value = blinkingCaretPosition.peek() == null ? pos : undefined),
+        () => (blinkingCaretTransformation.value = blinkingCaretTransformation.peek() == null ? pos : undefined),
         500,
       )
       return () => clearInterval(ref)
@@ -106,14 +111,14 @@ export function createCaret(
       panelGroupManager,
       matrix,
       computed(() => {
-        const size = blinkingCaretPosition.value
-        if (size == null) {
+        const height = blinkingCaretTransformation.value?.height
+        if (height == null) {
           return [0, 0]
         }
-        return [caretWidth.value, size[2]]
+        return [caretWidth.value, height]
       }),
       computed(() => {
-        const position = blinkingCaretPosition.value
+        const position = blinkingCaretTransformation.value?.position
         if (position == null) {
           return [0, 0]
         }

packages/uikit/src/components/input.ts

@@ -37,8 +37,8 @@ import { PanelGroupProperties, computedPanelGroupDependencies } from '../panel/i
 import { createInteractionPanel } from '../panel/instanced-panel-mesh.js'
 import { EventHandlers, ThreeEventMap, ThreePointerEvent } from '../events.js'
 import { Vector2Tuple, Vector2, Vector3Tuple } from 'three'
-import { CaretProperties, createCaret } from '../caret.js'
-import { SelectionBoxes, SelectionProperties, createSelection } from '../selection.js'
+import { CaretProperties, CaretTransformation, createCaret } from '../caret.js'
+import { SelectionTransformation, SelectionProperties, createSelection } from '../selection.js'
 import { WithFocus, createFocusPropertyTransformers } from '../focus.js'
 import {
   FontFamilies,
@@ -185,13 +185,13 @@ export function createInput<EM extends ThreeEventMap = ThreeEventMap>(
   )
 
   const instancedTextRef: { current?: InstancedText } = {}
-  const selectionBoxes = signal<SelectionBoxes>([])
-  const caretPosition = signal<Vector3Tuple | undefined>(undefined)
+  const selectionTransformations = signal<Array<SelectionTransformation>>([])
+  const caretTransformation = signal<CaretTransformation | undefined>(undefined)
   const selectionRange = signal<Vector2Tuple | undefined>(undefined)
   createCaret(
     mergedProperties,
     globalMatrix,
-    caretPosition,
+    caretTransformation,
     isVisible,
     backgroundOrderInfo,
     parentCtx.clippingRect,
@@ -201,7 +201,7 @@ export function createInput<EM extends ThreeEventMap = ThreeEventMap>(
   const selectionOrderInfo = createSelection(
     mergedProperties,
     globalMatrix,
-    selectionBoxes,
+    selectionTransformations,
     isVisible,
     backgroundOrderInfo,
     parentCtx.clippingRect,
@@ -240,8 +240,8 @@ export function createInput<EM extends ThreeEventMap = ThreeEventMap>(
     fontSignal,
     parentCtx.root.gylphGroupManager,
     selectionRange,
-    selectionBoxes,
-    caretPosition,
+    selectionTransformations,
+    caretTransformation,
     instancedTextRef,
     initializers,
     multiline ? 'break-word' : 'keep-all',
@@ -335,6 +335,9 @@ export function createInput<EM extends ThreeEventMap = ThreeEventMap>(
     interactionPanel,
     handlers,
     initializers,
+    selectionRange,
+    caretTransformation,
+    selectionTransformations,
   })
 }
 

packages/uikit/src/index.ts

@@ -26,3 +26,5 @@ export type {
 export * from './vanilla/index.js'
 export { htmlToCode } from './convert/html/index.js'
 export type { ColorRepresentation } from './utils.js'
+export type { CaretTransformation } from './caret.js'
+export type { SelectionTransformation } from './selection.js'

packages/uikit/src/internals.ts

@@ -14,6 +14,8 @@ export * from './panel/index.js'
 export * from './scroll.js'
 export * from './components/index.js'
 export * from './convert/html/internals.js'
+export * from './caret.js'
+export * from './selection.js'
 
 export type * from './events.js'
 export type * from './context.js'

packages/uikit/src/selection.ts

@@ -18,7 +18,7 @@ import {
 } from './panel/index.js'
 import { MergedProperties } from './properties/index.js'
 
-export type SelectionBoxes = Array<{ size: Vector2Tuple; position: Vector2Tuple }>
+export type SelectionTransformation = { size: Vector2Tuple; position: Vector2Tuple }
 
 export type SelectionBorderSizeProperties = {
   selectionBorderRightWidth?: number
@@ -69,7 +69,7 @@ function getSelectionMaterialConfig() {
 export function createSelection(
   propertiesSignal: Signal<MergedProperties>,
   matrix: Signal<Matrix4 | undefined>,
-  selectionBoxes: Signal<SelectionBoxes>,
+  selectionTransformations: Signal<Array<SelectionTransformation>>,
   isVisible: Signal<boolean>,
   prevOrderInfo: Signal<OrderInfo | undefined>,
   parentClippingRect: Signal<ClippingRect | undefined> | undefined,
@@ -93,7 +93,7 @@ export function createSelection(
   initializers.push(
     () =>
       effect(() => {
-        const selections = selectionBoxes.value
+        const selections = selectionTransformations.value
         const selectionsLength = selections.length
         for (let i = 0; i < selectionsLength; i++) {
           let panelData = panels[i]

packages/uikit/src/text/render/instanced-text.ts

@@ -12,11 +12,12 @@ import {
 } from '../utils.js'
 import { GlyphGroupManager, InstancedGlyphGroup } from './instanced-glyph-group.js'
 import { GlyphLayout, GlyphLayoutProperties, buildGlyphLayout, computedCustomLayouting } from '../layout.js'
-import { SelectionBoxes } from '../../selection.js'
+import { SelectionTransformation } from '../../selection.js'
 import { OrderInfo } from '../../order.js'
 import { Font } from '../font.js'
 import { MergedProperties, computedInheritableProperty } from '../../properties/index.js'
 import { FlexNode, FlexNodeState } from '../../flex/index.js'
+import { CaretTransformation } from '../../caret.js'
 
 export type TextAlignProperties = {
   textAlign?: keyof typeof alignmentXMap | 'block'
@@ -43,8 +44,8 @@ export function createInstancedText(
   fontSignal: Signal<Font | undefined>,
   glyphGroupManager: GlyphGroupManager,
   selectionRange: Signal<Vector2Tuple | undefined> | undefined,
-  selectionBoxes: Signal<SelectionBoxes> | undefined,
-  caretPosition: Signal<Vector3Tuple | undefined> | undefined,
+  selectionTransformations: Signal<Array<SelectionTransformation>> | undefined,
+  caretTransformation: Signal<CaretTransformation | undefined> | undefined,
   instancedTextRef: { current?: InstancedText } | undefined,
   initializers: Initializers,
   defaultWordBreak: GlyphLayoutProperties['wordBreak'],
@@ -108,8 +109,8 @@ export function createInstancedText(
           isVisible,
           parentClippingRect,
           selectionRange,
-          selectionBoxes,
-          caretPosition,
+          selectionTransformations,
+          caretTransformation,
         )
         if (instancedTextRef != null) {
           instancedTextRef.current = instancedText
@@ -121,7 +122,7 @@ export function createInstancedText(
   return customLayouting
 }
 
-const noSelectionBoxes: SelectionBoxes = []
+const noSelectionTransformations: Array<SelectionTransformation> = []
 
 export class InstancedText {
   private glyphLines: Array<Array<InstancedGlyph | number>> = []
@@ -142,8 +143,8 @@ export class InstancedText {
     isVisible: Signal<boolean>,
     private parentClippingRect: Signal<ClippingRect | undefined> | undefined,
     private selectionRange: Signal<Vector2Tuple | undefined> | undefined,
-    private selectionBoxes: Signal<SelectionBoxes> | undefined,
-    private caretPosition: Signal<Vector3Tuple | undefined> | undefined,
+    private selectionTransformations: Signal<Array<SelectionTransformation>> | undefined,
+    private caretTransformation: Signal<CaretTransformation | undefined> | undefined,
   ) {
     this.unsubscribeInitialList = [
       effect(() => {
@@ -194,12 +195,12 @@ export class InstancedText {
     verticalAlign: keyof typeof alignmentYMap,
     textAlign: keyof typeof alignmentXMap | 'block',
   ): void {
-    if (this.caretPosition == null || this.selectionBoxes == null) {
+    if (this.caretTransformation == null || this.selectionTransformations == null) {
       return
     }
     if (range == null || layout == null || layout.lines.length === 0) {
-      this.caretPosition.value = undefined
-      this.selectionBoxes.value = noSelectionBoxes
+      this.caretTransformation.value = undefined
+      this.selectionTransformations.value = noSelectionTransformations
       return
     }
     const whitespaceWidth = layout.font.getGlyphInfo(' ').xadvance * layout.fontSize
@@ -212,39 +213,41 @@ export class InstancedText {
         lineIndex * getOffsetToNextLine(layout.lineHeight, layout.fontSize) +
         getGlyphOffsetY(layout.fontSize, layout.lineHeight)
       )
-      this.caretPosition.value = [x, y - layout.fontSize / 2, layout.fontSize]
-      this.selectionBoxes.value = []
+      this.caretTransformation.value = { position: [x, y - layout.fontSize / 2], height: layout.fontSize }
+      this.selectionTransformations.value = []
       return
     }
-    this.caretPosition.value = undefined
+    this.caretTransformation.value = undefined
     const start = this.getGlyphLineAndX(layout, startCharIndexIncl, true, whitespaceWidth, textAlign)
     const end = this.getGlyphLineAndX(layout, endCharIndexExcl - 1, false, whitespaceWidth, textAlign)
     if (start.lineIndex === end.lineIndex) {
-      this.selectionBoxes.value = [
-        this.computeSelectionBox(start.lineIndex, start.x, end.x, layout, verticalAlign, whitespaceWidth),
+      this.selectionTransformations.value = [
+        this.computeSelectionTransformation(start.lineIndex, start.x, end.x, layout, verticalAlign, whitespaceWidth),
       ]
       return
     }
-    const newSelectionBoxes: SelectionBoxes = [
-      this.computeSelectionBox(start.lineIndex, start.x, undefined, layout, verticalAlign, whitespaceWidth),
+    const newSelectionTransformations: Array<SelectionTransformation> = [
+      this.computeSelectionTransformation(start.lineIndex, start.x, undefined, layout, verticalAlign, whitespaceWidth),
     ]
     for (let i = start.lineIndex + 1; i < end.lineIndex; i++) {
-      newSelectionBoxes.push(this.computeSelectionBox(i, undefined, undefined, layout, verticalAlign, whitespaceWidth))
+      newSelectionTransformations.push(
+        this.computeSelectionTransformation(i, undefined, undefined, layout, verticalAlign, whitespaceWidth),
+      )
     }
-    newSelectionBoxes.push(
-      this.computeSelectionBox(end.lineIndex, undefined, end.x, layout, verticalAlign, whitespaceWidth),
+    newSelectionTransformations.push(
+      this.computeSelectionTransformation(end.lineIndex, undefined, end.x, layout, verticalAlign, whitespaceWidth),
     )
-    this.selectionBoxes.value = newSelectionBoxes
+    this.selectionTransformations.value = newSelectionTransformations
   }
 
-  private computeSelectionBox(
+  private computeSelectionTransformation(
     lineIndex: number,
     startX: number | undefined,
     endX: number | undefined,
     layout: GlyphLayout,
     verticalAlign: keyof typeof alignmentYMap,
     whitespaceWidth: number,
-  ): SelectionBoxes[number] {
+  ): SelectionTransformation {
     const lineGlyphs = this.glyphLines[lineIndex]
     if (startX == null) {
       startX = this.getGlyphX(lineGlyphs[0], 0, whitespaceWidth)