igniteui-webcomponents 7.2.3 → 7.3.0-beta.0

package/components/splitter/splitter.d.ts

@@ -1,10 +1,10 @@
 import { LitElement, type PropertyValues } from 'lit';
-import type { Constructor } from '../common/mixins/constructor.js';
+import type { Constructor } from '#internals/mixins/constructor.js';
 import type { SplitterOrientation } from '../types.js';
-import type { IgcSplitterComponentEventMap, IgcSplitterResizeEventArgs, IgcSplitterResizeEventDetail, PanePosition } from './types.js';
-declare const IgcSplitterComponent_base: Constructor<import("../common/mixins/event-emitter.js").EventEmitterInterface<IgcSplitterComponentEventMap>> & Constructor<LitElement>;
+import type { IgcSplitterComponentEventMap, IgcSplitterLayoutChangedEventArgs, IgcSplitterResizeEventArgs, IgcSplitterResizeEventDetail, PanePosition } from './types.js';
+declare const IgcSplitterComponent_base: Constructor<import("#internals/mixins/event-emitter.js").EventEmitterInterface<IgcSplitterComponentEventMap>> & Constructor<LitElement>;
 /**
- * The `igc-splitter` component provides a resizable split-pane layout that divides the view
+ * A splitter component that provides a resizable split-pane layout, dividing the view
  * into two panels — *start* and *end* — separated by a draggable bar.
  *
  * Panels can be resized by dragging the bar, using keyboard shortcuts, or collapsed/expanded
@@ -67,6 +67,8 @@ declare const IgcSplitterComponent_base: Constructor<import("../common/mixins/ev
  * @fires igcResizeStart - Emitted once when a resize operation begins (pointer drag or keyboard).
  * @fires igcResizing - Emitted continuously while a pane is being resized.
  * @fires igcResizeEnd - Emitted once when a resize operation completes.
+ * @fires igcLayoutChanged - Emitted after a user-driven resize or expansion change, with a full
+ * snapshot of the current layout (pane sizes and collapsed states).
  *
  * @slot start - Content projected into the start (left/top) panel.
  * @slot end - Content projected into the end (right/bottom) panel.
@@ -79,6 +81,12 @@ declare const IgcSplitterComponent_base: Constructor<import("../common/mixins/ev
  * @csspart end-collapse-btn - The button to collapse the end panel.
  * @csspart start-expand-btn - The button to expand the start panel when collapsed.
  * @csspart end-expand-btn - The button to expand the end panel when collapsed.
+ *
+ * @remarks
+ * The bar holds two expander elements, one on either side of the drag handle,
+ * and each carries whichever part name applies to the current collapsed state.
+ * A part name is therefore not tied to a fixed side: with the end pane
+ * collapsed, `end-expand-btn` lands on the *first* of the two.
  */
 export default class IgcSplitterComponent extends IgcSplitterComponent_base {
     static readonly tagName = "igc-splitter";
@@ -86,55 +94,59 @@ export default class IgcSplitterComponent extends IgcSplitterComponent_base {
     static register(): void;
     private readonly _internals;
     private readonly _separatorRef;
-    private _startPaneState;
-    private _endPaneState;
+    private readonly _startPaneState;
+    private readonly _endPaneState;
     private _collapsedPane;
     private _resizeState;
+    private _measurement;
+    /** Container extent at the last resize notification we acted on. */
+    private _observedSize;
     private readonly _base;
     private readonly _startPane;
     private readonly _endPane;
     private get _separator();
+    private get _isDragging();
     private get _resizeDisallowed();
     private get _isHorizontal();
     private get _separatorCursor();
     /**
      * The orientation of the splitter, which determines the direction of resizing and collapsing.
      *
+     * Changing the orientation after the initial render clears the pane sizes and
+     * their min/max constraints, along with the corresponding attributes - a size
+     * authored for one axis rarely makes sense on the other.
      * @attr orientation
      * @default 'horizontal'
      */
     orientation: SplitterOrientation;
     /**
-     * When true, prevents the user from collapsing either pane.
-     * This also hides the expand/collapse buttons on the splitter bar.
-     *
+     * Whether collapsing either pane is disabled. When `true`, this also hides
+     * the expand/collapse buttons on the splitter bar.
      * @attr disable-collapse
      * @default false
      */
     disableCollapse: boolean;
     /**
-     * When true, prevents the user from resizing the panes by dragging the splitter bar or using keyboard shortcuts.
-     * This also hides the drag handle on the splitter bar.
-     *
+     * Whether resizing the panes by dragging the splitter bar or using keyboard
+     * shortcuts is disabled. When `true`, this also hides the drag handle on the
+     * splitter bar.
      * @attr disable-resize
      * @default false
      */
     disableResize: boolean;
     /**
-     * When true, hides the expand/collapse buttons on the splitter bar.
+     * Whether the expand/collapse buttons on the splitter bar are hidden.
      *
      * Note that the buttons will also be hidden if `disable-collapse` is true or
      * if a pane is currently collapsed.
-     *
      * @attr hide-collapse-buttons
      * @default false
      */
     hideCollapseButtons: boolean;
     /**
-     * When true, hides the drag handle on the splitter bar.
+     * Whether the drag handle on the splitter bar is hidden.
      *
      * Note that the drag handle will also be hidden if `disable-resize` is true.
-     *
      * @attr hide-drag-handle
      * @default false
      */
@@ -142,6 +154,9 @@ export default class IgcSplitterComponent extends IgcSplitterComponent_base {
     /**
      * The minimum size of the start pane.
      *
+     * Accepts a CSS length with an explicit unit, e.g. `100px` or `20%`, or a
+     * unitless `0`. Setting `auto`, any other unitless or unparsable value, a
+     * negative value, or a percentage above 100 removes the constraint.
      * @attr start-min-size
      */
     set startMinSize(value: string | undefined);
@@ -149,6 +164,9 @@ export default class IgcSplitterComponent extends IgcSplitterComponent_base {
     /**
      * The minimum size of the end pane.
      *
+     * Accepts a CSS length with an explicit unit, e.g. `100px` or `20%`, or a
+     * unitless `0`. Setting `auto`, any other unitless or unparsable value, a
+     * negative value, or a percentage above 100 removes the constraint.
      * @attr end-min-size
      */
     set endMinSize(value: string | undefined);
@@ -156,6 +174,9 @@ export default class IgcSplitterComponent extends IgcSplitterComponent_base {
     /**
      * The maximum size of the start pane.
      *
+     * Accepts a CSS length with an explicit unit, e.g. `500px` or `80%`, or a
+     * unitless `0`. Setting `auto`, any other unitless or unparsable value, a
+     * negative value, or a percentage above 100 removes the constraint.
      * @attr start-max-size
      */
     set startMaxSize(value: string | undefined);
@@ -163,6 +184,9 @@ export default class IgcSplitterComponent extends IgcSplitterComponent_base {
     /**
      * The maximum size of the end pane.
      *
+     * Accepts a CSS length with an explicit unit, e.g. `500px` or `80%`, or a
+     * unitless `0`. Setting `auto`, any other unitless or unparsable value, a
+     * negative value, or a percentage above 100 removes the constraint.
      * @attr end-max-size
      */
     set endMaxSize(value: string | undefined);
@@ -170,6 +194,9 @@ export default class IgcSplitterComponent extends IgcSplitterComponent_base {
     /**
      * The size of the start pane.
      *
+     * Accepts a CSS length with an explicit unit, e.g. `200px` or `50%`, or a
+     * unitless `0`. Setting `auto`, any other unitless or unparsable value, a
+     * negative value, or a percentage above 100 falls back to automatic sizing.
      * @attr start-size
      */
     set startSize(value: string | undefined);
@@ -177,29 +204,65 @@ export default class IgcSplitterComponent extends IgcSplitterComponent_base {
     /**
      * The size of the end pane.
      *
+     * Accepts a CSS length with an explicit unit, e.g. `200px` or `50%`, or a
+     * unitless `0`. Setting `auto`, any other unitless or unparsable value, a
+     * negative value, or a percentage above 100 falls back to automatic sizing.
      * @attr end-size
      */
     set endSize(value: string | undefined);
     get endSize(): string | undefined;
+    /**
+     * Whether the start pane is currently collapsed. Set this property to
+     * collapse or expand the pane programmatically.
+     * @attr start-collapsed
+     * @default false
+     */
+    set startCollapsed(value: boolean);
+    get startCollapsed(): boolean;
+    /**
+     * Whether the end pane is currently collapsed. Set this property to
+     * collapse or expand the pane programmatically.
+     * @attr end-collapsed
+     * @default false
+     */
+    set endCollapsed(value: boolean);
+    get endCollapsed(): boolean;
     constructor();
     protected update(changed: PropertyValues<this>): void;
     protected updated(): void;
+    disconnectedCallback(): void;
     private _handleBarPointerDown;
     private _getDragDelta;
     private _handleBarPointerMove;
     private _handleEndDrag;
+    /** A cancelled gesture reverts, but still reports an end for the start it emitted. */
+    private _handleCancelDrag;
     private _endDrag;
-    /** Toggles the collapsed state of the specified pane. */
+    /**
+     * Toggles the collapsed state of the specified pane.
+     *
+     * Does not emit `igcLayoutChanged` - that event reports user-driven changes,
+     * and a programmatic call is already known to the caller.
+     */
     toggle(position: PanePosition): void;
+    private _applyCollapse;
+    private _setPaneSize;
+    /** Drops the authored sizes and their attributes, which would otherwise diverge. */
+    private _resetPaneSizes;
+    private _setCollapsed;
     private _savePaneSizes;
     private _restoreSizesOnExpandCollapse;
-    /** Measures the actual rendered size of a pane and returns it as a percentage of total size. */
-    private _paneRectAsPercent;
-    /** Converts a CSS size string (px or %) to a percentage of total size. */
-    private _sizeToPercent;
+    /**
+     * The container is what the browser resolves a percentage `flex-basis`
+     * against, so a value measured this way survives a round trip through CSS.
+     */
+    private _asPercentOfContainer;
+    /** Resolves a CSS length to pixels, percentages against the container. */
+    private _toPixels;
     private _getStartPaneSizePercent;
     private _getMinMaxAsPercent;
     private _isCollapsed;
+    private _otherPane;
     private _updateBarAria;
     private _getPaneState;
     private _isPercentageSize;
@@ -207,20 +270,40 @@ export default class IgcSplitterComponent extends IgcSplitterComponent_base {
     private _normalizeValue;
     private _getFlex;
     private _handleResizePanes;
+    /**
+     * A complete resize for a non-pointer gesture. Sharing `_calcNewSizes` with
+     * the drag path is what keeps both panes' constraints honoured and the
+     * emitted sizes equal to the ones that actually render.
+     */
+    private _runResize;
     private _preventDefaultForEvent;
     private _resolveDelta;
+    /** Snaps the start pane to its minimum or maximum size. */
     private _handleMinMaxResize;
     private _handleExpanderAction;
+    private _toggleWithEvent;
+    private _reportedSize;
+    private _emitLayoutChanged;
     private _handleArrowsExpandCollapse;
     private _resizeStart;
     private _createPaneState;
-    private _setMinMaxInPx;
+    private _getConstraintInPx;
     private _resizing;
     private _computeSize;
     private _resizeEnd;
     private _rectSize;
     private _calcNewSizes;
+    /**
+     * Reads the container and bar extents once per update pass - both
+     * `_updatePanes` and `_updateBarAria` need them, and the style writes in
+     * between would force a reflow for every repeated read.
+     */
+    private _measure;
+    /** The content box of the flex container - the basis for every percentage. */
+    private _getContainerSize;
+    /** The space left for the panes once the bar has taken its own. */
     private _getTotalSize;
+    private _handleContainerResize;
     private _updatePanes;
     private _updatePaneStyles;
     private _setPaneMinMaxSizes;
@@ -232,7 +315,7 @@ export default class IgcSplitterComponent extends IgcSplitterComponent_base {
     private _renderSeparator;
     protected render(): import("lit-html").TemplateResult<1>;
 }
-export type { IgcSplitterComponentEventMap, IgcSplitterResizeEventArgs, IgcSplitterResizeEventDetail, };
+export type { IgcSplitterComponentEventMap, IgcSplitterLayoutChangedEventArgs, IgcSplitterResizeEventArgs, IgcSplitterResizeEventDetail, };
 declare global {
     interface HTMLElementTagNameMap {
         'igc-splitter': IgcSplitterComponent;