@westopp/windo 0.1.0 → 0.1.2

package/src/preview/index.ts

@@ -10,7 +10,7 @@ import type { z } from 'zod'
 import { describeSchema } from '../descriptor'
 import type { WindoHostMessage, WindoPreviewMessage } from '../protocol'
 import { isHostMessage, isWindoMessage, WINDO_MSG } from '../protocol'
-import type { WindoActionMeta, WindoContextMap, WindoDefinition, WindoEnvState, WindoFactoryArg, WindoGroup, WindoLogEntry, WindoManifestEntry, WindoRenderContext, WindoVariantMeta } from '../types'
+import type { WindoActionMeta, WindoContextMap, WindoDefinition, WindoEnvState, WindoFactoryArg, WindoGroup, WindoInitContext, WindoLogEntry, WindoManifestEntry, WindoPlacement, WindoPropDoc, WindoRenderContext, WindoVariant, WindoVariantMeta } from '../types'
 import { buildRenderContext } from './ctx'
 import { buildContextMeta, flattenZodError, idFromPath, sortEntries, summarizeLogArg, toCloneable } from './registry'
 import { PreviewRoot } from './render'
@@ -21,6 +21,7 @@ const contexts = config.contexts ?? {}
 const w: WindoFactoryArg<readonly WindoGroup[], WindoContextMap> = {
   groups: Object.fromEntries(config.groups.map(g => [g.slug, g])) as Record<string, WindoGroup>,
   contexts,
+  tags: config.tags ? [...config.tags] : [],
 }
 
 interface ResolvedWindo {
@@ -45,7 +46,14 @@ let currentSchema: z.ZodType | undefined
 let currentValues: unknown = {}
 let env: WindoEnvState = DEFAULT_ENV
 let currentState: Record<string, unknown> = {}
+// Shared, cross-component state. Seeded once from the config and — unlike
+// `currentState` — never reset on selection, so it survives switching windos.
+let ctxState: Record<string, unknown> = { ...((config.ctxState as Record<string, unknown>) ?? {}) }
 let root: Root | null = null
+// Raised while a windo's full-ctx fields are being resolved (init state, defaultProps,
+// placement). Resolution must be a pure read of the env/ctxState surface — so the
+// mutating callbacks no-op while it's set, closing every re-entrant render path.
+let resolving = false
 
 function postToParent(msg: WindoPreviewMessage) {
   window.parent.postMessage(msg, '*')
@@ -59,15 +67,57 @@ function postLog(entry: WindoLogEntry) {
 
 /** The live ctx, rebuilt on demand so render-time, toolbar, and stage events all share the current state. */
 function makeCtx(): WindoRenderContext {
-  return buildRenderContext(env, contexts, postLog, currentState, setState)
+  return buildRenderContext(env, contexts, postLog, currentState, setState, ctxState, setCtxState, setColorScheme)
+}
+
+/**
+ * The init-scoped ctx handed to a `state` resolver. State is resolved exactly once,
+ * here, before any component-local state exists — so it exposes the env surface only
+ * with a no-op `setState`. The shared `setCtxState`/`setColorScheme` are still wired
+ * through but no-op while `resolving` is set, preventing an author from re-triggering
+ * resolution mid-init. Typed as `WindoInitContext` to drop the absent `state`/`setState`.
+ */
+function makeInitCtx(): WindoInitContext {
+  return buildRenderContext(env, contexts, postLog, {}, () => {}, ctxState, setCtxState, setColorScheme)
 }
 
 function setState(patch: Partial<Record<string, unknown>>) {
+  // No-op while resolving a windo's full-ctx fields — those are pure reads and must
+  // never drive a render, which would re-enter resolution and loop.
+  if (resolving) return
   currentState = { ...currentState, ...patch }
   render()
   postState()
 }
 
+/** Merge a patch into the shared state, re-render, and echo it up to the chrome. */
+function setCtxState(patch: Record<string, unknown>) {
+  if (resolving) return
+  ctxState = { ...ctxState, ...patch }
+  render()
+  postCtxState()
+}
+
+/** Cloneable snapshot of the shared state (drops functions/JSX before postMessage). */
+function cloneableCtxState(): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(ctxState)) out[key] = toCloneable(ctxState[key])
+  return out
+}
+
+function postCtxState() {
+  postToParent({ source: WINDO_MSG, dir: 'preview', type: 'ctx-state', state: cloneableCtxState() })
+}
+
+/** Set the canvas colour scheme from a component/action and echo it so the chrome's toggle stays in sync. */
+function setColorScheme(scheme: 'light' | 'dark') {
+  if (resolving) return
+  if (env.colorScheme === scheme) return
+  env = { ...env, colorScheme: scheme }
+  render()
+  postToParent({ source: WINDO_MSG, dir: 'preview', type: 'color-scheme', colorScheme: scheme })
+}
+
 /** Post the current state snapshot + each action's live `disabled` flag up to the chrome. */
 function postState() {
   if (!currentId || !currentDef) return
@@ -110,12 +160,15 @@ function manifestEntry(id: string, def: WindoDefinition): WindoManifestEntry {
     id,
     title: def.title,
     group: def.group,
+    tags: def.tags ?? [],
     status: def.status ?? 'stable',
-    placement: def.placement ?? 'center',
+    // The now-functionable fields can't be resolved here (no ctx at init): fall back
+    // to a safe static value, and assume the dynamic forms contribute a variant/state.
+    placement: typeof def.placement === 'function' ? 'center' : (def.placement ?? 'center'),
     uses: def.uses ?? [],
-    hasVariants: (def.variants?.length ?? 0) > 0,
+    hasVariants: typeof def.variants === 'function' ? true : (def.variants?.length ?? 0) > 0,
     actions,
-    hasState: !!def.state && Object.keys(def.state as object).length > 0,
+    hasState: typeof def.state === 'function' ? true : !!def.state && Object.keys(def.state as object).length > 0,
   }
   if (def.description !== undefined) entry.description = def.description
   if (def.deprecation !== undefined) entry.deprecation = def.deprecation
@@ -130,10 +183,85 @@ function computeDefaults(schema: z.ZodType | undefined): unknown {
 
 function safeCode(def: WindoDefinition, defaults: unknown): string | null {
   if (!def.code) return null
+  // `code` is a pure string producer — resolve it under `resolving` so it can't drive a
+  // render and post an inconsistent describe payload by mutating state mid-resolution.
+  resolving = true
   try {
-    return def.code(defaults as never)
+    return def.code(defaults as never, makeCtx())
   } catch {
     return null
+  } finally {
+    resolving = false
+  }
+}
+
+/** Resolve the authored Props table — a static array or a `ctx => array` function — under `resolving` so it stays a pure read. */
+function safeProps(def: WindoDefinition): WindoPropDoc[] {
+  const p = def.props
+  if (typeof p !== 'function') return p ?? []
+  resolving = true
+  try {
+    return p(makeCtx()) ?? []
+  } catch {
+    return []
+  } finally {
+    resolving = false
+  }
+}
+
+/** Resolve a windo's initial state — a static value or an init-ctx function — under `resolving`, degrading to `{}` if it throws. */
+function safeState(def: WindoDefinition): Record<string, unknown> {
+  const state = def.state
+  if (typeof state !== 'function') return { ...((state as Record<string, unknown> | undefined) ?? {}) }
+  resolving = true
+  try {
+    return { ...((state as (c: WindoInitContext) => unknown)(makeInitCtx()) as Record<string, unknown>) }
+  } catch {
+    return {}
+  } finally {
+    resolving = false
+  }
+}
+
+/** Resolve `defaultProps` — a static value or a `ctx => props` function — under `resolving` so it can't drive a render. */
+function safeDefaultProps(def: WindoDefinition, ctx: WindoRenderContext): unknown {
+  const dp = def.defaultProps
+  if (typeof dp !== 'function') return dp
+  resolving = true
+  try {
+    return (dp as (c: WindoRenderContext) => unknown)(ctx)
+  } catch {
+    return {}
+  } finally {
+    resolving = false
+  }
+}
+
+/** Resolve `placement` — a static value or a `ctx => placement` function — under `resolving`, degrading to `center` if it throws. */
+function safePlacement(def: WindoDefinition, ctx: WindoRenderContext): WindoPlacement {
+  const p = def.placement
+  if (typeof p !== 'function') return p ?? 'center'
+  resolving = true
+  try {
+    return p(ctx)
+  } catch {
+    return 'center'
+  } finally {
+    resolving = false
+  }
+}
+
+/** Resolve the gallery variants — a static array or a `ctx => array` function — under `resolving` so it stays a pure read. */
+function safeVariants(def: WindoDefinition): WindoVariant<unknown>[] {
+  const v = def.variants
+  if (typeof v !== 'function') return v ?? []
+  resolving = true
+  try {
+    return v(makeCtx()) ?? []
+  } catch {
+    return []
+  } finally {
+    resolving = false
   }
 }
 
@@ -145,7 +273,9 @@ function postManifest() {
     title: config.title ?? 'windo',
     entries,
     groups: [...config.groups],
+    tags: config.tags ? [...config.tags] : [],
     contexts: buildContextMeta(contexts),
+    ctxState: cloneableCtxState(),
   })
 }
 
@@ -153,14 +283,14 @@ function postDescribe(id: string, def: WindoDefinition, schema: z.ZodType | unde
   const defaults = computeDefaults(schema)
   // variant patches and defaults may carry ReactNodes/functions that postMessage
   // cannot clone — reduce them to JSON-safe forms before they cross the boundary.
-  const variants: WindoVariantMeta[] = (def.variants ?? []).map(v => ({ label: v.label, props: toCloneable(v.props) as Record<string, unknown> }))
+  const variants: WindoVariantMeta[] = safeVariants(def).map(v => ({ label: v.label, props: toCloneable(v.props) as Record<string, unknown> }))
   postToParent({
     source: WINDO_MSG,
     dir: 'preview',
     type: 'describe',
     id,
     descriptor: describeSchema(schema),
-    props: def.props ?? [],
+    props: safeProps(def),
     variants,
     defaults: toCloneable(defaults),
     code: safeCode(def, defaults),
@@ -171,12 +301,18 @@ function render() {
   if (!currentDef || !root) return
   const ctx = makeCtx()
   const id = currentId ?? ''
+  // Resolve the full-ctx fields here, OUTSIDE the React render cycle, so a function
+  // field that touches a mutating callback can't re-enter render() synchronously.
+  const defaultProps = safeDefaultProps(currentDef, ctx)
+  const placement = safePlacement(currentDef, ctx)
   root.render(
     createElement(PreviewRoot, {
       def: currentDef,
       ctx,
       values: currentValues,
       contexts,
+      defaultProps,
+      placement,
       onStage: dispatchStage,
       onError: (message: string, stack?: string) => {
         postToParent({ source: WINDO_MSG, dir: 'preview', type: 'render-error', id, message, ...(stack === undefined ? {} : { stack }) })
@@ -192,8 +328,11 @@ function handleSelect(id: string) {
   currentDef = match.def
   currentSchema = match.def.configurableProps
   currentValues = computeDefaults(currentSchema)
-  // Reset component-local state to the windo's declared initial state.
-  currentState = { ...((match.def.state as Record<string, unknown>) ?? {}) }
+  // Reset component-local state to the windo's declared initial state. Resolve it
+  // ONCE here — a `state` function runs against the init ctx (no live state/setState)
+  // under `resolving`, degrading to `{}` on throw. It is never re-resolved in
+  // render/makeCtx/set-env/set-ctx-state, so the author cannot drive a resolution loop.
+  currentState = safeState(currentDef)
   render()
   postState()
   postDescribe(id, currentDef, currentSchema)
@@ -246,6 +385,12 @@ function handleMessage(msg: WindoHostMessage) {
       env = msg.env
       render()
       break
+    case 'set-ctx-state':
+      // Chrome is the source of this update (an editor edit or a reload re-sync),
+      // so adopt it and re-render — but don't echo it back, to avoid a ping-pong.
+      ctxState = { ...msg.state }
+      render()
+      break
     case 'invoke-action':
       invokeAction(msg.actionId)
       break

package/src/preview/render.tsx

@@ -45,15 +45,18 @@ export interface PreviewRootProps {
   ctx: WindoRenderContext
   values: unknown
   contexts: WindoContextMap
+  /** `defaultProps` resolved outside the render cycle by `index.ts`, so a function field can't re-enter render here. */
+  defaultProps: unknown
+  /** `placement` resolved outside the render cycle by `index.ts`, for the same reason. */
+  placement: WindoPlacement
   onError: (message: string, stack?: string) => void
   /** Fires the windo's pointer-bound actions (`enter`/`exit`/`hover`) as the pointer crosses the stage. */
   onStage: (phase: 'enter' | 'leave') => void
 }
 
 export function PreviewRoot(props: PreviewRootProps) {
-  const { def, ctx, values, contexts, onError, onStage } = props
+  const { def, ctx, values, contexts, defaultProps, placement, onError, onStage } = props
 
-  const defaultProps = typeof def.defaultProps === 'function' ? (def.defaultProps as (c: WindoRenderContext) => unknown)(ctx) : def.defaultProps
   const finalProps = { ...(defaultProps as object), ...((values as object) ?? {}) }
 
   let tree: ReactNode = def.component(finalProps, ctx)
@@ -77,7 +80,6 @@ export function PreviewRoot(props: PreviewRootProps) {
     )
   }
 
-  const placement: WindoPlacement = def.placement ?? 'center'
   // Placements render flush; the `-padding` suffix opts into frame padding.
   const padded = placement.endsWith('-padding')
   const align = padded ? placement.slice(0, -'-padding'.length) : placement

package/src/protocol.ts

@@ -13,6 +13,7 @@ export type WindoHostMessage =
   | { source: typeof WINDO_MSG; dir: 'host'; type: 'select'; id: string }
   | { source: typeof WINDO_MSG; dir: 'host'; type: 'set-props'; id: string; json: string }
   | { source: typeof WINDO_MSG; dir: 'host'; type: 'set-env'; env: WindoEnvState }
+  | { source: typeof WINDO_MSG; dir: 'host'; type: 'set-ctx-state'; state: Record<string, unknown> }
   | { source: typeof WINDO_MSG; dir: 'host'; type: 'invoke-action'; id: string; actionId: string }
 
 /** iframe -> chrome */
@@ -25,7 +26,10 @@ export type WindoPreviewMessage =
       title: string
       entries: WindoManifestEntry[]
       groups: WindoGroup[]
+      tags: string[]
       contexts: WindoContextMeta[]
+      /** Initial shared state from the config — seeds the chrome's editable strip. */
+      ctxState: Record<string, unknown>
     }
   | {
       source: typeof WINDO_MSG
@@ -42,6 +46,8 @@ export type WindoPreviewMessage =
   | { source: typeof WINDO_MSG; dir: 'preview'; type: 'parse-error'; id: string; errors: WindoFieldError[] }
   | { source: typeof WINDO_MSG; dir: 'preview'; type: 'log'; entry: WindoLogEntry }
   | { source: typeof WINDO_MSG; dir: 'preview'; type: 'state'; id: string; state: Record<string, unknown>; actions: { id: string; disabled: boolean }[] }
+  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'ctx-state'; state: Record<string, unknown> }
+  | { source: typeof WINDO_MSG; dir: 'preview'; type: 'color-scheme'; colorScheme: 'light' | 'dark' }
   | { source: typeof WINDO_MSG; dir: 'preview'; type: 'render-error'; id: string; message: string; stack?: string }
 
 export type WindoMessage = WindoHostMessage | WindoPreviewMessage

package/src/types.ts

@@ -131,6 +131,20 @@ export interface WindoRenderContext<State = unknown> {
   setState: (patch: Partial<State>) => void
   /** Resolved values of opted-in contexts, keyed by context name. */
   contexts: Record<string, unknown>
+  /**
+   * Shared, cross-component state seeded from the config's `ctxState`. Unlike
+   * `state` (per-windo, reset on selection), this persists across selection and
+   * is global: any component can read it and write it via `setCtxState`. Use it
+   * to drive providers that wrap every component — e.g. a theme provider toggled
+   * from any component on the canvas.
+   */
+  ctxState: Record<string, unknown>
+  /** Merge a patch into the shared `ctxState` and re-render every consumer. */
+  setCtxState: (patch: Record<string, unknown>) => void
+  /** Set the canvas colour scheme from a component or action. */
+  setColorScheme: (scheme: 'light' | 'dark') => void
+  /** Flip the canvas colour scheme between light and dark. */
+  toggleTheme: () => void
 }
 
 /* ------------------------------------------------------------------ *
@@ -151,7 +165,13 @@ export interface WindoPropDoc {
   desc?: string
 }
 
-export type WindoDefaultProps<Props, State = unknown> = Props | ((ctx: WindoRenderContext<State>) => Props)
+/** A value that may be authored statically or as a context-aware `ctx => value` function resolved at render-time. */
+export type Ctxual<T, State = unknown> = T | ((ctx: WindoRenderContext<State>) => T)
+
+/** The ctx surface available while resolving a windo's initial state — the render-time `state`/`setState` pair is excluded because it does not exist yet. */
+export type WindoInitContext<State = unknown> = Omit<WindoRenderContext<State>, 'state' | 'setState'>
+
+export type WindoDefaultProps<Props, State = unknown> = Ctxual<Props, State>
 
 /**
  * The object returned by a `windo(...)` factory.
@@ -161,15 +181,18 @@ export type WindoDefaultProps<Props, State = unknown> = Props | ((ctx: WindoRend
  * `actions`, `providers`, `component` — runs at render-time with the live `ctx`.
  * Never close over live values in the static factory body.
  */
-export interface WindoDefinition<Props = unknown, State = unknown, GroupSlug extends string = string> {
+export interface WindoDefinition<Props = unknown, State = unknown, GroupSlug extends string = string, Tag extends string = string> {
   title: string
   group: GroupSlug
+  /** Tags this component carries. Each must be one of the config's declared `tags`. Drives the sidebar's tag filter. */
+  tags?: Tag[]
   status?: WindoStatus
   description?: string
   deprecation?: string
-  placement?: WindoPlacement
-  /** Initial component-local state. Its shape is the `State` generic; `ctx.state`/`ctx.setState` derive from it. */
-  state?: State
+  /** Where the component anchors in the canvas frame. Either a static placement or a function resolved with the live `ctx`. */
+  placement?: Ctxual<WindoPlacement, State>
+  /** Initial component-local state. Its shape is the `State` generic; `ctx.state`/`ctx.setState` derive from it. Either a static value or a function resolved with the init `ctx` (no `state`/`setState`) when the component is selected. */
+  state?: State | ((ctx: WindoInitContext<State>) => State)
   /** Out-of-band actions that drive state: toolbar buttons (`click`) and stage pointer triggers (`enter`/`exit`/`hover`). */
   actions?: WindoAction<State>[]
   /** zod schema: validator + parser for the JSON-editable prop subset. `z.output ⊆ Props`. */
@@ -178,21 +201,24 @@ export interface WindoDefinition<Props = unknown, State = unknown, GroupSlug ext
   defaultProps: WindoDefaultProps<Props, State>
   /** Names of provider contexts this component opts into. */
   uses?: string[]
-  variants?: WindoVariant<Props>[]
-  /** Authored documentation table (not derived from the schema). */
-  props?: WindoPropDoc[]
-  /** Optional authored code snippet for the Code tab. */
-  code?: (values: Props) => string
+  /** Gallery variants. Either a static array or a function resolved with the live `ctx` when the component is selected. */
+  variants?: Ctxual<WindoVariant<Props>[], State>
+  /** Authored documentation table (not derived from the schema). Either a static array or a function resolved with the live `ctx` when the component is selected. */
+  props?: Ctxual<WindoPropDoc[], State>
+  /** Optional authored code snippet for the Code tab, resolved with the JSON-editable values and the live `ctx`. */
+  code?: (values: Props, ctx: WindoRenderContext<State>) => string
   /** A local provider wrapping just this windo (in addition to `uses`). */
   providers?: ComponentType<{ children: ReactNode; ctx: WindoRenderContext<State> }>
   component: (props: Props, ctx: WindoRenderContext<State>) => ReactNode
 }
 
 /** Argument handed to the `windo(w => ...)` factory. */
-export interface WindoFactoryArg<Groups extends readonly WindoGroup[], Contexts extends WindoContextMap> {
+export interface WindoFactoryArg<Groups extends readonly WindoGroup[], Contexts extends WindoContextMap, Tags extends readonly string[] = readonly string[]> {
   /** Configured groups keyed by slug. */
   groups: Record<Groups[number]['slug'], WindoGroup>
   contexts: Contexts
+  /** The config's declared tags, in declaration order. */
+  tags: Tags
 }
 
 /**
@@ -209,11 +235,15 @@ export interface WindoModule<Props = any, State = any> {
  * Config
  * ------------------------------------------------------------------ */
 
-export interface WindoConfig<Groups extends readonly WindoGroup[] = readonly WindoGroup[], Contexts extends WindoContextMap = WindoContextMap> {
+export interface WindoConfig<Groups extends readonly WindoGroup[] = readonly WindoGroup[], Contexts extends WindoContextMap = WindoContextMap, Tags extends readonly string[] = readonly string[]> {
   /** Configured groups. A component's `group` must be one of these slugs. */
   groups: Groups
   /** Named contexts available to components. */
   contexts?: Contexts
+  /** The set of tags components may be assigned. A component's `tags` must be drawn from this list; the sidebar filters by them. */
+  tags?: Tags
+  /** Initial shared state exposed on `ctx.ctxState`. Global across every component and persisted across selection — write it from any component via `ctx.setCtxState`. */
+  ctxState?: Record<string, unknown>
   /** Glob(s) for discovery, relative to project root. Default `**\/*.windo.tsx`. */
   include?: string | string[]
   /** Title shown in the workbench chrome. */
@@ -256,6 +286,7 @@ export interface WindoManifestEntry {
   id: string
   title: string
   group: string
+  tags: string[]
   status: WindoStatus
   description?: string
   deprecation?: string

package/src/descriptor.test.ts

@@ -1,59 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { z } from 'zod'
-import { describeSchema } from './descriptor'
-import type { WindoControlDescriptor } from './types'
-
-function field(fields: WindoControlDescriptor[], key: string): WindoControlDescriptor {
-  const found = fields.find(f => f.key === key)
-  if (!found) throw new Error(`no field "${key}"`)
-  return found
-}
-
-describe('describeSchema', () => {
-  it('returns no fields for a missing schema', () => {
-    expect(describeSchema(undefined).fields).toEqual([])
-    expect(describeSchema(null).fields).toEqual([])
-  })
-
-  it('describes a z.enum as kind enum with the right options', () => {
-    const { fields } = describeSchema(z.object({ variant: z.enum(['primary', 'secondary', 'ghost']) }))
-    const variant = field(fields, 'variant')
-    expect(variant.kind).toBe('enum')
-    expect(variant.options).toEqual(['primary', 'secondary', 'ghost'])
-  })
-
-  it('describes a z.boolean as kind boolean', () => {
-    const { fields } = describeSchema(z.object({ disabled: z.boolean() }))
-    expect(field(fields, 'disabled').kind).toBe('boolean')
-  })
-
-  it('describes a bounded z.number with min and max', () => {
-    const { fields } = describeSchema(z.object({ count: z.number().min(0).max(10) }))
-    const count = field(fields, 'count')
-    expect(count.kind).toBe('number')
-    expect(count.min).toBe(0)
-    expect(count.max).toBe(10)
-  })
-
-  it('marks an optional field as optional', () => {
-    const { fields } = describeSchema(z.object({ label: z.string().optional() }))
-    const label = field(fields, 'label')
-    expect(label.kind).toBe('string')
-    expect(label.optional).toBe(true)
-  })
-
-  it('marks a required field as not optional', () => {
-    const { fields } = describeSchema(z.object({ label: z.string() }))
-    expect(field(fields, 'label').optional).toBe(false)
-  })
-
-  it('describes a z.coerce.date as kind date', () => {
-    const { fields } = describeSchema(z.object({ when: z.coerce.date() }))
-    expect(field(fields, 'when').kind).toBe('date')
-  })
-
-  it('describes a z.array as kind array', () => {
-    const { fields } = describeSchema(z.object({ tags: z.array(z.string()) }))
-    expect(field(fields, 'tags').kind).toBe('array')
-  })
-})