@flytedan/flytebot-design-system 0.8.2 → 0.9.1

package/dist/index.d.ts

@@ -69,12 +69,27 @@ interface PopoverPosition {
 }
 /**
  * Fixed-position layer geometry for an anchored surface. Flips side when the
- * preferred one doesn't fit, clamps to the viewport, and re-measures on scroll
- * and resize (capture phase, so it tracks inside scrolling panels too).
+ * preferred one doesn't fit, clamps to the viewport, and re-measures continuously
+ * while open.
+ *
+ * Continuously, on an animation frame, rather than on scroll and resize events: those
+ * two cover an anchor that moves because the PAGE moved, and miss every other reason an
+ * anchor moves. The one that broke this was a row inside a virtualized list — rows are
+ * positioned by a CSS transform off their index, so re-sorting the list slides a row to
+ * a new slot with no scroll, no resize and no layout event of any kind, and a popover
+ * anchored to it simply stayed behind. Re-measuring per frame costs one
+ * getBoundingClientRect on one element for as long as a popover is open, and state is
+ * only set when the geometry actually changed (see samePosition), so a stationary anchor
+ * causes no re-renders at all.
+ *
+ * The same loop is what notices the anchor being REMOVED — a virtualized row scrolled
+ * out of the mounted band, a menu item deleted — and reports it through `onDetach`, so
+ * an anchored layer can never end up pinned to an element that no longer exists.
  */
 declare function usePopoverPosition(open: boolean, anchorRef: React.RefObject<HTMLElement>, opts?: Partial<PopoverProps> & {
     estHeight?: number;
     estWidth?: number;
+    onDetach?: () => void;
 }): PopoverPosition | null;
 /**
  * An anchored floating surface: menus, pickers, disclosure panels, meters.
@@ -906,6 +921,61 @@ interface QuotaRowProps {
  */
 declare function QuotaRow({ label, percent, note, tone, className }: QuotaRowProps): React.JSX.Element;
 
