@vireocodedev/ui 0.2.0 → 0.2.1

package/dist/capabilities/application-preferences/components/layout/VireoPreferencePanel/VireoPreferencePanel.styled.js

@@ -0,0 +1,140 @@
+import { Accordion, AccordionDetails, AccordionSummary, Box, Card, Typography, } from "@mui/material";
+import { styled } from "@mui/material/styles";
+import { VIREO_PREFERENCE_PANEL_NAME } from "./VireoPreferencePanel.identity.js";
+export const VireoPreferencePanelRoot = styled(Card, {
+    name: VIREO_PREFERENCE_PANEL_NAME,
+    slot: "Root",
+    overridesResolver: (_props, styles) => styles.root,
+})(({ theme, ownerState }) => ({
+    overflow: "clip",
+    borderRadius: ownerState.isCompact ? 0 : theme.shape.borderRadius,
+    backgroundColor: theme.palette.background.default,
+}));
+export const VireoPreferencePanelSection = styled(Accordion, {
+    name: VIREO_PREFERENCE_PANEL_NAME,
+    slot: "Section",
+    overridesResolver: (_props, styles) => styles.section,
+})(({ theme }) => ({
+    margin: 0,
+    borderRadius: 0,
+    backgroundColor: theme.palette.background.paper,
+    backgroundImage: "none",
+    boxShadow: "none",
+    "&::before": { display: "none" },
+    "& + &": { borderTop: `1px solid ${theme.palette.divider}` },
+    "&.Mui-expanded": { margin: 0 },
+}));
+export const VireoPreferencePanelSectionHeader = styled(Box, {
+    name: VIREO_PREFERENCE_PANEL_NAME,
+    slot: "SectionHeader",
+    overridesResolver: (_props, styles) => styles.sectionHeader,
+})(({ theme, ownerState }) => ({
+    position: ownerState.stickySectionHeaders ? "sticky" : "relative",
+    top: ownerState.stickySectionHeaders ? 0 : undefined,
+    zIndex: ownerState.stickySectionHeaders ? theme.zIndex.appBar - 1 : undefined,
+    display: "flex",
+    alignItems: "center",
+    minWidth: 0,
+    backgroundColor: theme.palette.background.paper,
+    borderBottom: `1px solid ${theme.palette.divider}`,
+}));
+export const VireoPreferencePanelSectionSummary = styled(AccordionSummary, {
+    name: VIREO_PREFERENCE_PANEL_NAME,
+    slot: "SectionSummary",
+    overridesResolver: (_props, styles) => styles.sectionSummary,
+})(({ theme, ownerState }) => ({
+    flex: "1 1 auto",
+    minWidth: 0,
+    minHeight: ownerState.isCompact ? 48 : 56,
+    paddingInline: ownerState.isCompact ? theme.spacing(2) : theme.spacing(3),
+    "&.Mui-expanded": { minHeight: ownerState.isCompact ? 48 : 56 },
+    "& .MuiAccordionSummary-content": {
+        marginBlock: theme.spacing(1.5),
+        minWidth: 0,
+        fontWeight: theme.typography.fontWeightBold,
+    },
+    "& .MuiAccordionSummary-content.Mui-expanded": { marginBlock: theme.spacing(1.5) },
+}));
+export const VireoPreferencePanelSectionAction = styled(Box, {
+    name: VIREO_PREFERENCE_PANEL_NAME,
+    slot: "SectionAction",
+    overridesResolver: (_props, styles) => styles.sectionAction,
+})(({ theme, ownerState }) => ({
+    flex: "0 0 auto",
+    paddingInlineEnd: ownerState.isCompact ? theme.spacing(1) : theme.spacing(2),
+}));
+export const VireoPreferencePanelSectionDetails = styled(AccordionDetails, {
+    name: VIREO_PREFERENCE_PANEL_NAME,
+    slot: "SectionDetails",
+    overridesResolver: (_props, styles) => styles.sectionDetails,
+})({ padding: 0 });
+export const VireoPreferencePanelItem = styled(Box, {
+    name: VIREO_PREFERENCE_PANEL_NAME,
+    slot: "Item",
+    overridesResolver: (_props, styles) => styles.item,
+})(({ theme, ownerState }) => ({
+    display: "grid",
+    gridTemplateColumns: ownerState.isCompact
+        ? "24px minmax(0, 1fr)"
+        : `24px minmax(0, 1fr) minmax(0, ${typeof ownerState.controlWidth === "number" ? `${ownerState.controlWidth}px` : ownerState.controlWidth})`,
+    alignItems: ownerState.isCompact ? "start" : "center",
+    columnGap: theme.spacing(2),
+    rowGap: theme.spacing(1.5),
+    minWidth: 0,
+    padding: ownerState.isCompact ? theme.spacing(2) : theme.spacing(2.5, 3),
+    backgroundColor: theme.palette.background.default,
+    transition: theme.transitions.create("background-color", { duration: theme.transitions.duration.shortest }),
+    "& + &": { borderTop: `1px solid ${theme.palette.divider}` },
+    "&:hover": { backgroundColor: theme.palette.action.hover },
+}));
+export const VireoPreferencePanelItemIcon = styled(Box, {
+    name: VIREO_PREFERENCE_PANEL_NAME,
+    slot: "ItemIcon",
+    overridesResolver: (_props, styles) => styles.itemIcon,
+})(({ theme }) => ({
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    minWidth: 24,
+    minHeight: 24,
+    color: theme.palette.text.secondary,
+}));
+export const VireoPreferencePanelItemContent = styled(Box, {
+    name: VIREO_PREFERENCE_PANEL_NAME,
+    slot: "ItemContent",
+    overridesResolver: (_props, styles) => styles.itemContent,
+})({ minWidth: 0 });
+export const VireoPreferencePanelItemTitle = styled(Typography, {
+    name: VIREO_PREFERENCE_PANEL_NAME,
+    slot: "ItemTitle",
+    overridesResolver: (_props, styles) => styles.itemTitle,
+})(({ theme }) => ({
+    color: theme.palette.text.primary,
+    fontWeight: theme.typography.fontWeightBold,
+}));
+export const VireoPreferencePanelItemDescription = styled(Typography, {
+    name: VIREO_PREFERENCE_PANEL_NAME,
+    slot: "ItemDescription",
+    overridesResolver: (_props, styles) => styles.itemDescription,
+})(({ theme }) => ({
+    marginTop: theme.spacing(0.5),
+    color: theme.palette.text.secondary,
+}));
+export const VireoPreferencePanelItemControl = styled(Box, {
+    name: VIREO_PREFERENCE_PANEL_NAME,
+    slot: "ItemControl",
+    overridesResolver: (_props, styles) => styles.itemControl,
+})(({ ownerState }) => ({
+    gridColumn: ownerState.isCompact ? "2" : "3",
+    width: "100%",
+    minWidth: 0,
+}));
+export const VireoPreferencePanelEmptyState = styled(Box, {
+    name: VIREO_PREFERENCE_PANEL_NAME,
+    slot: "EmptyState",
+    overridesResolver: (_props, styles) => styles.emptyState,
+})(({ theme }) => ({
+    padding: theme.spacing(4),
+    color: theme.palette.text.secondary,
+    textAlign: "center",
+}));

