com a popularidade crescente do TypeScript, acho que isso precisa acontecer. Muitos outros pacotes js estão começando a incluir suas próprias tipificações (oficiais) agora. Em vez de deixar isso para a comunidade DefinitelyTyped

Isso é algo que estamos considerando. Deve ser possível fazer um script de nó para gerá-lo automaticamente a partir de nosso despejo de API .

+1 👍 de mim também. O repositório DefinitelyTyped está desatualizado, onde após Highcharts v4.2.x apenas propriedades esporádicas e incidentais foram atualizadas. Mas a maioria das mudanças em Highcarts simplesmente não são processadas.

Portanto, o repositório DefinitelyTyped deve ser atualizado ou - mais conveniente - tê-lo agrupado com Highcharts seria uma solução muito melhor.

Tê-lo gerado automaticamente parece uma ótima opção, mas isso ainda pode exigir trabalho manual por parte de escrever testes para o arquivo .d.ts? Além disso, fazer com que seja gerado automaticamente pode ser.

Eu estaria disposto a fazer algum trabalho para atualizar o repositório DefinitelyTyped para a versão atual e fazer um PR em https://github.com/highcharts/highcharts se quiser incluir o arquivo do manual lá?

/ cc @ ry8806 @TorsteinHonsi

^ Criei um PR para o repositório DefinitelyTyped que

Ter definições de tipo TypeScript oficiais seria muito apreciado. Ajuda muito ao digitar uma configuração de gráfico.

Aqui estamos novamente com as definições de tipo, uma versão principal por trás da realidade. : /

Dada a complexidade desta biblioteca, acho que a melhor solução é gerar as defs de tipo a partir do "despejo de API" a que @TorsteinHonsi se referiu. No entanto, esse link parece estar quebrado. Existe um novo? Eu estaria disposto a tentar escrever um gerador.

No entanto, esse link parece estar quebrado. Existe um novo?

Sim, o novo está disponível em https://api.highcharts.com/highcharts/tree.json. Esta árvore é gerada a partir de nossos comentários JSDoc e código-fonte analisado.

@cvasseng FYI.

@TorsteinHonsi Obrigado, vou dar uma olhada nisso. Você está usando um tipo específico de "jsdoc" (Google Closure, JSDoc 3?) O despejo JSON acontece em algum lugar neste código-base que posso consultar como referência? A razão pela qual pergunto é porque existem conversores JSDoc-para-TSDef que podem funcionar ...

Estamos usando JSDoc 3, mas amplamente estendido para poder descrever nossa estrutura de opções declarativas.

@TorsteinHonsi Olhando para o JSON, tenho algumas perguntas ... por acaso você não tem uma documentação de esquema neste formato? Isso é o que eu coletei . Como você designa opções que são passadas para Highcharts.setOptions() vs Highcharts.chart() (por exemplo)? Existe um despejo de API para as classes e namespaces também?

@cvasseng

Olá @aaronbeall , não temos nenhuma documentação completa sobre o esquema no momento, mas parece que você tem tudo em sua definição.

As opções para Highcharts.setOptions() e as séries são tratadas como casos especiais fora do próprio esquema onde o usamos, mas devemos alterar pelo menos global e lang para serem fora da estrutura de opções principais.

Como uma observação lateral, o formato de despejo antigo estava disponível em https://api.highcharts.com/dump.json , agora o movemos de volta para a posição original em https://api.highcharts.com/highcharts/ opção / dump.json.

Obrigado @cvasseng. Estou começando a mexer nisso ... há muitos dados, tenho um trabalho cortado só para entender tudo. :) Notei que alguns campos não têm tipo e nenhum padrão para inferir o tipo, como boost.seriesThreshold , mas o tipo aparece nos documentos . Eles são tratados como um caso especial ou estou faltando alguma coisa? Além disso, existe algum esquema de API para os namespaces / classes ou isso é tratado separadamente? O modelo declarativo pretende torná-los obsoletos?

(Terei mais perguntas, há um lugar melhor para discutir isso? Gitter? Estou bem aqui, mas provavelmente está criando um pouco de barulho para algumas pessoas.)

O tipo de boost.seriesThreshold realmente parece estar errado em tree.json (e nos documentos ao vivo) - supõe-se que seja um número, não uma string. Olhando para o doclet real a partir do qual foi gerado, o tipo está faltando nele. É provável que isso aconteça em qualquer outro lugar onde também faltem tipos. Estamos trabalhando para adicionar mais testes e verificações à passagem de geração para encontrá-los automaticamente quando os doclets mudarem para evitar que isso aconteça.

