@seedgrid/fe-components 2026.9.5 → 2026.10.1

package/dist/realtime/SgRealtimeProvider.js

@@ -0,0 +1,170 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from "react";
+import { PulseSubscriberClient } from "@seedgrid/pulse-subscriber-react/core";
+const SgRealtimeContext = React.createContext(null);
+const DEFAULT_TOKEN_ENDPOINT = "/api/realtime/connect";
+function mapState(state) {
+    switch (state) {
+        case "connected":
+        case "subscribed":
+            return "connected";
+        case "connecting":
+            return "connecting";
+        case "reconnecting":
+            return "reconnecting";
+        case "auth-error":
+            return "auth-error";
+        case "idle":
+            return "idle";
+        default:
+            return "unavailable";
+    }
+}
+async function requestToken(endpoint, init) {
+    const response = await fetch(endpoint, { method: "POST", credentials: "same-origin", ...init });
+    if (!response.ok) {
+        throw new Error(`token de realtime indisponivel (HTTP ${response.status})`);
+    }
+    return (await response.json());
+}
+/**
+ * Avisos em tempo real para o usuário logado, pelo SeedGrid Pulse.
+ *
+ * Monte uma vez (no layout) e ouça com {@link useSgRealtimeEvent}. Pede o token de conexão ao backend
+ * (que o emite para o usuário DA SESSÃO), conecta direto no Pulse, reconecta sozinho e para se a
+ * credencial for revogada. O token fica só em memória. Quando o realtime não está conectado,
+ * {@link useSgRealtimeStatus} diz isso e a tela volta ao polling.
+ */
+export function SgRealtimeProvider({ children, channels, tokenEndpoint = DEFAULT_TOKEN_ENDPOINT, tokenRequestInit, fetchToken, pulseUrl, enabled = true, connectOptions }) {
+    const [status, setStatus] = React.useState("idle");
+    const listenersRef = React.useRef(new Set());
+    // Lidos sempre o mais recente, sem reconectar a cada render.
+    const optionsRef = React.useRef({ tokenEndpoint, tokenRequestInit, fetchToken, connectOptions });
+    optionsRef.current = { tokenEndpoint, tokenRequestInit, fetchToken, connectOptions };
+    const channelsKey = channels.join(",");
+    React.useEffect(() => {
+        if (typeof window === "undefined" || !enabled || channelsKey.length === 0) {
+            setStatus(enabled ? "idle" : "disabled");
+            return undefined;
+        }
+        let cancelled = false;
+        const client = new PulseSubscriberClient();
+        const getConnectResponse = () => {
+            const { tokenEndpoint: endpoint, tokenRequestInit: init, fetchToken: custom } = optionsRef.current;
+            return custom ? custom() : requestToken(endpoint, init);
+        };
+        const offState = client.onStateChange((state) => {
+            if (!cancelled)
+                setStatus(mapState(state));
+        });
+        const offMessage = client.onMessage((message) => {
+            const event = {
+                channel: message.channel,
+                event: message.event,
+                data: message.data,
+                messageId: message.messageId,
+                publishedAt: message.publishedAt
+            };
+            listenersRef.current.forEach((listener) => {
+                try {
+                    listener(event);
+                }
+                catch {
+                    // Um handler com defeito não derruba os outros.
+                }
+            });
+        });
+        void (async () => {
+            setStatus("connecting");
+            let first;
+            try {
+                first = await getConnectResponse();
+            }
+            catch {
+                if (!cancelled)
+                    setStatus("unavailable");
+                return;
+            }
+            if (cancelled)
+                return;
+            if (!first.enabled || !first.token) {
+                setStatus("disabled");
+                return;
+            }
+            // O primeiro token já está em mãos; as reconexões pedem um novo (ele vale só para entrar).
+            let pending = first;
+            const getToken = async () => {
+                const response = pending ?? (await getConnectResponse());
+                pending = null;
+                if (!response.enabled || !response.token) {
+                    throw new Error("realtime desligado");
+                }
+                return { token: response.token, expiresAt: response.expiresAt, connectUrl: response.connectUrl };
+            };
+            try {
+                await client.connect({
+                    ...optionsRef.current.connectOptions,
+                    getToken,
+                    ...(pulseUrl ? { baseUrl: pulseUrl } : {})
+                });
+                if (cancelled)
+                    return;
+                await client.subscribe({ channels: channelsKey.split(",") });
+            }
+            catch {
+                // O estado já reflete a falha (onStateChange); a tela fica no polling.
+            }
+        })();
+        return () => {
+            cancelled = true;
+            offState();
+            offMessage();
+            void client.disconnect().catch(() => undefined);
+        };
+    }, [enabled, channelsKey, pulseUrl]);
+    const addListener = React.useCallback((listener) => {
+        listenersRef.current.add(listener);
+        return () => {
+            listenersRef.current.delete(listener);
+        };
+    }, []);
+    const value = React.useMemo(() => ({ status, addListener }), [status, addListener]);
+    return _jsx(SgRealtimeContext.Provider, { value: value, children: children });
+}
+/** `backup.finished.*` casa `backup.finished.success` e `backup.finished.error`. */
+export function matchesSgRealtimeEvent(pattern, event) {
+    if (pattern === "*" || pattern === event)
+        return true;
+    if (pattern.endsWith(".*")) {
+        const prefix = pattern.slice(0, -1);
+        return event.startsWith(prefix);
+    }
+    return false;
+}
+/**
+ * Chama `handler` a cada aviso do `channel` cujo nome casa `events` (aceita `prefixo.*`). Fora de um
+ * {@link SgRealtimeProvider}, não faz nada.
+ */
+export function useSgRealtimeEvent(channel, events, handler) {
+    const context = React.useContext(SgRealtimeContext);
+    const handlerRef = React.useRef(handler);
+    handlerRef.current = handler;
+    const patterns = Array.isArray(events) ? events.join("|") : events;
+    React.useEffect(() => {
+        if (!context)
+            return undefined;
+        const list = patterns.split("|");
+        return context.addListener((event) => {
+            if (event.channel === channel && list.some((pattern) => matchesSgRealtimeEvent(pattern, event.event))) {
+                handlerRef.current(event);
+            }
+        });
+    }, [context, channel, patterns]);
+}
+/** Estado do realtime. `connected` falso ⇒ a tela usa o polling de reserva. */
+export function useSgRealtimeStatus() {
+    const context = React.useContext(SgRealtimeContext);
+    const status = context?.status ?? "disabled";
+    return { status, connected: status === "connected" };
+}

