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

package/src/components/common/buttons/Button.tsx

@@ -0,0 +1,241 @@
+import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from 'react'
+import { css, keyframes, styled } from 'styled-components'
+
+export type ButtonVariant =
+  | 'ghost'
+  | 'subtle'
+  | 'primary'
+  | 'danger'
+  | 'tile'
+  | 'text'
+export type ButtonSize = 'sm' | 'md'
+
+export interface ButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  variant?: ButtonVariant
+  size?: ButtonSize
+  selected?: boolean
+  fullWidth?: boolean
+  loading?: boolean
+  children: ReactNode
+}
+
+const spin = keyframes`
+  to { transform: rotate(360deg); }
+`
+
+const selectedCss = css`
+  background: var(--platform-colors-surface-hover);
+  border-color: var(
+    --platform-colors-border-strong,
+    var(--platform-colors-border)
+  );
+`
+
+const textSelectedCss = css`
+  background: transparent;
+  border-color: transparent;
+  color: var(--platform-colors-text);
+  text-decoration: underline;
+  text-underline-offset: 0.18em;
+`
+
+const variantStyles: Record<
+  Exclude<ButtonVariant, 'tile'>,
+  ReturnType<typeof css>
+> = {
+  ghost: css`
+    background: transparent;
+    border-color: transparent;
+    color: var(--platform-colors-text);
+
+    &:hover:not(:disabled) {
+      background: var(--platform-colors-surface-hover);
+    }
+  `,
+  subtle: css`
+    background: var(--platform-colors-surface);
+    border-color: var(--platform-colors-border);
+    color: var(--platform-colors-text);
+
+    &:hover:not(:disabled) {
+      background: var(--platform-colors-surface-hover);
+    }
+  `,
+  primary: css`
+    background: var(--platform-colors-text);
+    border-color: var(--platform-colors-text);
+    color: var(--platform-colors-text-inverse);
+
+    &:hover:not(:disabled) {
+      background: var(--platform-colors-text-secondary);
+      border-color: var(--platform-colors-text-secondary);
+    }
+  `,
+  danger: css`
+    background: var(--platform-colors-danger);
+    border-color: var(--platform-colors-danger);
+    color: var(--platform-colors-text-inverse);
+
+    &:hover:not(:disabled) {
+      filter: brightness(1.06);
+    }
+  `,
+  text: css`
+    background: transparent;
+    border-color: transparent;
+    color: var(--platform-colors-text-secondary);
+    text-decoration: none;
+
+    &:hover:not(:disabled) {
+      color: var(--platform-colors-text);
+      text-decoration: underline;
+      text-underline-offset: 0.18em;
+    }
+  `,
+}
+
+const tileCss = css`
+  flex-direction: column;
+  align-items: flex-start;
+  justify-content: flex-start;
+  gap: var(--platform-spacing-sm);
+  height: auto;
+  min-height: 72px;
+  padding: var(--platform-spacing-md);
+  text-align: left;
+  white-space: normal;
+  background: var(--platform-colors-surface);
+  border-color: var(--platform-colors-border);
+  color: inherit;
+
+  &:hover:not(:disabled) {
+    background: var(--platform-colors-surface-hover);
+  }
+`
+
+const sizeStyles: Record<ButtonSize, ReturnType<typeof css>> = {
+  sm: css`
+    height: 20px;
+    padding: 0 8px;
+    font-size: var(--platform-typography-font-size-sm);
+  `,
+  md: css`
+    height: 24px;
+    padding: 0 11px;
+    font-size: var(--platform-typography-font-size-base);
+  `,
+}
+
+const StyledSpinner = styled.span`
+  position: absolute;
+  width: 12px;
+  height: 12px;
+  border: 1.5px solid currentColor;
+  border-right-color: transparent;
+  border-radius: 50%;
+  animation: ${spin} 600ms linear infinite;
+`
+
+const StyledLabel = styled.span<{ $hidden: boolean }>`
+  display: inline-flex;
+  align-items: center;
+  gap: inherit;
+  visibility: ${({ $hidden }) => ($hidden ? 'hidden' : 'visible')};
+  line-height: 0.5;
+  font-size: var(--platform-typography-font-size-xs);
+`
+
+const StyledButton = styled.button<{
+  $variant: ButtonVariant
+  $size: ButtonSize
+  $selected: boolean
+  $fullWidth: boolean
+  $loading: boolean
+}>`
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  width: ${({ $fullWidth }) => ($fullWidth ? '100%' : 'fit-content')};
+  border: 1px solid transparent;
+  border-radius: 1rem;
+  font-size: var(--platform-typography);
+  line-height: 1;
+  white-space: nowrap;
+  cursor: pointer;
+  transition: background var(--platform-transition-fast),
+    border-color var(--platform-transition-fast),
+    color var(--platform-transition-fast),
+    filter var(--platform-transition-fast);
+
+  ${({ $variant, $size }) =>
+    $variant === 'tile' ? tileCss : sizeStyles[$size]}
+  ${({ $variant }) => ($variant === 'tile' ? '' : variantStyles[$variant])}
+  ${({ $variant }) =>
+    $variant === 'text'
+      ? css`
+          height: auto;
+          padding: 0;
+          border-radius: 0;
+        `
+      : ''}
+  ${({ $selected, $variant }) =>
+    $selected ? ($variant === 'text' ? textSelectedCss : selectedCss) : ''}
+
+  &:focus {
+    outline: none;
+  }
+
+  &:focus-visible {
+    outline: 1px solid
+      var(--platform-colors-border-strong, var(--platform-colors-border));
+    outline-offset: 2px;
+  }
+
+  &:disabled {
+    cursor: ${({ $loading }) => ($loading ? 'wait' : 'not-allowed')};
+    opacity: ${({ $loading, $variant }) =>
+      $loading || $variant === 'tile' ? 1 : 0.45};
+  }
+`
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  function Button(
+    {
+      variant = 'ghost',
+      size = 'md',
+      selected = false,
+      fullWidth = false,
+      loading = false,
+      type = 'button',
+      disabled = false,
+      children,
+      ...rest
+    },
+    ref,
+  ) {
+    const isDisabled = disabled || loading
+
+    return (
+      <StyledButton
+        ref={ref}
+        type={type}
+        disabled={isDisabled}
+        aria-busy={loading || undefined}
+        $variant={variant}
+        $size={size}
+        $selected={selected}
+        $fullWidth={fullWidth}
+        $loading={loading}
+        {...rest}
+      >
+        {loading ? <StyledSpinner aria-hidden="true" /> : null}
+        <StyledLabel $hidden={loading}>{children}</StyledLabel>
+      </StyledButton>
+    )
+  },
+)
+
+Button.displayName = 'Button'

