@adea-ai/ui 0.108.0 → 0.109.1

package/src/components/ui/alert-dialog/alert-dialog.tsx

@@ -5,9 +5,14 @@ import {
 // Use the alert-specific export rather than DialogRoot.Content, which other imports can replace.
 import type { ComponentProps } from 'solid-js'
 import { createEffect, createSignal, splitProps } from 'solid-js'
-import { overlayMotion, overlayPositioner, overlayScrim, overlaySurface } from '#lib/overlay'
+import {
+  overlayMotion,
+  overlayPositioner,
+  overlayScrim,
+  overlaySurface,
+  overlayTitle,
+} from '#lib/overlay'
 import { cn } from '#lib/utils'
-import { headingVariants } from '../typography'
 
 /**
  * AlertDialog.
@@ -116,12 +121,7 @@ export function AlertDialogFooter(props: ComponentProps<'div'>) {
 
 export function AlertDialogTitle(props: ComponentProps<typeof KobalteAlertDialog.Title>) {
   const [local, rest] = splitProps(props, ['class'])
-  return (
-    <KobalteAlertDialog.Title
-      class={cn(headingVariants({ size: 'card', leading: 'none' }), local.class)}
-      {...rest}
-    />
-  )
+  return <KobalteAlertDialog.Title class={cn(overlayTitle, local.class)} {...rest} />
 }
 
 export function AlertDialogDescription(

package/src/components/ui/annotation-surface/annotation-surface.css

@@ -0,0 +1,27 @@
+.dev-annotation-surface {
+  touch-action: none;
+  cursor: crosshair;
+  background-image: repeating-linear-gradient(
+    45deg,
+    color-mix(in oklch, var(--muted) 55%, transparent) 0 calc(var(--spacing) * 2),
+    transparent calc(var(--spacing) * 2) calc(var(--spacing) * 4)
+  );
+}
+
+.dev-annotation-surface[data-tool='point'] {
+  cursor: cell;
+}
+
+.dev-annotation-surface[data-dragging='true'] {
+  cursor: grabbing;
+}
+
+.dev-annotation-surface[aria-disabled='true'] {
+  touch-action: auto;
+  cursor: default;
+}
+
+.dev-annotation-surface__region,
+.dev-annotation-surface__hint {
+  pointer-events: none;
+}

package/src/components/ui/annotation-surface/annotation-surface.tsx

@@ -0,0 +1,316 @@
+import {
+  createEffect,
+  createSignal,
+  createUniqueId,
+  onCleanup,
+  Show,
+  splitProps,
+  type JSX,
+} from 'solid-js'
+import { cn } from '#lib/utils'
+import './annotation-surface.css'
+import {
+  clampSurfaceFraction,
+  normalizedSurfacePoint,
+  type AnnotationSurfacePoint,
+} from './geometry'
+
+export type AnnotationSurfaceRegion = Readonly<{
+  x: number
+  y: number
+  width: number
+  height: number
+}>
+
+export type AnnotationSurfaceDrag = Readonly<{
+  start: AnnotationSurfacePoint
+  current: AnnotationSurfacePoint
+}>
+
+export type AnnotationSurfaceTool = 'region' | 'point'
+export type AnnotationSurfaceDragPhase = 'start' | 'move' | 'end' | 'cancel' | 'keyboard'
+export type AnnotationSurfacePointerEvent = PointerEvent & { currentTarget: HTMLDivElement }
+export type AnnotationSurfaceKeyboardEvent = KeyboardEvent & { currentTarget: HTMLDivElement }
+export type AnnotationSurfaceInputEvent =
+  | AnnotationSurfacePointerEvent
+  | AnnotationSurfaceKeyboardEvent
+
+type SurfaceElementProps = Pick<JSX.HTMLAttributes<HTMLDivElement>, 'id' | 'aria-describedby'>
+
+export type AnnotationSurfaceProps = SurfaceElementProps & {
+  /** Accessible instructions for the keyboard-operated surface. */
+  label: string
+  /** Region draws a captured drag; point reports a single placement point. */
+  tool: AnnotationSurfaceTool
+  /** Normalized 0..1 geometry supplied by the host; absent means no region. */
+  region?: AnnotationSurfaceRegion
+  /** Visible idle guidance. It is hidden while a region is present. */
+  hint?: JSX.Element
+  /** Disable new drawing while the host is busy. Defaults to true. */
+  interactive?: boolean
+  /** Changing this value cancels an in-flight drag owned by the host context. */
+  resetKey?: string | number
+  /** Receives one normalized point in point mode. */
+  onPoint?: (point: AnnotationSurfacePoint, event: AnnotationSurfaceInputEvent) => void
+  /** Receives drag phases; cancel has no drag and fires at most once per capture. */
+  onDragChange?: (
+    drag: AnnotationSurfaceDrag | undefined,
+    phase: AnnotationSurfaceDragPhase,
+    event?: AnnotationSurfaceInputEvent
+  ) => void
+  /** Domain keyboard policy stays with the host and receives the native event. */
+  onKeyDown?: (event: AnnotationSurfaceKeyboardEvent) => void
+  /** Ref to the actual focusable and pointer-capturing HTMLDivElement. */
+  ref?: (element: HTMLDivElement) => void
+  /** Layout only; appearance remains owned by the shared component. */
+  class?: string
+}
+
+type ActiveDrag = AnnotationSurfaceDrag & {
+  pointerId: number
+  target: HTMLDivElement
+}
+
+function pointFrom(event: PointerEvent, target: HTMLDivElement): AnnotationSurfacePoint {
+  const bounds = target.getBoundingClientRect()
+  return normalizedSurfacePoint(event.clientX, event.clientY, bounds)
+}
+
+/**
+ * AnnotationSurface.
+ *
+ * A keyboard-focusable, viewport-shaped drawing surface for hosts that own an
+ * annotation domain. It renders normalized region geometry and idle guidance,
+ * captures region drags, and reports normalized points without reading or
+ * rendering screenshot pixels. The host keeps tool policy, domain geometry,
+ * persistence and capture commands.
+ *
+ * This bespoke application widget is necessary because a generic button or
+ * slider cannot represent a two-dimensional drawing viewport. Its keyboard
+ * behavior is supplied by the host and forwarded as a native key event. Space
+ * creates a centered region or places a point at the center; Escape is left to
+ * the host first, which can prevent the default gesture cancellation while it
+ * applies its own draft and mode rules.
+ */
+export function AnnotationSurface(props: AnnotationSurfaceProps) {
+  const [local] = splitProps(props, [
+    'id',
+    'aria-describedby',
+    'label',
+    'tool',
+    'region',
+    'hint',
+    'interactive',
+    'resetKey',
+    'onPoint',
+    'onDragChange',
+    'onKeyDown',
+    'ref',
+    'class',
+  ])
+
+  const [dragging, setDragging] = createSignal(false)
+  const hintId = createUniqueId()
+  let activeDrag: ActiveDrag | undefined
+  let previousResetKey = local.resetKey
+  let previousTool = local.tool
+
+  const isInteractive = () => local.interactive ?? true
+
+  function releaseCapture(drag: ActiveDrag): void {
+    try {
+      if (drag.target.hasPointerCapture(drag.pointerId))
+        drag.target.releasePointerCapture(drag.pointerId)
+    } catch {
+      // The browser may release capture while a host reset or unmount is running.
+    }
+  }
+
+  function cancelDrag(event?: AnnotationSurfaceInputEvent, release = true): void {
+    const drag = activeDrag
+    if (!drag) return
+
+    activeDrag = undefined
+    setDragging(false)
+    if (release) releaseCapture(drag)
+    local.onDragChange?.(undefined, 'cancel', event)
+  }
+
+  createEffect(() => {
+    const resetKey = local.resetKey
+    const tool = local.tool
+    const interactive = isInteractive()
+    if (activeDrag && (resetKey !== previousResetKey || tool !== previousTool || !interactive)) {
+      cancelDrag()
+    }
+    previousResetKey = resetKey
+    previousTool = tool
+  })
+
+  onCleanup(() => cancelDrag())
+
+  function handlePointerDown(event: AnnotationSurfacePointerEvent): void {
+    if (!isInteractive() || !event.isPrimary || event.button !== 0) return
+    event.preventDefault()
+    event.currentTarget.focus({ preventScroll: true })
+    const point = pointFrom(event, event.currentTarget)
+    if (activeDrag) return
+
+    if (local.tool === 'point') {
+      local.onPoint?.(point, event)
+      return
+    }
+
+    try {
+      event.currentTarget.setPointerCapture(event.pointerId)
+    } catch {
+      // A drag without real pointer capture can lose its final coordinates.
+      return
+    }
+
+    const drag: ActiveDrag = {
+      pointerId: event.pointerId,
+      target: event.currentTarget,
+      start: point,
+      current: point,
+    }
+    activeDrag = drag
+    setDragging(true)
+    local.onDragChange?.({ start: point, current: point }, 'start', event)
+  }
+
+  function handlePointerMove(event: AnnotationSurfacePointerEvent): void {
+    const drag = activeDrag
+    if (!drag || drag.pointerId !== event.pointerId) return
+
+    const current = pointFrom(event, event.currentTarget)
+    activeDrag = { ...drag, current }
+    local.onDragChange?.({ start: drag.start, current }, 'move', event)
+  }
+
+  function handlePointerUp(event: AnnotationSurfacePointerEvent): void {
+    const drag = activeDrag
+    if (!drag || drag.pointerId !== event.pointerId) return
+
+    const current = pointFrom(event, event.currentTarget)
+    activeDrag = undefined
+    setDragging(false)
+    releaseCapture(drag)
+    local.onDragChange?.({ start: drag.start, current }, 'end', event)
+  }
+
+  function handlePointerCancel(event: AnnotationSurfacePointerEvent): void {
+    if (activeDrag?.pointerId === event.pointerId) cancelDrag(event)
+  }
+
+  function handleLostPointerCapture(event: AnnotationSurfacePointerEvent): void {
+    if (activeDrag?.pointerId === event.pointerId) cancelDrag(event, false)
+  }
+
+  function handleKeyDown(event: AnnotationSurfaceKeyboardEvent): void {
+    local.onKeyDown?.(event)
+    if (event.key === 'Escape') {
+      if (!event.defaultPrevented) cancelDrag()
+      return
+    }
+    if (
+      event.defaultPrevented ||
+      !isInteractive() ||
+      event.key !== ' ' ||
+      event.repeat ||
+      event.isComposing ||
+      event.altKey ||
+      event.ctrlKey ||
+      event.metaKey ||
+      activeDrag
+    )
+      return
+
+    event.preventDefault()
+    if (local.tool === 'point') {
+      local.onPoint?.({ x: 0.5, y: 0.5 }, event)
+      return
+    }
+
+    local.onDragChange?.(
+      {
+        start: { x: 0.25, y: 0.25 },
+        current: { x: 0.75, y: 0.75 },
+      },
+      'keyboard',
+      event
+    )
+  }
+
+  const visibleRegion = (): AnnotationSurfaceRegion | undefined => {
+    const region = local.region
+    if (!region) return undefined
+    const x = clampSurfaceFraction(region.x)
+    const y = clampSurfaceFraction(region.y)
+    return {
+      x,
+      y,
+      width: Math.min(clampSurfaceFraction(region.width), 1 - x),
+      height: Math.min(clampSurfaceFraction(region.height), 1 - y),
+    }
+  }
+
+  const describedBy = () =>
+    [local['aria-describedby'], local.hint && !visibleRegion() ? hintId : undefined]
+      .filter(Boolean)
+      .join(' ') || undefined
+
+  return (
+    <div
+      id={local.id}
+      aria-describedby={describedBy()}
+      role="application"
+      aria-roledescription="annotation surface"
+      aria-label={local.label}
+      aria-disabled={isInteractive() ? undefined : 'true'}
+      tabIndex={0}
+      data-tool={local.tool}
+      data-dragging={dragging() ? 'true' : 'false'}
+      class={cn(
+        'dev-annotation-surface relative isolate block w-full aspect-video select-none overflow-hidden rounded-md border border-border bg-muted/20 text-muted-foreground outline-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-primary-subtle',
+        local.class
+      )}
+      ref={(element) => local.ref?.(element)}
+      onPointerDown={handlePointerDown}
+      onPointerMove={handlePointerMove}
+      onPointerUp={handlePointerUp}
+      onPointerCancel={handlePointerCancel}
+      onLostPointerCapture={handleLostPointerCapture}
+      onKeyDown={handleKeyDown}
+    >
+      <Show when={visibleRegion()}>
+        {(region) => (
+          <svg
+            class="dev-annotation-surface__region pointer-events-none absolute inset-0 size-full"
+            viewBox="0 0 10000 10000"
+            preserveAspectRatio="none"
+            aria-hidden="true"
+          >
+            <rect
+              class="fill-primary-subtle stroke-primary"
+              x={region().x * 10_000}
+              y={region().y * 10_000}
+              width={region().width * 10_000}
+              height={region().height * 10_000}
+              stroke-width="1.5"
+              vector-effect="non-scaling-stroke"
+            />
+          </svg>
+        )}
+      </Show>
+      <Show when={local.hint && !visibleRegion()}>
+        <span
+          id={hintId}
+          class="dev-annotation-surface__hint pointer-events-none absolute inset-0 grid place-items-center p-4 text-center text-xs text-muted-foreground"
+        >
+          {local.hint}
+        </span>
+      </Show>
+    </div>
+  )
+}

