@isoline-ui/native 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Isoline UI contributors
+Copyright (c) 2015-present 650 Industries, Inc. (aka Expo)
+
+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/NOTICE.md

@@ -0,0 +1,16 @@
+# Source notices
+
+The initial primitives were extracted with the owner's authorisation from the
+UI code maintained for Yours, Inboki and Atlas. Product data, credentials,
+artwork and feature code are not included.
+
+The existing MIT notice for 650 Industries, Inc. (Expo) is retained in LICENSE.
+Isoline-specific functional glyphs use simple original SVG paths. App-specific
+Material Symbols icon collections and brand fonts are not bundled.
+
+Runtime packages remain subject to their respective licences. Apps consuming
+Isoline should regenerate their dependency licence notices after integration.
+
+Android system-palette reading and dynamic color interpolation were extracted
+with the owner's authorisation from Yours (pserrer/mail). The native glass
+implementation is provided by the separately installed expo-glass-effect peer.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @isoline-ui/native
+
+Native system appearance for Isoline UI, distributed as an Expo module.
+
+- Android 12+: reads the device's five Material You tonal palettes.
+- iOS 26+: `MaterialSurface` uses native Liquid Glass through `expo-glass-effect`.
+- Web: CSS backdrop-filter approximation with solid fallbacks for unsupported browsers, reduced transparency and forced colors.
+- Unsupported devices, a missing Android bridge and reduced transparency use solid theme surfaces.
+
+Install **both** Isoline archives from the same GitHub prerelease, then let Expo
+select the glass dependency for the app's SDK:
+
+```sh
+npm install https://github.com/isoline-ui/isoline-ui/releases/download/v0.1.0-alpha.2/isoline-ui-react-native-0.1.0-alpha.2.tgz https://github.com/isoline-ui/isoline-ui/releases/download/v0.1.0-alpha.2/isoline-ui-native-0.1.0-alpha.2.tgz
+npx expo install expo-glass-effect
+```
+
+Keep the UI package's existing NativeWind and native peer setup. This package
+supports Expo SDK 57 and 58; do not force the SDK 58 glass version into SDK 57.
+
+```tsx
+import { IsolineProvider, themes, Text } from '@isoline-ui/react-native';
+import { MaterialSurface, useSystemTheme } from '@isoline-ui/native';
+
+function AppContent() {
+  // Supply your app's persisted preference and its active light/dark scheme.
+  const theme = useSystemTheme(themes.teal.light, true);
+  return (
+    <IsolineProvider theme={theme}>
+      <MaterialSurface style={{ borderRadius: 24, padding: 20 }}>
+        <Text>A shared component with a platform material</Text>
+      </MaterialSurface>
+    </IsolineProvider>
+  );
+}
+```
+
+`useSystemTheme(base, enabled)` preserves typography and semantic error/success
+colors. It refreshes the palette when the app becomes active and when system
+appearance changes. The supplied base controls light/dark mode; preferences and
+persistence remain app responsibilities. `getSystemPalette()` and
+`useSystemPalette()` expose the validated raw palette for custom integrations.
+
+`MaterialSurface` accepts View props plus `material: 'auto' | 'glass' | 'solid'`,
+`fallbackColor`, `tintColor`, `glassStyle: 'regular' | 'clear'` and `interactive`.
+Even explicit `glass` respects platform support and Reduce Transparency.
+`interactive` enables native material interaction; add your own accessible
+button to handle actions. Style glass with layout/radius/padding, avoiding opaque
+backgrounds and opacity animations on the glass or its ancestors. Use it for
+selected floating controls and navigation surfaces; it does not turn an entire
+screen into a native toolbar, tab bar or SwiftUI control.
+
+## Native linking and builds
+
+The npm name `@isoline-ui/native` is scoped; the Kotlin namespace
+`isoline.modules.systemcolors` and bridge name `IsolineSystemColors` are separate.
+Expo discovers the module from `expo-module.config.json` in the installed package.
+The archive contains the Android Gradle project and Kotlin sources. No manual
+`nativeModulesDir` entry is required for this dependency.
+
+The new bridge name allows coexistence with Yours' old `ExpoSystemColors` during
+migration. Once consumers switch to the shared hook, remove their unused local
+module and palette/theme logic. Do not copy the new native module into `modules/`
+as well as installing it.
+
+After adding or changing native dependencies, rebuild the development client or
+app (`npx expo run:android`, `npx expo run:ios`, or EAS Build). For projects that
+maintain native folders manually, follow their existing Gradle/CocoaPods workflow.
+An OTA update cannot add native code: use an appropriate Expo runtime version.
+Expo Go does not contain the custom Isoline Android module and uses the fallback.
+
+The showcase and CI test source types, palette mapping, installed-tarball
+Autolinking and Metro exports. These checks do not establish device rendering,
+accessibility behavior or native compilation; see `docs/native.md`.
+
+## Shared navigation surfaces
+
+Register `surfaceComponent={MaterialSurface}` and
+`surfaceGroupComponent={MaterialGroup}` on `IsolineProvider` using the optional
+`@isoline-ui/native` adapters. Core UI works without Expo using solid fallbacks.
+
+The shared `MaterialOptions` contract (`material`, `glassStyle`, `tintColor`,
+`fallbackColor`, `interactive`) supports buttons/icon buttons, search, segmented
+controls, pickers, floating/split actions, toolbars, navigation, tabs, popovers,
+context menus and optional overlay surfaces. `TabBar` is controlled; routing
+remains in the app. `Popover` anchors, flips and clamps a scrollable panel.
+Context menus and pickers support disabled and selected options. Action menus
+also support destructive actions.
+
+Navigation and anchored menus default to automatic material. Form/action controls,
+dialogs, sheets and snackbars default to solid; opt in per surface. Android stays
+solid Material UI. iOS uses native glass where available and respects Reduce
+Transparency. `SurfaceGroup` uses native `GlassContainer` to blend nearby glass
+surfaces and can animate `gap`, respecting reduced motion. Browser groups animate
+spacing only: CSS backdrop blur approximates glass without native merging or
+refraction. Use a contrasting background to make translucency visible.
+
+The new controls require native/device verification in consumer builds; browser
+checks and Metro exports do not verify UIKit rendering or accessibility.

