react-native-terra-ui 0.13.1 → 0.13.3

package/src/components/image/types.ts

@@ -1,7 +1,15 @@
 import type { RadiusKey, TerraImageProps } from "#theme/types";
 
+/** Width-to-height ratio. A number is used as is; `"3:4"` means 3 wide by 4 tall. */
+export type ImageAspect = number | "1:1" | "3:4" | "16:9";
+
 export interface ImageProps extends TerraImageProps {
   width?: number;
   height?: number;
+  /**
+   * Ratio that derives the missing dimension from the one given. Ignored when
+   * both `width` and `height` are set.
+   */
+  aspect?: ImageAspect;
   radius?: RadiusKey;
 }

package/src/components/image/utils.ts

@@ -0,0 +1,11 @@
+import type { ImageAspect } from "./types";
+
+const PRESET_RATIOS: Record<Exclude<ImageAspect, number>, number> = {
+  "1:1": 1,
+  "3:4": 3 / 4,
+  "16:9": 16 / 9,
+};
+
+export function toAspectRatio(aspect: ImageAspect | undefined) {
+  return typeof aspect === "string" ? PRESET_RATIOS[aspect] : aspect;
+}

package/src/components/input/parts/InputField.tsx

@@ -9,10 +9,10 @@ import { FONT_WEIGHT_VALUE, SYSTEM_FONT } from "#utils/typography";
 import type { InputBaseProps, InputSize } from "../types";
 
 /** Typographic role of the text, per size. */
