@brdgapp/ui 0.1.2 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+Every release of `@brdgapp/ui`. Versions follow the rules in README.md → Versions.
+
+## 1.0.0
+
+The first release of Bridge's design system as a package. A new major version: the 0.1.x releases
+(NetworkPeopleHelper, BridgeUIProvider) are not part of it. Apps using them stay on 0.1.2 until they move
+those parts into their own code.
+
+- Tokens: every Bridge role token in light and dark, three shadow levels, glass, dot-grid and noise
+  utilities, and base styles (`globals.css`).
+- Components: ActionMenu, Avatar, Badge, BottomSheet, BrandMark, Button, ButtonGroup, Card (with CardHeader, CardMedia and CardFooter), Checkbox (with CheckboxGroup), Collapsible, HoverCard, Illustration, NetworkGraph, Scene, ColumnFilterMenu, ColumnSortButton, ConfirmDialog,
+  CopyField, DataState, DataTable, Dialog, Drawer, ExpandableBio, Field (with FieldLabel, FieldDescription,
+  FieldError and FieldGroup), FilterChip, FilterPill, IconButton, InfoHint (with HoverTip and Tip), Input,
+  PageBanner, SearchInput, SegmentedControl, Skeleton, SkipLink, StatBox, Switch, Tabs, ThemeSwitch, Tag, TagInput, Textarea, Toast.
+- Needs React 19 and Tailwind 4 (the components take `ref` as a prop and use `inert`, which React 18 ignores).
+- Built on Base UI. Each component's handbook page notes how it relates to Bridge OS's own version.
+- Avatar shows a person's photo, or their initials on light blue, in six sizes (16 to 64px), with an
+  optional badge: Bridge member, Super Connector or warning. A photo that fails to load falls back to
+  the initials. AvatarGroup stacks the first faces and counts the rest ("+4").
+- Textarea starts 3 lines tall, grows with the text up to 10, then scrolls. With `maxLength` it shows a
+  count under the box that turns red near the limit.
+- Checkbox is 16px with a 28px click area, can be part-ticked for "Select all", and takes a `label` and
+  `description`. CheckboxGroup holds a list of ticked options.
+- Collapsible opens and closes a section in two looks (`section`, `inline`), sliding open in 200ms.
+- BrandMark draws the company logos Bridge shows (LinkedIn, Google, Microsoft, Apple, WhatsApp, Telegram,
+  Chrome) at icon size, in their own colors; LinkedIn, WhatsApp and Telegram can be one color. Lucide 1.x has no logos.
+- Illustration draws thirteen small scenes for empty states (people, intros, companies, messages, activity,
+  meetings, lists, jobs, connect, search, filters, done, error) in tokens, so they follow dark mode. DataState's
+  empty state takes `illustration` in place of `icon`.
+- NetworkGraph shows you (or someone) in the middle and the people you know around you, with an optional blue path.
+- Scene frames a product picture built from real components: decorative, inert, on the dot grid or a blue wash.
+- Light, Dark or System in every app: `themeScript` (`@brdgapp/ui/lib/theme`) sets the theme before the page
+  paints; `useTheme()` (`@brdgapp/ui/hooks/use-theme`) reads and changes it; ThemeSwitch is the Appearance setting.
+  System is the default. The choice is a cookie for all of brdg.app, so every Bridge app follows it; Bridge OS's
+  old saved choice is still read.
+- Focus is a solid 2px blue ring (red on danger buttons, white on blue) with a 2px gap: 7:1 in light, 5:1 in dark.
+  Bridge OS's 40% ring was under WCAG's 3:1. A fallback outline in `globals.css` covers anything an app builds
+  itself. TabPanel shows the ring when it takes focus.
+- Disabled is 50% in every component (Bridge OS buttons used 30%; the package mixed 30, 40, 50 and 60).
+- `glass-chrome` is the full top-bar glass (a 40px blur, a hairline under it, a near-solid fill where Safari
+  drops the blur). `liquid-glass-sm`, used nowhere, is removed. The stylesheet needs Tailwind 4.
+- Overlays follow Motion's speeds on Bridge's curve: menus, tips, hover cards and toasts 200ms in and 150ms out;
+  dialogs, drawers, sheets and backdrops 300ms in and 200ms out (dialogs and menus were 150ms both ways).
+- SkipLink: “Skip to content”, hidden until focused, for every app's layout.
+- HoverCard previews a person or company after the pointer rests on its name for 300ms. Read-only.
+- Card is frosted glass in three sizes (`lg`, `md`, `sm`), or a `bare` row inside another card. It can be a link
+  (`href`, rises on hover) or picked from a list (`onSelect`, `selected`, tints on hover); controls inside
+  keep working with no extra code. Header with icon (in blue, green, amber or purple) or avatar, an ⓘ hint, meta, action and an optional strip; CardMedia;
+  CardFooter; `flush` for tables.
+- `--text-muted` is #6D7284 (Bridge OS #6E7385) so it passes 4.5:1 on `--surface-secondary`; dark `--purple` is
+  #9A81ED (Bridge OS #8B6EE8) so purple tags pass 4.5:1 on every dark surface.
+- `cn` knows Bridge's page textures (`bg-dot-grid`, `bg-noise`, `bg-glow-patches`) aren't background colors, so
+  it keeps both a color and a texture, and lets the three stack.
+- Named type sizes on one ladder: `text-11`, `-12`, `-13`, `-14`, `-16`, `-18`, `-22`, `-28`, `-36`, `-48`, each with its
+  line height. `cn` knows they are sizes. Card titles are 16px; Dialog, ConfirmDialog and Drawer titles 18px.
+  Input, Textarea, SearchInput and TagInput are 16px on phones (14px from 768px up) so iOS doesn't zoom in.
+- Button `md` is 40px tall (Bridge OS 38px), the height of a text field, so the two line up in a row.
+- `@brdgapp/ui/lib/layout`: `PAGE_WIDTH` (wide 1600, standard 1280, read 800, form 720, narrow 448), `PAGE_EDGES`,
+  `pageFrame(width)` and `RAIL` (a 340px side rail from 1024px).
+- Phones (below 768px): FilterPill and ColumnFilterMenu open as a BottomSheet; ActionMenu rows, Tabs, fields and
+  the medium button are 44px tall; CopyField's copy hint shows without hover. `useIsMobile()` in
+  `@brdgapp/ui/hooks/use-is-mobile`.
+- Corners: ColumnSortButton, ColumnFilterMenu and Collapsible triggers use 4px (were 6px), so every component
+  is on the five corners (4, 8, 12, 16, round).
+- BottomSheet casts the dialog shadow (upward), not the drawer's.
+- Motion: `ease-out` is Bridge's one curve, cubic-bezier(0.23, 1, 0.32, 1); `@brdgapp/ui/lib/motion` has the three
+  speeds (`DURATION`: 150, 200, 300ms), `EASE` and `transition()` for JavaScript animations.
+- Tokens: `--super-connector-from`, `--super-connector-to` and `--badge-warning` for avatar badges.
+- StatBox corners are 12px (the small-card radius), up from Bridge OS's 8px.
+- Tag, TagInput, FilterPill, CopyField, ColumnSortButton, ColumnFilterMenu, InfoHint and HoverTip pass
+  extra attributes (`id`, `aria-*`, `data-*`, event handlers) to their main element; DataTable takes
+  `rowProps` for each row. The components' own props win where they overlap.
+- `@brdgapp/ui/lib/format`: `formatCount`, `formatMoney`, `formatPercent`, `formatDate`, `formatTime`, Bridge's
+  writing rules for numbers and dates (American English). StatBox formats its value with `formatCount`
+  (1,284 in full; 12.5K from 10,000).
+- Toast is built on Base UI Toast: mount `<Toaster />` once, then call `toast.success()` or
+  `toast.error()` from anywhere (a queue, a 3-second timer that pauses on hover, swipe to dismiss).
+- SearchInput, TagInput, CopyField, ColumnSortButton and DataTable's page buttons are built on Base UI
+  Input and Button, like Button.
+- Deprecated from the start: `Tag`'s `title` (a native tooltip). Use `Tip`; `title` is removed in 2.0.
+- Deprecated from the start: `<Toast open message />`, the Bridge OS API. Use `toast`; it is removed in 2.0.

