@a4ui/core 0.34.0 → 0.35.1

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>
+    </>
+  )
+}

package/src/ui/QueryBuilder.tsx

@@ -0,0 +1,281 @@
+// Nested AND/OR rule builder — renders a QueryGroup tree recursively.
+import { Plus, Trash2 } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { createMemo, createSignal, For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Button } from './Button'
+import { Input } from './Input'
+import { Select } from './Select'
+
+/** A field the query builder can filter on. */
+export interface QueryField {
+  /** Value stored in a rule's `field`; must be unique across `fields`. */
+  name: string
+  /** Label shown in the field `<Select>`. */
+  label: string
+  /** Determines which operators are offered and how the value is entered. Defaults to `'text'`. */
+  type?: 'text' | 'number' | 'select'
+  /** Options for the value `<Select>` when `type` is `'select'`. */
+  options?: string[]
+}
+
+/** A single leaf condition: `field operator value`. */
+export type QueryRule = { field: string; operator: string; value: string }
+
+/** A group of rules and/or nested groups, combined with `and`/`or`. */
+export type QueryGroup = { combinator: 'and' | 'or'; rules: (QueryRule | QueryGroup)[] }
+
+export interface QueryBuilderProps {
+  /** Fields available to filter on; drives the per-field operator and value-input set. */
+  fields: QueryField[]
+  /** Controlled tree. Omit to manage state internally, seeded with one empty rule. */
+  value?: QueryGroup
+  /** Called with the full, updated tree on every edit. */
+  onChange?: (group: QueryGroup) => void
+  class?: string
+}
+
+const OPERATORS: Record<NonNullable<QueryField['type']>, string[]> = {
+  text: ['is', 'contains', 'starts with'],
+  number: ['=', '>', '<', 'between'],
+  select: ['is', 'is not'],
+}
+
+function isGroup(node: QueryRule | QueryGroup): node is QueryGroup {
+  return 'combinator' in node
+}
+
+function emptyRule(fields: QueryField[]): QueryRule {
+  const field = fields[0]
+  const type = field?.type ?? 'text'
+  return { field: field?.name ?? '', operator: OPERATORS[type][0], value: '' }
+}
+
+function emptyGroup(fields: QueryField[]): QueryGroup {
+  return { combinator: 'and', rules: [emptyRule(fields)] }
+}
+
+/**
+ * Nested AND/OR rule builder: each group has a combinator toggle plus "+ Rule"
+ * / "+ Group" buttons, and rules/groups can be removed individually. Groups
+ * nest recursively, indented with a left border. Controlled via `value` +
+ * `onChange`, or uncontrolled (seeded with one empty rule) when `value` is
+ * omitted.
+ *
+ * @example
+ * ```tsx
+ * const [query, setQuery] = createSignal<QueryGroup>({
+ *   combinator: 'and',
+ *   rules: [{ field: 'status', operator: 'is', value: 'open' }],
+ * })
+ * <QueryBuilder
+ *   fields={[
+ *     { name: 'status', label: 'Status', type: 'select', options: ['open', 'closed'] },
+ *     { name: 'age', label: 'Age', type: 'number' },
+ *   ]}
+ *   value={query()}
+ *   onChange={setQuery}
+ * />
+ * ```
+ */
+export function QueryBuilder(props: QueryBuilderProps): JSX.Element {
+  const [internal, setInternal] = createSignal<QueryGroup>(props.value ?? emptyGroup(props.fields))
+
+  const group = createMemo(() => props.value ?? internal())
+
+  const emit = (next: QueryGroup): void => {
+    if (props.value === undefined) setInternal(next)
+    props.onChange?.(next)
+  }
+
+  const fieldByName = (name: string): QueryField | undefined => props.fields.find((f) => f.name === name)
+
+  const operatorsFor = (fieldName: string): string[] => OPERATORS[fieldByName(fieldName)?.type ?? 'text']
+
+  return (
+    <GroupView
+      group={group()}
+      fields={props.fields}
+      operatorsFor={operatorsFor}
+      fieldByName={fieldByName}
+      onChange={emit}
+      depth={0}
+      onRemove={undefined}
+    />
+  )
+}
+
+interface GroupViewProps {
+  group: QueryGroup
+  fields: QueryField[]
+  operatorsFor: (fieldName: string) => string[]
+  fieldByName: (name: string) => QueryField | undefined
+  onChange: (next: QueryGroup) => void
+  depth: number
+  /** Absent for the root group, which cannot remove itself. */
+  onRemove: (() => void) | undefined
+}
+
+function GroupView(props: GroupViewProps): JSX.Element {
+  const updateNode = (index: number, next: QueryRule | QueryGroup): void => {
+    const rules = props.group.rules.slice()
+    rules[index] = next
+    props.onChange({ ...props.group, rules })
+  }
+
+  const removeNode = (index: number): void => {
+    const rules = props.group.rules.slice()
+    rules.splice(index, 1)
+    props.onChange({ ...props.group, rules })
+  }
+
+  const addRule = (): void => {
+    props.onChange({ ...props.group, rules: [...props.group.rules, emptyRule(props.fields)] })
+  }
+
+  const addGroup = (): void => {
+    props.onChange({ ...props.group, rules: [...props.group.rules, emptyGroup(props.fields)] })
+  }
+
+  const setCombinator = (combinator: 'and' | 'or'): void => {
+    props.onChange({ ...props.group, combinator })
+  }
+
+  return (
+    <div class={cn('flex flex-col gap-2 rounded-md p-2', props.depth > 0 && 'border-l-2 border-border pl-3')}>
+      <div class="flex flex-wrap items-center gap-2">
+        <div
+          class="inline-flex overflow-hidden rounded-md border border-input"
+          role="group"
+          aria-label="Combinator"
+        >
+          <For each={['and', 'or'] as const}>
+            {(c) => (
+              <button
+                type="button"
+                class={cn(
+                  'px-2 py-1 text-xs font-semibold uppercase transition-colors',
+                  props.group.combinator === c
+                    ? 'bg-primary text-primary-foreground'
+                    : 'bg-background text-muted-foreground hover:bg-muted',
+                )}
+                aria-pressed={props.group.combinator === c}
+                onClick={() => setCombinator(c)}
+              >
+                {c}
+              </button>
+            )}
+          </For>
+        </div>
+        <Button variant="outline" onClick={addRule}>
+          <Plus class="mr-1 h-3.5 w-3.5" aria-hidden="true" />
+          Rule
+        </Button>
+        <Button variant="outline" onClick={addGroup}>
+          <Plus class="mr-1 h-3.5 w-3.5" aria-hidden="true" />
+          Group
+        </Button>
+        <Show when={props.onRemove}>
+          {(remove) => (
+            <button
+              type="button"
+              class="ml-auto rounded-md p-1.5 text-muted-foreground hover:bg-muted hover:text-foreground"
+              aria-label="Remove group"
+              onClick={() => remove()()}
+            >
+              <Trash2 class="h-3.5 w-3.5" aria-hidden="true" />
+            </button>
+          )}
+        </Show>
+      </div>
+
+      <For each={props.group.rules}>
+        {(node, index) => (
+          <Show
+            when={isGroup(node)}
+            fallback={
+              <RuleRow
+                rule={node as QueryRule}
+                fields={props.fields}
+                operatorsFor={props.operatorsFor}
+                fieldByName={props.fieldByName}
+                onChange={(next) => updateNode(index(), next)}
+                onRemove={() => removeNode(index())}
+              />
+            }
+          >
+            <GroupView
+              group={node as QueryGroup}
+              fields={props.fields}
+              operatorsFor={props.operatorsFor}
+              fieldByName={props.fieldByName}
+              onChange={(next) => updateNode(index(), next)}
+              depth={props.depth + 1}
+              onRemove={() => removeNode(index())}
+            />
+          </Show>
+        )}
+      </For>
+    </div>
+  )
+}
+
+interface RuleRowProps {
+  rule: QueryRule
+  fields: QueryField[]
+  operatorsFor: (fieldName: string) => string[]
+  fieldByName: (name: string) => QueryField | undefined
+  onChange: (next: QueryRule) => void
+  onRemove: () => void
+}
+
+function RuleRow(props: RuleRowProps): JSX.Element {
+  const field = createMemo(() => props.fieldByName(props.rule.field))
+
+  const setField = (name: string): void => {
+    const operators = props.operatorsFor(name)
+    props.onChange({ field: name, operator: operators[0], value: '' })
+  }
+
+  const setOperator = (operator: string): void => props.onChange({ ...props.rule, operator })
+  const setValue = (value: string): void => props.onChange({ ...props.rule, value })
+
+  return (
+    <div class="flex flex-wrap items-center gap-2">
+      <Select class="w-40" value={props.rule.field} onChange={setField} aria-label="Field">
+        <For each={props.fields}>{(f) => <option value={f.name}>{f.label}</option>}</For>
+      </Select>
+      <Select class="w-32" value={props.rule.operator} onChange={setOperator} aria-label="Operator">
+        <For each={props.operatorsFor(props.rule.field)}>{(op) => <option value={op}>{op}</option>}</For>
+      </Select>
+      <Show
+        when={field()?.type === 'select'}
+        fallback={
+          <Input
+            class="w-40"
+            type={field()?.type === 'number' ? 'number' : 'text'}
+            value={props.rule.value}
+            onInput={setValue}
+            aria-label="Value"
+          />
+        }
+      >
+        <Select class="w-40" value={props.rule.value} onChange={setValue} aria-label="Value">
+          <option value="" disabled>
+            Select…
+          </option>
+          <For each={field()?.options ?? []}>{(opt) => <option value={opt}>{opt}</option>}</For>
+        </Select>
+      </Show>
+      <button
+        type="button"
+        class="rounded-md p-1.5 text-muted-foreground hover:bg-muted hover:text-foreground"
+        aria-label="Remove rule"
+        onClick={props.onRemove}
+      >
+        <Trash2 class="h-3.5 w-3.5" aria-hidden="true" />
+      </button>
+    </div>
+  )
+}

