@hzblj/kara-components 0.17.0 → 0.18.0

package/lib/typescript/atoms/fab/fab.types.d.ts

@@ -1,22 +1,39 @@
 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;
 };
 export type FabComponent = (props: FabProps) => ReactNode;

package/lib/typescript/atoms/icon-button/icon-button.types.d.ts

@@ -1,9 +1,15 @@
+import type { ColorToken } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 import type { IconName } from '../icon';
 /**
- * A button that is just an icon: a plain SwiftUI `Button` on iOS, Material's `IconButton` on Android. The icon sits
- * centred in a tap target the size each platform asks for, 44pt on iOS and 48dp on Android, so a row of them spaces
- * itself the same way on both.
+ * How much the button stands out: just the icon (`plain`), on a fill in the accent (`filled`), on a muted fill
+ * (`tonal`), in a ring (`outlined`) or on Liquid Glass (`glass`).
+ */
+export type IconButtonVariant = 'filled' | 'glass' | 'outlined' | 'plain' | 'tonal';
+/**
+ * A button that is just an icon: a SwiftUI `Button` on iOS, one of Material's icon buttons on Android. A `plain` one
+ * sits centred in a tap target the size each platform asks for, 44pt on iOS and 48dp on Android, so a row of them
+ * spaces itself the same way on both; the other variants draw a circle around the icon.
  */
 export type IconButtonProps = {
     /**
@@ -13,13 +19,26 @@ export type IconButtonProps = {
     accessibilityLabel: string;
     /** What pressing it does, when the label alone does not say. See `AccessibilityProps`. */
     accessibilityHint?: string;
+    /**
+     * The icon's colour, `content.primary` by default. On `filled` it is the fill instead (`fill.accent.primary` by
+     * default) and the icon picks a colour that reads on it, as a `Button`'s `tint` does on a prominent style. On iOS a
+     * `tonal` button's circle takes a pale shade of it too.
+     */
+    color?: ColorToken;
     /** Dims the icon (iOS's own disabled look, `btn.content.disabled` on Android) and stops the button responding. */
     disabled?: boolean;
     /** The icon, one of the app's. */
     name: IconName;
     /** Called when the button is pressed. */
     onPress?: () => void;
-    /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
+    /**
+     * The look. `plain` by default. iOS draws the others as SwiftUI button styles in a circle: `borderedProminent` for
+     * `filled`, `bordered` for `tonal`, `glass` for `glass` (`bordered` below iOS 26), and `outlined` as a plain button
+     * in a hairline ring. Android draws Material's `IconButton`, `FilledIconButton`, `FilledTonalIconButton` and
+     * `OutlinedIconButton`; Material has no glass, so there `glass` is the tonal one.
+     */
+    variant?: IconButtonVariant;
 };
 export type IconButtonComponent = (props: IconButtonProps) => ReactNode;

package/lib/typescript/atoms/list/list.types.d.ts

@@ -1,4 +1,6 @@
 import type { ReactNode } from 'react';
+/** How the rows are laid out: in a rounded card inset from the edges, or edge to edge. */
+export type ListVariant = 'insetGrouped' | 'plain';
 /**
  * A scrolling list: SwiftUI `List`, Compose `LazyColumn`. It has no height of its own, so it needs one from outside:
  * a `Screen`, or an `Island` with `matchContents={false}` and a height. In an island that sizes itself to its content
@@ -16,7 +18,19 @@ export type ListProps = {
      * until the promise settles, so neither platform needs a `refreshing` flag kept in sync by hand.
      */
     onRefresh?: () => Promise<void>;
-    /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
+    /**
+     * Draws a line between rows. On by default. Off, iOS hides SwiftUI's row separators and Android draws no `Divider`,
+     * for rows that carry their own spacing (cards, media).
+     */
+    separators?: boolean;
+    /** Test identifier, forwarded to the native view. */
     testID?: string;
+    /**
+     * The layout. Each platform's own list by default: `insetGrouped` on iOS, `plain` on Android. `insetGrouped` sets
+     * the rows in a rounded card inset from the edges (SwiftUI's `insetGrouped` list style; on Android a `Card` inside the
+     * column, the way `Form` draws its sections). `plain` runs the rows edge to edge (SwiftUI's `plain` style; Android's
+     * column as it is).
+     */
+    variant?: ListVariant;
 };
 export type ListComponent = (props: ListProps) => ReactNode;

