Uh oh!
There was an error while loading. Please reload this page.
fix(ios): correct v5 UI Kit docs against the shipped 5.1.19 kit - #477
Merged
Conversation
…ents-overview, conversations
Every change verified against the public API surface of the CometChatUIKitSwift
5.1.19 xcframework (the artifact github.com/cometchat/cometchat-uikit-ios pins,
sha256 a0f19887…). Nothing here is inferred from prose or from another page.
components-overview.mdx
- Removes the "Composite Components" section and every reference to
CometChatMessages / CometChat{Users,Groups,Conversations}WithMessages. These
are v4 components; 5.1.19 contains none of them (0 occurrences in the public
.swiftinterface, no ObjC @interface, absent from the source tree). The page
was actively RECOMMENDING them as the quick-integration path.
- Replaces them with the host-composed pattern the clean recipe pages already
teach: a list component + your own chat screen (MessageHeader + MessageList
+ MessageComposer), linking to ios-conversation / ios-one-to-one-chat /
ios-tab-based-chat rather than duplicating them.
- Rewrites "Configurations": MessageHeaderConfiguration, MessageListConfiguration
and MessageComposerConfiguration do not exist in v5 either — that whole section
described the v4 pass-config-into-a-composite model. Now shows per-instance
configuration with verified API: set(user:), set(controller:), set(subtitleView:),
set(emptyView:), set(errorView:), placeholderText, hideBackButton.
- Re-roots the hierarchy diagram at YourNavigationController / MessagesVC so the
ownership boundary is explicit.
- AI Quick Reference: compositeComponents -> a `composition` block that positively
states no composite ships and names the three parts. An agent reading only that
block now gets the right answer instead of a phantom.
conversations.mdx
- Six styles + onSearchClick are public VARS, not set(label:) methods. Converted
to property assignment: conversations.avatarStyle = …, .badgeStyle, .dateStyle,
.receiptStyle, .statusIndicatorStyle, .typingIndicatorStyle, .onSearchClick.
- CometChatMentionTextFormatter and CometChatURLTextFormatter do not exist. The
kit ships CometChatTextFormatter and CometChatMentionsFormatter (plural) only —
there is no URL formatter at all, so the example no longer implies one.
- Custom empty state: the API takes a UIView, not a closure. Now assigns
emptyStateView (inherited from CometChatListBase) with set(emptyView:) noted as
the builder equivalent, plus emptyStateTitleText/emptyStateSubTitleText for the
keep-the-default case.
- CometChatMessages -> your own MessagesVC, with user/group passed from
conversation.conversationWith.
- AI Quick Reference slot names: tailView -> trailView, loadingStateView ->
loadingView, and emptyStateView/errorStateView retyped as UIView rather than
() -> UIView.
Both pages now pass the docs-vs-kit API check with zero findings.
Ref: cometchat-skills DOCS-BACKLOG G12 / features.ios-v5.json IOS-DOCS-001.CometChatSearch's documented API diverged furthest from the shipped component. Every replacement below is taken from the 5.1.19 public .swiftinterface. Removed — these do not exist on CometChatSearch: set(onError:) / set(onEmpty:) failures and empty results are VIEWS, not callbacks: set(errorView:), set(emptyView:), errorStateTitleText, errorStateSubTitleText set(conversationsRequestBuilder:) no request builder at all; scope with set(messagesRequestBuilder:) set(searchIn:) + set(searchFilters:initialFilter:), or user/group for a single conversation set(initialView:) no pre-search view API exists — section removed rather than left describing something unbuildable set(leadingViewForMessage:) the ForMessage granular slots do not exist. The set(titleViewForMessage:) only message-level slot is set(listItemViewForMessage:) set(subtitleViewForMessage:) (plus the per-media variants). The granular slots set(trailingViewForMessage:) exist for CONVERSATIONS only, as assignable properties: leading/title/subtitle/tailViewForConversation Documented correctly for the first time: SearchScope = .conversations | .messages SearchFilter = .messages | .conversations | .unread | .groups | .photos | .videos | .links | .documents | .audio AI Quick Reference (the block agents read first) had nine wrong entries. Fixed: dropped the two request builders, onBack/onError/onEmpty, and hideNavigationBar/ hideBackButton/hideReceipts — CometChatSearch inherits UIViewController, NOT CometChatListBase, so it has none of the list-base chrome. Added the five per-media listItemViewFor* slots that were missing, and marked onConversationClicked/onMessageClicked as assignable properties. Also replaced the CometChatMessages composite references (IOS-DOCS-001) with the host-composed MessagesVC, and repointed an itemView cross-reference from CometChatMessages to CometChatMessageList. search.mdx now passes the docs-vs-kit API check with zero findings. Running total across ui-kit/ios: 19 pages / 76 findings -> 17 pages / 55 findings.
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
…5 page users.mdx — verified against 5.1.19: set(usersRequestBuilder:) -> set(userRequestBuilder:) (singular "user") set(subtitleView:) -> set(subtitle:) ((User?) -> UIView) set(trailView:) -> set(trailingView:) ((User?) -> UIView) set(avatarStyle:) / set(statusIndicatorStyle:) -> public vars, assigned set(emptyStateView:) closure -> emptyStateView is a UIView you assign (inherited from CometChatListBase) set(onSelection:) left as-is — it IS real on CometChatUsers. groups.mdx — same subtitle/trailingView/style/emptyStateView corrections, plus: set(onSelection:) -> onSelectedItemProceed. CometChatGroups has NO onSelection (CometChatUsers does). Groups exposes onDidSelect (per row) and onSelectedItemProceed (multi-select confirm). Note for future edits: these renames are PER TYPE, not global. CometChatGroupMembers genuinely ships set(subtitleView:) and set(trailView:) — the kit is internally inconsistent, so a blanket search-and-replace would break the one page that is right. IOS-DOCS-001 cleanup — CometChatMessages and the *WithMessages composites are now gone from every v5 page (12 files). Code samples instantiate the developer's own MessagesVC / ChatListVC with a pointer to the recipe page; prose and AI Quick Reference component lists name the three real components instead. The v2/v3/v4 trees are untouched, and upgrading-from-v4.mdx keeps its 4 references — a migration page must name what it migrates away from. Running total for ui-kit/ios: 19 pages / 76 findings -> 10 pages / 24 findings.
…an against 5.1.19 Wrong CALL FORM (member exists as a settable property, not set(label:)): CometChatCallButtons onVoiceCallClick, onVideoCallClick CometChatMessageHeader avatarStyle, statusIndicatorStyle, typingIndicatorStyle, onAiChatHistoryClicked, onAiNewChatClicked (the two AI hooks also take (User) -> Void, not () -> Void) CometChatGroupMembers menus ([UIBarButtonItem]?), onSelectedItemProceed, emptyStateView CometChatMessageList emptyStateView Renamed: set(callSettingBuilder:) -> set(callSettingsBuilder:) (plural) set(onDeclineClick:) -> set(onCancelClick:) ((Call?, UIViewController?) -> Void) set(sessionID:) -> set(sessionId:) (casing — would not compile) CometChatDateStyle -> DateStyle (this one is un-prefixed) Absent, replaced with what actually ships: CometChatMessageList/Composer set(parentMessage:) -> set(parentMessageId: Int). Note CometChatThreadedMessageHeader DOES take set(parentMessage: BaseMessage) — left untouched. Three components, two different parent APIs. CometChatGroupMembers set(onSelection:) -> onSelectedItemProceed (no onSelection here) CometChatMessageHeaderOption -> CometChatPopupMenu.MenuItem(title:icon:action:); set(options:) takes [CometChatPopupMenu.MenuItem]?, not a closure returning options CometChatAddMembers -> no such component. Sample now builds its own picker and points at CometChat.addMembersToGroup(guid:groupMembers:bannedUIDs:onSuccess:onError:) (/sdk/ios/group-add-members) — UI Kit first, SDK where the kit has nothing. CometChatAvatar set(user:) -> setAvatar(avatarUrl:with:) (its only other API is set(image:)) ui-kit/ios: 51 pages scanned, 0 findings. Started at 19 pages / 76 findings.
…e table row guide-ai-agent.mdx declares its components as `private var messageList: CometChatMessageList!` and assigns them later. The checker only resolved let/var-with-initialiser and lazy-var forms, so every call on those receivers was silently skipped — hiding messageList/messageComposer set(parentMessage:) (they take set(parentMessageId: Int); only CometChatThreadedMessageHeader takes a BaseMessage) and messageList.set(emptyStateView:) (an assignable UIView). Fixed the receiver resolution in test-suite/scripts/verify-swift-docs-api.mjs rather than hand-patching the page, so the whole class is caught from now on. groups.mdx also had a prose table row still naming `set(onSelection:)`, which CometChatGroups does not have. The checker scans code fences only, so prose and tables need a separate sweep — noted for the remaining docs work. ui-kit/ios: 51 pages, 0 findings.
…re is no .both conversations.mdx taught `.set(conversationType: .both)`. Two errors, both verified against CometChatSDK 4.1.7 as shipped inside the 5.1.19 kit: method ConversationRequestBuilder ships setConversationType(conversationType:), NOT set(conversationType:). Zero matches for the documented form. case CometChat.ConversationType has .user / .group / .none. There is no .both. To get both 1:1s and groups you omit the call — that is the default. Fixed the Filtering example, both Filter Recipes rows, the two later usages, and the ConversationType block in the AI Quick Reference. Found by reviewing the iOS core skill against the kit rather than by the checker: the checker only indexed top-level declarations, so a NESTED type (ConversationRequest.ConversationRequestBuilder) was never indexed and every call on it was silently skipped. Checker fixed alongside.
Adds the iOS half of the scoped llms index set, matching the existing llms-angular-v5 and llms-javascript-v4 pages. - ui-kit/ios/llms-ios-v5.mdx — all 51 iOS UI Kit v5 pages, incl. a "Task guides (recipes)" section, plus install facts an agent must not guess (SPM-only; all three packages required because the UI Kit binary's .swiftinterface imports CometChatSDK and CometChatCallsSDK; exact version pins; iOS 15.1 floor; the xcconfig -> Info.plist -> Bundle credential chain) and the no-composite-component rule. - sdk/ios/llms-ios-v4.mdx — all iOS Chat SDK v4 pages, plus the .success/.onError and CometChatException.errorDescription facts. Both are unlisted but indexable (no docs.json entry), following the angular/js-sdk precedent: Mintlify's `hidden` implies noindex, which would drop them from search and AI context. Scope is v5/v4 only; the v2/v3/v4 UI Kit trees and 2.0/3.0 SDK trees are excluded so agents are never routed at dead API surfaces. All 119 links verified to resolve. Closes the DOCS-GAP recorded in the skills pack's cometchat-ios-core/references/docs-map.md (ENG-38208). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…, thread pattern All three verified against the shipped 5.1.19 .swiftinterface and the docs themselves, not taken on trust. BLOCKING — message-header.mdx: the example passed a closure to set(options:), but CometChatMessageHeader declares func set(options: [CometChatPopupMenu.MenuItem]?) -> CometChatMessageHeader i.e. the ARRAY directly. The closure-taking set(options:) overloads belong to Conversations / Users / Groups / GroupMembers, each returning their own option type — the header has no such overload, so the example could not compile. Now builds the two MenuItems (init is title:icon:action:, confirmed) and passes [viewProfileOption, muteOption]. Comment added naming why the header differs. P1 — groups.mdx: the Actions table listed `onSelectedItemProceed` twice; the replacement row was added without removing the pre-existing one. Dropped the stale duplicate, kept the row that names the multi-select context. P1 — message-list.mdx (2 sites): thread-opening pushed MessagesVC() and called .set(user:) / .set(parentMessage:) on it. ios-conversation.mdx defines MessagesVC with only `var user` / `var group` and no setters at all, so our own pages contradicted each other. Switched both to the pattern guide-threaded-messages.mdx already teaches: ThreadedMessagesVC() with `parentMessage` assigned as a property. MessagesVC is the root-conversation VC, not a thread host. Re-compiled all three pages against the real framework: 135 fences, 0 remaining failures of the reported classes. The 2 residual groups.mdx errors are the pre-existing CometChatGroupOption(id:title:icon:backgroundColor:onClick:) label mismatch — untouched by this PR and tracked with the wider backlog. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
raj-dubey1
left a comment
Contributor
There was a problem hiding this comment.
Docs review — iOS UI Kit v5 corrections + LLM indexes (ENG-38208)
Reviewed from the skills pack perspective: does this PR give the iOS skills a correct docs surface to fetch from?
✅ What's correct and solid
llms-ios-v5.mdx — "unlisted not hidden" pattern correct (explicit rationale comment, no hidden: true, not in docs.json). All required sections present. Critical iOS-specific content baked correctly:
- "All three packages required, even for a chat-only app" — present with the exact reason (kit binary's
.swiftinterfaceimportsCometChatCallsSDK) - Exact SPM version pins, not
from:floors — present - iOS 15.1 deployment floor — present
.xcconfig→Info.plist→Bundle.maincredential chain — present- No-composite-component rule — emphatic and prominent: "There is no composite chat component.
CometChatMessages,CometChatConversationsWithMessages,CometChatUsersWithMessagesandCometChatGroupsWithMessagesdo not exist in v5" - Task guides (recipes) section — present with 12 entries
components-overview.mdx correction — removing CometChatMessages, CometChatUsersWithMessages, CometChatGroupsWithMessages, CometChatConversationsWithMessages is the correct call. All four are verified absent from the 5.1.19 .swiftinterface. Replacing the "Configurations" section (MessageHeaderConfiguration/MessageListConfiguration/MessageComposerConfiguration are also v4-only) with the per-instance configuration pattern is accurate.
search.mdx correction — large and correct. set(onError:)/set(onEmpty:), the request-builder setters, set(initialView:), and the four *ForMessage granular slots do not exist. The replacement surface (set(searchIn:), set(searchFilters:initialFilter:), set(emptyView:), set(errorView:), set(loadingView:), set(listItemViewFor*:)) and the SearchScope/SearchFilter case documentation are all present in the 5.1.19 .swiftinterface. CometChatSearch inheriting UIViewController (not CometChatListBase) is the correct framing.
llms-ios-v4.mdx (SDK) — present. .success/.onError callback shape and CometChatException.errorDescription (not localizedDescription) documented.
conversations.mdx — Quick Reference block: Correct. CometChatMentionsFormatter (not CometChatMentionTextFormatter), trailView slot name, emptyStateView as property assignment (not closure), loadingView (not loadingStateView) — all accurate in the machine-readable Quick Reference accordion.
❌ Fix required: conversations.mdx Custom View Slots table still has stale entries
The PR description says "tailView→trailView" and "loadingStateView→loadingView" were fixed. The Quick Reference block at the top of the page is correct. But the human-readable "Custom View Slots" table further down still contains the stale names:
| Table still shows | Should be |
|---|---|
tailView | trailView |
emptyStateView: () -> UIView (closure) | emptyStateView: UIView (property, not a closure) |
loadingStateView | loadingView |
An agent that reads the full page (not just the Quick Reference accordion) will pick up the wrong slot name and write code that silently fails. The Quick Reference is agent-primary, but the discrepancy between the two sections is a correctness issue that should be resolved in this PR. Three targeted table row fixes:
<!-- tailView → trailView -->| trailView | (Conversation) -> UIView | Right side (time, badge) |<!-- emptyStateView closure → UIView property -->| emptyStateView | UIView | Shown when there are no conversations |<!-- loadingStateView → loadingView -->| loadingView | UIView | Shown while conversations are loading |⚠️ Tracked items (not blocking merge after the table fix)
conversations.mdx stays open while remaining ui-kit/ios pages are corrected — the PR description correctly notes this. The skills build against the Mintlify preview until merged. Merge order matters: this PR → skills docs-map.md URL swap → skills PR release.
Running total: 19→17 pages / 76→55 findings — the PR documents its own coverage accurately. Remaining pages will be corrected in this PR before merge per the description. Track that the conversations table fix above is included in that pass.
Summary
The LLM indexes are complete and correctly formed. The components-overview and search corrections are substantial and correct — they directly unblock the iOS skills from generating code that won't compile. The conversations.mdx Custom View Slots table is the one outstanding fix from the set the PR claims to have corrected; three table rows need updating to match the Quick Reference block already on the page.
Fix those three table rows in conversations.mdx, then this PR is ready to merge.
…sure types Raj's review on #477: the Quick Reference accordion was corrected but the human-readable "Custom View Slots" table below it still carried the old names, so an agent reading the full page picks up slots that do not exist. Verified each against the shipped 5.1.19 .swiftinterface and master-v5 source rather than taken on trust — one of them did not hold: tailView -> trailView CometChatConversations exposes set(trailView:) taking a closure over Conversation. `public var tailView: UIStackView` DOES exist, but on a different type, so the old row was not simply a typo. loadingStateView -> loadingView CometChatListBase (which Conversations inherits) declares `loadingView`; `loadingStateView` appears nowhere in source. emptyStateView () -> UIView is a UIView you ASSIGN, not a closure. errorStateView () -> UIView same — set(errorStateView: UIView). That last row is a FOURTH instance of the same defect, not in the review: the three Raj listed all shared the closure-vs-property confusion, and errorStateView sat in the same table with the same wrong shape. Also renamed the stale `### tailView` section heading to `### trailView` — its body already used set(trailView:) correctly, so heading and code disagreed. No inbound #tailview anchors exist. Re-compiled the page against the real framework: 50 fences, 0 slot-name errors. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Building the iOS skills pack (ENG-38208) required an existence oracle for the iOS UI Kit. Cross-checking the docs against that oracle surfaced a class of defect worth fixing at source: pages documenting API that does not exist in the shipped kit, including v4 components left standing on v5 pages.
Everything here is verified against the public
.swiftinterfaceof CometChatUIKitSwift 5.1.19 — the artifact this org's owncometchat-uikit-iosPackage.swiftpins (sha256a0f19887…, checked). Nothing is inferred from prose or from another docs page.The headline defect
components-overviewdocumented — and its Quick Reference actively recommended — four composite components:CometChatMessages·CometChatUsersWithMessages·CometChatGroupsWithMessages·CometChatConversationsWithMessagesNone exist in v5. Verified three ways: 0 occurrences in the public
.swiftinterface, no ObjC@interface, and 0 files in the UI Kit source tree declaring them. They are v4 components (11 files underui-kit/ios/v4/use them correctly).This mattered because it was the documented quick-integration path on the canonical component page — code following it does not compile. Replaced throughout with the host-composed pattern the recipe pages (
ios-conversation,ios-one-to-one-chat,ios-tab-based-chat) already teach correctly.Pages in this PR
components-overview.mdx— composites removed; "Configurations" section rewritten (MessageHeaderConfiguration/MessageListConfiguration/MessageComposerConfigurationare also v4-only) to show per-instance configuration; hierarchy diagram re-rooted at the developer's own VC.conversations.mdx— six style props plusonSearchClickare settable properties, notset(label:)methods;CometChatMentionTextFormatter/CometChatURLTextFormatterreplaced with the realCometChatMentionsFormatter(no URL formatter ships); custom empty state corrected to assign aUIViewrather than return one from a closure; Quick Reference slot names fixed (tailView→trailView,loadingStateView→loadingView).search.mdx— largest divergence.set(onError:)/set(onEmpty:), both request-builder setters,set(initialView:)and the four*ForMessagegranular slots do not exist. Replaced with the real surface:set(searchIn:),set(searchFilters:initialFilter:),set(emptyView:)/set(errorView:)/set(loadingView:),set(listItemViewFor*:), and the conversation-level granular properties.SearchScopeandSearchFiltercases are now documented. Quick Reference had nine wrong entries —CometChatSearchinheritsUIViewController, notCometChatListBase, so it has none of the list-base chrome props.Verification
Each page passes a mechanical docs-vs-kit API check (extracts Swift fences, resolves receiver types and superclasses, asserts every symbol and
set(label:)exists in the shipped interface).Running total for
ui-kit/ios: 19 pages / 76 findings → 17 pages / 55 findings. Remaining pages will be added to this PR as they are fixed.Also in this PR — the scoped iOS LLM docs indexes
Adds the iOS half of the scoped
llmsindex set, the twin of the existingllms-angular-v5andllms-javascript-v4pages. These were the last platform pair missing.ui-kit/ios/llms-ios-v5.mdx— all 51 iOS UI Kit v5 pages, including the"Task guides (recipes)" section, plus the install facts an agent otherwise gets wrong:
SPM-only; all three packages required (
cometchat-uikit-ios+chat-sdk-ios+calls-sdk-ios— the UI Kit binary's public.swiftinterfaceimports both SDKs, so even achat-only app fails to resolve without Calls); exact version pins rather than
from:floorsagainst a prebuilt binary; the iOS 15.1 floor; the
.xcconfig→ Info.plist →Bundlecredential chain; and the no-composite-component rule this PR establishes.
sdk/ios/llms-ios-v4.mdx— all iOS Chat SDK v4 pages, plus the.success/.onErrorcallback shape and
CometChatException.errorDescription(notlocalizedDescription).Both are unlisted but indexable — no
docs.jsonentry, matching the angular/js-sdkprecedent. Mintlify's
hiddenimpliesnoindex, which would drop them from search and from AIcontext, defeating the purpose.
Scope is v5/v4 only: the UI Kit
v2/,v3/,v4/trees and the SDK2.0/,3.0/trees areexcluded so agents are never routed at dead API surfaces.
All 119 links verified to resolve. Every UI Kit v5 page is covered; the only SDK page not
linked is
ios-overview, which is itself a pointer back at the UI Kit.This closes the DOCS-GAP recorded in the skills pack's
cometchat-ios-core/references/docs-map.md— once merged, that file's{DOCS_BASE}/ui-kit/ios/llms-ios-v5.mdline starts resolving with no other change.Note for reviewers
This PR stays open while the rest of
ui-kit/iosis corrected — the Mintlify preview it produces is being used as the docs source while the iOS skills are authored, so the skills build against corrected docs rather than the current ones.