From 250e31ed530dd38edf36befd39e5ec40b85b84da Mon Sep 17 00:00:00 2001
From: nathan <nathangray.bsc+github@gmail.com>
Date: Fri, 22 Sep 2023 15:03:37 -0600
Subject: [PATCH] Some more styling & docs

---
 doc/etemplate2/_includes/default.njk          |  5 +-
 doc/etemplate2/_includes/sidebar.njk          |  2 +
 doc/etemplate2/assets/styles/docs.css         |  4 +-
 doc/etemplate2/pages/components/sandbox.md    |  6 ++
 .../pages/getting-started/widgets.md          | 12 ++--
 .../pages/tutorials/automatic-testing.md      | 69 +++++++++++++++++++
 .../pages/tutorials/creating-a-widget.md      | 39 +++++++++++
 7 files changed, 126 insertions(+), 11 deletions(-)
 create mode 100644 doc/etemplate2/pages/components/sandbox.md
 create mode 100644 doc/etemplate2/pages/tutorials/automatic-testing.md
 create mode 100644 doc/etemplate2/pages/tutorials/creating-a-widget.md

diff --git a/doc/etemplate2/_includes/default.njk b/doc/etemplate2/_includes/default.njk
index 363b23ae49..52764d27bf 100644
--- a/doc/etemplate2/_includes/default.njk
+++ b/doc/etemplate2/_includes/default.njk
@@ -29,8 +29,11 @@
     <meta property="og:description" content="{{ meta.description }}" />
     <meta property="og:image" content="{{ assetUrl(meta.image, true) }}" />
 
