@sigx/lynx-safe-area 0.1.0

package/src/index.ts

@@ -0,0 +1,30 @@
+// Public API for @sigx/lynx-safe-area.
+
+export { SafeAreaProvider, SAFE_AREA_EVENT } from './provider.js';
+export type { SafeAreaProviderProps } from './provider.js';
+
+export { SafeAreaView } from './safe-area-view.js';
+export type { SafeAreaViewProps } from './safe-area-view.js';
+
+export {
+  useSafeAreaInsets,
+  useSafeAreaSharedValues,
+  useSafeAreaFrame,
+  useSafeAreaInsetsMT,
+} from './hooks.js';
+
+export { useSafeAreaContext } from './injectable.js';
+
+export {
+  readGlobalSafeArea,
+  GLOBAL_PROPS_KEY,
+} from './globals.js';
+export type { RawSafeAreaProps } from './globals.js';
+
+export { ZERO_INSETS } from './types.js';
+export type {
+  EdgeInsets,
+  Edge,
+  SafeAreaMode,
+  SafeAreaContextValue,
+} from './types.js';

package/src/injectable.ts

@@ -0,0 +1,17 @@
+import { defineInjectable } from '@sigx/lynx';
+import type { SafeAreaContextValue } from './types.js';
+
+/**
+ * The DI handle for the safe-area context.
+ *
+ * - Inside `<SafeAreaProvider>`'s setup we call `defineProvide(useSafeAreaContext, factory)`
+ *   to install a per-app instance.
+ * - Anywhere downstream `useSafeAreaContext()` returns that instance, or
+ *   `null` if no provider is in scope. Hooks defined in `./hooks.ts` wrap
+ *   this with the null-check + signal subscription.
+ *
+ * The factory returns `null` at the global-singleton level so consumers
+ * outside a `<SafeAreaProvider>` get a clear signal (vs. a phantom zero-
+ * insets context that silently does nothing).
+ */
+export const useSafeAreaContext = defineInjectable<SafeAreaContextValue | null>(() => null);

package/src/provider.tsx

