@dumiflex/wp-kit 0.0.0-stage → 0.4.0

package/src/EmptyState.vue

@@ -0,0 +1,111 @@
+<script setup lang="ts">
+import Icon from "./Icon.vue";
+
+interface Props {
+  icon: string;
+  headline: string;
+  body?: string | undefined;
+  /** "library" = encouraging first-run; "no-results" = corrective for
+   *  filter misses; "error" = network/permission failure with retry. */
+  variant?: "library" | "no-results" | "error" | undefined;
+  /** How much room it takes. `page` fills an empty list page, `panel` (the
+   *  default) sits in a card or panel at its own height, `inline` is one
+   *  compact row for a small box. */
+  size?: "page" | "panel" | "inline" | undefined;
+}
+const props = withDefaults(defineProps<Props>(), {
+  variant: "library",
+  size: "panel",
+});
+const ICON_PX = { page: 40, panel: 26, inline: 16 } as const;
+</script>
+
+<template>
+  <div class="wp-empty" :class="[`wp-empty--${variant}`, `wp-empty--${props.size}`]" data-test="empty-state">
+    <div class="wp-empty__icon">
+      <Icon :name="icon" :size="ICON_PX[props.size]" />
+    </div>
+    <h3 class="wp-empty__headline">{{ headline }}</h3>
+    <p v-if="body" class="wp-empty__body">{{ body }}</p>
+    <div v-if="$slots.cta" class="wp-empty__cta">
+      <slot name="cta" />
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.wp-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  padding: var(--wp-space-7) var(--wp-space-6);
+  gap: var(--wp-space-4);
+  box-sizing: border-box;
+}
+/* Page: an empty list page. The message reads as the page's content, not a
+ * line floating at the top of a tall area, but stops well short of the old
+ * 60vh that also hit cards and panels. `min-height` keeps the layout flat
+ * (no 100% chain through the table), so a full list is untouched. */
+.wp-empty--page {
+  min-height: max(40vh, 320px);
+  padding: var(--wp-space-8) var(--wp-space-6);
+  gap: var(--wp-space-5);
+}
+/* Inline: one compact row for a small box or a list section. */
+.wp-empty--inline {
+  flex-direction: row;
+  flex-wrap: wrap;
+  justify-content: flex-start;
+  text-align: left;
+  padding: var(--wp-space-4);
+  gap: var(--wp-space-3);
+}
+.wp-empty__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 52px;
+  height: 52px;
+  border-radius: var(--wp-radius-lg);
+  background: var(--wp-bg-2);
+  color: var(--wp-text-muted);
+}
+.wp-empty--page .wp-empty__icon { width: 80px; height: 80px; border-radius: var(--wp-radius-xl); }
+.wp-empty--inline .wp-empty__icon { width: 28px; height: 28px; border-radius: var(--wp-radius-sm); }
+.wp-empty--no-results .wp-empty__icon {
+  background: transparent;
+  border: 1px dashed var(--wp-border);
+}
+.wp-empty--error .wp-empty__icon {
+  background: color-mix(in oklab, var(--wp-danger) 12%, transparent);
+  color: var(--wp-danger);
+  border: 1px solid color-mix(in oklab, var(--wp-danger) 30%, transparent);
+}
+.wp-empty__headline {
+  margin: 0;
+  color: var(--wp-text);
+  font-size: var(--wp-text-md);
+  line-height: var(--wp-line-md, 1.4);
+  font-weight: var(--wp-weight-semibold);
+}
+.wp-empty--page .wp-empty__headline {
+  font-size: var(--wp-text-lg);
+  line-height: var(--wp-line-lg);
+}
+.wp-empty--inline .wp-empty__headline { font-size: var(--wp-text-base); }
+.wp-empty__body {
+  margin: 0;
+  font-size: var(--wp-text-sm);
+  line-height: var(--wp-line-sm);
+  color: var(--wp-text-muted);
+  max-width: 360px;
+}
+.wp-empty--inline .wp-empty__body { flex-basis: 100%; max-width: none; padding-left: calc(28px + var(--wp-space-3)); margin-top: calc(var(--wp-space-3) * -1); }
+.wp-empty__cta {
+  margin-top: var(--wp-space-2);
+}
+.wp-empty--inline .wp-empty__cta { margin: 0 0 0 auto; }
+</style>

package/src/Field.vue

