Add Wildcard developer documentation (#19523)

.github/ISSUE_TEMPLATE/wildcard_proposal.md

@@ -0,0 +1,21 @@
+---
+name: Propose a new Wildcard component
+about: Propose a new component for the Wildcard component library
+title: ''
+labels: 'team/frontend-platform'
+assignees: ''
+
+---
+
+#### Component description
+<!--
+Summarize how this component is suitable for Wildcard:
+- Where will this component be used?
+- Are we currently using some variant of this component in the codebase?
+-->
+
+#### Have designs already been created? If so, please link them here.
+<!-- Link to Figma file or design document -->
+
+#### Additional context
+<!-- Add any other context or other information you'd like to include. -->

client/wildcard/CODENOTIFY

@@ -0,0 +1,3 @@
+# See https://github.com/sourcegraph/codenotify for documentation.
+
+**/* @sourcegraph/frontend-platform

client/wildcard/README.md

@@ -4,20 +4,12 @@
 
 The Wildcard component library is a collection of design-approved reusable components that are suitable for use within the Sourcegraph codebase.
 
-## Usage
-
-This library is setup as a `yarn workspace` symlink.
-
-You can import components from the library like so:
-
-```javascript
-import { PageSelector } from '@sourcegraph/wildcard'
-```
-
-## Structure
+## Folder Structure
 
 - `src/`
   - `components/`
     Reusable React components
   - `hooks/`
     Reusable React hooks. Typically utilities or headless components
+
+See [Wildcard documentation](https://docs.sourcegraph.com/dev/background-information/web/wildcard) for more information.

doc/dev/background-information/index.md

@@ -16,6 +16,7 @@
   - [Developing the web app](web/web_app.md)
   - [Developing the code host integrations](web/code_host_integrations.md)
   - [Working with GraphQL](web/graphql.md)
+  - [Wildcard Component Library](web/wildcard.md)
   - [Styling UI](web/styling.md)
   - [Accessibility](web/accessibility.md)
   - [Build process](web/build.md)

doc/dev/background-information/web/index.md

@@ -6,6 +6,7 @@ See also our [TypeScript guide](https://about.sourcegraph.com/handbook/engineeri
 - [Developing the web app](web_app.md)
 - [Developing the code host integrations](code_host_integrations.md)
 - [Working with GraphQL](graphql.md)
+- [Wildcard Component Library](wildcard.md)
 - [Styling UI](styling.md)
 - [Accessibility](accessibility.md)
 - [Build process](build.md)

doc/dev/background-information/web/wildcard-component-architecture.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="241" height="231" viewBox="-0.5 -0.5 241 231"><rect width="240" height="70" rx="10.5" ry="10.5" fill="#0fb6f2" stroke="#000" pointer-events="all"/><switch transform="translate(-.5 -.5)"><foreignObject style="overflow:visible;text-align:left" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display:flex;align-items:unsafe center;justify-content:unsafe center;width:238px;height:1px;padding-top:35px;margin-left:1px"><div style="box-sizing:border-box;font-size:0;text-align:center"><div style="display:inline-block;font-size:16px;font-family:Helvetica;color:#fff;line-height:1.2;pointer-events:all;white-space:normal;word-wrap:normal">Component</div></div></div></foreignObject><text x="120" y="40" fill="#FFF" font-family="Helvetica" font-size="16" text-anchor="middle">Component</text></switch><rect y="80" width="240" height="70" rx="10.5" ry="10.5" fill="#b114f7" stroke="#000" pointer-events="all"/><switch transform="translate(-.5 -.5)"><foreignObject style="overflow:visible;text-align:left" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display:flex;align-items:unsafe center;justify-content:unsafe center;width:238px;height:1px;padding-top:115px;margin-left:1px"><div style="box-sizing:border-box;font-size:0;text-align:center"><div style="display:inline-block;font-size:16px;font-family:Helvetica;color:#fff;line-height:1.2;pointer-events:all;white-space:normal;word-wrap:normal">Behaviour Hook</div></div></div></foreignObject><text x="120" y="120" fill="#FFF" font-family="Helvetica" font-size="16" text-anchor="middle">Behaviour Hook</text></switch><rect y="160" width="240" height="70" rx="10.5" ry="10.5" fill="#f86012" stroke="#000" pointer-events="all"/><switch transform="translate(-.5 -.5)"><foreignObject style="overflow:visible;text-align:left" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display:flex;align-items:unsafe center;justify-content:unsafe center;width:238px;height:1px;padding-top:195px;margin-left:1px"><div style="box-sizing:border-box;font-size:0;text-align:center"><div style="display:inline-block;font-size:16px;font-family:Helvetica;color:#fff;line-height:1.2;pointer-events:all;white-space:normal;word-wrap:normal">State Hook</div></div></div></foreignObject><text x="120" y="200" fill="#FFF" font-family="Helvetica" font-size="16" text-anchor="middle">State Hook</text></switch><switch><a transform="translate(0 -5)" xlink:href="https://www.diagrams.net/doc/faq/svg-export-text-problems" target="_blank"></a></switch></svg>

doc/dev/background-information/web/wildcard.md

@@ -0,0 +1,89 @@
+# Wildcard Component Library
+
+Wildcard is a collection of design-approved, accessible and well-tested React components that are suitable for use within the Sourcegraph codebase.
+
+## Usage
+
+This library is setup as a `yarn workspace` symlink.
+
+You can import components from the library like so:
+
+```javascript
+import { PageSelector } from '@sourcegraph/wildcard'
+```
+
+## Architecture
+
+We want our components to be composable and reusable, but we don't want to 'reinvent the wheel' for everything we build. To support this, we aim to build our components in consideration of the following architecture as inspired by [React Spectrum](https://react-spectrum.adobe.com/).
+
+<img src="wildcard-component-architecture.svg" />
+
+#### State hook
+
+These hooks should act as a 'headless component', it should be entirely focused on state management and should function irrespective of any UI elements. Essentially, this hook should be decoupled from the component file and should be importable and usable on its own.
+
+These hooks will make it much easier to change styles whilst maintaining UX. In many scenarios we may find that it makes sense to use third-party libraries for common patterns here.
+
+Simplified Example:
+
+Fully featured PageSelector component:
+```jsx
+<PageSelector currentPage={page} onPageChange={setPage} totalPages={10} />
+```
+
+Alternative PageSelector making use of a state hook:
+```jsx
+const [page, setPage] = useState(1);
+const pages = useOffsetPagination({ page, onChange: setPage, totalPages: 10 })
+
+return (
+  // Map over pages and render some UI!
+)
+```
+
+#### Behavior Hook
+
+These hooks should capture key behavior and accessibility patterns that can be isolated from UI elements. For many simple components, this hook won't be necessary or required. For larger components this becomes more meaningful. Behavior hooks shouldn't be coupled to components in any way and should be importable on their own.
+
+For example, a `<PageSelector>` component might use `useOffsetPagination` to determine which pages to render, but we might have additional _behavior_ like keyboard shortcuts to select a page. This is where something like `useKeyboard` might be used.
+
+Often it will be clear when we have shared behaviour that should be extracted into these hooks. It may also make sense to use suitable third-party libraries for common patterns here just like our state hooks.
+
+Simplified Example:
+```jsx
+const [page, setPage] = useState(1);
+const status = useKeyboard({
+  key: 'ArrowRight'
+  onKeyDown: (e) => setPage(prev => prev + 1)
+})
+const pages = useOffsetPagination({ page, onChange: setPage, totalPages: 10 })
+
+return (
+  // Map over pages and render some UI!
+)
+```
+
+#### Component
+
+Now we have extracted our state and behaviour into separate hooks, our UI component should just focus on displaying simple elements with specific styles. It should be able to make use of our hooks to enhance these elements with more complex behavior and state.
+
+For most scenarios, **it doesn't make sense to use third-party libraries here.** When compared to other applications, it will ultimately be our UI that will significantly differ, not our UX.
+
+
+## Contributing
+Anyone can contribute to Wildcard:
+
+- If you want to add a new component, consider starting a new [component proposal](https://github.com/sourcegraph/sourcegraph/issues/new?labels=team/frontend-platform&template=wildcard_proposal.md) for visibility.
+- If you notice a bug, or want to change an existing component, simply make a PR if you are able to make this change, or create a new GitHub issue and add the label: `team/frontend-platform`.
+
+
+## FAQ
+
+### *Where can I view all of our current Wildcard components?*
+You can view our components:
+
+- On Storybook. The latest components are deployed at http://storybook.sgdev.org/.
+- In the code. If you want to take a closer look, the component code lives in [this directory](https://github.com/sourcegraph/sourcegraph/tree/main/client/wildcard).
+
+### *Can I use these components in a different codebase?*
+Currently our Wildcard components are not published on NPM, if this is a requirement please create a new issue and add the label: `team/frontend-platform`.

doc/dev/index.md

@@ -79,7 +79,11 @@ Clarification and discussion about key concepts, architecture, and development s
 - [Developing the web clients](background-information/web/index.md)
   - [Developing the web app](background-information/web/web_app.md)
   - [Developing the code host integrations](background-information/web/code_host_integrations.md)
+  - [Working with GraphQL](background-information/web/graphql.md)
+  - [Wildcard Component Library](background-information/web/wildcard.md)
   - [Styling UI](background-information/web/styling.md)
+  - [Accessibility](background-information/web/accessibility.md)
+  - [Build process](background-information/web/build.md)
 - [Developing the GraphQL API](background-information/graphql_api.md)
 - [Developing batch changes](background-information/batch_changes/index.md)
 - [Developing code intelligence](background-information/codeintel/index.md)