@a4ui/core 0.13.0 → 0.14.0

package/dist/ui/NotificationStack.d.ts

@@ -8,23 +8,23 @@ export interface StackNotification {
 export interface NotificationStackProps {
     /** Newest first. The parent owns this array. */
     items: StackNotification[];
-    /** How many cards are visible before the rest collapse behind. @default 3 */
+    /** How many cards peek when collapsed. @default 3 */
     max?: number;
     /** Fired when a card is dismissed; the parent should drop it from `items`. */
     onDismiss?: (id: string | number) => void;
     class?: string;
 }
 /**
- * Stacked notifications. Cards behind the front one are offset down and scaled,
- * so they peek from the bottom edge; removing the front card promotes the rest
- * with a smooth transition (skipped under reduced motion). New cards fade/slide
- * in via `animateIn`.
+ * Stacked notifications. Collapsed, cards behind the front one are offset down
+ * and scaled so they peek from the bottom edge; click the stack to expand every
+ * notification into a scrollable list, and "Show less" to collapse. Removing the
+ * front card promotes the rest; new cards fade/slide in via `animateIn`.
  *
  * @example
  * ```tsx
- * const [items, setItems] = createStore<StackNotification[]>([])
+ * const [items, setItems] = createSignal<StackNotification[]>([])
  * <NotificationStack
- *   items={items}
+ *   items={items()}
  *   onDismiss={(id) => setItems((xs) => xs.filter((x) => x.id !== id))}
  * />
  * ```

package/dist/ui/Ripple.d.ts

@@ -0,0 +1,25 @@
+import { JSX } from 'solid-js';
+export interface RippleProps {
+    children: JSX.Element;
+    /** Ripple color (CSS color). @default 'currentColor' */
+    color?: string;
+    /** Ripple opacity 0..1. @default 0.3 */
+    opacity?: number;
+    class?: string;
+}
+/**
+ * Wraps `children` in a `position: relative; overflow: hidden` layer that
+ * spawns a Material-style ripple — a circle centered on the pointer's down
+ * position, sized to cover the wrapped content, expanding and fading out —
+ * on every `pointerdown`. Rapid clicks stack multiple ripples; each removes
+ * itself once its animation finishes. A no-op under reduced motion: children
+ * still render, but no ripple ever spawns.
+ *
+ * @example
+ * ```tsx
+ * <Ripple color="white" opacity={0.25}>
+ *   <button class="rounded-lg bg-primary px-4 py-2 text-primary-foreground">Save</button>
+ * </Ripple>
+ * ```
+ */
+export declare function Ripple(props: RippleProps): JSX.Element;

package/dist/ui/Typewriter.d.ts

@@ -0,0 +1,28 @@
+import { JSX } from 'solid-js';
+export interface TypewriterProps {
+    /** The full string (or strings, cycled) to type out. */
+    text: string | string[];
+    /** ms per character. @default 55 */
+    speed?: number;
+    /** ms to pause on a completed string before deleting (only when `text` is an array). @default 1400 */
+    pause?: number;
+    /** Show a blinking caret. @default true */
+    caret?: boolean;
+    /** Loop through the array forever. @default true when text is an array */
+    loop?: boolean;
+    class?: string;
+}
+/**
+ * Types `text` out one character at a time, like a terminal. When `text` is
+ * an array, each string types in, holds for `pause` ms, then deletes before
+ * the next one types in — cycling forever unless `loop` is `false` (defaults
+ * to looping only when there's more than one string). Shows the first (or
+ * only) string statically, with no typing and no caret blink, when the user
+ * prefers reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <Typewriter text={['Building things…', 'Shipping things…']} speed={40} />
+ * ```
+ */
+export declare function Typewriter(props: TypewriterProps): JSX.Element;

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@a4ui/core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "A4ui — Spatial Glass design system & component library for SolidJS (Kobalte behavior + Tailwind glass tokens + motion).",
   "type": "module",
   "license": "MIT",
   "author": "Luis Alfredo Rivera Acuña <1alfredorivera@gmail.com>",
