Types and constants

Type definitions

Since Codex is written in TypeScript, we often make use of special types for things like complex props. Below is documentation of all public types.

ButtonAction

See ButtonActions.

// Allowed values: 'default', 'progressive', 'destructive'
type ButtonAction = typeof ButtonActions[ number ];

ButtonGroupItem

interface ButtonGroupItem {
	/** Button value or unique identifier */
	value: string | number,
	/**
	 * Display label for the button, or null to show no label (for icon-only buttons).
	 * If the label property is missing, the value property is used as the label.
	 */
	label?: string|null,
	/** Icon to display before the label */
	icon?: Icon,
	/** ARIA label for the button. Used for accessibility for icon-only buttons. */
	ariaLabel?: string,
	/** Whether the button is disabled */
	disabled?: boolean
}

ButtonSize

See ButtonSizes.

// Allowed values: 'medium', 'large'
type ButtonSize = typeof ButtonSizes[ number ];

ButtonType

See ButtonTypes.

// Allowed values: 'button', 'submit', 'reset'
type ButtonType = typeof ButtonTypes[ number ];

ButtonWeight

See ButtonWeights.

// Allowed values: 'normal', 'primary', 'quiet'
type ButtonWeight = typeof ButtonWeights[ number ];

ChipInputItem

interface ChipInputItem {
	value: string|number,
	label?: string,
	icon?: Icon
}

ChipValidator

type ChipValidator = ( value: string|number ) => boolean;

DialogAction

interface DialogAction {
	label: string,
	disabled?: boolean
}

FloatingMenuOptions

Options which can be passed to the useFloatingMenu composable. The Placement and OffsetOptions types come from the 3rd-party FloatingUI package.

interface FloatingMenuOptions {
	useAvailableWidth?: boolean,
	placement?: Placement,
	offset?: OffsetOptions
}

HTMLDirection

type HTMLDirection = 'ltr' | 'rtl';

I18nFunction

export type I18nFunction = ( messageKey: I18nMessageKey, ...params: any[] ) => string | null;

Icon

Icons are a special type defined in the @wikimedia/codex-icons package. The Icon type is a union of several different other types.

type Icon = SimpleIcon | IconFlipForRtl | IconVariedByDir | IconVariedByLang;

SimpleIcon

Either an object with a path property or a string.

interface PathIcon {
	/**
	 * An SVG path string, e.g. 'M3 3H1v16h18v-2H3z'
	 */
	path: string
}

/**
 * An SVG string, e.g. '<path d="M3 3H1v16h18v-2H3z"/>'. An SVG string may contain multiple tags,
 * e.g. '<circle x="..." y="..." r="..."/><path d="..."/>'. SVG strings should not contain an
 * <?xml ...?> tag or a wrapping <svg> tag.
 */
type SvgIcon = string;

type SimpleIcon = PathIcon | SvgIcon;

IconSize

See IconSizes.

// Allowed values: 'medium', 'small', 'x-small'
type IconSize = typeof IconSizes[ number ];

IconFlipForRtl

An icon with a single SVG that should flip horizontally in RTL mode.

interface IconFlipForRtl {
	/** LTR version of the icon. */
	ltr: SimpleIcon,
	/** Indicates that the icon should be flipped via CSS in RTL mode. */
	shouldFlip: true,
	/**
	 * Language codes that are exceptions to the above property (e.g. the help
	 * icon should flip in RTL mode, but not for Hebrew or Yiddish).
	 */
	shouldFlipExceptions?: string[]
}

IconVariedByDir

