@sarj/docs-ui 0.3.1 → 0.4.1

package/README.md

@@ -13,11 +13,13 @@ Import `@sarj/docs-ui/starlight.css` once, then compose the typed Astro componen
 Public exports:
 
 - `@sarj/docs-ui/Breadcrumbs.astro`
+- `@sarj/docs-ui/CodeComparison.astro`
 - `@sarj/docs-ui/PageAnchor.astro`
 - `@sarj/docs-ui/ReferencePage.astro`
 - `@sarj/docs-ui/RulePager.astro`
 - `@sarj/docs-ui/catalog`
 - `@sarj/docs-ui/contracts`
+- `@sarj/docs-ui/line-diff`
 - `@sarj/docs-ui/starlight.css`
 - `@sarj/docs-ui/styles.css`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarj/docs-ui",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "packageManager": "npm@12.0.2",
   "description": "Shared Astro and Starlight reference UI for Sarj standards sites",
   "type": "module",
@@ -12,6 +12,8 @@
     "./starlight.css": "./src/styles/starlight.css",
     "./catalog": "./src/catalog.ts",
     "./contracts": "./src/contracts.ts",
+    "./line-diff": "./src/line-diff.ts",
+    "./CodeComparison.astro": "./src/components/CodeComparison.astro",
     "./PageAnchor.astro": "./src/components/PageAnchor.astro",
     "./ReferencePage.astro": "./src/components/ReferencePage.astro",
     "./RulePager.astro": "./src/components/RulePager.astro",
