Merge pull request #37 from universal-ember/more-docs

More docs
universal-ember · Mar 11, 2024 · 583ad7f · 583ad7f
2 parents a096ea0 + 9dbd269
commit 583ad7f
Show file tree

Hide file tree

Showing 22 changed files with 707 additions and 521 deletions.
diff --git a/docs-app/app/index.html b/docs-app/app/index.html
@@ -16,6 +16,27 @@
     <link integrity="" rel="stylesheet" href="{{rootURL}}assets/docs-app.css" />
 
     {{content-for "head-footer"}}
+
+    <style>
+      #kolay__loading {
+        position: fixed;
+        inset: 0;
+        background: #111;
+        color: white;
+        font-size: 4rem;
+        z-index: 10;
+        font-family: "System UI", "System";
+        display: flex;
+        justify-content: center;
+        align-items: center;
+        flex-direction: column;
+        gap: 4rem;
+
+        [aria-busy="true"] {
+          background: #111;
+        }
+      }
+    </style>
   </head>
 
   <body>
@@ -24,6 +45,11 @@
     <script src="{{rootURL}}assets/vendor.js"></script>
     <script src="{{rootURL}}assets/docs-app.js"></script>
 
+    <div id="kolay__loading">
+      Kolay
+      <article aria-busy="true"></article>
+    </div>
+
     {{content-for "body-footer"}}
   </body>
 </html>
diff --git a/docs-app/app/routes/application.ts b/docs-app/app/routes/application.ts
@@ -1,19 +1,57 @@
 import Route from '@ember/routing/route';
 import { service } from '@ember/service';
 
