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

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

@@ -0,0 +1,60 @@
+import { styled } from 'styled-components'
+import { PureAppWordmark } from '../../chrome/PureAppWordmark.js'
+import type { PlatformAppManifest } from '../../../bridge/types.js'
+
+export type { PlatformAppManifest }
+
+export interface AppHeaderProps {
+  manifest: PlatformAppManifest
+  /** Optional slot for the app's tools — the header earns its row. */
+  actions?: React.ReactNode
+}
+
+/**
+ * Slim functional app header: the elegant lockup at the left (identity), the
+ * app's tools at the right. A wordmark with no tools doesn't deserve a bar —
+ * apps with nothing to host should render no header at all (identity already
+ * lives in the shell tab).
+ */
+const StyledHeader = styled.header`
+  display: flex;
+  align-items: center;
+  gap: var(--platform-spacing-md, 16px);
+  padding: 0 14px;
+  height: 36px;
+  flex: 0 0 auto;
+  border-bottom: 1px solid var(--platform-colors-divider);
+  background: var(--platform-colors-chrome-titlebar);
+`
+
+const ActionSlot = styled.div`
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  min-width: 0;
+  margin-left: auto;
+
+  &[data-layout='document-tools'] {
+    flex: 1;
+    justify-content: center;
+    margin-left: 0;
+  }
+`
+
+export const APP_HEADER_ACTIONS_PORTAL_ID = 'purescience-app-header-actions'
+
+export function AppHeader({
+  manifest,
+  actions,
+}: AppHeaderProps): React.ReactElement {
+  return (
+    <StyledHeader>
+      <PureAppWordmark
+        appName={manifest.navigationLabel ?? manifest.slug}
+        size="sm"
+        accentName
+      />
+      <ActionSlot id={APP_HEADER_ACTIONS_PORTAL_ID}>{actions}</ActionSlot>
+    </StyledHeader>
+  )
+}

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

@@ -0,0 +1,37 @@
+import type { SpacingToken } from './flex.js'
+import { styled } from 'styled-components'
+
+export interface AutoFillGridProps {
+  children: React.ReactNode
+  minColumnWidth?: number
+  gap?: SpacingToken
+}
+
+//#region styled-components
+
+const StyledGrid = styled.div<{
+  $minColumnWidth: number
+  $gap: SpacingToken
+}>`
+  display: grid;
+  grid-template-columns: repeat(
+    auto-fill,
+    minmax(${({ $minColumnWidth }) => $minColumnWidth}px, 1fr)
+  );
+  gap: ${({ $gap }) => `var(--platform-spacing-${$gap})`};
+  width: 100%;
+`
+
+//#endregion
+
+export function AutoFillGrid({
+  children,
+  minColumnWidth = 220,
+  gap = 'md',
+}: AutoFillGridProps): React.ReactElement {
+  return (
+    <StyledGrid $minColumnWidth={minColumnWidth} $gap={gap}>
+      {children}
+    </StyledGrid>
+  )
+}

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

@@ -0,0 +1,43 @@
+import { styled } from 'styled-components'
+
+export interface CollapsibleProps {
+  open: boolean
+  children: React.ReactNode
+  className?: string
+}
+
+//#region styled-components
+
+const StyledBody = styled.div`
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows var(--platform-transition-base);
+  min-width: 0;
+  width: auto;
+  max-width: 100%;
+  align-self: stretch;
+  box-sizing: border-box;
+
+  &[data-open='true'] {
+    grid-template-rows: 1fr;
+  }
+`
+
+const StyledInner = styled.div`
+  overflow: hidden;
+  min-width: 0;
+`
+
+//#endregion
+
+export function Collapsible({
+  open,
+  children,
+  className,
+}: CollapsibleProps): React.ReactElement {
+  return (
+    <StyledBody data-open={String(open)} className={className}>
+      <StyledInner>{children}</StyledInner>
+    </StyledBody>
+  )
+}

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

