Skip to content

app-dashboard ​

Tipo
Referência
Para
Desenvolvedor, Analista

app-dashboard é o formato de cada Dashboard da Aplicação. Ele não tem arquivo próprio: cada Dashboard é um item da lista dashboards: no arquivo da Aplicação, com um header e um body. O que é um Dashboard e como os Widgets se configuram está em Widgets e opções comuns de Widget.

Campos ​

A tabela descreve o Dashboard isolado. No arquivo da Aplicação, o header leva só o id: appId, tenantId, kind e lumo vêm do cabeçalho da Aplicação no push.

  • fileName
    string · opcional · valores: regex ^[a-z0-9-]+--\d+\.yaml$
  • header
    object · obrigatório
  • header.id
    integer · obrigatório · valores: ≥ 0
    A dashboard header id. 0 means "create a new dashboard" on push; a positive value addresses an existing one. Kept separate from #/$defs/id (minimum 1) because 0 is a valid, meaningful value here and nowhere else.
  • header.kind
    string · obrigatório · valores: app-dashboard (fixo)
  • header.lumo
    string · obrigatório · valores: v2 (fixo)
  • header.tenantId
    integer · obrigatório · valores: ≥ 1
  • header.appId
    integer · obrigatório · valores: ≥ 1
  • body
    object · obrigatório
  • body.criado_em
    string ou null · opcional · valores: regex ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$
    Somente leitura: o servidor preenche.
  • body.criado_por
    string ou integer ou null · opcional
    Somente leitura: o servidor preenche.
  • body.publicado_em
    string ou null · opcional · valores: regex ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$
    Somente leitura: o servidor preenche.
  • body.publicado_por
    string ou integer ou null · opcional
    Somente leitura: o servidor preenche.
  • body.nome
    string · obrigatório · valores: não vazio
  • body.slug
    string · opcional · valores: regex ^[a-z0-9]+(-[a-z0-9]+)*$
    Chave da dashboard escrita pelo autor: kebab-case, única no app (vendas-mensais). É como o endereço do erro e o MCP apontam a dashboard.
  • body.ordem
    integer · opcional · valores: ≥ 0
  • body.widget_columns
    integer · opcional · valores: ≥ 1
  • body.widget_float
    boolean · opcional
  • body.version
    integer ou null · opcional · valores: ≥ 0
    Somente leitura: o servidor preenche. Server-managed resource version.
  • body.filters
    array de object ou null · opcional
    Filtros de inicialização desta aba, só relevantes quando o app está em modo 'per_dashboard' (body.filter_mode do app). null (ou chave ausente) = aba nunca configurou filtro próprio - equivale a [] com allow_new_filters liberado, e é o que o CLI emite para toda aba que nunca usou o recurso (o hash de drift descarta chave null, então essa aba não muda de hash entre versões do CLI). Ver shared.schema.json#/$defs/filterDefinition para o contrato de cada item, inclusive value: false como campo declarado vazio.
  • body.filters[].column
    object · obrigatório
  • body.filters[].column.column_id
    string ou integer · obrigatório
    Normalmente inteiro; dado real em circulação às vezes serializa como string numérica (ex.: YAML pré-existente) - aceito nas duas formas.
  • body.filters[].column.expression
    string ou null · opcional
  • body.filters[].operator
    string ou null · opcional
  • body.filters[].value
    qualquer valor · opcional
    false é o marcador de campo declarado vazio (vaga): a aba assume a coluna como filtrável mas sem valor próprio, e herda o que estava aplicado na aba anterior. Qualquer outro valor (inclusive array, para múltipla escolha) é o valor efetivamente aplicado.
  • body.filters[].comparativeValues
    qualquer valor · opcional
  • body.filters[].required
    integer ou null · opcional · valores: 0, 1, 2, 3
    0 = opcional, múltiplos valores (padrão). 1 = obrigatório, um ou mais valores. 2 = obrigatório, valor único. 3 = opcional, valor único.
  • body.filters[].mergeStrategy
    string ou null · opcional
  • body.allow_new_filters
    boolean ou null · opcional
    Se quem usa a aba pode adicionar filtro além da lista declarada em filters. null = herda o padrão (true); só false explícito bloqueia.
  • body.widgets
    array de object · opcional
    Optional: an absent key means a brand-new, still-empty tab (the server defaults it to [] too). Create it, fill in widgets on a later push.
  • body.widgets[].id
    integer · opcional · valores: ≥ 1
  • body.widgets[].guid
    string · opcional · valores: não vazio
    Identificador do widget, dado pelo servidor. Sem slug, é a chave do widget. Não troque à mão.
  • body.widgets[].slug
    string · opcional · valores: regex ^[a-z0-9]+(-[a-z0-9]+)*$
    Chave do widget escrita pelo autor: kebab-case, única na dashboard (faturamento-mes). Widget novo precisa dela; o push casa o widget por id, depois guid, depois slug.
  • body.widgets[].nome
    string · opcional
  • body.widgets[].type
    string · obrigatório · valores: Kpi, Barline, Pie, Table, Matrix, ComposedMatrix, Map, Gauge, Punchcard, Sankey, Forecast, Calendar, ListBox, Text, Diagram, Svelte, ParametricSvelte, App, Funnel, Treemap
  • body.widgets[].display_nome
    boolean · opcional
  • body.widgets[].x
    number · opcional
    Coluna inicial na grade. Ausente: o servidor põe o widget no fim da dashboard, em x 0.
  • body.widgets[].y
    number · opcional
    Linha inicial na grade. Ausente: abaixo do último widget.
  • body.widgets[].w
    number ou null · opcional · valores: > 0
  • body.widgets[].h
    number ou null · opcional · valores: > 0
  • body.widgets[].mobileY
    number · opcional
  • body.widgets[].mobileH
    number · opcional · valores: > 0
  • body.widgets[].mobileVisible
    boolean · opcional
  • body.widgets[].schemaVersion
    integer · opcional · valores: ≥ 1
    Versão do contrato v1 dos widgets. Todo widget que o lumo grava tem esta chave, com a versão que o lumo fala (lumo scaffold widget <Tipo>); o widget inteiro é validado contra o schema do contrato (schemas/widget-contract/widget.schema.json). Ausente só no widget selado (sealed). Não troque à mão.
  • body.widgets[].sealed
    array de string · opcional
    Widget selado: o servidor não o converte para o contrato v1 sem perder algo, e estes são os motivos. Escrito pelo servidor. O chart fica guardado lá e volta intacto no push; aqui só nome e posição mudam. Para mudar o conteúdo, troque o widget por um no contrato v1 com o mesmo id, ou edite no app.
  • body.widgets[].chart
    object · opcional

