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

package/src/components/common/layout/PanelGroup.tsx

@@ -0,0 +1,479 @@
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type PointerEvent as ReactPointerEvent,
+  type ReactElement,
+  type ReactNode,
+} from 'react'
+import { css, styled } from 'styled-components'
+import type {
+  PanelConfig,
+  PanelGroupDirection,
+  PanelLayoutPersistence,
+  PanelLayoutSizes,
+} from './panelLayoutTypes.js'
+import {
+  isPanelResizeHandleHidden,
+  normalizePanelSizes,
+  panelFlexBasis,
+  resizeAdjacentPanels,
+  visiblePanelLayoutSizes,
+  visiblePanelResizeHandleCount,
+} from './panelLayoutState.js'
+
+/** ps-book BookView — layout width, not hit target. */
+const DIVIDER_WIDTH_PX = 2
+const DIVIDER_HIT_WIDTH_PX = 20
+
+//#region styled-components
+
+/** BookView StyledBody equivalent. */
+const StyledPanelGroup = styled.div<{ $vertical: boolean }>`
+  display: flex;
+  position: relative;
+  flex: 1 1 auto;
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+  flex-direction: ${({ $vertical }) => ($vertical ? 'column' : 'row')};
+`
+
+const StyledPanel = styled.div<{
+  $vertical: boolean
+  $basis?: string
+  $bordered: boolean
+  $collapsed: boolean
+  $resizing: boolean
+}>`
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+  transition: ${({ $resizing }) =>
+    $resizing
+      ? 'none'
+      : 'flex-basis var(--platform-transition-base), width var(--platform-transition-base), height var(--platform-transition-base)'};
+
+  ${({ $collapsed, $basis, $vertical }) =>
+    $collapsed
+      ? `
+    flex: 0 0 0;
+    ${$vertical ? 'height: 0;' : 'width: 0;'}
+    min-width: 0;
+    min-height: 0;
+  `
+      : `
+    flex: 0 0 ${$basis};
+    ${$vertical ? `height: ${$basis};` : ''}
+  `}
+
+  ${({ $bordered, $vertical, $collapsed }) =>
+    $bordered && !$collapsed
+      ? $vertical
+        ? `border-bottom: 1px solid var(--platform-colors-border);`
+        : `border-right: 1px solid var(--platform-colors-border);`
+      : ''}
+`
+
+const StyledPanelInner = styled.div<{
+  $collapsed: boolean
+  $resizing: boolean
+}>`
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+  opacity: ${({ $collapsed }) => ($collapsed ? 0 : 1)};
+  pointer-events: ${({ $collapsed }) => ($collapsed ? 'none' : 'auto')};
+  transition: ${({ $resizing }) =>
+    $resizing ? 'none' : 'opacity var(--platform-transition-base)'};
+`
+
+/** BookView StyledDivider equivalent. */
+const StyledResizeHandle = styled.div<{
+  $vertical: boolean
+  $dragging: boolean
+  $hidden: boolean
+  $resizing: boolean
+}>`
+  position: relative;
+  flex: 0 0 ${({ $hidden }) => ($hidden ? '0px' : `${DIVIDER_WIDTH_PX}px`)};
+  touch-action: none;
+  background: transparent;
+  overflow: hidden;
+  opacity: ${({ $hidden }) => ($hidden ? 0 : 1)};
+  pointer-events: ${({ $hidden }) => ($hidden ? 'none' : 'auto')};
+  transition: ${({ $dragging, $resizing }) =>
+    $dragging || $resizing
+      ? 'none'
+      : 'flex-basis var(--platform-transition-base), opacity var(--platform-transition-base), background var(--platform-transition-fast)'};
+  cursor: ${({ $vertical, $hidden }) =>
+    $hidden ? 'default' : $vertical ? 'row-resize' : 'col-resize'};
+
+  ${({ $vertical }) =>
+    $vertical
+      ? `
+    width: 100%;
+    height: ${DIVIDER_WIDTH_PX}px;
+  `
+      : `
+    width: ${DIVIDER_WIDTH_PX}px;
+    height: 100%;
+  `}
+
+  ${({ $dragging, $vertical }) =>
+    $dragging &&
+    css`
+      background: ${$vertical
+        ? `linear-gradient(
+        180deg,
+        transparent calc(50% - 1px),
+        rgb(from var(--platform-colors-text) r g b / 38%) calc(50% - 1px),
+        rgb(from var(--platform-colors-text) r g b / 38%) calc(50% + 1px),
+        transparent calc(50% + 1px)
+      )`
+        : `linear-gradient(
+        90deg,
+        transparent calc(50% - 1px),
+        rgb(from var(--platform-colors-text) r g b / 38%) calc(50% - 1px),
+        rgb(from var(--platform-colors-text) r g b / 38%) calc(50% + 1px),
+        transparent calc(50% + 1px)
+      )`};
+    `}
+
+  &:hover {
+    background: ${({ $vertical }) =>
+      $vertical
+        ? `linear-gradient(
+        180deg,
+        transparent calc(50% - 1px),
+        rgb(from var(--platform-colors-text-secondary) r g b / 28%)
+          calc(50% - 1px),
+        rgb(from var(--platform-colors-text-secondary) r g b / 28%)
+          calc(50% + 1px),
+        transparent calc(50% + 1px)
+      )`
+        : `linear-gradient(
+        90deg,
+        transparent calc(50% - 1px),
+        rgb(from var(--platform-colors-text-secondary) r g b / 28%)
+          calc(50% - 1px),
+        rgb(from var(--platform-colors-text-secondary) r g b / 28%)
+          calc(50% + 1px),
+        transparent calc(50% + 1px)
+      )`};
+  }
+
+  &::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    ${({ $vertical }) =>
+      $vertical
+        ? `height: ${DIVIDER_HIT_WIDTH_PX}px;`
+        : `width: ${DIVIDER_HIT_WIDTH_PX}px;`}
+  }
+`
+
+//#endregion
+
+interface PanelGroupContextValue {
+  direction: PanelGroupDirection
+}
+
+const PanelGroupContext = createContext<PanelGroupContextValue | null>(null)
+
+export interface PanelProps {
+  children: ReactNode
+  minSize?: number
+  maxSize?: number
+  /** Collapse to zero size with transition; stored drag sizes are preserved. */
+  collapsed?: boolean
+}
+
+export function Panel({
+  children,
+  minSize = 5,
+  maxSize = 95,
+  collapsed = false,
+}: PanelProps): React.ReactElement {
+  void minSize
+  void maxSize
+  void collapsed
+  return <>{children}</>
+}
+
+Panel.displayName = 'PlatformPanel'
+
+export interface PanelResizeHandleProps {
+  'aria-label'?: string
+}
+
+export function PanelResizeHandle({
+  'aria-label': ariaLabel = 'Resize panel',
+}: PanelResizeHandleProps): null {
+  void ariaLabel
+  return null
+}
+
+PanelResizeHandle.displayName = 'PlatformPanelResizeHandle'
+
+export interface PanelGroupProps {
+  direction?: PanelGroupDirection
+  defaultSizes: PanelLayoutSizes
+  sizes?: PanelLayoutSizes
+  onSizesChange?: (sizes: PanelLayoutSizes) => void
+  persistence?: PanelLayoutPersistence
+  children: ReactNode
+}
+
+interface ParsedPanelChild {
+  element: ReactElement<PanelProps>
+  config: PanelConfig
+  collapsed: boolean
+}
+
+interface ParsedPanelGroup {
+  items: Array<{ kind: 'panel'; panel: ParsedPanelChild } | { kind: 'handle' }>
+  configs: PanelConfig[]
+}
+
+export function PanelGroup({
+  direction = 'horizontal',
+  defaultSizes,
+  sizes: controlledSizes,
+  onSizesChange,
+  persistence,
+  children,
+}: PanelGroupProps): React.ReactElement {
+  const groupRef = useRef<HTMLDivElement | null>(null)
+  const parsed = useMemo(() => parsePanelGroupChildren(children), [children])
+  const collapsedByPanel = useMemo(
+    () =>
+      parsed.items
+        .filter(
+          (item): item is { kind: 'panel'; panel: ParsedPanelChild } =>
+            item.kind === 'panel',
+        )
+        .map(item => item.panel.collapsed),
+    [parsed.items],
+  )
+  const handleCount = useMemo(
+    () => parsed.items.filter(item => item.kind === 'handle').length,
+    [parsed.items],
+  )
+  const visibleDividerCount = useMemo(
+    () => visiblePanelResizeHandleCount(collapsedByPanel, handleCount),
+    [collapsedByPanel, handleCount],
+  )
+  const vertical = direction === 'vertical'
+  const [internalSizes, setInternalSizes] = useState<PanelLayoutSizes>(() => {
+    const loaded = persistence?.load()
+    const initial = loaded ?? defaultSizes
+    return normalizePanelSizes(initial, parsed.configs)
+  })
+  const [activeHandleIndex, setActiveHandleIndex] = useState<number | null>(
+    null,
+  )
+
+  const sizes = controlledSizes ?? internalSizes
+  const sizesRef = useRef(sizes)
+  sizesRef.current = sizes
+
+  const layoutSizes = useMemo(
+    () => visiblePanelLayoutSizes(sizes, collapsedByPanel),
+    [collapsedByPanel, sizes],
+  )
+
+  useEffect(() => {
+    const loaded = persistence?.load()
+    if (!loaded || controlledSizes) return
+    setInternalSizes(normalizePanelSizes(loaded, parsed.configs))
+  }, [controlledSizes, parsed.configs, persistence])
+
+  const applySizes = useCallback(
+    (next: PanelLayoutSizes) => {
+      const normalized = normalizePanelSizes(next, parsed.configs)
+      sizesRef.current = normalized
+      if (!controlledSizes) {
+        setInternalSizes(normalized)
+      }
+      onSizesChange?.(normalized)
+      return normalized
+    },
+    [controlledSizes, onSizesChange, parsed.configs],
+  )
+
+  const startResize = useCallback(
+    (handleIndex: number, event: ReactPointerEvent<HTMLDivElement>) => {
+      event.preventDefault()
+      const group = groupRef.current
+      const handle = event.currentTarget
+      if (!group) return
+
+      const rect = group.getBoundingClientRect()
+      const axisSize = vertical ? rect.height : rect.width
+      const availableSize = axisSize - visibleDividerCount * DIVIDER_WIDTH_PX
+      if (availableSize <= 0) return
+      if (isPanelResizeHandleHidden(handleIndex, collapsedByPanel)) return
+
+      const startSizes = [...sizesRef.current]
+      const startPosition = vertical ? event.clientY : event.clientX
+
+      setActiveHandleIndex(handleIndex)
+      handle.setPointerCapture(event.pointerId)
+
+      const previousUserSelect = document.body.style.userSelect
+      const previousCursor = document.body.style.cursor
+      document.body.style.userSelect = 'none'
+      document.body.style.cursor = vertical ? 'row-resize' : 'col-resize'
+
+      const onPointerMove = (moveEvent: PointerEvent): void => {
+        const deltaPx =
+          (vertical ? moveEvent.clientY : moveEvent.clientX) - startPosition
+        const deltaPercent = (deltaPx / availableSize) * 100
+        applySizes(
+          resizeAdjacentPanels(
+            startSizes,
+            parsed.configs,
+            handleIndex,
+            deltaPercent,
+          ),
+        )
+      }
+
+      const finishResize = (upEvent: PointerEvent): void => {
+        setActiveHandleIndex(null)
+        handle.releasePointerCapture(upEvent.pointerId)
+        document.body.style.userSelect = previousUserSelect
+        document.body.style.cursor = previousCursor
+        persistence?.save(sizesRef.current)
+        window.removeEventListener('pointermove', onPointerMove)
+        window.removeEventListener('pointerup', finishResize)
+        window.removeEventListener('pointercancel', finishResize)
+      }
+
+      window.addEventListener('pointermove', onPointerMove)
+      window.addEventListener('pointerup', finishResize)
+      window.addEventListener('pointercancel', finishResize)
+    },
+    [
+      applySizes,
+      collapsedByPanel,
+      parsed.configs,
+      persistence,
+      vertical,
+      visibleDividerCount,
+    ],
+  )
+
+  let panelIndex = -1
+  let handleIndex = -1
+  const isResizing = activeHandleIndex !== null
+  const panelCount = parsed.configs.length
+
+  return (
+    <PanelGroupContext.Provider value={{ direction }}>
+      <StyledPanelGroup ref={groupRef} $vertical={vertical}>
+        {parsed.items.map((item, index) => {
+          if (item.kind === 'panel') {
+            panelIndex += 1
+            const collapsed = item.panel.collapsed
+            const sizePercent =
+              layoutSizes[panelIndex] ?? defaultSizes[panelIndex] ?? 0
+            const basis = collapsed
+              ? undefined
+              : panelFlexBasis(sizePercent, visibleDividerCount)
+
+            return (
+              <StyledPanel
+                key={`panel-${index}`}
+                $vertical={vertical}
+                $basis={basis}
+                $bordered={panelIndex < panelCount - 1}
+                $collapsed={collapsed}
+                $resizing={isResizing}
+              >
+                <StyledPanelInner $collapsed={collapsed} $resizing={isResizing}>
+                  {item.panel.element.props.children}
+                </StyledPanelInner>
+              </StyledPanel>
+            )
+          }
+
+          handleIndex += 1
+          const currentHandleIndex = handleIndex
+          const handleHidden = isPanelResizeHandleHidden(
+            currentHandleIndex,
+            collapsedByPanel,
+          )
+          return (
+            <StyledResizeHandle
+              key={`handle-${index}`}
+              $vertical={vertical}
+              $dragging={activeHandleIndex === currentHandleIndex}
+              $hidden={handleHidden}
+              $resizing={isResizing}
+              role="separator"
+              aria-orientation={vertical ? 'horizontal' : 'vertical'}
+              aria-label="Resize panel"
+              aria-hidden={handleHidden}
+              onPointerDown={event => startResize(currentHandleIndex, event)}
+            />
+          )
+        })}
+      </StyledPanelGroup>
+    </PanelGroupContext.Provider>
+  )
+}
+
+function parsePanelGroupChildren(children: ReactNode): ParsedPanelGroup {
+  const items: ParsedPanelGroup['items'] = []
+  const configs: PanelConfig[] = []
+
+  Children.forEach(children, child => {
+    if (!isValidElement(child)) return
+    if (child.type === Panel) {
+      const props = child.props as PanelProps
+      items.push({
+        kind: 'panel',
+        panel: {
+          element: child as ReactElement<PanelProps>,
+          config: {
+            minSize: props.minSize,
+            maxSize: props.maxSize,
+          },
+          collapsed: props.collapsed ?? false,
+        },
+      })
+      configs.push({
+        minSize: props.minSize ?? 5,
+        maxSize: props.maxSize ?? 95,
+      })
+      return
+    }
+    if (child.type === PanelResizeHandle) {
+      items.push({ kind: 'handle' })
+    }
+  })
+
+  return { items, configs }
+}
+
+export function usePanelGroupDirection(): PanelGroupDirection {
+  const ctx = useContext(PanelGroupContext)
+  return ctx?.direction ?? 'horizontal'
+}

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

