Skip to content

Commit 289719d

Browse files
bcomnesbcomnes
committed
Switch examples over to use preact and general improvements
Generally switch all examples over to use preact, add react, etc.
1 parent 5d4c158 commit 289719d

File tree

65 files changed

+3223
-279
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+3223
-279
lines changed

‎examples/basic/README.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Basic DOMStack Example
2+
3+
This example demonstrates a fundamental website built with DOMStack, showcasing core features without advanced customization.
4+
5+
## Overview
6+
7+
The basic example illustrates:
8+
- Multiple page types (Markdown, HTML, JavaScript)
9+
- Layout system and page nesting
10+
- Asset handling
11+
- Client-side JavaScript integration
12+
- CSS styling (global and page-specific)
13+
- Variables and metadata
14+
15+
## Getting Started
16+
17+
### Prerequisites
18+
19+
- Node.js 22.x or higher
20+
21+
### Installation
22+
23+
```bash
24+
# Install dependencies
25+
npm install
26+
```
27+
28+
### Building the Example
29+
30+
```bash
31+
# Build the site
32+
npm run build
33+
34+
# Watch for changes during development
35+
npm run watch
36+
```
37+
38+
The built site will be in the `public` directory.
39+
40+
## Project Structure
41+
42+
```
43+
src/
44+
├── layouts/ # Layout templates
45+
│ ├── root.layout.js # Main layout
46+
│ └── child.layout.js # Nested layout
47+
├── md-page/ # Markdown page examples
48+
├── js-page/ # JavaScript page examples
49+
├── html-page/ # HTML page examples
50+
├── global.css # Global styles
51+
├── global.client.js # Global client-side JavaScript
52+
├── global.vars.js # Global variables
53+
└── README.md # Main content (becomes index.html)
54+
```
55+
56+
## Key Features Demonstrated
57+
58+
### Page Types
59+
- **Markdown pages** - Simple content authoring with frontmatter
60+
- **JavaScript pages** - Dynamic content generation with full JS capabilities
61+
- **HTML pages** - Direct HTML control for complex layouts
62+
63+
### Layouts
64+
The example demonstrates DOMStack's layout system with nested layouts that wrap page content.
65+
66+
### Assets
67+
Static assets like images are co-located with content and automatically copied to the output directory.
68+
69+
### Styling
70+
Both global and page-specific CSS is demonstrated, showing how to scope styles appropriately.
71+
72+
## Learn More
73+
74+
This is one of several examples in the DOMStack repository. For more advanced features, check out the other examples like:
75+
- css-modules
76+
- preact
77+
- tailwind
78+
- and more...
79+
80+
For complete documentation, visit the [DOMStack GitHub repository](https://github.com/bcomnes/domstack).

‎examples/basic/package.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,9 @@
2020
},
2121
"dependencies": {
2222
"@domstack/cli": "../../.",
23-
"uhtml-isomorphic": "^2.1.0",
23+
"htm": "^3.1.1",
24+
"preact": "^10.26.6",
25+
"preact-render-to-string": "^6.5.13",
2426
"mine.css": "^9.0.1"
2527
}
2628
}

‎examples/basic/src/README.md‎

Lines changed: 57 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,64 @@
11
---
2+
title: Basic DOMStack Example
23
md-files: support yaml frontmatter!
34
---
4-
# Minimal domstack example
55

6-
This example demonstrates a example of a minimal website, no customization.
6+
# Basic DOMStack Example
77

8-
It's just a `src` folder with a few markdown files that link to each other. Markdown files can link directly to their markdown counterparts so navigation works inside GitHub's built in markdown source navigator.
8+
This example demonstrates a complete basic website built with DOMStack, showcasing the core features without advanced customization.
99

10-
- [loose-file.md](./loose-file.md)
11-
- [nested-md](./md-page/README.md)
12-
- [sub-page](./md-page/sub-page/README.md)
10+
## Features Demonstrated
1311

