slidev-theme-practicum 0.1.4 → 0.3.0

package/composables/local-layout-variant-files.ts

@@ -0,0 +1,106 @@
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { hasLayoutVariant, type ThemeLayout } from './layout-recipes'
+
+export type DeckLayoutVariantFile = {
+  key: string
+  layout: ThemeLayout
+  variant: string
+  path: string
+}
+
+export const DECK_LAYOUT_VARIANTS_VIRTUAL_ID = 'virtual:practicum-deck-layout-variants'
+export const RESOLVED_DECK_LAYOUT_VARIANTS_VIRTUAL_ID = '\0virtual:practicum-deck-layout-variants'
+
+const THEME_LAYOUTS = new Set<ThemeLayout>(['cover', 'message', 'explainer', 'collection'])
+const VARIANT_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+export function deckLayoutVariantsDirectory(root: string) {
+  return join(root, 'components', 'layout-variants')
+}
+
+function readDirectory(path: string) {
+  try {
+    return readdirSync(path, { withFileTypes: true })
+  }
+  catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+      return []
+    throw error
+  }
+}
+
+export function discoverDeckLayoutVariantFiles(root: string): DeckLayoutVariantFile[] {
+  const directory = deckLayoutVariantsDirectory(root)
+  const layoutEntries = readDirectory(directory)
+
+  for (const entry of layoutEntries) {
+    if (entry.isFile() && entry.name.endsWith('.vue')) {
+      throw new Error(
+        `[Practicum] Локальный вариант "${entry.name}" должен лежать в components/layout-variants/<layout>/${entry.name}.`,
+      )
+    }
+
+    if (entry.isDirectory() && !THEME_LAYOUTS.has(entry.name as ThemeLayout)) {
+      throw new Error(
+        `[Practicum] "${entry.name}" не является тематическим layout. Для нового layout создайте layouts/${entry.name}.vue.`,
+      )
+    }
+  }
+
+  return layoutEntries
+    .filter(entry => entry.isDirectory() && THEME_LAYOUTS.has(entry.name as ThemeLayout))
+    .flatMap((layoutEntry) => {
+      const layout = layoutEntry.name as ThemeLayout
+      const layoutDirectory = join(directory, layout)
+
+      return readDirectory(layoutDirectory)
+        .filter(entry => entry.isFile() && entry.name.endsWith('.vue'))
+        .map((entry) => {
+          const variant = entry.name.slice(0, -'.vue'.length)
+
+          if (!VARIANT_ID_PATTERN.test(variant)) {
+            throw new Error(
+              `[Practicum] Локальный вариант "${layout}/${entry.name}" должен иметь kebab-case имя, например "lesson-summary.vue".`,
+            )
+          }
+
+          if (hasLayoutVariant(layout, variant)) {
+            throw new Error(
+              `[Practicum] Локальный вариант "${layout}:${variant}" конфликтует со встроенным вариантом темы.`,
+            )
+          }
+
+          return {
+            key: `${layout}:${variant}`,
+            layout,
+            variant,
+            path: join(layoutDirectory, entry.name),
+          }
+        })
+    })
+    .sort((left, right) => left.key.localeCompare(right.key))
+}
+
+function toViteFileId(path: string) {
+  const normalized = path.replaceAll('\\', '/')
+  return `/@fs${normalized.startsWith('/') ? '' : '/'}${normalized}`
+}
+
+export function createDeckLayoutVariantModuleSource(files: readonly DeckLayoutVariantFile[]) {
+  const imports = files.map((file, index) =>
+    `import DeckLayoutVariant${index} from ${JSON.stringify(toViteFileId(file.path))}`,
+  )
+  const entries = files.map((file, index) =>
+    `  ${JSON.stringify(file.key)}: DeckLayoutVariant${index},`,
+  )
+
+  return [
+    ...imports,
+    '',
+    'export const DECK_LAYOUT_VARIANTS = Object.freeze({',
+    ...entries,
+    '})',
+    '',
+  ].join('\n')
+}

