oink-ui 1.0.0 → 1.0.1

package/README.md

@@ -65,12 +65,12 @@ export function App() {
 | `defaultTheme` | `'light' \| 'dark' \| 'system'` | `'system'` |
 | `defaultAccent` | `'pink' \| 'orange' \| 'amber' \| 'blue' \| 'violet'` or any `#rrggbb` | `'pink'` |
 | `defaultMotion` | `'auto' \| 'full' \| 'reduced'` | `'auto'` |
-| `locale` | `'zh-CN' \| 'en-US'` | `'zh-CN'` |
+| `locale` | `'auto' \| 'zh-CN' \| 'en-US'` — `'auto'` follows the browser language: Chinese → `zh-CN`, anything else → `en-US` | `'auto'` |
 | `storageKey` | remember the user's choices in `localStorage` under this key | — |
 
 With a custom accent color, the text color on top of it (ink or white) and the darker / lighter variants used for text are derived automatically. `useOink()` reads and changes the theme at runtime.
 
-Components render the same markup on the server and the client, so they work with server rendering and static prerendering.
+Components render the same markup on the server and the client, so they work with server rendering and static prerendering. The server can't know the visitor's language, so with `locale="auto"` the server render and the hydration pass use `en-US` and switch to the browser's language right after; if you render on the server, pass `locale` explicitly (for example from the URL or the `Accept-Language` header).
 
 ## Development
 
@@ -81,8 +81,6 @@ npm run typecheck
 npm run build      # dist/: ESM + CJS, type declarations, styles.css and per-component style entries
 ```
 
-Component conventions (in Chinese) are in [CONTRIBUTING.md](./CONTRIBUTING.md).
-
 Every push to `main` that changes code is released automatically as a new patch version (`1.0.x`) by [`release.yml`](./.github/workflows/release.yml); put `[skip ci]` in the commit message to skip a release.
 
 ## License

package/dist/core/locale.d.ts

@@ -3,16 +3,25 @@ import type { Messages } from './messages';
 export type { Messages } from './messages';
 /** 组件内置文案和日期格式用的语言 */
 export type OinkLocale = 'zh-CN' | 'en-US';
+/** 语言设置：具体的语言，或 'auto'（跟随浏览器语言，见 detectLocale） */
+export type OinkLocaleSetting = OinkLocale | 'auto';
 /** 各语言的内置文案 */
 export declare const OINK_MESSAGES: Record<OinkLocale, Messages>;
+/** 服务端渲染、以及注水的那一帧用的语言：服务端不知道访客的语言，注水后再换成浏览器的 */
+export declare const SERVER_LOCALE: OinkLocale;
+/** 浏览器语言 → 组件语言：首选语言是任何一种中文（zh、zh-CN、zh-TW、zh-Hant…）用 zh-CN，其它都用 en-US */
+export declare function detectLocale(languages: readonly string[]): OinkLocale;
 export interface LocaleProviderProps {
-    /** 不传（undefined）时沿用外层的设置，最外层是 zh-CN */
-    locale?: OinkLocale;
+    /** 'auto' 跟随浏览器语言；不传（undefined）时沿用外层的设置，最外层是 'auto' */
+    locale?: OinkLocaleSetting;
     children?: ReactNode;
 }
 /** 在这一块里切换组件内置文案的语言。可以嵌套，内层优先。OinkProvider 的 locale 就是包了一层它 */
 export declare function LocaleProvider({ locale, children }: LocaleProviderProps): import("react").JSX.Element;
-/** 当前语言和对应的内置文案。没有 Provider 时是 zh-CN；不认识的语言回退到 zh-CN */
+/**
+ * 当前语言和对应的内置文案。设置是 'auto'（默认，包括没有 Provider）时跟随浏览器语言：
+ * 服务端渲染和注水那一帧是 SERVER_LOCALE，注水后换成浏览器的；只在浏览器里渲染的应用第一帧就是对的
+ */
 export declare function useLocale(): {
     locale: OinkLocale;
     messages: Messages;

package/dist/core/theme.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { OinkLocale } from './locale';
+import type { OinkLocaleSetting } from './locale';
 import type { TailGlyphSource } from './tail';
 export type ThemeMode = 'light' | 'dark' | 'system';
 export type ResolvedTheme = 'light' | 'dark';
@@ -39,8 +39,11 @@ export interface OinkProviderProps {
     storageKey?: string;
     /** 替换全局的“尾巴”图案（加载、提示里用到的品牌图形）。见 TailProvider */
     tail?: TailGlyphSource;
-    /** 组件内置文案（默认的读屏文字、按钮文字、占位符……）和日期格式的语言。默认 zh-CN。见 LocaleProvider */
-    locale?: OinkLocale;
+    /**
+     * 组件内置文案（默认的读屏文字、按钮文字、占位符……）和日期格式的语言。默认 'auto'：跟随浏览器语言，中文用 zh-CN、其它用 en-US。
+     * 服务端渲染时第一帧是 en-US、注水后才换成浏览器的语言；服务端渲染的应用最好显式传入。见 LocaleProvider
+     */
+    locale?: OinkLocaleSetting;
 }
 /**
  * 主题、强调色、动效偏好。把结果写到 <html> 的 data-theme / data-accent / data-motion 上，