Example/custom logo example (#6145)

* init

* guides for custom page and custom components

* more examples commits

* yarn.lock  and example changes

* dependency fix

* add more markup

* Update docs/pages/docs/guides/custom-admin-ui-pages.mdx

Co-authored-by: Mitchell Hamilton <mitchell@hamil.town>

* fix readme

* more updates to the docs

* add smoke tests

* add to smoke tests in workflow

* fill in links

* add new guides to docs nav

* fix docs

* fix readME.md

* changelog reset

* add examples link to docs and README.md

* update explanation of Old JSX transforms

* change custom-admin-ui-components example to custom-admin-ui-logo

* Update docs/pages/docs/guides/custom-admin-ui-pages.mdx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update docs/pages/docs/guides/custom-admin-ui-pages.mdx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update docs/pages/docs/guides/custom-admin-ui-pages.mdx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update docs/pages/docs/guides/custom-admin-ui-pages.mdx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update examples/custom-admin-ui-pages/README.md

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update examples/custom-admin-ui-pages/README.md

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update examples/custom-admin-ui-components/README.md

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update docs/pages/docs/guides/custom-admin-ui-components.mdx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update examples/custom-admin-ui-pages/admin/pages/custom-page.tsx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update examples/custom-admin-ui-components/README.md

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* add CTA to give us feedback on admin-ui components in slack

* fix up odds and ends in formatting for docs pages

* Update docs/pages/docs/guides/custom-admin-ui-logo.mdx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update docs/pages/docs/guides/custom-admin-ui-logo.mdx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update docs/pages/docs/guides/custom-admin-ui-pages.mdx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update docs/pages/docs/guides/custom-admin-ui-pages.mdx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update docs/pages/docs/guides/custom-admin-ui-pages.mdx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update docs/pages/docs/guides/custom-admin-ui-logo.mdx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update docs/pages/docs/guides/custom-admin-ui-logo.mdx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Feedback from Tim

* add image

* Update examples/README.md

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update examples/custom-admin-ui-logo/README.md

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* remove custom-page artifacts, so we can just ship the custom-logo guides for now

* dependency resolution

* update schema.graphql;

* Update examples/README.md

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update docs/components/docs/Navigation.tsx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update docs/components/docs/ExamplesList.tsx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update docs/pages/docs/guides/custom-admin-ui-logo.mdx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update docs/pages/docs/guides/custom-admin-ui-logo.mdx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* update broken image link

* remove admin-ui pages test

* Update examples/custom-admin-ui-logo/admin/components/CustomLogo.tsx

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* add chnageset

* Update examples/custom-admin-ui-logo/README.md

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update examples/custom-admin-ui-logo/README.md

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update examples/custom-admin-ui-logo/README.md

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

* Update examples/custom-admin-ui-logo/README.md

Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

Co-authored-by: Mitchell Hamilton <mitchell@hamil.town>
Co-authored-by: Tim Leslie <timl@thinkmill.com.au>

.changeset/slimy-moons-grow.md

@@ -0,0 +1,5 @@
+---
+'@keystone-next/example-custom-admin-ui-logo': major
+---
+
+Initial version of the custom-admin-ui-logo example.

.github/workflows/tests.yml

@@ -261,6 +261,7 @@ jobs:
             'with-auth.test.ts',
             'custom-field-view.test.ts',
             'custom-field.test.ts',
+            'custom-admin-ui-logo.test.ts',
           ]
       fail-fast: false
     steps:

docs/components/docs/ExamplesList.tsx

@@ -123,6 +123,15 @@ export function Examples() {
         Adds a custom field type based on the <InlineCode>integer</InlineCode> field type which lets
         users rate items on a 5-star scale. Builds on the Blog starter project.
       </Well>
+      <Well
+        grad="grad3"
+        heading="Custom Admin UI Logo"
+        href="https://github.com/keystonejs/keystone/blob/master/examples/custom-admin-ui-logo"
+        target="_blank"
+        rel="noopener noreferrer"
+      >
+        Adds a custom logo component in the Admin UI. Builds on the Task Manager starter project.
+      </Well>
     </div>
   );
 }

