@alauda/doom 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,7 +5,7 @@ import { glob } from 'tinyglobby';
5
5
  import { resolveStaticConfig } from '../../utils/index.js';
6
6
  const crdsMap = {};
7
7
  const openapisMap = {};
8
- let allReferences;
8
+ const shared = {};
9
9
  export const apiPlugin = () => {
10
10
  return {
11
11
  name: 'doom-api',
@@ -14,7 +14,7 @@ export const apiPlugin = () => {
14
14
  if (!config.api) {
15
15
  return;
16
16
  }
17
- const { crds, openapis, references } = config.api;
17
+ const { crds, openapis, references, pathPrefix } = config.api;
18
18
  if (crds) {
19
19
  for (const file of await glob(crds, {
20
20
  cwd: config.root,
@@ -39,12 +39,14 @@ export const apiPlugin = () => {
39
39
  openapisMap[file] = doc;
40
40
  }
41
41
  }
42
- allReferences = references;
42
+ shared.references = references;
43
+ shared.pathPrefix = pathPrefix;
43
44
  },
44
45
  extendPageData(pageData) {
45
46
  pageData.crdsMap = crdsMap;
46
47
  pageData.openapisMap = openapisMap;
47
- pageData.references = allReferences;
48
+ pageData.references = shared.references;
49
+ pageData.pathPrefix = shared.pathPrefix;
48
50
  },
49
51
  };
50
52
  };
@@ -0,0 +1,11 @@
1
+ import { ReactNode } from 'react';
2
+ export interface DirectiveProps {
3
+ type?: 'danger' | 'details' | 'info' | 'note' | 'tip' | 'warning';
4
+ children: ReactNode;
5
+ className?: string;
6
+ title?: ReactNode;
7
+ open?: boolean;
8
+ onToggle?: (open: boolean) => void;
9
+ }
10
+ export declare const Directive: ({ className, type, title, children, open, onToggle, }: DirectiveProps) => import("react/jsx-runtime").JSX.Element;
11
+ export default Directive;
@@ -0,0 +1,17 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { clsx } from 'clsx';
3
+ import { upperCase } from 'es-toolkit';
4
+ import { useCallback } from 'react';
5
+ export const Directive = ({ className, type = 'info', title, children, open, onToggle, }) => {
6
+ const rootClassName = clsx('rspress-directive', type, className);
7
+ const titleNode = title || upperCase(type);
8
+ const contentNode = (_jsx("div", { className: "rspress-directive-content", children: children }));
9
+ const handleToggle = useCallback((ev) => {
10
+ onToggle?.(ev.currentTarget.open);
11
+ }, [onToggle]);
12
+ if (type === 'details') {
13
+ return (_jsxs("details", { className: rootClassName, open: open, onToggle: handleToggle, children: [_jsx("summary", { className: "rspress-directive-title", children: titleNode }), contentNode] }));
14
+ }
15
+ return (_jsxs("div", { className: rootClassName, children: [_jsx("div", { className: "rspress-directive-title", children: titleNode }), contentNode] }));
16
+ };
17
+ export default Directive;
@@ -1,5 +1,26 @@
1
+ /**
2
+ * modified based on @see https://github.com/crdsdev/doc/blob/main/template/doc.html
3
+ */
4
+ import { OpenAPIV3_1 } from 'openapi-types';
1
5
  export interface K8sCrdProps {
6
+ /**
7
+ * The `metadata.name` of the CustomResourceDefinition
8
+ */
2
9
  name: string;
10
+ /**
11
+ * The specific path to the CRD, otherwise the first matched will be used.
12
+ */
13
+ crdPath?: string;
3
14
  }
4
- export declare const K8sCrd: ({ name }: K8sCrdProps) => import("react/jsx-runtime").JSX.Element;
15
+ export declare const K8sCrdSchemaPart: ({ name, parent, schema: property, openAll, }: {
16
+ name: string;
17
+ parent: OpenAPIV3_1.SchemaObject;
18
+ schema: OpenAPIV3_1.SchemaObject;
19
+ openAll: boolean;
20
+ }) => import("react/jsx-runtime").JSX.Element;
21
+ export declare const K8sCrdSchema: ({ schema, version, }: {
22
+ schema: OpenAPIV3_1.SchemaObject;
23
+ version: string;
24
+ }) => import("react/jsx-runtime").JSX.Element;
25
+ export declare const K8sCrd: ({ name, crdPath }: K8sCrdProps) => import("react/jsx-runtime").JSX.Element | null;
5
26
  export default K8sCrd;
@@ -1,5 +1,71 @@
1
- import { jsx as _jsx } from "react/jsx-runtime";
2
- export const K8sCrd = ({ name }) => {
3
- return _jsx("h2", { children: name });
1
+ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
2
+ /**
3
+ * modified based on @see https://github.com/crdsdev/doc/blob/main/template/doc.html
4
+ */
5
+ import { usePageData } from '@rspress/core/runtime';
6
+ import { Badge, Button, getCustomMDXComponent } from '@rspress/core/theme';
7
+ import { useCallback, useEffect, useMemo, useState } from 'react';
8
+ import { useTranslation } from '../hooks/index.js';
9
+ import { Markdown } from './_Markdown.js';
10
+ import Directive from './Directive.js';
11
+ const X = getCustomMDXComponent();
12
+ export const K8sCrdSchemaPart = ({ name, parent, schema: property, openAll, }) => {
13
+ const [open, setOpen] = useState(openAll);
14
+ const onToggle = useCallback((open) => {
15
+ setOpen(open);
16
+ }, []);
17
+ useEffect(() => {
18
+ setOpen(openAll);
19
+ }, [openAll]);
20
+ const [props, required, type, schema] = useMemo(() => {
21
+ let schema = property;
22
+ let props = property.properties;
23
+ let type = property.type;
24
+ if (property.type === 'array') {
25
+ const itemsSchema = property.items;
26
+ if (itemsSchema.type === 'object') {
27
+ schema = itemsSchema;
28
+ props = itemsSchema.properties;
29
+ type = `[]object`;
30
+ }
31
+ else if (itemsSchema.type) {
32
+ type = `[]${itemsSchema.type}`;
33
+ }
34
+ }
35
+ let required = false;
36
+ if (parent.required?.includes(name)) {
37
+ required = true;
38
+ }
39
+ return [props, required, type, schema];
40
+ }, [name, parent, property]);
41
+ return (_jsx(_Fragment, { children: _jsxs(Directive, { type: "details", title: _jsxs(_Fragment, { children: [name, type && _jsx(X.code, { children: type }), required && _jsx(Badge, { children: "required" })] }), open: open, onToggle: onToggle, children: [_jsx(Markdown, { children: schema.description }), props &&
42
+ Object.entries(props).map(([name, subSchema]) => (_jsx(K8sCrdSchemaPart, { name: name, parent: schema, schema: subSchema, openAll: openAll }, name)))] }) }));
43
+ };
44
+ const SKIPPED_PROPERTIES = ['apiVersion', 'kind', 'metadata'];
45
+ export const K8sCrdSchema = ({ schema, version, }) => {
46
+ const { description, properties } = schema;
47
+ const t = useTranslation();
48
+ const [openAll, setOpenAll] = useState(false);
49
+ const expandAll = useCallback(() => {
50
+ setOpenAll(true);
51
+ }, []);
52
+ const collapseAll = useCallback(() => {
53
+ setOpenAll(false);
54
+ }, []);
55
+ return (_jsxs(_Fragment, { children: [_jsx(Markdown, { children: description }), _jsxs("div", { className: "flex items-center", children: [_jsxs("span", { children: [_jsx(X.code, { children: version }), _jsx(Badge, { children: "version" })] }), properties != null && (_jsxs("div", { className: "ml-auto", children: [_jsx(Button, { className: "doom-btn", type: "button", text: _jsxs("span", { onClick: collapseAll, children: ["- ", t('collapse_all')] }), size: "medium", theme: "alt" }), _jsx(Button, { className: "doom-btn ml-2", type: "button", text: _jsxs("span", { onClick: expandAll, children: ["+ ", t('expand_all')] }), size: "medium", theme: "alt" })] }))] }), properties == null ? (_jsx(Directive, { type: "warning", children: t('crd_no_schema') })) : (_jsx("div", { className: "doom-collapse-group", children: Object.entries(properties).map(([name, subSchema]) => SKIPPED_PROPERTIES.includes(name) || (_jsx(K8sCrdSchemaPart, { name: name, parent: schema, schema: subSchema, openAll: openAll }, name))) }))] }));
56
+ };
57
+ export const K8sCrd = ({ name, crdPath }) => {
58
+ const { page } = usePageData();
59
+ const [, crd] = useMemo(() => Object.entries(page.crdsMap || {}).find(([pathname, crd]) => {
60
+ if (crdPath && pathname !== crdPath) {
61
+ return false;
62
+ }
63
+ return crd.metadata.name === name;
64
+ }) || [], [page]);
65
+ if (!crd) {
66
+ console.error(`No CustomResourceDefinition found for ${name}`);
67
+ return null;
68
+ }
69
+ return (_jsxs(_Fragment, { children: [_jsxs(X.p, { children: [_jsx(X.code, { children: crd.spec.group }), _jsx(Badge, { children: "group" })] }), crd.spec.versions.map((version) => (_jsx(K8sCrdSchema, { schema: version.schema.openAPIV3Schema, version: version.name })))] }));
4
70
  };
5
71
  export default K8sCrd;
@@ -1,6 +1,17 @@
1
1
  import { OpenAPIV3_1 } from 'openapi-types';
2
2
  export interface OpenAPIPathProps {
3
+ /**
4
+ * The path under the OpenAPI schema `paths` definition.
5
+ */
3
6
  path: string;
7
+ /**
8
+ * The specific path to the OpenAPI schema, otherwise the first matched will be used.
9
+ */
10
+ openapiPath?: string;
11
+ /**
12
+ * If you have a gateway which adds common path prefix, can be used to override global config level `pathPrefix`.
13
+ */
14
+ pathPrefix?: string;
4
15
  }
5
16
  export declare const OpenAPIParameters: ({ parameters, openapi, }: {
6
17
  parameters: Array<OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.ParameterObject>;
@@ -10,5 +21,5 @@ export declare const OpenAPIResponses: ({ responses, openapi, }: {
10
21
  responses: OpenAPIV3_1.ResponsesObject;
11
22
  openapi: OpenAPIV3_1.Document;
12
23
  }) => import("react/jsx-runtime").JSX.Element;
13
- export declare const OpenAPIPath: ({ path }: OpenAPIPathProps) => import("react/jsx-runtime").JSX.Element | null;
24
+ export declare const OpenAPIPath: ({ path, openapiPath: openapiPath_, pathPrefix: pathPrefix_, }: OpenAPIPathProps) => import("react/jsx-runtime").JSX.Element | null;
14
25
  export default OpenAPIPath;
@@ -72,16 +72,21 @@ const getRefsForPath = (openapi, path, knownRefs) => {
72
72
  }
73
73
  return Array.from(refs);
74
74
  };
75
- export const OpenAPIPath = ({ path }) => {
75
+ export const OpenAPIPath = ({ path, openapiPath: openapiPath_, pathPrefix: pathPrefix_, }) => {
76
76
  const { page } = usePageData();
77
+ const pathPrefix = pathPrefix_ ?? (page.pathPrefix || '');
77
78
  const slugger = useMemo(() => new BananaSlug(), []);
78
- const [pathItem, openapi, refs] = useMemo(() => {
79
- for (const openapi of Object.values(page.openapisMap || {})) {
79
+ const [pathItem, openapi, openapiPath, refs] = useMemo(() => {
80
+ for (const [pathname, openapi] of Object.entries(page.openapisMap || {})) {
81
+ if (openapiPath_ && pathname !== openapiPath_) {
82
+ continue;
83
+ }
80
84
  const pathItem = openapi.paths?.[path];
81
85
  if (pathItem) {
82
86
  return [
83
87
  pathItem,
84
88
  openapi,
89
+ pathname,
85
90
  getRefsForPath(openapi, path, omitRoutePathRefs({
86
91
  ...page.references,
87
92
  ...DEFAULT_COMMON_REFS,
@@ -95,7 +100,7 @@ export const OpenAPIPath = ({ path }) => {
95
100
  console.error(`No OpenAPI path definition found for ${path}`);
96
101
  return null;
97
102
  }
98
- return (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 2, children: path }), pathItem.parameters && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 3, children: "Common Parameters" }), _jsx(OpenAPIParameters, { parameters: pathItem.parameters, openapi: openapi })] })), Object.values(OpenAPIV3.HttpMethods).map((method) => {
103
+ return (_jsxs(_Fragment, { children: [_jsxs(HeadingTitle, { slugger: slugger, level: 2, children: [pathPrefix, path] }), pathItem.parameters && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 3, children: "Common Parameters" }), _jsx(OpenAPIParameters, { parameters: pathItem.parameters, openapi: openapi })] })), Object.values(OpenAPIV3.HttpMethods).map((method) => {
99
104
  if (!pathItem[method]) {
100
105
  return null;
101
106
  }
@@ -104,7 +109,7 @@ export const OpenAPIPath = ({ path }) => {
104
109
  ? requestBody.$ref
105
110
  : requestBody.content['application/json'].schema?.$ref })] })), responses && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 4, children: "Response" }), _jsx(OpenAPIResponses, { responses: responses, openapi: openapi })] }))] }));
