@thedatagrid/docs-kit 0.3.0 → 0.5.0

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.
Files changed (182) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +172 -4
  3. package/dist/code/demoFiles.d.ts.map +1 -1
  4. package/dist/code/demoFiles.js +2 -2
  5. package/dist/code/demoFiles.js.map +1 -1
  6. package/dist/code/index.d.ts +1 -0
  7. package/dist/code/index.d.ts.map +1 -1
  8. package/dist/code/index.js +1 -0
  9. package/dist/code/index.js.map +1 -1
  10. package/dist/code/regions.d.ts +2 -1
  11. package/dist/code/regions.d.ts.map +1 -1
  12. package/dist/code/regions.js +12 -8
  13. package/dist/code/regions.js.map +1 -1
  14. package/dist/code/vueBlocks.d.ts +3 -0
  15. package/dist/code/vueBlocks.d.ts.map +1 -0
  16. package/dist/code/vueBlocks.js +29 -0
  17. package/dist/code/vueBlocks.js.map +1 -0
  18. package/dist/demos/build.d.ts +5 -2
  19. package/dist/demos/build.d.ts.map +1 -1
  20. package/dist/demos/build.js +244 -85
  21. package/dist/demos/build.js.map +1 -1
  22. package/dist/demos/compile/core.d.ts +9 -1
  23. package/dist/demos/compile/core.d.ts.map +1 -1
  24. package/dist/demos/compile/core.js +19 -8
  25. package/dist/demos/compile/core.js.map +1 -1
  26. package/dist/demos/compile/vue.d.ts +107 -0
  27. package/dist/demos/compile/vue.d.ts.map +1 -0
  28. package/dist/demos/compile/vue.js +187 -0
  29. package/dist/demos/compile/vue.js.map +1 -0
  30. package/dist/demos/config.d.ts +41 -7
  31. package/dist/demos/config.d.ts.map +1 -1
  32. package/dist/demos/config.js.map +1 -1
  33. package/dist/demos/index.d.ts +3 -2
  34. package/dist/demos/index.d.ts.map +1 -1
  35. package/dist/demos/index.js +1 -0
  36. package/dist/demos/index.js.map +1 -1
  37. package/dist/demos/pages.d.ts +1 -1
  38. package/dist/demos/pages.d.ts.map +1 -1
  39. package/dist/demos/pages.js +4 -1
  40. package/dist/demos/pages.js.map +1 -1
  41. package/dist/demos/runtime/vue.d.ts +3 -0
  42. package/dist/demos/runtime/vue.d.ts.map +1 -0
  43. package/dist/demos/runtime/vue.js +15 -0
  44. package/dist/demos/runtime/vue.js.map +1 -0
  45. package/dist/demos/vendor.d.ts +5 -1
  46. package/dist/demos/vendor.d.ts.map +1 -1
  47. package/dist/demos/vendor.js +6 -2
  48. package/dist/demos/vendor.js.map +1 -1
  49. package/dist/demos/worker/compile.worker.js +3 -22
  50. package/dist/demos/worker/compile.worker.js.map +1 -1
  51. package/dist/demos/worker/compileVue.worker.d.ts +2 -0
  52. package/dist/demos/worker/compileVue.worker.d.ts.map +1 -0
  53. package/dist/demos/worker/compileVue.worker.js +11 -0
  54. package/dist/demos/worker/compileVue.worker.js.map +1 -0
  55. package/dist/demos/worker/start.d.ts +7 -0
  56. package/dist/demos/worker/start.d.ts.map +1 -0
  57. package/dist/demos/worker/start.js +27 -0
  58. package/dist/demos/worker/start.js.map +1 -0
  59. package/dist/fork/codesandbox.d.ts +19 -1
  60. package/dist/fork/codesandbox.d.ts.map +1 -1
  61. package/dist/fork/codesandbox.js +35 -22
  62. package/dist/fork/codesandbox.js.map +1 -1
  63. package/dist/fork/index.d.ts +30 -0
  64. package/dist/fork/index.d.ts.map +1 -1
  65. package/dist/fork/index.js +37 -0
  66. package/dist/fork/index.js.map +1 -1
  67. package/dist/fork/stackblitz.d.ts +18 -0
  68. package/dist/fork/stackblitz.d.ts.map +1 -0
  69. package/dist/fork/stackblitz.js +98 -0
  70. package/dist/fork/stackblitz.js.map +1 -0
  71. package/dist/frameworks/index.d.ts +4 -0
  72. package/dist/frameworks/index.d.ts.map +1 -0
  73. package/dist/frameworks/index.js +4 -0
  74. package/dist/frameworks/index.js.map +1 -0
  75. package/dist/frameworks/preference.d.ts +10 -0
  76. package/dist/frameworks/preference.d.ts.map +1 -0
  77. package/dist/frameworks/preference.js +34 -0
  78. package/dist/frameworks/preference.js.map +1 -0
  79. package/dist/frameworks/react/FrameworkBanner.d.ts +34 -0
  80. package/dist/frameworks/react/FrameworkBanner.d.ts.map +1 -0
  81. package/dist/frameworks/react/FrameworkBanner.js +50 -0
  82. package/dist/frameworks/react/FrameworkBanner.js.map +1 -0
  83. package/dist/frameworks/react/FrameworkContent.d.ts +21 -0
  84. package/dist/frameworks/react/FrameworkContent.d.ts.map +1 -0
  85. package/dist/frameworks/react/FrameworkContent.js +25 -0
  86. package/dist/frameworks/react/FrameworkContent.js.map +1 -0
  87. package/dist/frameworks/react/FrameworkLinks.d.ts +16 -0
  88. package/dist/frameworks/react/FrameworkLinks.d.ts.map +1 -0
  89. package/dist/frameworks/react/FrameworkLinks.js +50 -0
  90. package/dist/frameworks/react/FrameworkLinks.js.map +1 -0
  91. package/dist/frameworks/react/FrameworkSwitcher.d.ts +27 -0
  92. package/dist/frameworks/react/FrameworkSwitcher.d.ts.map +1 -0
  93. package/dist/frameworks/react/FrameworkSwitcher.js +42 -0
  94. package/dist/frameworks/react/FrameworkSwitcher.js.map +1 -0
  95. package/dist/frameworks/react/index.d.ts +6 -0
  96. package/dist/frameworks/react/index.d.ts.map +1 -0
  97. package/dist/frameworks/react/index.js +6 -0
  98. package/dist/frameworks/react/index.js.map +1 -0
  99. package/dist/frameworks/react/useFrameworkPreference.d.ts +32 -0
  100. package/dist/frameworks/react/useFrameworkPreference.d.ts.map +1 -0
  101. package/dist/frameworks/react/useFrameworkPreference.js +45 -0
  102. package/dist/frameworks/react/useFrameworkPreference.js.map +1 -0
  103. package/dist/frameworks/routeTree.d.ts +24 -0
  104. package/dist/frameworks/routeTree.d.ts.map +1 -0
  105. package/dist/frameworks/routeTree.js +31 -0
  106. package/dist/frameworks/routeTree.js.map +1 -0
  107. package/dist/frameworks/routing.d.ts +105 -0
  108. package/dist/frameworks/routing.d.ts.map +1 -0
  109. package/dist/frameworks/routing.js +142 -0
  110. package/dist/frameworks/routing.js.map +1 -0
  111. package/dist/frameworks/styles.css +104 -0
  112. package/dist/react/Demo.d.ts +12 -0
  113. package/dist/react/Demo.d.ts.map +1 -1
  114. package/dist/react/Demo.js +10 -4
  115. package/dist/react/Demo.js.map +1 -1
  116. package/dist/react/DemoShell.d.ts +5 -1
  117. package/dist/react/DemoShell.d.ts.map +1 -1
  118. package/dist/react/DemoShell.js +9 -6
  119. package/dist/react/DemoShell.js.map +1 -1
  120. package/dist/react/editor.d.ts.map +1 -1
  121. package/dist/react/editor.js +3 -0
  122. package/dist/react/editor.js.map +1 -1
  123. package/dist/react/fork.d.ts +4 -3
  124. package/dist/react/fork.d.ts.map +1 -1
  125. package/dist/react/fork.js +8 -6
  126. package/dist/react/fork.js.map +1 -1
  127. package/dist/react/styles.css +10 -0
  128. package/dist/remark/index.d.ts +2 -0
  129. package/dist/remark/index.d.ts.map +1 -1
  130. package/dist/remark/index.js +2 -0
  131. package/dist/remark/index.js.map +1 -1
  132. package/dist/remark/remarkDemoFences.d.ts +13 -0
  133. package/dist/remark/remarkDemoFences.d.ts.map +1 -1
  134. package/dist/remark/remarkDemoFences.js +48 -4
  135. package/dist/remark/remarkDemoFences.js.map +1 -1
  136. package/dist/remark/remarkFrameworkLinks.d.ts +36 -0
  137. package/dist/remark/remarkFrameworkLinks.d.ts.map +1 -0
  138. package/dist/remark/remarkFrameworkLinks.js +77 -0
  139. package/dist/remark/remarkFrameworkLinks.js.map +1 -0
  140. package/dist/remark/remarkFrameworkText.d.ts +16 -0
  141. package/dist/remark/remarkFrameworkText.d.ts.map +1 -0
  142. package/dist/remark/remarkFrameworkText.js +39 -0
  143. package/dist/remark/remarkFrameworkText.js.map +1 -0
  144. package/package.json +29 -4
  145. package/src/code/demoFiles.ts +2 -2
  146. package/src/code/index.ts +1 -0
  147. package/src/code/regions.ts +14 -8
  148. package/src/code/vueBlocks.ts +25 -0
  149. package/src/demos/build.ts +293 -99
  150. package/src/demos/compile/core.ts +27 -7
  151. package/src/demos/compile/vue.ts +259 -0
  152. package/src/demos/config.ts +59 -7
  153. package/src/demos/index.ts +13 -0
  154. package/src/demos/pages.ts +4 -2
  155. package/src/demos/runtime/vue.ts +17 -0
  156. package/src/demos/vendor.ts +6 -2
  157. package/src/demos/worker/compile.worker.ts +3 -30
  158. package/src/demos/worker/compileVue.worker.ts +13 -0
  159. package/src/demos/worker/start.ts +35 -0
  160. package/src/fork/codesandbox.ts +51 -24
  161. package/src/fork/index.ts +56 -0
  162. package/src/fork/stackblitz.ts +108 -0
  163. package/src/frameworks/index.ts +21 -0
  164. package/src/frameworks/preference.ts +35 -0
  165. package/src/frameworks/react/FrameworkBanner.tsx +112 -0
  166. package/src/frameworks/react/FrameworkContent.tsx +33 -0
  167. package/src/frameworks/react/FrameworkLinks.tsx +52 -0
  168. package/src/frameworks/react/FrameworkSwitcher.tsx +78 -0
  169. package/src/frameworks/react/index.ts +10 -0
  170. package/src/frameworks/react/useFrameworkPreference.ts +91 -0
  171. package/src/frameworks/routeTree.ts +54 -0
  172. package/src/frameworks/routing.ts +194 -0
  173. package/src/frameworks/styles.css +104 -0
  174. package/src/react/Demo.tsx +21 -2
  175. package/src/react/DemoShell.tsx +15 -7
  176. package/src/react/editor.ts +2 -0
  177. package/src/react/fork.ts +14 -6
  178. package/src/react/styles.css +10 -0
  179. package/src/remark/index.ts +6 -0
  180. package/src/remark/remarkDemoFences.ts +58 -3
  181. package/src/remark/remarkFrameworkLinks.ts +96 -0
  182. package/src/remark/remarkFrameworkText.ts +44 -0
