@djangocfg/ui-core 2.1.304 → 2.1.308

package/README.md

@@ -54,9 +54,25 @@ import { Button, Dialog, Table } from '@djangocfg/ui-core';
 ### Overlay (9)
 `Dialog` `AlertDialog` `Sheet` `Drawer` `Popover` `HoverCard` `Tooltip` `ResponsiveSheet` `SidePanel`
 
-Default **`TooltipContent`** styling uses semantic **popover** tokens (`bg-popover`, `text-popover-foreground`, `border-border`, shadow) — not `primary` — so hints read as neutral floating UI.
+**`Dialog`** — `DialogContent` adds two props on top of Radix:
 
-**`SidePanel`** — non-modal side drawer for inspector panels, playgrounds, filters. Slides in from the right (`side="right"`, default) or left edge. Unlike `Sheet`/`Drawer`, it does NOT lock the rest of the page — surrounding UI stays clickable and focusable. Esc-to-close (toggleable) and swipe-to-close via vaul. Use when you want a slide-in surface that co-exists with the page below; for modal side surfaces, prefer `Sheet`.
+- `fullscreen` — drops card chrome and stretches to `100dvw × 100dvh`.
+- `closeButton` — `undefined` (default `X`), `false` (none), or a `ReactNode` (wrap in `DialogClose`).
+
+```tsx
+<DialogContent
+  fullscreen
+  closeButton={
+    <DialogClose className="absolute right-4 top-4 inline-flex h-10 w-10 cursor-pointer items-center justify-center rounded-full border bg-background/90 hover:bg-accent">
+      <X className="h-4 w-4" />
+    </DialogClose>
+  }
+>
+  …your fullscreen layout…
+</DialogContent>
+```
+
+**`SidePanel`** — non-modal side drawer (right by default, or left). Surrounding UI stays interactive; Esc-to-close + swipe-to-close via vaul. Prefer `Sheet` for modal side surfaces.
 
 ```tsx
 <SidePanel open={open} onOpenChange={setOpen} side="right">
@@ -71,7 +87,7 @@ Default **`TooltipContent`** styling uses semantic **popover** tokens (`bg-popov
 </SidePanel>
 ```
 
-**`Drawer`** — modal vaul-based panel that slides in from any edge (`top` / `right` / `bottom` / `left`). Picks a size from a preset table or takes an explicit CSS length; both are applied via inline `style` so vaul's first-paint measurement matches the final layout (no inset miscalc).
+**`Drawer`** — modal vaul panel sliding from any edge (`top` / `right` / `bottom` / `left`). Sizes: `sm` `md` `lg` `xl` `full`, default `md`; or pass an explicit `width` / `height`.
 
 ```tsx
 <Drawer direction="right">
