@smicolon/fasla-ui 0.2.4 → 0.3.0

package/registry/effects/shimmer-button/shimmer-button.tsx

@@ -8,7 +8,7 @@ export interface ShimmerButtonProps
   extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   /** Shimmer color */
   shimmerColor?: string
-  /** Shimmer size in pixels */
+  /** Width of the sheen, as any CSS length or percentage of the button */
   shimmerSize?: string
   /** Border radius */
   borderRadius?: string
@@ -18,6 +18,26 @@ export interface ShimmerButtonProps
   background?: string
 }
 
+/** 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
+
+const DEFAULTS = {
+  // primary-foreground, not primary: a primary sheen on the primary background is invisible
+  shimmerColor: "color-mix(in oklch, var(--primary-foreground) 35%, transparent)",
+  shimmerSize: "100%",
+  shimmerDuration: "2s",
+  borderRadius: "0.5rem",
+  background: "var(--primary)",
+}
+
+const SHIMMER_KEYFRAMES = `
+  @keyframes fasla-shimmer {
+    from { transform: translateX(-100%); }
+    to { transform: translateX(100%); }
+  }
+`
+
 /**
  * A button with an animated shimmer effect.
  * The shimmer respects prefers-reduced-motion.
@@ -28,11 +48,11 @@ export const ShimmerButton = React.forwardRef<
 >(
   (
     {
-      shimmerColor = "hsl(var(--primary) / 0.2)",
-      shimmerSize = "0.1em",
-      shimmerDuration = "2s",
-      borderRadius = "0.5rem",
-      background = "hsl(var(--primary))",
+      shimmerColor,
+      shimmerSize,
+      shimmerDuration,
+      borderRadius,
+      background,
       className,
       children,
       ...props
@@ -45,40 +65,59 @@ export const ShimmerButton = React.forwardRef<
       <button
         ref={ref}
         className={cn(
-          "group relative inline-flex h-10 items-center justify-center overflow-hidden whitespace-nowrap px-6 py-2 text-sm font-medium text-primary-foreground transition-all hover:scale-105 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+          "group relative inline-flex h-10 items-center justify-center overflow-hidden whitespace-nowrap px-6 py-2 text-sm font-medium text-primary-foreground transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+          // Plain hover, gated in JS rather than with a stacked motion-safe
+          // hover variant: Storybook's pseudo-states addon rewrites that
+          // stacked rule into invalid CSS and throws. Tailwind reads comments
+          // too, so the stacked class name must not appear here either.
+          !prefersReducedMotion && "hover:scale-105",
           className
         )}
         style={
           {
-            "--shimmer-color": shimmerColor,
-            "--shimmer-size": shimmerSize,
-            "--shimmer-duration": shimmerDuration,
-            "--border-radius": borderRadius,
-            "--background": background,
+            // A blank value (a cleared control, say) falls back to the default
+            // rather than emptying the variable, which would hide the sheen,
+            // stop it, square the corners or clear the background.
+            "--shimmer-color": filled(shimmerColor, DEFAULTS.shimmerColor),
+            "--shimmer-size": filled(shimmerSize, DEFAULTS.shimmerSize),
+            "--shimmer-duration": filled(shimmerDuration, DEFAULTS.shimmerDuration),
+            "--border-radius": filled(borderRadius, DEFAULTS.borderRadius),
+            "--background": filled(background, DEFAULTS.background),
             borderRadius: "var(--border-radius)",
             background: "var(--background)",
           } as React.CSSProperties
         }
         {...props}
       >
-        {/* Shimmer effect */}
+        {/* Shimmer effect: mirrored in RTL so it sweeps in the reading direction */}
         {!prefersReducedMotion && (
           <div
-            className="absolute inset-0 overflow-hidden"
+            aria-hidden="true"
+            className="pointer-events-none absolute inset-0 overflow-hidden rtl:-scale-x-100"
             style={{ borderRadius: "var(--border-radius)" }}
           >
+            {/*
+              The keyframes ship with the component, so it animates without any
+              Tailwind config. The track is the button's width and travels from
+              fully before it to fully after it; the sheen sits at its centre.
+            */}
+            <style dangerouslySetInnerHTML={{ __html: SHIMMER_KEYFRAMES }} />
             <div
-              className="animate-shimmer absolute inset-0 -translate-x-full"
+              className="absolute inset-0 flex justify-center"
               style={{
-                background: `linear-gradient(
-                  90deg,
-                  transparent 0%,
-                  var(--shimmer-color) 50%,
-                  transparent 100%
-                )`,
-                animationDuration: "var(--shimmer-duration)",
+                transform: "translateX(-100%)",
+                animation: "fasla-shimmer var(--shimmer-duration) ease-in-out infinite",
               }}
-            />
+            >
+              <div
+                className="h-full shrink-0"
+                style={{
+                  width: "var(--shimmer-size)",
+                  background:
+                    "linear-gradient(90deg, transparent 0%, var(--shimmer-color) 50%, transparent 100%)",
+                }}
+              />
+            </div>
           </div>
         )}
 

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,42 @@ 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.
+  return text.match(/\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 +67,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 +83,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 +159,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"