@isoline-ui/react-native 0.0.0-stage → 1.0.0

package/src/provider.tsx

@@ -0,0 +1,201 @@
+import * as React from 'react';
+import { Platform, View, type ViewProps, type StyleProp, type ViewStyle } from 'react-native';
+import { vars } from 'nativewind';
+
+import {
+  resolveThemeColors,
+  rippleColors,
+  elevation,
+  type IsolineTheme,
+  type ThemeColors,
+  type RippleColors,
+} from './theme.ts';
+
+import type { MaterialOptions } from './material.ts';
+export type { MaterialOptions } from './material.ts';
+import { resolvePlatform, type IsolinePlatform } from './platform.ts';
+export type { IsolinePlatform } from './platform.ts';
+export { elevation };
+export interface IsolineSurfaceProps extends ViewProps, MaterialOptions {}
+export interface IsolineSurfaceGroupProps extends ViewProps {
+  spacing?: number;
+  gap?: number;
+  animate?: boolean;
+}
+export type { ThemeColors, RippleColors };
+export interface IsolineLabels {
+  close: string;
+  back: string;
+  showPassword: string;
+  hidePassword: string;
+}
+export interface IsolineHaptics {
+  selectionHaptic: () => void;
+  impactHaptic: (style: 'light' | 'medium') => void;
+}
+
+const noHaptics: IsolineHaptics = { selectionHaptic: () => {}, impactHaptic: () => {} };
+
+interface UIContext {
+  platform: IsolinePlatform;
+  surfaceComponent?: React.ComponentType<IsolineSurfaceProps>;
+  surfaceGroupComponent?: React.ComponentType<IsolineSurfaceGroupProps>;
+  theme: IsolineTheme;
+  colors: ThemeColors;
+  ripple: RippleColors;
+  labels: IsolineLabels;
+  haptics: IsolineHaptics;
+}
+
+const Context = React.createContext<UIContext | null>(null);
+export interface IsolineProviderProps {
+  /** Browser design preview; native devices always follow their OS. */
+  platform?: IsolinePlatform;
+  /** Supply MaterialSurface from @isoline-ui/native for native/browser glass. */
+  surfaceComponent?: React.ComponentType<IsolineSurfaceProps>;
+  surfaceGroupComponent?: React.ComponentType<IsolineSurfaceGroupProps>;
+  theme: IsolineTheme;
+  surface?: React.ComponentType<IsolineSurfaceProps>;
+  labels?: Partial<IsolineLabels>;
+  haptics?: Partial<IsolineHaptics>;
+  children: React.ReactNode;
+  className?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Supplies component contracts and CSS roles together. Preferences, translation,
+ * font loading and native haptic implementations remain in the consuming app.
+ * A nested provider inherits labels/haptics; its theme is explicit.
+ */
+export function IsolineProvider({
+  theme,
+  platform,
+  surface,
+  surfaceComponent,
+  surfaceGroupComponent,
+  labels,
+  haptics,
+  children,
+  className,
+  style,
+}: IsolineProviderProps) {
+  const parent = React.useContext(Context);
+  const value = React.useMemo<UIContext>(
+    () => ({
+      theme,
+      platform: resolvePlatform(Platform.OS, platform, parent?.platform),
+      surfaceComponent: surfaceComponent ?? surface ?? parent?.surfaceComponent,
+      surfaceGroupComponent: surfaceGroupComponent ?? parent?.surfaceGroupComponent,
+      colors: resolveThemeColors(theme),
+      ripple: rippleColors(theme.scheme),
+      labels: {
+        close: 'Close',
+        back: 'Back',
+        showPassword: 'Show password',
+        hidePassword: 'Hide password',
+        ...parent?.labels,
+        ...labels,
+      },
+      haptics: { ...noHaptics, ...parent?.haptics, ...haptics },
+    }),
+    [
+      theme,
+      platform,
+      surface,
+      surfaceComponent,
+      surfaceGroupComponent,
+      labels,
+      haptics,
+      parent,
+    ],
+  );
+
+  return (
+    <Context.Provider value={value}>
+      <View className={className} style={[{ flex: 1 }, vars(theme.tokens), style]}>
+        {children}
+      </View>
+    </Context.Provider>
+  );
+}
+
+function useUI() {
+  const value = React.useContext(Context);
+  if (!value) throw new Error('Isoline UI components must be inside IsolineProvider');
+  return value;
+}
+export function useIsolineTheme() {
+  return useUI().theme;
+}
+export function useThemeColors() {
+  return useUI().colors;
+}
+export function useRipple() {
+  return useUI().ripple;
+}
+export function useLabels() {
+  return useUI().labels;
+}
+export function useHaptics() {
+  return useUI().haptics;
+}
+
+export function useIsolinePlatform() {
+  return useUI().platform;
+}
+/** Surface adapter keeps optional Expo/native dependencies out of the UI package. */
+export function Surface({
+  material = 'auto',
+  interactive,
+  glassStyle,
+  tintColor,
+  fallbackColor,
+  style,
+  ...props
+}: IsolineSurfaceProps) {
+  const { surfaceComponent: Component, colors } = useUI();
+  if (Component)
+    return (
+      <Component
+        material={material}
+        interactive={interactive}
+        glassStyle={glassStyle}
+        tintColor={tintColor}
+        fallbackColor={fallbackColor}
+        style={style}
+        {...props}
+      />
+    );
+  return (
+    <View
+      {...props}
+      style={[{ backgroundColor: fallbackColor ?? colors.surfaceContainer }, style]}
+    />
+  );
+}
+
+export function useSurface() {
+  return Surface;
+}
+/** Reapply CSS variables inside web modal portals, outside the provider DOM node. */
+export function ThemeScope({ style, ...props }: ViewProps) {
+  const { theme } = useUI();
+  return <View {...props} style={[vars(theme.tokens), style]} />;
+}
+
+/** Native adapters can merge neighboring glass; solid/web adapters retain layout. */
+export function SurfaceGroup({
+  spacing,
+  gap,
+  animate = true,
+  style,
+  ...props
+}: IsolineSurfaceGroupProps) {
+  const { surfaceGroupComponent: Component } = useUI();
+  return Component ? (
+    <Component spacing={spacing} gap={gap} animate={animate} style={style} {...props} />
+  ) : (
+    <View {...props} style={[gap !== undefined && { gap }, style]} />
+  );
+}

package/src/reduced-motion.ts

@@ -0,0 +1,50 @@
+import { ReduceMotion, useReducedMotion } from 'react-native-reanimated';
+
+/**
+ * Honouring "Remove animations".
+ *
+ * Android's accessibility settings carry a switch that asks the whole system
+ * to stop moving things, and people turn it on for reasons that are not about
+ * taste: vestibular disorders, migraine, motion sickness, or simply not being
+ * able to read a screen that keeps sliding. This app is unusually animated —
+ * springs everywhere, a wave travelling along every progress bar — so ignoring
+ * that switch is not a small omission.
+ *
+ * The rule is not "turn every animation off". It is: **motion goes, meaning
+ * stays.** Three kinds of animation live in this app and they are treated
+ * differently:
+ *
+ * - **Decoration** — a wave travelling along a bar, a toolbar's items
+ *   unfolding one after another, a card springing in. All of this goes.
+ * - **Orientation** — a sheet rising from the edge it belongs to, a row
+ *   sliding out of a list. The movement goes; the end state arrives at once.
+ * - **Information** — the undo bar's countdown, which is the only thing
+ *   telling the reader how long they have left to change their mind. This one
+ *   *must not* go. Turning it off would not remove a distraction, it would
+ *   remove the answer to "how long do I have", and the reader who needs
+ *   reduced motion is not a reader who needs less information.
+ *
+ * Reanimated already defaults its own animations to `ReduceMotion.System`, so
+ * most of the first two categories are handled by the platform once
+ * `ReducedMotionConfig` states the policy. What this module is for is the
+ * third: the places that have to say `ReduceMotion.Never` on purpose, and the
+ * places where the app's own decorative loops have to be stopped by hand
+ * because Reanimated has no way to know they are decorative.
+ */
+
+export { useReducedMotion };
+
+/**
+ * For an animation that carries information rather than polish.
+ *
+ * Spelled out at each call site rather than defaulted, so that opting a piece
+ * of motion out of the accessibility setting is a decision somebody made and
+ * can be argued with — there should only ever be a handful.
+ */
+export const KEEP_MOTION = ReduceMotion.Never;
+
+/** For everything else: the platform's answer, whatever it is. */
+export const SYSTEM_MOTION = ReduceMotion.System;
+
+/** Re-exported so a call site needs one import, not two. See `~/lib/motion`. */
+export { staggerFor } from './motion.ts';

package/src/selection.ts

@@ -0,0 +1,11 @@
+/** Clamp and quantize controlled slider values without accumulating decimal drift. */
+export function sliderValue(value: number, min = 0, max = 1, step = 0) {
+  if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min)
+    return Number.isFinite(min) ? min : 0;
+  const finite = Number.isFinite(value) ? value : min;
+  const snapped =
+    step > 0 && Number.isFinite(step)
+      ? Number((min + Math.round((finite - min) / step) * step).toPrecision(12))
+      : finite;
+  return Math.max(min, Math.min(max, snapped));
+}

