@apple-pie/slice-native 0.1.4 → 0.1.7

package/README.md

@@ -1,120 +1,187 @@
 # @apple-pie/slice-native
 
-Experimental React Native SVG icons, with the same names and artwork as the web UIKit.
-Includes native light/dark theme tokens; other Slice components and a theme provider
-are not included. It is built and published independently
-of `@apple-pie/slice` and does not require that package at runtime.
+**Alpha software — APIs, styling, and platform behavior may change between releases.**
+
+A React Native UI kit with themed components, SVG icons, native blur, and Liquid Glass.
+It shares Slice’s visual language with the web UIKit, but is packaged independently
+and does not require `@apple-pie/slice` at runtime.
+
+**Blur, gradient masking, Liquid Glass, and device capability detection are built
+into this package and connected directly to native platform code.** No additional
+blur, gradient, masking, or glass libraries are required—including `expo-blur`,
+`expo-linear-gradient`, and `@react-native-masked-view/masked-view`.
+
+## Installation
+
+```sh
+npm install @apple-pie/slice-native
+```
+
+Configure the package’s peer dependencies in your app: React 18/19, React Native
+0.80+, `react-native-svg` 15, and Reanimated 4 with its compatible Worklets setup.
+For Expo projects, use `npx expo install` for native peers to select compatible versions.
+These general UI dependencies are separate from the built-in native visual effects.
+
+Native components require the New Architecture. iOS builds require Xcode 26+.
+Install iOS pods and rebuild your app after installing or updating the package.
+Expo apps need a development build; the custom native components are not available
+in Expo Go. Restarting Metro alone does not register new native code.
+
+## Quick start
 
 ```tsx
-import { Icon, SliceIcons } from '@apple-pie/slice-native';
-
-<Icon
-  name={SliceIcons.ui.home}
-  size={24}
-  strokeColor="#334155"
-  accessibilityLabel="Go home"
-  onPress={() => navigation.navigate('Home')}
-/>
+import { View } from 'react-native';
+import {
+  SliceButton,
+  SliceIcons,
+  SliceTextInput,
+  SliceThemeProvider,
+} from '@apple-pie/slice-native';
+
+export default function App() {
+  return (
+    <SliceThemeProvider>
+      <View style={{ padding: 24, gap: 16 }}>
+        <SliceTextInput accessibilityLabel="Search tasks" placeholder="Search…" />
+        <SliceButton icon={SliceIcons.ui.home} onPress={() => console.log('Home')}>
+          Go home
+        </SliceButton>
+      </View>
+    </SliceThemeProvider>
+  );
+}
 ```
 
-`NativeIcon` is also exported as an alias of `Icon`. Supply native SVG props and
-native `style` objects; use `onPress` instead of `onClick`. CSS classes, cursor
-styling (`pointer`), and browser keyboard handlers are not part of this API.
-Use an enclosing React Native `Pressable` when you need a larger touch target or
-button feedback, and mark the icon `accessible={false}` when it is decorative.
+## Components
 
-Defaults are 20×20, stroke width 1.5, and black/white colors based on the system
-color scheme. Pass `strokeColor` and `coverUp` explicitly to match an app theme.
-`fillColor` retains the web API's meaning: **opacity from 0 to 1**, not a color.
-`fill` enables that opacity (default 0.125 in light mode, 0.2 in dark mode).
-`toggle` selects the on variant when available; unknown names render nothing.
-`disabled` blocks press callbacks and halves the specified opacity.
+| Component | Summary |
+| --- | --- |
+| `SliceButton` | Primary/secondary buttons, optional icons, disabled states, Reanimated transitions, and optional Liquid Glass backgrounds. |
+| `SliceTextInput` | Themed native input with icons, optional focus control, focus callbacks, and opt-in clearing on blur. |
+| `StyledText` | Theme-based typography presets with native text props. |
+| `SliceIcon` / `SliceIcons` | Native SVG artwork and typed icon names shared with the web UIKit. Supports toggles, fills, sizing, and press handlers. |
+| `SliceLiquidGlassView` | Native glass container with children, tint, interaction feedback, and rounded corners. |
+| `SliceBackgroundBlur` | Background blur overlay with an optional directional fade on iOS. |
 
