@lickle/docs 0.0.0-dev.1

package/src/ui/util/kind.ts

@@ -0,0 +1,120 @@
+/**
+ * String discriminants for everything we render. Server-side normalisation
+ * (in `scan.ts`) collapses callable variables to `function`, so the client
+ * can read `decl.kind` directly without runtime adjustment.
+ *
+ * Members like `'enum-member'`, `'property'`, … are not declarations but
+ * still appear in member listings and search hits.
+ */
+export type Kind =
+  | 'module'
+  | 'namespace'
+  | 'export'
+  | 'variable'
+  | 'function'
+  | 'class'
+  | 'interface'
+  | 'type-alias'
+  | 'enum'
+  | 'enum-member'
+  | 'property'
+  | 'method'
+  | 'parameter'
+  | 'signature'
+  | 'index-signature'
+  | 'record'
+  | 'unknown'
+
+const LABELS: Record<Kind, string> = {
+  module: 'module',
+  namespace: 'namespace',
+  export: 'export',
+  variable: 'variable',
+  function: 'function',
+  class: 'class',
+  interface: 'interface',
+  'type-alias': 'type',
+  enum: 'enum',
+  'enum-member': 'member',
+  property: 'property',
+  method: 'method',
+  parameter: 'parameter',
+  signature: 'signature',
+  'index-signature': 'index signature',
+  record: 'object',
+  unknown: 'unknown',
+}
+
+export const labelOf = (kind: Kind | string): string => LABELS[kind as Kind] ?? 'symbol'
+
+const SHORTS: Partial<Record<Kind, string>> = {
+  module: 'M',
+  namespace: 'N',
+  variable: 'V',
+  function: 'ƒ',
+  class: 'C',
+  interface: 'I',
+  'type-alias': 'T',
+  enum: 'E',
+  property: 'p',
+  method: 'm',
+}
+
+export const shortOf = (kind: Kind | string): string => SHORTS[kind as Kind] ?? '·'
+
+const ROUTABLE: ReadonlySet<Kind> = new Set([
+  'module',
+  'namespace',
+  'class',
+  'interface',
+  'function',
+  'variable',
+  'enum',
+  'type-alias',
+])
+
+export const isRoutable = (kind: Kind | string): boolean => ROUTABLE.has(kind as Kind)
+
+const PLURAL: Record<Kind, string> = {
+  module: 'modules',
+  namespace: 'namespaces',
+  export: 'exports',
+  variable: 'variables',
+  function: 'functions',
+  class: 'classes',
+  interface: 'interfaces',
+  'type-alias': 'types',
+  enum: 'enums',
+  'enum-member': 'members',
+  property: 'properties',
+  method: 'methods',
+  parameter: 'parameters',
+  signature: 'signatures',
+  'index-signature': 'index signatures',
+  record: 'objects',
+  unknown: 'unknown',
+}
+
+export const pluralLabel = (kind: Kind | string): string => PLURAL[kind as Kind] ?? `${labelOf(kind)}s`
+
+/**
+ * Canonical group ordering: functions → variables → types → everything else.
+ * Unknown titles sort to the end.
+ */
+const GROUP_ORDER = [
+  'modules',
+  'namespaces',
+  'functions',
+  'variables',
+  'types',
+  'classes',
+  'interfaces',
+  'enums',
+  'properties',
+  'methods',
+]
+
+export const groupOrder = (title: string): number => {
+  const i = GROUP_ORDER.indexOf(title.trim().toLowerCase())
+  return i < 0 ? GROUP_ORDER.length : i
+}

package/src/ui/util/markdown.ts