package/dist/capabilities/application-preferences/components/layout/VireoPreferencePanel/VireoPreferencePanel.types.d.ts

@@ -0,0 +1,121 @@
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../core/public.js";
+import type { Accordion, AccordionDetails, AccordionSummary, Box, Card, CardProps, Typography } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import { type VireoPreferencePanelClasses, type VireoPreferencePanelClassKey } from "./VireoPreferencePanel.classes.js";
+import type { VIREO_PREFERENCE_PANEL_NAME, VireoPreferencePanelSlotName } from "./VireoPreferencePanel.identity.js";
+export type VireoPreferenceItemDefinition = {
+    id: string;
+    title: string;
+    description?: string;
+    searchKeywords?: readonly string[];
+    icon?: React.ReactNode;
+    control: React.ReactNode;
+};
+export type VireoPreferenceSectionDefinition = {
+    id: string;
+    title: string;
+    action?: React.ReactNode;
+    items: readonly VireoPreferenceItemDefinition[];
+};
+export type VireoPreferencePanelOwnerState = {
+    controlWidth: number | string;
+    hasVisibleItems: boolean;
+    isCompact: boolean;
+    isFiltering: boolean;
+    stickySectionHeaders: boolean;
+};
+export interface VireoPreferencePanelRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoPreferencePanelSectionSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoPreferencePanelSectionHeaderSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoPreferencePanelSectionSummarySlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoPreferencePanelSectionActionSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoPreferencePanelSectionDetailsSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoPreferencePanelItemSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoPreferencePanelItemIconSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoPreferencePanelItemContentSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoPreferencePanelItemTitleSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoPreferencePanelItemDescriptionSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoPreferencePanelItemControlSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoPreferencePanelEmptyStateSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+/** Replaceable semantic regions exposed by {@link VireoPreferencePanel}. */
+export type VireoPreferencePanelSlots = {
+    [TSlotName in VireoPreferencePanelSlotName]: React.ElementType;
+};
+/** Slot props exposed by {@link VireoPreferencePanel}. */
+export type VireoPreferencePanelSlotsAndSlotProps = CreateSlotsAndSlotProps<VireoPreferencePanelSlots, {
+    /** @default Card */
+    root: SlotProps<typeof Card, VireoPreferencePanelRootSlotPropsOverrides, VireoPreferencePanelOwnerState>;
+    /** @default Accordion */
+    section: SlotProps<typeof Accordion, VireoPreferencePanelSectionSlotPropsOverrides, VireoPreferencePanelOwnerState>;
+    /** @default Box */
+    sectionHeader: SlotProps<typeof Box, VireoPreferencePanelSectionHeaderSlotPropsOverrides, VireoPreferencePanelOwnerState>;
+    /** @default AccordionSummary */
+    sectionSummary: SlotProps<typeof AccordionSummary, VireoPreferencePanelSectionSummarySlotPropsOverrides, VireoPreferencePanelOwnerState>;
+    /** @default Box */
+    sectionAction: SlotProps<typeof Box, VireoPreferencePanelSectionActionSlotPropsOverrides, VireoPreferencePanelOwnerState>;
+    /** @default AccordionDetails */
+    sectionDetails: SlotProps<typeof AccordionDetails, VireoPreferencePanelSectionDetailsSlotPropsOverrides, VireoPreferencePanelOwnerState>;
+    /** @default Box */
+    item: SlotProps<typeof Box, VireoPreferencePanelItemSlotPropsOverrides, VireoPreferencePanelOwnerState>;
+    /** @default Box */
+    itemIcon: SlotProps<typeof Box, VireoPreferencePanelItemIconSlotPropsOverrides, VireoPreferencePanelOwnerState>;
+    /** @default Box */
+    itemContent: SlotProps<typeof Box, VireoPreferencePanelItemContentSlotPropsOverrides, VireoPreferencePanelOwnerState>;
+    /** @default Typography */
+    itemTitle: SlotProps<typeof Typography, VireoPreferencePanelItemTitleSlotPropsOverrides, VireoPreferencePanelOwnerState>;
+    /** @default Typography */
+    itemDescription: SlotProps<typeof Typography, VireoPreferencePanelItemDescriptionSlotPropsOverrides, VireoPreferencePanelOwnerState>;
+    /** @default Box */
+    itemControl: SlotProps<typeof Box, VireoPreferencePanelItemControlSlotPropsOverrides, VireoPreferencePanelOwnerState>;
+    /** @default Box */
+    emptyState: SlotProps<typeof Box, VireoPreferencePanelEmptyStateSlotPropsOverrides, VireoPreferencePanelOwnerState>;
+}>;
+/** Props owned by {@link VireoPreferencePanel}. */
+export type VireoPreferencePanelOwnProps = VireoPreferencePanelSlotsAndSlotProps & {
+    sections: readonly VireoPreferenceSectionDefinition[];
+    emptyState: React.ReactNode;
+    searchQuery?: string;
+    expandedSectionIds?: readonly string[];
+    defaultExpandedSectionIds?: readonly string[];
+    onExpandedSectionIdsChange?: (ids: readonly string[]) => void;
+    controlWidth?: number | string;
+    stickySectionHeaders?: boolean;
+    /** Override or extend the utility classes applied to each slot. */
+    classes?: Partial<VireoPreferencePanelClasses>;
+};
+/** Props VireoPreferencePanel inherits from its default root after excluding component-owned props. */
+export type VireoPreferencePanelInheritedProps = Omit<CardProps, "children" | "component">;
+/** Props accepted by {@link VireoPreferencePanel}. */
+export type VireoPreferencePanelProps = VireoPreferencePanelOwnProps & VireoPreferencePanelInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_PREFERENCE_PANEL_NAME]?: VireoThemeComponent<VireoPreferencePanelProps, VireoPreferencePanelClassKey, VireoPreferencePanelOwnerState, Theme>;
+    }
+}