package/src/components/common/buttons/ChoiceChip.tsx

@@ -0,0 +1,73 @@
+import { forwardRef, type ButtonHTMLAttributes } from 'react'
+import { styled } from 'styled-components'
+
+export interface ChoiceChipProps
+  extends ButtonHTMLAttributes<HTMLButtonElement> {
+  active?: boolean
+}
+
+//#region styled-components
+
+const StyledChip = styled.button<{ $active?: boolean }>`
+  min-height: 26px;
+  padding: 0 var(--platform-spacing-sm);
+  border: 1px solid
+    ${({ $active }) =>
+      $active
+        ? 'var(--platform-colors-border-strong, var(--platform-colors-border))'
+        : 'var(--platform-colors-border)'};
+  border-radius: var(--platform-radius-full);
+  background: ${({ $active }) =>
+    $active
+      ? 'var(--platform-colors-surface-hover)'
+      : 'var(--platform-colors-surface)'};
+  color: ${({ $active }) =>
+    $active
+      ? 'var(--platform-colors-text)'
+      : 'var(--platform-colors-text-secondary)'};
+  font: inherit;
+  font-size: var(--platform-typography-font-size-sm);
+  font-weight: var(--platform-typography-font-weight-medium);
+  cursor: pointer;
+
+  &:hover:not(:disabled) {
+    background: ${({ $active }) =>
+      $active
+        ? 'var(--platform-colors-surface-hover)'
+        : 'var(--platform-colors-surface-hover)'};
+    color: ${({ $active }) =>
+      $active ? 'var(--platform-colors-text)' : 'var(--platform-colors-text)'};
+  }
+
+  &:focus {
+    outline: none;
+  }
+
+  &:focus-visible {
+    outline: 1px solid
+      var(--platform-colors-border-strong, var(--platform-colors-border));
+    outline-offset: 2px;
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+`
+
+//#endregion
+
+/** Pill filter toggle — wrapping rows of selectable chips (see also SegmentedControl). */
+export const ChoiceChip = forwardRef<HTMLButtonElement, ChoiceChipProps>(
+  function ChoiceChip({ active = false, type = 'button', ...rest }, ref) {
+    return (
+      <StyledChip
+        ref={ref}
+        type={type}
+        $active={active}
+        aria-pressed={active}
+        {...rest}
+      />
+    )
+  },
+)

