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

package/src/components/common/containers/SurfacePanel.tsx

@@ -1,66 +1,66 @@
-import type { ReactNode } from 'react'
-import { styled } from 'styled-components'
-
-export interface SurfacePanelProps {
-  title?: string
-  description?: string
-  children?: ReactNode
-  footer?: ReactNode
-}
-
-//#region styled-components
-
-const StyledPanel = styled.section`
-  padding: var(--platform-spacing-lg);
-  border: 1px solid var(--platform-colors-border);
-  border-radius: var(--platform-radius-md);
-  background: var(--platform-colors-surface);
-  box-sizing: border-box;
-  min-width: 0;
-  max-width: 100%;
-`
-
-const StyledTitle = styled.h2`
-  margin: 0 0 var(--platform-spacing-sm);
-  font-size: var(--platform-typography-font-size-lg);
-  font-weight: var(--platform-typography-font-weight-medium);
-  line-height: var(--platform-typography-line-height-tight);
-`
-
-const StyledDescription = styled.p`
-  max-width: 48rem;
-  margin: 0;
-  color: var(--platform-colors-text-secondary);
-  line-height: var(--platform-typography-line-height-base);
-`
-
-const StyledBody = styled.div`
-  margin-top: var(--platform-spacing-md);
-  min-width: 0;
-`
-
-const StyledFooter = styled.div`
-  margin-top: var(--platform-spacing-md);
-  padding-top: var(--platform-spacing-sm);
-  border-top: 1px solid var(--platform-colors-border);
-`
-
-//#endregion
-
-export function SurfacePanel({
-  title,
-  description,
-  children,
-  footer,
-}: SurfacePanelProps): React.ReactElement {
-  return (
-    <StyledPanel>
-      {title ? <StyledTitle>{title}</StyledTitle> : null}
-      {description ? (
-        <StyledDescription>{description}</StyledDescription>
-      ) : null}
-      {children ? <StyledBody>{children}</StyledBody> : null}
-      {footer ? <StyledFooter>{footer}</StyledFooter> : null}
-    </StyledPanel>
-  )
-}
+import type { ReactNode } from 'react'
+import { styled } from 'styled-components'
+
+export interface SurfacePanelProps {
+  title?: string
+  description?: string
+  children?: ReactNode
+  footer?: ReactNode
+}
+
+//#region styled-components
+
+const StyledPanel = styled.section`
+  padding: var(--platform-spacing-lg);
+  border: 1px solid var(--platform-colors-border);
+  border-radius: var(--platform-radius-md);
+  background: var(--platform-colors-surface);
+  box-sizing: border-box;
+  min-width: 0;
+  max-width: 100%;
+`
+
+const StyledTitle = styled.h2`
+  margin: 0 0 var(--platform-spacing-sm);
+  font-size: var(--platform-typography-font-size-lg);
+  font-weight: var(--platform-typography-font-weight-medium);
+  line-height: var(--platform-typography-line-height-tight);
+`
+
+const StyledDescription = styled.p`
+  max-width: 48rem;
+  margin: 0;
+  color: var(--platform-colors-text-secondary);
+  line-height: var(--platform-typography-line-height-base);
+`
+
+const StyledBody = styled.div`
+  margin-top: var(--platform-spacing-md);
+  min-width: 0;
+`
+
+const StyledFooter = styled.div`
+  margin-top: var(--platform-spacing-md);
+  padding-top: var(--platform-spacing-sm);
+  border-top: 1px solid var(--platform-colors-border);
+`
+
+//#endregion
+
+export function SurfacePanel({
+  title,
+  description,
+  children,
+  footer,
+}: SurfacePanelProps): React.ReactElement {
+  return (
+    <StyledPanel>
+      {title ? <StyledTitle>{title}</StyledTitle> : null}
+      {description ? (
+        <StyledDescription>{description}</StyledDescription>
+      ) : null}
+      {children ? <StyledBody>{children}</StyledBody> : null}
+      {footer ? <StyledFooter>{footer}</StyledFooter> : null}
+    </StyledPanel>
+  )
+}

package/src/components/common/containers/ToolbarStrip.tsx

