@exegia/corpora-ui 0.28.0 → 1.0.0

package/src/components/atoms/text/index.ts

@@ -0,0 +1,24 @@
+import { Text as TextDefault } from "./default"
+import { Heading } from "./heading"
+import { Paragraph } from "./paragraph"
+import { Span } from "./span"
+import { Label } from "./label"
+export type { HeadingProps } from "./heading"
+export type { ParagraphProps } from "./paragraph"
+export type { SpanProps } from "./span"
+export type { TextProps, TextSize, TextVariant } from "./types"
+
+export const Text = {
+  /** The polymorphic base the presets below are built on — the only member
+   * that takes `type`, so it is what reaches `link` and `subscript`. The
+   * presets are reachable through the atoms barrel, and without this it
+   * would not be: `export *` does not carry a default export. */
+  Root: TextDefault,
+  Heading,
+  Paragraph,
+  Span,
+  Label,
+}
+
+export { TextDefault as default }
+

package/src/components/atoms/text/label.tsx

@@ -0,0 +1,16 @@
+import type { LabelProps } from "./types"
+import { cn } from "@/lib/utils"
+import { twLabelClasses } from "./utils"
+export function Label({ children, level = "title", className }: LabelProps) {
+  return (
+    <div
+      className={cn(
+        "leading-1 select-none",
+        level && twLabelClasses[level],
+        className
+      )}
+    >
+      {children}
+    </div>
+  )
+}

package/src/components/atoms/text/paragraph.tsx

@@ -0,0 +1,58 @@
+import { TextSelection } from "../text-selection"
+import type { TextSelectionProps } from "../text-selection"
+import { Text } from "./default"
+import type { TextProps } from "./types"
+import { cn } from "@/lib/utils"
+import { twClasses } from "./utils"
+
+export type ParagraphProps = Omit<TextProps, "type"> &
+  Omit<TextSelectionProps, "children" | "className">
+
+export function Paragraph({
+  children,
+  selected,
+  popover,
+  component,
+  componentProps,
+  popoverComponent,
+  popoverProps,
+  renderPopover,
+  onSelectionStart,
+  onSelectionEnd,
+  onPopoverShow,
+  onPopoverHide,
+  offset,
+  zIndex,
+  alignment,
+  className,
+  minSelectionLength,
+  ...textProps
+}: ParagraphProps) {
+  return (
+    <TextSelection
+      alignment={alignment}
+      component={component}
+      componentProps={componentProps}
+      minSelectionLength={minSelectionLength}
+      offset={offset}
+      onPopoverHide={onPopoverHide}
+      onPopoverShow={onPopoverShow}
+      onSelectionEnd={onSelectionEnd}
+      onSelectionStart={onSelectionStart}
+      popover={popover}
+      popoverComponent={popoverComponent}
+      popoverProps={popoverProps}
+      renderPopover={renderPopover}
+      selected={selected}
+      zIndex={zIndex}
+    >
+      <Text
+        {...textProps}
+        className={cn(twClasses["default"], className)}
+        type="paragraph"
+      >
+        {children}
+      </Text>
+    </TextSelection>
+  )
+}

package/src/components/atoms/text/span.tsx

@@ -0,0 +1,15 @@
+import type { TextProps } from "./types"
+import { Text } from "./default"
+import { cn } from "@/lib/utils"
+
+export type SpanProps = Omit<TextProps, "type">
+
+export function Span(props: SpanProps) {
+  return (
+    <Text
+      {...props}
+      className={cn("select-text selection:bg-transparent", props.className)}
+      type="default"
+    />
+  )
+}

package/src/components/atoms/text/types.ts

@@ -0,0 +1,31 @@
+import type { CSSProperties, HTMLAttributes, ReactNode } from "react"
+
+export type TextVariant =
+  "default" | "heading" | "paragraph" | "link" | "subscript"
+export type TextSize = "small" | "medium" | "large" | number
+
+export type TextProps = Omit<
+  HTMLAttributes<HTMLElement>,
+  "children" | "style"
+> & {
+  id?: string
+  children?: ReactNode
+  className?: string
+  /** Named sizes use the type scale; a number is interpreted as pixels. */
+  size?: TextSize
+  type?: TextVariant
+  href?: string
+  /** Marks a reader selection. A string is also exposed as data-selection. */
+  selection?: string | boolean
+  style?: CSSProperties
+}
+
+export type LabelLevel = "heading" | "title" | "caption" | "subtitle"
+
+export type LabelProps = {
+  children: ReactNode
+  className?: string
+  /** Type scale of the label. Defaults to "title". */
+  level?: LabelLevel
+  id?: string
+}

package/src/components/atoms/text/utils.ts

