@orbytes/astrolab 0.3.0

package/src/core/options.ts

@@ -0,0 +1,262 @@
+// Vendored from astrobook 0.13.3 (options.ts) — see ./LICENSE-astrobook.
+//
+// Divergence: rewritten in plain TypeScript. Upstream declares these options as a schema for a
+// validation library that weighs 1.8 MB and has this one caller (named in LICENSE-astrobook
+// § divergence 4), so the schema is unrolled here by hand. Every option name, every default, the
+// `home: false` → empty-component transform and the resolved shape are unchanged, and the thrown
+// message keeps upstream's layout so a mistake in a site's astro.config reads the same:
+//
+//     Invalid Astrobook options:
+//     × Invalid type: Expected string but received 111
+//       → at directory
+//
+// Divergence: the three component defaults are absolute paths into ./lib-paths.ts rather than bare
+// `astrobook/...` ids — see that file for why.
+import type { IntegrationOptions } from '../types/types.ts'
+
+import {
+  EMPTY_COMPONENT,
+  HEAD_COMPONENT,
+  HOME_COMPONENT,
+} from './lib-paths.ts'
+
+/**
+ * The upstream Astrobook version, inlined.
+ *
+ * It is the default label of the home page's version badge, whose default href is Astrobook's own
+ * CHANGELOG — so this package's version would be the wrong number to print beside it. It is only
+ * ever rendered by Astrobook's built-in home, which the lab replaces with its own.
+ */
+const ASTROBOOK_VERSION = '0.13.3'
+
+const DEFAULT_VERSION_HREF =
+  'https://github.com/ocavue/astrobook/blob/master/packages/astrobook/CHANGELOG.md'
+const DEFAULT_REPO_HREF = 'https://github.com/ocavue/astrobook'
+
+export interface ResolvedOptions {
+  directory: string
+  subpath: string
+  dashboardSubpath: string
+  previewSubpath: string
+  title: string
+  css: string[]
+  head: string
+  home: string
+  homeContent: {
+    title: string | false
+    subtitle: string | false
+    version: { href: string; label: string } | false
+    repo: { href: string; label: string } | false
+  }
+}
+
+/** One collected problem, in the shape upstream's validator summarised them. */
+interface Issue {
+  message: string
+  path: string
+}
+
+/** How upstream's validator rendered the value it received, so the message reads the same. */
+function stringify(value: unknown): string {
+  switch (typeof value) {
+    case 'string':
+      return `"${value}"`
+    case 'number':
+    case 'bigint':
+    case 'boolean':
+      return String(value)
+    case 'symbol':
+    case 'function':
+      return value.toString()
+    case 'object':
+      return value === null ? 'null' : Array.isArray(value) ? 'Array' : 'Object'
+    default:
+      return 'undefined'
+  }
+}
+
+function typeIssue(expected: string, value: unknown, path: string): Issue {
+  return {
+    message: `Invalid type: Expected ${expected} but received ${stringify(value)}`,
+    path,
+  }
+}
+
+function readString(
+  value: unknown,
+  fallback: string,
+  path: string,
+  issues: Issue[],
+): string {
+  if (value === undefined) return fallback
+  if (typeof value !== 'string') {
+    issues.push(typeIssue('string', value, path))
+    return fallback
+  }
+  return value
+}
+
+function readStringArray(
+  value: unknown,
+  path: string,
+  issues: Issue[],
+): string[] {
+  if (value === undefined) return []
+  if (!Array.isArray(value)) {
+    issues.push(typeIssue('Array', value, path))
+    return []
+  }
+  const result: string[] = []
+  value.forEach((item, index) => {
+    if (typeof item !== 'string') {
+      issues.push(typeIssue('string', item, `${path}.${index}`))
+      return
+    }
+    result.push(item)
+  })
+  return result
+}
+
+/** A `string | false` field of `homeContent`. */
+function readStringOrFalse(
+  value: unknown,
+  fallback: string,
+  path: string,
+  issues: Issue[],
+): string | false {
+  if (value === undefined) return fallback
+  if (value === false) return false
+  if (typeof value !== 'string') {
+    issues.push(typeIssue('(string | false)', value, path))
+    return fallback
+  }
+  return value
+}
+
+/** A `{ href, label } | false` badge of `homeContent`. */
+function readBadge(
+  value: unknown,
+  defaults: { href: string; label: string },
+  path: string,
+  issues: Issue[],
+): { href: string; label: string } | false {
+  if (value === undefined) return { ...defaults }
+  if (value === false) return false
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    issues.push(typeIssue('(Object | false)', value, path))
+    return { ...defaults }
+  }
+  const badge = value as Record<string, unknown>
+  return {
+    href: readString(badge['href'], defaults.href, `${path}.href`, issues),
+    label: readString(badge['label'], defaults.label, `${path}.label`, issues),
+  }
+}
+
+function readHomeContent(
+  value: unknown,
+  issues: Issue[],
+): ResolvedOptions['homeContent'] {
+  let content: Record<string, unknown> = {}
+  if (value !== undefined) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      issues.push(typeIssue('Object', value, 'homeContent'))
+    } else {
+      content = value as Record<string, unknown>
+    }
+  }
+
+  return {
+    title: readStringOrFalse(
+      content['title'],
+      'Astrobook',
+      'homeContent.title',
+      issues,
+    ),
+    subtitle: readStringOrFalse(
+      content['subtitle'],
+      'The minimal UI component playground',
+      'homeContent.subtitle',
+      issues,
+    ),
+    version: readBadge(
+      content['version'],
+      { href: DEFAULT_VERSION_HREF, label: `v${ASTROBOOK_VERSION}` },
+      'homeContent.version',
+      issues,
+    ),
+    repo: readBadge(
+      content['repo'],
+      { href: DEFAULT_REPO_HREF, label: 'Star on GitHub' },
+      'homeContent.repo',
+      issues,
+    ),
+  }
+}
+
+/**
+ * `home` takes a component path, or `false` for a home page that renders nothing. Upstream folds
+ * the `false` case into the resolved path here so nothing downstream has to know about it.
+ */
+function readHome(value: unknown, issues: Issue[]): string {
+  if (value === undefined) return HOME_COMPONENT
+  if (value === false) return EMPTY_COMPONENT
+  if (typeof value !== 'string') {
+    issues.push(typeIssue('(string | false)', value, 'home'))
+    return HOME_COMPONENT
+  }
+  if (value.length === 0) {
+    issues.push({
+      message: 'Invalid length: Expected >=1 but received 0',
+      path: 'home',
+    })
+    return HOME_COMPONENT
+  }
+  return value
+}
+
+export function resolveOptions(options?: IntegrationOptions): ResolvedOptions {
+  const issues: Issue[] = []
+
+  let input: Record<string, unknown> = {}
+  if (options !== undefined) {
+    if (typeof options !== 'object' || options === null) {
+      issues.push(typeIssue('Object', options, ''))
+    } else {
+      input = options as unknown as Record<string, unknown>
+    }
+  }
+
+  const resolved: ResolvedOptions = {
+    directory: readString(input['directory'], '.', 'directory', issues),
+    subpath: readString(input['subpath'], '', 'subpath', issues),
+    dashboardSubpath: readString(
+      input['dashboardSubpath'],
+      'dashboard',
+      'dashboardSubpath',
+      issues,
+    ),
+    previewSubpath: readString(
+      input['previewSubpath'],
+      'stories',
+      'previewSubpath',
+      issues,
+    ),
+    title: readString(input['title'], 'Astrobook', 'title', issues),
+    css: readStringArray(input['css'], 'css', issues),
+    head: readString(input['head'], HEAD_COMPONENT, 'head', issues),
+    home: readHome(input['home'], issues),
+    homeContent: readHomeContent(input['homeContent'], issues),
+  }
+
+  if (issues.length > 0) {
+    const summary = issues
+      .map((issue) =>
+        issue.path ? `× ${issue.message}\n  → at ${issue.path}` : `× ${issue.message}`,
+      )
+      .join('\n')
+    throw new Error(`Invalid Astrobook options:\n${summary}`)
+  }
+
+  return resolved
+}

