5 ms·

I've read and perused this, and I have some specific questions. 1. According to the spec[0], a "block package" is "a collection of files making a block type (w

I've read and perused this, and I have some specific questions. 1. According to the spec[0], a "block package" is "a collection of files making a block type (which is 'a definition and implementation', the schema and the code) available for use by embedding applications, including its source code and accompanying metadata." However, when I browse to a "block"/"block package" in the Block Hub[1], I'm presented with a demo of the "block package" in the form of a concrete "block", a view of example data being provided to this "block", and a view of the schema of this "block". However, if this is meant to be a view of the "block package", shouldn't I also be able to find my way to the rest of this "block package", i.e. where do I view the implementation code? The spec says that a block package includes its source code, and the block hub seems to be a browser of block packages, but it doesn't give me the full view into said block packages. Is there a reason for this? Is it on the to-do list? 2. What's going on with the type signatures here? I see a lot of what look like type signatures, in both the spec and the schemas. In reading the spec, it seems like the type signatures are being used pretty loosely, maybe as pseudo code of a sort, as I don't see them being rigorously referred to. For example, I see that in "Specification > Block Types > Entity type functions"[2] under `createEntityTypes` it refers to accepting a type of "CreateEntityTypesAction" (no type signature), but then lower down it refers to accepting a type of "CreateEntityTypesAction<T>", but then says that the shape of that entity is just two hard-coded fields, with no reference to the generic type "T". What's going on here? Then if I view an actual block in the Block Hub[1], I see that the schema for that block also has definitions for entities with some kind of type signature 'something' going on e.g. "#/definitions/Record<string,{cellState:UseRowStateLocalState<{},unknown>;}>". Maybe those are for use with something like TypeScript? I'm not familiar with TypeScript, so I don't know how to parse those, though I do know that they're not specifying anything at the level of "JSON Schema"[3], so I assume they're related to either something in the spec or something in the implementation, or both. What's happening here? Are these types in the schema owned by the implementation (e.g. they're used by the source code of the implementation for JSX or something?), while the types in the spec are merely pseudocode? If there's already a pattern where additional layers of features such as typing/templating are being shoved into the schemas of Blocks, might this make interop between blocks more difficult in the future? [0] - https://blockprotocol.org/spec#terminology https://blockprotocol.org/spec#terminology [1] - https://blockprotocol.org/@hash/table https://blockprotocol.org/@hash/table [2] - https://blockprotocol.org/spec/block-types#entity-functions https://blockprotocol.org/spec/block-types#entity-functions [3] - https://json-schema.org/ https://json-schema.org/

ciaranmn 5y ago
1) The spec says that a block package includes its source code, and the block hub seems to be a browser of block packages, but it doesn't give me the full view into said block packages. Is there a reason for this? Is it on the to-do list? It's on the to-list indeed - we are going to add links to the source of blocks. The package for distribution will typically be minified and less illuminating, although we can look to expose that too (as well as making it available for request via the API when actually loading a block). 2) What's going on with the type signatures here? The type signatures on functions in the spec definitely need cleaning up to be consistent and more helpful. They are pseudo-code. There are TypeScript types for them (https://github.com/blockprotocol/blockprotocol/blob/main/packages/blockprotocol/core.d.ts https://github.com/blockprotocol/blockprotocol/blob/main/pac...) which won't be much use to you, but I am including in case they are of someone else. The schema you mention in the Hub is autogenerated from the TypeScript interface for the block, which can lead to weird artefacts of the sort you identify. We need to add custom codegen to better handle this. It should valid JSON Schema.

ciaranmn 5y ago

1) The spec says that a block package includes its source code, and the block hub seems to be a browser of block packages, but it doesn't give me the full view into said block packages. Is there a reason for this? Is it on the to-do list? It's on the to-list indeed - we are going to add links to the source of blocks. The package for distribution will typically be minified and less illuminating, although we can look to expose that too (as well as making it available for request via the API when actually loading a block). 2) What's going on with the type signatures here? The type signatures on functions in the spec definitely need cleaning up to be consistent and more helpful. They are pseudo-code. There are TypeScript types for them (https://github.com/blockprotocol/blockprotocol/blob/main/packages/blockprotocol/core.d.ts https://github.com/blockprotocol/blockprotocol/blob/main/pac...) which won't be much use to you, but I am including in case they are of someone else. The schema you mention in the Hub is autogenerated from the TypeScript interface for the block, which can lead to weird artefacts of the sort you identify. We need to add custom codegen to better handle this. It should valid JSON Schema.