# Ng-EnjoyHint **EnjoyHint** is a web-tool that provides the simplest way to create interactive tutorials and hints for your site or web-application. It can also be used to highlight and sign application elements. **Ng-EnjoyHint** is an rewrite of EnjoyHint that removes jQuery and brings a native Angular experience. ## Installation ```bash npm install ng-enjoyhint ``` ## Usage - Inject the `NgEnjoyHintService` into your component. ```ts private readonly enjoyHintService = inject(NgEnjoyHintService); ``` - Call `runTutorial()` to run the tutorial. ```ts await this.enjoyHintService.runTutorial( [ { selector: ".my-element", event: "click", description: "Click on this element", }, { selector: ".my-other-element", event: "click", description: "Now click over here", }, ] ); ``` ## How it works When running a tutorial, an overlay is added to the page. Four semi-transparent elements, one on each side of the target element, de-emphasize the rest of the page and block user input. A description is shown on the side of the target element. The user can complete the configured event (normally a click) on the target element to advance to the next step of the tutorial. When the last step is completed, the overlay is removed. ## License MIT ## API ## EnjoyHintService Defined in: enjoyhint.service.ts:21 ### Properties | Property | Modifier | Type | Description | Defined in | | ------ | ------ | ------ | ------ | ------ | | `inProgress` | `readonly` | `Signal`\<`boolean`\> | Whether there is any active tutorial | enjoyhint.service.ts:31 | ### Methods #### runTutorial() > **runTutorial**(`steps`, `options?`): `Promise`\<`boolean`\> Defined in: enjoyhint.service.ts:41 Run an interactive tutorial ##### Parameters | Parameter | Type | Description | | ------ | ------ | ------ | | `steps` | [`ITutorialStep`](#itutorialstep)[] | the tutorial steps to run | | `options?` | `Partial`\<[`IEnjoyHintOptions`](#ienjoyhintoptions)\> | optional object to override the default behavior | ##### Returns `Promise`\<`boolean`\> a promise resolving when the tutorial is closed; resolves to `true` if the tutorial was completed, `false` if it was skipped *** ## IButtonOptions Defined in: lib.interfaces.ts:113 Custom settings for a tutorial button ### Properties | Property | Type | Description | Defined in | | ------ | ------ | ------ | ------ | | `className?` | `string` | Custom CSS class to apply to the button | lib.interfaces.ts:117 | | `text` | `string` | Text to display on the button | lib.interfaces.ts:115 | *** ## IEnjoyHintOptions Defined in: lib.interfaces.ts:3 ### Properties | Property | Type | Description | Defined in | | ------ | ------ | ------ | ------ | | `backdropColor` | `string` | Color of the backdrop overlay. Accepts any valid CSS color value. **Default** `'black'` | lib.interfaces.ts:18 | | `backdropOpacity` | `number` | Opacity of the backdrop overlay. Higher values makes text more readable. **Default** `0.75` | lib.interfaces.ts:23 | | `fontFamily` | `string` | Font family to use for the tutorial text and buttons. **Default** `'sans-serif'` | lib.interfaces.ts:13 | | `foregroundColor` | `string` | Color of text and arrow elements. **Default** `'white'` | lib.interfaces.ts:28 | | `nextButton` | [`IButtonOptions`](#ibuttonoptions) | Custom settings for the "Next" button. **Default** `{ text: 'Next' }` | lib.interfaces.ts:33 | | `overlayZIndex?` | `number` | Z-index of the backdrop. **Default** `1000 (from @angular/cdk/overlay)` | lib.interfaces.ts:48 | | `padding` | `number` | Amount of space between the edge of the current step's target element and the backdrop (in pixels) **Default** `5` | lib.interfaces.ts:8 | | `previousButton` | [`IButtonOptions`](#ibuttonoptions) | Custom settings for the "Previous" button. **Default** `{ text: 'Previous' }` | lib.interfaces.ts:43 | | `skipButton` | [`IButtonOptions`](#ibuttonoptions) | Custom settings for the "Skip" button. **Default** `{ text: 'Skip' }` | lib.interfaces.ts:38 | *** ## ITemplateWithContext Defined in: lib.interfaces.ts:107 ### Type Parameters | Type Parameter | Default type | | ------ | ------ | | `T` | `unknown` | ### Properties | Property | Type | Defined in | | ------ | ------ | ------ | | `context` | `T` | lib.interfaces.ts:109 | | `template` | `TemplateRef`\<`T`\> | lib.interfaces.ts:108 | *** ## ITutorialStep Defined in: lib.interfaces.ts:51 ### Properties | Property | Type | Description | Defined in | | ------ | ------ | ------ | ------ | | `description` | `string` \| `TemplateRef`\<`any`\> | The main instructions for the step. Keep this short. | lib.interfaces.ts:60 | | `details?` | `string` \| `TemplateRef`\<`any`\> \| [`ITemplateWithContext`](#itemplatewithcontext)\<`unknown`\> | Additional text displayed in a smaller font under the description. May be longer (but not too long). | lib.interfaces.ts:70 | | `event` | `string` | The event to listen for on the element to move onto the next step. Accepts any valid DOM event name, or 'next' to move on when the "Next" button is clicked. | lib.interfaces.ts:56 | | `hidePrevious?` | `boolean` | Whether or not to hide the "Previous" button. **Default** `false` | lib.interfaces.ts:92 | | `hideSkip?` | `boolean` | Whether or not to hide the "Skip" button. **Default** `false` | lib.interfaces.ts:87 | | `nextButton?` | [`IButtonOptions`](#ibuttonoptions) | Custom settings for the "Next" button. | lib.interfaces.ts:74 | | `previousButton?` | [`IButtonOptions`](#ibuttonoptions) | Custom settings for the "Previous" button. | lib.interfaces.ts:82 | | `selector?` | `string` | The CSS selector for the element to focus on. If not specified, the provided instructions will display in the center of the screen. | lib.interfaces.ts:65 | | `shouldSkip?` | () => `boolean` \| `Promise`\<`boolean`\> | Callback to determine if the step should be skipped. | lib.interfaces.ts:104 | | `skipButton?` | [`IButtonOptions`](#ibuttonoptions) | Custom settings for the "Skip" button. | lib.interfaces.ts:78 | | `stepEnd?` | () => `void` \| `Promise`\<`void`\> | Callback to execute when the step is ended. | lib.interfaces.ts:100 | | `stepStart?` | () => `void` \| `Promise`\<`void`\> | Callback to execute when the step is started. | lib.interfaces.ts:96 |