glint-project-navigation

The glint-project-navigation component is the main navigation control for a project. It renders navigation options provided by plugins and allows users to browse and select different parts of a project.

The component's navigation items are generated by ProjectFacet and ProjectFacetProvider services, which are dynamically contributed by plugins.

Usage

<glint-project-navigation
  [project]="project"
  (navigate)="onNavigate($event)"
  (selection)="onSelection($event)"
></glint-project-navigation>

Properties and Events

Property	Type	Description
[project]	ProjectData	A ProjectData object, typically fetched from the ModelService. This object provides the context for generating the navigation facets.
(navigate)	EventEmitter<ProjectFacet | ProjectFacetItem>	An event that fires when a user selects a navigation option (a facet) or a nested item. The event's value is the selected ProjectFacet or ProjectFacetItem.
(selection)	EventEmitter<ModelProjection>	An event that fires when a user selects a navigation option. The event's value is the ModelProjection object that the selected facet or item represents. This is the model element that should be displayed in the editor.

---

The Role of ProjectFacet

Each top-level navigation option (Programs or project-level views) is represented by a ProjectFacet. A facet defines the appearance and behavior of a navigation item.

interface ProjectFacet {
  readonly id: string; // A unique identifier for the facet instance.
  readonly title: string; // The short label displayed in the navigation menu.
  readonly priority: number; // A number from 1 to 10 that determines the facet's position. Higher numbers are placed first.
  readonly icon?: VariableIcon; // The icon to display next to the title.

  /**
   * Retrieves the ModelProjection that this facet represents.
   * This method is called when the user selects the facet.
   */
  model(): Promise<ModelProjection>;

  /**
   * Returns a list of nested navigation options (e.g., modules, sub-items).
   */
  items(): Promise<ProjectFacetItem[]>;

  /**
   * Returns a list of available views for the selected model.
   * These views are used by the editor to determine which components to render.
   */
  views(): Promise<ProjectViewCategory[]>;

  /**
   * Optional. If implemented, a link to "show more" items will be displayed.
   * This is useful for reducing clutter while still providing access to less-frequently used items.
   */
  moreItems?(): Promise<ProjectFacetItem[]>;
}

ProjectFacetItem

A ProjectFacetItem represents a nested navigation option within a ProjectFacet.

interface ProjectFacetItem {
  readonly id: string; // A unique identifier for the item instance.
  readonly title: string; // The short label displayed in the navigation menu.
  readonly facet: ProjectFacet; // A reference to the parent facet.

  /**
   * Retrieves the ModelProjection that this item represents.
   * This method is called when the user selects the item.
   */
  model(): Promise<ModelProjection>;

  /**
   * Optional. Returns a list of available views for this item.
   */
  views?(): Promise<ProjectViewCategory[]>;
}

---

ProjectFacetProvider: Creating Facets

ProjectFacet instances are not created directly. Instead, they are generated by a ProjectFacetProvider. A provider is a service that implements the ProjectFacetProvider interface and is responsible for creating facets based on the project's data.

interface ProjectFacetProvider {

  /**
   * Optional. Creates project-level facets. These facets are global and not tied to a specific program.
   * This method is called once per project.
   */
  getProjectFacets?(project: ProjectData): Promise<ProjectFacet[]>;

  /**
   * Optional. Creates facets for specific program instances within a project.
   * This method is called for each ProgramData instance found in the project.
   */
  getProgramFacets?(program: ProgramData): Promise<ProjectFacet[]>;
}

Providing ProjectFacetProvider Services

To make your ProjectFacetProvider available to the glint-project-navigation component, you must register it as a provider using the PROJECT_FACET_PROVIDERS injection token. This is typically done within a plugin's PluginBuilder.

For example, this service provides a facet for programs with type elements::Application:

@Injectable()
export class MyApplicationFacetService implements PluginBuilder, ProjectFacetProvider {

  async build(): Promise<PluginBuildResult> {
    return {
      providers: [
        {
          provide: PROJECT_FACET_PROVIDERS,
          multi: true,
          useValue: this
        }
      ]
    }
  }

  async getProgramFacets(program: ProgramData) {
    if (program.elementId.type === 'elements::Application') {
      return [new MyApplicationFacet({ program })]
    } else {
      return []
    }
  }
  
}