@topik/content 0.0.0-stage → 0.1.0-alpha.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Topik Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,268 @@
-# Temporary Holding Version
+# @topik/content
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Portable Markdown with declarative components, variables, and conditions. This
+package provides an mdast authoring tree, validation, lossless source operations,
+and a framework-independent render tree. React rendering lives in
+`@topik/content-react`; applications own editing, storage, and synchronization.
+
+The package is ESM and requires Node.js 22.12 or later. Install it with your
+package manager:
+
+```sh
+npm install @topik/content
+```
+
+## Validate, format, and render
+
+`compileTopikContent` validates source and produces a reader tree in one pipeline.
+It accepts canonical compiler-generated asset references as well as authored
+content. Parsing alone checks neither URL nor asset admission policies. Formatting
+validates input and output and checks that serialization preserves the authored
+content. Failures retain the exact input.
+
+```ts
+import { formatTopikContent, compileTopikContent } from "@topik/content";
+
+const source = '# Welcome\n\n{% callout variant="tip" %}\nKeep a **backup**.\n{% /callout %}';
+const formatted = formatTopikContent(source);
+if (!formatted.ok) throw new Error(JSON.stringify(formatted.diagnostics));
+
+const compiled = compileTopikContent(formatted.formatted);
+if (!compiled.ok) throw new Error(JSON.stringify(compiled.diagnostics));
+const tree = compiled.tree;
+// Store authored source; pass the derived tree to your renderer.
+if (tree === null) throw new Error("Expected rendered content");
+```
+
+`parseDocument` and `validateDocument` check tree structure and component rules.
+`writeDocument` serializes a supported authoring tree. ASTs must contain plain
+data with independent node objects: cycles, shared nodes, accessors, and executable
+values are refused. Use `validateTopikContent` for source admission, including
+navigation and asset policies.
+
+`sameDocumentMeaning(left, right)` compares already-admitted authoring trees. It
+ignores source positions, cosmetic spelling and derived metadata while retaining
+explicit heading IDs, reference bindings, ordered content and every conditional
+branch. It does not validate arbitrary trees or treat application editor defaults
+as authored defaults.
+
+## Markdown and components
+
+Supported Markdown includes headings, emphasis, strong and strikethrough marks,
+code, lists and task lists, blockquotes, hard breaks, links, images, reference
+definitions, tables, and leading YAML frontmatter. Frontmatter is retained but
+not rendered. Raw HTML and footnotes are refused. URLs and email addresses remain
+text unless expressed as explicit Markdown links or angle-bracket autolinks.
+
+Portable document destinations use `ref://wiki-page/<name>`, `ref://guide/<name>`,
+or `ref://course-page/<name>`, where the name is the target resource identity.
+`parseTopikResourceReference` and `serializeTopikResourceReference` retain its
+query and fragment separately from publishing routes. Renderers must resolve
+these identities to browser URLs; see the
+[resource-link reference](https://github.com/subtopik/topik/blob/main/docs/resources/navigation.md#links-between-pages).
+
+Block tags occupy their own lines; inline tags appear inside prose. Properties
+are literal strings, numbers, and booleans; selected built-in text properties also
+accept explicit templates. Unsupported syntax is diagnosed instead of silently
+discarded.
+
+| Component                                   | Content and principal properties                                                                    |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `callout`                                   | Block content; optional `variant` and `title`                                                       |
+| `accordion`                                 | Block content; required `title`, optional `open`                                                    |
+| `cardGrid`, `card`                          | Cards; grid `columns` from 1 to 4; card requires `title` and accepts `href`, `icon`                 |
+| `tabs`, `tab`                               | One or more tabs, each with a required `title`                                                      |
+| `steps`, `step`                             | One or more steps; optional step `title`                                                            |
+| `codeGroup`, `codeTab`                      | One or more code tabs; each requires `title` and fenced code                                        |
+| `figure`                                    | Self-closing; required `src` and `alt`, optional `darkSrc` and `caption`                            |
+| `math`, `mathInline`                        | Self-closing block/inline formula with required `content`                                           |
+| `badge`                                     | Inline content; optional `variant`                                                                  |
+| `underline` (alias `u`)                     | Inline content                                                                                      |
+| `quiz`, `question`, `choice`, `explanation` | Questions with at least two choices; `type` selects single/multiple choice, `correct` marks answers |
+
+Math `content` preserves line breaks and tabs using `\n`, `\r` and `\t`
+escapes. Other attributes continue to refuse control characters. These escapes
+remain literal formula data; they do not add Markdown blocks or inline nodes.
+
+The exported `components` registry contains complete property, placement, and
+child constraints. Defaults are applied when reading or rendering; absent authored
+properties remain absent when writing.
+
+Fenced code accepts presentation attributes such as `filename="Client.java"`,
+`lines`, `highlight="2"` and `collapse="3-4,8-9"`. Selections use closed physical-row
+ranges and normalize to sorted, merged intervals. Each collapsed interval has an
+independent inline control; Copy always retains the full exact code, and every row
+remains visible before hydration or without JavaScript. See the
+[code presentation reference](https://github.com/subtopik/topik/blob/main/docs/content/code-presentation.md)
+for options, limits and source-preservation rules.
+
+## Variables and conditions
+
+Evaluation selects branches and inserts variable values as literal text. It does
+not execute JavaScript or interpret interpolated Markdown. Save the authored
+document to retain variables and every branch.
+
+```ts
+import { evaluateDocument, parseDocument, writeDocument } from "@topik/content";
+
+const source = [
+  '{% if equals($student.role, "teacher") %}',
+  "Hello {% $student.name %}.",
+  "{% else /%}",
+  "Student instructions.",
+  "{% /if %}",
+].join("\n");
+const parsed = parseDocument(source);
+if (!parsed.ok) throw new Error(JSON.stringify(parsed.diagnostics));
+
+const evaluated = evaluateDocument(parsed.document, {
+  student: { role: "teacher", name: "Ada" },
+});
+if (writeDocument(evaluated) !== "Hello Ada.\n") throw new Error("Unexpected evaluation");
+```
+
+Expressions support scalar literals, variable paths, `equals`, `and`, `or`, and
+`not`. Only `false` and `null` are false; `and` and `or` short-circuit. Missing
+variables in evaluated paths throw `ContentEvaluationError`. Conditions control
+presentation and do not enforce authorization.
+
+Null and empty strings insert no text. Evaluation omits empty paragraphs, empty
+marks, and empty components that require inline children. It also removes terminal
+hard breaks exposed by those omissions so the evaluated document remains writable.
+
+`evaluateDocument` verifies that its result can be written faithfully. If evaluation
+creates an unrepresentable structure, such as an empty task item or adjacent
+strikethrough spans, it throws `ContentEvaluationError` and leaves the authored
+document untouched. Rendering through `transformTopikContent` does not require a
+Markdown representation and retains those structures in its derived render tree.
+
+Rendering assigns heading IDs using all authored headings before selecting
+branches or interpolating text, matching `analyzeTopikContent`. Hidden headings
+still reserve their IDs. Use explicit IDs, such as `## Hello {% $name %} {% #hello %}`,
+when a stable descriptive anchor is needed for a variable heading.
+
+## Text and code templates
+
+Use `t"..."` to interpolate `title` on `callout`, `accordion`, `card`, `tab`,
+`step`, and `codeTab`, or `alt`/`caption` on `figure`. Ordinary quoted properties
+stay literal. Empty and literal-only templates retain their template identity;
+an evaluated empty template remains a present empty value.
+
+Wrap exactly one fenced code block in `{% template code %}` and
+`{% /template code %}` on their own block lines. The markers and fence must share
+one logical parent, including a `codeTab` body. Empty payloads are valid; nested,
+missing, crossing, multi-fence, or indented-code scopes are refused. Language and
+metadata remain literal. Templated `mermaid` fences are refused before diagram
+dispatch; unknown languages remain ordinary code. Inline code and unwrapped code
+blocks stay literal.
+
+```ts
+import { compileTopikContent, formatTopikContent } from "@topik/content";
+
+const source = [
+  '{% callout title=t"Install {% $package.name %}" %}',
+  "{% template code %}",
+  "~~~sh",
+  "npm install {% $package.name %}@{% $package.version %}",
+  "~~~",
+  "{% /template code %}",
+  "{% /callout %}",
+].join("\n");
+const formatted = formatTopikContent(source);
+if (!formatted.ok) throw new Error(JSON.stringify(formatted.diagnostics));
+const compiled = compileTopikContent(source, {
+  config: { variables: { package: { name: "example-kit", version: "1.2.3" } } },
+});
+if (!compiled.ok) throw new Error(JSON.stringify(compiled.diagnostics));
+// Store source or formatted.formatted; compiled.tree contains reader values.
+if (compiled.source !== source) throw new Error("Authoring source changed");
+```
+
+Inside templates, `{% $path %}` inserts a scalar and `{%%` writes a literal `{%`
+opener. Scanning is single-pass: inserted values and escaped literals are never
+interpreted as new tokens. Code backslashes are unchanged; attribute templates
+retain ordinary quoted-string escapes. Dotted paths use identifier segments;
+expressions, functions, defaults, and bracket paths are unsupported.
+
+Strings, finite numbers, and booleans become raw text; null and empty strings
+become empty text. Missing/incompatible values and injected C0/DEL controls,
+including newlines and tabs, fail visibly. Each substitution is single-line.
+Values create no Markdown/HTML structure and receive normal renderer escaping;
+authors supply any shell/JSON/language quoting. Inactive branches validate source
+without resolving their variables.
+
+URLs, image sources, icons, math, enums, and custom component properties remain
+literal-only. Formatting preserves unevaluated templates and every branch;
+evaluation produces a separate derived result. See the [template
+reference](https://github.com/subtopik/topik/blob/main/docs/content/templates.md)
+for complete scope, escape, diagnostic, and source-storage rules.
+
+## Custom components
+
+Add declarative schemas through `config.components`. Built-in schemas cannot be
+overridden; `if` and `else` are reserved for conditions and cannot be component names.
+Custom runtime functions, partials, and executable property values
+are unsupported. Supply the corresponding render component in your application.
+Use `ComponentSchema` to type a reusable custom schema; `ComponentDefinition`
+additionally describes the built-in validators used by the runtime registry.
+
+```ts
+import {
+  parseTopikContent,
+  transformTopikContent,
+  validateTopikContent,
+  type TopikContentConfig,
+} from "@topik/content";
+
+const config: TopikContentConfig = {
+  components: {
+    notice: {
+      kind: "block",
+      render: "Notice",
+      attributes: { title: { type: "string", required: true } },
+      children: "blocks",
+    },
+  },
+};
+const source = '{% notice title="Remember" %}\nKeep a backup.\n{% /notice %}';
+if (!validateTopikContent(source, { config }).valid) throw new Error("Invalid notice");
+transformTopikContent(parseTopikContent(source, { config }), config);
+```
+
+## Asset rewriting
+
+Rewriting checks all authored branches and retains the original source on failure.
+Callbacks run after input admission; exceptions propagate. Keep callbacks free
+of side effects because a later replacement can invalidate the entire operation.
+
+```ts
+import { extractTopikAssetOccurrences, rewriteTopikAssetOccurrences } from "@topik/content";
+
+const result = rewriteTopikAssetOccurrences("![Diagram](old.png)", (occurrence) =>
+  occurrence.reference === "old.png" ? "new.png" : undefined,
+);
+if (!result.ok) throw new Error(JSON.stringify(result.diagnostics));
+if (extractTopikAssetOccurrences(result.content)[0]?.reference !== "new.png") {
+  throw new Error("Asset replacement was not preserved");
+}
+```
+
+Images and figure sources accept canonical relative paths or credential-free
+HTTPS URLs. Compiler-generated `asset:` references are accepted in rewritten
+output; source admission requires `allowCompiledAssetReferences: true` to accept
+them. Generic download links require explicit candidate selection or proven file
+paths. Custom asset attributes share validation policies but do not extend the
+compiler's closed asset-occurrence protocol.
+
+## Further documentation
+
+- [Format, normalization, and reference scopes](https://github.com/subtopik/topik/blob/main/docs/content/content-design.md)
+- [Text and code templates](https://github.com/subtopik/topik/blob/main/docs/content/templates.md)
+- [Code presentation](https://github.com/subtopik/topik/blob/main/docs/content/code-presentation.md)
+- [Explicit links and plain URLs](https://github.com/subtopik/topik/blob/main/docs/content/autolinks.md)
+- [Rendering and migration from content-schema](https://github.com/subtopik/topik/blob/main/docs/content/rendering.md)
+
+The schema version is `0.2.2` and `FORMAT_VERSION` is `1`. This package is alpha
+software. Review canonical output when upgrading and keep compiler and renderer
+versions aligned. The package verifier type-checks and executes every TypeScript
+example above against the published-package layout.