@hzblj/kara-components 0.9.0 → 0.10.0

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

@@ -3,7 +3,7 @@ import type {ReactNode} from 'react'
 import type {MenuAction} from '../menu'
 
 /**
- * A context menu on a React Native subtree — a card in a list, say — opened by a long press. iOS: a
+ * A context menu on a React Native subtree (a card in a list, say), opened by a long press. iOS: a
  * `UIContextMenuInteraction`, with an optional React Native `preview` lifted while the menu is open and a callback for
  * a tap on it. Android, where Material has no lifted preview: a ripple and the long-press haptic, then a Material
  * dropdown where the finger is, with the trigger highlighted while it is open. The trigger is ordinary React Native layout, so it
@@ -14,35 +14,35 @@ export type ContextMenuProps = ResponsiveViewSx & {
   actions: MenuAction[]
   /** The trigger, laid out as usual. */
   children: ReactNode
-  /** iOS: the user tapped the lifted preview, committing to it — open the detail the card stands for. */
+  /** iOS: the user tapped the lifted preview, committing to it. Open the detail the card stands for. */
   onPreviewPress?: () => void
   /**
-   * iOS: lifted in place of the trigger while the menu is open — a larger version of the card, say. A snapshot of the
+   * iOS: lifted in place of the trigger while the menu is open (a larger version of the card, say). A snapshot of the
    * trigger when unset. Mounted only once a finger has rested on the trigger, so a list of cards does not pay for
    * every preview up front.
    */
   preview?: ReactNode
   /**
    * iOS: how the preview leaves once tapped, before `onPreviewPress`. `zoom`: its photo grows straight into the pushed
-   * screen, the way the App Store expands a preview — needs a `ZoomTransition.Source` (`@hzblj/kara-ui/router`) in the
-   * trigger, a `preview` and iOS 18, and shrinks back like `dismiss` otherwise. `pop`: UIKit's default, the preview
+   * screen, the way the App Store expands a preview. It needs a `ZoomTransition.Source` (`@hzblj/kara-ui/router`) in
+   * the trigger, a `preview` and iOS 18, and shrinks back like `dismiss` otherwise. `pop`: UIKit's default, the preview
    * flies out. `dismiss`: it shrinks back onto the trigger first. Default: `zoom` when the trigger holds a
    * `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. */
+  /** 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`. */
+/** 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. */
+  /** The region: a button inside the card, say. */
   children: ReactNode
 }
 
 export type ContextMenuComponent = ((props: ContextMenuProps) => ReactNode) & {
   /**
-   * A region of the trigger that must not open the menu — a button inside the card. On iOS the interaction covers the
+   * A region of the trigger that must not open the menu: a button inside the card. On iOS the interaction covers the
    * whole trigger, so a long press on that button would otherwise open the card's menu.
    */
   Exclusion: (props: ContextMenuExclusionProps) => ReactNode

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

@@ -4,16 +4,16 @@ import type {IconName} from '../../atoms/icon'
 import type {MenuAction} from '../menu'
 
 /**
- * A floating action button that unfolds into its actions. Android: Material 3 Expressive's `FloatingActionButtonMenu`
- * — the button turns into a close and the actions rise above it as labelled pills. iOS: the same button as the label
- * of a SwiftUI `Menu`. A native atom — it renders inside `<Screen>` or `<Island>`.
+ * A floating action button that unfolds into its actions. Android: Material 3 Expressive's `FloatingActionButtonMenu`,
+ * where the button turns into a close and the actions rise above it as labelled pills. iOS: the same button as the
+ * label 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. */
+  /** 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. */
+  /** Test identifier, forwarded to the SwiftUI `Menu`. iOS only; Android ignores it. */
   testID?: string
 }
 

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

@@ -1,7 +1,7 @@
 import type {ReactNode} from 'react'
 
 /**
- * A settings form — SwiftUI `Form` with its grouped sections, Material cards on Android. On iOS it scrolls like a
+ * A settings form: SwiftUI `Form` with its grouped sections, Material cards on Android. On iOS it scrolls like a
  * `List`, so it needs a height from outside: a `Screen`, or an `Island` with `matchContents={false}` and a height. In
  * an island that sizes itself to its content it has no height and shows nothing.
  */

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

