@exegia/corpora-ui 1.0.0 → 3.0.0

package/src/components/blocks/chat/index.ts

@@ -4,9 +4,7 @@ export { AiPanel }
 export { AiPanelHeader } from "./header"
 export { SuggestedPrompts } from "./suggested-prompts"
 export { RecommendationStack } from "./recommendation-stack"
-export type { RecommendationStackProps } from "./recommendation-stack"
 export { DegradedBanner, LockedBanner, PinnedThreadBanner } from "./banners"
-export type { DegradedBannerProps, PinnedThreadBannerProps } from "./banners"
 export { VersionHistoryRecord } from "./version-history-record"
 
 export {
@@ -16,24 +14,24 @@ export {
   SelectionPopover,
 } from "@/components/composed/reader"
 export type {
-  AppliedMarkProps,
-  ApplyToastProps,
-  SelectionHighlightProps,
-  SelectionPopoverProps,
+  IAppliedMarkProps,
+  IApplyToastProps,
+  ISelectionHighlightProps,
+  ISelectionPopoverProps,
 } from "@/components/composed/reader"
 export type {
-  AiPanelHeaderProps,
-  AiPanelProps,
-  LockedBannerProps,
-  AiScope,
-  AiScopeKind,
-  ComposerMode,
-  DiffRow,
-  NodeSelection,
-  SuggestionState,
-  VersionHistoryEntry,
-  SuggestedPromptsProps,
-  WordSelection,
-} from "./types"
+  IAiPanelHeaderProps,
+  IAiPanelProps,
+  ILockedBannerProps,
+  IAiScope,
+  TAiScopeKind,
+  TComposerMode,
+  IDiffRow,
+  INodeSelection,
+  TSuggestionState,
+  IVersionHistoryEntry,
+  ISuggestedPromptsProps,
+  IWordSelection,
+} from "./type"
 
 export default AiPanel

package/src/components/blocks/chat/recommendation-stack.tsx

@@ -3,11 +3,9 @@
 import type * as React from "react"
 import { Group } from "@/components/ui/group"
 import { cn } from "@/lib/utils"
+import type { IRecommendationStackProps } from "./type"
+
 
