@globalpayments/vega 2.95.0 → 2.97.0

package/dist/types/helpers/a11y-tree/a11y-node-dto.d.ts

@@ -0,0 +1,173 @@
+import { A11yNode, A11ySemanticKind } from './a11y-tree.types';
+/**
+ * Semantic DTO layer for the A11y Tree.
+ *
+ * Authoring an A11y Tree with raw `A11yNode` literals asks the developer to
+ * think in ARIA terms (`role: 'group'`, `decorative: true`, etc.). The DTO
+ * classes here provide a higher-level vocabulary that names the *content's
+ * meaning* — "this is a container", "this is a heading", "this is a
+ * decorative icon" — and lets the strategy layer translate intent into ARIA.
+ *
+ * ## Design (Visitor / Strategy + typed semantic DTOs)
+ *
+ * - DTOs are *type-holders for semantic intent*. They do NOT contain ARIA
+ *   generation logic themselves.
+ * - Each DTO compiles to an `A11yNode` whose `kind` field carries the
+ *   semantic discriminator. Strategies can then dispatch on `kind`
+ *   (preferred) or fall back to `role` (for plain `A11yNode` authors).
+ * - This keeps strategies pure and independently testable, while letting
+ *   authors write:
+ *
+ *   ```ts
+ *   new A11yContainerNode('st-root', { label, description })
+ *     .childrenWith(
+ *       new A11yHeadingNode('st-heading', { level: 2, label }),
+ *       new A11yIconNode('st-icon'),
+ *     );
+ *   ```
+ *
+ *   instead of hand-shaping `{ role: 'group', label, description, … }`.
+ *
+ * ## Migration path
+ *
+ * Phase 1 (this file): DTOs are an additive layer on top of `A11yNode`.
+ * Existing strategies continue to work unchanged because each DTO emits
+ * a fully-populated `A11yNode` with `role` set correctly.
+ *
+ * Phase 2 (follow-up): strategies grow `compileNode(node)` methods that
+ * dispatch on `node.kind` for cases where semantic intent is richer than
+ * `role` alone can express.
+ */
+/**
+ * Base class for all semantic DTO nodes. Provides the `childrenWith()`
+ * composition helper and the abstract `toA11yNode()` contract.
+ */
+export declare abstract class A11yNodeDto {
+  protected childDtos: A11yNodeDto[];
+  abstract readonly kind: A11ySemanticKind;
+  /**
+   * Declare the semantic children of this node in reading order.
+   *
+   * @param {...A11yNodeDto} children - Semantic child DTOs in reading order.
+   * @returns {this} `this`, for fluent chaining.
+   */
+  childrenWith(...children: A11yNodeDto[]): this;
+  /**
+   * Compile the declared child DTOs into their `A11yNode` representations.
+   *
+   * @returns {A11yNode[] | undefined} The compiled children, or `undefined` when none.
+   */
+  protected compileChildren(): A11yNode[] | undefined;
+  /** Compile this DTO (and its subtree) into an `A11yNode`. */
+  abstract toA11yNode(): A11yNode;
+}
+/**
+ * A generic container that groups related content. Maps to `role="group"`
+ * by default; strategies may upgrade to `role="region"` when a description
+ * is present and the platform benefits (e.g. Firefox+NVDA landmark
+ * navigation — see `firefox-nvda-strategy.ts`).
+ */
+export declare class A11yContainerNode extends A11yNodeDto {
+  readonly id: string;
+  readonly opts: {
+    label?: string;
+    description?: string;
+  };
+  readonly kind: A11ySemanticKind;
+  constructor(id: string, opts?: {
+    label?: string;
+    description?: string;
+  });
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode(): A11yNode;
+}
+/**
+ * A navigable / discoverable section (landmark). Always renders as
+ * `role="region"` so it appears in AT landmark navigation.
+ */
+export declare class A11yLandmarkNode extends A11yNodeDto {
+  readonly id: string;
+  readonly opts: {
+    label?: string;
+    description?: string;
+  };
+  readonly kind: A11ySemanticKind;
+  constructor(id: string, opts?: {
+    label?: string;
+    description?: string;
+  });
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode(): A11yNode;
+}
+/**
+ * A heading at the given level (1–6, defaults to 2).
+ *
+ * Use this instead of a raw `{ role: 'heading', level: 2 }` literal to
+ * benefit from the default-level guard and the `kind` discriminator.
+ */
+export declare class A11yHeadingNode extends A11yNodeDto {
+  readonly id: string;
+  readonly opts: {
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    label?: string;
+  };
+  readonly kind: A11ySemanticKind;
+  constructor(id: string, opts?: {
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    label?: string;
+  });
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode(): A11yNode;
+}
+/**
+ * A purely decorative icon. `decorative` is always `true` so authors never
+ * have to remember the flag — that is the whole point of this DTO class.
+ *
+ * Produces `aria-hidden="true"` via the baseline strategy; webkit-voiceover
+ * additionally sets `role="none"` as a belt-and-suspenders guard.
+ */
+export declare class A11yIconNode extends A11yNodeDto {
+  readonly id: string;
+  readonly kind: A11ySemanticKind;
+  constructor(id: string);
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode(): A11yNode;
+}
+/**
+ * An informative image that requires an accessible label (alt text).
+ *
+ * Produces `role="img"` + `aria-label` via the baseline strategy.
+ * Contrast with `A11yIconNode` which is always decorative.
+ */
+export declare class A11yImageNode extends A11yNodeDto {
+  readonly id: string;
+  readonly opts: {
+    label: string;
+  };
+  readonly kind: A11ySemanticKind;
+  constructor(id: string, opts: {
+    label: string;
+  });
+  /**
+   * Compile this DTO into its `A11yNode` representation.
+   *
+   * @returns {A11yNode} The compiled semantic node.
+   */
+  toA11yNode(): A11yNode;
+}

