@nexxtmove/ui 2.2.0 → 2.3.0

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

@@ -0,0 +1,216 @@
+/**
+ * Geometry of the gradient preview: where a stop renders in a square of side
+ * `S`, and which angle, centre and positions a set of points stands for. The
+ * square's origin is its top-left corner with y pointing down; its centre is
+ * C = (S/2, S/2). Every derivation works on the rounded values that are
+ * written to the model, so the points and the rendered gradient always agree.
+ *
+ * Linear (CSS: 0° is up, clockwise): direction d = (sin θ, −cos θ), length of
+ * the gradient line L = S·(|sin θ| + |cos θ|), and a point P sits at
+ * t = 0.5 + ((P − C)·d) / L.
+ *
+ * Radial (`ellipse farthest-corner`): an ellipse with the proportions of
+ * `closest-side` that runs through the farthest corner, and t is the
+ * normalized distance from the centre.
+ */
+
+export interface Point {
+  x: number
+  y: number
+}
+
+const toRadians = (degrees: number) => (degrees * Math.PI) / 180
+
+/** A rounded percentage, clamped to 0–100. */
+const toPercent = (t: number) => Math.min(100, Math.max(0, Math.round(100 * t)))
+
+// ── Linear ────────────────────────────────────────────────────────────────
+
+export const linearDirection = (angle: number): Point => {
+  const radians = toRadians(angle)
+  return { x: Math.sin(radians), y: -Math.cos(radians) }
+}
+
+/** Length of the CSS gradient line for `angle` in a square of side `size`. */
+export const linearLength = (angle: number, size: number) => {
+  const radians = toRadians(angle)
+  return size * (Math.abs(Math.sin(radians)) + Math.abs(Math.cos(radians)))
+}
+
+/** Where on the gradient line a point projects, 0–1 inside the square (unclamped). */
+export const linearT = (angle: number, point: Point, size: number) => {
+  const d = linearDirection(angle)
+  const c = size / 2
+  return 0.5 + ((point.x - c) * d.x + (point.y - c) * d.y) / linearLength(angle, size)
+}
+
+/** The position a point stands for: a whole percentage, 0–100. */
+export const linearPosition = (angle: number, point: Point, size: number) =>
+  toPercent(linearT(angle, point, size))
+
+/** The canonical point of a position: on the line through the middle. */
+export const linearPoint = (angle: number, position: number, size: number): Point => {
+  const d = linearDirection(angle)
+  const offset = (position / 100 - 0.5) * linearLength(angle, size)
+  return { x: size / 2 + offset * d.x, y: size / 2 + offset * d.y }
+}
+
+/** Whether a point lies in the square (edges included). */
+export const isInSquare = (point: Point, size: number) =>
+  point.x >= 0 && point.x <= size && point.y >= 0 && point.y <= size
+
+/** A pointer clamped onto the square, so a dragged point never leaves it. */
+export const clampToSquare = (point: Point, size: number): Point => ({
+  x: Math.min(size, Math.max(0, point.x)),
+  y: Math.min(size, Math.max(0, point.y)),
+})
+
+/**
+ * Where the handle of a position is drawn: its canonical point, or -- when that
+ * lies outside the square, as 0 % and 100 % do at angles off the axes -- where
+ * the gradient line leaves the square. The handle is a grip; the class and the
+ * numbers stay the real CSS values.
+ */
+export const linearHandlePoint = (angle: number, position: number, size: number): Point => {
+  const d = linearDirection(angle)
+  const half = size / 2
+  const reach = Math.min(
+    Math.abs(d.x) > 1e-9 ? half / Math.abs(d.x) : Infinity,
+    Math.abs(d.y) > 1e-9 ? half / Math.abs(d.y) : Infinity,
+  )
+  const offset = (position / 100 - 0.5) * linearLength(angle, size)
+  const clamped = Math.min(reach, Math.max(-reach, offset))
+  return { x: half + clamped * d.x, y: half + clamped * d.y }
+}
+
+/**
+ * The angle from the from-point to the to-point, in whole degrees 0–359. Two
+ * points closer than `minDistance` say nothing about a direction, so the
+ * previous angle stays.
+ */
+export const angleBetween = (from: Point, to: Point, previous: number, minDistance: number) => {
+  const dx = to.x - from.x
+  const dy = to.y - from.y
+  if (Math.hypot(dx, dy) < minDistance) return previous
+  const degrees = Math.round((Math.atan2(dx, -dy) * 180) / Math.PI)
+  return ((degrees % 360) + 360) % 360
+}
+
+/** How far a point lies along the segment from `a` to `b`, clamped to 0–1. */
+export const projectOnSegment = (point: Point, a: Point, b: Point) => {
+  const dx = b.x - a.x
+  const dy = b.y - a.y
+  const lengthSquared = dx * dx + dy * dy
+  if (lengthSquared === 0) return 0.5
+  const f = ((point.x - a.x) * dx + (point.y - a.y) * dy) / lengthSquared
+  return Math.min(1, Math.max(0, f))
+}
+
+/** The point at fraction `f` from `a` to `b`. */
+export const lerpPoint = (a: Point, b: Point, f: number): Point => ({
+  x: a.x + f * (b.x - a.x),
+  y: a.y + f * (b.y - a.y),
+})
+
+/** Where the via stop sits between from and to: (via − from) / (to − from), or 0.5. */
+export const viaFraction = (from: number, via: number, to: number) =>
+  to === from ? 0.5 : (via - from) / (to - from)
+
+/**
+ * The angle and positions a set of points stands for: the angle from the
+ * from-point to the to-point, each position the projection of its point on the
+ * line of that rounded angle, and via at fraction `f` of the segment.
+ */
+export const linearFromPoints = (options: {
+  from: Point
+  to: Point
+  viaFraction?: number
+  previousAngle: number
+  size: number
+  minDistance: number
+}) => {
+  const { from, to, viaFraction: f, previousAngle, size, minDistance } = options
+  const angle = angleBetween(from, to, previousAngle, minDistance)
+  return {
+    angle,
+    from: linearPosition(angle, from, size),
+    via: f === undefined ? undefined : linearPosition(angle, lerpPoint(from, to, f), size),
+    to: linearPosition(angle, to, size),
+  }
+}
+
+// ── Radial ────────────────────────────────────────────────────────────────
+
+export interface RadialEllipse {
+  /** Centre in px. */
+  x: number
+  y: number
+  /** Radii in px. */
+  rx: number
+  ry: number
+}
+
+/**
+ * Clamps a centre percentage to 1–99: at 0 or 100 the closest side is 0 and
+ * CSS degenerates the ellipse.
+ */
+export const clampCenter = (value: number) => Math.min(99, Math.max(1, Math.round(value)))
+
+/** The `farthest-corner` ellipse of a centre at (cx %, cy %) in a square of side `size`. */
+export const radialEllipse = (cx: number, cy: number, size: number): RadialEllipse => {
+  const x = (clampCenter(cx) * size) / 100
+  const y = (clampCenter(cy) * size) / 100
+  const k = Math.min(x, size - x) / Math.min(y, size - y)
+  const dx = Math.max(x, size - x)
+  const dy = Math.max(y, size - y)
+  const ry = Math.sqrt((dx / k) ** 2 + dy ** 2)
+  return { x, y, rx: k * ry, ry }
+}
+
+/** The normalized distance of a point from the centre; 1 on the ellipse (unclamped). */
+export const radialT = (ellipse: RadialEllipse, point: Point) =>
+  Math.hypot((point.x - ellipse.x) / ellipse.rx, (point.y - ellipse.y) / ellipse.ry)
+
+export const radialPosition = (ellipse: RadialEllipse, point: Point) =>
+  toPercent(radialT(ellipse, point))
+
+/** The direction of the ray through a point, in the ellipse's own coordinates. */
+export const radialAngle = (ellipse: RadialEllipse, point: Point) =>
+  Math.atan2((point.y - ellipse.y) / ellipse.ry, (point.x - ellipse.x) / ellipse.rx)
+
+/** The ray towards the farthest corner, where 100 % falls exactly on the corner. */
+export const farthestCornerAngle = (ellipse: RadialEllipse, size: number) =>
+  radialAngle(ellipse, {
+    x: ellipse.x <= size / 2 ? size : 0,
+    y: ellipse.y <= size / 2 ? size : 0,
+  })
+
+/**
+ * The ray the stops are drawn on: `psi` while the farthest stop (`position`)
+ * still lies inside the square, otherwise the ray to the farthest corner. That
+ * one always fits: 100 % lands exactly on the corner. A ψ from a drag, or one
+ * left over after the centre moved, could otherwise put a point outside the
+ * preview, over the controls around it.
+ */
+export const radialRay = (
+  ellipse: RadialEllipse,
+  psi: number | null,
+  position: number,
+  size: number,
+) => {
+  if (psi === null) return farthestCornerAngle(ellipse, size)
+  const end = radialPoint(ellipse, psi, position)
+  const slack = size * 1e-6
+  const inside =
+    end.x >= -slack && end.x <= size + slack && end.y >= -slack && end.y <= size + slack
+  return inside ? psi : farthestCornerAngle(ellipse, size)
+}
+
+/** The point of a position on the ray `psi`: M + t·(E − M). */
+export const radialPoint = (ellipse: RadialEllipse, psi: number, position: number): Point => {
+  const t = position / 100
+  return {
+    x: ellipse.x + t * ellipse.rx * Math.cos(psi),
+    y: ellipse.y + t * ellipse.ry * Math.sin(psi),
+  }
+}

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

