@pathmx/core 0.5.0

package/plugins/input/state.ts

@@ -0,0 +1,272 @@
+import type { SourceTransaction } from "../../actions/transaction.ts"
+import { canonicalSourceId } from "../../canonical.ts"
+import type { PathMXYaml } from "../../environment.ts"
+import { SourceDiagnosticError } from "../../source-diagnostic.ts"
+import {
+  formatFrontmatter,
+  parseCodeFences,
+  splitTopmatter,
+  type Source,
+} from "../../source/index.ts"
+import type { UserActor } from "../../authority/model.ts"
+import type { AppContext } from "../types.ts"
+import { inputResponseConfig } from "./config.ts"
+
+export type InputValue = string | string[]
+export type InputValues = Record<string, InputValue>
+
+export type InputStateRecord = Readonly<{
+  actorId: string
+  originId: string
+  source: Source
+  data: Record<string, unknown>
+  values: InputValues
+  submitted: boolean
+  submittedAt?: string
+  statusIssue?: string
+}>
+
+export type InputStateBinding =
+  | Readonly<{ type: "bound"; state: InputStateRecord }>
+  | Readonly<{ type: "actor-relative"; state?: InputStateRecord }>
+
+function invalidState(source: Source, message: string) {
+  return new SourceDiagnosticError({
+    source: source.path,
+    plugin: "input",
+    message: `Invalid Input state in ${source.path}: ${message}`,
+  })
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value != null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+function inputStateData(source: Source, yaml: PathMXYaml) {
+  if (source.type !== "state") return
+  const block = splitTopmatter(source.body, yaml)
+  if (block.data.plugin !== "input") return
+  const fence = parseCodeFences(block.body).find(
+    (candidate) =>
+      candidate.lang === "yaml" &&
+      candidate.info.split(/\s+/).includes("@state"),
+  )
+  if (!fence) return
+  const parsed = yaml.parse(fence.body)
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw invalidState(source, "@state must contain a YAML map.")
+  }
+  return parsed as Record<string, unknown>
+}
+
+function submission(data: Record<string, unknown>) {
+  if (data.status == null) return { submitted: false }
+  const status = record(data.status)
+  if (!status) {
+    return { submitted: false, issue: "status must be a map." }
+  }
+  if (status.type !== "submitted") return { submitted: false }
+  if (typeof status.submitted_at !== "string" || !status.submitted_at.trim()) {
+    return {
+      submitted: false,
+      issue: "submitted status requires submitted_at.",
+    }
+  }
+  const submittedAt = Date.parse(status.submitted_at)
+  if (!Number.isFinite(submittedAt)) {
+    return {
+      submitted: false,
+      issue: "submitted_at must be an ISO 8601 timestamp.",
+    }
+  }
+  return {
+    submitted: true,
+    submittedAt: new Date(submittedAt).toISOString(),
+  }
+}
+
+function inputValues(source: Source, data: Record<string, unknown>) {
+  const raw = data.values
+  if (raw == null) return {}
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw invalidState(source, "values must be a map.")
+  }
+  const values: InputValues = {}
+  for (const [name, value] of Object.entries(raw)) {
+    if (typeof value === "string") {
+      values[name] = value
+      continue
+    }
+    if (
+      Array.isArray(value) &&
+      value.every((item) => typeof item === "string")
+    ) {
+      values[name] = [...new Set(value)]
+      continue
+    }
+    throw invalidState(source, `${name} must be a string or string list.`)
+  }
+  return values
+}
+
+function parseInputState(
+  source: Source,
+  app: AppContext,
+): InputStateRecord | undefined {
+  const data = inputStateData(source, app.yaml)
+  if (!data) return
+  const originId =
+    typeof source.data.for === "string" ? source.data.for.trim() : ""
+  if (!originId) {
+    throw invalidState(source, "frontmatter for is required.")
+  }
+  try {
+    canonicalSourceId(originId)
+  } catch {
+    throw invalidState(source, "frontmatter for must be a canonical Source id.")
+  }
+  const actorId = app.actors.homeActorId(source.id)
+  if (!actorId) {
+    throw invalidState(source, "state must be stored in an Actor Home.")
+  }
+  const status = submission(data)
+  return {
+    actorId,
+    originId,
+    source,
+    data,
+    values: inputValues(source, data),
+    submitted: status.submitted,
+    ...(status.submittedAt ? { submittedAt: status.submittedAt } : {}),
+    ...(status.issue ? { statusIssue: status.issue } : {}),
+  }
+}
+
+function formatInputState(
+  origin: Source,
+  values: InputValues,
+  previous: InputStateRecord | undefined,
+  yaml: PathMXYaml,
+) {
+  const data = {
+    ...previous?.data,
+    values,
+    status: { type: "submitted", submitted_at: new Date().toISOString() },
+  }
+  const frontmatter = {
+    ...previous?.source.data,
+    type: "state",
+    for: origin.id,
+  }
+  return `${formatFrontmatter(frontmatter, yaml)}\n<!--\nplugin: input\n-->\n\n\`\`\`yaml @state\n${yaml.stringify(data).trimEnd()}\n\`\`\`\n`
+}
+
+export class InputStateIndex {
+  private statesByPath = new Map<string, InputStateRecord>()
+  private statesById = new Map<string, InputStateRecord>()
+  private statesByActorOrigin = new Map<string, InputStateRecord>()
+  private boundStateByOriginId = new Map<string, string>()
+  private boundOriginByPath = new Map<string, string>()
+
+  private key(actorId: string, originId: string) {
+    return `${actorId}\0${originId}`
+  }
+
+  index(source: Source, app: AppContext) {
+    const stateId = inputResponseConfig(source)?.state
+    const record = parseInputState(source, app)
+    if (record) {
+      const key = this.key(record.actorId, record.originId)
+      const existing = this.statesByActorOrigin.get(key)
+      if (existing && existing.source.path !== source.path) {
+        throw invalidState(
+          source,
+          `duplicate State for ${record.actorId} and ${record.originId}: ${existing.source.path} and ${source.path}.`,
+        )
+      }
+      this.statesByPath.set(source.path, record)
+      this.statesById.set(source.id, record)
+      this.statesByActorOrigin.set(key, record)
+    }
+    if (stateId) {
+      this.boundStateByOriginId.set(source.id, stateId)
+      this.boundOriginByPath.set(source.path, source.id)
+    }
+  }
+
+  unindex(sourcePath: string) {
+    const originId = this.boundOriginByPath.get(sourcePath)
+    if (originId) this.boundStateByOriginId.delete(originId)
+    this.boundOriginByPath.delete(sourcePath)
+    const record = this.statesByPath.get(sourcePath)
+    if (!record) return
+    this.statesByPath.delete(sourcePath)
+    this.statesById.delete(record.source.id)
+    this.statesByActorOrigin.delete(this.key(record.actorId, record.originId))
+  }
+
+  private get(actorId: string, originId: string) {
+    return this.statesByActorOrigin.get(this.key(actorId, originId))
+  }
+
+  records() {
+    return Object.freeze([...this.statesByPath.values()])
+  }
+
+  forActor(actorId: string, originId: string) {
+    const stateId = this.boundStateByOriginId.get(originId)
+    if (!stateId) return this.get(actorId, originId)
+    const state = this.statesById.get(stateId)
+    return state?.actorId === actorId && state.originId === originId
+      ? state
+      : undefined
+  }
+
+  resolve(origin: Source, actorId?: string): InputStateBinding {
+    const stateId = this.boundStateByOriginId.get(origin.id)
+    if (!stateId) {
+      return {
+        type: "actor-relative",
+        state: actorId ? this.get(actorId, origin.id) : undefined,
+      }
+    }
+    const state = this.statesById.get(stateId)
+    if (!state) {
+      throw new Error(
+        `Invalid input-response config in ${origin.path}: bound State does not resolve: ${stateId}.`,
+      )
+    }
+    if (state.originId !== origin.id) {
+      throw new Error(
+        `Invalid input-response config in ${origin.path}: ${stateId} points back to ${state.originId}, not ${origin.id}.`,
+      )
+    }
+    return { type: "bound", state }
+  }
+
+  isBound(origin: Source, stateId: string) {
+    return this.boundStateByOriginId.get(origin.id) === stateId
+  }
+
+  transition(source: Source | undefined, app: AppContext) {
+    return source ? parseInputState(source, app) : undefined
+  }
+
+  async write(
+    tx: SourceTransaction,
+    actor: UserActor,
+    origin: Source,
+    values: InputValues,
+    yaml: PathMXYaml,
+  ) {
+    const current = this.resolve(origin, actor.id).state
+    const content = formatInputState(origin, values, current, yaml)
+    if (current) {
+      await tx.update(current.source.id, content)
+      return
+    }
+    await tx.create(`${actor.home}/input${origin.id}.state`, content)
+  }
+}

