oink-ui 1.0.2 → 1.0.4

package/README.md

@@ -73,11 +73,39 @@ export function App() {
 | `defaultMotion` | `'auto' \| 'full' \| 'reduced'` | `'auto'` |
 | `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 | — |
+| `cornerFallback` | draw the superellipse corners with script in engines without `corner-shape` (see [Corners](#corners)) | `true` |
 
 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. 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).
 
+## Corners
+
+Containers use continuous-curvature superellipse corners: `border-radius` plus `corner-shape: superellipse(1.75)` (the `--ok-corner` token), with radii multiplied by `--ok-rk` (1.45) so they look as large as their nominal size. Fully round shapes (pills, circles) stay `corner-shape: round`.
+
+When overriding a component's shape in application CSS, override its fallback marker in the same rule, including explicit round or inherited shapes:
+
+```css
+.search-button {
+  border-radius: calc(14px * var(--ok-rk));
+  corner-shape: var(--ok-corner); --ok-shape: var(--ok-corner);
+}
+```
+
+WebKit drops `corner-shape`, so omitting `--ok-shape` can retain a component's original marker (for example Button's `round`) even though its radius changed. A radius near half the control height then becomes a pill. The fallback does not infer the intended shape from radius alone.
+
+
+Only Chromium supports `corner-shape` (Chrome, Edge, WebView2). In Safari and in the `WKWebView` that Tauri uses on macOS, `OinkProvider` turns on a small script fallback that draws the same curve Chromium draws, so a Mac build looks like the Windows build. The fallback also starts in Firefox, which lacks `corner-shape` too, but it has not been checked there yet:
+
+- It does nothing at all where `corner-shape` is supported, and nothing on the server.
+- It finds the elements to redraw through `--ok-shape`, a non-inherited custom property every stylesheet declaration of `corner-shape` is paired with. Fully round elements keep the native `border-radius`.
+- On those elements the native corners are squared off and then cut along the curve with `clip-path`; the parts native painting can't put on a curve — the hairline, the top highlight, borders and the focus ring — are patched in with a nine-slice SVG `border-image`. Fills, straight edges and hover / press transitions stay native; the corner patches follow transitions frame by frame. Clipped content (images, scrolling areas) is cut on the curve too.
+- It follows mounts, unmounts, resizes, theme changes, hover, focus and running transitions. On a page with 300 rounded elements (about 1,900 elements in all) in WKWebView it costs about 13 ms once at start-up plus 8 ms for the first paint, 6–8 ms extra on a theme switch, and 1–2 ms of script per frame while 50 rounded elements resize or 10 animate their ring colour.
+
+Without `OinkProvider`, call `installCornerFallback()` once on the client (it returns a function that removes it again; calls are reference-counted). `<OinkProvider cornerFallback={false}>` turns it off. Your own CSS gets the same treatment when it pairs the declarations: `corner-shape: var(--ok-corner); --ok-shape: var(--ok-corner);`.
+
+Code that reads the tokens to draw matching shapes (`getComputedStyle(document.documentElement).getPropertyValue('--ok-corner')`) sees `superellipse(1.75)` and `--ok-rk: 1.45` wherever the corners are superellipses: natively in Chromium, and in other engines once the fallback is running (it marks `<html data-ok-corner-fallback>`). Before the script runs, or with the fallback turned off, those engines draw plain round corners and the tokens say `round` and `1`. `cornerShapePath()` returns the SVG path of a box with these corners, using the same Bézier construction as Chromium.
+
 ## Development
 
 ```bash

package/dist/core/corner.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 超椭圆圆角的几何：和 Chromium 画 `corner-shape: superellipse(K)` 用同一条曲线。
+ *
+ * · 规范里 superellipse(K) 的指数是 n = 2^K：|x|^n + |y|^n = 1。K = 1 是正圆，2 是 squircle，0 是斜切，∞ 是直角，负值内凹。
+ * · Chromium 不是逐点画这条数学曲线，而是每个角拆成两段三次贝塞尔：从直边起点到 45° 点（u = v = 2^(-1/n)），
+ *   起点把手沿直边、45° 点把手沿对角线的切线方向。把手长度（以半径为单位）下面的 HANDLES 表是从 Chromium 149
+ *   的实际渲染里拟合出来的（1000px 半径的角逐行测覆盖率，各 K 的拟合残差均方根 < 0.1px）；K = 1 时 Chromium
+ *   走正圆的画法，这里也单独处理。和数学曲线相比，Chromium 的曲线最多差半径的 0.16%，我们跟 Chromium 走。
+ * · 半径的取值和缩放（盒子太小时按比例缩小全部半径）与 border-radius 完全相同。
+ * · 偏移出来的轮廓（内阴影的洞、描边外缘、outline）：半径按 r ± d 增减、K 不变，原点随矩形内缩 / 外扩。
+ *   Chromium 对偏移轮廓的曲率还有一点微调，在 1–4px 的发丝线和焦点环上差不到 0.1px，这里不跟。
+ */
+/** 四个角的曲率参数 K（左上、右上、右下、左下）。Infinity 是直角，1 是正圆 */
+export type CornerKs = [number, number, number, number];
+/** 一个角的水平、垂直半径 */
+export type CornerRadius = [number, number];
+/** 四个角的半径（左上、右上、右下、左下），和 border-*-radius 的顺序一样 */
+export type CornerRadii = [CornerRadius, CornerRadius, CornerRadius, CornerRadius];
+export interface Box {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** superellipse(K) 的指数 n = 2^K */
+export declare const superellipseExponent: (k: number) => number;
+/** 两段贝塞尔的把手长度（以半径为单位），k ≥ 0 */
+export declare function cornerHandles(k: number): [number, number];
+type Pt = [number, number];
+/**
+ * 单位角上的点（u 是离左边的距离，v 是离上边的距离，都以半径为单位），从左边上的 (0, 1) 走到上边上的 (1, 0)。
+ * 返回 [起点, 控制点, 控制点, 终点, 控制点, 控制点, 终点]：两段三次贝塞尔；直角 / 斜切时退化成折线（控制点和端点重合）
+ */
+export declare function unitCorner(k: number): Pt[];
+/** 规范的半径缩放：相邻两个角的半径之和超过边长时，全部半径按同一个比例缩小 */
+export declare function clampRadii(w: number, h: number, r: CornerRadii): CornerRadii;
+/** 半径随轮廓偏移 d（正值外扩、负值内缩）：有圆角的角按 r + d 增减到不小于 0，直角保持直角 */
+export declare function offsetRadii(r: CornerRadii, d: number): CornerRadii;
+/** 矩形向外扩 d（负值内缩）、再平移 (dx, dy) */
+export declare const inflate: (b: Box, d: number, dx?: number, dy?: number) => Box;
+/**
+ * 一个闭合子路径（SVG / CSS path() 语法）：盒子 b、四角半径 r、四角曲率 ks。顺时针；reverse 时逆时针（nonzero 规则下挖洞）
+ */
+export declare function shapePath(b: Box, r: CornerRadii, ks: CornerKs, reverse?: boolean): string;
+/** 矩形子路径；reverse 时逆时针 */
+export declare function rectPath(b: Box, reverse?: boolean): string;
+/**
+ * 解析 corner-shape 的值（我们从 --ok-shape 读到的就是它）：1–4 个值，顺序同 border-radius。
+ * 关键字 round / squircle / square / bevel / scoop / notch 和 superellipse(K | infinity | -infinity)。全是 round 返回 null
+ */
+export declare function parseCornerShape(value: string): CornerKs | null;
+/** 一层阴影（来自计算后的 box-shadow）。模糊忽略不计：设计里没有阴影，只有零模糊的描边和高光 */
+export interface ShadowLayer {
+    inset: boolean;
+    dx: number;
+    dy: number;
+    spread: number;
+    color: string;
+    blur?: number;
+}
+export interface OutlineLayer {
+    offset: number;
+    width: number;
+    color: string;
+}
+/** 一个元素（或伪元素）在回退里需要知道的全部：尺寸、半径（已缩放）、曲率、边框、阴影、outline */
+export interface CornerDecor {
+    w: number;
+    h: number;
+    radii: CornerRadii;
+    ks: CornerKs;
+    /** 上右下左的边框宽度 */
+    border: [number, number, number, number];
+    borderColor: string;
+    shadows: ShadowLayer[];
+    outline: OutlineLayer | null;
+    /**
+     * 元素背后的颜色（最近的不透明祖先背景）。外侧装饰（outline、外阴影）离超椭圆很近时，环在 45° 附近会伸进盒子的矩形里；
+     * 那里原生画的是直角的底色，Chromium 那里露出的是背后的页面。补丁先用这个颜色盖住，再画环
+     */
+    backdrop?: string;
+    /**
+     * 叠在这个元素上的其它部件（伪元素）的外侧装饰，在本元素坐标里的区域（outerRegions，已外扩 1px）。
+     * 这时超椭圆外紧挨着的地方可见，补丁不能越过超椭圆；并且这片区域落在盒子矩形里的部分先铺 backdrop，盖住原生直角底色
+     */
+    attached?: string;
+}
+/** 颜色的不透明度：transparent、rgba(…, a)、rgb(… / a)、color(… / a)；解析不了当作不透明 */
+export declare function colorAlpha(c: string): number;
+/** 解析计算后的 box-shadow（颜色可能在前也可能在后；长度一律是 px） */
+export declare function parseBoxShadow(value: string): ShadowLayer[];
+/** 外侧的装饰（外阴影、outline）伸出盒子多远 */
+export declare function outerExtent(d: Pick<CornerDecor, 'shadows' | 'outline'>): number;
+/**
+ * 外侧装饰在这个元素坐标里的可见区域（nonzero 子路径），供 clip-path 合并。
+ * 外阴影 = 外扩后的形状（盒内部分本来就可见）；outline = 外扩到外缘的形状 + 外扩到内缘的形状（逆时针挖掉中间的缝）
+ */
+export declare function outerRegions(d: CornerDecor, at?: {
+    x: number;
+    y: number;
+}, grow?: number): string;
+/**
+ * clip-path 的路径：
+ * · 一个比盒子大 bleed 的大矩形（溢出盒子的子元素照常可见，只在四个角动刀）；
+ * · 每个有圆角的角挖一个洞：从角往盒内到半径、往盒外到外侧装饰的最远处 reach；
+ * · 再把超椭圆形状本身、以及外侧装饰（outline 环、外阴影）的可见区域并回来。
+ * 原生绘制在角上是直角（回退时 border-radius 置 0），洞里只留下超椭圆和装饰的真实形状。
+ * extra 是叠在这个元素上的其它部件（伪元素）的外侧装饰，reach 要覆盖它们
+ */
+export declare function cornerClipPath(d: CornerDecor, bleed: number, extra?: string, extraReach?: number): string;
+export interface CornerPaint {
+    /** SVG 源码 */
+    svg: string;
+    /** border-image-slice（也是 border-image-width，单位 px），上右下左 */
+    slice: [number, number, number, number];
+    /** border-image-outset */
+    outset: number;
+}
+/** 补丁缓存键里和尺寸有关的部分：能拉伸的方向不看尺寸 */
+export declare function paintSizeKey(d: CornerDecor): string;
+export declare function cornerPaint(d: CornerDecor): CornerPaint | null;
+/** 把补丁写成 border-image 的值 */
+export declare function borderImageValue(p: CornerPaint): string;
+export {};

package/dist/core/cornerFallback.d.ts

@@ -0,0 +1,13 @@
+/** <html> 上的开关：tokens.css 据此把 --ok-corner / --ok-rk 换成超椭圆那一套 */
+export declare const CORNER_FALLBACK_ATTR = "data-ok-corner-fallback";
+/** 当前内核要不要回退：能确定不支持 corner-shape、并且有需要的观察器时才要 */
+export declare function cornerFallbackNeeded(): boolean;
+/**
+ * 打开超椭圆回退。可以重复调用（引用计数），返回的函数撤销这一次；最后一个撤销时清掉所有观察器、属性和行内变量。
+ * 内核支持 corner-shape 或在服务端时什么都不做。OinkProvider 默认会调用它
+ */
+export declare function installCornerFallback(): () => void;
+/** 回退是否正在工作 */
+export declare const cornerFallbackActive: () => boolean;
+/** 组件里打开回退（OinkProvider 用它）。在布局副作用里打开：首帧绘制前角就已经画好。enabled 为 false 时不打开 */
+export declare function useCornerFallback(enabled?: boolean): void;

package/dist/core/index.d.ts

@@ -12,3 +12,6 @@ export * from './theme';
 export * from './locale';
 export * from './tail';
 export * from './OinkLogo';
+export { shapePath as cornerShapePath, cornerHandles, parseCornerShape, clampRadii as clampCornerRadii } from './corner';
+export type { CornerKs, CornerRadii, CornerRadius } from './corner';
+export { installCornerFallback, useCornerFallback, cornerFallbackNeeded, cornerFallbackActive } from './cornerFallback';

package/dist/core/theme.d.ts

@@ -44,11 +44,16 @@ export interface OinkProviderProps {
      * 服务端渲染时第一帧是 en-US、注水后才换成浏览器的语言；服务端渲染的应用最好显式传入。见 LocaleProvider
      */
     locale?: OinkLocaleSetting;
+    /**
+     * 不支持 `corner-shape` 的内核（Safari、macOS 上的 WKWebView、Firefox）里用脚本画出和 Chromium 一样的超椭圆圆角。默认打开；
+     * 支持 corner-shape 的内核里本来就什么都不做。见 installCornerFallback
+     */
+    cornerFallback?: boolean;
 }
 /**
  * 主题、强调色、动效偏好。把结果写到 <html> 的 data-theme / data-accent / data-motion 上，
  * 所有组件的样式都从这三个属性派生。不包 Provider 也能用组件，默认浅色 + 粉色强调。
  */
-export declare function OinkProvider({ children, defaultTheme, defaultAccent, defaultMotion, storageKey, tail, locale }: OinkProviderProps): import("react").JSX.Element;
+export declare function OinkProvider({ children, defaultTheme, defaultAccent, defaultMotion, storageKey, tail, locale, cornerFallback }: OinkProviderProps): import("react").JSX.Element;
 /** 读写主题。没有 Provider 时返回只读的默认值，方便组件在任何地方使用 */
 export declare function useOink(): OinkContextValue;

package/dist/inputs/Button.d.ts

@@ -50,7 +50,7 @@ type IconOnlyProps = {
 }));
 export type ButtonProps = ButtonOwnProps & Omit<ButtonHTMLAttributes<HTMLButtonElement>, keyof ButtonOwnProps> & IconOnlyProps;
 /** 按钮。全圆胶囊；传 href 渲染成链接 */
-export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
+export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLAnchorElement | HTMLButtonElement>>;
 export interface ButtonGroupProps extends HTMLAttributes<HTMLDivElement> {
     /** 组内按钮的默认尺寸 */
     size?: ButtonSize;