docs/components/docs/Navigation.tsx

@@ -144,6 +144,9 @@ export function DocsNavigation() {
         <NavItem href="/docs/guides/custom-fields">
           Custom Fields <Badge look="success">New</Badge>
         </NavItem>
+        <NavItem href="/docs/guides/custom-admin-ui-logo">
+          Custom Admin UI Logo <Badge look="success">New</Badge>
+        </NavItem>
         <NavItem href="/docs/guides/access-control" isPlaceholder>
           Access Control
         </NavItem>
@@ -156,9 +159,6 @@ export function DocsNavigation() {
         <NavItem href="/docs/guides/internal-items" isPlaceholder>
           Internal Items
         </NavItem>
-        <NavItem href="/docs/guides/custom-admin-ui-pages" isPlaceholder>
-          Custom Admin UI Pages
-        </NavItem>
         <NavItem href="/docs/guides/custom-field-views" isPlaceholder>
           Custom Field Views
         </NavItem>

docs/pages/docs/guides/custom-admin-ui-logo.mdx

@@ -0,0 +1,49 @@
+import { ComingSoon } from '../../../components/docs/ComingSoon';
+import { Markdown } from '../../../components/Markdown';
+import { Alert } from '../../../components/primitives/Alert'
+
+# Custom Admin UI Logo
+
+In this guide we'll show you how to add a custom logo to the Keystone Admin UI.
+
+!> Presently the only replaceable component in the Admin UI is the logo. If you have suggestions as to other components you would like to be able to customise, let us know on [Slack](https://community.keystonejs.com)
+
+To import a custom component for rendering within the Admin UI, ensure that the `admin/config.tsx` file exists in the root of your Keystone project.
+This file expects a named export `components`.
+
+```tsx
+// admin/config.tsx
+function CustomLogo () {
+    return <h3>Custom Logo here</h3>
+}
+
+export const components = {
+    Logo: CustomLogo
+}
+```
+
+If you have styling constraints, we recommend using the jsx export from the `@keystone-ui/core` package, as this will ensure that the version of emotion you're using conforms with the version of emotion used internally within Keystone.
+
+```tsx
+// admin/config.tsx
+/** @jsxRuntime classic */
+/** @jsx jsx */
+import { jsx } from '@keystone-ui/core';
+
+function CustomLogo () {
+    return <h3 css={{
+        background: 'papayawhip'
+    }}>Custom Logo here</h3>
+}
+
+export const components = {
+    Logo: CustomLogo
+}
+```
+
+Of course this is purely a recommendation, if you would prefer to roll your own css-in-js solution in with your custom component please feel free to! Although this may require additional configuration outside of the scope of this guide.
+
+Once you've added your custom logo component you should see it rendered out in the Admin UI.
+![image of Admin UI with custom logo](/assets/guides/custom-admin-ui-logo/custom-logo-result.png)
+
+export default ({ children }) => <Markdown>{children}</Markdown>;

examples/README.md

@@ -26,6 +26,7 @@ Each project below demonstrates a Keystone feature you can learn about and exper
 - [Testing](./testing): Adds tests with `@keystone-next/testing` to the `withAuth()` example.
 - [Custom field](./custom-field): Adds a custom `stars` field to the Blog base.
 - [Custom field view](./custom-field-view): Adds a custom Admin UI view to a `json` field to the Task Manager base.
+- [Custom Admin UI components](./custom-admin-ui-logo): Adds a custom logo in the Admin UI to the Task Manager base.
 
 ## Running examples
 

examples/custom-admin-ui-logo/CHANGELOG.md

@@ -0,0 +1 @@
+# @keystone-next/example-custom-admin-ui-logo

examples/custom-admin-ui-logo/README.md

@@ -0,0 +1,28 @@
+## Feature Example - Custom Components for the Admin UI
+
+This project demonstrates how to create a custom logo in the Admin UI.
+
+## Instructions
+
+To run this project, clone the Keystone repository locally then navigate to this directory and run:
+
+```shell
+yarn dev
+```
+
+This will start the Admin UI at [localhost:3000](http://localhost:3000).
+
+You can use the Admin UI to create items in your database.
+
+You can also access a GraphQL Playground at [localhost:3000/api/graphql](http://localhost:3000/api/graphql), which allows you to directly run GraphQL queries and mutations.
+
+🚀 Congratulations, you're now up and running with Keystone!
+
+## Exporting custom components
+
+This project shows how to export a custom logo to be rendered in the Admin UI via the [`/admin/config.tsx`](./admin/config.tsx) file. As elaborated on in the [Custom Logo](https://keystonejs.com/docs/guides/custom-admin-ui-logo) guide, the named `components` export of this file is used to replace specific components for use in the Admin UI.
+
+If you have specific components you think should also be exposed from this config, please let us know on [Slack](https://community.keystonejs.com)
+
+**NOTE** The Keystone monorepo leverages a babel config that means we use the old jsx transform (this doesn't have an impact on the code we ship to npm).
+This is why there are `import React from 'react'` statements in our examples. This is NOT necessary outside of the Keystone repo (unless you have a babel config with the old jsx transform which is currently the default with @babel/preset-react) as you'll be using Next.js' babel config which uses the new jsx transform.

examples/custom-admin-ui-logo/admin/components/CustomLogo.tsx

@@ -0,0 +1,26 @@
+/** @jsx jsx */
+import Link from 'next/link';
+import { jsx, H3 } from '@keystone-ui/core';
+
+export const CustomLogo = () => {
+  return (
+    <H3>
+      <Link href="/" passHref>
+        <a
+          css={{
+            // TODO: we don't have colors in our design-system for this.
+            backgroundImage: `linear-gradient(to right, #0ea5e9, #6366f1)`,
+            backgroundClip: 'text',
+            lineHeight: '1.75rem',
+            color: 'transparent',
+            verticalAlign: 'middle',
+            transition: 'color 0.3s ease',
+            textDecoration: 'none',
+          }}
+        >
+          LegendBoulder After
+        </a>
+      </Link>
+    </H3>
+  );
+};

examples/custom-admin-ui-logo/admin/config.tsx

@@ -0,0 +1,7 @@
+import { AdminConfig } from '@keystone-next/types';
+import { CustomLogo } from './components/CustomLogo';
+
+// Presently the Logo is the only Admin UI component that is customisable.
+export const components: AdminConfig['components'] = {
+  Logo: CustomLogo,
+};

examples/custom-admin-ui-logo/keystone.ts

@@ -0,0 +1,11 @@
+import { config } from '@keystone-next/keystone/schema';
+import { lists } from './schema';
+
+export default config({
+  db: {
+    provider: 'sqlite',
+    url: process.env.DATABASE_URL || 'file:./keystone-example.db',
+  },
+  lists,
+  ui: {},
+});

examples/custom-admin-ui-logo/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@keystone-next/example-custom-admin-ui-logo",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "scripts": {
+    "dev": "keystone-next dev",
+    "start": "keystone-next start",
+    "build": "keystone-next build"
+  },
+  "dependencies": {
+    "@keystone-next/fields": "^12.0.0",
+    "@keystone-next/keystone": "^22.0.0",
+    "@keystone-next/types": "^22.0.0",
+    "@keystone-ui/core": "^3.1.0",
+    "next": "^10.2.3",
+    "react": "^17.0.2"
+  },
+  "devDependencies": {
+    "typescript": "^4.3.5"
+  },
+  "engines": {
+    "node": "^12.20 || >= 14.13"
+  },
+  "repository": "https://github.com/keystonejs/keystone/tree/master/examples/custom-admin-ui-logo"
+}