@@ -0,0 +1,358 @@
+import { computed, ref, watch } from 'vue'
+import type { Ref } from 'vue'
+import {
+  DEFAULT_ANGLE,
+  DEFAULT_CENTER,
+  DEFAULT_GRADIENT,
+  MAX_STOPS,
+  MIN_STOPS,
+  clampPercent,
+  colorAt,
+  normalizeHex,
+  wrapAngle,
+} from './gradient'
+import type { ColorPickerGradient, ColorPickerPreset } from './gradient'
+import { clampCenter } from './gradientGeometry'
+
+/** A stop as the editor keeps it: with an id, so it stays itself while it moves. */
+export interface GradientEditorStop {
+  id: number
+  color: string
+  position: number
+  preset?: ColorPickerPreset
+}
+
+/**
+ * Compares two gradients on what they would store: a linear gradient has no
+ * centre and a radial one no angle, so those are left out.
+ */
+const keyOf = (gradient: ColorPickerGradient) =>
+  JSON.stringify([
+    gradient.type,
+    gradient.type === 'linear' ? gradient.angle : [gradient.centerX, gradient.centerY],
+    gradient.stops.map(({ color, position, preset }) => [
+      normalizeHex(color),
+      position,
+      preset?.key ?? null,
+      preset?.label ?? null,
+    ]),
+  ])
+
+/**
+ * State and actions of the picker's gradient mode. The stops are kept in the
+ * order of their handles in the DOM, which is only brought back in line with
+ * their positions once an action is over (`settle`): a dragged stop that passes
+ * another keeps its id, colour, selection and focus. What reaches the model is
+ * always in order of position, ties in the order they had before.
+ *
+ * `value` is the model. A change from outside is merged into the stops that are
+ * there, so ids survive a round trip through the parent; a different number of
+ * stops starts over. While `value` is unset `start` (or the default gradient)
+ * is shown and nothing is written until the first action.
+ */
+export const useGradientEditor = (options: {
+  value: Ref<ColorPickerGradient | undefined>
+  selectedIndex: Ref<number>
+  /** What to show while `value` is unset; the default gradient without it. */
+  start?: () => ColorPickerGradient | undefined
+}) => {
+  const { value, selectedIndex, start } = options
+
+  const type = ref<ColorPickerGradient['type']>(DEFAULT_GRADIENT.type)
+  const angle = ref(DEFAULT_ANGLE)
+  const centerX = ref(DEFAULT_CENTER)
+  const centerY = ref(DEFAULT_CENTER)
+  const stops = ref<GradientEditorStop[]>([])
+  const selectedId = ref(0)
+  /** In a radial gradient the centre can be the selected point instead of a stop. */
+  const centerSelected = ref(false)
+
+  let nextId = 1
+  let lastKey: string | null = null
+
+  /** The stops in order of position; equal positions keep their order. */
+  const sorted = computed(() =>
+    stops.value
+      .map((stop, index) => ({ stop, index }))
+      .sort((a, b) => a.stop.position - b.stop.position || a.index - b.index)
+      .map(({ stop }) => stop),
+  )
+
+  const snapshot = computed<ColorPickerGradient>(() => ({
+    type: type.value,
+    angle: angle.value,
+    centerX: centerX.value,
+    centerY: centerY.value,
+    stops: sorted.value.map(({ color, position, preset }) =>
+      preset ? { color, position, preset } : { color, position },
+    ),
+  }))
+
+  const selected = computed(() => stops.value.find((stop) => stop.id === selectedId.value))
+  const selectedOrder = computed(() => sorted.value.findIndex((s) => s.id === selectedId.value))
+  const canAdd = computed(() => stops.value.length < MAX_STOPS)
+  const canRemove = computed(() => stops.value.length > MIN_STOPS)
+
+  /** The colour of the next stop on position, or of the one before for the last. */
+  const neighbourColor = computed(() => {
+    const index = selectedOrder.value
+    const neighbour = sorted.value[index + 1] ?? sorted.value[index - 1]
+    return neighbour?.color
+  })
+
+  const syncSelectedIndex = () => {
+    const index = selectedOrder.value
+    if (index !== -1 && selectedIndex.value !== index) selectedIndex.value = index
+  }
+
+  const commit = () => {
+    value.value = snapshot.value
+    lastKey = keyOf(snapshot.value)
+    syncSelectedIndex()
+  }
+
+  const selectIndex = (index: number) => {
+    const stop = sorted.value[Math.min(Math.max(index, 0), sorted.value.length - 1)]
+    if (stop) selectedId.value = stop.id
+  }
+
+  const load = (gradient: ColorPickerGradient) => {
+    type.value = gradient.type
+    angle.value = gradient.angle
+    centerX.value = gradient.centerX
+    centerY.value = gradient.centerY
+    stops.value = gradient.stops.map((stop) => ({ ...stop, id: nextId++ }))
+    selectIndex(selectedIndex.value)
+    // A different number of stops can clamp the index (3 → 2 after an undo):
+    // the parent reads it, so it gets the clamped one back.
+    syncSelectedIndex()
+  }
+
+  const merge = (gradient: ColorPickerGradient) => {
+    if (keyOf(gradient) === lastKey) return
+    lastKey = keyOf(gradient)
+    if (gradient.stops.length !== stops.value.length) return load(gradient)
+    type.value = gradient.type
+    if (gradient.type === 'linear') angle.value = gradient.angle
+    else {
+      centerX.value = gradient.centerX
+      centerY.value = gradient.centerY
+    }
+    const current = sorted.value
+    gradient.stops.forEach((incoming, index) => {
+      const stop = current[index]
+      if (!stop) return
+      stop.color = incoming.color
+      stop.position = incoming.position
+      stop.preset = incoming.preset
+    })
+    settle()
+  }
+
+  watch(
+    [value, () => (value.value ? undefined : start?.())],
+    ([gradient, startValue]) => {
+      if (gradient) return merge(gradient)
+      lastKey = null
+      load(startValue ?? DEFAULT_GRADIENT)
+    },
+    { immediate: true },
+  )
+
+  // An index from outside can be out of range (7 with three stops): it is
+  // clamped, and the parent gets the clamped index back.
+  watch(selectedIndex, (index) => {
+    if (index === selectedOrder.value) return
+    selectIndex(index)
+    syncSelectedIndex()
+  })
+
+  /** Puts the handles back in order of position, once an action is over. */
+  const settle = () => {
+    const order = sorted.value
+    if (order.some((stop, index) => stop !== stops.value[index])) stops.value = [...order]
+  }
+
+  const select = (id: number) => {
+    selectedId.value = id
+    centerSelected.value = false
+    syncSelectedIndex()
+  }
+
+  const selectCenter = () => {
+    centerSelected.value = true
+  }
+
+  const setType = (next: ColorPickerGradient['type']) => {
+    if (next === type.value) return
+    type.value = next
+    centerSelected.value = false
+    commit()
+  }
+
+  const setAngle = (next: number) => {
+    const wrapped = wrapAngle(next)
+    if (wrapped === angle.value && value.value) return
+    angle.value = wrapped
+    commit()
+  }
+
+  /** Sets the centre of a radial gradient, clamped to 1–99 (at 0 or 100 CSS degenerates it). */
+  const setCenter = (x: number, y: number) => {
+    const nextX = clampCenter(x)
+    const nextY = clampCenter(y)
+    if (nextX === centerX.value && nextY === centerY.value && value.value) return
+    centerX.value = nextX
+    centerY.value = nextY
+    commit()
+  }
+
+  const moveStop = (id: number, position: number) => {
+    const stop = stops.value.find((candidate) => candidate.id === id)
+    const next = clampPercent(position)
+    if (!stop || (stop.position === next && value.value)) return
+    stop.position = next
+    commit()
+  }
+
+  /**
+   * Sets several positions at once, and the angle with them: a drag in the
+   * preview moves the points of a whole gradient in one step.
+   */
+  const setGeometry = (positions: Map<number, number>, nextAngle?: number) => {
+    let changed = false
+    positions.forEach((position, id) => {
+      const stop = stops.value.find((candidate) => candidate.id === id)
+      const next = clampPercent(position)
+      if (stop && stop.position !== next) {
+        stop.position = next
+        changed = true
+      }
+    })
+    if (nextAngle !== undefined && wrapAngle(nextAngle) !== angle.value) {
+      angle.value = wrapAngle(nextAngle)
+      changed = true
+    }
+    if (changed || !value.value) commit()
+  }
+
+  /**
+   * Adds a stop at `position`, or halfway between the first and the last, in
+   * the colour the gradient already has there so it does not change. Between
+   * two stops bound to the same preset the new stop is bound to it too.
+   * Returns the new stop's id, or `null` when there are already three.
+   */
+  const addStop = (position?: number) => {
+    if (!canAdd.value) return null
+    const order = sorted.value
+    const first = order[0]
+    const last = order[order.length - 1]
+    if (!first || !last) return null
+    const at = clampPercent(position ?? (first.position + last.position) / 2)
+    const preset = first.preset && first.preset.key === last.preset?.key ? first.preset : undefined
+    const stop: GradientEditorStop = {
+      id: nextId++,
+      color: preset ? first.color : colorAt(order, at),
+      position: at,
+      ...(preset ? { preset } : {}),
+    }
+    stops.value = [...stops.value, stop]
+    settle()
+    selectedId.value = stop.id
+    commit()
+    return stop.id
+  }
+
+  /**
+   * Removes a stop; only possible with three. The other two keep their
+   * positions. Returns the id of the neighbour that takes the selection -- the
+   * one before, or the one after when the first was removed -- or `null`.
+   */
+  const removeStop = (id: number) => {
+    if (!canRemove.value) return null
+    const order = sorted.value
+    const index = order.findIndex((stop) => stop.id === id)
+    if (index === -1) return null
+    const neighbour = order[index - 1] ?? order[index + 1]
+    if (!neighbour) return null
+    stops.value = order.filter((stop) => stop.id !== id)
+    selectedId.value = neighbour.id
+    commit()
+    return neighbour.id
+  }
+
+  /**
+   * Mirrors the stops: every position p becomes 100 - p and the order turns
+   * around. Angle, centre, selection and focus stay. A gradient that is its own
+   * mirror image is left alone, so the consumer records no step.
+   */
+  const reverse = () => {
+    const mirrored = [...sorted.value]
+      .reverse()
+      .map((stop) => ({ ...stop, position: 100 - stop.position }))
+    const before = keyOf(snapshot.value)
+    const after = keyOf({ ...snapshot.value, stops: mirrored })
+    if (before === after && value.value) return
+    stops.value = mirrored
+    commit()
+  }
+
+  /** Gives a stop a colour, or binds it to a preset in that preset's colour. */
+  const setColorOf = (id: number, color: string, preset?: ColorPickerPreset) => {
+    const stop = stops.value.find((candidate) => candidate.id === id)
+    if (!stop) return
+    const hex = normalizeHex(color)
+    if (stop.color === hex && stop.preset?.key === preset?.key && value.value) return
+    stop.color = hex
+    stop.preset = preset
+    commit()
+  }
+
+  /** Gives the selected stop a colour, or binds it to a preset in that preset's colour. */
+  const setStopColor = (color: string, preset?: ColorPickerPreset) =>
+    setColorOf(selectedId.value, color, preset)
+
+  /**
+   * Forgets what is only remembered for the panel session: the centre of a
+   * linear gradient and the angle of a radial one.
+   */
+  const resetSession = () => {
+    if (type.value === 'linear') {
+      centerX.value = DEFAULT_CENTER
+      centerY.value = DEFAULT_CENTER
+    } else angle.value = DEFAULT_ANGLE
+  }
+
+  return {
+    type,
+    angle,
+    centerX,
+    centerY,
+    stops,
+    sorted,
+    snapshot,
+    selectedId,
+    centerSelected,
+    selected,
+    selectedOrder,
+    canAdd,
+    canRemove,
+    neighbourColor,
+    select,
+    selectCenter,
+    settle,
+    setType,
+    setAngle,
+    setCenter,
+    moveStop,
+    setGeometry,
+    addStop,
+    removeStop,
+    reverse,
+    setStopColor,
+    setColorOf,
+    resetSession,
+  }
+}
+
+export type GradientEditor = ReturnType<typeof useGradientEditor>

