@smwb/ui-styles 2.7.0 → 2.8.0

package/README.md

@@ -144,6 +144,26 @@ so a copied or printed svg scans without the library CSS). Only the caption is t
 (`--smui-onSurfaceVariant`). The corner rounding is `@qrCodeRadius` (`@smui-radius-sm`); the svg clips to
 it, and the quiet zone keeps the modules clear of the rounding.
 
+#### Markdown
+
+`Markdown` (issue and PR descriptions and comments) takes its text styles from `@markdown*` variables and
+its colours from runtime tokens, so the dark theme follows without extra settings: the link is
+`@markdownLinkColor` (`--smui-primaryColor`), the code and table-head surfaces are
+`@markdownCodeBackground` / `@markdownTableHeadBackground` (`--smui-surfaceVariant`), the quote border and
+text are `@markdownQuoteBorderColor` / `@markdownQuoteColor` (`--smui-outlineColor` /
+`--smui-onSurfaceVariant`), the table borders are `@markdownTableBorderColor` (`--smui-tableBorderColor`)
+and the rule is `@markdownRuleColor` (`--smui-dividerColor`). The type scale lives in
+`@markdownFontSize` / `@markdownLineHeight` (body2), the six `@markdownHeading*Size` steps, sized in `em`
+off the prose, `@markdownHeadingWeight`, `@markdownListIndent`, the code measures (`@markdownCodeFontFamily`,
+`@markdownCodeFontSize`, `@markdownCodeRadius`, `@markdownCodeBlockPadding`, `@markdownInlineCodePadding`),
+the quote's `@markdownQuoteBorderWidth` and the table's `@markdownTableCellPadding`.
+
+Two layout promises are part of the theme contract: the prose wraps long words and addresses itself
+(`overflow-wrap: anywhere` on the root), and the code blocks and tables scroll sideways _inside
+themselves_ (`overflow-x: auto` with `contain: inline-size`), so a long line or a wide table never widens
+the page — not even inside a flex or grid parent that does not set `min-width: 0`. Override the variables
+in `theme.config`; an app needs no rules of its own on the `smwb-markdown` classes.
+
 #### DagView colours
 
 The dependency graph (`DagView` in `@smwb/ui-solid` and `@smwb/ui-react`) takes its colours from theme variables that default to the

package/less/components/markdown/markdown.entry.less

@@ -0,0 +1,2 @@
+@import (reference) "../../_prelude.less";
+@import "./markdown.less";

package/less/components/markdown/markdown.less

