@puredesktop/puredesktop-ui-bridge 1.0.0-beta.1

package/src/components/common/canvas/CanvasElementFrame.tsx

@@ -0,0 +1,182 @@
+import type {
+  KeyboardEvent,
+  PointerEvent,
+  ReactElement,
+  ReactNode,
+} from 'react'
+import { styled } from 'styled-components'
+import type {
+  CanvasRect,
+  CanvasResizeHandle,
+  CanvasSize,
+} from './canvasGeometry.js'
+
+const HANDLE_POSITIONS: Record<CanvasResizeHandle, string> = {
+  nw: 'top: -6px; left: -6px; cursor: nwse-resize;',
+  ne: 'top: -6px; right: -6px; cursor: nesw-resize;',
+  se: 'right: -6px; bottom: -6px; cursor: nwse-resize;',
+  sw: 'bottom: -6px; left: -6px; cursor: nesw-resize;',
+}
+
+const Frame = styled.div<{
+  $active?: boolean
+  $readOnly?: boolean
+  $disabled?: boolean
+}>`
+  position: absolute;
+  z-index: 20;
+  box-sizing: border-box;
+  border: ${({ $active }) => ($active ? '2px' : '1.5px')} solid
+    ${({ $active, $readOnly }) =>
+      $active
+        ? 'color-mix(in srgb, var(--platform-color-accent, #3b6ff5) 82%, white)'
+        : $readOnly
+        ? 'rgb(127 127 127 / 42%)'
+        : 'rgb(127 127 127 / 58%)'};
+  background: ${({ $active }) =>
+    $active
+      ? 'color-mix(in srgb, var(--platform-color-accent, #3b6ff5) 8%, transparent)'
+      : 'transparent'};
+  box-shadow: ${({ $active }) =>
+    $active
+      ? '0 0 0 2px color-mix(in srgb, var(--platform-color-accent, #3b6ff5) 22%, transparent), 0 8px 22px rgb(0 0 0 / 16%)'
+      : '0 0 0 1px rgb(255 255 255 / 42%)'};
+  opacity: ${({ $disabled }) => ($disabled ? 0.55 : 1)};
+  pointer-events: ${({ $disabled }) => ($disabled ? 'none' : 'auto')};
+
+  &:hover {
+    border-style: solid;
+    border-color: ${({ $readOnly }) =>
+      $readOnly
+        ? 'rgb(127 127 127 / 60%)'
+        : 'color-mix(in srgb, var(--platform-color-accent, #3b6ff5) 68%, white)'};
+  }
+`
+
+const Label = styled.div`
+  position: absolute;
+  top: -25px;
+  left: -1px;
+  max-width: min(220px, 100%);
+  overflow: hidden;
+  padding: 3px 7px;
+  border-radius: 4px 4px 0 0;
+  background: color-mix(in srgb, var(--platform-color-surface, #ffffff) 96%, transparent);
+  box-shadow: 0 1px 4px rgb(0 0 0 / 14%);
+  color: var(--platform-color-text, #1f2430);
+  font-size: 12px;
+  font-weight: 760;
+  line-height: 1.2;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+`
+
+const Handle = styled.button<{ $handle: CanvasResizeHandle }>`
+  position: absolute;
+  width: 14px;
+  height: 14px;
+  padding: 0;
+  border: 2px solid currentColor;
+  border-radius: 3px;
+  background: var(--platform-color-surface, #ffffff);
+  color: var(--platform-color-accent, #3b6ff5);
+  box-shadow: 0 1px 5px rgb(0 0 0 / 20%);
+  ${({ $handle }) => HANDLE_POSITIONS[$handle]}
+`
+
+function percent(value: number, total: number): string {
+  return `${(value / total) * 100}%`
+}
+
+export interface CanvasElementFrameProps {
+  frame: CanvasRect
+  canvas: CanvasSize
+  label?: string
+  ariaLabel?: string
+  selected?: boolean
+  readOnly?: boolean
+  disabled?: boolean
+  children?: ReactNode
+  onSelect?: () => void
+  onMovePointerDown?: (event: PointerEvent<HTMLDivElement>) => void
+  onFrameKeyDown?: (event: KeyboardEvent<HTMLDivElement>) => void
+  onResizePointerDown?: (
+    handle: CanvasResizeHandle,
+    event: PointerEvent<HTMLButtonElement>,
+  ) => void
+}
+
+export function CanvasElementFrame({
+  frame,
+  canvas,
+  label,
+  ariaLabel,
+  selected,
+  readOnly,
+  disabled,
+  children,
+  onSelect,
+  onMovePointerDown,
+  onFrameKeyDown,
+  onResizePointerDown,
+}: CanvasElementFrameProps): ReactElement {
+  const resolvedAriaLabel = ariaLabel ?? `${label ?? 'Canvas element'}${
+    readOnly ? ', read-only' : ', selectable'
+  }${selected ? ', selected' : ''}`
+  return (
+    <Frame
+      data-canvas-element-frame="true"
+      data-canvas-selected={selected ? 'true' : undefined}
+      data-canvas-read-only={readOnly ? 'true' : undefined}
+      data-canvas-disabled={disabled ? 'true' : undefined}
+      $active={selected}
+      $readOnly={readOnly}
+      $disabled={disabled}
+      role="button"
+      tabIndex={disabled ? -1 : 0}
+      aria-label={resolvedAriaLabel}
+      aria-pressed={selected ? true : undefined}
+      aria-disabled={disabled ? true : undefined}
+      style={{
+        left: percent(frame.x, canvas.w),
+        top: percent(frame.y, canvas.h),
+        width: percent(frame.w, canvas.w),
+        height: percent(frame.h, canvas.h),
+        cursor: onMovePointerDown && !readOnly ? 'grab' : 'default',
+      }}
+      onClick={event => {
+        event.stopPropagation()
+        onSelect?.()
+      }}
+      onKeyDown={event => {
+        onFrameKeyDown?.(event)
+        if (event.defaultPrevented) return
+        if (event.key === 'Enter' || event.key === ' ') {
+          event.preventDefault()
+          onSelect?.()
+        }
+      }}
+      onPointerDown={event => {
+        if (readOnly) return
+        onMovePointerDown?.(event)
+      }}
+    >
+      {label ? <Label>{label}</Label> : null}
+      {children}
+      {selected && onResizePointerDown && !readOnly
+        ? (Object.keys(HANDLE_POSITIONS) as CanvasResizeHandle[]).map(handle => (
+            <Handle
+              key={handle}
+              type="button"
+              aria-label={`Resize ${label ?? 'element'} ${handle}`}
+              $handle={handle}
+              onPointerDown={event => {
+                event.stopPropagation()
+                onResizePointerDown(handle, event)
+              }}
+            />
+          ))
+        : null}
+    </Frame>
+  )
+}

