From bb5fcec57f917d7234f1f51d5516b2fd59d5b2c9 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 15 Mar 2024 20:56:54 -0400 Subject: [PATCH 01/18] More signature rendering --- ui/docs/docs/helper-signature.md | 17 +++++++ ui/docs/docs/modifier-signature.md | 17 +++++++ ui/src/components/page-nav.gts | 4 +- ui/src/samples/-private/modifier.ts | 12 +++++ ui/src/typedoc/signature/args.gts | 28 +++++++++++ ui/src/typedoc/signature/component.gts | 64 +++-------------------- ui/src/typedoc/signature/element.gts | 36 +++++++++++++ ui/src/typedoc/signature/helper.gts | 0 ui/src/typedoc/signature/modifier.gts | 70 ++++++++++++++++++++++++++ 9 files changed, 190 insertions(+), 58 deletions(-) create mode 100644 ui/docs/docs/helper-signature.md create mode 100644 ui/docs/docs/modifier-signature.md create mode 100644 ui/src/samples/-private/modifier.ts create mode 100644 ui/src/typedoc/signature/args.gts create mode 100644 ui/src/typedoc/signature/element.gts create mode 100644 ui/src/typedoc/signature/helper.gts create mode 100644 ui/src/typedoc/signature/modifier.gts diff --git a/ui/docs/docs/helper-signature.md b/ui/docs/docs/helper-signature.md new file mode 100644 index 00000000..f82778dd --- /dev/null +++ b/ui/docs/docs/helper-signature.md @@ -0,0 +1,17 @@ +# `` + +Render the docs generated from Comments, [JSDoc](https://jsdoc.app/), etc, specialized specifically for helpers and plain functions, which have a known signature format, consisting of `Args`, and `Return`. + +This, along with the other API doc-related components, are powered by [TypeDoc](https://typedoc.org/) and generated from declarations. + +## API Reference + +API Reference generated via: + +```hbs live no-shadow preview below + +``` diff --git a/ui/docs/docs/modifier-signature.md b/ui/docs/docs/modifier-signature.md new file mode 100644 index 00000000..b23245db --- /dev/null +++ b/ui/docs/docs/modifier-signature.md @@ -0,0 +1,17 @@ +# `` + +Render the docs generated from Comments, [JSDoc](https://jsdoc.app/), etc, specialized specifically for element modifiers, which have a known signature format, consisting of `Args`, and `Element`. + +This, along with the other API doc-related components, are powered by [TypeDoc](https://typedoc.org/) and generated from declarations. + +## API Reference + +API Reference generated via: + +```hbs live no-shadow preview below + +``` diff --git a/ui/src/components/page-nav.gts b/ui/src/components/page-nav.gts index 1cd906fa..174ac4c8 100644 --- a/ui/src/components/page-nav.gts +++ b/ui/src/components/page-nav.gts @@ -29,7 +29,7 @@ export class PageNav extends Component<{ * ```gjs * import { PageNav } from 'kolay/components'; * - * function toSentenceCase(name) { /* ... \*\/ } + * function toSentenceCase(name) { /* ... *\/ } * * ; diff --git a/ui/src/typedoc/styles.css b/ui/src/typedoc/styles.css index 3274cf40..2d84c002 100644 --- a/ui/src/typedoc/styles.css +++ b/ui/src/typedoc/styles.css @@ -95,6 +95,12 @@ section { align-items: baseline; } +.typedoc__component-signature__block .typedoc-rendered-comment { + border-top: 1px solid #333; + padding-top: 0.5rem; + margin-top: 0.5rem; +} + .typedoc__component-signature__block .typedoc-declaration-name + .typedoc-reference { From 9e4cdb77b4989c5ce3c536c8e22a2a294cfb16f5 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Sat, 16 Mar 2024 21:18:48 -0400 Subject: [PATCH 06/18] CSS oof --- docs-app/app/styles/app.css | 9 ++++++ docs-app/app/templates/application.gts | 7 +++++ docs-app/app/templates/page.gjs | 24 +++++++-------- docs-app/public/docs/usage/rendering-pages.md | 30 +++++++++---------- ui/src/samples/-private/helper.ts | 4 +++ ui/src/typedoc/styles.css | 17 +++++++++-- 6 files changed, 60 insertions(+), 31 deletions(-) diff --git a/docs-app/app/styles/app.css b/docs-app/app/styles/app.css index acfca60b..e92d7b32 100644 --- a/docs-app/app/styles/app.css +++ b/docs-app/app/styles/app.css @@ -3,3 +3,12 @@ a.active { font-weight: bold; } + +pre.shiki { + white-space: pre-wrap; + /* overflow: hidden; */ +} +pre.shiki>code { + /* padding-right: 1rem; */ + /* overflow: auto; */ +} diff --git a/docs-app/app/templates/application.gts b/docs-app/app/templates/application.gts index f31bbe33..afb216ec 100644 --- a/docs-app/app/templates/application.gts +++ b/docs-app/app/templates/application.gts @@ -106,6 +106,13 @@ export default Route( 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 { diff --git a/docs-app/app/templates/page.gjs b/docs-app/app/templates/page.gjs index 9646aacb..99f5a79a 100644 --- a/docs-app/app/templates/page.gjs +++ b/docs-app/app/templates/page.gjs @@ -7,20 +7,18 @@ function removeLoader() { export default Route( ); diff --git a/docs-app/public/docs/usage/rendering-pages.md b/docs-app/public/docs/usage/rendering-pages.md index e16b3ee5..36ef95d1 100644 --- a/docs-app/public/docs/usage/rendering-pages.md +++ b/docs-app/public/docs/usage/rendering-pages.md @@ -15,22 +15,20 @@ function removeLoader() { export default Route( , ); ``` diff --git a/ui/src/samples/-private/helper.ts b/ui/src/samples/-private/helper.ts index 2cd0c469..e0b52854 100644 --- a/ui/src/samples/-private/helper.ts +++ b/ui/src/samples/-private/helper.ts @@ -3,6 +3,10 @@ import Helper from '@ember/component/helper'; import type { HelperLike } from '@glint/template'; +/** + * @param {number} a - the first argument + * @param {number} b - the second argument + */ export function plainHelperA(a: number, b: number): number { return a + b; } diff --git a/ui/src/typedoc/styles.css b/ui/src/typedoc/styles.css index 2d84c002..aeff232f 100644 --- a/ui/src/typedoc/styles.css +++ b/ui/src/typedoc/styles.css @@ -46,18 +46,23 @@ section { } .typedoc-named-tuple, -.typedoc-component-arg-info { +.typedoc-component-arg-info, +.typedoc-helper-arg-info { display: flex; gap: 0.25rem; align-items: baseline; justify-content: space-between; } -.typedoc-component-arg-info > .typedoc-name { +.typedoc-component-arg-info > .typedoc-name, +.typedoc-helper-arg-info > .typedoc-name { display: inline-block; margin: 0; font-size: 1rem; font-weight: bold; } +.typedoc-helper-arg-info { + border-bottom: 1px gray dashed; +} .typedoc-declaration-children { list-style: none; @@ -69,11 +74,13 @@ section { * Component Signatures * */ +.typedoc__modifier-signature__element, .typedoc__component-signature__element, .typedoc__component-signature__block { display: block; padding: 0 1rem; } +.typedoc__modifier-signature__element-type, .typedoc__component-signature__element-type { display: flex; gap: 0.25rem; @@ -81,12 +88,14 @@ section { justify-content: space-between; } +.typedoc__modifier-signature__element-type > .typedoc__name, .typedoc__component-signature__element-type > .typedoc__name { display: inline-block; margin: 0; line-height: 1.5rem; } +.typedoc__modifier-signature__element-header, .typedoc__component-signature__element-header { display: flex; flex-direction: row; @@ -95,6 +104,7 @@ section { align-items: baseline; } +.typedoc__helper-signature__block .typedoc-rendered-comment, .typedoc__component-signature__block .typedoc-rendered-comment { border-top: 1px solid #333; padding-top: 0.5rem; @@ -122,11 +132,13 @@ section { padding: 0.5rem; } +.typedoc-helper-arg, .typedoc-component-arg { margin-bottom: 0.5rem; display: grid; gap: 0.25rem; } +.typedoc-helper-arg > .typedoc-name, .typedoc-component-arg > .typedoc-name, .typedoc__component-signature__block > .typedoc__name { font-size: 1.2rem; @@ -137,6 +149,7 @@ section { max-height: unset; } +.typedoc-helper-arg .typedoc-rendered-comment p, .typedoc-component-arg .typedoc-rendered-comment p { margin-top: 0; margin-bottom: 0.25rem; From cc0fc9cd3b043b24cfcecad99b34fd733d244424 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Sat, 16 Mar 2024 22:21:57 -0400 Subject: [PATCH 07/18] fix --- docs-app/app/templates/page.gjs | 4 +++- ui/src/typedoc/signature/args.gts | 8 +++++++- ui/src/typedoc/signature/helper.gts | 6 ++++-- ui/src/typedoc/styles.css | 10 +++++++++- 4 files changed, 23 insertions(+), 5 deletions(-) diff --git a/docs-app/app/templates/page.gjs b/docs-app/app/templates/page.gjs index 99f5a79a..80cbb9c5 100644 --- a/docs-app/app/templates/page.gjs +++ b/docs-app/app/templates/page.gjs @@ -2,7 +2,9 @@ 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( diff --git a/ui/src/typedoc/signature/args.gts b/ui/src/typedoc/signature/args.gts index d88cfc66..936990c7 100644 --- a/ui/src/typedoc/signature/args.gts +++ b/ui/src/typedoc/signature/args.gts @@ -5,6 +5,12 @@ import type { DeclarationReflection } from 'typedoc'; const not = (x: unknown) => !x; +const isComponent = (kind: 'component' | 'modifier' | 'helper') => kind === 'component'; + +/** + * Only components' args are prefixed with a `@`, + * because only components have template-content. + */ export const Args: TOC<{ Args: { kind: 'component' | 'modifier' | 'helper'; info: any }; }> =