@cloudgrid-io/ui 0.35.0 → 0.37.0

package/dist/badge/fan.d.ts

@@ -0,0 +1,211 @@
+/**
+ * THE REACTION FAN (ui#351): the visitor's way in, replacing the feedback
+ * bubble. Vlad's design, as Tamir approved it on 2026-10-21 after trying the
+ * prototype on a desktop and an iPhone.
+ *
+ * At rest it is a small drop in the bottom-right corner, round with one sharp
+ * corner at the bottom left, holding the CloudGrid plug. It follows the system
+ * theme: purple with a white plug on a light system, white with a purple plug on
+ * a dark one. Opened, four options fan out up and to the left: Like, Dislike,
+ * Clever idea and Comment. The first three save in one tap; Comment opens the
+ * visitor panel, which is unchanged.
+ *
+ * This module has three parts, in the badge's usual style:
+ *
+ *   markup     `fan()`, an HTML string like `bubble()`; the stylesheet is
+ *              `BADGE_FAN_CSS`, already inside `BADGE_VISITOR_CSS` and
+ *              `BADGE_OWNER_CSS`
+ *   helpers    pure functions and the approved timings, tested in node
+ *   behaviour  `wireFan()`, which attaches the approved hover, touch and
+ *              keyboard behaviour to a rendered fan and reports each choice;
+ *              `wireFanPreview()` does the same for the owner's small copy
+ *
+ * Unlike the panels, the fan's state is not all in its markup: whether it is
+ * open, which option is under a finger and the cue that plays on a press are
+ * moment-to-moment, and live on the element. Render `fan()` once, wire it, and
+ * from then on update it with the handle (`sync`, `chosen`, `setHidden`), never
+ * by re-rendering or morphing it. The pressed state the markup takes is only the
+ * first paint.
+ *
+ * Importing this module does nothing: every DOM call is inside `wireFan()`.
+ */
+import { type ReactionKind } from "./reactions.js";
+export { BADGE_FAN_CSS } from "./css-fan.js";
+/** Desktop: how long the pointer rests on the icon before the fan opens. */
+export declare const FAN_HOVER_OPEN_MS = 120;
+/** Desktop: how long after the pointer leaves the fan before it closes. */
+export declare const FAN_HOVER_CLOSE_MS = 300;
+/**
+ * Touch: after every lift the fan stays open this long, then closes by itself.
+ * A tap inside the window chooses (founder, 2026-10-21; it was 0.5s).
+ */
+export declare const FAN_RELEASE_MS = 1200;
+/** After Like, Dislike or Clever idea is pressed, the fan closes this long after the cue starts. */
+export declare const FAN_CHOICE_CLOSE_MS = 1000;
+/** How long the check shows in a pressed option before its glyph comes back. */
+export declare const FAN_CHECK_MS = 650;
+/** A click this soon after hover opened the fan is the same intent: it keeps the fan open. */
+export declare const FAN_CLICK_AFTER_HOVER_MS = 700;
+/** A click this soon after a touch is the touch's own echo, and is ignored. */
+export declare const FAN_TOUCH_ECHO_MS = 800;
+/** The haptic tick when a finger slides onto an option, where the browser has one. */
+export declare const FAN_VIBRATE_MS = 10;
+export { FAN_DIRECTIONS, FAN_HIT_SLOP, FAN_HOT_SCALE, FAN_SIZE } from "./fan-geometry.js";
+/** What a fan option does: one of the three one-tap reactions, or Comment. */
+export type FanKind = "like" | "dislike" | "idea" | "comment";
+/**
+ * The four options, in order around the fan. The three reactions take the
+ * panel's own names, so the fan and the panel never call one thing two names.
+ */
+export declare const FAN_OPTIONS: ReadonlyArray<{
+    kind: FanKind;
+    label: string;
+    paths: readonly string[];
+}>;
+/** The icon's accessible name, the bubble's: the word "React" is never used. */
+export declare const FAN_LABEL = "Leave feedback on this app";
+/**
+ * The small marks the icon keeps for what this visitor has chosen, in this
+ * order. Rocket and Bug are chosen in the panel only, and still show here.
+ */
+export declare function fanMarkKinds(pressed: readonly ReactionKind[]): ReactionKind[];
+/** The line a screen reader hears after a press: "Like saved", "Like removed". */
+export declare function fanAnnouncement(kind: ReactionKind, on: boolean): string;
+/**
+ * What a press on `kind` does to the pressed set, and which cues play: the
+ * pressed option pops (or shrinks, when it is taken back), and an option the
+ * press cleared (Like and Dislike exclude each other) shrinks too. Comment is
+ * not a reaction and changes nothing here.
+ */
+export declare function fanPress(pressed: readonly ReactionKind[], kind: ReactionKind): {
+    next: ReactionKind[];
+    on: boolean;
+    cleared: ReactionKind[];
+};
+export interface FanHitGeometry {
+    /** The icon's centre, in client pixels. */
+    cx: number;
+    cy: number;
+    /** Half the icon's drawn width. A point on the icon is never an option. */
+    iconHalf: number;
+    /** The radius and option size, unscaled (`FAN_SIZE`). */
+    radius: number;
+    option: number;
+    /** The drawn scale: 1 in the corner, 0.5 in the owner's preview. */
+    scale?: number;
+    /** The option currently under the finger, whose hit area has grown with it. */
+    hot?: number;
+}
+/**
+ * The option under a point, or -1. It tests where each option LANDS, not where
+ * it is mid-spread, so a quick tap on the icon never picks an option that is
+ * still passing under it. A point on the icon is never an option. Of the
+ * options whose square (half the option, grown when hot, plus the slop) holds
+ * the point, the nearest wins.
+ */
+export declare function fanOptionAt(x: number, y: number, g: FanHitGeometry): number;
+/** `auto` follows the system setting; `light` and `dark` pin the icon, for a frozen frame. */
+export type FanTheme = "auto" | "light" | "dark";
+export interface FanOptions {
+    /** The kinds this visitor has already chosen: options drawn pressed, and the marks on the icon. First paint only. */
+    pressed?: readonly ReactionKind[];
+    /** Render it open, for a frozen frame and for the owner's preview. The badge opens it through the handle. */
+    open?: boolean;
+    /** Default `auto`. */
+    theme?: FanTheme;
+    /** The icon's accessible name. Default `FAN_LABEL`. */
+    label?: string;
+    /**
+     * When the arrival starts, in ms after insertion. Default 600, after the
+     * live badge's, as the bubble's was. `0` for a re-show.
+     */
+    delay?: number;
+    /**
+     * The owner's small working copy in the "Ask visitors for feedback"
+     * explanation: no tab stops, no arrival, no status line, never the touch
+     * sizes. It sits inside a decorative (`aria-hidden`) tile.
+     */
+    preview?: boolean;
+}
+/** One mark on the icon. `fresh` pops in; the first paint's marks are at rest. */
+export declare function fanMark(kind: ReactionKind, fresh?: boolean): string;
+/**
+ * The fan: the drop icon, its marks, and the four options. Closed and at rest
+ * unless `open`. Every option is a button with its name and tooltip; the three
+ * reactions carry `aria-pressed`, Comment `aria-haspopup="dialog"`. The options
+ * are `inert` while the fan is closed.
+ *
+ * No `data-action` anywhere: `wireFan()` handles every press itself and reports
+ * the choice, so a delegated `[data-action]` listener never sees the fan.
+ */
+export declare function fan({ pressed, open, theme, label: name, delay, preview }?: FanOptions): string;
+export interface WireFanOptions {
+    /**
+     * A press on an option. Like, Dislike and Clever idea: save the reaction, then
+     * call `handle.chosen(before, after, kind)` for the cue. Comment: close the
+     * fan and open the visitor panel. On an app that needs sign-in, close the fan
+     * and open the sign-in step instead.
+     */
+    onChoose: (kind: FanKind, handle: FanHandle) => void;
+    /**
+     * Use the touch sizes from the start. Default: on where the primary pointer
+     * is coarse or there is no hover. The first touch turns them on regardless.
+     */
+    touch?: boolean;
+    /** Close on a press anywhere outside the fan, and on Escape, in an open or a closed shadow root alike. Default true; the owner's preview turns it off. */
+    dismissable?: boolean;
+}
+export interface FanHandle {
+    /** The `.cgf` element. */
+    readonly el: HTMLElement;
+    readonly isOpen: boolean;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    /** The pressed state, without a cue: `aria-pressed` on the options and the marks on the icon. Marks already shown are kept, never popped again. */
+    sync(pressed: readonly ReactionKind[]): void;
+    /**
+     * After a press on a reaction: sync to `after`, pop the pressed option (or
+     * shrink it, when it was taken back) with a check, shrink any option the
+     * press cleared, announce it, and close `FAN_CHOICE_CLOSE_MS` later.
+     */
+    chosen(before: readonly ReactionKind[], after: readonly ReactionKind[], kind: ReactionKind): void;
+    /** Play one option's cue: `on` pops it (with the check unless `check` is false), otherwise it shrinks. */
+    cue(kind: FanKind | ReactionKind, on: boolean, check?: boolean): void;
+    /** Close `FAN_CHOICE_CLOSE_MS` from now, as after a choice. The pointer leaving does not cut it short. */
+    closeAfterCue(): void;
+    /** Hide it while a panel is open; showing it again replays the arrival at once. */
+    setHidden(hidden: boolean): void;
+    /** Focus the icon without opening the fan, as after a panel closes. */
+    focusIcon(): void;
+    /** Remove every listener and timer. */
+    destroy(): void;
+}
+/**
+ * Attach the approved behaviour to a fan rendered by `fan()`.
+ *
+ *   desktop    hover opens it after `FAN_HOVER_OPEN_MS`, leaving closes it
+ *              after `FAN_HOVER_CLOSE_MS`; a quick pass never opens it. A click
+ *              on the icon toggles (but not one right after hover opened it).
+ *              Closed while the pointer is still over it (after a choice, a
+ *              click, Escape), it reopens only once the pointer has left.
+ *   keyboard   focus on the icon opens it, Tab walks the options, Escape closes
+ *              it, and focus leaving the fan closes it.
+ *   touch      a press opens it; slide onto an option (it grows, and the phone
+ *              ticks) and lift to choose. After every lift it stays open for
+ *              `FAN_RELEASE_MS`, then closes; a tap inside that window chooses.
+ *              A tap on the icon while it is open closes it.
+ *
+ * The page never scrolls under a finger on the fan: the icon and the options
+ * take no touch gestures.
+ */
+export declare function wireFan(el: HTMLElement, { onChoose, touch, dismissable }: WireFanOptions): FanHandle;
+/**
+ * Wire the owner's small copy of the fan, in the "Ask visitors for feedback"
+ * explanation, so the owner can try exactly what visitors get. Choices are kept
+ * in the preview only and saved nowhere; Comment plays its pop and nothing
+ * opens. Call it after each render that shows the explanation, on
+ * `.cgb-info .cgf`, and `destroy()` the handle when the explanation closes.
+ */
+export declare function wireFanPreview(el: HTMLElement): FanHandle;
+//# sourceMappingURL=fan.d.ts.map

package/dist/badge/fan.d.ts.map

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