bb.ui

The bb.ui plugin provides shared React components, pure helpers, and display contracts.

Purpose

bb.ui supplies one versioned component kit for first-party and external app plugins. It exposes code through module imports, so it declares no claims, surfaces, services, or host roles.

The kit owns reusable presentation primitives. Domain plugins own their data, routes, state, and replaceable surfaces.

Surfaces

bb.ui declares no surfaces. It cannot win or replace a host surface.

Services

bb.ui declares no services. Its helpers do not read a service token or keep shared state.

Exports

Plugins import the kit from @bb/ui. The root entry re-exports the stable groups below.

import type {
  ComponentPropsWithoutRef,
  ComponentType,
  CSSProperties,
  ReactNode,
} from "react";

export type UiProps = {
  className?: string;
  children?: ReactNode;
};

export type UiComponent<P extends object = UiProps> = ComponentType<P>;
export type NativeButtonProps = ComponentPropsWithoutRef<"button">;
export type NativeInputProps = ComponentPropsWithoutRef<"input">;
export type NativeTextareaProps = ComponentPropsWithoutRef<"textarea">;
export type StyleProps = { style?: CSSProperties };
export type DateRange = { from: Date; to?: Date };
export type DateMatcher = (date: Date) => boolean;
export type ChartConfig = Record<string, {
  label?: ReactNode;
  color?: string;
  icon?: ComponentType;
}>;
export type CarouselOptions = Record<string, unknown>;
export type CarouselApi = {
  scrollNext(): void;
  scrollPrev(): void;
  selectedScrollSnap(): number;
};
export type FormFieldRenderContext = {
  name: string;
  value: unknown;
  onChange(value: unknown): void;
  onBlur(): void;
  ref: unknown;
};

The kit forwards standard DOM props unless a contract below lists a narrower prop. Every controlled component calls its change callback after it accepts the new value.

Layout, status, and display

These exports build static content, status, and responsive layout.

Form controls

These exports keep input behavior controlled and keyboard accessible.

Menus, overlays, and feedback

These exports provide accessible overlays with controlled open state.

Navigation and data widgets

These exports support movement through records and presentation of structured values.

Domain-facing exports

These exports provide shared BB presentation behavior. They do not expose domain services.

Pure display helpers from @bb/ui/core

The core helper types remain available from @bb/ui/core.

Semantic links and code viewers

UrlLink keeps normal anchor behavior while applying the BB URL policy. FileLink carries a complete target, so it does not depend on ambient route state. SourceCode and Diff are module facades over the active Files renderer choice. The bb.files plugin owns the renderer surfaces and their replacement rules.

export type SourceCodeLineRange = { start: number; end: number };
export type CodeOverflowMode = "scroll" | "wrap";
export type DiffViewMode = "unified" | "split";

export interface SourceCodeProps {
  content: string;
  path: string;
  overflow?: CodeOverflowMode;
  highlightedLines?: SourceCodeLineRange | null;
  className?: string;
}

export interface DiffFileContent {
  path: string;
  content: string;
}

export interface DiffFullFileContents {
  old: DiffFileContent;
  new: DiffFileContent;
}

export interface DiffProps {
  patch: string;
  path: string;
  view?: DiffViewMode;
  overflow?: CodeOverflowMode;
  showLineNumbers?: boolean;
  experimental_fullFileContents?: DiffFullFileContents;
  className?: string;
}

export type LiveFileTarget =
  | { kind: "workspace"; environmentId: string; path: string }
  | { kind: "host"; hostId: string; path: string }
  | { kind: "thread-storage"; threadId: string; path: string };

export type FileLocation =
  | { kind: "line"; line: number; column: number | null }
  | { kind: "range"; startLine: number; endLine: number };

export interface FileOpenOptions {
  target: LiveFileTarget;
  location: FileLocation | null;
}

export type UrlLinkProps = Omit<
  ComponentPropsWithoutRef<"a">,
  "href"
> & { href: string };

export type FileLinkProps = Omit<
  ComponentPropsWithoutRef<"a">,
  "href" | "target"
> & {
  target: LiveFileTarget;
  location?: FileLocation | null;
};

export const UrlLink: UiComponent<UrlLinkProps>;
export const FileLink: UiComponent<FileLinkProps>;
export const SourceCode: UiComponent<SourceCodeProps>;
export const Diff: UiComponent<DiffProps>;
/** Deprecated alias. Use UrlLink. */
export const experimental_UrlLink: typeof UrlLink;
/** Deprecated alias. Use FileLink. */
export const experimental_FileLink: typeof FileLink;
/** Deprecated alias. Use SourceCode. */
export const experimental_SourceCode: typeof SourceCode;
/** Deprecated alias. Use Diff. */
export const experimental_Diff: typeof Diff;

The experimental_* names preserve old bundles during the alias window. New code uses the unprefixed names.

Provider execution pickers

These controlled facades use the active bb.providers directory. They keep the current provider, model, reasoning, tier, and permission reconciliation in one component contract.

export type ProviderPickerRouting =
  | { kind: "host"; hostId: string }
  | { kind: "environment"; environmentId: string };

export interface ProviderPickerValue {
  providerId: string;
  model: string;
  reasoningLevel: string;
  serviceTier?: string;
}

export interface ProviderModelPickerProps {
  value: ProviderPickerValue;
  onChange(value: ProviderPickerValue): void;
  routing?: ProviderPickerRouting;
  allowProviderChange?: boolean;
  align?: "start" | "center" | "end";
  disabled?: boolean;
  className?: string;
}

export interface PermissionModePickerProps {
  providerId: string;
  value: string;
  onChange(value: string): void;
  routing?: ProviderPickerRouting;
  align?: "start" | "center" | "end";
  disabled?: boolean;
  className?: string;
}

export const ProviderModelPicker: UiComponent<ProviderModelPickerProps>;
export const PermissionModePicker: UiComponent<PermissionModePickerProps>;

The pickers use the Providers app adapter and the Workspace route identity. They do not own provider records or workspace state. The old experimental_ exports remain aliases during migration.

Host roles

bb.ui declares no host roles. Its code runs in the app module graph and uses no server or daemon artifact.

Example

This plugin uses bb.ui imports inside its own page. It owns the page data and action handlers.

import {
  Alert,
  Button,
  Card,
  CardContent,
  FileLink,
  Input,
  SourceCode,
  extractErrorMessage,
  formatEnvironmentDisplay,
} from "@bb/ui";

type AuditProps = {
  environment: Environment;
  target: {
    kind: "workspace";
    environmentId: string;
    path: string;
  };
  source: string;
  onSearch(value: string): void;
  onRefresh(): void;
  error: unknown;
};

export function AuditPanel(props: AuditProps) {
  const display = formatEnvironmentDisplay({
    environment: props.environment,
    host: { locality: "local", identity: null },
  });
  const errorMessage = extractErrorMessage(props.error);

  return (
    <Card>
      <CardContent className="space-y-3">
        <div>{display.modeLabel}</div>
        <Input
          aria-label="Search audit text"
          onChange={(event) => props.onSearch(event.currentTarget.value)}
        />
        <FileLink target={props.target} location={{ kind: "line", line: 1, column: null }}>
          Open source file
        </FileLink>
        <SourceCode path={props.target.path} content={props.source} />
        {errorMessage ? <Alert variant="destructive">{errorMessage}</Alert> : null}
        <Button onClick={props.onRefresh}>Refresh</Button>
      </CardContent>
    </Card>
  );
}

The example imports concrete code. It does not claim bb.ui or replace a surface.

Covers

The following table covers every item assigned to this page. Thread-selected host components and their types stay with bb.threads and do not appear here.