themelia-ui 2.0.0 → 3.0.0

package/dist/components/base/alert-dialog/alert-dialog.d.ts

@@ -6,6 +6,12 @@ import { OverlayContentProps } from '../overlay/index.js';
  * answers (`Action`, `Cancel`) and a media slot.
  */
 import * as React from "react";
+/**
+ * A centred surface that demands an answer. It fixes `placement` to centre and announces as
+ * `alertdialog`; both dismissal routes are fixed off and the corner close is off by
+ * default, so the backdrop and Escape never decide for the reader. `modality`, `surface`
+ * and `initialFocusRef` are OverlayContent's props.
+ */
 export declare function AlertDialogContent({ className, ...props }: Omit<OverlayContentProps, "placement" | "dismissal">): React.JSX.Element;
 /** Media slot above the title — an illustration or icon carrying the alert's weight. */
 export declare function AlertDialogMedia({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
@@ -15,5 +21,9 @@ type AnswerProps = React.ComponentProps<"button"> & {
 };
 /** The affirmative answer. Closes on click unless the handler prevents it. */
 export declare function AlertDialogAction({ className, ...props }: AnswerProps): React.JSX.Element;
+/**
+ * The answer that backs out. Both answers close the dialog; `AlertDialogAction` is the one
+ * that commits. With no dismissal and no corner close, they are the only ways out.
+ */
 export declare function AlertDialogCancel({ className, ...props }: AnswerProps): React.JSX.Element;
 export {};

package/dist/components/base/aspect-ratio/aspect-ratio.d.ts

@@ -4,8 +4,9 @@ export interface AspectRatioProps extends ComponentProps<"div"> {
     /** Width divided by height — `16 / 9`, `1`, `4 / 3` — as a number, never parsed. */
     ratio?: ResponsiveValue<number>;
     /**
-     * How a media child fills the box: `cover` crops to fill (the usual frame); `contain` fits
-     * inside, for artwork whose edges matter (a logo, a diagram, a screenshot).
+     * How a media child fills the box: `cover` crops to fill it (the usual frame); `contain`
+     * fits the whole image inside and leaves the rest of the box empty, for artwork whose edges
+     * matter (a logo, a diagram, a screenshot).
      */
     fit?: "cover" | "contain";
 }

package/dist/components/base/avatar/avatar.d.ts

@@ -3,12 +3,25 @@ import * as React from "react";
 /** An avatar keeps a size prop: it has no content to scale with. */
 export type AvatarSize = "default" | "sm" | "lg";
 export type AvatarProps = AvatarPrimitive.Root.Props & {
+    /** Disc size. One of the kit's few size props: an avatar has no content to scale with. */
     size?: AvatarSize;
 };
+/** A person or an entity as a disc: an image, with initials behind it for when there is none. */
 declare function Avatar({ className, size, ...props }: AvatarProps): React.JSX.Element;
-declare function AvatarImage({ className, ...props }: AvatarPrimitive.Image.Props): React.JSX.Element;
+/**
+ * The picture. An empty `alt` is correct beside a visible name; the name already announces
+ * the person.
+ */
+declare function AvatarImage({ className, ...props }: AvatarPrimitive.Image.Props & Pick<AvatarPrimitive.Image.Props, "src" | "alt">): React.JSX.Element;
+/** Shown when there is no image. Initials, not a placeholder glyph. */
 declare function AvatarFallback({ className, ...props }: AvatarPrimitive.Fallback.Props): React.JSX.Element;
+/** A small status mark on the disc's corner. */
 declare function AvatarBadge({ className, ...props }: React.ComponentProps<"span">): React.JSX.Element;
+/** A row of overlapping avatars. */
 declare function AvatarGroup({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+/**
+ * The "+3" at the end of an `AvatarGroup`. A count rather than another avatar, so a group of
+ * twelve does not need twelve images to say so.
+ */
 declare function AvatarGroupCount({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
 export { Avatar, AvatarImage, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarBadge };

package/dist/components/base/avatar/stacked-avatars.d.ts

@@ -9,14 +9,19 @@ export interface StackedAvatarUser {
     initials?: string;
 }
 export interface StackedAvatarsProps extends Omit<ComponentProps<"div">, "children"> {
+    /** The people in the row, in order. */
     users: StackedAvatarUser[];
     /** Overrides this group's own copy — its accessible name, and the overflow chip. */
     strings?: Partial<StackedAvatarsStrings>;
-    /** How many faces to show before collapsing the rest into a count. */
+    /** How many faces to show. Beyond it, the remainder becomes a count. */
     max?: number;
-    /** Hides the "+N" tile, for a group where the total does not matter. */
+    /** Shows the "+N" tile. Turn it off for a group where the total does not matter. */
     showOverflow?: boolean;
-    /** Formats the overflow tile — "+12", "+12 more". Defaults to `strings.overflow`. */
+    /**
+     * How the remainder reads on the overflow tile — "+12", "+12 more". Defaults to
+     * `strings.overflow`, which reads "+N".
+     */
     overflowFormatter?: (overflow: number) => ReactNode;
 }
+/** People as overlapping avatars, capped with a count of the rest. */
 export declare function StackedAvatars({ users, strings, max, showOverflow, overflowFormatter, className, ...props }: StackedAvatarsProps): import("react").JSX.Element;

package/dist/components/base/badge/badge.d.ts

@@ -9,17 +9,21 @@ export type BadgeTone = "neutral" | "primary" | "secondary" | "success" | "info"
 /** Structural presentation. The tone supplies the hue; this decides how it is applied. */
 export type BadgeVariant = "soft" | "solid" | "outline";
 export interface BadgeProps extends React.ComponentProps<"span">, VariantProps<typeof badgeVariants> {
-    /**
-     * The element this becomes — an anchor, a router link, a label (docs/adr/0005).
-     * `children` stays the content.
-     */
-    render?: React.ReactElement;
+    /** Semantic colour: what the badge means. `variant` decides how much of it is applied. */
+    tone?: BadgeTone;
+    /** How much of the tone is applied. Structural, not semantic. */
+    variant?: BadgeVariant;
     /** A leading status dot in the badge's own tone. */
     dot?: boolean;
-    /** Draws the dot hollow, for a state that hasn't happened yet ("queued", not "failed"). */
+    /** Draws the dot hollow, for a state that has not happened yet: "queued", not "failed". */
     pending?: boolean;
     /** Animates the dot, for a state that is actively changing. */
     pulse?: boolean;
+    /**
+     * The element the badge becomes — an anchor or a router link, for a badge that links.
+     * The dot and `children` go inside it.
+     */
+    render?: React.ReactElement;
 }
 declare function Badge({ className, tone, variant, render, dot, pending, pulse, children, ...props }: BadgeProps): React.JSX.Element;
 export { Badge };

package/dist/components/base/batch-action-bar/batch-action-bar.d.ts

@@ -7,10 +7,11 @@ export interface BatchActionBarProps {
     selectedCount: number;
     /** Optional denominator for the summary. Omit when the total is unknown or unbounded. */
     totalCount?: number;
-    /** Omit to render no clear control — a selection the user cannot drop needs a reason. */
+    /** Drops the selection. Omit to render no clear control — a selection the user cannot drop needs a reason. */
     onClear?: () => void;
     /** `floating` docks to the bottom centre of the viewport; `inline` sits in flow. */
     placement?: BatchActionBarPlacement;
+    /** Overrides this bar's own copy: `summary(selected, total)`, `clear`, and the region's accessible `label`. */
     strings?: StringsProp<BatchActionBarStrings>;
     /** The bulk actions. Buttons, a menu, whatever the surface needs. */
     children?: ReactNode;

package/dist/components/base/buttons/button-group.d.ts

@@ -1,15 +1,24 @@
 /** ButtonGroup — adjacent buttons read as one control: one hairline seam, squared inner corners. */
 import * as React from "react";
 export interface ButtonGroupProps extends React.ComponentProps<"div"> {
+    /** The direction the buttons run in. */
     orientation?: "horizontal" | "vertical";
 }
+/** Adjacent buttons that read as one control: one hairline seam, squared inner corners. */
 export declare function ButtonGroup({ orientation, className, ...props }: ButtonGroupProps): React.JSX.Element;
 export interface ButtonGroupTextProps extends React.ComponentProps<"span"> {
 }
-/** A non-interactive segment — a unit, a prefix, a count. A span, so it adds no tab stop. */
+/**
+ * A label that sits in the run without becoming pressable — a unit, a prefix, a count. A
+ * span, so it adds no tab stop.
+ */
 export declare function ButtonGroupText({ className, ...props }: ButtonGroupTextProps): React.JSX.Element;
 export interface ButtonGroupSeparatorProps extends React.ComponentProps<"div"> {
+    /** The orientation of the group it sits in; the seam runs across it. */
     orientation?: "horizontal" | "vertical";
 }
-/** A rule between segments, where the collapsed border alone is not enough. */
+/**
+ * The seam between welded buttons, where the collapsed border alone is not enough. A plain
+ * `Separator` here would draw a full-height rule against the group's own border.
+ */
 export declare function ButtonGroupSeparator({ orientation, className, ...props }: ButtonGroupSeparatorProps): React.JSX.Element;

package/dist/components/base/buttons/button.d.ts

@@ -1,17 +1,25 @@
 import { ButtonStyle, ButtonTone } from './button.types.js';
 /**
  * Button — the kit's action primitive. `tone` (colour intent) and `buttonStyle` (fill) are
- * independent axes; the tone × style matrix in button-tones.module.css is generated.
+ * independent axes; the tone × style matrix lives in button-tones.module.css.
  * Defaults resolve through the provider, so a scope can restyle every button in it.
  */
 import * as React from "react";
 export interface ButtonProps extends Omit<React.ComponentProps<"button">, "children"> {
-    /** Semantic colour intent. */
+    /**
+     * Semantic colour intent. Resolves through the provider when omitted, so `UIProvider`
+     * defaults can change it.
+     * @default "primary"
+     */
     tone?: ButtonTone;
-    /** Fill treatment. */
+    /**
+     * Fill treatment, independent of `tone`. `UIProvider` defaults can change it.
+     * @default "solid"
+     */
     buttonStyle?: ButtonStyle;
     /** Square button sized to its height. The label becomes the accessible name. */
     iconOnly?: boolean;
+    /** Stretches the button to its container's width. */
     fullWidth?: boolean;
     /**
      * Shows a spinner and blocks interaction. The label keeps its space so the button does
@@ -19,8 +27,10 @@ export interface ButtonProps extends Omit<React.ComponentProps<"button">, "child
      */
     loading?: boolean;
     /**
-     * The element this button becomes — an anchor, a router link, a label (docs/adr/0005).
-     * `children` stay the content and keep the button's label wrapper.
+     * The element this button becomes — an anchor, a router link, a label. `children` stay
+     * the content and keep the button's label wrapper, so a link still sizes like a button.
+     * `render` is how every kit component changes its element, the contract Base UI's parts
+     * already take.
      *
      *   <Button render={<a href="/settings" />}>Settings</Button>
      */
@@ -28,7 +38,7 @@ export interface ButtonProps extends Omit<React.ComponentProps<"button">, "child
     children?: React.ReactNode;
 }
 /**
- * No `size` prop by design: geometry follows the scale factors, so a denser region is a
- * scope (styles/FACTORS.md).
+ * The kit's action primitive. No `size` prop by design: geometry follows the scale factors,
+ * so a denser region is a scope (styles/FACTORS.md).
  */
 export declare function Button({ tone, buttonStyle, iconOnly, fullWidth, loading, render, className, disabled, children, onClick, ...props }: ButtonProps): React.JSX.Element;

package/dist/components/base/buttons/loader-button.d.ts

@@ -7,15 +7,23 @@ import { ButtonLoadingStrings } from './button.strings.js';
  */
 import * as React from "react";
 export interface LoaderButtonProps extends Omit<ButtonProps, "onClick"> {
-    /** Controlled pending state. Omit to let the button manage it from `onClick`. */
+    /**
+     * Controlled pending state. Omit it and the button holds the state itself, from the
+     * promise `onClick` returns.
+     */
     loading?: boolean;
     /**
-     * Accepted for source-kit compatibility; inert. Choosing `LoaderButton` is already that
-     * decision. Swallowed rather than spread, so ported call sites don't leak it to the DOM.
+     * Accepted so call sites that pass it keep compiling; inert. Choosing `LoaderButton` is
+     * already that decision. Swallowed rather than spread, so it never reaches the DOM.
      */
     handlesLoading?: boolean;
     /** May return a promise; the button then stays pending until it settles. */
     onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void | Promise<unknown>;
+    /** Overrides the button's own copy: what it announces while it works. */
     strings?: StringsProp<ButtonLoadingStrings>;
 }
+/**
+ * A `Button` that can run its handler and hold the pending state itself. It also announces
+ * the wait, which `Button`'s own `loading` prop does not.
+ */
 export declare const LoaderButton: React.ForwardRefExoticComponent<Omit<LoaderButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/base/buttons/text-button.d.ts

@@ -1,8 +1,21 @@
 import { ButtonProps } from './button.js';
+import { ButtonTone } from './button.types.js';
 /**
  * TextButton — a button styled as a link, for actions on this page (announced as a
  * button, activated by Space). Anything that navigates should be a real anchor.
  */
 import * as React from "react";
-export type TextButtonProps = Omit<ButtonProps, "buttonStyle" | "iconOnly" | "fullWidth">;
+export type TextButtonProps = Omit<ButtonProps, "tone" | "buttonStyle" | "iconOnly" | "fullWidth"> & {
+    /**
+     * Semantic colour intent. A text button always sets it, so the provider's button defaults
+     * do not reach it.
+     */
+    tone?: ButtonTone;
+};
+/**
+ * A button that reads as a link, for actions on this page: announced as a button and
+ * activated by Space. Anything that navigates should be a real anchor. It carries its own
+ * `data-slot`, so nothing downstream mistakes it for a ghost button that should line up
+ * with controls — it is inline prose.
+ */
 export declare const TextButton: React.ForwardRefExoticComponent<Omit<TextButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/base/buttons/tooltip-button.d.ts

@@ -7,11 +7,17 @@ import { ButtonProps } from './button.js';
 import * as React from "react";
 export interface TooltipButtonProps extends ButtonProps {
     /**
-     * Shown on hover and focus. It is the accessible name only when the button has no text of
-     * its own; beside a visible label it is the description.
+     * Shown on hover and focus. It is also the accessible name when the button has no text
+     * of its own, and that pairing is the point: an icon button with a tooltip and no
+     * `aria-label` is unnamed to everyone not using a mouse. Beside a visible label it is the
+     * description.
      */
     tooltip: string;
     /** Where the tooltip opens. */
     side?: React.ComponentProps<typeof TooltipContent>["side"];
 }
+/**
+ * A button with a tooltip. For an icon-only button the tooltip text is also the accessible
+ * name, so it is not unnamed to anyone not using a mouse.
+ */
 export declare const TooltipButton: React.ForwardRefExoticComponent<Omit<TooltipButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/base/cards/card-actions.d.ts

@@ -1,22 +1,39 @@
 import { ComponentProps } from 'react';
-import { ActionDefinition, ActionLinkRenderer } from '../action-menu/index.js';
+import { ActionDefinition } from '../action-menu/index.js';
+import { LinkRenderer } from '../../../lib/navigation.js';
 export interface CardActionStripProps extends Omit<ComponentProps<"div">, "children"> {
+    /**
+     * The commands, as the overflow menu takes them. The first is the primary action; the rest
+     * follow in outline unless an entry sets its own `buttonStyle`.
+     */
     actions: ActionDefinition[];
-    /** A rule above the strip, for a card whose content runs right into it. */
+    /** A rule above the strip, ruling it off from content that runs right into it. */
     separator?: boolean;
+    /** Where the buttons sit along the strip. */
     align?: "start" | "end" | "between";
-    /** Stretches the first action, for a narrow card where two buttons will not fit. */
+    /**
+     * Stretches the first action, for a card whose action is the point, or a narrow card where
+     * two buttons will not fit.
+     */
     fullWidthPrimary?: boolean;
     /** Routes `href` actions through the app's router. */
-    renderLink?: ActionLinkRenderer;
+    renderLink?: LinkRenderer;
 }
+/**
+ * A card's commands as buttons. One array decides which action is primary and how the rest
+ * follow, so a page of cards cannot disagree about it.
+ */
 export declare function CardActionStrip({ actions, separator, align, fullWidthPrimary, renderLink, className, ...props }: CardActionStripProps): import("react").JSX.Element | null;
-export interface CardPrimaryActionProps extends ComponentProps<"a"> {
-    /** Names the target. The card's own title is not enough — many cards share one. */
+export interface CardPrimaryActionProps extends ComponentProps<"a">, Pick<ComponentProps<"a">, "href"> {
+    /**
+     * The link's accessible name. The visible title is not necessarily the destination, and
+     * many cards share one.
+     */
     label: string;
 }
 /**
- * Makes a whole card one target with a covering link (wrapping the card would nest its
- * controls inside an anchor). Interactive children are lifted above it in CSS.
+ * Stretches an anchor across the whole card, so the card is one tab stop rather than a grid
+ * of them (wrapping the card would nest its controls inside an anchor). Interactive children
+ * are lifted above it in CSS.
  */
 export declare function CardPrimaryAction({ label, className, ...props }: CardPrimaryActionProps): import("react").JSX.Element;

package/dist/components/base/cards/card-skeleton.d.ts

@@ -4,11 +4,19 @@ export interface CardSkeletonProps extends Omit<ComponentProps<"div">, "title">
     /**
      * Match the real card's surface. Unset, it takes the card's default (the provider's
      * `defaults.card.surface`, framed out of the box).
+     * @default "framed"
      */
     surface?: CardSurface;
     /** Reserves the header's height. */
     showHeader?: boolean;
+    /** Lines of content to reserve. Match the real card's. */
     lines?: number;
+    /** What the placeholder announces while it waits. Unset, the skeleton's own loading copy. */
     label?: string;
 }
+/**
+ * A placeholder that reserves the real card's box, so the page doesn't reflow when content
+ * lands. Matching the surface and the line count is the whole job: a placeholder of the wrong
+ * shape moves the page twice.
+ */
 export declare function CardSkeleton({ surface, showHeader, lines, label, className, ...props }: CardSkeletonProps): import("react").JSX.Element;

package/dist/components/base/cards/card.d.ts

@@ -8,16 +8,23 @@ import * as React from "react";
 export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
     /** Leading glyph on the title line. */
     icon?: React.ReactNode;
+    /** Header copy. The title truncates rather than pushing header controls off the row. */
     title?: React.ReactNode;
     /** Badges, status, or counts immediately after the title. */
     titleSuffix?: React.ReactNode;
     /**
-     * Explanatory copy behind a focusable info button on the title line — for a definition or
-     * caveat too long for the description.
+     * Explanatory copy behind an info button on the title line — for a definition or caveat
+     * too long for the description. A real focusable button, not a `title` attribute;
+     * `strings.tooltip` names it.
      */
     tooltip?: React.ReactNode;
+    /** Header copy under the title. */
     description?: React.ReactNode;
-    /** Outer chrome. */
+    /**
+     * Outer chrome. `framed`, the bezel, is the default; `card` is the plain panel. Change it
+     * for a whole product once with `UIProvider` `defaults.card.surface`.
+     * @default "framed"
+     */
     surface?: CardSurface;
     /** Full-width row above the title — an eyebrow or breadcrumb. Rare. */
     headerStart?: React.ReactNode;
@@ -25,25 +32,42 @@ export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
     headerEnd?: React.ReactNode;
     /** A single control at the end of the header. Use `actions` for a list of commands. */
     headerAction?: React.ReactNode;
-    /** Overflow commands, collapsed into one menu trigger. */
+    /**
+     * Overflow commands, collapsed into one menu trigger and rendered by the shared
+     * `ActionMenu`: a destructive entry moves last and is separated.
+     */
     actions?: CardAction[];
     /**
-     * Renders the title as a heading of this level. Unset, the title is a span that heading
-     * navigation can't find; set it when the card titles a page section.
+     * Renders the title as a heading of this level, for a card that heads a page or a region.
+     * Unset, the title is a span that heading navigation can't find.
      */
     titleLevel?: 1 | 2 | 3 | 4 | 5 | 6;
-    /** A full-bleed strip above the header — a cover image, an illustration, a preview. */
+    /**
+     * A full-bleed strip above the header — a cover image, a map, a brand band — clipped to
+     * the card's top corners.
+     */
     media?: React.ReactNode;
-    /** Banner between header and content. A plain string is wrapped for you. */
+    /** Banner between header and content. A plain string is wrapped in an `Alert`. */
     alert?: React.ReactNode;
+    /** Tone of the alert band. */
     alertTone?: CardAlertTone;
+    /** Content inside the content inset, above `children`. */
     contentTop?: React.ReactNode;
+    /** Content inside the content inset, below `children`. */
     contentBottom?: React.ReactNode;
     /** Muted text in the footer band. */
     footerText?: React.ReactNode;
     /** Footer band under the content — a single primary action fits well here. */
     footerSlot?: React.ReactNode;
+    /**
+     * A rule between the header and the content. `UIProvider` defaults can change it.
+     * @default false
+     */
     headerDivider?: boolean;
+    /**
+     * A rule between the content and the footer.
+     * @default false
+     */
     footerDivider?: boolean;
     /**
      * Clips content to a collapsed height with a fade, and adds a toggle. `true` uses
@@ -52,10 +76,21 @@ export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
     expandable?: boolean | {
         collapsedMaxHeight?: number | string;
     };
+    /** Whether an expandable card's content is expanded, for controlled expansion. */
     expanded?: boolean;
+    /** Whether an expandable card starts expanded, for uncontrolled expansion. */
     defaultExpanded?: boolean;
+    /** Called with the new state when the reader expands or collapses the content. */
     onExpandedChange?: (expanded: boolean) => void;
-    /** Overrides this card's own copy — the info glyph, the overflow trigger, the disclosure. */
+    /**
+     * Overrides this card's own copy — the info glyph, the overflow trigger, and the
+     * disclosure control's name in each state.
+     */
     strings?: Partial<CardStrings>;
 }
+/**
+ * The single surface primitive. Slot props (`title`, `description`, `actions`, `footerText`,
+ * …) cover the common shape; `CardHeader`, `CardContent` and `CardFooter` are exported for
+ * composing.
+ */
 export declare function Card({ icon, title, titleSuffix, tooltip, description, surface, titleLevel, media, headerStart, headerEnd, headerAction, actions, alert, alertTone, contentTop, contentBottom, footerText, footerSlot, headerDivider, footerDivider, expandable, expanded, defaultExpanded, onExpandedChange, strings, className, children, ...props }: CardProps): React.JSX.Element;

package/dist/components/base/cards/index.d.ts

@@ -4,3 +4,4 @@ export type { CardSurface, CardAction, CardAlertTone } from './card.types.js';
 export { CardActionStrip, CardPrimaryAction, type CardActionStripProps, type CardPrimaryActionProps, } from './card-actions.js';
 export { CardSkeleton, type CardSkeletonProps } from './card-skeleton.js';
 export { defaultCardStrings, type CardStrings } from './card.strings.js';
+export type { LinkRenderer, LinkRenderProps } from '../../../lib/navigation.js';

package/dist/components/base/carousel/carousel-context.d.ts

@@ -7,6 +7,10 @@ export declare const CarouselContext: import('react').Context<{
     scrollToSlide: (index: number) => void;
     strings: CarouselStrings;
 } | null>;
+/**
+ * The track's position, its slide count, and the scroll helpers, for a fully custom control
+ * surface. Must be called inside a `Carousel`.
+ */
 export declare function useCarousel(): {
     index: number;
     count: number;

package/dist/components/base/carousel/carousel.d.ts

@@ -4,30 +4,62 @@ export type CarouselOrientation = "horizontal" | "vertical";
 /** Where the previous/next controls sit. `overlay` floats them over the track's edges. */
 export type CarouselControlPlacement = "outside" | "overlay" | "none";
 export interface CarouselProps extends Omit<ComponentProps<"div">, "children"> {
+    /** The slides, usually `CarouselSlide`s. */
     children: ReactNode;
+    /** Which axis snaps. */
     orientation?: CarouselOrientation;
+    /**
+     * Where the previous/next buttons sit: `outside` the track, `overlay` on its edges, or
+     * `none` when you compose your own with `CarouselControl`.
+     */
     controls?: CarouselControlPlacement;
     /** Shows the position indicators, and lets them be clicked. */
     showDots?: boolean;
+    /** `pill` stretches the active indicator instead of only recolouring it. */
     dotStyle?: "dot" | "pill";
-    /** Overrides this carousel's own copy — the region name and the two controls. */
+    /**
+     * Overrides this carousel's own copy — the region name, the two icon-only controls, and
+     * each pagination dot. It travels through the context, so a control placed with
+     * `CarouselControl` is named by the same override as one the root rendered.
+     */
     strings?: Partial<CarouselStrings>;
+    /**
+     * Names the region for assistive technology; unset, `strings.label` does. A carousel with
+     * no name is an unexplained scroll box, and a page with two needs two names.
+     */
     label?: string;
+    /**
+     * Styles the scroll container rather than the outer frame — for a carousel that needs its
+     * own padding inside the clip.
+     */
     viewportClassName?: string;
 }
+/**
+ * A native scroll-snap track with controls. Script only reports the current slide and
+ * scrolls to a chosen one.
+ */
 export declare function Carousel({ children, orientation, controls, showDots, dotStyle, strings, label, className, viewportClassName, ...props }: CarouselProps): import("react").JSX.Element;
 export interface CarouselControlProps extends ComponentProps<"button"> {
+    /** Which way the control moves the track. */
     direction: "previous" | "next";
 }
-/** A previous/next control placed by the caller rather than by the root. */
+/**
+ * A single previous/next control placed by the caller rather than by the root, for composing
+ * your own layout with `controls="none"`. Must sit inside a `Carousel`.
+ */
 export declare function CarouselControl({ direction, className, children, ...props }: CarouselControlProps): import("react").JSX.Element;
 export interface CarouselDotsProps extends ComponentProps<"div"> {
+    /** `pill` stretches the active indicator instead of only recolouring it. */
     dotStyle?: "dot" | "pill";
 }
-/** The position indicators, placed by the caller. */
+/**
+ * The position indicators on their own, placed by the caller outside the track. Must sit
+ * inside a `Carousel`.
+ */
 export declare function CarouselDots({ dotStyle, className, ...props }: CarouselDotsProps): import("react").JSX.Element;
 export interface CarouselSlideProps extends ComponentProps<"div"> {
     /** Track width this slide occupies — "100%", "50%", "18rem". */
     size?: string;
 }
+/** One slide of the track, announced as a slide. */
 export declare function CarouselSlide({ size, className, style, ...props }: CarouselSlideProps): import("react").JSX.Element;

package/dist/components/base/chart/chart.d.ts

@@ -24,7 +24,15 @@ export interface ChartPayloadItem {
     payload?: Record<string, unknown>;
 }
 export interface ChartContainerProps extends Omit<React.ComponentProps<"div">, "children"> {
+    /**
+     * Maps each data key to a label, a colour, and an icon. Each colour becomes
+     * `--color-{key}` on the container.
+     */
     config: ChartConfig;
+    /**
+     * One Recharts chart. `label` and `description` become its `<title>` and `<desc>` unless
+     * it sets its own.
+     */
     children: React.ComponentProps<typeof Recharts.ResponsiveContainer>["children"];
     /**
      * What the chart shows, as a sentence a screen reader can speak ("Monthly revenue against
@@ -34,29 +42,57 @@ export interface ChartContainerProps extends Omit<React.ComponentProps<"div">, "
     /** A longer summary of the data or its takeaway, read after the label. */
     description?: string;
 }
+/**
+ * Recharts on the kit's tokens: Recharts owns geometry, this owns chrome. Each series key
+ * maps to `--color-<key>`, so colours are set once in the config; prefer `var(--chart-1)` …
+ * `var(--chart-5)`, which follow the theme.
+ */
 export declare function ChartContainer({ config, label, description, className, children, style, ...props }: ChartContainerProps): React.JSX.Element;
 export declare const ChartTooltip: typeof Recharts.Tooltip;
 export declare function ChartLegend({ itemSorter, ...props }: React.ComponentProps<typeof Recharts.Legend>): React.JSX.Element;
 export interface ChartTooltipContentProps extends Omit<React.ComponentProps<"div">, "color"> {
-    /** Supplied by Recharts. */
+    /**
+     * Supplied by Recharts. A content component is cloned with it; it never receives it from
+     * you.
+     */
     active?: boolean;
+    /**
+     * The entries under the cursor. Supplied by Recharts, which clones a content component with
+     * them; it never receives them from you.
+     */
     payload?: ChartPayloadItem[];
+    /** The hovered category, supplied by Recharts. `labelKey` and `labelFormatter` change what shows. */
     label?: React.ReactNode;
+    /** Drops the label row. */
     hideLabel?: boolean;
+    /** Drops the swatches. */
     hideIndicator?: boolean;
+    /** Shape of the swatch beside each value. */
     indicator?: "dot" | "line" | "dashed";
-    /** Key in the payload holding each series name. */
+    /** Key in the payload holding each series name, when it is not the data key. */
     nameKey?: string;
-    /** Key in the payload holding the tooltip label. */
+    /** Key in the payload holding the tooltip label, when it is not the data key. */
     labelKey?: string;
+    /** Formats the tooltip's heading — a date key into a readable date. */
     labelFormatter?: (label: React.ReactNode, payload: ChartPayloadItem[]) => React.ReactNode;
+    /** Formats each value. Without it, numbers get locale grouping. */
     formatter?: (value: NonNullable<ChartPayloadItem["value"]>, name: NonNullable<ChartPayloadItem["name"]>, item: ChartPayloadItem, index: number) => React.ReactNode;
 }
+/**
+ * The tooltip body, passed to `ChartTooltip` as its `content`. Names, colours and icons come
+ * from the container's config.
+ */
 export declare function ChartTooltipContent({ active, payload, label, hideLabel, hideIndicator, indicator, nameKey, labelKey, labelFormatter, formatter, className, ...props }: ChartTooltipContentProps): React.JSX.Element | null;
 export interface ChartLegendContentProps extends React.ComponentProps<"div"> {
     /** Supplied by Recharts. */
     payload?: ChartPayloadItem[];
+    /** Drops the swatch, for a legend beside a chart whose colours are already named. */
     hideIcon?: boolean;
+    /** Key in the payload holding each series name, when it is not the data key. */
     nameKey?: string;
 }
+/**
+ * The legend body, passed to `ChartLegend` as its `content`. Names, colours and icons come
+ * from the container's config.
+ */
 export declare function ChartLegendContent({ payload, hideIcon, nameKey, className, ...props }: ChartLegendContentProps): React.JSX.Element | null;

package/dist/components/base/chart/sparkline.d.ts

@@ -9,4 +9,9 @@ export interface SparklineProps extends Omit<React.ComponentProps<"div">, "child
     /** What the shape says. Without it the chart is decorative and hidden from readers. */
     label?: string;
 }
+/**
+ * A trend line with no axes, no grid and no tooltip — the shape of a series beside the figure
+ * it belongs to. Not a small `ChartContainer`: it draws no chrome, so it can sit inside a table
+ * cell or a metric tile.
+ */
 export declare function Sparkline({ data, tone, animated, label, className, ...props }: SparklineProps): import("react").JSX.Element;