@a4ui/core 0.33.0 → 0.35.0

package/src/ui/MaskedInput.tsx

@@ -0,0 +1,108 @@
+import type { JSX } from 'solid-js'
+import { createEffect, createSignal, splitProps } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+const INPUT_BASE =
+  'w-full rounded-md border border-border bg-card text-foreground placeholder:text-muted-foreground px-3 py-2 text-sm outline-none transition-colors focus-visible:ring-2 focus-visible:ring-ring focus-visible:border-ring disabled:cursor-not-allowed disabled:opacity-50'
+
+export interface MaskedInputProps {
+  /** `#` = digit slot, `A` = letter slot, any other char is a literal, e.g. `'(###) ###-####'`. */
+  mask: string
+  /** Controlled raw value (just the entered #/A characters, no literals). */
+  value?: string
+  /** Called with `(raw, formatted)` on every accepted keystroke or paste. */
+  onInput?: (raw: string, formatted: string) => void
+  placeholder?: string
+  class?: string
+  'aria-label'?: string
+}
+
+const matchesSlot = (mask: string, i: number, char: string): boolean => {
+  const slot = mask[i]
+  if (slot === '#') return /[0-9]/.test(char)
+  if (slot === 'A') return /[a-zA-Z]/.test(char)
+  return false
+}
+
+const isLiteral = (mask: string, i: number): boolean => mask[i] !== '#' && mask[i] !== 'A'
+
+/** Build the formatted string for a mask given only the raw slot characters. */
+const format = (mask: string, raw: string): string => {
+  let out = ''
+  let r = 0
+  for (let i = 0; i < mask.length && r < raw.length; i++) {
+    if (isLiteral(mask, i)) {
+      out += mask[i]
+      continue
+    }
+    out += raw[r]
+    r++
+  }
+  return out
+}
+
+/** Extract the raw #/A characters a formatted string carries, validating each against its slot. */
+const extractRaw = (mask: string, formatted: string): string => {
+  let raw = ''
+  let m = 0
+  for (const char of formatted) {
+    while (m < mask.length && isLiteral(mask, m)) m++
+    if (m >= mask.length) break
+    if (matchesSlot(mask, m, char)) {
+      raw += char
+      m++
+    }
+  }
+  return raw
+}
+
+/**
+ * Format-as-you-type input over a real `<input>`. `mask` uses `#` for a digit
+ * slot and `A` for a letter slot; any other character is a literal inserted
+ * automatically as the user reaches it. Characters that don't fit the next
+ * slot are rejected, and pasted text is normalized by re-extracting only its
+ * valid #/A characters. Controlled (`value`) or uncontrolled.
+ *
+ * @example
+ * ```tsx
+ * const [phone, setPhone] = createSignal('')
+ * <MaskedInput mask="(###) ###-####" value={phone()} onInput={setPhone} placeholder="(555) 123-4567" />
+ * ```
+ */
+export function MaskedInput(props: MaskedInputProps): JSX.Element {
+  const [local] = splitProps(props, ['mask', 'value', 'onInput', 'placeholder', 'class', 'aria-label'])
+
+  const maxRaw = () => local.mask.split('').filter((c) => c === '#' || c === 'A').length
+
+  const [raw, setRaw] = createSignal(extractRaw(local.mask, local.value ?? '').slice(0, maxRaw()))
+
+  createEffect(() => {
+    if (local.value !== undefined) setRaw(extractRaw(local.mask, local.value).slice(0, maxRaw()))
+  })
+
+  const emit = (nextRaw: string) => {
+    setRaw(nextRaw)
+    local.onInput?.(nextRaw, format(local.mask, nextRaw))
+  }
+
+  const handleInput = (ev: InputEvent & { currentTarget: HTMLInputElement }) => {
+    const typedFormatted = ev.currentTarget.value
+    // Re-derive raw from the full field value so pasted or IME text is
+    // normalized the same way as single keystrokes.
+    const nextRaw = extractRaw(local.mask, typedFormatted).slice(0, maxRaw())
+    emit(nextRaw)
+  }
+
+  return (
+    <input
+      class={cn(INPUT_BASE, local.class)}
+      type="text"
+      inputMode="text"
+      placeholder={local.placeholder ?? local.mask}
+      value={format(local.mask, raw())}
+      onInput={handleInput}
+      aria-label={local['aria-label']}
+    />
+  )
+}

