@govflanders/vl-widget-global-header-types 0.0.2 → 0.0.4

package/README.md

@@ -0,0 +1,156 @@
+# Global Header Widget types
+
+The **`@govflanders/vl-widget-global-header-types`** package provides TypeScript types and interfaces for interacting with the **Global Header Widget**. This widget is embedded in customer web pages and exposes a client object (`window.globalHeaderClient`) that allows for dynamic configuration and interaction with the global header.
+
+By using the types defined in this package, developers can ensure type-safe interactions with the widget while improving their development experience (DX) by utilizing autocompletion and built-in documentation.
+
+## Installation
+
+To install the `global-header-types` package, use the following command:
+
+```bash
+npm install -D @govflanders/vl-widget-global-header-types
+```
+or
+```bash
+yarn add -D @govflanders/vl-widget-global-header-types
+```
+
+## Usage
+This package provides all the types required for working with the Global Header Widget. The widget is available on the global window object as window.globalHeaderClient. You can import the types from global-header-types to use them in your project.
+
+Example of using the types to interact with the widget:
+```typescript
+import { GlobalHeaderClient, MainLink } from '@govflanders/vl-widget-global-header-types';
+
+const client: GlobalHeaderClient = window.globalHeaderClient;
+
+const contactLink: MainLink = {
+  title: 'Contact',
+  href: '/contact',
+};
+
+const feedbackLink: MainLink = {
+  title: 'Feedback',
+  href: 'https://example.com/feedback',
+  isExternal: true,
+  target: '_blank',
+};
+
+client.setMainLinks([
+  contactLink,
+  feedbackLink,
+]);
+```
+
+## API
+The window.globalHeaderClient object offers several methods for interacting with the widget. Each method is typed and returns promises, making asynchronous operations easier to handle. Below is a detailed breakdown of each method, its parameters, and the expected return values.
+
+### getConfig(): Promise\<Config\>
+Retrieve the current widget configuration.
+
+### setServicePoints(servicePoints: Translatable\<ServicePoints\>): Promise\<Translatable\<ServicePoints\>\>
+Update the service points displayed in the widget.
+
+### getServicePoints(): Promise\<EnrichedServicePoints\>
+Fetch the current service points from the widget.
+
+### resetServicePoints(): Promise\<boolean\>
+Reset the service points to the initial values defined in the widget’s configuration.
+
+### setProfile(profileConfig: Partial\<ProfileConfig\>): Promise\<boolean\>
+Set or update the profile configuration for the widget.
+
+### setMainLinks(mainLinks: MainLink[]): Promise\<boolean\>
+Set the main links that are displayed in the widget.
+
+### addApplicationMenuLink(link: ApplicationMenuLink): Promise\<ApplicationMenuLink[]\>
+Add a single link to the application menu.
+
+### addApplicationMenuLinks(links: ApplicationMenuLink[]): Promise\<ApplicationMenuLink[]\>
+Add multiple links to the application menu.
+
+### setApplicationMenuLinks(links: ApplicationMenuLink[]): Promise\<ApplicationMenuLink[]\>
+Replace all application menu links.
+
+### mount(element?: HTMLElement): Promise\<boolean\>
+
+The `mount` method allows you to control where the **Global Header Widget** is rendered on the page. There are two main ways to integrate the widget, depending on whether you want to manually control its placement or let it render automatically:
+
+1. **Using the 'entry' script**:
+   When you include the widget via the following script:
+
+   ```html
+   <script src="https://prod.widgets.burgerprofiel.vlaanderen.be/api/v1/widget/__global_header_id__/entry"></script>
+   ```
+
+   The widget is **not automatically rendered** on the page. Instead, you must call the `mount` method from the `window.globalHeaderClient` object to display it. This gives you control over where and when the widget is added. You can either:
+
+   - **Mount to a specific element**:
+     Pass an HTML element to the `mount` method to render the widget inside that element.
+
+     ```typescript
+     const element = document.getElementById('customHeader');
+     window.globalHeaderClient.mount(element);
+     ```
+
+   - **Mount without specifying an element**:
+     If no element is provided, the widget will automatically render at the top of the page.
+
+     ```typescript
+     window.globalHeaderClient.mount();
+     ```
+
+2. **Using the 'embed' script**:
+   If you use this script instead:
+
+   ```html
+   <script src="https://prod.widgets.burgerprofiel.vlaanderen.be/api/v1/widget/__global_header_id__/embed"></script>
+   ```
+
+   The widget will **automatically render** at the location where the script is placed in the HTML. No additional action is needed to mount the widget in this case.
+
+#### Return Value
+The `mount` method returns a promise that resolves to `true` if the widget was successfully mounted, or `false` otherwise.
+
+## Notes
+
+### Translatable Type
+
+The `Translatable<T>` type allows an object to either be a single value or a language-specific dictionary. This is useful when content needs to be available in multiple languages.
+
+#### Example
+
+For example, `setMainLinks` can accept single-language or multi-language links:
+
+```typescript
+const singleLanguageLink: Translatable<MainLink> = {
+  title: 'Home',
+  href: 'https://www.example.com',
+};
+
+const multiLanguageLink: Translatable<MainLink> = {
+  nl: {
+    title: 'Startpagina',
+    href: 'https://www.example.com/nl',
+  },
+  en: {
+    title: 'Home',
+    href: 'https://www.example.com/en',
+  },
+  fr: {
+    title: 'Accueil',
+    href: 'https://www.example.com/fr',
+  },
+  de: {
+    title: 'Startseite',
+    href: 'https://www.example.com/de',
+  },
+};
+
+client.setMainLinks([singleLanguageLink, multiLanguageLink]);
+```
+
+
+## License
+This package is licensed under the MIT License.