package/composables/local-layout-variants.ts

@@ -0,0 +1,73 @@
+import { h, type Component, type VNode } from 'vue'
+import type { ThemeLayout } from './layout-recipes'
+
+export type DeckLayoutVariantCatalog = Readonly<Record<string, Component>>
+
+export type DeckLayoutVariantProps<Frontmatter extends object = Record<string, unknown>> = {
+  layout: ThemeLayout
+  variant: string
+  frontmatter: Readonly<Frontmatter>
+}
+
+export type DeckLayoutVariantSlots = {
+  default(): VNode[]
+}
+
+export type SlideDeckLayoutVariantContractError = Error & {
+  name: 'SlideMarkdownContractError'
+  hint?: string
+}
+
+function failDeckLayoutVariantContract(message: string, hint?: string): never {
+  const error = new Error(`[Slide] Локальный вариант ${message}`) as SlideDeckLayoutVariantContractError
+  error.name = 'SlideMarkdownContractError'
+  if (hint)
+    error.hint = hint
+  throw error
+}
+
+export function deckLayoutVariantKey(layout: ThemeLayout, variant: string) {
+  return `${layout}:${variant}`
+}
+
+export function resolveDeckLayoutVariant(input: {
+  layout: ThemeLayout
+  variant: string
+  arrangement: string
+  variants: DeckLayoutVariantCatalog
+}) {
+  const component = input.variants[deckLayoutVariantKey(input.layout, input.variant)]
+
+  if (component && input.arrangement) {
+    failDeckLayoutVariantContract(
+      `"${input.layout}:${input.variant}" не поддерживает arrangement: ${input.arrangement}.`,
+      'Удалите `arrangement` либо используйте встроенный вариант темы.',
+    )
+  }
+
+  if (component)
+    return component
+
+  failDeckLayoutVariantContract(
+    `"${input.layout}:${input.variant}" не найден.`,
+    `Создайте components/layout-variants/${input.layout}/${input.variant}.vue в проекте презентации.`,
+  )
+}
+
+export function buildDeckLayoutVariantVNode(input: {
+  layout: ThemeLayout
+  variant: string
+  component: Component
+  frontmatter: Record<string, unknown>
+  children: readonly VNode[]
+}) {
+  const frontmatter = Object.freeze({ ...input.frontmatter })
+
+  return h(input.component, {
+    layout: input.layout,
+    variant: input.variant,
+    frontmatter,
+  } satisfies DeckLayoutVariantProps, {
+    default: () => [...input.children],
+  })
+}

package/composables/slide-layout.ts

@@ -5,6 +5,7 @@ import {
   type LayoutAuthoringInput,
 } from './layout-authoring'
 import type { LayoutShorthandComponents } from './layout-shorthands'
