Merge pull request #83 from webcomponents-preview/feature/nested-nav-groups

Feature/nested nav groups

Author: davidenke

custom-elements-manifest.config.ts

@@ -9,7 +9,7 @@ import { customElementGroupingPlugin } from '@webcomponents-preview/cem-plugin-g
 export default {
   packagejson: true,
   litelement: true,
-  globs: ['src/components/**/*.{component,plugin}.ts', 'src/components/**/EXAMPLES.md'],
+  globs: ['src/**/*.{component,plugin}.ts', 'src/**/EXAMPLES.md'],
   outdir: 'dist',
   plugins: [
     customElementExamplesPlugin(),
@@ -23,8 +23,11 @@ export default {
     }),
     customElementGroupingPlugin({
       addGroups(componentPath) {
-        const [, , group] = componentPath?.split('/') || [];
-        return [group];
+        const path = componentPath?.split('/') || [];
+        const [, type, category, sub] = path;
+        const group = `${type}/${category}`;
+
+        return path.length > 5 ? [`${group}/${sub}`] : [group];
       },
     }),
   ],

scripts/separate-examples.ts

@@ -0,0 +1,84 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname } from 'node:path';
+import { cwd } from 'node:process';
+import { parseArgs } from 'node:util';
+
+import glob from 'fast-glob';
+import prettier from 'prettier';
+
+/**
+ * Finds all examples in the component files and extracts them to a separate markdown file.
+ * A markdown file named `EXAMPLES.md` is created for each component in the same directory
+ * as the component file if examples have been found. Found examples will be removed from the
+ * component files after extraction.
+ *
+ * For now, only one positional argument is supported, which is the glob pattern to match
+ * the component files to look up. Any valid glob pattern of `fast-glob` is supported.
+ * This script is meant to be run manually, see usage below.
+ *
+ * @usage node --loader ts-node/esm --no-warnings scripts/separate-examples.ts src/{components,plugins}/**\/*.ts
+ * @link https://github.com/mrmlnc/fast-glob?tab=readme-ov-file#pattern-syntax
+ */
+
+// todo expose options as cli arguments
+const examplesFileName = 'EXAMPLES.md';
+const removeFromComponent = true;
+const skipEmpty = true;
+const silent = false;
+
+const { positionals: paths } = parseArgs({ allowPositionals: true });
+const componentPaths = await glob(paths, { cwd: cwd(), absolute: true, onlyFiles: true });
+
+componentPaths.forEach(async (componentPath) => {
+  const componentName = basename(componentPath);
+  const content = await readFile(componentPath, 'utf-8');
+  const matchAnyAnnotation = /\*\s+@(\w+)\s*\n*/;
+  const matchExampleAnnotation = /\*\s+@example\s*\n*/;
+  const matchJsDocEnd = /\*\//;
+  const matchAnything = /[\s\S]*/;
+
+  // prepare match for examples
+  const matchExamples = new RegExp(
+    `(?<=${matchExampleAnnotation.source})(${matchAnything.source}?)(?:(?=${matchJsDocEnd.source})|(?=${matchAnyAnnotation.source}))`,
+    'g',
+  );
+  const examples = Array
+    // find all examples
+    .from(content.matchAll(matchExamples))
+    // remove leading asterisks and trim
+    .map(([, match]) => match.replace(/^\s*\*\s/gm, '').trim());
+
+  // skip if no examples found
+  if (skipEmpty && !examples.length) {
+    if (!silent) console.info(`No examples found in ${componentName}`);
+    return;
+  }
+
+  // write examples to markdown file
+  const componentDir = dirname(componentPath);
+  const examplesPath = `${componentDir}/${examplesFileName}`;
+
+  // store prettified and joined examples
+  let examplesContent = examples.join('\n\n\n');
+  examplesContent = await prettier.format(examplesContent, { filepath: examplesPath });
+  await writeFile(examplesPath, examplesContent, 'utf-8');
+
+  if (removeFromComponent) {
+    // remove found examples from component file
+    const replaceExamples = new RegExp(
+      `(${matchExampleAnnotation.source}(${matchAnything.source}?))(?:(?=${matchJsDocEnd.source})|(?=${matchAnyAnnotation.source}))`,
+      'g',
+    );
+    const cleanedContent = content
+      // remove the examples
+      .replace(replaceExamples, '')
+      // remove now eventually empty block comment
+      .replace(/^\/\*\*\s*\n\s*\*\/\s*\n/m, '');
+    await writeFile(componentPath, cleanedContent, 'utf-8');
+  }
+
+  // notify
+  if (!silent) {
+    console.info(`Separated ${examples.length} example${examples.length > 1 ? 's' : ''} from ${componentName}`);
+  }
+});

src/components/features/markdown-example/EXAMPLES.md