package/android/build.gradle

@@ -0,0 +1,18 @@
+// Same layout as modules/expo-imap: expo-module-gradle-plugin applies the
+// Kotlin plugin and configures publishing itself.
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'isoline.modules.systemcolors'
+version = '0.1.0'
+
+android {
+  namespace 'isoline.modules.systemcolors'
+
+  defaultConfig {
+    versionCode 1
+    versionName '0.1.0'
+  }
+}

package/android/src/main/java/isoline/modules/systemcolors/IsolineSystemColorsModule.kt

@@ -0,0 +1,123 @@
+package isoline.modules.systemcolors
+
+import android.annotation.TargetApi
+import android.content.Context
+import android.os.Build
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+/**
+ * The device's Material You tonal palettes — the colors Android 12+ derives
+ * from the wallpaper (or the user's chosen theme) and hands to every app that
+ * asks, which is where Gmail and the system apps get their colors from.
+ *
+ * Only the raw palettes cross the bridge. Which tone of which palette plays
+ * which role is decided in `src/dynamic-color.ts`, where it can be tested
+ * and changed over the air.
+ */
+class IsolineSystemColorsModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("IsolineSystemColors")
+
+    // Synchronous: a handful of resource lookups, and the first frame needs
+    // the answer to paint in the right colors rather than flash the default.
+    Function("getPalette") {
+      val context = appContext.reactContext ?: return@Function null
+      if (Build.VERSION.SDK_INT < Build.VERSION_CODES.S) return@Function null
+      readPalette(context)
+    }
+  }
+
+  @TargetApi(Build.VERSION_CODES.S)
+  private fun readPalette(context: Context): Map<String, List<String>> = mapOf(
+    "accent1" to tones(context, ACCENT1),
+    "accent2" to tones(context, ACCENT2),
+    "accent3" to tones(context, ACCENT3),
+    "neutral1" to tones(context, NEUTRAL1),
+    "neutral2" to tones(context, NEUTRAL2),
+  )
+
+  private fun tones(context: Context, ids: IntArray): List<String> =
+    ids.map { id -> String.format("#%06X", 0xFFFFFF and context.getColor(id)) }
+
+  private companion object {
+    // Each palette in the order of its stops: _0 (tone 100, white) through
+    // _1000 (tone 0, black). `PALETTE_TONES` in `src/dynamic-color.ts`
+    // mirrors this order.
+    val ACCENT1 = intArrayOf(
+      android.R.color.system_accent1_0,
+      android.R.color.system_accent1_10,
+      android.R.color.system_accent1_50,
+      android.R.color.system_accent1_100,
+      android.R.color.system_accent1_200,
+      android.R.color.system_accent1_300,
+      android.R.color.system_accent1_400,
+      android.R.color.system_accent1_500,
+      android.R.color.system_accent1_600,
+      android.R.color.system_accent1_700,
+      android.R.color.system_accent1_800,
+      android.R.color.system_accent1_900,
+      android.R.color.system_accent1_1000,
+    )
+    val ACCENT2 = intArrayOf(
+      android.R.color.system_accent2_0,
+      android.R.color.system_accent2_10,
+      android.R.color.system_accent2_50,
+      android.R.color.system_accent2_100,
+      android.R.color.system_accent2_200,
+      android.R.color.system_accent2_300,
+      android.R.color.system_accent2_400,
+      android.R.color.system_accent2_500,
+      android.R.color.system_accent2_600,
+      android.R.color.system_accent2_700,
+      android.R.color.system_accent2_800,
+      android.R.color.system_accent2_900,
+      android.R.color.system_accent2_1000,
+    )
+    val ACCENT3 = intArrayOf(
+      android.R.color.system_accent3_0,
+      android.R.color.system_accent3_10,
+      android.R.color.system_accent3_50,
+      android.R.color.system_accent3_100,
+      android.R.color.system_accent3_200,
+      android.R.color.system_accent3_300,
+      android.R.color.system_accent3_400,
+      android.R.color.system_accent3_500,
+      android.R.color.system_accent3_600,
+      android.R.color.system_accent3_700,
+      android.R.color.system_accent3_800,
+      android.R.color.system_accent3_900,
+      android.R.color.system_accent3_1000,
+    )
+    val NEUTRAL1 = intArrayOf(
+      android.R.color.system_neutral1_0,
+      android.R.color.system_neutral1_10,
+      android.R.color.system_neutral1_50,
+      android.R.color.system_neutral1_100,
+      android.R.color.system_neutral1_200,
+      android.R.color.system_neutral1_300,
+      android.R.color.system_neutral1_400,
+      android.R.color.system_neutral1_500,
+      android.R.color.system_neutral1_600,
+      android.R.color.system_neutral1_700,
+      android.R.color.system_neutral1_800,
+      android.R.color.system_neutral1_900,
+      android.R.color.system_neutral1_1000,
+    )
+    val NEUTRAL2 = intArrayOf(
+      android.R.color.system_neutral2_0,
+      android.R.color.system_neutral2_10,
+      android.R.color.system_neutral2_50,
+      android.R.color.system_neutral2_100,
+      android.R.color.system_neutral2_200,
+      android.R.color.system_neutral2_300,
+      android.R.color.system_neutral2_400,
+      android.R.color.system_neutral2_500,
+      android.R.color.system_neutral2_600,
+      android.R.color.system_neutral2_700,
+      android.R.color.system_neutral2_800,
+      android.R.color.system_neutral2_900,
+      android.R.color.system_neutral2_1000,
+    )
+  }
+}

