component-previewer 0.1.0

package/src/PreviewControls.tsx

@@ -0,0 +1,128 @@
+import React from 'react';
+import { Pressable, ScrollView, StyleSheet, Switch, Text, TextInput, View } from 'react-native';
+import type { Control } from './controls';
+
+// Dependency-free controls panel (bottom sheet). Neutral chrome — the host theme
+// applies to the previewed story, not here. Each control edits one arg live.
+export function PreviewControls({
+  controls,
+  onChange,
+  onReset,
+}: {
+  controls: Control[];
+  onChange: (name: string, value: unknown) => void;
+  onReset: () => void;
+}) {
+  return (
+    <View style={styles.sheet}>
+      <View style={styles.header}>
+        <Text style={styles.title}>Props</Text>
+        <Pressable onPress={onReset} accessibilityLabel="Reset props">
+          <Text style={styles.reset}>Reset</Text>
+        </Pressable>
+      </View>
+      <ScrollView keyboardShouldPersistTaps="handled">
+        {controls.map((c) => (
+          <View key={c.name} style={styles.row}>
+            <Text style={styles.label}>{c.name}</Text>
+            <View style={styles.control}>
+              <ControlInput control={c} onChange={(v) => onChange(c.name, v)} />
+            </View>
+          </View>
+        ))}
+      </ScrollView>
+    </View>
+  );
+}
+
+function ControlInput({ control, onChange }: { control: Control; onChange: (value: unknown) => void }) {
+  switch (control.kind) {
+    case 'boolean':
+      return <Switch value={control.value} onValueChange={onChange} />;
+
+    case 'number':
+      return (
+        <TextInput
+          style={styles.input}
+          keyboardType="numeric"
+          value={String(control.value)}
+          onChangeText={(text) => {
+            const n = Number(text);
+            if (text.trim() === '' || Number.isNaN(n)) return; // ignore non-numeric input
+            let next = n;
+            if (control.min != null) next = Math.max(control.min, next);
+            if (control.max != null) next = Math.min(control.max, next);
+            onChange(next);
+          }}
+        />
+      );
+
+    case 'select':
+      return (
+        <View style={styles.options}>
+          {control.options.map((opt) => {
+            const selected = opt === control.value;
+            return (
+              <Pressable
+                key={String(opt)}
+                style={[styles.pill, selected && styles.pillSelected]}
+                onPress={() => onChange(opt)}
+              >
+                <Text style={[styles.pillText, selected && styles.pillTextSelected]}>{String(opt)}</Text>
+              </Pressable>
+            );
+          })}
+        </View>
+      );
+
+    default: // 'text'
+      return (
+        <TextInput
+          style={styles.input}
+          value={control.value}
+          autoCapitalize="none"
+          autoCorrect={false}
+          onChangeText={onChange}
+        />
+      );
+  }
+}
+
+const styles = StyleSheet.create({
+  sheet: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    bottom: 0,
+    maxHeight: '45%',
+    backgroundColor: '#1a1a1c',
+    borderTopLeftRadius: 16,
+    borderTopRightRadius: 16,
+    paddingHorizontal: 16,
+    paddingTop: 12,
+    paddingBottom: 28,
+    borderTopWidth: StyleSheet.hairlineWidth,
+    borderTopColor: '#333',
+  },
+  header: { flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center', marginBottom: 8 },
+  title: { color: '#fff', fontSize: 16, fontWeight: '700' },
+  reset: { color: '#7aa2ff', fontSize: 14, fontWeight: '600' },
+  row: { flexDirection: 'row', alignItems: 'center', paddingVertical: 8, gap: 12 },
+  label: { color: '#cbcbd2', fontSize: 14, width: 96 },
+  control: { flex: 1, alignItems: 'flex-end' },
+  input: {
+    color: '#fff',
+    backgroundColor: '#262629',
+    borderRadius: 8,
+    paddingHorizontal: 10,
+    paddingVertical: 8,
+    minWidth: 120,
+    width: '100%',
+    textAlign: 'right',
+  },
+  options: { flexDirection: 'row', flexWrap: 'wrap', justifyContent: 'flex-end', gap: 6 },
+  pill: { backgroundColor: '#262629', borderRadius: 999, paddingHorizontal: 12, paddingVertical: 6 },
+  pillSelected: { backgroundColor: '#7aa2ff' },
+  pillText: { color: '#cbcbd2', fontSize: 13, fontWeight: '600' },
+  pillTextSelected: { color: '#10131a' },
+});

