@aparte/plugin-cards 0.0.0-stage → 0.29.0

package/dist/media/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @aparte/plugin-cards/media — a tool's pictures, videos and sounds, drawn as a card: one
+ * photo large, a gallery as a mosaic, a row of thumbnails, a lightbox to see each one big.
+ *
+ *   import { setupMediaCard } from '@aparte/plugin-cards/media';
+ *
+ *   setupMediaCard({ tool: 'generate_image' });                         // DALL·E's `{ data: [{ url }] }` as it is
+ *   setupMediaCard({ tool: 'search_photos', map: (r) => r.results });   // Unsplash, Pexels…
+ *
+ * One medium, several (`[...]`), or `{ title, items: [...] }`. Three variants of one card:
+ * `single` (the first medium large, its caption under it), `gallery` (a mosaic, the first
+ * larger, "+3" on the last tile) and `strip` (square thumbnails that scroll sideways). Every
+ * picture opens in a lightbox: the browser's own `<dialog>`, wearing core's `.aparte-dialog`.
+ *
+ * Nothing here plays a third party: a video is the native `<video>`, a sound the native
+ * `<audio>`, and a YouTube or Vimeo page is a poster that LINKS to it — no iframe, no
+ * player script. What the browser fetches is what the tool's data names — the medium, its
+ * poster — and nothing else: no thumbnail is derived from a video's address, no service
+ * is asked about a link. An HLS or DASH stream (`.m3u8`, `.mpd`) plays in the native
+ * `<video>` only where the browser says it can (Safari, for HLS); elsewhere it would need a
+ * player script, so it is a poster that links out, like a YouTube page.
+ */
+import type { AparteConfig } from '@aparte/core';
+import { type CardSetupOptions } from '../kit/define.js';
+export type MediaKind = 'image' | 'video' | 'audio';
+export type MediaVariant = 'single' | 'gallery' | 'strip';
+/**
+ * A medium as `map` returns it. Only `src` is needed; every other field adds something when
+ * it is there and nothing when it is not. `readMedia` also reads the usual aliases (listed
+ * on each field).
+ */
+export interface MediumInput {
+    /** Read from the address's extension or `mimeType` when absent. Also `type`, `mediaType`. */
+    kind?: MediaKind;
+    /** An `http(s)` address. Also `url`, `link`, `href`, `image`, `imageUrl`, `thumbnail`, Unsplash's `urls.regular`. */
+    src: string;
+    /** The still shown before a video plays, the cover of a sound, a smaller copy of an image for its tile. Also `thumb`, `preview`. */
+    poster?: string;
+    title?: string;
+    /** Also `description`, and an image model's `revised_prompt`. */
+    caption?: string;
+    /** Who made it, or where it comes from. Also `author`, `source`, `photographer`, Unsplash's `user.name`. */
+    credit?: string;
+    /** What the picture shows, for a reader who cannot see it. Also `alt_description`. */
+    alt?: string;
+    /** With `height`, reserves the picture's shape before it loads — nothing jumps when it does. */
+    width?: number;
+    height?: number;
+    /** In seconds; `"3:42"` and ISO 8601 (`"PT3M42S"`) are read too. */
+    duration?: number | string;
+    mimeType?: string;
+    /** The page the medium comes from. */
+    url?: string;
+}
+/** A medium as the card draws it, once read. */
+export interface Medium {
+    kind: MediaKind;
+    src: string;
+    /**
+     * Set when `src` is a video's page on a site that plays it itself ("YouTube", "Vimeo"):
+     * drawn as a poster that links out, never embedded.
+     */
+    site?: string;
+    poster?: string;
+    title?: string;
+    caption?: string;
+    credit?: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    duration?: number;
+    mimeType?: string;
+    url?: string;
+}
+/** The card's data: one medium or several, and the collection's title. */
+export interface MediaData {
+    title?: string;
+    items: Medium[];
+}
+export type MediaCardOptions = CardSetupOptions<MediaData, MediaVariant>;
+/**
+ * A length in seconds from what tools write: a number, `"3:42"`, `"1:02:03"`, ISO 8601's
+ * `"PT3M42S"` (YouTube's API). `undefined` for anything else.
+ */
+export declare function readDuration(value: unknown): number | undefined;
+/**
+ * The card's data from what `map` returns: one medium (an object, or its address), an array,
+ * or a collection (`{ title?, items | media | images | photos | videos | results | data }` —
+ * the last is an image model's answer). At most 24; `null` when not one has an `http(s)` source.
+ */
+export declare function readMedia(raw: unknown): MediaData | null;
+/** A length as a player writes it, in the chat's digits: `3:42`, `1:02:03`. */
+export declare function formatDuration(config: AparteConfig, seconds: number): string;
+/** The media card — for `mediaCard.segment(data)`. Plug it in with `setupMediaCard`. */
+export declare const mediaCard: {
+    name: string;
+    variants: readonly MediaVariant[];
+    setup: (options?: CardSetupOptions<MediaData, MediaVariant>) => () => void;
+    segment: (raw: unknown, options?: {
+        id?: string;
+        variant?: MediaVariant | undefined;
+        config?: AparteConfig;
+    }) => import("../index.js").AparteCardSegment;
+};
+/** Draw a tool's media as this card — returns the function that stops it. */
+export declare function setupMediaCard(options?: MediaCardOptions): () => void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/media/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAgC,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAOvF,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AACpD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,6FAA6F;IAC7F,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,qHAAqH;IACrH,GAAG,EAAE,MAAM,CAAC;IACZ,oIAAoI;IACpI,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4GAA4G;IAC5G,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gDAAgD;AAChD,MAAM,WAAW,MAAM;IACnB,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AA0EzE;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAc/D;AAsGD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAmBxD;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ5E;AAwaD,wFAAwF;AACxF,eAAO,MAAM,SAAS;;;;;;;;;CAWpB,CAAC;AAEH,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,OAAO,GAAE,gBAAqB,GAAG,MAAM,IAAI,CAEzE"}