@brdgapp/ui 0.1.1 → 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,113 +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"],
-}
+npm install @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.
+In the app's main CSS file, after Tailwind:
 
-```tsx
-import "@brdgapp/ui/styles.css"
+```css
+@import "tailwindcss";
+@import "@brdgapp/ui/globals.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"
+That brings every token (light and dark), the base styles, and tells Tailwind to read the package's
+files, so its classes are included.
 
-import { BridgeUIProvider } from "@brdgapp/ui"
+Load Mulish however the app loads fonts. With `next/font`, name the variable `--font-mulish`:
 
-export function AppProviders({ children }: { children: React.ReactNode }) {
-  return (
-    <BridgeUIProvider getAccessToken={getAuthToken}>
-      {children}
-    </BridgeUIProvider>
-  )
-}
+```ts
+const mulish = Mulish({ subsets: ["latin"], variable: "--font-mulish" });
 ```
 
-`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.
+Anything else (a Google Fonts link, a self-hosted file) works too, as long as the family is "Mulish".
 
-`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:
+Themes follow `data-theme="light"` or `data-theme="dark"` on `<html>`, not the device setting.
 
-```tsx
-"use server"
+## Use
 
-import { cookies } from "next/headers"
+Import each component from its own file. There is no single index file.
 
-export async function getAuthToken(): Promise<string | null> {
-  const cookieStore = await cookies()
-  return cookieStore.get("authToken")?.value ?? null
-}
+```tsx
+import { Button } from "@brdgapp/ui/components/button";
+import { DataState } from "@brdgapp/ui/components/data-state";
+import { cn } from "@brdgapp/ui/lib/utils";
 ```
 
-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
-
-| Component | Folder | What it is for |
-| --- | --- | --- |
-| Network people helper | [`src/network-people-helper`](./src/network-people-helper/README.md) | Shows how many people you know at a domain, and who they are, from the signed-in user’s Bridge network. |
-
-Read that component’s README before rendering it. Import from `@brdgapp/ui`, not from a deep path.
+For toasts, mount `<Toaster />` once in the root layout, then call `toast.success("Link copied")` from
+anywhere (`@brdgapp/ui/components/toast`).
 
-## 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.
-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 README for the component you are adding 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 };

package/components/badge.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cva } from "class-variance-authority";
+import { cn } from "@brdgapp/ui/lib/utils";
+// The "Solid label" sticker from the Arch Design System: 8px, bold, uppercase. Ported from Bridge OS
+// src/components/ui/badge.tsx. Rounded 4px, never a pill. For soft status and category labels use Tag.
+// Two fixes over Bridge OS: solid-red fills with --danger-solid (white on --error fails AA at 4.41:1), and
+// solid-dark's text uses --surface-primary so it stays readable in dark mode (white on light grey didn't).
+const badgeVariants = cva("inline-flex items-center rounded-[4px] px-[7px] py-1 text-[8px] leading-[8px] font-bold tracking-[1px] uppercase", {
+    variants: {
+        // Named `style` to match Bridge OS's API. It is not React's style prop: Badge takes no CSS styles.
+        style: {
+            outline: "border border-[var(--text-disabled)] text-[var(--text-muted)]",
+            alum: "border border-[var(--honey)] text-[var(--honey)]",
+            "solid-red": "bg-[var(--danger-solid)] text-white",
+            "solid-dark": "bg-[var(--text-secondary)] text-[var(--surface-primary)]",
+        },
+    },
+    defaultVariants: { style: "outline" },
+});
+function Badge({ style, className, children }) {
+    return (_jsx("span", { "data-slot": "badge", className: cn(badgeVariants({ style }), className), children: children }));
+}
+export { Badge, badgeVariants };

package/components/bottom-sheet.d.ts

@@ -0,0 +1,17 @@
+import type * as React from "react";
+type BottomSheetProps = {
+    open: boolean;
+    onClose: () => void;
+    /** What's being chosen: "Degree", "Sort by". */
+    title: React.ReactNode;
+    children: React.ReactNode;
+};
+declare function BottomSheet({ open, onClose, title, children }: BottomSheetProps): React.JSX.Element;
+/** One choice in a sheet: a 44px row with a tick when chosen. Wrap a set in `role="radiogroup"`. */
+declare function BottomSheetOption({ selected, onSelect, children }: {
+    selected?: boolean;
+    onSelect: () => void;
+    children: React.ReactNode;
+}): React.JSX.Element;
+export { BottomSheet, BottomSheetOption };
+export type { BottomSheetProps };

package/components/bottom-sheet.js

@@ -0,0 +1,12 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { cn } from "@brdgapp/ui/lib/utils";
+function BottomSheet({ open, onClose, title, children }) {
+    return (_jsx(DialogPrimitive.Root, { open: open, onOpenChange: (next) => !next && onClose(), children: _jsxs(DialogPrimitive.Portal, { children: [_jsx(DialogPrimitive.Backdrop, { className: "fixed inset-0 z-[80] bg-black/30 transition-opacity duration-300 ease-out data-[ending-style]:duration-200 data-[starting-style]:opacity-0 data-[ending-style]:opacity-0" }), _jsxs(DialogPrimitive.Popup, { "data-slot": "bottom-sheet", className: cn("fixed inset-x-0 bottom-0 z-[80] flex max-h-[85dvh] flex-col rounded-t-2xl border-t border-[var(--border-default)] bg-[var(--surface-elevated)] shadow-[var(--shadow-dialog)] outline-none", "pb-[max(12px,env(safe-area-inset-bottom))]", "transition-transform duration-300 ease-out data-[ending-style]:duration-200 data-[starting-style]:translate-y-full data-[ending-style]:translate-y-full motion-reduce:transition-none"), children: [_jsx("div", { "aria-hidden": "true", className: "mx-auto mt-2 h-1 w-10 shrink-0 rounded-full bg-[var(--border-hover)]" }), _jsx(DialogPrimitive.Title, { className: "shrink-0 px-5 pt-3 pb-2 text-16 font-bold tracking-tight text-[var(--text-primary)]", children: title }), _jsx("div", { "data-slot": "bottom-sheet-body", className: "min-h-0 flex-1 overflow-y-auto overscroll-contain", children: children })] })] }) }));
+}
+/** One choice in a sheet: a 44px row with a tick when chosen. Wrap a set in `role="radiogroup"`. */
+function BottomSheetOption({ selected, onSelect, children }) {
+    return (_jsxs("button", { type: "button", role: "radio", "aria-checked": selected, onClick: onSelect, "data-slot": "bottom-sheet-option", className: cn("flex min-h-11 w-full items-center justify-between gap-3 px-5 text-left text-14 outline-none transition-colors", "active:bg-[var(--surface-tertiary)] focus-visible:bg-[var(--surface-secondary)]", selected ? "font-semibold text-[var(--text-primary)]" : "text-[var(--text-body)]"), children: [_jsx("span", { className: "truncate", children: children }), selected ? (_jsx("svg", { "aria-hidden": "true", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2.5", strokeLinecap: "round", strokeLinejoin: "round", className: "size-4 shrink-0 text-[var(--primary)]", children: _jsx("polyline", { points: "20 6 9 17 4 12" }) })) : null] }));
+}
+export { BottomSheet, BottomSheetOption };

package/components/brand-mark.d.ts

@@ -0,0 +1,20 @@
+export type Brand = "linkedin" | "google" | "microsoft" | "apple" | "whatsapp" | "telegram" | "chrome";
+declare const NAME: Record<Brand, string>;
+type BrandMarkProps = {
+    brand: Brand;
+    /**
+     * Say the company's name to screen readers. Leave it off when its name is already written next to it
+     * ("Sign in with Google"): the mark is then hidden from them. Set it when the mark stands alone.
+     */
+    label?: boolean;
+    /**
+     * One color that follows the text, for a quiet mark in a row of links. LinkedIn, WhatsApp and Telegram
+     * only; Google, Microsoft and Chrome stay in color, and Apple is always one color.
+     */
+    mono?: boolean;
+    /** Size and layout only: `size-3.5`, `shrink-0`. 16px by default, like an icon. */
+    className?: string;
+};
+/** A company's logo at icon size, in its own colors. Not an icon: Lucide has none of these. */
+declare function BrandMark({ brand, label, mono, className }: BrandMarkProps): import("react").JSX.Element;
+export { BrandMark, NAME as BRAND_NAMES };