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

package/src/components/common/media/ImageReferencePicker.tsx

@@ -0,0 +1,242 @@
+import { useRef, useState, type ClipboardEvent } from 'react'
+import { styled } from 'styled-components'
+import { QuietAction } from '../buttons/QuietAction.js'
+
+export interface ImageReference {
+  id: string
+  title: string
+  dataUrl: string
+  mimeType: string
+}
+
+export interface ImageReferencePickerProps {
+  label?: string
+  description?: string
+  variant?: 'standalone' | 'embedded'
+  references: ImageReference[]
+  onChange: (references: ImageReference[]) => void
+}
+
+const Wrap = styled.div<{ $variant: 'standalone' | 'embedded' }>`
+  display: grid;
+  gap: 10px;
+  padding-top: ${({ $variant }) => ($variant === 'embedded' ? '0' : '14px')};
+  border-top: ${({ $variant }) =>
+    $variant === 'embedded' ? '0' : '1px solid rgb(127 127 127 / 16%)'};
+  outline: none;
+
+  &:focus-within {
+    border-top-color: rgb(127 127 127 / 34%);
+  }
+`
+
+const Head = styled.div<{ $variant: 'standalone' | 'embedded' }>`
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 14px;
+  padding-top: ${({ $variant }) => ($variant === 'embedded' ? '10px' : '0')};
+  border-top: ${({ $variant }) =>
+    $variant === 'embedded' ? '1px solid rgb(127 127 127 / 12%)' : '0'};
+`
+
+const Label = styled.div`
+  color: rgb(104 112 123);
+  font-size: 12px;
+  font-weight: 800;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+`
+
+const Description = styled.p`
+  margin: 0;
+  max-width: 560px;
+  color: rgb(104 112 123);
+  font-size: 12.5px;
+  line-height: 1.45;
+`
+
+const Input = styled.input`
+  position: fixed;
+  inset: auto auto 0 0;
+  width: 1px;
+  height: 1px;
+  opacity: 0;
+  pointer-events: none;
+`
+
+const Grid = styled.div`
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(104px, 1fr));
+  gap: 10px;
+`
+
+const PasteTarget = styled.div`
+  min-height: 58px;
+  padding: 11px 13px;
+  border: 1px dashed rgb(127 127 127 / 28%);
+  border-radius: 7px;
+  color: rgb(104 112 123);
+  font-size: 13px;
+  line-height: 1.45;
+  background: rgb(255 255 255 / 26%);
+
+  &:focus {
+    border-color: rgb(127 127 127 / 48%);
+    outline: none;
+  }
+`
+
+const Tile = styled.figure`
+  display: grid;
+  gap: 7px;
+  margin: 0;
+`
+
+const Thumb = styled.img`
+  display: block;
+  width: 100%;
+  aspect-ratio: 16 / 10;
+  object-fit: cover;
+  border: 1px solid rgb(127 127 127 / 18%);
+  border-radius: 3px;
+  background: rgb(127 127 127 / 8%);
+`
+
+const Caption = styled.figcaption`
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  color: rgb(79 88 100);
+  font-size: 12px;
+  line-height: 1.25;
+
+  span {
+    min-width: 0;
+    overflow-wrap: anywhere;
+  }
+`
+
+function createReferenceId(): string {
+  if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+    return `image_ref_${crypto.randomUUID()}`
+  }
+  return `image_ref_${Math.random().toString(36).slice(2, 10)}`
+}
+
+function readImageFile(file: File): Promise<ImageReference> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader()
+    reader.onload = () => {
+      const dataUrl = typeof reader.result === 'string' ? reader.result : ''
+      if (!dataUrl) {
+        reject(new Error(`Could not read ${file.name}`))
+        return
+      }
+      resolve({
+        id: createReferenceId(),
+        title: file.name || 'Theme reference',
+        dataUrl,
+        mimeType: file.type || 'image/*',
+      })
+    }
+    reader.onerror = () => reject(reader.error ?? new Error('Read failed'))
+    reader.readAsDataURL(file)
+  })
+}
+
+export function ImageReferencePicker({
+  label = 'Theme references',
+  description = 'Attach images for typography, color, spacing, and design cues. They guide the look; they do not become slides unless you add them later.',
+  variant = 'standalone',
+  references,
+  onChange,
+}: ImageReferencePickerProps): React.ReactElement {
+  const inputRef = useRef<HTMLInputElement | null>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  const chooseImages = (): void => {
+    setError(null)
+    inputRef.current?.click()
+  }
+
+  const addFiles = async (files: FileList | null): Promise<void> => {
+    if (!files?.length) return
+    const images = Array.from(files).filter(file =>
+      file.type.startsWith('image/'),
+    )
+    if (!images.length) {
+      setError('Choose image files.')
+      return
+    }
+    try {
+      const next = await Promise.all(images.map(readImageFile))
+      onChange([...references, ...next])
+    } catch (readError) {
+      setError(readError instanceof Error ? readError.message : 'Read failed')
+    } finally {
+      if (inputRef.current) inputRef.current.value = ''
+    }
+  }
+
+  const pasteImages = (event: ClipboardEvent): void => {
+    const files = event.clipboardData.files
+    if (!files.length) return
+    const hasImage = Array.from(files).some(file =>
+      file.type.startsWith('image/'),
+    )
+    if (!hasImage) return
+    event.preventDefault()
+    void addFiles(files)
+  }
+
+  return (
+    <Wrap $variant={variant} onPaste={pasteImages}>
+      <Head $variant={variant}>
+        <div>
+          <Label>{label}</Label>
+          <Description>{description}</Description>
+        </div>
+        <QuietAction type="button" onClick={chooseImages}>
+          attach images
+        </QuietAction>
+      </Head>
+      <PasteTarget tabIndex={0}>
+        Paste images here, or attach them. They are used as visual references,
+        not slide content.
+      </PasteTarget>
+      <Input
+        ref={inputRef}
+        aria-label={label}
+        type="file"
+        accept="image/*"
+        multiple
+        onChange={event => void addFiles(event.currentTarget.files)}
+      />
+      {references.length ? (
+        <Grid>
+          {references.map(reference => (
+            <Tile key={reference.id}>
+              <Thumb src={reference.dataUrl} alt="" />
+              <Caption>
+                <span>{reference.title}</span>
+                <QuietAction
+                  type="button"
+                  onClick={() =>
+                    onChange(
+                      references.filter(item => item.id !== reference.id),
+                    )
+                  }
+                >
+                  remove
+                </QuietAction>
+              </Caption>
+            </Tile>
+          ))}
+        </Grid>
+      ) : null}
+      {error ? <Description>{error}</Description> : null}
+    </Wrap>
+  )
+}

