@pixel-point/toolcraft 0.0.14 → 0.0.15

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

@@ -0,0 +1,222 @@
+import type { CSSProperties } from "react";
+
+import {
+  getFontPickerFontById,
+  resolveFontPickerFontId,
+  type FontPickerFontCatalogEntry,
+} from "./font-catalog";
+
+export type FontPickerLetterSpacingPreset =
+  | "tight"
+  | "tighter"
+  | "normal"
+  | "wide"
+  | "wider"
+  | "widest";
+
+export type FontPickerLineHeightPreset =
+  | "loose"
+  | "none"
+  | "normal"
+  | "relaxed"
+  | "snug"
+  | "tight";
+
+export type FontPickerTextCasePreset =
+  | "capitalize"
+  | "lowercase"
+  | "original"
+  | "titleCase"
+  | "uppercase";
+
+export type FontPickerValue = {
+  color: string;
+  fontId: string;
+  fontSize: number;
+  fontWeight: string;
+  letterSpacing: FontPickerLetterSpacingPreset;
+  lineHeight: FontPickerLineHeightPreset;
+  opacity: number;
+  textCase: FontPickerTextCasePreset;
+};
+
+export type FontPickerInputValue = Partial<FontPickerValue> | string | undefined;
+
+export const defaultFontPickerFontSizePx = 16;
+export const defaultFontPickerColor = "#FFFFFF";
+export const defaultFontPickerOpacity = 100;
+export const minFontPickerFontSizePx = 1;
+
+export const letterSpacingSteps: Array<{
+  label: string;
+  numericValue: number;
+  value: FontPickerLetterSpacingPreset;
+}> = [
+  { label: "Tighter", numericValue: -0.05, value: "tighter" },
+  { label: "Tight", numericValue: -0.025, value: "tight" },
+  { label: "Normal", numericValue: 0, value: "normal" },
+  { label: "Wide", numericValue: 0.025, value: "wide" },
+  { label: "Wider", numericValue: 0.05, value: "wider" },
+  { label: "Widest", numericValue: 0.1, value: "widest" },
+];
+
+export const lineHeightSteps: Array<{
+  label: string;
+  numericValue: number;
+  value: FontPickerLineHeightPreset;
+}> = [
+  { label: "None", numericValue: 1, value: "none" },
+  { label: "Tight", numericValue: 1.25, value: "tight" },
+  { label: "Snug", numericValue: 1.375, value: "snug" },
+  { label: "Normal", numericValue: 1.5, value: "normal" },
+  { label: "Relaxed", numericValue: 1.625, value: "relaxed" },
+  { label: "Loose", numericValue: 2, value: "loose" },
+];
+
+export const textCaseOptions: Array<{
+  label: string;
+  value: FontPickerTextCasePreset;
+}> = [
+  { label: "As typed", value: "original" },
+  { label: "Uppercase", value: "uppercase" },
+  { label: "Lowercase", value: "lowercase" },
+  { label: "Capitalize", value: "capitalize" },
+  { label: "Title Case", value: "titleCase" },
+];
+
+export function isFontPickerTextCase(
+  value: unknown,
+): value is FontPickerTextCasePreset {
+  return textCaseOptions.some((option) => option.value === value);
+}
+
+export function getStepByValue<Value extends string>(
+  steps: readonly { numericValue: number; value: Value }[],
+  value: Value,
+  fallbackValue: Value,
+): { numericValue: number; value: Value } {
+  const step = steps.find((item) => item.value === value);
+  if (step) {
+    return step;
+  }
+
+  return steps.find((item) => item.value === fallbackValue) ?? steps[0]!;
+}
+
+export function getStepIndexByValue<Value extends string>(
+  steps: readonly { value: Value }[],
+  value: Value,
+  fallbackValue: Value,
+): number {
+  const stepIndex = steps.findIndex((item) => item.value === value);
+  if (stepIndex >= 0) {
+    return stepIndex;
+  }
+
+  const fallbackIndex = steps.findIndex((item) => item.value === fallbackValue);
+  return fallbackIndex >= 0 ? fallbackIndex : 0;
+}
+
+export function normalizeFontPickerValue(
+  value: FontPickerInputValue,
+): FontPickerValue {
+  const fontId = resolveFontPickerFontId(
+    typeof value === "string" ? value : value?.fontId,
+  );
+  const font = getFontPickerFontById(fontId);
+
+  if (typeof value === "string") {
+    return {
+      color: defaultFontPickerColor,
+      fontId,
+      fontSize: defaultFontPickerFontSizePx,
+      fontWeight: resolveFontPickerFontWeight(font),
+      letterSpacing: "normal",
+      lineHeight: "normal",
+      opacity: defaultFontPickerOpacity,
+      textCase: "original",
+    };
+  }
+
+  return {
+    color: normalizeFontPickerColor(value?.color),
+    fontId,
+    fontSize: normalizeFontPickerFontSize(value?.fontSize),
+    fontWeight: resolveFontPickerFontWeight(font, value?.fontWeight),
+    letterSpacing: value?.letterSpacing ?? "normal",
+    lineHeight: value?.lineHeight ?? "normal",
+    opacity: normalizeFontPickerOpacity(value?.opacity),
+    textCase: isFontPickerTextCase(value?.textCase) ? value.textCase : "original",
+  };
+}
+
+export function normalizeFontPickerColor(value: unknown): string {
+  return typeof value === "string" && value.trim()
+    ? value
+    : defaultFontPickerColor;
+}
+
+export function normalizeFontPickerOpacity(value: unknown): number {
+  const nextOpacity =
+    typeof value === "number" ? value : Number.parseFloat(String(value ?? ""));
+
+  return Number.isFinite(nextOpacity)
+    ? Math.min(100, Math.max(0, Math.round(nextOpacity)))
+    : defaultFontPickerOpacity;
+}
+
+export function getFontPickerWeightOptions(
+  font: FontPickerFontCatalogEntry | null,
+): string[] {
+  const weights = font?.weights.length ? font.weights : ["400"];
+
+  return Array.from(new Set(weights.map((weight) => String(weight)))).sort(
+    (left, right) => Number(left) - Number(right),
+  );
+}
+
+export function resolveFontPickerFontWeight(
+  font: FontPickerFontCatalogEntry | null,
+  weight?: string,
+): string {
+  const weights = getFontPickerWeightOptions(font);
+  const requestedWeight = typeof weight === "string" ? weight : undefined;
+
+  if (requestedWeight && weights.includes(requestedWeight)) {
+    return requestedWeight;
+  }
+
+  if (weights.includes("400")) {
+    return "400";
+  }
+
+  const requestedNumericWeight = Number(requestedWeight ?? 400);
+  if (Number.isFinite(requestedNumericWeight)) {
+    return weights.reduce((closest, current) => {
+      return Math.abs(Number(current) - requestedNumericWeight) <
+        Math.abs(Number(closest) - requestedNumericWeight)
+        ? current
+        : closest;
+    }, weights[0] ?? "400");
+  }
+
+  return weights[0] ?? "400";
+}
+
+export function normalizeFontPickerFontSize(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return defaultFontPickerFontSizePx;
+  }
+
+  return Math.max(minFontPickerFontSizePx, Math.round(value));
+}
+
+export function getFontFamilyStyle(
+  font: FontPickerFontCatalogEntry | null,
+): CSSProperties | undefined {
+  return font
+    ? {
+        fontFamily: `"${font.family}", ui-sans-serif, system-ui, sans-serif`,
+      }
+    : undefined;
+}

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

