@nexxtmove/ui 1.52.0 → 1.54.0

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

@@ -0,0 +1,515 @@
+<script lang="ts">
+/** The three places on one axis, in reading order: left/top, middle, right/bottom. */
+export const EDITOR_ALIGNMENT_POSITIONS = ['start', 'center', 'end'] as const
+
+/** A visual place on one axis: `start` is left or top, `end` is right or bottom. */
+export type EditorAlignmentPosition = (typeof EDITOR_ALIGNMENT_POSITIONS)[number]
+
+/**
+ * Where the content sits, as a visual place: `x` horizontal, `y` vertical,
+ * whatever the direction. `null` for an axis that does not count in a band
+ * mode; the grid writes `null` there, and reads only the axis that counts.
+ */
+export interface EditorAlignmentValue {
+  x: EditorAlignmentPosition | null
+  y: EditorAlignmentPosition | null
+}
+
+/** The direction the content stacks in. Decides the glyph and which way bands run. */
+export type EditorAlignmentDirection = 'row' | 'column'
+
+/**
+ * What can be chosen: `'both'` axes (nine cells), only the `'cross'` axis
+ * (three bands along the main axis), or only the `'main'` axis (three bands
+ * along the cross axis).
+ */
+export type EditorAlignmentMode = 'both' | 'cross' | 'main'
+
+/** Overridable copy. Every key is optional. */
+export interface EditorAlignmentGridMessages {
+  /** Name of the top left cell. Defaults to `'Linksboven'`. */
+  topLeft?: string
+  /** Name of the top middle cell. Defaults to `'Midden boven'`. */
+  topCenter?: string
+  /** Name of the top right cell. Defaults to `'Rechtsboven'`. */
+  topRight?: string
+  /** Name of the middle left cell. Defaults to `'Links midden'`. */
+  centerLeft?: string
+  /** Name of the middle cell. Defaults to `'Midden'`. */
+  center?: string
+  /** Name of the middle right cell. Defaults to `'Rechts midden'`. */
+  centerRight?: string
+  /** Name of the bottom left cell. Defaults to `'Linksonder'`. */
+  bottomLeft?: string
+  /** Name of the bottom middle cell. Defaults to `'Midden onder'`. */
+  bottomCenter?: string
+  /** Name of the bottom right cell. Defaults to `'Rechtsonder'`. */
+  bottomRight?: string
+  /** Name of the top band. Defaults to `'Boven'`. */
+  top?: string
+  /** Name of the middle band, horizontal or vertical. Defaults to `'Midden'`. */
+  middle?: string
+  /** Name of the bottom band. Defaults to `'Onder'`. */
+  bottom?: string
+  /** Name of the left band. Defaults to `'Links'`. */
+  left?: string
+  /** Name of the right band. Defaults to `'Rechts'`. */
+  right?: string
+  /** The main axis as a place while `auto` is on, in the stretched readout. Defaults to `'Auto'`. */
+  auto?: string
+  /** Readout while `auto` is on; `{position}` is the band. Defaults to `'Auto · {position}'`. */
+  autoValue?: string
+  /** Readout while `stretched` is on; `{position}` is the main-axis place. Defaults to `'Uitgerekt · {position}'`. */
+  stretchedValue?: string
+}
+
+export interface NexxtEditorAlignmentGridProps {
+  /**
+   * Header text of the settings block, and the name of the radiogroup.
+   * Defaults to the Dutch `'Uitlijning'`; the library has no i18n layer, so a
+   * consumer in another language passes its own copy in.
+   */
+  label?: string
+  /** The direction the content stacks in. Defaults to `'row'`. */
+  direction?: EditorAlignmentDirection
+  /** What can be chosen. Defaults to `'both'`, the nine cells. */
+  mode?: EditorAlignmentMode
+  /**
+   * The main axis distributes the space (Auto): in `'cross'` mode the bands
+   * draw their bars spread out, and the readout says `autoValue`.
+   */
+  auto?: boolean
+  /**
+   * The content is stretched over the cross axis (a legacy setting): no radio
+   * is checked, and a band with long bars marks the main-axis place. Every
+   * radio stays clickable; a choice is the way out.
+   */
+  stretched?: boolean
+  /**
+   * Copy of the cells, bands and readout. Defaults are Dutch and are merged
+   * per key. Copy is never translated inside the component.
+   */
+  messages?: EditorAlignmentGridMessages
+}
+
+const DEFAULT_MESSAGES = {
+  topLeft: 'Linksboven',
+  topCenter: 'Midden boven',
+  topRight: 'Rechtsboven',
+  centerLeft: 'Links midden',
+  center: 'Midden',
+  centerRight: 'Rechts midden',
+  bottomLeft: 'Linksonder',
+  bottomCenter: 'Midden onder',
+  bottomRight: 'Rechtsonder',
+  top: 'Boven',
+  middle: 'Midden',
+  bottom: 'Onder',
+  left: 'Links',
+  right: 'Rechts',
+  auto: 'Auto',
+  autoValue: 'Auto · {position}',
+  stretchedValue: 'Uitgerekt · {position}',
+} satisfies Required<EditorAlignmentGridMessages>
+
+type Axis = 'x' | 'y'
+type Copy = Required<EditorAlignmentGridMessages>
+
+/** Cell names by row (`y`) and then column (`x`). */
+const CELL_KEYS: Record<EditorAlignmentPosition, Record<EditorAlignmentPosition, keyof Copy>> = {
+  start: { start: 'topLeft', center: 'topCenter', end: 'topRight' },
+  center: { start: 'centerLeft', center: 'center', end: 'centerRight' },
+  end: { start: 'bottomLeft', center: 'bottomCenter', end: 'bottomRight' },
+}
+
+/**
+ * Band names by the axis the band stands for. "Midden" is the same word for
+ * both orientations, so there are five keys, not six (spec §7).
+ */
+const BAND_KEYS: Record<Axis, Record<EditorAlignmentPosition, keyof Copy>> = {
+  x: { start: 'left', center: 'middle', end: 'right' },
+  y: { start: 'top', center: 'middle', end: 'bottom' },
+}
+
+const SIZE = 3
+
+/** Bar sizes of the glyph: lengths along the cross axis. */
+const BARS = [
+  { tall: 'h-3', wide: 'w-3' },
+  { tall: 'h-4', wide: 'w-4' },
+  { tall: 'h-2', wide: 'w-2' },
+] as const
+
+const ITEMS: Record<EditorAlignmentPosition, string> = {
+  start: 'items-start',
+  center: 'items-center',
+  end: 'items-end',
+}
+
+/** Grid placement of a band over the cross axis, by its line. Literals, so Tailwind emits them. */
+const COLUMN_START = ['col-start-1', 'col-start-2', 'col-start-3'] as const
+const ROW_START = ['row-start-1', 'row-start-2', 'row-start-3'] as const
+</script>
+
+<script lang="ts" setup>
+import { computed, nextTick, useTemplateRef, watch } from 'vue'
+import NexxtEditorSettingsBlock from '../../atoms/EditorSettingsBlock/EditorSettingsBlock.vue'
+import { useRadioGrid } from '../../composables/useRadioGrid'
+
+defineOptions({ name: 'NexxtEditorAlignmentGrid', inheritAttrs: false })
+
+const {
+  label = 'Uitlijning',
+  direction = 'row',
+  mode = 'both',
+  auto = false,
+  stretched = false,
+  messages,
+} = defineProps<NexxtEditorAlignmentGridProps>()
+
+const emit = defineEmits<{
+  /**
+   * One edit is finished: after a click, and when the focus leaves the grid
+   * after a run of arrow keys. A consumer that folds model writes into one undo
+   * step closes it here.
+   */
+  commit: []
+}>()
+
+/** The chosen place. Every choice writes it: a click, an arrow, Space. */
+const model = defineModel<EditorAlignmentValue>({ required: true })
+
+const copy = computed<Copy>(() => ({ ...DEFAULT_MESSAGES, ...messages }))
+
+const at = (position: EditorAlignmentPosition | null) =>
+  position === null ? null : EDITOR_ALIGNMENT_POSITIONS.indexOf(position)
+
+const mainAxis = computed<Axis>(() => (direction === 'row' ? 'x' : 'y'))
+const crossAxis = computed<Axis>(() => (direction === 'row' ? 'y' : 'x'))
+
+/** The axis the bands stand for; `null` with nine cells. */
+const bandAxis = computed<Axis | null>(() =>
+  mode === 'both' ? null : mode === 'cross' ? crossAxis.value : mainAxis.value,
+)
+
+/**
+ * The cell a band is registered on: the first of its row for a horizontal band
+ * (one per vertical place), the first of its column for a vertical one.
+ */
+const bandCell = (axis: Axis, index: number) => (axis === 'y' ? index * SIZE : index)
+
+const positions = computed(() => {
+  const axis = bandAxis.value
+  if (!axis) return Array.from({ length: SIZE * SIZE }, (_, index) => index)
+  return [0, 1, 2].map((index) => bandCell(axis, index))
+})
+
+const selected = computed(() => {
+  if (stretched) return null
+  const axis = bandAxis.value
+  if (axis) {
+    const index = at(model.value[axis])
+    return index === null ? null : bandCell(axis, index)
+  }
+  const x = at(model.value.x)
+  const y = at(model.value.y)
+  return x === null || y === null ? null : y * SIZE + x
+})
+
+/** The main-axis place, which a stretched grid marks; the start without one. */
+const mainIndex = computed(() => at(model.value[mainAxis.value]) ?? 0)
+
+/** Without a chosen radio (stretched): the main-axis place × the middle. */
+const preferred = () => {
+  const cell = mainAxis.value === 'x' ? SIZE + mainIndex.value : mainIndex.value * SIZE + 1
+  const axis = bandAxis.value
+  if (!axis) return cell
+  return axis === 'y' ? Math.floor(cell / SIZE) * SIZE : cell % SIZE
+}
+
+const valueAt = (position: number): EditorAlignmentValue => {
+  const x = EDITOR_ALIGNMENT_POSITIONS[position % SIZE]
+  const y = EDITOR_ALIGNMENT_POSITIONS[Math.floor(position / SIZE)]
+  const axis = bandAxis.value
+  if (axis === 'x') return { x, y: null }
+  if (axis === 'y') return { x: null, y }
+  return { x, y }
+}
+
+/** Writes the place; `false` when it was already chosen. */
+const choose = (position: number) => {
+  if (position === selected.value) return false
+  model.value = valueAt(position)
+  return true
+}
+
+const { tabStop, cellRef, onKeydown, onFocusout, reset, focusTabStop } = useRadioGrid({
+  rows: SIZE,
+  columns: SIZE,
+  positions,
+  selected,
+  preferred,
+  homeEnd: 'row',
+  onChoose: choose,
+  onLeave: () => emit('commit'),
+})
+
+/**
+ * A click, or Space and Enter through the button's own click. Its commit also
+ * closes a keyboard run before it, so leaving the grid afterwards adds none.
+ */
+const onClick = (position: number) => {
+  if (!choose(position)) return
+  emit('commit')
+  reset()
+}
+
+const format = (template: string, position: string) => template.replace('{position}', position)
+
+const bandName = (axis: Axis, position: EditorAlignmentPosition) =>
+  copy.value[BAND_KEYS[axis][position]]
+
+/** The readout next to the grid: only what has an effect (spec §4.2). */
+const readout = computed(() => {
+  const { x, y } = model.value
+  if (stretched) {
+    const main = model.value[mainAxis.value] ?? 'start'
+    return format(
+      copy.value.stretchedValue,
+      auto ? copy.value.auto : bandName(mainAxis.value, main),
+    )
+  }
+  const axis = bandAxis.value
+  if (axis) {
+    const position = model.value[axis]
+    if (!position) return ''
+    const name = bandName(axis, position)
+    return auto && mode === 'cross' ? format(copy.value.autoValue, name) : name
+  }
+  return x && y ? copy.value[CELL_KEYS[y][x]] : ''
+})
+
+/** Spread bars: Auto in cross mode, where the main axis distributes. */
+const spread = computed(() => auto && mode === 'cross')
+
+/** Bars stand in a row and lie in a column. */
+const standing = computed(() => direction === 'row')
+
+const radios = computed(() =>
+  positions.value.map((position) => {
+    const x = EDITOR_ALIGNMENT_POSITIONS[position % SIZE]
+    const y = EDITOR_ALIGNMENT_POSITIONS[Math.floor(position / SIZE)]
+    const axis = bandAxis.value
+    const checked = position === selected.value
+    // The cross-axis place the bars line up on: the cell's own in nine cells
+    // and in cross mode; the middle in main mode, where the cross axis has no
+    // effect.
+    const align: EditorAlignmentPosition = mode === 'main' ? 'center' : standing.value ? y : x
+    const horizontalBand = axis === 'y'
+    const inStretchedBand =
+      stretched &&
+      (mode === 'cross' ||
+        (mainAxis.value === 'x' ? at(x) === mainIndex.value : at(y) === mainIndex.value))
+    return {
+      position,
+      checked,
+      label: axis ? bandName(axis, axis === 'x' ? x : y) : copy.value[CELL_KEYS[y][x]],
+      tabindex: position === tabStop.value ? 0 : -1,
+      span: axis ? (horizontalBand ? 'col-span-3' : 'row-span-3') : '',
+      // A band's long side, where spread bars and dots run.
+      track: !axis
+        ? ''
+        : horizontalBand
+          ? 'w-full px-2 justify-between'
+          : 'h-full flex-col py-2 justify-between',
+      align: ITEMS[align],
+      showDots: !inStretchedBand,
+      dots: axis && spread.value ? 3 : 1,
+    }
+  }),
+)
+
+/** The stretched bands: all three in cross mode, else one over the cross axis at the main place. */
+const stretchedBands = computed(() => {
+  if (!stretched) return []
+  if (mode === 'cross') {
+    return [0, 1, 2].map((index) =>
+      standing.value
+        ? {
+            key: index,
+            place: `col-span-3 ${ROW_START[index]}`,
+            bars: 'w-full px-2 justify-between',
+          }
+        : {
+            key: index,
+            place: `row-span-3 ${COLUMN_START[index]}`,
+            bars: 'h-full flex-col py-2 justify-between',
+          },
+    )
+  }
+  return [
+    standing.value
+      ? {
+          key: 0,
+          place: `row-span-3 row-start-1 ${COLUMN_START[mainIndex.value]}`,
+          bars: 'h-full py-2 justify-center',
+        }
+      : {
+          key: 0,
+          place: `col-span-3 col-start-1 ${ROW_START[mainIndex.value]}`,
+          bars: 'w-full flex-col px-2 justify-center',
+        },
+  ]
+})
+
+/** Changes of mode or direction crossfade the cell layer. */
+const layerKey = computed(() => `${mode}-${direction}`)
+
+const group = useTemplateRef<HTMLElement>('group')
+
+/**
+ * A switch while the focus is in the grid moves it to the tab stop of the new
+ * layer, once that is mounted, rather than letting it drop to `body` with the
+ * old one. The focus stays inside, so it is no end of a keyboard run and
+ * commits nothing; leaving the grid does, later.
+ */
+watch(
+  layerKey,
+  () => {
+    if (!group.value?.contains(document.activeElement)) return
+    nextTick(focusTabStop)
+  },
+  { flush: 'pre' },
+)
+
+// The leaving layer is still in the DOM for 150 ms; inert keeps its radios out
+// of the tab order and the accessibility tree meanwhile. Set a tick later, so
+// the watcher above has moved the focus out first: making the focused button
+// inert would blur it to `body`.
+const onBeforeLeave = (el: Element) => {
+  nextTick(() => {
+    ;(el as HTMLElement).inert = true
+  })
+}
+</script>
+
+<template>
+  <NexxtEditorSettingsBlock :label="label">
+    <div class="flex items-center gap-4">
+      <div class="size-28 shrink-0 rounded-xl bg-gray-100 p-1">
+        <div
+          ref="group"
+          role="radiogroup"
+          :aria-label="label"
+          v-bind="$attrs"
+          class="relative size-full"
+          @focusout="onFocusout"
+        >
+          <Transition
+            enter-active-class="transition-opacity duration-150 ease-out motion-reduce:transition-none"
+            enter-from-class="opacity-0"
+            leave-active-class="absolute inset-0 transition-opacity duration-150 ease-in motion-reduce:transition-none"
+            leave-to-class="opacity-0"
+            @before-leave="onBeforeLeave"
+          >
+            <div :key="layerKey" class="size-full">
+              <!-- The stretched marker: drawing only, under the radios, which stay clickable. -->
+              <div
+                v-if="stretchedBands.length"
+                aria-hidden="true"
+                class="pointer-events-none absolute inset-0 grid grid-cols-3 grid-rows-3 gap-1"
+              >
+                <div
+                  v-for="band in stretchedBands"
+                  :key="band.key"
+                  :class="['flex rounded-lg bg-white text-cornflower-blue-600', band.place]"
+                >
+                  <div :class="['flex size-full items-stretch gap-0.5', band.bars]">
+                    <span
+                      v-for="(_, index) in BARS"
+                      :key="index"
+                      :class="['rounded-full bg-current', standing ? 'w-1' : 'h-1']"
+                    />
+                  </div>
+                </div>
+              </div>
+
+              <!--
+                No `focus:outline-none`: in Tailwind v4 it hides the focus-visible
+                ring. The ring is -600, not -500: -500 reaches 2.78:1 on white.
+              -->
+              <div
+                :class="[
+                  'relative grid size-full grid-cols-3 grid-rows-3 gap-1',
+                  bandAxis === 'x' && 'grid-flow-col',
+                ]"
+              >
+                <button
+                  v-for="radio in radios"
+                  :key="radio.position"
+                  :ref="cellRef(radio.position)"
+                  type="button"
+                  role="radio"
+                  :aria-checked="radio.checked"
+                  :aria-label="radio.label"
+                  :tabindex="radio.tabindex"
+                  :class="[
+                    'group relative flex items-center justify-center rounded-lg outline-cornflower-blue-600 transition-colors duration-150 ease-out focus-visible:outline-2 focus-visible:outline-offset-0 motion-reduce:transition-none',
+                    radio.span,
+                    radio.checked ? 'bg-white' : 'cursor-pointer',
+                  ]"
+                  @click="onClick(radio.position)"
+                  @keydown="onKeydown($event, radio.position)"
+                >
+                  <span
+                    v-if="radio.showDots && !radio.checked"
+                    aria-hidden="true"
+                    :class="[
+                      'flex items-center transition-opacity duration-150 ease-out group-hover:opacity-0 motion-reduce:transition-none',
+                      radio.dots > 1 ? radio.track : '',
+                    ]"
+                  >
+                    <span
+                      v-for="dot in radio.dots"
+                      :key="dot"
+                      class="size-1 shrink-0 rounded-full bg-gray-700"
+                    />
+                  </span>
+                  <span
+                    aria-hidden="true"
+                    :class="[
+                      'absolute inset-0 flex items-center justify-center transition-[opacity,color] duration-150 ease-out motion-reduce:transition-none',
+                      radio.checked
+                        ? 'text-cornflower-blue-600'
+                        : 'text-gray-700 opacity-0 group-hover:opacity-100',
+                    ]"
+                  >
+                    <span
+                      :class="[
+                        'flex gap-0.5',
+                        standing ? 'h-4' : 'w-4 flex-col',
+                        radio.align,
+                        spread && radio.track,
+                      ]"
+                    >
+                      <span
+                        v-for="(bar, index) in BARS"
+                        :key="index"
+                        :class="[
+                          'shrink-0 rounded-full bg-current',
+                          standing ? ['w-1', bar.tall] : ['h-1', bar.wide],
+                        ]"
+                      />
+                    </span>
+                  </span>
+                </button>
+              </div>
+            </div>
+          </Transition>
+        </div>
+      </div>
+
+      <span aria-hidden="true" class="min-w-0 small-normal text-gray-700">{{ readout }}</span>
+    </div>
+  </NexxtEditorSettingsBlock>
+</template>

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

