Merge pull request #1279 from CleverCloud/storybook/typecheck-related-libs

refactor(storybook): typecheck related libs

Author: florian-sanders-cc

.storybook/preview.js

@@ -2,14 +2,21 @@ import { setCustomElementsManifest } from '@storybook/web-components';
 // Any CSS file import automagically generates a `<link rel="stylesheet" href="bundledCssFile">` in the story iframe
 import 'github-markdown-css/github-markdown.css';
 import 'highlight.js/styles/vs.css';
+// @ts-ignore not worth helping TS understand this is valid since we don't need to type check this module
 // eslint-disable-next-line import/no-unresolved
 import customElementsManifest from '../dist/custom-elements.json';
 import { AutodocsTemplate } from '../src/stories/lib/autodocs-template.jsx';
 import '../src/stories/lib/i18n-control.js';
 import '../src/styles/default-theme.css';
 
+/**
+ * @typedef {import('@storybook/web-components').Preview} Preview
+ * @typedef {import('@storybook/addon-viewport').ViewportMap} ViewportMap
+ */
+
 setCustomElementsManifest(customElementsManifest);
 
+/** @type {Partial<ViewportMap>} */
 const viewports = {};
 Array.from(new Array(10)).map((_, i) => {
   const w = 350 + i * 100;
@@ -29,7 +36,7 @@ const availableLanguages = [
   { value: 'missing', title: '🤬 Missing' },
 ];
 
-/** @type { import('@storybook/web-components').Preview } */
+/** @type {Preview} */
 const preview = {
   parameters: {
     docs: {

cem/generate-cem-vite-plugin.js

@@ -1,3 +1,4 @@
+// @ts-ignore no types available for this dependency
 import { cli } from '@custom-elements-manifest/analyzer/cli.js';
 
 /**

package-lock.json

@@ -94,6 +94,7 @@
     "@storybook/theming": "^8.4.5",
     "@storybook/web-components": "^8.4.5",
     "@storybook/web-components-vite": "^8.4.5",
+    "@types/js-yaml": "^4.0.9",
     "@types/leaflet": "^1.9.12",
     "@types/leaflet.heat": "^0.2.4",
     "@types/statuses": "^2.0.5",

package.json

@@ -4,7 +4,7 @@ export type Translations = { [key: string]: Translation };
 
 export type Translation = string | TranslateFunction;
 
-export type TranslateFunction = (data: { [key: string]: any }) => Translated;
+export type TranslateFunction = (data: any) => Translated;
 
 export type Translated = string | Node;
 

src/lib/i18n/i18n.types.d.ts

@@ -1,3 +1,4 @@
+// @ts-ignore not worth helping TS understand this is valid since we don't need to type check this module
 // eslint-disable-next-line import/no-unresolved
 import customElementsManifest from '../../../dist/custom-elements.json';
 import { setLanguage } from '../../lib/i18n/i18n.js';

src/stories/lib/make-story.js

@@ -1,15 +1,15 @@
 import { readFile } from 'fs/promises';
 import { getMetaDataFromMd } from './markdown-to-csf.js';
 
-/** @type {import ('@storybook/types').Indexer} */
+/** @type {import('storybook/internal/types').Indexer} */
 export const markdownIndexer = {
   test: /.md$/,
   createIndex: async (fileName, { makeTitle }) => {
     const markdownContent = await readFile(fileName, { encoding: 'utf-8' });
 
     const { title, subtitle } = getMetaDataFromMd(markdownContent);
 
-    /** @type {import('@storybook/types').IndexInput} */
+    /** @type {import('storybook/internal/types').IndexInput} */
     const indexInput = {
       type: 'docs',
       importPath: fileName,

src/stories/lib/markdown-indexer.js

@@ -1,11 +1,21 @@
 import { load as yamlLoad } from 'js-yaml';
 import frontmatter from 'remark-frontmatter';
 import remarkGfm from 'remark-gfm';
+// @ts-ignore no types available for this dependency
 import highlight from 'remark-highlight.js';
 import remark2Html from 'remark-html';
 import remarkParse from 'remark-parse';
 import unified from 'unified';
 
+/**
+ * @typedef {import('vite').Plugin} Plugin
+ */
+
+/**
+ * A Vite plugin that transforms markdown files into Component Story Format (CSF).
+ *
+ * @returns {Plugin}
+ */
 export function rollupMdToCsfPlugin() {
   return {
     name: 'markdown-to-csf',
@@ -25,6 +35,13 @@ const processor = unified()
   .use(highlight)
   .use(remark2Html, { sanitize: false });
 
+/**
+ * Converts markdown text into a Component Story Format (CSF) file with embedded documentation.
+ * Processes the markdown into HTML and wraps it in a React component for display in Storybook.
+ *
+ * @param {string} markdownText
+ * @returns {string} the CSF code with the markdown text embedded in a react component
+ */
 export function markdownToCsfWithDocsPage(markdownText) {
   const htmlContent = processor().processSync(markdownText).contents;
   const parsedHTML = JSON.stringify(htmlContent);
@@ -63,11 +80,20 @@ export function markdownToCsfWithDocsPage(markdownText) {
   return csfScript;
 }
 
+/**
+ * Extracts metadata from markdown content, including title and subtitle information
+ * from frontmatter YAML and heading nodes.
+ *
+ * @param {string} markdownContent
+ * @returns {{ title: string, subtitle: string }}
+ */
 export function getMetaDataFromMd(markdownContent) {
   const markdownAst = processor.parse(markdownContent);
 
+  // @ts-ignore the AST is not really typed
   const frontmatterNode = markdownAst.children.find((node) => node.type === 'yaml');
 
+  // @ts-ignore the AST is not really typed
   const headingNode = markdownAst.children.find((node) => node.type === 'heading' && node.depth === 1);
   const kind = getKind(frontmatterNode);
   const subtitle = getSubTitle(frontmatterNode, headingNode);
@@ -76,9 +102,17 @@ export function getMetaDataFromMd(markdownContent) {
   return { title, subtitle };
 }
 
+/**
+ * Extracts the subtitle from either the frontmatter YAML or the first heading.
+ * Falls back to 'Untitled' if neither source contains a title.
+ *
+ * @param {{ value: string }|null} frontmatterNode
+ * @param {{ children: Array<{ value: string }> }} headingNode
+ * @returns {string} the extracted subtitle
+ */
 function getSubTitle(frontmatterNode, headingNode) {
   if (frontmatterNode != null) {
-    const fmObject = yamlLoad(frontmatterNode.value);
+    const fmObject = /** @type {{ title: string|null }} */ (yamlLoad(frontmatterNode.value));
     if (fmObject.title != null) {
       return fmObject.title;
     }
@@ -91,9 +125,16 @@ function getSubTitle(frontmatterNode, headingNode) {
   return 'Untitled';
 }
 
+/**
+ * Extracts the 'kind' metadata from the frontmatter YAML node.
+ * Returns null if there is no kind specified.
+ *
+ * @param {{ value: string }|null} frontmatterNode - The frontmatter node containing YAML content
+ * @returns {string|null} The extracted kind value or null if not found
+ */
 function getKind(frontmatterNode) {
   if (frontmatterNode != null) {
-    const fmObject = yamlLoad(frontmatterNode.value);
+    const fmObject = /** @type {{ kind: string }|null} */ (yamlLoad(frontmatterNode.value));
     if (fmObject.kind != null) {
       return fmObject.kind;
     }

src/stories/lib/markdown-to-csf.js

@@ -1,3 +1,13 @@
+/**
+ * @typedef {import('vite').Plugin} Plugin
+ */
+
+/**
+ * A Vite plugin that injects Clever Cloud Authentication tokens.
+ * !! Caution: NEVER USE THIS PLUGIN FOR THE PROD BUILD !!
+ *
+ * @type {Plugin}
+ */
 export const injectAuthForSmartComponentsPlugin = {
   name: 'inject-auth-for-smart-components',
   async transform(code, id) {

src/stories/lib/smart-auth-plugin.js

@@ -1,3 +1,13 @@
+/**
+ * Formats a story name by applying various transformations:
+ * - Capitalizes the first letter
+ * - Adds spaces before numbers
+ * - Converts CSS to uppercase
+ * - Changes "with" phrases to parenthetical format
+ *
+ * @param {string} rawName - The raw story name to format
+ * @returns {string} The formatted story name
+ */
 function formatStoryName(rawName) {
   return (
     rawName[0].toUpperCase() +
@@ -13,6 +23,21 @@ function formatStoryName(rawName) {
   );
 }
 
+/**
+ * Enhances a story name by adding appropriate emoji prefixes based on the story type/state.
+ * Processes special cases and adds visual indicators for different states:
+ * - ⌛ for loading/waiting/skeleton states
+ * - ➕ for adding states
+ * - 📝 for editing states
+ * - 🗑️ for deleting states
+ * - 🕳 for empty states
+ * - 👍 for loaded states
+ * - 📈 for simulation states
+ * - 🔥 for error states
+ *
+ * @param {string} defaultName - The original story name to enhance
+ * @returns {string} The enhanced story name with appropriate prefix
+ */
 export function enhanceStoryName(defaultName) {
   if (defaultName === 'Default Story') {
     return 'Default';