@@ -0,0 +1,14 @@
+### Shows arbitrary HTML code example
+
+```html
+<wcp-markdown-example>
+  <pre slot="code">
+&lt;h1&gt;Readme&lt;/h1&gt;
+&lt;p&gt;Some readme content&lt;/p&gt;
+  </pre>
+  <div slot="preview">
+    <h1>Readme</h1>
+    <p>Some readme content</p>
+  </div>
+</wcp-markdown-example>
+```

src/components/features/markdown-example/README.md

@@ -11,23 +11,6 @@ or the enhanced markdown renderer which instruments this element under the hood.
 
 **Mixins:** ColorSchemable
 
-## Example
-
-### Shows arbitrary HTML code example
-
-```html
-<wcp-markdown-example>
-  <pre slot="code">
-&lt;h1&gt;Readme&lt;/h1&gt;
-&lt;p&gt;Some readme content&lt;/p&gt;
-  </pre>
-  <div slot="preview">
-    <h1>Readme</h1>
-    <p>Some readme content</p>
-  </div>
-</wcp-markdown-example>
-```
-
 ## Slots
 
 | Name      | Description              |

src/components/features/markdown-example/markdown-example.component.ts

@@ -18,22 +18,6 @@ const MARKDOWN_EXAMPLE_TABS = { preview: { label: 'Preview' }, code: { label: 'C
  * or the enhanced markdown renderer which instruments this element under the hood. It can be used with the
  * `renderMarkdown` function provided by the `@/utils/markdown.utils`.
  *
- * @example
- * ### Shows arbitrary HTML code example
- *
- * ```html
- * <wcp-markdown-example>
- *   <pre slot="code">
- * &lt;h1&gt;Readme&lt;/h1&gt;
- * &lt;p&gt;Some readme content&lt;/p&gt;
- *   </pre>
- *   <div slot="preview">
- *     <h1>Readme</h1>
- *     <p>Some readme content</p>
- *   </div>
- * </wcp-markdown-example>
- * ```
- *
  * @slot code - Code example
  * @slot preview - Rendered example preview
  *

src/components/features/navigation/README.md

@@ -0,0 +1,13 @@
+### Non-interactive
+
+This will probably only be used for the active item.
+
+```html
+<wcp-navigation-item> Non-interactive </wcp-navigation-item>
+```
+
+### With link
+
+```html
+<wcp-navigation-item href="/home"> Home </wcp-navigation-item>
+```

src/components/features/navigation/navigation-item/EXAMPLES.md

@@ -4,26 +4,6 @@
 
 **Mixins:** ColorSchemable
 
-## Examples
-
-### Non-interactive
-
-This will probably only be used for the active item.
-
-```html
-<wcp-navigation-item>
-  Non-interactive
-</wcp-navigation-item>
-```
-
-### With link
-
-```html
-<wcp-navigation-item href="/home">
-  Home
-</wcp-navigation-item>
-```
-
 ## Properties
 
 | Property | Attribute | Type                  | Default |

src/components/features/navigation/navigation-item/README.md

@@ -45,15 +45,33 @@
   }
 }
 
-a,
 span {
   display: block;
   padding: var(---wcp-navigation-item-spacing);
 
+  overflow: hidden;
   text-decoration: none;
   text-overflow: ellipsis;
   white-space: nowrap;
 
   background-color: var(---wcp-navigation-item-background);
   color: var(---wcp-navigation-item-color);
 }
+
+// as the surrounding navigation element might be inset, we add the background
+// in front to fill the whole navigation width to increase the clickable area
+a {
+  position: relative;
+  color: inherit;
+  text-decoration: none;
+
+  &::before {
+    content: '';
+
+    position: absolute;
+    inset: 0 100% 0 auto;
+    width: calc(var(---wcp-aside-max-width, 100vw) - 100%);
+
+    background-color: var(---wcp-navigation-item-background);
+  }
+}

src/components/features/navigation/navigation-item/navigation-item.component.scss

@@ -8,28 +8,6 @@ import { ColorSchemable } from '@/mixins/color-schemable.mixin.js';
 import styles from './navigation-item.component.scss';
 
 /**
- * @element wcp-navigation-item
- *
- * @example
- * ### Non-interactive
- *
- * This will probably only be used for the active item.
- *
- * ```html
- * <wcp-navigation-item>
- *   Non-interactive
- * </wcp-navigation-item>
- * ```
- *
- * @example
- * ### With link
- *
- * ```html
- * <wcp-navigation-item href="/home">
- *   Home
- * </wcp-navigation-item>
- * ```
- *
  * @slot - Default slot for contents
  *
  * @cssprop --wcp-navigation-item-spacing - Inner padding of the item
@@ -64,7 +42,11 @@ export class NavigationItem extends ColorSchemable(LitElement) {
     return html`
       ${when(
         this.href !== undefined,
-        () => html`<a href="${ifDefined(this.href)}"><slot></slot></a>`,
+        () => html`
+          <a href="${ifDefined(this.href)}">
+            <span><slot></slot></span>
+          </a>
+        `,
         () => html`<span><slot></slot></span>`,
       )}
     `;