@@ -0,0 +1,174 @@
+import {
+  forwardRef,
+  type ComponentPropsWithoutRef,
+  type CSSProperties,
+} from 'react'
+import { styled } from 'styled-components'
+import {
+  COLLAPSIBLE_GRID_DURATION_MS,
+  useOpenTransition,
+} from './useOpenTransition.js'
+
+export { COLLAPSIBLE_GRID_DURATION_MS } from './useOpenTransition.js'
+
+export type CollapsibleAnimationDirection = 'x' | 'y' | 'xy'
+
+//#region styled-components
+
+const StyledRoot = styled.div<{ $indent?: boolean }>`
+  --collapsible-grid-duration: ${COLLAPSIBLE_GRID_DURATION_MS}ms;
+  --collapsible-grid-easing: ease;
+  --collapsible-grid-track-closed: 0fr;
+  --collapsible-grid-track-open: 1fr;
+
+  position: relative;
+  z-index: var(--platform-z-index-zi-app-menus);
+  display: grid;
+  width: auto;
+  padding-left: ${p =>
+    p.$indent === false ? 0 : 'var(--platform-spacing-sm)'};
+  transition: grid-template-rows var(--collapsible-grid-duration)
+      var(--collapsible-grid-easing),
+    grid-template-columns var(--collapsible-grid-duration)
+      var(--collapsible-grid-easing),
+    padding-block var(--collapsible-grid-duration)
+      var(--collapsible-grid-easing),
+    padding-inline var(--collapsible-grid-duration)
+      var(--collapsible-grid-easing);
+
+  * {
+    transition: all 0.2s ease;
+  }
+
+  &[data-open='true'] {
+    z-index: calc(var(--platform-z-index-zi-app-menus) + 1);
+
+    * {
+      opacity: 1;
+    }
+  }
+
+  &[data-open='false'] {
+    * {
+      opacity: 0;
+    }
+    /* border-color: transparent !important; */
+  }
+
+  &[data-animation-direction='y'] {
+    width: 100%;
+    grid-template-rows: var(--collapsible-grid-track-closed);
+    grid-template-columns: minmax(0, 1fr);
+
+    &[data-open='true'] {
+      grid-template-rows: var(--collapsible-grid-track-open);
+    }
+
+    &[data-open='false'] {
+      padding-block: 0 !important;
+    }
+
+    & > .content {
+      min-height: 0;
+    }
+  }
+
+  &[data-animation-direction='x'] {
+    width: auto;
+    grid-template-columns: var(--collapsible-grid-track-closed);
+    grid-template-rows: auto;
+
+    &[data-open='true'] {
+      grid-template-columns: var(--collapsible-grid-track-open);
+    }
+
+    &[data-open='false'] {
+      padding-inline: 0 !important;
+    }
+
+    & > .content {
+      min-width: 0;
+    }
+
+    & > .content > * {
+      width: max-content;
+    }
+  }
+
+  &[data-animation-direction='xy'] {
+    width: auto;
+    grid-template-rows: var(--collapsible-grid-track-closed);
+    grid-template-columns: var(--collapsible-grid-track-closed);
+
+    &[data-open='true'] {
+      grid-template-rows: var(--collapsible-grid-track-open);
+      grid-template-columns: var(--collapsible-grid-track-open);
+    }
+
+    &[data-open='false'] {
+      padding-block: 0 !important;
+      padding-inline: 0 !important;
+    }
+
+    & > .content {
+      min-height: 0;
+      min-width: 0;
+    }
+
+    & > .content > * {
+      width: max-content;
+      height: max-content;
+    }
+  }
+
+  & > .content {
+    overflow: hidden;
+  }
+`
+
+//#endregion
+
+export type CollapsibleGridProps = {
+  open: boolean
+  animationDirection?: CollapsibleAnimationDirection
+  /** When false, no left indent (e.g. top-level dropdown panel). Default true. */
+  indent?: boolean
+  durationMs?: number
+} & ComponentPropsWithoutRef<'div'>
+
+export const CollapsibleGrid = forwardRef<HTMLDivElement, CollapsibleGridProps>(
+  function CollapsibleGrid(
+    {
+      open,
+      animationDirection = 'y',
+      indent = true,
+      durationMs = COLLAPSIBLE_GRID_DURATION_MS,
+      children,
+      style,
+      ...rest
+    },
+    ref,
+  ) {
+    const { mounted, expanded } = useOpenTransition(open, durationMs)
+
+    const gridStyle = {
+      '--collapsible-grid-duration': `${durationMs}ms`,
+      ...style,
+    } as CSSProperties
+
+    if (!mounted) return null
+
+    return (
+      <StyledRoot
+        ref={ref}
+        data-open={expanded}
+        data-animation-direction={animationDirection}
+        $indent={indent}
+        style={gridStyle}
+        {...rest}
+      >
+        <div className="content">{children}</div>
+      </StyledRoot>
+    )
+  },
+)

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

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react'
+import { styled } from 'styled-components'
+
+export interface MotionScopeProps {
+  children: ReactNode
+  className?: string
+}
+
+//#region styled-components
+
+const StyledScope = styled.div`
+  display: contents;
+
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      animation-duration: 1ms !important;
+      scroll-behavior: auto !important;
+      transition-duration: 1ms !important;
+    }
+  }
+`
+
+//#endregion
+
+export function MotionScope({
+  children,
+  className,
+}: MotionScopeProps): React.ReactElement {
+  return <StyledScope className={className}>{children}</StyledScope>
+}

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

