panelui-native 0.22.3 → 0.22.6

package/README.md

@@ -1,7 +1,7 @@
 # PanelUI — React Native UI components for Expo, styled with Tailwind CSS
 
 **PanelUI** (`panelui-native`) is an accessible, high-performance React Native component
-library for Expo apps. 29 typed components — buttons, bottom sheets, dialogs, selects,
+library for Expo apps. 53 typed components — buttons, bottom sheets, dialogs, selects,
 toasts, forms — styled with Tailwind CSS v4 and animated on the UI thread with Reanimated.
 Zero native code, so it runs in Expo Go.
 
@@ -24,15 +24,35 @@ Zero native code, so it runs in Expo Go.
   state and labels.
 - 📦 **TypeScript, tree-shakeable, zero native modules** — works in Expo Go, no prebuild needed.
 
-## Install
+## Quick start
+
+Needs an Expo SDK 57+ app and Node 20+. No Xcode, no Android Studio, no `prebuild` — PanelUI has
+no native modules, so it runs in Expo Go. No app yet? `npx create-expo-app@latest my-app`.
+
+Five steps. The full walkthrough, with a fix for every error people hit, is at
+**[panelui.dev/docs/installation](https://panelui.dev/docs/installation)**.
+
+### 1. Install the packages
 
 ```sh
-npx expo install panelui-native uniwind tailwindcss react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-svg react-native-worklets
+npx expo install panelui-native uniwind tailwindcss @react-native-masked-view/masked-view expo-linear-gradient react-native-gesture-handler react-native-reanimated react-native-safe-area-context react-native-svg react-native-worklets
 ```
 
-## Quick start
+Install all of them, including the ones you think you don't need. Metro resolves every import in
+the library when it builds your bundle, so leaving one out fails the **first** bundle with
+`Unable to resolve module …` — for a component you may never use. `npx expo install` (rather than
+`npm install`) picks the versions that match your SDK.
+
+Optional, each behind a guarded import: `expo-haptics` (the `haptics` prop), `expo-blur` (blurred
+overlay backdrops), `expo-clipboard` (`useCopyToClipboard`), `react-native-keyboard-controller`
+(keyboard avoidance on Android), `expo-file-system` + `react-native-view-shot` (Signature export),
+`@expo/ui` (native platform controls).
 
-**1. Configure Metro**
+### 2. Add `metro.config.js`
+
+**In the root of your project, next to `package.json`** — not in `app/`, not in `src/`. A Metro
+config anywhere else is silently ignored and none of your classes will do anything. A fresh Expo
+app has no such file; `npx expo customize metro.config.js` writes one.
 
 ```js
 // metro.config.js
@@ -42,49 +62,104 @@ const { withUniwindConfig } = require('uniwind/metro');
 const config = getDefaultConfig(__dirname);
 
 module.exports = withUniwindConfig(config, {
-  cssEntryFile: './global.css',
+  cssEntryFile: './src/global.css',
   dtsFile: './uniwind-types.d.ts',
-  // Only needed if you use the Moon or Grass themes.
+  // Only needed to switch to the Moon or Grass themes at runtime.
   extraThemes: ['moon', 'moon-dark', 'grass', 'grass-dark'],
 });
 ```
 
-**2. Create `global.css`**
+`cssEntryFile` and `dtsFile` are relative to this file. `./src/global.css` is where
+`create-expo-app` puts the CSS — if yours is at the project root, change it to `'./global.css'`.
+
+**Nothing validates that path.** Point it at a file that does not exist and Metro still bundles, the
+app still launches, and not one class resolves — no `flex-1`, so views collapse and you get a blank
+screen with `Uniwind - We couldn't find your variable --color-background`.
+
+### 3. Add the imports to `global.css`
+
+**Look for this file before you create one** — an app made by `create-expo-app` already has
+`src/global.css`. Add these lines at the top of it and leave the rest below. A second CSS file at
+the project root gives you two entries, only one of which is compiled, and nothing gets styled.
 
 ```css
+/* src/global.css */
 @import 'tailwindcss';
 @import 'uniwind';
 @import 'panelui-native/theme.css';
 
-@source './node_modules/panelui-native/src';
+@source '../node_modules/panelui-native/src';
 ```
 
-**3. Wrap your app**
+`@source` is relative to **the CSS file**, and has to land on `node_modules/panelui-native/src` —
+hence the `../` above, from `src/`. From the project root it is `'./node_modules/…'`, from
+`src/styles/` it is `'../../node_modules/…'`. Get it wrong and your own classes work while
+PanelUI's components come out unstyled. Whichever file you used is what `cssEntryFile` must name.
+
+### 4. Import the CSS and add the provider
+
+At the top of your app's entry file. The default template uses Expo Router with routes under
+`src/`, so there is usually no `App.tsx` — the entry is `src/app/_layout.tsx`, and it already
+returns a navigation `ThemeProvider` to wrap rather than replace:
 
 ```tsx
-// App.tsx
-import './global.css';
-import { PanelUIProvider, Button, Card } from 'panelui-native';
+// src/app/_layout.tsx
+import '../global.css';
+
+import { DarkTheme, DefaultTheme, ThemeProvider } from 'expo-router';
+import { useColorScheme } from 'react-native';
+import { PanelUIProvider } from 'panelui-native';
+
+import AppTabs from '@/components/app-tabs';
+
+export default function RootLayout() {
+  const colorScheme = useColorScheme();
 
-export default function App() {
   return (
     <PanelUIProvider>
-      <Card>
-        <Card.Header>
-          <Card.Title>Create project</Card.Title>
-          <Card.Description>Deploy your new project in one click.</Card.Description>
-        </Card.Header>
-        <Card.Footer>
-          <Button>Deploy</Button>
-        </Card.Footer>
-      </Card>
+      <ThemeProvider value={colorScheme === 'dark' ? DarkTheme : DefaultTheme}>
+        <AppTabs />
+      </ThemeProvider>
     </PanelUIProvider>
   );
 }
 ```
 
+That navigation theme paints over PanelUI's background once you switch themes — see
+[Using Expo Router?](#using-expo-router-read-this) below for the version fed from live tokens.
+
 `PanelUIProvider` sets up the gesture root, the themed page background, the portal host used by
-overlays, and the toast viewport.
+overlays, and the toast viewport. One at the root is enough — don't nest a second.
+
+You do **not** need a `babel.config.js`; Expo's default preset already wires the worklets plugin
+Reanimated needs.
+
+### 5. Restart
+
+```sh
+npx expo start --clear
+```
+
+Metro reads `metro.config.js`, `global.css` and `extraThemes` once, at startup. After changing any
+of them, stop the dev server and start it again — `--clear` on a running one is not enough.
+
+```tsx
+import { Button, Card } from 'panelui-native';
+
+<Card>
+  <Card.Header>
+    <Card.Title>It works</Card.Title>
+    <Card.Description>PanelUI is installed and themed.</Card.Description>
+  </Card.Header>
+  <Card.Footer>
+    <Button>Deploy</Button>
+  </Card.Footer>
+</Card>;
+```
+
+A themed background, a card with a border and radius, and a button that dips when pressed means
+you are done. Unstyled text on a white screen means the styles are not reaching the bundle — see
+[Troubleshooting](https://panelui.dev/docs/installation#troubleshooting).
 
 ## Components
 
@@ -246,6 +321,25 @@ the named themes, which the OS `Appearance` API knows nothing about. For the sam
 
 ## FAQ
 
+### The first bundle fails with `Unable to resolve module …`
+
+A required package is missing. Run the [install command](#1-install-the-packages) again — all of
+it, not just the package named in the error. Metro resolves every import in the library, so this
+happens even for components you never use.
+
+### `Cannot use @variant with unknown variant: moon` when building
+
+Fixed in 0.22.5 — upgrade with `npx expo install panelui-native`. Before that release the Moon and
+Grass token blocks leaned on variants that only existed in the artifact Uniwind generates from your
+Metro config, so the dev server worked while `npx expo export` and EAS builds failed.
+
+### None of my classes do anything
+
+In order of likelihood: `metro.config.js` is not in the project root; it does not wrap the config
+in `withUniwindConfig`; `cssEntryFile` does not point at your CSS file; `import './global.css'` is
+missing from the entry file; or the dev server was running when you changed one of those. Full
+list at [Troubleshooting](https://panelui.dev/docs/installation#troubleshooting).
+
 ### How is PanelUI different from NativeWind?
 
 NativeWind is a styling engine; PanelUI is a component library. PanelUI is built on **Uniwind**,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "panelui-native",
-  "version": "0.22.3",
+  "version": "0.22.6",
   "description": "High-performance React Native UI components for Expo. Semantic design tokens, powered by Uniwind (Tailwind v4) and Reanimated.",
   "main": "./lib/module/index.js",
   "module": "./lib/module/index.js",

package/theme.css

@@ -16,6 +16,28 @@
  *   @source './node_modules/panelui-native/src';
  */
 
+/*
+ * The named themes declare their own variants, so this file compiles on its
+ * own terms.
+ *
+ * `light` and `dark` exist wherever Uniwind does. The other four are extra
+ * themes, and their variants are otherwise only defined in the artifact
+ * Uniwind generates from the theme list in a project's Metro config — which
+ * that generation step has to compile *this file* to produce. A fresh install
+ * therefore had nothing defining `moon` at the moment it was first used: the
+ * dev server got away with it because it registers the themes in memory, while
+ * a production bundle failed with `Cannot use @variant with unknown variant`.
+ *
+ * Declared here, the cycle does not exist and neither does the difference
+ * between the two. Registering a theme in `extraThemes` is then only about
+ * being able to switch to it at runtime, which is what that option reads like
+ * it is for.
+ */
+@custom-variant moon (&:where(.moon, .moon *));
+@custom-variant moon-dark (&:where(.moon-dark, .moon-dark *));
+@custom-variant grass (&:where(.grass, .grass *));
+@custom-variant grass-dark (&:where(.grass-dark, .grass-dark *));
+
 @theme {
   --color-background: unset;
   --color-foreground: unset;