package/README.md

@@ -1,231 +1,67 @@
 # @brdgapp/ui
 
-Shared UI components for Bridge apps. Each component lives in its own folder under `src/` with its own README. Apps install one package and import the components they need.
+Bridge's shared components, tokens and styles. How and when to use each part is in the handbook:
+**https://handbook.brdg.app** (start with "Using the system").
 
-It publishes to the `brdgapp` npm team. Installing it does not need an `.npmrc` or a registry token. Vercel installs it like any other dependency.
+## Needs
 
-Source lives in the private GitLab repo `intropath/packages/ui`. The published tarball is what apps install.
+- React 19
+- Tailwind CSS 4 (apps still on Tailwind 3 upgrade first)
+- The Mulish font, loaded by the app
 
-## Install
-
-Peer dependencies are `react` and `react-dom` (18 or newer). The app already has those.
+## Set up
 
 ```bash
-pnpm add @brdgapp/ui
-```
-
-The package publishes TypeScript source, not a prebuilt `dist`. The app bundler must compile it.
-
-### Next.js
-
-In `next.config.mjs` (or `next.config.js`):
-
-```js
-const nextConfig = {
-  transpilePackages: ["@brdgapp/ui"],
-}
-```
-
-Import the stylesheet once from the root layout (`app/layout.tsx`). That file pulls in every component stylesheet. Next.js does not pick up the package’s CSS import on its own.
-
-```tsx
-import "@brdgapp/ui/styles.css"
-```
-
-### Vite
-
-Add the package to `optimizeDeps.exclude` only if the dev server fails to compile its TypeScript. The package entry imports `styles.css`, so a normal Vite app gets the CSS from the JS import. If styles are missing, import `@brdgapp/ui/styles.css` once from the app entry.
-
-## Provider
-
-Wrap the tree once with `BridgeUIProvider`. It supplies the Bridge API base and the signed-in user’s access token. Components that talk to the Bridge API use this provider. They do not take their own token prop.
-
-```tsx
-"use client"
-
-import { BridgeUIProvider } from "@brdgapp/ui"
-
-export function AppProviders({ children }: { children: React.ReactNode }) {
-  return (
-    <BridgeUIProvider getAccessToken={getAuthToken}>
-      {children}
-    </BridgeUIProvider>
-  )
-}
-```
-
-`apiBaseUrl` defaults to production: `https://api.brdg.app/api/v4`. Pass it only for staging or a local backend, using the same value the app already uses for `NEXT_PUBLIC_API_BASE_URL`. Include the `/api/v4` prefix and leave off the trailing slash.
-
-`getAccessToken` returns the bearer token for the signed-in user, or `null` when nobody is signed in. It may be async. A Next.js server action that reads the `authToken` cookie is a valid implementation, because components call it from the browser:
-
-```tsx
-"use server"
-
-import { cookies } from "next/headers"
-
-export async function getAuthToken(): Promise<string | null> {
-  const cookieStore = await cookies()
-  return cookieStore.get("authToken")?.value ?? null
-}
-```
-
-Pass that function as `getAccessToken`. Do not put the token, or any other secret, in this package.
-
-`introInboxUrl` and `profileUrlForUsername` override the URLs used by built-in intro and profile actions. Defaults are `https://intros.brdg.app/inbox` and `https://os.brdg.app/to/<username>`.
-
-## Components
-
-Import from `@brdgapp/ui`, not from a deep path. The app must already wrap the tree in `BridgeUIProvider`.
-
-- [Network people helper](#network-people-helper)
-
-<details id="network-people-helper">
-<summary><strong>Network people helper</strong> — people you know at a domain</summary>
-
-Shows how many people you know at a specific domain, and who they are, from the signed-in user’s Bridge network.
-
-Use it on any screen that is about one company or firm. Pass that domain. The component looks up the signed-in user’s contacts whose email domain matches, then renders a floating widget: “You know 6 people at Brdg”, with avatars. Opening it lists those people (name, role, company, email) so the user can make an intro, copy an intro link, or open a Bridge profile. Apps can add their own row actions, such as adding the person as a team member.
-
-Nothing appears when the user is signed out, or when they know nobody at that domain.
-
-### Floating widget
-
-```tsx
-import { NetworkPeopleHelper } from "@brdgapp/ui"
-
-<NetworkPeopleHelper
-  domain={domain}
-  placement="bottom-end"
-  customActions={[
-    {
-      id: "add-team-member",
-      label: "Add as team member",
-      description: "Save them on this firm's team so they show up with the rest of the roster.",
-      onSelect: (contact) => addTeamMember(contact),
-    },
-  ]}
-/>
+npm install @brdgapp/ui
 ```
 
-`domain` is required. The component cleans it (strips protocol, `www.`, path, and query) and sends it as `domain_override`.
-
-After `checkDelayMs` (default 3000) it requests:
-
-- `GET {apiBaseUrl}/search/owned_full_network_contacts/count?domain_override=`
-- `GET {apiBaseUrl}/search/owned_full_network_contacts?domain_override=&limit=&offset=`
-
-Requests send `Authorization: Bearer <token>` from the provider’s `getAccessToken`. Pass `0` to skip the wait.
-
-When the count is greater than zero, the widget appears: icon, then the “You know N people at …” note, then a searchable list with infinite scroll. “Do not show again” hides it for the rest of the browser session (`sessionStorage` key `bridge-network-helper-dismissed:<domain>`).
-
-#### Props
-
-| Prop | Required | Default | Purpose |
-| --- | --- | --- | --- |
-| `domain` | yes | — | Company or firm domain to match contacts against. |
-| `organizationLabel` | no | cleaned domain | Text after “at”. Pass a display name such as `"Brdg"` when the screen already has one. The contacts API does not return an organization name. |
-| `enabled` | no | `true` | Set `false` to skip the request and render nothing. |
-| `checkDelayMs` | no | `3000` | Wait after the page visit before the first request. |
-| `placement` | no | `"bottom-end"` | Fixed corner. See below. |
-| `className` | no | — | Extra class on the fixed root. |
-| `style` | no | — | Extra inline style on the fixed root. |
-| `customActions` | no | `[]` | Extra rows in each person’s menu. |
-
-`placement` is one of `"bottom-end"`, `"bottom-start"`, `"top-end"`, `"top-start"`. `"bottom-end"` is fixed, bottom-right, with a slightly larger offset from 640px up.
-
-Override that position in the app’s CSS. These variables win over the preset:
+In the app's main CSS file, after Tailwind:
 
 ```css
-.my-helper {
-  --bridge-helper-bottom: 5rem;
-  --bridge-helper-right: 2rem;
-  --bridge-helper-z: 50;
-}
+@import "tailwindcss";
+@import "@brdgapp/ui/globals.css";
 ```
 
-The full set is `--bridge-helper-top`, `--bridge-helper-right`, `--bridge-helper-bottom`, `--bridge-helper-left`, and `--bridge-helper-z`.
+That brings every token (light and dark), the base styles, and tells Tailwind to read the package's
+files, so its classes are included.
 
-Colors follow the host app’s `--foreground`, `--background`, `--muted`, `--muted-foreground`, and `--border` when those exist. Otherwise the widget uses its own defaults. The Bridge blue accent is `#0038ff`.
-
-#### Person menu
-
-Built-in actions, shown only when the contact has the field they need:
-
-- **Make intro** opens `https://intros.brdg.app/inbox?action=make-intro&n1=<email>` when `email` is set.
-- **Copy intro link** copies `shareLink`.
-- **View Bridge profile** opens `https://os.brdg.app/to/<username>` when `username` is set.
-
-Change those URLs with `introInboxUrl` and `profileUrlForUsername` on `BridgeUIProvider`.
-
-Custom actions are not built in. “Add as team member” and “Add as founder” belong to the app. Pass them only on the screens where they apply. `onSelect` receives the row’s contact:
+Load Mulish however the app loads fonts. With `next/font`, name the variable `--font-mulish`:
 
 ```ts
-type NetworkContact = {
-  id: string
-  name: string
-  email: string | null
-  shareLink: string | null
-  profilePicUrl: string | null
-  position: string | null
-  company: string | null
-  username: string | null
-  isMember: boolean
-}
-
-type NetworkPersonAction = {
-  id: string
-  label: string
-  description?: string
-  icon?: React.ReactNode
-  onSelect: (contact: NetworkContact) => void
-}
+const mulish = Mulish({ subsets: ["latin"], variable: "--font-mulish" });
 ```
 
-Custom actions render above the built-in ones. The component does not check edit permission. If the user must not see an action, omit it from `customActions`.
+Anything else (a Google Fonts link, a self-hosted file) works too, as long as the family is "Mulish".
 
-### Inline nudge
+Themes follow `data-theme="light"` or `data-theme="dark"` on `<html>`, not the device setting.
 
-`NetworkPeopleNudge` is the same note, inline in a team or founders section. It uses the same request as the floating helper. Clicking it opens the helper’s people list on this page.
+## Use
 
-```tsx
-import { NetworkPeopleNudge } from "@brdgapp/ui"
+Import each component from its own file. There is no single index file.
 
-<NetworkPeopleNudge domain={domain} organizationLabel={displayName} />
+```tsx
+import { Button } from "@brdgapp/ui/components/button";
+import { DataState } from "@brdgapp/ui/components/data-state";
+import { cn } from "@brdgapp/ui/lib/utils";
 ```
 
-Pass `onOpen` when the click should do something else. `organizationLabel`, `enabled`, and `className` match the helper. The nudge’s check delay is fixed at 3 seconds.
-
-`openNetworkPeopleHelper(domain)` opens the floating helper from any other button. It clears the session dismiss for that domain.
+For toasts, mount `<Toaster />` once in the root layout, then call `toast.success("Link copied")` from
+anywhere (`@brdgapp/ui/components/toast`).
 
-</details>
-
-## Adding a component
-
-1. Add `src/<component-name>/` with the component source and a `README.md` that says what it is for, its props, and a usage example. Add a `<details id="...">` section for that component under Components in this README, with the same usage, and link the component name to that id. npm renders this file only, and the GitLab repo is private.
-2. Export the public components and types from `src/<component-name>/index.ts`.
-3. Re-export those names from `src/index.ts` so apps keep importing `@brdgapp/ui`.
-4. If the component has CSS, put it in `src/<component-name>/styles.css` and add `@import "./<component-name>/styles.css";` to `src/styles.css`.
-5. If it calls the Bridge API, use `useBridgeUI()` from `src/provider.tsx`. Do not read tokens inside the component.
-
-## Publish
-
-From this repo, after the version in `package.json` is the one you want to release:
-
-```bash
-pnpm login
-pnpm publish
-```
+`useMockQuery` (`hooks/use-mock-query`) and `lib/demo-controls` are for handbook examples and
+prototypes. Replace them with real data loading in product code.
 
-`pnpm login` uses the `brdgapp` team account. `publishConfig.access` is `public`, so `pnpm publish` does not need `--access public`.
+## Versions
 
-This package has no dependencies of its own, so there is no lockfile to install first. Commit the release before publishing. pnpm refuses to publish a dirty git tree.
+- A fix bumps the last number (1.0.1).
+- A new component or option bumps the middle number (1.1.0).
+- Anything that could break an app bumps the first number (2.0.0).
+- Before something is renamed or removed, it's marked Deprecated for at least one release, with its
+  replacement named.
 
-To release a change, bump `version`, commit, push, then run `pnpm publish` again.
+Every release is listed in `CHANGELOG.md`.
 
-## Agent checklist
+## Agents
 
-1. Run `pnpm add @brdgapp/ui`.
-2. Next.js: set `transpilePackages: ["@brdgapp/ui"]`.
-3. Import `@brdgapp/ui/styles.css` once in the root layout.
-4. Wrap the app in `BridgeUIProvider` with a `getAccessToken` that returns the signed-in user’s bearer token.
-5. Open the component’s section under Components in this README and follow that.
+AI coding agents connect to the handbook's read-only MCP server at `https://handbook.brdg.app/mcp`.
+Setup: https://handbook.brdg.app/for-agents.

package/components/action-menu.d.ts

@@ -0,0 +1,65 @@
+import type * as React from "react";
+declare const ACTION_MENU_ITEM_CLASS: string;
+type ActionMenuContextValue = {
+    close: (restoreFocus?: boolean) => void;
+};
+/** Close the menu from inside its body, for custom controls. */
+declare function useActionMenu(): ActionMenuContextValue;
+/** Everything the trigger needs: ref, click and keyboard handlers, aria-haspopup, aria-expanded. */
+type TriggerRenderProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    ref?: React.Ref<HTMLButtonElement>;
+    "aria-haspopup"?: React.AriaAttributes["aria-haspopup"];
+    "aria-expanded"?: boolean;
+};
+type ActionMenuProps = {
+    /** Names the default ⋮ trigger. Name what the menu is for when it helps: "Actions for Leah Okonkwo". */
+    ariaLabel?: string;
+    /** Trigger size: `sm` for compact rows, `md` for headers. */
+    size?: "sm" | "md";
+    /** Menu width in px. 248 is the contact-menu width. */
+    width?: number;
+    /** Trigger icon. Defaults to vertical dots. */
+    icon?: React.ReactNode;
+    triggerClassName?: string;
+    menuClassName?: string;
+    /** Stop the trigger's click reaching a clickable row behind it. */
+    stopPropagation?: boolean;
+    /** Know when it opens, for example to load data then. */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * A custom trigger, such as a split button's caret. Spread `props` onto your control so it gets the
+     * keyboard handling too (Arrow Down opens the menu). `state.open` says whether the menu is open.
+     */
+    renderTrigger?: (props: TriggerRenderProps, state: {
+        open: boolean;
+    }) => React.ReactElement;
+    children: React.ReactNode | ((close: (restoreFocus?: boolean) => void) => React.ReactNode);
+};
+declare function ActionMenu({ ariaLabel, size, width, icon, triggerClassName, menuClassName, stopPropagation, onOpenChange, renderTrigger, children, }: ActionMenuProps): React.JSX.Element;
+type ActionMenuItemProps = {
+    icon?: React.ReactNode;
+    children: React.ReactNode;
+    /** A muted second line under the label. */
+    description?: React.ReactNode;
+    onClick?: () => void;
+    /** Makes the row a link. */
+    href?: string;
+    /** With `href`: opens in a new tab. */
+    external?: boolean;
+    /** Red, for removing or leaving. */
+    danger?: boolean;
+    disabled?: boolean;
+    /** Keep the menu open after choosing, for a row that shows its own result ("Copied"). */
+    closeOnClick?: boolean;
+    /**
+     * Render the link with your router's link, e.g. `render={<Link href="/settings" />}`.
+     * Without it, `href` renders a plain `<a>`.
+     */
+    render?: React.ReactElement;
+    className?: string;
+};
+declare function ActionMenuItem({ icon, children, description, onClick, href, external, danger, disabled, closeOnClick, render, className, }: ActionMenuItemProps): React.JSX.Element;
+/** A thin line between groups of rows. */
+declare function ActionMenuSeparator(): React.JSX.Element;
+export { ActionMenu, ActionMenuItem, ActionMenuSeparator, useActionMenu, ACTION_MENU_ITEM_CLASS };
+export type { ActionMenuProps, ActionMenuItemProps };