@@ -0,0 +1,35 @@
+import { FlexCol, FlexRow } from './flex.js'
+import { Heading } from '../typography/Heading.js'
+import { Kicker } from '../typography/Kicker.js'
+import { Text } from '../typography/Text.js'
+
+export interface PageHeaderProps {
+  title: string
+  description?: string
+  kicker?: string
+  actions?: React.ReactNode
+}
+
+export function PageHeader({
+  title,
+  description,
+  kicker,
+  actions,
+}: PageHeaderProps): React.ReactElement {
+  return (
+    <header style={{ maxWidth: '48rem', width: '100%' }}>
+      <FlexRow $justify="between" $align="start" $gap="md">
+        <FlexCol $gap="xs">
+          {kicker ? <Kicker>{kicker}</Kicker> : null}
+          <Heading level={1}>{title}</Heading>
+          {description ? (
+            <Text as="p" tone="secondary">
+              {description}
+            </Text>
+          ) : null}
+        </FlexCol>
+        {actions ? <FlexRow $flex="0 0 auto">{actions}</FlexRow> : null}
+      </FlexRow>
+    </header>
+  )
+}

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

@@ -0,0 +1,113 @@
+import { styled } from 'styled-components'
+import { FlexRow } from './flex.js'
+import { Kicker } from '../typography/Kicker.js'
+
+export interface PanelToolbarHeaderProps {
+  /** Uppercase label row — used when `children` is omitted (e.g. Locations). */
+  kicker?: string
+  subtitle?: React.ReactNode
+  /** Left slot — icon buttons, navigation, etc. */
+  leading?: React.ReactNode
+  /** Growing center slot — search field, custom toolbar content. */
+  children?: React.ReactNode
+  /** Right slot — badges, icon actions. */
+  actions?: React.ReactNode
+  /** Optional second row below the main toolbar (e.g. breadcrumbs). */
+  footer?: React.ReactNode
+}
+
+//#region styled-components
+
+const StyledWrap = styled.div`
+  flex: 0 0 auto;
+  border-bottom: 1px solid var(--platform-colors-border);
+  background: var(--platform-colors-surface);
+`
+
+const StyledRow = styled.div`
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--platform-spacing-sm);
+  min-height: 37px;
+  padding: 0 var(--platform-spacing-sm);
+`
+
+const StyledLeading = styled(FlexRow)`
+  min-width: 0;
+  flex: 1 1 auto;
+  overflow: hidden;
+`
+
+const StyledCenter = styled.div`
+  display: flex;
+  align-items: center;
+  min-width: 0;
+  flex: 1 1 auto;
+`
+
+const StyledTitleSep = styled.span`
+  flex: 0 0 auto;
+  color: var(--platform-colors-text-disabled);
+  font-size: var(--platform-typography-font-size-sm);
+  line-height: 1;
+  user-select: none;
+`
+
+const StyledActions = styled(FlexRow)`
+  flex: 0 0 auto;
+  min-width: 0;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+`
+
+const StyledFooter = styled.div`
+  padding: 0 var(--platform-spacing-md) var(--platform-spacing-xs);
+`
+
+//#endregion
+
+/** Panel chrome — kicker row or custom leading / center / actions layout. */
+export function PanelToolbarHeader({
+  kicker,
+  subtitle,
+  leading,
+  children,
+  actions,
+  footer,
+}: PanelToolbarHeaderProps): React.ReactElement {
+  const useCustomLayout = Boolean(children || leading)
+
+  return (
+    <StyledWrap>
+      <StyledRow>
+        {useCustomLayout ? (
+          <>
+            {leading ? (
+              <FlexRow $align="center" $gap="xs" $width="auto" $flex="0 0 auto">
+                {leading}
+              </FlexRow>
+            ) : null}
+            {children ? <StyledCenter>{children}</StyledCenter> : null}
+          </>
+        ) : (
+          <StyledLeading $align="center" $gap="xs" $width="auto">
+            {kicker ? <Kicker inline>{kicker}</Kicker> : null}
+            {subtitle ? (
+              <>
+                <StyledTitleSep aria-hidden="true">/</StyledTitleSep>
+                {subtitle}
+              </>
+            ) : null}
+          </StyledLeading>
+        )}
+        {actions ? (
+          <StyledActions $align="center" $gap="xs" $width="auto">
+            {actions}
+          </StyledActions>
+        ) : null}
+      </StyledRow>
+      {footer ? <StyledFooter>{footer}</StyledFooter> : null}
+    </StyledWrap>
+  )
+}

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

