themelia-react-ui 1.0.2 → 2.0.0

package/dist/components/primitives/date.d.ts

@@ -7,14 +7,22 @@ export type DateInput = NativeDate | string | number | null | undefined;
 type SpanProps = Omit<ComponentPropsWithoutRef<'span'>, 'children' | 'color'>;
 export type DatePreset = 'compact' | 'short' | 'medium' | 'long';
 export interface DateProps extends SpanProps {
+    /** A native Date, ISO string or millisecond timestamp. Unparseable input renders the empty label. */
     value?: DateInput;
+    /** date-fns pattern; prefer `preset` so a screen stays consistent. */
     format?: string;
+    /** Library preset. Defaults to the provider `dates.format`, then `medium`. */
     preset?: DatePreset;
+    /** date-fns locale. Defaults to the provider `dates.locale`. */
     locale?: Locale;
+    /** Rendered with the shared empty treatment when the value is absent or invalid. Defaults to an em dash. */
     emptyLabel?: ReactNode;
+    /** Text size. Defaults to the provider text size; inside running text, the surrounding size. */
     size?: TextSize;
     align?: TextProps['align'];
+    /** Font weight. Defaults to `regular`; inside running text, the surrounding weight. */
     weight?: TextProps['weight'];
+    /** Colour role. Defaults to `main`; inside running text, the surrounding colour. */
     type?: TextProps['type'];
     ref?: Ref<HTMLSpanElement>;
 }
@@ -40,24 +48,29 @@ export interface DateRangeProps extends Omit<DateProps, 'value'>, DateRangeValue
 export interface RelativeTimeProps extends SpanProps {
     value?: DateInput;
     locale?: Locale;
+    /** Adds "ago"/"in". Defaults to `true`. */
     addSuffix?: boolean;
     includeSeconds?: boolean;
+    /** Rendered with the shared empty treatment when the value is absent or invalid. Defaults to an em dash. */
     emptyLabel?: ReactNode;
+    /** Text size. Defaults to the provider text size; inside running text, the surrounding size. */
     size?: TextSize;
     align?: TextProps['align'];
+    /** Font weight. Defaults to `regular`; inside running text, the surrounding weight. */
     weight?: TextProps['weight'];
+    /** Colour role. Defaults to `secondary` for feeds; inside running text, the surrounding colour. */
     type?: TextProps['type'];
     formatRelativeTime?: (iso: string) => string;
     ref?: Ref<HTMLSpanElement>;
 }
 export declare function parseDateInput(value: DateInput): NativeDate | null;
 export declare function formatDateRange({ from, to }: DateRangeValue, { format, preset, locale, separator, }?: FormatDateRangeOptions): string | null;
-export declare function DatePrimitive({ value, format, preset, locale, emptyLabel, size, align, weight, type, className, ref, ...props }: DateProps): import("react").JSX.Element;
+export declare function DatePrimitive({ value, format, preset, locale, emptyLabel, ...props }: DateProps): import("react").JSX.Element;
 export declare namespace DatePrimitive {
     var displayName: string;
 }
-export declare function Time({ value, format, preset, locale, emptyLabel, size, align, weight, type, className, ref, ...props }: TimeProps): import("react").JSX.Element;
-export declare function DateTime({ value, format, timeFormat, preset, locale, emptyLabel, size, align, weight, type, className, ref, ...props }: DateTimeProps): import("react").JSX.Element;
+export declare function Time({ value, format, preset, locale, emptyLabel, ...props }: TimeProps): import("react").JSX.Element;
+export declare function DateTime({ value, format, timeFormat, preset, locale, emptyLabel, ...props }: DateTimeProps): import("react").JSX.Element;
 export declare function DateRange({ from, to, format, preset, locale, separator, emptyLabel, size, align, weight, type, className, ref, ...props }: DateRangeProps): import("react").JSX.Element;
 export declare function RelativeTime({ value, locale, addSuffix, includeSeconds, emptyLabel, size, align, weight, type, formatRelativeTime, className, ref, ...props }: RelativeTimeProps): import("react").JSX.Element;
 export {};

package/dist/components/primitives/dimensions.d.ts

