@meistrari/tela-build 1.68.0 → 1.69.1

package/components/tela/presence/presence-avatars.mdx

@@ -0,0 +1,123 @@
+# TelaPresenceAvatars
+
+Shows who else is currently viewing the same page. Two variants:
+
+- **`pill`** (default): a "N Viewing" count followed by up to `max` overlapping round avatars on a `bg-muted` pill (8px radius, 4px vertical / 10px left / 8px right padding). Hovering the count lists viewer names (up to `tooltipMax`, then a "x more" line).
+- **`avatars`**: just the overlapping avatar stack — no count label, no pill surface — at a larger default size (`xs`, 24px). Meant for page headers (canvas, workflow, agent) where the count pill is too heavy. When more than `max` viewers are present, the last visible avatar gets an 80% `neutral-950` mask with a white "+N" count on top (no extra bubble); hovering it shows the same tooltip as the pill count (up to `tooltipMax` names, then the "x more" line).
+
+Hovering an avatar shows the viewer's name and live status on separate lines: `Viewing now`, or for away viewers a relative time like "3 min ago" when `awaySinceLabel` is provided (falling back to the plain `awayLabel`). All tooltips share one `TelaTooltipGroup`, so moving between triggers skips the open delay instead of re-animating each tooltip. Viewers with `active: false` (page open, tab hidden) render dimmed instead of disappearing. Renders nothing when the viewers list is empty, so mount points need no guards.
+
+Overlapping avatars are separated with a `mask-image` radial-gradient (the tags-select dot technique): each avatar except the last carves a transparent 2px crescent where the next avatar overlaps, so the gap shows whatever is behind the stack instead of a hardcoded ring color. Overlap scales with avatar size (16px→4px, 24px→6px, 32px→8px, 40px→10px).
+
+Pair it with the `usePresence` composable, which joins a Yjs awareness room over websockets (channel switching, hard stop on repeated connection failures) and exposes the other viewers as `PresenceViewer[]` — deduped per user across tabs, sorted with active viewers first, then by join time, so people who tab away drop to the back of the stack and active viewers hold the visible slots. The connection stays open while the tab is hidden; the composable publishes `active: false` so peers dim and demote the avatar rather than dropping it. The consuming app provides the websocket `url`, the auth `getToken`, and the local `self` identity.
+
+The component is i18n-free: pass pre-translated `countLabel`, `viewingLabel`, `awayLabel`, and `moreLabel` strings, and the `awaySinceLabel` formatter, from the app layer.
+
+## Examples
+
+### Basic Usage
+
+```vue
+<TelaPresenceAvatars
+  :viewers="[
+    { name: 'Ada Lovelace', email: 'ada@example.com', image: 'https://example.com/ada.jpg' },
+    { name: 'Grace Hopper', email: 'grace@example.com' },
+  ]"
+  count-label="2 Viewing"
+/>
+```
+
+### Avatars-only variant
+
+No count label, no pill chrome, larger avatars (defaults to `xs` / 24px). Used inside canvas, workflow, and agent headers. Overflow beyond `max` darkens the last visible avatar with an 80% mask and a "+N" count, with the name-list tooltip on hover.
+
+```vue
+<TelaPresenceAvatars
+  variant="avatars"
+  :viewers="others"
+  label="Viewing this canvas"
+/>
+```
+
+### Away viewers
+
+A viewer with `active: false` renders at reduced opacity, moves behind the active viewers (`usePresence` sorts active-first), and their tooltip status switches to `awaySinceLabel(viewer.awaySince)` (e.g. "3 min ago") or the `awayLabel` when no timestamp/formatter is available. `usePresence` publishes `awaySince` when the tab goes hidden and clears it on return; pass a formatter that reads a reactive clock (e.g. `useNow`) so the label stays fresh while the tooltip is open.
+
+```vue
+<TelaPresenceAvatars
+  :viewers="[
+    { name: 'Ada Lovelace', email: 'ada@example.com' },
+    { name: 'Grace Hopper', email: 'grace@example.com', active: false },
+  ]"
+  count-label="2 Viewing"
+  viewing-label="Viewing now"
+  away-label="Away"
+/>
+```
+
+### Overflow
+
+Only the first `max` viewers render as avatars (priority to active viewers, then the earliest joiners — the input order). The count tooltip lists up to `tooltipMax` emails, then a final "x more" line built with `moreLabel`.
+
+```vue
+<TelaPresenceAvatars
+  :viewers="manyViewers"
+  :max="3"
+  :tooltip-max="7"
+  count-label="9 Viewing"
+  :more-label="count => `${count} more`"
+/>
+```
+
+### With usePresence
+
+The composable joins the live-collaboration room for the channel; `others` is already sorted (active first, then join time) and feeds straight into the component.
+
+```ts
+const { others } = usePresence({
+  channel: computed(() => `prompt:${route.params.promptId}`),
+  url: 'wss://collab.example.com',
+  self: computed(() => ({ id: user.id, email: user.email, name: user.name, image: user.image })),
+  getToken: async () => await auth.getToken(),
+})
+```
+
+```vue
+<TelaPresenceAvatars
+  :viewers="others"
+  :count-label="`${others.length} Viewing`"
+  label="Viewing this canvas"
+/>
+```
+
+## Props
+
+| Prop           | Type                                                                                        | Default               | Description                                                              |
+| -------------- | ------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------ |
+| `viewers`      | `{ name?: string, email?: string, image?: string, active?: boolean, joinedAt?: number \| null }[]` | required      | The other people in the room, pre-sorted (`usePresence` output)          |
+| `max`          | `number`                                                                                    | `3`                   | Visible avatar slots                                                     |
+| `tooltipMax`   | `number`                                                                                    | `7`                   | Names listed in the count tooltip before the "x more" line               |
+| `variant`      | `'pill' \| 'avatars'`                                                                       | `'pill'`              | `pill` shows the count on a muted surface; `avatars` is just the stack   |
+| `size`         | `'2xs' \| 'xs' \| 'sm' \| 'md'`                                                             | `'2xs'` pill / `'xs'` avatars | Avatar size                                                      |
+| `label`        | `string`                                                                                    | `'Viewing this page'` | aria-label suffix; pass a translated string                              |
+| `countLabel`   | `string`                                                                                    | viewer count          | Pre-translated count text, e.g. "3 Viewing" (pill variant only)          |
+| `viewingLabel` | `string`                                                                                    | `'Viewing now'`       | Status word in the avatar tooltip for active viewers                     |
+| `awayLabel`    | `string`                                                                                    | `'Away'`              | Status word in the avatar tooltip for hidden-tab viewers                 |
+| `awaySinceLabel` | `(awaySince: number) => string`                                                           | —                     | Formats the away timestamp (e.g. "3 min ago"); falls back to `awayLabel` |
+| `moreLabel`    | `(count: number) => string`                                                                 | `` count => `${count} more` `` | Builds the overflow line in the count tooltip                    |
+
+## Features
+
+- Pill variant surface: `bg-muted`, 8px radius, 4px vertical / 10px left / 8px right padding, `body-12-medium` count text
+- Overlapping avatars separated by a mask-carved 2px transparent crescent (no hardcoded ring color), overlap proportional to avatar size
+- Falls back to initials when a viewer has no image (via `TelaAvatar`)
+- Count tooltip lists viewer names (capped at `tooltipMax` + "x more"); avatar tooltip stacks the name and Viewing/Away status on separate lines
+- Shared `TelaTooltipGroup`: hovering across triggers skips the tooltip delay/animation
+- Away viewers (`active: false`) dim the avatar to 50% with a 160ms transition and reorder to the back of the stack instead of leaving
+- Subtle 160ms enter/leave/move transitions when viewers join, drop off, or reorder
+- Empty viewers list renders nothing
+
+## Accessibility
+
+- Container exposes `role="group"` with an `aria-label` of `"{count} {label}"`
+- Each avatar's accessible name comes from its `alt` (viewer name or email)