package/dist/realtime/SgRealtimeProvider.meta.d.ts

@@ -0,0 +1,4 @@
+import type { SgAiHintsV0, SgMetaV0 } from "../ai-meta/types";
+export declare const sgMeta: SgMetaV0;
+export declare const aiHints: SgAiHintsV0;
+//# sourceMappingURL=SgRealtimeProvider.meta.d.ts.map

package/dist/realtime/SgRealtimeProvider.meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SgRealtimeProvider.meta.d.ts","sourceRoot":"","sources":["../../src/realtime/SgRealtimeProvider.meta.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE9D,eAAO,MAAM,MAAM,EAAE,QAgCpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAiBrB,CAAC"}

package/dist/realtime/SgRealtimeProvider.meta.js

@@ -0,0 +1,50 @@
+export const sgMeta = {
+    version: "0.1",
+    componentId: "provider.realtime",
+    package: "@seedgrid/fe-components",
+    exportName: "SgRealtimeProvider",
+    slug: "sg-realtime-provider",
+    displayName: "SgRealtimeProvider",
+    category: "provider",
+    subcategory: "realtime",
+    description: "Avisos em tempo real para o usuario logado pelo SeedGrid Pulse: pede o token de conexao ao backend (que o emite para o usuario da sessao), conecta direto no Pulse, reconecta sozinho, para quando a credencial e revogada e expoe o status para a tela decidir entre aviso e polling de reserva.",
+    tags: ["provider", "realtime", "pulse", "websocket", "notification", "polling"],
+    capabilities: ["token-from-backend", "auto-reconnect", "channel-subscription", "fallback-status"],
+    fieldSemantics: ["realtimeChannels", "tokenEndpoint", "connectionStatus"],
+    props: [
+        { name: "channels", type: "string[]", required: true, description: "Channels que a aplicacao quer ouvir (ex.: [\"backup\"]).", semanticRole: "data", bindable: true },
+        { name: "tokenEndpoint", type: "string", default: "/api/realtime/connect", description: "Rota que entrega o token de conexao do usuario logado (a BFF, na mesma origem).", semanticRole: "behavior", bindable: true },
+        { name: "enabled", type: "boolean", default: true, description: "Liga/desliga (ex.: false enquanto nao ha usuario logado).", semanticRole: "behavior", bindable: true },
+        { name: "children", type: "ReactNode", required: true, description: "Arvore que ouve os avisos com useSgRealtimeEvent.", semanticRole: "data", bindable: false }
+    ],
+    states: ["idle", "disabled", "connecting", "connected", "reconnecting", "unavailable", "auth-error"],
+    examples: [
+        { id: "simulador", title: "Simulador", file: "apps/showcase/src/app/components/providers/sg-realtime-provider/samples/simulador.tsx.sample", kind: "sample" },
+        { id: "layout-com-bff", title: "No layout, com a BFF", file: "apps/showcase/src/app/components/providers/sg-realtime-provider/samples/layout-com-bff.tsx.sample", kind: "sample" },
+        { id: "polling-de-reserva", title: "Polling de reserva", file: "apps/showcase/src/app/components/providers/sg-realtime-provider/samples/polling-de-reserva.tsx.sample", kind: "sample" }
+    ],
+    showcase: { route: "/components/providers/sg-realtime-provider", hasPlayground: true, hasPropsTable: true },
+    sdui: {
+        rendererType: "provider.realtime",
+        acceptsDataBinding: true,
+        defaultProps: { channels: [], tokenEndpoint: "/api/realtime/connect", enabled: true }
+    }
+};
+export const aiHints = {
+    version: "0.1",
+    preferredUseCases: [
+        "Avisar o usuario quando um processo demorado termina (backup, relatorio, importacao) sem polling.",
+        "Atualizar uma lista quando o backend publica um evento para o usuario logado."
+    ],
+    avoidUseCases: [
+        "Transportar dados de negocio: o aviso so leva identificadores; busque o registro pela API.",
+        "Mensagens entre usuarios ou chat."
+    ],
+    synonyms: ["realtime provider", "pulse provider", "websocket provider", "push notifications"],
+    relatedEntityFields: ["channel", "event", "userPublicId"],
+    compositionHints: [
+        "Montar uma vez no layout autenticado e ouvir com useSgRealtimeEvent nas telas.",
+        "Usar useSgRealtimeStatus para ligar o polling de reserva quando nao estiver conectado."
+    ],
+    rankingSignals: { freeText: 0, structuredChoice: 0, date: 0, number: 0, denseLayout: 0 }
+};

