More signature rendering

.eslintignore

@@ -1,6 +1,8 @@
 node_modules/
 declarations/
+dist/
+dist-typedoc/
 *.yaml
 *.md
 docs-app/
-ui/
+ui/

.gitignore

@@ -1,3 +1,5 @@
 node_modules/
+dist/
+dist-typedoc/
 declarations/
 .turbo/

.prettierignore

@@ -1,5 +1,7 @@
 node_modules/
 declarations/
+dist/
+dist-typedoc/
 *.yaml
 *.md
 docs-app/

docs-app/.template-lintrc.js

@@ -5,5 +5,7 @@ module.exports = {
   rules: {
     'no-forbidden-elements': 'off',
     'no-inline-styles': 'off',
+    // Let prettier maintain invis
+    'no-whitespace-for-layout': 'off',
   },
 };

docs-app/app/routes/application.ts

@@ -25,6 +25,7 @@ export default class ApplicationRoute extends Route {
         import('shiki/langs/glimmer-js.mjs'),
         import('shiki/langs/glimmer-ts.mjs'),
         import('shiki/langs/handlebars.mjs'),
+        import('shiki/langs/jsonc.mjs'),
       ],
       langAlias: {
         gjs: 'glimmer-js',

docs-app/app/styles/app.css

@@ -3,3 +3,22 @@
 a.active {
   font-weight: bold;
 }
+
+pre.shiki {
+  white-space: pre-wrap;
+  /* overflow: hidden; */
+}
+pre.shiki > code {
+  /* padding-right: 1rem; */
+  /* overflow: auto; */
+}
+
+fieldset {
+  padding: 1rem;
+}
+fieldset summary {
+  font-weight: bold;
+  font-style: italic;
+  font-size: 1.2rem;
+  border-bottom: 1px solid #888;
+}

docs-app/app/templates/application.gts

@@ -1,42 +1,127 @@
+import 'ember-mobile-menu/themes/android';
+
+import { on } from '@ember/modifier';
+
 import { pascalCase, sentenceCase } from 'change-case';
 import ENV from 'docs-app/config/environment';
+// @ts-expect-error no types for the mobile-menu
+import MenuWrapper from 'ember-mobile-menu/components/mobile-menu-wrapper';
 import { pageTitle } from 'ember-page-title';
 import Route from 'ember-route-template';
 import { GroupNav, PageNav } from 'kolay/components';
 
+import type { TOC } from '@ember/component/template-only';
 import type { Page } from 'kolay';
 
+const Menu: TOC<{ Element: SVGElement }> = <template>
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    x="0px"
+    y="0px"
+    viewBox="0 0 50 50"
+    style="fill:currentColor"
+    ...attributes
+  ><path
+      d="M 0 7.5 L 0 12.5 L 50 12.5 L 50 7.5 Z M 0 22.5 L 0 27.5 L 50 27.5 L 50 22.5 Z M 0 37.5 L 0 42.5 L 50 42.5 L 50 37.5 Z"
+    ></path></svg>
+</template>;
+
+const SideNav: TOC<{ Element: HTMLElement }> = <template>
+  <aside>
+    <PageNav ...attributes>
+      <:page as |page|>
+        {{nameFor page}}
+      </:page>
+      <:collection as |collection|>
+        {{sentenceCase collection.name}}
+      </:collection>
+    </PageNav>
+  </aside>
+</template>;
+
 export default Route(
   <template>
     {{pageTitle ENV.APP.shortVersion}}
 
-    <div class="container">
-      <header>
-        <GroupNav />
-      </header>
-
-      <div class="application__layout">
-        <aside>
-          <PageNav id="side-nav">
-            <:page as |page|>
-              {{nameFor page}}
-            </:page>
-            <:collection as |collection|>
-              {{sentenceCase collection.name}}
-            </:collection>
-          </PageNav>
-        </aside>
-
-        <main>
-          {{outlet}}
-        </main>
-      </div>
-
-    </div>
+    <MenuWrapper as |mmw|>
+      <mmw.MobileMenu @mode="push" @maxWidth={{200}} as |mm|>
+        <SideNav {{on "click" mm.actions.close}} />
+      </mmw.MobileMenu>
+
+      <mmw.Content class="container">
+        <header style="display: flex; align-items: baseline; gap: 1rem;">
+          <mmw.Toggle><Menu /></mmw.Toggle>
+          <GroupNav />
+        </header>
+
+        <div class="big-layout">
+          <SideNav />
+
+          <main style="padding-top: 1rem;">
+            {{outlet}}
+          </main>
+        </div>
+      </mmw.Content>
+    </MenuWrapper>
+
+    {{!-- prettier-ignore --}}
     <style>
-      .application__layout { display: grid; grid-template-columns: max-content 1fr; gap: 2rem;
-      padding-top: 1rem; } header { border-bottom: 1px solid currentColor; } nav#side-nav {
-      min-width: 150px; ul { padding-left: 0.5rem; list-style: none; line-height: 1.75rem; } }
+      .mobile-menu-wrapper__content,
+      .mobile-menu__tray {
+        background: none;
+      }
+
+      header {
+        border-bottom: 1px solid currentColor;
+      }
+
+      header button.mobile-menu__toggle {
+        padding: 0.25rem 0.5rem;
+        background: none;
+        color: currentColor;
+        width: 48px;
+        height: 44px;
+        display: inline-flex;
+        align-self: center;
+        align-items: center;
+        justify-content: center;
+        margin: 0;
+      }
+
+      @media (min-width: 768px) {
+        header button.mobile-menu__toggle {
+          display: none;
+        }
+      }
+
+      @media (max-width: 768px) {
+        .big-layout aside { display: none; }
+      }
+
+      .big-layout {
+        display: grid;
+        grid-template-columns: max-content 1fr;
+        gap: 2rem;
+
+        main {
+          max-width: 100%;
+          display: flex;
+          flex-direction: column;
+          overflow-x: hidden;
+        }
+      }
+
+      .mobile-menu__tray, .big-layout {
+        overflow-x: hidden;
+
+        nav {
+          ul {
+            padding-left: 0.5rem;
+            list-style: none;
+            line-height: 1.75rem;
+          }
+        }
+      }
     </style>
   </template>
 );

