# Header Actions (`header-actions`) - SignalOS widget

> Header-bar action cluster: connection status, theme switch, sound toggle, notifications menu, and user profile menu.

- **Version:** 0.2.0
- **Kind:** widget · **Category:** layout
- **Install:** `npx shadcn@latest add @signalos/header-actions`
- **Registry dependencies (pulled automatically):** @signalos/tokens, @signalos/utils, @signalos/button, @signalos/popover, @signalos/tooltip
- **npm dependencies:** lucide-react@^1.7.0
- **Files installed:** `src/components/widgets/header-actions/HeaderActions.tsx`, `src/components/widgets/header-actions/HeaderActions.types.ts`

## Access

This is a private registry: pulling source requires a `SIGNALOS_REGISTRY_TOKEN`
(GitHub fine-grained PAT with read access to the signal-widgets repo) and an
`@signalos` entry in components.json `"registries"`. Previews and this document are public.

## Usage

```tsx
import HeaderActions from "@/components/widgets/header-actions/HeaderActions"
```

## Example

```tsx
import { useState } from "react"

import { HeaderActions } from "@/components/widgets/header-actions/HeaderActions"

export default function Example() {
  const [theme, setTheme] = useState<"light" | "dark">("light")

  return (
    <HeaderActions
      organizationLabel="Sample Managed Services - Health Care"
      connectionStatus="connected"
      theme={theme}
      onThemeChange={setTheme}
      notifications={[{ id: "n1", title: "New alert" }]}
      onNotificationSelect={(notification) => console.info(notification.id)}
      user={{ name: "Jane Doe", email: "jane@example.com" }}
      onSignOut={() => console.info("sign out")}
    />
  )
}
```

## Props

### `HeaderActionsConnectionStatus`

```ts
export type HeaderActionsConnectionStatus =
  "connected" | "connecting" | "disconnected"
```

### `HeaderActionsNotification`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` | yes | - |  |
| `title` | `string` | yes | - |  |
| `description` | `string \| undefined` | no | - |  |
| `timestamp` | `string \| undefined` | no | - |  |
| `read` | `boolean \| undefined` | no | - |  |

### `HeaderActionsUser`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | `string` | yes | - |  |
| `email` | `string \| undefined` | no | - |  |
| `avatarUrl` | `string \| null \| undefined` | no | - |  |

### `HeaderActionsProps`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `organizationLabel` | `string \| undefined` | no | - |  |
| `connectionStatus` | `HeaderActionsConnectionStatus \| undefined` | no | - | Realtime connection status. Omit to hide the indicator. |
| `showConnectionLabel` | `boolean \| undefined` | no | - | Shows the text label next to the connection indicator. |
| `theme` | `"light" \| "dark" \| undefined` | no | - | Current theme. Omit to hide the theme switch. |
| `onThemeChange` | `((theme: "light" \| "dark") => void) \| undefined` | no | - | Called when the theme switch is toggled. |
| `soundEnabled` | `boolean \| undefined` | no | - | Whether notification sounds are enabled. Omit to hide the sound toggle. |
| `onSoundEnabledChange` | `((enabled: boolean) => void) \| undefined` | no | - | Called when the sound toggle is pressed. |
| `notifications` | `HeaderActionsNotification[] \| undefined` | no | - | Notifications rendered inside the notifications popover. |
| `notificationsLoading` | `boolean \| undefined` | no | - | Loading state for the notifications popover content. |
| `onNotificationSelect` | `((notification: HeaderActionsNotification) => void) \| undefined` | no | - | Called when a notification row is selected. |
| `onNotificationsOpenChange` | `((open: boolean) => void) \| undefined` | no | - | Called whenever the notifications popover opens or closes. |
| `user` | `HeaderActionsUser \| null \| undefined` | no | - | Current user rendered inside the profile menu. Omit to hide the menu. |
| `userLoading` | `boolean \| undefined` | no | - | Loading state for the user avatar/profile menu. |
| `userMenuExtra` | `ReactNode` | no | - | Extra items rendered above sign out inside the profile menu. |
| `onSignOut` | `(() => void) \| undefined` | no | - | Called when "Sign out" is selected. |
| `isSigningOut` | `boolean \| undefined` | no | - | Disables the sign out action and shows a busy label. |
| `className` | `string \| undefined` | no | - | Additional Tailwind classes for the outer container. |
| `data-testid` | `string \| undefined` | no | - | Test identifier rendered as `data-testid` on the root element. |

## Changelog

# header-actions

## 0.2.0

- **Breaking:** rename the `testId` prop to `data-testid` to match the rest
  of the registry and the DOM attribute name.

## 0.1.2

- Use semantic status tokens (text-text-error, bg-bg-warning, border-border-*, bg-status-*) instead of raw palette scales so client theme overrides restyle status colors.


## 0.1.1

- Content sync fix to bring source in line with published registry payload.


## 0.1.0

- Initial release: cluster of header-bar action controls (connection status,
  theme switch, sound toggle, notifications menu, user profile menu). Extracted
  from the `app-shell2` scaffold's stray `components/Header1` folder into its
  own registry item with a single flat `HeaderActions.tsx` file.