@openfin/here-zero

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 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

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

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',
    // Optional: Configure theme colors
    theme: {
        // Seed tokens applied to both themes (optional)
        seed: {
            'brand.base.light': '#ffffff',
            'brand.base.dark': '#140611',
            'brand.accent.light': '#641e55',
            'brand.accent.dark': '#8b2a6f'
        },
        // Light theme overrides (optional)
        light: {},
        // Dark theme overrides (optional)
        dark: {}
    },
    // Optional: Configure interop settings
    interop: {
        defaultContextGroup: 'supertab', // 'supertab' | 'window'
        colorChannels: {
            enabled: true // Enable/disable color linking functionality
        }
    }
});

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
• theme: (Optional) Configure custom theme colors for light and dark modes.
  • seed: (Optional) Base tokens applied to both light and dark themes
    • brand.base.light: Base light color (typically white) - used to generate foreground/text colors
    • brand.base.dark: Base dark color (typically dark) - used to generate background colors
    • brand.accent.light: Primary brand accent color - generates the full accent color palette
    • brand.accent.dark: Secondary brand accent color - used for accent color variations and highlights
    • Additional extended tokens for fine-grained customization (optional)
  • light: (Optional) Color token overrides for light mode
  • dark: (Optional) Color token overrides for dark mode

Note: The brand.base and brand.accent colors are foundational seed colors that the theme engine uses to algorithmically generate a comprehensive, harmonious color system. From just these 4 core colors, the theme engine can generate CSS variables including color scales, semantic color roles, status colors, component-specific colors, and dark mode variants.

Theme Configuration Format: HERE Zero uses a tokenMap format with dot-notation keys (e.g., 'brand.base.light', 'color.role.background.1'). This format maps directly to CSS custom property names and provides a flat, easy-to-scan structure.

Minimal Extended Color Tokens

For better UI appearance, you can add these minimal extended color tokens to your theme configuration:

theme: {
    // Seed tokens applied to both themes (optional)
    seed: {
        'brand.base.light': '#ffffff',
        'brand.base.dark': '#1e293b',
        'brand.accent.light': '#3b82f6',
        'brand.accent.dark': '#f59e0b'
    },
    // Light theme overrides (optional)
    light: {
        'color.role.background.1': '#ffffff',
        'color.role.background.2': '#f8fafc',
        'color.role.background.3': '#f1f5f9',
        'color.role.background.4': '#e2e8f0',
        'color.role.background.5': '#cbd5e1',
        'color.role.foreground.base': '#1e293b'
    },
    // Dark theme overrides (optional)
    dark: {
        'brand.base.dark': '#0f172a',
        'brand.accent.light': '#60a5fa',
        'brand.accent.dark': '#fbbf24',
        'color.role.background.1': '#0f172a',
        'color.role.background.2': '#1e293b',
        'color.role.background.3': '#334155',
        'color.role.background.4': '#475569',
        'color.role.background.5': '#64748b',
        'color.role.foreground.base': '#ffffff'
    }
}

Extended Token Descriptions:

Background Color Progression (color.role.background.1-6):

• color.role.background.1: Primary background - Main application background, content areas, and selected tabs
• color.role.background.2: Secondary background - Tab dropdown lists and container backgrounds
• color.role.background.3: Tertiary background - Tab headers, active tabs, and scroll tracks
• color.role.background.4: Quaternary background - Available for additional UI containers
• color.role.background.5: Interactive/border background - Tab hover states, content borders, and scroll shadows
• color.role.background.6: Scroll elements - Scroll thumbs and dropdown backgrounds

Text Colors:

• color.role.foreground.base: Primary text color - Main content text, labels, and primary UI text

These tokens provide minimal custom styling examples. The theme engine automatically generates the full suite of CSS variables covering all UI components, so most projects only need to provide the 4 core seed colors (brand.base.light, brand.base.dark, brand.accent.light, brand.accent.dark). Extended tokens allow for fine-grained customization when needed.

• interop: (Optional) Configure interop and context grouping behavior
  • defaultContextGroup: (Optional) Controls how supertabs share context
    • 'supertab': (Default) Views within the same supertab share context
    • 'window': All views within the same window (per-browser-tab) can share context
  • colorChannels: (Optional) Configure color linking functionality
    • enabled: (default: false) Enable/disable color linking UI and interop context grouping behaviors

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.

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
            };
        }
    },
    telemetry: {
        handle: (telemetryData) => {
            console.log(telemetryData);
            return;
        } ;
    };
});

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:

...
    "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:

• Creates the outputDir declared in the config if it doesn't exist
• Copies necessary HERE web assets to the output directory
• Copies and injects the provided overrides file into the HERE web entry point
• 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 via the @openfin/core-web library.

The HERE Zero platform application includes a core-web 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.

Context Grouping

The defaultContextGroup setting controls how content shares context across the application:

• 'supertab' (Default): Views within the same supertab share context
• 'window': All views within the same window (per-browser-tab) can share context

Color Linking

When colorChannels.enabled is set to true, the platform enables color linking functionality that allows users to:

• Assign color channels to tabs and views
• Group related content by color for better organization
• Create visual associations between different parts of the application

The color linking feature includes a predefined set of color channels (blue, indigo, pink, teal, green, orange, red, yellow, gray) that users can assign to their content.

core-web Recommended resources

• Core Web Starter Example
• Porting HERE Core Container Content to Core Web
• Core Web versions and Release Notes