@brdgapp/ui 0.1.1 → 0.1.2

package/README.md

@@ -75,15 +75,133 @@ Pass that function as `getAccessToken`. Do not put the token, or any other secre
 
 ## 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. |
+Import from `@brdgapp/ui`, not from a deep path. The app must already wrap the tree in `BridgeUIProvider`.
 
-Read that component’s README before rendering it. Import from `@brdgapp/ui`, not from a deep path.
+- [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),
+    },
+  ]}
+/>
+```
+
+`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:
+
+```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. 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.
+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`.
@@ -110,4 +228,4 @@ To release a change, bump `version`, commit, push, then run `pnpm publish` again
 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.
+5. Open the component’s section under Components in this README and follow that.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brdgapp/ui",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Shared Bridge UI components for Bridge apps.",
   "license": "UNLICENSED",
   "type": "module",