@@ -1,80 +1,80 @@
-import { FlexRow } from './flex.js'
-import { styled } from 'styled-components'
-import { zi } from '../../../theme/themeVars.js'
-
-export interface ToolbarStripProps {
-  leading?: React.ReactNode
-  children?: React.ReactNode
-  trailing?: React.ReactNode
-  elevated?: boolean
-}
-
-//#region styled-components
-
-const StyledToolbar = styled(FlexRow)<{ $elevated: boolean }>`
-  align-items: center;
-  gap: var(--platform-spacing-md);
-  padding: var(--platform-spacing-sm) var(--platform-spacing-md);
-  border-bottom: 1px solid var(--platform-colors-border);
-  background: ${({ $elevated }) =>
-    $elevated
-      ? 'var(--platform-colors-elevated)'
-      : 'var(--platform-colors-surface)'};
-  font-size: var(--platform-typography-font-size-base);
-  z-index: ${zi.appViewportToolbar};
-  width: 100%;
-`
-
-export const ToolbarDivider = styled.span`
-  flex: 0 0 auto;
-  width: 1px;
-  height: 20px;
-  background: var(--platform-colors-border);
-`
-
-//#endregion
-
-export function ToolbarStrip({
-  leading,
-  children,
-  trailing,
-  elevated = true,
-}: ToolbarStripProps): React.ReactElement {
-  return (
-    <StyledToolbar $elevated={elevated} $align="start" $gap="md">
-      {leading ? (
-        <FlexRow
-          $align="center"
-          $gap="sm"
-          $flex="1 1 0"
-          $width="auto"
-          style={{ minWidth: 0 }}
-        >
-          {leading}
-        </FlexRow>
-      ) : null}
-      {children ? (
-        <FlexRow
-          $align="center"
-          $gap="md"
-          $flex="1 1 0"
-          $width="auto"
-          style={{ minWidth: 0 }}
-        >
-          {children}
-        </FlexRow>
-      ) : null}
-      {trailing ? (
-        <FlexRow
-          $align="center"
-          $gap="sm"
-          $flex="0 0 auto"
-          $width="auto"
-          style={{ marginLeft: 'auto', alignSelf: 'center' }}
-        >
-          {trailing}
-        </FlexRow>
-      ) : null}
-    </StyledToolbar>
-  )
-}
+import { FlexRow } from './flex.js'
+import { styled } from 'styled-components'
+import { zi } from '../../../theme/themeVars.js'
+
+export interface ToolbarStripProps {
+  leading?: React.ReactNode
+  children?: React.ReactNode
+  trailing?: React.ReactNode
+  elevated?: boolean
+}
+
+//#region styled-components
+
+const StyledToolbar = styled(FlexRow)<{ $elevated: boolean }>`
+  align-items: center;
+  gap: var(--platform-spacing-md);
+  padding: var(--platform-spacing-sm) var(--platform-spacing-md);
+  border-bottom: 1px solid var(--platform-colors-border);
+  background: ${({ $elevated }) =>
+    $elevated
+      ? 'var(--platform-colors-elevated)'
+      : 'var(--platform-colors-surface)'};
+  font-size: var(--platform-typography-font-size-base);
+  z-index: ${zi.appViewportToolbar};
+  width: 100%;
+`
+
+export const ToolbarDivider = styled.span`
+  flex: 0 0 auto;
+  width: 1px;
+  height: 20px;
+  background: var(--platform-colors-border);
+`
+
+//#endregion
+
+export function ToolbarStrip({
+  leading,
+  children,
+  trailing,
+  elevated = true,
+}: ToolbarStripProps): React.ReactElement {
+  return (
+    <StyledToolbar $elevated={elevated} $align="start" $gap="md">
+      {leading ? (
+        <FlexRow
+          $align="center"
+          $gap="sm"
+          $flex="1 1 0"
+          $width="auto"
+          style={{ minWidth: 0 }}
+        >
+          {leading}
+        </FlexRow>
+      ) : null}
+      {children ? (
+        <FlexRow
+          $align="center"
+          $gap="md"
+          $flex="1 1 0"
+          $width="auto"
+          style={{ minWidth: 0 }}
+        >
+          {children}
+        </FlexRow>
+      ) : null}
+      {trailing ? (
+        <FlexRow
+          $align="center"
+          $gap="sm"
+          $flex="0 0 auto"
+          $width="auto"
+          style={{ marginLeft: 'auto', alignSelf: 'center' }}
+        >
+          {trailing}
+        </FlexRow>
+      ) : null}
+    </StyledToolbar>
+  )
+}