@@ -0,0 +1,74 @@
+import type { Highlighter } from 'shiki'
+import { Marked } from 'marked'
+
+let highlighterPromise: Promise<Highlighter> | null = null
+
+const LANGS = ['ts', 'tsx', 'js', 'jsx', 'json', 'bash', 'html', 'css', 'md']
+
+export const getHighlighter = (): Promise<Highlighter> => {
+  if (!highlighterPromise) {
+    highlighterPromise = import('shiki').then((s) =>
+      s.createHighlighter({ themes: ['github-light', 'github-dark'], langs: LANGS }),
+    )
+  }
+  return highlighterPromise
+}
+
+const escape = (s: string) =>
+  s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+
+export const langOf = (info: string | undefined) => {
+  const raw = (info ?? '').trim().split(/\s+/)[0]?.toLowerCase() ?? ''
+  if (!raw) return 'text'
+  if (LANGS.includes(raw)) return raw
+  if (raw === 'sh' || raw === 'zsh') return 'bash'
+  if (raw === 'typescript') return 'ts'
+  if (raw === 'javascript') return 'js'
+  return 'text'
+}
+
+/** Lookup for inline-code auto-linking. Receives the raw `code` text, returns a slug or undefined. */
+export type CodespanLookup = (raw: string) => string | undefined
+
+const ID = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/
+
+const buildMarked = (h: Highlighter | null, lookup?: CodespanLookup) => {
+  const m = new Marked({
+    gfm: true,
+    breaks: false,
+    renderer: {
+      code({ text, lang }) {
+        const language = langOf(lang)
+        if (h && language !== 'text') {
+          try {
+            return h.codeToHtml(text, {
+              lang: language,
+              themes: { light: 'github-light', dark: 'github-dark' },
+              defaultColor: false,
+            })
+          } catch {
+            /* fall through */
+          }
+        }
+        return `<pre class="codeblock"><code>${escape(text)}</code></pre>`
+      },
+      codespan({ text }) {
+        if (lookup && ID.test(text)) {
+          const slug = lookup(text)
+          if (slug) return `<a href="/${slug}" class="codelink"><code>${text}</code></a>`
+        }
+        return `<code>${text}</code>`
+      },
+    },
+  })
+  return m
+}
+
+export const renderMarkdown = async (src: string, lookup?: CodespanLookup): Promise<string> => {
+  const h = await getHighlighter().catch(() => null)
+  return buildMarked(h, lookup).parse(src) as string
+}
+
+export const renderMarkdownSync = (src: string, lookup?: CodespanLookup): string => {
+  return buildMarked(null, lookup).parse(src) as string
+}

package/src/ui/util/search.ts

@@ -0,0 +1,84 @@
+import { create, insert, search } from '@orama/orama'
+
+import { type Types } from '../context/index.ts'
+import { type Kind } from './kind.ts'
+
+export type SearchHit = { name: string; qualified: string; kind: Kind; slug: string; file: string }
+
+export type SearchEngine = { query: (term: string, limit?: number) => Promise<SearchHit[]> }
+
+/**
+ * Build an in-browser Orama index over every routed page in `project`.
+ * Names are boosted above qualified paths so exact-name hits rank first;
+ * `tolerance: 1` allows one-character typos. Each declaration is indexed once
+ * — re-export routes share a declaration id, so they're de-duplicated here.
+ */
+export const createSearchEngine = async (project: Types.Project): Promise<SearchEngine> => {
+  const db = await create({
+    // `terms` holds the name/qualified split into sub-words so `provider`
+    // matches `ProjectProvider` and `render error` matches `renderError`.
+    schema: { name: 'string', qualified: 'string', kind: 'string', slug: 'string', file: 'string', terms: 'string' },
+    components: { tokenizer: { stemming: false } },
+  })
+
+  const seen = new Set<number>()
+  const walk = async (routes: Types.RouteNode[]): Promise<void> => {
+    for (const r of routes) {
+      if (r.page.kind !== 'markdown' && !seen.has(r.page.id)) {
+        seen.add(r.page.id)
+        const decl = project.byId(r.page.id)
+        const kind = (decl?.kind ?? 'module') as Kind
+        await insert(db, {
+          name: r.label,
+          qualified: r.page.qualified,
+          kind,
+          slug: r.slug,
+          file: decl?.sources?.[0]?.file ?? '',
+          terms: termsOf(r.label, r.page.qualified),
+        })
+      }
+      await walk(r.children)
+    }
+  }
+  await walk(project.routes)
+
+  return {
+    query: async (term, limit = 20) => {
+      const t = term.trim()
+      if (!t) return []
+      const res = await search(db, {
+        term: t,
+        properties: ['name', 'qualified', 'terms'],
+        boost: { name: 3, qualified: 2, terms: 1 },
+        tolerance: 1,
+        limit,
+      })
+      return res.hits.map((h) => h.document as unknown as SearchHit)
+    },
+  }
+}
+
+/** Sub-words of the indexed strings, so partial / multi-word queries match. */
+const termsOf = (...sources: string[]): string => {
+  const words = new Set<string>()
+  for (const s of sources) for (const w of splitWords(s)) words.add(w)
+  return [...words].join(' ')
+}
+
+/**
+ * Split an identifier into lowercase words on separators and case boundaries:
+ * `getHTMLParser` -> `get html parser`, `render-error` -> `render error`,
+ * `a.b_c` -> `a b c`.
+ */
+const splitWords = (input: string): string[] =>
+  input
+    .split(/[\s._/\\-]+/)
+    .flatMap((part) =>
+      part
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .replace(/([A-Za-z])([0-9])/g, '$1 $2')
+        .split(/\s+/),
+    )
+    .map((w) => w.toLowerCase())
+    .filter(Boolean)