106
111
  }), refs?.map((ref, index) => {
107
- return (_jsx(OpenAPIRef, { schema: ref, openapi: openapi, collectRefs: false }, index));
112
+ return (_jsx(OpenAPIRef, { schema: ref, openapiPath: openapiPath, collectRefs: false }, index));
108
113
  })] }));
109
114
  };
110
115
  export default OpenAPIPath;
@@ -1,12 +1,18 @@
1
1
  import { OpenAPIV3_1 } from 'openapi-types';
2
2
  export interface OpenAPIRefProps {
3
+ /**
4
+ * The schema name under the OpenAPI schema `definitions` (swagger 2.0) or `components/schemas` (openapi 3.x).
5
+ */
3
6
  schema: string;
4
- openapi?: OpenAPIV3_1.Document;
7
+ /**
8
+ * The specific path to the OpenAPI schema, otherwise the first matched will be used.
9
+ */
10
+ openapiPath?: string;
5
11
  collectRefs?: boolean;
6
12
  }
7
13
  export declare const OpenAPIProperties: ({ properties, openapi, }: {
8
14
  properties: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.SchemaObject>;
9
15
  openapi: OpenAPIV3_1.Document;
10
16
  }) => import("react/jsx-runtime").JSX.Element;
11
- export declare const OpenAPIRef: ({ schema, openapi: openapi_, collectRefs, }: OpenAPIRefProps) => import("react/jsx-runtime").JSX.Element | null;
17
+ export declare const OpenAPIRef: ({ schema, openapiPath: openapiPath_, collectRefs, }: OpenAPIRefProps) => import("react/jsx-runtime").JSX.Element | null;
12
18
  export default OpenAPIRef;
