npm - @westopp/windo - Versions diffs - 0.1.0 - Mend

@westopp/windo 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (48) hide show

package/LICENSE +21 -0
package/README.md +146 -0
package/dist/chunk-5RM2VYAM.js +150 -0
package/dist/chunk-5RM2VYAM.js.map +1 -0
package/dist/cli.cjs +303 -0
package/dist/cli.cjs.map +1 -0
package/dist/cli.d.cts +1 -0
package/dist/cli.d.ts +1 -0
package/dist/cli.js +138 -0
package/dist/cli.js.map +1 -0
package/dist/index.cjs +219 -0
package/dist/index.cjs.map +1 -0
package/dist/index.d.cts +374 -0
package/dist/index.d.ts +374 -0
package/dist/index.js +182 -0
package/dist/index.js.map +1 -0
package/dist/plugin.cjs +185 -0
package/dist/plugin.cjs.map +1 -0
package/dist/plugin.d.cts +11 -0
package/dist/plugin.d.ts +11 -0
package/dist/plugin.js +11 -0
package/dist/plugin.js.map +1 -0
package/package.json +95 -0
package/src/cli/index.ts +160 -0
package/src/client/App.tsx +310 -0
package/src/client/Canvas.tsx +358 -0
package/src/client/Inspector.tsx +586 -0
package/src/client/Sidebar.tsx +108 -0
package/src/client/bridge.ts +124 -0
package/src/client/chrome.css +1966 -0
package/src/client/icons.tsx +110 -0
package/src/client/index.ts +15 -0
package/src/client/internal-types.ts +147 -0
package/src/client/persist.ts +38 -0
package/src/define-config.ts +54 -0
package/src/descriptor.test.ts +59 -0
package/src/descriptor.ts +185 -0
package/src/globals.d.ts +9 -0
package/src/index.ts +54 -0
package/src/plugin/index.ts +181 -0
package/src/preview/ctx.ts +43 -0
package/src/preview/index.ts +283 -0
package/src/preview/preview.css +81 -0
package/src/preview/registry.ts +159 -0
package/src/preview/render.tsx +90 -0
package/src/preview/virtual.d.ts +8 -0
package/src/protocol.ts +59 -0
package/src/types.ts +319 -0

package/src/plugin/index.ts ADDED Viewed

