@hzblj/kara-components 0.16.0 → 0.18.0

package/src/atoms/checkbox/checkbox.ios.tsx

@@ -6,7 +6,7 @@ import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import type {CheckboxComponent, CheckboxProps} from './checkbox.types'
 
-export const Checkbox: CheckboxComponent = ({disabled = false, label, onValueChange, value}: CheckboxProps) => {
+export const Checkbox: CheckboxComponent = ({disabled = false, label, onValueChange, testID, value}: CheckboxProps) => {
   useHostGuard('Checkbox')
   const theme = useAppTheme()
 
@@ -20,5 +20,5 @@ export const Checkbox: CheckboxComponent = ({disabled = false, label, onValueCha
     return list
   }, [disabled, theme])
 
-  return <Toggle isOn={value} label={label} modifiers={modifiers} onIsOnChange={onValueChange} />
+  return <Toggle isOn={value} label={label} modifiers={modifiers} onIsOnChange={onValueChange} testID={testID} />
 }

package/src/atoms/checkbox/checkbox.types.ts

@@ -8,6 +8,8 @@ export type CheckboxProps = {
   label?: string
   /** Called with the new value when the user toggles it. */
   onValueChange?: (value: boolean) => void
+  /** Test identifier, forwarded to the native control (on Android the box itself, not the labelled row). */
+  testID?: string
   /** Whether it is checked. Controlled: update it from `onValueChange`. */
   value: boolean
 }

package/src/atoms/color-picker/color-picker.android.tsx

@@ -9,8 +9,10 @@ import type {ColorPickerComponent, ColorPickerProps} from './color-picker.types'
 /**
  * The row SwiftUI's `ColorPicker` lays out on iOS, the label leading and the well trailing, around kara's own Compose
  * well: Compose ships no colour picker, so the sheet behind it draws the iOS picker's grid, spectrum and sliders.
+ * `disabled` dims the label and the well, which then does not open its sheet.
  */
 export const ColorPicker: ColorPickerComponent = ({
+  disabled = false,
   label,
   onValueChange,
   supportsOpacity = false,
@@ -21,9 +23,15 @@ export const ColorPicker: ColorPickerComponent = ({
 
   return (
     <HStack align="center" spacing="s12" testID={testID} wide>
-      {label ? <Text>{label}</Text> : null}
+      {label ? <Text color={disabled ? 'content.tertiary' : undefined}>{label}</Text> : null}
       <Spacer />
-      <ColorWell onValueChange={onValueChange} supportsOpacity={supportsOpacity} title={label} value={value} />
+      <ColorWell
+        enabled={!disabled}
+        onValueChange={onValueChange}
+        supportsOpacity={supportsOpacity}
+        title={label}
+        value={value}
+      />
     </HStack>
   )
 }

package/src/atoms/color-picker/color-picker.ios.tsx

@@ -1,9 +1,19 @@
 import {ColorPicker as SwiftUIColorPicker} from '@expo/ui/swift-ui'
+import {disabled as disabledModifier, labelsHidden, opacity as opacityModifier} from '@expo/ui/swift-ui/modifiers'
+import {opacity} from '@hzblj/kara-theme'
 
 import {useHostGuard} from '../../host-context'
+import {HStack} from '../h-stack'
+import {Spacer} from '../spacer'
+import {Text} from '../text'
 import type {ColorPickerComponent, ColorPickerProps} from './color-picker.types'
 
+// iOS 27 stops a disabled picker but draws its label and well at full strength: the label is then kara's own text,
+// dimmed, and the well takes the opacity.
+const DISABLED = [labelsHidden(), disabledModifier(true), opacityModifier(opacity.o40)]
+
 export const ColorPicker: ColorPickerComponent = ({
+  disabled = false,
   label,
   onValueChange,
   supportsOpacity = false,
@@ -12,13 +22,26 @@ export const ColorPicker: ColorPickerComponent = ({
 }: ColorPickerProps) => {
   useHostGuard('ColorPicker')
 
-  return (
+  const picker = (
     <SwiftUIColorPicker
       label={label}
+      modifiers={disabled ? DISABLED : undefined}
       onSelectionChange={onValueChange}
       selection={value}
       supportsOpacity={supportsOpacity}
       testID={testID}
     />
   )
+
+  if (!disabled) {
+    return picker
+  }
+
+  return (
+    <HStack align="center" spacing="s12" wide>
+      {label ? <Text color="content.tertiary">{label}</Text> : null}
+      <Spacer />
+      {picker}
+    </HStack>
+  )
 }

package/src/atoms/color-picker/color-picker.types.ts

@@ -6,6 +6,8 @@ import type {ReactNode} from 'react'
  * spectrum and RGB sliders.
  */
 export type ColorPickerProps = {
+  /** Stops the user picking a colour, and dims the label and the well. */
+  disabled?: boolean
   /** Text beside the colour well, and the Android sheet's title. */
   label?: string
   /** Called with the colour the user picks. */

package/src/atoms/date-picker/date-picker.android.tsx

@@ -1,7 +1,8 @@
 import {DateTimePicker} from '@expo/ui/community/datetime-picker'
-import {RNHostView} from '@expo/ui/jetpack-compose'
-import {useAppTheme} from '@hzblj/kara-theme'
-import {useCallback, useState} from 'react'
+import {DateTimePicker as ComposeDateTimePicker, Host, RNHostView} from '@expo/ui/jetpack-compose'
+import {alpha, testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
+import {opacity, useAppTheme} from '@hzblj/kara-theme'
+import {useCallback, useMemo, useState} from 'react'
 
 import {useInsideHost} from '../../host-context'
 import {Box} from '../box'
@@ -9,6 +10,8 @@ import {Pressable} from '../pressable'
 import {RnText} from '../rn-text'
 import type {DatePickerComponent, DatePickerMode, DatePickerProps} from './date-picker.types'
 
+const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
+
 const formatted = (value: Date, mode: DatePickerMode): string => {
   if (mode === 'time') {
     return value.toLocaleTimeString(undefined, {hour: '2-digit', minute: '2-digit'})
@@ -21,20 +24,68 @@ const formatted = (value: Date, mode: DatePickerMode): string => {
     : date
 }
 
+/** Material's calendar counts in UTC days: `value`'s local day goes in as that day's UTC midnight. */
+const utcDayOf = (value: Date): string =>
+  new Date(Date.UTC(value.getFullYear(), value.getMonth(), value.getDate())).toISOString()
+
+/** The UTC day the calendar reports, back on `value`'s local time of day. */
+const localDayOf = (utcDay: Date, value: Date): Date => {
+  const next = new Date(value)
+  next.setFullYear(utcDay.getUTCFullYear(), utcDay.getUTCMonth(), utcDay.getUTCDate())
+
+  return next
+}
+
+/**
+ * Material's calendar in place, for `graphical`: the month and its days, without the title and headline its dialog
+ * shows, in the accent. It also reports its day when it first shows and whenever `value` hands it a new one, so only a
+ * day that differs from `value` goes out. It has no disabled state, so a disabled one is dimmed and offers only the
+ * selected day.
+ */
+const Calendar = ({disabled, max, min, onValueChange, testID, value}: DatePickerProps) => {
+  const theme = useAppTheme()
+
+  const onDateSelected = useCallback(
+    (date: Date) => {
+      const next = localDayOf(date, value)
+
+      if (!disabled && next.getTime() !== value.getTime()) {
+        onValueChange?.(next)
+      }
+    },
+    [disabled, onValueChange, value]
+  )
+
+  const modifiers = useMemo(
+    () => [...(disabled ? [alpha(opacity.o40)] : []), ...(testID ? [testIdModifier(testID)] : [])],
+    [disabled, testID]
+  )
+
+  return (
+    <ComposeDateTimePicker
+      color={theme.color('fill.accent.primary')}
+      displayedComponents="date"
+      initialDate={utcDayOf(value)}
+      modifiers={modifiers}
+      onDateSelected={onDateSelected}
+      selectableDates={disabled ? {end: value, start: value} : min || max ? {end: max, start: min} : undefined}
+      showHeadline={false}
+      showTitle={false}
+      showVariantToggle={false}
+      variant="picker"
+    />
+  )
+}
+
 /**
- * The value as a field that opens Material's date picker dialog on a tap. Android's picker *is* a dialog — mounted, it
- * opens — so it is mounted only while open, and unmounted on confirm or dismiss, as the component asks its caller to.
+ * The value as a field that opens Material's date picker dialog on a tap. Android's picker *is* a dialog (mounted, it
+ * opens), so it is mounted only while open, and unmounted on confirm or dismiss, as the component asks its caller to.
  * Both are React Native views; inside a `Screen` or `Island` `RNHostView` carries them into that host, sized to the
- * field (see `useInsideHost`).
+ * field (see `useInsideHost`). With `datePickerStyle="graphical"` and a date to pick, it is Material's calendar in
+ * place instead: a Compose view, in a host of its own the width of its container, or straight in the enclosing one.
  */
-export const DatePicker: DatePickerComponent = ({
-  max,
-  min,
-  mode = 'date',
-  onValueChange,
-  testID,
-  value,
-}: DatePickerProps) => {
+export const DatePicker: DatePickerComponent = (props: DatePickerProps) => {
+  const {datePickerStyle = 'compact', disabled = false, max, min, mode = 'date', onValueChange, testID, value} = props
   const theme = useAppTheme()
   const insideHost = useInsideHost()
   const [open, setOpen] = useState(false)
@@ -50,20 +101,39 @@ export const DatePicker: DatePickerComponent = ({
     [onValueChange]
   )
 
+  if (datePickerStyle === 'graphical' && mode !== 'time') {
+    const calendar = <Calendar {...props} disabled={disabled} />
+
+    return insideHost ? (
+      calendar
+    ) : (
+      <Host
+        colorScheme={theme.dark ? 'dark' : 'light'}
+        matchContents={MATCH_HEIGHT_ONLY}
+        seedColor={theme.materialSeed}
+      >
+        {calendar}
+      </Host>
+    )
+  }
+
   const field = (
     <>
       <Pressable
         alignSelf="flex-start"
         bg="fill.tertiary"
         borderRadius="medium"
+        disabled={disabled}
         onPress={show}
         px="s12"
         py="s8"
         testID={testID}
       >
-        <RnText variant="body">{formatted(value, mode)}</RnText>
+        <RnText color={disabled ? 'content.tertiary' : 'content.primary'} variant="body">
+          {formatted(value, mode)}
+        </RnText>
       </Pressable>
-      {open ? (
+      {open && !disabled ? (
         <DateTimePicker
           accentColor={theme.colorString('fill.accent.primary')}
           maximumDate={max}

package/src/atoms/date-picker/date-picker.ios.tsx

@@ -1,5 +1,10 @@
 import {Host, DatePicker as SwiftUIDatePicker} from '@expo/ui/swift-ui'
-import {datePickerStyle, labelsHidden, tint} from '@expo/ui/swift-ui/modifiers'
+import {
+  datePickerStyle as datePickerStyleModifier,
+  disabled as disabledModifier,
+  labelsHidden,
+  tint,
+} from '@expo/ui/swift-ui/modifiers'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 
@@ -13,13 +18,15 @@ const COMPONENTS = {
 } as const satisfies Record<DatePickerMode, ('date' | 'hourAndMinute')[]>
 
 /**
- * The system's compact date picker: the value in a pill, and a tap on it opens the calendar popover UIKit owns. Its own
- * host, sized to the pill on both axes — a host that took the width it was given would lay the pill out against the
- * far edge of it, or past its container's — so it drops into a row the way a `Text` does. The label is the caller's,
- * beside it; the calendar is in the accent. Inside a `Screen` or `Island` it renders into that host instead (see
- * `useInsideHost`).
+ * The system's date picker, in the accent. `compact` by default: the value in a pill, and a tap on it opens the
+ * calendar popover UIKit owns. `graphical` is that calendar in place, `wheel` the value on wheels. Its own host, sized
+ * to the picker on both axes (a host that took the width it was given would lay the pill out against the far edge of
+ * it, or past its container's), so it drops into a row the way a `Text` does. The label is the caller's, beside it.
+ * Inside a `Screen` or `Island` it renders into that host instead (see `useInsideHost`).
  */
 export const DatePicker: DatePickerComponent = ({
+  datePickerStyle = 'compact',
+  disabled = false,
   max,
   min,
   mode = 'date',
@@ -31,8 +38,13 @@ export const DatePicker: DatePickerComponent = ({
   const insideHost = useInsideHost()
 
   const modifiers = useMemo(
-    () => [datePickerStyle('compact'), labelsHidden(), tint(theme.color('fill.accent.primary'))],
-    [theme]
+    () => [
+      datePickerStyleModifier(datePickerStyle),
+      labelsHidden(),
+      tint(theme.color('fill.accent.primary')),
+      ...(disabled ? [disabledModifier(true)] : []),
+    ],
+    [datePickerStyle, disabled, theme]
   )
 
   const picker = (

package/src/atoms/date-picker/date-picker.types.ts

@@ -2,24 +2,48 @@ import type {ReactNode} from 'react'
 
 export type DatePickerMode = 'date' | 'datetime' | 'time'
 
+/** How SwiftUI shows the picker: a pill that opens the calendar, the calendar in place, or wheels. */
+export type DatePickerStyleName = 'compact' | 'graphical' | 'wheel'
+
 /**
- * A date or time picker: SwiftUI's compact `DatePicker` on iOS, a field that opens Material's picker dialog on a tap
- * on Android. The React Native tier: it brings its own host and sizes itself to the value, so it sits in a row beside
- * its label like a `Text`. Inside a `Screen` or `Island` it joins that host instead, beside a native `Text` label.
+ * A date or time picker: SwiftUI's `DatePicker` on iOS (a pill by default, a calendar or wheels with
+ * `datePickerStyle`), a field that opens Material's picker dialog on a tap on Android, or Material's calendar in place
+ * with `datePickerStyle="graphical"`. The React Native tier: it brings its own host and sizes itself to the value, so it
+ * sits in a row beside its label like a `Text`. Inside a `Screen` or `Island` it joins that host instead, beside a
+ * native `Text` label.
  */
 export type DatePickerProps = {
+  /**
+   * SwiftUI's date picker style. `compact` by default: the value in a pill, which opens the calendar in a popover.
+   * `graphical` is the calendar in place, a month at a time, with the time under it in `datetime` mode: what a screen
+   * built around picking a day wants. `wheel` puts the value on wheels. Android shows Material's calendar in place for
+   * `graphical` in `date` and `datetime` modes (without its title and headline); otherwise it keeps its field and
+   * dialog, since Material has no wheel.
+   */
+  datePickerStyle?: DatePickerStyleName
+  /**
+   * Stops the user changing the date, and dims the picker. Material's calendar has no disabled state of its own, so a
+   * `graphical` picker on Android is dimmed and offers only the selected day.
+   */
+  disabled?: boolean
   /** The latest date that can be picked. Android ignores it in `time` mode. */
   max?: Date
   /** The earliest date that can be picked. Android ignores it in `time` mode. */
   min?: Date
   /**
-   * What it picks. `date` by default. Android has no combined dialog, so there `datetime` picks the date and keeps
-   * `value`'s time of day.
+   * What it picks. `date` by default. Android has no combined dialog or calendar, so there `datetime` picks the date
+   * and keeps `value`'s time of day.
    */
   mode?: DatePickerMode
-  /** Called with the new date: on iOS as it changes, on Android when the dialog is confirmed. */
+  /**
+   * Called with the new date: on iOS as it changes, on Android when the dialog is confirmed or a day in the calendar
+   * is tapped.
+   */
   onValueChange?: (date: Date) => void
-  /** Test identifier, on the native picker on iOS and on the tappable field on Android. */
+  /**
+   * Test identifier, on the native picker on iOS and on Android's calendar, and on the tappable field elsewhere on
+   * Android.
+   */
   testID?: string
   /** The selected date. Controlled: update it from `onValueChange`. */
   value: Date

package/src/atoms/divider/divider.android.tsx

@@ -1,12 +1,23 @@
-import {HorizontalDivider} from '@expo/ui/jetpack-compose'
+import {HorizontalDivider, VerticalDivider} from '@expo/ui/jetpack-compose'
+import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
 import type {DividerComponent, DividerProps} from './divider.types'
 
-export const Divider: DividerComponent = ({color = 'border.tertiary'}: DividerProps) => {
+/**
+ * Compose's dividers. Unlike SwiftUI's, a Compose divider does not turn with its stack, so `axis` picks the one:
+ * `VerticalDivider` fills the height of the `Row` around it.
+ */
+export const Divider: DividerComponent = ({axis = 'horizontal', color = 'border.tertiary', testID}: DividerProps) => {
   useHostGuard('Divider')
   const theme = useAppTheme()
+  const modifiers = useMemo(() => (testID ? [testIdModifier(testID)] : undefined), [testID])
 
-  return <HorizontalDivider color={theme.color(color)} />
+  return axis === 'vertical' ? (
+    <VerticalDivider color={theme.color(color)} modifiers={modifiers} />
+  ) : (
+    <HorizontalDivider color={theme.color(color)} modifiers={modifiers} />
+  )
 }

package/src/atoms/divider/divider.ios.tsx

@@ -6,6 +6,10 @@ import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import type {DividerComponent, DividerProps} from './divider.types'
 
+/**
+ * SwiftUI's divider, which turns with its stack: vertical in an `HStack`, horizontal anywhere else. So `axis`, which
+ * Android needs to pick its divider, has nothing to do here.
+ */
 export const Divider: DividerComponent = ({color = 'border.tertiary', testID}: DividerProps) => {
   useHostGuard('Divider')
   const theme = useAppTheme()

package/src/atoms/divider/divider.types.ts

@@ -1,11 +1,23 @@
 import type {ColorToken} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
-/** A horizontal hairline: SwiftUI `Divider` / Compose `HorizontalDivider`. */
+/** Which way the line runs. */
+export type DividerAxis = 'horizontal' | 'vertical'
+
+/**
+ * A hairline between views: SwiftUI `Divider` / Compose `HorizontalDivider`, or `VerticalDivider` with
+ * `axis="vertical"`.
+ */
 export type DividerProps = {
+  /**
+   * Which way the line runs. `horizontal` by default: across a `VStack`. `vertical` stands it up between the children
+   * of an `HStack`, as tall as the stack, so give the stack a height (`h`). iOS ignores it: SwiftUI's divider turns by
+   * itself, vertical in an `HStack` and horizontal anywhere else. Set it anyway, so Android draws the same.
+   */
+  axis?: DividerAxis
   /** The line's colour. `border.tertiary` by default. */
   color?: ColorToken
-  /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }
 

package/src/atoms/fab/fab.android.tsx

@@ -1,23 +1,73 @@
-import {FloatingActionButton} from '@expo/ui/jetpack-compose'
+import {
+  ExtendedFloatingActionButton,
+  FloatingActionButton,
+  LargeFloatingActionButton,
+  SmallFloatingActionButton,
+} from '@expo/ui/jetpack-compose'
+import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {useAccessibilityModifiers} from '@hzblj/kara-sx'
-import {useAppTheme} from '@hzblj/kara-theme'
+import {type SpaceSize, useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
 import {Icon} from '../icon'
-import type {FabComponent, FabProps} from './fab.types'
+import {Text} from '../text'
+import type {FabComponent, FabProps, FabSize} from './fab.types'
 
-export const Fab: FabComponent = ({accessibilityHint, accessibilityLabel, name, onPress}: FabProps) => {
+/** Material's three FABs, and the icon each draws (`FloatingActionButtonDefaults.LargeIconSize` is 36dp). */
+const SIZES = {
+  large: {icon: 's36', Material: LargeFloatingActionButton},
+  regular: {icon: 's24', Material: FloatingActionButton},
+  small: {icon: 's24', Material: SmallFloatingActionButton},
+} as const satisfies Record<FabSize, {Material: unknown; icon: SpaceSize}>
+
+export const Fab: FabComponent = ({
+  accessibilityHint,
+  accessibilityLabel,
+  label,
+  name,
+  onPress,
+  size = 'regular',
+  testID,
+}: FabProps) => {
   useHostGuard('Fab')
 
   const theme = useAppTheme()
-  const modifiers = useAccessibilityModifiers({accessibilityHint}, accessibilityHint !== undefined)
+  const accessibilityModifiers = useAccessibilityModifiers({accessibilityHint}, accessibilityHint !== undefined)
+  const modifiers = useMemo(
+    () => (testID ? [testIdModifier(testID), ...accessibilityModifiers] : accessibilityModifiers),
+    [accessibilityModifiers, testID]
+  )
+  const containerColor = theme.color('fill.accent.primary')
+
+  /*
+   * `@expo/ui`'s FABs are slot-based: content outside `.Icon` (and the extended one's `.Text`) is not composed at all.
+   * The label rides on the icon, as for every FAB, and the text beside it is hidden from TalkBack so the button is not
+   * read twice; a label on the FAB itself would clear the click inside it, which Material's FAB composes after our
+   * modifiers.
+   */
+  if (label) {
+    return (
+      <ExtendedFloatingActionButton containerColor={containerColor} modifiers={modifiers} onClick={onPress}>
+        <ExtendedFloatingActionButton.Icon>
+          <Icon accessibilityLabel={accessibilityLabel} color="content.on.accent" name={name} />
+        </ExtendedFloatingActionButton.Icon>
+        <ExtendedFloatingActionButton.Text>
+          <Text accessibilityHidden color="content.on.accent" variant="body">
+            {label}
+          </Text>
+        </ExtendedFloatingActionButton.Text>
+      </ExtendedFloatingActionButton>
+    )
+  }
+
+  const {icon, Material} = SIZES[size]
 
   return (
-    <FloatingActionButton containerColor={theme.color('fill.accent.primary')} modifiers={modifiers} onClick={onPress}>
-      {/* `@expo/ui`'s FAB is slot-based: content outside `.Icon` is not composed at all. */}
-      <FloatingActionButton.Icon>
-        <Icon accessibilityLabel={accessibilityLabel} color="content.on.accent" name={name} />
-      </FloatingActionButton.Icon>
-    </FloatingActionButton>
+    <Material containerColor={containerColor} modifiers={modifiers} onClick={onPress}>
+      <Material.Icon>
+        <Icon accessibilityLabel={accessibilityLabel} color="content.on.accent" name={name} size={icon} />
+      </Material.Icon>
+    </Material>
   )
 }

package/src/atoms/fab/fab.ios.tsx

@@ -1,23 +1,49 @@
 import {Button} from '@expo/ui/swift-ui'
 import {buttonStyle} from '@expo/ui/swift-ui/modifiers'
-import {useAccessibilityModifiers, useSxModifiers} from '@hzblj/kara-sx'
+import {type ResponsiveSx, useAccessibilityModifiers, useSxModifiers} from '@hzblj/kara-sx'
+import type {SpaceSize} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
+import {HStack} from '../h-stack'
 import {Icon} from '../icon'
-import type {FabComponent, FabProps} from './fab.types'
+import {Text} from '../text'
+import type {FabComponent, FabProps, FabSize} from './fab.types'
 
-export const Fab: FabComponent = ({accessibilityHint, accessibilityLabel, name, onPress, testID}: FabProps) => {
+/** Material's sizes, in points: the circle across and the icon in it. */
+const SIZES = {
+  large: {icon: 's36', side: 96},
+  regular: {icon: 's24', side: 56},
+  small: {icon: 's24', side: 40},
+} as const satisfies Record<FabSize, {icon: SpaceSize; side: number}>
+
+const SURFACE = {bg: 'fill.accent.primary', borderRadius: 'full', shadow: 'btn.accent'} as const satisfies ResponsiveSx
+
+/**
+ * Material's extended FAB in kara's iOS language: the regular FAB's height, accent and shadow, drawn as a capsule (the
+ * shape a round button takes once it has words), 16 before the icon and 20 after the text, as Material pads it.
+ */
+const EXTENDED = {...SURFACE, h: SIZES.regular.side, pl: 's16', pr: 's20'} as const satisfies ResponsiveSx
+
+export const Fab: FabComponent = ({
+  accessibilityHint,
+  accessibilityLabel,
+  label,
+  name,
+  onPress,
+  size = 'regular',
+  testID,
+}: FabProps) => {
   useHostGuard('Fab')
-  const accessibilityModifiers = useAccessibilityModifiers({accessibilityHint})
+  const extended = Boolean(label)
+  const {icon, side} = SIZES[size]
+
+  // An icon alone carries the label; beside text, the button does, in place of what the text would say.
+  const accessibilityModifiers = useAccessibilityModifiers(
+    extended ? {accessibilityHint, accessibilityLabel} : {accessibilityHint}
+  )
 
-  const sxModifiers = useSxModifiers({
-    bg: 'fill.accent.primary',
-    borderRadius: 'full',
-    h: 56,
-    p: 's16',
-    shadow: 'btn.accent',
-    w: 56,
-  })
+  // The frame centres the icon, so one circle serves every size: `regular` is the 56pt one it always was.
+  const sxModifiers = useSxModifiers(extended ? EXTENDED : {...SURFACE, h: side, w: side}, 'center')
   const modifiers = useMemo(
     () => [buttonStyle('plain'), ...sxModifiers, ...accessibilityModifiers],
     [accessibilityModifiers, sxModifiers]
@@ -25,7 +51,16 @@ export const Fab: FabComponent = ({accessibilityHint, accessibilityLabel, name,
 
   return (
     <Button modifiers={modifiers} onPress={onPress} testID={testID}>
-      <Icon accessibilityLabel={accessibilityLabel} color="content.on.accent" name={name} />
+      {extended ? (
+        <HStack align="center" spacing="s12">
+          <Icon color="content.on.accent" name={name} />
+          <Text color="content.on.accent" variant="body">
+            {label}
+          </Text>
+        </HStack>
+      ) : (
+        <Icon accessibilityLabel={accessibilityLabel} color="content.on.accent" name={name} size={icon} />
+      )}
     </Button>
   )
 }

package/src/atoms/fab/fab.types.ts

@@ -2,23 +2,41 @@ import type {ReactNode} from 'react'
 
 import type {IconName} from '../icon'
 
+/** Material's three floating action buttons: 40, 56 and 96 across. */
+export type FabSize = 'large' | 'regular' | 'small'
+
 /**
- * A floating action button: Material's `FloatingActionButton` on Android, a 56pt accent circle (a plain SwiftUI
- * `Button`) on iOS. It renders inline; pinning it to a corner is up to the screen.
+ * A floating action button: Material's `FloatingActionButton` on Android, an accent circle (a plain SwiftUI `Button`)
+ * on iOS. With a `label` it is the extended one, the icon and the text side by side: Material's
+ * `ExtendedFloatingActionButton`, an accent capsule on iOS. It renders inline; pinning it to a corner is up to the
+ * screen.
  */
 export type FabProps = {
   /**
    * What VoiceOver and TalkBack say for the button, since an icon has no words of its own: "Share", "Add to
-   * favourites". Required for that reason.
+   * favourites". Required for that reason. With a `label` it is still what they say, in place of the label, so give
+   * it the label's words (or words that start with them), and Voice Control finds the button by what it shows.
    */
   accessibilityLabel: string
   /** What pressing it does, when the label alone does not say. See `AccessibilityProps`. */
   accessibilityHint?: string
+  /**
+   * Text beside the icon, which makes it an extended FAB: "Compose", "New post". For a screen whose main action needs
+   * its words. Material's `ExtendedFloatingActionButton` on Android; on iOS the same accent, 56pt tall, as a capsule.
+   */
+  label?: string
   /** The icon, one of the app's, drawn in `content.on.accent`. */
   name: IconName
   /** Called when the button is pressed. */
   onPress?: () => void
-  /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
+  /**
+   * `regular` by default, 56 across. `small` is 40, for a secondary action beside a regular one; `large` is 96, with a
+   * 36 icon, for a screen built around one action. Material's `SmallFloatingActionButton` and
+   * `LargeFloatingActionButton` on Android, the same sizes of circle on iOS. A FAB with a `label` has one size and
+   * ignores it.
+   */
+  size?: FabSize
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }