@arbidocs/blocks 0.3.185 → 0.4.1

package/dist/facts/FactPassages.d.ts

@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react';
+export interface FactPassagesLabels {
+    loading: string;
+    close: string;
+}
+export declare const DEFAULT_FACT_PASSAGES_LABELS: FactPassagesLabels;
+export interface FactSourcesPanelTestIds {
+    popover: string;
+    close: string;
+    list: string;
+}
+/**
+ * Flatten a passage's markdown to one readable line for a list preview: headings, bullets,
+ * emphasis, links and table pipes only add noise on a single truncated line.
+ */
+export declare function toPreviewLine(md: string): string;
+/**
+ * Render a flattened preview line with real super/subscripts: `<sup>15</sup>` shows as a
+ * superscript 15, not literal tag text. Unpaired tag fragments are dropped.
+ */
+export declare function renderPreviewInline(line: string): ReactNode;
+export interface FactPassageItemProps {
+    /** Zero-based position in the list (shown as `n.`). */
+    index: number;
+    page?: number | null;
+    /** The passage excerpt (markdown), or null/undefined while it loads. */
+    excerpt?: string | null;
+    /** This passage is the one open in the viewer. */
+    isViewing?: boolean;
+    onSelect: () => void;
+    testId?: string;
+    className?: string;
+    labels?: Partial<FactPassagesLabels>;
+}
+/** One cited passage: index badge, page pill and a single quoted line. */
+export declare function FactPassageItem({ index, page, excerpt, isViewing, onSelect, testId, className, labels, }: FactPassageItemProps): import("react").JSX.Element;
+export interface FactSourcesPanelProps {
+    /** Header caption, e.g. "Sources (2 documents)". */
+    title: string;
+    onClose: () => void;
+    /** The fact section the panel is portalled INTO and fenced WITHIN. */
+    container?: HTMLElement | null;
+    children: ReactNode;
+    labels?: Partial<FactPassagesLabels>;
+    testIds?: Partial<FactSourcesPanelTestIds>;
+}
+/**
+ * Popover panel shell for a fact's sources: sticky header with a close control and a scrolling
+ * list. Must sit inside a `Popover`. Stays open while the user works in the document viewer
+ * (clicks inside the viewer, dialogs or other popper layers do not dismiss it).
+ */
+export declare function FactSourcesPanel({ title, onClose, container, children, labels, testIds, }: FactSourcesPanelProps): import("react").JSX.Element;

package/dist/facts/FactRowActions.d.ts

@@ -0,0 +1,18 @@
+export interface FactRowActionsLabels {
+    actions: string;
+    edit: string;
+    delete: string;
+}
+export declare const DEFAULT_FACT_ROW_ACTIONS_LABELS: FactRowActionsLabels;
+export interface FactRowActionsTestIds {
+    trigger: string;
+    edit: string;
+    delete: string;
+}
+export interface FactRowActionsProps {
+    onEdit: () => void;
+    onDelete: () => void;
+    labels?: Partial<FactRowActionsLabels>;
+    testIds?: Partial<FactRowActionsTestIds>;
+}
+export declare function FactRowActions({ onEdit, onDelete, labels, testIds }: FactRowActionsProps): import("react").JSX.Element;

package/dist/facts/FactSearchParts.d.ts