-The package requires React, React Native, and react-native-svg as peers. Install
-the native SVG dependency in the consuming app using its normal native/Expo setup.
+Buttons and inputs support `size` (`s`, `m`, `l`, or a number), `borderRadius`
+(`pill`, `rectangular`, or a number), `borderWidth`, `borderColor`, and
+`backgroundColor`. Sizes define minimum heights, allowing room for larger text.
+Inputs forward `style` to the underlying text field. Buttons expose `animatedStyle`
+for their wrapper.
 
-## Development
+`SliceButton`, `SliceTextInput`, and `StyledText` use `SliceThemeProvider`. Give
+inputs and icon-only buttons an accessible name. Icons inside these components
+are decorative; standalone icons can use `accessibilityLabel` and `onPress`.
+For `SliceIcon`, `fillColor` means fill opacity, not a color value.
 
-The package manifest and entry point live in `native/`. Icon components, types,
-generated artwork, and tests live in `native/components/Icon/`.
+### Built-in Liquid Glass and blur
 
-From this directory, run `npm run generate` after changing the web icon registry
-or `SliceIcons` constants. Generated files contain native SVG components and have
-no runtime imports from the web UIKit. Run `npm run typecheck` with the peer
-dependencies installed and TypeScript available from the repository.
+| Effect | iOS | Android | Web |
+| --- | --- | --- | --- |
+| `SliceLiquidGlassView` | Native Liquid Glass on iOS 26+; system blur on older iOS. | Tinted color fallback. | Tinted color fallback. |
+| `SliceBackgroundBlur` | Native backdrop blur; optional directional fade. | Uniform backdrop blur when the required API is present (SDK 37.2+) and hardware acceleration is available; otherwise a color fallback. | Color fallback. |
 
-From the repository root:
+The implementations ship with the package: Swift/UIKit and Fabric on iOS, and Java
+platform code on Android. Consumers do not need to install another effects library.
+iOS respects Reduce Transparency and renders a fallback when it is enabled.
 
-```sh
-npm install
-npm install --prefix native
-npm run lint --prefix native
-npm test --prefix native
-npm run build --prefix native
-```
+```tsx
+import { SliceBackgroundBlur, SliceLiquidGlassView } from '@apple-pie/slice-native';
+
+// Place over background content; fills its parent by default.
+<SliceBackgroundBlur blurIntensity={20} fadeStop={0.5} direction="down" />
 
-The build refreshes generated icons, checks types, and produces `dist/cjs/index.js`,
-`dist/esm/index.mjs`, and declarations under `dist/types`. React, React Native, and
-react-native-svg stay external peer dependencies. The web build is independent.
+<SliceLiquidGlassView cornerRadius={24} glassStyle="regular" style={{ padding: 20 }}>
+  {/* Foreground content */}
+</SliceLiquidGlassView>
 
-Native tests use their own `vitest.config.mts` and mocked native components. Install native
-dependencies before running them. Root tests and coverage do not include the native package;
-passing the native unit tests does not replace device rendering checks.
+<SliceButton liquidGlassBackground={{ glassStyle: 'clear', fallbackColor: '#eeeeee' }}>
+  Continue
+</SliceButton>
+```
+
+Blur defaults to intensity `12` and `fadeStop={0}`, which renders uniform blur
+without a mask. A positive `fadeStop` (0–1) enables fading on iOS. Directions are
+`down`, `up`, `left`, and `right`, from transparent toward full blur. Android
+ignores fading props. This fades the visibility of a uniform blur rather than
+varying the blur radius across the view.
 
-CI runs these checks independently in **Slice Native Lint, Build, Test** on Node 24.
-It uses `npm run lint:ci --prefix native` to check formatting and types without writing
-fixes, then runs native tests, builds, and inspects the package contents. Root dependencies
-provide shared tooling such as Biome; native dependencies are installed separately.
+Use `cornerRadius` to control a glass container’s shape. Supported glass buttons
+keep their background transparent; unsupported devices use their solid background
+or configured fallback. Both effect components accept `fallbackColor`. Avoid opaque
+content over glass when you want the backdrop to remain visible. Android backdrop
+blur samples the same window; separately composed surfaces such as video may differ.
 