Não temos um esquema para namespaces / classes, mas eles são controlados pelo vanilla JSDoc 3, portanto, pode ser possível adicionar um plugin existente para gerar automaticamente definições de typescript para eles. A configuração dessa parte pode ser encontrada aqui: https://github.com/highcharts/highcharts-docstrap

E discutir isso aqui funciona muito bem. :) Assim teremos um logradouro central para ele, para que outros também possam acompanhá-lo.

Caso seja útil, este é um despejo de todos os campos (em highcharts / tree.json) que não parecem ter um tipo. Uma rápida verificação dos tipos inferidos de valores padrão (string, número, booleano) parece correto para mim, mas aqueles que dizem "Incapaz de determinar o tipo" significam que eu não encontrei uma propriedade type ou default propriedade, portanto, é atribuída a any . Eu poderia escrever um arquivo de patch para esses tipos, ou existe uma maneira melhor?

Também há uma chave em branco no JSON de nível superior e em mapNavigation.buttons .

Fiz algum progresso nisso hoje, você pode ver o que está sendo gerado aqui . Ainda há muito trabalho para fazer isso de alta qualidade. Vou enviar um repo amanhã. Em um nível alto, alguns problemas que encontrei:

• Não tenho certeza de como organizar a saída. No momento, existem 559 símbolos, que incluem coisas importantes como Highcharts.Options e Series até pequenos objetos muito específicos como PlotOptionsBbTopLine . Para evitar conflitos de nome, ele converte o nome completo em PascalCase, ex de plotOptions.bb.topLine . Ainda estou tentando descobrir como fazer isso melhor. Tentar comparar com os @types/highcharts atuais é um pouco difícil, na maioria das vezes as coisas simplesmente não existem lá.
• Não tenho certeza se entendo a relação de highcharts / highstocks / highmaps. (Eu só usei Highcharts pessoalmente.) O despejo de API contém todos os dados de todos os produtos? Como deve ser dividido? Terei que entender melhor como realmente usar highstock e highmaps em um projeto ...
• A maneira como os objetos se estendem faz todo o sentido, mas estou tendo dificuldade em descobrir como convertê-los em tipos sensíveis. No momento, os objetos são mesclados usando & tipos de interseção porque extends estava gerando muitos erros sobre extensão incompatível. Atualmente não há manipulação de excludes , comecei a brincar com o tipo Omit mas isso gerou muitos erros sobre campos omitidos não existentes no tipo. Acho que isso ocorre porque, em alguns casos, uma propriedade do objeto herda indiretamente do pai, então, na verdade, não tem os campos que deveriam ser omitidos, a propriedade do objeto pai tem. plotOptions.mfi.params é um exemplo disso, ele exclui index mas não tem uma index propriedade ou extends um objeto que tem, mas o pai plotOptions.mfi estende plotOptions.sma que tem uma propriedade filha plotOptions.sma.params que tem index que é mesclada no pai com plotOptions.mfi.params . Sim, ainda pensando em como lidar com isso. :) Parece que preciso avaliar a árvore totalmente mesclada e descobrir os tipos a partir daí ...
• Muitos tipos genéricos de Array , Object e Function ... provavelmente todos bem documentados nas descrições, mas não parecem estar expressos nos tipos. Talvez alguma correção criteriosa dos dados de tipo conserte isso. Meu favorito é Array.<Array.<Mixed>> - não tenho ideia do que seja ainda. :)

Algumas outras coisas específicas:

• Quais são os tipos Color , CSSObject e Mixed ? Color parece ser um string , CSSObject formatado é um objeto de estilo padrão ou algo especial?
• series.bellcurve.data e series.histogram.data se estendem, criando referências circulares. Eu acho que isso é apenas um erro de digitação, eles provavelmente se destinam a estender algo mais?

Além disso, alguns dos seus tipos ausentes não estão ausentes na API, por exemplo https://api.highcharts.com/highstock/plotOptions.bb.topLine.styles.lineColor. Se bem me lembro, nós digitamos adivinhação no gerador api-docs , mas isso poderia ser movido para o script highcharts.jsdoc.js para que fosse parte de tree.json.