@@ -18,13 +18,19 @@ export interface DimensionsProps extends SpanProps {
     separator?: ReactNode;
     locale?: string;
     options?: Intl.NumberFormatOptions;
+    /** Rendered with the shared empty treatment when width or height is missing. Defaults to an em dash. */
     emptyLabel?: ReactNode;
+    /** Text size. Defaults to the provider text size; inside running text, the surrounding size. */
     size?: TextSize;
+    /** Text alignment. Defaults to `right` so columns of readings line up. */
     align?: TextProps['align'];
+    /** Font weight. Defaults to `regular`; inside running text, the surrounding weight. */
     weight?: TextProps['weight'];
+    /** Colour role. Defaults to `main`; inside running text, the surrounding colour. */
     type?: TextProps['type'];
     ref?: Ref<HTMLSpanElement>;
 }
 export declare function formatDimensions(width: DimensionPart, height: DimensionPart, { depth, unit, separator, locale, options, }?: FormatDimensionsOptions): string | null;
+/** A width × height (× depth) reading with localized numbers, sans UI font with tabular figures. */
 export declare function Dimensions({ width, height, depth, unit, separator, locale, options, emptyLabel, size, align, weight, type, className, ref, ...props }: DimensionsProps): import("react").JSX.Element;
 export {};

package/dist/components/primitives/duration.d.ts

@@ -11,13 +11,19 @@ export interface DurationProps extends SpanProps {
     unitDisplay?: DurationUnitDisplay;
     minimumFractionDigits?: number;
     maximumFractionDigits?: number;
+    /** Rendered with the shared empty treatment when the value is absent. Defaults to an em dash. */
     emptyLabel?: ReactNode;
+    /** Text size. Defaults to the provider text size; inside running text, the surrounding size. */
     size?: TextSize;
+    /** Text alignment. Defaults to `right` so columns of durations line up. */
     align?: TextProps['align'];
+    /** Font weight. Defaults to `regular`; inside running text, the surrounding weight. */
     weight?: TextProps['weight'];
+    /** Colour role. Defaults to `main`; inside running text, the surrounding colour. */
     type?: TextProps['type'];
     ref?: Ref<HTMLSpanElement>;
 }
+/** An elapsed span in localized units, sans UI font with tabular figures. */
 export declare function Duration({ value, from, locale, maxParts, unitDisplay, minimumFractionDigits, maximumFractionDigits, emptyLabel, size, align, weight, type, className, ref, ...props }: DurationProps): import("react").JSX.Element;
 export { formatDuration } from '../../lib/format';
 export type { DurationUnit, DurationUnitDisplay, FormatDurationOptions } from '../../lib/format';

package/dist/components/primitives/file-size.d.ts

@@ -7,10 +7,15 @@ export interface FileSizeProps extends SpanProps {
     value?: number | null;
     from?: FileSizeUnit;
     locale?: string;
+    /** Rendered with the shared empty treatment when the value is absent or not positive. Defaults to an em dash. */
     emptyLabel?: ReactNode;
+    /** Text size. Defaults to the provider text size; inside running text, the surrounding size. */
     size?: TextSize;
+    /** Text alignment. Defaults to `right` so columns of sizes line up. */
     align?: TextProps['align'];
+    /** Font weight. Defaults to `regular`; inside running text, the surrounding weight. */
     weight?: TextProps['weight'];
+    /** Colour role. Defaults to `main`; inside running text, the surrounding colour. */
     type?: TextProps['type'];
     ref?: Ref<HTMLSpanElement>;
 }
@@ -19,5 +24,6 @@ export interface FileSizeFormatOptions {
     locale?: string;
 }
 export declare function formatFileSize(value?: number | null, options?: FileSizeFormatOptions | string): string | null;
+/** A byte count in the largest readable unit, sans UI font with tabular figures. */
 export declare function FileSize({ value, from, locale, emptyLabel, size, align, weight, type, className, ref, ...props }: FileSizeProps): import("react").JSX.Element;
 export {};

package/dist/components/primitives/index.d.ts

@@ -3,7 +3,7 @@ export { Name, formatName, type NameProps, type NameFormatOptions, } from './nam
 export { Initials, type InitialsProps, } from './initials';
 export { formatInitials, type InitialsFormatOptions, type InitialsStrategy, type InitialsMaxCharacters, } from './initials-format';
 export { Link, Email, Phone, Url, type LinkProps, type EmailProps, type PhoneProps, type UrlProps, } from './link';
-export { Money, type MoneyProps, type MoneyValue, type MoneyUnit, type MoneyLayout, type MoneySecondaryEmphasis, } from './money';
+export { Money, useMoneyFormatter, type MoneyFormatter, type MoneyFormatterOptions, type MoneyProps, type MoneyValue, type MoneyUnit, type MoneyLayout, type MoneySecondaryEmphasis, } from './money';
 export { DatePrimitive as Date, Time, DateTime, DateRange, RelativeTime, formatDateRange, parseDateInput, type DateProps, type TimeProps, type DateTimeProps, type DateRangeProps, type DateRangeValue, type FormatDateRangeOptions, type RelativeTimeProps, type DatePreset, type DateInput, } from './date';
 export { Number, Percent, type NumberProps, type PercentProps, } from './number';
 export { FileSize, formatFileSize, type FileSizeProps, type FileSizeUnit, } from './file-size';

