(feat) Docxml playground

.github/workflows/playground-pages.yml

@@ -0,0 +1,51 @@
+name: Playground Pages
+
+on:
+    push:
+        branches:
+            - playground
+    release:
+        types:
+            - published
+    workflow_dispatch:
+
+permissions:
+    contents: read
+    pages: write
+    id-token: write
+
+concurrency:
+    group: pages
+    cancel-in-progress: true
+
+jobs:
+    deploy:
+        environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v6
+              with:
+                  ref: ${{ inputs.ref || github.ref }}
+
+            - name: Setup Deno
+              uses: denoland/setup-deno@v2
+              with:
+                  deno-version: 2.8.0
+
+            - name: Build playground
+              run: deno task playground:build
+
+            - name: Setup Pages
+              uses: actions/configure-pages@v6
+
+            - name: Upload playground artifact
+              uses: actions/upload-pages-artifact@v5
+              with:
+                  path: playground/dist
+
+            - name: Deploy to GitHub Pages
+              id: deployment
+              uses: actions/deploy-pages@v5

README.md

@@ -5,11 +5,11 @@ an existing `.docx` or `.dotx` template.
 
 You could use `docxml` to:
 
--   Create an MS Word file without ever opening MS Word
--   Create a parameterized template file and render it to `.docx` with your data parameters
--   Write JSON, XML or other data structures to `.docx`
--   Parse content from an existing `.docx` file
--   Extract style information from a `.docx` or `.dotx` file
+- Create an MS Word file without ever opening MS Word
+- Create a parameterized template file and render it to `.docx` with your data parameters
+- Write JSON, XML or other data structures to `.docx`
+- Parse content from an existing `.docx` file
+- Extract style information from a `.docx` or `.dotx` file
 
 This documentation for this lib is available at various locations:
 
