expo-interface 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kat-tax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# expo-interface
+
+Native-first, universal UI kit for [Expo](https://expo.dev), built on
+[`@expo/ui`](https://docs.expo.dev/versions/v56.0.0/sdk/ui/).
+
+Every component renders the platform's real control:
+
+| Platform | Renders with |
+| -------- | ------------ |
+| iOS      | SwiftUI (`@expo/ui/swift-ui`) |
+| Android  | Jetpack Compose / Material 3 (`@expo/ui/jetpack-compose`) |
+| Web      | Plain DOM elements styled with CSS custom properties |
+
+One accent seed themes all three: it seeds a Material 3 palette on Android,
+cascades as a SwiftUI `tint` on iOS, and is emitted as `--color-*` variables on
+web. The prop surface of each component is the intersection of what the three
+platforms support, so the same JSX renders a native-feeling control everywhere.
+
+> **Status:** early. The API follows `@expo/ui`, which is itself still
+> evolving, so expect breaking changes between minor versions.
+
+## Install
+
+```sh
+npx expo install expo-interface @expo/ui expo-router expo-symbols expo-image expo-constants expo-status-bar expo-system-ui expo-web-browser react-native-safe-area-context
+```
+
+`expo-interface` ships TypeScript source (`src/index.ts`) and relies on Metro to
+compile it, exactly like the rest of your app — no build step, and the
+`.ios.tsx` / `.android.tsx` / `.web.tsx` platform files resolve as usual.
+
+### Android drawables (optional)
+
+Jetpack Compose controls render icons from drawables rather than symbol glyphs.
+To use Material Symbols as drawables, install `@expo/material-symbols` and
+register `xml` as an asset extension in `metro.config.js`:
+
+```js
+const {getDefaultConfig} = require('expo/metro-config');
+
+const config = getDefaultConfig(__dirname);
+
+if (!config.resolver.assetExts.includes('xml')) {
+  config.resolver.assetExts.push('xml');
+}
+
+module.exports = config;
+```
+
+## Setup
+
+### 1. Provide the accent
+
+Wrap the app in `AccentProvider`. Omit `seed` for the default (iOS systemBlue,
+`#007AFF`) or pass a hex color to re-theme every platform at once.
+
+```tsx
+// app/_layout.tsx
+import {ThemeProvider, Stack} from 'expo-router';
+import {AccentProvider, useNavTheme} from 'expo-interface';
+
+function Navigation() {
+  // Reads the accent seed, so it must render inside AccentProvider.
+  return (
+    <ThemeProvider value={useNavTheme()}>
+      <Stack screenOptions={{headerShown: false}}/>
+    </ThemeProvider>
+  );
+}
+
+export default function Layout() {
+  return (
+    <AccentProvider seed="#8959EA">
+      <Navigation/>
+    </AccentProvider>
+  );
+}
+```
+
+### 2. Emit the palette on web
+
+`getThemeCSS()` renders the light/dark palette as `--color-*` custom
+properties. Add it to the root HTML so CSS consumers (buttons, typography,
+`theme.*` tokens) resolve without JavaScript.
+
+```tsx
+// app/+html.tsx
+import {ScrollViewStyleReset} from 'expo-router/html';
+import {getThemeCSS} from 'expo-interface';
+
+export default function Root({children}: React.PropsWithChildren) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8"/>
+        <meta name="viewport" content="width=device-width, initial-scale=1"/>
+        <style dangerouslySetInnerHTML={{__html: getThemeCSS()}}/>
+        <ScrollViewStyleReset/>
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+### 3. Build screens
+
+`Screen` handles safe areas, the status bar, the system background color, and
+the content max-width. With `native`, children are mounted inside an
+accent-seeded `@expo/ui` `Host`, so you can compose SwiftUI / Compose
+primitives directly.
+
+```tsx
+import {Screen, Button, Title, Body} from 'expo-interface';
+
+export default function Home() {
+  return (
+    <Screen gutter>
+      <Title>Hello</Title>
+      <Body color="secondaryLabel">Rendered with the platform's own text.</Body>
+      <Button label="Continue" onPress={() => {}}/>
+    </Screen>
+  );
+}
+```
+
+## Components
+
+All exports come from the package root: `import {…} from 'expo-interface'`.
+
+### Layout
+
+| Export | Description |
+| ------ | ----------- |
+| `Screen` | Safe-area screen container. Props: `native` (mount an accent-seeded `Host`), `header` (sits under a stack header), `gutter` (horizontal padding). |
+| `ScreenHeader` | Simple header bar with optional back button and trailing slot. |
+| `ConstrainedStackHeader` | `Stack` `header` implementation for web that matches the content max-width (renders nothing on native). |
+| `TabStack` | Pre-configured `expo-router` `Stack` for a tab's root screen, themed from `useNavTheme()`. |
+| `Tabs` | Tab bar: `NativeTabs` on iOS/Android, a floating top bar on web. Props: `routes`, `webLogo` (`'icon-only'`, `'text-only'`, `'icon-and-text'` or a `ReactNode`), `webIcon`. |
+| `Sheet` | Accent-aware `@expo/ui` `BottomSheet`. |
+| `hostAccentProps(seed)` | Extra `Host` props that apply the accent (`seedColor` on Android, `tint` modifier on iOS) — use when mounting your own `Host`. |
+| `fillWidth` | Modifiers that make a universal `Column`/`Row` span its parent's width. |
+
+### Controls
+
+| Export | Description |
+| ------ | ----------- |
+| `Button` | `label`, `onPress`, `variant` (`filled` / `outlined` / `text`), `role` (`default` / `destructive`), `size`, `shape` (`rounded` / `pill` / `circle`), `color`, `prefixIcon`, `suffixIcon`, `hideLabel`, `disabled`. |
+| `TextField` | `value`, `onChangeText`, `onSubmit`, `placeholder`, `keyboardType`, `autoCapitalize`, `secureTextEntry`, `multiline`, `maxLength`, `accentColor`, … |
+| `Switch` | `value`, `onValueChange`, `label`, `disabled`, `accentColor`. |
+| `Picker` | `selectedValue`, `onValueChange`, `label`, with `{label, value}` option children. |
+| `DateTimePicker` | `value`, `onChange`, `mode` (`date` / `time` / `datetime`), `minimumDate`, `maximumDate`, `label`. |
+| `Progress` | Linear progress: `value` (0–1, indeterminate when omitted), `color`, `trackColor`. |
+| `ListItem` | Row with `leading`, `trailing`, `supporting` text and `onPress`. |
+| `FieldGroup` | Re-export of `@expo/ui`'s grouped form container (styled on web). |
+| `QRCode` | Renders `value` as a QR image (`size`). |
+| `ExternalLink` | `expo-router` `Link` that opens in an in-app browser on native. |
+
+### Typography
+
+`Typography` plus one component per variant: `LargeTitle`, `Title`, `Title2`,
+`Title3`, `Headline`, `Body`, `Callout`, `Subheadline`, `Footnote`, `Caption`,
+`Label`. Props: `color` (a theme token), `weight`, `align`, `numberOfLines`,
+`style`. Metrics follow the iOS text styles on iOS/web and the Material type
+scale on Android.
+
+### Icons
+
+Components take an `IconToken` — an `expo-symbols` name (single string or
+`{ios, android, web}` map) plus an optional Android drawable:
+
+```ts
+// icons.drawables.android.ts
+import share from '@expo/material-symbols/share.xml';
+export const drawables = {share};
+
+// icons.drawables.ts (iOS/web stub)
+export const drawables: Record<string, ImageSourcePropType | undefined> = {};
+
+// icons.ts
+import {icon} from 'expo-interface';
+import {drawables} from './icons.drawables';
+
+export const share = icon(
+  {ios: 'square.and.arrow.up', android: 'share', web: 'share'},
+  drawables.share,
+);
+```
+
+### Theme
+
+| Export | Description |
+| ------ | ----------- |
+| `theme` | Scheme-adaptive color tokens as opaque platform values (`PlatformColor` on iOS, theme attrs on Android, `var(--color-*)` on web) for styles the platform resolves natively. |
+| `useColor(token)` | Hook returning a concrete color string for the active scheme and accent — use for anything that can't consume a `PlatformColor` (symbols, `@expo/ui` props). |
+| `colors` | The raw light/dark palette. |
+| `spacing`, `bound`, `inset`, `fonts`, `fontWeights`, `variants` | Layout and type constants. |
+| `useNavTheme()` | React Navigation theme resolved from the palette and live accent. |
+| `getThemeCSS()` | Palette as `--color-*` CSS for `+html.tsx`. |
+| `AccentProvider`, `useAccentSeed`, `onAccent`, `ACCENT_SEED` | Accent seed context and helpers. |
+
+Tokens: `label`, `secondaryLabel`, `tertiaryLabel`, `background`,
+`backgroundElement`, `backgroundSelected`, `separator`, `tint`, `onTint`,
+`pillBackground`, `switchTrack`, `switchOn`, `destructive`, `onDestructive`.
+
+### Utilities
+
+`shareUrl(url, message?)` opens the native share sheet / Web Share API;
+`copyText(text)` copies on web and falls back to the share sheet on native.
+
+## Example app
+
+[`example/`](./example) is **dropfiles**, a small file-drop app that exercises
+every component in the kit. It resolves the package straight from `../src`
+through the npm workspace, so it doubles as the development harness:
+
+```sh
+npm install
+npm run web       # expo start --web
+npm run ios       # expo run:ios
+npm run android   # expo run:android
+npm run typecheck # package + example
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "expo-interface",
+  "version": "0.1.0",
+  "description": "Native-first universal UI kit for Expo — SwiftUI on iOS, Jetpack Compose on Android, real DOM on web — built on @expo/ui.",
+  "license": "MIT",
+  "author": "kat-tax",
+  "homepage": "https://github.com/kat-tax/expo-interface#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kat-tax/expo-interface.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kat-tax/expo-interface/issues"
+  },
+  "keywords": [
+    "expo",
+    "expo-ui",
+    "react-native",
+    "swiftui",
+    "jetpack-compose",
+    "ui-kit",
+    "design-system",
+    "universal"
+  ],
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "sideEffects": [
+    "**/*.css",
+    "src/theme.ts",
+    "src/screen/index.tsx"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "workspaces": [
+    "example"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit && bun run --cwd example typecheck",
+    "lint": "bun run --cwd example lint",
+    "start": "bun run --cwd example start",
+    "web": "bun run --cwd example web",
+    "ios": "bun run --cwd example ios",
+    "android": "bun run --cwd example android"
+  },
+  "dependencies": {
+    "qrcode-generator": "^2.0.4"
+  },
+  "peerDependencies": {
+    "@expo/material-symbols": "*",
+    "@expo/ui": "^56.0.0",
+    "expo": "^56.0.0",
+    "expo-constants": "*",
+    "expo-image": "*",
+    "expo-router": "^56.0.0",
+    "expo-status-bar": "*",
+    "expo-symbols": "*",
+    "expo-system-ui": "*",
+    "expo-web-browser": "*",
+    "react": "*",
+    "react-native": "*",
+    "react-native-safe-area-context": "*"
+  },
+  "peerDependenciesMeta": {
+    "@expo/material-symbols": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.2",
+    "typescript": "~6.0.3"
+  },
+  "packageManager": "bun@1.3.9"
+}

package/src/accent.tsx

@@ -0,0 +1,62 @@
+import type {PropsWithChildren} from 'react';
+import {createContext, useContext, useEffect} from 'react';
+import {Platform} from 'react-native';
+
+/**
+ * Default accent seed (iOS systemBlue). A single color that seeds the tint on
+ * every platform:
+ * - Android: generates a full Material 3 palette via `SchemeTonalSpot` (the
+ *   Material You algorithm), light and dark, through the Compose `Host`
+ *   `seedColor` prop and `useMaterialColors({seedColor})`.
+ * - iOS: applied verbatim as the SwiftUI `tint` (cascades from the `Host`),
+ *   like a single-color AccentColor asset.
+ * - Web: emitted as the `--color-tint` default by `getThemeCSS`; runtime
+ *   overrides are applied as inline custom properties (see AccentProvider).
+ */
+export const ACCENT_SEED = '#007AFF';
+
+const AccentContext = createContext(ACCENT_SEED);
+
+/** The active accent seed color (hardcoded default or user-supplied). */
+export function useAccentSeed(): string {
+  return useContext(AccentContext);
+}
+
+/**
+ * Contrast color (black or white) for content rendered on top of the accent.
+ * Used for iOS/web `onTint`; Android uses the seeded palette's `onPrimary`.
+ */
+export function onAccent(seed: string): '#000000' | '#FFFFFF' {
+  let hex = seed.replace('#', '');
+  if (hex.length === 3) hex = hex.split('').map(c => c + c).join('');
+  const n = parseInt(hex.slice(0, 6), 16);
+  if (Number.isNaN(n)) return '#FFFFFF';
+  const r = (n >> 16) & 255;
+  const g = (n >> 8) & 255;
+  const b = n & 255;
+  const luma = 0.299 * r + 0.587 * g + 0.114 * b;
+  return luma > 153 ? '#000000' : '#FFFFFF';
+}
+
+/**
+ * Provides the accent seed to the app. Pass `seed` to apply a user-supplied
+ * accent; omit it for the hardcoded default. On web the seed is mirrored to
+ * the `--color-tint`/`--color-on-tint` custom properties (inline styles win
+ * over the `:root` defaults emitted by `getThemeCSS`), so all CSS consumers
+ * react without JS recomputation.
+ */
+export function AccentProvider({seed = ACCENT_SEED, children}: PropsWithChildren<{seed?: string}>) {
+  useEffect(() => {
+    if (Platform.OS !== 'web' || typeof document === 'undefined') return;
+    const root = document.documentElement;
+    if (seed === ACCENT_SEED) {
+      root.style.removeProperty('--color-tint');
+      root.style.removeProperty('--color-on-tint');
+      return;
+    }
+    root.style.setProperty('--color-tint', seed);
+    root.style.setProperty('--color-on-tint', onAccent(seed));
+  }, [seed]);
+
+  return <AccentContext.Provider value={seed}>{children}</AccentContext.Provider>;
+}

package/src/button/button.css

@@ -0,0 +1,118 @@
+.ui-button {
+  --ui-button-accent: var(--color-tint);
+  --ui-button-on-accent: var(--color-on-tint);
+  -webkit-appearance: none;
+  appearance: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 999px;
+  border: 1px solid transparent;
+  padding: 10px 18px;
+  gap: 8px;
+  cursor: pointer;
+  font-family: var(--font-display);
+  font-size: 15px;
+  font-weight: 600;
+  line-height: 1.2;
+  user-select: none;
+  white-space: nowrap;
+  transition: background-color 0.15s ease, filter 0.15s ease, opacity 0.15s ease;
+}
+
+.ui-button--small {
+  font-size: 13px;
+  padding: 6px 12px;
+}
+
+.ui-button--large {
+  font-size: 17px;
+  padding: 14px 22px;
+}
+
+.ui-button--rounded {
+  border-radius: 12px;
+}
+
+.ui-button--pill {
+  border-radius: 999px;
+}
+
+.ui-button--circle {
+  border-radius: 50%;
+  aspect-ratio: 1;
+  padding: 10px;
+}
+
+.ui-button--circle.ui-button--small {
+  padding: 6px;
+}
+
+.ui-button--circle.ui-button--large {
+  padding: 14px;
+}
+
+.ui-button--icon-only.ui-button--small {
+  padding: 6px;
+}
+
+.ui-button--icon-only.ui-button--medium {
+  padding: 10px;
+}
+
+.ui-button--icon-only.ui-button--large {
+  padding: 14px;
+}
+
+.ui-button--filled {
+  color: var(--ui-button-on-accent);
+  background: var(--ui-button-accent);
+}
+
+.ui-button--outlined {
+  color: var(--ui-button-accent);
+  background: transparent;
+  border-color: var(--ui-button-accent);
+}
+
+.ui-button--text {
+  color: var(--ui-button-accent);
+  background: transparent;
+  border-color: transparent;
+  padding-inline: 10px;
+}
+
+.ui-button--text.ui-button--small {
+  padding-inline: 6px;
+}
+
+.ui-button--text.ui-button--large {
+  padding-inline: 14px;
+}
+
+.ui-button--destructive {
+  --ui-button-accent: var(--color-destructive);
+  --ui-button-on-accent: var(--color-on-destructive);
+}
+
+.ui-button__label {
+  display: inline-block;
+}
+
+.ui-button:hover:not(:disabled) {
+  filter: brightness(1.08);
+}
+
+.ui-button--outlined:hover:not(:disabled),
+.ui-button--text:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--ui-button-accent) 12%, transparent);
+}
+
+.ui-button:active:not(:disabled) {
+  filter: brightness(0.92);
+}
+
+.ui-button:disabled {
+  opacity: 0.45;
+  cursor: default;
+}