package/dist/realtime/useSgRealtimeEvent.meta.d.ts

@@ -0,0 +1,4 @@
+import type { SgAiHintsV0, SgMetaV0 } from "../ai-meta/types";
+export declare const sgMeta: SgMetaV0;
+export declare const aiHints: SgAiHintsV0;
+//# sourceMappingURL=useSgRealtimeEvent.meta.d.ts.map

package/dist/realtime/useSgRealtimeEvent.meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSgRealtimeEvent.meta.d.ts","sourceRoot":"","sources":["../../src/realtime/useSgRealtimeEvent.meta.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE9D,eAAO,MAAM,MAAM,EAAE,QAwBpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAQrB,CAAC"}

package/dist/realtime/useSgRealtimeEvent.meta.js

@@ -0,0 +1,33 @@
+export const sgMeta = {
+    version: "0.1",
+    componentId: "hook.realtime-event",
+    package: "@seedgrid/fe-components",
+    exportName: "useSgRealtimeEvent",
+    slug: "use-sg-realtime-event",
+    displayName: "useSgRealtimeEvent",
+    category: "hook",
+    subcategory: "realtime",
+    description: "Hook que chama o handler a cada aviso do SgRealtimeProvider no channel informado cujo evento casa o padrao (nome, lista, prefixo.* ou *).",
+    tags: ["hook", "realtime", "pulse", "event"],
+    capabilities: ["event-subscription", "wildcard-match"],
+    fieldSemantics: ["realtimeChannel", "eventPattern", "eventHandler"],
+    props: [
+        { name: "channel", type: "string", required: true, description: "Channel do aviso (ex.: \"backup\").", semanticRole: "data", bindable: false },
+        { name: "events", type: "string | string[]", required: true, description: "Nome do evento, lista, \"prefixo.*\" ou \"*\".", semanticRole: "data", bindable: false },
+        { name: "handler", type: "(event: SgRealtimeEvent) => void", required: true, description: "Chamado a cada aviso que casa.", semanticRole: "behavior", bindable: false }
+    ],
+    states: ["listening"],
+    examples: [
+        { id: "uso-basico", title: "Uso basico", file: "apps/showcase/src/app/components/hooks/use-sg-realtime-event/samples/uso-basico.tsx.sample", kind: "sample" }
+    ],
+    showcase: { route: "/components/hooks/use-sg-realtime-event", hasPlayground: true, hasPropsTable: true }
+};
+export const aiHints = {
+    version: "0.1",
+    preferredUseCases: ["Recarregar uma tela quando o backend avisa que um processo terminou."],
+    avoidUseCases: ["Ler dados de negocio do aviso: ele so traz identificadores."],
+    synonyms: ["realtime event", "pulse event", "on notice"],
+    relatedEntityFields: ["channel", "event"],
+    compositionHints: ["Usar dentro de um SgRealtimeProvider que assina o channel."],
+    rankingSignals: { freeText: 0, structuredChoice: 0, date: 0, number: 0, denseLayout: 0 }
+};

