Rewrite Visual Editor API JSDoc from the implementation#37
Open
EllaCloudCannon wants to merge 8 commits into
Open
Rewrite Visual Editor API JSDoc from the implementation#37EllaCloudCannon wants to merge 8 commits into
EllaCloudCannon wants to merge 8 commits into
Conversation
EllaCloudCannon
changed the title
rycoll
reviewed
Jun 23, 2026
Comment on lines
+17
to
+22
| /** | ||
| * A stable identifier for the panel, returned as the `panelId` and passed to | ||
| * `destroyCustomDataPanel` to close it. When omitted, CloudCannon generates a | ||
| * seven-character base-36 id (digits `0`-`9` and lowercase `a`-`z`, e.g. | ||
| * `k4j92xq`). Treat it as an opaque token. | ||
| */ |
Contributor
There was a problem hiding this comment.
This description makes me think there is something in the code called panelId, but I don't think that's the case? I also don't really know what "opaque token" means, but that might just be me?
Comment on lines
+17
to
+22
| /** | ||
| * A stable identifier for the panel, returned as the `panelId` and passed to | ||
| * `destroyCustomDataPanel` to close it. When omitted, CloudCannon generates a | ||
| * seven-character base-36 id (digits `0`-`9` and lowercase `a`-`z`, e.g. | ||
| * `k4j92xq`). Treat it as an opaque token. | ||
| */ |
Contributor
There was a problem hiding this comment.
Suggested change
| /** | |
| * A stable identifier for the panel, returned as the `panelId` and passed to | |
| * `destroyCustomDataPanel` to close it. When omitted, CloudCannon generates a | |
| * seven-character base-36 id (digits `0`-`9` and lowercase `a`-`z`, e.g. | |
| * `k4j92xq`). Treat it as an opaque token. | |
| */ | |
| /** | |
| * A stable identifier for the new panel. This can be passed to `destroyCustomDataPanel` | |
| * to close it. When omitted, CloudCannon generates a seven-character base-36 id | |
| * (digits `0`-`9` and lowercase `a`-`z`, e.g.`k4j92xq`). | |
| */ |
| /** The slug of the target field. */ | ||
| slug: string; | ||
| /** Optional style information */ | ||
| /** Optional style hint for the editing surface. */ |
Contributor
There was a problem hiding this comment.
Suggested change
| /** Optional style hint for the editing surface. */ | |
| /** Set to "sidebar" to open in the Data Editor sidebar instead of a Data Panel. */ |
| * In this example, we read when the file was created. | ||
| * ```javascript | ||
| * const { created_at } = await api.currentFile().metadata(); | ||
| * console.log(created_at); |
Contributor
There was a problem hiding this comment.
Suggested change
| * console.log(created_at); | |
| * console.log(`Created at ${new Date(created_at).toLocaleString()}`); |
Contributor
There was a problem hiding this comment.
Slightly more dynamic example to show it's a date string? All good either way, just an idea
| file(path: string): CloudCannonVisualEditorAPIV1File; | ||
| /** | ||
| * Returns the Collection with the given key, as configured under | ||
| * `collections_config` in your CloudCannon Configuration File. |
Contributor
There was a problem hiding this comment.
Bit of a nitpick, but "Collection" could mean the items in the collection, or the configuration for the collection. Maybe we could say that here it means an object with methods for listing collection items and listening to changes?
Comment on lines
+1182
to
+1185
| * Opens a custom Data Panel in the Visual Editor and resolves with its | ||
| * `panelId`. When `options.id` is omitted, CloudCannon generates a | ||
| * seven-character base-36 id. Pass the returned `panelId` to | ||
| * `destroyCustomDataPanel` to close the panel. |
Contributor
There was a problem hiding this comment.
Suggested change
| * Opens a custom Data Panel in the Visual Editor and resolves with its | |
| * `panelId`. When `options.id` is omitted, CloudCannon generates a | |
| * seven-character base-36 id. Pass the returned `panelId` to | |
| * `destroyCustomDataPanel` to close the panel. | |
| * Opens a custom Data Panel in the Visual Editor and resolves with an | |
| * ID corresponding to that panel. Pass the returned `panelId` to | |
| * `destroyCustomDataPanel` to close the panel. |
| */ | ||
| createCustomDataPanel(options: CreateCustomDataPanelOptions): Promise<string>; | ||
| /** | ||
| * Closes the custom Data Panel with the given `panelId`. |
Contributor
There was a problem hiding this comment.
Maybe this is actually fine, but the camelcase and backticks on "panelId" make me think it's supposed to be an actual variable name, and I think it's just a concept?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PLEASE DELETE HANDOFF DOC BEFORE MERGE
Summary
Replaces the Visual Editor API's JSDoc (
src/index.d.ts) with a full rewrite grounded in the actual app implementation, plus aHANDOFF.mddocumenting type-level follow-ups the comment pass can't make. The previous JSDoc was AI-generated and unreliable (e.g.@throws {FileNotFoundError}/{CollectionNotFoundError}that are never thrown). Sinceplatform-documentationgenerates the developer reference directly from this file, these comments are the published reference.What changed
src/index.d.ts— JSDoc rewrite (comments + one type change):@throws; only the realErrorcases documented, with actual failure modes described instead (resolve-undefined, theitems()falsy-key hang).@exampleon every method and property; consistent present-tense voice; CloudCannon terminology capitalized ("Configuration File", "Team Member", "Data Panel"); no em dashes.event.detailpayload (isNew,sourcePath) documented once in the reference's Events section rather than repeated.Collection.items()/Dataset.items()document their (verified, asymmetric) bad-key behavior: a non-matching Collection key resolves to[], while a Dataset hangs.File.data/contentreframed as entry points (no longer duplicate the childget()examples);FileData/FileContentlead with "Accessed through a File'sdata/contentproperty".data.uploaddocuments its save semantics and uses a self-contained example;editreworded;EditOptions.sluggeneralized to cover botheditandupload; void mutators say "Has no effect if the file does not exist".datasets()reference fromDataset; addedfiles()to theFile"Returned by" list.File.get(),claimLock(),releaseLock()to… | undefined, matching the verified handler behavior (the message handler returnsundefinedfor any unresolvedsourcePath).HANDOFF.md(new): maintainer follow-ups that require type/code changes, tiered by priority:FileContent.get()throws on a missing file instead of resolvingundefined(client bug);data.uploadsurfacesstyle/positionit ignores;FileMetadata.last_modifiedis typedstring | Datebut the client only ever receives a string (JSON boundary);FileData/FileContentaddEventListenernever fire (no:data:/:content:events are dispatched).AddArrayItemOptions.valueoptionality; whether adatasets()method should exist.event.detail; naming inline option literals (GetDataOptions,PanelPosition); a V0 listener-union cleanup.Each Tier 1 item cites the specific app code it was verified against.