@fiddle-digital/string-tune 1.1.52 → 1.1.54

package/dist/index.d.mts

@@ -524,6 +524,9 @@ declare class StringObject {
      * modules it is associated with.
      */
     remove(): void;
+    setInviewAutoBlocked(blocked: boolean): void;
+    isInviewAutoBlocked(): boolean;
+    syncInviewClass(): void;
     /**
      * Shows the object, applies visual class and notifies connected modules.
      */
@@ -1341,6 +1344,9 @@ declare class StringModule implements IStringModule {
      * 6. Sets the processed attributes as properties on the `StringObject` instance.
      */
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
+    protected cacheLayoutSnapshot(object: StringObject, element: HTMLElement): void;
+    private getOffsetSize;
+    private getOffsetChainPosition;
     /**
      * Calculates object-specific positions or metrics based on the current layout or scroll state.
      * This method is intended to be overridden in subclasses if the module needs to precompute
@@ -1960,6 +1966,7 @@ declare class StringProgress extends StringModule {
     constructor(context: StringContext);
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
     private sanitizeRawProgress;
+    private resolveRawProgress;
     private applyRawProgress;
     private recomputeProgress;
     private ensureBatchCapacity;
@@ -2029,6 +2036,7 @@ declare class StringScrollbar extends StringModule {
  */
 declare class StringSplit extends StringModule {
     constructor(context: StringContext);
+    onInit(): void;
     onResizeWidth(): void;
     onObjectConnected(object: StringObject): void;
     split(element: HTMLElement, options: ISplitOptions): {
@@ -2670,6 +2678,138 @@ declare class ScrollController {
     scrollTo(position: number, immediate?: boolean): void;
 }
 
+/**
+ * Discriminated union of all UI field descriptors.
+ * Each devtool module returns an array of these to describe its settings panel.
+ */
+type StringDevUIFieldDescriptor = StringDevUIFieldNumber | StringDevUIFieldRange | StringDevUIFieldColor | StringDevUIFieldSelect | StringDevUIFieldToggle | StringDevUIFieldDivider;
+interface StringDevUIFieldNumber {
+    readonly type: "number";
+    readonly key: string;
+    readonly label: string;
+    readonly default: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+}
+interface StringDevUIFieldRange {
+    readonly type: "range";
+    readonly key: string;
+    readonly label: string;
+    readonly default: number;
+    readonly min: number;
+    readonly max: number;
+    readonly step?: number;
+    /** When provided, a compact unit dropdown is shown next to the value input. */
+    readonly units?: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+    /** Default unit value (used when no persisted unit exists). */
+    readonly defaultUnit?: string;
+}
+interface StringDevUIFieldColor {
+    readonly type: "color";
+    readonly key: string;
+    readonly label: string;
+    readonly default: string;
+}
+interface StringDevUIFieldSelect {
+    readonly type: "select";
+    readonly key: string;
+    readonly label: string;
+    readonly default: string;
+    readonly options: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+}
+interface StringDevUIFieldToggle {
+    readonly type: "toggle";
+    readonly key: string;
+    readonly label: string;
+    readonly default: boolean;
+}
+interface StringDevUIFieldDivider {
+    readonly type: "divider";
+    readonly label?: string;
+}
+
+/**
+ * Abstract base class for all grid adapters.
+ *
+ * Each adapter is a self-contained unit that:
+ * - Declares its own default settings
+ * - Describes its UI schema for the settings panel
+ * - Renders itself into an SVG overlay
+ *
+ * To create a new grid type, extend this class and implement
+ * all abstract members. The system handles everything else.
+ */
+declare abstract class GridAdapter {
+    /** Unique type key used for serialization and registry lookup */
+    abstract readonly type: string;
+    /** Human-readable label shown in the HUD menu */
+    abstract readonly label: string;
+    /** SVG icon string (inline SVG markup) */
+    abstract readonly icon: string;
+    /**
+     * Returns the default settings for this adapter.
+     * These are used when a new grid instance is created.
+     */
+    abstract getDefaults(): Record<string, any>;
+    /**
+     * Returns the UI field descriptors that GridUIBuilder
+     * uses to construct the settings panel.
+     */
+    abstract getUISchema(): StringDevUIFieldDescriptor[];
+    /**
+     * Renders the grid into the given SVG element.
+     *
+     * @param svg    The SVG overlay element (same size as target)
+     * @param width  Element width in px
+     * @param height Element height in px
+     * @param settings  Current settings for this instance
+     */
+    abstract render(svg: SVGSVGElement, width: number, height: number, settings: Record<string, any>): void;
+    /**
+     * Removes all elements previously rendered by this adapter.
+     * Default implementation clears the adapter's group element.
+     */
+    clear(svg: SVGSVGElement, instanceId: string): void;
+    /**
+     * Creates or retrieves a <g> group element scoped to a grid instance.
+     * All rendering should happen inside this group for clean cleanup.
+     */
+    protected getGroup(svg: SVGSVGElement, instanceId: string): SVGGElement;
+    /**
+     * Helper: creates an SVG line element.
+     */
+    protected createLine(x1: number, y1: number, x2: number, y2: number, color: string, opacity: number, strokeWidth?: number): SVGLineElement;
+    /**
+     * Helper: creates an SVG rect element.
+     */
+    protected createRect(x: number, y: number, width: number, height: number, fill: string, opacity: number): SVGRectElement;
+    /**
+     * Converts a value from the given unit to pixels.
+     *
+     * @param value     Raw numeric value
+     * @param unit      "px" | "%" | "vw" | "vh" | "em" | "rem"
+     * @param dimension Reference dimension (element width or height) for "%" mode
+     */
+    protected resolveUnit(value: number, unit: string, dimension: number, referenceElement?: Element | null): number;
+    /**
+     * Helper: creates an SVG path element.
+     */
+    protected createPath(d: string, stroke: string, opacity: number, strokeWidth?: number, fill?: string): SVGPathElement;
+}
+
+declare function resolveDevtoolsIcon(iconOrId: string): string;
+
+type StringDevStyleTokens = Record<string, string>;
+declare function buildDevtoolsThemeBlock(selectors: string | string[], overrides?: StringDevStyleTokens): string;
+declare function ensureStringDevtoolsSharedStyles(): HTMLStyleElement | null;
+
 /**
  * What the trigger does when activated.
  * Defaults to "toggle" when not specified.
@@ -2771,6 +2911,22 @@ interface RowsLayoutGrid {
 }
 type RulersLayoutGrid = ColumnsLayoutGrid | RowsLayoutGrid;
 
+interface StringDevtoolState {
+    active: boolean;
+}
+interface StringDevtoolDefinition {
+    id: string;
+    label: string;
+    icon: string;
+    order?: number;
+    getState: () => StringDevtoolState;
+    setActive: (active: boolean) => void;
+    subscribe?: (listener: (state: StringDevtoolState) => void) => () => void;
+}
+interface StringDevtoolProvider {
+    getDevtoolDefinition(): StringDevtoolDefinition | null;
+}
+
 interface ModuleBatchContext {
     module: StringModule;
     object: StringObject;
@@ -2859,6 +3015,9 @@ declare class StringTune {
     private centers;
     /** Tracks hover states of string objects. */
     private hoverManager;
+    private devtools;
+    private devtoolsFpsLastSampleTime;
+    private devtoolsFpsFrameCount;
     private observerContainerResize;
     canRebuild: boolean;
     /**
@@ -3056,6 +3215,7 @@ declare class StringTune {
      * Triggers scroll engine, modules, and global `update` event.
      */
     private onUpdateEvent;
+    private updateDevtoolsFPS;
     /**
      * Handles resize events from scroll container or window.
      * Ignores height-only changes on mobile to prevent layout jumps.
@@ -3063,11 +3223,25 @@ declare class StringTune {
      */
     onResize(force?: boolean): void;
     invalidateCenter(id: string): void;
-    scrollTo(value: number | {
+    scrollTo(position: number): void;
+    scrollTo(selector: string): void;
+    scrollTo(element: HTMLElement): void;
+    scrollTo(options: {
         position: number;
         immediate?: boolean;
+        offset?: number;
+    } | {
+        selector: string;
+        immediate?: boolean;
+        offset?: number;
+    } | {
+        element: HTMLElement;
+        immediate?: boolean;
+        offset?: number;
     }): void;
+    private resolveScrollToValue;
+    private resolveElementScrollPosition;
     destroy(): void;
 }
 
-export { CursorReactiveModule, DOMBatcher, type RulersLayoutGrid, type RulersTriggerAction, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringMasonry, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringRandom, StringResponsive, type StringRulersTrigger, StringScrollContainer, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, StringTune as default, frameDOM, styleTxn };
+export { CursorReactiveModule, DOMBatcher, GridAdapter, type RulersLayoutGrid, type RulersTriggerAction, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, type StringDevStyleTokens, type StringDevtoolDefinition, type StringDevtoolProvider, type StringDevtoolState, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringMasonry, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringRandom, StringResponsive, type StringRulersTrigger, StringScrollContainer, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, buildDevtoolsThemeBlock, StringTune as default, ensureStringDevtoolsSharedStyles, frameDOM, resolveDevtoolsIcon, styleTxn };

package/dist/index.d.ts

@@ -524,6 +524,9 @@ declare class StringObject {
      * modules it is associated with.
      */
     remove(): void;
+    setInviewAutoBlocked(blocked: boolean): void;
+    isInviewAutoBlocked(): boolean;
+    syncInviewClass(): void;
     /**
      * Shows the object, applies visual class and notifies connected modules.
      */
@@ -1341,6 +1344,9 @@ declare class StringModule implements IStringModule {
      * 6. Sets the processed attributes as properties on the `StringObject` instance.
      */
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
+    protected cacheLayoutSnapshot(object: StringObject, element: HTMLElement): void;
+    private getOffsetSize;
+    private getOffsetChainPosition;
     /**
      * Calculates object-specific positions or metrics based on the current layout or scroll state.
      * This method is intended to be overridden in subclasses if the module needs to precompute
@@ -1960,6 +1966,7 @@ declare class StringProgress extends StringModule {
     constructor(context: StringContext);
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
     private sanitizeRawProgress;
+    private resolveRawProgress;
     private applyRawProgress;
     private recomputeProgress;
     private ensureBatchCapacity;
@@ -2029,6 +2036,7 @@ declare class StringScrollbar extends StringModule {
  */
 declare class StringSplit extends StringModule {
     constructor(context: StringContext);
+    onInit(): void;
     onResizeWidth(): void;
     onObjectConnected(object: StringObject): void;
     split(element: HTMLElement, options: ISplitOptions): {
@@ -2670,6 +2678,138 @@ declare class ScrollController {
     scrollTo(position: number, immediate?: boolean): void;
 }
 
+/**
+ * Discriminated union of all UI field descriptors.
+ * Each devtool module returns an array of these to describe its settings panel.
+ */
+type StringDevUIFieldDescriptor = StringDevUIFieldNumber | StringDevUIFieldRange | StringDevUIFieldColor | StringDevUIFieldSelect | StringDevUIFieldToggle | StringDevUIFieldDivider;
+interface StringDevUIFieldNumber {
+    readonly type: "number";
+    readonly key: string;
+    readonly label: string;
+    readonly default: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+}
+interface StringDevUIFieldRange {
+    readonly type: "range";
+    readonly key: string;
+    readonly label: string;
+    readonly default: number;
+    readonly min: number;
+    readonly max: number;
+    readonly step?: number;
+    /** When provided, a compact unit dropdown is shown next to the value input. */
+    readonly units?: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+    /** Default unit value (used when no persisted unit exists). */
+    readonly defaultUnit?: string;
+}
+interface StringDevUIFieldColor {
+    readonly type: "color";
+    readonly key: string;
+    readonly label: string;
+    readonly default: string;
+}
+interface StringDevUIFieldSelect {
+    readonly type: "select";
+    readonly key: string;
+    readonly label: string;
+    readonly default: string;
+    readonly options: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+}
+interface StringDevUIFieldToggle {
+    readonly type: "toggle";
+    readonly key: string;
+    readonly label: string;
+    readonly default: boolean;
+}
+interface StringDevUIFieldDivider {
+    readonly type: "divider";
+    readonly label?: string;
+}
+
+/**
+ * Abstract base class for all grid adapters.
+ *
+ * Each adapter is a self-contained unit that:
+ * - Declares its own default settings
+ * - Describes its UI schema for the settings panel
+ * - Renders itself into an SVG overlay
+ *
+ * To create a new grid type, extend this class and implement
+ * all abstract members. The system handles everything else.
+ */
+declare abstract class GridAdapter {
+    /** Unique type key used for serialization and registry lookup */
+    abstract readonly type: string;
+    /** Human-readable label shown in the HUD menu */
+    abstract readonly label: string;
+    /** SVG icon string (inline SVG markup) */
+    abstract readonly icon: string;
+    /**
+     * Returns the default settings for this adapter.
+     * These are used when a new grid instance is created.
+     */
+    abstract getDefaults(): Record<string, any>;
+    /**
+     * Returns the UI field descriptors that GridUIBuilder
+     * uses to construct the settings panel.
+     */
+    abstract getUISchema(): StringDevUIFieldDescriptor[];
+    /**
+     * Renders the grid into the given SVG element.
+     *
+     * @param svg    The SVG overlay element (same size as target)
+     * @param width  Element width in px
+     * @param height Element height in px
+     * @param settings  Current settings for this instance
+     */
+    abstract render(svg: SVGSVGElement, width: number, height: number, settings: Record<string, any>): void;
+    /**
+     * Removes all elements previously rendered by this adapter.
+     * Default implementation clears the adapter's group element.
+     */
+    clear(svg: SVGSVGElement, instanceId: string): void;
+    /**
+     * Creates or retrieves a <g> group element scoped to a grid instance.
+     * All rendering should happen inside this group for clean cleanup.
+     */
+    protected getGroup(svg: SVGSVGElement, instanceId: string): SVGGElement;
+    /**
+     * Helper: creates an SVG line element.
+     */
+    protected createLine(x1: number, y1: number, x2: number, y2: number, color: string, opacity: number, strokeWidth?: number): SVGLineElement;
+    /**
+     * Helper: creates an SVG rect element.
+     */
+    protected createRect(x: number, y: number, width: number, height: number, fill: string, opacity: number): SVGRectElement;
+    /**
+     * Converts a value from the given unit to pixels.
+     *
+     * @param value     Raw numeric value
+     * @param unit      "px" | "%" | "vw" | "vh" | "em" | "rem"
+     * @param dimension Reference dimension (element width or height) for "%" mode
+     */
+    protected resolveUnit(value: number, unit: string, dimension: number, referenceElement?: Element | null): number;
+    /**
+     * Helper: creates an SVG path element.
+     */
+    protected createPath(d: string, stroke: string, opacity: number, strokeWidth?: number, fill?: string): SVGPathElement;
+}
+
+declare function resolveDevtoolsIcon(iconOrId: string): string;
+
+type StringDevStyleTokens = Record<string, string>;
+declare function buildDevtoolsThemeBlock(selectors: string | string[], overrides?: StringDevStyleTokens): string;
+declare function ensureStringDevtoolsSharedStyles(): HTMLStyleElement | null;
+
 /**
  * What the trigger does when activated.
  * Defaults to "toggle" when not specified.
@@ -2771,6 +2911,22 @@ interface RowsLayoutGrid {
 }
 type RulersLayoutGrid = ColumnsLayoutGrid | RowsLayoutGrid;
 
+interface StringDevtoolState {
+    active: boolean;
+}
+interface StringDevtoolDefinition {
+    id: string;
+    label: string;
+    icon: string;
+    order?: number;
+    getState: () => StringDevtoolState;
+    setActive: (active: boolean) => void;
+    subscribe?: (listener: (state: StringDevtoolState) => void) => () => void;
+}
+interface StringDevtoolProvider {
+    getDevtoolDefinition(): StringDevtoolDefinition | null;
+}
+
 interface ModuleBatchContext {
     module: StringModule;
     object: StringObject;
@@ -2859,6 +3015,9 @@ declare class StringTune {
     private centers;
     /** Tracks hover states of string objects. */
     private hoverManager;
+    private devtools;
+    private devtoolsFpsLastSampleTime;
+    private devtoolsFpsFrameCount;
     private observerContainerResize;
     canRebuild: boolean;
     /**
@@ -3056,6 +3215,7 @@ declare class StringTune {
      * Triggers scroll engine, modules, and global `update` event.
      */
     private onUpdateEvent;
+    private updateDevtoolsFPS;
     /**
      * Handles resize events from scroll container or window.
      * Ignores height-only changes on mobile to prevent layout jumps.
@@ -3063,11 +3223,25 @@ declare class StringTune {
      */
     onResize(force?: boolean): void;
     invalidateCenter(id: string): void;
-    scrollTo(value: number | {
+    scrollTo(position: number): void;
+    scrollTo(selector: string): void;
+    scrollTo(element: HTMLElement): void;
+    scrollTo(options: {
         position: number;
         immediate?: boolean;
+        offset?: number;
+    } | {
+        selector: string;
+        immediate?: boolean;
+        offset?: number;
+    } | {
+        element: HTMLElement;
+        immediate?: boolean;
+        offset?: number;
     }): void;
+    private resolveScrollToValue;
+    private resolveElementScrollPosition;
     destroy(): void;
 }
 
-export { CursorReactiveModule, DOMBatcher, type RulersLayoutGrid, type RulersTriggerAction, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringMasonry, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringRandom, StringResponsive, type StringRulersTrigger, StringScrollContainer, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, StringTune as default, frameDOM, styleTxn };
+export { CursorReactiveModule, DOMBatcher, GridAdapter, type RulersLayoutGrid, type RulersTriggerAction, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, type StringDevStyleTokens, type StringDevtoolDefinition, type StringDevtoolProvider, type StringDevtoolState, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringMasonry, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringRandom, StringResponsive, type StringRulersTrigger, StringScrollContainer, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, buildDevtoolsThemeBlock, StringTune as default, ensureStringDevtoolsSharedStyles, frameDOM, resolveDevtoolsIcon, styleTxn };