package/dist/capabilities/application-preferences/components/layout/VireoPreferencePanel/VireoPreferencePanel.types.js

@@ -0,0 +1 @@
+export {};

package/dist/capabilities/application-preferences/components/layout/VireoPreferencePanel/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./VireoPreferencePanel.js";
+export * from "./VireoPreferencePanel.classes.js";
+export * from "./VireoPreferencePanel.types.js";

package/dist/capabilities/application-preferences/components/layout/VireoPreferencePanel/index.js

@@ -0,0 +1,3 @@
+export * from "./VireoPreferencePanel.js";
+export * from "./VireoPreferencePanel.classes.js";
+export * from "./VireoPreferencePanel.types.js";

package/dist/capabilities/application-preferences/public.d.ts

@@ -0,0 +1 @@
+export * from "./components/layout/VireoPreferencePanel/index.js";

package/dist/capabilities/application-preferences/public.js

@@ -0,0 +1 @@
+export * from "./components/layout/VireoPreferencePanel/index.js";

package/dist/capabilities/country/components/data-display/VireoCountryFlag/VireoCountryFlag.classes.d.ts

@@ -0,0 +1,9 @@
+import { type VireoCountryFlagSlotName } from "./VireoCountryFlag.identity.js";
+/** Utility classes available to VireoCountryFlag. */
+export type VireoCountryFlagClasses = Record<VireoCountryFlagSlotName | "known" | "unknown" | "tooltipEnabled", string>;
+/** Valid keys for VireoCountryFlag utility classes and theme style overrides. */
+export type VireoCountryFlagClassKey = keyof VireoCountryFlagClasses;
+/** Returns the generated utility class name for a VireoCountryFlag slot or state. */
+export declare function getVireoCountryFlagUtilityClass(slot: string): string;
+/** Generated utility class names keyed by each public VireoCountryFlag class key. */
+export declare const vireoCountryFlagClasses: VireoCountryFlagClasses;