+interface ScoreMeterProps {
+    /** The score itself, 0-100. Shown as a plain integer next to the rail. */
+    score: number;
+    /** One segment per contributing thing, each already carrying its own colour. Widths
+     *  are proportional to `value` out of 100, so what doesn't contribute reads as the
+     *  empty remainder of the rail rather than as a missing segment. */
+    segments: MeterSegmentInput[];
+    /** Accessible name for the meter, e.g. "Preference score". Required — a bare bar with
+     *  a number next to it is meaningless to a screen reader without one. */
+    label: string;
+    /** Rail width in px. A fixed width (not a flexing one) is what lets a column of these
+     *  line up down a list. */
+    width?: number;
+    height?: number;
+    /** Hide the numeral and show only the rail, for somewhere the number is already said. */
+    showScore?: boolean;
+    /** Content of the breakdown popover. Supplying it is what makes the meter clickable —
+     *  without it this renders as a plain, inert span. */
+    breakdown?: React.ReactNode;
+    /** Accessible name for the popover. Defaults to `label` + " breakdown". */
+    breakdownLabel?: string;
+    placement?: Placement;
+    /** Width of the breakdown popover in px. */
+    breakdownWidth?: number;
+    className?: string;
+}
+/**
+ * ScoreMeter — a small 0-100 score drawn as a categorical bar, optionally opening a
+ * breakdown of how the score was arrived at.
+ *
+ * Not a new meter primitive: the rail IS SegmentedMeter (chosen over CsiMeter because a
+ * score built from a variable number of differently-coloured contributions needs
+ * per-segment colour and a variable segment count, and CsiMeter is fixed at four
+ * segments all drawn in one `currentColor`) with its head and legend turned off, so the
+ * proportional-width maths, the transition, the empty-remainder rail and the full
+ * `role="meter"` aria that SegmentedMeter already ships are used rather than reimplemented.
+ * What this adds is the part SegmentedMeter deliberately lacks: a real trigger.
+ *
+ * The trigger is a `<button>`, never a div with an onClick — three things follow from
+ * that, and all three are the reason it's a button. It is keyboard-operable and
+ * announced as a control; SegmentedMeter's own `onClick` (which lands on a plain div)
+ * is neither. And inside a drag source it is automatically safe: TransferList arms a
+ * drag on any row pointerdown EXCEPT one originating inside a `button`, so the meter
+ * stays clickable in a row you can also pick up and drag, with no extra coordination
+ * between the two components.
+ *
+ * The popover is rendered as this component's own child rather than hoisted, which is
+ * what makes it survive a virtualized list: the anchor and the open state live and die
+ * together, so a row scrolled out of the mounted window takes its popover with it
+ * instead of leaving an orphan pinned to a dead element. While the row IS mounted, the
+ * popover tracks its anchor frame by frame (see usePopoverPosition), so it follows a row
+ * that slides to a new slot when the list is re-sorted underneath it.
+ */
+declare function ScoreMeter({ score, segments, label, width, height, showScore, breakdown, breakdownLabel, placement, breakdownWidth, className, }: ScoreMeterProps): React.JSX.Element;
+
 interface SortMenuField {
     /** Sort key sent to the endpoint. */
     key: string;
@@ -980,17 +1050,29 @@ declare function StepList({ steps, label, defaultOpen, open: openProp, onToggle,
  *  (one per edge) plus the visible band itself is what keeps the mounted node count
  *  bounded — see the file doc comment below for why 20 is the right number here. */
 declare const VIRTUAL_LIST_BUFFER_ROWS = 20;
+/** Default px of empty space left at the bottom of every row slot, which is what reads
+ *  as the gap between two cards. See VirtualListProps.rowGap. */
+declare const VIRTUAL_LIST_ROW_GAP = 6;
+/** Where the caller's loaded slice sits inside the full collection. `firstItemIndex` is
+ *  the absolute index of items[0]; `count` is how many are loaded. For a caller that
+ *  holds the whole collection this is simply { firstItemIndex: 0, count: items.length }. */
+interface VirtualLoadedBand {
+    firstItemIndex: number;
+    count: number;
+}
 interface VirtualWindow {
-    /** Index of the first row a viewport of this height would actually show. */
+    /** ABSOLUTE index of the first row a viewport of this height would actually show. */
     visibleStart: number;
-    /** Index of the last row a viewport of this height would actually show (inclusive). */
+    /** ABSOLUTE index of the last row a viewport of this height would actually show (inclusive). */
     visibleEnd: number;
-    /** Index of the first row that should be mounted in the DOM (visibleStart minus the buffer, clamped to 0). */
+    /** ABSOLUTE index of the first row that should be mounted in the DOM (visibleStart minus
+     *  the buffer), clamped to the loaded band — a row the caller hasn't loaded can't mount. */
     startIndex: number;
-    /** Index of the last row that should be mounted in the DOM (inclusive; visibleEnd plus the buffer, clamped to itemCount - 1). */
+    /** ABSOLUTE index of the last row that should be mounted in the DOM (inclusive). */
     endIndex: number;
     /** Full scrollable height in px — this is what makes the scrollbar/scroll range honest
-     *  about itemCount even though only a slice of it is ever mounted. */
+     *  about the whole collection even though only a slice of it is ever mounted, and it is
+     *  computed from the TOTAL count, never from how many rows happen to be loaded. */
     totalHeight: number;
     /** px the mounted block must be pushed down so its rows land at their real scroll position. */
     offsetY: number;
@@ -1004,23 +1086,38 @@ interface VirtualWindow {
  * Every fixed-height virtualizer boils down to integer division: row i sits at
  * `i * itemHeight` px, so scrollTop/itemHeight lands on the first partially-visible row
  * and (scrollTop + viewportHeight)/itemHeight lands on the last one. Everything else here
- * is clamping that to the buffer and to the real item count.
+ * is clamping that to the buffer, to the real item count, and to whatever slice of it the
+ * caller currently has in memory.
+ *
+ * Every index this returns is ABSOLUTE — an index into the whole collection, not into the
+ * caller's loaded array. That distinction is the entire point of `loaded`: a caller that
+ * keeps a sliding window (say 50 rows retained out of 4,000, discarding rows as it scrolls
+ * rather than accumulating them) still gets row 3,214 drawn at 3,214 * itemHeight and a
+ * scrollbar sized for 4,000 rows. Compute positions off array indices instead and the
+ * whole list jumps every time the window slides.
  */
 declare function computeVirtualWindow(opts: {
     scrollTop: number;
     viewportHeight: number;
     itemHeight: number;
+    /** TOTAL rows in the collection, loaded or not. */
     itemCount: number;
+    /** Which slice of that total is actually in memory. Defaults to "all of it". */
+    loaded?: VirtualLoadedBand;
     bufferRows?: number;
 }): VirtualWindow;
 /**
- * Given the current window and the real item count, says whether the visible band has
- * come within one buffer's width of either edge of what's currently loaded — the signal
+ * Given the current window and the LOADED band, says whether the visible band has come
+ * within one buffer's width of either edge of what's currently in memory — the signal
  * VirtualList uses to ask its caller for more. Threading it through the *visible* band
  * (not the mounted one) means the caller gets asked while the buffer still has rows left
  * to show, not only once the user has scrolled past all of them.
+ *
+ * Measured against the loaded band rather than the total, because "do I need to fetch"
+ * is a question about memory, not about the collection: a caller holding rows 800-849 of
+ * 4,000 needs more in BOTH directions even though it is nowhere near either end.
  */
-declare function computeNeedMore(win: Pick<VirtualWindow, "visibleStart" | "visibleEnd">, itemCount: number, bufferRows?: number): {
+declare function computeNeedMore(win: Pick<VirtualWindow, "visibleStart" | "visibleEnd">, loaded: VirtualLoadedBand, bufferRows?: number): {
     start: boolean;
     end: boolean;
 };
@@ -1029,16 +1126,35 @@ interface VirtualListProps<T> {
     items: T[];
     /** Fixed row height in px. Every row is assumed to be exactly this tall. */
     itemHeight: number;
+    /** px of the row's slot left empty at the bottom, which is what reads as the gap
+     *  between two cards. A real prop rather than a constant because the right gap depends
+     *  on how much the row itself weighs: a one-line 44px row wants the 6px default, a
+     *  two-line card wants more air. Note it comes OUT of itemHeight — the slot is still
+     *  exactly itemHeight tall, so the scroll math is untouched by changing this. */
+    rowGap?: number;
+    /** Called with the ABSOLUTE index of the row (its index in the whole collection), which
+     *  is not the same as its index in `items` once a sliding window is in play. */
     renderItem: (item: T, index: number) => React.ReactNode;
-    /** Fired when the visible band comes within one buffer's width of an edge of `items`
-     *  and that edge isn't known to be exhausted. The caller owns fetching — this only asks. */
-    onNeedMore: (direction: "start" | "end") => void;
+    /** Fired when the visible band comes within one buffer's width of an edge of what's
+     *  loaded and that edge isn't known to be exhausted. The caller owns fetching — this
+     *  only asks. The window is handed over too so a caller running a sliding window can
+     *  answer a big scrollbar jump (visible band nowhere near the loaded band) by fetching
+     *  around `win.visibleStart` instead of stepping a page at a time towards it. */
+    onNeedMore: (direction: "start" | "end", win: VirtualWindow) => void;
     /** Which edges of `items` still have more behind them. Omitted/undefined reads as "yes,
      *  there might be more" for that edge, since an unknown edge is the common starting state. */
     hasMore?: {
         start?: boolean;
         end?: boolean;
     };
+    /** Absolute index of `items[0]` in the full collection. Non-zero when the caller keeps a
+     *  sliding window and has discarded the rows above. */
+    firstItemIndex?: number;
+    /** Size of the WHOLE collection, when the caller knows it and is holding only a slice.
+     *  Defaults to firstItemIndex + items.length, i.e. "what's loaded is all there is". This
+     *  is what the scrollbar is sized against, so a caller that discards rows as it scrolls
+     *  gets a scroll range that stays still instead of shrinking under the user. */
+    totalCount?: number;
     /** Suppresses onNeedMore while a fetch the caller already started is in flight. Drives the
      *  small pinned spinner at the bottom of the list — rows already mounted stay exactly as
      *  they are, since this only ever means "more is being appended," never "what's on screen
@@ -1084,11 +1200,20 @@ interface VirtualListProps<T> {
  * next onScroll fires, without ever mounting more than a small bounded slice regardless
  * of how many thousand rows `items` holds.
  *
+ * `items` does not have to be the whole collection, or even start at the top of it.
+ * `firstItemIndex`/`totalCount` let the caller hand over a SLIDING WINDOW — say 50 rows
+ * retained out of 4,000, fetching ten at a time in either direction and DISCARDING the
+ * rows that fall out the other side. Every position here is computed from the absolute
+ * index, so discarding rows above the viewport doesn't move the rows below it, and the
+ * scrollbar stays sized to `totalCount` rather than shrinking to whatever is still in
+ * memory. Keeping a window is strictly the caller's business — this component never
+ * decides what to drop, it only refuses to assume that `items[0]` is row zero.
+ *
  * Fully controlled: this holds no item data and no page state, only the scroll position
  * needed to compute the window. The caller owns fetching more rows (onNeedMore) and
  * knowing when an edge is exhausted (hasMore).
  */
-declare function VirtualList<T>({ items, itemHeight, renderItem, onNeedMore, hasMore, loading, refreshing, refreshingLabel, keyOf, height, emptyState, className, style, }: VirtualListProps<T>): React.JSX.Element;
+declare function VirtualList<T>({ items, itemHeight, rowGap, renderItem, onNeedMore, hasMore, firstItemIndex, totalCount, loading, refreshing, refreshingLabel, keyOf, height, emptyState, className, style, }: VirtualListProps<T>): React.JSX.Element;
 
 interface EntityRowAction {
     /** Phosphor icon name, e.g. "plus" */
@@ -1100,11 +1225,54 @@ interface EntityRowAction {
      *  (danger-text). No effect on layout, only color, so a caller can still pass any icon. */
     tone?: "add" | "remove";
 }
-interface EntityRowProps {
+/** Width in px a metric cell takes when it doesn't ask for its own. Wide enough for a
+ *  five-digit grouped number plus its glyph at --overline-size. */
+declare const ENTITY_ROW_METRIC_WIDTH = 74;
+interface EntityRowMetric {
+    /** Stable identity for the column. Falls back to `label`, which is what actually has
+     *  to match between rows for a column to line up, so an id is only needed when two
+     *  columns legitimately share a label. */
+    id?: string;
+    /** What the number means — "students", "ad units". Never rendered as running text:
+     *  it is the metric's accessible name (and its tooltip), so the row stays scannable
+     *  as numbers while a screen reader still hears "1,240 students". */
+    label: string;
+    value: React.ReactNode;
+    /** Phosphor icon name shown before the value, e.g. "student". */
+    icon?: string;
+    /** Fixed cell width in px. Same value on the same column of every row is what makes
+     *  the strip a real aligned column rather than text that happens to sit near text. */
+    width?: number;
+    tone?: "default" | "muted" | "danger";
+}
+/**
+ * Everything about a row that is CONTENT rather than behaviour — what the row says, as
+ * opposed to what it does. Split out from EntityRowProps as its own type on purpose: a
+ * caller that renders the same row twice (TransferList renders every row a second time
+ * as the drag ghost) hands one of these around whole, so a prop added here can't be
+ * silently dropped by the second render site the way individually-spread props were.
+ */
+interface EntityRowContent {
     title: string;
     /** A secondary line — a count, a subtitle, whatever the caller's data has that a raw
-     *  title doesn't. Optional because plenty of rows are fine with just a name. */
+     *  title doesn't. Optional because plenty of rows are fine with just a name. Sits
+     *  inline after the title; for numbers that must line up row-to-row use `metrics`. */
     meta?: React.ReactNode;
+    /** An aligned strip of small numbers below the title — fixed-width cells, so the same
+     *  column lands at the same x on every row. Rendering more than one number through
+     *  `meta` instead would produce a ragged line that happens to contain numbers. */
+    metrics?: EntityRowMetric[];
+    /** A small interactive element pinned to the end of the metric strip — the row's
+     *  score meter, a menu, a flag. Anything focusable belongs in a real `<button>`: the
+     *  row is a drag source, and TransferList's drag arming explicitly skips any
+     *  pointerdown originating inside a button, which is what keeps this clickable. */
+    accessory?: React.ReactNode;
+    /** Whole-row state colour. "danger" repaints fill, border and title (e.g. a school
+     *  with no sellable inventory) — the tone tokens are --erow-danger-*, defined for
+     *  both themes. Default is the ordinary card treatment. */
+    tone?: "default" | "danger";
+}
+interface EntityRowProps extends EntityRowContent {
     action?: EntityRowAction;
     /** Marks the row a drag source: shows the grip icon and a grab cursor, and reports
      *  `onPointerDown` so the caller's own pointer-based drag (see TransferList) can pick
@@ -1115,9 +1283,22 @@ interface EntityRowProps {
     style?: React.CSSProperties;
     className?: string;
 }
+interface EntityRowMetricsProps {
+    metrics: EntityRowMetric[];
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * The aligned number strip, on its own so the SAME columns can be rendered outside a
+ * row — TransferList's per-side footer totals are literally this component with the
+ * same widths, which is the only way a totals line can stay lined up with the rows it
+ * totals without the two places agreeing on magic numbers by hand.
+ */
+declare function EntityRowMetrics({ metrics, className, style }: EntityRowMetricsProps): React.JSX.Element;
 /**
- * EntityRow — a single row for a name plus an optional secondary line and an optional
- * action, meant to be stamped out by the hundreds inside a VirtualList.
+ * EntityRow — a single row for a name plus an optional aligned strip of numbers, an
+ * optional accessory and an optional action, meant to be stamped out by the hundreds
+ * inside a VirtualList.
  *
  * A real card per row, not flat text: its own surface distinct from the list's
  * background (`--surface-2` against the list's `--surface`), a hairline border, a soft
@@ -1127,7 +1308,14 @@ interface EntityRowProps {
  * still left to the caller (it fills 100% of its parent) because VirtualList is what
  * actually fixes row height, and duplicating that number here would be one more place a
  * future change has to remember to update — the card treatment lives entirely in
- * padding/border/shadow, not height.
+ * padding/border/shadow, not height. The border is --erow-border rather than --border
+ * for a measured reason: the card and the panel behind it are 1.06:1 apart in light
+ * mode, so the inter-card gap is only visible if the hairline carries it.
+ *
+ * The row lays out as one or two lines depending on what it's given: title (plus inline
+ * `meta`) always, and a second line holding the metric strip and accessory only when
+ * there is one. That keeps a plain name-only row exactly as tall and as quiet as it
+ * always was while letting a richer row carry three numbers and a meter.
  *
  * The drag/drop split is deliberate: a row only ever needs to say "I am the thing being
  * dragged" (draggable + onPointerDown), never "something was dropped on me" — nothing in
@@ -1144,7 +1332,7 @@ interface EntityRowProps {
  * same move — pointer-only and keyboard users get an equally real affordance, not a
  * degraded fallback.
  */
-declare function EntityRow({ title, meta, action, draggable, onPointerDown, style, className }: EntityRowProps): React.JSX.Element;
+declare function EntityRow({ title, meta, metrics, accessory, tone, action, draggable, onPointerDown, style, className, }: EntityRowProps): React.JSX.Element;
 
 type TransferListSide = "left" | "right";
 interface TransferListSideProps<T> {
@@ -1166,14 +1354,28 @@ interface TransferListSideProps<T> {
     } | null;
     sortFields: SortMenuField[];
     onSort: (key: string, dir: "asc" | "desc") => void;
-    onNeedMore: (direction: "start" | "end") => void;
+    onNeedMore: (direction: "start" | "end", win: VirtualWindow) => void;
     hasMore?: {
         start?: boolean;
         end?: boolean;
     };
+    /** Absolute index of `items[0]` in this side's full collection, and the size of that
+     *  collection — threaded straight through to this side's VirtualList so each side can
+     *  independently run a sliding window. See VirtualList's own docs. */
+    firstItemIndex?: number;
+    totalCount?: number;
     /** Heading text for this side. Fully caller-supplied — this component has no opinion
-     *  about what the two sides represent. */
+     *  about what the two sides represent. Stays a plain string because it is also woven
+     *  into the search field's and the move action's accessible names; anything richer
+     *  than a name belongs in `header`. */
     label?: string;
+    /** A slot above the search row, under the label. */
+    header?: React.ReactNode;
+    /** A slot below the list — where a running totals line for this side goes. A real slot
+     *  rather than more `label`, because totals are structured content (typically an
+     *  EntityRowMetrics strip using the same widths as the rows, so the columns line up
+     *  with the numbers they total) and `label` is a string that gets concatenated. */
+    footer?: React.ReactNode;
     /** Copy shown in the full-panel drop overlay while a drag is over this side. Falls
      *  back to a generic "Drop here" (plus `label`, if set) when omitted — set this for
      *  exact per-side wording (e.g. "Drop to add to audience" / "Drop to remove from
@@ -1185,15 +1387,28 @@ interface TransferListProps<T> {
     left: TransferListSideProps<T>;
     right: TransferListSideProps<T>;
     keyOf: (item: T) => string | number;
-    renderLabel: (item: T) => string;
-    renderMeta?: (item: T) => React.ReactNode;
+    /** Everything a row SAYS, as one object — title, meta, the aligned metric strip, the
+     *  accessory, the row tone. One render prop returning one EntityRowContent rather than
+     *  a render prop per field, because a dragged row is rendered a SECOND time as the
+     *  ghost that follows the cursor: with per-field props that second call has to
+     *  remember to pass each of them, and the version of this component that did exactly
+     *  that quietly dropped every field but title and meta off the dragged card. Handing
+     *  the same object to both render sites makes that class of bug unrepresentable. */
+    renderRow: (item: T) => EntityRowContent;
     /** Fired by both a drag-drop and the equivalent +/- click. The caller owns actually
      *  moving the item between whatever backing lists it maintains — this component never
      *  mutates `left.items`/`right.items` itself. */
     onMove: (item: T, from: TransferListSide, to: TransferListSide) => void;
-    /** Row height fed straight through to each side's VirtualList. Default (44) matches
-     *  the kit's --control-h-md, since that's the height EntityRow is tuned to look right at. */
+    /** Row height fed straight through to each side's VirtualList. Default (64) fits the
+     *  two-line card an EntityRow becomes once it carries a metric strip and an accessory:
+     *  a 56px card (title line + strip line, 10px of vertical padding) plus the 8px gap.
+     *  A list of bare title-only rows should pass 44 (the kit's --control-h-md, which is
+     *  what EntityRow's single-line form is tuned to) with a matching smaller rowGap. */
     itemHeight?: number;
+    /** px of each row slot left empty, which is what draws the gap between two cards.
+     *  Default 8 — see the --erow-border token note for why a card on this kit's surfaces
+     *  needs both a real gap and a real hairline before the separation is visible. */
+    rowGap?: number;
     /** Viewport height fed straight through to each side's VirtualList. */
     listHeight?: number;
     className?: string;
@@ -1229,12 +1444,19 @@ interface TransferListProps<T> {
  * it is the same onMove call a drop makes, exposed as a first-class equivalent, because
  * drag-and-drop alone would silently exclude anyone not using a mouse.
  *
+ * Each side owns a `header` and a `footer` slot in addition to its `label`. `label` stays
+ * a plain string because it is also woven into that side's search field and move-action
+ * accessible names and gets a count concatenated onto it; the slots are where real
+ * content goes — a running totals line in the footer, rendered with EntityRowMetrics at
+ * the same column widths the rows use, so the totals sit under the numbers they total.
+ *
  * Fully controlled and stateless about the actual item sets: `left`/`right` are handed in
  * whole, this never copies or reorders them, and the only state kept locally is which row
  * is mid-drag and which side a drag is currently over — pure interaction feedback, thrown
- * away the moment the drag ends.
+ * away the moment the drag ends. Each side may independently be a sliding window over a
+ * much larger collection (`firstItemIndex`/`totalCount`, threaded to its VirtualList).
  */
-declare function TransferList<T>({ left, right, keyOf, renderLabel, renderMeta, onMove, itemHeight, listHeight, className, }: TransferListProps<T>): React.JSX.Element;
+declare function TransferList<T>({ left, right, keyOf, renderRow, onMove, itemHeight, rowGap, listHeight, className, }: TransferListProps<T>): React.JSX.Element;
 
 /**
  * Multi-select control with a 44px comfortable hit area.
@@ -2283,6 +2505,120 @@ interface SurroundSoundProps {
 }
 declare function SurroundSound({ present, bonusPct, bonusMax, missedCost, className }: SurroundSoundProps): React.JSX.Element;
 
+type ImportanceLevelId = "nudge" | "lean" | "priority" | "driver" | "dealbreaker";
+interface ImportanceLevel {
+    id: ImportanceLevelId;
+    /** 1-5, ascending. This is the number the --imp-N-* tokens are keyed by. */
+    rank: 1 | 2 | 3 | 4 | 5;
+    /** How the level is named in the UI. */
+    label: string;
+    /** Phosphor icon name. */
+    icon: string;
+    /** One line saying what choosing this level actually does to a plan. */
+    description: string;
+}
+/**
+ * How much a single criterion is allowed to matter, as five ordered steps. Ordered
+ * ascending, and index-stable: the position in this array IS the `rank`, which is what
+ * the --imp-N-* colour tokens are keyed by, so reordering it would silently re-colour
+ * every criterion in the product.
+ *
+ * The ramp runs slate → blue → indigo → amber → red, i.e. from "barely registers" to
+ * "nothing else matters". It deliberately crosses from the neutral/interaction end of
+ * the palette into the warning end, because that IS the semantic gradient: a
+ * Deal-breaker isn't a stronger preference, it's a veto, and it should look like one.
+ */
+declare const IMPORTANCE_LEVELS: ImportanceLevel[];
+/** The level record for an id, falling back to the lowest step for an unknown one — an
+ *  unrecognised level should read as "barely matters", never throw in a list row. */
+declare function importanceLevel(id: ImportanceLevelId | string): ImportanceLevel;
+interface ImportanceTokens {
+    /** Background wash for a criterion card at this level. */
+    fill: string;
+    /** Border for that card. */
+    edge: string;
+    /** AA-safe text colour ON `fill`. */
+    text: string;
+    /** The solid — meter segments, glyphs, dots. Clears 3:1 on the meter rail. */
+    mark: string;
+}
+/**
+ * The four `var(--imp-N-*)` references for a level, as a plain object, so a criterion
+ * card elsewhere in a consuming app tints itself from exactly the same tokens the meter
+ * segments are drawn in rather than from a second hand-copied list of hexes. Returns the
+ * var() references, not resolved colours — the whole point is that the theme resolves
+ * them, and every one of these is defined for both light and dark ground.
+ */
+declare function importanceTokens(id: ImportanceLevelId | string): ImportanceTokens;
+interface ImportanceTagProps {
+    level: ImportanceLevelId | string;
+    /** Show the level's name next to its glyph. Off for a bare glyph in tight spots. */
+    showLabel?: boolean;
+    size?: "sm" | "md";
+    className?: string;
+}
+/**
+ * The level itself, as a small tinted tag — glyph plus name in that level's own fill,
+ * edge and text tokens. Never colour alone: the name and the icon both carry the level,
+ * so the five steps are still distinguishable without colour vision.
+ */
+declare function ImportanceTag({ level, showLabel, size, className }: ImportanceTagProps): React.JSX.Element;
+
+interface PreferenceCriterion {
+    id: string;
+    /** What the planner asked for — "Within 50 miles", "Enrollment over 10,000". */
+    label: string;
+    importance: ImportanceLevelId | string;
+    /** The most this criterion could contribute to a 100-point score, i.e. what it is
+     *  worth given its importance relative to the other criteria. */
+    weight: number;
+    /** What it actually contributed for this option, 0..weight. A partially-satisfied
+     *  criterion is allowed — this is not a pass/fail flag. */
+    earned: number;
+    /** Optional plain-language reason shown under the criterion in the breakdown, e.g.
+     *  "31 miles" or "no outdoor inventory". */
+    note?: React.ReactNode;
+}
+/** The score a set of criteria adds up to, rounded to a whole 0-100. Exported because a
+ *  consumer usually needs the same number for sorting the list as for drawing the meter,
+ *  and two implementations of that would drift. */
+declare function preferenceScore(criteria: PreferenceCriterion[]): number;
+/** One meter segment per criterion, each sized by what that criterion actually earned
+ *  (as a share of 100) and coloured by its importance level's `mark` token. */
+declare function preferenceSegments(criteria: PreferenceCriterion[]): MeterSegmentInput[];
+interface PreferenceMeterProps {
+    criteria: PreferenceCriterion[];
+    /** Overrides the score derived from `criteria`. Pass it when the score is computed
+     *  server-side and the criteria are only the explanation of it. */
+    score?: number;
+    /** Accessible name. Defaults to "Preference score". */
+    label?: string;
+    width?: number;
+    height?: number;
+    showScore?: boolean;
+    placement?: Placement;
+    /** Heading shown above the breakdown list. */
+    breakdownTitle?: string;
+    className?: string;
+}
+/**
+ * PreferenceMeter — how well one option matches the planner's stated priorities, drawn
+ * as one segment per criterion coloured by that criterion's importance.
+ *
+ * The encoding is the point, and it is not "how high did this score". A plain 0-100 bar
+ * says a school scored 72; this says WHICH of the planner's priorities it satisfies — a
+ * bar that is mostly red-and-amber is meeting the deal-breakers and drivers, a bar of
+ * the same length that is mostly slate is scraping the same number out of things the
+ * planner said barely matter. Two schools with identical scores are visibly different
+ * propositions, at a glance, in a list row.
+ *
+ * Segment width is what the criterion EARNED, not what it was worth, so the unfilled
+ * remainder of the rail is exactly what the option is failing to deliver. Clicking opens
+ * the breakdown: every criterion, its level, what it earned out of its weight, and the
+ * caller's own note explaining why.
+ */
+declare function PreferenceMeter({ criteria, score, label, width, height, showScore, placement, breakdownTitle, className, }: PreferenceMeterProps): React.JSX.Element;
+
 /**
  * Chat state machine. Framework-shaped as a React hook, but the rules it encodes
  * are the portable part: thread resolution, serial sending, escalation polling,
@@ -3109,4 +3445,4 @@ interface VersionStore<TState, TDiff = unknown> {
 }
 declare function createVersionStore<TState, TDiff = unknown>(initialState: TState, options?: CreateVersionStoreOptions<TState, TDiff>): VersionStore<TState, TDiff>;
 
-export { AccountMenu, type AccountMenuLink, type AccountMenuProps, AgentChatPanel, type AgentChatPanelProps, ApiSpecBrowser, type ApiSpecBrowserProps, type Attachment, Avatar, type AvatarProps, AvatarStack, type AvatarStackProps, Badge, type BadgeProps, BudgetReallocator, type BudgetReallocatorProps, Button, type ButtonProps, CHANNELS, CHANNEL_WEIGHTS, CHAT_UNAVAILABLE, Calendar, type CalendarProps, Card, type CardProps, CardRow, type CardRowProps, ChannelContribution, type ChannelContributionChannel, type ChannelContributionProps, ChannelMeta, type ChannelMetaRecord, ChannelTag, type ChannelTagProps, ChannelWeightOf, type ChatAdapter, ChatComposer, type ChatComposerProps, type ChatEngine, type ChatEngineOptions, ChatKit, type ChatMessage, type ChatRenderContext, ChatSessionBar, type ChatSessionBarProps, ChatTranscript, type ChatTranscriptProps, ChatTurn, type ChatTurnProps, Checkbox, type CheckboxProps, type Citation, Citations, type CitationsProps, Clamp, type ClampProps, ClockFace, type ClockFaceProps, CodeBlock, type CodeBlockProps, Collapsible, type CollapsibleProps, ComingSoon, type ComingSoonProps, type ContextUsage, type CreateVersionStoreOptions, CsiBadge, type CsiBadgeProps, CsiHero, type CsiHeroProps, CsiMeter, type CsiMeterProps, DataTable, type DataTableColumn, type DataTableProps, DatePicker, type DatePickerProps, type DeviceSession, DiffBlock, type DiffBlockProps, Drawer, type DrawerProps, Dropzone, DropzoneKit, type DropzoneProps, type EditorTrigger, EmptyState, type EmptyStateProps, type EndpointSpec, EntityRow, type EntityRowAction, type EntityRowProps, FeatureGate, type FeatureGateProps, type FeatureStatus, FileChip, type FileChipProps, FileGrid, type FileGridProps, FileKit, FilePickButton, type FilePickButtonProps, type FileRejection, FileStrip, type FileStripProps, FileTile, type FileTileProps, type FileUploadHandler, FilterBar, type FilterBarProps, type FilterField, type FilterFieldOption, type FilterFieldSelect, type FilterFieldText, Flag$1 as Flag, type FlagExplanation, type FlagProps, FlytedeskBrand, type FlytedeskBrandProps, FlytedeskMark, type FlytedeskMarkProps, FormatEta, Gate, type GateProps, IconButton, type IconButtonProps, Input, type InputProps, type JobStatus, Json, KeyHint, type KeyHintProps, type ListEnvelope, LoadingRegion, type LoadingRegionProps, Markdown, MarkdownEditor, type MarkdownEditorHandle, type MarkdownEditorProps, MarkdownInline, type MarkdownProps, type MentionSource, Menu, MenuButton, type MenuButtonProps, type MenuItem, type MenuProps, MessageBody, type MessageBodyProps, type MessageGroup, Meter, type MeterProps, type MeterSegment, type MeterSegmentInput, MixGap, type MixGapProps, type MixGapRow, MockJobKit, type MockJobStatus, Modal, type ModalProps, ModeSwitch, type ModeSwitchProps, type Model, ModelControls, type ModelControlsProps, NumberInput, type NumberInputProps, type Packet, PacketCard, type PacketCardProps, type PacketSchema, type Pager, Pagination, type PaginationProps, PermissionDenied, type PermissionDeniedProps, type PermissionGroup, PermissionHint, type PermissionItem, type Placement, type PollOptions, Popover, type PopoverProps, ProfilePage, type ProfilePageProps, ProgressBar, type ProgressBarProps, QueryKit, type QueuedTurn, QuotaRow, type QuotaRowProps, Radio, type RadioProps, RangeSlider, type RangeSliderProps, RelativeTime, type RelativeTimeProps, type RoadmapItem, type RoadmapResult, RoadmapTimeline, type RoadmapTimelineProps, type Role, RunActions, type RunActionsProps, type RunConfig, RuntimeKit, type RuntimeSummary, SaturationDistribution, type SaturationDistributionCampus, type SaturationDistributionProps, SearchField, type SearchFieldProps, SegmentedControl, type SegmentedControlProps, SegmentedMeter, type SegmentedMeterProps, Select, type SelectOption, type SelectProps, type SendMessageResult, type ServerTable, type Session, type Flag as SessionFlag, SessionKit, type SessionStats, SidebarNav, type SidebarNavItem, type SidebarNavProps, Skeleton, type SkeletonProps, SkeletonText, type SkeletonTextProps, type SlashCommand, Slider, type SliderProps, SortMenu, type SortMenuField, type SortMenuProps, type SpecModule, Spinner, type SpinnerProps, StatTile, type StatTileProps, type Step, StepList, type StepListProps, type StreamHandlers, type Suggestion, SurroundSound, type SurroundSoundProps, Switch, type SwitchProps, type TableQuery, Tabs, type TabsProps, Tag, type TagProps, TestModeBar, type TestModeBarProps, Textarea, type TextareaProps, ThinkingBlock, type ThinkingBlockProps, type ThreadSummary, TimePicker, type TimePickerProps, Toast, type ToastProps, Tooltip, type TooltipProps, Topbar, type TopbarProps, TranscriptKit, TransferList, type TransferListProps, type TransferListSide, type TransferListSideProps, type UsageLimit, UseFeatureStatus, UseRuntimeMode, type UseServerTableOptions, type User, VIRTUAL_LIST_BUFFER_ROWS, type VersionRecord, type VersionStore, VirtualList, type VirtualListProps, type VirtualWindow, type VoiceHandler, acceptMatches, anyOfFilter, channelWeightOf, computeNeedMore, computeVirtualWindow, createVersionStore, eqFilter, extensionOf, extractClipboardFiles, filterFiles, formatAbsolute, formatBytes, formatClock, formatDuration, formatEta, formatRelative, groupMessages, hasModifier, iconForMime, isImage, isSystemMessage, jobBucket, languageLabel, markdownToText, meterFormats, modifierLabel, pastedTextName, rangeFilter, revokeAttachment, toAttachment, tokenize, useChatEngine, useFeatureStatus, usePopoverPosition, useRuntimeMode, useServerTable, useStagedFiles, visibleMessages };
+export { AccountMenu, type AccountMenuLink, type AccountMenuProps, AgentChatPanel, type AgentChatPanelProps, ApiSpecBrowser, type ApiSpecBrowserProps, type Attachment, Avatar, type AvatarProps, AvatarStack, type AvatarStackProps, Badge, type BadgeProps, BudgetReallocator, type BudgetReallocatorProps, Button, type ButtonProps, CHANNELS, CHANNEL_WEIGHTS, CHAT_UNAVAILABLE, Calendar, type CalendarProps, Card, type CardProps, CardRow, type CardRowProps, ChannelContribution, type ChannelContributionChannel, type ChannelContributionProps, ChannelMeta, type ChannelMetaRecord, ChannelTag, type ChannelTagProps, ChannelWeightOf, type ChatAdapter, ChatComposer, type ChatComposerProps, type ChatEngine, type ChatEngineOptions, ChatKit, type ChatMessage, type ChatRenderContext, ChatSessionBar, type ChatSessionBarProps, ChatTranscript, type ChatTranscriptProps, ChatTurn, type ChatTurnProps, Checkbox, type CheckboxProps, type Citation, Citations, type CitationsProps, Clamp, type ClampProps, ClockFace, type ClockFaceProps, CodeBlock, type CodeBlockProps, Collapsible, type CollapsibleProps, ComingSoon, type ComingSoonProps, type ContextUsage, type CreateVersionStoreOptions, CsiBadge, type CsiBadgeProps, CsiHero, type CsiHeroProps, CsiMeter, type CsiMeterProps, DataTable, type DataTableColumn, type DataTableProps, DatePicker, type DatePickerProps, type DeviceSession, DiffBlock, type DiffBlockProps, Drawer, type DrawerProps, Dropzone, DropzoneKit, type DropzoneProps, ENTITY_ROW_METRIC_WIDTH, type EditorTrigger, EmptyState, type EmptyStateProps, type EndpointSpec, EntityRow, type EntityRowAction, type EntityRowContent, type EntityRowMetric, EntityRowMetrics, type EntityRowMetricsProps, type EntityRowProps, FeatureGate, type FeatureGateProps, type FeatureStatus, FileChip, type FileChipProps, FileGrid, type FileGridProps, FileKit, FilePickButton, type FilePickButtonProps, type FileRejection, FileStrip, type FileStripProps, FileTile, type FileTileProps, type FileUploadHandler, FilterBar, type FilterBarProps, type FilterField, type FilterFieldOption, type FilterFieldSelect, type FilterFieldText, Flag$1 as Flag, type FlagExplanation, type FlagProps, FlytedeskBrand, type FlytedeskBrandProps, FlytedeskMark, type FlytedeskMarkProps, FormatEta, Gate, type GateProps, IMPORTANCE_LEVELS, IconButton, type IconButtonProps, type ImportanceLevel, type ImportanceLevelId, ImportanceTag, type ImportanceTagProps, type ImportanceTokens, Input, type InputProps, type JobStatus, Json, KeyHint, type KeyHintProps, type ListEnvelope, LoadingRegion, type LoadingRegionProps, Markdown, MarkdownEditor, type MarkdownEditorHandle, type MarkdownEditorProps, MarkdownInline, type MarkdownProps, type MentionSource, Menu, MenuButton, type MenuButtonProps, type MenuItem, type MenuProps, MessageBody, type MessageBodyProps, type MessageGroup, Meter, type MeterProps, type MeterSegment, type MeterSegmentInput, MixGap, type MixGapProps, type MixGapRow, MockJobKit, type MockJobStatus, Modal, type ModalProps, ModeSwitch, type ModeSwitchProps, type Model, ModelControls, type ModelControlsProps, NumberInput, type NumberInputProps, type Packet, PacketCard, type PacketCardProps, type PacketSchema, type Pager, Pagination, type PaginationProps, PermissionDenied, type PermissionDeniedProps, type PermissionGroup, PermissionHint, type PermissionItem, type Placement, type PollOptions, Popover, type PopoverProps, type PreferenceCriterion, PreferenceMeter, type PreferenceMeterProps, ProfilePage, type ProfilePageProps, ProgressBar, type ProgressBarProps, QueryKit, type QueuedTurn, QuotaRow, type QuotaRowProps, Radio, type RadioProps, RangeSlider, type RangeSliderProps, RelativeTime, type RelativeTimeProps, type RoadmapItem, type RoadmapResult, RoadmapTimeline, type RoadmapTimelineProps, type Role, RunActions, type RunActionsProps, type RunConfig, RuntimeKit, type RuntimeSummary, SaturationDistribution, type SaturationDistributionCampus, type SaturationDistributionProps, ScoreMeter, type ScoreMeterProps, SearchField, type SearchFieldProps, SegmentedControl, type SegmentedControlProps, SegmentedMeter, type SegmentedMeterProps, Select, type SelectOption, type SelectProps, type SendMessageResult, type ServerTable, type Session, type Flag as SessionFlag, SessionKit, type SessionStats, SidebarNav, type SidebarNavItem, type SidebarNavProps, Skeleton, type SkeletonProps, SkeletonText, type SkeletonTextProps, type SlashCommand, Slider, type SliderProps, SortMenu, type SortMenuField, type SortMenuProps, type SpecModule, Spinner, type SpinnerProps, StatTile, type StatTileProps, type Step, StepList, type StepListProps, type StreamHandlers, type Suggestion, SurroundSound, type SurroundSoundProps, Switch, type SwitchProps, type TableQuery, Tabs, type TabsProps, Tag, type TagProps, TestModeBar, type TestModeBarProps, Textarea, type TextareaProps, ThinkingBlock, type ThinkingBlockProps, type ThreadSummary, TimePicker, type TimePickerProps, Toast, type ToastProps, Tooltip, type TooltipProps, Topbar, type TopbarProps, TranscriptKit, TransferList, type TransferListProps, type TransferListSide, type TransferListSideProps, type UsageLimit, UseFeatureStatus, UseRuntimeMode, type UseServerTableOptions, type User, VIRTUAL_LIST_BUFFER_ROWS, VIRTUAL_LIST_ROW_GAP, type VersionRecord, type VersionStore, VirtualList, type VirtualListProps, type VirtualLoadedBand, type VirtualWindow, type VoiceHandler, acceptMatches, anyOfFilter, channelWeightOf, computeNeedMore, computeVirtualWindow, createVersionStore, eqFilter, extensionOf, extractClipboardFiles, filterFiles, formatAbsolute, formatBytes, formatClock, formatDuration, formatEta, formatRelative, groupMessages, hasModifier, iconForMime, importanceLevel, importanceTokens, isImage, isSystemMessage, jobBucket, languageLabel, markdownToText, meterFormats, modifierLabel, pastedTextName, preferenceScore, preferenceSegments, rangeFilter, revokeAttachment, toAttachment, tokenize, useChatEngine, useFeatureStatus, usePopoverPosition, useRuntimeMode, useServerTable, useStagedFiles, visibleMessages };