package/src/ui/OnboardingChecklist.tsx

@@ -0,0 +1,163 @@
+// Card-shaped step list for onboarding/setup flows. Completion state is
+// controlled by the caller (`steps[].done`) but each step also tracks its own
+// expanded/collapsed description locally, following the Collapse idiom.
+import { Check } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { createSignal, For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Button } from './Button'
+import { RingProgress } from './RingProgress'
+
+/** A single step in an {@link OnboardingChecklist}. */
+export interface OnboardingStep {
+  /** Stable identifier, used as the toggle key and `For` item key. */
+  id: string
+  title: JSX.Element
+  /** Optional detail shown when the step is expanded. */
+  description?: JSX.Element
+  /** Whether the step is complete. */
+  done?: boolean
+  /** Optional call-to-action rendered alongside the description. */
+  action?: { label: string; onClick: () => void }
+}
+
+export interface OnboardingChecklistProps {
+  steps: OnboardingStep[]
+  /** Called with the step id and its next `done` state when the indicator is toggled. */
+  onToggle?: (id: string, done: boolean) => void
+  /** Heading shown above the progress summary. Defaults to `'Getting started'`. */
+  title?: JSX.Element
+  class?: string
+}
+
+/**
+ * Card-shaped onboarding/setup checklist: a header with a completion ring and
+ * "{done} of {total} complete" summary, followed by expandable steps. Each
+ * step has a clickable check indicator (toggles `done` via `onToggle`), a
+ * title, and an optional description + CTA revealed on expand. Completion is
+ * controlled by the caller; expansion is local UI state (one step open at a time).
+ *
+ * @example
+ * ```tsx
+ * const [steps, setSteps] = createSignal<OnboardingStep[]>([
+ *   { id: 'profile', title: 'Complete your profile', done: true },
+ *   {
+ *     id: 'invite',
+ *     title: 'Invite a teammate',
+ *     description: 'Collaborate faster by adding at least one teammate.',
+ *     action: { label: 'Invite', onClick: () => openInviteDialog() },
+ *   },
+ * ])
+ * <OnboardingChecklist
+ *   steps={steps()}
+ *   onToggle={(id, done) =>
+ *     setSteps((prev) => prev.map((s) => (s.id === id ? { ...s, done } : s)))
+ *   }
+ * />
+ * ```
+ */
+export function OnboardingChecklist(props: OnboardingChecklistProps): JSX.Element {
+  const [expanded, setExpanded] = createSignal<string | null>(null)
+
+  const total = () => props.steps.length
+  const done = () => props.steps.filter((step) => step.done).length
+  const percent = () => (total() === 0 ? 0 : (done() / total()) * 100)
+
+  const toggleDone = (step: OnboardingStep): void => {
+    props.onToggle?.(step.id, !step.done)
+  }
+
+  const toggleExpanded = (id: string): void => {
+    setExpanded((prev) => (prev === id ? null : id))
+  }
+
+  return (
+    <div class={cn('rounded-xl border border-border bg-card text-card-foreground', props.class)}>
+      <div class="flex items-center gap-4 border-b border-border p-4">
+        <RingProgress
+          value={percent()}
+          size={56}
+          thickness={6}
+          label={
+            <span class="text-xs">
+              {done()}/{total()}
+            </span>
+          }
+        />
+        <div>
+          <p class="font-semibold text-foreground">{props.title ?? 'Getting started'}</p>
+          <p class="text-sm text-muted-foreground">
+            {done()} of {total()} complete
+          </p>
+        </div>
+      </div>
+      <ul role="list" class="divide-y divide-border">
+        <For each={props.steps}>
+          {(step) => {
+            const isExpanded = () => expanded() === step.id
+            const hasDetail = () => step.description !== undefined || step.action !== undefined
+            return (
+              <li class="p-4">
+                <div class="flex items-start gap-3">
+                  <button
+                    type="button"
+                    role="checkbox"
+                    aria-checked={!!step.done}
+                    aria-label={step.done ? 'Mark step as not done' : 'Mark step as done'}
+                    onClick={() => toggleDone(step)}
+                    class={cn(
+                      'mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center rounded-full border transition-colors',
+                      step.done
+                        ? 'border-emerald-500 bg-emerald-500 text-white'
+                        : 'border-input bg-background text-transparent hover:border-emerald-500/60',
+                    )}
+                  >
+                    <Check class="h-3.5 w-3.5" />
+                  </button>
+                  <button
+                    type="button"
+                    class="min-w-0 flex-1 text-left"
+                    aria-expanded={hasDetail() ? isExpanded() : undefined}
+                    disabled={!hasDetail()}
+                    onClick={() => hasDetail() && toggleExpanded(step.id)}
+                  >
+                    <span
+                      class={cn(
+                        'block text-sm font-medium',
+                        step.done ? 'text-muted-foreground line-through' : 'text-foreground',
+                      )}
+                    >
+                      {step.title}
+                    </span>
+                  </button>
+                </div>
+                <Show when={hasDetail()}>
+                  <div
+                    class={cn(
+                      'grid transition-[grid-template-rows] duration-200 ease-out motion-reduce:transition-none',
+                      isExpanded() ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]',
+                    )}
+                  >
+                    <div class="overflow-hidden">
+                      <div class="mt-2 pl-8 text-sm text-muted-foreground">
+                        <Show when={step.description}>{step.description}</Show>
+                        <Show when={step.action}>
+                          {(action) => (
+                            <Button variant="outline" class="mt-2" onClick={() => action().onClick()}>
+                              {action().label}
+                            </Button>
+                          )}
+                        </Show>
+                      </div>
+                    </div>
+                  </div>
+                </Show>
+              </li>
+            )
+          }}
+        </For>
+      </ul>
+    </div>
+  )
+}

