@nexxtmove/ui 2.1.0 → 2.3.0

package/src/components/organisms/ColorPicker/_GradientStops.vue

@@ -0,0 +1,218 @@
+<script lang="ts">
+/** The step of Shift (and PageUp/PageDown) on a stop handle, in percent. */
+const STOP_STEP = 10
+</script>
+
+<script lang="ts" setup>
+import { computed, nextTick, useId, useTemplateRef } from 'vue'
+import NexxtIcon from '../../atoms/Icon/Icon.vue'
+import { CHECKERBOARD, fillMessage, stopBarCss } from './gradient'
+import type { GradientCopy } from './gradient'
+import type { GradientEditor, GradientEditorStop } from './useGradientEditor'
+
+export interface NexxtGradientStopsProps {
+  /** The gradient state of the picker. */
+  editor: GradientEditor
+  /** Copy, already merged over the defaults. */
+  copy: GradientCopy
+}
+
+/**
+ * The bar with a handle per stop, and under it the heading of the stop list
+ * with the add button. Each handle is a slider of its own (the APG pattern for a slider with
+ * several thumbs); reka's multi-thumb slider is not used because it sorts its
+ * values, so a handle would swap stops when two pass each other.
+ */
+defineOptions({ name: 'NexxtGradientStops' })
+
+const { editor, copy } = defineProps<NexxtGradientStopsProps>()
+
+const emit = defineEmits<{
+  /** The add button was used; the parent adds the stop and focuses its row. */
+  add: []
+  /** Delete or Backspace on a handle; the parent removes the stop and moves the focus. */
+  remove: [id: number]
+}>()
+
+const REASON_ID = useId()
+
+const bar = useTemplateRef<HTMLElement>('bar')
+const handles = new Map<number, HTMLElement>()
+
+const handleRef = (id: number) => (element: unknown) => {
+  if (element instanceof HTMLElement) handles.set(id, element)
+  else handles.delete(id)
+}
+
+/** Focuses the handle of a stop once the DOM has caught up with the state. */
+const focusStop = async (id: number) => {
+  await nextTick()
+  handles.get(id)?.focus()
+}
+
+defineExpose({ focusStop })
+
+const barStyle = computed(() => ({
+  backgroundImage: `${stopBarCss(editor.snapshot.value)}, ${CHECKERBOARD}`,
+  backgroundSize: 'auto, 10px 10px',
+}))
+
+const handleStyle = (stop: GradientEditorStop) => ({
+  left: `${stop.position}%`,
+  backgroundImage: `linear-gradient(${stop.color}, ${stop.color}), ${CHECKERBOARD}`,
+  backgroundSize: 'auto, 8px 8px',
+})
+
+const nameOf = (stop: GradientEditorStop) =>
+  fillMessage(copy.stop, {
+    n: editor.sorted.value.indexOf(stop) + 1,
+    total: editor.stops.value.length,
+  })
+
+const valueTextOf = (stop: GradientEditorStop) => {
+  if (stop.preset) return `${stop.position} %, ${stop.preset.label}`
+  const hex = stop.color.slice(0, 7)
+  const alpha = stop.color.length === 9 ? parseInt(stop.color.slice(7), 16) / 255 : 1
+  const opacity =
+    alpha < 1 ? `, ${fillMessage(copy.stopOpacity, { n: Math.round(alpha * 100) })}` : ''
+  return `${stop.position} %, ${hex}${opacity}`
+}
+
+const positionAt = (event: PointerEvent) => {
+  const rect = bar.value?.getBoundingClientRect()
+  if (!rect || rect.width === 0) return 0
+  return ((event.clientX - rect.left) / rect.width) * 100
+}
+
+/** The stop a pointer is moving, until it is released. */
+let dragged: number | null = null
+
+const startDrag = (event: PointerEvent, id: number, capture: HTMLElement) => {
+  capture.setPointerCapture?.(event.pointerId)
+  dragged = id
+}
+
+const onHandlePointerDown = (event: PointerEvent, id: number) => {
+  if (event.button !== 0) return
+  // No default: it would hand the focus back to whatever the browser picks.
+  event.preventDefault()
+  event.stopPropagation()
+  editor.select(id)
+  handles.get(id)?.focus()
+  startDrag(event, id, event.currentTarget as HTMLElement)
+}
+
+/** A click on the bar adds a stop there, and keeps dragging it while the button is down. */
+const onBarPointerDown = async (event: PointerEvent) => {
+  if (event.button !== 0) return
+  event.preventDefault()
+  const id = editor.addStop(positionAt(event))
+  if (id === null) return
+  startDrag(event, id, event.currentTarget as HTMLElement)
+  await focusStop(id)
+}
+
+const onPointerMove = (event: PointerEvent) => {
+  if (dragged !== null) editor.moveStop(dragged, positionAt(event))
+}
+
+const onPointerUp = async () => {
+  if (dragged === null) return
+  const id = dragged
+  dragged = null
+  editor.settle()
+  await focusStop(id)
+}
+
+const add = () => {
+  if (editor.canAdd.value) emit('add')
+}
+
+const KEY_MOVES: Record<string, (position: number, shift: boolean) => number> = {
+  ArrowLeft: (p, shift) => p - (shift ? STOP_STEP : 1),
+  ArrowDown: (p, shift) => p - (shift ? STOP_STEP : 1),
+  ArrowRight: (p, shift) => p + (shift ? STOP_STEP : 1),
+  ArrowUp: (p, shift) => p + (shift ? STOP_STEP : 1),
+  PageUp: (p) => p + STOP_STEP,
+  PageDown: (p) => p - STOP_STEP,
+  Home: () => 0,
+  End: () => 100,
+}
+
+const onHandleKeydown = async (event: KeyboardEvent, stop: GradientEditorStop) => {
+  if (event.key === 'Delete' || event.key === 'Backspace') {
+    event.preventDefault()
+    if (editor.canRemove.value) emit('remove', stop.id)
+    return
+  }
+  const move = KEY_MOVES[event.key]
+  if (!move) return
+  event.preventDefault()
+  editor.moveStop(stop.id, move(stop.position, event.shiftKey))
+  editor.settle()
+  await focusStop(stop.id)
+}
+</script>
+
+<template>
+  <!-- `mx-2.5`: half a handle, so a stop at 0 % or 100 % stays inside the column. -->
+  <div
+    ref="bar"
+    data-gradient-bar
+    class="relative mx-2.5 h-5 touch-none select-none"
+    :class="editor.canAdd.value ? 'cursor-copy' : 'cursor-default'"
+    @pointerdown="onBarPointerDown"
+    @pointermove="onPointerMove"
+    @pointerup="onPointerUp"
+    @lostpointercapture="onPointerUp"
+  >
+    <div class="absolute inset-x-0 inset-y-1 rounded-full" :style="barStyle" />
+    <span
+      v-for="stop in editor.stops.value"
+      :key="stop.id"
+      :ref="handleRef(stop.id)"
+      role="slider"
+      tabindex="0"
+      aria-orientation="horizontal"
+      aria-valuemin="0"
+      aria-valuemax="100"
+      :aria-label="nameOf(stop)"
+      :aria-valuenow="stop.position"
+      :aria-valuetext="valueTextOf(stop)"
+      :data-selected="stop.id === editor.selectedId.value || undefined"
+      class="absolute top-0 size-5 -translate-x-1/2 cursor-grab rounded-full border-2 border-white shadow-[0_0_0_1px_rgba(0,0,0,0.5)] outline-cornflower-blue-600 focus-visible:outline-2 focus-visible:outline-offset-2 active:cursor-grabbing"
+      :class="{ 'z-10 ring-2 ring-cornflower-blue-600': stop.id === editor.selectedId.value }"
+      :style="handleStyle(stop)"
+      @pointerdown="onHandlePointerDown($event, stop.id)"
+      @pointermove="onPointerMove"
+      @pointerup="onPointerUp"
+      @lostpointercapture="onPointerUp"
+      @focus="editor.select(stop.id)"
+      @keydown="onHandleKeydown($event, stop)"
+    />
+  </div>
+
+  <div class="flex h-6 items-center gap-1">
+    <p class="min-w-0 flex-1 extra-small-normal text-gray-900">
+      {{ copy.stops }} <span class="text-gray-700">{{ copy.max }}</span>
+    </p>
+    <!--
+      `aria-disabled`, not `disabled`: the button stays focusable, so the reason
+      it does nothing can be heard.
+    -->
+    <button
+      type="button"
+      data-gradient-add
+      :aria-label="copy.addName"
+      :aria-disabled="editor.canAdd.value ? undefined : 'true'"
+      :aria-describedby="editor.canAdd.value ? undefined : REASON_ID"
+      class="flex h-6 shrink-0 cursor-pointer items-center gap-1 rounded-md px-1.5 extra-small-normal text-gray-900 hover:bg-gray-100 focus:outline-none focus-visible:ring-2 focus-visible:ring-cornflower-blue-600"
+      :class="!editor.canAdd.value && 'cursor-not-allowed opacity-50 hover:bg-transparent'"
+      @click="add"
+    >
+      <NexxtIcon name="plus" aria-hidden="true" />
+      {{ copy.add }}
+    </button>
+    <span :id="REASON_ID" hidden>{{ copy.maxReason }}</span>
+  </div>
+</template>