package/src/PreviewList.tsx

@@ -0,0 +1,71 @@
+import React, { useMemo, useState } from 'react';
+import { FlatList, Pressable, StyleSheet, Text, TextInput, View } from 'react-native';
+import type { StoryEntry } from './types';
+
+// Neutral, dependency-free picker. The host's theme applies only to the
+// previewed story (via the shell), not this chrome.
+export function PreviewList({
+  entries,
+  onSelect,
+}: {
+  entries: StoryEntry[];
+  onSelect: (entry: StoryEntry) => void;
+}) {
+  const [query, setQuery] = useState('');
+  const filtered = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    if (!q) return entries;
+    return entries.filter((e) => `${e.title} ${e.name}`.toLowerCase().includes(q));
+  }, [entries, query]);
+
+  return (
+    <View style={styles.root}>
+      <Text style={styles.heading}>Stories ({entries.length})</Text>
+      <TextInput
+        style={styles.search}
+        placeholder="Filter…"
+        placeholderTextColor="#888"
+        autoCapitalize="none"
+        autoCorrect={false}
+        value={query}
+        onChangeText={setQuery}
+      />
+      {filtered.length === 0 ? (
+        <Text style={styles.empty}>
+          {entries.length === 0 ? 'No *.stories.tsx found.' : 'No matches.'}
+        </Text>
+      ) : (
+        <FlatList
+          data={filtered}
+          keyExtractor={(e) => e.id}
+          renderItem={({ item }) => (
+            <Pressable style={styles.row} onPress={() => onSelect(item)}>
+              <Text style={styles.rowTitle}>
+                {item.title} <Text style={styles.rowName}>/ {item.name}</Text>
+              </Text>
+              <Text style={styles.rowId}>{item.id}</Text>
+            </Pressable>
+          )}
+        />
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1, paddingTop: 64, paddingHorizontal: 16, backgroundColor: '#111' },
+  heading: { color: '#fff', fontSize: 20, fontWeight: '600', marginBottom: 12 },
+  search: {
+    color: '#fff',
+    backgroundColor: '#222',
+    borderRadius: 10,
+    paddingHorizontal: 12,
+    paddingVertical: 10,
+    marginBottom: 12,
+  },
+  empty: { color: '#888', marginTop: 24 },
+  row: { paddingVertical: 14, borderBottomWidth: StyleSheet.hairlineWidth, borderBottomColor: '#333' },
+  rowTitle: { color: '#fff', fontSize: 16 },
+  rowName: { color: '#9a9aa2' },
+  rowId: { color: '#666', fontSize: 12, marginTop: 2 },
+});

package/src/PreviewStage.tsx