@@ -5,7 +5,7 @@ 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
+   * Draws the action in the destructive colour (the system's destructive role on iOS). `FabMenu` ignores it on
    * Android.
    */
   destructive?: boolean
@@ -22,7 +22,7 @@ export type MenuAction = {
 
 /**
  * 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 native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type MenuProps = {
   /** The menu's actions, top to bottom. */

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

@@ -9,13 +9,13 @@ export type SheetDetent = 'auto' | number
 
 /**
  * `center` is iOS's own, `leading` Material's. `large` puts the title above the content in a large face, and once
- * that scrolls under the bar the bar's own title fades in — centred on iOS, leading on Android.
+ * that scrolls under the bar the bar's own title fades in (centred on iOS, leading on Android).
  */
 export type SheetTitleStyle = 'center' | 'large' | 'leading'
 
 /**
  * The sheet's header: a `NavigationBar` with the title and items, and anything else that should stay put above the
- * content (`children` — a segmented control, a search hint). On iOS 26 a scrollable sheet's content scrolls under it
+ * content (`children`: a segmented control, a search hint). On iOS 26 a scrollable sheet's content scrolls under it
  * with the system's scroll edge effect; elsewhere it sits above the content.
  */
 export type SheetHeaderProps = {
@@ -27,11 +27,11 @@ 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`. */
+  /** The title: in the bar, or above the content with a `large` `titleStyle`. */
   title?: string
   /** `center` by default. */
   titleStyle?: SheetTitleStyle
-  /** In screen order, toward the trailing edge — the close item, by convention. */
+  /** In screen order, toward the trailing edge: the close item, by convention. */
   trailingItems?: NavigationBarItem[]
 }
 
@@ -39,14 +39,14 @@ export type SheetHeaderProps = {
 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. */
+  /** Presents at a detent, the first by default. */
   present: (detentIndex?: number) => Promise<void>
   /** Moves to another detent. */
   resize: (detentIndex: number) => Promise<void>
 }
 
 /**
- * A native sheet — `UISheetPresentationController` on iOS, Material's bottom sheet on Android — with an optional
+ * A native sheet (`UISheetPresentationController` on iOS, Material's bottom sheet on Android) with an optional
  * native header (`<Sheet.Header>` as a direct child). The React Native tier: it needs no host, and must not sit inside
  * one; native atoms in its content go in an `Island`.
  */
@@ -55,7 +55,7 @@ export type SheetProps = {
   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. */
+  /** Where the sheet can rest, smallest first. `['auto']` (fit the content) by default. */
   detents?: SheetDetent[]
   /** Dims what is behind. On by default. */
   dimmed?: boolean
@@ -67,9 +67,9 @@ export type SheetProps = {
   footer?: ReactElement
   /** The drag handle. On by default. */
   grabber?: boolean
-  /** The user dismissed it — `visible` going false does not call this. */
+  /** The user dismissed it; `visible` going false does not call this. */
   onDismiss: () => void
-  /** The sheet moved to another detent — its index in `detents`. */
+  /** The sheet moved to another detent: its index in `detents`. */
   onDetentChange?: (detentIndex: number) => void
   /** The sheet finished presenting. */
   onPresent?: () => void
@@ -77,7 +77,7 @@ export type SheetProps = {
   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.
+   * 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. */
@@ -92,7 +92,7 @@ export type SheetScrollHandler = (event: NativeSyntheticEvent<NativeScrollEvent>
 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. */
+  /** 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
@@ -105,7 +105,7 @@ export type SheetScrollContextValue = {
 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`. */
+  /** 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

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

@@ -9,7 +9,7 @@ export type SnackbarProps = {
   actionLabel?: string
   /** The message. */
   message: string
-  /** The action was pressed. The snackbar stays up — turn `visible` off to hide it. */
+  /** 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

package/src/organisms/swipe-actions/swipe-actions.types.ts

@@ -7,26 +7,26 @@ import type {IconName} from '../../atoms/icon'
 export type SwipeAction = {
   /** Fills the button with `fill.destructive.primary` unless `tint` says otherwise. */
   destructive?: boolean
-  /** One of the app's icons, on the button — a round one on iOS 26, as in Mail, a filled stadium on Android. */
+  /** One of the app's icons, on the button: a round one on iOS 26, as in Mail, a filled stadium on Android. */
   icon: IconName
   /**
-   * The action's name, written under the button — before iOS 26 a row of the usual height shows the icon alone and
+   * The action's name, written under the button; before iOS 26 a row of the usual height shows the icon alone and
    * keeps the label for VoiceOver. Actions are keyed by it, so keep labels unique within one row.
    */
   label: string
   /** Called when the button is pressed. The row closes by itself. */
   onPress: () => void
   /**
-   * The button's fill — `fill.destructive.primary` for a destructive action, `fill.accent.primary` otherwise. The icon
+   * The button's fill: `fill.destructive.primary` for a destructive action, `fill.accent.primary` otherwise. The icon
    * on it is white, so pick a fill that holds white in both appearances.
    */
   tint?: ColorToken
 }
 
 /**
- * A list row with buttons behind it, uncovered by a swipe — SwiftUI's `swipeActions` on iOS, and on Android, where
+ * A list row with buttons behind it, uncovered by a swipe. SwiftUI's `swipeActions` on iOS, and on Android, where
  * Compose has none, kara's own: the row slides on an anchored drag and the buttons show in the strip it leaves. One
- * row is open at a time on both; a tap on an open row closes it. A native organism — it belongs inside a `List`.
+ * row is open at a time on both; a tap on an open row closes it. A native organism: it belongs inside a `List`.
  */
 export type SwipeActionsProps = {
   /**

package/src/templates/screen/screen.types.ts

@@ -2,7 +2,7 @@ import type {Sx} from '@hzblj/kara-sx'
 import type {ReactNode} from 'react'
 
 /**
- * The full-bleed native host a screen starts with — a SwiftUI or Compose `Host` filling its parent, so native atoms
+ * The full-bleed native host a screen starts with: a SwiftUI or Compose `Host` filling its parent, so native atoms
  * render anywhere inside it. The background runs to the edges; the content keeps clear of the status bar where the
  * screen covers it (no navigation bar above), on Android as SwiftUI's safe area does on iOS.
  */
@@ -13,7 +13,7 @@ export type ScreenProps = {
   children?: ReactNode
   /** Keeps the content where it is when the keyboard opens, instead of avoiding it. Android reads it once, on mount. */
   ignoreKeyboardInset?: boolean
-  /** Test identifier — on the host view on iOS, on the view around it on Android. */
+  /** Test identifier, on the host view on iOS and on the view around it on Android. */
   testID?: string
 }
 

package/lib/module/platform-support.js

@@ -1,19 +0,0 @@
-"use strict";
-
-const warned = new Set();
-
-/**
- * Announces an atom that only one platform can implement. The stub still satisfies the shared
- * component type, so `contract.check.ts` keeps both files honest — this just makes the gap loud
- * in dev instead of leaving a control that mysteriously never appears.
- *
- * Warns once per atom: the gap is permanent, so repeating it every render would be noise.
- */
-export const warnUnsupported = (atom, platform) => {
-  if (!__DEV__ || warned.has(atom)) {
-    return;
-  }
-  warned.add(atom);
-  console.error(`[kara-ui] <${atom}> has no ${platform} implementation and renders nothing there. Branch on Platform.OS at the call site.`);
-};
-//# sourceMappingURL=platform-support.js.map

package/lib/module/platform-support.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["warned","Set","warnUnsupported","atom","platform","__DEV__","has","add","console","error"],"sourceRoot":"../../src","sources":["platform-support.ts"],"mappings":";;AAAA,MAAMA,MAAM,GAAG,IAAIC,GAAG,CAAS,CAAC;;AAEhC;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAAe,GAAGA,CAACC,IAAY,EAAEC,QAA2B,KAAK;EAC5E,IAAI,CAACC,OAAO,IAAIL,MAAM,CAACM,GAAG,CAACH,IAAI,CAAC,EAAE;IAChC;EACF;EAEAH,MAAM,CAACO,GAAG,CAACJ,IAAI,CAAC;EAEhBK,OAAO,CAACC,KAAK,CACX,cAAcN,IAAI,YAAYC,QAAQ,oFACxC,CAAC;AACH,CAAC","ignoreList":[]}

package/lib/typescript/platform-support.d.ts

@@ -1,8 +0,0 @@
-/**
- * Announces an atom that only one platform can implement. The stub still satisfies the shared
- * component type, so `contract.check.ts` keeps both files honest — this just makes the gap loud
- * in dev instead of leaving a control that mysteriously never appears.
- *
- * Warns once per atom: the gap is permanent, so repeating it every render would be noise.
- */
-export declare const warnUnsupported: (atom: string, platform: 'Android' | 'iOS') => void;

package/src/platform-support.ts

@@ -1,20 +0,0 @@
-const warned = new Set<string>()
-
-/**
- * Announces an atom that only one platform can implement. The stub still satisfies the shared
- * component type, so `contract.check.ts` keeps both files honest — this just makes the gap loud
- * in dev instead of leaving a control that mysteriously never appears.
- *
- * Warns once per atom: the gap is permanent, so repeating it every render would be noise.
- */
-export const warnUnsupported = (atom: string, platform: 'Android' | 'iOS') => {
-  if (!__DEV__ || warned.has(atom)) {
-    return
-  }
-
-  warned.add(atom)
-
-  console.error(
-    `[kara-ui] <${atom}> has no ${platform} implementation and renders nothing there. Branch on Platform.OS at the call site.`
-  )
-}