@@ -6,11 +6,14 @@ export {
 } from "./font-picker-control";
 export type {
   FontPickerControlProps,
+} from "./font-picker-control";
+export type {
+  FontPickerInputValue,
   FontPickerLetterSpacingPreset,
   FontPickerLineHeightPreset,
   FontPickerTextCasePreset,
   FontPickerValue,
-} from "./font-picker-control";
+} from "./font-picker-value";
 export {
   getDefaultFontPickerFontId,
   getFontPickerCatalog,

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

@@ -0,0 +1,163 @@
+"use client";
+
+import * as React from "react";
+
+import type { FontPickerFontCatalogEntry } from "./font-catalog";
+import {
+  queueFontPickerPreviewLoad,
+  queueFontPickerPreviewLoadBatch,
+} from "./font-preview-loader";
+import { useHoverIntent } from "./use-hover-intent";
+
+export function useFontPickerPreviewPipeline({
+  disabled,
+  onPreviewChange,
+  open,
+  selectedFont,
+  visibleFonts,
+}: {
+  disabled: boolean;
+  onPreviewChange?: (nextFontId: string | null) => void;
+  open: boolean;
+  selectedFont?: FontPickerFontCatalogEntry | null;
+  visibleFonts: readonly FontPickerFontCatalogEntry[];
+}): {
+  cancelHoverPreviewIntent: () => void;
+  clearHoverPreview: () => void;
+  emitPreviewChange: (
+    nextFontId: string | null,
+    options?: { immediate?: boolean },
+  ) => void;
+  handleHoverPreview: (font: FontPickerFontCatalogEntry) => void;
+  scheduleHoverPreviewIntent: (font: FontPickerFontCatalogEntry) => void;
+  warmFontPreview: (
+    fontEntry: FontPickerFontCatalogEntry | null | undefined,
+    priority?: "high" | "normal",
+  ) => void;
+} {
+  const previewFrameRef = React.useRef<number | null>(null);
+  const pendingPreviewFontIdRef = React.useRef<string | null>(null);
+  const lastEmittedPreviewFontIdRef = React.useRef<string | null>(null);
+
+  const emitPreviewImmediately = React.useCallback(
+    (nextFontId: string | null) => {
+      if (disabled) {
+        return;
+      }
+
+      if (nextFontId !== null && lastEmittedPreviewFontIdRef.current === nextFontId) {
+        return;
+      }
+
+      lastEmittedPreviewFontIdRef.current = nextFontId;
+      onPreviewChange?.(nextFontId);
+    },
+    [disabled, onPreviewChange],
+  );
+
+  const cancelScheduledPreview = React.useCallback(() => {
+    if (previewFrameRef.current !== null) {
+      window.cancelAnimationFrame(previewFrameRef.current);
+      previewFrameRef.current = null;
+    }
+
+    pendingPreviewFontIdRef.current = null;
+  }, []);
+
+  const emitPreviewChange = React.useCallback(
+    (nextFontId: string | null, options?: { immediate?: boolean }) => {
+      if (disabled) {
+        return;
+      }
+
+      if (nextFontId === null || options?.immediate) {
+        cancelScheduledPreview();
+        emitPreviewImmediately(nextFontId);
+        return;
+      }
+
+      pendingPreviewFontIdRef.current = nextFontId;
+      if (previewFrameRef.current !== null) {
+        return;
+      }
+
+      previewFrameRef.current = window.requestAnimationFrame(() => {
+        previewFrameRef.current = null;
+        const scheduledFontId = pendingPreviewFontIdRef.current;
+        pendingPreviewFontIdRef.current = null;
+
+        if (scheduledFontId) {
+          emitPreviewImmediately(scheduledFontId);
+        }
+      });
+    },
+    [cancelScheduledPreview, disabled, emitPreviewImmediately],
+  );
+
+  const warmFontPreview = React.useCallback(
+    (
+      fontEntry: FontPickerFontCatalogEntry | null | undefined,
+      priority: "high" | "normal" = "normal",
+    ) => {
+      if (!fontEntry) {
+        return;
+      }
+
+      queueFontPickerPreviewLoad(fontEntry, { priority });
+    },
+    [],
+  );
+
+  const handleHoverPreview = React.useCallback(
+    (font: FontPickerFontCatalogEntry) => {
+      warmFontPreview(font, "high");
+      emitPreviewChange(font.id);
+    },
+    [emitPreviewChange, warmFontPreview],
+  );
+
+  const {
+    cancelIntent: cancelHoverPreviewIntent,
+    scheduleIntent: scheduleHoverPreviewIntent,
+  } = useHoverIntent({ onIntent: handleHoverPreview });
+
+  const clearHoverPreview = React.useCallback(() => {
+    cancelHoverPreviewIntent();
+    emitPreviewChange(null, { immediate: true });
+  }, [cancelHoverPreviewIntent, emitPreviewChange]);
+
+  React.useEffect(() => {
+    if (selectedFont) {
+      warmFontPreview(selectedFont, "high");
+    }
+  }, [selectedFont, warmFontPreview]);
+
+  React.useEffect(() => {
+    if (!open) {
+      return;
+    }
+
+    if (selectedFont) {
+      warmFontPreview(selectedFont, "high");
+    }
+
+    queueFontPickerPreviewLoadBatch(visibleFonts, { priority: "high" });
+  }, [open, selectedFont, visibleFonts, warmFontPreview]);
+
+  React.useEffect(() => {
+    return () => {
+      cancelHoverPreviewIntent();
+      cancelScheduledPreview();
+      onPreviewChange?.(null);
+    };
+  }, [cancelHoverPreviewIntent, cancelScheduledPreview, onPreviewChange]);
+
+  return {
+    cancelHoverPreviewIntent,
+    clearHoverPreview,
+    emitPreviewChange,
+    handleHoverPreview,
+    scheduleHoverPreviewIntent,
+    warmFontPreview,
+  };
+}

package/templates/ui/components/controls/font-picker/use-font-picker-virtual-list.ts

@@ -0,0 +1,293 @@
+"use client";
+
+import * as React from "react";
+
+import {
+  filterFontPickerFonts,
+  type FontPickerFontCatalogEntry,
+  type FontPickerFontFilterValue,
+} from "./font-catalog";
+import { queueFontPickerPreviewLoadBatch } from "./font-preview-loader";
+import {
+  fontItemHeightPx,
+  fontListHeightWithFooterPx,
+  fontListOverscanItems,
+  fontPreloadBufferAheadItems,
+  fontPreloadBufferBehindItems,
+  fontVirtualItemStepPx,
+  type FontPickerPinnedSelectedRowSide,
+} from "./font-picker-list";
+
+export function useFontPickerVirtualList({
+  open,
+  selectedFont,
+}: {
+  open: boolean;
+  selectedFont?: FontPickerFontCatalogEntry | null;
+}): {
+  attachScrollViewport: (node: HTMLDivElement | null) => void;
+  bottomSpacerHeight: number;
+  cancelOpenSelectedScroll: () => void;
+  category: FontPickerFontFilterValue;
+  filteredFonts: readonly FontPickerFontCatalogEntry[];
+  pinnedSelectedRowSide: FontPickerPinnedSelectedRowSide;
+  prepareForOpen: (nextCategory: FontPickerFontFilterValue) => void;
+  query: string;
+  scrollToFontIndex: (index: number) => void;
+  searchInputRef: React.RefObject<HTMLInputElement | null>;
+  selectedFontIndex: number;
+  setCategoryWithReset: (nextCategory: FontPickerFontFilterValue) => void;
+  setQueryWithReset: (nextQuery: string) => void;
+  topSpacerHeight: number;
+  virtualEndIndex: number;
+  virtualStartIndex: number;
+  visibleFonts: readonly FontPickerFontCatalogEntry[];
+} {
+  const [query, setQuery] = React.useState("");
+  const [category, setCategory] =
+    React.useState<FontPickerFontFilterValue>("sans-serif");
+  const [scrollTop, setScrollTop] = React.useState(0);
+  const [viewportHeight, setViewportHeight] = React.useState(0);
+  const [scrollViewportElement, setScrollViewportElement] =
+    React.useState<HTMLDivElement | null>(null);
+  const searchInputRef = React.useRef<HTMLInputElement>(null);
+  const scrollViewportRef = React.useRef<HTMLDivElement | null>(null);
+  const previousScrollTopRef = React.useRef(0);
+  const scrollDirectionRef = React.useRef<"backward" | "forward">("forward");
+  const shouldScrollSelectedOnOpenRef = React.useRef(false);
+  const scrollFrameRef = React.useRef<number | null>(null);
+
+  const filteredFonts = React.useMemo(
+    () => filterFontPickerFonts(query, category),
+    [category, query],
+  );
+  const selectedFontIndex = React.useMemo(() => {
+    if (!selectedFont) {
+      return -1;
+    }
+
+    return filteredFonts.findIndex((font) => font.id === selectedFont.id);
+  }, [filteredFonts, selectedFont]);
+  const resolvedViewportHeight =
+    viewportHeight > 0 ? viewportHeight : fontListHeightWithFooterPx;
+  const selectedFontTop =
+    selectedFontIndex >= 0 ? selectedFontIndex * fontVirtualItemStepPx : 0;
+  const selectedFontBottom = selectedFontTop + fontItemHeightPx;
+  const selectedFontVisible =
+    selectedFontIndex >= 0 &&
+    selectedFontBottom > scrollTop &&
+    selectedFontTop < scrollTop + resolvedViewportHeight;
+  const pinnedSelectedRowSide =
+    selectedFont && selectedFontIndex >= 0 && !selectedFontVisible
+      ? selectedFontBottom <= scrollTop
+        ? "top"
+        : "bottom"
+      : null;
+  const visibleItemCount = Math.max(
+    1,
+    Math.ceil(resolvedViewportHeight / fontVirtualItemStepPx),
+  );
+  const virtualStartIndex = Math.max(
+    0,
+    Math.floor(scrollTop / fontVirtualItemStepPx) - fontListOverscanItems,
+  );
+  const virtualEndIndex = Math.min(
+    filteredFonts.length,
+    virtualStartIndex + visibleItemCount + fontListOverscanItems * 2,
+  );
+  const visibleFonts = React.useMemo(
+    () => filteredFonts.slice(virtualStartIndex, virtualEndIndex),
+    [filteredFonts, virtualEndIndex, virtualStartIndex],
+  );
+  const topSpacerHeight = virtualStartIndex * fontVirtualItemStepPx;
+  const bottomSpacerHeight = Math.max(
+    0,
+    (filteredFonts.length - virtualEndIndex) * fontVirtualItemStepPx,
+  );
+
+  const resetViewportScroll = React.useCallback(() => {
+    const viewportElement = scrollViewportRef.current;
+    if (viewportElement) {
+      viewportElement.scrollTop = 0;
+    }
+
+    previousScrollTopRef.current = 0;
+    scrollDirectionRef.current = "forward";
+    setScrollTop(0);
+  }, []);
+
+  const scrollToFontIndex = React.useCallback((index: number) => {
+    if (index < 0 || !scrollViewportRef.current) {
+      return;
+    }
+
+    const nextScrollTop = index * fontVirtualItemStepPx;
+    scrollDirectionRef.current =
+      nextScrollTop >= scrollViewportRef.current.scrollTop
+        ? "forward"
+        : "backward";
+    previousScrollTopRef.current = nextScrollTop;
+    scrollViewportRef.current.scrollTop = nextScrollTop;
+    setScrollTop(nextScrollTop);
+  }, []);
+
+  const queueBufferedPreload = React.useCallback(
+    (direction: "backward" | "forward") => {
+      if (!filteredFonts.length) {
+        return;
+      }
+
+      const backwardItems =
+        direction === "forward"
+          ? fontPreloadBufferBehindItems
+          : fontPreloadBufferAheadItems;
+      const forwardItems =
+        direction === "forward"
+          ? fontPreloadBufferAheadItems
+          : fontPreloadBufferBehindItems;
+      const preloadStart = Math.max(0, virtualStartIndex - backwardItems);
+      const preloadEnd = Math.min(filteredFonts.length, virtualEndIndex + forwardItems);
+
+      if (preloadStart >= preloadEnd) {
+        return;
+      }
+
+      queueFontPickerPreviewLoadBatch(filteredFonts.slice(preloadStart, preloadEnd), {
+        priority: "normal",
+      });
+    },
+    [filteredFonts, virtualEndIndex, virtualStartIndex],
+  );
+
+  const setCategoryWithReset = React.useCallback(
+    (nextCategory: FontPickerFontFilterValue) => {
+      resetViewportScroll();
+      setCategory(nextCategory);
+    },
+    [resetViewportScroll],
+  );
+
+  const setQueryWithReset = React.useCallback(
+    (nextQuery: string) => {
+      resetViewportScroll();
+      setQuery(nextQuery);
+    },
+    [resetViewportScroll],
+  );
+
+  const prepareForOpen = React.useCallback(
+    (nextCategory: FontPickerFontFilterValue) => {
+      shouldScrollSelectedOnOpenRef.current = true;
+      setQuery("");
+      setCategory(nextCategory);
+      resetViewportScroll();
+    },
+    [resetViewportScroll],
+  );
+
+  const cancelOpenSelectedScroll = React.useCallback(() => {
+    shouldScrollSelectedOnOpenRef.current = false;
+  }, []);
+
+  const attachScrollViewport = React.useCallback((node: HTMLDivElement | null) => {
+    scrollViewportRef.current = node;
+    setScrollViewportElement(node);
+  }, []);
+
+  React.useEffect(() => {
+    if (!open) {
+      return;
+    }
+
+    queueBufferedPreload(scrollDirectionRef.current);
+  }, [open, queueBufferedPreload, scrollTop]);
+
+  React.useEffect(() => {
+    if (!open) {
+      return undefined;
+    }
+
+    const frame = window.requestAnimationFrame(() => {
+      searchInputRef.current?.focus({ preventScroll: true });
+    });
+
+    return () => window.cancelAnimationFrame(frame);
+  }, [open]);
+
+  React.useEffect(() => {
+    if (!open || !shouldScrollSelectedOnOpenRef.current || selectedFontIndex < 0) {
+      return undefined;
+    }
+
+    const frame = window.requestAnimationFrame(() => {
+      shouldScrollSelectedOnOpenRef.current = false;
+      scrollToFontIndex(selectedFontIndex);
+    });
+
+    return () => window.cancelAnimationFrame(frame);
+  }, [open, scrollToFontIndex, selectedFontIndex]);
+
+  React.useEffect(() => {
+    if (!open || !scrollViewportElement) {
+      return undefined;
+    }
+
+    const viewportElement = scrollViewportElement;
+    const syncMetrics = () => {
+      setViewportHeight(
+        viewportElement.clientHeight > 0
+          ? viewportElement.clientHeight
+          : fontListHeightWithFooterPx,
+      );
+      setScrollTop(viewportElement.scrollTop);
+    };
+    const handleScroll = () => {
+      if (scrollFrameRef.current !== null) {
+        window.cancelAnimationFrame(scrollFrameRef.current);
+      }
+
+      scrollFrameRef.current = window.requestAnimationFrame(() => {
+        scrollFrameRef.current = null;
+        const nextScrollTop = viewportElement.scrollTop;
+        scrollDirectionRef.current =
+          nextScrollTop >= previousScrollTopRef.current ? "forward" : "backward";
+        previousScrollTopRef.current = nextScrollTop;
+        setScrollTop(nextScrollTop);
+      });
+    };
+
+    syncMetrics();
+    viewportElement.addEventListener("scroll", handleScroll, { passive: true });
+    window.addEventListener("resize", syncMetrics);
+
+    return () => {
+      viewportElement.removeEventListener("scroll", handleScroll);
+      window.removeEventListener("resize", syncMetrics);
+
+      if (scrollFrameRef.current !== null) {
+        window.cancelAnimationFrame(scrollFrameRef.current);
+        scrollFrameRef.current = null;
+      }
+    };
+  }, [open, scrollViewportElement]);
+
+  return {
+    attachScrollViewport,
+    bottomSpacerHeight,
+    cancelOpenSelectedScroll,
+    category,
+    filteredFonts,
+    pinnedSelectedRowSide,
+    prepareForOpen,
+    query,
+    scrollToFontIndex,
+    searchInputRef,
+    selectedFontIndex,
+    setCategoryWithReset,
+    setQueryWithReset,
+    topSpacerHeight,
+    virtualEndIndex,
+    virtualStartIndex,
+    visibleFonts,
+  };
+}