@creative-locator/core

Framework-agnostic dealer / distributor locator core.

The runtime that powers Creative Locator. Ships the map, search, filters, result list, mobile bottom sheet, analytics event bus, and orchestration layer as a single platform-independent TypeScript library.

@creative-locator/core has zero WordPress dependencies. It talks to its host environment exclusively through four adapter interfaces that consumers implement against their own runtime:

• ApiClient — dealer / search / geocoding / analytics transport.
• I18n — __, _n, _x, sprintf for translatable strings.
• Storage — persistent key/value storage (recent searches, user preferences).
• ConfigSource — resolves the LocatorConfig for each container on the page.

Current adapter implementations:

| Host | Package | | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | WordPress | @creative-locator/wordpress — shipped as the Creative Locator plugin on Freemius. | | Headless (Astro, Next.js, Eleventy, SvelteKit, vanilla HTML) | @creative-locator/headless — published on npm. | | Shopify | Planned (Creative Locator Shopify app). |

Install

pnpm add @creative-locator/core leaflet leaflet.markercluster

leaflet and leaflet.markercluster are peer dependencies so the host site can dedupe.

Usage

import { createLocator, type PlatformAdapters } from '@creative-locator/core';
import '@creative-locator/core/styles/style.scss';

// Implement the four adapters against your host runtime.
// See packages/wordpress/src/adapters/ for a reference implementation.
const adapters: PlatformAdapters = {
	api: new MyApiClient(/* ... */),
	i18n: new MyI18n(/* ... */),
	storage: new MyStorage(/* ... */),
	config: new MyConfigSource(/* ... */),
};

const container = document.querySelector<HTMLElement>('.crloc-dealer-locator')!;
createLocator(container, {
	adapters,
	configContainerId: container.id,
});

Accessibility

WCAG 2.1 AAA — this is the core reason Creative Locator exists. Every interactive element is keyboard accessible, focus indicators are 2px minimum with 3:1 contrast, every visible text token clears 7:1 contrast, touch targets are 44×44 px, prefers-reduced-motion is respected for every animation, and the ARIA combobox pattern is implemented to spec. A mandatory build-time contrast guard verifies the shipped token set mathematically against the WCAG AAA threshold in three scopes (light, @media dark, forced dark).

License

GPL-2.0-or-later. See LICENSE.