@jfrader/storybook-docs 0.9.2 → 0.10.0

package/dist/build/props.d.ts

@@ -1,7 +1,11 @@
 import type { ComponentPropsDoc, PropDoc } from '../prop-docs.js';
 export declare function toPropDoc(prop: unknown): PropDoc;
 export declare function createPropsCollector(): {
-    collect: (storyFile: string | undefined, entryName: string, slug: string) => ComponentPropsDoc[];
+    collect: (storyFile: string | undefined, entryName: string, slug: string, bases?: {
+        name: string;
+        slug: string;
+        storyFile: string;
+    }[]) => ComponentPropsDoc[];
     setBuildMode(value: boolean): void;
     clearPrograms(): void;
 };

package/dist/index.js

@@ -13,6 +13,15 @@ import { pages, site as site2, theme } from "virtual:storybook-docs/site";
 import { useEffect as useEffect6, useMemo as useMemo3, useState as useState7 } from "react";
 import { storySource as storySource2 } from "virtual:storybook-docs/catalog";
 
+// src/base.ts
+var STORYBOOK_DOCS_BASE = (() => {
+  const globalBase = globalThis.__STORYBOOK_DOCS_BASE__;
+  if (globalBase) return globalBase.replace(/\/$/, "");
+  const { pathname } = window.location;
+  return pathname === "/" || pathname.endsWith(".html") ? "" : pathname.replace(/\/$/, "");
+})();
+var hrefFor = (path) => `${STORYBOOK_DOCS_BASE}${path}`;
+
 // src/guidance.tsx
 import { createElement, useEffect, useMemo as useMemo2, useState } from "react";
 import { loadGuidance } from "virtual:storybook-docs/guidance";