-const TEXT_VARIANT: Record<InputSize, "body-sm" | "body-md" | "body-lg"> = {
-  sm: "body-sm",
-  md: "body-md",
-  lg: "body-lg",
+const TEXT_VARIANT: Record<InputSize, "subheadline" | "callout" | "body"> = {
+  sm: "subheadline",
+  md: "callout",
+  lg: "body",
 };
 
 /**

package/src/components/surface/Surface.tsx

@@ -64,7 +64,7 @@ const resolveElevation = (variant: SurfaceVariant, elevation?: ElevationKey): El
  * @example
  * ```tsx
  * <Surface variant="raised" elevation="md" p="4" radius="lg">
- *   <Text variant="title-sm">Card title</Text>
+ *   <Text variant="headline">Card title</Text>
  * </Surface>
  * ```
  */

package/src/components/text/Text.tsx

@@ -7,6 +7,7 @@ import type {
   ColorToken,
   FontWeightToken,
   HeadingTextVariant,
+  LegacyTextVariant,
   RoleTextVariant,
   TextVariant,
 } from "#theme/types";
@@ -17,22 +18,40 @@ import { FONT_WEIGHT_VALUE, SYSTEM_FONT } from "#utils/typography";
 export type TextAlign = "left" | "center" | "right" | "justify";
 
 const HEADING_VARIANT_ALIAS: Record<HeadingTextVariant, RoleTextVariant> = {
-  h1: "headline-lg",
-  h2: "headline-md",
-  h3: "headline-sm",
-  h4: "title-lg",
-  h5: "title-md",
-  h6: "title-sm",
+  h1: "large-title",
+  h2: "title-1",
+  h3: "title-2",
+  h4: "title-3",
+  h5: "headline",
+  h6: "callout",
 };
 
+// Pre-0.14 names, mapped to the nearest role on the iOS-style scale. Only the
+// name is aliased; a legacy variant takes the new role's weight and cap.
+const LEGACY_VARIANT_ALIAS: Record<LegacyTextVariant, RoleTextVariant> = {
+  "display-lg": "display",
+  "display-md": "display",
+  "display-sm": "large-title",
+  "headline-lg": "title-1",
+  "headline-md": "title-2",
+  "headline-sm": "title-2",
+  "title-lg": "title-3",
+  "title-md": "headline",
+  "title-sm": "headline",
+  "body-lg": "body",
+  "body-md": "body",
+  "body-sm": "subheadline",
+  caption: "caption-1",
+};
+
+const VARIANT_ALIAS: Record<string, RoleTextVariant> = { ...HEADING_VARIANT_ALIAS, ...LEGACY_VARIANT_ALIAS };
+
 function resolveTextVariant(variant: TextVariant): RoleTextVariant {
-  return variant in HEADING_VARIANT_ALIAS
-    ? HEADING_VARIANT_ALIAS[variant as HeadingTextVariant]
-    : (variant as RoleTextVariant);
+  return VARIANT_ALIAS[variant] ?? (variant as RoleTextVariant);
 }
 
 export interface TextProps extends RNTextProps {
-  /** Typographic role. Defaults to `body-md`. */
+  /** Typographic role. Defaults to `body`. */
   variant?: TextVariant;
   /** Semantic color token (e.g. `text.secondary`, `danger.soft.fg`). */
   color?: ColorToken;
@@ -53,7 +72,7 @@ export interface TextProps extends RNTextProps {
  */
 export const Text = forwardRef<ComponentRef<typeof RNText>, TextProps>(function Text(
   {
-    variant = "body-md",
+    variant = "body",
     color,
     weight,
     align,

package/src/components/toast/Toast.tsx

@@ -187,7 +187,7 @@ const ToastTitle = forwardRef<ComponentRef<typeof Text>, ToastTitleProps>(functi
 export interface ToastDescriptionProps extends TextProps {}
 
 const ToastDescription = forwardRef<ComponentRef<typeof Text>, ToastDescriptionProps>(
-  function ToastDescription({ color, nativeID, variant = "body-sm", ...rest }, ref) {
+  function ToastDescription({ color, nativeID, variant = "subheadline", ...rest }, ref) {
     const { theme } = useUnistyles();
     const { nativeID: rootNativeID, variant: toastVariant } = useToastContext();
     const colors = getToastColors(toastVariant, theme);
@@ -362,7 +362,16 @@ export function DefaultToast({
 
   return (
     <ToastRoot id={id} hide={hide} variant={variant} {...rest}>
-      {shouldRenderIcon ? <Box alignSelf="start">{icon ?? <ToastIcon />}</Box> : null}
+      {/*
+        With a description the icon stays at the top, beside the title rather
+        than the middle of two lines. With a title alone it centres on it: the
+        title's line box is taller than the 20pt icon (a font's ascender and
+        descender add to the line), so pinning it to the top leaves the icon
+        visibly above the text.
+      */}
+      {shouldRenderIcon ? (
+        <Box alignSelf={description ? "start" : "center"}>{icon ?? <ToastIcon />}</Box>
+      ) : null}
       <Box flex={1} gap="0">
         {label ? <ToastTitle>{label}</ToastTitle> : null}
         {description ? <ToastDescription>{description}</ToastDescription> : null}

package/src/components/toolbar/Toolbar.tsx

@@ -207,14 +207,14 @@ function renderLabel(children: ReactNode, tint: ColorToken): ReactNode {
   return Children.map(children, (child) => {
     if (typeof child === "string") {
       return child.trim().length > 0 ? (
-        <Text variant={LABEL_VARIANT} color={tint} weight="bold">
+        <Text variant={LABEL_VARIANT} color={tint} weight="medium">
           {child}
         </Text>
       ) : null;
     }
     if (typeof child === "number") {
       return (
-        <Text variant={LABEL_VARIANT} color={tint} weight="bold">
+        <Text variant={LABEL_VARIANT} color={tint} weight="medium">
           {child}
         </Text>
       );

package/src/theme/tokens/primitives.ts

@@ -375,102 +375,108 @@ export const primitives = {
   // are not physical pixels. Pass them directly to Text without multiplying
   // by PixelRatio or fontScale (native Text handles accessibility scaling).
   // Each role pairs fontSize with an absolute lineHeight, not a ratio.
-  // Line heights use a 4-unit grid; font sizes need not follow that grid.
   //
-  // Font size / line height, listed from lg to sm:
-  // display:  40/48, 36/44, 32/40 — short, prominent hero text.
-  // headline: 28/36, 24/32, 22/28 — page and section headings.
-  // title:    20/28, 18/24, 16/24 — card, list, and navigation titles.
-  // body:     18/28, 16/24, 14/20 — reading text; body-md is Text's default.
-  // label:    16/20, 14/20, 12/16 — short control labels, not paragraphs.
-  // caption:  12/16              — brief supplementary text.
-  // Prefer body sizes for essential information; reserve 12 for compact text.
-  // These are Terra's custom roles, not native platform text-style presets.
+  // Sizes follow the iOS text styles at the Default (Large) Dynamic Type size,
+  // and the role names follow iOS too, so `headline` is the 17pt semibold a
+  // navigation bar or table cell title uses and `large-title` is the 34pt
+  // bold large title. Line heights are the iOS values rounded to an even
+  // number. Weights are what UIKit renders in practice (bold titles), not the
+  // "Regular" the HIG table lists. Tracking is left to the font: SF carries
+  // its own, and a configured custom family can set `letterSpacing` per role.
+  //
+  // Font size / line height:
+  // display:      40/48 — hero text, no iOS equivalent.
+  // large-title:  34/40 — iOS Large Title.
+  // title-1/2/3:  28/34, 22/28, 20/24 — iOS Title 1, Title 2, Title 3.
+  // headline:     17/22 semibold — iOS Headline; compact header bar title.
+  // body:         17/22 — iOS Body; Text's default.
+  // callout:      16/20 — iOS Callout.
+  // subheadline:  15/20 — iOS Subheadline.
+  // footnote:     13/18 — iOS Footnote.
+  // caption-1/2:  12/16, 11/14 — iOS Caption 1, Caption 2.
+  // label-lg/md/sm: 16/20, 15/20, 13/16 medium — control labels; no iOS role.
   //
   // maxFontSizeMultiplier limits accessibility enlargement when scaling is
-  // enabled. The caps below are layout tradeoffs, not accessibility targets.
+  // enabled. Reading roles cap at 2 so text still meets WCAG 1.4.4 at the OS's
+  // 200% setting. Titles cap at 1.5 (iOS itself scales Large Title to 1.76x at
+  // most) and labels at 1.6 because toolbars and chips have fixed heights.
   // RN uses 0 for no cap; Terra Text also accepts a per-instance override.
   // Validate wrapping and clipping at large OS text sizes and with custom fonts.
-  "typography.variants.display-lg.fontSize": 40,
-  "typography.variants.display-lg.lineHeight": 48,
-  "typography.variants.display-lg.fontWeight": "bold",
-  "typography.variants.display-lg.letterSpacing": -1,
-  "typography.variants.display-lg.maxFontSizeMultiplier": 1.2,
-  "typography.variants.display-md.fontSize": 36,
-  "typography.variants.display-md.lineHeight": 44,
-  "typography.variants.display-md.fontWeight": "bold",
-  "typography.variants.display-md.letterSpacing": -0.8,
-  "typography.variants.display-md.maxFontSizeMultiplier": 1.2,
-  "typography.variants.display-sm.fontSize": 32,
-  "typography.variants.display-sm.lineHeight": 40,
-  "typography.variants.display-sm.fontWeight": "bold",
-  "typography.variants.display-sm.letterSpacing": -0.5,
-  "typography.variants.display-sm.maxFontSizeMultiplier": 1.2,
-  "typography.variants.headline-lg.fontSize": 28,
-  "typography.variants.headline-lg.lineHeight": 36,
-  "typography.variants.headline-lg.fontWeight": "semibold",
-  "typography.variants.headline-lg.letterSpacing": -0.3,
-  "typography.variants.headline-lg.maxFontSizeMultiplier": 1.3,
-  "typography.variants.headline-md.fontSize": 24,
-  "typography.variants.headline-md.lineHeight": 32,
-  "typography.variants.headline-md.fontWeight": "semibold",
-  "typography.variants.headline-md.letterSpacing": -0.2,
-  "typography.variants.headline-md.maxFontSizeMultiplier": 1.3,
-  "typography.variants.headline-sm.fontSize": 22,
-  "typography.variants.headline-sm.lineHeight": 28,
-  "typography.variants.headline-sm.fontWeight": "semibold",
-  "typography.variants.headline-sm.letterSpacing": -0.1,
-  "typography.variants.headline-sm.maxFontSizeMultiplier": 1.3,
-  "typography.variants.title-lg.fontSize": 20,
-  "typography.variants.title-lg.lineHeight": 28,
-  "typography.variants.title-lg.fontWeight": "semibold",
-  "typography.variants.title-lg.letterSpacing": 0,
-  "typography.variants.title-lg.maxFontSizeMultiplier": 1.4,
-  "typography.variants.title-md.fontSize": 18,
-  "typography.variants.title-md.lineHeight": 24,
-  "typography.variants.title-md.fontWeight": "semibold",
-  "typography.variants.title-md.letterSpacing": 0,
-  "typography.variants.title-md.maxFontSizeMultiplier": 1.4,
-  "typography.variants.title-sm.fontSize": 16,
-  "typography.variants.title-sm.lineHeight": 24,
-  "typography.variants.title-sm.fontWeight": "semibold",
-  "typography.variants.title-sm.letterSpacing": 0,
-  "typography.variants.title-sm.maxFontSizeMultiplier": 1.4,
-  "typography.variants.body-lg.fontSize": 18,
-  "typography.variants.body-lg.lineHeight": 28,
-  "typography.variants.body-lg.fontWeight": "regular",
-  "typography.variants.body-lg.letterSpacing": 0,
-  "typography.variants.body-lg.maxFontSizeMultiplier": 1.8,
-  "typography.variants.body-md.fontSize": 16,
-  "typography.variants.body-md.lineHeight": 24,
-  "typography.variants.body-md.fontWeight": "regular",
-  "typography.variants.body-md.letterSpacing": 0,
-  "typography.variants.body-md.maxFontSizeMultiplier": 1.8,
-  "typography.variants.body-sm.fontSize": 14,
-  "typography.variants.body-sm.lineHeight": 20,
-  "typography.variants.body-sm.fontWeight": "regular",
-  "typography.variants.body-sm.letterSpacing": 0,
-  "typography.variants.body-sm.maxFontSizeMultiplier": 1.8,
+  "typography.variants.display.fontSize": 40,
+  "typography.variants.display.lineHeight": 48,
+  "typography.variants.display.fontWeight": "bold",
+  "typography.variants.display.letterSpacing": -0.3,
+  "typography.variants.display.maxFontSizeMultiplier": 1.3,
+  "typography.variants.large-title.fontSize": 34,
+  "typography.variants.large-title.lineHeight": 40,
+  "typography.variants.large-title.fontWeight": "bold",
+  "typography.variants.large-title.letterSpacing": -0.3,
+  "typography.variants.large-title.maxFontSizeMultiplier": 1.5,
+  "typography.variants.title-1.fontSize": 28,
+  "typography.variants.title-1.lineHeight": 34,
+  "typography.variants.title-1.fontWeight": "bold",
+  "typography.variants.title-1.letterSpacing": 0,
+  "typography.variants.title-1.maxFontSizeMultiplier": 1.5,
+  "typography.variants.title-2.fontSize": 22,
+  "typography.variants.title-2.lineHeight": 28,
+  "typography.variants.title-2.fontWeight": "bold",
+  "typography.variants.title-2.letterSpacing": 0,
+  "typography.variants.title-2.maxFontSizeMultiplier": 1.5,
+  "typography.variants.title-3.fontSize": 20,
+  "typography.variants.title-3.lineHeight": 24,
+  "typography.variants.title-3.fontWeight": "semibold",
+  "typography.variants.title-3.letterSpacing": 0,
+  "typography.variants.title-3.maxFontSizeMultiplier": 1.5,
+  "typography.variants.headline.fontSize": 17,
+  "typography.variants.headline.lineHeight": 22,
+  "typography.variants.headline.fontWeight": "semibold",
+  "typography.variants.headline.letterSpacing": 0,
+  "typography.variants.headline.maxFontSizeMultiplier": 2,
+  "typography.variants.body.fontSize": 17,
+  "typography.variants.body.lineHeight": 22,
+  "typography.variants.body.fontWeight": "regular",
+  "typography.variants.body.letterSpacing": 0,
+  "typography.variants.body.maxFontSizeMultiplier": 2,
+  "typography.variants.callout.fontSize": 16,
+  "typography.variants.callout.lineHeight": 20,
+  "typography.variants.callout.fontWeight": "regular",
+  "typography.variants.callout.letterSpacing": 0,
+  "typography.variants.callout.maxFontSizeMultiplier": 2,
+  "typography.variants.subheadline.fontSize": 15,
+  "typography.variants.subheadline.lineHeight": 20,
+  "typography.variants.subheadline.fontWeight": "regular",
+  "typography.variants.subheadline.letterSpacing": 0,
+  "typography.variants.subheadline.maxFontSizeMultiplier": 2,
+  "typography.variants.footnote.fontSize": 13,
+  "typography.variants.footnote.lineHeight": 18,
+  "typography.variants.footnote.fontWeight": "regular",
+  "typography.variants.footnote.letterSpacing": 0,
+  "typography.variants.footnote.maxFontSizeMultiplier": 2,
+  "typography.variants.caption-1.fontSize": 12,
+  "typography.variants.caption-1.lineHeight": 16,
+  "typography.variants.caption-1.fontWeight": "regular",
+  "typography.variants.caption-1.letterSpacing": 0,
+  "typography.variants.caption-1.maxFontSizeMultiplier": 2,
+  "typography.variants.caption-2.fontSize": 11,
+  "typography.variants.caption-2.lineHeight": 14,
+  "typography.variants.caption-2.fontWeight": "regular",
+  "typography.variants.caption-2.letterSpacing": 0,
+  "typography.variants.caption-2.maxFontSizeMultiplier": 2,
   "typography.variants.label-lg.fontSize": 16,
   "typography.variants.label-lg.lineHeight": 20,
   "typography.variants.label-lg.fontWeight": "medium",
-  "typography.variants.label-lg.letterSpacing": 0.1,
-  "typography.variants.label-lg.maxFontSizeMultiplier": 1.5,
-  "typography.variants.label-md.fontSize": 14,
+  "typography.variants.label-lg.letterSpacing": 0,
+  "typography.variants.label-lg.maxFontSizeMultiplier": 1.6,
+  "typography.variants.label-md.fontSize": 15,
   "typography.variants.label-md.lineHeight": 20,
   "typography.variants.label-md.fontWeight": "medium",
-  "typography.variants.label-md.letterSpacing": 0.1,
-  "typography.variants.label-md.maxFontSizeMultiplier": 1.5,
-  "typography.variants.label-sm.fontSize": 12,
+  "typography.variants.label-md.letterSpacing": 0,
+  "typography.variants.label-md.maxFontSizeMultiplier": 1.6,
+  "typography.variants.label-sm.fontSize": 13,
   "typography.variants.label-sm.lineHeight": 16,
   "typography.variants.label-sm.fontWeight": "medium",
-  "typography.variants.label-sm.letterSpacing": 0.2,
-  "typography.variants.label-sm.maxFontSizeMultiplier": 1.5,
-  "typography.variants.caption.fontSize": 12,
-  "typography.variants.caption.lineHeight": 16,
-  "typography.variants.caption.fontWeight": "regular",
-  "typography.variants.caption.letterSpacing": 0.2,
-  "typography.variants.caption.maxFontSizeMultiplier": 2,
+  "typography.variants.label-sm.letterSpacing": 0,
+  "typography.variants.label-sm.maxFontSizeMultiplier": 1.6,
 
   // ── component opacity multipliers ─────────────────────────────────────────────────
   "opacity.disabled": 0.45,

package/src/theme/types.ts

@@ -64,6 +64,30 @@ export type ElevationScale = Record<ElevationKey, ElevationStyle>;
 // ─── Typography ──────────────────────────────────────────────────────────────
 
 export type RoleTextVariant =
+  | "display"
+  | "large-title"
+  | "title-1"
+  | "title-2"
+  | "title-3"
+  | "headline"
+  | "body"
+  | "callout"
+  | "subheadline"
+  | "footnote"
+  | "caption-1"
+  | "caption-2"
+  | "label-lg"
+  | "label-md"
+  | "label-sm";
+
+export type HeadingTextVariant = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+
+/**
+ * Pre-0.14 role names. Still accepted by `Text` and resolved onto the iOS-style
+ * scale; removed at 1.0. `label-*` kept its name and is not listed here.
+ * @deprecated Use the {@link RoleTextVariant} it maps to.
+ */
+export type LegacyTextVariant =
   | "display-lg"
   | "display-md"
   | "display-sm"
@@ -76,14 +100,9 @@ export type RoleTextVariant =
   | "body-lg"
   | "body-md"
   | "body-sm"
-  | "label-lg"
-  | "label-md"
-  | "label-sm"
   | "caption";
 
-export type HeadingTextVariant = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
-
-export type TextVariant = RoleTextVariant | HeadingTextVariant;
+export type TextVariant = RoleTextVariant | HeadingTextVariant | LegacyTextVariant;
 
 export type FontWeightToken = "regular" | "medium" | "semibold" | "bold";