docs-app/app/templates/page.gjs

@@ -2,25 +2,25 @@ import Route from 'ember-route-template';
 import { Page } from 'kolay/components';
 
 function removeLoader() {
-  document.querySelector('#kolay__loading')?.remove();
+  requestAnimationFrame(() => {
+    document.querySelector('#kolay__loading')?.remove();
+  });
 }
 
 export default Route(
   <template>
-    <div>
-      <Page>
-        <:error as |error|>
-          <div style="border: 1px solid red; padding: 1rem;">
-            {{error}}
-          </div>
-        </:error>
+    <Page>
+      <:error as |error|>
+        <div style="border: 1px solid red; padding: 1rem;">
+          {{error}}
+        </div>
+      </:error>
 
-        <:success as |Prose|>
-          <Prose />
-          {{(removeLoader)}}
-        </:success>
+      <:success as |Prose|>
+        <Prose />
+        {{(removeLoader)}}
+      </:success>
 
-      </Page>
-    </div>
+    </Page>
   </template>
 );

docs-app/ember-cli-build.js

@@ -8,6 +8,9 @@ module.exports = async function (defaults) {
     'ember-cli-babel': {
       enableTypeScriptTransform: true,
     },
+    autoImport: {
+      watchedDependencies: ['kolay', '@universal-ember/kolay-ui'],
+    },
   });
 
   const { Webpack } = require('@embroider/webpack');

docs-app/package.json

@@ -102,6 +102,7 @@
     "change-case": "^5.4.3",
     "ember-async-data": "^1.0.3",
     "ember-cached-decorator-polyfill": "^1.0.2",