package/dist/capabilities/country/components/data-display/VireoCountryFlag/VireoCountryFlag.classes.js

@@ -0,0 +1,13 @@
+import { generateUtilityClass, generateUtilityClasses } from "@mui/material";
+import { VIREO_COUNTRY_FLAG_NAME, VIREO_COUNTRY_FLAG_SLOTS, } from "./VireoCountryFlag.identity.js";
+/** Returns the generated utility class name for a VireoCountryFlag slot or state. */
+export function getVireoCountryFlagUtilityClass(slot) {
+    return generateUtilityClass(VIREO_COUNTRY_FLAG_NAME, slot);
+}
+/** Generated utility class names keyed by each public VireoCountryFlag class key. */
+export const vireoCountryFlagClasses = generateUtilityClasses(VIREO_COUNTRY_FLAG_NAME, [
+    ...VIREO_COUNTRY_FLAG_SLOTS,
+    "known",
+    "unknown",
+    "tooltipEnabled",
+]);

package/dist/capabilities/country/components/data-display/VireoCountryFlag/VireoCountryFlag.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+import type { VireoCountryFlagProps } from "./VireoCountryFlag.types.js";
+/**
+ * Renders a country-flag-icons registry identifier through a consistent, accessible 3:2 flag surface.
+ */
+export declare const VireoCountryFlag: React.ForwardRefExoticComponent<Omit<VireoCountryFlagProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/capabilities/country/components/data-display/VireoCountryFlag/VireoCountryFlag.identity.d.ts

