@alfakit/react 0.0.0-stage → 0.1.0

package/src/components/helpdesk/chat-panel.tsx

@@ -0,0 +1,247 @@
+import type { HelpdeskChatClient } from '@alfakit/core'
+import { SendIcon, XIcon } from 'lucide-react'
+import { useEffect, useId, useRef, type KeyboardEvent } from 'react'
+import { useStore } from '../../hooks/use-store'
+import { cn } from '../../lib/utils'
+import { Button } from '../ui/button'
+import { Input } from '../ui/input'
+import { Spinner } from '../ui/spinner'
+import { Textarea } from '../ui/textarea'
+
+/**
+ * The open live chat: the conversation (a polite live log), the visitor's contact details
+ * before the first message, and the composer. Texts come from the server.
+ */
+export interface HelpdeskChatPanelProps {
+  client: HelpdeskChatClient
+  onClose: () => void
+  className?: string
+}
+
+export function HelpdeskChatPanel({ client, onClose, className }: HelpdeskChatPanelProps) {
+  const state = useStore(client.store)
+  const titleId = useId()
+  const composerId = useId()
+  const emailHintId = useId()
+  const logRef = useRef<HTMLOListElement>(null)
+  const composerRef = useRef<HTMLTextAreaElement>(null)
+  const t = (key: string, fallback: string, replacements: Record<string, string> = {}) =>
+    client.t(key, fallback, replacements)
+  const conversation = state.conversation
+  const started = Boolean(conversation?.key)
+  const closed = Boolean(conversation?.closed)
+  const config = state.config
+
+  useEffect(() => {
+    composerRef.current?.focus()
+  }, [])
+
+  useEffect(() => {
+    const element = logRef.current
+
+    if (element) element.scrollTop = element.scrollHeight
+  }, [conversation?.messages.length, conversation?.agentTyping])
+
+  const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
+    if (event.key === 'Enter' && !event.shiftKey && !event.nativeEvent.isComposing) {
+      event.preventDefault()
+      void client.send()
+    }
+  }
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="false"
+      aria-labelledby={titleId}
+      data-slot="helpdesk-chat"
+      onKeyDown={(event) => {
+        if (event.key === 'Escape') {
+          event.stopPropagation()
+          onClose()
+        }
+      }}
+      className={cn(
+        'bg-background text-foreground flex h-[min(36rem,calc(100svh-7rem))] w-[min(24rem,calc(100vw-2rem))] flex-col overflow-hidden rounded-xl border shadow-xl',
+        className,
+      )}
+    >
+      <header className="bg-primary text-primary-foreground flex items-start gap-2 px-4 py-3">
+        <div className="min-w-0 flex-1">
+          <h2 id={titleId} className="text-sm font-semibold">
+            {t('title', 'Chat with us')}
+          </h2>
+          <p className="text-xs opacity-80">
+            {t('subtitle', 'We usually reply in a few minutes.')}
+          </p>
+        </div>
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon-sm"
+          onClick={onClose}
+          aria-label={t('close', 'Close chat')}
+          className="hover:bg-primary-foreground/10 text-primary-foreground hover:text-primary-foreground -me-2"
+        >
+          <XIcon />
+        </Button>
+      </header>
+
+      <ol
+        ref={logRef}
+        role="log"
+        aria-live="polite"
+        aria-label={t('messages', 'Messages')}
+        className="flex min-h-0 flex-1 flex-col gap-2 overflow-y-auto p-3"
+      >
+        {state.status === 'loading' && !config ? (
+          <li className="m-auto">
+            <Spinner />
+          </li>
+        ) : (
+          <>
+            {config?.greeting && (
+              <li
+                data-from="agent"
+                className="bg-muted max-w-[85%] self-start rounded-2xl rounded-ss-sm px-3 py-2 text-sm"
+              >
+                {config.greeting}
+              </li>
+            )}
+            {conversation?.messages.map((message) => (
+              <li
+                key={message.key}
+                data-from={message.from}
+                className={cn(
+                  'flex max-w-[85%] flex-col gap-0.5',
+                  message.from === 'visitor' ? 'items-end self-end' : 'items-start self-start',
+                )}
+              >
+                <span className="text-muted-foreground px-1 text-xs">{message.name}</span>
+                <div
+                  className={cn(
+                    'prose prose-sm dark:prose-invert max-w-none rounded-2xl px-3 py-2 break-words [&_p]:my-0',
+                    message.from === 'visitor'
+                      ? 'bg-primary text-primary-foreground prose-a:text-primary-foreground rounded-se-sm'
+                      : 'bg-muted rounded-ss-sm',
+                  )}
+                  dangerouslySetInnerHTML={{ __html: message.html }}
+                />
+              </li>
+            ))}
+            {conversation?.agentTyping && (
+              <li
+                role="status"
+                className="text-muted-foreground animate-pulse self-start px-1 text-xs"
+              >
+                {t('typing', ':name is typing…', { name: conversation.agentTyping })}
+              </li>
+            )}
+          </>
+        )}
+      </ol>
+
+      {closed ? (
+        <div className="flex flex-col items-center gap-2 border-t p-3 text-center text-sm">
+          <p className="text-muted-foreground">{t('closed', 'This chat has ended.')}</p>
+          <Button type="button" size="sm" onClick={() => void client.startNew()}>
+            {t('new_chat', 'Start a new chat')}
+          </Button>
+        </div>
+      ) : (
+        <form
+          className="flex flex-col gap-2 border-t p-3"
+          onSubmit={(event) => {
+            event.preventDefault()
+            void client.send()
+          }}
+        >
+          {!started && config?.askContact && (
+            <div className="grid grid-cols-2 gap-2">
+              <Input
+                value={state.name}
+                onChange={(event) => client.setContact({ name: event.target.value })}
+                placeholder={t('name', 'Your name')}
+                aria-label={t('name', 'Your name')}
+                autoComplete="name"
+                maxLength={255}
+              />
+              <Input
+                type="email"
+                value={state.email}
+                onChange={(event) => client.setContact({ email: event.target.value })}
+                placeholder={t('email', 'Your email')}
+                aria-label={t('email', 'Your email')}
+                aria-describedby={emailHintId}
+                autoComplete="email"
+                required={config.requireEmail}
+                maxLength={255}
+              />
+              <p id={emailHintId} className="sr-only">
+                {t('email_hint', 'So we can follow up if you leave.')}
+              </p>
+              {/* People never see or fill this; bots that fill every input do. */}
+              <input
+                type="text"
+                name={config.honeypot}
+                value={state.trap}
+                onChange={(event) => client.setContact({ trap: event.target.value })}
+                tabIndex={-1}
+                autoComplete="off"
+                aria-hidden="true"
+                className="absolute -start-[10000px] size-px overflow-hidden"
+              />
+            </div>
+          )}
+          <label htmlFor={composerId} className="sr-only">
+            {t('message', 'Message')}
+          </label>
+          <div className="flex items-end gap-2">
+            <Textarea
+              ref={composerRef}
+              id={composerId}
+              rows={1}
+              value={state.draft}
+              maxLength={config?.maxLength}
+              onChange={(event) => client.setDraft(event.target.value)}
+              onKeyDown={onKeyDown}
+              placeholder={t('placeholder', 'Write a message…')}
+              aria-invalid={state.error ? true : undefined}
+              className="max-h-32 min-h-10 flex-1 resize-none"
+            />
+            <Button
+              type="submit"
+              size="icon"
+              disabled={state.sending || state.draft.trim() === ''}
+              aria-label={
+                state.sending
+                  ? t('sending', 'Sending…')
+                  : started
+                    ? t('send', 'Send')
+                    : t('start', 'Start chat')
+              }
+            >
+              {state.sending ? <Spinner /> : <SendIcon className="rtl:-scale-x-100" />}
+            </Button>
+          </div>
+          {state.error && (
+            <p role="alert" className="text-destructive text-xs">
+              {state.error}
+            </p>
+          )}
+          {config?.contactUrl && !started && (
+            <a
+              href={config.contactUrl}
+              className="text-muted-foreground self-center text-xs underline-offset-4 hover:underline"
+            >
+              {t('contact', 'Prefer email? Contact us')}
+            </a>
+          )}
+        </form>
+      )}
+      {config?.poweredBy && (
+        <div className="shrink-0" dangerouslySetInnerHTML={{ __html: config.poweredBy }} />
+      )}
+    </div>
+  )
+}

