@duro-app/ui 5.20.0 → 5.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "5.20.0",
+  "version": "5.21.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -92,7 +92,7 @@
   "dependencies": {
     "@tanstack/react-virtual": "^3.14.13",
     "qrcode": "^1.5.4",
-    "@duro-app/tokens": "^5.20.0"
+    "@duro-app/tokens": "^5.21.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/Heading/Heading.meta.ts

@@ -2,11 +2,12 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Semantic heading element (h1-h6) with typography presets. Always use the correct level for document hierarchy. Visual size can differ from semantic level via the variant prop.',
+    'Semantic heading element (h1-h6) with typography presets. Always use the correct level for document hierarchy. The look is `variant` (heading, display, overline) and its size is `size` (sm, md, lg, xl), both independent of the semantic level. The old combined variants (headingSm, displayLg, …) still work and are deprecated.',
   whenToUse: [
     'Page titles (level 1)',
     'Section headers (level 2-3)',
     'Card or panel titles (level 3-4)',
+    'Group titles over a list of rows or a form section (level 3-4, variant="overline", any size)',
   ],
   whenNotToUse: [
     'Body text — use Text',
@@ -22,7 +23,9 @@ export const meta: ComponentMeta = {
   ],
   example: `<Stack gap="md">
   <Heading level={1}>Page Title</Heading>
-  <Heading level={2} variant="headingMd">Section</Heading>
-  <Heading level={3}>Subsection</Heading>
+  <Heading level={2} size="md">Section</Heading>
+  <Heading level={1} variant="display" size="lg">Hero</Heading>
+  <Heading level={3} variant="overline" color="muted">Group</Heading>
+  <Heading level={2} variant="overline" size="lg">Large group</Heading>
 </Stack>`,
 }

package/src/components/Heading/Heading.stories.tsx

@@ -49,3 +49,48 @@ export const WithId: Story = {
     await expect(canvas.getByRole('link', {name: 'Install'})).toHaveAttribute('href', '#install')
   },
 }
+
+/** `variant` is the look and `size` its size, independent of the level: a group title over a
+ *  list of rows is an `overline` heading, at any size. */
+export const Overline: Story = {
+  render: () => (
+    <Stack gap="xs">
+      <Heading level={3} variant="overline" color="muted">
+        Today
+      </Heading>
+      <Heading level={3} variant="overline" size="md" color="muted">
+        Earlier
+      </Heading>
+      <Heading level={2} variant="overline" size="lg">
+        Archive
+      </Heading>
+    </Stack>
+  ),
+  play: async ({canvas}) => {
+    await expect(canvas.getByRole('heading', {level: 3, name: 'Today'})).toBeInTheDocument()
+    await expect(canvas.getAllByRole('heading', {level: 3})).toHaveLength(2)
+    const sm = getComputedStyle(canvas.getByRole('heading', {name: 'Today'})).fontSize
+    const lg = getComputedStyle(canvas.getByRole('heading', {name: 'Archive'})).fontSize
+    await expect(parseFloat(lg)).toBeGreaterThan(parseFloat(sm))
+  },
+}
+
+/** The old combined variants still render the same preset as the two props. */
+export const LegacyVariant: Story = {
+  render: () => (
+    <Stack gap="xs">
+      <Heading level={2} variant="headingSm">
+        Legacy
+      </Heading>
+      <Heading level={2} variant="heading" size="sm">
+        Current
+      </Heading>
+    </Stack>
+  ),
+  play: async ({canvas}) => {
+    const legacy = getComputedStyle(canvas.getByRole('heading', {name: 'Legacy'}))
+    const current = getComputedStyle(canvas.getByRole('heading', {name: 'Current'}))
+    await expect(legacy.fontSize).toBe(current.fontSize)
+    await expect(legacy.fontWeight).toBe(current.fontWeight)
+  },
+}

package/src/components/Heading/Heading.tsx

@@ -3,7 +3,12 @@ import {html} from 'react-strict-dom'
 import {typePresets} from '@duro-app/tokens/tokens/type-presets.css'
 import {styles} from './styles.css'
 
