@a4ui/core 0.13.1 → 0.14.0

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.1",
+  "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.1'
+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/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>
+  )
+}

package/src/elements.tsx

@@ -1,167 +0,0 @@
-// Web Components entry (`@a4ui/core/elements`) — a curated subset of A4ui's
-// presentational components registered as framework-agnostic custom elements so
-// they can be used from React/Next.js, Vue, Svelte, or plain HTML.
-//
-// Design notes:
-// - Each element renders in LIGHT DOM (noShadowDOM) so the global stylesheet
-//   (`@a4ui/core/elements.css`) and CSS theme variables apply normally — Shadow
-//   DOM would isolate the Tailwind utility classes the components rely on.
-// - Props map to attributes/properties (solid-element coerces by the declared
-//   default's type: number/boolean/string). Text content is taken from a `label`
-//   or `text` attribute, falling back to the element's initial text.
-// - Only leaf, primitive-prop components are wrapped. Rich/interactive/portalled
-//   components (Modal, Combobox, DataGrid, …) remain SolidJS-only — see the docs.
-//
-// This bundle is self-contained (solid-js is bundled in), so non-Solid apps need
-// no Solid toolchain: `import '@a4ui/core/elements'` once, then use the tags.
-import { customElement, noShadowDOM } from 'solid-element'
-import type { JSX } from 'solid-js'
-
-import { Alert, type AlertTone } from './ui/Alert'
-import { Avatar } from './ui/Avatar'
-import { Badge, type BadgeTone } from './ui/Badge'
-import { Button, type ButtonVariant } from './ui/Button'
-import { Clock } from './ui/Clock'
-import { Countdown } from './ui/Countdown'
-import { Kbd } from './ui/Kbd'
-import { Meter } from './ui/Meter'
-import { Progress } from './ui/Progress'
-import { Rating } from './ui/Rating'
-import { RingProgress } from './ui/RingProgress'
-import { Separator } from './ui/Separator'
-import { Spinner } from './ui/Spinner'
-import { Stat, type StatTone } from './ui/Stat'
-
-/** The initial text an author put between the tags, before Solid renders over it. */
-function initialText(element: unknown): string {
-  return ((element as HTMLElement).textContent ?? '').trim()
-}
-
-/** Register every A4ui custom element. Import for its side effect. */
-export function defineA4uiElements(): void {
-  customElement(
-    'a4-button',
-    { variant: 'primary', disabled: false, type: 'button', label: '' },
-    (props, { element }): JSX.Element => {
-      noShadowDOM()
-      const text = props.label || initialText(element)
-      return (
-        <Button
-          variant={props.variant as ButtonVariant}
-          disabled={props.disabled}
-          type={props.type as 'button' | 'submit' | 'reset'}
-        >
-          {text}
-        </Button>
-      )
-    },
-  )
-
-  customElement('a4-badge', { tone: 'neutral', label: '' }, (props, { element }): JSX.Element => {
-    noShadowDOM()
-    return <Badge tone={props.tone as BadgeTone}>{props.label || initialText(element)}</Badge>
-  })
-
-  customElement(
-    // `heading`, not `title` — the latter is a global HTML attribute and would
-    // clash with the element's native `title` (tooltip) property.
-    'a4-alert',
-    { tone: 'info', heading: '', text: '' },
-    (props, { element }): JSX.Element => {
-      noShadowDOM()
-      return (
-        <Alert tone={props.tone as AlertTone} title={props.heading || undefined}>
-          {props.text || initialText(element)}
-        </Alert>
-      )
-    },
-  )
-
-  customElement('a4-spinner', { label: 'Loading' }, (props): JSX.Element => {
-    noShadowDOM()
-    return <Spinner label={props.label} />
-  })
-
-  customElement('a4-avatar', { src: '', alt: '', fallback: '' }, (props): JSX.Element => {
-    noShadowDOM()
-    return <Avatar src={props.src || undefined} alt={props.alt} fallback={props.fallback || ''} />
-  })
-
-  customElement('a4-progress', { value: 0, max: 100, label: '' }, (props): JSX.Element => {
-    noShadowDOM()
-    return <Progress value={props.value} max={props.max} label={props.label || undefined} />
-  })
-
-  customElement('a4-meter', { value: 0, max: 100, label: '' }, (props): JSX.Element => {
-    noShadowDOM()
-    return <Meter value={props.value} max={props.max} label={props.label || undefined} />
-  })
-
-  customElement('a4-ring-progress', { value: 0, size: 96, thickness: 8, label: '' }, (props): JSX.Element => {
-    noShadowDOM()
-    return (
-      <RingProgress
-        value={props.value}
-        size={props.size}
-        thickness={props.thickness}
-        label={props.label || undefined}
-      />
-    )
-  })
-
-  customElement('a4-stat', { label: '', value: 0, tone: 'neutral' }, (props): JSX.Element => {
-    noShadowDOM()
-    return <Stat label={props.label} value={props.value} tone={props.tone as StatTone} />
-  })
-
-  customElement('a4-kbd', { label: '' }, (props, { element }): JSX.Element => {
-    noShadowDOM()
-    return <Kbd>{props.label || initialText(element)}</Kbd>
-  })
-
-  customElement('a4-separator', { orientation: 'horizontal' }, (props): JSX.Element => {
-    noShadowDOM()
-    return <Separator orientation={props.orientation as 'horizontal' | 'vertical'} />
-  })
-
-  customElement('a4-rating', { value: 0, max: 5, readonly: false }, (props, { element }): JSX.Element => {
-    noShadowDOM()
-    return (
-      <Rating
-        value={props.value}
-        max={props.max}
-        readonly={props.readonly}
-        onChange={(v) =>
-          (element as unknown as HTMLElement).dispatchEvent(new CustomEvent('change', { detail: v }))
-        }
-      />
-    )
-  })
-
-  customElement('a4-countdown', { to: '' }, (props): JSX.Element => {
-    noShadowDOM()
-    // eslint-disable-next-line solid/reactivity -- read the `to` attribute once to fix the target
-    const target = props.to ? new Date(props.to) : new Date(Date.now() + 86_400_000)
-    return <Countdown to={target} />
-  })
-
-  customElement(
-    'a4-clock',
-    { variant: 'digital', seconds: true, hour12: false, timezone: '', size: 160 },
-    (props): JSX.Element => {
-      noShadowDOM()
-      return (
-        <Clock
-          variant={props.variant as 'digital' | 'analog'}
-          seconds={props.seconds}
-          hour12={props.hour12}
-          timeZone={props.timezone || undefined}
-          size={props.size}
-        />
-      )
-    },
-  )
-}
-
-// Registering on import is the ergonomic default for `import '@a4ui/core/elements'`.
-defineA4uiElements()