package/src/components/common/buttons/CleanButton.tsx

@@ -0,0 +1,34 @@
+import { styled } from 'styled-components'
+
+//#region styled-components
+
+export const CleanButton = styled.button`
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin: 0;
+  padding: 0;
+  border: none;
+  border-radius: 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  line-height: inherit;
+  outline: none;
+  cursor: pointer;
+  appearance: none;
+  -webkit-appearance: none;
+
+  &:disabled {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--platform-colors-focus-ring);
+    outline-offset: 2px;
+  }
+`
+
+//#endregion

package/src/components/common/buttons/IconButton.tsx

@@ -0,0 +1,89 @@
+import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from 'react'
+import { styled } from 'styled-components'
+
+export type IconButtonSize = 'sm' | 'md' | 'window'
+export type IconButtonVariant = 'ghost' | 'dangerHover'
+
+export interface IconButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  size?: IconButtonSize
+  variant?: IconButtonVariant
+  children: ReactNode
+}
+
+const sizeStyles: Record<IconButtonSize, { width: string; height: string }> = {
+  sm: { width: '26px', height: '26px' },
+  md: { width: '30px', height: '30px' },
+  window: { width: '30px', height: '30px' },
+}
+
+const StyledIconButton = styled.button<{
+  $size: IconButtonSize
+  $variant: IconButtonVariant
+}>`
+  display: grid;
+  place-items: center;
+  width: ${({ $size }) => sizeStyles[$size].width};
+  height: ${({ $size }) => sizeStyles[$size].height};
+  border: none;
+  border-radius: var(--platform-radius-sm);
+  background: transparent;
+  color: var(--platform-colors-text-secondary);
+  cursor: pointer;
+  transition: background var(--platform-transition-fast),
+    color var(--platform-transition-fast);
+
+  &:hover:not(:disabled) {
+    background: ${({ $variant }) =>
+      $variant === 'dangerHover'
+        ? 'var(--platform-colors-danger)'
+        : 'var(--platform-colors-surface-hover)'};
+    color: ${({ $variant }) =>
+      $variant === 'dangerHover'
+        ? 'var(--platform-colors-text-inverse)'
+        : 'var(--platform-colors-text)'};
+  }
+
+  &:focus {
+    outline: none;
+  }
+
+  &:focus-visible {
+    outline: 1px solid var(--platform-colors-border-strong);
+    outline-offset: 2px;
+  }
+
+  &:disabled {
+    opacity: 0.45;
+    cursor: not-allowed;
+  }
+`
+
+export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(
+  function IconButton(
+    {
+      size = 'sm',
+      variant = 'ghost',
+      type = 'button',
+      disabled = false,
+      children,
+      ...rest
+    },
+    ref,
+  ) {
+    return (
+      <StyledIconButton
+        ref={ref}
+        type={type}
+        disabled={disabled}
+        $size={size}
+        $variant={variant}
+        {...rest}
+      >
+        {children}
+      </StyledIconButton>
+    )
+  },
+)
+
+IconButton.displayName = 'IconButton'