package/src/ui/RingProgress.tsx

@@ -12,6 +12,8 @@ export interface RingProgressProps {
   thickness?: number
   /** Content centered over the ring. Defaults to the rounded percent. */
   label?: JSX.Element
+  /** Accessible name for the `role="progressbar"` element. */
+  'aria-label'?: string
   class?: string
 }
 
@@ -37,6 +39,7 @@ export function RingProgress(props: RingProgressProps): JSX.Element {
   return (
     <div
       role="progressbar"
+      aria-label={props['aria-label']}
       aria-valuenow={clamped()}
       aria-valuemin={0}
       aria-valuemax={100}

package/src/ui/SignaturePad.tsx

@@ -0,0 +1,221 @@
+// Canvas-based signature capture. DPR-aware sizing (crisp strokes on retina),
+// pointer events (mouse + touch + pen in one listener set), and a stroke stack
+// so Undo can redraw from scratch instead of trying to "erase" a curve.
+import { Eraser, Undo2 } from 'lucide-solid'
+import { createSignal, onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+interface Point {
+  x: number
+  y: number
+}
+
+type Stroke = Point[]
+
+export interface SignaturePadProps {
+  /** Called with a PNG data URL after each completed stroke, or `null` once the pad is empty (cleared/undone to nothing). */
+  onChange?: (dataUrl: string | null) => void
+  /** Canvas height in CSS pixels. @default 200 */
+  height?: number
+  class?: string
+}
+
+/**
+ * A signature capture pad: draw with mouse, pen, or touch on a DPR-aware
+ * `<canvas>`, with Clear and Undo controls. Strokes are kept as point lists so
+ * Undo can fully redraw the remaining ones rather than trying to erase pixels.
+ *
+ * @example
+ * ```tsx
+ * <SignaturePad height={220} onChange={(dataUrl) => setSignature(dataUrl)} />
+ * ```
+ */
+export function SignaturePad(props: SignaturePadProps): JSX.Element {
+  let canvas!: HTMLCanvasElement
+  let container!: HTMLDivElement
+  let ctx: CanvasRenderingContext2D | null = null
+
+  const strokes: Stroke[] = []
+  let current: Stroke | null = null
+  let drawing = false
+
+  const [hasInk, setHasInk] = createSignal(false)
+
+  const height = () => props.height ?? 200
+
+  const resize = (): void => {
+    if (!canvas || !container) return
+    const dpr = window.devicePixelRatio || 1
+    const width = container.clientWidth
+    const h = height()
+    canvas.width = Math.max(1, Math.round(width * dpr))
+    canvas.height = Math.max(1, Math.round(h * dpr))
+    canvas.style.width = `${width}px`
+    canvas.style.height = `${h}px`
+    ctx = canvas.getContext('2d')
+    if (ctx) ctx.scale(dpr, dpr)
+    redraw()
+  }
+
+  const strokeColor = (): string => {
+    // Resolved at draw time so it stays correct across theme/light-dark toggles.
+    const root = getComputedStyle(document.documentElement)
+    const hsl = root.getPropertyValue('--foreground').trim()
+    return hsl ? `hsl(${hsl})` : '#000'
+  }
+
+  const drawStroke = (context: CanvasRenderingContext2D, stroke: Stroke): void => {
+    if (stroke.length < 2) {
+      // A single tap/click: draw a dot so it's not silently lost.
+      if (stroke.length === 1) {
+        context.beginPath()
+        context.arc(stroke[0].x, stroke[0].y, 1.25, 0, Math.PI * 2)
+        context.fillStyle = strokeColor()
+        context.fill()
+      }
+      return
+    }
+    context.lineJoin = 'round'
+    context.lineCap = 'round'
+    context.lineWidth = 2.25
+    context.strokeStyle = strokeColor()
+    context.beginPath()
+    context.moveTo(stroke[0].x, stroke[0].y)
+    for (let i = 1; i < stroke.length; i++) context.lineTo(stroke[i].x, stroke[i].y)
+    context.stroke()
+  }
+
+  const clearCanvas = (context: CanvasRenderingContext2D): void => {
+    const dpr = window.devicePixelRatio || 1
+    context.clearRect(0, 0, canvas.width / dpr, canvas.height / dpr)
+  }
+
+  const redraw = (): void => {
+    if (!ctx) return
+    clearCanvas(ctx)
+    for (const stroke of strokes) drawStroke(ctx, stroke)
+    setHasInk(strokes.length > 0)
+  }
+
+  const emitChange = (): void => {
+    props.onChange?.(strokes.length > 0 ? canvas.toDataURL('image/png') : null)
+  }
+
+  const pointFromEvent = (event: PointerEvent): Point => {
+    const rect = canvas.getBoundingClientRect()
+    return { x: event.clientX - rect.left, y: event.clientY - rect.top }
+  }
+
+  const onPointerDown = (event: PointerEvent): void => {
+    if (!ctx) return
+    event.preventDefault()
+    drawing = true
+    current = [pointFromEvent(event)]
+    canvas.setPointerCapture(event.pointerId)
+  }
+
+  const onPointerMove = (event: PointerEvent): void => {
+    if (!drawing || !current || !ctx) return
+    const point = pointFromEvent(event)
+    const prev = current[current.length - 1]
+    current.push(point)
+    ctx.lineJoin = 'round'
+    ctx.lineCap = 'round'
+    ctx.lineWidth = 2.25
+    ctx.strokeStyle = strokeColor()
+    ctx.beginPath()
+    ctx.moveTo(prev.x, prev.y)
+    ctx.lineTo(point.x, point.y)
+    ctx.stroke()
+  }
+
+  const endStroke = (): void => {
+    if (!drawing) return
+    drawing = false
+    if (current && current.length > 0) {
+      strokes.push(current)
+      setHasInk(true)
+      emitChange()
+    }
+    current = null
+  }
+
+  const onPointerUp = (event: PointerEvent): void => {
+    if (canvas.hasPointerCapture(event.pointerId)) canvas.releasePointerCapture(event.pointerId)
+    endStroke()
+  }
+
+  const handleClear = (): void => {
+    strokes.length = 0
+    current = null
+    drawing = false
+    redraw()
+    emitChange()
+  }
+
+  const handleUndo = (): void => {
+    strokes.pop()
+    redraw()
+    emitChange()
+  }
+
+  onMount(() => {
+    resize()
+    window.addEventListener('resize', resize)
+    canvas.addEventListener('pointerdown', onPointerDown)
+    canvas.addEventListener('pointermove', onPointerMove)
+    canvas.addEventListener('pointerup', onPointerUp)
+    canvas.addEventListener('pointercancel', onPointerUp)
+  })
+
+  onCleanup(() => {
+    window.removeEventListener('resize', resize)
+    canvas.removeEventListener('pointerdown', onPointerDown)
+    canvas.removeEventListener('pointermove', onPointerMove)
+    canvas.removeEventListener('pointerup', onPointerUp)
+    canvas.removeEventListener('pointercancel', onPointerUp)
+  })
+
+  return (
+    <div class={cn('flex flex-col gap-2', props.class)} role="group" aria-label="Signature pad">
+      <div
+        ref={container}
+        class="relative w-full touch-none overflow-hidden rounded-md border border-input bg-background"
+        style={{ height: `${height()}px` }}
+      >
+        <canvas
+          ref={canvas}
+          class="block h-full w-full cursor-crosshair touch-none"
+          aria-label="Draw your signature here"
+        />
+        {!hasInk() && (
+          <div class="pointer-events-none absolute inset-x-4 bottom-6 flex flex-col items-center gap-1">
+            <span class="w-full border-b border-dashed border-border" />
+            <span class="text-xs text-muted-foreground">Sign here</span>
+          </div>
+        )}
+      </div>
+      <div class="flex items-center justify-end gap-2">
+        <button
+          type="button"
+          onClick={handleUndo}
+          disabled={strokes.length === 0}
+          class="inline-flex items-center gap-1.5 rounded-md border border-border px-2.5 py-1.5 text-xs font-medium text-foreground transition-colors hover:bg-muted focus:outline-none focus:ring-2 focus:ring-ring disabled:pointer-events-none disabled:opacity-50"
+        >
+          <Undo2 class="h-3.5 w-3.5" />
+          Undo
+        </button>
+        <button
+          type="button"
+          onClick={handleClear}
+          disabled={!hasInk()}
+          class="inline-flex items-center gap-1.5 rounded-md border border-border px-2.5 py-1.5 text-xs font-medium text-foreground transition-colors hover:bg-muted focus:outline-none focus:ring-2 focus:ring-ring disabled:pointer-events-none disabled:opacity-50"
+        >
+          <Eraser class="h-3.5 w-3.5" />
+          Clear
+        </button>
+      </div>
+    </div>
+  )
+}