package/src/core/utils/get-exports.ts

@@ -0,0 +1,59 @@
+import { tsPlugin } from '@sveltejs/acorn-typescript'
+import { Parser } from 'acorn'
+
+/**
+ * Parses the content of the given file and returns all its exports
+ */
+export function getExports(code: string): string[] {
+  // Parse the code into an AST
+  const parser = Parser.extend(
+    tsPlugin({
+      dts: false,
+      jsx: {
+        allowNamespaces: true,
+        allowNamespacedObjects: true,
+      },
+    }),
+  )
+  const ast = parser.parse(code, {
+    sourceType: 'module',
+    ecmaVersion: 'latest',
+    allowImportExportEverywhere: true,
+    locations: true,
+  })
+
+  const exports = new Set<string>()
+
+  // Walk through the AST
+  for (const node of ast.body) {
+    if (node.type === 'ExportNamedDeclaration') {
+      for (const specifier of node.specifiers) {
+        const { exported } = specifier
+        if (exported.type === 'Identifier') {
+          exports.add(exported.name)
+        }
+      }
+
+      const { declaration } = node
+      if (declaration?.type === 'VariableDeclaration') {
+        const { declarations } = declaration
+        for (const declaration of declarations) {
+          const id = declaration.id
+          if (id.type === 'Identifier') {
+            exports.add(id.name)
+          }
+        }
+      }
+      if (declaration?.type === 'FunctionDeclaration') {
+        exports.add(declaration.id.name)
+      }
+      if (declaration?.type === 'ClassDeclaration') {
+        exports.add(declaration.id.name)
+      }
+    } else if (node.type === 'ExportDefaultDeclaration') {
+      exports.add('default')
+    }
+  }
+
+  return Array.from(exports).sort()
+}

