@rokkit/stories 1.0.0-next.132 → 1.0.0-next.134
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.
- package/LICENSE +21 -0
- package/README.md +169 -0
- package/package.json +9 -2
- package/src/lib/shiki.js +1 -1
- package/src/Code.svelte +0 -21
- package/src/CodeViewer.svelte +0 -16
- package/src/CopyToClipboard.svelte +0 -26
- package/src/Notes.svelte +0 -57
- package/src/Preview.svelte +0 -10
- package/src/lib/StoryViewer.svelte +0 -16
- package/tsconfig.build.json +0 -11
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Jerry Thomas
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# @rokkit/stories
|
|
2
|
+
|
|
3
|
+
Utilities for building interactive code stories and tutorials in SvelteKit — file fetching, metadata parsing, section navigation, and syntax-highlighted code display.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
bun add @rokkit/stories
|
|
9
|
+
# or
|
|
10
|
+
npm install @rokkit/stories
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Overview
|
|
14
|
+
|
|
15
|
+
`@rokkit/stories` is used to build interactive documentation pages where each "story" pairs a live Svelte component preview with its source files. It handles:
|
|
16
|
+
|
|
17
|
+
- Loading and grouping source files via Vite's `import.meta.glob`
|
|
18
|
+
- Parsing metadata (title, description, category, order) from story modules
|
|
19
|
+
- Navigating stories by section and slug
|
|
20
|
+
- Rendering syntax-highlighted code via Shiki
|
|
21
|
+
- Displaying a live preview alongside the highlighted source
|
|
22
|
+
|
|
23
|
+
## Usage
|
|
24
|
+
|
|
25
|
+
### Loading stories in a SvelteKit route
|
|
26
|
+
|
|
27
|
+
```js
|
|
28
|
+
// src/routes/stories/[slug]/+page.js
|
|
29
|
+
import { fetchStories, getAllSections, findSection } from '@rokkit/stories'
|
|
30
|
+
|
|
31
|
+
const sources = import.meta.glob('/src/stories/**/+page.svelte', { as: 'raw', eager: false })
|
|
32
|
+
const modules = import.meta.glob('/src/stories/**/meta.js')
|
|
33
|
+
|
|
34
|
+
export async function load({ params }) {
|
|
35
|
+
const stories = await fetchStories(sources, modules)
|
|
36
|
+
const sections = getAllSections()
|
|
37
|
+
const section = findSection(sections, params.slug)
|
|
38
|
+
|
|
39
|
+
return { stories, sections, section }
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### Rendering a story
|
|
44
|
+
|
|
45
|
+
```svelte
|
|
46
|
+
<!-- src/routes/stories/[slug]/+page.svelte -->
|
|
47
|
+
<script>
|
|
48
|
+
import { StoryViewer } from '@rokkit/stories'
|
|
49
|
+
|
|
50
|
+
let { data } = $props()
|
|
51
|
+
</script>
|
|
52
|
+
|
|
53
|
+
<StoryViewer App={data.section.App} files={data.section.files} />
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`StoryViewer` renders a split view: the live component preview on the left, syntax-highlighted source files on the right.
|
|
57
|
+
|
|
58
|
+
### Working with sections and metadata
|
|
59
|
+
|
|
60
|
+
```js
|
|
61
|
+
import {
|
|
62
|
+
fetchImports,
|
|
63
|
+
getSlug,
|
|
64
|
+
getSections,
|
|
65
|
+
groupFiles,
|
|
66
|
+
findSection,
|
|
67
|
+
findGroupForSection
|
|
68
|
+
} from '@rokkit/stories'
|
|
69
|
+
|
|
70
|
+
// Fetch raw source file contents
|
|
71
|
+
const files = await fetchImports(import.meta.glob('./examples/**', { as: 'raw' }))
|
|
72
|
+
|
|
73
|
+
// Group files by their parent folder
|
|
74
|
+
const grouped = groupFiles(files)
|
|
75
|
+
|
|
76
|
+
// Build a navigation tree from story metadata
|
|
77
|
+
const sections = getSections(metadata)
|
|
78
|
+
|
|
79
|
+
// Look up a section by URL slug
|
|
80
|
+
const current = findSection(sections, 'getting-started')
|
|
81
|
+
|
|
82
|
+
// Find which nav group a section belongs to
|
|
83
|
+
const group = findGroupForSection(sections, current.id)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Syntax highlighting
|
|
87
|
+
|
|
88
|
+
```js
|
|
89
|
+
import { highlightCode, preloadHighlighter } from '@rokkit/stories'
|
|
90
|
+
|
|
91
|
+
// Warm the highlighter (call once on app start to avoid first-render delay)
|
|
92
|
+
await preloadHighlighter()
|
|
93
|
+
|
|
94
|
+
// Highlight a code string
|
|
95
|
+
const html = await highlightCode('const x = 1', {
|
|
96
|
+
lang: 'javascript',
|
|
97
|
+
theme: 'github-light' // or 'github-dark'
|
|
98
|
+
})
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Supported languages: `svelte`, `javascript`, `typescript`, `css`, `html`, `json`, `bash`, `shell`.
|
|
102
|
+
|
|
103
|
+
## API
|
|
104
|
+
|
|
105
|
+
### Components
|
|
106
|
+
|
|
107
|
+
| Export | Description |
|
|
108
|
+
| ------------- | -------------------------------------------------------------------------------------------- |
|
|
109
|
+
| `StoryViewer` | Renders a live preview (`App` prop) alongside syntax-highlighted source files (`files` prop) |
|
|
110
|
+
| `CodeViewer` | Tabbed code viewer with syntax highlighting |
|
|
111
|
+
| `Preview` | Isolated preview container for a live component |
|
|
112
|
+
| `Notes` | Prose content area for story narrative text |
|
|
113
|
+
|
|
114
|
+
### Story utilities (`@rokkit/stories`)
|
|
115
|
+
|
|
116
|
+
| Export | Description |
|
|
117
|
+
| ----------------------------------- | ------------------------------------------------------------- |
|
|
118
|
+
| `fetchImports(sources)` | Resolve `import.meta.glob` entries into `File[]` objects |
|
|
119
|
+
| `fetchStories(sources, modules)` | Combine source files and metadata modules into stories |
|
|
120
|
+
| `getSlug(file)` | Derive a URL slug from a file path |
|
|
121
|
+
| `getSections(metadata)` | Build a hierarchical section list from metadata objects |
|
|
122
|
+
| `groupFiles(files)` | Group `File[]` by parent folder name |
|
|
123
|
+
| `getAllSections()` | Return the full section list (populated after `fetchStories`) |
|
|
124
|
+
| `findSection(sections, slug)` | Look up a section by slug |
|
|
125
|
+
| `findGroupForSection(sections, id)` | Find the nav group that contains a section |
|
|
126
|
+
|
|
127
|
+
### Shiki utilities
|
|
128
|
+
|
|
129
|
+
| Export | Description |
|
|
130
|
+
| ------------------------------ | ------------------------------------------------------ |
|
|
131
|
+
| `highlightCode(code, options)` | Highlight a code string; returns HTML string |
|
|
132
|
+
| `preloadHighlighter()` | Warm the Shiki highlighter to avoid cold-start latency |
|
|
133
|
+
|
|
134
|
+
### Types
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
type File = {
|
|
138
|
+
file: string
|
|
139
|
+
group?: string
|
|
140
|
+
name: string
|
|
141
|
+
language: string
|
|
142
|
+
content: string | object
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
type Metadata = {
|
|
146
|
+
title: string
|
|
147
|
+
description: string
|
|
148
|
+
category: string
|
|
149
|
+
tags: string[]
|
|
150
|
+
depth: number
|
|
151
|
+
order: number
|
|
152
|
+
children?: Metadata[]
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
type Story = {
|
|
156
|
+
files: File[]
|
|
157
|
+
App?: SvelteComponent
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## Dependencies
|
|
162
|
+
|
|
163
|
+
- `shiki` — syntax highlighting
|
|
164
|
+
- `frontmatter` — metadata parsing
|
|
165
|
+
- `@rokkit/core` — shared utilities
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
Part of [Rokkit](https://github.com/jerrythomas/rokkit) — a Svelte 5 component library and design system.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rokkit/stories",
|
|
3
|
-
"version": "1.0.0-next.
|
|
3
|
+
"version": "1.0.0-next.134",
|
|
4
4
|
"description": "Utilities for building tutorials.",
|
|
5
5
|
"publishConfig": {
|
|
6
6
|
"access": "public"
|
|
@@ -22,8 +22,15 @@
|
|
|
22
22
|
"import": "./src/index.js"
|
|
23
23
|
}
|
|
24
24
|
},
|
|
25
|
+
"files": [
|
|
26
|
+
"src/**/*.js",
|
|
27
|
+
"dist/**/*.d.ts",
|
|
28
|
+
"README.md",
|
|
29
|
+
"LICENSE"
|
|
30
|
+
],
|
|
25
31
|
"scripts": {
|
|
26
|
-
"prepublishOnly": "bun clean && bun tsc --project tsconfig.build.json",
|
|
32
|
+
"prepublishOnly": "cp ../../LICENSE . && bun clean && bun tsc --project tsconfig.build.json",
|
|
33
|
+
"postpublish": "rm -f LICENSE",
|
|
27
34
|
"clean": "rm -rf dist",
|
|
28
35
|
"build": "bun prepublishOnly"
|
|
29
36
|
},
|
package/src/lib/shiki.js
CHANGED
|
@@ -70,7 +70,7 @@ export async function preloadHighlighter() {
|
|
|
70
70
|
try {
|
|
71
71
|
await initializeHighlighter()
|
|
72
72
|
} catch (error) {
|
|
73
|
-
console.warn('Failed to preload syntax highlighter:', error.message)
|
|
73
|
+
console.warn('Failed to preload syntax highlighter:', error.message)
|
|
74
74
|
}
|
|
75
75
|
}
|
|
76
76
|
|
package/src/Code.svelte
DELETED
|
@@ -1,21 +0,0 @@
|
|
|
1
|
-
<script>
|
|
2
|
-
import { vibe } from '@rokkit/states'
|
|
3
|
-
import { highlightCode } from './shiki.js'
|
|
4
|
-
import CopyToClipboard from './CopyToClipboard.svelte'
|
|
5
|
-
|
|
6
|
-
let { content, language } = $props()
|
|
7
|
-
let theme = $derived(vibe.mode === 'dark' ? 'github-dark' : 'github-light')
|
|
8
|
-
let highlightedCode = $derived(highlightCode(content, { lang: language, theme }))
|
|
9
|
-
</script>
|
|
10
|
-
|
|
11
|
-
<div data-code-root>
|
|
12
|
-
<CopyToClipboard {content} floating={true} />
|
|
13
|
-
{#await highlightedCode}
|
|
14
|
-
<div class="text-surface-z7 p-4">Highlighting code...</div>
|
|
15
|
-
{:then code}
|
|
16
|
-
<!-- eslint-disable svelte/no-at-html-tags -->
|
|
17
|
-
{@html code}
|
|
18
|
-
{:catch error}
|
|
19
|
-
<div class="p-4 text-red-500">Error highlighting code: {error.message}</div>
|
|
20
|
-
{/await}
|
|
21
|
-
</div>
|
package/src/CodeViewer.svelte
DELETED
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
<script>
|
|
2
|
-
import { Tabs } from '@rokkit/ui'
|
|
3
|
-
import Code from './Code.svelte'
|
|
4
|
-
let { files = [] } = $props()
|
|
5
|
-
let current = $state(null)
|
|
6
|
-
$effect(() => {
|
|
7
|
-
if (files.length > 0 && current === null) {
|
|
8
|
-
current = files[0]
|
|
9
|
-
}
|
|
10
|
-
})
|
|
11
|
-
let fields = { text: 'name', icon: 'language' }
|
|
12
|
-
</script>
|
|
13
|
-
|
|
14
|
-
<Tabs items={files} {fields} bind:value={current} class="no-padding">
|
|
15
|
-
<Code content={current?.content} language={current?.language} />
|
|
16
|
-
</Tabs>
|
|
@@ -1,26 +0,0 @@
|
|
|
1
|
-
<script>
|
|
2
|
-
import { DEFAULT_STATE_ICONS } from '@rokkit/core'
|
|
3
|
-
import { Icon, Button } from '@rokkit/ui'
|
|
4
|
-
let { content, class: className = 'absolute right-2 top-2 z-10', title = 'Copy code' } = $props()
|
|
5
|
-
let copySuccess = $state(false)
|
|
6
|
-
|
|
7
|
-
async function copyToClipboard() {
|
|
8
|
-
try {
|
|
9
|
-
await navigator.clipboard.writeText(content || '')
|
|
10
|
-
copySuccess = true
|
|
11
|
-
setTimeout(() => {
|
|
12
|
-
copySuccess = false
|
|
13
|
-
}, 2000)
|
|
14
|
-
} catch (err) {
|
|
15
|
-
console.error('Failed to copy code:', err)
|
|
16
|
-
}
|
|
17
|
-
}
|
|
18
|
-
</script>
|
|
19
|
-
|
|
20
|
-
<Button onclick={copyToClipboard} class={className} {title}>
|
|
21
|
-
{#if copySuccess}
|
|
22
|
-
<Icon name={DEFAULT_STATE_ICONS.action.copysuccess} />
|
|
23
|
-
{:else}
|
|
24
|
-
<Icon name={DEFAULT_STATE_ICONS.action.copy} />
|
|
25
|
-
{/if}
|
|
26
|
-
</Button>
|
package/src/Notes.svelte
DELETED
|
@@ -1,57 +0,0 @@
|
|
|
1
|
-
<script>
|
|
2
|
-
import { Icon, BreadCrumbs } from '@rokkit/ui'
|
|
3
|
-
import { getContext } from 'svelte'
|
|
4
|
-
import { goto } from '$app/navigation'
|
|
5
|
-
import { page } from '$app/state'
|
|
6
|
-
const site = getContext('site')()
|
|
7
|
-
|
|
8
|
-
let { content, crumbs, previous, next } = $props()
|
|
9
|
-
/**
|
|
10
|
-
*
|
|
11
|
-
* @param {string} route
|
|
12
|
-
*/
|
|
13
|
-
async function gotoPage(route) {
|
|
14
|
-
if (route) {
|
|
15
|
-
const location = `/${ page.params.segment }/${ route}`
|
|
16
|
-
await goto(location)
|
|
17
|
-
}
|
|
18
|
-
}
|
|
19
|
-
function toggle() {
|
|
20
|
-
site.sidebar = !site.sidebar
|
|
21
|
-
}
|
|
22
|
-
</script>
|
|
23
|
-
|
|
24
|
-
<aside class="border-r-surface-z0 flex h-full w-full flex-col border-r">
|
|
25
|
-
{#if content}
|
|
26
|
-
<nav class="border-b-surface-z0 box-border flex h-10 items-center gap-1 border-b px-2 text-sm">
|
|
27
|
-
{#if !site.sidebar}
|
|
28
|
-
<Icon
|
|
29
|
-
name="i-rokkit:menu"
|
|
30
|
-
class="border-r-surface-z2 border-r"
|
|
31
|
-
role="button"
|
|
32
|
-
onclick={toggle}
|
|
33
|
-
/>
|
|
34
|
-
{/if}
|
|
35
|
-
<Icon
|
|
36
|
-
name="i-rokkit:arrow-left"
|
|
37
|
-
role="button"
|
|
38
|
-
onclick={() => gotoPage(previous)}
|
|
39
|
-
class="square"
|
|
40
|
-
/>
|
|
41
|
-
<h1 class="w-full">
|
|
42
|
-
<BreadCrumbs items={crumbs} class="text-xs" />
|
|
43
|
-
</h1>
|
|
44
|
-
<Icon
|
|
45
|
-
name="i-rokkit:arrow-right"
|
|
46
|
-
role="button"
|
|
47
|
-
onclick={() => gotoPage(next)}
|
|
48
|
-
class="square"
|
|
49
|
-
/>
|
|
50
|
-
</nav>
|
|
51
|
-
|
|
52
|
-
{@const SvelteComponent = content}
|
|
53
|
-
<notes class="markdown-body h-full w-full overflow-scroll p-8 font-thin">
|
|
54
|
-
<SvelteComponent />
|
|
55
|
-
</notes>
|
|
56
|
-
{/if}
|
|
57
|
-
</aside>
|
package/src/Preview.svelte
DELETED
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
<script>
|
|
2
|
-
import CodeViewer from './CodeViewer.svelte'
|
|
3
|
-
|
|
4
|
-
let { App, files } = $props()
|
|
5
|
-
</script>
|
|
6
|
-
|
|
7
|
-
<div data-story-root>
|
|
8
|
-
<div data-story-preview>
|
|
9
|
-
{#if App}
|
|
10
|
-
<App />
|
|
11
|
-
{:else}
|
|
12
|
-
<div>No preview available</div>
|
|
13
|
-
{/if}
|
|
14
|
-
</div>
|
|
15
|
-
<CodeViewer {files} />
|
|
16
|
-
</div>
|
package/tsconfig.build.json
DELETED