More docs improvements

Author: bcomnes

README.md

@@ -1,16 +1,17 @@
-# Basic DOMStack Example
+# Basic DOMStack Example with TypeScript
 
-This example demonstrates a fundamental website built with DOMStack, showcasing core features without advanced customization.
+This example demonstrates a fundamental website built with DOMStack using TypeScript, showcasing core features without advanced customization.
 
 ## Overview
 
 The basic example illustrates:
-- Multiple page types (Markdown, HTML, JavaScript)
+- Multiple page types (Markdown, HTML, JavaScript/TypeScript)
 - Layout system and page nesting
 - Asset handling
-- Client-side JavaScript integration
+- Client-side TypeScript integration
 - CSS styling (global and page-specific)
 - Variables and metadata
+- TypeScript integration with proper type definitions
 
 ## Getting Started
 
@@ -41,34 +42,46 @@ The built site will be in the `public` directory.
 
 ```
 src/
-├── layouts/            # Layout templates
-│   ├── root.layout.js  # Main layout
-│   └── child.layout.js # Nested layout
-├── md-page/            # Markdown page examples
-├── js-page/            # JavaScript page examples
-├── html-page/          # HTML page examples
-├── global.css          # Global styles
-├── global.client.js    # Global client-side JavaScript
-├── global.vars.js      # Global variables
-└── README.md           # Main content (becomes index.html)
+├── layouts/             # Layout templates
+│   ├── root.layout.ts   # Main layout (TypeScript)
+│   └── child.layout.ts  # Nested layout (TypeScript)
+├── md-page/             # Markdown page examples
+│   ├── page.vars.ts     # Page variables (TypeScript)
+│   └── client.ts        # Page-specific client script (TypeScript)
+├── js-page/             # JavaScript page examples (kept as JS for demonstration)
+│   ├── loose-assets/    # Contains TypeScript files
+│   │   ├── page.ts      # TypeScript page
+│   │   ├── client.ts    # TypeScript client
+│   │   └── shared-lib.ts # TypeScript shared library
+├── html-page/           # HTML page examples
+│   └── client.ts        # Page-specific client script (TypeScript)
+├── global.css           # Global styles
+├── global.client.ts     # Global client-side TypeScript
+├── global.vars.ts       # Global variables (TypeScript)
+└── README.md            # Main content (becomes index.html)
 ```
 
-## Key Features Demonstrated
+### Key Features Demonstrated
 
 ### Page Types
 - **Markdown pages** - Simple content authoring with frontmatter
-- **JavaScript pages** - Dynamic content generation with full JS capabilities
+- **JavaScript/TypeScript pages** - Dynamic content generation with full JS/TS capabilities
 - **HTML pages** - Direct HTML control for complex layouts
 
 ### Layouts
-The example demonstrates DOMStack's layout system with nested layouts that wrap page content.
+The example demonstrates DOMStack's layout system with nested layouts that wrap page content, fully typed with TypeScript interfaces.
 
 ### Assets
 Static assets like images are co-located with content and automatically copied to the output directory.
 
 ### Styling
 Both global and page-specific CSS is demonstrated, showing how to scope styles appropriately.
 
+### TypeScript Integration
+- **Strong typing** - Full TypeScript support with interfaces for layouts, pages, and components
+- **JSDoc example** - The js-page directory is kept as JavaScript with JSDoc comments to demonstrate compatibility
+- **Type definitions** - Proper type definitions for page variables, layout functions, and client scripts
+
 ## Learn More
 
 This is one of several examples in the DOMStack repository. For more advanced features, check out the other examples like:
@@ -77,4 +90,4 @@ This is one of several examples in the DOMStack repository. For more advanced fe
 - tailwind
 - and more...
 
-For complete documentation, visit the [DOMStack GitHub repository](https://github.com/bcomnes/domstack).
+For complete documentation, visit the [DOMStack GitHub repository](https://github.com/bcomnes/domstack).

examples/basic/README.md

@@ -7,22 +7,23 @@
     "start": "npm run watch",
     "build": "npm run clean && domstack",
     "clean": "rm -rf public && mkdir -p public",
-    "watch": "npm run clean && run-p watch:*",
-    "watch:serve": "browser-sync start --server 'public' --files 'public'",
-    "watch:domstack": "npm run build -- --watch"
+    "watch": "npm run clean && dom --watch",
+    "test": "tsc"
   },
   "keywords": [],
   "author": "Bret Comnes <[email protected]> (https://bret.io/)",
   "license": "MIT",
   "devDependencies": {
-    "browser-sync": "^2.26.7",
-    "npm-run-all2": "^6.0.0"
+    "npm-run-all2": "^6.0.0",
+    "typescript": "~5.8.2",
+    "@voxpelli/tsconfig": "^15.0.0"
   },
   "dependencies": {
     "@domstack/cli": "file:../../.",
     "htm": "^3.1.1",
     "preact": "^10.26.6",
     "preact-render-to-string": "^6.5.13",
-    "mine.css": "^9.0.1"
+    "mine.css": "^9.0.1",
+    "highlight.js": "^11.9.0"
   }
 }

examples/basic/package.json

@@ -1,6 +1,6 @@
 console.log('This client bundle only loads in the root page.')
 
-// Each page folder can have a client.js file in it.
-// The client.js file is treated as an entry point script for just the
+// Each page folder can have a client.ts file in it.
+// The client.ts file is treated as an entry point script for just the
 // page it is associated with, but all dependencies are de-duped via
 // esbuild.

examples/basic/src/client.js examples/basic/src/client.tsexamples/basic/src/client.js renamed to examples/basic/src/client.ts

@@ -1,5 +1,12 @@
+// @ts-expect-error
 import { toggleTheme } from 'mine.css'
 
+declare global {
+  interface Window {
+    toggleTheme: typeof toggleTheme;
+  }
+}
+
 window.toggleTheme = toggleTheme
 
 console.log('The global client is loaded on every page.')

examples/basic/src/global.client.js examples/basic/src/global.client.tsexamples/basic/src/global.client.js renamed to examples/basic/src/global.client.ts

@@ -1,5 +1,6 @@
 @import 'mine.css/dist/mine.css';
 @import 'mine.css/dist/layout.css';
+@import 'highlight.js/styles/github-dark-dimmed.css';
 
 /* The global.css in the root directory of the site is loaded on every page. */
 

examples/basic/src/global.css

@@ -1,9 +1,14 @@
-// The global.vars.js file should export default either an object, function that
+// The global.vars.ts file should export default either an object, function that
 // returns an object or an async function that returns an object.
 //
 // These variables are available to every page, and have the lowest precedence.
 
-export default async function () {
+interface GlobalVars {
+  siteName: string;
+  [key: string]: unknown;
+}
+
+export default async function (): Promise<GlobalVars> {
   return {
     siteName: 'domstack basic',
   }

examples/basic/src/global.vars.js examples/basic/src/global.vars.tsexamples/basic/src/global.vars.js renamed to examples/basic/src/global.vars.ts

@@ -0,0 +1,3 @@
+import sharedData from './shared-lib.ts'
+
+console.log(sharedData.shared)