@pretextbook/remark-pretext 0.0.6 → 0.0.8

package/dist/lib/context.d.ts

@@ -1,5 +1,5 @@
 import { BlockContent, DefinitionContent, PhrasingContent } from 'mdast';
-import { DivisionType } from '@pretextbook/ptxast';
+import { RootDivisionType, TopLevelDivisionType } from '@pretextbook/ptxast';
 export interface VisitContext {
     /** Parent node, if any. */
     parent?: BlockContent | DefinitionContent | PhrasingContent;
@@ -12,7 +12,19 @@ export interface VisitContext {
     /** Raw source markdown (optional, used for delimiter detection). */
     source?: string;
     /** The division type that a depth-1 heading (`#`) maps to. */
-    topLevelDivision: DivisionType;
+    topLevelDivision: TopLevelDivisionType;
+    /** When set, the whole document is wrapped in this root element
+     * (`book`/`article`/`slideshow`) and `topLevelDivision` is the root's
+     * outermost child division. */
+    documentRoot?: RootDivisionType;
+    /** Attributes (e.g. from frontmatter `xmlid`/`label`/`component`) to apply
+     * to the first root-level division built from the document. */
+    topLevelAttributes?: Record<string, string>;
+    /** Mutable: set once `topLevelAttributes` has been applied to a division,
+     * shared by reference across the recursive conversion of this document. */
+    topLevelAttributesApplied?: {
+        done: boolean;
+    };
 }
 export interface ConversionMessage {
     type: 'warning' | 'error';

package/dist/lib/frontmatter.d.ts

@@ -1,7 +1,13 @@
-import { DivisionType } from '@pretextbook/ptxast';
+import { RootDivisionType, TopLevelDivisionType } from '@pretextbook/ptxast';
 export interface FrontmatterResult {
-    /** The declared top-level division type, if present and valid. */
-    division?: DivisionType;
+    /** The division a depth-1 heading (`#`) maps to, if present and valid. When
+     * `documentRoot` is set this is the root's outermost child division. */
+    division?: TopLevelDivisionType;
+    /** The document root (`book`/`article`/`slideshow`) to wrap the whole
+     * document in, when `division:` names one. */
+    documentRoot?: RootDivisionType;
+    /** Attributes (`xml:id`, `label`, `component`) for the top-level division. */
+    attributes?: Record<string, string>;
     /** The markdown source with the frontmatter block removed. */
     body: string;
 }

package/dist/lib/mdast-to-ptxast.d.ts

@@ -1,7 +1,7 @@
 import { Root as MdastRoot } from 'mdast';
 import { Root } from 'xast';
 import { ConversionMessage } from './context.js';
-import { DivisionType } from '@pretextbook/ptxast';
+import { RootDivisionType, TopLevelDivisionType } from '@pretextbook/ptxast';
 /** Result type for conversion: tree + diagnostic messages. */
 export interface ConversionResult {
     tree: Root;
@@ -10,7 +10,14 @@ export interface ConversionResult {
 /** Options controlling heading-to-division conversion. */
 export interface MdastToPtxastOptions {
     /** The division type that a depth-1 heading (`#`) maps to. Defaults to `'chapter'`. */
-    topLevelDivision?: DivisionType;
+    topLevelDivision?: TopLevelDivisionType;
+    /** When set, wrap the whole document in this root element
+     * (`book`/`article`/`slideshow`); `topLevelDivision` is then the division a
+     * depth-1 heading maps to inside the root. */
+    documentRoot?: RootDivisionType;
+    /** Attributes (`xml:id`, `label`, `component`) applied to the first
+     * root-level division built from the document, e.g. from frontmatter. */
+    topLevelAttributes?: Record<string, string>;
 }
 /** Transform an mdast Root node into an xast Root node (backwards compatible). */
 export declare function mdastToPtxast(tree: MdastRoot, source?: string, options?: MdastToPtxastOptions): Root;

package/dist/lib/plus-include.d.ts

@@ -0,0 +1,27 @@
+import { Element } from 'xast';
+import { ContainerDirective, LeafDirective, TextDirective } from 'mdast-util-directive';
+/** Any of the three remark-directive node shapes (`:x`, `::x`, `:::x`). */
+type DirectiveNode = TextDirective | LeafDirective | ContainerDirective;
+/**
+ * Build a `<plus:KIND .../>` include element from a kind name and attributes.
+ *
+ * This is the one choke point every include syntax funnels through: the tag is
+ * always `plus:<kind>`, the element is always empty (a reference, never
+ * transcluded), and `null`/`undefined` attribute values are dropped so a
+ * value-less directive attribute doesn't emit `key="null"`.
+ */
+export declare function plusIncludeElement(kind: string, attributes?: Record<string, string | null | undefined>): Element;
+/**
+ * Interpret a remark-directive node as a PreTeXt Plus include: the directive
+ * name becomes the `plus:` kind and its attributes pass through verbatim
+ * (`::section{ref="x"}` → `<plus:section ref="x"/>`).
+ *
+ * Attributes are intentionally *not* remapped the way block directives remap
+ * `id`→`xml:id`: an include points at another element by `ref`, so its
+ * attributes are kept exactly as written.
+ *
+ * Returns `null` when the node carries no usable name, so callers can fall back
+ * to their normal handling rather than emitting `<plus:/>`.
+ */
+export declare function directiveToPlusInclude(node: DirectiveNode): Element | null;
+export {};

package/dist/lib/remark-pretext.d.ts

@@ -1,7 +1,7 @@
 import { Plugin } from 'unified';
 import { Root as MdastRoot } from 'mdast';
 import { Root } from 'xast';
-import { DivisionType } from '@pretextbook/ptxast';
+import { RootDivisionType, TopLevelDivisionType } from '@pretextbook/ptxast';
 /** Options for the remark-pretext plugin. */
 export interface RemarkPretextOptions {
     /**
@@ -9,7 +9,20 @@ export interface RemarkPretextOptions {
      * `division:` field declared in the markdown's frontmatter. Defaults to
      * `'chapter'` (matching historical behavior) when neither is set.
      */
-    topLevelDivision?: DivisionType;
+    topLevelDivision?: TopLevelDivisionType;
+    /**
+     * Wraps the whole document in this root element (`book`/`article`/
+     * `slideshow`). Overrides any document root declared via the frontmatter
+     * `division:` field. When set, `topLevelDivision` is the division a depth-1
+     * heading maps to *inside* the root.
+     */
+    documentRoot?: RootDivisionType;
+    /**
+     * Attributes (`xml:id`, `label`, `component`) applied to the first
+     * root-level division. Overrides any `xmlid:`/`label:`/`component:`
+     * fields declared in the markdown's frontmatter.
+     */
+    topLevelAttributes?: Record<string, string>;
 }
 declare const remarkPretext: Plugin<[RemarkPretextOptions?], MdastRoot, Root>;
 export default remarkPretext;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretextbook/remark-pretext",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "remark plugin to transform markdown-style PreTeXt directives into ptxast",
   "author": "Oscar Levin",
   "license": "MIT",
@@ -39,7 +39,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@pretextbook/ptxast": "^0.0.5",
+    "@pretextbook/ptxast": "^0.0.7",
     "@types/mdast": "^4.0.0",
     "mdast-util-directive": "^3.0.0",
     "remark-directive": "^4.0.0",