+    "ember-mobile-menu": "^5.1.0",
     "ember-repl": "^4.1.1",
     "ember-route-template": "^1.0.3",
     "kolay": "workspace:^",

docs-app/public/docs/plugins/kolay.md

@@ -1,14 +1,38 @@
 # `kolay(...)`
 
-This is the main build plugin
+Kolay requires some build-time static analysis to function.
 
-## Config
+`kolay(...)` is the only required plugin. This generates the navigation and information about how Kolay's runtime code will fetch the markdown documents deployed with the app's static assets. Optionally, if a list of packages is provided, apiDocs will be generated from your library's type declarations. Rendering these api docs uses the [Signature Components][ui-signature] or [`APIDocs`][ui-apiDocs] components.
 
-either json or jsonc
+[plugin-kolay]: /plugins/kolay.md
+[ui-signature]: /Runtime/components/component-signature.md
+[ui-apiDocs]: /Runtime/components/api-docs.md
 
-- set order
-- change name
+Usage in embroider / webpack:
+
+```js
+// ember-cli-build.js
+
+const { kolay } = await import("kolay/webpack");
+
+return require("@embroider/compat").compatBuild(app, Webpack, {
+  /* ... */
+  packagerOptions: {
+    webpackConfig: {
+      /* ... */
+      plugins: [kolay(/* Options, see below */)],
+    },
+  },
+});
+```
 
 ```hbs live no-shadow
-<APIDocs @package="kolay" @module="declarations/vite" @name="kolay" />
+<APIDocs @package="kolay" @module="declarations/plugins/types" @name="Options" />
 ```
+
+## Conventions
+
+There are a few ways you can collect docs:
+
+- using `src`, these are your main docs, but they could also be your only docs. If you have a small project, this will provide the best experience for working with documentation as changes to this directory are (especially if using the recommended `public/docs` value), will automatically reload when changes are made.
+- The `groups` option are where more freedom is provided. This can point at a `docs` folder in another folder in your project, or it can point at a `components` folder and the plugin will pick up all markdown files it finds in there. This can be useful for co-locating docs with their implementations.

docs-app/public/docs/usage/meta.jsonc

@@ -0,0 +1,4 @@
+{
+  // This is in order of need-to-know
+  "order": ["setup", "rendering-pages", "ordering-pages"],
+}

docs-app/public/docs/usage/ordering-pages.md

@@ -0,0 +1,54 @@
+## Ordering
+
+At build time, the order of both pages and folders can be configured by providing a `meta.json` or `meta.jsonc` file as a sibling to the list of paths you want to sort.
+
+### Sorting folders
+
+For example, in this project, the docs are in folders in `public/docs`:
+
+```
+public/
+  docs/
+    plugins/
+    usage/
+```
+
+But we want `usage` to come before `plugins`, even though alphabetically, `plugins` comes before `usage`.
+
+We can create a `meta.jsonc` file at `public/docs/meta.jsonc`:
+
+```jsonc
+{
+  // We want usage to be first, which breaks the
+  // default sort order provided by the filesystem: Alphabetical
+  "order": ["usage", "plugins"],
+}
+```
+
+With `jsonc`, we can have comments to explain our reasoning for having configuration at all, and now when rendering the navigation at runtime, we can have `Usage` rendered above `Plugins` without needing to implement any runtime code to do this for us.
+
+### Sorting pages
+
+For example, in this project, the pages under `usage` appear alphabetically in the filesystem like this:
+
+```
+public/
+  docs/
+    usage/
+      ordering-pages.md
+      rendering-pages.md
+      setup.md
+```
+
+Alphabetical ordering in this case is backwards from how it is _useful_ to read about the information contained within these documents.
+
+To sort these pages, we can create a `meta.json` file at `public/docs/usage/meta.jsonc` with the following contents:
+
+```jsonc
+{
+  // This is in order of need-to-know
+  "order": ["setup", "rendering-pages", "ordering-pages"],
+}
+```
+
+And then the order of these pages is adjusted so that at runtime, there is nothing to do! 🥳