@masmarino/gabarit 1.2.2 → 1.4.0

package/README.md

@@ -135,6 +135,12 @@ but plain, without the layout the directive provides.
 | `MenuTrigger`  | `[gbtMenuTrigger]`   | `gbt-menu`: a custom trigger element instead of the default button.  |
 | `StatTileLink` | `a[gbtStatTileLink]` | `gbt-stat-tile`: the router-agnostic link, its text is the label.    |
 
+## Documentation reader
+
+`@masmarino/gabarit/docs` is a reader for documentation written in Markdown and shipped with an app (navigation,
+search, outline, neighbours), with `gbt-markdown-view` for Markdown anywhere else. It is a separate entry point
+because it needs `@angular/router`, `marked` and `dompurify`; see [its README](docs/README.md).
+
 ## Primitives and pipes
 
 Pure functions exported from `@masmarino/gabarit`, usable in any TypeScript
@@ -324,6 +330,29 @@ Other tokens live on `:root` without being colors — border radii
 (`--site-border-radius*`), shadows (`--site-shadow-*`), transition
 durations (`--site-transition-*`), the monospace stack `--gbt-font-mono` — overridable the same way.
 
+### Theming hooks
+
+A few more tokens are not set on `:root`: each component falls back to the
+value in the last column, resolved where it is used, so an app that leaves
+them alone looks the same. Set one to take that part of the look in hand.
+
+| Token                                           | Used by                                                                   | Fallback                                |
+| ----------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------- |
+| `--gbt-focus-ring`                              | Every focus outline                                                       | `var(--primary)`                        |
+| `--gbt-font-display`                            | Page titles, stat tile values, empty state, auth panel and modal headings | `inherit`                               |
+| `--gbt-radius-badge`                            | Badges, card and tab counts                                               | `999px` (a pill)                        |
+| `--gbt-radius-chip`                             | Mono badges, inline code in a list row, search bar keys                   | `6px`                                   |
+| `--gbt-radius-menu`                             | Select and autocomplete panels, menu items, search results                | `8px`                                   |
+| `--gbt-radius-tile`                             | Icon marker tiles, job graph nodes, avatar group overflow, TOTP QR code   | `8px` (`12px` for the QR)               |
+| `--gbt-radius-search`                           | The search bar field                                                      | `16px`                                  |
+| `--gbt-nav-active-bg` / `--gbt-nav-active-text` | The current page in the app shell navigation                              | `--primary` / its text                  |
+| `--gbt-nav-active-mark`                         | A 2px rule on the start edge of the current page link                     | `transparent`                           |
+| `--gbt-shell-border`                            | The app shell's navigation and header edges                               | `var(--border-color)`                   |
+| `--gbt-shell-header-bg`                         | The app shell's header                                                    | `transparent`                           |
+| `--gbt-shell-content-padding`                   | The app shell's main content area                                         | `1rem`                                  |
+| `--gbt-auth-panel-backdrop`                     | The page behind the auth panels (login, register…)                        | a soft `--primary` glow on `--bg-panel` |
+| `--gbt-auth-panel-radius`                       | The auth panel card                                                       | `12px`                                  |
+
 Overriding a token after the import:
 
 ```scss

package/docs/README.md

@@ -0,0 +1,102 @@
+# @masmarino/gabarit/docs
+
+A reader for documentation written in Markdown and shipped with an app: a navigation with search on the left, the page
+with its breadcrumb and neighbours, and its outline on a wide screen. It is its own entry point because it needs
+`@angular/router`, [marked](https://marked.js.org) and [DOMPurify](https://github.com/cure53/DOMPurify), which the rest
+of Gabarit does not; install them next to Gabarit:
+
+```sh
+npm install marked dompurify
+```
+
+## The pages
+
+The app serves the documentation as static files under a root (`/docs` by default), for instance from its `public/`
+folder:
+
+```
+public/docs/
+  index.json                # the sections and their pages, in reading order
+  demarrer/presentation.md  # one Markdown file per page: <section>/<page>.md
+  demarrer/prise-en-main.md
+```
+
+```json
+{
+  "sections": [
+    {
+      "slug": "demarrer",
+      "title": "Démarrer",
+      "pages": [
+        { "slug": "presentation", "title": "Présentation", "description": "What the app does." }
+      ]
+    }
+  ]
+}
+```
+
+The index and each page are fetched once and kept. A page links to another with a root-relative link
+(`[Configuration](/docs/installation/configuration#variables)`): the reader follows it through the router. A quote
+whose first word is a bold callout key becomes a callout: `> **Note** …` (and `> **Warning** …` by default).
+
+## Wiring
+
+```ts
+// app.routes.ts
+import { docsRoutes } from '@masmarino/gabarit/docs'
+
+export const routes: Routes = [
+  {
+    path: 'docs',
+    // The app's own page around the reader (its layout, its header), or DocsPage itself.
+    children: docsRoutes(() => import('./docs/docs-route').then((m) => m.DocsRoute)),
+  },
+]
+```
+
+```ts
+// docs-route.ts: the reader inside the app's layout
+@Component({
+  imports: [AppLayout, DocsPage],
+  providers: [
+    provideDocs({ callouts: { note: 'note', attention: 'warning' } }),
+    provideDocsLabels(FRENCH_DOCS_LABELS),
+    { provide: DOCS_TITLE, useFactory: () => (title: string) => inject(Title).setTitle(title) },
+  ],
+  template: `<app-layout><gbt-docs-page /></app-layout>`,
+})
+export class DocsRoute {}
+```
+
+`docsRoutes()` sends the root to the first page, mounts `<section>/<page>`, and gives any other address the reader's
+own "not found". `gbt-docs-page` reads the section and the page from the route.
+
+## Providers
+
+| Token                 | Role                                                                                                   |
+| --------------------- | ------------------------------------------------------------------------------------------------------ |
+| `provideDocs(config)` | `root` (`/docs`) and the `callouts` keys (`note`, `warning`).                                          |
+| `provideDocsLabels()` | The reader's strings, over the English defaults (`DEFAULT_DOCS_LABELS`).                               |
+| `DOCS_TITLE`          | A function given the shown page's title (or "not found", or the reader's name while loading). Optional. |
+
+## Pieces
+
+| Piece                  | Role                                                                                                     |
+| ---------------------- | -------------------------------------------------------------------------------------------------------- |
+| `gbt-docs-page`        | The whole reader for the routed page: navigation, page, neighbours, outline, loading, failure, not found. |
+| `gbt-docs-nav`         | The sections and their pages, with the search; folds behind a toggle on a narrow layout.                  |
+| `gbt-docs-search`      | A search over every page, in the browser, loaded on first focus.                                          |
+| `gbt-markdown-view`    | Markdown to sanitised HTML, with the reading styles; usable on its own (a README, release notes).          |
+| `gbt-markdown-outline` | The "On this page" panel for the headings a `gbt-markdown-view` emits.                                    |
+
+## Security
+
+The Markdown is sanitised with a dedicated DOMPurify instance, stricter than its defaults: no `<style>`, no `style`
+attribute, no forms or buttons, no IDREFs or `tabindex`, ids and names prefixed with `user-content-`, only the
+`language-*` classes of code blocks kept, task-list checkboxes disabled, remote images lazy and without a referrer.
+
+## Accessibility
+
+Every heading gets a stable id; the outline and in-page links move the focus to the heading they reach. Code blocks
+and tables that scroll sideways take the focus and are named. Task-list checkboxes are named by their item. A new page
+moves the focus to its title, except on the first visit.