@@ -0,0 +1,91 @@
+import type { ReactNode } from 'react'
+import { styled } from 'styled-components'
+
+export interface QuietDisclosureProps {
+  summary: ReactNode
+  children: ReactNode
+  className?: string
+  defaultOpen?: boolean
+  open?: boolean
+  'aria-label'?: string
+}
+
+//#region styled-components
+
+const StyledDetails = styled.details`
+  border-top: 1px solid var(--platform-colors-divider);
+  padding-top: 14px;
+  transition: border-color var(--platform-transition-base),
+    padding var(--platform-transition-base);
+
+  &[open] {
+    padding-bottom: var(--platform-spacing-sm);
+  }
+
+  &[open] > div {
+    animation: quiet-disclosure-enter 240ms ease both;
+  }
+
+  @keyframes quiet-disclosure-enter {
+    from {
+      opacity: 0;
+      transform: translateY(-4px);
+    }
+
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+`
+
+const StyledSummary = styled.summary`
+  cursor: pointer;
+  color: var(--platform-colors-text-secondary);
+  font-size: var(--platform-typography-font-size-xs);
+  font-weight: 720;
+  letter-spacing: 0.08em;
+  list-style: none;
+  text-transform: uppercase;
+
+  &::-webkit-details-marker {
+    display: none;
+  }
+
+  &::after {
+    content: '+';
+    margin-left: var(--platform-spacing-sm);
+    color: var(--quiet-accent, var(--platform-colors-accent));
+    transition: color var(--platform-transition-base);
+  }
+
+  details[open] &::after {
+    content: '-';
+  }
+`
+
+const StyledBody = styled.div`
+  min-width: 0;
+`
+
+//#endregion
+
+export function QuietDisclosure({
+  summary,
+  children,
+  className,
+  defaultOpen,
+  open,
+  'aria-label': ariaLabel,
+}: QuietDisclosureProps): React.ReactElement {
+  return (
+    <StyledDetails
+      className={className}
+      open={open ?? defaultOpen}
+      aria-label={ariaLabel}
+    >
+      <StyledSummary>{summary}</StyledSummary>
+      <StyledBody>{children}</StyledBody>
+    </StyledDetails>
+  )
+}

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

