sdocs-dev 1.15.0 → 1.18.0

package/shared/sdocs-slide-resolve.js

@@ -0,0 +1,258 @@
+// sdocs-slide-resolve.js — template resolution for slide blocks (UMD).
+// Shared by the browser slide pipeline and Node unit tests.
+//
+// Input:  an array of raw slide DSL strings (the text between ~~~slide
+//         fences), in document order.
+// Output: an array of { dsl, skip, errors } in the same order, where:
+//           - dsl: the DSL text to render (merged for consumers; unchanged
+//             for plain slides; the template body for template slides)
+//           - skip: true for @template slides (they register but don't render)
+//           - errors: [{ message }] of resolve-time problems (unknown
+//             template, malformed directive, etc.). Empty array when clean.
+//
+// Directives (must be the first non-blank line inside the fence):
+//   @template NAME   — register this slide's DSL under NAME; don't render it.
+//   @extends  NAME   — replace slot contents in template NAME with the
+//                      `#id: value` blocks that follow.
+//
+// Slot block syntax inside @extends bodies:
+//   #id: inline value                 (single-line)
+//   #id:                              (multi-line; content on following
+//     content line one                 lines, until the next `#id:` or EOF)
+//     content line two
+//
+// The resolver is deliberately pure — it takes strings, returns strings,
+// and does not touch the DOM, parse shape geometry, or know anything
+// about CSS. All heavy lifting (DSL parsing, rendering) happens downstream
+// on the resolved text, so templates re-use every existing code path.
+
+(function (exports) {
+'use strict';
+
+var DIRECTIVE_RE = /^\s*@(template|extends)\s+([A-Za-z][\w-]*)\s*$/;
+// Consumer slot lines optionally accept a trailing `!` after the id - the
+// required marker belongs in the template, but accepting it here means a
+// copy-paste from a template definition doesn't silently break.
+var SLOT_RE = /^#([A-Za-z][\w-]*)!?\s*:\s?(.*)$/;
+
+function splitDirective(raw) {
+  var lines = String(raw == null ? '' : raw).split('\n');
+  var i = 0;
+  while (i < lines.length && lines[i].trim() === '') i++;
+  if (i >= lines.length) return { kind: null };
+  var m = lines[i].match(DIRECTIVE_RE);
+  if (!m) return { kind: null };
+  return {
+    kind: m[1],
+    name: m[2],
+    body: lines.slice(i + 1).join('\n'),
+  };
+}
+
+function parseSlots(body) {
+  var lines = body.split('\n');
+  var slots = {};
+  var currentId = null;
+  var buf = [];
+  var inline = false;  // inline-only slot (body on the directive line)
+  for (var i = 0; i < lines.length; i++) {
+    var ln = lines[i];
+    var m = ln.match(SLOT_RE);
+    if (m) {
+      if (currentId !== null) slots[currentId] = finalizeBuf(buf, inline);
+      currentId = m[1];
+      // A bare `|` after the colon is YAML-style block-scalar sugar: the
+      // user signalled "multi-line body follows", same as an empty inline.
+      // Dropping it prevents the literal `|` from leaking into the rendered
+      // markdown as a stray paragraph.
+      var inlineVal = m[2] === '|' ? '' : m[2];
+      inline = inlineVal.length > 0;
+      buf = inlineVal ? [inlineVal] : [];
+    } else if (currentId !== null) {
+      buf.push(ln);
+      inline = false;  // as soon as we collect body lines, treat as block
+    }
+    // Lines before the first #id: are ignored (allows authors to leave
+    // notes or blank space between @extends and the first slot).
+  }
+  if (currentId !== null) slots[currentId] = finalizeBuf(buf, inline);
+  return slots;
+}
+
+// Inline slots (single-line `#id: value`) round-trip as-is. Block slots get
+// trailing blank lines trimmed and common leading indent stripped, so an
+// author who wrote:
+//
+//   #body:
+//     - one
+//     - two
+//
+// gets `- one\n- two` in their shape content (not `  - one\n  - two`, which
+// markdown may render with an extra indent level or misread as code).
+function finalizeBuf(lines, isInline) {
+  if (isInline) return lines.join('\n');
+  return dedent(trimTrailingBlank(lines)).join('\n');
+}
+
+function trimTrailingBlank(lines) {
+  var end = lines.length;
+  while (end > 0 && lines[end - 1].trim() === '') end--;
+  return lines.slice(0, end);
+}
+
+function dedent(lines) {
+  var min = Infinity;
+  for (var i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === '') continue;
+    var lead = /^ */.exec(lines[i])[0].length;
+    if (lead < min) min = lead;
+  }
+  if (!isFinite(min) || min === 0) return lines;
+  return lines.map(function (l) {
+    return l.length >= min ? l.slice(min) : l;
+  });
+}
+
+// Merge the template's shapes with the consumer's slots by #id match.
+// Relies on the SDocShapes parse/serialize pair, so any DSL the parser
+// accepts round-trips correctly. Shapes whose id doesn't appear in the
+// consumer's slots keep their template-provided content — that's how
+// "partial fills render the layout's placeholder" works.
+function mergeTemplate(templateDsl, slots, SDocShapes) {
+  var parsed = SDocShapes.parse(templateDsl);
+  var shapes = parsed.shapes.map(function (s) {
+    if (s.id && Object.prototype.hasOwnProperty.call(slots, s.id)) {
+      var copy = {};
+      for (var k in s) if (Object.prototype.hasOwnProperty.call(s, k)) copy[k] = s[k];
+      copy.content = slots[s.id];
+      return copy;
+    }
+    return s;
+  });
+  return SDocShapes.serialize(shapes, parsed.grid);
+}
+
+function resolveSlides(rawDsls, SDocShapes, opts) {
+  if (!SDocShapes) {
+    throw new Error('resolveSlides: SDocShapes is required');
+  }
+  opts = opts || {};
+  var stdlib = opts.stdlib || {};
+
+  var templates = {};
+  var shadowSlideByName = {};
+  var parsed = rawDsls.map(splitDirective);
+
+  // Pass 1: register every user @template. Doing this ahead of pass 2
+  // means author ordering in the document is unconstrained - a consumer
+  // can appear before its template. A user template shadowing a stdlib
+  // name is allowed but flagged on the template's own slide entry, so
+  // accidental shadowing is visible at render time.
+  for (var i = 0; i < parsed.length; i++) {
+    var p = parsed[i];
+    if (p.kind === 'template') {
+      templates[p.name] = p.body;
+      if (Object.prototype.hasOwnProperty.call(stdlib, p.name)) {
+        shadowSlideByName[p.name] = i;
+      }
+    }
+  }
+
+  // Pass 2: build a result per slide.
+  return parsed.map(function (p, idx) {
+    var raw = rawDsls[idx];
+    if (p.kind === 'template') {
+      var tErrs = [];
+      if (shadowSlideByName[p.name] === idx) {
+        tErrs.push({
+          line: 1,
+          message: 'template "' + p.name + '" shadows the stdlib template of the same name',
+        });
+      }
+      return { dsl: p.body, skip: true, errors: tErrs };
+    }
+    if (p.kind === 'extends') {
+      var tplBody = Object.prototype.hasOwnProperty.call(templates, p.name)
+        ? templates[p.name]
+        : (Object.prototype.hasOwnProperty.call(stdlib, p.name) ? stdlib[p.name] : null);
+      if (!tplBody) {
+        return {
+          dsl: raw,
+          skip: false,
+          errors: [{ line: 1, message: 'unknown template "' + p.name + '"' }],
+        };
+      }
+
+      var slots = parseSlots(p.body);
+      var errors = [];
+
+      // Parse the template once so we can introspect shape ids + required
+      // markers. The same parse work happens inside mergeTemplate; we eat
+      // the duplication for clarity (resolver stays pure DSL-string-in,
+      // DSL-string-out at the boundary).
+      var parsedTpl;
+      try {
+        parsedTpl = SDocShapes.parse(tplBody);
+      } catch (e) {
+        return {
+          dsl: raw,
+          skip: false,
+          errors: [{ line: 1, message: 'template parse failed: ' + e.message }],
+        };
+      }
+
+      var templateIds = {};
+      for (var s = 0; s < parsedTpl.shapes.length; s++) {
+        var sid = parsedTpl.shapes[s].id;
+        if (sid) templateIds[sid] = parsedTpl.shapes[s];
+      }
+
+      // Unknown-slot check: consumer named a slot the template doesn't
+      // define. Silently no-op was the #1 cause of "template feels
+      // broken" confusion - surface it as an error per the DSL-design
+      // review.
+      for (var slotName in slots) {
+        if (!Object.prototype.hasOwnProperty.call(slots, slotName)) continue;
+        if (!Object.prototype.hasOwnProperty.call(templateIds, slotName)) {
+          errors.push({
+            line: 1,
+            message: 'unknown slot "#' + slotName + '" (template "' + p.name + '" has no shape with that id)',
+          });
+        }
+      }
+
+      // Required-slot check: template marked the shape with #id! but
+      // the consumer didn't pass that slot.
+      for (var tid in templateIds) {
+        if (!Object.prototype.hasOwnProperty.call(templateIds, tid)) continue;
+        var shp = templateIds[tid];
+        if (shp.required && !Object.prototype.hasOwnProperty.call(slots, tid)) {
+          errors.push({
+            line: 1,
+            message: 'missing required slot "#' + tid + '" for template "' + p.name + '"',
+          });
+        }
+      }
+
+      var merged;
+      try {
+        merged = mergeTemplate(tplBody, slots, SDocShapes);
+      } catch (e) {
+        return {
+          dsl: raw,
+          skip: false,
+          errors: [{ line: 1, message: 'template merge failed: ' + e.message }],
+        };
+      }
+      return { dsl: merged, skip: false, errors: errors };
+    }
+    // Plain slide - untouched.
+    return { dsl: raw, skip: false, errors: [] };
+  });
+}
+
+exports.resolveSlides = resolveSlides;
+exports.splitDirective = splitDirective;
+exports.parseSlots = parseSlots;
+
+})(typeof module !== 'undefined' && module.exports ? module.exports : (window.SDocSlideResolve = {}));

