@fiddle-digital/string-tune 1.1.51-alpha.0 → 1.1.52

package/dist/index.d.mts

@@ -1058,7 +1058,7 @@ interface ISplitOptionItem {
  * Holds arrays of option definitions for each split type.
  */
 interface ISplitOptions {
-    fit?: ISplitOptionItem[];
+    fit?: boolean;
     line?: ISplitOptionItem[];
     word?: ISplitOptionItem[];
     char?: ISplitOptionItem[];
@@ -1737,6 +1737,7 @@ declare class StringCursor extends StringModule {
     private getFrameAdjustedLerp;
     private getObjectDimensions;
     private calculateOffset;
+    private reverseOffset;
     removeObject(id: string): void;
     destroy(): void;
 }
@@ -2670,167 +2671,105 @@ declare class ScrollController {
 }
 
 /**
- * StringGrid — developer utility module for layout grid overlays.
- *
- * Usage:
- *   <div string="grid">...</div>
- *
- * No configuration attributes needed. All configuration happens
- * through the interactive HUD panel (hover top-right corner).
+ * What the trigger does when activated.
+ * Defaults to "toggle" when not specified.
+ */
+type RulersTriggerAction = "toggle" | "show" | "hide";
+/**
+ * Keyboard shortcut trigger.
  *
- * Supports multiple grid types via the adapter pattern:
- * - Columns, Rows, Center
- * - Rule of Thirds, Phi Grid, Golden Rectangle, Harmonic Armature
- * - Extensible via `st.use(StringGrid, { adapters: [MyAdapter] })`
- */
-declare class StringGrid extends StringModule {
-    private gridManager;
-    private overlays;
-    private huds;
-    private elementMap;
-    constructor(context: StringContext);
-    onInit(): void;
-    onObjectConnected(object: StringObject): void;
-    onObjectDisconnected(object: StringObject): void;
-    onResize(): void;
-    destroy(): void;
-    private handleAdd;
-    private handleRemove;
-    private handleToggle;
-    private handleSettingChange;
-    private renderElement;
-    private refreshHUD;
-    private destroyElement;
-    private registerBuiltInAdapters;
-    private registerExternalAdapters;
-    private injectStyles;
-}
-
-/**
- * Discriminated union of all UI field descriptors.
- * Each adapter returns an array of these to describe its settings panel.
- */
-type UIFieldDescriptor = UIFieldNumber | UIFieldRange | UIFieldColor | UIFieldSelect | UIFieldToggle | UIFieldDivider;
-interface UIFieldNumber {
-    readonly type: "number";
-    readonly key: string;
-    readonly label: string;
-    readonly default: number;
-    readonly min?: number;
-    readonly max?: number;
-    readonly step?: number;
-}
-interface UIFieldRange {
-    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 UIFieldColor {
-    readonly type: "color";
-    readonly key: string;
-    readonly label: string;
-    readonly default: string;
-}
-interface UIFieldSelect {
-    readonly type: "select";
-    readonly key: string;
-    readonly label: string;
-    readonly default: string;
-    readonly options: ReadonlyArray<{
-        value: string;
-        label: string;
-    }>;
+ * @example
+ *   { type: "keyboard", key: "R", shiftKey: true }
+ */
+interface KeyboardRulersTrigger {
+    type: "keyboard";
+    /** The KeyboardEvent.key value (case-sensitive, e.g. "R", "g", "F2"). */
+    key: string;
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+    action?: RulersTriggerAction;
 }
-interface UIFieldToggle {
-    readonly type: "toggle";
-    readonly key: string;
-    readonly label: string;
-    readonly default: boolean;
+/**
+ * DOM element trigger — binds to one or more elements matching a CSS selector.
+ * The element(s) must exist in the DOM when the module subscribes (at `start()` time).
+ * For dynamically-added controls, prefer `type: "event"` instead.
+ *
+ * @example
+ *   { type: "element", selector: "#rulers-toggle-btn" }
+ *   { type: "element", selector: ".dev-toolbar [data-action='rulers']", event: "pointerdown" }
+ */
+interface ElementRulersTrigger {
+    type: "element";
+    /** CSS selector. All matching elements are bound. */
+    selector: string;
+    /** DOM event type. Defaults to "click". */
+    event?: string;
+    action?: RulersTriggerAction;
 }
-interface UIFieldDivider {
-    readonly type: "divider";
-    readonly label?: string;
+/**
+ * StringTune event-bus trigger — reacts to a named event emitted via the event manager.
+ * Useful for toolbar integrations, programmatic control, and cross-module communication.
+ *
+ * @example
+ *   { type: "event", name: "dev:rulers:toggle" }
+ *
+ * Activate via:
+ *   stringTune.emit("dev:rulers:toggle", null)
+ */
+interface EventRulersTrigger {
+    type: "event";
+    /** Event name on the StringTune event bus. */
+    name: string;
+    action?: RulersTriggerAction;
 }
+/**
+ * Discriminated union of all supported ruler trigger descriptors.
+ */
+type StringRulersTrigger = KeyboardRulersTrigger | ElementRulersTrigger | EventRulersTrigger;
 
 /**
- * Abstract base class for all grid adapters.
+ * Column-based layout grid.
+ *
+ * Displays a fixed set of equally-spaced column bands across the viewport.
+ * Column width is derived from the viewport width, margins, count, and gap.
+ *
+ * @example
+ *   { type: "columns", count: 12, marginLeft: 40, marginRight: 40, gap: 20 }
+ */
+interface ColumnsLayoutGrid {
+    type: "columns";
+    /** Number of columns. */
+    count: number;
+    /** Space reserved on the left edge of the viewport (px). Default: 0. */
+    marginLeft?: number;
+    /** Space reserved on the right edge of the viewport (px). Default: 0. */
+    marginRight?: number;
+    /** Gutter between columns (px). Default: 0. */
+    gap?: number;
+    /** Fill color for column bands. Default: "rgba(255, 0, 80, 0.08)". */
+    color?: string;
+}
+/**
+ * Row-based layout grid.
  *
- * 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
+ * Displays repeating horizontal stripes across the full document height.
+ * Stripes scroll with the page content.
  *
- * To create a new grid type, extend this class and implement
- * all abstract members. The system handles everything else.
+ * @example
+ *   { type: "rows", height: 8, gap: 0 }
  */
-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(): UIFieldDescriptor[];
-    /**
-     * 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"
-     * @param dimension Reference dimension (element width or height) for "%" mode
-     */
-    protected resolveUnit(value: number, unit: string, dimension: number): number;
-    /**
-     * Helper: creates an SVG path element.
-     */
-    protected createPath(d: string, stroke: string, opacity: number, strokeWidth?: number, fill?: string): SVGPathElement;
+interface RowsLayoutGrid {
+    type: "rows";
+    /** Height of each row band (px). */
+    height: number;
+    /** Gap between row bands (px). Default: 0. */
+    gap?: number;
+    /** Fill color for row bands. Default: "rgba(0, 120, 255, 0.06)". */
+    color?: string;
 }
+type RulersLayoutGrid = ColumnsLayoutGrid | RowsLayoutGrid;
 
 interface ModuleBatchContext {
     module: StringModule;
@@ -3131,4 +3070,4 @@ declare class StringTune {
     destroy(): void;
 }
 
-export { CursorReactiveModule, DOMBatcher, GridAdapter, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringForm, StringGlide, StringGrid, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringMasonry, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringRandom, StringResponsive, StringScrollContainer, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, StringTune as default, frameDOM, styleTxn };
+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 };

package/dist/index.d.ts

@@ -1058,7 +1058,7 @@ interface ISplitOptionItem {
  * Holds arrays of option definitions for each split type.
  */
 interface ISplitOptions {
-    fit?: ISplitOptionItem[];
+    fit?: boolean;
     line?: ISplitOptionItem[];
     word?: ISplitOptionItem[];
     char?: ISplitOptionItem[];
@@ -1737,6 +1737,7 @@ declare class StringCursor extends StringModule {
     private getFrameAdjustedLerp;
     private getObjectDimensions;
     private calculateOffset;
+    private reverseOffset;
     removeObject(id: string): void;
     destroy(): void;
 }
@@ -2670,167 +2671,105 @@ declare class ScrollController {
 }
 
 /**
- * StringGrid — developer utility module for layout grid overlays.
- *
- * Usage:
- *   <div string="grid">...</div>
- *
- * No configuration attributes needed. All configuration happens
- * through the interactive HUD panel (hover top-right corner).
+ * What the trigger does when activated.
+ * Defaults to "toggle" when not specified.
+ */
+type RulersTriggerAction = "toggle" | "show" | "hide";
+/**
+ * Keyboard shortcut trigger.
  *
- * Supports multiple grid types via the adapter pattern:
- * - Columns, Rows, Center
- * - Rule of Thirds, Phi Grid, Golden Rectangle, Harmonic Armature
- * - Extensible via `st.use(StringGrid, { adapters: [MyAdapter] })`
- */
-declare class StringGrid extends StringModule {
-    private gridManager;
-    private overlays;
-    private huds;
-    private elementMap;
-    constructor(context: StringContext);
-    onInit(): void;
-    onObjectConnected(object: StringObject): void;
-    onObjectDisconnected(object: StringObject): void;
-    onResize(): void;
-    destroy(): void;
-    private handleAdd;
-    private handleRemove;
-    private handleToggle;
-    private handleSettingChange;
-    private renderElement;
-    private refreshHUD;
-    private destroyElement;
-    private registerBuiltInAdapters;
-    private registerExternalAdapters;
-    private injectStyles;
-}
-
-/**
- * Discriminated union of all UI field descriptors.
- * Each adapter returns an array of these to describe its settings panel.
- */
-type UIFieldDescriptor = UIFieldNumber | UIFieldRange | UIFieldColor | UIFieldSelect | UIFieldToggle | UIFieldDivider;
-interface UIFieldNumber {
-    readonly type: "number";
-    readonly key: string;
-    readonly label: string;
-    readonly default: number;
-    readonly min?: number;
-    readonly max?: number;
-    readonly step?: number;
-}
-interface UIFieldRange {
-    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 UIFieldColor {
-    readonly type: "color";
-    readonly key: string;
-    readonly label: string;
-    readonly default: string;
-}
-interface UIFieldSelect {
-    readonly type: "select";
-    readonly key: string;
-    readonly label: string;
-    readonly default: string;
-    readonly options: ReadonlyArray<{
-        value: string;
-        label: string;
-    }>;
+ * @example
+ *   { type: "keyboard", key: "R", shiftKey: true }
+ */
+interface KeyboardRulersTrigger {
+    type: "keyboard";
+    /** The KeyboardEvent.key value (case-sensitive, e.g. "R", "g", "F2"). */
+    key: string;
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+    action?: RulersTriggerAction;
 }
-interface UIFieldToggle {
-    readonly type: "toggle";
-    readonly key: string;
-    readonly label: string;
-    readonly default: boolean;
+/**
+ * DOM element trigger — binds to one or more elements matching a CSS selector.
+ * The element(s) must exist in the DOM when the module subscribes (at `start()` time).
+ * For dynamically-added controls, prefer `type: "event"` instead.
+ *
+ * @example
+ *   { type: "element", selector: "#rulers-toggle-btn" }
+ *   { type: "element", selector: ".dev-toolbar [data-action='rulers']", event: "pointerdown" }
+ */
+interface ElementRulersTrigger {
+    type: "element";
+    /** CSS selector. All matching elements are bound. */
+    selector: string;
+    /** DOM event type. Defaults to "click". */
+    event?: string;
+    action?: RulersTriggerAction;
 }
-interface UIFieldDivider {
-    readonly type: "divider";
-    readonly label?: string;
+/**
+ * StringTune event-bus trigger — reacts to a named event emitted via the event manager.
+ * Useful for toolbar integrations, programmatic control, and cross-module communication.
+ *
+ * @example
+ *   { type: "event", name: "dev:rulers:toggle" }
+ *
+ * Activate via:
+ *   stringTune.emit("dev:rulers:toggle", null)
+ */
+interface EventRulersTrigger {
+    type: "event";
+    /** Event name on the StringTune event bus. */
+    name: string;
+    action?: RulersTriggerAction;
 }
+/**
+ * Discriminated union of all supported ruler trigger descriptors.
+ */
+type StringRulersTrigger = KeyboardRulersTrigger | ElementRulersTrigger | EventRulersTrigger;
 
 /**
- * Abstract base class for all grid adapters.
+ * Column-based layout grid.
+ *
+ * Displays a fixed set of equally-spaced column bands across the viewport.
+ * Column width is derived from the viewport width, margins, count, and gap.
+ *
+ * @example
+ *   { type: "columns", count: 12, marginLeft: 40, marginRight: 40, gap: 20 }
+ */
+interface ColumnsLayoutGrid {
+    type: "columns";
+    /** Number of columns. */
+    count: number;
+    /** Space reserved on the left edge of the viewport (px). Default: 0. */
+    marginLeft?: number;
+    /** Space reserved on the right edge of the viewport (px). Default: 0. */
+    marginRight?: number;
+    /** Gutter between columns (px). Default: 0. */
+    gap?: number;
+    /** Fill color for column bands. Default: "rgba(255, 0, 80, 0.08)". */
+    color?: string;
+}
+/**
+ * Row-based layout grid.
  *
- * 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
+ * Displays repeating horizontal stripes across the full document height.
+ * Stripes scroll with the page content.
  *
- * To create a new grid type, extend this class and implement
- * all abstract members. The system handles everything else.
+ * @example
+ *   { type: "rows", height: 8, gap: 0 }
  */
-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(): UIFieldDescriptor[];
-    /**
-     * 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"
-     * @param dimension Reference dimension (element width or height) for "%" mode
-     */
-    protected resolveUnit(value: number, unit: string, dimension: number): number;
-    /**
-     * Helper: creates an SVG path element.
-     */
-    protected createPath(d: string, stroke: string, opacity: number, strokeWidth?: number, fill?: string): SVGPathElement;
+interface RowsLayoutGrid {
+    type: "rows";
+    /** Height of each row band (px). */
+    height: number;
+    /** Gap between row bands (px). Default: 0. */
+    gap?: number;
+    /** Fill color for row bands. Default: "rgba(0, 120, 255, 0.06)". */
+    color?: string;
 }
+type RulersLayoutGrid = ColumnsLayoutGrid | RowsLayoutGrid;
 
 interface ModuleBatchContext {
     module: StringModule;
@@ -3131,4 +3070,4 @@ declare class StringTune {
     destroy(): void;
 }
 
-export { CursorReactiveModule, DOMBatcher, GridAdapter, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringForm, StringGlide, StringGrid, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringMasonry, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringRandom, StringResponsive, StringScrollContainer, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, StringTune as default, frameDOM, styleTxn };
+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 };