-Run `npm pack --dry-run` from `native/` to inspect the publishable files, or
-`npm pack` to create a tarball. The `prepack` hook builds automatically. Build and
-pack from this repository: generation uses the web artwork in `src/components/Icon`.
+## Hooks, provider, and theme
 
-## Theme tokens
+| Export | Purpose |
+| --- | --- |
+| `SliceThemeProvider` | Light/dark themes; follows the system by default. Use `preference="light"` or `"dark"` to override. |
+| `useSliceTheme()` | Returns the active theme. |
+| `useSliceContext()` | Returns the theme, mode, preference, and optional preference setter. |
+| `useCreateThemedStyles(factory)` | Creates memoized styles from the active theme. Define the factory outside the component for stable reuse. |
+| `useDeviceCapabilities()` | Reports native effect support, platform, OS/API version, and device information. Does not require the theme provider. |
 
 ```tsx
-import { Text, View, useColorScheme } from 'react-native';
-import { lightTheme, darkTheme } from '@apple-pie/slice-native/theme';
+const {
+  supportsLiquidGlass,
+  supportsNativeBlur,
+  platform,
+  iosVersion,
+  androidSdkVersion,
+  deviceName,
+  deviceModel,
+} = useDeviceCapabilities();
+```
 
-function Card() {
-  const theme = useColorScheme() === 'dark' ? darkTheme : lightTheme;
-  return (
-    <View style={{
-      backgroundColor: theme.colors['core-surface-primary'],
-      padding: theme.spacing.m,
-      borderRadius: theme.corners['corner-m'],
-      ...theme.shadows['surface-shadow-soft'],
-    }}>
-      <Text style={{ ...theme.type['body-m-regular'], color: theme.colors['core-text-primary'] }}>
-        Hello Slice
-      </Text>
-    </View>
-  );
-}
+Capability flags describe API availability, not live accessibility settings or
+per-view rendering conditions. They return `false` when the native module is absent.
+`iosVersion` is a full version string; `androidSdkVersion` is an integer API level
+without minor-release information. Use the support flags for effects decisions.
+Unavailable fields are `null`. iOS device names may be generic; its model is a
+hardware identifier such as `iPhone17,1`, not a marketing name. Android reports
+the system model name/code.
+
+`lightTheme`, `darkTheme`, and `createTypography` are exported alongside theme types.
+Themes include colors, spacing, corners, typography, shadows, stacking levels, and
+motion. The `/theme` entry also exposes the underlying token groups. Typography
+uses Funnel Sans by default; load it in your app or use `createTypography` with
+your own loaded font. Fonts are not loaded by the package.
+
+## Utilities and entry points
+
+| Utility | Purpose |
+| --- | --- |
+| `sizeToNumber(size)` | Resolves size presets to points: `s` = 40, `m` = 48, `l` = 56. |
+| `borderRadiusToNumber(radius)` | Resolves `pill` to 1000, `rectangular` to 4, and numeric radii to nonnegative points. |
+| `lineHeightTextStyle(style, multiplier)` | Returns a new text style with an absolute line height. |
+
+Public types include `Size`, `BorderRadius`, `LiquidGlassBackground`,
+`DeviceCapabilities`, component props, and theme/provider types.
+
+Import from the package root or the dedicated `/components`, `/hooks`, `/providers`,
+`/theme`, and `/utils` entry points. ESM, CommonJS, TypeScript declarations, and
+Metro platform files are included. Theme tokens and utilities can be used independently
+of the component runtime.
+
+## Development
+
+From the repository root:
+
+```sh
+npm install
+npm install --prefix native
+npm run lint:ci --prefix native
+npm run coverage --prefix native
+npm run test:package --prefix native
+npm run pack:tarball --prefix native
 ```
 
