@pixel-point/toolcraft 0.0.2

package/templates/ui/components/controls/font-picker/font-preview-loader.ts

@@ -0,0 +1,336 @@
+import {
+  buildFontPickerGoogleStylesheetHref,
+  getFontPickerFontById,
+  type FontPickerFontCatalogEntry,
+} from "./font-catalog";
+
+export type FontPickerPreviewLoadPriority = "high" | "normal";
+
+type QueuedPreviewTask = {
+  fontEntry: FontPickerFontCatalogEntry;
+  order: number;
+  priorityScore: number;
+};
+
+const loadedHrefSet = new Set<string>();
+const pendingHrefMap = new Map<string, Promise<void>>();
+const loadedFontFaceSet = new Set<string>();
+const pendingFontFaceMap = new Map<string, Promise<void>>();
+const queuedPreviewTaskMap = new Map<string, QueuedPreviewTask>();
+const activeQueuedFontIdSet = new Set<string>();
+const maxPreviewLoadConcurrency = 6;
+
+let activeQueuedTaskCount = 0;
+let queuedTaskOrderCounter = 0;
+
+function resolvePriorityScore(priority: FontPickerPreviewLoadPriority): number {
+  return priority === "high" ? 1 : 0;
+}
+
+function resolvePreviewWeights(entry: FontPickerFontCatalogEntry): string[] {
+  const uniqueWeights = Array.from(
+    new Set(
+      entry.weights
+        .map((value) => Number.parseInt(value, 10))
+        .filter((value) => Number.isFinite(value))
+        .sort((left, right) => left - right),
+    ),
+  );
+
+  if (!uniqueWeights.length) {
+    return ["400"];
+  }
+
+  const pickNearest = (target: number): number =>
+    uniqueWeights.reduce((closest, candidate) =>
+      Math.abs(candidate - target) < Math.abs(closest - target)
+        ? candidate
+        : closest,
+    );
+
+  return Array.from(new Set([pickNearest(400), pickNearest(600)])).map((value) =>
+    String(value),
+  );
+}
+
+function buildFontFaceDescriptor(
+  entry: FontPickerFontCatalogEntry,
+  weight: string,
+): string {
+  return `${weight} 16px "${entry.family.trim().replace(/"/g, '\\"')}"`;
+}
+
+function buildFontFaceKey(
+  entry: FontPickerFontCatalogEntry,
+  weight: string,
+): string {
+  return `${entry.id}:${weight}`;
+}
+
+function escapeSelectorValue(value: string): string {
+  return typeof CSS !== "undefined" && typeof CSS.escape === "function"
+    ? CSS.escape(value)
+    : value.replace(/["\\]/g, "\\$&");
+}
+
+function ensurePreviewFontStylesheet(href: string): Promise<void> {
+  if (typeof document === "undefined") {
+    return Promise.resolve();
+  }
+
+  if (loadedHrefSet.has(href)) {
+    return Promise.resolve();
+  }
+
+  const existing = document.head.querySelector<HTMLLinkElement>(
+    `link[data-toolcraft-font-href="${escapeSelectorValue(href)}"]`,
+  );
+
+  if (existing) {
+    if (existing.dataset.loaded === "true") {
+      loadedHrefSet.add(href);
+      return Promise.resolve();
+    }
+
+    const pending = pendingHrefMap.get(href);
+    if (pending) {
+      return pending;
+    }
+
+    const nextPending = new Promise<void>((resolve) => {
+      existing.addEventListener(
+        "load",
+        () => {
+          existing.dataset.loaded = "true";
+          loadedHrefSet.add(href);
+          pendingHrefMap.delete(href);
+          resolve();
+        },
+        { once: true },
+      );
+      existing.addEventListener(
+        "error",
+        () => {
+          pendingHrefMap.delete(href);
+          resolve();
+        },
+        { once: true },
+      );
+    });
+
+    pendingHrefMap.set(href, nextPending);
+    return nextPending;
+  }
+
+  const link = document.createElement("link");
+  link.rel = "stylesheet";
+  link.href = href;
+  link.crossOrigin = "anonymous";
+  link.dataset.toolcraftFontHref = href;
+
+  const pending = new Promise<void>((resolve) => {
+    link.addEventListener(
+      "load",
+      () => {
+        link.dataset.loaded = "true";
+        loadedHrefSet.add(href);
+        pendingHrefMap.delete(href);
+        resolve();
+      },
+      { once: true },
+    );
+    link.addEventListener(
+      "error",
+      () => {
+        pendingHrefMap.delete(href);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+
+  pendingHrefMap.set(href, pending);
+  document.head.appendChild(link);
+
+  return pending;
+}
+
+function ensurePreviewFontFaces(entry: FontPickerFontCatalogEntry): Promise<void> {
+  if (typeof document === "undefined" || !("fonts" in document)) {
+    return Promise.resolve();
+  }
+
+  const fontFaceSet = document.fonts;
+  const load =
+    typeof fontFaceSet.load === "function"
+      ? fontFaceSet.load.bind(fontFaceSet)
+      : null;
+  const check =
+    typeof fontFaceSet.check === "function"
+      ? fontFaceSet.check.bind(fontFaceSet)
+      : null;
+
+  if (!load) {
+    return Promise.resolve();
+  }
+
+  return Promise.all(
+    resolvePreviewWeights(entry).map((weight) => {
+      const key = buildFontFaceKey(entry, weight);
+
+      if (loadedFontFaceSet.has(key)) {
+        return Promise.resolve();
+      }
+
+      const descriptor = buildFontFaceDescriptor(entry, weight);
+      if (check?.(descriptor)) {
+        loadedFontFaceSet.add(key);
+        return Promise.resolve();
+      }
+
+      const pending = pendingFontFaceMap.get(key);
+      if (pending) {
+        return pending;
+      }
+
+      const nextPending = load(descriptor)
+        .then(() => {
+          loadedFontFaceSet.add(key);
+        })
+        .catch(() => undefined)
+        .finally(() => {
+          pendingFontFaceMap.delete(key);
+        });
+
+      pendingFontFaceMap.set(key, nextPending);
+      return nextPending;
+    }),
+  ).then(() => undefined);
+}
+
+export async function ensureFontPickerPreviewLoaded(
+  entry: FontPickerFontCatalogEntry,
+): Promise<void> {
+  await ensurePreviewFontStylesheet(buildFontPickerGoogleStylesheetHref(entry));
+  await ensurePreviewFontFaces(entry);
+}
+
+export function isFontPickerPreviewLoaded(
+  fontEntry: FontPickerFontCatalogEntry | null | undefined,
+): boolean {
+  if (!fontEntry) {
+    return true;
+  }
+
+  const href = buildFontPickerGoogleStylesheetHref(fontEntry);
+  if (!loadedHrefSet.has(href)) {
+    return false;
+  }
+
+  if (typeof document === "undefined" || !("fonts" in document)) {
+    return true;
+  }
+
+  const fontFaceSet = document.fonts;
+  const check =
+    typeof fontFaceSet.check === "function"
+      ? fontFaceSet.check.bind(fontFaceSet)
+      : null;
+
+  return resolvePreviewWeights(fontEntry).every((weight) => {
+    const key = buildFontFaceKey(fontEntry, weight);
+    const descriptor = buildFontFaceDescriptor(fontEntry, weight);
+    return loadedFontFaceSet.has(key) || check?.(descriptor) === true;
+  });
+}
+
+function pickNextQueuedTask(): QueuedPreviewTask | null {
+  let nextTask: QueuedPreviewTask | null = null;
+
+  queuedPreviewTaskMap.forEach((task) => {
+    if (!nextTask) {
+      nextTask = task;
+      return;
+    }
+
+    if (task.priorityScore > nextTask.priorityScore) {
+      nextTask = task;
+      return;
+    }
+
+    if (task.priorityScore === nextTask.priorityScore && task.order < nextTask.order) {
+      nextTask = task;
+    }
+  });
+
+  return nextTask;
+}
+
+function drainPreviewQueue(): void {
+  while (activeQueuedTaskCount < maxPreviewLoadConcurrency) {
+    const nextTask = pickNextQueuedTask();
+
+    if (!nextTask) {
+      return;
+    }
+
+    const taskId = nextTask.fontEntry.id;
+    queuedPreviewTaskMap.delete(taskId);
+
+    if (isFontPickerPreviewLoaded(nextTask.fontEntry)) {
+      continue;
+    }
+
+    activeQueuedFontIdSet.add(taskId);
+    activeQueuedTaskCount += 1;
+
+    void ensureFontPickerPreviewLoaded(nextTask.fontEntry).finally(() => {
+      activeQueuedFontIdSet.delete(taskId);
+      activeQueuedTaskCount = Math.max(0, activeQueuedTaskCount - 1);
+      drainPreviewQueue();
+    });
+  }
+}
+
+export function queueFontPickerPreviewLoad(
+  fontEntryOrId: FontPickerFontCatalogEntry | string | null | undefined,
+  options: { priority?: FontPickerPreviewLoadPriority } = {},
+): void {
+  const fontEntry =
+    typeof fontEntryOrId === "string"
+      ? getFontPickerFontById(fontEntryOrId)
+      : fontEntryOrId;
+
+  if (
+    !fontEntry ||
+    isFontPickerPreviewLoaded(fontEntry) ||
+    activeQueuedFontIdSet.has(fontEntry.id)
+  ) {
+    return;
+  }
+
+  const priorityScore = resolvePriorityScore(options.priority ?? "normal");
+  const existing = queuedPreviewTaskMap.get(fontEntry.id);
+
+  if (existing && existing.priorityScore >= priorityScore) {
+    return;
+  }
+
+  queuedTaskOrderCounter += 1;
+  queuedPreviewTaskMap.set(fontEntry.id, {
+    fontEntry,
+    order: queuedTaskOrderCounter,
+    priorityScore,
+  });
+
+  drainPreviewQueue();
+}
+
+export function queueFontPickerPreviewLoadBatch(
+  fontEntries: readonly FontPickerFontCatalogEntry[],
+  options: { priority?: FontPickerPreviewLoadPriority } = {},
+): void {
+  for (const fontEntry of fontEntries) {
+    queueFontPickerPreviewLoad(fontEntry, options);
+  }
+}

package/templates/ui/components/controls/font-picker/index.ts

@@ -0,0 +1,24 @@
+"use client";
+
+export {
+  FontPickerControl,
+  FontPickerControl as FontPicker,
+} from "./font-picker-control";
+export type {
+  FontPickerControlProps,
+  FontPickerLetterSpacingPreset,
+  FontPickerLineHeightPreset,
+  FontPickerTextCasePreset,
+  FontPickerValue,
+} from "./font-picker-control";
+export {
+  getDefaultFontPickerFontId,
+  getFontPickerCatalog,
+  getFontPickerFontById,
+  resolveFontPickerFontId,
+} from "./font-catalog";
+export type {
+  FontPickerFontCatalogEntry,
+  FontPickerFontCategory,
+  FontPickerFontFilterValue,
+} from "./font-catalog";

package/templates/ui/components/controls/font-picker/use-hover-intent.ts

@@ -0,0 +1,46 @@
+import * as React from "react";
+
+const hoverIntentDwellMs = 160;
+
+export function useHoverIntent<T>({
+  dwellMs = hoverIntentDwellMs,
+  onIntent,
+}: {
+  dwellMs?: number;
+  onIntent: (value: T) => void;
+}): {
+  cancelIntent: () => void;
+  scheduleIntent: (value: T) => void;
+} {
+  const timeoutRef = React.useRef<number | null>(null);
+  const pendingValueRef = React.useRef<T | undefined>(undefined);
+
+  const cancelIntent = React.useCallback(() => {
+    if (timeoutRef.current !== null) {
+      window.clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+
+    pendingValueRef.current = undefined;
+  }, []);
+
+  const scheduleIntent = React.useCallback(
+    (value: T) => {
+      cancelIntent();
+      pendingValueRef.current = value;
+      timeoutRef.current = window.setTimeout(() => {
+        timeoutRef.current = null;
+        const pendingValue = pendingValueRef.current;
+        pendingValueRef.current = undefined;
+        if (pendingValue !== undefined) {
+          onIntent(pendingValue);
+        }
+      }, dwellMs);
+    },
+    [cancelIntent, dwellMs, onIntent],
+  );
+
+  React.useEffect(() => cancelIntent, [cancelIntent]);
+
+  return { cancelIntent, scheduleIntent };
+}

package/templates/ui/components/controls/gradient/gradient-control-utils.ts

@@ -0,0 +1,190 @@
+import type { GradientStop, GradientType } from "../control-types";
+
+export type IndexedGradientStop = GradientStop & { originalIndex: number };
+
+export const maxGradientStops = 5;
+export const minGradientStops = 2;
+export const gradientTypeOptions = [
+  { label: "Linear", value: "linear" },
+  { label: "Radial", value: "radial" },
+  { label: "Angular", value: "angular" },
+  { label: "Diamond", value: "diamond" },
+] as const satisfies readonly { label: string; value: GradientType }[];
+
+function clamp(value: number, min = 0, max = 1): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+export function getGradientType(type: GradientType | undefined): GradientType {
+  return type ?? "linear";
+}
+
+export function getGradientAngle(angle: number | undefined): number {
+  return typeof angle === "number" && Number.isFinite(angle) ? Math.round(angle) : 90;
+}
+
+export function normalizeGradientAngle(angle: string): number {
+  const parsedValue = Number.parseFloat(angle);
+
+  return Number.isFinite(parsedValue) ? Math.round(parsedValue) : 90;
+}
+
+export function parseStopPosition(position: string): number {
+  const parsedValue = Number.parseFloat(position);
+
+  return Number.isFinite(parsedValue) ? clamp(parsedValue / 100) : 0;
+}
+
+export function formatStopPosition(position: number): string {
+  return `${Math.round(clamp(position) * 100)}%`;
+}
+
+export function parseStopOpacity(opacity: number | undefined): number {
+  return clamp(opacity ?? 100, 0, 100);
+}
+
+export function normalizeStopOpacity(opacity: string): number {
+  const parsedValue = Number.parseFloat(opacity);
+
+  return Number.isFinite(parsedValue) ? Math.round(clamp(parsedValue, 0, 100)) : 100;
+}
+
+export function normalizeColorInput(value: string): string {
+  const trimmedValue = value.trim();
+
+  if (/^[\da-f]{6}$/i.test(trimmedValue)) {
+    return `#${trimmedValue.toUpperCase()}`;
+  }
+
+  if (/^#[\da-f]{6}$/i.test(trimmedValue)) {
+    return trimmedValue.toUpperCase();
+  }
+
+  return getNativeColorPickerValue(trimmedValue).toUpperCase();
+}
+
+export function formatColorInputValue(color: string): string {
+  const normalizedColor = getNativeColorPickerValue(color).toUpperCase();
+
+  return normalizedColor.slice(1);
+}
+
+export function getNativeColorPickerValue(color: string): string {
+  const trimmedColor = color.trim();
+
+  if (/^#[\da-f]{6}$/i.test(trimmedColor)) {
+    return trimmedColor.toUpperCase();
+  }
+
+  if (/^[\da-f]{6}$/i.test(trimmedColor)) {
+    return `#${trimmedColor.toUpperCase()}`;
+  }
+
+  return "#000000";
+}
+
+export function sortStops(stops: readonly GradientStop[]): GradientStop[] {
+  return [...stops].sort(
+    (left, right) => parseStopPosition(left.position) - parseStopPosition(right.position),
+  );
+}
+
+export function getIndexedStops(stops: readonly GradientStop[]): IndexedGradientStop[] {
+  return stops
+    .map((stop, originalIndex) => ({ ...stop, originalIndex }))
+    .sort((left, right) => parseStopPosition(left.position) - parseStopPosition(right.position));
+}
+
+export function getStopCssColor(stop: GradientStop): string {
+  const opacity = parseStopOpacity(stop.opacity);
+
+  if (opacity >= 100) {
+    return stop.color;
+  }
+
+  return `color-mix(in oklab, ${stop.color} ${opacity}%, transparent)`;
+}
+
+function getGradientStopList(stops: readonly GradientStop[]): string {
+  return sortStops(stops)
+    .map(
+      (stop) => `${getStopCssColor(stop)} ${formatStopPosition(parseStopPosition(stop.position))}`,
+    )
+    .join(", ");
+}
+
+export function getGradientBackground(
+  type: GradientType,
+  stops: readonly GradientStop[],
+  angle = 90,
+): string {
+  const stopList = getGradientStopList(stops);
+  const gradientAngle = getGradientAngle(angle);
+
+  switch (type) {
+    case "angular":
+      return `conic-gradient(from 90deg, ${stopList})`;
+    case "diamond":
+      return `radial-gradient(closest-corner at 50% 50%, ${stopList})`;
+    case "radial":
+      return `radial-gradient(circle at 50% 50%, ${stopList})`;
+    case "linear":
+      return `linear-gradient(${gradientAngle}deg, ${stopList})`;
+  }
+}
+
+export function getNextGradientType(type: GradientType): GradientType {
+  const typeIndex = gradientTypeOptions.findIndex((option) => option.value === type);
+  const nextOption = gradientTypeOptions[(typeIndex + 1) % gradientTypeOptions.length];
+
+  return nextOption?.value ?? "linear";
+}
+
+export function isButtonTarget(target: EventTarget): boolean {
+  return target instanceof HTMLElement && target.closest("button") !== null;
+}
+
+export function getPositionFromTrack(track: HTMLDivElement | null, clientX: number): string {
+  const rect = track?.getBoundingClientRect();
+
+  if (!rect) {
+    return "0%";
+  }
+
+  return formatStopPosition((clientX - rect.left) / rect.width);
+}
+
+export function updateStopAt(
+  stops: readonly GradientStop[],
+  index: number,
+  nextStop: Partial<GradientStop>,
+): GradientStop[] {
+  return stops.map((stop, stopIndex) => (stopIndex === index ? { ...stop, ...nextStop } : stop));
+}
+
+export function addGradientStop(
+  stops: readonly GradientStop[],
+  activeStop: GradientStop | null,
+  position: string,
+): { nextStop: GradientStop; nextStops: GradientStop[] } {
+  const nextStop = {
+    color: getNativeColorPickerValue(activeStop?.color ?? "#D9D9D9"),
+    opacity: parseStopOpacity(activeStop?.opacity),
+    position,
+  };
+
+  return { nextStop, nextStops: sortStops([...stops, nextStop]) };
+}
+
+export function removeGradientStop(stops: readonly GradientStop[], index: number): GradientStop[] {
+  return stops.filter((_, stopIndex) => stopIndex !== index);
+}
+
+export function reverseGradientStops(stops: readonly GradientStop[]): GradientStop[] {
+  return sortStops(
+    stops.map((stop) => ({
+      ...stop,
+      position: formatStopPosition(1 - parseStopPosition(stop.position)),
+    })),
+  );
+}