@@ -1156,7 +1165,7 @@ function formatValue(value) {
   return String(value);
 }
 function TableFrame({ label, children }) {
-  return /* @__PURE__ */ jsx8("div", { className: "table-scroll", role: "region", "aria-label": label, tabIndex: 0, children: /* @__PURE__ */ jsxs5("table", { children: [
+  return /* @__PURE__ */ jsx8("div", { className: "table-scroll", role: "region", "aria-label": label, tabIndex: 0, children: /* @__PURE__ */ jsxs5("table", { className: "props-table", children: [
     /* @__PURE__ */ jsx8("caption", { className: "sr-only", children: label }),
     children
   ] }) });
@@ -1175,28 +1184,67 @@ function PropNotes({ prop }) {
     !prop.description && !prop.tags?.length && !prop.inheritedFrom ? "\u2014" : null
   ] });
 }
+var SHAPE_PREVIEW_FIELDS = 3;
+function PropType({ prop }) {
+  const signature2 = prop.signatures?.[0];
+  const fields = prop.members?.slice(0, SHAPE_PREVIEW_FIELDS).map((member) => `${member.name}${member.required ? "" : "?"}: \u2026`).join("; ");
+  return /* @__PURE__ */ jsxs5(Fragment3, { children: [
+    /* @__PURE__ */ jsx8("code", { className: signature2 ? "type signature" : "type", tabIndex: signature2 ? 0 : void 0, children: prop.typeUnavailable ? "Not resolved" : signature2?.type ?? prop.type }),
+    signature2 ? /* @__PURE__ */ jsxs5("details", { children: [
+      /* @__PURE__ */ jsx8("summary", { children: "Signature details" }),
+      prop.type !== signature2.type ? /* @__PURE__ */ jsx8("code", { className: "type", children: prop.type }) : null,
+      prop.signatures?.map((item, index) => /* @__PURE__ */ jsxs5("div", { children: [
+        /* @__PURE__ */ jsx8("code", { className: "type", children: item.type }),
+        /* @__PURE__ */ jsx8("dl", { children: item.parameters.filter((parameter) => parameter.description).map((parameter) => /* @__PURE__ */ jsxs5("div", { children: [
+          /* @__PURE__ */ jsx8("dt", { children: /* @__PURE__ */ jsxs5("code", { children: [
+            parameter.name,
+            ": ",
+            parameter.type
+          ] }) }),
+          /* @__PURE__ */ jsx8("dd", { children: /* @__PURE__ */ jsx8(MarkdownView, { markdown: parameter.description }) })
+        ] }, parameter.name)) })
+      ] }, index))
+    ] }) : null,
+    prop.members?.length ? /* @__PURE__ */ jsxs5("details", { children: [
+      /* @__PURE__ */ jsxs5("summary", { children: [
+        prop.name === "slotProps" ? "Slots" : "Fields",
+        " ",
+        /* @__PURE__ */ jsx8("code", { children: `{ ${fields}${prop.members.length > SHAPE_PREVIEW_FIELDS ? "; \u2026" : ""} }` })
+      ] }),
+      /* @__PURE__ */ jsx8("dl", { children: prop.members.map((member) => /* @__PURE__ */ jsxs5("div", { children: [
+        /* @__PURE__ */ jsxs5("dt", { children: [
+          /* @__PURE__ */ jsxs5("code", { children: [
+            member.name,
+            member.required ? "" : "?"
+          ] }),
+          member.required ? " (required)" : ""
+        ] }),
+        /* @__PURE__ */ jsxs5("dd", { children: [
+          /* @__PURE__ */ jsx8(PropType, { prop: member }),
+          /* @__PURE__ */ jsx8(PropNotes, { prop: member })
+        ] })
+      ] }, member.name)) })
+    ] }) : null
+  ] });
+}
+function InheritedLinks({ component }) {
+  const bases = Array.from(new Map(component.props.flatMap((prop) => prop.inheritedComponent ? [[prop.inheritedComponent.slug, prop.inheritedComponent]] : [])).values());
+  return bases.length ? /* @__PURE__ */ jsxs5("p", { children: [
+    "Also available from ",
+    bases.map((entry, index) => /* @__PURE__ */ jsxs5("span", { children: [
+      index ? ", " : "",
+      /* @__PURE__ */ jsx8("a", { href: `#${hrefFor(`/components/${entry.slug}`)}`, children: entry.name })
+    ] }, entry.slug)),
+    "."
+  ] }) : null;
+}
 function PropRows({ props }) {
   return props.map((prop) => /* @__PURE__ */ jsxs5("tr", { children: [
     /* @__PURE__ */ jsxs5("th", { scope: "row", children: [
       /* @__PURE__ */ jsx8("code", { children: prop.name }),
       prop.required ? /* @__PURE__ */ jsx8("span", { className: "req", children: "required" }) : null
     ] }),
-    /* @__PURE__ */ jsxs5("td", { children: [
-      /* @__PURE__ */ jsx8("code", { className: "type", children: prop.typeUnavailable ? "Not resolved" : prop.type }),
-      prop.members?.length ? /* @__PURE__ */ jsxs5("details", { children: [
-        /* @__PURE__ */ jsx8("summary", { children: prop.name === "slotProps" ? "Slots" : "Fields" }),
-        /* @__PURE__ */ jsx8("dl", { children: prop.members.map((member) => /* @__PURE__ */ jsxs5("div", { children: [
-          /* @__PURE__ */ jsxs5("dt", { children: [
-            /* @__PURE__ */ jsx8("code", { children: member.name }),
-            member.required ? " (required)" : ""
-          ] }),
-          /* @__PURE__ */ jsxs5("dd", { children: [
-            /* @__PURE__ */ jsx8("code", { children: member.type }),
-            /* @__PURE__ */ jsx8(PropNotes, { prop: member })
-          ] })
-        ] }, member.name)) })
-      ] }) : null
-    ] }),
+    /* @__PURE__ */ jsx8("td", { children: /* @__PURE__ */ jsx8(PropType, { prop }) }),
     /* @__PURE__ */ jsx8("td", { children: /* @__PURE__ */ jsx8("code", { children: prop.defaultValue === "undefined" ? "\u2014" : prop.defaultValue ?? "\u2014" }) }),
     /* @__PURE__ */ jsx8("td", { children: /* @__PURE__ */ jsx8(PropNotes, { prop }) })
   ] }, prop.name));
@@ -1231,6 +1279,7 @@ function PropsTable({
         ] }) }),
         /* @__PURE__ */ jsx8("tbody", { children: /* @__PURE__ */ jsx8(PropRows, { props: component.props.filter((prop) => !prop.inheritedFrom) }) })
       ] }) : /* @__PURE__ */ jsx8("p", { children: "No component-specific props." }),
