@uniweb/kit 0.9.45 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.9.45",
+  "version": "0.10.0",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -40,7 +40,8 @@
     "fuse.js": "^7.0.0",
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
-    "@uniweb/core": "0.7.33",
+    "@uniweb/semantic-parser": "1.2.0",
+    "@uniweb/core": "0.8.0",
     "@uniweb/scene": "0.1.2"
   },
   "peerDependencies": {

package/src/hooks/useEntityDetail.js

@@ -44,7 +44,7 @@
  * }
  */
 
-import { getUniweb } from '@uniweb/core'
+import { getUniweb, recordDataUrl } from '@uniweb/core'
 import { useFetched } from './useFetched.js'
 
 /**
@@ -63,7 +63,19 @@ export function useEntityDetail(record, options = {}) {
   return useFetched(request)
 }
 
-function buildDetailRequest(record, collection) {
+/**
+ * Build the fetch request for one record's full payload.
+ *
+ * Exported for tests only — not re-exported from the package index. The
+ * static-file branch has to resolve to the same URL the build writes and the
+ * same URL core's dynamic-route auto-detail injects; a test can only assert
+ * that if it can call this without a React tree.
+ *
+ * @param {Object|null} record
+ * @param {string} collection
+ * @returns {{path?: string, url?: string, schema: string}|null}
+ */
+export function buildDetailRequest(record, collection) {
   const slug = record?.slug
   if (!slug || !collection) return null
 
@@ -83,10 +95,11 @@ function buildDetailRequest(record, collection) {
     return { url, schema: collection }
   }
 
-  // Static-file default — the build emitted per-record JSON files.
-  // Phase 5 of the CDN migration moved storage from /data/ to /_data/;
-  // the site router accepts both URL shapes during the transition.
-  return { path: `/_data/${collection}/${slug}.json`, schema: collection }
+  // Static-file default — the build emitted per-record JSON files. Shares
+  // `recordDataUrl` with the build that writes them and with core's
+  // dynamic-route auto-detail injection, which is the other half of this
+  // same feature: the three must resolve one record to one URL.
+  return { path: recordDataUrl(collection, slug), schema: collection }
 }
 
 export default useEntityDetail

package/src/hooks/useThemeData.js