14-
Also notice how the title of this document set the `title` variable for the page, and renders in the title `<head>` properly.
15-
Page builders can implement variable extraction based on assumptions like this for a given document type.
16-
More automatic variable extraction is planned, like `git` metadata (first commit date, last commit date that touched the file. etc).
12+
- Multiple page types (Markdown, HTML, JavaScript)
13+
- Page layouts and nesting
14+
- Asset handling
15+
- Client-side JavaScript
16+
- CSS styling (global and page-specific)
17+
- Frontmatter variables
18+
19+
## Project Structure
20+
21+
```
22+
src/
23+
├── layouts/ # Layout templates
24+
├── md-page/ # Markdown page examples
25+
├── js-page/ # JavaScript page examples
26+
├── html-page/ # HTML page examples
27+
├── global.css # Global styles
28+
├── global.client.js # Global client-side JavaScript
29+
├── global.vars.js # Global variables
30+
└── README.md # This file (becomes index.html)
31+
```
32+
33+
## Page Examples
34+
35+
Navigate through different page types:
36+
37+
- [Loose Markdown File](./loose-file.md)
38+
- [Markdown Page Example](./md-page/README.md)
39+
- [Nested Markdown Page](./md-page/sub-page/README.md)
40+
- [JavaScript Page Example](./js-page/page.js)
41+
- [HTML Page Example](./html-page/page.html)
42+
43+
## How It Works
44+
45+
- **Markdown Pages**: The title of this document (`h1`) becomes the `title` variable for the page and renders in the `<title>` tag.
46+
- **Layouts**: Pages use layouts defined in the `layouts` directory.
47+
- **Assets**: Static assets are copied to the output directory.
48+
- **Styling**: Both global and page-specific CSS is processed and included.
49+
- **Client JS**: JavaScript bundles are created for enhanced functionality.
50+
51+
## Building the Example
52+
53+
Run the following commands:
54+
55+
```bash
56+
npm install
57+
npm run build
58+
```
59+
60+
To watch for changes during development:
61+
62+
```bash
63+
npm run watch
64+
```

‎examples/basic/src/js-page/loose-assets/page.js‎

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,23 @@
1-
import { html } from 'uhtml-isomorphic'
1+
import { html } from 'htm/preact'
2+
import { render } from 'preact-render-to-string'
23

34
import sharedData from './shared-lib.js'
45

56
export default async function JSPage () {
6-
return html`
7-
<p>
8-
You can keep loose assets basically anywhere in the <pre>src</pre> directory.
9-
If they are css or js files, they get included into the built website into any of the
10-
client bundle they are imported into.
11-
</p>
12-
<p>
13-
This page demonstrates that with the shared-lib.js and local-import.css files
14-
that get imported into the page.js, client.js and style.css files for this page.
15-
</p>
16-
<p>${sharedData.shared}</p>
17-
`
7+
return render(html`
8+
<div>
9+
<p>
10+
You can keep loose assets basically anywhere in the <pre>src</pre> directory.
11+
If they are css or js files, they get included into the built website into any of the
12+
client bundle they are imported into.
13+
</p>
14+
<p>
15+
This page demonstrates that with the shared-lib.js and local-import.css files
16+
that get imported into the page.js, client.js and style.css files for this page.
17+
</p>
18+
<p>${sharedData.shared}</p>
19+
</div>
20+
`)
1821
}
1922