package/src/components/ui/annotation-surface/geometry.ts

@@ -0,0 +1,31 @@
+export type AnnotationSurfacePoint = Readonly<{ x: number; y: number }>
+
+type SurfaceBounds = Readonly<Pick<DOMRectReadOnly, 'left' | 'top' | 'width' | 'height'>>
+
+function fraction(client: number, start: number, length: number): number {
+  if (
+    !Number.isFinite(client) ||
+    !Number.isFinite(start) ||
+    !Number.isFinite(length) ||
+    length <= 0
+  )
+    return 0
+
+  return Math.min(1, Math.max(0, (client - start) / length))
+}
+
+/** Pointer coordinates normalized to the surface; degenerate bounds resolve to the origin. */
+export function normalizedSurfacePoint(
+  clientX: number,
+  clientY: number,
+  bounds: SurfaceBounds
+): AnnotationSurfacePoint {
+  return {
+    x: fraction(clientX, bounds.left, bounds.width),
+    y: fraction(clientY, bounds.top, bounds.height),
+  }
+}
+
+export function clampSurfaceFraction(value: number): number {
+  return Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 0
+}

package/src/components/ui/annotation-surface/index.ts

@@ -0,0 +1,13 @@
+/** Keyboard-operable normalized drawing surface; hosts retain domain geometry and actions. */
+export {
+  AnnotationSurface,
+  type AnnotationSurfaceDrag,
+  type AnnotationSurfaceDragPhase,
+  type AnnotationSurfaceInputEvent,
+  type AnnotationSurfaceKeyboardEvent,
+  type AnnotationSurfacePointerEvent,
+  type AnnotationSurfaceProps,
+  type AnnotationSurfaceRegion,
+  type AnnotationSurfaceTool,
+} from './annotation-surface'
+export type { AnnotationSurfacePoint } from './geometry'