-export interface RecommendationStackProps
-  extends React.ComponentPropsWithoutRef<"div"> {
-  children: React.ReactNode
-}
 
 /**
  * Fuses a run of RecommendationCards into one bordered stack for the thread.
@@ -21,11 +19,11 @@ export function RecommendationStack({
   className,
   children,
   ...props
-}: RecommendationStackProps): React.ReactElement {
+}: IRecommendationStackProps): React.ReactElement {
   return (
     <Group
       className={cn(
-        "w-full *:before:content-none",
+        "w-full *:before:content-none mt-3",
         "[&>*:not(:last-child)_[data-slot=recommendation-card]]:rounded-b-none",
         "[&>*:not(:last-child)_[data-slot=recommendation-card]]:before:rounded-b-none",
         "[&>*+*_[data-slot=recommendation-card]]:rounded-t-none",

package/src/components/blocks/chat/suggested-prompts.tsx

@@ -5,7 +5,7 @@ import { cn } from "@/lib/utils"
 import { Button } from "@/components/ui/button"
 import { accentRing, mutedText } from "./shared"
 import { Sparkles } from "lucide-react"
-import type { SuggestedPromptsProps } from "./types";
+import type { ISuggestedPromptsProps } from "./type";
 
 
 export function SuggestedPrompts({
@@ -13,7 +13,7 @@ export function SuggestedPrompts({
   onSelect,
   emptyLabel = "Ask about this selection or validate it against the schema.",
   className,
-}: SuggestedPromptsProps): React.ReactElement | null {
+}: ISuggestedPromptsProps): React.ReactElement | null {
   if (!prompts.length) {
     return (
       <p className={cn("px-1 py-3", mutedText, className)} data-empty="true">

package/src/components/blocks/chat/type.ts

@@ -0,0 +1,96 @@
+import type * as React from "react"
+import type { IComposerProps } from "@/components/composed/chat/composer"
+
+export type TAiScopeKind =
+  "word" | "passage" | "articulus" | "quaestio" | "corpus"
+
+export interface IAiScope {
+  kind: TAiScopeKind
+  label: string
+  /** Reader location shown after a normal word/node scope. */
+  location?: string
+  range?: string
+  nodeId?: string
+  nodeIds?: string[]
+  pinned?: boolean
+}
+
+export interface IRecommendationStackProps
+  extends React.ComponentPropsWithoutRef<"div"> {
+  children: React.ReactNode
+}
+
+export interface IPinnedThreadBannerProps {
+  className?: string
+}
+
+export interface IDegradedBannerProps {
+  reason?: React.ReactNode
+  onRetry?: () => void
+  className?: string
+}
+
+// The reader selection shapes moved with `SelectionPopover` to
+// `composed/reader`; re-exported so the block's surface stays whole.
+export type { INodeSelection, IWordSelection } from "@/components/composed/reader"
+
+export interface IAiPanelProps extends Omit<
+  React.ComponentPropsWithoutRef<"aside">,
+  "title"
+> {
+  scope: IAiScope
+  onNewThread?: () => void
+  onScopeChange?: (kind: IAiScope["kind"]) => void
+  onRemoveScope?: () => void
+  thread?: React.ReactNode
+  /** Transient confirmation (e.g. ApplyToast), anchored to the bottom of the
+   * thread and sized slightly narrower than the composer. */
+  toast?: React.ReactNode
+  prompts?: string[]
+  onPromptSelect?: (prompt: string) => void
+  composerProps?: IComposerProps
+  scopePickerOpen?: boolean
+  onScopePickerOpenChange?: (open: boolean) => void
+  locked?: boolean
+  headerTitle?: string
+}
+
+export interface IAiPanelHeaderProps {
+  title: string
+  /** Shows the lock affordance and its “Published corpus” tooltip. */
+  locked?: boolean
+  onNewThread?: () => void
+}
+
+export type { TComposerMode } from "@/components/composed/chat/composer"
+export type { IDiffRow, TSuggestionState } from "@/components/composed/ai/types"
+
+export interface IVersionHistoryEntry {
+  id?: string
+  responseId: string
+  applyingUser?: string
+  nodeId: string
+  previousValue: string
+  nextValue?: string
+  timestamp: string | Date
+  version: string
+  action?: "apply" | "revert"
+}
+
+export interface ISuggestedPromptsProps {
+  prompts?: string[]
+  onSelect?: (prompt: string) => void
+  emptyLabel?: string
+  className?: string
+}
+
+export interface IVersionHistoryRecordProps {
+  entry: IVersionHistoryEntry
+  className?: string
+}
+
+
+export interface ILockedBannerProps {
+  children?: React.ReactNode
+  className?: string
+}

package/src/components/blocks/chat/version-history-record.tsx

@@ -3,14 +3,14 @@
 import type * as React from "react"
 import { cn } from "@/lib/utils"
 import { accentText, mutedText } from "./shared"
