@gallerist/plugin-pins 0.0.0-stage → 0.3.1

package/dist/index.d.cts

@@ -0,0 +1,130 @@
+import { ViewerApi, Group, Item, Plugin } from '@gallerist/core';
+
+type PinPresentation = 'comment' | 'tag' | 'feature';
+interface PinReply {
+    author?: string;
+    /** a secondary line, e.g. a timestamp */
+    meta?: string;
+    body: string;
+}
+interface Pin {
+    id: string;
+    /** position on the image: 0..1 of its width/height (`normalized`, default) or image pixels */
+    x: number;
+    y: number;
+    space?: 'normalized' | 'natural';
+    /** short name: the product, the feature, or the comment's author line; also the pin's label */
+    label?: string;
+    /** the card's text: a comment, a description */
+    body?: string;
+    /** a secondary line: a price, a timestamp, a dimension */
+    meta?: string;
+    /** a link from the card (a product page) */
+    href?: string;
+    /** the link's text; defaults to `strings.open` */
+    linkLabel?: string;
+    /** comment threads: the replies under the first comment */
+    replies?: PinReply[];
+    /** comment threads: drawn muted and marked as resolved */
+    resolved?: boolean;
+}
+interface PinContext {
+    viewer: ViewerApi;
+    group: Group;
+    item: Item;
+}
+/** `onOpenChange`'s context: the pin's item, and the pin whose card was open before this change. */
+interface PinOpenChange extends PinContext {
+    /** the pin whose card was open until now (the one that closed), or `null` if none was */
+    previous: Pin | null;
+}
+/** Options for `open()`. */
+interface PinOpenOptions {
+    /** move focus: into the card when it opens (once it is painted), to the pin when it closes */
+    focus?: boolean;
+}
+interface PinsStrings {
+    /** the toolbar toggle's label */
+    toggle: string;
+    /** the "place a comment" button's label */
+    add: string;
+    /** shown while placing a comment */
+    placing: string;
+    /** a pin's accessible name: its number (1-based) and label */
+    pin: (n: number, label?: string) => string;
+    /** the card's close button */
+    close: string;
+    /** default link text */
+    open: string;
+    /** a resolved thread's badge */
+    resolved: string;
+}
+declare const DEFAULT_PINS_STRINGS: PinsStrings;
+interface PinsOptions {
+    /** how pins look and what their card holds. Default `tag`. */
+    presentation?: PinPresentation;
+    /** the pins of an item. Default: `item.meta.pins`. */
+    pins?: (item: Item, group: Group) => readonly Pin[] | undefined;
+    /** whether pins start shown (default true); the toolbar toggle and the `p` key flip it */
+    visible?: boolean;
+    /** add the show/hide toggle to the toolbar (default true) */
+    toggle?: boolean;
+    /**
+     * Replace the card's contents for a pin; `null` (or `undefined`) keeps the default card
+     * (`defaultPinCard`) for that pin. Called each time the card opens, and again when an open card
+     * is redrawn (`refresh()`, new data); the card is empty while closed. Returning the same node
+     * again (one cached per pin) is supported. If it throws, the pin gets the default card and the
+     * error is reported (`reportError`, else `console.error`). Don't call `open()` from here.
+     */
+    renderCard?: (pin: Pin, ctx: PinContext) => Node | null | undefined;
+    /**
+     * A node `renderCard` returned was dropped: its card closed (by the user, `open()`, moving to
+     * another item, the pin leaving the data), was redrawn, or the plugin or viewer was destroyed.
+     * Called once per returned node, after it left the card, so a host can unmount what it rendered
+     * there (a React root or portal). Not called for the default card, nor for a node `renderCard`
+     * returned again for the redrawn card (it hasn't left; it is handed back when it does). Runs once
+     * the change has settled, before `onOpenChange`; calling `open()` from it is fine.
+     */
+    onCardRemove?: (pin: Pin, node: Node) => void;
+    /**
+     * A pin's card opened (`pin`) or closed (`null`). `ctx.previous` is the pin whose card was open
+     * until now: the one that closed, also when another pin's card replaced it. When a callback
+     * changes the card again (`open()`), an earlier call may describe a state already replaced: the
+     * last one is current.
+     */
+    onOpenChange?: (pin: Pin | null, ctx: PinOpenChange) => void;
+    /**
+     * Turns on placing: an "Add a comment" toolbar button (and the `c` key) arms a one-shot click on
+     * the image, and this is called with the point in normalized image coordinates. Add the pin to
+     * your data and call `refresh()` (or update the collection) to show it.
+     */
+    onPlace?: (at: {
+        x: number;
+        y: number;
+    }, ctx: PinContext) => void;
+    strings?: Partial<PinsStrings>;
+}
+/** The plugin, plus controls for the host. */
+interface PinsPlugin extends Plugin {
+    /** re-read every pin (after the host changed pin data in place) */
+    refresh(): void;
+    /** show or hide all pins */
+    setVisible(visible: boolean): void;
+    /** open a pin's card on the current item by id; `null` closes it. `{ focus: true }` moves focus
+     *  into the card (or, closing, to its pin). */
+    open(id: string | null, opts?: PinOpenOptions): void;
+}
+/** What `defaultPinCard` draws: the presentation and the strings it uses (`open`, `resolved`). */
+interface PinCardOptions {
+    /** default `tag` */
+    presentation?: PinPresentation;
+    strings?: Partial<PinsStrings>;
+}
+/**
+ * The card contents `pins()` draws for a pin by default, for a `renderCard` that wraps or extends
+ * them (text is set as text, never parsed as HTML).
+ */
+declare function defaultPinCard(pin: Pin, opts?: PinCardOptions): DocumentFragment;
+declare function pins(opts?: PinsOptions): PinsPlugin;
+
+export { DEFAULT_PINS_STRINGS, type Pin, type PinCardOptions, type PinContext, type PinOpenChange, type PinOpenOptions, type PinPresentation, type PinReply, type PinsOptions, type PinsPlugin, type PinsStrings, defaultPinCard, pins };

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+import { ViewerApi, Group, Item, Plugin } from '@gallerist/core';
+
+type PinPresentation = 'comment' | 'tag' | 'feature';
+interface PinReply {
+    author?: string;
+    /** a secondary line, e.g. a timestamp */
+    meta?: string;
+    body: string;
+}
+interface Pin {
+    id: string;
+    /** position on the image: 0..1 of its width/height (`normalized`, default) or image pixels */
+    x: number;
+    y: number;
+    space?: 'normalized' | 'natural';
+    /** short name: the product, the feature, or the comment's author line; also the pin's label */
+    label?: string;
+    /** the card's text: a comment, a description */
+    body?: string;
+    /** a secondary line: a price, a timestamp, a dimension */
+    meta?: string;
+    /** a link from the card (a product page) */
+    href?: string;
+    /** the link's text; defaults to `strings.open` */
+    linkLabel?: string;
+    /** comment threads: the replies under the first comment */
+    replies?: PinReply[];
+    /** comment threads: drawn muted and marked as resolved */
+    resolved?: boolean;
+}
+interface PinContext {
+    viewer: ViewerApi;
+    group: Group;
+    item: Item;
+}
+/** `onOpenChange`'s context: the pin's item, and the pin whose card was open before this change. */
+interface PinOpenChange extends PinContext {
+    /** the pin whose card was open until now (the one that closed), or `null` if none was */
+    previous: Pin | null;
+}
+/** Options for `open()`. */
+interface PinOpenOptions {
+    /** move focus: into the card when it opens (once it is painted), to the pin when it closes */
+    focus?: boolean;
+}
+interface PinsStrings {
+    /** the toolbar toggle's label */
+    toggle: string;
+    /** the "place a comment" button's label */
+    add: string;
+    /** shown while placing a comment */
+    placing: string;
+    /** a pin's accessible name: its number (1-based) and label */
+    pin: (n: number, label?: string) => string;
+    /** the card's close button */
+    close: string;
+    /** default link text */
+    open: string;
+    /** a resolved thread's badge */
+    resolved: string;
+}
+declare const DEFAULT_PINS_STRINGS: PinsStrings;
+interface PinsOptions {
+    /** how pins look and what their card holds. Default `tag`. */
+    presentation?: PinPresentation;
+    /** the pins of an item. Default: `item.meta.pins`. */
+    pins?: (item: Item, group: Group) => readonly Pin[] | undefined;
+    /** whether pins start shown (default true); the toolbar toggle and the `p` key flip it */
+    visible?: boolean;
+    /** add the show/hide toggle to the toolbar (default true) */
+    toggle?: boolean;
+    /**
+     * Replace the card's contents for a pin; `null` (or `undefined`) keeps the default card
+     * (`defaultPinCard`) for that pin. Called each time the card opens, and again when an open card
+     * is redrawn (`refresh()`, new data); the card is empty while closed. Returning the same node
+     * again (one cached per pin) is supported. If it throws, the pin gets the default card and the
+     * error is reported (`reportError`, else `console.error`). Don't call `open()` from here.
+     */
+    renderCard?: (pin: Pin, ctx: PinContext) => Node | null | undefined;
+    /**
+     * A node `renderCard` returned was dropped: its card closed (by the user, `open()`, moving to
+     * another item, the pin leaving the data), was redrawn, or the plugin or viewer was destroyed.
+     * Called once per returned node, after it left the card, so a host can unmount what it rendered
+     * there (a React root or portal). Not called for the default card, nor for a node `renderCard`
+     * returned again for the redrawn card (it hasn't left; it is handed back when it does). Runs once
+     * the change has settled, before `onOpenChange`; calling `open()` from it is fine.
+     */
+    onCardRemove?: (pin: Pin, node: Node) => void;
+    /**
+     * A pin's card opened (`pin`) or closed (`null`). `ctx.previous` is the pin whose card was open
+     * until now: the one that closed, also when another pin's card replaced it. When a callback
+     * changes the card again (`open()`), an earlier call may describe a state already replaced: the
+     * last one is current.
+     */
+    onOpenChange?: (pin: Pin | null, ctx: PinOpenChange) => void;
+    /**
+     * Turns on placing: an "Add a comment" toolbar button (and the `c` key) arms a one-shot click on
+     * the image, and this is called with the point in normalized image coordinates. Add the pin to
+     * your data and call `refresh()` (or update the collection) to show it.
+     */
+    onPlace?: (at: {
+        x: number;
+        y: number;
+    }, ctx: PinContext) => void;
+    strings?: Partial<PinsStrings>;
+}
+/** The plugin, plus controls for the host. */
+interface PinsPlugin extends Plugin {
+    /** re-read every pin (after the host changed pin data in place) */
+    refresh(): void;
+    /** show or hide all pins */
+    setVisible(visible: boolean): void;
+    /** open a pin's card on the current item by id; `null` closes it. `{ focus: true }` moves focus
+     *  into the card (or, closing, to its pin). */
+    open(id: string | null, opts?: PinOpenOptions): void;
+}
+/** What `defaultPinCard` draws: the presentation and the strings it uses (`open`, `resolved`). */
+interface PinCardOptions {
+    /** default `tag` */
+    presentation?: PinPresentation;
+    strings?: Partial<PinsStrings>;
+}
+/**
+ * The card contents `pins()` draws for a pin by default, for a `renderCard` that wraps or extends
+ * them (text is set as text, never parsed as HTML).
+ */
+declare function defaultPinCard(pin: Pin, opts?: PinCardOptions): DocumentFragment;
+declare function pins(opts?: PinsOptions): PinsPlugin;
+
+export { DEFAULT_PINS_STRINGS, type Pin, type PinCardOptions, type PinContext, type PinOpenChange, type PinOpenOptions, type PinPresentation, type PinReply, type PinsOptions, type PinsPlugin, type PinsStrings, defaultPinCard, pins };