Organization Search Viewer

A collection of Lit web components for organization search functionality compatible with React and Angular.

Overview

Organization Search Viewer provides customizable web components built with Lit that can be used to search for organizations, display organization details, and handle address searching. These components are designed to work seamlessly with modern frameworks like React and Angular.

Components

The package exports the following web components:

• <organization-address-search>: Component for searching and displaying organization addresses
• <address-autocomplete>: Component for address autocomplete functionality with loading spinner
• <organization-details-viewer>: Component for displaying detailed organization information in a structured layout
• <organization-map-search>: Component for searching organizations with an interactive map interface using Trimble Maps

Installation

npm install organization-search-viewer

The package is self-contained and bundles all its dependencies, including Lit. This means you don't need to install Lit separately in your project.

Usage

Basic Usage

Import the components in your JavaScript/TypeScript file:

// Import all components
import 'organization-search-viewer';

// Or import individual components
import 'organization-search-viewer/dist/organization-search-viewer.es.js';

// For vanilla JS without module bundlers, you can use the UMD version in a script tag

<!-- Include directly in HTML (UMD version) -->
<script src="./node_modules/organization-search-viewer/dist/organization-search-viewer.umd.js"></script>

Then use the components in your HTML:

<!-- Organization Address Search -->
<organization-address-search map-api-key="trimble-map-api-key" ></organization-address-search>

<!-- Address Autocomplete -->
<address-autocomplete></address-autocomplete>

<!-- Organization Details Viewer -->
<organization-details-viewer></organization-details-viewer>

<!-- Organization Map Search -->
<organization-map-search 
  map-api-key="your-trimble-maps-api-key"
  show-company-details="true">
</organization-map-search>

With Data

<!-- Display organization details with data -->
<organization-details-viewer 
  .organizationData="${yourOrganizationData}">
</organization-details-viewer>

// Set data programmatically
const detailsViewer = document.querySelector('organization-details-viewer');
detailsViewer.organizationData = {
  mainCompany: {
    details: {
      name: "Example Corp",
      description: "A technology company",
      industry: "Software",
      website: "example.com",
      phone: "+1 (555) 123-4567"
    },
    address: {
      street: "123 Main St",
      city: "San Francisco",
      region: "CA",
      zipcode: "94105",
      country: "USA"
    }
  }
};

React Integration

import React from 'react';
import 'organization-search-viewer';

function App() {
  return (
    <div>
      <organization-address-search map-api-key="trimble-map-api-key" ></organization-address-search>
    </div>
  );
}

Accessing Raw Company Data in React

You can access the raw, unformatted company data using event listeners:

import React, { useRef, useEffect } from 'react';
import 'organization-search-viewer';

function App() {
  const addressSearchRef = useRef(null);
  
  useEffect(() => {
    const handleCompanyData = (event) => {
      const rawCompanyData = event.detail;
      // Process the data as needed
    };
    
    const element = addressSearchRef.current;
    if (element) {
      element.addEventListener('onCompanySelected', handleCompanyData);
      
      return () => {
        element.removeEventListener('onCompanySelected', handleCompanyData);
      };
    }
  }, []);
  
  return (
    <organization-address-search 
      ref={addressSearchRef} 
      map-api-key="trimble-map-api-key" 
    />
  );
}

Angular Integration

First, ensure custom elements schema is added to your module:

import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  bootstrap: [AppComponent]
})
export class AppModule {}

Then use the components in your templates:

<organization-address-search map-api-key="trimble-map-api-key"></organization-address-search>

Handling Events in Angular

@Component({
  selector: 'app-my-component',
  template: `
    <organization-address-search 
      map-api-key="trimble-map-api-key"
      (onCompanySelected)="handleCompanyData($event)">
    </organization-address-search>
  `
})
export class MyComponent {
  handleCompanyData(event: CustomEvent) {
    const companyData = event.detail;
    // Process data as needed
  }
}

OrganizationMapSearch Framework Integration Examples

React Integration

import React, { useRef, useEffect } from 'react';
import 'organization-search-viewer';