package/src/components/common/buttons/QuietAction.tsx

@@ -0,0 +1,29 @@
+import { styled } from 'styled-components'
+
+/**
+ * The suite's quiet verb: an uppercase whisper that acts. Used for
+ * secondary actions in toolbars and kickers (export, notes, settings).
+ */
+export const QuietAction = styled.button`
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  font-size: 12px;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  opacity: 0.6;
+  cursor: pointer;
+  white-space: nowrap;
+
+  &:hover:not(:disabled) {
+    opacity: 1;
+  }
+
+  &:disabled {
+    opacity: 0.35;
+    cursor: default;
+  }
+`

package/src/components/common/buttons/SegmentedControl.tsx

@@ -0,0 +1,67 @@
+import { styled } from 'styled-components'
+
+export interface SegmentedControlOption<T extends string> {
+  value: T
+  label: React.ReactNode
+}
+
+export interface SegmentedControlProps<T extends string> {
+  options: readonly SegmentedControlOption<T>[]
+  value: T
+  onValueChange: (value: T) => void
+  'aria-label'?: string
+}
+
+//#region styled-components
+
+const StyledGroup = styled.div`
+  display: inline-flex;
+  gap: var(--platform-spacing-2xs, 4px);
+  padding: var(--platform-spacing-2xs, 4px);
+  border: 1px solid var(--platform-colors-border);
+  border-radius: var(--platform-radius-lg);
+  background: var(--platform-colors-surface-active);
+`
+
+const StyledSegment = styled.button<{ $active: boolean }>`
+  min-height: 30px;
+  padding: 0 var(--platform-spacing-sm);
+  border: 0;
+  border-radius: var(--platform-radius-md);
+  background: ${({ $active }) =>
+    $active ? 'var(--platform-colors-surface)' : 'transparent'};
+  color: ${({ $active }) =>
+    $active
+      ? 'var(--platform-colors-text)'
+      : 'var(--platform-colors-text-secondary)'};
+  font: inherit;
+  font-size: var(--platform-typography-font-size-sm);
+  font-weight: var(--platform-typography-font-weight-bold);
+  cursor: pointer;
+`
+
+//#endregion
+
+/** Exclusive choice toggle — a row of segments with one active value. */
+export function SegmentedControl<T extends string>({
+  options,
+  value,
+  onValueChange,
+  'aria-label': ariaLabel,
+}: SegmentedControlProps<T>): React.ReactElement {
+  return (
+    <StyledGroup role="group" aria-label={ariaLabel}>
+      {options.map(option => (
+        <StyledSegment
+          key={option.value}
+          type="button"
+          $active={option.value === value}
+          aria-pressed={option.value === value}
+          onClick={() => onValueChange(option.value)}
+        >
+          {option.label}
+        </StyledSegment>
+      ))}
+    </StyledGroup>
+  )
+}

package/src/components/common/buttons/TextActionButton.tsx

@@ -0,0 +1,55 @@
+import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from 'react'
+import { styled } from 'styled-components'
+
+export interface TextActionButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  children: ReactNode
+}
+
+const StyledTextActionButton = styled.button`
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: fit-content;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: var(--platform-colors-text-secondary);
+  font: inherit;
+  font-size: var(--platform-typography-font-size-xs);
+  font-weight: 500;
+  line-height: 1.2;
+  letter-spacing: 0;
+  text-decoration: none;
+  white-space: nowrap;
+  cursor: pointer;
+
+  &:hover:not(:disabled) {
+    color: var(--platform-colors-text);
+    text-decoration: underline;
+    text-underline-offset: 0.18em;
+  }
+
+  &:focus {
+    outline: none;
+  }
+
+  &:focus-visible {
+    outline: 1px solid var(--platform-colors-border-strong);
+    outline-offset: 2px;
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+    opacity: 0.45;
+  }
+`
+
+export const TextActionButton = forwardRef<
+  HTMLButtonElement,
+  TextActionButtonProps
+>(function TextActionButton({ type = 'button', ...rest }, ref) {
+  return <StyledTextActionButton ref={ref} type={type} {...rest} />
+})
+
+TextActionButton.displayName = 'TextActionButton'