@@ -0,0 +1,209 @@
+import {
+  component,
+  defineProvide,
+  computed,
+  signal,
+  onMounted,
+  onUnmounted,
+  useSharedValue,
+  useMainThreadRef,
+  runOnMainThread,
+  type Define,
+  type MainThread,
+  type SharedValue,
+} from '@sigx/lynx';
+import { useSafeAreaContext } from './injectable.js';
+import { readGlobalSafeArea } from './globals.js';
+import type { EdgeInsets, SafeAreaContextValue } from './types.js';
+
+/**
+ * The native publisher (iOS `SafeAreaPublisher.swift`, Android
+ * `SafeAreaPublisher.kt`) emits this event via `GlobalEventEmitter` every
+ * time it republishes insets. Payload mirrors the same `RawSafeAreaProps`
+ * shape stored under `lynx.__globalProps[GLOBAL_PROPS_KEY]`.
+ *
+ * We use a custom event rather than upstream's `onGlobalPropsChanged` so
+ * the contract stays in our hands (upstream's event-name conventions have
+ * churned across Lynx releases).
+ */
+export const SAFE_AREA_EVENT = 'safeAreaChanged';
+
+interface GlobalEventEmitterLike {
+  addListener: (name: string, fn: (...a: unknown[]) => void) => void;
+  removeListener: (name: string, fn: (...a: unknown[]) => void) => void;
+}
+
+interface LynxLike {
+  getJSModule?: (name: string) => GlobalEventEmitterLike | undefined;
+}
+
+// Closure-injected identifier provided by
+// `@lynx-js/runtime-wrapper-webpack-plugin`. Same pattern as
+// `runtime-lynx/src/shims.d.ts`. Declared locally so this package doesn't
+// have to depend on runtime-lynx-internal just for the ambient.
+declare const lynx: unknown | undefined;
+
+export type SafeAreaProviderProps =
+  & Define.Prop<'class', string, false>
+  & Define.Prop<'style', Record<string, string | number>, false>
+  & Define.Slot<'default'>;
+
+/**
+ * Mount once at the root of an app. Responsibilities:
+ *
+ * 1. **Seed insets synchronously** from `lynx.__globalProps[safeArea]`. The
+ *    native side populates this *before* the MT bundle evaluates, so the
+ *    seed is correct on first render — no flash of unsafe content.
+ *
+ * 2. **Provide a DI context** (`useSafeAreaContext`) holding:
+ *    - four per-edge `SharedValue<number>`s — the single source of truth,
+ *      writable on MT, observable from both threads.
+ *    - a derived BG `computed<EdgeInsets>` for re-render-driven consumers
+ *      (`useSafeAreaInsets()`).
+ *
+ * 3. **Subscribe to live updates** via `GlobalEventEmitter`. The native
+ *    publisher emits `'safeAreaChanged'` after each `updateGlobalProps`,
+ *    carrying the new inset map. We dispatch a `runOnMainThread` worklet
+ *    that writes the per-edge SVs on MT — the SharedValue diff/publish
+ *    bridge then propagates the new values back to the BG signal mirror,
+ *    which re-fires the `computed` and re-renders consumers.
+ *
+ * 4. **Apply CSS variables** (`--sat`, `--sar`, `--sab`, `--sal`,
+ *    `--safe-area-keyboard`) on the root `<view>` so utility-class
+ *    consumers can write `class="pt-[var(--sat)]"` and have it work
+ *    uniformly across iOS and Android (upstream's
+ *    `env(safe-area-inset-*)` is iOS-only).
+ */
+export const SafeAreaProvider = component<SafeAreaProviderProps>(({ props, slots }) => {
+  const initial = readGlobalSafeArea();
+
+  const svTop = useSharedValue(initial.top);
+  const svRight = useSharedValue(initial.right);
+  const svBottom = useSharedValue(initial.bottom);
+  const svLeft = useSharedValue(initial.left);
+
+  // Reactive object signal for the non-SV extras (BG-only — keyboard,
+  // statusBar, navigationBar don't drive MT-bound layout, so SV plumbing
+  // isn't worth the cost). `signal({...})` returns a deeply reactive proxy;
+  // access via `extras.keyboard` etc., replace via `extras.$set({...})`.
+  const extras = signal<Extras>({
+    keyboard: initial.keyboard,
+    statusBar: initial.statusBar,
+    navigationBar: initial.navigationBar,
+  });
+
+  // Single source of truth for BG consumers — derived reactively from the
+  // four edge SVs (which live on MT) and the extras signal (which lives on
+  // BG). Re-runs when MT publishes new SV values via the AvBridge OR when
+  // the safeAreaChanged listener writes to `extras`.
+  const insets = computed<EdgeInsets>(() => ({
+    top: svTop.value,
+    right: svRight.value,
+    bottom: svBottom.value,
+    left: svLeft.value,
+    keyboard: extras.keyboard,
+    statusBar: extras.statusBar,
+    navigationBar: extras.navigationBar,
+  }));
+
+  const ctx: SafeAreaContextValue = {
+    insets,
+    sv: { top: svTop, right: svRight, bottom: svBottom, left: svLeft },
+  };
+  defineProvide(useSafeAreaContext, () => ctx);
+
+  // Worklet that writes the four per-edge SVs on MT. Captured by `_c` at
+  // build time — runOnMainThread ships the SV refs as `{_wvid, _initValue}`
+  // placeholders that the MT runtime resolves to the live envelope.
+  const writeOnMT = runOnMainThread((t: number, r: number, b: number, l: number) => {
+    'main thread';
+    svTop.current.value = t;
+    svRight.current.value = r;
+    svBottom.current.value = b;
+    svLeft.current.value = l;
+  });
+
+  // Hold the elRef purely so consumers can extend the provider's host view
+  // via the published CSS variables. Not used internally for any MT writes.
+  const elRef = useMainThreadRef<MainThread.Element | null>(null);
+
+  let listener: ((...a: unknown[]) => void) | undefined;
+  let emitter: GlobalEventEmitterLike | undefined;
+
+  onMounted(() => {
+    // `lynx` is a closure-injected identifier (provided by
+    // `@lynx-js/runtime-wrapper-webpack-plugin`'s `__init_card_bundle__`
+    // wrapper), NOT a property of `globalThis`. Access as a bare identifier
+    // with `typeof` guard — same pattern as `runtime-lynx/src/bg-bridge.ts`.
+    const lynxObj: LynxLike | undefined = typeof lynx !== 'undefined'
+      ? (lynx as unknown as LynxLike)
+      : undefined;
+    emitter = lynxObj?.getJSModule?.('GlobalEventEmitter');
+    if (!emitter) return;
+    listener = (raw: unknown) => {
+      const next = normaliseInsets(raw, insets.value);
+      extras.$set({
+        keyboard: next.keyboard,
+        statusBar: next.statusBar,
+        navigationBar: next.navigationBar,
+      });
+      void writeOnMT(next.top, next.right, next.bottom, next.left);
+    };
+    emitter.addListener(SAFE_AREA_EVENT, listener);
+  });
+
+  onUnmounted(() => {
+    if (emitter && listener) emitter.removeListener(SAFE_AREA_EVENT, listener);
+  });
+
+  return () => (
+    <view
+      class={props.class}
+      main-thread:ref={elRef}
+      style={cssVarStyle(insets.value, props.style)}
+    >
+      {slots.default?.()}
+    </view>
+  );
+});
+
+interface Extras {
+  keyboard: number;
+  statusBar: number;
+  navigationBar: number;
+}
+
+function normaliseInsets(raw: unknown, fallback: EdgeInsets): EdgeInsets {
+  if (!raw || typeof raw !== 'object') return fallback;
+  const o = raw as Record<string, unknown>;
+  return {
+    top: numOr(o['top'], fallback.top),
+    right: numOr(o['right'], fallback.right),
+    bottom: numOr(o['bottom'], fallback.bottom),
+    left: numOr(o['left'], fallback.left),
+    keyboard: numOr(o['keyboard'], fallback.keyboard),
+    statusBar: numOr(o['statusBar'], fallback.statusBar),
+    navigationBar: numOr(o['navigationBar'], fallback.navigationBar),
+  };
+}
+
+function numOr(v: unknown, fallback: number): number {
+  return typeof v === 'number' && Number.isFinite(v) ? v : fallback;
+}
+
+function cssVarStyle(
+  i: EdgeInsets,
+  user: Record<string, string | number> | undefined,
+): Record<string, string | number> {
+  const base: Record<string, string | number> = {
+    '--sat': `${i.top}px`,
+    '--sar': `${i.right}px`,
+    '--sab': `${i.bottom}px`,
+    '--sal': `${i.left}px`,
+    '--safe-area-keyboard': `${i.keyboard}px`,
+  };
+  return user ? { ...base, ...user } : base;
+}
+
+// re-export so users only need `@sigx/lynx-safe-area`
+export type { SharedValue };