-export type HeadingVariant =
+/** The heading's look; its size is the `size` prop. */
+export type HeadingFamily = 'heading' | 'display' | 'overline'
+export type HeadingSize = 'sm' | 'md' | 'lg' | 'xl'
+
+/** @deprecated Use `variant` with `size`: `headingSm` is `variant="heading" size="sm"`. */
+export type HeadingLegacyVariant =
   | 'displayLg'
   | 'displayMd'
   | 'displaySm'
@@ -12,9 +17,14 @@ export type HeadingVariant =
   | 'headingMd'
   | 'headingSm'
 
+export type HeadingVariant = HeadingFamily | HeadingLegacyVariant
+
 interface HeadingProps {
   level: 1 | 2 | 3 | 4 | 5 | 6
+  /** The look: `heading` (default), `display` (fluid hero titles), `overline` (small uppercase group titles). */
   variant?: HeadingVariant
+  /** The size within the look. Default: the level's size for `heading`, `md` for `display`, `sm` for `overline`; `display` and `overline` stop at `lg`. */
+  size?: HeadingSize
   color?: 'default' | 'muted' | 'accent'
   align?: 'start' | 'center' | 'end'
   /** The heading's id: an in-page link's target (`href="#id"`), an `aria-labelledby` reference. */
@@ -22,13 +32,32 @@ interface HeadingProps {
   children: ReactNode
 }
 
-const defaultVariantMap: Record<number, HeadingVariant> = {
-  1: 'headingXl',
-  2: 'headingLg',
-  3: 'headingMd',
-  4: 'headingSm',
-  5: 'headingSm',
-  6: 'headingSm',
+type Preset = keyof typeof typePresets
+
+const levelSize: Record<HeadingProps['level'], HeadingSize> = {
+  1: 'xl',
+  2: 'lg',
+  3: 'md',
+  4: 'sm',
+  5: 'sm',
+  6: 'sm',
+}
+
+const presets = {
+  heading: {sm: 'headingSm', md: 'headingMd', lg: 'headingLg', xl: 'headingXl'},
+  display: {sm: 'displaySm', md: 'displayMd', lg: 'displayLg'},
+  overline: {sm: 'overline', md: 'overlineMd', lg: 'overlineLg'},
+} as const satisfies Record<HeadingFamily, Partial<Record<HeadingSize, Preset>>>
+
+function presetOf(
+  level: HeadingProps['level'],
+  variant: HeadingVariant = 'heading',
+  size?: HeadingSize,
+): Preset {
+  if (variant === 'heading') return presets.heading[size ?? levelSize[level]]
+  if (variant === 'display') return presets.display[size === 'xl' ? 'lg' : (size ?? 'md')]
+  if (variant === 'overline') return presets.overline[size === 'xl' ? 'lg' : (size ?? 'sm')]
+  return variant
 }
 
 const alignMap = {
@@ -37,9 +66,20 @@ const alignMap = {
   end: styles.alignEnd,
 } as const
 
-export function Heading({level, variant, color = 'default', align, id, children}: HeadingProps) {
-  const resolvedVariant = variant ?? defaultVariantMap[level]
-  const style = [typePresets[resolvedVariant], styles[color], align && alignMap[align]]
+export function Heading({
+  level,
+  variant,
+  size,
+  color = 'default',
+  align,
+  id,
+  children,
+}: HeadingProps) {
+  const style = [
+    typePresets[presetOf(level, variant, size)],
+    styles[color],
+    align && alignMap[align],
+  ]
 
   if (level === 1)
     return (

package/src/components/Text/Text.meta.ts

@@ -6,10 +6,10 @@ export const meta: ComponentMeta = {
   whenToUse: [
     'Body text (paragraphs, descriptions)',
     'UI labels and metadata',
-    'Captions, code snippets, overlines',
+    'Captions, code snippets, and overline eyebrows above a Heading',
   ],
   whenNotToUse: [
-    'Page or section titles — use Heading',
+    'Page, section or group titles — use Heading, even in overline style (variant="overline")',
     'Form field labels — use Field.Label (auto-binds to form)',
   ],
   relatedTo: [

package/src/docs/Typography.mdx

@@ -55,12 +55,15 @@ Presets compose scale tokens + weight + tracking into named styles via `typePres
 
 ### Heading
 
-| Preset      | Size  | Weight   | Tracking |
-| ----------- | ----- | -------- | -------- |
-| `headingSm` | 20/28 | Semibold | Tight    |
-| `headingMd` | 24/32 | Semibold | Tight    |
-| `headingLg` | 30/36 | Bold     | Tight    |
-| `headingXl` | 36/44 | Bold     | Tight    |
+| Preset      | Size  | Weight   | Tracking                                                 |
+| ----------- | ----- | -------- | -------------------------------------------------------- |
+| `headingSm` | 20/28 | Semibold | Tight                                                    |
+| `headingMd` | 24/32 | Semibold | Tight                                                    |
+| `headingLg` | 30/36 | Bold     | Tight                                                    |
+| `headingXl` | 36/44 | Bold     | Tight                                                    |
+| `overline`  | 12/16 | Semibold | Wide, uppercase (`overlineMd` 14/20, `overlineLg` 16/24) |
+
+`Heading` picks a preset from two props: `variant` (`heading`, `display`, `overline`) and `size` (`sm`, `md`, `lg`, `xl`). `<Heading level={3} variant="overline" size="lg">` is a group title at 16/24. Without `size`, a heading takes its level's size, a display title `md` and an overline `sm`.
 
 ### Display (fluid)
 
@@ -82,12 +85,13 @@ See the **Fluid Display** story for a resizable demo.
 
 ## When to use which layer
 
-| Scenario                                       | Use                                       |
-| ---------------------------------------------- | ----------------------------------------- |
-| Body text in a page or card                    | `<Text variant="bodyMd">`                 |
-| Section heading                                | `<Heading level={2}>`                     |
-| Hero or landing page title                     | `<Heading level={1} variant="displayLg">` |
-| Form label                                     | `<Text variant="label">`                  |
-| Inline code                                    | `<Text variant="code">`                   |
-| Custom component needing raw font size         | `typeScale.fontSize4` token               |
-| Composing a one-off style with preset defaults | `typePresets.bodyMd` in `css.create()`    |
+| Scenario                                       | Use                                               |
+| ---------------------------------------------- | ------------------------------------------------- |
+| Body text in a page or card                    | `<Text variant="bodyMd">`                         |
+| Section heading                                | `<Heading level={2}>`                             |
+| Group title over a list of rows                | `<Heading level={3} variant="overline">`          |
+| Hero or landing page title                     | `<Heading level={1} variant="display" size="lg">` |
+| Form label                                     | `<Text variant="label">`                          |
+| Inline code                                    | `<Text variant="code">`                           |
+| Custom component needing raw font size         | `typeScale.fontSize4` token                       |
+| Composing a one-off style with preset defaults | `typePresets.bodyMd` in `css.create()`            |

package/src/index.native.ts

@@ -20,7 +20,7 @@ export {Badge, type BadgeVariant, type BadgeSize} from './components/Badge/Badge
 export {Button, type ButtonVariant, type ButtonSize} from './components/Button/Button'
 export {Card, type CardVariant, type CardSize} from './components/Card/Card'
 export {Checkbox} from './components/Checkbox/Checkbox'
-export {Heading, type HeadingVariant} from './components/Heading/Heading'
+export {Heading, type HeadingSize, type HeadingVariant} from './components/Heading/Heading'
 export {Input, type InputVariant} from './components/Input/Input'
 export {Switch} from './components/Switch/Switch'
 export {Text, type TextVariant, type TextColor} from './components/Text/Text'

package/src/index.ts

@@ -56,7 +56,7 @@ export {
   type SnapPoint,
 } from './components/Drawer/Drawer'
 export {EmptyState} from './components/EmptyState/EmptyState'
-export {Heading, type HeadingVariant} from './components/Heading/Heading'
+export {Heading, type HeadingSize, type HeadingVariant} from './components/Heading/Heading'
 export {List, type ListSelectionMode} from './components/List/List'
 export {LiveRegion, type LiveRegionPoliteness} from './components/LiveRegion/LiveRegion'
 export {Field} from './components/Field/Field'