@limetech/kompendium 1.1.1

package/dist/typedoc.ts

@@ -0,0 +1,665 @@
+import {
+    Application,
+    Reflection,
+    ReflectionKind,
+    DeclarationReflection,
+    TypeDocOptions,
+    CommentTag,
+    TypeDocReader,
+    TSConfigReader,
+} from 'typedoc';
+import { JsonDocsTag, JsonDocsProp } from '@stencil/core/internal';
+import {
+    InterfaceDescription,
+    AliasDescription,
+    EnumDescription,
+    EnumMember,
+    TypeDescription,
+    MethodDescription,
+    ParameterDescription,
+    ClassDescription,
+    DecoratorDescription,
+} from '../types';
+import { existsSync, readFileSync } from 'fs';
+import ts from 'typescript';
+
+export function parseFile(
+    filename: string,
+    tsconfig?: string,
+): TypeDescription[] {
+    if (!existsSync(filename)) {
+        // eslint-disable-next-line no-console
+        console.warn('typeRoot file does not exist', filename);
+
+        return [];
+    }
+
+    const app = new Application();
+
+    // Use current working directory as TypeDoc's base path for clean relative paths
+    const projectRoot = process.cwd();
+
+    const options: Partial<TypeDocOptions> = {
+        entryPoints: [filename],
+        skipErrorChecking: true,
+        basePath: projectRoot,
+    };
+
+    if (tsconfig) {
+        options.tsconfig = tsconfig;
+    }
+
+    if (filename.endsWith('.d.ts')) {
+        options.exclude = ['**/+(*test*|node_modules)/**'];
+    }
+
+    app.options.addReader(new TypeDocReader());
+    app.options.addReader(new TSConfigReader());
+    app.bootstrap(options);
+
+    const project = app.convert();
+    if (!project) {
+        // eslint-disable-next-line no-console
+        console.warn('Could not find any type information');
+
+        return [];
+    }
+
+    const data: TypeDescription[] = [];
+
+    const allInterfaces = project.getReflectionsByKind(
+        ReflectionKind.Interface,
+    );
+    const allClasses = project.getReflectionsByKind(ReflectionKind.Class);
+    const allTypeAliases = project.getReflectionsByKind(
+        ReflectionKind.TypeAlias,
+    );
+    const allEnums = project.getReflectionsByKind(ReflectionKind.Enum);
+
+    const interfaces = allInterfaces.filter((r) =>
+        shouldIncludeType(r as DeclarationReflection),
+    );
+    const classes = allClasses.filter((r) =>
+        shouldIncludeType(r as DeclarationReflection),
+    );
+    const typeAliases = allTypeAliases.filter((r) =>
+        shouldIncludeType(r as DeclarationReflection),
+    );
+    const enums = allEnums.filter((r) =>
+        shouldIncludeType(r as DeclarationReflection),
+    );
+
+    interfaces.forEach((reflection) =>
+        addInterface(reflection as DeclarationReflection, data as any),
+    );
+    classes.forEach((reflection) =>
+        addClass(reflection as DeclarationReflection, data as any),
+    );
+    typeAliases.forEach((reflection) =>
+        addType(reflection as DeclarationReflection, data as any),
+    );
+    enums.forEach((reflection) => {
+        const members: EnumMember[] = [];
+        const enumReflection = reflection as DeclarationReflection;
+        enumReflection.children?.forEach((child) => {
+            if (child.kind === ReflectionKind.EnumMember) {
+                addEnumMember(child, members);
+            }
+        });
+        data.push({
+            type: 'enum',
+            name: enumReflection.name,
+            docs: getDocs(enumReflection),
+            docsTags: getDocsTags(enumReflection),
+            members: members,
+            sources: getSources(enumReflection),
+        } as EnumDescription);
+    });
+
+    return data;
+}
+
+/**
+ * Determines if a type should be included in the documentation based on its source location
+ * and documentation tags.
+ *
+ * Excludes types from:
+ * - node_modules (third-party dependencies)
+ * - examples directories
+ * - test files (.test., .spec., /test/, /tests/)
+ * - Types marked with @private or @internal tags
+ * - Stencil auto-generated types (components.d.ts, Components namespace, CustomEvent wrappers)
+ * @param {DeclarationReflection} reflection - The TypeDoc reflection to check
+ * @returns {boolean} true if the type should be documented, false otherwise
+ */
+function shouldIncludeType(reflection: DeclarationReflection): boolean {
+    if (!reflection.sources || reflection.sources.length === 0) {
+        // No source information - include by default
+        return true;
+    }
+
+    for (const source of reflection.sources) {
+        const sourcePath = source.fullFileName || source.fileName || '';
+
+        if (shouldExcludeSource(sourcePath)) {
+            return false;
+        }
+    }
+
+    // Exclude CustomEvent wrapper types
+    // These are generic wrappers around CustomEvent<T> that don't add useful
+    // documentation
+    if (reflection.name.endsWith('CustomEvent')) {
+        return false;
+    }
+
+    // Exclude HTML element interface types
+    // These are DOM element interfaces (HTMLLimelButtonElement, etc.) already
+    // documented in the Components section
+    if (
+        reflection.name.startsWith('HTML') &&
+        reflection.name.endsWith('Element')
+    ) {
+        return false;
+    }
+
+    // Exclude types in Stencil's Components namespace
+    // Belt-and-suspenders: catches any component interfaces that were not
+    // excluded based on source location
+    if (isInComponentsNamespace(reflection)) {
+        return false;
+    }
+
+    // Don't include anything marked @private or @internal
+    if (reflection.comment?.blockTags) {
+        const hasPrivateTag = reflection.comment.blockTags.some(
+            (tag: any) => tag.tag === '@private' || tag.tag === '@internal',
+        );
+        if (hasPrivateTag) {
+            return false;
+        }
+    }
+
+    // Include this type
+    return true;
+}
+
+/**
+ * Checks if a source path should be excluded from documentation.
+ * @param {string} sourcePath - The file path to check
+ * @returns {boolean} true if the source should be excluded, false otherwise
+ */
+function shouldExcludeSource(sourcePath: string): boolean {
+    const normalizedPath = sourcePath.replaceAll('\\', '/');
+
+    if (normalizedPath.includes('node_modules/')) {
+        return true;
+    }
+
+    if (
+        normalizedPath.includes('/examples/') ||
+        normalizedPath.includes('/example/')
+    ) {
+        return true;
+    }
+
+    if (
+        normalizedPath.includes('.test.') ||
+        normalizedPath.includes('.spec.')
+    ) {
+        return true;
+    }
+
+    // This file contains component prop interfaces and HTML element types that
+    // are already documented in the Components section
+    return normalizedPath.endsWith('components.d.ts');
+}
+
+/**
+ * Checks if a TypeDoc reflection is defined within Stencil's Components namespace.
+ *
+ * Stencil generates a Components namespace in components.d.ts containing interfaces
+ * for component props. These types are already documented in the Components section
+ * and should not be duplicated in the Types section.
+ * @param {DeclarationReflection} reflection - The TypeDoc reflection to check
+ * @returns {boolean} true if the reflection is in a Components namespace, false otherwise
+ */
+function isInComponentsNamespace(reflection: DeclarationReflection): boolean {
+    let current: Reflection | undefined = reflection.parent;
+    while (current) {
+        if (
+            current.kind === ReflectionKind.Namespace &&
+            current.name === 'Components'
+        ) {
+            return true;
+        }
+
+        current = current.parent;
+    }
+
+    return false;
+}
+
+const fns = {
+    [ReflectionKind.Interface]: addInterface,
+    [ReflectionKind.Class]: addClass,
+    [ReflectionKind.TypeAlias]: addType,
+    [ReflectionKind.Enum]: addEnum,
+    [ReflectionKind.EnumMember]: addEnumMember,
+};
+
+const traverseCallback = (data: any) => (reflection: Reflection) => {
+    const fn = fns[reflection.kind];
+    if (fn) {
+        fn(reflection, data);
+    } else {
+        reflection.traverse(traverseCallback(data));
+    }
+};
+
+function addInterface(
+    reflection: DeclarationReflection,
+    data: InterfaceDescription[],
+) {
+    data.push({
+        type: 'interface',
+        name: reflection.name,
+        typeParams: getTypeParams(reflection),
+        docs: getDocs(reflection),
+        docsTags: getDocsTags(reflection),
+        props: reflection.children?.filter(isProperty).map(getProperty) || [],
+        methods: reflection.children?.filter(isMethod).map(getMethod) || [],
+        sources: getSources(reflection),
+    });
+}
+
+function addClass(reflection: DeclarationReflection, data: ClassDescription[]) {
+    const decorators = getDecorators(reflection);
+
+    const implementedInterfaces = getImplementedInterfaces(reflection);
+
+    data.push({
+        type: 'class',
+        name: reflection.name,
+        typeParams: getTypeParams(reflection),
+        docs: getDocs(reflection),
+        docsTags: getDocsTags(reflection),
+        props:
+            reflection.children
+                ?.filter(isProperty)
+                .map((prop) =>
+                    getPropertyWithInheritDoc(prop, implementedInterfaces),
+                ) || [],
+        methods:
+            reflection.children
+                ?.filter(isMethod)
+                .map((method) =>
+                    getMethodWithInheritDoc(method, implementedInterfaces),
+                ) || [],
+        sources: getSources(reflection),
+        decorators: decorators,
+    });
+}
+
+function addType(reflection: DeclarationReflection, data: AliasDescription[]) {
+    data.push({
+        type: 'alias',
+        name: reflection.name,
+        docs: getDocs(reflection),
+        docsTags: getDocsTags(reflection),
+        alias: reflection.type.toString(),
+        sources: getSources(reflection),
+    });
+}
+
+function addEnum(reflection: DeclarationReflection, data: EnumDescription[]) {
+    const members = [];
+    reflection.traverse(traverseCallback(members));
+
+    data.push({
+        type: 'enum',
+        name: reflection.name,
+        docs: getDocs(reflection),
+        docsTags: getDocsTags(reflection),
+        members: members,
+        sources: getSources(reflection),
+    });
+}
+
+function addEnumMember(reflection: DeclarationReflection, data: EnumMember[]) {
+    let value: string;
+    if (reflection.type && (reflection.type as any).type === 'literal') {
+        const literalValue = (reflection.type as any).value;
+        if (typeof literalValue === 'string') {
+            value = `"${literalValue}"`;
+        } else {
+            value = String(literalValue);
+        }
+    } else {
+        value = reflection.defaultValue;
+    }
+
+    data.push({
+        name: reflection.name,
+        docs: getDocs(reflection),
+        docsTags: getDocsTags(reflection),
+        value: value,
+    });
+}
+
+function getDocs(reflection: Reflection): string {
+    if (!reflection.comment) {
+        return '';
+    }
+
+    const text =
+        reflection.comment.summary
+            ?.map((part: any) => part.text)
+            .join('')
+            .trim() || '';
+
+    // Normalize multiple newlines to single newlines
+    return text.replaceAll(/\n\n+/g, '\n');
+}
+
+function getDocsTags(reflection: DeclarationReflection) {
+    return reflection.comment?.blockTags?.map(getTag) || [];
+}
+
+function getTag(tag: CommentTag): JsonDocsTag {
+    // tag already has @ prefix, so remove it
+    const tagName = (tag.tag as string).replace(/^@+/, '');
+
+    return {
+        name: tagName,
+        text:
+            tag.content
+                ?.map((part: any) => part.text)
+                .join('')
+                .trim() || '',
+    };
+}
+
+function isProperty(reflection: DeclarationReflection): boolean {
+    if (reflection.kind !== ReflectionKind.Property) {
+        return false;
+    }
+
+    const type = reflection.type as any;
+
+    return !(type?.type === 'reflection' && type.declaration?.signatures);
+}
+
+function isMethod(reflection: DeclarationReflection): boolean {
+    if (reflection.kind !== ReflectionKind.Property) {
+        return false;
+    }
+
+    const type = reflection.type as any;
+
+    return type?.type === 'reflection' && type.declaration?.signatures;
+}
+
+function getProperty(reflection: DeclarationReflection): Partial<JsonDocsProp> {
+    return {
+        name: reflection.name,
+        type: reflection.type.toString(),
+        docs: getDocs(reflection),
+        docsTags: getDocsTags(reflection),
+        default: reflection.defaultValue,
+        optional: reflection.flags.isOptional,
+    };
+}
+
+function getMethod(reflection: DeclarationReflection): MethodDescription {
+    const type = reflection.type as any;
+    const signature = type?.declaration?.signatures?.[0];
+
+    if (!signature) {
+        return {
+            name: reflection.name,
+            docs: getDocs(reflection),
+            docsTags: [],
+            parameters: [],
+            returns: { type: 'void', docs: '' },
+        };
+    }
+
+    let docs =
+        signature.comment?.summary
+            ?.map((part: any) => part.text)
+            .join('')
+            .trim() || '';
+    // Normalize multiple newlines to single newlines
+    docs = docs.replaceAll(/\n\n+/g, '\n');
+
+    const parameters: ParameterDescription[] =
+        signature.parameters?.map((param: any) => ({
+            name: param.name,
+            type: param.type?.toString() || 'any',
+            docs:
+                param.comment?.summary
+                    ?.map((part: any) => part.text)
+                    .join('')
+                    .trim() || '',
+            default: param.defaultValue,
+            optional: param.flags?.isOptional || false,
+        })) || [];
+
+    const returnsTag = signature.comment?.blockTags?.find(
+        (tag: any) => tag.tag === '@returns',
+    );
+    const returnsText =
+        returnsTag?.content
+            ?.map((part: any) => part.text)
+            .join('')
+            .trim() || '';
+
+    const returns = {
+        type: signature.type?.toString() || 'void',
+        docs: returnsText,
+    };
+
+    const docsTags =
+        signature.comment?.blockTags
+            ?.filter(
+                (tag: any) => tag.tag !== '@param' && tag.tag !== '@returns',
+            )
+            .map(getTag) || [];
+
+    return {
+        name: reflection.name,
+        docs: docs,
+        docsTags: docsTags,
+        parameters: parameters,
+        returns: returns,
+    };
+}
+
+function getImplementedInterfaces(
+    reflection: DeclarationReflection,
+): DeclarationReflection[] {
+    const interfaces: DeclarationReflection[] = [];
+
+    const implemented = (reflection as any).implementedTypes;
+    if (implemented) {
+        implemented.forEach((type: any) => {
+            if (type.reflection) {
+                interfaces.push(type.reflection);
+            }
+        });
+    }
+
+    return interfaces;
+}
+
+function getPropertyWithInheritDoc(
+    reflection: DeclarationReflection,
+    interfaces: DeclarationReflection[],
+): Partial<JsonDocsProp> {
+    const prop = getProperty(reflection);
+
+    const hasInheritDoc = reflection.comment?.blockTags?.some(
+        (tag: any) => tag.tag.toLowerCase() === '@inheritdoc',
+    );
+
+    if (hasInheritDoc && interfaces.length > 0) {
+        // Try to find the property in implemented interfaces
+        for (const iface of interfaces) {
+            const interfaceProp = iface.children?.find(
+                (child) => child.name === reflection.name,
+            );
+            if (interfaceProp) {
+                return {
+                    ...prop,
+                    docs: getDocs(interfaceProp),
+                    docsTags: getDocsTags(interfaceProp),
+                };
+            }
+        }
+    }
+
+    return prop;
+}
+
+function getMethodWithInheritDoc(
+    reflection: DeclarationReflection,
+    interfaces: DeclarationReflection[],
+): MethodDescription {
+    const type = reflection.type as any;
+    const signature = type?.declaration?.signatures?.[0];
+    const hasInheritDoc = signature?.comment?.blockTags?.some(
+        (tag: any) => tag.tag.toLowerCase() === '@inheritdoc',
+    );
+
+    if (hasInheritDoc && interfaces.length > 0) {
+        for (const iface of interfaces) {
+            const interfaceMethod = iface.children?.find(
+                (child) => child.name === reflection.name,
+            );
+            if (interfaceMethod) {
+                return getMethod(interfaceMethod);
+            }
+        }
+    }
+
+    return getMethod(reflection);
+}
+
+/**
+ * Extract decorator information from TypeScript source code using AST parsing
+ *
+ * TypeDoc 0.23 removed the decorators property from DeclarationReflection,
+ * which was present in 0.17. This function works around that limitation by
+ * parsing the original TypeScript source files to extract decorator information.
+ * @param {DeclarationReflection} reflection - The TypeDoc reflection to extract decorators from
+ * @returns {DecoratorDescription[]} Array of decorator descriptions with names and arguments
+ * @remarks
+ * This is a workaround for incomplete TypeDoc 0.23 API. TypeDoc removed
+ * decorator information from their reflection model, but decorators are
+ * essential for documenting Stencil components (e.g., @Component, @Prop).
+ *
+ * Performance considerations:
+ * - Reads and parses source files on demand (I/O + parsing overhead)
+ * - Caches nothing - each call re-parses the file
+ * - For large codebases, consider caching parsed source files
+ *
+ * Known limitations:
+ * - Only extracts class-level decorators, not property/method decorators
+ * - Decorator arguments are captured as raw text, not parsed
+ * - Fails silently if source file is unavailable or parsing fails
+ * - Depends on TypeScript AST structure (may break with TS version changes)
+ * @example
+ * ```typescript
+ * // For a class like:
+ * @Component({ tag: 'my-component' })
+ * class MyComponent { }
+ *
+ * // Returns:
+ * [{
+ *   name: 'Component',
+ *   arguments: { _config: "{ tag: 'my-component' }" }
+ * }]
+ * ```
+ */
+function getDecorators(
+    reflection: DeclarationReflection,
+): DecoratorDescription[] {
+    if (!reflection.sources || reflection.sources.length === 0) {
+        return [];
+    }
+
+    const source = reflection.sources[0];
+    const fileName = source.fullFileName || source.fileName;
+
+    if (!existsSync(fileName)) {
+        return [];
+    }
+
+    try {
+        const sourceFile = ts.createSourceFile(
+            fileName,
+            readFileSync(fileName, 'utf8'),
+            ts.ScriptTarget.Latest,
+            true,
+        );
+
+        let decorators: DecoratorDescription[] = [];
+
+        const visit = (node: ts.Node): void => {
+            if (
+                ts.isClassDeclaration(node) &&
+                node.name?.getText() === reflection.name
+            ) {
+                let nodeDecorators;
+                if (ts.canHaveDecorators(node)) {
+                    nodeDecorators = ts.getDecorators(node);
+                }
+
+                if (nodeDecorators) {
+                    decorators = nodeDecorators.map((decorator: any) => {
+                        const expression = decorator.expression;
+                        let name = '';
+                        let args: any = {};
+
+                        if (ts.isCallExpression(expression)) {
+                            name = expression.expression.getText();
+                            if (expression.arguments.length > 0) {
+                                args = {
+                                    _config: expression.arguments[0].getText(),
+                                };
+                            }
+                        } else {
+                            name = expression.getText();
+                        }
+
+                        return { name: name, arguments: args };
+                    });
+                }
+            }
+
+            ts.forEachChild(node, visit);
+        };
+
+        visit(sourceFile);
+
+        return decorators;
+    } catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn('Failed to parse decorators:', error);
+
+        return [];
+    }
+}
+
+function getTypeParams(reflection: DeclarationReflection) {
+    return (
+        reflection.typeParameters?.map((param) => ({
+            name: param.name,
+        })) || []
+    );
+}
+
+function getSources(reflection: DeclarationReflection) {
+    return reflection.sources?.map((source) => source.fileName) || [];
+}

