themelia-ui 1.0.3 → 2.0.0

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

@@ -1,9 +1,4 @@
-/**
- * ButtonGroup — adjacent buttons that read as a single control.
- *
- * Collapses the seam between neighbours and squares the inner corners, so a row of
- * outline buttons shows one hairline between them rather than two.
- */
+/** 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"> {
     orientation?: "horizontal" | "vertical";
@@ -11,12 +6,7 @@ export interface ButtonGroupProps extends React.ComponentProps<"div"> {
 export declare function ButtonGroup({ orientation, className, ...props }: ButtonGroupProps): React.JSX.Element;
 export interface ButtonGroupTextProps extends React.ComponentProps<"span"> {
 }
-/**
- * A non-interactive segment inside a group — a unit, a prefix, a count.
- *
- * A `<span>`, deliberately: it is not activatable, so making it a disabled button would
- * put a phantom stop in the tab order and announce a control that does nothing.
- */
+/** A non-interactive segment — 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"> {
     orientation?: "horizontal" | "vertical";

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

@@ -1,9 +1,4 @@
-/**
- * ButtonGroup — adjacent buttons that read as a single control.
- *
- * Collapses the seam between neighbours and squares the inner corners, so a row of
- * outline buttons shows one hairline between them rather than two.
- */
+/** 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"> {
     orientation?: "horizontal" | "vertical";
@@ -11,12 +6,7 @@ export interface ButtonGroupProps extends React.ComponentProps<"div"> {
 export declare function ButtonGroup({ orientation, className, ...props }: ButtonGroupProps): React.JSX.Element;
 export interface ButtonGroupTextProps extends React.ComponentProps<"span"> {
 }
-/**
- * A non-interactive segment inside a group — a unit, a prefix, a count.
- *
- * A `<span>`, deliberately: it is not activatable, so making it a disabled button would
- * put a phantom stop in the tab order and announce a control that does nothing.
- */
+/** A non-interactive segment — 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"> {
     orientation?: "horizontal" | "vertical";

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

@@ -1,14 +1,8 @@
 import { ButtonStyle, ButtonTone } from './button.types.cjs';
 /**
- * Button — the kit's action primitive.
- *
- * Presentation splits along two independent axes, per the component vocabulary:
- * `tone` is semantic colour intent, `buttonStyle` is fill treatment. Keeping them
- * separate is what makes "a destructive ghost button" expressible without a
- * `destructive-ghost` variant, and why the matrix is generated rather than enumerated.
- *
- * Defaults resolve through the provider, so a scope can make every button in a toolbar
- * `ghost` without touching a call site.
+ * 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.
+ * 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"> {
@@ -24,18 +18,17 @@ export interface ButtonProps extends Omit<React.ComponentProps<"button">, "child
      * not resize mid-action.
      */
     loading?: boolean;
-    /** Renders the child element instead of a `button`. */
     /**
-     * The element this button becomes — an anchor, a router link, a label.
-     *
-     * The canonical polymorphic contract (docs/adr/0005). The element is a VALUE, so it can
-     * be built conditionally or defaulted, and `children` keeps meaning the content: the
-     * button's own label wrapper still applies, which was the difference from the retired
-     * `asChild`.
+     * 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.
      *
      *   <Button render={<a href="/settings" />}>Settings</Button>
      */
     render?: React.ReactElement;
     children?: React.ReactNode;
 }
-export declare function Button({ tone, buttonStyle, iconOnly, fullWidth, loading, render, className, disabled, children, ...props }: ButtonProps): React.JSX.Element;
+/**
+ * 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/button.d.ts

@@ -1,14 +1,8 @@
 import { ButtonStyle, ButtonTone } from './button.types.js';
 /**
- * Button — the kit's action primitive.
- *
- * Presentation splits along two independent axes, per the component vocabulary:
- * `tone` is semantic colour intent, `buttonStyle` is fill treatment. Keeping them
- * separate is what makes "a destructive ghost button" expressible without a
- * `destructive-ghost` variant, and why the matrix is generated rather than enumerated.
- *
- * Defaults resolve through the provider, so a scope can make every button in a toolbar
- * `ghost` without touching a call site.
+ * 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.
+ * 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"> {
@@ -24,18 +18,17 @@ export interface ButtonProps extends Omit<React.ComponentProps<"button">, "child
      * not resize mid-action.
      */
     loading?: boolean;