-`lightTheme`, `darkTheme`, `createTypography`, and the `SliceNativeTheme` type are
-also available from the package root. `SliceTheme` aliases the native theme type.
-The dedicated `/theme` entry has no runtime React Native, React, or SVG imports.
-It also exports `coreColors`, `corners`, `spacing`, `elevations`, `type`, and `motion`.
-
-Colors, spacing, corners, and stacking levels are sourced from the web tokens at
-build time and bundled into this package. No web package is needed in an app.
-CSS shadow strings are removed from `colors` and `coreColors`; use `theme.shadows`
-instead. Shadows use native `boxShadow` arrays, which require the New Architecture
-and supported Android versions (outset shadows require Android 9+).
-
-Typography uses a fixed 16dp base for rem conversion and numeric line heights and
-letter spacing. Load Funnel Sans in your app, or replace `theme.type` with
-`createTypography('YourLoadedFontName')`. Exact font weights depend on the font
-and platform; test your loaded font on devices. This package does not load fonts.
-
-Motion durations are milliseconds. Curve tokens are easing functions suitable for
-`Animated.timing`'s `easing` option; the CSS spring is interpolated from its original
-samples, preserving overshoot. They are ordinary JavaScript functions, not Reanimated
-worklets. `elevations` retains the web stacking levels for `zIndex`; do not pass these
-values to Android's `elevation` property.
-
-Build from the repository so shared source tokens are available. All generated
-JavaScript and declarations are included under `dist/`, including declarations for
-shared source types. Changes to web tokens are picked up by the next native build.
+Builds regenerate and automatically format native icons from the shared web artwork,
+check types, and emit the package distributions. The tarball is written to
+`native/pack/apple-pie-slice-native-<version>.tgz`; reinstall it and rebuild the
+consuming native app when testing platform changes.
+
+Browser documentation runs with `npm run storybook:native` from the repository root.
+It previews web fallbacks; native effects need simulator/device checks. Native unit
+coverage enforces a 95% overall threshold and does not measure Swift/Java rendering.

package/SliceNative.podspec

@@ -0,0 +1,24 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'SliceNative'
+  s.module_name = 'SliceNative'
+  s.version = package['version']
+  s.summary = package['description']
+  s.homepage = 'https://github.com/uris/slice'
+  s.license = package['license']
+  s.authors = package['author']
+  s.source = { :git => 'https://github.com/uris/slice.git', :tag => "native-v#{s.version}" }
+  s.platforms = { :ios => min_ios_version_supported }
+  s.swift_version = '5.0'
+  s.requires_arc = true
+  s.source_files = 'platform/ios/**/*.{h,m,mm,swift}'
+  # Keep C++ React headers out of the module imported by the Swift compiler.
+  s.private_header_files = 'platform/ios/RCT*View.h', 'platform/ios/SliceDeviceCapabilities.h'
+  s.frameworks = 'UIKit'
+  s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' }
+
+  install_modules_dependencies(s)
+end

package/dist/cjs/components.js

@@ -0,0 +1,19 @@
+'use strict';
+
+var SliceIcon = require('./src/components/SliceIcon/SliceIcon.js');
+var icons = require('./src/components/SliceIcon/icons.js');
+var SliceText = require('./src/components/SliceText/SliceText.js');
+var SliceButton = require('./src/components/SliceButton/SliceButton.js');
+var SliceTextInput = require('./src/components/SliceTextInput/SliceTextInput.js');
+var SliceLiquidGlassView = require('./src/components/SliceLiquidGlassView/SliceLiquidGlassView.js');
+var SliceBackgroundBlur = require('./src/components/SliceBackgroundBlur/SliceBackgroundBlur.js');
+
+
+
+exports.SliceIcon = SliceIcon.SliceIcon;
+exports.SliceIcons = icons.SliceIcons;
+exports.StyledText = SliceText.StyledText;
+exports.SliceButton = SliceButton.SliceButton;
+exports.SliceTextInput = SliceTextInput.SliceTextInput;
+exports.SliceLiquidGlassView = SliceLiquidGlassView.SliceLiquidGlassView;
+exports.SliceBackgroundBlur = SliceBackgroundBlur.SliceBackgroundBlur;

package/dist/cjs/hooks.js

@@ -0,0 +1,9 @@
+'use strict';
+
+var useCreateThemedStyles = require('./src/hooks/useCreateThemedStyles/useCreateThemedStyles.js');
+var useDeviceCapabilities = require('./src/hooks/useDeviceCapabilities/useDeviceCapabilities.js');
+
+
+
+exports.useCreateThemedStyles = useCreateThemedStyles.useCreateThemedStyles;
+exports.useDeviceCapabilities = useDeviceCapabilities.useDeviceCapabilities;