package/dist/types/helpers/a11y-tree/a11y-tree-applier.d.ts

@@ -0,0 +1,28 @@
+import { A11yNode } from './a11y-tree.types';
+/**
+ * Applies an A11y Tree to a shadow root by:
+ *
+ *   1. Resolving the `A11yTreeStrategy` that best matches the current
+ *      browser engine / AT environment.
+ *   2. Compiling the semantic tree into a flat list of `AriaPatch`
+ *      instructions.
+ *   3. Clearing any previously managed ARIA attributes (`data-a11y-managed`).
+ *   4. Applying each patch to the `data-a11y-id` target node in the shadow.
+ *   5. Materialising one visually-hidden description `<span>` per patch that
+ *      references `aria-describedby` and whose node carries description text.
+ *   6. Stamping `data-a11y-strategy-applied` on the host for observability.
+ *
+ * This is the generic, component-agnostic projection step. Components
+ * interact with it indirectly through `A11yTreeSlimmer`.
+ *
+ * @param {A11yNode} root - The root `A11yNode` of the semantic tree.
+ * @param {HTMLElement} host - The component's host element. Must have a `shadowRoot`.
+ *   If `shadowRoot` is null (e.g. light-DOM component or early call before first
+ *   render), the function returns immediately without throwing.
+ * @example
+ * ```ts
+ * // Called once per render from A11yTreeSlimmer.projectA11yTree():
+ * applyA11yTree(buildSectionTitleA11yTree({ titleText, description }), this.host);
+ * ```
+ */
+export declare function applyA11yTree(root: A11yNode, host: HTMLElement): void;