@@ -0,0 +1,16 @@
+import type { ClassValue } from "clsx"
+import type { LabelProps } from "./types"
+
+export const twClasses: Record<string, ClassValue> = {
+  default: "selection:text-amber-500 dark:selection:text-amber-400",
+}
+
+export const twLabelClasses: Record<
+  NonNullable<LabelProps["level"]>,
+  Element["className"]
+> = {
+  title: "text-lg text-neutral-500",
+  subtitle: "text-md text-neutral-500",
+  caption: "text-xs text-neutral-400 dark:text-neutral-700",
+  heading: "text-sm text-neutral-500"
+}

package/src/components/atoms/text-selection/__tests__/click-popover.test.tsx

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test"
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { TextClickPopover } from "../click-popover"
+
+describe("text click popover", () => {
+  test("clicking the text opens the popover content", async () => {
+    const user = userEvent.setup()
+    render(
+      <TextClickPopover popover={<p>Popover body</p>} size="small">
+        Clickable span
+      </TextClickPopover>
+    )
+
+    expect(screen.queryByText("Popover body")).toBeNull()
+
+    await user.click(screen.getByText("Clickable span"))
+    expect(await screen.findByText("Popover body")).toBeTruthy()
+  })
+
+  test("keeps the text element semantics for link and subscript", async () => {
+    const user = userEvent.setup()
+    render(
+      <>
+        <TextClickPopover popover={<p>Link body</p>} type="link">
+          Link text
+        </TextClickPopover>
+        <TextClickPopover popover={<p>Subscript body</p>} type="subscript">
+          Subscript note
+        </TextClickPopover>
+      </>
+    )
+
+    expect(screen.getByText("Link text").tagName).toBe("A")
+    expect(screen.getByText("Subscript note").tagName).toBe("SUB")
+
+    await user.click(screen.getByText("Subscript note"))
+    expect(await screen.findByText("Subscript body")).toBeTruthy()
+  })
+
+  test("renderPopover receives close and dismisses the popup", async () => {
+    const user = userEvent.setup()
+    render(
+      <TextClickPopover
+        renderPopover={({ close }) => (
+          <button onClick={close} type="button">
+            Dismiss
+          </button>
+        )}
+      >
+        Clickable text
+      </TextClickPopover>
+    )
+
+    await user.click(screen.getByText("Clickable text"))
+    const dismiss = await screen.findByText("Dismiss")
+
+    await user.click(dismiss)
+    expect(screen.queryByText("Dismiss")).toBeNull()
+  })
+})

package/src/components/atoms/text-selection/__tests__/text-selection.test.tsx

@@ -0,0 +1,90 @@
+import { describe, expect, mock, test } from "bun:test"
+import { Provider, createStore } from "jotai"
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { TextSelection } from "../selection"
+import {
+  initialSelectionState,
+  selectionAtom,
+  setSelectionAtom,
+  setSelectionPopoverAtom,
+} from "../selection-atom"
+import { useSelection } from "../use-selection"
+
+function SelectionHarness({
+  onSelectionEnd,
+}: {
+  onSelectionEnd?: (selection: string) => void
+}) {
+  const selection = useSelection({ onSelectionEnd })
+  return (
+    <>
+      <button
+        onClick={() =>
+          selection.selectionProps.onSelectionEnd("selected words")
+        }
+        type="button"
+      >
+        End selection
+      </button>
+      <button
+        onClick={() => selection.selectionProps.onPopoverShow()}
+        type="button"
+      >
+        Show popover
+      </button>
+      <output data-testid="selection-state">
+        {selection.currentSelection} · {String(selection.showPopover)}
+      </output>
+    </>
+  )
+}
+
+describe("text selection", () => {
+  test("the atom exposes independent selection and popover updates", () => {
+    const store = createStore()
+    expect(store.get(selectionAtom)).toEqual(initialSelectionState)
+
+    store.set(setSelectionAtom, "doctrinam")
+    expect(store.get(selectionAtom)).toMatchObject({
+      currentSelection: "doctrinam",
+      selected: true,
+      showPopover: false,
+    })
+
+    store.set(setSelectionPopoverAtom, true)
+    expect(store.get(selectionAtom).showPopover).toBe(true)
+  })
+
+  test("useSelection turns highlight callbacks into shared state", async () => {
+    const user = userEvent.setup()
+    const store = createStore()
+    const onSelectionEnd = mock(() => {})
+    render(
+      <Provider store={store}>
+        <SelectionHarness onSelectionEnd={onSelectionEnd} />
+      </Provider>
+    )
+
+    await user.click(screen.getByRole("button", { name: "End selection" }))
+    expect(onSelectionEnd).toHaveBeenCalledWith("selected words")
+    expect(screen.getByTestId("selection-state").textContent).toBe(
+      "selected words · false"
+    )
+
+    await user.click(screen.getByRole("button", { name: "Show popover" }))
+    expect(screen.getByTestId("selection-state").textContent).toBe(
+      "selected words · true"
+    )
+  })
+
+  test("TextSelection renders its selected children", () => {
+    render(
+      <TextSelection onSelectionEnd={() => {}} renderPopover={() => null}>
+        <span>Selectable corpus text</span>
+      </TextSelection>
+    )
+
+    expect(screen.getByText("Selectable corpus text")).toBeDefined()
+  })
+})

