@squeletteapp/widget 0.1.0 → 0.3.0

package/dist/types/app/app.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal Preact component responsible for rendering the sandboxed iframe. By
+ * keeping the widget UI in an isolated module we can lazy-load it only when the
+ * launcher opens, keeping the initial footprint tiny.
+ */
+import type { JSX } from "preact";
+export interface WidgetFrameProps {
+    src: string;
+    title: string;
+    onLoaded?: () => void;
+    onClose: () => void;
+}
+export declare function WidgetFrame({ src, title, onLoaded, onClose, }: WidgetFrameProps): JSX.Element;
+export declare const stylesText: string;
+export default WidgetFrame;

package/dist/types/banner/banner-modal.d.ts

@@ -0,0 +1,15 @@
+type Ticket = {
+    title: string;
+    id: number;
+    workspace: {
+        slug: string;
+    };
+    created_at: string;
+};
+export declare const showModal: import("@preact/signals").Signal<boolean>;
+export declare const modalTicket: import("@preact/signals").Signal<Ticket | null>;
+export declare function BannerModal({ workspaceSlug, theme, }: {
+    workspaceSlug: string;
+    theme: "light" | "dark";
+}): import("preact").VNode<any> | null;
+export {};

package/dist/types/banner/banner.d.ts

@@ -0,0 +1,14 @@
+type SqueletteBannerWidgetProps = {
+    workspaceSlug: string;
+    theme: "light" | "dark";
+};
+export declare function Banner({ workspaceSlug, theme, }: SqueletteBannerWidgetProps): import("preact").JSX.Element | null;
+type MarqueeSpanProps = {
+    children: string;
+    duration?: number;
+    gap?: number;
+    className?: string;
+    delay?: number;
+};
+export declare function MarqueeSpan({ children, duration, gap, className, delay, }: MarqueeSpanProps): import("preact").JSX.Element;
+export {};

package/dist/types/banner/element.d.ts

@@ -0,0 +1,7 @@
+declare class SqueletteBannerElement extends HTMLElement {
+    private shadow;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}
+export { SqueletteBannerElement };

package/dist/types/banner/index.d.ts

