feat(docs): colocate localized package sandboxes

docs/src/components/sandbox/index.ts

@@ -7,6 +7,8 @@ export {
 export {
   defineSandbox,
   type SandboxDefinition,
+  type SandboxLocalizedText,
+  type SandboxPreviewProps,
   type SandboxPreviewModule,
   type SandboxSource,
   type SandboxSourceModule,

docs/src/components/sandbox/registry.ts

@@ -5,7 +5,10 @@ type SandboxManifestModule = {
 }
 
 const manifestModules = import.meta.glob<SandboxManifestModule>(
-  "../../sandboxes/*/*/sandbox.ts",
+  [
+    "../../sandboxes/*/*/sandbox.ts",
+    "../../../../packages/*/docs/sandboxes/*/sandbox.ts",
+  ],
   { eager: true }
 )
 

docs/src/components/sandbox/sandbox-env.d.ts

@@ -0,0 +1,4 @@
+declare module "*?raw" {
+  const source: string
+  export default source
+}

docs/src/components/sandbox/sandbox-frame.tsx

@@ -1,16 +1,20 @@
 import React from "react"
 import { createPortal } from "react-dom"
 
+import type { DocLocale } from "../../content/types"
+
 const minimumFrameHeight = 288
 
 export function SandboxFrame({
   children,
   fill = false,
+  locale,
   reloadKey,
   title,
 }: {
   children: React.ReactNode
   fill?: boolean
+  locale: DocLocale
   reloadKey: number
   title: string
 }) {
@@ -56,6 +60,7 @@ export function SandboxFrame({
         document.documentElement.style.colorScheme
     }
     syncDocumentTheme()
+    frameDocument.documentElement.lang = locale
 
     const themeObserver = new MutationObserver(syncDocumentTheme)
     themeObserver.observe(document.documentElement, {
@@ -70,7 +75,7 @@ export function SandboxFrame({
       themeObserver.disconnect()
       setMountNode(null)
     }
-  }, [reloadKey])
+  }, [locale, reloadKey])
 
   React.useEffect(() => {
     if (!mountNode || fill) return

docs/src/components/sandbox/sandbox.tsx

@@ -1,13 +1,15 @@
 import React from "react"
 import { Icon } from "@icones/react"
 
-import { useTranslate } from "../../lib/locale"
+import { useLocale, useTranslate } from "../../lib/locale"
 import { getSandboxDefinition } from "./registry"
 import { SandboxErrorBoundary } from "./sandbox-error-boundary"
 import { SandboxFrame } from "./sandbox-frame"
 import { highlightSource, type HighlightedSource } from "./highlight-source"
 import type {
   SandboxDefinition,
+  SandboxLocalizedText,
+  SandboxPreviewProps,
   SandboxPreviewModule,
   SandboxSource,
 } from "./types"
@@ -19,7 +21,7 @@ const codeFontSizes = [12, 13, 14, 16] as const
 export type SandboxProps = {
   className?: string
   example: string
-  title?: string
+  title?: SandboxLocalizedText
 }
 
 export function Sandbox({ className, example, title }: SandboxProps) {
@@ -51,7 +53,7 @@ export type SingleFileSandboxProps = {
   component: React.ComponentType
   filename?: string
   source: string
-  title?: string
+  title?: SandboxLocalizedText
 }
 
 export function SingleFileSandbox({
@@ -64,7 +66,9 @@ export function SingleFileSandbox({
   const definition = React.useMemo<SandboxDefinition>(
     () => ({
       defaultFile: filename,
-      entry: async () => ({ default: component }),
+      entry: async () => ({
+        default: component as React.ComponentType<SandboxPreviewProps>,
+      }),
       files: { [filename]: source },
       id: `single-file:${filename}`,
       title,
@@ -82,9 +86,10 @@ function SandboxViewer({
 }: {
   className?: string
   definition: SandboxDefinition
-  title?: string
+  title?: SandboxLocalizedText
 }) {
   const rootRef = React.useRef<HTMLElement>(null)
+  const locale = useLocale()
   const t = useTranslate()
   const filenames = React.useMemo(
     () => Object.keys(definition.files),
@@ -105,7 +110,11 @@ function SandboxViewer({
   const [reloadKey, setReloadKey] = React.useState(0)
   const [copied, setCopied] = React.useState(false)
   const [fullscreen, setFullscreen] = React.useState(false)
-  const resolvedTitle = title ?? definition.title ?? definition.id
+  const resolvedTitle = resolveSandboxText(
+    title ?? definition.title,
+    locale,
+    definition.id
+  )
 
   React.useEffect(() => {
     const root = rootRef.current
@@ -288,6 +297,7 @@ function SandboxViewer({
       {view === "preview" ? (
         <SandboxFrame
           fill={fullscreen}
+          locale={locale}
           reloadKey={reloadKey}
           title={resolvedTitle}
         >
@@ -297,7 +307,10 @@ function SandboxViewer({
                 {previewError.message}
               </SandboxMessage>
             ) : previewModule ? (
-              React.createElement(previewModule.default, { key: reloadKey })
+              React.createElement(previewModule.default, {
+                key: reloadKey,
+                locale,
+              })
             ) : (
               <SandboxMessage>
                 {t({ zh: "正在加载预览…", us: "Loading preview…" })}
@@ -350,6 +363,15 @@ function SandboxViewer({
   )
 }
 
+function resolveSandboxText(
+  value: SandboxLocalizedText | undefined,
+  locale: "en-US" | "zh-Hans",
+  fallback: string
+) {
+  if (typeof value === "string") return value
+  return value?.[locale] ?? fallback
+}
+
 function CodeFontSizeControl({
   decreaseLabel,
   increaseLabel,

docs/src/components/sandbox/types.ts

@@ -1,7 +1,15 @@
 import type { ComponentType } from "react"
 
+import type { DocLocale } from "../../content/types"
+
+export type SandboxLocalizedText = string | Readonly<Record<DocLocale, string>>
+
+export type SandboxPreviewProps = {
+  locale: DocLocale
+}
+
 export type SandboxPreviewModule = {
-  default: ComponentType
+  default: ComponentType<SandboxPreviewProps>
 }
 
 export type SandboxSourceModule = {
@@ -17,7 +25,7 @@ export type SandboxDefinition = {
   entry: () => Promise<SandboxPreviewModule>
   files: Readonly<Record<string, SandboxSource>>
   id: string
-  title?: string
+  title?: SandboxLocalizedText
 }
 
 export function defineSandbox<const Definition extends SandboxDefinition>(

docs/src/index.css

@@ -5,6 +5,8 @@
 @import "@workspace/page/globals.css";
 @import "@workspace/search/globals.css";
 
+@source "../../packages/*/docs/**/*.{mdx,ts,tsx}";
+
 @custom-variant dark (&:where(.dark, .dark *));
 
 @layer base {

docs/src/sandboxes/appearance/theme-toggle/App.tsx

@@ -1,22 +0,0 @@
-import React from "react"
-import type { ThemeColorConfig } from "@workspace/appearance/theme"
-
-import { AccentPicker } from "./AccentPicker"
-
-export default function ThemeColorsExample() {
-  const [config, setConfig] = React.useState<ThemeColorConfig>({
-    accentColor: "indigo",
-    baseColor: "neutral",
-  })
-
-  return (
-    <div className="mx-auto flex max-w-xl flex-col gap-6">
-      <AccentPicker config={config} onConfigChange={setConfig} />
-      <AccentPicker
-        config={config}
-        variant="swatch"
-        onConfigChange={setConfig}
-      />
-    </div>
-  )
-}

docs/tsconfig.app.json

@@ -22,5 +22,9 @@
     "erasableSyntaxOnly": true,
     "noFallthroughCasesInSwitch": true
   },
-  "include": ["src"]
-}
+  "include": [
+    "src",
+    "../packages/*/docs/sandboxes/**/*.ts",
+    "../packages/*/docs/sandboxes/**/*.tsx"
+  ]
+}

docs/tsconfig.sandbox.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.app.json",
+  "compilerOptions": {
+    "types": []
+  },
+  "files": ["src/components/sandbox/sandbox-env.d.ts"],
+  "include": []
+}

packages/appearance/docs/sandboxes/theme-toggle/AccentPicker.tsx

@@ -8,15 +8,17 @@ import type { ThemeColorConfig } from "@workspace/appearance/theme"
 export function AccentPicker({
   config,
   onConfigChange,
+  title,
   variant,
 }: {
   config: ThemeColorConfig
   onConfigChange: (config: ThemeColorConfig) => void
+  title: string
   variant?: ThemeColorPickerVariant
 }) {
   return (
     <ThemeColorPicker
-      title="Accent color"
+      title={title}
       swatches={accentColorSwatches}
       value={config.accentColor}
       variant={variant}

packages/appearance/docs/sandboxes/theme-toggle/App.tsx

@@ -0,0 +1,43 @@
+import React from "react"
+import { I18nProvider } from "@workspace/i18n"
+import { messages as englishMessages } from "@workspace/appearance/locales/en-US"
+import { messages as chineseMessages } from "@workspace/appearance/locales/zh-Hans"
+import type { ThemeColorConfig } from "@workspace/appearance/theme"
+
+import { AccentPicker } from "./AccentPicker"
+
+const catalogs = {
+  "en-US": englishMessages,
+  "zh-Hans": chineseMessages,
+} as const
+
+export default function ThemeColorsExample({
+  locale,
+}: {
+  locale: "en-US" | "zh-Hans"
+}) {
+  const [config, setConfig] = React.useState<ThemeColorConfig>({
+    accentColor: "indigo",
+    baseColor: "neutral",
+  })
+
+  const title = locale === "zh-Hans" ? "强调色" : "Accent color"
+
+  return (
+    <I18nProvider catalogs={catalogs} locale={locale}>
+      <div className="mx-auto flex max-w-xl flex-col gap-6">
+        <AccentPicker
+          config={config}
+          title={title}
+          onConfigChange={setConfig}
+        />
+        <AccentPicker
+          config={config}
+          title={title}
+          variant="swatch"
+          onConfigChange={setConfig}
+        />
+      </div>
+    </I18nProvider>
+  )
+}

packages/appearance/docs/sandboxes/theme-toggle/sandbox.ts

@@ -1,12 +1,13 @@
-import { defineSandbox } from "../../../components/sandbox"
-
-export default defineSandbox({
+export default {
   id: "appearance/theme-colors",
-  title: "Controlled theme colors",
+  title: {
+    "en-US": "Controlled theme colors",
+    "zh-Hans": "受控主题颜色",
+  },
   entry: () => import("./App"),
   files: {
     "App.tsx": () => import("./App.tsx?raw"),
     "AccentPicker.tsx": () => import("./AccentPicker.tsx?raw"),
   },
   defaultFile: "App.tsx",
-})
+} satisfies import("../../../../../docs/src/components/sandbox/types").SandboxDefinition

packages/appearance/docs/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../../docs/tsconfig.sandbox.json",
+  "compilerOptions": {
+    "tsBuildInfoFile": "../../../docs/node_modules/.tmp/appearance-docs.tsbuildinfo"
+  },
+  "include": ["sandboxes/**/*.ts", "sandboxes/**/*.tsx"]
+}