@tuwaio/docs-ui 0.5.0 → 0.5.2

package/README.md

@@ -12,6 +12,7 @@
 - **Nextra layout parts:** `Navbar` and `Footer` wrap the navbar and footer of `nextra-theme-docs` with the site logo and a row of external links (`baseNavLinks`, `baseFooterLinks` are the defaults: the npm and GitHub organizations of TUWA). The footer also links the policies in force on tuwa.io and the list of all policies on the docs hub.
 - **Logo:** `RemoteLogo` is an async React Server Component that fetches an SVG (by default the TUWA logo) and renders it as React elements, so it takes `className` and `currentColor`.
 - **Theme switch:** `ThemeSwitcher` is a light/dark switch for any theme state (for example `next-themes`).
+- **Language select:** `LocaleSwitcher` is an accessible glassmorphic select dropdown for switching languages (English, Українська, 简体中文, etc.), styled to match `ThemeSwitcher`. Features zero layout shift, Nova UI Kit animated directional chevron, collision detection with auto-flip (`placement="auto"`), multi-layout Latin typeahead navigation (independent of user OS keyboard language), and an invisible native `<select>` overlay on touch devices (`pointer: coarse`) for native mobile system pickers (iOS wheel, Android sheet). Full WCAG 2.1/2.2 AA/AAA compliance. It renders an invisible placeholder during SSR to avoid hydration shifts.
 - **Interface settings for 30 days:** `PreferenceExpiry` is an inline script for the `<head>` of a site's root layout. It forgets the Local Storage values of the given keys (by default `theme`) 30 days after they were written, as the [Cookie Policy](https://tuwa.io/cookie) states, and dates each later write, whatever library writes it (`next-themes`, the `Tabs` of Nextra).
 - **Decoration:** `Orb` (an animated sphere in the brand color of a TUWA project), `StarryBackground` (an animated star field on a canvas) and `NoSSR` (renders its children only on the client).
 - **Policy pages:** `policies` lists the TUWA policies (Terms, Privacy, Cookie, Refund, Security, Data Processing Addendum) with their paths and whether they are in force (`publishedPolicies`; footers use `footerPolicies`). `loadPolicy` loads the text of a policy in a language, and `PolicyDocument` renders it with the date of the version, a Download PDF button, a language switch (English, Українська) when the policy is translated, anchored sections (the same anchors in every language) and a list of sections. The texts and PDFs come from [`TuwaIO/workflows/docs`](https://github.com/TuwaIO/workflows/tree/main/docs). Code that needs only the list or `loadPolicy` (footers, sitemaps, route handlers) imports them from `@tuwaio/docs-ui/policies`, which has no React, Next.js or Nextra imports.
@@ -143,11 +144,11 @@ It writes the index to `public/_pagefind` (keep that directory in `.gitignore`)
 
 ## 🗄️ Browser Storage
 
-`ThemeSwitcher` stores nothing; it only calls `onToggle`, and the site keeps the theme. `PreferenceExpiry` stores `<key>:expires` (the time in epoch milliseconds) next to each key it is given, removes both once that time has passed, and wraps `Storage.prototype.setItem` on the page to date later writes of those keys.
+`LocaleSwitcher` and `ThemeSwitcher` store nothing; they only call `onSelect` / `onToggle`, and the site keeps the choice. `PreferenceExpiry` stores `<key>:expires` (the time in epoch milliseconds) next to each key it is given, removes both once that time has passed, and wraps `Storage.prototype.setItem` on the page to date later writes of those keys.
 
 ## 🌐 External Services
 
-`RemoteLogo` requests its `url` on the server (by default `cdn.jsdelivr.net/gh/TuwaIO/workflows@main/preview/logo_v2.svg`), cached by Next.js for 24 hours. `loadPolicy` requests `raw.githubusercontent.com/TuwaIO/workflows/main/docs/<slug>.json` (a translation: `docs/<language>/<slug>.json`, and the English file when it does not exist) on the server, cached by Next.js for an hour by default. The Download PDF button of `PolicyDocument` links to the PDF on the same host; the browser requests it only when it is clicked. The other components send no requests.
+`RemoteLogo` requests its `url` on the server (by default `tuwa.io/brand/logo_v2.svg`), cached by Next.js for 24 hours. `loadPolicy` requests `raw.githubusercontent.com/TuwaIO/workflows/main/docs/<slug>.json` (a translation: `docs/<language>/<slug>.json`, and the English file when it does not exist) on the server, cached by Next.js for an hour by default. The Download PDF button of `PolicyDocument` links to the PDF on the same host; the browser requests it only when it is clicked. The other components send no requests.
 
 ---
 

package/dist/components/Footer.d.cts

@@ -1,4 +1,4 @@
-import * as React from 'react';
+import * as react from 'react';
 import { NavProps } from './NavBar.cjs';
 
 /**
@@ -10,6 +10,6 @@ import { NavProps } from './NavBar.cjs';
  * @param props - See {@link NavProps}.
  * @returns The footer.
  */
-declare function Footer({ links, logo }: NavProps): React.JSX.Element;
+declare function Footer({ links, logo }: NavProps): react.JSX.Element;
 
 export { Footer };

package/dist/components/Footer.d.ts

@@ -1,4 +1,4 @@
-import * as React from 'react';
+import * as react from 'react';
 import { NavProps } from './NavBar.js';
 
 /**
@@ -10,6 +10,6 @@ import { NavProps } from './NavBar.js';
  * @param props - See {@link NavProps}.
  * @returns The footer.
  */
-declare function Footer({ links, logo }: NavProps): React.JSX.Element;
+declare function Footer({ links, logo }: NavProps): react.JSX.Element;
 
 export { Footer };

package/dist/components/LocaleSwitcher.cjs

@@ -0,0 +1,474 @@
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var LocaleSwitcher_exports = {};
+__export(LocaleSwitcher_exports, {
+  DEFAULT_LOCALES: () => DEFAULT_LOCALES,
+  LocaleSwitcher: () => LocaleSwitcher,
+  getLocaleFlag: () => getLocaleFlag
+});
+module.exports = __toCommonJS(LocaleSwitcher_exports);
+var import_jsx_runtime = require("react/jsx-runtime");
+var import_utils = require("@tuwaio/nova-core/utils");
+var import_react = require("react");
+function FlagUK({ className }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("svg", { viewBox: "0 0 640 480", className, "aria-hidden": "true", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { fill: "#012169", d: "M0 0h640v480H0z" }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { fill: "#FFF", d: "m75 0 245 180L565 0h75v60L435 240l205 180v60h-75L320 300 75 480H0v-60l205-180L0 60V0h75z" }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "path",
+      {
+        fill: "#C8102E",
+        d: "m425 285 215 165v30h-35L380 300l45-15zM215 195 0 30v-30h35l225 180-45 15zm0 90L0 450v30h35l225-180-45-15zm210-90L640 30v-30h-35L380 180l45 15z"
+      }
+    ),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { fill: "#FFF", d: "M250 0h140v480H250zM0 170h640v140H0z" }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { fill: "#C8102E", d: "M276 0h88v480h-88zM0 196h640v88H0z" })
+  ] });
+}
+function FlagUkraine({ className }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("svg", { viewBox: "0 0 640 480", className, "aria-hidden": "true", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { fill: "#0057b7", d: "M0 0h640v240H0z" }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { fill: "#ffd700", d: "M0 240h640v240H0z" })
+  ] });
+}
+function FlagChina({ className }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("svg", { viewBox: "0 0 640 480", className, "aria-hidden": "true", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("rect", { width: "640", height: "480", fill: "#ee1c25" }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "path",
+      {
+        fill: "#ffde00",
+        d: "M120 72l14.1 43.4H180l-36.9 26.8 14.1 43.4-37.2-26.8-37.2 26.8 14.1-43.4L60 115.4h45.9z"
+      }
+    ),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("circle", { cx: "200", cy: "40", r: "12", fill: "#ffde00" }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("circle", { cx: "240", cy: "80", r: "12", fill: "#ffde00" }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("circle", { cx: "240", cy: "140", r: "12", fill: "#ffde00" }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("circle", { cx: "200", cy: "180", r: "12", fill: "#ffde00" })
+  ] });
+}
+function ChevronArrowWithAnim({ isOpen, className }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+    "span",
+    {
+      className: (0, import_utils.cn)(
+        "tuwadocs:relative tuwadocs:inline-flex tuwadocs:h-3.5 tuwadocs:w-3.5 tuwadocs:items-center tuwadocs:justify-center tuwadocs:overflow-hidden tuwadocs:shrink-0",
+        className
+      ),
+      "aria-hidden": "true",
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "svg",
+          {
+            viewBox: "0 0 24 24",
+            fill: "none",
+            strokeWidth: 2,
+            stroke: "currentColor",
+            className: (0, import_utils.cn)(
+              "tuwadocs:absolute tuwadocs:h-3.5 tuwadocs:w-3.5 tuwadocs:transition-all tuwadocs:duration-400 tuwadocs:ease-out tuwadocs:motion-reduce:transition-none tuwadocs:motion-reduce:transform-none",
+              isOpen ? "tuwadocs:opacity-0 -tuwadocs:translate-y-[3px] tuwadocs:scale-y-[0.8] tuwadocs:pointer-events-none" : "tuwadocs:opacity-100 tuwadocs:translate-y-0 tuwadocs:scale-y-100"
+            ),
+            children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "m19.5 8.25-7.5 7.5-7.5-7.5" })
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "svg",
+          {
+            viewBox: "0 0 24 24",
+            fill: "none",
+            strokeWidth: 2,
+            stroke: "currentColor",
+            className: (0, import_utils.cn)(
+              "tuwadocs:absolute tuwadocs:h-3.5 tuwadocs:w-3.5 tuwadocs:transition-all tuwadocs:duration-400 tuwadocs:ease-out tuwadocs:motion-reduce:transition-none tuwadocs:motion-reduce:transform-none",
+              isOpen ? "tuwadocs:opacity-100 tuwadocs:translate-y-0 tuwadocs:scale-y-100" : "tuwadocs:opacity-0 tuwadocs:translate-y-[3px] tuwadocs:scale-y-[0.8] tuwadocs:pointer-events-none"
+            ),
+            children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "m4.5 15.75 7.5-7.5 7.5 7.5" })
+          }
+        )
+      ]
+    }
+  );
+}
+function getLocaleFlag(code) {
+  const normalized = code.toLowerCase();
+  const flagClass = "tuwadocs:h-3 tuwadocs:w-4 tuwadocs:rounded-[2px] tuwadocs:object-cover tuwadocs:shadow-xs tuwadocs:border tuwadocs:border-black/10 tuwadocs:dark:border-white/20 tuwadocs:shrink-0";
+  if (normalized === "en" || normalized === "en-us" || normalized === "en-gb") {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FlagUK, { className: flagClass });
+  }
+  if (normalized === "uk" || normalized === "ua") {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FlagUkraine, { className: flagClass });
+  }
+  if (normalized === "zh" || normalized === "zh-cn" || normalized === "zh-hans") {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FlagChina, { className: flagClass });
+  }
+  return void 0;
+}
+const DEFAULT_LOCALES = [
+  { code: "en", label: "English", short: "EN" },
+  { code: "uk", label: "\u0423\u043A\u0440\u0430\u0457\u043D\u0441\u044C\u043A\u0430", short: "UK" },
+  { code: "zh-CN", label: "\u7B80\u4F53\u4E2D\u6587", short: "ZH" }
+];
+function resolveLatinChar(event) {
+  if (event.ctrlKey || event.metaKey || event.altKey) {
+    return null;
+  }
+  if (/^[a-zA-Z]$/.test(event.key)) {
+    return event.key.toLowerCase();
+  }
+  if (event.code && event.code.startsWith("Key")) {
+    return event.code.slice(3).toLowerCase();
+  }
+  return null;
+}
+function matchesLocaleOption(item, char) {
+  const code = item.code.toLowerCase();
+  const short = (item.short ?? "").toLowerCase();
+  const label = item.label.toLowerCase();
+  if (code.startsWith(char) || short.startsWith(char) || label.startsWith(char)) {
+    return true;
+  }
+  if ((code.startsWith("zh") || short === "zh") && (char === "z" || char === "c")) {
+    return true;
+  }
+  if ((code.startsWith("uk") || code.startsWith("ua") || short === "uk" || short === "ua") && char === "u") {
+    return true;
+  }
+  if ((code.startsWith("es") || short === "es") && char === "s") {
+    return true;
+  }
+  if ((code.startsWith("de") || short === "de") && char === "g") {
+    return true;
+  }
+  return false;
+}
+function LocaleSwitcher({
+  locale,
+  onSelect,
+  locales = DEFAULT_LOCALES,
+  placement: placementProp = "auto",
+  className,
+  ariaLabel = "Select language",
+  nativeTouch = true
+}) {
+  const [mounted, setMounted] = (0, import_react.useState)(false);
+  const [isOpen, setIsOpen] = (0, import_react.useState)(false);
+  const [activeIndex, setActiveIndex] = (0, import_react.useState)(0);
+  const [resolvedPlacement, setResolvedPlacement] = (0, import_react.useState)("bottom");
+  const [isTouch, setIsTouch] = (0, import_react.useState)(false);
+  const listboxId = (0, import_react.useId)();
+  const containerRef = (0, import_react.useRef)(null);
+  const buttonRef = (0, import_react.useRef)(null);
+  const listRef = (0, import_react.useRef)(null);
+  (0, import_react.useEffect)(() => {
+    setMounted(true);
+    if (typeof window === "undefined") return;
+    const query = window.matchMedia("(pointer: coarse)");
+    const updateTouch = () => {
+      setIsTouch(query.matches && !window.matchMedia("(pointer: fine)").matches);
+    };
+    updateTouch();
+    query.addEventListener?.("change", updateTouch);
+    return () => {
+      query.removeEventListener?.("change", updateTouch);
+    };
+  }, []);
+  const updatePlacement = () => {
+    if (placementProp !== "auto") {
+      setResolvedPlacement(placementProp);
+      return;
+    }
+    if (buttonRef.current) {
+      const rect = buttonRef.current.getBoundingClientRect();
+      const spaceBelow = window.innerHeight - rect.bottom;
+      const spaceAbove = rect.top;
+      const estimatedHeight = Math.min(locales.length * 40, 260) + 16;
+      setResolvedPlacement(spaceBelow < estimatedHeight && spaceAbove > spaceBelow ? "top" : "bottom");
+    }
+  };
+  const openMenu = () => {
+    if (isTouch) return;
+    updatePlacement();
+    const currentIndex = locales.findIndex((item) => item.code === locale);
+    setActiveIndex(currentIndex >= 0 ? currentIndex : 0);
+    setIsOpen(true);
+  };
+  const closeMenu = () => {
+    setIsOpen(false);
+    buttonRef.current?.focus();
+  };
+  const pickLocale = (code) => {
+    closeMenu();
+    if (code !== locale) {
+      onSelect(code);
+    }
+  };
+  (0, import_react.useEffect)(() => {
+    if (!isOpen) return;
+    listRef.current?.focus();
+    const onPointerDown = (event) => {
+      if (!containerRef.current?.contains(event.target)) {
+        setIsOpen(false);
+      }
+    };
+    document.addEventListener("pointerdown", onPointerDown);
+    return () => {
+      document.removeEventListener("pointerdown", onPointerDown);
+    };
+  }, [isOpen]);
+  (0, import_react.useEffect)(() => {
+    if (!isOpen) return;
+    const activeEl = document.getElementById(`${listboxId}-option-${locales[activeIndex]?.code}`);
+    activeEl?.scrollIntoView({ block: "nearest" });
+  }, [activeIndex, isOpen, listboxId, locales]);
+  const handleKeyDown = (event) => {
+    const last = locales.length - 1;
+    if (event.key === "ArrowDown") {
+      event.preventDefault();
+      if (!isOpen) {
+        openMenu();
+      } else {
+        setActiveIndex((prev) => prev < last ? prev + 1 : 0);
+      }
+      return;
+    }
+    if (event.key === "ArrowUp") {
+      event.preventDefault();
+      if (!isOpen) {
+        openMenu();
+      } else {
+        setActiveIndex((prev) => prev > 0 ? prev - 1 : last);
+      }
+      return;
+    }
+    if (event.key === "Home" && isOpen) {
+      event.preventDefault();
+      setActiveIndex(0);
+      return;
+    }
+    if (event.key === "End" && isOpen) {
+      event.preventDefault();
+      setActiveIndex(last);
+      return;
+    }
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      if (!isOpen) {
+        openMenu();
+      } else {
+        const targetOption = locales[activeIndex];
+        if (targetOption) {
+          pickLocale(targetOption.code);
+        }
+      }
+      return;
+    }
+    if (event.key === "Escape") {
+      if (isOpen) {
+        event.preventDefault();
+        event.stopPropagation();
+        closeMenu();
+      }
+      return;
+    }
+    if (event.key === "Tab") {
+      if (isOpen) {
+        closeMenu();
+      }
+      return;
+    }
+    const char = resolveLatinChar(event);
+    if (char) {
+      const matchAfter = locales.findIndex((item, idx) => idx > activeIndex && matchesLocaleOption(item, char));
+      const matchFromStart = locales.findIndex((item) => matchesLocaleOption(item, char));
+      const targetIndex = matchAfter >= 0 ? matchAfter : matchFromStart;
+      if (targetIndex >= 0) {
+        event.preventDefault();
+        if (!isOpen) {
+          updatePlacement();
+          setActiveIndex(targetIndex);
+          setIsOpen(true);
+        } else {
+          setActiveIndex(targetIndex);
+        }
+      }
+    }
+  };
+  const defaultStyles = "tuwadocs:bg-black/5 tuwadocs:border-black/5 tuwadocs:hover:bg-black/10 tuwadocs:dark:bg-white/10 tuwadocs:dark:border-white/10 tuwadocs:dark:hover:bg-white/20";
+  const staticSize = "tuwadocs:h-10 tuwadocs:w-[5.25rem] tuwadocs:md:h-8 tuwadocs:md:w-[4.75rem]";
+  if (!mounted) {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "div",
+      {
+        className: (0, import_utils.cn)(
+          "tuwadocs:relative tuwadocs:flex tuwadocs:rounded-[var(--tuwa-rounded-corners)] tuwadocs:border tuwadocs:opacity-0",
+          staticSize,
+          defaultStyles,
+          className
+        )
+      }
+    );
+  }
+  const activeOption = locales.find((item) => item.code === locale) ?? locales[0];
+  const shortText = activeOption?.short ?? activeOption?.code?.slice(0, 2).toUpperCase() ?? "EN";
+  const activeFlag = activeOption?.flag ?? getLocaleFlag(activeOption?.code ?? "en");
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { ref: containerRef, className: (0, import_utils.cn)("tuwadocs:relative tuwadocs:inline-block", className), children: [
+    nativeTouch && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "select",
+      {
+        value: locale,
+        onChange: (event) => pickLocale(event.target.value),
+        "aria-label": ariaLabel,
+        tabIndex: isTouch ? 0 : -1,
+        "aria-hidden": !isTouch,
+        className: "tuwadocs:absolute tuwadocs:inset-0 tuwadocs:z-10 tuwadocs:h-full tuwadocs:w-full tuwadocs:cursor-pointer tuwadocs:appearance-none tuwadocs:border-none tuwadocs:bg-transparent tuwadocs:opacity-0 tuwadocs:outline-none tuwadocs:hidden tuwadocs:pointer-coarse:block tuwadocs:pointer-fine:hidden",
+        children: locales.map((item) => /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("option", { value: item.code, lang: item.code, children: [
+          item.label,
+          " (",
+          item.short ?? item.code.toUpperCase(),
+          ")"
+        ] }, item.code))
+      }
+    ),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+      "button",
+      {
+        ref: buttonRef,
+        type: "button",
+        tabIndex: isTouch ? -1 : 0,
+        "aria-hidden": isTouch ? true : void 0,
+        onClick: () => isOpen ? closeMenu() : openMenu(),
+        onKeyDown: handleKeyDown,
+        className: (0, import_utils.cn)(
+          "tuwadocs:group tuwadocs:relative tuwadocs:flex tuwadocs:cursor-pointer tuwadocs:items-center tuwadocs:justify-between tuwadocs:rounded-[var(--tuwa-rounded-corners)] tuwadocs:px-2 tuwadocs:transition-all tuwadocs:duration-300 tuwadocs:ease-in-out tuwadocs:backdrop-blur-sm tuwadocs:border tuwadocs:motion-reduce:transition-none",
+          "tuwadocs:focus-visible:ring-2 tuwadocs:focus-visible:ring-[var(--tuwa-text-accent)] tuwadocs:focus-visible:outline-none tuwadocs:focus-visible:ring-offset-1 tuwadocs:focus-visible:ring-offset-[var(--tuwa-bg-primary)]",
+          staticSize,
+          defaultStyles
+        ),
+        "aria-haspopup": "listbox",
+        "aria-expanded": isOpen,
+        "aria-controls": isOpen ? listboxId : void 0,
+        children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            "span",
+            {
+              "aria-hidden": "true",
+              className: "tuwadocs:flex tuwadocs:items-center tuwadocs:justify-center tuwadocs:shrink-0",
+              children: activeFlag
+            }
+          ),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "tuwadocs:w-5 tuwadocs:text-center tuwadocs:font-mono tuwadocs:text-xs tuwadocs:font-bold tuwadocs:tracking-tight tuwadocs:text-[var(--tuwa-text-primary)] tuwadocs:shrink-0", children: shortText }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", { className: "tuwadocs:sr-only", children: [
+            ", ",
+            activeOption.label,
+            " \u2014 ",
+            ariaLabel
+          ] }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            ChevronArrowWithAnim,
+            {
+              isOpen,
+              className: "tuwadocs:text-[var(--tuwa-text-secondary)] tuwadocs:group-hover:text-[var(--tuwa-text-primary)]"
+            }
+          )
+        ]
+      }
+    ),
+    isOpen && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "div",
+      {
+        ref: listRef,
+        id: listboxId,
+        role: "listbox",
+        tabIndex: -1,
+        "aria-label": ariaLabel,
+        "aria-activedescendant": `${listboxId}-option-${locales[activeIndex]?.code}`,
+        onKeyDown: handleKeyDown,
+        className: (0, import_utils.cn)(
+          "tuwadocs:absolute tuwadocs:right-0 tuwadocs:z-50 tuwadocs:min-w-[12rem] tuwadocs:max-h-[min(20rem,60vh)] tuwadocs:overflow-y-auto tuwadocs:overflow-x-hidden tuwadocs:rounded-[var(--tuwa-rounded-corners)] tuwadocs:border tuwadocs:border-[var(--tuwa-border-primary)] tuwadocs:bg-[var(--tuwa-bg-primary)]/95 tuwadocs:p-0 tuwadocs:shadow-xl tuwadocs:backdrop-blur-md tuwadocs:outline-none",
+          resolvedPlacement === "top" ? "tuwadocs:bottom-full tuwadocs:mb-1.5" : "tuwadocs:top-full tuwadocs:mt-1.5"
+        ),
+        children: locales.map((item, i) => {
+          const isSelected = item.code === locale;
+          const isFocused = i === activeIndex;
+          const flag = item.flag ?? getLocaleFlag(item.code);
+          return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+            "button",
+            {
+              id: `${listboxId}-option-${item.code}`,
+              type: "button",
+              role: "option",
+              lang: item.code,
+              tabIndex: -1,
+              "aria-selected": isSelected,
+              onClick: () => pickLocale(item.code),
+              onPointerMove: () => {
+                if (activeIndex !== i) setActiveIndex(i);
+              },
+              className: (0, import_utils.cn)(
+                "tuwadocs:relative tuwadocs:flex tuwadocs:w-full tuwadocs:cursor-pointer tuwadocs:items-center tuwadocs:justify-between tuwadocs:gap-2.5 tuwadocs:px-3.5 tuwadocs:py-2.5 tuwadocs:text-xs tuwadocs:transition-colors tuwadocs:outline-none",
+                "tuwadocs:focus-visible:ring-1 tuwadocs:focus-visible:ring-inset tuwadocs:focus-visible:ring-[var(--tuwa-text-accent)]",
+                isSelected ? isFocused ? "tuwadocs:bg-gradient-to-r tuwadocs:from-[var(--tuwa-text-accent)]/25 tuwadocs:via-[var(--tuwa-text-accent)]/10 tuwadocs:to-transparent tuwadocs:text-[var(--tuwa-text-primary)] tuwadocs:font-bold" : "tuwadocs:bg-gradient-to-r tuwadocs:from-[var(--tuwa-text-accent)]/15 tuwadocs:via-[var(--tuwa-text-accent)]/5 tuwadocs:to-transparent tuwadocs:text-[var(--tuwa-text-primary)] tuwadocs:font-bold" : isFocused ? "tuwadocs:bg-[var(--tuwa-bg-muted)]/70 tuwadocs:text-[var(--tuwa-text-primary)]" : "tuwadocs:text-[var(--tuwa-text-secondary)] tuwadocs:hover:bg-[var(--tuwa-bg-muted)]/50 tuwadocs:hover:text-[var(--tuwa-text-primary)]"
+              ),
+              children: [
+                isSelected && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                  "span",
+                  {
+                    className: "tuwadocs:absolute tuwadocs:left-0 tuwadocs:top-0 tuwadocs:bottom-0 tuwadocs:w-[3px] tuwadocs:bg-[var(--tuwa-text-accent)] tuwadocs:shadow-[0_0_8px_var(--tuwa-text-accent)]",
+                    "aria-hidden": "true"
+                  }
+                ),
+                /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "tuwadocs:flex tuwadocs:items-center tuwadocs:gap-2 tuwadocs:truncate", children: [
+                  flag && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { "aria-hidden": "true", className: "tuwadocs:shrink-0", children: flag }),
+                  /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "tuwadocs:truncate", children: item.label })
+                ] }),
+                /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "tuwadocs:flex tuwadocs:items-center tuwadocs:gap-1.5 tuwadocs:shrink-0", children: [
+                  /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                    "span",
+                    {
+                      className: (0, import_utils.cn)(
+                        "tuwadocs:font-mono tuwadocs:text-[10px] tuwadocs:uppercase tuwadocs:px-1.5 tuwadocs:py-0.5 tuwadocs:rounded",
+                        isSelected ? "tuwadocs:bg-[var(--tuwa-text-accent)]/15 tuwadocs:text-[var(--tuwa-text-accent)] tuwadocs:font-bold" : "tuwadocs:text-[var(--tuwa-text-tertiary)]"
+                      ),
+                      children: item.short ?? item.code
+                    }
+                  ),
+                  isSelected && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                    "span",
+                    {
+                      className: "tuwadocs:h-1.5 tuwadocs:w-1.5 tuwadocs:rounded-full tuwadocs:bg-[var(--tuwa-text-accent)] tuwadocs:shadow-[0_0_8px_var(--tuwa-text-accent)]",
+                      "aria-hidden": "true"
+                    }
+                  )
+                ] })
+              ]
+            },
+            item.code
+          );
+        })
+      }
+    )
+  ] });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_LOCALES,
+  LocaleSwitcher,
+  getLocaleFlag
+});

