@fibery/ui-kit 2.1.1 → 4.0.0

package/src/antd/styles.ts

@@ -1,5 +1,6 @@
 import {css} from "@linaria/core";
-import {border, layout, shadows, space, textStyles, themeVars, transition} from "../design-system";
+
+import {border, layout, shadows, space, textStyles, themeVars, transitions} from "../design-system";
 
 const inputVariables = {
   default: {
@@ -31,7 +32,7 @@ export const inputOverrides = {
     paddingRight: space.s12,
     border: 0,
     borderColor: themeVars.transparent,
-    transition: `box-shadow ${transition}`,
+    transition: `box-shadow ${transitions.faster}`,
     boxShadow: `var(--input-border, ${themeVars.inputBorderColor})`,
     letterSpacing: 0,
     "&::placeholder": {
@@ -40,18 +41,18 @@ export const inputOverrides = {
   },
   hover: {
     boxShadow: `var(--input-hover-border, 0 0 0 1px ${themeVars.colorAccentStrokeHover}) !important`,
-    transition: `box-shadow ${transition}`,
+    transition: `box-shadow ${transitions.faster}`,
   },
   focus: {
     boxShadow: `var(--input-focus-border, 0 0 0 1px ${themeVars.colorAccentStroke}), var(--input-focus-shadow) !important`,
-    transition: `box-shadow ${transition}`,
+    transition: `box-shadow ${transitions.faster}`,
   },
   disabled: {
     color: `${themeVars.textColor}`,
     backgroundColor: `${themeVars.inputDisabledBgColor} !important`,
     borderColor: themeVars.transparent,
     boxShadow: `${themeVars.inputDisabledBorderColor} !important`,
-    transition: `box-shadow ${transition}`,
+    transition: `box-shadow ${transitions.faster}`,
     WebkitTextFillColor: "currentColor",
     cursor: "default",
     "&:hover": {
@@ -68,6 +69,58 @@ export const inputStyles = css`
   }
   ${{
     ...textStyles.regular,
+    "& .ant-input, & .ant-input-affix-wrapper, & .ant-input-group-wrapper, & .ant-input-wrapper": {
+      boxSizing: "border-box",
+    },
+    "& .ant-input-affix-wrapper": {
+      display: "inline-flex",
+      alignItems: "center",
+      width: "100%",
+      position: "relative",
+      font: "inherit",
+      padding: 0,
+      border: "none",
+      boxShadow: "none",
+      backgroundColor: themeVars.transparent,
+    },
+    "& .ant-input-affix-wrapper > input.ant-input": {
+      minWidth: 0,
+      flex: 1,
+      padding: "0 12px",
+      border: "inherit",
+      outline: "inherit",
+    },
+    "& .ant-input-prefix, & .ant-input-suffix": {
+      display: "flex",
+      flex: "none",
+      alignItems: "center",
+    },
+    // antd source: spacing between adjacent icons when prefix/suffix holds multiple nodes.
+    "& .ant-input-prefix > *:not(:last-child), & .ant-input-suffix > *:not(:last-child)": {
+      marginRight: space.s8,
+    },
+    "& .ant-input-suffix": {
+      marginLeft: space.s6,
+    },
+    "& .ant-input-clear-icon": {
+      display: "inline-flex",
+      alignItems: "center",
+      color: themeVars.iconColor,
+      cursor: "pointer",
+      lineHeight: 1,
+    },
+    "& .ant-input-clear-icon-hidden": {
+      visibility: "hidden",
+    },
+    "& .ant-input-group-wrapper": {
+      display: "inline-block",
+      width: "100%",
+    },
+    "& .ant-input-wrapper.ant-input-group": {
+      display: "inline-flex",
+      width: "100%",
+      alignItems: "stretch",
+    },
     "& .ant-input-group-addon": {
       backgroundColor: themeVars.transparent,
       border: "none",
@@ -78,23 +131,37 @@ export const inputStyles = css`
       "&:focus": inputOverrides.focus,
     },
     "& .ant-input-group": {borderSpacing: 1, ...textStyles.regular},
-    "& .ant-input": inputOverrides.main,
+    "& .ant-input": {
+      ...inputOverrides.main,
+      // antd source: .ant-input { width: 100%; min-width: 0 } — without it, bare <AntInput>
+      // doesn't fill its container and can't shrink inside a flex parent. AutoComplete's
+      // .ant-select-selection-search .ant-input rule (two-class selector) beats this on
+      // specificity for combobox inputs, so the nested-AntAutoComplete case is unaffected.
+      width: "100%",
+      minWidth: 0,
+    },
+    // antd source: long placeholders get ellipsis instead of wrap-clip.
+    "& .ant-input:placeholder-shown": {
+      textOverflow: "ellipsis",
+    },
+    // bordered={false} → wrap with `ant-input-borderless` class; strip the box-shadow ring + bg.
+    // antd source covers base + hover/focus/disabled with the same declarations.
+    // !important needed to beat inputOverrides.main's !important on backgroundColor/boxShadow.
+    "& .ant-input.ant-input-borderless, & .ant-input.ant-input-borderless:hover, & .ant-input.ant-input-borderless:focus, & .ant-input.ant-input-borderless:disabled, & .ant-input.ant-input-borderless[disabled]":
+      {
+        boxShadow: "none !important",
+        backgroundColor: `${themeVars.transparent} !important`,
+      },
+    // antd source: inner input inside affix-wrapper must not paint its own focus ring —
+    // the wrapper owns the visual focus state. Without this prefix/suffix usage shows a
+    // double ring.
+    "& .ant-input-affix-wrapper > .ant-input:focus": {
+      boxShadow: "none !important",
+    },
     "& .ant-input-status-error": inputVariables.error,
     "& .ant-input[readonly].ant-input[readonly]": {...inputOverrides.disabled, cursor: "inherit"},
     "& .ant-input:hover[readonly].ant-input:hover[readonly]": {...inputOverrides.disabled, cursor: "inherit"},
     "& .ant-input-affix-wrapper:hover .ant-input[readonly]": {...inputOverrides.disabled, cursor: "inherit"},
-    "& .ant-input-affix-wrapper > input.ant-input": {
-      padding: "0 12px",
-      border: "inherit",
-      outline: "inherit",
-    },
-    "& .ant-input-affix-wrapper": {
-      font: "inherit",
-      padding: 0,
-      border: "none",
-      boxShadow: "none",
-      backgroundColor: themeVars.transparent,
-    },
     "& .ant-input-affix-wrapper.ant-input-affix-wrapper-readonly": {
       border: "none !important",
       outline: "none !important",
@@ -103,22 +170,15 @@ export const inputStyles = css`
     "& .ant-input-affix-wrapper:hover .ant-input:not(.ant-input-disabled)": {
       borderColor: "transparent",
     },
-    "& .ant-cascader-picker:focus .ant-cascader-input, & .ant-cascader-picker:focus:hover .ant-cascader-input":
-      inputOverrides.focus,
-    "& .ant-select-auto-complete.ant-select": {
-      ...textStyles.regular,
-      "&  .ant-select-selection--single": {height: layout.inputHeight},
-      "& .ant-input": inputOverrides.main,
-      "& .ant-input.ant-input:hover": inputOverrides.hover,
-      "& .ant-input.ant-input:focus": inputOverrides.focus,
-      "& .ant-input.ant-input-disabled": inputOverrides.disabled,
-    },
+    // antd source: textarea defaults — min-height anchors empty <AntTextArea> to a sane
+    // height, max-width prevents user-resize from blowing out the container, and
+    // vertical-align: bottom matches the baseline of a single-line <input> next to it.
     "& textarea.ant-input": {
       paddingTop: space.s8,
       paddingBottom: space.s8,
-    },
-    "& .ant-select-disabled .ant-select-selection": {
-      backgroundColor: themeVars.transparent,
+      minHeight: layout.inputHeight,
+      maxWidth: "100%",
+      verticalAlign: "bottom",
     },
     "&& input:hover:not(:focus):not(:disabled), && textarea:hover:not(:focus):not(:disabled), && .ant-input:hover:not(:focus):not(:disabled)":
       inputOverrides.hover,
@@ -128,7 +188,6 @@ export const inputStyles = css`
     "&& input::placeholder, && textarea::placeholder": {
       color: themeVars.inputPlaceholderTextColor,
     },
-    "& .ant-input-affix-wrapper .ant-input-prefix": {left: space.s6},
     "& .ant-input-affix-wrapper .ant-input:not(:first-child)": {paddingLeft: space.s6 + space.s24 + space.s8}, // Match TitlePreview spacing
   }}
 `;

package/src/antd/tabs.tsx

@@ -0,0 +1,174 @@
+import {css} from "@linaria/core";
+import Tabs from "rc-tabs";
+import type {ComponentProps} from "react";
+import {forwardRef} from "react";
+
+import {textStyles, space, themeVars, transitions} from "../design-system";
+import {getWrapper} from "./get-wrapper";
+import {wrapWith} from "./utils";
+
+type TabsPropsAny = ComponentProps<typeof Tabs>;
+
+const PrefixedTabs = forwardRef<HTMLDivElement, TabsPropsAny>(function PrefixedTabs(props, ref) {
+  return <Tabs prefixCls="ant-tabs" {...props} ref={ref} />;
+});
+
+export const tabsStyles = css`
+  ${{
+    width: "100%",
+    "& .ant-tabs": {
+      boxSizing: "border-box",
+      display: "flex",
+      overflow: "visible",
+      width: "100%",
+    },
+    "& .ant-tabs-top, & .ant-tabs-bottom": {
+      flexDirection: "column",
+    },
+    "& .ant-tabs-nav": {
+      display: "flex",
+      flex: "none",
+      alignItems: "center",
+      margin: 0,
+      width: "100%",
+      position: "relative",
+      "&::before": {
+        position: "absolute",
+        right: 0,
+        bottom: 0,
+        left: 0,
+        borderBottom: themeVars.borderSolidFilterGroup,
+        content: "''",
+      },
+    },
+    "& .ant-tabs-nav-wrap": {
+      display: "flex",
+      flex: "auto",
+      overflow: "hidden",
+      whiteSpace: "nowrap",
+      position: "relative",
+      alignSelf: "stretch",
+      transform: "translate(0)",
+      marginBottom: 1,
+      marginLeft: space.s12,
+      marginRight: space.s12,
+    },
+    "& .ant-tabs-nav-wrap::before, & .ant-tabs-nav-wrap::after": {
+      position: "absolute",
+      zIndex: 1,
+      opacity: 0,
+      transition: `opacity ${transitions.slow}`,
+      content: "''",
+      pointerEvents: "none",
+    },
+    "& .ant-tabs-nav-list": {
+      position: "relative",
+      display: "flex",
+      transition: `transform ${transitions.normal}`,
+    },
+    "& .ant-tabs-nav-operations": {
+      display: "flex",
+      alignSelf: "stretch",
+    },
+    "& .ant-tabs-nav-operations-hidden": {
+      position: "absolute",
+      visibility: "hidden",
+      pointerEvents: "none",
+    },
+    "& .ant-tabs-nav-more": {
+      position: "relative",
+      padding: `${space.s8}px ${space.s16}px`,
+      backgroundColor: themeVars.transparent,
+      border: 0,
+    },
+    "& .ant-tabs-nav-more::after": {
+      position: "absolute",
+      right: 0,
+      bottom: 0,
+      left: 0,
+      height: 5,
+      transform: "translateY(100%)",
+      content: "''",
+    },
+    "& .ant-tabs-extra-content": {
+      flex: "none",
+    },
+    "& .ant-tabs-centered .ant-tabs-nav-wrap:not([class*='ant-tabs-nav-wrap-ping'])": {
+      justifyContent: "center",
+    },
+    "& .ant-tabs-ink-bar": {
+      position: "absolute",
+      bottom: 0,
+      backgroundColor: themeVars.colorAccent,
+      height: 2,
+      pointerEvents: "none",
+      transition: `left ${transitions.faster}, right ${transitions.faster}, width ${transitions.faster}`,
+    },
+    "& .ant-tabs-tab, & .ant-tabs-tab:hover, & .ant-tabs-tab-btn:active, & .ant-tabs-tabpane, & .ant-tabs-tab-active .ant-tabs-tab-btn":
+      {
+        ...textStyles.regular,
+        textShadow: "none",
+      },
+    "& .ant-tabs-tab": {
+      position: "relative",
+      display: "inline-flex",
+      alignItems: "center",
+      padding: "12px 12px",
+      margin: `0 ${space.s8}px 0 0`,
+      cursor: "pointer",
+      outline: "none",
+    },
+    "& .ant-tabs-tab + .ant-tabs-tab": {
+      margin: `0 ${space.s8}px 0 0`,
+    },
+    "& .ant-tabs-tab-btn": {
+      outline: "none",
+      transition: `all ${transitions.slow}`,
+    },
+    "& .ant-tabs-tab-active .ant-tabs-tab-btn": {
+      color: themeVars.colorAccent,
+    },
+    "& .ant-tabs-content-holder": {
+      flex: "auto",
+      minWidth: 0,
+      minHeight: 0,
+    },
+    "& .ant-tabs-content": {
+      position: "relative",
+      display: "flex",
+      width: "100%",
+    },
+    "& .ant-tabs-tabpane": {
+      flex: "none",
+      width: "100%",
+      outline: "none",
+    },
+    "& .ant-tabs-tabpane-hidden": {
+      display: "none",
+    },
+    "& .ant-tabs-switch-appear, & .ant-tabs-switch-enter": {
+      transition: "none",
+    },
+    "& .ant-tabs-switch-appear-start, & .ant-tabs-switch-enter-start": {
+      opacity: 0,
+    },
+    "& .ant-tabs-switch-appear-active, & .ant-tabs-switch-enter-active": {
+      opacity: 1,
+      transition: `opacity ${transitions.slow}`,
+    },
+    "& .ant-tabs-switch-leave": {
+      position: "absolute",
+      inset: 0,
+      transition: "none",
+    },
+    "& .ant-tabs-switch-leave-start": {
+      opacity: 1,
+    },
+    "& .ant-tabs-switch-leave-active": {
+      opacity: 0,
+      transition: `opacity ${transitions.slow}`,
+    },
+  }}
+`;
+
+export const AntTabs = wrapWith(getWrapper(tabsStyles), PrefixedTabs);

package/src/antd/utils.tsx

@@ -1,4 +1,5 @@
-import {ElementType, forwardRef, useCallback, useRef} from "react";
+import type {ElementType} from "react";
+import {forwardRef, useCallback, useRef} from "react";
 
 export const wrapWith = <C extends React.ElementType>(
   WrapperComponent: ElementType,

package/src/apca.lc-low.test.ts

@@ -0,0 +1,69 @@
+import {calcLc, colorFromLcCompensated} from "./apca";
+import {colorFromUnsafe, oklchFrom} from "./color-utils";
+import {userColorChoices} from "./palettes/testkit";
+
+const SURFACE = "#FFFFFF";
+const TARGETS = [0, 1, 2, 3, 4, 5, 6, 7, 8] as const;
+// Tolerance bound for the round-trip (target Lc → setter → calcLc) in the
+// formerly-bridged Lc range, against pure white. Dominated by 8-bit hex
+// quantization inside apcach's solver — will tighten when storage moves
+// to OKLCH/P3.
+const MAX_LC_ROUNDTRIP_ERR = 1;
+
+const fmtRow = (errors: number[]) => errors.map((e) => (e >= 0 ? "+" : "") + e.toFixed(1)).join(" ");
+
+describe("Lc round-trip in the formerly-bridged region (target Lc 0..8)", () => {
+  const violations: string[] = [];
+  test("diagnostic snapshot: per-seed round-trip errors", () => {
+    expect(
+      userColorChoices((seed) => {
+        const {c = 0, h = 0} = oklchFrom(colorFromUnsafe(seed));
+        const errors = TARGETS.map((target) => {
+          const out = colorFromLcCompensated(SURFACE, target, c, h, (s) => s);
+          return calcLc(out, SURFACE) - target;
+        });
+        for (const [i, err] of errors.entries()) {
+          if (Math.abs(err) > MAX_LC_ROUNDTRIP_ERR) {
+            violations.push(`${seed.trim()}: target=${TARGETS[i]} err=${err.toFixed(2)}`);
+          }
+        }
+        return `target: ${TARGETS.join("    ")}    →    err: ${fmtRow(errors)}`;
+      })
+    ).toMatchInlineSnapshot(`
+      {
+        "CMYK Black  ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.0 -0.4 +0.4 -0.0 +0.2 -0.2 -0.0 -0.4",
+        "CMYK Cyan   ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.0 -0.0 +0.1 +0.1 -0.0 +0.0 -0.0 -0.0",
+        "CMYK Magenta": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 +0.2 +0.1 -0.1 +0.2 +0.0 -0.1 -0.3 -0.0",
+        "CMYK Yellow ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.1 -0.0 +0.2 +0.4 -0.0 +0.1 +0.3 -0.1",
+        "Noti green  ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 +0.1 -0.1 -0.0 +0.2 -0.1 -0.0 +0.2 +0.3",
+        "Noti red    ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 +0.2 +0.1 +0.1 +0.0 -0.0 -0.1 +0.0 -0.4",
+        "Noti yellow ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.0 -0.5 -0.2 -0.1 +0.1 +0.3 +0.5 +0.1",
+        "RGB  Blue   ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 +0.1 +0.3 -0.0 +0.1 +0.3 +0.0 -0.3 -0.1",
+        "RGB  Green  ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 +0.1 -0.0 +0.0 +0.1 +0.0 +0.1 +0.0 +0.0",
+        "RGB  Red    ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 +0.2 +0.1 +0.1 +0.0 -0.0 -0.1 -0.1 +0.2",
+        "White       ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.0 -0.4 +0.4 -0.0 +0.2 -0.2 -0.0 -0.4",
+        "swatches[ 0] aka Swatch.GreyDark  ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.0 -0.4 +0.4 -0.0 +0.2 -0.2 -0.0 -0.4",
+        "swatches[ 1] aka Swatch.Grey      ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.1 +0.1 -0.1 +0.2 -0.0 +0.3 -0.0 +0.3",
+        "swatches[ 2] aka Swatch.GreyLight ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.2 +0.0 -0.1 +0.0 -0.2 -0.0 +0.0 +0.2",
+        "swatches[ 3] aka Swatch.Red       ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 +0.2 +0.1 +0.0 +0.0 -0.0 -0.1 +0.3 +0.2",
+        "swatches[ 4] aka Swatch.Magenta   ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 +0.1 +0.0 -0.0 +0.3 +0.2 +0.1 +0.0 -0.1",
+        "swatches[ 5] aka Swatch.Purple    ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.1 +0.3 +0.2 +0.0 +0.3 -0.2 +0.1 -0.1",
+        "swatches[ 6] aka Swatch.Violet    ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.0 +0.1 +0.2 +0.2 -0.1 +0.4 -0.0 -0.1",
+        "swatches[ 7] aka Swatch.BlueDark  ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.1 +0.1 -0.1 -0.0 +0.1 +0.3 -0.0 +0.1",
+        "swatches[ 8] aka Swatch.Blue      ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 +0.1 -0.1 -0.0 +0.2 -0.1 -0.3 -0.1 +0.0",
+        "swatches[ 9] aka Swatch.BlueSky   ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 +0.0 -0.2 +0.1 -0.0 -0.2 -0.0 -0.1 +0.1",
+        "swatches[10] aka Swatch.Turquoise ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.0 +0.0 -0.4 -0.2 -0.1 -0.0 +0.1 -0.0",
+        "swatches[11] aka Swatch.GreenDark ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.1 +0.0 -0.1 +0.1 -0.0 +0.0 -0.1 -0.0",
+        "swatches[12] aka Swatch.Green     ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.1 -0.1 -0.0 -0.0 +0.0 -0.0 -0.0 -0.1",
+        "swatches[13] aka Swatch.GreenLight": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.1 +0.0 -0.0 +0.0 +0.0 +0.0 +0.1 +0.0",
+        "swatches[14] aka Swatch.Yellow    ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 -0.0 +0.0 -0.0 +0.0 +0.0 +0.0 +0.0 -0.0",
+        "swatches[15] aka Swatch.Orange    ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 +0.2 +0.1 +0.1 +0.1 +0.0 -0.0 -0.1 +0.3",
+        "swatches[16] aka Swatch.Brown     ": "target: 0    1    2    3    4    5    6    7    8    →    err: +0.0 +0.2 +0.1 +0.1 +0.1 +0.0 -0.0 -0.1 -0.1",
+      }
+    `);
+  });
+
+  test(`every (seed, target) round-trip is within ±${MAX_LC_ROUNDTRIP_ERR} Lc`, () => {
+    expect(violations).toEqual([]);
+  });
+});

package/src/apca.test.ts

@@ -0,0 +1,186 @@
+import {calcContrast} from "apcach";
+
+import {calcLc, colorFromLc, solveNearIdentity} from "./apca";
+
+describe("calcLc", () => {
+  // With the apca-w3 patch, calcLc is continuous from 0 across the full range
+  // and matches stock APCA wherever stock returns non-zero.
+  describe("matches stock apcach.calcContrast on high-contrast pairs", () => {
+    const pairs: [fg: string, bg: string][] = [
+      ["#000000", "#ffffff"],
+      ["#ffffff", "#000000"],
+      ["#222222", "#ffffff"],
+      ["#ff0000", "#ffffff"],
+      ["#0000ff", "#ffffff"],
+      ["#0080ff", "#ffffff"],
+      ["#ffffff", "#1d1d1d"],
+      ["#888888", "#ffffff"],
+      ["#444444", "#ffffff"],
+    ];
+    it.each(pairs)("Lc(%s, %s)", (fg, bg) => {
+      const ours = calcLc(fg, bg);
+      const stock = Math.abs(Number(calcContrast(fg, bg, "apca", "srgb")));
+      expect(Math.abs(ours - stock)).toBeLessThan(0.01);
+    });
+  });
+
+  describe("near-zero contrast (former dead zone)", () => {
+    it("returns exactly 0 when fg === bg", () => {
+      expect(calcLc("#888888", "#888888")).toBe(0);
+      expect(calcLc("#000000", "#000000")).toBe(0);
+      expect(calcLc("#ffffff", "#ffffff")).toBe(0);
+    });
+
+    it("monotonically increases as fg diverges from bg", () => {
+      // Use a wider sweep — adjacent 8-bit greys may both fall below the
+      // loOffset noise floor and tie at 0.
+      const bg = "#888888";
+      const lcs = ["#888888", "#aaaaaa", "#cccccc", "#eeeeee", "#ffffff"].map((fg) => calcLc(fg, bg));
+      for (let i = 1; i < lcs.length; i++) {
+        expect(lcs[i]).toBeGreaterThan(lcs[i - 1]);
+      }
+      expect(lcs).toMatchInlineSnapshot(`
+        [
+          0,
+          16.897864551748565,
+          36.33194143878067,
+          57.418767755407885,
+          68.54146436644962,
+        ]
+      `);
+    });
+
+    it("preserves APCA's normal-vs-reverse polarity asymmetry", () => {
+      const dark_on_light = calcLc("#888888", "#8c8c8c");
+      const light_on_dark = calcLc("#8c8c8c", "#888888");
+      expect(dark_on_light).not.toBeCloseTo(light_on_dark, 1);
+    });
+  });
+
+  it("polarity: dark-on-light and light-on-dark are both reported as positive Lc", () => {
+    expect(calcLc("#000000", "#ffffff")).toBeGreaterThan(0);
+    expect(calcLc("#ffffff", "#000000")).toBeGreaterThan(0);
+    // APCA's normal vs reverse exponents make these unequal in magnitude.
+    expect(calcLc("#000000", "#ffffff")).not.toBeCloseTo(calcLc("#ffffff", "#000000"), 1);
+  });
+
+  // Mirror property: colorFromLc is the right-inverse of calcLc. Pick a target
+  // Lc against a surface, generate a color at that Lc, then re-measure — the
+  // result must match the input within hex-output quantization.
+  describe("colorFromLc ↔ calcLc round-trip", () => {
+    // White and black give every target Lc up to ~106 at chroma=0 in sRGB.
+    const surfaces = ["#ffffff", "#000000"];
+    // Bound dominated by 8-bit sRGB hex quantization (apcach's solver snaps
+    // candidates to integer channels). Targets below ~5 against extreme
+    // surfaces aren't reachable on the 8-bit grid; will tighten and extend
+    // when storage moves to OKLCH/P3.
+    const TOLERANCE = 1;
+    const targets = [5, 8, 10, 20, 30, 45, 60, 75, 90];
+    const cases = surfaces.flatMap((surface) => targets.map((target) => ({surface, target})));
+    it.each(cases)("$surface @ Lc=$target round-trips within ±1", ({surface, target}) => {
+      const out = colorFromLc(surface, target, 0, 0);
+      expect(Math.abs(calcLc(out, surface) - target)).toBeLessThan(TOLERANCE);
+    });
+
+    it("Lc=0 produces a color that measures back to 0 (grey surfaces)", () => {
+      for (const surface of ["#ffffff", "#000000", "#7f7f7f", "#1d1d1d"]) {
+        const out = colorFromLc(surface, 0, 0, 0);
+        expect(calcLc(out, surface)).toBe(0);
+      }
+    });
+
+    it("monotonic: higher target Lc yields higher measured Lc", () => {
+      const surface = "#ffffff";
+      const measured = [10, 25, 50, 75, 90].map((t) => calcLc(colorFromLc(surface, t, 0, 0), surface));
+      for (let i = 1; i < measured.length; i++) {
+        expect(measured[i]).toBeGreaterThan(measured[i - 1]);
+      }
+    });
+  });
+});
+
+describe("solveNearIdentity", () => {
+  const trace = <T extends (x: number) => number>(f: T) => {
+    const calls: number[] = [];
+    const wrapped = (x: number) => {
+      calls.push(x);
+      return f(x);
+    };
+    return {wrapped, calls};
+  };
+
+  it("identity f(x)=x: solves exactly in 2 calls", () => {
+    const {wrapped, calls} = trace((x) => x);
+    expect(solveNearIdentity(wrapped, 50)).toBe(50);
+    expect(calls).toHaveLength(2);
+  });
+
+  it("translation f(x)=x+b: residual at x1 is exactly 0, no refinement", () => {
+    const f = (x: number) => x + 5;
+    const {wrapped, calls} = trace(f);
+    const result = solveNearIdentity(wrapped, 30);
+    expect(f(result)).toBeCloseTo(30, 9);
+    expect(calls).toHaveLength(2);
+  });
+
+  it("slope ≠ 1 triggers refinement; secant already exact, refinement is no-op", () => {
+    const f = (x: number) => 0.8 * x;
+    const {wrapped, calls} = trace(f);
+    const result = solveNearIdentity(wrapped, 40);
+    expect(f(result)).toBeCloseTo(40, 9);
+    expect(calls).toHaveLength(3);
+  });
+
+  it("slope close to 1: residual under threshold, no refinement", () => {
+    const f = (x: number) => 0.99 * x;
+    const {wrapped, calls} = trace(f);
+    const result = solveNearIdentity(wrapped, 40);
+    expect(f(result)).toBeCloseTo(40, 9);
+    expect(calls).toHaveLength(2);
+  });
+
+  it("nonlinear off-center: refinement reduces error", () => {
+    const f = (x: number) => x + 0.005 * (x - 50) ** 2;
+    const {wrapped, calls} = trace(f);
+    const result = solveNearIdentity(wrapped, 30);
+    expect(Math.abs(f(result) - 30)).toBeLessThan(0.05);
+    expect(calls).toHaveLength(3);
+  });
+
+  it("flat function (denom = 0): falls back to x1 without throwing", () => {
+    const {wrapped} = trace(() => 50);
+    expect(() => solveNearIdentity(wrapped, 50)).not.toThrow();
+  });
+
+  it("custom refineThreshold gates refinement", () => {
+    const f = (x: number) => 0.95 * x;
+    const {calls: looseCalls} = trace(f);
+    solveNearIdentity(
+      (x) => {
+        looseCalls.push(x);
+        return f(x);
+      },
+      40,
+      {refineThreshold: 5}
+    );
+    expect(looseCalls).toHaveLength(2);
+
+    const {calls: tightCalls} = trace(f);
+    solveNearIdentity(
+      (x) => {
+        tightCalls.push(x);
+        return f(x);
+      },
+      40,
+      {refineThreshold: 0.1}
+    );
+    expect(tightCalls).toHaveLength(3);
+  });
+
+  it("damp factor changes the refinement result", () => {
+    const f = (x: number) => 0.7 * x + 0.001 * (x - 30) ** 2;
+    const a = solveNearIdentity(f, 40, {damp: 1});
+    const b = solveNearIdentity(f, 40, {damp: 0.5});
+    expect(a).not.toBe(b);
+  });
+});