From 7cf8d7c80aa91e4b423c390e566a74a7b426ff0c Mon Sep 17 00:00:00 2001 From: Louis-Dominique Dubeau Date: Sat, 31 Mar 2018 10:15:26 -0400 Subject: [PATCH 1/5] Distinguish exported symbols from those not exported. The themes previously did not visually distinguish those symbols that are exported from those that are not exported. This commit modifies the theme to make the distinction. The relevantFlags helper is required due to changes to typedoc. Typedoc would previously arbitrarily narrow the array of flags recorded in reflections to those that the default (and minimal) themes care about. Typedoc has been changed to include all the flags in the array and let the themes decide which flags are relevant to them. --- gruntfile.js | 22 ++++++- src/default/helpers/relevant-flags.ts | 65 +++++++++++++++++++ src/default/partials/flag.hbs | 1 + src/default/partials/header.hbs | 25 +++---- src/default/partials/index.hbs | 12 ++-- src/default/partials/member.hbs | 2 +- .../partials/member.signature.body.hbs | 6 +- src/default/partials/parameter.hbs | 4 +- 8 files changed, 111 insertions(+), 26 deletions(-) create mode 100644 src/default/helpers/relevant-flags.ts create mode 100644 src/default/partials/flag.hbs diff --git a/gruntfile.js b/gruntfile.js index 3d1e6346..aa4088b5 100644 --- a/gruntfile.js +++ b/gruntfile.js @@ -5,7 +5,18 @@ module.exports = function(grunt) ts: { themeDefault: { tsconfig: './tsconfig.json' - } + }, + themeDefaultHelpers: { + options: { + sourceMap: false, + module: 'commonjs', + declaration: false + }, + src: [ + 'src/default/helpers/*.ts', + ], + outDir: 'bin/default/helpers' + }, }, uglify: { themeDefault: { @@ -98,6 +109,11 @@ module.exports = function(grunt) cwd: 'src/default/partials', src: ['**/*.hbs'], dest: 'bin/minimal/partials' + }, { + expand: true, + cwd: 'bin/default/helpers', + src: ['**/*.js'], + dest: 'bin/minimal/helpers', }] }, themeMinimal: { @@ -143,6 +159,6 @@ module.exports = function(grunt) grunt.loadNpmTasks('grunt-ts'); grunt.registerTask('css', ['sass', 'autoprefixer']); - grunt.registerTask('js', ['ts:themeDefault', 'uglify']); - grunt.registerTask('default', ['copy', 'css', 'js', 'string-replace']); + grunt.registerTask('js', ['ts:themeDefault', 'uglify', 'ts:themeDefaultHelpers']); + grunt.registerTask('default', ['copy', 'css', 'js', 'copy:themeDefault2Minimal', 'string-replace']); }; diff --git a/src/default/helpers/relevant-flags.ts b/src/default/helpers/relevant-flags.ts new file mode 100644 index 00000000..d076eccd --- /dev/null +++ b/src/default/helpers/relevant-flags.ts @@ -0,0 +1,65 @@ +// The order of the flags in this list is important. It determines the +// order in which the theme processes the flags. It should reflect the +// order in which the keywords can appear in the TS source. +// +// Some combinations are impossible. In such case, the relative order +// of such impossible combinations does not matter. (e.g. a symbol +// cannot be both private and protected, or abstract and static.) +const relevantFlagList = [ + "Private", + "Protected", + "Abstract", + "Static", + "ExportAssignment", + "Optional", + "DefaultValue", + "Rest", + "Let", + "Const", +]; + +const relevantFlagListWithExport = + ["Export"].concat(relevantFlagList); + +/** + * Filter the flag names that are set on a reflection to only those + * names relevant to this theme. + * + * Templates that iterate over the flags of reflections should + * **always** use this helper to filter the flags, because what flags + * are relevant varies depending on the settings used when rendering + * with the theme and on the reflection being examined. + * + * @returns The filtered array. + */ +export function relevantFlags(options: any): string[] { + + // When excludeNotExported is set, we don't want to produce labels + // for "Exported" because everything is exported and thus the + // labels are pointless. + const list = options.data.root.settings.excludeNotExported ? + relevantFlagList : + relevantFlagListWithExport; + + // We filter the list of relevant flags so that the flags are + // produce in the order set by that list instead of the order the + // flags happen to be set on the reflection. + const flags = this.flags; + return list.filter((x) => flags.indexOf(x) !== -1); +} + +/** + * Checks whether a relevant flag is set. If the flag is deemed + * irrelevant, then the flag is considered to be unset. + * + * It is generally better to use this helper than accessing flags + * directly, because some flags may be set and yet be irrelevant due + * to the settings used when rendering with the theme. + * + * @param name The name of the flag to check. + * + * @returns Whether the flag is set. + */ +export function hasRelevantFlag(name: string, options: any): boolean { + return relevantFlags.call(this, options).indexOf(name) !== -1; +} diff --git a/src/default/partials/flag.hbs b/src/default/partials/flag.hbs new file mode 100644 index 00000000..576367b1 --- /dev/null +++ b/src/default/partials/flag.hbs @@ -0,0 +1 @@ +{{#if useForName}}{{useForName}}{{else}}{{this}}{{/if}} diff --git a/src/default/partials/header.hbs b/src/default/partials/header.hbs index 102d966f..b486067e 100644 --- a/src/default/partials/header.hbs +++ b/src/default/partials/header.hbs @@ -55,17 +55,20 @@ {{#with model}}{{> breadcrumb}}{{/with}}

