@nexxtmove/ui 2.2.0 → 2.3.0

package/package.json

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

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

@@ -1,4 +1,24 @@
 <script lang="ts">
+import type { EditorColorRole, EditorColorThemeRole } from './colorClass'
+import type { EditorColorGradientValue } from './gradientClass'
+import type {
+  ColorPickerFillMode,
+  ColorPickerGradientMessages,
+} from '../../../organisms/ColorPicker/ColorPicker.vue'
+
+export type { EditorColorRole, EditorColorThemeRole } from './colorClass'
+export type {
+  EditorColorGradientValue,
+  EditorColorLinearGradientValue,
+  EditorColorRadialGradientValue,
+} from './gradientClass'
+
+/** A fill the editor can offer: `'solid'` or `'gradient'`; see NexxtColorPicker. */
+export type EditorColorFillMode = ColorPickerFillMode
+
+/** Copy of the gradient mode; see NexxtColorPicker. */
+export type EditorColorGradientMessages = ColorPickerGradientMessages
+
 /**
  * The CSS property the chosen colour is written to. It is the prefix of the
  * Tailwind class the model carries, so it decides whether the colour becomes a
@@ -7,14 +27,6 @@
  */
 export type EditorColorProperty = 'bg' | 'text'
 
-const 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 ROLES)[number]
-
 /** A literal colour: a Tailwind arbitrary-value class such as `'bg-[#1777EA]'`. */
 export type EditorColorLiteralValue = `${EditorColorProperty}-[#${string}]`
 
@@ -24,22 +36,11 @@ export type EditorColorRoleValue = `${EditorColorProperty}-theme-${EditorColorRo
 /**
  * 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.
+ * colour or a theme role, or with `modes` including `'gradient'` a gradient: a string of classes
+ * such as `'bg-linear-135 from-[#7f56d9] to-[#432e73]'`.
  */
-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
-}
+export type EditorColorValue =
+  EditorColorLiteralValue | EditorColorRoleValue | EditorColorGradientValue
 
 export interface EditorColorMessages {
   /** Text shown while no colour is set. Defaults to `'Kies kleur...'`. */
@@ -98,6 +99,38 @@ export interface NexxtEditorColorProps {
    * alpha and the model gets the opaque 6-digit hex.
    */
   showAlpha?: boolean
+  /**
+   * The fills the picker offers. `['solid']` (the default) is the plain colour
+   * picker, unchanged. `['solid', 'gradient']`, in any order, adds an
+   * "Effen | Verloop" switch; `['gradient']` offers only the gradient, without a
+   * switch -- an empty value or a solid colour then opens on the gradient a
+   * switch would give, written only on the first change. A gradient only exists
+   * for `property` `'bg'`: with `'text'` this falls back to `['solid']`, also
+   * for `['gradient']`. A gradient is written as
+   * one string of classes in a fixed order -- type, from, from-position, via,
+   * via-position, to, to-position -- such as
+   * `'bg-linear-135 from-[#7f56d9] via-theme-main via-40% to-[#432e73cc]'` or
+   * `'bg-radial-[at_30%_70%] from-theme-accent to-[#ffffff00]'`. Hexes are in
+   * lower case without an opaque `ff`, and a position is only written when it
+   * differs from 0 %, 50 % or 100 %. In the gradient mode the opacity slider is
+   * always offered, whatever `showAlpha` says. To draw a stored gradient as an
+   * inline style, parse it with `parseGradientClass` and turn it into CSS with
+   * `gradientClassToCss`, which always interpolates in oklab, as the preview does.
+   * A radial gradient off centre renders in sRGB as a Tailwind class; draw it
+   * with `gradientClassToCss` for the oklab result the picker shows.
+   */
+  modes?: EditorColorFillMode[]
+  /**
+   * Copy of the gradient mode. Merged per key over the Dutch defaults, so
+   * overriding one key keeps the others.
+   */
+  gradientMessages?: EditorColorGradientMessages
+  /**
+   * Id(s) of an element that describes the setting, such as a hint the
+   * consumer renders itself. Set as `aria-describedby` on the picker's trigger,
+   * and on the switch when `switchable`. Without it no attribute is set.
+   */
+  describedby?: string
 }
 
 const DEFAULT_MESSAGES = {
@@ -108,36 +141,17 @@ const DEFAULT_MESSAGES = {
 } satisfies Required<EditorColorMessages>
 
 /**
- * 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 whether or not `showAlpha` is set, so a stored `#1777EA80` survives a
- * round trip either way.
- */
-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})?$/
-
-/**
- * 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.
+ * The prefixes read as a colour. A value with the other prefix is shown and
+ * rewritten to `property`; a `border-[…]` class, like any other class this
+ * component does not own, is read as unparseable.
  */
