#7027: add code comment brick

[twschiller]

What does this PR do?

• Closes Add Comment Brick #7027
• Adds a "Comment" brick a user can use to document their mod
• The Comment Configuration is just a text entry with expressions not supported
• Displays a snippet of the comment in the brick outline
• Refactoring:
  • Refactors block -> brick in touched files
  • Refactors BrickConfiguration to use the modern useAsyncState hook

Remaining Work

• Fix warning when used in renderer pipeline
• Finish UI of the snippet in the brick outline

Discussion

• I put the advanced options logic in BlockConfiguration vs. adding a new property to the Brick interface/protocol
• Added as an effect brick so it doesn't have an output. To do so, needed to add an exception to the Brick Type Analysis so it can be added to Renderer pipelines

Demo

• https://www.loom.com/share/f8e427c394d24dcd82313c3e0cdd84f5?sid=281cb1ba-9165-4645-932e-44c1c300cd19

Future Work

• Brick comments in mods: https://www.notion.so/pixiebrix/Brick-Comments-in-Mods-e4382d34bcd84a23b3467374144ebbff?pvs=4

Team Coordination

• This PR requires updating brick headers: it's safe to update headers before the release
• This PR requires a documentation change (link to old docs)
• This PR requires a marketplace listing: need to pick a comment icon. Potentially fas fa-book or a comment bubble: @brittanyjoiner15

Checklist

• Add tests
• New files added to src/tsconfig.strictNullChecks.json (if possible)
• Designate a primary reviewer: @grahamlangford

[codecov]

Codecov Report

Attention: 16 lines in your changes are missing coverage. Please review.

Comparison is base (681fee3) 71.05% compared to head (1814534) 71.09%.

Files	Patch %	Lines
src/pageEditor/exampleStarterBrickConfigs.ts	0.00%	7 Missing ⚠️
src/bricks/effects/comment.ts	76.47%	4 Missing ⚠️
src/pageEditor/brickSummary.tsx	81.81%	2 Missing ⚠️
src/bricks/effects/CommentOptions.tsx	94.11%	1 Missing ⚠️
src/development/headers.ts	0.00%	1 Missing ⚠️
src/pageEditor/panes/insert/useAutoInsert.ts	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7028      +/-   ##
==========================================
+ Coverage   71.05%   71.09%   +0.03%     
==========================================
  Files        1207     1210       +3     
  Lines       37335    37399      +64     
  Branches     6997     7004       +7     
==========================================
+ Hits        26528    26588      +60     
- Misses      10807    10811       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[grahamlangford]

Rather than having the comment as a separate textarea, it might be better UX to make the step name into a textarea so that the "comment" shows up in the pipeline.

[brittanyjoiner15]

Looks good to me!

[twschiller]

Rather than having the comment as a separate textarea, it might be better UX to make the step name into a textarea so that the "comment" shows up in the pipeline.

I'll chat with @BrandonPxBx today. We don't have much screen real-estate in the outline view

[grahamlangford]

Rather than having the comment as a separate textarea, it might be better UX to make the step name into a textarea so that the "comment" shows up in the pipeline.

I'll chat with @BrandonPxBx today. We don't have much screen real-estate in the outline view

I know, but I'm not sure I'm convinced the current implementation is useful. I think I'd rather have to write shorter comments than have to click into a brick to read it.

[twschiller]

@grahamlangford @BrandonPxBx @mnholtz what do you think of including a snippet of the comment preview in the outline? We'd likely want a way to show it's truncated or not

Right now it ignores new lines. We could consider having it show the first paragraph (but still truncate). That would support a summary + details style of commenting

[mnholtz]

what do you think of including a snippet of the comment preview in the outline? We'd likely want a way to show it's truncated or not

Definitely on board with this @twschiller

[grahamlangford]

Right now it ignores new lines. We could consider having it show the first paragraph (but still truncate). That would support a summary + details style of commenting

-webkit-line-clamp: 3 would probably work well here.

[mnholtz]

Updated the UI to include line-clamping and the [Experimental] tag:

AI Copilot - PixieBrix - 5 December 2023 - Watch Video

@twschiller @grahamlangford @BrandonPxBx does this satisfy the remaining UI work?

[BrandonPxBx]

Updated the UI to include line-clamping and the [Experimental] tag:

AI Copilot - PixieBrix - 5 December 2023 - Watch Video

Looks great to me.

[github-actions]

When the PR is merged, the first loom link found on this PR will be posted to #sprint-demo on Slack. Do not edit this comment manually.