diff --git a/README.md b/README.md index 568dd24..8decb26 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,49 @@ +# CommaFeed Podcasts +

- + CommaFeed Podcasts logo

-# CommaFeed Podcasts -**Experimantal/WIP** PWA podcast app. Idea is to use [CommaFeed](https://github.com/Athou/commafeed) as a backend. +> **Experimental / WIP** – A progressive web application for podcast consumption, powered by [CommaFeed](https://github.com/Athou/commafeed) as the backend. +## Links - [Plan](./changelog/PLAN.md), [Task](./changelog/TASK.md) -- [Building scripts](./bs/README.md) - [![Built with open-wc recommendations](https://img.shields.io/badge/built%20with-open--wc-blue.svg)](https://github.com/open-wc) - [What is Lit? – Lit](https://lit.dev/docs/) - [@lit-labs/router - npm](https://www.npmjs.com/package/@lit-labs/router) - [lit-translate - npm](https://www.npmjs.com/package/lit-translate) + +## Features +- **PWA** support with offline caching. +- Client‑side routing via a lightweight router. +- Dynamic page rendering based on URL parameters (e.g., `/episodes/:id`). +- Built with Lit, TypeScript and Open‑WC tooling. + +## Getting Started +```bash +npm install +bs/start +``` + +## Build Scripts +See [bs/README.md](./bs/README.md) for available build and deployment scripts. + +## Testing +Tests are written with `@open-wc/testing` (Mocha) / Web Test Runner and follow the `*.test.ts` convention. Run all tests via: +```bash +bs/test +``` + +## Documentation +- Overall development plan: [docs/dev/PLAN.md](./docs/dev/PLAN.md) +- Overall task board: [docs/dev/TASK.md](./docs/dev/TASK.md) +- App source overview: [src/README.md](./src/README.md) + +## Contributing +TBD + + +## License +[MIT](LICENSE) diff --git a/examples/auth.js b/docs/dev/examples/auth.js similarity index 100% rename from examples/auth.js rename to docs/dev/examples/auth.js diff --git a/examples/data/podcasts.opml b/docs/dev/examples/data/podcasts.opml similarity index 100% rename from examples/data/podcasts.opml rename to docs/dev/examples/data/podcasts.opml diff --git a/examples/playground.js b/docs/dev/examples/playground.js similarity index 100% rename from examples/playground.js rename to docs/dev/examples/playground.js diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..df3b962 --- /dev/null +++ b/src/README.md @@ -0,0 +1,63 @@ +# CommaFeed Podcasts – Web Component/App + +This repository contains the **source code** for a small progressive web application built with Lit and Open‑WC recommendations. + +## High‑level structure + +### Pages (`app-*`, `index.ts`, `*.css.ts`, `*.test.ts`) +Folder naming (`app-name`) corresponds to custom element name (``) and endpoint (`/name`). +Dynamic parameters are supported using `:` in the name (`app-:id`/``/`/episodes/:id`). + +Each folder follows a consistent pattern: + +1. **Page component file** – `index.ts` contains the Lit component definition. +1. **Styles** – `*.css.ts` holds the scoped CSS for that component. +1. **Tests** – optional `*.test.ts` hoding overall app router tests (probably integration test). +1. **Routing helper** – optional `routes.ts` +1. **README** – describes the module’s purpose and key files. + +Below is an overview of the current pages: + +- [``](./app-home) +- [``](./app-episodes) + +*(More feature modules can be added in the future following the same pattern.)* + +### Components (`src/components/`, `*.css.ts`, `*.test.ts`) +The `components/` folder contains re‐usable UI building blocks shared across feature modules. + +- file naming: `c-name` (files `c-name.ts` and `c-name.css.ts`) +- folder follows the same pattern as pages (except no routes) + +### Core (`src/core/`, `*.test.ts`) +The `core/` folder contains routing and translation infrastructure, and shared utilities. + +The `*.test.ts` files are used for unit tests for given core file. + +### Assets (`src/assets/`) +The `assets/` folder contains static files (logos, icons, etc.) that are imported by components. + +Use `new URL('/assets/logo.png', import.meta.url)` to get the URL of a static file. + +## How routing works +The application uses a lightweight client‑side router (see `core/routes.ts`). +Route definitions look like: + +```ts +import { route } from "@/core/route.js"; +import { html } from "lit"; + +export const path = "/episodes/" as const; +export const routes = route( + { + path: "/episodes/:id/", + async enter() { + await import("./index.js"); + return true; + }, + render({ id }){ + return html``; + }, + }, +); +``` diff --git a/src/app-episodes/README.md b/src/app-episodes/README.md new file mode 100644 index 0000000..a1af1e9 --- /dev/null +++ b/src/app-episodes/README.md @@ -0,0 +1,8 @@ +# `` + +Displays a list of podcast episodes. + +## Subroutes + +### `` +The component is routed to via `/episodes/:id?` where `:id` is an optional episode identifier used to show a specific episode. diff --git a/src/app-episodes/:id/index.css.ts b/src/app-episodes/app-:id/index.css.ts similarity index 100% rename from src/app-episodes/:id/index.css.ts rename to src/app-episodes/app-:id/index.css.ts diff --git a/src/app-episodes/:id/index.ts b/src/app-episodes/app-:id/index.ts similarity index 100% rename from src/app-episodes/:id/index.ts rename to src/app-episodes/app-:id/index.ts diff --git a/src/app-episodes/:id/routes.ts b/src/app-episodes/app-:id/routes.ts similarity index 100% rename from src/app-episodes/:id/routes.ts rename to src/app-episodes/app-:id/routes.ts diff --git a/src/app-episodes/routes.ts b/src/app-episodes/routes.ts index 8368ab8..7432df1 100644 --- a/src/app-episodes/routes.ts +++ b/src/app-episodes/routes.ts @@ -1,5 +1,5 @@ import { route } from "@/core/route.js"; -import { routes as routeEpisode } from "./:id/routes.js"; +import { routes as routeEpisode } from "./app-:id/routes.js"; import { html } from "lit"; export const path = "/episodes/" as const; diff --git a/src/app-home/README.md b/src/app-home/README.md new file mode 100644 index 0000000..5c915a3 --- /dev/null +++ b/src/app-home/README.md @@ -0,0 +1,7 @@ +# app‑home + +This feature module implements the home page of the podcast application and handles navigation logic. + +## Files +- `index.ts` – Lit component that renders the landing view. +- `router.js` (if any) – Routing helpers for navigating between pages. diff --git a/src/index.ts b/src/index.ts index 1d32119..1b73137 100644 --- a/src/index.ts +++ b/src/index.ts @@ -23,13 +23,14 @@ export class AppCfpodcasts extends LitElement {