Merge pull request #743 from sugarlabs/704

704 feat(masonry) observe feedback when connecting/disconnecting Bricks

Author: meganindya

modules/masonry/src/components/Tower/TowerBrick.tsx

@@ -27,7 +27,12 @@ export const TowerBrickView = memo(function (props: TowerBrickViewProps) {
 
   useBrickMove(id, ref);
 
-  const { x, y } = useBrickLayoutStore((state) => state.coords[id]);
+  // We explicitly extract coords without returning a fallback object in the selector.
+  // Returning a new `{ x: 0, y: 0 }` object inside the selector would cause useSyncExternalStore
+  // to detect a new reference on every render, triggering an infinite re-render loop.
+  const coords = useBrickLayoutStore((state) => state.coords[id]);
+  const x = coords?.x ?? 0;
+  const y = coords?.y ?? 0;
   const isMounted = useBrickLayoutStore((state) => state.mounted[id]);
   const isPositioned = useBrickLayoutStore((state) => state.positioned[id]);
 

modules/masonry/src/components/Workspace/DisconnectShadowView.test.tsx

@@ -0,0 +1,34 @@
+import { render } from '@testing-library/react';
+import { describe, it, expect, beforeEach } from 'vitest';
+import { DisconnectShadowView } from './DisconnectShadowView';
+import { useConnectionPreviewStore } from '@/stores/connection-preview';
+import { useBrickLayoutStore } from '@/stores/brick';
+
+describe('DisconnectShadowView', () => {
+  beforeEach(() => {
+    useConnectionPreviewStore.setState({
+      activeTarget: null,
+      isValid: false,
+      snapPosition: null,
+      disconnectShadow: null,
+    });
+    useBrickLayoutStore.setState({ coords: {} });
+  });
+
+  it('renders nothing when there is no disconnect shadow', () => {
+    const { container } = render(<DisconnectShadowView />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('renders nothing when the host coordinates are not found', () => {
+    useConnectionPreviewStore.setState({
+      disconnectShadow: {
+        hostTowerId: 'tower1',
+        hostBrickId: 'missing-host',
+        socket: 'next',
+      },
+    });
+    const { container } = render(<DisconnectShadowView />);
+    expect(container.firstChild).toBeNull();
+  });
+});

modules/masonry/src/components/Workspace/DisconnectShadowView.tsx

@@ -0,0 +1,138 @@
+import { useMemo } from 'react';
+import type { BrickViewProps, BrickViewPropsWithModel } from '@/@types/brick.types';
+import { BrickView } from '@/components/Brick/Brick';
+import { useConnectionPreviewStore } from '@/stores/connection-preview';
+import { findNodeAndTower } from '@/stores/workspace';
+import { useBrickLayoutStore } from '@/stores/brick';
+import { createBrickModel } from '@/utils/brick-model-factory';
+import { SCALE_LEVEL_CONFIG } from '@/utils/constants';
+
+/**
+ * Renders a "ghost" footprint (DisconnectShadow) exactly where a brick was just disconnected from.
+ * This provides visual feedback to the user, showing them the empty slot where the brick
+ * previously lived before they dropped it somewhere else or deleted it.
+ * It automatically disappears once the user finishes dragging and drops the brick.
+ */
+export function DisconnectShadowView() {
+  const disconnectShadow = useConnectionPreviewStore((state) => state.disconnectShadow);
+
+  // We need the exact coordinates of the host brick to render the shadow at the correct location
+  const hostCoords = useBrickLayoutStore((state) =>
+    disconnectShadow ? state.coords[disconnectShadow.hostBrickId] : null,
+  );
+
+  // Generate a dummy grey "ghost" model that perfectly matches the shape of the disconnected brick
+  const shadowModel = useMemo(() => {
+    if (!disconnectShadow || !hostCoords) return null;
+
+    const found = findNodeAndTower(disconnectShadow.hostBrickId);
+    if (!found) return null;
+    const hostModel = found.node.model;
+
+    const colors = { background: '#d1d5db', foreground: 'transparent', border: '#9ca3af' };
+
+    if (typeof disconnectShadow.socket === 'number' || disconnectShadow.socket === 'output') {
+      const props: BrickViewProps = {
+        kind: 'value',
+        widget: { type: 'label', text: '' },
+        colorsDefault: colors,
+        tooltipText: '',
+        scaleLevel: hostModel.scaleLevel,
+      };
+      return createBrickModel(props);
+    } else {
+      const props: BrickViewProps = {
+        kind: 'statement',
+        widget: { type: 'label', text: '' },
+        colorsDefault: colors,
+        hasConnectionPrev: true,
+        hasConnectionNext: true,
+        tooltipText: '',
+        scaleLevel: hostModel.scaleLevel,
+      };
+      return createBrickModel(props);
+    }
+  }, [disconnectShadow, hostCoords]);
+
+  // Calculate the precise absolute coordinates on the workspace where the shadow should render.
+  // We extract the exact connector bounds (e.g. the notch for 'next') and scale it.
+  const snapPosition = useMemo(() => {
+    if (!disconnectShadow || !shadowModel || !hostCoords) return null;
+
+    const found = findNodeAndTower(disconnectShadow.hostBrickId);
+    if (!found) return null;
+
+    const hostModel = found.node.model;
+    const connectors = hostModel.getConnectorCoords();
+
+    let hostBounds = null;
+    if (disconnectShadow.socket === 'next') {
+      hostBounds = connectors.next;
+    } else if (disconnectShadow.socket === 'nestedNext') {
+      hostBounds = connectors.nestedNext;
+      // If the host block's cavity collapsed (because we just detached its last child),
+      // connectors.nestedNext will be missing. We can synthesize its exact location
+      // by shifting the bottom tab to the right by TAIL_INDENT_W (8) + strokeWidth.
+      if (!hostBounds && connectors.next) {
+        const strokeWidth = hostModel.scaleLevel * 2;
+        hostBounds = {
+          x: connectors.next.x + 8 + strokeWidth,
+          y: connectors.next.y,
+          w: connectors.next.w,
+          h: connectors.next.h,
+        };
+      }
+    } else if (typeof disconnectShadow.socket === 'number') {
+      hostBounds = connectors.inputs[disconnectShadow.socket];
+    } else if (disconnectShadow.socket === 'output') hostBounds = connectors.output;
+
+    const hostScale = SCALE_LEVEL_CONFIG[hostModel.scaleLevel].brickScale;
+    const hx = hostCoords.x + (hostBounds ? hostBounds.x * hostScale : 0);
+    const hy = hostCoords.y + (hostBounds ? hostBounds.y * hostScale : 0);
+
+    const shadowScale = SCALE_LEVEL_CONFIG[shadowModel.scaleLevel].brickScale;
+    const shadowConnectors = shadowModel.getConnectorCoords();
+    const shadowBounds =
+      typeof disconnectShadow.socket === 'number' || disconnectShadow.socket === 'output'
+        ? shadowConnectors.output
+        : shadowConnectors.prev;
+
+    const dx = shadowBounds ? shadowBounds.x * shadowScale : 0;
+    const dy = shadowBounds ? shadowBounds.y * shadowScale : 0;
+
+    const strokeWidthOffset = 2 * hostScale; // STROKE_WIDTH = 2
+    let snapX = hx - dx;
+    let snapY = hy - dy;
+
+    // The layout engine makes strokes abut rather than overlap
+    if (typeof disconnectShadow.socket === 'number' || disconnectShadow.socket === 'output') {
+      snapX += strokeWidthOffset;
+    } else {
+      snapY += strokeWidthOffset;
+    }
+
+    return {
+      x: snapX,
+      y: snapY,
+    };
+  }, [disconnectShadow, hostCoords, shadowModel]);
+
+  if (!disconnectShadow || !snapPosition || !shadowModel) return null;
+
+  const viewProps = {
+    kind: shadowModel.kind,
+    model: shadowModel,
+  } as unknown as BrickViewPropsWithModel;
+
+  return (
+    <div
+      data-testid="disconnect-shadow-view"
+      className="pointer-events-none absolute top-0 left-0 z-20 opacity-80"
+      style={{
+        transform: `translate(${snapPosition.x}px, ${snapPosition.y}px)`,
+      }}
+    >
+      <BrickView {...viewProps} />
+    </div>
+  );
+}

modules/masonry/src/components/Workspace/SnapHintOverlay.test.tsx

@@ -0,0 +1,65 @@
+import { render } from '@testing-library/react';
+import { describe, it, expect, beforeEach } from 'vitest';
+import { SnapHintOverlay } from './SnapHintOverlay';
+import { useConnectionPreviewStore } from '@/stores/connection-preview';
+
+describe('SnapHintOverlay', () => {
+  beforeEach(() => {
+    useConnectionPreviewStore.setState({
+      activeTarget: null,
+      isValid: false,
+      snapPosition: null,
+      disconnectShadow: null,
+    });
+  });
+
+  it('renders nothing when there is no active target', () => {
+    const { container } = render(<SnapHintOverlay />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('renders valid hint overlay with correct position and color', () => {
+    useConnectionPreviewStore.setState({
+      activeTarget: {
+        draggedTowerId: 'tower1',
+        targetTowerId: 'tower2',
+        targetBrickId: 'brick1',
+        type: 'statement',
+        distance: 5,
+        centroid: { x: 100, y: 150 },
+      },
+      isValid: true,
+    });
+
+    const { getByTestId } = render(<SnapHintOverlay />);
+    const overlay = getByTestId('snap-hint-overlay');
+
+    expect(overlay).toBeTruthy();
+    expect(overlay.style.left).toBe('100px');
+    expect(overlay.style.top).toBe('150px');
+    expect(overlay.style.transform).toContain('scale(1.2)');
+    // Valid color falls back to rgba(34, 197, 94, 0.4) because towers store is empty in this test
+    expect(overlay.style.backgroundColor).toBe('rgba(34, 197, 94, 0.4)');
+  });
+
+  it('renders invalid hint overlay with correct color', () => {
+    useConnectionPreviewStore.setState({
+      activeTarget: {
+        draggedTowerId: 'tower1',
+        targetTowerId: 'tower2',
+        targetBrickId: 'brick1',
+        type: 'argument',
+        distance: 5,
+        centroid: { x: 200, y: 250 },
+      },
+      isValid: false,
+    });
+
+    const { getByTestId } = render(<SnapHintOverlay />);
+    const overlay = getByTestId('snap-hint-overlay');
+
+    expect(overlay).toBeTruthy();
+    expect(overlay.style.transform).toContain('scale(1)');
+    expect(overlay.style.backgroundColor).toBe('rgba(239, 68, 68, 0.4)');
+  });
+});

modules/masonry/src/components/Workspace/SnapHintOverlay.tsx

@@ -0,0 +1,55 @@
+import { useConnectionPreviewStore } from '@/stores/connection-preview';
+import { useWorkspaceStore } from '@/stores/workspace';
+
+/**
+ * Renders a glowing dot (hint overlay) precisely at the socket or slot centroid when a user
+ * drags a brick close to a valid or invalid connection candidate.
+ *
+ * - If the connection is valid, it pulses slightly larger and matches the color of the brick being dragged.
+ * - If the connection is invalid, it shows a red glow to indicate a connection cannot be made here.
+ */
+export function SnapHintOverlay() {
+  const activeTarget = useConnectionPreviewStore((state) => state.activeTarget);
+  const isValid = useConnectionPreviewStore((state) => state.isValid);
+  const towers = useWorkspaceStore((state) => state.towers);
+
+  if (!activeTarget) return null;
+
+  const { centroid, draggedTowerId } = activeTarget;
+
+  // We look up the dragged brick to match its theme colors for a seamless visual experience.
+  const draggedTower = towers[draggedTowerId];
+  const modelColors = draggedTower?.root?.model?.colorsDefault;
+
+  // Generate dynamic styles based on validity and the source brick's color palette
+  const bgColor = isValid
+    ? modelColors
+      ? `${modelColors.background}80`
+      : 'rgba(34, 197, 94, 0.4)'
+    : 'rgba(239, 68, 68, 0.4)';
+  const borderColor = isValid
+    ? modelColors
+      ? modelColors.border
+      : 'rgba(20, 83, 45, 0.8)'
+    : 'rgba(153, 27, 27, 0.8)';
+  const glow = isValid
+    ? modelColors
+      ? `${modelColors.background}80`
+      : 'rgba(34, 197, 94, 0.5)'
+    : 'rgba(239, 68, 68, 0.5)';
+
+  return (
+    <div
+      data-testid="snap-hint-overlay"
+      className="pointer-events-none absolute z-40 h-3 w-3 rounded-full transition-all duration-100 ease-out"
+      style={{
+        left: centroid.x,
+        top: centroid.y,
+        transform: `translate(-50%, -50%) ${isValid ? 'scale(1.2)' : 'scale(1)'}`,
+        backgroundColor: bgColor,
+        border: `2px solid ${borderColor}`,
+        boxShadow: `0 0 10px 4px ${glow}`,
+      }}
+    />
+  );
+}

modules/masonry/src/components/Workspace/SnapPreviewView.test.tsx

@@ -0,0 +1,41 @@
+import { render } from '@testing-library/react';
+import { describe, it, expect, beforeEach } from 'vitest';
+import { SnapPreviewView } from './SnapPreviewView';
+import { useConnectionPreviewStore } from '@/stores/connection-preview';
+import { useWorkspaceStore } from '@/stores/workspace';
+
+describe('SnapPreviewView', () => {
+  beforeEach(() => {
+    useConnectionPreviewStore.setState({
+      activeTarget: null,
+      isValid: false,
+      snapPosition: null,
+      disconnectShadow: null,
+    });
+    useWorkspaceStore.setState({ towers: {} });
+  });
+
+  it('renders nothing when there is no snap position', () => {
+    const { container } = render(<SnapPreviewView />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('renders a dummy ghost block even if the dragged tower is not in the store', () => {
+    useConnectionPreviewStore.setState({
+      snapPosition: { x: 100, y: 100 },
+      activeTarget: {
+        draggedTowerId: 'missing-tower',
+        targetTowerId: 'tower2',
+        targetBrickId: 'brick1',
+        type: 'statement',
+        distance: 5,
+        centroid: { x: 100, y: 150 },
+      },
+      isValid: true,
+    });
+    const { getByTestId } = render(<SnapPreviewView />);
+    const container = getByTestId('snap-preview-view');
+    expect(container).toBeTruthy();
+    expect(container.style.transform).toBe('translate(100px, 100px)');
+  });
+});