package/src/shape.ts

@@ -0,0 +1,217 @@
+/**
+ * Material 3 Expressive shape system.
+ *
+ * Expressive treats shape as a *state*, not a constant. A component's corners
+ * change when it is pressed, selected or busy, and the change is animated by a
+ * spatial spring (see `motion.ts`). The two halves of that idea live here:
+ *
+ * - `corner`, the shape scale every radius in the app is drawn from, so a
+ *   round-to-square morph moves between two named steps rather than two magic
+ *   numbers;
+ * - the polygon helpers, which make a *shape sequence* possible — morphing a
+ *   4-sided shape into a 7-sided one, which is how the Expressive loading
+ *   indicator is drawn.
+ *
+ * Everything here is pure maths with no `expo-*` or React imports, so it is
+ * covered by `node --test`. The functions used inside animated props are
+ * marked `'worklet'` so they can run on the UI thread.
+ */
+
+/** The Expressive corner scale, in dp. `full` is a pill, sized at runtime. */
+export const corner = {
+  none: 0,
+  extraSmall: 4,
+  small: 8,
+  medium: 12,
+  large: 16,
+  largeIncreased: 20,
+  extraLarge: 28,
+  extraLargeIncreased: 32,
+  extraExtraLarge: 48,
+} as const;
+
+/**
+ * Number of points a shape is sampled at.
+ *
+ * Every shape in a morph sequence is resampled to this many points so two
+ * shapes with different vertex counts can be interpolated pairwise. 48 is
+ * enough that a 9-sided polygon still reads as one, and cheap enough to
+ * rebuild every frame on the UI thread.
+ */
+export const SHAPE_SAMPLES = 48;
+
+/**
+ * Samples a regular polygon as a radius per angle.
+ *
+ * Describing a shape radially — rather than as a vertex list — is what makes
+ * shapes with different vertex counts morphable: two radius arrays of equal
+ * length always interpolate, whereas two vertex lists of different lengths do
+ * not. Radii are normalised so the polygon's corners touch the unit circle.
+ */
+export function polygonRadii(
+  vertices: number,
+  samples: number = SHAPE_SAMPLES,
+  rotation = 0,
+): number[] {
+  const step = (Math.PI * 2) / vertices;
+  // Centre-to-edge distance. A corner sits at 1, an edge midpoint at `apothem`.
+  const apothem = Math.cos(Math.PI / vertices);
+  const radii: number[] = [];
+
+  for (let index = 0; index < samples; index += 1) {
+    const theta = (index / samples) * Math.PI * 2 + rotation;
+    // Angle from the nearest edge midpoint, folded into one polygon segment.
+    const local = (((theta % step) + step) % step) - step / 2;
+    radii.push(apothem / Math.cos(local));
+  }
+
+  return radii;
+}
+
+/**
+ * Rounds a shape's corners by averaging its radii with their neighbours.
+ *
+ * A circular moving average over the radial function is a corner rounding:
+ * the sharp maxima at the vertices flatten while the edges stay put. `amount`
+ * runs 0 (the raw polygon) to 1 (nearly a circle), which is the "roundness"
+ * dimension of the Expressive shape library.
+ */
+export function roundRadii(radii: number[], amount: number): number[] {
+  const span = Math.max(0, Math.round((radii.length / 8) * amount));
+  if (span === 0) return radii.slice();
+
+  const rounded: number[] = [];
+  for (let index = 0; index < radii.length; index += 1) {
+    let total = 0;
+    for (let offset = -span; offset <= span; offset += 1) {
+      total += radii[(index + offset + radii.length * 2) % radii.length]!;
+    }
+    rounded.push(total / (span * 2 + 1));
+  }
+
+  return rounded;
+}
+
+/** A shape in a morph sequence: how many corners, how round, how turned. */
+export interface ShapeSpec {
+  vertices: number;
+  roundness: number;
+  rotation: number;
+}
+
+/** Builds the radius array for a shape, ready to be interpolated. */
+export function shapeRadii(shape: ShapeSpec, samples: number = SHAPE_SAMPLES): number[] {
+  return roundRadii(polygonRadii(shape.vertices, samples, shape.rotation), shape.roundness);
+}
+
+/**
+ * A lobed shape: a circle with `lobes` soft bumps around its edge.
+ *
+ * The scalloped members of the Expressive shape library — the 4-leaf clover,
+ * the 9-sided cookie — are not rounded polygons: their edges dip *inward*
+ * between the lobes, which averaging a polygon's radii can never produce. A
+ * cosine around the circle can. `depth` is how far each dip reaches toward the
+ * centre, as a fraction of the radius; the lobes still touch the unit circle.
+ */
+export function lobedRadii(
+  lobes: number,
+  depth: number,
+  samples: number = SHAPE_SAMPLES,
+  rotation = 0,
+): number[] {
+  const radii: number[] = [];
+  for (let index = 0; index < samples; index += 1) {
+    const theta = (index / samples) * Math.PI * 2 + rotation;
+    radii.push(1 - depth * (0.5 - 0.5 * Math.cos(lobes * theta)));
+  }
+  return radii;
+}
+
+/**
+ * Blends two sampled shapes. `t` runs 0 (all `from`) to 1 (all `to`).
+ *
+ * Runs on the UI thread once per frame, which is why it takes prebuilt arrays
+ * rather than `ShapeSpec`s — sampling is done once at module load.
+ */
+export function blendRadii(from: number[], to: number[], t: number): number[] {
+  'worklet';
+  const blended: number[] = [];
+  for (let index = 0; index < from.length; index += 1) {
+    const a = from[index]!;
+    const b = to[index] ?? a;
+    blended.push(a + (b - a) * t);
+  }
+  return blended;
+}
+
+/**
+ * Turns a radius array into a closed SVG path.
+ *
+ * The points are joined with a Catmull-Rom spline converted to cubic Béziers,
+ * so the outline stays smooth as the radii move under it. Drawing straight
+ * segments instead would make a morph visibly snap between sample points.
+ */
+export function radiiToPath(radii: number[], center: number, scale: number): string {
+  'worklet';
+  const count = radii.length;
+  const points: { x: number; y: number }[] = [];
+
+  for (let index = 0; index < count; index += 1) {
+    const theta = (index / count) * Math.PI * 2;
+    const radius = radii[index]! * scale;
+    points.push({ x: center + Math.cos(theta) * radius, y: center + Math.sin(theta) * radius });
+  }
+
+  let path = `M${points[0]!.x.toFixed(2)} ${points[0]!.y.toFixed(2)}`;
+
+  for (let index = 0; index < count; index += 1) {
+    const previous = points[(index - 1 + count) % count]!;
+    const current = points[index]!;
+    const next = points[(index + 1) % count]!;
+    const after = points[(index + 2) % count]!;
+
+    // Catmull-Rom → Bézier: the control points are a sixth of the way along
+    // the chord through each endpoint's neighbours.
+    const c1x = current.x + (next.x - previous.x) / 6;
+    const c1y = current.y + (next.y - previous.y) / 6;
+    const c2x = next.x - (after.x - current.x) / 6;
+    const c2y = next.y - (after.y - current.y) / 6;
+
+    path += `C${c1x.toFixed(2)} ${c1y.toFixed(2)} ${c2x.toFixed(2)} ${c2y.toFixed(2)} ${next.x.toFixed(2)} ${next.y.toFixed(2)}`;
+  }
+
+  return `${path}Z`;
+}
+
+/**
+ * The Expressive wavy progress track.
+ *
+ * The active half of an Expressive progress indicator is a sine wave rather
+ * than a bar: the wave is what distinguishes "working" from "a coloured
+ * rectangle" at a glance, and its amplitude can fall to zero to signal that
+ * the indicator has settled.
+ */
+export function wavePath(
+  width: number,
+  height: number,
+  amplitude: number,
+  wavelength: number,
+  phase: number,
+): string {
+  'worklet';
+  const middle = height / 2;
+  if (width <= 0) return `M0 ${middle}`;
+
+  // A sample every 2dp keeps the curve smooth without emitting a path so long
+  // it costs more to parse than to draw.
+  const steps = Math.max(2, Math.ceil(width / 2));
+  let path = '';
+
+  for (let index = 0; index <= steps; index += 1) {
+    const x = (index / steps) * width;
+    const y = middle + Math.sin((x / wavelength) * Math.PI * 2 + phase) * amplitude;
+    path += `${index === 0 ? 'M' : 'L'}${x.toFixed(2)} ${y.toFixed(2)}`;
+  }
+
+  return path;
+}

