@nendlabs/docpage 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# @nendlabs/docpage
+
+a config-first, interactive paper-style project page renderer for nendlabs.
+
+it ships fully compiled styles, so consumers only need one css import.
+
+### install
+
+use your package manager of choice:
+
+```bash
+npm install @nendlabs/docpage
+```
+
+```bash
+bun add @nendlabs/docpage
+```
+
+### quick start
+
+import the styles once near your app root:
+
+```ts
+import "@nendlabs/docpage/styles.css";
+```
+
+render a page from a typed config:
+
+```tsx
+import { DocPage, type DocPageConfig } from "@nendlabs/docpage";
+
+const CONFIG: DocPageConfig = {
+  brand: { name: "nendlabs" },
+  header: {
+    title: "a project page",
+    subtitle: "how we built it",
+  },
+  toc: [
+    { id: "abstract", label: "abstract" },
+    { id: "api", label: "api" },
+  ],
+  sections: [
+    {
+      kind: "prose",
+      id: "abstract",
+      titleBorder: true,
+      blocks: [
+        { kind: "p", text: "we start with the concept and work backward." },
+        {
+          kind: "ul",
+          items: [
+            "derive signals from raw events",
+            "compress context with retrieval",
+            "reason over multi-day windows",
+          ],
+        },
+      ],
+    },
+    {
+      kind: "api",
+      id: "api",
+      intro: "a tiny example with tabs.",
+      tabs: [
+        {
+          id: "curl",
+          language: "bash",
+          code: "curl https://example.com/v1/events",
+        },
+        {
+          id: "ts",
+          label: "typescript",
+          language: "typescript",
+          code: "client.event(\"user.login\", { userId: \"123\" })",
+        },
+      ],
+    },
+  ],
+  footer: { copyrightName: "nendlabs" },
+};
+
+export default function ProjectPage() {
+  return <DocPage config={CONFIG} />;
+}
+```
+
+### requirements
+
+- react and react-dom are peer dependencies (react 18+ recommended)
+- mdx sections require your host app to compile mdx into react components
+
+### mdx sections
+
+the renderer is config-first, but mdx is supported via `kind: "mdx"` sections.
+
+```tsx
+import type { DocPageConfig } from "@nendlabs/docpage";
+import AbstractSection from "./sections/abstract.mdx";
+
+const CONFIG: DocPageConfig = {
+  brand: { name: "nendlabs" },
+  header: { title: "mdx section example" },
+  sections: [
+    {
+      kind: "mdx",
+      id: "abstract",
+      titleBorder: true,
+      Component: AbstractSection,
+    },
+  ],
+};
+```
+
+code fences inside mdx are automatically rendered through the shared highlighted code block.
+
+### styling model
+
+consumers only need this import:
+
+```ts
+import "@nendlabs/docpage/styles.css";
+```
+
+this package compiles its own tailwind classes into the shipped css.
+
+important note about custom classes:
+
+- classes used inside this package are included in the shipped css
+- classes that only appear in your mdx or custom nodes are not guaranteed to exist
+- if you want arbitrary tailwind classes in your content, also run tailwind in the host app
+
+### config reference
+
+sections are discriminated by `kind`:
+
+- `kind: "prose"` with `blocks`
+- `kind: "api"` with `tabs`
+- `kind: "mdx"` with a compiled `Component`
+
+for the concrete shapes, see:
+
+- `src/types.ts`
+- `playground/src/logst-config.tsx`

package/README.repo.md

@@ -0,0 +1,68 @@
+# @nendlabs/docpage repo
+
+this repository contains the `@nendlabs/docpage` package, its playground, and internal docs.
+
+### repository overview
+
+key paths:
+
+- `src/`: the package source
+- `styles/`: tailwind entry + theme tokens
+- `playground/`: local app to preview configs
+- `docs/`: deeper documentation and publishing notes
+- `.github/workflows/`: ci and main-branch publishing
+
+### npm readme behavior
+
+npm always reads `README.md` at publish time.
+
+to keep this repo readme maintainer-focused while shipping a package-focused npm readme:
+
+- `docs/package.md` is the source of truth for the npm readme
+- `prepack` copies `docs/package.md` into `README.md`
+- `postpack` restores the original `README.md`
+
+relevant scripts:
+
+- `bun run readme:package`
+- `bun run readme:restore`
+- `bun run build`
+
+### development
+
+install and run the playground:
+
+```bash
+bun install
+bun run dev
+```
+
+run local validation:
+
+```bash
+bun run typecheck
+bun run test
+bun run build
+```
+
+### docs
+
+deeper documentation lives under `docs/`:
+
+- `docs/authoring.md`
+- `docs/mdx.md`
+- `docs/publishing.md`
+- `docs/package.md`
+
+### release flow
+
+publishing is automated on pushes to `main`.
+
+high level:
+
+1. open a pr into `main`
+2. bump `package.json` version in the pr
+3. merge to `main`
+4. ci validates and the publish workflow runs `npm publish`
+
+see `docs/publishing.md` for details.

package/dist/cn.d.ts

@@ -0,0 +1,3 @@
+import { type ClassValue } from "clsx";
+export declare function cn(...inputs: ClassValue[]): string;
+//# sourceMappingURL=cn.d.ts.map

package/dist/cn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cn.d.ts","sourceRoot":"","sources":["../src/cn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,MAAM,CAAC;AAG7C,wBAAgB,EAAE,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,UAEzC"}