package/dist/types/helpers/a11y-tree/a11y-tree.types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * A11y Tree — generic type definitions.
+ *
+ * The A11y Tree is a browser-agnostic description of the *semantic* a11y
+ * structure of a component. Each node captures the intent (role, label,
+ * description, level, etc.) and a stable `id` that the strategy layer
+ * can use to project ARIA attributes onto the real DOM.
+ *
+ * ## Architecture overview
+ *
+ * ```
+ * Component (TSX)
+ *   ↓  builds semantic tree via DTO helpers (a11y-node-dto.ts)
+ * A11yNode tree (this file)
+ *   ↓  compiled by an A11yTreeStrategy
+ * AriaPatch[]
+ *   ↓  applied by a11y-tree-applier.ts
+ * Shadow DOM (ARIA attributes on data-a11y-id elements)
+ * ```
+ *
+ * The A11y Tree is NOT rendered itself. It is consumed by an
+ * `A11yTreeStrategy` that decides, per browser/AT, which ARIA attributes
+ * to attach to which DOM nodes.
+ *
+ * ## Browser-engine strategy contract
+ *
+ * Assistive technology (AT) cannot be detected from JavaScript (by design,
+ * for user privacy). The strategy resolver therefore branches on *browser
+ * engine* as a coarse proxy for the most likely AT pairing:
+ *
+ * | Engine    | Assumed AT         | Confidence          |
+ * |-----------|-------------------|---------------------|
+ * | WebKit    | VoiceOver (macOS/iOS) | medium on Apple, low elsewhere |
+ * | Gecko     | NVDA (Windows), Orca (Linux) | medium on Win, low elsewhere |
+ * | Chromium  | JAWS / NVDA / TalkBack     | high on non-Apple, medium on Apple |
+ *
+ * **Confidence semantics** (see `A11yStrategyConfidence`):
+ * - `high`   — direct signal (explicit override or confirmed UA).
+ * - `medium` — plausible proxy; AT pairing is an assumption that covers the
+ *              majority of users on that engine+platform combination.
+ * - `low`    — unknown UA or atypical engine/platform combo; dev-mode warning
+ *              fires once per (strategy, reason) tuple via `resolveStrategy`.
+ *
+ * Consumers who know the AT environment (e.g. automated tests, a storybook
+ * knob) can pin a strategy explicitly via `data-a11y-strategy` on the host
+ * element — this is always treated as `high` confidence.
+ */
+export declare type A11yRole = 'heading' | 'group' | 'region' | 'img' | 'presentation' | 'none';
+/**
+ * Semantic kind — describes *what the content is*, independent of which
+ * ARIA attribute it ultimately produces. Strategies may dispatch on `kind`
+ * for fine-grained control beyond what `role` can express.
+ *
+ * Authoritative definition: `a11y-node-dto.ts`. Re-exported here so tree
+ * literal authors can type-check without importing the DTO module.
+ */
+export declare type A11ySemanticKind = 'container' | 'landmark' | 'heading' | 'icon' | 'image' | 'button' | 'live';
+/**
+ * A single node in the semantic A11y Tree.
+ *
+ * Nodes are authored via the DTO helpers in `a11y-node-dto.ts` to avoid
+ * hand-shaping ARIA field names. Raw literals are still accepted by all
+ * APIs for backwards compatibility and quick inline use.
+ */
+export interface A11yNode {
+  /** Stable identifier; DOM nodes opt in via `data-a11y-id`. */
+  id: string;
+  /** Semantic role for this node. */
+  role: A11yRole;
+  /**
+   * Optional semantic discriminator emitted by the DTO layer.
+   * Strategies that need to distinguish intent beyond `role`
+   * (e.g. landmark vs plain container) dispatch on this first
+   * and fall back to `role` when absent.
+   */
+  kind?: A11ySemanticKind;
+  /** Visible text label (used for aria-label / aria-labelledby). */
+  label?: string;
+  /** Supplementary description (used for aria-describedby). */
+  description?: string;
+  /** Heading level (1–6) when role === 'heading'. */
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+  /** Whether this node is purely decorative. */
+  decorative?: boolean;
+  /** Child semantic nodes. */
+  children?: A11yNode[];
+}
+/**
+ * A flat instruction emitted by the strategy: "on the DOM node carrying
+ * `data-a11y-id=<targetId>`, set this attribute to this value".
+ *
+ * `value === null` means the attribute should be removed.
+ */
+export interface AriaPatch {
+  targetId: string;
+  attribute: string;
+  value: string | null;
+}
+/**
+ * Strategy contract. Each strategy encapsulates the per-browser/AT quirks
+ * needed to project an `A11yNode` tree onto real ARIA attributes.
+ *
+ * Strategies MUST be pure functions of the tree: same input → same output.
+ * Side effects (DOM manipulation) belong in `a11y-tree-applier.ts`.
+ */
+export interface A11yTreeStrategy {
+  /** Machine-readable name, used for `data-a11y-strategy` lookups. */
+  name: string;
+  /** Convert a semantic A11y tree into a flat list of ARIA patches. */
+  compile(root: A11yNode): AriaPatch[];
+}
+/**
+ * Confidence level for the strategy-resolver's UA→AT mapping.
+ *
+ *   - `high`   : we observed a direct signal (explicit override, or a
+ *                UA the resolver has confirmed test coverage for).
+ *   - `medium` : UA pattern is a known proxy but the AT pairing is an
+ *                assumption (e.g. Firefox → NVDA on Windows; users on
+ *                Linux running Orca will also match this branch).
+ *   - `low`    : we are falling back to baseline because we could not
+ *                recognise the UA at all.
+ *
+ * Low-confidence matches surface a dev-mode console warning (rate-limited
+ * per strategy+reason tuple) so product teams know when to pin a strategy
+ * explicitly via `data-a11y-strategy`.
+ */
+export declare type A11yStrategyConfidence = 'high' | 'medium' | 'low';
+/**
+ * Full resolution result including the strategy, how confident we are,
+ * and a human-readable reason string for dev warnings.
+ */
+export interface A11yStrategyResolution {
+  strategy: A11yTreeStrategy;
+  confidence: A11yStrategyConfidence;
+  /** Human-readable reason — surfaced in dev warnings. */
+  reason: string;
+}

