@brdgapp/ui 0.1.0 → 0.1.1

package/README.md

@@ -1,12 +1,8 @@
 # @brdgapp/ui
 
-Shows how many people you know at a specific domain, and who they are, from the signed-in user’s Bridge network.
+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.
 
-Use it on any screen that is about one company or firm. Pass that domain. The package 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.
-
-It publishes to the `brdgapp` npm team as `@brdgapp/ui`. Installing it does not need an `.npmrc` or a registry token. Vercel installs it like any other dependency.
+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.
 
 Source lives in the private GitLab repo `intropath/packages/ui`. The published tarball is what apps install.
 
@@ -30,7 +26,7 @@ const nextConfig = {
 }
 ```
 
-Import the stylesheet once from the root layout (`app/layout.tsx`). Next.js does not pick up the package’s CSS import on its own.
+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"
@@ -40,14 +36,14 @@ import "@brdgapp/ui/styles.css"
 
 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.
 
-## Wire it up
+## Provider
 
-Render `BridgeUIProvider` once around the tree that contains the helper. It supplies the Bridge API base and the signed-in user’s access token. The helper then calls the contacts API itself.
+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, NetworkPeopleHelper } from "@brdgapp/ui"
+import { BridgeUIProvider } from "@brdgapp/ui"
 
 export function AppProviders({ children }: { children: React.ReactNode }) {
   return (
@@ -60,7 +56,7 @@ export function AppProviders({ children }: { children: React.ReactNode }) {
 
 `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 the helper calls it from the browser:
+`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"
@@ -75,126 +71,23 @@ export async function getAuthToken(): Promise<string | null> {
 
 Pass that function as `getAccessToken`. Do not put the token, or any other secret, in this package.
 
-If `getAccessToken` returns `null`, or the user knows nobody at the domain, the helper stays hidden.
-
-## Network people helper
-
-```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),
-    },
-  ]}
-/>
-```
-
-`domain` is required. The package cleans it (strips protocol, `www.`, path, and query) and sends it as `domain_override`.
-
-### What the package does
-
-After about 3 seconds on the page 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 `getAccessToken`.
-
-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"` matches the portfolio widget: 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:
-
-```css
-.my-helper {
-  --bridge-helper-bottom: 5rem;
-  --bridge-helper-right: 2rem;
-  --bridge-helper-z: 50;
-}
-```
+`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>`.
 
-The full set is `--bridge-helper-top`, `--bridge-helper-right`, `--bridge-helper-bottom`, `--bridge-helper-left`, and `--bridge-helper-z`.
+## Components
 
-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`.
+| 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. |
 
-### 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 on the provider:
-
-```tsx
-<BridgeUIProvider
-  getAccessToken={getAuthToken}
-  introInboxUrl="https://intros.brdg.app/inbox"
-  profileUrlForUsername={(username) => `https://os.brdg.app/to/${username}`}
->
-```
-
-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:
-
-```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
-}
-```
-
-Custom actions render above the built-in ones. The package does not check edit permission. If the user must not see an action, omit it from `customActions`.
-
-## Inline nudge
-
-`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.
-
-```tsx
-import { NetworkPeopleNudge } from "@brdgapp/ui"
-
-<NetworkPeopleNudge domain={domain} organizationLabel={displayName} />
-```
+Read that component’s README before rendering it. Import from `@brdgapp/ui`, not from a deep path.
 
-Pass `onOpen` when the click should do something else. `organizationLabel`, `enabled`, and `className` match the helper.
+## Adding a component
 
-`openNetworkPeopleHelper(domain)` opens the floating helper from any other button. It clears the session dismiss for that domain.
+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
 
@@ -216,8 +109,5 @@ To release a change, bump `version`, commit, push, then run `pnpm publish` again
 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. The API base defaults to `https://api.brdg.app/api/v4`. Pass `apiBaseUrl` only for staging or local.