package/dist/MaterialGroup.d.ts

@@ -0,0 +1,4 @@
+import * as React from 'react';
+import type { MaterialGroupProps } from './material-types.ts';
+/** Web animates layout only. It does not imitate native merging/refraction. */
+export declare function MaterialGroup({ spacing, gap, animate, style, ...props }: MaterialGroupProps): React.JSX.Element;

package/dist/MaterialGroup.ios.d.ts

@@ -0,0 +1,4 @@
+import * as React from 'react';
+import type { MaterialGroupProps } from './material-types.ts';
+/** Native merging follows the smoothly changing layout, with a reduced-motion path. */
+export declare function MaterialGroup({ spacing, gap, animate, style, ...props }: MaterialGroupProps): React.JSX.Element;

package/dist/MaterialSurface.d.ts

@@ -0,0 +1,4 @@
+import * as React from 'react';
+import type { MaterialSurfaceProps } from './material-types.ts';
+export type { MaterialSurfaceProps } from './material-types.ts';
+export declare function MaterialSurface({ material, fallbackColor, tintColor, glassStyle, interactive, style, ...props }: MaterialSurfaceProps): React.JSX.Element;

package/dist/MaterialSurface.ios.d.ts

@@ -0,0 +1,4 @@
+import * as React from 'react';
+import type { MaterialSurfaceProps } from './material-types.ts';
+export type { MaterialSurfaceProps } from './material-types.ts';
+export declare function MaterialSurface({ material, fallbackColor, tintColor, glassStyle, interactive, style, ...props }: MaterialSurfaceProps): React.JSX.Element;

package/dist/MaterialSurface.web.d.ts

@@ -0,0 +1,5 @@
+import * as React from 'react';
+import type { MaterialSurfaceProps } from './material-types.ts';
+export type { MaterialSurfaceProps } from './material-types.ts';
+/** CSS approximation only: browsers cannot render Apple's native Liquid Glass. */
+export declare function MaterialSurface({ material, fallbackColor, tintColor, glassStyle, interactive, style, ...props }: MaterialSurfaceProps): React.JSX.Element;

package/dist/dynamic-color.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Material You: the app's color roles, taken from the device's own palette.
+ *
+ * Android 12+ derives five tonal palettes from the wallpaper (or a theme the
+ * user picked) — three accents and two neutrals — and every app that follows
+ * the system, Gmail included, draws its roles from them. The native side
+ * (`modules/expo-system-colors`) only hands the palettes over; this module
+ * decides which tone of which palette plays each role, so the mapping can be
+ * tested and changed over the air.
+ *
+ * Tones follow the Material 3 scheme for the accent roles. The surfaces take
+ * their cue from Gmail in the light scheme: the screen behind everything is
+ * tinted from the secondary palette, and the cards on it (thread rows,
+ * settings groups) stay near-white, so the wallpaper shows in the space
+ * around the content rather than in the content itself. Chips, fields and
+ * button groups (`surface-container-high`) take a tinted fill so they still
+ * read against a white card. The dark scheme keeps the app's own neutral
+ * tones, including its deliberate inversion (the background sits lighter
+ * than the containers on it, see `global.css`).
+ *
+ * Pure and free of `expo-*` imports so it runs under `node --test`.
+ */
+/** Tone of each stop in a palette as Android reports it: `_0` (white) through `_1000` (black). */
+export declare const PALETTE_TONES: readonly [100, 99, 95, 90, 80, 70, 60, 50, 40, 30, 20, 10, 0];
+declare const PALETTE_KEYS: readonly ["accent1", "accent2", "accent3", "neutral1", "neutral2"];
+type PaletteKey = (typeof PALETTE_KEYS)[number];
+/** The device's tonal palettes, each a `#rrggbb` per stop in `PALETTE_TONES` order. */
+export type SystemPalette = Readonly<Record<PaletteKey, readonly string[]>>;
+/**
+ * Narrows what the native module returned to a usable palette, or `null`.
+ *
+ * Anything short of five complete palettes of valid colors is refused whole
+ * rather than patched: a half-read palette would paint some roles from the
+ * wallpaper and leave others unset.
+ */
+export declare function parseSystemPalette(value: unknown): SystemPalette | null;
+/** Whether two palettes hold the same colors, so a re-read that changed nothing re-renders nothing. */
+export declare function samePalette(a: SystemPalette | null, b: SystemPalette | null): boolean;
+/** One scheme's roles, both as `#rrggbb` and as the `H S% L%` triplet `global.css` variables hold. */
+export interface DynamicRoles {
+    hex: Readonly<Record<string, string>>;
+    vars: Readonly<Record<string, string>>;
+}
+/**
+ * The role colors for one scheme. Cached per palette object: this runs on
+ * every render of every component that reads a theme color, and the palette
+ * only changes when the wallpaper does.
+ */
+export declare function dynamicRoles(palette: SystemPalette, scheme: 'light' | 'dark'): DynamicRoles;
+/**
+ * A palette's color at any tone, `#rrggbb`.
+ *
+ * Android reports thirteen stops, and several roles sit between them
+ * (the light background at 94, the dark one at 11). Material
+ * tone is CIE L*, so a tone between two stops is found by interpolating in
+ * CIELAB: L* lands exactly on the tone asked for, and chroma eases between
+ * the neighbours' — fading out toward black and white as it should.
+ */
+export declare function paletteTone(stops: readonly string[], tone: number): string;
+export type Rgb = [number, number, number];
+export type Lab = [number, number, number];
+export declare function hexToRgb(hex: string): Rgb;
+export declare function hexToLab(hex: string): Lab;
+/** `#rrggbb` to the `H S% L%` triplet a `global.css` variable holds, one decimal place each. */
+export declare function hexToHslTriplet(hex: string): string;
+/** `#rrggbb` to hue in degrees, saturation and lightness in percent, unrounded. */
+export declare function hexToHsl(hex: string): [number, number, number];
+export {};

