vitral 0.1.0 → 0.3.0

package/dist/types-Czvm-siZ.d.ts

@@ -0,0 +1,327 @@
+import { R as RemoteError } from './errors-kjBv6IH_.js';
+
+/**
+ * Tipos das chaves compartilhadas. Declare uma vez no projeto:
+ *
+ *   declare module 'vitral' {
+ *     interface Shared { usuario: { id: number; nome: string } | null; tema: 'claro' | 'escuro' }
+ *   }
+ */
+interface Shared {
+}
+/** Tipo do valor de `K`: o declarado em `Shared`, ou `unknown`. */
+type SharedType<K extends string> = K extends keyof Shared ? Shared[K] : unknown;
+/**
+ * Acesso a uma chave. Segue o contrato de store do Svelte (`$tema` funciona).
+ * O valor é tratado como imutável: para mudar, passe um valor novo.
+ */
+interface SharedValue<T> {
+    /** A chave. */
+    readonly key: string;
+    /** Valor atual, ou `undefined` se ninguém deu valor ainda. */
+    get(): T | undefined;
+    /** Troca o valor. Numa chave com `writable: false`, só o dono pode. */
+    set(value: T): void;
+    /** `set(fn(get()))`. */
+    update(fn: (value: T | undefined) => T): void;
+    /** Chama `fn` agora, com o valor atual, e a cada mudança. Devolve a função que cancela. */
+    subscribe(fn: (value: T | undefined) => void): () => void;
+}
+/** O que `provide` devolve. Quando é o dono, `set` sempre passa. */
+interface ProvidedValue<T> extends SharedValue<T> {
+    get(): T;
+    update(fn: (value: T) => T): void;
+    subscribe(fn: (value: T) => void): () => void;
+}
+interface ProvideOptions {
+    /** `false`: só quem chamou `provide` altera. Padrão `true`. */
+    writable?: boolean;
+}
+/** `shared`, com `provide` e `batch`. É também o tipo de `ctx.shared`. */
+interface SharedApi {
+    <K extends keyof Shared>(key: K): SharedValue<Shared[K]>;
+    <T = unknown>(key: string): SharedValue<T>;
+    /**
+     * Cria a chave e vira dono dela. Quem chama primeiro é o dono; depois disso,
+     * `provide` só devolve um acesso comum e não grava o valor.
+     */
+    provide<K extends keyof Shared>(key: K, value: Shared[K], options?: ProvideOptions): ProvidedValue<Shared[K]>;
+    provide<T>(key: string, value: T, options?: ProvideOptions): ProvidedValue<T>;
+    /** Várias mudanças, uma notificação por chave no fim. */
+    batch<R>(fn: () => R): R;
+}
+/** Acesso a uma chave compartilhada: `get()`, `set()`, `update()` e `subscribe()`. */
+declare function shared<K extends keyof Shared>(key: K): SharedValue<Shared[K]>;
+declare function shared<T = unknown>(key: string): SharedValue<T>;
+/**
+ * Cria uma chave compartilhada e vira dono dela. Quem chama primeiro é o
+ * dono; depois disso, `provide` só devolve um acesso comum e não grava o valor.
+ */
+declare function provide<K extends keyof Shared>(key: K, value: Shared[K], options?: ProvideOptions): ProvidedValue<Shared[K]>;
+declare function provide<T>(key: string, value: T, options?: ProvideOptions): ProvidedValue<T>;
+/** Várias mudanças, uma notificação por chave no fim. */
+declare function batch<R>(fn: () => R): R;
+
+type Props = Record<string, unknown>;
+/**
+ * Props de cada remote, por nome. `npx vitral types` gera um
+ * `vitral-env.d.ts` que preenche esta interface:
+ *
+ *   declare module 'vitral' { interface Remotes { carrinho: { userId: number } } }
+ */
+interface Remotes {
+}
+/** Props do remote `N`: as declaradas em `Remotes`, ou qualquer objeto. */
+type PropsOf<N extends string> = N extends keyof Remotes ? Remotes[N] : Props;
+/** Restrição extra nas props de um componente de host quando o nome está em `Remotes`. */
+type CheckedProps<N extends string> = N extends keyof Remotes ? {
+    name?: N;
+    props?: Remotes[N];
+} : {
+    name?: N;
+};
+interface RemoteContext {
+    /** Nome com que o host registrou este remote. */
+    name: string;
+    /** URL base de onde o remote foi carregado (útil para assets). */
+    baseUrl: string;
+    /**
+     * Barramento de eventos compartilhado entre host e todos os remotes. As
+     * assinaturas feitas por aqui são canceladas sozinhas no unmount.
+     */
+    events: EventBus;
+    /** Shadow root quando o host pediu isolamento, senão `null`. */
+    shadowRoot: ShadowRoot | null;
+    /**
+     * Onde popovers, menus e dialogs devem ser renderizados (`container` do
+     * Radix e do MUI, `Teleport` do Vue). No Shadow DOM é um elemento dentro do
+     * shadow root, com os estilos e o tema do remote; senão, `document.body`.
+     * Hosts antigos não mandam este campo.
+     */
+    portalContainer?: HTMLElement;
+    /** Avisa o host de um erro em tempo de execução (os adaptadores já chamam). */
+    reportError(error: unknown): void;
+    /** Navega a página inteira (host e todos os roteadores) para `url`. */
+    navigate(url: string, options?: {
+        replace?: boolean;
+    }): void;
+    /**
+     * Versão do protocolo entre cópias da lib que o host fala (hoje 1). Use
+     * para detectar recursos; hosts antigos não mandam este campo.
+     */
+    protocol?: number;
+    /**
+     * Com keep-alive: `fn` roda quando o remote volta para a página. Devolve a
+     * função que cancela. Hosts antigos não mandam este campo.
+     */
+    onActivate?(fn: () => void): () => void;
+    /** Com keep-alive: `fn` roda quando o remote sai da página sem desmontar (pause timers e assinaturas). */
+    onDeactivate?(fn: () => void): () => void;
+    /**
+     * O mesmo `shared` de `import { shared } from 'vitral'`, mas as assinaturas
+     * feitas por aqui são canceladas no unmount, e as chaves criadas com
+     * `ctx.shared.provide` perdem o dono. Vem quando o host usa o store
+     * (`provide`, `shared` ou um hook); senão, importe `shared` de 'vitral'.
+     */
+    shared?: SharedApi;
+}
+interface MountedRemote<P extends Props = Props> {
+    update?(props: P): void;
+    unmount(): void;
+}
+interface RemoteModule<P extends Props = Props> {
+    mount(el: HTMLElement, props: P, ctx: RemoteContext): MountedRemote<P> | Promise<MountedRemote<P>>;
+}
+interface RemoteEntry {
+    /** URL do módulo JS do remote, ou do `vitral.json` gerado pelo plugin. */
+    url?: string;
+    /**
+     * Remote local, sem rede: o próprio módulo ou uma função que o importa
+     * (ex.: `() => import('./carrinho')`). Útil em monorepos e testes.
+     */
+    module?: RemoteModule<any> | (() => Promise<RemoteModule<any> | {
+        default: RemoteModule<any>;
+    }>);
+    /** Hash SRI (`sha256-…`, `sha384-…`, `sha512-…`) do JS. Verificado antes de executar. */
+    integrity?: string;
+    /** CSS extra para carregar junto. */
+    css?: string[];
+    /** Isolamento padrão para este remote. */
+    isolate?: Isolation;
+    /**
+     * O `vitral.json` já baixado (ex.: por `vitral registry`), para não buscá-lo
+     * na hora. Os caminhos dele são relativos a `url`, e os hashes ficam fixos
+     * no host.
+     */
+    manifest?: RemoteManifest;
+    /**
+     * Faixa de versão do contrato do remote que o host aceita (ex.: `'^2'`).
+     * Vence a de `configure`. Veja `VitralConfig.contract`.
+     */
+    contract?: string;
+}
+/**
+ * `none`: CSS com escopo. `shadow`: Shadow DOM. `iframe`: iframe com
+ * `sandbox`, para código de terceiros (precisa de `enableIframe()`).
+ */
+type Isolation = 'shadow' | 'none' | 'iframe';
+/** Estilos do host dentro do Shadow DOM. Sem efeito no modo escopo. */
+interface StyleOptions {
+    /**
+     * CSS do host adotado em cada shadow root antes do CSS do remote (ex.:
+     * `['/assets/base.css']`). Um `CSSStyleSheet` por arquivo, o mesmo em todos.
+     */
+    inherit?: string[];
+    /**
+     * Copia `class` e `data-theme` do `<html>` para a raiz do remote, para
+     * `dark:` e `[data-theme]` funcionarem no Shadow DOM. Padrão `true`.
+     */
+    mirrorTheme?: boolean;
+}
+interface VitralConfig {
+    /** Mapa nome → URL (ou entrada completa), ou a URL de um JSON com esse mapa. */
+    remotes?: Record<string, string | RemoteEntry> | string;
+    /**
+     * Origens de onde é permitido carregar código. Padrão: a própria origem da
+     * página mais as origens das URLs registradas. Use `['*']` para liberar tudo.
+     */
+    allowedOrigins?: string[];
+    /** Tempo máximo para baixar um remote, em ms. Padrão 15000. */
+    timeout?: number;
+    /** Tentativas extras se o download falhar. Padrão 1. */
+    retries?: number;
+    /** Isolamento padrão para todos os remotes. Padrão `'none'`. */
+    isolate?: Isolation;
+    /**
+     * Liga os overrides de desenvolvimento (`?vitral=nome@url` e
+     * `localStorage['vitral:overrides']`) fora de localhost. Em localhost já
+     * valem. Nunca ligue em produção: um link com `?vitral=` executaria código
+     * de qualquer origem.
+     */
+    devOverrides?: boolean;
+    /** Estilos do host no Shadow DOM: `{ inherit: ['/assets/base.css'] }`. */
+    styles?: StyleOptions;
+    /** Recebe o tempo de cada etapa do carregamento (para RUM). */
+    onMetric?: (metric: RemoteMetric) => void;
+    /**
+     * Recebe cada `RemoteError` de qualquer remote (falha de download, de
+     * `mount`, erro de render), uma vez só por erro, além do `onError` de cada
+     * montagem. Use para mandar os erros ao seu monitoramento.
+     */
+    onError?: (error: RemoteError) => void;
+    /**
+     * Atribui a um remote os erros sem tratamento (`error` e
+     * `unhandledrejection` da janela) cujo topo da pilha é um arquivo dele, e
+     * entrega como `RENDER_FAILED` ao `onError`. Padrão `false`.
+     */
+    captureGlobalErrors?: boolean;
+    /**
+     * Dependências que o host oferece aos remotes com `dedupe`, por grupo:
+     * `{ vue: { version: Vue.version, modules: { vue: Vue } } }`. O remote usa
+     * a do host se a versão estiver na faixa dele; senão, a própria cópia.
+     */
+    dedupe?: Record<string, {
+        version: string;
+        modules: SharedModules;
+    }>;
+    /**
+     * Faixa de versão do contrato que o host aceita dos remotes (ex.: `'^2'`).
+     * Antes de executar o remote, o host confere a versão do `contract` do
+     * manifesto e as dependências que ele espera do host; se não servir, o
+     * remote não monta (`CONTRACT_MISMATCH`). Sem contrato no manifesto, nada é
+     * conferido. `'*'` confere só as dependências.
+     */
+    contract?: string;
+}
+/** Módulos de um grupo de `dedupe`, por especificador (`'react-dom/client'`). */
+type SharedModules = Record<string, unknown>;
+/**
+ * Tempo de uma etapa do carregamento de um remote. Cada etapa também vira
+ * `performance.measure('vitral:<nome>:<etapa>')`, visível no painel
+ * Performance do DevTools.
+ */
+interface RemoteMetric {
+    name: string;
+    stage: 'manifest' | 'js' | 'css' | 'mount';
+    /** Início, em ms desde `performance.timeOrigin`. */
+    start: number;
+    duration: number;
+}
+/** Formato do `vitral.json` emitido pelo plugin de build. */
+interface RemoteManifest {
+    name: string;
+    version?: string;
+    entry: string;
+    css?: string[];
+    integrity?: string;
+    /** Escopo usado pelo plugin para prefixar o CSS (`[data-vitral-scope]`). */
+    scope?: string;
+    /**
+     * Componentes e módulos extras do remote (`./MiniCarrinho`, `./api`). Vêm
+     * do mesmo `entry`, no export `exposes`. O host usa `carrinho/MiniCarrinho`.
+     */
+    exposes?: string[];
+    /**
+     * Hash SRI de cada arquivo publicado (CSS e JS do build dividido), pelo
+     * caminho relativo ao manifesto.
+     */
+    files?: Record<string, string>;
+    /**
+     * Build dividido, para navegadores que conferem o hash de cada módulo:
+     * a entrada e os chunks que ela importa logo. `entry` e `integrity`
+     * continuam apontando para o arquivo único, usado por hosts antigos e
+     * quando o navegador não confere o hash por módulo.
+     */
+    split?: {
+        entry: string;
+        chunks?: string[];
+    };
+    /**
+     * Dependências de `dedupe` do build dividido: faixa aceita, versão da
+     * cópia própria e o arquivo dela, para o loader baixar junto com a entrada.
+     */
+    dedupe?: {
+        name: string;
+        range: string;
+        version: string;
+        file: string;
+        chunks?: string[];
+    }[];
+    /** O que o remote declara para o host conferir antes de montar. */
+    contract?: RemoteContract;
+    /**
+     * CSS já preparado no build para o Shadow DOM. Sem este campo (manifestos
+     * antigos), o runtime faz esse trabalho em cada página.
+     */
+    shadow?: ShadowCss;
+}
+/** Contrato do remote no `vitral.json`. */
+interface RemoteContract {
+    /** Versão do contrato (opção `contract.version` do plugin). */
+    version?: string;
+    /** Faixa aceita de cada dependência de `dedupe`, por grupo (`{ react: '^19.0.0' }`). */
+    peers?: Record<string, string>;
+}
+/**
+ * CSS do remote preparado no build para `isolate: 'shadow'`. Os caminhos são
+ * relativos ao primeiro arquivo de `css` (o plugin grava tudo na mesma pasta).
+ */
+interface ShadowCss {
+    /** Cada arquivo de `css`, na mesma ordem, sem `@import`, `@property` e `@font-face`. */
+    css: string[];
+    /** `@property` e `@font-face`, que só valem no documento (vão num `<link>`). */
+    global?: string[];
+    /** `@import` que o build não embutiu (outra origem), adotados antes de `css`. */
+    imports?: string[];
+    /** O CSS ainda tem `url()` relativa, que precisa apontar para o remote. */
+    rebase?: boolean;
+}
+type Handler<T = unknown> = (payload: T) => void;
+interface EventBus {
+    emit<T = unknown>(type: string, payload?: T): void;
+    on<T = unknown>(type: string, handler: Handler<T>): () => void;
+    /** Último valor emitido em `type` (útil para estado como "usuário logado"). */
+    last<T = unknown>(type: string): T | undefined;
+}
+
+export { type CheckedProps as C, type EventBus as E, type Handler as H, type Isolation as I, type MountedRemote as M, type Props as P, type RemoteContext as R, type Shared as S, type VitralConfig as V, type RemoteModule as a, type StyleOptions as b, type RemoteEntry as c, type SharedValue as d, type PropsOf as e, type ProvideOptions as f, type ProvidedValue as g, type RemoteContract as h, type RemoteManifest as i, type RemoteMetric as j, type Remotes as k, type SharedApi as l, type SharedModules as m, type SharedType as n, batch as o, provide as p, shared as s };

