Skip to content

Commit ff1afa1

Browse files
markmalsmarkmals
committed
Update READMEs and licenses
1 parent 476a5f7 commit ff1afa1

File tree

7 files changed

+491
-9
lines changed

7 files changed

+491
-9
lines changed

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025-present, Mark Malstrom
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# @webstd-ui/router
2+
3+
A framework-agnostic client-side router built on top of `@remix-run/fetch-router` and `@remix-run/events`. This monorepo contains the core router package and example applications demonstrating its usage.
4+
5+
## Overview
6+
7+
This project provides a small, generic client-side router that can be integrated into any web application. It leverages the proven routing architecture from Remix/React Router while remaining independent of any specific UI framework.
8+
9+
## Repository Structure
10+
11+
```
12+
router/
13+
├── packages/
14+
│ └── router/ # Core router package (@webstd-ui/router)
15+
└── examples/
16+
├── blog/ # Blog application example
17+
├── contacts/ # Contact management example (SPA)
18+
└── tasks/ # Task management example
19+
```
20+
21+
## Getting Started
22+
23+
### Prerequisites
24+
25+
This project uses [Mise](https://mise.jdx.dev/) for task automation and dependency management.
26+
27+
1. [Install Mise](https://mise.jdx.dev/installing-mise.html)
28+
2. Install dependencies:
29+
```sh
30+
mise install
31+
```
32+
33+
### Development
34+
35+
The repository uses pnpm workspaces. To work on the router package:
36+
37+
```sh
38+
# Install all dependencies
39+
pnpm install
40+
41+
# Build the router package
42+
cd packages/router
43+
mise run :dev
44+
```
45+
46+
### Running Examples
47+
48+
Each example application can be run independently:
49+
50+
```sh
51+
# Run the contacts example
52+
cd examples/contacts
53+
mise run :dev
54+
55+
# Run the blog example
56+
cd examples/blog
57+
mise run :dev
58+
59+
# Run the tasks example
60+
cd examples/tasks
61+
mise run :dev
62+
```
63+
64+
## Packages
65+
66+
### [@webstd-ui/router](./packages/router)
67+
68+
The core router package that provides framework-agnostic client-side routing capabilities.
69+
70+
**Features:**
71+
- Framework-agnostic design
72+
- Built on `@remix-run/fetch-router`
73+
- Event-driven architecture using `@remix-run/events`
74+
- TypeScript support
75+
- ESM module format
76+
77+
## Examples
78+
79+
### [Contacts](./examples/contacts)
80+
81+
A contact management application demonstrating basic routing, data loading, and navigation. Based on the React Router address book tutorial.
82+
83+
### [Blog](./examples/blog)
84+
85+
A blog application example showcasing the router in a content-focused context.
86+
87+
### [Tasks](./examples/tasks)
88+
89+
A task management application demonstrating the router with state management and async operations.
90+
91+
## Technology Stack
92+
93+
- **Build Tool:** tsdown (router), Vite (examples)
94+
- **Package Manager:** pnpm
95+
- **Language:** TypeScript
96+
97+
## Contributing
98+
99+
This is a monorepo managed with pnpm workspaces. When making changes:
100+
101+
1. Make changes to the router package in `packages/router/`
102+
2. Test your changes in one or more example applications
103+
3. Ensure all TypeScript types are properly exported
104+
105+
## License
106+
107+
[MIT](LICENSE)

‎examples/blog/README.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Blog Example
2+
3+
A simple blog application demonstrating the capabilities of [@webstd-ui/router](../../packages/router) with a content-focused use case. This example shows how to build a blog with post creation, listing, and viewing functionality.
4+
5+
## Features
6+
7+
- **Post Management**: Create and view blog posts
8+
- **Resource Routes**: Uses `resources()` helper for RESTful route structure
9+
- **Post Listing**: Browse all blog posts
10+
- **Individual Post Views**: View individual blog posts by ID
11+
- **Form Handling**: Create new posts via form submission
12+
- **AppStorage**: Demonstrates per-request storage for data persistence
13+
- **Type-Safe Routing**: Full TypeScript support with route type inference
14+
- **Interactive Components**: Includes a counter component for client-side interactivity
15+
16+
## Technology Stack
17+
18+
- **Router**: [@webstd-ui/router](../../packages/router)
19+
- **UI Framework**: [@remix-run/dom](https://www.npmjs.com/package/@remix-run/dom)
20+
- **Build Tool**: Vite
21+
- **Language**: TypeScript
22+
23+
## Getting Started
24+
25+
### Prerequisites
26+
27+
- [Mise](https://mise.jdx.dev/) for task automation
28+
29+
### Installation & Running
30+
31+
1. Install dependencies:
32+
```sh
33+
mise install
34+
```
35+
36+
2. Start the development server:
37+
```sh
38+
mise run :dev
39+
```
40+
41+
3. Open your browser to the URL shown in the terminal (typically `http://localhost:5173`)
42+
43+
## Project Structure
44+
45+
```
46+
src/
47+
├── components/ # Reusable UI components (e.g., Counter)
48+
├── lib/ # Utilities and data management (posts.ts)
49+
├── handlers.tsx # Route handlers for all pages
50+
├── routes.ts # Route definitions using resources()
51+
├── App.tsx # Main application component
52+
└── main.tsx # Application entry point
53+
```
54+
55+
## Routes
56+
57+
| Path | Method | Handler | Description |
58+
|------|--------|---------|-------------|
59+
| `/` | GET | `index` | Home page with counter |
60+
| `/about` | GET | `about` | About page |
61+
| `/blog` | GET | `blog.index` | List all blog posts |
62+
| `/blog/new` | GET | `blog.new` | New post form |
63+
| `/blog` | POST | `blog.create` | Create new post |
64+
| `/blog/:id` | GET | `blog.show` | View individual post |
65+
66+
## Learn More
67+
68+
- [Router Documentation](../../packages/router)
69+
- [@remix-run/fetch-router Resources](https://www.npmjs.com/package/@remix-run/fetch-router) - Learn about resource routes
70+
- [@remix-run/dom](https://www.npmjs.com/package/@remix-run/dom)

‎examples/contacts/README.md‎

Lines changed: 54 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,58 @@
1-
# Remix 3 Contacts (SPA)
1+
# Contacts Example
22

3-
A version of the [React Router address book tutorial](https://reactrouter.com/tutorials/address-book) using my Remix 3 [client-side router](/packages/remix-client-router/router/router.ts) for `@remix-run/dom`, utilizing `@remix-run/events` and `@remix-run/fetch-router`.
3+
A contact management application demonstrating the capabilities of [@webstd-ui/router](../../packages/router). This example is based on the [React Router address book tutorial](https://reactrouter.com/tutorials/address-book), adapted to use our framework-agnostic client-side router.
44

5-
To start the development server, [install Mise](https://mise.jdx.dev/installing-mise.html) and run:
5+
## Features
6+
7+
- **Contact Management**: Create, read, update, and delete contacts
8+
- **Search Functionality**: Real-time contact search with URL integration
9+
- **Favorite Contacts**: Mark contacts as favorites
10+
- **Form Handling**: Demonstrates POST/PUT/DELETE form submissions
11+
- **Navigation States**: Loading indicators and optimistic UI
12+
- **URL-Driven State**: All state reflected in the URL
13+
- **File-Based Routing**: Organized route structure in `src/routes/`
14+
15+
## Technology Stack
16+
17+
- **Router**: [@webstd-ui/router](../../packages/router)
18+
- **UI Framework**: [@remix-run/dom](https://www.npmjs.com/package/@remix-run/dom)
19+
- **Build Tool**: Vite
20+
- **Language**: TypeScript
21+
22+
## Getting Started
23+
24+
### Prerequisites
25+
26+
- [Mise](https://mise.jdx.dev/) for task automation
27+
28+
### Installation & Running
29+
30+
1. Install dependencies:
31+
```sh
32+
mise install
33+
```
34+
35+
2. Start the development server:
36+
```sh
37+
mise run :dev
38+
```
39+
40+
3. Open your browser to the URL shown in the terminal (typically `http://localhost:5173`)
41+
42+
## Project Structure
643

7-
```sh
8-
mise install
9-
mise run :dev
1044
```
45+
src/
46+
├── components/ # Reusable UI components
47+
├── lib/ # Utilities and data storage
48+
├── routes/ # Route handlers for different pages
49+
├── app.tsx # Main application component
50+
├── main.tsx # Application entry point
51+
└── index.css # Global styles
52+
```
53+
54+
## Learn More
55+
56+
- [Router Documentation](../../packages/router)
57+
- [React Router Tutorial](https://reactrouter.com/tutorials/address-book) (original inspiration)
58+
- [@remix-run/dom](https://www.npmjs.com/package/@remix-run/dom)

‎examples/tasks/README.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Tasks Example
2+
3+
A task management application demonstrating the capabilities of [@webstd-ui/router](../../packages/router) with async operations, redirects, and optimistic UI patterns. This example shows how to build a task manager with create, view, and delete functionality.
4+
5+
## Features
6+
7+
- **Task Management**: Create, view, and delete tasks
8+
- **Resource Routes**: Uses `resources()` helper for RESTful routing with custom destroy route
9+
- **Async Operations**: Demonstrates loading states with simulated delays
10+
- **Redirects**: Server-style redirects after mutations
11+
- **Form Handling**: Create and delete tasks via form submissions
12+
- **Navigation States**: Loading indicators during async operations
13+
- **Type-Safe Routing**: Full TypeScript support with route type inference
14+
- **Component-Based UI**: Reusable task components
15+
16+
## Technology Stack
17+
18+
- **Router**: [@webstd-ui/router](../../packages/router)
19+
- **UI Framework**: [@remix-run/dom](https://www.npmjs.com/package/@remix-run/dom)
20+
- **Build Tool**: Vite
21+
- **Language**: TypeScript
22+
- **Async Utilities**: [@std/async](https://jsr.io/@std/async) for delays
23+
24+
## Getting Started
25+
26+
### Prerequisites
27+
28+
- [Mise](https://mise.jdx.dev/) for task automation
29+
30+
### Installation & Running
31+
32+
1. Install dependencies:
33+
```sh
34+
mise install
35+
```
36+
37+
2. Start the development server:
38+
```sh
39+
mise run :dev
40+
```
41+
42+
3. Open your browser to the URL shown in the terminal (typically `http://localhost:5173`)
43+
44+
## Project Structure
45+
46+
```
47+
src/
48+
├── components/ # Reusable UI components
49+
│ ├── NewTask.tsx # New task creation form
50+
│ └── TaskItem.tsx # Individual task component
51+
├── lib/ # Utilities and data management
52+
│ └── task-data.ts # Task data storage
53+
├── handlers.tsx # Route handlers for all pages
54+
├── routes.ts # Route definitions
55+
├── app.tsx # Main application component
56+
└── main.tsx # Application entry point
57+
```
58+
59+
## Routes
60+
61+
| Path | Method | Handler | Description |
62+
|------|--------|---------|-------------|
63+
| `/` | GET | `index` | Redirects to first task |
64+
| `/task/new` | GET | `tasks.new` | New task form |
65+
| `/task` | POST | `tasks.create` | Create new task |
66+
| `/task/:id` | GET | `tasks.show` | View task details |
67+
| `/task/destroy/:id` | POST | `tasks.destroy` | Delete task |
68+
69+
## Testing Loading States
70+
71+
This example includes artificial delays (800ms) in async handlers to make loading states visible during development. This helps test:
72+
73+
- Loading indicators during navigation
74+
- Pending states in the UI
75+
- Navigation state transitions
76+
- User experience during async operations
77+
78+
## Learn More
79+
80+
- [Router Documentation](../../packages/router)
81+
- [@remix-run/fetch-router Resources](https://www.npmjs.com/package/@remix-run/fetch-router) - Learn about resource routes
82+
- [@remix-run/dom](https://www.npmjs.com/package/@remix-run/dom)
83+
84+
## License
85+
86+
See the root repository for license information.

‎packages/router/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025-present, Mark Malstrom
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)