package/src/components/atoms/text-selection/click-popover.tsx

@@ -0,0 +1,62 @@
+"use client"
+
+import { useState } from "react"
+import type { ReactElement } from "react"
+import { Popover, PopoverPopup, PopoverTrigger } from "@/components/ui/popover"
+import { cn } from "@/lib/utils"
+import { Text } from "../text/default"
+import type { TextClickPopoverProps, TextPopoverRenderProps } from "./types"
+
+export function TextClickPopover({
+  children,
+  popover,
+  renderPopover,
+  popoverProps,
+  open: controlledOpen,
+  defaultOpen = false,
+  onOpenChange,
+  className,
+  ...textProps
+}: TextClickPopoverProps): ReactElement {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen)
+  const open = controlledOpen ?? uncontrolledOpen
+  const setOpen = (next: boolean) => {
+    setUncontrolledOpen(next)
+    onOpenChange?.(next)
+  }
+
+  const renderProps: TextPopoverRenderProps = {
+    open,
+    setOpen,
+    close: () => setOpen(false),
+  }
+  const content = renderPopover ? renderPopover(renderProps) : popover
+
+  return (
+    <Popover onOpenChange={(next) => setOpen(next)} open={open}>
+      <PopoverTrigger
+        nativeButton={false}
+        render={
+          <Text
+            {...textProps}
+            className={cn(
+              "w-fit cursor-pointer data-popup-open:opacity-80",
+              className
+            )}
+          />
+        }
+      >
+        {children}
+      </PopoverTrigger>
+      {content !== undefined && content !== null ? (
+        <PopoverPopup
+          {...popoverProps}
+          className={cn("max-w-64", popoverProps?.className)}
+          data-selection-popover=""
+        >
+          {content}
+        </PopoverPopup>
+      ) : null}
+    </Popover>
+  )
+}

package/src/components/atoms/text-selection/index.ts

@@ -0,0 +1,30 @@
+export { TextClickPopover } from "./click-popover"
+export { HighlightPopover } from "./popover"
+export { TextSelection } from "./selection"
+export {
+  initialSelectionState,
+  resetSelectionAtom,
+  selectionAtom,
+  setCurrentSelectionAtom,
+  setPopoverPositionAtom,
+  setSelectionAtom,
+  setSelectionPopoverAtom,
+  setSelectionPositionAtom,
+  setShowPopoverAtom,
+  updateSelectionAtom,
+} from "./selection-atom"
+export { useSelection } from "./use-selection"
+export type {
+  HighlightPopoverPrimitiveProps,
+  HighlightPopoverProps,
+  SelectionPosition,
+  SelectionPopoverComponent,
+  SelectionRenderProps,
+  SelectionState,
+  SelectionStateUpdate,
+  TextClickPopoverProps,
+  TextPopoverRenderProps,
+  TextSelectionProps,
+  UseSelectionOptions,
+  UseSelectionResult,
+} from "./types"

package/src/components/atoms/text-selection/popover.tsx