+    {# API Viewer Element #}
+	<script type="module" src="https://jspm.dev/api-viewer-element"></script>
+
     {# EGroupware #}
-    <script src="{{ assetUrl('scripts/etemplate/etemplate2.js') }}" type="module"></script>
+    <!--<script src="{{ assetUrl('scripts/etemplate/etemplate2.js') }}" type="module"></script>-->
 
     {# Shoelace #}
     <link rel="stylesheet" href="{{ assetUrl('shoelace/themes/light.css') }}" />
diff --git a/doc/etemplate2/_includes/sidebar.njk b/doc/etemplate2/_includes/sidebar.njk
index 96d97e2019..921035201b 100644
--- a/doc/etemplate2/_includes/sidebar.njk
+++ b/doc/etemplate2/_includes/sidebar.njk
@@ -21,6 +21,7 @@
   <li>
     <h2>Components</h2>
     <ul>
+    <li><em><a href="/components/sandbox">Sandbox</a></em></li>
       {% for component in meta.components %}
         <li>
           <a href="/components/{{ component.tagName | removeSlPrefix }}">
@@ -33,6 +34,7 @@
   <li>
     <h2>Tutorials</h2>
     <ul>
+	  <li><a href="/tutorials/creating-a-widget">Creating a widget</a></li>
       <li><a href="/tutorials/integrating-with-egw">Integrating with EGroupware</a></li>
       <li><a href="/tutorials/link-system">Implementing the linking system</a></li>
     </ul>
diff --git a/doc/etemplate2/assets/styles/docs.css b/doc/etemplate2/assets/styles/docs.css
index 7b52198156..fcc676c282 100644
--- a/doc/etemplate2/assets/styles/docs.css
+++ b/doc/etemplate2/assets/styles/docs.css
@@ -3,10 +3,10 @@
   --docs-border-color: var(--sl-color-neutral-200);
   --docs-border-width: 1px;
   --docs-border-radius: var(--sl-border-radius-medium);
-  --docs-content-max-width: 860px;
+	--docs-content-max-width: 100%;
   --docs-sidebar-width: 320px;
   --docs-sidebar-transition-speed: 250ms;
-  --docs-content-toc-max-width: 260px;
+	--docs-content-toc-max-width: 220px;
   --docs-content-padding: 2rem;
   --docs-content-vertical-spacing: 2rem;
   --docs-search-overlay-background: rgb(0 0 0 / 0.2);
diff --git a/doc/etemplate2/pages/components/sandbox.md b/doc/etemplate2/pages/components/sandbox.md
new file mode 100644
index 0000000000..f95778a111
--- /dev/null
+++ b/doc/etemplate2/pages/components/sandbox.md
@@ -0,0 +1,6 @@
+## Widget Sandbox
+
+You can see and play with the widgets, once they're loaded.
+Maybe this should go on each page, limited to just that widget.
+
+<api-viewer src="/assets/custom-elements.json"></api-viewer>
\ No newline at end of file
diff --git a/doc/etemplate2/pages/getting-started/widgets.md b/doc/etemplate2/pages/getting-started/widgets.md
index 0f6f6e9a6a..3a1054d54e 100644
--- a/doc/etemplate2/pages/getting-started/widgets.md
+++ b/doc/etemplate2/pages/getting-started/widgets.md
@@ -1,16 +1,12 @@
 ## Widgets
 
 Widgets are the building blocks of our UI.
-While there is some legacy mess, we are currently making all our
+We are currently making all our
 widgets [WebComponents](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
-based on [Lit](https://lit.dev/docs/).
+based on [Lit](https://lit.dev/docs/). Many of our widgets use [Shoelace](https://shoelace.style) components as building
+blocks.
 
-Automated widget testing is done using "web-test-runner" to run the tests, which are written using
-
-* Mocha (https://mochajs.org/) & Chai Assertion Library (https://www.chaijs.com/api/assert/)
-* Playwright (https://playwright.dev/docs/intro) runs the tests in actual browsers.
-
-If you just want to use existing widgets, you can just put them in your .xet template file:
+If you just want to use existing widgets, you can put them in your .xet template file:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
diff --git a/doc/etemplate2/pages/tutorials/automatic-testing.md b/doc/etemplate2/pages/tutorials/automatic-testing.md
new file mode 100644
index 0000000000..6dbd93d9ac
--- /dev/null
+++ b/doc/etemplate2/pages/tutorials/automatic-testing.md
@@ -0,0 +1,69 @@
+## Automatic testing
+
+Automatic tests go in the `test/` subfolder of your component's directory. They will be found and run by
+“web-test-runner”.
+Tests are written using
+
+* Mocha (https://mochajs.org/) & Chai Assertion Library (https://www.chaijs.com/api/assert/)
+* Playwright (https://playwright.dev/docs/intro) runs the tests in actual browsers.
+
+Here's a simple example:
+
+```ts
+/**
+ * Test file for Etemplate webComponent Textbox
+ */
+import {assert, fixture, html} from '@open-wc/testing';
+import {Et2Textbox} from "../Et2Textbox";
+import {inputBasicTests} from "../../Et2InputWidget/test/InputBasicTests";
+
+// Reference to component under test
+let element : Et2Textbox;
+
+async function before()
+{
+	// Create an element to test with, and wait until it's ready
+	element = await fixture<Et2Textbox>(html`
+        <et2-textbox></et2-textbox>
+	`);
+	return element;
+}
+
+describe("Textbox widget", () =>
+{
+	// Setup run before each test
+	beforeEach(before);
+
+	it('is defined', () =>
+	{
+		assert.instanceOf(element, Et2Textbox);
+	});
+
+	it('has a label', () =>
+	{
+		element.set_label("Yay label");
+		assert.isEmpty(element.shadowRoot.querySelectorAll('.et2_label'));
+	})
+});
+
+// Run some common, basic tests for inputs (readonly, value, etc.)
+inputBasicTests(before, "I'm a good test value", "input");
+```
+
+This verifies that the component can be loaded and created.  `inputBasicTests()` checks readonly and in/out values.
+
+### What to test
+
+#### Can the component be loaded and created?
+
+Quite often components get accidental dependencies that complicate things, but sometimes they just break.
+
+#### Value in = value out
+
+Many of our components do correction and coercion on bad data or invalid values, but you should test that values out
+match
+the values going in. How to do this, and what to do with bad values, depends on the component.
+
+### Test tips
+
+* Always use `this.egw()`. It can be easily stubbed for your test. Global `egw` cannot.
\ No newline at end of file
diff --git a/doc/etemplate2/pages/tutorials/creating-a-widget.md b/doc/etemplate2/pages/tutorials/creating-a-widget.md
new file mode 100644
index 0000000000..51ee7dd065
--- /dev/null
+++ b/doc/etemplate2/pages/tutorials/creating-a-widget.md
@@ -0,0 +1,39 @@
+## Creating a component
+
+ETemplate components are [LitElements](https://lit.dev/docs/) that are wrapped with
+our [Et2Widget](https://github.com/EGroupware/egroupware/blob/master/api/js/etemplate/Et2Widget/Et2Widget.ts) mixin,
+which adds properties and methods to support loading from our template files and returning values to the server. They
+should (relatively) stand-alone.
+
+Common components are in `api/js/etemplate/`. You can add application specific components in `<appname>/js/`.
+
+### Create the files
+
+```
+myapp/
+    js/
+        MyWidget/
+            test/
+            MyWidget.ts
+            
+```
+
+You should have [automatic tests](/tutorials/automatic-testing) to verify your component and avoid regressions
+in `test/`.
+
+### Get it loaded
+
+To have EGroupware load your component, it must be included somewhere.
+Add your component to the `include` block at the top of `/api/js/etemplate/etemplate2.js`. If you have an application
+specific component, include at the top of your `app.js`.
+
+```typescript
+...
+import './MyWidget/MyWidget.ts';
+
+...
+```
+
+### Load and return
+
+### AJAX data