@@ -0,0 +1,31 @@
+export {
+  PLATFORM_PANEL_LAYOUT_PREFERENCE_KEY,
+  PLATFORM_PANEL_LAYOUT_STATE_VERSION,
+  PLATFORM_PANEL_LAYOUT_STORAGE_PREFIX,
+} from './panelLayoutConstants.js'
+export type {
+  PanelConfig,
+  PanelGroupDirection,
+  PanelLayoutPersistence,
+  PanelLayoutPreferenceState,
+  PanelLayoutSizes,
+} from './panelLayoutTypes.js'
+export {
+  normalizePanelSizes,
+  evenPanelSizes,
+  resizeAdjacentPanels,
+  serializePanelLayoutPreference,
+  patchPanelLayoutPreference,
+  readPanelLayoutFromAppSettings,
+  parsePanelLayoutPreference,
+} from './panelLayoutState.js'
+export { createLocalStoragePanelPersistence } from './panelLayoutPersistence.js'
+export {
+  Panel,
+  PanelGroup,
+  PanelResizeHandle,
+  usePanelGroupDirection,
+  type PanelGroupProps,
+  type PanelProps,
+  type PanelResizeHandleProps,
+} from './PanelGroup.js'

package/src/components/common/layout/panelLayoutConstants.ts