package/dist/types/helpers/a11y-tree/strategies/baseline-strategy.d.ts

@@ -0,0 +1,18 @@
+import { A11yTreeStrategy } from '../a11y-tree.types';
+/**
+ * Baseline strategy: spec-compliant ARIA, works on evergreen Chromium,
+ * Firefox, and Safari with their default AT pairings (NVDA, Orca,
+ * VoiceOver-macOS). Used as the default when no engine-specific override
+ * matches.
+ *
+ * ## Mapping rules
+ *
+ * | Node role     | ARIA output                                        |
+ * |---------------|----------------------------------------------------|
+ * | heading       | `role="heading"` + `aria-level`                    |
+ * | group/region  | `role` + `aria-label` (if present) + `aria-describedby` (if description) |
+ * | img (decorative) | `aria-hidden="true"`                            |
+ * | img (labelled)   | `role="img"` + `aria-label`                    |
+ * | presentation/none | `role="presentation"`                         |
+ */
+export declare const baselineStrategy: A11yTreeStrategy;

package/dist/types/helpers/a11y-tree/strategies/firefox-nvda-strategy.d.ts

@@ -0,0 +1,16 @@
+import { A11yTreeStrategy } from '../a11y-tree.types';
+/**
+ * Firefox + NVDA strategy.
+ *
+ * Firefox/NVDA generally handles spec-compliant ARIA correctly. The one
+ * known quirk for the Vega component family:
+ *
+ * **NVDA browse-mode may skip `aria-describedby` on `role="group"`.**
+ * When a group container carries a description, NVDA in browse (reading)
+ * mode sometimes does not announce it. Workaround: promote the container to
+ * `role="region"`, which is part of the landmark navigation set and is
+ * reliably announced by NVDA when encountered during linear reading.
+ *
+ * All other node types fall back to baseline behaviour.
+ */
+export declare const firefoxNvdaStrategy: A11yTreeStrategy;

package/dist/types/helpers/a11y-tree/strategies/webkit-voiceover-strategy.d.ts

@@ -0,0 +1,23 @@
+import { A11yTreeStrategy } from '../a11y-tree.types';
+/**
+ * WebKit + VoiceOver strategy.
+ *
+ * Applies on top of the baseline to work around two known VoiceOver quirks:
+ *
+ * **Quirk #1 — `aria-describedby` on non-focusable containers is skipped.**
+ * VoiceOver on Safari often does not read `aria-describedby` on non-focusable
+ * `role="group"` (A11yContainerNode) or `role="region"` (A11yLandmarkNode)
+ * containers. Workaround: fold the description text directly into the
+ * heading's `aria-label` (joined with `. `) so it is read together with the
+ * title, and remove the orphaned `aria-describedby` patch.
+ *
+ * **Quirk #2 — Decorative `<vega-icon>` announced twice.**
+ * Safari occasionally announces a decorative icon twice when only
+ * `aria-hidden` is set on the host. We additionally set `role="none"` as a
+ * belt-and-suspenders guard that suppresses the extra announcement.
+ *
+ * These adjustments are applied as a *diff* on top of the baseline patch
+ * list — the A11y Tree itself is unchanged. Other node types fall back to
+ * baseline behaviour.
+ */
+export declare const webkitVoiceOverStrategy: A11yTreeStrategy;