{{#compact}} - {{model.kindString}}  - {{model.name}} - {{#if model.typeParameters}} - < - {{#each model.typeParameters}} - {{#if @index}}, {{/if}} - {{name}} - {{/each}} - > - {{/if}} + {{#with model}} + {{#if (hasRelevantFlag "Export")}}{{> flag useForClass="Export" useForName="Export"}} {{/if}} + {{kindString}}  + {{name}} + {{#if typeParameters}} + < + {{#each typeParameters}} + {{#if @index}}, {{/if}} + {{name}} + {{/each}} + > + {{/if}} + {{/with}} {{/compact}}

- \ No newline at end of file + diff --git a/src/default/partials/index.hbs b/src/default/partials/index.hbs index 05d199d6..cd5ba7d8 100644 --- a/src/default/partials/index.hbs +++ b/src/default/partials/index.hbs @@ -1,6 +1,10 @@ {{#if groups}}
-

Index

+ {{#if settings.excludeNotExported}} +

Index of Exported Symbols

+ {{else}} +

Index

+ {{/if}}
{{#each groups}} @@ -10,7 +14,7 @@

{{#if title}}{{title}} {{/if}}{{../title}}

{{/each}} @@ -18,7 +22,7 @@

{{title}}

{{/if}} @@ -27,4 +31,4 @@
-{{/if}} \ No newline at end of file +{{/if}} diff --git a/src/default/partials/member.hbs b/src/default/partials/member.hbs index 01c59e81..de32b931 100644 --- a/src/default/partials/member.hbs +++ b/src/default/partials/member.hbs @@ -1,7 +1,7 @@
{{#if name}} -

{{#each flags}}{{this}} {{/each}}{{{wbr name}}}

+

{{#compact}}{{#each (relevantFlags)}}{{> flag}} {{/each}}{{/compact}}{{{wbr name}}}

{{/if}} {{#if signatures}} diff --git a/src/default/partials/member.signature.body.hbs b/src/default/partials/member.signature.body.hbs index fdde257d..9bd47ef2 100644 --- a/src/default/partials/member.signature.body.hbs +++ b/src/default/partials/member.signature.body.hbs @@ -15,9 +15,7 @@ {{#each parameters}}
  • {{#compact}} - {{#each flags}} - {{this}}  - {{/each}} + {{#each (relevantFlags)}}{{> flag}} {{/each}} {{#if flags.isRest}}...{{/if}} {{name}}:  {{#with type}}{{>type}}{{/with}} @@ -53,4 +51,4 @@ {{> parameter}} {{/with}} {{/if}} -{{/if}} \ No newline at end of file +{{/if}} diff --git a/src/default/partials/parameter.hbs b/src/default/partials/parameter.hbs index eb06dc07..7a3a284c 100644 --- a/src/default/partials/parameter.hbs +++ b/src/default/partials/parameter.hbs @@ -52,9 +52,7 @@ {{> member.signatures}} {{else}}
    {{#compact}} - {{#each flags}} - {{this}}  - {{/each}} + {{#each (relevantFlags)}}{{> flag}} {{/each}} {{#if flags.isRest}}...{{/if}} {{{wbr name}}} From 7bbf73e973b4712749dbf0c7901740ba276a6367 Mon Sep 17 00:00:00 2001 From: Louis-Dominique Dubeau Date: Tue, 1 May 2018 18:43:01 -0400 Subject: [PATCH 2/5] Deal with symbol renames. --- src/default/helpers/get-reflection.ts | 13 +++ src/default/partials/member.hbs | 14 +-- src/default/templates/reflection.hbs | 144 +++++++++++++------------- 3 files changed, 94 insertions(+), 77 deletions(-) create mode 100644 src/default/helpers/get-reflection.ts diff --git a/src/default/helpers/get-reflection.ts b/src/default/helpers/get-reflection.ts new file mode 100644 index 00000000..4662c013 --- /dev/null +++ b/src/default/helpers/get-reflection.ts @@ -0,0 +1,13 @@ +/** + * Get a reflection object form a reflection id. + * + * @returns The filtered array. + */ +export function getReflection(id: number, options: any): any { + const refl = options.data.root.project.reflections[id]; + if (!refl) { + throw new Error(`cannot find reflection with id ${id}`); + } + + return refl; +} diff --git a/src/default/partials/member.hbs b/src/default/partials/member.hbs index de32b931..7a0be1bf 100644 --- a/src/default/partials/member.hbs +++ b/src/default/partials/member.hbs @@ -1,9 +1,9 @@
    - - {{#if name}} -

    {{#compact}}{{#each (relevantFlags)}}{{> flag}} {{/each}}{{/compact}}{{{wbr name}}}

    - {{/if}} - + +

    {{#compact}}{{#each (relevantFlags)}}{{> flag}} {{/each}}{{/compact}}{{{wbr name}}}

    + {{#if renames}} + Renames {{#with (getReflection renames)}}{{{wbr name}}}{{/with}} + {{else}} {{#if signatures}} {{> member.signatures}} {{else}}{{#if hasGetterOrSetter}} @@ -11,12 +11,12 @@ {{else}} {{> member.declaration}} {{/if}}{{/if}} - - {{#each groups}} + {{#each groups}} {{#each children}} {{#unless hasOwnDocument}} {{> member}} {{/unless}} {{/each}} {{/each}} + {{/if}}
    diff --git a/src/default/templates/reflection.hbs b/src/default/templates/reflection.hbs index cdfd9c1e..6f0d733c 100644 --- a/src/default/templates/reflection.hbs +++ b/src/default/templates/reflection.hbs @@ -1,79 +1,83 @@ -{{#with model}} - {{#if hasComment}} -
    - {{> comment}} -
    - {{/if}} -{{/with}} +{{#if model.renames}} + Renames {{#with (getReflection model.renames)}}{{{wbr name}}}{{/with}} +{{else}} + {{#with model}} + {{#if hasComment}} +
    + {{> comment}} +
    + {{/if}} + {{/with}} -{{#if model.typeParameters}} -
    -

    Type parameters

    - {{#with model}}{{> typeParameters}}{{/with}} -
    -{{/if}} + {{#if model.typeParameters}} +
    +

    Type parameters

    + {{#with model}}{{> typeParameters}}{{/with}} +
    + {{/if}} -{{#if model.typeHierarchy}} -
    -

    Hierarchy

    - {{#with model.typeHierarchy}}{{> hierarchy}}{{/with}} -
    -{{/if}} + {{#if model.typeHierarchy}} +
    +

    Hierarchy

    + {{#with model.typeHierarchy}}{{> hierarchy}}{{/with}} +
    + {{/if}} -{{#if model.implementedTypes}} -
    -

    Implements

    -
      - {{#each model.implementedTypes}} -
    • {{> type}}
      • - {{/each}} -
    -
    -{{/if}} + {{#if model.implementedTypes}} +
    +

    Implements

    +
      + {{#each model.implementedTypes}} +
    • {{> type}}
      • + {{/each}} +
    +
    + {{/if}} -{{#if model.implementedBy}} -
    -

    Implemented by

    -
      - {{#each model.implementedBy}} -
    • {{> type}}
      • - {{/each}} -
    -
    -{{/if}} + {{#if model.implementedBy}} +
    +

    Implemented by

    +
      + {{#each model.implementedBy}} +
    • {{> type}}
      • + {{/each}} +
    +
    + {{/if}} -{{#if model.signatures}} -
    -

    Callable

    - {{#with model}}{{> member.signatures}}{{/with}} -
    -{{/if}} + {{#if model.signatures}} +
    +

    Callable

    + {{#with model}}{{> member.signatures}}{{/with}} +
    + {{/if}} -{{#if model.indexSignature}} -
    -

    Indexable

    -
    {{#compact}} - [ - {{#each model.indexSignature.parameters}} - {{name}}: {{#with type}}{{>type}}{{/with}} - {{/each}} - ]:  - {{#with model.indexSignature.type}}{{>type}}{{/with}} - {{/compact}}
    + {{#if model.indexSignature}} +
    +

    Indexable

    +
    {{#compact}} + [ + {{#each model.indexSignature.parameters}} + {{name}}: {{#with type}}{{>type}}{{/with}} + {{/each}} + ]:  + {{#with model.indexSignature.type}}{{>type}}{{/with}} + {{/compact}}
    - {{#with model.indexSignature}} - {{> comment}} - {{/with}} + {{#with model.indexSignature}} + {{> comment}} + {{/with}} - {{#if model.indexSignature.type.declaration}} - {{#with model.indexSignature.type.declaration}} - {{> parameter}} - {{/with}} - {{/if}} -
    -{{/if}} + {{#if model.indexSignature.type.declaration}} + {{#with model.indexSignature.type.declaration}} + {{> parameter}} + {{/with}} + {{/if}} +
    + {{/if}} -{{#with model}} - {{> index}} - {{> members}} -{{/with}} \ No newline at end of file + {{#with model}} + {{> index}} + {{> members}} + {{/with}} +{{/if}} From b99df4c031bf95bc347566c5c75c17318c10c465 Mon Sep 17 00:00:00 2001 From: Louis-Dominique Dubeau Date: Thu, 4 Apr 2019 13:33:45 -0400 Subject: [PATCH 3/5] Split out the part of the tsconfig that will be shared. --- tsconfig-common.json | 11 +++++++++++ tsconfig.json | 12 +++--------- 2 files changed, 14 insertions(+), 9 deletions(-) create mode 100644 tsconfig-common.json diff --git a/tsconfig-common.json b/tsconfig-common.json new file mode 100644 index 00000000..4e7402da --- /dev/null +++ b/tsconfig-common.json @@ -0,0 +1,11 @@ +{ + "compilerOptions": { + "target": "es5", + "module": "amd", + "declaration": false, + "skipLibCheck": true, + "allowJs": true, + "strict": true, + "esModuleInterop": true + } +} diff --git a/tsconfig.json b/tsconfig.json index 8a6f9e96..3daf0c46 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,16 +1,10 @@ { + "extends": "./tsconfig-common.json", "include": [ "src/default/assets/js/src/**/*.ts", "src/default/assets/js/src/~bootstrap.ts" ], "compilerOptions": { - "target": "es5", - "module": "amd", - "declaration": false, - "skipLibCheck": true, - "allowJs": true, - "outFile": "./src/default/assets/js/main.js", - "strict": true, - "esModuleInterop": true + "outFile": "./src/default/assets/js/main.js" } -} \ No newline at end of file +} From 7f9ba6e79d228d6f1bd55210a66d56d1b4d38ebf Mon Sep 17 00:00:00 2001 From: Louis-Dominique Dubeau Date: Thu, 4 Apr 2019 13:34:09 -0400 Subject: [PATCH 4/5] Move the tsc configuration options for helpers to an external file. --- gruntfile.js | 10 +--------- src/default/helpers/tsconfig.json | 12 ++++++++++++ 2 files changed, 13 insertions(+), 9 deletions(-) create mode 100644 src/default/helpers/tsconfig.json diff --git a/gruntfile.js b/gruntfile.js index aa4088b5..357b212a 100644 --- a/gruntfile.js +++ b/gruntfile.js @@ -7,15 +7,7 @@ module.exports = function(grunt) tsconfig: './tsconfig.json' }, themeDefaultHelpers: { - options: { - sourceMap: false, - module: 'commonjs', - declaration: false - }, - src: [ - 'src/default/helpers/*.ts', - ], - outDir: 'bin/default/helpers' + tsconfig: 'src/default/helpers/tsconfig.json' }, }, uglify: { diff --git a/src/default/helpers/tsconfig.json b/src/default/helpers/tsconfig.json new file mode 100644 index 00000000..c1df6283 --- /dev/null +++ b/src/default/helpers/tsconfig.json @@ -0,0 +1,12 @@ +{ + "extends": "../../../tsconfig-common", + "compilerOptions": { + "sourceMap": false, + "module": "commonjs", + "declaration": false, + "outDir": "../../../bin/default/helpers" + }, + "include": [ + "*.ts" + ] +} From 3b5d22d3e284d1f275d7a4dd9cd8426d394d9817 Mon Sep 17 00:00:00 2001 From: Louis-Dominique Dubeau Date: Thu, 4 Apr 2019 13:34:26 -0400 Subject: [PATCH 5/5] Fix a few compilation errors happening post-rebase. --- src/default/helpers/relevant-flags.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/default/helpers/relevant-flags.ts b/src/default/helpers/relevant-flags.ts index d076eccd..671ac7c0 100644 --- a/src/default/helpers/relevant-flags.ts +++ b/src/default/helpers/relevant-flags.ts @@ -32,7 +32,7 @@ const relevantFlagListWithExport = * * @returns The filtered array. */ -export function relevantFlags(options: any): string[] { +export function relevantFlags(this: any, options: any): string[] { // When excludeNotExported is set, we don't want to produce labels // for "Exported" because everything is exported and thus the @@ -60,6 +60,7 @@ export function relevantFlags(options: any): string[] { * * @returns Whether the flag is set. */ -export function hasRelevantFlag(name: string, options: any): boolean { +export function hasRelevantFlag(this: any, name: string, + options: any): boolean { return relevantFlags.call(this, options).indexOf(name) !== -1; }