@@ -0,0 +1,41 @@
+import type { ReactNode } from 'react'
+import { styled } from 'styled-components'
+
+export interface QuietSurfaceProps {
+  children: ReactNode
+  className?: string
+}
+
+//#region styled-components
+
+const StyledSurface = styled.div`
+  display: grid;
+  gap: var(--platform-spacing-md);
+  min-width: 0;
+  border: 1px solid
+    rgb(from var(--quiet-ink, var(--platform-colors-text)) r g b / 10%);
+  border-radius: var(--platform-radius-md);
+  background: rgb(255 255 255 / 58%);
+  box-shadow: 0 16px 42px rgb(31 38 52 / 5%);
+  padding: clamp(20px, 3vw, 34px);
+  transition: border-color var(--platform-transition-base),
+    box-shadow var(--platform-transition-base),
+    transform var(--platform-transition-base),
+    background var(--platform-transition-base);
+
+  &:focus-within {
+    border-color: rgb(
+      from var(--quiet-accent, var(--platform-colors-accent)) r g b / 28%
+    );
+    box-shadow: 0 20px 54px rgb(31 38 52 / 8%);
+  }
+`
+
+//#endregion
+
+export function QuietSurface({
+  children,
+  className,
+}: QuietSurfaceProps): React.ReactElement {
+  return <StyledSurface className={className}>{children}</StyledSurface>
+}

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

@@ -0,0 +1,33 @@
+import type { ComponentPropsWithoutRef } from 'react'
+import { FlexCol, flexPanelBodyCss, type SpacingToken } from './flex.js'
+import { styled } from 'styled-components'
+
+export interface ScrollPanelProps extends ComponentPropsWithoutRef<'div'> {
+  children: React.ReactNode
+  padding?: SpacingToken
+}
+
+//#region styled-components
+
+const StyledScrollPanel = styled(FlexCol)<{ $padding: SpacingToken }>`
+  ${flexPanelBodyCss}
+  overflow: auto;
+  padding: var(
+    --platform-modal-inset,
+    var(--platform-spacing-${({ $padding }) => $padding})
+  );
+`
+
+//#endregion
+
+export function ScrollPanel({
+  children,
+  padding = 'xl',
+  ...rest
+}: ScrollPanelProps): React.ReactElement {
+  return (
+    <StyledScrollPanel $padding={padding} {...rest}>
+      {children}
+    </StyledScrollPanel>
+  )
+}

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

@@ -0,0 +1,42 @@
+import { styled } from 'styled-components'
+
+export interface StatusBarProps {
+  status: string
+  meta?: string
+}
+
+const StyledStatusBar = styled.footer`
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  border-top: 1px solid var(--platform-colors-divider);
+  color: var(--platform-colors-text-secondary);
+  flex-shrink: 0;
+  font-size: var(--platform-typography-font-size-xs, 11px);
+  min-height: 26px;
+  padding: 4px 12px;
+`
+
+const StyledStatusMessage = styled.span`
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+`
+
+const StyledStatusMeta = styled.span`
+  flex-shrink: 0;
+  white-space: nowrap;
+`
+
+export function StatusBar({
+  status,
+  meta,
+}: StatusBarProps): React.ReactElement {
+  return (
+    <StyledStatusBar>
+      <StyledStatusMessage>{status}</StyledStatusMessage>
+      {meta ? <StyledStatusMeta>{meta}</StyledStatusMeta> : null}
+    </StyledStatusBar>
+  )
+}