@@ -40,7 +42,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@fontsource-variable/nunito": "5.3.0"
+    "@fontsource-variable/nunito": "5.3.0",
+    "diff": "8.0.4"
   },
   "peerDependencies": {
     "@astrojs/starlight": ">=0.41.7 <0.42",

package/src/catalog.ts

@@ -1,4 +1,4 @@
-import type { BreadcrumbsProps, ReferencePageProps, RulePagerProps } from './contracts';
+import type { BreadcrumbsProps, CodeComparisonProps, ReferencePageProps, RulePagerProps } from './contracts';
 
 export interface ComponentDefinition<Props extends object = object> {
   exportPath: string;
@@ -22,6 +22,16 @@ export const componentCatalog = Object.freeze({
       current: 'Current page label, announced with aria-current="page".',
     },
   } satisfies ComponentDefinition<BreadcrumbsProps>,
+  CodeComparison: {
+    exportPath: '@sarj/docs-ui/CodeComparison.astro',
+    purpose: 'Compare independently readable before and after source with accessible change cues.',
+    properties: {
+      id: 'Stable identifier used to connect the comparison and its heading.',
+      title: 'Optional scenario heading shared by both sides.',
+      before: 'Rejected or prior source snapshot and its presentation metadata.',
+      after: 'Preferred or resulting source snapshot and its presentation metadata.',
+    },
+  } satisfies ComponentDefinition<CodeComparisonProps>,
   PageAnchor: {
     exportPath: '@sarj/docs-ui/PageAnchor.astro',
     purpose: 'Provide the focusable top anchor used by Starlight reference pages.',

package/src/components/CodeComparison.astro

@@ -0,0 +1,44 @@
+---
+import { Code } from '@astrojs/starlight/components';
+
+import type { CodeComparisonFile, CodeComparisonProps as Props, CodeComparisonSide } from '../contracts';
+
+const { id, title, before, after } = Astro.props;
+const headingId = `${id}-title`;
+
+function files(side: CodeComparisonSide): readonly CodeComparisonFile[] {
+  return side.files.filter((file) => file.source.trim().length > 0);
+}
+---
+
+<section
+  class="sarj-code-comparison"
+  aria-label={title === undefined ? 'Before and after code comparison' : undefined}
+  aria-labelledby={title === undefined ? undefined : headingId}
+  data-code-comparison={id}
+>
+  {title !== undefined && <h3 id={headingId} class="sarj-code-comparison__title">{title}</h3>}
+  <div class="sarj-code-comparison__grid">
+    {[{ side: before, kind: 'before' }, { side: after, kind: 'after' }].map(({ side, kind }) => (
+      <figure class:list={['sarj-code-comparison__side', `sarj-code-comparison__side--${kind}`]}>
+        <figcaption>
+          <span>{side.label}</span>
+          {side.title !== undefined && <strong>{side.title}</strong>}
+        </figcaption>
+        <div class="sarj-code-comparison__files">
+          {files(side).map((file) => (
+            <Code
+              code={file.source}
+              lang={file.language}
+              title={file.title}
+              frame={file.title === undefined ? 'none' : 'code'}
+              del={kind === 'before' ? file.marks : undefined}
+              ins={kind === 'after' ? file.marks : undefined}
+              wrap
+            />
+          ))}
+        </div>
+      </figure>
+    ))}
+  </div>
+</section>

package/src/contracts.ts

@@ -12,6 +12,34 @@ export interface BreadcrumbsProps {
   current: string;
 }
 
+/** A one-based inclusive range understood by Expressive Code text markers. */
+export interface CodeLineMark {
+  range: string;
+}
+
+/** One source file rendered inside a comparison side. */
+export interface CodeComparisonFile {
+  source: string;
+  language: string;
+  title?: string;
+  marks?: CodeLineMark;
+}
+
+/** One independently readable state in a code comparison. */
+export interface CodeComparisonSide {
+  label: string;
+  title?: string;
+  files: readonly CodeComparisonFile[];
+}
+
+/** Public properties accepted by {@link CodeComparison}. */
+export interface CodeComparisonProps {
+  id: string;
+  title?: string;
+  before: CodeComparisonSide;
+  after: CodeComparisonSide;
+}
+
 export interface RulePagerLink {
   href: string;
   label: string;

package/src/line-diff.ts

@@ -0,0 +1,55 @@
+import { diffLines } from 'diff';
+
+import type { CodeLineMark } from './contracts';
+
+export interface ChangedLineMarks {
+  before: CodeLineMark | undefined;
+  after: CodeLineMark | undefined;
+}
+
+/** Return presentation-only line markers for two explicitly related sources. */
+export function changedLineMarks(before: string, after: string): ChangedLineMarks {
+  const beforeLines: number[] = [];
+  const afterLines: number[] = [];
+  let beforeLine = 1;
+  let afterLine = 1;
+
+  for (const change of diffLines(before, after)) {
+    const count = change.count;
+    if (change.removed) {
+      addLines(beforeLines, beforeLine, count);
+      beforeLine += count;
+    } else if (change.added) {
+      addLines(afterLines, afterLine, count);
+      afterLine += count;
+    } else {
+      beforeLine += count;
+      afterLine += count;
+    }
+  }
+
+  return { before: lineMark(beforeLines), after: lineMark(afterLines) };
+}
+
+function addLines(output: number[], first: number, count: number): void {
+  for (let offset = 0; offset < count; offset += 1) output.push(first + offset);
+}
+
+function lineMark(lines: readonly number[]): CodeLineMark | undefined {
+  if (lines.length === 0) return undefined;
+  const ranges: string[] = [];
+  let first = lines[0] ?? 1;
+  let last = first;
+
+  for (const line of lines.slice(1)) {
+    if (line === last + 1) {
+      last = line;
+      continue;
+    }
+    ranges.push(first === last ? String(first) : `${String(first)}-${String(last)}`);
+    first = line;
+    last = line;
+  }
+  ranges.push(first === last ? String(first) : `${String(first)}-${String(last)}`);
+  return { range: ranges.join(',') };
+}

package/src/styles/starlight.css

@@ -1,5 +1,34 @@
 @import './theme.css';
 
+html {
+  scroll-behavior: smooth;
+}
+
+body,
+.content-panel,
+.main-pane,
+.right-sidebar-panel,
+.sidebar-pane {
+  background-color: var(--sl-color-black);
+}
+
+body {
+  font-weight: 450;
+}
+
+.sarj-visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
 .main-pane,
 .main-frame,
 .sl-container {
@@ -7,6 +36,7 @@
 }
 
 .main-pane {
+  --sl-content-width: 100%;
   width: 100%;
 }
 
@@ -14,22 +44,211 @@
   display: none;
 }
 
-header.header {
+.page > header.header {
   border-bottom: 1px solid var(--sarj-color-rule);
   box-shadow: none;
 }
 
-.sidebar-pane a,
+.page > header.header > .header {
+  border-bottom: 0;
+}
+
+.sidebar-content a,
+.sidebar-content summary,
 .social-icons a,
+.header button,
 starlight-menu-button button {
   min-width: 44px;
   min-height: 44px;
 }
 
-.sidebar-content a[aria-current='page'] {
+.sidebar-content a,
+.sidebar-content summary {
+  display: flex;
+  align-items: center;
+}
+
+.sidebar-content a[aria-current='page'],
+.sidebar-content a[aria-current='page']:hover,
+.sidebar-content a[aria-current='page']:focus {
+  background: var(--sl-color-accent-low);
   color: var(--sl-color-accent-high);
 }
 
+:where(.sl-markdown-content, main) :is(h1, h2, h3) {
+  color: var(--sl-color-white);
+  font-weight: 700;
+  letter-spacing: -0.035em;
+  text-wrap: balance;
+}
+
+:where(.sl-markdown-content, main) h1 {
+  font-size: clamp(1.8rem, 3.5vw, 2.35rem);
+  line-height: 1.08;
+}
+
+.sarj-about-page {
+  width: min(100%, 48rem);
+  padding-block: 1.25rem 3rem;
+}
+
+.sarj-about-page > h1 {
+  margin-block: 0 0.75rem;
+}
+
+.sarj-about-page > p {
+  max-width: 42rem;
+  color: var(--sl-color-gray-2);
+  font-size: 1.05rem;
+  line-height: 1.65;
+}
+
+.sarj-related-standards {
+  margin-top: 3rem;
+  padding-top: 1.5rem;
+  border-top: 1px solid var(--sarj-color-rule);
+}
+
+.sarj-related-standards h2 {
+  margin: 0 0 0.5rem;
+  font-size: 1rem;
+}
+
+.sarj-breadcrumbs {
+  margin-block: 0 1.25rem;
+}
+
+.sarj-breadcrumbs ol {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 0.45rem;
+  margin: 0;
+  padding: 0;
+  color: var(--sl-color-gray-2);
+  font-size: 0.85rem;
+  list-style: none;
+}
+
+.sarj-breadcrumbs li + li::before {
+  margin-inline-end: 0.45rem;
+  color: var(--sl-color-gray-4);
+  content: '/';
+}
+
+.sarj-breadcrumbs a {
+  display: inline-flex;
+  min-height: 44px;
+  align-items: center;
+  color: inherit;
+  text-decoration: underline;
+  text-underline-offset: 0.2em;
+}
+
+.sarj-breadcrumbs [aria-current='page'] {
+  color: var(--sl-color-white);
+  font-weight: 650;
+}
+
+.sarj-code-comparison {
+  min-width: 0;
+  max-width: 100%;
+  container-type: inline-size;
+}
+
+.sarj-code-comparison__title {
+  margin: 0 0 0.5rem;
+  font-size: 0.95rem;
+  line-height: 1.35;
+}
+
+.sarj-code-comparison__grid {
+  display: grid;
+  min-width: 0;
+  gap: 1rem;
+}
+
+.sarj-code-comparison__side {
+  display: flex;
+  min-width: 0;
+  max-width: 100%;
+  margin: 0;
+  flex-direction: column;
+  border: 1px solid var(--sarj-color-rule);
+  border-radius: 0.55rem;
+  background: var(--sl-color-black);
+}
+
+.sarj-code-comparison__side--before {
+  border-top-color: var(--sarj-color-report);
+}
+
+.sarj-code-comparison__side--after {
+  border-top-color: var(--sarj-color-pass);
+}
+
+.sarj-code-comparison__side figcaption {
+  display: grid;
+  gap: 0.15rem;
+  padding: 0.75rem 0.9rem;
+  border-bottom: 1px solid var(--sarj-color-rule);
+}
+
+.sarj-code-comparison__side figcaption span {
+  color: var(--sl-color-gray-2);
+  font: 700 0.68rem/1.4 var(--sl-font-mono);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.sarj-code-comparison__side figcaption strong {
+  font-size: 1rem;
+  line-height: 1.35;
+}
+
+.sarj-code-comparison__files,
+.sarj-code-comparison__files > .expressive-code {
+  min-width: 0;
+  max-width: 100%;
+}
+
+.sarj-code-comparison__files {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+}
+
+.sarj-code-comparison__files > .expressive-code {
+  margin: 0;
+}
+
+.sarj-code-comparison__files .expressive-code figure {
+  border: 0;
+  border-top: 1px solid var(--sarj-color-rule);
+  border-radius: 0;
+}
+
+.sarj-code-comparison__files .expressive-code figcaption.header:empty {
+  display: none;
+}
+
+.sarj-code-comparison__files pre {
+  max-width: 100%;
+  overflow: auto;
+}
+
+*:focus-visible {
+  outline: 3px solid var(--sl-color-accent);
+  outline-offset: 3px;
+}
+
+@container (min-width: 52rem) {
+  .sarj-code-comparison__grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    align-items: stretch;
+  }
+}
+
 .sarj-rule-pager {
   display: flex;
   flex: 0 0 auto;
@@ -71,3 +290,10 @@ starlight-menu-button button {
 @media (prefers-reduced-motion: reduce) {
   :root { scroll-behavior: auto; }
 }
+
+@media (forced-colors: active) {
+  .sarj-code-comparison__side--before,
+  .sarj-code-comparison__side--after {
+    border-top-width: 3px;
+  }
+}