package/src/components/common/menubar/MenuBar.tsx

@@ -0,0 +1,78 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { isMenuInteractionTarget } from '../dropdown/menuPortalConstants.js'
+import { styled } from 'styled-components'
+import { zi } from '../../../theme/themeVars.js'
+import { FlexRow } from '../containers/flex.js'
+import type { MenuActionItem, MenuBarProps } from '../dropdown/menuTypes.js'
+import { MenuBarTrigger } from './MenuBarTrigger.js'
+
+//#region styled-components
+
+const StyledMenuBar = styled.nav`
+  position: relative;
+  z-index: ${zi.appMenus};
+  display: flex;
+  align-items: center;
+  min-height: 28px;
+  -webkit-app-region: no-drag;
+  user-select: none;
+`
+
+//#endregion
+
+export function MenuBar({
+  sections,
+  onSelectItem,
+  'aria-label': ariaLabel = 'Application menu',
+}: MenuBarProps): React.ReactElement {
+  const menubarRef = useRef<HTMLElement>(null)
+  const [openSectionId, setOpenSectionId] = useState<string | null>(null)
+
+  const close = useCallback(() => setOpenSectionId(null), [])
+
+  useEffect(() => {
+    if (!openSectionId) return
+
+    const onPointerDown = (event: MouseEvent) => {
+      if (isMenuInteractionTarget(event.target)) return
+      close()
+    }
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') close()
+    }
+
+    document.addEventListener('mousedown', onPointerDown)
+    document.addEventListener('keydown', onKeyDown)
+    return () => {
+      document.removeEventListener('mousedown', onPointerDown)
+      document.removeEventListener('keydown', onKeyDown)
+    }
+  }, [openSectionId, close])
+
+  const handleSelect = useCallback(
+    (sectionId: string, item: MenuActionItem) => {
+      onSelectItem?.(sectionId, item)
+      close()
+    },
+    [onSelectItem, close],
+  )
+
+  return (
+    <StyledMenuBar ref={menubarRef} role="menubar" aria-label={ariaLabel}>
+      <FlexRow $align="center" $height="100%">
+        {sections.map(section => (
+          <MenuBarTrigger
+            key={section.id}
+            section={section}
+            menubarRef={menubarRef}
+            open={openSectionId === section.id}
+            onOpen={() => setOpenSectionId(section.id)}
+            onClose={close}
+            onSelectItem={item => handleSelect(section.id, item)}
+          />
+        ))}
+      </FlexRow>
+    </StyledMenuBar>
+  )
+}

