@uniweb/kit 0.19.7 → 0.19.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.19.7",
+  "version": "0.19.9",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -43,10 +43,11 @@
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
     "temml": "^0.13.2",
-    "@uniweb/projections": "^0.7.6",
-    "@uniweb/core": "^0.32.0",
+    "@uniweb/core": "^0.33.0",
+    "@uniweb/projections": "^0.7.9",
+    "@uniweb/semantic-parser": "^1.4.1",
     "@uniweb/scene": "^0.1.3",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/schemas": "^0.8.3"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/components/SectionBackground/SectionBackground.jsx

@@ -0,0 +1,36 @@
+/**
+ * SectionBackground — the background the author set on a section, drawn by the runtime's own
+ * renderer, for a component that places it itself.
+ *
+ * The runtime draws a section's background behind every section, so most components need
+ * nothing. A component that paints its own — a hero with a built-in gradient, a background
+ * that belongs inside a card — declares `background: 'self'` in its `meta.js`, and the runtime
+ * then draws none. With this it can still draw what the author chose, wherever it wants,
+ * without rebuilding the image, video, gradient and overlay handling.
+ *
+ * It fills the nearest positioned ancestor (`position: absolute; inset: 0`), so place it inside
+ * an element with `position: relative`, before the content.
+ *
+ * @param {Object} props
+ * @param {Object} props.block - The section's block — its `block.background`, normalized by core
+ * @param {string} [props.className] - Classes on the background layer
+ *
+ * @example
+ * function Hero({ content, block }) {
+ *   return (
+ *     <section className="relative">
+ *       <SectionBackground block={block} />
+ *       <div className="relative z-10">…</div>
+ *     </section>
+ *   )
+ * }
+ */
+export function SectionBackground({ block, className }) {
+  const background = block?.background
+  if (!background?.mode) return null
+  const Renderer = globalThis.uniweb?.backgroundRenderer
+  if (!Renderer) return null
+  return <Renderer {...background} className={className} />
+}
+
+export default SectionBackground

package/src/components/SectionBackground/index.js

@@ -0,0 +1 @@
+export { SectionBackground, default } from './SectionBackground.jsx'

package/src/hooks/useThemeData.js