@@ -0,0 +1,19 @@
+import { SqueletteBannerElement } from "./element";
+export { SqueletteBannerElement };
+type BannerInitPayload = {
+    slug: string;
+    contentTheme?: "light" | "dark";
+    theme?: BannerTheme;
+};
+export type BannerTheme = {
+    bg?: string;
+    border?: string;
+    text?: string;
+    badgeBg?: string;
+    badgeText?: string;
+    buttonHover?: string | number;
+};
+export declare const SqueletteBanner: {
+    init({ slug, theme, contentTheme, }: BannerInitPayload): SqueletteBannerElement | null;
+    setTheme(theme: BannerTheme): void;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Public entry-point that re-exports the custom element and typings. Consumers
+ * importing via ESM or CommonJS land here after bundling.
+ */
+export * from "./widget/element";
+export { type WidgetTheme, type WidgetEventName, type WidgetEventListener, type WidgetEventDetailMap, type WidgetSubmitPayload, type CreateWidgetOptions, type WidgetView, type WidgetIdentityPayload, type WidgetPosition, type WidgetFloatingPosition, type WidgetFixedPosition, } from "./widget/types";
+export { identify, clearIdentity } from "./widget/element";
+export { createWidget, createFeedbackWidget, createRoadmapWidget, createChangelogWidget, } from "./widget/factories";
+export * from "./banner";
+export type { BannerTheme } from "./banner";

package/dist/types/utils.d.ts

@@ -0,0 +1,2 @@
+import { type ClassValue } from "clsx";
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/types/widget/__tests__/widget.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/widget/components/widget-shell.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Presentational shell rendered inside the widget's shadow root. It hosts the
+ * launcher button, overlay, and the lazy-loaded iframe container while keeping
+ * the custom element class free of JSX and rendering concerns.
+ */
+import type { JSX } from "preact";
+import type { WidgetShellProps } from "../types";
+export declare function WidgetShell({ open, label, iframeSrc, FrameComponent, ensureFrame, onOpen, onClose, onFrameLoaded, }: WidgetShellProps): JSX.Element;

package/dist/types/widget/constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Centralised constants that define the public identity of the widget bundle.
+ * These values are relied upon across the element implementation and by the
+ * CDN embed snippet, so keep them in one place to avoid drift.
+ */
+export declare const TAG_NAME = "squelette-widget";
+export declare const API_BASE: string;
+export declare const CDN_BASE = "https://cdn.squelette.app/widget.js";
+export declare const DEFAULT_LABEL = "Feedback";

package/dist/types/widget/core/custom-element.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Custom Element Implementation
+ *
+ * Defines the `<squelette-widget>` custom element that powers the widget system.
+ * This class extends HTMLElement to create a fully-featured web component with:
+ *
+ * **Core Features:**
+ * - Shadow DOM encapsulation for style isolation
+ * - Lazy loading of iframe renderer (loaded only when widget opens)
+ * - Reactive attribute system using observed attributes
+ * - Event emitter for widget lifecycle events (open, close, submit)
+ * - Theme management with auto/light/dark modes
+ * - Internationalization support
+ *
+ * **State Management:**
+ * - Tracks open/closed state
+ * - Manages iframe loading state
+ * - Handles user identity forwarding to iframe
+ * - Coordinates scroll locking when panel is open
+ *
+ * **Communication:**
+ * - PostMessage API for iframe communication
+ * - CustomEvent system for host application integration
+ * - Event emitter pattern for programmatic access
+ *
+ * The element is designed to be used both declaratively (HTML attributes)
+ * and programmatically (JavaScript API), making it flexible for different
+ * integration patterns.
+ *
+ * @example
+ * ```html
+ * <!-- Declarative usage -->
+ * <squelette-widget
+ *   project="my-project"
+ *   board="feedback"
+ *   theme="auto"
+ *   locale="en"
+ * ></squelette-widget>
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Programmatic usage
+ * const widget = document.querySelector('squelette-widget');
+ * await widget.open();
+ * widget.on('submit', (event) => {
+ *   console.log('Feedback submitted:', event.payload);
+ * });
+ * ```
+ */
+import { type WidgetEventListener, type WidgetEventName } from "../types";
+/**
+ * Custom element class for `<squelette-widget>`.
+ *
+ * This is the main widget component that handles all widget functionality
+ * including rendering, state management, event handling, and iframe coordination.
+ */
+export declare class SqueletteWidgetElement extends HTMLElement {
+    #private;
+    /**
+     * Attributes that trigger attributeChangedCallback when modified.
+     */
+    static get observedAttributes(): string[];
+    constructor();
+    /**
+     * Called when element is inserted into the DOM.
+     * Initializes configuration from attributes and sets up event listeners.
+     */
+    connectedCallback(): void;
+    /**
+     * Called when element is removed from the DOM.
+     * Cleans up all event listeners and restores page state.
+     */
+    disconnectedCallback(): void;
+    /**
+     * Called when observed attributes change.
+     * Updates internal configuration and triggers re-render.
+     */
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    /**
+     * Opens the widget panel.
+     * @public
+     */
+    open(): Promise<void>;
+    /**
+     * Closes the widget panel.
+     * @public
+     */
+    close(): Promise<void>;
+    /**
+     * Toggles the widget panel open/closed state.
+     * @public
+     */
+    toggle(): Promise<void>;
+    /**
+     * Registers an event listener for widget events.
+     * @public
+     * @returns Cleanup function to remove the listener
+     */
+    on<K extends WidgetEventName>(event: K, handler: WidgetEventListener<K>): () => void;
+    /**
+     * Destroys the widget and removes it from the DOM.
+     * Cleans up all resources and event listeners.
+     * @public
+     */
+    destroy(): Promise<void>;
+    /**
+     * Renders the widget UI using Preact.
+     * @private
+     */
+    private render;
+    /**
+     * Lazy loads the iframe frame module when needed.
+     * @private
+     */
+    private ensureFrameModule;
+    /**
+     * Called when iframe finishes loading.
+     * @private
+     */
+    private handleFrameLoaded;
+    /**
+     * Updates the open/closed state and manages side effects.
+     * @private
+     */
+    private setOpen;
+    /**
+     * Applies theme and sets up theme change listeners.
+     * @private
+     */
+    private applyTheme;
+    /**
+     * Posts identity payload to iframe via postMessage.
+     * @private
+     */
+    private postIdentityToFrame;
+}
+/**
+ * Registers the custom element if not already registered.
+ * @internal
+ */
+export declare function registerSqueletteWidget(): void;

package/dist/types/widget/core/global-api.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Global API Helper
+ *
+ * Creates and exposes the `window.SqueletteWidget` global API for widget integrations.
+ * This module provides convenient factory functions and utilities that make
+ * it easy to create and configure widgets without using the custom element directly.
+ *
+ * **Available API Methods:**
+ *
+ * 1. `create()` - Flexible widget factory
+ * 2. `createFeedbackWidget()` - Specialized feedback widget factory
+ * 3. `createRoadmapWidget()` - Specialized roadmap widget factory
+ * 4. `createChangelogWidget()` - Specialized changelog widget factory
+ * 5. `identify()` - Set user identity across all widgets
+ * 6. `clearIdentity()` - Clear user identity
+ *
+ * **Specialized Options:**
+ * The specialized factories support advanced positioning options including:
+ * - Button-anchored positioning with collision detection
+ * - Fixed viewport positioning (9 preset positions)
+ * - Overlay blur effects
+ * - Custom event callbacks
+ * - Click-outside-to-close behavior
+ *
+ * This API maintains backward compatibility with existing integrations while
+ * internally using the modern custom element system.
+ *
+ * @example
+ * ```ts
+ * // Modern API
+ * const widget = SqueletteWidget.create({
+ *   project: 'my-project',
+ *   board: 'feedback',
+ *   view: 'feedback'
+ * });
+ *
+ * // Specialized API
+ * const widget = SqueletteWidget.createFeedbackWidget('my-project', 'feedback', {
+ *   buttonSelector: '#feedback-btn',
+ *   position: 'bottom'
+ * });
+ *
+ * // Identity management
+ * SqueletteWidget.identify({
+ *   userId: '123',
+ *   email: 'user@example.com',
+ *   signature: 'hmac-sig'
+ * });
+ * ```
+ */
+import type { CreateWidgetOptions } from "../types";
+import { SqueletteWidgetElement } from "./custom-element";
+import { type PositioningOptions } from "./positioning";
+import { identify as identityIdentify, clearIdentity as identityClearIdentity } from "./identity";
+import { SqueletteBanner } from "../../banner";
+/**
+ * Widget options that extend positioning options.
+ * Omits project/board/view as these are passed separately in some factory APIs.
+ */
+type WidgetFactoryOptions = Omit<CreateWidgetOptions, "project" | "board" | "view"> & PositioningOptions;
+/**
+ * Global API interface exposed on window.SqueletteWidget
+ */
+export interface GlobalSqueletteWidget {
+    /** Modern widget factory */
+    create: (options: CreateWidgetOptions) => SqueletteWidgetElement;
+    /** Specialized feedback widget factory */
+    createFeedbackWidget: (project: string, board?: string | null, options?: WidgetFactoryOptions) => SqueletteWidgetElement;
+    /** Specialized roadmap widget factory */
+    createRoadmapWidget: (project: string, board?: string | null, options?: WidgetFactoryOptions) => SqueletteWidgetElement;
+    /** Specialized changelog widget factory */
+    createChangelogWidget: (project: string, options?: WidgetFactoryOptions) => SqueletteWidgetElement;
+    /** Set user identity */
+    identify: typeof identityIdentify;
+    /** Clear user identity */
+    clearIdentity: typeof identityClearIdentity;
+    /** Banner API */
+    banner: typeof SqueletteBanner;
+    /** Widget version */
+    version: string;
+    /** CDN base URL */
+    cdn: string;
+}
+/**
+ * Initializes and exposes the global SqueletteWidget API.
+ * This function is called once during module initialization.
+ *
+ * If the API already exists (e.g., from a previous script load),
+ * this function does nothing to avoid conflicts.
+ */
+export declare function ensureGlobalHelper(): void;
+declare global {
+    interface Window {
+        SqueletteWidget?: GlobalSqueletteWidget;
+    }
+}
+export {};

package/dist/types/widget/core/identity.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Identity Management Module
+ *
+ * Handles user identification for the widget system. This module provides:
+ * - A global identity store accessible across all widget instances
+ * - Event-based identity updates using CustomEvents
+ * - Type-safe identity payload validation
+ * - Centralized identity state management
+ *
+ * The identity system works by:
+ * 1. Storing identity payload in module-level state
+ * 2. Broadcasting changes via 'squelette:identity' CustomEvent
+ * 3. Widget instances listen to this event and forward to iframes
+ *
+ * This allows multiple widget instances to share the same user identity
+ * without prop drilling or complex state management.
+ *
+ * @example
+ * ```ts
+ * // Set user identity
+ * identify({
+ *   userId: '123',
+ *   email: 'user@example.com',
+ *   signature: 'hmac-signature'
+ * });
+ *
+ * // Clear identity
+ * clearIdentity();
+ * ```
+ */
+import type { WidgetIdentityPayload } from '../types';
+/**
+ * Sets the user identity for all widget instances.
+ *
+ * This function validates the payload and broadcasts the identity
+ * to all active widget instances via a CustomEvent. Each widget
+ * will then forward this information to its iframe.
+ *
+ * @param payload - User identification data including userId, email, and HMAC signature
+ * @throws {Error} Logs an error if payload is invalid (missing required fields)
+ *
+ * @example
+ * ```ts
+ * identify({
+ *   userId: 'user_123',
+ *   email: 'john@example.com',
+ *   signature: 'hmac_abc123',
+ *   name: 'John Doe', // optional
+ *   avatar: 'https://...', // optional
+ * });
+ * ```
+ */
+export declare function identify(payload: WidgetIdentityPayload): void;
+/**
+ * Clears the current user identity for all widget instances.
+ *
+ * This removes the stored identity and notifies all widgets
+ * to clear their identity state, typically used on logout.
+ *
+ * @example
+ * ```ts
+ * // On user logout
+ * clearIdentity();
+ * ```
+ */
+export declare function clearIdentity(): void;
+/**
+ * Gets the current identity payload.
+ *
+ * @internal This is used internally by widget instances
+ * @returns The current identity payload, or null if no user is identified
+ */
+export declare function getIdentityPayload(): WidgetIdentityPayload | null;

package/dist/types/widget/core/panel-dimensions.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Panel Dimensions Configuration
+ *
+ * Defines the default dimensions for different widget views (feedback, roadmap, changelog).
+ * Each view has optimized width and height values based on its content requirements:
+ *
+ * - Feedback: Compact form for quick feedback submission
+ * - Roadmap: Medium height for displaying planned features
+ * - Changelog: Taller panel for scrolling through updates
+ *
+ * These dimensions are applied as CSS custom properties (--sq-panel-width, --sq-panel-height)
+ * to the custom element, allowing the widget to adapt its size based on the active view.
+ */
+import type { WidgetView } from "../types";
+/**
+ * Default dimensions for each widget view type.
+ * Values are in pixels and represent the ideal size for each view's content.
+ */
+export declare const PANEL_DIMENSIONS: Record<WidgetView, {
+    width: number;
+    height: number;
+}>;
+/**
+ * Fallback dimensions when view type is unknown or not specified.
+ */
+export declare const DEFAULT_PANEL_DIMENSIONS: {
+    width: number;
+    height: number;
+};
+/**
+ * Applies panel dimensions to the widget element as CSS custom properties.
+ *
+ * @param element - The widget element to apply dimensions to
+ * @param view - The widget view type (feedback, roadmap, or changelog)
+ */
+export declare function applyPanelDimensions(element: HTMLElement, view: WidgetView): void;

package/dist/types/widget/core/positioning.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Widget Positioning System
+ *
+ * Handles advanced positioning logic for the widget.
+ * This module supports two positioning modes:
+ *
+ * 1. **Button-anchored positioning**: Widget appears relative to a trigger button
+ *    - Dynamically calculates optimal placement (top/bottom/left/right)
+ *    - Automatically repositions on scroll/resize
+ *    - Ensures widget stays within viewport bounds
+ *    - Supports collision detection and smart fallback positioning
+ *
+ * 2. **Fixed positioning**: Widget appears at a fixed viewport location
+ *    - Supports 9 preset positions (fixed-top-left, fixed-center-center, etc.)
+ *    - Maintains position regardless of page scroll
+ *    - Respects viewport margins and responsive layouts
+ *
+ * This module also handles:
+ * - Click-outside detection to close the widget
+ * - Overlay blur effects
+ * - Custom button selector binding
+ * - Lifecycle cleanup for event listeners
+ *
+ * @example
+ * ```ts
+ * const cleanup = applyPositioning(element, {
+ *   buttonSelector: '#feedback-button',
+ *   position: 'bottom',
+ *   overlayBlur: true
+ * });
+ *
+ * // Later: cleanup all event listeners
+ * cleanup();
+ * ```
+ */
+import type { SqueletteWidgetElement } from "./custom-element";
+import type { WidgetPosition } from "../types";
+/**
+ * Widget positioning and binding options.
+ */
+export interface PositioningOptions {
+    /** CSS selector for the button that triggers the widget */
+    buttonSelector?: string;
+    /** Preferred position relative to button or fixed viewport position */
+    position?: WidgetPosition;
+    /** Whether to apply blur effect to the overlay backdrop */
+    overlayBlur?: boolean;
+    /** Callback when widget open state changes */
+    onOpenChange?: (open: boolean) => void;
+    /** Callback when widget iframe finishes loading */
+    onLoad?: () => void;
+}
+/**
+ * Applies positioning and event bindings to a widget element.
+ *
+ * This function sets up all the positioning logic, event listeners, and
+ * custom behaviors needed for the widget.
+ *
+ * @param element - The widget element to enhance
+ * @param options - Positioning and behavior options
+ * @returns Array of cleanup functions to remove all applied behaviors
+ */
+export declare function applyPositioning(element: SqueletteWidgetElement, options: PositioningOptions): Array<() => void>;

package/dist/types/widget/core/scroll-lock.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Body Scroll Lock Utility
+ *
+ * Manages the locking and unlocking of body scroll when the widget panel is open.
+ * This prevents the underlying page from scrolling while the user interacts with
+ * the widget overlay.
+ *
+ * Key behaviors:
+ * - Locks body scroll by setting `overflow: hidden`
+ * - Calculates and compensates for scrollbar width to prevent layout shift
+ * - Returns a cleanup function to restore original scroll state
+ * - Preserves original overflow and padding-right values
+ *
+ * @example
+ * ```ts
+ * const restoreScroll = toggleBodyScroll(true);
+ * // ... widget is open, body cannot scroll
+ * restoreScroll(); // restore original scroll behavior
+ * ```
+ */
+/**
+ * Toggles body scroll lock and compensates for scrollbar width
+ * to prevent layout shift.
+ *
+ * @param lock - Whether to lock (true) or unlock (false) body scroll
+ * @returns A cleanup function that restores the original scroll state
+ */
+export declare function toggleBodyScroll(lock: boolean): () => void;

package/dist/types/widget/element.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Widget Element Module
+ *
+ * This is the main entry point for the widget's custom element implementation.
+ * It has been refactored into smaller, focused modules for better maintainability:
+ *
+ * **Module Structure:**
+ *
+ * - `core/custom-element.ts` - The `<squelette-widget>` custom element class
+ *   - Handles Shadow DOM, lifecycle methods, attribute observation
+ *   - Manages widget state (open/closed, loading, theme)
+ *   - Coordinates iframe loading and communication
+ *
+ * - `core/identity.ts` - User identity management
+ *   - Global identity store for all widget instances
+ *   - `identify()` and `clearIdentity()` functions
+ *   - Event-based identity synchronization
+ *
+ * - `core/scroll-lock.ts` - Body scroll management
+ *   - Locks page scroll when widget is open
+ *   - Compensates for scrollbar width to prevent layout shift
+ *
+ * - `core/panel-dimensions.ts` - Widget panel dimensions
+ *   - Default dimensions for each view type (feedback, roadmap, changelog)
+ *   - CSS custom property application
+ *
+ * - `core/positioning.ts` - Advanced positioning system
+ *   - Button-anchored positioning with collision detection
+ *   - Fixed viewport positioning (9 preset positions)
+ *   - Click-outside-to-close behavior
+ *   - Responsive viewport tracking
+ *
+ * - `core/global-api.ts` - Global `window.SqueletteWidget` API
+ *   - Factory functions for creating widgets
+ *   - Convenient JavaScript API layer
+ *   - Version and CDN information
+ *
+ * **Usage:**
+ *
+ * Declarative (HTML):
+ * ```html
+ * <squelette-widget
+ *   project="my-project"
+ *   board="feedback"
+ *   theme="auto"
+ *   locale="en"
+ * ></squelette-widget>
+ * ```
+ *
+ * Programmatic (JavaScript):
+ * ```js
+ * const widget = SqueletteWidget.create({
+ *   project: 'my-project',
+ *   board: 'feedback',
+ *   view: 'feedback'
+ * });
+ *
+ * await widget.open();
+ * widget.on('submit', (e) => console.log(e.payload));
+ * ```
+ *
+ * Alternative API:
+ * ```js
+ * const widget = SqueletteWidget.createFeedbackWidget('my-project', 'feedback', {
+ *   buttonSelector: '#feedback-button',
+ *   position: 'bottom',
+ *   overlayBlur: true
+ * });
+ * ```
+ *
+ * Identity Management:
+ * ```js
+ * SqueletteWidget.identify({
+ *   userId: '123',
+ *   email: 'user@example.com',
+ *   signature: 'hmac-signature',
+ *   name: 'John Doe' // optional
+ * });
+ *
+ * SqueletteWidget.clearIdentity(); // on logout
+ * ```
+ */
+export { SqueletteWidgetElement, registerSqueletteWidget, } from "./core/custom-element";
+export { identify, clearIdentity } from "./core/identity";
+export { ensureGlobalHelper, type GlobalSqueletteWidget, } from "./core/global-api";
+declare global {
+    interface HTMLElementTagNameMap {
+        "squelette-widget": import("./core/custom-element").SqueletteWidgetElement;
+    }
+}

package/dist/types/widget/events.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lightweight event emitter dedicated to the widget element. It keeps
+ * allocation pressure low while offering an ergonomic `.on()` API for clients
+ * embedding the widget and for internal coordination between the shell and the
+ * custom element lifecycle.
+ */
+import type { WidgetEventListener, WidgetEventName, WidgetEventDetailMap } from './types';
+export declare class WidgetEventEmitter {
+    private listeners;
+    on<K extends WidgetEventName>(event: K, handler: WidgetEventListener<K>): () => void;
+    off<K extends WidgetEventName>(event: K, handler: WidgetEventListener<K>): void;
+    emit<K extends WidgetEventName>(event: K, payload: WidgetEventDetailMap[K]): void;
+}