feat: create ion tour

projects/ion/src/lib/core/types/index.ts

@@ -35,4 +35,5 @@ export * from './tab-group';
 export * from './table';
 export * from './tag';
 export * from './tooltip';
+export * from './tour';
 export * from './triple-toggle';

projects/ion/src/lib/core/types/tour.ts

@@ -0,0 +1,27 @@
+import { EventEmitter } from '@angular/core';
+
+import { PopoverButtonsProps, PopoverPosition, PopoverProps } from './popover';
+
+export interface IonTourStepProps {
+  ionStepId: string;
+  ionTourId: string;
+  ionStepTitle?: PopoverProps['ionPopoverTitle'];
+  ionStepBody?: PopoverProps['ionPopoverBody'];
+  ionPrevStepId?: IonTourStepProps['ionStepId'];
+  ionNextStepId?: IonTourStepProps['ionStepId'];
+  ionPrevStepBtn?: PopoverButtonsProps;
+  ionNextStepBtn?: PopoverButtonsProps;
+  ionStepPosition?: PopoverPosition;
+  ionStepMarginToContent?: number;
+  ionStepBackdropPadding?: number;
+  ionStepCustomClass?: string;
+  ionStepBackdropCustomClass?: string;
+  ionOnPrevStep?: EventEmitter<void>;
+  ionOnNextStep?: EventEmitter<void>;
+  ionOnFinishTour?: EventEmitter<void>;
+  target?: DOMRect;
+}
+
+export interface IonStartTourProps {
+  tourId?: string;
+}

projects/ion/src/lib/position/position.service.ts