package/src/components/ui/dialog/dialog.tsx

@@ -7,9 +7,14 @@ import {
 import { X } from 'lucide-solid'
 import type { Accessor, ComponentProps, JSX } from 'solid-js'
 import { createRenderEffect, onCleanup, Show, splitProps } from 'solid-js'
-import { overlayMotion, overlayPositioner, overlayScrim, overlaySurface } from '#lib/overlay'
+import {
+  overlayMotion,
+  overlayPositioner,
+  overlayScrim,
+  overlaySurface,
+  overlayTitle,
+} from '#lib/overlay'
 import { cn } from '#lib/utils'
-import { headingVariants } from '../typography'
 
 type FocusCycle = {
   content: HTMLElement
@@ -326,12 +331,7 @@ export function DialogFooter(props: ComponentProps<'div'>) {
 
 export function DialogTitle(props: ComponentProps<typeof KobalteDialog.Title>) {
   const [local, rest] = splitProps(props, ['class'])
-  return (
-    <KobalteDialog.Title
-      class={cn(headingVariants({ size: 'card', leading: 'none' }), local.class)}
-      {...rest}
-    />
-  )
+  return <KobalteDialog.Title class={cn(overlayTitle, local.class)} {...rest} />
 }
 
 export function DialogDescription(props: ComponentProps<typeof KobalteDialog.Description>) {

package/src/components/ui/sheet/sheet.tsx

@@ -8,9 +8,9 @@ import { X } from 'lucide-solid'
 import type { Accessor, ComponentProps, JSX } from 'solid-js'
 import { Show, splitProps } from 'solid-js'
 import { cva, type VariantProps } from '#lib/variants'
+import { overlayTitle } from '#lib/overlay'
 import { cn } from '#lib/utils'
 import { createDialogFocusRestoration, DialogOverlay } from '../dialog/dialog'
-import { headingVariants } from '../typography'
 
 /**
  * Sheet.
@@ -215,12 +215,7 @@ export function SheetFooter(props: ComponentProps<'div'>) {
 
 export function SheetTitle(props: ComponentProps<typeof KobalteDialog.Title>) {
   const [local, rest] = splitProps(props, ['class'])
-  return (
-    <KobalteDialog.Title
-      class={cn(headingVariants({ size: 'card', leading: 'none' }), local.class)}
-      {...rest}
-    />
-  )
+  return <KobalteDialog.Title class={cn(overlayTitle, local.class)} {...rest} />
 }
 
 export function SheetDescription(props: ComponentProps<typeof KobalteDialog.Description>) {

package/src/components/ui/typography/typography.tsx

@@ -25,7 +25,8 @@ import { cn } from '#lib/utils'
  * stack already sets the rhythm (a card or dialog header), and is the only other
  * option.
  */
-export const headingVariants = cva('font-semibold', {
+// cva only returns a closure. A heading-only consumer must discard Text's recipe.
+export const headingVariants = /* @__PURE__ */ cva('font-semibold', {
   variants: {
     size: {
       /** 30px. An app-level headline — a first-run or empty-app screen. Once per app. */
@@ -130,7 +131,7 @@ export function Heading<T extends ValidComponent = 'h2'>(props: HeadingProps<T>)
  *
  * Defaults: `body` renders a `p`, `code` a `code`, every other variant a `span`.
  */
-export const textVariants = cva('', {
+export const textVariants = /* @__PURE__ */ cva('', {
   variants: {
     variant: {
       /** 14px / 400. Body copy and descriptions. */

package/src/index.ts

@@ -18,6 +18,7 @@
 export * from './components/ui/accordion'
 export * from './components/ui/alert'
 export * from './components/ui/alert-dialog'
+export * from './components/ui/annotation-surface'
 export * from './components/ui/aspect-ratio'
 export * from './components/ui/avatar'
 export * from './components/ui/board'

package/src/lib/overlay.ts

@@ -14,6 +14,12 @@
 export const overlaySurface =
   'bg-popover text-popover-foreground rounded-xl border border-border shadow-lg'
 
+/**
+ * Overlay titles have one fixed typography role. Keep this small recipe shared
+ * without loading the configurable Heading component into every dialog.
+ */
+export const overlayTitle = 'font-semibold text-base tracking-tight leading-none'
+
 /** The span of the portal wrapper that centres a dialog-like overlay. */
 export const overlayPositioner = 'fixed inset-0 z-(--z-dialog) grid place-items-center p-4'