+import rehypeShikiFromHighlighter from '@shikijs/rehype/core';
+import { colorScheme, sync } from 'ember-primitives/color-scheme';
+import { getHighlighterCore } from 'shiki/core';
+import getWasm from 'shiki/wasm';
+
+sync();
+
 import type { DocsService, Manifest } from 'kolay';
 
 export default class ApplicationRoute extends Route {
   @service('kolay/docs') declare docs: DocsService;
 
   async model(): Promise<{ manifest: Manifest }> {
+    const highlighter = await getHighlighterCore({
+      themes: [import('shiki/themes/github-dark.mjs'), import('shiki/themes/github-light.mjs')],
+      langs: [
+        import('shiki/langs/javascript.mjs'),
+        import('shiki/langs/typescript.mjs'),
+        import('shiki/langs/bash.mjs'),
+        import('shiki/langs/css.mjs'),
+        import('shiki/langs/html.mjs'),
+        import('shiki/langs/glimmer-js.mjs'),
+        import('shiki/langs/glimmer-ts.mjs'),
+      ],
+      langAlias: {
+        gjs: 'glimmer-js',
+        gts: 'glimmer-ts',
+      },
+      loadWasm: getWasm,
+    });
+
     await this.docs.setup({
-      apiDocs: await import('kolay/api-docs:virtual'),
-      manifest: await import('kolay/manifest:virtual'),
+      apiDocs: import('kolay/api-docs:virtual'),
+      manifest: import('kolay/manifest:virtual'),
       resolve: {
-        'ember-primitives': await import('ember-primitives'),
-        kolay: await import('kolay'),
+        'ember-primitives': import('ember-primitives'),
+        kolay: import('kolay'),
       },
+      rehypePlugins: [
+        [
+          rehypeShikiFromHighlighter,
+          highlighter,
+          {
+            defaultColor: colorScheme.current === 'dark' ? 'dark' : 'light',
+            themes: {
+              light: 'github-light',
+              dark: 'github-dark',
+            },
+          },
+        ],
+      ],
     });
 
     return { manifest: this.docs.manifest };

diff --git a/docs-app/app/templates/application.gjs b/docs-app/app/templates/application.gjs
@@ -26,6 +26,7 @@ export default Route(
     </div>
     <style>
       .application__layout { display: grid; grid-template-columns: max-content 1fr; gap: 2rem; }
+      header { filter: drop-shadow(0 10px 0.75rem #000000); }
     </style>
   </template>
 );
diff --git a/docs-app/app/templates/nav.gts b/docs-app/app/templates/nav.gts
@@ -1,6 +1,8 @@
 import Component from '@glimmer/component';
 import { service } from '@ember/service';
 
+import { pascalCase } from 'change-case';
+
 import type { TOC } from '@ember/component/template-only';
 import type RouterService from '@ember/routing/router-service';
 import type { Collection, DocsService, Page } from 'kolay';
@@ -9,17 +11,34 @@ export class Nav extends Component {
   @service('kolay/docs') declare docs: DocsService;
 
   <template>
-    <nav>
+    <nav id="side-nav">
       <Pages @item={{this.docs.tree}} />
     </nav>
-    <style>nav ul { padding-left: 0.5rem; list-style: none; line-height: 1.75rem; }</style>
+    <style>
+      nav#side-nav { min-width: 150px; ul { padding-left: 0.5rem; list-style: none; line-height:
+      1.75rem; } }
+    </style>
   </template>
 }
 
 function isCollection(x: Page | Collection): x is Collection {
   return 'pages' in x;
 }
 
+function nameFor(x: Page) {
+  // We defined componentName via json file
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  if ('componentName' in x) {
+    return `${x.componentName}`;
+  }
+
+  if (x.path.includes('/components/')) {
+    return `<${pascalCase(x.name)} />`;
+  }
+
+  return x.name;
+}
+
 const Pages: TOC<{ Args: { item: Page | Collection } }> = <template>
   <ul>
     {{#if (isCollection @item)}}
@@ -33,7 +52,7 @@ const Pages: TOC<{ Args: { item: Page | Collection } }> = <template>
         </li>
       {{/each}}
     {{else}}
-      <a href={{@item.path}}>{{@item.name}}</a>
+      <a href={{@item.path}}>{{nameFor @item}}</a>
     {{/if}}
   </ul>
 </template>;

diff --git a/docs-app/app/templates/page.gjs b/docs-app/app/templates/page.gjs
@@ -1,15 +1,14 @@
 import { service } from 'ember-primitives/helpers';
 import Route from 'ember-route-template';
-import { highlight } from 'kolay';
+
+function removeLoader() {
+  document.querySelector('#kolay__loading')?.remove();
+}
 
 export default Route(
   <template>
     {{#let (service "kolay/docs") as |docs|}}
-      <div
-        data-prose
-        class="prose p-4"
-        {{(if docs.selected.prose (modifier highlight docs.selected.prose))}}
-      >
+      <div data-prose class="prose p-4">
         {{#if docs.selected.hasError}}
           <div style="border: 1px solid red; padding: 1rem;">
             {{docs.selected.error}}
@@ -18,6 +17,7 @@ export default Route(
 
         {{#if docs.selected.prose}}
           <docs.selected.prose />
+          {{(removeLoader)}}
         {{/if}}
       </div>
     {{/let}}

diff --git a/docs-app/package.json b/docs-app/package.json
@@ -59,7 +59,7 @@
     "ember-load-initializers": "^2.1.2",
     "ember-modifier": "^4.1.0",
     "ember-page-title": "^8.1.0",
-    "ember-primitives": "^0.11.3",
+    "ember-primitives": "^0.11.4",
     "ember-qunit": "^8.0.2",
     "ember-resolver": "^11.0.1",
     "ember-resources": "^7.0.0",
@@ -84,7 +84,7 @@
     "stylelint-prettier": "^5.0.0",
     "tracked-built-ins": "^3.3.0",
     "typescript": "^5.3.3",
-    "webpack": "^5.89.0"
+    "webpack": "^5.90.3"
   },
   "engines": {
     "node": ">= 18"
@@ -96,14 +96,17 @@
     "extends": "../package.json"
   },
   "dependencies": {
+    "@shikijs/rehype": "^1.1.7",
     "@universal-ember/kolay-ui": "workspace:^",
-    "@universal-ember/test-support": "^0.0.0",
+    "@universal-ember/test-support": "^0.1.1",
+    "change-case": "^5.4.3",
     "ember-async-data": "^1.0.3",
     "ember-cached-decorator-polyfill": "^1.0.2",
-    "ember-repl": "3.0.0",
+    "ember-repl": "^4.1.1",
     "ember-route-template": "^1.0.3",
     "kolay": "workspace:^",
-    "reactiveweb": "^1.2.1"
+    "reactiveweb": "^1.2.1",
+    "shiki": "^1.1.7"
   },
   "dependenciesMeta": {
     "kolay": {

diff --git a/docs-app/public/docs/usage/setup.md b/docs-app/public/docs/usage/setup.md
@@ -18,45 +18,67 @@
 
 <hr>
 
+## Install[^type-module]
+
+```bash
+pnpm add kolay @universal-ember/kolay-ui
+```
+
+[^type-module]: `@universal-ember/kolay-ui` is only needed because due to a temporary technical problem. Once the ember ecosystem has broader `package.json#type=module` support for its own ember using libraries, `@universal-ember/kolay-ui` can be removed and there will only be `kolay`. Note that `package.json#type=module` support is already working and has worked for a good number of years for non-Ember libraries.
+
 ## Setup
 
-There are two areas of configuration needed: buildtime, and runtime.
+There are two areas of configuration needed: buildtime, and runtime[^runtime-optional].
+
+[^runtime-optional]: The runtime components are optional and if you don't import them, they will not be included in your app. However, since links generated from markdown use vanilla `<a>` tags, you'll probably want at least `@properLinks` from `ember-primitives`.
 
 ### Build: Embroider + Webpack
 
 import `kolay/webpack`
 
 ```js
-const { createManifest, apiDocs } = await import("kolay/webpack");
+const { kolay } = await import("kolay/webpack");
 
 return require("@embroider/compat").compatBuild(app, Webpack, {
   /* ... */
   packagerOptions: {
     webpackConfig: {
       devtool: "source-map",
-      plugins: [createManifest({ src: "public/docs" }), apiDocs({ package: "kolay" })],
+      plugins: [
+        kolay({
+          src: "public/docs",
+          // Generate API docs from JSDoc
+          packages: ["kolay"],
+        }),
+      ],
     },
   },
 });
 ```
 
-You can create docs for multiple libraries by invoking these plugins more than once:
+You can create docs for multiple libraries at once:
 
 ```js
 devtool: 'source-map',
 plugins: [
-  createManifest({ src: 'public/docs', name: 'own-manifest.json' }),
-  apiDocs({ package: 'kolay' }),
-  createManifest({ src: '../../my-library', name: 'my-library-manifest.json' }),
-  apiDocs({ package: 'my-library' }),
+  kolay({
+    src: 'public/docs',
+    groups: [
+      {
+        name: 'Runtime',
+        src: '../ui/docs',
+      },
+    ],
+    // Generate API docs from JSDoc
+    // NOTE: these must all be declared in your projects package.json
+    packages: ['kolay', 'ember-primitives', 'ember-resources'],
+  }),
 ],
 ```
 
-See related for
+This is useful for monorepos where they may be scaling to large teams and many packages could end up being added quickly. In a traditionally compiled app, this may cause build times to slow down over time. Since many docs' sites are deployed continuously, that is wasted time and money spent on building things that may not be looked at all that often (we all wish folks looked at docs more!).
 
-- [createManifest(...)](/plugins/create-manifest.md)
-- [apiDocs(...)](/plugins/api-docs.md)
-- [All Build Plugins](/plugins/index.md)
+By distributing the rendering of pages to the browesr, we only pay for "build" when somenoe views the page.
 
 ### Runtime: Routing
 

diff --git a/package.json b/package.json
@@ -103,8 +103,8 @@
     "@universal-ember/kolay-ui": "workspace:^",
     "concurrently": "^8.2.2",
     "ember-modifier": "^4.1.0",
-    "ember-primitives": "^0.11.3",
-    "ember-repl": "3.0.0",
+    "ember-primitives": "^0.11.4",
+    "ember-repl": "^4.1.1",
     "ember-resources": "^7.0.0",
     "ember-source": "~5.7.0",
     "eslint": "^8.56.0",
@@ -118,7 +118,7 @@
     "typescript": "^5.3.3",
     "vite": "^5.1.3",
     "vitest": "^1.2.2",
-    "webpack": "^5.89.0"
+    "webpack": "^5.90.3"
   },
   "engines": {
     "node": ">= 18"
@@ -167,7 +167,7 @@
     "overrides": {
       "@ember/test-waiters": "^3.1.0",
       "webpack": "^5.90.3",
-      "ember-repl": "^3.0.0"
+      "ember-repl": "^4.1.1"
     }
   },
   "volta": {
@@ -182,7 +182,7 @@
     "@universal-ember/kolay-ui": "workspace:^",
     "ember-modifier": "^4.1.0",
     "ember-primitives": "^0.11.3",
-    "ember-repl": "3.0.0-beta.8",
+    "ember-repl": "^4.1.1",
     "ember-resources": "^7.0.0",
     "ember-source": "~5.5.0",
     "reactiveweb": "^1.2.1",