entasis 0.13.5 → 0.13.7

package/dist/components/Address/Address.svelte

@@ -0,0 +1,44 @@
+<script lang="ts">
+	import Slot from '../Slot/Slot.svelte';
+	import { useI18n } from '../../i18n/context.svelte.js';
+	import { formatAddress } from './address.js';
+	import type { AddressProps } from './address.props.js';
+	import { useAddressTheme } from './address.theme.js';
+
+	let {
+		address,
+		fields,
+		layout = 'block',
+		size = 'normal',
+		empty,
+		ref = $bindable(null),
+		class: className,
+		theme,
+		...rest
+	}: AddressProps = $props();
+
+	const t = $derived(useI18n());
+	const classes = $derived(useAddressTheme(theme));
+	// The country is named in the active locale when the value only carries its code.
+	const lines = $derived(formatAddress(address, { fields, locale: t.locale }));
+</script>
+
+<address
+	bind:this={ref}
+	data-slot="address"
+	data-layout={layout}
+	data-empty={lines.length === 0 ? 'true' : undefined}
+	class={classes.root({ size, layout, className })}
+	{...rest}
+>
+	{#each lines as line, index (index)}
+		<span data-slot="address-line" class={classes.line({ layout })}
+			>{line}{#if layout === 'inline' && index < lines.length - 1},
+			{/if}</span
+		>
+	{:else}
+		{#if empty}
+			<Slot as="span" render={empty} class={classes.empty()} />
+		{/if}
+	{/each}
+</address>

package/dist/components/Address/Address.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { AddressProps } from './address.props.js';
+declare const Address: import("svelte").Component<AddressProps, {}, "ref">;
+type Address = ReturnType<typeof Address>;
+export default Address;

package/dist/components/Address/address.d.ts

@@ -0,0 +1,99 @@
+/**
+ * A postal address as entasis stores, edits and displays it, the order its lines take in each
+ * country, and the provider contract an address search plugs into.
+ */
+/** A part of an address a field can show and edit. */
+export type AddressField = 'line1' | 'line2' | 'postalCode' | 'city' | 'region' | 'country';
+/** Every address part, in the order a form usually asks for them. */
+export declare const ADDRESS_FIELDS: readonly AddressField[];
+export type AddressLocation = {
+    lat: number;
+    lng: number;
+};
+/**
+ * A postal address. Every part is optional: a field shows and fills the parts it asks for, and
+ * a provider fills what it knows.
+ */
+export type Address = {
+    /** Street line: the number and the street, in the country's order ("12 Rue de Rivoli"). */
+    line1?: string | null;
+    /** Second line: apartment, suite, building, floor. */
+    line2?: string | null;
+    postalCode?: string | null;
+    /** City, town or postal town. */
+    city?: string | null;
+    /** State, province or region (first administrative level). */
+    region?: string | null;
+    /** Country name, as the provider or the field wrote it. */
+    country?: string | null;
+    /** ISO 3166-1 alpha-2 country code ("FR"). It decides the line order. */
+    countryCode?: string | null;
+    /** Street number alone, when a provider resolved it. Cleared by a manual edit of `line1`. */
+    streetNumber?: string | null;
+    /** Street name alone, when a provider resolved it. Cleared by a manual edit of `line1`. */
+    street?: string | null;
+    /** The provider's own one-line address. Cleared by any manual edit. */
+    formatted?: string | null;
+    /** The provider's place id. Cleared by any manual edit. */
+    placeId?: string | null;
+    /** Coordinates of the place. Cleared by any manual edit. */
+    location?: AddressLocation | null;
+};
+/** One search suggestion. */
+export type AddressSuggestion = {
+    /** Provider id passed back to `resolve`. */
+    id: string;
+    /** Main text: the street line or the place name. */
+    label: string;
+    /** Secondary text: the city, region and country. */
+    description?: string;
+};
+/** What an address search sends with each call. */
+export type AddressProviderRequest = {
+    /** Aborted when a newer query replaces this one, or the field is destroyed. */
+    signal?: AbortSignal;
+    /**
+     * One id per search, from the first keystroke to the chosen suggestion. Providers that bill
+     * by session (Google Places) group the calls under it.
+     */
+    session: string;
+    /** BCP 47 language the results should be written in: the active I18n locale. */
+    language?: string;
+    /** ISO 3166-1 alpha-2 codes the search is limited to. */
+    countries?: readonly string[];
+};
+/**
+ * An address search: suggestions for typed text, and the full address for a chosen suggestion.
+ * `createGooglePlacesProvider` is one; any service can implement it.
+ */
+export type AddressProvider = {
+    search: (query: string, request: AddressProviderRequest) => Promise<AddressSuggestion[]>;
+    resolve: (id: string, request: AddressProviderRequest) => Promise<Address | null>;
+};
+/** True when no part a person reads (lines, postal code, city, region, country) is filled. */
+export declare function isAddressEmpty(address: Address | null | undefined): boolean;
+/** The street line for a number and a street, in the order `countryCode` writes them. */
+export declare function composeStreetLine(streetNumber: string | null | undefined, street: string | null | undefined, countryCode?: string | null): string | null;
+export type FormatAddressOptions = {
+    /** Parts to include, in any order. Defaults to every part. */
+    fields?: readonly AddressField[];
+    /**
+     * Locale the country name is written in when only `countryCode` is set. Defaults to the
+     * runtime's locale.
+     */
+    locale?: string;
+};
+/** The country name for `address`: its own `country`, or `countryCode` written in `locale`. */
+export declare function addressCountryName(address: Address, locale?: string): string;
+/**
+ * The lines of an address as the country writes them: street lines, then the locality line
+ * (postal code and city, in the country's order, with the region where it belongs), then the
+ * country. Empty parts and empty lines are left out.
+ */
+export declare function formatAddress(address: Address | null | undefined, { fields, locale }?: FormatAddressOptions): string[];
+/** The address on one line, its lines joined by ", ". */
+export declare const formatAddressLine: (address: Address | null | undefined, options?: FormatAddressOptions) => string;
+/** ISO 3166-1 alpha-2 codes of every country and territory a postal address can be in. */
+export declare const COUNTRY_CODES: readonly string[];
+/** The name of the country `code` in `locale`, or the code itself when Intl cannot name it. */
+export declare function countryName(code: string, locale?: string): string;

package/dist/components/Address/address.google.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Google Places (Places API "New", REST) as an `AddressProvider`. No SDK is loaded: the search
+ * and the place details are two `fetch` calls, grouped under the field's session token so
+ * Google bills one autocomplete session per chosen address.
+ */
+import type { Address, AddressProvider } from './address.js';
+/** One entry of a Place's `addressComponents`. */
+export type GooglePlaceAddressComponent = {
+    longText?: string;
+    shortText?: string;
+    types?: string[];
+    languageCode?: string;
+};
+/** The Place fields `parseGooglePlace` reads. */
+export type GooglePlace = {
+    id?: string;
+    formattedAddress?: string;
+    addressComponents?: GooglePlaceAddressComponent[];
+    location?: {
+        latitude?: number;
+        longitude?: number;
+    };
+};
+export type GooglePlacesProviderOptions = {
+    /**
+     * Browser API key, sent as `X-Goog-Api-Key`. Restrict it to your sites and to Places API
+     * (New) in the Google Cloud console. Omit it when `endpoint` is your own proxy that adds the
+     * key on the server.
+     */
+    apiKey?: string;
+    /**
+     * Base URL of the Places API, or of a proxy that forwards `POST {endpoint}/places:autocomplete`
+     * and `GET {endpoint}/places/{id}` to it. Defaults to `https://places.googleapis.com/v1`.
+     */
+    endpoint?: string;
+    /** Language of the results when the field does not pass one. */
+    language?: string;
+    /** CLDR region code that biases the results and formats them ("fr"). */
+    region?: string;
+    /**
+     * Primary place types the search is limited to (up to 5). Defaults to addresses only
+     * (`street_address`, `premise`, `subpremise`, `route`), so shops and landmarks stay out;
+     * pass `[]` to search every place.
+     */
+    types?: readonly string[];
+    /** Fetch implementation, for a server or a test. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+};
+/**
+ * An `Address` from a Google Place: the street line in the country's order, the postal town
+ * or the nearest locality as the city, the first administrative level as the region (its short
+ * form in the United States, Canada and Australia, where it is written "CA" or "NSW").
+ */
+export declare function parseGooglePlace(place: GooglePlace): Address;
+/** A Places request that failed, with its HTTP status. */
+export declare class GooglePlacesError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * An `AddressProvider` backed by Google Places (Places API "New"). Pass a browser `apiKey`, or an
+ * `endpoint` on your server that adds the key, so it never reaches the page.
+ */
+export declare function createGooglePlacesProvider(options?: GooglePlacesProviderOptions): AddressProvider;
+export type GooglePlacesProxyOptions = {
+    /** Server-side Places API (New) key. It stays on the server: the page never sees it. */
+    apiKey: string | undefined;
+    /** Fetch implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+};
+type ProxyEvent = {
+    request: Request;
+};
+/**
+ * Server handlers for the route `AddressInput` searches through by default
+ * (`/api/places/[...path]`): they forward the two Places calls to Google with the server's key.
+ * Nothing else passes: any other path or method answers 404, so the route is not an open proxy.
+ *
+ * ```ts
+ * // src/routes/api/places/[...path]/+server.ts
+ * import { createGooglePlacesProxy } from './index.ts';
+ * export const { GET, POST } = createGooglePlacesProxy({ apiKey: GOOGLE_PLACE_API_KEY });
+ * ```
+ */
+export declare function createGooglePlacesProxy({ apiKey, fetch: fetchImpl }: GooglePlacesProxyOptions): {
+    POST: ({ request }: ProxyEvent) => Promise<Response>;
+    GET: ({ request }: ProxyEvent) => Promise<Response>;
+};
+export {};