package/dist/vite.d.ts

@@ -1,8 +1,40 @@
 import { Plugin } from 'vite';
 
-interface VitralViteOptions {
-    /** Arquivo que exporta o remote (default export de reactRemote/vueRemote/defineRemote). */
-    entry: string;
+interface CssBuildOptions {
+    /**
+     * `'host'`: as variáveis globais do remote (`:root`, `:host`) viram só
+     * fallback. O remote usa o valor do host quando ele existe e o próprio
+     * quando não existe. Para quem não tem um pacote de tokens compartilhado.
+     */
+    theme?: 'host';
+    /**
+     * `'flatten'`: tira os `@layer` do CSS do remote mantendo a ordem. Use quando
+     * o host tem CSS sem camada (Tailwind v3, CSS legado), que no modo escopo
+     * venceria todo o CSS em camada do remote.
+     */
+    layers?: 'flatten';
+    /**
+     * Renomeia as propriedades `--tw-*` registradas com `@property` para
+     * `--tw-<escopo>-*`. Use quando o host tem Tailwind v3 e o remote, v4:
+     * sem isso os gradientes do host quebram.
+     */
+    renameRegisteredProperties?: boolean;
+}
+
+type AdapterName = 'react' | 'vue' | 'svelte' | 'solid' | 'preact' | 'angular' | 'element';
+
+interface VitralViteOptions extends CssBuildOptions {
+    /**
+     * Arquivo cujo `export default` é o remote: um componente do framework ou
+     * um objeto com `mount`. Padrão: `src/remote.*` ou `src/App.*`.
+     */
+    entry?: string;
+    /**
+     * Adaptador que embrulha o `export default`. Padrão: descoberto pelos
+     * plugins do Vite (React, Vue, Svelte, Solid, Preact, Angular; sem nenhum,
+     * Web Component ou função). `false` usa o export como está.
+     */
+    adapter?: AdapterName | false;
     /** Nome do remote no manifesto. Padrão: `name` do package.json. */
     name?: string;
     /** Versão no manifesto. Padrão: `version` do package.json. */
@@ -11,6 +43,7 @@ interface VitralViteOptions {
      * Dependências que NÃO entram no bundle e vêm do import map do host
      * (ex.: ['react', 'react-dom', 'react-dom/client']). Padrão: nenhuma, cada
      * remote leva suas dependências e nunca há conflito de versão.
+     * @deprecated Use `dedupe`, que cai na própria cópia se a versão não servir.
      */
     shared?: string[];
     /**
@@ -18,7 +51,36 @@ interface VitralViteOptions {
      * preflight/tema do Tailwind). Padrão: true.
      */
     scopeCss?: boolean;
+    /**
+     * Outros componentes e módulos do remote, por nome. O host usa
+     * `carrinho/MiniCarrinho` ou `loadModule('carrinho/api')`.
+     *
+     *   exposes: { './MiniCarrinho': 'src/MiniCarrinho.tsx', './api': 'src/api.ts' }
+     *
+     * Um componente exporta `default` com `mount` (`reactRemote(Mini)` etc.).
+     */
+    exposes?: Record<string, string>;
+    /**
+     * Dependências que o remote usa da página, se a versão servir (padrão: `^`
+     * da versão instalada), ou da própria cópia. Ex.: `['react']` (o grupo do
+     * React inteiro) ou `['vue']`.
+     */
+    dedupe?: string[];
+    /**
+     * Publica `vitral.d.ts` com o tipo das props do `export default`, para o
+     * host checar as props (`npx vitral types`). Precisa de TypeScript no
+     * projeto e de entrada .ts/.tsx/.js/.jsx. Padrão: true.
+     */
+    types?: boolean;
+    /**
+     * Contrato publicado no `vitral.json`. O host que declara
+     * `contract: '^2'` só monta o remote se `version` estiver na faixa. As
+     * faixas de `dedupe` entram sozinhas, em `peers`. Padrão: sem versão.
+     */
+    contract?: {
+        version?: string;
+    };
 }
-declare function vitral(options: VitralViteOptions): Plugin;
+declare function vitral(options?: VitralViteOptions): Plugin;
 
 export { type VitralViteOptions, vitral as default, vitral };