@masmarino/gabarit 1.4.0 → 2.0.0

package/src/lib/tokens/_utilities.scss

@@ -1,3 +1,5 @@
+@use 'a11y';
+
 .gbt-form-error {
   margin: 0 0 0.75rem;
   font-size: 0.875rem;
@@ -85,8 +87,7 @@
   }
 }
 
-// Global, so it reaches the links the app projects: each piece of the rail keeps its height, and a rail taller than the
-// window scrolls rather than squeezing its links together.
+// Global to reach the projected links: a rail taller than the window scrolls instead of squeezing them.
 .gbt-app-shell__nav > * {
   flex-shrink: 0;
 }
@@ -101,6 +102,7 @@
   border-radius: var(--site-border-radius-sm);
   color: var(--text-secondary);
   font-size: 0.875rem;
+  font-weight: 500;
   text-decoration: none;
   overflow: hidden;
   white-space: nowrap;
@@ -118,16 +120,15 @@
   }
 
   &:focus-visible {
-    outline: 2px solid var(--gbt-focus-ring, var(--primary));
-    outline-offset: -2px;
+    @include a11y.focus-ring(-2px);
   }
 
   // An app can tone the current page down to a tint with a mark on its edge (--gbt-nav-active-*).
   &[aria-current] {
-    background: var(--gbt-nav-active-bg, var(--primary));
-    color: var(--gbt-nav-active-text, var(--text-on-primary));
+    background: var(--gbt-nav-active-bg, color-mix(in srgb, var(--text-primary) 9%, transparent));
+    color: var(--gbt-nav-active-text, var(--text-primary));
     font-weight: 600;
-    box-shadow: inset 2px 0 0 var(--gbt-nav-active-mark, transparent);
+    box-shadow: inset 2px 0 0 var(--gbt-nav-active-mark, var(--accent));
   }
 }
 
@@ -223,7 +224,7 @@
   gap: 0.5rem;
   width: 100%;
   padding: 8px 10px;
-  border-radius: var(--gbt-radius-menu, 8px);
+  border-radius: var(--gbt-radius-menu, 4px);
   color: var(--text-primary);
   font-size: 14px;
   text-align: left;
@@ -238,8 +239,7 @@
   }
 
   &:focus-visible {
-    outline: 2px solid var(--gbt-focus-ring, var(--primary));
-    outline-offset: -2px;
+    @include a11y.focus-ring(-2px);
   }
 }
 

package/src/lib/tokens/index.scss

@@ -1,3 +1,6 @@
 @forward 'palette';
 @forward 'semantic';
+@forward 'themes';
+@forward 'a11y';
+@forward 'base';
 @forward 'utilities';

package/types/masmarino-gabarit-docs.d.ts

@@ -5,23 +5,16 @@ import { CanActivateFn, Routes } from "@angular/router";
 import { SafeHtml } from "@angular/platform-browser";
 import { AutocompleteSearchFn, PanelHeadingLevel } from "@masmarino/gabarit";
 interface DocsConfig {
-  /**
-   * Where the pages are, both as files and as the reader's routes: `<root>/index.json`, `<root>/<section>/<page>.md`,
-   * and the page `<root>/<section>/<page>`. `/docs` by default.
-   */
+  /** Where the files (`<root>/index.json`, `<root>/<section>/<page>.md`) and the routes live. `/docs` by default. */
   root: string;
-  /**
-   * The quotes that become callouts: a quote whose first word, in bold, is one of these keys (`> **Note** …`), drawn
-   * in the tone it maps to. Case does not matter.
-   */
+  /** A quote opening on one of these words in bold (`> **Note** …`) becomes a callout of that tone. Any case. */
   callouts: Readonly<Record<string, 'note' | 'warning'>>;
 }
 export declare const DEFAULT_DOCS_CONFIG: Readonly<DocsConfig>;
 export declare const DOCS_CONFIG: InjectionToken<DocsConfig>;
 /**
- * Where the shown page's title goes, for an app that names its pages somewhere of its own (a header, a breadcrumb):
- * called with the page's title, "not found" or the reader's name while loading. Without it the reader leaves the
- * title alone.
+ * Gets the shown page's title (or "not found", or the reader's name while loading), for an app that shows titles in
+ * its own header. Optional.
  */
 export declare const DOCS_TITLE: InjectionToken<(title: string) => void>;
 export declare function provideDocs(config?: Partial<DocsConfig>): Provider;
