@flex-development/docmark-grammar 1.0.0-alpha.1

package/LICENSE.md

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Flex Development, LLC All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,100 @@
+# docmark-grammar
+
+[![npm](https://img.shields.io/npm/v/@flex-development/docmark.svg)](https://npmjs.com/package/@flex-development/docmark-grammar)
+[![npm downloads](https://img.shields.io/npm/dm/@flex-development/docmark.svg)](https://www.npmcharts.com/compare/@flex-development/docmark-grammar?interval=30)
+[![install size](https://packagephobia.now.sh/badge?p=@flex-development/docmark)](https://packagephobia.now.sh/result?p=@flex-development/docmark-grammar)
+[![module type: esm](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://github.com/voxpelli/badges-cjs-esm)
+
+core [docmark][] constructs and utilities.
+
+## Contents
+
+- [What is this?](#what-is-this)
+- [When should I use this?](#when-should-i-use-this)
+- [Install](#install)
+- [Use](#use)
+- [API](#api)
+- [Types](#types)
+- [Contribute](#contribute)
+
+## What is this?
+
+**TODO**: what is this?
+
+## When should I use this?
+
+This package is useful when extending docmark.
+
+## Install
+
+This package is [ESM only][esm].
+
+In Node.js with [yarn][]:
+
+```sh
+yarn add @flex-development/docmark-grammar
+```
+
+<blockquote>
+  <small>
+    See <a href='https://yarnpkg.com/protocol/git'>Git - Protocols | Yarn</a>
+    &nbsp;for details regarding installing from Git.
+  </small>
+</blockquote>
+
+In Deno with [`esm.sh`][esmsh]:
+
+```ts
+import {
+  blankLine,
+  eoc,
+  region,
+  summary,
+  trailingWhitespace,
+  typeExpressionValue
+} from 'https://esm.sh/@flex-development/docmark'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {
+    blankLine,
+    eoc,
+    region,
+    summary,
+    trailingWhitespace,
+    typeExpressionValue
+  } from 'https://esm.sh/@flex-development/docmark'
+</script>
+```
+
+## Use
+
+**TODO**: use
+
+## API
+
+**TODO**: api
+
+## Types
+
+This package is fully typed with [TypeScript][].
+
+## Contribute
+
+See [`CONTRIBUTING.md`](../../CONTRIBUTING.md).
+
+This project has a [code of conduct](../../CODE_OF_CONDUCT.md).
+By interacting with this repository, organization, or community you agree to abide by its terms.
+
+[docmark]: ../../README.md
+
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[typescript]: https://www.typescriptlang.org
+
+[yarn]: https://yarnpkg.com

package/dist/index.d.mts

@@ -0,0 +1,138 @@
+import type { PartialConstruct, ContinuableConstruct, NamedConstruct } from '@flex-development/docmark-util-types';
+
+/**
+ * @file Constructs - blankLine
+ * @module docmark-grammar/constructs/blankLine
+ */
+
+/**
+ * The blank line construct.
+ *
+ * A blank line may start at the beginning of stream or after a new line.
+ *
+ * At the `source` content level, blank lines are considered opaque content when
+ * there is no active comment.\
+ * Otherwise, leading whitespace is a captured as a `linePrefix`.
+ *
+ * This construct is expected to run at the `comment` or `source` content level.
+ *
+ * @category
+ *  constructs
+ *
+ * @const {PartialConstruct} blankLine
+ */
+declare const blankLine: PartialConstruct;
+
+/**
+ * @file Constructs - eoc
+ * @module docmark-grammar/constructs/eoc
+ */
+
+/**
+ * The end-of-content construct.
+ *
+ * End of content consists of zero or more line endings and/or whitespace
+ * characters followed by end of stream.
+ *
+ * This construct is used when a caller must determine whether the remainder of
+ * a content stream contains only blank lines and/or whitespace.
+ *
+ * @const {PartialConstruct} eoc
+ */
+declare const eoc: PartialConstruct;
+
+/**
+ * @file Constructs - region
+ * @module docmark-grammar/constructs/region
+ */
+
+/**
+ * Attempt a comment region at the current position.
+ *
+ * An unprefixed region attempt is made first.\
+ * If the initial attempt fails, a line prefix is then attempted and regions are
+ * checked again at the new position, or the current position if no line prefix
+ * is present.
+ *
+ * The construct fails without consuming any input if no prefixed or unprefixed
+ * region can begin.
+ *
+ * Constructs registered for the `comment` content type are then attempted
+ * in extension order.
+ *
+ * @category
+ *  constructs
+ *
+ * @const {PartialConstruct} region
+ */
+declare const region: PartialConstruct;
+
+/**
+ * @file Constructs - summary
+ * @module docmark-grammar/constructs/summary
+ */
+
+/**
+ * The comment summary construct.
+ *
+ * A summary is the initial markdown region of a comment.\
+ * Summary content is only allowed at the beginning of a comment and continues
+ * across subsequent logical comment lines until another region begins or the
+ * end of content is reached.
+ *
+ * Summary content is not tokenized by this construct,
+ * nor its `continuation` construct.
+ * Markdown chunk creation, region-boundary detection, and continuation routing
+ * are handled by the `comment` initializer.
+ *
+ * This construct is expected to run at the `comment` content level.
+ *
+ * @category
+ *  constructs
+ *
+ * @const {ContinuableConstruct & NamedConstruct} summary
+ */
+declare const summary: ContinuableConstruct & NamedConstruct;
+
+/**
+ * @file Constructs - trailingWhitespace
+ * @module docmark-grammar/constructs/trailingWhitespace
+ */
+
+/**
+ * The trailing whitespace construct.
+ *
+ * Trailing whitespace may be seen at the end of a line.
+ *
+ * > 👉 **Note**: Blank lines are expected to already be parsed.\
+ * > The construct does not check for blank lines before parse attempts.
+ *
+ * @category
+ *  constructs
+ *
+ * @const {PartialConstruct} trailingWhitespace
+ */
+declare const trailingWhitespace: PartialConstruct;
+
+/**
+ * @file Constructs - typeExpressionValue
+ * @module docmark-grammar/constructs/typeExpressionValue
+ */
+
+/**
+ * The type expression value construct.
+ *
+ * A type expression value represents the contents of a value within a type
+ * expression. The value is preserved as-is until the end of the current `type`
+ * content stream.
+ *
+ * This construct is expected to run at the `type` content level.
+ *
+ * It is `partial` so the enclosing type construct remains the tokenizer's
+ * `currentConstruct` while the value is parsed.
+ *
+ * @const {NamedConstruct & PartialConstruct} typeExpressionValue
+ */
+declare const typeExpressionValue: NamedConstruct & PartialConstruct;
+
+export { blankLine, eoc, region, summary, trailingWhitespace, typeExpressionValue };

package/dist/index.mjs

@@ -0,0 +1,148 @@
+import { factorySpace } from '@flex-development/docmark-factory-space';
+import { constants, tt } from '@flex-development/docmark-util-symbol';
+import { bos, eol, whitespace, eos } from '@flex-development/mark-util-character';
+import { ok } from 'devlop';
+
+const blankLine = {
+    partial: true,
+    previous: previousBlankLine,
+    tokenize: tokenizeBlankLine
+};
+function previousBlankLine(code) {
+    return bos(code) || eol(code);
+}
+function tokenizeBlankLine(effects, ok, nok) {
+    const self = this;
+    return startBlankLine;
+    function startBlankLine(code) {
+        if (!whitespace(code))
+            return afterLinePrefix(code);
+        const type =
+        self.contentType !== constants.contentTypeSource ||
+            self.containerState?.comment
+            ? tt.linePrefix
+            : undefined;
+        return factorySpace(effects, afterLinePrefix, type)(code);
+    }
+    function afterLinePrefix(code) {
+        if (eol(code) || eos(code))
+            return ok(code);
+        return nok(code);
+    }
+}
+
+const eoc = { partial: true, tokenize: tokenizeEndOfContent };
+function tokenizeEndOfContent(effects, ok, nok) {
+    return maybeEnd;
+    function maybeEnd(code) {
+        if (eos(code))
+            return ok(code);
+        if (eol(code) || whitespace(code))
+            return effects.consume(code), maybeEnd;
+        return nok(code);
+    }
+}
+
+const region = { partial: true, tokenize: tokenizeRegion };
+function tokenizeRegion(effects, ok$1, nok) {
+    const self = this;
+    return effects.attempt(this.parser.constructs.comment, ok$1, prefixedRegion);
+    function prefixedRegion(code) {
+        ok(self.parser.constructs.disable.null, 'expected `disable.null`');
+        ok(eos(code) || bos(self.previous) || eol(self.previous), 'expected end of stream, beginning of stream, or beginning of line');
+        return factorySpace(effects, effects.attempt(self.parser.constructs.comment, ok$1, nok), tt.linePrefix, self.parser.constructs.disable.null.includes(tt.codeIndented)
+            ? undefined
+            : constants.tabSize)(code);
+    }
+}
+
+const summary = {
+    continuation: { tokenize: tokenizeSummaryContinuation },
+    exit: exitSummary,
+    name: tt.summary,
+    previous: previousSummary,
+    tokenize: tokenizeSummary
+};
+function exitSummary(effects) {
+    return void effects.exit(tt.summary);
+}
+function previousSummary(code) {
+    return bos(code) || eol(code);
+}
+function tokenizeSummary(effects, ok$1, nok) {
+    const self = this;
+    return startSummary;
+    function startSummary(code) {
+        ok(self.containerState, 'expected `containerState` inside region');
+        ok(!self.parser.atBlankLine, 'did not expect blank line');
+        ok(!eol(code), 'did not expect line ending');
+        ok(!eos(code), 'did not expect end of stream');
+        if (self.containerState.open)
+            return nok(code);
+        if (self.parser.skipSummary)
+            return nok(code);
+        effects.enter(tt.summary, { _container: true, _region: true });
+        self.containerState.open = true;
+        effects.enter(tt.summaryMarker);
+        effects.exit(tt.summaryMarker);
+        return effects.check(region, nok, ok$1)(code);
+    }
+}
+function tokenizeSummaryContinuation(effects, ok, nok) {
+    return continueSummary;
+    function continueSummary(code) {
+        if (eos(code))
+            return nok(code);
+        return ok(code);
+    }
+}
+
+const trailingWhitespace = {
+    partial: true,
+    tokenize: tokenizeTrailingWhitespace
+};
+function tokenizeTrailingWhitespace(effects, ok$1, nok) {
+    const self = this;
+    return whitespaceTrail;
+    function whitespaceTrail(code) {
+        ok(!self.parser.atBlankLine, 'did not expect blank line');
+        ok(whitespace(code), 'expected whitespace');
+        return factorySpace(effects, afterWhitespaceTrail, tt.whitespace)(code);
+    }
+    function afterWhitespaceTrail(code) {
+        self.events.at(-1)[1]._trailing = true;
+        if (eol(code)) {
+            effects.enter(tt.lineEnding);
+            effects.consume(code);
+            effects.exit(tt.lineEnding);
+            return ok$1;
+        }
+        if (eos(code))
+            return ok$1(code);
+        return nok(code);
+    }
+}
+
+const typeExpressionValue = {
+    add: 'after',
+    name: tt.typeExpressionValue,
+    partial: true,
+    tokenize: tokenizeTypeExpressionValue
+};
+function tokenizeTypeExpressionValue(effects, ok) {
+    return startTypeExpressionValue;
+    function startTypeExpressionValue(code) {
+        effects.enter(tt.typeExpressionValue);
+        return insideValue(code);
+    }
+    function insideValue(code) {
+        if (eos(code)) {
+            effects.exit(tt.typeExpressionValue);
+            return ok(code);
+        }
+        effects.consume(code);
+        return insideValue;
+    }
+}
+
+export { blankLine, eoc, region, summary, trailingWhitespace, typeExpressionValue };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@flex-development/docmark-grammar",
+  "description": "core docmark constructs and utilities",
+  "version": "1.0.0-alpha.1",
+  "keywords": [
+    "commonmark",
+    "docdown",
+    "docmark",
+    "documentation",
+    "gfm",
+    "markdown",
+    "md",
+    "mdast",
+    "parse",
+    "parser",
+    "token",
+    "tokenize",
+    "tokenizer"
+  ],
+  "license": "BSD-3-Clause",
+  "homepage": "https://github.com/flex-development/docmark",
+  "repository": {
+    "directory": "packages/docmark-grammar",
+    "type": "git",
+    "url": "git+https://github.com/flex-development/docmark.git"
+  },
+  "bugs": "https://github.com/flex-development/docmark/issues",
+  "author": {
+    "name": "Lexus Drumgold",
+    "url": "https://github.com/unicornware"
+  },
+  "publishConfig": {
+    "access": "public",
+    "diff-dst-prefix": "docmark-grammar",
+    "diff-src-prefix": "docmark-grammar",
+    "directory": "./",
+    "executableFiles": [],
+    "node-options": null,
+    "pack-destination": ".",
+    "parseable": true,
+    "prefer-dedupe": true,
+    "provenance": true,
+    "tag-version-prefix": "docmark-grammar"
+  },
+  "type": "module",
+  "files": [
+    "LICENSE.md",
+    "README.md",
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "docmark": "./src/index.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "scripts": {
+    "attw": "tsc --build tsconfig.build.json --clean --dry && tsc --build tsconfig.build.json --clean && tsc --build tsconfig.build.json --verbose"
+  },
+  "dependencies": {
+    "@flex-development/docmark-factory-space": "1.0.0-alpha.1",
+    "@flex-development/docmark-util-symbol": "1.0.0-alpha.1",
+    "@flex-development/docmark-util-types": "1.0.0-alpha.1",
+    "@flex-development/mark-util-character": "1.1.0",
+    "devlop": "1.1.0"
+  },
+  "sideEffects": false,
+  "build": "524f7d653272a777cde27efaac4656fb90cd4855"
+}