package/dist/components/LocaleSwitcher.d.cts

@@ -0,0 +1,89 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * Returns a locally embedded SVG flag node for a given locale code.
+ *
+ * Supported built-in codes:
+ * - English: `'en'`, `'en-US'`, `'en-GB'`
+ * - Ukrainian: `'uk'`, `'ua'`
+ * - Chinese: `'zh'`, `'zh-CN'`, `'zh-Hans'`
+ *
+ * @param code - The BCP-47 or ISO language tag (e.g. `'en'`, `'uk'`, `'zh-CN'`).
+ * @returns The SVG icon node or `undefined` if no built-in flag is available.
+ */
+declare function getLocaleFlag(code: string): ReactNode;
+/**
+ * A supported locale option for {@link LocaleSwitcher}.
+ */
+interface LocaleOption {
+    /** The language tag or locale code, for example `'en'`, `'uk'`, or `'zh-CN'`. */
+    code: string;
+    /** Full native name of the language, for example `'English'`, `'Українська'`, or `'简体中文'`. */
+    label: string;
+    /** Short label displayed on the compact trigger button, for example `'EN'`, `'UK'`, or `'ZH'`. */
+    short?: string;
+    /** Optional custom flag element. If omitted, built-in vector flags are used. */
+    flag?: ReactNode;
+}
+/**
+ * Default list of supported locales across the TUWA documentation ecosystem.
+ */
+declare const DEFAULT_LOCALES: readonly LocaleOption[];
+/**
+ * Props of {@link LocaleSwitcher}.
+ */
+interface LocaleSwitcherProps {
+    /** The currently active locale code (e.g. `'en'`, `'uk'`). */
+    locale: string;
+    /** Callback fired when a new locale is selected by the user. */
+    onSelect: (code: string) => void;
+    /** The list of available locales. Defaults to {@link DEFAULT_LOCALES}. */
+    locales?: readonly LocaleOption[] | LocaleOption[];
+    /** Preferred placement of the dropdown menu (`'auto'`, `'bottom'`, or `'top'`). Defaults to `'auto'`. */
+    placement?: 'auto' | 'bottom' | 'top';
+    /** Optional additional CSS classes for the root container. */
+    className?: string;
+    /** Accessible name for the button and listbox. Defaults to `'Select language'`. */
+    ariaLabel?: string;
+    /**
+     * Whether to render an invisible native `<select>` overlay on mobile touch devices (`pointer: coarse`).
+     * When `true`, tapping on iOS or Android summons the native system wheel/sheet picker.
+     * Defaults to `true`.
+     */
+    nativeTouch?: boolean;
+}
+/**
+ * A glassmorphic language select dropdown matching the visual footprint, theme variables, and interaction
+ * standards of `ThemeSwitcher`.
+ *
+ * ### Architectural Features:
+ * - **Zero Layout Shift:** Rigid static dimensions (`w-[5.25rem] md:w-[4.75rem]`) and fixed-width label slots
+ *   prevent any layout reflow or navigation jumping when switching between language codes of varying character widths.
+ * - **Nova Motion Language:** Chevron arrow utilizes directional vertical translation (±3px), vertical scale
+ *   compression (`scaleY(0.8)`), and opacity curves matching Nova UI Kit's `ChevronArrowWithAnim`.
+ * - **Flush Edge Indicator:** Replaced traditional checkboxes with a flush, zero-margin left-edge blue accent bar
+ *   and glowing status indicator, cleanly abutting the dropdown boundary.
+ * - **Collision Detection & Dynamic Placement:** When configured with `'auto'` placement, dynamically calculates
+ *   available viewport clearance below the trigger button. If rendered inside a mobile sheet, drawer, or footer
+ *   with insufficient bottom clearance, it automatically opens upwards (`bottom-full`).
+ * - **Layout-Independent Latin Typeahead (WCAG 2.1.1):** Normalizes keystrokes through physical `event.code`
+ *   to ensure keys like `E`, `U`, and `Z` reliably navigate to English, Ukrainian, and Chinese regardless of the user's
+ *   active OS keyboard layout.
+ * - **Native Touch Device Support (`pointer: coarse`):** On mobile devices, an invisible native `<select>` overlay
+ *   activates, triggering the operating system's native wheel picker (iOS Safari) or bottom sheet dialog (Android Chrome)
+ *   with full system haptics and touch fluidness while retaining the custom visual trigger design.
+ * - **WCAG 2.1 & 2.2 AA/AAA Compliance:**
+ *   - WCAG 2.5.3 (Label in Name): The accessible name of the button begins with the visible label text.
+ *   - WCAG 3.1.2 (Language of Parts): Every option specifies its native `lang` attribute for screen readers.
+ *   - WCAG 2.4.7 (Focus Visible): High-contrast focus rings with distinct offset colors.
+ *   - WCAG 2.3.3 (Animation from Interactions): `motion-reduce:transition-none` disables transitions for sensitive users.
+ *   - WCAG 4.1.2 (Name, Role, Value): WAI-ARIA `listbox`, `option`, `aria-activedescendant`, and `aria-selected`.
+ *
+ * @param props - Component properties (see {@link LocaleSwitcherProps}).
+ * @returns The rendered locale switcher trigger button, touch overlay, and dropdown menu.
+ */
+declare function LocaleSwitcher({ locale, onSelect, locales, placement: placementProp, className, ariaLabel, nativeTouch, }: LocaleSwitcherProps): react.JSX.Element;
+
+export { DEFAULT_LOCALES, LocaleSwitcher, getLocaleFlag };
+export type { LocaleOption, LocaleSwitcherProps };