@cvasseng Qual é o status em nossas definições oficiais do TypeScript?

Carregou um repositório para brincar com isso , mas sem adições hoje.

Se bem me lembro, nós digitamos adivinhação no gerador api-docs

Eu ficaria curioso para entender como funciona o gerador api-docs . Ele faz um bom trabalho ao entender o dump da API. Estou encontrando coisas com as quais não tenho certeza de como lidar. Por exemplo series.bullet.data.targetOptions extends series.bullet.targetOptions , mas uma definição para series.bullet.targetOptions não existe ... no entanto, as propriedades aparecem nos documentos muito bem. Eu acho que é porque series.bullet estende plotOptions.bullet que tem plotOptions.bullet.targetOptions , então series.bullet.targetOptions resolve plotOptions.bullet.targetOptions ?

Edit: Pequeno progresso esta noite, minha verificação verdadeira para o valor padrão estava descartando todos os valores false literais, consertou isso e muito mais coisas são inferidas como um booleano. No entanto, não tenho certeza se booleano é o tipo correto para inferir em alguns lugares. Eu também verifico values para tipos literais (essa informação é excelente de se ter!). De qualquer forma, o despejo de tipos ausentes é atualizado.

Fez algum progresso depois de pensar sobre como a árvore estende objetos:

• Veio com um método para resolver todos os defs que são mesclados em um determinado caminho . (Isso esticou meu cérebro ... imagino que o gerador de documentos faça algo assim?)
• Em seguida, reduzo a árvore inteira removendo defs redundantes em caminhos que sombreiam outros defs mesclados de outras partes da árvore, o que remove cerca de 100 defs de objetos redundantes e centenas de propriedades redundantes. (Muitos desses defs "redundantes" pareciam estar lá para fornecer adições de documentos, como descrição ou valores padrão, mas não ajudaram o tipo defs ... parece certo?)
• Depois disso, apenas alguns defs na árvore reduzida estavam realmente ausentes de tipos que não podem ser inferidos, que eu remendo aqui (essas alterações provavelmente seriam boas no próprio jsdoc). O que resta pode ser inferido ( consulte o último despejo de "tipos ausentes" ), embora eu não tenha validado se o tipo inferido está sempre correto. Ainda há o problema de tipos vagos como object , array e function .
• Aqui está um dump de como a árvore def é alterada antes de gerar defs do tipo TS. Isso nos dá essa saída gerada que está começando a parecer promissora.

Qual é o próximo

• Lide com campos excluídos, que acho que tenho uma estratégia usando Omit<> e fazendo um passe para adicionar extends explícito a todos os objetos que têm excludes (usando o método mencionado no primeiro marcador) e voltando a usar interfaces com todas as propriedades opcionais. Acho que isso vai funcionar, desde que possamos ter certeza de que todas as propriedades serão opcionais. Existem propriedades obrigatórias?
• Alguns outros detalhes : melhorias de tipo, limpeza e testes
• Vou pegar de volta depois das férias. Adoraria qualquer feedback se vocês acham que isso está indo na direção certa ou não.

Perguntas

• O que significa "memberof": "yaxis" em tooltipValueFormat doclet?
• Um dos context valores é PlotLineOrBand mas não vejo isso nos documentos das classes, é uma subclasse de Series ?
• plotOptions.series.states tem o nome do tipo doclet "plotOptions.series.states" - isso significa algo especial?

@aaronbeall você tem algum progresso? Eu também mergulhei um pouco na geração de tipos para gráficos altos.

Uma grande falha é que o tree.json gerado não contém todas as digitações de highcharts, como métodos estáticos no namespace highcharts. Existem 703 símbolos após a remoção de símbolos válidos. Mas depois disso, os símbolos de saída dentro de tree.json são cerca de 100. Muitos deles são ignorados.

@ scott-ho Já passou um pouco porque saí do projeto usando Highcharts no ano novo, mas estou de volta agora e voltarei a este projeto em breve.