package/dist/glass-support.ios.d.ts

@@ -0,0 +1,2 @@
+/** Fail closed until accessibility preferences are known; newer events win. */
+export declare function useNativeGlassAvailable(): boolean;

package/dist/hooks.d.ts

@@ -0,0 +1,5 @@
+import type { IsolineTheme } from '@isoline-ui/react-native/theme';
+import { type SystemPalette } from './dynamic-color.ts';
+/** Refreshes when returning from wallpaper settings or changing system appearance. */
+export declare function useSystemPalette(enabled?: boolean): SystemPalette | null;
+export declare function useSystemTheme(base: IsolineTheme, enabled?: boolean): IsolineTheme;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { MaterialSurface } from './MaterialSurface';
+export type { MaterialSurfaceProps } from './material-types.ts';
+export { getSystemPalette } from './system-colors.ts';
+export { useSystemPalette, useSystemTheme } from './hooks.ts';
+export { applySystemPalette } from './theme.ts';
+export { parseSystemPalette, dynamicRoles, PALETTE_TONES } from './dynamic-color.ts';
+export type { SystemPalette, DynamicRoles } from './dynamic-color.ts';
+export { MaterialGroup } from './MaterialGroup';
+export type { MaterialGroupProps } from './material-types.ts';

package/dist/material-types.d.ts

@@ -0,0 +1,5 @@
+import type { IsolineSurfaceProps, IsolineSurfaceGroupProps } from '@isoline-ui/react-native';
+export interface MaterialSurfaceProps extends IsolineSurfaceProps {
+}
+export interface MaterialGroupProps extends IsolineSurfaceGroupProps {
+}

package/dist/system-colors.d.ts

@@ -0,0 +1,3 @@
+import { type SystemPalette } from './dynamic-color.ts';
+/** Missing native code and unsupported Android versions use the supplied app theme. */
+export declare function getSystemPalette(): SystemPalette | null;

package/dist/theme.d.ts

@@ -0,0 +1,4 @@
+import type { IsolineTheme } from '@isoline-ui/react-native/theme';
+import { type SystemPalette } from './dynamic-color.ts';
+/** Keeps brand typography and semantic error/success colors. */
+export declare function applySystemPalette(base: IsolineTheme, palette: SystemPalette | null): IsolineTheme;

package/expo-module.config.json

@@ -0,0 +1,6 @@
+{
+  "platforms": ["android"],
+  "android": {
+    "modules": ["isoline.modules.systemcolors.IsolineSystemColorsModule"]
+  }
+}

package/package.json

@@ -1,6 +1,52 @@
-{
-  "name": "@isoline-ui/native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@isoline-ui/native",
+  "version": "1.0.0",
+  "description": "Native system colors and platform materials for Isoline UI",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "react-native": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./theme": {
+      "types": "./dist/dynamic-color.d.ts",
+      "default": "./src/dynamic-color.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "dist",
+    "android",
+    "expo-module.config.json",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/isoline-ui/isoline-ui.git",
+    "directory": "packages/native"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@isoline-ui/react-native": "0.1.0-alpha.3",
+    "expo": ">=57 <59",
+    "expo-glass-effect": ">=57 <59",
+    "react": ">=19.2 <20",
+    "react-native": ">=0.86 <0.89",
+    "react-native-reanimated": ">=4.5.0 <5"
+  },
+  "scripts": {
+    "typecheck": "tsc --project tsconfig.json",
+    "build": "tsc --project tsconfig.build.json"
+  }
+}

package/src/MaterialGroup.ios.tsx

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { View } from 'react-native';
+import { GlassContainer } from 'expo-glass-effect';
+import Animated, {
+  useAnimatedStyle,
+  useSharedValue,
+  withSpring,
+} from 'react-native-reanimated';
+import { spatial, useReducedMotion } from '@isoline-ui/react-native';
+import { useNativeGlassAvailable } from './glass-support.ios.ts';
+import type { MaterialGroupProps } from './material-types.ts';
+const AnimatedContainer = Animated.createAnimatedComponent(GlassContainer);
+/** Native merging follows the smoothly changing layout, with a reduced-motion path. */
+export function MaterialGroup({
+  spacing,
+  gap = 0,
+  animate = true,
+  style,
+  ...props
+}: MaterialGroupProps) {
+  const supported = useNativeGlassAvailable();
+  const reduced = useReducedMotion();
+  const current = useSharedValue(gap);
+  React.useEffect(() => {
+    current.value = animate && !reduced ? withSpring(gap, spatial.default) : gap;
+  }, [gap, animate, reduced, current]);
+  const layout = useAnimatedStyle(() => ({ gap: current.value }));
+  return supported ? (
+    <AnimatedContainer spacing={spacing} {...props} style={[layout, style]} />
+  ) : (
+    <View {...props} style={[{ gap }, style]} />
+  );
+}