@@ -89,31 +89,28 @@ export function useThemeData() {
 }
 
 /**
- * Get the current section's color context.
+ * The color context a section renders in: `'light'`, `'medium'` or `'dark'`.
  *
- * Note: This requires the component to receive the block prop.
- * For components that don't have block access, use a default or pass context explicitly.
+ * A section pinned with `theme:` renders in that context. One that follows the site — no
+ * `theme:` — renders in the site's current scheme, so on a dark-scheme site it is `'dark'`.
+ * This is how a component reads its context for its own logic, a light or dark logo say:
+ * `theme` is a setting of the section, never one of the component's params. ⛔ Until
+ * 2026-09-28 a section that follows the site read as `'light'` whatever the scheme.
  *
- * @param {Object} block - Block instance (optional)
- * @returns {string} Context name ('light', 'medium', or 'dark')
+ * @param {Object} block - The section's Block
+ * @returns {'light'|'medium'|'dark'}
  *
  * @example
- * function MyComponent({ block }) {
+ * function Logo({ block }) {
  *   const context = useColorContext(block)
- *   return <div className={`context-${context}`}>...</div>
+ *   return <img src={context === 'dark' ? '/logo-light.svg' : '/logo.svg'} alt="" />
  * }
  */
 export function useColorContext(block) {
-  // Get context from block's theme property
-  const context = block?.themeName || block?.theme || 'light'
-
-  // Validate context name
-  const validContexts = ['light', 'medium', 'dark']
-  if (validContexts.includes(context)) {
-    return context
-  }
-
-  return 'light'
+  const { scheme } = useAppearance()
+  const pinned = block?.themeName
+  if (pinned === 'light' || pinned === 'medium' || pinned === 'dark') return pinned
+  return scheme === 'dark' ? 'dark' : 'light'
 }
 
 /**

package/src/index.js

@@ -40,6 +40,9 @@ export { Asset } from './components/Asset/index.js'
 // Data loading
 export { DataPlaceholder } from './components/DataPlaceholder.jsx'
 
+// A section's background, for a component that draws it itself (`background: 'self'`)
+export { SectionBackground } from './components/SectionBackground/index.js'
+
 // Social
 export {
   SocialIcon,
@@ -158,6 +161,7 @@ export { Article } from './styled/Article/index.jsx'
 export { Code, Alert, Warning, Table, Details, Divider } from './styled/Section/renderers/index.js'
 export { Disclaimer } from './styled/Disclaimer/index.js'
 export { Visual } from './styled/Visual/index.jsx'
+export { ChildGrid } from './styled/ChildGrid/index.jsx'
 export { Scene } from './styled/Scene/index.jsx'
 
 // ============================================================================

package/src/styled/ChildGrid/index.jsx

@@ -0,0 +1,74 @@
+/**
+ * ChildGrid — a section's child sections, laid out in the columns its author chose.
+ *
+ * The author chooses with the section's reserved `grid:` key — `3` (equal columns) or
+ * `'40/60'` (relative widths) — one of the layouts the component offers in `meta.js`
+ * (`children: { grid: [2, 3, '40/60'] }`). A component opts in by rendering its
+ * children through this, so what a visual editor draws from the same value
+ * (`gridTemplate`, `@uniweb/schemas/grid`) is what renders.
+ *
+ * Narrow screens get one column; from the `md` breakpoint a layout of up to two
+ * columns applies as chosen and a wider one shows two equal columns; from `lg` the
+ * chosen layout applies whatever its width.
+ *
+ * ⭐ Each child renders as a section, in a `div`: its own `theme:` and `background:`
+ * apply, and it carries the `section-{id}` its theme rules select [2026-09-28]. ⛔ Until
+ * then the children rendered bare, and a child's theme and background did nothing.
+ *
+ * @module @uniweb/kit/styled/ChildGrid
+ */
+
+import React from 'react'
+import { parseGrid, gridTemplate } from '@uniweb/schemas/grid'
+import { ChildBlocks, cn } from '../../utils/index.js'
+
+const TWO_EQUAL = 'repeat(2, minmax(0, 1fr))'
+
+/**
+ * @param {Object} props
+ * @param {Object} props.from - the section's Block; its `childBlocks` are laid out
+ * @param {number|string} [props.fallback] - the layout when the section chose none
+ *   (or chose something that is not a layout) — the component's default
+ * @param {boolean} [props.headerRow] - the first child spans every column
+ * @param {string} [props.className] - classes on the grid, e.g. a gap (`gap-8` by default)
+ * @param {string} [props.cellClassName] - classes on each child's cell
+ *
+ * @example
+ * <ChildGrid from={block} fallback={3} headerRow={params.headerRow} className="gap-6" />
+ */
+export function ChildGrid({ from: block, fallback = null, headerRow = false, className, cellClassName }) {
+  const children = block?.childBlocks || []
+  if (children.length === 0) return null
+
+  const choice = parseGrid(block.grid) ? block.grid : fallback
+  const layout = parseGrid(choice)
+  const style = layout
+    ? {
+        '--uniweb-grid-cols': gridTemplate(choice),
+        '--uniweb-grid-cols-md': layout.columns <= 2 ? gridTemplate(choice) : TWO_EQUAL,
+      }
+    : undefined
+
+  return (
+    <div
+      className={cn(
+        'grid grid-cols-1 gap-8',
+        layout && 'md:grid-cols-[var(--uniweb-grid-cols-md)] lg:grid-cols-[var(--uniweb-grid-cols)]',
+        className
+      )}
+      style={style}
+      data-grid={layout ? String(choice) : undefined}
+    >
+      {children.map((child, index) => (
+        <div
+          key={child.id || index}
+          className={cn(headerRow && index === 0 && 'md:col-span-full', cellClassName)}
+        >
+          <ChildBlocks blocks={[child]} wrapAs="div" />
+        </div>
+      ))}
+    </div>
+  )
+}
+
+export default ChildGrid

package/src/styled/Render/index.jsx

@@ -87,14 +87,15 @@ export const NOT_RENDERED = {
   dataBlock:
     'structured data, not prose — a component reads it from content.data[tag]',
   inset_ref:
-    'a BUILD-TIME intermediate. The reader emits it for `![](@Component)`; the ' +
-    'build\'s content-collector extracts it into the section\'s insets and leaves ' +
+    'the stored form of a leaf inset (`![](@Component)`, `[@key]`, `[#id]`). ' +
+    '@uniweb/core lifts it when it builds a Block — a placeholder in place, a ' +
+    'Block in `block.insets` — so a section\'s content reaches this renderer as ' +
     'an `inset_placeholder`, which is what the `inset` case resolves. Its attrs ' +
     'carry a component NAME and no refId, so there is nothing here to look up — ' +
     'and kit answering for the name is the shadowing the inset_block case ' +
-    'refuses. Consequence worth knowing: a document rendered straight from ' +
-    'markdown without that build step (a record body, say) loses its ' +
-    'inline component references.',
+    'refuses. Consequence worth knowing: a document rendered here WITHOUT a Block ' +
+    'built over it (a record\'s body passed straight in, say) keeps its ' +
+    'inset_ref nodes, and they render nothing.',
   form: 'an editor node; its data reaches components as content.data[schemaId]',
   'card-group': 'an editor node, deprecated — maps to content.data[cardType]',
   'document-group': 'an editor node — its documents reach content.links',

package/src/styled/index.js

@@ -42,6 +42,9 @@ export { Disclaimer } from './Disclaimer/index.js'
 // Visual - Unified visual renderer (inset > video > image)
 export { Visual } from './Visual/index.jsx'
 
+// ChildGrid - A section's child sections in the columns its `grid:` chose
+export { ChildGrid } from './ChildGrid/index.jsx'
+
 // Media - Video player with styled play button facade
 export { Media } from './Media/index.js'