@goflowstate/widget-sdk 0.3.0 → 0.3.2

package/dist/feedback.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Flow feedback: the bug icon every flow carries (flowstate-docs plan 2026-11-09-flow-feedback).
+ *
+ * The session client mounts this when the session state says `feedbackEnabled`. A round button
+ * sits in the corner of the flow's own page. A tap takes a screenshot of the page as the person
+ * sees it, then opens a sheet: the thumbnail, one field, one button. The note goes out through
+ * the flow's own session (`session.request('feedback', …)`).
+ *
+ * It lives in the flow's document, in a shadow root, so it takes the flow's look instead of
+ * bringing one: the flow's fonts by inheritance, and its ground, ink, main button and corner
+ * radius read from the page (`readFlowTheme`). A flow pins any role with a `--fs-feedback-*`
+ * custom property on `:root`, and opts a page out with `<html data-fs-feedback="off">`.
+ */
+export interface FlowFeedbackTheme {
+    ground: string;
+    surface: string;
+    ink: string;
+    inkDim: string;
+    line: string;
+    fill: string;
+    cta: string;
+    ctaInk: string;
+    fontBody: string;
+    fontDisplay: string;
+    displayWeight: string;
+    radius: string;
+    buttonRadius: string;
+    dark: boolean;
+}
+export interface FlowFeedbackReport {
+    message: string;
+    screenshot?: string;
+    pageKey?: string;
+    pagePath: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+export interface FlowFeedbackOptions {
+    /** Sends the report. The session client passes `session.request('feedback', report)`. */
+    submit: (report: FlowFeedbackReport) => Promise<unknown>;
+    /** Renders the page to a JPEG data URL, or null when it cannot. Defaults to the built-in
+     *  rasterizer; tests and unusual hosts pass their own. */
+    capture?: () => Promise<string | null>;
+    /** Called once the icon is on the page, so a host page can hide its own fallback. */
+    onReady?: () => void;
+}
+export interface FlowFeedbackHandle {
+    /** The element the shadow root hangs from. */
+    readonly host: HTMLElement;
+    /** Re-read the flow's look (the page under the icon may have changed). */
+    refresh(): void;
+    open(): Promise<void>;
+    close(): void;
+    unmount(): void;
+}
+export declare const FEEDBACK_HOST_ATTR = "data-fs-feedback-host";
+/** The validator on the service accepts 160 KB of JPEG; stay under it with room for headers. */
+export declare const SCREENSHOT_MAX_BYTES = 150000;
+export declare const SCREENSHOT_MAX_SIDE = 1280;
+type Rgba = [number, number, number, number];
+export declare function parseColor(raw: string | null | undefined): Rgba | null;
+/** WCAG relative luminance. */
+export declare const luminance: (c: Rgba) => number;
+/**
+ * Read the look of the page the icon sits on. Order per role: the flow's own pin
+ * (`--fs-feedback-*`), what the page actually renders (computed styles), the flow's design
+ * tokens (`--sb-*`, then the Flowstate widget tokens), a neutral default.
+ */
+export declare function readFlowTheme(doc?: Document): FlowFeedbackTheme;
+/** Step the JPEG quality, then the size, until the picture fits the service's cap. */
+export declare function encodeScreenshot(canvas: HTMLCanvasElement): string | null;
+export declare const PLACEMENT_BASE = 16;
+export declare const PLACEMENT_STEP = 8;
+/** Clear space kept around the icon, so it does not crowd what it sits beside. */
+export declare const PLACEMENT_PAD = 8;
+/** The icon never climbs past this share of the viewport. */
+export declare const PLACEMENT_MAX_SHARE = 0.6;
+/** How far up empty space is still worth more than sitting on a line of text lower down. */
+export declare const PLACEMENT_READ_COST = 240;
+/** What is at a point: nothing, something to read or look at, or something to tap. */
+export declare const EMPTY = 0;
+export declare const READ = 1;
+export declare const TAP = 2;
+export type Occupancy = typeof EMPTY | typeof READ | typeof TAP;
+export interface PlacementBox {
+    /** The icon's box as measured now, in viewport pixels. */
+    left: number;
+    top: number;
+    size: number;
+    /** The bottom offset that box was measured at. */
+    bottom: number;
+}
+/**
+ * The bottom offset to sit at. `at(x, y)` says what is at a viewport point. An empty spot costs
+ * its height; a spot over text or a picture costs its height plus PLACEMENT_READ_COST; a spot
+ * over a control is taken only when there is no other, and then it is the base.
+ */
+export declare function choosePlacement(box: PlacementBox, viewportHeight: number, at: (x: number, y: number) => Occupancy): number;
+/**
+ * Reads what is at viewport points, the feedback host aside. One reader serves one placement
+ * pass: what it learns about an element is kept for the pass and dropped with it.
+ *
+ * A tap lands on the topmost element and travels up its ancestors, so only those can make a
+ * point a control: a button under the flow's own bottom sheet is not one. What a person reads
+ * is whatever shows through, down to the first element that paints its own ground.
+ */
+export declare function occupancyReader(host: Element, doc?: Document): (x: number, y: number) => Occupancy;
+export type DockState = 'float' | 'dock-left' | 'dock-right';
+export declare const BUTTON_SIZE = 44;
+export declare const TAB_WIDTH = 26;
+export declare const TAB_HEIGHT = 54;
+export declare const EDGE_MARGIN = 12;
+/** How far past an edge a release has to be heading before the button docks there. */
+export declare const DOCK_PAST = 14;
+/** Storage key for where the person left the button. One origin serves every flow, so the
+ *  choice follows them from flow to flow. */
+export declare const SPOT_KEY = "fs-feedback-spot";
+/** The part of the viewport the button may rest in: its size, less the safe-area insets. */
+export interface FeedbackViewport {
+    width: number;
+    height: number;
+    top: number;
+    bottom: number;
+}
+export interface FeedbackSpot {
+    state: DockState;
+    x: number;
+    y: number;
+}
+/** Where a release at velocity `v` (px per second) comes to rest: scroll deceleration. */
+export declare const projectMomentum: (v: number, deceleration?: number) => number;
+/** Past a boundary the button follows less and less, so the edge reads as soft, not stuck. */
+export declare const rubberband: (overshoot: number, dimension: number, constant?: number) => number;
+/** The resting spot for a state on one side, at a height. */
+export declare function restingSpot(state: DockState, left: boolean, y: number, view: FeedbackViewport): FeedbackSpot;
+/**
+ * Where a drag that ends at (x, y) with velocity (vx, vy) settles. A floating button heading
+ * past an edge, or let go against one, docks on that side; otherwise it floats on the side its
+ * momentum carries it to. A docked tab stays docked and only slides along its edge.
+ */
+export declare function settleRelease(from: FeedbackSpot, velocity: {
+    x: number;
+    y: number;
+}, view: FeedbackViewport): FeedbackSpot;
+/** Whether the page asked for no feedback icon (`<html data-fs-feedback="off">`). */
+export declare const feedbackOptedOut: (doc?: Document) => boolean;
+export declare function mountFlowFeedback(options: FlowFeedbackOptions): FlowFeedbackHandle | null;
+export declare const unmountFlowFeedback: () => void;
+export {};
+//# sourceMappingURL=feedback.d.ts.map

package/dist/feedback.d.ts.map

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

package/dist/feedback.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=feedback.test.d.ts.map

package/dist/feedback.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.test.d.ts","sourceRoot":"","sources":["../src/feedback.test.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export { initSession, createMockSession, hostOriginOf, readSessionLaunchParams }
 export type { SessionClient, SessionStateView, SessionMember, SessionPhase, SessionGateView, SessionFlowView, SessionClaim, SessionClaimSet, SessionViewer, SessionPollOptions, SessionLaunchParams, MockSessionOptions, } from './session';
 export { getInitialTheme, onThemeChange, applyWidgetTheme, initWidgetTheme } from './theme';
 export type { WidgetTheme } from './theme';
+export { mountFlowFeedback, unmountFlowFeedback, readFlowTheme, feedbackOptedOut, } from './feedback';
+export type { FlowFeedbackTheme, FlowFeedbackReport, FlowFeedbackOptions, FlowFeedbackHandle, } from './feedback';
 export { onArtifactIngested, INGEST_MESSAGE_TYPE } from './ingest';
 export type { IngestedArtifact } from './ingest';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AACrC,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC7F,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EACV,0BAA0B,EAC1B,0BAA0B,EAC1B,mBAAmB,EACnB,QAAQ,EACR,YAAY,EACZ,KAAK,EACL,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAClG,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,eAAe,EACf,eAAe,EACf,YAAY,EACZ,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC5F,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACnE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AACrC,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC7F,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EACV,0BAA0B,EAC1B,0BAA0B,EAC1B,mBAAmB,EACnB,QAAQ,EACR,YAAY,EACZ,KAAK,EACL,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAClG,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,eAAe,EACf,eAAe,EACf,YAAY,EACZ,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC5F,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACnE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC"}