package/shared/sdocs-slide-stdlib.js

@@ -0,0 +1,180 @@
+// sdocs-slide-stdlib.js - built-in slide templates (UMD).
+//
+// Each entry is a DSL string the resolver registers under the given name,
+// alongside user `@template` definitions. User-defined templates shadow
+// stdlib names (with a warning surfaced through the slide error badge),
+// so authors can override any built-in without touching this file.
+//
+// Design constants applied across every template:
+//   - 1-unit safe margin on all four sides of a 16x9 grid (roughly 6%
+//     horizontal, 5-7% vertical, matching the standard slide safe area).
+//   - No shape fill colours for shapes containing title/body text. The
+//     section divider uses `grid bg=` for full-bleed contrast instead.
+//   - Title role (64px) reserved for cover + quote + section. In-deck
+//     content slides use subtitle role (40px) so action titles can wrap
+//     to two lines without filling half the page.
+//   - Caption role (14px) reserved for eyebrows / footers / attributions
+//     - never for load-bearing content (it renders as ~3px in a 240px
+//     thumbnail, illegible).
+//   - Optional slots default to empty content, so omitting them renders
+//     nothing visible. Required slots (#name!) emit a resolver error
+//     when the consumer doesn't fill them.
+//
+// All templates assume a 16x9 grid. Authors who need a different aspect
+// ratio should copy a template into a user `@template` and edit the grid.
+
+(function (exports) {
+'use strict';
+
+var TEMPLATES = {
+
+  // Opening slide. Once per deck, sets the tone before anything else.
+  cover: [
+    'grid 16 9',
+    'r 1 1 14 0.7 #eyebrow text=caption color=$color opacity=0.6 align=left |',
+    'r 1 3.2 14 2.2 #title! text=title align=left | (required: cover title)',
+    'r 1 5.8 14 1.0 #subtitle text=subtitle color=$color opacity=0.75 align=left |',
+    'r 1 7.7 14 0.6 #meta text=caption color=$color opacity=0.6 align=left |',
+  ].join('\n'),
+
+  // The workhorse. 60-70% of body slides. Title at top, body filling the
+  // safe area below, optional footer for source / page / context. Title
+  // uses subtitle role so an action title can wrap to two lines without
+  // crowding the body.
+  'title-body': [
+    'grid 16 9',
+    'r 1 0.7 14 1.1 #title! text=subtitle align=left | (required: slide title)',
+    'r 1 2.2 14 5.7 #body! text=body align=left valign=top | (required: slide body)',
+    'r 1 8.1 14 0.4 #footer text=caption color=$color opacity=0.55 align=left |',
+  ].join('\n'),
+
+  // Two equal columns with a 1-unit gutter, both bodies anchored top so
+  // matched-length content reads as parallel. Optional column headers in
+  // caption role above each body.
+  'two-column': [
+    'grid 16 9',
+    'r 1 0.7 14 1.1 #title! text=subtitle align=left | (required: slide title)',
+    'r 1 2.4 6.5 0.5 #left-header text=caption color=$color opacity=0.75 align=left |',
+    'r 1 3.0 6.5 5.0 #left! text=body align=left valign=top | (required: left column)',
+    'r 8.5 2.4 6.5 0.5 #right-header text=caption color=$color opacity=0.75 align=left |',
+    'r 8.5 3.0 6.5 5.0 #right! text=body align=left valign=top | (required: right column)',
+  ].join('\n'),
+
+  // Three-way compare. A/B/C variants, before/during/after, three
+  // perspectives on the same question. Three equal columns (4.3 wide
+  // each) separated by 0.55-unit gutters, optional headers above each.
+  // Bias to keeping all three columns roughly the same length - if one
+  // is half-empty, drop it and use two-column.
+  'three-column': [
+    'grid 16 9',
+    'r 1 0.7 14 1.1 #title! text=subtitle align=left | (required: slide title)',
+    'r 1 2.4 4.3 0.5 #left-header text=caption color=$color opacity=0.75 align=left |',
+    'r 1 3.0 4.3 5.0 #left! text=body align=left valign=top | (required: left column)',
+    'r 5.85 2.4 4.3 0.5 #mid-header text=caption color=$color opacity=0.75 align=left |',
+    'r 5.85 3.0 4.3 5.0 #mid! text=body align=left valign=top | (required: middle column)',
+    'r 10.7 2.4 4.3 0.5 #right-header text=caption color=$color opacity=0.75 align=left |',
+    'r 10.7 3.0 4.3 5.0 #right! text=body align=left valign=top | (required: right column)',
+  ].join('\n'),
+
+  // Exhibit. Chart on the left (~56% wide), takeaway column on the
+  // right (~28% wide). The chart is the evidence; the takeaway tells
+  // the audience what to see. Optional source caption at the bottom.
+  // Reserve for business decks where the audience needs a verbal
+  // handle on the chart under time pressure - if your audience can
+  // read the chart themselves in 5 seconds, use figure-hero instead.
+  exhibit: [
+    'grid 16 9',
+    'r 1 0.7 14 1.1 #title! text=subtitle align=left | (required: action title)',
+    'r 1 2 9 6 #chart! align=center valign=center | (required: ![alt](url) or chart)',
+    'r 10.5 2 4.5 6 #takeaway! text=body align=left valign=center | (required: takeaway)',
+    'r 1 8.1 14 0.4 #source text=caption color=$color opacity=0.55 align=left |',
+  ].join('\n'),
+
+  // Image-and-text. Image fills the left half of the safe area, body
+  // sits on the right. The image slot accepts markdown image syntax:
+  // `#image: ![alt](url)`. Optional small title above both columns.
+  'image-and-text': [
+    'grid 16 9',
+    'r 1 0.7 14 0.9 #title text=caption color=$color opacity=0.75 align=left |',
+    'r 1 1.9 7.5 6.2 #image! align=center valign=center | (required: ![alt](url))',
+    'r 9 1.9 6 6.2 #body! text=body align=left valign=top | (required: body)',
+  ].join('\n'),
+
+  // Image-dominant slide. The figure carries the slide; a small
+  // caption sits below. Use when the image IS the argument (a chart,
+  // a screenshot, a product shot, a photo). If you want supporting
+  // body text alongside the image, use `image-and-text` instead.
+  'figure-hero': [
+    'grid 16 9',
+    'r 1 0.6 14 7.0 #image! align=center valign=center | (required: ![alt](url))',
+    'r 1 7.9 14 0.6 #caption text=caption color=$color opacity=0.75 align=center valign=top |',
+  ].join('\n'),
+
+  // Single big idea. Quote, customer voice, or a callout sentence that
+  // deserves the whole slide. Lead is centered both ways so short content
+  // sits visually balanced rather than top-left adrift.
+  quote: [
+    'grid 16 9',
+    'r 2 2 12 4 #lead! text=title align=center valign=center | (required: the lead)',
+    'r 2 6.5 12 0.7 #attribution text=caption color=$color opacity=0.6 align=center valign=top |',
+  ].join('\n'),
+
+  // One big number + a line of context. The hero metric slide.
+  // `size=fit` lets the number balloon to fill its shape, so a 3-char
+  // value (`87%`) lands much larger than a long one (`$4,231,889`).
+  // `maxfont=300px` lifts the default 12%-of-stage cap so the number
+  // can actually feel hero-sized; without it, autofit would cap at
+  // ~86px on a 720-tall stage and the slide reads as "a small number
+  // floating in a big box" rather than "stop the room".
+  // Use sparingly - one metric slide per deck is the rule, not three.
+  metric: [
+    'grid 16 9',
+    'r 1 1.5 14 4.8 #metric! size=fit maxfont=300px align=center valign=center | (required: the number)',
+    'r 1 6.7 14 1.4 #context text=body color=$color opacity=0.75 align=center valign=top |',
+  ].join('\n'),
+
+  // Section divider. The one template where the slide background gets a
+  // saturated fill - the contrast against content slides is the point.
+  // Text shapes themselves have no fill (Consultant-2 rule preserved);
+  // the grid's bg= provides the colour underneath.
+  section: [
+    'grid 16 9 bg=#0f172a',
+    'r 1 1 14 0.7 #kicker text=caption color=#94a3b8 align=left |',
+    'r 1 3 14 3 #title! text=title color=#f8fafc align=left valign=center | (required: section title)',
+    'r 1 6 14 1 #subtitle text=subtitle color=#cbd5e1 align=left valign=center |',
+  ].join('\n'),
+
+  // Closing slide. Symmetric bookend with `cover`. Center-aligned and
+  // minimal - one quiet message + optional contact line. Don't write
+  // "Thanks for listening" here; pick something the audience will
+  // remember instead.
+  closing: [
+    'grid 16 9',
+    'r 1 3.5 14 2.0 #lead! text=subtitle align=center valign=center | (required: closing line)',
+    'r 1 6 14 0.6 #contact text=caption color=$color opacity=0.6 align=center valign=center |',
+  ].join('\n'),
+
+};
+
+// Per-template slot summary for `sdoc slides list` and the resolver's
+// unknown-slot check. Required slots end with `!` here too, matching the
+// DSL marker. Order matters - it controls how the listing reads.
+var SLOT_DOCS = {
+  cover:           ['eyebrow', 'title!', 'subtitle', 'meta'],
+  'title-body':    ['title!', 'body!', 'footer'],
+  'two-column':    ['title!', 'left-header', 'left!', 'right-header', 'right!'],
+  'three-column':  ['title!', 'left-header', 'left!', 'mid-header', 'mid!', 'right-header', 'right!'],
+  exhibit:         ['title!', 'chart!', 'takeaway!', 'source'],
+  'image-and-text':['title', 'image!', 'body!'],
+  'figure-hero':   ['image!', 'caption'],
+  quote:           ['lead!', 'attribution'],
+  metric:          ['metric!', 'context'],
+  section:         ['kicker', 'title!', 'subtitle'],
+  closing:         ['lead!', 'contact'],
+};
+
+exports.templates = TEMPLATES;
+exports.slots = SLOT_DOCS;
+exports.names = Object.keys(TEMPLATES);
+
+})(typeof module !== 'undefined' && module.exports ? module.exports : (window.SDocSlideStdlib = {}));

package/shared/sdocs-styles.js

@@ -536,7 +536,7 @@ var STYLE_DEFAULTS = {
   p: { lineHeight: 1.75, marginBottom: 1.1 },
   link: { color: '#2563eb', decoration: 'underline' },
   code: { font: 'JetBrains Mono' },
-  blockquote: { borderColor: '#2563eb', borderWidth: 3, fontSize: 1.0 },
+  blockquote: { borderColor: '#2563eb', borderWidth: 3, fontSize: 1.05 },
   list: { spacing: 0.3, indent: 1.6 },
 };