@@ -0,0 +1,6 @@
+/** Stable component name shared by every VireoCountryFlag integration point. */
+export declare const VIREO_COUNTRY_FLAG_NAME = "VireoCountryFlag";
+/** Canonical public slots exposed by VireoCountryFlag, in rendered DOM order. */
+export declare const VIREO_COUNTRY_FLAG_SLOTS: readonly ["root", "flag", "tooltip"];
+/** Public slot names exposed by VireoCountryFlag. */
+export type VireoCountryFlagSlotName = (typeof VIREO_COUNTRY_FLAG_SLOTS)[number];

package/dist/capabilities/country/components/data-display/VireoCountryFlag/VireoCountryFlag.identity.js

@@ -0,0 +1,4 @@
+/** Stable component name shared by every VireoCountryFlag integration point. */
+export const VIREO_COUNTRY_FLAG_NAME = "VireoCountryFlag";
+/** Canonical public slots exposed by VireoCountryFlag, in rendered DOM order. */
+export const VIREO_COUNTRY_FLAG_SLOTS = ["root", "flag", "tooltip"];

package/dist/capabilities/country/components/data-display/VireoCountryFlag/VireoCountryFlag.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { isCountryCode } from "../../../../../capabilities/country/models/countryCode.models.js";
+import { getCountryName } from "../../../../../capabilities/country/utils/countryNames.utils.js";
+import { UnknownCountryFlag } from "../../../../../capabilities/country/components/data-display/VireoCountryFlag/internal/components/UnknownCountryFlag.js";
+import { joinClassNames, mergeSx, resolveSlotProps } from "../../../../../core/public.js";
+import { Tooltip, unstable_composeClasses as composeClasses } from "@mui/material";
+import { useThemeProps } from "@mui/material/styles";
+import { useForkRef } from "@mui/material/utils";
+import * as CountryFlags from "country-flag-icons/react/3x2";
+import React from "react";
+import { getVireoCountryFlagUtilityClass } from "./VireoCountryFlag.classes.js";
+import { VIREO_COUNTRY_FLAG_NAME } from "./VireoCountryFlag.identity.js";
+import { VireoCountryFlagFlag, VireoCountryFlagRoot } from "./VireoCountryFlag.styled.js";
+function getFlagComponent(countryCode) {
+    if (!isCountryCode(countryCode))
+        return undefined;
+    return CountryFlags[countryCode.replaceAll("-", "_")];
+}
+function useUtilityClasses(ownerState, classes) {
+    return composeClasses({
+        root: ["root", ownerState.known ? "known" : "unknown", ownerState.enableTooltip && "tooltipEnabled"],
+        flag: ["flag"],
+        tooltip: ["tooltip"],
+    }, getVireoCountryFlagUtilityClass, classes);
+}
+function getTooltipLabel(countryCode, known, label) {
+    if (label)
+        return label;
+    if (known)
+        return getCountryName(countryCode, "en");
+    return countryCode ? `Unknown country (${countryCode})` : "Unknown country";
+}
+/**
+ * Renders a country-flag-icons registry identifier through a consistent, accessible 3:2 flag surface.
+ */
+export const VireoCountryFlag = React.forwardRef(function VireoCountryFlag(inProps, forwardedRef) {
+    const props = useThemeProps({ props: inProps, name: VIREO_COUNTRY_FLAG_NAME });
+    const { className, classes: classesProp, countryCode, enableTooltip = false, label, slotProps = {}, slots = {}, style, sx, width = 24, ...other } = props;
+    const FlagComponent = getFlagComponent(countryCode);
+    const known = Boolean(FlagComponent);
+    const ownerState = { countryCode, enableTooltip, known, width };
+    const classes = useUtilityClasses(ownerState, classesProp);
+    const tooltipLabel = getTooltipLabel(countryCode, known, label);
+    const accessibleLabel = label || (enableTooltip ? tooltipLabel : undefined);
+    const resolvedRootSlotProps = resolveSlotProps(slotProps.root, ownerState);
+    const rootSlotClassName = resolvedRootSlotProps.className;
+    const rootSlotRef = resolvedRootSlotProps.ref;
+    const rootSlotStyle = resolvedRootSlotProps.style;
+    const rootSlotSx = resolvedRootSlotProps.sx;
+    const rootSlotOther = { ...resolvedRootSlotProps };
+    delete rootSlotOther["aria-hidden"];
+    delete rootSlotOther["aria-label"];
+    delete rootSlotOther.children;
+    delete rootSlotOther.className;
+    delete rootSlotOther.dangerouslySetInnerHTML;
+    delete rootSlotOther.ref;
+    delete rootSlotOther.role;
+    delete rootSlotOther.style;
+    delete rootSlotOther.sx;
+    delete rootSlotOther.title;
+    const rootRef = useForkRef(forwardedRef, rootSlotRef);
+    const resolvedFlagSlotProps = resolveSlotProps(slotProps.flag, ownerState);
+    const flagSlotClassName = resolvedFlagSlotProps.className;
+    const flagSlotRef = resolvedFlagSlotProps.ref;
+    const flagSlotStyle = resolvedFlagSlotProps.style;
+    const flagSlotOther = { ...resolvedFlagSlotProps };
+    delete flagSlotOther["aria-hidden"];
+    delete flagSlotOther.children;
+    delete flagSlotOther.className;
+    delete flagSlotOther.focusable;
+    delete flagSlotOther.height;
+    delete flagSlotOther.ref;
+    delete flagSlotOther.style;
+    delete flagSlotOther.viewBox;
+    delete flagSlotOther.width;
+    const flag = (_jsx(VireoCountryFlagRoot, { ...other, ...rootSlotOther, as: slots.root ?? "span", ref: rootRef, ownerState: ownerState, className: joinClassNames(classes.root, className, rootSlotClassName), style: { ...style, ...rootSlotStyle }, sx: mergeSx(sx, rootSlotSx), role: accessibleLabel ? "img" : undefined, "aria-label": accessibleLabel, "aria-hidden": accessibleLabel ? undefined : true, children: _jsx(VireoCountryFlagFlag, { ...flagSlotOther, as: slots.flag ?? FlagComponent ?? UnknownCountryFlag, ref: flagSlotRef, ownerState: ownerState, className: joinClassNames(classes.flag, flagSlotClassName), style: flagSlotStyle, width: "24", height: "16", "aria-hidden": "true", focusable: "false" }) }));
+    if (!enableTooltip)
+        return flag;
+    const TooltipSlot = slots.tooltip ?? Tooltip;
+    const resolvedTooltipSlotProps = resolveSlotProps(slotProps.tooltip, ownerState);
+    const tooltipSlotClasses = resolvedTooltipSlotProps.classes;
+    const disableInteractive = resolvedTooltipSlotProps.disableInteractive ?? true;
+    const placement = resolvedTooltipSlotProps.placement ?? "top";
+    const tooltipSlotOther = { ...resolvedTooltipSlotProps };
+    delete tooltipSlotOther.children;
+    delete tooltipSlotOther.classes;
+    delete tooltipSlotOther.disableInteractive;
+    delete tooltipSlotOther.placement;
+    delete tooltipSlotOther.title;
+    return (_jsx(TooltipSlot, { ...tooltipSlotOther, title: tooltipLabel, placement: placement, disableInteractive: disableInteractive, classes: { ...tooltipSlotClasses, tooltip: joinClassNames(classes.tooltip, tooltipSlotClasses?.tooltip) }, children: flag }));
+});
+VireoCountryFlag.displayName = VIREO_COUNTRY_FLAG_NAME;

