@smicolon/fasla-ui 0.2.4 → 0.4.0

package/registry/effects/spotlight/spotlight.tsx

@@ -1,9 +1,16 @@
 "use client"
 
 import * as React from "react"
-import { motion, useMotionValue, useSpring, useReducedMotion } from "framer-motion"
+import { AnimatePresence, motion, useMotionValue, useSpring, useReducedMotion } from "framer-motion"
 import { cn } from "../../../src/lib/utils"
 
+/** A layout effect in the browser, a plain effect on the server (where neither runs). */
+const useIsomorphicLayoutEffect = typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect
+
+/** The value, or the fallback when it is missing or blank (a cleared control, say). */
+const filled = (value: string | undefined, fallback: string) =>
+  value && value.trim() ? value : fallback
+
 export interface SpotlightProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Spotlight color */
   color?: string
@@ -20,7 +27,7 @@ export interface SpotlightProps extends React.HTMLAttributes<HTMLDivElement> {
  * Respects prefers-reduced-motion by disabling the effect.
  */
 export function Spotlight({
-  color = "hsl(var(--primary) / 0.15)",
+  color: colorProp,
   size = 400,
   blur = 80,
   opacity = 1,
@@ -28,6 +35,7 @@ export function Spotlight({
   children,
   ...props
 }: SpotlightProps) {
+  const color = filled(colorProp, "color-mix(in oklch, var(--primary) 15%, transparent)")
   const prefersReducedMotion = useReducedMotion()
   const containerRef = React.useRef<HTMLDivElement>(null)
 
@@ -38,18 +46,43 @@ export function Spotlight({
   const springX = useSpring(mouseX, springConfig)
   const springY = useSpring(mouseY, springConfig)
 
+  // The motion values hold the light's centre, and the light is offset by half
+  // its size through left and top, so a change of size keeps it centred on the
+  // same point instead of drifting away from the pointer.
+  //
+  // Rest at the container's centre, not its top-left corner, until the pointer
+  // moves, and follow that centre while the container resizes (a sidebar
+  // opening, say).
+  const pointerMoved = React.useRef(false)
+  useIsomorphicLayoutEffect(() => {
+    const el = containerRef.current
+    if (!el) return
+    const centre = () => {
+      if (pointerMoved.current) return
+      const x = el.offsetWidth / 2
+      const y = el.offsetHeight / 2
+      mouseX.jump(x)
+      mouseY.jump(y)
+      springX.jump(x)
+      springY.jump(y)
+    }
+    centre()
+    if (typeof ResizeObserver === "undefined") return
+    const observer = new ResizeObserver(centre)
+    observer.observe(el)
+    return () => observer.disconnect()
+  }, [mouseX, mouseY, springX, springY, prefersReducedMotion])
+
   const handleMouseMove = React.useCallback(
     (e: React.MouseEvent<HTMLDivElement>) => {
       if (!containerRef.current || prefersReducedMotion) return
 
+      pointerMoved.current = true
       const rect = containerRef.current.getBoundingClientRect()
-      const x = e.clientX - rect.left - size / 2
-      const y = e.clientY - rect.top - size / 2
-
-      mouseX.set(x)
-      mouseY.set(y)
+      mouseX.set(e.clientX - rect.left)
+      mouseY.set(e.clientY - rect.top)
     },
-    [mouseX, mouseY, size, prefersReducedMotion]
+    [mouseX, mouseY, prefersReducedMotion]
   )
 
   if (prefersReducedMotion) {
@@ -64,15 +97,19 @@ export function Spotlight({
     <div
       ref={containerRef}
       onMouseMove={handleMouseMove}
-      className={cn("relative overflow-hidden", className)}
+      className={cn("relative isolate overflow-hidden", className)}
       {...props}
     >
-      {/* Spotlight */}
+      {/* Spotlight. Placed from the top-left corner (a flex parent that centres
+          its content would otherwise move the origin), then pulled back by half
+          its size so x and y are its centre. */}
       <motion.div
         className="pointer-events-none absolute -z-10 rounded-full"
         style={{
           x: springX,
           y: springY,
+          left: -size / 2,
+          top: -size / 2,
           width: size,
           height: size,
           background: `radial-gradient(circle, ${color} 0%, transparent 70%)`,
@@ -98,12 +135,13 @@ export interface SpotlightCardProps extends React.HTMLAttributes<HTMLDivElement>
  * Card with spotlight effect on hover.
  */
 export function SpotlightCard({
-  spotlightColor = "hsl(var(--primary) / 0.1)",
+  spotlightColor: spotlightColorProp,
   spotlightSize = 300,
   className,
   children,
   ...props
 }: SpotlightCardProps) {
+  const spotlightColor = filled(spotlightColorProp, "color-mix(in oklch, var(--primary) 10%, transparent)")
   const prefersReducedMotion = useReducedMotion()
   const containerRef = React.useRef<HTMLDivElement>(null)
   const [isHovered, setIsHovered] = React.useState(false)
@@ -132,28 +170,34 @@ export function SpotlightCard({
       onMouseEnter={() => setIsHovered(true)}
       onMouseLeave={() => setIsHovered(false)}
       className={cn(
-        "relative overflow-hidden rounded-xl border bg-card p-6 shadow",
+        "relative isolate overflow-hidden rounded-xl border bg-card p-6 shadow",
         className
       )}
       {...props}
     >
-      {/* Spotlight */}
-      {!prefersReducedMotion && isHovered && (
-        <motion.div
-          className="pointer-events-none absolute -z-10 rounded-full"
-          style={{
-            x: mouseX,
-            y: mouseY,
-            width: spotlightSize,
-            height: spotlightSize,
-            background: `radial-gradient(circle, ${spotlightColor} 0%, transparent 70%)`,
-            transform: "translate(-50%, -50%)",
-          }}
-          initial={{ opacity: 0 }}
-          animate={{ opacity: 1 }}
-          exit={{ opacity: 0 }}
-        />
-      )}
+      {/*
+        Spotlight. Centred on the pointer by offsetting half its size: a CSS
+        translate(-50%, -50%) is overwritten by the x and y motion values.
+      */}
+      <AnimatePresence>
+        {!prefersReducedMotion && isHovered && (
+          <motion.div
+            className="pointer-events-none absolute -z-10 rounded-full"
+            style={{
+              x: mouseX,
+              y: mouseY,
+              left: -spotlightSize / 2,
+              top: -spotlightSize / 2,
+              width: spotlightSize,
+              height: spotlightSize,
+              background: `radial-gradient(circle, ${spotlightColor} 0%, transparent 70%)`,
+            }}
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={{ opacity: 0 }}
+          />
+        )}
+      </AnimatePresence>
 
       {/* Content */}
       {children}

package/registry/effects/text-reveal/index.ts

@@ -1,6 +1,7 @@
 export {
   TextReveal,
   WordReveal,
+  revealUnits,
   type TextRevealProps,
   type WordRevealProps,
 } from "./text-reveal"

package/registry/effects/text-reveal/text-reveal.test.tsx

@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeAll } from "vitest"
+import { render } from "@testing-library/react"
+import { TextReveal, revealUnits } from "./text-reveal"
+
+// framer-motion's useInView needs an observer, which jsdom does not provide.
+beforeAll(() => {
+  globalThis.IntersectionObserver ??= class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  } as unknown as typeof IntersectionObserver
+})
+
+describe("TextReveal units", () => {
+  it("splits Latin text into characters", () => {
+    expect(revealUnits("Hi there")).toEqual(["H", "i", " ", "t", "h", "e", "r", "e"])
+  })
+
+  it("keeps a combining mark with its letter", () => {
+    expect(revealUnits("été")).toEqual(["é", "t", "é"])
+  })
+
+  it("splits Arabic into words, so the letters stay joined", () => {
+    expect(revealUnits("مكوّن جاهز")).toEqual(["مكوّن", " ", "جاهز"])
+  })
+
+  it("renders one span per Arabic word", () => {
+    const { container } = render(<TextReveal text="أطلق متجرك اليوم" triggerOnView={false} />)
+    const spans = Array.from(container.querySelectorAll("span[aria-hidden]"), (span) => span.textContent)
+    expect(spans).toEqual(["أطلق", "متجرك", "اليوم"])
+  })
+
+  it("gives assistive tech the whole text once", () => {
+    const { container } = render(<TextReveal text="Hello" triggerOnView={false} />)
+    expect(container.querySelector(".sr-only")?.textContent).toBe("Hello")
+    expect(container.querySelectorAll("span[aria-hidden]")).toHaveLength(5)
+  })
+
+  it("keeps whitespace as plain text, so white-space rules apply as they do to the unanimated text", () => {
+    const text = "أطلق  متجرك\nاليوم"
+    const { container } = render(<TextReveal text={text} triggerOnView={false} className="whitespace-pre-wrap" />)
+    const root = container.firstElementChild!
+    const visible = Array.from(root.childNodes)
+      .filter((node) => !(node instanceof HTMLElement && node.classList.contains("sr-only")))
+      .map((node) => node.textContent)
+      .join("")
+    expect(visible).toBe(text)
+    expect(root.querySelectorAll("span[aria-hidden]")).toHaveLength(3)
+  })
+
+  it("keeps a combining mark with its letter when Intl.Segmenter is missing", () => {
+    const intl = Intl as unknown as { Segmenter?: unknown }
+    const saved = intl.Segmenter
+    delete intl.Segmenter
+    try {
+      expect(revealUnits("e\u0301te\u0300")).toEqual(["e\u0301", "t", "e\u0300"])
+    } finally {
+      intl.Segmenter = saved
+    }
+  })
+
+  it("is exported from the effect's entry point", async () => {
+    const entry = await import("./index")
+    expect(entry.revealUnits).toBe(revealUnits)
+  })
+})

package/registry/effects/text-reveal/text-reveal.tsx

@@ -16,7 +16,44 @@ export interface TextRevealProps extends React.HTMLAttributes<HTMLDivElement> {
 }
 
 /**
- * Text reveal animation that reveals text character by character.
+ * Scripts whose letters join to their neighbours: Arabic (with its supplements
+ * and presentation forms), Syriac, N'Ko and Mandaic. A span per letter would
+ * break the joins, so these reveal by word instead. The range also takes in
+ * Thaana, which does not join; revealing it by word is harmless.
+ */
+const JOINED_SCRIPT = /[\u0600-\u08FF\uFB50-\uFDFF\uFE70-\uFEFF]/
+
+/** The slice of Intl.Segmenter used here, typed locally: older TypeScript libs lack it. */
+type GraphemeSegmenter = new (
+  locale: undefined,
+  options: { granularity: "grapheme" }
+) => { segment(text: string): Iterable<{ segment: string }> }
+
+/** Splits into user-perceived characters, so a mark stays with its letter. */
+function splitGraphemes(text: string): string[] {
+  const Segmenter = (Intl as unknown as { Segmenter?: GraphemeSegmenter }).Segmenter
+  if (Segmenter) {
+    const segmenter = new Segmenter(undefined, { granularity: "grapheme" })
+    return Array.from(segmenter.segment(text), (part) => part.segment)
+  }
+  // Without Segmenter (Firefox before 125, for one), keep each combining mark
+  // with the character before it, so a letter and its accent animate together.
+  // Built from a string: TypeScript rejects the u flag in a regex literal when
+  // the target is below ES2015, as it is in a Next.js 14 tsconfig.
+  return text.match(new RegExp("\\P{M}\\p{M}*|\\p{M}+", "gu")) ?? []
+}
+
+/**
+ * Splits the text into the pieces TextReveal animates: characters, or words
+ * with their spaces for a joined script such as Arabic.
+ */
+export function revealUnits(text: string): string[] {
+  return JOINED_SCRIPT.test(text) ? text.split(/(\s+)/).filter(Boolean) : splitGraphemes(text)
+}
+
+/**
+ * Text reveal animation that reveals text character by character. Arabic and
+ * other joined scripts reveal word by word, so their letters stay connected.
  * Respects prefers-reduced-motion by showing text immediately.
  */
 export function TextReveal({
@@ -32,7 +69,7 @@ export function TextReveal({
   const isInView = useInView(ref, { once: true, amount: 0.5 })
 
   const shouldAnimate = triggerOnView ? isInView : true
-  const characters = text.split("")
+  const units = revealUnits(text)
 
   if (prefersReducedMotion) {
     return (
@@ -48,25 +85,35 @@ export function TextReveal({
       className={cn("inline-block", className)}
       {...props}
     >
-      {characters.map((char, i) => (
-        <motion.span
-          key={`${char}-${i}`}
-          className="inline-block"
-          initial={{ opacity: 0, y: 10 }}
-          animate={
-            shouldAnimate
-              ? { opacity: 1, y: 0 }
-              : { opacity: 0, y: 10 }
-          }
-          transition={{
-            duration,
-            delay: i * delay,
-            ease: [0.2, 0.65, 0.3, 0.9],
-          }}
-        >
-          {char === " " ? "\u00A0" : char}
-        </motion.span>
-      ))}
+      {/* Read once, whole; the animated pieces are hidden from assistive tech */}
+      <span className="sr-only">{text}</span>
+      {units.map((unit, i) =>
+        /^\s+$/.test(unit) ? (
+          // Whitespace stays plain text, so it follows the element's
+          // white-space like the unanimated text: collapsed normally, kept
+          // (with its line breaks) under whitespace-pre-wrap.
+          <React.Fragment key={`space-${i}`}>{unit}</React.Fragment>
+        ) : (
+          <motion.span
+            aria-hidden="true"
+            key={`${unit}-${i}`}
+            className="inline-block"
+            initial={{ opacity: 0, y: 10 }}
+            animate={
+              shouldAnimate
+                ? { opacity: 1, y: 0 }
+                : { opacity: 0, y: 10 }
+            }
+            transition={{
+              duration,
+              delay: i * delay,
+              ease: [0.2, 0.65, 0.3, 0.9],
+            }}
+          >
+            {unit}
+          </motion.span>
+        )
+      )}
     </div>
   )
 }
@@ -114,8 +161,10 @@ export function WordReveal({
       className={cn("inline-block", className)}
       {...props}
     >
+      <span className="sr-only">{text}</span>
       {words.map((word, i) => (
         <motion.span
+          aria-hidden="true"
           key={`${word}-${i}`}
           className="inline-block"
           initial={{ opacity: 0, y: 20, filter: "blur(10px)" }}

package/registry/effects/typewriter-text/typewriter-text.tsx

@@ -3,6 +3,27 @@
 import * as React from "react"
 import { cn } from "../../../src/lib/utils"
 
+/**
+ * Whether the user asks for reduced motion. It starts false, so the server and
+ * the first client render agree, then follows the setting as it changes.
+ */
+function usePrefersReducedMotion() {
+  const [reduced, setReduced] = React.useState(false)
+  React.useEffect(() => {
+    if (typeof window.matchMedia !== "function") return
+    const query = window.matchMedia("(prefers-reduced-motion: reduce)")
+    setReduced(query.matches)
+    const onChange = () => setReduced(query.matches)
+    query.addEventListener("change", onChange)
+    return () => query.removeEventListener("change", onChange)
+  }, [])
+  return reduced
+}
+
+/** The value, or the fallback when it is missing or blank (a cleared control, say). */
+const filled = (value: string | undefined, fallback: string) =>
+  value && value.trim() ? value : fallback
+
 export interface TypewriterTextProps extends React.HTMLAttributes<HTMLSpanElement> {
   /** Text to type out */
   text: string
@@ -27,34 +48,35 @@ export function TypewriterText({
   speed = 50,
   delay = 0,
   cursor = true,
-  cursorChar = "|",
+  cursorChar: cursorCharProp,
   loop = false,
   loopDelay = 2000,
   onComplete,
   className,
   ...props
 }: TypewriterTextProps) {
+  const cursorChar = filled(cursorCharProp, "|")
   const [displayText, setDisplayText] = React.useState("")
   const [isTyping, setIsTyping] = React.useState(false)
-  const [showCursor, setShowCursor] = React.useState(cursor)
+  const prefersReducedMotion = usePrefersReducedMotion()
+  const showCursor = cursor && !prefersReducedMotion
 
-  // Check for reduced motion preference
-  const prefersReducedMotion = React.useMemo(() => {
-    if (typeof window === "undefined") return false
-    return window.matchMedia("(prefers-reduced-motion: reduce)").matches
-  }, [])
+  // Held in a ref: an inline callback is a new function every render, and as
+  // an effect dependency it restarted the typing each time the parent rendered.
+  const onCompleteRef = React.useRef(onComplete)
+  onCompleteRef.current = onComplete
 
   React.useEffect(() => {
     // If user prefers reduced motion, show full text immediately
     if (prefersReducedMotion) {
       setDisplayText(text)
-      setShowCursor(false)
-      onComplete?.()
+      onCompleteRef.current?.()
       return
     }
 
     let timeoutId: ReturnType<typeof setTimeout>
     let charIndex = 0
+    setDisplayText("")
     setIsTyping(true)
 
     const startTyping = () => {
@@ -65,7 +87,7 @@ export function TypewriterText({
           timeoutId = setTimeout(typeChar, speed)
         } else {
           setIsTyping(false)
-          onComplete?.()
+          onCompleteRef.current?.()
 
           if (loop) {
             timeoutId = setTimeout(() => {
@@ -84,20 +106,20 @@ export function TypewriterText({
     timeoutId = setTimeout(startTyping, delay)
 
     return () => clearTimeout(timeoutId)
-  }, [text, speed, delay, loop, loopDelay, onComplete, prefersReducedMotion])
+  }, [text, speed, delay, loop, loopDelay, prefersReducedMotion])
 
   // Cursor blink effect
   const [cursorVisible, setCursorVisible] = React.useState(true)
 
   React.useEffect(() => {
-    if (!showCursor || prefersReducedMotion) return
+    if (!showCursor) return
 
     const blinkInterval = setInterval(() => {
       setCursorVisible((prev) => !prev)
     }, 530)
 
     return () => clearInterval(blinkInterval)
-  }, [showCursor, prefersReducedMotion])
+  }, [showCursor])
 
   return (
     <span className={cn("inline", className)} {...props}>
@@ -105,7 +127,7 @@ export function TypewriterText({
       {showCursor && (
         <span
           className={cn(
-            "ml-0.5 inline-block",
+            "ms-0.5 inline-block",
             cursorVisible ? "opacity-100" : "opacity-0",
             isTyping ? "" : "animate-pulse"
           )}
@@ -144,10 +166,7 @@ export function TypewriterWords({
   const [displayText, setDisplayText] = React.useState("")
   const [isDeleting, setIsDeleting] = React.useState(false)
 
-  const prefersReducedMotion = React.useMemo(() => {
-    if (typeof window === "undefined") return false
-    return window.matchMedia("(prefers-reduced-motion: reduce)").matches
-  }, [])
+  const prefersReducedMotion = usePrefersReducedMotion()
 
   React.useEffect(() => {
     if (prefersReducedMotion) {
@@ -204,10 +223,10 @@ export function TypewriterWords({
   return (
     <span className={cn("inline", className)} {...props}>
       {displayText}
-      {cursor && (
+      {cursor && !prefersReducedMotion && (
         <span
           className={cn(
-            "ml-0.5 inline-block",
+            "ms-0.5 inline-block",
             cursorVisible ? "opacity-100" : "opacity-0"
           )}
           aria-hidden="true"

package/registry/next14-tsconfig.test.ts

@@ -0,0 +1,43 @@
+// @vitest-environment node
+import { describe, it, expect } from "vitest"
+import { readdirSync } from "node:fs"
+import { join } from "node:path"
+import ts from "typescript"
+
+const registry = __dirname
+
+function sourceFiles(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) return sourceFiles(path)
+    return /\.tsx?$/.test(entry.name) && !/\.(test|stories)\.tsx?$/.test(entry.name) ? [path] : []
+  })
+}
+
+// The compiler options create-next-app@14 writes. It sets no target, so
+// TypeScript falls back to ES5, and syntax that needs ES2015 or later (a u
+// flag on a regex literal, for one) fails `next build`.
+const next14 = {
+  lib: ["lib.dom.d.ts", "lib.dom.iterable.d.ts", "lib.esnext.d.ts"],
+  allowJs: true,
+  skipLibCheck: true,
+  strict: true,
+  noEmit: true,
+  esModuleInterop: true,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  resolveJsonModule: true,
+  isolatedModules: true,
+  jsx: ts.JsxEmit.Preserve,
+}
+
+describe("registry under a Next.js 14 tsconfig", () => {
+  it("type-checks with no target set", () => {
+    const program = ts.createProgram(sourceFiles(registry), next14)
+    const errors = ts.getPreEmitDiagnostics(program).map((d) => {
+      const where = d.file ? `${d.file.fileName.replace(registry, "registry")}:${d.file.getLineAndCharacterOfPosition(d.start ?? 0).line + 1}` : ""
+      return `${where} TS${d.code} ${ts.flattenDiagnosticMessageText(d.messageText, " ")}`
+    })
+    expect(errors).toEqual([])
+  }, 60_000)
+})

package/registry/text-props-undefined.test.tsx

@@ -0,0 +1,73 @@
+import { describe, it, expect } from "vitest"
+import { render, screen } from "@testing-library/react"
+import { Pagination } from "./blocks/data-table/DataTable"
+import { EmptySearchResults, EmptyData } from "./blocks/empty-state"
+import { PageHeader } from "./blocks/page-header/PageHeader"
+import { Button } from "./ui/button"
+import { Combobox } from "./ui/combobox"
+
+/**
+ * Every optional text prop added for translation falls back to its English
+ * default when a caller passes it explicitly as undefined, as a translation
+ * lookup that misses a key does.
+ */
+describe("text props passed as undefined keep their English default", () => {
+  it("Pagination", () => {
+    render(
+      <Pagination
+        page={2}
+        totalPages={5}
+        onPageChange={() => {}}
+        labels={{
+          pagination: undefined,
+          status: undefined,
+          previous: undefined,
+          next: undefined,
+          goToPrevious: undefined,
+          goToNext: undefined,
+          goToPage: undefined,
+        }}
+      />
+    )
+    expect(screen.getByRole("navigation", { name: "Pagination" })).toBeTruthy()
+    expect(screen.getByText("Page 2 of 5")).toBeTruthy()
+    expect(screen.getByRole("button", { name: "Go to previous page" }).textContent).toBe("Previous")
+    expect(screen.getByRole("button", { name: "Go to page 3" })).toBeTruthy()
+  })
+
+  it("EmptySearchResults", () => {
+    render(<EmptySearchResults query="linen" title={undefined} description={undefined} />)
+    expect(screen.getByText("No results found")).toBeTruthy()
+    expect(screen.getByText('No results for "linen". Try a different search term.')).toBeTruthy()
+  })
+
+  it("EmptyData", () => {
+    render(<EmptyData resourceName="orders" title={undefined} description={undefined} />)
+    expect(screen.getByText("No orders yet")).toBeTruthy()
+    expect(screen.getByText("Get started by creating your first order.")).toBeTruthy()
+  })
+
+  it("PageHeader", () => {
+    render(<PageHeader title="Orders" breadcrumb={<a href="/">Home</a>} breadcrumbLabel={undefined} />)
+    expect(screen.getByRole("navigation", { name: "Breadcrumb" })).toBeTruthy()
+  })
+
+  it("Button", () => {
+    render(<Button loading loadingLabel={undefined}>Save</Button>)
+    expect(screen.getByText("Loading")).toBeTruthy()
+  })
+
+  it("Combobox", () => {
+    render(
+      <Combobox
+        options={[]}
+        loading
+        loadingText={undefined}
+        openLabel={undefined}
+        closeLabel={undefined}
+        removeLabel={undefined}
+      />
+    )
+    expect(screen.getByRole("button", { name: "Open" })).toBeTruthy()
+  })
+})