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

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

@@ -0,0 +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>
+  )
+}

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

@@ -0,0 +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>
+  )
+}

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

@@ -0,0 +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')};
+`

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

@@ -0,0 +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 }
+}

package/src/components/common/context/ContextSelector.tsx

@@ -0,0 +1,269 @@
+import { useEffect, useRef, useState } from 'react'
+import { styled } from 'styled-components'
+
+export type ContextSourceKind =
+  | 'knowledge'
+  | 'report'
+  | 'research'
+  | 'person'
+  | 'file'
+  | 'dataset'
+  | 'chart'
+  | 'note'
+
+export interface ContextOption {
+  id: string
+  title: string
+  meta?: string
+  kind: ContextSourceKind
+  description?: string
+}
+
+export interface ContextSelection extends ContextOption {
+  text?: string
+  href?: string
+  excerpts?: Array<{
+    title?: string
+    text: string
+    href?: string
+  }>
+}
+
+export interface ContextSelectorProps {
+  label?: string
+  options: ContextOption[]
+  selected: ContextSelection[]
+  loading?: boolean
+  emptyLabel?: string
+  onOpen?: () => void | Promise<void>
+  onSelect: (option: ContextOption) => void
+  onRemove: (id: string) => void
+  className?: string
+}
+
+const kindLabels: Record<ContextSourceKind, string> = {
+  knowledge: 'knowledge',
+  report: 'report',
+  research: 'research',
+  person: 'person',
+  file: 'file',
+  dataset: 'data',
+  chart: 'chart',
+  note: 'note',
+}
+
+const Shell = styled.div`
+  position: relative;
+  display: grid;
+  gap: 8px;
+`
+
+const TriggerRow = styled.div`
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+`
+
+const Trigger = styled.button`
+  min-height: 28px;
+  border: 0;
+  background: transparent;
+  padding: 0;
+  color: var(--platform-colors-text-secondary, #68717c);
+  font: inherit;
+  font-size: 13px;
+  font-weight: 750;
+  cursor: pointer;
+
+  &:hover,
+  &:focus-visible {
+    color: var(--platform-colors-text, #2e3338);
+    outline: none;
+  }
+`
+
+const Count = styled.span`
+  color: var(--platform-colors-text-tertiary, #9aa2ad);
+  font-size: 12px;
+`
+
+const Menu = styled.div`
+  position: absolute;
+  z-index: 6;
+  top: 34px;
+  left: 0;
+  right: 0;
+  display: grid;
+  gap: 4px;
+  max-height: min(360px, 70vh);
+  overflow: auto;
+  border: 1px solid rgb(46 51 56 / 12%);
+  border-radius: 8px;
+  background: rgb(255 254 250 / 96%);
+  box-shadow: 0 18px 48px rgb(46 51 56 / 12%);
+  padding: 6px;
+`
+
+const OptionButton = styled.button`
+  display: grid;
+  gap: 3px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  padding: 9px 10px;
+  color: var(--platform-colors-text, #2e3338);
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+
+  &:hover,
+  &:focus-visible {
+    background: rgb(46 51 56 / 6%);
+    outline: none;
+  }
+`
+
+const OptionTitle = styled.span`
+  font-size: 13px;
+  font-weight: 760;
+`
+
+const OptionMeta = styled.span`
+  color: var(--platform-colors-text-tertiary, #8f98a4);
+  font-size: 11px;
+  line-height: 1.35;
+`
+
+const SelectedList = styled.div`
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+`
+
+const SelectedChip = styled.span`
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  max-width: 100%;
+  border: 1px solid rgb(46 51 56 / 12%);
+  border-radius: 999px;
+  background: rgb(255 255 255 / 48%);
+  padding: 3px 7px;
+  color: var(--platform-colors-text-secondary, #68717c);
+  font-size: 12px;
+`
+
+const RemoveButton = styled.button`
+  border: 0;
+  background: transparent;
+  padding: 0;
+  color: var(--platform-colors-text-tertiary, #9aa2ad);
+  font: inherit;
+  cursor: pointer;
+`
+
+export function ContextSelector({
+  label = 'Use context',
+  options,
+  selected,
+  loading = false,
+  emptyLabel = 'No context available yet',
+  onOpen,
+  onSelect,
+  onRemove,
+  className,
+}: ContextSelectorProps): React.ReactElement {
+  const [open, setOpen] = useState(false)
+  const shellRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (!open) return undefined
+
+    const close = (): void => setOpen(false)
+    const onPointerDown = (event: MouseEvent): void => {
+      if (shellRef.current?.contains(event.target as Node)) return
+      close()
+    }
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key === 'Escape') close()
+    }
+
+    document.addEventListener('mousedown', onPointerDown)
+    document.addEventListener('keydown', onKeyDown)
+    return () => {
+      document.removeEventListener('mousedown', onPointerDown)
+      document.removeEventListener('keydown', onKeyDown)
+    }
+  }, [open])
+
+  async function toggleOpen(): Promise<void> {
+    if (open) {
+      setOpen(false)
+      return
+    }
+    setOpen(true)
+    await onOpen?.()
+  }
+
+  return (
+    <Shell ref={shellRef} className={className}>
+      <TriggerRow>
+        <Trigger type="button" onClick={() => void toggleOpen()}>
+          {label}
+        </Trigger>
+        <Count>
+          {selected.length
+            ? `${selected.length} selected`
+            : 'optional grounding'}
+        </Count>
+      </TriggerRow>
+      {selected.length ? (
+        <SelectedList>
+          {selected.map(item => (
+            <SelectedChip key={item.id}>
+              {item.title}
+              <OptionMeta>{kindLabels[item.kind]}</OptionMeta>
+              <RemoveButton
+                type="button"
+                aria-label={`Remove ${item.title}`}
+                onClick={() => onRemove(item.id)}
+              >
+                ×
+              </RemoveButton>
+            </SelectedChip>
+          ))}
+        </SelectedList>
+      ) : null}
+      {open ? (
+        <Menu>
+          {loading ? (
+            <OptionButton as="div">Loading context…</OptionButton>
+          ) : options.length ? (
+            options.map(option => (
+              <OptionButton
+                key={option.id}
+                type="button"
+                onClick={() => {
+                  onSelect(option)
+                  setOpen(false)
+                }}
+              >
+                <OptionTitle>{option.title}</OptionTitle>
+                <OptionMeta>
+                  {kindLabels[option.kind]}
+                  {option.meta ? ` · ${option.meta}` : ''}
+                </OptionMeta>
+                {option.description ? (
+                  <OptionMeta>{option.description}</OptionMeta>
+                ) : null}
+              </OptionButton>
+            ))
+          ) : (
+            <OptionButton as="div">{emptyLabel}</OptionButton>
+          )}
+        </Menu>
+      ) : null}
+    </Shell>
+  )
+}

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

@@ -0,0 +1,7 @@
+export {
+  ContextSelector,
+  type ContextOption,
+  type ContextSelection,
+  type ContextSelectorProps,
+  type ContextSourceKind,
+} from './ContextSelector.js'