package/src/components/common/canvas/canvasGeometry.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest'
+import {
+  clampCanvasRect,
+  clientDeltaToCanvas,
+  clientPointToCanvas,
+  moveCanvasRect,
+  resizeCanvasRect,
+} from './canvasGeometry.js'
+
+const canvas = { w: 1280, h: 720 }
+const viewport = { left: 10, top: 20, width: 640, height: 360 }
+
+describe('canvasGeometry', () => {
+  it('maps browser points and deltas into canvas coordinates', () => {
+    expect(
+      clientPointToCanvas({
+        clientX: 330,
+        clientY: 200,
+        viewport,
+        canvas,
+      }),
+    ).toEqual({ x: 640, y: 360 })
+
+    expect(
+      clientDeltaToCanvas({
+        deltaX: 50,
+        deltaY: 25,
+        viewport,
+        canvas,
+      }),
+    ).toEqual({ x: 100, y: 50 })
+  })
+
+  it('clamps rectangles to slide bounds', () => {
+    expect(
+      clampCanvasRect(
+        { x: -80, y: 700, w: 200, h: 100 },
+        canvas,
+        { w: 80, h: 40 },
+      ),
+    ).toEqual({ x: 0, y: 620, w: 200, h: 100 })
+  })
+
+  it('moves and snaps rectangles within the canvas', () => {
+    expect(
+      moveCanvasRect({
+        rect: { x: 90, y: 90, w: 200, h: 120 },
+        delta: { x: 23, y: 37 },
+        canvas,
+        gridStep: 20,
+      }),
+    ).toEqual({ x: 120, y: 120, w: 200, h: 120 })
+  })
+
+  it('resizes from handles and respects minimum size', () => {
+    expect(
+      resizeCanvasRect({
+        rect: { x: 100, y: 100, w: 200, h: 120 },
+        delta: { x: 80, y: 40 },
+        handle: 'nw',
+        canvas,
+        minimum: { w: 100, h: 80 },
+      }),
+    ).toEqual({ x: 180, y: 140, w: 120, h: 80 })
+  })
+})

