@sarj/docs-ui 0.1.1 → 0.3.1

package/README.md

@@ -8,6 +8,17 @@ Shared Astro and Starlight reference UI for Sarj standards sites
 npm install --save-dev @sarj/docs-ui
 ```
 
-Rules and configuration are documented in the generated rule directory.
+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/).
 
-[Documentation](https://code-standards.sarj.ai/) · [Source](https://github.com/sarj-ai/code-standards)
+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://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.1.1",
+  "version": "0.3.1",
   "packageManager": "npm@12.0.2",
   "description": "Shared Astro and Starlight reference UI for Sarj standards sites",
   "type": "module",
@@ -9,8 +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": [
@@ -19,7 +23,8 @@
     "LICENSE"
   ],
   "sideEffects": [
-    "./src/styles/theme.css"
+    "./src/styles/theme.css",
+    "./src/styles/starlight.css"
   ],
   "publishConfig": {
     "access": "public"
@@ -29,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

@@ -0,0 +1,59 @@
+import type { BreadcrumbsProps, ReferencePageProps, RulePagerProps } from './contracts';
+
+export interface ComponentDefinition<Props extends object = object> {
+  exportPath: string;
+  purpose: string;
+  properties: Readonly<Record<keyof Props, string>>;
+}
+
+export interface ThemeTokenDefinition {
+  cssName: `--sarj-${string}`;
+  purpose: string;
+  light: `#${string}`;
+  dark: `#${string}`;
+}
+
+export const componentCatalog = Object.freeze({
+  Breadcrumbs: {
+    exportPath: '@sarj/docs-ui/Breadcrumbs.astro',
+    purpose: 'Show a compact, accessible path to the current reference page.',
+    properties: {
+      ancestors: 'Ordered links from the reference root to the current page.',
+      current: 'Current page label, announced with aria-current="page".',
+    },
+  } satisfies ComponentDefinition<BreadcrumbsProps>,
+  PageAnchor: {
+    exportPath: '@sarj/docs-ui/PageAnchor.astro',
+    purpose: 'Provide the focusable top anchor used by Starlight reference pages.',
+    properties: {},
+  } satisfies ComponentDefinition,
+  ReferencePage: {
+    exportPath: '@sarj/docs-ui/ReferencePage.astro',
+    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.',
+      indexable: 'Whether robots may index the public page; defaults to true.',
+      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.', 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

@@ -1,18 +1,10 @@
 ---
-interface Ancestor {
-  label: string;
-  href: string;
-}
-
-interface Props {
-  ancestors: readonly Ancestor[];
-  current: string;
-}
+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

@@ -1,29 +1,16 @@
 ---
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
-import type { StarlightUserConfig } from '@astrojs/starlight/types';
-
-type Sidebar = NonNullable<StarlightUserConfig['sidebar']>;
-type Discovery = 'searchable' | 'navigation-only' | 'unlisted';
-
-interface Props {
-  title: string;
-  description: string;
-  sidebar: Sidebar;
-  discovery?: Discovery;
-  hasSidebar?: boolean;
-  template?: 'doc' | 'splash';
-}
+import type { ReferencePageProps as Props } from '../contracts';
 
 const {
   title,
   description,
   sidebar,
-  discovery = 'searchable',
+  indexable: indexableProp,
   hasSidebar = true,
   template = 'doc',
 } = Astro.props;
-const pagefind = discovery === 'searchable';
-const noindex = discovery === 'unlisted';
+const indexable = indexableProp ?? true;
 ---
 
 <StarlightPage
@@ -31,15 +18,15 @@ const noindex = discovery === 'unlisted';
     title,
     description,
     template,
-    pagefind,
+    pagefind: false,
     prev: false,
     next: false,
-    head: noindex ? [{ tag: 'meta', attrs: { name: 'robots', content: 'noindex, nofollow' } }] : [],
+    head: indexable ? [] : [{ tag: 'meta', attrs: { name: 'robots', content: 'noindex, nofollow' } }],
   }}
   sidebar={sidebar}
   hasSidebar={hasSidebar}
 >
-  <div data-pagefind-body={pagefind ? true : undefined} data-pagefind-ignore={pagefind ? 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

@@ -0,0 +1,37 @@
+import type { StarlightUserConfig } from '@astrojs/starlight/types';
+
+/** One navigable ancestor rendered before the current page. */
+export interface BreadcrumbAncestor {
+  label: string;
+  href: string;
+}
+
+/** Public properties accepted by {@link Breadcrumbs}. */
+export interface BreadcrumbsProps {
+  ancestors: readonly BreadcrumbAncestor[];
+  current: string;
+}
+
+export interface RulePagerLink {
+  href: string;
+  label: string;
+}
+
+/** 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;
+  /** Allow search engines to index the page. Defaults to true. */
+  indexable?: boolean;
+  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

@@ -15,11 +15,18 @@
   --sl-color-gray-5: #dfe2e8;
   --sl-color-gray-6: #f1f2f5;
   --sl-color-black: #ffffff;
-  --report: #c34453;
-  --pass: #16806d;
-  --rule: #e4e6eb;
-  --paper: #ffffff;
-  --ink: #12141a;
+  --sarj-color-report: #c34453;
+  --sarj-color-pass: #16806d;
+  --sarj-color-warning: #986a00;
+  --sarj-color-rule: #e4e6eb;
+  --sarj-color-paper: #ffffff;
+  --sarj-color-ink: #12141a;
+  /* Compatibility aliases. Prefer the namespaced public tokens above. */
+  --report: var(--sarj-color-report);
+  --pass: var(--sarj-color-pass);
+  --rule: var(--sarj-color-rule);
+  --paper: var(--sarj-color-paper);
+  --ink: var(--sarj-color-ink);
 }
 
 :root[data-theme='dark'] {
@@ -34,9 +41,46 @@
   --sl-color-gray-5: #272b34;
   --sl-color-gray-6: #15171d;
   --sl-color-black: #0b0c10;
-  --report: #ff8794;
-  --pass: #62d5bd;
-  --rule: #272a32;
-  --paper: #0b0c10;
-  --ink: #f4f5f8;
+  --sarj-color-report: #ff8794;
+  --sarj-color-pass: #62d5bd;
+  --sarj-color-warning: #a97708;
+  --sarj-color-rule: #272a32;
+  --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;
 }