Skip to content
This repository has been archived by the owner on Dec 15, 2022. It is now read-only.

Documentation on our component architecture #1726

Merged
merged 6 commits into from Oct 5, 2018
Merged

Documentation on our component architecture #1726

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
139fc03
Copy-paste from the original issue
smashwilson Oct 5, 2018
3e8f3ad
Absolute paths maybe?
smashwilson Oct 5, 2018
3636a57
Nah let's not get too ambitious here
smashwilson Oct 5, 2018
2e5bebf
Let's make the Atlas its own top-level thing
smashwilson Oct 5, 2018
8bbf040
Begin the atlas :world_map:
smashwilson Oct 5, 2018
0310d93
Atlas descriptions
smashwilson Oct 5, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
143 changes: 143 additions & 0 deletions docs/react-component-atlas.md
View file
Open in desktop
@@ -0,0 +1,143 @@
# React Component Atlas

This is a high-level overview of the structure of the React component tree that this package creates. It's intended _not_ to be comprehensive, but to give you an idea of where to find specific bits of functionality.

> [`<RootController>`](/lib/controllers/root-controller.js)
>
> Root of the entire, unified React component tree. Mostly responsible for registering pane items, status bar tiles, workspace commands, and managing dialog box state. Action methods that are shared across broad swaths of the component tree.
>
> > [`<GitTabItem>`](/lib/items/git-tab-item.js)
> > [`<GitTabContainer>`](/lib/containers/git-tab-container.js)
> > [`<GitTabController>`](/lib/controllers/git-tab-controller.js)
> > [`<GitTabView>`](/lib/views/git-tab-view.js)
> >
> > The "Git" tab that appears in the right dock (by default).
> >
> > > [`<StagingView>`](/lib/views/staging-view.js)
> > >
> > > The lists of unstaged changes, staged changes, and merge conflicts.
> >
> > > [`<CommitController>`](/lib/controllers/commit-controller.js)
> > > [`<CommitView>`](/lib/views/commit-view.js)
> > >
> > > The commit message editor, submit button, and co-author selection controls.
> >
> > > [`<RecentCommitsController>`](/lib/controllers/recent-commits-controller.js)
> > > [`<RecentCommitsView>` `<RecentCommitView>`](/lib/views/recent-commits-view.js)
> > >
> > > List of most recent commits on the current branch.
>
> > [`<GitHubTabItem>`](/lib/items/github-tab-item.js)
> > [`<GitHubTabContainer>`](/lib/containers/github-tab-container.js)
> > [`<GitHubTabController>`](/lib/controllers/github-tab-controller.js)
> > [`<GitHubTabView>`](/lib/views/github-tab-view.js)
> >
> > The "GitHub" tab that appears in the right dock (by default).
> >
> > > [`<RemoteSelectorView>`](/lib/views/remote-selector-view.js)
> > >
> > > Shown if the current repository has more than one remote that's identified as a github.com remote.
> >
> > > [`<RemoteContainer>`](/lib/containers/remote-container.js)
> > > [`<RemoteController>`](/lib/controllers/remote-controller.js)
> > >
> > > GraphQL query and actions that only require the context of a unique repository name to work.
> > >
> > > > [`<IssueishSearchesController>`](/lib/controllers/issueish-searches-controller.js)
> > > >
> > > > Manages the set of GitHub API issueish searches that we wish to perform, including the special "checked-out pull request" search.
> > > >
> > > > > [`<CurrentPullRequestContainer>`](/lib/containers/current-pull-request-container.js)
> > > > > [`<CreatePullRequestTile>`](/lib/views/create-pull-request-tile.js)
> > > > >
> > > > > GraphQL query and result rendering for the special "checked-out pull request" search.
> > > >
> > > > > [`<IssueishListController>`](/lib/controllers/issueish-list-controller.js)
> > > > > [`<IssueishListView>`](/lib/views/issueish-list-view.js)
> > > > >
> > > > > Render an issueish result as a row within the result list of the current pull request tile.
> > > >
> > > > > [`<IssueishSearchContainer>`](/lib/containers/issueish-search-container.js)
> > > > >
> > > > > GraphQL query and result rendering for an issueish search based on the [`search()`](https://developer.github.com/v4/query/#search) GraphQL connection.
> > > > >
> > > > > > [`<IssueishListController>`](/lib/controllers/issueish-list-controller.js)
> > > > > > [`<IssueishListView>`](/lib/views/issueish-list-view.js)
> > > > > >
> > > > > > Render a list of issueish results as rows within the result list of a specific search.
>
> > [`<FilePatchController>`](/lib/controllers/file-patch-controller.js)
> > [`<FilePatchView>`](/lib/views/file-patch-view.js)
> >
> > The workspace-center pane that appears when looking at the staged or unstaged changes associated with a file.
> >
> > :construction: Being rewritten in [#1712](https://github.com/atom/github/pull/1512) :construction:
>
> > [`<IssueishDetailItem>`](/lib/items/issueish-detail-item.js)
> > [`<IssueishDetailContainer>`](/lib/containers/issueish-detail-container.js)
> > [`<IssueishDetailController>`](/lib/controllers/issueish-detail-controller.js)
> > [`<IssueishDetailView>`](/lib/controllers/issueish-detail-controller.js)
> >
> > The workspace-center pane that displays information about a pull request or issue ("issueish", collectively) from github.com.
> >
> > > [`<IssueTimelineController>`](/lib/controllers/issue-timeline-controller.js)
> > > [`<IssueishTimelineView>`](/lib/views/issueish-timeline-view.js)
> > >
> > > Render "timeline events" (comments, label additions or removals, assignments...) related to an issue.
> >
> > > [`<PrTimelineController>`](/lib/controllers/pr-timeline-controller.js)
> > > [`<IssueishTimelineView>`](/lib/views/issueish-timeline-view.js)
> > >
> > > Render "timeline events" related to a pull request.
> >
> > > [`<PrStatusesView>`](/lib/views/pr-statuses-view.js)
> > >
> > > Display the current build state of a pull request in detail, including a "donut chart" and links to individual build results.
> >
> > > [`<PrCommitsView>`](/lib/views/pr-commits-view.js)
> > > [`<PrCommitView>`](/lib/views/pr-commit-view.js)
> > >
> > > Enumerate the commits associated with a pull request.
>
> > [`<InitDialog>`](/lib/views/init-dialog.js)
> > [`<CloneDialog>`](/lib/views/clone-dialog.js)
> > [`<OpenIssueishDialog>`](/lib/views/open-issueish-dialog.js)
> > [`<CredentialDialog>`](/lib/views/credential-dialog.js)
> >
> > Various dialog panels we use to (modally) collect information from users. Notably, the CredentialDialog is used for usernames, passwords, SSH key passwords, and GPG passphrases.
>
> > [`<RepositoryConflictController>`](/lib/controllers/repository-conflict-controller.js)
> >
> > Identifies TextEditors opened on files that git believes contain merge conflicts.
> >
> > > [`<EditorConflictController>`](/lib/controllers/editor-conflict-controller.js)
> > >
> > > Parses conflict regions from the buffer associated with a single TextEditor.
> > >
> > > > [`<ConflictController>`](/lib/controllers/conflict-controller.js)
> > > >
> > > > Creates TextEditor decorations related to one conflict region, including resolution controls.
>
> > [`<StatusBarTileController>`](/lib/controllers/status-bar-tile-controller.js)
> >
> > Add the git and GitHub-related tiles to Atom's status bar.
> >
> > > [`<BranchView>`](/lib/views/branch-view.js)
> > >
> > > The little widget that tells you what branch you're on.
> >
> > > [`<BranchMenuView>`](/lib/views/branch-menu-view.js)
> > >
> > > Menu that appears within a tooltip when you click the current branch which lets you switch or create branches.
> >
> > > [`<PushPullView>`](/lib/views/push-pull-view.js)
> > >
> > > Shows the relative position of your local `HEAD` to its upstream ("1 ahead", "2 behind"). Allows you to fetch, pull, or push.
> >
> > > [`<ChangedFilesCountView>`](/lib/views/changed-files-count-view.js)
> > >
> > > Displays the git logo and the number of changed files. Clicking it opens the git tab.
> >
> > > [`<GithubTileView>`](/lib/views/changed-files-count-view.js)
> > >
> > > Displays the GitHub logo. Clicking it opens the GitHub tab.
27 changes: 27 additions & 0 deletions docs/react-component-classification.md
View file
Open in desktop
@@ -0,0 +1,27 @@
# React Component Classification

This is a high-level summary of the organization and implementation of our React components.

## Items

**Items** are intended to be used as top-level components within subtrees that are rendered into some [Portal](https://reactjs.org/docs/portals.html) and passed to the Atom API, like pane items, dock items, or tooltips. They are mostly responsible for implementing the [Atom "item" contract](https://github.com/atom/atom/blob/a3631f0dafac146185289ac5e37eaff17b8b0209/src/workspace.js#L29-L174).

These live within [`lib/items/`](/lib/items), are tested within [`test/items/`](/test/items), and are named with an `Item` suffix. Examples: `PullRequestDetailItem`, `FilePatchItem`.

## Containers

**Containers** are responsible for statefully fetching asynchronous data and rendering their children appropriately. They handle the logic for how subtrees handle loading operations (displaying a loading spinner, passing null objects to their children) and how errors are reported. Containers should mostly be thin wrappers around things like [`<ObserveModel>`](lib/views/observe-model.js), [`<QueryRenderer>`](https://facebook.github.io/relay/docs/en/query-renderer.html), or [context](https://reactjs.org/docs/context.html) providers

These live within [`lib/containers`]/(lib/containers), are tested within [`test/containers`](/test/containers), and are named with a `Container` suffix. Examples: `PrInfoContainer`, `GitTabContainer`.

## Controllers

**Controllers** are responsible for implementing action methods and maintaining logical application state for some subtree of components. A Controller's `render()` method should only consist of passing props to a single child, usually a View.

These live within [`lib/controllers`](/lib/controllers), are tested within [`test/controllers`](/test/controllers), and are named with a `Controller` suffix. Examples: `GitTabController`, `RecentCommitsController`, `ConflictController`.

## Views

**Views** are responsible for accepting props and rendering a DOM tree. View components should contain very few non-render methods and little state.

These live within [`lib/views`](/lib/views), are tested within [`test/views`](/test/views), and are named with a `View` suffix. Examples: `GitTabView`, `GithubLoginView`.