@imolko/create-ultra-reporter 2.1.23-beta

package/templates/documentation/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "documentation",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids",
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/preset-classic": "3.9.2",
+    "@docusaurus/theme-mermaid": "3.9.2",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "mermaid": "11.12.1",
+    "prism-react-renderer": "^2.3.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "3.9.2",
+    "@docusaurus/tsconfig": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "typescript": "~5.9.3"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 3 chrome version",
+      "last 3 firefox version",
+      "last 5 safari version"
+    ]
+  },
+  "engines": {
+    "node": ">=20.0"
+  }
+}

package/templates/documentation/sidebars.ts

@@ -0,0 +1,33 @@
+import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
+/**
+ * Creating a sidebar enables you to:
+ - create an ordered group of docs
+ - render a sidebar for each doc of that group
+ - provide next/previous navigation
+
+ The sidebars can be generated from the filesystem, or explicitly defined here.
+
+ Create as many sidebars as you want.
+ */
+const sidebars: SidebarsConfig = {
+  // By default, Docusaurus generates a sidebar from the docs folder structure
+  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
+
+  // But you can create a sidebar manually
+  /*
+  tutorialSidebar: [
+    'intro',
+    'hello',
+    {
+      type: 'category',
+      label: 'Tutorial',
+      items: ['tutorial-basics/create-a-document'],
+    },
+  ],
+   */
+};
+
+export default sidebars;

package/templates/documentation/src/components/ArtifactTable/FilterBar.tsx