Exemplo ​

Um item da lista dashboards: da Aplicação, com a indentação tirada. No arquivo, ele vem precedido de - sob dashboards:.

yaml
header:
  id: 9101                 # Dashboard que já existe: mantenha o id que veio do pull
                           # 0 = criar um Dashboard novo no próximo push
body:
  nome: Visão geral
  ordem: 0                 # ordem da aba: o menor vem primeiro
  widget_columns: 12       # grade de 12, 24, 36 ou 60 colunas
  widgets:
    - nome: Faturamento
      type: Kpi
      w: 3                 # largura, em colunas da grade
      h: 1                 # altura, em linhas da grade: veja Posição e tamanho
      x: 0
      y: 0
      chart:
        primaryData:
          dataSource: "70011:SUM"   # <id da coluna>:<agregação>, de lumo info app:<id> --full
          title:
            value: Faturamento
          filter: []

lumo scaffold widget <tipo> mostra a configuração de cada tipo de Widget (Kpi, Barline, Pie, Table, Matrix e os outros), comentada. Para conferir o resultado, lumo app dashboard-preview app:<id> devolve os dados de cada Widget e lumo app export app:<id> gera a imagem.

Posição e tamanho ​

w conta colunas da grade de widget_columns, e h conta linhas. A linha não tem altura fixa: no computador, ela mede 0,9 da largura de uma coluna. Por isso o mesmo h fica mais baixo quanto mais colunas a Dashboard tem, e um KPI com h: 1 numa grade de 12 tem a mesma altura de um com h: 2 numa grade de 24. O celular tem posição própria, em mobileY, mobileH e mobileVisible.

Alturas medidas nos Widgets dos Dashboards publicados. A porcentagem é a parcela dos Widgets daquele tipo que usa aquela altura:

widget_columnsKpiListBoxTable, Matrix, Barline
12h: 1 (77%), h: 2h: 2 a h: 3h: 3 a h: 5
24h: 2 (99%)sem amostrah: 6 a h: 8
60h: 3 (94%)h: 7 a h: 10h: 13 a h: 16

Widgets da mesma linha ficam com o mesmo h: a grade empilha pela coordenada y, e alturas diferentes na mesma linha abrem buracos.

Limites ​

  • O push substitui a lista inteira. Um Dashboard que está no servidor e falta em dashboards: é apagado. Um Dashboard reescrito sem o header.id é recriado com outro id, o que quebra lumo app export --dashboard <id> e as Apresentações que apontam para ele.
  • A ordem das abas vem de ordem, não da posição no array.
  • filters e allow_new_filters de cada Dashboard só valem quando a Aplicação tem filter_mode: per_dashboard.
  • No Widget Kpi, o filtro fica em filter, no singular. filters não é lido.
  • Uma aba sem widgets é válida: nasce vazia e recebe Widgets num push seguinte.
  • Numa Aplicação publicada, mudar Widgets, nomes ou abas pede clone. Só filters e allow_new_filters de cada Dashboard passam direto.