@sarj/docs-ui 0.1.1 → 0.2.0

package/README.md

@@ -8,6 +8,15 @@ 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/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/).
+
+Public exports:
+
+- `@sarj/docs-ui/Breadcrumbs.astro`
+- `@sarj/docs-ui/PageAnchor.astro`
+- `@sarj/docs-ui/ReferencePage.astro`
+- `@sarj/docs-ui/catalog`
+- `@sarj/docs-ui/contracts`
+- `@sarj/docs-ui/styles.css`
 
 [Documentation](https://code-standards.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.2.0",
   "packageManager": "npm@12.0.2",
   "description": "Shared Astro and Starlight reference UI for Sarj standards sites",
   "type": "module",
@@ -9,6 +9,8 @@
   },
   "exports": {
     "./styles.css": "./src/styles/theme.css",
+    "./catalog": "./src/catalog.ts",
+    "./contracts": "./src/contracts.ts",
     "./PageAnchor.astro": "./src/components/PageAnchor.astro",
     "./ReferencePage.astro": "./src/components/ReferencePage.astro",
     "./Breadcrumbs.astro": "./src/components/Breadcrumbs.astro"

package/src/catalog.ts

@@ -0,0 +1,51 @@
+import type { BreadcrumbsProps, ReferencePageProps } 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;
+}
+
+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 search and 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>,
+});
+
+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.' },
+] satisfies readonly ThemeTokenDefinition[]);

package/src/components/Breadcrumbs.astro

@@ -1,13 +1,5 @@
 ---
-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;
 ---

package/src/components/ReferencePage.astro

@@ -1,29 +1,19 @@
 ---
 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',
+  searchable: searchableProp,
+  indexable: indexableProp,
+  discovery,
   hasSidebar = true,
   template = 'doc',
 } = Astro.props;
-const pagefind = discovery === 'searchable';
-const noindex = discovery === 'unlisted';
+const searchable = searchableProp ?? (discovery === undefined || discovery === 'searchable');
+const indexable = indexableProp ?? discovery !== 'unlisted';
 ---
 
 <StarlightPage
@@ -31,15 +21,15 @@ const noindex = discovery === 'unlisted';
     title,
     description,
     template,
-    pagefind,
+    pagefind: searchable,
     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 data-pagefind-body={searchable ? true : undefined} data-pagefind-ignore={searchable ? undefined : true}>
     <slot />
   </div>
 </StarlightPage>

package/src/contracts.ts

@@ -0,0 +1,36 @@
+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 type ReferenceSidebar = NonNullable<StarlightUserConfig['sidebar']>;
+
+/**
+ * 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 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/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,10 @@
   --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;
 }