package/src/components/common/canvas/canvasGeometry.ts

@@ -0,0 +1,133 @@
+export interface CanvasRect {
+  x: number
+  y: number
+  w: number
+  h: number
+}
+
+export interface CanvasSize {
+  w: number
+  h: number
+}
+
+export interface ViewportRect {
+  left: number
+  top: number
+  width: number
+  height: number
+}
+
+export interface CanvasPoint {
+  x: number
+  y: number
+}
+
+export type CanvasResizeHandle = 'nw' | 'ne' | 'se' | 'sw'
+
+export function canvasScale(
+  viewport: Pick<ViewportRect, 'width' | 'height'>,
+  canvas: CanvasSize,
+): number {
+  const xScale = viewport.width / canvas.w
+  const yScale = viewport.height / canvas.h
+  return Number.isFinite(xScale) && xScale > 0 ? xScale : yScale
+}
+
+export function clientPointToCanvas(input: {
+  clientX: number
+  clientY: number
+  viewport: ViewportRect
+  canvas: CanvasSize
+}): CanvasPoint {
+  const scale = canvasScale(input.viewport, input.canvas)
+  return {
+    x: (input.clientX - input.viewport.left) / scale,
+    y: (input.clientY - input.viewport.top) / scale,
+  }
+}
+
+export function clientDeltaToCanvas(input: {
+  deltaX: number
+  deltaY: number
+  viewport: Pick<ViewportRect, 'width' | 'height'>
+  canvas: CanvasSize
+}): CanvasPoint {
+  const scale = canvasScale(input.viewport, input.canvas)
+  return {
+    x: input.deltaX / scale,
+    y: input.deltaY / scale,
+  }
+}
+
+export function clampCanvasRect(
+  rect: CanvasRect,
+  canvas: CanvasSize,
+  minimum: Pick<CanvasRect, 'w' | 'h'> = { w: 24, h: 24 },
+): CanvasRect {
+  const w = Math.min(Math.max(rect.w, minimum.w), canvas.w)
+  const h = Math.min(Math.max(rect.h, minimum.h), canvas.h)
+  return {
+    x: Math.min(Math.max(rect.x, 0), canvas.w - w),
+    y: Math.min(Math.max(rect.y, 0), canvas.h - h),
+    w,
+    h,
+  }
+}
+
+export function moveCanvasRect(input: {
+  rect: CanvasRect
+  delta: CanvasPoint
+  canvas: CanvasSize
+  gridStep?: number
+}): CanvasRect {
+  return clampCanvasRect(
+    snapCanvasRect(
+      {
+        ...input.rect,
+        x: input.rect.x + input.delta.x,
+        y: input.rect.y + input.delta.y,
+      },
+      input.gridStep,
+    ),
+    input.canvas,
+  )
+}
+
+export function resizeCanvasRect(input: {
+  rect: CanvasRect
+  delta: CanvasPoint
+  handle: CanvasResizeHandle
+  canvas: CanvasSize
+  minimum?: Pick<CanvasRect, 'w' | 'h'>
+  gridStep?: number
+}): CanvasRect {
+  const { rect, delta, handle } = input
+  const left = handle.includes('w')
+  const top = handle.includes('n')
+  const next = {
+    x: left ? rect.x + delta.x : rect.x,
+    y: top ? rect.y + delta.y : rect.y,
+    w: left ? rect.w - delta.x : rect.w + delta.x,
+    h: top ? rect.h - delta.y : rect.h + delta.y,
+  }
+  return clampCanvasRect(
+    snapCanvasRect(next, input.gridStep),
+    input.canvas,
+    input.minimum,
+  )
+}
+
+export function snapCanvasRect(
+  rect: CanvasRect,
+  gridStep = 0,
+): CanvasRect {
+  if (gridStep <= 0) return rect
+  const snap = (value: number): number =>
+    Math.round(value / gridStep) * gridStep
+  return {
+    x: snap(rect.x),
+    y: snap(rect.y),
+    w: Math.max(gridStep, snap(rect.w)),
+    h: Math.max(gridStep, snap(rect.h)),
+  }
+}