package/theme.css

@@ -0,0 +1,301 @@
+@import 'tailwindcss';
+@source './src';
+
+@theme inline {
+  --color-bg: var(--color-bg);
+  --color-panel: var(--color-panel);
+  --color-hover: var(--color-hover);
+  --color-line: var(--color-line);
+  --color-fg: var(--color-fg);
+  --color-mute: var(--color-mute);
+  --color-link: var(--color-link);
+  --color-accent: var(--color-accent);
+
+  /* Typography mapping to Tailwind v4 namespaces */
+  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  --font-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace;
+  --font-code: var(--font-mono);
+  --font-code-size: 0.85em;
+  --text-font-size: 15px;
+  --leading-line-height: 1.65;
+  --tracking-letter-spacing: -0.005em;
+}
+
+:root {
+  --color-bg: #ffffff;
+  --color-panel: #fafafa;
+  --color-hover: #f0f0f0;
+  --color-line: #e8e8e8;
+  --color-fg: #0a0a0a;
+  --color-mute: #6b6b6b;
+  --color-link: #0a0a0a;
+  --color-accent: #6f42c1;
+  --color-code-bg: #fafafa;
+  --color-error: #c5302a;
+  --color-error-bg: rgba(197, 48, 42, 0.06);
+}
+
+:root[data-theme='dark'] {
+  --color-bg: #0a0a0a;
+  --color-panel: #131313;
+  --color-hover: #1f1f1f;
+  --color-line: #1f1f1f;
+  --color-fg: #fafafa;
+  --color-mute: #a3a3a3;
+  --color-link: #fafafa;
+  --color-accent: #c4a8ff;
+  --color-code-bg: #131313;
+  --color-error: #fca5a5;
+  --color-error-bg: rgba(252, 165, 165, 0.08);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme='light']) {
+    --color-bg: #0a0a0a;
+    --color-panel: #131313;
+    --color-hover: #1f1f1f;
+    --color-line: #1f1f1f;
+    --color-fg: #fafafa;
+    --color-mute: #a3a3a3;
+    --color-link: #fafafa;
+    --color-accent: #c4a8ff;
+    --color-code-bg: #131313;
+    --color-error: #fca5a5;
+    --color-error-bg: rgba(252, 165, 165, 0.08);
+  }
+}
+
+@layer base {
+  html,
+  body {
+    background: var(--color-bg);
+    color: var(--color-fg);
+  }
+  html {
+    font-feature-settings: 'cv11', 'ss01', 'ss03';
+  }
+  body {
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    font-size: var(--text-font-size);
+    line-height: var(--leading-line-height);
+    letter-spacing: var(--tracking-letter-spacing);
+  }
+  @supports (font-variation-settings: normal) {
+    body {
+      font-family:
+        'Inter var',
+        -apple-system,
+        BlinkMacSystemFont,
+        sans-serif;
+    }
+  }
+  code,
+  pre,
+  kbd {
+    font-family: var(--font-mono);
+    font-feature-settings:
+      'liga' 0,
+      'calt' 0;
+  }
+  * {
+    scrollbar-width: thin;
+    scrollbar-color: var(--color-line) transparent;
+  }
+}
+
+@layer components {
+  code, pre {
+    background: transparent !important;
+    padding: 0;
+    margin: 0;
+    border: 0;
+  }
+
+  code {
+    font-family: var(--font-code);
+    font-size: var(--font-code-size);
+    white-space: pre-wrap;
+    tab-size: 2;
+  }
+
+  code,
+  code span {
+    color: var(--shiki-light);
+    font-style: var(--shiki-light-font-style);
+    font-weight: var(--shiki-light-font-weight);
+    text-decoration: var(--shiki-light-text-decoration);
+  }
+  :root[data-theme='dark'] code,
+  :root[data-theme='dark'] code span {
+    color: var(--shiki-dark) !important;
+    font-style: var(--shiki-dark-font-style) !important;
+    font-weight: var(--shiki-dark-font-weight) !important;
+    text-decoration: var(--shiki-dark-text-decoration) !important;
+  }
+
+  .codeblock {
+    background: var(--color-code-bg);
+    border: 1px solid var(--color-line);
+    border-radius: 8px;
+    padding: 14px 16px;
+  }
+  .codeblock:focus-within {
+    border-color: var(--color-mute);
+  }
+}
+
+/* Syntax highlighting */
+@layer components {
+  .shiki,
+  .shiki span {
+    color: var(--shiki-light);
+    font-style: var(--shiki-light-font-style);
+    font-weight: var(--shiki-light-font-weight);
+    text-decoration: var(--shiki-light-text-decoration);
+  }
+  :root[data-theme='dark'] .shiki,
+  :root[data-theme='dark'] .shiki span {
+    color: var(--shiki-dark) !important;
+    font-style: var(--shiki-dark-font-style) !important;
+    font-weight: var(--shiki-dark-font-weight) !important;
+    text-decoration: var(--shiki-dark-text-decoration) !important;
+  }
+}
+
+@layer components {
+  .markdown {
+    color: var(--color-fg);
+  }
+  .markdown.markdown-tight > :first-child {
+    margin-top: 0;
+  }
+  .markdown.markdown-tight > :last-child {
+    margin-bottom: 0;
+  }
+
+  .markdown h1 {
+    font-weight: 600;
+    font-size: 1.875rem;
+    margin: 0 0 1rem 0;
+    letter-spacing: -0.02em;
+  }
+  .markdown h2 {
+    font-weight: 600;
+    font-size: 1.4rem;
+    margin: 2.5rem 0 0.75rem 0;
+    padding-bottom: 0.25rem;
+    border-bottom: 1px solid var(--color-line);
+    letter-spacing: -0.02em;
+  }
+  .markdown h3 {
+    font-weight: 600;
+    font-size: 1.1rem;
+    margin: 2rem 0 0.5rem 0;
+    letter-spacing: -0.01em;
+  }
+  .markdown h4 {
+    font-weight: 600;
+    font-size: 0.78rem;
+    margin: 1.5rem 0 0.5rem 0;
+    color: var(--color-mute);
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+  }
+  .markdown p {
+    margin: 1rem 0;
+  }
+  .markdown ul {
+    list-style: disc;
+    padding-left: 1.5rem;
+    margin: 1rem 0;
+  }
+  .markdown ol {
+    list-style: decimal;
+    padding-left: 1.5rem;
+    margin: 1rem 0;
+  }
+  .markdown li {
+    margin: 0.25rem 0;
+  }
+  .markdown blockquote {
+    border-left: 2px solid var(--color-line);
+    padding-left: 1rem;
+    color: var(--color-mute);
+    font-style: italic;
+    margin: 1rem 0;
+  }
+  .markdown a {
+    text-decoration: underline;
+    text-decoration-color: var(--color-line);
+    text-underline-offset: 3px;
+    text-decoration-thickness: 1px;
+    font-weight: 500;
+    transition: opacity 150ms;
+  }
+  .markdown a:hover {
+    opacity: 0.7;
+  }
+  .markdown :not(pre) > code {
+    background: var(--color-code-bg);
+    border: 1px solid var(--color-line);
+    border-radius: 4px;
+    padding: 0 5px;
+    font-size: 0.85em;
+  }
+  .markdown a.codelink {
+    text-decoration: none;
+  }
+  .markdown a.codelink > code {
+    border-color: var(--color-mute);
+    transition:
+      color 150ms,
+      border-color 150ms;
+  }
+  .markdown a.codelink:hover > code {
+    color: var(--color-accent);
+    border-color: var(--color-accent);
+  }
+  .markdown pre {
+    background: var(--color-code-bg);
+    border: 1px solid var(--color-line);
+    border-radius: 8px;
+    padding: 14px 16px;
+    overflow-x: auto;
+    margin: 1.25rem 0;
+  }
+  .markdown pre code {
+    background: transparent;
+    border: none;
+    padding: 0;
+  }
+  .markdown table {
+    font-size: 0.9em;
+    margin: 1.25rem 0;
+    border-collapse: collapse;
+  }
+  .markdown th,
+  .markdown td {
+    border: 1px solid var(--color-line);
+    padding: 0.375rem 0.625rem;
+  }
+  .markdown th {
+    background: var(--color-panel);
+    font-weight: 600;
+    text-align: left;
+  }
+  .markdown hr {
+    border: 0;
+    border-top: 1px solid var(--color-line);
+    margin: 2rem 0;
+  }
+  /* Tailwind preflight forces `img { display: block }`; restore inline flow so
+     badge rows (shields-style image links separated by whitespace) sit
+     side-by-side instead of stacking. */
+  .markdown img {
+    display: inline-block;
+    vertical-align: middle;
+    max-width: 100%;
+    border-radius: 4px;
+  }
+}

package/tsconfig.client.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "lib": ["DOM"],
+    "types": ["@lickle/docs/client"],
+    "jsx": "preserve",
+    "jsxImportSource": "@lickle/docs/solidjs",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  }
+}