@nukleus-sports/ui-patterns 0.2.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,70 +1,6 @@
1
1
  import * as react from 'react';
2
2
  import { ReactNode, MouseEvent } from 'react';
3
-
4
- type EntityType = "player" | "coach" | "team" | "contact" | "company" | "agency" | "initials";
5
- type EntityAvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
6
- interface BaseEntityData {
7
- first_name?: string | null;
8
- last_name?: string | null;
9
- player_image_url?: string | null;
10
- coach_image_url?: string | null;
11
- profile_image_url?: string | null;
12
- team?: string | null;
13
- nickname?: string | null;
14
- team_logo_url?: string | null;
15
- name?: string | null;
16
- avatar_url?: string | null;
17
- }
18
- /**
19
- * CSS pixel size of each avatar size step, mirroring `sizeClasses`/`contactSizeClasses` below.
20
- * Exported so a consuming app's `resolveImageUrl` adapter can request an appropriately
21
- * sized render (e.g. nukleus-clientapp's `sizedStorageImage(rawUrl, ENTITY_AVATAR_SIZE_PX[size], "cover")`)
22
- * without this package needing to know about that CDN's resize API.
23
- */
24
- declare const ENTITY_AVATAR_SIZE_PX: Record<EntityAvatarSize, number>;
25
- /**
26
- * Turns a raw, possibly-relative stored image path into a renderable URL.
27
- *
28
- * Both source apps resolved this inline by calling Supabase-storage-specific helpers
29
- * (`getStoragePublicUrl`, `sizedStorageImage`, cache-busting query params) straight out of
30
- * `@/lib/image-utils`. This package has no legitimate reason to talk to Supabase or know
31
- * about a particular CDN's URL shape, so that resolution step is lifted out to this
32
- * injectable adapter instead of being baked into the shared component — the same
33
- * data-arrives-through-props principle this repo already applies to page-shells.
34
- *
35
- * Return `null` to fall back to initials/the default placeholder image.
36
- */
37
- type EntityImageResolver = (rawUrl: string, context: {
38
- entityType: EntityType;
39
- size: EntityAvatarSize;
40
- cacheBreaker?: string | number;
41
- }) => string | null;
42
- interface EntityAvatarProps {
43
- /**
44
- * Drives image resolution and the placeholder shown when there's no image.
45
- * Defaults to "initials" — image when one is supplied, initials otherwise —
46
- * which is the behaviour every plain `name` + `imageUrl` call site expects.
47
- */
48
- entityType?: EntityType;
49
- entityData?: BaseEntityData | null;
50
- firstName?: string | null;
51
- lastName?: string | null;
52
- name?: string | null;
53
- imageUrl?: string | null;
54
- /**
55
- * Resolves a raw stored image path/URL into something renderable. Omit it to only
56
- * render already-absolute URLs (`http(s)://...` or `data:...`) as-is — anything else
57
- * (a bare storage path) falls back to initials/the default placeholder, since this
58
- * package can't resolve it itself. See `EntityImageResolver` for why.
59
- */
60
- resolveImageUrl?: EntityImageResolver;
61
- size?: EntityAvatarSize;
62
- className?: string;
63
- fallbackClassName?: string;
64
- showInitials?: boolean;
65
- cacheBreaker?: string | number;
66
- }
67
- declare function EntityAvatar({ entityType, entityData, firstName, lastName, name, imageUrl, resolveImageUrl, size, className, fallbackClassName, showInitials, cacheBreaker, }: EntityAvatarProps): react.JSX.Element;
3
+ import { EntityImageResolver } from './index.js';
68
4
 
