fix(ios): correct v5 UI Kit docs against the shipped 5.1.19 kit - #477
Open
ashfaqcometchat wants to merge 6 commits into
Open
fix(ios): correct v5 UI Kit docs against the shipped 5.1.19 kit#477ashfaqcometchat wants to merge 6 commits into
ashfaqcometchat wants to merge 6 commits into
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.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.