Da minha última postagem, segui o caminho de converter type em interface e usar extends vez de & (esta era minha estratégia para apoiar adequadamente o tree.json uso de excludes de campos específicos), e teve problemas: TS não permitirá que uma interface estenda outra interface que compartilha um nome de campo que é um tipo de objeto que não compartilha pelo menos 1 propriedade. Aqui está um exemplo abstrato. Eu esqueci os exemplos exatos disso que encontrei, mas havia muitos, por causa da maneira tree.json estende objetos livremente (em alguns casos as cadeias de extensão excedem 5) e exclui campos livremente em qualquer ponto. Isso me levou a pensar que minha abordagem anterior de usar & tipos de interseção pode ser o melhor caminho. Basicamente, isso resultará em algumas propriedades que são "excluídas" não aparecendo realmente excluídas na sugestão de tipo (porque elas são mescladas de algo estendido mais alto na árvore que não pode ser omitido do nó atual), mas eu não posso pense em uma maneira melhor de fazer isso. Os documentos contornam esse problema porque renderizam as propriedades a partir de um único ponto, mas estruturalmente não podemos descrever os tipos dessa maneira sem descartar extends e criar uma tonelada de definições de tipo quase sempre duplicadas.

Existem 703 símbolos após a remoção de símbolos válidos. Mas depois disso, os símbolos de saída dentro de tree.json são cerca de 100. Muitos deles são ignorados.

A que método de poda você está se referindo? Esta tem sido a parte mais difícil de lidar ...

Sim, eu também percebi que as classes / namespaces não são descritos em tree.json (que basicamente descreve as opções de init declarativas como eu as entendo), mas @cvasseng disse que são vanilla jsdoc3, então esperamos poder usar um padrão conversor para isso.

pruning é referido a partir desta linha .

Toda a coleta de dados para tree.json vive dentro do método publish .

Acho que pode haver algum uso indevido de jsdoc api dentro dele.

Poderíamos descobrir uma maneira melhor de gerar uma nova versão de tree.json base na saída original do jsdoc.

Hoje, passei um tempo tentando descobrir o que os tree.json representam. Então, finalmente descobri que tree.json hospeda apenas os tipos de opções de gráfico. Veja aqui https://api.highcharts.com/highcharts/.

A coleta de tipos e a lógica de geração são escritas aqui - https://github.com/highcharts/highcharts/blob/master/tools/jsdoc/plugins/highcharts.jsdoc.js.

Podemos precisar gerar a versão completa dos tipos por conta própria e fazer algo semelhante a https://github.com/englercj/tsd-jsdoc.

Existe algum HEC para isso? As definições em DefinitelyTyped são horríveis.

Você pensou em conversar com a equipe do TypeScript sobre os recursos ausentes de que você precisa? Tenho certeza que eles ouviriam as necessidades de um projeto do tamanho de Highcharts e eles têm um ciclo de lançamento bastante rápido.

@aaronbeall Você já olhou os Tipos mapeados ?

Aqui está um link com uma correção para o seu exemplo

@cvasseng @TorsteinHonsi

Você pensou em conversar com a equipe do TypeScript sobre os recursos ausentes de que você precisa?

@JannesMeyer Infelizmente sem caixa eletrônico ETA, meu projeto definitivamente está voltando ao uso pesado de Highcharts, mas no momento estou trabalhando em outra coisa. Na verdade, estou usando tipos mapeados (e tipos condicionais) que é como Omit<> funciona para separar as coisas ... mas os desafios para mim são mais em torno de como trabalhar a forma como a estrutura de dados Highcharts é definida em utilizável , definições de tipo ergonômicas completas. Parece que as definições devem ser minimamente definidas (ou seja, não redefinir a mesma propriedade em objetos semelhantes em todo o lugar), mas sem perder nada. Ter uma opção exibida no preenchimento de tipo que o Highcharts não usa em um determinado contexto é menos um problema do que perder algo que deveria estar lá. Há também o problema de falta de esquema doc que resulta em tipos genéricos object ou any ... em algum lugar alguém tem que escrever o tipo, a geração de tipo não pode fazer isso por você.

Sim, isso faz sentido. Parece que talvez a equipe Highcharts deva adotar o TypeScript um pouco mais do que atualmente. Talvez fosse possível gerar os documentos a partir de definições de tipo em vez de gerá-los a partir de jsdoc?

@JannesMeyer # 8307 está se

Tenho acompanhado este post e será muito útil se o arquivo de declaração estiver disponível.
Tenho usado DefenitelyTyped para nosso projeto React / Typescript. No entanto, ficou preso com acessibilidade. não percebi que a parte de acessibilidade não funcionará com o DefenitelyTyped. Entrei em contato com a equipe de suporte do Highcharts para resolver o meu problema, mas ainda não tive sorte.
Em nossa equipe, estamos usando Highcharts / Highmaps intensamente. Portanto, temos investido nisso. Por favor, pense sobre a prioridade deste projeto.

