@westopp/windo 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,374 @@
+import { ComponentType, ReactNode } from 'react';
+import { z } from 'zod';
+
+type WindoStatus = 'stable' | 'beta' | 'deprecated';
+declare const WINDO_STATUSES: readonly WindoStatus[];
+/** Anchor a component within the canvas frame. */
+type WindoPlacementBase = 'center' | 'fill' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/**
+ * Where a component renders inside the canvas frame. Placements render flush by
+ * default; append `-padding` to inset the component from the frame edges
+ * (e.g. `top` sits flush at the top, `top-padding` adds breathing room).
+ */
+type WindoPlacement = WindoPlacementBase | `${WindoPlacementBase}-padding`;
+declare const WINDO_PLACEMENTS: readonly WindoPlacement[];
+/** A configured group. Components reference a group by its `slug`. */
+interface WindoGroup {
+    name: string;
+    slug: string;
+    description?: string;
+}
+type WindoControlType = 'enum' | 'boolean' | 'string' | 'number';
+/** A single ambient control: a value plus the metadata to render its toggle. */
+interface WindoControlSpec<T = unknown> {
+    type: WindoControlType;
+    label?: string;
+    default: T;
+    options?: readonly string[];
+    min?: number;
+    max?: number;
+    step?: number;
+}
+type WindoControlMap = Record<string, WindoControlSpec>;
+/** Resolve a control map to the value object it produces. */
+type WindoControlValues<C extends WindoControlMap> = {
+    [K in keyof C]: C[K] extends WindoControlSpec<infer T> ? T : never;
+};
+/**
+ * A named context. Two capabilities, either or both:
+ *  - `controls`  → ambient values + UI toggles (free, no opt-in needed)
+ *  - `provider`  → a React wrapper, mounted inside the iframe around components
+ *                  that opt in via `uses`
+ */
+interface WindoContextDefinition<Values = unknown, Provided = Values> {
+    label?: string;
+    description?: string;
+    controls?: WindoControlMap;
+    provider?: ComponentType<{
+        children: ReactNode;
+        values: Values;
+        ctx: WindoRenderContext;
+    }>;
+    /** Derive the value exposed on `ctx.contexts[name]`. Defaults to the control values. */
+    resolve?: (values: Values, ctx: WindoRenderContext) => Provided;
+}
+type WindoContextMap = Record<string, WindoContextDefinition<any, any>>;
+interface WindoViewport {
+    width: number;
+    height: number;
+    name: 'mobile' | 'tablet' | 'desktop';
+}
+/** Console channel: `ctx.logger.log(…)` posts an entry to the chrome's Console tab. */
+interface WindoLogger {
+    log: (...args: unknown[]) => void;
+}
+/** How an action fires. `click` renders a toolbar button; the rest bind to the stage's pointer events. */
+type WindoActionTrigger = 'click' | 'enter' | 'exit' | 'hover';
+declare const WINDO_ACTION_TRIGGERS: readonly WindoActionTrigger[];
+/**
+ * An out-of-band action that drives a component's state. `click` actions render as
+ * toolbar buttons; `enter`/`exit`/`hover` bind to the stage's pointer events. `run`
+ * receives the live ctx and an `active` flag — for `hover` it is `true` on
+ * pointer-enter and `false` on pointer-leave; for the others it is always `true`.
+ */
+interface WindoAction<State = unknown> {
+    label: string;
+    /** Defaults to `click`. */
+    on?: WindoActionTrigger;
+    run: (ctx: WindoRenderContext<State>, active: boolean) => void;
+    /** Greys out a `click` action's toolbar button. Evaluated against the live state. */
+    disabled?: (ctx: WindoRenderContext<State>) => boolean;
+}
+/** Live environment handed to every render-time function inside the iframe. */
+interface WindoRenderContext<State = unknown> {
+    colorScheme: 'light' | 'dark';
+    viewport: WindoViewport;
+    reducedMotion: boolean;
+    direction: 'ltr' | 'rtl';
+    locale: string;
+    logger: WindoLogger;
+    /** Current component-local state, typed by the windo's `State` generic. */
+    state: State;
+    /** Merge a patch into the component-local state and re-render. */
+    setState: (patch: Partial<State>) => void;
+    /** Resolved values of opted-in contexts, keyed by context name. */
+    contexts: Record<string, unknown>;
+}
+/** A variant: a label plus a partial prop patch. Renders in the gallery and is click-to-apply. */
+interface WindoVariant<Props> {
+    label: string;
+    props: Partial<Props>;
+}
+/** A row in the authored Props documentation table. */
+interface WindoPropDoc {
+    name: string;
+    type: string;
+    default?: string;
+    desc?: string;
+}
+type WindoDefaultProps<Props, State = unknown> = Props | ((ctx: WindoRenderContext<State>) => Props);
+/**
+ * The object returned by a `windo(...)` factory.
+ *
+ * Keystone rule: the surrounding factory runs ONCE (definition-time) for static
+ * fields (title, group, schema). Every function field below — `defaultProps`,
+ * `actions`, `providers`, `component` — runs at render-time with the live `ctx`.
+ * Never close over live values in the static factory body.
+ */
+interface WindoDefinition<Props = unknown, State = unknown, GroupSlug extends string = string> {
+    title: string;
+    group: GroupSlug;
+    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;
+    /** 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`. */
+    configurableProps?: z.ZodType;
+    /** Full props incl. functions/JSX. The editor's JSON overrides merge on top. */
+    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;
+    /** 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. */
+interface WindoFactoryArg<Groups extends readonly WindoGroup[], Contexts extends WindoContextMap> {
+    /** Configured groups keyed by slug. */
+    groups: Record<Groups[number]['slug'], WindoGroup>;
+    contexts: Contexts;
+}
+/**
+ * The default export of a `*.windo.tsx` file. A branded, lazily-resolved
+ * definition — the runtime calls `resolve(w)` with the config-derived factory arg.
+ */
+interface WindoModule<Props = any, State = any> {
+    readonly __windo: true;
+    resolve: (w: WindoFactoryArg<readonly WindoGroup[], WindoContextMap>) => WindoDefinition<Props, State>;
+}
+interface WindoConfig<Groups extends readonly WindoGroup[] = readonly WindoGroup[], Contexts extends WindoContextMap = WindoContextMap> {
+    /** Configured groups. A component's `group` must be one of these slugs. */
+    groups: Groups;
+    /** Named contexts available to components. */
+    contexts?: Contexts;
+    /** Glob(s) for discovery, relative to project root. Default `**\/*.windo.tsx`. */
+    include?: string | string[];
+    /** Title shown in the workbench chrome. */
+    title?: string;
+}
+type WindoControlKind = 'string' | 'number' | 'boolean' | 'enum' | 'date' | 'array' | 'object' | 'unknown';
+interface WindoControlDescriptor {
+    key: string;
+    kind: WindoControlKind;
+    optional: boolean;
+    options?: string[];
+    min?: number;
+    max?: number;
+    description?: string;
+}
+interface WindoSchemaDescriptor {
+    fields: WindoControlDescriptor[];
+}
+/** Serialisable metadata for one action — drives the canvas toolbar. */
+interface WindoActionMeta {
+    id: string;
+    label: string;
+    on: WindoActionTrigger;
+}
+/** Static, serialisable metadata for one windo — drives the sidebar. */
+interface WindoManifestEntry {
+    id: string;
+    title: string;
+    group: string;
+    status: WindoStatus;
+    description?: string;
+    deprecation?: string;
+    placement: WindoPlacement;
+    uses: string[];
+    hasVariants: boolean;
+    actions: WindoActionMeta[];
+    hasState: boolean;
+}
+interface WindoVariantMeta {
+    label: string;
+    props: Record<string, unknown>;
+}
+/** Ambient environment pushed from the chrome down into the iframe. */
+interface WindoEnvState {
+    colorScheme: 'light' | 'dark';
+    viewport: WindoViewport;
+    reducedMotion: boolean;
+    direction: 'ltr' | 'rtl';
+    locale: string;
+    /** Per-context control values, keyed by context name then control key. */
+    contexts: Record<string, Record<string, unknown>>;
+}
+interface WindoLogEntry {
+    ts: number;
+    args: unknown[];
+}
+interface WindoFieldError {
+    path: string;
+    message: string;
+}
+interface WindoContextControlMeta {
+    key: string;
+    type: WindoControlType;
+    label?: string;
+    options?: string[];
+    default: unknown;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+interface WindoContextMeta {
+    name: string;
+    label?: string;
+    description?: string;
+    /** True when the context contributes controls (ambient values). */
+    ambient: boolean;
+    /** True when the context mounts a provider (opt-in via `uses`). */
+    hasProvider: boolean;
+    controls: WindoContextControlMeta[];
+}
+
+interface DefineWindoConfigResult<Groups extends readonly WindoGroup[], Contexts extends WindoContextMap> {
+    config: WindoConfig<Groups, Contexts>;
+    windo: <Props, State = Record<string, never>>(factory: (w: WindoFactoryArg<Groups, Contexts>) => WindoDefinition<Props, State, Groups[number]['slug']>) => WindoModule<Props, State>;
+}
+declare function defineWindoConfig<const Groups extends readonly WindoGroup[], Contexts extends WindoContextMap = Record<string, never>>(config: WindoConfig<Groups, Contexts>): DefineWindoConfigResult<Groups, Contexts>;
+/**
+ * Define a named context. A context can contribute ambient `controls` (values +
+ * UI), a `provider` (mounted inside the iframe for components that opt in via
+ * `uses`), or both.
+ *
+ * No cast: `def` is already structurally a `WindoContextDefinition<WindoControlValues<C>,
+ * Provided>` (only `controls` widens, covariantly). The unavoidable variance — TS has
+ * no existential type to hold contexts heterogeneous in `C` — is absorbed once, in
+ * `WindoContextMap`, not here and not at call sites.
+ */
+declare function defineContext<C extends WindoControlMap, Provided = WindoControlValues<C>>(def: {
+    label?: string;
+    description?: string;
+    controls?: C;
+    provider?: ComponentType<{
+        children: ReactNode;
+        values: WindoControlValues<C>;
+        ctx: WindoRenderContext;
+    }>;
+    resolve?: (values: WindoControlValues<C>, ctx: WindoRenderContext) => Provided;
+}): WindoContextDefinition<WindoControlValues<C>, Provided>;
+/**
+ * Bind a zod schema to a component's props. The generic carries the component's
+ * prop type so the schema's output stays a subset of it; the returned schema is
+ * the runtime validator + parser (`z.input` is the JSON edit surface, `z.output`
+ * is what the component receives).
+ */
+declare function configurableProps<P>(): <S extends z.ZodType<Partial<P>>>(schema: S) => S;
+
+declare function describeSchema(schema: z.ZodType | undefined | null): WindoSchemaDescriptor;
+
+declare const WINDO_MSG = "windo";
+/** chrome -> iframe */
+type WindoHostMessage = {
+    source: typeof WINDO_MSG;
+    dir: 'host';
+    type: 'request-manifest';
+} | {
+    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: 'invoke-action';
+    id: string;
+    actionId: string;
+};
+/** iframe -> chrome */
+type WindoPreviewMessage = {
+    source: typeof WINDO_MSG;
+    dir: 'preview';
+    type: 'ready';
+} | {
+    source: typeof WINDO_MSG;
+    dir: 'preview';
+    type: 'manifest';
+    title: string;
+    entries: WindoManifestEntry[];
+    groups: WindoGroup[];
+    contexts: WindoContextMeta[];
+} | {
+    source: typeof WINDO_MSG;
+    dir: 'preview';
+    type: 'describe';
+    id: string;
+    descriptor: WindoSchemaDescriptor;
+    props: WindoPropDoc[];
+    variants: WindoVariantMeta[];
+    defaults: unknown;
+    code: string | null;
+} | {
+    source: typeof WINDO_MSG;
+    dir: 'preview';
+    type: 'parse-ok';
+    id: string;
+} | {
+    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: 'render-error';
+    id: string;
+    message: string;
+    stack?: string;
+};
+type WindoMessage = WindoHostMessage | WindoPreviewMessage;
+declare function isWindoMessage(data: unknown): data is WindoMessage;
+declare function isHostMessage(msg: WindoMessage): msg is WindoHostMessage;
+declare function isPreviewMessage(msg: WindoMessage): msg is WindoPreviewMessage;
+
+export { type DefineWindoConfigResult, WINDO_ACTION_TRIGGERS, WINDO_MSG, WINDO_PLACEMENTS, WINDO_STATUSES, type WindoAction, type WindoActionMeta, type WindoActionTrigger, type WindoConfig, type WindoContextControlMeta, type WindoContextDefinition, type WindoContextMap, type WindoContextMeta, type WindoControlDescriptor, type WindoControlKind, type WindoControlMap, type WindoControlSpec, type WindoControlType, type WindoControlValues, type WindoDefaultProps, type WindoDefinition, type WindoEnvState, type WindoFactoryArg, type WindoFieldError, type WindoGroup, type WindoHostMessage, type WindoLogEntry, type WindoLogger, type WindoManifestEntry, type WindoMessage, type WindoModule, type WindoPlacement, type WindoPreviewMessage, type WindoPropDoc, type WindoRenderContext, type WindoSchemaDescriptor, type WindoStatus, type WindoVariant, type WindoVariantMeta, type WindoViewport, configurableProps, defineContext, defineWindoConfig, describeSchema, isHostMessage, isPreviewMessage, isWindoMessage };