package/lib/typescript/atoms/progress/progress.types.d.ts

@@ -1,13 +1,24 @@
+import type { ColorToken } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 /**
- * A progress bar or ring, tinted `fill.accent.primary`: SwiftUI `ProgressView` (a capacity `Gauge` for a ring with a
- * value, which `ProgressView` cannot draw on iOS) / Compose's `LinearProgressIndicator` and `CircularProgressIndicator`.
+ * A progress bar or ring, tinted `fill.accent.primary` unless `color` names another: SwiftUI `ProgressView` (a capacity
+ * `Gauge` for a ring with a value, which `ProgressView` cannot draw on iOS) / Compose's `LinearProgressIndicator` and
+ * `CircularProgressIndicator`.
  */
 export type ProgressProps = {
     /** What is in progress, for VoiceOver and TalkBack: "Uploading". They read how far along it is themselves. */
     accessibilityLabel?: string;
     /** A circular indicator instead of a bar. Off by default. */
     circular?: boolean;
+    /**
+     * Its colour: `fill.destructive.primary` for storage nearly full, `fill.success.primary` for a goal reached.
+     * `fill.accent.primary` by default. iOS tints the bar or ring with it. Android draws the indicator in it and, for any
+     * colour but the accent, the track in the same colour faded (Material's own track stays under the accent, and an
+     * indeterminate ring has none).
+     */
+    color?: ColorToken;
+    /** Test identifier, forwarded to the native view. */
+    testID?: string;
     /** Between `0` and `1`. Leave it unset for an indeterminate indicator. */
     value?: number;
 };

package/lib/typescript/atoms/slider/slider.ios.d.ts

@@ -1,2 +1,6 @@
 import type { SliderComponent } from './slider.types';
+/**
+ * SwiftUI's slider. `onValueChangeEnd` is its `onEditingChanged(false)`, with the last value the drag reported: the
+ * controlled `value` can still be a render behind when the finger lifts.
+ */
 export declare const Slider: SliderComponent;

package/lib/typescript/atoms/slider/slider.types.d.ts

@@ -9,8 +9,15 @@ export type SliderProps = {
     min?: number;
     /** Called with the new value as the thumb moves. */
     onValueChange?: (value: number) => void;
+    /**
+     * Called once with the final value when the user lets go of the slider: where a seek or a volume commits, rather
+     * than at every step of the drag.
+     */
+    onValueChangeEnd?: (value: number) => void;
     /** The increment between stops; leave it unset for a continuous slider. On Android every stop plays a `tick`. */
     step?: number;
+    /** Test identifier, forwarded to the native view. */
+    testID?: string;
     /** Between `min` and `max`. Controlled: pass back what `onValueChange` reports. */
     value: number;
 };

package/lib/typescript/atoms/switch/switch.types.d.ts

@@ -10,6 +10,8 @@ export type SwitchProps = {
     label?: string;
     /** Called with the new value when the user flips it. On Android a flip plays `toggleOn` / `toggleOff`. */
     onValueChange?: (value: boolean) => void;
+    /** Test identifier, forwarded to the native switch (on Android the switch itself, not the labelled row). */
+    testID?: string;
     /** Whether it is on. Controlled: pass back what `onValueChange` reports. */
     value: boolean;
 };

package/lib/typescript/atoms/text/spans.d.ts

@@ -5,6 +5,8 @@ export type TextSpan = {
     color?: ColorToken;
     text: string;
 };
+/** The string and number children, joined: the text of a `Text` without spans, however JSX split it. */
+export declare const textOf: (children: ReactNode) => string;
 /**
  * The children as runs when any of them is a nested `Text` (`type`, the platform's own component), `null` when they
  * are only text. A span keeps its `color`; anything else it sets is the outer text's.

package/lib/typescript/atoms/text/text.types.d.ts

@@ -4,6 +4,8 @@ import type { ReactNode } from 'react';
 export type TextAlign = 'center' | 'left' | 'right';
 export type TextDecoration = 'none' | 'strikethrough' | 'underline';
 export type TextTransform = 'lowercase' | 'uppercase';
+/** Where the ellipsis goes in a text cut short: its start, its middle or its end. */
+export type TextTruncation = 'head' | 'middle' | 'tail';
 /**
  * SwiftUI `Text` / Compose `Text` in a theme typography variant. A native atom: outside a host, use `RnText`. It takes
  * the native `sx` surface too: padding, a frame (`wide` lines it up by `align`), a background, and the `ios` bucket's
@@ -29,7 +31,7 @@ export type TextProps = ResponsiveSx & AccessibilityProps & {
     color?: ColorToken;
     /** An underline or a strikethrough. */
     decoration?: TextDecoration;