+      /* @__PURE__ */ jsx8(InheritedLinks, { component }),
       component.props.some((prop) => prop.inheritedFrom) ? /* @__PURE__ */ jsxs5("details", { children: [
         /* @__PURE__ */ jsxs5("summary", { children: [
           "Inherited props (",
@@ -1567,17 +1616,6 @@ function TypePage() {
 // src/pages/overview.tsx
 import { catalog, groups, stats } from "virtual:storybook-docs/catalog";
 import { site } from "virtual:storybook-docs/site";
-
-// src/base.ts
-var STORYBOOK_DOCS_BASE = (() => {
-  const globalBase = globalThis.__STORYBOOK_DOCS_BASE__;
-  if (globalBase) return globalBase.replace(/\/$/, "");
-  const { pathname } = window.location;
-  return pathname === "/" || pathname.endsWith(".html") ? "" : pathname.replace(/\/$/, "");
-})();
-var hrefFor = (path) => `${STORYBOOK_DOCS_BASE}${path}`;
-
-// src/pages/overview.tsx
 import { Fragment as Fragment8, jsx as jsx13, jsxs as jsxs10 } from "react/jsx-runtime";
 function OverviewPage() {
   const startHere = catalog.slice(0, 6);

package/dist/prop-docs.d.ts

@@ -6,11 +6,23 @@ export interface PropDoc {
     defaultValue: string | null;
     description: string;
     inheritedFrom?: string;
+    inheritedComponent?: {
+        name: string;
+        slug: string;
+    };
     tags?: {
         name: string;
         text: string;
     }[];
     members?: PropDoc[];
+    signatures?: {
+        type: string;
+        parameters: {
+            name: string;
+            type: string;
+            description: string;
+        }[];
+    }[];
 }
 export interface ComponentPropsDoc {
     name: string;

package/dist/styles.css

@@ -426,8 +426,30 @@ pre.code {
 }
 code.type {
   white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  display: inline-block;
+  max-inline-size: 100%;
+}
+code.signature {
+  display: block;
+  white-space: pre;
+  overflow-x: auto;
+  padding-bottom: 4px;
+}
+.table-scroll > .props-table {
+  table-layout: fixed;
+  min-inline-size: 640px;
+}
+.props-table thead th:nth-child(1) { width: 18%; }
+.props-table thead th:nth-child(2) { width: 34%; }
+.props-table thead th:nth-child(3) { width: 12%; }
+.props-table thead th:nth-child(4) { width: 36%; }
+.props-table :is(th, td) {
+  overflow-wrap: anywhere;
 }
 .req {
+  display: inline-block;
+  white-space: nowrap;
   margin-left: 6px;
   font-size: 10.5px;
   letter-spacing: 0.05em;

package/dist/vite-plugin.js

@@ -1,5 +1,5 @@
 // src/vite-plugin.ts
-import { readFileSync as readFileSync3, realpathSync } from "node:fs";
+import { readFileSync as readFileSync3, realpathSync as realpathSync2 } from "node:fs";
 import path7 from "node:path";
 
 // src/build/catalog.ts
@@ -248,7 +248,7 @@ function globalStylesCode(engineStyles, css = []) {
 }
 
 // src/build/props.ts
-import { readdirSync as readdirSync2 } from "node:fs";
+import { readdirSync as readdirSync2, realpathSync } from "node:fs";
 import path3 from "node:path";
 import { withCompilerOptions } from "react-docgen-typescript";
 import ts from "typescript";
@@ -319,7 +319,7 @@ function createPropsCollector() {
     cache.program = ts.createProgram(sources, compilerOptions, cache.host, cache.program);
     return cache.program;
   };
-  const collect = (storyFile, entryName, slug) => {
+  const collect = (storyFile, entryName, slug, bases = []) => {
     if (storyFile) {
       const directory = path3.dirname(storyFile);
       const sources = readdirSync2(directory).filter((file) => /\.tsx?$/.test(file) && !file.endsWith(".stories.tsx")).map((file) => path3.join(directory, file));
@@ -331,7 +331,7 @@ function createPropsCollector() {
           })).filter((component) => component.props.length > 0);
           const matchesOwnName = (name) => entryName.length > 0 && name.toLowerCase().startsWith(entryName.toLowerCase());
           const relevant = parsed.some((component) => matchesOwnName(component.name)) ? parsed.filter((component) => matchesOwnName(component.name)) : parsed;
-          const typed = collectTypeProps(sources, entryName);
+          const typed = collectTypeProps(sources, entryName, bases);
           return mergePropsTables(typed.length > 0 ? [...relevant.filter((table) => typed.some((item) => item.name === table.name)), ...typed] : relevant);
         } catch (cause) {
           console.warn(`storybook-docs: could not read props for "${slug}" (${String(cause)})`);
@@ -340,10 +340,45 @@ function createPropsCollector() {
     }
     return [];
   };
-  const collectTypeProps = (sources, entryName) => {
+  const collectTypeProps = (sources, entryName, bases) => {
     const program = createPropsProgram(sources, TYPE_PROPS_COMPILER_OPTIONS);
     const checker = program.getTypeChecker();
     const tables = [];
+    const baseContracts = bases.filter((base) => base.name !== entryName).map((base) => ({
+      ...base,
+      directory: path3.dirname(realpathSync(base.storyFile)),
+      declarations: /* @__PURE__ */ new Set()
+    }));
+    const readContract = (type, location, declarations, depth = 0) => {
+      for (const signature of type.getCallSignatures()) {
+        const parameter = signature.getParameters()[0];
+        if (!parameter) continue;
+        const propsType = checker.getTypeOfSymbolAtLocation(parameter, signature.getDeclaration() ?? location);
+        for (const prop of checker.getPropertiesOfType(propsType)) {
+          prop.declarations?.forEach((declaration) => declarations.add(declaration));
+        }
+      }
+      if (depth >= 2) return;
+      for (const member of checker.getPropertiesOfType(type)) {
+        if (["bind", "call", "apply"].includes(member.getName())) continue;
+        const memberType = checker.getTypeOfSymbolAtLocation(member, member.valueDeclaration ?? location);
+        if (memberType.getCallSignatures().length) readContract(memberType, location, declarations, depth + 1);
+      }
+    };
+    for (const source of program.getSourceFiles()) {
+      if (isExternal(source.fileName)) continue;
+      const directory = path3.dirname(realpathSync(source.fileName));
+      const candidates = baseContracts.filter((base) => base.directory === directory);
+      if (!candidates.length) continue;
+      const module = checker.getSymbolAtLocation(source);
+      if (!module) continue;
+      for (const symbol of checker.getExportsOfModule(module)) {
+        for (const base of candidates.filter((candidate) => candidate.name === symbol.getName())) {
+          const target = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+          readContract(checker.getTypeOfSymbolAtLocation(target, target.valueDeclaration ?? source), source, base.declarations);
+        }
+      }
+    }
     const unresolved = /* @__PURE__ */ Symbol("unresolved");
     const literalValue = (node, seen = /* @__PURE__ */ new Set()) => {
       if (seen.has(node)) return unresolved;
@@ -391,9 +426,26 @@ function createPropsCollector() {
       const printedType = checker.typeToString(propType, void 0, typeFlags);
       const displayType = literalUnion && propType.isUnion() ? propType.types.filter((part) => !optional || !(part.flags & ts.TypeFlags.Undefined)).map((part) => checker.typeToString(part, void 0, typeFlags)).join(" | ").replace(/false \| true/g, "boolean") : optional ? printedType.replace(/ \| undefined$/, "") : printedType;
       const parent = declaration?.parent;
-      const inheritedFrom = declaration && (isExternal(declaration.getSourceFile().fileName) || !sources.includes(declaration.getSourceFile().fileName)) ? parent && (ts.isInterfaceDeclaration(parent) || ts.isTypeAliasDeclaration(parent)) ? parent.name.text : path3.basename(declaration.getSourceFile().fileName) : void 0;
+      const declarationName = declaration ? parent && (ts.isInterfaceDeclaration(parent) || ts.isTypeAliasDeclaration(parent)) ? parent.name.text : path3.basename(declaration.getSourceFile().fileName) : void 0;
+      const inheritedComponent = declaration ? baseContracts.find(
+        (base) => base.declarations.has(declaration) && base.directory === path3.dirname(realpathSync(declaration.getSourceFile().fileName))
+      ) : void 0;
+      const inheritedFrom = declaration && (inheritedComponent || isExternal(declaration.getSourceFile().fileName) || !sources.includes(declaration.getSourceFile().fileName)) ? declarationName : void 0;
       const memberType = checker.getNonNullableType(propType);
-      const hasLocalMembers = !checker.isArrayType(memberType) && !checker.isTupleType(memberType) && !memberType.getCallSignatures().length && checker.getPropertiesOfType(memberType).some((member) => member.declarations?.some((node) => !isExternal(node.getSourceFile().fileName)));
+      const nonCallableAlternatives = propType.isUnion() ? propType.types.filter((part) => Boolean(part.flags & (ts.TypeFlags.Null | ts.TypeFlags.Undefined)) && (!optional || !(part.flags & ts.TypeFlags.Undefined))).map((part) => checker.typeToString(part, void 0, typeFlags)) : [];
+      const signatures = memberType.getCallSignatures().map((signature) => {
+        const signatureType = checker.signatureToString(signature, location, typeFlags | ts.TypeFormatFlags.WriteArrowStyleSignature);
+        return {
+          type: nonCallableAlternatives.length ? `(${signatureType}) | ${nonCallableAlternatives.join(" | ")}` : signatureType,
+          parameters: signature.getParameters().map((parameter) => ({
+            name: parameter.getName(),
+            type: checker.typeToString(checker.getTypeOfSymbolAtLocation(parameter, parameter.valueDeclaration ?? location), location, typeFlags),
+            description: ts.displayPartsToString(parameter.getDocumentationComment(checker)).trim()
+          }))
+        };
+      });
+      const objectTypes = memberType.isUnion() ? memberType.types : [memberType];
+      const hasLocalMembers = objectTypes.every((part) => Boolean(part.flags & (ts.TypeFlags.Object | ts.TypeFlags.Intersection))) && !checker.isArrayType(memberType) && !checker.isTupleType(memberType) && !signatures.length && checker.getPropertiesOfType(memberType).some((member) => member.declarations?.some((node) => !isExternal(node.getSourceFile().fileName)));
       return {
         name: symbol.getName(),
         type: displayType || "unknown",
@@ -402,6 +454,8 @@ function createPropsCollector() {
         defaultValue: null,
         description: ts.displayPartsToString(symbol.getDocumentationComment(checker)).trim(),
         inheritedFrom,
+        inheritedComponent: inheritedComponent ? { name: inheritedComponent.name, slug: inheritedComponent.slug } : void 0,
+        signatures: signatures.length ? signatures : void 0,
         tags: symbol.getJsDocTags(checker).filter((tag) => ["deprecated", "since", "example"].includes(tag.name)).map((tag) => ({ name: tag.name, text: ts.displayPartsToString(tag.text) })),
         members: depth === 0 && (symbol.getName() === "slotProps" || !inheritedFrom && hasLocalMembers) ? describeProps(memberType, location, depth + 1) : void 0
       };
@@ -928,7 +982,10 @@ function storybookDocs(options2) {
     let components = propsCache.get(slug);
     if (!components) {
       const name = catalog.entries.find((entry) => entry.slug === slug)?.name ?? "";
-      components = propsCollector.collect(catalog.files.get(slug), name, slug);
+      components = propsCollector.collect(catalog.files.get(slug), name, slug, catalog.entries.flatMap((entry) => {
+        const storyFile = catalog.files.get(entry.slug);
+        return storyFile ? [{ name: entry.name, slug: entry.slug, storyFile }] : [];
+      }));
       propsCache.set(slug, components);
     }
     return propsCode(components);
@@ -980,7 +1037,7 @@ export const storySource = ${JSON.stringify(config.stories.from)};`,
     },
     resolveId(id) {
       if (id.startsWith(VIRTUAL_PREFIX)) return `\0${id}`;
-      if (id.startsWith(FILE_PREFIX)) return realpathSync(id.slice(FILE_PREFIX.length));
+      if (id.startsWith(FILE_PREFIX)) return realpathSync2(id.slice(FILE_PREFIX.length));
       if (id === "storybook/test") return `\0${VIRTUAL_PREFIX}stub-storybook-test`;
       return null;
     },
@@ -993,7 +1050,7 @@ export const storySource = ${JSON.stringify(config.stories.from)};`,
       if (name.startsWith("story-sources/")) {
         const storyFile = catalog.files.get(name.slice("story-sources/".length));
         if (!storyFile) return storySourcesCode({});
-        const file = realpathSync(storyFile);
+        const file = realpathSync2(storyFile);
         let sources = storySourcesCache.get(file);
         if (!sources) {
           sources = extractStorySources(readFileSync3(file, "utf8"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jfrader/storybook-docs",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "type": "module",
   "description": "A documentation front for any design system that has Storybook: navigation, live examples and API tables are generated from the story files themselves.",
   "exports": {