package/dist/capabilities/country/components/data-display/VireoCountryFlag/VireoCountryFlag.styled.d.ts

@@ -0,0 +1,11 @@
+import { type StyledSlotComponent } from "../../../../../core/public.js";
+import { type BoxProps, type SxProps, type Theme } from "@mui/material";
+import type React from "react";
+import type { VireoCountryFlagOwnerState } from "./VireoCountryFlag.types.js";
+type VireoCountryFlagStyledSlotComponent<TProps extends object> = StyledSlotComponent<TProps, VireoCountryFlagOwnerState>;
+type VireoCountryFlagFlagProps = React.SVGProps<SVGSVGElement> & {
+    sx?: SxProps<Theme>;
+};
+export declare const VireoCountryFlagRoot: VireoCountryFlagStyledSlotComponent<BoxProps>;
+export declare const VireoCountryFlagFlag: VireoCountryFlagStyledSlotComponent<VireoCountryFlagFlagProps>;
+export {};

package/dist/capabilities/country/components/data-display/VireoCountryFlag/VireoCountryFlag.styled.js

@@ -0,0 +1,33 @@
+import { Box } from "@mui/material";
+import { styled } from "@mui/material/styles";
+import { VIREO_COUNTRY_FLAG_NAME } from "./VireoCountryFlag.identity.js";
+export const VireoCountryFlagRoot = styled(Box, {
+    name: VIREO_COUNTRY_FLAG_NAME,
+    slot: "Root",
+    overridesResolver: ({ ownerState }, styles) => [
+        styles.root,
+        ownerState.known ? styles.known : styles.unknown,
+        ownerState.enableTooltip && styles.tooltipEnabled,
+    ],
+})(({ ownerState, theme }) => ({
+    "--VireoCountryFlag-unknownBackground": theme.palette.action.disabledBackground,
+    "--VireoCountryFlag-unknownForeground": theme.palette.text.disabled,
+    display: "inline-flex",
+    flexShrink: 0,
+    width: ownerState.width,
+    aspectRatio: "3 / 2",
+    lineHeight: 0,
+    overflow: "hidden",
+    verticalAlign: "middle",
+    borderRadius: 2,
+    boxShadow: `inset 0 0 0 1px ${theme.palette.divider}`,
+}));
+export const VireoCountryFlagFlag = styled("svg", {
+    name: VIREO_COUNTRY_FLAG_NAME,
+    slot: "Flag",
+    overridesResolver: (_props, styles) => styles.flag,
+})({
+    display: "block",
+    width: "100%",
+    height: "100%",
+});