package/src/components/common/menubar/MenuBarTrigger.tsx

@@ -0,0 +1,70 @@
+import { useRef } from 'react'
+import { styled } from 'styled-components'
+import { MenuDropdown } from '../dropdown/MenuDropdown.js'
+import type { RefObject } from 'react'
+import type {
+  MenuActionItem,
+  MenuBarTriggerProps,
+} from '../dropdown/menuTypes.js'
+
+export interface MenuBarTriggerComponentProps extends MenuBarTriggerProps {
+  menubarRef: RefObject<HTMLElement | null>
+  onSelectItem?: (item: MenuActionItem) => void
+  onClose: () => void
+}
+
+//#region styled-components
+
+const StyledTrigger = styled.button<{ $open: boolean }>`
+  padding: var(--platform-spacing-xs) var(--platform-spacing-sm);
+  border: none;
+  border-radius: 0;
+  background: ${p =>
+    p.$open ? 'var(--platform-colors-surface-hover)' : 'transparent'};
+  color: var(--platform-colors-text);
+  font-size: var(--platform-typography-font-size-base);
+  cursor: pointer;
+
+  &:hover {
+    background: var(--platform-colors-surface-hover);
+  }
+`
+
+//#endregion
+
+export function MenuBarTrigger({
+  section,
+  menubarRef,
+  open,
+  onOpen,
+  onSelectItem,
+  onClose,
+}: MenuBarTriggerComponentProps): React.ReactElement {
+  const triggerRef = useRef<HTMLButtonElement>(null)
+
+  return (
+    <>
+      <StyledTrigger
+        ref={triggerRef}
+        type="button"
+        role="menuitem"
+        data-platform-menu-trigger
+        aria-haspopup="menu"
+        aria-expanded={open}
+        $open={open}
+        onClick={() => (open ? onClose() : onOpen())}
+      >
+        {section.label}
+      </StyledTrigger>
+      <MenuDropdown
+        sectionId={section.id}
+        items={section.items}
+        open={open}
+        menubarRef={menubarRef}
+        triggerRef={triggerRef}
+        onSelectItem={onSelectItem}
+        onClose={onClose}
+      />
+    </>
+  )
+}

package/src/components/common/narrative/NarrativeMention.tsx