@@ -92,10 +85,7 @@ export declare function docsReadingOrder(index: DocsIndex): {
 /** Where `<root>` leads: the first page of the first section, or `null` for an empty index. */
 export declare function firstDocsPage(root: string, index: DocsIndex): string[] | null;
 export declare function locateDocsPage(root: string, index: DocsIndex, section: string | null, page: string | null): DocsLocation | null;
-/**
- * The documentation, shipped as static files under the configured root. The index and each page are fetched once
- * and kept, since they only change with a new version of the app. A failure isn't kept, so it gets retried.
- */
+/** Fetches the index and each page once; they only change with a new app version. Failures aren't cached. */
 export declare class DocsService {
   private readonly http;
   readonly root: string;
@@ -124,10 +114,7 @@ interface DocsSearchHit {
   };
 }
 export declare function searchTokens(query: string): string[];
-/**
- * Title, headings and body text of one page. Heading ids follow `gbt-markdown-view`: `user-content-<slug>` on every
- * h1–h4, and `-2`, `-3`… on a repeated slug in document order.
- */
+/** Title, headings and text of a page. Heading ids must match gbt-markdown-view's (`-2`, `-3` on repeats). */
 export declare function parseDocsPage(markdown: string): {
   headings: {
     id: string;
@@ -136,9 +123,8 @@ export declare function parseDocsPage(markdown: string): {
   body: string;
 };
 /**
- * Search over the whole documentation, in the browser. Nothing is fetched until the first search (or `prepare()`),
- * then every page once, kept by `DocsService`. Every word of the query must appear in the page; a word in the title
- * ranks higher than one in a heading, and a heading higher than the text.
+ * Searches every page in the browser, fetching them on first use. All words must match; title beats heading beats
+ * text.
  */
 export declare class DocsSearchService {
   private docs;
@@ -150,21 +136,11 @@ export declare class DocsSearchService {
   static ɵfac: i0.ɵɵFactoryDeclaration<DocsSearchService, never>;
   static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
-/**
- * The root opens the first page of the index. If the index can't be read or is empty, the reader shows that itself,
- * inside its own layout.
- */
+/** Sends the root to the first page. A broken or empty index is left for the reader to show. */
 export declare const docsHomeGuard: CanActivateFn;
-/**
- * The reader's routes, to mount at the configured root: the root (to the first page), `<section>/<page>`, and any
- * other depth, which gets the reader's own "not found". `page` is the routed component that shows the reader (often
- * the app's own, wrapping `gbt-docs-page` in its layout).
- */
+/** The reader's routes, for the configured root. `page` loads the component that shows it (often the app's). */
 export declare function docsRoutes(page: () => Promise<unknown>): Routes;
-/**
- * The documentation's left column: the search field, then every section with its pages. Only the current section
- * starts open. On a narrow layout the sections fold behind a toggle and the search stays.
- */
+/** The left column: search, then the sections and their pages, only the current one open. */
 export declare class DocsNav {
   index: import("@angular/core").InputSignal<DocsIndex>;
   section: import("@angular/core").InputSignal<string | null>;
@@ -218,18 +194,12 @@ export declare function headingSlug(text: string): string;
 export declare function decodeFragment(rawFragment: string): string;
 /** The element a `#fragment` points at: the plain `id`, else the `user-content-` id or `<a name>` the sanitiser made. */
 export declare function findAnchorTarget(root: HTMLElement, rawFragment: string): HTMLElement | null;
-/**
- * A long code block or a wide table scrolls sideways, which a keyboard can only do once it takes the focus (WCAG
- * 2.1.1): each one becomes a named stop in the tab order. A table keeps its own role and gets only the stop and the
- * name.
- */
+/** A keyboard only scrolls a wide code block or table it has focused (WCAG 2.1.1): each gets a tab stop. */
 export declare function makeScrollableBlocksFocusable(container: HTMLElement, names: {
   codeBlock: string;
   table: string;
 }): void;
-/**
- * A task-list checkbox is named by its item's text, so a screen reader says what is done or still to do.
- */
+/** Names each task-list checkbox after its item, so a screen reader says what's done. */
 export declare function nameTaskCheckboxes(container: HTMLElement): void;
 /**
  * Markdown rendered to sanitised HTML, with the reading styles of the design system: headings, lists, code, tables,
@@ -239,10 +209,7 @@ export declare class MarkdownView {
   content: import("@angular/core").InputSignal<string>;
   /** Levels added to every heading (up to h6), so a `# Title` under the page's own headings keeps the outline. */
   headingOffset: import("@angular/core").InputSignal<number>;
-  /**
-   * Links under this prefix (`/docs` → `/docs/install/configuration#variables`) go through the router instead of
-   * reloading the app. Off by default: a link in a README is left to the browser.
-   */
+  /** Links under this prefix (say `/docs`) go through the router instead of reloading the app. Off by default. */
   routedLinkPrefix: import("@angular/core").InputSignal<string | null>;
   /** The h2–h4 headings, emitted after each render once their ids are in the DOM. */
   outline: import("@angular/core").OutputEmitterRef<MarkdownOutlineEntry[]>;
@@ -252,8 +219,8 @@ export declare class MarkdownView {
   private readonly container;
   constructor();
   /**
-   * In-content `#anchor` links would resolve against `<base href="/">` and load the home page, so a plain left click
-   * scrolls to the target inside this view and focuses it. Modified and middle clicks are left to the browser.
+   * A bare #anchor resolves against <base href="/"> and would load the home page, so a plain click scrolls here
+   * instead. Modified and middle clicks are the browser's.
    */
   protected onClick(event: MouseEvent): void;
   /** The `href` of a clicked in-content link under `routedLinkPrefix`, or `null` when the browser should follow it. */
@@ -292,11 +259,7 @@ type DocsView = {
   location: DocsLocation;
   content: string;
 };
-/**
- * One documentation page (`<root>/<section>/<page>`, read from the route): the navigation, the page with its
- * breadcrumb and neighbours, and on a wide screen the outline beside it. An unknown address gets a "not found" in the
- * same frame.
- */
+/** The routed page with its nav, breadcrumb, neighbours and outline, or a "not found" in the same frame. */
 export declare class DocsPage {
   private readonly docs;
   private readonly route;
@@ -358,10 +321,7 @@ export declare class DocsSearch {
 }
 /** An outline is worth a panel from two headings on: one heading is no table of contents. */
 export declare function hasOutline(entries: readonly MarkdownOutlineEntry[]): boolean;
-/**
- * The "On this page" panel beside rendered Markdown. Each entry links to `#user-content-…` on the current URL; the
- * router does no anchor scrolling, so the click scrolls to the heading and focuses it itself.
- */
+/** "On this page" for rendered Markdown. The router doesn't scroll to anchors, so a click does it here. */
 export declare class MarkdownOutline {
   entries: import("@angular/core").InputSignal<MarkdownOutlineEntry[]>;
   headingLevel: import("@angular/core").InputSignal<PanelHeadingLevel>;

package/types/masmarino-gabarit.d.ts

@@ -2,7 +2,7 @@ import * as i0 from "@angular/core";
 import { ElementRef, InjectionToken, Injector, OnDestroy, PipeTransform, Provider, Signal, TemplateRef, WritableSignal } from "@angular/core";
 import { ControlValueAccessor, FormControl } from "@angular/forms";
 import { Observable } from "rxjs";
-export declare const GABARIT_VERSION = "1.4.0";
+export declare const GABARIT_VERSION = "2.0.0";
 export declare class Icon {
   private readonly sanitizer;
   private readonly registry;
@@ -1064,10 +1064,7 @@ type InputSize = 'md' | 'sm';
 type InputInputmode = 'none' | 'text' | 'tel' | 'url' | 'email' | 'numeric' | 'decimal' | 'search';
 type InputAutocapitalize = 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters';
 type InputEnterkeyhint = 'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send';
-/**
- * The field as the combobox of a list of suggestions it does not render itself: the caller owns the
- * listbox, the keys (`(keydown)` on the host) and the active option.
- */
+/** Makes the field the combobox of a suggestion list the caller renders, with its keys and active option. */
 interface InputCombobox {
   /** Whether the listbox is shown. */
   expanded: boolean;
@@ -4841,10 +4838,7 @@ export declare class ListCard {
   emptyMessage: import("@angular/core").InputSignal<string>;
   emptyIllustration: import("@angular/core").InputSignal<EmptyStateIllustration | null>;
   emptyIcon: import("@angular/core").InputSignal<string | null>;
-  /**
-   * What sits above the box: the projected `[list-card-header]` (ready), its placeholder (loading,
-   * unless `skeletonHeader` is off), or nothing (failed, empty).
-   */
+  /** The projected header when ready, its placeholder while loading (unless skeletonHeader is off), else nothing. */
   protected readonly header: import("@angular/core").Signal<"slot" | "skeleton" | null>;
   protected readonly placeholders: import("@angular/core").Signal<string[]>;
   static ɵfac: i0.ɵɵFactoryDeclaration<ListCard, never>;