@@ -4,8 +4,8 @@ import { getCustomMDXComponent } from '@rspress/theme-default';
4
4
  import { useMemo } from 'react';
5
5
  import { DEFAULT_COMMON_REFS, modelName, omitRoutePathRefs, resolveRef, } from '../utils.js';
6
6
  import { HeadingTitle } from './_HeadingTitle.js';
7
- import { RefLink } from './_RefLink.js';
8
7
  import { Markdown } from './_Markdown.js';
8
+ import { RefLink } from './_RefLink.js';
9
9
  const X = getCustomMDXComponent();
10
10
  export const OpenAPIProperties = ({ properties, openapi, }) => {
11
11
  return (_jsx(X.ul, { children: Object.entries(properties).map(([name, prop], index) => {
@@ -65,20 +65,16 @@ const getRefsForSchema = (openapi, schema, knownRefs) => {
65
65
  collectRefs(refSchema);
66
66
  return Array.from(refs);
67
67
  };
68
- export const OpenAPIRef = ({ schema, openapi: openapi_, collectRefs = true, }) => {
68
+ export const OpenAPIRef = ({ schema, openapiPath: openapiPath_, collectRefs = true, }) => {
69
69
  const { page } = usePageData();
70
- const [schemaItem, openapi] = useMemo(() => {
71
- if (openapi_) {
72
- return [
73
- // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments -- no sure to understand
74
- resolveRef(openapi_, schema),
75
- openapi_,
76
- ];
77
- }
78
- for (const openapi of Object.values(page.openapisMap || {})) {
70
+ const [schemaItem, openapi, openapiPath] = useMemo(() => {
71
+ for (const [pathname, openapi] of Object.entries(page.openapisMap || {})) {
72
+ if (openapiPath_ && pathname !== openapiPath_) {
73
+ continue;
74
+ }
79
75
  const schemaItem = openapi.components?.schemas?.[schema];
80
76
  if (schemaItem) {
81
- return [schemaItem, openapi];
77
+ return [schemaItem, openapi, pathname];
82
78
  }
83
79
  }
84
80
  return [];
@@ -95,6 +91,6 @@ export const OpenAPIRef = ({ schema, openapi: openapi_, collectRefs = true, }) =
95
91
  }, page.routePath));
96
92
  }
97
93
  }, [collectRefs, openapi, page.routePath, schema]);
98
- return (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slug: schema, level: 2, children: modelName(schema) }), _jsx(Markdown, { children: schemaItem.description }), schemaItem.properties && (_jsx(OpenAPIProperties, { properties: schemaItem.properties, openapi: openapi })), refs?.map((schema, index) => (_jsx(OpenAPIRef, { schema: schema, openapi: openapi, collectRefs: false }, index)))] }));
94
+ return (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slug: schema, level: 2, children: modelName(schema) }), _jsx(Markdown, { children: schemaItem.description }), schemaItem.properties && (_jsx(OpenAPIProperties, { properties: schemaItem.properties, openapi: openapi })), refs?.map((schema, index) => (_jsx(OpenAPIRef, { schema: schema, openapiPath: openapiPath, collectRefs: false }, index)))] }));
99
95
  };