package/src/MaterialGroup.tsx

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import { Platform, View, type ViewStyle } from 'react-native';
+import { useReducedMotion } from '@isoline-ui/react-native';
+import type { MaterialGroupProps } from './material-types.ts';
+/** Web animates layout only. It does not imitate native merging/refraction. */
+export function MaterialGroup({
+  spacing,
+  gap,
+  animate = true,
+  style,
+  ...props
+}: MaterialGroupProps) {
+  const reduced = useReducedMotion();
+  const motion =
+    Platform.OS === 'web'
+      ? ({
+          transitionProperty: 'gap',
+          transitionDuration: animate && !reduced ? '180ms' : '0ms',
+        } as ViewStyle)
+      : undefined;
+  return <View {...props} style={[gap !== undefined && { gap }, motion, style]} />;
+}

package/src/MaterialSurface.ios.tsx

@@ -0,0 +1,39 @@
+import * as React from 'react';
+import { View } from 'react-native';
+import { GlassView } from 'expo-glass-effect';
+import { useNativeGlassAvailable } from './glass-support.ios.ts';
+import { useThemeColors, useIsolineTheme } from '@isoline-ui/react-native';
+import type { MaterialSurfaceProps } from './material-types.ts';
+export type { MaterialSurfaceProps } from './material-types.ts';
+
+export function MaterialSurface({
+  material = 'auto',
+  fallbackColor,
+  tintColor,
+  glassStyle = 'regular',
+  interactive = false,
+  style,
+  ...props
+}: MaterialSurfaceProps) {
+  const colors = useThemeColors();
+  const { scheme } = useIsolineTheme();
+  const supported = useNativeGlassAvailable();
+  if (material === 'solid' || !supported) {
+    return (
+      <View
+        {...props}
+        style={[{ backgroundColor: fallbackColor ?? colors.surfaceContainer }, style]}
+      />
+    );
+  }
+  return (
+    <GlassView
+      {...props}
+      style={style}
+      glassEffectStyle={glassStyle}
+      tintColor={tintColor}
+      isInteractive={interactive}
+      colorScheme={scheme}
+    />
+  );
+}

package/src/MaterialSurface.tsx

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import { View } from 'react-native';
+import { useThemeColors } from '@isoline-ui/react-native';
+import type { MaterialSurfaceProps } from './material-types.ts';
+export type { MaterialSurfaceProps } from './material-types.ts';
+
+export function MaterialSurface({
+  material,
+  fallbackColor,
+  tintColor,
+  glassStyle,
+  interactive,
+  style,
+  ...props
+}: MaterialSurfaceProps) {
+  const colors = useThemeColors();
+  return (
+    <View
+      {...props}
+      style={[{ backgroundColor: fallbackColor ?? colors.surfaceContainer }, style]}
+    />
+  );
+}

package/src/MaterialSurface.web.tsx

@@ -0,0 +1,62 @@
+import * as React from 'react';
+import { View, type ViewStyle } from 'react-native';
+import { useThemeColors, useIsolineTheme } from '@isoline-ui/react-native';
+import type { MaterialSurfaceProps } from './material-types.ts';
+export type { MaterialSurfaceProps } from './material-types.ts';
+
+/** CSS approximation only: browsers cannot render Apple's native Liquid Glass. */
+export function MaterialSurface({
+  material = 'auto',
+  fallbackColor,
+  tintColor,
+  glassStyle = 'regular',
+  interactive,
+  style,
+  ...props
+}: MaterialSurfaceProps) {
+  const colors = useThemeColors();
+  const { scheme } = useIsolineTheme();
+  const [supported, setSupported] = React.useState(false);
+  React.useEffect(() => {
+    const transparency = window.matchMedia('(prefers-reduced-transparency: reduce)');
+    const contrast = window.matchMedia('(forced-colors: active)');
+    const update = () =>
+      setSupported(
+        !transparency.matches &&
+          !contrast.matches &&
+          typeof CSS !== 'undefined' &&
+          (CSS.supports('backdrop-filter', 'blur(1px)') ||
+            CSS.supports('-webkit-backdrop-filter', 'blur(1px)')),
+      );
+    update();
+    transparency.addEventListener('change', update);
+    contrast.addEventListener('change', update);
+    return () => {
+      transparency.removeEventListener('change', update);
+      contrast.removeEventListener('change', update);
+    };
+  }, []);
+  const glass = material !== 'solid' && supported;
+  const glassStyleWeb = {
+    backgroundColor:
+      tintColor ??
+      (scheme === 'dark'
+        ? `rgba(28,28,32,${glassStyle === 'clear' ? 0.35 : 0.72})`
+        : `rgba(255,255,255,${glassStyle === 'clear' ? 0.35 : 0.72})`),
+    backdropFilter: 'blur(24px) saturate(160%)',
+    WebkitBackdropFilter: 'blur(24px) saturate(160%)',
+    borderWidth: 1,
+    borderColor: scheme === 'dark' ? 'rgba(255,255,255,0.2)' : 'rgba(255,255,255,0.65)',
+    boxShadow: '0px 4px 20px rgba(0,0,0,0.12)',
+  } as ViewStyle;
+  return (
+    <View
+      {...props}
+      style={[
+        { backgroundColor: fallbackColor ?? colors.surfaceContainer },
+        glass && glassStyleWeb,
+        style,
+      ]}
+    />
+  );
+}

package/src/dynamic-color.ts

