@linktr.ee/messaging-react 3.31.1 → 3.31.2-rc-1785926144

package/src/components/LinkAttachment/components/_shared/accentSurface.test.ts

@@ -1,135 +0,0 @@
-import { converter } from 'culori'
-import { describe, expect, it } from 'vitest'
-
-import { accentSurface } from './accentSurface'
-import {
-  contrastRatio,
-  inkFor,
-  INK_ON_DARK,
-  INK_ON_LIGHT,
-  WCAG_AA_NORMAL_TEXT,
-} from './chinContrast'
-
-const toOklch = converter('oklch')
-
-/** Hue is only meaningful above a little chroma, so tests gate on this. */
-function chromaOf(hex: string): number {
-  return toOklch(hex)?.c ?? 0
-}
-
-function hueOf(hex: string): number {
-  return toOklch(hex)?.h ?? 0
-}
-
-/** Hues far enough apart to be visibly different colours. */
-const SAMPLES = [
-  '#7008E7', // violet — chroma well outside sRGB at both stops
-  '#2FCB5F', // green
-  '#FFF099', // pale yellow
-  '#00B6FF', // cyan
-  '#738883', // the Figma mock's desaturated green
-  '#FCF5E3', // the near-white from the MES-1388 report
-  '#1e2330', // already as dark as the sender fallback
-  '#767676', // fully neutral, zero chroma
-]
-
-describe('accentSurface', () => {
-  it('always produces a surface its own ink can clear AA on', () => {
-    // The whole point of deriving rather than admitting: no extracted colour is
-    // ever rejected for contrast, and none is ever illegible.
-    for (const sample of SAMPLES) {
-      for (const [variant, ink] of [
-        ['dark', INK_ON_DARK],
-        ['light', INK_ON_LIGHT],
-      ] as const) {
-        const surface = accentSurface(sample, variant)
-        expect(surface, `${sample} on ${variant}`).toBeDefined()
-        expect(
-          contrastRatio(surface as string, ink),
-          `${sample} on ${variant}`
-        ).toBeGreaterThanOrEqual(WCAG_AA_NORMAL_TEXT)
-        // And the ink the card will actually pick agrees with that side.
-        expect(inkFor(surface as string)).toBe(ink)
-      }
-    }
-  })
-
-  it('keeps the image hue so different links stay distinguishable', () => {
-    for (const sample of SAMPLES) {
-      // Hue is only meaningful above a little chroma: `#FCF5E3` and `#767676`
-      // are near-neutral, where the angle is numerically unstable and invisible.
-      if (chromaOf(sample) < 0.03) continue
-      const expected = hueOf(sample)
-      for (const variant of ['dark', 'light'] as const) {
-        const surface = accentSurface(sample, variant) as string
-        const drift = Math.abs(hueOf(surface) - expected)
-        // Tight on purpose. `clampChroma` holds hue while it desaturates, so
-        // this stays under 2° — the same fidelity as the hand-rolled OKLCH pass
-        // it replaced. Swapping to culori's `toGamut` would drift up to 12° and
-        // trip this, which is exactly the regression it is here to catch.
-        expect(
-          Math.min(drift, 360 - drift),
-          `${sample} ${variant}`
-        ).toBeLessThan(2)
-      }
-    }
-  })
-
-  it('separates the two sides, so each is legible under its own ink', () => {
-    // Sent lands dark, received pale — the same link, the same hue, opposite
-    // ends of the lightness axis because the inks are opposites.
-    for (const sample of SAMPLES) {
-      const sent = accentSurface(sample, 'dark') as string
-      const received = accentSurface(sample, 'light') as string
-      expect(contrastRatio(sent, INK_ON_DARK)).toBeGreaterThan(
-        contrastRatio(sent, INK_ON_LIGHT)
-      )
-      expect(contrastRatio(received, INK_ON_LIGHT)).toBeGreaterThan(
-        contrastRatio(received, INK_ON_DARK)
-      )
-    }
-  })
-
-  it('holds AA at every hue, at chroma beyond what sRGB can show', () => {
-    // Sweeps the failure mode that a fixed lightness stop could plausibly have:
-    // a hue whose maximum chroma pushes the derived colour out of gamut.
-    for (let hue = 0; hue < 360; hue += 15) {
-      const vivid = `#${[0, 120, 240]
-        .map((offset) =>
-          Math.round(127 + 127 * Math.cos(((hue + offset) * Math.PI) / 180))
-            .toString(16)
-            .padStart(2, '0')
-        )
-        .join('')}`
-      for (const [variant, ink] of [
-        ['dark', INK_ON_DARK],
-        ['light', INK_ON_LIGHT],
-      ] as const) {
-        const surface = accentSurface(vivid, variant)
-        expect(
-          contrastRatio(surface as string, ink),
-          `hue ${hue} on ${variant}`
-        ).toBeGreaterThanOrEqual(WCAG_AA_NORMAL_TEXT)
-      }
-    }
-  })
-
-  it('accepts the shapes the extractor and CSS disagree about', () => {
-    // `accent_color` arrives from the ugc-kit query as a bare hex often enough
-    // that a missing `#` must not silently drop the colour.
-    expect(accentSurface('7008E7', 'dark')).toBe(
-      accentSurface('#7008E7', 'dark')
-    )
-    expect(accentSurface('  #7008E7  ', 'dark')).toBe(
-      accentSurface('#7008E7', 'dark')
-    )
-    expect(accentSurface('#70E', 'dark')).toBeDefined()
-  })
-
-  it('has no surface when there was no colour to derive from', () => {
-    expect(accentSurface(undefined, 'dark')).toBeUndefined()
-    expect(accentSurface('', 'dark')).toBeUndefined()
-    expect(accentSurface('rebeccapurple', 'dark')).toBeUndefined()
-    expect(accentSurface('#ff', 'light')).toBeUndefined()
-  })
-})