100
96
  export default OpenAPIRef;
@@ -3,4 +3,4 @@ import { getCustomMDXComponent } from '@rspress/core/theme';
3
3
  import ReactMarkdown from 'react-markdown';
4
4
  import remarkGfm from 'remark-gfm';
5
5
  const components = getCustomMDXComponent();
6
- export const Markdown = ({ children }) => children && (_jsx(ReactMarkdown, { remarkPlugins: [[remarkGfm]], components: components, skipHtml: true, className: "rspress-plugin-api-docgen", children: children }));
6
+ export const Markdown = ({ children }) => children && (_jsx(ReactMarkdown, { remarkPlugins: [[remarkGfm]], components: components, skipHtml: true, children: children }));
@@ -0,0 +1 @@
1
+ export * from './useTranslation.js';
@@ -0,0 +1 @@
1
+ export * from './useTranslation.js';
@@ -0,0 +1 @@
1
+ export declare const useTranslation: () => (key: "collapse_all" | "expand_all" | "crd_no_schema") => string;
@@ -0,0 +1,8 @@
1
+ import { useLang } from '@rspress/core/runtime';
2
+ import { TRANSLATIONS } from '../translation.js';
3
+ import { useCallback } from 'react';
4
+ export const useTranslation = () => {
5
+ const lang = (useLang() || 'zh');
6
+ const translations = TRANSLATIONS[lang];
7
+ return useCallback((key) => translations[key], []);
8
+ };
@@ -1,4 +1,5 @@
1
1
  /// <reference path="../../global.d.ts" preserve="true" />