package/src/components/helpdesk/chat-widget.tsx

@@ -0,0 +1,107 @@
+import { HelpdeskChatClient, type HelpdeskChatOptions } from '@alfakit/core'
+import { MessageCircleIcon, XIcon } from 'lucide-react'
+import { useEffect, useId, useRef, useState } from 'react'
+import { useHydrated } from '../../hooks/use-hydrated'
+import { useStore } from '../../hooks/use-store'
+import { lazyComponent } from '../../lib/lazy'
+import { cn } from '../../lib/utils'
+import type { HelpdeskChatPanelProps } from './chat-panel'
+
+const ChatPanel = lazyComponent<HelpdeskChatPanelProps>(
+  () => import('./chat-panel').then((module) => module.HelpdeskChatPanel),
+  () => null,
+)
+
+export interface HelpdeskChatProps extends HelpdeskChatOptions {
+  /** Which corner, in the reading direction (`end` by default: bottom right in LTR). */
+  position?: 'start' | 'end'
+  /** Open on load. */
+  defaultOpen?: boolean
+  /** The launcher's accessible name before the server's texts arrive. */
+  label?: string
+  className?: string
+}
+
+/**
+ * The helpdesk's live chat widget for your public pages (alfasix/alfakit-helpdesk): a
+ * launcher button that opens the chat. The chat's code loads when it is first opened;
+ * nothing renders on the server. Works outside panels (no `AlfakitRoot` needed).
+ *
+ * ```tsx
+ * <HelpdeskChat endpoint="/support/chat" />
+ * ```
+ */
+export function HelpdeskChat({
+  position = 'end',
+  defaultOpen = false,
+  label,
+  className,
+  ...options
+}: HelpdeskChatProps) {
+  const [client] = useState(() => new HelpdeskChatClient(options))
+  const mounted = useHydrated()
+  const state = useStore(client.store)
+  const launcher = useRef<HTMLButtonElement>(null)
+  const panelId = useId()
+
+  useEffect(() => {
+    void client.load()
+
+    if (defaultOpen) client.setOpen(true)
+
+    return () => client.stop()
+  }, [client, defaultOpen])
+
+  if (!mounted || state.config?.enabled === false) return null
+
+  const close = () => {
+    client.setOpen(false)
+    launcher.current?.focus()
+  }
+  const name = state.open ? client.t('close', 'Close chat') : client.t('open', label ?? 'Open chat')
+
+  return (
+    <div
+      data-slot="helpdesk-chat-widget"
+      className={cn(
+        'fixed bottom-4 z-50 flex flex-col gap-3',
+        position === 'end' ? 'end-4 items-end' : 'start-4 items-start',
+        className,
+      )}
+    >
+      {state.open && (
+        <div id={panelId}>
+          <ChatPanel client={client} onClose={close} />
+        </div>
+      )}
+      <button
+        ref={launcher}
+        type="button"
+        aria-expanded={state.open}
+        aria-controls={state.open ? panelId : undefined}
+        aria-label={name}
+        title={name}
+        onClick={() => (state.open ? close() : client.setOpen(true))}
+        onMouseEnter={() => void ChatPanel.preload()}
+        onFocus={() => void ChatPanel.preload()}
+        className="bg-primary text-primary-foreground focus-visible:ring-ring/50 relative flex size-14 items-center justify-center rounded-full shadow-lg transition-transform outline-none hover:scale-105 focus-visible:ring-[3px]"
+      >
+        {state.open ? (
+          <XIcon className="size-6" aria-hidden="true" />
+        ) : (
+          <MessageCircleIcon className="size-6 rtl:-scale-x-100" aria-hidden="true" />
+        )}
+        {!state.open && state.unread > 0 && (
+          <span className="bg-destructive text-destructive-foreground absolute -end-0.5 -top-0.5 flex min-w-5 items-center justify-center rounded-full px-1 text-xs font-semibold">
+            {new Intl.NumberFormat(document.documentElement.lang || undefined).format(state.unread)}
+            <span className="sr-only">
+              {client.t('new_message', 'New message from :name', {
+                name: client.t('agent', 'Support'),
+              })}
+            </span>
+          </span>
+        )}
+      </button>
+    </div>
+  )
+}

