uniweb 1.27.0 → 1.27.2

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,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.27.0",
3
+ "version": "1.27.2",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -41,10 +41,10 @@
41
41
  "js-yaml": "^4.3.2",
42
42
  "prompts": "^2.4.2",
43
43
  "tar": "^7.5.21",
44
- "@uniweb/content-writer": "~1.3.1",
45
44
  "@uniweb/core": "~1.6.4",
46
45
  "@uniweb/semantic-parser": "~1.13.2",
47
- "@uniweb/schemas": "~1.6.8"
46
+ "@uniweb/content-writer": "~1.3.1",
47
+ "@uniweb/schemas": "~1.6.9"
48
48
  },
49
49
  "peerDependencies": {
50
50
  "@uniweb/build": "~1.16.0",
@@ -292,7 +292,7 @@ import { H1, P, Prose, Visual, Icon, Link, ChildBlocks, Overlay, PlainText } fro
292
292
  export default {
293
293
  title: 'Feature Grid', description: 'Grid of feature cards with icons',
294
294
  family: 'features', // the standard kind it is (`uniweb families`); a name like `Hero` resolves on its own
295
- // hidden: true · inset: true · section: true · children: true · background: 'self' · sticky: true
295
+ // hidden: true · inset: true · area: true · section: true · children: true · background: 'self' · sticky: true
296
296
  content: { title: 'Heading', paragraphs: 'Intro [0-1]', media: 'Photo [1]',
297
297
  items: { label: 'Cards [3-6]', content: { icon: 'Icon [1]', title: 'Name', paragraphs: 'Text' } } },
298
298
  params: { columns: { type: 'number', default: 3 },
@@ -4,7 +4,7 @@ Lane guide — AGENTS.md procedure step 6 loads it before any content is written
4
4
 
5
5
  ## Sections
6
6
 
7
- **A section with no `type:` renders through the foundation's default section type** — a component named `Section`, unless the foundation's `main.js` sets `defaultSection`. This is what lets a folder of plain markdown with no frontmatter become pages: mounted documentation, an imported wiki. If such content renders blank, the foundation has no `Section` — that, not the markdown, is what to fix.
7
+ **A section with no `type:` renders through the foundation's default section type** — the `defaultSection` its `main.js` sets, else a section type named `Section` where the foundation has one, the fallback for foundations that declare none. This is what lets a folder of plain markdown with no frontmatter become pages: mounted documentation, an imported wiki. If such content shows "Component not found", the foundation has neither: declare `defaultSection` in its `main.js`, naming the type that content should render with. `uniweb doctor` states each foundation's default, and suggests one where a type stands out.
8
8
 
9
9
  **Content before the first heading changes the parse:** headings after body content become items, not the section title. That's how repeating groups are made. An icon counts: `![](lu-globe)` above `# Title` leaves `content.title` empty and puts the heading in `items[0]`. For an icon that belongs to the title, write it under the heading, where it is still `content.icons[0]`; `uniweb inspect` shows the shape, and warns about an icon above one heading. An image above the title empties it too, with the heading in `content.headings` and no warning.
10
10
 
@@ -226,7 +226,7 @@ Colors, tokens, light and dark, fonts and `styles.css` are in `uniweb guide them
226
226
 
227
227
  **A data block whose value is a schema** — an author-designed form at `content.data.form` — is the inverse of every other component: declare the key, receive the fields, draw what you're given. You may declare a schema of the *envelope* (`title`, `description`, `fields`) for validation, never of the form's own fields.
228
228
 
229
- **Insets** are full section types: `{ content, params, block }`, alt text → `content.title`, attributes → `params`. `inset: true` in `meta.js`; add `section: true` for a component placed both ways. The hosting section declares a `media` slot and renders `<Visual>`, so one type works whether the author supplies an image, a video or an interactive component. Don't use `hidden: true` on insets — that means "never export".
229
+ **Insets** are full section types: `{ content, params, block }`, alt text → `content.title`, attributes → `params`. `inset: true` in `meta.js`; add `section: true` for a component placed both ways. A component meant for a layout area (a header, a footer, a side panel) says `area: true`, and an editor leaves it out of a page's sections; `section: true` again for both. The hosting section declares a `media` slot and renders `<Visual>`, so one type works whether the author supplies an image, a video or an interactive component. Don't use `hidden: true` on insets — that means "never export".
230
230
 
231
231
  **Block insets** get their whole body parsed (`title`, `paragraphs`, `items`, `sequence`); render with `<Prose content={content} block={block} />` or read fields. Prefer a child section when the author needs their own type and independent editing; a block inset when the wrapper is presentational and inline.
232
232
 
@@ -76,7 +76,7 @@ const { submit, status, error, canSubmit } = useFormSubmit({
76
76
  if (!canSubmit) return null // check at render, not on the button press
77
77
  ```
78
78
 
79
- `status`: `idle → submitting → success | error`; a non-2xx becomes a thrown `Error` carrying the endpoint's `error` message. File fields: pass `files`; the endpoint replies with `uploadUrls`, and bytes never ride inside the JSON. `submitForm()` / `resolveSubmitTarget(website)` are the same without React. A failed read leaves its key `null`, with the message on `block.dataError[key]`; a write that 404s loses what a person typed, so it gets no silent fallback.
79
+ `status`: `idle → submitting → success | error`; a non-2xx becomes a thrown `Error` carrying the endpoint's `error` message. File fields: pass `files`; the endpoint replies with `uploadUrls`, and bytes never ride inside the JSON. `submitForm()` / `resolveSubmitTarget(website)` are the same without React. A host that protects its address names a `challenge` beside `endpoint`; the hook then solves an ALTCHA v1 puzzle and sends `X-Proof` itself, so a form needs no change (`sendWithProof` + `resolveServiceAddress(website, name, 'challenge')` for any other service). A failed read leaves its key `null`, with the message on `block.dataError[key]`; a write that 404s loses what a person typed, so it gets no silent fallback.
80
80
 
81
81
  **Rendering an author-designed form** (`yaml:form` at `content.data.form`): you don't declare the fields, you receive them. `useFormValues` owns what's identical in every such component:
82
82
 
@@ -989,8 +989,17 @@ export function writeItemBaseVersions(siteDir, backend, versions) {
989
989
  export function readHeldUnits(siteDir, backend) {
990
990
  return readMap(siteDir, backend, 'heldUnits')
991
991
  }
992
- export function writeHeldUnits(siteDir, backend, held) {
993
- updateSyncCache(siteDir, backend, { heldUnits: { ...(held || {}) } })
992
+ /**
993
+ * Record what a pull held: its units as the files keep them (`heldUnits`), and the `$uuid` of every
994
+ * item it held (`heldItems`), by which a push tells a held page in the backend's document, where the
995
+ * app may keep it under another path, from a change of someone else's.
996
+ */
997
+ export function writeHeldUnits(siteDir, backend, held, items = []) {
998
+ updateSyncCache(siteDir, backend, { heldUnits: { ...(held || {}) }, heldItems: [...new Set(items)].sort() })
999
+ }
1000
+ export function readHeldItems(siteDir, backend) {
1001
+ const items = readSyncCacheFile(siteDir, backend).heldItems
1002
+ return Array.isArray(items) ? items : []
994
1003
  }
995
1004
 
996
1005
  /**
@@ -3110,11 +3119,18 @@ export async function pushSyncPackages({
3110
3119
  // (The site-content lane's own state was settled when it landed — `settleSiteContent`.)
3111
3120
  // What the backend holds that this copy doesn't. None of it was overwritten, and no
3112
3121
  // later push will overwrite it — but the files are behind until a pull.
3113
- if (notHeld.kept.length || notHeld.foreign.length) {
3122
+ // A page a pull held is not one of these: the push left it out and said so (`noteHeldLeftOut`), and a pull
3123
+ // cannot take it, so naming it here asked for a pull that holds it again (measured 2026-11-05).
3124
+ const heldIds = new Set(readHeldItems(siteDir, client.origin))
3125
+ const heldAt = new Set(
3126
+ Object.entries(siteFinalizedDoc ? collectUnitUuids(siteFinalizedDoc) : {})
3127
+ .filter(([, uuid]) => heldIds.has(uuid))
3128
+ .map(([path]) => path)
3129
+ )
3130
+ const othersChanged = [...notHeld.kept, ...notHeld.foreign].filter((p) => !heldAt.has(p))
3131
+ if (othersChanged.length) {
3114
3132
  // Named by the file it is in here, not by its id (`unitFilesOf`).
3115
- const paths = [
3116
- ...new Set([...notHeld.kept, ...notHeld.foreign].map((p) => (p === 'site.yml' ? p : unitFilesOf(siteDir, p)[0] || p)))
3117
- ].sort()
3133
+ const paths = [...new Set(othersChanged.map((p) => (p === 'site.yml' ? p : unitFilesOf(siteDir, p)[0] || p)))].sort()
3118
3134
  note(`Changed on the backend by someone else, not in your files yet: ${paths.join(', ')}`)
3119
3135
  note('Take them with `uniweb refresh` (or `uniweb pull`). Until then, pushing leaves them as they are.')
3120
3136
  }
@@ -692,6 +692,94 @@ export function checkSectionFamilies({
692
692
  }
693
693
  }
694
694
 
695
+ /**
696
+ * The foundation's default section type — what renders a section that names none — said for every
697
+ * foundation, as a fact: declared, the fallback, or none [Diego, 2026-11-05: "It can list the default
698
+ * section type and show if there is none"].
699
+ *
700
+ * The rule is core's (`@uniweb/core/section-type`): the foundation's `defaultSection`, else `Section`.
701
+ * ⭐ `Section` is only a legacy fallback: the name every foundation was once expected to provide. The
702
+ * runtime ships no component by that name, so where the foundation has no type by it, a section that
703
+ * names no type shows "Component not found" where an author composes it.
704
+ *
705
+ * ⛔ "None" IS NOT A WARNING. Many vocabularies have no natural default (Hero, Features, …), and their
706
+ * sections each name a type — 32 of 56 workspace foundations, measured 2026-11-05, with no site of theirs
707
+ * leaving a section without one. Warning there would be noise, and would push an arbitrary default. Only
708
+ * a declared `defaultSection` that names no type is a mistake, and warned. Here rather than in the build,
709
+ * which would print it on every build while a developer works [Diego, 2026-11-05].
710
+ *
711
+ * The suggestion, for none or a mistake: the type a mistyped name meant, else the foundation's only type
712
+ * in the `article` or `rich-text` family, declared or by its name (`resolveFamily`). ⚠️ Reads the built
713
+ * `schema.json`, as `checkSectionFamilies` does, so it says nothing before a build.
714
+ *
715
+ * @returns {{ type: string|null, declared: boolean, exists: boolean }|null} null with no built schema
716
+ */
717
+ export function checkDefaultSection({ foundationName, folderName, foundationDir, issues }) {
718
+ const schema = loadSchemaJson(foundationDir)
719
+ if (!schema) return null
720
+ const types = Object.keys(schema).filter((key) => !key.startsWith('_') && key !== 'dataSchemas' && schema[key] && typeof schema[key] === 'object')
721
+ if (types.length === 0) return null
722
+
723
+ const named = schema._self?.defaultSection
724
+ const declared = typeof named === 'string' && named !== ''
725
+ const fallback = declared ? named : 'Section'
726
+ const exists = types.includes(fallback)
727
+ if (exists) {
728
+ info(
729
+ `${folderName}: default section type ${fallback} ` +
730
+ (declared ? `${colors.dim}(defaultSection in main.js)${colors.reset}` : `${colors.dim}(the fallback: main.js declares no defaultSection)${colors.reset}`)
731
+ )
732
+ if (!declared) log(` ${colors.dim}Declare defaultSection in main.js to choose it by name.${colors.reset}`)
733
+ return { type: fallback, declared, exists }
734
+ }
735
+
736
+ const prose = types.filter((name) => ['article', 'rich-text'].includes(resolveFamily({ name, family: schema[name]?.family }).id))
737
+ const meant = declared ? types.find((name) => name.toLowerCase() === named.toLowerCase()) : null
738
+ const suggestion = meant || (prose.length === 1 ? prose[0] : null)
739
+ const proposal = suggestion ? `defaultSection: '${suggestion}' in main.js would make ${suggestion} the default.` : null
740
+ if (declared) {
741
+ const id = 'default-section-missing'
742
+ const message = `defaultSection names '${named}', which is not a section type of this foundation`
743
+ issues.push({ id, type: 'warn', foundation: foundationName, message, ...(suggestion ? { suggested: suggestion } : {}) })
744
+ warn(`[${id}] ${folderName}: ${message}`)
745
+ log(` A section that names no type shows "Component not found" where an author composes it.`)
746
+ if (proposal) log(` ${colors.blue}${proposal}${colors.reset}`)
747
+ return { type: null, declared, exists }
748
+ }
749
+ issues.push({ id: 'default-section-none', type: 'info', foundation: foundationName, message: 'no default section type: each section names its own', ...(suggestion ? { suggested: suggestion } : {}) })
750
+ info(`${folderName}: no default section type ${colors.dim}(each section names its own; one that names none shows "Component not found")${colors.reset}`)
751
+ if (proposal) log(` ${colors.dim}${proposal}${colors.reset}`)
752
+ return { type: null, declared, exists }
753
+ }
754
+
755
+ /**
756
+ * The section types an editor would leave out of a page's sections if they said `area: true` — those
757
+ * whose family is `header` or `footer`, declared or by their name — suggested, never applied.
758
+ *
759
+ * `area: true` is a placement, beside `inset` (`describePlacement`, `@uniweb/schemas/component`): a
760
+ * type meant for a layout area, offered where an author fills one and left out of a page's sections.
761
+ * ⭐ A family is a claim about a type's shape, not about where it goes, so it never places a type on its
762
+ * own: it is only why doctor asks [Diego, 2026-11-05: "maybe a family that makes it predictable that they
763
+ * are layout only components. or some mix of that"]. Only `header` and `footer`: a `toc` or a `pathways`
764
+ * type is as often a page's own section. A type that says `area` or `section` either way has decided.
765
+ *
766
+ * @returns {string[]} the types suggested; [] with no built schema
767
+ */
768
+ export function checkAreaTypes({ foundationName, folderName, foundationDir, issues }) {
769
+ const schema = loadSchemaJson(foundationDir)
770
+ if (!schema) return []
771
+ const suggested = Object.entries(schema)
772
+ .filter(([key, entry]) => !key.startsWith('_') && key !== 'dataSchemas' && entry && typeof entry === 'object')
773
+ .filter(([, entry]) => entry.area === undefined && entry.section === undefined && entry.inset !== true)
774
+ .filter(([name, entry]) => ['header', 'footer'].includes(resolveFamily({ name, family: entry.family }).id))
775
+ .map(([name]) => name)
776
+ if (suggested.length === 0) return []
777
+ issues.push({ id: 'section-area-suggested', type: 'info', foundation: foundationName, message: `${suggested.join(', ')} could say area: true`, details: suggested })
778
+ info(`${folderName}: ${suggested.join(', ')} could say ${colors.blue}area: true${colors.reset} in meta.js`)
779
+ log(` ${colors.dim}A type meant only for a layout area (a header, a footer, a side panel) says so, and an editor leaves it out of a page's sections. With section: true beside it, it is offered for both; section: true alone says it is a page's.${colors.reset}`)
780
+ return suggested
781
+ }
782
+
695
783
  /**
696
784
  * Insert `family: '<id>'` as the first key of a meta.js default export.
697
785
  *
@@ -1886,6 +1974,19 @@ async function runDoctor(args = []) {
1886
1974
  shouldFixExplicitly,
1887
1975
  fixed
1888
1976
  })
1977
+ // A foundation's own default — not an extension's, whose types join a site's primary foundation.
1978
+ checkDefaultSection({
1979
+ foundationName: f.name,
1980
+ folderName: f.folderName,
1981
+ foundationDir: f.path,
1982
+ issues
1983
+ })
1984
+ checkAreaTypes({
1985
+ foundationName: f.name,
1986
+ folderName: f.folderName,
1987
+ foundationDir: f.path,
1988
+ issues
1989
+ })
1889
1990
  checkRetiredMetaKeys({
1890
1991
  foundationName: f.name,
1891
1992
  folderName: f.folderName,
@@ -1924,6 +2025,12 @@ async function runDoctor(args = []) {
1924
2025
  shouldFixExplicitly,
1925
2026
  fixed
1926
2027
  })
2028
+ checkAreaTypes({
2029
+ foundationName: e.name,
2030
+ folderName: e.folderName,
2031
+ foundationDir: e.path,
2032
+ issues
2033
+ })
1927
2034
  checkRetiredMetaKeys({
1928
2035
  foundationName: e.name,
1929
2036
  folderName: e.folderName,
@@ -1296,14 +1296,15 @@ export async function pull(args = [], deps = {}) {
1296
1296
  // say it (`readHeldUnits`). Replaced by each pull that takes the site's content. In the stand-in's
1297
1297
  // cache, which comes back to the site with the others.
1298
1298
  try {
1299
+ const held = leftOutOfPush(heldPages).flatMap((h) => h.uuids || [])
1299
1300
  writeHeldUnits(projDir, client.origin, await heldUnitBaseline(projDir, client.origin, {
1300
- held: leftOutOfPush(heldPages).flatMap((h) => h.uuids || []),
1301
+ held,
1301
1302
  // Where this copy kept each item before the pull, over where the backend keeps it — the same
1302
1303
  // place for a page the app did not move, and the one a `sync.json` without items still has.
1303
1304
  itemUuids: { ...collectUnitUuids(siteDoc), ...priorItems },
1304
1305
  ...(declarations.size ? { declarations } : {}),
1305
1306
  fields
1306
- }))
1307
+ }), held)
1307
1308
  } catch (err) {
1308
1309
  // The files did not emit: neither will a push from them, which this pull leaves to say why.
1309
1310
  writeHeldUnits(projDir, client.origin, {})
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-05T01:35:06.410Z",
3
+ "generatedAt": "2026-11-05T19:34:17.109Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
6
  "version": "1.6.9"
@@ -42,7 +42,7 @@
42
42
  "version": "1.0.1"
43
43
  },
44
44
  "@uniweb/schemas": {
45
- "version": "1.6.8"
45
+ "version": "1.6.9"
46
46
  },
47
47
  "@uniweb/scholar": {
48
48
  "version": "1.1.0"
@@ -54,7 +54,7 @@
54
54
  "version": "1.1.2"
55
55
  },
56
56
  "@uniweb/templates": {
57
- "version": "1.2.6"
57
+ "version": "1.2.7"
58
58
  },
59
59
  "@uniweb/theming": {
60
60
  "version": "1.2.1"