2
2
  export * from './components/index.js';
3
+ export * from './hooks/index.js';
3
4
  export * from './types.js';
4
5
  export * from './utils.js';
@@ -1,5 +1,6 @@
1
1
  // eslint-disable-next-line @typescript-eslint/triple-slash-reference
2
2
  /// <reference path="../../global.d.ts" preserve="true" />
3
3
  export * from './components/index.js';
4
+ export * from './hooks/index.js';
4
5
  export * from './types.js';
5
6
  export * from './utils.js';
@@ -0,0 +1,13 @@
1
+ export declare const TRANSLATIONS: {
2
+ en: {
3
+ collapse_all: string;
4
+ expand_all: string;
5
+ crd_no_schema: string;
6
+ };
7
+ zh: {
8
+ collapse_all: string;
9
+ expand_all: string;
10
+ crd_no_schema: string;
11
+ };
12
+ };
13
+ export type Locale = keyof typeof TRANSLATIONS;
@@ -0,0 +1,11 @@
1
+ const en = {
2
+ collapse_all: 'Collapse All',
3
+ expand_all: 'Expand All',
4
+ crd_no_schema: 'This CRD has an empty or unspecified schema.',
5
+ };
6
+ const zh = {
7
+ collapse_all: '全部收起',
8
+ expand_all: '全部展开',
9
+ crd_no_schema: '此 CRD 未定义或定义为空。',
10
+ };
11
+ export const TRANSLATIONS = { en, zh };
@@ -5,6 +5,7 @@ export interface ExtendedPage {
5
5
  crdsMap?: Record<string, CustomResourceDefinition>;
6
6
  openapisMap?: Record<string, OpenAPIV3_1.Document>;
7
7
  references?: Record<string, string>;
8
+ pathPrefix?: string;
8
9
  }
