themelia-react-ui 1.0.2 → 2.0.1

package/dist/components/layout/page/partials/page-header.d.ts

@@ -1,2 +1,2 @@
 import type { PageHeaderProps } from '../page.types';
-export declare function PageHeader({ title, description, textGap, headingTag, titleIcon: TitleIcon, titleIconHref, onTitleIconClick, titleIconLabel, backHref, onBack, backLabel, titleBadges, actions, slots, renderLink, className, contentClassName, actionsClassName, titleClassName, titleIconClassName, descriptionClassName, }: PageHeaderProps): import("react").JSX.Element;
+export declare function PageHeader({ title, description, textGap, headingTag, titleIcon: TitleIcon, titleIconHref, onTitleIconClick, titleIconLabel, backHref, onBack, backLabel, titleBadges, primaryAction, secondaryActions, moreActionsLabel, tabs, actions, slots, renderLink, className, contentClassName, actionsClassName, titleClassName, titleIconClassName, descriptionClassName, }: PageHeaderProps): import("react").JSX.Element;

package/dist/components/layout/settings/settings.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentType, ReactNode } from 'react';
+import { type PageHeaderAction } from '../../base/navigation/page-header/page-header-commands';
 import { type StringsProp } from '../../../lib/strings';
 import { type LayoutNavigationAdapter } from '../layout.types';
 export interface AsideNavShellStrings {
@@ -45,8 +46,21 @@ export interface AsideNavShellProps extends LayoutNavigationAdapter {
     children?: ReactNode;
     /** Content beside the main settings panel. */
     aside?: ReactNode;
-    /** Controls offered on the surface. */
+    /**
+     * Non-command controls beside the title, such as a scope select. They
+     * render before the role-based commands.
+     */
     actions?: ReactNode;
+    /** The page's one main command: a solid primary button, visible at every width. */
+    primaryAction?: PageHeaderAction;
+    /**
+     * Supporting commands in priority order, as in Page headers: the first two
+     * render as outline buttons before the primary command; the rest, and every
+     * destructive command, move into the More actions menu, which closes the row.
+     */
+    secondaryActions?: readonly PageHeaderAction[];
+    /** Accessible name of the More actions menu trigger. Default: `'More actions'`. */
+    moreActionsLabel?: string;
     /** Content below the body. */
     footer?: ReactNode;
     className?: string;
@@ -58,7 +72,7 @@ export interface AsideNavShellProps extends LayoutNavigationAdapter {
     strings?: StringsProp<AsideNavShellStrings>;
 }
 export type SettingsShellProps = AsideNavShellProps;
-export declare function AsideNavShell({ title, description, groups, currentId, currentPath, children, aside, actions, footer, className, navClassName, contentClassName, renderLink, strings: stringsProp, }: AsideNavShellProps): import("react").JSX.Element;
+export declare function AsideNavShell({ title, description, groups, currentId, currentPath, children, aside, actions, primaryAction, secondaryActions, moreActionsLabel, footer, className, navClassName, contentClassName, renderLink, strings: stringsProp, }: AsideNavShellProps): import("react").JSX.Element;
 export declare namespace AsideNavShell {
     var displayName: string;
 }

package/dist/components/layout/workspace/workspace.types.d.ts

@@ -2,6 +2,7 @@ import type { CSSProperties, HTMLAttributes, MouseEvent, ReactNode } from 'react
 import type { LayoutIconComponent, LayoutNavigationAdapter } from '../layout.types';
 import type { StringsProp } from '../../../lib/strings';
 import type { TextGap } from '../../base/structure';
+import type { PageHeaderAction } from '../../base/navigation/page-header';
 import type { WorkspaceLocaleStripStrings, WorkspaceNavStrings, WorkspaceRecordHeaderStrings } from './workspace.strings';
 export type WorkspaceContentWidth = 'default' | 'wide' | 'full';
 export interface WorkspaceLayoutStyle extends CSSProperties {
@@ -42,7 +43,7 @@ export interface WorkspaceRecordHeaderMetadataItem {
     /** Current value. Controlled. */
     value: ReactNode;
 }
-export interface WorkspaceRecordHeaderProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+export interface WorkspaceRecordHeaderProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'>, LayoutNavigationAdapter {
     /** Title/supporting-copy rhythm. Defaults to dense. */
     textGap?: TextGap;
     /** Surface title. */
@@ -53,10 +54,26 @@ export interface WorkspaceRecordHeaderProps extends Omit<HTMLAttributes<HTMLDivE
     badges?: ReactNode;
     /** Label/value facts under the record title. */
     metadata?: WorkspaceRecordHeaderMetadataItem[];
-    /** Controls offered on the surface. */
+    /**
+     * Non-command controls, such as a locale or period select. They render
+     * before the role-based commands.
+     */
     actions?: ReactNode;
-    /** Lower-emphasis controls beside the primary action. */
-    secondaryActions?: ReactNode;
+    /**
+     * The record's one main command: a solid primary button after the secondary
+     * commands, visible at every width.
+     */
+    primaryAction?: PageHeaderAction;
+    /**
+     * Supporting commands in priority order, as in Page headers: the first two
+     * render as outline buttons before the primary command; the rest, and every
+     * destructive command, move into the More actions menu, which closes the
+     * row. Rendered elements are still accepted for existing headers; pass
+     * command objects instead.
+     */
+    secondaryActions?: ReactNode | readonly PageHeaderAction[];
+    /** Accessible name of the More actions menu trigger. Default: `'More actions'`. */
+    moreActionsLabel?: string;
     /** Current state, shown as a chip. */
     status?: ReactNode;
     /** Illustration or imagery beside the form. */

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/rich-text/index.d.ts

@@ -1,2 +1,2 @@
 export { RichText } from './rich-text';
-export type { RichTextProps } from './rich-text';
+export type { RichTextProps, RichTextImageRendering, RichTextImageAttributes, RenderRichTextImage } from './rich-text';

package/dist/components/typography/rich-text/rich-text-tree.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode } from 'react';
+import type { Root } from 'hast';
+/** An image in sanitized rich text, as handed to `renderImage`. */
+export interface RichTextImageAttributes {
+    /** Source that passed the package image policy (http, https, blob or relative). */
+    src: string;
+    /** Text alternative; empty for a decorative image. */
+    alt: string;
+    title?: string;
+    width?: number;
+    height?: number;
+}
+export type RenderRichTextImage = (image: RichTextImageAttributes) => ReactNode;
+/**
+ * Renders an already sanitized tree as React elements, so each image can be
+ * the consumer's own component (a framework image, a lightbox trigger) while
+ * the surrounding markup keeps its structure. Server and client output match.
+ */
+export declare function renderRichTextTree(tree: Root, renderImage: RenderRichTextImage): ReactNode;

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

@@ -1,6 +1,22 @@
 import type { TextProps } from '../text';
+import { type RenderRichTextImage } from './rich-text-tree';
+export type { RenderRichTextImage, RichTextImageAttributes } from './rich-text-tree';
+/** Image rendering for read-only rich text. */
+export interface RichTextImageRendering {
+    /**
+     * Renders each image, for example with a framework image component. It
+     * receives only sources that passed the package image policy.
+     */
+    renderImage?: RenderRichTextImage;
+}
 export interface RichTextProps extends Omit<TextProps, 'children' | 'content' | 'dangerouslySetInnerHTML'> {
     /** HTML sanitized through the package allowlist before rendering. */
     html?: string | null;
+    /**
+     * Keeps images whose source is a web URL, a `blob:` preview or a relative
+     * path (script and `data:` sources are removed). Pass `renderImage` to draw
+     * each image with your own component. Default: images are removed.
+     */
+    images?: boolean | RichTextImageRendering;
 }
 export declare const RichText: import("react").ForwardRefExoticComponent<RichTextProps & import("react").RefAttributes<HTMLElement>>;

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,30 @@
 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 shared focus edge sits just outside the
+ * glyphs inside the soft halo, 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: string;
+/** 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;