Desde já, obrigado!

Eu só gostaria de notificar que este assunto se tornou de alta prioridade.

A equipe do Highcharts ( @sophiebremer e @oysteinmoseng ) entrou em uma sessão de depuração comigo e me ajudou a resolver esse problema carregando os arquivos Js diretamente. Agradeço muito o tempo e a solução que me forneceram para me desbloquear neste momento. Aguarde o arquivo de declaração TS com Highcharts como uma solução definitiva. :)

Obrigado @sophiebremer por dar prioridade a isso. Isso será muito útil para projetos que usam Typescript.

Nota: Eu editei o comentário para fornecer um melhor contexto e também agradecer às pessoas da equipe Highcharts.

Usamos Highstock intensivamente em uma grande equipe de front-end que trabalha com angular / datilografado. Seria incrível para nós ter definições de texto datilografado, pensamos que as definições de DefinitelyTyped eram a referência, mas está completamente desatualizado para Highstock.

Essas definições de texto datilografado são realmente uma grande necessidade para nós!
Qualquer hora prevista de chegada é bem-vinda :)

Agora trabalhamos na qualidade e tentamos reduzir o número de interfaces geradas na árvore de opções do Highcharts. Depois disso, iniciaremos uma fase beta pública.

Nosso ETA é para agora o terceiro trimestre de 2018 para o Beta.

@sophiebremer Essa é uma ótima notícia! Você tem um gerador DTS ou está usando uma ferramenta de conversão existente?

Usamos um personalizado. Tentamos a abordagem desta solicitação pull https://github.com/highcharts/highcharts/pull/8307 usando dts-dom por baixo, mas isso não funcionou bem.

Algumas notícias sobre este? Parece que @types/highcharts não está mais sendo atualizado.

Ainda estamos trabalhando nisso com alta prioridade. Infelizmente não posso publicar uma prévia da declaração agora. Ainda existem tipos que precisam ser consolidados ou que precisam ser introduzidos. O "highcharts.d.ts" será um arquivo enorme com mais de 200.000 linhas de declarações e comentários.

@sophiebremer como você produz esse arquivo? Manualmente?

@ scott-ho
Embora os arquivos de declaração sejam gerados automaticamente, corrigir e atualizar os doclets no código-fonte é um processo manual.

Olá a todos! Publiquei uma prévia das declarações de Highcharts em meu repositório pessoal. Você pode testá-lo npm i https://github.com/sophiebremer/highcharts-declarations-alpha.git ou baixar a declaração em https://github.com/sophiebremer/highcharts-declarations-alpha/blob/master/highcharts.d.ts e colocá-lo diretamente em ./node_modules/highcharts/ . Informe-nos se a declaração está funcionando para você ou se você tiver problemas. Obrigado!

Problemas conhecidos:

• tipo pinning na propriedade options.series não está funcionando. A solução agora é lançar o objeto para o seu tipo de série, como { data: [0, 1, 2]} as Highcharts.SeriesLineOptions
• as opções de estilo não estão em todos os lugares do tipo CSSObject

As funções ChartEventsOptions, como seleção, não parecem assumir o parâmetro de função do evento

Alguns outros problemas que encontrei

• Não é possível importar os módulos de exportação, exportação offline. Tive que alterar export = factory para exportar a fábrica padrão e usá-la como uma importação padrão

• Módulo de anotações ausentes

• O clique PlotSeriesEventsOptions precisa ser modificado como clique ?: (e: PointerEventObject) => boolean;

Obrigado pelo feedback, @muperi !
Alguns comentários sobre sua segunda postagem:

• Os módulos regulares não exportam por padrão. Verifique seu tsconfig para as configurações ES6.
• Apenas alguns módulos têm declarações ainda. É claro que adicionaremos mais nos próximos meses.
• Vamos analisar esse problema.

As funções ChartEventsOptions, como seleção, não parecem assumir o parâmetro de função do evento

A correção faz parte do highcharts / highcharts # 9110 e será incluída na próxima atualização de https://github.com/highcharts/highcharts-declarations-beta.

Adicione mais problemas com os arquivos de declaração a este repositório: https://github.com/highcharts/highcharts-declarations-beta.

Obrigada.