package/dist/components/primitives/initials.d.ts

@@ -11,6 +11,15 @@ export interface InitialsProps extends Omit<ValueProps, 'children'> {
     locale?: string;
     /** Returned when no usable letter or number exists. Defaults to an empty string. */
     fallback?: string;
+    /** Defaults to `inherit`: the avatar or chip that hosts the initials owns their size. */
+    size?: ValueProps['size'];
+    /** Defaults to `inherit`: the host owns the colour, such as an avatar fallback tone. */
+    type?: ValueProps['type'];
+    /** Defaults to `inherit`: the host owns the weight. */
+    weight?: ValueProps['weight'];
 }
-/** Semantic displayed initials for identities and avatar fallbacks. */
-export declare function Initials({ value, strategy, maxCharacters, locale, fallback, size, className, ref, ...props }: InitialsProps): import("react").JSX.Element;
+/**
+ * Semantic displayed initials for identities and avatar fallbacks. They take the
+ * size, colour and weight of the avatar or chip that hosts them.
+ */
+export declare function Initials({ value, strategy, maxCharacters, locale, fallback, size, type, weight, className, ref, ...props }: InitialsProps): import("react").JSX.Element;

package/dist/components/primitives/link.d.ts

@@ -1,9 +1,16 @@
 import { type AnchorHTMLAttributes, type ReactNode, type Ref } from 'react';
 export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
     children?: ReactNode;
+    /** Rendered instead of a dead link when there is nothing to show. Defaults to an em dash. */
     emptyLabel?: ReactNode;
     ref?: Ref<HTMLAnchorElement>;
 }
