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

package/src/components/common/lists/reorderable/ReorderableSections.tsx

@@ -0,0 +1,344 @@
+import type { DragEvent, ReactNode } from 'react'
+import { styled } from 'styled-components'
+import { Text } from '../../typography/Text.js'
+import { ReorderableListRow } from './ReorderableListRow.js'
+import { insertIndexFromRowRect } from './reorderableUtils.js'
+import type {
+  ReorderableItem,
+  ReorderableItemRenderContext,
+  ReorderableMove,
+  ReorderableSection,
+} from './types.js'
+import { useReorderableDragState } from './useReorderableDragState.js'
+
+//#region styled-components
+
+export type ReorderableSectionsDensity = 'default' | 'compact'
+
+const StyledRoot = styled.div<{ $density: ReorderableSectionsDensity }>`
+  display: flex;
+  flex-direction: column;
+  gap: ${({ $density }) => ($density === 'compact' ? '6px' : '8px')};
+  min-width: 0;
+`
+
+const StyledSection = styled.section<{ $density: ReorderableSectionsDensity }>`
+  display: flex;
+  flex-direction: column;
+  gap: ${({ $density }) => ($density === 'compact' ? '0' : '2px')};
+  min-width: 0;
+`
+
+const StyledSectionHeader = styled.div`
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+  padding: 4px 6px;
+`
+
+const StyledSectionLabel = styled(Text)`
+  flex: 1;
+  min-width: 0;
+  color: var(--platform-colors-text-secondary);
+  font-size: var(--platform-typography-font-size-xs);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+`
+
+const StyledSectionActions = styled.div`
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  gap: 4px;
+`
+
+const StyledList = styled.ul<{ $density: ReorderableSectionsDensity }>`
+  display: flex;
+  flex-direction: column;
+  gap: ${({ $density }) => ($density === 'compact' ? '2px' : '4px')};
+  margin: 0;
+  padding: ${({ $density }) =>
+    $density === 'compact' ? '0 0 0 4px' : '0 0 0 8px'};
+  list-style: none;
+`
+
+const StyledEmpty = styled.li<{
+  $active?: boolean
+  $density: ReorderableSectionsDensity
+}>`
+  padding: ${({ $density }) => ($density === 'compact' ? '7px 9px' : '12px 14px')};
+  border: 1px dashed
+    ${({ $active }) =>
+      $active
+        ? 'var(--platform-colors-border-strong, var(--platform-colors-border))'
+        : 'var(--platform-colors-border)'};
+  border-radius: var(--platform-radius-sm);
+  color: var(--platform-colors-text-secondary);
+  font-size: ${({ $density }) =>
+    $density === 'compact'
+      ? 'var(--platform-typography-font-size-xs)'
+      : 'var(--platform-typography-font-size-sm)'};
+  list-style: none;
+`
+
+const StyledItemButton = styled.button<{ $selected?: boolean }>`
+  display: block;
+  width: 100%;
+  padding: 6px 8px;
+  border: 1px solid
+    ${({ $selected }) =>
+      $selected
+        ? 'var(--platform-colors-border-strong, var(--platform-colors-border))'
+        : 'transparent'};
+  border-radius: var(--platform-radius-sm);
+  background: ${({ $selected }) =>
+    $selected
+      ? 'var(--platform-colors-surface-hover, var(--platform-colors-surface))'
+      : 'transparent'};
+  color: var(--platform-colors-text);
+  font-size: var(--platform-typography-font-size-sm);
+  text-align: left;
+  cursor: pointer;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+
+  &:hover:not(:disabled) {
+    background: var(
+      --platform-colors-surface-hover,
+      var(--platform-colors-surface)
+    );
+  }
+
+  &:disabled {
+    cursor: default;
+    opacity: 0.55;
+  }
+`
+
+//#endregion
+
+export interface ReorderableSectionsProps<TId extends string = string> {
+  sections: ReadonlyArray<ReorderableSection<TId>>
+  selectedId?: TId
+  readonly?: boolean
+  density?: ReorderableSectionsDensity
+  'aria-label'?: string
+  onSelect?: (id: TId) => void
+  onMove?: (move: ReorderableMove<TId>) => void
+  renderItem?: (ctx: ReorderableItemRenderContext<TId>) => ReactNode
+  renderSectionHeader?: (ctx: { section: ReorderableSection<TId> }) => ReactNode
+  renderSectionFooter?: (ctx: { section: ReorderableSection<TId> }) => ReactNode
+}
+
+export function ReorderableSections<TId extends string = string>({
+  sections,
+  selectedId,
+  readonly = false,
+  density = 'default',
+  'aria-label': ariaLabel = 'Reorderable sections',
+  onSelect,
+  onMove,
+  renderItem,
+  renderSectionHeader,
+  renderSectionFooter,
+}: ReorderableSectionsProps<TId>): React.ReactElement {
+  const {
+    draggedId,
+    dropTarget,
+    beginDrag,
+    endDrag,
+    hoverDrop,
+    takeCommittedMove,
+  } = useReorderableDragState<TId>()
+
+  const canReorder = !readonly && Boolean(onMove)
+
+  const commitDrop = (sectionKey: string, insertIndex: number): void => {
+    if (!canReorder) return
+    hoverDrop({ sectionKey, insertIndex })
+    const committed = takeCommittedMove()
+    endDrag()
+    if (!committed || !onMove) return
+    onMove({
+      itemId: committed.drag.itemId,
+      from: committed.drag.from,
+      to: committed.to,
+    })
+  }
+
+  const renderRowContent = (
+    id: TId,
+    disabled: boolean,
+    ctx: ReorderableItemRenderContext<TId>,
+  ): ReactNode => {
+    if (renderItem) return renderItem(ctx)
+    return (
+      <StyledItemButton
+        type="button"
+        $selected={ctx.selected}
+        disabled={disabled}
+        onClick={() => {
+          if (!disabled) onSelect?.(id)
+        }}
+      >
+        {id}
+      </StyledItemButton>
+    )
+  }
+
+  return (
+    <StyledRoot aria-label={ariaLabel} $density={density}>
+      {sections.map(section => {
+        const handleRowDragOver = (
+          event: DragEvent<HTMLDivElement>,
+          index: number,
+        ): void => {
+          if (!canReorder || !draggedId) return
+          event.preventDefault()
+          event.dataTransfer.dropEffect = 'move'
+          hoverDrop({
+            sectionKey: section.key,
+            insertIndex: insertIndexFromRowRect(
+              event.clientY,
+              event.currentTarget.getBoundingClientRect(),
+              index,
+            ),
+          })
+        }
+
+        const handleRowDrop = (
+          event: DragEvent<HTMLDivElement>,
+          index: number,
+        ): void => {
+          if (!canReorder || !draggedId) return
+          event.preventDefault()
+          event.stopPropagation()
+          commitDrop(
+            section.key,
+            insertIndexFromRowRect(
+              event.clientY,
+              event.currentTarget.getBoundingClientRect(),
+              index,
+            ),
+          )
+        }
+
+        const handleEmptyDragOver = (event: DragEvent<HTMLLIElement>): void => {
+          if (!canReorder || !draggedId) return
+          event.preventDefault()
+          event.dataTransfer.dropEffect = 'move'
+          hoverDrop({ sectionKey: section.key, insertIndex: 0 })
+        }
+
+        const handleEmptyDrop = (event: DragEvent<HTMLLIElement>): void => {
+          if (!canReorder || !draggedId) return
+          event.preventDefault()
+          commitDrop(section.key, 0)
+        }
+
+        return (
+          <StyledSection
+            key={section.key}
+            $density={density}
+            aria-label={String(section.label ?? section.key)}
+          >
+            {renderSectionHeader ? (
+              renderSectionHeader({ section })
+            ) : section.label ? (
+              <StyledSectionHeader>
+                <StyledSectionLabel as="span">
+                  {section.label}
+                </StyledSectionLabel>
+                {section.headerActions ? (
+                  <StyledSectionActions>
+                    {section.headerActions}
+                  </StyledSectionActions>
+                ) : null}
+              </StyledSectionHeader>
+            ) : section.headerActions ? (
+              <StyledSectionHeader>
+                <StyledSectionActions>
+                  {section.headerActions}
+                </StyledSectionActions>
+              </StyledSectionHeader>
+            ) : null}
+
+            {section.items.length === 0 ? (
+              <StyledList role="list" $density={density}>
+                <StyledEmpty
+                  $density={density}
+                  $active={
+                    Boolean(draggedId) && dropTarget?.sectionKey === section.key
+                  }
+                  onDragOver={handleEmptyDragOver}
+                  onDrop={handleEmptyDrop}
+                >
+                  <Text as="span">{section.emptyLabel ?? 'No items'}</Text>
+                </StyledEmpty>
+              </StyledList>
+            ) : (
+              <StyledList role="list" $density={density}>
+                {section.items.map(
+                  (item: ReorderableItem<TId>, index: number) => {
+                    const dragging = item.id === draggedId
+                    const dropAbove =
+                      dropTarget?.sectionKey === section.key &&
+                      dropTarget.insertIndex === index
+                    const dropBelow =
+                      dropTarget?.sectionKey === section.key &&
+                      dropTarget.insertIndex === index + 1
+                    const disabled = Boolean(item.disabled)
+                    const ctx: ReorderableItemRenderContext<TId> = {
+                      id: item.id,
+                      sectionKey: section.key,
+                      index,
+                      item,
+                      selected: selectedId === item.id,
+                      dragging,
+                      disabled,
+                    }
+
+                    return (
+                      <li key={`${section.key}:${item.id}`}>
+                        <ReorderableListRow
+                          dragging={dragging}
+                          dropAbove={dropAbove}
+                          dropBelow={dropBelow}
+                          readonly={readonly || disabled}
+                          draggable={!disabled}
+                          onDragOver={(event: DragEvent<HTMLDivElement>) =>
+                            handleRowDragOver(event, index)
+                          }
+                          onDrop={(event: DragEvent<HTMLDivElement>) =>
+                            handleRowDrop(event, index)
+                          }
+                          onDragHandleStart={(
+                            event: DragEvent<HTMLSpanElement>,
+                          ) => {
+                            event.dataTransfer.setData('text/plain', item.id)
+                            event.dataTransfer.effectAllowed = 'move'
+                            beginDrag(item.id, {
+                              sectionKey: section.key,
+                              index,
+                            })
+                          }}
+                          onDragEnd={endDrag}
+                        >
+                          {renderRowContent(item.id, disabled, ctx)}
+                        </ReorderableListRow>
+                      </li>
+                    )
+                  },
+                )}
+              </StyledList>
+            )}
+            {renderSectionFooter ? renderSectionFooter({ section }) : null}
+          </StyledSection>
+        )
+      })}
+    </StyledRoot>
+  )
+}