package/src/core/utils/invariant.ts

@@ -0,0 +1,13 @@
+import assert from 'node:assert'
+
+export function invariant(
+  condition: unknown,
+  message = 'Unexpected invariant violation',
+): asserts condition {
+  if (!condition) {
+    assert(
+      condition,
+      `[astrobook] Unexpected internal error. Please open an issue at https://github.com/ocavue/astrobook/issues. ${message}`,
+    )
+  }
+}

package/src/core/utils/kebab-case.ts

@@ -0,0 +1,30 @@
+// just-kebab-case@4.2.0, inlined.
+//
+// Upstream's get-story-modules.ts imports `just-kebab-case`, but @astrobook/core declares it as a
+// DEV dependency only: tsdown bundles the function into the published dist, so the package never
+// installs it. This package ships source with no bundler, so the function has to come from
+// somewhere — and it decides every story id, which is what lab URLs and the cull/responsive
+// mark files are keyed on. The three regexes below were extracted from the bundle that shipped in
+// @astrobook/core 0.13.3 (dist/index.js, its `just-kebab-case@4.2.0` region) so the ids cannot
+// drift.
+//
+// MIT, Copyright (c) 2016 Angus Croll — https://github.com/angus-c/just
+
+const wordSeparators = /[\s\u2000-\u206F\u2E00-\u2E7F\\'!"#$%&()*+,\-.\/:;<=>?@\[\]^_`{|}~]+/
+const capital_plus_lower = /[A-ZÀ-Ý\u00C0-\u00D6\u00D9-\u00DD][a-zà-ÿ]/g
+const capitals = /[A-ZÀ-Ý\u00C0-\u00D6\u00D9-\u00DD]+/g
+
+export default function kebabCase(str: string): string {
+  str = str.replace(capital_plus_lower, function (match) {
+    return ' ' + (match[0].toLowerCase() || match[0]) + match[1]
+  })
+  str = str.replace(capitals, function (match) {
+    return ' ' + match.toLowerCase()
+  })
+  return str
+    .trim()
+    .split(wordSeparators)
+    .join('-')
+    .replace(/^-/, '')
+    .replace(/-\s*$/, '')
+}

package/src/core/utils/path-builder.ts

@@ -0,0 +1,45 @@
+// Vendored from astrobook 0.13.3 (utils/path-builder.ts) — see ../LICENSE-astrobook.
+// Divergence: relative imports carry the .ts extension so node can load this graph directly
+// (upstream is bundled before it ships; this package is not).
+import type { AstroConfig } from 'astro'
+
+import {
+  ensureLeadingSlash,
+  ensureTrailingSlash,
+  stripLeadingAndTrailingSlashes,
+  stripTrailingSlash,
+} from './path.ts'
+
+interface PathBuilderOptions {
+  trailingSlash?: AstroConfig['trailingSlash']
+}
+
+/**
+ * @internal
+ */
+export type PathBuilder = (...parts: string[]) => string
+
+/**
+ * Joins multiple path segments into a single URL path with a leading slash,
+ * and adds or removes a trailing slash based on config.
+ *
+ * @internal
+ */
+export function createPathBuilder({
+  trailingSlash = 'ignore',
+}: PathBuilderOptions): PathBuilder {
+  return function buildPath(...parts): string {
+    let result = parts
+      .map(stripLeadingAndTrailingSlashes)
+      .filter(Boolean)
+      .join('/')
+
+    if (trailingSlash === 'always') {
+      result = ensureTrailingSlash(result)
+    } else if (trailingSlash === 'never') {
+      result = stripTrailingSlash(result)
+    }
+
+    return ensureLeadingSlash(result)
+  }
+}

package/src/core/utils/path.ts

@@ -0,0 +1,80 @@
+/**
+ * Ensure the passed path starts with a leading slash.
+ */
+export function ensureLeadingSlash(href: string): string {
+  if (href[0] !== '/') href = '/' + href
+  return href
+}
+
+/**
+ * Ensure the passed path ends with a trailing slash.
+ */
+export function ensureTrailingSlash(href: string): string {
+  if (href[href.length - 1] !== '/') href += '/'
+  return href
+}
+
+/**
+ * Ensure the passed path starts and ends with slashes.
+ */
+export function ensureLeadingAndTrailingSlashes(href: string): string {
+  href = ensureLeadingSlash(href)
+  href = ensureTrailingSlash(href)
+  return href
+}
+
+/**
+ * Ensure the passed path does not start with a leading slash.
+ */
+export function stripLeadingSlash(href: string) {
+  while (href[0] === '/') href = href.slice(1)
+  return href
+}
+
+/**
+ * Ensure the passed path does not end with a trailing slash.
+ */
+export function stripTrailingSlash(href: string) {
+  while (href[href.length - 1] === '/') href = href.slice(0, -1)
+  return href
+}
+
+/**
+ * Ensure the passed path does not start and end with slashes.
+ */
+export function stripLeadingAndTrailingSlashes(href: string): string {
+  href = stripLeadingSlash(href)
+  href = stripTrailingSlash(href)
+  return href
+}
+
+/**
+ * Remove the extension from a path.
+ */
+export function stripHtmlExtension(path: string) {
+  const pathWithoutTrailingSlash = stripTrailingSlash(path)
+  return pathWithoutTrailingSlash.endsWith('.html')
+    ? pathWithoutTrailingSlash.slice(0, -5)
+    : path
+}
+
+/**
+ * Add '.html' extension to a path.
+ */
+export function ensureHtmlExtension(path: string) {
+  path = stripLeadingAndTrailingSlashes(path)
+  if (!path.endsWith('.html')) {
+    path = path ? path + '.html' : '/index.html'
+  }
+  return ensureLeadingSlash(path)
+}
+
+/**
+ * Remove the extension from a path.
+ */
+export function stripExtension(path: string) {
+  const periodIndex = path.lastIndexOf('.')
+  return path.slice(0, periodIndex > -1 ? periodIndex : undefined)
+}
+
+export { stripLeadingAndTrailingSlashes as stripSlashes }

package/src/core/virtual-module/get-story-modules.ts

@@ -0,0 +1,110 @@
+// Vendored from astrobook 0.13.3 (virtual-module/get-story-modules.ts) — see ../LICENSE-astrobook.
+// Divergence: relative imports carry the .ts extension so node can load this graph directly
+// (upstream is bundled before it ships; this package is not).
+// Divergence: just-kebab-case is inlined at ../utils/kebab-case.ts (upstream bundles it).
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import type { StoryModule } from '../../types/types.ts'
+import { fdir } from 'fdir'
+import slash from 'slash'
+
+import { getExports } from '../utils/get-exports.ts'
+import { invariant } from '../utils/invariant.ts'
+import kebabCase from '../utils/kebab-case.ts'
+
+/**
+ * List the absolute paths of all story files in the given directory.
+ */
+async function listStoryFiles(rootDir: string): Promise<string[]> {
+  invariant(
+    path.isAbsolute(rootDir),
+    `Root directory must be absolute, but got '${rootDir}'`,
+  )
+
+  const filePaths = await new fdir()
+    .withSymlinks()
+    .withFullPaths()
+    .normalize()
+    .glob('./**/*.stories.{ts,tsx,js,jsx,mts,mtsx,mjs,mjsx}')
+    .exclude((dirname) => dirname === 'node_modules')
+    .crawl(rootDir)
+    .withPromise()
+
+  return filePaths.sort()
+}
+
+type ParsedStoryFile = {
+  /**
+   * The absolute path to the file. Unix-style slashes are used.
+   */
+  filePath: string
+
+  /**
+   * Whether the file has a default export
+   */
+  defaultExport: boolean
+
+  /**
+   * The named exports in the file
+   */
+  namedExports: string[]
+}
+
+async function parseStoryFiles(filePath: string): Promise<ParsedStoryFile> {
+  const code = await fs.readFile(filePath, 'utf-8')
+  const exports = getExports(code)
+  const defaultExport = exports.includes('default')
+  const namedExports = exports.filter((name) => name !== 'default')
+
+  return { filePath, defaultExport, namedExports }
+}
+
+export function convertStoryFileToModule(
+  rootDir: string,
+  file: ParsedStoryFile,
+): StoryModule | undefined {
+  if (file.namedExports.length === 0) {
+    console.warn(`[astrobook] File ${file.filePath} has no named exports`)
+    return
+  }
+
+  if (!file.defaultExport) {
+    console.warn(`[astrobook] File ${file.filePath} has no default export`)
+    return
+  }
+
+  const relativePath = path.normalize(path.relative(rootDir, file.filePath))
+  const relativePathWithoutStories = relativePath.replace(
+    /\.stories\.\w+$/i,
+    '',
+  )
+  const parts = relativePathWithoutStories.split(path.sep)
+
+  const directory = parts.slice(0, -1).join('/')
+  const name = parts.pop()
+  invariant(name, `Unexpected file path: ${file.filePath}`)
+
+  const moduleId = directory
+    ? `${directory}/${kebabCase(name)}`
+    : kebabCase(name)
+
+  return {
+    id: moduleId,
+    name,
+    directory,
+    importPath: slash(file.filePath),
+    stories: file.namedExports.map((name) => {
+      return { id: `${moduleId}/${kebabCase(name)}`, name }
+    }),
+  }
+}
+
+export async function getStoryModules(rootDir: string): Promise<StoryModule[]> {
+  const storyFilePaths = await listStoryFiles(rootDir)
+  const storyFiles = await Promise.all(storyFilePaths.map(parseStoryFiles))
+
+  return storyFiles
+    .map((storyFile) => convertStoryFileToModule(rootDir, storyFile))
+    .filter((module) => !!module)
+}

package/src/core/virtual-module/story-modules.ts

@@ -0,0 +1,9 @@
+// Vendored from astrobook 0.13.3 (virtual-module/story-modules.ts) — see ../LICENSE-astrobook.
+// Divergence: relative imports carry the .ts extension so node can load this graph directly
+// (upstream is bundled before it ships; this package is not).
+import { getStoryModules } from './get-story-modules.ts'
+
+export async function loadStoryModules(rootDir: string): Promise<string> {
+  const modules = await getStoryModules(rootDir)
+  return `export default ${JSON.stringify(modules)}`
+}

package/src/core/virtual-module/virtual-module-ids.ts

@@ -0,0 +1,17 @@
+export const STORY_MODULES_ID = 'virtual:astrobook/story-modules.mjs'
+export const STORY_MODULES_RESOLVED_ID =
+  '__virtual_astrobook_story_modules__.mjs'
+
+export const GLOBAL_CONFIG_ID = 'virtual:astrobook/global-config.mjs'
+export const GLOBAL_CONFIG_RESOLVED_ID = '__virtual_astrobook_user_config__.mjs'
+
+export const COMPONENT_HEAD_ID = 'virtual:astrobook/components/head.mjs'
+export const COMPONENT_HEAD_RESOLVED_ID =
+  '__virtual_astrobook_COMPONENT_HEAD__.mjs'
+
+export const COMPONENT_HOME_ID = 'virtual:astrobook/components/home.mjs'
+export const COMPONENT_HOME_RESOLVED_ID =
+  '__virtual_astrobook_COMPONENT_HOME__.mjs'
+
+export const USER_CSS_ID = 'virtual:astrobook/user-css.mjs'
+export const USER_CSS_RESOLVED_ID = '__virtual_astrobook_user_css__.mjs'