@santi020k/lumen-astro 1.2.0 → 1.4.0

package/README.md

@@ -60,6 +60,63 @@ incremental migrations, but new code should keep native behavior and visual styl
 <NativeSelect size={8} visualSize="lg" />
 ```
 
+## Compound interactive components
+
+Popover, dropdown menu, tabs, and tooltip parts expose the DOM and ARIA contracts consumed by the
+shared progressive-enhancement runtime. Prefer these parts over recreating roles and `data-ui-*`
+attributes by hand.
+
+```astro
+---
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+  Popover,
+  PopoverPanel,
+  PopoverTrigger,
+  Tabs,
+  TabsList,
+  TabsPanel,
+  TabsTrigger,
+  Tooltip,
+  TooltipContent
+} from '@santi020k/lumen-astro'
+---
+
+<DropdownMenu>
+  <DropdownMenuTrigger>Download</DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem>macOS</DropdownMenuItem>
+    <DropdownMenuItem>Windows</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem disabled status="Soon">Android</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+
+<Popover>
+  <PopoverTrigger>Filters</PopoverTrigger>
+  <PopoverPanel>Filter controls</PopoverPanel>
+</Popover>
+
+<Tabs initialValue="preview">
+  <TabsList aria-label="Workspace view">
+    <TabsTrigger value="preview">Preview</TabsTrigger>
+    <TabsTrigger value="code">Code</TabsTrigger>
+  </TabsList>
+  <TabsPanel value="preview">Rendered result</TabsPanel>
+  <TabsPanel value="code">Source code</TabsPanel>
+</Tabs>
+
+<Tooltip>
+  <Button aria-label="Save changes">Save</Button>
+  <TooltipContent>Save changes</TooltipContent>
+</Tooltip>
+```
+
 ## Context navigation
 
 Use `ContextNavigation` below a primary header when the available links change with a selected

package/components/Backdrop.astro

@@ -0,0 +1,35 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'div'> {
+  class?: string | null
+  className?: string
+  intensity?: 'medium' | 'strong' | 'subtle'
+  tone?: 'accent' | 'brand' | 'neutral'
+  variant?: 'aurora' | 'dots' | 'grid' | 'rays'
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  intensity = 'medium',
+  tone = 'brand',
+  variant = 'aurora',
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(rest, [
+  'ui-backdrop',
+  `ui-backdrop--${variant}`,
+  `ui-backdrop--${tone}`,
+  `ui-backdrop--${intensity}`
+], classProp, className)
+---
+
+<div class:list={classList} {...passthrough}>
+  <div class="ui-backdrop__content">
+    <slot />
+  </div>
+</div>

package/components/DropdownMenuContent.astro

@@ -0,0 +1,28 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'div'> {
+  class?: string | null
+  className?: string
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  role = 'menu',
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(
+  rest,
+  ['ui-menu__content'],
+  classProp,
+  className
+)
+---
+
+<div role={role} class:list={classList} {...passthrough}>
+  <slot />
+</div>

package/components/DropdownMenuItem.astro

@@ -0,0 +1,39 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'button'> {
+  class?: string | null
+  className?: string
+  status?: string
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  disabled = false,
+  status,
+  type = 'button',
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(
+  rest,
+  ['ui-menu__item'],
+  classProp,
+  className
+)
+---
+
+<button
+  type={type}
+  role="menuitem"
+  class:list={classList}
+  disabled={disabled}
+  aria-disabled={disabled ? 'true' : undefined}
+  {...passthrough}
+>
+  <span class="ui-menu__item-label"><slot /></span>
+  {status && <span class="ui-menu__item-status">{status}</span>}
+</button>

package/components/DropdownMenuSeparator.astro

@@ -0,0 +1,25 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'div'> {
+  class?: string | null
+  className?: string
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(
+  rest,
+  ['ui-menu__separator'],
+  classProp,
+  className
+)
+---
+
+<div role="separator" class:list={classList} {...passthrough} />

package/components/DropdownMenuTrigger.astro

@@ -0,0 +1,39 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'button'> {
+  class?: string | null
+  className?: string
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  type = 'button',
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(
+  rest,
+  [
+    'ui-button',
+    'ui-button--outline',
+    'ui-button--default-size',
+    'ui-menu__trigger'
+  ],
+  classProp,
+  className
+)
+---
+
+<button
+  type={type}
+  class:list={classList}
+  data-ui-trigger
+  aria-haspopup="menu"
+  {...passthrough}
+>
+  <slot />
+</button>

package/components/Graphic.astro

@@ -0,0 +1,43 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'div'> {
+  class?: string | null
+  className?: string
+  label?: string
+  size?: 'lg' | 'md' | 'sm'
+  tone?: 'accent' | 'brand' | 'neutral'
+  variant?: 'glow' | 'grid' | 'orbit'
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  label,
+  size = 'md',
+  tone = 'brand',
+  variant = 'orbit',
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(rest, [
+  'ui-graphic',
+  `ui-graphic--${variant}`,
+  `ui-graphic--${tone}`,
+  `ui-graphic--${size}`
+], classProp, className)
+---
+
+<div
+  aria-hidden={label ? undefined : 'true'}
+  aria-label={label}
+  class:list={classList}
+  role={label ? 'img' : undefined}
+  {...passthrough}
+>
+  <div class="ui-graphic__content">
+    <slot />
+  </div>
+</div>

package/components/Illustration.astro

@@ -0,0 +1,67 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'span'> {
+  class?: string | null
+  className?: string
+  label?: string
+  size?: 'lg' | 'md' | 'sm'
+  tone?: 'accent' | 'auto' | 'brand' | 'neutral'
+  variant?: 'empty' | 'error' | 'offline' | 'success'
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  label,
+  size = 'md',
+  tone = 'auto',
+  variant = 'empty',
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(rest, [
+  'ui-illustration',
+  `ui-illustration--${variant}`,
+  `ui-illustration--${tone}`,
+  `ui-illustration--${size}`
+], classProp, className)
+---
+
+<span
+  aria-hidden={label ? undefined : 'true'}
+  aria-label={label}
+  class:list={classList}
+  role={label ? 'img' : undefined}
+  {...passthrough}
+>
+  <svg aria-hidden="true" fill="none" viewBox="0 0 120 120">
+    <circle class="ui-illustration__wash" cx="60" cy="60" r="48" />
+    {variant === 'empty' && (
+      <g>
+        <path d="M32 48h56l-7 35H39l-7-35Z" />
+        <path d="M43 48 49 36h22l6 12M47 66h26" />
+      </g>
+    )}
+    {variant === 'success' && (
+      <g>
+        <circle cx="60" cy="60" r="28" />
+        <path d="m45 60 10 10 21-23" />
+      </g>
+    )}
+    {variant === 'error' && (
+      <g>
+        <circle cx="60" cy="60" r="28" />
+        <path d="m49 49 22 22m0-22L49 71" />
+      </g>
+    )}
+    {variant === 'offline' && (
+      <g>
+        <path d="M37 74h44a14 14 0 0 0 1-28 23 23 0 0 0-42-4 16 16 0 0 0-3 32Z" />
+        <path d="m38 34 44 52" />
+      </g>
+    )}
+  </svg>
+</span>

package/components/LanguageToggle.astro

@@ -1,20 +1,41 @@
 ---
 import type { HTMLAttributes } from 'astro/types'
 
-import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+import {
+  formatLumenLanguageLabel,
+  getLumenLocalePair,
+  type LumenLocaleOption,
+  normalizeLumenLocales,
+  resolveLumenAstroProps
+} from '@santi020k/lumen-core'
 
 interface Props extends HTMLAttributes<'button'> {
   class?: string | null
   className?: string
+  defaultValue?: string
+  labelTemplate?: string
+  locales?: readonly LumenLocaleOption[]
+  storageKey?: string
+  value?: string
 }
 
 const {
   class: classProp = '',
   className = '',
+  defaultValue,
+  labelTemplate = 'Change language from {current} to {next}',
+  locales: localeOptions,
+  storageKey,
   type = 'button',
+  value,
   ...rest
 } = Astro.props
 
+const locales = normalizeLumenLocales(localeOptions)
+const initialValue = value ?? defaultValue ?? locales[0]?.value
+const { current, next } = getLumenLocalePair(locales, initialValue)
+const accessibleLabel = formatLumenLanguageLabel(labelTemplate, current, next)
+
 const { classList, passthrough } = resolveLumenAstroProps(rest, [
   'ui-language-toggle'
 ], classProp, className)
@@ -24,7 +45,19 @@ const { classList, passthrough } = resolveLumenAstroProps(rest, [
   type={type}
   class:list={classList}
   data-ui-language-toggle
+  data-ui-language-controlled={value === undefined ? undefined : ''}
+  data-ui-language-initial-value={initialValue}
+  data-ui-language-label-template={labelTemplate}
+  data-ui-language-locales={JSON.stringify(locales)}
+  data-ui-language-value={current.value}
+  data-ui-language-next-value={next.value}
+  data-ui-language-storage-key={storageKey}
+  aria-label={accessibleLabel}
   {...passthrough}
 >
-  <slot />
+  {
+    Astro.slots.has('default') ?
+      <slot /> :
+      <span data-ui-language-label lang={next.value}>{next.label}</span>
+  }
 </button>

package/components/PopoverPanel.astro

@@ -0,0 +1,27 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'div'> {
+  class?: string | null
+  className?: string
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(
+  rest,
+  ['ui-popover__panel'],
+  classProp,
+  className
+)
+---
+
+<div class:list={classList} {...passthrough}>
+  <slot />
+</div>

package/components/PopoverTrigger.astro

@@ -0,0 +1,34 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'button'> {
+  class?: string | null
+  className?: string
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  type = 'button',
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(
+  rest,
+  ['ui-button', 'ui-button--outline', 'ui-button--default-size'],
+  classProp,
+  className
+)
+---
+
+<button
+  type={type}
+  class:list={classList}
+  data-ui-trigger
+  aria-haspopup="menu"
+  {...passthrough}
+>
+  <slot />
+</button>

package/components/TabsList.astro

@@ -0,0 +1,34 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'div'> {
+  class?: string | null
+  className?: string
+  orientation?: 'horizontal' | 'vertical'
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  orientation = 'horizontal',
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(
+  rest,
+  [],
+  classProp,
+  className
+)
+---
+
+<div
+  role="tablist"
+  aria-orientation={orientation}
+  class:list={classList}
+  {...passthrough}
+>
+  <slot />
+</div>

package/components/TabsPanel.astro

@@ -0,0 +1,35 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'div'> {
+  class?: string | null
+  className?: string
+  value: string
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  value,
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(
+  rest,
+  [],
+  classProp,
+  className
+)
+---
+
+<div
+  role="tabpanel"
+  data-value={value}
+  tabindex="0"
+  class:list={classList}
+  {...passthrough}
+>
+  <slot />
+</div>

package/components/TabsTrigger.astro

@@ -0,0 +1,36 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'button'> {
+  class?: string | null
+  className?: string
+  value: string
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  type = 'button',
+  value,
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(
+  rest,
+  [],
+  classProp,
+  className
+)
+---
+
+<button
+  type={type}
+  role="tab"
+  data-value={value}
+  class:list={classList}
+  {...passthrough}
+>
+  <slot />
+</button>

package/components/TooltipContent.astro

@@ -0,0 +1,27 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+
+import { resolveLumenAstroProps } from '@santi020k/lumen-core'
+
+interface Props extends HTMLAttributes<'span'> {
+  class?: string | null
+  className?: string
+}
+
+const {
+  class: classProp = '',
+  className = '',
+  ...rest
+} = Astro.props
+
+const { classList, passthrough } = resolveLumenAstroProps(
+  rest,
+  [],
+  classProp,
+  className
+)
+---
+
+<span role="tooltip" class:list={classList} {...passthrough}>
+  <slot />
+</span>

package/index.ts

@@ -11,6 +11,7 @@ export { default as AspectRatio } from './components/AspectRatio.astro'
 export { default as Attachment } from './components/Attachment.astro'
 export { default as Autocomplete } from './components/Autocomplete.astro'
 export { default as Avatar } from './components/Avatar.astro'
+export { default as Backdrop } from './components/Backdrop.astro'
 export { default as BackToTop } from './components/BackToTop.astro'
 export { default as Badge } from './components/Badge.astro'
 export { default as BarChart } from './components/BarChart.astro'
@@ -51,6 +52,10 @@ export { default as Dialog } from './components/Dialog.astro'
 export { default as Direction } from './components/Direction.astro'
 export { default as Drawer } from './components/Drawer.astro'
 export { default as DropdownMenu } from './components/DropdownMenu.astro'
+export { default as DropdownMenuContent } from './components/DropdownMenuContent.astro'
+export { default as DropdownMenuItem } from './components/DropdownMenuItem.astro'
+export { default as DropdownMenuSeparator } from './components/DropdownMenuSeparator.astro'
+export { default as DropdownMenuTrigger } from './components/DropdownMenuTrigger.astro'
 export { default as Empty } from './components/Empty.astro'
 export { default as ErrorSummary } from './components/ErrorSummary.astro'
 export { default as Eyebrow } from './components/Eyebrow.astro'
@@ -61,9 +66,11 @@ export { default as FloatingBadge } from './components/FloatingBadge.astro'
 export { default as Form } from './components/Form.astro'
 export { default as FormattedDate } from './components/FormattedDate.astro'
 export { default as GradientDivider } from './components/GradientDivider.astro'
+export { default as Graphic } from './components/Graphic.astro'
 export { default as Grid } from './components/Grid.astro'
 export { default as HoverCard } from './components/HoverCard.astro'
 export { default as Icon } from './components/Icon.astro'
+export { default as Illustration } from './components/Illustration.astro'
 export { default as Image } from './components/Image.astro'
 export { default as Input } from './components/Input.astro'
 export { default as InputGroup } from './components/InputGroup.astro'
@@ -95,6 +102,8 @@ export { default as PieChart } from './components/PieChart.astro'
 export { default as Pill } from './components/Pill.astro'
 export { default as Popconfirm } from './components/Popconfirm.astro'
 export { default as Popover } from './components/Popover.astro'
+export { default as PopoverPanel } from './components/PopoverPanel.astro'
+export { default as PopoverTrigger } from './components/PopoverTrigger.astro'
 export { default as Progress } from './components/Progress.astro'
 export { default as Prose } from './components/Prose.astro'
 export { default as QRCode } from './components/QRCode.astro'
@@ -131,6 +140,9 @@ export { default as Stepper } from './components/Stepper.astro'
 export { default as Switch } from './components/Switch.astro'
 export { default as Table } from './components/Table.astro'
 export { default as Tabs } from './components/Tabs.astro'
+export { default as TabsList } from './components/TabsList.astro'
+export { default as TabsPanel } from './components/TabsPanel.astro'
+export { default as TabsTrigger } from './components/TabsTrigger.astro'
 export { default as TagGroup } from './components/TagGroup.astro'
 export { default as Textarea } from './components/Textarea.astro'
 export { default as ThemeBuilder } from './components/ThemeBuilder.astro'
@@ -143,6 +155,7 @@ export { default as Toggle } from './components/Toggle.astro'
 export { default as ToggleGroup } from './components/ToggleGroup.astro'
 export { default as Toolbar } from './components/Toolbar.astro'
 export { default as Tooltip } from './components/Tooltip.astro'
+export { default as TooltipContent } from './components/TooltipContent.astro'
 export { default as Tour } from './components/Tour.astro'
 export { default as Transfer } from './components/Transfer.astro'
 export { default as Tree } from './components/Tree.astro'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@santi020k/lumen-astro",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "publishConfig": {
     "access": "public"
   },
@@ -37,8 +37,8 @@
   ],
   "dependencies": {
     "uqr": "^0.1.3",
-    "@santi020k/lumen": "^1.2.0",
-    "@santi020k/lumen-core": "^1.2.0"
+    "@santi020k/lumen": "^1.4.0",
+    "@santi020k/lumen-core": "^1.4.0"
   },
   "devDependencies": {
     "@astrojs/ts-plugin": "^1.10.10",

package/runtime/UIPrimitives.astro

@@ -15,13 +15,16 @@ import {
   exportThemeCss,
   exportThemeDesignTokens,
   exportThemeFigmaVariables,
+  formatLumenLanguageLabel,
+  getLumenLocalePair,
   getLumenRichTextShortcut,
   isLumenRichTextToggleCommand,
+  type LumenLocaleOption,
   type LumenRichTextChangeDetail,
   type LumenRichTextCommandDetail,
   type LumenThemeTokens,
-  lumenTokenNames
-} from '@santi020k/lumen-core'
+  lumenTokenNames,
+  normalizeLumenLocales } from '@santi020k/lumen-core'
 
 /* eslint-disable complexity */
 /* Stateful DOM handlers stay local so Astro consumers do not need a framework runtime. */
@@ -237,6 +240,18 @@ const initDisclosures = (scope: ParentNode): void => {
       nextItem?.focus()
     })
 
+    if (root.hasAttribute('data-ui-dropdown-menu')) {
+      panel.addEventListener('click', event => {
+        const item = event.target instanceof Element ?
+          event.target.closest<HTMLElement>('[role="menuitem"]') :
+          null
+
+        if (!item || item.matches(':disabled, [aria-disabled="true"]')) return
+
+        setOpen(trigger, panel, false)
+      })
+    }
+
     if (root.hasAttribute('data-ui-hover-card')) {
       root.addEventListener('mouseenter', () => setOpen(trigger, panel, true))
 
@@ -933,6 +948,12 @@ const initTabs = (scope: ParentNode): void => {
     const panels = [...root.querySelectorAll<HTMLElement>('[role="tabpanel"]')]
       .filter(panel => panel.closest('[data-ui-tabs]') === root)
 
+    const tabList = tabs[0]?.closest<HTMLElement>('[role="tablist"]')
+
+    const orientation = tabList?.getAttribute('aria-orientation') === 'vertical' ?
+      'vertical' :
+      'horizontal'
+
     if (!tabs.length || !panels.length) continue
 
     const rootId = root.id || `ui-tabs-${++uiTabsCount}`
@@ -1034,13 +1055,22 @@ const initTabs = (scope: ParentNode): void => {
       tab.addEventListener('click', () => activate(tab))
 
       tab.addEventListener('keydown', event => {
-        const keys = ['ArrowLeft', 'ArrowRight', 'Home', 'End']
+        const keys = orientation === 'vertical' ?
+          ['ArrowUp', 'ArrowDown', 'Home', 'End'] :
+          ['ArrowLeft', 'ArrowRight', 'Home', 'End']
 
         if (!keys.includes(event.key)) return
 
         event.preventDefault()
 
-        const nextTab = tabs[getLoopedIndex(event.key, index, tabs.length, ['ArrowRight'])]
+        const nextTab = tabs[
+          getLoopedIndex(
+            event.key,
+            index,
+            tabs.length,
+            orientation === 'vertical' ? ['ArrowDown'] : ['ArrowRight']
+          )
+        ]
 
         if (nextTab) {
           activate(nextTab)
@@ -1282,6 +1312,109 @@ const initThemeToggles = (scope: ParentNode): void => {
   }
 }
 
+const isUnknownArray = (value: unknown): value is unknown[] => Array.isArray(value)
+
+const parseLanguageToggleLocales = (value: string | undefined): readonly LumenLocaleOption[] => {
+  if (!value) return normalizeLumenLocales(undefined)
+
+  try {
+    const parsed: unknown = JSON.parse(value)
+
+    if (!isUnknownArray(parsed)) return normalizeLumenLocales(undefined)
+
+    const locales = parsed.flatMap(item => {
+      if (!item || typeof item !== 'object' || !('label' in item) || !('value' in item)) return []
+
+      const { label, value: localeValue } = item
+
+      return typeof label === 'string' && typeof localeValue === 'string' ?
+        [{ label, value: localeValue }] :
+        []
+    })
+
+    return normalizeLumenLocales(locales)
+  } catch {
+    return normalizeLumenLocales(undefined)
+  }
+}
+
+const initLanguageToggles = (scope: ParentNode): void => {
+  for (const control of scope.querySelectorAll<HTMLButtonElement>('[data-ui-language-toggle]')) {
+    if (control.dataset.uiBound === 'true') continue
+
+    control.dataset.uiBound = 'true'
+
+    const locales = parseLanguageToggleLocales(control.dataset.uiLanguageLocales)
+    const storageKey = control.dataset.uiLanguageStorageKey
+    const controlled = control.hasAttribute('data-ui-language-controlled')
+
+    const labelTemplate = control.dataset.uiLanguageLabelTemplate ??
+      'Change language from {current} to {next}'
+
+    const sync = (value: string): void => {
+      const { current, next } = getLumenLocalePair(locales, value)
+      const label = control.querySelector<HTMLElement>('[data-ui-language-label]')
+
+      control.dataset.uiLanguageValue = current.value
+
+      control.dataset.uiLanguageNextValue = next.value
+
+      control.setAttribute('aria-label', formatLumenLanguageLabel(labelTemplate, current, next))
+
+      if (label) {
+        label.lang = next.value
+
+        label.textContent = next.label
+      }
+    }
+
+    let storedValue: string | null = null
+
+    if (!controlled && storageKey) {
+      try {
+        storedValue = localStorage.getItem(storageKey)
+      } catch {
+        // Storage can be unavailable in privacy modes.
+      }
+    }
+
+    const documentValue = document.documentElement.lang || undefined
+
+    const initialValue = controlled ?
+      control.dataset.uiLanguageValue :
+      storedValue ?? control.dataset.uiLanguageInitialValue ?? documentValue
+
+    const initialPair = getLumenLocalePair(locales, initialValue)
+
+    sync(initialPair.current.value)
+
+    if (!controlled) document.documentElement.lang = initialPair.current.value
+
+    control.addEventListener('click', () => {
+      const { current, next } = getLumenLocalePair(locales, control.dataset.uiLanguageValue)
+
+      if (!controlled) {
+        document.documentElement.lang = next.value
+
+        sync(next.value)
+
+        if (storageKey) {
+          try {
+            localStorage.setItem(storageKey, next.value)
+          } catch {
+            // Storage can be unavailable in privacy modes.
+          }
+        }
+      }
+
+      control.dispatchEvent(new CustomEvent('ui:language-change', {
+        bubbles: true,
+        detail: { previousValue: current.value, value: next.value }
+      }))
+    })
+  }
+}
+
 const getVisibleItems = (items: HTMLElement[]): HTMLElement[] => items.filter(item => !item.hidden &&
   item.offsetParent !== null &&
   !item.hasAttribute('disabled') &&
@@ -5460,6 +5593,8 @@ const initUiPrimitives = (scope: ParentNode = document): void => {
 
   initThemeToggles(scope)
 
+  initLanguageToggles(scope)
+
   initCommand(scope)
 
   initComboboxes(scope)