@brdgapp/ui 0.1.0 → 0.1.2

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.
-
-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.
+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.
 
-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,9 +71,24 @@ 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.
+`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.
 
-## Network people helper
+### Floating widget
 
 ```tsx
 import { NetworkPeopleHelper } from "@brdgapp/ui"
@@ -96,20 +107,18 @@ import { NetworkPeopleHelper } from "@brdgapp/ui"
 />
 ```
 
-`domain` is required. The package cleans it (strips protocol, `www.`, path, and query) and sends it as `domain_override`.
+`domain` is required. The component 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:
+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 `getAccessToken`.
+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
+#### Props
 
 | Prop | Required | Default | Purpose |
 | --- | --- | --- | --- |
@@ -122,7 +131,7 @@ When the count is greater than zero, the widget appears: icon, then the “You k
 | `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.
+`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:
 
@@ -138,7 +147,7 @@ The full set is `--bridge-helper-top`, `--bridge-helper-right`, `--bridge-helper
 
 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
+#### Person menu
 
 Built-in actions, shown only when the contact has the field they need:
 
@@ -146,15 +155,7 @@ Built-in actions, shown only when the contact has the field they need:
 - **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}`}
->
-```
+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:
 
@@ -180,9 +181,9 @@ type NetworkPersonAction = {
 }
 ```
 
-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`.
+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
+### 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.
 
@@ -192,10 +193,20 @@ 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.
+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.
 
+</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:
@@ -216,8 +227,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 component’s section under Components in this README 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.2",
+  "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)