package/src/ui/OtpInput.tsx

@@ -0,0 +1,153 @@
+import type { JSX } from 'solid-js'
+import { createEffect, createSignal, For, splitProps } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+const BOX_BASE =
+  'h-11 w-10 rounded-md border border-border bg-card text-center text-lg font-medium text-foreground outline-none transition-colors focus-visible:ring-2 focus-visible:ring-ring focus-visible:border-ring disabled:cursor-not-allowed disabled:opacity-50'
+
+export interface OtpInputProps {
+  /** Number of single-character boxes. @default 6 */
+  length?: number
+  /** Controlled value; when provided, the group renders it and the parent owns state. */
+  value?: string
+  /** Called with the full joined value on every box change (both typing and deletion). */
+  onInput?: (value: string) => void
+  /** Called once with the full value when every box is filled. */
+  onComplete?: (value: string) => void
+  /** Restrict input to digits and switch the mobile keyboard to numeric. */
+  numeric?: boolean
+  class?: string
+  'aria-label'?: string
+}
+
+/**
+ * Segmented one-time-passcode input: one `<input maxlength=1>` per character.
+ * Typing advances focus to the next box, Backspace on an empty box moves back
+ * and clears the previous one, arrow keys move focus, and pasting a string
+ * distributes its characters across boxes starting at the focused index.
+ * Works controlled (pass `value`) or uncontrolled.
+ *
+ * @example
+ * ```tsx
+ * const [code, setCode] = createSignal('')
+ * <OtpInput length={6} value={code()} onInput={setCode} numeric onComplete={verify} />
+ * ```
+ */
+export function OtpInput(props: OtpInputProps): JSX.Element {
+  const [local] = splitProps(props, [
+    'length',
+    'value',
+    'onInput',
+    'onComplete',
+    'numeric',
+    'class',
+    'aria-label',
+  ])
+  const length = () => local.length ?? 6
+
+  const toChars = (v: string) => {
+    const chars = v.slice(0, length()).split('')
+    return Array.from({ length: length() }, (_, i) => chars[i] ?? '')
+  }
+
+  const [chars, setChars] = createSignal<string[]>(toChars(local.value ?? ''))
+  const inputs: (HTMLInputElement | undefined)[] = []
+
+  createEffect(() => {
+    if (local.value !== undefined) setChars(toChars(local.value))
+  })
+
+  const emit = (next: string[]) => {
+    setChars(next)
+    const joined = next.join('')
+    local.onInput?.(joined)
+    if (next.every((c) => c !== '')) local.onComplete?.(joined)
+  }
+
+  const isValidChar = (c: string) => (local.numeric ? /^[0-9]$/.test(c) : c.length === 1)
+
+  const handleInput = (index: number, raw: string) => {
+    // Take the last typed character in case the box already held one.
+    const typed = raw.slice(-1)
+    if (typed === '') {
+      const next = [...chars()]
+      next[index] = ''
+      emit(next)
+      return
+    }
+    if (!isValidChar(typed)) {
+      // Revert the DOM to the last known-good value for this box.
+      const el = inputs[index]
+      if (el) el.value = chars()[index] ?? ''
+      return
+    }
+    const next = [...chars()]
+    next[index] = typed
+    emit(next)
+    if (index < length() - 1) inputs[index + 1]?.focus()
+  }
+
+  const handleKeyDown = (index: number, ev: KeyboardEvent) => {
+    if (ev.key === 'Backspace') {
+      if (chars()[index] === '' && index > 0) {
+        ev.preventDefault()
+        const next = [...chars()]
+        next[index - 1] = ''
+        emit(next)
+        inputs[index - 1]?.focus()
+      }
+      return
+    }
+    if (ev.key === 'ArrowLeft' && index > 0) {
+      ev.preventDefault()
+      inputs[index - 1]?.focus()
+      return
+    }
+    if (ev.key === 'ArrowRight' && index < length() - 1) {
+      ev.preventDefault()
+      inputs[index + 1]?.focus()
+    }
+  }
+
+  const handlePaste = (index: number, ev: ClipboardEvent) => {
+    ev.preventDefault()
+    const pasted = ev.clipboardData?.getData('text') ?? ''
+    const valid = pasted.split('').filter(isValidChar)
+    if (valid.length === 0) return
+    const next = [...chars()]
+    let last = index
+    for (let i = 0; i < valid.length && index + i < length(); i++) {
+      next[index + i] = valid[i]
+      last = index + i
+    }
+    emit(next)
+    inputs[Math.min(last + 1, length() - 1)]?.focus()
+  }
+
+  return (
+    <div
+      role="group"
+      aria-label={local['aria-label'] ?? 'One-time passcode'}
+      class={cn('flex gap-2', local.class)}
+    >
+      <For each={chars()}>
+        {(char, index) => (
+          <input
+            ref={(el) => (inputs[index()] = el)}
+            class={BOX_BASE}
+            type="text"
+            inputMode={local.numeric ? 'numeric' : 'text'}
+            maxlength={1}
+            autocomplete="one-time-code"
+            value={char}
+            onInput={(ev) => handleInput(index(), ev.currentTarget.value)}
+            onKeyDown={(ev) => handleKeyDown(index(), ev)}
+            onPaste={(ev) => handlePaste(index(), ev)}
+            aria-label={`Digit ${index() + 1} of ${length()}`}
+          />
+        )}
+      </For>
+    </div>
+  )
+}