@@ -0,0 +1,100 @@
+"use client"
+
+import { useEffect } from "react"
+import type * as React from "react"
+import { useHighlightPopover } from "@omsimos/react-highlight-popover"
+import { Card, CardPanel } from "@/components/ui/card"
+import { cn } from "@/lib/utils"
+import { useSelection } from "./use-selection"
+import type { HighlightPopoverProps, SelectionRenderProps } from "./types"
+
+export function HighlightPopover({
+  children,
+  component: Component = Card,
+  componentProps,
+  render,
+  className,
+  ...props
+}: HighlightPopoverProps): React.ReactElement {
+  const primitive = useHighlightPopover()
+  const selection = useSelection()
+  const currentSelection =
+    primitive.currentSelection || selection.currentSelection
+  const position = selection.popoverPosition ?? primitive.popoverPosition
+  const {
+    currentSelection: stateSelection,
+    popoverPosition: statePosition,
+    selected,
+    setPosition,
+    setSelection,
+    setShowPopover,
+    showPopover,
+  } = selection
+
+  useEffect(() => {
+    if (stateSelection !== currentSelection) {
+      setSelection(currentSelection)
+    }
+    if (
+      statePosition?.top !== primitive.popoverPosition.top ||
+      statePosition?.left !== primitive.popoverPosition.left
+    ) {
+      setPosition(primitive.popoverPosition)
+    }
+    if (showPopover !== primitive.showPopover) {
+      setShowPopover(primitive.showPopover)
+    }
+  }, [
+    currentSelection,
+    primitive.popoverPosition,
+    primitive.showPopover,
+    setPosition,
+    setSelection,
+    setShowPopover,
+    showPopover,
+    statePosition,
+    stateSelection,
+  ])
+
+  const renderProps: SelectionRenderProps = {
+    position,
+    selection: currentSelection,
+    selected,
+    showPopover: primitive.showPopover,
+    setCurrentSelection: (value) => {
+      primitive.setCurrentSelection(value)
+      setSelection(value)
+    },
+    setShowPopover: (show) => {
+      primitive.setShowPopover(show)
+      setShowPopover(show)
+    },
+    close: () => {
+      primitive.setShowPopover(false)
+      setShowPopover(false)
+    },
+  }
+
+  const content = render ? render(renderProps) : children
+  const forwardedClassName =
+    typeof componentProps?.className === "string"
+      ? componentProps.className
+      : undefined
+  const componentContextProps =
+    typeof Component === "string" || Component === Card ? {} : renderProps
+  return (
+    <Component
+      {...componentProps}
+      {...props}
+      {...componentContextProps}
+      className={cn(
+        "max-w-52 rounded-md bg-white/50 shadow-lg inset-shadow-sm shadow-black/10 inset-shadow-popover backdrop-blur-md dark:bg-black/20",
+        forwardedClassName,
+        className
+      )}
+      data-selection-popover=""
+    >
+      <CardPanel className="p-3">{content}</CardPanel>
+    </Component>
+  )
+}

package/src/components/atoms/text-selection/selection-atom.ts

@@ -0,0 +1,51 @@
+import { atom } from "jotai"
+import type {
+  SelectionPosition,
+  SelectionState,
+  SelectionStateUpdate,
+} from "./types"
+
+export const initialSelectionState: SelectionState = {
+  selected: false,
+  currentSelection: "",
+  showPopover: false,
+  popoverPosition: null,
+}
+
+export const selectionAtom = atom<SelectionState>(initialSelectionState)
+
+/** Update only the fields that changed, keeping selection state atomic. */
+export const updateSelectionAtom = atom(
+  null,
+  (get, set, update: SelectionStateUpdate) => {
+    const next =
+      typeof update === "function" ? update(get(selectionAtom)) : update
+    set(selectionAtom, { ...get(selectionAtom), ...next })
+  }
+)
+
+export const setSelectionAtom = atom(null, (_get, set, selection: string) => {
+  set(updateSelectionAtom, { currentSelection: selection, selected: true })
+})
+
+export const setSelectionPositionAtom = atom(
+  null,
+  (_get, set, popoverPosition: SelectionPosition) => {
+    set(updateSelectionAtom, { popoverPosition })
+  }
+)
+
+export const setSelectionPopoverAtom = atom(
+  null,
+  (_get, set, showPopover: boolean) => {
+    set(updateSelectionAtom, { showPopover })
+  }
+)
+
+export const setCurrentSelectionAtom = setSelectionAtom
+export const setPopoverPositionAtom = setSelectionPositionAtom
+export const setShowPopoverAtom = setSelectionPopoverAtom
+
+export const resetSelectionAtom = atom(null, (_get, set) => {
+  set(selectionAtom, initialSelectionState)
+})

package/src/components/atoms/text-selection/selection.tsx

@@ -0,0 +1,56 @@
+"use client"
+
+import type { ReactElement } from "react"
+import { HighlightPopover as HighlightPopoverPrimitive } from "@omsimos/react-highlight-popover"
+import { HighlightPopover } from "./popover"
+import { useSelection } from "./use-selection"
+import type { TextSelectionProps } from "./types"
+
+export function TextSelection({
+  children,
+  selected,
+  popover,
+  component,
+  componentProps,
+  popoverComponent,
+  popoverProps,
+  renderPopover,
+  onSelectionStart,
+  onSelectionEnd,
+  onPopoverShow,
+  onPopoverHide,
+  ...props
+}: TextSelectionProps): ReactElement {
+  const selection = useSelection({
+    selected,
+    onSelectionStart,
+    onSelectionEnd,
+    onPopoverShow,
+    onPopoverHide,
+  })
+  const hasPopover =
+    renderPopover !== undefined ||
+    component !== undefined ||
+    popoverComponent !== undefined ||
+    (popover !== undefined && popover !== null)
+
+  return (
+    <HighlightPopoverPrimitive
+      {...props}
+      {...selection.selectionProps}
+      renderPopover={() =>
+        hasPopover ? (
+          <HighlightPopover
+            component={component ?? popoverComponent}
+            componentProps={componentProps ?? popoverProps}
+            render={renderPopover}
+          >
+            {popover}
+          </HighlightPopover>
+        ) : null
+      }
+    >
+      {children}
+    </HighlightPopoverPrimitive>
+  )
+}