@@ -0,0 +1,10 @@
1
+ export { createFrameworkContent, type FrameworkContentProps } from './FrameworkContent.tsx';
2
+ export { FrameworkBanner, type FrameworkBannerLabels, type FrameworkBannerProps } from './FrameworkBanner.tsx';
3
+ export { FrameworkLinks, type FrameworkLinksProps } from './FrameworkLinks.tsx';
4
+ export { FrameworkSwitcher, type FrameworkSwitcherProps } from './FrameworkSwitcher.tsx';
5
+ export {
6
+ EXPLICIT_LINK_ATTRIBUTE,
7
+ useFrameworkPreference,
8
+ useFrameworks,
9
+ type FrameworkProps,
10
+ } from './useFrameworkPreference.ts';
@@ -0,0 +1,91 @@
1
+ 'use client';
2
+
3
+ import { useCallback, useMemo, useSyncExternalStore } from 'react';
4
+
5
+ import {
6
+ FRAMEWORK_CHANGE_EVENT,
7
+ frameworkStorageKey,
8
+ readFrameworkPreference,
9
+ writeFrameworkPreference,
10
+ } from '../preference.ts';
11
+ import {
12
+ createHasPage,
13
+ defineFrameworks,
14
+ type Frameworks,
15
+ type FrameworksConfig,
16
+ type HasPage,
17
+ } from '../routing.ts';
18
+
19
+ /** What every framework component needs; plain data, so a server component can pass it down. */
20
+ export type FrameworkProps<Id extends string = string> = {
21
+ config: FrameworksConfig<Id>;
22
+ /**
23
+ * Neutral paths of the pages each framework has. A framework without a
24
+ * list has every page (usually the default one).
25
+ */
26
+ pages: Partial<Record<Id, readonly string[]>>;
27
+ };
28
+
29
+ export function useFrameworks<Id extends string>(props: FrameworkProps<Id>): {
30
+ frameworks: Frameworks<Id>;
31
+ hasPage: HasPage<Id>;
32
+ } {
33
+ const { config, pages } = props;
34
+ return useMemo(() => ({ frameworks: defineFrameworks(config), hasPage: createHasPage(pages) }), [config, pages]);
35
+ }
36
+
37
+ /**
38
+ * The visitor's stored framework and a setter. `null` during server
39
+ * rendering and hydration, and when nothing is stored.
40
+ */
41
+ export function useFrameworkPreference<Id extends string>(
42
+ frameworks: Frameworks<Id>,
43
+ ): [preference: Id | null, setPreference: (framework: Id | null) => void] {
44
+ const subscribe = useCallback(
45
+ (onChange: () => void) => {
46
+ const onStorage = (event: StorageEvent) => {
47
+ if (event.key == null || event.key === frameworkStorageKey(frameworks)) onChange();
48
+ };
49
+ window.addEventListener('storage', onStorage);
50
+ window.addEventListener(FRAMEWORK_CHANGE_EVENT, onChange);
51
+ return () => {
52
+ window.removeEventListener('storage', onStorage);
53
+ window.removeEventListener(FRAMEWORK_CHANGE_EVENT, onChange);
54
+ };
55
+ },
56
+ [frameworks],
57
+ );
58
+ const preference = useSyncExternalStore(
59
+ subscribe,
60
+ () => readFrameworkPreference(frameworks),
61
+ () => null,
62
+ );
63
+ const setPreference = useCallback(
64
+ (framework: Id | null) => writeFrameworkPreference(frameworks, framework),
65
+ [frameworks],
66
+ );
67
+ return [preference, setPreference];
68
+ }
69
+
70
+ /** The page's path: the prop when given (routers know it during server rendering), else `location.pathname`. */
71
+ export function usePagePath(pathname: string | null | undefined): string | null {
72
+ const fromLocation = useSyncExternalStore(
73
+ subscribeToLocation,
74
+ () => window.location.pathname,
75
+ () => null,
76
+ );
77
+ return pathname ?? fromLocation;
78
+ }
79
+
80
+ function subscribeToLocation(onChange: () => void) {
81
+ window.addEventListener('popstate', onChange);
82
+ return () => window.removeEventListener('popstate', onChange);
83
+ }
84
+
85
+ /** Marks links the visitor's preference must not rewrite (the switcher, the banner). */
86
+ export const EXPLICIT_LINK_ATTRIBUTE = 'data-framework-explicit';
87
+
88
+ /** A plain left click, without modifier keys: the only clicks the components take over. */
89
+ export function isPlainClick(event: { button: number; metaKey: boolean; ctrlKey: boolean; shiftKey: boolean; altKey: boolean }) {
90
+ return event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
91
+ }
@@ -0,0 +1,54 @@
1
+ import { resolveFrameworkLink, type Frameworks, type HasPage } from './routing.ts';
2
+
3
+ /** A sidebar entry: anything with an optional `path` and nested `routes`. */
4
+ export type RouteNode = { path?: string; routes?: RouteNode[] };
5
+
6
+ export type MapRouteTreeOptions<R extends RouteNode, Id extends string> = {
7
+ /**
8
+ * A page the framework doesn't have:
9
+ * - `fallback` (default): the entry stays and links to the framework that
10
+ * has it; `onFallback` can mark it (a badge).
11
+ * - `hide`: the entry is dropped, unless one of its children stays.
12
+ */
13
+ missing?: 'fallback' | 'hide';
14
+ /** Returns the entry to show for a fallback. Default: adds `fallbackFramework`. */
15
+ onFallback?: (route: R, fallbackFramework: Id) => R;
16
+ };
17
+
18
+ /**
19
+ * A sidebar tree written with neutral paths, for one framework: every path
20
+ * goes to that framework's page. Entries outside the framework roots are
21
+ * kept as they are; entries whose page exists nowhere are dropped.
22
+ */
23
+ export function mapRouteTree<R extends RouteNode, Id extends string>(
24
+ frameworks: Frameworks<Id>,
25
+ routes: readonly R[],
26
+ framework: Id,
27
+ hasPage: HasPage<Id>,
28
+ options: MapRouteTreeOptions<R, Id> = {},
29
+ ): R[] {
30
+ const { missing = 'fallback' } = options;
31
+ const onFallback =
32
+ options.onFallback ?? ((route: R, fallbackFramework: Id) => ({ ...route, fallbackFramework }) as R);
33
+
34
+ const mapRoute = (route: R): R | null => {
35
+ const children = route.routes ? (route.routes as R[]).map(mapRoute).filter((child): child is R => !!child) : undefined;
36
+ const withChildren = (mapped: R): R => (children ? { ...mapped, routes: children } : mapped);
37
+ if (route.path == null) return children && !children.length && route.routes?.length ? null : withChildren(route);
38
+
39
+ const link = resolveFrameworkLink(frameworks, route.path, framework, hasPage);
40
+ switch (link.kind) {
41
+ case 'shared':
42
+ return withChildren(route);
43
+ case 'page':
44
+ return withChildren({ ...route, path: link.href });
45
+ case 'fallback':
46
+ if (missing === 'hide' && !children?.length) return null;
47
+ return withChildren(onFallback({ ...route, path: link.href }, link.framework));
48
+ case 'missing':
49
+ return children?.length ? withChildren(route) : null;
50
+ }
51
+ };
52
+
53
+ return routes.map(mapRoute).filter((route): route is R => !!route);
54
+ }
@@ -0,0 +1,194 @@
1
+ /**
2
+ * Docs for more than one framework, one URL tree per framework.
3
+ *
4
+ * The default framework keeps its URLs (`/docs/...`); every other framework
5
+ * lives under a prefix (`/vue/docs/...`). Authors write the default form
6
+ * everywhere (the "neutral" path); the build maps it to the page's framework.
7
+ * Only paths under `roots` exist per framework, the rest of the site (blog,
8
+ * pricing) is shared.
9
+ *
10
+ * Pure logic: no React, no Node, no DOM. It runs in the build (remark plugin,
11
+ * sitemap) and in the browser (switcher, banner, link following).
12
+ */
13
+
14
+ export type FrameworkDefinition = {
15
+ /** Shown in the switcher, the banner and notices. */
16
+ label: string;
17
+ /** URL prefix of this framework's tree: `''` for the default one, `/vue` otherwise. */
18
+ prefix: string;
19
+ };
20
+
21
+ export type FrameworksConfig<Id extends string = string> = {
22
+ /** The framework whose URLs carry no prefix. */
23
+ default: Id;
24
+ frameworks: Record<Id, FrameworkDefinition>;
25
+ /** Path prefixes that exist once per framework, e.g. `['/docs']`. */
26
+ roots: string[];
27
+ /** `localStorage` key of the visitor's choice. Default `docs-framework`. */
28
+ storageKey?: string;
29
+ };
30
+
31
+ /** Does `neutralPath` (no trailing slash, no hash) have a page in `framework`? */
32
+ export type HasPage<Id extends string = string> = (neutralPath: string, framework: Id) => boolean;
33
+
34
+ export type Frameworks<Id extends string = string> = {
35
+ config: FrameworksConfig<Id>;
36
+ /** Default framework first. */
37
+ ids: Id[];
38
+ default: Id;
39
+ label(framework: Id): string;
40
+ /** The framework a URL path belongs to; `null` outside every root (a shared page). */
41
+ frameworkOf(href: string): Id | null;
42
+ /** The default framework's form of a path: `/vue/docs/x#y` → `/docs/x#y`. Shared paths are returned as they are. */
43
+ neutralPath(href: string): string;
44
+ /** A neutral path in a framework's tree: `/docs/x#y`, `vue` → `/vue/docs/x#y`. */
45
+ pathFor(neutralHref: string, framework: Id): string;
46
+ };
47
+
48
+ /** `/docs/x/?a=1#b` → `['/docs/x', '?a=1#b']`. The path loses its trailing slash. */
49
+ export function splitHref(href: string): [path: string, suffix: string] {
50
+ const at = href.search(/[?#]/);
51
+ const path = at === -1 ? href : href.slice(0, at);
52
+ const suffix = at === -1 ? '' : href.slice(at);
53
+ return [path.length > 1 ? path.replace(/\/+$/, '') : path, suffix];
54
+ }
55
+
56
+ const isUnder = (path: string, root: string) => path === root || path.startsWith(`${root}/`);
57
+
58
+ export function defineFrameworks<Id extends string>(config: FrameworksConfig<Id>): Frameworks<Id> {
59
+ const ids = [config.default, ...(Object.keys(config.frameworks) as Id[]).filter((id) => id !== config.default)];
60
+ const roots = config.roots.map((root) => root.replace(/\/+$/, ''));
61
+ const prefixed = ids
62
+ .filter((id) => id !== config.default)
63
+ .map((id) => ({ id, prefix: config.frameworks[id].prefix.replace(/\/+$/, '') }));
64
+ for (const { id, prefix } of prefixed) {
65
+ if (!prefix.startsWith('/')) {
66
+ throw new Error(`docs-kit: framework "${id}" needs a URL prefix like "/${id}" (only the default framework has none)`);
67
+ }
68
+ }
69
+
70
+ /** The framework and neutral path of a path, or null when it's shared. */
71
+ const locate = (path: string): { framework: Id; neutral: string } | null => {
72
+ for (const { id, prefix } of prefixed) {
73
+ if (!isUnder(path, prefix)) continue;
74
+ const rest = path.slice(prefix.length) || '/';
75
+ if (roots.some((root) => isUnder(rest, root))) return { framework: id, neutral: rest };
76
+ }
77
+ if (roots.some((root) => isUnder(path, root))) return { framework: config.default, neutral: path };
78
+ return null;
79
+ };
80
+
81
+ return {
82
+ config,
83
+ ids,
84
+ default: config.default,
85
+ label: (framework) => config.frameworks[framework].label,
86
+ frameworkOf(href) {
87
+ return locate(splitHref(href)[0])?.framework ?? null;
88
+ },
89
+ neutralPath(href) {
90
+ const [path, suffix] = splitHref(href);
91
+ const located = locate(path);
92
+ return located ? `${located.neutral}${suffix}` : href;
93
+ },
94
+ pathFor(neutralHref, framework) {
95
+ const [path, suffix] = splitHref(neutralHref);
96
+ const located = locate(path);
97
+ if (!located) return neutralHref;
98
+ const prefix = framework === config.default ? '' : config.frameworks[framework].prefix.replace(/\/+$/, '');
99
+ return `${prefix}${located.neutral}${suffix}`;
100
+ },
101
+ };
102
+ }
103
+
104
+ /**
105
+ * `HasPage` from lists of neutral paths per framework. A framework without a
106
+ * list has every page (the usual case for the default framework).
107
+ */
108
+ export function createHasPage<Id extends string>(pages: Partial<Record<Id, readonly string[]>>): HasPage<Id> {
109
+ const sets = new Map<string, Set<string>>();
110
+ for (const [framework, paths] of Object.entries(pages) as [Id, readonly string[]][]) {
111
+ sets.set(framework, new Set(paths.map((path) => splitHref(path)[0])));
112
+ }
113
+ return (neutralPath, framework) => sets.get(framework)?.has(splitHref(neutralPath)[0]) ?? true;
114
+ }
115
+
116
+ export type ResolvedLink<Id extends string = string> =
117
+ /** Outside the framework roots: the same URL for everyone. */
118
+ | { kind: 'shared'; href: string }
119
+ /** The page exists in the wanted framework. */
120
+ | { kind: 'page'; href: string; framework: Id }
121
+ /** It doesn't; `framework` is the one whose page the link goes to instead. */
122
+ | { kind: 'fallback'; href: string; framework: Id }
123
+ /** No framework has this page. */
124
+ | { kind: 'missing'; neutralPath: string };
125
+
126
+ /**
127
+ * Where a link written in the neutral form goes on a page of `framework`:
128
+ * that framework's page, else the default framework's, else any other's.
129
+ */
130
+ export function resolveFrameworkLink<Id extends string>(
131
+ frameworks: Frameworks<Id>,
132
+ href: string,
133
+ framework: Id,
134
+ hasPage: HasPage<Id>,
135
+ ): ResolvedLink<Id> {
136
+ if (frameworks.frameworkOf(href) == null) return { kind: 'shared', href };
137
+ const neutral = frameworks.neutralPath(href);
138
+ const [neutralPath] = splitHref(neutral);
139
+ if (hasPage(neutralPath, framework)) return { kind: 'page', href: frameworks.pathFor(neutral, framework), framework };
140
+ const other = frameworks.ids.find((id) => id !== framework && hasPage(neutralPath, id));
141
+ if (other) return { kind: 'fallback', href: frameworks.pathFor(neutral, other), framework: other };
142
+ return { kind: 'missing', neutralPath };
143
+ }
144
+
145
+ /**
146
+ * Where the switcher goes from `pathname` when the visitor picks `target`:
147
+ * the same page, or the nearest parent that exists in that framework (`exact`
148
+ * is then false). `null` on shared pages and when the framework has no page
149
+ * on the way up: the switcher then only stores the preference.
150
+ */
151
+ export function resolveSwitchTarget<Id extends string>(
152
+ frameworks: Frameworks<Id>,
153
+ pathname: string,
154
+ target: Id,
155
+ hasPage: HasPage<Id>,
156
+ ): { href: string; exact: boolean } | null {
157
+ if (frameworks.frameworkOf(pathname) == null) return null;
158
+ const [start] = splitHref(frameworks.neutralPath(pathname));
159
+ let path = start;
160
+ while (path && path !== '/') {
161
+ if (frameworks.frameworkOf(path) == null) break;
162
+ if (hasPage(path, target)) return { href: frameworks.pathFor(path, target), exact: path === start };
163
+ path = path.slice(0, path.lastIndexOf('/'));
164
+ }
165
+ return null;
166
+ }
167
+
168
+ /**
169
+ * Following the visitor's preference when they click a docs link. Returns the
170
+ * URL to go to instead, or `null` to leave the link alone.
171
+ *
172
+ * - With a stored preference, a link to another framework's page goes to the
173
+ * preferred framework when the page exists there.
174
+ * - Without one, a page of a non-default framework keeps the visitor in its
175
+ * tree: links in the default form (a shared header, a component that builds
176
+ * its own URL) go to that framework. Nothing else is rewritten.
177
+ */
178
+ export function resolveNavigation<Id extends string>(
179
+ frameworks: Frameworks<Id>,
180
+ options: { href: string; pagePath: string; preference: Id | null; hasPage: HasPage<Id> },
181
+ ): string | null {
182
+ const { href, pagePath, preference, hasPage } = options;
183
+ const linked = frameworks.frameworkOf(href);
184
+ if (linked == null) return null;
185
+ let wanted = preference;
186
+ if (wanted == null) {
187
+ const page = frameworks.frameworkOf(pagePath);
188
+ if (page == null || page === frameworks.default || linked !== frameworks.default) return null;
189
+ wanted = page;
190
+ }
191
+ if (linked === wanted) return null;
192
+ const neutral = frameworks.neutralPath(href);
193
+ return hasPage(splitHref(neutral)[0], wanted) ? frameworks.pathFor(neutral, wanted) : null;
194
+ }
@@ -0,0 +1,104 @@
1
+ /*
2
+ * docs-kit framework switcher, banner and fallback marks. Plain CSS on the
3
+ * same --dk-* custom properties as the demo cards (react/styles.css), with
4
+ * fallbacks, so this file also works on its own. Sites restyle by overriding
5
+ * the variables or any .dk-framework-* rule.
6
+ */
7
+ .dk-framework-switcher {
8
+ display: inline-flex;
9
+ padding: 2px;
10
+ gap: 2px;
11
+ border: 1px solid var(--dk-border, rgb(128 128 128 / 0.3));
12
+ border-radius: 999px;
13
+ font-family: var(--dk-font-sans, system-ui, sans-serif);
14
+ font-size: 13px;
15
+ line-height: 1.4;
16
+ }
17
+ .dk-framework-option {
18
+ all: unset;
19
+ box-sizing: border-box;
20
+ padding: 3px 12px;
21
+ border-radius: 999px;
22
+ color: var(--dk-muted, inherit);
23
+ cursor: pointer;
24
+ white-space: nowrap;
25
+ }
26
+ .dk-framework-option:hover {
27
+ color: var(--dk-fg, inherit);
28
+ }
29
+ .dk-framework-option:focus-visible {
30
+ outline: 2px solid var(--dk-accent, currentColor);
31
+ outline-offset: 1px;
32
+ }
33
+ .dk-framework-option--active {
34
+ background: var(--dk-accent-soft, rgb(128 128 128 / 0.2));
35
+ color: var(--dk-accent, inherit);
36
+ font-weight: 600;
37
+ }
38
+
39
+ .dk-framework-banner {
40
+ display: flex;
41
+ flex-wrap: wrap;
42
+ align-items: center;
43
+ gap: 6px 14px;
44
+ padding: 10px 14px;
45
+ border: 1px solid var(--dk-border, rgb(128 128 128 / 0.3));
46
+ border-radius: var(--dk-radius, 12px);
47
+ background: var(--dk-accent-soft, rgb(128 128 128 / 0.12));
48
+ color: var(--dk-fg, inherit);
49
+ font-family: var(--dk-font-sans, system-ui, sans-serif);
50
+ font-size: 14px;
51
+ line-height: 1.5;
52
+ }
53
+ .dk-framework-banner-text {
54
+ flex: 1 1 240px;
55
+ }
56
+ .dk-framework-banner-link {
57
+ color: var(--dk-accent, inherit);
58
+ font-weight: 600;
59
+ text-decoration: underline;
60
+ text-underline-offset: 3px;
61
+ }
62
+ .dk-framework-banner-action,
63
+ .dk-framework-banner-dismiss {
64
+ all: unset;
65
+ cursor: pointer;
66
+ color: var(--dk-muted, inherit);
67
+ }
68
+ .dk-framework-banner-action:hover,
69
+ .dk-framework-banner-dismiss:hover {
70
+ color: var(--dk-fg, inherit);
71
+ }
72
+ .dk-framework-banner-action:focus-visible,
73
+ .dk-framework-banner-dismiss:focus-visible,
74
+ .dk-framework-banner-link:focus-visible {
75
+ outline: 2px solid var(--dk-accent, currentColor);
76
+ outline-offset: 2px;
77
+ }
78
+ .dk-framework-banner-dismiss {
79
+ padding: 0 4px;
80
+ font-size: 18px;
81
+ line-height: 1;
82
+ }
83
+
84
+ /*
85
+ * A link whose page doesn't exist for the page's framework (set by
86
+ * remarkFrameworkLinks). The label comes from the site:
87
+ * :root { --dk-framework-fallback-label: 'React only for now'; }
88
+ */
89
+ a[data-framework-fallback]::after {
90
+ content: var(--dk-framework-fallback-label, attr(data-framework-fallback));
91
+ display: inline-block;
92
+ margin-left: 6px;
93
+ padding: 0 6px;
94
+ border: 1px solid var(--dk-border, rgb(128 128 128 / 0.3));
95
+ border-radius: 999px;
96
+ color: var(--dk-muted, inherit);
97
+ font-family: var(--dk-font-sans, system-ui, sans-serif);
98
+ font-size: 0.72em;
99
+ font-weight: 400;
100
+ line-height: 1.6;
101
+ text-decoration: none;
102
+ vertical-align: middle;
103
+ white-space: nowrap;
104
+ }
@@ -8,6 +8,7 @@ import { DEMO_HEIGHTS, parseDemoHeight, type DemoHeights } from '../code/heights
8
8
  import { parseLineRanges } from '../code/lineRanges.ts';
9
9
  import { applySourceReplacements, extractCodeMarkers, sliceRegion, stripCodeMarkers } from '../code/regions.ts';
10
10
  import { highlightCode, langForFile, type CodeThemes } from '../code/shiki.ts';
11
+ import { vueBlockLang } from '../code/vueBlocks.ts';
11
12
  import type { DemoManifest } from '../demos/config.ts';
12
13
  import { slugifyDemoTitle } from '../demos/slug.ts';
13
14
  import { DemoShell, type DemoShellFile } from './DemoShell.tsx';
@@ -28,6 +29,13 @@ export type DemoContext = {
28
29
  * with heading ids. Must match the builder's `anchorPrefix`. Default `''`.
29
30
  */
30
31
  anchorPrefix?: string;
32
+ /**
33
+ * For a page in another framework than its fences name (`siblings` in the
34
+ * remark plugin): a fence without a sibling file falls back to the manifest
35
+ * of the framework it was written for, and its card shows `notice`
36
+ * (e.g. "React only for now").
37
+ */
38
+ fallback?: { manifest: string | DemoManifest; notice?: ReactNode };
31
39
  };
32
40
 
33
41
  export type DemoProps = {
@@ -57,6 +65,8 @@ export type DemoProps = {
57
65
  lines?: string | boolean;
58
66
  /** Original file line numbers (`"12-14,16"`) of a `region` snippet. */
59
67
  originalLines?: string;
68
+ /** `true`: no sibling file for the page's framework (set by the remark plugin). */
69
+ fallback?: string;
60
70
  /** `<DemoTitle>` / `<DemoDescription>`. */
61
71
  children?: ReactNode;
62
72
  };
@@ -138,6 +148,8 @@ export async function Demo(props: DemoProps & { context: DemoContext }) {
138
148
  const parsedLines = typeof props.originalLines === 'string' ? parseLineRanges(props.originalLines) : [];
139
149
  const originalLines = parsedLines.length ? parsedLines : undefined;
140
150
  const themes = context.themes;
151
+ const isFallback = props.fallback === 'true';
152
+ const notice = isFallback ? context.fallback?.notice : undefined;
141
153
 
142
154
  if (!props.name) {
143
155
  if (typeof props.code !== 'string') {
@@ -163,11 +175,12 @@ export async function Demo(props: DemoProps & { context: DemoContext }) {
163
175
  slug={explicitTitle ? `${context.anchorPrefix ?? ''}${slugifyDemoTitle(explicitTitle)}` : ''}
164
176
  files={[{ name: props.codeTitle || '', path: '', rawCode, html }]}
165
177
  header={props.title || extractDemoTitle(children) ? resolveHeader(children, props.title) : children}
178
+ notice={notice}
166
179
  />
167
180
  );
168
181
  }
169
182
 
170
- const manifest = readManifest(context.manifest);
183
+ const manifest = readManifest((isFallback && context.fallback?.manifest) || context.manifest);
171
184
  // `name` is relative to the page, or to the content root when it starts with `/`
172
185
  const demoId = path.posix.normalize(
173
186
  props.name.startsWith('/') ? props.name.slice(1) : folder ? `${folder}/${props.name}` : props.name,
@@ -203,7 +216,11 @@ export async function Demo(props: DemoProps & { context: DemoContext }) {
203
216
  const fullCode = stripCodeMarkers(fullSource);
204
217
  const copyCode = sliced ? stripCodeMarkers(sliced.source) : fullCode;
205
218
  const html = await highlightCode(marked.source, {
206
- lang: langForFile(filePath),
219
+ // a region of a Vue component is highlighted as its block (script, template, style)
220
+ lang:
221
+ sliced && filePath.endsWith('.vue')
222
+ ? vueBlockLang(fullSource, sliced.originalLines[0] ?? 1)
223
+ : langForFile(filePath),
207
224
  themes,
208
225
  highlight: marked.highlight,
209
226
  lineNumbers: showLines ? (sliced ? marked.originalLines : true) : null,
@@ -235,6 +252,8 @@ export async function Demo(props: DemoProps & { context: DemoContext }) {
235
252
  header={resolveHeader(children, props.title)}
236
253
  editor={editable ? manifest.editor : undefined}
237
254
  fork={manifest.fork}
255
+ framework={manifest.framework}
256
+ notice={notice}
238
257
  devEvents={manifest.devEvents}
239
258
  />
240
259
  );
@@ -4,10 +4,11 @@ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, typ
4
4
  import { createPortal } from 'react-dom';
5
5
 
6
6
  import type { DemoHeight, DemoHeights } from '../code/heights.ts';
7
- import type { ForkConfig } from '../demos/config.ts';
7
+ import type { DemoFramework, ForkConfig } from '../demos/config.ts';
8
8
  import type { CompileOptions, Compiler, CompilerConfig } from '../demos/client.ts';
9
9
  import { DemoIframe, type DemoIframeHandle } from './DemoIframe.tsx';
10
- import { forkInCodeSandbox } from './fork.ts';
10
+ import { FORK_TARGETS } from '../fork/index.ts';
11
+ import { forkDemo } from './fork.ts';
11
12
 
12
13
  export type DemoShellFile = {
13
14
  /** Tab name: path relative to the demo entry's folder. */
@@ -40,6 +41,10 @@ export type DemoShellProps = {
40
41
  /** Present when the demo can be edited. */
41
42
  editor?: { compiler: CompilerConfig; options: CompileOptions };
42
43
  fork?: ForkConfig;
44
+ /** The demo's framework: picks the fork template. Default `react`. */
45
+ framework?: DemoFramework;
46
+ /** Shown in the toolbar, e.g. "React only for now" on a demo with no version for the page's framework. */
47
+ notice?: ReactNode;
43
48
  /** Dev-only SSE endpoint (`:port/path`). */
44
49
  devEvents?: string;
45
50
  };
@@ -73,7 +78,7 @@ type CompileStatus = 'idle' | 'compiling' | 'ok' | 'error';
73
78
  * to the preview, rebuilt in the browser on every change.
74
79
  */
75
80
  export function DemoShell(props: DemoShellProps) {
76
- const { demoUrl, height, heights, initialTab, title, slug, files, hideFiles, header, editor } = props;
81
+ const { demoUrl, height, heights, initialTab, title, slug, files, hideFiles, header, editor, notice } = props;
77
82
  const [tab, setTab] = useState<'preview' | 'code'>(demoUrl ? (initialTab ?? 'preview') : 'code');
78
83
  const [activeFile, setActiveFile] = useState(0);
79
84
  const [copied, setCopied] = useState(false);
@@ -263,17 +268,19 @@ export function DemoShell(props: DemoShellProps) {
263
268
  };
264
269
  }, [overlay, closeOverlay]);
265
270
 
271
+ const forkTarget = FORK_TARGETS[props.framework ?? 'react'].name;
266
272
  const fork = () =>
267
- forkInCodeSandbox({
273
+ forkDemo({
268
274
  title,
269
275
  entry: files[0].path,
270
276
  files: files.map((file) => ({ path: file.path, content: edits[file.path] ?? originalByPath[file.path] })),
271
277
  config: props.fork,
278
+ framework: props.framework,
272
279
  });
273
280
 
274
281
  const showFileTabs = !hideFiles && files.length > 1 && (tab === 'code' || editing);
275
282
  // a plain snippet: no title, no file name — just the code and a floating copy button
276
- const bare = !demoUrl && !header && !files[0].name;
283
+ const bare = !demoUrl && !header && !files[0].name && !notice;
277
284
  const codeVisible = editing || tab === 'code';
278
285
  const previewVisible = demoUrl && (editing || tab === 'preview') && !overlay;
279
286
 
@@ -333,6 +340,7 @@ export function DemoShell(props: DemoShellProps) {
333
340
  ) : !hideFiles && files[0].name && (tab === 'code' || editing) ? (
334
341
  <span className="dk-demo-filename">{files[0].name}</span>
335
342
  ) : null}
343
+ {notice ? <span className="dk-demo-notice">{notice}</span> : null}
336
344
  <span className="dk-demo-spacer" />
337
345
  {editing ? (
338
346
  <>
@@ -342,7 +350,7 @@ export function DemoShell(props: DemoShellProps) {
342
350
  reset<ResetIcon />
343
351
  </ToolbarButton>
344
352
  ) : null}
345
- <ToolbarButton title={`Fork “${title}” in CodeSandbox (with your changes)`} onClick={fork}>
353
+ <ToolbarButton title={`Fork “${title}” in ${forkTarget} (with your changes)`} onClick={fork}>
346
354
  fork<ForkIcon />
347
355
  </ToolbarButton>
348
356
  <ToolbarButton title="Stop editing (your changes stay until you reset or leave the page)" onClick={() => setEditing(false)}>
@@ -379,7 +387,7 @@ export function DemoShell(props: DemoShellProps) {
379
387
  >
380
388
  reset<ResetIcon />
381
389
  </ToolbarButton>
382
- <ToolbarButton title={`Fork “${title}” in CodeSandbox`} onClick={fork}>
390
+ <ToolbarButton title={`Fork “${title}” in ${forkTarget}`} onClick={fork}>
383
391
  fork<ForkIcon />
384
392
  </ToolbarButton>
385
393
  <OpenDemoLink demoUrl={demoUrl!} title={title} />
@@ -11,6 +11,7 @@ import { autocompletion, closeBrackets, closeBracketsKeymap } from '@codemirror/
11
11
  import { defaultKeymap, history, historyKeymap, indentWithTab } from '@codemirror/commands';
12
12
  import { css } from '@codemirror/lang-css';
13
13
  import { javascript } from '@codemirror/lang-javascript';
14
+ import { vue } from '@codemirror/lang-vue';
14
15
  import {
15
16
  bracketMatching,
16
17
  HighlightStyle,
@@ -138,6 +139,7 @@ export const editorHighlightStyle = HighlightStyle.define([
138
139
 
139
140
  function languageFor(fileName: string): Extension {
140
141
  if (/\.css$/.test(fileName)) return css();
142
+ if (/\.vue$/.test(fileName)) return vue();
141
143
  const ts = /\.[cm]?tsx?$/.test(fileName);
142
144
  const jsx = /x$/.test(fileName) || !/\.[cm]?[jt]s$/.test(fileName);
143
145
  return javascript({ typescript: ts, jsx });
package/src/react/fork.ts CHANGED
@@ -1,10 +1,17 @@
1
1
  import type { ForkConfig } from '../demos/config.ts';
2
- import { codeSandboxForm, type ForkFile } from '../fork/codesandbox.ts';
2
+ import { forkForm, resolveForkSettings, type ForkFile, type ForkFramework } from '../fork/index.ts';
3
3
 
4
- /** Posts the demo (with any edits) to CodeSandbox's define API in a new tab. */
5
- export function forkInCodeSandbox(options: { title: string; entry: string; files: ForkFile[]; config?: ForkConfig }) {
6
- const { config = {} } = options;
7
- const form = codeSandboxForm(options.files, {
4
+ /** Posts the demo (with any edits) to its fork target (CodeSandbox, or StackBlitz for Vue) in a new tab. */
5
+ export function forkDemo(options: {
6
+ title: string;
7
+ entry: string;
8
+ files: ForkFile[];
9
+ config?: ForkConfig;
10
+ framework?: ForkFramework;
11
+ }) {
12
+ const config = resolveForkSettings(options.config ?? {}, options.entry);
13
+ const form = forkForm(options.files, {
14
+ framework: options.framework,
8
15
  title: options.title,
9
16
  entry: options.entry,
10
17
  dependencies: config.dependencies,
@@ -12,13 +19,14 @@ export function forkInCodeSandbox(options: { title: string; entry: string; files
12
19
  entryPrelude: config.entryPrelude,
13
20
  styles: config.styles,
14
21
  sourceReplacements: config.sourceReplacements,
22
+ indexHtmlHead: config.indexHtmlHead,
15
23
  });
16
24
  const el = document.createElement('form');
17
25
  el.action = form.action;
18
26
  el.method = 'POST';
19
27
  el.target = '_blank';
20
28
  el.style.display = 'none';
21
- for (const [name, value] of Object.entries({ parameters: form.parameters, query: form.query })) {
29
+ for (const [name, value] of Object.entries(form.fields)) {
22
30
  const input = document.createElement('input');
23
31
  input.type = 'hidden';
24
32
  input.name = name;