diff --git a/.mintignore b/.mintignore index d2c59d971..cec5c5579 100644 --- a/.mintignore +++ b/.mintignore @@ -1,12 +1,22 @@ -# Files excluded from the Mintlify docs build (gitignore syntax). -# scripts/ holds the skills-sync pipeline + reference artifacts (e.g. -# reference-artifacts/format-guide.md) — internal tooling, not docs pages. -# Its template syntax () is not valid MDX and breaks -# the build, so exclude the whole directory. -scripts/ +# Exclude from Mintlify processing (.gitignore syntax). +# See https://www.mintlify.com/docs/organize/mintignore +# +# Note: node_modules and .claude are ignored by default in recent Mintlify +# versions, but list them explicitly so older CLIs stay quiet. -# Internal release-notes pipeline artifacts and agent logs — not docs pages. -# These contain raw text/JSX-like snippets that aren't valid MDX and break the -# build (e.g. "Could not parse import/exports with acorn"). +# Dependencies / tooling +node_modules/ +scripts/ .pipeline-scratch/ .claude/ +.cursor/ +.agents/ +.git/ +.github/ + +# Scratch / temp docs that aren't published pages +temp-release-notes*.mdx +WIREFRAME_VARIABLES_TEMPLATE.md +SKILLS_SYNC_PIPELINE.md +CLAUDE.md +README.md diff --git a/api-reference/sdk/api/api-methods.mdx b/api-reference/sdk/api/api-methods.mdx index a0feff5a6..17e3b5f65 100644 --- a/api-reference/sdk/api/api-methods.mdx +++ b/api-reference/sdk/api/api-methods.mdx @@ -3890,7 +3890,7 @@ Reset the state of Velt Button components. - Params: (optional) [VeltResetButtonStateConfig](/api-reference/sdk/models/data-models#veltresetbuttonstateconfig) - Returns: `void` - React Hook: `n/a` -- [Full Documentation →](/ui-customization/custom-action-component#reset-velt-button-state) +- [Full Documentation →](/ui-customization/patterns-and-tips#reset-a-veltbuttonwireframe-after-app-logic-runs) diff --git a/api-reference/sdk/models/data-models.mdx b/api-reference/sdk/models/data-models.mdx index 12b1ddfd7..48f05fdc9 100644 --- a/api-reference/sdk/models/data-models.mdx +++ b/api-reference/sdk/models/data-models.mdx @@ -2619,11 +2619,11 @@ class ReactionMetadata extends BaseMetadata { ### Comment Dialog Primitives -Types for the 92+ primitive components used to build custom comment dialog interfaces. See [Comment Dialog Primitives Overview](/ui-customization/features/async/comments/comment-dialog/primitives) for usage examples. +Types for the 92+ primitive components used to build custom comment dialog interfaces. See [`Primitive components`](/ui-customization/reference/primitives) for the complete component list and [`Primitives`](/ui-customization/primitives) for usage guidance. #### CommentDialogCommonProps -## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#common-inputs) +Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Base props inherited by all Comment Dialog primitive components. @@ -2637,7 +2637,7 @@ Base props inherited by all Comment Dialog primitive components. #### CommentDialogContextWrapperProps -## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcontextwrapper) +Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for the VeltCommentDialogContextWrapper component. @@ -2651,7 +2651,7 @@ Props for the VeltCommentDialogContextWrapper component. #### ThreadCardProps -## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogthreadcard) +Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for VeltCommentDialogThreadCard with priority-based comment lookup. @@ -2665,7 +2665,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr #### CommentIndexProps -## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogthreadcardavatar) +Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for thread card sub-components that require a comment index. @@ -2677,7 +2677,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr #### ComposerProps -## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcomposer) +Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for VeltCommentDialogComposer with placeholder and edit mode options. @@ -2697,7 +2697,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr #### ComposerInputProps -## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcomposerinput) +Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for VeltCommentDialogComposerInput. @@ -2709,7 +2709,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr #### StatusDropdownItemProps -## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogstatusdropdowncontentitem) +Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for VeltCommentDialogStatusDropdownContentItem with priority-based status lookup. @@ -2723,7 +2723,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr #### PriorityDropdownItemProps -## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogprioritydropdowncontentitem) +Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for VeltCommentDialogPriorityDropdownContentItem with priority-based priority lookup. @@ -2737,7 +2737,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr #### OptionsDropdownProps -## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogoptionsdropdown) +Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for VeltCommentDialogOptionsDropdown with feature enable flags. @@ -2761,7 +2761,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr #### CustomAnnotationItemProps -## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcustomannotationdropdowntriggerlistitem) +Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for custom annotation dropdown items. @@ -2774,7 +2774,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr #### ReplyAvatarsListItemProps -## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogreplyavatarslistitem) +Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list. Props for VeltCommentDialogReplyAvatarsListItem. @@ -4581,7 +4581,7 @@ Defines the time window and activity cap for a single batching scope. ### Notification Primitives -Types for the primitive components used to build custom notification interfaces. See [Notifications Primitives](/ui-customization/features/async/notifications/notifications-panel/primitives) for usage examples. +Types for the primitive components used to build custom notification interfaces. See [Notifications Primitives](/ui-customization/features/async/notifications/notifications-panel/primitives) for usage examples and [`Primitives catalog`](/ui-customization/reference/primitives) for the complete component list. #### NotificationsPrimitiveCommonProps [Usage Examples →](/ui-customization/features/async/notifications/notifications-panel/primitives#common-inputs) diff --git a/async-collaboration/comments-sidebar/v1/customize-behavior.mdx b/async-collaboration/comments-sidebar/v1/customize-behavior.mdx index 98c26ed62..2a1f30c55 100644 --- a/async-collaboration/comments-sidebar/v1/customize-behavior.mdx +++ b/async-collaboration/comments-sidebar/v1/customize-behavior.mdx @@ -5,7 +5,7 @@ title: "Customize Behavior" # Custom filtering, sorting and grouping - Here is the overview on how it works: - Enable custom actions in the comments sidebar. - - Add [Velt Button Wireframe](/ui-customization/custom-action-component) to the sidebar wireframe. + - Add the Velt button wireframe to the sidebar wireframe. See [Bridge a wireframe button to your app logic](/ui-customization/patterns-and-tips#bridge-a-wireframe-button-to-your-app-logic-the-onclick-escape-hatch). - Handle click events and lifecycle events to apply custom filtering, sorting, and grouping logic. - Update sidebar data. - Here are the steps to implement it: @@ -42,7 +42,7 @@ title: "Customize Behavior" - - Learn more about how to setup [Velt Button Wireframe](/ui-customization/custom-action-component). + - Learn more about how to set up a [wireframe button for app logic](/ui-customization/patterns-and-tips#bridge-a-wireframe-button-to-your-app-logic-the-onclick-escape-hatch). - Set default state using the `active` prop. - Handle `veltButtonClick` event to implement custom filtering, sorting, and grouping logic. It returns [VeltButtonClickEvent](/api-reference/sdk/models/data-models#veltbuttonclickevent). @@ -609,7 +609,7 @@ Default: `true` - Enabling this mode also adds a navigation button in the comment dialog. Clicking it will navigate to the comment and trigger a callback. Learn more about it [here](#oncommentnavigationbuttonclick). - If you had previously used a wireframe for the comment dialog, you will need to add the [navigation button wireframe](/ui-customization/features/async/comments/comment-dialog/wireframes#header) and the [focused thread wireframe](/ui-customization/features/async/comments/comment-sidebar-structure-v2). + If you had previously used a wireframe for the comment dialog, you will need to add the navigation button wireframe and the focused thread wireframe. See the [`Component catalog`](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) and [`Wireframe components`](/ui-customization/reference/wireframe-components) for the current slot names. diff --git a/async-collaboration/comments-sidebar/v2/customize-behavior.mdx b/async-collaboration/comments-sidebar/v2/customize-behavior.mdx index f2571d25f..2af15c344 100644 --- a/async-collaboration/comments-sidebar/v2/customize-behavior.mdx +++ b/async-collaboration/comments-sidebar/v2/customize-behavior.mdx @@ -196,7 +196,7 @@ Default: `[]` A **path predicate** is a rule that keeps only comments whose value at a given field path matches. For example, `{ path: 'from.userId', value: '1.1' }` keeps comments authored by the user with id `1.1`. The `value` is a literal (there is no `@me` token), and paths auto-flatten nested arrays (e.g. `comments.taggedUserContacts.contact.userId`). -Each dropdown is rendered by the filter-dropdown primitive ([`VeltCommentSidebarV2FilterDropdown`](/ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-primitives#veltcommentsidebarv2filterdropdown) / `velt-comment-sidebar-filter-dropdown-v2`). +Each dropdown is rendered by the filter-dropdown primitive (`VeltCommentSidebarV2FilterDropdown` / `velt-comment-sidebar-filter-dropdown-v2`). See [`Primitive components`](/ui-customization/reference/primitives) for the current primitive list. The examples below show one dropdown per `type`. @@ -331,7 +331,7 @@ To match several paths in one quick filter, give an action a list of `conditions -Prefer configuring dropdowns through `minimalFilters` as shown above. If you need to place or restyle a dropdown directly in your own markup, you can set these same inputs on the filter-dropdown primitive — see [Comment Sidebar V2 Primitives](/ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-primitives#veltcommentsidebarv2filterdropdown). +Prefer configuring dropdowns through `minimalFilters` as shown above. If you need to place or restyle a dropdown directly in your own markup, you can set these same inputs on the filter-dropdown primitive — see [`Primitives`](/ui-customization/primitives) and [`Primitive components`](/ui-customization/reference/primitives). #### defaultMinimalFilter @@ -1350,5 +1350,5 @@ commentElement.toggleCommentSidebar(); -For V2 customization, see [Comment Sidebar V2 Wireframes](/ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-wireframes) and [Comment Sidebar V2 Primitives](/ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-primitives). The sidebar is shadow-DOM isolated by default. +For V2 wireframe and primitive customization, start with the [`Component catalog`](/ui-customization/reference/component-catalog#sidebar-slot-trees), then use [`Wireframe components`](/ui-customization/reference/wireframe-components) for the complete slot tree and [`Primitive components`](/ui-customization/reference/primitives) for the primitive list. The sidebar is shadow-DOM isolated by default. diff --git a/async-collaboration/comments-sidebar/v2/setup.mdx b/async-collaboration/comments-sidebar/v2/setup.mdx index 2946b824d..01a1cbc15 100644 --- a/async-collaboration/comments-sidebar/v2/setup.mdx +++ b/async-collaboration/comments-sidebar/v2/setup.mdx @@ -42,4 +42,4 @@ export default function App() { For V2 props reference, see [`VeltCommentsSidebarV2Props`](/api-reference/sdk/models/data-models#veltcommentssidebarv2props). -For V2 wireframe customization, see [Comment Sidebar V2 Wireframes](/ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-wireframes). +For V2 wireframe customization, start with the [`Component catalog`](/ui-customization/reference/component-catalog#sidebar-slot-trees), then use [`Wireframe components`](/ui-customization/reference/wireframe-components) for the complete slot tree. diff --git a/async-collaboration/comments/customize-behavior.mdx b/async-collaboration/comments/customize-behavior.mdx index 5011a69bb..1bc8c0ac7 100644 --- a/async-collaboration/comments/customize-behavior.mdx +++ b/async-collaboration/comments/customize-behavior.mdx @@ -905,7 +905,7 @@ Programmatically submit a comment from a composer. Enables custom buttons or key - Params: [`SubmitCommentRequest`](/api-reference/sdk/models/data-models#submitcommentrequest) - Returns: `void` -- See also: [Comment Composer targetComposerElementId](/ui-customization/features/async/comments/standalone-components/comment-composer#target-composer-element-id) +- See also: [Comment Composer targetComposerElementId](/async-collaboration/comments/standalone-components/comment-composer/customize-behavior) @@ -9349,4 +9349,3 @@ subscription?.unsubscribe() ``` - diff --git a/async-collaboration/comments/standalone-components/comment-composer/overview.mdx b/async-collaboration/comments/standalone-components/comment-composer/overview.mdx index 7b13393b4..288725864 100644 --- a/async-collaboration/comments/standalone-components/comment-composer/overview.mdx +++ b/async-collaboration/comments/standalone-components/comment-composer/overview.mdx @@ -8,6 +8,6 @@ The Comment Standalone Composer enables you to add comments anywhere in your app - [Comment Data APIs](/async-collaboration/comments/customize-behavior#getcommentannotations): Fetch and submit comment data. - [Comment Thread](/async-collaboration/comments/standalone-components/comment-thread/overview): Render comment threads using fetched data. - [Comment Pin](/async-collaboration/comments/standalone-components/comment-pin/overview): Display and position comment pins based on fetched data. -- [Comment Dialog Primitives](/ui-customization/features/async/comments/comment-dialog/primitives): Use 115+ granular components for maximum customization flexibility. +- [Primitive components](/ui-customization/reference/primitives): Use granular components for maximum customization flexibility. By combining these components, you can create custom comment interfaces such as sidebars, overlays, popovers, or inline comments. This approach offers greater flexibility and control over your comment system's design and functionality. \ No newline at end of file diff --git a/async-collaboration/comments/standalone-components/comment-thread/overview.mdx b/async-collaboration/comments/standalone-components/comment-thread/overview.mdx index 844dd63c4..1c4051bbd 100644 --- a/async-collaboration/comments/standalone-components/comment-thread/overview.mdx +++ b/async-collaboration/comments/standalone-components/comment-thread/overview.mdx @@ -8,7 +8,7 @@ sidebarTitle: "Overview" - your own version of the `Comments Sidebar` component - This component does not add any additional functionality. It is just used to render existing comment data. -- This is a thin wrapper around the [Comment Dialog component](/ui-customization/features/async/comments/comment-dialog/wireframes). +- This is a thin wrapper around the Comment Dialog component. See the [`Component catalog`](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) and [`Wireframe components`](/ui-customization/reference/wireframe-components) for customization guidance. - Get the Comment Annotations data using the APIs. - Use this component to render the Comment Annotations data. diff --git a/docs.json b/docs.json index 26cbed0d5..ef61fe80c 100644 --- a/docs.json +++ b/docs.json @@ -30,10 +30,12 @@ "group": "Agentic Setup", "pages": [ "get-started/agentic-overview", - "get-started/plugins", + "get-started/installation-plugin", "get-started/mcp-installer", + "get-started/ui-customization-plugin", "get-started/skills", - "get-started/cli" + "get-started/cli", + "get-started/docs-mcp" ] }, { @@ -406,21 +408,49 @@ "group": "Concepts", "pages": [ "ui-customization/overview", - "ui-customization/setup", - "ui-customization/layout", + "ui-customization/how-it-works", + "ui-customization/decision-tree", + "ui-customization/setup" + ] + }, + { + "group": "Approaches", + "pages": [ "ui-customization/styling", - "ui-customization/template-variables", - "ui-customization/conditional-templates", - "ui-customization/custom-action-component", + { + "group": "Wireframes", + "pages": [ + "ui-customization/layout", + "ui-customization/wireframes/setup-wireframes", + "ui-customization/wireframes/layout-customization", + "ui-customization/template-variables", + "ui-customization/conditional-templates", + "ui-customization/context", + "ui-customization/wireframes/action-components" + ] + }, + "ui-customization/primitives", + "ui-customization/headless", + "ui-customization/combining-approaches" + ] + }, + { + "group": "Recipes & Troubleshooting", + "pages": [ + "ui-customization/patterns-and-tips", + "ui-customization/debugging", + "ui-customization/edge-cases-and-limitations", "ui-customization/localisation" ] }, { - "group": "Async Collaboration", + "group": "Components: Async Collaboration", "pages": [ + "ui-customization/features/other-features", { "group": "Comments", "pages": [ + "ui-customization/features/comment-surfaces", { "group": "Comment Dialog", "pages": [ @@ -470,13 +500,6 @@ "ui-customization/features/async/comments/inline-comments-section/primitives" ] }, - { - "group": "Comment Pin", - "pages": [ - "ui-customization/features/async/comments/comment-pin/wireframes", - "ui-customization/features/async/comments/comment-pin/primitives" - ] - }, { "group": "Comment Tool", "pages": [ @@ -487,6 +510,7 @@ { "group": "Autocomplete", "pages": [ + "ui-customization/features/mentions-and-autocomplete", "ui-customization/features/async/comments/autocomplete-wireframe-variables" ] }, @@ -536,6 +560,7 @@ { "group": "In-app Notifications", "pages": [ + "ui-customization/features/notifications", { "group": "Notifications Tool", "pages": [ @@ -557,6 +582,7 @@ { "group": "Recorder", "pages": [ + "ui-customization/features/recorder-and-transcription", "ui-customization/features/async/recorder/wireframe-variables", "ui-customization/features/async/recorder/control-panel", "ui-customization/features/async/recorder/media-source-settings", @@ -573,6 +599,7 @@ { "group": "Reactions", "pages": [ + "ui-customization/features/reactions", "ui-customization/features/async/inline-reactions", "ui-customization/features/async/reactions-wireframe-variables" ] @@ -583,6 +610,7 @@ "ui-customization/features/async/rewriter/wireframe-variables" ] }, + "ui-customization/features/annotations-tags-arrows-areas", { "group": "Arrows", "pages": [ @@ -614,6 +642,7 @@ { "group": "Activity Logs", "pages": [ + "ui-customization/features/activity-log", "ui-customization/features/async/activity-logs/activity-logs-wireframes", "ui-customization/features/async/activity-logs/activity-logs-wireframe-variables", "ui-customization/features/async/activity-logs/activity-logs-primitives" @@ -622,8 +651,9 @@ ] }, { - "group": "Realtime Collaboration", + "group": "Components: Realtime Collaboration", "pages": [ + "ui-customization/features/presence-and-cursors", { "group": "Presence", "pages": [ @@ -656,6 +686,70 @@ ] } ] + }, + { + "group": "Reference", + "pages": [ + { + "group": "Components", + "pages": [ + "ui-customization/reference/component-catalog", + "ui-customization/reference/component-definitions", + "ui-customization/reference/wireframe-components", + "ui-customization/reference/primitives", + "ui-customization/reference/component-config" + ] + }, + { + "group": "Props, APIs & Data", + "pages": [ + "ui-customization/reference/props", + "ui-customization/reference/apis", + "ui-customization/reference/hooks", + "ui-customization/reference/events", + "ui-customization/reference/data-models", + "ui-customization/reference/feature-flags" + ] + }, + { + "group": "Styling", + "pages": [ + "ui-customization/reference/css-variables", + "ui-customization/reference/css-classes" + ] + }, + { + "group": "Behaviors", + "pages": [ + "ui-customization/reference/behaviors", + { + "group": "Behavior Details", + "pages": [ + "ui-customization/reference/behaviors/comments-core", + "ui-customization/reference/behaviors/dialog", + "ui-customization/reference/behaviors/sidebar", + "ui-customization/reference/behaviors/notifications", + "ui-customization/reference/behaviors/pins-tools", + "ui-customization/reference/behaviors/presence-reactions", + "ui-customization/reference/behaviors/recorder-huddle" + ] + } + ] + }, + { + "group": "AI Agent Workflow", + "pages": [ + "ui-customization/build-methodology", + "ui-customization/extraction", + "ui-customization/rules", + "ui-customization/build-gotchas", + "ui-customization/verifying-a-customization", + "ui-customization/sdk-gaps-and-blockers", + "ui-customization/reference/manifest", + "ui-customization/reference/source-of-truth-invariant" + ] + } + ] } ] }, @@ -1233,6 +1327,14 @@ ] }, "redirects": [ + { + "source": "/get-started/figma-plugin", + "destination": "/get-started/ui-customization-plugin" + }, + { + "source": "/get-started/plugins", + "destination": "/get-started/installation-plugin" + }, { "source": "/async-collaboration/comments-sidebar/setup", "destination": "/async-collaboration/comments-sidebar/v1/setup" @@ -1261,46 +1363,6 @@ "source": "/get-started/setup", "destination": "/get-started/quickstart" }, - { - "source": "/ui-customization/features/async/notifications/notifications-tool", - "destination": "/ui-customization/features/async/notifications/notifications-tool/wireframes" - }, - { - "source": "/ui-customization/features/async/notifications/notifications-panel", - "destination": "/ui-customization/features/async/notifications/notifications-panel/wireframes" - }, - { - "source": "/ui-customization/features/async/notifications/notifications-primitives", - "destination": "/ui-customization/features/async/notifications/notifications-panel/primitives" - }, - { - "source": "/ui-customization/features/async/comments/comment-bubble", - "destination": "/ui-customization/features/async/comments/comment-bubble/wireframes" - }, - { - "source": "/ui-customization/features/async/comments/comment-pin", - "destination": "/ui-customization/features/async/comments/comment-pin/wireframes" - }, - { - "source": "/ui-customization/features/async/comments/comment-sidebar-button", - "destination": "/ui-customization/features/async/comments/comment-sidebar-button/wireframes" - }, - { - "source": "/ui-customization/features/async/comments/inline-comments-section", - "destination": "/ui-customization/features/async/comments/inline-comments-section/wireframes" - }, - { - "source": "/ui-customization/features/async/comments/multithread-comment-dialog", - "destination": "/ui-customization/features/async/comments/multithread-comments/wireframes" - }, - { - "source": "/ui-customization/features/async/comments/text-comment-tool", - "destination": "/ui-customization/features/async/comments/text-comment/text-comment-tool/wireframes" - }, - { - "source": "/ui-customization/features/async/comments/text-comment-toolbar", - "destination": "/ui-customization/features/async/comments/text-comment/text-comment-toolbar/wireframes" - }, { "source": "/key-concepts/access-control/overview", "destination": "/key-concepts/overview#access-control" @@ -1409,13 +1471,121 @@ "source": "/key-concepts/locations/setup/api-update-location", "destination": "/key-concepts/overview#locations" }, + { + "source": "/ui-customization/getting-started", + "destination": "/ui-customization/setup" + }, + { + "source": "/ui-customization/approaches/css", + "destination": "/ui-customization/styling" + }, + { + "source": "/ui-customization/approaches/wireframes", + "destination": "/ui-customization/layout" + }, + { + "source": "/ui-customization/approaches/primitives", + "destination": "/ui-customization/primitives" + }, + { + "source": "/ui-customization/approaches/headless", + "destination": "/ui-customization/headless" + }, + { + "source": "/ui-customization/approaches/combining-approaches", + "destination": "/ui-customization/combining-approaches" + }, + { + "source": "/ui-customization/reference/wireframe-tokens", + "destination": "/ui-customization/conditional-templates" + }, + { + "source": "/ui-customization/reference/wireframe-variables", + "destination": "/ui-customization/template-variables" + }, + { + "source": "/ui-customization/cross-cutting", + "destination": "/ui-customization/localisation" + }, + { + "source": "/ui-customization/other-features", + "destination": "/ui-customization/features/other-features" + }, { "source": "/ui-customization/customize-css/remove-shadow-dom", "destination": "/ui-customization/styling" }, { "source": "/ui-customization/customize-css/themes", - "destination": "/ui-customization/styling#themes" + "destination": "/ui-customization/styling" + }, + { + "source": "/realtime-collaboration/presence/heartbeat", + "destination": "/realtime-collaboration/presence/overview#heartbeat-monitoring" + }, + { + "source": "/ai-copilot/design/setup", + "destination": "/ai/rewriter/setup" + }, + { + "source": "/users/client-side/setup", + "destination": "/key-concepts/overview#users" + }, + { + "source": "/users/server-side/api-reset-contact-list", + "destination": "/api-reference/rest-apis/v2/users/delete-users" + }, + { + "source": "/ui-customization/custom-action-component", + "destination": "/ui-customization/wireframes/action-components" + }, + { + "source": "/collaboration/version-history", + "destination": "/realtime-collaboration/crdt/overview" + }, + { + "source": "/realtime-collaboration/crdt/version-history", + "destination": "/realtime-collaboration/crdt/overview" + }, + { + "source": "/ui-customization/features/async/notifications/notifications-tool", + "destination": "/ui-customization/features/async/notifications/notifications-tool/wireframes" + }, + { + "source": "/ui-customization/features/async/notifications/notifications-panel", + "destination": "/ui-customization/features/async/notifications/notifications-panel/wireframes" + }, + { + "source": "/ui-customization/features/async/notifications/notifications-primitives", + "destination": "/ui-customization/features/async/notifications/notifications-panel/primitives" + }, + { + "source": "/ui-customization/features/async/comments/comment-bubble", + "destination": "/ui-customization/features/async/comments/comment-bubble/wireframes" + }, + { + "source": "/ui-customization/features/async/comments/comment-pin", + "destination": "/ui-customization/features/async/comments/comment-pin/wireframes" + }, + { + "source": "/ui-customization/features/async/comments/comment-sidebar-button", + "destination": "/ui-customization/features/async/comments/comment-sidebar-button/wireframes" + }, + { + "source": "/ui-customization/features/async/comments/inline-comments-section", + "destination": "/ui-customization/features/async/comments/inline-comments-section/wireframes" + }, + { + "source": "/ui-customization/features/async/comments/multithread-comment-dialog", + "destination": "/ui-customization/features/async/comments/multithread-comments/wireframes" + }, + { + "source": "/ui-customization/features/async/comments/text-comment-tool", + "destination": "/ui-customization/features/async/comments/text-comment/text-comment-tool/wireframes" + }, + { + "source": "/ui-customization/features/async/comments/text-comment-toolbar", + "destination": "/ui-customization/features/async/comments/text-comment/text-comment-toolbar/wireframes" }, { "source": "/ui-customization/features/async/comments/comment-dialog-components", @@ -1608,30 +1778,6 @@ { "source": "/ui-customization/features/async/comments/inline-comments-section/subcomponents/panel/sorting-dropdown", "destination": "/ui-customization/features/async/comments/inline-comments-section/wireframes" - }, - { - "source": "/realtime-collaboration/presence/heartbeat", - "destination": "/realtime-collaboration/presence/overview#heartbeat-monitoring" - }, - { - "source": "/ai-copilot/design/setup", - "destination": "/ai/rewriter/setup" - }, - { - "source": "/users/client-side/setup", - "destination": "/key-concepts/overview#users" - }, - { - "source": "/users/server-side/api-reset-contact-list", - "destination": "/api-reference/rest-apis/v2/users/delete-users" - }, - { - "source": "/collaboration/version-history", - "destination": "/realtime-collaboration/crdt/overview" - }, - { - "source": "/realtime-collaboration/crdt/version-history", - "destination": "/realtime-collaboration/crdt/overview" } ], "logo": { diff --git a/get-started/agentic-overview.mdx b/get-started/agentic-overview.mdx index f1a8e8707..13b8607ac 100644 --- a/get-started/agentic-overview.mdx +++ b/get-started/agentic-overview.mdx @@ -1,41 +1,54 @@ --- title: "Overview" -description: "Use AI coding agents to build with Velt. Understand how plugins, the MCP installer, skills, the CLI, and the Velt Docs MCP work together." +description: "Use AI coding agents to build with Velt. Understand how the installation plugin, UI customization plugin, MCP installer, skills, CLI, and Velt Docs MCP work together." --- -Velt provides a layered AI toolchain that helps coding agents write correct Velt integration code on the first try. Think of it like a combo meal: each component plays a distinct role, and together they give your AI agent everything it needs. +Velt gives your AI coding agent the knowledge and tools to set up the SDK, add features, and customize the UI correctly the first time. Pick the path that matches what you're doing: -| Component | Role | Analogy | -|-----------|------|---------| -| **[Plugin](/get-started/plugins)** | Combo meal packaging: bundles skills, rules, an agent persona, and MCP servers into one install | The box | -| **[MCP Installer](/get-started/mcp-installer)** | WHAT to do, WHEN, in what ORDER: guided setup with codebase scanning and plan generation | The recipe card | -| **[Skills](/get-started/skills)** | HOW to implement Velt features and code: 277 prioritized rules with correct/incorrect patterns | The cookbook | -| **[CLI](/get-started/cli)** | Quick-start scaffolding (login, setup doc, user). Non-interactive, flag-driven setup | The pre-made base | -| **[Velt Docs MCP](/mcp/mcp#docs-mcp-server)** | FALLBACK ONLY when skills don't cover it. Search Velt docs directly from your editor | Emergency hotline | +| Tool | What it does | +|------|----------------| +| **[Installation Plugin](/get-started/installation-plugin)** | One install for Cursor or Claude Code: skills, rules, `velt-expert` agent, and MCP servers for SDK setup and feature work | +| **[MCP Installer](/get-started/mcp-installer)** | Guided Velt setup that scans your codebase, proposes a plan, and walks through install steps | +| **[UI Customization Plugin](/get-started/ui-customization-plugin)** | Turns a Figma design into verified Velt UI customization (comments + notifications) | +| **[Skills](/get-started/skills)** | Implementation rules and patterns your agent follows when writing Velt code | +| **[CLI](/get-started/cli)** | Terminal scaffolding for Next.js (no AI agent required) | +| **[Velt Docs MCP](/get-started/docs-mcp)** | Live docs search when skills don't cover a question | ## How They Fit Together ``` -Plugin (the box) -├── MCP Installer (the recipe card) → plans and executes setup steps -├── Skills (the cookbook) → teaches correct Velt patterns -├── CLI (the pre-made base) → quick-start scaffolding -└── Velt Docs MCP (emergency hotline) → fallback docs search +Set up Velt in your app +├── Installation Plugin → full package (recommended) +│ ├── MCP Installer → guided install plan +│ ├── Skills → correct SDK patterns +│ ├── CLI → optional scaffolding +│ └── Docs MCP → fallback docs search +└── or MCP Installer + Skills / CLI on their own + +Customize Velt UI to match your design +└── UI Customization Plugin → Figma → plan → build → verify + (requires Velt already installed and rendering) ``` -The **Plugin** is the recommended starting point. It installs everything in one step. If you only need part of the stack, each component also works standalone. +Start with the **Installation Plugin** to get Velt into your app. When the default UI is working, use the **UI Customization Plugin** to match a Figma design. Each piece also works standalone if you only need part of the stack. ## Choose Your Path - - Full package for Cursor or Claude Code. Installs skills, rules, MCP servers, and the velt-expert agent persona. + + Full package for Cursor or Claude Code. Installs skills, rules, MCP servers, and the velt-expert agent persona for SDK setup. AI-guided setup with codebase scanning. Works with Claude Code, Cursor, Windsurf, and Claude Desktop. + + Figma → verified Velt UI customization for Cursor or Claude Code. Builds CSS, wireframes, or primitives and checks each surface in a live browser. + - Install 267 implementation rules for any AI agent. Works with Claude Code, Cursor, GitHub Copilot, and more. + Install 282 implementation rules for any AI agent. Works with Claude Code, Cursor, GitHub Copilot, and more. + + + Search Velt documentation from Claude, Claude Code, Cursor, or VS Code. Non-interactive, flag-driven scaffolding for Next.js. No AI agent required. @@ -46,25 +59,29 @@ The **Plugin** is the recommended starting point. It installs everything in one | Scenario | Use | |----------|-----| -| First time setting up Velt with an AI editor | **Plugin**: gives your agent everything at once | -| Already have the plugin, adding a new feature | Your agent uses **Skills** automatically when it detects a Velt task | -| Using an editor without plugin support | **MCP Installer** + **Skills** installed separately | -| Want terminal-only setup, no AI agent | **CLI** with feature flags | -| Agent can't find the answer in skills | **Velt Docs MCP** searches the full documentation | +| First time setting up Velt with an AI editor | **Installation Plugin** | +| Already set up, adding a new feature | **Skills** (included in the installation plugin) | +| Matching Velt UI to a Figma design | **UI Customization Plugin** | +| Editor without plugin support | **MCP Installer** + **Skills** separately | +| Terminal-only setup, no AI agent | **CLI** | +| Agent can't find the answer in skills | **Velt Docs MCP** | ## What Each Component Provides -### Plugin -Bundles all components below into a single install for Cursor or Claude Code. Includes 2 slash-command skills (`/install-velt`, `/velt-help`), 13 bundled agent-skill packages (277 rules), 6 embedded best-practice rules, 1 agent persona (`velt-expert`), and 2 MCP servers. +### Installation Plugin +Bundles skills, rules, an agent persona, and MCP servers into a single install for Cursor or Claude Code. Use it to set up and extend the Velt SDK. Includes 2 slash-command skills (`/install-velt`, `/velt-help`), 14 bundled agent-skill packages (282 rules), 6 embedded best-practice rules, 1 agent persona (`velt-expert`), and 2 MCP servers. ### MCP Installer An MCP server that your AI agent uses to run guided Velt setup. It scans your codebase, detects your auth system and document structure, generates an implementation plan, and executes the plan with your approval. Supports both guided mode and CLI-only mode. +### UI Customization Plugin +A separate Cursor / Claude Code plugin that turns a Figma Loop into working Velt UI customization (comments + notifications). It plans per surface, builds CSS / wireframes / primitives, and verifies each result against the design in a live browser. See [UI Customization Plugin](/get-started/ui-customization-plugin). Requires Velt already installed and rendering in your app. + ### Skills -Structured knowledge packages containing prioritized rules with correct and incorrect code patterns, verification checklists, and source pointers. Available for 13 Velt feature areas: Setup, Comments, CRDT, Notifications, Recorder, Single Editor Mode, Self-Hosting Data, Activity Logs, Presence, Cursors, Huddle, REST APIs, and Proxy Server. +Structured knowledge packages containing prioritized rules with correct and incorrect code patterns, verification checklists, and source pointers. Available for 14 Velt feature areas: Setup, Comments, CRDT, Notifications, Recorder, Single Editor Mode, Self-Hosting Data, Activity Logs, Presence, Cursors, Huddle, REST APIs, Proxy Server, and AI Rewriter. ### CLI A terminal command (`npx @velt-js/add-velt`) that scaffolds Velt into a Next.js project. Installs dependencies, generates components, and wires `VeltProvider` into your app layout. Supports feature flags for comments, notifications, presence, cursors, and CRDT. ### Velt Docs MCP -An MCP server that searches Velt's documentation. Use it as a fallback when skills don't cover your specific question. Available for Claude, Claude Code, Cursor, and VS Code. +An MCP server that searches Velt's documentation. Use it as a fallback when skills don't cover your specific question. Available for Claude, Claude Code, Cursor, and VS Code. See [Velt Docs MCP](/get-started/docs-mcp). diff --git a/get-started/docs-mcp.mdx b/get-started/docs-mcp.mdx new file mode 100644 index 000000000..2baa8b22e --- /dev/null +++ b/get-started/docs-mcp.mdx @@ -0,0 +1,138 @@ +--- +title: "Velt Docs MCP" +description: "Search and browse Velt documentation from Cursor, Claude, Claude Code, VS Code, and other MCP-compatible clients." +--- + +Search and browse Velt's documentation directly in your MCP-compatible editor. The Docs MCP server helps you find SDK, API, and feature info without leaving your editor. + +Endpoint: `https://velt.dev/docs/mcp` + +## When to Use + +- You want docs answers in Cursor, Claude, Claude Code, or VS Code while coding +- Skills or the installation plugin don't cover a specific question +- You need quick lookup of setup steps, APIs, or feature guides + + + For guided Velt **installation**, use the [Velt Installation MCP](/get-started/mcp-installer). For REST API data access, see [MCP Servers](/mcp/mcp). + + +## Setup + + + + To use the Velt Docs MCP server with Claude: + + + + 1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings. + 2. Select **Add custom connector**. + 3. Add the Velt Docs MCP server: + + * Name: `Velt` + * URL: `https://velt.dev/docs/mcp` + + 4. Select **Add**. + + + + 1. When using Claude, select the attachments button (the plus icon). + 2. Select the Velt Docs MCP server. + 3. Ask Claude a question about Velt. + + + + See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details. + + + + To use the Velt Docs MCP server with Claude Code, run the following command: + + ```bash + claude mcp add --transport http Velt https://velt.dev/docs/mcp + ``` + + Test the connection by running: + + ```bash + claude mcp list + ``` + + See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details. + + + + Install in Cursor + + To connect the Velt Docs MCP server to Cursor, follow these steps: + + + + 1. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open the command palette. + 2. Search for "Open MCP settings". + 3. Select **Add custom MCP**. This will open the `mcp.json` file. + + + + In `mcp.json`, add: + + ```json + { + "mcpServers": { + "Velt": { + "url": "https://velt.dev/docs/mcp" + } + } + } + ``` + + + + In Cursor's chat, ask "What tools do you have available?" Cursor should show the Velt Docs MCP server as an available tool. + + + + See [Installing MCP servers](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) in the Cursor documentation for more details. + + + + Install in VS Code + + To connect the Velt Docs MCP server to VS Code, click the **Install in VS Code** button. Or to manually connect the MCP server, create a `.vscode/mcp.json` file and add: + + ```json + { + "servers": { + "Velt": { + "type": "http", + "url": "https://velt.dev/docs/mcp" + } + } + } + ``` + + See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details. + + + +## Example Usage + +Once the Velt Docs MCP server is configured, search for documentation from your client. + +For example, in Cursor, ask: + +**Query:** +`how to add Velt popover comments?` + +**Result:** +The MCP returns relevant documentation pages and snippets related to adding popover comments. + +**More examples:** +- `Generate sample data for adding Velt comment annotations via Velt Rest API` + +## Next Steps + +* [Installation Plugin](/get-started/installation-plugin): bundles Docs MCP with skills and rules +* [Velt Installation MCP](/get-started/mcp-installer): guided SDK install +* [Agent Skills](/get-started/skills): offline implementation patterns +* [REST APIs MCP](/mcp/mcp): query and mutate Velt data via REST APIs diff --git a/get-started/plugins.mdx b/get-started/installation-plugin.mdx similarity index 93% rename from get-started/plugins.mdx rename to get-started/installation-plugin.mdx index c10c7f769..26750bccc 100644 --- a/get-started/plugins.mdx +++ b/get-started/installation-plugin.mdx @@ -1,9 +1,9 @@ --- -title: "AI Plugins" -description: "Install the Velt plugin in Cursor or Claude Code to get skills, rules, an expert agent, and MCP servers for building with the Velt SDK." +title: "Installation Plugin" +description: "Install the Velt installation plugin in Cursor or Claude Code to get skills, rules, an expert agent, and MCP servers for setting up and building with the Velt SDK." --- -Add Velt collaboration knowledge directly into your AI coding editor. The Velt AI plugin gives your AI agent access to slash-command skills, 14 bundled agent-skills (282 implementation rules), 6 embedded best-practice rules, a `velt-expert` agent persona, and two MCP servers, so it can scaffold, debug, and extend Velt features with accurate, up-to-date patterns. +Add Velt collaboration knowledge directly into your AI coding editor. The Velt **installation plugin** gives your AI agent access to slash-command skills, 14 bundled agent-skills (282 implementation rules), 6 embedded best-practice rules, a `velt-expert` agent persona, and two MCP servers, so it can scaffold, debug, and extend Velt features with accurate, up-to-date patterns. @@ -14,18 +14,19 @@ Add Velt collaboration knowledge directly into your AI coding editor. The Velt A -## When to Use AI Plugins +## When to Use the Installation Plugin -- You are building with Velt in Cursor or Claude Code and want your AI agent to have deep Velt SDK knowledge +- You are setting up or building with Velt in Cursor or Claude Code and want your AI agent to have deep Velt SDK knowledge - You want slash-command skills like `/install-velt`, `/add-comments`, or `/velt-help` available in your editor - You want always-on rules that prevent common Velt integration mistakes (e.g., incorrect `VeltProvider` placement, missing `setDocuments`) - You want the `velt-expert` agent persona for architecture and integration guidance -AI plugins bundle MCP servers, skills, rules, and an agent into a single installable package. If you only need one of these: +The installation plugin bundles MCP servers, skills, rules, and an agent into a single installable package for SDK setup and feature work. If you only need one of these: - **MCP servers only**: See the [MCP Installer](/get-started/mcp-installer) - **Skills only** (for any AI agent): See [Agent Skills](/get-started/skills) - **No AI agent**: See the [CLI](/get-started/cli) +- **Matching Velt UI to a Figma design**: See the [UI Customization Plugin](/get-started/ui-customization-plugin) ## Prerequisites @@ -379,6 +380,7 @@ Ensure you are pointing at `velt-plugin-claude`, not `velt-plugin-cursor`. The C ## Next Steps +- **[UI Customization Plugin](/get-started/ui-customization-plugin)**: Turn a Figma design into verified Velt UI customization - **[MCP Installer](/get-started/mcp-installer)**: AI-assisted Velt installation through MCP (without the full plugin) - **[Agent Skills](/get-started/skills)**: Standalone skill packages for any AI coding agent - **[CLI](/get-started/cli)**: Terminal-based Velt setup without an AI agent diff --git a/get-started/ui-customization-plugin.mdx b/get-started/ui-customization-plugin.mdx new file mode 100644 index 000000000..b8f222656 --- /dev/null +++ b/get-started/ui-customization-plugin.mdx @@ -0,0 +1,188 @@ +--- +title: "UI Customization Plugin" +description: "Install the velt-customize plugin in Cursor or Claude Code to turn a Figma design into clean Velt UI customization (comments + notifications) on your React app." +--- + +Turn a **Figma design** into working **Velt UI customization** directly in your AI coding editor. The `velt-customize` plugin reads your design from Figma, plans the customization surface by surface, builds it in your app, and verifies each result against the design in a real browser, or honestly reports what the Velt SDK can't do yet. + + + + velt-js/velt-figma-plugin-cursor + + + + velt-js/velt-figma-plugin-claude + + + +## When to Use + +* You have a Figma design for how Velt comments or notifications should look in your product +* You want your AI agent to build the customization for you (CSS, wireframes, or primitives) instead of hand-writing it +* You want every result verified against the design in a live browser, not just generated and hoped for + +**No Figma design?** Follow the [UI Customization guide](/ui-customization/overview) manually; the plugin currently requires Figma. + + + This plugin customizes Velt's **UI** on an app where Velt is already installed and working. If you haven't set up Velt yet, start with the [Installation Plugin](/get-started/installation-plugin) or [Quickstart](/get-started/quickstart) first. + + +## Prerequisites + +* **Node.js** 18+ +* A **React app** with `@veltdev/react` installed, authenticated, and rendering Velt's default UI +* A **Figma design** of your desired Velt UI, plus a [Figma personal access token](https://www.figma.com/developers/api#access-tokens) (figma.com → Settings → Security → Personal access tokens) +* **Chrome** with the Claude in Chrome extension (Claude Code), or Cursor's built-in browser, to verify results against the design +* **`playwright-core`** (Cursor install step below) for device-resolution screenshot capture + +## Quickstart + + + + 1. Clone the plugin repository and install it: + + ```bash + git clone https://github.com/velt-js/velt-figma-plugin-cursor.git + cd velt-figma-plugin-cursor + npm run all + ``` + + This validates the plugin and copies its skills, rules, commands, and agents into `~/.cursor/`. **Fully restart Cursor** afterwards. If you later move the repo or pull updates, run `npm run all` again. + + 2. Store your Figma token (kept in your OS keychain, never in a file): + + ```bash + node scripts/figma-extract.mjs token set + ``` + + 3. Install the one screenshot dependency: + + ```bash + npm i -g playwright-core + ``` + + 4. Open **your app's repo** in Cursor (not the plugin repo), make sure the app is running, and start a run: + + ``` + /velt-customize-run --mode "wireframes + primitives" --budget balanced + ``` + + `` is the exact page where Velt renders in your running app (e.g. `http://localhost:3000/inline-comments?documentId=my-run-1`). Include a run-unique `documentId` so runs never pollute each other's comment data. + + + + 1. Inside Claude Code, install the plugin and restart: + + ``` + /plugin marketplace add velt-js/velt-figma-plugin-claude + /plugin install velt-customize@velt-customize + ``` + + Then restart Claude Code (or run `/reload-plugins`). + + 2. Store your Figma token (kept in your OS keychain, never in a file). Run this **inside Claude Code** (`$CLAUDE_PLUGIN_ROOT` only exists there), or just ask Claude to run it: + + ```bash + node "$CLAUDE_PLUGIN_ROOT/scripts/figma-extract.mjs" token set + ``` + + 3. Connect the **Claude in Chrome** extension. The plugin uses Chrome to check your running app against the design. + + 4. Open your app's folder in Claude Code, make sure your dev server can run, and start a run: + + ``` + /velt-customize:run --mode "wireframes + primitives" --budget balanced + ``` + + `` is the exact page where Velt renders in your running app (e.g. `http://localhost:3000/inline-comments?documentId=my-run-1`). Include a run-unique `documentId` so runs never pollute each other's comment data. + + + + + A **Loop** is just a Figma section or frame that groups the design frames you want built, in order. The Figma URL must point at one Loop node in your file (right-click the Loop → Copy link), not the whole file. Keep a Loop to 8 frames or fewer; split bigger designs into several Loops and run them one at a time. The app URL is **required** too; without it the run halts and asks for it. Preflight verifies that Velt actually renders at that URL. + + + + A full customization run can take **up to about 4 hours**, depending on Loop size, `--budget`, and how many fix iterations the verification agent (the Judge) needs. Plan to leave the editor and app running until the handoff report finishes. + + +### Run Options + +| Flag | Values | Description | +| ---------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| `--mode` | `strictly wireframe`, `strictly primitives`, `wireframes + primitives`, `freeform` | How the plugin is allowed to build; these correspond to the [Wireframes](/ui-customization/layout) and [Primitives](/ui-customization/primitives) approaches. Leave it out and it asks you, with a recommendation | +| `--budget` | `strict`, `balanced`, `thorough` | How much polish effort per design frame/surface, also caps fix iterations per defect (6 / 8 / 12) | +| `--auto` | - | Fully unattended run (CI/cloud): no questions asked. Requires `--mode`; reads the Figma token from the `FIGMA_TOKEN` environment variable. `--cloud` is a legacy alias | + +## What's Included + +| Resource | Count | Description | +| ------------ | ----- | ---------------------------------------------------------------------------------------------------------------------------------- | +| **Commands** | 5 | Run, fix, replay, clear, and memory (see below) | +| **Agents** | 6 | `velt-orchestrator` (drives the run), `velt-planner-structure` and `velt-planner-style` (plan structure, then styles against the real rendered DOM), `velt-builder` (builds), `velt-judge-2` (independently verifies), `velt-judge` (legacy) | +| **Skills** | 14 | Customization approaches (CSS, wireframes, primitives), extraction, verification, comments, notifications, references, and rules | +| **Guide** | 1 | A bundled customization knowledge base: the single source of truth the agents read on every run (same content as the [UI Customization](/ui-customization/overview) docs) | + +## Available Commands + +| Cursor | Claude Code | Description | +| ------------------------------- | ------------------------------ | ----------------------------------------------------------------------- | +| `/velt-customize-run ` | `/velt-customize:run ` | Start a customization run from a Figma Loop node URL and live app page | +| `/velt-customize-fix ""` | `/velt-customize:fix ""`| Surgically fix one described mismatch, then re-verify the affected area | +| `/velt-customize-replay` | `/velt-customize:replay` | Open the session-replay player for every stage, measurement, and fix of a run, with screenshots | +| `/velt-customize-clear` | `/velt-customize:clear` | Wipe run state and start fresh (does not touch generated code) | +| `/velt-customize-memory` | `/velt-customize:memory` | Inspect what the plugin has learned across runs | + +## How It Works + +Each run follows a plan → approve → two-phase build → verify loop: + +1. **Plan structure**: reads your Figma Loop via the Figma REST API, recognizes which Velt component each design element is, and picks the cheapest viable approach per surface +2. **Approach gate**: shows you a per-surface coverage matrix with a recommendation and **waits for your confirmation** before building anything +3. **Structure build**: mounts a bare wireframe skeleton (no cosmetic CSS) family by family +4. **DOM snapshot → style plan → style build**: snapshots the real rendered DOM, maps the design's exact values onto real selectors, then applies styles +5. **Judge → fix**: an independent fresh-context Judge (`velt-judge-2`) verifies the whole design in a live browser with screenshot evidence. Each defect is fixed and re-measured until it's clean, or documented as a blocker or SDK gap +6. **Report**: coverage achieved, screenshots, any SDK gaps, and the generated code under `components/velt/ui-customization/` + +You can watch progress live from a second terminal: + + + + ```bash + node /path/to/velt-figma-plugin-cursor/scripts/progress.mjs --watch + ``` + + + ```bash + node "$CLAUDE_PLUGIN_ROOT/scripts/progress.mjs" --watch + ``` + + + +After a run, `/velt-customize-replay` (Cursor) or `/velt-customize:replay` (Claude Code) opens a session-replay player over every stage, measurement, and fix, with screenshots, so you can scrub to where something drifted. + +## Troubleshooting + +### The run halts at preflight + +Preflight checks every prerequisite (Figma token, browser, target app URL, Node version) and halts with the exact fix if any is missing. Follow the printed instruction and re-run the command. + +### "No Figma token" error + +Design intake uses the Figma REST API and requires a token. There is no Figma desktop fallback. Store one with `figma-extract.mjs token set`, or set the `FIGMA_TOKEN` environment variable in CI/cloud environments. Verify with `figma-extract.mjs token status`. + +### Commands don't appear after install + +Restart your editor fully. Cursor loads plugin files from `~/.cursor/` (re-run `npm run all` after moving or updating the repo), and Claude Code registers plugin commands at startup (or use `/reload-plugins`). + +### App URL doesn't render Velt + +Pass the exact page where Velt comments or notifications are mounted, not just the app origin. Preflight verifies that URL; if Velt isn't there, fix the URL and re-run. Include a unique `documentId` query param so concurrent runs don't share comment data. + +--- + +## Next Steps + +* [UI Customization](/ui-customization/overview): the customization guide the plugin agents read on every run +* [Installation Plugin](/get-started/installation-plugin): Velt SDK knowledge, skills, and MCP servers for your editor +* [Quickstart](/get-started/quickstart): set up Velt in your app first diff --git a/mcp/mcp.mdx b/mcp/mcp.mdx index d127973a6..915feca21 100644 --- a/mcp/mcp.mdx +++ b/mcp/mcp.mdx @@ -1,12 +1,14 @@ --- -title: MCP Servers (Beta) +title: "REST APIs MCP Server (Beta)" +sidebarTitle: "REST APIs MCP" +description: "Interact with your Velt data from Cursor, Windsurf, Claude Desktop, and other MCP-compatible clients via the REST APIs MCP server." --- -## Overview +Interact with your Velt data directly from MCP-compatible clients such as Cursor, Windsurf, and Claude Desktop. This server exposes Velt REST APIs as tools. -We provide two MCP servers: -- [REST APIs MCP Server](#rest-apis-mcp-server): Allows you to interact with your Velt data directly from various MCP compatible clients, such as Cursor, Windsurf, Claude Desktop, etc. -- [Docs MCP Server](#docs-mcp-server): Allows you to search and browse Velt's documentation directly within your MCP-compatible IDEs, like Cursor, Windsurf etc. This enables you to quickly find information about our SDKs, APIs, and features without having to leave your editor, streamlining your development workflow when implementing Velt. + + Looking for documentation search in your editor? See [Velt Docs MCP](/get-started/docs-mcp). For guided SDK install, see [Velt Installation MCP](/get-started/mcp-installer). + ## Supported MCP Clients @@ -16,11 +18,7 @@ The MCP server is compatible with any client that supports MCP. Here are few exa * [Windsurf](https://windsurf.dev/) * [Claude Desktop](https://www.anthropic.com/products/claude-desktop) -## REST APIs MCP Server - -This allows you to interact with your Velt data directly from various MCP compatible clients, such as Cursor, Windsurf, Claude Desktop, etc. - -### Tools +## Tools The MCP server exposes **all** the [Velt REST APIs](/api-reference/rest-apis/v2/workspace/create) as tools. Below you will find links to different collections of APIs: @@ -35,11 +33,11 @@ Below you will find links to different collections of APIs: * [Live State](/api-reference/rest-apis/v2/livestate/broadcast-event) * [Workspace](/api-reference/rest-apis/v2/workspace/add-domain) -### Setup +## Setup You can set up the REST API MCP Server using any of the following methods. Note you will be required to provide your Velt API key and Velt Auth token to the MCP server. -#### Using Smithery CLI +### Using Smithery CLI The easiest way to get started is by using the `@smithery/cli` package installer. This will automatically download and configure the MCP server for your chosen client. You can visit: https://smithery.ai/server/@velt-js/velt-api-mcp to see the list of clients supported by the MCP server and steps to install it. Here are some examples: @@ -81,7 +79,7 @@ npx -y @smithery/cli install @velt-js/velt-api-mcp --client vscode -#### Manual Configuration +### Manual Configuration If you prefer to configure the server manually, follow these steps. @@ -166,7 +164,8 @@ Here are some examples: -### Use cases +## Use cases + Once configured, you can interact with the Velt API through your MCP client. Here are some examples: 1. **Querying Velt Data:** @@ -237,121 +236,3 @@ root_agent = Agent( ], ) ``` - - -## Docs MCP Server - -The Velt Docs MCP Server allows you to search and browse Velt's documentation directly within your MCP-compatible client, like Cursor, Windsurf, Claude Desktop and more. This enables you to quickly find information about our SDKs, APIs, and features without having to leave your editor, streamlining your development workflow when implementing Velt. - -### Setup - - - - To use the Velt Docs MCP server with Claude: - - - - 1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings. - 2. Select **Add custom connector**. - 3. Add the Velt Docs MCP server: - - * Name: `Velt` - * URL: `https://velt.dev/docs/mcp` - - 4. Select **Add**. - - - - 1. When using Claude, select the attachments button (the plus icon). - 2. Select the Velt Docs MCP server. - 3. Ask Claude a question about Velt. - - - - See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details. - - - - To use the Velt Docs MCP server with Claude Code, run the following command: - - ```bash - claude mcp add --transport http Velt https://velt.dev/docs/mcp - ``` - - Test the connection by running: - - ```bash - claude mcp list - ``` - - See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details. - - - - Install in Cursor - - To connect the Velt Docs MCP server to Cursor, follow these steps: - - - - 1. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open the command palette. - 2. Search for "Open MCP settings". - 3. Select **Add custom MCP**. This will open the `mcp.json` file. - - - - In `mcp.json`, add: - - ```json - { - "mcpServers": { - "Velt": { - "url": "https://velt.dev/docs/mcp" - } - } - } - ``` - - - - In Cursor's chat, ask "What tools do you have available?" Cursor should show the Velt Docs MCP server as an available tool. - - - - See [Installing MCP servers](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) in the Cursor documentation for more details. - - - - Install in VS Code - - To connect the Velt Docs MCP server to VS Code, click the **Install in VS Code** button. Or to manually connect the MCP server, create a `.vscode/mcp.json` file and add: - - ```json - { - "servers": { - "Velt": { - "type": "http", - "url": "https://velt.dev/docs/mcp" - } - } - } - ``` - - See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details. - - - -### Example Usage - -Once the Velt Docs MCP Server is configured, you can use it to search for documentation from your client. - -For example, in Cursor, you can use questions like `how to add Velt popover comments?` in the chat to ask questions about Velt. - -**Query:** -`how to add Velt popover comments?` - -**Result:** -The MCP will return relevant documentation pages and snippets related to adding popover comments, allowing you to quickly access the information you need. - -**More examples:** -- `Generate sample data for adding Velt comment annotations via Velt Rest API` \ No newline at end of file diff --git a/public/custom.css b/public/custom.css new file mode 100644 index 000000000..e69de29bb diff --git a/realtime-collaboration/single-editor-mode/setup.mdx b/realtime-collaboration/single-editor-mode/setup.mdx index 2489728b5..b4ff2039b 100644 --- a/realtime-collaboration/single-editor-mode/setup.mdx +++ b/realtime-collaboration/single-editor-mode/setup.mdx @@ -26,7 +26,7 @@ Setup and initialize the Velt client by following the [Velt Setup Docs](/get-sta - Optionally scope the feature to specific containers. -- We recommend using the default UI for simplicity and velocity. You can customize it to change the look, feel and position of the UI. You can customize the UI by following [this guide](/ui-customization/features/realtime/single-editor-mode). +- We recommend using the default UI for simplicity and velocity. You can customize it to change the look, feel and position of the UI by following the [UI customization guide](/ui-customization/overview). - If you do want to create your UI from scratch then you can use the following APIs to create a similar UX: [Editor](/realtime-collaboration/single-editor-mode/customize-behavior#editor) and [Viewer](/realtime-collaboration/single-editor-mode/customize-behavior#viewer). diff --git a/release-notes/3-0-0.mdx b/release-notes/3-0-0.mdx index fef2b70ad..f0e877d6c 100644 --- a/release-notes/3-0-0.mdx +++ b/release-notes/3-0-0.mdx @@ -7,7 +7,7 @@ title: Version 3.0.0 ### Improvements - [**Comments**]: Added pagination in autocomplete option dropdown for improved performance. -- [**Comments**]: Added "Edit Comment" option in header options dropdown menu for editing the first comment. Only visible to comment author and admins. [Learn more](/ui-customization/features/async/comments/comment-dialog/subcomponents/options-dropdown). +- [**Comments**]: Added "Edit Comment" option in header options dropdown menu for editing the first comment. Only visible to comment author and admins. [Learn more](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree). - [**Recorder**]: Added `shadow dom` prop in Recorder Player component to control shadow DOM encapsulation. @@ -44,7 +44,7 @@ title: Version 3.0.0 ### Features -- [**UI Customization**]: Added additional CSS variables for z-index customization. [Learn more](/ui-customization/styling#themes). +- [**UI Customization**]: Added additional CSS variables for z-index customization. [Learn more](/ui-customization/reference/css-variables). - `--velt-comment-pin-z-index: 2147483557`: For Components like Comment Pin, Triangle, etc. - `--velt-arrow-z-index: 2147483557`: For Arrow Component. - `--velt-recorder-player-z-index: 2147483557`: For Recorder Player Component. @@ -80,7 +80,7 @@ title: Version 3.0.0 - Now just clicking on a comment doesn't open the comment on the DOM. - A lot of users reported this behaviour as frustrating. That's why now there is an explicit navigation button for that. - You will still get the [`onCommentClick`](/async-collaboration/comments-sidebar/customize-behavior#oncommentclick) event. You can still use that to maintain the old behavior [using this](/async-collaboration/comments/customize-behavior#selectcommentbyannotationid). - - If you had previously used a wireframe for the comment dialog, you will need to add the [navigation button wireframe](/ui-customization/features/async/comments/comment-dialog/wireframes#header) to show the navigation button. + - If you had previously used a wireframe for the comment dialog, you will need to add the [navigation button wireframe](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) to show the navigation button. - [**Comments**]: Added feature to show resolved comments on for inline comments section. - [**Comments**]: Disabled collapsed comments by default. Most customers don't want to show collapsed comments by default so we disabled it. You can enable it by setting using [this](/async-collaboration/comments/customize-behavior#enablecollapsedcomments). - [**Comments**]: Disabled auto-focus on new comments in inline comments section and sidebar page mode. @@ -115,7 +115,7 @@ title: Version 3.0.0 ### Features -- [**Velt Button**]: Added a customizable button component that can be used to add custom actions and extend the functionality of any Velt component. [Learn more](/ui-customization/custom-action-component). Some examples include: +- [**Velt Button**]: Added a customizable button component that can be used to add custom actions and extend the functionality of any Velt component. [Learn more](/ui-customization/patterns-and-tips#bridge-a-wireframe-button-to-your-app-logic-the-onclick-escape-hatch). Some examples include: - Add custom filtering, sorting and grouping to the Comment Sidebar. - Add custom actions to each item in the Notifications panel. - Add custom actions to the Comment Dialog. @@ -126,7 +126,7 @@ title: Version 3.0.0 ### Improvements -- [**Comments**]: Added additional wireframes for Comment Dialog Toggle Reply Component. [Learn more](/ui-customization/features/async/comments/comment-dialog/subcomponents/body/subcomponents/togglereply). +- [**Comments**]: Added additional wireframes for Comment Dialog Toggle Reply Component. [Learn more](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree). - [**Comments**]: Now users can't submit empty comments during editing. - [**Comments**]: Improved the padding on the @mention autocomplete dropdown. - [**Ergonomics**]: Updated `useCommentActionCallback` to `useCommentEventCallback`. The old hook name will continue to work. @@ -1125,7 +1125,7 @@ title: Version 3.0.0 ### New Features - [**Comments**]: Added "Seen" Feature in the comment dialog. It shows which users have seen the comments. It's automatically enabled in the default component. - - If you had previously used a wireframe for the comment dialog, you will need to add the [seen component wireframe](/ui-customization/features/async/comments/comment-dialog/subcomponents/body/subcomponents/threadcard). + - If you had previously used a wireframe for the comment dialog, you will need to add the [seen component wireframe](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree). ![](/images/seen-feature.png) @@ -1207,7 +1207,7 @@ title: Version 3.0.0 - In this mode, when you click on a comment in the sidebar, it will open the thread in expanded view within the sidebar itself. - Other threads and actions like filters, search etc are hidden behind a back button. - Turning this on also adds a navigation button in the comment dialog. Clicking it will navigate to the comment and also trigger a callback. - - If you had previously used a wireframe for the comment dialog, you will need to add the [navigation button wireframe](/ui-customization/features/async/comments/comment-dialog/subcomponents/navigation-button) and the [focused thread wireframe](/ui-customization/features/async/comments/comments-sidebar/subcomponents/focused-thread). + - If you had previously used a wireframe for the comment dialog, you will need to add the [navigation button wireframe](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) and the [focused thread wireframe](/ui-customization/reference/component-catalog#sidebar-slot-trees). @@ -2199,7 +2199,7 @@ subscription?.unsubscribe() - On first attempt to close: Dialog shakes to indicate draft status. - On second attempt: the comment is saved as draft and the dialog closes. - Added a visual indicator for draft comments in the dialog. - - If you had previously used a wireframe for the comment dialog, you will need to add the [draft wireframe](/ui-customization/features/async/comments/comment-dialog/subcomponents/body/subcomponents/threadcard). + - If you had previously used a wireframe for the comment dialog, you will need to add the [draft wireframe](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree). @@ -2220,7 +2220,7 @@ subscription?.unsubscribe() - On first attempt to close: Dialog shakes to indicate draft status. - On second attempt: the comment is saved as draft and the dialog closes. - Added a visual indicator for draft comments in the dialog. - - If you had previously used a wireframe for the comment dialog, you will need to add the [draft wireframe](/ui-customization/features/async/comments/comment-dialog/subcomponents/body/subcomponents/threadcard). + - If you had previously used a wireframe for the comment dialog, you will need to add the [draft wireframe](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree). diff --git a/release-notes/archive/aug-13-2024.mdx b/release-notes/archive/aug-13-2024.mdx index 9739c2db7..ecb36628f 100644 --- a/release-notes/archive/aug-13-2024.mdx +++ b/release-notes/archive/aug-13-2024.mdx @@ -2,6 +2,6 @@ ### New Features -- [**UI Customization**]: Added [Confirm Dialog Wireframe](/ui-customization/features/async/comments/confirm-dialog/overview) and added support for light and dark modes. +- [**UI Customization**]: Added [Confirm Dialog Wireframe](/ui-customization/reference/component-catalog#comments) and added support for light and dark modes. - This is a common UI component used for multiple features like deleting comment thread, deleting a recorded content and more. - It will automatically inherit the light or dark mode property from the parent feature. \ No newline at end of file diff --git a/release-notes/archive/july-18-2024.mdx b/release-notes/archive/july-18-2024.mdx index fd30d203d..938daa154 100644 --- a/release-notes/archive/july-18-2024.mdx +++ b/release-notes/archive/july-18-2024.mdx @@ -36,7 +36,7 @@ commentElement.setPinCursorImage(BASE64_IMAGE_STRING); ## Added `placeholder` Support -We have added `placeholder` support for Comments DIalog within the `comment-dialog-composer-input-wireframe`. [Learn more](https://docs.velt.dev/ui-customization/features/async/comments/comment-dialog/subcomponents/composer/overview). +We have added `placeholder` support for Comments DIalog within the `comment-dialog-composer-input-wireframe`. [Learn more](https://docs.velt.dev/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree). ## Added `notificationSourceData` Field diff --git a/release-notes/archive/july-29-2024.mdx b/release-notes/archive/july-29-2024.mdx index a25bd9fcd..595105bfc 100644 --- a/release-notes/archive/july-29-2024.mdx +++ b/release-notes/archive/july-29-2024.mdx @@ -5,7 +5,7 @@ ## Added Wireframe for Custom Annotation Dropdown -We have added wireframes for custom annotation. [Learn more](https://docs.velt.dev/ui-customization/features/async/comments/comment-dialog/subcomponents/custom-annotation-dropdown). +We have added wireframes for custom annotation. [Learn more](https://docs.velt.dev/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree). ## Added Custom Annotation Dropdown Component Feature You can now customize annotation dropdown component feature. Create custom list data on annotation as required. diff --git a/release-notes/archive/july-31-2024.mdx b/release-notes/archive/july-31-2024.mdx index 1e8107c9e..37e495079 100644 --- a/release-notes/archive/july-31-2024.mdx +++ b/release-notes/archive/july-31-2024.mdx @@ -4,7 +4,7 @@ - Latest Types: [2.0.24](https://www.npmjs.com/package/@veltdev/types) ## Added the option to Subscribe/Unsubscribe at Thread Level -Within the comments dialog options dropdown, we have added subscribe/unsubscribe wireframes. [Learn more](/ui-customization/features/async/comments/comment-dialog/subcomponents/options-dropdown). +Within the comments dialog options dropdown, we have added subscribe/unsubscribe wireframes. [Learn more](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree). ```jsx @@ -30,7 +30,7 @@ Users can now add an optional custom initial within the [user object](https://do We have added the feature to search on organization names in the contact list, if present. ## Added Delete Button on the Thread Header -You can now add a delete button within the comments dialog thread header. [Learn more](/ui-customization/features/async/comments/comment-dialog/wireframes#header). +You can now add a delete button within the comments dialog thread header. [Learn more](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree). ```jsx diff --git a/release-notes/archive/june-6-2024.mdx b/release-notes/archive/june-6-2024.mdx index 9d91cd796..7d4efb64d 100644 --- a/release-notes/archive/june-6-2024.mdx +++ b/release-notes/archive/june-6-2024.mdx @@ -11,29 +11,29 @@ In this update, we made several improvements to the `Customization` of the `Comm We modified or added support for customizing the following `subcomponents` of the `Comments Sidebar`: - - [Filter](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/overview) - - [Filter Category](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/category) - - [Filter Close Button](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/close-button) - - [Filter Done Button](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/done-button) - - [Filter Item](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/filter-item) - - [Filter Groupby](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/groupby) - - [Filter Location](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/location) - - [Filter People](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/people) - - [Filter Priority](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/priority) - - [Filter Title](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/title) - - [Filter Versions](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/versions) - - [Header](/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/overview) - - [Header Status](/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/subcomponents/status/overview) - - [Header Status Trigger](/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/subcomponents/status/subcomponents/trigger) - - [Header Status Content](/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/subcomponents/status/subcomponents/content) - - [List](/ui-customization/features/async/comments/comments-sidebar/subcomponents/list/overview) - - [List Dialog Container](/ui-customization/features/async/comments/comments-sidebar/subcomponents/list/subcomponents/dialog-container) - - [List Group](/ui-customization/features/async/comments/comments-sidebar/subcomponents/list/subcomponents/group) + - [Filter](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [Filter Category](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [Filter Close Button](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [Filter Done Button](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [Filter Item](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [Filter Groupby](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [Filter Location](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [Filter People](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [Filter Priority](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [Filter Title](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [Filter Versions](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [Header](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [Header Status](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [Header Status Trigger](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [Header Status Content](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [List](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [List Dialog Container](/ui-customization/reference/component-catalog#sidebar-slot-trees) + - [List Group](/ui-customization/reference/component-catalog#sidebar-slot-trees) We modified or added support for customizing the following `subcomponents` of the `Sidebar Button`: - - [Sidebar Button](/ui-customization/features/async/comments/comments-sidebar/sidebar-button/overview) - - [Sidebar Button Icon](/ui-customization/features/async/comments/comments-sidebar/sidebar-button/subcomponents/icon) + - [Sidebar Button](/ui-customization/reference/component-catalog#comments) + - [Sidebar Button Icon](/ui-customization/reference/component-catalog#comments) ## Subcomponent Name Changes diff --git a/release-notes/archive/may-17-2024.mdx b/release-notes/archive/may-17-2024.mdx index 140057623..b4ea5d0ea 100644 --- a/release-notes/archive/may-17-2024.mdx +++ b/release-notes/archive/may-17-2024.mdx @@ -5,7 +5,7 @@ ## Added Variant support in customization -If you want to have multiple versions of customized components that you can swap between, you can use [variants](/ui-customization/layout#variants). +If you want to have multiple versions of customized components that you can swap between, you can use [variants](/ui-customization/layout#2-variants-multiple-looks-for-the-same-component). To define multiple `variants`, add multiple templates of the same component `wireframe` to the `VeltWireframe` component and give them each a `variant` name. diff --git a/release-notes/archive/may-24-2024.mdx b/release-notes/archive/may-24-2024.mdx index af11e4d97..efb4911a3 100644 --- a/release-notes/archive/may-24-2024.mdx +++ b/release-notes/archive/may-24-2024.mdx @@ -6,7 +6,7 @@ ## Added Skeleton loader subcomponent to Comments Sidebar Wireframe -The Comments Sidebar Wireframe now has a [Skeleton loader subcomponent](/ui-customization/features/async/comments/comment-sidebar-components) that you can modify. +The Comments Sidebar Wireframe now has a [Skeleton loader subcomponent](/ui-customization/reference/component-catalog#sidebar-slot-trees) that you can modify. ## Added functionality to search by name in @mention dropdown @@ -53,15 +53,15 @@ await client.identify(user); ## Added additional subcomponents to the Comments Dialog Wireframe The following subcomponents were added to the Comments Dialog Wireframe: - - [Priority Dropdown](/ui-customization/features/async/comments/comment-dialog/subcomponents/priority-dropdown) - - [Status Dropdown](/ui-customization/features/async/comments/comment-dialog/subcomponents/status-dropdown) - - [Options Dropdown](/ui-customization/features/async/comments/comment-dialog/subcomponents/options-dropdown) - - [Reaction Tool](/ui-customization/features/async/comments/comment-dialog/subcomponents/reaction-tool) - - [Reaction Pin](/ui-customization/features/async/comments/comment-dialog/subcomponents/reaction-pin) - - [Reactions Panel](/ui-customization/features/async/comments/comment-dialog/subcomponents/reactions-panel) - - [Reactions Pin Tooltip](/ui-customization/features/async/comments/comment-dialog/subcomponents/reaction-pin-tooltip) - - [Autocomplete Option](/ui-customization/features/async/comments/comment-dialog/subcomponents/autocomplete-option) - - [Autocomplete Chip Tooltip](/ui-customization/features/async/comments/comment-dialog/subcomponents/autocomplete-chip-tooltip) + - [Priority Dropdown](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) + - [Status Dropdown](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) + - [Options Dropdown](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) + - [Reaction Tool](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) + - [Reaction Pin](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) + - [Reactions Panel](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) + - [Reactions Pin Tooltip](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) + - [Autocomplete Option](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) + - [Autocomplete Chip Tooltip](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) ## Added support to set custom reactions @@ -107,13 +107,13 @@ commentElement.setCustomReactions(customReactions); ## Changed type in VeltCommentDialogWireframe.Composer.ActionButton from `file` to `attachments`. Keeping legacy support for `file`. -In the [Comment Dialog Wireframe](/ui-customization/features/async/comments/comment-dialog-components), we changed the type from `file` to `attachments` +In the [Comment Dialog Wireframe](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree), we changed the type from `file` to `attachments` `` -> `` ## Added support for customizing attachments in Comment Dialog -The `VeltCommentDialogWireframe.Composer.Attachments` and `VeltCommentDialogWireframe.ThreadCard.Attachments` subcomponents within the [Comment Dialog Wireframe](/ui-customization/features/async/comments/comment-dialog-components) now support customization. +The `VeltCommentDialogWireframe.Composer.Attachments` and `VeltCommentDialogWireframe.ThreadCard.Attachments` subcomponents within the [Comment Dialog Wireframe](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) now support customization. ## Added method listen to Comment Selection changes. diff --git a/release-notes/version-4/sdk-changelog.mdx b/release-notes/version-4/sdk-changelog.mdx index 4410f02a4..470a37d4c 100644 --- a/release-notes/version-4/sdk-changelog.mdx +++ b/release-notes/version-4/sdk-changelog.mdx @@ -1465,11 +1465,11 @@ export enum ReactionResolverModuleName { ### New Features -- [**Comments**]: Added mark as read/unread option in comment dialog. You can now toggle read status for individual comments. [See wireframe customization →](/ui-customization/features/async/comments/comment-dialog-components#optionscontentmarkasread) +- [**Comments**]: Added mark as read/unread option in comment dialog. You can now toggle read status for individual comments. [See wireframe customization →](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) - [**Comments**]: Added `unread` property to annotations. You can now check if an annotation is unread by the current user. See [`CommentAnnotation` data model](/api-reference/sdk/models/data-models#commentannotation). -- [**Comments**]: Added Open and Reset filters to sidebar minimal filter dropdown. Filter annotations by open status or clear all active filters. [See wireframe customization →](/ui-customization/features/async/comments/comment-sidebar-components#minimalfilterdropdowncontent) +- [**Comments**]: Added Open and Reset filters to sidebar minimal filter dropdown. Filter annotations by open status or clear all active filters. [See wireframe customization →](/ui-customization/reference/component-catalog#sidebar-slot-trees) - [**Comments**]: Added `context` prop to comment sidebar. Pass context data to page mode composer comments. @@ -1887,7 +1887,7 @@ export interface CommentBubbleClickedEvent { } ``` -- [**UI Customization**]: Added unread icon wireframes to sidebar buttons and comment bubbles. Display custom unread indicators for unread comments. [See sidebar button wireframes →](/ui-customization/features/async/comments/comment-sidebar-button#unreadicon) [See comment bubble wireframes →](/ui-customization/features/async/comments/comment-bubble#unreadicon) +- [**UI Customization**]: Added unread icon wireframes to sidebar buttons and comment bubbles. Display custom unread indicators for unread comments. [See comment surface wireframes →](/ui-customization/reference/component-catalog#comments) @@ -3107,11 +3107,11 @@ notificationElement.disableCurrentDocumentOnly(); ### New Features -- [**UI Customization**]: Added hide reply button wireframe for the comment dialog. [See wireframe customization →](/ui-customization/features/async/comments/comment-dialog-components#hidereply) +- [**UI Customization**]: Added hide reply button wireframe for the comment dialog. [See wireframe customization →](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) -- [**UI Customization**]: Added thread card reply button wireframe for the comment dialog to enable quick replies directly from comment thread cards. [See wireframe customization →](/ui-customization/features/async/comments/comment-dialog-components#threadcardreply) +- [**UI Customization**]: Added thread card reply button wireframe for the comment dialog to enable quick replies directly from comment thread cards. [See wireframe customization →](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) -- [**UI Customization**]: Added filter dropdown wireframe for the inline comments section. [See wireframe customization →](/ui-customization/features/async/comments/inline-comments-section#filterdropdown-panel) +- [**UI Customization**]: Added filter dropdown wireframe for the inline comments section. [See wireframe customization →](/ui-customization/features/async/comments/inline-comments-section/wireframes) - [**Comments**]: Added `allowedFileTypes` property to limit file types in comment attachments. @@ -3301,7 +3301,7 @@ commentElement.disableFullScreenInSidebar(); - [**Comments**]: Added search by annotation number in Comments Sidebar. You can now quickly find specific comments by typing their annotation number (e.g., `#2`) in the search field, making it faster to locate and navigate to referenced comments. ### UI Customization -- [**Comments**]: Added new wireframes to customize the appearance of comment annotation numbers and full-screen button in the Comments Sidebar. [See comment dialog wireframes →](/ui-customization/features/async/comments/comment-dialog-components#commentnumber) [See comment pin wireframes →](/ui-customization/features/async/comments/comment-pin#number) [See sidebar wireframes →](/ui-customization/features/async/comments/comment-sidebar-components#fullscreenbutton) +- [**Comments**]: Added new wireframes to customize the appearance of comment annotation numbers and full-screen button in the Comments Sidebar. [See comment wireframes →](/ui-customization/reference/component-catalog#comments) ### Bug Fixes - [**Recorder**]: Fixed Firefox compatibility issue that was preventing recordings from being stopped properly. @@ -3720,7 +3720,7 @@ await Velt.getUserPermissions(request as GetUserPermissionsRequest); ### New Features -- [**Comments**]: Updated default placeholders and added props to customize placeholders for comment and reply inputs. Added wireframes to allow users to customize how it looks. [See wireframe customization →](/ui-customization/features/async/comments/comment-dialog-components#composerinput) +- [**Comments**]: Updated default placeholders and added props to customize placeholders for comment and reply inputs. Added wireframes to allow users to customize how it looks. [See wireframe customization →](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) - Default placeholders: - Comment: "Comment or add others with @" - Reply: "Reply or add others with @" @@ -3755,9 +3755,9 @@ useEffect(() => { -- [**Comments**]: Added Edited chip in comment thread: Edits are now visibly transparent at a glance, improving auditability and helping reviewers quickly spot updated messages in long discussions. See [Comment Dialog components](/ui-customization/features/async/comments/comment-dialog-components). +- [**Comments**]: Added Edited chip in comment thread: Edits are now visibly transparent at a glance, improving auditability and helping reviewers quickly spot updated messages in long discussions. See [Comment Dialog components](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree). -**New wireframes added to customize "Edited" Chip:** [See wireframe customization →](/ui-customization/features/async/comments/comment-dialog-components#threadcardedited) +**New wireframes added to customize "Edited" Chip:** [See wireframe customization →](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) ### Bug Fixes - [**Comments**]: In `InlineCommentsSection` single-thread mode, count now reflects the number of Comments vs Comment Annotations. @@ -4920,7 +4920,7 @@ Note after this update, if you plan to go back to older version of the SDK befor - [Learn more](/realtime-collaboration/crdt/setup/tiptap) -- [**Video Editor**]: Added zoom button in video editor with [wireframes support](/ui-customization/features/async/recorder/video-editor#addzoombutton). +- [**Video Editor**]: Added zoom button in video editor with [wireframes support](/ui-customization/features/recorder-and-transcription). - [**Recorder**]: Added API to turn on/off the microphone on the recorder control panel. @@ -4951,7 +4951,7 @@ Note after this update, if you plan to go back to older version of the SDK befor ### New Features -- [**Comments**]: Added reply avatar component with [wireframes support](/ui-customization/features/async/comments/comment-dialog/subcomponents/body/subcomponents/replyavatars). This shows the avatars of unique users who have replied to a comment. +- [**Comments**]: Added reply avatar component with [wireframes support](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree). This shows the avatars of unique users who have replied to a comment. **Using props:** @@ -5010,7 +5010,7 @@ Note after this update, if you plan to go back to older version of the SDK befor ### New Features - [**Core**]: Added MCP Servers for: - **Velt REST APIs**: Allows you to interact with your Velt data directly from various MCP compatible clients, such as Cursor, Windsurf, Claude Desktop, etc. [Learn More](/mcp/mcp). - - **Velt Docs**: Allows you to search and browse Velt's documentation directly within your MCP-compatible IDEs, like Cursor, Windsurf etc. This enables you to quickly find information about our SDKs, APIs, and features without having to leave your editor, streamlining your development workflow when implementing Velt. [Learn More](/mcp/mcp). + - **Velt Docs**: Allows you to search and browse Velt's documentation directly within your MCP-compatible IDEs, like Cursor, Windsurf etc. This enables you to quickly find information about our SDKs, APIs, and features without having to leave your editor, streamlining your development workflow when implementing Velt. [Learn More](/get-started/docs-mcp). ### Bug Fixes - [**Comments**]: Minor UX fixes: @@ -5268,7 +5268,7 @@ Note after this update, if you plan to go back to older version of the SDK befor - [**Comments**]: Added ability to add custom filters via `FilterConfig`. 1. First enable custom actions. 2. Add custom filters in filter config. - 3. Add [custom filters wireframe](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/custom) to the sidebar wireframe. + 3. Add [custom filters wireframe](/ui-customization/reference/component-catalog#sidebar-slot-trees) to the sidebar wireframe. 4. Add callbacks to update sidebar data when the filters are used. @@ -5351,7 +5351,7 @@ Note after this update, if you plan to go back to older version of the SDK befor /> ``` - **3. Add [custom filters wireframe](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/custom) for each custom filter you added in filter config:** + **3. Add [custom filters wireframe](/ui-customization/reference/component-catalog#sidebar-slot-trees) for each custom filter you added in filter config:** ```jsx @@ -5930,7 +5930,7 @@ Velt.setDataProviders({ - Update settings programmatically with `setSettings()` API. [Learn more](/async-collaboration/notifications/customize-behavior#setsettings) - Get current settings with `getSettings()` API. [Learn more](/async-collaboration/notifications/customize-behavior#getsettings) - Subscribe to settings updates with `settingsUpdated` event. [Learn more](/async-collaboration/notifications/customize-behavior#on) - - Added wireframe components for notifications panel settings UI. [Learn more](/ui-customization/features/async/notifications/notifications-panel#settings) + - Added wireframe components for notifications panel settings UI. [Learn more](/ui-customization/features/notifications#wireframes-slot-trees--tokens) - Added Backend APIs to set and get notifications settings. [Learn more](/api-reference/rest-apis/v2/notifications/set-config) ### Improvements @@ -7293,7 +7293,7 @@ contactElement.getContactList().subscribe((response) => { ### New Features - [**Comments**]: Added a config to show expanded user groups inside the @mentions dropdown menu. - - Added [new wireframes](/ui-customization/features/async/comments/comment-dialog/subcomponents/autocomplete-group-option) to customize the display of user groups. + - Added [new wireframes](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) to customize the display of user groups. - Here are some props to control the display of user groups: - `expandMentionGroups`: Whether to expand the user groups and show individual users inside the groups in the @mentions dropdown menu. - `showMentionGroupsFirst`: Whether to show the user groups in the @mentions dropdown menu before the non-group users. @@ -7321,8 +7321,8 @@ contactElement.getContactList().subscribe((response) => { - [**Comments Sidebar**]: Added two new default system filters and their wireframes to the sidebar: - - `Tagged`: Filter comments by specifying the user who was tagged in the comment. ([Wireframe](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/tagged)) - - `Assigned`: Filter comments by specifying the user who was assigned to the comment. ([Wireframe](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/assigned)) + - `Tagged`: Filter comments by specifying the user who was tagged in the comment. ([Wireframe](/ui-customization/reference/component-catalog#sidebar-slot-trees)) + - `Assigned`: Filter comments by specifying the user who was assigned to the comment. ([Wireframe](/ui-customization/reference/component-catalog#sidebar-slot-trees)) ```typescript class CommentSidebarFilterConfig { @@ -7332,7 +7332,7 @@ contactElement.getContactList().subscribe((response) => { // ... existing properties ... } ``` -- [**Comments Sidebar**]: Added another UI pattern for filters options: searchable dropdown with checklist. ([Example Wireframe](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/tagged)) +- [**Comments Sidebar**]: Added another UI pattern for filters options: searchable dropdown with checklist. ([Example Wireframe](/ui-customization/reference/component-catalog#sidebar-slot-trees)) @@ -7347,7 +7347,7 @@ contactElement.getContactList().subscribe((response) => { -- [**Comments Sidebar**]: Added a reset filter button. ([Wireframe](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/reset-button)) +- [**Comments Sidebar**]: Added a reset filter button. ([Wireframe](/ui-customization/reference/component-catalog#sidebar-slot-trees)) - [**Comments Sidebar**]: Added prop to disable count calculation for sidebar filter options. @@ -7902,7 +7902,7 @@ client.setDataProviders({ ### New Features - [**Comments**]: Tiptap comments marks are now persisted automatically by default. This simplifies implementation as you no longer need to store marks yourself or modify your editor's content handling. -- [**Comments**]: Added Sorting Dropdown Wireframe support for inline comments section. [Learn more](/ui-customization/features/async/comments/inline-comments-section/subcomponents/panel/sorting-dropdown) +- [**Comments**]: Added Sorting Dropdown Wireframe support for inline comments section. [Learn more](/ui-customization/features/async/comments/inline-comments-section/wireframes) ### Improvements - [**Comments**]: Made the freestyle comment pins adapt to DOM elements with complex layouts. @@ -9187,7 +9187,7 @@ CommentAnnotationsCount { - [**Comments**]: Added support for Status Filter in Comments Sidebar's main filter menu: - By default, the status filter is disabled in the main filter menu. - Currently, it doesn't support grouping. - - Added Wireframe support for this. [Learn more](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/status). + - Added Wireframe support for this. [Learn more](/ui-customization/reference/component-catalog#sidebar-slot-trees). - If you were using wireframes before, you will add this to your wireframes. diff --git a/release-notes/version-5/sdk-changelog.mdx b/release-notes/version-5/sdk-changelog.mdx index 8efcfd941..f8a8c05df 100644 --- a/release-notes/version-5/sdk-changelog.mdx +++ b/release-notes/version-5/sdk-changelog.mdx @@ -44,7 +44,7 @@ description: Release Notes of changes added to the core Velt SDK ### Bug Fixes -- [**Comments**]: "Hide replies" now fully collapses an inline comment thread back to its first-comment teaser. Previously, clicking "Hide replies" on an expanded thread left it partially expanded (first comment + last comment + divider) instead of returning to the teaser (first comment + "N replies" toggle). The collapse now mirrors clicking outside the thread: it deselects the annotation so the thread-card visibility logic shows the teaser, and the click no longer re-selects the annotation. Applies to the comment dialog/comment tool in both the HTML and React SDKs. [Learn more →](/ui-customization/features/async/comments/comment-dialog/wireframe-variables) +- [**Comments**]: "Hide replies" now fully collapses an inline comment thread back to its first-comment teaser. Previously, clicking "Hide replies" on an expanded thread left it partially expanded (first comment + last comment + divider) instead of returning to the teaser (first comment + "N replies" toggle). The collapse now mirrors clicking outside the thread: it deselects the annotation so the thread-card visibility logic shows the teaser, and the click no longer re-selects the annotation. Applies to the comment dialog/comment tool in both the HTML and React SDKs. [Learn more →](/ui-customization/template-variables) @@ -143,7 +143,7 @@ Velt.clearPageInfo(); ### Improvements -- [**Comments & Notifications**]: Added additional standalone primitive support across comments and notifications components. [Learn more →](/ui-customization/features/async/comments/comment-dialog/primitives) +- [**Comments & Notifications**]: Added additional standalone primitive support across comments and notifications components. [See primitive components →](/ui-customization/reference/primitives) - [**Notifications**]: The notification panel's People tab now shows per-user notification counts in org-mode sessions. @@ -435,7 +435,7 @@ commentElement.on('addCommentDraft').subscribe((event) => { -- [**Comments**]: Added download buttons for image and other file attachments in the edit comment dialog. [Learn more →](/ui-customization/features/async/comments/comment-dialog/primitives) +- [**Comments**]: Added download buttons for image and other file attachments in the edit comment dialog. [See comment dialog slots →](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) - [**Comments**]: Confirm dialog now uses variant CSS classes for comment and reply deletes, enabling easier styling. @@ -605,7 +605,7 @@ contactElement.updateContactList(contacts, { filters: true }); ### New Features -- [**Notifications**]: Added granular primitive components for `VeltNotificationsPanel` and `VeltNotificationsTool`, including — header tabs, content lists, settings accordion, skeleton, and more. Each primitive is standalone (not nested inside another) and supports `variant`, `darkMode`, `shadowDom`, and `parentLocalUIState` props. [Learn more →](/ui-customization/features/async/notifications/notifications-panel/primitives) +- [**Notifications**]: Added granular primitive components for `VeltNotificationsPanel` and `VeltNotificationsTool`, including header tabs, content lists, settings accordion, skeleton, and more. Each primitive is standalone (not nested inside another) and supports `variant`, `darkMode`, `shadowDom`, and `parentLocalUIState` props. [Learn more →](/ui-customization/features/async/notifications/notifications-panel/primitives) - [**Workspace REST API**]: Added 20 endpoints to create and manage Velt workspace covering workspace creation, API key management, auth tokens, domain management, email and webhook configuration, and API key metadata. [Learn more →](/api-reference/rest-apis/v2/workspace/create) @@ -824,7 +824,7 @@ authHost: 'auth-proxy.example.com', -- [**UI Customization**]: Six comment component families — Comment Pin, Comment Bubble, Text Comment, Inline Comments Section, Multi-Thread Comment Dialog, and Sidebar Button — have been migrated to the V2 primitive architecture. Each family now exposes standalone primitive components for fine-grained wireframe customization. All primitives accept a `defaultCondition` / `default-condition` prop to control whether the built-in render condition is evaluated. [Learn more →](/ui-customization/features/async/comments/comment-dialog/primitives) +- [**UI Customization**]: Six comment component families — Comment Pin, Comment Bubble, Text Comment, Inline Comments Section, Multi-Thread Comment Dialog, and Sidebar Button — have been migrated to the V2 primitive architecture. Each family now exposes standalone primitive components for fine-grained wireframe customization. All primitives accept a `defaultCondition` / `default-condition` prop to control whether the built-in render condition is evaluated. [See comment surface mapping →](/ui-customization/reference/component-catalog#comments) - [**Recorder**]: Added a `recorder.done` webhook event (available on both V1 `WebhookService` and V2 `WebhooksV2Service`) fired when a recording finishes processing. The event payload includes recording assets, transcription data (segments, VTT file URL, content summary), and action user metadata. Enable or disable it per workspace via `triggers.recorder.done` (defaults to `true`). @@ -1254,9 +1254,9 @@ Velt.setDataProviders({ ### New Features -- [**UI Customization**]: Added 13 standalone autocomplete primitive components (`VeltAutocompleteOption`, `VeltAutocompleteChip`, `VeltAutocompleteEmpty`, etc.) for building fully custom autocomplete UIs without requiring the full `` panel. [Learn More →](/ui-customization/features/async/comments/comment-dialog/primitives#veltautocomplete) +- [**UI Customization**]: Added 13 standalone autocomplete primitive components (`VeltAutocompleteOption`, `VeltAutocompleteChip`, `VeltAutocompleteEmpty`, etc.) for building fully custom autocomplete UIs without requiring the full `` panel. [Learn More →](/ui-customization/reference/primitives) -- [**UI Customization**]: Added `multiSelect`, `selectedFirstOrdering`, `readOnly`, `inline`, and `contacts` props to the [`VeltAutocomplete`](/ui-customization/features/async/comments/comment-dialog/primitives#veltautocomplete) panel component. +- [**UI Customization**]: Added `multiSelect`, `selectedFirstOrdering`, `readOnly`, `inline`, and `contacts` props to the [`VeltAutocomplete`](/ui-customization/reference/primitives) panel component. ### Improvements @@ -3070,7 +3070,7 @@ commentElement.submitComment('composer-1'); -- [**Comments**]: Added `placeholder` prop to customize input placeholder text in comment composer. Overrides default placeholders. [Learn more](/ui-customization/features/async/comments/standalone-components/comment-composer#placeholder) +- [**Comments**]: Added `placeholder` prop to customize input placeholder text in comment composer. Overrides default placeholders. [Learn more](/async-collaboration/comments/standalone-components/comment-composer/customize-behavior) @@ -3169,6 +3169,6 @@ Released 115+ primitive components for building custom comment dialogs. Each sub - **Dropdowns**: StatusDropdown, PriorityDropdown, OptionsDropdown, CustomAnnotationDropdown (each with full sub-component breakdown) - **Additional**: ReplyAvatars, AssigneeBanner, ResolveButton, UnresolveButton, CopyLink, DeleteButton, PrivateBanner, NavigationButton, and 90+ more -[View full documentation →](/ui-customization/features/async/comments/comment-dialog/primitives) | [Data Models](/api-reference/sdk/models/data-models#comment-dialog-primitives) +[View full documentation →](/ui-customization/reference/primitives) | [Data Models](/api-reference/sdk/models/data-models#comment-dialog-primitives) diff --git a/ui-customization/.DS_Store b/ui-customization/.DS_Store deleted file mode 100644 index 1eb8d9368..000000000 Binary files a/ui-customization/.DS_Store and /dev/null differ diff --git a/ui-customization/build-gotchas.mdx b/ui-customization/build-gotchas.mdx new file mode 100644 index 000000000..8be93c208 --- /dev/null +++ b/ui-customization/build-gotchas.mdx @@ -0,0 +1,73 @@ +--- +title: "Build gotchas: common traps and fixes" +sidebarTitle: "Build gotchas" +description: "Avoid common build-time mistakes when translating design specs into Velt UI customizations." +--- + + +**Audience: AI coding agents** (and teams running them). This page is part of the deterministic agent workflow for building and verifying Velt UI customizations. Customizing by hand? Start with the [Approaches](/ui-customization/styling) and the [feature overviews](/ui-customization/features/other-features). This is the workflow the [UI Customization Plugin](/get-started/ui-customization-plugin) runs for you. + + +These are common failure modes when building Velt UI customizations from a design. Check them before assuming the SDK is broken. + +## Inspecting +- **Inspect the LIVE rendered node, not the registry template.** A wireframe is cloned: the `velt-*-wireframe` custom-element tags are the hidden registry copy (0-size, empty). `document.querySelector('.vc-x')` may hit that copy. Always pick the element with `getBoundingClientRect().width > 0` (the visible clone) and read *its* classes/computed styles. Measuring the wrong node is how you "verify" something that's actually broken. + +## Wireframe clone behavior +- **Some slots OVERWRITE their inner markup with their own label.** `ToggleReply` replaced custom ` + Reply` with a plain "Reply" text node; `CopyLink` did the same. **Two verified fixes:** (a) inject the icon via CSS `::before` (a data-URI SVG on your `.vc-*` class), which survives the clone; or (b) put the custom icon in a plain sibling wrapper *next to* the slot's `.Text` subslot, never inside the slot itself. If you use a different reply slot with nested children, live-verify the children survive adoption before certifying, overwrite behavior is per-slot. +- **Wireframe MARKUP changes need a FULL page reload to take effect, not just new wireframes.** CSS edits hot-reload fine, but the `` registry is built at mount: changing an existing template's markup (e.g. switching the composer's send to a self-closing `ActionButton`, or swapping Cancel to a `VeltButtonWireframe`) **re-renders under Fast Refresh but does NOT re-register the template**: the browser keeps rendering the OLD wireframe, so your fix "doesn't work" until a hard reload. After ANY `*Wf.tsx` change: hard-reload (Cmd-Shift-R), re-auth, reopen, and verify in a freshly-loaded tab, never a hot-reloaded one. (This masked a *correct* composer-submit fix as "still broken".) +- **Container slots drop undeclared children**: declare the full child tree you intend to use. +- **`velt-if`/`velt-class` attributes on plain HTML elements NEVER fire (R28).** A `velt-if="…"` on a `
`/`` (or a helper spread like `{...veltIf("…")}`) survives the clone as inert markup, the element renders unconditionally, the class never toggles, nothing errors. Directives resolve **only on Velt elements**. Gate custom HTML by wrapping it in ``; toggle classes via `velt-class` on a Velt wireframe element or key CSS off Velt's own state classes (e.g. `.velt-composer-open`, the submit button's `:disabled`). + +## Styling / scoping +- **Class CSS needs shadow off + `!important`** (R6/R9b). With `shadowDom={false}` the live classes are reachable; Velt's runtime CSS is high-specificity, so overrides need `!important`. +- **The page-mode composer renders the WHOLE dialog wireframe** (your `.vc-card` and all). It inherits the card chrome (border/shadow/resolve-icon) and crushes the input. **Fix:** scope the card chrome off in that context: `.velt-comment-dialog--page-mode-composer .vc-card { border:none; box-shadow:none; padding:0; background:transparent }`, leaving just the composer pill. (Alternatively give the page-mode composer its own variant via `pageModeComposerVariant`.) +- **Composer "active" state = the `.velt-composer-open` ancestor class** (focus/compose), not a "has-text" class (there is none). Style the send button: grey/disabled by default, dark/enabled under `.velt-composer-open`. +- **Avatar fill color is user-data-driven**, not CSS: "User 1" renders peach. To match a design that shows a flat dark avatar, override `.…s-user-avatar-initial-container { background }` + the initial color (this overrides per-user colors: a deliberate choice to flag). +- **The send-arrow indigo lives on an inner element** (`.velt-composer--input-button`), not the outer `.velt-composer--submit-button`: override the inner one. + +## Composer actions, collapsed replies, resolved state +- **Cancel button: use `VeltButtonWireframe`, never a raw ` ) @@ -36,7 +36,7 @@ return ( ```html HTML - ``` diff --git a/ui-customization/features/async/arrows/slots.mdx b/ui-customization/features/async/arrows/slots.mdx index 128f9f325..cdea69677 100644 --- a/ui-customization/features/async/arrows/slots.mdx +++ b/ui-customization/features/async/arrows/slots.mdx @@ -47,9 +47,9 @@ export default function App() { - + - + diff --git a/ui-customization/features/async/comments/.DS_Store b/ui-customization/features/async/comments/.DS_Store deleted file mode 100644 index fcd0ac6ce..000000000 Binary files a/ui-customization/features/async/comments/.DS_Store and /dev/null differ diff --git a/ui-customization/features/async/comments/comment-pin/wireframes.mdx b/ui-customization/features/async/comments/comment-pin/wireframes.mdx index 5a5ddc3d4..56cf88ea9 100644 --- a/ui-customization/features/async/comments/comment-pin/wireframes.mdx +++ b/ui-customization/features/async/comments/comment-pin/wireframes.mdx @@ -236,7 +236,7 @@ commentElement.disableDarkMode(); ### Variants - Define variants for the `Velt Comment Pin` component. This is useful for customizing how the pin looks on different elements like charts, tables, etc. -- Learn more about how to define and use variants [here](/ui-customization/layout#variants). +- Learn more about how to define and use variants [here](/ui-customization/wireframes/layout-customization#variants). diff --git a/ui-customization/features/async/comments/inline-comments-section/wireframes.mdx b/ui-customization/features/async/comments/inline-comments-section/wireframes.mdx index 853ea27a8..a55fefa1a 100644 --- a/ui-customization/features/async/comments/inline-comments-section/wireframes.mdx +++ b/ui-customization/features/async/comments/inline-comments-section/wireframes.mdx @@ -507,7 +507,7 @@ Here are the pre-deinfed variants: 3. `composer-variant`: Use this to customize the main Composer that appears within the `Inline Comments Section` component. -Learn more about Variants [here](/ui-customization/layout#variants) +Learn more about Variants [here](/ui-customization/wireframes/layout-customization#variants) diff --git a/ui-customization/features/async/comments/standalone-components/comment-composer.mdx b/ui-customization/features/async/comments/standalone-components/comment-composer.mdx index dfe18ad96..f8c6bfd7f 100644 --- a/ui-customization/features/async/comments/standalone-components/comment-composer.mdx +++ b/ui-customization/features/async/comments/standalone-components/comment-composer.mdx @@ -79,7 +79,7 @@ You can find the wireframe for the `Comment Composer` [here](/ui-customization/f ### Variants - Define variants for the entire Comment Composer component. This will enable you to show different Composer UI in different parts of your app. - Alternatively, define a variant for the Comment Dialog component and use it here. This will enable you to show different Comment Dialog UI on the DOM vs here. -- Learn more about how to define and use variants [here](/ui-customization/layout#variants). +- Learn more about how to define and use variants [here](/ui-customization/wireframes/layout-customization#variants). diff --git a/ui-customization/features/async/comments/standalone-components/comment-thread.mdx b/ui-customization/features/async/comments/standalone-components/comment-thread.mdx index 54fc5f6e8..40270bb29 100644 --- a/ui-customization/features/async/comments/standalone-components/comment-thread.mdx +++ b/ui-customization/features/async/comments/standalone-components/comment-thread.mdx @@ -80,7 +80,7 @@ You can find the wireframe for the `Comment Dialog` [here](/ui-customization/fea ### Variants - Define variants for the entire Comment Thread component. This will enable you to show different Thread UI in different parts of your app. - Alternatively, define a variant for the Comment Dialog component and use it here. This will enable you to show different Comment Dialog UI on the DOM vs here. -- Learn more about how to define and use variants [here](/ui-customization/layout#variants). +- Learn more about how to define and use variants [here](/ui-customization/wireframes/layout-customization#variants). diff --git a/ui-customization/features/async/notifications/notifications-tool/wireframes.mdx b/ui-customization/features/async/notifications/notifications-tool/wireframes.mdx index 95bb58b37..5691b04cf 100644 --- a/ui-customization/features/async/notifications/notifications-tool/wireframes.mdx +++ b/ui-customization/features/async/notifications/notifications-tool/wireframes.mdx @@ -89,7 +89,7 @@ We recommend that you familiarize yourselves with [UI Customization Concepts](/u ## Variant -You can define and use [variants](/ui-customization/layout#variants) for the Notification Tool or the Notification Panel. +You can define and use [variants](/ui-customization/wireframes/layout-customization#variants) for the Notification Tool or the Notification Panel. 1. `variant`: For the Notification Tool. 2. `panelVariant`: For the Notification Panel. diff --git a/ui-customization/features/async/reactions-wireframe-variables.mdx b/ui-customization/features/async/reactions-wireframe-variables.mdx index 0236f4c00..f65f211ed 100644 --- a/ui-customization/features/async/reactions-wireframe-variables.mdx +++ b/ui-customization/features/async/reactions-wireframe-variables.mdx @@ -102,7 +102,7 @@ The "+" emoji-picker button. | Property | Value | |---|---| -| Extra variables | See [Component Config — Reaction Tool](#component-config-reaction-tool). | +| Extra variables | See [Component Config — Reaction Tool](#component-config--reaction-tool). | --- @@ -116,7 +116,7 @@ A single placed emoji reaction. | Property | Value | |---|---| -| Extra variables | See [Component Config — Reaction Pin](#component-config-reaction-pin). | +| Extra variables | See [Component Config — Reaction Pin](#component-config--reaction-pin). | --- @@ -130,7 +130,7 @@ An inline strip of reactions placed next to a target element. | Property | Value | |---|---| -| Extra variables | See [Component Config — Inline Reactions Section](#component-config-inline-reactions-section). | +| Extra variables | See [Component Config — Inline Reactions Section](#component-config--inline-reactions-section). | #### Children diff --git a/ui-customization/features/async/recorder/transcription-wireframe-variables.mdx b/ui-customization/features/async/recorder/transcription-wireframe-variables.mdx index 6c4edf31c..aef8b5539 100644 --- a/ui-customization/features/async/recorder/transcription-wireframe-variables.mdx +++ b/ui-customization/features/async/recorder/transcription-wireframe-variables.mdx @@ -106,7 +106,7 @@ The transcript panel — full transcript with speaker labels and clickable segme | Property | Value | |---|---| -| Extra variables | See [Component Config — Transcription](#component-config-transcription) and the per-iteration `segment` / `currentTime` injected into content-item children. | +| Extra variables | See [Component Config — Transcription](#component-config--transcription) and the per-iteration `segment` / `currentTime` injected into content-item children. | The transcription feature has no root wireframe slot — register a wireframe directly on one of the mode-specific tags (`` or ``). @@ -158,7 +158,7 @@ The live subtitle overlay shown during playback. | Property | Value | |---|---| -| Extra variables | See [Component Config — Subtitles / Subtitles Dialog](#component-config-subtitles--subtitles-dialog). | +| Extra variables | See [Component Config — Subtitles / Subtitles Dialog](#component-config--subtitles--subtitles-dialog). | --- diff --git a/ui-customization/features/async/recorder/wireframe-variables.mdx b/ui-customization/features/async/recorder/wireframe-variables.mdx index a8171f6d2..e14b932f3 100644 --- a/ui-customization/features/async/recorder/wireframe-variables.mdx +++ b/ui-customization/features/async/recorder/wireframe-variables.mdx @@ -129,7 +129,7 @@ The record-trigger button. | Property | Value | |---|---| -| Extra variables | See [Component Config — Recorder Button](#component-config-recorder-button). | +| Extra variables | See [Component Config — Recorder Button](#component-config--recorder-button). | | Host class | `velt-recorder-tool` (always). | #### Children @@ -170,7 +170,7 @@ The pin icon shown over a recorder annotation. | Property | Value | |---|---| -| Extra variables | See [Component Config — Recorder Pin](#component-config-recorder-pin). | +| Extra variables | See [Component Config — Recorder Pin](#component-config--recorder-pin). | | Host class | `recorder-pin-container` (always). `recorder-pin-player-container` on the inner player wrapper. | | Angular Binding | Type | Default | Description | @@ -194,7 +194,7 @@ The playback widget (audio + video). Composes ~20 sub-primitives — each with i | Property | Value | |---|---| -| Extra variables | See [Component Config — Recorder Player (shared)](#component-config-recorder-player-shared). | +| Extra variables | See [Component Config — Recorder Player (shared)](#component-config--recorder-player-shared). | ## Recorder Player Internals diff --git a/ui-customization/features/async/rewriter/wireframe-variables.mdx b/ui-customization/features/async/rewriter/wireframe-variables.mdx index 2c06d24c8..d3c9706f1 100644 --- a/ui-customization/features/async/rewriter/wireframe-variables.mdx +++ b/ui-customization/features/async/rewriter/wireframe-variables.mdx @@ -79,7 +79,7 @@ The inline highlight that sits over the rewriter's target text. | Property | Value | |---|---| -| Extra variables | See [Component Config — Rewriter Text Portal](#component-config-rewriter-text-portal). | +| Extra variables | See [Component Config — Rewriter Text Portal](#component-config--rewriter-text-portal). | --- @@ -92,7 +92,7 @@ The desktop popover with rewrite options. | Property | Value | |---|---| -| Extra variables | See [Component Config — Rewriter Dialog / Bottom Sheet](#component-config-rewriter-dialog-bottom-sheet). | +| Extra variables | See [Component Config — Rewriter Dialog / Bottom Sheet](#component-config--rewriter-dialog--bottom-sheet). | --- diff --git a/ui-customization/features/async/view-analytics/wireframe-variables.mdx b/ui-customization/features/async/view-analytics/wireframe-variables.mdx index dc263a422..e3d27cd9c 100644 --- a/ui-customization/features/async/view-analytics/wireframe-variables.mdx +++ b/ui-customization/features/async/view-analytics/wireframe-variables.mdx @@ -69,7 +69,7 @@ The trigger button that shows the "N people viewed today" badge. | Property | Value | |---|---| -| Extra variables | See [Component Config — View Analytics](#component-config-view-analytics). | +| Extra variables | See [Component Config — View Analytics](#component-config--view-analytics). | --- @@ -82,7 +82,7 @@ The desktop popover listing recent viewers. | Property | Value | |---|---| -| Extra variables | See [Component Config — View Analytics Dialog / Bottom Sheet](#component-config-view-analytics-dialog--bottom-sheet). | +| Extra variables | See [Component Config — View Analytics Dialog / Bottom Sheet](#component-config--view-analytics-dialog--bottom-sheet). | --- diff --git a/ui-customization/features/comment-surfaces.mdx b/ui-customization/features/comment-surfaces.mdx new file mode 100644 index 000000000..4c0a75989 --- /dev/null +++ b/ui-customization/features/comment-surfaces.mdx @@ -0,0 +1,70 @@ +--- +title: "Other comment surfaces (Text, Inline, Multi-thread)" +sidebarTitle: "Comment surfaces" +description: "Customize text comments, inline comments, and multi-thread comment surfaces beyond the standard dialog and sidebar." +--- + +Three comment *variants* beyond the standard dialog/sidebar. They reuse the comment data model and hooks (so the comment hooks in [`Hooks`](/ui-customization/reference/hooks) apply), and each is **wireframed**. + + +**Have this design in Figma?** The [UI Customization Plugin](/get-started/ui-customization-plugin) for Cursor and Claude Code turns a Figma design into verified Velt UI customization (comments and notifications today): it picks the approach, builds a comment surface like these in your app, and verifies the result against the design in a real browser. + + + +**Looking for the standard comment surfaces?** The **dialog, sidebar (V1/V2), sidebar button, pin, bubble, and comment tool** aren't on this page: they're the running examples throughout the approach guides ([`Wireframes`](/ui-customization/layout), [`CSS`](/ui-customization/styling), [`Primitives`](/ui-customization/primitives)), and each has a one-stop entry (primitive · root wireframe · key props · flags · variables · refs) in the **Surface lookup** map in [`Component catalog`](/ui-customization/reference/component-catalog). Start there for any standard comment surface; this page is only the three variants below. + + +## Components + +**Full examples:** each variant has per-component pages with complete tabbed code examples and screenshots: [Inline comments section wireframes](/ui-customization/features/async/comments/inline-comments-section/wireframes), [Multi-thread comments wireframes](/ui-customization/features/async/comments/multithread-comments/wireframes), [Text comment tool wireframes](/ui-customization/features/async/comments/text-comment/text-comment-tool/wireframes), and [Text comment toolbar wireframes](/ui-customization/features/async/comments/text-comment/text-comment-toolbar/wireframes). + +| | What it is | Primitive | Wireframe | +|---|---|---|---| +| Text Comment (selection-anchored) | Toolbar on text selection to comment on / rewrite the selected text | `VeltTextComment`, `VeltTextCommentTool`, `VeltTextCommentToolbar` (sub-accessors `.CommentAnnotation` / `.Copywriter` / `.Generic` / `.Divider`) | `VeltTextCommentToolWireframe`; toolbar wireframe → `.CommentAnnotation`, `.Copywriter` (AI rewriter), `.Generic`, `.Divider` | +| Inline Comments Section (Substack-style) | Thread anchored to a target element with composer, list, filter, and sort. **Very rich**: renders comment-dialog primitives internally, so nested comment-dialog wireframes/variables resolve here too | `VeltInlineCommentsSection` | `VeltInlineCommentsSectionWireframe` | +| Multi-Thread Comment Dialog | Multiple threads in one dialog/panel with a minimal filter + bulk actions. Also renders comment-dialog primitives internally | `VeltMultiThreadCommentDialog` | `VeltMultiThreadCommentDialogWireframe` | + +## Config props + +| Surface | Props | +|---|---| +| Text Comment | None dedicated beyond enabling text comments: drive behaviour via the comment config and the tokens below (`enableTextComments`, `rewriterEnabled`, …) | +| Inline Comments Section | `targetElementId`, `composerPosition` (`'top'\|'bottom'`), `sortBy` (`'createdAt'\|'lastUpdated'`), `sortOrder` (`'asc'\|'desc'`), `multiThread`, `dialogVariant`/`composerVariant`, `fullExpanded`, `readOnly`, all the `*Placeholder` props, `context`/`contextOptions`, `messageTruncation(Lines)`, `darkMode`/`shadowDom`/`variant` | +| Multi-Thread Comment Dialog | `annotationId`, `multiThreadAnnotationId`, `commentPinSelected`, `commentPinType`, `dialogVariant`, `inboxMode`, `readOnly`, `context` | + +## CSS: stateful classes + +None dedicated to these variants: they reuse the comment-dialog classes. Theme via `--velt-*` and override structural classes with `!important` because Velt's own styles are high-specificity; see [CSS](/ui-customization/styling#override-classes). See also [`CSS classes`](/ui-customization/reference/css-classes). + +## Wireframes: slot trees + tokens + +### Text Comment +`VeltTextCommentToolbar` wireframe → `.CommentAnnotation`, `.Copywriter` (AI rewriter), `.Generic`, `.Divider`. +**Key tokens** (use full paths where they collide): `{showAdder}`, `{commentToolEnabled}`, `{isUserAllowed}`, `{enableTextComments}`, `{rewriterEnabled}`, `{selectedWordsCount}`, `{selectedCharactersCount}`, `{position.top}`/`{position.left}`, `{uiState.disabled}`. + +### Inline Comments Section +`VeltInlineCommentsSectionWireframe`: +``` +.Skeleton · .Panel · .List · .ComposerContainer · .CommentCount +.FilterDropdown → .Trigger(.Name/.Arrow) / .Content(.ApplyButton, .List→.Item→.Label/.Checkbox) +.SortingDropdown → .Trigger(.Icon/.Name) / .Content→.Item(.Icon/.Name/.Tick) +``` +**Key tokens:** `{skeletonLoading}`, `{annotations}`, `{filterState.filterDropdownOpen}`, `{sortState.sortingDropdownOpen}`, `{isResolvedCommentsOnDomFilterSelected}`; per-item `{filter.isSelected}`, `{sortOption}`, `{isActive}`, `{isAscending}`. + +### Multi-Thread Comment Dialog +`VeltMultiThreadCommentDialogWireframe`: +``` +.CommentCount · .ComposerContainer · .List · .CloseButton · .NewThreadButton +.ResetFilterButton · .EmptyPlaceholder +.MinimalFilterDropdown → .Trigger / .Content(.FilterAll/.FilterUnread/.FilterRead/.FilterResolved/.SelectedIcon/.SortDate/.SortUnread) +.MinimalActionsDropdown → .Trigger / .Content(.MarkAllRead/.MarkAllResolved) +``` +**Key tokens:** `{filteredAnnotations}`, `{nonDraftCommentsCount}`, `{minimalFilter}` (`'all'|'read'|'unread'|'resolved'`), `{noCommentsFound}`, `{noCommentsFoundForAppliedFilters}`, `{hideMultiThreadAnnotationComposer}`; per minimal-filter item `{isSelected}`. + +## Headless hooks + +None section-specific: all three reuse the shared comment hooks (see [`Hooks`](/ui-customization/reference/hooks)). Text Comment additionally drives via the comment element (`useCommentUtils`) and the AI rewriter (`useAIRewriterUtils`). + +## Limitations + +Text Comment has a thinner slot set (the four toolbar buttons) and no dedicated hooks. Otherwise all three follow the same rules as the comment dialog: the [interactivity rule](/ui-customization/layout#5-the-interactivity-rule-the-single-most-important-thing), scoping (nest vs root), and `shadowDom`/CSS guidance all apply. The visible "panel" is the container; fill the slots inside it. diff --git a/ui-customization/features/mentions-and-autocomplete.mdx b/ui-customization/features/mentions-and-autocomplete.mdx new file mode 100644 index 000000000..b594265c2 --- /dev/null +++ b/ui-customization/features/mentions-and-autocomplete.mdx @@ -0,0 +1,81 @@ +--- +title: "@Mentions & Autocomplete" +sidebarTitle: "Mentions & autocomplete" +description: "Customize mentions and autocomplete behavior, styling, slots, and related hooks." +--- + +The @-mention / autocomplete picker that appears inside comment composers (and the mention chips it produces). You customize **the data** (who/what is mentionable), **the layout** (option rows, groups, empty state), and **the chips**. + +## Components + +**Full examples:** [Autocomplete wireframe variables](/ui-customization/features/async/comments/autocomplete-wireframe-variables) has the complete variable reference with tabbed code examples. + +| | Primitive | Wireframe | +|---|---|---| +| Autocomplete root | `VeltAutocomplete` | None | +| Option row | `VeltAutocompleteOption` | `VeltAutocompleteOptionWireframe` | +| Group header row | `VeltAutocompleteGroupOption` | `VeltAutocompleteGroupOptionWireframe` | +| Empty state | `VeltAutocompleteEmpty` | `VeltAutocompleteEmptyWireframe` | +| Mention chip | `VeltAutocompleteChip` | None | +| Chip tooltip | `VeltAutocompleteChipTooltip` | `VeltAutocompleteChipTooltipWireframe` | +| Panel | `VeltAutocompletePanel` | None | + +> Most customers don't mount the primitives directly: autocomplete renders **inside the comment composer**. + +## Config props + +Customize the data (the most common need): these props live on ``: + +| Prop | Type | What it does | +|---|---|---| +| `customAutocompleteSearch` | **`boolean`** | **A toggle, not a callback.** Switches the picker to *your* data, which you supply via `ContactElement` / `AutocompleteElement` (below). | +| `expandMentionGroups` | `boolean` | Expand group members inline | +| `showMentionGroupsFirst` / `showMentionGroupsOnly` | `boolean` | Group ordering / groups-only | +| `paginatedContactList` | `boolean` | Paginate a long contact list | +| `atHereEnabled` / `atHereLabel` / `atHereDescription` | `boolean` / `string` | The "@here" option | +| `customListDataOnComment` | `AutocompleteData` | Custom (non-contact) mention data | + + +Watch out for near-miss names: the real props are `showMentionGroupsFirst` / `showMentionGroupsOnly` (there is no `showMentionGroups`), `atHereEnabled` (there is no `atHere` or `showAtHere`), and `customListDataOnComment` (there is no `customGroups`). + + +**Supply the contacts/data via hooks (headless config):** +- **Contacts:** `useContactUtils()` → `ContactElement`: `updateContactList(userContacts, config?)`, `updateOrgList(...)`, `enableAtHere()`/`setAtHereLabel()`, `getContactList()`. Read with `useContactList()`. +- **Custom (non-contact) items:** `useAutocompleteUtils()` → `AutocompleteElement.create({ hotkey, type: 'custom'|'contact'|'group', data, groups? })`: combine with `customAutocompleteSearch`. + +## CSS: stateful classes + +(Override with `!important` because Velt's own styles are high-specificity; see [CSS](/ui-customization/styling#override-classes).) + +| Class | Applies to | +|---|---| +| `velt-autocomplete-option--container`, `--selected`, `--multi-select` | Option rows | +| `velt-group-option` (header), `velt-group-member-option` | Groups | +| `velt-autocomplete--contact-chip`, `--contact-chip-current-user`, `--group-chip`, `.custom-chip` | Chips | +| `velt-autocomplete-empty--no-results` / `--add-contact` / `--error` | Empty state | + +> **Chip classes are styled in a global stylesheet**: override them globally, not inside a component scope. + +## Wireframes: slot trees + tokens + +``` +VeltAutocompleteOptionWireframe → .Icon · .Name · .Description (prop: field) · .ErrorIcon +VeltAutocompleteGroupOptionWireframe (group header row) +VeltAutocompleteEmptyWireframe (no-results / add-contact state) +VeltAutocompleteChipTooltipWireframe → .Name · .Description · .Icon +``` +`.Description` is the one slot with an input prop (`field`). Read tokens with `{componentConfig.}`: `flattenedItems` (empty when `length === 0`), `groups`, `expandMentionGroups`, `customAutocompleteSearch`; per-row `option` (`.name`/`.email`/`.description`/`.group.name`/`.group.userCount`), `chip` (`.label`). + +## Headless hooks + +| Hook | Purpose | +|---|---| +| `useContactUtils()` | Contact element: update contact/org lists, `@here` config | +| `useContactList()` | Read the current contact list | +| `useContactSelected()` | React to contact selection | +| `useAutocompleteUtils()` | Autocomplete element: create custom mention data | +| `useAutocompleteChipClick()` | React to chip clicks | + +## Limitations + +`customAutocompleteSearch` only flips the mode: you must also feed data. The panel switches to virtual scroll past ~6 items. Some option/group types referenced in tokens are internal shapes (not in the public types): rely on the documented fields above and inspect at runtime if unsure. diff --git a/ui-customization/features/notifications.mdx b/ui-customization/features/notifications.mdx new file mode 100644 index 000000000..eb4268ed5 --- /dev/null +++ b/ui-customization/features/notifications.mdx @@ -0,0 +1,95 @@ +--- +title: "Notifications" +sidebarTitle: "Overview" +description: "Customize Velt notification tools and panels with props, classes, wireframes, hooks, and limitations." +--- + +The notifications bell (tool) + the notifications panel (inbox with For-you / All / Documents / People tabs + a settings view). **Fully wireframed**, with rich config props: all four layers apply. + + +**Have this design in Figma?** The [UI Customization Plugin](/get-started/ui-customization-plugin) for Cursor and Claude Code turns a Figma design into verified Velt UI customization (comments and notifications today): it picks the approach, builds your notification tool and panel in your app, and verifies the result against the design in a real browser. + + +## Components + +**Full examples:** the per-component pages have complete tabbed code examples and screenshots: [Notifications tool wireframes](/ui-customization/features/async/notifications/notifications-tool/wireframes), [Notifications panel wireframes](/ui-customization/features/async/notifications/notifications-panel/wireframes), and the matching [tool](/ui-customization/features/async/notifications/notifications-tool/primitives) and [panel](/ui-customization/features/async/notifications/notifications-panel/primitives) primitives pages. + +| | Primitive | Wireframe | +|---|---|---| +| Bell / trigger | `VeltNotificationsTool` | `VeltNotificationsToolWireframe` | +| Inbox panel | `VeltNotificationsPanel` | `VeltNotificationsPanelWireframe` | +| History panel (inline) | `VeltNotificationsHistoryPanel` | None | + +## Config props + +Cheapest customization: do this first. On `VeltNotificationsTool` / `VeltNotificationsPanel`: + +| Prop | Values | Notes | +|---|---|---| +| `panelOpenMode` | `'popover'` · `'sidebar'` | popover vs docked panel | +| `settingsLayout` | `'accordion'` · `'dropdown'` | settings UI | +| `tabConfig` | `{ forYou?, documents?, all?, people?: { name?, enable? } }` | enable/rename/reorder tabs | +| `settings` | `boolean` | show/hide settings view | +| `enableSettingsAtOrganizationLevel` | `boolean` | org-scoped settings | +| `enableCrossOrganization` | `boolean \| string \| CrossOrganizationConfig` | cross-org feeds (only `forYou` feed supported; current org excluded) | +| `considerAllNotifications` | `boolean` | **Tool-only**: count all, not just unread | +| `selfNotifications` / `readNotificationsOnForYouTab` | `boolean` | include self / auto-read on For-you | +| `pageSize` (default 5) / `maxDays` (Tool-only) | `number` (>0) | page size / history window | +| `darkMode` / `shadowDom` / `variant` | None | theme / shadow-DOM / variant; Tool also has `panelShadowDom` / `panelVariant` | + +> Boolean attributes only emit when explicitly `true`/`false`; `shadowDom`/`panelShadowDom` default to `true`. `pageSize`/`maxDays` are ignored unless `> 0`. + +## CSS: stateful classes + +(Override with `!important` because Velt's own styles are high-specificity; see [CSS](/ui-customization/styling#override-classes).) + +| Class | Applied when | +|---|---| +| `velt-notifications-tool`, `active` / `velt-notification-tool-open` | Tool; panel open | +| `velt-notifications-panel--tab`, `velt-notifications-panel--tab-selected` | Tabs; active tab | +| `velt-notifications-panel--sidebar-panel`, `bottom-sheet` | Panel mode | +| `velt-notifications-panel--list-item-unread`, `velt-notifications-panel--unread-is-default` | Unread items | +| `velt-notification-panel--settings-accordion-container-expanded` / `…-open` | Settings accordion | +| `velt-notification-panel--settings-mute-all-toggle-container-muted` | Mute-all toggle | + +## Wireframes: slot trees + tokens + +**`VeltNotificationsToolWireframe`:** `.Icon` · `.Label` · `.UnreadIcon` · `.UnreadCount`. (Root prop `variant`.) + +**`VeltNotificationsPanelWireframe`** (abridged; full tree in [Wireframe components](/ui-customization/reference/wireframe-components)): +``` +VeltNotificationsPanelWireframe +├── .Header → .TabAll / .TabForYou / .TabDocuments / .TabPeople +├── .Title .TitleText .ReadAllButton .ViewAllButton .CloseButton .Skeleton .SettingsButton +├── .Content +│ ├── .All → .List → .Item → .Label / .Content +│ ├── .ForYou +│ ├── .Documents → .List → .Item → .Content / .Name / .Count / .Unread +│ ├── .People → .List → .Item → .Avatar / .Name / .Count / .Content +│ ├── .List → .Item → .Avatar / .Body / .FileName / .Headline / .Time / .Unread +│ ├── .LoadMore .AllReadContainer +└── .Settings + ├── .Header → .Title .BackButton .Description .Footer .Title + ├── .MuteAllTitle .MuteAllDescription .MuteAllToggle + └── .List → .Accordion + ├── .Trigger → .SelectedValue / .Label / .Icon + └── .Content → .Item → .Icon / .Label +``` + +**Key tokens:** `{selectedTab}` (`'forYou'|'people'|'documents'|'all'`), `{TABS}`, `{tabConfig}`, `{settingsOpen}`, `{settingsMutedAll}`, `{notificationsPanelVisible}`, `{unreadNotificationsForYou}` (tool: array → `.length` for the badge), `{notificationsByDate}` / `{notificationsByUserMap}` / `{notificationsByDocumentId}`. Inside the content list: `{notification}` (`.title`, `.from.name`, `.from.photoUrl`, `.read`, `.createdAt`, `.documentName`), `{isLoadMoreVisible}`, `{isAllRead}`. + +> Gotchas: `{notification.*}` only resolves **inside** the content-list iteration. `.Title` is a leaf: to change the heading text use the top-level `.TitleText` slot (there's no `.Title.Text`). + +## Headless hooks + +| Hook | Returns | +|---|---| +| `useNotificationsData(query?)` | `Notification[] \| null` (`query.type`: `'all'\|'forYou'\|'documents'`) | +| `useUnreadNotificationsCount()` | `{ forYou: number\|null, all: number\|null }` (badges) | +| `useNotificationSettings()` | `{ settings, setSettings, setSettingsInitialConfig }` | +| `useNotificationEventCallback(action)` | Event subscription (e.g. settings updated) | +| `useNotificationUtils()` | Imperative element (open/close panel, mark-all-read, mute, tab config, cross-org, …) | + +## Limitations + +All list rendering flows through the content-list iteration (variables scoped there). Tool-only props (`considerAllNotifications`, `panelShadowDom`, `panelVariant`, `maxDays`) aren't on the panel. Cross-org `feeds:'all'` is ignored (only `forYou`). diff --git a/ui-customization/features/other-features.mdx b/ui-customization/features/other-features.mdx new file mode 100644 index 000000000..04ed04a48 --- /dev/null +++ b/ui-customization/features/other-features.mdx @@ -0,0 +1,41 @@ +--- +title: "Customize by Feature" +sidebarTitle: "Customize by feature" +description: "Find the customization entry point for every Velt feature: each feature area under Components opens with an overview page." +--- + +The same four-layer model (CSS · Wireframes · Primitives · Headless) and the same rules apply to **every** Velt feature, comments included. Each feature area below opens with an **overview page** at the top of its group: open the one you need. (The standard comment dialog, sidebar, pin, bubble, and comment tool are the running examples throughout the approach guides, [`Wireframes`](/ui-customization/layout), [`CSS`](/ui-customization/styling), and [`Primitives`](/ui-customization/primitives), so start there for those.) + +> Run the [decision tree](/ui-customization/decision-tree) on the feature (same four questions), then jump to its page below. The core rules (no hacks against Velt's internal DOM, one ``, the [interactivity rule](/ui-customization/layout#5-the-interactivity-rule-the-single-most-important-thing), `shadowDom`/`injectCustomCss`) hold everywhere. + +## Where to customize each feature + + +**Have this design in Figma?** The [UI Customization Plugin](/get-started/ui-customization-plugin) for Cursor and Claude Code turns a Figma design into verified Velt UI customization (comments and notifications today): it picks the approach, builds the feature UI in your app, and verifies the result against the design in a real browser. + + +| Feature | Customization depth | Guide | +|---|---|---| +| **Comment Dialog** | Full wireframe tree + variables + primitives; the running example in the approach guides | [`Comment Dialog`](/ui-customization/features/async/comments/comment-dialog/wireframes) | +| **Comments Sidebar** | V1/V2 wireframes + variables + V2 primitives | [`Comment Sidebar`](/ui-customization/features/async/comments/comment-sidebar/comment-sidebar-components) | +| **Comment Pin / Bubble / Tool** | Wireframes + variables per surface | [`Pin`](/ui-customization/features/async/comments/comment-pin/wireframes) · [`Bubble`](/ui-customization/features/async/comments/comment-bubble/wireframes) · [`Tool`](/ui-customization/features/async/comments/comment-tool) | +| **Comment surfaces** (Text / Inline / Multi-thread) | Comment variants: wireframed, reuse comment hooks | [`Comment surfaces`](/ui-customization/features/comment-surfaces) | +| **Notifications** | Full wireframe + rich config props (panel mode, settings layout, tabs) + hooks | [`Notifications`](/ui-customization/features/notifications) | +| **Reactions** | Wireframed (tool/panel/pin/tooltip/inline) + custom emoji sets + hooks | [`Reactions`](/ui-customization/features/reactions) | +| **Recorder & Transcription** | Deepest wireframe tree (control panel/player/tools/dialogs/subtitles/transcript) + hooks | [`Recorder and transcription`](/ui-customization/features/recorder-and-transcription) | +| **@Mentions & Autocomplete** | Custom mention data (contacts/groups/custom) + option/chip wireframes | [`Mentions and autocomplete`](/ui-customization/features/mentions-and-autocomplete) | +| **Presence & Live Cursors** | Per-item wireframes (avatar list / cursor pointer) + hooks; flat-config | [`Presence and cursors`](/ui-customization/features/presence-and-cursors) | +| **Activity Log** | Full wireframe + data hooks | [`Activity Log`](/ui-customization/features/activity-log) | +| **Tags / Arrows / Areas** | **Thin**: CSS + props (+ Tag hooks); no wireframe slots | [`Annotations, tags, arrows, and areas`](/ui-customization/features/annotations-tags-arrows-areas) | +| **Huddle** | Wireframe variables (flat-config) for the huddle panels and attendee tiles | [`Huddle wireframe variables`](/ui-customization/features/realtime/huddle/wireframe-variables) | +| **Live Selection** | CSS classes + default-styling toggle | [`Live Selection`](/ui-customization/features/realtime/live-selection) | +| **Single Editor Mode** | Panel wireframe | [`Single Editor Mode`](/ui-customization/features/realtime/single-editor-mode) | +| **View Analytics** | Wireframe variables for the viewers indicator | [`View Analytics wireframe variables`](/ui-customization/features/async/view-analytics/wireframe-variables) | +| **Rewriter** | Wireframe variables for the AI rewriter | [`Rewriter wireframe variables`](/ui-customization/features/async/rewriter/wireframe-variables) | + +## Two things to remember for non-comment features + +1. **Flat-config variables** ([what this means](/ui-customization/conditional-templates#mapped-vs-flat-config-features-which-name-form-to-use)). Cursor, Presence, Huddle, Recording, Transcription, Reactions, Autocomplete, View, Area, Arrow, Tag read wireframe tokens as **`{componentConfig.}`** (not the short aliases used by comments). See [`Conditional Templates`](/ui-customization/conditional-templates). +2. **Some features are config/hooks-only.** Tags/Arrows/Areas have no wireframe slots; Transcription/Subtitles are surfaced through the recorder player's slots; Reactions actions live on the comment element. Each feature page calls out its exact limits. + +Cross-cutting concerns (a11y, i18n, RTL, responsive, testing) apply to all of these: see [`Cross-cutting concerns`](/ui-customization/localisation). diff --git a/ui-customization/features/presence-and-cursors.mdx b/ui-customization/features/presence-and-cursors.mdx new file mode 100644 index 000000000..e46f1b454 --- /dev/null +++ b/ui-customization/features/presence-and-cursors.mdx @@ -0,0 +1,95 @@ +--- +title: "Presence & Live Cursors" +sidebarTitle: "Presence & cursors" +description: "Customize Velt presence avatars and live cursors with supported components and styling hooks." +--- + +Real-time "who's here" avatars (presence) and live remote cursors. Both are **wireframed at the per-item level** and use **flat-config** variables (`{componentConfig.}`; see [what this means](/ui-customization/conditional-templates#mapped-vs-flat-config-features-which-name-form-to-use)). + +## Components + +**Full examples:** the per-component pages have complete tabbed code examples and screenshots: [Presence](/ui-customization/features/realtime/presence), [Cursors](/ui-customization/features/realtime/cursors), [Presence wireframe variables](/ui-customization/features/realtime/presence-wireframe-variables), and [Cursors wireframe variables](/ui-customization/features/realtime/cursors-wireframe-variables). + +| | Primitive | Wireframe | +|---|---|---| +| Presence | `VeltPresence` | `VeltPresenceWireframe` | +| Presence tooltip | None (no standalone mount) | `VeltPresenceTooltipWireframe` | +| Live cursor pointer | `VeltCursor` | `VeltCursorPointerWireframe` (per-user pointer only) | + +> The root `` just spawns one pointer per remote user and isn't wireframable; only the per-user pointer is. + +## Config props + +### Presence + +| Prop | Default | What it does | +|---|---|---| +| `maxUsers` | `5` | Caps avatars before the "+N" overflow | +| `self` | | Include the local user | +| `inactivityTime` | 5 min | Time until a user shows as away | +| `offlineInactivityTime` | 10 min | Time until a user drops offline | +| `flockMode` / `defaultFlockNavigation` | | Follow-along mode | +| `location` / `locationId` | | Scope presence to a location | +| `variant` / `shadowDom` | | Wireframe variant / shadow-DOM toggle | + +### Live Cursors + +| Prop | Default | What it does | +|---|---|---| +| `avatarMode` | | Avatar bubbles vs arrows | +| `inactivityTime` | 5 | Time until a cursor hides | +| `allowedElementIds` | | Restrict cursors to specific elements | +| `variant` / `darkMode` | | Wireframe variant / dark theme | + +## CSS: stateful classes + +(Override with `!important`; Velt's own styles are high-specificity; see [why](/ui-customization/styling#override-classes).) + +| Class | Applied when | +|---|---| +| `velt-presence-avatar--away` (and `.away`) | `onlineStatus === 'away'` | +| `velt-presence-avatar-outline` | Always; tinted by `presenceUser.color` | +| `no-transition` | Self pointer | +| `…default-container-comment-border` | `cursorUser.comment` present | +| `flip` (on the huddle `