@flytedan/flytebot-design-system 0.10.0 → 0.11.0

package/dist/index.d.cts

@@ -29,24 +29,41 @@ interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>
     /** Accessible name, also the title tooltip. Required. */
     label: string;
     size?: "sm" | "md" | "lg";
-    variant?: "ghost" | "outline";
+    /** "ghost" and "outline" are quiet: no fill, the glyph carries the tone. "solid" is a
+     *  filled button in the tone's colour — for the one action on a surface that has to be
+     *  found at a glance, like the add/remove button on every row of a transfer list. */
+    variant?: "ghost" | "outline" | "solid";
+    /** What the action does. On "solid" it picks the fill; on "ghost"/"outline" it tints the
+     *  glyph. "neutral" is the default look of each variant, which for "solid" is the brand
+     *  fill. Every tone has hover, pressed and focus states and is legible in both themes —
+     *  the fills are the --btn-solid-* tokens, measured against light and dark grounds. */
+    tone?: "neutral" | "ok" | "danger";
     round?: boolean;
     disabled?: boolean;
     className?: string;
 }
-declare function IconButton({ icon, label, size, variant, round, disabled, className, ...rest }: IconButtonProps): React.JSX.Element;
+declare function IconButton({ icon, label, size, variant, tone, round, disabled, className, ...rest }: IconButtonProps): React.JSX.Element;
 
 type Placement = "bottom-start" | "bottom-end" | "bottom-center" | "top-start" | "top-end" | "top-center";
 interface PopoverProps {
     open?: boolean;
     anchorRef: React.RefObject<HTMLElement>;
+    /** The element whose own clicks open and close this popover, when that is more than
+     *  the anchor — a form field's label toggles it too, but the surface is positioned
+     *  against the input box alone. A pointerdown inside it is not an "outside" press, so
+     *  the toggle it is about to run is not undone by a dismissal a moment earlier.
+     *  Defaults to `anchorRef`. */
+    triggerRef?: React.RefObject<HTMLElement>;
     onClose?: () => void;
     placement?: Placement;
     offset?: number;
-    matchWidth?: boolean;
+    /** `true`: exactly the anchor's width. `"min"`: at least the anchor's width, growing
+     *  with content past it (a select whose options are wider than its box). */
+    matchWidth?: boolean | "min";
     width?: number;
     minWidth?: number;
     maxHeight?: number;
+    /** Standard content padding on the body. The header and footer own their own. */
     padded?: boolean;
     role?: string;
     label?: string;
@@ -55,6 +72,13 @@ interface PopoverProps {
     returnFocus?: boolean;
     className?: string;
     style?: React.CSSProperties;
+    /** Pinned above the body and never scrolled away: a back link, a title, a segmented
+     *  toggle, a search field. */
+    header?: React.ReactNode;
+    /** Pinned below the body and never scrolled away: the Add / Apply / Confirm action and
+     *  any summary beside it. */
+    footer?: React.ReactNode;
+    /** The body — the one region of the surface that scrolls. */
     children?: React.ReactNode;
 }
 interface PopoverPosition {
@@ -82,6 +106,14 @@ interface PopoverPosition {
  * only set when the geometry actually changed (see samePosition), so a stationary anchor
  * causes no re-renders at all.
  *
+ * The side is chosen from the layer's real size once `layerRef` has rendered (see
+ * measureLayer): it flips when what it needs does not fit on the preferred side and the
+ * other side has more room. Until then — the first frame, before there is anything to
+ * measure — `estHeight` stands in, and only a nearly-exhausted side (under 180px) flips,
+ * so a small layer of unknown size is not thrown to the far side on a guess. The real
+ * width replaces `estWidth` the same way, which is what keeps an end- or center-aligned
+ * layer of content width lined up with its anchor.
+ *
  * 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.
@@ -90,12 +122,29 @@ declare function usePopoverPosition(open: boolean, anchorRef: React.RefObject<HT
     estHeight?: number;
     estWidth?: number;
     onDetach?: () => void;
+    /** The rendered layer, so its real size replaces the estimates once it exists. */
+    layerRef?: React.RefObject<HTMLElement>;
 }): PopoverPosition | null;
 /**
  * An anchored floating surface: menus, pickers, disclosure panels, meters.
- * Owns nothing but placement, dismissal and focus return — the content is yours.
- */
-declare function Popover({ open, anchorRef, onClose, placement, offset, matchWidth, width, minWidth, maxHeight, padded, role, label, closeOnOutside, closeOnEscape, returnFocus, className, style, children, }: PopoverProps): React.ReactElement<any, string | React.JSXElementConstructor<any>> | null;
+ * Owns placement, dismissal, focus return — and its own layout, which is the one rule
+ * every popover shares: THE SURFACE NEVER SCROLLS.
+ *
+ * It is always three stacked regions: an optional `header`, the body (`children`), and
+ * an optional `footer`. Header and footer are pinned; the body is the only thing that
+ * scrolls, and it shrinks to whatever height is left once they are laid out. The surface
+ * is capped by the real room between the anchor and the viewport edge (or `maxHeight`, if
+ * that is smaller) and flips to the other side when it doesn't fit, so the footer is
+ * never the thing that gets cut off.
+ *
+ * This is structural rather than advice because the failure it prevents is structural:
+ * a surface that scrolls as a whole takes its Apply button below the fold with it, and a
+ * scrolling list inside a scrolling surface is two nested scrollbars. Anything inside
+ * the body that owns a scroll region of its own (a Menu, a Select's options) is laid out
+ * to shrink into the body rather than overflow it — see `.fd-pop-body` in
+ * components.css — so there is only ever one scrollbar.
+ */
+declare function Popover({ open, anchorRef, triggerRef, onClose, placement, offset, matchWidth, width, minWidth, maxHeight, padded, role, label, closeOnOutside, closeOnEscape, returnFocus, className, style, header, footer, children, }: PopoverProps): React.ReactElement<any, string | React.JSXElementConstructor<any>> | null;
 interface MenuItem {
     id?: string;
     label?: React.ReactNode;
@@ -134,6 +183,10 @@ interface MenuProps {
  *   {id,label,icon,description,meta,shortcut,checked,disabled,submenu,onSelect}
  *   {kind:"separator"} · {kind:"section",label} · {kind:"custom",render}
  * `shortcut` is a HINT — it renders a cap and binds nothing.
+ *
+ * `header` and `footer` are pinned and only the items scroll: the whole menu is one
+ * shrinkable frame, so inside a Popover body a search header stays put while a long list
+ * scrolls beneath it, instead of the header scrolling away with the items.
  */
 declare function Menu({ items, onSelect, onClose, autoFocus, className, footer, header }: MenuProps): React.JSX.Element;
 interface MenuButtonProps extends Omit<MenuProps, "onClose" | "autoFocus"> {
@@ -495,13 +548,33 @@ interface ToastProps {
 }
 declare function Toast({ title, children, tone, onUndo, onDismiss, className, ...rest }: ToastProps): React.JSX.Element;
 
-/** A short clarification on hover or focus. Never the only place information lives. */
+/** A short clarification on hover, focus or tap. Never the only place information lives. */
 interface TooltipProps {
     label: React.ReactNode;
     placement?: "top" | "bottom";
     children?: React.ReactNode;
     className?: string;
 }
+/**
+ * Tooltip — the kit's one tooltip, for any trigger.
+ *
+ * Three ways in, because a tooltip reachable only by a mouse hides its text from
+ * everyone else: hover (mouse only), keyboard focus (`:focus-visible`, so a mouse click
+ * that happens to focus a button does not pin a tip open) and tap (touch or pen — there is
+ * no hover on a touchscreen, so a tap toggles it). Escape and a press anywhere else
+ * dismiss it; the pointer can move from the trigger onto the tip without it closing.
+ *
+ * The text is the trigger's accessible DESCRIPTION, not just a visual: a visually hidden
+ * copy is always in the document and the trigger points at it with aria-describedby, so a
+ * screen reader announces it on focus whether or not the bubble is showing at that
+ * instant. The trigger is the single child element when there is one (it receives the
+ * attribute); otherwise the wrapper does.
+ *
+ * The bubble is portaled to document.body and positioned with the same anchored-layer
+ * geometry as Popover (flip, clamp, follow a moving anchor), because a tooltip drawn
+ * inside its trigger's box is clipped by the first `overflow: hidden` ancestor — which in
+ * a fixed-width table cell or a list row is all of them.
+ */
 declare function Tooltip({ label, placement, children, className }: TooltipProps): React.JSX.Element;
 
 interface ClampProps {
@@ -1230,8 +1303,11 @@ interface EntityRowAction {
     /** Accessible name for the action button. */
     label: string;
     onClick: () => void;
-    /** Tints the icon — "add" reads as constructive (ok-text), "remove" as destructive
-     *  (danger-text). No effect on layout, only color, so a caller can still pass any icon. */
+    /** Picks the fill — "add" is the constructive (ok) fill, "remove" the destructive
+     *  (danger) fill, and no tone the brand fill. The button is always a filled
+     *  IconButton (variant "solid"): it is the one action on the row, repeated down a long
+     *  list, and has to be findable at a glance on a default card and on a danger-toned one
+     *  alike. No effect on layout, so a caller can still pass any icon. */
     tone?: "add" | "remove";
 }
 /** Width in px a metric cell takes when it doesn't ask for its own. Wide enough for a
@@ -1243,9 +1319,17 @@ interface EntityRowMetric {
      *  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". */
+     *  it is the metric's accessible name, so the row stays scannable as numbers while a
+     *  screen reader still hears "1,240 students". Without a `tooltip` it is also the
+     *  cell's native hover title. */
     label: string;
+    /** The long-form explanation of this figure — what it counts, why it is zero, what an
+     *  "unknown" means. Shown in the kit's Tooltip on hover, keyboard focus and tap, and
+     *  exposed as the cell's accessible description (`label` stays its short name). A cell
+     *  with a tooltip becomes a focusable button so the explanation is reachable without a
+     *  mouse, and drops the native `title` so two tooltips never show at once. A button is
+     *  also what keeps a tap on it from arming TransferList's row drag. */
+    tooltip?: React.ReactNode;
     value: React.ReactNode;
     /** Phosphor icon name shown before the value, e.g. "student". */
     icon?: string;
@@ -1516,6 +1600,11 @@ interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
     loading?: boolean;
     /** Applied to the outer .fd-field element — this is where width belongs. */
     style?: React.CSSProperties;
+    /** Applied to the outer .fd-field element, like `style` and for the same reason: that
+     *  element is the field's box in whatever layout it sits in (a flex toolbar, a grid
+     *  cell). The input box inside it is a child of a vertical flex column, so a sizing
+     *  class landing THERE turns a row's `flex-basis` into a height. */
+    className?: string;
     /** Applied to the inner input element. Rarely needed. */
     inputStyle?: React.CSSProperties;
 }
@@ -1532,6 +1621,7 @@ interface SearchFieldProps {
     onClear?: () => void;
     /** Applied to the outer .fd-field element — this is where width belongs. */
     style?: React.CSSProperties;
+    /** Applied to the outer .fd-field element, like `style`. */
     className?: string;
     /** Visible field label, same as Input. Most search fields skip this and rely on placeholder. */
     label?: string;
@@ -1563,8 +1653,10 @@ interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement
     error?: string;
     required?: boolean;
     rows?: number;
-    /** Applied to the field wrapper. */
+    /** Applied to the outer .fd-field element — this is where width belongs. */
     style?: React.CSSProperties;
+    /** Applied to the outer .fd-field element, like `style` — the same rule as Input. */
+    className?: string;
 }
 declare function Textarea({ label, help, error, required, rows, disabled, id, className, style, ...rest }: TextareaProps): React.JSX.Element;
 

package/dist/index.d.ts

@@ -29,24 +29,41 @@ interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>
     /** Accessible name, also the title tooltip. Required. */
     label: string;
     size?: "sm" | "md" | "lg";
-    variant?: "ghost" | "outline";
+    /** "ghost" and "outline" are quiet: no fill, the glyph carries the tone. "solid" is a
+     *  filled button in the tone's colour — for the one action on a surface that has to be
+     *  found at a glance, like the add/remove button on every row of a transfer list. */
+    variant?: "ghost" | "outline" | "solid";
+    /** What the action does. On "solid" it picks the fill; on "ghost"/"outline" it tints the
+     *  glyph. "neutral" is the default look of each variant, which for "solid" is the brand
+     *  fill. Every tone has hover, pressed and focus states and is legible in both themes —
+     *  the fills are the --btn-solid-* tokens, measured against light and dark grounds. */
+    tone?: "neutral" | "ok" | "danger";
     round?: boolean;
     disabled?: boolean;
     className?: string;
 }
-declare function IconButton({ icon, label, size, variant, round, disabled, className, ...rest }: IconButtonProps): React.JSX.Element;
+declare function IconButton({ icon, label, size, variant, tone, round, disabled, className, ...rest }: IconButtonProps): React.JSX.Element;
 
 type Placement = "bottom-start" | "bottom-end" | "bottom-center" | "top-start" | "top-end" | "top-center";
 interface PopoverProps {
     open?: boolean;
     anchorRef: React.RefObject<HTMLElement>;
+    /** The element whose own clicks open and close this popover, when that is more than
+     *  the anchor — a form field's label toggles it too, but the surface is positioned
+     *  against the input box alone. A pointerdown inside it is not an "outside" press, so
+     *  the toggle it is about to run is not undone by a dismissal a moment earlier.
+     *  Defaults to `anchorRef`. */
+    triggerRef?: React.RefObject<HTMLElement>;
     onClose?: () => void;
     placement?: Placement;
     offset?: number;
-    matchWidth?: boolean;
+    /** `true`: exactly the anchor's width. `"min"`: at least the anchor's width, growing
+     *  with content past it (a select whose options are wider than its box). */
+    matchWidth?: boolean | "min";
     width?: number;
     minWidth?: number;
     maxHeight?: number;
+    /** Standard content padding on the body. The header and footer own their own. */
     padded?: boolean;
     role?: string;
     label?: string;
@@ -55,6 +72,13 @@ interface PopoverProps {
     returnFocus?: boolean;
     className?: string;
     style?: React.CSSProperties;
+    /** Pinned above the body and never scrolled away: a back link, a title, a segmented
+     *  toggle, a search field. */
+    header?: React.ReactNode;
+    /** Pinned below the body and never scrolled away: the Add / Apply / Confirm action and
+     *  any summary beside it. */
+    footer?: React.ReactNode;
+    /** The body — the one region of the surface that scrolls. */
     children?: React.ReactNode;
 }
 interface PopoverPosition {
@@ -82,6 +106,14 @@ interface PopoverPosition {
  * only set when the geometry actually changed (see samePosition), so a stationary anchor
  * causes no re-renders at all.
  *
+ * The side is chosen from the layer's real size once `layerRef` has rendered (see
+ * measureLayer): it flips when what it needs does not fit on the preferred side and the
+ * other side has more room. Until then — the first frame, before there is anything to
+ * measure — `estHeight` stands in, and only a nearly-exhausted side (under 180px) flips,
+ * so a small layer of unknown size is not thrown to the far side on a guess. The real
+ * width replaces `estWidth` the same way, which is what keeps an end- or center-aligned
+ * layer of content width lined up with its anchor.
+ *
  * 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.
@@ -90,12 +122,29 @@ declare function usePopoverPosition(open: boolean, anchorRef: React.RefObject<HT
     estHeight?: number;
     estWidth?: number;
     onDetach?: () => void;
+    /** The rendered layer, so its real size replaces the estimates once it exists. */
+    layerRef?: React.RefObject<HTMLElement>;
 }): PopoverPosition | null;
 /**
  * An anchored floating surface: menus, pickers, disclosure panels, meters.
- * Owns nothing but placement, dismissal and focus return — the content is yours.
- */
-declare function Popover({ open, anchorRef, onClose, placement, offset, matchWidth, width, minWidth, maxHeight, padded, role, label, closeOnOutside, closeOnEscape, returnFocus, className, style, children, }: PopoverProps): React.ReactElement<any, string | React.JSXElementConstructor<any>> | null;
+ * Owns placement, dismissal, focus return — and its own layout, which is the one rule
+ * every popover shares: THE SURFACE NEVER SCROLLS.
+ *
+ * It is always three stacked regions: an optional `header`, the body (`children`), and
+ * an optional `footer`. Header and footer are pinned; the body is the only thing that
+ * scrolls, and it shrinks to whatever height is left once they are laid out. The surface
+ * is capped by the real room between the anchor and the viewport edge (or `maxHeight`, if
+ * that is smaller) and flips to the other side when it doesn't fit, so the footer is
+ * never the thing that gets cut off.
+ *
+ * This is structural rather than advice because the failure it prevents is structural:
+ * a surface that scrolls as a whole takes its Apply button below the fold with it, and a
+ * scrolling list inside a scrolling surface is two nested scrollbars. Anything inside
+ * the body that owns a scroll region of its own (a Menu, a Select's options) is laid out
+ * to shrink into the body rather than overflow it — see `.fd-pop-body` in
+ * components.css — so there is only ever one scrollbar.
+ */
+declare function Popover({ open, anchorRef, triggerRef, onClose, placement, offset, matchWidth, width, minWidth, maxHeight, padded, role, label, closeOnOutside, closeOnEscape, returnFocus, className, style, header, footer, children, }: PopoverProps): React.ReactElement<any, string | React.JSXElementConstructor<any>> | null;
 interface MenuItem {
     id?: string;
     label?: React.ReactNode;
@@ -134,6 +183,10 @@ interface MenuProps {
  *   {id,label,icon,description,meta,shortcut,checked,disabled,submenu,onSelect}
  *   {kind:"separator"} · {kind:"section",label} · {kind:"custom",render}
  * `shortcut` is a HINT — it renders a cap and binds nothing.
+ *
+ * `header` and `footer` are pinned and only the items scroll: the whole menu is one
+ * shrinkable frame, so inside a Popover body a search header stays put while a long list
+ * scrolls beneath it, instead of the header scrolling away with the items.
  */
 declare function Menu({ items, onSelect, onClose, autoFocus, className, footer, header }: MenuProps): React.JSX.Element;
 interface MenuButtonProps extends Omit<MenuProps, "onClose" | "autoFocus"> {
@@ -495,13 +548,33 @@ interface ToastProps {
 }
 declare function Toast({ title, children, tone, onUndo, onDismiss, className, ...rest }: ToastProps): React.JSX.Element;
 
-/** A short clarification on hover or focus. Never the only place information lives. */
+/** A short clarification on hover, focus or tap. Never the only place information lives. */
 interface TooltipProps {
     label: React.ReactNode;
     placement?: "top" | "bottom";
     children?: React.ReactNode;
     className?: string;
 }
+/**
+ * Tooltip — the kit's one tooltip, for any trigger.
+ *
+ * Three ways in, because a tooltip reachable only by a mouse hides its text from
+ * everyone else: hover (mouse only), keyboard focus (`:focus-visible`, so a mouse click
+ * that happens to focus a button does not pin a tip open) and tap (touch or pen — there is
+ * no hover on a touchscreen, so a tap toggles it). Escape and a press anywhere else
+ * dismiss it; the pointer can move from the trigger onto the tip without it closing.
+ *
+ * The text is the trigger's accessible DESCRIPTION, not just a visual: a visually hidden
+ * copy is always in the document and the trigger points at it with aria-describedby, so a
+ * screen reader announces it on focus whether or not the bubble is showing at that
+ * instant. The trigger is the single child element when there is one (it receives the
+ * attribute); otherwise the wrapper does.
+ *
+ * The bubble is portaled to document.body and positioned with the same anchored-layer
+ * geometry as Popover (flip, clamp, follow a moving anchor), because a tooltip drawn
+ * inside its trigger's box is clipped by the first `overflow: hidden` ancestor — which in
+ * a fixed-width table cell or a list row is all of them.
+ */
 declare function Tooltip({ label, placement, children, className }: TooltipProps): React.JSX.Element;
 
 interface ClampProps {
@@ -1230,8 +1303,11 @@ interface EntityRowAction {
     /** Accessible name for the action button. */
     label: string;
     onClick: () => void;
-    /** Tints the icon — "add" reads as constructive (ok-text), "remove" as destructive
-     *  (danger-text). No effect on layout, only color, so a caller can still pass any icon. */
+    /** Picks the fill — "add" is the constructive (ok) fill, "remove" the destructive
+     *  (danger) fill, and no tone the brand fill. The button is always a filled
+     *  IconButton (variant "solid"): it is the one action on the row, repeated down a long
+     *  list, and has to be findable at a glance on a default card and on a danger-toned one
+     *  alike. No effect on layout, so a caller can still pass any icon. */
     tone?: "add" | "remove";
 }
 /** Width in px a metric cell takes when it doesn't ask for its own. Wide enough for a
@@ -1243,9 +1319,17 @@ interface EntityRowMetric {
      *  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". */
+     *  it is the metric's accessible name, so the row stays scannable as numbers while a
+     *  screen reader still hears "1,240 students". Without a `tooltip` it is also the
+     *  cell's native hover title. */
     label: string;
+    /** The long-form explanation of this figure — what it counts, why it is zero, what an
+     *  "unknown" means. Shown in the kit's Tooltip on hover, keyboard focus and tap, and
+     *  exposed as the cell's accessible description (`label` stays its short name). A cell
+     *  with a tooltip becomes a focusable button so the explanation is reachable without a
+     *  mouse, and drops the native `title` so two tooltips never show at once. A button is
+     *  also what keeps a tap on it from arming TransferList's row drag. */
+    tooltip?: React.ReactNode;
     value: React.ReactNode;
     /** Phosphor icon name shown before the value, e.g. "student". */
     icon?: string;
@@ -1516,6 +1600,11 @@ interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
     loading?: boolean;
     /** Applied to the outer .fd-field element — this is where width belongs. */
     style?: React.CSSProperties;
+    /** Applied to the outer .fd-field element, like `style` and for the same reason: that
+     *  element is the field's box in whatever layout it sits in (a flex toolbar, a grid
+     *  cell). The input box inside it is a child of a vertical flex column, so a sizing
+     *  class landing THERE turns a row's `flex-basis` into a height. */
+    className?: string;
     /** Applied to the inner input element. Rarely needed. */
     inputStyle?: React.CSSProperties;
 }
@@ -1532,6 +1621,7 @@ interface SearchFieldProps {
     onClear?: () => void;
     /** Applied to the outer .fd-field element — this is where width belongs. */
     style?: React.CSSProperties;
+    /** Applied to the outer .fd-field element, like `style`. */
     className?: string;
     /** Visible field label, same as Input. Most search fields skip this and rely on placeholder. */
     label?: string;
@@ -1563,8 +1653,10 @@ interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement
     error?: string;
     required?: boolean;
     rows?: number;
-    /** Applied to the field wrapper. */
+    /** Applied to the outer .fd-field element — this is where width belongs. */
     style?: React.CSSProperties;
+    /** Applied to the outer .fd-field element, like `style` — the same rule as Input. */
+    className?: string;
 }
 declare function Textarea({ label, help, error, required, rows, disabled, id, className, style, ...rest }: TextareaProps): React.JSX.Element;