package/dist/capabilities/country/components/data-display/VireoCountryFlag/VireoCountryFlag.types.d.ts

@@ -0,0 +1,61 @@
+import type { CountryCode } from "../../../../../capabilities/country/models/countryCode.models.js";
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../core/public.js";
+import type { BoxProps, Tooltip } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import { type VireoCountryFlagClasses, type VireoCountryFlagClassKey } from "./VireoCountryFlag.classes.js";
+import type { VIREO_COUNTRY_FLAG_NAME } from "./VireoCountryFlag.identity.js";
+/** Known country codes retain autocomplete while arbitrary strings remain renderable as unknown flags. */
+export type VireoCountryFlagCode = CountryCode | (string & {});
+export type VireoCountryFlagOwnerState = {
+    countryCode: string;
+    enableTooltip: boolean;
+    known: boolean;
+    width: number | string;
+};
+export interface VireoCountryFlagRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoCountryFlagFlagSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoCountryFlagTooltipSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+/** Replaceable semantic regions exposed by {@link VireoCountryFlag}. */
+export type VireoCountryFlagSlots = {
+    /** @default 'span' */
+    root: React.ElementType;
+    /** @default country-flag-icons SVG or the Vireo unknown-flag SVG */
+    flag: React.ElementType;
+    /** @default Tooltip */
+    tooltip: React.ElementType;
+};
+/** Slot props exposed by {@link VireoCountryFlag}. */
+export type VireoCountryFlagSlotsAndSlotProps = CreateSlotsAndSlotProps<VireoCountryFlagSlots, {
+    root: SlotProps<"span", VireoCountryFlagRootSlotPropsOverrides, VireoCountryFlagOwnerState>;
+    flag: SlotProps<"svg", VireoCountryFlagFlagSlotPropsOverrides, VireoCountryFlagOwnerState>;
+    tooltip: SlotProps<typeof Tooltip, VireoCountryFlagTooltipSlotPropsOverrides, VireoCountryFlagOwnerState>;
+}>;
+/** Props owned by {@link VireoCountryFlag}. */
+export type VireoCountryFlagOwnProps = VireoCountryFlagSlotsAndSlotProps & {
+    /** Country or subdivision identifier. Unknown strings render the fallback flag. */
+    countryCode: VireoCountryFlagCode;
+    /** Accessible flag label and, when enabled, tooltip content. */
+    label?: string;
+    /** Shows a country-name tooltip. @default false */
+    enableTooltip?: boolean;
+    /** Rendered width. Height follows the flag's 3:2 aspect ratio. @default 24 */
+    width?: number | string;
+    /** Override or extend the utility classes applied to each slot and state. */
+    classes?: Partial<VireoCountryFlagClasses>;
+};
+/** Props VireoCountryFlag inherits from its default root after excluding protected component-owned props. */
+export type VireoCountryFlagInheritedProps = Omit<BoxProps<"span">, "aria-hidden" | "aria-label" | "children" | "component" | "dangerouslySetInnerHTML" | "role" | "title">;
+/** Props accepted by {@link VireoCountryFlag}. */
+export type VireoCountryFlagProps = VireoCountryFlagOwnProps & VireoCountryFlagInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_COUNTRY_FLAG_NAME]?: VireoThemeComponent<VireoCountryFlagProps, VireoCountryFlagClassKey, VireoCountryFlagOwnerState, Theme>;
+    }
+}