-    /** The most lines it wraps to. iOS truncates the last with an ellipsis; Android clips it. */
+    /** The most lines it wraps to. A text cut short ends with an ellipsis, where `truncation` puts it. */
     numberOfLines?: number;
     /**
      * Sets it in the theme's fixed-width face, at the variant's size and weight: the app's `fonts.mono`, else Menlo on
@@ -46,6 +48,12 @@ export type TextProps = ResponsiveSx & AccessibilityProps & {
     testID?: string;
     /** Upper- or lower-cases the text. Android applies it only when `children` is a plain string. */
     transform?: TextTransform;
+    /**
+     * Where the ellipsis goes in a text cut short. `tail` by default: the end of the last line. `head` keeps the end of
+     * the text and `middle` both of its ends, for a file name, a path or an address. Android puts it at the head or in
+     * the middle of a single line only (`numberOfLines={1}`), as Compose does; a longer text there ends at the tail.
+     */
+    truncation?: TextTruncation;
     /** The typography variant. `body` by default. */
     variant?: TextVariant;
 };

package/lib/typescript/atoms/text-field/text-field-input.d.ts

@@ -0,0 +1,7 @@
+import type { TextFieldAutoCapitalize, TextFieldKeyboard } from './text-field.types';
+/** The capitalisation asked for, else `none` for an address; `undefined` leaves the platform's own. */
+export declare const capitalizationFor: (keyboard: TextFieldKeyboard, autoCapitalize: TextFieldAutoCapitalize | undefined) => TextFieldAutoCapitalize | undefined;
+/** Autocorrection as asked for, else on for everything but an address. */
+export declare const autoCorrectFor: (keyboard: TextFieldKeyboard, autoCorrect: boolean | undefined) => boolean;
+/** A no-op for a ref call that lands after the native view has gone. */
+export declare const ignoreDetachedView: () => undefined;

package/lib/typescript/atoms/text-field/text-field.types.d.ts