@@ -55,6 +55,10 @@ export class IonPositionService {
   private currentPosition: IonPositions;
   private pointAtCenter = true;
 
+  public setElementPadding(padding: number): void {
+    this.elementPadding = padding;
+  }
+
   public setHostPosition(position: DOMRect): void {
     this.hostPosition = position;
   }

projects/ion/src/lib/tour/index.ts

@@ -0,0 +1,3 @@
+export * from './tour-step.directive';
+export * from './tour.module';
+export * from './tour.service';

projects/ion/src/lib/tour/mocks/tour-basic-demo.component.ts

@@ -0,0 +1,135 @@
+import { Component } from '@angular/core';
+
+import { IonTourService } from '../tour.service';
+import { IonTourStepProps, PopoverPosition } from '../../core/types';
+
+export enum DemoSteps {
+  UPLOAD = 'upload',
+  SAVE = 'save',
+  MORE_OPTIONS = 'more_options',
+}
+
+export const STEP1_MOCK: IonTourStepProps = {
+  ionStepTitle: 'Upload Action',
+  ionTourId: 'basic-demo',
+  ionStepId: DemoSteps.UPLOAD,
+  ionNextStepId: DemoSteps.SAVE,
+  ionStepPosition: PopoverPosition.BOTTOM_CENTER,
+  ionPrevStepBtn: { label: 'Close' },
+};
+
+export const STEP2_MOCK: IonTourStepProps = {
+  ionStepTitle: 'Save Action',
+  ionTourId: 'basic-demo',
+  ionStepId: DemoSteps.SAVE,
+  ionPrevStepId: DemoSteps.UPLOAD,
+  ionNextStepId: DemoSteps.MORE_OPTIONS,
+  ionStepPosition: PopoverPosition.BOTTOM_CENTER,
+};
+
+export const STEP3_MOCK: IonTourStepProps = {
+  ionStepTitle: 'More Options',
+  ionTourId: 'basic-demo',
+  ionStepId: DemoSteps.MORE_OPTIONS,
+  ionPrevStepId: DemoSteps.SAVE,
+  ionStepPosition: PopoverPosition.RIGHT_CENTER,
+  ionNextStepBtn: { label: 'Finish' },
+};
+
+@Component({
+  template: `
+    <style>
+      div {
+        height: 100%;
+        margin-top: 200px;
+        display: flex;
+        flex-direction: column;
+        justify-content: center;
+        align-items: center;
+        gap: 100px;
+
+        main {
+          display: flex;
+          gap: 10px;
+        }
+      }
+
+      span {
+        color: #8d93a5;
+        font-size: 14px;
+      }
+    </style>
+
+    <div>
+      <ion-button label="Begin tour" (ionOnClick)="startTour()"> </ion-button>
+
+      <main>
+        <ion-button
+          label="Upload"
+          type="secondary"
+          ionTourStep
+          [ionStepTitle]="step1.ionStepTitle"
+          [ionStepPosition]="step1.ionStepPosition"
+          [ionTourId]="step1.ionTourId"
+          [ionStepId]="step1.ionStepId"
+          [ionNextStepId]="step1.ionNextStepId"
+          [ionPrevStepBtn]="step1.ionPrevStepBtn"
+          [ionStepBody]="uploadStepContent"
+        ></ion-button>
+        <ion-button
+          label="Save"
+          ionTourStep
+          [ionTourId]="step2.ionTourId"
+          [ionStepId]="step2.ionStepId"
+          [ionPrevStepId]="step2.ionPrevStepId"
+          [ionNextStepId]="step2.ionNextStepId"
+          [ionStepTitle]="step2.ionStepTitle"
+          [ionStepBody]="saveStep"
+        ></ion-button>
+        <ion-button
+          iconType="option"
+          type="secondary"
+          ionTourStep
+          [ionStepPosition]="step3.ionStepPosition"
+          [ionTourId]="step3.ionTourId"
+          [ionStepId]="step3.ionStepId"
+          [ionPrevStepId]="step3.ionPrevStepId"
+          [ionStepTitle]="step3.ionStepTitle"
+          [ionStepBody]="optionsStepContent"
+          [ionNextStepBtn]="step3.ionNextStepBtn"
+        ></ion-button>
+      </main>
+    </div>
+
+    <ng-template #uploadStepContent>
+      <span>Here is a random image:</span>
+      <img
+        src="https://picsum.photos/200/100"
+        alt="Random Image"
+        width="200px"
+        height="100px"
+      />
+    </ng-template>
+
+    <ng-template #saveStep>
+      <span>Save your changes.</span>
+    </ng-template>
+
+    <ng-template #optionsStepContent>
+      <span>Click to see other actions.</span>
+    </ng-template>
+  `,
+})
+export class TourBasicDemoComponent {
+  public tourId = 'basic-demo';
+
+  public step1 = STEP1_MOCK;
+  public step2 = STEP2_MOCK;
+  public step3 = STEP3_MOCK;
+
+  constructor(private readonly ionTourService: IonTourService) {}
+
+  public startTour(): void {
+    this.ionTourService.start();
+  }
+}

projects/ion/src/lib/tour/mocks/tour-step-props.component.ts

@@ -0,0 +1,74 @@
+import { AfterViewInit, Component, Input, OnChanges } from '@angular/core';
+
+import { PopoverButtonsProps, PopoverPosition } from '../../core/types';
+import { IonTourService } from '../tour.service';
+
+@Component({
+  selector: 'tour-step-props',
+  template: `
+    <style>
+      div {
+        height: 800px;
+        width: 100%;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+      }
+    </style>
+
+    <div>
+      <ion-button
+        label="Demo"
+        type="secondary"
+        (ionOnClick)="restartTour()"
+        ionTourStep
+        [ionStepId]="ionStepId"
+        [ionTourId]="ionTourId"
+        [ionStepBody]="stepBody"
+        [ionStepTitle]="ionStepTitle"
+        [ionPrevStepBtn]="ionPrevStepBtn"
+        [ionNextStepBtn]="ionNextStepBtn"
+        [ionPrevStepId]="ionPrevStepId"
+        [ionNextStepId]="ionNextStepId"
+        [ionStepPosition]="ionStepPosition"
+        [ionStepMarginToContent]="ionStepMarginToContent"
+        [ionStepBackdropPadding]="ionStepBackdropPadding"
+        [ionStepCustomClass]="ionStepCustomClass"
+        [ionStepBackdropCustomClass]="ionStepBackdropCustomClass"
+      ></ion-button>
+    </div>
+
+    <ng-template #stepBody>
+      <p>Step body content</p>
+    </ng-template>
+  `,
+})
+export class TourStepDemoComponent implements AfterViewInit, OnChanges {
+  @Input() ionStepId = 'demo-step';
+  @Input() ionTourId = 'demo-tour';
+  @Input() ionStepTitle: string;
+  @Input() ionPrevStepBtn: PopoverButtonsProps;
+  @Input() ionNextStepBtn: PopoverButtonsProps;
+  @Input() ionPrevStepId: string;
+  @Input() ionNextStepId: string;
+  @Input() ionStepPosition: PopoverPosition;
+  @Input() ionStepMarginToContent: number;
+  @Input() ionStepBackdropPadding: number;
+  @Input() ionStepCustomClass: string;
+  @Input() ionStepBackdropCustomClass: string;
+
+  constructor(private readonly ionTourService: IonTourService) {}
+
+  public ngAfterViewInit(): void {
+    this.ionTourService.start();
+  }
+
+  public ngOnChanges(): void {
+    this.restartTour();
+  }
+
+  public restartTour(): void {
+    this.ionTourService.finish();
+    this.ionTourService.start();
+  }
+}

projects/ion/src/lib/tour/tour-backdrop/index.ts

@@ -0,0 +1 @@
+export * from './tour-backdrop.component';

projects/ion/src/lib/tour/tour-backdrop/tour-backdrop.component.html

@@ -0,0 +1,10 @@
+<svg
+  *ngIf="(isActive && currentStep) || inTransition"
+  data-testid="ion-tour-backdrop"
+  [ngClass]="
+    'ion-tour-backdrop ' +
+    (currentStep ? currentStep.ionStepBackdropCustomClass : '')
+  "
+  [class.ion-tour-backdrop-transition]="inTransition"
+  [style.clip-path]="clipPath"
+></svg>

projects/ion/src/lib/tour/tour-backdrop/tour-backdrop.component.scss

@@ -0,0 +1,37 @@
+@import '../../../styles/index.scss';
+
+.ion-tour-backdrop {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background-color: $black-transparence-45;
+  transition: all 0.4s ease;
+  z-index: $zIndexMid;
+
+  &-transition {
+    background-color: #00000000;
+    clip-path: polygon(
+      0px 0px,
+      0px 100%,
+      0px 100%,
+      0px 0,
+      100% 0,
+      100% 100%,
+      0px 100%,
+      0px 100%,
+      100% 100%,
+      100% 0px
+    ) !important;
+  }
+}
+
+::ng-deep .ion-tour-popover {
+  position: absolute !important;
+  transform: translate(0) !important;
+
+  .ion-popover__content-body {
+    max-height: unset !important;
+  }
+}

projects/ion/src/lib/tour/tour-backdrop/tour-backdrop.component.spec.ts

@@ -0,0 +1,74 @@
+import { render, RenderResult, screen } from '@testing-library/angular';
+
+import { IonTourStepProps } from '../../core/types';
+import { IonTourBackdropComponent } from './tour-backdrop.component';
+
+const sut = async (
+  props: Partial<IonTourBackdropComponent> = {}
+): Promise<RenderResult<IonTourBackdropComponent>> => {
+  return render(IonTourBackdropComponent, {
+    declarations: [IonTourBackdropComponent],
+    componentProperties: {
+      ...props,
+    },
+  });
+};
+
+const STEP_MOCK = {
+  target: {
+    x: 300,
+    y: 300,
+    width: 100,
+    height: 100,
+    bottom: 400,
+    right: 400,
+    left: 300,
+    top: 300,
+  } as DOMRect,
+} as IonTourStepProps;
+
+describe('IonTourBackdropComponent', () => {
+  it('should render', async () => {
+    await sut();
+    expect(screen.queryByTestId('ion-tour-backdrop')).toBeInTheDocument();
+  });
+
+  it('should render with custom class', async () => {
+    const ionStepBackdropCustomClass = 'custom-class';
+
+    await sut({
+      currentStep: { ...STEP_MOCK, ionStepBackdropCustomClass },
+    });
+
+    expect(screen.queryByTestId('ion-tour-backdrop')).toHaveClass(
+      ionStepBackdropCustomClass
+    );
+  });
+
+  describe('transitions', () => {
+    it('should render with transition', async () => {
+      await sut({ inTransition: true });
+      expect(screen.queryByTestId('ion-tour-backdrop')).toHaveClass(
+        'ion-tour-backdrop-transition'
+      );
+    });
+
+    it('should stop rendering when the transition ends and the tour remains inactive', async () => {
+      const { rerender } = await sut({ inTransition: true, isActive: false });
+      rerender({ inTransition: false });
+      expect(screen.queryByTestId('ion-tour-backdrop')).not.toBeInTheDocument();
+    });
+
+    it('should stop rendering when performFinalTransition is called', async () => {
+      jest.useFakeTimers();
+      const { fixture } = await sut({ inTransition: true });
+      const callback = jest.fn();
+
+      fixture.componentInstance.performFinalTransition(callback);
+
+      jest.runAllTimers();
+      expect(screen.queryByTestId('ion-tour-backdrop')).not.toBeInTheDocument();
+      expect(callback).toHaveBeenCalled();
+    });
+  });
+});