package/src/components/common/containers/flex.ts

@@ -1,117 +1,117 @@
-import { css, styled } from 'styled-components'
-
-export type FlexAlign = 'start' | 'center' | 'end' | 'stretch'
-export type FlexJustify =
-  | 'start'
-  | 'center'
-  | 'end'
-  | 'between'
-  | 'around'
-  | 'evenly'
-export type SpacingToken = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'
-
-export interface FlexStyleProps {
-  $row?: boolean
-  $column?: boolean
-  $align?: FlexAlign
-  $justify?: FlexJustify
-  $gap?: SpacingToken
-  $flex?: string
-  $width?: string
-  $height?: string
-  $minHeight?: string
-  $wrap?: boolean
-  /** Frameless Electron chrome — exclude from window drag region. */
-  $noDrag?: boolean
-}
-
-const alignMap: Record<FlexAlign, string> = {
-  start: 'flex-start',
-  center: 'center',
-  end: 'flex-end',
-  stretch: 'stretch',
-}
-
-const justifyMap: Record<FlexJustify, string> = {
-  start: 'flex-start',
-  center: 'center',
-  end: 'flex-end',
-  between: 'space-between',
-  around: 'space-around',
-  evenly: 'space-evenly',
-}
-
-function gapCss(gap?: SpacingToken): string {
-  return gap ? `var(--platform-spacing-${gap})` : '0'
-}
-
-/** Full-height panel shell inside a resizable column — stretch, never width: 100%. */
-export const flexPanelShellCss = css`
-  flex: 1 1 auto;
-  min-width: 0;
-  min-height: 0;
-  width: auto;
-  max-width: 100%;
-  align-self: stretch;
-  height: 100%;
-  box-sizing: border-box;
-`
-
-/** Growing scroll region inside a panel column — stretch, never width: 100%. */
-export const flexPanelBodyCss = css`
-  flex: 1 1 auto;
-  min-width: 0;
-  min-height: 0;
-  width: auto;
-  max-width: 100%;
-  align-self: stretch;
-  box-sizing: border-box;
-`
-
-/** Non-growing block inside a panel body (preview, header block, etc.). */
-export const flexPanelBlockCss = css`
-  flex: 0 0 auto;
-  min-width: 0;
-  width: auto;
-  max-width: 100%;
-  align-self: stretch;
-  box-sizing: border-box;
-`
-
-export const flexStyles = css<FlexStyleProps>`
-  display: flex;
-  flex: ${p => p.$flex ?? '0 0 auto'};
-  flex-direction: ${p => {
-    if (p.$row) return 'row'
-    if (p.$column) return 'column'
-    return 'row'
-  }};
-  flex-wrap: ${p => (p.$wrap ? 'wrap' : 'nowrap')};
-  align-items: ${p => (p.$align ? alignMap[p.$align] : 'inherit')};
-  justify-content: ${p => (p.$justify ? justifyMap[p.$justify] : 'inherit')};
-  gap: ${p => gapCss(p.$gap)};
-  width: ${p => p.$width ?? 'fit-content'};
-  height: ${p => p.$height ?? 'fit-content'};
-  min-height: ${p => p.$minHeight ?? 'auto'};
-  -webkit-app-region: ${p => (p.$noDrag ? 'no-drag' : 'inherit')};
-`
-
-export const Flex = styled.div<FlexStyleProps>`
-  ${flexStyles}
-`
-
-export const FlexRow = styled.div<FlexStyleProps>`
-  ${flexStyles}
-  flex-direction: row;
-  width: ${p => p.$width ?? '100%'};
-`
-
-export const FlexCol = styled.div<FlexStyleProps>`
-  ${flexStyles}
-  flex-direction: column;
-  min-width: 0;
-  box-sizing: border-box;
-  width: ${p => p.$width ?? 'auto'};
-  max-width: ${p => (p.$width ? 'none' : '100%')};
-  align-self: ${p => (p.$width ? 'auto' : 'stretch')};
-`
+import { css, styled } from 'styled-components'
+
+export type FlexAlign = 'start' | 'center' | 'end' | 'stretch'
+export type FlexJustify =
+  | 'start'
+  | 'center'
+  | 'end'
+  | 'between'
+  | 'around'
+  | 'evenly'
+export type SpacingToken = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'
+
+export interface FlexStyleProps {
+  $row?: boolean
+  $column?: boolean
+  $align?: FlexAlign
+  $justify?: FlexJustify
+  $gap?: SpacingToken
+  $flex?: string
+  $width?: string
+  $height?: string
+  $minHeight?: string
+  $wrap?: boolean
+  /** Frameless Electron chrome — exclude from window drag region. */
+  $noDrag?: boolean
+}
+
+const alignMap: Record<FlexAlign, string> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  stretch: 'stretch',
+}
+
+const justifyMap: Record<FlexJustify, string> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  between: 'space-between',
+  around: 'space-around',
+  evenly: 'space-evenly',
+}
+
+function gapCss(gap?: SpacingToken): string {
+  return gap ? `var(--platform-spacing-${gap})` : '0'
+}
+
+/** Full-height panel shell inside a resizable column — stretch, never width: 100%. */
+export const flexPanelShellCss = css`
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+  width: auto;
+  max-width: 100%;
+  align-self: stretch;
+  height: 100%;
+  box-sizing: border-box;
+`
+
+/** Growing scroll region inside a panel column — stretch, never width: 100%. */
+export const flexPanelBodyCss = css`
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+  width: auto;
+  max-width: 100%;
+  align-self: stretch;
+  box-sizing: border-box;
+`
+
+/** Non-growing block inside a panel body (preview, header block, etc.). */
+export const flexPanelBlockCss = css`
+  flex: 0 0 auto;
+  min-width: 0;
+  width: auto;
+  max-width: 100%;
+  align-self: stretch;
+  box-sizing: border-box;
+`
+
+export const flexStyles = css<FlexStyleProps>`
+  display: flex;
+  flex: ${p => p.$flex ?? '0 0 auto'};
+  flex-direction: ${p => {
+    if (p.$row) return 'row'
+    if (p.$column) return 'column'
+    return 'row'
+  }};
+  flex-wrap: ${p => (p.$wrap ? 'wrap' : 'nowrap')};
+  align-items: ${p => (p.$align ? alignMap[p.$align] : 'inherit')};
+  justify-content: ${p => (p.$justify ? justifyMap[p.$justify] : 'inherit')};
+  gap: ${p => gapCss(p.$gap)};
+  width: ${p => p.$width ?? 'fit-content'};
+  height: ${p => p.$height ?? 'fit-content'};
+  min-height: ${p => p.$minHeight ?? 'auto'};
+  -webkit-app-region: ${p => (p.$noDrag ? 'no-drag' : 'inherit')};
+`
+
+export const Flex = styled.div<FlexStyleProps>`
+  ${flexStyles}
+`
+
+export const FlexRow = styled.div<FlexStyleProps>`
+  ${flexStyles}
+  flex-direction: row;
+  width: ${p => p.$width ?? '100%'};
+`
+
+export const FlexCol = styled.div<FlexStyleProps>`
+  ${flexStyles}
+  flex-direction: column;
+  min-width: 0;
+  box-sizing: border-box;
+  width: ${p => p.$width ?? 'auto'};
+  max-width: ${p => (p.$width ? 'none' : '100%')};
+  align-self: ${p => (p.$width ? 'auto' : 'stretch')};
+`

