@nexxtmove/ui 2.1.0 → 2.3.0

package/src/components/editor/molecules/EditorColor/_ColorField.vue

@@ -0,0 +1,445 @@
+<script lang="ts">
+import type { ColorClass, EditorColorRole, EditorColorThemeRole } from './colorClass'
+import type { EditorColorGradientValue } from './gradientClass'
+import type {
+  ColorPickerFillMode,
+  ColorPickerGradientMessages,
+} from '../../../organisms/ColorPicker/ColorPicker.vue'
+
+export interface ColorFieldProps<P extends string> {
+  /** The prefix of the class that is written, such as `'bg'` or `'from'`. */
+  property: P
+  /**
+   * The prefixes that are read as a colour. Defaults to `property` alone.
+   * NexxtEditorColor reads both `bg` and `text`, so a value with the other
+   * prefix is shown, and rewritten once `property` changes.
+   */
+  accepts?: readonly P[]
+  /** Visible label above the trigger. Without it the placeholder names the trigger. */
+  label?: string
+  /** Id(s) set as `aria-describedby` on the trigger. */
+  describedby?: string
+  /** Text shown while no colour is set. */
+  placeholder: string
+  /** Label shown above the suggestions. */
+  suggestionsLabel: string
+  /** Label shown above the theme roles. */
+  themeLabel: string
+  /** Label above the opacity slider, and its accessible name. */
+  alphaLabel: string
+  /** Hex colours offered as one-click suggestions. */
+  suggestions?: string[]
+  /** Theme roles offered above the suggestions; an entry with an unreadable hex is left out. */
+  themeRoles?: EditorColorThemeRole[]
+  /** Offer an opacity slider, hidden while a theme role is selected. */
+  showAlpha?: boolean
+  /**
+   * The fills offered: `['solid']` (the default), `['solid', 'gradient']` or
+   * `['gradient']`. A gradient only exists for `property` `'bg'`; for any other
+   * prefix only the solid colour is offered, also with `['gradient']`. The
+   * gradient is written as the class string of `gradientClass.ts`.
+   */
+  modes?: readonly ColorPickerFillMode[]
+  /** Copy of the gradient mode, merged per key over the picker's defaults. */
+  gradientMessages?: ColorPickerGradientMessages
+}
+
+/** What switching to the gradient mode writes when there is no colour to start from. */
+const DEFAULT_GRADIENT_CLASS = 'bg-linear-180 from-[#00000000] to-[#00000099]'
+
+/**
+ * The picker writes `#rrggbbaa` only below full opacity, but an alpha a hair
+ * under 1 still rounds to `ff`. That pair says nothing, so it is dropped.
+ */
+const OPAQUE_ALPHA_PATTERN = /^(#[0-9A-Fa-f]{6})[fF]{2}$/
+</script>
+
+<script lang="ts" setup generic="P extends string">
+import { computed, ref, watch } from 'vue'
+import NexxtTooltip from '../../../atoms/Tooltip/Tooltip.vue'
+import NexxtColorPicker from '../../../organisms/ColorPicker/ColorPicker.vue'
+import type { ColorPickerGradient } from '../../../organisms/ColorPicker/ColorPicker.vue'
+import { clampCenter } from '../../../organisms/ColorPicker/gradientGeometry'
+import { COLOR_ROLES, ROLE_HEX_PATTERN, isHex, parseColorClass } from './colorClass'
+import {
+  looksLikeGradientClass,
+  normalizeGradientHex,
+  parseGradientClass,
+  serializeGradientClass,
+} from './gradientClass'
+import type { GradientClass, GradientClassColor } from './gradientClass'
+
+/**
+ * The colour picker of the editor: a hex with an optional opacity slider, or a
+ * theme role, and with `gradient` a gradient of those. The model is the class
+ * itself, built from `property`.
+ *
+ * `matchWidth` makes the panel as wide as the full-width trigger instead of the
+ * fixed `w-70` it defaults to. It works by setting a `min-width` on the floating
+ * element, so a panel in a container narrower than its content would still be
+ * wider than the trigger; in the settings column it is not.
+ */
+defineOptions({ name: 'NexxtColorField' })
+
+const {
+  property,
+  accepts,
+  label,
+  describedby,
+  placeholder,
+  suggestionsLabel,
+  themeLabel,
+  alphaLabel,
+  suggestions = [],
+  themeRoles = [],
+  showAlpha = false,
+  modes = ['solid'],
+  gradientMessages,
+} = defineProps<ColorFieldProps<P>>()
+
+/**
+ * The chosen colour, as the class to apply, or with `gradient` the gradient's
+ * class string. Unset or unreadable shows the placeholder.
+ */
+const model = defineModel<ColorClass<P> | EditorColorGradientValue>()
+
+const parsed = computed(() => parseColorClass(model.value, accepts ?? [property]))
+
+/** The hex out of the model, or an empty string when it is not a literal colour. */
+const hex = computed(() => (parsed.value && 'hex' in parsed.value ? parsed.value.hex : ''))
+
+/** The role out of the model, or `undefined` when it is not a role class. */
+const storedRole = computed(() =>
+  parsed.value && 'role' in parsed.value ? parsed.value.role : undefined,
+)
+
+const offeredRoles = computed(() => themeRoles.filter((entry) => ROLE_HEX_PATTERN.test(entry.hex)))
+
+/**
+ * The stored role as the consumer offers it. Only a role class selects a role:
+ * a literal colour that happens to equal a role's hex stays a literal.
+ */
+const activeRole = computed(() => offeredRoles.value.find(({ role }) => role === storedRole.value))
+
+/**
+ * Picking the role's own colour -- from the suggestions, or typed -- is how a
+ * colour is detached from the theme without changing how it looks. The picker
+ * reports nothing when it is told to pick the string it already has, so a role's
+ * hex is handed over in its 8-digit form: with `show-alpha` off the picker never
+ * reports an alpha pair, which makes every pick a change.
+ *
+ * A role has no opacity here, so an alpha pair in the role's own hex is replaced
+ * by `ff`. Handed over translucent, the picker would drop that alpha the moment
+ * the role turns `show-alpha` off, and write the opaque hex over the role.
+ */
+const pickerHex = (roleHex: string) => `${roleHex.slice(0, 7)}ff`
+
+/**
+ * A role class has no opacity, so the slider is only offered for a literal.
+ * Hiding it is also what keeps the trick in `pickerHex` working: without the
+ * alpha channel the picker reads the role's hex as opaque.
+ */
+const alphaEnabled = computed(() => showAlpha && !activeRole.value)
+
+// An unparseable value -- empty, a token class such as `bg-red-500`, or copy
+// from before this component -- leaves the picker empty and its placeholder
+// visible, rather than being reported as a problem: the first pick writes a
+// valid class back. A role the consumer does not offer is shown the same way,
+// because there is no label or hex to show it with; it is not written back.
+const picked = computed({
+  get: () => (activeRole.value ? pickerHex(activeRole.value.hex) : hex.value),
+  // The picker clears its own value in no flow it offers, but an empty string
+  // would still wipe a perfectly good colour, so it is dropped rather than
+  // written through. The picker keeps rendering the model's colour.
+  set: (value: string) => {
+    const color = value.replace(OPAQUE_ALPHA_PATTERN, '$1')
+    if (isHex(color)) model.value = `${property}-[${color}]`
+  },
+})
+
+const pickRole = (role: EditorColorRole) => {
+  model.value = `${property}-theme-${role}`
+}
+
+// ── Gradient ─────────────────────────────────────────────────────────────────
+
+/**
+ * The fills the picker offers. A gradient only exists for a background; for
+ * any other property this falls back to the solid colour alone.
+ */
+const offeredModes = computed<ColorPickerFillMode[]>(() => {
+  const withGradient = modes.includes('gradient') && property === 'bg'
+  if (!withGradient) return ['solid']
+  return modes.includes('solid') ? ['solid', 'gradient'] : ['gradient']
+})
+
+const gradientEnabled = computed(() => offeredModes.value.includes('gradient'))
+
+/** Only the gradient is offered: there is no switch, and the mode is always gradient. */
+const gradientOnly = computed(() => !offeredModes.value.includes('solid'))
+
+const parsedGradient = computed(() =>
+  gradientEnabled.value ? parseGradientClass(model.value) : null,
+)
+
+const modeOf = (value: string | undefined): ColorPickerFillMode | null => {
+  if (looksLikeGradientClass(value)) return 'gradient'
+  if (parseColorClass(value, accepts ?? [property])) return 'solid'
+  return null
+}
+
+/**
+ * Which fill the picker edits. It follows the model, but an empty or
+ * unreadable value keeps the mode the user switched to: the picker then shows
+ * its default, and nothing is written until the first change.
+ */
+const switchedMode = ref<ColorPickerFillMode>(
+  gradientEnabled.value ? (modeOf(model.value) ?? 'solid') : 'solid',
+)
+
+watch(
+  () => [model.value, gradientEnabled.value] as const,
+  ([value, enabled]) => {
+    if (!enabled) switchedMode.value = 'solid'
+    else switchedMode.value = modeOf(value) ?? switchedMode.value
+  },
+)
+
+const mode = computed<ColorPickerFillMode>(() => {
+  if (!gradientEnabled.value) return 'solid'
+  return gradientOnly.value ? 'gradient' : switchedMode.value
+})
+
+/** The selected stop, as its index in order of position. */
+const selectedStop = ref(0)
+
+/**
+ * The gradient last switched away from in this panel session, so switching
+ * back brings it back. Forgotten when the panel closes.
+ */
+const remembered = ref<{ value: EditorColorGradientValue; stop: number } | null>(null)
+
+const roleEntry = (role: EditorColorRole) => offeredRoles.value.find((entry) => entry.role === role)
+
+/**
+ * A gradient as the picker takes it. A role the consumer does not offer has
+ * no colour to paint, so such a gradient is shown as unreadable.
+ */
+const toPickerGradient = (parsed: GradientClass | null): ColorPickerGradient | undefined => {
+  if (!parsed) return undefined
+  const stops = []
+  for (const { color, position } of parsed.stops) {
+    if ('hex' in color) {
+      stops.push({ color: color.hex, position })
+      continue
+    }
+    const entry = roleEntry(color.role)
+    if (!entry) return undefined
+    stops.push({
+      color: entry.hex.slice(0, 7).toLowerCase(),
+      position,
+      preset: { key: entry.role, label: entry.label },
+    })
+  }
+  return {
+    type: parsed.type,
+    angle: parsed.type === 'linear' ? parsed.angle : 180,
+    // Read clamped to 1–99, as the preview's geometry works; a stored 0 or 100
+    // is only rewritten by a change.
+    centerX: parsed.type === 'radial' ? clampCenter(parsed.x) : 50,
+    centerY: parsed.type === 'radial' ? clampCenter(parsed.y) : 50,
+    stops,
+  }
+}
+
+const pickerGradient = computed(() => toPickerGradient(parsedGradient.value))
+
+/**
+ * With only the gradient offered, an empty value or a solid colour opens on
+ * the gradient a switch from solid would give: the colour fading out to its own
+ * hex at `00`. It is shown, not written, until the first change.
+ */
+const pickerGradientStart = computed(() =>
+  gradientOnly.value && gradientEnabled.value && !pickerGradient.value
+    ? toPickerGradient(parseGradientClass(gradientFromSolid()))
+    : undefined,
+)
+
+/** A stop from the picker as a class colour: its preset is a role, otherwise it is a hex. */
+const toClassColor = (color: string, presetKey?: string): GradientClassColor => {
+  const role = COLOR_ROLES.find((candidate) => candidate === presetKey)
+  if (role) return { role }
+  return { hex: normalizeGradientHex(isHex(color) ? color : `#${color}`) }
+}
+
+const writeGradient = (value: ColorPickerGradient | undefined) => {
+  if (!value) return
+  const stops = value.stops.map(({ color, position, preset }) => ({
+    color: toClassColor(color, preset?.key),
+    position,
+  }))
+  model.value = serializeGradientClass(
+    value.type === 'linear'
+      ? { type: 'linear', angle: value.angle, stops }
+      : { type: 'radial', x: value.centerX, y: value.centerY, stops },
+  )
+}
+
+/** The solid colour as the first stop of a new gradient, fading out to its own hex at `00`. */
+const gradientFromSolid = (): EditorColorGradientValue => {
+  const role = activeRole.value
+  const literal = hex.value
+  if (role) {
+    const hex6 = role.hex.slice(0, 7).toLowerCase()
+    return `bg-linear-180 from-theme-${role.role} to-[${hex6}00]`
+  }
+  if (literal) {
+    const from = normalizeGradientHex(literal)
+    return `bg-linear-180 from-[${from}] to-[${from.slice(0, 7)}00]`
+  }
+  return DEFAULT_GRADIENT_CLASS
+}
+
+/**
+ * A stop's hex as the solid colour. Without `showAlpha` the solid mode has no
+ * opacity, so the alpha is dropped -- as the picker does when `showAlpha` goes off.
+ */
+const solidHex = (stopHex: `#${string}`): `#${string}` => {
+  const normal = normalizeGradientHex(stopHex)
+  const opaque = normal.slice(0, 7)
+  return showAlpha || !isHex(opaque) ? normal : opaque
+}
+
+/** Whether the picker can paint every stop: a role stop needs a role the consumer offers. */
+const isShowable = (parsed: GradientClass) =>
+  parsed.stops.every(({ color }) => 'hex' in color || !!roleEntry(color.role))
+
+/**
+ * The selected stop (or the first) as a solid class with the given prefix: its
+ * role, or its hex -- without alpha when there is no opacity slider.
+ */
+const solidFromGradient = <Q extends string>(
+  parsed: GradientClass,
+  prefix: Q,
+): ColorClass<Q> | null => {
+  const stop = parsed.stops[selectedStop.value] ?? parsed.stops[0]
+  if (!stop) return null
+  return 'role' in stop.color
+    ? `${prefix}-theme-${stop.color.role}`
+    : `${prefix}-[${solidHex(stop.color.hex)}]`
+}
+
+const switchMode = (next: ColorPickerFillMode) => {
+  if (next === mode.value || gradientOnly.value) return
+  if (next === 'gradient') {
+    switchedMode.value = 'gradient'
+    const restore = remembered.value
+    selectedStop.value = restore?.stop ?? 0
+    model.value = restore?.value ?? gradientFromSolid()
+    return
+  }
+  switchedMode.value = 'solid'
+  // The same source as what the picker shows: a gradient it cannot show (a role
+  // the consumer does not offer) shows the default, so none of its stops is used.
+  const parsed = pickerGradient.value ? parsedGradient.value : null
+  if (!parsed) return
+  remembered.value = { value: serializeGradientClass(parsed), stop: selectedStop.value }
+  const solid = solidFromGradient(parsed, property)
+  if (solid) model.value = solid
+}
+
+/**
+ * A role swatch picks the role for the solid colour, or in the gradient mode
+ * for the selected stop, through the picker.
+ */
+const onRoleClick = (
+  entry: EditorColorThemeRole,
+  selectPreset: (preset: { key: string; label: string }, hex: string) => void,
+) => {
+  if (mode.value === 'gradient') selectPreset({ key: entry.role, label: entry.label }, entry.hex)
+  else pickRole(entry.role)
+}
+
+/** Whether a role swatch is pressed: the solid colour's role, or the selected stop's. */
+const isRolePressed = (role: EditorColorRole, stopPreset: string | undefined) =>
+  mode.value === 'gradient' ? role === stopPreset : role === activeRole.value?.role
+
+const onClose = () => {
+  remembered.value = null
+}
+
+// `property` is a prop, so the parent can flip a background setting into a
+// text-colour one while a value is already set. Rewriting the prefix here is
+// what keeps the stored class and the prop from drifting apart.
+watch(
+  () => property,
+  (next) => {
+    if (storedRole.value) model.value = `${next}-theme-${storedRole.value}`
+    else if (hex.value) model.value = `${next}-[${hex.value}]`
+    else if (next !== 'bg') {
+      // A gradient only exists for a background, so it becomes the solid colour
+      // of its selected stop, as a switch to "Effen" would make it.
+      const parsed = parseGradientClass(model.value)
+      const solid = parsed && isShowable(parsed) ? solidFromGradient(parsed, next) : null
+      if (solid) model.value = solid
+    }
+  },
+)
+</script>
+
+<template>
+  <NexxtColorPicker
+    v-model="picked"
+    v-model:selected-stop="selectedStop"
+    :modes="offeredModes"
+    :gradient-messages="gradientMessages"
+    :mode="mode"
+    :gradient-value="pickerGradient"
+    :gradient-start="pickerGradientStart"
+    full-width
+    match-width
+    :label="label"
+    :describedby="describedby"
+    :formats="['hex']"
+    :show-alpha="alphaEnabled"
+    :placeholder="placeholder"
+    :suggestions="{ hex: suggestions }"
+    :suggestions-label="suggestionsLabel"
+    :alpha-label="alphaLabel"
+    :value-label="activeRole?.label"
+    @update:mode="switchMode"
+    @update:gradient-value="writeGradient"
+    @close="onClose"
+  >
+    <template v-if="offeredRoles.length" #presets="{ preset, selectPreset }">
+      <div class="flex flex-col gap-1">
+        <span class="extra-small-normal text-gray-500">{{ themeLabel }}</span>
+        <!--
+            Same swatches and row as the picker's suggestions. Two roles often
+            share a hex (heading and text), so the tooltip is what tells them
+            apart; it repeats the accessible name rather than adding copy.
+          -->
+        <div class="flex flex-wrap gap-1.5">
+          <NexxtTooltip v-for="entry in offeredRoles" :key="entry.role" disable-closing-trigger>
+            <button
+              type="button"
+              :aria-label="entry.label"
+              :aria-pressed="isRolePressed(entry.role, preset)"
+              class="cursor-pointer rounded-md p-0.5 ring-gray-200 transition-shadow hover:ring-2 hover:ring-cornflower-blue-400 focus-visible:ring-2 focus-visible:ring-cornflower-blue-500 focus-visible:outline-none aria-pressed:ring-2 aria-pressed:ring-cornflower-blue-500"
+              @click="onRoleClick(entry, selectPreset)"
+            >
+              <span
+                aria-hidden="true"
+                class="block size-6 rounded-sm shadow-[inset_0_0_0_1px_rgba(0,0,0,0.1)]"
+                :style="{ backgroundColor: entry.hex }"
+              />
+            </button>
+            <template #tooltip>
+              <span class="small-normal text-gray-900">{{ entry.label }}</span>
+            </template>
+          </NexxtTooltip>
+        </div>
+      </div>
+    </template>
+  </NexxtColorPicker>
+</template>

package/src/components/editor/molecules/EditorColor/colorClass.ts

@@ -0,0 +1,61 @@
+/**
+ * Parsing of the colour classes of the editor: NexxtEditorColor writes `bg-`/
+ * `text-` classes, and its gradient `from-`/`via-`/`to-` ones (see
+ * `gradientClass.ts`). The class is always a prefix, then either a hex between
+ * brackets or `theme-` and a role.
+ */
+
+export const COLOR_ROLES = ['main', 'accent', 'background', 'heading', 'text'] as const
+
+/**
+ * A role of the customer's theme. A colour bound to a role follows the theme,
+ * where a literal colour stays what it was picked as.
+ */
+export type EditorColorRole = (typeof COLOR_ROLES)[number]
+
+export interface EditorColorThemeRole {
+  /** The role the class is written for: `'main'` becomes `bg-theme-main`. */
+  role: EditorColorRole
+  /** Name of the role as the user reads it, in the swatch's tooltip and in the trigger. */
+  label: string
+  /**
+   * The role's current colour as a 6- or 8-digit hex. Only used to paint the
+   * swatch: the library ships no CSS for the role classes, and the hex never
+   * reaches the model.
+   */
+  hex: string
+}
+
+/** A colour class with the given prefix: a literal hex or a theme role. */
+export type ColorClass<P extends string> = `${P}-[#${string}]` | `${P}-theme-${EditorColorRole}`
+
+/** What a colour class stands for, or `null` when it is not one. */
+export type ParsedColorClass = { hex: `#${string}` } | { role: EditorColorRole } | null
+
+/** The picker throws on a colour it cannot read, so a role's hex is checked first. */
+export const ROLE_HEX_PATTERN = /^#[0-9A-Fa-f]{6}(?:[0-9A-Fa-f]{2})?$/
+
+/**
+ * The `#` is part of the model's type, so a plain `string` cannot be written
+ * into it. This narrows a regex capture or picker output without a cast.
+ */
+export const isHex = (value: string): value is `#${string}` => value.startsWith('#')
+
+/**
+ * Reads a class written with one of `prefixes`. A 6- or 8-digit hex is accepted
+ * whatever its case, so a stored `#1777EA80` survives a round trip. A tint such
+ * as `bg-theme-main/10`, a token class such as `bg-red-500` or a class with
+ * another prefix is read as `null`.
+ */
+export const parseColorClass = (
+  value: string | undefined,
+  prefixes: readonly string[],
+): ParsedColorClass => {
+  if (!value) return null
+  const prefix = `(?:${prefixes.join('|')})`
+  const hex = new RegExp(`^${prefix}-\\[(#[0-9A-Fa-f]{6}(?:[0-9A-Fa-f]{2})?)\\]$`).exec(value)?.[1]
+  if (hex && isHex(hex)) return { hex }
+  const captured = new RegExp(`^${prefix}-theme-(${COLOR_ROLES.join('|')})$`).exec(value)?.[1]
+  const role = COLOR_ROLES.find((candidate) => candidate === captured)
+  return role ? { role } : null
+}