@longform/async 0.0.29

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matthew Quinn
+
+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

@@ -0,0 +1,196 @@
+# Longform
+
+<b class=keyword>Longform</b> is an easy to read markup language and transport format
+for HTML fragments.
+
+
+This repo contains the Longform language specification and some light weight Longform
+parser implementations. Both the Longform language and parsers are a work in progress.
+
+
+Read more about the Longform language in <a href=https://longform.occultist.dev>
+the Longform Markup Language</a> specification document.
+
+
+## When to use not use these parsers
+
+Longform boasts a number of interesting features allowing safe embedding of untrusted user
+content. The sanitizer and templating specifications for these features are still
+in development, as are the parser's features.
+
+
+The Longform parsers also make heavy use of regular expressions. Currently these
+have ReDos vulnerabilities in them and it will be a while before these issues are
+addressed.
+
+
+There a lot of uses for Longform without allowing untrusted user data and a lot of
+the language features are mature. But the language and specification and these
+parsers are not considered stable, keep that in mind if you decide to use them.
+
+
+## Install
+
+```
+pnpm install @longform/async
+deno install jsr:@longform/async
+
+# the sync version is not the latest and is not on JSR.
+# It is also missing features
+pnpm install @longform/longform@=0.0.6
+```
+
+## Usage
+
+```typescript
+import { longform } from '@longform/async';
+
+const markup = `
+@doctype:: html
+html::
+  head::
+    title:: Example Longform
+  body::
+    h1:: Example Longform
+    #[fragment2]
+
+#fragment1
+div::
+  p::
+    This is a Longform fragment referenceable by it's identifier.
+
+#fragment2
+div::
+  p::
+    This fragment will be embedded in the fragment that references it.
+`;
+
+const result = await longform(markup);
+
+// outputs the root fragment as HTML
+console.log(result.root);
+
+// outputs fragment1 as HTML
+console.log(result.fragments.fragment1.html);
+```
+
+
+## Sync and Async Parsers
+
+Several parsers are planned. The async parser is intended for uses of Longform
+where custom directives might be used. The sync parser will be limited to
+standard Longform features, so no custom directive support and will be usable
+in places where code must be synchronous.
+
+
+The roadmap is to get the async flavour feature complete, and then port
+to the sync parser. Following that a direct to DOM parser will be developed
+if it proves to be the more performant method of working with Longform in
+the browser. Longform will have a well defined security model for in browser
+use and support for the Trusted-Types API will be added if specific
+considerations are required.
+
+
+Also note there are many ways the editing capabilities of the Longform markup
+languages could be implemented. The scope of these parsers is to eventually
+allow data attributes be embedded in HTML elements which a client application
+could use to complete the editing feature. Reading the resulting attributes
+from the DOM, providing users with an editor and issuing the HTTP requests
+is not in scope.
+
+
+The following documentation applies to the `@longform/async` parser only.
+
+See JSR's <a href=https://jsr.io/@longform/async/doc>docs page for @longform/async</a>
+for current API documentation.
+
+
+## Status of Longform syntax features
+
+Some syntax features are still in progress. Notably:
+
+- Inline directives, ie `div:: @foo:bar`.
+- Block args with blank lines work only if the blank like has some whitespace on it.
+- Templates using the `##{foo-bar}` syntax to inline externally defined markup.
+- Templating requires some extra escaping rules.
+- Templating is currently a basic search and replace. This will later be
+  structurally aware and be restricted in some locations. The specification rules
+  will be expanded to explain these rules better so expect changes.
+
+
+## Status of standard directive support
+
+Only supported or partially supported directives are documented here.
+Most unsupported directives require the sanitizer rules be developed.
+
+
+Also note that while the HTTP PATCH features are "supported" it is
+likely that you would require other tooling to really make use of them.
+
+
+### `@id`
+
+Supported.
+
+### `@lang`
+
+Supported
+
+### `@dir`
+
+Supported
+
+### `@doctype`
+
+Supported
+
+### `@xml`
+
+Supported
+
+### `@template`
+
+Partially supported. The `processTemplate()` function can be used to
+apply templating logic but not for nested Longform markup. Note that
+this implementation will change as the sanitization features are
+developed.
+
+
+## Custom directive support
+
+The async parser supports custom directives with a number of hooks to work
+for different locations in the document structure.
+
+See the docs on the <a href=https://jsr.io/@longform/async/doc/~/Directive>
+Directive</a> type for a description of the hooks available to directives.
+Directives are passed to the Longform parser as an object.
+
+```typescript
+const directives = {
+  'foo:bar': {
+    meta: ({ inlineArgs }) => inlineArgs.trim(),
+    attr: ({ doc }) => doc.meta['foo:bar'],
+    render: ({ doc }) => doc.meta['foo:bar'],
+  },
+  'example:md': {
+    render: ({ blockArgs }) => commonmark.render(commonmark.parse(blockArgs)),
+  },
+};
+
+const doc = `
+@foo:bar:: Foo bar
+
+html::
+  head::
+    title:: @foo:bar
+    meta::
+      [name=description]
+      [content=@foo:bar]
+  body::
+    @example:md::
+      # Example document using Markdown.
+`;
+
+const result = await longform(doc, { directives });
+```
+