69
5
  interface RowAction {
70
6
  /** Visible text. */
@@ -88,37 +24,24 @@ interface RowActionsDropdownProps {
88
24
  trigger?: ReactNode;
89
25
  /** Trigger button extra classes. */
90
26
  triggerClassName?: string;
91
- /**
92
- * Extra classes on the menu content. Mainly for stacking: the menu defaults
93
- * to `z-[60]`, which sits below overlays such as `Sheet` (`z-[120]`), so a
94
- * dropdown opened inside one needs a higher `z-` here to render above it.
95
- */
27
+ /** Extra classes on the menu content -- e.g. a higher `z-` than the default
28
+ * `z-[60]` when nesting inside an overlay like `Sheet` (`z-[120]`). */
96
29
  contentClassName?: string;
97
30
  /** `align` prop on the popover content. Default `"end"`. */
98
31
  align?: "start" | "center" | "end";
99
32
  /** Aria label on the trigger button. */
100
33
  ariaLabel?: string;
101
- /**
102
- * Radix `modal` on the menu. Default `true`.
103
- *
104
- * Pass `false` when the dropdown lives inside a modal Dialog/Sheet: two
105
- * nested modal layers each lock `pointer-events` on `document.body` and each
106
- * register a dismissable layer, so on touch the tap that opens the menu is
107
- * then read as an outside-press and closes it again — the trigger looks dead.
108
- */
34
+ /** Radix `modal` on the menu, default `true`. Pass `false` inside another modal
35
+ * Dialog/Sheet -- two nested modal layers otherwise make the trigger look dead on touch. */
109
36
  modal?: boolean;
110
37
  }
111
38
  /**
112
- * Canonical "row actions" dropdown — replaces the repeated
113
- * MoreIcon trigger + popover-styled content + Edit/Delete items pattern.
39
+ * Canonical row-actions dropdown (MoreIcon trigger + Edit/Delete items).
114
40
  *
115
41
  * @example
116
42
  * <RowActionsDropdown
117
43
  * ariaLabel={`Actions for ${row.name}`}
118
- * actions={[
119
- * { label: "Edit", onClick: () => onEdit(row) },
120
- * { label: "Delete", onClick: () => onDelete(row.id), destructive: true },
121
- * ]}
44
+ * actions={[{ label: "Edit", onClick: () => onEdit(row) }]}
122
45
  * />
123
46
  */
124
47
  declare function RowActionsDropdown({ actions, trigger, triggerClassName, contentClassName, align, ariaLabel, modal, }: RowActionsDropdownProps): react.JSX.Element | null;
@@ -131,42 +54,10 @@ interface DealEmptyStateProps {
131
54
  /** Optional override/extension for the message text's classes. */
132
55
  messageClassName?: string;
133
56
  }
134
- /**
135
- * Empty-state placeholder for a deals list (marketing deals tab/page).
136
- *
137
- * Extracted from two independent, non-exported local components:
138
- * - nukleus-app's `MarketingDealsTab.tsx` (`text-[14px] text-text-primary`)
139
- * - nukleus-clientapp's `Marketing.tsx` (`body-text text-text-secondary`)
140
- *
141
- * Both apps already agree on the `{ message: string }` shape and layout; the text
142
- * styling genuinely diverged. This uses clientapp's version as the default — it
143
- * reaches for the shared `body-text` typography primitive instead of a magic
144
- * `text-[14px]`, and dims the copy with `text-secondary`, which reads better for
145
- * empty-state messaging than the higher-emphasis `text-primary` nukleus-app used.
146
- * `messageClassName` is exposed so either app can override back to its prior look
147
- * if that divergence turns out to matter at the call site.
148
- */
57
+ /** Empty-state placeholder for a deals list (marketing deals tab/page).
58
+ * Reconciled from both apps -- see RECONCILIATION.md#deal-empty-statetsx */
149
59
  declare function DealEmptyState({ message, className, messageClassName }: DealEmptyStateProps): react.JSX.Element;
150
60
 
151
- /**
152
- * Reconciled from two near-identical implementations (clientapp's own file
153
- * comment already said "Mirrors nukleus-app's ContractDetailsCard"):
154
- * - nukleus-app's version had optional `title`/`caption` props (defaulting
155
- * to "Contract Details", no caption) -- kept as a strict superset,
156
- * clientapp's callers simply never pass them.
157
- * - clientapp's due-date formatting was a local `date-fns`-based helper
158
- * producing "MMM dd, yyyy" (zero-padded day); this uses `@nukleus-sports/
159
- * core`'s existing `formatDealDate` ("MMM d, yyyy", no zero-padding)
160
- * instead of introducing a second date formatter for one field -- the
161
- * day-padding difference is cosmetic.
162
- *
163
- * Found missing from this package entirely while wiring the Marketing Deals
164
- * Layer 5 retrofit into both apps: both apps' real `MarketingDealMetadata`
165
- * already has an identical `contract_details` shape (read from an uploaded
166
- * contract via each app's own AI extraction flow), and both apps' local
167
- * `ManualDealPreviewDialog`s already rendered this card -- a genuine
168
- * duplicate that simply hadn't been ported yet, not a single-app feature.
169
- */
170
61
  interface ContractDetailsCardDeliverable {
171
62
  description: string;
172
63
  due_date: string | null;
@@ -196,80 +87,11 @@ interface ContractDetailsCardProps {
196
87
  caption?: string;
197
88
  className?: string;
198
89
  }
199
- /**
200
- * Contract terms the deal form has no field for (territory, exclusivity,
201
- * payment terms, usage rights, deliverables, warnings), read from the
202
- * uploaded contract. Read-only; rows without a value are left out.
203
- */
90
+ /** Contract terms read from the uploaded contract. Read-only; empty rows are left out. */
204
91
  declare function ContractDetailsCard({ details, title, caption, className, }: ContractDetailsCardProps): react.JSX.Element;
205
92
 
206
- /**
207
- * Reconciled from two independent implementations:
208
- * - nukleus-app's `ManualDealCard.tsx` — superset: has Edit/Delete, a raw
209
- * `DropdownMenu` + `MoreIcon` trigger, an explicit "Preview Doc" quick-open
210
- * affordance next to the brand name, and an entirely separate collapsible
211
- * mobile layout (chevron + brand/amount summary row, expanding to a "View
212
- * Details"/"Preview Doc" footer).
213
- * - nukleus-clientapp's `ManualDealCard.tsx` — read-only subset: no Edit/Delete,
214
- * already uses a shared `RowActionsDropdown` (single "Preview Deal" action),
215
- * no "Preview Doc" affordance on the card at all, and no distinct mobile
216
- * layout (always renders the "desktop" row).
217
- *
218
- * Union, not intersection:
219
- * - `onEdit`/`onDelete` are optional — omitting either simply drops that row
220
- * action, which is exactly how clientapp's read-only usage degrades.
221
- * - The "Preview Doc" quick-open link is kept (additive from nukleus-app) and
222
- * gated on both a resolved document *and* `onOpenDocument` being supplied.
223
- * - The collapsible mobile layout is kept (additive from nukleus-app, and not
224
- * actually mentioned by the rollout-plan doc — found by reading the source).
225
- * It's implemented with Tailwind `sm:` responsive classes (both layouts are
226
- * in the DOM, toggled by `hidden`/`sm:hidden`) rather than a JS viewport
227
- * hook, so this stays free of any store/router dependency.
228
- *
229
- * Genuine conflicts resolved (not just formatting):
230
- * - Lead-agent avatar `entityType`: nukleus-app used `"agency"` while passing
231
- * only a flattened `name` string (no `firstName`/`lastName`). `EntityAvatar`'s
232
- * `"agency"` initials fallback reads `firstName`/`lastName`, not `name` — so
233
- * nukleus-app's original call site would always fall back to "?" for any
234
- * lead agent without a profile photo. clientapp used `"initials"`, which
235
- * correctly derives initials from a plain `name` string. This component uses
236
- * `"initials"` (clientapp's choice), both to fix that latent bug and because
237
- * this component only ever receives a flattened `lead_agent_name` string.
238
- * - Lead-agent name formatting: nukleus-app abbreviated it via a local
239
- * `getInitialFullName(name, null, true)` helper to "J. Smith"; clientapp
240
- * rendered the full name as-is. That abbreviation helper isn't part of this
241
- * design system and is a display nicety, not core behavior, so this
242
- * component renders `lead_agent_name` verbatim (clientapp's behavior). An
243
- * adapter that wants the abbreviated form can format the string itself
244
- * before passing it in.
245
- * - Brand avatar size: nukleus-app hard-coded `w-[34px] h-[34px]` on top of
246
- * `size="sm"` (overriding the scale to a bespoke value); clientapp left the
247
- * standard `size="sm"` (24px) in place. Kept clientapp's behavior — fighting
248
- * a documented size step with a one-off pixel override is the smell here,
249
- * not the other way around. `className` is still exposed if 34px turns out
250
- * to be the intentional spec.
251
- *
252
- * Revisited after this component shipped: clientapp's real `ManualDealCard`
253
- * has since converged onto the same aside/tracking-row/payment-footer shape
254
- * `ProjectDealCard` already had (its `DealAside`/`DealDesktopCard` are shared
255
- * between both of its card types), independently of this package. Ported
256
- * into the desktop layout: a status pill (always literal "Complete" — a past
257
- * deal has no Active/Upcoming state, so this isn't `ProjectDealCard`'s own
258
- * `statusLabel()`), a Client/Agency/Third-Party-paid tracking row (always
259
- * `done` — a past deal is definitionally fully settled, same as clientapp's
260
- * `getPastDealPaymentProgress`'s synthetic fully-paid values), and a payment
261
- * progress footer (always 100%, "Fully Paid"). `asideFooter` is the same
262
- * generic slot `ProjectDealCard` has, for clientapp's per-deal commission
263
- * line ("$X to you · Y% agency commission") — this package has no opinion on
264
- * what goes there. Desktop only for now; the mobile layout's structure
265
- * doesn't share clientapp's `DealMobileCard`/`DealCollectedSummary`
266
- * abstraction the way the desktop one does, a separate, bigger gap left for
267
- * its own decision later.
268
- */
269
93
  interface ManualDealDocumentRef {
270
- /** Resolved, directly-fetchable URL for the attached document — a signed/serve
271
- * URL (nukleus-app) or a public URL (clientapp), whatever the host app's
272
- * adapter resolves it to. */
94
+ /** Resolved, directly-fetchable URL; the adapter decides how to get there. */
273
95
  url: string;
274
96
  /** Display name for the document, when known. */
275
97
  name?: string | null;
@@ -294,17 +116,12 @@ interface ManualDealMetadata {
294
116
  notes?: string | null;
295
117
  document_name?: string | null;
296
118
  document_url?: string | null;
297
- /** nukleus-app-only shape for an internally-uploaded document; clientapp
298
- * never populates this and relies solely on the flattened `document_*` pair. */
299
119
  uploaded_document?: {
300
120
  name: string;
301
121
  url: string;
302
122
  } | null;
303
- /** The current field for the preview dialog's "Contract Summary" section.
304
- * `notes` is the legacy key for rows written before this field existed. */
123
+ /** Current "Contract Summary" field; `notes` is the legacy key it replaced. */
305
124
  summary?: string | null;
306
- /** Terms read from the uploaded contract via each app's own AI extraction
307
- * flow. Both apps' real data already has this identical shape. */
308
125
  contract_details?: MarketingDealContractDetails | null;
309
126
  }
310
127
  interface ManualDeal {
@@ -312,38 +129,23 @@ interface ManualDeal {
312
129
  metadata: ManualDealMetadata;
313
130
  company_name?: string | null;
314
131
  company_avatar_url?: string | null;
315
- /** Pre-resolved display name for the deal's lead agent. nukleus-app derives
316
- * this from `lead_agent_profile ?? created_by_profile`; clientapp already
317
- * has it flattened. Resolving which profile wins is adapter work, not this
318
- * component's — it only ever renders the final string. */
132
+ /** Pre-resolved by the adapter -- this component only ever renders the string. */
319
133
  lead_agent_name?: string | null;
320
134
  lead_agent_avatar_url?: string | null;
321
135
  }
322
- /** Resolves the one attached document, whichever of the two historical shapes
323
- * it was stored under. Returns `null` when the deal has no document, in which
324
- * case neither this card nor `ManualDealPreviewDialog` render a document
325
- * affordance. */
136
+ /** Resolves the attached document from either historical shape. Returns `null` if none. */
326
137
  declare function resolveDealDocument(meta: ManualDealMetadata): ManualDealDocumentRef | null;
327
138
  interface ManualDealCardProps {
328
139
  deal: ManualDeal;
329
140
  onPreview: (deal: ManualDeal) => void;
330
- /** Omit to hide the "Edit" row action entirely (clientapp's read-only usage). */
141
+ /** Omit to hide the "Edit" row action entirely. */
331
142
  onEdit?: (deal: ManualDeal) => void;
332
- /** Omit to hide the "Delete" row action entirely (clientapp's read-only usage). */
143
+ /** Omit to hide the "Delete" row action entirely. */
333
144
  onDelete?: (deal: ManualDeal) => void;
334
- /** Required only insofar as a document is actually attached — the "Preview
335
- * Doc" link only renders when both a document resolves (see
336
- * `resolveDealDocument`) and this is supplied. Never call `window.open()` or
337
- * a document-fetch service directly from this package. */
145
+ /** Renders the "Preview Doc" link only once a document resolves and this is supplied. */
338
146
  onOpenDocument?: (doc: ManualDealDocumentRef) => void;
339
- /** Passed straight through to this card's `EntityAvatar` instances. See
340
- * `EntityImageResolver` for why this package can't resolve storage paths
341
- * itself. */
342
147
  resolveImageUrl?: EntityImageResolver;
343
- /** Rendered at the end of the desktop layout's amount/status column,
344
- * after the status pill -- e.g. a commission breakdown. Same slot as
345
- * `ProjectDealCard`'s `asideFooter`; this package has no opinion on what
346
- * goes here. Desktop only for now -- see module doc. */
148
+ /** Rendered at the end of the desktop amount/status column, e.g. a commission breakdown. */
347
149
  asideFooter?: ReactNode;
348
150
  className?: string;
349
151
  }
@@ -353,147 +155,16 @@ interface ManualDealPreviewDialogProps {
353
155
  deal: ManualDeal | null;
354
156
  open: boolean;
355
157
  onOpenChange: (open: boolean) => void;
356
- /** Omit to hide the "Edit Deal" footer button entirely (clientapp's
357
- * read-only usage). */
158
+ /** Omit to hide the "Edit Deal" footer button entirely. */
358
159
  onEdit?: (deal: ManualDeal) => void;
359
- /** Never call `window.open()` or a document-fetch service directly from
360
- * this package — see the file-level comment for why the two source apps'
361
- * behavior couldn't be unified here. */
160
+ /** Required: document-opening behavior differs per host app, so it's always adapter-supplied. */
362
161
  onOpenDocument: (doc: ManualDealDocumentRef) => void;
363
- /** Photo of the client whose page this deal is viewed from, shown beside
364
- * "Client Name". Omit to show just the name (no avatar). */
162
+ /** Photo of the client whose page this deal is viewed from. Omit to show just the name. */
365
163
  clientImageUrl?: string | null;
366
- /** Passed straight through to this dialog's `EntityAvatar` instances. */
367
164
  resolveImageUrl?: EntityImageResolver;
368
165
  }
369
166
  declare function ManualDealPreviewDialog({ deal, open, onOpenChange, onEdit, onOpenDocument, clientImageUrl, resolveImageUrl, }: ManualDealPreviewDialogProps): react.JSX.Element | null;
370
167
 
371
- /**
372
- * Reconciled from two independent implementations:
373
- * - nukleus-app's `ProjectDealCard.tsx` — superset: gates the "Collab"
374
- * link/badge on project membership, has a demo-mode fallback (non-member
375
- * -of-org "explorable" projects swap the link for a toast-triggering
376
- * button), shows a "N of M payments" line, and has an entirely separate
377
- * collapsible mobile layout (chevron + brand/amount summary row, expanding
378
- * to stats/progress/footer).
379
- * - nukleus-clientapp's `ProjectDealCard.tsx` — no membership gate at all (see
380
- * bug below), no demo-mode concept, no payments-count line, and a single
381
- * layout used at every viewport width, with its own more defensive
382
- * responsive wrapping for the tracking row.
383
- *
384
- * ## Confirmed bug: unconditional "Collab" link (fixed here)
385
- * nukleus-app calls `useGetProjectMembersQuery` and only renders the "Collab"
386
- * footer link when the current user `isProjectMember`; clientapp's card has
387
- * **no membership gate at all** — the link renders unconditionally. A
388
- * clientapp user linked to the org but not individually added as a
389
- * `project_members` row can click through to a project detail page that then
390
- * immediately bounces them for failing its own membership check. Confirmed by
391
- * reading both files in full; this is not a reconciliation artifact.
392
- *
393
- * This package can't import RTK Query (no data-fetching in a shared
394
- * presentational component), so the membership check itself has to live in
395
- * each app's adapter/hook. To stop a call site from ever *forgetting* that
396
- * check — or from treating "still loading" as "show the link", which is the
397
- * exact shape of bug clientapp shipped — `collabMembership` is a **required,
398
- * explicit tri-state** (`"loading" | "member" | "not-member"`) rather than an
399
- * optional boolean:
400
- * - Required means omitting it is a type error, not a silent default.
401
- * - Tri-state means there is no boolean "both missing and false look the
402
- * same" ambiguity — "loading" is its own named state, and this component
403
- * treats it identically to "not-member" (hidden), which is also exactly
404
- * nukleus-app's original runtime behavior (`!!members?.find(...)` is
405
- * `false` while `members` is still `undefined`). The link can only ever
406
- * render when the caller has explicitly resolved and supplied `"member"`.
407
- * A plain `isProjectMember?: boolean` was considered and rejected — making
408
- * it required-but-boolean still lets a lazy adapter write
409
- * `isProjectMember={someQuery.data?.find(...) !== undefined}` without ever
410
- * having had to name the loading state, whereas the tri-state forces that
411
- * decision into the open at the call site.
412
- *
413
- * ## Mobile accordion
414
- * Verified nukleus-app's collapsed/expanded mobile behavior is real
415
- * open/closed state (a chevron button toggles `isExpanded`), not just a
416
- * responsive layout swap — but that's exactly what `ManualDealCard` (this
417
- * same directory) already does: Tailwind `sm:hidden`/`hidden sm:flex` decides
418
- * *which* layout is in the DOM, and a local `useState` drives the
419
- * expand/collapse *within* the mobile one. Ported faithfully using that same
420
- * established convention, so this stays store/router-free. The mobile
421
- * layout's own card chrome (bordered, rounded, standalone) and the desktop
422
- * layout's chrome (flush list row, `border-b`) are genuinely different
423
- * between the two apps' originals and are kept as-is rather than forced
424
- * under one shared wrapper style.
425
- *
426
- * ## Other genuine conflicts resolved (not formatting)
427
- * - Tracking row on tablet widths: nukleus-app hides the whole
428
- * deliverables/paid-status row between `sm` and `xl` (`hidden xl:flex`) —
429
- * real content just disappears at tablet widths. clientapp solves the same
430
- * "N items don't fit in a row" problem by reflowing into a responsive grid
431
- * instead (`grid grid-cols-2 md:grid-cols-3 lg:flex`), never hiding it.
432
- * Kept clientapp's grid — it's strictly better (no hidden content) and
433
- * doesn't conflict with keeping the mobile accordion, since the accordion
434
- * only applies below `sm` and this row only applies at `sm` and up.
435
- * - Lead/owner avatar `entityType`: same latent bug as `ManualDealCard` —
436
- * nukleus-app used `"agency"` while only ever passing a flattened `name`
437
- * (not `firstName`/`lastName`, which is what `"agency"` initials read), so
438
- * it always fell back to "?" for an owner with no photo. clientapp used
439
- * `"initials"`, which correctly derives initials from `name`. Kept
440
- * `"initials"`, same reasoning as `ManualDealCard`.
441
- * - Owner name abbreviation: originally reconciled as "render verbatim"
442
- * (clientapp's behavior when this file was first built). Revisited when
443
- * clientapp's `ProjectDealCard.tsx` was found to have since grown its own
444
- * `getInitialFullName(name, null, true)` abbreviation ("J. Smith") --
445
- * matching what nukleus-app's (by-then-retired) local component already
446
- * did. Both apps' real current behavior agrees, so this renders abbreviated
447
- * via `@nukleus-sports/core`'s `abbreviatePersonName` (the `EntityAvatar`
448
- * still gets the raw `owner_name` for initials -- only the visible text
449
- * span is abbreviated, same split as both apps' originals).
450
- * - Owner-name empty fallback: nukleus-app used a literal `"--"`; clientapp
451
- * used `"—"` (em dash). `formatDealDate` (from `@nukleus-sports/core`)
452
- * already established "—" as this design system's missing-value sentinel,
453
- * so that's what's used here instead of introducing a second glyph.
454
- * - Brand avatar size: nukleus-app hard-coded `w-[34px] h-[34px]` on top of
455
- * `size="sm"`; clientapp left the standard `size="sm"` (24px) in place.
456
- * Kept clientapp's behavior, same reasoning as `ManualDealCard`.
457
- * - Owner avatar size: nukleus-app used `size="sm"` for the owner's
458
- * `EntityAvatar`; clientapp used `size="xs"`. Kept `"sm"` — it's what
459
- * `ManualDealCard`'s own lead-agent avatar (the equivalent "who owns this"
460
- * row in this same package) already established, and consistency across
461
- * this package's cards outweighs either single original's choice.
462
- * - "Complete" vs "Completed" status label: nukleus-app relabels the
463
- * `"Complete"` status to "Completed" in its badge text (both its layouts);
464
- * clientapp renders the raw status value. Kept nukleus-app's relabel (it's
465
- * the grammatically correct one) and, since "Completed" is longer than
466
- * clientapp's fixed `w-[104px]` badge was sized for, dropped that fixed
467
- * width in favor of nukleus-app's auto-sized badge so the longer label
468
- * never clips.
469
- * - Collected-amount trailing space: nukleus-app's template literal leaves a
470
- * trailing space when `total_collected` is 0 (`` `${fmtUSD(...)} ` ``
471
- * with an empty suffix); clientapp's has no such gap. Kept clientapp's.
472
- * - First footer span's flex sizing: clientapp adds `min-w-0` alongside
473
- * `flex-1` so `truncate`/wrapping actually engages instead of overflowing
474
- * the card; nukleus-app's omits it. Kept clientapp's (a strict fix, same
475
- * `min-w-0` reasoning already documented in `ManualDealCard`/`TrackingItem`).
476
- * - "N of M payments" line: only nukleus-app's RPC/type returns
477
- * `payments_total`/`payments_paid` — clientapp's doesn't have these fields
478
- * and never rendered the line. Kept as an *additive* capability gated on
479
- * both fields being supplied, rather than dropped or forced to be required.
480
- * - Demo-mode link/button swap: nukleus-app swaps the "Collab" link for a
481
- * plain button that triggers a demo-limit toast when a project isn't
482
- * "explorable" in demo mode. `isDemoMode`/`showDemoLimitToast` are
483
- * app-internal concepts this package can't import. Generalized into
484
- * `onCollabClick`: when supplied, the "Collab" affordance renders as a
485
- * `<button>` calling it instead of an `<a href>` — nukleus-app's adapter
486
- * can wire its demo-mode toast through this; clientapp simply never passes
487
- * it and always gets a real link.
488
- * - Commission line: clientapp renders a per-deal commission breakdown
489
- * ("$X to you · Y% agency commission") in the aside column, after the
490
- * status pill; nukleus-app has no equivalent at all. Rather than teach
491
- * this package the concept of a commission, `asideFooter` is a generic
492
- * slot rendered in that exact spot — nukleus-app simply never passes it.
493
- *
494
- * No icon needed inlining — `ArrowDownFormIcon`, `CheckRingRoundIcon`, and
495
- * `XsViewInvoiceIcon` are all already in `@nukleus-sports/icons`.
496
- */
497
168
  interface ProjectDeal {
498
169
  project_id: string;
499
170
  project_title: string;
@@ -512,8 +183,8 @@ interface ProjectDeal {
512
183
  total_equity_shares: number;
513
184
  deliverables_total: number;
514
185
  deliverables_met: number;
515
- /** Only present in nukleus-app's RPC today — clientapp's doesn't return
516
- * these. The "N of M payments" line only renders when both are supplied. */
186
+ /** Only one app's RPC returns these; the "N of M payments" line only
187
+ * renders when both are supplied. */
517
188
  payments_total?: number;
518
189
  payments_paid?: number;
519
190
  client_paid: boolean;
@@ -522,36 +193,27 @@ interface ProjectDeal {
522
193
  third_party_paid: boolean;
523
194
  }
524
195
  /**
525
- * Tri-state result of the caller's own project-membership check (see the
526
- * module doc above for why this is required and not an optional boolean).
527
- * `"loading"` and `"not-member"` are both treated as "hide the Collab
528
- * affordance" — only `"member"` ever shows it.
196
+ * Required tri-state, not an optional boolean, so a caller must name "loading"
197
+ * explicitly instead of treating it the same as "not a member" by default.
529
198
  */
530
199
  type ProjectCollabMembership = "loading" | "member" | "not-member";
531
200
  interface ProjectDealCardProps {
532
201
  deal: ProjectDeal;
533
202
  isCompleted: boolean;
534
- /** Required — see module doc. Gates every "Collab"/"Collab Hub" affordance
535
- * on this card. */
203
+ /** Gates every "Collab"/"Collab Hub" affordance; see `ProjectCollabMembership`. */
536
204
  collabMembership: ProjectCollabMembership;
537
- /** Destination for the "Collab"/"Collab Hub" link, e.g.
538
- * `/projects/${deal.project_id}?tab=overview`. Rendered as a plain
539
- * `<a href>` — never a `react-router` `Link` — so this package carries no
540
- * router dependency. */
205
+ /** Rendered as a plain `<a href>`, never a router `Link` -- this package
206
+ * carries no router dependency. */
541
207
  collabHref: string;
542
- /** Supply to replace the `<a href={collabHref}>` with a `<button>` that
543
- * calls this instead (e.g. nukleus-app's demo-mode upsell toast for a
544
- * non-"explorable" project). Omit for a normal link. */
208
+ /** Swaps the Collab affordance from a link to a `<button>` calling this
209
+ * (e.g. a demo-mode upsell toast). Omit for a normal link. */
545
210
  onCollabClick?: (e: MouseEvent<HTMLButtonElement>) => void;
546
- /** Passed straight through to this card's `EntityAvatar` instances. */
547
211
  resolveImageUrl?: EntityImageResolver;
548
- /** Rendered at the end of the amount/status column, after the status pill
549
- * -- e.g. a commission breakdown. This package has no opinion on what
550
- * goes here (clientapp's real cards render a commission line nukleus-app
551
- * has no equivalent for at all); omit for nothing extra. */
212
+ /** Generic slot after the status pill (e.g. a commission breakdown); this
213
+ * package has no opinion on its content. */
552
214
  asideFooter?: ReactNode;
553
215
  className?: string;
554
216
  }
555
217
  declare function ProjectDealCard({ deal, isCompleted, collabMembership, collabHref, onCollabClick, resolveImageUrl, asideFooter, className, }: ProjectDealCardProps): react.JSX.Element;
556
218
 
557
- export { ContractDetailsCard, type ContractDetailsCardDeliverable, type ContractDetailsCardProps, type ContractDetailsCardWarning, DealEmptyState, type DealEmptyStateProps, ENTITY_AVATAR_SIZE_PX, EntityAvatar, type EntityAvatarProps, type EntityAvatarSize, type EntityImageResolver, type EntityType, type ManualDeal, ManualDealCard, type ManualDealCardProps, type ManualDealDocumentRef, type ManualDealMetadata, ManualDealPreviewDialog, type ManualDealPreviewDialogProps, type MarketingDealContractDetails, type ProjectCollabMembership, type ProjectDeal, ProjectDealCard, type ProjectDealCardProps, type RowAction, RowActionsDropdown, type RowActionsDropdownProps, resolveDealDocument };
219
+ export { ContractDetailsCard, type ContractDetailsCardDeliverable, type ContractDetailsCardProps, type ContractDetailsCardWarning, DealEmptyState, type DealEmptyStateProps, type ManualDeal, ManualDealCard, type ManualDealCardProps, type ManualDealDocumentRef, type ManualDealMetadata, ManualDealPreviewDialog, type ManualDealPreviewDialogProps, type MarketingDealContractDetails, type ProjectCollabMembership, type ProjectDeal, ProjectDealCard, type ProjectDealCardProps, type RowAction, RowActionsDropdown, type RowActionsDropdownProps, resolveDealDocument };