-  "homepage": "https://a4uikit.github.io/a4ui/",
+  "homepage": "https://a4ui.pages.dev/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/A4uikit/a4ui.git"
@@ -29,10 +29,16 @@
   ],
   "files": [
     "dist",
-    "src",
+    "preset.js",
+    "src/index.ts",
+    "src/ui",
+    "src/lib",
+    "src/layout",
+    "src/themes",
+    "src/commerce",
+    "src/charts",
     "!src/**/*.test.ts",
-    "!src/**/*.test.tsx",
-    "preset.js"
+    "!src/**/*.test.tsx"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -72,10 +78,12 @@
   "engines": {
     "node": ">=20"
   },
+  "packageManager": "npm@10.9.3",
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
+    "prebuild": "node scripts/sync-version.mjs",
     "build": "vite build && npm run build:elements",
     "build:elements": "vite build --config vite.elements.config.ts && node scripts/build-elements-css.mjs",
     "dev": "vite build --watch",
@@ -92,7 +100,7 @@
     "test:a11y": "playwright test a11y --project=desktop",
     "test:report": "playwright show-report",
     "test:package": "node scripts/test-package.mjs",
-    "validate": "npm run typecheck && npm run lint && npm run test:unit && npm run build",
+    "validate": "npm run typecheck && npm run lint && npm run format:check && npm run test:unit && npm run build && npm run test:package",
     "prepublishOnly": "npm run validate",
     "prepare": "husky"
   },

package/src/index.ts

@@ -8,7 +8,7 @@
 //   import '@a4ui/core/styles.css'
 //   import { Button, Card, Modal } from '@a4ui/core'
 
-export const A4UI_VERSION = '0.13.0'
+export const A4UI_VERSION = '0.14.0'
 
 // Helpers (src/lib) — generic, framework-level utilities.
 export { cn } from './lib/cn'