-import type { VersionHistoryRecordProps } from "./types"
+import type { IVersionHistoryRecordProps } from "./type"
 
 
 
 export function VersionHistoryRecord({
   entry,
   className,
-}: VersionHistoryRecordProps): React.ReactElement {
+}: IVersionHistoryRecordProps): React.ReactElement {
   const timestamp =
     entry.timestamp instanceof Date
       ? entry.timestamp.toLocaleString()

package/src/components/blocks/profile/__tests__/profile-card-block.test.tsx

@@ -10,7 +10,7 @@ import {
   useProfileCardActions,
   useProfileCardState,
 } from "../use-profile-card-state"
-import type { ProfileCardActions, ProfileCardState } from "../type"
+import type { IProfileCardActions, IProfileCardState } from "../type"
 
 const USER = { name: "Jenny Hamilton", username: "@jennycodes" }
 
@@ -227,8 +227,8 @@ describe("ProfileCardBlock", () => {
   })
   test("data-variant mirrors the fold and onVariantChange reports store-driven changes", () => {
     const onVariantChange = mock(() => {})
-    let actions!: ProfileCardActions
-    let state!: ProfileCardState
+    let actions!: IProfileCardActions
+    let state!: IProfileCardState
     function Probe() {
       actions = useProfileCardActions("account")
       state = useProfileCardState("account")
@@ -260,7 +260,7 @@ describe("ProfileCardBlock", () => {
   })
 
   test("a controlled variant is never overwritten by the store", () => {
-    let actions!: ProfileCardActions
+    let actions!: IProfileCardActions
     function Probe() {
       actions = useProfileCardActions("locked")
       return null
@@ -286,7 +286,7 @@ describe("ProfileCardBlock", () => {
   })
 
   test("openMenu / closeMenu from outside drive the menu through the store", async () => {
-    let actions!: ProfileCardActions
+    let actions!: IProfileCardActions
     function Probe() {
       actions = useProfileCardActions("menu")
       return null
@@ -309,7 +309,7 @@ describe("ProfileCardBlock", () => {
   test("busy tracks a pending action in the store", async () => {
     const user = userEvent.setup()
     let resolve!: () => void
-    let state!: ProfileCardState
+    let state!: IProfileCardState
     function Probe() {
       state = useProfileCardState("busy")
       return null

package/src/components/blocks/profile/index.ts

@@ -2,9 +2,9 @@ export {
   ProfileCardBlock,
   defaultProfileCardItems,
 } from "./profile-card-block"
-export type { ProfileCardBlockProps } from "./profile-card-block"
+export type { IProfileCardBlockProps } from "./profile-card-block"
 export { useProfileCard } from "./use-profile-card"
-export type { ProfileCardBinding, UseProfileCardOptions } from "./use-profile-card"
+export type { IProfileCardBinding, IUseProfileCardOptions } from "./use-profile-card"
 export {
   useProfileCardActions,
   useProfileCardState,

package/src/components/blocks/profile/profile-card-atom.ts

@@ -11,39 +11,39 @@ import { atom } from "jotai"
 import type { Getter, Setter } from "jotai"
 
 import type {
-  ProfileCardAction,
-  ProfileCardConfig,
-  ProfileCardHandlers,
-  ProfileCardInstanceId,
-  ProfileCardState,
-  ProfileCardVariant,
+  IProfileCardAction,
+  IProfileCardConfig,
+  IProfileCardHandlers,
+  TProfileCardInstanceId,
+  IProfileCardState,
+  TProfileCardVariant,
 } from "./type"
 
-const DEFAULT_CONFIG: ProfileCardConfig = {
+const DEFAULT_CONFIG: IProfileCardConfig = {
   controlsVariant: false,
   controlsMenuOpen: false,
 }
-const NO_HANDLERS: ProfileCardHandlers = {}
+const NO_HANDLERS: IProfileCardHandlers = {}
 
 // ── families ───────────────────────────────────────────────────────────────
 
-type Family<AtomType> = ((id: ProfileCardInstanceId) => AtomType) & {
-  remove: (id: ProfileCardInstanceId) => void
+type TFamily<AtomType> = ((id: TProfileCardInstanceId) => AtomType) & {
+  remove: (id: TProfileCardInstanceId) => void
 }
 
-const families: { remove: (id: ProfileCardInstanceId) => void }[] = []
+const families: { remove: (id: TProfileCardInstanceId) => void }[] = []
 
-function keyed<AtomType>(create: (id: ProfileCardInstanceId) => AtomType) {
-  const cache = new Map<ProfileCardInstanceId, AtomType>()
-  const family = ((id: ProfileCardInstanceId) => {
+function keyed<AtomType>(create: (id: TProfileCardInstanceId) => AtomType) {
+  const cache = new Map<TProfileCardInstanceId, AtomType>()
+  const family = ((id: TProfileCardInstanceId) => {
     let instance = cache.get(id)
     if (instance === undefined) {
       instance = create(id)
       cache.set(id, instance)
     }
     return instance
-  }) as Family<AtomType>
-  family.remove = (id: ProfileCardInstanceId) => {
+  }) as TFamily<AtomType>
+  family.remove = (id: TProfileCardInstanceId) => {
     cache.delete(id)
   }
   families.push(family)
@@ -60,7 +60,7 @@ function stateFamily<Value>(name: string, initialValue: Value) {
 
 function readFamily<Value>(
   name: string,
-  read: (get: Getter, id: ProfileCardInstanceId) => Value
+  read: (get: Getter, id: TProfileCardInstanceId) => Value
 ) {
   return keyed((id) => {
     const instance = atom((get) => read(get, id))
@@ -74,7 +74,7 @@ function actionFamily<Args extends unknown[]>(
   write: (
     get: Getter,
     set: Setter,
-    id: ProfileCardInstanceId,
+    id: TProfileCardInstanceId,
     ...args: Args
   ) => void
 ) {
@@ -89,7 +89,7 @@ function actionFamily<Args extends unknown[]>(
 
 // ── primitives ─────────────────────────────────────────────────────────────
 
-export const profileCardVariantAtom = stateFamily<ProfileCardVariant>(
+export const profileCardVariantAtom = stateFamily<TProfileCardVariant>(
   "variant",
   "expanded"
 )
@@ -102,13 +102,13 @@ export const profileCardPendingActionIdAtom = stateFamily<string | null>(
 )
 
 /** @internal */
-export const profileCardConfigAtom = stateFamily<ProfileCardConfig>(
+export const profileCardConfigAtom = stateFamily<IProfileCardConfig>(
   "config",
   DEFAULT_CONFIG
 )
 
 /** @internal */
-export const profileCardHandlersAtom = stateFamily<ProfileCardHandlers>(
+export const profileCardHandlersAtom = stateFamily<IProfileCardHandlers>(
   "handlers",
   NO_HANDLERS
 )
@@ -127,7 +127,7 @@ export const profileCardBusyAtom = readFamily(
 
 /** Whole-state read for callers that want the object; the field atoms are
  * cheaper for components that watch one thing. */
-export const profileCardStateAtom = readFamily<ProfileCardState>(
+export const profileCardStateAtom = readFamily<IProfileCardState>(
   "state",
   (get, id) => ({
     variant: get(profileCardVariantAtom(id)),
@@ -142,7 +142,7 @@ export const profileCardStateAtom = readFamily<ProfileCardState>(
 /** Reports through `onVariantChange` always; writes the store only when no
  * `variant` prop controls the card — the prop is truth then. */
 export const setProfileCardVariantAtom = actionFamily<
-  [variant: ProfileCardVariant]
+  [variant: TProfileCardVariant]
 >("setVariant", (get, set, id, variant) => {
   if (get(profileCardVariantAtom(id)) === variant) return
   if (!get(profileCardConfigAtom(id)).controlsVariant)
@@ -181,7 +181,7 @@ export const setProfileCardMenuOpenAtom = actionFamily<[open: boolean]>(
  * writes to an instance nobody renders any more.
  */
 export const selectProfileCardActionAtom = actionFamily<
-  [action: ProfileCardAction]
+  [action: IProfileCardAction]
 >("selectAction", (get, set, id, action) => {
   const result = action.onSelect?.()
   if (!(result instanceof Promise)) return
@@ -200,8 +200,8 @@ export const selectProfileCardActionAtom = actionFamily<
 /** @internal Projection of the mounted component's controlled props. */
 export const projectProfileCardPropsAtom = actionFamily<
   [
-    config: ProfileCardConfig,
-    variant: ProfileCardVariant | undefined,
+    config: IProfileCardConfig,
+    variant: TProfileCardVariant | undefined,
     menuOpen: boolean | undefined,
   ]
 >("projectProps", (_get, set, id, config, variant, menuOpen) => {
@@ -214,7 +214,7 @@ export const projectProfileCardPropsAtom = actionFamily<
 
 /** @internal */
 export const setProfileCardHandlersAtom = actionFamily<
-  [handlers: ProfileCardHandlers]
+  [handlers: IProfileCardHandlers]
 >("setHandlers", (_get, set, id, handlers) => {
   set(profileCardHandlersAtom(id), handlers)
 })
@@ -222,7 +222,7 @@ export const setProfileCardHandlersAtom = actionFamily<
 /** @internal Seed the uncontrolled variant on mount without firing
  * `onVariantChange`. */
 export const seedProfileCardVariantAtom = actionFamily<
-  [variant: ProfileCardVariant]
+  [variant: TProfileCardVariant]
 >("seedVariant", (_get, set, id, variant) => {
   set(profileCardVariantAtom(id), variant)
 })
@@ -242,6 +242,6 @@ export const resetProfileCardAtom = actionFamily<[]>(
 
 /** Forget a card entirely — every family drops the key so the store can
  * release its state. Call on teardown of a named instance. */
-export function removeProfileCardInstance(id: ProfileCardInstanceId): void {
+export function removeProfileCardInstance(id: TProfileCardInstanceId): void {
   for (const family of families) family.remove(id)
 }

package/src/components/blocks/profile/profile-card-block.tsx

@@ -35,29 +35,29 @@ import { cn } from "@/lib/utils"
 
 import { useProfileCard } from "./use-profile-card"
 import type {
-  ProfileCardAction,
-  ProfileCardItem,
-  ProfileCardUser,
-  ProfileCardVariant,
+  IProfileCardAction,
+  TProfileCardItem,
+  IProfileCardUser,
+  TProfileCardVariant,
 } from "./type"
 
 export type {
-  ProfileCardAction,
-  ProfileCardActions,
-  ProfileCardInstanceId,
-  ProfileCardItem,
-  ProfileCardLabel,
-  ProfileCardSeparator,
-  ProfileCardState,
-  ProfileCardUser,
-  ProfileCardVariant,
+  IProfileCardAction,
+  IProfileCardActions,
+  TProfileCardInstanceId,
+  TProfileCardItem,
+  IProfileCardLabel,
+  IProfileCardSeparator,
+  IProfileCardState,
+  IProfileCardUser,
+  TProfileCardVariant,
 } from "./type"
 
 /**
  * The menu the card ships with. Spread it to keep the shape and attach your
  * own handlers, or ignore it and pass `items` of your own.
  */
-export const defaultProfileCardItems: ProfileCardItem[] = [
+export const defaultProfileCardItems: TProfileCardItem[] = [
   { type: "label", label: "Management" },
   { id: "profile", label: "Profile", icon: <UserIcon aria-hidden="true" /> },
   {
@@ -77,19 +77,19 @@ export const defaultProfileCardItems: ProfileCardItem[] = [
   },
 ]
 
-type PopupProps = React.ComponentProps<typeof DropdownMenuContent>
+type TPopupProps = React.ComponentProps<typeof DropdownMenuContent>
 
-export interface ProfileCardBlockProps {
-  user: ProfileCardUser
+export interface IProfileCardBlockProps {
+  user: IProfileCardUser
   /**
    * The menu, flat: actions plus `{ type: "separator" }` / `{ type: "label" }`
    * entries. Defaults to `defaultProfileCardItems` (no handlers attached).
    */
-  items?: ProfileCardItem[]
+  items?: TProfileCardItem[]
   /** Menu placement relative to the card. */
-  align?: PopupProps["align"]
-  side?: PopupProps["side"]
-  sideOffset?: PopupProps["sideOffset"]
+  align?: TPopupProps["align"]
+  side?: TPopupProps["side"]
+  sideOffset?: TPopupProps["sideOffset"]
   open?: boolean
   defaultOpen?: boolean
   onOpenChange?: MenuPrimitive.Root.Props["onOpenChange"]
@@ -106,9 +106,9 @@ export interface ProfileCardBlockProps {
    * it sits in (a panel footer folds with the rail on its own), and
    * outside a panel starts from `defaultVariant`.
    */
-  variant?: ProfileCardVariant
-  defaultVariant?: ProfileCardVariant
-  onVariantChange?: (variant: ProfileCardVariant) => void
+  variant?: TProfileCardVariant
+  defaultVariant?: TProfileCardVariant
+  onVariantChange?: (variant: TProfileCardVariant) => void
   /**
    * Name this card's slice of the store so `useProfileCardState(id)` /
    * `useProfileCardActions(id)` can read or drive it (fold it, open its
@@ -117,7 +117,7 @@ export interface ProfileCardBlockProps {
    */
   profileCardId?: string
   /** Presence badge on the avatar — overrides `user.presence`. */
-  presence?: ProfileCardUser["presence"]
+  presence?: IProfileCardUser["presence"]
   /**
    * Emit cuelume press/release on the card and play the open/close cues.
    * Inert unless the app opts into interaction sound via `bindSounds()`.
@@ -130,10 +130,10 @@ export interface ProfileCardBlockProps {
 
 /** Split a flat item list into the groups the menu renders. */
 function toGroups(
-  items: ProfileCardItem[]
-): { label?: string; actions: ProfileCardAction[] }[] {
-  const groups: { label?: string; actions: ProfileCardAction[] }[] = []
-  let current: { label?: string; actions: ProfileCardAction[] } = {
+  items: TProfileCardItem[]
+): { label?: string; actions: IProfileCardAction[] }[] {
+  const groups: { label?: string; actions: IProfileCardAction[] }[] = []
+  let current: { label?: string; actions: IProfileCardAction[] } = {
     actions: [],
   }
 
@@ -179,7 +179,7 @@ export function ProfileCardBlock({
   sound = true,
   onError,
   className,
-}: ProfileCardBlockProps): React.ReactElement {
+}: IProfileCardBlockProps): React.ReactElement {
   const groups = React.useMemo(() => toGroups(items), [items])
 
   // Optional, not required: the card is a standalone block that also lands

package/src/components/blocks/profile/type.ts

@@ -1,9 +1,9 @@
 import type * as React from "react"
 
-import type { AvatarStatus } from "@/components/atoms"
+import type { TAvatarStatus } from "@/components/atoms"
 
 /** The identity shown on the card. */
-export interface ProfileCardUser {
+export interface IProfileCardUser {
   name: string
   /** Secondary line under the name — a handle, an email, a role. */
   username?: string
@@ -12,11 +12,11 @@ export interface ProfileCardUser {
   /** Fallback initials. Derived from `name` when omitted. */
   initials?: string
   /** Presence badge on the avatar. Omitted, no badge. */
-  presence?: AvatarStatus
+  presence?: TAvatarStatus
 }
 
 /** An actionable row of the menu. */
-export interface ProfileCardAction {
+export interface IProfileCardAction {
   type?: "item"
   id: string
   label: string
@@ -30,13 +30,13 @@ export interface ProfileCardAction {
 }
 
 /** A heading over the rows that follow it, up to the next separator. */
-export interface ProfileCardLabel {
+export interface IProfileCardLabel {
   type: "label"
   label: string
 }
 
 /** A rule between two sections. */
-export interface ProfileCardSeparator {
+export interface IProfileCardSeparator {
   type: "separator"
 }
 
@@ -44,20 +44,20 @@ export interface ProfileCardSeparator {
  * One entry of `items`. Authored flat; the block renders each run between
  * separators as its own menu group so a label actually names its section.
  */
-export type ProfileCardItem =
-  ProfileCardAction | ProfileCardLabel | ProfileCardSeparator
+export type TProfileCardItem =
+  IProfileCardAction | IProfileCardLabel | IProfileCardSeparator
 
 /** `expanded` shows avatar, name and handle; `collapsed` folds to the avatar
  * alone — for an icon-collapsed sidebar rail. */
-export type ProfileCardVariant = "expanded" | "collapsed"
+export type TProfileCardVariant = "expanded" | "collapsed"
 
 /** Key for one card's state in the store. Any stable string; `useProfileCard`
  * generates one when the component does not name itself. */
-export type ProfileCardInstanceId = string
+export type TProfileCardInstanceId = string
 
 /** Everything the store knows about one card. */
-export interface ProfileCardState {
-  variant: ProfileCardVariant
+export interface IProfileCardState {
+  variant: TProfileCardVariant
   menuOpen: boolean
   /** Id of the action whose promise is in flight, `null` while idle. */
   pendingActionId: string | null
@@ -66,8 +66,8 @@ export interface ProfileCardState {
 }
 
 /** Write-only handles onto one card. Nothing here re-renders the caller. */
-export interface ProfileCardActions {
-  setVariant: (variant: ProfileCardVariant) => void
+export interface IProfileCardActions {
+  setVariant: (variant: TProfileCardVariant) => void
   toggleVariant: () => void
   /** Convenience over `setVariant`. */
   collapse: () => void
@@ -80,14 +80,14 @@ export interface ProfileCardActions {
 
 /** @internal Which fields the mounted component controls from props. The
  * store must never overwrite a controlled value. */
-export interface ProfileCardConfig {
+export interface IProfileCardConfig {
   controlsVariant: boolean
   controlsMenuOpen: boolean
 }
 
 /** @internal Latest option callbacks. Only write atoms read this, so it can
  * be refreshed every commit without re-rendering anything. */
-export interface ProfileCardHandlers {
-  onVariantChange?: (variant: ProfileCardVariant) => void
+export interface IProfileCardHandlers {
+  onVariantChange?: (variant: TProfileCardVariant) => void
   onError?: (error: unknown) => void
 }