@@ -0,0 +1,181 @@
+// Vite plugin (node side). Pairs `@vitejs/plugin-react` with the windo plugin:
+// serves the chrome + iframe HTML documents ourselves (appType custom) and
+// exposes a `virtual:windo-registry` module that re-exports the user config and
+// glob-imports every `*.windo.tsx` file.
+import { existsSync } from 'node:fs'
+import { isAbsolute, resolve as resolvePath } from 'node:path'
+import reactPlugin from '@vitejs/plugin-react'
+import type { Plugin, PluginOption, UserConfig, ViteDevServer } from 'vite'
+export interface WindoPluginOptions {
+  include?: string | string[]
+  config?: string
+  root?: string
+}
+const VIRTUAL_ID = 'virtual:windo-registry'
+const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_ID}`
+const CONFIG_CANDIDATES = ['windo.config.ts', 'windo.config.tsx', 'windo.config.mts', 'windo.config.js', 'windo.config.mjs'] as const
+function findConfig(root: string, configOpt?: string): string | null {
+  if (configOpt) return isAbsolute(configOpt) ? configOpt : resolvePath(root, configOpt)
+  for (const candidate of CONFIG_CANDIDATES) {
+    const full = resolvePath(root, candidate)
+    if (existsSync(full)) return full
+  }
+  return null
+}
+function toGlob(include?: string | string[]): string {
+  const first = Array.isArray(include) ? include[0] : include
+  const pattern = first ?? '**/*.windo.tsx'
+  return pattern.startsWith('/') ? pattern : `/${pattern}`
+}
+const CHROME_HTML = `<!doctype html>
+<html data-theme="light">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>windo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module">
+      import('@westopp/windo/client')
+    </script>
+  </body>
+</html>
+`
+const IFRAME_HTML = `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body style="background: transparent">
+    <div id="root"></div>
+    <script type="module">
+      import('@westopp/windo/preview')
+    </script>
+  </body>
+</html>
+`
+// Absolute ids for the two HTML entry documents, relative to the project root.
+// They are virtual — the files need not exist on disk; the plugin's `load`
+// returns their contents. Keeping them rooted at `<root>/index.html` and
+// `<root>/__windo/iframe.html` makes `vite build` emit them at the matching
+// paths in the output directory (Vite derives an HTML asset's output path from
+// the input id's path relative to root).
+function htmlIds(root: string) {
+  return {
+    index: resolvePath(root, 'index.html'),
+    iframe: resolvePath(root, '__windo/iframe.html'),
+  }
+}
+export function windo(options: WindoPluginOptions = {}): PluginOption[] {
+  let resolvedRoot = process.cwd()
+  let ids = htmlIds(resolvedRoot)
+  const registryModule = (): string => {
+    const root = options.root ?? resolvedRoot ?? process.cwd()
+    const configPath = findConfig(root, options.config)
+    const glob = toGlob(options.include)
+    const importPath = configPath ? JSON.stringify(configPath) : 'null'
+    const globLiteral = JSON.stringify(glob)
+    return [
+      `import * as __cfg from ${importPath}`,
+      'const config = __cfg.config ?? (__cfg.default && __cfg.default.config) ?? __cfg.default',
+      'export { config }',
+      `export const modules = import.meta.glob(${globLiteral})`,
+      '',
+    ].join('\n')
+  }
+  const plugin: Plugin = {
+    name: 'windo',
+    // `pre` so our resolveId/load claim the virtual registry and the two HTML
+    // entries before Vite's filesystem fallback tries (and fails) to read them.
+    enforce: 'pre',
+    config(userConfig: UserConfig, { command, isPreview }) {
+      const root = resolvePath(options.root ?? userConfig.root ?? '.')
+      ids = htmlIds(root)
+      const base: UserConfig = {
+        // Dev serves the chrome + iframe HTML from `configureServer`, so it runs
+        // headless (`custom`). Build and preview want the normal SPA behaviour so
+        // `/` resolves to the emitted index.html.
+        appType: command === 'serve' && !isPreview ? 'custom' : 'spa',
+        define: {
+          __WINDO_IFRAME_SRC__: JSON.stringify(command === 'build' ? './__windo/iframe.html' : './__windo/iframe'),
+        },
+        resolve: {
+          dedupe: ['react', 'react-dom'],
+        },
+        optimizeDeps: {
+          // Pre-bundle every React entrypoint in one pass so React's identity is
+          // fixed up front. If `react-dom/client` (the preview renderer) is
+          // discovered late, Vite re-optimizes and can split React across two
+          // instances — fine until a component calls a hook, then "invalid hook
+          // call". Keeping them all here prevents that re-optimize.
+          include: ['react', 'react-dom', 'react-dom/client', 'react/jsx-runtime', 'react/jsx-dev-runtime'],
+        },
+      }
+      // Wire the chrome + iframe as build inputs unless the user supplied their
+      // own. Both are emitted as static HTML the canvas can be hosted from.
+      if (command === 'build' && !userConfig.build?.rollupOptions?.input) {
+        base.build = { rollupOptions: { input: { index: ids.index, iframe: ids.iframe } } }
+      }
+      return base
+    },
+    configResolved(resolved) {
+      resolvedRoot = resolved.root
+      ids = htmlIds(resolvedRoot)
+    },
+    resolveId(id) {
+      if (id === VIRTUAL_ID) return RESOLVED_VIRTUAL_ID
+      if (id === ids.index || id === ids.iframe) return id
+      return null
+    },
+    load(id) {
+      if (id === RESOLVED_VIRTUAL_ID) return registryModule()
+      if (id === ids.index) return CHROME_HTML
+      if (id === ids.iframe) return IFRAME_HTML
+      return null
+    },
+    configureServer(server: ViteDevServer) {
+      server.middlewares.use(async (req, res, next) => {
+        if (req.method !== 'GET') return next()
+        const url = (req.url ?? '').split('?')[0]
+        let html: string | null = null
+        if (url === '/' || url === '/index.html') html = CHROME_HTML
+        else if (url.startsWith('/__windo/iframe')) html = IFRAME_HTML
+        if (html === null) return next()
+        try {
+          const transformed = await server.transformIndexHtml(url, html)
+          res.statusCode = 200
+          res.setHeader('Content-Type', 'text/html')
+          res.end(transformed)
+        } catch (err) {
+          next(err)
+        }
+      })
+    },
+  }
+  return [reactPlugin(), plugin]
+}
+export const windoPlugin = windo
+export default windo

package/src/preview/ctx.ts ADDED Viewed

@@ -0,0 +1,43 @@
+// Build the live `WindoRenderContext` handed to every render-time function
+// inside the iframe. `ctx.logger.log` posts WindoLogEntry events up to the
+// chrome; `ctx.state`/`ctx.setState` are the component-local state surface;
+// opted-in contexts are resolved against the current env values.
+import type { WindoContextMap, WindoEnvState, WindoLogEntry, WindoRenderContext } from '../types'
+export function buildRenderContext<State>(
+  env: WindoEnvState,
+  contexts: WindoContextMap,
+  postLog: (entry: WindoLogEntry) => void,
+  state: State,
+  setState: (patch: Partial<State>) => void
+): WindoRenderContext<State> {
+  const logger = {
+    log: (...args: unknown[]) => postLog({ ts: Date.now(), args }),
+  }
+  const ctx: WindoRenderContext<State> = {
+    colorScheme: env.colorScheme,
+    viewport: env.viewport,
+    reducedMotion: env.reducedMotion,
+    direction: env.direction,
+    locale: env.locale,
+    logger,
+    state,
+    setState,
+    contexts: {},
+  }
+  for (const name of Object.keys(contexts)) {
+    const def = contexts[name]
+    const defaults: Record<string, unknown> = {}
+    const controlMap = def.controls ?? {}
+    for (const key of Object.keys(controlMap)) {
+      defaults[key] = controlMap[key].default
+    }
+    const values = { ...defaults, ...(env.contexts[name] ?? {}) }
+    ctx.contexts[name] = def.resolve ? def.resolve(values, ctx) : values
+  }
+  return ctx
+}

package/src/preview/index.ts ADDED Viewed

@@ -0,0 +1,283 @@
+// The iframe preview entry. Resolves the virtual registry into a manifest,
+// owns the runtime state (selected windo, parsed values, env), renders the
+// selected component, and runs the postMessage conversation with the chrome.
+import { config, modules } from 'virtual:windo-registry'
+import { createElement } from 'react'
+import type { Root } from 'react-dom/client'
+import { createRoot } from 'react-dom/client'
+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 { buildRenderContext } from './ctx'
+import { buildContextMeta, flattenZodError, idFromPath, sortEntries, summarizeLogArg, toCloneable } from './registry'
+import { PreviewRoot } from './render'
+import './preview.css'
+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,
+}
+interface ResolvedWindo {
+  id: string
+  def: WindoDefinition
+}
+const DEFAULT_ENV: WindoEnvState = {
+  colorScheme: 'light',
+  viewport: { width: 1160, height: 720, name: 'desktop' },
+  reducedMotion: false,
+  direction: 'ltr',
+  locale: 'en-US',
+  contexts: {},
+}
+let resolved: ResolvedWindo[] = []
+let entries: WindoManifestEntry[] = []
+let currentId: string | null = null
+let currentDef: WindoDefinition | null = null
+let currentSchema: z.ZodType | undefined
+let currentValues: unknown = {}
+let env: WindoEnvState = DEFAULT_ENV
+let currentState: Record<string, unknown> = {}
+let root: Root | null = null
+function postToParent(msg: WindoPreviewMessage) {
+  window.parent.postMessage(msg, '*')
+}
+function postLog(entry: WindoLogEntry) {
+  // Summarize args (events/DOM nodes → compact markers) so the console stays
+  // readable and a SyntheticEvent doesn't balloon the postMessage payload.
+  postToParent({ source: WINDO_MSG, dir: 'preview', type: 'log', entry: { ...entry, args: entry.args.map(summarizeLogArg) } })
+}
+/** 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)
+}
+function setState(patch: Partial<Record<string, unknown>>) {
+  currentState = { ...currentState, ...patch }
+  render()
+  postState()
+}
+/** Post the current state snapshot + each action's live `disabled` flag up to the chrome. */
+function postState() {
+  if (!currentId || !currentDef) return
+  // `disabled` predicates are pure reads of the same state — one ctx covers them all.
+  const ctx = makeCtx()
+  const actions = (currentDef.actions ?? []).map((a, i) => ({
+    id: String(i),
+    disabled: a.disabled ? !!a.disabled(ctx) : false,
+  }))
+  // Preserve declared keys (incl. explicit `undefined`) so the read-only strip mirrors state faithfully.
+  const state: Record<string, unknown> = {}
+  for (const key of Object.keys(currentState)) state[key] = toCloneable(currentState[key])
+  postToParent({ source: WINDO_MSG, dir: 'preview', type: 'state', id: currentId, state, actions })
+}
+/** Run a toolbar (`click`) action by its index. */
+function invokeAction(actionId: string) {
+  const action = currentDef?.actions?.[Number(actionId)]
+  if (!action) return
+  action.run(makeCtx(), true)
+}
+/** Dispatch pointer-bound actions as the pointer crosses the stage. */
+function dispatchStage(phase: 'enter' | 'leave') {
+  if (!currentDef?.actions) return
+  for (const action of currentDef.actions) {
+    const on = action.on ?? 'click'
+    if (on === 'click') continue
+    // Rebuild ctx per action so a later action sees an earlier one's setState.
+    const ctx = makeCtx()
+    if (on === 'hover') action.run(ctx, phase === 'enter')
+    else if (on === 'enter' && phase === 'enter') action.run(ctx, true)
+    else if (on === 'exit' && phase === 'leave') action.run(ctx, true)
+  }
+}
+function manifestEntry(id: string, def: WindoDefinition): WindoManifestEntry {
+  const actions: WindoActionMeta[] = (def.actions ?? []).map((a, i) => ({ id: String(i), label: a.label, on: a.on ?? 'click' }))
+  const entry: WindoManifestEntry = {
+    id,
+    title: def.title,
+    group: def.group,
+    status: def.status ?? 'stable',
+    placement: def.placement ?? 'center',
+    uses: def.uses ?? [],
+    hasVariants: (def.variants?.length ?? 0) > 0,
+    actions,
+    hasState: !!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
+  return entry
+}
+function computeDefaults(schema: z.ZodType | undefined): unknown {
+  if (!schema) return {}
+  const result = schema.safeParse({})
+  return result.success ? result.data : {}
+}
+function safeCode(def: WindoDefinition, defaults: unknown): string | null {
+  if (!def.code) return null
+  try {
+    return def.code(defaults as never)
+  } catch {
+    return null
+  }
+}
+function postManifest() {
+  postToParent({
+    source: WINDO_MSG,
+    dir: 'preview',
+    type: 'manifest',
+    title: config.title ?? 'windo',
+    entries,
+    groups: [...config.groups],
+    contexts: buildContextMeta(contexts),
+  })
+}
+function postDescribe(id: string, def: WindoDefinition, schema: z.ZodType | undefined) {
+  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> }))
+  postToParent({
+    source: WINDO_MSG,
+    dir: 'preview',
+    type: 'describe',
+    id,
+    descriptor: describeSchema(schema),
+    props: def.props ?? [],
+    variants,
+    defaults: toCloneable(defaults),
+    code: safeCode(def, defaults),
+  })
+}
+function render() {
+  if (!currentDef || !root) return
+  const ctx = makeCtx()
+  const id = currentId ?? ''
+  root.render(
+    createElement(PreviewRoot, {
+      def: currentDef,
+      ctx,
+      values: currentValues,
+      contexts,
+      onStage: dispatchStage,
+      onError: (message: string, stack?: string) => {
+        postToParent({ source: WINDO_MSG, dir: 'preview', type: 'render-error', id, message, ...(stack === undefined ? {} : { stack }) })
+      },
+    })
+  )
+}
+function handleSelect(id: string) {
+  const match = resolved.find(r => r.id === id)
+  if (!match) return
+  currentId = id
+  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>) ?? {}) }
+  render()
+  postState()
+  postDescribe(id, currentDef, currentSchema)
+}
+function handleSetProps(id: string, json: string) {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(json)
+  } catch (err) {
+    postToParent({
+      source: WINDO_MSG,
+      dir: 'preview',
+      type: 'parse-error',
+      id,
+      errors: [{ path: '', message: err instanceof Error ? err.message : 'Invalid JSON' }],
+    })
+    return
+  }
+  if (currentSchema) {
+    const result = currentSchema.safeParse(parsed)
+    if (result.success) {
+      currentValues = result.data
+      postToParent({ source: WINDO_MSG, dir: 'preview', type: 'parse-ok', id })
+      render()
+    } else {
+      postToParent({ source: WINDO_MSG, dir: 'preview', type: 'parse-error', id, errors: flattenZodError(result.error) })
+    }
+    return
+  }
+  currentValues = parsed
+  postToParent({ source: WINDO_MSG, dir: 'preview', type: 'parse-ok', id })
+  render()
+}
+function handleMessage(msg: WindoHostMessage) {
+  switch (msg.type) {
+    case 'request-manifest':
+      postManifest()
+      break
+    case 'select':
+      handleSelect(msg.id)
+      break
+    case 'set-props':
+      handleSetProps(msg.id, msg.json)
+      break
+    case 'set-env':
+      env = msg.env
+      render()
+      break
+    case 'invoke-action':
+      invokeAction(msg.actionId)
+      break
+  }
+}
+async function init() {
+  const rootEl = document.getElementById('root')
+  if (!rootEl) return
+  root = createRoot(rootEl)
+  const paths = Object.keys(modules)
+  const loaded = await Promise.all(
+    paths.map(async path => {
+      const mod = await modules[path]()
+      return { path, def: mod.default.resolve(w) }
+    })
+  )
+  resolved = loaded.map(({ path, def }) => ({ id: idFromPath(path), def }))
+  entries = sortEntries(
+    resolved.map(r => manifestEntry(r.id, r.def)),
+    config.groups.map(g => g.slug)
+  )
+  window.addEventListener('message', event => {
+    if (!isWindoMessage(event.data)) return
+    if (!isHostMessage(event.data)) return
+    handleMessage(event.data)
+  })
+  postToParent({ source: WINDO_MSG, dir: 'preview', type: 'ready' })
+}
+void init()

package/src/preview/preview.css ADDED Viewed

@@ -0,0 +1,81 @@
+/* The iframe document is transparent — the chrome paints the canvas grid
+   behind it. The root fills the frame; placement classes position the
+   rendered component within it. */
+html,
+body {
+  margin: 0;
+  background: transparent;
+}
+#root {
+  min-height: 100vh;
+  display: flex;
+}
+.windo-placement {
+  flex: 1;
+  display: flex;
+  box-sizing: border-box;
+}
+/* Opt-in padding via the `-padding` placement suffix. */
+.windo-placement.padded {
+  padding: 24px;
+}
+.windo-placement.center {
+  align-items: center;
+  justify-content: center;
+}
+.windo-placement.top {
+  justify-content: center;
+  align-items: flex-start;
+}
+.windo-placement.bottom {
+  justify-content: center;
+  align-items: flex-end;
+}
+.windo-placement.left {
+  justify-content: flex-start;
+  align-items: center;
+}
+.windo-placement.right {
+  justify-content: flex-end;
+  align-items: center;
+}
+.windo-placement.top-left {
+  justify-content: flex-start;
+  align-items: flex-start;
+}
+.windo-placement.top-right {
+  justify-content: flex-end;
+  align-items: flex-start;
+}
+.windo-placement.bottom-left {
+  justify-content: flex-start;
+  align-items: flex-end;
+}
+.windo-placement.bottom-right {
+  justify-content: flex-end;
+  align-items: flex-end;
+}
+.windo-placement.fill {
+  align-items: stretch;
+  justify-content: stretch;
+}
+.windo-placement.fill > * {
+  flex: 1;
+  width: 100%;
+  height: 100%;
+}