@@ -0,0 +1,80 @@
+import type { ReactNode } from 'react';
+export interface FactSearchBarLabels {
+    search: string;
+    placeholder: string;
+    clear: string;
+    submit: string;
+}
+export declare const DEFAULT_FACT_SEARCH_BAR_LABELS: FactSearchBarLabels;
+export interface FactSearchBarTestIds {
+    input: string;
+    clear: string;
+    submit: string;
+}
+export interface FactSearchResultLabels {
+    core: string;
+    verified: string;
+    open: string;
+}
+export declare const DEFAULT_FACT_SEARCH_RESULT_LABELS: FactSearchResultLabels;
+export interface FactSearchResultTestIds {
+    hit: (id: string) => string;
+    labels: (id: string) => string;
+    verified: (id: string) => string;
+}
+export interface FactSearchBarProps {
+    query: string;
+    onQueryChange: (query: string) => void;
+    onSubmit: () => void;
+    onClear: () => void;
+    isSearching: boolean;
+    /** Wins over `labels.placeholder`. */
+    placeholder?: string;
+    labels?: Partial<FactSearchBarLabels>;
+    testIds?: Partial<FactSearchBarTestIds>;
+}
+/**
+ * The facts Smart Search bar: the same bordered, auto-growing box as the Files Smart Search.
+ * Enter searches; Shift+Enter breaks a line.
+ */
+export declare function FactSearchBar({ query, onQueryChange, onSubmit, onClear, isSearching, placeholder, labels, testIds, }: FactSearchBarProps): import("react").JSX.Element;
+/** Totals headline pinned between the search bar and the scrolling results. */
+export declare function FactSearchTotals({ children, testId }: {
+    children: ReactNode;
+    testId?: string;
+}): import("react").JSX.Element;
+/** "Searching facts…" line. */
+export declare function FactSearchPending({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** No-matches message. */
+export declare function FactSearchNoMatches({ children, testId, }: {
+    children: ReactNode;
+    testId?: string;
+}): import("react").JSX.Element;
+export interface FactSearchResultLabel {
+    id: string;
+    name: string;
+    color: string;
+}
+export interface FactSearchResultProps {
+    /** Fact id: keys the test ids. */
+    id: string;
+    /** 1-based rank, shown outside the card (it numbers the results, it is not part of the hit). */
+    rank: number;
+    text: string;
+    terms: string[];
+    renderSnippet: (content: string, terms: string[]) => ReactNode;
+    labels: FactSearchResultLabel[];
+    isPinned?: boolean;
+    isVerified?: boolean;
+    /** The fact open in the composer. */
+    isSelected?: boolean;
+    onOpen: () => void;
+    uiLabels?: Partial<FactSearchResultLabels>;
+    testIds?: Partial<FactSearchResultTestIds>;
+    /** Destination of the fact; the card stays a click target (see SearchHit `href`). */
+    href?: string;
+}
+/** One facts search result: rank, highlighted text, labels (and Core) and the Verified mark. */
+export declare function FactSearchResult({ id, rank, text, terms, renderSnippet, labels, isPinned, isVerified, isSelected, onOpen, uiLabels: labelOverrides, testIds, href, }: FactSearchResultProps): import("react").JSX.Element;

package/dist/facts/FactSourceGroup.d.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from 'react';
+export interface FactSourceGroupLabels {
+    remove: string;
+    wholeDocument: string;
+}
+export declare const DEFAULT_FACT_SOURCE_GROUP_LABELS: FactSourceGroupLabels;
+export interface FactSourceGroupTestIds {
+    root: (docId: string) => string;
+    remove: (docId: string) => string;
+}
+export interface FactSourceGroupProps {
+    docId: string;
+    /** The document label/pill (the app supplies its entity pill). */
+    document: ReactNode;
+    /** True when this document is the one on display in the viewer. */
+    isViewing?: boolean;
+    onRemove: () => void;
+    /** The FactPassageItem children; when absent a "whole document" hint shows. */
+    children?: ReactNode;
+    /** Whether any passages are cited from this document. */
+    hasPassages: boolean;
+    labels?: Partial<FactSourceGroupLabels>;
+    testIds?: Partial<FactSourceGroupTestIds>;
+}
+/** One cited document in the sources list: its label, a remove control and its passages. */
+export declare function FactSourceGroup({ docId, document, isViewing, onRemove, children, hasPassages, labels, testIds, }: FactSourceGroupProps): import("react").JSX.Element;

package/dist/facts/FactTimelineViews.d.ts

@@ -0,0 +1,37 @@
+import { type TimelineGanttProps } from '../timeline/TimelineGantt';
+export interface FactTimelineLabels {
+    ganttEmpty: string;
+}
+export declare const DEFAULT_FACT_TIMELINE_LABELS: FactTimelineLabels;
+/** The fields of a fact the calendar reads. */
+export interface FactCalendarRow {
+    external_id: string;
+    text: string;
+    date_start?: string | null;
+    date_end?: string | null;
+}
+export interface FactsCalendarProps<T extends FactCalendarRow> {
+    facts: T[];
+    onSelect?: (fact: T) => void;
+    /** The fact currently open for editing: its bars are highlighted. */
+    selectedId?: string | null;
+    /** Host element the n / N fact navigator portals into (see TimelineCalendar). */
+    navigatorContainer?: HTMLElement | null;
+    /** Denominator for the navigator: the page's filtered fact count. */
+    navigatorTotal?: number;
+    /** Calendar test id; entries are `${testId}-entry-${factId}` (default `facts-calendar`). */
+    testId?: string;
+}
+/**
+ * Facts on the shared calendar. Maps a fact to a labelled span and hands the fact back on select,
+ * so packing, spanning bars and continuous scroll stay one implementation shared with every
+ * other timeline surface. Undated facts have nowhere to sit and are skipped.
+ */
+export declare function FactsCalendar<T extends FactCalendarRow>({ facts, onSelect, selectedId, navigatorContainer, navigatorTotal, testId, }: FactsCalendarProps<T>): import("react").JSX.Element;
+/**
+ * The Facts timeline. `.facts-gantt` scopes CSS that truncates row labels to one line and hides
+ * the built-in detail side panel: a fact's contents are seen and edited in the composer instead.
+ */
+export declare function FactsGanttPane({ testId, emptyMessage, labels, ...props }: TimelineGanttProps & {
+    labels?: Partial<FactTimelineLabels>;
+}): import("react").JSX.Element;

package/dist/facts/FactsBulkBar.d.ts

@@ -0,0 +1,53 @@
+import type { ReactNode } from 'react';
+export interface FactsBulkBarLabels {
+    unpin: string;
+    pin: string;
+    label: string;
+    shared: string;
+    more: string;
+    export: string;
+    delete: string;
+    budgetHint: string;
+    /** The `~{tokens}/{cap} tokens` line (numbers arrive formatted). */
+    budget: (tokens: string, cap: string) => string;
+    unpinTooltip: (pluralNoun: string) => string;
+    pinTooltip: (pluralNoun: string) => string;
+    labelTooltip: (pluralNoun: string) => string;
+}
+export declare const DEFAULT_FACTS_BULK_BAR_LABELS: FactsBulkBarLabels;
+export interface FactsBulkBarTestIds {
+    budget: string;
+    pin: string;
+    label: string;
+    more: string;
+    export: string;
+    delete: string;
+}
+export interface FactsBulkBarProps {
+    /** Number of selected facts. */
+    count: number;
+    onClear: () => void;
+    /** True when every selected fact is already pinned (the action then unpins). */
+    allSelectedPinned: boolean;
+    onTogglePin: () => void;
+    onLabel: () => void;
+    /** The aggregate Shared switch for the selection (the app binds its toggle). */
+    sharedToggle: ReactNode;
+    onExport: () => void;
+    onDelete: () => void;
+    /** Pinned-core token budget, shown at the left (reflects the whole workspace, not the selection). */
+    budget?: {
+        tokens: number;
+        cap: number;
+        isOver: boolean;
+    } | null;
+    /** Plural noun for tooltips (lower case). */
+    pluralNoun?: string;
+    labels?: Partial<FactsBulkBarLabels>;
+    testIds?: Partial<FactsBulkBarTestIds>;
+}
+/**
+ * Sticky bulk-action bar for the facts table: Pin, Label, Shared and a More menu (Export,
+ * Delete). Actions are disabled until something is selected.
+ */
+export declare function FactsBulkBar({ count, onClear, allSelectedPinned, onTogglePin, onLabel, sharedToggle, onExport, onDelete, budget, pluralNoun, labels, testIds, }: FactsBulkBarProps): import("react").JSX.Element;

package/dist/facts/FactsEmptyState.d.ts

@@ -0,0 +1,38 @@
+export interface FactsEmptyStateLabels {
+    title: string;
+    intro: string;
+    tryAdding: string;
+    /** Three kinds of durable knowledge a fact captures. */
+    kinds: {
+        label: string;
+        desc: string;
+    }[];
+    /** Starter fact texts offered as one-tap examples. */
+    examples: string[];
+    loading: string;
+    loadError: string;
+    retry: string;
+}
+export declare const DEFAULT_FACTS_EMPTY_STATE_LABELS: FactsEmptyStateLabels;
+export interface FactsEmptyStateTestIds {
+    root: string;
+    example: string;
+}
+export interface FactsEmptyStateProps {
+    /** Open the composer prefilled with an example. */
+    onUseExample: (text: string) => void;
+    labels?: Partial<FactsEmptyStateLabels>;
+    testIds?: Partial<FactsEmptyStateTestIds>;
+}
+/** First-run state: what facts are, the kinds they capture, and one-tap examples. */
+export declare function FactsEmptyState({ onUseExample, labels, testIds }: FactsEmptyStateProps): import("react").JSX.Element;
+/** Centered "Loading facts…" line. */
+export declare function FactsLoading({ label, }: {
+    label?: string;
+}): import("react").JSX.Element;
+/** Load-failure message with a retry action. */
+export declare function FactsLoadError({ onRetry, message, retryLabel, }: {
+    onRetry: () => void;
+    message?: string;
+    retryLabel?: string;
+}): import("react").JSX.Element;

package/dist/facts/FactsFieldsButton.d.ts

@@ -0,0 +1,21 @@
+import type { GridApi } from 'ag-grid-community';
+export interface FactsFieldsButtonLabels {
+    fields: string;
+    defaultView: string;
+    columns: string;
+    /** Names for icon-only columns, keyed by colId. */
+    columnNames: Record<string, string>;
+}
+export declare const DEFAULT_FACTS_FIELDS_BUTTON_LABELS: FactsFieldsButtonLabels;
+export interface FactsFieldsButtonTestIds {
+    trigger: string;
+    defaultView: string;
+    toggle: (colId: string) => string;
+}
+export interface FactsFieldsButtonProps<TData = unknown> {
+    /** The facts grid api (read lazily: the grid may not exist yet). */
+    getGridApi: () => GridApi<TData> | null | undefined;
+    labels?: Partial<FactsFieldsButtonLabels>;
+    testIds?: Partial<FactsFieldsButtonTestIds>;
+}
+export declare function FactsFieldsButton<TData = unknown>({ getGridApi, labels, testIds, }: FactsFieldsButtonProps<TData>): import("react").JSX.Element;

package/dist/facts/FactsFilterInput.d.ts

@@ -0,0 +1,46 @@
+/**
+ * FactsFilterInput
+ *
+ * The Facts table's "Filter…" box, styled to match the Documents table's filter
+ * bar: a muted input with a leading funnel icon and an appended settings button
+ * whose popover picks WHICH fields the text matches against (the fact text, its
+ * labels, or both). The page owns the query + field state; this is a view.
+ */
+import type { ReactNode } from 'react';
+export type FactsSearchField = 'text' | 'labels';
+export declare const FACTS_SEARCH_FIELD_OPTIONS: {
+    value: FactsSearchField;
+    label: string;
+}[];
+export interface FactsFilterInputLabels {
+    placeholder: string;
+    clear: string;
+    chooseFields: string;
+    fieldsHeading: string;
+    /** Display name per searchable field. */
+    fieldNames: Record<FactsSearchField, string>;
+}
+export declare const DEFAULT_FACTS_FILTER_INPUT_LABELS: FactsFilterInputLabels;
+export interface FactsFilterInputTestIds {
+    root: string;
+    quick: string;
+    input: string;
+    fieldsButton: string;
+    field: (field: FactsSearchField) => string;
+}
+export interface FactsFilterInputProps {
+    value: string;
+    onChange: (q: string) => void;
+    fields: FactsSearchField[];
+    onFieldsChange: (fields: FactsSearchField[]) => void;
+    /**
+     * The quick-filter dropdown trigger, embedded inside the input on the left
+     * (mirroring the Files search box). When absent, a static funnel icon shows.
+     */
+    filter?: ReactNode;
+    /** Width classes for the box (default `w-44`). */
+    className?: string;
+    labels?: Partial<FactsFilterInputLabels>;
+    testIds?: Partial<FactsFilterInputTestIds>;
+}
+export declare function FactsFilterInput({ value, onChange, fields, onFieldsChange, filter, className, labels, testIds, }: FactsFilterInputProps): import("react").JSX.Element;

package/dist/facts/FactsTable.d.ts

@@ -0,0 +1,28 @@
+import { type GridViewProps } from '../files/GridView';
+import { type FactColumnLabels, type FactRowView } from './factColumns';
+export interface FactsTableProps<T extends FactRowView> {
+    facts: T[];
+    onTogglePin: (fact: T) => void;
+    onToggleConfirmed: (fact: T) => void;
+    onToggleShared: (fact: T) => void;
+    /** The row menu appears when both `onEdit` and `onDelete` are provided. */
+    onEdit?: (fact: T) => void;
+    onDelete?: (fact: T) => void;
+    /** Row click (opens the fact). */
+    onOpen?: (fact: T) => void;
+    /** Display name of the fact's creator (sorting, filtering and the initials chip). */
+    getCreatorName?: (fact: T) => string;
+    /** Friendly display of an ISO timestamp. Defaults to the locale date. */
+    formatDate?: (iso: string) => string;
+    columnLabels?: Partial<FactColumnLabels>;
+    isLoading?: boolean;
+    /** Saved column state key (AG Grid persists by it). */
+    gridId?: string;
+    height?: GridViewProps<T>['height'];
+    rowHeight?: number;
+    /** Escape hatch for any other `GridView` prop. */
+    gridProps?: Partial<Omit<GridViewProps<T>, 'items' | 'columnDefs' | 'getItemId'>>;
+    testId?: string;
+}
+/** The default facts table: columns, cells and the grid in one component. */
+export declare function FactsTable<T extends FactRowView>({ facts, onTogglePin, onToggleConfirmed, onToggleShared, onEdit, onDelete, onOpen, getCreatorName, formatDate, columnLabels, isLoading, gridId, height, rowHeight, gridProps, testId, }: FactsTableProps<T>): import("react").JSX.Element;

package/dist/facts/FactsToolbar.d.ts

@@ -0,0 +1,53 @@
+import { type ReactNode } from 'react';
+import { type FactsFilterInputLabels, type FactsFilterInputTestIds, type FactsSearchField } from './FactsFilterInput';
+import { type FactsViewMode, type FactsViewToggleLabels } from './FactsViewToggle';
+export interface FactsToolbarLabels {
+    tags: string;
+    newFact: string;
+}
+export declare const DEFAULT_FACTS_TOOLBAR_LABELS: FactsToolbarLabels;
+export interface FactsToolbarTestIds {
+    tab: string;
+    tagsButton: string;
+    newFact: string;
+    filterBar: string;
+    filterBarNav: string;
+}
+export interface FactsToolbarProps {
+    /** Facts matching the current filters (shown beside the glyph). */
+    count: number;
+    /** Solid-fill the count while any filter is narrowing the list. */
+    hasActiveFilters: boolean;
+    filterText: string;
+    onFilterTextChange: (text: string) => void;
+    searchFields: FactsSearchField[];
+    onSearchFieldsChange: (fields: FactsSearchField[]) => void;
+    /** The quick-filter dropdown, embedded inside the filter box. */
+    quickFilter?: ReactNode;
+    /** Open the Labels panel. Omit it to hide the Tags button. */
+    onOpenTags?: () => void;
+    viewMode: FactsViewMode;
+    onViewModeChange: (mode: FactsViewMode) => void;
+    onNewFact: () => void;
+    /** Second row: left slot for the row navigator (portal host for calendar/timeline). */
+    navSlotRef?: (el: HTMLElement | null) => void;
+    /** Table navigator rendered directly in the left slot. */
+    navigator?: ReactNode;
+    /** Second row, right side: per-view controls (Fields, density, zoom). */
+    tools?: ReactNode;
+    /** Smart Search has no toolbar row. */
+    showToolbarRow?: boolean;
+    labels?: Partial<FactsToolbarLabels>;
+    testIds?: Partial<FactsToolbarTestIds>;
+    /** Overrides for the embedded filter box. */
+    filterLabels?: Partial<FactsFilterInputLabels>;
+    filterTestIds?: Partial<FactsFilterInputTestIds>;
+    /** Overrides for the embedded view toggle. */
+    viewToggleLabels?: Partial<FactsViewToggleLabels>;
+    viewToggleTestIdPrefix?: string;
+}
+/**
+ * Facts page header: count tab with filter box and Tags button, the view toggle centred, New fact
+ * on the right (the page's one primary action), and a second row for per-view controls.
+ */
+export declare function FactsToolbar({ count, hasActiveFilters, filterText, onFilterTextChange, searchFields, onSearchFieldsChange, quickFilter, onOpenTags, viewMode, onViewModeChange, onNewFact, navSlotRef, navigator, tools, showToolbarRow, labels, testIds, filterLabels, filterTestIds, viewToggleLabels, viewToggleTestIdPrefix, }: FactsToolbarProps): import("react").JSX.Element;

package/dist/facts/FactsViewToggle.d.ts

@@ -0,0 +1,38 @@
+/**
+ * FactsViewToggle
+ *
+ * Table / Calendar / Timeline switch for the Notes page. (The list view
+ * retired into the table — 'list' stays in the type for old deep links,
+ * which the page maps to 'table'.) Uses the shared
+ * ViewToggle so it matches Documents (Gallery / Table / Review), Home and Smart
+ * Search rather than being a fifth bespoke button group, and sits in the tab
+ * header where every other page puts its views.
+ *
+ * Calendar and Timeline read only the dated notes — a note without a date has
+ * nowhere to sit on either — which the tooltips say rather than the labels.
+ */
+export type FactsViewMode = 'list' | 'table' | 'calendar' | 'gantt' | 'smart_search';
+export interface FactsViewToggleLabels {
+    table: string;
+    calendar: string;
+    timeline: string;
+    smartSearch: string;
+}
+export declare const DEFAULT_FACTS_VIEW_TOGGLE_LABELS: FactsViewToggleLabels;
+export interface FactsViewToggleProps {
+    viewMode: FactsViewMode;
+    onChange: (mode: FactsViewMode) => void;
+    /**
+     * Collapse the labels to icons. Driven by a width measurement of the header
+     * row (see FactsPage) rather than a `@container`, so the toggle can stay
+     * absolutely centred — its position never shifts with the side controls —
+     * while still collapsing when the row actually runs out of room.
+     */
+    collapsed?: boolean;
+    labels?: Partial<FactsViewToggleLabels>;
+    /** Item test ids are `${testIdPrefix}-${mode}-button` (default `facts-layout`). */
+    testIdPrefix?: string;
+    /** Per-mode item ids that replace the prefixed ones. */
+    testIds?: Partial<Record<FactsViewMode, string>>;
+}
+export declare function FactsViewToggle({ viewMode, onChange, collapsed, labels, testIdPrefix, testIds, }: FactsViewToggleProps): import("react").JSX.Element;

package/dist/facts/fact-date.d.ts

@@ -0,0 +1,22 @@
+export interface FactDateFields {
+    /** `YYYY-MM-DD`. Empty means the fact has no date at all. */
+    date: string;
+    /** `HH:MM`. Empty means `date` is a whole day, not an instant. */
+    time: string;
+    /** IANA zone `time` is expressed in. Only meaningful (and only sent) when `time` is set. */
+    timezone: string;
+    /** `YYYY-MM-DD` end of a range. Empty means a single day/instant, not a span. */
+    endDate: string;
+    /** `HH:MM` paired with `endDate`, only offered once `time` is set. */
+    endTime: string;
+}
+export declare const EMPTY_FACT_DATE_FIELDS: FactDateFields;
+/** Editable fields from a stored fact's date span — the inverse of `factDateFieldsToSpan`. */
+export declare function factDateSpanToFields(dateStart: string | null | undefined, dateEnd: string | null | undefined, timezone: string | null | undefined): FactDateFields;
+/** A fact's date span for the API — the inverse of `factDateSpanToFields`. `null`s
+ *  clear the span entirely; a bare date (no time) stays timezone-agnostic. */
+export declare function factDateFieldsToSpan(fields: FactDateFields): {
+    date: string | null;
+    date_end: string | null;
+    timezone: string | null;
+};

package/dist/facts/fact-row.d.ts

@@ -0,0 +1,32 @@
+import type { FactRowView } from './factColumns';
+/**
+ * A fact as a host with plain records usually holds it: camelCase, optional flags, tags as
+ * strings. `toFactRow` maps it to the `FactRowView` that `FactsTable` and `createFactColumns`
+ * read, so a host without the SDK type needs no adapter of its own.
+ */
+export interface PlainFactRecord {
+    id: string;
+    text: string;
+    pinned?: boolean;
+    confirmed?: boolean;
+    shared?: boolean;
+    /** ISO date (or date-time) the fact starts. */
+    dateStart?: string | null;
+    dateEnd?: string | null;
+    timezone?: string | null;
+    tags?: Array<string | {
+        name: string;
+    }> | null;
+    /** Passages that support the fact; only their count is shown. */
+    citations?: unknown[] | null;
+    createdBy?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+}
+/** The row plus the record it came from, so callbacks can hand the host its own object back. */
+export type PlainFactRow<T extends PlainFactRecord> = FactRowView & {
+    record: T;
+};
+/** Map one plain record to a grid row. Missing flags are `false`, missing lists are empty. */
+export declare function toFactRow<T extends PlainFactRecord>(record: T): PlainFactRow<T>;
+export declare function toFactRows<T extends PlainFactRecord>(records: T[]): PlainFactRow<T>[];

package/dist/facts/fact-text.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A fact's text is written in the rich markdown editor, which encodes
+ * otherwise-insignificant whitespace as HTML character references so it survives
+ * markdown's round-trip — a trailing space becomes ` `, a tab `	`, and
+ * so on. The editor decodes them back when it re-renders, but anything that
+ * shows the raw text (the grid cell, its tooltip) prints the reference verbatim,
+ * so a fact reads like `This is a fact. ` instead of `This is a fact.`.
+ *
+ * {@link decodeWhitespaceEntities} turns those references back into the
+ * characters they stand for. Only WHITESPACE code points are decoded, so the
+ * result is safe both to store as markdown (an escaped `*` or `<` is never
+ * turned back into active syntax) and to show as plain text.
+ */
+export declare function decodeWhitespaceEntities(text: string | null | undefined): string;

package/dist/facts/factColumns.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Column definitions for the Facts grid. Every column has an explicit `colId` (AG Grid persists
+ * column state by id: see CLAUDE.md). The app supplies behaviour and app-specific cells through
+ * slots; the structure, widths, sorting, filters and presentational cells live here.
+ */
+import type { ReactNode } from 'react';
+import type { ColDef, ICellRendererParams, IHeaderParams, ValueGetterParams } from 'ag-grid-community';
+export interface FactColumnLabels {
+    pinnedHeaderTooltip: string;
+    pinnedTitle: string;
+    unpinnedTitle: string;
+    unpin: string;
+    pin: string;
+    fact: string;
+    dates: string;
+    dateTitle: string;
+    labels: string;
+    verified: string;
+    verifiedTooltip: string;
+    shared: string;
+    sharedTooltip: string;
+    createdBy: string;
+    sources: string;
+    /** Tooltip of the Sources cell for `count` cited documents. */
+    sourcedFrom: (count: number) => string;
+    createdAt: string;
+    updated: string;
+    id: string;
+}
+export declare const DEFAULT_FACT_COLUMN_LABELS: FactColumnLabels;
+export interface FactColumnTestIds {
+    pinned: (factId: string) => string;
+    text: (factId: string) => string;
+    date: (factId: string) => string;
+}
+/** The fields of a fact the grid reads. Callers' richer types are accepted as-is. */
+export interface FactRowView {
+    external_id: string;
+    text: string;
+    pinned: boolean;
+    confirmed: boolean;
+    shared: boolean;
+    date_start?: string | null;
+    date_end?: string | null;
+    timezone?: string | null;
+    tags?: Array<{
+        name: string;
+    }> | null;
+    citations?: unknown[] | null;
+    created_by_ext_id?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+}
+export interface FactColumnSlots<T extends FactRowView> {
+    onTogglePin: (fact: T) => void;
+    /** Custom header (persistent filter button) for the columns that use one. */
+    renderHeader: (params: IHeaderParams, colId: string) => ReactNode;
+    /** Row action menu, shown at the right edge of the Fact cell. */
+    renderRowActions: (fact: T, params: ICellRendererParams<T>) => ReactNode;
+    /** Inline label picker for the Labels cell. */
+    renderLabels: (fact: T, params: ICellRendererParams<T>) => ReactNode;
+    /** The Verified switch. */
+    renderVerified: (fact: T) => ReactNode;
+    /** The Shared switch. */
+    renderShared: (fact: T) => ReactNode;
+    /** The creator avatar. */
+    renderCreator: (fact: T, params: ICellRendererParams<T>) => ReactNode;
+    /** Sort/filter value for the Created by column (the creator's display name). */
+    getCreatorName: (params: ValueGetterParams<T>) => string;
+    /** Friendly display of an ISO timestamp (Created at / Updated). */
+    formatDate: (iso: string) => string;
+    labels?: Partial<FactColumnLabels>;
+    testIds?: Partial<FactColumnTestIds>;
+}
+/**
+ * Date-filter params for a column whose value is an ISO string. AG Grid hands the comparator a JS
+ * `Date` from the picker and the raw cell value; this compares UTC day components so a filter
+ * never shifts a date by a day for viewers west of UTC.
+ */
+export declare const ISO_DATE_FILTER_PARAMS: {
+    browserDatePicker: boolean;
+    comparator: (filterDate: Date, cellValue: unknown) => number;
+};
+/** How many source documents a fact cites (the Sources column counts documents, not passages). */
+export declare function sourceDocCount(fact: Pick<FactRowView, 'citations'> | undefined): number;
+/** Default left-to-right order; default-hidden columns trail. Every colId must be listed. */
+export declare const DEFAULT_FACT_COLUMN_ORDER: readonly ["pinned", "text", "sources", "tags", "date", "confirmed", "shared", "created_by", "created_at", "updated_at", "note_id"];
+export declare function createFactColumns<T extends FactRowView>(slots: FactColumnSlots<T>): ColDef<T>[];