@@ -0,0 +1,185 @@
+import React, { useState, useRef, useEffect, useCallback } from 'react';
+import type { FilterState } from './types';
+import styles from './styles.module.css';
+
+interface FilterBarProps {
+  filters: FilterState;
+  availableTypes: string[];
+  availableContexts: string[];
+  onFilterChange: (updates: Partial<FilterState>) => void;
+  onClearFilters: () => void;
+  totalResults: number;
+}
+
+/**
+ * Debounce hook — delays updating a value until `delay` ms of inactivity.
+ */
+function useDebouncedValue<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debounced;
+}
+
+/**
+ * Filter bar with text inputs, a multi-select type dropdown, and a
+ * single-select contextName dropdown.
+ */
+export default function FilterBar({
+  filters,
+  availableTypes,
+  availableContexts,
+  onFilterChange,
+  onClearFilters,
+  totalResults,
+}: FilterBarProps): JSX.Element {
+  // Local state for text inputs (debounced before propagating)
+  const [localName, setLocalName] = useState(filters.nameQuery);
+  const [localTags, setLocalTags] = useState(filters.tagsQuery);
+
+  const debouncedName = useDebouncedValue(localName, 250);
+  const debouncedTags = useDebouncedValue(localTags, 250);
+
+  // Sync debounced values upward
+  useEffect(() => {
+    onFilterChange({ nameQuery: debouncedName });
+  }, [debouncedName]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(() => {
+    onFilterChange({ tagsQuery: debouncedTags });
+  }, [debouncedTags]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Sync from parent (e.g. URL restore)
+  useEffect(() => {
+    setLocalName(filters.nameQuery);
+    setLocalTags(filters.tagsQuery);
+  }, [filters.nameQuery, filters.tagsQuery]);
+
+  // Multi-select dropdown state
+  const [typeDropdownOpen, setTypeDropdownOpen] = useState(false);
+  const typeDropdownRef = useRef<HTMLDivElement>(null);
+
+  // Close dropdown on outside click
+  useEffect(() => {
+    function handleClickOutside(event: MouseEvent) {
+      if (
+        typeDropdownRef.current &&
+        !typeDropdownRef.current.contains(event.target as Node)
+      ) {
+        setTypeDropdownOpen(false);
+      }
+    }
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, []);
+
+  const toggleType = useCallback(
+    (type: string) => {
+      const next = filters.selectedTypes.includes(type)
+        ? filters.selectedTypes.filter((t) => t !== type)
+        : [...filters.selectedTypes, type];
+      onFilterChange({ selectedTypes: next });
+    },
+    [filters.selectedTypes, onFilterChange],
+  );
+
+  const hasActiveFilters =
+    filters.nameQuery !== '' ||
+    filters.tagsQuery !== '' ||
+    filters.selectedTypes.length > 0 ||
+    filters.selectedContext !== '';
+
+  return (
+    <div className={styles.filterBar}>
+      <div className={styles.filterGroup}>
+        <input
+          type="text"
+          className={styles.filterInput}
+          placeholder="Search by name..."
+          value={localName}
+          onChange={(e) => setLocalName(e.target.value)}
+          aria-label="Filter by artifact name"
+        />
+      </div>
+
+      <div className={styles.filterGroup}>
+        <input
+          type="text"
+          className={styles.filterInput}
+          placeholder="Search by tags..."
+          value={localTags}
+          onChange={(e) => setLocalTags(e.target.value)}
+          aria-label="Filter by tags"
+        />
+      </div>
+
+      <div className={styles.filterGroup} ref={typeDropdownRef}>
+        <button
+          type="button"
+          className={styles.multiSelectToggle}
+          onClick={() => setTypeDropdownOpen(!typeDropdownOpen)}
+          aria-expanded={typeDropdownOpen}
+          aria-haspopup="listbox"
+        >
+          Type
+          {filters.selectedTypes.length > 0 && (
+            <span className={styles.multiSelectBadge}>
+              {filters.selectedTypes.length}
+            </span>
+          )}
+          <span className={styles.dropdownArrow}>▾</span>
+        </button>
+        {typeDropdownOpen && (
+          <div className={styles.multiSelectDropdown} role="listbox" aria-multiselectable="true">
+            {availableTypes.map((type) => (
+              <label key={type} className={styles.multiSelectOption}>
+                <input
+                  type="checkbox"
+                  checked={filters.selectedTypes.includes(type)}
+                  onChange={() => toggleType(type)}
+                />
+                <span>{type}</span>
+              </label>
+            ))}
+          </div>
+        )}
+      </div>
+
+      <div className={styles.filterGroup}>
+        <select
+          className={styles.filterSelect}
+          value={filters.selectedContext}
+          onChange={(e) =>
+            onFilterChange({ selectedContext: e.target.value })
+          }
+          aria-label="Filter by context"
+        >
+          <option value="">All contexts</option>
+          {availableContexts.map((ctx) => (
+            <option key={ctx} value={ctx}>
+              {ctx}
+            </option>
+          ))}
+        </select>
+      </div>
+
+      {hasActiveFilters && (
+        <button
+          type="button"
+          className={styles.clearFiltersButton}
+          onClick={onClearFilters}
+        >
+          Clear filters
+        </button>
+      )}
+
+      <span className={styles.resultCount}>
+        {totalResults} artifact{totalResults !== 1 ? 's' : ''}
+      </span>
+    </div>
+  );
+}

package/templates/documentation/src/components/ArtifactTable/index.tsx

@@ -0,0 +1,298 @@
+import React, { useEffect, useState, useMemo, useCallback } from 'react';
+import FilterBar from './FilterBar';
+import type { ArtifactEntry, FilterState, SortColumn, SortDirection } from './types';
+import styles from './styles.module.css';
+
+interface ArtifactTableProps {
+  category: 'domain-artifacts' | 'aggregates';
+}
+
+/** All available columns sorted by their position in the table. */
+const COLUMNS: { key: SortColumn | 'contextName' | 'tags' | 'description'; label: string }[] = [
+  { key: 'name', label: 'Name' },
+  { key: 'type', label: 'Type' },
+  { key: 'contextName', label: 'Context' },
+  { key: 'tags', label: 'Tags' },
+  { key: 'description', label: 'Description' },
+];
+
+const MANIFEST_URL = '/data/artifacts-manifest.json';
+const DESCRIPTION_MAX_LENGTH = 120;
+
+function readFiltersFromURL(): Partial<FilterState> {
+  if (typeof window === 'undefined') return {};
+  const params = new URLSearchParams(window.location.search);
+  const result: Partial<FilterState> = {};
+  const name = params.get('name');
+  const tags = params.get('tags');
+  const type = params.get('type');
+  const context = params.get('context');
+  if (name) result.nameQuery = name;
+  if (tags) result.tagsQuery = tags;
+  if (type) result.selectedTypes = type.split(',');
+  if (context) result.selectedContext = context;
+  return result;
+}
+
+function writeFiltersToURL(filters: FilterState): void {
+  if (typeof window === 'undefined') return;
+  const params = new URLSearchParams();
+  if (filters.nameQuery) params.set('name', filters.nameQuery);
+  if (filters.tagsQuery) params.set('tags', filters.tagsQuery);
+  if (filters.selectedTypes.length > 0) params.set('type', filters.selectedTypes.join(','));
+  if (filters.selectedContext) params.set('context', filters.selectedContext);
+  const qs = params.toString();
+  const url = qs ? `${window.location.pathname}?${qs}` : window.location.pathname;
+  window.history.replaceState(null, '', url);
+}
+
+type ViewState = 'loading' | 'ready' | 'error';
+
+/**
+ * Main component: fetches the artifact manifest, filters by category,
+ * and renders a sortable, filterable table.
+ */
+export default function ArtifactTable({ category }: ArtifactTableProps): JSX.Element {
+  const [artifacts, setArtifacts] = useState<ArtifactEntry[]>([]);
+  const [viewState, setViewState] = useState<ViewState>('loading');
+
+  // ---- Fetch manifest ----
+  useEffect(() => {
+    let cancelled = false;
+    async function fetchManifest() {
+      try {
+        const res = await fetch(MANIFEST_URL);
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const data: ArtifactEntry[] = await res.json();
+        if (!cancelled) {
+          setArtifacts(data);
+          setViewState('ready');
+        }
+      } catch {
+        if (!cancelled) setViewState('error');
+      }
+    }
+    fetchManifest();
+    return () => { cancelled = true; };
+  }, []);
+
+  // ---- Derived data ----
+  const categoryArtifacts = useMemo(
+    () => artifacts.filter((a) => a.categories.includes(category)),
+    [artifacts, category],
+  );
+
+  const availableTypes = useMemo(
+    () => [...new Set(categoryArtifacts.map((a) => a.type))].sort(),
+    [categoryArtifacts],
+  );
+
+  const availableContexts = useMemo(
+    () => [...new Set(categoryArtifacts.map((a) => a.contextName))].sort(),
+    [categoryArtifacts],
+  );
+
+  // ---- Filter state (initialised from URL) ----
+  const [filters, setFilters] = useState<FilterState>(() => ({
+    nameQuery: '',
+    tagsQuery: '',
+    selectedTypes: [],
+    selectedContext: '',
+    ...readFiltersFromURL(),
+  }));
+
+  // Sync filters to URL
+  useEffect(() => {
+    writeFiltersToURL(filters);
+  }, [filters]);
+
+  const updateFilters = useCallback((updates: Partial<FilterState>) => {
+    setFilters((prev) => ({ ...prev, ...updates }));
+  }, []);
+
+  const clearFilters = useCallback(() => {
+    setFilters({ nameQuery: '', tagsQuery: '', selectedTypes: [], selectedContext: '' });
+  }, []);
+
+  // ---- Filtered data ----
+  const filtered = useMemo(() => {
+    return categoryArtifacts.filter((a) => {
+      if (filters.nameQuery && !a.name.toLowerCase().includes(filters.nameQuery.toLowerCase())) {
+        return false;
+      }
+      if (filters.tagsQuery && !a.tags.some((t) => t.toLowerCase().includes(filters.tagsQuery.toLowerCase()))) {
+        return false;
+      }
+      if (filters.selectedTypes.length > 0 && !filters.selectedTypes.includes(a.type)) {
+        return false;
+      }
+      if (filters.selectedContext && a.contextName !== filters.selectedContext) {
+        return false;
+      }
+      return true;
+    });
+  }, [categoryArtifacts, filters]);
+
+  // ---- Sorting ----
+  const [sort, setSort] = useState<{ column: SortColumn; direction: SortDirection }>({
+    column: 'name',
+    direction: 'asc',
+  });
+
+  const sorted = useMemo(() => {
+    const dir = sort.direction === 'asc' ? 1 : -1;
+    return [...filtered].sort((a, b) => {
+      const aVal = a[sort.column].toLowerCase();
+      const bVal = b[sort.column].toLowerCase();
+      if (aVal < bVal) return -1 * dir;
+      if (aVal > bVal) return 1 * dir;
+      return 0;
+    });
+  }, [filtered, sort]);
+
+  const toggleSort = useCallback((column: SortColumn) => {
+    setSort((prev) => ({
+      column,
+      direction: prev.column === column && prev.direction === 'asc' ? 'desc' : 'asc',
+    }));
+  }, []);
+
+  // ---- Render helpers ----
+  function renderSortIndicator(col: SortColumn): string {
+    if (col !== sort.column) return '';
+    return sort.direction === 'asc' ? ' ▲' : ' ▼';
+  }
+
+  function renderCell(artifact: ArtifactEntry, col: (typeof COLUMNS)[number]): React.ReactNode {
+    switch (col.key) {
+      case 'name':
+        return <a href={`./${artifact.idMarkdown}`}>{artifact.name}</a>;
+      case 'type':
+        return artifact.type;
+      case 'contextName':
+        return artifact.contextName;
+      case 'tags':
+        return (
+          <span className={styles.tagList}>
+            {artifact.tags.length > 0
+              ? artifact.tags.map((tag) => (
+                  <span key={tag} className={styles.tagChip}>{tag}</span>
+                ))
+              : '—'}
+          </span>
+        );
+      case 'description':
+        return (
+          <span className={styles.descriptionCell} title={artifact.description || undefined}>
+            {artifact.description
+              ? artifact.description.length > DESCRIPTION_MAX_LENGTH
+                ? artifact.description.slice(0, DESCRIPTION_MAX_LENGTH) + '…'
+                : artifact.description
+              : '—'}
+          </span>
+        );
+      default:
+        return null;
+    }
+  }
+
+  // ---- Error state ----
+  if (viewState === 'error') {
+    return (
+      <div className={styles.errorState}>
+        <p>Could not load artifact data. Please try refreshing the page.</p>
+      </div>
+    );
+  }
+
+  // ---- Loading state ----
+  if (viewState === 'loading') {
+    return (
+      <div className={styles.tableContainer}>
+        <table className={`table ${styles.table}`}>
+          <thead>
+            <tr>
+              {COLUMNS.map((col) => (
+                <th key={col.key}>{col.label}</th>
+              ))}
+            </tr>
+          </thead>
+          <tbody>
+            {[1, 2, 3, 4].map((i) => (
+              <tr key={i}>
+                {COLUMNS.map((col) => (
+                  <td key={col.key}>
+                    <div className={styles.skeleton}>&nbsp;</div>
+                  </td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    );
+  }
+
+  // ---- Ready state ----
+  return (
+    <div>
+      <FilterBar
+        filters={filters}
+        availableTypes={availableTypes}
+        availableContexts={availableContexts}
+        onFilterChange={updateFilters}
+        onClearFilters={clearFilters}
+        totalResults={sorted.length}
+      />
+
+      {sorted.length === 0 && filtered.length === 0 && categoryArtifacts.length > 0 ? (
+        <div className={styles.emptyState}>
+          <p>No artifacts match your filters.</p>
+          <button type="button" className={styles.clearFiltersButton} onClick={clearFilters}>
+            Clear filters
+          </button>
+        </div>
+      ) : sorted.length === 0 ? (
+        <div className={styles.emptyState}>
+          <p>No artifacts found for this category.</p>
+        </div>
+      ) : (
+        <div className={styles.tableContainer}>
+          <table className={`table ${styles.table}`}>
+            <thead>
+              <tr>
+                {COLUMNS.map((col) => (
+                  <th key={col.key}>
+                    {col.key === 'name' || col.key === 'type' ? (
+                      <button
+                        type="button"
+                        className={styles.sortableHeader}
+                        onClick={() => toggleSort(col.key as SortColumn)}
+                      >
+                        {col.label}
+                        <span className={styles.sortIndicator}>
+                          {renderSortIndicator(col.key as SortColumn)}
+                        </span>
+                      </button>
+                    ) : (
+                      col.label
+                    )}
+                  </th>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {sorted.map((artifact) => (
+                <tr key={`${artifact.contextName}-${artifact.idMarkdown}`}>
+                  {COLUMNS.map((col) => (
+                    <td key={col.key}>{renderCell(artifact, col)}</td>
+                  ))}
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </div>
+  );
+}