-5. Render `NetworkPeopleHelper` with `domain`.
-6. Pass `organizationLabel` only when the screen already has a display name.
-7. Pass `customActions` only for actions this screen owns. `onSelect` gets the `NetworkContact`.
-8. Leave Make intro, Copy intro link, and View Bridge profile to the package.
+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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brdgapp/ui",
-  "version": "0.1.0",
-  "description": "Shows how many people you know at a domain, and who they are, from the signed-in user's Bridge network.",
+  "version": "0.1.1",
+  "description": "Shared Bridge UI components for Bridge apps.",
   "license": "UNLICENSED",
   "type": "module",
   "sideEffects": [

package/src/index.ts

@@ -4,9 +4,15 @@ import "./styles.css"
 
 export { BridgeUIProvider, DEFAULT_API_BASE_URL } from "./provider"
 export type { BridgeUIProviderProps } from "./provider"
-export { NetworkPeopleHelper } from "./network-people-helper"
-export type { NetworkPeopleHelperProps } from "./network-people-helper"
-export { NetworkPeopleNudge } from "./network-people-nudge"
-export type { NetworkPeopleNudgeProps } from "./network-people-nudge"
-export { openNetworkPeopleHelper } from "./open-helper"
-export type { NetworkContact, NetworkPersonAction, HelperPlacement } from "./types"
+export {
+  NetworkPeopleHelper,
+  NetworkPeopleNudge,
+  openNetworkPeopleHelper,
+} from "./network-people-helper"
+export type {
+  NetworkPeopleHelperProps,
+  NetworkPeopleNudgeProps,
+  NetworkContact,
+  NetworkPersonAction,
+  HelperPlacement,
+} from "./network-people-helper"

package/src/network-people-helper/README.md

@@ -0,0 +1,130 @@
+# Network people helper
+
+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.
+
+The app must already wrap the tree in `BridgeUIProvider`. See the [package README](../../README.md).
+
+## 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),
+    },
+  ]}
+/>
+```
+
+`domain` is required. The component cleans it (strips protocol, `www.`, path, and query) and sends it as `domain_override`.
+
+### What it requests
+
+After about 3 seconds on the page 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`.
+
+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:
+
+```css
+.my-helper {
+  --bridge-helper-bottom: 5rem;
+  --bridge-helper-right: 2rem;
+  --bridge-helper-z: 50;
+}
+```
+
+The full set is `--bridge-helper-top`, `--bridge-helper-right`, `--bridge-helper-bottom`, `--bridge-helper-left`, and `--bridge-helper-z`.
+
+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:
+
+```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
+}
+```
+
+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`.
+
+## Inline nudge
+
+`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.
+
+```tsx
+import { NetworkPeopleNudge } from "@brdgapp/ui"
+
+<NetworkPeopleNudge domain={domain} organizationLabel={displayName} />
+```
+
+Pass `onOpen` when the click should do something else. `organizationLabel`, `enabled`, and `className` match the helper.
+
+`openNetworkPeopleHelper(domain)` opens the floating helper from any other button. It clears the session dismiss for that domain.
+
+## Files
+
+| File | Role |
+| --- | --- |
+| `network-people-helper.tsx` | Floating widget. |
+| `network-people-nudge.tsx` | Inline note that opens the widget. |
+| `api.ts` | Count, preview, and paged contact requests. |
+| `styles.css` | Widget styles. Imported by the package stylesheet. |
+| `index.ts` | Public exports for this component. |

package/src/{api.ts → network-people-helper/api.ts}

@@ -1,5 +1,6 @@
 import { cleanDomain } from "./domain"
-import type { BridgeClientConfig, NetworkContact } from "./types"
+import type { BridgeClientConfig } from "../provider"
+import type { NetworkContact } from "./types"
 
 export const PREVIEW_LIMIT = 3
 export const PAGE_SIZE = 20

package/src/network-people-helper/index.ts

@@ -0,0 +1,6 @@
+export { NetworkPeopleHelper } from "./network-people-helper"
+export type { NetworkPeopleHelperProps } from "./network-people-helper"
+export { NetworkPeopleNudge } from "./network-people-nudge"
+export type { NetworkPeopleNudgeProps } from "./network-people-nudge"
+export { openNetworkPeopleHelper } from "./open-helper"
+export type { NetworkContact, NetworkPersonAction, HelperPlacement } from "./types"

package/src/{network-people-helper.tsx → network-people-helper/network-people-helper.tsx}

@@ -16,7 +16,7 @@ import {
   type NetworkPeopleHelperOpenDetail,
 } from "./open-helper"
 import { PersonMenu, ShareLinkCopyControl } from "./person-menu"
-import { useBridgeUI } from "./provider"
+import { useBridgeUI } from "../provider"
 import type { HelperPlacement, NetworkPersonAction } from "./types"
 import { useNetworkPeopleList } from "./use-network-people-list"
 import { useNetworkPreview } from "./use-network-preview"

package/src/{network-people-nudge.tsx → network-people-helper/network-people-nudge.tsx}

@@ -5,7 +5,7 @@ import { ContactAvatar } from "./contact-avatar"
 import { cleanDomain, organizationLabelFromDomain } from "./domain"
 import { BridgeHelperIcon, ChevronUpIcon } from "./icons"
 import { openNetworkPeopleHelper } from "./open-helper"
-import { useBridgeUI } from "./provider"
+import { useBridgeUI } from "../provider"
 import { useNetworkPreview } from "./use-network-preview"
 
 const DEFAULT_CHECK_DELAY_MS = 3000

package/src/{person-menu.tsx → network-people-helper/person-menu.tsx}

@@ -3,7 +3,8 @@
 import { useEffect, useLayoutEffect, useRef, useState } from "react"
 import { createPortal } from "react-dom"
 import { CheckIcon, CopyIcon, LinkIcon, MoreIcon, UserIcon, UserPlusIcon } from "./icons"
-import type { BridgeClientConfig, NetworkContact, NetworkPersonAction } from "./types"
+import type { BridgeClientConfig } from "../provider"
+import type { NetworkContact, NetworkPersonAction } from "./types"
 
 function introUrl(inboxUrl: string, email: string): string {
   const url = new URL(inboxUrl)