@@ -0,0 +1,72 @@
+import React, { useMemo, useState } from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+import { inferControls } from './controls';
+import { PreviewControls } from './PreviewControls';
+import { composeStory, type ShellComponent } from './shell';
+import type { Args, StoryEntry } from './types';
+
+// Renders the selected story full-bleed, composed with the real shell (outer)
+// and the story's decorators (inner). The picker chrome stays outside the shell.
+// Live props controls edit `args` and re-render the story in place.
+export function PreviewStage({
+  entry,
+  shell,
+  onBack,
+}: {
+  entry: StoryEntry;
+  shell?: ShellComponent;
+  onBack: () => void;
+}) {
+  const [args, setArgs] = useState<Args>(entry.args);
+  const [controlsOpen, setControlsOpen] = useState(false);
+  const controls = useMemo(() => inferControls(args, entry.argTypes), [args, entry.argTypes]);
+
+  return (
+    <View style={styles.root}>
+      <View style={styles.content}>{composeStory(entry, shell, args)}</View>
+      <Pressable style={styles.back} onPress={onBack} accessibilityLabel="Back to stories">
+        <Text style={styles.backText}>‹ {entry.title} / {entry.name}</Text>
+      </Pressable>
+      {controls.length > 0 && (
+        <Pressable
+          style={styles.toggle}
+          onPress={() => setControlsOpen((v) => !v)}
+          accessibilityLabel="Toggle props controls"
+        >
+          <Text style={styles.backText}>{controlsOpen ? 'Controls ▾' : 'Controls ▴'}</Text>
+        </Pressable>
+      )}
+      {controlsOpen && controls.length > 0 && (
+        <PreviewControls
+          controls={controls}
+          onChange={(name, value) => setArgs((a) => ({ ...a, [name]: value }))}
+          onReset={() => setArgs(entry.args)}
+        />
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1 },
+  content: { flex: 1 },
+  back: {
+    position: 'absolute',
+    top: 56,
+    left: 12,
+    backgroundColor: 'rgba(0,0,0,0.6)',
+    borderRadius: 999,
+    paddingHorizontal: 14,
+    paddingVertical: 8,
+  },
+  toggle: {
+    position: 'absolute',
+    top: 56,
+    right: 12,
+    backgroundColor: 'rgba(0,0,0,0.6)',
+    borderRadius: 999,
+    paddingHorizontal: 14,
+    paddingVertical: 8,
+  },
+  backText: { color: '#fff', fontSize: 14, fontWeight: '600' },
+});

package/src/Previewer.tsx

@@ -0,0 +1,28 @@
+import React, { useState } from 'react';
+import { PreviewList } from './PreviewList';
+import { PreviewStage } from './PreviewStage';
+import type { ShellComponent } from './shell';
+import type { StoryEntry } from './types';
+
+// The reusable picker + stage UI. The host builds `stories` via
+// fromRequireContext/fromGlob and passes its real `shell` (AppProviders).
+// `initialStoryId` boots straight into one story (useful for deep links /
+// screenshots / "jump to the thing I'm editing").
+export function Previewer({
+  stories,
+  shell,
+  initialStoryId,
+}: {
+  stories: StoryEntry[];
+  shell?: ShellComponent;
+  initialStoryId?: string;
+}) {
+  const initial = initialStoryId ? (stories.find((s) => s.id === initialStoryId) ?? null) : null;
+  const [selected, setSelected] = useState<StoryEntry | null>(initial);
+
+  if (selected) {
+    // key by story id so live-edited arg state resets cleanly per story.
+    return <PreviewStage key={selected.id} entry={selected} shell={shell} onBack={() => setSelected(null)} />;
+  }
+  return <PreviewList entries={stories} onSelect={setSelected} />;
+}

package/src/controls.ts

@@ -0,0 +1,75 @@
+import type { Args, ArgType, ArgTypes, ControlKind } from './types';
+
+// A render-ready control descriptor. Pure data — the UI maps these to inputs.
+export type Control =
+  | { name: string; kind: 'text'; value: string }
+  | { name: string; kind: 'boolean'; value: boolean }
+  | { name: string; kind: 'number'; value: number; min?: number; max?: number; step?: number }
+  | { name: string; kind: 'select'; value: unknown; options: unknown[] };
+
+type Bounds = { min?: number; max?: number; step?: number };
+
+// Normalize an ArgType's `control` (string shorthand or { type, ... }) into a
+// kind plus any numeric bounds. Returns kind: undefined when no control given.
+function explicit(argType?: ArgType): { kind?: ControlKind } & Bounds {
+  const c = argType?.control;
+  if (!c) return {};
+  if (typeof c === 'string') {
+    return { kind: c, min: argType?.min, max: argType?.max, step: argType?.step };
+  }
+  return { kind: c.type, min: c.min ?? argType?.min, max: c.max ?? argType?.max, step: c.step ?? argType?.step };
+}
+
+function toNumber(value: unknown): number {
+  return typeof value === 'number' ? value : Number(value);
+}
+
+function toText(value: unknown): string {
+  return typeof value === 'string' ? value : value == null ? '' : String(value);
+}
+
+// Build controls for a story's editable args. Explicit `argTypes` win; otherwise
+// the kind is inferred from the runtime value type. `range` becomes a number
+// control with bounds. `select` needs `options`, else it degrades to text.
+// Non-primitive values (function/object/array/null/undefined) with no explicit
+// control are skipped — they pass through to render untouched.
+export function inferControls(args: Args, argTypes: ArgTypes = {}): Control[] {
+  const controls: Control[] = [];
+
+  for (const name of Object.keys(args)) {
+    const value = args[name];
+    const { kind, min, max, step } = explicit(argTypes[name]);
+
+    if (kind === 'select') {
+      const options = argTypes[name]?.options;
+      if (options && options.length > 0) {
+        controls.push({ name, kind: 'select', value, options });
+        continue;
+      }
+      // No options to choose from — fall back to a text control.
+      controls.push({ name, kind: 'text', value: toText(value) });
+      continue;
+    }
+
+    if (kind === 'number' || kind === 'range') {
+      controls.push({ name, kind: 'number', value: toNumber(value), min, max, step });
+      continue;
+    }
+    if (kind === 'boolean') {
+      controls.push({ name, kind: 'boolean', value: Boolean(value) });
+      continue;
+    }
+    if (kind === 'text') {
+      controls.push({ name, kind: 'text', value: toText(value) });
+      continue;
+    }
+
+    // No explicit control — infer from the value type.
+    if (typeof value === 'string') controls.push({ name, kind: 'text', value });
+    else if (typeof value === 'number') controls.push({ name, kind: 'number', value });
+    else if (typeof value === 'boolean') controls.push({ name, kind: 'boolean', value });
+    // else: skipped (function/object/array/null/undefined).
+  }
+
+  return controls;
+}

package/src/csf.ts

@@ -0,0 +1,59 @@
+import { createElement } from 'react';
+import type { Args, ArgTypes, CsfModule, Meta, Story, StoryEntry } from './types';
+
+const RESERVED = new Set(['default', '__esModule']);
+
+function slug(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function deriveTitle(meta: Meta | undefined, id: string): string {
+  if (meta?.title) return meta.title;
+  const c = meta?.component as { displayName?: string; name?: string } | undefined;
+  if (c?.displayName) return c.displayName;
+  if (c?.name) return c.name;
+  return id.replace(/^.*\//, '').replace(/\.stories\.[jt]sx?$/, '');
+}
+
+function normalizeStory(raw: unknown): Exclude<Story, (args: Args) => unknown> | null {
+  if (typeof raw === 'function') return { render: raw as (args: Args) => ReturnType<typeof createElement> };
+  if (raw && typeof raw === 'object') return raw as Exclude<Story, (args: Args) => unknown>;
+  return null;
+}
+
+// Parse one CSF module into normalized story entries. Pure: no rendering, no
+// host libraries. This is the heart of the surface-agnostic core.
+export function parseCsfModule(id: string, mod: CsfModule): StoryEntry[] {
+  const meta = mod.default;
+  const title = deriveTitle(meta, id);
+  const entries: StoryEntry[] = [];
+
+  for (const exportName of Object.keys(mod)) {
+    if (RESERVED.has(exportName)) continue;
+    const story = normalizeStory(mod[exportName]);
+    if (!story) continue;
+
+    const args: Args = { ...(meta?.args ?? {}), ...(story.args ?? {}) };
+    // argTypes merge with the same precedence as args (story wins over meta).
+    const argTypes: ArgTypes = { ...(meta?.argTypes ?? {}), ...(story.argTypes ?? {}) };
+    // Story decorators wrap innermost, meta decorators outer (Storybook order).
+    const decorators = [...(story.decorators ?? []), ...(meta?.decorators ?? [])];
+    const name = story.name ?? exportName;
+
+    const render =
+      story.render ??
+      ((a: Args) => {
+        if (!meta?.component) {
+          throw new Error(`Story "${exportName}" in ${id}: no render fn and meta has no component`);
+        }
+        return createElement(meta.component, a);
+      });
+
+    entries.push({ id: `${slug(title)}--${slug(name)}`, title, name, args, argTypes, decorators, render });
+  }
+
+  return entries;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+// Surface-agnostic core
+export { parseCsfModule } from './csf';
+export { buildRegistry, fromRequireContext, fromGlob } from './registry';
+export { composeStory } from './shell';
+export type { ShellComponent } from './shell';
+export { inferControls } from './controls';
+export type { Control } from './controls';
+export type {
+  Args,
+  ArgType,
+  ArgTypes,
+  ControlKind,
+  CsfModule,
+  Decorator,
+  GlobModules,
+  Meta,
+  RequireContext,
+  Story,
+  StoryEntry,
+} from './types';
+
+// UI (reused by backends)
+export { Previewer } from './Previewer';

package/src/registry.ts

@@ -0,0 +1,21 @@
+import { parseCsfModule } from './csf';
+import type { CsfModule, GlobModules, RequireContext, StoryEntry } from './types';
+
+// Build a sorted, flattened registry from already-loaded story modules.
+export function buildRegistry(modules: Array<{ id: string; module: CsfModule }>): StoryEntry[] {
+  return modules
+    .slice()
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .flatMap(({ id, module }) => parseCsfModule(id, module));
+}
+
+// Discovery adapter — Metro's require.context (native + web/Metro).
+export function fromRequireContext(ctx: RequireContext): StoryEntry[] {
+  return buildRegistry(ctx.keys().map((id) => ({ id, module: ctx(id) as CsfModule })));
+}
+
+// Discovery adapter — Vite's eager import.meta.glob (web/Vite backend).
+// Pass `import.meta.glob('...', { eager: true })`.
+export function fromGlob(glob: GlobModules): StoryEntry[] {
+  return buildRegistry(Object.entries(glob).map(([id, module]) => ({ id, module })));
+}

package/src/shell.tsx

@@ -0,0 +1,22 @@
+import { createElement } from 'react';
+import type { ComponentType, ReactElement } from 'react';
+import type { Args, StoryEntry } from './types';
+
+export type ShellComponent = ComponentType<{ children: ReactElement }>;
+
+// Compose the full element for a story:
+//   AppShell (outer, single source of truth) > decorators > story.render(args).
+// The real-shell contract: the host's AppShell ALWAYS wraps outside; CSF
+// decorators run inside it. Pure — returns an element tree, does not mount.
+// `args` defaults to the story's declared args; pass an override for live edits.
+export function composeStory(entry: StoryEntry, Shell?: ShellComponent, args: Args = entry.args): ReactElement {
+  let node: ReactElement = entry.render(args);
+
+  for (const decorate of entry.decorators) {
+    const inner = node;
+    const Story: ComponentType = () => inner;
+    node = decorate(Story);
+  }
+
+  return Shell ? createElement(Shell, null, node) : node;
+}

package/src/types.ts

@@ -0,0 +1,68 @@
+import type { ComponentType, ReactElement } from 'react';
+
+// --- CSF (Component Story Format) — compatible with Storybook stories ---
+
+export type Args = Record<string, unknown>;
+
+// A decorator receives the story as a component and returns a wrapped element,
+// e.g. (Story) => <Provider><Story /></Provider>.
+export type Decorator = (Story: ComponentType) => ReactElement;
+
+// CSF-compatible control hints. Optional: controls default to value-inference.
+// `control` accepts the Storybook string shorthand or an object { type, ... }.
+export type ControlKind = 'text' | 'number' | 'boolean' | 'select' | 'range';
+
+export type ArgType = {
+  control?: ControlKind | { type: ControlKind; min?: number; max?: number; step?: number };
+  options?: unknown[]; // for 'select'
+  min?: number;
+  max?: number;
+  step?: number; // for 'range' shorthand (alongside control: 'range')
+};
+
+export type ArgTypes = Record<string, ArgType>;
+
+// `export default` of a *.stories.tsx file.
+export type Meta = {
+  title?: string;
+  // Components have varied prop shapes; CSF passes args at runtime. Permissive
+  // by design so story files need no casts.
+  component?: ComponentType<any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+  args?: Args;
+  argTypes?: ArgTypes;
+  decorators?: Decorator[];
+};
+
+// A named export of a *.stories.tsx file (CSF3 object, or a CSF2 render fn).
+export type Story =
+  | {
+      name?: string;
+      args?: Args;
+      argTypes?: ArgTypes;
+      decorators?: Decorator[];
+      render?: (args: Args) => ReactElement;
+    }
+  | ((args: Args) => ReactElement);
+
+// A loaded story module: default = meta, named exports = stories.
+export type CsfModule = { default?: Meta } & Record<string, unknown>;
+
+// One normalized, render-ready story. Backend-agnostic: native and web both
+// consume this identical shape.
+export type StoryEntry = {
+  id: string; // 'button--primary'
+  title: string; // group, e.g. 'Button'
+  name: string; // story name, e.g. 'Primary'
+  args: Args;
+  argTypes: ArgTypes; // merged meta+story argTypes (possibly empty)
+  decorators: Decorator[];
+  render: (args: Args) => ReactElement;
+};
+
+// --- Discovery inputs (host-side, zero-codegen) ---
+
+// Metro's require.context.
+export type RequireContext = { keys(): string[]; (id: string): unknown };
+
+// Vite's eager import.meta.glob result: path -> module.
+export type GlobModules = Record<string, CsfModule>;