@horizon-js/web-nextjs

Frontend core do Horizon — pacote multi-subpath. Consolida tudo que é genérico do frontend Next.js: hooks, motor de query, capabilities, navegação, UI kit, platform core.

Antes da versão 2.4.0 este pacote era apenas documentação. A partir de 2.4.0 virou runtime + docs.

Subpaths

// Motor de query de listas (enricher, URL parser, factory, facets)
import { createListContext, SearchStateEnricher, UrlStateSerializer } from "@horizon-js/web-nextjs/frontend-query-engine"

Roadmap de subpaths (adicionados conforme FASE D+ do projetão):

| Subpath | Status | O que contém | |---|---|---| | /frontend-query-engine | ✅ 2.4.0 | Factory, state-to-request, state-to-url, request-options | | /hooks | pendente | useGetOnScreen, useScrollLock, useGetDeviceSizeName, useGetScrollDirection | | /platform-core | pendente | Registry de módulos, tipos da plataforma | | /capabilities/mkt-scripts | pendente | GTM, GA, Facebook Pixel | | /capabilities/contacts | pendente | WhatsApp button, redes sociais | | /capabilities/seo | pendente | Meta tags, JSON-LD helpers |

frontend-query-engine

Motor de query de listas. Submódulo principal até agora.

import {
  createListContext,
  SearchStateEnricher,
  UrlStateSerializer,
  buildRequestOptionsGenerator,
  FieldsResolver,
  RangeIdentifier,
  type ListSchema,
  type EnrichedRequest
} from '@horizon-js/web-nextjs/frontend-query-engine'

Organização interna

frontend-query-engine/
├── factory/           → createListContext (context React de listagem)
├── state-to-request/  → SearchStateEnricher (estado → request da API)
├── state-to-url/      → UrlStateSerializer (estado ↔ querystring)
└── request-options/   → buildRequestOptionsGenerator (config de facets)

Para documentação detalhada da arquitetura interna ver src/frontend-query-engine/.

Origem

Este módulo foi extraído de 4 libs locais do projeto GHI-7661 (Horizon 2.3) em 2026-04-22:

• list-context-factory → factory/
• list-context-state-to-request-enricher → state-to-request/
• list-context-state-to-url-parser → state-to-url/
• list-context-request-options-generator → request-options/

O código foi inicialmente publicado como @horizon-js/[email protected] standalone (desvio da arquitetura planejada). Corrigido em 2026-04-22 movendo pra subpath deste pacote, conforme o projetão documentado em Inteligência Imobland/02 - Projetos e ideias/Horizon 2.3/reorganizacao-pacotes-npm/.

Filosofia atual vs futura

A filosofia atual do frontend-query-engine é list-context v4 (factory pattern com handlers plugáveis). Está planejada migração pra TanStack Query + Zustand + contratos universais (QueryRequest/QueryResponse) — ver doc 05-FRONTEND-QUERY-ENGINE.md do projetão.

Essa migração vai acontecer em releases futuras:

• 2.4.x — mantém filosofia atual, apenas consolida o código aqui
• 2.5.0 — adiciona contratos universais (QueryRequest, QueryResponse) + adapter pattern
• 2.6.0+ — adiciona TanStack hooks (useListInfinite, useListMap, useListFacets, useListPreview)
• 3.0.0 — depreca list-context v4 (factory pattern), filosofia totalmente TanStack+Zustand

Consumidores em 2.4.x seguirão funcionando ao atualizar pra 3.0.0 via migration guide.

Peer dependencies

• react >= 18.0.0 (opcional — só requerido pelo factory/ submódulo)

Documentação

• docs/ARQUITETURA_MODULOS_WEB.md
• docs/CAPABILITIES.md
• docs/HOOKS_REGISTRY.md
• docs/NAVEGACAO_DINAMICA.md
• docs/UI_KIT_COMPLETO.md
• docs/COMPONENTES_GLOBAIS_UI.md
• docs/ISR_CACHE_INVALIDATION.md — padrão canônico de cache ISR + invalidação on-demand (agnóstico a módulo)
• CHANGELOG.md