@@ -0,0 +1,7 @@
+/** Field name inside `settings.app.*` patch objects for panel size arrays. */
+export const PLATFORM_PANEL_LAYOUT_PREFERENCE_KEY = 'panelLayout'
+
+/** Prefix for optional localStorage fallback keys (append app-specific suffix). */
+export const PLATFORM_PANEL_LAYOUT_STORAGE_PREFIX = 'platform.panelLayout.'
+
+export const PLATFORM_PANEL_LAYOUT_STATE_VERSION = 1

package/src/components/common/layout/panelLayoutPersistence.ts

@@ -0,0 +1,35 @@
+import { PLATFORM_PANEL_LAYOUT_STORAGE_PREFIX } from './panelLayoutConstants.js'
+import {
+  parsePanelLayoutPreference,
+  serializePanelLayoutPreference,
+} from './panelLayoutState.js'
+import type {
+  PanelLayoutPersistence,
+  PanelLayoutSizes,
+} from './panelLayoutTypes.js'
+
+export function createLocalStoragePanelPersistence(
+  storageKey: string,
+): PanelLayoutPersistence {
+  const key = `${PLATFORM_PANEL_LAYOUT_STORAGE_PREFIX}${storageKey}`
+
+  return {
+    load(): PanelLayoutSizes | null {
+      if (typeof window === 'undefined') return null
+      try {
+        const raw = window.localStorage.getItem(key)
+        if (!raw) return null
+        return parsePanelLayoutPreference(JSON.parse(raw))
+      } catch {
+        return null
+      }
+    },
+    save(sizes: PanelLayoutSizes): void {
+      if (typeof window === 'undefined') return
+      window.localStorage.setItem(
+        key,
+        JSON.stringify(serializePanelLayoutPreference(sizes)),
+      )
+    },
+  }
+}