@@ -18,6 +18,10 @@ This documentation for this lib is available at various locations:
 [👉 Deno mirror](http://jsr.io/@fontoxml/docxml)<br />
 [👉 npm mirror](http://npmjs.org/package/docxml)
 
+#### Try it now!
+
+**[Docxml playground](https://fontoxml.github.io/docxml/)**
+
 #### For Deno
 
 [👉 Main article](https://github.com/fontoxml/docxml/wiki/Deno-or-Node)
@@ -85,68 +89,68 @@ yet -- they are not available, but hopefully soon.
 
 **API features:**
 
--   [x] 100% typed
--   [x] Asynchronous components
--   [x] Component composition
+- [x] 100% typed
+- [x] Asynchronous components
+- [x] Component composition
 
 **Custom styles:**
 
--   [x] Font size and color
--   [x] Bold, italic, underline styles, strike-through
--   [x] Subscript, superscript, small caps
--   [x] Paragraph spacing and indentation
--   [x] Left/right/center/justified alignment
--   [x] Numbering
--   [ ] Aligning text on tabs
--   [x] Font family
--   [ ] Embed TTF in the DOCX file
+- [x] Font size and color
+- [x] Bold, italic, underline styles, strike-through
+- [x] Subscript, superscript, small caps
+- [x] Paragraph spacing and indentation
+- [x] Left/right/center/justified alignment
+- [x] Numbering
+- [ ] Aligning text on tabs
+- [x] Font family
+- [ ] Embed TTF in the DOCX file
 
 **References:**
 
--   [x] Cross references
--   [ ] Table of contents
+- [x] Cross references
+- [ ] Table of contents
 
 **Tables:**
 
--   [x] Colspans and rowspans
--   [x] Cell borders
--   [x] [Table borders](http://officeopenxml.com/WPtableBorders.php)
--   [x] [Conditional formatting](http://officeopenxml.com/WPtblLook.php)
+- [x] Colspans and rowspans
+- [x] Cell borders
+- [x] [Table borders](http://officeopenxml.com/WPtableBorders.php)
+- [x] [Conditional formatting](http://officeopenxml.com/WPtblLook.php)
 
 **Images:**
 
--   [x] From any `UInt8Array` source
--   [x] Alternative and title text
--   [x] Width and height
+- [x] From any `UInt8Array` source
+- [x] Alternative and title text
+- [x] Width and height
 
 **Sections:**
 
--   [x] Width and height
--   [x] Orientation
--   [x] Page headers & footers
+- [x] Width and height
+- [x] Orientation
+- [x] Page headers & footers
 
 **Comments:**
 
--   [x] Point comment
--   [x] Range comment
--   [ ] Comment reply
+- [x] Point comment
+- [x] Range comment
+- [ ] Comment reply
 
 **Change tracking:**
 
--   [x] Text additions and deletions
--   [x] Style changes
--   [x] Table row additions and deletions
+- [x] Text additions and deletions
+- [x] Style changes
+- [x] Table row additions and deletions
 
 #### Differences with actual MS Word DOCX
 
 Obviously `docxml` is a TypeScript project, which is already very different from how you would normally interact with a `.docx` file. More meaningfully however, `docxml` is meant to make writing Word document files _easier_ than going straight to OOXML. For example:
 
--   All sizes are of type `Length`, which means it doesn't matter wether you input them as points, centimeters, inches, 1/2, 1/8th or 1/20th points, English Metric Units, and so on.
--   The JSX pragma will try to correct components that would lead to invalid XML structures, by splitting the parents of invalidly placed components recursively until the new position is valid. Moreover, string content in unexpected places is automatically wrapped in `<Text>` when using JSX. This makes the configuration of a new DOCX a little more forgiving.
--   Using the `<Image>` or `<Comment>` components will automatically create all required relationships etc.
--   Some of the words have changed, generally speaking `docxml` is more verbose than the DOCX verbiage.
--   Generally speaking `docxml` prefers formal (JS) references over references-by-identifier. In those cases the identifiers are randomly generated for you when the `.docx` file is written.
--   Especially in tables and images, a lot of formatting details are automatically applied. In a lot of cases there is no API _yet_ to change them.
+- All sizes are of type `Length`, which means it doesn't matter wether you input them as points, centimeters, inches, 1/2, 1/8th or 1/20th points, English Metric Units, and so on.
+- The JSX pragma will try to correct components that would lead to invalid XML structures, by splitting the parents of invalidly placed components recursively until the new position is valid. Moreover, string content in unexpected places is automatically wrapped in `<Text>` when using JSX. This makes the configuration of a new DOCX a little more forgiving.
+- Using the `<Image>` or `<Comment>` components will automatically create all required relationships etc.
+- Some of the words have changed, generally speaking `docxml` is more verbose than the DOCX verbiage.
+- Generally speaking `docxml` prefers formal (JS) references over references-by-identifier. In those cases the identifiers are randomly generated for you when the `.docx` file is written.
+- Especially in tables and images, a lot of formatting details are automatically applied. In a lot of cases there is no API _yet_ to change them.
 
 #### For contributors
 

deno.json

@@ -49,9 +49,12 @@
 	},
 	"importMap": "imports.json",
 	"tasks": {
-		"check": "deno check .",
-		"lint": "deno lint",
+		"check": "deno check mod.ts inspect.ts $(find examples lib vendor -type f \\( -name '*.ts' -o -name '*.tsx' \\))",
+		"lint": "deno lint --ignore=playground/dist",
 		"test": "deno task lint && deno task check && deno test -A lib",
+		"playground:dev": "cd playground && deno task dev",
+		"playground:build": "cd playground && deno task build",
+		"playground:preview": "cd playground && deno task preview",
 		"test:coverage": "deno task test --coverage=coverage && deno coverage --exclude='utils/xml-validation/fontoxml' --exclude='vendor' --lcov --output=coverage/cov.lcov coverage && genhtml --ignore-errors inconsistent --output-directory ./coverage/html_cov ./coverage/cov.lcov && open ./coverage/html_cov/index.html",
 		"precommit": "deno task lint && deno task test"
 	}

imports.json

@@ -15,6 +15,7 @@
 		"std/path/posix/relative": "jsr:@std/path@1.1.4/posix/relative",
 		"std/path/posix/resolve": "jsr:@std/path@1.1.4/posix/resolve",
 		"std/testing/bdd": "jsr:@std/testing@1.0.18/bdd",
+		"typescript": "npm:typescript@6.0.3",
 
 		"xml_renderer": "./vendor/xml_renderer/mod.ts"
 	}

playground/.gitignore

@@ -0,0 +1,3 @@
+dist/
+node_modules/
+public/

playground/deno.json

@@ -0,0 +1,16 @@
+{
+	"tasks": {
+		"types": "deno run -A scripts/generate-docxml-dts.ts",
+		"dev": "deno task types && deno run -A --node-modules-dir=auto npm:vite",
+		"build": "deno task types && deno run -A --node-modules-dir=auto npm:vite build",
+		"preview": "deno run -A --node-modules-dir=auto npm:vite preview --host --port 4173"
+	},
+	"nodeModulesDir": "auto",
+	"compilerOptions": {
+		"lib": ["dom", "dom.iterable", "es2021"],
+		"jsx": "react-jsx",
+		"jsxImportSource": "preact",
+		"types": ["vite/client"]
+	},
+	"exclude": ["dist"]
+}