package/src/components/common/canvas/index.ts

@@ -0,0 +1,27 @@
+export { CanvasElementFrame } from './CanvasElementFrame.js'
+export type { CanvasElementFrameProps } from './CanvasElementFrame.js'
+export type CanvasElementPlacement = 'flow' | 'absolute'
+export type CanvasElementDropSide = 'before' | 'left' | 'right'
+export {
+  canvasScale,
+  clampCanvasRect,
+  clientDeltaToCanvas,
+  clientPointToCanvas,
+  moveCanvasRect,
+  resizeCanvasRect,
+  snapCanvasRect,
+} from './canvasGeometry.js'
+export type {
+  CanvasPoint,
+  CanvasRect,
+  CanvasResizeHandle,
+  CanvasSize,
+  ViewportRect,
+} from './canvasGeometry.js'
+export { useCanvasDragResize } from './useCanvasDragResize.js'
+export type {
+  CanvasDragKind,
+  CanvasDragState,
+  UseCanvasDragResizeOptions,
+  UseCanvasDragResizeResult,
+} from './useCanvasDragResize.js'

package/src/components/common/canvas/useCanvasDragResize.test.tsx

@@ -0,0 +1,152 @@
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, describe, expect, it } from 'vitest'
+import type { CanvasRect, CanvasSize, ViewportRect } from './canvasGeometry.js'
+import { useCanvasDragResize } from './useCanvasDragResize.js'
+
+const canvas: CanvasSize = { w: 1280, h: 720 }
+const viewport: ViewportRect = { left: 0, top: 0, width: 640, height: 360 }
+const frame: CanvasRect = { x: 120, y: 80, w: 240, h: 120 }
+
+;(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean })
+  .IS_REACT_ACT_ENVIRONMENT = true
+
+let root: Root | null = null
+let host: HTMLDivElement | null = null
+
+afterEach(() => {
+  act(() => {
+    root?.unmount()
+  })
+  root = null
+  host?.remove()
+  host = null
+})
+
+function dispatchPointer(
+  target: EventTarget,
+  type: string,
+  init: PointerEventInit,
+): void {
+  target.dispatchEvent(
+    new PointerEvent(type, {
+      bubbles: true,
+      cancelable: true,
+      pointerId: 1,
+      buttons: type === 'pointerup' || type === 'pointercancel' ? 0 : 1,
+      ...init,
+    }),
+  )
+}
+
+function Harness({
+  onPreview,
+  onCommit,
+}: {
+  onPreview: (rect: CanvasRect) => void
+  onCommit: (rect: CanvasRect) => void
+}) {
+  const drag = useCanvasDragResize({
+    canvas,
+    getViewport: () => viewport,
+    gridStep: 10,
+    minimum: { w: 80, h: 60 },
+    onPreview,
+    onCommit,
+  })
+
+  return (
+    <button
+      type="button"
+      data-drag-kind={drag.dragState?.kind ?? 'none'}
+      data-suppress-click={drag.shouldSuppressClick ? 'true' : 'false'}
+      onClick={() => drag.clearClickSuppression()}
+      onPointerDown={event => drag.beginMove(frame, event)}
+    >
+      Move
+    </button>
+  )
+}
+
+function mountHarness(input: {
+  onPreview?: (rect: CanvasRect) => void
+  onCommit?: (rect: CanvasRect) => void
+} = {}): HTMLButtonElement {
+  host = document.createElement('div')
+  document.body.append(host)
+  root = createRoot(host)
+  act(() => {
+    root?.render(
+      <Harness
+        onPreview={input.onPreview ?? (() => undefined)}
+        onCommit={input.onCommit ?? (() => undefined)}
+      />,
+    )
+  })
+  const button = host.querySelector('button')
+  if (!button) throw new Error('Harness button did not render')
+  return button
+}
+
+describe('useCanvasDragResize', () => {
+  it('previews and commits moved frames from pointer deltas', () => {
+    const previews: CanvasRect[] = []
+    const commits: CanvasRect[] = []
+    const button = mountHarness({
+      onPreview: rect => previews.push(rect),
+      onCommit: rect => commits.push(rect),
+    })
+
+    act(() => {
+      dispatchPointer(button, 'pointerdown', { clientX: 40, clientY: 40 })
+      dispatchPointer(window, 'pointermove', { clientX: 70, clientY: 60 })
+    })
+
+    expect(button.dataset.dragKind).toBe('move')
+    expect(previews).toEqual([{ x: 180, y: 120, w: 240, h: 120 }])
+
+    act(() => {
+      dispatchPointer(window, 'pointerup', { clientX: 70, clientY: 60 })
+    })
+
+    expect(commits).toEqual([{ x: 180, y: 120, w: 240, h: 120 }])
+    expect(button.dataset.dragKind).toBe('none')
+    expect(button.dataset.suppressClick).toBe('true')
+  })
+
+  it('does not commit or suppress clicks for selection-only pointer presses', () => {
+    const commits: CanvasRect[] = []
+    const button = mountHarness({ onCommit: rect => commits.push(rect) })
+
+    act(() => {
+      dispatchPointer(button, 'pointerdown', { clientX: 40, clientY: 40 })
+      dispatchPointer(window, 'pointerup', { clientX: 41, clientY: 41 })
+    })
+
+    expect(commits).toEqual([])
+    expect(button.dataset.suppressClick).toBe('false')
+  })
+
+  it('restores the preview and does not commit when the pointer drag is cancelled', () => {
+    const previews: CanvasRect[] = []
+    const commits: CanvasRect[] = []
+    const button = mountHarness({
+      onPreview: rect => previews.push(rect),
+      onCommit: rect => commits.push(rect),
+    })
+
+    act(() => {
+      dispatchPointer(button, 'pointerdown', { clientX: 40, clientY: 40 })
+      dispatchPointer(window, 'pointermove', { clientX: 70, clientY: 60 })
+      dispatchPointer(window, 'pointercancel', { clientX: 70, clientY: 60 })
+    })
+
+    expect(previews).toEqual([
+      { x: 180, y: 120, w: 240, h: 120 },
+      frame,
+    ])
+    expect(commits).toEqual([])
+    expect(button.dataset.dragKind).toBe('none')
+    expect(button.dataset.suppressClick).toBe('false')
+  })
+})