package/dist/types/helpers/a11y-tree/strategy-resolver.d.ts

@@ -0,0 +1,59 @@
+import { A11yStrategyResolution, A11yTreeStrategy } from './a11y-tree.types';
+/**
+ * All registered strategies. The resolver picks from this list; callers that
+ * need exhaustive enumeration (e.g. tests, Storybook knobs) can import this
+ * constant directly.
+ */
+export declare const ALL_A11Y_STRATEGIES: A11yTreeStrategy[];
+/**
+ * Picks an `A11yTreeStrategy` from the runtime environment and returns the
+ * full `A11yStrategyResolution` including confidence and a reason string.
+ *
+ * ## Browser-engine detection
+ *
+ * AT cannot be detected from JS (user privacy). We branch on *browser engine*
+ * as a coarse proxy for the most likely AT pairing on each platform:
+ *
+ * | Engine    | Assumed AT                   | Confidence              |
+ * |-----------|------------------------------|-------------------------|
+ * | WebKit    | VoiceOver (macOS/iOS)        | medium on Apple, low elsewhere |
+ * | Gecko     | NVDA (Win), Orca (Linux)     | medium on Win32, low elsewhere |
+ * | Chromium  | JAWS / NVDA / TalkBack       | high on non-Apple, medium on Apple |
+ *
+ * An explicit `data-a11y-strategy` attribute on the host element is always
+ * treated as `high` confidence (known override). If the override value does
+ * not match any registered strategy name, the resolver falls back to baseline
+ * with `low` confidence and logs an actionable warning.
+ *
+ * @param {HTMLElement} [host] - The component host element. When provided, its
+ *   `data-a11y-strategy` attribute is checked first.
+ * @returns {A11yStrategyResolution} The resolved strategy with confidence and reason.
+ */
+export declare function resolveStrategyDetailed(host?: HTMLElement): A11yStrategyResolution;
+/**
+ * Pure UA→strategy mapping. Separated from `resolveStrategyDetailed` so the
+ * browser-engine detection table can be unit tested deterministically by
+ * passing explicit `userAgent` / `platform` values instead of mocking the
+ * global `navigator` (which build/test tooling may sandbox).
+ *
+ * @param {string | undefined} userAgent - The `navigator.userAgent` string, or
+ *   `undefined` for an SSR / non-browser environment.
+ * @param {string} platform - The `navigator.platform` string (empty string when
+ *   unavailable).
+ * @returns {A11yStrategyResolution} The resolved strategy with confidence and reason.
+ */
+export declare function resolveStrategyFromEnv(userAgent: string | undefined, platform: string): A11yStrategyResolution;
+/**
+ * Convenience wrapper for callers that only need the resolved strategy.
+ * Equivalent to `resolveStrategyDetailed(host).strategy` but additionally
+ * emits a **dev-mode console warning** for `low`-confidence resolutions,
+ * pointing engineers at the `data-a11y-strategy` override mechanism.
+ *
+ * The warning is rate-limited per `(strategyName, reason)` tuple to avoid
+ * log spam on every render cycle.
+ *
+ * @param {HTMLElement} [host] - The component host element (optional). Used for
+ *   the `data-a11y-strategy` override check.
+ * @returns {A11yTreeStrategy} The resolved strategy.
+ */
+export declare function resolveStrategy(host?: HTMLElement): A11yTreeStrategy;

package/dist/types/helpers/slimmers/a11y-tree-slimmer.d.ts