package/src/ui/PresenceAvatars.tsx

@@ -0,0 +1,142 @@
+// Multiplayer presence: a stacked avatar group (same overlap idiom as
+// AvatarGroup) of active users with an online dot, plus optional data-driven
+// remote cursors positioned within the caller's own relative canvas wrapper.
+// Distinct from the decorative FollowingPointer, which follows the LOCAL
+// pointer — these render OTHER users' server-driven positions.
+import type { JSX } from 'solid-js'
+import { For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Avatar } from './Avatar'
+
+/** A user currently present/active in a collaborative session. */
+export interface PresenceUser {
+  id: string
+  name: string
+  avatar?: string
+  /** Accent for this user's remote cursor label. Falls back to the primary token. */
+  color?: string
+}
+
+/** A remote user's pointer position, as fractions of the shared canvas. */
+export interface RemoteCursor {
+  userId: string
+  /** 0..1 fraction of the container's width. */
+  x: number
+  /** 0..1 fraction of the container's height. */
+  y: number
+}
+
+export interface PresenceAvatarsProps {
+  users: PresenceUser[]
+  /** Max avatars shown before collapsing the rest into `+N`. @default 4 */
+  max?: number
+  /**
+   * Remote cursors to render. Positioned absolutely against the nearest
+   * `relative` ancestor, so the caller wraps its canvas/surface with
+   * `class="relative"` for the cursors to anchor to — this component itself
+   * does not create that positioning context.
+   */
+  cursors?: RemoteCursor[]
+  class?: string
+}
+
+function initials(name: string): string {
+  return name
+    .split(' ')
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((part) => part[0]?.toUpperCase())
+    .join('')
+}
+
+/**
+ * Stacked avatar group of users active in a collaborative session, each with
+ * a small online dot and a name tooltip; overflow past `max` (default 4)
+ * collapses into a trailing `+N` chip, mirroring {@link AvatarGroup}. When
+ * `cursors` is given, also renders labeled remote cursors — a small arrow
+ * plus a name chip tinted with the user's `color` — positioned at `x`/`y`
+ * fractions of the nearest `relative` ancestor and animated smoothly as
+ * positions update.
+ *
+ * @example
+ * ```tsx
+ * <div class="relative h-64 w-full overflow-hidden rounded-lg border">
+ *   <PresenceAvatars
+ *     class="absolute right-3 top-3"
+ *     users={[
+ *       { id: 'u1', name: 'Ada Lovelace' },
+ *       { id: 'u2', name: 'Grace Hopper', color: 'hsl(280 80% 60%)' },
+ *     ]}
+ *     cursors={[{ userId: 'u2', x: 0.42, y: 0.6 }]}
+ *   />
+ * </div>
+ * ```
+ */
+export function PresenceAvatars(props: PresenceAvatarsProps): JSX.Element {
+  const max = () => props.max ?? 4
+  const shown = () => props.users.slice(0, max())
+  const overflow = () => props.users.length - shown().length
+  const cursorUser = (userId: string) => props.users.find((user) => user.id === userId)
+
+  return (
+    <>
+      <div class={cn('flex items-center', props.class)}>
+        <For each={shown()}>
+          {(user, index) => (
+            <div
+              class={cn('relative rounded-full ring-2 ring-background', index() > 0 && '-ml-2')}
+              title={user.name}
+            >
+              <Avatar src={user.avatar} alt={user.name} fallback={initials(user.name)} />
+              <span
+                aria-hidden="true"
+                class="absolute bottom-0 right-0 h-2.5 w-2.5 rounded-full bg-emerald-500 ring-2 ring-background"
+              />
+            </div>
+          )}
+        </For>
+        <Show when={overflow() > 0}>
+          <div class="-ml-2 rounded-full ring-2 ring-background">
+            <span class="grid h-9 w-9 shrink-0 place-items-center rounded-full bg-muted text-xs font-medium text-muted-foreground">
+              +{overflow()}
+            </span>
+          </div>
+        </Show>
+      </div>
+      <Show when={props.cursors && props.cursors.length > 0}>
+        <div class="pointer-events-none absolute inset-0 z-50 overflow-hidden">
+          <For each={props.cursors}>
+            {(cursor) => {
+              const user = () => cursorUser(cursor.userId)
+              const color = () => user()?.color ?? 'hsl(var(--primary))'
+              return (
+                <Show when={user()}>
+                  <div
+                    class="absolute flex -translate-x-0.5 -translate-y-0.5 items-center transition-[left,top] duration-150 ease-out will-change-[left,top]"
+                    style={{ left: `${cursor.x * 100}%`, top: `${cursor.y * 100}%` }}
+                  >
+                    <svg width="18" height="18" viewBox="0 0 20 20" class="drop-shadow">
+                      <path
+                        d="M2 2 L18 9 L10 11 L8 18 Z"
+                        fill={color()}
+                        stroke="hsl(var(--background))"
+                        stroke-width="1"
+                      />
+                    </svg>
+                    <span
+                      class="ml-1.5 whitespace-nowrap rounded-full px-2 py-0.5 text-xs font-medium text-white shadow"
+                      style={{ 'background-color': color() }}
+                    >
+                      {user()!.name}
+                    </span>
+                  </div>
+                </Show>
+              )
+            }}
+          </For>
+        </div>
+      </Show>
+    </>
+  )
+}