package/src/safe-area-view.tsx

@@ -0,0 +1,73 @@
+import { component, type Define } from '@sigx/lynx';
+import { useSafeAreaInsets } from './hooks.js';
+import type { Edge, SafeAreaMode } from './types.js';
+
+export type SafeAreaViewProps =
+  & Define.Prop<'edges', Edge[], false>
+  & Define.Prop<'mode', SafeAreaMode, false>
+  & Define.Prop<'class', string, false>
+  & Define.Prop<'style', Record<string, string | number>, false>
+  & Define.Slot<'default'>;
+
+const ALL_EDGES: Edge[] = ['top', 'right', 'bottom', 'left'];
+
+/**
+ * Drop-in container that applies the current safe-area insets as padding
+ * (default) or margin on the configured edges.
+ *
+ * Implementation: BG signal + inline style. Sigx auto-tracks `insets.value`
+ * access in the render function, so the inset values land in the FIRST
+ * layout pass and re-apply reactively on every `safeAreaChanged` event.
+ *
+ * The previous implementation used `useAnimatedStyle` to drive padding via
+ * the MT bridge — but `setStyleProperties` writes that affect layout fire
+ * AFTER the first layout pass, and child elements that have already laid
+ * out (notably `<scroll-view>`, which captures its frame eagerly) don't
+ * reflow. Inline style avoids that timing trap entirely.
+ *
+ * `edges` defaults to all four sides. Pass a subset (e.g. `['top']`) to
+ * leave the unspecified sides unaffected.
+ *
+ * Must be a descendant of `<SafeAreaProvider>`. If no provider is in scope
+ * (test/storybook), `useSafeAreaInsets()` returns `ZERO_INSETS` with a
+ * dev-mode warning and SafeAreaView passes through unchanged.
+ *
+ * @example
+ * ```tsx
+ * <SafeAreaProvider>
+ *   <SafeAreaView edges={['top', 'bottom']} class="bg-base-100 flex-1">
+ *     <PageContent />
+ *   </SafeAreaView>
+ * </SafeAreaProvider>
+ * ```
+ */
+export const SafeAreaView = component<SafeAreaViewProps>(({ props, slots }) => {
+  const insets = useSafeAreaInsets();
+  const edges = props.edges ?? ALL_EDGES;
+  const mode = props.mode ?? 'padding';
+
+  return () => {
+    const i = insets.value;
+    const insetStyle: Record<string, string | number> = {};
+    if (edges.includes('top')) {
+      insetStyle[mode === 'padding' ? 'paddingTop' : 'marginTop'] = `${i.top}px`;
+    }
+    if (edges.includes('right')) {
+      insetStyle[mode === 'padding' ? 'paddingRight' : 'marginRight'] = `${i.right}px`;
+    }
+    if (edges.includes('bottom')) {
+      insetStyle[mode === 'padding' ? 'paddingBottom' : 'marginBottom'] = `${i.bottom}px`;
+    }
+    if (edges.includes('left')) {
+      insetStyle[mode === 'padding' ? 'paddingLeft' : 'marginLeft'] = `${i.left}px`;
+    }
+    return (
+      <view
+        class={props.class}
+        style={props.style ? { ...props.style, ...insetStyle } : insetStyle}
+      >
+        {slots.default?.()}
+      </view>
+    );
+  };
+});

