component-previewer 0.1.1 → 0.2.0

package/src/PreviewControls.tsx

@@ -1,27 +1,76 @@
-import React from 'react';
+import React, { useState } from 'react';
 import { Pressable, ScrollView, StyleSheet, Switch, Text, TextInput, View } from 'react-native';
 import type { Control } from './controls';
+import type { GlobalTypes, Globals } from './types';
 
 // Dependency-free controls panel (bottom sheet). Neutral chrome — the host theme
-// applies to the previewed story, not here. Each control edits one arg live.
+// applies to the previewed story, not here. A top "Globals" section switches the
+// shell (theme/locale, …); below it, each control edits one arg live.
 export function PreviewControls({
   controls,
   onChange,
   onReset,
+  onCopy,
+  globalTypes,
+  globals,
+  onGlobalChange,
 }: {
   controls: Control[];
   onChange: (name: string, value: unknown) => void;
   onReset: () => void;
+  onCopy?: () => void;
+  globalTypes?: GlobalTypes;
+  globals?: Globals;
+  onGlobalChange?: (key: string, value: unknown) => void;
 }) {
+  const globalKeys = globalTypes ? Object.keys(globalTypes) : [];
   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 style={styles.headerActions}>
+          {onCopy && (
+            <Pressable onPress={onCopy} accessibilityRole="button" accessibilityLabel="Copy props">
+              <Text style={styles.action}>Copy</Text>
+            </Pressable>
+          )}
+          <Pressable onPress={onReset} accessibilityRole="button" accessibilityLabel="Reset props">
+            <Text style={styles.action}>Reset</Text>
+          </Pressable>
+        </View>
       </View>
       <ScrollView keyboardShouldPersistTaps="handled">
+        {globalKeys.length > 0 && globalTypes && globals && onGlobalChange && (
+          <View style={styles.globals}>
+            <Text style={styles.sectionLabel}>Globals</Text>
+            {globalKeys.map((key) => {
+              const gt = globalTypes[key];
+              return (
+                <View key={key} style={styles.row}>
+                  <Text style={styles.label}>{gt.label ?? key}</Text>
+                  <View style={styles.control}>
+                    <View style={styles.options}>
+                      {gt.options.map((opt) => {
+                        const selected = opt === globals[key];
+                        return (
+                          <Pressable
+                            key={String(opt)}
+                            style={[styles.pill, selected && styles.pillSelected]}
+                            onPress={() => onGlobalChange(key, opt)}
+                            accessibilityRole="button"
+                            accessibilityLabel={`${gt.label ?? key}: ${String(opt)}`}
+                          >
+                            <Text style={[styles.pillText, selected && styles.pillTextSelected]}>{String(opt)}</Text>
+                          </Pressable>
+                        );
+                      })}
+                    </View>
+                  </View>
+                </View>
+              );
+            })}
+          </View>
+        )}
         {controls.map((c) => (
           <View key={c.name} style={styles.row}>
             <Text style={styles.label}>{c.name}</Text>
@@ -75,6 +124,25 @@ function ControlInput({ control, onChange }: { control: Control; onChange: (valu
         </View>
       );
 
+    case 'color':
+      return (
+        <View style={styles.colorRow}>
+          <View style={[styles.swatch, { backgroundColor: control.value || 'transparent' }]} />
+          <TextInput
+            style={[styles.input, styles.colorInput]}
+            value={control.value}
+            autoCapitalize="none"
+            autoCorrect={false}
+            placeholder="#rrggbb"
+            placeholderTextColor="#666"
+            onChangeText={onChange}
+          />
+        </View>
+      );
+
+    case 'object':
+      return <ObjectInput value={control.value} onChange={onChange} />;
+
     default: // 'text'
       return (
         <TextInput
@@ -88,6 +156,33 @@ function ControlInput({ control, onChange }: { control: Control; onChange: (valu
   }
 }
 
+// Object/array editor. Holds the raw text locally so a transiently-invalid edit
+// (mid-typing) isn't reverted keystroke-by-keystroke; commits only on valid JSON.
+// Reset reseeds it because the panel is keyed by a reset nonce in PreviewStage.
+function ObjectInput({ value, onChange }: { value: unknown; onChange: (value: unknown) => void }) {
+  const [text, setText] = useState(() => JSON.stringify(value, null, 2));
+  const [valid, setValid] = useState(true);
+  return (
+    <TextInput
+      style={[styles.input, styles.objectInput, !valid && styles.objectInvalid]}
+      value={text}
+      multiline
+      autoCapitalize="none"
+      autoCorrect={false}
+      onChangeText={(t) => {
+        setText(t);
+        try {
+          const parsed: unknown = JSON.parse(t);
+          setValid(true);
+          onChange(parsed);
+        } catch {
+          setValid(false); // keep the text; don't commit until it parses
+        }
+      }}
+    />
+  );
+}
+
 const styles = StyleSheet.create({
   sheet: {
     position: 'absolute',
@@ -106,7 +201,10 @@ const styles = StyleSheet.create({
   },
   header: { flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center', marginBottom: 8 },
   title: { color: '#fff', fontSize: 16, fontWeight: '700' },
-  reset: { color: '#7aa2ff', fontSize: 14, fontWeight: '600' },
+  headerActions: { flexDirection: 'row', gap: 16 },
+  action: { color: '#7aa2ff', fontSize: 14, fontWeight: '600' },
+  globals: { marginBottom: 8, paddingBottom: 8, borderBottomWidth: StyleSheet.hairlineWidth, borderBottomColor: '#333' },
+  sectionLabel: { color: '#7f7f88', fontSize: 11, fontWeight: '700', textTransform: 'uppercase', letterSpacing: 0.6 },
   row: { flexDirection: 'row', alignItems: 'center', paddingVertical: 8, gap: 12 },
   label: { color: '#cbcbd2', fontSize: 14, width: 96 },
   control: { flex: 1, alignItems: 'flex-end' },
@@ -120,6 +218,11 @@ const styles = StyleSheet.create({
     width: '100%',
     textAlign: 'right',
   },
+  colorRow: { flexDirection: 'row', alignItems: 'center', gap: 8, width: '100%' },
+  swatch: { width: 26, height: 26, borderRadius: 6, borderWidth: StyleSheet.hairlineWidth, borderColor: '#555' },
+  colorInput: { flex: 1, minWidth: 0 },
+  objectInput: { textAlign: 'left', minHeight: 88, fontFamily: 'Courier', fontSize: 12 },
+  objectInvalid: { borderWidth: 1, borderColor: '#e0566f' },
   options: { flexDirection: 'row', flexWrap: 'wrap', justifyContent: 'flex-end', gap: 6 },
   pill: { backgroundColor: '#262629', borderRadius: 999, paddingHorizontal: 12, paddingVertical: 6 },
   pillSelected: { backgroundColor: '#7aa2ff' },

package/src/PreviewList.tsx

@@ -39,7 +39,13 @@ export function PreviewList({
           data={filtered}
           keyExtractor={(e) => e.id}
           renderItem={({ item }) => (
-            <Pressable style={styles.row} onPress={() => onSelect(item)}>
+            <Pressable
+              style={styles.row}
+              onPress={() => onSelect(item)}
+              accessibilityRole="button"
+              accessibilityLabel={`${item.title} / ${item.name}`}
+              testID={`story-row-${item.id}`}
+            >
               <Text style={styles.rowTitle}>
                 {item.title} <Text style={styles.rowName}>/ {item.name}</Text>
               </Text>

package/src/PreviewStage.tsx

@@ -2,45 +2,90 @@ import React, { useMemo, useState } from 'react';
 import { Pressable, StyleSheet, Text, View } from 'react-native';
 import { inferControls } from './controls';
 import { PreviewControls } from './PreviewControls';
+import { loadArgs, resetArgs, saveArgs, type ArgsPersistence } from './persistence';
 import { composeStory, type ShellComponent } from './shell';
-import type { Args, StoryEntry } from './types';
+import type { Args, GlobalTypes, Globals, 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.
+// Live props controls edit `args` and re-render the story in place. Edits persist
+// per story id (session by default; cross-reload if a `persistence` adapter is
+// passed), so navigating away and back keeps your tweaks. `globals` parameterize
+// the shell (theme/locale) from the same panel.
 export function PreviewStage({
   entry,
   shell,
   onBack,
+  persistence,
+  onCopyArgs,
+  globalTypes,
+  globals,
+  onGlobalChange,
 }: {
   entry: StoryEntry;
   shell?: ShellComponent;
   onBack: () => void;
+  persistence?: ArgsPersistence;
+  onCopyArgs?: (args: Args, entry: StoryEntry) => void;
+  globalTypes?: GlobalTypes;
+  globals?: Globals;
+  onGlobalChange?: (key: string, value: unknown) => void;
 }) {
-  const [args, setArgs] = useState<Args>(entry.args);
+  const [args, setArgs] = useState<Args>(() => loadArgs(entry.id, entry.args, persistence));
   const [controlsOpen, setControlsOpen] = useState(false);
+  // Bumped on Reset to remount the controls panel so the JSON object editor
+  // reseeds its local text from the restored args.
+  const [resetNonce, setResetNonce] = useState(0);
   const controls = useMemo(() => inferControls(args, entry.argTypes), [args, entry.argTypes]);
 
+  const change = (name: string, value: unknown) =>
+    setArgs((a) => {
+      const next = { ...a, [name]: value };
+      saveArgs(entry.id, next, persistence);
+      return next;
+    });
+
+  const reset = () => {
+    resetArgs(entry.id, persistence);
+    setArgs(entry.args);
+    setResetNonce((n) => n + 1);
+  };
+
+  // Default copy logs the args JSON (zero-dep); a host can wire a real clipboard.
+  const copy = () => {
+    if (onCopyArgs) onCopyArgs(args, entry);
+    else console.log(`[previewer] ${entry.id} args:\n${JSON.stringify(args, null, 2)}`);
+  };
+
+  const hasGlobals = !!globalTypes && Object.keys(globalTypes).length > 0;
+  const hasPanel = controls.length > 0 || hasGlobals;
+
   return (
     <View style={styles.root}>
-      <View style={styles.content}>{composeStory(entry, shell, args)}</View>
-      <Pressable style={styles.back} onPress={onBack} accessibilityLabel="Back to stories">
+      <View style={styles.content}>{composeStory(entry, shell, args, globals)}</View>
+      <Pressable style={styles.back} onPress={onBack} accessibilityRole="button" accessibilityLabel="Back to stories">
         <Text style={styles.backText}>‹ {entry.title} / {entry.name}</Text>
       </Pressable>
-      {controls.length > 0 && (
+      {hasPanel && (
         <Pressable
           style={styles.toggle}
           onPress={() => setControlsOpen((v) => !v)}
+          accessibilityRole="button"
           accessibilityLabel="Toggle props controls"
         >
           <Text style={styles.backText}>{controlsOpen ? 'Controls ▾' : 'Controls ▴'}</Text>
         </Pressable>
       )}
-      {controlsOpen && controls.length > 0 && (
+      {controlsOpen && hasPanel && (
         <PreviewControls
+          key={resetNonce}
           controls={controls}
-          onChange={(name, value) => setArgs((a) => ({ ...a, [name]: value }))}
-          onReset={() => setArgs(entry.args)}
+          onChange={change}
+          onReset={reset}
+          onCopy={copy}
+          globalTypes={globalTypes}
+          globals={globals}
+          onGlobalChange={onGlobalChange}
         />
       )}
     </View>

package/src/Previewer.tsx

@@ -1,28 +1,55 @@
 import React, { useState } from 'react';
+import { initGlobals } from './globals';
 import { PreviewList } from './PreviewList';
 import { PreviewStage } from './PreviewStage';
+import type { ArgsPersistence } from './persistence';
 import type { ShellComponent } from './shell';
-import type { StoryEntry } from './types';
+import type { Args, GlobalTypes, 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").
+// screenshots / "jump to the thing I'm editing"). `persistence` (optional) makes
+// edited args survive a cold reload; `onCopyArgs` (optional) wires a real
+// clipboard for the Copy button (defaults to console.log). `globalTypes`
+// (optional) declares toolbar params (theme/locale) that the shell reads — one
+// real shell parameterized, instead of forked light/dark copies.
 export function Previewer({
   stories,
   shell,
   initialStoryId,
+  persistence,
+  onCopyArgs,
+  globalTypes,
 }: {
   stories: StoryEntry[];
   shell?: ShellComponent;
   initialStoryId?: string;
+  persistence?: ArgsPersistence;
+  onCopyArgs?: (args: Args, entry: StoryEntry) => void;
+  globalTypes?: GlobalTypes;
 }) {
   const initial = initialStoryId ? (stories.find((s) => s.id === initialStoryId) ?? null) : null;
   const [selected, setSelected] = useState<StoryEntry | null>(initial);
+  // Globals live above the selected story so they survive list <-> stage nav.
+  const [globals, setGlobals] = useState(() => initGlobals(globalTypes));
+  const changeGlobal = (key: string, value: unknown) => setGlobals((g) => ({ ...g, [key]: value }));
 
   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 (
+      <PreviewStage
+        key={selected.id}
+        entry={selected}
+        shell={shell}
+        onBack={() => setSelected(null)}
+        persistence={persistence}
+        onCopyArgs={onCopyArgs}
+        globalTypes={globalTypes}
+        globals={globals}
+        onGlobalChange={changeGlobal}
+      />
+    );
   }
   return <PreviewList entries={stories} onSelect={setSelected} />;
 }

package/src/controls.ts

@@ -3,9 +3,14 @@ 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: 'color'; 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[] };
+  | { name: string; kind: 'select'; value: unknown; options: unknown[] }
+  | { name: string; kind: 'object'; value: unknown };
+
+// A full hex color: #rgb, #rgba, #rrggbb, or #rrggbbaa.
+const HEX_COLOR = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
 
 type Bounds = { min?: number; max?: number; step?: number };
 
@@ -59,16 +64,31 @@ export function inferControls(args: Args, argTypes: ArgTypes = {}): Control[] {
       controls.push({ name, kind: 'boolean', value: Boolean(value) });
       continue;
     }
+    if (kind === 'color') {
+      controls.push({ name, kind: 'color', value: toText(value) });
+      continue;
+    }
+    if (kind === 'object') {
+      // Editable as JSON; the value passes through as-is until edited.
+      controls.push({ name, kind: 'object', 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 });
+    if (typeof value === 'string') {
+      // A bare hex string is unambiguously a color; everything else is text.
+      controls.push(
+        HEX_COLOR.test(value)
+          ? { name, kind: 'color', value }
+          : { 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).
+    // else: skipped (function/object/array/null/undefined) — pass through untouched.
   }
 
   return controls;

package/src/csf.ts

@@ -43,11 +43,16 @@ export function parseCsfModule(id: string, mod: CsfModule): StoryEntry[] {
     const decorators = [...(story.decorators ?? []), ...(meta?.decorators ?? [])];
     const name = story.name ?? exportName;
 
+    // Resolution order (Storybook CSF3): the story's own render, then a
+    // meta-level default render, then the meta `component` itself.
     const render =
       story.render ??
+      meta?.render ??
       ((a: Args) => {
         if (!meta?.component) {
-          throw new Error(`Story "${exportName}" in ${id}: no render fn and meta has no component`);
+          throw new Error(
+            `Story "${exportName}" in ${id}: no story render, no meta render, and meta has no component`,
+          );
         }
         return createElement(meta.component, a);
       });

package/src/globals.ts

@@ -0,0 +1,13 @@
+import type { GlobalTypes, Globals } from './types';
+
+// Build the initial globals object from the declared globalTypes: each key takes
+// its `default`, falling back to the first option. Pure; the Previewer seeds its
+// state from this and the shell reads the result.
+export function initGlobals(globalTypes: GlobalTypes = {}): Globals {
+  const globals: Globals = {};
+  for (const key of Object.keys(globalTypes)) {
+    const gt = globalTypes[key];
+    globals[key] = gt.default !== undefined ? gt.default : gt.options[0];
+  }
+  return globals;
+}

package/src/index.ts

@@ -5,6 +5,9 @@ export { composeStory } from './shell';
 export type { ShellComponent } from './shell';
 export { inferControls } from './controls';
 export type { Control } from './controls';
+export { initGlobals } from './globals';
+export { loadArgs, saveArgs, resetArgs } from './persistence';
+export type { ArgsPersistence } from './persistence';
 export type {
   Args,
   ArgType,
@@ -13,6 +16,9 @@ export type {
   CsfModule,
   Decorator,
   GlobModules,
+  Globals,
+  GlobalType,
+  GlobalTypes,
   Meta,
   RequireContext,
   Story,

package/src/persistence.ts

@@ -0,0 +1,49 @@
+import type { Args } from './types';
+
+// Optional host-provided adapter for cross-reload persistence. The package stays
+// dependency-free, so it never imports AsyncStorage/MMKV itself — the host wires
+// one if it wants edited args to survive a COLD reload:
+//
+//   import AsyncStorage from '@react-native-async-storage/async-storage';
+//   // ...a thin synchronous cache around AsyncStorage, or any sync store...
+//   <Previewer persistence={myAdapter} ... />
+export type ArgsPersistence = {
+  get(storyId: string): Args | undefined;
+  set(storyId: string, args: Args): void;
+  remove?(storyId: string): void;
+};
+
+// In-memory session store. Survives list <-> stage navigation AND Fast Refresh
+// (this module is untouched when a *.stories.tsx file edits), with zero deps.
+// Cleared only on a cold reload; pass `persistence` to outlast that too.
+const session = new Map<string, Args>();
+
+// Resolve the args to seed a story with: a live session edit wins, then a
+// host-persisted value (cached back into the session), then the declared args.
+export function loadArgs(storyId: string, declared: Args, persistence?: ArgsPersistence): Args {
+  const live = session.get(storyId);
+  if (live) return live;
+  const stored = persistence?.get(storyId);
+  if (stored) {
+    session.set(storyId, stored);
+    return stored;
+  }
+  return declared;
+}
+
+// Record an edit. Always updates the session; mirrors to the host adapter.
+export function saveArgs(storyId: string, args: Args, persistence?: ArgsPersistence): void {
+  session.set(storyId, args);
+  persistence?.set(storyId, args);
+}
+
+// Drop the override so the story falls back to its declared args.
+export function resetArgs(storyId: string, persistence?: ArgsPersistence): void {
+  session.delete(storyId);
+  persistence?.remove?.(storyId);
+}
+
+// Test seam: forget every session edit.
+export function _clearSession(): void {
+  session.clear();
+}

package/src/shell.tsx

@@ -1,15 +1,25 @@
 import { createElement } from 'react';
 import type { ComponentType, ReactElement } from 'react';
-import type { Args, StoryEntry } from './types';
+import type { Args, Globals, StoryEntry } from './types';
 
-export type ShellComponent = ComponentType<{ children: ReactElement }>;
+// The host's real app shell. Receives `children` always, and `globals` (the
+// toolbar params) so the SAME shell can switch theme/locale instead of being
+// forked. Shells written before globals existed (`{ children }` only) keep
+// working — the extra prop is simply ignored.
+export type ShellComponent = ComponentType<{ children: ReactElement; globals?: Globals }>;
 
 // Compose the full element for a story:
-//   AppShell (outer, single source of truth) > decorators > story.render(args).
+//   AppShell(globals) (outer, single source of truth) > decorators > 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 {
+// `globals` parameterize the shell (theme, locale, ...).
+export function composeStory(
+  entry: StoryEntry,
+  Shell?: ShellComponent,
+  args: Args = entry.args,
+  globals?: Globals,
+): ReactElement {
   let node: ReactElement = entry.render(args);
 
   for (const decorate of entry.decorators) {
@@ -18,5 +28,5 @@ export function composeStory(entry: StoryEntry, Shell?: ShellComponent, args: Ar
     node = decorate(Story);
   }
 
-  return Shell ? createElement(Shell, null, node) : node;
+  return Shell ? createElement(Shell, { children: node, globals }) : node;
 }

package/src/types.ts

@@ -10,7 +10,7 @@ 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 ControlKind = 'text' | 'number' | 'boolean' | 'select' | 'range' | 'color' | 'object';
 
 export type ArgType = {
   control?: ControlKind | { type: ControlKind; min?: number; max?: number; step?: number };
@@ -22,6 +22,21 @@ export type ArgType = {
 
 export type ArgTypes = Record<string, ArgType>;
 
+// --- Globals: toolbar-level params that parameterize the SHELL across every
+// story (theme, locale, ...). Unlike args (per-component props), globals let the
+// one real shell vary instead of being forked into light/dark copies or a
+// lighter hand-built lab. Declared once on the host <Previewer globalTypes=…>. ---
+
+export type Globals = Record<string, unknown>;
+
+export type GlobalType = {
+  options: unknown[]; // the toolbar choices (rendered as a pill select)
+  default?: unknown; // initial value; defaults to options[0]
+  label?: string; // toolbar label; defaults to the key
+};
+
+export type GlobalTypes = Record<string, GlobalType>;
+
 // `export default` of a *.stories.tsx file.
 export type Meta = {
   title?: string;
@@ -31,6 +46,9 @@ export type Meta = {
   args?: Args;
   argTypes?: ArgTypes;
   decorators?: Decorator[];
+  // A default render shared by every story in the file (CSF3). A story's own
+  // `render` overrides it; this overrides the `component` fallback.
+  render?: (args: Args) => ReactElement;
 };
 
 // A named export of a *.stories.tsx file (CSF3 object, or a CSF2 render fn).