-const OPAQUE_ALPHA_PATTERN = /^(#[0-9A-Fa-f]{6})[fF]{2}$/
+const PROPERTIES = ['bg', 'text'] as const satisfies readonly EditorColorProperty[]
 </script>
 
 <script lang="ts" setup>
-import { computed, watch } from 'vue'
+import { computed } from 'vue'
 import NexxtEditorSettingsBlock from '../../atoms/EditorSettingsBlock/EditorSettingsBlock.vue'
-import NexxtTooltip from '../../../atoms/Tooltip/Tooltip.vue'
-import NexxtColorPicker from '../../../organisms/ColorPicker/ColorPicker.vue'
+import NexxtColorField from './_ColorField.vue'
 
 defineOptions({ name: 'NexxtEditorColor' })
 
@@ -149,6 +163,9 @@ const {
   suggestions = [],
   themeRoles = [],
   showAlpha = false,
+  modes = ['solid'],
+  gradientMessages,
+  describedby,
 } = defineProps<NexxtEditorColorProps>()
 
 /**
@@ -170,88 +187,15 @@ const model = defineModel<EditorColorValue>({ required: true })
 const enabled = defineModel<boolean>('enabled', { default: true })
 
 const copy = computed(() => ({ ...DEFAULT_MESSAGES, ...messages }))
-
-/**
- * The `#` is part of the model's type, so a plain `string` cannot be written
- * into it. This narrows the picker's output and the regex capture to the shape
- * the model promises, without a cast.
- */
-const isHex = (value: string): value is `#${string}` => value.startsWith('#')
-
-/** The hex out of the model, or an empty string when it is not a colour class. */
-const hex = computed(() => {
-  const captured = VALUE_PATTERN.exec(model.value)?.[2]
-  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.
- *
- * 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}`
-}
-
-// `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}]`
-  },
-)
 </script>
 
 <template>
-  <NexxtEditorSettingsBlock v-model="enabled" :label="label" :switchable="switchable">
+  <NexxtEditorSettingsBlock
+    v-model="enabled"
+    :label="label"
+    :switchable="switchable"
+    :describedby="describedby"
+  >
     <!--
       The block label is a <p> (or the switch's own label), so the picker gets
       no `label` of its own -- that would print the heading twice. Its trigger
@@ -264,52 +208,20 @@ watch(
       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.
     -->
-    <NexxtColorPicker
-      v-model="picked"
-      full-width
-      match-width
-      :formats="['hex']"
-      :show-alpha="alphaEnabled"
+    <NexxtColorField
+      v-model="model"
+      :property="property"
+      :accepts="PROPERTIES"
+      :show-alpha="showAlpha"
       :placeholder="copy.placeholder"
-      :suggestions="{ hex: suggestions }"
+      :suggestions="suggestions"
       :suggestions-label="copy.suggestionsLabel"
+      :theme-label="copy.themeLabel"
       :alpha-label="copy.alphaLabel"
-      :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>
+      :theme-roles="themeRoles"
+      :modes="modes"
+      :gradient-messages="gradientMessages"
+      :describedby="describedby"
+    />
   </NexxtEditorSettingsBlock>
 </template>