package/src/components/common/containers/useOpacityPresence.ts

@@ -0,0 +1,80 @@
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useState,
+  type TransitionEvent,
+} from 'react'
+
+export const OPACITY_PRESENCE_DURATION_MS = 200
+
+export type OpacityPresencePhase = 'hidden' | 'entering' | 'visible' | 'exiting'
+
+export interface OpacityPresence {
+  /** Apply display:none when false; subtree stays mounted. */
+  present: boolean
+  opacity: number
+  phase: OpacityPresencePhase
+  onTransitionEnd: (event: TransitionEvent<HTMLElement>) => void
+}
+
+/**
+ * Fade in/out via opacity; after fade-out completes, `present` is false for display:none.
+ * Unlike useOpenTransition (timeout + unmount), this waits for transitionend and keeps children mounted.
+ */
+export function useOpacityPresence(
+  active: boolean,
+): OpacityPresence {
+  const [phase, setPhase] = useState<OpacityPresencePhase>(() =>
+    active ? 'visible' : 'hidden',
+  )
+  const [opacity, setOpacity] = useState(() => (active ? 1 : 0))
+
+  useEffect(() => {
+    if (active) {
+      setPhase(prev => {
+        if (prev === 'hidden' || prev === 'exiting') {
+          setOpacity(0)
+          return 'entering'
+        }
+        return prev
+      })
+      return
+    }
+
+    setPhase(prev => {
+      if (prev === 'visible' || prev === 'entering') {
+        setOpacity(0)
+        return 'exiting'
+      }
+      return prev
+    })
+  }, [active])
+
+  useLayoutEffect(() => {
+    if (phase !== 'entering') return
+    const id = requestAnimationFrame(() => setOpacity(1))
+    return () => cancelAnimationFrame(id)
+  }, [phase])
+
+  const onTransitionEnd = useCallback(
+    (event: TransitionEvent<HTMLElement>) => {
+      if (event.target !== event.currentTarget) return
+      if (event.propertyName !== 'opacity') return
+
+      setPhase(prev => {
+        if (prev === 'exiting') return 'hidden'
+        if (prev === 'entering') return 'visible'
+        return prev
+      })
+    },
+    [],
+  )
+
+  return {
+    present: phase !== 'hidden',
+    opacity,
+    phase,
+    onTransitionEnd,
+  }
+}

