@lovett/ui 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovett/ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "description": "Design system primitives, tokens, layouts, and patterns for the Lovett portfolio.",

package/src/__tests__/display-store.test.tsx

@@ -10,11 +10,18 @@
  *   2. PERSISTENCE IS PER SCOPE and VALIDATED. A key from another scope never
  *      leaks; a hand-edited value that is the wrong type or outside the
  *      allow-list falls back to the default instead of reaching a component.
+ *
+ * And one contract that is not an inversion but a PIN. `prefix` moves the key
+ * for a host that is not this workspace, and the default has to stay
+ * byte-identical: these keys hold operator preferences already on disk, so a
+ * changed default would not migrate them, it would lose them. The default is
+ * asserted as a literal, and asserted again through a value written by hand at
+ * the key an older build wrote.
  */
 import { describe, expect, it, beforeEach } from 'vitest'
 import { render, screen } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
-import { createDisplayStore } from '../display-store'
+import { createDisplayStore, type DisplayStore } from '../display-store'
 
 type Settings = {
   readonly grouping: 'column' | 'assignee'
@@ -40,28 +47,52 @@ const store = createDisplayStore<Settings>(
   },
 )
 
-function Panel({ name }: { name: string }) {
-  const { settings, set, reset, isDefault } = store.useDisplay()
-  return (
-    <div>
-      <span data-testid={`${name}-grouping`}>{settings.grouping}</span>
-      <span data-testid={`${name}-empty`}>{String(settings.showEmpty)}</span>
-      <span data-testid={`${name}-default`}>{String(isDefault)}</span>
-      <button type="button" onClick={() => set('grouping', 'assignee')}>
-        {`${name}: group by assignee`}
-      </button>
-      <button type="button" onClick={() => set('showEmpty', false)}>
-        {`${name}: hide empty`}
-      </button>
-      <span data-testid={`${name}-size`}>{String(settings.panelSize)}</span>
-      <button type="button" onClick={() => set('panelSize', 820)}>
-        {`${name}: widen`}
-      </button>
-      <button type="button" onClick={reset}>{`${name}: reset`}</button>
-    </div>
-  )
+/**
+ * The same store under a different PREFIX, and identical in every other way —
+ * same name, same defaults, same allow-list. The pair is what proves the
+ * option moves the key and touches nothing else: if the prefix were dropped
+ * these two would be one store sharing one key.
+ */
+const prefixedStore = createDisplayStore<Settings>(
+  'test',
+  DEFAULTS,
+  { grouping: ['column', 'assignee'] },
+  undefined,
+  { prefix: 'lightwork' },
+)
+
+/**
+ * A panel per store. `useDisplay` reaches the nearest provider, so a second
+ * store needs a component that calls the second store's hook — the panel is
+ * built from the store rather than closing over one.
+ */
+function panelFor(target: DisplayStore<Settings>) {
+  return function Panel({ name }: { name: string }) {
+    const { settings, set, reset, isDefault } = target.useDisplay()
+    return (
+      <div>
+        <span data-testid={`${name}-grouping`}>{settings.grouping}</span>
+        <span data-testid={`${name}-empty`}>{String(settings.showEmpty)}</span>
+        <span data-testid={`${name}-default`}>{String(isDefault)}</span>
+        <button type="button" onClick={() => set('grouping', 'assignee')}>
+          {`${name}: group by assignee`}
+        </button>
+        <button type="button" onClick={() => set('showEmpty', false)}>
+          {`${name}: hide empty`}
+        </button>
+        <span data-testid={`${name}-size`}>{String(settings.panelSize)}</span>
+        <button type="button" onClick={() => set('panelSize', 820)}>
+          {`${name}: widen`}
+        </button>
+        <button type="button" onClick={reset}>{`${name}: reset`}</button>
+      </div>
+    )
+  }
 }
 
+const Panel = panelFor(store)
+const PrefixedPanel = panelFor(prefixedStore)
+
 describe('createDisplayStore', () => {
   beforeEach(() => window.localStorage.clear())
 
@@ -69,6 +100,74 @@ describe('createDisplayStore', () => {
     expect(store.storageKey('brn_1')).toBe('workspace:test:brn_1:display')
   })
 
+  it('refuses an empty prefix rather than silently sharing the default namespace', () => {
+    // Both quiet alternatives are worse than a throw: defaulting hands a caller
+    // who asked for isolation the shared namespace, and accepting produces
+    // `:name:scope:display`, which collides with every other empty-prefix
+    // caller — the cross-product the option exists to prevent.
+    expect(() => createDisplayStore('board', { a: 1 }, undefined, undefined, { prefix: '' })).toThrow(
+      /prefix.*cannot be empty/i,
+    )
+    // And the default path is untouched by the guard.
+    expect(createDisplayStore('board', { a: 1 }).storageKey('ws_1')).toBe('workspace:board:ws_1:display')
+  })
+
+  it('reads a key written before the prefix option existed', () => {
+    // The key is spelled out rather than taken from `storageKey`, because what
+    // is under test is that the two still agree. A store built without the
+    // option has to find exactly what the build before it left behind.
+    window.localStorage.setItem(
+      'workspace:test:brn_old:display',
+      JSON.stringify({ grouping: 'assignee', showEmpty: false, panelSize: 700 }),
+    )
+    render(
+      <store.Provider scope="brn_old">
+        <Panel name="old" />
+      </store.Provider>,
+    )
+    expect(screen.getByTestId('old-grouping')).toHaveTextContent('assignee')
+    expect(screen.getByTestId('old-empty')).toHaveTextContent('false')
+    expect(screen.getByTestId('old-size')).toHaveTextContent('700')
+  })
+
+  it('takes a prefix, and the prefix is the only segment it changes', () => {
+    expect(prefixedStore.storageKey('brn_1')).toBe('lightwork:test:brn_1:display')
+  })
+
+  it('a prefixed store writes its own key and never the unprefixed one', async () => {
+    const user = userEvent.setup()
+    render(
+      <prefixedStore.Provider scope="brn_p">
+        <PrefixedPanel name="p" />
+      </prefixedStore.Provider>,
+    )
+    await user.click(screen.getByRole('button', { name: 'p: group by assignee' }))
+    expect(window.localStorage.getItem('lightwork:test:brn_p:display')).toContain(
+      'assignee',
+    )
+    // The point of the option: another product on the same origin, using the
+    // same primitive under the same name, is not writing over this workspace.
+    expect(window.localStorage.getItem('workspace:test:brn_p:display')).toBeNull()
+  })
+
+  it('two prefixes over one name and one scope do not see each other', async () => {
+    const user = userEvent.setup()
+    const { unmount } = render(
+      <store.Provider scope="brn_shared">
+        <Panel name="host" />
+      </store.Provider>,
+    )
+    await user.click(screen.getByRole('button', { name: 'host: group by assignee' }))
+    unmount()
+
+    render(
+      <prefixedStore.Provider scope="brn_shared">
+        <PrefixedPanel name="guest" />
+      </prefixedStore.Provider>,
+    )
+    expect(screen.getByTestId('guest-grouping')).toHaveTextContent('column')
+  })
+
   it('persists a change and reads it back on the next mount', async () => {
     const user = userEvent.setup()
     const { unmount } = render(

package/src/__tests__/sortable.test.tsx

@@ -0,0 +1,394 @@
+/**
+ * `MultiSortableList` — the two drag defects, pinned.
+ *
+ * Both were reported from a browser and neither was visible to any gate, which
+ * is the reason this file exists rather than a note in a README:
+ *
+ *   1. dropping a card in another lane flashed it back to its origin for a
+ *      frame — "like an invisible or ghost presence" — because the drop
+ *      cleared the preview and rendered from `containers`, which the consumer
+ *      had not patched yet.
+ *   2. the drop target was resolved from the CARD's corners, so a tall card
+ *      had to be dragged bodily into a lane before that lane would catch it.
+ *      The pointer was not consulted.
+ *
+ * The collision suite is a pure-function suite: a `CollisionDetection` takes
+ * rects and coordinates and returns collisions, so the geometry that jsdom
+ * cannot produce can simply be handed to it. It asserts the new answer and,
+ * on the identical geometry, the one `closestCorners` gives — so the defect is
+ * pinned next to the fix, and a revert to either fails here.
+ *
+ * The preview suite drives a real keyboard drag. That works — barely, and only
+ * with the geometry mock — because dnd-kit measures the DragOverlay's single
+ * child (`getMeasurableNode`), which the harness gives a `data-rect` like every
+ * other node. A pointer drag is still not reproducible here: the PointerSensor
+ * needs layout that jsdom does not have. The keyboard path exercises the same
+ * `handleDragOver` / `handleDragEnd` the pointer path does, which is the code
+ * under test, and it has the side benefit of proving keyboard dragging still
+ * works at all after the collision change.
+ */
+
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest'
+import { act, render, screen } from '@testing-library/react'
+import { closestCorners, type CollisionDetection } from '@dnd-kit/core'
+import {
+  MultiSortableList,
+  PREVIEW_SETTLE_MS,
+  SortableDropZone,
+  SortableItem,
+  pointerFirstCollision,
+} from '../sortable'
+import type { MultiSortableMove, SortableContainers } from '../sortable'
+import { mockGeometry, setViewport } from './helpers/geometry'
+
+/* ── collision detection ─────────────────────────────────────────────────── */
+
+type CollisionArgs = Parameters<CollisionDetection>[0]
+type ClientRect = CollisionArgs['collisionRect']
+type Droppable = CollisionArgs['droppableContainers'][number]
+
+const rect = (left: number, top: number, width: number, height: number): ClientRect => ({
+  left,
+  top,
+  width,
+  height,
+  right: left + width,
+  bottom: top + height,
+})
+
+const droppable = (id: string, r: ClientRect): Droppable => ({
+  id,
+  key: id,
+  disabled: false,
+  data: { current: undefined },
+  node: { current: null },
+  rect: { current: r },
+})
+
+/**
+ * A two-lane board. `build-1` is 600px tall — the variable-height card the
+ * whole collision argument is about.
+ */
+const LANE_PLANNING = rect(0, 0, 300, 800)
+const LANE_BUILD = rect(320, 0, 300, 800)
+const CARD_PLAN_1 = rect(0, 0, 300, 120)
+const CARD_BUILD_1 = rect(320, 100, 300, 600)
+
+const LANE_OF: Record<string, string> = {
+  planning: 'planning',
+  build: 'build',
+  'plan-1': 'planning',
+  'build-1': 'build',
+}
+
+/**
+ * Dragged left by 100px: 80px of the card has crossed into Planning and 200px
+ * is still over Build. Under any card-measuring strategy Build still wins,
+ * which is the defect — the user is pointing at Planning.
+ */
+const DRAGGED = rect(220, 100, 300, 600)
+
+function args(pointerCoordinates: { x: number; y: number } | null): CollisionArgs {
+  const rects: Array<[string, ClientRect]> = [
+    ['planning', LANE_PLANNING],
+    ['build', LANE_BUILD],
+    ['plan-1', CARD_PLAN_1],
+    ['build-1', CARD_BUILD_1],
+  ]
+  return {
+    active: {
+      id: 'build-1',
+      data: { current: undefined },
+      rect: { current: { initial: CARD_BUILD_1, translated: DRAGGED } },
+    },
+    collisionRect: DRAGGED,
+    droppableRects: new Map(rects),
+    droppableContainers: rects.map(([id, r]) => droppable(id, r)),
+    pointerCoordinates,
+  }
+}
+
+/** What `MultiSortableList` does with the winner: resolve it to a lane. */
+function laneFor(strategy: CollisionDetection, at: { x: number; y: number } | null): string {
+  const winner = strategy(args(at))[0]
+  return winner ? (LANE_OF[String(winner.id)] ?? 'none') : 'none'
+}
+
+describe('pointerFirstCollision', () => {
+  it('catches the card in the lane the POINTER is over', () => {
+    // Cursor at x=260: inside Planning, and below plan-1, so the lane itself.
+    expect(laneFor(pointerFirstCollision, { x: 260, y: 400 })).toBe('planning')
+  })
+
+  it('is a real change: closestCorners answers the source lane on the same geometry', () => {
+    // The defect, kept next to the fix. If this ever agrees with the case
+    // above, the geometry has stopped exercising anything.
+    expect(laneFor(closestCorners, { x: 260, y: 400 })).toBe('build')
+  })
+
+  it('resolves to a card, not the lane, when the pointer is over one', () => {
+    // The card is what carries the destination INDEX, so a pointer over a card
+    // has to win over the lane containing it or every cross-lane drop appends.
+    const winner = pointerFirstCollision(args({ x: 150, y: 60 }))[0]
+    expect(winner?.id).toBe('plan-1')
+  })
+
+  it('falls back to closestCorners when there is no pointer — the keyboard drag', () => {
+    // dnd-kit derives pointerCoordinates from the activator event's clientX/Y,
+    // and a KeyboardEvent has neither. A pointer-only strategy returns nothing
+    // here, `over` stays null for the whole drag, and cross-lane keyboard
+    // movement dies silently.
+    const byFallback = pointerFirstCollision(args(null))
+    expect(byFallback.length).toBeGreaterThan(0)
+    expect(byFallback.map((c) => c.id)).toEqual(closestCorners(args(null)).map((c) => c.id))
+  })
+
+  it('falls back when the pointer is over no droppable — the board margins', () => {
+    // x=900 is past the right edge of every lane. Dropping there still has to
+    // resolve somewhere rather than reading as a drop outside the board.
+    expect(laneFor(pointerFirstCollision, { x: 900, y: 400 })).toBe('build')
+  })
+})
+
+/* ── the preview, across a drop ──────────────────────────────────────────── */
+
+const ORDER = ['planning', 'build'] as const
+
+const RECTS: Record<string, string> = {
+  planning: '0,0,300,800',
+  build: '320,0,300,800',
+  'plan-1': '0,0,300,120',
+  'build-1': '320,0,300,600',
+}
+
+const START: SortableContainers = { planning: ['plan-1'], build: ['build-1'] }
+
+/**
+ * dnd-kit's KeyboardSensor adds its document keydown listener inside a
+ * `setTimeout`, so every key after the activating one has to wait a macrotask
+ * or it lands before the sensor is listening.
+ */
+const flush = async () => {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0))
+  })
+}
+
+const press = async (el: HTMLElement, code: string, key: string) => {
+  await act(async () => {
+    el.dispatchEvent(new KeyboardEvent('keydown', { key, code, bubbles: true }))
+  })
+}
+
+/**
+ * `containers` is a PROP, so each test decides for itself whether, when, and
+ * with what the consumer answers a move — which is the variable under test.
+ * A `rerender` is the consumer patching its cache.
+ */
+function Harness({
+  containers,
+  onMove,
+  log,
+}: {
+  containers: SortableContainers
+  onMove: (move: MultiSortableMove, next: SortableContainers) => void
+  log: SortableContainers[]
+}) {
+  return (
+    <MultiSortableList
+      containers={containers}
+      containerOrder={ORDER}
+      onMove={onMove}
+      renderOverlay={(id) => <div data-rect={RECTS[id]}>overlay {id}</div>}
+    >
+      {(arrangement) => {
+        log.push(arrangement)
+        return (
+          <div>
+            {ORDER.map((laneId) => (
+              <SortableDropZone key={laneId} id={laneId} items={arrangement[laneId] ?? []}>
+                {({ setNodeRef }) => (
+                  <div ref={setNodeRef} data-testid={`lane-${laneId}`} data-rect={RECTS[laneId]}>
+                    {(arrangement[laneId] ?? []).map((itemId) => (
+                      <SortableItem key={itemId} id={itemId}>
+                        {({ setNodeRef: setItemRef, setActivatorNodeRef, dragListeners }) => (
+                          <div ref={setItemRef} data-rect={RECTS[itemId]}>
+                            <button type="button" ref={setActivatorNodeRef} {...dragListeners}>
+                              drag {itemId}
+                            </button>
+                          </div>
+                        )}
+                      </SortableItem>
+                    ))}
+                  </div>
+                )}
+              </SortableDropZone>
+            ))}
+          </div>
+        )
+      }}
+    </MultiSortableList>
+  )
+}
+
+/** What the consumer's cache holds once it has accepted the move. */
+const MOVED: SortableContainers = { planning: ['plan-1', 'build-1'], build: [] }
+
+/** Pick up `build-1`, move it left into Planning, and stop before the drop. */
+async function dragBuildCardIntoPlanning(): Promise<void> {
+  const handle = screen.getByRole('button', { name: /drag build-1/i })
+  handle.focus()
+  await press(handle, 'Space', ' ')
+  await flush()
+  // The card is re-rendered into the other lane as the preview updates, so the
+  // original handle node is detached. Subsequent keys go to the document, which
+  // is where the sensor listens anyway.
+  await press(document.body, 'ArrowLeft', 'ArrowLeft')
+  await flush()
+}
+
+const lanes = () => ({
+  planning: screen.getByTestId('lane-planning').textContent,
+  build: screen.getByTestId('lane-build').textContent,
+})
+
+describe('MultiSortableList — the preview across a drop', () => {
+  let restore: () => void
+
+  beforeEach(() => {
+    restore = mockGeometry()
+    setViewport(1200, 900)
+  })
+  afterEach(() => restore())
+
+  it('never renders the pre-drag arrangement between the drop and the patch', async () => {
+    // The ghost, exactly: every render taken while `containers` is still stale
+    // — which is every render between the drop and a mutation's `onMutate` —
+    // used to put the card back in Build. This walks that window and asserts
+    // Build is empty in all of it.
+    const onMove = vi.fn()
+    const log: SortableContainers[] = []
+    const { rerender } = render(<Harness containers={START} onMove={onMove} log={log} />)
+
+    await dragBuildCardIntoPlanning()
+
+    const atDrop = log.length
+    await press(document.body, 'Space', ' ')
+
+    expect(onMove).toHaveBeenCalledWith(
+      { itemId: 'build-1', fromContainerId: 'build', toContainerId: 'planning', toIndex: 1 },
+      MOVED,
+    )
+    const afterDrop = log.slice(atDrop)
+    // Non-empty, or the loop below asserts nothing: the drop DOES render.
+    expect(afterDrop.length).toBeGreaterThan(0)
+    for (const arrangement of afterDrop) {
+      expect(arrangement['build']).toEqual([])
+    }
+    expect(lanes().build).toBe('')
+
+    // The consumer's patch finally lands. Nothing moves.
+    rerender(<Harness containers={MOVED} onMove={onMove} log={log} />)
+    expect(lanes().planning).toContain('drag build-1')
+    expect(lanes().build).toBe('')
+  })
+
+  it('yields to `containers` the moment the consumer disagrees', async () => {
+    // A rejected move, or an optimistic write rolled back. The preview is a
+    // bridge, not a claim that outranks the consumer: a new `containers`
+    // supersedes it at once, well inside the settle deadline.
+    const onMove = vi.fn()
+    const { rerender } = render(<Harness containers={START} onMove={onMove} log={[]} />)
+
+    await dragBuildCardIntoPlanning()
+    await press(document.body, 'Space', ' ')
+    expect(lanes().build).toBe('')
+
+    rerender(
+      <Harness
+        containers={{ planning: ['plan-1'], build: ['build-1'] }}
+        onMove={onMove}
+        log={[]}
+      />,
+    )
+    expect(lanes().build).toContain('drag build-1')
+    expect(lanes().planning).not.toContain('drag build-1')
+  })
+
+  it('does not resurrect the preview when `containers` returns to its old identity', async () => {
+    // The preview is held against a `containers` IDENTITY, and identities come
+    // back: a rolled-back optimistic write restores the previous object, not a
+    // copy of it. A preview still in state at that point would stop looking
+    // superseded and draw the move a second time, after the consumer undid it.
+    const onMove = vi.fn()
+    const { rerender } = render(<Harness containers={START} onMove={onMove} log={[]} />)
+
+    await dragBuildCardIntoPlanning()
+    await press(document.body, 'Space', ' ')
+
+    // Optimistic patch, then the write fails and the exact prior object is put
+    // back — `START` itself, which is the value the preview was held against.
+    rerender(<Harness containers={MOVED} onMove={onMove} log={[]} />)
+    rerender(<Harness containers={START} onMove={onMove} log={[]} />)
+
+    expect(lanes().build).toContain('drag build-1')
+    expect(lanes().planning).not.toContain('drag build-1')
+  })
+
+  it('does not yank a still-held card back when the next drag starts', async () => {
+    // The fast user: drop one card, grab another before the first patch lands.
+    // A drag that rebased on `containers` would put the first card back in
+    // Build on pickup — the same ghost, one drag later.
+    const onMove = vi.fn()
+    render(<Harness containers={START} onMove={onMove} log={[]} />)
+
+    await dragBuildCardIntoPlanning()
+    await press(document.body, 'Space', ' ')
+    expect(lanes().planning).toContain('drag build-1')
+
+    const other = screen.getByRole('button', { name: /drag plan-1/i })
+    other.focus()
+    await press(other, 'Space', ' ')
+    await flush()
+    expect(lanes().planning).toContain('drag build-1')
+    expect(lanes().build).toBe('')
+
+    // And cancelling the second drag returns to the held arrangement, not to
+    // the `containers` the consumer still has not updated.
+    await press(document.body, 'Escape', 'Escape')
+    expect(lanes().planning).toContain('drag build-1')
+    expect(lanes().build).toBe('')
+  })
+
+  it('expires the preview when the consumer never patches at all', async () => {
+    // The cost of holding. A consumer that ignores `onMove` produces no new
+    // `containers`, so nothing supersedes the preview and the board would
+    // otherwise assert a move that never happened, indefinitely and silently.
+    const onMove = vi.fn()
+    render(<Harness containers={START} onMove={onMove} log={[]} />)
+
+    await dragBuildCardIntoPlanning()
+    await press(document.body, 'Space', ' ')
+    expect(onMove).toHaveBeenCalledTimes(1)
+    expect(lanes().planning).toContain('drag build-1')
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, PREVIEW_SETTLE_MS + 50))
+    })
+    expect(lanes().build).toContain('drag build-1')
+    expect(lanes().planning).not.toContain('drag build-1')
+  })
+
+  it('returns the card on cancel, without a move', async () => {
+    const onMove = vi.fn()
+    render(<Harness containers={START} onMove={onMove} log={[]} />)
+
+    await dragBuildCardIntoPlanning()
+    expect(lanes().planning).toContain('drag build-1')
+
+    await press(document.body, 'Escape', 'Escape')
+    expect(onMove).not.toHaveBeenCalled()
+    expect(lanes().build).toContain('drag build-1')
+    expect(lanes().planning).not.toContain('drag build-1')
+  })
+})