@sigx/lynx-zero 0.4.9

package/src/components/SwiperIndicator.tsx

@@ -0,0 +1,519 @@
+import {
+  component,
+  effect,
+  runOnMainThread,
+  signal,
+  useSharedValue,
+  type Define,
+  type PrimitiveSignal,
+  type SharedValue,
+} from '@sigx/lynx';
+import {
+  useSwiperDotProgress,
+  useSwiperDotScale,
+  useSwiperDotGrowX,
+  useSwiperDotTranslate,
+} from '@sigx/lynx-gestures';
+import { withTiming } from '@sigx/lynx-motion';
+import { resolveColorToken, type ColorToken } from '../contract.js';
+
+/**
+ * Visual style for the swiper page indicator.
+ *
+ * - `dots` — equally-spaced circles, the active one fades in via opacity.
+ *   Today's default. Cheap (opacity-only MT mapper, no layout each frame).
+ * - `bar` — fixed track with a single sliding thumb. Single MT binding
+ *   regardless of page count, so cheapest for very long carousels.
+ * - `pill` — the active dot stretches horizontally into a pill while
+ *   neighbours stay circular. Uses `scaleX` so siblings don't reflow.
+ * - `numbered` — text counter like `2 / 5`. Pure BG-thread, no animation.
+ * - `scale-pulse` — circles where the active one scales up. No colour
+ *   crossfade — pairs well with monochrome palettes.
+ */
+export type SwiperIndicatorVariant =
+  | 'dots'
+  | 'bar'
+  | 'pill'
+  | 'numbered'
+  | 'scale-pulse';
+
+export type SwiperIndicatorSize = 'xs' | 'sm' | 'md' | 'lg';
+
+interface SizeSpec {
+  /** Dot diameter in px. */
+  dot: number;
+  /** Gap between dots in px. */
+  gap: number;
+  /** Bar track height in px. */
+  barHeight: number;
+  /** Numbered variant font size in px. */
+  fontSize: number;
+}
+
+const SIZE_TABLE: Record<SwiperIndicatorSize, SizeSpec> = {
+  xs: { dot: 4, gap: 4, barHeight: 3, fontSize: 11 },
+  sm: { dot: 6, gap: 6, barHeight: 4, fontSize: 12 },
+  md: { dot: 8, gap: 8, barHeight: 5, fontSize: 14 },
+  lg: { dot: 12, gap: 10, barHeight: 6, fontSize: 16 },
+};
+
+export type SwiperIndicatorProps =
+  & Define.Prop<'variant', SwiperIndicatorVariant, false>
+  /**
+   * Live MT pixel offset from the parent `<Swiper>` — full scroll-linked
+   * fidelity for the animated variants. When omitted but `index` is wired,
+   * the indicator derives one internally (#211): it glides between page
+   * positions with a timing curve on every index change. Mode is fixed at
+   * mount.
+   */
+  & Define.Prop<'offset', SharedValue<number>, false>
+  /** Page width in CSS px. Must match the Swiper's effective page width. */
+  & Define.Prop<'pageWidth', number, false>
+  /** Total page count. */
+  & Define.Prop<'count', number, true>
+  /**
+   * Current page (whole-units). Required for `numbered`, drives the
+   * derived offset in index-only mode, and consumed by all variants for
+   * tap-to-jump.
+   */
+  & Define.Prop<'index', PrimitiveSignal<number>, false>
+  & Define.Prop<'color', ColorToken, false>
+  & Define.Prop<'inactiveColor', ColorToken, false>
+  & Define.Prop<'size', SwiperIndicatorSize, false>
+  /**
+   * Tap-to-jump handler. The receiver should typically write
+   * `index.value = i` to glide the swiper to that page.
+   */
+  & Define.Prop<'onDotPress', (index: number) => void, false>
+  & Define.Prop<'class', string, false>
+  & Define.Prop<'style', Record<string, string | number>, false>;
+
+/**
+ * Themed swiper page indicator with five preset variants. Each variant
+ * is a thin shell over a headless hook from `@sigx/lynx-gestures` (see
+ * `useSwiperDotProgress`, `useSwiperDotScale`, `useSwiperDotGrowX`,
+ * `useSwiperDotTranslate`). For a fully custom indicator, compose the
+ * hooks yourself rather than forking this file.
+ *
+ * @example Scroll-linked (full fidelity, wired to a `<Swiper>`)
+ * ```tsx
+ * const offset = useSharedValue(0);
+ * const idx = signal({ value: 0 });
+ * <Swiper offset={offset} index={idx} width={W}>…</Swiper>
+ * <SwiperIndicator
+ *   variant="pill"
+ *   offset={offset}
+ *   pageWidth={W}
+ *   count={photos.length}
+ *   index={idx}
+ *   color="primary"
+ *   onDotPress={(i) => { idx.value = i; }}
+ * />
+ * ```
+ *
+ * @example Index-only (no Swiper — the offset is derived internally)
+ * ```tsx
+ * const idx = signal({ value: 0 });
+ * <SwiperIndicator
+ *   variant="dots"
+ *   count={5}
+ *   index={idx}
+ *   onDotPress={(i) => { idx.value = i; }}
+ * />
+ * ```
+ */
+/**
+ * Nominal page width for the internally-derived offset (index-only mode).
+ * The animated variants consume `offset` and `pageWidth` only as the ratio
+ * `offset / pageWidth`, so any non-zero constant works.
+ */
+const SYNTHETIC_PAGE_WIDTH = 100;
+
+/** Timing used when gliding the derived offset between page positions. */
+const SYNTHETIC_GLIDE_SECONDS = 0.28;
+
+export const SwiperIndicator = component<SwiperIndicatorProps>(({ props }) => {
+  // Index-only mode (#211), fixed at mount: with no live `offset` wired but
+  // an `index`, own a SharedValue and glide it to `index × nominal width`
+  // with a timing curve whenever the index changes — the same push a real
+  // `<Swiper>` makes, minus the scroll-linked in-between frames.
+  const indexOnly = props.offset == null && props.index != null;
+  const derivedOffset = useSharedValue(
+    indexOnly ? (props.index!.value | 0) * SYNTHETIC_PAGE_WIDTH : 0,
+  );
+  if (indexOnly) {
+    // Hoisted once — wrapping per call would allocate a new MT runner on
+    // every index change.
+    const glideTo = runOnMainThread((to: number) => {
+      'main thread';
+      withTiming(derivedOffset, to, { duration: SYNTHETIC_GLIDE_SECONDS });
+    });
+    effect(() => {
+      glideTo((props.index!.value | 0) * SYNTHETIC_PAGE_WIDTH);
+    });
+  }
+
+  return () => {
+    const variant: SwiperIndicatorVariant = props.variant ?? 'dots';
+    const size = SIZE_TABLE[props.size ?? 'md'];
+    const activeColor = resolveColorToken(props.color ?? 'primary');
+    const inactiveColor = resolveColorToken(props.inactiveColor ?? 'base-content');
+    const offset = indexOnly ? derivedOffset : props.offset;
+    const pageWidth = indexOnly ? SYNTHETIC_PAGE_WIDTH : props.pageWidth;
+
+    if (variant === 'numbered') {
+      return (
+        <NumberedIndicator
+          count={props.count}
+          index={props.index ?? FALLBACK_INDEX}
+          color={activeColor}
+          fontSize={size.fontSize}
+          class={props.class}
+          style={props.style}
+        />
+      );
+    }
+
+    if (variant === 'bar') {
+      if (offset == null || pageWidth == null) return null;
+      return (
+        <BarIndicator
+          offset={offset}
+          pageWidth={pageWidth}
+          count={props.count}
+          activeColor={activeColor}
+          inactiveColor={inactiveColor}
+          barHeight={size.barHeight}
+          dotSize={size.dot}
+          gap={size.gap}
+          onDotPress={props.onDotPress}
+          class={props.class}
+          style={props.style}
+        />
+      );
+    }
+
+    if (offset == null || pageWidth == null) return null;
+    return (
+      <view
+        class={props.class}
+        style={{
+          display: 'flex',
+          flexDirection: 'row',
+          alignItems: 'center',
+          justifyContent: 'center',
+          gap: size.gap + 'px',
+          ...props.style,
+        }}
+      >
+        {Array.from({ length: props.count }, (_, i) => (
+          <Dot
+            key={i}
+            index={i}
+            offset={offset}
+            pageWidth={pageWidth}
+            variant={variant}
+            size={size}
+            activeColor={activeColor}
+            inactiveColor={inactiveColor}
+            onPress={props.onDotPress}
+          />
+        ))}
+      </view>
+    );
+  };
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Per-variant pieces. Each owns a single `useAnimatedStyle` call-site
+// (per-iteration call inside `.map()` is fine — call-sites are stable).
+
+const FALLBACK_INDEX: PrimitiveSignal<number> = signal({ value: 0 });
+
+type DotProps =
+  & Define.Prop<'index', number, true>
+  & Define.Prop<'offset', SharedValue<number>, true>
+  & Define.Prop<'pageWidth', number, true>
+  & Define.Prop<'variant', Exclude<SwiperIndicatorVariant, 'numbered' | 'bar'>, true>
+  & Define.Prop<'size', SizeSpec, true>
+  & Define.Prop<'activeColor', string, true>
+  & Define.Prop<'inactiveColor', string, true>
+  & Define.Prop<'onPress', (index: number) => void, false>;
+
+type ResolvedDotProps = {
+  index: number;
+  offset: SharedValue<number>;
+  pageWidth: number;
+  variant: Exclude<SwiperIndicatorVariant, 'numbered' | 'bar'>;
+  size: SizeSpec;
+  activeColor: string;
+  inactiveColor: string;
+  onPress?: (index: number) => void;
+};
+
+const Dot = component<DotProps>(({ props }) => {
+  // Each branch picks a different headless hook. Variants that need
+  // *two* simultaneous channels (opacity AND scale, or scale AND scaleX)
+  // need two refs — one per element — because `useAnimatedStyle` is
+  // one-binding-per-element.
+  if (props.variant === 'dots') {
+    return DotsBody(props);
+  }
+  if (props.variant === 'pill') {
+    return PillBody(props);
+  }
+  // scale-pulse
+  return ScalePulseBody(props);
+});
+
+function DotsBody(props: ResolvedDotProps) {
+  const overlayRef = useSwiperDotProgress({
+    offset: props.offset,
+    pageWidth: props.pageWidth,
+    index: props.index,
+  });
+  return () => (
+    <view
+      catchtap={props.onPress ? () => props.onPress?.(props.index) : undefined}
+      style={{
+        width: props.size.dot + 'px',
+        height: props.size.dot + 'px',
+        borderRadius: (props.size.dot / 2) + 'px',
+        backgroundColor: withAlpha(props.inactiveColor, 0.4),
+        position: 'relative',
+        overflow: 'hidden',
+      }}
+    >
+      <view
+        main-thread:ref={overlayRef}
+        style={{
+          position: 'absolute',
+          left: '0',
+          top: '0',
+          right: '0',
+          bottom: '0',
+          backgroundColor: props.activeColor,
+          opacity: '0',
+        }}
+      />
+    </view>
+  );
+}
+
+function PillBody(props: ResolvedDotProps) {
+  // Pill stretches horizontally via scaleX (no layout cost) and brightens
+  // via opacity on the active-colour overlay. Both channels target the
+  // same dot — but each needs its own bound element, so we wrap the
+  // overlay inside a scaling shell.
+  const shellRef = useSwiperDotGrowX({
+    offset: props.offset,
+    pageWidth: props.pageWidth,
+    index: props.index,
+    inactive: 1,
+    active: 3,
+  });
+  const overlayRef = useSwiperDotProgress({
+    offset: props.offset,
+    pageWidth: props.pageWidth,
+    index: props.index,
+  });
+  return () => (
+    <view
+      catchtap={props.onPress ? () => props.onPress?.(props.index) : undefined}
+      main-thread:ref={shellRef}
+      style={{
+        width: props.size.dot + 'px',
+        height: props.size.dot + 'px',
+        borderRadius: (props.size.dot / 2) + 'px',
+        backgroundColor: withAlpha(props.inactiveColor, 0.4),
+        position: 'relative',
+        overflow: 'hidden',
+        transformOrigin: 'center center',
+      }}
+    >
+      <view
+        main-thread:ref={overlayRef}
+        style={{
+          position: 'absolute',
+          left: '0',
+          top: '0',
+          right: '0',
+          bottom: '0',
+          backgroundColor: props.activeColor,
+          opacity: '0',
+        }}
+      />
+    </view>
+  );
+}
+
+function ScalePulseBody(props: ResolvedDotProps) {
+  // No colour crossfade — pure scale. Active dot uses `activeColor`,
+  // inactive uses `inactiveColor` at low alpha. Visual is monochrome
+  // friendly.
+  const scaleRef = useSwiperDotScale({
+    offset: props.offset,
+    pageWidth: props.pageWidth,
+    index: props.index,
+    inactive: 1,
+    active: 1.6,
+  });
+  const opacityRef = useSwiperDotProgress({
+    offset: props.offset,
+    pageWidth: props.pageWidth,
+    index: props.index,
+  });
+  return () => (
+    <view
+      catchtap={props.onPress ? () => props.onPress?.(props.index) : undefined}
+      main-thread:ref={scaleRef}
+      style={{
+        width: props.size.dot + 'px',
+        height: props.size.dot + 'px',
+        borderRadius: (props.size.dot / 2) + 'px',
+        backgroundColor: withAlpha(props.inactiveColor, 0.4),
+        position: 'relative',
+        overflow: 'hidden',
+      }}
+    >
+      <view
+        main-thread:ref={opacityRef}
+        style={{
+          position: 'absolute',
+          left: '0',
+          top: '0',
+          right: '0',
+          bottom: '0',
+          backgroundColor: props.activeColor,
+          opacity: '0',
+        }}
+      />
+    </view>
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Bar variant — one sliding thumb across a fixed track.
+
+type BarProps =
+  & Define.Prop<'offset', SharedValue<number>, true>
+  & Define.Prop<'pageWidth', number, true>
+  & Define.Prop<'count', number, true>
+  & Define.Prop<'activeColor', string, true>
+  & Define.Prop<'inactiveColor', string, true>
+  & Define.Prop<'barHeight', number, true>
+  & Define.Prop<'dotSize', number, true>
+  & Define.Prop<'gap', number, true>
+  & Define.Prop<'onDotPress', (index: number) => void, false>
+  & Define.Prop<'class', string, false>
+  & Define.Prop<'style', Record<string, string | number>, false>;
+
+const BarIndicator = component<BarProps>(({ props }) => {
+  // The thumb advances by (dot + gap) per page. We use the headless
+  // translate hook — a single MT binding regardless of page count.
+  const step = props.dotSize + props.gap;
+  const thumbRef = useSwiperDotTranslate({
+    offset: props.offset,
+    pageWidth: props.pageWidth,
+    step,
+  });
+
+  return () => {
+    const trackWidth = props.count * props.dotSize + Math.max(0, props.count - 1) * props.gap;
+    return (
+      <view
+        class={props.class}
+        style={{
+          position: 'relative',
+          width: trackWidth + 'px',
+          height: props.barHeight + 'px',
+          borderRadius: (props.barHeight / 2) + 'px',
+          backgroundColor: withAlpha(props.inactiveColor, 0.25),
+          overflow: 'visible',
+          ...props.style,
+        }}
+      >
+        {props.onDotPress
+          ? (
+            <view
+              style={{
+                position: 'absolute',
+                inset: '0',
+                display: 'flex',
+                flexDirection: 'row',
+                alignItems: 'center',
+              }}
+            >
+              {Array.from({ length: props.count }, (_, i) => (
+                <view
+                  key={i}
+                  catchtap={() => props.onDotPress?.(i)}
+                  style={{
+                    width: (props.dotSize + props.gap) + 'px',
+                    height: '100%',
+                  }}
+                />
+              ))}
+            </view>
+          )
+          : null}
+        <view
+          main-thread:ref={thumbRef}
+          style={{
+            position: 'absolute',
+            left: '0',
+            top: '0',
+            width: props.dotSize + 'px',
+            height: '100%',
+            borderRadius: (props.barHeight / 2) + 'px',
+            backgroundColor: props.activeColor,
+          }}
+        />
+      </view>
+    );
+  };
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Numbered variant — pure BG-thread.
+
+type NumberedProps =
+  & Define.Prop<'count', number, true>
+  & Define.Prop<'index', PrimitiveSignal<number>, true>
+  & Define.Prop<'color', string, true>
+  & Define.Prop<'fontSize', number, true>
+  & Define.Prop<'class', string, false>
+  & Define.Prop<'style', Record<string, string | number>, false>;
+
+const NumberedIndicator = component<NumberedProps>(({ props }) => {
+  const label = signal({ value: '' });
+  effect(() => {
+    label.value = `${(props.index.value | 0) + 1} / ${props.count}`;
+  });
+  return () => (
+    <text
+      class={props.class}
+      style={{
+        color: props.color,
+        fontSize: props.fontSize + 'px',
+        fontWeight: '600',
+        ...props.style,
+      }}
+    >
+      {label.value}
+    </text>
+  );
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Helpers
+
+/**
+ * Apply an alpha to a CSS colour value. Works for `var(--color-*)`
+ * (uses `color-mix`) and for raw rgb/hex strings (uses `color-mix`
+ * too — broadly supported on the platforms Lynx targets).
+ */
+function withAlpha(color: string, alpha: number): string {
+  const pct = Math.round(Math.max(0, Math.min(1, alpha)) * 100);
+  return `color-mix(in srgb, ${color} ${pct}%, transparent)`;
+}

package/src/contract.ts

@@ -0,0 +1,136 @@
+/**
+ * The shared design-system contract.
+ *
+ * `@sigx/lynx-zero` is the design-system-neutral foundation that DS packages
+ * (`@sigx/lynx-daisyui`, `@sigx/lynx-heroui`, …) build on. This module is the
+ * *vocabulary* they agree on — size scales, semantic colors, theme token
+ * names, and common prop shapes — so that switching an app from one design
+ * system to another is mostly an import swap, not a rewrite.
+ *
+ * Rules of the contract:
+ *
+ * - DS packages **extend** these types, they never redeclare them. A daisy
+ *   button is `color: ColorVariant` plus daisy-specific extras; its size IS
+ *   `SizeScale`. Drift fails `pnpm typecheck`.
+ * - `variant` is intentionally NOT in the contract — fill style (outline,
+ *   soft, bordered, flat, …) is design-system chrome and differs per DS.
+ * - Theme CSS custom-property NAMES are part of the contract (see below);
+ *   the *values* come from each DS's registered themes.
+ *
+ * ## Structural token-name contract
+ *
+ * Every DS theme resolves against the same custom-property names:
+ *
+ * - Colors:    `--color-<ColorToken>` (e.g. `--color-primary`, `--color-base-100`)
+ * - Roundness: `--radius-selector` | `--radius-field` | `--radius-box`
+ * - Sizing:    `--size-selector` | `--size-field`, `--size-xs` … `--size-lg`
+ * - Text ramp: `--text-xs` … `--text-3xl` (app text, font-scaled)
+ * - Controls:  `--font-xs` … `--font-lg` (control-internal labels, unscaled)
+ * - Misc:      `--disabled-opacity`
+ */
+import type { Define } from '@sigx/lynx';
+
+/** The shared component size scale. */
+export type SizeScale = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+/**
+ * Semantic color names — the shared `color` prop vocabulary. A DS maps each
+ * onto its palette (HeroUI: `danger`→`error`, `default`→`neutral`, …).
+ *
+ * Single source of truth: the `ColorVariant` union, the `-content` / `-soft`
+ * token derivations, and the runtime `COLOR_TOKENS` Set all derive from this
+ * tuple.
+ */
+export const COLOR_VARIANT_LIST = [
+  'primary', 'secondary', 'accent', 'neutral',
+  'info', 'success', 'warning', 'error',
+] as const;
+
+export type ColorVariant = typeof COLOR_VARIANT_LIST[number];
+
+/**
+ * Tokens authored by every theme: each variant + its `-content` pairing,
+ * plus the base surfaces.
+ */
+export type CoreColorToken =
+  | ColorVariant
+  | `${ColorVariant}-content`
+  | 'base-100' | 'base-200' | 'base-300' | 'base-content';
+
+/**
+ * Soft (tinted-surface) tokens — one per variant, emitted as
+ * `--color-<variant>-soft`. Lynx CSS can't alpha-compose `var()` colors, so
+ * these are *materialized in the palette*: computed at theme registration
+ * (`Theme.softMix` of the variant color mixed into `base-100`) unless the
+ * theme provides them explicitly. They are what soft/flat component fills
+ * read (`btn-soft`, hero's `flat`).
+ */
+export type SoftColorToken = `${ColorVariant}-soft`;
+
+/**
+ * The full set of semantic color tokens every *registered* theme carries,
+ * exposed as `--color-<token>` CSS custom properties. Authors write the core
+ * tokens; the registry completes the soft ones.
+ */
+export type ColorToken = CoreColorToken | SoftColorToken;
+
+const COLOR_TOKEN_LIST: readonly ColorToken[] = [
+  ...COLOR_VARIANT_LIST.flatMap((v): ColorToken[] => [v, `${v}-content`, `${v}-soft`]),
+  'base-100', 'base-200', 'base-300', 'base-content',
+];
+
+const COLOR_TOKENS: ReadonlySet<ColorToken> = new Set(COLOR_TOKEN_LIST);
+
+/**
+ * Resolve a color value to a CSS color string.
+ *
+ * - Known semantic tokens (e.g. `'base-100'`) → `var(--color-base-100)`.
+ * - Anything else (`'#ffaa00'`, `'rgb(…)'`, `'var(--my-custom)'`) passes
+ *   through unchanged.
+ */
+export function resolveColorToken(value: string): string {
+  return (COLOR_TOKENS as ReadonlySet<string>).has(value)
+    ? `var(--color-${value})`
+    : value;
+}
+
+/**
+ * Accepts a semantic color token (autocompleted) OR any raw CSS color
+ * string (`'#fff'`, `'rgb(…)'`, `'var(--foo)'`).
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type, @typescript-eslint/ban-types
+export type BackgroundValue = ColorToken | (string & {});
+
+// ---------------------------------------------------------------------------
+// Common prop fragments — DS component props intersect these instead of
+// redeclaring the conventions.
+// ---------------------------------------------------------------------------
+
+/** Arbitrary extra classes appended after the DS-computed ones. */
+export type WithClass = Define.Prop<'class', string, false>;
+
+/** Disabled: non-interactive + DS disabled styling. */
+export type WithDisabled = Define.Prop<'disabled', boolean, false>;
+
+/** Semantic color of the component (`primary`, `error`, …). */
+export type WithColor = Define.Prop<'color', ColorVariant, false>;
+
+/** Component size on the shared scale. */
+export type WithSize = Define.Prop<'size', SizeScale, false>;
+
+/** The shared press event — sigx convention is `onPress`, not `onTap`/`onClick`. */
+export type PressEvent = Define.Event<'press', void>;
+
+/**
+ * Accessibility passthrough for interactive components — mirrors the
+ * `accessibility-*` surface `@sigx/lynx-gestures`'s `Pressable` accepts on
+ * its host view (the same node that owns the gesture handler, so
+ * screen-reader activation works). DS components intersect this and forward
+ * the props verbatim.
+ */
+export type WithAccessibility =
+  & Define.Prop<'accessibility-element', boolean, false>
+  & Define.Prop<'accessibility-label', string, false>
+  & Define.Prop<'accessibility-role', string, false>
+  & Define.Prop<'accessibility-trait', string, false>
+  & Define.Prop<'accessibility-status', string, false>;