@nexxtmove/ui 1.34.0 → 1.36.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nexxtmove/ui",
   "type": "module",
-  "version": "1.34.0",
+  "version": "1.36.0",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",

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

@@ -7,17 +7,47 @@
  */
 export type EditorColorProperty = 'bg' | 'text'
 
+const ROLES = ['main', 'accent', 'background', 'heading', 'text'] as const
+
 /**
- * The colour as the editor needs it: a Tailwind arbitrary-value class such as
- * `'bg-[#1777EA]'`, so the consumer can put the model value straight on the
- * element it styles.
+ * 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 EditorColorValue = `${EditorColorProperty}-[#${string}]`
+export type EditorColorRole = (typeof ROLES)[number]
+
+/** A literal colour: a Tailwind arbitrary-value class such as `'bg-[#1777EA]'`. */
+export type EditorColorLiteralValue = `${EditorColorProperty}-[#${string}]`
+
+/** A colour bound to a theme role: a token class such as `'bg-theme-main'`. */
+export type EditorColorRoleValue = `${EditorColorProperty}-theme-${EditorColorRole}`
+
+/**
+ * The colour as the editor needs it: the class to apply, so the consumer can
+ * put the model value straight on the element it styles. Either a literal
+ * colour or a theme role.
+ */
+export type EditorColorValue = EditorColorLiteralValue | EditorColorRoleValue
+
+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
+}
 
-/** Overridable copy of the picker. Every key is optional. */
 export interface EditorColorMessages {
   /** Text shown while no colour is set. Defaults to `'Kies kleur...'`. */
   placeholder?: string
+  /** Label shown above reusable colours. */
+  suggestionsLabel?: string
+  /** Label shown above the theme roles. Defaults to `'Huisstijl'`. */
+  themeLabel?: string
 }
 
 export interface NexxtEditorColorProps {
@@ -44,25 +74,47 @@ export interface NexxtEditorColorProps {
    * defaults of the others. Copy is never translated inside the component.
    */
   messages?: EditorColorMessages
+  /** Hex colours available inside the picker panel as one-click suggestions. */
+  suggestions?: string[]
+  /**
+   * Theme roles offered above the suggestions. Picking one writes the role
+   * class for the current `property` instead of a literal colour. Which roles
+   * are offered is up to the consumer; an entry whose `hex` is not a 6- or
+   * 8-digit hex is left out. Without roles the section is not rendered.
+   */
+  themeRoles?: EditorColorThemeRole[]
 }
 
 const DEFAULT_MESSAGES = {
   placeholder: 'Kies kleur...',
+  suggestionsLabel: 'Gebruikte kleuren',
+  themeLabel: 'Huisstijl',
 } satisfies Required<EditorColorMessages>
 
 /**
- * A full model value: one of the two prefixes, then a 6- or 8-digit hex between
+ * A literal model value: one of the two prefixes, then a 6- or 8-digit hex between
  * brackets. A `border-[…]` class is therefore read as unparseable, the same as
  * any other class this component does not own. The
  * alpha pair is accepted on read so a stored `#1777EA80` survives a round trip,
  * even though the picker itself is opened without an alpha channel here.
  */
 const VALUE_PATTERN = /^(bg|text)-\[(#[0-9A-Fa-f]{6}(?:[0-9A-Fa-f]{2})?)\]$/
+
+/**
+ * A role class: one of the two prefixes, then `theme-` and one of the five
+ * roles. Either prefix takes every role. A tint such as `bg-theme-main/10` is
+ * not a value this component writes, so it is read as unparseable.
+ */
+const ROLE_PATTERN = new RegExp(`^(?:bg|text)-theme-(${ROLES.join('|')})$`)
+
+/** The picker throws on a colour it cannot read, so a role's hex is checked first. */
+const ROLE_HEX_PATTERN = /^#[0-9A-Fa-f]{6}(?:[0-9A-Fa-f]{2})?$/
 </script>
 
 <script lang="ts" setup>
 import { computed, watch } from 'vue'
 import NexxtEditorSettingsBlock from '../../atoms/EditorSettingsBlock/EditorSettingsBlock.vue'
+import NexxtTooltip from '../../../atoms/Tooltip/Tooltip.vue'
 import NexxtColorPicker from '../../../organisms/ColorPicker/ColorPicker.vue'
 
 defineOptions({ name: 'NexxtEditorColor' })
@@ -72,17 +124,22 @@ const {
   switchable = false,
   property = 'bg',
   messages,
+  suggestions = [],
+  themeRoles = [],
 } = defineProps<NexxtEditorColorProps>()
 
 /**
  * The chosen colour, as the Tailwind class to apply.
  *
  * Beware: Tailwind only generates an arbitrary class for text it finds in the
- * source at build time. A value that arrives at runtime -- from a database,
- * say -- therefore gets no CSS of its own; the consumer either translates it
- * into an inline style or safelists the classes it can produce. The hex is
- * always parseable out of the string, which is what makes that translation
- * possible.
+ * source at build time. A literal value that arrives at runtime -- from a
+ * database, say -- therefore gets no CSS of its own; the consumer either
+ * translates it into an inline style or safelists the classes it can produce.
+ * The hex is always parseable out of a literal value, which is what makes that
+ * translation possible.
+ *
+ * A role class is a finite list, so it is static CSS -- but the consumer's:
+ * this library defines no `theme-*` colours.
  */
 const model = defineModel<EditorColorValue>({ required: true })
 
@@ -104,12 +161,36 @@ const hex = computed(() => {
   return captured && isHex(captured) ? captured : ''
 })
 
+/** The role out of the model, or `undefined` when it is not a role class. */
+const storedRole = computed(() => {
+  const captured = ROLE_PATTERN.exec(model.value)?.[1]
+  return ROLES.find((role) => role === captured)
+})
+
+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.
+ */
+const pickerHex = (roleHex: string) => (roleHex.length === 7 ? `${roleHex}ff` : roleHex)
+
 // 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.
+// 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: () => hex.value,
+  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.
@@ -118,13 +199,18 @@ const picked = computed({
   },
 })
 
+const pickRole = (role: EditorColorRole) => {
+  model.value = `${property}-theme-${role}`
+}
+
 // `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 (hex.value) model.value = `${next}-[${hex.value}]`
+    if (storedRole.value) model.value = `${next}-theme-${storedRole.value}`
+    else if (hex.value) model.value = `${next}-[${hex.value}]`
   },
 )
 </script>