@@ -0,0 +1,258 @@
+/**
+ * Material You: the app's color roles, taken from the device's own palette.
+ *
+ * Android 12+ derives five tonal palettes from the wallpaper (or a theme the
+ * user picked) — three accents and two neutrals — and every app that follows
+ * the system, Gmail included, draws its roles from them. The native side
+ * (`modules/expo-system-colors`) only hands the palettes over; this module
+ * decides which tone of which palette plays each role, so the mapping can be
+ * tested and changed over the air.
+ *
+ * Tones follow the Material 3 scheme for the accent roles. The surfaces take
+ * their cue from Gmail in the light scheme: the screen behind everything is
+ * tinted from the secondary palette, and the cards on it (thread rows,
+ * settings groups) stay near-white, so the wallpaper shows in the space
+ * around the content rather than in the content itself. Chips, fields and
+ * button groups (`surface-container-high`) take a tinted fill so they still
+ * read against a white card. The dark scheme keeps the app's own neutral
+ * tones, including its deliberate inversion (the background sits lighter
+ * than the containers on it, see `global.css`).
+ *
+ * Pure and free of `expo-*` imports so it runs under `node --test`.
+ */
+
+/** Tone of each stop in a palette as Android reports it: `_0` (white) through `_1000` (black). */
+export const PALETTE_TONES = [100, 99, 95, 90, 80, 70, 60, 50, 40, 30, 20, 10, 0] as const;
+
+const PALETTE_KEYS = ['accent1', 'accent2', 'accent3', 'neutral1', 'neutral2'] as const;
+
+type PaletteKey = (typeof PALETTE_KEYS)[number];
+
+/** The device's tonal palettes, each a `#rrggbb` per stop in `PALETTE_TONES` order. */
+export type SystemPalette = Readonly<Record<PaletteKey, readonly string[]>>;
+
+const HEX_COLOR = /^#[0-9a-f]{6}$/i;
+
+/**
+ * Narrows what the native module returned to a usable palette, or `null`.
+ *
+ * Anything short of five complete palettes of valid colors is refused whole
+ * rather than patched: a half-read palette would paint some roles from the
+ * wallpaper and leave others unset.
+ */
+export function parseSystemPalette(value: unknown): SystemPalette | null {
+  if (typeof value !== 'object' || value === null) return null;
+  const palette: Partial<Record<PaletteKey, readonly string[]>> = {};
+  for (const key of PALETTE_KEYS) {
+    const tones: unknown = Reflect.get(value, key);
+    if (!Array.isArray(tones) || tones.length !== PALETTE_TONES.length) return null;
+    const colors: string[] = [];
+    for (const tone of tones) {
+      if (typeof tone !== 'string' || !HEX_COLOR.test(tone)) return null;
+      colors.push(tone.toLowerCase());
+    }
+    palette[key] = colors;
+  }
+  const { accent1, accent2, accent3, neutral1, neutral2 } = palette;
+  if (!accent1 || !accent2 || !accent3 || !neutral1 || !neutral2) return null;
+  return { accent1, accent2, accent3, neutral1, neutral2 };
+}
+
+/** Whether two palettes hold the same colors, so a re-read that changed nothing re-renders nothing. */
+export function samePalette(a: SystemPalette | null, b: SystemPalette | null): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return PALETTE_KEYS.every((key) => a[key].every((color, index) => color === b[key][index]));
+}
+
+type Role = readonly [palette: PaletteKey, light: number, dark: number];
+
+/**
+ * Every CSS variable `global.css` defines that the accent tints, plus the
+ * tertiary roles (which keep a fixed indigo under the presets but follow the
+ * wallpaper's third accent here, as they do in the system apps). Error and
+ * the triage colors stay fixed: they carry meaning, not decoration.
+ */
+const ROLES: Record<string, Role> = {
+  '--background': ['accent2', 94, 11],
+  '--foreground': ['neutral1', 10, 90],
+  '--surface': ['accent2', 94, 11],
+  '--surface-variant': ['neutral2', 90, 25],
+  '--on-surface': ['neutral1', 10, 90],
+  '--on-surface-variant': ['neutral2', 30, 80],
+  '--surface-container-lowest': ['neutral1', 100, 6],
+  '--surface-container-low': ['neutral1', 99, 8],
+  '--surface-container': ['neutral1', 97, 13],
+  '--surface-container-high': ['accent2', 90, 17],
+  '--surface-container-highest': ['accent2', 87, 22],
+  '--card': ['neutral1', 99, 13],
+  '--card-foreground': ['neutral1', 10, 90],
+  '--popover': ['neutral1', 97, 17],
+  '--popover-foreground': ['neutral1', 10, 90],
+  '--primary': ['accent1', 40, 80],
+  '--primary-foreground': ['accent1', 100, 20],
+  '--primary-container': ['accent1', 90, 30],
+  '--on-primary-container': ['accent1', 10, 90],
+  '--secondary-container': ['accent2', 90, 30],
+  '--on-secondary-container': ['accent2', 10, 90],
+  '--tertiary': ['accent3', 40, 80],
+  '--on-tertiary': ['accent3', 100, 20],
+  '--tertiary-container': ['accent3', 90, 30],
+  '--on-tertiary-container': ['accent3', 10, 90],
+  '--muted': ['neutral2', 90, 25],
+  '--muted-foreground': ['neutral2', 30, 80],
+  '--accent': ['accent2', 90, 22],
+  '--accent-foreground': ['accent1', 10, 90],
+  '--outline': ['neutral2', 50, 60],
+  '--outline-variant': ['neutral2', 80, 30],
+  '--border': ['neutral2', 80, 22],
+  '--input': ['neutral2', 55, 45],
+  '--ring': ['accent1', 40, 80],
+  '--inverse-surface': ['neutral1', 20, 90],
+  '--inverse-on-surface': ['neutral1', 95, 20],
+  '--inverse-primary': ['accent1', 80, 40],
+};
+
+/** One scheme's roles, both as `#rrggbb` and as the `H S% L%` triplet `global.css` variables hold. */
+export interface DynamicRoles {
+  hex: Readonly<Record<string, string>>;
+  vars: Readonly<Record<string, string>>;
+}
+
+const cache = new WeakMap<SystemPalette, { light?: DynamicRoles; dark?: DynamicRoles }>();
+
+/**
+ * The role colors for one scheme. Cached per palette object: this runs on
+ * every render of every component that reads a theme color, and the palette
+ * only changes when the wallpaper does.
+ */
+export function dynamicRoles(palette: SystemPalette, scheme: 'light' | 'dark'): DynamicRoles {
+  const entry = cache.get(palette) ?? {};
+  const cached = entry[scheme];
+  if (cached) return cached;
+
+  const hex: Record<string, string> = {};
+  const vars: Record<string, string> = {};
+  for (const [name, [key, light, dark]] of Object.entries(ROLES)) {
+    const color = paletteTone(palette[key], scheme === 'light' ? light : dark);
+    hex[name] = color;
+    vars[name] = hexToHslTriplet(color);
+  }
+  const roles = { hex, vars };
+  entry[scheme] = roles;
+  cache.set(palette, entry);
+  return roles;
+}
+
+/**
+ * A palette's color at any tone, `#rrggbb`.
+ *
+ * Android reports thirteen stops, and several roles sit between them
+ * (the light background at 94, the dark one at 11). Material
+ * tone is CIE L*, so a tone between two stops is found by interpolating in
+ * CIELAB: L* lands exactly on the tone asked for, and chroma eases between
+ * the neighbours' — fading out toward black and white as it should.
+ */
+export function paletteTone(stops: readonly string[], tone: number): string {
+  const target = Math.min(100, Math.max(0, tone));
+  for (let index = 0; index < PALETTE_TONES.length - 1; index++) {
+    const upper = PALETTE_TONES[index];
+    const lower = PALETTE_TONES[index + 1];
+    if (target > upper || target < lower) continue;
+    if (target === upper) return stops[index];
+    if (target === lower) return stops[index + 1];
+    const t = (upper - target) / (upper - lower);
+    const from = hexToLab(stops[index]);
+    const to = hexToLab(stops[index + 1]);
+    return labToHex([target, from[1] + (to[1] - from[1]) * t, from[2] + (to[2] - from[2]) * t]);
+  }
+  return stops[stops.length - 1];
+}
+
+export type Rgb = [number, number, number];
+export type Lab = [number, number, number];
+
+export function hexToRgb(hex: string): Rgb {
+  const value = parseInt(hex.slice(1), 16);
+  return [(value >> 16) & 0xff, (value >> 8) & 0xff, value & 0xff];
+}
+
+function rgbToHex([r, g, b]: Rgb): string {
+  const channel = (value: number) =>
+    Math.round(Math.min(255, Math.max(0, value)))
+      .toString(16)
+      .padStart(2, '0');
+  return `#${channel(r)}${channel(g)}${channel(b)}`;
+}
+
+// sRGB (D65) <-> CIELAB.
+const WHITE: Rgb = [95.047, 100, 108.883];
+
+function toLinear(channel: number): number {
+  const c = channel / 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+function fromLinear(value: number): number {
+  const c = value <= 0.0031308 ? value * 12.92 : 1.055 * value ** (1 / 2.4) - 0.055;
+  return c * 255;
+}
+
+function labF(t: number): number {
+  return t > 216 / 24389 ? Math.cbrt(t) : ((24389 / 27) * t + 16) / 116;
+}
+
+function labFInverse(t: number): number {
+  return t ** 3 > 216 / 24389 ? t ** 3 : (116 * t - 16) / (24389 / 27);
+}
+
+export function hexToLab(hex: string): Lab {
+  const [r, g, b] = hexToRgb(hex).map(toLinear);
+  const x = (0.4124 * r + 0.3576 * g + 0.1805 * b) * 100;
+  const y = (0.2126 * r + 0.7152 * g + 0.0722 * b) * 100;
+  const z = (0.0193 * r + 0.1192 * g + 0.9505 * b) * 100;
+  const fx = labF(x / WHITE[0]);
+  const fy = labF(y / WHITE[1]);
+  const fz = labF(z / WHITE[2]);
+  return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)];
+}
+
+function labToHex([l, a, b]: Lab): string {
+  const fy = (l + 16) / 116;
+  const x = labFInverse(fy + a / 500) * WHITE[0];
+  const y = labFInverse(fy) * WHITE[1];
+  const z = labFInverse(fy - b / 200) * WHITE[2];
+  const [xn, yn, zn] = [x / 100, y / 100, z / 100];
+  return rgbToHex([
+    fromLinear(3.2406 * xn - 1.5372 * yn - 0.4986 * zn),
+    fromLinear(-0.9689 * xn + 1.8758 * yn + 0.0415 * zn),
+    fromLinear(0.0557 * xn - 0.204 * yn + 1.057 * zn),
+  ]);
+}
+
+/** `#rrggbb` to the `H S% L%` triplet a `global.css` variable holds, one decimal place each. */
+export function hexToHslTriplet(hex: string): string {
+  const round = (value: number) => Math.round(value * 10) / 10;
+  const [hue, saturation, lightness] = hexToHsl(hex);
+  return `${round(hue)} ${round(saturation)}% ${round(lightness)}%`;
+}
+
+/** `#rrggbb` to hue in degrees, saturation and lightness in percent, unrounded. */
+export function hexToHsl(hex: string): [number, number, number] {
+  const [r, g, b] = hexToRgb(hex).map((channel) => channel / 255);
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const lightness = (max + min) / 2;
+  const delta = max - min;
+  let hue = 0;
+  let saturation = 0;
+  if (delta > 0) {
+    saturation = delta / (1 - Math.abs(2 * lightness - 1));
+    if (max === r) hue = ((g - b) / delta) % 6;
+    else if (max === g) hue = (b - r) / delta + 2;
+    else hue = (r - g) / delta + 4;
+    hue *= 60;
+    if (hue < 0) hue += 360;
+  }
+  return [hue, saturation * 100, lightness * 100];
+}