package/plugins/layout.ts

@@ -0,0 +1,313 @@
+import { dependencyKey, type Dependency } from "../dependencies.ts"
+import { isIndexSource } from "../server/router.ts"
+import { type Source, type SourceLink } from "../source/index.ts"
+import {
+  isExactMarkdownSourceHref,
+  parseLinkFragments,
+} from "../source/markdown/links.ts"
+import { scanMarkdownStructure } from "../source/markdown/scan.ts"
+import { SourceDiagnosticError } from "../source-diagnostic.ts"
+import type { AppContext, DocumentAsset, PageContext, Plugin } from "./types.ts"
+
+const LAYOUT_TYPE = "layout"
+
+// TODO: replace this with a view component?
+const OUTLET_OPEN = /<pmx-content\b/gi
+const OUTLET = /<pmx-content\s*(?:\/\s*>|>\s*<\/pmx-content\s*>)/gi
+
+export const layoutDefaultDependency: Dependency = Object.freeze({
+  type: "plugin",
+  plugin: "layout",
+  key: "default",
+})
+
+function layoutTypeDependency(type: string): Dependency {
+  return { type: "plugin", plugin: "layout", key: `type:${type}` }
+}
+
+type LayoutRelations = Readonly<{
+  local?: SourceLink
+  defaults: ReadonlyMap<string, SourceLink>
+}>
+
+type CompiledLayout = Readonly<{
+  before: string
+  after: string
+  assets: readonly DocumentAsset[]
+  dependencies: readonly Dependency[]
+}>
+
+function layoutError(source: Source, message: string): never {
+  throw new SourceDiagnosticError({
+    source: source.path,
+    plugin: "layout",
+    message: `Invalid layout in ${source.path}: ${message}`,
+  })
+}
+
+function relationLinks(source: Source, indexed: boolean) {
+  if (indexed && source.blocks.length) {
+    return source.blocks.flatMap((block) => block.links)
+  }
+  if (indexed && source.links.length) return source.links
+  return parseLinkFragments(scanMarkdownStructure(source.body).linkFragments)
+}
+
+function readRelations(source: Source, indexed = true): LayoutRelations {
+  if (!source.body.includes("@layout")) return { defaults: new Map() }
+  const local: SourceLink[] = []
+  const defaults = new Map<string, SourceLink>()
+  for (const link of relationLinks(source, indexed)) {
+    if (link.directive?.name !== "layout") continue
+    if (link.kind !== "definition") {
+      layoutError(source, `@layout must use a reference definition.`)
+    }
+    const qualifiers = link.directive.qualifiers
+    if (!qualifiers.length) local.push(link)
+    else if (qualifiers.length === 1) {
+      const type = qualifiers[0]!
+      if (defaults.has(type)) {
+        layoutError(source, `multiple @layout.${type} definitions.`)
+      }
+      defaults.set(type, link)
+    } else {
+      layoutError(
+        source,
+        `@layout accepts one source type qualifier, received ${qualifiers.join(".")}.`,
+      )
+    }
+  }
+  if (local.length > 1) layoutError(source, `multiple @layout definitions.`)
+  return { local: local[0], defaults }
+}
+
+function defaultSignatures(source: Source | undefined, indexed: boolean) {
+  if (!source) return new Map<string, string>()
+  return new Map(
+    [...readRelations(source, indexed).defaults].map(([type, link]) => [
+      type,
+      link.href,
+    ]),
+  )
+}
+
+function changedDefaultDependencies(
+  before: Source | undefined,
+  after: Source | undefined,
+) {
+  const previous = defaultSignatures(before, true)
+  const next = defaultSignatures(after, false)
+  const changed: Dependency[] = []
+  for (const type of new Set([...previous.keys(), ...next.keys()])) {
+    if (previous.get(type) === next.get(type)) continue
+    changed.push(
+      type === "default" ? layoutDefaultDependency : layoutTypeDependency(type),
+    )
+  }
+  return changed
+}
+
+function exactMarkdownTarget(source: Source, link: SourceLink) {
+  const href = link.href.trim()
+  if (!isExactMarkdownSourceHref(href)) {
+    layoutError(
+      source,
+      `@layout must target an exact Markdown Source, received ${href}.`,
+    )
+  }
+  return href
+}
+
+function resolveLayout(
+  relationSource: Source,
+  consumer: Source,
+  link: SourceLink,
+  app: AppContext,
+) {
+  const href = exactMarkdownTarget(relationSource, link)
+  const edge = app.graph
+    .linksFrom(relationSource.path)
+    .find((candidate) => candidate.href === href && candidate.type === "source")
+
+  const target = edge?.to ? app.sources.get(edge.to) : undefined
+  if (!target) {
+    layoutError(relationSource, `layout Source not found: ${href}.`)
+  }
+  if (target.type === "components") {
+    app.log.warn("legacy-components", {
+      source: relationSource.path,
+      target: target.path,
+      detail: "Use an authored .layout.md Source for site layout.",
+    })
+    return
+  }
+  if (target.type !== LAYOUT_TYPE) {
+    layoutError(
+      relationSource,
+      `${href} is a ${target.type} Source, not a layout.`,
+    )
+  }
+  if (!app.access.canEmbed(consumer.id, target.id)) {
+    layoutError(consumer, `cannot embed layout ${target.path}.`)
+  }
+  return target
+}
+
+function splitOutlet(source: Source, html: string) {
+  const openings = [...html.matchAll(OUTLET_OPEN)]
+  const outlets = [...html.matchAll(OUTLET)]
+  if (openings.length !== 1 || outlets.length !== 1) {
+    layoutError(
+      source,
+      `expected exactly one empty <pmx-content />, found ${openings.length}.`,
+    )
+  }
+  const outlet = outlets[0]!
+  const start = outlet.index!
+  return {
+    before: html.slice(0, start),
+    after: html.slice(start + outlet[0].length),
+  }
+}
+
+function dependencyRecorder() {
+  const values: Dependency[] = []
+  const seen = new Set<string>()
+  return {
+    values,
+    depend(dependency: Dependency) {
+      const key = dependencyKey(dependency)
+      if (seen.has(key)) return
+      seen.add(key)
+      values.push(dependency)
+    },
+  }
+}
+
+/** Authored layout selection and composition over the normal plugin pipeline. */
+export function LayoutPlugin(): Plugin {
+  const defaults = new Map<
+    string,
+    Readonly<{ source: Source; links: ReadonlyMap<string, SourceLink> }>
+  >()
+  const compiled = new Map<string, Promise<CompiledLayout>>()
+
+  const compile = (source: Source, app: AppContext) => {
+    if (source.type !== LAYOUT_TYPE) {
+      layoutError(source, `expected a ${LAYOUT_TYPE} Source.`)
+    }
+    let pending = compiled.get(source.path)
+    if (pending) return pending
+    pending = (async () => {
+      const dependencies = dependencyRecorder()
+      const template = await app.compile.document(source, dependencies)
+      return {
+        ...splitOutlet(source, template.html),
+        assets: template.assets,
+        dependencies: dependencies.values,
+      }
+    })()
+    compiled.set(source.path, pending)
+    return pending
+  }
+
+  const selectedDefaults = (source: Source) => {
+    if (defaults.size > 1) {
+      layoutError(source, `multiple root-owned layout configurations.`)
+    }
+    const first = defaults.values().next()
+    return first.done ? undefined : first.value
+  }
+
+  const layoutChain = (source: Source, ctx: PageContext, app: AppContext) => {
+    if (source.data.layout === false) return []
+    const local = readRelations(source).local
+    let relation = local
+    let relationSource = source
+    if (!relation) {
+      const selected = selectedDefaults(source)
+      const typedDependency = layoutTypeDependency(source.type)
+      ctx.depend(typedDependency)
+      relation = selected?.links.get(source.type)
+      if (!relation) {
+        ctx.depend(layoutDefaultDependency)
+        relation = selected?.links.get("default")
+      }
+      relationSource = selected?.source ?? source
+    }
+    if (!relation) return []
+
+    const chain: Source[] = []
+    const seen = new Set([source.path])
+    let consumer = source
+    while (relation) {
+      const layout = resolveLayout(relationSource, consumer, relation, app)
+      if (!layout) break
+      if (seen.has(layout.path)) {
+        layoutError(
+          source,
+          `layout cycle: ${[...seen, layout.path].join(" -> ")}.`,
+        )
+      }
+      seen.add(layout.path)
+      chain.push(layout)
+      ctx.depend({ type: "source", path: layout.path })
+      consumer = layout
+      relationSource = layout
+      relation =
+        layout.data.layout === false ? undefined : readRelations(layout).local
+    }
+    return chain
+  }
+
+  return {
+    id: "layout",
+    schema: {
+      sources: {
+        layout: {
+          label: "Layout",
+          description: "Authored page chrome with one content outlet.",
+          icon: "panels-top-left",
+          color: "violet",
+        },
+      },
+    },
+
+    index(source, app) {
+      const relations = readRelations(source)
+      defaults.delete(source.path)
+      if (!relations.defaults.size) return
+      const root = app.sources.resolve("/")
+      if (!isIndexSource(source) || root?.path !== source.path) {
+        const qualifier = relations.defaults.keys().next().value
+        layoutError(
+          source,
+          `@layout.${qualifier} is owned by the root route Source only.`,
+        )
+      }
+      defaults.set(source.path, { source, links: relations.defaults })
+    },
+
+    unindex(sourcePath) {
+      defaults.delete(sourcePath)
+      compiled.clear()
+    },
+
+    invalidate({ before, after }) {
+      compiled.clear()
+      const dependencies = changedDefaultDependencies(before, after)
+      if (dependencies.length) return { dependencies }
+    },
+
+    async page(html, ctx, app) {
+      const chain = layoutChain(ctx.source, ctx, app)
+      for (const source of chain) {
+        const template = await compile(source, app)
+        for (const dependency of template.dependencies) ctx.depend(dependency)
+        ctx.addAsset(...template.assets)
+        html = `${template.before}${html}${template.after}`
+      }
+      return html
+    },
+  }
+}