# HERE Zero

HERE Zero is a library that creates a zero-install web-based implementation of a HERE platform. It aims to provide an out-of-the-box, low-code solution for building HERE platforms that run in a standard web browser and can be themed and integrated with a customer’s backend to support application directories and search ("HERE Zero platform" for short).

## Overview

The HERE Zero packager is a tool that helps configure and build a HERE Zero platform based on the [`core-web`](https://www.npmjs.com/package/@openfin/core-web) package. Its output is an application that you can host. It handles: 

- Loading HERE configuration files
- Managing assets and dependencies
- Injecting necessary scripts into overridden HERE web output
- Customizing logos

## Usage

```bash
here-zero
```

## Configuration

The HERE Zero packager requires a configuration file as its entry point. The file must be called `here.config.js` (`.ts`,  and `.mjs` are also supported) and must exist in the project root directory. 

**here.config.ts** 
```typescript
import { defineConfig } from '@openfin/here-zero';

export default defineConfig({
    overrides: {
        file: './overrides.js'
    },
    outputDir: './dist',
    // Optional: Configure custom logos
    logo: {
        searchCommandBar: 'path/to/your/logo.ico',
        newTab: 'path/to/your/logo.ico'
    },
    // Optional: Configure title for the application
    title: 'Here® Web App',
    // Optional: Configure favicon for the application
    favicon: 'path/to/your/favicon.ico'
});
```

### Configuration Options

- `overrides`: Specify the path to your overrides file
  - `file`: Path to your client-side JavaScript overrides file
- `outputDir`: Directory where built files will be placed
- `logo`: (Optional) Customize logos in different parts of the application
  - `searchCommandBar`: (Optional) Logo for the search command bar
  - `newTab`: (Optional) Logo for new tabs
- `title`: (Optional) Set the title of your HERE Zero platform
- `favicon`: (Optional) Set the favicon for your HERE Zero platform

## Overrides
You can supply content to the HERE Zero platform, such as featured apps, launcher entries, and search results, allowing the platform to display dynamic or custom content tailored to your environment.
To do this, you provide a JavaScript file that defines the content "overrides" that you want to display.

**overrides.js** 
The filename must match `overrides.file` in the configuration definition.

**IMPORTANT:** The HERE Zero packager does not handle building or bundling the provided overrides file.
This file executes in a browser context, so it must contain valid client-side JavaScript.
```javascript
const { defineOverrides } = require('@openfin/here-zero');

defineOverrides({
    content: {
        fetchFeaturedContent: async () => {
            // Return array of featured content items
            return [
                {
                    title: 'Example App',
                    url: 'https://example.com',
                    iconUrl: 'https://example.com/favicon.ico',
                    type: 'app'
                }
            ];
        },
        fetchLauncherContent: async () => {
            // Return array of launcher content items
            return [
                {
                    title: 'Example App',
                    url: 'https://example.com',
                    iconUrl: 'https://example.com/favicon.ico',
                    type: 'app'
                }
            ];
        },
        getInitialContent: () => {
            // Return initial content for user consumption
            // This can return an InitialContent object directly (synchronous) or a Promise<InitialContent> (asynchronous)
            return {
                content: [
                    {
                        title: 'Welcome',
                        url: 'https://example.com/welcome',
                        iconUrl: 'https://example.com/favicon.ico',
                        type: 'app'
                    }
                ]
            };
        }
    },
    search: {
        handleSearchQuery: async ({ query }) => {
            // Handle search queries and return results
            return {
                items: [
                    {
                        title: 'Search Result',
                        url: 'https://example.com',
                        iconUrl: 'https://example.com/favicon.ico',
                        type: 'app'
                    }
                ],
                totalCount: 1
            };
        }
    }
});
```

## Build
In order to generate a HERE Zero platform, you run the HERE Zero packager.
It produces an application in the `outputDir` specified in the configuration file.
You can host and run this application as your HERE Zero platform.

Example package.json scripts section:

```json
...
    "scripts": {
        "serve": "npx http-server dist -p 8080",
        "start": "npm run serve",
        "build": "npm run build:overrides && npm run build:here",
        "build:overrides": "rollup -c",
        "build:here": "here-zero"
    },
...
```

On a successful build, the packager does the following:
1. Creates the `outputDir` declared in the config if it doesn't exist
2. Copies necessary HERE web assets to the output directory
3. Copies and injects the provided `overrides` file into the HERE web entry point
4. If configured, injects the logo, title and favicon customizations into the output

## Web Interop

The HERE Zero platform includes built-in support for [HERE Web Interop APIs](https://resources.here.io/docs/core/container/interop/api/web-interop/) via the [`@openfin/core-web`](https://www.npmjs.com/package/@openfin/core-web) library.

The HERE Zero platform application includes a `core-web` [Web broker](https://resources.here.io/docs/core/container/interop/api/web-interop/#build-a-web-broker), preconfigured with smart defaults. 
For example:  content placed within supertabs is automatically context-bound. We recommend setting the `connectionInheritance` property to `"enabled"` on the content contexts in order to connect to the preconfigured broker. 


### core-web Recommended resources

- [Core Web Starter Example](https://github.com/built-on-openfin/web-starter/?tab=readme-ov-file#openfin-web)
- [Porting HERE Core Container Content to Core Web](https://github.com/built-on-openfin/web-starter/tree/main/how-to/web-client-api)
- [Core Web versions and Release Notes](https://cdn.openfin.co/versions/?product=Core%20Web#0.41.122)