package/src/components/common/containers/useOpenTransition.ts

@@ -1,33 +1,33 @@
-import { useEffect, useState } from 'react'
-
-/** Matches `--platform-transition-slow` (320ms). */
-export const COLLAPSIBLE_GRID_DURATION_MS = 320
-
-export interface OpenTransition {
-  mounted: boolean
-  expanded: boolean
-}
-
-export function useOpenTransition(
-  open: boolean,
-  durationMs: number = COLLAPSIBLE_GRID_DURATION_MS,
-): OpenTransition {
-  const [mounted, setMounted] = useState(open)
-  const [expanded, setExpanded] = useState(false)
-
-  useEffect(() => {
-    if (open) {
-      setMounted(true)
-      const raf = requestAnimationFrame(() => {
-        requestAnimationFrame(() => setExpanded(true))
-      })
-      return () => cancelAnimationFrame(raf)
-    }
-
-    setExpanded(false)
-    const timer = window.setTimeout(() => setMounted(false), durationMs)
-    return () => window.clearTimeout(timer)
-  }, [open, durationMs])
-
-  return { mounted, expanded }
-}
+import { useEffect, useState } from 'react'
+
+/** Matches `--platform-transition-slow` (320ms). */
+export const COLLAPSIBLE_GRID_DURATION_MS = 320
+
+export interface OpenTransition {
+  mounted: boolean
+  expanded: boolean
+}
+
+export function useOpenTransition(
+  open: boolean,
+  durationMs: number = COLLAPSIBLE_GRID_DURATION_MS,
+): OpenTransition {
+  const [mounted, setMounted] = useState(open)
+  const [expanded, setExpanded] = useState(false)
+
+  useEffect(() => {
+    if (open) {
+      setMounted(true)
+      const raf = requestAnimationFrame(() => {
+        requestAnimationFrame(() => setExpanded(true))
+      })
+      return () => cancelAnimationFrame(raf)
+    }
+
+    setExpanded(false)
+    const timer = window.setTimeout(() => setMounted(false), durationMs)
+    return () => window.clearTimeout(timer)
+  }, [open, durationMs])
+
+  return { mounted, expanded }
+}