vira/dist/elements/vira-tabs.element.d.ts

A simple and highly versatile design system using element-vir.

import { type PartialWithUndefined } from '@augment-vir/common';
import { type FullSpaRoute, type GenericTreePaths, type SpaRouter } from 'spa-router-vir';
import { type ViraIconSvg } from '../icons/icon-svg.js';
import { ViraColorVariant } from '../styles/form-variants.js';
import { ViraThemeColorName } from '../styles/vira-color-theme-object.js';
import { type HorizontalAnchor, type PopUpOffset } from './pop-up/vira-pop-up-trigger.element.js';
/**
 * Controls which edge of the tab the selection indicator bar appears on.
 *
 * @category Internal
 */
export declare enum ViraTabsBarDirection {
    Top = "top",
    Bottom = "bottom",
    Left = "left",
    Right = "right"
}
/**
 * Controls whether tab icons render above/below or beside the label text.
 *
 * @category Internal
 */
export declare enum ViraTabsIconLayout {
    /** Icon renders above (or below) the label. */
    Vertical = "vertical",
    /** Icon renders beside the label. */
    Horizontal = "horizontal"
}
/**
 * A single tab entry for {@link ViraTabs}.
 *
 * @category Internal
 */
export type ViraTab = {
    label: string;
    paths: GenericTreePaths;
} & PartialWithUndefined<{
    icon: Readonly<ViraIconSvg>;
    isHidden: boolean;
    isDisabled: boolean;
    /**
     * When true, the tab is only considered selected when the current route's paths exactly equal
     * `paths.fullPaths`. By default a tab is considered selected when its paths are a prefix of the
     * current route.
     */
    exactMatch: boolean;
    /**
     * Optional cluster label. Consecutive tabs sharing the same `group` string render together
     * under that label, separated from other clusters by an inset vertical divider. Tabs with no
     * `group` render standalone (no label, no divider). Grouping only affects rendering when at
     * least one tab has a `group`.
     */
    group: string;
}>;
/**
 * Groups a flat list of tabs into clusters. Consecutive tabs sharing the same `group` string are
 * merged into a single cluster; ungrouped tabs (and tabs whose `group` differs from their
 * predecessor) each start a new cluster.
 *
 * @category Internal
 */
export declare function buildClusters(tabList: ReadonlyArray<Readonly<ViraTab>>): {
    group: string | undefined;
    tabs: ReadonlyArray<Readonly<ViraTab>>;
}[];
/**
 * A tab bar element that renders an array of tabs with an animated selection indicator.
 *
 * @category Elements
 */
export declare const ViraTabs: import("element-vir").DeclarativeElementDefinition<"vira-tabs", {
    tabs: ReadonlyArray<Readonly<ViraTab>>;
    router: Pick<SpaRouter<any, any, any>, "createRouteUrl" | "setRouteOnDirectNavigation">;
    currentRoute: Readonly<FullSpaRoute>;
} & PartialWithUndefined<{
    /**
     * Which edge of the tab the selection bar appears on.
     *
     * @default ViraTabsBarDirection.Bottom
     */
    barDirection: ViraTabsBarDirection;
    /**
     * Color variant for the tab selection indicator and active tab text. Accepts any
     * {@link ViraColorVariant} or a {@link ViraThemeColorName} (e.g.,
     * `ViraThemeColorName.blue`).
     *
     * @default ViraColorVariant.Plain
     */
    color: ViraColorVariant | ViraThemeColorName;
    /**
     * Layout direction for icons relative to their label text.
     *
     * @default ViraTabsIconLayout.Vertical
     */
    iconLayout: ViraTabsIconLayout;
    /**
     * Horizontal anchor for the dropdown menu. Only used when tabs overflow into a dropdown.
     *
     * @default HorizontalAnchor.Left
     */
    menuHorizontalAnchor: HorizontalAnchor;
    /** Whether the dropdown trigger is disabled. Only used when tabs overflow into a dropdown. */
    menuIsDisabled: boolean;
    /** Offset for the dropdown pop-up. Only used when tabs overflow into a dropdown. */
    menuPopUpOffset: Readonly<PopUpOffset>;
    /**
     * Text shown on the overflow "more" trigger when the selected tab is _not_ collapsed into
     * the menu. When the selected tab _is_ collapsed, the trigger shows that tab's label (with
     * a checkmark) instead. Set this to a localized string; it defaults to `'More'`.
     *
     * @default 'More'
     */
    overflowLabel: string;
    /** When true, tabs and their container expand to fill all available horizontal space. */
    shouldFillWidth: boolean;
}>, {
    /** How many of the visible tabs are collapsed into the overflow "more" menu. */
    overflowCount: number;
    /** A callback to remove all internal observers. */
    cleanupObserver: undefined | (() => void);
}, {
    /** Fires when a tab is clicked with the corresponding tab entry. */
    tabSelect: import("element-vir").DefineEvent<Readonly<ViraTab>>;
}, "vira-tabs-bar-top" | "vira-tabs-bar-bottom" | "vira-tabs-bar-left" | "vira-tabs-bar-right" | "vira-tabs-color-red" | "vira-tabs-color-yellow" | "vira-tabs-color-green" | "vira-tabs-color-blue" | "vira-tabs-color-brand" | "vira-tabs-color-purple" | "vira-tabs-color-plain" | "vira-tabs-color-neutral" | "vira-tabs-color-teal" | "vira-tabs-color-pink" | "vira-tabs-color-grey" | "vira-tabs-icon-layout-vertical" | "vira-tabs-icon-layout-horizontal" | "vira-tabs-fill-width", "vira-tabs-active-color" | "vira-tabs-active-hover-color" | "vira-tabs-inactive-color" | "vira-tabs-inactive-hover-color" | "vira-tabs-bar-thickness", readonly [], readonly []>;