package/src/components/LinkAttachment/components/_shared/accentSurface.ts

@@ -1,95 +0,0 @@
-/**
- * Turns the colour extracted from an attachment image into a card surface that
- * the card's own text can survive.
- *
- * `ugc-kit`'s `ImageAnalysis` (`getDominantColorFromImageUrl`) answers only
- * "what colour is this image?" — it has no notion of contrast or readability.
- * Painting that colour straight onto the card is what broke: the extracted
- * colour is whatever the photo happened to be, so roughly half of them left the
- * title illegible against the side's ink, and refusing those threw away the
- * colour the feature exists to add (MES-1349, MES-1388).
- *
- * So the hue is kept and the *lightness* is replaced with a fixed stop chosen
- * per side — dark behind the sender's white ink, pale behind the receiver's
- * near-black. This is the approach already used in `linktr.ee-profiles`
- * (`ui/src/utils/rgbToTheme.ts`), whose `getPaletteFromColor` generates a
- * 16-stop OKLCH ramp from one colour and has callers pick a background stop and
- * a text stop from it. We need exactly one stop per side rather than a whole
- * theme, so the ramp is collapsed to a single lightness target.
- *
- * OKLCH rather than HSL because its lightness axis is perceptually uniform: one
- * L value gives the same *apparent* lightness — and therefore the same contrast
- * — across every hue. In HSL, `50%` lightness yellow and `50%` blue differ by
- * several stops of contrast, so no single target would hold.
- *
- * The conversion, the sRGB gamut mapping and the WCAG ratio are all `culori`'s.
- * An earlier revision of this module hand-rolled them (~90 lines of OKLab
- * matrices and a bisecting chroma search); `culori` is zero-dependency and ships
- * a real CJS build, so it is safe for both frontyard's Jest and profiles' build.
- */
-import { clampChroma, converter, formatHex, wcagContrast } from 'culori'
-
-import type { LinkAttachmentVariant } from './CardShell'
-import { INK_ON_DARK, INK_ON_LIGHT, WCAG_AA_NORMAL_TEXT } from './chinContrast'
-import { HEX_PATTERN, toCssHex } from './hex'
-
-/**
- * Perceived-lightness stop each side paints at, in OKLCH L (0..1) — profiles'
- * `color12` / `color2` equivalent. Both sit far enough from their ink to clear
- * AA at any hue and chroma: swept across every hue at maximum chroma the worst
- * case is comfortably above the 4.5:1 floor (see `accentSurface.test.ts`).
- */
-const SURFACE_LIGHTNESS: Record<LinkAttachmentVariant, number> = {
-  dark: 0.3,
-  light: 0.9,
-}
-
-/** Ink each side draws, so the derived surface can be checked against it. */
-const INK_BY_VARIANT: Record<LinkAttachmentVariant, string> = {
-  dark: INK_ON_DARK,
-  light: INK_ON_LIGHT,
-}
-
-const toOklch = converter('oklch')
-
-/**
- * The card surface for an extracted colour: the image's hue at this side's
- * lightness stop, or `undefined` when there was no colour to work from.
- *
- * The input is validated as a hex rather than handed to `culori` directly.
- * `culori` accepts every CSS colour, including names like `rebeccapurple`, and
- * `accent_color` is always a hex from `getDominantColorFromImageUrl` — widening
- * that contract by accident would let a caller pass something no other part of
- * this module can reason about. The bare-hex case *is* supported, because the
- * extractor omits the `#` often enough that dropping it would silently lose the
- * colour (MES-1349).
- *
- * The AA check at the end is a guard, not a branch anyone expects to take: the
- * lightness stops were chosen to clear it everywhere. It exists so that a future
- * change to `SURFACE_LIGHTNESS` or to the ink cannot quietly reintroduce an
- * illegible card — it degrades to the plain bubble fill instead.
- */
-export function accentSurface(
-  accentColor: string | undefined,
-  variant: LinkAttachmentVariant
-): string | undefined {
-  if (accentColor == null || !HEX_PATTERN.test(accentColor.trim())) {
-    return undefined
-  }
-
-  const base = toOklch(toCssHex(accentColor))
-  if (!base) return undefined
-
-  // `clampChroma`, not `toGamut`: both bring an out-of-sRGB colour back into
-  // range, but `toGamut` follows the CSS Color 4 path and drifts hue by up to
-  // 12° on saturated bases, while `clampChroma` reduces chroma at constant hue
-  // and lightness — 2.8° worst case. Vivid hues desaturate rather than shift,
-  // which is what keeps the card recognisably the image's colour.
-  const surface = formatHex(
-    clampChroma({ ...base, l: SURFACE_LIGHTNESS[variant] }, 'oklch')
-  )
-
-  return wcagContrast(surface, INK_BY_VARIANT[variant]) >= WCAG_AA_NORMAL_TEXT
-    ? surface
-    : undefined
-}

