@fiddle-digital/string-tune 1.1.51 → 1.1.52

package/dist/index.d.mts

@@ -1737,6 +1737,7 @@ declare class StringCursor extends StringModule {
     private getFrameAdjustedLerp;
     private getObjectDimensions;
     private calculateOffset;
+    private reverseOffset;
     removeObject(id: string): void;
     destroy(): void;
 }
@@ -2670,130 +2671,105 @@ declare class ScrollController {
 }
 
 /**
- * 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;
-    }>;
+ * What the trigger does when activated.
+ * Defaults to "toggle" when not specified.
+ */
+type RulersTriggerAction = "toggle" | "show" | "hide";
+/**
+ * Keyboard shortcut trigger.
+ *
+ * @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.
  *
- * 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
+ * @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.
  *
- * To create a new grid type, extend this class and implement
- * all abstract members. The system handles everything else.
+ * Displays repeating horizontal stripes across the full document height.
+ * Stripes scroll with the page content.
+ *
+ * @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;
@@ -3094,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, 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

@@ -1737,6 +1737,7 @@ declare class StringCursor extends StringModule {
     private getFrameAdjustedLerp;
     private getObjectDimensions;
     private calculateOffset;
+    private reverseOffset;
     removeObject(id: string): void;
     destroy(): void;
 }
@@ -2670,130 +2671,105 @@ declare class ScrollController {
 }
 
 /**
- * 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;
-    }>;
+ * What the trigger does when activated.
+ * Defaults to "toggle" when not specified.
+ */
+type RulersTriggerAction = "toggle" | "show" | "hide";
+/**
+ * Keyboard shortcut trigger.
+ *
+ * @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.
  *
- * 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
+ * @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.
  *
- * To create a new grid type, extend this class and implement
- * all abstract members. The system handles everything else.
+ * Displays repeating horizontal stripes across the full document height.
+ * Stripes scroll with the page content.
+ *
+ * @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;
@@ -3094,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, 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 };