@astratra/native-ui 0.1.1 → 1.0.0

package/README.md

@@ -3,7 +3,8 @@
 Le kit d'interface mobile : **le verre liquide d'Apple sur iOS, une surface
 visible sur Android**, des boutons en verre, des cartes pâles, des barres qui se
 replient au défilement, une barre d'onglets façon Instagram, un en-tête
-repliable, et le rendu propre des réponses d'une IA.
+repliable, le rendu propre des réponses d'une IA, et les images : à leurs
+propres proportions, une place qui attend, une visionneuse plein écran.
 
 Pour React Native / Expo. Pas d'étape de build, pas de JSX : le source est du
 CommonJS écrit avec `createElement`, comme `@astratra/react`, et Metro le prend
@@ -350,6 +351,141 @@ Avec cette réserve, le défilement maximal vaut exactement la position de la
 question, que la réponse s'allonge ou raccourcisse ; elle tombe à zéro dès que la
 réponse remplit l'écran.
 
+# Les images
+
+Trois composants et leurs règles pures (`logic/picture.js`). Aucun ne construit
+d'adresse ni n'ajoute d'en-tête : la source vient de l'application, en général
+de `createPictureSources().resolve` de `@astratra/native`, **seul** à décider si
+le jeton de la personne part avec (jamais vers une autre origine).
+
+## AutoRatioImage
+
+```js
+import { Image } from 'expo-image';
+import { AutoRatioImage } from '@astratra/native-ui';
+
+h(AutoRatioImage, {
+  load: () => pictures.resolve(card.url),   // ou `source` déjà prête
+  sourceKey: card.url,
+  ImageComponent: Image,                     // Image de React Native par défaut
+  imageProps: { cachePolicy: 'disk' },
+  accessibilityLabel: title,
+  accessibilityHint: t('viewer.openHint'),
+  loadingLabel: t('picture.loading'),
+  renderError: ({ retry }) => h(GlassButton, { onPress: retry, accessibilityLabel: t('retry') }, icon),
+  onPress: () => setViewing(0)
+});
+```
+
+**Libre sur la page** : pas de cadre, coins arrondis, rien de coupé. Un carré
+(ou `initialRatio`) tant que l'image n'est pas connue, puis **ses propres
+proportions** — bornées entre 1/5 et 5 (`minRatio`, `maxRatio`) : une bande de
+1 × 10 000 ne fait pas une vue de dix mille points de haut, elle est montrée
+entière dans la boîte bornée.
+
+**Elle monte doucement** une fois là — d'un rien plus petite et transparente
+à sa place, 700 ms, sortie en douceur — au lieu d'apparaître d'un coup.
+**Réduire les animations** : d'un coup. En attendant, la place tenue porte le
+reflet d'`ImageShimmer` (`placeholder` pour en mettre une autre, `null` pour
+aucune).
+
+**Un échec n'est jamais un indicateur qui tourne pour toujours.** Une source
+qui échoue ou ne résout rien, une image qui ne se décode pas : l'emplacement
+d'erreur de l'application (`renderError({ retry })`). L'ancienne version
+laissait une promesse rejetée sans suite — la roue tournait indéfiniment.
+**Une nouvelle image repart de zéro** : l'ancienne gardait la forme et l'échec
+de la précédente quand l'adresse changeait.
+
+**Touchable** (`onPress`) : un bouton-image, désactivé tant que l'image n'est
+pas là, qui s'enfonce sur un ressort comme `GlassButton` (Réduire les
+animations : il s'assombrit seulement). Sans `onPress`, une simple image
+annoncée comme telle. Les deux événements de chargement sont lus (expo-image
+et React Native) ; `fit` devient `contentFit` ou `resizeMode` selon le
+composant.
+
+## ImageShimmer
+
+La place d'une image qu'on prépare : la forme aux proportions attendues, plate,
+sans contour, où passe une lumière douce de gauche à droite (1,6 s). Un seul
+élément pour le lecteur d'écran, une barre de progression avec les mots de
+l'application (`accessibilityLabel`), et une légende discrète facultative
+(`caption`). **Réduire les animations** : la lumière ne bouge pas. Elle
+s'arrête quand la place disparaît.
+
+### Les images en route
+
+```js
+import { reducePicturesArriving, picturesArrivingCount, PICTURES_ARRIVING_EMPTY } from '@astratra/native-ui/logic';
+
+const [arriving, dispatch] = useReducer(reducePicturesArriving, PICTURES_ARRIVING_EMPTY);
+// step 'draw' commencé   → dispatch({ type: 'started', id })
+// step terminé           → dispatch({ type: 'finished', id, ok })
+// l'image est arrivée    → dispatch({ type: 'arrived', id? })
+// fin du flux            → dispatch({ type: 'ended' })
+Array.from({ length: picturesArrivingCount(arriving) }, (_, i) => h(ImageShimmer, { key: i, … }));
+```
+
+La première version comptait les étapes « dessiner » en cours : le compte
+tombait à zéro dès la fin de l'étape, alors que l'image arrivait dans un
+événement suivant — la place disparaissait, le texte remontait, puis l'image le
+repoussait. Ici une tâche finie **garde sa place jusqu'à l'arrivée de l'image** ;
+seuls un échec ou la fin du flux la rendent. Un événement qui ne change rien
+rend **le même objet** (React ne redessine pas). `countRunningSteps(steps, tool)`
+donne l'ancien compte pour une application qui garde des étapes.
+
+## ImageViewer
+
+```js
+h(ImageViewer, {
+  pictures,                        // [{ key, title?, accessibilityLabel?, … }]
+  start: viewing,                  // null : fermée
+  onClose: () => setViewing(null),
+  resolveSource: (picture) => pictures.resolve(picture.url),
+  ImageComponent: Image,
+  labels: { close: t('close'), share: t('share'), details: t('details'),
+            counter: (n, total) => t('counter', { n, total }), zoomHint: t('zoomHint') },
+  icons: { close: xmark, share: shareIcon, details: info, detailsActive: infoFill, failed: photo, notice: check },
+  onShare: (picture) => sharePicture(picture),
+  actions: [{ key: 'save', label: t('save'), icon: download, onPress: async (p) => (await save(p), t('saved')) }],
+  onActionError: (error, key) => Alert.alert(t('failed')),
+  renderDetails: (picture) => h(Details, { picture }),
+  insets: useSafeAreaInsets(),
+  onHaptic: (kind) => haptics[kind]()
+});
+```
+
+Comme Photos : du noir autour, des commandes rondes en verre qu'un appui cache
+et remontre (la barre d'état avec, et le lecteur d'écran ne les atteint plus
+tant qu'elles sont cachées).
+
+- **Glisser de côté** passe d'une image à l'autre ; le compteur (« 3 sur 12 »,
+  les mots de l'application) suit, `onIndexChange` est appelé.
+- **Pincer ou toucher deux fois** zoome là où l'on touche, au plus ×4 ; deux
+  fois encore pour revenir. Zoomé, le doigt déplace l'image et les pages ne
+  tournent plus. Sur **iOS** le zoom est natif (ScrollView qui zoome, son rebond,
+  sa décélération). La ScrollView d'**Android** ne zoome pas — l'ancienne
+  version n'y avait tout simplement pas de pincement — : Android reçoit le sien,
+  deux doigts autour du point entre eux, un doigt pour se déplacer, et au
+  relâcher l'image revient dans ses bornes. Un toucher unique attend 260 ms
+  pour ne pas être le premier d'un double.
+- **Tirer vers le bas** ferme : le noir s'efface sur une demi-hauteur, l'image
+  rétrécit jusqu'à 80 %. Au-delà de 120 points ou assez vite, elle part ;
+  sinon elle revient sur un ressort. Deux doigts ne tirent jamais.
+- **En haut** : fermer, le compteur, les détails si l'application en donne
+  (`renderDetails`, qui remplace alors le titre). **En bas** : le titre, puis
+  partager (`onShare`) et les actions de l'application. Une action peut rendre
+  un court message (« Enregistrée ») montré un instant et annoncé au lecteur
+  d'écran ; un échec va à `onActionError` avec sa clé et l'image. Pendant
+  qu'une action tourne, les autres attendent.
+- **Réduire les animations** : pas de fondu, pas de ressort, pas de
+  rétrécissement ; la visionneuse s'ouvre et se ferme d'un coup, le zoom par
+  double toucher n'est pas animé.
+- Une **rotation** remet la liste sur la même image ; la dernière image retirée
+  ferme la visionneuse ; le retour Android et le geste d'échappement de
+  VoiceOver ferment aussi.
+
+Aucun texte, aucune icône, aucun chargement en dur : tout vient des props.
+
 ---
 
 # Tests

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astratra/native-ui",
-  "version": "0.1.1",
-  "description": "Mobile UI kit for React Native / Expo: Apple's Liquid Glass on iOS and a calibrated visible surface on Android, glass buttons, pale cards, bars that fold on scroll, an Instagram-style tab bar, a collapsible header, and a Markdown renderer for AI answers. Pure rules exported separately and tested in plain Node.",
+  "version": "1.0.0",
+  "description": "Mobile UI kit for React Native / Expo: Apple's Liquid Glass on iOS and a calibrated visible surface on Android, glass buttons, pale cards, bars that fold on scroll, an Instagram-style tab bar, a collapsible header, a Markdown renderer for AI answers, and pictures: natural-ratio images revealed gently, a shimmer placeholder, and a full-screen viewer with pinch, double-tap and pull-to-close. Pure rules exported separately and tested in plain Node.",
   "engines": {
     "node": ">=20"
   },
@@ -38,14 +38,16 @@
     "liquid-glass",
     "ui",
     "tab-bar",
-    "markdown"
+    "markdown",
+    "image",
+    "image-viewer"
   ],
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@astratra/native": "^0.2.0"
+    "@astratra/native": "^1.0.0"
   },
   "peerDependencies": {
     "expo-blur": ">=14",

package/src/components/AutoRatioImage.js

@@ -0,0 +1,237 @@
+/**
+ * A picture free on the page, in its own proportions: no frame around it, its
+ * corners rounded, nothing cut off. Until it is known it holds a place (a
+ * square by default, or the shape the app expects) where a soft light passes;
+ * once there, it takes its own shape and comes up gently — from a hair smaller
+ * and transparent — rather than all at once. "Reduce Motion": at once.
+ *
+ * The source is given ready (`source`), or fetched (`load`, with a
+ * `sourceKey` naming the picture) — typically `@astratra/native`'s
+ * `createPictureSources().resolve`, which decides whether the person's token
+ * goes with it. This component never builds an address nor adds a header.
+ *
+ * A failure — a load that rejects, a picture that does not decode — leaves the
+ * place with the app's error slot (`renderError({ retry })`); nothing spins
+ * forever.
+ *
+ * The image component is injected: React Native's Image by default, or
+ * expo-image's (`ImageComponent={Image}` with its caching props in
+ * `imageProps`). Both load events are read.
+ */
+const { React, h, RN, Reanimated, AnimatedView, useReducedMotion, useScheme } = require('./runtime');
+const { ImageShimmer } = require('./ImageShimmer');
+const { PICTURE_REVEAL, naturalRatio, loadedSize, revealStyle } = require('../logic/picture');
+const { PALE_CARD_RADIUS } = require('../logic/paleCard');
+
+const { Easing, useAnimatedStyle, useSharedValue, withSpring, withTiming } = Reanimated;
+
+/* The surface shown only while the picture is not there (loading, failed). */
+const DEFAULT_SURFACE = { light: '#eef0f5', dark: '#1c1c1e' };
+
+/* The press, like the kit's glass button: the finger sinks the picture on a
+   spring without bounce, the release brings it back with a hair of overshoot. */
+const PRESSED_SCALE = 0.98;
+const PRESS_IN = { stiffness: 600, damping: 2 * Math.sqrt(600), mass: 1 };
+const RELEASE = { stiffness: 380, damping: 20, mass: 1 };
+
+function AutoRatioImage({
+  source,
+  load,
+  sourceKey,
+  ImageComponent,
+  imageProps,
+  fit = 'contain',
+  initialRatio = 1,
+  minRatio,
+  maxRatio,
+  borderRadius = PALE_CARD_RADIUS,
+  surfaceColor,
+  placeholder,
+  loadingLabel,
+  renderError,
+  accessibilityLabel,
+  accessibilityHint,
+  onPress,
+  onLongPress,
+  onLoad,
+  onError,
+  onRatio,
+  revealMs = PICTURE_REVEAL.durationMs,
+  scheme: schemeOverride,
+  style,
+  testID
+}) {
+  const scheme = useScheme(schemeOverride);
+  const reduceMotion = useReducedMotion();
+  const Picture = ImageComponent || RN.Image;
+  const limits = { min: minRatio, max: maxRatio };
+  const startRatio = naturalRatio(null, { fallback: initialRatio, ...limits });
+  const key = sourceKey !== undefined && sourceKey !== null ? String(sourceKey) : source && source.uri ? source.uri : null;
+
+  const [resolved, setResolved] = React.useState(null);
+  const [phase, setPhase] = React.useState('resolving');
+  const [ratio, setRatio] = React.useState(startRatio);
+  const [attempt, setAttempt] = React.useState(0);
+  const shown = useSharedValue(0);
+  const press = useSharedValue(0);
+
+  /* A new picture starts over: its own place, its own reveal. The first
+     version kept the previous picture's shape and failure. */
+  const latest = React.useRef({ load, source, onError });
+  latest.current = { load, source, onError };
+  React.useEffect(() => {
+    let live = true;
+    shown.value = 0;
+    setRatio(startRatio);
+    setResolved(null);
+    const fail = (error) => {
+      if (!live) return;
+      setPhase('failed');
+      if (latest.current.onError) latest.current.onError(error);
+    };
+    if (typeof latest.current.load === 'function') {
+      setPhase('resolving');
+      Promise.resolve()
+        .then(() => latest.current.load())
+        .then((next) => {
+          if (!live) return;
+          if (next && typeof next.uri === 'string' && next.uri) {
+            setResolved(next);
+            setPhase('loading');
+          } else {
+            fail(null);
+          }
+        }, fail);
+    } else if (latest.current.source && latest.current.source.uri) {
+      setResolved(latest.current.source);
+      setPhase('loading');
+    } else {
+      setPhase('failed');
+    }
+    return () => {
+      live = false;
+    };
+    /* The picture is named by its key: a new object for the same key is the
+       same picture, and must not start the reveal over. */
+  }, [key, attempt]);
+
+  const retry = React.useCallback(() => setAttempt((count) => count + 1), []);
+
+  const handleLoad = (event) => {
+    const size = loadedSize(event);
+    if (size) {
+      const next = naturalRatio(size, { fallback: initialRatio, ...limits });
+      setRatio(next);
+      if (onRatio) onRatio(next);
+    }
+    shown.value = reduceMotion ? 1 : withTiming(1, { duration: revealMs, easing: Easing.out(Easing.cubic) });
+    setPhase('loaded');
+    if (onLoad) onLoad(size);
+  };
+
+  const handleError = (event) => {
+    setPhase('failed');
+    if (onError) onError(event && event.nativeEvent ? event.nativeEvent.error : event);
+  };
+
+  const reveal = useAnimatedStyle(() => revealStyle(shown.value));
+  const pressed = useAnimatedStyle(() => ({
+    transform: [{ scale: reduceMotion ? 1 : 1 - (1 - PRESSED_SCALE) * press.value }],
+    opacity: reduceMotion ? 1 - 0.25 * press.value : 1
+  }));
+
+  const loaded = phase === 'loaded';
+  const failed = phase === 'failed';
+  const surface = surfaceColor || DEFAULT_SURFACE[scheme];
+  const fitProps = Picture === RN.Image ? { resizeMode: fit } : { contentFit: fit };
+
+  const waiting =
+    placeholder !== undefined
+      ? placeholder
+      : h(ImageShimmer, {
+          ratio,
+          borderRadius: 0,
+          colors: { base: surface },
+          accessibilityLabel: loadingLabel,
+          scheme,
+          style: RN.StyleSheet.absoluteFill
+        });
+
+  const content = failed
+    ? h(
+        RN.View,
+        { style: [RN.StyleSheet.absoluteFill, { alignItems: 'center', justifyContent: 'center' }] },
+        typeof renderError === 'function' ? renderError({ retry }) : null
+      )
+    : [
+        loaded ? null : h(React.Fragment, { key: 'waiting' }, waiting),
+        resolved
+          ? h(
+              AnimatedView,
+              { key: `picture-${attempt}`, pointerEvents: 'none', style: [RN.StyleSheet.absoluteFill, reveal] },
+              h(Picture, {
+                ...fitProps,
+                ...(imageProps || {}),
+                source: resolved,
+                onLoad: handleLoad,
+                onError: handleError,
+                accessibilityIgnoresInvertColors: true,
+                style: { width: '100%', height: '100%' }
+              })
+            )
+          : null
+      ];
+
+  const frame = {
+    aspectRatio: ratio,
+    borderRadius,
+    overflow: 'hidden',
+    backgroundColor: loaded ? 'transparent' : surface
+  };
+
+  if (typeof onPress !== 'function' && typeof onLongPress !== 'function') {
+    return h(
+      RN.View,
+      {
+        testID,
+        /* Failed, the frame stops grouping: the app's retry button inside
+           must be reachable by the screen reader on its own. */
+        accessible: !failed,
+        accessibilityRole: 'image',
+        accessibilityLabel,
+        accessibilityState: { busy: !loaded && !failed },
+        style: [frame, style]
+      },
+      content
+    );
+  }
+
+  return h(
+    AnimatedView,
+    { style: [pressed, style] },
+    h(
+      RN.Pressable,
+      {
+        testID,
+        accessible: !failed,
+        accessibilityRole: 'imagebutton',
+        accessibilityLabel,
+        accessibilityHint,
+        accessibilityState: { disabled: !loaded, busy: !loaded && !failed },
+        disabled: !loaded,
+        onPress,
+        onLongPress,
+        onPressIn: () => {
+          press.value = withSpring(1, PRESS_IN);
+        },
+        onPressOut: () => {
+          press.value = withSpring(0, RELEASE);
+        },
+        style: frame
+      },
+      content
+    )
+  );
+}
+
+module.exports = { AutoRatioImage };

package/src/components/ImageShimmer.js

@@ -0,0 +1,91 @@
+/**
+ * The place a picture will take while it is being made or fetched: a rounded
+ * shape at the picture's proportions, where a soft light passes left to right,
+ * and an optional quiet caption beneath.
+ *
+ * The screen reader hears one element, a progress bar with the app's label
+ * ("Drawing the picture…"). "Reduce Motion": the light does not move — the
+ * shape stays, still.
+ */
+const { React, h, RN, LinearGradient, Reanimated, AnimatedView, useReducedMotion, useScheme } = require('./runtime');
+const { SHIMMER_PASS_MS, shimmerTranslate } = require('../logic/picture');
+const { PALE_CARD_RADIUS } = require('../logic/paleCard');
+
+/* Destructured once: a worklet must capture what it calls itself. */
+const { Easing, cancelAnimation, useAnimatedStyle, useSharedValue, withRepeat, withTiming } = Reanimated;
+
+/* A flat ground with no outline, and a light only a little brighter: the
+   placeholder is a presence, not a signal. The app's own theme passes its
+   colours in `colors`. */
+const DEFAULT_COLORS = {
+  light: { base: '#eef0f5', light: 'rgba(255,255,255,0.85)', caption: 'rgba(60,60,67,0.6)' },
+  dark: { base: '#1c1c1e', light: 'rgba(255,255,255,0.08)', caption: 'rgba(235,235,245,0.6)' }
+};
+
+function ImageShimmer({
+  ratio = 1,
+  borderRadius = PALE_CARD_RADIUS,
+  colors,
+  accessibilityLabel,
+  caption,
+  captionStyle,
+  passMs = SHIMMER_PASS_MS,
+  scheme: schemeOverride,
+  style,
+  testID
+}) {
+  const scheme = useScheme(schemeOverride);
+  const palette = { ...DEFAULT_COLORS[scheme], ...(colors || {}) };
+  const reduceMotion = useReducedMotion();
+  const position = useSharedValue(0);
+
+  React.useEffect(() => {
+    if (reduceMotion) {
+      cancelAnimation(position);
+      position.value = 0;
+      return undefined;
+    }
+    position.value = withRepeat(withTiming(1, { duration: passMs, easing: Easing.inOut(Easing.quad) }), -1, false);
+    return () => cancelAnimation(position);
+  }, [reduceMotion, passMs, position]);
+
+  const light = useAnimatedStyle(() => ({ transform: [{ translateX: shimmerTranslate(position.value) }] }));
+
+  return h(
+    RN.View,
+    {
+      testID,
+      accessible: true,
+      accessibilityRole: 'progressbar',
+      accessibilityLabel,
+      accessibilityState: { busy: true },
+      style: [{ gap: 8 }, style]
+    },
+    h(
+      RN.View,
+      {
+        style: {
+          aspectRatio: ratio > 0 ? ratio : 1,
+          borderRadius,
+          overflow: 'hidden',
+          backgroundColor: palette.base
+        }
+      },
+      reduceMotion
+        ? null
+        : h(
+            AnimatedView,
+            { pointerEvents: 'none', style: [RN.StyleSheet.absoluteFill, light] },
+            h(LinearGradient, {
+              colors: ['transparent', palette.light, 'transparent'],
+              start: { x: 0, y: 0.35 },
+              end: { x: 1, y: 0.65 },
+              style: RN.StyleSheet.absoluteFill
+            })
+          )
+    ),
+    caption ? h(RN.Text, { style: [{ fontSize: 13, color: palette.caption }, captionStyle] }, caption) : null
+  );
+}
+
+module.exports = { ImageShimmer };