@pascal-app/editor 1.0.3 → 1.0.5

package/src/components/ui/helpers/contextual-helper-panel.tsx

@@ -1,12 +1,14 @@
 import { Icon } from '@iconify/react'
 import type { ToolHint } from '@pascal-app/core'
-import { Fragment, useSyncExternalStore } from 'react'
+import { Fragment, useEffect, useId, useState, useSyncExternalStore } from 'react'
 import {
   CONTINUATION_PROFILES,
   type ContinuationContext,
 } from '../../../lib/continuation'
 import type { ContextualShortcutHint } from '../../../lib/contextual-help'
+import type { HudTitle } from '../../../lib/hud-title'
 import { hasActivePaintMaterial } from '../../../lib/material-paint'
+import { usePaintRegionMode } from '../../../lib/paint-region-mode'
 import { paintScopeLabel, type PaintScope } from '../../../lib/paint-scope'
 import { sfxEmitter } from '../../../lib/sfx-bus'
 import {
@@ -17,19 +19,23 @@ import {
 import { cn } from '../../../lib/utils'
 import useEditor, { type GridSnapStep } from '../../../store/use-editor'
 import useFenceCurveDraft from '../../../store/use-fence-curve-draft'
+import { IconRefGlyph } from '../icon-ref'
 import { ShortcutToken } from '../primitives/shortcut-token'
 import { Tooltip, TooltipContent, TooltipTrigger } from '../primitives/tooltip'
+import { useInRightStack } from '../right-stack'
 
 // One muted container holds every row — passive key hints and interactive chips
-// alike — so the HUD reads as a single panel, not a stack of floating pills. The
-// background is near-opaque (`bg-background/95`) with a single backdrop blur so
-// active rows stay readable over the 3D scene even while a modifier is held.
+// alike — so the HUD reads as a single panel, not a stack of floating pills. It
+// opens with the tool in hand (icon, name, arming key), then the gesture rows,
+// then — past a hairline — the mode chips (snapping, continuation, …) and Esc.
 // A 2-track grid: column 1 sizes to `max-content` (the widest key across ALL
 // rows), column 2 (`1fr`) is the label. Every row is a subgrid sharing those
 // tracks, so labels align even when keys differ in width (⌘ vs Shift) or wrap to
 // two lines. Near-opaque bg + single backdrop blur keeps active rows readable.
-const CONTAINER_CLASS =
-  'pointer-events-none fixed top-1/2 right-4 z-40 grid max-w-[260px] -translate-y-1/2 grid-cols-[max-content_1fr] gap-x-2.5 gap-y-1.5 rounded-lg border border-border bg-background/95 px-3 py-2.5 shadow-lg backdrop-blur-md'
+const CARD_CLASS =
+  'pointer-events-none grid w-[252px] grid-cols-[max-content_1fr] gap-x-2.5 gap-y-1.5 rounded-xl border border-border bg-background/95 p-3 shadow-lg backdrop-blur-md'
+// On its own (no shared right column) it floats centred on the right edge.
+const FLOATING_CLASS = 'fixed top-1/2 right-4 z-40 -translate-y-1/2'
 
 const TOKEN_CLASS = 'h-5 px-1.5 text-[10px]'
 
@@ -67,14 +73,16 @@ function ShortcutSequence({
                   <span className="text-[9px] text-muted-foreground/70">/</span>
                 ) : null}
                 <ShortcutToken
-                  className={cn(TOKEN_CLASS, active && 'border-white bg-white text-black shadow-sm')}
+                  className={cn(TOKEN_CLASS, active &&
+                      'border-foreground bg-foreground text-background shadow-sm dark:border-white dark:bg-white dark:text-black')}
                   value={alternative}
                 />
               </Fragment>
             ))
           ) : (
             <ShortcutToken
-              className={cn(TOKEN_CLASS, active && 'border-white bg-white text-black shadow-sm')}
+              className={cn(TOKEN_CLASS, active &&
+                      'border-foreground bg-foreground text-background shadow-sm dark:border-white dark:bg-white dark:text-black')}
               value={entry}
             />
           )}