9
10
  export interface ExtendedPageData extends PageData {
10
11
  page: PageData['page'] & ExtendedPage;
@@ -4,5 +4,6 @@ export interface DoomConfig extends UserConfig {
4
4
  crds?: string[];
5
5
  openapis?: string[];
6
6
  references?: Record<string, string>;
7
+ pathPrefix?: string;
7
8
  };
8
9
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alauda/doom",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "type": "module",
5
5
  "description": "Doctor Doom making docs.",
6
6
  "repository": {
@@ -40,6 +40,7 @@
40
40
  "@rspress/core": "^1.37.4",
41
41
  "@rspress/plugin-preview": "^1.37.4",
42
42
  "chokidar": "^4.0.1",
43
+ "clsx": "^2.1.1",
43
44
  "commander": "^12.1.0",
44
45
  "es-toolkit": "^1.29.0",
45
46
  "react-markdown": "^8.0.7",
@@ -4,3 +4,36 @@ td {
4
4
  display: inline-block;
5
5
  }
6
6
  }
7
+
8
+ .doom-btn {
9
+ position: relative;
10
+ padding: 0 !important;
11
+
12
+ > span {
13
+ display: block;
14
+ padding: 0 20px;
15
+ }
16
+ }
17
+
18
+ .doom-collapse-group {
19
+ .rspress-directive {
20
+ margin-bottom: 0;
21
+ padding-top: 10px;
22
+ padding-bottom: 10px;
23
+ border-radius: 0;
24
+
25
+ &:first-child {
26
+ border-top-left-radius: var(--rp-radius-small);
27
+ border-top-right-radius: var(--rp-radius-small);
28
+ }
29
+
30
+ &:last-child {
31
+ border-bottom-left-radius: var(--rp-radius-small);
32
+ border-bottom-right-radius: var(--rp-radius-small);
33
+ }
34
+
35
+ + .rspress-directive {
36
+ margin-top: -1px;
37
+ }
38
+ }
39
+ }