2023
export const vars = {

‎examples/basic/src/js-page/page.js‎

Lines changed: 56 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,71 @@
1-
import { html } from 'uhtml-isomorphic'
1+
import { html } from 'htm/preact'
2+
import { render } from 'preact-render-to-string'
23

34
export default async function JSPage ({
45
vars: {
56
siteName,
67
title,
78
}
89
}) {
9-
return html`
10-
<p>The js page is the only page type that can render the body with the set variables.</p>
10+
return render(html`
11+
<div class="js-page-example">
12+
<h1>JavaScript Page Example</h1>
13+
14+
<section class="explanation">
15+
<h2>What is a JavaScript Page?</h2>
16+
<p>
17+
The JavaScript page type is the most powerful and flexible option in DOMStack.
18+
It allows you to:
19+
</p>
20+
<ul>
21+
<li>Access and use variables directly in your rendering logic</li>
22+
<li>Generate dynamic content based on data or conditions</li>
23+
<li>Use component-based architecture with Preact or other libraries</li>
24+
<li>Return either HTML strings or component objects</li>
25+
</ul>
26+
</section>
1127
12-
<p>
13-
All you have to do is export a default function (async or sync) that returns a string, or any
14-
type that your layout can handle.
15-
In this case, we are using <a href="https://ghub.io/uhtml-isomorphic"><pre>uhtml-isomorphic</pre></a>.
16-
</p>
28+
<section class="implementation">
29+
<h2>How to Implement</h2>
30+
<p>
31+
Export a default function (async or sync) that returns a string or any
32+
type that your layout can handle. In this example, we're using
33+
<a href="https://github.com/developit/htm"><code>htm/preact</code></a> for JSX-like syntax.
34+
</p>
35+
<div class="code-example">
36+
<pre><code>export default async function MyPage({ vars }) {
37+
return render(html\`<div>Content here</div>\`)
38+
}</code></pre>
39+
</div>
40+
</section>
1741
18-
<p>Here we access the <pre>siteName</pre> and <pre>title</pre> variables inside the page</p>
42+
<section class="variables-demo">
43+
<h2>Using Variables</h2>
44+
<p>Here we access the <code>siteName</code> and <code>title</code> variables inside the page:</p>
45+
<div class="variable-display">
46+
<div><strong>Site Name:</strong> ${siteName}</div>
47+
<div><strong>Page Title:</strong> ${title}</div>
48+
</div>
49+
</section>
1950
20-
<p>${siteName}</p>
21-
<p>${title}</p>
51+
<section class="additional-features">
52+
<h2>Additional Features</h2>
53+
<p>JavaScript pages support:</p>
54+
<ul>
55+
<li>Page-scoped <code>client.js</code> for browser interactions</li>
56+
<li>Page-scoped <code>style.css</code> for component styling</li>
57+
<li>Page-specific variables via <code>export const vars</code></li>
58+
<li>Async data fetching before rendering</li>
59+
</ul>
60+
</section>
2261
23-
<p>JS pages can also have a page scoped <pre>client.js</pre> and <pre>style.css</pre>. It
24-
is an incredibly flexible page type.
25-
</p>
26-
`
62+
<a href="../" class="back-link">← Back to Home</a>
63+
</div>
64+
`)
2765
}
2866

67+
// Define page-specific variables
2968
export const vars = {
30-
title: 'JS Page',
69+
title: 'JavaScript Page Example',
70+
description: 'Learn how to use JavaScript pages in DOMStack for dynamic content generation'
3171
}

‎examples/basic/src/js-page/style.css‎

Lines changed: 73 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,74 @@
1-
.js-page-class {
2-
background: purple;
1+
.js-page-example {
2+
max-width: 800px;
3+
margin: 0 auto;
4+
padding: 1rem;
5+
font-family: system-ui, -apple-system, sans-serif;
6+
}
7+
8+
.js-page-example h1 {
9+
color: #333;
10+
border-bottom: 2px solid #6200ee;
11+
padding-bottom: 0.5rem;
12+
}
13+
14+
.js-page-example section {
15+
margin-bottom: 2rem;
16+
padding: 1.5rem;
17+
border-radius: 8px;
18+
background-color: #f9f9f9;
19+
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
20+
}
21+
22+
.js-page-example h2 {
23+
color: #6200ee;
24+
margin-top: 0;
25+
margin-bottom: 1rem;
26+
}
27+
28+
.js-page-example .code-example {
29+
background-color: #272822;
30+
color: #f8f8f2;
31+
padding: 1rem;
32+
border-radius: 4px;
33+
overflow-x: auto;
34+
}
35+
36+
.js-page-example .code-example pre {
37+
margin: 0;
38+
}
39+
40+
.js-page-example code {
41+
background-color: #eee;
42+
padding: 0.2rem 0.4rem;
43+
border-radius: 3px;
44+
font-family: monospace;
45+
font-size: 0.9em;
46+
}
47+
48+
.js-page-example .code-example code {
49+
background-color: transparent;
50+
padding: 0;
51+
}
52+
53+
.js-page-example .variable-display {
54+
background-color: #fff;
55+
border: 1px solid #ddd;
56+
padding: 1rem;
57+
border-radius: 4px;
58+
margin-top: 1rem;
59+
}
60+
61+
.js-page-example .back-link {
62+
display: inline-block;
63+
margin-top: 1rem;
64+
padding: 0.5rem 1rem;
65+
background-color: #6200ee;
66+
color: white;
67+
text-decoration: none;
68+
border-radius: 4px;
69+
transition: background-color 0.2s;
70+
}
71+
72+
.js-page-example .back-link:hover {
73+
background-color: #3700b3;
374
}

‎examples/basic/src/layouts/child.layout.js‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,23 @@
1-
import { html } from 'uhtml-isomorphic'
1+
import { html } from 'htm/preact'
2+
import { render } from 'preact-render-to-string'
23

34
import defaultRootLayout from './root.layout.js'
45

56
export default function articleLayout (args) {
67
const { children, ...rest } = args
7-
const wrappedChildren = html`
8+
const wrappedChildren = render(html`
89
<article class="bc-article h-entry" itemscope itemtype="http://schema.org/NewsArticle">
910
1011
<h1>${rest.vars.title}</h1>
1112
1213
<section class="e-content" itemprop="articleBody">
1314
${typeof children === 'string'
14-
? html([children])
15-
: children /* Support both uhtml and string children. Optional. */
15+
? html`<div dangerouslySetInnerHTML=${{ __html: children }}></div>`
16+
: children /* Support both preact and string children */
1617
}
1718
</section>
1819
</article>
19-
`
20+
`)
2021

2122
return defaultRootLayout({ children: wrappedChildren, ...rest })
2223
}

0 commit comments

Comments
 (0)