package/dist/capabilities/country/components/data-display/VireoCountryFlag/VireoCountryFlag.types.js

@@ -0,0 +1 @@
+export {};

package/dist/capabilities/country/components/data-display/VireoCountryFlag/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./VireoCountryFlag.js";
+export * from "./VireoCountryFlag.classes.js";
+export * from "./VireoCountryFlag.types.js";

package/dist/capabilities/country/components/data-display/VireoCountryFlag/index.js

@@ -0,0 +1,3 @@
+export * from "./VireoCountryFlag.js";
+export * from "./VireoCountryFlag.classes.js";
+export * from "./VireoCountryFlag.types.js";

package/dist/capabilities/country/components/data-display/VireoCountryFlag/internal/components/UnknownCountryFlag.d.ts

@@ -0,0 +1,2 @@
+import React from "react";
+export declare const UnknownCountryFlag: React.ForwardRefExoticComponent<Omit<React.SVGProps<SVGSVGElement>, "ref"> & React.RefAttributes<SVGSVGElement>>;

package/dist/capabilities/country/components/data-display/VireoCountryFlag/internal/components/UnknownCountryFlag.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from "react";
+export const UnknownCountryFlag = React.forwardRef(function UnknownCountryFlag(props, ref) {
+    return (_jsxs("svg", { viewBox: "0 0 24 16", ...props, ref: ref, children: [_jsx("rect", { width: "24", height: "16", fill: "var(--VireoCountryFlag-unknownBackground)" }), _jsx("text", { x: "12", y: "11.5", fill: "var(--VireoCountryFlag-unknownForeground)", fontFamily: "system-ui, sans-serif", fontSize: "10", fontWeight: "600", textAnchor: "middle", children: "?" })] }));
+});

package/dist/capabilities/country/constants/countryCodes.constants.d.ts

@@ -0,0 +1,2 @@
+/** Country and territory identifiers with 3:2 flag assets shipped by country-flag-icons. */
+export declare const COUNTRY_CODES: readonly ["AC", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ-BO", "BQ-SA", "BQ-SE", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES-CT", "ES", "ET", "EU", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB-ENG", "GB-NIR", "GB-SCT", "GB-WLS", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "IC", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TA", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XA", "XC", "XK", "XO", "YE", "YT", "ZA", "ZM", "ZW"];