@@ -0,0 +1,265 @@
+// Markdown prose: an issue or PR description or comment rendered from a parsed tree.
+// Text styles follow the @markdown* theme variables; colours are runtime tokens, so the
+// dark theme follows without extra settings. Long words and addresses wrap in the prose
+// itself; the wide blocks (code and tables) scroll sideways inside themselves instead
+// of widening the page — `contain: inline-size` takes their min-content contribution out
+// of flex and grid parents that do not set min-width: 0.
+.smwb-markdown {
+  min-width: 0;
+  max-width: 100%;
+  overflow-wrap: anywhere;
+  font-size: @markdownFontSize;
+  line-height: @markdownLineHeight;
+
+  // Blocks stack with a gap; the first and the last child carry no outer margin.
+  > * {
+    margin-block: 0;
+  }
+  > * + * {
+    margin-block-start: @markdownBlockGap;
+  }
+
+  // Over the maxLength cap, and for raw HTML that survived as a block, the text is pre-wrapped prose.
+  &__plain,
+  &__raw {
+    white-space: pre-wrap;
+  }
+
+  // The look follows the Markdown level (the class), not the tag: `headingOffset` shifts
+  // the tag for the document outline, not the size.
+  &__heading {
+    font-weight: @markdownHeadingWeight;
+    line-height: 1.3;
+
+    &_level-1 {
+      font-size: @markdownHeading1Size;
+    }
+    &_level-2 {
+      font-size: @markdownHeading2Size;
+    }
+    &_level-3 {
+      font-size: @markdownHeading3Size;
+    }
+    &_level-4 {
+      font-size: @markdownHeading4Size;
+    }
+    &_level-5 {
+      font-size: @markdownHeading5Size;
+    }
+    &_level-6 {
+      font-size: @markdownHeading6Size;
+    }
+  }
+
+  &__rule {
+    height: 0;
+    border: 0;
+    border-block-start: 1px solid @markdownRuleColor;
+  }
+
+  &__quote {
+    margin-inline: 0;
+    padding-inline-start: @markdownBlockGap;
+    border-inline-start: @markdownQuoteBorderWidth solid @markdownQuoteBorderColor;
+    color: @markdownQuoteColor;
+
+    > * + * {
+      margin-block-start: @markdownBlockGap;
+    }
+  }
+
+  // Deep nesting stops widening the text: from the fourth occurrence of the same container on,
+  // a quote, a list or a footnote indents only a little, so the deepest text that still draws as
+  // Markdown (31 levels of quotes, lists and footnotes, alone or mixed) fits a phone-width column.
+  &__quote &__quote &__quote &__quote,
+  &__footnote &__footnote &__footnote &__footnote {
+    padding-inline-start: ~"calc(@{markdownBlockGap} / 3)";
+  }
+  &__list &__list &__list &__list {
+    padding-inline-start: ~"calc(@{markdownListIndent} * 2 / 3)";
+  }
+
+  // The marker kind lives on the list…
+  &__list {
+    padding-inline-start: @markdownListIndent;
+    list-style: disc;
+
+    &_ordered {
+      list-style: decimal;
+    }
+
+    // A nested list hangs closer to its parent item than a top-level block gap.
+    .smwb-markdown__list {
+      margin-block-start: ~"calc(@{markdownBlockGap} / 2)";
+    }
+  }
+
+  // …and reaches each item through `inherit`: normalize.css sets `list-style: none` on every
+  // `ul li` (0,0,2), and this class (0,1,0) wins over it.
+  &__item {
+    list-style: inherit;
+
+    // Loose list items stack their paragraphs like the root's blocks.
+    > * + * {
+      margin-block-start: ~"calc(@{markdownBlockGap} / 2)";
+    }
+
+    // A task item drops its marker, the checkbox leads it instead; plain items in the same list
+    // keep theirs. In a loose item the first paragraph runs on after the checkbox.
+    &_task {
+      list-style: none;
+
+      > .smwb-markdown__checkbox + .smwb-markdown__paragraph {
+        display: inline;
+      }
+    }
+  }
+
+  // normalize.css stretches every `input` to the full width and height of its parent; the
+  // checkbox keeps its own size so the item's text runs on beside it.
+  &__checkbox {
+    width: auto;
+    height: auto;
+    margin-block: 0;
+    margin-inline-end: 0.5em;
+    vertical-align: middle;
+    accent-color: var(--smui-primaryColor);
+  }
+
+  // A focusable scroll container: it keeps long lines inside itself, never the page.
+  &__code-block {
+    max-width: 100%;
+    overflow-x: auto;
+    contain: inline-size;
+    padding: @markdownCodeBlockPadding;
+    border-radius: @markdownCodeRadius;
+    background-color: @markdownCodeBackground;
+    white-space: pre;
+    overflow-wrap: normal;
+    tab-size: 4;
+
+    @supports not (contain: inline-size) {
+      width: 0;
+      min-width: 100%;
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--smui-primaryColor);
+      outline-offset: 2px;
+    }
+  }
+
+  &__code,
+  &__inline-code {
+    font-family: @markdownCodeFontFamily;
+    font-size: @markdownCodeFontSize;
+  }
+
+  &__code {
+    padding: 0;
+    border-radius: 0;
+    background-color: transparent;
+  }
+
+  &__inline-code {
+    padding: @markdownInlineCodePadding;
+    border-radius: @markdownCodeRadius;
+    background-color: @markdownCodeBackground;
+    // The background (and padding), not the font, tells inline code apart: an app's own
+    // UI font may already be monospace, so a different family alone would read as plain text.
+  }
+
+  &__table-wrap {
+    max-width: 100%;
+    overflow-x: auto;
+    contain: inline-size;
+
+    @supports not (contain: inline-size) {
+      width: 0;
+      min-width: 100%;
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--smui-primaryColor);
+      outline-offset: 2px;
+    }
+  }
+
+  // The cells carry the borders, so the grid reads both when the table fills the wrap
+  // and when the wrap scrolls sideways over a wider table.
+  &__table {
+    width: 100%;
+    border-collapse: collapse;
+  }
+
+  // Cells wrap at spaces only: with the root's `overflow-wrap: anywhere` every character would
+  // be a break, the table's min-content width would drop to nothing and a wide table would squeeze
+  // into the wrap instead of scrolling inside it. Prose in a cell still wraps.
+  &__cell {
+    overflow-wrap: normal;
+    padding: @markdownTableCellPadding;
+    border: 1px solid @markdownTableBorderColor;
+    text-align: left;
+
+    &_head {
+      background-color: @markdownTableHeadBackground;
+      font-weight: @markdownHeadingWeight;
+    }
+
+    &_align-left {
+      text-align: left;
+    }
+    &_align-center {
+      text-align: center;
+    }
+    &_align-right {
+      text-align: right;
+    }
+  }
+
+  &__link {
+    color: @markdownLinkColor;
+    text-decoration: underline;
+    text-underline-offset: 0.15em;
+
+    &:hover,
+    &:focus-visible {
+      text-decoration-thickness: 2px;
+    }
+  }
+
+  &__image {
+    max-width: 100%;
+    height: auto;
+  }
+
+  // Footnotes render where their definitions stand, with no ids or back-links.
+  &__footnote {
+    margin-inline: 0;
+    padding-inline-start: @markdownListIndent;
+
+    > * + * {
+      margin-block-start: @markdownBlockGap;
+    }
+  }
+
+  // The label leads the definition's first paragraph on its line.
+  &__footnote-label {
+    margin-inline-end: 0.5em;
+    font-weight: @markdownHeadingWeight;
+
+    + .smwb-markdown__paragraph {
+      display: inline;
+    }
+  }
+}
+
+// Forced colours drop background colours: the code surfaces become frames so they stay visible.
+@media (forced-colors: active) {
+  .smwb-markdown {
+    &__code-block,
+    &__inline-code {
+      border: 1px solid CanvasText;
+    }
+  }
+}