package/src/components/common/buttons/TextLink.tsx

@@ -0,0 +1,38 @@
+import { styled } from 'styled-components'
+
+export interface TextLinkProps {
+  href: string
+  external?: boolean
+  children: React.ReactNode
+}
+
+//#region styled-components
+
+const StyledLink = styled.a`
+  color: var(--platform-colors-text);
+  font-size: var(--platform-typography-font-size-sm);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+
+  &:hover {
+    color: var(--platform-colors-accent);
+  }
+`
+
+//#endregion
+
+export function TextLink({
+  href,
+  external = true,
+  children,
+}: TextLinkProps): React.ReactElement {
+  return (
+    <StyledLink
+      href={href}
+      target={external ? '_blank' : undefined}
+      rel={external ? 'noreferrer' : undefined}
+    >
+      {children}
+    </StyledLink>
+  )
+}

package/src/components/common/canvas/CanvasElementFrame.test.tsx

@@ -0,0 +1,79 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { ServerStyleSheet } from 'styled-components'
+import { describe, expect, it } from 'vitest'
+import { CanvasElementFrame } from './CanvasElementFrame.js'
+
+const canvas = { w: 1280, h: 720 }
+const frame = { x: 128, y: 72, w: 320, h: 180 }
+
+describe('CanvasElementFrame', () => {
+  it('renders frame geometry and selected resize handles', () => {
+    const html = renderToStaticMarkup(
+      <CanvasElementFrame
+        canvas={canvas}
+        frame={frame}
+        label="body"
+        selected
+        onResizePointerDown={() => undefined}
+      />,
+    )
+
+    expect(html).toContain('data-canvas-element-frame="true"')
+    expect(html).toContain('data-canvas-selected="true"')
+    expect(html).toContain('role="button"')
+    expect(html).toContain('tabindex="0"')
+    expect(html).toContain('aria-label="body, selectable, selected"')
+    expect(html).toContain('aria-pressed="true"')
+    expect(html).toContain('left:10%')
+    expect(html).toContain('top:10%')
+    expect(html).toContain('width:25%')
+    expect(html).toContain('height:25%')
+    expect(html).toContain('Resize body nw')
+    expect(html).toContain('Resize body se')
+  })
+
+  it('marks read-only and disabled states without resize handles', () => {
+    const html = renderToStaticMarkup(
+      <CanvasElementFrame
+        canvas={canvas}
+        frame={frame}
+        label="image read-only"
+        selected
+        readOnly
+        disabled
+        onResizePointerDown={() => undefined}
+      />,
+    )
+
+    expect(html).toContain('data-canvas-read-only="true"')
+    expect(html).toContain('data-canvas-disabled="true"')
+    expect(html).toContain('tabindex="-1"')
+    expect(html).toContain('aria-disabled="true"')
+    expect(html).not.toContain('Resize image read-only')
+  })
+
+  it('uses high-contrast editor chrome for visible slot frames', () => {
+    const sheet = new ServerStyleSheet()
+    try {
+      renderToStaticMarkup(
+        sheet.collectStyles(
+          <CanvasElementFrame
+            canvas={canvas}
+            frame={frame}
+            label="title"
+            selected
+            onResizePointerDown={() => undefined}
+          />,
+        ),
+      )
+      const css = sheet.getStyleTags()
+
+      expect(css).toContain('z-index:20')
+      expect(css).toContain('border:2px solid')
+      expect(css).toContain('box-shadow')
+      expect(css).toContain('font-weight:760')
+    } finally {
+      sheet.seal()
+    }
+  })
+})