@@ -1,9 +1,50 @@
-import type { ReactNode } from 'react';
+import type { ReactNode, Ref } from 'react';
+/** The keyboard a field brings up. */
+export type TextFieldKeyboard = 'decimal' | 'default' | 'email' | 'number' | 'phone' | 'url';
+/** When the keyboard turns Shift on by itself. */
+export type TextFieldAutoCapitalize = 'characters' | 'none' | 'sentences' | 'words';
+/** What the return key says. */
+export type TextFieldSubmitLabel = 'done' | 'go' | 'next' | 'search' | 'send';
+/**
+ * What a field holds, so the system can offer to fill it in: an account's email or password, a new strong password,
+ * the code from a text message, the user's own name, phone number or address.
+ */
+export type TextFieldContentType = 'addressCity' | 'countryName' | 'creditCardNumber' | 'emailAddress' | 'familyName' | 'fullStreetAddress' | 'givenName' | 'name' | 'newPassword' | 'oneTimeCode' | 'password' | 'postalCode' | 'streetAddressLine1' | 'streetAddressLine2' | 'telephoneNumber' | 'username';
+/** Drives a `TextField` from code, as when `onSubmit` moves on to the next field. */
+export type TextFieldRef = {
+    /** Ends editing: the field gives up focus and the keyboard goes down. */
+    blur: () => void;
+    /** Empties the field and calls `onChangeText` with `''`. */
+    clear: () => void;
+    /** Starts editing: the field takes focus and brings up the keyboard. */
+    focus: () => void;
+};
 /**
  * An uncontrolled text field with an optional label above it: SwiftUI `TextField` (`SecureField` when `secure`) /
- * Compose `OutlinedTextField`.
+ * Compose `OutlinedTextField`. `keyboard`, `autoCapitalize`, `autoCorrect` and `contentType` fit it to the text it
+ * takes; `submitLabel`, `onSubmit` and `ref` chain fields so the return key moves on to the next.
  */
 export type TextFieldProps = {
+    /**
+     * When the keyboard turns Shift on by itself: never (`none`), at the start of `sentences`, of `words`, or for all
+     * `characters`. Unset, it is `none` for the `email` and `url` keyboards, and otherwise each platform's own:
+     * `sentences` on iOS, `none` on Android.
+     */
+    autoCapitalize?: TextFieldAutoCapitalize;
+    /**
+     * Lets the keyboard correct words as they are typed and suggest the next. On unless the keyboard is `email` or
+     * `url`, where a correction would only break an address. A `secure` field never corrects.
+     */
+    autoCorrect?: boolean;
+    /** Takes focus, and brings up the keyboard, as soon as the field appears. Off by default. */
+    autoFocus?: boolean;
+    /**
+     * What the field holds, so the system can offer to fill it in: a saved `username` or `password` from the keychain
+     * or a password manager, a strong `newPassword` for a sign-up, the `oneTimeCode` from a text message, the user's own
+     * `emailAddress`, `name`, `telephoneNumber` or address. iOS's `textContentType`; on Android a Compose autofill
+     * hint, which an autofill service (Google's, a password manager) answers.
+     */
+    contentType?: TextFieldContentType;
     /** The text it starts with. Read once, on mount: the field is uncontrolled. */
     defaultValue?: string;
     /** Stops editing and dims the field. On iOS it outranks `error`. */
@@ -14,15 +55,47 @@ export type TextFieldProps = {
      * colour is a pale red in dark mode. `true` marks it without a message.
      */
     error?: boolean | string;
+    /**
+     * The keyboard it brings up. `default` by default. `email` and `url` add their `@` and `.` keys and turn
+     * capitals and corrections off unless `autoCapitalize` or `autoCorrect` say otherwise; `number` is a pad of digits,
+     * `decimal` adds the locale's decimal separator, `phone` is a dial pad. With `secure`, Android brings up its password
+     * keyboard (a numeric one for `number`).
+     */
+    keyboard?: TextFieldKeyboard;
     /** Shown above the field, in `labelMedium`. */
     label?: string;
+    /**
+     * The most characters it takes. What is typed past it is cut off as the user types; `defaultValue` is not. No limit
+     * by default.
+     */
+    maxLength?: number;
     /** Wraps the text and grows the field to fit it. iOS ignores it when `secure`. */
     multiline?: boolean;
-    /** Called with the whole text after every change. */
+    /** Called with the whole text after every change, `clear()` included. */
     onChangeText?: (text: string) => void;
+    /** Called with `true` when the field starts editing and `false` when it stops. */
+    onFocusChange?: (focused: boolean) => void;
+    /**
+     * Called with the whole text when the return key is pressed. A `multiline` field never calls it: its return key
+     * starts a new line. Neither do iOS's `number`, `decimal` and `phone` pads, which have no return key.
+     */
+    onSubmit?: (text: string) => void;
+    /**
+     * Shown in the empty field, in the platform's placeholder colour, until the first character is typed. A hint at
+     * the format (`name@example.com`), not a replacement for `label`.
+     */
+    placeholder?: string;
+    /** `focus`, `blur` and `clear`, for moving to the next field from `onSubmit`. */
+    ref?: Ref<TextFieldRef>;
     /** Masks the text, for a password. */
     secure?: boolean;
-    /** iOS: forwarded to the native field. Android ignores it. */
+    /**
+     * What the return key says. Unset, each platform's own (`return` on iOS). It names the key; what pressing it does
+     * is up to `onSubmit`, so a `next` focuses the following field through its `ref`. Android's `next` also moves focus
+     * to the next field in the same host by itself. A `multiline` field ignores it: its return key starts a new line.
+     */
+    submitLabel?: TextFieldSubmitLabel;
+    /** Test identifier, forwarded to the native field (not the label above it). */
     testID?: string;
 };
 export type TextFieldComponent = (props: TextFieldProps) => ReactNode;

package/lib/typescript/molecules/collapsible/collapsible.types.d.ts

@@ -12,5 +12,7 @@ export type CollapsibleProps = {
     label: string;
     /** The user pressed the row; it passes the state the row asks for. */
     onExpandedChange: (expanded: boolean) => void;
+    /** Test identifier: on SwiftUI's `DisclosureGroup` on iOS, on the pressable row on Android. */
+    testID?: string;
 };
 export type CollapsibleComponent = (props: CollapsibleProps) => ReactNode;

package/lib/typescript/molecules/radio-group/radio-group.types.d.ts

@@ -11,10 +11,14 @@ export type RadioOption = {
  * native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type RadioGroupProps = {
+    /** Stops the user changing the selection, and dims the options. */
+    disabled?: boolean;
     /** The user pressed an option; it passes that option's `value`. */
     onValueChange?: (value: string) => void;
     /** The choices, top to bottom. */
     options: RadioOption[];
+    /** Test identifier, on the whole group. Reach an option by its label. */
+    testID?: string;
     /** The selected option's `value`. Update it from `onValueChange`. */
     value: string;
 };

package/lib/typescript/molecules/search-bar/search-bar.types.d.ts

@@ -1,11 +1,21 @@
 import type { ReactNode } from 'react';
+import type { TextFieldAutoCapitalize } from '../../atoms/text-field';
 /**
  * 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.
+ * while there is text. The keyboard's return key reads Search, and a query is taken as typed: no capitals and no
+ * corrections unless asked for. The React Native tier: it needs no host.
  */
 export type SearchBarProps = {
+    /** When the keyboard turns Shift on by itself. `none` by default: a query is not a sentence. */
+    autoCapitalize?: TextFieldAutoCapitalize;
+    /** Lets the keyboard correct words as they are typed. Off by default, so a query is searched as typed. */
+    autoCorrect?: boolean;
+    /** Takes focus, and brings up the keyboard, as soon as the field appears. Off by default. */
+    autoFocus?: boolean;
     /** Every edit, and `''` when the clear button is pressed. */
     onChangeText?: (text: string) => void;
+    /** Called with the query when the keyboard's Search key is pressed. The keyboard goes down after it. */
+    onSubmit?: (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`. */

package/lib/typescript/molecules/stepper/stepper.ios.d.ts

@@ -2,6 +2,7 @@ import type { StepperComponent } from './stepper.types';
 /**
  * SwiftUI's `Stepper` at the end of a row, the label leading and the value just before the control — the way iOS's own
  * settings show a stepped value. The value rolls to the next one (`numericText`), up or down with the change, in
- * monospaced digits so the row does not jump. With motion reduced it cross-fades instead.
+ * monospaced digits so the row does not jump. With motion reduced it cross-fades instead. Its buttons are labelled by
+ * the system, so `decrementLabel` and `incrementLabel` are Android's alone.
  */
 export declare const Stepper: StepperComponent;

package/lib/typescript/molecules/stepper/stepper.types.d.ts

@@ -4,6 +4,18 @@ import type { ReactNode } from 'react';
  * two icon buttons in a row. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type StepperProps = {
+    /**
+     * What TalkBack says for the minus button. `Decrement` by default: pass the app's own words, in its language.
+     * Android only. iOS ignores it: its native stepper labels its buttons itself, in the device's language.
+     */
+    decrementLabel?: string;
+    /** Stops the user changing the value, and dims the row. */
+    disabled?: boolean;
+    /**
+     * What TalkBack says for the plus button. `Increment` by default: pass the app's own words, in its language. Android
+     * only. iOS ignores it: its native stepper labels its buttons itself, in the device's language.
+     */
+    incrementLabel?: string;
     /** The leading text. The value is shown too: before the control on iOS, between the buttons on Android. */
     label: string;
     /** The highest value. When unset, Android has no upper limit and iOS stops at `100`. */
@@ -14,6 +26,11 @@ export type StepperProps = {
     onValueChange: (value: number) => void;
     /** How much one press adds or takes away. `1` by default. */
     step?: number;
+    /**
+     * Test identifier, on the control rather than the row: SwiftUI's `Stepper` on iOS, the minus and plus buttons with
+     * the value between them on Android. Reach a button by what screen readers say for it.
+     */
+    testID?: string;
     /** The current value. Update it from `onValueChange`. iOS's native stepper counts in whole numbers. */
     value: number;
 };

package/lib/typescript/organisms/action-sheet/action-sheet.ios.d.ts

@@ -1,2 +1,6 @@
 import type { ActionSheetComponent } from './action-sheet.types';
+/**
+ * `titleVisibility="visible"`: left to `automatic`, SwiftUI drops the title of a dialog presented as an action sheet,
+ * and the actions lose what they are about.
+ */
 export declare const ActionSheet: ActionSheetComponent;

package/lib/typescript/organisms/action-sheet/action-sheet.types.d.ts

@@ -2,14 +2,19 @@ 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>`.
+ * under the title and message on Android. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type ActionSheetProps = {
-    /** The choices, top to bottom. Picking one closes the sheet. */
+    /** The choices, top to bottom. Picking one closes the sheet. A `disabled` one stays in the list, greyed. */
     actions: MenuAction[];
+    /**
+     * A line under the title saying what the choice is about: "The photo will be removed from all your devices." Unset,
+     * the title stands alone.
+     */
+    message?: string;
     /** 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. */
+    /** The heading above the actions, shown on both platforms. */
     title: string;
     /** Presents the sheet while true. */
     visible: boolean;

package/lib/typescript/organisms/alert/alert.types.d.ts

@@ -1,9 +1,14 @@
 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>`.
+ * A modal alert with a confirm button and a cancel button (or the confirm button alone): SwiftUI's alert on iOS,
+ * Material's `AlertDialog` on Android. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type AlertProps = {
+    /**
+     * The cancel button's label, in the app's language: "Zrušit". `Cancel` by default. `null` leaves the button out, for
+     * an alert that only informs and is closed by its confirm button alone ("OK").
+     */
+    cancelLabel?: string | null;
     /** 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. */
@@ -12,7 +17,7 @@ export type AlertProps = {
     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. */
+    /** The alert closed (any of its buttons, or on Android a tap outside or back), so turn `visible` off. */
     onDismiss: () => void;
     /** The alert's heading. */
     title: string;

package/lib/typescript/organisms/menu/menu-parts.d.ts

@@ -0,0 +1,14 @@
+import type { ColorToken } from '@hzblj/kara-theme';
+import type { IconName } from '../../atoms/icon';
+import type { MenuAction, MenuProps } from './menu.types';
+/**
+ * An action's colour in a row kara draws itself (the Android menus and sheets): greyed when disabled, as `IconButton`
+ * greys, red when destructive. A Compose `DropdownMenuItem` cannot grey its own text here, since the text sets its
+ * colour explicitly.
+ */
+export declare const menuActionColor: ({ destructive, disabled }: MenuAction) => ColorToken;
+/** A trigger with no text: the props' union guarantees its icon and the words a screen reader says for it. */
+export declare const isIconOnly: (props: MenuProps) => props is MenuProps & {
+    accessibilityLabel: string;
+    icon: IconName;
+};

package/lib/typescript/organisms/menu/menu.types.d.ts

@@ -8,8 +8,13 @@ export type MenuAction = {
      */
     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.
+     * Greys the action out and stops it responding, for one that does not apply right now: "Paste" with nothing copied.
+     * Off by default. `FabMenu` ignores it on Android, where Material's FAB menu items have no disabled state.
+     */
+    disabled?: boolean;
+    /**
+     * One of the app's icons, before the label. `Menu`, `ContextMenu` and `FabMenu` show it on both platforms,
+     * `ActionSheet` on Android only: an iOS confirmation dialog draws text alone.
      */
     icon?: IconName;
     /** The action's text. Rows are keyed by it, so keep labels unique within one list. */
@@ -17,14 +22,37 @@ export type MenuAction = {
     /** Called when the action is chosen; the menu closes by itself. */
     onPress: () => void;
 };
+/** What the trigger needs: its text, or an icon and the words a screen reader says for it. */
+type MenuTrigger = {
+    label: string;
+} | {
+    accessibilityLabel: string;
+    icon: IconName;
+};
 /**
- * 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>`.
+ * A button that opens a list of actions: a SwiftUI `Menu` on iOS, a Material dropdown anchored to it on Android. The
+ * trigger is text, an icon and text, or an icon alone. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
-export type MenuProps = {
+export type MenuProps = MenuTrigger & {
+    /**
+     * What VoiceOver and TalkBack say for the trigger: "More options". Required with an `icon` and no `label`, since an
+     * icon has no words of its own. With a label, it replaces the label for screen readers.
+     */
+    accessibilityLabel?: string;
     /** 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;
+    /**
+     * One of the app's icons on the trigger. Before the `label`, in the same colour, when there is one; alone, the
+     * trigger is drawn as an `IconButton` (`content.primary`, in a 44pt target on iOS and 48dp on Android) and needs an
+     * `accessibilityLabel`.
+     */
+    icon?: IconName;
+    /**
+     * The trigger's text. Android draws it in the accent colour, with a chevron. Required unless there is an `icon`.
+     */
+    label?: string;
+    /** Test identifier, forwarded to the trigger. Reach an action by its label once the menu is open. */
+    testID?: string;
 };
 export type MenuComponent = (props: MenuProps) => ReactNode;
+export {};

package/lib/typescript/organisms/sheet/sheet.types.d.ts

@@ -46,7 +46,7 @@ export type SheetRef = {
  * one; native atoms in its content go in an `Island`.
  */
 export type SheetProps = {
-    /** The sheet's colour. `surface.primary` by default. */
+    /** The sheet's colour. `surface.primary` by default; ignored on iOS with `systemBackground`. */
     bg?: ColorToken;
     /** The content. A `<Sheet.Header>` among the direct children becomes the native header instead. */
     children: ReactNode;
@@ -75,6 +75,12 @@ export type SheetProps = {
      * and a header scrolls with the iOS 26 edge effect. Off by default; set it with a scrolling body.
      */
     scrollable?: boolean;
+    /**
+     * iOS: the system's own sheet background instead of `bg` — untinted Liquid Glass on iOS 26, a material blur before
+     * it — for a sheet that floats over content it should let through, like a map. Keep the content free of fills. Android
+     * keeps `bg`. Off by default.
+     */
+    systemBackground?: boolean;
     /** Test identifier, forwarded to the native sheet. */
     testID?: string;
     /** Presents the sheet while true; going false dismisses it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzblj/kara-components",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "The atoms, molecules, organisms and templates of @hzblj/kara-ui — real SwiftUI and Jetpack Compose views through @expo/ui.",
   "author": "Jan Blazej",
   "license": "MIT",
@@ -61,9 +61,9 @@
   "dependencies": {
     "@hzblj/expo-native-icons": "^0.1.0",
     "@hzblj/expo-rich-haptics": "^0.1.0",
-    "@hzblj/kara-native": "^0.17.0",
-    "@hzblj/kara-sx": "^0.17.0",
-    "@hzblj/kara-theme": "^0.17.0",
+    "@hzblj/kara-native": "^0.18.0",
+    "@hzblj/kara-sx": "^0.18.0",
+    "@hzblj/kara-theme": "^0.18.0",
     "sf-symbols-typescript": "^2.2.0"
   },
   "peerDependencies": {

package/src/atoms/badge/badge.android.tsx

@@ -1,17 +1,24 @@
 import {Badge as ComposeBadge, Text as ComposeText} 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 {BadgeComponent, BadgeProps} from './badge.types'
 import {BADGE_TOKENS} from './badge-tokens'
 
 /** Material's badge. Its content is a Compose `Text` — `@expo/ui`'s badge takes composable content, not a string. */
-export const Badge: BadgeComponent = ({label, tone = 'neutral'}: BadgeProps) => {
+export const Badge: BadgeComponent = ({label, testID, tone = 'neutral'}: BadgeProps) => {
   useHostGuard('Badge')
   const theme = useAppTheme()
   const tokens = BADGE_TOKENS[tone]
+  const modifiers = useMemo(() => (testID ? [testIdModifier(testID)] : undefined), [testID])
 
   return (
-    <ComposeBadge containerColor={theme.color(tokens.fill)} contentColor={theme.color(tokens.content)}>
+    <ComposeBadge
+      containerColor={theme.color(tokens.fill)}
+      contentColor={theme.color(tokens.content)}
+      modifiers={modifiers}
+    >
       <ComposeText color={theme.colorString(tokens.content)} style={theme.typography.captionMedium}>
         {label}
       </ComposeText>