@@ -0,0 +1,74 @@
+import { styled } from 'styled-components'
+
+/**
+ * The suite's narrative-mention primitives: inline spans inside agent
+ * prose that stay live — hoverable for detail, clickable to act.
+ * Used by the briefing surfaces (mail narrative, the Desk, calendar).
+ *
+ * Theming flows through CSS variables with quiet fallbacks:
+ * --narrative-ink, --narrative-faint, --narrative-muted,
+ * --narrative-accent. Hosts set them (or inherit the defaults).
+ */
+
+export const MentionWrap = styled.span`
+  position: relative;
+  display: inline;
+`
+
+export const MentionButton = styled.button<{ $dim?: boolean }>`
+  display: inline;
+  padding: 0;
+  border: 0;
+  border-bottom: 1px solid var(--narrative-underline, rgba(127, 127, 127, 0.4));
+  background: transparent;
+  color: ${({ $dim }) =>
+    $dim ? 'var(--narrative-faint, #9aa2ad)' : 'var(--narrative-ink, inherit)'};
+  font: inherit;
+  font-weight: 500;
+  cursor: pointer;
+
+  &:hover {
+    border-bottom-color: var(--narrative-accent, currentColor);
+  }
+`
+
+export const MentionHoverCard = styled.span`
+  position: absolute;
+  top: calc(100% + 8px);
+  left: 0;
+  z-index: 30;
+  display: block;
+  min-width: 240px;
+  max-width: 330px;
+  padding: 12px 14px;
+  border: 1px solid rgba(127, 127, 127, 0.28);
+  border-radius: 6px;
+  background: var(--narrative-card, #fff);
+  box-shadow: 0 14px 34px rgba(38, 46, 55, 0.14);
+  font-size: 12px;
+  font-weight: 400;
+  line-height: 1.55;
+  white-space: normal;
+  text-align: left;
+`
+
+export const MentionHoverTitle = styled.span`
+  display: block;
+  color: var(--narrative-ink, inherit);
+  font-weight: 650;
+`
+
+export const MentionHoverLine = styled.span`
+  display: block;
+  margin-top: 3px;
+  color: var(--narrative-muted, #737b86);
+`
+
+export const MentionHoverNote = styled.span`
+  display: block;
+  margin-top: 8px;
+  padding-left: 8px;
+  border-left: 2px solid var(--narrative-accent, #525a65);
+  color: var(--narrative-muted, #737b86);
+  font-style: italic;
+`

package/src/components/common/navigation/PathBreadcrumbs.tsx

@@ -0,0 +1,78 @@
+import { Fragment } from 'react'
+import { styled } from 'styled-components'
+
+export interface PathBreadcrumbItem {
+  label: string
+  path: string
+}
+
+export interface PathBreadcrumbsProps {
+  items: PathBreadcrumbItem[]
+  onSelect: (path: string) => void
+  'aria-label'?: string
+  /** Keep crumbs on one line (toolbar headers). */
+  nowrap?: boolean
+}
+
+//#region styled-components
+
+const StyledNav = styled.nav<{ $nowrap?: boolean }>`
+  display: flex;
+  align-items: center;
+  flex-wrap: ${({ $nowrap }) => ($nowrap ? 'nowrap' : 'wrap')};
+  gap: var(--platform-spacing-xs);
+  min-width: 0;
+  overflow: hidden;
+`
+
+const StyledSep = styled.span`
+  flex: 0 0 auto;
+  color: var(--platform-colors-text-disabled);
+  font-size: var(--platform-typography-font-size-sm);
+  user-select: none;
+`
+
+const StyledCrumb = styled.button`
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: var(--platform-colors-accent);
+  font-size: var(--platform-typography-font-size-sm);
+  line-height: 1;
+  cursor: pointer;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  min-width: 0;
+
+  &:disabled {
+    color: var(--platform-colors-text);
+    cursor: default;
+  }
+`
+
+//#endregion
+
+export function PathBreadcrumbs({
+  items,
+  onSelect,
+  'aria-label': ariaLabel = 'Path',
+  nowrap = false,
+}: PathBreadcrumbsProps): React.ReactElement {
+  return (
+    <StyledNav aria-label={ariaLabel} $nowrap={nowrap}>
+      {items.map((item, index) => (
+        <Fragment key={item.path}>
+          {index > 0 ? <StyledSep aria-hidden="true">/</StyledSep> : null}
+          <StyledCrumb
+            type="button"
+            disabled={index === items.length - 1}
+            onClick={() => onSelect(item.path)}
+          >
+            {item.label}
+          </StyledCrumb>
+        </Fragment>
+      ))}
+    </StyledNav>
+  )
+}

package/src/components/common/navigation/UnderlineTabs.tsx