@@ -0,0 +1,49 @@
+import { VegaSlimmer } from '../../vega-slimmer/vega-slimmer-core';
+import { A11yNode } from '../a11y-tree/a11y-tree.types';
+/**
+ * Builder function type: given the component host element, produce the
+ * semantic `A11yNode` tree describing the component's a11y intent.
+ *
+ * Builders are component-specific; this slimmer is generic and reusable
+ * across any component that opts into the A11y Tree foundation.
+ *
+ * @template T - The concrete `HTMLElement` subtype for the host (e.g.
+ *   `HTMLVegaSectionTitleElement`).
+ */
+export declare type A11yTreeBuilder<T extends HTMLElement> = (host: T) => A11yNode;
+/**
+ * Generic A11y Tree slimmer.
+ *
+ * Hooks `componentDidRender` and projects the component's semantic A11y
+ * Tree onto its shadow DOM using the strategy resolved for the current
+ * browser engine.
+ *
+ * ## Opt-in steps for a component
+ *
+ * 1. Tag render targets with `data-a11y-id="<stable-id>"` in the renderer.
+ * 2. Author a `build<Component>A11yTree(host)` function (see
+ *    `a11y-node-dto.ts` for the DTO helpers that make this ergonomic).
+ * 3. Inject this slimmer with `@InjectVegaSlimmer()`:
+ *
+ * ```ts
+ * @InjectVegaSlimmer()
+ * protected a11yTreeSlimmer = new A11yTreeSlimmer<HTMLVegaFooElement>(
+ *   host => buildFooA11yTree({ title: host.title, description: host.description }),
+ * );
+ * ```
+ *
+ * The slimmer handles strategy selection, patch application, and cleanup
+ * on every subsequent render.
+ *
+ * @template T - The concrete `HTMLElement` subtype for the component host.
+ */
+export declare class A11yTreeSlimmer<T extends HTMLElement> extends VegaSlimmer {
+  private readonly buildA11yTree;
+  host: T;
+  constructor(buildA11yTree: A11yTreeBuilder<T>);
+  /**
+   * Called by Stencil after each render. Projects the semantic A11y Tree
+   * onto the shadow DOM via the resolved browser-engine strategy.
+   */
+  protected projectA11yTree(): void;
+}

package/dist/types/helpers/slimmers/element-appender/element-appender-slimmer.d.ts