+/**
+ * Link-coloured inline value. Standalone it uses the provider text size with an
+ * underline on hover. Inside running text it takes the sentence's size, weight
+ * and leading and stays underlined, because colour alone does not set a link
+ * apart from the words around it.
+ */
 export declare function Link({ children, emptyLabel, className, ref, ...props }: LinkProps): import("react").JSX.Element;
 export interface EmailProps extends Omit<LinkProps, 'href' | 'children' | 'ref'> {
     value?: string | null;

package/dist/components/primitives/money.d.ts

@@ -32,21 +32,27 @@ export interface MoneyProps extends SpanProps, MoneyValue {
     ref?: Ref<HTMLElement>;
     /** BCP-47 locale override. Falls back to `UIProvider.formatting.locale`. */
     locale?: string;
-    /** Content rendered when the amount is absent or cannot be parsed. */
+    /** Content rendered, with the shared empty treatment, when the amount is absent or cannot be parsed. */
     emptyLabel?: ReactNode;
-    /** Typography size for both primary and secondary monetary values. */
+    /**
+     * Typography size for the primary value (and a `match` secondary). Defaults to
+     * the provider text size; inside running text, the surrounding size.
+     */
     size?: TextSize;
     /** Inline text alignment. Defaults to right alignment for numeric scanning. */
     align?: TextProps['align'];
-    /** Typography weight for the primary value. */
+    /** Weight of the primary value. Defaults to `medium`; inside running text, the surrounding weight. */
     weight?: TextProps['weight'];
-    /** Primary or secondary semantic text tone. */
+    /** Colour role. Defaults to `main`; inside running text, the surrounding colour. */
     type?: TextProps['type'];
     /** Semantic root element used by the typography primitive. */
     tag?: TextProps['tag'];
-    /** Line-height preset applied to the root value. */
+    /** Line-height preset applied to the root value. Defaults to `normal`; inside running text, the surrounding leading. */
     lineHeight?: TextProps['lineHeight'];
-    /** Applies the typography primitive's monospace numeric treatment. */
+    /**
+     * Opt-in monospace figures. Amounts already render in the sans UI font with
+     * tabular figures; reserve this for code-like ledgers. Defaults to `false`.
+     */
     numeric?: TextProps['numeric'];
     /**
      * Optional converted/display value. Passing it is an explicit request to
@@ -67,6 +73,22 @@ export interface MoneyProps extends SpanProps, MoneyValue {
     /** Inline separator. Defaults to a quiet middle dot; pass an arrow for conversion flows. */
     separator?: ReactNode;
 }
+/** Options for formatting money as text; they mirror the Money primitive's value props. */
+export type MoneyFormatterOptions = Omit<MoneyValue, 'amount'> & {
+    /** BCP-47 locale override. Falls back to `UIProvider.formatting.locale`. */
+    locale?: string;
+    /** Text returned when the amount is absent or cannot be parsed. */
+    emptyLabel?: string;
+};
+/** Formats an amount as text; per-call options win over the hook's defaults. */
+export type MoneyFormatter = (amount: MoneyValue['amount'], options?: MoneyFormatterOptions) => string;
+/**
+ * Text formatting with the Money primitive's rules and UIProvider defaults, for
+ * places that need a string: button labels, toasts, activity text, aria labels.
+ * Pass defaults such as `{ currency: 'USD' }` once for a screen whose amounts
+ * share a currency.
+ */
+export declare function useMoneyFormatter(defaults?: MoneyFormatterOptions): MoneyFormatter;
 /**
  * Canonical monetary display primitive.
  *
@@ -75,5 +97,5 @@ export interface MoneyProps extends SpanProps, MoneyValue {
  * this component instead of composing separate money-display or currency-pair
  * wrappers.
  */
-export declare function Money({ amount, currency, unit, minorUnitScale, symbol, locale, currencyDisplay, minimumFractionDigits, maximumFractionDigits, formatMode, emptyLabel, size, align, weight, type, tag, lineHeight, numeric, secondary, displayMode, layout, secondaryEmphasis, separator, className, ref, ...props }: MoneyProps): import("react").JSX.Element;
+export declare function Money({ amount, currency, unit, minorUnitScale, symbol, locale, currencyDisplay, minimumFractionDigits, maximumFractionDigits, formatMode, emptyLabel, size: sizeProp, align, weight: weightProp, type: typeProp, tag, lineHeight: lineHeightProp, numeric, secondary, displayMode, layout, secondaryEmphasis, separator, className, ref, ...props }: MoneyProps): import("react").JSX.Element;
 export {};

package/dist/components/primitives/number.d.ts

@@ -4,20 +4,37 @@ import type { TextSize } from '../../lib/ui-provider';
 type SpanProps = Omit<ComponentPropsWithoutRef<'span'>, 'children' | 'color'>;
 export interface NumberProps extends SpanProps {
     value?: number | string | null;
+    /** BCP-47 locale override. Falls back to `UIProvider.formatting.locale`. */
     locale?: string;
+    /** Passed to `Intl.NumberFormat`; for example `signDisplay: 'exceptZero'` for deltas. */
     options?: Intl.NumberFormatOptions;
+    /** Rendered with the shared empty treatment when the value is absent or unparsable. Defaults to an em dash. */
     emptyLabel?: ReactNode;
+    /** Text size. Defaults to the provider text size; inside running text, the surrounding size. */
     size?: TextSize;
+    /** Text alignment. Defaults to `right` so columns of figures line up. */
     align?: TextProps['align'];
+    /** Font weight. Defaults to `regular`; inside running text, the surrounding weight. */
     weight?: TextProps['weight'];
+    /** Colour role. Defaults to `main`; inside running text, the surrounding colour. */
     type?: TextProps['type'];
     ref?: Ref<HTMLSpanElement>;
 }
 export interface PercentProps extends Omit<NumberProps, 'options'> {
+    /** The value is already 0–100 rather than a 0–1 ratio. Defaults to `false`. */
     scaled?: boolean;
+    /** Passed to `Intl.NumberFormat` after the percent style and one-decimal default. */
     options?: Intl.NumberFormatOptions;
     ref?: Ref<HTMLSpanElement>;
 }
+/**
+ * A locale-formatted count or quantity in the sans UI font with tabular figures.
+ * Negative values use the typographic minus sign (U+2212).
+ */
 export declare function Number({ value, locale, options, emptyLabel, size, align, weight, type, className, ref, ...props }: NumberProps): import("react").JSX.Element;
+/**
+ * A percentage in the sans UI font with tabular figures. Expects a 0–1 ratio
+ * unless `scaled`; one decimal place by default; negative values use U+2212.
+ */
 export declare function Percent({ value, locale, scaled, options, emptyLabel, size, align, weight, type, className, ref, ...props }: PercentProps): import("react").JSX.Element;
 export {};

package/dist/components/primitives/value-typography.d.ts

@@ -0,0 +1,54 @@
+import type { TextSize } from '../../lib/ui-provider';
+import type { TextProps } from '../typography/text';
+type TextType = NonNullable<TextProps['type']>;
+type TextWeight = NonNullable<TextProps['weight']>;
+type TextLineHeight = NonNullable<TextProps['lineHeight']>;
+/** Typography props a value primitive accepts and passes to `Text`. */
+export interface ValueTypographyProps {
+    size?: TextSize;
+    type?: TextProps['type'];
+    weight?: TextProps['weight'];
+    lineHeight?: TextProps['lineHeight'];
+}
+/** Resolved typography; `undefined` size means the provider default. */
+export interface ValueTypography {
+    size: TextSize | undefined;
+    type: TextType;
+    weight: TextWeight;
+    lineHeight: TextLineHeight | undefined;
+}
+/** Standalone role of a value primitive. */
+export interface ValueTypographyRole {
+    /** Colour role outside running text. */
+    type: TextType;
+    /** Weight outside running text. */
+    weight: TextWeight;
+    /** Size outside running text; the provider default when omitted. */
+    size?: TextSize;
+    /**
+     * Keep the colour role inside running text. Secondary, muted and empty values
+     * stay recessive in a sentence; ordinary values take the sentence colour.
+     */
+    keepType?: boolean;
+    /**
+     * Leading inside running text. Defaults to the surrounding leading. A span in
+     * another font family (monospace) uses `none` so its own ascent and descent
+     * never grow the sentence's line box; the line keeps the sentence leading.
+     */
+    inTextLineHeight?: TextLineHeight;
+}
+/**
+ * Resolves what a value primitive passes to `Text`. Explicit props always win.
+ * Inside running text (a `Text`, `Heading`, label, link or value parent) unset
+ * size, colour, weight and leading inherit the surrounding text, so an SKU or an
+ * amount in a sentence matches the words around it. A standalone value keeps
+ * its role defaults and the provider text size.
+ */
+export declare function useValueTypography(props: ValueTypographyProps, role: ValueTypographyRole): ValueTypography;
+/**
+ * The shared missing-value treatment (`EmptyValue`): secondary colour and a
+ * regular weight at the value's size. An explicit weight is kept; inside
+ * running text the weight follows the sentence.
+ */
+export declare function emptyValueTypography(resolved: ValueTypography, explicitWeight: TextProps['weight']): ValueTypography;
+export {};

package/dist/components/primitives/value.d.ts

@@ -2,22 +2,47 @@ import { type ComponentPropsWithoutRef, type ReactNode, type Ref } from 'react';
 import { type TextProps } from '../typography';
 import type { TextSize } from '../../lib/ui-provider';
 type SpanProps = Omit<ComponentPropsWithoutRef<'span'>, 'children' | 'color'>;
-export type ValueType = Extract<TextProps['type'], 'main' | 'secondary'>;
+/** Value colour roles: foreground, secondary, or the surrounding text colour. */
+export type ValueType = Extract<TextProps['type'], 'main' | 'secondary' | 'inherit'>;
 export interface ValueProps extends SpanProps {
     children?: ReactNode;
+    /** Rendered with the shared empty treatment when children are absent. Defaults to an em dash. */
     emptyLabel?: ReactNode;
+    /**
+     * Text size. A standalone value uses the provider text size; inside running
+     * text (`Text`, `Heading`, labels, links, other values) it inherits the size.
+     */
     size?: TextSize;
     align?: TextProps['align'];
+    /** Font weight. Defaults to the component's role weight; inside running text, the surrounding weight. */
     weight?: TextProps['weight'];
+    /** Colour role. Defaults to the component's role; inside running text `Value` and `MonoValue` take the surrounding colour. */
     type?: ValueType;
     ref?: Ref<HTMLSpanElement>;
 }
-export declare function Value({ children, emptyLabel, size, align, weight, type, className, ref, ...props }: ValueProps): import("react").JSX.Element;
-export declare function SecondaryValue({ children, emptyLabel, size, align, weight, type, className, ref, ...props }: ValueProps): import("react").JSX.Element;
-export declare function MutedValue({ children, emptyLabel, size, align, weight, type, className, ref, ...props }: ValueProps): import("react").JSX.Element;
-export declare function MonoValue({ children, emptyLabel, size, align, weight, type, className, ref, ...props }: ValueProps): import("react").JSX.Element;
+/**
+ * An ordinary displayed fact: foreground, regular weight. Inside running text it
+ * takes the sentence's size, colour and weight.
+ */
+export declare function Value(props: ValueProps): import("react").JSX.Element;
+/** Supporting detail in the secondary colour. Inside running text it keeps the colour and takes the size and weight. */
+export declare function SecondaryValue(props: ValueProps): import("react").JSX.Element;
+/** A note that recedes further than secondary text. */
+export declare function MutedValue(props: ValueProps): import("react").JSX.Element;
+/**
+ * An identifier or code (SKU, reference, tracking number, key) in the monospace
+ * family. Standalone it is foreground medium at the provider size; inside running
+ * text only the family changes, so an SKU in a description matches the words
+ * around it. Amounts and dates belong to the number primitives, which keep the
+ * sans font with tabular figures.
+ */
+export declare function MonoValue(props: ValueProps): import("react").JSX.Element;
 export interface EmptyValueProps extends Omit<ValueProps, 'emptyLabel'> {
     ref?: Ref<HTMLSpanElement>;
 }
-export declare function EmptyValue({ children, size, align, weight, type, className, ref, ...props }: EmptyValueProps): import("react").JSX.Element;
+/**
+ * An intentionally absent value: secondary colour, regular weight. Every value
+ * primitive renders its missing state with this treatment.
+ */
+export declare function EmptyValue({ children, ...props }: EmptyValueProps): import("react").JSX.Element;
 export {};

package/dist/components/typography/heading.d.ts

@@ -5,14 +5,22 @@ export type HeadingTag = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 export type HeadingSize = keyof typeof headingSizes;
 export interface HeadingProps extends HTMLAttributes<HTMLHeadingElement> {
     ref?: Ref<HTMLHeadingElement>;
+    /** Semantic outline level. Defaults to `h3`; it never changes the visual size. */
     tag?: HeadingTag;
-    /** Visual emphasis; semantic tag and the default admin size remain independent. */
+    /**
+     * Visual emphasis, independent of `tag`. Defaults to the compact admin `base`.
+     * `xl` and larger tighten tracking; `2xl` and larger also tighten leading.
+     */
     size?: HeadingSize;
+    /** Secondary line under the title, rendered as secondary `Text`. */
     subHeading?: ReactNode;
     subHeadingClassName?: string;
+    /** Text size of `subHeading`; defaults to the provider text size. */
     subHeadingSize?: TextSize;
     containerClassName?: string;
+    /** Text alignment for the title and sub-heading. Defaults to `left`. */
     align?: keyof typeof textAlignments;
+    /** Adds a bottom rule under the title. Defaults to `false`. */
     divider?: boolean;
 }
 /** Semantic heading levels share Themelia's restrained admin heading scale. */

package/dist/components/typography/label.d.ts

@@ -1,8 +1,11 @@
 import type { LabelHTMLAttributes, ReactNode, Ref } from 'react';
 import type { ComponentScale } from '../../lib/component-vocabulary';
 export interface LabelProps extends Omit<LabelHTMLAttributes<HTMLLabelElement>, 'content'> {
+    /** Fallback content; children take precedence. */
     content?: ReactNode;
+    /** Control scale the caption belongs to (`sm` → xs, `md` → sm, `lg` → base). Defaults to the provider density scale. */
     size?: ComponentScale;
     ref?: Ref<HTMLLabelElement>;
 }
+/** Form caption for a control; medium weight, foreground, no incidental margins. */
 export declare function Label({ content, children, size, className, ref, ...props }: LabelProps): import("react").JSX.Element;

package/dist/components/typography/running-text.d.ts

@@ -0,0 +1,12 @@
+/**
+ * True below an element that renders running text: `Text`, `Heading`,
+ * `DisplayLabel`, `Label`, `TextLink` and the inline value primitives.
+ *
+ * Inline value primitives read it to tell a value inside a sentence from a
+ * standalone value. Inside running text their unset size, colour, weight and
+ * leading inherit from the surrounding text; standalone values keep their role
+ * defaults. Explicit props always win.
+ */
+export declare const RunningTextContext: import("react").Context<boolean>;
+/** Whether the caller renders inside running text owned by a typography role. */
+export declare function useInRunningText(): boolean;

package/dist/components/typography/text-link.d.ts

@@ -1,7 +1,29 @@
 import type { AnchorHTMLAttributes, Ref } from 'react';
 import type { TextProps } from './text';
+/**
+ * Inline-link mechanics shared by `TextLink` and the link primitives. As a flex
+ * or grid item the link hugs its text, so neither the hit area nor the focus
+ * ring stretches across the row. The full-strength ring uses the small radius
+ * role and follows every line of a wrapped link. Links keep one colour whether
+ * or not they were visited: the role colour is explicit.
+ */
+export declare const inlineLinkClassName = "w-fit max-w-full rounded-radius-xs outline-none box-decoration-clone transition-colors motion-reduce:transition-none focus-visible:ring-2 focus-visible:ring-ring";
+/** Underline geometry shared with content links: proportional to the text size. */
+export declare const linkUnderlineClassName = "underline decoration-current underline-offset-[0.2em]";
 export interface TextLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'type'>, Pick<TextProps, 'type' | 'size' | 'weight' | 'align' | 'lineHeight'> {
+    /** Text size. Defaults to the provider text size; inside running text, the surrounding size. */
+    size?: TextProps['size'];
+    /**
+     * Underlined at rest, clearing on hover. Defaults to `true`; keep it for links
+     * whose colour matches the surrounding text. `false` renders no underline and
+     * leaves the hover treatment to the composition (a row, chip or menu).
+     */
     underline?: boolean;
     ref?: Ref<HTMLAnchorElement>;
 }
-export declare function TextLink({ type, size, weight, align, lineHeight, underline, className, ref, ...props }: TextLinkProps): import("react").JSX.Element;
+/**
+ * Native anchor sibling of `Text`: the same roles plus link focus and hover
+ * states. Inside running text an unset size, weight and leading follow the
+ * sentence; the colour role stays, so the link still reads as a link.
+ */
+export declare function TextLink({ type, size, weight, align, lineHeight, underline, className, ref, children, ...props }: TextLinkProps): import("react").JSX.Element;

package/dist/components/typography/text.d.ts

@@ -5,13 +5,25 @@ export interface TextProps extends Omit<ComponentPropsWithoutRef<'p'>, 'children
     /** Plain text fallback; children take precedence, including zero and empty strings. */
     content?: string;
     children?: ReactNode;
+    /** Colour role. Defaults to `main`; `inherit` keeps the surrounding text colour. */
     type?: keyof typeof textTypes;
+    /** Text size. Defaults to the provider `typography.defaultTextSize` (`sm`). */
     size?: TextSize;
+    /** Font weight. Defaults to `regular`; `inherit` keeps the surrounding weight. */
     weight?: keyof typeof textWeights;
+    /** Text alignment. Defaults to `left`; `left` and `right` follow the reading direction. */
     align?: keyof typeof textAlignments;
+    /** Line height. Defaults to `normal`; `inherit` keeps the surrounding leading. */
     lineHeight?: keyof typeof textLineHeights;
+    /** Renders the inverse colour role on inverse surfaces. Defaults to `false`. */
     invert?: boolean;
+    /**
+     * Monospace with tabular figures, for identifiers and code-like values. Numbers,
+     * amounts and dates use the number primitives (tabular sans figures) instead.
+     * Defaults to `false`.
+     */
     numeric?: boolean;
+    /** Rendered element. Defaults to `p`. */
     tag?: 'div' | 'p' | 'span';
 }
 export declare const Text: import("react").ForwardRefExoticComponent<TextProps & import("react").RefAttributes<HTMLElement>>;