package/less/components.less

@@ -42,6 +42,7 @@
 @import "./components/grid/grid.less";
 @import "./components/tooltip/tooltip.less";
 @import "./components/kbd/kbd.less";
+@import "./components/markdown/markdown.less";
 @import "./components/commandPalette/commandPalette.less";
 @import "./components/sheet/sheet.less";
 @import "./components/floatingWindow/floatingWindow.less";

package/less/default/globals/default.variables.less

@@ -229,6 +229,35 @@
 @kbdKeyMinSize: 1.5em; // a key cap is square at one character
 @kbdKeyPaddingX: 0.375em;
 @kbdKeyRadius: @smui-radius-sm;
+
+// ---- Markdown ----
+// Prose of Markdown descriptions and comments. The colours are runtime tokens, so the
+// dark theme follows without a Dark set here.
+@markdownFontSize: @smui-font-body2-size; // 14px
+@markdownLineHeight: @smui-font-body2-lh; // 1.5
+@markdownBlockGap: @smui-space-md; // 12px between blocks
+@markdownHeadingWeight: 600;
+@markdownHeading1Size: 1.5em;
+@markdownHeading2Size: 1.3em;
+@markdownHeading3Size: 1.15em;
+@markdownHeading4Size: 1em;
+@markdownHeading5Size: 0.925em;
+@markdownHeading6Size: 0.85em;
+@markdownListIndent: 1.5em;
+@markdownLinkColor: ~"var(--smui-primaryColor)";
+@markdownCodeFontFamily: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
+@markdownCodeFontSize: 0.9em;
+@markdownCodeBackground: ~"var(--smui-surfaceVariant)";
+@markdownCodeRadius: @smui-radius-sm;
+@markdownCodeBlockPadding: @smui-space-sm @smui-space-md;
+@markdownInlineCodePadding: 0.1em 0.35em;
+@markdownQuoteBorderWidth: 3px;
+@markdownQuoteBorderColor: ~"var(--smui-outlineColor)";
+@markdownQuoteColor: ~"var(--smui-onSurfaceVariant)";
+@markdownTableBorderColor: ~"var(--smui-tableBorderColor)";
+@markdownTableCellPadding: @smui-space-xs @smui-space-sm;
+@markdownTableHeadBackground: ~"var(--smui-surfaceVariant)";
+@markdownRuleColor: ~"var(--smui-dividerColor)";
 // ---- DiffStat ----
 @diffStatFontSize: 0.875rem;
 @diffStatCompactFontSize: 0.75rem; // a tab label

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smwb/ui-styles",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Framework-agnostic LESS design tokens and component styles (smwb-*) shared by the @smwb UI libraries. Prebuilt aggregate CSS lives in @smwb/ui-css.",
   "license": "MIT",
   "sideEffects": [