@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/prose.md

@@ -0,0 +1,226 @@
+<!-- index: ./index.md -->
+# prose
+
+`data-ui="prose"` · Styles long-form HTML text.
+
+## Import
+
+```ts
+import {
+  provideProseDefaults,
+  SlProse,
+  SlProseAnchor,
+  SlProseExclude,
+  SlProseFootnotes,
+  SlProseLead,
+  SlProseScroll,
+} from '@slotted/angular/prose';
+```
+
+Selector: `[slProse]` · exportAs: `slProse`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<article slProse size="lg" flow="normal" [innerHTML]="rendered"></article>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element the page wrote — div, article, section | yes |
+| `lead` | p, by slProseLead | no |
+| `anchor` | a, by slProseAnchor | no |
+| `scroll` | div, by slProseScroll | no |
+| `exclude` | any element, by slProseExclude | no |
+| `footnotes` | section, by slProseFootnotes | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `'md' \| 'lg' \| 'xl'` | lg | slProse | The type-scale step the body text takes. Named for the scale’s own steps, so the offset from control type is visible: lg is one rem, and md is the size a button label is set in |
+| `flow` | `'tight' \| 'normal' \| 'loose'` | normal | slProse | The space between blocks, from which every other distance derives — the gap above a heading, between list rows, and around a rule. tight is a chat message, loose an article |
+| `messages` | `Partial<ProseMessages>` | — | slProseScroll | Words laid over the language in force: the last resort name of a scrolling block (scroll), used when neither labelledBy nor aria-label names one. It comes from the catalog rather than a required input because a renderer’s component map cannot supply one per table |
+| `labelledBy` | `string` | — | slProseScroll | Names it from an element already on the page — the block’s own caption is the good answer, and the one Adrian Roselli’s pattern uses |
+| `the attribute selector` | `directive` | — | every part | Each part attaches to the element the template already has, so a page keeps its own tags and the family adds only its data attributes. Nothing is re-projected, and nothing needs NgTemplateOutlet |
+| `exportAs` | `slProse, slProseScroll` | — | slProse, slProseScroll | Reaches the instance from the template. On the scrolling block that is refresh() and isOverflowing(): content that arrived without Angular knowing — an image finishing, a renderer writing into the DOM — changes whether the block overflows after the observer measured |
+| `provideProseDefaults` | `{ size, flow }` | — | a route or the application | Sets both once for every region under it — Typeset’s presets, typed. An explicit input on one region still wins, and providing again on a route narrows the decision for part of an application |
+| `role, aria-label` | `static attribute` | — | slProseScroll | A name or a role the template wrote is read with HostAttributeToken before anything is bound over it, so a consumer who named the region itself keeps that name |
+| `slContainer` | `composition` | — | around slProse | The measure belongs to container and to it alone: size="measure" is the maximum this family refuses to state. Tailwind bakes 65ch in and ships max-w-none to remove it |
+| `slLink, slKbd, slCheckbox` | `composition` | — | inside slProse | Every content rule weighs 0-1-0, so a family placed inside the region wins on specificity and is left exactly as it is. A bare a, hr or kbd from the renderer reads the same theme tokens the family would |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `md`, `lg`, `xl` | `lg` |
+| `flow` | `tight`, `normal`, `loose` | `normal` |
+
+## Rules
+
+- There is no APG pattern for this family: the Authoring Practices publish patterns for widgets a reader operates, and a region of rendered text is not one. The governing sources are the platform’s own semantics for the elements a renderer emits, SC 1.4.8 and SC 1.4.12 for how that text may be spaced, and the axe rule scrollable-region-focusable for the one block a reader has to move.
+- A wide block takes role="region", tabindex="0" and a name only while it actually overflows. The axe rule makes an unreachable scroller a level A failure, and anything that takes focus then needs a name and a role or it fails SC 4.1.2 — so both halves are written together, and neither is written on a block that fits. A role the template wrote itself is kept.
+- The heading anchor is hidden with opacity, never with display: none or visibility: hidden. It stays in the tab sequence and in the accessible tree, appears on hover and on focus-visible, and holds a 24-pixel target — WCAG 2.2 SC 2.5.8. The directive writes a word joiner before it so the last word of a title and its permalink wrap together.
+- The family sets no fixed block size and clips no text box, so a reader raising line height to 1.5, paragraph spacing to 2 and tracking to 0.12 of the font size loses nothing — SC 1.4.12. Leading is stated once, at 1.5, rather than taken per step: the scale pairs 1.45 with its two largest steps because a control label is one line, and a paragraph is not.
+- Every rule is written in logical properties, so a right-to-left document is the same component mirrored rather than a second stylesheet. A fence is the exception and is forced left to right: the order of the characters is what the code means.
+- The family holds no mutable value, so it emits nothing and has no output table. Which words appear here is the renderer’s decision, and so is whether they are announced: a region that announced every appended token would read a whole answer twice.
+- It does not sanitise. Angular’s own DomSanitizer and the renderer that produced the tree are where that belongs, and a component that both styled and sanitised would hide which of the two failed.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-divider-color`, `--slotted-divider-thickness`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-mono`, `--slotted-font-family-sans`, `--slotted-font-size-lg`, `--slotted-font-size-md`, `--slotted-font-size-xl`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-kbd-border-width`, `--slotted-kbd-font-family`, `--slotted-kbd-font-weight`, `--slotted-kbd-radius`, `--slotted-line-height-2xl`, `--slotted-line-height-3xl`, `--slotted-line-height-lg`, `--slotted-line-height-md`, `--slotted-link-color`, `--slotted-link-color-hover`, `--slotted-link-focus-ring-offset`, `--slotted-link-underline-color`, `--slotted-link-underline-offset`, `--slotted-link-underline-thickness`, `--slotted-prose-anchor-gap`, `--slotted-prose-caption-size`, `--slotted-prose-code-inset`, `--slotted-prose-code-size`, `--slotted-prose-flow-loose`, `--slotted-prose-flow-normal`, `--slotted-prose-flow-tight`, `--slotted-prose-focus-ring-offset`, `--slotted-prose-font-family`, `--slotted-prose-footnotes-size`, `--slotted-prose-h1-size`, `--slotted-prose-h1-size-narrow`, `--slotted-prose-h2-size`, `--slotted-prose-h2-size-narrow`, `--slotted-prose-h3-size`, `--slotted-prose-h4-size`, `--slotted-prose-h5-size`, `--slotted-prose-h6-size`, `--slotted-prose-h6-tracking`, `--slotted-prose-lead-line-height`, `--slotted-prose-lead-size`, `--slotted-prose-line-height`, `--slotted-prose-list-inset`, `--slotted-prose-list-inset-narrow`, `--slotted-prose-mark-inset`, `--slotted-prose-marker-gap`, `--slotted-prose-media-radius`, `--slotted-prose-quote-color`, `--slotted-prose-quote-inset`, `--slotted-prose-quote-thickness`, `--slotted-prose-small-size`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-radius-xs`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-warning-surface`, `--slotted-tone-warning-text`
+
+## Examples
+
+### Every element a renderer emits
+
+Headings, lists, a quotation, a fence, a table, media, a rule, a description list, a disclosure and the inline set — all bare tags, styled without a single attribute of their own.
+
+Excerpt — not a complete module
+
+```html
+<div slProse [innerHTML]="sanitized"></div>
+```
+
+### Size
+
+The type-scale step the body takes. lg is one rem and is the default; md is the size a button label is set in, for a region inside dense product chrome.
+
+Excerpt — not a complete module
+
+```html
+<div slProse size="md">…</div>
+<div slProse size="lg">…</div>
+<div slProse size="xl">…</div>
+```
+
+### Flow
+
+The one number that governs every gap on the page. Heading spacing, list spacing and the room around a rule all derive from it, so a chat message and an article are one input apart.
+
+Excerpt — not a complete module
+
+```html
+<div slProse flow="tight">…</div>
+<div slProse flow="normal">…</div>
+<div slProse flow="loose">…</div>
+```
+
+### The lead paragraph
+
+The opening sentence set one step up, in the muted role, with a wider gap under it — so the opening reads as its own movement rather than as the first of several paragraphs.
+
+Excerpt — not a complete module
+
+```html
+<div slProse>
+  <h2>Deploying a service</h2>
+  <p slProseLead>Everything a team needs to move a service to production.</p>
+  <p>A deployment is three decisions…</p>
+</div>
+```
+
+### Heading anchors
+
+Hover a heading, then tab to its permalink: it appears for both, because a control that answers hover alone is a control a keyboard cannot find. It holds its box whether visible or not, so revealing it moves nothing.
+
+Excerpt — not a complete module
+
+```html
+<h2 id="deploying">
+  Deploying a service<a slProseAnchor href="#deploying" aria-label="Link to this section">#</a>
+</h2>
+```
+
+### A block wider than its column
+
+Tab into the table below: it takes a tab stop, a region role and a name only because it overflows. Widen the window until it fits and all three disappear, which is the point.
+
+Excerpt — not a complete module
+
+```html
+<div slProseScroll labelledBy="environments" #wide="slProseScroll">
+  <table>
+    <caption id="environments">
+      Environments and their gates
+    </caption>
+  </table>
+</div>
+<button type="button" (click)="wide.refresh()">Measure again</button>
+```
+
+### Opting a component out
+
+The card below sits inside the region and keeps its own type, rhythm and colour. Everything around it is still set by the family, and the boundary is one directive.
+
+Excerpt — not a complete module
+
+```html
+<div slProse>
+  <p>Styled by the family.</p>
+  <div slProseExclude>
+    <div slCard>Untouched.</div>
+  </div>
+</div>
+```
+
+### Content that is still arriving
+
+Press the button and blocks are appended one at a time, the way a language model answers. Nothing already on screen moves: no rule in this family selects forward, and every gap is on the block that arrives.
+
+Excerpt — not a complete module
+
+```html
+<div slProse flow="tight">
+  @for (block of blocks(); track block.id) {
+    <p>{{ block.text }}</p>
+  }
+</div>
+```
+
+### Content the family did not choose
+
+A body that starts at h3, two headings with nothing between them, a pasted destination with no break in it, four levels of list, and a right-to-left paragraph in the middle of the page.
+
+Excerpt — not a complete module
+
+```html
+<div slProse>
+  <h3>A body that does not start at the top level</h3>
+  <h4>Two headings with nothing between them</h4>
+  <p lang="ar" dir="rtl">فقرة عربية داخل نفس المنطقة.</p>
+</div>
+```
+
+### The families it sits with
+
+slContainer bounds the measure, and a real slLink inside the text wins on specificity — every content rule here is written to lose to a family placed inside it.
+
+Excerpt — not a complete module
+
+```html
+<div slContainer size="measure">
+  <article slProse>
+    <p>Read <a slLink href="/guide">the guide</a> first.</p>
+  </article>
+</div>
+```
+
+### Accessibility
+
+The two things in this family a reader operates: the permalink beside a heading, and the scrolling block. Tab through the region and both take focus in the order the document holds them.
+
+Excerpt — not a complete module
+
+```html
+<div slProse>
+  <h2 id="gates">Gates<a slProseAnchor href="#gates" aria-label="Link to this section">#</a></h2>
+  <div slProseScroll labelledBy="gates">
+    <table></table>
+  </div>
+</div>
+```