package/src/index.ts

@@ -45,6 +45,26 @@ export type {
   NexxtPlaceholderInputMessages,
   NexxtPlaceholderInputProps,
 } from './components/molecules/PlaceholderInput/PlaceholderInput.vue'
+export type {
+  ColorFormat,
+  ColorPickerGradient,
+  ColorPickerGradientMessages,
+  ColorPickerGradientStop,
+  ColorPickerFillMode,
+  ColorPickerPreset,
+  ColorSuggestions,
+} from './components/organisms/ColorPicker/ColorPicker.vue'
+export {
+  gradientClassToCss,
+  looksLikeGradientClass,
+  parseGradientClass,
+} from './components/editor/molecules/EditorColor/gradientClass'
+export type {
+  GradientClass,
+  GradientClassColor,
+  GradientClassStop,
+  GradientClassType,
+} from './components/editor/molecules/EditorColor/gradientClass'
 export { EDITOR_ALIGNMENT_POSITIONS } from './components/editor/molecules/EditorAlignmentGrid/EditorAlignmentGrid.vue'
 export type {
   EditorAlignmentDirection,
@@ -87,9 +107,14 @@ export type {
   EditorGapValue,
 } from './components/editor/molecules/EditorGap/EditorGap.vue'
 export type {
+  EditorColorFillMode,
+  EditorColorGradientMessages,
+  EditorColorGradientValue,
+  EditorColorLinearGradientValue,
   EditorColorLiteralValue,
   EditorColorMessages,
   EditorColorProperty,
+  EditorColorRadialGradientValue,
   EditorColorRole,
   EditorColorRoleValue,
   EditorColorThemeRole,