@@ -55,9 +55,14 @@ function readAppliedScheme() {
  * Returns the Theme instance which provides methods like:
  * - getColor(name, shade) - Get a color value
  * - getPalette(name) - Get all shades for a color
- * - getContextToken(context, token) - Get semantic token
  * - getAppearance() - Get appearance configuration
  *
+ * For a semantic token's ACTUAL value at some element, read the CSS variable
+ * rather than asking the theme: getComputedStyle(el).getPropertyValue('--heading').
+ * Only that accounts for the section's own `theme:` overrides and the active
+ * light/dark scheme. (`getContextToken`/`getContextTokens` were removed in
+ * 2026-07-28 for exactly this reason — see the note in @uniweb/core's theme.js.)
+ *
  * @returns {Theme|null} Theme instance or null if not available
  *
  * @example

package/src/index.js

@@ -131,7 +131,8 @@ export {
 // Styled Components (Tailwind-based)
 // ============================================================================
 
-export { Section, Render } from './styled/Section/index.js'
+export { Section } from './styled/Section/index.js'
+export { Render, SequenceElement } from './styled/Render/index.jsx'
 export { Prose } from './styled/Prose/index.jsx'
 export { Article } from './styled/Article/index.jsx'
 export { Code, Alert, Warning, Table, Details, Divider } from './styled/Section/renderers/index.js'

package/src/styled/Article/index.jsx

@@ -1,84 +1,54 @@
 /**
- * Article Component
+ * Article — a document, in a semantic <article>.
  *
- * Semantic article wrapper with prose typography.
- * Use for blog posts, news articles, documentation pages, etc.
+ * `<Prose>` with the right tag. That is the whole component now, and the point
+ * of it is the element: an article is a self-contained composition, and saying
+ * so in markup is what assistive technology and reader modes act on.
+ *
+ * It used to be its own thing — a prose container wrapped around a SECOND node
+ * walker that read raw ProseMirror. That is why articles rendered with no bold,
+ * no links and no math until 2026-07-30: the walker's `paragraph` case
+ * flattened inline content to plain text, and it had no case for math at all.
+ * Going through `<Render>` means there is one walk, and inline content arrives
+ * from the parser already correct.
  *
  * @module @uniweb/kit/styled/Article
  */
 
 import React from 'react'
-import { cn } from '../../utils/index.js'
-import { Render } from '../Section/Render.jsx'
-
-/**
- * Prose sizes
- */
-const SIZE_CLASSES = {
-  sm: 'prose-sm',
-  base: 'prose-base',
-  lg: 'prose-lg',
-  xl: 'prose-xl',
-  '2xl': 'prose-2xl'
-}
+import { Prose } from '../Prose/index.jsx'
 
 /**
  * Article - Semantic article with prose typography
  *
- * Renders content inside a semantic <article> tag with prose styling.
- * Can accept either children or a content prop (ProseMirror JSON).
- *
  * @param {Object} props
- * @param {Object|Array} [props.content] - ProseMirror content to render
+ * @param {Object|Array} [props.content] - Parsed content (`.sequence`), a
+ *   ProseMirror doc, or an array of ProseMirror nodes
+ * @param {Object} [props.block] - Block instance (supplies content; resolves insets)
+ * @param {Object} [props.components] - Per-element-type renderer overrides
  * @param {string} [props.size='lg'] - Text size: sm, base, lg, xl, 2xl
  * @param {string} [props.className] - Additional CSS classes
- * @param {React.ReactNode} [props.children] - Content to render (alternative to content prop)
+ * @param {React.ReactNode} [props.children] - Content to render (alternative to content)
  *
  * @example
- * // With ProseMirror content
  * <Article content={articleData.content} />
  *
  * @example
- * // With children
- * <Article>
- *   <h1>My Article</h1>
- *   <p>Article content...</p>
- * </Article>
- *
- * @example
- * // Composing with Render
- * <Article size="base" className="dark:prose-invert">
- *   <Render content={proseMirrorContent} />
- * </Article>
+ * <Article block={block} components={{ blockquote: PullQuote }} />
  */
-export function Article({
-  content,
-  block,
-  size = 'lg',
-  className,
-  children,
-  ...props
-}) {
-  const sizeClass = SIZE_CLASSES[size] || SIZE_CLASSES.lg
-
-  // Get content from block if not provided directly
-  let resolvedContent = content
-  if (!resolvedContent && block) {
-    resolvedContent = block.rawContent
-  }
-
-  // If it's a ProseMirror doc, get the content array
-  if (resolvedContent?.type === 'doc') {
-    resolvedContent = resolvedContent.content
-  }
-
+export function Article({ content, block, components, size = 'lg', className, children, ...props }) {
   return (
-    <article
-      className={cn('prose', sizeClass, 'max-w-none', className)}
+    <Prose
+      as="article"
+      content={content}
+      block={block}
+      components={components}
+      size={size}
+      className={className}
       {...props}
     >
-      {children || (resolvedContent && <Render content={resolvedContent} />)}
-    </article>
+      {children}
+    </Prose>
   )
 }
 

package/src/styled/Media/Media.jsx

@@ -202,11 +202,34 @@ function PlayButton({ onClick, className }) {
  * @example
  * // Local video
  * <Media src="/videos/intro.mp4" controls autoplay={false} />
+ *
+ * @example
+ * // A video authored in markdown, delivered via content.videos[]
+ * // ![Demo](./demo.mp4){role=video poster=./thumb.jpg autoplay muted loop}
+ * <Visual video={content.videos[0]} />
  */
 export function Media({
   src,
   media,
   thumbnail,
+  // Same concept, three producers. `thumbnail` is this component's own prop;
+  // `poster` is the authored markdown spelling (`{role=video poster=…}`, and
+  // what @uniweb/build auto-generates when it is absent); `coverImg` is what
+  // the editor's Video node carries. All three named here because a video
+  // entry from `content.videos[]` is spread straight in — `<Media {...video} />`
+  // via <Visual> — so an unrecognised one would land on the wrapper div, where
+  // it does nothing and React warns.
+  poster,
+  coverImg,
+  // Also part of the delivered video shape. Absorbed rather than forwarded:
+  // the reference documents wrapping media in a link as the FOUNDATION's job
+  // (docs/reference/content-structure.md, "Clickable Images and Videos"), so
+  // these are the author's to use, not this component's to consume.
+  alt,
+  role,
+  href,
+  target,
+  caption: captionProp,
   autoplay = false,
   muted = false,
   loop = false,
@@ -222,13 +245,14 @@ export function Media({
 
   // Normalize source
   const videoSrc = typeof src === 'string' ? src : (src?.src || media?.src || '')
-  const caption = media?.caption || src?.caption || ''
+  const caption = captionProp || media?.caption || src?.caption || ''
 
   // Detect video type
   const mediaType = detectMediaType(videoSrc)
 
   // Get thumbnail
-  const thumbnailSrc = thumbnail || getVideoThumbnail(videoSrc, mediaType)
+  const thumbnailSrc =
+    thumbnail || poster || coverImg || getVideoThumbnail(videoSrc, mediaType)
 
   // Handle play click (for facade mode)
   const handlePlay = useCallback(() => {

package/src/styled/Prose/index.jsx

@@ -1,27 +1,29 @@
 /**
- * Prose Component
+ * Prose — content plus prose typography.
  *
- * Renders the prose (narrative) portions of parsed content from content.sequence.
- * Data blocks (tagged code blocks, dataBlocks) are skipped — they're structured
- * data, not prose. Access them via content.data instead.
+ * `<Render>` walks the sequence; this adds the Tailwind Typography container
+ * that styles the semantic markup it emits. Two concerns, deliberately separate:
+ * a foundation with its own type system uses `<Render>` and lays out the
+ * elements itself.
  *
- * Also works as a pure typography wrapper when given children instead of content.
+ * Typography comes from a plugin the FOUNDATION installs — kit ships no
+ * stylesheet — and answers to the site's `theme.yml` through
+ * `@uniweb/kit/prose-tokens.css`. See that file for the two rules that bite:
+ * one prose container per subtree (the variables are inherited, so a nested one
+ * silently resets its subtree), and no palette modifier (`prose-gray` and
+ * friends re-declare every variable and defeat the theme bridge).
+ *
+ * Also works as a pure typography wrapper when given children instead of
+ * content.
  *
  * @module @uniweb/kit/styled/Prose
  */
 
 import React from 'react'
-import { cn, getChildBlockRenderer, headingId } from '../../utils/index.js'
-import { SafeHtml } from '../../components/SafeHtml/index.js'
-import { Image } from '../../components/Image/index.js'
-import { Media } from '../../components/Media/index.js'
-import { Icon } from '../../components/Icon/index.js'
-import { Link } from '../../components/Link/index.js'
-import { Code } from '../Section/renderers/Code.jsx'
+import { cn } from '../../utils/index.js'
+import { Render } from '../Render/index.jsx'
 
-/**
- * Prose sizes
- */
+/** Prose sizes */
 const SIZE_CLASSES = {
   sm: 'prose-sm',
   base: 'prose-base',
@@ -30,215 +32,14 @@ const SIZE_CLASSES = {
   '2xl': 'prose-2xl'
 }
 
-
-const INLINE_INSET_RE = /<uniweb-inset data-ref-id="([^"]+)"><\/uniweb-inset>/g
-
 /**
- * Render an HTML paragraph fragment that contains inline-inset markers
- * (`<uniweb-inset data-ref-id="…">`). The fragment is split at marker
- * boundaries; HTML chunks render via SafeHtml, marker positions render
- * via the framework's child-block renderer (the same path block-level
- * insets use, scoped to a single inset block).
- *
- * Components rendered through this path return an inline element
- * (typically a `<span>`) so the paragraph stays a single line of prose.
- */
-function renderParagraphWithInsets(html, block) {
-  if (!block) return <SafeHtml value={html} as="span" />
-  const InsetRenderer = getChildBlockRenderer()
-  const parts = []
-  let lastIdx = 0
-  INLINE_INSET_RE.lastIndex = 0
-  let match
-  while ((match = INLINE_INSET_RE.exec(html)) !== null) {
-    if (match.index > lastIdx) {
-      parts.push(
-        <SafeHtml
-          key={`t${lastIdx}`}
-          value={html.slice(lastIdx, match.index)}
-          as="span"
-        />
-      )
-    }
-    const refId = match[1]
-    const insetBlock = block.getInset?.(refId)
-    if (insetBlock && InsetRenderer) {
-      parts.push(<InsetRenderer key={`i${refId}`} blocks={[insetBlock]} />)
-    }
-    lastIdx = match.index + match[0].length
-  }
-  if (lastIdx < html.length) {
-    parts.push(
-      <SafeHtml key={`t${lastIdx}`} value={html.slice(lastIdx)} as="span" />
-    )
-  }
-  return parts
-}
-
-/**
- * Render a single sequence element to React
- */
-function SequenceElement({ element, block }) {
-  if (!element) return null
-
-  switch (element.type) {
-    case 'heading': {
-      const level = Math.min(element.level || 1, 6)
-      const Tag = `h${level}`
-      const id = headingId(element.text || '')
-      return <Tag id={id}><SafeHtml value={element.text} as="span" /></Tag>
-    }
-
-    case 'paragraph': {
-      if (!element.text) return null
-      // Inline insets ride through the paragraph text as
-      // `<uniweb-inset data-ref-id="…"></uniweb-inset>` markers (see
-      // semantic-parser's getTextContent). When any are present, walk
-      // the text once and intersperse React-rendered insets at the
-      // marker positions; otherwise stick to the fast SafeHtml path.
-      if (/<uniweb-inset/.test(element.text)) {
-        return <p>{renderParagraphWithInsets(element.text, block)}</p>
-      }
-      return <p><SafeHtml value={element.text} as="span" /></p>
-    }
-
-    case 'image': {
-      const { url, alt, caption, role } = element.attrs || {}
-      if (role === 'icon') {
-        return <Icon {...element.attrs} />
-      }
-      return (
-        <figure>
-          <Image src={url} alt={alt || caption || ''} />
-          {caption && <figcaption>{caption}</figcaption>}
-        </figure>
-      )
-    }
-
-    case 'video': {
-      return <Media src={element.attrs?.src} />
-    }
-
-    case 'codeBlock': {
-      return <Code content={element.text || ''} language={element.attrs?.language || ''} />
-    }
-
-    case 'dataBlock':
-      return null
-
-    case 'math': {
-      // Math from $$...$$ on its own line, ```math fence, or inline
-      // $...$ (the inline form doesn't reach the sequence walker — it
-      // rides inside paragraph HTML — but render the same way for
-      // safety in case a future caller surfaces it here). Mathml is
-      // pre-compiled at parse time; the browser renders real MathML
-      // natively. Foundations that want to style errors can target
-      // .temml-error inside this wrapper.
-      if (!element.mathml) return null
-      const display = element.display !== false
-      const Tag = display ? 'div' : 'span'
-      return (
-        <Tag
-          className={display ? 'math-display' : 'math-inline'}
-          dangerouslySetInnerHTML={{ __html: element.mathml }}
-        />
-      )
-    }
-
-    case 'list': {
-      const Tag = element.style === 'ordered' ? 'ol' : 'ul'
-      return (
-        <Tag>
-          {element.children?.map((itemSeq, i) => (
-            <li key={i}>
-              {itemSeq.map((el, j) => (
-                <SequenceElement key={j} element={el} block={block} />
-              ))}
-            </li>
-          ))}
-        </Tag>
-      )
-    }
-
-    case 'blockquote': {
-      return (
-        <blockquote>
-          {element.children?.map((el, i) => (
-            <SequenceElement key={i} element={el} block={block} />
-          ))}
-        </blockquote>
-      )
-    }
-
-    case 'inset_block': {
-      // A component reference that carries block content — the block form of
-      // an inset. Children recurse; flattening them to text is what the
-      // sequence's default branch used to do, and it lost the body.
-      //
-      // Reaching this case means the container was NOT lifted — `@uniweb/core`
-      // rewrites `inset_block` to `inset_placeholder` when it builds the render
-      // graph, and the `inset` case resolves that against the foundation. This
-      // is the fallback for a document rendered without a Block behind it.
-      //
-      // kit does NOT map the name to one of its own components — see the longer
-      // note in Section/Render. A visible generic box; never a drop.
-      const body = element.children?.map((el, i) => (
-        <SequenceElement key={i} element={el} block={block} />
-      ))
-
-      return (
-        <div
-          data-inset-block={element.component || 'unknown'}
-          className="border border-border rounded-md p-4 my-4"
-        >
-          {body}
-        </div>
-      )
-    }
-
-    case 'link': {
-      const { href, label, role } = element.attrs || {}
-      // Standalone links promoted from paragraphs
-      return <p><Link to={href}>{label}</Link></p>
-    }
-
-    case 'button': {
-      return <p><Link to={element.attrs?.href}>{element.text}</Link></p>
-    }
-
-    case 'divider':
-      return <hr />
-
-    case 'inset': {
-      if (!block || !element.refId) return null
-      const insetBlock = block.getInset(element.refId)
-      if (!insetBlock) return null
-      const InsetRenderer = getChildBlockRenderer()
-      if (!InsetRenderer) return null
-      return <InsetRenderer blocks={[insetBlock]} />
-    }
-
-    case 'icon': {
-      return <Icon {...element.attrs} />
-    }
-
-    default:
-      return null
-  }
-}
-
-/**
- * Prose - Renders the narrative content from a parsed content sequence
- *
- * Skips data blocks (tagged code blocks, dataBlocks) — those are structured
- * data accessible via content.data, not prose to render.
- *
- * Pass `content` (the parsed content object from component props).
- * Optionally pass `block` for inset resolution.
+ * Prose - Rendered content with prose typography
  *
  * @param {Object} props
- * @param {Object} [props.content] - Parsed content object (has .sequence)
- * @param {Object} [props.block] - Block instance (needed for inset resolution)
+ * @param {Object|Array} [props.content] - Parsed content (`.sequence`), a
+ *   ProseMirror doc, or an array of ProseMirror nodes
+ * @param {Object} [props.block] - Block instance (supplies content; resolves insets)
+ * @param {Object} [props.components] - Per-element-type renderer overrides
  * @param {string} [props.size='lg'] - Text size: sm, base, lg, xl, 2xl
  * @param {string} [props.as='div'] - HTML element to render as
  * @param {string} [props.className] - Additional CSS classes
@@ -251,20 +52,24 @@ function SequenceElement({ element, block }) {
  * }
  *
  * @example
- * // Access data blocks separately
+ * // Render one element type your own way — the foundation's design, kit's walk
+ * <Prose content={content} block={block} components={{ concept_block: Faq }} />
+ *
+ * @example
+ * // Access data blocks separately — they are deliberately not rendered
  * <Prose content={content} block={block} />
  * {content.data.quiz && <Quiz data={content.data.quiz} />}
  *
  * @example
- * // Pure typography wrapper (backward compatible)
+ * // Pure typography wrapper
  * <Prose size="base">
  *   <h2>Title</h2>
- *   <p>Content...</p>
  * </Prose>
  */
 export function Prose({
   block,
   content,
+  components,
   size = 'lg',
   as: Component = 'div',
   className,
@@ -272,19 +77,10 @@ export function Prose({
   ...props
 }) {
   const sizeClass = SIZE_CLASSES[size] || SIZE_CLASSES.lg
-  const sequence = content?.sequence
 
   return (
-    <Component
-      className={cn('prose', sizeClass, 'max-w-none', className)}
-      {...props}
-    >
-      {sequence
-        ? sequence.map((element, i) => (
-            <SequenceElement key={i} element={element} block={block} />
-          ))
-        : children
-      }
+    <Component className={cn('prose', sizeClass, 'max-w-none', className)} {...props}>
+      {children ?? <Render content={content} block={block} components={components} />}
     </Component>
   )
 }