@@ -149,6 +149,8 @@ export {
 export { MultiStateBadge, type MultiStateBadgeProps, type BadgeState } from './ui/MultiStateBadge'
 export { NowPlaying, type NowPlayingProps } from './ui/NowPlaying'
 export { Expandable, type ExpandableProps } from './ui/Expandable'
+export { Typewriter, type TypewriterProps } from './ui/Typewriter'
+export { Ripple, type RippleProps } from './ui/Ripple'
 export { flyToCart, type FlyToCartOptions } from './lib/flyToCart'
 
 // Layout (src/layout) — generic shell + backdrop + toggles. App-coupled pieces

package/src/ui/NotificationStack.tsx

@@ -1,8 +1,9 @@
-// A stacked-notifications widget (phone lock-screen style): the newest card is
-// full-size on top and older cards peek out behind it, scaled down and offset.
-// Presentational + controlled — the parent owns `items` (newest first) and
-// removes a card when `onDismiss` fires; the stack re-flows with a CSS transition.
-import { For, type JSX } from 'solid-js'
+// A stacked-notifications widget (phone lock-screen style): collapsed, the
+// newest card is full-size on top and older ones peek out behind it, scaled
+// down and offset. Click the stack (or "Show all") to EXPAND it into a full,
+// scrollable list; "Show less" collapses it back. Presentational + controlled —
+// the parent owns `items` (newest first) and removes a card on `onDismiss`.
+import { createSignal, For, Show, type JSX } from 'solid-js'
 
 import { cn } from '../lib/cn'
 import { animateIn, motionReduced } from '../lib/motion'
@@ -17,7 +18,7 @@ export interface StackNotification {
 export interface NotificationStackProps {
   /** Newest first. The parent owns this array. */
   items: StackNotification[]
-  /** How many cards are visible before the rest collapse behind. @default 3 */
+  /** How many cards peek when collapsed. @default 3 */
   max?: number
   /** Fired when a card is dismissed; the parent should drop it from `items`. */
   onDismiss?: (id: string | number) => void
@@ -25,80 +26,114 @@ export interface NotificationStackProps {
 }
 
 /**
- * Stacked notifications. Cards behind the front one are offset down and scaled,
- * so they peek from the bottom edge; removing the front card promotes the rest
- * with a smooth transition (skipped under reduced motion). New cards fade/slide
- * in via `animateIn`.
+ * Stacked notifications. Collapsed, cards behind the front one are offset down
+ * and scaled so they peek from the bottom edge; click the stack to expand every
+ * notification into a scrollable list, and "Show less" to collapse. Removing the
+ * front card promotes the rest; new cards fade/slide in via `animateIn`.
  *
  * @example
  * ```tsx
- * const [items, setItems] = createStore<StackNotification[]>([])
+ * const [items, setItems] = createSignal<StackNotification[]>([])
  * <NotificationStack
- *   items={items}
+ *   items={items()}
  *   onDismiss={(id) => setItems((xs) => xs.filter((x) => x.id !== id))}
  * />
  * ```
  */
 export function NotificationStack(props: NotificationStackProps): JSX.Element {
   const max = () => props.max ?? 3
+  const [expanded, setExpanded] = createSignal(false)
+  const canExpand = () => props.items.length > 1
 
   return (
-    <div
-      role="log"
-      aria-live="polite"
-      class={cn('relative w-full max-w-sm', props.class)}
-      // reserve room for the front card plus the peek of those behind it
-      style={{ 'min-height': `${88 + (Math.min(props.items.length, max()) - 1) * 10}px` }}
-    >
-      <For each={props.items}>
-        {(item, i) => {
-          const hidden = () => i() > max() - 1
-          return (
-            <div
-              ref={(el) => animateIn(el, { y: -8 })}
-              class={cn(
-                'card absolute inset-x-0 top-0 rounded-xl border border-border bg-card p-3 shadow-lg',
-                !motionReduced() && 'transition-[transform,opacity] duration-300 ease-out',
-              )}
-              style={{
-                transform: `translateY(${i() * 10}px) scale(${1 - i() * 0.05})`,
-                opacity: hidden() ? 0 : 1 - i() * 0.15,
-                'z-index': props.items.length - i(),
-                'pointer-events': hidden() ? 'none' : 'auto',
-                'transform-origin': 'top center',
-              }}
-            >
-              <div class="flex items-start gap-2.5">
-                {item.icon && <span class="mt-0.5 shrink-0 text-primary">{item.icon}</span>}
-                <div class="min-w-0 flex-1">
-                  <p class="truncate text-sm font-medium text-foreground">{item.title}</p>
-                  {item.description && (
-                    <p class="mt-0.5 line-clamp-2 text-sm text-muted-foreground">{item.description}</p>
-                  )}
-                </div>
-                <button
-                  type="button"
-                  aria-label={`Dismiss ${item.title}`}
-                  onClick={() => props.onDismiss?.(item.id)}
-                  class="shrink-0 rounded-md p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
-                >
-                  <svg
-                    viewBox="0 0 24 24"
-                    class="h-3.5 w-3.5"
-                    fill="none"
-                    stroke="currentColor"
-                    stroke-width="2.5"
-                    stroke-linecap="round"
-                    aria-hidden="true"
+    <div role="log" aria-live="polite" class={cn('w-full max-w-sm', props.class)}>
+      <div
+        class={cn(
+          expanded()
+            ? 'max-h-[60vh] space-y-2 overflow-y-auto pr-1'
+            : cn('relative', canExpand() && 'cursor-pointer'),
+        )}
+        style={
+          expanded()
+            ? undefined
+            : // reserve room for the front card plus the peek of those behind it
+              { 'min-height': `${88 + (Math.min(props.items.length, max()) - 1) * 10}px` }
+        }
+        onClick={() => {
+          if (!expanded() && canExpand()) setExpanded(true)
+        }}
+      >
+        <For each={props.items}>
+          {(item, i) => {
+            const collapsedHidden = () => !expanded() && i() > max() - 1
+            return (
+              <div
+                ref={(el) => animateIn(el, { y: -8 })}
+                class={cn(
+                  'card rounded-xl border border-border bg-card p-3 shadow-lg',
+                  expanded() ? 'relative' : 'absolute inset-x-0 top-0',
+                  !motionReduced() && !expanded() && 'transition-[transform,opacity] duration-300 ease-out',
+                )}
+                style={
+                  expanded()
+                    ? undefined
+                    : {
+                        transform: `translateY(${i() * 10}px) scale(${1 - i() * 0.05})`,
+                        opacity: collapsedHidden() ? 0 : 1 - i() * 0.15,
+                        'z-index': props.items.length - i(),
+                        'pointer-events': collapsedHidden() ? 'none' : 'auto',
+                        'transform-origin': 'top center',
+                      }
+                }
+              >
+                <div class="flex items-start gap-2.5">
+                  {item.icon && <span class="mt-0.5 shrink-0 text-primary">{item.icon}</span>}
+                  <div class="min-w-0 flex-1">
+                    <p class={cn('text-sm font-medium text-foreground', !expanded() && 'truncate')}>
+                      {item.title}
+                    </p>
+                    {item.description && (
+                      <p class="mt-0.5 line-clamp-2 text-sm text-muted-foreground">{item.description}</p>
+                    )}
+                  </div>
+                  <button
+                    type="button"
+                    aria-label={`Dismiss ${item.title}`}
+                    onClick={(e) => {
+                      e.stopPropagation()
+                      props.onDismiss?.(item.id)
+                    }}
+                    class="shrink-0 rounded-md p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
                   >
-                    <path d="M6 6l12 12M18 6L6 18" />
-                  </svg>
-                </button>
+                    <svg
+                      viewBox="0 0 24 24"
+                      class="h-3.5 w-3.5"
+                      fill="none"
+                      stroke="currentColor"
+                      stroke-width="2.5"
+                      stroke-linecap="round"
+                      aria-hidden="true"
+                    >
+                      <path d="M6 6l12 12M18 6L6 18" />
+                    </svg>
+                  </button>
+                </div>
               </div>
-            </div>
-          )
-        }}
-      </For>
+            )
+          }}
+        </For>
+      </div>
+
+      <Show when={canExpand()}>
+        <button
+          type="button"
+          aria-expanded={expanded()}
+          onClick={() => setExpanded((v) => !v)}
+          class="mt-2 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground"
+        >
+          {expanded() ? 'Show less' : `Show all ${props.items.length}`}
+        </button>
+      </Show>
     </div>
   )
 }

package/src/ui/Ripple.tsx

@@ -0,0 +1,119 @@
+// Material-style click ripple: a wrapper that spawns an expanding, fading
+// circle from the pointer's down position on every `pointerdown` — Motion's
+// `animate` drives the scale/opacity tween since each ripple is a one-shot
+// spawn-then-discard element, not a persistent CSS transition. `x`/`y` are
+// animated to a constant -50% alongside `scale` so Motion (which owns the
+// element's `transform` once it's animating any transform sub-property)
+// composes `translate(-50%,-50%) scale(...)` itself rather than clobbering a
+// translate we'd otherwise have set by hand via inline style.
+import { createSignal, For, onCleanup, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+export interface RippleProps {
+  children: JSX.Element
+  /** Ripple color (CSS color). @default 'currentColor' */
+  color?: string
+  /** Ripple opacity 0..1. @default 0.3 */
+  opacity?: number
+  class?: string
+}
+
+interface RippleInstance {
+  id: number
+  x: number
+  y: number
+  size: number
+}
+
+let nextRippleId = 0
+
+/**
+ * Wraps `children` in a `position: relative; overflow: hidden` layer that
+ * spawns a Material-style ripple — a circle centered on the pointer's down
+ * position, sized to cover the wrapped content, expanding and fading out —
+ * on every `pointerdown`. Rapid clicks stack multiple ripples; each removes
+ * itself once its animation finishes. A no-op under reduced motion: children
+ * still render, but no ripple ever spawns.
+ *
+ * @example
+ * ```tsx
+ * <Ripple color="white" opacity={0.25}>
+ *   <button class="rounded-lg bg-primary px-4 py-2 text-primary-foreground">Save</button>
+ * </Ripple>
+ * ```
+ */
+export function Ripple(props: RippleProps): JSX.Element {
+  const [ripples, setRipples] = createSignal<RippleInstance[]>([])
+  const active = new Set<ReturnType<typeof animate>>()
+
+  let containerEl: HTMLSpanElement | undefined
+
+  const remove = (id: number): void => {
+    setRipples((current) => current.filter((ripple) => ripple.id !== id))
+  }
+
+  const spawnAnimation = (el: HTMLSpanElement, id: number, opacity: number): void => {
+    const controls = animate(
+      el,
+      { x: ['-50%', '-50%'], y: ['-50%', '-50%'], scale: [0, 1], opacity: [opacity, 0] },
+      { duration: 0.6, ease: 'easeOut' },
+    )
+    active.add(controls)
+    controls.finished
+      .then(() => {
+        active.delete(controls)
+        remove(id)
+      })
+      .catch(() => {})
+  }
+
+  const handlePointerDown = (event: PointerEvent): void => {
+    if (motionReduced() || !containerEl) return
+
+    const rect = containerEl.getBoundingClientRect()
+    const x = event.clientX - rect.left
+    const y = event.clientY - rect.top
+    const maxDist = Math.max(
+      Math.hypot(x, y),
+      Math.hypot(rect.width - x, y),
+      Math.hypot(x, rect.height - y),
+      Math.hypot(rect.width - x, rect.height - y),
+    )
+
+    setRipples((current) => [...current, { id: nextRippleId++, x, y, size: maxDist * 2 }])
+  }
+
+  onCleanup(() => {
+    active.forEach((controls) => controls.stop())
+    active.clear()
+  })
+
+  return (
+    <span
+      ref={containerEl}
+      class={cn('relative inline-block overflow-hidden', props.class)}
+      onPointerDown={handlePointerDown}
+    >
+      {props.children}
+      <span aria-hidden="true" class="pointer-events-none absolute inset-0">
+        <For each={ripples()}>
+          {(ripple) => (
+            <span
+              ref={(el) => spawnAnimation(el, ripple.id, props.opacity ?? 0.3)}
+              class="absolute rounded-full"
+              style={{
+                left: `${ripple.x}px`,
+                top: `${ripple.y}px`,
+                width: `${ripple.size}px`,
+                height: `${ripple.size}px`,
+                background: props.color ?? 'currentColor',
+              }}
+            />
+          )}
+        </For>
+      </span>
+    </span>
+  )
+}

package/src/ui/Typewriter.tsx

@@ -0,0 +1,149 @@
+// Terminal-style text reveal: characters appear one at a time via a plain
+// setTimeout loop (not a CSS transition, since each character is a discrete
+// reveal step, not a tween). Accepts a single string or an array to cycle
+// through — type, pause, delete, type the next — with an optional blinking
+// caret, whose keyframe is injected once into the document head (mirroring
+// LoadingDots's approach to a component-scoped CSS animation).
+import { createSignal, onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface TypewriterProps {
+  /** The full string (or strings, cycled) to type out. */
+  text: string | string[]
+  /** ms per character. @default 55 */
+  speed?: number
+  /** ms to pause on a completed string before deleting (only when `text` is an array). @default 1400 */
+  pause?: number
+  /** Show a blinking caret. @default true */
+  caret?: boolean
+  /** Loop through the array forever. @default true when text is an array */
+  loop?: boolean
+  class?: string
+}
+
+const STYLE_ID = 'a4ui-typewriter-style'
+
+function ensureStyleInjected(): void {
+  if (typeof document === 'undefined' || document.getElementById(STYLE_ID)) return
+  const style = document.createElement('style')
+  style.id = STYLE_ID
+  style.textContent = `
+@keyframes a4-caret-blink {
+  0%, 49% { opacity: 1; }
+  50%, 100% { opacity: 0; }
+}
+`
+  document.head.appendChild(style)
+}
+
+function toList(text: string | string[]): string[] {
+  return Array.isArray(text) ? text : [text]
+}
+
+/**
+ * Types `text` out one character at a time, like a terminal. When `text` is
+ * an array, each string types in, holds for `pause` ms, then deletes before
+ * the next one types in — cycling forever unless `loop` is `false` (defaults
+ * to looping only when there's more than one string). Shows the first (or
+ * only) string statically, with no typing and no caret blink, when the user
+ * prefers reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <Typewriter text={['Building things…', 'Shipping things…']} speed={40} />
+ * ```
+ */
+export function Typewriter(props: TypewriterProps): JSX.Element {
+  ensureStyleInjected()
+
+  // eslint-disable-next-line solid/reactivity -- one-time seed; run() re-reads props.text on each (re)start
+  const [display, setDisplay] = createSignal(motionReduced() ? (toList(props.text)[0] ?? '') : '')
+
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  const stop = (): void => {
+    if (timer === undefined) return
+    clearTimeout(timer)
+    timer = undefined
+  }
+
+  const run = (): void => {
+    stop()
+    const list = toList(props.text)
+    const first = list[0] ?? ''
+
+    if (motionReduced() || list.length === 0) {
+      setDisplay(first)
+      return
+    }
+
+    const speed = props.speed ?? 55
+    const pause = props.pause ?? 1400
+    const shouldLoop = props.loop ?? list.length > 1
+
+    let stringIndex = 0
+    let charIndex = 0
+    let phase: 'typing' | 'pausing' | 'deleting' = 'typing'
+
+    const step = (): void => {
+      const text = list[stringIndex] ?? ''
+
+      if (phase === 'typing') {
+        charIndex += 1
+        setDisplay(text.slice(0, charIndex))
+        if (charIndex >= text.length) {
+          const isLastString = stringIndex >= list.length - 1
+          if (list.length <= 1 || (isLastString && !shouldLoop)) {
+            stop()
+            return
+          }
+          phase = 'pausing'
+          timer = setTimeout(step, pause)
+          return
+        }
+        timer = setTimeout(step, speed)
+        return
+      }
+
+      if (phase === 'pausing') {
+        phase = 'deleting'
+        timer = setTimeout(step, speed)
+        return
+      }
+
+      // deleting
+      charIndex -= 1
+      setDisplay(text.slice(0, Math.max(0, charIndex)))
+      if (charIndex <= 0) {
+        stringIndex = (stringIndex + 1) % list.length
+        phase = 'typing'
+      }
+      timer = setTimeout(step, speed)
+    }
+
+    setDisplay('')
+    timer = setTimeout(step, speed)
+  }
+
+  onMount(run)
+  onCleanup(stop)
+
+  const showCaret = (): boolean => (props.caret ?? true) && !motionReduced()
+
+  return (
+    <span class={cn('font-mono', props.class)}>
+      {display()}
+      {showCaret() && (
+        <span
+          aria-hidden="true"
+          class="inline-block"
+          style={{ animation: 'a4-caret-blink 1s step-end infinite' }}
+        >
+          |
+        </span>
+      )}
+    </span>
+  )
+}