package/src/components/helpdesk/inbox-lazy.tsx

@@ -0,0 +1,42 @@
+import type { HelpdeskInboxSchema } from '@alfakit/core'
+import { useT } from '../../context'
+import { lazyComponent } from '../../lib/lazy'
+import { Card } from '../ui/card'
+import { Skeleton } from '../ui/skeleton'
+
+/** The server render and the first paint: the inbox's outline. */
+function HelpdeskInboxSkeleton() {
+  const t = useT()
+
+  return (
+    <Card
+      data-slot="helpdesk-inbox"
+      aria-busy="true"
+      className="grid h-[calc(100svh-12rem)] min-h-[34rem] grid-cols-1 gap-0 overflow-hidden py-0 md:grid-cols-[18rem_1fr] xl:grid-cols-[13rem_20rem_1fr]"
+    >
+      <span className="sr-only">{t('helpdesk.loading', {}, 'Loading…')}</span>
+      <div className="flex flex-col gap-2 border-e p-2 max-xl:hidden" aria-hidden="true">
+        {Array.from({ length: 6 }, (_, index) => (
+          <Skeleton key={index} className="h-7" />
+        ))}
+      </div>
+      <div className="flex flex-col gap-2 border-e p-2" aria-hidden="true">
+        <Skeleton className="h-9" />
+        {Array.from({ length: 6 }, (_, index) => (
+          <Skeleton key={index} className="h-16" />
+        ))}
+      </div>
+      <div className="flex flex-col gap-3 p-4 max-md:hidden" aria-hidden="true">
+        <Skeleton className="h-6 w-1/2" />
+        <Skeleton className="h-24" />
+        <Skeleton className="h-24" />
+      </div>
+    </Card>
+  )
+}
+
+/** The helpdesk inbox; its code loads the first time the inbox is shown. */
+export const HelpdeskInbox = lazyComponent<{ component: HelpdeskInboxSchema }>(
+  () => import('./inbox').then((module) => module.HelpdeskInbox),
+  () => <HelpdeskInboxSkeleton />,
+)