@sarj/docs-ui 0.2.0 → 0.3.1

package/README.md

@@ -8,15 +8,17 @@ Shared Astro and Starlight reference UI for Sarj standards sites
 npm install --save-dev @sarj/docs-ui
 ```
 
-Import `@sarj/docs-ui/styles.css` once, then compose the typed Astro components. The live component and theme contract is published at [code-standards.sarj.ai/design-system/](https://code-standards.sarj.ai/design-system/).
+Import `@sarj/docs-ui/starlight.css` once, then compose the typed Astro components. The live component and theme contract is published at [docs-ui.sarj.ai](https://docs-ui.sarj.ai/).
 
 Public exports:
 
 - `@sarj/docs-ui/Breadcrumbs.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/starlight.css`
 - `@sarj/docs-ui/styles.css`
 
-[Documentation](https://code-standards.sarj.ai/) · [Source](https://github.com/sarj-ai/code-standards)
+[Documentation](https://docs-ui.sarj.ai/) · [Source](https://github.com/sarj-ai/code-standards)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarj/docs-ui",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "packageManager": "npm@12.0.2",
   "description": "Shared Astro and Starlight reference UI for Sarj standards sites",
   "type": "module",
@@ -9,10 +9,12 @@
   },
   "exports": {
     "./styles.css": "./src/styles/theme.css",
+    "./starlight.css": "./src/styles/starlight.css",
     "./catalog": "./src/catalog.ts",
     "./contracts": "./src/contracts.ts",
     "./PageAnchor.astro": "./src/components/PageAnchor.astro",
     "./ReferencePage.astro": "./src/components/ReferencePage.astro",
+    "./RulePager.astro": "./src/components/RulePager.astro",
     "./Breadcrumbs.astro": "./src/components/Breadcrumbs.astro"
   },
   "files": [
@@ -21,7 +23,8 @@
     "LICENSE"
   ],
   "sideEffects": [
-    "./src/styles/theme.css"
+    "./src/styles/theme.css",
+    "./src/styles/starlight.css"
   ],
   "publishConfig": {
     "access": "public"
@@ -31,7 +34,7 @@
     "url": "git+https://github.com/sarj-ai/code-standards.git",
     "directory": "packages/docs-ui"
   },
-  "homepage": "https://code-standards.sarj.ai/",
+  "homepage": "https://docs-ui.sarj.ai/",
   "bugs": {
     "url": "https://github.com/sarj-ai/code-standards/issues"
   },

package/src/catalog.ts

@@ -1,4 +1,4 @@
-import type { BreadcrumbsProps, ReferencePageProps } from './contracts';
+import type { BreadcrumbsProps, ReferencePageProps, RulePagerProps } from './contracts';
 
 export interface ComponentDefinition<Props extends object = object> {
   exportPath: string;
@@ -9,6 +9,8 @@ export interface ComponentDefinition<Props extends object = object> {
 export interface ThemeTokenDefinition {
   cssName: `--sarj-${string}`;
   purpose: string;
+  light: `#${string}`;
+  dark: `#${string}`;
 }
 
 export const componentCatalog = Object.freeze({
@@ -27,25 +29,31 @@ export const componentCatalog = Object.freeze({
   } satisfies ComponentDefinition,
   ReferencePage: {
     exportPath: '@sarj/docs-ui/ReferencePage.astro',
-    purpose: 'Render a Starlight reference shell with explicit search and robots behavior.',
+    purpose: 'Render a Starlight reference shell with explicit robots behavior.',
     properties: {
       title: 'Document title and primary accessible page identity.',
       description: 'Concise page description used by document metadata.',
       sidebar: 'Starlight sidebar definition for this reference surface.',
-      searchable: 'Whether Pagefind indexes the page body; defaults to true.',
       indexable: 'Whether robots may index the public page; defaults to true.',
-      discovery: 'Deprecated shorthand retained for compatibility; never access control.',
       hasSidebar: 'Whether the Starlight sidebar is rendered; defaults to true.',
       template: 'Starlight document or splash template; defaults to doc.',
     },
   } satisfies ComponentDefinition<ReferencePageProps>,
+  RulePager: {
+    exportPath: '@sarj/docs-ui/RulePager.astro',
+    purpose: 'Navigate between adjacent rules with accessible links and guarded arrow-key shortcuts.',
+    properties: {
+      previous: 'Optional previous rule link and label.',
+      next: 'Optional next rule link and label.',
+    },
+  } satisfies ComponentDefinition<RulePagerProps>,
 });
 
 export const themeTokenCatalog = Object.freeze([
-  { cssName: '--sarj-color-report', purpose: 'Diagnostic and rejection emphasis.' },
-  { cssName: '--sarj-color-pass', purpose: 'Accepted example and success emphasis.' },
-  { cssName: '--sarj-color-warning', purpose: 'Warning-level diagnostic emphasis with AA text contrast.' },
-  { cssName: '--sarj-color-rule', purpose: 'Structural borders and separators.' },
-  { cssName: '--sarj-color-paper', purpose: 'Reference surface background.' },
-  { cssName: '--sarj-color-ink', purpose: 'Primary reference text.' },
+  { cssName: '--sarj-color-report', purpose: 'Diagnostic and rejection emphasis.', light: '#c34453', dark: '#ff8794' },
+  { cssName: '--sarj-color-pass', purpose: 'Accepted example and success emphasis.', light: '#16806d', dark: '#62d5bd' },
+  { cssName: '--sarj-color-warning', purpose: 'Warning-level diagnostic emphasis with AA text contrast.', light: '#986a00', dark: '#a97708' },
+  { cssName: '--sarj-color-rule', purpose: 'Structural borders and separators.', light: '#e4e6eb', dark: '#272a32' },
+  { cssName: '--sarj-color-paper', purpose: 'Reference surface background.', light: '#ffffff', dark: '#0b0c10' },
+  { cssName: '--sarj-color-ink', purpose: 'Primary reference text.', light: '#12141a', dark: '#f4f5f8' },
 ] satisfies readonly ThemeTokenDefinition[]);

package/src/components/Breadcrumbs.astro

@@ -4,7 +4,7 @@ import type { BreadcrumbsProps as Props } from '../contracts';
 const { ancestors, current } = Astro.props;
 ---
 
-<nav class="breadcrumbs" aria-label="Breadcrumb">
+<nav class="breadcrumbs sarj-breadcrumbs" aria-label="Breadcrumb">
   <ol>
     {ancestors.map((ancestor) => <li><a href={ancestor.href}>{ancestor.label}</a></li>)}
     <li><span aria-current="page">{current}</span></li>

package/src/components/ReferencePage.astro

@@ -6,14 +6,11 @@ const {
   title,
   description,
   sidebar,
-  searchable: searchableProp,
   indexable: indexableProp,
-  discovery,
   hasSidebar = true,
   template = 'doc',
 } = Astro.props;
-const searchable = searchableProp ?? (discovery === undefined || discovery === 'searchable');
-const indexable = indexableProp ?? discovery !== 'unlisted';
+const indexable = indexableProp ?? true;
 ---
 
 <StarlightPage
@@ -21,7 +18,7 @@ const indexable = indexableProp ?? discovery !== 'unlisted';
     title,
     description,
     template,
-    pagefind: searchable,
+    pagefind: false,
     prev: false,
     next: false,
     head: indexable ? [] : [{ tag: 'meta', attrs: { name: 'robots', content: 'noindex, nofollow' } }],
@@ -29,7 +26,7 @@ const indexable = indexableProp ?? discovery !== 'unlisted';
   sidebar={sidebar}
   hasSidebar={hasSidebar}
 >
-  <div data-pagefind-body={searchable ? true : undefined} data-pagefind-ignore={searchable ? undefined : true}>
+  <div>
     <slot />
   </div>
 </StarlightPage>

package/src/components/RulePager.astro

@@ -0,0 +1,32 @@
+---
+import type { RulePagerProps as Props } from '../contracts';
+
+const { previous, next } = Astro.props;
+---
+
+<nav class="sarj-rule-pager" aria-label="Rule navigation">
+  {previous && (
+    <a href={previous.href} rel="prev" data-rule-previous aria-keyshortcuts="ArrowLeft" aria-label={`Previous rule: ${previous.label}`} title={previous.label}>
+      <kbd aria-hidden="true">←</kbd><span>Previous</span>
+    </a>
+  )}
+  {next && (
+    <a href={next.href} rel="next" data-rule-next aria-keyshortcuts="ArrowRight" aria-label={`Next rule: ${next.label}`} title={next.label}>
+      <span>Next</span><kbd aria-hidden="true">→</kbd>
+    </a>
+  )}
+</nav>
+
+<script>
+  document.addEventListener('keydown', (event) => {
+    if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
+    if (event.target instanceof Element && event.target.closest('a, button, input, select, textarea, summary, [contenteditable]')) return;
+    const selector = event.key === 'ArrowLeft' ? '[data-rule-previous]' : event.key === 'ArrowRight' ? '[data-rule-next]' : null;
+    if (!selector) return;
+    const link = document.querySelector(selector);
+    if (link instanceof HTMLAnchorElement) {
+      event.preventDefault();
+      location.assign(link.href);
+    }
+  });
+</script>

package/src/contracts.ts

@@ -12,25 +12,26 @@ export interface BreadcrumbsProps {
   current: string;
 }
 
-export type ReferenceSidebar = NonNullable<StarlightUserConfig['sidebar']>;
+export interface RulePagerLink {
+  href: string;
+  label: string;
+}
 
-/**
- * Legacy discovery shorthand. `unlisted` affects search and robots metadata;
- * it is not access control and the rendered page remains public.
- */
-export type ReferenceDiscovery = 'searchable' | 'navigation-only' | 'unlisted';
+/** Public properties accepted by {@link RulePager}. */
+export interface RulePagerProps {
+  previous?: RulePagerLink | null;
+  next?: RulePagerLink | null;
+}
+
+export type ReferenceSidebar = NonNullable<StarlightUserConfig['sidebar']>;
 
 /** Public properties accepted by {@link ReferencePage}. */
 export interface ReferencePageProps {
   title: string;
   description: string;
   sidebar: ReferenceSidebar;
-  /** Include the page body in Pagefind. Defaults to true. */
-  searchable?: boolean;
   /** Allow search engines to index the page. Defaults to true. */
   indexable?: boolean;
-  /** @deprecated Prefer the explicit `searchable` and `indexable` properties. */
-  discovery?: ReferenceDiscovery;
   hasSidebar?: boolean;
   template?: 'doc' | 'splash';
 }

package/src/styles/starlight.css

@@ -0,0 +1,73 @@
+@import './theme.css';
+
+.main-pane,
+.main-frame,
+.sl-container {
+  min-width: 0;
+}
+
+.main-pane {
+  width: 100%;
+}
+
+.content-panel:has(> .reference-page-anchor:only-child) {
+  display: none;
+}
+
+header.header {
+  border-bottom: 1px solid var(--sarj-color-rule);
+  box-shadow: none;
+}
+
+.sidebar-pane a,
+.social-icons a,
+starlight-menu-button button {
+  min-width: 44px;
+  min-height: 44px;
+}
+
+.sidebar-content a[aria-current='page'] {
+  color: var(--sl-color-accent-high);
+}
+
+.sarj-rule-pager {
+  display: flex;
+  flex: 0 0 auto;
+  gap: 0.35rem;
+  margin: 0;
+}
+
+.sarj-rule-pager a {
+  display: inline-flex;
+  min-height: 44px;
+  align-items: center;
+  gap: 0.3rem;
+  padding: 0.35rem 0.55rem;
+  border: 1px solid var(--sarj-color-rule);
+  border-radius: 0.4rem;
+  color: var(--sl-color-white);
+  font-size: 0.75rem;
+  text-decoration: none;
+}
+
+.sarj-rule-pager a:hover,
+.sarj-rule-pager a:focus-visible {
+  border-color: var(--sl-color-accent);
+}
+
+.sarj-rule-pager kbd {
+  padding: 0.05rem 0.28rem;
+  border: 1px solid var(--sarj-color-rule);
+  border-radius: 0.2rem;
+  background: var(--sl-color-gray-6);
+  font-family: var(--sl-font-mono);
+}
+
+@media (max-width: 22rem) {
+  .sarj-rule-pager a { width: 44px; justify-content: center; padding-inline: 0; }
+  .sarj-rule-pager a span { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root { scroll-behavior: auto; }
+}

package/src/styles/theme.css

@@ -48,3 +48,39 @@
   --sarj-color-paper: #0b0c10;
   --sarj-color-ink: #f4f5f8;
 }
+
+.breadcrumbs ol {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.35rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.breadcrumbs li {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  min-width: 0;
+}
+
+.breadcrumbs li + li::before {
+  color: var(--sl-color-gray-3);
+  content: '/';
+}
+
+.breadcrumbs a,
+.breadcrumbs [aria-current='page'] {
+  overflow-wrap: anywhere;
+}
+
+.breadcrumbs a {
+  border-radius: 0.2rem;
+  color: var(--sl-color-accent-high);
+}
+
+.breadcrumbs a:focus-visible {
+  outline: 2px solid var(--sl-color-accent);
+  outline-offset: 3px;
+}