package/components/tela/presence/presence-avatars.vue

@@ -0,0 +1,192 @@
+<script setup lang="ts">
+export type PresenceAvatarSize = '2xs' | 'xs' | 'sm' | 'md'
+export type PresenceAvatarsVariant = 'pill' | 'avatars'
+
+export interface PresenceAvatarViewer {
+    name?: string
+    email?: string
+    image?: string
+    active?: boolean
+    joinedAt?: number | null
+    awaySince?: number | null
+}
+
+const props = withDefaults(defineProps<{
+    viewers: PresenceAvatarViewer[]
+    max?: number
+    tooltipMax?: number
+    size?: PresenceAvatarSize
+    variant?: PresenceAvatarsVariant
+    label?: string
+    countLabel?: string
+    viewingLabel?: string
+    awayLabel?: string
+    awaySinceLabel?: (awaySince: number) => string
+    moreLabel?: (count: number) => string
+}>(), {
+    max: 3,
+    tooltipMax: 7,
+    variant: 'pill',
+    label: 'Viewing this page',
+    viewingLabel: 'Viewing now',
+    awayLabel: 'Away',
+    moreLabel: (count: number) => `${count} more`,
+})
+
+const STACK_METRICS: Record<PresenceAvatarSize, { size: number, overlap: number, fontSize: number }> = {
+    '2xs': { size: 16, overlap: 4, fontSize: 8 },
+    'xs': { size: 24, overlap: 6, fontSize: 10 },
+    'sm': { size: 32, overlap: 8, fontSize: 12 },
+    'md': { size: 40, overlap: 10, fontSize: 14 },
+}
+
+const resolvedSize = computed<PresenceAvatarSize>(() => props.size ?? (props.variant === 'avatars' ? 'xs' : '2xs'))
+
+// Overlapped avatars get a crescent carved out with a mask (same technique as
+// tags-select dots): the mask circle is centered on the next avatar's center,
+// with a 2px ring of transparency around it.
+const stackStyle = computed(() => {
+    const { size, overlap } = STACK_METRICS[resolvedSize.value]
+    return {
+        '--presence-overlap': `${overlap}px`,
+        '--presence-mask-radius': `${size / 2 + 2}px`,
+        '--presence-mask-x': `calc(100% + ${size / 2 - overlap}px)`,
+    }
+})
+
+const visibleViewers = computed(() => props.viewers.slice(0, props.max))
+const tooltipViewers = computed(() => props.viewers.slice(0, props.tooltipMax))
+const hiddenTooltipCount = computed(() => Math.max(props.viewers.length - props.tooltipMax, 0))
+const resolvedCountLabel = computed(() => props.countLabel ?? `${props.viewers.length}`)
+
+const overflowCount = computed(() => props.variant === 'avatars' ? Math.max(props.viewers.length - props.max, 0) : 0)
+
+const overflowTextStyle = computed(() => ({ fontSize: `${STACK_METRICS[resolvedSize.value].fontSize}px` }))
+
+function isOverflowSlot(index: number) {
+    return overflowCount.value > 0 && index === visibleViewers.value.length - 1
+}
+
+function isActive(viewer: PresenceAvatarViewer) {
+    return viewer.active !== false
+}
+
+function displayName(viewer: PresenceAvatarViewer) {
+    return viewer.name || viewer.email || 'Unknown'
+}
+
+function viewerKey(viewer: PresenceAvatarViewer, index: number) {
+    return viewer.email || viewer.name || `viewer-${index}`
+}
+
+function statusLabel(viewer: PresenceAvatarViewer) {
+    if (isActive(viewer))
+        return props.viewingLabel
+    if (viewer.awaySince != null && props.awaySinceLabel)
+        return props.awaySinceLabel(viewer.awaySince)
+    return props.awayLabel
+}
+</script>
+
+<template>
+    <TelaTooltipGroup v-if="viewers.length > 0">
+        <div
+            role="group"
+            :aria-label="`${viewers.length} ${label}`"
+            flex items-center
+            :class="variant === 'pill' ? 'gap-6px rounded-8px bg-muted py-4px pl-10px pr-8px' : ''"
+        >
+            <TelaTooltipGroupTrigger v-if="variant === 'pill'" side="bottom" trigger-class="flex">
+                <span body-12-medium text-primary leading-16px>{{ resolvedCountLabel }}</span>
+                <template #content>
+                    <div flex="~ col" gap-4px text-left>
+                        <p
+                            v-for="(viewer, index) in tooltipViewers"
+                            :key="viewerKey(viewer, index)"
+                            body-12-regular text-white leading-16px
+                        >
+                            {{ displayName(viewer) }}
+                        </p>
+                        <p v-if="hiddenTooltipCount > 0" body-12-regular text-white leading-16px>
+                            {{ moreLabel(hiddenTooltipCount) }}
+                        </p>
+                    </div>
+                </template>
+            </TelaTooltipGroupTrigger>
+
+            <TransitionGroup name="tela-presence" tag="div" flex items-center :style="stackStyle">
+                <div
+                    v-for="(viewer, index) in visibleViewers"
+                    :key="viewerKey(viewer, index)"
+                    class="tela-presence-avatar"
+                    flex
+                >
+                    <TelaTooltipGroupTrigger side="bottom" trigger-class="flex">
+                        <div relative flex>
+                            <TelaAvatar
+                                :image="viewer.image"
+                                :alt="displayName(viewer)"
+                                :size="resolvedSize"
+                                rounded-full transition-opacity duration-160 ease-out
+                                :class="isActive(viewer) || isOverflowSlot(index) ? '' : 'op-50'"
+                            />
+                            <div
+                                v-if="isOverflowSlot(index)"
+                                absolute inset-0 rounded-full
+                                class="bg-neutral-950/80"
+                                flex items-center justify-center
+                                text-white font-500 leading-none select-none
+                                :style="overflowTextStyle"
+                            >
+                                +{{ overflowCount }}
+                            </div>
+                        </div>
+                        <template #content>
+                            <div v-if="isOverflowSlot(index)" flex="~ col" gap-4px text-left>
+                                <p
+                                    v-for="(tooltipViewer, tooltipIndex) in tooltipViewers"
+                                    :key="viewerKey(tooltipViewer, tooltipIndex)"
+                                    body-12-regular text-white leading-16px
+                                >
+                                    {{ displayName(tooltipViewer) }}
+                                </p>
+                                <p v-if="hiddenTooltipCount > 0" body-12-regular text-white leading-16px>
+                                    {{ moreLabel(hiddenTooltipCount) }}
+                                </p>
+                            </div>
+                            <div v-else flex="~ col" gap-2px text-left>
+                                <span body-12-medium text-white>{{ displayName(viewer) }}</span>
+                                <span body-12-regular text-neutral-200>{{ statusLabel(viewer) }}</span>
+                            </div>
+                        </template>
+                    </TelaTooltipGroupTrigger>
+                </div>
+            </TransitionGroup>
+        </div>
+    </TelaTooltipGroup>
+</template>
+
+<style scoped>
+.tela-presence-avatar:not(:first-child) {
+    margin-left: calc(var(--presence-overlap) * -1);
+}
+
+.tela-presence-avatar:not(:last-child) {
+    mask-image: radial-gradient(circle var(--presence-mask-radius) at var(--presence-mask-x) center, transparent var(--presence-mask-radius), #fff var(--presence-mask-radius));
+}
+
+.tela-presence-enter-active,
+.tela-presence-leave-active {
+    transition: opacity 160ms cubic-bezier(0.215, 0.61, 0.355, 1), transform 160ms cubic-bezier(0.215, 0.61, 0.355, 1);
+}
+
+.tela-presence-enter-from,
+.tela-presence-leave-to {
+    opacity: 0;
+    transform: scale(0.8);
+}
+
+.tela-presence-move {
+    transition: transform 160ms cubic-bezier(0.215, 0.61, 0.355, 1);
+}
+</style>

package/components/tela/tooltip/tooltip-body.vue

@@ -0,0 +1,66 @@
+<script setup lang="ts">
+import { TooltipArrow } from 'reka-ui'
+import TelaTooltipContent from './tooltip-content.vue'
+
+export type TooltipBodyProps = {
+    content?: string
+    align?: 'start' | 'center' | 'end'
+    side?: 'top' | 'right' | 'bottom' | 'left'
+    contentClass?: string
+    alignOffset?: number
+    arrowOffset?: number
+    variant?: 'single' | 'multiline'
+    title?: string
+    description?: string
+}
+
+const props = withDefaults(defineProps<TooltipBodyProps>(), {
+    variant: 'single',
+})
+
+defineEmits<{
+    (e: 'clickContent', event: Event): void
+}>()
+
+const variantClasses = computed(() => {
+    if (props.variant === 'multiline') {
+        return 'w-full min-w-255px max-w-320px py-12px pl-16px pr-24px text-left'
+    }
+
+    return ''
+})
+</script>
+
+<template>
+    <TelaTooltipContent
+        :align="align"
+        :side="side"
+        :align-offset="props.alignOffset"
+        :class="cn(contentClass, variantClasses)"
+        @click="$emit('clickContent', $event)"
+    >
+        <slot>
+            <div v-if="variant === 'multiline' && (title || description)" class="max-h-96 overflow-y-auto">
+                <h3
+                    v-if="title"
+                    body-14-semibold text-white
+                >
+                    {{ title }}
+                </h3>
+                <p
+                    v-if="description"
+                    body-12-regular mt-2px class="text-white/85"
+                >
+                    {{ description }}
+                </p>
+            </div>
+            <template v-else>
+                {{ content }}
+            </template>
+        </slot>
+        <TooltipArrow
+            class="fill-neutral-800"
+            :style="props.arrowOffset ? { transform: `translateX(${props.arrowOffset}px)` } : {}"
+        />
+    </TelaTooltipContent>
+</template>

package/components/tela/tooltip/tooltip-content.vue

@@ -1,16 +1,15 @@
 <script setup lang="ts">
-import { TooltipContent, TooltipPortal, useForwardPropsEmits } from 'reka-ui'
+import { TooltipContent, TooltipPortal, injectTooltipRootContext, useForwardPropsEmits } from 'reka-ui'
 import type { TooltipContentEmits, TooltipContentProps } from 'reka-ui'
 import { reactiveOmit } from '@vueuse/core'
-import { inject } from 'vue'
-import type { HTMLAttributes } from 'vue'
+import type { HTMLAttributes, ShallowRef } from 'vue'
 
 defineOptions({
     inheritAttrs: false,
 })
 
 const props = withDefaults(defineProps<TooltipContentProps & { class?: HTMLAttributes['class'] }>(), {
-    sideOffset: 4,
+    sideOffset: 2,
 })
 
 const emits = defineEmits<TooltipContentEmits & {
@@ -22,22 +21,73 @@ const delegatedProps = reactiveOmit(props, 'class')
 const forwarded = useForwardPropsEmits(delegatedProps, emits)
 
 const disablePortal = inject<boolean>('tela-disable-tooltip-portal', false)
+
+const id = Symbol('tela-tooltip')
+const activeId = inject<ShallowRef<symbol | null> | null>('tela-tooltip-active-id', null)
+const { open } = injectTooltipRootContext()
+
+watch(open, (isOpen) => {
+    if (!activeId) {
+        return
+    }
+
+    if (isOpen) {
+        activeId.value = id
+    }
+    else if (activeId.value === id) {
+        activeId.value = null
+    }
+})
+
+const isGrouped = computed(() => activeId !== null && activeId.value !== null && activeId.value !== id)
 </script>
 
 <template>
     <TooltipPortal :disabled="disablePortal">
         <TooltipContent
             v-bind="{ ...forwarded, ...$attrs }"
-            :style="{ pointerEvents: 'auto' }"
-            z-1000 overflow-hidden rounded-12px
-            py-7px px-12px
+            z-1000 relative rounded-8px
+            py-5px px-10px pointer-events-auto
             body-12-semibold text-white
-            shadow-flying
-            class="bg-[#030C16F0]"
-            :class="props.class"
+            bg-neutral-800
+            :class="cn('tooltip-content', props.class)"
+            :data-grouped="isGrouped || undefined"
             @click="$emit('click', $event)"
         >
             <slot />
         </TooltipContent>
     </TooltipPortal>
 </template>
+
+<style>
+.tooltip-content {
+    transform-origin: var(--reka-tooltip-content-transform-origin);
+    animation: tooltip-in 0.125s ease-out;
+
+    &[data-state='closed'] {
+        animation: tooltip-out 0.125s ease-out forwards;
+    }
+
+    &[data-state='instant-open'] {
+        animation: none;
+    }
+
+    &[data-state='closed'][data-grouped] {
+        animation-duration: 0ms;
+    }
+}
+
+@keyframes tooltip-in {
+    from {
+        opacity: 0;
+        transform: scale(0.97);
+    }
+}
+
+@keyframes tooltip-out {
+    to {
+        opacity: 0;
+        transform: scale(0.97);
+    }
+}
+</style>

package/components/tela/tooltip/tooltip-provider.vue

@@ -3,6 +3,10 @@ import { TooltipProvider } from 'reka-ui'
 import type { TooltipProviderProps } from 'reka-ui'
 
 const props = defineProps<TooltipProviderProps>()
+
+// Tracks which tooltip in this provider is currently open, so a closing tooltip
+// can tell whether a sibling took over (instant swap) or it is just leaving (exit animation).
+provide('tela-tooltip-active-id', shallowRef<symbol | null>(null))
 </script>
 
 <template>

package/components/tela/tooltip/tooltip.vue

@@ -1,24 +1,14 @@
 <script setup lang="ts">
-import { TooltipArrow } from 'reka-ui'
 import TelaTooltipProvider from './tooltip-provider.vue'
 import TelaTooltipRoot from './tooltip-root.vue'
 import TelaTooltipTrigger from './tooltip-trigger.vue'
-import TelaTooltipContent from './tooltip-content.vue'
-import { computed } from 'vue'
+import TelaTooltipBody from './tooltip-body.vue'
+import type { TooltipBodyProps } from './tooltip-body.vue'
 
-export type TooltipProps = {
-    content?: string
-    align?: 'start' | 'center' | 'end'
-    side?: 'top' | 'right' | 'bottom' | 'left'
-    contentClass?: string
+export type TooltipProps = TooltipBodyProps & {
     disabled?: boolean
     delayDuration?: number
     open?: boolean
-    alignOffset?: number
-    arrowOffset?: number
-    variant?: 'single' | 'multiline'
-    title?: string
-    description?: string
     triggerClass?: string
 }
 
@@ -40,13 +30,6 @@ const tooltipRootProps = computed(() => {
 
     return rootProps
 })
-
-const variantClasses = computed(() => {
-    if (props.variant === 'multiline') {
-        return 'w-full min-w-255px max-w-320px pt-12px pb-16px px-16px gap-12px flex flex-col text-left max-h-96 overflow-y-auto'
-    }
-    return ''
-})
 </script>
 
 <template>
@@ -55,36 +38,22 @@ const variantClasses = computed(() => {
             <TelaTooltipTrigger :class="triggerClass" :tabindex="-1">
                 <slot />
             </TelaTooltipTrigger>
-            <TelaTooltipContent
+            <TelaTooltipBody
+                :content="content"
                 :align="align"
                 :side="side"
-                :align-offset="props.alignOffset"
-                :class="cn(contentClass, variantClasses)"
-                @click="$emit('clickContent', $event)"
+                :content-class="contentClass"
+                :align-offset="alignOffset"
+                :arrow-offset="arrowOffset"
+                :variant="variant"
+                :title="title"
+                :description="description"
+                @click-content="$emit('clickContent', $event)"
             >
-                <slot name="content">
-                    <div v-if="variant === 'multiline' && (title || description)">
-                        <div
-                            v-if="title"
-                            class="text-white font-inter text-14px leading-16px not-italic font-580 tracking--0.14px"
-                        >
-                            {{ title }}
-                        </div>
-                        <div
-                            v-if="description"
-                            class="body-12-regular text-gray-200 mt-[4px] break-words whitespace-pre-line w-full"
-                        >
-                            {{ description }}
-                        </div>
-                    </div>
-                    <template v-else>
-                        {{ content }}
-                    </template>
-                </slot>
-                <TooltipArrow
-                    :style="props.arrowOffset ? { transform: `translateX(${props.arrowOffset}px)` } : {}"
-                />
-            </TelaTooltipContent>
+                <template v-if="$slots.content" #default>
+                    <slot name="content" />
+                </template>
+            </TelaTooltipBody>
         </TelaTooltipRoot>
     </TelaTooltipProvider>
 </template>