feat(formation): badge, card and staff deep links on the project page

[manishdixitlfx]

Summary

Part of the Formation Checklist epic (#1965). Adds Formation-stage UI to the project dashboard, gated behind the new FORMATION_ENABLED_FLAG:

• Title badge (FORMATION · <sub-stage>) + subtitle on the project dashboard, with a distinct amber/lock treatment and visibility caption for the Confidential sub-stage
• A new FormationCardComponent in the sidebar: sub-stage pill, announcement date, project slug, and a staff-only deep link into the admin tool
• A "Formation" tag in the project selector's dropdown rows
• No new backend work — everything reads fields already synced via v1→v2 (stage, formation_date, announcement_date)

Scope decisions made during implementation

Several fields/behaviors the ticket asked for don't exist anywhere in the sync pipeline (verified against the live lfx-v2-project-service contract via gh api, not a local checkout). Decided with the ticket owner before implementation:

• Formation lead/coordinator/partner/product contact/trademark status/assigning org, plus the intake block (repository, assigning org, trademark status, logo): Epic 1 was scoped down after this PR was first opened — the application/intake flow that would populate these moved to Epic 2 (Propose a project: application intake, review and accept/decline (Epic 2) #1962). The revised Formation badge, Formation card and staff-only admin-tool deep links on the project page #1955 is explicit that the card renders only fields the synced record already carries, so these are out by ticket scope, not a workaround. An earlier revision of this PR showed executive_director/program_manager/opportunity_owner here as a stand-in (duplicating ProjectStaffCardComponent directly above it in the sidebar); those rows are now removed entirely rather than duplicated, since Epic 1 doesn't call for formation-specific contacts on this card at all. If any of the intake fields (repository_url, logo_url) turn out to be populated independently of intake, they can come back later as ordinary project fields — not as an intake block.
• formation_admin permission: doesn't exist anywhere in the linuxfoundation org. Staff-only gating uses PersonaService.isLFStaff instead (LF-staff team membership) — a materially wider audience than a hypothetical formation-specific grant, but the closest real thing available. This is now tracked as open guard question FGA model change for the formation checklist: new formation types vs. new grants on project #2148: the FGA model defines writer/auditor/participant/item_owner on formation, and Per-project lf-staff tuples replacing ROOT inheritance; withheld on Formation - Confidential #1954 grants LF Staff auditor, not writer — a writer-based guard would hide the deep link from most of staff, so the correct relation is an open architecture decision. Marked with a // TODO(#2148) at the guard site in formation-card.component.ts; guard behavior is unchanged in this PR.
• FormationConfidential stays excluded from the shared project picker (consistent with the name implying pre-announcement secrecy); its own dashboard page still renders normally for anyone already authorized to view it. Epic 1 also excludes Confidential formations end-to-end at the grant layer (Per-project lf-staff tuples replacing ROOT inheritance; withheld on Formation - Confidential #1954), which narrows the title badge's amber/lock treatment's practical audience to lf-formation/lf-legal viewers who do have access — still a coherent visual signal for that audience.

Found and fixed during review (not part of the original diff)

The post-commit reviewer trio caught several real issues across iteration, most notably:

• A duplicate-active-nav-item bug: the ticket asked for a stage-scoped "Formation" nav item, but the only route available (/project/overview) is the same route Dashboard already uses — routerLinkActive can't disambiguate two entries on one path (it ignores fragment/queryParams). Removed the nav item rather than ship a visibly broken sidebar; the badge + card already surface Formation status on that page. Formation badge, Formation card and staff-only admin-tool deep links on the project page #1955 as currently written still asks for this nav item — its bullet needs to be struck or given a distinct destination; that's an issue-text edit, not a code change this PR can make.
• A sidebar entity-mismatch bug: DashboardSidebarComponent is shared by the project, ED, and board-member dashboards, each of which passes a different entity as projectUid — but FormationCardComponent read ProjectContextService.activeProject regardless. Fixed with an explicit showFormationCard opt-in input, defaulting false, set true only by ProjectDashboardComponent where the two are guaranteed to agree.
• Two wrong PCC deep-link URLs, caught and corrected twice: first a ?tab= query param that doesn't exist anywhere in PCC's routing, then a /setup route that only exists on PCC's v1 frontend (environment.urls.pcc resolves to v2). The link now points at the one route confirmed to resolve (/project/:id) — flagging for product/PCC: the real "edit stage" / "set up" destination(s) still need to be named.
• An evictOnWriteAccessLoss() regression: an earlier review-driven fix added startWith(null) to a shared context signal to avoid stale-project flicker, which would have caused vote/survey/mailing-list manage pages to evict a user mid-edit on every project switch. Caught, reverted, and locked in with a regression test.
• A prototype-pollution vector in the stage-label lookup (stage in OBJECT), a duplicate HTTP fetch, several silent catchErrors, and a missing loading guard that briefly asserted "Not set" before data arrived.

Open items for product/design (not blockers, documented here per review)

• EasyCLA/Crowdfunding/Insights/public stats have no project-scoped nav surface today to gate on Formation status — EasyCLA is a personal tab, Crowdfunding and Insights are Me-lens/global links, no "public stats" component exists anywhere. Nothing was gated; a real destination needs to exist first.
• PROJECT_LENS_ALLOWED_STAGES now includes FormationOnHold/FormationDisengaged — this is server-side and unflagged (unlike the rest of this PR's UI), so those projects become picker-visible to all users ahead of the flagged UI reaching them. Doesn't widen data access (the picker is a UX convenience over already-reachable projects), but is a rollout-sequencing call worth a second look. Recommendation: this can be moved behind a flag cheaply — a new ServerFeatureFlag entry (mirroring WeeklyBriefSlack/MarketingOpsFga) gating whether these two stages are added to the set, same pattern already used elsewhere in server-feature-flag.helper.ts. Not implemented in this PR; flagging for a decision.
• The staff-name tooltip ([attr.title] on a non-focusable <span>) was copied verbatim from ProjectStaffCardComponent's existing pattern. Retired on FormationCardComponent itself as part of the Epic 1 scope trim (the contact rows it applied to are gone), but ProjectStaffCardComponent's own instance is untouched — still inherited a11y debt there.
• No e2e coverage for the new empty/error states (unit coverage exists).

Test plan

• yarn lint && yarn format && yarn test && yarn build all pass
• Flag on/off, all 5 Formation sub-stages + Draft sentinel, isLFStaff present/absent — unit tested
• String-content assertion that "PCC" never appears in any rendered state
• Regression test locking in no transient canWrite flip during a project switch
• Manual verification against a real Formation-stage project (none confirmed available in the accessible test tenant as of this PR — may need stubbed data)

Refs #1955. Depends on nothing; #1958 reads the same FORMATION_ENABLED_FLAG constant added here.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Essentials

Run ID: 646cad11-d221-417c-86ea-75d27085c80b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Adds feature-flagged Formation-stage UI to project dashboards and selectors, including LF Staff admin-tool deep links.

Changes:

• Adds Formation stage classification and display helpers.
• Adds dashboard badges, subtitles, selector tags, and a Formation sidebar card.
• Expands project-lens stages and adds unit coverage.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/shared/src/utils/project.utils.ts	Adds Formation stage helpers.
packages/shared/src/utils/project.utils.spec.ts	Tests stage classification.
packages/shared/src/utils/date-time.utils.ts	Adds announcement-date formatting.
packages/shared/src/interfaces/project.interface.ts	Shares resolved staff-row type.
packages/shared/src/interfaces/navigation.interface.ts	Adds Formation metadata to lens items.
packages/shared/src/constants/project-formation.constants.ts	Defines Formation labels and Draft sentinel.
packages/shared/src/constants/index.ts	Exports Formation constants.
packages/shared/src/constants/feature-flags.constants.ts	Defines the Formation feature flag.
apps/lfx-one/src/server/services/navigation.service.ts	Expands stage filtering and maps Formation labels.
apps/lfx-one/src/server/services/navigation.service.spec.ts	Tests navigation filtering and mapping.
apps/lfx-one/src/app/shared/services/sidebar-nav.service.ts	Documents omitted navigation surfaces.
apps/lfx-one/src/app/shared/services/project-context.service.ts	Exposes active-project Formation state.
apps/lfx-one/src/app/shared/services/project-context.service.spec.ts	Tests Formation and write signals.
apps/lfx-one/src/app/shared/components/project-selector/project-selector.component.ts	Adds feature-flag state.
apps/lfx-one/src/app/shared/components/project-selector/project-selector.component.html	Renders Formation selector tags.
apps/lfx-one/src/app/modules/dashboards/project-dashboard/project-dashboard.component.ts	Loads Formation subtitle data.
apps/lfx-one/src/app/modules/dashboards/project-dashboard/project-dashboard.component.spec.ts	Tests badge and subtitle states.
apps/lfx-one/src/app/modules/dashboards/project-dashboard/project-dashboard.component.html	Renders Formation dashboard UI.
apps/lfx-one/src/app/modules/dashboards/components/project-staff-card/project-staff-card.component.ts	Uses the shared staff-row type.
apps/lfx-one/src/app/modules/dashboards/components/formation-card/formation-card.component.ts	Implements Formation card behavior.
apps/lfx-one/src/app/modules/dashboards/components/formation-card/formation-card.component.spec.ts	Tests card states and links.
apps/lfx-one/src/app/modules/dashboards/components/formation-card/formation-card.component.html	Defines Formation card markup.
apps/lfx-one/src/app/modules/dashboards/components/dashboard-sidebar/dashboard-sidebar.component.ts	Adds opt-in Formation card gating.
apps/lfx-one/src/app/modules/dashboards/components/dashboard-sidebar/dashboard-sidebar.component.spec.ts	Tests sidebar gating.
apps/lfx-one/src/app/modules/dashboards/components/dashboard-sidebar/dashboard-sidebar.component.html	Mounts the Formation card.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated no new comments.

Suppressed comments (1)

apps/lfx-one/src/app/modules/dashboards/components/formation-card/formation-card.component.ts:137

• Clear the previous mapping when projectUid changes. toSignal retains the last SFID while the new HTTP request is pending, so after switching between two Formation projects the card temporarily combines the new project's slug/intake data with the old project's admin-tool URL; a staff user can therefore open the wrong project. Mirror initSelectedFoundationSfid() by starting each inner lookup with null (and import startWith) so the link stays hidden until the current UID resolves.

      toObservable(computed(() => (this.isLFStaff() ? this.projectUid() : null))).pipe(
        filter((uid): uid is string => !!uid),
        switchMap((uid) => this.projectService.getProjectSfid(uid))

[Copilot]

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated 1 comment.

Suppressed comments (6)

Previously missed (4) — in code that hasn't changed since the last review.

apps/lfx-one/src/app/modules/dashboards/components/formation-card/formation-card.component.ts:67

• This gates the admin-tool affordance on organization-wide staff membership, but #1955 requires the resolved Formation permission from #2148 and explicitly says participants/item owners must not receive it. The repository's permission model also treats persona/team membership as presentation context, not action authority. Resolve the Formation relation and check that permission before rendering the link.
  apps/lfx-one/src/app/shared/services/sidebar-nav.service.ts:465
• The linked #1955 requirement still calls for a stage-scoped Formation navigation item. This comment records that the requirement is intentionally omitted, but it does not resolve the acceptance-criteria mismatch. Either add a distinct destination and restore the item, or update the issue/scope before merging.
  apps/lfx-one/src/server/services/navigation.service.ts:32
• Adding these stages to the server-side query makes On Hold and Disengaged projects appear in every user's picker even when formation-enabled is false. That makes the dark-launched feature observable before rollout; the client-side tag gate cannot hide the rows themselves. Gate this expansion with a server feature flag or defer it until the rollout is enabled.
  apps/lfx-one/src/app/modules/dashboards/project-dashboard/project-dashboard.component.html:28
• This user-facing caption says a Confidential formation can become visible by invitation, but Epic 1 explicitly excludes Confidential formations from invitations. Remove “until invited” so the page does not promise an unavailable visibility path.

apps/lfx-one/src/app/shared/services/project-context.service.ts:292

• toSignal retains the previous emission while the new getProject request is pending. Now that activeProject supplies rendered Formation data, switching from project A to B temporarily combines B's heading/context with A's stage, slug, and admin-link inputs. Preserve canWrite safely without retaining cross-project display data—for example, track writer resolution separately or key the emitted project to the current context.

          // organizer mid-edit. Formation's badge/card briefly showing the previous project's stage
          // during a switch is an accepted, pre-existing trade-off (this is the same staleness
          // canWrite itself already had before this ticket).
          return this.projectService.getProject(ctx.slug, false);

apps/lfx-one/src/app/modules/dashboards/components/formation-card/formation-card.component.ts:116

• On a second project UID, switchMap cancels the prior request but the signal continues exposing the prior SFID until the new lookup emits. The card for project B can therefore render an admin URL for project A, allowing staff to open the wrong project. Start each inner SFID lookup with null and cover a Formation-to-Formation switch in the test.

      toObservable(computed(() => (this.isLFStaff() ? this.projectUid() : null))).pipe(
        filter((uid): uid is string => !!uid),
        switchMap((uid) => this.projectService.getProjectSfid(uid))

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated 4 comments.

Suppressed comments (2)

apps/lfx-one/src/app/shared/services/project-context.service.ts:103

• These Formation signals expose the previous project's stage while a new context fetch is pending because toSignal retains its last value. The dashboard heading already switches to the new context, so it can temporarily show project A's badge/card—and its admin link—under project B. Preserve the stale value only for canWrite, and make Formation state null unless the fetched project's UID matches the active context.

  public readonly activeProjectFormationSubStage: Signal<string | null> = computed(() => getFormationSubStageLabel(this.activeProject()?.stage));

  /** True when the current active context is in Draft or any Formation sub-stage. */
  public readonly isActiveProjectInFormation: Signal<boolean> = computed(() => isFormationStage(this.activeProject()?.stage));

apps/lfx-one/src/app/modules/dashboards/components/formation-card/formation-card.component.html:52

• #1955 requires two distinct staff deep links—“Edit stage” and “Set up”—to the admin tool's Project Definition, but this renders one generic “Open” link. The unresolved PCC destination should be confirmed before merging; then render both required actions rather than silently dropping them.

            Open in admin tool ↗

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated 2 comments.

Suppressed comments (4)

apps/lfx-one/src/server/services/navigation.service.ts:16

• The current #1955 acceptance criteria explicitly require no Confidential-specific UI gate: direct-grant holders should see the project, while query-service authorization excludes everyone else. This exclusion also makes fetchSelectedItem reject an authorized Confidential selection, so these projects disappear from the selector despite the updated requirement. Include FormationConfidential and rely on the access-filtered query.

 * `FormationConfidential` is intentionally excluded (GH-1955): the name implies pre-announcement
 * secrecy, so a Confidential project should not be listed by name in the shared project picker.
 * Its own dashboard page still renders normally for anyone already authorized to view it.

apps/lfx-one/src/app/shared/services/sidebar-nav.service.ts:499

• This leaves a current #1955 acceptance criterion unimplemented. The issue now requires the Formation nav item to return with a distinct Formation route; it no longer treats the missing destination as an open product question. Add the flagged route and point the nav item at it rather than documenting the omission as final.

  // GH-1955: a separate "Formation" nav item was tried here and removed on review — pointing it at
  // the same '/project/overview' route as Dashboard means both entries render highlighted-active
  // simultaneously (sidebar.component.html's routerLinkActive ignores fragment and queryParams, so
  // neither can disambiguate two entries sharing one path). The Formation badge/subtitle and sidebar
  // card already surface "you are in Formation" on that page; a real destination (a distinct route)
  // is needed before a dedicated nav item can ship — flagged for product/design.

apps/lfx-one/src/app/modules/dashboards/components/formation-card/formation-card.component.html:52

• #1955 requests two distinct deep links—“Edit stage” and “Set up”—into the project definition. A single generic project-page link does not satisfy either action, so the deep-link portion of this PR remains incomplete. The actual PCC destinations need to be confirmed and represented separately before this is considered implemented.

            Open in admin tool ↗

apps/lfx-one/src/app/shared/services/project-context.service.ts:292

• Keeping the previous Project value during a context switch now affects more than the pre-existing canWrite boolean: the new header and Formation card can show project A’s stage, slug, announcement date, and admin link while the page heading already names project B. On a slow request this presents an actionable link for the wrong project. Preserve the old value only for the write-access eviction logic, and clear or context-key the display-facing project data as soon as activeContext changes.

          // Deliberately no startWith(null) here, unlike initSelectedFoundationSfid below: canWrite
          // reads this signal, and evictOnWriteAccessLoss() (vote/survey/mailing-list manage pages)
          // takes the *first* true→false transition as a genuine access loss and navigates away. A
          // transient null on every project switch — not just a real loss of access — would evict an
          // organizer mid-edit. Formation's badge/card briefly showing the previous project's stage
          // during a switch is an accepted, pre-existing trade-off (this is the same staleness
          // canWrite itself already had before this ticket).
          return this.projectService.getProject(ctx.slug, false);

[Copilot]

Pull request overview

Copilot reviewed 31 out of 31 changed files in this pull request and generated no new comments.

Suppressed comments (4)

apps/lfx-one/src/app/shared/services/project-context.service.ts:103

• On /project/overview, selecting another project updates activeContext without recreating the route, but activeProject intentionally retains the prior response while the next request is pending. These new computations therefore keep the old Formation state active beside the new project's heading, and the mounted card can temporarily show the previous project's slug/date. Key Formation state to activeContextUid() so the UI clears during that mismatch while leaving the deliberately sticky canWrite behavior unchanged.

  public readonly activeProjectFormationSubStage: Signal<string | null> = computed(() => getFormationSubStageLabel(this.activeProject()?.stage));

  /** True when the current active context is in Draft or any Formation sub-stage. */
  public readonly isActiveProjectInFormation: Signal<boolean> = computed(() => isFormationStage(this.activeProject()?.stage));

apps/lfx-one/src/app/shared/services/sidebar-nav.service.ts:499

• The current #1955 acceptance criteria require a distinct Formation route and nav destination; they explicitly say the previously removed same-route item must come back once it has that destination. This comment records the old decision but leaves that required surface unimplemented, so the ticket is not complete until the route and flag-gated nav item are added (or the issue scope is changed).

  // GH-1955: a separate "Formation" nav item was tried here and removed on review — pointing it at
  // the same '/project/overview' route as Dashboard means both entries render highlighted-active
  // simultaneously (sidebar.component.html's routerLinkActive ignores fragment and queryParams, so
  // neither can disambiguate two entries sharing one path). The Formation badge/subtitle and sidebar
  // card already surface "you are in Formation" on that page; a real destination (a distinct route)
  // is needed before a dedicated nav item can ship — flagged for product/design.

apps/lfx-one/src/app/modules/dashboards/components/formation-card/formation-card.component.html:52

• #1955 requests two actionable deep links—“Edit stage in admin tool” and “Set up in admin tool”—to the project-definition destination. This generic project-page link provides neither requested action, so the deep-link portion remains incomplete. Resolve the actual admin-tool destinations before merging or explicitly rescope the issue.

            Open in admin tool ↗

apps/lfx-one/src/server/services/navigation.service.ts:33

• The current #1955/#1965 requirements explicitly supersede this exclusion: Confidential formations must appear like any other formation for users whose project grant lets the query return them, with access control as the only visibility gate. Leaving FormationConfidential out here also makes fetchSelectedItem discard an authorized current selection. Include it in the allowed-stage set instead of adding a second confidentiality policy in navigation.

  ProjectStage.FormationOnHold,
  ProjectStage.FormationDisengaged,
]);