package/src/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Per-edge inset values, in dp/pt (logical pixels). Top/right/bottom/left
+ * follow CSS shorthand order. Keyboard, statusBar, navigationBar are
+ * informational extras populated when the host platform exposes them — they
+ * may be 0 if unknown.
+ */
+export interface EdgeInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+  /** IME (soft keyboard) height when visible, 0 when hidden. */
+  keyboard: number;
+  /** Status-bar height (top system bar). Often equal to `top`, but on
+   *  notched devices the safe-area top includes the notch and the status
+   *  bar is the smaller status-only inset. */
+  statusBar: number;
+  /** Navigation-bar height (Android gesture/3-button nav at bottom). */
+  navigationBar: number;
+}
+
+/**
+ * The four standard CSS edges. Subset to control which sides
+ * `<SafeAreaView>` applies inset padding/margin to.
+ */
+export type Edge = 'top' | 'right' | 'bottom' | 'left';
+
+/** Whether `<SafeAreaView>` applies its insets as `padding` or `margin`. */
+export type SafeAreaMode = 'padding' | 'margin';
+
+/**
+ * The injectable shape exposed by `<SafeAreaProvider>`. Components that need
+ * insets reactively read `insets.value` (BG signal) or, for MT-driven
+ * layouts, subscribe to per-edge `SharedValue`s.
+ */
+export interface SafeAreaContextValue {
+  /** BG-side reactive insets. Re-renders the consumer on change. */
+  readonly insets: import('@sigx/reactivity').PrimitiveSignal<EdgeInsets>;
+  /** Per-edge SharedValues for MT-driven `useAnimatedStyle` bindings. */
+  readonly sv: {
+    top: import('@sigx/lynx').SharedValue<number>;
+    right: import('@sigx/lynx').SharedValue<number>;
+    bottom: import('@sigx/lynx').SharedValue<number>;
+    left: import('@sigx/lynx').SharedValue<number>;
+  };
+}
+
+export const ZERO_INSETS: EdgeInsets = {
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0,
+  keyboard: 0,
+  statusBar: 0,
+  navigationBar: 0,
+};