@@ -85,20 +101,6 @@ Default **`TooltipContent`** styling uses semantic **popover** tokens (`bg-popov
 </Drawer>
 ```
 
-Size presets — `sm` `md` `lg` `xl` `full`. Maps to width for `left`/`right`, height for `top`/`bottom`:
-
-| Size | Horizontal width | Vertical height |
-|------|-------------------|------------------|
-| sm   | `min(100vw, 360px)` | `min(100vh, 240px)` |
-| md   | `min(100vw, 480px)` | `min(100vh, 360px)` |
-| lg   | `min(100vw, 640px)` | `min(100vh, 480px)` |
-| xl   | `min(100vw, 800px)` | `min(100vh, 640px)` |
-| full | `100vw`           | `100vh`          |
-
-If you need an exact size, pass `width` / `height` (a CSS length string or number → px). Inline-applied so the vaul measurement is correct on first paint.
-
-**Migration note** — the default size changed (was hardcoded `280px` for left/right, `auto` for top/bottom). New default is `size="md"`. Pass `size="sm"` (~360px) for the closest old left/right behavior, or set an explicit `width` / `height`.
-
 ### Navigation (8)
 `Tabs` `Accordion` `Collapsible` `Command` `ContextMenu` `DropdownMenu` `Menubar` `NavigationMenu`
 
@@ -108,8 +110,17 @@ If you need an exact size, pass `width` / `height` (a CSS length string or numbe
 ### Feedback (5)
 `Alert` `Toaster` (Sonner) `Spinner` `Empty` `Preloader`
 
-### Specialized (7)
-`Kbd` `TokenIcon` `Item` `Portal` `ImageWithFallback` `CopyButton` `CopyField`
+### Specialized (9)
+`Kbd` `TokenIcon` `Item` `Portal` `ImageWithFallback` `CopyButton` `CopyField` `Flag` `LanguageFlag`
+
+**`Flag`** / **`LanguageFlag`** — SVG country flags (3:2 aspect) backed by `country-flag-icons`. `Flag` takes an ISO 3166-1 alpha-2 `countryCode` and covers every ISO country (~270 entries); `LanguageFlag` resolves a locale (`'en'`, `'pt-BR'`, `'zh_CN'`) to a country and renders the flag. Both render `null` for unknown codes. Used by `LocaleSwitcher`, `PhoneInput`, and `CountrySelect` — no emoji fallbacks anywhere.
+
+```tsx
+<Flag countryCode="JP" rounded className="h-3 w-4" />
+<LanguageFlag code="pt-BR" rounded className="h-3 w-4" />
+```
+
+Helper: `getLanguageCountryCode(locale)` returns the resolved alpha-2 code (or `null`). The static `LANGUAGE_TO_COUNTRY` map is exported for callers that need their own lookup.
 
 ## Hooks (30+)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.304",
+  "version": "2.1.308",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -91,7 +91,7 @@
     "playground": "playground dev"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.304",
+    "@djangocfg/i18n": "^2.1.308",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -144,6 +144,7 @@
     "clsx": "^2.1.1",
     "cmdk": "1.1.1",
     "countries-list": "^3.2.2",
+    "country-flag-icons": "^1.6.16",
     "date-fns": "^4.1.0",
     "embla-carousel-react": "8.6.0",
     "i18n-iso-countries": "^7.14.0",
@@ -159,9 +160,9 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.304",
+    "@djangocfg/i18n": "^2.1.308",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.304",
+    "@djangocfg/typescript-config": "^2.1.308",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/components/forms/phone-input/index.tsx

@@ -13,13 +13,7 @@ import { cn } from '../../../lib';
 import {
     DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger
 } from '../../navigation/dropdown-menu';
-
-// Generate country flag emoji from country code
-const getCountryFlag = (countryCode: CountryCode): string => {
-  return countryCode
-    .toUpperCase()
-    .replace(/./g, char => String.fromCodePoint(char.charCodeAt(0) + 127397))
-}
+import { Flag } from '../../specialized/flag';
 
 // Get country name from country code using browser's built-in Intl.DisplayNames
 const getCountryName = (countryCode: CountryCode): string => {
@@ -37,7 +31,6 @@ const getAllCountries = () => {
   return getCountries().map(countryCode => ({
     code: countryCode,
     name: getCountryName(countryCode),
-    flag: getCountryFlag(countryCode),
     dialCode: `+${getCountryCallingCode(countryCode)}`
   })).sort((a, b) => a.name.localeCompare(b.name))
 }
@@ -215,7 +208,7 @@ const PhoneInput = React.forwardRef<HTMLInputElement, PhoneInputProps>(
               className="h-10 px-3 rounded-r-none border-r-0 flex items-center gap-2"
               disabled={disabled}
             >
-              <span className="text-base">{currentCountry.flag}</span>
+              <Flag countryCode={currentCountry.code} rounded className="h-3 w-4" />
               <span className="text-sm font-mono">{currentCountry.dialCode}</span>
               <ChevronDown className="h-3 w-3 opacity-50" />
             </Button>
@@ -251,7 +244,7 @@ const PhoneInput = React.forwardRef<HTMLInputElement, PhoneInputProps>(
                       index === highlightedIndex && "bg-accent"
                     )}
                   >
-                    <span className="text-base">{country.flag}</span>
+                    <Flag countryCode={country.code} rounded className="h-3 w-4" />
                     <span className="flex-1 text-sm">{country.name}</span>
                     <span className="text-sm font-mono text-muted-foreground">
                       {country.dialCode}

package/src/components/index.ts

@@ -121,6 +121,8 @@ export { Portal } from './specialized/portal';
 export type { PortalProps } from './specialized/portal';
 export { ImageWithFallback } from './specialized/image-with-fallback';
 export type { ImageWithFallbackProps } from './specialized/image-with-fallback';
+export { Flag, LanguageFlag, LANGUAGE_TO_COUNTRY, getLanguageCountryCode, FLAG_COMPONENTS } from './specialized/flag';
+export type { FlagProps, LanguageFlagProps, FlagSvgComponent } from './specialized/flag';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Effects

package/src/components/overlay/dialog/dialog.story.tsx

@@ -1,3 +1,4 @@
+import { ArrowLeft, X } from 'lucide-react';
 import { defineStory } from '@djangocfg/playground';
 import {
   Dialog,
@@ -99,6 +100,80 @@ export const Confirmation = () => (
   </Dialog>
 );
 
+export const Fullscreen = () => (
+  <Dialog>
+    <DialogTrigger asChild>
+      <Button variant="outline">Open fullscreen dialog</Button>
+    </DialogTrigger>
+    <DialogContent fullscreen>
+      <div className="mx-auto flex h-full w-full max-w-3xl flex-col px-4 py-10 sm:px-6 lg:px-8">
+        <DialogTitle className="text-2xl font-semibold tracking-tight">
+          Fullscreen layout
+        </DialogTitle>
+        <DialogDescription className="mt-1 text-muted-foreground">
+          `fullscreen` removes the centred-card chrome and stretches the content to
+          the viewport. Build your own header / footer inside.
+        </DialogDescription>
+        <div className="mt-6 flex-1 rounded-xl border border-dashed border-border/60 bg-muted/30 p-6 text-sm text-muted-foreground">
+          Slot for a custom layout — gallery, onboarding, command palette, etc.
+        </div>
+      </div>
+    </DialogContent>
+  </Dialog>
+);
+
+export const CustomCloseButton = () => (
+  <Dialog>
+    <DialogTrigger asChild>
+      <Button variant="outline">Open with pill close</Button>
+    </DialogTrigger>
+    <DialogContent
+      fullscreen
+      closeButton={
+        <DialogClose
+          aria-label="Close"
+          className="absolute right-4 top-4 inline-flex h-10 w-10 cursor-pointer items-center justify-center rounded-full border border-border/60 bg-background/90 text-muted-foreground shadow-sm transition-colors hover:bg-accent hover:text-foreground"
+        >
+          <X className="h-4 w-4" />
+        </DialogClose>
+      }
+    >
+      <div className="mx-auto flex h-full w-full max-w-2xl flex-col px-4 py-10">
+        <DialogTitle>Custom close affordance</DialogTitle>
+        <DialogDescription className="mt-1 text-muted-foreground">
+          Pass `closeButton` to override the default Radix `X`. Pass `false` to
+          drop the affordance entirely.
+        </DialogDescription>
+      </div>
+    </DialogContent>
+  </Dialog>
+);
+
+export const NoCloseButton = () => (
+  <Dialog>
+    <DialogTrigger asChild>
+      <Button variant="outline">Modal step (no close)</Button>
+    </DialogTrigger>
+    <DialogContent closeButton={false}>
+      <DialogHeader>
+        <DialogTitle>Saving…</DialogTitle>
+        <DialogDescription>
+          The dialog has no close affordance — dismissal is driven by the action
+          buttons below or programmatically.
+        </DialogDescription>
+      </DialogHeader>
+      <DialogFooter>
+        <DialogClose asChild>
+          <Button variant="outline">
+            <ArrowLeft className="mr-1.5 h-3.5 w-3.5" />
+            Back
+          </Button>
+        </DialogClose>
+      </DialogFooter>
+    </DialogContent>
+  </Dialog>
+);
+
 export const LongContent = () => (
   <Dialog>
     <DialogTrigger asChild>

package/src/components/overlay/dialog/index.tsx

@@ -31,26 +31,52 @@ const DialogOverlay = React.forwardRef<
 ))
 DialogOverlay.displayName = DialogPrimitive.Overlay.displayName
 
+interface DialogContentProps
+  extends React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
+  /**
+   * Stretch the content to fill the viewport (`100dvw × 100dvh`) and drop
+   * the centred-card chrome (no `max-w`, no `rounded`, no `border`, no
+   * default padding). Use for full-screen pickers, galleries, onboarding.
+   */
+  fullscreen?: boolean
+  /**
+   * Close affordance shown in the top-right corner.
+   * - `undefined` (default): renders the built-in `X` button.
+   * - `false`: no close button — use this when the surrounding UI provides
+   *   its own close trigger (or the dialog has no dismiss).
+   * - `ReactNode`: replaces the built-in button. Wrap your node in
+   *   `DialogClose` so it dismisses the dialog.
+   */
+  closeButton?: React.ReactNode | false
+}
+
 const DialogContent = React.forwardRef<
   React.ElementRef<typeof DialogPrimitive.Content>,
-  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
->(({ className, children, ...props }, ref) => (
+  DialogContentProps
+>(({ className, children, fullscreen = false, closeButton, ...props }, ref) => (
   <DialogPortal>
     <DialogOverlay />
     <DialogPrimitive.Content
       ref={ref}
       className={cn(
-        "fixed left-1/2 top-1/2 z-600 grid w-full max-w-lg -translate-x-1/2 -translate-y-1/2 gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 sm:rounded-lg",
+        "fixed z-600 bg-background duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+        fullscreen
+          ? "left-0 top-0 grid h-[100dvh] w-screen max-w-none gap-0 border-0 p-0 shadow-none data-[state=closed]:zoom-out-[0.98] data-[state=open]:zoom-in-[0.98]"
+          : "left-1/2 top-1/2 grid w-full max-w-lg -translate-x-1/2 -translate-y-1/2 gap-4 border p-6 shadow-lg sm:rounded-lg data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
         className
       )}
       {...props}
     >
       {children}
       <DialogPrimitive.Description className="sr-only" />
-      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground">
-        <Cross2Icon className="h-4 w-4" />
-        <span className="sr-only">Close</span>
-      </DialogPrimitive.Close>
+      {closeButton === undefined ? (
+        <DialogPrimitive.Close className="absolute right-4 top-4 cursor-pointer rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground">
+          <Cross2Icon className="h-4 w-4" />
+          <span className="sr-only">Close</span>
+        </DialogPrimitive.Close>
+      ) : closeButton === false ? null : (
+        closeButton
+      )}
     </DialogPrimitive.Content>
   </DialogPortal>
 ))

package/src/components/select/country-select.tsx

@@ -2,7 +2,7 @@
 
 import { Check, ChevronsUpDown, Search, X } from 'lucide-react';
 import * as React from 'react';
-import { countries, getEmojiFlag, type TCountryCode } from 'countries-list';
+import { countries, type TCountryCode } from 'countries-list';
 
 import { cn } from '../../lib/utils';
 import { Badge } from '../data/badge';
@@ -14,12 +14,12 @@ import {
 import { Input } from '../forms/input';
 import { Popover, PopoverContent, PopoverTrigger } from '../overlay/popover';
 import { ScrollArea } from '../layout/scroll-area';
+import { Flag } from '../specialized/flag';
 
 export interface CountryOption {
   code: TCountryCode;
   name: string;
   native: string;
-  emoji: string;
 }
 
 export type CountrySelectVariant = 'dropdown' | 'inline';
@@ -64,7 +64,7 @@ export interface CountrySelectProps {
 }
 
 /**
- * Country Select component with emoji flags
+ * Country Select component with SVG flags
  *
  * Supports:
  * - Single and multiple selection
@@ -156,7 +156,6 @@ export function CountrySelect({
         code,
         name: getCountryName?.(code) ?? countries[code].name,
         native: countries[code].native,
-        emoji: getEmojiFlag(code),
       }))
       .sort((a, b) => a.name.localeCompare(b.name));
   }, [getCountryName, allowedCountries, excludedCountries]);
@@ -256,7 +255,7 @@ export function CountrySelect({
                         {isSelected && <div className="h-2 w-2 rounded-full bg-primary-foreground" />}
                       </div>
                     )}
-                    <span className="text-lg">{country.emoji}</span>
+                    <Flag countryCode={country.code} rounded className="h-4 w-6 shrink-0" />
                     <div className="flex flex-col flex-1 min-w-0">
                       <span className={cn('text-sm', isSelected && 'font-medium')}>
                         {country.name}
@@ -287,7 +286,7 @@ export function CountrySelect({
       const country = selectedCountries[0]!;
       return (
         <div className="flex items-center gap-2">
-          <span>{country.emoji}</span>
+          <Flag countryCode={country.code} rounded className="h-3 w-4 shrink-0" />
           <span>{country.name}</span>
         </div>
       );
@@ -304,7 +303,7 @@ export function CountrySelect({
             variant="secondary"
             className="mr-1 text-xs"
           >
-            <span className="mr-1">{country.emoji}</span>
+            <Flag countryCode={country.code} rounded className="mr-1 h-3 w-4 shrink-0" />
             {country.name}
             <button
               className="ml-1 rounded-full hover:bg-muted-foreground/20"
@@ -379,7 +378,7 @@ export function CountrySelect({
                           isSelected ? "opacity-100" : "opacity-0"
                         )}
                       />
-                      <span className="mr-2 text-lg">{country.emoji}</span>
+                      <Flag countryCode={country.code} rounded className="mr-2 h-4 w-6 shrink-0" />
                       <div className="flex flex-col flex-1 min-w-0">
                         <span className="truncate">{country.name}</span>
                         {showNativeName && country.native !== country.name && (
@@ -402,4 +401,3 @@ export function CountrySelect({
 
 // Re-export types for convenience
 export type { TCountryCode } from 'countries-list';
-export { getEmojiFlag } from 'countries-list';

package/src/components/select/index.ts

@@ -58,10 +58,9 @@ export type { OptionBuilderConfig } from './helpers';
 export { CountrySelect } from './country-select';
 export type { CountrySelectProps, CountryOption } from './country-select';
 export type { TCountryCode } from 'countries-list';
-export { getEmojiFlag } from 'countries-list';
 
 // LanguageSelect
-export { LanguageSelect, getLanguageFlag } from './language-select';
+export { LanguageSelect } from './language-select';
 export type { LanguageSelectProps, LanguageOption, TLanguageCode } from './language-select';
 
 // Shared types

package/src/components/select/language-select.tsx

@@ -2,289 +2,11 @@
 
 import { Check, ChevronsUpDown, Search, X } from 'lucide-react';
 import * as React from 'react';
-import { languages, getEmojiFlag, type TLanguageCode, type TCountryCode } from 'countries-list';
+import { languages, type TLanguageCode } from 'countries-list';
 
 import { cn } from '../../lib/utils';
+import { LanguageFlag } from '../specialized/flag';
 
-/**
- * Mapping of language codes (ISO 639-1) to primary country codes (ISO 3166-1 alpha-2)
- * Used to display country flag emoji for each language
- *
- * Note: Some languages are spoken in multiple countries, we pick the most representative one.
- */
-const LANGUAGE_TO_COUNTRY: Partial<Record<TLanguageCode, TCountryCode>> = {
-  // Major world languages
-  en: 'US', // English → United States
-  zh: 'CN', // Chinese → China
-  es: 'ES', // Spanish → Spain
-  ar: 'SA', // Arabic → Saudi Arabia
-  hi: 'IN', // Hindi → India
-  bn: 'BD', // Bengali → Bangladesh
-  pt: 'BR', // Portuguese → Brazil
-  ru: 'RU', // Russian → Russia
-  ja: 'JP', // Japanese → Japan
-  de: 'DE', // German → Germany
-  fr: 'FR', // French → France
-  ko: 'KR', // Korean → South Korea
-  it: 'IT', // Italian → Italy
-  tr: 'TR', // Turkish → Turkey
-  vi: 'VN', // Vietnamese → Vietnam
-  pl: 'PL', // Polish → Poland
-  uk: 'UA', // Ukrainian → Ukraine
-  nl: 'NL', // Dutch → Netherlands
-
-  // European languages
-  el: 'GR', // Greek → Greece
-  cs: 'CZ', // Czech → Czech Republic
-  sv: 'SE', // Swedish → Sweden
-  hu: 'HU', // Hungarian → Hungary
-  ro: 'RO', // Romanian → Romania
-  da: 'DK', // Danish → Denmark
-  fi: 'FI', // Finnish → Finland
-  no: 'NO', // Norwegian → Norway
-  nb: 'NO', // Norwegian Bokmål → Norway
-  nn: 'NO', // Norwegian Nynorsk → Norway
-  sk: 'SK', // Slovak → Slovakia
-  bg: 'BG', // Bulgarian → Bulgaria
-  hr: 'HR', // Croatian → Croatia
-  sr: 'RS', // Serbian → Serbia
-  sl: 'SI', // Slovenian → Slovenia
-  et: 'EE', // Estonian → Estonia
-  lv: 'LV', // Latvian → Latvia
-  lt: 'LT', // Lithuanian → Lithuania
-  be: 'BY', // Belarusian → Belarus
-  mk: 'MK', // Macedonian → North Macedonia
-  sq: 'AL', // Albanian → Albania
-  is: 'IS', // Icelandic → Iceland
-  mt: 'MT', // Maltese → Malta
-  ga: 'IE', // Irish → Ireland
-  cy: 'GB', // Welsh → United Kingdom
-  gd: 'GB', // Scottish Gaelic → United Kingdom
-  br: 'FR', // Breton → France
-  lb: 'LU', // Luxembourgish → Luxembourg
-  fo: 'FO', // Faroese → Faroe Islands
-  bs: 'BA', // Bosnian → Bosnia
-
-  // Spanish regional
-  eu: 'ES', // Basque → Spain
-  ca: 'ES', // Catalan → Spain
-  gl: 'ES', // Galician → Spain
-
-  // Asian languages
-  th: 'TH', // Thai → Thailand
-  id: 'ID', // Indonesian → Indonesia
-  ms: 'MY', // Malay → Malaysia
-  tl: 'PH', // Tagalog → Philippines
-  jv: 'ID', // Javanese → Indonesia
-  su: 'ID', // Sundanese → Indonesia
-
-  // South Asian languages
-  ta: 'IN', // Tamil → India
-  te: 'IN', // Telugu → India
-  mr: 'IN', // Marathi → India
-  gu: 'IN', // Gujarati → India
-  kn: 'IN', // Kannada → India
-  ml: 'IN', // Malayalam → India
-  pa: 'IN', // Punjabi → India
-  or: 'IN', // Odia → India
-  as: 'IN', // Assamese → India
-  ne: 'NP', // Nepali → Nepal
-  si: 'LK', // Sinhala → Sri Lanka
-  dz: 'BT', // Dzongkha → Bhutan
-
-  // Middle East & Central Asia
-  fa: 'IR', // Persian/Farsi → Iran
-  ur: 'PK', // Urdu → Pakistan
-  ps: 'AF', // Pashto → Afghanistan
-  he: 'IL', // Hebrew → Israel
-  ku: 'IQ', // Kurdish → Iraq
-  hy: 'AM', // Armenian → Armenia
-  ka: 'GE', // Georgian → Georgia
-  az: 'AZ', // Azerbaijani → Azerbaijan
-  kk: 'KZ', // Kazakh → Kazakhstan
-  uz: 'UZ', // Uzbek → Uzbekistan
-  tg: 'TJ', // Tajik → Tajikistan
-  ky: 'KG', // Kyrgyz → Kyrgyzstan
-  tk: 'TM', // Turkmen → Turkmenistan
-  mn: 'MN', // Mongolian → Mongolia
-
-  // Southeast Asian
-  my: 'MM', // Burmese → Myanmar
-  km: 'KH', // Khmer → Cambodia
-  lo: 'LA', // Lao → Laos
-
-  // African languages
-  sw: 'KE', // Swahili → Kenya
-  am: 'ET', // Amharic → Ethiopia
-  ha: 'NG', // Hausa → Nigeria
-  yo: 'NG', // Yoruba → Nigeria
-  ig: 'NG', // Igbo → Nigeria
-  zu: 'ZA', // Zulu → South Africa
-  xh: 'ZA', // Xhosa → South Africa
-  af: 'ZA', // Afrikaans → South Africa
-  st: 'ZA', // Southern Sotho → South Africa
-  tn: 'BW', // Tswana → Botswana
-  sn: 'ZW', // Shona → Zimbabwe
-  rw: 'RW', // Kinyarwanda → Rwanda
-  rn: 'BI', // Kirundi → Burundi
-  so: 'SO', // Somali → Somalia
-  ti: 'ER', // Tigrinya → Eritrea
-  mg: 'MG', // Malagasy → Madagascar
-  ny: 'MW', // Chichewa → Malawi
-  lg: 'UG', // Luganda → Uganda
-  wo: 'SN', // Wolof → Senegal
-  ff: 'SN', // Fulah → Senegal
-  bm: 'ML', // Bambara → Mali
-
-  // Caribbean & Creole
-  ht: 'HT', // Haitian Creole → Haiti
-
-  // Pacific
-  mi: 'NZ', // Maori → New Zealand
-  sm: 'WS', // Samoan → Samoa
-  to: 'TO', // Tongan → Tonga
-  fj: 'FJ', // Fijian → Fiji
-  mh: 'MH', // Marshallese → Marshall Islands
-  ty: 'PF', // Tahitian → French Polynesia
-  na: 'NR', // Nauruan → Nauru
-  bi: 'VU', // Bislama → Vanuatu
-  ch: 'GU', // Chamorro → Guam
-
-  // Other constructed/historical
-  // Note: Constructed languages have no country, using symbolic mappings
-  // eo: Esperanto - no country flag available
-  la: 'VA', // Latin → Vatican
-  // ia: Interlingua - no country flag available
-  // ie: Interlingue - no country flag available
-  // io: Ido - no country flag available
-  // vo: Volapük - no country flag available
-
-  // China minority languages
-  bo: 'CN', // Tibetan → China
-  ug: 'CN', // Uyghur → China
-  za: 'CN', // Zhuang → China
-  ii: 'CN', // Sichuan Yi → China
-
-  // South Asia
-  dv: 'MV', // Dhivehi → Maldives
-  ks: 'IN', // Kashmiri → India
-  sd: 'PK', // Sindhi → Pakistan
-  sa: 'IN', // Sanskrit → India
-  pi: 'IN', // Pali → India (historical Buddhist)
-
-  // Baltic-Finnic
-  fy: 'NL', // Western Frisian → Netherlands
-
-  // Caucasian
-  os: 'RU', // Ossetic → Russia
-  ce: 'RU', // Chechen → Russia
-  av: 'RU', // Avar → Russia
-  ab: 'GE', // Abkhazian → Georgia
-
-  // Turkic in Russia
-  tt: 'RU', // Tatar → Russia
-  ba: 'RU', // Bashkir → Russia
-  cv: 'RU', // Chuvash → Russia
-
-  // Russia minority
-  kv: 'RU', // Komi → Russia
-
-  // Africa additional
-  aa: 'ET', // Afar → Ethiopia
-  ak: 'GH', // Akan → Ghana
-  ee: 'GH', // Ewe → Ghana
-  tw: 'GH', // Twi → Ghana
-  ln: 'CD', // Lingala → DR Congo
-  lu: 'CD', // Luba-Katanga → DR Congo
-  kg: 'CD', // Kongo → DR Congo
-  sg: 'CF', // Sango → Central African Republic
-  ki: 'KE', // Kikuyu → Kenya
-  om: 'ET', // Oromo → Ethiopia
-  kr: 'NE', // Kanuri → Niger
-  kj: 'NA', // Kuanyama → Namibia
-  hz: 'NA', // Herero → Namibia
-  ng: 'NA', // Ndonga → Namibia
-  nd: 'ZW', // North Ndebele → Zimbabwe
-  nr: 'ZA', // South Ndebele → South Africa
-  ss: 'SZ', // Swati → Eswatini (Swaziland)
-  ts: 'ZA', // Tsonga → South Africa
-  ve: 'ZA', // Venda → South Africa
-
-  // Americas indigenous
-  gn: 'PY', // Guarani → Paraguay
-  qu: 'PE', // Quechua → Peru
-  ay: 'BO', // Aymara → Bolivia
-  nv: 'US', // Navajo → United States
-  oj: 'CA', // Ojibwa → Canada
-  cr: 'CA', // Cree → Canada
-  iu: 'CA', // Inuktitut → Canada
-  ik: 'US', // Inupiak → United States (Alaska)
-
-  // Greenland
-  kl: 'GL', // Greenlandic → Greenland
-
-  // Other European
-  an: 'ES', // Aragonese → Spain
-  wa: 'BE', // Walloon → Belgium
-  li: 'NL', // Limburgian → Netherlands
-
-  // Slavic historical
-  cu: 'BG', // Old Church Slavonic → Bulgaria
-  mo: 'MD', // Moldovan → Moldova
-
-  // Jewish
-  yi: 'IL', // Yiddish → Israel
-
-  // Bihari (group)
-  bh: 'IN', // Bihari → India
-
-  // Papua New Guinea
-  ho: 'PG', // Hiri Motu → Papua New Guinea
-
-  // Other Slavic
-  sh: 'RS', // Serbo-Croatian → Serbia
-
-  // Romance
-  oc: 'FR', // Occitan → France
-  co: 'FR', // Corsican → France
-  sc: 'IT', // Sardinian → Italy
-  rm: 'CH', // Romansh → Switzerland
-
-  // Germanic
-  gv: 'IM', // Manx → Isle of Man
-  kw: 'GB', // Cornish → United Kingdom
-
-  // Uralic
-  se: 'NO', // Northern Sami → Norway
-
-  // Note: ch (Chamorro) already defined above in Pacific section
-};
-
-/**
- * Get emoji flag for a language code
- * @param languageCode - ISO 639-1 language code (e.g., 'en', 'ru', 'ko')
- * @returns Emoji flag string or empty string if no mapping exists
- */
-export function getLanguageFlag(languageCode: TLanguageCode | string): string {
-  const code = languageCode.toLowerCase();
-
-  // Handle locale with region: pt-BR, pt-br, zh-CN, etc.
-  if (code.includes('-') || code.includes('_')) {
-    const parts = code.split(/[-_]/);
-    const region = parts[1]?.toUpperCase() as TCountryCode;
-    // Try region code as country first (pt-BR → BR)
-    if (region && region.length === 2) {
-      const flag = getEmojiFlag(region);
-      if (flag) return flag;
-    }
-  }
-
-  // Fall back to language → country mapping
-  const langCode = code.split(/[-_]/)[0] as TLanguageCode;
-  const countryCode = LANGUAGE_TO_COUNTRY[langCode];
-  if (!countryCode) return '';
-  return getEmojiFlag(countryCode);
-}
 import { Badge } from '../data/badge';
 import { Button } from '../forms/button';
 import { Checkbox } from '../forms/checkbox';
@@ -299,8 +21,6 @@ export interface LanguageOption {
   code: TLanguageCode;
   name: string;
   native: string;
-  /** Emoji flag (if available) */
-  flag: string;
 }
 
 export type LanguageSelectVariant = 'dropdown' | 'inline';
@@ -334,7 +54,7 @@ export interface LanguageSelectProps {
   allowedLanguages?: TLanguageCode[];
   /** Exclude specific language codes */
   excludedLanguages?: TLanguageCode[];
-  /** Show flag emoji (default: true) */
+  /** Show country-flag SVG (default: true) */
   showFlag?: boolean;
   /** Show language code (default: false) */
   showCode?: boolean;
@@ -443,7 +163,6 @@ export function LanguageSelect({
         code,
         name: getLanguageName?.(code) ?? languages[code].name,
         native: languages[code].native,
-        flag: getLanguageFlag(code),
       }))
       .sort((a, b) => a.name.localeCompare(b.name));
   }, [getLanguageName, allowedLanguages, excludedLanguages]);
@@ -553,8 +272,8 @@ export function LanguageSelect({
                         {isSelected && <div className="h-2 w-2 rounded-full bg-primary-foreground" />}
                       </div>
                     )}
-                    {showFlag && language.flag && (
-                      <span className="text-lg">{language.flag}</span>
+                    {showFlag && (
+                      <LanguageFlag code={language.code} className="h-3.5 w-5" rounded />
                     )}
                     <div className="flex flex-col flex-1 min-w-0">
                       <span className={cn('text-sm', isSelected && 'font-medium')}>
@@ -591,7 +310,7 @@ export function LanguageSelect({
       const language = selectedLanguages[0]!;
       return (
         <div className="flex items-center gap-2">
-          {showFlag && language.flag && <span>{language.flag}</span>}
+          {showFlag && <LanguageFlag code={language.code} className="h-3 w-4" rounded />}
           {showCode && <span className="text-xs text-muted-foreground uppercase">{language.code}</span>}
           <span>{language.name}</span>
         </div>
@@ -609,7 +328,7 @@ export function LanguageSelect({
             variant="secondary"
             className="mr-1 text-xs"
           >
-            {showFlag && language.flag && <span className="mr-1">{language.flag}</span>}
+            {showFlag && <LanguageFlag code={language.code} className="mr-1 h-3 w-4" rounded />}
             {showCode && <span className="mr-1 text-muted-foreground uppercase">{language.code}</span>}
             {language.name}
             <button
@@ -685,8 +404,8 @@ export function LanguageSelect({
                           isSelected ? "opacity-100" : "opacity-0"
                         )}
                       />
-                      {showFlag && language.flag && (
-                        <span className="mr-2 text-lg">{language.flag}</span>
+                      {showFlag && (
+                        <LanguageFlag code={language.code} className="mr-2 h-3.5 w-5" rounded />
                       )}
                       <div className="flex flex-col flex-1 min-w-0">
                         <span className="truncate">{language.name}</span>
@@ -715,4 +434,4 @@ export function LanguageSelect({
 
 // Re-export types for convenience
 export type { TLanguageCode } from 'countries-list';
-export { LANGUAGE_TO_COUNTRY };
+export { LANGUAGE_TO_COUNTRY } from '../specialized/flag';

package/src/components/specialized/flag/Flag.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import * as React from 'react';
+
+import { cn } from '../../../lib/utils';
+
+import { FLAG_COMPONENTS } from './flag-map';
+import { getLanguageCountryCode } from './language-to-country';
+
+export interface FlagProps extends Omit<React.SVGAttributes<SVGSVGElement>, 'children'> {
+  /** ISO 3166-1 alpha-2 country code (e.g. `'US'`, `'JP'`). Case-insensitive. */
+  countryCode: string;
+  /** Optional rounded corners — common for tile / chip presentations. */
+  rounded?: boolean;
+}
+
+/**
+ * SVG country flag (3:2 aspect). Renders nothing for unknown country codes
+ * — call sites should reserve space if they want a stable layout.
+ */
+export function Flag({ countryCode, rounded, className, ...props }: FlagProps) {
+  const code = countryCode?.toUpperCase();
+  const Component = code ? FLAG_COMPONENTS[code] : undefined;
+  if (!Component) return null;
+  // `country-flag-icons` types its components against an HTML+SVG intersection;
+  // we narrow to plain `SVGAttributes` for our consumers.
+  const Tag = Component as unknown as React.ComponentType<React.SVGAttributes<SVGSVGElement>>;
+  return (
+    <Tag
+      className={cn(
+        'inline-block shrink-0 select-none',
+        rounded && 'overflow-hidden rounded-[2px]',
+        className,
+      )}
+      aria-hidden="true"
+      focusable={false}
+      {...props}
+    />
+  );
+}
+
+export interface LanguageFlagProps extends Omit<FlagProps, 'countryCode'> {
+  /** Locale / language code (`'en'`, `'pt-BR'`, `'zh_CN'`, …). */
+  code: string;
+}
+
+/**
+ * Convenience wrapper — resolves a locale to a country code and renders `Flag`.
+ * Returns `null` when the locale has no country mapping.
+ */
+export function LanguageFlag({ code, ...props }: LanguageFlagProps) {
+  const country = getLanguageCountryCode(code);
+  if (!country) return null;
+  return <Flag countryCode={country} {...props} />;
+}

package/src/components/specialized/flag/flag-map.ts

@@ -0,0 +1,22 @@
+/**
+ * Static map: ISO 3166-1 alpha-2 country code → SVG React component.
+ *
+ * Re-exports every flag from `country-flag-icons` (~270 entries) so the
+ * `Flag` component covers every consumer — locale switchers, phone-input
+ * country picker, country select, etc. Tree-shaking keeps unused flags out
+ * of the final bundle when consumers reach for `<Flag countryCode>`
+ * directly with a constant code.
+ */
+
+import type * as React from 'react';
+import * as Flags from 'country-flag-icons/react/3x2';
+
+/**
+ * `country-flag-icons` types its components against `HTMLSVGElement`
+ * (their custom intersection of HTMLElement + SVGElement). We treat them
+ * as opaque components — call sites use `<Flag />` rather than touching
+ * the DOM type directly.
+ */
+export type FlagSvgComponent = (props: React.SVGProps<SVGSVGElement> & React.HTMLAttributes<SVGSVGElement>) => React.JSX.Element;
+
+export const FLAG_COMPONENTS = Flags as unknown as Record<string, FlagSvgComponent>;

package/src/components/specialized/flag/flag.story.tsx

@@ -0,0 +1,82 @@
+import * as React from 'react';
+
+import { defineStory, useSelect } from '@djangocfg/playground';
+
+import { Flag, LanguageFlag } from '.';
+import { Input } from '../../forms/input';
+
+export default defineStory({
+  title: 'Core/Flag',
+  component: Flag,
+  description:
+    'SVG country flag (3:2). Flag takes a country code; LanguageFlag resolves a locale → country.',
+});
+
+export const Default = () => <Flag countryCode="US" className="h-6 w-9" />;
+
+export const Rounded = () => (
+  <div className="flex items-center gap-3">
+    <Flag countryCode="US" className="h-6 w-9" />
+    <Flag countryCode="US" rounded className="h-6 w-9" />
+  </div>
+);
+
+export const Interactive = () => {
+  const [code] = useSelect('country', {
+    options: ['US', 'JP', 'BR', 'DE', 'FR', 'KR', 'CN', 'RU', 'GB', 'IL'] as const,
+    defaultValue: 'US',
+    label: 'Country code',
+  });
+  const [size] = useSelect('size', {
+    options: ['h-3 w-4', 'h-4 w-6', 'h-6 w-9', 'h-10 w-14'] as const,
+    defaultValue: 'h-6 w-9',
+    label: 'Size',
+  });
+  return <Flag countryCode={code} rounded className={size} />;
+};
+
+export const LanguageInteractive = () => {
+  const [code, setCode] = React.useState('pt-BR');
+  return (
+    <div className="space-y-3">
+      <div className="flex items-center gap-3 text-sm">
+        <LanguageFlag code={code} rounded className="h-6 w-9" />
+        <span className="font-mono text-muted-foreground">{code}</span>
+      </div>
+      <Input
+        value={code}
+        onChange={(e) => setCode(e.target.value)}
+        placeholder="Locale (en, pt-BR, zh-CN, …)"
+        className="max-w-xs"
+      />
+    </div>
+  );
+};
+
+export const Grid = () => {
+  const codes = [
+    'US', 'GB', 'CA', 'BR', 'DE', 'FR', 'IT', 'ES', 'PT',
+    'NL', 'SE', 'NO', 'DK', 'FI', 'PL', 'CZ', 'GR', 'TR',
+    'RU', 'UA', 'JP', 'KR', 'CN', 'IN', 'TH', 'VN', 'ID', 'IL', 'SA',
+  ];
+  return (
+    <div className="grid grid-cols-6 gap-3">
+      {codes.map((c) => (
+        <div key={c} className="flex flex-col items-center gap-1">
+          <Flag countryCode={c} rounded className="h-6 w-9" />
+          <span className="font-mono text-xs text-muted-foreground">{c}</span>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+export const UnknownCode = () => (
+  <div className="text-sm text-muted-foreground">
+    Unknown code renders nothing:{' '}
+    <span className="inline-flex items-center gap-1.5">
+      <Flag countryCode="ZZ" className="h-3 w-4" />
+      <span>(no flag here →)</span>
+    </span>
+  </div>
+);

package/src/components/specialized/flag/index.ts

@@ -0,0 +1,5 @@
+export { Flag, LanguageFlag } from './Flag';
+export type { FlagProps, LanguageFlagProps } from './Flag';
+export { LANGUAGE_TO_COUNTRY, getLanguageCountryCode } from './language-to-country';
+export { FLAG_COMPONENTS } from './flag-map';
+export type { FlagSvgComponent } from './flag-map';

package/src/components/specialized/flag/language-to-country.ts

@@ -0,0 +1,258 @@
+/**
+ * Mapping of language codes (ISO 639-1) → primary country code (ISO 3166-1 alpha-2).
+ *
+ * Used to render a country flag SVG for a language code. Many languages are
+ * spoken in multiple countries — we pick the most representative one.
+ */
+
+import type { TLanguageCode, TCountryCode } from 'countries-list';
+
+export const LANGUAGE_TO_COUNTRY: Partial<Record<TLanguageCode, TCountryCode>> = {
+  // Major world languages
+  en: 'US',
+  zh: 'CN',
+  es: 'ES',
+  ar: 'SA',
+  hi: 'IN',
+  bn: 'BD',
+  pt: 'BR',
+  ru: 'RU',
+  ja: 'JP',
+  de: 'DE',
+  fr: 'FR',
+  ko: 'KR',
+  it: 'IT',
+  tr: 'TR',
+  vi: 'VN',
+  pl: 'PL',
+  uk: 'UA',
+  nl: 'NL',
+
+  // European
+  el: 'GR',
+  cs: 'CZ',
+  sv: 'SE',
+  hu: 'HU',
+  ro: 'RO',
+  da: 'DK',
+  fi: 'FI',
+  no: 'NO',
+  nb: 'NO',
+  nn: 'NO',
+  sk: 'SK',
+  bg: 'BG',
+  hr: 'HR',
+  sr: 'RS',
+  sl: 'SI',
+  et: 'EE',
+  lv: 'LV',
+  lt: 'LT',
+  be: 'BY',
+  mk: 'MK',
+  sq: 'AL',
+  is: 'IS',
+  mt: 'MT',
+  ga: 'IE',
+  cy: 'GB',
+  gd: 'GB',
+  br: 'FR',
+  lb: 'LU',
+  fo: 'FO',
+  bs: 'BA',
+
+  // Spanish regional
+  eu: 'ES',
+  ca: 'ES',
+  gl: 'ES',
+
+  // Asian
+  th: 'TH',
+  id: 'ID',
+  ms: 'MY',
+  tl: 'PH',
+  jv: 'ID',
+  su: 'ID',
+
+  // South Asian
+  ta: 'IN',
+  te: 'IN',
+  mr: 'IN',
+  gu: 'IN',
+  kn: 'IN',
+  ml: 'IN',
+  pa: 'IN',
+  or: 'IN',
+  as: 'IN',
+  ne: 'NP',
+  si: 'LK',
+  dz: 'BT',
+
+  // Middle East & Central Asia
+  fa: 'IR',
+  ur: 'PK',
+  ps: 'AF',
+  he: 'IL',
+  ku: 'IQ',
+  hy: 'AM',
+  ka: 'GE',
+  az: 'AZ',
+  kk: 'KZ',
+  uz: 'UZ',
+  tg: 'TJ',
+  ky: 'KG',
+  tk: 'TM',
+  mn: 'MN',
+
+  // Southeast Asian
+  my: 'MM',
+  km: 'KH',
+  lo: 'LA',
+
+  // African
+  sw: 'KE',
+  am: 'ET',
+  ha: 'NG',
+  yo: 'NG',
+  ig: 'NG',
+  zu: 'ZA',
+  xh: 'ZA',
+  af: 'ZA',
+  st: 'ZA',
+  tn: 'BW',
+  sn: 'ZW',
+  rw: 'RW',
+  rn: 'BI',
+  so: 'SO',
+  ti: 'ER',
+  mg: 'MG',
+  ny: 'MW',
+  lg: 'UG',
+  wo: 'SN',
+  ff: 'SN',
+  bm: 'ML',
+
+  // Caribbean & Creole
+  ht: 'HT',
+
+  // Pacific
+  mi: 'NZ',
+  sm: 'WS',
+  to: 'TO',
+  fj: 'FJ',
+  mh: 'MH',
+  ty: 'PF',
+  na: 'NR',
+  bi: 'VU',
+  ch: 'GU',
+
+  // Historical / constructed
+  la: 'VA',
+
+  // China minorities
+  bo: 'CN',
+  ug: 'CN',
+  za: 'CN',
+  ii: 'CN',
+
+  // South Asia extras
+  dv: 'MV',
+  ks: 'IN',
+  sd: 'PK',
+  sa: 'IN',
+  pi: 'IN',
+
+  fy: 'NL',
+
+  // Caucasian
+  os: 'RU',
+  ce: 'RU',
+  av: 'RU',
+  ab: 'GE',
+
+  // Turkic in Russia
+  tt: 'RU',
+  ba: 'RU',
+  cv: 'RU',
+  kv: 'RU',
+
+  // Africa extras
+  aa: 'ET',
+  ak: 'GH',
+  ee: 'GH',
+  tw: 'GH',
+  ln: 'CD',
+  lu: 'CD',
+  kg: 'CD',
+  sg: 'CF',
+  ki: 'KE',
+  om: 'ET',
+  kr: 'NE',
+  kj: 'NA',
+  hz: 'NA',
+  ng: 'NA',
+  nd: 'ZW',
+  nr: 'ZA',
+  ss: 'SZ',
+  ts: 'ZA',
+  ve: 'ZA',
+
+  // Americas indigenous
+  gn: 'PY',
+  qu: 'PE',
+  ay: 'BO',
+  nv: 'US',
+  oj: 'CA',
+  cr: 'CA',
+  iu: 'CA',
+  ik: 'US',
+  kl: 'GL',
+
+  // Other European
+  an: 'ES',
+  wa: 'BE',
+  li: 'NL',
+
+  // Slavic historical
+  cu: 'BG',
+  mo: 'MD',
+
+  yi: 'IL',
+  bh: 'IN',
+  ho: 'PG',
+  sh: 'RS',
+
+  // Romance
+  oc: 'FR',
+  co: 'FR',
+  sc: 'IT',
+  rm: 'CH',
+
+  // Germanic
+  gv: 'IM',
+  kw: 'GB',
+
+  // Uralic
+  se: 'NO',
+};
+
+/**
+ * Resolve a locale (`'en'`, `'pt-BR'`, `'zh_CN'`, …) to an ISO 3166-1 alpha-2
+ * country code. Region suffixes win when present (`pt-BR` → `BR`).
+ *
+ * Returns `null` when no mapping exists — callers should render a graceful
+ * fallback (no flag).
+ */
+export function getLanguageCountryCode(localeCode: string): TCountryCode | null {
+  if (!localeCode) return null;
+  const normalized = localeCode.replace('_', '-');
+
+  // Region wins: pt-BR → BR, zh-CN → CN.
+  const dash = normalized.indexOf('-');
+  if (dash !== -1) {
+    const region = normalized.slice(dash + 1).toUpperCase();
+    if (region.length === 2) return region as TCountryCode;
+  }
+
+  const lang = normalized.slice(0, dash === -1 ? normalized.length : dash).toLowerCase() as TLanguageCode;
+  return LANGUAGE_TO_COUNTRY[lang] ?? null;
+}