function MapSearchComponent() {
  const mapSearchRef = useRef(null);
  
  useEffect(() => {
    const handleCompanySelected = (event) => {
      const selectedCompany = event.detail;
      console.log('Selected company:', selectedCompany);
      // Handle the selected company data
    };
    
    const element = mapSearchRef.current;
    if (element) {
      element.addEventListener('onCompanySelected', handleCompanySelected);
      return () => {
        element.removeEventListener('onCompanySelected', handleCompanySelected);
      };
    }
  }, []);
  
  return (
    <organization-map-search 
      ref={mapSearchRef}
      map-api-key="your-trimble-maps-api-key"
      show-company-details={true}
    />
  );
}

Angular Integration

// In your component
import { Component, ElementRef, ViewChild, OnInit, OnDestroy } from '@angular/core';

@Component({
  selector: 'app-map-search',
  template: `
    <organization-map-search
      #mapSearch
      [attr.map-api-key]="trimbleMapsApiKey"
      [attr.show-company-details]="true">
    </organization-map-search>
  `
})
export class MapSearchComponent implements OnInit, OnDestroy {
  @ViewChild('mapSearch') mapSearch!: ElementRef;
  trimbleMapsApiKey = 'your-trimble-maps-api-key';

  ngOnInit() {
    this.mapSearch.nativeElement.addEventListener('onCompanySelected', this.handleCompanySelected);
  }

  ngOnDestroy() {
    this.mapSearch.nativeElement.removeEventListener('onCompanySelected', this.handleCompanySelected);
  }

  handleCompanySelected(event: CustomEvent) {
    const selectedCompany = event.detail;
    console.log('Selected company:', selectedCompany);
    // Handle the selected company data
  }
}

API Reference

OrganizationDetailsViewer

Component for displaying detailed organization information in a structured, responsive layout. can be used to display the data returned from organization-address-search

Properties

• organizationData: An object containing the organization data to display, including main company and potentially domestic and global ultimate parent companies

Data Structure

interface OrganizationData {
  mainCompany?: CompanyEntity;
  domesticUltimate?: CompanyEntity;
  globalUltimate?: CompanyEntity;
}

interface CompanyEntity {
  address?: Address;
  details?: CompanyDetails;
}

interface CompanyDetails {
  name?: string;
  description?: string;
  industry?: string;
  website?: string;
  phone?: string;
}

interface Address {
  street?: string;
  city?: string;
  region?: string;
  zipcode?: string;
  country?: string;
}

OrganizationAddressSearch

Component for organization address search.

Properties

• map-api-key (required):Trimble Maps API key for calling Maps search API endpoint
• show-company-details: Boolean to control whether to display company details

Events

• onCompanySelected: Fired when a company is selected with the unformatted company data

AddressAutocomplete

Component for address autocomplete functionality.this component is a plain autocomplete without any API integrated exposed for custom implementation

Properties

• options: Array of options to display in the dropdown
• placeholder: Text to display in the input field when empty
• minSearchLength: Minimum number of characters required to start a search (default: 3)

Events

• search-input: Fired when the user types in the search field
• option-selected: Fired when an option is selected from the dropdown

OrganizationMapSearch

Component for organization map search using Trimble Maps SDK and Single Search Addon.

Properties

• map-api-key (required): Your Trimble Maps API key
• show-company-details (optional): Boolean to control the visibility of company details panel

Events

The component emits a onCompanySelected event when an organization is selected from search results:

Utilities

parameter - companyData: data received from organization-address-search returns - Formatted company in the format OrganizationData

import { formatCompanyDetails } from 'organization-search-viewer';

const organizationData: OrganizationData = formatCompanyDetails(companyData);

Features

• Structured Layout: Company details are displayed in a structured, easy-to-read layout
• Loading Indicators: Visual feedback for loading states in the autocomplete component and organization data loading
• Responsive Design: Components adapt to different screen sizes for optimal display
• Conditional Rendering: Only renders sections when data is available
• Event System: Rich event system for integration with any framework

Development

Setup

npm install

Development Server

npm run dev

Building

npm run build

Preview

npm run preview

Publishing

To NPM Registry

npm run publish-package

Dependencies

This package bundles its dependencies and can be used without requiring users to install additional packages:

• Lit: Core library for building web components (bundled with the package)

License

Please refer to the license file included with this package.