@@ -260,47 +268,52 @@ function FenceContinuationChips() {
   const curveStarted = useFenceCurveDraft((s) => s.pointCount > 0)
 
   const isCurved = mode === 'curved'
+  const isFreehand = mode === 'freehand'
   const straightMode = isCurved ? 'continuous' : mode
-  const straightLabel = straightMode === 'single' ? 'Straight: Single' : 'Straight: Continuous'
-  const straightIcon = straightMode === 'single' ? 'lucide:minus' : 'lucide:waypoints'
-  const typeLabel = isCurved ? 'Type: Curved' : 'Type: Straight'
-  const typeIcon = isCurved ? 'lucide:spline' : 'lucide:minus'
+  const typeLabel = isFreehand ? 'Type: Freehand' : isCurved ? 'Type: Curved' : 'Type: Straight'
+  const typeIcon = isFreehand ? 'lucide:scribble' : isCurved ? 'lucide:spline' : 'lucide:minus'
+  const nextType =
+    mode === 'continuous' || mode === 'single'
+      ? 'curved'
+      : mode === 'curved'
+        ? 'freehand'
+        : 'continuous'
 
   return (
     <>
       <ChipRow
-        ariaLabel={`Fence type: ${isCurved ? 'Curved' : 'Straight'}`}
+        ariaLabel={`Fence type: ${typeLabel.replace('Type: ', '')}`}
         icon={typeIcon}
         label={typeLabel}
-        onClick={() => setContinuation('fence', isCurved ? 'continuous' : 'curved')}
+        onClick={() => setContinuation('fence', nextType)}
         shortcut="T"
-        tooltip="Fence type — click or press T to switch between straight and curved"
+        tooltip="Fence type — click or press T to switch between straight, curved and freehand"
       />
       <ChipRow
-        ariaLabel={`Fence continuation: ${straightLabel}`}
-        disabled={isCurved}
-        icon={straightIcon}
-        label={straightLabel}
+        ariaLabel={`Fence continuation: ${straightMode === 'single' ? 'Single' : 'Continuous'}`}
+        disabled={isCurved || isFreehand}
+        icon={straightMode === 'single' ? 'lucide:minus' : 'lucide:waypoints'}
+        label={straightMode === 'single' ? 'Straight: Single' : 'Straight: Continuous'}
         onClick={
-          isCurved
+          isCurved || isFreehand
             ? undefined
             : () => setContinuation('fence', straightMode === 'single' ? 'continuous' : 'single')
         }
         shortcut="C"
         tooltip={
-          isCurved
-            ? 'Straight continuation is unavailable while curved fence type is active'
+          isCurved || isFreehand
+            ? 'Straight continuation is unavailable for curved or freehand fences'
             : 'Straight fence continuation — click or press C to toggle'
         }
       />
       {/* Curved fences are committed by a closing gesture rather than per-click,
           so the finish keys aren't discoverable on their own — surface them, but
           only once the user has placed a point and a curve is actually in flight. */}
-      {isCurved && curveStarted ? (
+      {(isCurved || isFreehand) && curveStarted ? (
         <ChipRow
           icon="lucide:circle-check"
-          label="Finish curve (or double-click)"
-          shortcut="Enter"
+          label={isFreehand ? 'Drag to draw fence' : 'Finish curve (or double-click)'}
+          shortcut={isFreehand ? 'Release' : 'Enter'}
         />
       ) : null}
     </>
@@ -314,6 +327,15 @@ const PAINT_SCOPE_ICONS: Record<PaintScope, string> = {
   room: 'lucide:scan',
 }
 
+// Why the last paint click did nothing (a surface that has no finish of its
+// own to paint), in the same "!" row the region gestures use for a refusal.
+function PaintNotice() {
+  const notice = usePaintRegionMode((s) => s.notice)
+  // Leaving the painter forgets it.
+  useEffect(() => () => usePaintRegionMode.getState().setNotice(null), [])
+  return notice ? <HintRow hint={{ keys: ['!'], label: notice, active: true }} /> : null
+}
+
 // The painter's application-scope chip. Driven entirely by the hovered node's
 // derived `paintHover` (scopes + labels), so it works for any kind without a
 // per-target table.
@@ -324,18 +346,31 @@ function PaintScopeChip() {
   const paintScope = useEditor((s) => s.paintScope)
   const cyclePaintScope = useEditor((s) => s.cyclePaintScope)
   const activePaintMaterial = useEditor((s) => s.activePaintMaterial)
-  const paintEraser = useEditor((s) => s.paintEraser)
+  const paintMode = usePaintRegionMode((s) => s.mode)
+  const paintEraser = paintMode === 'erase'
+  const picking = paintMode === 'pick'
+  const verb = picking ? 'Pick' : paintEraser ? 'Erase' : 'Paint'
 
   // Nothing to paint with yet (no material picked, not erasing) → the first step
   // is choosing a material, so say that before anything about scope or hovering.
-  if (!(paintEraser || hasActivePaintMaterial(activePaintMaterial))) {
+  if (!(paintEraser || picking || hasActivePaintMaterial(activePaintMaterial))) {
     return <ChipRow icon="lucide:palette" label="Select a material to paint" />
   }
 
   // Not over anything paintable → guide the user to hover, still teaching Shift.
   if (!paintHover) {
     return (
-      <ChipRow icon="lucide:mouse-pointer-click" label="Hover a surface to paint" shortcut="Shift" />
+      <ChipRow
+        icon="lucide:mouse-pointer-click"
+        label={
+          picking
+            ? 'Hover a surface to pick its material'
+            : paintEraser
+              ? 'Hover a painted surface to erase'
+              : 'Hover a surface to paint'
+        }
+        shortcut={picking ? undefined : 'Shift'}
+      />
     )
   }
 
@@ -346,33 +381,85 @@ function PaintScopeChip() {
 
   // Paintable but with no scope choice (roof, a one-slot node, …) → a passive
   // row that still names the surface, so the user always sees what they'll paint.
-  if (scopes.length <= 1) {
+  if (scopes.length <= 1 || picking) {
     return (
       <ChipRow
-        icon={PAINT_SCOPE_ICONS[effective]}
-        label={`Paint: ${paintScopeLabel(effective, paintHover)}`}
+        icon={picking ? 'lucide:pipette' : PAINT_SCOPE_ICONS[effective]}
+        label={`${verb}: ${paintScopeLabel(picking ? 'single' : effective, paintHover)}`}
       />
     )
   }
 
   return (
     <ChipRow
-      ariaLabel={`Paint scope: ${paintScopeLabel(effective, paintHover)}`}
+      ariaLabel={`${verb} scope: ${paintScopeLabel(effective, paintHover)}`}
       icon={PAINT_SCOPE_ICONS[effective]}
-      label={`Paint: ${paintScopeLabel(effective, paintHover)}`}
+      label={`${verb}: ${paintScopeLabel(effective, paintHover)}`}
       onClick={() => cyclePaintScope()}
       shortcut="Shift"
-      tooltip="Paint scope — click or press Shift to cycle"
+      tooltip={`${verb} scope — click or press Shift to cycle`}
     />
   )
 }
 
+// The tool in hand: its icon, name and arming key, over a hairline.
+function HudHeader({ title }: { title: HudTitle }) {
+  return (
+    <div
+      className="col-span-2 mb-0.5 flex items-center gap-2.5 border-border border-b pb-2.5"
+      data-hud-title={title.label}
+    >
+      {title.icon ? (
+        <span className="flex size-7 shrink-0 items-center justify-center">
+          <IconRefGlyph icon={title.icon} size={26} />
+        </span>
+      ) : null}
+      <span className="min-w-0 flex-1 truncate font-medium text-[13px] text-foreground leading-tight">
+        {title.label}
+      </span>
+      {title.shortcut ? <ShortcutToken className={TOKEN_CLASS} value={title.shortcut} /> : null}
+    </div>
+  )
+}
+
+const isEscHint = (hint: ContextualShortcutHint) =>
+  hint.keys.length === 1 && hint.keys[0] === 'Esc'
+
+// A "!" row says why something won't happen here (a wall end a window can't wrap), not a key to
+// press, so it is never folded under More shortcuts.
+const isNoteHint = (hint: ContextualShortcutHint) => hint.keys.length === 1 && hint.keys[0] === '!'
+
+function HintRow({ hint }: { hint: ContextualShortcutHint }) {
+  return (
+    <div className={cn(ROW_CLASS, 'items-start')}>
+      <ShortcutSequence active={hint.active} keys={hint.keys} />
+      <div className="min-w-0">
+        <div
+          className={cn(
+            'text-xs leading-5',
+            hint.active ? 'font-medium text-foreground dark:text-white' : 'text-muted-foreground',
+          )}
+        >
+          {hint.label}
+        </div>
+        {hint.subtitle ? (
+          <div className="text-[10px] text-muted-foreground/70 leading-snug">{hint.subtitle}</div>
+        ) : null}
+      </div>
+    </div>
+  )
+}
+
+const hintKey = (hint: ContextualShortcutHint) => `${hint.keys.join('+')}:${hint.label}`
+
 export function ContextualHelperPanel({
   hints,
   chipHints = [],
   snapContext = null,
   showPaintScope = false,
   continuationContext = null,
+  title = null,
+  notice = null,
 }: {
   hints: ContextualShortcutHint[]
   // Kind-owned live mode chips (`ToolHint.chip`), rendered alongside the
@@ -383,54 +470,76 @@ export function ContextualHelperPanel({
   snapContext?: SnapContext | null
   showPaintScope?: boolean
   continuationContext?: ContinuationContext | null
+  // The tool or gesture in hand, shown as the panel's header.
+  title?: HudTitle | null
+  // A warning about what is in hand (a floor item in a door's way), in the "!" row.
+  notice?: string | null
 }) {
-  if (
-    hints.length === 0 &&
-    chipHints.length === 0 &&
-    !snapContext &&
-    !showPaintScope &&
-    !continuationContext
+  const inStack = useInRightStack()
+  const [showAllHints, setShowAllHints] = useState(false)
+  const hintsId = useId()
+  const modeChips = chipHints.filter((hint) => hint.chip)
+  const hasChips = !!snapContext || !!continuationContext || modeChips.length > 0 || showPaintScope
+  const fenceFeature = useEditor((state) =>
+    state.mode === 'build' && state.tool === 'fence' ? state.toolDefaults.fence?.featurePlacement : null,
   )
-    return null
+  if (fenceFeature === 'gate' || fenceFeature === 'opening') return (
+    <div className={cn(CARD_CLASS, !inStack && FLOATING_CLASS)} data-hud-card>
+      {title ? <HudHeader title={title} /> : null}
+      <ChipRow shortcut="Left click" label={fenceFeature === 'gate' ? 'Place gate on a fence' : 'Place passage on a fence'} />
+      <ChipRow shortcut="Esc" label="Cancel placement" />
+    </div>
+  )
+  if (hints.length === 0 && !hasChips && !notice) return null
+
+  const actionHints = hints.filter((hint) => !isEscHint(hint))
+  const escHints = hints.filter(isEscHint)
+  const collapsedHints = actionHints.filter(
+    (hint, index) => index === 0 || hint.active || isNoteHint(hint),
+  )
+  const visibleHints = showAllHints ? actionHints : collapsedHints
 
   return (
-    <div className={CONTAINER_CLASS}>
+    <div
+      className={cn(CARD_CLASS, !inStack && FLOATING_CLASS)}
+      data-hud-card
+    >
+      {title ? <HudHeader title={title} /> : null}
+      <div id={hintsId} className="col-span-2 grid grid-cols-subgrid gap-y-1.5">
+        {visibleHints.map((hint) => (
+          <HintRow hint={hint} key={hintKey(hint)} />
+        ))}
+      </div>
+      {collapsedHints.length < actionHints.length ? (
+        <button
+          aria-controls={hintsId}
+          aria-expanded={showAllHints}
+          className="pointer-events-auto col-span-2 min-h-7 rounded-md px-1 text-left text-[11px] text-muted-foreground hover:bg-muted/60 hover:text-foreground focus-visible:outline-2 focus-visible:outline-ring"
+          onClick={() => setShowAllHints((value) => !value)}
+          type="button"
+        >
+          {showAllHints ? 'Fewer shortcuts' : 'More shortcuts'}
+        </button>
+      ) : null}
+      {notice ? <HintRow hint={{ keys: ['!'], label: notice, active: true }} /> : null}
+      {actionHints.length > 0 && (hasChips || escHints.length > 0) ? (
+        <div className="col-span-2 my-0.5 h-px bg-border" />
+      ) : null}
       {snapContext ? <SnappingChips context={snapContext} /> : null}
       {continuationContext === 'fence' ? <FenceContinuationChips /> : null}
       {continuationContext && continuationContext !== 'fence' ? (
         <ContinuationChip context={continuationContext} />
       ) : null}
-      {chipHints.map((hint) =>
-        hint.chip ? (
-          <ToolHintChipRow
-            hint={hint as ToolHint & { chip: NonNullable<ToolHint['chip']> }}
-            key={`${hint.key}:${hint.label}`}
-          />
-        ) : null,
-      )}
+      {modeChips.map((hint) => (
+        <ToolHintChipRow
+          hint={hint as ToolHint & { chip: NonNullable<ToolHint['chip']> }}
+          key={`${hint.key}:${hint.label}`}
+        />
+      ))}
+      {showPaintScope ? <PaintNotice /> : null}
       {showPaintScope ? <PaintScopeChip /> : null}
-      {hints.map((hint) => (
-        <div
-          className={cn(ROW_CLASS, 'items-start')}
-          key={`${hint.keys.join('+')}:${hint.label}`}
-        >
-          <ShortcutSequence active={hint.active} keys={hint.keys} />
-          <div className="min-w-0">
-            <div
-              className={cn(
-                'text-xs leading-5',
-                hint.active ? 'font-medium text-white' : 'text-muted-foreground',
-              )}
-            >
-              {hint.label}
-            </div>
-            {hint.subtitle ? (
-              <div className="text-[10px] text-muted-foreground/70 leading-snug">
-                {hint.subtitle}
-              </div>
-            ) : null}
-          </div>
-        </div>
+      {escHints.map((hint) => (
+        <HintRow hint={hint} key={hintKey(hint)} />
       ))}
     </div>
   )

package/src/components/ui/helpers/helper-manager.test.tsx

@@ -0,0 +1,121 @@
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { SELECT_HUD_TITLE, toolHudTitle } from '../../../lib/hud-title'
+import { snapContextOf } from '../../../lib/snapping-mode'
+import { cornerHintRows } from '../../../store/use-corner-snap-hint'
+import { TooltipProvider } from '../primitives/tooltip'
+import { ContextualHelperPanel } from './contextual-helper-panel'
+import { ROOM_DIVIDE_HINTS } from './helper-manager'
+
+describe('Divide HUD', () => {
+  test('uses the wall draft snapping context', () => {
+    expect(
+      snapContextOf({
+        scope: { kind: 'room-divide' },
+        mode: 'select',
+        tool: null,
+        profileOf: () => undefined,
+      }),
+    ).toBe('wall')
+  })
+
+  test('shows snapping controls and the primary gesture with expandable secondary shortcuts', () => {
+    // Server rendering reads each store's initial state: the wall context starts
+    // on Grid with a 0.5 m step.
+    const html = renderToStaticMarkup(
+      <TooltipProvider>
+        <ContextualHelperPanel hints={ROOM_DIVIDE_HINTS} snapContext="wall" />
+      </TooltipProvider>,
+    )
+    expect(html).toContain('Snapping: Grid')
+    expect(html).toContain('Grid: 0.50 m')
+    for (const label of ['Add point', 'More shortcuts', 'Cancel'])
+      expect(html).toContain(label)
+    expect(html).toContain('aria-expanded="false"')
+    for (const label of ['Remove last point', 'Finish at the edge'])
+      expect(html).not.toContain(label)
+    expect(ROOM_DIVIDE_HINTS.map((hint) => hint.keys)).toEqual([
+      ['Left click'],
+      ['Backspace'],
+      ['Enter'],
+      ['Esc'],
+    ])
+  })
+
+  test('keeps active secondary gestures visible while shortcuts are collapsed', () => {
+    const html = renderToStaticMarkup(
+      <TooltipProvider>
+        <ContextualHelperPanel
+          hints={ROOM_DIVIDE_HINTS.map((hint) => ({
+            ...hint,
+            active: hint.keys.includes('Enter'),
+          }))}
+          snapContext="wall"
+        />
+      </TooltipProvider>,
+    )
+    for (const label of ['Add point', 'Finish at the edge', 'Cancel'])
+      expect(html).toContain(label)
+    expect(html).not.toContain('Remove last point')
+    expect(html).toContain('aria-expanded="false"')
+  })
+
+  test('keeps a note row visible while shortcuts are collapsed', () => {
+    const html = renderToStaticMarkup(
+      <TooltipProvider>
+        <ContextualHelperPanel
+          hints={[
+            { keys: ['Left click'], label: 'Place' },
+            ...cornerHintRows('free_end'),
+            { keys: ['R', 'T'], label: 'Rotate' },
+            { keys: ['Esc'], label: 'Cancel' },
+          ]}
+        />
+      </TooltipProvider>,
+    )
+    for (const label of ['Place', 'No wall meets here', 'More shortcuts', 'Cancel'])
+      expect(html).toContain(label)
+    expect(html).not.toContain('Rotate')
+  })
+
+  test('offers More shortcuts only when collapsing hides a row', () => {
+    const html = renderToStaticMarkup(
+      <TooltipProvider>
+        <ContextualHelperPanel
+          hints={[{ keys: ['Left click'], label: 'Place' }, ...cornerHintRows('free_end')]}
+        />
+      </TooltipProvider>,
+    )
+    expect(html).toContain('No wall meets here')
+    expect(html).not.toContain('More shortcuts')
+  })
+})
+
+describe('HUD header', () => {
+  test('names the tool in hand with its icon and key, above the gesture rows', () => {
+    const html = renderToStaticMarkup(
+      <TooltipProvider>
+        <ContextualHelperPanel
+          hints={[
+            { keys: ['Left click'], label: 'Set one corner, then the opposite' },
+            { keys: ['Esc'], label: 'Cancel' },
+          ]}
+          snapContext="wall"
+          title={toolHudTitle('wall', 'rectangle')}
+        />
+      </TooltipProvider>,
+    )
+    expect(html).toContain('data-hud-title="Rectangle room"')
+    expect(html).toContain('src="/icons/room.webp"')
+    // Header, then the gesture, then the mode chips, with Esc last.
+    const order = ['Rectangle room', 'Set one corner', 'Snapping: Grid', 'Cancel'].map((text) =>
+      html.indexOf(text),
+    )
+    expect(order.every((at) => at >= 0)).toBe(true)
+    expect([...order].sort((a, b) => a - b)).toEqual(order)
+  })
+
+  test('select mode is titled Select with its V key', () => {
+    expect(SELECT_HUD_TITLE).toMatchObject({ label: 'Select', shortcut: 'V' })
+  })
+})