package/dist/client.d.ts

@@ -36,13 +36,13 @@ export type Handlers = {
      * @param profileConfig The profile configuration to set
      * @returns A promise that resolves to true if the profile configuration was set, false otherwise
      */
-    setProfile: Handler<ProfileConfig, boolean>;
+    setProfile: Handler<Partial<ProfileConfig>, boolean>;
     /**
      * Set the main links
      * @param mainLinks The main links to set
      * @returns A promise that resolves to true if the main links were set, false otherwise
      */
-    setMainLinks: Handler<MainLink[], boolean>;
+    setMainLinks: Handler<Translatable<MainLink>[], boolean>;
     /**
      * Add an application menu link
      * @param link The link to add
@@ -78,7 +78,7 @@ type ReturnTypes = {
     [HandlersKey in keyof Handlers]: Handlers[HandlersKey] extends Handler<any, infer Return> ? Return : never;
 };
 export type GlobalHeaderClient = {
-    [K in keyof Handlers]: (args: ArgumentTypes[K]) => Promise<ReturnTypes[K]>;
+    [K in keyof Handlers]: ArgumentTypes[K] extends undefined ? () => Promise<ReturnTypes[K]> : (args: ArgumentTypes[K]) => Promise<ReturnTypes[K]>;
 };
 export type QueueItem<Key extends keyof Handlers> = {
     [K in keyof Handlers]: {

package/dist/i18n.d.ts

@@ -14,7 +14,7 @@ export interface ResolveOptions {
 }
 export interface I18n {
     default: Language;
-    translations: Partial<Record<Language, RecursiveRecord>>;
+    translations: Translatable<RecursiveRecord>;
 }
 export type Translatable<T> = T | Record<Language, T>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@govflanders/vl-widget-global-header-types",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "TypeScript definitions for GlobalHeaderClient",
   "main": "",
   "types": "dist/index.d.ts",
@@ -22,6 +22,9 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "watch": "tsc -w",
+    "prepublishOnly": "npm run build",
+    "release": "yarn build && yarn version --patch --no-git-tag-version && git add . && git commit -m \"Release global-header-types $(node -p \"require('./package.json').version\")\" && git tag \"global-header-types-$(node -p \"require('./package.json').version\")\" && git push && git push --tags",
     "publish": "npm_config_registry=https://registry.npmjs.org/ npm publish --access public"
   }
 }