astro-pigment 0.9.0

package/.browserslistrc

@@ -0,0 +1 @@
+last 2 versions and not dead

package/README.md

@@ -0,0 +1,384 @@
+# astro-pigment
+
+An Astro 6 documentation theme with dark mode, interactive playgrounds, and SEO endpoints. One integration call gives you a complete docs site: layout, navigation, table of contents, code highlighting, LLM-friendly endpoints, and a library of interactive components.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+- **Single integration**: rehype plugins, PostCSS, Shiki themes, sitemap, and SEO routes configured automatically
+- **Dark mode**: three-state toggle (auto/light/dark) with View Transitions, no FOUC
+- **CSS variable theming**: override `--theme-hue-override` or `--layout-width-override` in plain CSS, no config options needed
+- **Interactive playgrounds**: CodeMirror editor + sandboxed live preview with console capture
+- **LLM endpoints**: `/llms.txt` and `/llms-full.txt` auto-generated from your markdown content
+- **Auto-generated favicons**: provide one or two source icons (simplified favicon + detailed manifest), get favicon.ico, SVG, PNG, apple-touch-icon, and webmanifest
+- **Bundled fonts**: Martian Grotesk + Martian Mono auto-injected (opt out with `fonts: false`)
+- **Accessible**: roving focus, ARIA attributes, keyboard navigation throughout
+- **Zero build step**: Astro resolves `.astro`/`.ts` source directly from the package
+
+## Installation
+
+Add the theme as a GitHub dependency along with its peer dependencies:
+
+```json
+// package.json
+{
+  "dependencies": {
+    "astro-pigment": "github:psd-coder/astro-pigment",
+    "astro": "^6.0.0",
+    "nanotags": "^0.14.0",
+    "nanostores": "^1.0.0"
+  }
+}
+```
+
+Then install:
+
+```bash
+pnpm install
+```
+
+## Quick Start
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import docsTheme from "astro-pigment";
+
+export default defineConfig({
+  integrations: [
+    docsTheme({
+      project: {
+        name: "my-project",
+        description: "A short description of your project",
+        license: { name: "MIT", url: "https://github.com/your-name/your-repo/blob/main/LICENSE" },
+        github: { user: "your-name", repository: "your-repo" },
+      },
+      author: { name: "Your Name", url: "https://x.com/your_handle" },
+      icon: "src/assets/icon.svg",
+      navLinks: [
+        { href: "/", label: "Overview" },
+        { href: "/api", label: "API" },
+      ],
+    }),
+  ],
+});
+```
+
+```ts
+// src/content.config.ts
+import { defineDocsCollections } from "astro-pigment/content";
+
+export const collections = defineDocsCollections();
+```
+
+Drop your `.md`/`.mdx` files in `src/content/docs/`. The integration injects `/[...slug]` automatically; pages render with the full layout, TOC, prev/next navigation, and edit-on-github link out of the box. Dark mode, sticky header, sidebar + mobile TOC, code copy buttons, favicons, webmanifest, sitemap, and LLM endpoints are all wired up automatically.
+
+To render pages yourself, set `docs.renderDefaultPage: false` and create your own `src/pages/[...slug].astro`. Reuse the boilerplate via `getDocsStaticPaths` from `astro-pigment/utils/content`.
+
+### Pick a theme hue (optional)
+
+Temporarily enable the hue slider to find the right color for your site:
+
+```js
+docsTheme({
+  // ...your config
+  hueSlider: true, // shows a color slider in the header
+})
+```
+
+Drag the slider, pick a hue you like, then hardcode it in CSS and remove `hueSlider`:
+
+```css
+:root {
+  --theme-hue-override: 135; /* the value you picked */
+}
+```
+
+All UI and code syntax highlighting colors derive from this hue via OKLch.
+
+## Integration Config
+
+```ts
+type DocsThemeConfig = {
+  // Required
+  github: {
+    user?: string;          // one of user/organization required
+    organization?: string;
+    repository: string;
+  };
+  project: {
+    name: string;
+    description: string;
+    license: { name: string; url: string };
+  };
+  author: {
+    name: string;
+    url: string;
+    icon?: IconName;        // auto-detected: "x" for x.com URLs
+  };
+
+  // Optional
+  links?: Array<{ label: string; url: string; icon?: IconName }>;
+  site?: string;            // default: auto GitHub Pages URL
+  icon?: string;            // path to 512x512 PNG or SVG, generates favicons + webmanifest
+  hueSlider?: boolean;      // show hue slider in header for initial theme setup
+  shikiThemes?: {           // overrides adaptive hue-based theme
+    light: string;
+    dark: string;
+  };
+  navLinks?: NavItem[];     // header nav links; href accepts "/api" or "api"
+  docs?: {
+    directory?: string;     // default: "src/content/docs"
+    pattern?: string;       // default: "**/*.{md,mdx}"
+    deepSections?: string[];// slugs where llms.txt shows ### headings
+    renderDefaultPage?: boolean; // default: true. set false to ship your own [...slug].astro
+    tocItemsSelector?: string;   // default: ".prose :is(h2, h3)[id]"
+  };
+};
+```
+
+### What the integration does
+
+- Stores config in a virtual module (`virtual:theme-integration-config`) so components read it automatically
+- Auto-sets `site` and `base` from GitHub config (GitHub Pages URL in CI, `/` in dev)
+- Injects rehype-slug + rehype-autolink-headings
+- Injects an adaptive Shiki theme that derives syntax colors from `--theme-hue` (based on Catppuccin, hue-rotated via OKLch). Override with `shikiThemes` to use fixed themes instead.
+- Injects PostCSS preset-env (nesting, custom-media, media-query-ranges)
+- When `icon` is configured: generates favicons (svg, ico, 96x96 png), apple-touch-icon, webmanifest + manifest icons
+- Injects sitemap + llms.txt, llms-full.txt, [slug].md routes
+- Injects `/[...slug]` page rendering docs from the content collection (opt out with `docs.renderDefaultPage: false`)
+
+## Components
+
+### Core
+
+Import from `astro-pigment/components`:
+
+**Layout** -- full page shell: sticky header, sidebar, footer, code copy buttons. Config read from virtual module. Includes ThemeToggle, ThemeScript, CodeBlockWrapper automatically.
+
+```astro
+<Layout title="Page Title" navItems={[{ href: "", label: "Home" }, { href: "api", label: "API" }]}>
+  <MyLogo slot="logo" />
+  <TableOfContents slot="sidebar" headings={headings} itemsSelector=".prose :is(h2, h3)[id]" />
+  <article class="prose"><slot /></article>
+  <span slot="footer-extra">& My Company</span>
+</Layout>
+```
+
+Props: `title`, `navItems?`. Slots: `default`, `sidebar`, `logo`, `head-extra`, `footer-extra`, `author-icon`.
+
+**TableOfContents** -- desktop sidebar with scroll-spy highlighting + mobile popover trigger. Both rendered from a single component.
+
+```astro
+<TableOfContents slot="sidebar" headings={headings} itemsSelector=".prose :is(h2, h3)[id]" />
+```
+
+**PageHeading** -- heading row with a "view as markdown" icon link.
+
+```astro
+<PageHeading title="API Reference" href="/api.md" />
+```
+
+**Button** -- styled button with optional `square` prop for icon-only use.
+
+```astro
+<Button>Click me</Button>
+<Button square aria-label="Menu"><Icon name="list" /></Button>
+```
+
+**Icon** -- built-in SVGs: `check`, `chevron-left`, `copy`, `github`, `list`, `markdown`, `x`. Use `name="custom"` + slot for your own.
+
+```astro
+<Icon name="github" size={32} />
+<Icon name="custom" label="Mastodon"><svg>...</svg></Icon>
+```
+
+**Footer** -- license, GitHub, and author links from virtual config. Slot: `extra`. Included in Layout by default.
+
+**ThemeToggle** -- three-state switcher (auto/light/dark). Included in Layout automatically.
+
+**ThemeScript** -- inline script preventing FOUC. Included in Layout automatically.
+
+**CodeBlockWrapper** -- adds copy buttons to all `.prose pre` blocks. Included in Layout automatically.
+
+**InstallPackage** -- tabbed package manager switcher. Selection persists to localStorage.
+
+```astro
+<InstallPackage pkg="nanotags nanostores" />
+<InstallPackage pkg="typescript" dev />
+```
+
+**PrevNextNav** -- previous/next page navigation.
+
+```astro
+<PrevNextNav prev={{ title: "Getting Started", href: "/" }} next={{ title: "API", href: "/api" }} />
+```
+
+### Playground
+
+Import from `astro-pigment/components/playground`:
+
+**CodeEditor** -- CodeMirror 6 with adaptive hue-based theme synced to dark mode.
+
+```astro
+<CodeEditor lang="javascript" />
+```
+
+**LivePreview** -- sandboxed iframe execution with console capture.
+
+**CodeExample** -- full playground: tabbed editor + live preview + collapsible logs.
+
+```astro
+<CodeExample files={[
+  { name: "index.html", type: "html", lang: "html", content: "<h1>Hello</h1>" },
+  { name: "app.js", type: "javascript", lang: "javascript", content: "console.log('hi')" },
+]} />
+```
+
+**CodePanels** -- multi-file code display with Shiki highlighting and tabs.
+
+**ResizablePanes** / **ResizablePane** -- draggable split-pane layout.
+
+**CollapsiblePane** -- expandable/collapsible section with resize handle.
+
+**Tabs** / **Tab** -- accessible tabs with roving focus and scroll arrows.
+
+## CSS Customization
+
+The theme uses CSS variables with fallback defaults. Override them in your own CSS:
+
+```css
+:root {
+  --theme-hue-override: 135;         /* green instead of default cyan (180) */
+  --layout-width-override: 1280px;   /* wider layout */
+  --layout-sidebar-width-override: 280px;
+}
+```
+
+All color tokens are derived from `--theme-hue` using OKLch, so changing the hue recolors the entire site.
+
+### Available tokens
+
+| Token | Light | Dark |
+|-------|-------|------|
+| `--color-surface-1` | 99% lightness | 12% lightness |
+| `--color-surface-2` | 98% | 18% |
+| `--color-surface-3` | 96% | 21% |
+| `--color-accent` | 55% lightness | 65% lightness |
+| `--color-text-primary` | 15% | 90% |
+| `--color-text-secondary` | 40% | 75% |
+| `--color-border` | 90% | 25% |
+
+Typography: `--text-xxs` (0.625rem) through `--text-2xl` (2rem). Spacing base: `--spacing` (4px). Radii: `--radius-sm`, `--radius-md`.
+
+## Fonts
+
+The integration auto-injects bundled Martian Grotesk (variable weight) and Martian Mono (400) as local fonts, setting `--font-sans` and `--font-mono` CSS variables. Pass `fonts: false` to opt out and set those variables to your own fonts.
+
+## Stores
+
+Available from `astro-pigment/stores/theme` and `astro-pigment/stores/media`:
+
+```ts
+import { $themeSetting, $resolvedTheme, cycleTheme } from "astro-pigment/stores/theme";
+import { $prefersDarkScheme, $prefersReducedMotion } from "astro-pigment/stores/media";
+```
+
+- `$themeSetting`: persistent atom (`"auto"` | `"light"` | `"dark"`)
+- `$resolvedTheme`: computed (`"light"` | `"dark"`)
+- `cycleTheme()`: cycles auto -> light -> dark
+
+Package manager store (from `astro-pigment/stores/pkgManager`):
+
+```ts
+import { $pkgManager } from "astro-pigment/stores/pkgManager";
+
+$pkgManager.get() // "pnpm" | "npm" | "yarn" | "bun"
+```
+
+Used by `InstallPackage` internally. Also available for custom `CodePanels`-based tab switchers via `defineCodePanels`:
+
+```ts
+import { defineCodePanels } from "astro-pigment/utils/defineCodePanels";
+import { $pkgManager } from "astro-pigment/stores/pkgManager";
+
+defineCodePanels("x-my-switcher", $pkgManager);
+```
+
+## SEO & LLM Endpoints
+
+When `docs` is configured, the integration auto-generates:
+
+- **`/llms.txt`**: structured index with project name, description, and per-doc sections
+- **`/llms-full.txt`**: all docs concatenated into a single markdown file
+- **`/[slug].md`**: individual markdown endpoints for each doc file
+- **Sitemap**: via `@astrojs/sitemap`
+
+## Favicon & Webmanifest
+
+`icon` accepts either a single source path or an object with two sources:
+
+```js
+// single source (same icon for all sizes)
+icon: "src/assets/icon.svg",
+
+// two sources — simplified design for tiny favicons, detailed for manifest
+icon: {
+  favicon: "src/assets/favicon.svg",      // used for /favicon.svg and /favicon.ico (16-32px)
+  manifest: "src/assets/icon-detailed.svg", // used for 96px and up
+}
+```
+
+Use the object form when a 512x512 design has fine details that become illegible at 16-32px. Both fields are required in the object form.
+
+Generated routes:
+
+- `/favicon.svg` — from `favicon` source (passthrough for SVG)
+- `/favicon.ico` — from `favicon` source (32x32)
+- `/favicon-96x96.png` — from `manifest` source
+- `/apple-touch-icon.png` — from `manifest` source (180x180)
+- `/web-app-manifest-192x192.png` — from `manifest` source
+- `/web-app-manifest-512x512.png` — from `manifest` source
+- `/site.webmanifest`
+
+Layout renders the corresponding `<link>` tags only when `icon` is set.
+
+## Examples Loader
+
+For sites with interactive code examples, import the content collection loader:
+
+```ts
+// content.config.ts
+import { examplesLoader } from "astro-pigment/loaders/examples";
+
+const examples = defineCollection({
+  loader: examplesLoader("src/content/examples/"),
+  schema: z.object({
+    title: z.string(),
+    description: z.string(),
+    files: z.array(z.object({
+      name: z.string(),
+      type: z.enum(["html", "javascript", "css", "importmap"]),
+      lang: z.enum(["html", "javascript", "css"]),
+      content: z.string(),
+    })),
+  }),
+});
+```
+
+The loader parses `.html` files with `data-type` attributes into `FileEntry` arrays compatible with the `CodeExample` playground component.
+
+## Exportable Configs
+
+```js
+// stylelint.config.js
+export default { extends: ["astro-pigment/stylelint.config"] };
+```
+
+```
+// .browserslistrc
+extends astro-pigment/browserslist
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "astro-pigment",
+  "version": "0.9.0",
+  "type": "module",
+  "files": [
+    "src",
+    "stylelint.config.js",
+    ".browserslistrc",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./content": "./src/content.ts",
+    "./components": "./src/components/index.ts",
+    "./components/playground": "./src/components/playground.ts",
+    "./stores/theme": "./src/stores/theme.ts",
+    "./stores/media": "./src/stores/media.ts",
+    "./stores/pkgManager": "./src/stores/pkgManager.ts",
+    "./loaders/examples": "./src/loaders/examples-loader.ts",
+    "./utils/content": "./src/utils/content.ts",
+    "./utils/urls": "./src/utils/urls.ts",
+    "./utils/schemas": "./src/utils/schemas.ts",
+    "./utils/defineCodePanels": "./src/utils/defineCodePanels.ts",
+    "./styles/*": "./src/styles/*",
+    "./types": "./src/types.ts",
+    "./stylelint.config": "./stylelint.config.js",
+    "./browserslist": "./.browserslistrc"
+  },
+  "peerDependencies": {
+    "astro": "^6.0.0",
+    "nanostores": "^1.0.0",
+    "nanotags": "^0.14.0"
+  },
+  "dependencies": {
+    "@astrojs/mdx": "^5.0.3",
+    "@astrojs/sitemap": "^3.7.1",
+    "@codemirror/lang-css": "^6.3.1",
+    "@codemirror/lang-html": "^6.4.9",
+    "@codemirror/lang-javascript": "^6.2.3",
+    "@codemirror/lang-json": "^6.0.1",
+    "@codemirror/language": "^6.12.3",
+    "@codemirror/state": "^6.5.0",
+    "@codemirror/view": "^6.36.0",
+    "@lezer/highlight": "^1.2.3",
+    "@nanostores/persistent": "^1.3.0",
+    "codemirror": "^6.0.1",
+    "es-toolkit": "^1.45.1",
+    "fuse.js": "7.4.0-beta.1",
+    "github-slugger": "^2.0.0",
+    "keyux": "^0.11.3",
+    "linkedom": "^0.18.12",
+    "mdast-util-to-string": "^4.0.0",
+    "nanoid": "^5.1.7",
+    "postcss-preset-env": "^11.0.0",
+    "rehype-autolink-headings": "^7.0.0",
+    "rehype-slug": "^6.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-mdx": "^3.1.1",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
+    "sharp": "^0.34.0",
+    "typed-channel": "^0.10.1",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0",
+    "valibot": "^1.3.1"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4",
+    "astro": "^6.1.5",
+    "nanostores": "^1.0.0",
+    "nanotags": "^0.15.0",
+    "oxfmt": "^0.44.0",
+    "oxlint": "^1.59.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "bump": "bash scripts/bump.sh",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --fix --fix-suggestions",
+    "format": "oxfmt --write src/"
+  }
+}