@@ -150,6 +236,44 @@ watch(
       :formats="['hex']"
       :show-alpha="false"
       :placeholder="copy.placeholder"
-    />
+      :suggestions="{ hex: suggestions }"
+      :suggestions-label="copy.suggestionsLabel"
+      :value-label="activeRole?.label"
+    >
+      <template v-if="offeredRoles.length" #presets>
+        <div class="flex flex-col gap-1">
+          <span class="extra-small-normal text-gray-500">{{ copy.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="{ role, label: roleLabel, hex: roleHex } in offeredRoles"
+              :key="role"
+              disable-closing-trigger
+            >
+              <button
+                type="button"
+                :aria-label="roleLabel"
+                :aria-pressed="role === activeRole?.role"
+                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="pickRole(role)"
+              >
+                <span
+                  aria-hidden="true"
+                  class="block size-6 rounded-sm shadow-[inset_0_0_0_1px_rgba(0,0,0,0.1)]"
+                  :style="{ backgroundColor: roleHex }"
+                />
+              </button>
+              <template #tooltip>
+                <span class="small-normal text-gray-900">{{ roleLabel }}</span>
+              </template>
+            </NexxtTooltip>
+          </div>
+        </div>
+      </template>
+    </NexxtColorPicker>
   </NexxtEditorSettingsBlock>
 </template>

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

@@ -19,6 +19,7 @@ import NexxtFloatingPanel from '../../atoms/FloatingPanel/FloatingPanel.vue'
 import NexxtIcon from '../../atoms/Icon/Icon.vue'
 
 export type ColorFormat = 'hex' | 'hsl' | 'rgb'
+export type ColorSuggestions = Partial<Record<ColorFormat, string[]>>
 
 export interface NexxtColorPickerProps {
   label?: string
@@ -30,10 +31,24 @@ export interface NexxtColorPickerProps {
   formats?: ColorFormat[]
   fullWidth?: boolean
   matchWidth?: boolean
+  /** Existing colours grouped by format; only suggestions for the active format are shown. */
+  suggestions?: ColorSuggestions
+  /** Accessible and visible label for the suggestions. */
+  suggestionsLabel?: string
+  /**
+   * Text shown in the trigger in place of the formatted colour, for a value that has a name of
+   * its own, such as a theme role. Only shown while a colour is set.
+   */
+  valueLabel?: string
 }
 
 defineOptions({ name: 'NexxtColorPicker' })
 
+defineSlots<{
+  /** Named colours a wrapper offers next to the free picker; rendered above the suggestions. */
+  presets?(): unknown
+}>()
+
 const PICKER_ID = 'color-picker-' + Math.random().toString(36).slice(2, 10)
 
 const props = withDefaults(defineProps<NexxtColorPickerProps>(), {
@@ -42,24 +57,66 @@ const props = withDefaults(defineProps<NexxtColorPickerProps>(), {
   formats: () => ['hex'],
   fullWidth: false,
   matchWidth: false,
+  suggestions: () => ({}),
+  suggestionsLabel: 'Gebruikte kleuren',
 })
 
 const model = defineModel<string>({ default: '' })
 
-const colorObj = ref<Color>(normalizeColor(model.value || '#3b82f6'))
-const hexInputError = ref('')
-const activeFormatIndex = ref(0)
-const channelInputErrors = ref<Partial<Record<ColorChannel, string>>>({})
+const withoutAlpha = (color: Color) =>
+  color.alpha < 1 ? setChannelValue(color, 'alpha', 100) : color
 
-const hexColor = computed(() => colorToString(colorObj.value, 'hex'))
-const activeFormat = computed<ColorFormat>(() => props.formats[activeFormatIndex.value] ?? 'hex')
-const displayValue = computed(() => (model.value ? fmt(colorObj.value, activeFormat.value) : ''))
+const normalizeModelColor = (value: string) => {
+  const color = normalizeColor(value)
+
+  return props.showAlpha ? color : withoutAlpha(color)
+}
+
+const normalizeInputColor = (value: string) => {
+  const color = normalizeColor(value)
+
+  if (!props.showAlpha && color.alpha < 1) {
+    throw new Error('Transparantie is niet beschikbaar')
+  }
+
+  return color
+}
 
+const activeFormatIndex = ref(0)
+const activeFormat = computed<ColorFormat>(() => props.formats[activeFormatIndex.value] ?? 'hex')
 const fmt = (color: Color, format: ColorFormat) => {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   return colorToString(color, format as any)
 }
 
+const colorObj = ref<Color>(normalizeModelColor(model.value || '#3b82f6'))
+const hexInputError = ref('')
+const channelInputErrors = ref<Partial<Record<ColorChannel, string>>>({})
+
+const hexColor = computed(() => colorToString(colorObj.value, 'hex'))
+const displayValue = computed(() =>
+  model.value ? props.valueLabel || fmt(colorObj.value, activeFormat.value) : '',
+)
+const colorSuggestions = computed(() => {
+  const values = new Set<string>()
+
+  props.suggestions[activeFormat.value]?.forEach((suggestion) => {
+    try {
+      const color = normalizeInputColor(suggestion)
+      values.add(fmt(color, activeFormat.value))
+    } catch {
+      // Consumers can derive suggestions from stored classes; ignore malformed or unsupported values safely.
+    }
+  })
+
+  return [...values]
+})
+
+const selectSuggestion = (suggestion: string) => {
+  colorObj.value = normalizeInputColor(suggestion)
+  model.value = fmt(colorObj.value, activeFormat.value)
+}
+
 const cycleFormat = (direction: 1 | -1) => {
   activeFormatIndex.value =
     (activeFormatIndex.value + direction + props.formats.length) % props.formats.length
@@ -67,14 +124,15 @@ const cycleFormat = (direction: 1 | -1) => {
 }
 
 const handleColorUpdate = (newColor: Color) => {
-  colorObj.value = newColor
-  model.value = fmt(newColor, activeFormat.value)
+  const updated = props.showAlpha ? newColor : withoutAlpha(newColor)
+  colorObj.value = updated
+  model.value = fmt(updated, activeFormat.value)
 }
 
 const handleHexInput = (event: Event) => {
   const val = (event.target as HTMLInputElement).value
   try {
-    colorObj.value = normalizeColor(val)
+    colorObj.value = normalizeInputColor(val)
     model.value = fmt(colorObj.value, activeFormat.value)
     hexInputError.value = ''
   } catch (e) {
@@ -103,12 +161,23 @@ watch(
   (val) => {
     if (!val) return
     try {
-      colorObj.value = normalizeColor(val)
+      colorObj.value = normalizeModelColor(val)
     } catch {
       // Ignore invalid color strings
     }
   },
 )
+
+watch(
+  () => props.showAlpha,
+  (showAlpha) => {
+    if (!showAlpha && colorObj.value.alpha < 1) {
+      const updated = withoutAlpha(colorObj.value)
+      colorObj.value = updated
+      model.value = fmt(updated, activeFormat.value)
+    }
+  },
+)
 </script>
 
 <template>
@@ -386,6 +455,26 @@ watch(
               </ColorFieldRoot>
             </div>
           </div>
+          <slot name="presets" />
+          <div v-if="colorSuggestions.length" class="flex flex-col gap-1">
+            <span class="extra-small-normal text-gray-500">{{ suggestionsLabel }}</span>
+            <div class="flex flex-wrap gap-1.5">
+              <button
+                v-for="suggestion in colorSuggestions"
+                :key="suggestion"
+                type="button"
+                class="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-label="`Kies kleur ${suggestion}`"
+                @click="selectSuggestion(suggestion)"
+              >
+                <ColorSwatch
+                  :color="suggestion"
+                  class="size-6 rounded-sm shadow-[inset_0_0_0_1px_rgba(0,0,0,0.1)]"
+                  :style="{ backgroundColor: 'var(--reka-color-swatch-color)' }"
+                />
+              </button>
+            </div>
+          </div>
         </div>
       </template>
     </NexxtFloatingPanel>

package/src/index.ts

@@ -49,8 +49,12 @@ export type {
   EditorGapValue,
 } from './components/editor/molecules/EditorGap/EditorGap.vue'
 export type {
+  EditorColorLiteralValue,
   EditorColorMessages,
   EditorColorProperty,
+  EditorColorRole,
+  EditorColorRoleValue,
+  EditorColorThemeRole,
   EditorColorValue,
 } from './components/editor/molecules/EditorColor/EditorColor.vue'
 export type {