@hzblj/kara-ui 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/README.md +33 -157
  3. package/package.json +9 -7
package/CHANGELOG.md CHANGED
@@ -1,5 +1,23 @@
1
1
  # @hzblj/kara-ui
2
2
 
3
+ ## 0.3.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [`f84ffd5`](https://github.com/hzblj/kara-ui/commit/f84ffd52954a5e7052541c8682787137de205a28) Thanks [@hzblj](https://github.com/hzblj)! - Native sheets with a native header. `Sheet` is now a TrueSheet (`@lodev09/react-native-true-sheet`, a new peer dependency) with `<Sheet.Header>` — a real navigation bar with a centred, leading or large title that hands over to the bar as it scrolls away, items on either side, and on iOS 26 the content scrolls under it with the soft edge effect — plus `<Sheet.ScrollView>`, `useSheetScroll`, detents, a footer and a ref (`present`/`dismiss`/`resize`). It is React Native tier now: no host, native atoms inside go in an `Island`. `fitToContents` is replaced by `detents` (`['auto']` by default).
8
+
9
+ `NavigationBar` takes `leadingItems` / `trailingItems` instead of `onBack` / `onClose`: `back`, `close` or an app `icon`, on either side and in any order; on iOS 26 neighbours share a glass capsule unless an item is `separated`. Also `titleAlignment`, `titleVisible`, `inverted` and an iOS `search` field. On Android it is now Material's native top app bar.
10
+
11
+ ### Patch Changes
12
+
13
+ - Updated dependencies [[`f84ffd5`](https://github.com/hzblj/kara-ui/commit/f84ffd52954a5e7052541c8682787137de205a28)]:
14
+ - @hzblj/kara-components@0.3.0
15
+ - @hzblj/kara-native@0.3.0
16
+ - @hzblj/kara-router@0.3.0
17
+ - @hzblj/kara-theme@0.3.0
18
+ - @hzblj/kara-sx@0.3.0
19
+ - @hzblj/kara-expo-plugin@0.3.0
20
+
3
21
  ## 0.2.1
4
22
 
5
23
  ### Patch Changes
package/README.md CHANGED
@@ -1,196 +1,72 @@
1
1
  # @hzblj/kara-ui
2
2
 
3
- A native-first design system for Expo. Components render **real SwiftUI and Jetpack Compose views**
4
- through [`@expo/ui`](https://docs.expo.dev/versions/latest/sdk/ui/), not styled `View`s, and every
5
- one of them is styled through one token-typed `sx` surface — `p="s16"`, `bg="surface.primary"`,
6
- `borderRadius="large"`. A raw number or hex does not type-check.
7
-
8
- - **Platform colours by default.** Most tokens resolve to UIKit semantic colours on iOS and Material 3
9
- roles on Android, so light/dark, increased contrast and Material You are the platform's job.
10
- - **The platform's typeface by default.** SF Pro on iOS, Roboto on Android, with your own exact sizes
11
- that still follow Dynamic Type. Bring your own font with one config entry.
12
- - **Override anything, keep the types.** Colours, fonts and the Android seed are set once on the
13
- provider; every token name stays the same, so every component keeps type-checking.
14
- - **Atomic tiers.** Atoms, molecules, organisms and a `Screen` template — plus a React Native tier
15
- (`Box`, `RnView`, `RnText`, lists) with the same `sx` surface for layouts that host native views.
16
-
17
- React Native and Expo only (iOS and Android), Expo SDK 57. A development build is required — the
18
- package includes a native module.
3
+ A native-first design system for Expo. Components render real SwiftUI and Jetpack Compose views, styled through one
4
+ token-typed `sx` surface. Platform colours and typeface by default, your own through the theme.
5
+
6
+ iOS and Android, Expo SDK 57, development build required.
19
7
 
20
8
  ## Install
21
9
 
22
10
  ```bash
23
- npx expo install @hzblj/kara-ui @expo/ui @shopify/flash-list expo-haptics expo-image react-native-reanimated react-native-worklets
24
- # optional, for `@hzblj/kara-ui/router` (native tabs)
25
- npx expo install expo-router
11
+ npx expo install @hzblj/kara-ui @expo/ui @lodev09/react-native-true-sheet @shopify/flash-list expo-haptics expo-image react-native-reanimated react-native-worklets
12
+ npx expo install expo-router # optional, for native tabs
26
13
  ```
27
14
 
28
- Then rebuild the native app (`npx expo prebuild` / `npx expo run:ios`).
29
-
30
15
  ## Use
31
16
 
32
17
  ```tsx
33
18
  import {Button, KaraProvider, Screen, Text, VStack} from '@hzblj/kara-ui'
34
19
 
35
- export default function App() {
36
- return (
37
- <KaraProvider>
38
- <Screen>
39
- <VStack p="s16" spacing="s12" wide>
40
- <Text variant="headingS">Hello</Text>
41
- <Button label="Continue" variant="accent" wide />
42
- </VStack>
43
- </Screen>
44
- </KaraProvider>
45
- )
46
- }
20
+ export const App = () => (
21
+ <KaraProvider>
22
+ <Screen>
23
+ <VStack p="s16" spacing="s12" wide>
24
+ <Text variant="headingS">Hello</Text>
25
+ <Button label="Continue" />
26
+ </VStack>
27
+ </Screen>
28
+ </KaraProvider>
29
+ )
47
30
  ```
48
31
 
49
- **Native views need a host.** `@expo/ui`-backed components render inside `<Screen>` (full-bleed,
50
- one per screen) or `<Island>` (a native island inside React Native layout). Outside one they do not
51
- appear, and development builds warn.
52
-
53
- `KaraProvider` takes `themePreference` (`'system' | 'light' | 'dark'`). A pinned preference is pushed
54
- down to the platform too, so the SwiftUI/Compose hosts and every `PlatformColor` agree.
32
+ Native components render inside `<Screen>` or `<Island>`. The `Rn*` components (`RnText`, `RnScrollView`, …) are plain
33
+ React Native views with the same `sx` props.
55
34
 
56
35
  ## Theme
57
36
 
58
- Pass a theme to the provider. Declare it at module scope so its identity is stable:
59
-
60
37
  ```tsx
61
- import {adaptive, defineTheme, KaraProvider} from '@hzblj/kara-ui'
62
-
63
38
  const theme = defineTheme({
64
- // Override any token's value — a hex, `adaptive({light, dark})`, or `native({ios, android})`.
65
- colors: {
66
- content: {accent: adaptive({dark: '#a5b4fc', light: '#4338ca'})},
67
- fill: {accent: {primary: '#4f46e5'}},
68
- },
69
- // Your own typeface, by role and weight — the names you registered the files under (e.g. with expo-font).
70
- fonts: {
71
- text: {regular: 'Inter-Regular', medium: 'Inter-Medium', semibold: 'Inter-SemiBold', bold: 'Inter-Bold'},
72
- display: {medium: 'InterDisplay-Medium'}, // headings; falls back to `text`
73
- },
74
- // The colour Android's Material 3 scheme grows from.
75
- materialSeed: '#4f46e5',
39
+ colors: {fill: {accent: {primary: '#4f46e5'}}},
40
+ fonts: {text: {regular: 'Inter-Regular', medium: 'Inter-Medium'}},
41
+ dynamicColor: true, // Material You on Android 12+
76
42
  })
77
43
 
78
- export const App = ({children}) => <KaraProvider theme={theme}>{children}</KaraProvider>
79
- ```
80
-
81
- - **Colours** are merged over the defaults; you override values, never token names. A token that
82
- supports dimming (`fill.accent.base:o50`) only accepts a value that stays dimmable — a hex,
83
- `adaptive(...)`, or `native({android, light, dark})` — never a UIKit semantic colour.
84
- - **Fonts** are optional. Without them, text uses the platform's face. With them, each text variant
85
- picks the face for its weight (falling back to the role's `regular`). Native text keeps scaling with
86
- Dynamic Type either way.
87
- - Read the resolved theme anywhere with `useAppTheme()`: `theme.color('content.accent')`,
88
- `theme.typography.body`, `theme.dark`.
89
-
90
- ### Material You (Android)
91
-
92
- ```tsx
93
- const theme = defineTheme({dynamicColor: true})
94
- ```
95
-
96
- On Android 12+ the whole Material scheme follows the device wallpaper, and the accent tokens take
97
- Material's `primary` roles — buttons, switches, links, FABs and tinted backgrounds move with it. A new
98
- wallpaper is picked up when the app returns to the foreground, without a restart. Below Android 12 the
99
- scheme grows from `materialSeed` instead. iOS has no wallpaper colours and keeps your accent; every
100
- dimmed token (`:o50`) keeps working on both. `theme.dynamicColor` tells whether it is active on this
101
- device.
102
-
103
- `materialSeed: null` is the halfway house: the wallpaper's neutrals and controls, your own accent.
104
-
105
- ### iOS semantic colours
106
-
107
- The theme decides which colour a token *uses*. To redefine what a UIKit semantic colour *is*, app-wide
108
- and natively (e.g. `labelColor`), use the config plugin:
109
-
110
- ```ts
111
- plugins: [['@hzblj/kara-ui', {icons: {source: './assets/icons'}, iosSemanticColors: {file: './ios-colors.json'}}]]
44
+ <KaraProvider theme={theme} themePreference="system">…</KaraProvider>
112
45
  ```
113
46
 
114
- `ios-colors.json` maps semantic names (with their `Color` suffix) to `{light, dark, highContrastLight?, highContrastDark?}`.
115
- It has no Android counterpart; use `colors` in the theme for both platforms.
116
-
117
47
  ## Icons
118
48
 
119
- kara-ui ships no icon set — your app brings its own SVGs, and kara turns them into **native assets** on both
120
- platforms. No icon font, no JavaScript rendering.
121
-
122
49
  ```ts
123
50
  // app.config.ts
124
51
  plugins: [['@hzblj/kara-ui', {icons: {source: './assets/icons'}}]]
125
52
  ```
126
53
 
127
- ```
128
- assets/icons/
129
- bolt.svg → <Icon name="bolt" />
130
- share.svg → iOS
131
- share.android.svg → Android's own share glyph
132
- ```
54
+ Every SVG in the folder becomes a native icon at prebuild: `bolt.svg` → `<Icon name="bolt" />`.
55
+
56
+ ## Sheets
133
57
 
134
58
  ```tsx
135
- <Icon name="bolt" /> // inside <Screen> / <Island>: SwiftUI Image · Compose Icon
136
- <RnIcon name="bolt" color="content.accent" /> // anywhere: UIImageView · ImageView
137
- <Tabs.Screen icon="home" selectedIcon="home-filled" name="index" title="Home" />
59
+ <Sheet onDismiss={close} visible={open}>
60
+ <Sheet.Header title="Choose a size" trailingItems={[{type: 'close', onPress: close}]} />
61
+ <Content />
62
+ </Sheet>
138
63
  ```
139
64
 
140
- - At prebuild every SVG becomes a template image set in the iOS asset catalog (vector data kept, so it scales crisply)
141
- and a vector drawable in Android's resources. A new or changed icon needs `npx expo prebuild`.
142
- - Whenever the app config is read — `expo start` included — the plugin writes `kara-icons.d.ts`, so `name` only accepts
143
- icons that exist. `npx kara-icons ./assets/icons` does the same without Expo (CI).
144
- - One single-colour glyph per file, made of `<path>`s (`fill-rule="evenodd"` is fine). Groups, clips, masks and strokes
145
- must be flattened first — the plugin fails loudly rather than shipping a broken icon. The platform tints every icon
146
- with the `color` token.
147
- - `x.ios.svg` / `x.android.svg` replace `x.svg` on that platform, for glyphs that differ (share, back).
148
-
149
- ## Components
150
-
151
- | Tier | |
152
- | --- | --- |
153
- | Atoms | `Box`, `Text`, `Button`, `IconButton`, `TextField`, `Switch`, `Checkbox`, `Slider`, `Picker`, `DatePicker`, `ColorPicker`, `SegmentedControl`, `Icon`, `Image`, `Avatar`, `Badge`, `Chip`, `Card`, `Surface`, `Progress`, `ActivityIndicator`, `Skeleton`, `Fab`, `Divider`, `Spacer`, `VStack` / `HStack` / `ZStack`, `ScrollView`, `List`, `Island`, `Pressable`, `GlassView` |
154
- | React Native tier | `RnView`, `RnText`, `RnIcon`, `RnScrollView`, `RnFlatList`, `RnSectionList`, `FlashList` — the same `sx` surface on plain React Native views |
155
- | Molecules | `Label`, `LabeledContent`, `ListItem`, `Link`, `SearchBar`, `EmptyState`, `Collapsible`, `Pager`, `RadioGroup`, `Stepper`, `Tooltip`, `RnTooltip`, `NavigationBar`, `ScrollEdgeContainer` |
156
- | Organisms | `Sheet`, `ActionSheet`, `Alert`, `Menu`, `ContextMenu`, `Form`, `SwipeActions`, `Snackbar`, `FabMenu` |
157
- | Templates | `Screen` |
158
-
159
- A few come from the package's own native module rather than `@expo/ui`: `GlassView` (iOS 26 Liquid
160
- Glass around React Native children), `ScrollEdgeContainer` (the iOS 26 scroll edge effect under your
161
- bars), `NavigationBar` (real `UINavigationBar` items in a sheet), `ContextMenu` (long-press menu
162
- with a custom preview), `RnTooltip` (rich,
163
- controlled tooltip) and `FabMenu` (Material 3 Expressive on Android). Each falls back gracefully where
164
- the platform lacks the feature.
65
+ The header is a real navigation bar: `back`, `close` and icon items on either side, a centred, leading or large title.
165
66
 
166
67
  ## Entry points
167
68
 
168
- | Import | What it is |
169
- | --- | --- |
170
- | `@hzblj/kara-ui` | Components, `sx`, theme, `KaraProvider`, hooks. |
171
- | `@hzblj/kara-ui/router` | `Tabs` (native tabs on Expo Router) and `navigationTheme(theme)` for expo-router's `ThemeProvider`. Needs `expo-router`. |
172
- | `@hzblj/kara-ui/swift-ui` | The raw SwiftUI/UIKit views and modifiers of the native module (iOS only). |
173
- | `@hzblj/kara-ui/jetpack-compose` | The raw Compose views and modifiers of the native module (Android only). |
174
-
175
- ## Packages
176
-
177
- `@hzblj/kara-ui` is all you install. It is built from scoped packages, versioned together, which you
178
- never need to depend on directly:
179
-
180
- | Package | |
181
- | --- | --- |
182
- | `@hzblj/kara-theme` | Tokens, palette, typography, `defineTheme`, `KaraProvider` |
183
- | `@hzblj/kara-sx` | The `sx` styling engine |
184
- | `@hzblj/kara-native` | The `KaraUI` Expo native module (Swift/Kotlin) and its bindings |
185
- | `@hzblj/kara-components` | Atoms, molecules, organisms, templates |
186
- | `@hzblj/kara-router` | `Tabs`, `navigationTheme` |
187
- | `@hzblj/kara-expo-plugin` | The config plugin (icons, iOS semantic colours) and the `kara-icons` CLI |
188
-
189
- ## Development
190
-
191
- All of them live in the [kara-ui monorepo](https://github.com/hzblj/kara-ui) together with an example
192
- app (Showcase, Gallery and on-device Storybook). See the repository README.
193
-
194
- ## License
69
+ `@hzblj/kara-ui` (everything), `@hzblj/kara-ui/router` (native tabs), `@hzblj/kara-ui/swift-ui` and
70
+ `@hzblj/kara-ui/jetpack-compose` (the raw native views).
195
71
 
196
- MIT
72
+ [Example app and source](https://github.com/hzblj/kara-ui) · MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hzblj/kara-ui",
3
- "version": "0.2.1",
3
+ "version": "0.3.0",
4
4
  "description": "A native-first design system for Expo: real SwiftUI and Jetpack Compose views through @expo/ui, styled by one token-typed sx engine.",
5
5
  "author": "Jan Blazej",
6
6
  "license": "MIT",
@@ -87,15 +87,16 @@
87
87
  ]
88
88
  },
89
89
  "dependencies": {
90
- "@hzblj/kara-components": "^0.2.1",
91
- "@hzblj/kara-expo-plugin": "^0.2.1",
92
- "@hzblj/kara-native": "^0.2.1",
93
- "@hzblj/kara-router": "^0.2.1",
94
- "@hzblj/kara-sx": "^0.2.1",
95
- "@hzblj/kara-theme": "^0.2.1"
90
+ "@hzblj/kara-components": "^0.3.0",
91
+ "@hzblj/kara-expo-plugin": "^0.3.0",
92
+ "@hzblj/kara-native": "^0.3.0",
93
+ "@hzblj/kara-router": "^0.3.0",
94
+ "@hzblj/kara-sx": "^0.3.0",
95
+ "@hzblj/kara-theme": "^0.3.0"
96
96
  },
97
97
  "peerDependencies": {
98
98
  "@expo/ui": "~57.0.0",
99
+ "@lodev09/react-native-true-sheet": ">=3.11.0",
99
100
  "@shopify/flash-list": ">=2.0.0",
100
101
  "expo": "~57.0.0",
101
102
  "expo-haptics": "*",
@@ -112,6 +113,7 @@
112
113
  },
113
114
  "devDependencies": {
114
115
  "@expo/ui": "~57.0.18",
116
+ "@lodev09/react-native-true-sheet": "3.11.18",
115
117
  "@shopify/flash-list": "^2.3.2",
116
118
  "@types/react": "~19.2.18",
117
119
  "expo": "~57.0.22",