package/src/components/common/lists/reorderable/ReorderableSectionsDemo.tsx

@@ -0,0 +1,94 @@
+import { useCallback, useState } from 'react'
+import { styled } from 'styled-components'
+import { Text } from '../../typography/Text.js'
+import { ReorderableSections } from './ReorderableSections.js'
+import type { ReorderableMove, ReorderableSection } from './types.js'
+
+//#region styled-components
+
+const StyledDemo = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  max-width: 320px;
+  padding: 16px;
+  color: var(--platform-colors-text);
+  background: var(
+    --platform-colors-app-viewport,
+    var(--platform-colors-surface)
+  );
+`
+
+const StyledHint = styled(Text)`
+  margin: 0;
+  color: var(--platform-colors-text-secondary);
+  font-size: var(--platform-typography-font-size-sm);
+`
+
+//#endregion
+
+const INITIAL_SECTIONS: ReorderableSection[] = [
+  {
+    key: 'group-a',
+    label: 'Group A',
+    items: [{ id: 'alpha' }, { id: 'beta' }, { id: 'gamma' }],
+    emptyLabel: 'Drop items here',
+  },
+  {
+    key: 'group-b',
+    label: 'Group B',
+    items: [{ id: 'delta' }],
+    emptyLabel: 'Drop items here',
+  },
+]
+
+function applyDemoMove(
+  sections: ReadonlyArray<ReorderableSection>,
+  move: ReorderableMove,
+): ReorderableSection[] {
+  const next = sections.map(section => ({
+    ...section,
+    items: [...section.items],
+  }))
+
+  const fromSection = next.find(section => section.key === move.from.sectionKey)
+  const toSection = next.find(section => section.key === move.to.sectionKey)
+  if (!fromSection || !toSection) return [...sections]
+
+  const [moved] = fromSection.items.splice(move.from.index, 1)
+  if (!moved) return [...sections]
+
+  let insertIndex = move.to.insertIndex
+  if (fromSection.key === toSection.key && move.from.index < insertIndex) {
+    insertIndex -= 1
+  }
+  insertIndex = Math.max(0, Math.min(insertIndex, toSection.items.length))
+  toSection.items.splice(insertIndex, 0, moved)
+  return next
+}
+
+/** Dummy prop-driven demo — wire into a dev screen or Storybook later. */
+export function ReorderableSectionsDemo(): React.ReactElement {
+  const [sections, setSections] =
+    useState<ReadonlyArray<ReorderableSection>>(INITIAL_SECTIONS)
+  const [selectedId, setSelectedId] = useState<string | undefined>('alpha')
+
+  const handleMove = useCallback((move: ReorderableMove) => {
+    setSections(current => applyDemoMove(current, move))
+  }, [])
+
+  return (
+    <StyledDemo>
+      <StyledHint as="p">
+        Drag handles reorder within and across groups. Selection is local demo
+        state only.
+      </StyledHint>
+      <ReorderableSections
+        sections={sections}
+        selectedId={selectedId}
+        onSelect={setSelectedId}
+        onMove={handleMove}
+      />
+    </StyledDemo>
+  )
+}

package/src/components/common/lists/reorderable/index.ts

@@ -0,0 +1,15 @@
+export { DragHandle } from './DragHandle.js'
+export { ReorderableList } from './ReorderableList.js'
+export { ReorderableListRow } from './ReorderableListRow.js'
+export { ReorderableSections } from './ReorderableSections.js'
+export { ReorderableSectionsDemo } from './ReorderableSectionsDemo.js'
+export { insertIndexFromRowRect, reorderIds } from './reorderableUtils.js'
+export type {
+  ReorderableDragSource,
+  ReorderableDropTarget,
+  ReorderableItem,
+  ReorderableItemRenderContext,
+  ReorderableMove,
+  ReorderableSection,
+} from './types.js'
+export { useReorderableDragState } from './useReorderableDragState.js'

package/src/components/common/lists/reorderable/reorderableUtils.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { insertIndexFromRowRect, reorderIds } from './reorderableUtils.js'
+
+describe('insertIndexFromRowRect', () => {
+  const rect = { top: 100, height: 40 }
+
+  it('returns row index when pointer is in upper half', () => {
+    expect(insertIndexFromRowRect(110, rect, 2)).toBe(2)
+  })
+
+  it('returns row index + 1 when pointer is in lower half', () => {
+    expect(insertIndexFromRowRect(125, rect, 2)).toBe(3)
+  })
+})
+
+describe('reorderIds', () => {
+  it('moves an item down within the list', () => {
+    expect(reorderIds(['a', 'b', 'c'], 0, 2)).toEqual(['b', 'a', 'c'])
+  })
+
+  it('moves an item up within the list', () => {
+    expect(reorderIds(['a', 'b', 'c'], 2, 0)).toEqual(['c', 'a', 'b'])
+  })
+
+  it('returns a copy when from index is invalid', () => {
+    expect(reorderIds(['a', 'b'], 5, 0)).toEqual(['a', 'b'])
+  })
+})

package/src/components/common/lists/reorderable/reorderableUtils.ts

@@ -0,0 +1,23 @@
+/** Half-row hit test — ps-book ChapterTree SectionList parity. */
+export function insertIndexFromRowRect(
+  clientY: number,
+  rect: Pick<DOMRect, 'top' | 'height'>,
+  rowIndex: number,
+): number {
+  return clientY < rect.top + rect.height / 2 ? rowIndex : rowIndex + 1
+}
+
+/** Rebuild item order after a within-list move (same container). */
+export function reorderIds<TId extends string>(
+  ids: ReadonlyArray<TId>,
+  fromIndex: number,
+  insertIndex: number,
+): TId[] {
+  if (fromIndex < 0 || fromIndex >= ids.length) return [...ids]
+  const next = [...ids]
+  const [moved] = next.splice(fromIndex, 1)
+  const targetIndex = insertIndex > fromIndex ? insertIndex - 1 : insertIndex
+  const clamped = Math.max(0, Math.min(targetIndex, next.length))
+  next.splice(clamped, 0, moved)
+  return next
+}

package/src/components/common/lists/reorderable/types.ts

@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react'
+
+export type ReorderableItem<TId extends string = string> = {
+  id: TId
+  disabled?: boolean
+}
+
+export type ReorderableSection<TId extends string = string> = {
+  key: string
+  label?: ReactNode
+  items: ReadonlyArray<ReorderableItem<TId>>
+  headerActions?: ReactNode
+  emptyLabel?: string
+}
+
+export type ReorderableMove<TId extends string = string> = {
+  itemId: TId
+  from: { sectionKey: string; index: number }
+  to: { sectionKey: string; insertIndex: number }
+}
+
+export type ReorderableItemRenderContext<TId extends string = string> = {
+  id: TId
+  sectionKey: string
+  index: number
+  item: ReorderableItem<TId>
+  selected: boolean
+  dragging: boolean
+  disabled: boolean
+}
+
+export type ReorderableDragSource = {
+  sectionKey: string
+  index: number
+}
+
+export type ReorderableDropTarget = {
+  sectionKey: string
+  insertIndex: number
+}

package/src/components/common/lists/reorderable/useReorderableDragState.ts

@@ -0,0 +1,49 @@
+import { useCallback, useRef, useState } from 'react'
+import type { ReorderableDragSource, ReorderableDropTarget } from './types.js'
+
+export type ActiveReorderableDrag<TId extends string> = {
+  itemId: TId
+  from: ReorderableDragSource
+}
+
+export function useReorderableDragState<TId extends string>() {
+  const draggedRef = useRef<ActiveReorderableDrag<TId> | null>(null)
+  const [draggedId, setDraggedId] = useState<TId | null>(null)
+  const [dropTarget, setDropTarget] = useState<ReorderableDropTarget | null>(
+    null,
+  )
+
+  const beginDrag = useCallback((itemId: TId, from: ReorderableDragSource) => {
+    draggedRef.current = { itemId, from }
+    setDraggedId(itemId)
+    setDropTarget(null)
+  }, [])
+
+  const endDrag = useCallback(() => {
+    draggedRef.current = null
+    setDraggedId(null)
+    setDropTarget(null)
+  }, [])
+
+  const hoverDrop = useCallback((target: ReorderableDropTarget) => {
+    setDropTarget(target)
+  }, [])
+
+  const takeCommittedMove = useCallback((): {
+    drag: ActiveReorderableDrag<TId>
+    to: ReorderableDropTarget
+  } | null => {
+    const drag = draggedRef.current
+    if (!drag || !dropTarget) return null
+    return { drag, to: dropTarget }
+  }, [dropTarget])
+
+  return {
+    draggedId,
+    dropTarget,
+    beginDrag,
+    endDrag,
+    hoverDrop,
+    takeCommittedMove,
+  }
+}