@aparte/plugin-cards 0.0.0-stage → 0.29.0

package/dist/place/index.d.ts

@@ -0,0 +1,207 @@
+/**
+ * @aparte/plugin-cards/place — a tool's places, drawn as cards: a restaurant, a shop, a
+ * hotel, a venue, with its rating, whether it is open now, and the way there.
+ *
+ *   import { setupPlaceCard } from '@aparte/plugin-cards/place';
+ *
+ *   setupPlaceCard({ tool: 'search_places', map: (result) => result.results });
+ *
+ * One place or several (`[...]`, or `{ title, places: [...] }`). Three variants of one
+ * card: `card` (a tile with its photo; several scroll sideways), `compact` (one row each,
+ * stacked) and `detail` (one place in full, with its week of opening hours). Your tool keeps
+ * its own fields: `readPlaces` reads the usual names for each (Google Places, both
+ * generations, Yelp, OpenStreetMap-ish tools, what a model writes by hand), and `map` says
+ * the rest.
+ *
+ * Whether a place is open is worked out when the card is drawn, from its weekly `hours`
+ * (`isOpenAt`, `placeStatus`) — Google's current hours, holidays included, before its
+ * regular week — else from the tool's own `openNow`. The three buttons a place
+ * gets for free — Directions, Call, Website — appear only when its data can honour them,
+ * and an app that passes its own `actions` replaces them.
+ */
+import type { AparteConfig } from '@aparte/core';
+import { type CardSetupOptions } from '../kit/define.js';
+import { type PlaceKind } from './icons.js';
+export type { PlaceKind } from './icons.js';
+export type PlaceVariant = 'card' | 'compact' | 'detail';
+/** One opening range of the week, as a tool writes it. */
+export interface PlaceHoursInput {
+    /** 0 = Sunday … 6 = Saturday (7 reads as Sunday too), or an English day name ("mon", "Monday"). */
+    day: number | string;
+    /** "09:00", "9:30", "0900", "21h30", "9 PM". */
+    open: string;
+    /** Past midnight is fine ("02:00" after "18:00"). Missing, or "24:00", is midnight. */
+    close?: string;
+}
+/** An opening range once read: minutes from the start of `day`. `end` passes 1440 when it closes after midnight. */
+export interface PlaceHoursRange {
+    day: number;
+    start: number;
+    end: number;
+}
+/**
+ * A place as `map` returns it. Only `name` is needed; every other field adds a line when it
+ * is there and nothing when it is not. `readPlaces` also reads the usual aliases (listed on
+ * each field).
+ */
+export interface PlaceInput {
+    /** Also `title`, `displayName`. */
+    name: string;
+    /** Shown as it is: "Trattoria", "Boulangerie". Also `primaryTypeDisplayName`, `categories[0]`. */
+    category?: string;
+    /** Google's `types`, read only to choose a glyph and, without `category`, a word. */
+    types?: string[];
+    /** An `http(s)` photo. Also `photo`, `imageUrl`, `thumbnail`, `photos[0]`. */
+    image?: string;
+    /** 0–5 (a 10-point score is halved). */
+    rating?: number;
+    /** Also `user_ratings_total`, `userRatingCount`, `reviews`, `review_count`. */
+    reviewCount?: number;
+    /** 1–4, `"€€"`, or Google's `"PRICE_LEVEL_MODERATE"`; any other text is shown as it is ("€10–20"). Also `price_level`. */
+    priceLevel?: number | string;
+    /** Also `formatted_address`, `formattedAddress`, `vicinity`, Yelp's `location.display_address`. */
+    address?: string;
+    /** In metres; a text ("12 min walk") is shown as it is. Also `distanceMeters`. */
+    distance?: number | string;
+    /** Also `formatted_phone_number`, `international_phone_number`, `nationalPhoneNumber`. */
+    phone?: string;
+    /** The place's own site. Also `websiteUri`. */
+    website?: string;
+    /** The place's page (on a map, a guide); the name links to it. Also `googleMapsUri`. */
+    url?: string;
+    /** Also `lat`/`lng`, `latitude`/`longitude`, `geometry.location`, `location`. */
+    coordinates?: {
+        lat: number;
+        lng: number;
+    };
+    /** Google's place id, which makes Directions land on the place itself. Also `place_id`. */
+    placeId?: string;
+    /** The tool's own answer; `hours` wins when both are given. Also `open_now`, `isOpen`, `opening_hours.open_now`, Yelp's `hours[0].is_open_now`. */
+    openNow?: boolean;
+    /**
+     * The week's opening hours: `[{ day, open, close }]` (several ranges a day, closing past
+     * midnight), Google's `periods` or `weekday_text`, Yelp's `hours`, or
+     * `{ monday: "09:00-18:00", sunday: "closed" }`. Also `currentOpeningHours` (read first:
+     * it has the holidays), `regularOpeningHours`, `opening_hours`, `openingHours`.
+     */
+    hours?: PlaceHoursInput[] | Record<string, unknown> | string[];
+    /** The place's offset from UTC in minutes, so "Open now" is read on the place's clock. Also `utc_offset_minutes`. */
+    utcOffset?: number;
+    /** At most four short facts: "Terrace", "Vegan". Also `features`, `amenities`. */
+    tags?: string[];
+}
+/** A price level once read: the tier, and the sign the source wrote it with, if it did. */
+export interface PlacePrice {
+    level: number;
+    symbol?: string;
+}
+/** A place as the card draws it, once read. */
+export interface Place {
+    name: string;
+    category?: string;
+    kind: PlaceKind;
+    image?: string;
+    rating?: number;
+    reviewCount?: number;
+    price?: PlacePrice;
+    priceText?: string;
+    address?: string;
+    distance?: number;
+    distanceText?: string;
+    phone?: string;
+    website?: string;
+    url?: string;
+    coordinates?: {
+        lat: number;
+        lng: number;
+    };
+    placeId?: string;
+    openNow?: boolean;
+    hours: PlaceHoursRange[];
+    utcOffset?: number;
+    tags: string[];
+}
+/** The card's data: one place or several, and the collection's title. */
+export interface PlaceData {
+    title?: string;
+    places: Place[];
+}
+/** Whether a place is open at a moment, and when that changes (none: it never does). */
+export interface PlaceStatus {
+    open: boolean;
+    changesAt?: Date;
+}
+/** How an app plugs the place card in: the kit's options, and two of the card's own. */
+export interface PlaceCardOptions extends CardSetupOptions<PlaceData, PlaceVariant> {
+    /**
+     * The sign a price TIER (1–4) is drawn with. A tier is a scale, not an amount — Google
+     * and Yelp return a number, not a currency — so the card cannot know the place's money.
+     * `$` by default, the sign those APIs' own documentation uses; a European app passes `€`.
+     * A tier the source wrote with its own sign ("€€") keeps it. Read aloud as
+     * "Price level 2 of 4" either way.
+     */
+    currencySymbol?: string;
+    /** The clock "Open now" is read against — the device's by default; a test or a replay passes its own. */
+    now?: () => Date;
+    /**
+     * The Directions / Call / Website buttons on each place, drawn from its data (`true` by
+     * default). They are the place's own; the app's `actions` are the card's, under it, and
+     * one does not replace the other. `false` draws none.
+     */
+    builtIns?: boolean;
+}
+/** Minutes from midnight: "09:00", "9:30", "0900", "21h30", "9 PM", Google's `{ hour, minute }`. */
+export declare function readTime(value: unknown): number | undefined;
+/**
+ * The week's opening hours from the shapes tools write them in: `[{ day, open, close }]`,
+ * Google's `periods` (`{ open: { day, time | hour, minute }, close }`), its `weekday_text`
+ * ("Monday: 9:00 AM – 5:00 PM"), or a week by name (`{ monday: "09:00-18:00" }`).
+ * Anything it cannot read is left out.
+ */
+export declare function readHours(raw: unknown): PlaceHoursRange[];
+/**
+ * Whether a place with these hours is open at `date`, and when that changes — read on
+ * `date`'s own clock (pass the place's local time). `null` when the hours say nothing.
+ * Hours take any shape `readHours` reads.
+ */
+export declare function placeStatus(hours: unknown, date: Date): PlaceStatus | null;
+/** Whether a place with these hours is open at `date`. No hours, no answer: `false`. */
+export declare function isOpenAt(hours: unknown, date: Date): boolean;
+/**
+ * The card's data from what `map` returns: one place, an array of places, or a collection
+ * (`{ title?, places | results | candidates }`). At most ten places; `null` when not one
+ * has a name.
+ */
+export declare function readPlaces(raw: unknown): PlaceData | null;
+/**
+ * Google Maps directions to the place: to its coordinates when known, else to its name and
+ * address, landing on the place itself when its Google id is known. `null` without either.
+ */
+export declare function directionsUrl(place: Pick<Place, 'name' | 'address' | 'coordinates' | 'placeId'>): string | null;
+/**
+ * A `tel:` link from a written number — its digits, and the `+` before the first of them
+ * ("Tel: +33 …" keeps it). An extension ("ext. 12", "x12", "#3") is not part of the number:
+ * dialled as digits, it would make a different one. `null` for no number.
+ */
+export declare function phoneUrl(phone: string | undefined): string | null;
+/**
+ * The place card with its built-in buttons and the device's clock — for `placeCard.segment(data)`.
+ * Plug it in with `setupPlaceCard`, which also hears the card's own options.
+ */
+export declare const placeCard: {
+    name: string;
+    variants: readonly PlaceVariant[];
+    setup: (options?: CardSetupOptions<PlaceData, PlaceVariant>) => () => void;
+    segment: (raw: unknown, options?: {
+        id?: string;
+        variant?: PlaceVariant | undefined;
+        config?: AparteConfig;
+    }) => import("../index.js").AparteCardSegment;
+};
+/**
+ * Draw a tool's places as this card — returns the function that stops it. Each place keeps
+ * its Directions / Call / Website buttons beside the app's own `actions` unless `builtIns`
+ * is `false`.
+ */
+export declare function setupPlaceCard(options?: PlaceCardOptions): () => void;
+//# sourceMappingURL=index.d.ts.map

package/dist/place/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/place/index.ts"],"names":[],"mappings":"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"}