clio-design-system 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,731 @@
+import * as react from 'react';
+import { ButtonHTMLAttributes, ReactNode, MouseEvent, InputHTMLAttributes, ChangeEventHandler, CSSProperties, TextareaHTMLAttributes, HTMLAttributes, DragEventHandler, ElementType, MouseEventHandler } from 'react';
+
+interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'style' | 'title' | 'type'> {
+    /** Visual treatment. 'nav' is the segmented top-bar tab style (Learn/Practice/Review). */
+    variant?: 'primary' | 'dark' | 'secondary' | 'ghost' | 'nav';
+    size?: 'sm' | 'md';
+    /** For variant="nav" — whether this tab is the active one. */
+    active?: boolean;
+    disabled?: boolean;
+    /** Optional leading glyph, e.g. an ↥ import icon. Rendered aria-hidden — pass meaningful text via children, not icon. */
+    icon?: ReactNode;
+    children?: ReactNode;
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    title?: string;
+}
+/**
+ * Button — Clio's pill-shaped mono-label action button.
+ * Variants: primary (filled accent), dark (filled ink-900, e.g. DOWNLOAD),
+ * secondary (outlined), ghost (text-only), nav (segmented top-nav tab).
+ */
+declare function Button({ variant, size, active, disabled, icon, children, onClick, title, ...rest }: ButtonProps): react.JSX.Element;
+
+interface IconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'style' | 'type' | 'title'> {
+    size?: number;
+    children?: ReactNode;
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    /** Also used as the accessible name (via aria-label) — required so glyph-only buttons are never announced by their raw unicode content. */
+    title: string;
+    /** Adds a hairline border + surface fill (used for ⚙ manage-tags, ⇥ import/export). */
+    bordered?: boolean;
+    hoverColor?: string;
+    disabled?: boolean;
+    /** Corner radius token. Defaults to the standard control radius; row-level menu triggers use the smaller 'var(--radius-sm)'. */
+    radius?: string;
+}
+/**
+ * IconButton — circular glyph-only button (⋯ menu trigger, ⚙ manage tags,
+ * chevron collapse toggle, back arrow).
+ */
+declare function IconButton({ size, children, onClick, title, bordered, hoverColor, disabled, radius, onMouseEnter, onMouseLeave, onFocus, onBlur, ...rest }: IconButtonProps): react.JSX.Element;
+
+interface TagChipProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'style' | 'color' | 'type'> {
+    label: string;
+    /** Tag or topic color — tints when inactive, fills solid when active. */
+    color?: string;
+    active?: boolean;
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    removable?: boolean;
+    onRemove?: () => void;
+    size?: 'sm' | 'md';
+}
+/**
+ * TagChip — mono capsule tag (#exam-prep). Two states: inactive (tinted)
+ * and active/selected (solid fill, white text) used in tag filter bars.
+ */
+declare function TagChip({ label, color, active, onClick, removable, onRemove, size, ...rest }: TagChipProps): react.JSX.Element;
+
+interface BadgeProps {
+    variant?: 'topic' | 'mono' | 'eyebrow' | 'count';
+    color?: string;
+    tint?: string;
+    children?: ReactNode;
+}
+/**
+ * Badge — small labeled pill/rect used across the product:
+ *  - 'topic'   : rounded-rect topic-color label on note headers (e.g. MACHINE LEARNING)
+ *  - 'mono'    : neutral rounded-rect mono badge (e.g. MULTIPLE CHOICE problem type)
+ *  - 'eyebrow' : borderless mono accent label above a content card (e.g. INTERACTIVE, CODE)
+ *  - 'count'   : small circular counter (review due-count)
+ */
+declare function Badge({ variant, children, color, tint }: BadgeProps): react.JSX.Element;
+
+interface SolvedStatusButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'style' | 'type'> {
+    solved?: boolean;
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+}
+/**
+ * SolvedStatusButton — Practice problem's status toggle. Two states only:
+ * unsolved (neutral outline, "MARK SOLVED") and solved (green tint, "✓ SOLVED").
+ * FLAGGED IN README: exact green was inferred from the app's shared success
+ * color (#059669) — confirm this is intentional vs. a distinct status hue.
+ */
+declare function SolvedStatusButton({ solved, onClick, ...rest }: SolvedStatusButtonProps): react.JSX.Element;
+
+interface TextInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'style' | 'aria-label' | 'type'> {
+    value: string;
+    onChange: ChangeEventHandler<HTMLInputElement>;
+    placeholder?: string;
+    mono?: boolean;
+    autoFocus?: boolean;
+    style?: CSSProperties;
+    /** Accessible name. The source design has no visible label for this field — pass this when the placeholder alone isn't a sufficient accessible name. */
+    'aria-label'?: string;
+    /** Restricted to text-like input types — this component's value/onChange contract assumes a string, which checkbox/radio/file don't provide. */
+    type?: 'text' | 'search' | 'email' | 'password' | 'tel' | 'url';
+}
+/** TextInput — single-line text field (rename inputs, tag search). */
+declare function TextInput({ value, onChange, placeholder, mono, autoFocus, style, 'aria-label': ariaLabel, type, ...rest }: TextInputProps): react.JSX.Element;
+
+interface TextAreaProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'onChange' | 'style' | 'aria-label'> {
+    value: string;
+    onChange: ChangeEventHandler<HTMLTextAreaElement>;
+    placeholder?: string;
+    rows?: number;
+    mono?: boolean;
+    /** Accessible name. The source design has no visible label for this field — pass this when the placeholder alone isn't a sufficient accessible name. */
+    'aria-label'?: string;
+}
+/** TextArea — multi-line field (import/export paste box). */
+declare function TextArea({ value, onChange, placeholder, rows, mono, 'aria-label': ariaLabel, ...rest }: TextAreaProps): react.JSX.Element;
+
+interface AvatarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    initial?: string;
+    size?: number;
+    dark?: boolean;
+    style?: CSSProperties;
+}
+/** Avatar — user initial circle in the topbar (dark mono initial on tint). */
+declare function Avatar({ initial, size, dark, style, ...rest }: AvatarProps): react.JSX.Element;
+
+interface ColorSwatchProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'style' | 'color' | 'type' | 'title'> {
+    color: string;
+    active?: boolean;
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    size?: number;
+    title?: string;
+}
+/** ColorSwatch — small circular color-picker swatch used in recolor rows. */
+declare const ColorSwatch: react.ForwardRefExoticComponent<ColorSwatchProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface DragHandleProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'onDragStart' | 'title' | 'style'> {
+    onDragStart?: DragEventHandler<HTMLSpanElement>;
+    title?: string;
+    style?: CSSProperties;
+}
+/**
+ * DragHandle — the ⋮⋮ grip used to reorder topic/note rows.
+ *
+ * KNOWN GAP: this uses HTML5 native drag-and-drop (the `draggable` attribute),
+ * which has no keyboard equivalent — keyboard-only and screen-reader users
+ * cannot trigger it. It's marked aria-hidden so it isn't announced as a
+ * false, non-operable affordance in the meantime. Real keyboard reordering
+ * (e.g. Space to lift, arrow keys to move, a live region announcing the new
+ * position) needs actual reorder state to wire into, which belongs in the
+ * list that owns it (Sidebar/TopicRow/NoteRow) — revisit this when those
+ * are built, not in this leaf component alone.
+ */
+declare function DragHandle({ onDragStart, title, style, ...rest }: DragHandleProps): react.JSX.Element;
+
+type NavTabId = 'notes' | 'practice' | 'review';
+interface NavTabsProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role' | 'onChange'> {
+    active?: NavTabId;
+    onChange?: (id: NavTabId) => void;
+    reviewCount?: number;
+}
+/**
+ * NavTabs — top-bar Learn / Practice / Review segmented control, with an
+ * optional due-count badge on the Review tab.
+ *
+ * Implements the ARIA tabs pattern (role="tablist"/"tab", aria-selected,
+ * roving tabindex + arrow-key navigation) rather than aria-current, since
+ * these buttons swap the active view in place — aria-current is intended for
+ * navigation links to different pages/locations, not view-switching controls.
+ */
+declare function NavTabs({ active, onChange, reviewCount, ...rest }: NavTabsProps): react.JSX.Element;
+
+interface SidebarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    collapsed?: boolean;
+    onToggle?: () => void;
+    /** Eyebrow section label, e.g. "TOPICS" or "CONCEPTS". */
+    label?: string;
+    width?: number;
+    children?: ReactNode;
+    borderSide?: 'right' | 'none';
+    style?: CSSProperties;
+}
+/**
+ * Sidebar — collapsible panel shell used for both the topics column and the
+ * notes column on desktop. Collapsed state shrinks to a 26px chevron rail;
+ * expanded shows a scrollable content area. Pass a section label + children.
+ */
+declare function Sidebar({ collapsed, onToggle, label, width, children, borderSide, style, ...rest }: SidebarProps): react.JSX.Element;
+
+interface TopicRowProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onClick' | 'style' | 'color'> {
+    name: string;
+    color: string;
+    notesLabel: string;
+    selected?: boolean;
+    onClick?: () => void;
+    onMenuClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    draggable?: boolean;
+    onDragStart?: DragEventHandler<HTMLSpanElement>;
+    /** Mobile topics-screen layout omits the drag handle + indent. */
+    dense?: boolean;
+    style?: CSSProperties;
+}
+/**
+ * TopicRow — a single row in the topics sidebar (desktop) / topics screen
+ * (mobile). Shows color dot, name, note count, drag handle, and a hover-
+ * revealed ⋯ menu. `selected` drives the sunken background + bold text.
+ *
+ * The selectable area (dot + name + note count) is a real <button>, not a
+ * click handler on the outer row: the row also hosts the drag handle and the
+ * ⋯ menu button, and an ARIA `role="button"` on the outer element would
+ * improperly nest interactive descendants inside another interactive
+ * element. A native button sidesteps that entirely.
+ */
+declare function TopicRow({ name, color, notesLabel, selected, onClick, onMenuClick, draggable, onDragStart, dense, style, ...rest }: TopicRowProps): react.JSX.Element;
+
+interface NoteRowTag {
+    label: string;
+    color: string;
+}
+interface NoteRowProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onClick' | 'style'> {
+    title: string;
+    meta: string;
+    selected?: boolean;
+    showTopic?: boolean;
+    topicColor?: string;
+    topicName?: string;
+    tags?: NoteRowTag[];
+    onClick?: () => void;
+    onMenuClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    draggable?: boolean;
+    onDragStart?: DragEventHandler<HTMLSpanElement>;
+    style?: CSSProperties;
+}
+/**
+ * NoteRow — a single concept/note row in the notes list (desktop sidebar
+ * column 2) / concepts screen (mobile). Optional topic dot+label (shown
+ * when listing across topics, e.g. tag-filtered results) and tag chips.
+ *
+ * Like TopicRow, the selectable area is a real <button> rather than a click
+ * handler on the outer row, since the row also hosts the drag handle and the
+ * ⋯ menu button as separate interactive controls.
+ */
+declare function NoteRow({ title, meta, selected, showTopic, topicColor, topicName, tags, onClick, onMenuClick, draggable, onDragStart, style, ...rest }: NoteRowProps): react.JSX.Element;
+
+interface ContextMenuItem {
+    label?: string;
+    onClick?: () => void;
+    danger?: boolean;
+    icon?: ReactNode;
+    divider?: boolean;
+}
+interface ContextMenuSwatch {
+    color: string;
+    active?: boolean;
+    pick: () => void;
+}
+interface ContextMenuProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onClick' | 'style' | 'role' | 'tabIndex'> {
+    items: ContextMenuItem[];
+    /** Recolor swatch row, e.g. topic/tag color picker. */
+    swatches?: ContextMenuSwatch[];
+    width?: number;
+    style?: CSSProperties;
+    /** Called on Escape — the menu itself doesn't track open/closed state; the parent (typically toggled by a row's ⋯ button) owns that. */
+    onClose?: () => void;
+    /** Accessible label for the menu, since its contents vary by context (e.g. "Topic options"). */
+    'aria-label'?: string;
+}
+/**
+ * ContextMenu — desktop floating dropdown (topic ⋯, note ⋯, manage tags).
+ * Pass `items`: array of { label, onClick, danger? } or { divider: true },
+ * plus optional `swatches` (color-recolor row) and `header`.
+ *
+ * Implements the ARIA menu pattern: role="menu"/"menuitem", roving tabindex,
+ * Arrow/Home/End navigation, and Escape-to-close — none of which the source
+ * design has, since it only renders the dropdown's visual chrome.
+ */
+declare function ContextMenu({ items, swatches, width, style, onClose, 'aria-label': ariaLabel, ...rest }: ContextMenuProps): react.JSX.Element;
+
+interface BottomSheetProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style' | 'onClick' | 'role' | 'aria-modal' | 'tabIndex'> {
+    open: boolean;
+    onClose?: () => void;
+    children?: ReactNode;
+    maxHeight?: string | number;
+    style?: CSSProperties;
+    /** Accessible name for the sheet, since its content varies by context (e.g. "Topic actions"). Prefer aria-labelledby if the sheet's content has its own visible heading. */
+    'aria-label'?: string;
+}
+/**
+ * BottomSheet — mobile modal pattern: dims the screen, slides a rounded-top
+ * panel up from the bottom with a drag-handle bar. Used for topic/note
+ * action sheets, manage-tags, add-tag, and the TOC outline.
+ *
+ * A true modal dialog: role="dialog" + aria-modal, focus moves into the
+ * sheet on open and is trapped there, Escape closes it, and focus returns to
+ * whatever triggered it on close (see internal/useDialog). The source design
+ * has none of this — it's presentational chrome only.
+ */
+declare function BottomSheet({ open, onClose, children, maxHeight, style, 'aria-label': ariaLabel, ...rest }: BottomSheetProps): react.JSX.Element | null;
+
+type ImportExportTab = 'import' | 'export';
+interface ImportExportModalProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style' | 'onClick' | 'role' | 'aria-modal' | 'tabIndex'> {
+    open: boolean;
+    tab?: ImportExportTab;
+    onTabChange?: (tab: ImportExportTab) => void;
+    onClose?: () => void;
+    children?: ReactNode;
+}
+/**
+ * ImportExportModal — desktop centered modal (mobile uses a full-screen
+ * variant, same content structure with a header row instead of an X close).
+ *
+ * A true modal dialog: role="dialog" + aria-modal, focus trapped inside and
+ * moved in on open / restored on close (internal/useDialog), Escape closes,
+ * and page scroll is locked while open (unlike BottomSheet, this overlay is
+ * `position: fixed; inset: 0` over the whole viewport, so background scroll
+ * genuinely needs to be suppressed here). The Import/Export toggle uses the
+ * ARIA tabs pattern (role="tablist"/"tab", aria-selected, roving tabindex +
+ * arrow-key navigation) since it swaps the modal's content in place, same
+ * reasoning as NavTabs. None of this exists in the source design.
+ */
+declare function ImportExportModal({ open, tab, onTabChange, onClose, children, ...rest }: ImportExportModalProps): react.JSX.Element | null;
+interface ExportRowProps {
+    title: string;
+    sub: string;
+    onCopy?: () => void;
+    copyLabel?: string;
+    onDownload?: () => void;
+}
+/** ExportRow — one exportable-item row inside the EXPORT tab (This note, Topic, Full backup). */
+declare function ExportRow({ title, sub, onCopy, copyLabel, onDownload }: ExportRowProps): react.JSX.Element;
+
+interface TocItem {
+    label: string;
+    active?: boolean;
+    go?: () => void;
+}
+interface TocRailProps extends Omit<HTMLAttributes<HTMLElement>, 'onMouseEnter' | 'onMouseLeave' | 'onFocus' | 'onBlur' | 'aria-label' | 'style'> {
+    items: TocItem[];
+    /** Hovering (or focusing, via keyboard) the rail expands dots into labels. */
+    hovered?: boolean;
+    onHoverIn?: () => void;
+    onHoverOut?: () => void;
+    'aria-label'?: string;
+    style?: CSSProperties;
+}
+/**
+ * TocRail — desktop floating-dot outline rail (scroll-spy), hover to reveal
+ * labels.
+ *
+ * The source design only expands labels on mouse hover (onMouseEnter/
+ * onMouseLeave on the wrapping div) — a keyboard user tabbing through the
+ * rail's buttons never sees the labels, only bare dots. Also triggers the
+ * same expansion on focus-within (with a relatedTarget check so tabbing
+ * between the rail's own buttons doesn't flicker collapsed/expanded), and
+ * wraps the items in nav > ol so screen readers announce it as a real list
+ * inside a labeled navigation landmark, with aria-current marking the
+ * active section (this is exactly what aria-current is for — the current
+ * location within a browsing context — unlike a view-switching control).
+ * role="list" on the <ol> works around a long-standing Safari/VoiceOver
+ * quirk where `list-style: none` drops the implicit list semantics.
+ */
+declare function TocRail({ items, hovered, onHoverIn, onHoverOut, 'aria-label': ariaLabel, style, ...rest }: TocRailProps): react.JSX.Element;
+
+interface TocFabProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'style' | 'type'> {
+    onClick?: () => void;
+    /** Accessible name — the glyph alone ("☰") has no meaning to a screen reader. */
+    'aria-label'?: string;
+    style?: CSSProperties;
+}
+/** TocFab — mobile floating action button that opens the TOC bottom sheet. */
+declare function TocFab({ onClick, 'aria-label': ariaLabel, style, ...rest }: TocFabProps): react.JSX.Element;
+
+interface TocSheetListProps {
+    items: TocItem[];
+}
+/**
+ * TocSheetList — the outline list rendered inside a BottomSheet on mobile.
+ *
+ * Wrapped in nav > ol (screen readers announce it as a real list inside a
+ * navigation landmark) with the visible "OUTLINE" eyebrow as the landmark's
+ * accessible name via aria-labelledby, rather than a redundant separate
+ * aria-label repeating the same text. aria-current marks the active section
+ * — this is exactly what aria-current is for (current location within a
+ * browsing context), matching TocRail. role="list" on the <ol> works around
+ * a long-standing Safari/VoiceOver quirk where `list-style: none` drops the
+ * implicit list semantics.
+ */
+declare function TocSheetList({ items }: TocSheetListProps): react.JSX.Element;
+
+interface CardShellProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    children?: ReactNode;
+    dark?: boolean;
+    tint?: boolean;
+    style?: CSSProperties;
+}
+/** CardShell — shared white-surface wrapper most content-card types use. */
+declare function CardShell({ children, dark, tint, style, ...rest }: CardShellProps): react.JSX.Element;
+
+interface CardHeaderProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    /** e.g. "INTERACTIVE", "WALKTHROUGH", "CODE", "COMPARE", "CHECKPOINT" */
+    eyebrow: string;
+    eyebrowColor?: string;
+    title?: string;
+    /**
+     * Element the title renders as. Defaults to a plain `span` (matches the
+     * source design exactly). Content cards sit at an arbitrary point in a
+     * note's document outline that only the consuming app knows — this
+     * library can't safely guess a heading level (h2 vs h3 vs h4) without
+     * risking an inconsistent or skipped-level heading hierarchy. Pass e.g.
+     * "h3" here when the consumer knows the right level and wants the title
+     * reachable via screen-reader heading navigation.
+     */
+    as?: ElementType;
+    subtitle?: string;
+    right?: ReactNode;
+    dark?: boolean;
+    style?: CSSProperties;
+}
+/** CardHeader — eyebrow + title row shared by interactive/walkthrough/code/table/quiz/image/related/references cards. */
+declare function CardHeader({ eyebrow, eyebrowColor, title, as: TitleTag, subtitle, right, dark, style, ...rest }: CardHeaderProps): react.JSX.Element;
+
+interface TextBlockProps extends Omit<HTMLAttributes<HTMLParagraphElement>, 'style' | 'children'> {
+    text: string;
+    style?: CSSProperties;
+}
+/** TextBlock — plain paragraph content block (no card shell, no eyebrow). */
+declare function TextBlock({ text, style, ...rest }: TextBlockProps): react.JSX.Element;
+
+interface EquationBlockProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    /** Raw TeX/LaTeX source — real product renders via KaTeX (`<ka-tex>`). */
+    tex: string;
+    style?: CSSProperties;
+}
+/**
+ * EquationBlock — display-math content block. Renders bare (no card shell).
+ * The real product uses a `<ka-tex>` custom element backed by KaTeX; this
+ * design-system stand-in renders the raw TeX in an italic serif style so
+ * the layout/spacing is representative without a KaTeX runtime dependency.
+ * Consumers should mount the actual `ka-tex` element (see readme.md).
+ */
+declare function EquationBlock({ tex, style, ...rest }: EquationBlockProps): react.JSX.Element;
+
+interface IntuitionCalloutProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    text: string;
+    /** e.g. "INTUITION" or "THIRD LAW" for a named-principle variant. */
+    label?: string;
+    style?: CSSProperties;
+}
+/** IntuitionCallout — tinted amber-ochre inline callout box (plain-language intuition, no card shell/border-radius-2xl but its own padded box). */
+declare function IntuitionCallout({ text, label, style, ...rest }: IntuitionCalloutProps): react.JSX.Element;
+
+interface WalkthroughStep {
+    tex: string;
+    note: string;
+}
+interface WalkthroughCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    title: string;
+    steps: WalkthroughStep[];
+    currentStep: number;
+    onPrev?: () => void;
+    onNext?: () => void;
+    style?: CSSProperties;
+}
+/**
+ * WalkthroughCard — numbered step-through derivation. Steps reveal one at
+ * a time via Back/Next (earlier steps stay visible, dimmed).
+ *
+ * Two fixes over the source: the Next button now gets a real `disabled`
+ * attribute at the last step (it previously only dimmed via opacity while
+ * remaining fully clickable — inconsistent with Back, which already
+ * disables for real at the first step, and would let Next keep firing past
+ * the end). The revealed-steps list is wrapped in an aria-live region so
+ * screen reader users are told a new step appeared after Next/Back, rather
+ * than needing to rediscover it themselves.
+ */
+declare function WalkthroughCard({ title, steps, currentStep, onPrev, onNext, style, ...rest }: WalkthroughCardProps): react.JSX.Element;
+
+interface CodeCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    title: string;
+    lang: string;
+    code: string;
+    copyLabel?: string;
+    onCopy?: () => void;
+    style?: CSSProperties;
+}
+/** CodeCard — dark code block with copy button + optional My-note annotation trigger. */
+declare function CodeCard({ title, lang, code, copyLabel, onCopy, style, ...rest }: CodeCardProps): react.JSX.Element;
+
+interface TableCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    title: string;
+    header: string[];
+    rows: string[][];
+    style?: CSSProperties;
+}
+/**
+ * TableCard — "COMPARE" content block; a labeled comparison table.
+ *
+ * The source markup rendered every cell — header row included — as `<td>`
+ * inside a single flat `<tr>` list, with no `<thead>`/`<tbody>` split: a
+ * screen reader navigating the table got no column-header announcements at
+ * all. This shape is actually a two-way table (header[0] is blank because
+ * it's the corner above the row-label column — rows[i][0] labels that row,
+ * e.g. "Memory", the same way header[1..] label columns, e.g. "SGD"). Fixed
+ * to `<thead><tr><th scope="col">` for the header row and `<th scope="row">`
+ * for each row's first cell — the standard markup for a table with both row
+ * and column headers. The empty corner header cell gets a visually-hidden
+ * label (real content tables always pass a non-empty `header[0]` in
+ * practice, but an empty `<th>` fails an accessibility check regardless of
+ * why it's empty, so this covers that case defensively too).
+ */
+declare function TableCard({ title, header, rows, style, ...rest }: TableCardProps): react.JSX.Element;
+
+interface QuizCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    question: string;
+    answerOpen: boolean;
+    answer: string;
+    quizLabel: string;
+    onToggleQuiz?: () => void;
+    addFlashLabel: string;
+    onAddFlash?: () => void;
+    style?: CSSProperties;
+}
+/**
+ * QuizCard — "CHECKPOINT" self-test block: question, reveal-answer toggle,
+ * add-to-flashcards. Uses the accent-tinted background (mixes with the
+ * active topic color).
+ *
+ * The reveal-answer button is a disclosure widget (it shows/hides the
+ * answer panel below), so it now carries aria-expanded and aria-controls —
+ * the source only changed the button's visible text (quizLabel), giving
+ * assistive tech no programmatic signal of the panel's state or its
+ * relationship to the toggle, same gap fixed on Sidebar's chevron earlier.
+ */
+declare function QuizCard({ question, answerOpen, answer, quizLabel, onToggleQuiz, addFlashLabel, onAddFlash, style, ...rest }: QuizCardProps): react.JSX.Element;
+
+interface ImageCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    /** "UPLOAD" (user's own work) or "FIGURE" (author-provided diagram). */
+    label?: 'UPLOAD' | 'FIGURE';
+    title: string;
+    /** Unique id — required for the drop to persist (see image-slot.js). */
+    slotId: string;
+    placeholder?: string;
+    height?: number;
+    caption?: string;
+    style?: CSSProperties;
+}
+/**
+ * ImageCard — "UPLOAD"/"FIGURE" content block wrapping the product's
+ * `<image-slot>` web component (drag-and-drop image placeholder).
+ *
+ * `<image-slot>` is an opaque vendored utility, not a component this library
+ * owns — its internal accessibility (accessible name, keyboard operability
+ * of the drop zone) lives in that script, out of this port's scope. See
+ * readme.md for the empty/filled state spec, flagged there as ambiguous.
+ */
+declare function ImageCard({ label, title, slotId, placeholder, height, caption, style, ...rest }: ImageCardProps): react.JSX.Element;
+
+interface RelatedCardItem {
+    label: string;
+    color: string;
+    onClick?: (event: MouseEvent) => void;
+    /** Renders as a real link (enabling native middle-click/Cmd-click "open in new tab") instead of a button. */
+    href?: string;
+    /** Render as a custom element/component — e.g. a router's Link — instead of the default <a>/<button>. Receives href and onClick. */
+    as?: ElementType;
+}
+interface RelatedCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    items: RelatedCardItem[];
+    style?: CSSProperties;
+}
+/**
+ * RelatedCard — "RELATED" content block linking to other concepts.
+ *
+ * Items are wrapped in a real <ul role="list">/<li> instead of bare
+ * <button>s, so screen readers announce "list of N items" and let a user
+ * navigate it as a list; the trailing "›" glyph is aria-hidden since it's
+ * purely decorative next to each item's own visible label.
+ *
+ * Each item renders as a real <a href> when `href` is given (so
+ * middle-click/Cmd-click "open in new tab" works natively, which a <button>
+ * can never support), or as a fully custom element via `as` (e.g. a router's
+ * Link component) — falling back to a plain <button> only when neither is
+ * given.
+ */
+declare function RelatedCard({ items, style, ...rest }: RelatedCardProps): react.JSX.Element;
+
+interface ReferencesCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    items: string[];
+    style?: CSSProperties;
+}
+/**
+ * ReferencesCard — "REFERENCES" content block: a simple citation list.
+ *
+ * Items are wrapped in a real <ul role="list">/<li> instead of bare <div>s,
+ * so screen readers announce "list of N items"; the leading "›" glyph is
+ * aria-hidden since it's a purely decorative bullet marker.
+ */
+declare function ReferencesCard({ items, style, ...rest }: ReferencesCardProps): react.JSX.Element;
+
+interface AnnotationPanelProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'onChange' | 'placeholder' | 'style' | 'aria-labelledby' | 'rows'> {
+    open: boolean;
+    value: string;
+    onChange: ChangeEventHandler<HTMLTextAreaElement>;
+    placeholder?: string;
+}
+/**
+ * AnnotationPanel — the "MY NOTE" panel appended to every content-card and
+ * practice-problem type. Always amber, regardless of the active topic
+ * accent. Font is the hand-script Kalam — the ONLY place it's used.
+ *
+ * The visible "MY NOTE" label had no programmatic association with the
+ * textarea below it (just adjacent markup) — linked via aria-labelledby so
+ * the textarea has a real accessible name instead of none. Native textarea
+ * attributes (disabled, maxLength, onKeyDown, onBlur, etc.) spread onto the
+ * textarea itself, since that's the one interactive element here — the
+ * outer wrapper div has no independent need for them.
+ */
+declare function AnnotationPanel({ open, value, onChange, placeholder, ...rest }: AnnotationPanelProps): react.JSX.Element | null;
+
+interface AnnotationToggleProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'style' | 'type'> {
+    hasText?: boolean;
+    open?: boolean;
+    onClick?: MouseEventHandler<HTMLButtonElement>;
+    /** Row is hovered — reveals the otherwise-invisible toggle. */
+    hot?: boolean;
+}
+/**
+ * AnnotationToggle — the small "+ My note" trigger button shown in a card's
+ * header row.
+ *
+ * The source only reveals this button when the parent row reports `hot`
+ * (mouse hover). A keyboard user tabbing to the button directly (without
+ * the row ever being "hot") would land on an invisible-but-focusable
+ * control with no visual indication it exists until they arrive at it.
+ * Reusing the shared useHover hook makes the button also reveal itself on
+ * its own hover/focus, so tabbing to it makes it visible the same way
+ * hovering the row does.
+ */
+declare function AnnotationToggle({ hasText, open, onClick, hot, onMouseEnter, onMouseLeave, onFocus, onBlur, ...rest }: AnnotationToggleProps): react.JSX.Element;
+
+interface McqOptionProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'style' | 'type' | 'disabled'> {
+    label: string;
+    /** 'default' before pick; 'correct'/'wrong' after pick (shown on both the chosen option and the true correct one). */
+    state?: 'default' | 'correct' | 'wrong';
+    onClick?: () => void;
+}
+/**
+ * McqOption — a single multiple-choice option row. States: default, hover,
+ * picked-correct, picked-wrong.
+ *
+ * Two fixes over the source: the ✓/✕ mark was the ONLY signal of an
+ * option's correctness, conveyed purely as a raw glyph character with no
+ * semantic backing — some screen readers won't announce it meaningfully at
+ * all, and unlike a decorative icon next to a text label, hiding it outright
+ * would remove the only indicator entirely. Kept the mark visible but added
+ * adjacent visually-hidden text ("Correct"/"Incorrect") so the state reaches
+ * assistive tech in words, not just a symbol. Also: once a state is set
+ * (the question has been answered), the option is no longer meant to be
+ * re-clickable, but the source left every option fully interactive
+ * regardless of state — added a real `disabled` once state !== 'default'.
+ */
+declare function McqOption({ label, state, onClick, ...rest }: McqOptionProps): react.JSX.Element;
+
+interface FillBlankInputProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    value: string;
+    onChange: ChangeEventHandler<HTMLInputElement>;
+    checked?: boolean;
+    correct?: boolean;
+    onCheck?: () => void;
+    resultLabel?: string;
+    style?: CSSProperties;
+}
+/**
+ * FillBlankInput — fill-in-the-blank answer row with Check button + result
+ * state.
+ *
+ * Reuses the TextInput component (with a style override for the
+ * correct/incorrect border color) instead of a bare hand-rolled <input>. The
+ * input had no accessible name at all beyond its placeholder (not reliable
+ * across browsers/screen readers) — added one, plus aria-invalid reflecting
+ * the check result programmatically, not just via border color. The result
+ * panel is wrapped in an aria-live region so screen reader users hear the
+ * outcome as soon as Check is pressed, rather than needing to find it.
+ */
+declare function FillBlankInput({ value, onChange, checked, correct, onCheck, resultLabel, style, ...rest }: FillBlankInputProps): react.JSX.Element;
+
+interface ScenarioBoxProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+    text: string;
+    style?: CSSProperties;
+}
+/** ScenarioBox — amber-tinted scenario framing shown above a practice prompt. */
+declare function ScenarioBox({ text, style, ...rest }: ScenarioBoxProps): react.JSX.Element;
+
+interface FlashcardProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'style' | 'type' | 'aria-pressed'> {
+    flipped: boolean;
+    front: string;
+    back: string;
+    /** e.g. "BOX 3" or "NEW" */
+    boxLabel: string;
+    onFlip?: () => void;
+}
+/**
+ * Flashcard — flippable review card (front prompt / back answer) + box
+ * label.
+ *
+ * Added aria-pressed (the flip button is a real toggle — flipped/unflipped
+ * — so this is the correct ARIA state for it) and wrapped the revealed
+ * content in an aria-live region so screen reader users hear the answer as
+ * soon as the card flips, rather than needing to re-navigate into the
+ * button to discover it changed.
+ */
+declare function Flashcard({ flipped, front, back, boxLabel, onFlip, ...rest }: FlashcardProps): react.JSX.Element;
+
+interface RateButtonsProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style' | 'role' | 'aria-label'> {
+    /** Only enabled once the card is flipped. */
+    enabled?: boolean;
+    onAgain?: () => void;
+    onGood?: () => void;
+    onEasy?: () => void;
+    style?: CSSProperties;
+}
+/**
+ * RateButtons — Again / Good / Easy spaced-repetition rating row, revealed
+ * once flipped.
+ *
+ * The source "disabled" the row purely via `opacity` + `pointer-events:
+ * none` on the wrapping div, with no `disabled` attribute on the buttons
+ * themselves. `pointer-events: none` blocks mouse clicks but NOT keyboard
+ * activation — a keyboard user could Tab to these buttons and press
+ * Enter/Space to rate a card before flipping it, bypassing the entire
+ * intended flow. Added a real `disabled` to each button so it's actually
+ * inert, not just unclickable by mouse.
+ */
+declare function RateButtons({ enabled, onAgain, onGood, onEasy, style, ...rest }: RateButtonsProps): react.JSX.Element;
+
+export { AnnotationPanel, type AnnotationPanelProps, AnnotationToggle, type AnnotationToggleProps, Avatar, type AvatarProps, Badge, type BadgeProps, BottomSheet, type BottomSheetProps, Button, type ButtonProps, CardHeader, type CardHeaderProps, CardShell, type CardShellProps, CodeCard, type CodeCardProps, ColorSwatch, type ColorSwatchProps, ContextMenu, type ContextMenuItem, type ContextMenuProps, type ContextMenuSwatch, DragHandle, type DragHandleProps, EquationBlock, type EquationBlockProps, ExportRow, type ExportRowProps, FillBlankInput, type FillBlankInputProps, Flashcard, type FlashcardProps, IconButton, type IconButtonProps, ImageCard, type ImageCardProps, ImportExportModal, type ImportExportModalProps, type ImportExportTab, IntuitionCallout, type IntuitionCalloutProps, McqOption, type McqOptionProps, type NavTabId, NavTabs, type NavTabsProps, NoteRow, type NoteRowProps, type NoteRowTag, QuizCard, type QuizCardProps, RateButtons, type RateButtonsProps, ReferencesCard, type ReferencesCardProps, RelatedCard, type RelatedCardItem, type RelatedCardProps, ScenarioBox, type ScenarioBoxProps, Sidebar, type SidebarProps, SolvedStatusButton, type SolvedStatusButtonProps, TableCard, type TableCardProps, TagChip, type TagChipProps, TextArea, type TextAreaProps, TextBlock, type TextBlockProps, TextInput, type TextInputProps, TocFab, type TocFabProps, type TocItem, TocRail, type TocRailProps, TocSheetList, type TocSheetListProps, TopicRow, type TopicRowProps, WalkthroughCard, type WalkthroughCardProps, type WalkthroughStep };