package/src/button/index.android.tsx

@@ -0,0 +1,114 @@
+import type {ButtonProps, ButtonShape, ButtonVariant} from './types';
+import {testID as testIDModifier, width} from '@expo/ui/jetpack-compose/modifiers';
+import {Button as ComposeButton, OutlinedButton, TextButton, Icon, IconButton, FilledIconButton, OutlinedIconButton, Spacer, Shape, Text} from '@expo/ui/jetpack-compose';
+import {SIZE_ICON, SIZE_TEXT, androidContentPadding} from './shared';
+import {onAccent as contrastOf} from '../accent';
+import {useColor} from '../theme';
+
+const VARIANT_COMPONENT: Record<ButtonVariant, typeof ComposeButton | typeof OutlinedButton | typeof TextButton> = {
+  filled: ComposeButton,
+  outlined: OutlinedButton,
+  text: TextButton,
+};
+
+const ICON_ONLY_COMPONENT: Record<ButtonVariant, typeof FilledIconButton | typeof OutlinedIconButton | typeof IconButton> = {
+  filled: FilledIconButton,
+  outlined: OutlinedIconButton,
+  text: IconButton,
+};
+
+function resolveShape(shape?: ButtonShape) {
+  if (!shape) return undefined;
+  switch (shape) {
+    case 'rounded':
+      return Shape.RoundedCorner({cornerRadii: {topStart: 12, topEnd: 12, bottomStart: 12, bottomEnd: 12}});
+    case 'pill':
+      return Shape.Pill({});
+    case 'circle':
+      return Shape.Circle({});
+  }
+}
+
+/**
+ * Android renders the matching Material 3 button component for each variant.
+ * The accent defaults to the theme tint (red for the destructive role) and is
+ * applied as the container color (filled) or content color (outlined/text), so
+ * the button is branded instead of falling back to the device's Material theme.
+ */
+export function Button({
+  label,
+  onPress,
+  variant = 'filled',
+  role = 'default',
+  color,
+  size = 'medium',
+  shape,
+  prefixIcon,
+  suffixIcon,
+  hideLabel = false,
+  disabled,
+  testID,
+}: ButtonProps) {
+  const themeTint = useColor('tint');
+  const destructive = useColor('destructive');
+  const themeOnAccent = useColor(role === 'destructive' ? 'onDestructive' : 'onTint');
+  const accent = color ?? (role === 'destructive' ? destructive : themeTint);
+  // A custom accent brings its own contrast color for filled content.
+  const onAccent = color ? contrastOf(color) : themeOnAccent;
+  const onFilled = variant === 'filled';
+  const textColor = onFilled ? onAccent : accent;
+  const colors = onFilled
+    ? {containerColor: accent, contentColor: onAccent}
+    : {contentColor: accent};
+  const iconSize = SIZE_ICON[size];
+  const textSize = SIZE_TEXT[size];
+  const resolvedShape = resolveShape(shape);
+  const modifiers = testID ? [testIDModifier(testID)] : [];
+  const iconOnly = hideLabel && !!prefixIcon?.drawable;
+
+  if (iconOnly) {
+    const IconComponent = ICON_ONLY_COMPONENT[variant];
+    return (
+      <IconComponent
+        onClick={disabled ? undefined : onPress}
+        enabled={!disabled}
+        colors={colors}
+        shape={resolvedShape}
+        modifiers={modifiers}>
+        <Icon
+          source={prefixIcon!.drawable!}
+          size={iconSize}
+          tint={textColor}
+          contentDescription={label}
+        />
+      </IconComponent>
+    );
+  }
+
+  const Component = VARIANT_COMPONENT[variant];
+  const pad = androidContentPadding(size, !!(prefixIcon?.drawable || suffixIcon?.drawable));
+
+  return (
+    <Component
+      onClick={disabled ? undefined : onPress}
+      enabled={!disabled}
+      colors={colors}
+      shape={resolvedShape}
+      contentPadding={pad}
+      modifiers={modifiers}>
+      {prefixIcon?.drawable ? (
+        <>
+          <Icon source={prefixIcon.drawable} size={iconSize} tint={textColor}/>
+          <Spacer modifiers={[width(8)]}/>
+        </>
+      ) : null}
+      <Text color={textColor} style={{fontSize: textSize}}>{label}</Text>
+      {suffixIcon?.drawable ? (
+        <>
+          <Spacer modifiers={[width(8)]}/>
+          <Icon source={suffixIcon.drawable} size={iconSize} tint={textColor}/>
+        </>
+      ) : null}
+    </Component>
+  );
+}