@flytedan/flytebot-design-system 0.7.1 → 0.8.0

package/dist/index.d.cts

@@ -924,6 +924,12 @@ interface SortMenuProps extends React.HTMLAttributes<HTMLSpanElement> {
     onSort?: (key: string, dir: "asc" | "desc") => void;
     /** Which edge the popover aligns to. Default "right". */
     align?: "left" | "right";
+    /** Trigger button height, same scale as every other control in the kit (Button,
+     *  Input). Default "md" — matches Input/SearchField's own default height, since
+     *  this is most often placed directly alongside a SearchField in one header row
+     *  (see TransferList) and the two need to line up. Pass "sm" for a denser,
+     *  standalone placement. */
+    size?: "sm" | "md";
     className?: string;
 }
 /**
@@ -941,7 +947,7 @@ interface SortMenuProps extends React.HTMLAttributes<HTMLSpanElement> {
  * Purely presentational: reports intent through onSort(key, dir) and never holds sort
  * state, so it stays honest against a real endpoint.
  */
-declare function SortMenu({ fields, sort, onSort, align, className, ...rest }: SortMenuProps): React.JSX.Element;
+declare function SortMenu({ fields, sort, onSort, align, size, className, ...rest }: SortMenuProps): React.JSX.Element;
 
 interface Step {
     id: string;
@@ -1033,8 +1039,19 @@ interface VirtualListProps<T> {
         start?: boolean;
         end?: boolean;
     };
-    /** Suppresses onNeedMore while a fetch the caller already started is in flight. */
+    /** 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
+     *  might be stale." For the append-vs-replace distinction, see `refreshing` below. */
     loading?: boolean;
+    /** True while the caller is replacing the WHOLE result set (a search or sort change), as
+     *  opposed to `loading` appending more onto the end. `items` is expected to still be the
+     *  PREVIOUS result set while this is true — this renders it underneath a full-panel scrim
+     *  instead of clearing to empty, so a search/sort edit never blanks the list while the new
+     *  page is in flight. Swap `items` to the new rows once they land and this back to false. */
+    refreshing?: boolean;
+    /** Copy shown in the `refreshing` overlay's centered card, next to its spinner. */
+    refreshingLabel?: string;
     keyOf: (item: T) => string | number;
     /** Viewport height in px. Default (400) is ten rows at the kit's --control-h-md (44px). */
     height?: number;
@@ -1071,7 +1088,7 @@ interface VirtualListProps<T> {
  * 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, keyOf, height, emptyState, className, style, }: VirtualListProps<T>): React.JSX.Element;
