kawapress 0.2.2 → 0.3.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.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "kawapress",
3
3
  "type": "module",
4
- "version": "0.2.2",
4
+ "version": "0.3.0",
5
5
  "description": "A Vue-centric static site generator",
6
6
  "license": "MIT",
7
7
  "homepage": "https://kawapress.dev/",
@@ -82,6 +82,6 @@
82
82
  "tinyglobby": "^0.2.17",
83
83
  "vite": "^8.2.2",
84
84
  "vue": "^3.5.41",
85
- "@kawapress/preset-nagi": "^0.2.2"
85
+ "@kawapress/preset-nagi": "^0.3.0"
86
86
  }
87
87
  }
package/src/api/plugin.ts CHANGED
@@ -68,8 +68,10 @@ export function definePlugin(plugin: KawaPressPlugin): KawaPressPlugin {
68
68
  export type RuntimePluginHandler<T> = (value: T) => MaybePromise<void>
69
69
 
70
70
  export interface RuntimePluginAPI {
71
- /** Places a component in a theme outlet. */
72
- addToOutlet: (outlet: OutletName, item: OutletItemInput) => void
71
+ /** Places a component before the theme's own content of an outlet. */
72
+ prependToOutlet: (outlet: OutletName, item: OutletItemInput) => void
73
+ /** Places a component after the theme's own content of an outlet. */
74
+ appendToOutlet: (outlet: OutletName, item: OutletItemInput) => void
73
75
  vueApp: (handler: RuntimePluginHandler<App>) => void
74
76
  router: (handler: RuntimePluginHandler<Router>) => void
75
77
  }
@@ -1,7 +1,7 @@
1
1
  <script setup lang="ts">
2
- import type { OutletItem, OutletName } from '../../core/outlet'
2
+ import type { OutletName } from '../../core/outlet'
3
3
  import { computed, onUnmounted } from 'vue'
4
- import { assertOutletName, getOutletItems } from '../../core/outlet'
4
+ import { assertOutletName, getOutletSlots } from '../../core/outlet'
5
5
  import { recordRenderedOutlet, useOutletRegistry, useOutletRenderStore } from '../outlet'
6
6
 
7
7
  const props = defineProps<{
@@ -9,14 +9,15 @@ const props = defineProps<{
9
9
  }>()
10
10
 
11
11
  defineSlots<{
12
- /** Full control over the outlet: filter, wrap, or replace the items. */
13
- default?: (props: { items: readonly OutletItem[] }) => unknown
12
+ /** The theme's own content. Plugin items render before and after it. */
13
+ default?: () => unknown
14
14
  }>()
15
15
 
16
16
  assertOutletName(props.name, '<KawaOutlet>')
17
17
 
18
18
  const registry = useOutletRegistry('<KawaOutlet>')
19
- const items = computed(() => getOutletItems(registry, props.name))
19
+ // `slots` stays unset when the name check above throws; Vue still renders once after that.
20
+ const slots = computed(() => getOutletSlots(registry, props.name))
20
21
 
21
22
  const renderStore = useOutletRenderStore()
22
23
  renderStore?.mount(props.name)
@@ -26,11 +27,15 @@ recordRenderedOutlet(props.name)
26
27
  </script>
27
28
 
28
29
  <template>
29
- <slot :items="items">
30
- <component
31
- :is="item.component"
32
- v-for="item in items"
33
- :key="item.id"
34
- />
35
- </slot>
30
+ <component
31
+ :is="item.component"
32
+ v-for="item in slots?.prepend"
33
+ :key="item.id"
34
+ />
35
+ <slot />
36
+ <component
37
+ :is="item.component"
38
+ v-for="item in slots?.append"
39
+ :key="item.id"
40
+ />
36
41
  </template>
@@ -37,8 +37,8 @@ interface MarkdownEnv extends PageComponentEnv {
37
37
  sfcBlocks?: MarkdownSfcBlocks
38
38
  /** Set by the LLMS plugin when it compiles Markdown for plain-text output. */
39
39
  ssgMarkdown?: boolean
40
- /** Set once the `doc.header` outlet has been placed after the first H1. */
41
- docHeaderOutletPlaced?: boolean
40
+ /** Set once the `doc.under-title` outlet has been placed after the first H1. */
41
+ docUnderTitleOutletPlaced?: boolean
42
42
  /** Page body after frontmatter removal, set by the frontmatter plugin. */
43
43
  content?: string
44
44
  /** Internal links of the page, with line numbers relative to the source file. */
@@ -86,7 +86,7 @@ export async function createMarkdownCompiler(options: MarkdownCompilerOptions =
86
86
  installHeadingTitles(md)
87
87
  installPageLinkCollector(md)
88
88
  installLinkRenderer(md, options.base ?? '/')
89
- installDocHeaderOutlet(md)
89
+ installDocUnderTitleOutlet(md)
90
90
 
91
91
  await options.pluginRunner?.runMarkdown(md)
92
92
  return md
@@ -169,14 +169,14 @@ function installAsyncSfcRenderCompatibility(md: MarkdownExit): void {
169
169
  }
170
170
  }
171
171
 
172
- const DOC_HEADER_OUTLET = '<KawaOutlet name="doc.header" />'
172
+ const DOC_UNDER_TITLE_OUTLET = '<KawaOutlet name="doc.under-title" />'
173
173
 
174
174
  /**
175
- * Renders the `doc.header` outlet right after the first H1 of every page, so
175
+ * Renders the `doc.under-title` outlet right after the first H1 of every page, so
176
176
  * plugins can place interface pieces inside the Markdown body without the
177
177
  * theme reaching into compiled content. Pages without an H1 get no outlet.
178
178
  */
179
- function installDocHeaderOutlet(md: MarkdownExit): void {
179
+ function installDocUnderTitleOutlet(md: MarkdownExit): void {
180
180
  const original = md.renderer.rules.heading_close
181
181
 
182
182
  md.renderer.rules.heading_close = (tokens, index, options, env, renderer) => {
@@ -190,13 +190,13 @@ function installDocHeaderOutlet(md: MarkdownExit): void {
190
190
  || typeof env !== 'object'
191
191
  || env === null
192
192
  || renderEnv.ssgMarkdown
193
- || renderEnv.docHeaderOutletPlaced
193
+ || renderEnv.docUnderTitleOutletPlaced
194
194
  ) {
195
195
  return rendered
196
196
  }
197
197
 
198
- renderEnv.docHeaderOutletPlaced = true
199
- return `${rendered}\n${DOC_HEADER_OUTLET}\n`
198
+ renderEnv.docUnderTitleOutletPlaced = true
199
+ return `${rendered}\n${DOC_UNDER_TITLE_OUTLET}\n`
200
200
  }
201
201
  }
202
202
 
@@ -2,18 +2,26 @@ import type { Component } from 'vue'
2
2
 
3
3
  /**
4
4
  * Every outlet a theme can render. The list is the public contract between
5
- * plugins (which place interface pieces) and themes (which place the sockets).
5
+ * plugins (which contribute interface pieces) and themes (which draw the
6
+ * default content of each outlet).
7
+ *
8
+ * A name is a scope plus a role: `layout` is the page frame, `doc` is the page
9
+ * being read. `start` and `end` follow the reading direction.
6
10
  */
7
11
  export const OUTLET_NAMES = [
8
- 'header.actions',
9
- 'doc.header',
10
- 'doc.footer',
11
- 'doc.after',
12
+ 'layout.header',
13
+ 'layout.header.start',
14
+ 'layout.header.end',
15
+ 'layout.sidebar',
16
+ 'layout.footer',
17
+ 'doc',
18
+ 'doc.under-title',
19
+ 'doc.toc',
12
20
  ] as const
13
21
 
14
22
  export type OutletName = typeof OUTLET_NAMES[number]
15
23
 
16
- /** What a plugin passes to `api.addToOutlet()`. */
24
+ /** What a plugin passes to `api.prependToOutlet()` or `api.appendToOutlet()`. */
17
25
  export interface OutletItemInput {
18
26
  id: string
19
27
  component: Component
@@ -27,10 +35,14 @@ export interface OutletItem extends OutletItemInput {
27
35
  owner: string
28
36
  }
29
37
 
30
- /** Outlet items grouped by outlet name, in render order. */
31
- export type OutletRegistry = Readonly<
32
- Record<OutletName, readonly OutletItem[]>
33
- >
38
+ /** Items of one outlet: `prepend` renders before the theme content, `append` after it. */
39
+ export interface OutletSlots {
40
+ readonly prepend: readonly OutletItem[]
41
+ readonly append: readonly OutletItem[]
42
+ }
43
+
44
+ /** Outlet items grouped by outlet name. Each side is in plugin install order. */
45
+ export type OutletRegistry = Readonly<Record<OutletName, OutletSlots>>
34
46
 
35
47
  export function isOutletName(value: unknown): value is OutletName {
36
48
  return typeof value === 'string'
@@ -50,11 +62,21 @@ export function assertOutletName(
50
62
  )
51
63
  }
52
64
 
65
+ const EMPTY_SLOTS: OutletSlots = Object.freeze({ prepend: [], append: [] })
66
+
67
+ export function getOutletSlots(
68
+ registry: OutletRegistry,
69
+ outlet: OutletName,
70
+ ): OutletSlots {
71
+ return registry[outlet] ?? EMPTY_SLOTS
72
+ }
73
+
53
74
  export function getOutletItems(
54
75
  registry: OutletRegistry,
55
76
  outlet: OutletName,
56
77
  ): readonly OutletItem[] {
57
- return registry[outlet] ?? []
78
+ const { prepend, append } = getOutletSlots(registry, outlet)
79
+ return [...prepend, ...append]
58
80
  }
59
81
 
60
82
  /** One registered item that no page ever rendered. */
@@ -6,31 +6,46 @@ import type {
6
6
  } from '../core/outlet'
7
7
  import { assertOutletName, OUTLET_NAMES } from '../core/outlet'
8
8
 
9
+ type OutletSide = 'prepend' | 'append'
10
+ type OutletAdder = (outlet: OutletName, item: OutletItemInput) => void
11
+
9
12
  export interface OutletCollector {
10
13
  /**
11
- * Registers an item for one plugin. The plugin name is bound once by the
12
- * caller so a plugin cannot claim items that belong to another plugin.
14
+ * The two registration functions of one plugin. The plugin name is bound once
15
+ * by the caller so a plugin cannot claim items that belong to another plugin.
13
16
  */
14
- addForPlugin: (pluginName: string) => (outlet: OutletName, item: OutletItemInput) => void
17
+ forPlugin: (pluginName: string) => {
18
+ prependToOutlet: OutletAdder
19
+ appendToOutlet: OutletAdder
20
+ }
15
21
  /** Freezes the collected items into the registry handed to the Vue app. */
16
22
  createRegistry: () => OutletRegistry
17
23
  }
18
24
 
19
25
  export function createOutletCollector(): OutletCollector {
20
- const itemsByOutlet = new Map<OutletName, OutletItem[]>()
26
+ const sides: Record<OutletSide, Map<OutletName, OutletItem[]>> = {
27
+ prepend: new Map(),
28
+ append: new Map(),
29
+ }
21
30
  const outletsById = new Map<string, OutletName>()
22
31
 
23
- function add(pluginName: string, outlet: OutletName, item: OutletItemInput): void {
32
+ function add(
33
+ side: OutletSide,
34
+ pluginName: string,
35
+ outlet: OutletName,
36
+ item: OutletItemInput,
37
+ ): void {
38
+ const method = `${side}ToOutlet`
24
39
  assertOutletName(
25
40
  outlet,
26
- `plugin ${JSON.stringify(pluginName)} calling api.addToOutlet()`,
41
+ `plugin ${JSON.stringify(pluginName)} calling api.${method}()`,
27
42
  )
28
43
 
29
44
  const localId = item?.id
30
45
  if (typeof localId !== 'string' || localId.trim() === '') {
31
46
  throw new Error(
32
- `[${pluginName} / runtime / addToOutlet] Item id for outlet ${JSON.stringify(outlet)} `
33
- + `must be a non-empty string. Pass { id: 'my-item', component } to api.addToOutlet().`,
47
+ `[${pluginName} / runtime / ${method}] Item id for outlet ${JSON.stringify(outlet)} `
48
+ + `must be a non-empty string. Pass { id: 'my-item', component } to api.${method}().`,
34
49
  )
35
50
  }
36
51
 
@@ -38,30 +53,30 @@ export function createOutletCollector(): OutletCollector {
38
53
  const existingOutlet = outletsById.get(id)
39
54
  if (existingOutlet) {
40
55
  throw new Error(
41
- `[${pluginName} / runtime / addToOutlet] Duplicate item id ${JSON.stringify(id)} `
56
+ `[${pluginName} / runtime / ${method}] Duplicate item id ${JSON.stringify(id)} `
42
57
  + `(already used for outlet ${JSON.stringify(existingOutlet)}). `
43
- + `Item ids must be unique per plugin; rename one of the api.addToOutlet() calls.`,
58
+ + `Item ids must be unique per plugin; rename one of the outlet calls.`,
44
59
  )
45
60
  }
46
61
 
47
62
  outletsById.set(id, outlet)
48
- const items = itemsByOutlet.get(outlet) ?? []
49
- items.push({
50
- id,
51
- owner: pluginName,
52
- component: item.component,
53
- })
54
- itemsByOutlet.set(outlet, items)
63
+ const items = sides[side].get(outlet) ?? []
64
+ items.push({ id, owner: pluginName, component: item.component })
65
+ sides[side].set(outlet, items)
55
66
  }
56
67
 
57
68
  return {
58
- addForPlugin: pluginName => (outlet, item) => {
59
- add(pluginName, outlet, item)
60
- },
69
+ forPlugin: pluginName => ({
70
+ prependToOutlet: (outlet, item) => add('prepend', pluginName, outlet, item),
71
+ appendToOutlet: (outlet, item) => add('append', pluginName, outlet, item),
72
+ }),
61
73
  createRegistry() {
62
- const registry = {} as Record<OutletName, readonly OutletItem[]>
74
+ const registry = {} as Record<OutletName, OutletRegistry[OutletName]>
63
75
  for (const name of OUTLET_NAMES) {
64
- registry[name] = Object.freeze([...(itemsByOutlet.get(name) ?? [])])
76
+ registry[name] = Object.freeze({
77
+ prepend: Object.freeze([...(sides.prepend.get(name) ?? [])]),
78
+ append: Object.freeze([...(sides.append.get(name) ?? [])]),
79
+ })
65
80
  }
66
81
  return Object.freeze(registry)
67
82
  },
@@ -26,7 +26,7 @@ export async function createRuntimePluginRunner(
26
26
 
27
27
  for (const plugin of plugins) {
28
28
  const api: RuntimePluginAPI = {
29
- addToOutlet: outletCollector.addForPlugin(plugin.name),
29
+ ...outletCollector.forPlugin(plugin.name),
30
30
  vueApp: handler => vueAppHandlers.add(plugin.name, handler),
31
31
  router: handler => routerHandlers.add(plugin.name, handler),
32
32
  }