@igstack/app-catalog-frontend-core 6.9.0 → 6.10.1

package/src/modules/appCatalog/ui/detail/CommunityInput.tsx

@@ -0,0 +1,419 @@
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { Paperclip, X } from 'lucide-react'
+import React from 'react'
+import { useTRPC } from '~/api/infra/trpc'
+import { cn } from '~/lib/utils'
+import { Button } from '~/ui/button'
+import {
+  attachmentUrl,
+  readAttachments,
+  readDraft,
+  writeAttachments,
+  writeDraft,
+} from './communityDraft'
+import type { PendingImage } from './communityDraft'
+import { formatCommunityError } from './communityError'
+
+const MAX_HEIGHT = 200
+
+/** How long the Share highlight stays on the field, ms. */
+const FLASH_MS = 900
+
+/** Mirrors the server's cap, which refuses anything above it regardless. */
+const MAX_ATTACHMENTS = 3
+
+const UPLOAD_URL = '/api/feedback-attachments/upload'
+
+/** What the card holds on to, so "Share what you know" can point at the field. */
+export interface CommunityInputHandle {
+  /** Focuses the field and highlights it briefly. Re-triggers on every call. */
+  focus: () => void
+}
+
+const isImage = (file: File) => file.type.startsWith('image/')
+
+/**
+ * Upload on pick, not on send: the person sees whether their screenshot
+ * arrived while they can still do something about it, and Send stays one fast
+ * request that cannot half-fail with images in flight.
+ */
+async function upload(files: File[]): Promise<string[] | string> {
+  const form = new FormData()
+  for (const file of files) form.append('image', file)
+  try {
+    const response = await fetch(UPLOAD_URL, {
+      method: 'POST',
+      body: form,
+      // The visitor cookie is the identity the upload is recorded against, and
+      // it is httpOnly — so it has to ride along explicitly.
+      credentials: 'same-origin',
+    })
+    const payload: unknown = await response.json().catch(() => null)
+    const field = (key: string): unknown =>
+      typeof payload === 'object' && payload !== null
+        ? (payload as Record<string, unknown>)[key]
+        : undefined
+    const ids = field('ids')
+    if (response.ok && Array.isArray(ids)) return ids.map(String)
+    const reported = field('error')
+    return typeof reported === 'string'
+      ? reported
+      : 'Could not attach that image'
+  } catch {
+    return 'Could not attach that image'
+  }
+}
+
+/**
+ * The card's one ask for more information, at the top of Behind this card:
+ * one line with Send beside it, grey until there is something to send. The
+ * field grows as the text wraps. Screenshots come in through the
+ * paperclip, paste or drop, and a screenshot alone is a valid note.
+ */
+export function CommunityInput({
+  appSlug,
+  appName,
+  ref,
+}: {
+  appSlug: string
+  appName: string
+  ref?: React.Ref<CommunityInputHandle>
+}) {
+  const trpc = useTRPC()
+  const queryClient = useQueryClient()
+  // Seeded from storage so a draft survives the tab panel unmounting under it.
+  const [text, setText] = React.useState(() => readDraft(appSlug))
+  const [images, setImages] = React.useState<PendingImage[]>(() =>
+    readAttachments(appSlug),
+  )
+  const [sent, setSent] = React.useState(false)
+  // Counts successful sends, so a click on Send hands focus back every time.
+  const [sends, setSends] = React.useState(0)
+  const [uploading, setUploading] = React.useState(false)
+  const [uploadError, setUploadError] = React.useState<string | null>(null)
+  const [dragging, setDragging] = React.useState(false)
+  // The guard events read, set synchronously: `uploading` only updates on the
+  // next render, so a second paste or drop in the same tick would slip past it.
+  const inFlightRef = React.useRef(false)
+  const dragDepthRef = React.useRef(0)
+  // Cleared draft stays cleared: Esc increments this; the upload checks it
+  // on completion so an in-flight upload does not re-add its image.
+  const draftGenRef = React.useRef(0)
+  const [height, setHeight] = React.useState(40)
+  const fieldRef = React.useRef<HTMLTextAreaElement>(null)
+  // A hidden twin measures the height the text needs, so the real field can
+  // animate to it. Setting `height: auto` on the real one snaps instead.
+  const mirrorRef = React.useRef<HTMLTextAreaElement>(null)
+  const fileRef = React.useRef<HTMLInputElement>(null)
+  const formRef = React.useRef<HTMLFormElement>(null)
+  const flashTimerRef = React.useRef<ReturnType<typeof setTimeout>>(undefined)
+
+  // Detect coarse pointer (touch) to adjust placeholder and hide keyboard hints.
+  const [isCoarse, setIsCoarse] = React.useState(() => {
+    if (typeof window === 'undefined') return false
+    return window.matchMedia('(pointer: coarse)').matches
+  })
+  React.useEffect(() => {
+    if (typeof window === 'undefined') return
+    const mq = window.matchMedia('(pointer: coarse)')
+    const handler = () => setIsCoarse(mq.matches)
+    mq.addEventListener('change', handler)
+    return () => mq.removeEventListener('change', handler)
+  }, [])
+
+  React.useEffect(() => writeDraft(appSlug, text), [appSlug, text])
+  React.useEffect(() => writeAttachments(appSlug, images), [appSlug, images])
+
+  // The class goes on the form, whose className React never rewrites, and
+  // is removed and re-added with a reflow between so a second call restarts
+  // the highlight instead of merely extending it.
+  React.useImperativeHandle(ref, () => ({
+    focus: () => {
+      fieldRef.current?.focus()
+      const form = formRef.current
+      if (!form) return
+      form.classList.remove('is-flash')
+      void form.offsetWidth
+      form.classList.add('is-flash')
+      clearTimeout(flashTimerRef.current)
+      flashTimerRef.current = setTimeout(
+        () => form.classList.remove('is-flash'),
+        FLASH_MS,
+      )
+    },
+  }))
+  React.useEffect(() => () => clearTimeout(flashTimerRef.current), [])
+
+  const add = useMutation(
+    trpc.feedback.add.mutationOptions({
+      onSuccess: () => {
+        setText('')
+        setImages([])
+        setUploadError(null)
+        setSent(true)
+        setSends((n) => n + 1)
+        void queryClient.invalidateQueries({
+          queryKey: trpc.feedback.list.queryKey({ resourceSlug: appSlug }),
+        })
+      },
+    }),
+  )
+
+  // Focus stays in the field so the next Tab doesn't walk the grid behind the scrim.
+  React.useEffect(() => {
+    if (sends) fieldRef.current?.focus()
+  }, [sends])
+
+  const typing = text.trim() !== ''
+  const canSend = typing || images.length > 0
+
+  const fit = React.useCallback(() => {
+    const field = fieldRef.current
+    const mirror = mirrorRef.current
+    if (!field || !mirror) return
+    mirror.style.width = `${field.offsetWidth}px`
+    mirror.value = text || ' '
+    // Compute ONE_LINE from the actual field styles (varies by viewport width).
+    const styles = window.getComputedStyle(field)
+    const lineHeight = parseFloat(styles.lineHeight)
+    const paddingTop = parseFloat(styles.paddingTop)
+    const paddingBottom = parseFloat(styles.paddingBottom)
+    const borderTop = parseFloat(styles.borderTopWidth)
+    const borderBottom = parseFloat(styles.borderBottomWidth)
+    const oneLine =
+      lineHeight + paddingTop + paddingBottom + borderTop + borderBottom
+    // +2: scrollHeight excludes the border, the box height includes it.
+    setHeight(Math.min(Math.max(mirror.scrollHeight + 2, oneLine), MAX_HEIGHT))
+  }, [text])
+  React.useLayoutEffect(fit, [fit])
+  React.useEffect(() => {
+    const field = fieldRef.current
+    if (!field || typeof ResizeObserver === 'undefined') return
+    const observer = new ResizeObserver(fit)
+    observer.observe(field)
+    return () => observer.disconnect()
+  }, [fit])
+
+  /**
+   * One upload at a time: a paste or drop while one is in flight is ignored,
+   * and the "Attaching…" line says why. The updater clamps as well, so the
+   * draft can never hold more than the server accepts on send.
+   */
+  const attach = async (picked: File[]) => {
+    const files = picked.filter(isImage)
+    if (files.length === 0 || inFlightRef.current) return
+    const room = MAX_ATTACHMENTS - images.length
+    if (room <= 0) {
+      setUploadError(`Up to ${MAX_ATTACHMENTS} images`)
+      return
+    }
+    setUploadError(null)
+    inFlightRef.current = true
+    setUploading(true)
+    const startGen = draftGenRef.current
+    const result = await upload(files.slice(0, room))
+    inFlightRef.current = false
+    setUploading(false)
+    // Draft was cleared (Esc) while upload was in flight: stay cleared.
+    if (draftGenRef.current !== startGen) return
+    if (typeof result === 'string') {
+      setUploadError(result)
+      return
+    }
+    const newImages = result.map((id, i) => ({
+      id,
+      name: files[i]?.name ?? 'image',
+    }))
+    // Merge into both state and persisted draft so unmount restores it.
+    setImages((current) => {
+      const updated = [...current, ...newImages].slice(0, MAX_ATTACHMENTS)
+      writeAttachments(appSlug, updated)
+      return updated
+    })
+    if (files.length > room)
+      setUploadError(`Only the first ${room} were attached`)
+  }
+
+  /** Only a drag carrying files is ours; dragged text still drops into the field. */
+  const carriesFiles = (e: React.DragEvent) =>
+    [...e.dataTransfer.types].includes('Files')
+
+  const submit = () => {
+    if (!canSend || add.isPending || uploading) return
+    const body = text.trim()
+    add.mutate({
+      resourceSlug: appSlug,
+      ...(body ? { body } : {}),
+      ...(images.length > 0 ? { attachmentIds: images.map((i) => i.id) } : {}),
+    })
+  }
+
+  return (
+    <form
+      ref={formRef}
+      // State rides on data attributes: the className stays static so the
+      // imperative `is-flash` below survives a re-render.
+      className="know-more"
+      data-drop={dragging || undefined}
+      onSubmit={(e) => {
+        e.preventDefault()
+        submit()
+      }}
+      onDragEnter={(e) => {
+        if (!carriesFiles(e)) return
+        dragDepthRef.current += 1
+        setDragging(true)
+      }}
+      onDragOver={(e) => {
+        // Accepting the drop is what lets it fire.
+        if (carriesFiles(e)) e.preventDefault()
+      }}
+      onDragLeave={(e) => {
+        if (!carriesFiles(e)) return
+        // Every child the drag crosses fires its own enter and leave, so only
+        // the last leave means the drag left the form.
+        dragDepthRef.current = Math.max(0, dragDepthRef.current - 1)
+        if (dragDepthRef.current === 0) setDragging(false)
+      }}
+      onDrop={(e) => {
+        if (!carriesFiles(e)) return
+        e.preventDefault()
+        dragDepthRef.current = 0
+        setDragging(false)
+        void attach([...e.dataTransfer.files])
+      }}
+    >
+      {images.length > 0 && (
+        <ul className="know-more-thumbs">
+          {images.map((image) => (
+            <li key={image.id} className="know-more-thumb">
+              <img src={attachmentUrl(image.id)} alt={image.name} />
+              <button
+                type="button"
+                aria-label={`Remove ${image.name}`}
+                onClick={() =>
+                  setImages((current) =>
+                    current.filter((i) => i.id !== image.id),
+                  )
+                }
+              >
+                <X className="size-2.5" />
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+      <div className="know-more-field">
+        <button
+          type="button"
+          className="know-more-clip"
+          aria-label="Attach a screenshot"
+          title="Attach a screenshot"
+          aria-busy={uploading || undefined}
+          disabled={uploading || images.length >= MAX_ATTACHMENTS}
+          onClick={() => fileRef.current?.click()}
+        >
+          <Paperclip className="size-4" />
+        </button>
+        <input
+          ref={fileRef}
+          type="file"
+          accept="image/*"
+          multiple
+          tabIndex={-1}
+          aria-hidden
+          className="sr-only"
+          onChange={(e) => {
+            void attach([...(e.target.files ?? [])])
+            // Cleared so picking the SAME file again still fires a change.
+            e.target.value = ''
+          }}
+        />
+        <textarea
+          ref={fieldRef}
+          rows={1}
+          value={text}
+          aria-label={`Know more about ${appName}?`}
+          placeholder={
+            isCoarse
+              ? 'Add a fact, a fix or a question'
+              : 'Add a fact, a fix or a question — press Enter'
+          }
+          style={{
+            height,
+            overflowY: height >= MAX_HEIGHT ? 'auto' : 'hidden',
+          }}
+          onChange={(e) => {
+            setText(e.target.value)
+            setSent(false)
+            if (add.isError) add.reset()
+          }}
+          onPaste={(e) => {
+            const files = [...e.clipboardData.files].filter(isImage)
+            if (files.length === 0) return
+            e.preventDefault()
+            void attach(files)
+          }}
+          onKeyDown={(e) => {
+            if (
+              e.key === 'Enter' &&
+              !e.shiftKey &&
+              !e.nativeEvent.isComposing
+            ) {
+              e.preventDefault()
+              submit()
+            }
+            // Esc clears a draft, and only a draft: with nothing typed or
+            // attached it must reach the card's layer so the card still closes.
+            if (
+              e.key === 'Escape' &&
+              !e.nativeEvent.isComposing &&
+              (text !== '' || images.length > 0)
+            ) {
+              e.preventDefault()
+              e.stopPropagation()
+              draftGenRef.current += 1
+              setText('')
+              setImages([])
+            }
+          }}
+        />
+        <Button
+          type="submit"
+          size="sm"
+          className="know-more-send"
+          disabled={!canSend || add.isPending || uploading}
+        >
+          Send
+        </Button>
+        <textarea
+          ref={mirrorRef}
+          rows={1}
+          readOnly
+          tabIndex={-1}
+          aria-hidden
+          className="know-more-mirror"
+        />
+      </div>
+      {!isCoarse && (
+        <p className={cn('know-more-hint', typing && 'is-on')}>
+          Enter sends · Shift+Enter new line · Esc clears · paste or drop a
+          screenshot
+        </p>
+      )}
+      <p className="know-more-attaching" aria-live="polite">
+        {uploading ? 'Attaching…' : ''}
+      </p>
+      {(add.isError || uploadError) && (
+        <p role="alert" className="know-more-error">
+          {add.isError
+            ? `Could not send: ${formatCommunityError(add.error)}. Your note is still here.`
+            : uploadError}
+        </p>
+      )}
+      <p role="status" className={cn('know-more-sent', sent && 'is-on')}>
+        {sent ? 'Thanks — sent. It shows below.' : ''}
+      </p>
+    </form>
+  )
+}

package/src/modules/appCatalog/ui/detail/CommunitySection.tsx

@@ -0,0 +1,41 @@
+import type { Claim } from '@igstack/app-catalog-backend-core'
+import React from 'react'
+import { CommentsFeed } from './CommentsFeed'
+import { CommentsHelp } from './CommentsHelp'
+import { CommunityInput } from './CommunityInput'
+import type { CommunityInputHandle } from './CommunityInput'
+
+export type CommunitySectionHandle = CommunityInputHandle
+
+const NO_CLAIMS: Claim[] = []
+
+/**
+ * The top of Behind this card: one input that takes words and screenshots,
+ * then "Comments" with its help, then everything already said about the entry
+ * as one feed.
+ */
+export function CommunitySection({
+  appSlug,
+  appName,
+  claims = NO_CLAIMS,
+  ref,
+}: {
+  appSlug: string
+  appName: string
+  claims?: Claim[]
+  ref?: React.Ref<CommunitySectionHandle>
+}) {
+  const headingId = React.useId()
+  return (
+    <section className="behind-group">
+      <CommunityInput ref={ref} appSlug={appSlug} appName={appName} />
+      <div className="comments-head">
+        <h2 id={headingId} className="behind-group__title">
+          Comments
+        </h2>
+        <CommentsHelp appSlug={appSlug} appName={appName} />
+      </div>
+      <CommentsFeed appSlug={appSlug} claims={claims} labelledBy={headingId} />
+    </section>
+  )
+}

package/src/modules/appCatalog/ui/detail/DetailTabs.tsx

@@ -36,32 +36,13 @@ export interface DetailTab {
 export function DetailTabs({
   tabs,
   forcedTab,
-  requestTab,
-  requestNonce,
   band,
   bandClassName,
+  trailing,
 }: {
   tabs: DetailTab[]
   /** Overrides `?tab=` while set. */
   forcedTab?: string
-  /**
-   * A one-shot "please show this tab" from outside the strip — the band's
-   * "Suggest a change" uses it.
-   *
-   * It has to come through here rather than the caller writing `?tab=` itself:
-   * `useUrlSyncedState` keeps its own `useState` seeded once from the URL and only
-   * ever pushes state OUT to the URL, so a second instance writing the same key
-   * does not update this one. The two then fight — the strip's next render sees the
-   * URL disagreeing with its own state and navigates back over it.
-   */
-  requestTab?: string
-  /**
-   * Bumped by the caller every time it asks again. Without it a repeat request is
-   * indistinguishable from the same standing value, so the effect below does not
-   * re-fire and the second ask does nothing — which is what made the band's
-   * button work exactly once per card.
-   */
-  requestNonce?: number
   /**
    * Identity and actions, shown ABOVE the strip and inside the same tinted
    * surface. Owned here rather than by the caller because the band and the
@@ -72,6 +53,13 @@ export function DetailTabs({
   band?: React.ReactNode
   /** Cancels the dialog's own padding so the tint reaches the card's edges. */
   bandClassName?: string
+  /**
+   * Shown at the right end of the strip, outside the tablist so it is not
+   * announced as a tab. Handed `select` because the strip owns the active tab:
+   * a caller writing `?tab=` itself would fight `useUrlSyncedState`, which keeps
+   * its own state and only pushes it out to the url.
+   */
+  trailing?: (select: (id: string) => void) => React.ReactNode
 }) {
   /**
    * The first tab is what the card opens on, so naming it in the URL says nothing.
@@ -93,29 +81,29 @@ export function DetailTabs({
    * Renaming one would silently drop those onto the first tab, so a retired id
    * keeps resolving to its replacement instead.
    */
-  const RETIRED: Record<string, string> = { metadata: 'documentation' }
+  const RETIRED: Record<string, string> = {
+    metadata: 'documentation',
+    notes: 'behind',
+  }
+
+  /**
+   * Where a link to a tab the entry does not have lands instead. A thin entry
+   * has no Documentation tab, and links to it were mostly about sources and
+   * dates, which Behind this card holds.
+   */
+  const ABSENT: Record<string, string> = {
+    documentation: 'behind',
+  }
 
   /**
    * `forcedTab` picks the tab you ARRIVE on, not the tab you are stuck on.
    *
-   * It used to win over `?tab=` for as long as it was set, and `?sub=` keeps it set
-   * for the whole life of the card — so on any entry reached by a sub-resource
-   * search (667 accounts on one of them) the strip was dead: every click wrote
-   * nothing and the tab never moved. The same override also silently killed the
-   * band's "Suggest a change", which navigates by writing `?tab=`.
-   *
-   * So it applies until the user expresses a preference, and then gets out of the
-   * way. `userChose` is what distinguishes "no opinion yet" from "chose the tab
-   * that happens to be the forced one".
+   * `?sub=` stays set for the card's whole life, so forcing it permanently would
+   * make the strip unclickable. It applies until the user expresses a preference,
+   * and then gets out of the way. `userChose` is what distinguishes "no opinion
+   * yet" from "chose the tab that happens to be the forced one".
    */
   const [userChose, setUserChose] = React.useState(false)
-
-  // Applied when it changes, through the state that actually owns the tab.
-  React.useEffect(() => {
-    if (!requestTab) return
-    setUserChose(true)
-    setUrlTab(requestTab)
-  }, [requestTab, requestNonce, setUrlTab])
   /**
    * Releasing the force must not move the view.
    *
@@ -137,10 +125,27 @@ export function DetailTabs({
   }
 
   const asked = userChose || !forcedTab ? urlTab : forcedTab
-  const requested = RETIRED[asked] ?? asked
+  const retired = RETIRED[asked] ?? asked
+  const requested = ids.includes(retired)
+    ? retired
+    : (ABSENT[retired] ?? retired)
   const activeId = ids.includes(requested) ? requested : (ids[0] ?? '')
   const active = tabs.find((t) => t.id === activeId)
 
+  const select = (id: string) => {
+    setUserChose(true)
+    setUrlTab(id)
+    // Scroll the active tab into view on narrow screens where tabs overflow.
+    requestAnimationFrame(() => {
+      const tabElement = document.getElementById(`detail-tab-${id}`)
+      tabElement?.scrollIntoView({
+        behavior: 'smooth',
+        block: 'nearest',
+        inline: 'center',
+      })
+    })
+  }
+
   // Arrow keys move between tabs, per the tablist pattern. Selection follows
   // focus, which is correct here because every panel is already loaded.
   const onKeyDown = (event: React.KeyboardEvent) => {
@@ -151,8 +156,7 @@ export function DetailTabs({
     const from = ids.indexOf(activeId)
     const next = ids[(from + delta + ids.length) % ids.length]
     if (!next) return
-    setUserChose(true)
-    setUrlTab(next)
+    select(next)
     // Focus follows selection, or the arrow keys would walk the visual
     // selection away from the keyboard's position. By id rather than by
     // position in a NodeList: each tab already carries one, and an id lookup
@@ -164,37 +168,39 @@ export function DetailTabs({
     <>
       <div className={cn('detail-band', bandClassName)}>
         {band}
-        <div role="tablist" className="detail-tabs mt-5" onKeyDown={onKeyDown}>
-          {tabs.map((tab) => {
-            const selected = tab.id === activeId
-            return (
-              <button
-                key={tab.id}
-                type="button"
-                role="tab"
-                id={`detail-tab-${tab.id}`}
-                aria-selected={selected}
-                aria-controls={`detail-panel-${tab.id}`}
-                // Only the selected tab stays in the tab order; the rest are
-                // reached with the arrow keys, as the pattern requires.
-                tabIndex={selected ? 0 : -1}
-                aria-label={tab.ariaLabel}
-                className="detail-tab"
-                onClick={() => {
-                  setUserChose(true)
-                  setUrlTab(tab.id)
-                }}
-              >
-                {tab.label}
-                {tab.chip && (
-                  <span className="detail-tab__chip">{tab.chip}</span>
-                )}
-                {tab.dot && (
-                  <span className="detail-tab__dot" aria-hidden="true" />
-                )}
-              </button>
-            )
-          })}
+        <div className="detail-tabs-row mt-5">
+          <div role="tablist" className="detail-tabs" onKeyDown={onKeyDown}>
+            {tabs.map((tab) => {
+              const selected = tab.id === activeId
+              return (
+                <button
+                  key={tab.id}
+                  type="button"
+                  role="tab"
+                  id={`detail-tab-${tab.id}`}
+                  aria-selected={selected}
+                  aria-controls={`detail-panel-${tab.id}`}
+                  // Only the selected tab stays in the tab order; the rest are
+                  // reached with the arrow keys, as the pattern requires.
+                  tabIndex={selected ? 0 : -1}
+                  aria-label={tab.ariaLabel}
+                  className="detail-tab"
+                  onClick={() => select(tab.id)}
+                >
+                  {tab.label}
+                  {tab.chip && (
+                    <span className="detail-tab__chip">{tab.chip}</span>
+                  )}
+                  {tab.dot && (
+                    <span className="detail-tab__dot" aria-hidden="true" />
+                  )}
+                </button>
+              )
+            })}
+          </div>
+          {trailing && (
+            <div className="detail-tabs-trailing">{trailing(select)}</div>
+          )}
         </div>
       </div>
       {active && (