@startsimpli/ui 0.4.93 → 0.4.94

package/src/components/states/Footnote.tsx

@@ -0,0 +1,171 @@
+'use client'
+
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+import { Caveat } from './Caveat'
+
+interface FootnoteRegistry {
+  /** Distinct notes in the order they were first claimed. */
+  notes: string[]
+  register: (note: string) => void
+  unregister: (note: string) => void
+  noteId: (index: number) => string
+}
+
+const FootnoteContext = React.createContext<FootnoteRegistry | null>(null)
+
+export interface FootnoteScopeProps {
+  children: React.ReactNode
+  /** Accessible name for the collected list. */
+  label?: string
+  className?: string
+  listClassName?: string
+}
+
+/**
+ * Collects the notes its children claim and prints each distinct one ONCE,
+ * underneath them.
+ *
+ * A caveat that belongs to seven tiles used to be authored inside the tile,
+ * which printed it seven times. Authored as a {@link Footnote} inside a scope,
+ * the same sentence is said once per section and each tile carries only a
+ * marker pointing at it.
+ */
+export function FootnoteScope({
+  children,
+  label = 'Notes',
+  className,
+  listClassName,
+}: FootnoteScopeProps) {
+  const scopeId = React.useId().replace(/:/g, '')
+  const counts = React.useRef<Map<string, number>>(new Map())
+  const [notes, setNotes] = React.useState<string[]>([])
+
+  const register = React.useCallback((note: string) => {
+    const next = (counts.current.get(note) ?? 0) + 1
+    counts.current.set(note, next)
+    if (next === 1) {
+      setNotes((prev) => (prev.includes(note) ? prev : [...prev, note]))
+    }
+  }, [])
+
+  const unregister = React.useCallback((note: string) => {
+    const next = (counts.current.get(note) ?? 1) - 1
+    if (next > 0) {
+      counts.current.set(note, next)
+      return
+    }
+    counts.current.delete(note)
+    setNotes((prev) => prev.filter((existing) => existing !== note))
+  }, [])
+
+  const noteId = React.useCallback(
+    (index: number) => `footnote-${scopeId}-${index}`,
+    [scopeId],
+  )
+
+  const registry = React.useMemo<FootnoteRegistry>(
+    () => ({ notes, register, unregister, noteId }),
+    [notes, register, unregister, noteId],
+  )
+
+  return (
+    <FootnoteContext.Provider value={registry}>
+      <div className={cn('space-y-4', className)}>
+        {children}
+        {notes.length > 0 && (
+          <ol
+            aria-label={label}
+            className={cn(
+              'space-y-1 border-t border-border/60 pt-3 text-start',
+              listClassName,
+            )}
+          >
+            {notes.map((note, index) => (
+              <li
+                key={note}
+                id={noteId(index + 1)}
+                tabIndex={-1}
+                className="text-xs leading-relaxed text-muted-foreground"
+              >
+                <span aria-hidden="true" className="me-1 font-medium tabular-nums">
+                  {index + 1}.
+                </span>
+                {note}
+              </li>
+            ))}
+          </ol>
+        )}
+      </div>
+    </FootnoteContext.Provider>
+  )
+}
+
+export interface FootnoteProps {
+  /** The sentence that should be said once per scope, however many items carry it. */
+  note: string
+  /** What the note qualifies — used when there is no scope to collect it. */
+  subject?: string
+  className?: string
+}
+
+/**
+ * A marker standing in for a note that belongs to the whole section.
+ *
+ * Inside a {@link FootnoteScope} it renders as a numbered reference to the one
+ * copy of the sentence printed under the section. With no scope above it, the
+ * note is not dropped — it falls back to a {@link Caveat} disclosure, so the
+ * information survives wherever the component is used.
+ */
+export function Footnote({ note, subject, className }: FootnoteProps) {
+  const scope = React.useContext(FootnoteContext)
+  const register = scope?.register
+  const unregister = scope?.unregister
+
+  React.useEffect(() => {
+    if (!register || !unregister) return
+    register(note)
+    return () => unregister(note)
+  }, [register, unregister, note])
+
+  if (!scope) {
+    return (
+      <Caveat label="Note" subject={subject} className={className}>
+        {note}
+      </Caveat>
+    )
+  }
+
+  const index = scope.notes.indexOf(note) + 1
+  const markerClass = cn(
+    'ms-0.5 inline-block align-super text-[10px] font-semibold leading-none tabular-nums text-muted-foreground',
+    className,
+  )
+
+  // Until the effect has registered the note there is no number to point at.
+  // A stable placeholder keeps the marker's footprint identical either way.
+  if (index === 0) {
+    return (
+      <span className={markerClass} data-footnote="pending">
+        <span aria-hidden="true">·</span>
+      </span>
+    )
+  }
+
+  const targetId = scope.noteId(index)
+
+  return (
+    <a
+      href={`#${targetId}`}
+      aria-describedby={targetId}
+      data-footnote={index}
+      className={cn(
+        markerClass,
+        'rounded underline-offset-2 hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+      )}
+    >
+      <span aria-hidden="true">{index}</span>
+      <span className="sr-only">{`Note ${index}`}</span>
+    </a>
+  )
+}