package/src/components/LinkAttachment/components/_shared/chinContrast.test.ts

@@ -1,95 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { AUDIO_BG, AUDIO_BG_CLASS } from './CardThumbnail'
-import {
-  BUBBLE_BG_BY_VARIANT,
-  contrastRatio,
-  inkFor,
-  INK_ON_DARK,
-  INK_ON_LIGHT,
-  WCAG_AA_NORMAL_TEXT,
-} from './chinContrast'
-
-describe('contrastRatio', () => {
-  // The arithmetic is culori's. What this module owns is the input contract:
-  // which strings are colours, and what happens to the ones that are not.
-  it('matches the WCAG maximum for black on white', () => {
-    expect(contrastRatio('#000000', '#ffffff')).toBeCloseTo(21, 2)
-  })
-
-  it('is symmetric and self-referential', () => {
-    expect(contrastRatio('#1e2330', '#ffffff')).toBeCloseTo(
-      contrastRatio('#ffffff', '#1e2330'),
-      5
-    )
-    expect(contrastRatio('#1e2330', '#1e2330')).toBeCloseTo(1, 5)
-  })
-
-  it('accepts short hex and the missing hash the extractor omits', () => {
-    const canonical = contrastRatio('#ffffff', '#1e2330')
-    for (const white of ['#fff', 'ffffff', '  #fff  ']) {
-      expect(contrastRatio(white, '#1e2330')).toBeCloseTo(canonical, 5)
-    }
-  })
-
-  it('is NaN for anything that is not a hex, including CSS colour names', () => {
-    // culori would happily resolve `rebeccapurple`; this module deliberately
-    // does not, because every colour reaching it comes from a hex extractor.
-    for (const input of ['', '#ff', '#gggggg', 'rebeccapurple', '#ffffff00']) {
-      expect(contrastRatio(input, '#ffffff')).toBeNaN()
-      expect(contrastRatio('#ffffff', input)).toBeNaN()
-    }
-  })
-})
-
-describe('the fallback fills stay legible', () => {
-  it('clears AA on both sides, so a card with no accent is always readable', () => {
-    for (const variant of ['dark', 'light'] as const) {
-      const fill = BUBBLE_BG_BY_VARIANT[variant]
-      const ink = inkFor(fill)
-      expect(ink).toBeDefined()
-      expect(contrastRatio(fill, ink as string)).toBeGreaterThanOrEqual(
-        WCAG_AA_NORMAL_TEXT
-      )
-    }
-  })
-
-  it('uses the plain message bubble fills', () => {
-    // Keep in sync with `--str-chat__own-message-bubble-background-color` and
-    // `--str-chat__message-bubble-background-color` in styles.css.
-    expect(BUBBLE_BG_BY_VARIANT).toEqual({
-      dark: '#1e2330',
-      light: '#f1f0ee',
-    })
-  })
-})
-
-describe('inkFor', () => {
-  it('inks a dark surface light and a light surface dark', () => {
-    expect(inkFor('#1e2330')).toBe(INK_ON_DARK)
-    expect(inkFor('#f1f0ee')).toBe(INK_ON_LIGHT)
-  })
-
-  it('inks the audio strip dark, which is the MES-1388 regression', () => {
-    // `AUDIO_BG_CLASS` is imposed on the shell of any variant, so a sent audio
-    // card drew the dark variant's white ink on near-white at ~1.13:1.
-    expect(contrastRatio(AUDIO_BG, INK_ON_DARK)).toBeLessThan(
-      WCAG_AA_NORMAL_TEXT
-    )
-    const ink = inkFor(AUDIO_BG)
-    expect(ink).toBe(INK_ON_LIGHT)
-    expect(contrastRatio(AUDIO_BG, ink as string)).toBeGreaterThanOrEqual(
-      WCAG_AA_NORMAL_TEXT
-    )
-  })
-
-  it('keeps the audio hex and its tailwind class in step', () => {
-    // Tailwind only emits utilities it can find as complete literals, so the
-    // class cannot be built from the constant — hence the pair.
-    expect(AUDIO_BG_CLASS).toBe(`bg-[${AUDIO_BG}]`)
-  })
-
-  it('has no ink for an unparseable surface', () => {
-    expect(inkFor('rebeccapurple')).toBeUndefined()
-  })
-})

