@squeletteapp/widget 0.4.0 → 1.0.0

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

@@ -1,15 +0,0 @@
-/**
- * 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

@@ -1,17 +0,0 @@
-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, base, ticketId, }: {
-    workspaceSlug: string;
-    theme: "light" | "dark";
-    base: string;
-    ticketId?: number;
-}): import("preact").VNode<any> | null;
-export {};

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

@@ -1,17 +0,0 @@
-type SqueletteBannerWidgetProps = {
-    workspaceSlug: string;
-    theme: "light" | "dark";
-    base?: string;
-    debug?: boolean;
-    ticketId?: number;
-};
-export declare function Banner({ workspaceSlug, theme, base, debug, ticketId, }: 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

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

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

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

package/dist/types/banner/use-css-animation.d.ts

@@ -1,37 +0,0 @@
-interface AnimationOptions {
-    duration?: number;
-    easing?: string;
-    delay?: number;
-    onComplete?: () => void;
-}
-/**
- * Hook to apply CSS transform/transition animations
- */
-export declare function useCSSAnimation<T extends HTMLElement>(): {
-    ref: import("preact").RefObject<T>;
-    animate: (styles: Record<string, string>, options?: AnimationOptions) => Promise<void>;
-};
-/**
- * Hook to handle banner drop animation with bounce effect
- */
-export declare function useBannerDrop<T extends HTMLElement>(shouldAnimate: boolean, onComplete?: () => void): import("preact").RefObject<T>;
-/**
- * Hook to handle expand/collapse width animation
- */
-export declare function useExpandAnimation<T extends HTMLElement>(shouldExpand: boolean, targetWidth: number): import("preact").RefObject<T>;
-/**
- * Hook to handle close animation
- */
-export declare function useCloseAnimation<T extends HTMLElement>(): {
-    ref: import("preact").RefObject<T>;
-    close: () => Promise<void>;
-};
-/**
- * Hook for modal fade in/out animations
- */
-export declare function useModalAnimation(isOpen: boolean): {
-    overlayRef: import("preact").RefObject<HTMLDivElement>;
-    contentRef: import("preact").RefObject<HTMLDivElement>;
-    close: () => Promise<void>;
-};
-export {};

package/dist/types/changelog/changelog.d.ts

@@ -1,15 +0,0 @@
-import { h } from "preact";
-interface ChangelogProps {
-    workspaceSlug: string;
-    workspace: string;
-    theme: "light" | "dark";
-    contentTheme: "light" | "dark";
-    base: string;
-    debug?: boolean;
-    onClose: () => void;
-}
-/**
- * Changelog component renders iframe pointing to workspace widget changelog page.
- */
-export declare function Changelog({ workspaceSlug, workspace, theme, contentTheme, base, debug, onClose, }: ChangelogProps): h.JSX.Element;
-export {};

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

@@ -1,86 +0,0 @@
-declare class SqueletteChangelogElement extends HTMLElement {
-    private shadow;
-    private targetElement;
-    private resizeObserver;
-    private scrollListener;
-    private clickListener;
-    private outsideClickListener;
-    private isOpen;
-    private currentAlign;
-    private instanceId;
-    static get observedAttributes(): string[];
-    constructor();
-    connectedCallback(): void;
-    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
-    private renderChangelog;
-    disconnectedCallback(): void;
-    /**
-     * Opens the changelog widget with animation based on position.
-     */
-    private lastToggleTs;
-    open(): void;
-    /**
-     * Toggles the changelog widget open/close state.
-     * Debounced to prevent double firing in the same tick (StrictMode / duplicate listeners).
-     */
-    toggle(): void;
-    /**
-     * Closes the changelog widget with animation.
-     */
-    close(): void;
-    /**
-     * Applies opening animation based on the current align position.
-     */
-    private applyOpenAnimation;
-    /**
-     * Applies closing animation.
-     */
-    private applyCloseAnimation;
-    /**
-     * Sets up click listener on the target element to toggle changelog.
-     * Also sets up element tracking for positioning when element-based.
-     */
-    private setupClickListener;
-    /**
-     * Cleans up click listener.
-     */
-    private cleanupClickListener;
-    /**
-     * Sets up outside click listener to close the widget.
-     */
-    private setupOutsideClickListener;
-    /**
-     * Cleans up outside click listener.
-     */
-    private cleanupOutsideClickListener;
-    /**
-     * Updates the widget position based on alignment.
-     * Screen-based positioning is relative to viewport.
-     * Element-based positioning is relative to the target element.
-     */
-    private updatePosition;
-    /**
-     * Positions the widget relative to the viewport.
-     */
-    private positionRelativeToScreen;
-    /**
-     * Positions the widget relative to a target element.
-     * If position is 'auto', finds the best position based on available viewport space.
-     */
-    private positionRelativeToElement;
-    /**
-     * Calculates the best position for the widget based on available viewport space.
-     * Returns the position with the most available space.
-     */
-    private calculateBestPosition;
-    /**
-     * Sets up ResizeObserver and scroll listener to track element position changes.
-     * Only updates position when widget is open.
-     */
-    private setupElementTracking;
-    /**
-     * Cleans up observers and listeners.
-     */
-    private cleanupTracking;
-}
-export { SqueletteChangelogElement };

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

@@ -1,32 +0,0 @@
-import { SqueletteChangelogElement } from "./element";
-export { SqueletteChangelogElement };
-type ChangelogInitPayload = {
-    workspace: string;
-    contentTheme?: "light" | "dark";
-    theme?: ChangelogTheme;
-    base?: string;
-    debug?: boolean;
-    selector?: string;
-    align?: ChangelogAlign;
-    height?: number | string;
-};
-export type ChangelogTheme = {
-    bg?: string;
-    border?: string;
-};
-/**
- * Alignment format: <anchor>-<position>
- * - anchor: "screen" or "element"
- * - position: "top-left" | "top-center" | "top-right" | "left" | "center" | "right" | "bottom-left" | "bottom-center" | "bottom-right" | "auto"
- * - "auto" is only supported for element-based positioning and will automatically choose the best position
- */
-export type ChangelogAlign = "screen-top-left" | "screen-top-center" | "screen-top-right" | "screen-left" | "screen-center" | "screen-right" | "screen-bottom-left" | "screen-bottom-center" | "screen-bottom-right" | "element-top-left" | "element-top-center" | "element-top-right" | "element-left" | "element-center" | "element-right" | "element-bottom-left" | "element-bottom-center" | "element-bottom-right" | "element-auto";
-export declare const SqueletteChangelog: {
-    init({ workspace, theme, contentTheme, base, debug, selector, align, height, }: ChangelogInitPayload): SqueletteChangelogElement | null;
-    open(): void;
-    close(): void;
-    toggle(): void;
-    setTheme(theme: ChangelogTheme): void;
-    setContentTheme(contentTheme: "light" | "dark"): void;
-    destroy(): void;
-};

package/dist/types/index.d.ts

@@ -1,12 +0,0 @@
-/**
- * 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";
-export * from "./changelog";
-export type { ChangelogTheme, ChangelogAlign } from "./changelog";

package/dist/types/utils.d.ts

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

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

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

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

@@ -1,8 +0,0 @@
-/**
- * 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

@@ -1,9 +0,0 @@
-/**
- * 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

@@ -1,142 +0,0 @@
-/**
- * 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

@@ -1,97 +0,0 @@
-/**
- * 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

@@ -1,73 +0,0 @@
-/**
- * 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

@@ -1,36 +0,0 @@
-/**
- * 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;