package/components/action-menu.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useMemo, useState } from "react";
+import { Menu } from "@base-ui/react/menu";
+import { MoreVertical } from "lucide-react";
+import { IconButton } from "@brdgapp/ui/components/icon-button";
+import { cn } from "@brdgapp/ui/lib/utils";
+// THE overflow (⋮) menu. Ported from Bridge OS src/components/ui/action-menu.tsx with the same API.
+// Bridge OS hand-built the portal, positioning, outside-click and Escape handling; Base UI Menu now
+// does that, plus arrow-key movement, type-to-find and focus return. It also follows the trigger on
+// scroll instead of closing. The danger colour is now a token (Bridge OS hard-coded #E13535).
+// The one menu-row look. Exported so custom stateful rows can match it.
+const ACTION_MENU_ITEM_CLASS = "flex w-full cursor-default items-center gap-3 px-3.5 py-2.5 max-md:min-h-11 text-left text-[13px] text-[var(--text-body)] outline-none transition-colors " +
+    "data-[highlighted]:bg-[var(--surface-secondary)] hover:bg-[var(--surface-secondary)] data-[disabled]:opacity-50 [&_svg]:size-4 [&_svg]:shrink-0";
+const ACTION_MENU_ITEM_DANGER_CLASS = "text-[var(--danger-text)] data-[highlighted]:bg-[var(--error-bg)] hover:bg-[var(--error-bg)]";
+const ActionMenuContext = createContext(null);
+/** Close the menu from inside its body, for custom controls. */
+function useActionMenu() {
+    const ctx = useContext(ActionMenuContext);
+    if (!ctx)
+        throw new Error("useActionMenu must be used inside <ActionMenu>");
+    return ctx;
+}
+function ActionMenu({ ariaLabel = "More options", size = "md", width = 248, icon, triggerClassName, menuClassName, stopPropagation = true, onOpenChange, renderTrigger, children, }) {
+    const [open, setOpen] = useState(false);
+    const setOpenAndNotify = useCallback((next) => {
+        setOpen(next);
+        onOpenChange?.(next);
+    }, [onOpenChange]);
+    // Base UI returns focus to the trigger whenever the menu closes, so `restoreFocus` needs no extra work.
+    const close = useCallback(() => setOpenAndNotify(false), [setOpenAndNotify]);
+    const ctx = useMemo(() => ({ close }), [close]);
+    const stop = stopPropagation ? (e) => e.stopPropagation() : undefined;
+    return (_jsxs(Menu.Root, { open: open, onOpenChange: setOpenAndNotify, children: [renderTrigger ? (_jsx(Menu.Trigger, { render: (props) => renderTrigger(props, { open }) })) : (_jsx(Menu.Trigger, { render: _jsx(IconButton, { "aria-label": ariaLabel, size: size, className: cn("shrink-0", triggerClassName), children: icon ?? _jsx(MoreVertical, {}) }), onClick: stop, onPointerDown: stop })), _jsx(Menu.Portal, { children: _jsx(Menu.Positioner, { side: "bottom", align: "end", sideOffset: 6, collisionPadding: 8, className: "z-[80]", children: _jsx(Menu.Popup, { "data-slot": "action-menu", style: { width }, className: cn("max-w-[calc(100vw-16px)] rounded-xl border border-[var(--border-default)] bg-[var(--surface-elevated)] py-1 shadow-[var(--shadow-menu)] outline-none", "origin-[var(--transform-origin)] transition-[opacity,scale] duration-200 ease-out data-[ending-style]:duration-150 data-[starting-style]:scale-95 data-[starting-style]:opacity-0 data-[ending-style]:opacity-0", menuClassName), children: _jsx(ActionMenuContext.Provider, { value: ctx, children: typeof children === "function" ? children(close) : children }) }) }) })] }));
+}
+function ActionMenuItem({ icon, children, description, onClick, href, external = false, danger = false, disabled = false, closeOnClick = true, render, className, }) {
+    const classes = cn(ACTION_MENU_ITEM_CLASS, danger && ACTION_MENU_ITEM_DANGER_CLASS, description && "items-start", className);
+    const body = description ? (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": "true", className: "mt-0.5 inline-flex shrink-0", children: icon }), _jsxs("span", { className: "min-w-0", children: [_jsx("span", { className: "block text-[13px] font-semibold text-[var(--text-primary)]", children: children }), _jsx("span", { className: "block text-[12px] text-[var(--text-muted)]", children: description })] })] })) : (_jsxs(_Fragment, { children: [icon ? (_jsx("span", { "aria-hidden": "true", className: "inline-flex shrink-0", children: icon })) : null, children] }));
+    if (href && !disabled) {
+        return (_jsx(Menu.LinkItem, { "data-slot": "action-menu-item", href: href, closeOnClick: closeOnClick, onClick: onClick, className: classes, render: render, ...(external ? { target: "_blank", rel: "noopener noreferrer" } : {}), children: body }));
+    }
+    return (_jsx(Menu.Item, { "data-slot": "action-menu-item", onClick: onClick, disabled: disabled, closeOnClick: closeOnClick, className: classes, children: body }));
+}
+/** A thin line between groups of rows. */
+function ActionMenuSeparator() {
+    return _jsx(Menu.Separator, { "data-slot": "action-menu-separator", className: "my-1 h-px bg-[var(--border-divider)]" });
+}
+export { ActionMenu, ActionMenuItem, ActionMenuSeparator, useActionMenu, ACTION_MENU_ITEM_CLASS };

package/components/avatar.d.ts

@@ -0,0 +1,50 @@
+import type { CSSProperties } from "react";
+import { type VariantProps } from "class-variance-authority";
+declare const avatarVariants: (props?: ({
+    size?: "sm" | "md" | "lg" | "xs" | "xl" | "2xl" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+type AvatarSize = NonNullable<VariantProps<typeof avatarVariants>["size"]>;
+type AvatarBadge = "member" | "super-connector" | "warning";
+/** "Priya Natarajan" → "PN", "Priya" → "P", "" → "?". First and last word, so middle names don't crowd it. */
+declare function initialsOf(name: string | null | undefined): string;
+type AvatarProps = {
+    /** The person's name. Used for the initials, and read out when `standalone`. */
+    name: string | null | undefined;
+    /** Photo URL. Leave empty and the initials show. */
+    src?: string | null;
+    /** 16, 24, 32, 40, 48 or 64px. */
+    size?: AvatarSize;
+    /** A corner mark: Bridge member, Super Connector, or an account that needs attention. Not shown at `xs`. */
+    badge?: AvatarBadge | null;
+    /**
+     * Set when no name shows next to the avatar, so screen readers hear who it is. Most avatars sit
+     * beside the name, and only the badge (if any) is read, so the name isn't read twice.
+     */
+    standalone?: boolean;
+    /** Layout only: `mt-0.5`. */
+    className?: string;
+    /** For AvatarGroup's stacking order. */
+    style?: CSSProperties;
+};
+declare function Avatar({ name, src, size, badge, standalone, className, style }: AvatarProps): import("react").JSX.Element;
+type AvatarGroupProps = {
+    /** Everyone in the group, in order. The first ones show. */
+    people: {
+        name: string | null | undefined;
+        src?: string | null;
+    }[];
+    /** How many faces show before "+N". */
+    max?: number;
+    /** 16 to 64px. Stacks are usually `sm` (24px). */
+    size?: AvatarSize;
+    /**
+     * Set when the names are written next to the stack. Otherwise screen readers hear the names:
+     * "Leah Okonkwo, Priya Natarajan, Mei Lin Zhou and 4 others".
+     */
+    decorative?: boolean;
+    /** Layout only. */
+    className?: string;
+};
+declare function AvatarGroup({ people, max, size, decorative, className }: AvatarGroupProps): import("react").JSX.Element;
+export { Avatar, AvatarGroup, avatarVariants, initialsOf };
+export type { AvatarBadge, AvatarGroupProps, AvatarProps, AvatarSize };

package/components/avatar.js

@@ -0,0 +1,91 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar";
+import { cva } from "class-variance-authority";
+import { cn } from "@brdgapp/ui/lib/utils";
+// A person's photo in a circle, or their initials when there's no photo, with an optional corner badge.
+// Started from shadcn's Base UI avatar, then fitted to the Bridge apps, which draw this by hand in over
+// 100 places across 12 repos. Base UI shows the initials while the photo loads and keeps them if the
+// photo fails, so a broken URL never shows a broken image.
+//
+// Decisions (2026-11-03, after checking all 12 app repos):
+// - Initials on light blue (`--info-bg`), letters in `--info` (not `--primary`: 3.3:1 in dark).
+// - Sizes 16, 24, 32, 40, 48, 64: stacks and chips 16–24, lists 32, rows 40, cards 48, profile headers 64.
+// - Badges, as in Bridge OS contact-card.tsx and app-cc avatar-status-badge.tsx: a blue tick for a Bridge
+//   member, a purple award for a Super Connector (replaces the tick), an amber "!" when the account is
+//   deactivated or its emails fail. The warning amber is darker than app-cc's #E19500, which gave the
+//   white mark 2.5:1; #B87A00 gives 3.6:1.
+// - AvatarGroup: 3 faces then "+N", overlapping a little less than the apps do, a ring between faces (app-directories, together,
+//   app-portfolio, raise, bridge-jobs).
+const avatarVariants = cva("relative inline-flex shrink-0 rounded-full bg-[var(--info-bg)] align-middle select-none", {
+    variants: {
+        size: {
+            xs: "size-4 text-[8px]",
+            sm: "size-6 text-[10px]",
+            md: "size-8 text-[12px]",
+            lg: "size-10 text-[14px]",
+            xl: "size-12 text-[16px]",
+            "2xl": "size-16 text-[20px]",
+        },
+    },
+    defaultVariants: { size: "md" },
+});
+const BADGE_LABEL = {
+    member: "Bridge member",
+    "super-connector": "Super Connector",
+    warning: "Account needs attention",
+};
+// Badge diameter for each avatar size. None at 16px: too small to read.
+const BADGE_SIZE = {
+    xs: null,
+    sm: "size-2.5 ring-1",
+    md: "size-3 ring-[1.5px]",
+    lg: "size-3.5 ring-2",
+    xl: "size-[18px] ring-2",
+    "2xl": "size-5 ring-2",
+};
+/** "Priya Natarajan" → "PN", "Priya" → "P", "" → "?". First and last word, so middle names don't crowd it. */
+function initialsOf(name) {
+    const words = (name ?? "").trim().split(/\s+/).filter(Boolean);
+    const first = words[0]?.[0] ?? "";
+    const last = words.length > 1 ? (words[words.length - 1]?.[0] ?? "") : "";
+    return (first + last).toUpperCase() || "?";
+}
+function BadgeMark({ badge }) {
+    if (badge === "member") {
+        return (_jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "4", strokeLinecap: "round", strokeLinejoin: "round", className: "size-[60%]", children: _jsx("polyline", { points: "20 6 9 17 4 12" }) }));
+    }
+    if (badge === "super-connector") {
+        // The award glyph from the Arch Design System, via Bridge OS super-connector-badge.tsx.
+        return (_jsx("svg", { viewBox: "0 0 8.24323 14.1285", fill: "currentColor", className: "h-[60%] w-auto", children: _jsx("path", { fillRule: "evenodd", clipRule: "evenodd", d: "M0.136812 0.00229937H3.11564L5.79901 4.88271C5.85649 4.98618 5.94042 5.06781 6.03584 5.11954H2.03034L0.136812 0V0.00229937ZM4.12162 5.88523C6.39799 5.88523 8.24323 7.73047 8.24323 10.0068C8.24323 12.2832 6.39799 14.1285 4.12162 14.1285C1.84524 14.1273 0 12.2821 0 10.0057C0 7.72932 1.84524 5.88523 4.12162 5.88523ZM4.12162 7.627L4.81028 9.30784L6.62333 9.44465L5.23566 10.6219L5.66679 12.3855L4.12162 11.4279L2.57644 12.3855L3.00757 10.6219L1.61875 9.4435L3.43181 9.30669L4.12162 7.627ZM4.48722 0.00229937H7.97306L6.57044 3.79396L4.48722 0.00229937Z" }) }));
+    }
+    return (_jsxs("svg", { viewBox: "0 0 16 16", fill: "currentColor", className: "size-[70%]", children: [_jsx("path", { d: "M8 3.2c-.59 0-1.05.5-1.02 1.08l.25 4a.77.77 0 0 0 1.53 0l.25-4A1.02 1.02 0 0 0 8 3.2Z" }), _jsx("circle", { cx: "8", cy: "11.6", r: "0.95" })] }));
+}
+const BADGE_FILL = {
+    member: "bg-[var(--primary-solid)]",
+    "super-connector": "bg-linear-to-l from-[var(--super-connector-from)] to-[var(--super-connector-to)]",
+    warning: "bg-[var(--badge-warning)]",
+};
+function Avatar({ name, src, size = "md", badge, standalone = false, className, style }) {
+    const badgeSize = badge ? BADGE_SIZE[size] : null;
+    const label = badge ? BADGE_LABEL[badge] : null;
+    return (_jsxs(AvatarPrimitive.Root, { "data-slot": "avatar", "data-size": size, className: cn(avatarVariants({ size }), className), style: style, ...(standalone ? { role: "img", "aria-label": [name || "Unknown person", label].filter(Boolean).join(", ") } : {}), children: [_jsxs("span", { className: "block size-full overflow-hidden rounded-full", "aria-hidden": "true", children: [src ? _jsx(AvatarPrimitive.Image, { "data-slot": "avatar-image", src: src, alt: "", className: "size-full object-cover" }) : null, _jsx(AvatarPrimitive.Fallback, { "data-slot": "avatar-fallback", className: "flex size-full items-center justify-center leading-none font-bold text-[var(--info)]", children: initialsOf(name) })] }), badge && badgeSize ? (_jsx("span", { "data-slot": "avatar-badge", "data-badge": badge, "aria-hidden": "true", className: cn("absolute -right-0.5 -bottom-0.5 flex items-center justify-center rounded-full text-white ring-[var(--surface-primary)]", BADGE_FILL[badge], badgeSize), children: _jsx(BadgeMark, { badge: badge }) })) : null, badge && !standalone ? _jsx("span", { className: "sr-only", children: label }) : null] }));
+}
+// How far each face tucks under the one before it: a quarter of the face less the ring, so two-letter
+// initials stay readable (the apps' 6px at 24px hid the first letter).
+const OVERLAP = {
+    xs: "-ml-0.5",
+    sm: "-ml-1",
+    md: "-ml-1.5",
+    lg: "-ml-2",
+    xl: "-ml-2.5",
+    "2xl": "-ml-3",
+};
+function AvatarGroup({ people, max = 3, size = "sm", decorative = false, className }) {
+    const shown = people.slice(0, max);
+    const extra = people.length - shown.length;
+    const names = shown.map((p) => p.name || "Unknown person");
+    const label = extra > 0 ? `${names.join(", ")} and ${extra} ${extra === 1 ? "other" : "others"}` : names.join(", ");
+    return (_jsxs("span", { "data-slot": "avatar-group", className: cn("inline-flex items-center align-middle", className), ...(decorative ? { "aria-hidden": true } : { role: "img", "aria-label": label }), children: [shown.map((p, i) => (_jsx(Avatar, { name: p.name, src: p.src, size: size, className: cn("ring-2 ring-[var(--surface-primary)]", i > 0 && OVERLAP[size]), style: { zIndex: shown.length - i } }, `${p.name}-${i}`))), extra > 0 ? (_jsxs("span", { "data-slot": "avatar-group-count", className: cn(avatarVariants({ size }), OVERLAP[size], "items-center justify-center bg-[var(--surface-tertiary)] leading-none font-semibold text-[var(--text-secondary)] ring-2 ring-[var(--surface-primary)]"), children: ["+", extra] })) : null] }));
+}
+export { Avatar, AvatarGroup, avatarVariants, initialsOf };

package/components/badge.d.ts

@@ -0,0 +1,12 @@
+import type * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+declare const badgeVariants: (props?: ({
+    style?: "outline" | "alum" | "solid-red" | "solid-dark" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+type BadgeProps = VariantProps<typeof badgeVariants> & {
+    className?: string;
+    children: React.ReactNode;
+};
+declare function Badge({ style, className, children }: BadgeProps): React.JSX.Element;
+export { Badge, badgeVariants };
+export type { BadgeProps };