package/src/components/LinkAttachment/components/_shared/chinContrast.ts

@@ -1,79 +0,0 @@
-/**
- * Ink and fallback fills for the `LinkAttachment` card, whose background is a
- * colour derived from the attachment image (see `accentSurface`).
- *
- * The card's text is chosen by measuring contrast against whatever surface the
- * card actually paints. Ink used to be fixed per variant, which left any
- * background the card imposed on *itself* unchecked: `AUDIO_BG_CLASS`
- * (`#F2F3F4`) is applied on either variant, so a sent audio card drew white ink
- * on near-white at 1.13:1 and the title was invisible (MES-1388).
- *
- * The ratio itself is `culori`'s `wcagContrast`. A previous revision computed
- * relative luminance here by hand; the only thing this module adds now is the
- * decision of *which* ink, and the hex validation that keeps the surface a hex
- * rather than any CSS colour.
- */
-import { wcagContrast } from 'culori'
-
-import type { LinkAttachmentVariant } from './CardShell'
-import { HEX_PATTERN, toCssHex } from './hex'
-
-/** WCAG 2.1 SC 1.4.3 (AA), normal text. Both chin lines are normal text. */
-export const WCAG_AA_NORMAL_TEXT = 4.5
-
-/**
- * Fill each side falls back to when no accent is paintable: the plain message
- * bubble's own background, so a link card without a usable colour is indistinct
- * from the text bubbles around it rather than a third colour nobody chose.
- *
- * These are the literal values behind `--str-chat__own-message-bubble-background-color`
- * and `--str-chat__message-bubble-background-color` in `styles.css`. Duplicated
- * as hex because the bubble tail paints *outside* the shell's box via an inline
- * style, and because the contrast arithmetic needs a colour, not a `var()`.
- * Keep in sync with those two custom properties.
- */
-export const BUBBLE_BG_BY_VARIANT: Record<LinkAttachmentVariant, string> = {
-  dark: '#1e2330',
-  light: '#f1f0ee',
-}
-
-/** Ink candidates for a surface the card cannot refuse. */
-export const INK_ON_DARK = '#FFFFFF'
-/** The near-black used across the Figma frames. */
-export const INK_ON_LIGHT = '#040403'
-
-/**
- * WCAG contrast ratio between two hex colours, or `NaN` if either is not a hex.
- *
- * The hex guard is deliberate: `culori` resolves any CSS colour, and every
- * colour reaching this module comes from an image extractor or from the two
- * constants above. `NaN` rather than a throw so callers can branch on
- * `Number.isNaN` and fall back.
- */
-export function contrastRatio(a: string, b: string): number {
-  if (typeof a !== 'string' || typeof b !== 'string') return Number.NaN
-  if (!HEX_PATTERN.test(a.trim()) || !HEX_PATTERN.test(b.trim())) {
-    return Number.NaN
-  }
-
-  return wcagContrast(toCssHex(a), toCssHex(b))
-}
-
-/**
- * Ink for a surface the card did not choose — the audio strip's flat neutral, or
- * a variant fallback fill — picking whichever candidate scores the higher ratio
- * against it. `undefined` when the surface is not a hex, so callers keep the
- * variant's own `text-*` classes.
- *
- * This is the rule the accent derivation cannot cover. A derived accent suits
- * its side's ink by construction; an imposed background has to be met the other
- * way round, by moving the ink. Only decoration can be refused (MES-1388).
- */
-export function inkFor(background: string): string | undefined {
-  const againstDarkInk = contrastRatio(background, INK_ON_LIGHT)
-  if (Number.isNaN(againstDarkInk)) return undefined
-
-  return againstDarkInk >= contrastRatio(background, INK_ON_DARK)
-    ? INK_ON_LIGHT
-    : INK_ON_DARK
-}