package/src/components/common/layout/panelLayoutState.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest'
+import {
+  isPanelResizeHandleHidden,
+  panelFlexBasis,
+  visiblePanelLayoutSizes,
+} from './panelLayoutState.js'
+
+describe('panelLayoutState', () => {
+  it('renormalizes sizes across visible panels only', () => {
+    const allVisible = visiblePanelLayoutSizes(
+      [22, 58, 20],
+      [false, false, false],
+    )
+    expect(allVisible[0]).toBeCloseTo(22, 5)
+    expect(allVisible[1]).toBeCloseTo(58, 5)
+    expect(allVisible[2]).toBeCloseTo(20, 5)
+
+    const drawerClosed = visiblePanelLayoutSizes(
+      [22, 58, 20],
+      [false, false, true],
+    )
+    expect(drawerClosed[0]).toBeCloseTo(27.5, 5)
+    expect(drawerClosed[1]).toBeCloseTo(72.5, 5)
+    expect(drawerClosed[2]).toBe(0)
+
+    expect(visiblePanelLayoutSizes([72, 28], [false, true])).toEqual([100, 0])
+  })
+
+  it('hides resize handle when either neighbor is collapsed', () => {
+    expect(isPanelResizeHandleHidden(0, [false, true])).toBe(true)
+    expect(isPanelResizeHandleHidden(0, [false, false, true])).toBe(false)
+    expect(isPanelResizeHandleHidden(1, [false, false, true])).toBe(true)
+  })
+
+  it('builds flex basis from visible percent and divider count', () => {
+    expect(panelFlexBasis(28, 1)).toBe('calc((100% - 2px) * 0.28)')
+  })
+})