package/dist/components/typography/text.styles.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Text roles. `inherit` keeps the surrounding text's role: an inline span inside
+ * a sentence takes its colour, weight or leading instead of resetting them. Colour
+ * uses an explicit inherit utility because anchors otherwise fall back to the
+ * browser link colour without preflight; weight and leading emit no class.
+ */
 export declare const textTypes: {
     readonly main: "text-foreground";
     readonly inverse: "text-inverse-foreground";
@@ -6,6 +12,7 @@ export declare const textTypes: {
     readonly error: "text-destructive";
     readonly success: "text-success";
     readonly primary: "text-primary-accent";
+    readonly inherit: "text-inherit";
 };
 export declare const textSizes: {
     readonly inherit: "[font-size:inherit]";
@@ -17,15 +24,19 @@ export declare const textSizes: {
     readonly lg: "text-lg";
     readonly xl: "text-xl";
 };
-/** Semantic heading level is independent of visual emphasis. No additional theme roots. */
+/**
+ * Semantic heading level is independent of visual emphasis. No additional theme
+ * roots: compact admin sizes keep snug leading; display sizes (xl and up) tighten
+ * tracking and 2xl and up tighten leading so multi-line titles stay one block.
+ */
 export declare const headingSizes: {
-    readonly sm: "text-sm";
-    readonly base: "text-base";
-    readonly lg: "text-lg";
-    readonly xl: "text-xl";
-    readonly '2xl': "text-2xl";
-    readonly '3xl': "text-3xl";
-    readonly '4xl': "text-4xl";
+    readonly sm: "text-sm leading-snug";
+    readonly base: "text-base leading-snug";
+    readonly lg: "text-lg leading-snug";
+    readonly xl: "text-xl leading-snug tracking-tight";
+    readonly '2xl': "text-2xl leading-tight tracking-tight";
+    readonly '3xl': "text-3xl leading-tight tracking-tight";
+    readonly '4xl': "text-4xl leading-tight tracking-tight";
 };
 export declare const textWeights: {
     readonly normal: "font-normal";
@@ -33,11 +44,16 @@ export declare const textWeights: {
     readonly medium: "font-medium";
     readonly semibold: "font-semibold";
     readonly bold: "font-bold";
+    readonly inherit: "";
 };
+/**
+ * `left` and `right` follow the reading direction (start and end), so default
+ * text and right-aligned figures mirror correctly under `dir="rtl"`.
+ */
 export declare const textAlignments: {
-    readonly left: "text-left";
+    readonly left: "text-start";
     readonly center: "text-center";
-    readonly right: "text-right";
+    readonly right: "text-end";
 };
 export declare const textLineHeights: {
     readonly normal: "leading-normal";
@@ -46,13 +62,19 @@ export declare const textLineHeights: {
     readonly tight: "leading-tight";
     readonly snug: "leading-snug";
     readonly none: "leading-none";
+    readonly inherit: "";
 };
+/**
+ * `numeric` is the monospace treatment for identifiers and code-like values
+ * (`font-mono tabular-nums`). Numbers, amounts, dates and durations use the
+ * number primitives, which keep the sans UI font with tabular figures.
+ */
 export declare const textVariants: (props?: ({
-    type?: "primary" | "secondary" | "success" | "main" | "inverse" | "discrete" | "error" | null | undefined;
+    type?: "primary" | "secondary" | "success" | "inherit" | "main" | "inverse" | "discrete" | "error" | null | undefined;
     size?: "sm" | "lg" | "inherit" | "xxs" | "xs" | "pxs" | "base" | "xl" | null | undefined;
-    weight?: "bold" | "normal" | "medium" | "regular" | "semibold" | null | undefined;
+    weight?: "inherit" | "bold" | "normal" | "medium" | "regular" | "semibold" | null | undefined;
     align?: "center" | "left" | "right" | null | undefined;
-    lineHeight?: "none" | "normal" | "loose" | "relaxed" | "tight" | "snug" | null | undefined;
+    lineHeight?: "inherit" | "none" | "normal" | "loose" | "relaxed" | "tight" | "snug" | null | undefined;
     numeric?: boolean | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export declare function resolveTextClassNames(options: Parameters<typeof textVariants>[0] & {

package/dist/components/ui/button.d.ts

@@ -4,7 +4,7 @@ import * as React from 'react';
 /** Internal presentation only; public buttons own the stable tone/style API. */
 export declare const buttonVariants: (props?: ({
     variant?: "secondary" | "destructive" | "default" | "outline" | "ghost" | "link" | null | undefined;
-    size?: "sm" | "lg" | "xs" | "default" | "icon" | "icon-sm" | "icon-lg" | "icon-xs" | null | undefined;
+    size?: "sm" | "lg" | "xs" | "default" | "icon" | "icon-lg" | "icon-sm" | "icon-xs" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export declare namespace Button {
     type Props = ButtonPrimitive.Props & VariantProps<typeof buttonVariants>;

package/dist/components/ui/checkbox.d.ts

@@ -2,5 +2,10 @@ import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox";
 export interface CheckboxProps extends Omit<CheckboxPrimitive.Root.Props, 'onChange'> {
     onCheckedChange?: (checked: boolean | 'indeterminate') => void;
 }
+/**
+ * Raw checkbox recipe. The boundary is the shared `--input` control border
+ * (3:1 on every surface), focus is the shared full-strength ring, and invalid
+ * follows the field-state contract (soft halo, full-strength ring on focus).
+ */
 declare function Checkbox({ className, onCheckedChange, ...props }: CheckboxProps): import("react").JSX.Element;
 export { Checkbox };

package/dist/components/ui/overlay.recipes.d.ts

@@ -1,2 +1,15 @@
-/** One modal scrim recipe; the color comes from the shared semantic token. */
-export declare const modalBackdropRecipe = "fixed inset-0 z-50 bg-(--overlay-backdrop) supports-backdrop-filter:backdrop-blur-sm";
+import * as React from 'react';
+/**
+ * One modal scrim recipe: a plain tint from the shared semantic token. No
+ * backdrop blur — the page behind a modal stays recognisable and the tint alone
+ * separates the surface.
+ */
+export declare const modalBackdropRecipe = "fixed inset-0 z-50 bg-(--overlay-backdrop)";
+/**
+ * Marks which edges of a scrolling modal region are hiding content:
+ * `data-scroll-start` while content is scrolled out above, `data-scroll-end`
+ * while more content remains below. The modal region recipe draws a rule only
+ * on those edges, so a body that fits draws none. Attributes are written to the
+ * node directly, so scrolling never re-renders the region.
+ */
+export declare function useScrollEdges<T extends HTMLElement>(forwardedRef?: React.Ref<T>): React.RefCallback<T>;