package/src/sheet-physics.ts

@@ -0,0 +1,73 @@
+/**
+ * The arithmetic of a bottom sheet under a finger, kept apart from the views
+ * so it can be tested under `node --test`. Every function is a worklet: the
+ * pull runs on the UI thread.
+ */
+
+/** A pull past this share of the panel's height closes it on release. */
+export const CLOSE_SHARE = 0.3;
+/** A flick down faster than this (points a second) closes it however short. */
+export const CLOSE_VELOCITY = 900;
+/** How far a pull up can lift the panel, at most: it gives, but not much. */
+export const LIFT_LIMIT = 24;
+
+/** Whether letting go `pull` points below the rest, moving at `velocity`, closes the sheet. */
+export function releaseCloses(pull: number, velocity: number, height: number): boolean {
+  'worklet';
+  if (pull <= 0) return false;
+  return pull > height * CLOSE_SHARE || velocity > CLOSE_VELOCITY;
+}
+
+/**
+ * How far the panel rises for a finger `pull` points up: it follows at first
+ * and gives less the further it goes, never more than `limit`. A panel that
+ * does not move at all under an upward pull feels stuck rather than anchored.
+ */
+export function rubberBand(pull: number, limit?: number): number {
+  'worklet';
+  // Not a default parameter: a worklet unpacks the constants it captured at the
+  // top of its body, after the defaults have run, so `limit = LIFT_LIMIT` looks
+  // for a global that does not exist on the UI thread and the pull crashes.
+  const most = limit ?? LIFT_LIMIT;
+  if (pull <= 0) return 0;
+  return most * (1 - 1 / ((pull * 0.55) / most + 1));
+}
+
+/**
+ * How dark the scrim is, 0–1, with the panel `offset` points below its rest:
+ * full while it rests (or is lifted), clear once it is all the way down. The
+ * scrim follows the panel rather than a clock of its own, so the two arrive
+ * and leave together and a pull lightens it as it goes.
+ */
+export function scrimShare(offset: number, height: number): number {
+  'worklet';
+  if (height <= 0) return 0;
+  return Math.min(1, Math.max(0, 1 - offset / height));
+}
+
+/** Where a scrolling list inside a sheet is, as the sheet's pull needs to know it. */
+export interface SheetScroll {
+  /** How far it is scrolled from its top. */
+  y: number;
+  /** Whether its content is taller than it is, so that it scrolls at all. */
+  scrollable: boolean;
+}
+
+/** Whether every list in the sheet is at its top, so a pull down moves the sheet. */
+export function listsAtTop(scrolls: Record<string, SheetScroll>): boolean {
+  'worklet';
+  for (const key of Object.keys(scrolls)) {
+    const scroll = scrolls[key];
+    if (scroll && scroll.scrollable && scroll.y > 0.5) return false;
+  }
+  return true;
+}
+
+/** Whether a list in the sheet scrolls, so a pull up belongs to it and not to the panel. */
+export function anyScrollable(scrolls: Record<string, SheetScroll>): boolean {
+  'worklet';
+  for (const key of Object.keys(scrolls)) {
+    if (scrolls[key]?.scrollable) return true;
+  }
+  return false;
+}