package/src/components/organisms/ColorPicker/gradient.ts

@@ -0,0 +1,303 @@
+/**
+ * The gradient of NexxtColorPicker's gradient mode, as plain data. The picker
+ * knows no class names: a wrapper such as NexxtEditorColor turns this into
+ * whatever it stores.
+ */
+
+/** A named colour a stop can be bound to, such as a theme role. Always opaque. */
+export interface ColorPickerPreset {
+  /** What the wrapper knows the preset by, such as `'main'`. */
+  key: string
+  /** Name of the preset as the user reads it, announced on the stop's handle. */
+  label: string
+}
+
+export interface ColorPickerGradientStop {
+  /** The colour as `#rrggbb`, or `#rrggbbaa` below full opacity; lower case. */
+  color: string
+  /** Whole percentage, 0–100. */
+  position: number
+  /** Set when the stop is bound to a preset; `color` is then the preset's hex. */
+  preset?: ColorPickerPreset
+}
+
+export interface ColorPickerGradient {
+  type: 'linear' | 'radial'
+  /** Whole degrees, 0–359, clockwise from the top. Only used by a linear gradient. */
+  angle: number
+  /** Centre in whole percentages from the left. Only used by a radial gradient. */
+  centerX: number
+  /** Centre in whole percentages from the top. Only used by a radial gradient. */
+  centerY: number
+  /** Two or three stops, in order of position. */
+  stops: ColorPickerGradientStop[]
+}
+
+export const MIN_STOPS = 2
+export const MAX_STOPS = 3
+export const DEFAULT_ANGLE = 180
+export const DEFAULT_CENTER = 50
+
+/** What the gradient mode shows while there is no readable gradient. */
+export const DEFAULT_GRADIENT: ColorPickerGradient = {
+  type: 'linear',
+  angle: DEFAULT_ANGLE,
+  centerX: DEFAULT_CENTER,
+  centerY: DEFAULT_CENTER,
+  stops: [
+    { color: '#00000000', position: 0 },
+    { color: '#00000099', position: 100 },
+  ],
+}
+
+/** Rounds and clamps to a whole percentage. */
+export const clampPercent = (value: number) => Math.min(100, Math.max(0, Math.round(value)))
+
+/** Rounds and wraps to a whole angle, 0–359: 360 is 0 and -10 is 350. */
+export const wrapAngle = (value: number) => ((Math.round(value) % 360) + 360) % 360
+
+/** A stop as CSS needs it: any CSS colour, and a position in percent. */
+export interface CssGradientStop {
+  color: string
+  position: number
+}
+
+/** The shape of a gradient as CSS needs it. */
+export type CssGradientShape =
+  { type: 'linear'; angle: number } | { type: 'radial'; centerX: number; centerY: number }
+
+const stopList = (stops: CssGradientStop[]) =>
+  stops.map(({ color, position }) => `${color} ${position}%`).join(', ')
+
+/**
+ * A gradient as a CSS `background-image`, always interpolated in oklab and with
+ * every position written. This is how the consuming app draws a gradient class
+ * (as inline CSS), so the preview shows exactly what the app renders. For
+ * `bg-linear-*` and `bg-radial` it is also what the Tailwind class renders;
+ * for `bg-radial-[at_…]` Tailwind would interpolate in sRGB, the app does not.
+ * The position comes before the interpolation method, as in
+ * `radial-gradient(at 30% 70% in oklab, …)`; a centred radial gradient leaves
+ * the position out.
+ */
+export const buildGradientCss = (shape: CssGradientShape, stops: CssGradientStop[]) => {
+  const list = stopList(stops)
+  if (shape.type === 'linear') return `linear-gradient(${shape.angle}deg in oklab, ${list})`
+  return shape.centerX === DEFAULT_CENTER && shape.centerY === DEFAULT_CENTER
+    ? `radial-gradient(in oklab, ${list})`
+    : `radial-gradient(at ${shape.centerX}% ${shape.centerY}% in oklab, ${list})`
+}
+
+/** The picker's gradient as CSS; see `buildGradientCss`. */
+export const gradientCss = (gradient: ColorPickerGradient) =>
+  buildGradientCss(
+    gradient.type === 'linear'
+      ? { type: 'linear', angle: gradient.angle }
+      : { type: 'radial', centerX: gradient.centerX, centerY: gradient.centerY },
+    gradient.stops,
+  )
+
+/** The stops left to right in oklab, for the stop bar. */
+export const stopBarCss = (gradient: ColorPickerGradient) =>
+  `linear-gradient(to right in oklab, ${stopList(gradient.stops)})`
+
+/** The checkerboard that shows through a translucent colour. */
+export const CHECKERBOARD = 'repeating-conic-gradient(#e5e7eb 0% 25%, #ffffff 0% 50%)'
+
+// ── Colour maths ──────────────────────────────────────────────────────────
+
+type Rgba = [r: number, g: number, b: number, a: number]
+
+const parseHex = (hex: string): Rgba => {
+  const value = hex.replace('#', '')
+  const channel = (index: number) => parseInt(value.slice(index, index + 2), 16) / 255
+  return [channel(0), channel(2), channel(4), value.length === 8 ? channel(6) : 1]
+}
+
+const toHexPair = (value: number) =>
+  Math.round(Math.min(1, Math.max(0, value)) * 255)
+    .toString(16)
+    .padStart(2, '0')
+
+/** `#rrggbb`, or `#rrggbbaa` below full opacity, in lower case. */
+export const formatHex = ([r, g, b, a]: Rgba) => {
+  const alpha = toHexPair(a)
+  return `#${toHexPair(r)}${toHexPair(g)}${toHexPair(b)}${alpha === 'ff' ? '' : alpha}`
+}
+
+/** A hex in the one spelling the picker reports: lower case, without an opaque `ff`. */
+export const normalizeHex = (hex: string) => formatHex(parseHex(hex))
+
+const toLinear = (c: number) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4)
+const fromLinear = (c: number) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055)
+
+const srgbToOklab = (r: number, g: number, b: number): [number, number, number] => {
+  const [lr, lg, lb] = [toLinear(r), toLinear(g), toLinear(b)]
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb)
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb)
+  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb)
+  return [
+    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  ]
+}
+
+const oklabToSrgb = (L: number, A: number, B: number): [number, number, number] => {
+  const l = (L + 0.3963377774 * A + 0.2158037573 * B) ** 3
+  const m = (L - 0.1055613458 * A - 0.0638541728 * B) ** 3
+  const s = (L - 0.0894841775 * A - 1.291485548 * B) ** 3
+  return [
+    fromLinear(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
+    fromLinear(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
+    fromLinear(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s),
+  ]
+}
+
+/**
+ * Mixes two colours the way a CSS gradient does: in the given space, with
+ * premultiplied alpha, so a fade from a transparent black to a colour keeps the
+ * colour's hue all the way.
+ */
+export const mixColors = (from: string, to: string, t: number, space: 'oklab' | 'srgb') => {
+  const [r1, g1, b1, a1] = parseHex(from)
+  const [r2, g2, b2, a2] = parseHex(to)
+  const convert = space === 'oklab' ? srgbToOklab : (r: number, g: number, b: number) => [r, g, b]
+  const c1 = convert(r1, g1, b1)
+  const c2 = convert(r2, g2, b2)
+  const alpha = a1 + (a2 - a1) * t
+  const mixed = [0, 1, 2].map((index) => {
+    const premultiplied =
+      (c1[index] ?? 0) * a1 + ((c2[index] ?? 0) * a2 - (c1[index] ?? 0) * a1) * t
+    return alpha === 0 ? 0 : premultiplied / alpha
+  })
+  const [x = 0, y = 0, z = 0] = mixed
+  const [r, g, b] = space === 'oklab' ? oklabToSrgb(x, y, z) : [x, y, z]
+  return formatHex([r, g, b, alpha])
+}
+
+/**
+ * The colour the gradient shows at `position`, as a hex: what a stop added
+ * there needs so that the gradient does not change. Interpolated in oklab, as
+ * every gradient is drawn. Before the first stop and after the last the
+ * gradient is flat.
+ */
+export const colorAt = (stops: ColorPickerGradientStop[], position: number) => {
+  const first = stops[0]
+  const last = stops[stops.length - 1]
+  if (!first || !last) return '#000000'
+  if (position <= first.position) return normalizeHex(first.color)
+  if (position >= last.position) return normalizeHex(last.color)
+  const after = stops.findIndex((stop) => stop.position > position)
+  const right = stops[after]
+  const left = stops[after - 1]
+  if (!left || !right) return normalizeHex(last.color)
+  const t = (position - left.position) / (right.position - left.position)
+  return mixColors(left.color, right.color, t, 'oklab')
+}
+
+// ── Copy ──────────────────────────────────────────────────────────────────
+
+/**
+ * Copy of the gradient mode. Every key is optional and merged over the Dutch
+ * defaults. `{n}`, `{total}`, `{x}` and `{y}` are filled in by the picker.
+ */
+export interface ColorPickerGradientMessages {
+  /** Accessible name of the solid/gradient switch. Defaults to `'Vulling'`. */
+  mode?: string
+  /** Solid option of the switch. Defaults to `'Effen'`. */
+  solid?: string
+  /** Gradient option of the switch. Defaults to `'Verloop'`. */
+  gradient?: string
+  /** Accessible name of the type switch. Defaults to `'Type verloop'`. */
+  type?: string
+  /** Linear option of the type switch. Defaults to `'Lineair'`. */
+  linear?: string
+  /** Radial option of the type switch. Defaults to `'Radiaal'`. */
+  radial?: string
+  /** Accessible name of the angle point in the preview. Defaults to `'Hoek'`. */
+  angle?: string
+  /** Value text of the angle point. Defaults to `'{n} graden'`. */
+  angleValue?: string
+  /** Accessible name of the centre point in the preview. Defaults to `'Middelpunt'`. */
+  center?: string
+  /** Value text of the centre point. Defaults to `'{x} % van links, {y} % van boven'`. */
+  centerValue?: string
+  /** Accessible name of the reverse button. Defaults to `'Kleurstops omdraaien'`. */
+  reverse?: string
+  /** Heading above the stop list. Defaults to `'Kleurstops'`. */
+  stops?: string
+  /** Hint next to the heading. Defaults to `'max. 3'`. */
+  max?: string
+  /** Why no stop can be added, announced on the add button. Defaults to `'Een verloop heeft maximaal 3 kleurstops.'`. */
+  maxReason?: string
+  /** Visible text of the add button. Defaults to `'Toevoegen'`. */
+  add?: string
+  /** Accessible name of the add button. Defaults to `'Kleurstop toevoegen'`. */
+  addName?: string
+  /** Name of a stop's row and of its handle on the bar. Defaults to `'Kleurstop {n} van {total}'`. */
+  stop?: string
+  /** Accessible name of a row's position field. Defaults to `'Positie (%)'`. */
+  position?: string
+  /** Accessible name of a row's colour button. Defaults to `'Kleur kiezen'`. */
+  pick?: string
+  /** Accessible name of a row's hex field. Defaults to `'Hex'`. */
+  hex?: string
+  /** Accessible name of a row's remove button. Defaults to `'Verwijderen'`. */
+  remove?: string
+  /** Accessible name of a stop's colour popover. Defaults to `'Kleur van kleurstop {n}'`. */
+  dialog?: string
+  /** Opacity part of a handle's value text. Defaults to `'dekking {n} %'`. */
+  stopOpacity?: string
+  /** Hint under the locked opacity slider of a stop bound to a preset. Defaults to `'Huisstijlkleuren zijn altijd dekkend.'`. */
+  roleOpaque?: string
+  /** Trigger text for a linear gradient. Defaults to `'Lineair verloop'`. */
+  triggerLinear?: string
+  /** Trigger text for a radial gradient. Defaults to `'Radiaal verloop'`. */
+  triggerRadial?: string
+  /** Name of the trigger swatch for a linear gradient. Defaults to `'Geselecteerd verloop: lineair, {n} kleuren'`. */
+  swatchLinear?: string
+  /** Name of the trigger swatch for a radial gradient. Defaults to `'Geselecteerd verloop: radiaal, {n} kleuren'`. */
+  swatchRadial?: string
+  /** Name of the trigger swatch while there is no gradient. Defaults to `'Geen kleur geselecteerd'`. */
+  swatchEmpty?: string
+}
+
+export const DEFAULT_GRADIENT_MESSAGES = {
+  mode: 'Vulling',
+  solid: 'Effen',
+  gradient: 'Verloop',
+  type: 'Type verloop',
+  linear: 'Lineair',
+  radial: 'Radiaal',
+  angle: 'Hoek',
+  angleValue: '{n} graden',
+  center: 'Middelpunt',
+  centerValue: '{x} % van links, {y} % van boven',
+  reverse: 'Kleurstops omdraaien',
+  stops: 'Kleurstops',
+  max: 'max. 3',
+  maxReason: 'Een verloop heeft maximaal 3 kleurstops.',
+  add: 'Toevoegen',
+  addName: 'Kleurstop toevoegen',
+  stop: 'Kleurstop {n} van {total}',
+  position: 'Positie (%)',
+  pick: 'Kleur kiezen',
+  hex: 'Hex',
+  remove: 'Verwijderen',
+  dialog: 'Kleur van kleurstop {n}',
+  stopOpacity: 'dekking {n} %',
+  roleOpaque: 'Huisstijlkleuren zijn altijd dekkend.',
+  triggerLinear: 'Lineair verloop',
+  triggerRadial: 'Radiaal verloop',
+  swatchLinear: 'Geselecteerd verloop: lineair, {n} kleuren',
+  swatchRadial: 'Geselecteerd verloop: radiaal, {n} kleuren',
+  swatchEmpty: 'Geen kleur geselecteerd',
+} satisfies Required<ColorPickerGradientMessages>
+
+export type GradientCopy = typeof DEFAULT_GRADIENT_MESSAGES
+
+/** Fills `{key}` placeholders in a message. */
+export const fillMessage = (message: string, values: Record<string, string | number>) =>
+  message.replace(/\{(\w+)\}/g, (match, key: string) =>
+    key in values ? String(values[key]) : match,
+  )