-    /** Renders the child element instead of a `button`. */
     /**
-     * The element this button becomes — an anchor, a router link, a label.
-     *
-     * The canonical polymorphic contract (docs/adr/0005). The element is a VALUE, so it can
-     * be built conditionally or defaulted, and `children` keeps meaning the content: the
-     * button's own label wrapper still applies, which was the difference from the retired
-     * `asChild`.
+     * 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.
      *
      *   <Button render={<a href="/settings" />}>Settings</Button>
      */
     render?: React.ReactElement;
     children?: React.ReactNode;
 }
-export declare function Button({ tone, buttonStyle, iconOnly, fullWidth, loading, render, className, disabled, children, ...props }: ButtonProps): React.JSX.Element;
+/**
+ * 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/button.types.d.cts

@@ -4,10 +4,7 @@ export type ButtonStyle = "solid" | "outline" | "ghost";
 export type ButtonTone = SemanticTone;
 declare module '../../../lib/ui-provider' {
     interface ComponentDefaults {
-        /**
-         * Registered from here rather than in the provider's core type, so adding a
-         * component family never edits `lib/`.
-         */
+        /** Registered here, not in the provider's core type, so adding a family never edits `lib/`. */
         button: {
             tone: ButtonTone;
             buttonStyle: ButtonStyle;

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

@@ -4,10 +4,7 @@ export type ButtonStyle = "solid" | "outline" | "ghost";
 export type ButtonTone = SemanticTone;
 declare module '../../../lib/ui-provider' {
     interface ComponentDefaults {
-        /**
-         * Registered from here rather than in the provider's core type, so adding a
-         * component family never edits `lib/`.
-         */
+        /** Registered here, not in the provider's core type, so adding a family never edits `lib/`. */
         button: {
             tone: ButtonTone;
             buttonStyle: ButtonStyle;

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

@@ -2,36 +2,19 @@ import { StringsProp } from '../../../lib/strings.cjs';
 import { ButtonProps } from './button.cjs';
 import { ButtonLoadingStrings } from './button.strings.cjs';
 /**
- * LoaderButton — a button that owns its pending state.
- *
- * `Button` already takes `loading`; this adds the two things a real async action needs:
- * it can run the handler itself and hold the state, and it announces the wait.
- *
- * `handlesLoading` is accepted for source-kit parity but does nothing here — see below.
+ * LoaderButton — a Button that can run its handler, hold the pending state and announce
+ * the wait. `handlesLoading` is accepted but inert (see the prop).
  */
 import * as React from "react";
 export interface LoaderButtonProps extends Omit<ButtonProps, "onClick"> {
     /** Controlled pending state. Omit to let the button manage it from `onClick`. */
     loading?: boolean;
     /**
-     * Accepted for source-kit compatibility; inert here.
-     *
-     * Upstream a single `Button` upgrades itself into the loading-capable implementation,
-     * and `handlesLoading` is how a caller asks for that upgrade up front — swapping
-     * implementations at the moment of the first press would change the element's
-     * component identity, so React would unmount one and mount the other and the button
-     * would lose focus mid-action.
-     *
-     * This kit splits the two into `Button` and `LoaderButton`, so reaching for
-     * `LoaderButton` IS that decision and there is nothing left for the flag to do. It is
-     * still accepted, and still swallowed rather than spread, so a call site ported from
-     * the source kit keeps working and does not leak an unknown attribute to the DOM.
+     * 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.
      */
     handlesLoading?: boolean;
-    /**
-     * May return a promise. When it does, the button holds its pending state until the
-     * promise settles, so the caller does not have to mirror it in their own state.
-     */
+    /** May return a promise; the button then stays pending until it settles. */
     onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void | Promise<unknown>;
     strings?: StringsProp<ButtonLoadingStrings>;
 }

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

@@ -2,36 +2,19 @@ import { StringsProp } from '../../../lib/strings.js';
 import { ButtonProps } from './button.js';
 import { ButtonLoadingStrings } from './button.strings.js';
 /**
- * LoaderButton — a button that owns its pending state.
- *
- * `Button` already takes `loading`; this adds the two things a real async action needs:
- * it can run the handler itself and hold the state, and it announces the wait.
- *
- * `handlesLoading` is accepted for source-kit parity but does nothing here — see below.
+ * LoaderButton — a Button that can run its handler, hold the pending state and announce
+ * the wait. `handlesLoading` is accepted but inert (see the prop).
  */
 import * as React from "react";
 export interface LoaderButtonProps extends Omit<ButtonProps, "onClick"> {
     /** Controlled pending state. Omit to let the button manage it from `onClick`. */
     loading?: boolean;
     /**
-     * Accepted for source-kit compatibility; inert here.
-     *
-     * Upstream a single `Button` upgrades itself into the loading-capable implementation,
-     * and `handlesLoading` is how a caller asks for that upgrade up front — swapping
-     * implementations at the moment of the first press would change the element's
-     * component identity, so React would unmount one and mount the other and the button
-     * would lose focus mid-action.
-     *
-     * This kit splits the two into `Button` and `LoaderButton`, so reaching for
-     * `LoaderButton` IS that decision and there is nothing left for the flag to do. It is
-     * still accepted, and still swallowed rather than spread, so a call site ported from
-     * the source kit keeps working and does not leak an unknown attribute to the DOM.
+     * 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.
      */
     handlesLoading?: boolean;
-    /**
-     * May return a promise. When it does, the button holds its pending state until the
-     * promise settles, so the caller does not have to mirror it in their own state.
-     */
+    /** May return a promise; the button then stays pending until it settles. */
     onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void | Promise<unknown>;
     strings?: StringsProp<ButtonLoadingStrings>;
 }

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

@@ -1,11 +1,7 @@
 import { ButtonProps } from './button.cjs';
 /**
- * TextButton — a button that reads as a link.
- *
- * A button, not an anchor, because it acts on this page. The distinction matters more
- * than the styling: a screen reader announces "button" versus "link", and a keyboard user
- * expects Space to activate one and not the other. Anything that navigates should be a
- * real anchor even when it looks identical.
+ * 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">;

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

@@ -1,11 +1,7 @@
 import { ButtonProps } from './button.js';
 /**
- * TextButton — a button that reads as a link.
- *
- * A button, not an anchor, because it acts on this page. The distinction matters more
- * than the styling: a screen reader announces "button" versus "link", and a keyboard user
- * expects Space to activate one and not the other. Anything that navigates should be a
- * real anchor even when it looks identical.
+ * 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">;

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

@@ -1,15 +1,15 @@
 import { TooltipContent } from '../tooltip/index.cjs';
 import { ButtonProps } from './button.cjs';
 /**
- * TooltipButton — an icon button with its name in a tooltip.
- *
- * The tooltip text is ALSO the accessible name, which is the point: an icon-only button
- * with a hover tooltip and no `aria-label` is unnamed to everyone not using a mouse, and
- * that is the commonest way an icon button becomes unusable.
+ * TooltipButton — a button with a tooltip. For an icon-only button the tooltip text is
+ * also the accessible name, so it isn't unnamed to non-mouse users.
  */
 import * as React from "react";
 export interface TooltipButtonProps extends ButtonProps {
-    /** Shown on hover and focus, and used as the accessible name. */
+    /**
+     * 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.
+     */
     tooltip: string;
     /** Where the tooltip opens. */
     side?: React.ComponentProps<typeof TooltipContent>["side"];

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

@@ -1,15 +1,15 @@
 import { TooltipContent } from '../tooltip/index.js';
 import { ButtonProps } from './button.js';
 /**
- * TooltipButton — an icon button with its name in a tooltip.
- *
- * The tooltip text is ALSO the accessible name, which is the point: an icon-only button
- * with a hover tooltip and no `aria-label` is unnamed to everyone not using a mouse, and
- * that is the commonest way an icon button becomes unusable.
+ * TooltipButton — a button with a tooltip. For an icon-only button the tooltip text is
+ * also the accessible name, so it isn't unnamed to non-mouse users.
  */
 import * as React from "react";
 export interface TooltipButtonProps extends ButtonProps {
-    /** Shown on hover and focus, and used as the accessible name. */
+    /**
+     * 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.
+     */
     tooltip: string;
     /** Where the tooltip opens. */
     side?: React.ComponentProps<typeof TooltipContent>["side"];

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

@@ -16,10 +16,7 @@ export interface CardPrimaryActionProps extends ComponentProps<"a"> {
     label: string;
 }
 /**
- * Makes a whole card one target.
- *
- * A covering link rather than a wrapping one: wrapping the card in an anchor nests its
- * buttons and menus inside it, which is invalid and makes them unreachable. This sits
- * behind the content, and anything interactive is lifted above it in CSS.
+ * 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.
  */
 export declare function CardPrimaryAction({ label, className, ...props }: CardPrimaryActionProps): import("react").JSX.Element;

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

@@ -16,10 +16,7 @@ export interface CardPrimaryActionProps extends ComponentProps<"a"> {
     label: string;
 }
 /**
- * Makes a whole card one target.
- *
- * A covering link rather than a wrapping one: wrapping the card in an anchor nests its
- * buttons and menus inside it, which is invalid and makes them unreachable. This sits
- * behind the content, and anything interactive is lifted above it in CSS.
+ * 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.
  */
 export declare function CardPrimaryAction({ label, className, ...props }: CardPrimaryActionProps): import("react").JSX.Element;

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

@@ -1,7 +1,10 @@
 import { ComponentProps } from 'react';
 import { CardSurface } from './card.types.cjs';
 export interface CardSkeletonProps extends Omit<ComponentProps<"div">, "title"> {
-    /** Match the real card, or the placeholder is the wrong shape. */
+    /**
+     * Match the real card's surface. Unset, it takes the card's default (the provider's
+     * `defaults.card.surface`, framed out of the box).
+     */
     surface?: CardSurface;
     /** Reserves the header's height. */
     showHeader?: boolean;

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

@@ -1,7 +1,10 @@
 import { ComponentProps } from 'react';
 import { CardSurface } from './card.types.js';
 export interface CardSkeletonProps extends Omit<ComponentProps<"div">, "title"> {
-    /** Match the real card, or the placeholder is the wrong shape. */
+    /**
+     * Match the real card's surface. Unset, it takes the card's default (the provider's
+     * `defaults.card.surface`, framed out of the box).
+     */
     surface?: CardSurface;
     /** Reserves the header's height. */
     showHeader?: boolean;

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

@@ -1,14 +1,8 @@
 import { CardStrings } from './card.strings.cjs';
 import { CardAction, CardAlertTone, CardSurface } from './card.types.cjs';
 /**
- * Card — the single surface primitive.
- *
- * Every framed region in the kit is a Card. Nothing else grows card-shaped chrome, because
- * a parallel wrapper is how two "cards" end up with different radii and shadows.
- *
- * Slot-driven rather than composed: `title`, `description`, `actions`, `footerText` cover
- * the shape almost every card takes, so the common case is props rather than six nested
- * elements. The regions are exported too, for a card that genuinely needs composing.
+ * Card — the single surface primitive. Slot props (`title`, `description`, `actions`,
+ * `footerText`, …) cover the common shape; the regions are exported for composing.
  */
 import * as React from "react";
 export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
@@ -18,11 +12,8 @@ export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
     /** Badges, status, or counts immediately after the title. */
     titleSuffix?: React.ReactNode;
     /**
-     * Explanatory copy behind an info affordance on the title line.
-     *
-     * For the sentence that would make the description too long — a definition, a caveat,
-     * how a number was arrived at. It is a real focusable control, not a title attribute,
-     * so a keyboard reader can reach it.
+     * Explanatory copy behind a focusable info button on the title line — for a definition or
+     * caveat too long for the description.
      */
     tooltip?: React.ReactNode;
     description?: React.ReactNode;
@@ -36,6 +27,13 @@ export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
     headerAction?: React.ReactNode;
     /** Overflow commands, collapsed into one menu trigger. */
     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.
+     */
+    titleLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** A full-bleed strip above the header — a cover image, an illustration, a preview. */
+    media?: React.ReactNode;
     /** Banner between header and content. A plain string is wrapped for you. */
     alert?: React.ReactNode;
     alertTone?: CardAlertTone;
@@ -47,13 +45,9 @@ export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
     footerSlot?: React.ReactNode;
     headerDivider?: boolean;
     footerDivider?: boolean;
-    /** Clips the content to a collapsed height with a fade, and adds a toggle. */
     /**
-     * Clips content to a collapsed height with a fade, and adds a toggle.
-     *
-     * The object form sets the height for this card only; the bare `true` uses
-     * `--card-collapsed-height`. A fixed token is right for a grid of equal cards and
-     * wrong for one card whose natural fold is somewhere else.
+     * Clips content to a collapsed height with a fade, and adds a toggle. `true` uses
+     * `--card-collapsed-height`; the object form sets the height for this card only.
      */
     expandable?: boolean | {
         collapsedMaxHeight?: number | string;
@@ -64,4 +58,4 @@ export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
     /** Overrides this card's own copy — the info glyph, the overflow trigger, the disclosure. */
     strings?: Partial<CardStrings>;
 }
-export declare function Card({ icon, title, titleSuffix, tooltip, description, surface, headerStart, headerEnd, headerAction, actions, alert, alertTone, contentTop, contentBottom, footerText, footerSlot, headerDivider, footerDivider, expandable, expanded, defaultExpanded, onExpandedChange, strings, className, children, ...props }: CardProps): React.JSX.Element;
+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/card.d.ts

@@ -1,14 +1,8 @@
 import { CardStrings } from './card.strings.js';
 import { CardAction, CardAlertTone, CardSurface } from './card.types.js';
 /**
- * Card — the single surface primitive.
- *
- * Every framed region in the kit is a Card. Nothing else grows card-shaped chrome, because
- * a parallel wrapper is how two "cards" end up with different radii and shadows.
- *
- * Slot-driven rather than composed: `title`, `description`, `actions`, `footerText` cover
- * the shape almost every card takes, so the common case is props rather than six nested
- * elements. The regions are exported too, for a card that genuinely needs composing.
+ * Card — the single surface primitive. Slot props (`title`, `description`, `actions`,
+ * `footerText`, …) cover the common shape; the regions are exported for composing.
  */
 import * as React from "react";
 export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
@@ -18,11 +12,8 @@ export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
     /** Badges, status, or counts immediately after the title. */
     titleSuffix?: React.ReactNode;
     /**
-     * Explanatory copy behind an info affordance on the title line.
-     *
-     * For the sentence that would make the description too long — a definition, a caveat,
-     * how a number was arrived at. It is a real focusable control, not a title attribute,
-     * so a keyboard reader can reach it.
+     * Explanatory copy behind a focusable info button on the title line — for a definition or
+     * caveat too long for the description.
      */
     tooltip?: React.ReactNode;
     description?: React.ReactNode;
@@ -36,6 +27,13 @@ export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
     headerAction?: React.ReactNode;
     /** Overflow commands, collapsed into one menu trigger. */
     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.
+     */
+    titleLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** A full-bleed strip above the header — a cover image, an illustration, a preview. */
+    media?: React.ReactNode;
     /** Banner between header and content. A plain string is wrapped for you. */
     alert?: React.ReactNode;
     alertTone?: CardAlertTone;
@@ -47,13 +45,9 @@ export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
     footerSlot?: React.ReactNode;
     headerDivider?: boolean;
     footerDivider?: boolean;
-    /** Clips the content to a collapsed height with a fade, and adds a toggle. */
     /**
-     * Clips content to a collapsed height with a fade, and adds a toggle.
-     *
-     * The object form sets the height for this card only; the bare `true` uses
-     * `--card-collapsed-height`. A fixed token is right for a grid of equal cards and
-     * wrong for one card whose natural fold is somewhere else.
+     * Clips content to a collapsed height with a fade, and adds a toggle. `true` uses
+     * `--card-collapsed-height`; the object form sets the height for this card only.
      */
     expandable?: boolean | {
         collapsedMaxHeight?: number | string;
@@ -64,4 +58,4 @@ export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
     /** Overrides this card's own copy — the info glyph, the overflow trigger, the disclosure. */
     strings?: Partial<CardStrings>;
 }
-export declare function Card({ icon, title, titleSuffix, tooltip, description, surface, headerStart, headerEnd, headerAction, actions, alert, alertTone, contentTop, contentBottom, footerText, footerSlot, headerDivider, footerDivider, expandable, expanded, defaultExpanded, onExpandedChange, strings, className, children, ...props }: CardProps): React.JSX.Element;
+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/partials/card-header.d.cts

@@ -1,12 +1,9 @@
 import * as React from "react";
 /**
- * The header region.
- *
- * A single row of title-line content with trailing controls pushed to the end, plus an
- * optional full-width row above it. The title truncates rather than pushing the controls
- * off the row — a header that reflows when a name gets longer is the usual failure.
+ * The header region: a title row with trailing controls, plus an optional full-width row
+ * above. The title truncates rather than pushing the controls off the row.
  */
-export declare function CardHeader({ icon, title, titleSuffix, tooltip, tooltipLabel, description, headerStart, headerEnd, headerAction, divider, className, ...props }: Omit<React.ComponentProps<"div">, "title"> & {
+export declare function CardHeader({ icon, title, titleSuffix, tooltip, tooltipLabel, description, headerStart, headerEnd, headerAction, divider, titleLevel, className, ...props }: Omit<React.ComponentProps<"div">, "title"> & {
     icon?: React.ReactNode;
     title?: React.ReactNode;
     titleSuffix?: React.ReactNode;
@@ -17,4 +14,6 @@ export declare function CardHeader({ icon, title, titleSuffix, tooltip, tooltipL
     headerEnd?: React.ReactNode;
     headerAction?: React.ReactNode;
     divider?: boolean;
+    /** Renders the title as a heading of this level. See `CardProps.titleLevel`. */
+    titleLevel?: 1 | 2 | 3 | 4 | 5 | 6;
 }): React.JSX.Element;

package/dist/components/base/cards/partials/card-header.d.ts

@@ -1,12 +1,9 @@
 import * as React from "react";
 /**
- * The header region.
- *
- * A single row of title-line content with trailing controls pushed to the end, plus an
- * optional full-width row above it. The title truncates rather than pushing the controls
- * off the row — a header that reflows when a name gets longer is the usual failure.
+ * The header region: a title row with trailing controls, plus an optional full-width row
+ * above. The title truncates rather than pushing the controls off the row.
  */
-export declare function CardHeader({ icon, title, titleSuffix, tooltip, tooltipLabel, description, headerStart, headerEnd, headerAction, divider, className, ...props }: Omit<React.ComponentProps<"div">, "title"> & {
+export declare function CardHeader({ icon, title, titleSuffix, tooltip, tooltipLabel, description, headerStart, headerEnd, headerAction, divider, titleLevel, className, ...props }: Omit<React.ComponentProps<"div">, "title"> & {
     icon?: React.ReactNode;
     title?: React.ReactNode;
     titleSuffix?: React.ReactNode;
@@ -17,4 +14,6 @@ export declare function CardHeader({ icon, title, titleSuffix, tooltip, tooltipL
     headerEnd?: React.ReactNode;
     headerAction?: React.ReactNode;
     divider?: boolean;
+    /** Renders the title as a heading of this level. See `CardProps.titleLevel`. */
+    titleLevel?: 1 | 2 | 3 | 4 | 5 | 6;
 }): React.JSX.Element;

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

@@ -26,14 +26,6 @@ export interface CarouselDotsProps extends ComponentProps<"div"> {
 }
 /** The position indicators, placed by the caller. */
 export declare function CarouselDots({ dotStyle, className, ...props }: CarouselDotsProps): import("react").JSX.Element;
-/**
- * The compound parts.
- *
- * `Carousel` with children is the whole story for most cases. These exist for a track
- * whose controls belong somewhere the single component cannot put them — beside a
- * heading, in a card footer — and they read the same context, so the two APIs cannot
- * disagree about which slide is current.
- */
 export interface CarouselSlideProps extends ComponentProps<"div"> {
     /** Track width this slide occupies — "100%", "50%", "18rem". */
     size?: string;

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

@@ -26,14 +26,6 @@ export interface CarouselDotsProps extends ComponentProps<"div"> {
 }
 /** The position indicators, placed by the caller. */
 export declare function CarouselDots({ dotStyle, className, ...props }: CarouselDotsProps): import("react").JSX.Element;
-/**
- * The compound parts.
- *
- * `Carousel` with children is the whole story for most cases. These exist for a track
- * whose controls belong somewhere the single component cannot put them — beside a
- * heading, in a card footer — and they read the same context, so the two APIs cannot
- * disagree about which slide is current.
- */
 export interface CarouselSlideProps extends ComponentProps<"div"> {
     /** Track width this slide occupies — "100%", "50%", "18rem". */
     size?: string;

package/dist/components/base/carousel/carousel.strings.d.cts

@@ -6,12 +6,7 @@ export interface CarouselStrings {
     next: string;
     /** Accessible name for a pagination dot, by the slide it jumps to. */
     goToSlide: (index: number) => string;
-    /**
-     * What the region and each slide ARE, announced before their name.
-     *
-     * `aria-roledescription` is read aloud, so it is copy — it was the one accessible
-     * string in this family still written into the markup as English.
-     */
+    /** What the region and each slide are (`aria-roledescription`), announced before their name. */
     roleDescription: string;
     slideRoleDescription: string;
 }

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

@@ -6,12 +6,7 @@ export interface CarouselStrings {
     next: string;
     /** Accessible name for a pagination dot, by the slide it jumps to. */
     goToSlide: (index: number) => string;
-    /**
-     * What the region and each slide ARE, announced before their name.
-     *
-     * `aria-roledescription` is read aloud, so it is copy — it was the one accessible
-     * string in this family still written into the markup as English.
-     */
+    /** What the region and each slide are (`aria-roledescription`), announced before their name. */
     roleDescription: string;
     slideRoleDescription: string;
 }