package/dist/components/api-tabs.d.ts

@@ -0,0 +1,9 @@
+import type { DocApiTab } from "../types";
+type ApiTabsProps = {
+    tabs: DocApiTab[];
+    defaultTabId?: string;
+    className?: string;
+};
+export declare function ApiTabs({ tabs, defaultTabId, className }: ApiTabsProps): import("react/jsx-runtime").JSX.Element | null;
+export {};
+//# sourceMappingURL=api-tabs.d.ts.map

package/dist/components/api-tabs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-tabs.d.ts","sourceRoot":"","sources":["../../src/components/api-tabs.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG1C,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAcF,wBAAgB,OAAO,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,EAAE,YAAY,kDA0CtE"}

package/dist/components/code-block.d.ts

@@ -0,0 +1,11 @@
+type CodeBlockProps = {
+    code: string;
+    language?: string;
+    caption?: React.ReactNode;
+    className?: string;
+    preClassName?: string;
+    codeClassName?: string;
+};
+export declare function CodeBlock({ code, language, caption, className, preClassName, codeClassName, }: CodeBlockProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=code-block.d.ts.map

package/dist/components/code-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-block.d.ts","sourceRoot":"","sources":["../../src/components/code-block.tsx"],"names":[],"mappings":"AAWA,KAAK,cAAc,GAAG;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAoBF,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,SAAS,EACT,YAAY,EACZ,aAAa,GACd,EAAE,cAAc,2CAwChB"}

package/dist/components/mermaid.d.ts

@@ -0,0 +1,4 @@
+export declare function Mermaid({ chart }: {
+    chart: string;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=mermaid.d.ts.map

package/dist/components/mermaid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../../src/components/mermaid.tsx"],"names":[],"mappings":"AAEA,wBAAgB,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,2CA8CnD"}

package/dist/docpage.d.ts

@@ -0,0 +1,9 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+import type { DocPageProps } from "./types";
+type MdxPreProps = HTMLAttributes<HTMLPreElement> & {
+    children?: ReactNode;
+};
+export declare function MdxCodeBlockPre(props: MdxPreProps): import("react/jsx-runtime").JSX.Element;
+export declare function DocPage({ config, className }: DocPageProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=docpage.d.ts.map

package/dist/docpage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docpage.d.ts","sourceRoot":"","sources":["../src/docpage.tsx"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,cAAc,EAEnB,KAAK,SAAS,EAIf,MAAM,OAAO,CAAC;AAUf,OAAO,KAAK,EAKV,YAAY,EAIb,MAAM,SAAS,CAAC;AA6OjB,KAAK,WAAW,GAAG,cAAc,CAAC,cAAc,CAAC,GAAG;IAClD,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,CAAC;AAiBF,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,2CAmBjD;AAqPD,wBAAgB,OAAO,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,YAAY,2CAiD1D"}

package/dist/hooks/use-active-scroll-section-ids.d.ts

@@ -0,0 +1,8 @@
+type Options = {
+    rootMargin?: string;
+    threshold?: number | number[];
+    syncToUrl?: boolean;
+};
+export declare function useActiveScrollSectionIds(ids: string[], options?: Options): string;
+export {};
+//# sourceMappingURL=use-active-scroll-section-ids.d.ts.map

package/dist/hooks/use-active-scroll-section-ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-active-scroll-section-ids.d.ts","sourceRoot":"","sources":["../../src/hooks/use-active-scroll-section-ids.tsx"],"names":[],"mappings":"AAEA,KAAK,OAAO,GAAG;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAUF,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,UA0CzE"}

package/dist/hooks/use-color-scheme.d.ts

@@ -0,0 +1,4 @@
+type Scheme = "light" | "dark";
+export declare function useColorScheme(): Scheme;
+export {};
+//# sourceMappingURL=use-color-scheme.d.ts.map

package/dist/hooks/use-color-scheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-color-scheme.d.ts","sourceRoot":"","sources":["../../src/hooks/use-color-scheme.tsx"],"names":[],"mappings":"AAEA,KAAK,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAS/B,wBAAgB,cAAc,IAAI,MAAM,CAmBvC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { cn } from "./cn";
+export { DocPage, MdxCodeBlockPre } from "./docpage";
+export { ApiTabs } from "./components/api-tabs";
+export { CodeBlock } from "./components/code-block";
+export { Mermaid } from "./components/mermaid";
+export { useActiveScrollSectionIds } from "./hooks/use-active-scroll-section-ids";
+export { useColorScheme } from "./hooks/use-color-scheme";
+export type { DocApiSection, DocApiTab, DocBlock, DocBrand, DocCalloutBlock, DocCalloutTone, DocFooter, DocFooterLink, DocHeader, DocListBlock, DocLabeledListBlock, DocMdxSection, DocOptions, DocPageConfig, DocPageProps, DocParagraphBlock, DocPreBlock, DocProseSection, DocSection, DocSectionBase, DocTheme, DocThemeTokens, DocTocEntry, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,MAAM,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAC;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,YAAY,EACV,aAAa,EACb,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,cAAc,EACd,SAAS,EACT,aAAa,EACb,SAAS,EACT,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,UAAU,EACV,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,UAAU,EACV,cAAc,EACd,QAAQ,EACR,cAAc,EACd,WAAW,GACZ,MAAM,SAAS,CAAC"}