@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import { computed } from "vue";
+
+interface Props {
+  label?: string | undefined;
+  hint?: string | undefined;
+  error?: string | undefined;
+  for?: string | undefined;
+  required?: boolean | undefined;
+}
+const props = defineProps<Props>();
+
+const classes = computed(() => [
+  "wp-field",
+  props.error && "wp-field--error",
+]);
+</script>
+
+<template>
+  <div :class="classes">
+    <label v-if="label" :for="props.for" class="wp-field__label">
+      {{ label }}<span v-if="required" aria-hidden="true"> *</span>
+    </label>
+    <slot :ariaInvalid="!!error" />
+    <div v-if="error" class="wp-field__error" role="alert">{{ error }}</div>
+    <div v-else-if="hint" class="wp-field__hint">{{ hint }}</div>
+  </div>
+</template>

package/src/HsvPicker.vue

@@ -0,0 +1,208 @@
+<script setup lang="ts">
+/**
+ * HsvPicker — saturation/value square + hue slider.
+ *
+ * Shared between manager ColorPicker / TweaksPanel AND the canvas
+ * bundle modal. CSS uses `--wp-*` tokens with hardcoded fallbacks so
+ * the picker renders inside the extension where the manager spacing
+ * tokens (`--wp-space-*`) aren't loaded.
+ *
+ * Pure CSS gradient render — no canvas. The SV square stacks three
+ * gradients to produce the HSV picker visual; the hue strip is a
+ * single multi-stop linear gradient across the spectrum.
+ *
+ * Drag is driven by document-level `pointermove` + `pointerup`
+ * listeners attached on pointerdown and detached on release. The
+ * earlier `setPointerCapture`-based approach locked up the hue
+ * slider when the SV picker reached an edge: in certain hosts
+ * (notably the canvas Teleport popover), capture wasn't always
+ * released cleanly, so subsequent pointerdown events on the hue
+ * slider got rerouted back to the SV element and the slider read
+ * as "stuck". Document-level handlers don't depend on element
+ * capture and always cleanly tear down on pointerup, even when the
+ * release happens outside the picker.
+ */
+import { computed, onBeforeUnmount, ref, watch } from "vue";
+import { hexToHsv, hsvToHex, type Hsv } from "./hsv";
+
+interface Props {
+  modelValue: string;
+  ariaLabel?: string | undefined;
+}
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (e: "update:modelValue", value: string): void;
+}>();
+
+const hsv = ref<Hsv>({ h: 0, s: 1, v: 1 });
+
+function syncFromProp(hex: string) {
+  const parsed = hexToHsv(hex);
+  if (!parsed) return;
+  // Preserve the local hue when incoming RGB is pure black/white —
+  // otherwise the user's hue selection snaps to 0 every time s or v
+  // hits 0, which is jarring during a vertical drag.
+  if (parsed.s === 0) parsed.h = hsv.value.h;
+  hsv.value = parsed;
+}
+
+watch(() => props.modelValue, syncFromProp, { immediate: true });
+
+function emitHex() {
+  emit("update:modelValue", hsvToHex(hsv.value));
+}
+
+const hueBg = computed(() => `hsl(${hsv.value.h}, 100%, 50%)`);
+
+const svEl = ref<HTMLDivElement | null>(null);
+const hueEl = ref<HTMLDivElement | null>(null);
+
+/** Document-level drag state. Only one drag can be active at a time
+ *  (one mouse / one finger), so a single `activeDrag` ref tracking
+ *  which surface owns the current pointer is sufficient. */
+let activeDrag: "sv" | "hue" | null = null;
+
+function handleSvMove(evt: PointerEvent) {
+  const el = svEl.value;
+  if (!el) return;
+  const rect = el.getBoundingClientRect();
+  const x = Math.max(0, Math.min(rect.width, evt.clientX - rect.left));
+  const y = Math.max(0, Math.min(rect.height, evt.clientY - rect.top));
+  hsv.value = { h: hsv.value.h, s: x / rect.width, v: 1 - (y / rect.height) };
+  emitHex();
+}
+
+function handleHueMove(evt: PointerEvent) {
+  const el = hueEl.value;
+  if (!el) return;
+  const rect = el.getBoundingClientRect();
+  const x = Math.max(0, Math.min(rect.width, evt.clientX - rect.left));
+  hsv.value = { h: (x / rect.width) * 360, s: hsv.value.s, v: hsv.value.v };
+  emitHex();
+}
+
+function onDocPointerMove(evt: PointerEvent) {
+  if (activeDrag === "sv") handleSvMove(evt);
+  else if (activeDrag === "hue") handleHueMove(evt);
+}
+
+function onDocPointerUp() {
+  activeDrag = null;
+  document.removeEventListener("pointermove", onDocPointerMove);
+  document.removeEventListener("pointerup", onDocPointerUp);
+  document.removeEventListener("pointercancel", onDocPointerUp);
+}
+
+function startDrag(kind: "sv" | "hue", evt: PointerEvent) {
+  activeDrag = kind;
+  if (kind === "sv") handleSvMove(evt);
+  else handleHueMove(evt);
+  document.addEventListener("pointermove", onDocPointerMove);
+  document.addEventListener("pointerup", onDocPointerUp);
+  document.addEventListener("pointercancel", onDocPointerUp);
+}
+
+function onSvPointerDown(evt: PointerEvent) {
+  evt.preventDefault();
+  startDrag("sv", evt);
+}
+function onHuePointerDown(evt: PointerEvent) {
+  evt.preventDefault();
+  startDrag("hue", evt);
+}
+
+onBeforeUnmount(onDocPointerUp);
+
+const svCursorStyle = computed(() => ({
+  left: `${hsv.value.s * 100}%`,
+  top: `${(1 - hsv.value.v) * 100}%`,
+}));
+const hueCursorStyle = computed(() => ({
+  left: `${(hsv.value.h / 360) * 100}%`,
+}));
+</script>
+
+<template>
+  <div class="wp-hsv-picker" :aria-label="ariaLabel">
+    <div
+      ref="svEl"
+      class="wp-hsv-picker__sv"
+      :style="{ '--wp-hsv-hue': hueBg }"
+      :aria-label="`Saturation and brightness, current ${Math.round(hsv.s * 100)}% / ${Math.round(hsv.v * 100)}%`"
+      data-test="hsv-sv"
+      @pointerdown="onSvPointerDown"
+    >
+      <div class="wp-hsv-picker__sv-cursor" :style="svCursorStyle" />
+    </div>
+    <div
+      ref="hueEl"
+      class="wp-hsv-picker__hue"
+      :aria-label="`Hue, current ${Math.round(hsv.h)}°`"
+      data-test="hsv-hue"
+      @pointerdown="onHuePointerDown"
+    >
+      <div class="wp-hsv-picker__hue-cursor" :style="hueCursorStyle" />
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.wp-hsv-picker { display: flex; flex-direction: column; gap: var(--wp-space-4, 8px); width: 100%; }
+.wp-hsv-picker__sv {
+  position: relative;
+  width: 100%;
+  height: 120px;
+  border-radius: var(--wp-radius-sm, 4px);
+  border: 1px solid var(--wp-border, #3a3a3a);
+  cursor: crosshair;
+  touch-action: none;
+  user-select: none;
+  background:
+    linear-gradient(to top, #000, transparent),
+    linear-gradient(to right, #fff, transparent),
+    var(--wp-hsv-hue, hsl(0, 100%, 50%));
+}
+.wp-hsv-picker__sv-cursor {
+  position: absolute;
+  width: 14px;
+  height: 14px;
+  border-radius: 50%; /* round: picker cursor on the colour field */
+  border: 2px solid #fff;
+  box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.6), 0 1px 2px rgba(0, 0, 0, 0.45);
+  transform: translate(-50%, -50%);
+  pointer-events: none;
+}
+.wp-hsv-picker__hue {
+  position: relative;
+  width: 100%;
+  height: 12px;
+  border-radius: var(--wp-radius-sm, 4px);
+  border: 1px solid var(--wp-border, #3a3a3a);
+  cursor: ew-resize;
+  touch-action: none;
+  user-select: none;
+  background: linear-gradient(
+    to right,
+    hsl(0, 100%, 50%),
+    hsl(60, 100%, 50%),
+    hsl(120, 100%, 50%),
+    hsl(180, 100%, 50%),
+    hsl(240, 100%, 50%),
+    hsl(300, 100%, 50%),
+    hsl(360, 100%, 50%)
+  );
+}
+.wp-hsv-picker__hue-cursor {
+  position: absolute;
+  top: 50%;
+  width: 12px;
+  height: 16px;
+  border-radius: var(--wp-radius-sm, 4px);
+  border: 2px solid #fff;
+  box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.6), 0 1px 2px rgba(0, 0, 0, 0.45);
+  transform: translate(-50%, -50%);
+  pointer-events: none;
+  background: transparent;
+}
+</style>

package/src/Icon.vue

@@ -0,0 +1,39 @@
+<script lang="ts">
+/**
+ * Canonical icon sizes. Use these instead of raw numbers on `:size`.
+ *
+ *  ICON_SM (12) — micro indicators, badge glyphs, tight pill icons
+ *  ICON_MD (14) — default toolbar / sidebar / inline icons
+ *  ICON_LG (18) — emphasized icons (CTA buttons, empty-state subheadings,
+ *                 panel-header glyphs)
+ *
+ * Outliers (e.g. very large empty-state icons at 48-80px) stay as raw
+ * numbers — flag the locations in PR review so we can decide whether
+ * to grow the scale.
+ */
+export const ICON_SM = 12;
+export const ICON_MD = 14;
+export const ICON_LG = 18;
+</script>
+
+<script setup lang="ts">
+import { computed } from "vue";
+
+interface Props {
+  name: string;
+  size?: number | undefined;
+}
+const props = defineProps<Props>();
+
+const className = computed(() => {
+  // Accept either bare name ("plus", "check-circle") or already-prefixed ("pi-plus").
+  const n = props.name.startsWith("pi-") ? props.name : `pi-${props.name}`;
+  return `pi ${n}`;
+});
+
+const style = computed(() => (props.size ? { fontSize: `${props.size}px` } : undefined));
+</script>
+
+<template>
+  <i :class="className" :style="style" aria-hidden="true" />
+</template>

package/src/IconPicker.vue

@@ -0,0 +1,209 @@
+<script setup lang="ts">
+/**
+ * IconPicker — pick one PrimeIcons glyph, or none.
+ *
+ * The `icon` column has existed on categories end-to-end (engine column,
+ * `wp_api/categories.py` `_UPDATABLE_FIELDS`, `CategoryRow.icon`) with no UI
+ * to set it, so every category rendered with the same generic bookmark.
+ *
+ * The offered glyphs live in `./icon-catalog`, which is verified against the
+ * installed `primeicons.css` by a test — an unknown name renders as an empty
+ * cell rather than failing, so nothing else would catch a typo.
+ *
+ * The glyph name is stored WITHOUT the `pi pi-` prefix (e.g. `"user"`), which
+ * is what the engine column already holds and what `Icon.vue` expects.
+ */
+import { computed, ref } from "vue";
+import Popover from "./Popover.vue";
+import { ICON_GROUPS } from "./icon-catalog";
+
+const props = withDefaults(
+  defineProps<{
+    /** Current glyph name, unprefixed (`"user"`). Empty / null = none. */
+    modelValue: string | null;
+    ariaLabel?: string | undefined;
+    dataTest?: string | undefined;
+    /** Icon only, no name beside it, for a tight table cell. */
+    compact?: boolean | undefined;
+  }>(),
+  { ariaLabel: "Pick an icon", dataTest: undefined, compact: false },
+);
+
+const emit = defineEmits<{ "update:modelValue": [v: string | null] }>();
+
+const open = ref(false);
+const current = computed<string | null>(() => props.modelValue || null);
+
+/** "arrow-right" → "Arrow right": the closed picker says which icon it holds. */
+const currentName = computed(() => {
+  const n = current.value;
+  if (!n) return "Choose icon";
+  const words = n.replace(/-/g, " ");
+  return words.charAt(0).toUpperCase() + words.slice(1);
+});
+
+function pick(name: string | null): void {
+  emit("update:modelValue", name);
+  open.value = false;
+}
+</script>
+
+<template>
+  <!-- On the kit Popover: it follows the trigger on scroll, flips to stay on
+       screen, and closes on Escape or a click outside with focus back on
+       the trigger. -->
+  <Popover v-model:open="open" :label="ariaLabel" role="listbox">
+    <template #trigger="{ props: triggerProps }">
+      <button
+        v-bind="triggerProps"
+        type="button"
+        class="wp-iconpick__trigger"
+        :class="{ 'wp-iconpick__trigger--compact': compact }"
+        :aria-label="`${ariaLabel}: ${current ? currentName : 'none'}`"
+        :data-test="dataTest"
+      >
+        <!-- Both states share one fixed-size slot: an em-dash and a glyph have
+             different intrinsic widths and baselines, so without it the trigger
+             resized and the mark shifted the moment an icon was picked. -->
+        <span class="wp-iconpick__slot" aria-hidden="true">
+          <i v-if="current" :class="`pi pi-${current}`" />
+          <span v-else class="wp-iconpick__none">—</span>
+        </span>
+        <span
+          v-if="!compact"
+          class="wp-iconpick__name"
+          :class="{ 'wp-iconpick__name--empty': !current }"
+          aria-hidden="true"
+        >{{ currentName }}</span>
+        <i class="pi pi-chevron-down wp-iconpick__caret" aria-hidden="true" />
+      </button>
+    </template>
+    <div class="wp-iconpick__panel" :data-test="dataTest ? `${dataTest}-panel` : undefined">
+      <button
+        type="button"
+        class="wp-iconpick__clear"
+        data-test="icon-picker-none"
+        @click="pick(null)"
+      >No icon</button>
+      <div v-for="group in ICON_GROUPS" :key="group.label" class="wp-iconpick__group">
+        <div class="wp-iconpick__group-label">{{ group.label }}</div>
+        <div class="wp-iconpick__grid">
+          <button
+            v-for="name in group.icons"
+            :key="name"
+            type="button"
+            class="wp-iconpick__cell"
+            :class="{ 'wp-iconpick__cell--on': name === current }"
+            role="option"
+            :aria-selected="name === current"
+            :title="name"
+            :aria-label="name"
+            :data-test="`icon-picker-${name}`"
+            @click="pick(name)"
+          ><i :class="`pi pi-${name}`" aria-hidden="true" /></button>
+        </div>
+      </div>
+    </div>
+  </Popover>
+</template>
+
+<style scoped>
+.wp-iconpick__trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--wp-space-2);
+  height: var(--wp-control-h-md, 32px);
+  min-width: 140px;
+  max-width: 220px;
+  padding: 0 var(--wp-space-4) 0 var(--wp-space-3);
+  background: var(--wp-bg-2);
+  border: 1px solid var(--wp-border);
+  border-radius: var(--wp-radius-sm);
+  font: inherit;
+  font-size: 12.5px;
+  color: var(--wp-text);
+  cursor: pointer;
+}
+.wp-iconpick__trigger:hover { border-color: var(--wp-border-strong); }
+.wp-iconpick__trigger:focus-visible { outline: none; border-color: var(--wp-accent-500); box-shadow: var(--wp-focus-ring); }
+.wp-iconpick__trigger--compact { min-width: 0; padding: 0 var(--wp-space-3); }
+.wp-iconpick__name {
+  flex: 1; min-width: 0; text-align: left;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.wp-iconpick__name--empty { color: var(--wp-text-dim); }
+/* Fixed square so the glyph is centred in it regardless of the glyph's own
+ * advance width, and so swapping "no icon" for an icon doesn't reflow. */
+.wp-iconpick__slot {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  font-size: 14px;
+  line-height: 1;
+}
+.wp-iconpick__none { color: var(--wp-text-dim); line-height: 1; }
+.wp-iconpick__caret { font-size: 9px; color: var(--wp-text-dim); line-height: 1; }
+</style>
+
+<style>
+/* Unscoped: the panel is teleported to <body> by Popover, so a scoped selector's
+   `[data-v-…]` attribute would never match it. Class names are
+   component-specific (`wp-iconpick*`), so global is safe. */
+/* Lives inside the kit Popover's panel, which gives the frame and shadow. */
+.wp-iconpick__panel {
+  width: 212px;
+  max-height: 276px;
+  overflow-y: auto;
+}
+.wp-iconpick__clear {
+  width: 100%;
+  margin-bottom: var(--wp-space-3);
+  padding: var(--wp-space-2);
+  background: transparent;
+  border: 1px dashed var(--wp-border);
+  border-radius: var(--wp-radius-sm);
+  color: var(--wp-text-muted);
+  font-size: var(--wp-text-xs);
+  cursor: pointer;
+}
+.wp-iconpick__clear:hover { color: var(--wp-text); border-color: var(--wp-accent); }
+.wp-iconpick__group + .wp-iconpick__group { margin-top: var(--wp-space-3); }
+.wp-iconpick__group-label {
+  font-size: 9.5px;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--wp-text-dim);
+  margin-bottom: var(--wp-space-2);
+}
+.wp-iconpick__grid {
+  display: grid;
+  grid-template-columns: repeat(8, 1fr);
+  gap: 2px;
+}
+.wp-iconpick__cell {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  aspect-ratio: 1;
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: var(--wp-radius-sm);
+  color: var(--wp-text-muted);
+  cursor: pointer;
+  font-size: 13px;
+}
+/* Kill the icon font's own line box — it otherwise pushes the glyph off the
+ * cell's vertical centre even though the cell is a centred flex container. */
+.wp-iconpick__cell i { line-height: 1; }
+.wp-iconpick__cell:hover {
+  background: color-mix(in oklab, var(--wp-accent) 18%, transparent);
+  color: var(--wp-text);
+}
+.wp-iconpick__cell--on {
+  border-color: var(--wp-accent);
+  color: var(--wp-accent);
+}
+</style>