+import type { DeckLayoutVariantCatalog } from './local-layout-variants'
 import {
   createSlotPlacementSession,
   type SlotPlacementSession,
@@ -19,6 +20,7 @@ export type SlideLayout = SlotPlacementSession & {
 
 export function createSlideLayout(input: {
   components: LayoutShorthandComponents
+  layoutVariants?: DeckLayoutVariantCatalog
 }): SlideLayout {
   const slotPlanState = createLayoutSlotPlanState()
   let current: CompiledSlideLayout | null = null
@@ -31,6 +33,7 @@ export function createSlideLayout(input: {
       const compiled = compileLayoutAuthoring({
         ...authoringInput,
         components: input.components,
+        layoutVariants: input.layoutVariants,
         slotPlanState,
       })
 

package/composables/use-theme-config.ts

@@ -1,9 +1,15 @@
 import { computed } from 'vue'
 import { useSlideContext } from '@slidev/client'
+import { collectDecorSources, isRecord } from './decor-sources'
 import { resolveTone, type ThemeTone } from './theme-foundation'
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
+function readFileDecors() {
+  try {
+    return Array.isArray(__PRATICUM_DECK_DECORS__) ? __PRATICUM_DECK_DECORS__ : []
+  }
+  catch {
+    return []
+  }
 }
 
 function readBoolean(value: unknown, fallback: boolean) {
@@ -45,20 +51,20 @@ export function useThemeConfig() {
     if (typeof explicit === 'string' && explicit.trim())
       return explicit.trim()
 
-    const fallback = configs.value.title
-    if (typeof fallback === 'string' && fallback.trim())
-      return fallback.trim()
-
     return ''
   })
 
   const showPageNumber = computed(() => readBoolean(themeConfigs.value.showPageNumber, true))
   const debugGrid = computed(() => readBoolean(themeConfigs.value.debugGrid, false))
   const defaultTone = computed(() => readDefaultTone(themeConfigs.value.defaultTone, 'blue'))
-  const decors = computed(() => {
-    const explicit = themeConfigs.value.decors
-    return Array.isArray(explicit) ? explicit : []
-  })
+  const decors = computed(() => [
+    ...readFileDecors(),
+    ...collectDecorSources(themeConfigs.value.decors).inline,
+  ])
+  const replaceDecors = computed(() => readBoolean(
+    themeConfigs.value.replaceDecors,
+    readFileDecors().length > 0 || collectDecorSources(themeConfigs.value.decors).files.length > 0,
+  ))
 
   return {
     themeConfigs,
@@ -67,5 +73,6 @@ export function useThemeConfig() {
     debugGrid,
     defaultTone,
     decors,
+    replaceDecors,
   }
 }

package/composables/validate-deck-layouts.cjs

@@ -1,5 +1,5 @@
 const { readFileSync } = require('node:fs')
-const { isAbsolute, join, resolve } = require('node:path')
+const { dirname, isAbsolute, join, resolve } = require('node:path')
 const { parseSync } = require('@slidev/parser')
 const { createCommentVNode, createTextVNode, createVNode } = require('vue')
 const { registerTypeScript } = require('./typescript-require.cjs')
@@ -41,7 +41,10 @@ registerTypeScript()
 
 const { compileLayoutAuthoring } = require(themePath('composables/layout-authoring.ts'))
 const { hasLayoutShorthand } = require(themePath('composables/layout-shorthands.ts'))
+const { discoverDeckLayoutVariantFiles } = require(themePath('composables/local-layout-variant-files.ts'))
+const { resolveDeckLayoutVariant } = require(themePath('composables/local-layout-variants.ts'))
 const {
+  hasLayoutVariant,
   resolveLayoutSlotSpec,
   resolveLayoutVariant,
 } = require(themePath('composables/layout-recipes.ts'))
@@ -57,6 +60,7 @@ function stubComponents() {
     Slot: named('Slot'),
     Text: named('Text'),
     Timeline: named('Timeline'),
+    StepsGrid: named('StepsGrid'),
   }
 }
 
@@ -121,7 +125,7 @@ function validateExplicitSlotIntents(intents, input) {
 function slideRef(slide, index) {
   const layout = String(slide.frontmatter?.layout ?? '').trim()
   const variant = String(slide.frontmatter?.variant ?? '').trim()
-  const title = String(slide.title || slide.content?.match(/^#\s+(.+)/m)?.[1] || '').trim()
+  const title = String(slide.content?.match(/^#\s+(.+)/m)?.[1] || '').trim()
   return {
     index,
     page: index + 1,
@@ -141,17 +145,64 @@ async function validateDeckLayouts(deckPath) {
   const source = readFileSync(absolutePath, 'utf8')
   const deck = parseSync(source, absolutePath)
   const components = stubComponents()
+  /** @type {{ key: string, path: string }[]} */
+  const layoutVariantFiles = discoverDeckLayoutVariantFiles(dirname(absolutePath))
+  const layoutVariants = Object.fromEntries(
+    layoutVariantFiles
+      .map(file => [file.key, { name: `DeckLayoutVariant:${file.key}` }]),
+  )
   /** @type {DeckValidationIssue[]} */
   const issues = []
 
   for (const [index, slide] of deck.slides.entries()) {
     const layout = String(slide.frontmatter?.layout ?? '').trim()
+    const ref = slideRef(slide, index)
+
+    if (index > 0 && Object.prototype.hasOwnProperty.call(slide.frontmatter ?? {}, 'title')) {
+      issues.push({
+        ...ref,
+        message: 'Верхнеуровневое поле `title` разрешено только в первом headmatter как служебное название колоды и не является видимым содержимым слайда.',
+        hint: 'Удалите поле и перенесите основной текст в тело слайда: используйте Markdown-заголовок `# …` или видимый `<Text as="h1">…</Text>` в явной композиции.',
+      })
+    }
+
     if (!isThemeLayout(layout))
       continue
 
     const rawVariant = String(slide.frontmatter?.variant ?? '').trim()
     const arrangement = String(slide.frontmatter?.arrangement ?? '').trim()
-    const ref = slideRef(slide, index)
+    const localVariant = layoutVariants[`${layout}:${rawVariant}`]
+
+    if (localVariant) {
+      const content = stripAuthorNotes(slide.content ?? '')
+
+      try {
+        compileLayoutAuthoring({
+          props: {
+            layout,
+            variant: rawVariant,
+            arrangement,
+            mode: slide.frontmatter?.mode,
+            tone: slide.frontmatter?.tone ?? '',
+          },
+          frontmatter: slide.frontmatter ?? {},
+          children: markdownToVnodes(content),
+          components,
+          layoutVariants,
+          defaultTone: 'blue',
+        })
+      }
+      catch (error) {
+        const hint = error && typeof error === 'object' && 'hint' in error ? error.hint : undefined
+        issues.push({
+          ...ref,
+          message: error instanceof Error ? error.message : String(error),
+          hint: typeof hint === 'string' ? hint : undefined,
+        })
+      }
+      continue
+    }
+
     /** @type {string} */
     let variant
 
@@ -159,10 +210,26 @@ async function validateDeckLayouts(deckPath) {
       variant = resolveLayoutVariant(layout, rawVariant, arrangement)
     }
     catch (error) {
-      const hint = error && typeof error === 'object' && 'hint' in error ? error.hint : undefined
+      let reportedError = error
+      if (rawVariant && !hasLayoutVariant(layout, rawVariant)) {
+        try {
+          resolveDeckLayoutVariant({
+            layout,
+            variant: rawVariant,
+            arrangement,
+            variants: layoutVariants,
+          })
+        }
+        catch (deckVariantError) {
+          reportedError = deckVariantError
+        }
+      }
+      const hint = reportedError && typeof reportedError === 'object' && 'hint' in reportedError
+        ? reportedError.hint
+        : undefined
       issues.push({
         ...ref,
-        message: error instanceof Error ? error.message : String(error),
+        message: reportedError instanceof Error ? reportedError.message : String(reportedError),
         hint: typeof hint === 'string' ? hint : undefined,
       })
       continue
@@ -197,6 +264,7 @@ async function validateDeckLayouts(deckPath) {
           frontmatter: slide.frontmatter ?? {},
           children: liveStructure.children.map(node => liveNodeToVNode(node, components)),
           components,
+          layoutVariants,
           defaultTone: 'blue',
         })
         validateExplicitSlotIntents(liveStructure.intents, {
@@ -233,6 +301,7 @@ async function validateDeckLayouts(deckPath) {
         frontmatter: slide.frontmatter ?? {},
         children: markdownToVnodes(content),
         components,
+        layoutVariants,
         defaultTone: 'blue',
       })
     }
@@ -264,7 +333,9 @@ function formatDeckLayoutIssues(issues, deckPath = 'deck') {
     ]
     if (issue.hint)
       lines.push(`  Подсказка: ${issue.hint}`)
-    lines.push('  См. example.md в slidev-theme-practicum (заметки «Контракт»).')
+    lines.push(issue.hint?.includes('components/layout-variants/')
+      ? '  См. README.md в slidev-theme-practicum, раздел «Локальные варианты презентации».'
+      : '  См. example.md в slidev-theme-practicum (заметки «Контракт»).')
     return lines.join('\n')
   }).join(`\n\n${'—'.repeat(40)}\n\n`)
 

package/env.d.ts

@@ -0,0 +1,18 @@
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+
+  const component: DefineComponent<Record<string, never>, Record<string, never>, unknown>
+  export default component
+}
+
+declare const __PRATICUM_DECK_DECORS__: readonly Record<string, unknown>[]
+
+declare module 'virtual:practicum-deck-layout-variants' {
+  import type { Component } from 'vue'
+
+  export const DECK_LAYOUT_VARIANTS: Readonly<Record<string, Component>>
+}
+
+declare module 'virtual:practicum-deck-decors' {
+  export const DECK_FILE_DECORS: readonly Record<string, unknown>[]
+}

package/example.md

@@ -306,9 +306,6 @@ variant: title-supports-bottom-plain
 # Когда нужны два самостоятельных абзаца
 
 - Этот вариант снимает приглушение с нижних опор. Каждый абзац читается как самостоятельный текст: его не воспринимают как «второстепенный к заголовку», а ставят рядом по весу.
-  - авава
-  - ава
-  авава
 - Берите слайд, когда тезис распадается на два независимых направления: например, «что включить» и «чего избегать», «теория» и «практика», «причина» и «следствие». Третий блок не нужен — два аргумента уже задают сильную смысловую пару.
 
 ---
@@ -467,10 +464,143 @@ decor:
 
 # Оранжевый тон: акцент
 
-1. Выносите важный поворот или предупреждение
+1. Подсвечивайте один критический поворот
 2. Не окрашивайте им весь ряд одинаковых фактов
 3. Оставляйте рядом достаточно воздуха
 
+---
+layout: collection
+variant: comparison
+arrangement: before-after
+comparison:
+  from:
+    kicker: До разбора
+    title: «Я просто запомнил формулу»
+    body: Ответ верный, но ученик не может объяснить выбор метода.
+  to:
+    kicker: После разбора
+    title: «Я выбрал формулу по условию»
+    body: Ученик связывает данные, метод и проверку результата.
+relation:
+  label: объяснить ход мысли
+---
+
+<!-- Контракт: comparison before-after — заголовок в Markdown, две стороны и связь во frontmatter. -->
+
+# Как обратная связь превращает ответ в решение
+
+---
+layout: collection
+variant: comparison
+arrangement: stable-variable
+comparison:
+  from:
+    kicker: Сохраняем
+    title: Научиться проверять гипотезу
+    body: Результат занятия остаётся общим для любой группы.
+  to:
+    kicker: Меняем
+    title: Данные и уровень подсказок
+    body: Контекст и поддержка зависят от опыта студентов.
+relation:
+  label: одна цель, разные маршруты
+---
+
+<!-- Контракт: comparison stable-variable — тот же shorthand, но вертикальная связь. -->
+
+# Как адаптировать практику, сохраняя учебную цель
+
+---
+layout: collection
+variant: steps
+arrangement: linear
+items:
+  - title: Назвать цель
+    body: Что студент сделает сам
+  - title: Дать контекст
+    body: Где возникает задача
+  - title: Показать пример
+    body: Один разобранный ход
+  - title: Оставить практику
+    body: Задание без подсказки
+  - title: Проверить критерий
+    body: Видимый признак качества
+    active: true
+  - title: Закрепить вывод
+    body: Что перенести дальше
+---
+
+<!-- Контракт: steps linear — ровно 6 шагов во frontmatter, один из них active. -->
+
+# Шесть шагов учебного объяснения
+
+---
+layout: collection
+variant: steps
+arrangement: staggered
+items:
+  - label: Сигнал
+    title: Заметить сбой
+    body: Зафиксировать наблюдение
+  - label: Факт
+    title: Повторить шаг
+    body: Отделить случайность
+  - label: Причина
+    title: Найти правило
+    body: Объяснить механизм
+    active: true
+  - label: Решение
+    title: Изменить подход
+    body: Проверить новый ход
+  - label: Перенос
+    title: Записать вывод
+    body: Применить в другой задаче
+---
+
+<!-- Контракт: steps staggered — ровно 5 шагов во frontmatter для ритма 3+2. -->
+
+# Как команда разбирает ошибку
+
+---
+layout: collection
+variant: metrics
+arrangement: dashboard
+metrics:
+  - value: '84%'
+    label: завершили тренажёр
+  - value: '18 мин'
+    label: медиана выполнения
+  - value: '3'
+    label: попытки до зачёта
+  - value: '12'
+    label: вопросов разобрали
+  - value: '+21 п. п.'
+    label: к входной диагностике
+---
+
+<!-- Контракт: metrics dashboard — ровно 5 метрик во frontmatter, без media и ручных spans. -->
+
+# Что изменилось после практикума
+
+---
+layout: collection
+variant: facts
+arrangement: numbered-quartet
+---
+
+<!-- Контракт: facts numbered-quartet — заголовок и 4 вложенных Markdown-факта; номера добавляет тема. -->
+
+# Четыре вопроса перед публикацией задания
+
+- Цель
+  - Что студент сделает самостоятельно
+- Контекст
+  - Почему задача нужна именно сейчас
+- Критерий
+  - Как выглядит проверяемый результат
+- Обратная связь
+  - Что поможет улучшить следующую попытку
+
 ---
 layout: collection
 variant: metrics
@@ -717,7 +847,7 @@ header: default
 </Slot>
 
 <Slot area="6 / 1 / -1 / 7" surface="color" tone="orange" margin="4" gap="2">
-  <Text size="5">Цветная поверхность</Text>
+  <Text size="5">Акцентная поверхность</Text>
   <Text size="3">Слот целиком красится в текущий акцентный цвет — для смыслового выделения.</Text>
 </Slot>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slidev-theme-practicum",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "Strict Slidev presentation theme with a 12x12 grid, editorial layouts, and low-level slot composition API",
   "keywords": [
     "slidev-theme",
@@ -25,6 +25,7 @@
     "styles",
     "types",
     "skills",
+    "env.d.ts",
     "LICENSE",
     "README.md",
     "example.md",
@@ -64,12 +65,13 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "validate-deck": "node scripts/validate-deck.cjs",
-    "test": "npm run lint && npm run typecheck && npm run test:unit && npm run test:architecture && npm run test:build && npm run test:build-artifact && npm run test:browser && npm run test:package",
+    "test": "npm run lint && npm run typecheck && npm run test:unit && npm run test:architecture && npm run test:build && npm run test:layout-variant-build && npm run test:build-artifact && npm run test:browser && npm run test:package",
     "typecheck": "vue-tsc --noEmit",
     "test:architecture": "node scripts/check-test-architecture.mjs",
     "test:unit": "node --test tests/*.test.cjs",
     "test:validate-deck": "node scripts/validate-deck.cjs example.md",
     "test:build": "slidev build example.md",
+    "test:layout-variant-build": "node scripts/check-local-layout-variant-build.mjs",
     "test:build-artifact": "node scripts/check-build-artifact.mjs",
     "test:browser": "node scripts/browser-smoke.mjs",
     "test:package": "node scripts/check-package.mjs"
@@ -81,7 +83,8 @@
     "@slidev/types": "^52.14.2",
     "markdown-it": "^14.1.0",
     "typescript": "^6.0.3",
-    "vue": "^3.5.13"
+    "vue": "^3.5.13",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",