@omnic/widget-locations v1.1.27

USAGE

Integration in standalone mode

When build in standalone mode the widget exposes window.OMNIC_WIDGET_LOCATIONS_CONFIG config object. Add script tag to your page and pass the config object to the widget like this:

<script>
  window.OMNIC_WIDGET_LOCATIONS_CONFIG = {
    INN: "INN",
    locale: "en",
    map: {
      provider: "google",
      center: [55.75, 37.57],
    },
    onPointClick: (point: CallbackPoint) => {
      // TODO: process point click
    },
  };
</script>

The onPointClick callback will be called when user clicks on a point on the map. The point object has the following structure:

type Coordinates = [number, number];

interface Country {
  uid: string;
  name: string;
  abbreviation: string;
}

interface Region {
  uid: string;
  name: string;
  national_id: string;
}

interface City {
  uid: string;
  name: string;
  region: Region;
  latitude: number;
  country: Country;
  longitude: number;
  national_id: string;
}

interface Location {
  city: City;
  house: string;
  block: string;
  street: string;
  office: string;
  region: Region;
  floor: unknown;
  latitude: number;
  country: Country;
  longitude: number;
  postal_index: string;
  full_address: string;
}

interface LocationPoint {
  uid: string;
  name: string;
  code: string;
  type: number;
  brand: string;
  status: number;
  images: string[];
  schedule: string[];
  max_length: number;
  max_weight: number;
  is_pickup: boolean;
  location: Location;
  description: string;
  is_favorite: boolean;
  pay_by_cash: boolean;
  pay_by_card: boolean;
  is_delivery: boolean;
  near_station?: string;
  location_name?: string;
  is_check_order: boolean;
  round_the_clock: boolean;
  is_dressing_room: boolean;
  near_metro_station?: string;
}

interface NormalizeAddressResponseData {
  country_name: string;
  country_code: string;
  region: string;
  city: string;
  latitude: number;
  longitude: number;
  street: string;
  house: string;
  block: string;
  office: string;
  postal_index: string;
  address: string;
  address_full: string;
  city_place_id: string;
  region_place_id: string;
  place_id: string;
}

export interface DeliveryPoint {
  coords: Coordinates;
  address: Nullable<string>;
}

export interface DeliveryPointWithFullAddress extends Omit<DeliveryPoint, "address"> {
  comment: string;
  address: Nullable<NormalizeAddressResponseData>;
  delivery_time: string;
  apartment_number: string;
  // pay_by_cash: boolean;
  // pay_by_card: boolean;
}

// THIS IS THE TYPE OF THE CALLBACK POINT
type CallbackPoint = LocationPoint | CourierDeliveryPoint;

Then OMNIC_WIDGET_LOCATIONS_CONFIG has the following structure:

WidgetInputs type has the following structure:

interface ForwardedInputElement extends Pick<HTMLInputElement, "focus" | "blur"> {
  setValue: (value: string) => void;
}

interface InputConfig {
  name: string;
  ref: RefObject<ForwardedInputElement>;
  onClick?: (name: string) => void;
}

interface WidgetInputs {
  /**
    Widget Map address input
   */
  address: InputConfig;
  /**
   * Widget city input
   */
  city: InputConfig;
  /**
   * Delivery apartment input
   */
  apartment: InputConfig;
  /**
   * Delivery comment input
   */
  comment: InputConfig;
}

WidgetHandlers type has the following structure:

interface LocationSelectorElement {
  open: () => void;
  close: () => void;
}

interface WidgetHandlers {
  locationSelector: RefObject<LocationSelectorElement>;
}

NOTE: when using screen keyboard do not forget to call focus() method for address and city inputs, so that autocomplete will appear.

Include styles.css and widget.umd.js in your page:

<link rel="stylesheet" href="styles.css" />
<script src="widget.umd.js"></script>

After that you can create a div block with id @omnic/widget-locations and widget will be rendered there:

<div id="@omnic/widget-locations"></div>

Integration in React mode

When build in React mode the widget exposes Widget component. First install a package:

npm install @omnic/widget-locations

Then import it and use like this:

import React from "react";

import { Widget } from "@omnic/widget-locations";
import type { LocationPoint, DeliveryPoint } from "@omnic/widget-locations";

import "@omnic/widget-locations/dist/lib/style.css";

const App = () => {
  const onPointClick = (point: LocationPoint | DeliveryPoint) => {
    // TODO: process point click
  };

  return (
    <Widget /> {/* 👈 don't forget to provide `config` props */}
  );
};

Widget component has the following props:

DON'T FORGET to wrap the widget in a div with id @omnic/widget-locations, so that all css styles will be applied correctly.

DEVELOPMENT

Project setup

Install all dependencies:

$ npm install

Then build it in lib mode:

$ npm run build:lib

or standalone mode:

$ npm run build:app

Use npm run dev to start local development server.

API

All API and components are exposed in src/index.ts file.

src/main.tsx file is responsible for rendering the widget in standalone mode or in development mode.