package/src/glass-support.ios.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import { AccessibilityInfo } from 'react-native';
+import { isLiquidGlassAvailable, isGlassEffectAPIAvailable } from 'expo-glass-effect';
+/** Fail closed until accessibility preferences are known; newer events win. */
+export function useNativeGlassAvailable() {
+  const [reduceTransparency, setReduceTransparency] = React.useState(true);
+  React.useEffect(() => {
+    let current = true;
+    const sub = AccessibilityInfo.addEventListener('reduceTransparencyChanged', (value) => {
+      current = false;
+      setReduceTransparency(value);
+    });
+    void AccessibilityInfo.isReduceTransparencyEnabled().then(
+      (value) => {
+        if (current) setReduceTransparency(value);
+      },
+      () => {},
+    );
+    return () => {
+      current = false;
+      sub.remove();
+    };
+  }, []);
+  return !reduceTransparency && isGlassEffectAPIAvailable() && isLiquidGlassAvailable();
+}

package/src/hooks.ts

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import { AppState, Appearance } from 'react-native';
+import type { IsolineTheme } from '@isoline-ui/react-native/theme';
+import { getSystemPalette } from './system-colors.ts';
+import { samePalette, type SystemPalette } from './dynamic-color.ts';
+import { applySystemPalette } from './theme.ts';
+
+/** Refreshes when returning from wallpaper settings or changing system appearance. */
+export function useSystemPalette(enabled = true): SystemPalette | null {
+  const [palette, setPalette] = React.useState<SystemPalette | null>(() =>
+    enabled ? getSystemPalette() : null,
+  );
+  React.useEffect(() => {
+    if (!enabled) {
+      setPalette(null);
+      return;
+    }
+    const refresh = () => {
+      const next = getSystemPalette();
+      setPalette((previous) => (samePalette(previous, next) ? previous : next));
+    };
+    refresh();
+    const app = AppState.addEventListener('change', (state) => {
+      if (state === 'active') refresh();
+    });
+    const appearance = Appearance.addChangeListener(refresh);
+    return () => {
+      app.remove();
+      appearance.remove();
+    };
+  }, [enabled]);
+  return enabled ? palette : null;
+}
+
+export function useSystemTheme(base: IsolineTheme, enabled = true): IsolineTheme {
+  const palette = useSystemPalette(enabled);
+  return React.useMemo(() => applySystemPalette(base, palette), [base, palette]);
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { MaterialSurface } from './MaterialSurface';
+export type { MaterialSurfaceProps } from './material-types.ts';
+export { getSystemPalette } from './system-colors.ts';
+export { useSystemPalette, useSystemTheme } from './hooks.ts';
+export { applySystemPalette } from './theme.ts';
+export { parseSystemPalette, dynamicRoles, PALETTE_TONES } from './dynamic-color.ts';
+export type { SystemPalette, DynamicRoles } from './dynamic-color.ts';
+export { MaterialGroup } from './MaterialGroup';
+export type { MaterialGroupProps } from './material-types.ts';

package/src/material-types.ts

@@ -0,0 +1,3 @@
+import type { IsolineSurfaceProps, IsolineSurfaceGroupProps } from '@isoline-ui/react-native';
+export interface MaterialSurfaceProps extends IsolineSurfaceProps {}
+export interface MaterialGroupProps extends IsolineSurfaceGroupProps {}

package/src/system-colors.ts

@@ -0,0 +1,17 @@
+import { requireOptionalNativeModule } from 'expo';
+import { Platform } from 'react-native';
+import { parseSystemPalette, type SystemPalette } from './dynamic-color.ts';
+
+interface SystemColorsModule {
+  getPalette(): unknown;
+}
+/** Missing native code and unsupported Android versions use the supplied app theme. */
+export function getSystemPalette(): SystemPalette | null {
+  if (Platform.OS !== 'android') return null;
+  try {
+    const module = requireOptionalNativeModule<SystemColorsModule>('IsolineSystemColors');
+    return parseSystemPalette(module?.getPalette());
+  } catch {
+    return null;
+  }
+}

package/src/theme.ts

@@ -0,0 +1,15 @@
+import type { IsolineTheme } from '@isoline-ui/react-native/theme';
+import { dynamicRoles, type SystemPalette } from './dynamic-color.ts';
+
+/** Keeps brand typography and semantic error/success colors. */
+export function applySystemPalette(
+  base: IsolineTheme,
+  palette: SystemPalette | null,
+): IsolineTheme {
+  if (!palette) return base;
+  return {
+    ...base,
+    name: `${base.name}-system`,
+    tokens: { ...base.tokens, ...dynamicRoles(palette, base.scheme).vars },
+  };
+}