An icon that varies per text direction (but can't only be flipped).

interface IconVariedByDir {
	/** Icon for RTL */
	rtl: SimpleIcon,
	/** Icon for LTR */
	ltr: SimpleIcon
}

IconVariedByLang

An icon that varies per language.

interface IconVariedByLang {
	/** HTMLElement.lang code with corresponding icon. */
	langCodeMap: Record<string, SimpleIcon | IconFlipForRtl>,
	/** The default icon. */
	default: SimpleIcon | IconFlipForRtl
}

ImageAspectRatio

See ImageAspectRatios.

// Allowed values: '16-9','3-2','4-3','1-1','3-4','2-3'
export type ImageAspectRatio = typeof ImageAspectRatios[ number ];

MenuConfig

interface MenuConfig {
	/** The maximum number of items visible in an expanded menu. */
	visibleItemLimit?: number | null,
	/** Whether to show thumbnails (or placeholder). */
	showThumbnail?: boolean,
	/** Whether to bold menu item labels. */
	boldLabel?: boolean,
	/** Whether to hide description text overflow via an ellipsis. */
	hideDescriptionOverflow?: boolean
}

MenuGroupData

interface MenuGroupData {
	/** Required label for the group. */
	label: string,
	/** The menu items that appear in this group. */
	items: MenuItemData[],
	/** Optional description for the group. */
	description?: string,
	/** Optional icon for the group. */
	icon?: Icon,
	/** Whether to visually hide the label. */
	hideLabel?: boolean
}

MenuItemValue

type MenuItemValue = string | number;

MenuItemData

interface MenuItemData {
	/** Item value or unique identifier. */
	value: MenuItemValue,
	/** Display label for the menu item. */
	label?: string,
	/** Text to be appended to the result's label, e.g. text matching a search query. */
	match?: string,
	description?: string | null,
	/** Lang attributes of text properties. */
	language?: MenuItemLanguageData,
	icon?: Icon,
	thumbnail?: Thumbnail | null,
	/** If URL is included, menu item will be wrapped in an anchor element. */
	url?: string,
	disabled?: boolean
}

MenuItemDataWithId

interface MenuItemDataWithId extends MenuItemData {
	id: string
}

MenuButtonItemData

interface MenuButtonItemData extends MenuItemData {
	// Only the "destructive" action is allowed for now
	action?: typeof ButtonActions[ 2 ]
}

MenuItemLanguageData

interface MenuItemLanguageData {
	/** lang attribute of the label. */
	label?: string,
	/** lang attribute of the match. */
	match?: string,
	/** lang attribute of the description. */
	description?: string
}

MenuState

See MenuStates.

// Allowed values: 'selected', 'highlighted', 'active'
type MenuState = typeof MenuStates[ number ];

PrimaryDialogAction

See DialogAction.

interface PrimaryDialogAction extends DialogAction {
	actionType: 'progressive' | 'destructive'
}

SearchResult

interface SearchResult extends MenuItemData {
	/** Result link. */
	url: string
}

SearchResultClickEvent

interface SearchResultClickEvent {
	/** Search result that was clicked. */
	searchResult: SearchResult|null,
	/** Index of the search result within the array of results. */
	index: number,
	/** Number of search results. */
	numberOfResults: number
}

StatusType

See StatusTypes.

// Allowed values: 'notice', 'warning', 'error', 'success'
type StatusType = typeof StatusTypes[ number ];

TableSort

type TableSort<K extends string = string> = { [P in K]?: TableSortOption };

TableSortOption

type TableSortOption = 'none' | 'asc' | 'desc';

TableColumn

interface TableColumn {
	id: string,
	label?: string,
	// Allowed values: 'start' (default), 'center', 'end', 'number'
	textAlign?: typeof TableTextAlignments[ number ]
	// Value with units.
	width?: string,
	// Value with units.
	minWidth?: string,
	allowSort?: boolean
}

TableRow

type TableRow = Record<string, any>;

TableRowWithIdentifier

When both sorting and row selection are enabled, an extra unique idenfitier is needed for each row. Check TableRowIdentifier.

interface TableRowWithIdentifier extends TableRow {
	[TableRowIdentifier]: string
}

TablePaginationPosition

type TablePaginationPosition = 'top' | 'bottom' | 'both';

TablePaginationSizeOption

Like MenuItemData, but value must be a number.

export interface TablePaginationSizeOption extends MenuItemData {
	value: number;
}

TextInputType

See TextInputTypes.

// Allowed values: 'text', 'search', 'number', 'email', 'password', 'tel', 'url', 'week', 'month', 'date', 'datetime-local', 'time'
type TextInputType = typeof TextInputTypes[ number ];

ValidationMessages

interface ValidationMessages {
	warning?: string,
	error?: string,
	success?: string
}

ValidationStatusType

See ValidationStatusTypes.

// Allowed values: 'default', 'error'
type ValidationStatusType = typeof ValidationStatusTypes[ number ];

Thumbnail

interface Thumbnail {
	url: string;
}

Constants

ButtonActions

const ButtonActions = [
	'default',
	'progressive',
	'destructive'
];

ButtonSizes

const ButtonSizes = [
	'medium',
	'large'
];

ButtonTypes

const ButtonTypes = [
	'button',
	'submit',
	'reset'
];

ButtonWeights

const ButtonWeights = [
	'normal',
	'primary',
	'quiet'
];

IconSizes

const IconSizes = [
	'x-small',
	'small',
	'medium'
];

ImageAspectRatios

const ImageAspectRatios = [
    '16-9',
    '3-2',
    '4-3',
    '1-1',
    '3-4',
    '2-3'
];

MenuStates

const MenuStates = [
	'selected',
	'highlighted',
	'active'
];

ObjectFitOptions

const ObjectFitOptions = [
    'fill',
    'contain',
    'cover',
    'none',
    'scale-down'
];

ObjectPositions

const ObjectPositions = [
    'top',
    'bottom',
    'left',
    'right',
    'center'
];

StatusTypes

const StatusTypes = [
	'notice',
	'warning',
	'error',
	'success'
];

TableRowIdentifier

Special property of a table row for a unique identifier. Required when both sorting and row selection are enabled.

const TableRowIdentifier = Symbol( 'CdxTableRowIdentifier' );

TableTextAlignments

const TableTextAlignments = [
	'start',
	'center',
	'end',
	// Numbers should be aligned to the right in all reading directionalities.
	'number'
];

TextInputTypes

const TextInputTypes = [
	'text',
	'search',
	'number',
	'email',
	'password',
	'tel',
	'url',
	'week',
	'month',
	'date',
	'datetime-local',
	'time'
];

ValidationStatusTypes

const ValidationStatusTypes = [
	'default',
	'warning',
	'error',
	'success'
];

DebounceInterval

Default length of delay for debouncing, in milliseconds.

const DebounceInterval = 120;

PendingDelay

Default length of delay for displaying pending state, in milliseconds.

const PendingDelay = 500;

NoInvertClass

A utility class to indicate that certain elements (like thumbnail images) should be excluded from any invert-based "dark mode" theming applied downstream (by the DarkMode extension, for example). No styles are applied to this class within Codex.

const NoInvertClass = 'cdx-no-invert';

Any user of Codex applying an invert-based color theme can use this class to exclude certain elements from color inversion so that they appear in their natural colors.