@@ -99,7 +99,8 @@ const MIDDLE = 4
 </script>
 
 <script lang="ts" setup>
-import { computed, useId, useTemplateRef } from 'vue'
+import { computed, useId } from 'vue'
+import { useRadioGrid } from '../../composables/useRadioGrid'
 
 defineOptions({ name: 'NexxtEditorAnchor', inheritAttrs: false })
 
@@ -118,8 +119,6 @@ const model = defineModel<EditorAnchorValue | null>({ required: true })
 
 const labelId = useId()
 
-const cellEls = useTemplateRef<HTMLButtonElement[]>('cellButtons')
-
 const copy = computed(() => ({ ...DEFAULT_MESSAGES, ...messages }))
 
 const selectedIndex = computed(() => {
@@ -129,8 +128,28 @@ const selectedIndex = computed(() => {
   return index === -1 ? null : index
 })
 
-/** Roving tabindex: one tab stop, on the chosen cell or else on the middle. */
-const tabStop = computed(() => selectedIndex.value ?? MIDDLE)
+const choose = (index: number) => {
+  const cell = EDITOR_ANCHOR_OPTIONS[index]
+
+  if (disabled || !cell || index === selectedIndex.value) return
+
+  model.value = { x: cell.x, y: cell.y }
+}
+
+/**
+ * The radio pattern in two dimensions: an arrow moves and chooses at once and
+ * stops at the edge; Home and End jump to the first and the last cell. One tab
+ * stop, on the chosen cell or else on the middle. Modifier keys are left to the
+ * browser.
+ */
+const { tabStop, cellRef, onKeydown } = useRadioGrid({
+  rows: ROWS,
+  columns: COLUMNS,
+  selected: selectedIndex,
+  preferred: () => MIDDLE,
+  homeEnd: 'grid',
+  onChoose: choose,
+})
 
 const cells = computed(() =>
   EDITOR_ANCHOR_OPTIONS.map(({ x, y }, index) => {
@@ -155,41 +174,6 @@ const cells = computed(() =>
 const groupName = computed(() =>
   showLabel ? { 'aria-labelledby': labelId } : { 'aria-label': label },
 )
-
-const choose = (index: number) => {
-  const cell = EDITOR_ANCHOR_OPTIONS[index]
-
-  if (disabled || !cell || index === selectedIndex.value) return
-
-  model.value = { x: cell.x, y: cell.y }
-}
-
-/**
- * The radio pattern in two dimensions: an arrow moves and chooses at once and
- * stops at the edge; Home and End jump to the first and the last cell. A key
- * with a modifier belongs to the browser or the OS (Alt+Left is back, Cmd+Left
- * is line start), so it is left alone: no choice, no preventDefault.
- */
-const onKeydown = (event: KeyboardEvent, index: number) => {
-  if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return
-
-  const row = Math.floor(index / COLUMNS)
-  const column = index % COLUMNS
-  const next = {
-    ArrowLeft: column > 0 ? index - 1 : index,
-    ArrowRight: column < COLUMNS - 1 ? index + 1 : index,
-    ArrowUp: row > 0 ? index - COLUMNS : index,
-    ArrowDown: row < ROWS - 1 ? index + COLUMNS : index,
-    Home: 0,
-    End: EDITOR_ANCHOR_OPTIONS.length - 1,
-  }[event.key]
-
-  if (next === undefined) return
-
-  event.preventDefault()
-  choose(next)
-  cellEls.value?.[next]?.focus()
-}
 </script>
 
 <template>
@@ -216,7 +200,7 @@ const onKeydown = (event: KeyboardEvent, index: number) => {
     <button
       v-for="cell in cells"
       :key="cell.index"
-      ref="cellButtons"
+      :ref="cellRef(cell.index)"
       type="button"
       role="radio"
       :aria-checked="cell.checked"