package/dist/realtime/useSgRealtimeStatus.meta.d.ts

@@ -0,0 +1,4 @@
+import type { SgAiHintsV0, SgMetaV0 } from "../ai-meta/types";
+export declare const sgMeta: SgMetaV0;
+export declare const aiHints: SgAiHintsV0;
+//# sourceMappingURL=useSgRealtimeStatus.meta.d.ts.map

package/dist/realtime/useSgRealtimeStatus.meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSgRealtimeStatus.meta.d.ts","sourceRoot":"","sources":["../../src/realtime/useSgRealtimeStatus.meta.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE9D,eAAO,MAAM,MAAM,EAAE,QAuBpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAQrB,CAAC"}

package/dist/realtime/useSgRealtimeStatus.meta.js

@@ -0,0 +1,32 @@
+export const sgMeta = {
+    version: "0.1",
+    componentId: "hook.realtime-status",
+    package: "@seedgrid/fe-components",
+    exportName: "useSgRealtimeStatus",
+    slug: "use-sg-realtime-status",
+    displayName: "useSgRealtimeStatus",
+    category: "hook",
+    subcategory: "realtime",
+    description: "Hook com o estado da conexao do SgRealtimeProvider com o Pulse. connected falso indica que a tela deve usar o polling de reserva.",
+    tags: ["hook", "realtime", "pulse", "status", "polling"],
+    capabilities: ["connection-status", "fallback-signal"],
+    fieldSemantics: ["connectionStatus", "connected"],
+    props: [
+        { name: "returns.status", type: "SgRealtimeStatus", description: "idle, disabled, connecting, connected, reconnecting, unavailable ou auth-error.", semanticRole: "data", bindable: false },
+        { name: "returns.connected", type: "boolean", description: "true so com a conexao aberta e assinada.", semanticRole: "data", bindable: false }
+    ],
+    states: ["disabled", "connected", "unavailable"],
+    examples: [
+        { id: "uso-basico", title: "Uso basico", file: "apps/showcase/src/app/components/hooks/use-sg-realtime-status/samples/uso-basico.tsx.sample", kind: "sample" }
+    ],
+    showcase: { route: "/components/hooks/use-sg-realtime-status", hasPlayground: true, hasPropsTable: true }
+};
+export const aiHints = {
+    version: "0.1",
+    preferredUseCases: ["Decidir entre aviso em tempo real e polling de reserva numa tela."],
+    avoidUseCases: ["Decidir permissao ou autenticacao: o status so diz da conexao com o Pulse."],
+    synonyms: ["realtime status", "pulse status", "connection state"],
+    relatedEntityFields: ["status"],
+    compositionHints: ["Usar dentro de um SgRealtimeProvider; fora dele o status e disabled."],
+    rankingSignals: { freeText: 0, structuredChoice: 0, date: 0, number: 0, denseLayout: 0 }
+};