package/src/attachments/attachResizing.ts

@@ -0,0 +1,177 @@
+import type { SetupContext } from "nanotags";
+import { atom } from "nanostores";
+import styles from "./styles.module.css";
+
+type AttachResizingOptions = {
+  position: "before" | "after";
+  element: HTMLElement;
+  direction: "horizontal" | "vertical";
+  label?: string;
+  minValue?: number;
+  maxValue?: number;
+  step?: number;
+  initialValue?: number;
+  onDragStart?: (info: { startPos: number; elementSize: number; containerSize: number }) => void;
+  onDrag?: (delta: number) => void;
+  onDragEnd?: () => void;
+  onKeyResize?: (value: number) => void;
+};
+
+function createHandle(direction: "horizontal" | "vertical"): HTMLElement {
+  const handle = document.createElement("div");
+  handle.className = styles.handle ?? "";
+  handle.dataset["direction"] = direction;
+  handle.setAttribute("role", "separator");
+  handle.setAttribute("tabindex", "0");
+  return handle;
+}
+
+export function attachResizing(
+  ctx: SetupContext<{}, {}>,
+  options: AttachResizingOptions,
+): { handle: HTMLElement; setAriaValue: (value: number) => void } {
+  const {
+    position,
+    element,
+    direction,
+    label,
+    minValue = 0,
+    maxValue = 100,
+    step = 1,
+    initialValue = 50,
+    onDragStart,
+    onDrag,
+    onDragEnd,
+    onKeyResize,
+  } = options;
+
+  const handle = createHandle(direction);
+  handle.setAttribute("aria-valuemin", String(minValue));
+  handle.setAttribute("aria-valuemax", String(maxValue));
+  handle.setAttribute("aria-valuenow", String(initialValue));
+  if (label) {
+    handle.setAttribute("aria-label", label);
+  }
+
+  element.insertAdjacentElement(position === "before" ? "beforebegin" : "afterend", handle);
+
+  const $drag = atom({ isDragging: false, startPos: 0 });
+  let valueBeforeCollapse: number | null = null;
+
+  function setAriaValue(value: number) {
+    handle.setAttribute("aria-valuenow", String(Math.round(value)));
+  }
+
+  function onMouseMove(ev: MouseEvent) {
+    const { startPos } = $drag.get();
+    const currentPos = direction === "vertical" ? ev.clientY : ev.clientX;
+    const rawDelta = currentPos - startPos;
+    const delta = position === "before" ? -rawDelta : rawDelta;
+    onDrag?.(delta);
+  }
+
+  function onMouseUp() {
+    window.removeEventListener("mousemove", onMouseMove);
+    window.removeEventListener("mouseup", onMouseUp);
+    $drag.set({ ...$drag.get(), isDragging: false });
+    onDragEnd?.();
+  }
+
+  ctx.on(handle, "mousedown", (ev) => {
+    ev.preventDefault();
+    const isVertical = direction === "vertical";
+    const startPos = isVertical ? ev.clientY : ev.clientX;
+
+    $drag.set({ isDragging: true, startPos });
+
+    window.addEventListener("mousemove", onMouseMove);
+    window.addEventListener("mouseup", onMouseUp);
+
+    const elementRect = element.getBoundingClientRect();
+    const containerRect = element.parentElement?.getBoundingClientRect();
+    onDragStart?.({
+      startPos,
+      elementSize: isVertical ? elementRect.height : elementRect.width,
+      containerSize: containerRect
+        ? isVertical
+          ? containerRect.height
+          : containerRect.width
+        : Infinity,
+    });
+  });
+
+  ctx.on(handle, "keydown", (ev) => {
+    const current = Number(handle.getAttribute("aria-valuenow"));
+    let next: number | null = null;
+
+    const isHorizontal = direction === "horizontal";
+    const invert = position === "before";
+    const decreaseKey = isHorizontal
+      ? invert
+        ? "ArrowRight"
+        : "ArrowLeft"
+      : invert
+        ? "ArrowDown"
+        : "ArrowUp";
+    const increaseKey = isHorizontal
+      ? invert
+        ? "ArrowLeft"
+        : "ArrowRight"
+      : invert
+        ? "ArrowUp"
+        : "ArrowDown";
+
+    switch (ev.key) {
+      case decreaseKey:
+        next = Math.max(minValue, current - step);
+        break;
+      case increaseKey:
+        next = Math.min(maxValue, current + step);
+        break;
+      case "Home":
+        next = invert ? maxValue : minValue;
+        break;
+      case "End":
+        next = invert ? minValue : maxValue;
+        break;
+      case "Enter": {
+        if (current > minValue) {
+          valueBeforeCollapse = current;
+          next = minValue;
+        } else if (valueBeforeCollapse !== null) {
+          next = valueBeforeCollapse;
+          valueBeforeCollapse = null;
+        }
+        break;
+      }
+      default:
+        return;
+    }
+
+    ev.preventDefault();
+    if (next !== null && next !== current) {
+      setAriaValue(next);
+      onKeyResize?.(next);
+    }
+  });
+
+  ctx.effect($drag, ({ isDragging }) => {
+    handle.dataset["dragging"] = String(isDragging);
+
+    const parent = element.parentElement;
+    if (!parent) return;
+    for (const child of parent.children) {
+      if (child !== handle && child instanceof HTMLElement) {
+        child.style.pointerEvents = isDragging ? "none" : "";
+      }
+    }
+  });
+
+  ctx.onCleanup(() => {
+    window.removeEventListener("mousemove", onMouseMove);
+    window.removeEventListener("mouseup", onMouseUp);
+    handle.remove();
+  });
+
+  return { handle, setAriaValue };
+}