package/dist/types/components/anchor-scroll.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Utility functions for handling anchor link scrolling in shadow DOM components.
+ */
+/**
+ * Get the current route from the URL hash (without the leading #).
+ *
+ * For hash-based routing where the entire hash is the route.
+ * Example: "#/component/limel-button/examples/" → "/component/limel-button/examples/"
+ * @returns {string} The route extracted from the URL hash
+ */
+export declare function getRoute(): string;
+/**
+ * Extract the anchor ID from the current URL hash.
+ *
+ * Handles both simple anchors (#section) and route-based anchors (#/guide/page#section).
+ * Returns null if no valid anchor is found.
+ *
+ * Example: "#/guide/changelog#v2-features" → "v2-features"
+ * @returns {string | null} The anchor ID or null if not found
+ */
+export declare function getAnchorId(): string | null;
+/**
+ * Scroll to an anchor element within a shadow root.
+ *
+ * Uses requestAnimationFrame to ensure the DOM is ready before scrolling.
+ * @param {ShadowRoot} shadowRoot - The shadow root to search for the element
+ * @param {ScrollBehavior} behavior - Scroll behavior ('auto' or 'smooth')
+ */
+export declare function scrollToAnchor(shadowRoot: ShadowRoot, behavior?: ScrollBehavior): void;
+/**
+ * Scroll to a specific element by ID within a shadow root.
+ * @param {ShadowRoot} shadowRoot - The shadow root to search for the element
+ * @param {string} id - The element ID to scroll to
+ * @param {ScrollBehavior} behavior - Scroll behavior ('auto' or 'smooth')
+ */
+export declare function scrollToElement(shadowRoot: ShadowRoot, id: string, behavior?: ScrollBehavior): void;