+declare function VirtualList<T>({ items, itemHeight, renderItem, onNeedMore, hasMore, loading, refreshing, refreshingLabel, keyOf, height, emptyState, className, style, }: VirtualListProps<T>): React.JSX.Element;
 
 interface EntityRowAction {
     /** Phosphor icon name, e.g. "plus" */
@@ -1089,35 +1106,45 @@ interface EntityRowProps {
      *  title doesn't. Optional because plenty of rows are fine with just a name. */
     meta?: React.ReactNode;
     action?: EntityRowAction;
-    /** Marks the row a native HTML5 drag source. Wiring onDragOver/onDrop is the drop
-     *  target's job (a list container, not each row) — see the file doc comment. */
+    /** 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
+     *  the gesture up from there. Deliberately NOT the native HTML `draggable` attribute
+     *  (see the file doc comment for why) — this row never starts a native browser drag. */
     draggable?: boolean;
-    onDragStart?: (e: React.DragEvent<HTMLDivElement>) => void;
-    onDragEnd?: (e: React.DragEvent<HTMLDivElement>) => void;
+    onPointerDown?: (e: React.PointerEvent<HTMLDivElement>) => void;
     style?: React.CSSProperties;
     className?: string;
 }
 /**
- * EntityRow — a single compact 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 secondary line and an optional
+ * action, meant to be stamped out by the hundreds inside a VirtualList.
  *
- * Deliberately thin, not a card: no border, no shadow, no internal padding beyond enough
- * to keep text off the edges, so it reads as one line in a dense list rather than a tile.
- * Height is left to the caller (it fills 100% of its parent) because VirtualList is what
+ * 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
+ * rest-state shadow that lifts on hover — the same `--r-md`/`--e-1`/`--e-2` elevation
+ * vocabulary Card itself uses (see styles/components.css's ".fd-erow" rules), just at
+ * the tighter radius a compact row reads better at than Card's own `--r-lg`. Height is
+ * 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.
+ * future change has to remember to update — the card treatment lives entirely in
+ * padding/border/shadow, not height.
  *
  * The drag/drop split is deliberate: a row only ever needs to say "I am the thing being
- * dragged" (draggable + onDragStart/onDragEnd), never "something was dropped on me" —
- * nothing in this kit drops one row onto another to reorder it, only a row onto a list to
- * move it there. Putting onDragOver/onDrop on every row would mean wiring the same drop
- * logic N times over instead of once on the list container that actually owns it (see
- * TransferList), so this only exposes the source half of the native HTML5 DnD contract.
+ * dragged" (draggable + onPointerDown), never "something was dropped on me" — nothing in
+ * this kit drops one row onto another to reorder it, only a row onto a list to move it
+ * there. Putting the drop handling on every row would mean wiring the same drop logic N
+ * times over instead of once on the list container that actually owns it (see
+ * TransferList's own doc comment for why it drives a pointer-based custom drag rather than
+ * native HTML5 DnD — in short, a native drag image is a static snapshot, not a live
+ * element, so it can't sustain a persistent tilt that follows the cursor), so this only
+ * exposes the source half of the contract: `onPointerDown` hands the gesture off to
+ * whatever the caller wants to do with it (TransferList starts tracking a drag once the
+ * pointer has moved past a small threshold, so a plain click still reads as a click).
  * The action button exists precisely so drag-and-drop is never the only way to do the
  * same move — pointer-only and keyboard users get an equally real affordance, not a
  * degraded fallback.
  */
-declare function EntityRow({ title, meta, action, draggable, onDragStart, onDragEnd, style, className }: EntityRowProps): React.JSX.Element;
+declare function EntityRow({ title, meta, action, draggable, onPointerDown, style, className }: EntityRowProps): React.JSX.Element;
 
 type TransferListSide = "left" | "right";
 interface TransferListSideProps<T> {
@@ -1126,6 +1153,11 @@ interface TransferListSideProps<T> {
     /** Total matching count on the server, if known — shown next to the label. */
     total?: number;
     loading?: boolean;
+    /** True while this side's WHOLE result set is being replaced (a search or sort
+     *  change), not merely appended to. `items` should still be the previous result set
+     *  while this is true — see VirtualList's own `refreshing` prop, which this threads
+     *  straight through. */
+    refreshing?: boolean;
     search: string;
     onSearchChange: (value: string) => void;
     sort?: {
@@ -1142,6 +1174,12 @@ interface TransferListSideProps<T> {
     /** Heading text for this side. Fully caller-supplied — this component has no opinion
      *  about what the two sides represent. */
     label?: string;
+    /** 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
+     *  audience"), since that phrasing is about what a drop here DOES, which only the
+     *  caller's domain actually knows. */
+    dropLabel?: string;
 }
 interface TransferListProps<T> {
     left: TransferListSideProps<T>;
@@ -1169,19 +1207,23 @@ interface TransferListProps<T> {
  * lists is specific to that use, and baking in "available"/"selected" (or worse, this
  * kit's actual first consumer's own vocabulary) would make every *other* two-list picker
  * this kit will ever be asked for a second component instead of a second set of props. A
- * caller wanting domain words passes them through `label`.
+ * caller wanting domain words passes them through `label`/`dropLabel`.
  *
- * Native HTML5 drag-and-drop, not a library: this kit ships zero runtime dependencies on
- * purpose, and moving one row between two lists is exactly the case the platform's own
- * draggable/dragstart/dragover/drop already cover with no gap to fill — sortable-within-
- * a-list (which does need pointer math and placeholder gaps) is a different, harder
- * problem this component doesn't attempt. Each row is the drag source (via EntityRow's
- * draggable prop); each *side* is the drop target — one onDragOver/onDrop pair per side,
- * not per row, since dropping only ever means "move into this list," never "onto this
- * particular other row." dataTransfer carries the dragged key mainly so a real
- * OS-level drag has real payload (Firefox refuses a drag with no data set at all); which
- * item is actually moved is tracked in local `dragging` state, because dataTransfer's own
- * payload can't hold a reference to `item: T` — only the string the caller's keyOf gives it.
+ * A pointer-based custom drag, not native HTML5 DnD, and not a library: this kit ships
+ * zero runtime dependencies on purpose, and a pointer-events implementation (pointerdown/
+ * pointermove/pointerup driving a portaled ghost element) is still zero-dependency — just
+ * more code than `draggable`. It replaced an earlier native-HTML5-DnD version once the
+ * spec called for a real "card lifts out of the list and tilts, following the cursor"
+ * feel: a native drag image (`dataTransfer.setDragImage`) is a static snapshot taken once
+ * at dragstart, not a live element, so it can't sustain a persistent rotation that tracks
+ * the pointer for the duration of the drag — only owning the pointer events ourselves can.
+ * Each row's pointerdown (via EntityRow's `onPointerDown`) arms a potential drag; nothing
+ * visually happens until the pointer actually moves past `DRAG_THRESHOLD_PX`, so a plain
+ * click (on the row, or on its +/- action button) is never mistaken for one. Once armed,
+ * window-level pointermove/pointerup/pointercancel listeners (not per-row ones, since the
+ * row being dragged gets replaced by a placeholder mid-drag) track the gesture to
+ * completion; which side the pointer is currently over is decided by hit-testing each
+ * side's own bounding rect against the pointer position, not by any per-row target.
  *
  * The +/- action on every row is not a fallback bolted on for accessibility box-ticking:
  * it is the same onMove call a drop makes, exposed as a first-class equivalent, because

package/dist/index.d.ts

@@ -924,6 +924,12 @@ interface SortMenuProps extends React.HTMLAttributes<HTMLSpanElement> {
     onSort?: (key: string, dir: "asc" | "desc") => void;
     /** Which edge the popover aligns to. Default "right". */
     align?: "left" | "right";
+    /** Trigger button height, same scale as every other control in the kit (Button,
+     *  Input). Default "md" — matches Input/SearchField's own default height, since
+     *  this is most often placed directly alongside a SearchField in one header row
+     *  (see TransferList) and the two need to line up. Pass "sm" for a denser,
+     *  standalone placement. */
+    size?: "sm" | "md";
     className?: string;
 }
 /**
@@ -941,7 +947,7 @@ interface SortMenuProps extends React.HTMLAttributes<HTMLSpanElement> {
  * Purely presentational: reports intent through onSort(key, dir) and never holds sort
  * state, so it stays honest against a real endpoint.
  */
-declare function SortMenu({ fields, sort, onSort, align, className, ...rest }: SortMenuProps): React.JSX.Element;
+declare function SortMenu({ fields, sort, onSort, align, size, className, ...rest }: SortMenuProps): React.JSX.Element;
 
 interface Step {
     id: string;
@@ -1033,8 +1039,19 @@ interface VirtualListProps<T> {
         start?: boolean;
         end?: boolean;
     };
-    /** Suppresses onNeedMore while a fetch the caller already started is in flight. */
+    /** 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
+     *  might be stale." For the append-vs-replace distinction, see `refreshing` below. */
     loading?: boolean;
+    /** True while the caller is replacing the WHOLE result set (a search or sort change), as
+     *  opposed to `loading` appending more onto the end. `items` is expected to still be the
+     *  PREVIOUS result set while this is true — this renders it underneath a full-panel scrim
+     *  instead of clearing to empty, so a search/sort edit never blanks the list while the new
+     *  page is in flight. Swap `items` to the new rows once they land and this back to false. */
+    refreshing?: boolean;
+    /** Copy shown in the `refreshing` overlay's centered card, next to its spinner. */
+    refreshingLabel?: string;
     keyOf: (item: T) => string | number;
     /** Viewport height in px. Default (400) is ten rows at the kit's --control-h-md (44px). */
     height?: number;
@@ -1071,7 +1088,7 @@ interface VirtualListProps<T> {
  * 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, keyOf, height, emptyState, className, style, }: VirtualListProps<T>): React.JSX.Element;
+declare function VirtualList<T>({ items, itemHeight, renderItem, onNeedMore, hasMore, loading, refreshing, refreshingLabel, keyOf, height, emptyState, className, style, }: VirtualListProps<T>): React.JSX.Element;
 
 interface EntityRowAction {
     /** Phosphor icon name, e.g. "plus" */
@@ -1089,35 +1106,45 @@ interface EntityRowProps {
      *  title doesn't. Optional because plenty of rows are fine with just a name. */
     meta?: React.ReactNode;
     action?: EntityRowAction;
-    /** Marks the row a native HTML5 drag source. Wiring onDragOver/onDrop is the drop
-     *  target's job (a list container, not each row) — see the file doc comment. */
+    /** 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
+     *  the gesture up from there. Deliberately NOT the native HTML `draggable` attribute
+     *  (see the file doc comment for why) — this row never starts a native browser drag. */
     draggable?: boolean;
-    onDragStart?: (e: React.DragEvent<HTMLDivElement>) => void;
-    onDragEnd?: (e: React.DragEvent<HTMLDivElement>) => void;
+    onPointerDown?: (e: React.PointerEvent<HTMLDivElement>) => void;
     style?: React.CSSProperties;
     className?: string;
 }
 /**
- * EntityRow — a single compact 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 secondary line and an optional
+ * action, meant to be stamped out by the hundreds inside a VirtualList.
  *
- * Deliberately thin, not a card: no border, no shadow, no internal padding beyond enough
- * to keep text off the edges, so it reads as one line in a dense list rather than a tile.
- * Height is left to the caller (it fills 100% of its parent) because VirtualList is what
+ * 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
+ * rest-state shadow that lifts on hover — the same `--r-md`/`--e-1`/`--e-2` elevation
+ * vocabulary Card itself uses (see styles/components.css's ".fd-erow" rules), just at
+ * the tighter radius a compact row reads better at than Card's own `--r-lg`. Height is
+ * 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.
+ * future change has to remember to update — the card treatment lives entirely in
+ * padding/border/shadow, not height.
  *
  * The drag/drop split is deliberate: a row only ever needs to say "I am the thing being
- * dragged" (draggable + onDragStart/onDragEnd), never "something was dropped on me" —
- * nothing in this kit drops one row onto another to reorder it, only a row onto a list to
- * move it there. Putting onDragOver/onDrop on every row would mean wiring the same drop
- * logic N times over instead of once on the list container that actually owns it (see
- * TransferList), so this only exposes the source half of the native HTML5 DnD contract.
+ * dragged" (draggable + onPointerDown), never "something was dropped on me" — nothing in
+ * this kit drops one row onto another to reorder it, only a row onto a list to move it
+ * there. Putting the drop handling on every row would mean wiring the same drop logic N
+ * times over instead of once on the list container that actually owns it (see
+ * TransferList's own doc comment for why it drives a pointer-based custom drag rather than
+ * native HTML5 DnD — in short, a native drag image is a static snapshot, not a live
+ * element, so it can't sustain a persistent tilt that follows the cursor), so this only
+ * exposes the source half of the contract: `onPointerDown` hands the gesture off to
+ * whatever the caller wants to do with it (TransferList starts tracking a drag once the
+ * pointer has moved past a small threshold, so a plain click still reads as a click).
  * The action button exists precisely so drag-and-drop is never the only way to do the
  * same move — pointer-only and keyboard users get an equally real affordance, not a
  * degraded fallback.
  */
-declare function EntityRow({ title, meta, action, draggable, onDragStart, onDragEnd, style, className }: EntityRowProps): React.JSX.Element;
+declare function EntityRow({ title, meta, action, draggable, onPointerDown, style, className }: EntityRowProps): React.JSX.Element;
 
 type TransferListSide = "left" | "right";
 interface TransferListSideProps<T> {
@@ -1126,6 +1153,11 @@ interface TransferListSideProps<T> {
     /** Total matching count on the server, if known — shown next to the label. */
     total?: number;
     loading?: boolean;
+    /** True while this side's WHOLE result set is being replaced (a search or sort
+     *  change), not merely appended to. `items` should still be the previous result set
+     *  while this is true — see VirtualList's own `refreshing` prop, which this threads
+     *  straight through. */
+    refreshing?: boolean;
     search: string;
     onSearchChange: (value: string) => void;
     sort?: {
@@ -1142,6 +1174,12 @@ interface TransferListSideProps<T> {
     /** Heading text for this side. Fully caller-supplied — this component has no opinion
      *  about what the two sides represent. */
     label?: string;
+    /** 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
+     *  audience"), since that phrasing is about what a drop here DOES, which only the
+     *  caller's domain actually knows. */
+    dropLabel?: string;
 }
 interface TransferListProps<T> {
     left: TransferListSideProps<T>;
@@ -1169,19 +1207,23 @@ interface TransferListProps<T> {
  * lists is specific to that use, and baking in "available"/"selected" (or worse, this
  * kit's actual first consumer's own vocabulary) would make every *other* two-list picker
  * this kit will ever be asked for a second component instead of a second set of props. A
- * caller wanting domain words passes them through `label`.
+ * caller wanting domain words passes them through `label`/`dropLabel`.
  *
- * Native HTML5 drag-and-drop, not a library: this kit ships zero runtime dependencies on
- * purpose, and moving one row between two lists is exactly the case the platform's own
- * draggable/dragstart/dragover/drop already cover with no gap to fill — sortable-within-
- * a-list (which does need pointer math and placeholder gaps) is a different, harder
- * problem this component doesn't attempt. Each row is the drag source (via EntityRow's
- * draggable prop); each *side* is the drop target — one onDragOver/onDrop pair per side,
- * not per row, since dropping only ever means "move into this list," never "onto this
- * particular other row." dataTransfer carries the dragged key mainly so a real
- * OS-level drag has real payload (Firefox refuses a drag with no data set at all); which
- * item is actually moved is tracked in local `dragging` state, because dataTransfer's own
- * payload can't hold a reference to `item: T` — only the string the caller's keyOf gives it.
+ * A pointer-based custom drag, not native HTML5 DnD, and not a library: this kit ships
+ * zero runtime dependencies on purpose, and a pointer-events implementation (pointerdown/
+ * pointermove/pointerup driving a portaled ghost element) is still zero-dependency — just
+ * more code than `draggable`. It replaced an earlier native-HTML5-DnD version once the
+ * spec called for a real "card lifts out of the list and tilts, following the cursor"
+ * feel: a native drag image (`dataTransfer.setDragImage`) is a static snapshot taken once
+ * at dragstart, not a live element, so it can't sustain a persistent rotation that tracks
+ * the pointer for the duration of the drag — only owning the pointer events ourselves can.
+ * Each row's pointerdown (via EntityRow's `onPointerDown`) arms a potential drag; nothing
+ * visually happens until the pointer actually moves past `DRAG_THRESHOLD_PX`, so a plain
+ * click (on the row, or on its +/- action button) is never mistaken for one. Once armed,
+ * window-level pointermove/pointerup/pointercancel listeners (not per-row ones, since the
+ * row being dragged gets replaced by a placeholder mid-drag) track the gesture to
+ * completion; which side the pointer is currently over is decided by hit-testing each
+ * side's own bounding rect against the pointer position, not by any per-row target.
  *
  * The +/- action on every row is not a fallback bolted on for accessibility box-ticking:
  * it is the same onMove call a drop makes, exposed as a first-class equivalent, because