@fiddle-digital/string-tune 1.1.50 → 1.1.51

package/dist/index.d.mts

@@ -1058,6 +1058,7 @@ interface ISplitOptionItem {
  * Holds arrays of option definitions for each split type.
  */
 interface ISplitOptions {
+    fit?: boolean;
     line?: ISplitOptionItem[];
     word?: ISplitOptionItem[];
     char?: ISplitOptionItem[];
@@ -2034,6 +2035,38 @@ declare class StringSplit extends StringModule {
         result: DocumentFragment;
         extraProps: Map<string, string>;
     };
+    private getFitContext;
+    /**
+     * Computes target font sizes to fill the container width and stores them on each line.
+     *
+     * With a line-level split (`line`, `wordLine`, `charLine`): sets `fitFontSize` on each
+     * `LayoutLine` so that BuildDOMTree can expose `--fit-font-size` per `-s-line` span.
+     * Each line may receive a different value, allowing text to fill 100% of the container
+     * width independently per line.
+     *
+     * Without a line-level split: finds the widest line and returns a single
+     * `--fit-font-size` in the extraProps map, to be applied to the container element.
+     *
+     * Formula: targetFontSize = currentFontSize * (contentWidth / lineWidth)
+     */
+    private applyFit;
+    private refineFitFontSize;
+    private solveRenderedFitFontSize;
+    private measureScopeAtFontSize;
+    private measureCharScopeWidth;
+    private measureContentWidth;
+    /**
+     * Computes the target font size to fill `contentWidth`.
+     *
+     * Inter-word `\u00a0` nodes in the DOM are NOT wrapped in `-s-char` spans, so they
+     * stay at the original font size and do not scale. The formula accounts for this by
+     * subtracting total space width (fitWidth - browserWordWidthSum) from both sides:
+     *
+     *   targetFontSize = currentFontSize * (contentWidth - spacesWidth) / (lineWidth - spacesWidth)
+     *
+     * For single-word lines spacesWidth = 0 and the formula reduces to the simple ratio.
+     */
+    private computeFitFontSize;
     /**
      * Computes a numeric value based on the provided split option, index, and total count.
      *
@@ -2636,6 +2669,132 @@ declare class ScrollController {
     scrollTo(position: number, immediate?: boolean): void;
 }
 
+/**
+ * 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;
+    }>;
+}
+interface UIFieldToggle {
+    readonly type: "toggle";
+    readonly key: string;
+    readonly label: string;
+    readonly default: boolean;
+}
+interface UIFieldDivider {
+    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(): 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 ModuleBatchContext {
     module: StringModule;
     object: StringObject;
@@ -2935,4 +3094,4 @@ declare class StringTune {
     destroy(): void;
 }
 
-export { CursorReactiveModule, DOMBatcher, 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, 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 };

package/dist/index.d.ts

@@ -1058,6 +1058,7 @@ interface ISplitOptionItem {
  * Holds arrays of option definitions for each split type.
  */
 interface ISplitOptions {
+    fit?: boolean;
     line?: ISplitOptionItem[];
     word?: ISplitOptionItem[];
     char?: ISplitOptionItem[];
@@ -2034,6 +2035,38 @@ declare class StringSplit extends StringModule {
         result: DocumentFragment;
         extraProps: Map<string, string>;
     };
+    private getFitContext;
+    /**
+     * Computes target font sizes to fill the container width and stores them on each line.
+     *
+     * With a line-level split (`line`, `wordLine`, `charLine`): sets `fitFontSize` on each
+     * `LayoutLine` so that BuildDOMTree can expose `--fit-font-size` per `-s-line` span.
+     * Each line may receive a different value, allowing text to fill 100% of the container
+     * width independently per line.
+     *
+     * Without a line-level split: finds the widest line and returns a single
+     * `--fit-font-size` in the extraProps map, to be applied to the container element.
+     *
+     * Formula: targetFontSize = currentFontSize * (contentWidth / lineWidth)
+     */
+    private applyFit;
+    private refineFitFontSize;
+    private solveRenderedFitFontSize;
+    private measureScopeAtFontSize;
+    private measureCharScopeWidth;
+    private measureContentWidth;
+    /**
+     * Computes the target font size to fill `contentWidth`.
+     *
+     * Inter-word `\u00a0` nodes in the DOM are NOT wrapped in `-s-char` spans, so they
+     * stay at the original font size and do not scale. The formula accounts for this by
+     * subtracting total space width (fitWidth - browserWordWidthSum) from both sides:
+     *
+     *   targetFontSize = currentFontSize * (contentWidth - spacesWidth) / (lineWidth - spacesWidth)
+     *
+     * For single-word lines spacesWidth = 0 and the formula reduces to the simple ratio.
+     */
+    private computeFitFontSize;
     /**
      * Computes a numeric value based on the provided split option, index, and total count.
      *
@@ -2636,6 +2669,132 @@ declare class ScrollController {
     scrollTo(position: number, immediate?: boolean): void;
 }
 
+/**
+ * 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;
+    }>;
+}
+interface UIFieldToggle {
+    readonly type: "toggle";
+    readonly key: string;
+    readonly label: string;
+    readonly default: boolean;
+}
+interface UIFieldDivider {
+    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(): 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 ModuleBatchContext {
     module: StringModule;
     object: StringObject;
@@ -2935,4 +3094,4 @@ declare class StringTune {
     destroy(): void;
 }
 
-export { CursorReactiveModule, DOMBatcher, 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, 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 };