@@ -16,6 +16,7 @@ export declare class ElementAppenderSlimmer extends VegaSlimmer {
   private delayHideTimer;
   private elementAppender;
   private shadowRootElementScrollingObserver;
+  private visibilityModifiers;
   /**
    * appendableElement is interactive by default (to pass [WCAG 2.1 success criterion 1.4.13](https://www.w3.org/TR/WCAG21/#content-on-hover-or-focus))
    */
@@ -50,6 +51,14 @@ export declare class ElementAppenderSlimmer extends VegaSlimmer {
   private elementMouseLeaveHandler;
   private globalMouseDownHandler;
   private globalScrollHandler;
+  /**
+   * Runs every enabled visibility modifier against the current show config and
+   * routes their actions to the appender. Modifiers are viewport-level,
+   * cross-cutting concerns that run in parallel with (not in place of) the
+   * selected trigger strategy — they only affect the appendable's visual
+   * clipping, never its logical open state.
+   */
+  private executeVisibilityModifiers;
   private createDelayHideTimer;
   private clearDelayHideTimer;
   /**

package/dist/types/helpers/slimmers/element-appender/visibility-modifiers/clip-on-scroll-modifier.d.ts

@@ -0,0 +1,37 @@
+import { VegaEAVisibilityContext, VegaEAVisibilityModifier, VegaEAVisibilityResult } from './visibility-modifier.interface';
+/**
+ * Returns the flattened-tree parent of a node so we can walk from inside a shadow
+ * tree up to the top-level document: assigned slot → parent element → shadow
+ * host.
+ *
+ * @param {Node} node - The node whose flattened-tree parent should be returned.
+ * @returns {HTMLElement | null} The flattened-tree parent, or null when the walk has reached the top.
+ */
+export declare function flatParent(node: Node): HTMLElement | null;
+/**
+ * Returns true when the trigger is clipped out of view by the visual viewport
+ * or by any scrollable ancestor.
+ *
+ * @param {HTMLElement} target - The trigger element to test against the viewport and scrollable ancestors.
+ * @returns {boolean} True when the trigger is clipped and the appendable should be hidden.
+ */
+export declare function isTriggerClipped(target: HTMLElement): boolean;
+/**
+ * Clip-hides an appendable while its trigger is scrolled out of view and
+ * restores it when the trigger returns, without touching the popup's logical
+ * open state. Applies to every appender consumer.
+ */
+export declare class ClipOnScrollModifier implements VegaEAVisibilityModifier {
+  /**
+   * @returns {boolean} Always true — geometry alone decides clip vs restore in `evaluate`.
+   */
+  isEnabled(): boolean;
+  /**
+   * Evaluates whether the appendable should be clip-hidden or restored based
+   * on the current trigger geometry.
+   *
+   * @param {VegaEAVisibilityContext} context - Evaluation context.
+   * @returns {VegaEAVisibilityResult} The next clip action.
+   */
+  evaluate(context: VegaEAVisibilityContext): VegaEAVisibilityResult;
+}

package/dist/types/helpers/slimmers/element-appender/visibility-modifiers/visibility-modifier.interface.d.ts

@@ -0,0 +1,56 @@
+import { ElementAppenderShowConfig } from '../../../ui/element-appender';
+/**
+ * Viewport-level event that can drive a visibility modifier. Modeled as a
+ * discriminated union so new event kinds (resize, IntersectionObserver, etc.)
+ * can be added without breaking existing modifiers.
+ */
+export declare type VegaEAVisibilityEvent = {
+  kind: 'scroll';
+  event?: Event;
+};
+/**
+ * Context supplied to a visibility modifier when it is evaluated.
+ *
+ * @param target - The trigger HTMLElement associated with the appendable.
+ * @param appendableElement - The HTMLElement that is currently shown.
+ * @param showConfig - The active show config (used for gating via `isEnabled`).
+ * @param currentState - Current visibility flags of the appendable element.
+ * @param event - The viewport event that triggered evaluation.
+ */
+export interface VegaEAVisibilityContext {
+  target: HTMLElement;
+  appendableElement: HTMLElement;
+  showConfig: ElementAppenderShowConfig;
+  currentState: {
+    isVisible: boolean;
+  };
+  event: VegaEAVisibilityEvent;
+}
+/**
+ * Action returned by a visibility modifier.
+ *
+ * - `clip-hide` — visually hide the appendable without changing its logical open state.
+ * - `clip-show` — restore visibility that was previously clip-hidden.
+ * - `noop` — no visibility change required.
+ */
+export declare type VegaEAVisibilityAction = 'clip-hide' | 'clip-show' | 'noop';
+/**
+ * Result of evaluating a visibility modifier.
+ */
+export interface VegaEAVisibilityResult {
+  nextAction: VegaEAVisibilityAction;
+}
+/**
+ * A visibility modifier is a viewport-level, cross-cutting concern that runs
+ * alongside the currently-selected `VegaEATriggerStrategy`. Whereas trigger
+ * strategies dispatch user-intent events (click / hover / etc.) to logical
+ * show/hide, visibility modifiers dispatch viewport events (scroll / resize /
+ * etc.) to visual-only clip actions that preserve the popup's logical state.
+ *
+ * @function isEnabled - Gate — decides whether the modifier applies to the current show config.
+ * @function evaluate - Evaluates the context and returns the action to be taken.
+ */
+export interface VegaEAVisibilityModifier {
+  isEnabled(showConfig: ElementAppenderShowConfig): boolean;
+  evaluate(context: VegaEAVisibilityContext): VegaEAVisibilityResult;
+}

package/dist/types/helpers/slimmers/{field-error-controller-silmmer.d.ts → form/field-error-controller-silmmer.d.ts}

@@ -1,4 +1,4 @@
-import { VegaSlimmer } from '../../vega-slimmer/vega-slimmer-core';
+import { VegaSlimmer } from '../../../vega-slimmer/vega-slimmer-core';
 import { FormFieldOptionForSlimmer } from './form-field-controller-slimmer';
 import { FieldErrorUIControllerSlimmer } from './field-error-ui-controller-slimmer';
 /**

package/dist/types/helpers/slimmers/{field-error-ui-controller-slimmer.d.ts → form/field-error-ui-controller-slimmer.d.ts}

@@ -1,5 +1,5 @@
-import { VegaSlimmer } from '../../vega-slimmer/vega-slimmer-core';
-import { EvaluateResult } from '../validator/rules/validation-rule';
+import { VegaSlimmer } from '../../../vega-slimmer/vega-slimmer-core';
+import { EvaluateResult } from '../../validator/rules/validation-rule';
 import { FormFieldMessageTranslatorSlimmer } from './form-field-message-translator';
 /** The `FieldErrorUIControllerSlimmer` class is responsible for displaying error messages and managing the invalid UI state of a form field. */
 export declare class FieldErrorUIControllerSlimmer extends VegaSlimmer {