@hzblj/kara-components 0.6.0 → 0.7.0

package/src/molecules/rn-tooltip/rn-tooltip.types.ts

@@ -2,8 +2,11 @@ import type {ReactElement, ReactNode} from 'react'
 
 export type RnTooltipActionVariant = 'link' | 'primary' | 'secondary'
 
+/** A button in an `RnTooltip`. */
 export type RnTooltipAction = {
+  /** The button's text. */
   label: string
+  /** Called on press. The tooltip stays up — turn `visible` off here if the action should close it. */
   onPress: () => void
   /** `link` by default — an underlined text. `primary`/`secondary` are small filled/outlined buttons. */
   variant?: RnTooltipActionVariant
@@ -18,6 +21,7 @@ export type RnTooltipDismissReason = 'anchorHidden' | 'outside'
  * Native tier, unlike `Tooltip`, whose anchor is a native view inside a host.
  */
 export type RnTooltipProps = {
+  /** A row of buttons under the text, in order. */
   actions?: RnTooltipAction[]
   /** Which end of the bubble the actions sit at. `end` by default. */
   actionsAlignment?: 'end' | 'start'
@@ -28,11 +32,18 @@ export type RnTooltipProps = {
   boundaryInsets?: {bottom?: number; top?: number}
   /** The anchor — a single React Native view. */
   children: ReactElement
+  /** The body text, under the title. */
   message?: string
+  /**
+   * Asks for the tooltip to close, with the reason — turn `visible` off. On Android any touch outside asks, the start
+   * of a scroll included; iOS keeps the tooltip through a scroll.
+   */
   onDismiss: (reason: RnTooltipDismissReason) => void
   /** The appear animation finished. */
   onShown?: () => void
+  /** The heading line, above the message. */
   title?: string
+  /** Shows the tooltip while true. It never hides itself. */
   visible: boolean
 }
 

package/src/molecules/scroll-edge-container/scroll-edge-container.types.ts

@@ -17,12 +17,15 @@ export type ScrollEdgeContainerProps = ResponsiveViewSx & {
    * content begins below the top bar and scrolls under it. On by default.
    */
   automaticInsets?: boolean
+  /** Laid over the scroll view's bottom edge on iOS; stacked below it on Android, where it wants a background. */
   bottomBar?: ReactNode
   /** Exactly one React Native scroll view — `RnScrollView`, `RnFlatList`, `RnSectionList`. */
   children: ReactElement<ScrollEdgeScrollableProps>
   /** iOS 26: how hard the edge cuts. `soft` by default. */
   effect?: ScrollEdgeEffect
+  /** Test identifier, forwarded to the container view. */
   testID?: string
+  /** Laid over the scroll view's top edge on iOS; stacked above it on Android, where it wants a background. */
   topBar?: ReactNode
 }
 

package/src/molecules/search-bar/search-bar.tsx

@@ -1,5 +1,5 @@
 import {useAppTheme} from '@hzblj/kara-theme'
-import {TextInput} from 'react-native'
+import {Platform, TextInput} from 'react-native'
 
 import {Box} from '../../atoms/box'
 import {Pressable} from '../../atoms/pressable'
@@ -13,6 +13,13 @@ export const SearchBar: SearchBarComponent = ({
   value,
 }: SearchBarProps) => {
   const theme = useAppTheme()
+  const {lineHeight, ...face} = theme.typography.body
+  /**
+   * A single-line `UITextField` sets its text against the bottom of a line taller than the font, so the variant's
+   * `lineHeight` pushed the text below the magnifier beside it. iOS takes the face without it, in a field as tall as
+   * the line would have been; Android centres the line and keeps it.
+   */
+  const text = Platform.OS === 'ios' ? {...face, height: lineHeight} : theme.typography.body
 
   return (
     <Box
@@ -31,7 +38,7 @@ export const SearchBar: SearchBarComponent = ({
         onChangeText={onChangeText}
         placeholder={placeholder}
         placeholderTextColor={theme.color('content.quaternary')}
-        style={[theme.typography.body, {color: theme.color('content.primary'), flex: 1, padding: 0}]}
+        style={[text, {color: theme.color('content.primary'), flex: 1, padding: 0}]}
         value={value}
       />
       {value.length > 0 ? (

package/src/molecules/search-bar/search-bar.types.ts

@@ -1,9 +1,17 @@
 import type {ReactNode} from 'react'
 
+/**
+ * A search field drawn the same on both platforms — a rounded box with a magnifier, a `TextInput` and a clear button
+ * while there is text. The React Native tier: it needs no host.
+ */
 export type SearchBarProps = {
+  /** Every edit, and `''` when the clear button is pressed. */
   onChangeText?: (text: string) => void
+  /** Shown while the field is empty. `Search` by default. */
   placeholder?: string
+  /** Test identifier, put on the field's container view rather than on the `TextInput`. */
   testID?: string
+  /** The field's text. Controlled — pass back what `onChangeText` reports. */
   value: string
 }
 

package/src/molecules/stepper/stepper.types.ts

@@ -1,11 +1,24 @@
 import type {ReactNode} from 'react'
 
+/**
+ * A number with minus and plus buttons beside a label: SwiftUI's `Stepper` on iOS; on Android the label, the value and
+ * two icon buttons in a row. A native atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type StepperProps = {
+  /**
+   * The leading text. iOS shows only the label, not the value — put the value in it if it should be seen. Android
+   * shows the value between its buttons.
+   */
   label: string
+  /** The highest value. When unset, Android has no upper limit and iOS stops at `100`. */
   max?: number
+  /** The lowest value. When unset, Android has no lower limit and iOS stops at `0`. */
   min?: number
+  /** A button was pressed; it passes the new value, kept within `min` and `max`. */
   onValueChange: (value: number) => void
+  /** How much one press adds or takes away. `1` by default. */
   step?: number
+  /** The current value. Update it from `onValueChange`. iOS's native stepper counts in whole numbers. */
   value: number
 }
 

package/src/molecules/tooltip/tooltip.android.tsx

@@ -1,24 +1,32 @@
-import {Text as ComposeText, TooltipBox} from '@expo/ui/jetpack-compose'
+import {Text as ComposeText} from '@expo/ui/jetpack-compose'
+import {TooltipBox} from '@hzblj/kara-native/jetpack-compose'
 import {useAppTheme} from '@hzblj/kara-theme'
+import {useCallback} from 'react'
 
 import {useHostGuard} from '../../host-context'
 import type {TooltipComponent, TooltipProps} from './tooltip.types'
 
-export const Tooltip: TooltipComponent = ({children, text}: TooltipProps) => {
+/**
+ * Material's plain tooltip in kara's controlled `TooltipBox`: shown while `visible`, centred above the anchor and kept
+ * inside the window. Material's own would open on a long press and hide itself without a word to JS.
+ */
+export const Tooltip: TooltipComponent = ({children, onDismiss, text, visible}: TooltipProps) => {
   useHostGuard('Tooltip')
-
   const theme = useAppTheme()
+  const onDismissRequest = useCallback(() => onDismiss(), [onDismiss])
 
   return (
-    <TooltipBox>
-      <TooltipBox.PlainTooltip
-        containerColor={theme.colorString('surface.high.contrast')}
-        contentColor={theme.colorString('content.on.high.contrast')}
-      >
+    <TooltipBox
+      containerColor={theme.color('surface.high.contrast')}
+      isPresented={visible}
+      onDismissRequest={onDismissRequest}
+      plain
+    >
+      <TooltipBox.Text>
         <ComposeText color={theme.colorString('content.on.high.contrast')} style={theme.typography.footnote}>
           {text}
         </ComposeText>
-      </TooltipBox.PlainTooltip>
+      </TooltipBox.Text>
       {children}
     </TooltipBox>
   )

package/src/molecules/tooltip/tooltip.types.ts

@@ -1,9 +1,21 @@
 import type {ReactNode} from 'react'
 
+/**
+ * A short text tip on a native view, shown while `visible` — a SwiftUI popover from `children` on iOS, Material's plain
+ * tooltip centred above them on Android. A native atom — it renders inside `<Screen>` or `<Island>`; `RnTooltip`
+ * anchors to a React Native view.
+ */
 export type TooltipProps = {
+  /** The anchor — a native view. */
   children: ReactNode
+  /** The tip. */
   text: string
+  /** Shows the tip while true. Controlled: nothing opens it but this — wire a long press to it if you want one. */
   visible: boolean
+  /**
+   * The user dismissed the tip — turn `visible` off. iOS: a tap outside the popover. Android: any touch outside it, the
+   * start of a scroll included, or the anchor scrolling out of the window.
+   */
   onDismiss: () => void
 }
 

package/src/organisms/action-sheet/action-sheet.android.tsx

@@ -1,35 +1,53 @@
-import {Divider} from '../../atoms/divider'
 import {HStack} from '../../atoms/h-stack'
+import {Icon} from '../../atoms/icon'
+import {Island} from '../../atoms/island'
 import {Text} from '../../atoms/text'
 import {VStack} from '../../atoms/v-stack'
 import {useHostGuard} from '../../host-context'
 import {Sheet} from '../sheet'
 import type {ActionSheetComponent, ActionSheetProps} from './action-sheet.types'
 
+/**
+ * Material's bottom-sheet menu: the title, then a full-width row per action, its icon leading. The sheet is the React
+ * Native tier, so the rows — Compose views — sit in an `Island` of their own; rendered straight into the sheet they had
+ * no host and threw.
+ */
 export const ActionSheet: ActionSheetComponent = ({actions, onDismiss, title, visible}: ActionSheetProps) => {
   useHostGuard('ActionSheet')
 
   return (
     <Sheet onDismiss={onDismiss} visible={visible}>
-      <VStack p="s16" spacing="s4" wide>
-        <Text color="content.secondary" variant="labelMedium">
-          {title}
-        </Text>
-        <Divider />
-        {actions.map(action => (
-          <HStack
-            key={action.label}
-            onPress={() => {
-              onDismiss()
-              action.onPress()
-            }}
-            py="s12"
-            wide
-          >
-            <Text color={action.destructive ? 'content.destructive' : 'content.primary'}>{action.label}</Text>
+      <Island>
+        <VStack pb="s16" wide>
+          <HStack px="s24" py="s12" wide>
+            <Text color="content.secondary" variant="labelMedium">
+              {title}
+            </Text>
           </HStack>
-        ))}
-      </VStack>
+          {actions.map(action => {
+            const color = action.destructive ? 'content.destructive' : 'content.primary'
+
+            return (
+              <HStack
+                key={action.label}
+                onPress={() => {
+                  onDismiss()
+                  action.onPress()
+                }}
+                px="s24"
+                py="s16"
+                spacing="s16"
+                wide
+              >
+                {action.icon ? <Icon color={color} name={action.icon} /> : null}
+                <Text color={color} variant="body">
+                  {action.label}
+                </Text>
+              </HStack>
+            )
+          })}
+        </VStack>
+      </Island>
     </Sheet>
   )
 }

package/src/organisms/action-sheet/action-sheet.ios.tsx

@@ -1,8 +1,16 @@
-import {Button, ConfirmationDialog} from '@expo/ui/swift-ui'
+import {Button, ConfirmationDialog, Spacer} from '@expo/ui/swift-ui'
+import {frame} from '@expo/ui/swift-ui/modifiers'
 
 import {useHostGuard} from '../../host-context'
 import type {ActionSheetComponent, ActionSheetProps} from './action-sheet.types'
 
+/**
+ * `@expo/ui` hangs the dialog on its `Trigger` and reads the buttons from its `Actions` slot. Without a trigger it
+ * attaches to an `EmptyView`, which SwiftUI never presents from — a spacer framed to nothing is a real view that takes
+ * no room.
+ */
+const ANCHOR = [frame({height: 0, width: 0})]
+
 export const ActionSheet: ActionSheetComponent = ({actions, onDismiss, title, visible}: ActionSheetProps) => {
   useHostGuard('ActionSheet')
 
@@ -16,14 +24,19 @@ export const ActionSheet: ActionSheetComponent = ({actions, onDismiss, title, vi
       }}
       title={title}
     >
-      {actions.map(action => (
-        <Button
-          key={action.label}
-          label={action.label}
-          onPress={action.onPress}
-          role={action.destructive ? 'destructive' : 'default'}
-        />
-      ))}
+      <ConfirmationDialog.Trigger>
+        <Spacer modifiers={ANCHOR} />
+      </ConfirmationDialog.Trigger>
+      <ConfirmationDialog.Actions>
+        {actions.map(action => (
+          <Button
+            key={action.label}
+            label={action.label}
+            onPress={action.onPress}
+            role={action.destructive ? 'destructive' : 'default'}
+          />
+        ))}
+      </ConfirmationDialog.Actions>
     </ConfirmationDialog>
   )
 }

package/src/organisms/action-sheet/action-sheet.types.ts

@@ -2,10 +2,18 @@ import type {ReactNode} from 'react'
 
 import type {MenuAction} from '../menu'
 
+/**
+ * A list of actions to pick one from: SwiftUI's confirmation dialog on iOS, a `Sheet` of Material rows — icon and label
+ * — under the title on Android. A native atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type ActionSheetProps = {
+  /** The choices, top to bottom. Picking one closes the sheet. */
   actions: MenuAction[]
+  /** The sheet closed — after a pick too — so turn `visible` off. */
   onDismiss: () => void
+  /** The heading above the actions. Android always shows it; on iOS the system decides, and may hide it. */
   title: string
+  /** Presents the sheet while true. */
   visible: boolean
 }
 

package/src/organisms/alert/alert.ios.tsx

@@ -1,8 +1,15 @@
-import {Button, Alert as SwiftUIAlert, Text as SwiftUIText} from '@expo/ui/swift-ui'
+import {Button, Spacer, Alert as SwiftUIAlert, Text as SwiftUIText} from '@expo/ui/swift-ui'
+import {frame} from '@expo/ui/swift-ui/modifiers'
 
 import {useHostGuard} from '../../host-context'
 import type {AlertComponent, AlertProps} from './alert.types'
 
+/**
+ * `@expo/ui` hangs the alert on its `Alert.Trigger`, and on an `EmptyView` when there is none — which SwiftUI never
+ * presents from, so the alert would not appear at all. A spacer framed to nothing is a real view that takes no room.
+ */
+const ANCHOR = [frame({height: 0, width: 0})]
+
 export const Alert: AlertComponent = ({
   confirmLabel = 'OK',
   destructive = false,
@@ -24,6 +31,9 @@ export const Alert: AlertComponent = ({
       }}
       title={title}
     >
+      <SwiftUIAlert.Trigger>
+        <Spacer modifiers={ANCHOR} />
+      </SwiftUIAlert.Trigger>
       <SwiftUIAlert.Actions>
         <Button label={confirmLabel} onPress={onConfirm ?? onDismiss} role={destructive ? 'destructive' : 'default'} />
         <Button label="Cancel" onPress={onDismiss} role="cancel" />

package/src/organisms/alert/alert.types.ts

@@ -1,12 +1,23 @@
 import type {ReactNode} from 'react'
 
+/**
+ * A modal alert with a confirm button and Cancel: SwiftUI's alert on iOS, Material's `AlertDialog` on Android. A native
+ * atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type AlertProps = {
+  /** The confirm button's label. `OK` by default. */
   confirmLabel?: string
+  /** Marks the confirm button destructive — the system's destructive role on iOS, the destructive colour on Android. */
   destructive?: boolean
+  /** The body text, under the title. */
   message?: string
+  /** The confirm button was pressed. `onDismiss` follows, as it does for every way the alert closes. */
   onConfirm?: () => void
+  /** The alert closed — either button, or on Android a tap outside or back — so turn `visible` off. */
   onDismiss: () => void
+  /** The alert's heading. */
   title: string
+  /** Shows the alert while true. */
   visible: boolean
 }
 

package/src/organisms/context-menu/context-menu.types.ts

@@ -10,6 +10,7 @@ import type {MenuAction} from '../menu'
  * needs no `Screen` or `Island`.
  */
 export type ContextMenuProps = ResponsiveViewSx & {
+  /** The menu's actions, top to bottom. */
   actions: MenuAction[]
   /** The trigger, laid out as usual. */
   children: ReactNode
@@ -29,10 +30,13 @@ export type ContextMenuProps = ResponsiveViewSx & {
    * `ZoomTransition.Source`, `pop` otherwise.
    */
   previewTransition?: 'dismiss' | 'pop' | 'zoom'
+  /** Test identifier — on the native view around the trigger on iOS, on the trigger's `Pressable` on Android. */
   testID?: string
 }
 
+/** A region of a `ContextMenu`'s trigger that keeps its own long press — see `ContextMenu.Exclusion`. */
 export type ContextMenuExclusionProps = {
+  /** The region — a button inside the card, say. */
   children: ReactNode
 }
 

package/src/organisms/fab-menu/fab-menu.types.ts

@@ -9,9 +9,11 @@ import type {MenuAction} from '../menu'
  * of a SwiftUI `Menu`. A native atom — it renders inside `<Screen>` or `<Island>`.
  */
 export type FabMenuProps = {
+  /** The actions the button unfolds into. */
   actions: MenuAction[]
   /** The closed button's icon — one of the app's. A plus by default. */
   icon?: IconName
+  /** Test identifier, forwarded to the SwiftUI `Menu`. iOS only — Android ignores it. */
   testID?: string
 }
 

package/src/organisms/form/form.android.tsx

@@ -4,11 +4,15 @@ import {VStack} from '../../atoms/v-stack'
 import {useHostGuard} from '../../host-context'
 import type {FormComponent, FormProps, FormSectionProps} from './form.types'
 
+/**
+ * Inset from its container on every side, as SwiftUI's grouped form is — in a `Screen` the cards would otherwise run
+ * into the screen's edges — and the section titles and footers indented to the cards' content.
+ */
 const FormRoot = ({children, testID}: FormProps) => {
   useHostGuard('Form')
 
   return (
-    <VStack spacing="s16" testID={testID} wide>
+    <VStack p="s16" spacing="s16" testID={testID} wide>
       {children}
     </VStack>
   )
@@ -17,15 +21,19 @@ const FormRoot = ({children, testID}: FormProps) => {
 const FormSection = ({children, footer, title}: FormSectionProps) => (
   <VStack spacing="s4" wide>
     {title ? (
-      <Text color="content.secondary" transform="uppercase" variant="labelMedium">
-        {title}
-      </Text>
+      <VStack px="s16" wide>
+        <Text color="content.secondary" transform="uppercase" variant="labelMedium">
+          {title}
+        </Text>
+      </VStack>
     ) : null}
     <Card wide>{children}</Card>
     {footer ? (
-      <Text color="content.tertiary" variant="footnote">
-        {footer}
-      </Text>
+      <VStack px="s16" wide>
+        <Text color="content.tertiary" variant="footnote">
+          {footer}
+        </Text>
+      </VStack>
     ) : null}
   </VStack>
 )

package/src/organisms/form/form.types.ts

@@ -6,13 +6,19 @@ import type {ReactNode} from 'react'
  * an island that sizes itself to its content it has no height and shows nothing.
  */
 export type FormProps = {
+  /** The form's `Form.Section`s. */
   children: ReactNode
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }
 
+/** A group of rows in a `Form`: a SwiftUI `Section` on iOS, a `Card` under a heading on Android. */
 export type FormSectionProps = {
+  /** The section's rows. */
   children: ReactNode
+  /** Small print under the section. */
   footer?: string
+  /** The section's heading. */
   title?: string
 }
 

package/src/organisms/menu/menu.types.ts

@@ -2,15 +2,32 @@ import type {ReactNode} from 'react'
 
 import type {IconName} from '../../atoms/icon'
 
+/** One action of a `Menu`, an `ActionSheet`, a `ContextMenu` or a `FabMenu`. */
 export type MenuAction = {
+  /**
+   * Draws the action in the destructive colour — the system's destructive role on iOS. `FabMenu` ignores it on
+   * Android.
+   */
   destructive?: boolean
+  /**
+   * One of the app's icons, before the label. `ContextMenu` and `FabMenu` show it on both platforms, `Menu` and
+   * `ActionSheet` on Android only.
+   */
   icon?: IconName
+  /** The action's text. Rows are keyed by it, so keep labels unique within one list. */
   label: string
+  /** Called when the action is chosen; the menu closes by itself. */
   onPress: () => void
 }
 
+/**
+ * A text button that opens a list of actions: a SwiftUI `Menu` on iOS, a Material dropdown anchored to it on Android.
+ * A native atom — it renders inside `<Screen>` or `<Island>`.
+ */
 export type MenuProps = {
+  /** The menu's actions, top to bottom. */
   actions: MenuAction[]
+  /** The trigger's text. Android draws it in the accent colour, with a chevron. */
   label: string
 }
 

package/src/organisms/sheet/sheet.types.ts

@@ -27,6 +27,7 @@ export type SheetHeaderProps = {
   leadingItems?: NavigationBarItem[]
   /** A search field in place of the title (iOS). */
   search?: NavigationBarSearch
+  /** The title — in the bar, or above the content with a `large` `titleStyle`. */
   title?: string
   /** `center` by default. */
   titleStyle?: SheetTitleStyle
@@ -34,7 +35,9 @@ export type SheetHeaderProps = {
   trailingItems?: NavigationBarItem[]
 }
 
+/** Imperative control of a `Sheet`, through its `ref`. */
 export type SheetRef = {
+  /** Dismisses it without calling `onDismiss`, which reports the user's dismissals only. */
   dismiss: () => Promise<void>
   /** Presents at a detent — the first by default. */
   present: (detentIndex?: number) => Promise<void>
@@ -50,6 +53,7 @@ export type SheetRef = {
 export type SheetProps = {
   /** The sheet's colour. `surface.primary` by default. */
   bg?: ColorToken
+  /** The content. A `<Sheet.Header>` among the direct children becomes the native header instead. */
   children: ReactNode
   /** Where the sheet can rest, smallest first. `['auto']` — fit the content — by default. */
   detents?: SheetDetent[]
@@ -65,15 +69,20 @@ export type SheetProps = {
   grabber?: boolean
   /** The user dismissed it — `visible` going false does not call this. */
   onDismiss: () => void
+  /** The sheet moved to another detent — its index in `detents`. */
   onDetentChange?: (detentIndex: number) => void
+  /** The sheet finished presenting. */
   onPresent?: () => void
+  /** `present`, `dismiss` and `resize`, for driving the sheet imperatively. */
   ref?: Ref<SheetRef>
   /**
    * The content is a scroll view (`<Sheet.ScrollView>`) the sheet drives: dragging past its top resizes the sheet,
    * and a header scrolls with the iOS 26 edge effect. Off by default — set it with a scrolling body.
    */
   scrollable?: boolean
+  /** Test identifier, forwarded to the native sheet. */
   testID?: string
+  /** Presents the sheet while true; going false dismisses it. */
   visible: boolean
 }
 
@@ -81,16 +90,26 @@ export type SheetScrollHandler = (event: NativeSyntheticEvent<NativeScrollEvent>
 
 /** What a scroll view inside a sheet needs: the room the header takes, the large title, the scroll listener. */
 export type SheetScrollContextValue = {
+  /** Render it first in the content. `null` unless the header's `titleStyle` is `large`. */
   largeTitle: ReactNode
+  /** Forward the scroll view's scroll events to it — it tracks the large title. Unset when there is none. */
   onScroll?: SheetScrollHandler
+  /** The room an overlaid header takes, to add to the content's top padding. `0` where the header sits above it. */
   topInset: number
 }
 
+/**
+ * The body of a `scrollable` sheet: its content starts below an overlaid header, it carries a large title, and it
+ * reports its scroll to the sheet.
+ */
 export type SheetScrollViewProps = Pick<ScrollViewProps, 'keyboardShouldPersistTaps'> & {
+  /** The scrolling content, after the large title if there is one. */
   children: ReactNode
   /** Styles the scrolling content — padding and gap belong here, as with `RnScrollView`. */
   content?: ResponsiveViewSx
+  /** Called on every scroll event, after the sheet's own listener. */
   onScroll?: SheetScrollHandler
+  /** Test identifier, forwarded to the scroll view. */
   testID?: string
 }
 

package/src/organisms/snackbar/snackbar.types.ts

@@ -1,9 +1,17 @@
 import type {ReactNode} from 'react'
 
+/**
+ * A short message laid over the bottom of its parent, with an optional action. The React Native tier, drawn the same on
+ * both platforms: it needs no host, and it never hides itself.
+ */
 export type SnackbarProps = {
+  /** The action button's text, on the trailing side. No button without it. */
   actionLabel?: string
+  /** The message. */
   message: string
+  /** The action was pressed. The snackbar stays up — turn `visible` off to hide it. */
   onAction?: () => void
+  /** Shows the snackbar while true, fading it in and out. It sets no timer of its own. */
   visible: boolean
 }