@@ -0,0 +1,83 @@
+import { Each } from '../render/Each.js'
+import { styled } from 'styled-components'
+
+export interface UnderlineTabItem {
+  id: string
+  label: React.ReactNode
+}
+
+export interface UnderlineTabsProps {
+  items: readonly UnderlineTabItem[]
+  activeId: string
+  onSelect: (id: string) => void
+  'aria-label'?: string
+}
+
+//#region styled-components
+
+const StyledTabs = styled.nav`
+  display: flex;
+  align-items: center;
+  gap: var(--platform-spacing-md);
+  min-width: 0;
+  overflow-x: auto;
+  scrollbar-width: none;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+`
+
+const StyledTab = styled.button<{ $active?: boolean }>`
+  border: 0;
+  border-bottom: 2px solid
+    ${({ $active }) =>
+      $active ? 'var(--platform-colors-accent)' : 'transparent'};
+  background: transparent;
+  color: ${({ $active }) =>
+    $active
+      ? 'var(--platform-colors-text)'
+      : 'var(--platform-colors-text-secondary)'};
+  font: inherit;
+  font-weight: ${({ $active }) =>
+    $active
+      ? 'var(--platform-typography-font-weight-bold)'
+      : 'var(--platform-typography-font-weight-medium)'};
+  padding: 6px 2px;
+  white-space: nowrap;
+  cursor: pointer;
+
+  &:hover {
+    color: var(--platform-colors-text);
+  }
+`
+
+//#endregion
+
+/** Underlined view switcher — a row of text tabs with an accent underline. */
+export function UnderlineTabs({
+  items,
+  activeId,
+  onSelect,
+  'aria-label': ariaLabel,
+}: UnderlineTabsProps): React.ReactElement {
+  function renderTab(item: UnderlineTabItem): React.ReactElement {
+    const active = item.id === activeId
+    return (
+      <StyledTab
+        type="button"
+        $active={active}
+        aria-current={active}
+        onClick={() => onSelect(item.id)}
+      >
+        {item.label}
+      </StyledTab>
+    )
+  }
+
+  return (
+    <StyledTabs aria-label={ariaLabel}>
+      <Each of={items} as={renderTab} />
+    </StyledTabs>
+  )
+}

package/src/components/common/overlays/InstallAppPromptDialog.tsx

@@ -0,0 +1,59 @@
+import { Button } from '../buttons/Button.js'
+import { FlexRow } from '../containers/flex.js'
+import { Text } from '../typography/Text.js'
+import { Modal } from './Modal.js'
+import { styled } from 'styled-components'
+
+const StyledDialogActions = styled(FlexRow)`
+  justify-content: flex-end;
+  margin-top: var(--platform-spacing-md);
+`
+
+export interface InstallAppPromptDialogProps {
+  appSlug: string | null
+  appName: string
+  entityLabel?: string
+  open: boolean
+  busy?: boolean
+  onClose: () => void
+  /** Pick a plugin folder (dev tree or `.pure.app` package) and install via shell. */
+  onChoosePackage: () => void
+}
+
+export function InstallAppPromptDialog({
+  appSlug,
+  appName,
+  entityLabel,
+  open,
+  busy = false,
+  onClose,
+  onChoosePackage,
+}: InstallAppPromptDialogProps): React.ReactElement | null {
+  if (!appSlug) return null
+
+  return (
+    <Modal open={open} onClose={onClose} title="App not installed" size="sm">
+      <Text as="p" size="sm" tone="secondary">
+        {entityLabel
+          ? `${appName} is required to create “${entityLabel}”.`
+          : `${appName} is not installed.`}{' '}
+        Install the plugin into your PureScience apps folder (for development,
+        choose the app directory from this repo or a <code>.pure.app</code>{' '}
+        package).
+      </Text>
+      <StyledDialogActions $gap="sm">
+        <Button variant="ghost" size="sm" disabled={busy} onClick={onClose}>
+          Cancel
+        </Button>
+        <Button
+          variant="primary"
+          size="sm"
+          disabled={busy}
+          onClick={onChoosePackage}
+        >
+          {busy ? 'Installing…' : 'Choose package folder…'}
+        </Button>
+      </StyledDialogActions>
+    </Modal>
+  )
+}