create-ncblock 0.0.1

package/templates/radar-chart/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "radar-chart",
+	"private": true,
+	"version": "0.0.1",
+	"type": "module",
+	"notionCustomTemplate": {
+		"title": "Radar Chart",
+		"description": "Multi-series chart demo with a fixed numeric schema for mapped collection data.",
+		"recommended": false
+	},
+	"scripts": {
+		"dev": "vite",
+		"build": "vite build",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"ncblock": "workspace:*",
+		"react": "^19.2.5",
+		"react-dom": "^19.2.5"
+	},
+	"devDependencies": {
+		"@tailwindcss/vite": "^4.2.4",
+		"@types/react": "^19.2.14",
+		"@types/react-dom": "^19.2.3",
+		"@vitejs/plugin-react": "^6.0.1",
+		"tailwindcss": "^4.2.4",
+		"typescript": "^6.0.3",
+		"vite": "^8.0.10"
+	}
+}

package/templates/radar-chart/src/index.css

@@ -0,0 +1,44 @@
+@import "tailwindcss";
+
+:root {
+	font-family:
+		ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica,
+		Arial, sans-serif;
+}
+
+:root,
+[data-theme="light"] {
+	--app-bg: var(--color-white);
+	--card-bg: var(--color-stone-100);
+	--surface-bg: var(--color-white);
+	--foreground: var(--color-stone-800);
+	--muted: color-mix(in oklab, var(--color-stone-800) 45%, transparent);
+	--border: color-mix(in oklab, var(--color-stone-800) 12%, transparent);
+	--grid-stroke: color-mix(in oklab, var(--color-stone-800) 12%, transparent);
+	--series-1: var(--color-blue-600);
+	--series-2: var(--color-red-600);
+	--series-3: var(--color-green-600);
+	--series-4: var(--color-violet-700);
+	--series-5: var(--color-amber-600);
+	--series-6: var(--color-cyan-600);
+}
+
+[data-theme="dark"] {
+	--app-bg: var(--color-zinc-900);
+	--card-bg: var(--color-zinc-800);
+	--surface-bg: var(--color-zinc-900);
+	--foreground: var(--color-zinc-200);
+	--muted: color-mix(in oklab, var(--color-white) 45%, transparent);
+	--border: color-mix(in oklab, var(--color-white) 12%, transparent);
+	--grid-stroke: color-mix(in oklab, var(--color-white) 16%, transparent);
+	--series-1: var(--color-blue-400);
+	--series-2: var(--color-red-400);
+	--series-3: var(--color-green-400);
+	--series-4: var(--color-violet-400);
+	--series-5: var(--color-amber-400);
+	--series-6: var(--color-cyan-400);
+}
+
+body {
+	margin: 0;
+}

package/templates/radar-chart/src/index.tsx

@@ -0,0 +1,531 @@
+import {
+	NotionCustomBlock,
+	type NotionDataSourcePage,
+	type NotionPageId,
+	useDataSource,
+	useDataSourceDefinitions,
+	useTheme,
+} from "ncblock"
+import React from "react"
+import ReactDOM from "react-dom/client"
+
+import "./index.css"
+
+type RadarSeries = {
+	id: string
+	label: string
+	color: string
+	values: number[]
+}
+
+type RadarSchemaAnalysis = {
+	labelKey?: string
+	missingFields: string[]
+	isReady: boolean
+}
+
+function makeFakeItem(
+	id: string,
+	properties: NotionDataSourcePage["propertiesByKey"],
+): NotionDataSourcePage {
+	return {
+		id: id as NotionPageId,
+		propertiesById: {},
+		propertiesByKey: properties,
+		update: async () => ({
+			status: "error",
+			error: "Sample rows are read-only",
+		}),
+	}
+}
+
+const FAKE_ITEMS: NotionDataSourcePage[] = [
+	makeFakeItem("engineering", {
+		name: "Engineering",
+		speed: 82,
+		quality: 91,
+		focus: 74,
+		collaboration: 88,
+		execution: 79,
+	}),
+	makeFakeItem("design", {
+		name: "Design",
+		speed: 68,
+		quality: 84,
+		focus: 90,
+		collaboration: 77,
+		execution: 70,
+	}),
+	makeFakeItem("product", {
+		name: "Product",
+		speed: 75,
+		quality: 79,
+		focus: 86,
+		collaboration: 81,
+		execution: 83,
+	}),
+]
+
+const EXPECTED_LABEL_KEYS = ["name", "title"]
+const EXPECTED_DIMENSION_KEYS = [
+	"speed",
+	"quality",
+	"focus",
+	"collaboration",
+	"execution",
+]
+const SERIES_COLORS = [
+	"var(--series-1)",
+	"var(--series-2)",
+	"var(--series-3)",
+	"var(--series-4)",
+	"var(--series-5)",
+	"var(--series-6)",
+]
+
+function isFiniteNumber(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value)
+}
+
+function formatDimensionLabel(key: string): string {
+	return key.replace(/([a-z])([A-Z])/g, "$1 $2")
+}
+
+function getLabelKey(items: NotionDataSourcePage[]): string | undefined {
+	for (const key of EXPECTED_LABEL_KEYS) {
+		if (items.some(item => typeof item.propertiesByKey[key] === "string")) {
+			return key
+		}
+	}
+	return undefined
+}
+
+function analyzeRadarSchema(
+	items: NotionDataSourcePage[],
+): RadarSchemaAnalysis {
+	const labelKey = getLabelKey(items)
+	const missingFields: string[] = []
+
+	if (!labelKey) {
+		missingFields.push("name (or title)")
+	}
+
+	for (const key of EXPECTED_DIMENSION_KEYS) {
+		if (!items.some(item => isFiniteNumber(item.propertiesByKey[key]))) {
+			missingFields.push(key)
+		}
+	}
+
+	return {
+		labelKey,
+		missingFields,
+		isReady: missingFields.length === 0,
+	}
+}
+
+function getRoundedMaxValue(
+	items: NotionDataSourcePage[],
+	keys: string[],
+): number {
+	const maxValue = items.reduce((currentMax, item) => {
+		return keys.reduce((rowMax, key) => {
+			const value = item.propertiesByKey[key]
+			return isFiniteNumber(value) ? Math.max(rowMax, value) : rowMax
+		}, currentMax)
+	}, 0)
+
+	if (maxValue <= 10) {
+		return 10
+	}
+
+	if (maxValue <= 100) {
+		return Math.ceil(maxValue / 10) * 10
+	}
+
+	return Math.ceil(maxValue / 25) * 25
+}
+
+function RadarChart(props: {
+	items: NotionDataSourcePage[]
+	isUsingFallbackData: boolean
+	analysis: RadarSchemaAnalysis
+	queryError: string | undefined
+	hasMore: boolean
+	isLoading: boolean
+	onFetchMore: () => void
+}) {
+	const {
+		items,
+		isUsingFallbackData,
+		analysis,
+		queryError,
+		hasMore,
+		isLoading,
+		onFetchMore,
+	} = props
+
+	const { labelKey } = analysis
+	const dimensionKeys = EXPECTED_DIMENSION_KEYS
+	const maxValue = React.useMemo(
+		() => getRoundedMaxValue(items, dimensionKeys),
+		[dimensionKeys, items],
+	)
+	const chartSize = 520
+	const radius = 170
+	const levels = 4
+	const labelRadius = radius + 34
+	const angleStep =
+		dimensionKeys.length > 0 ? (Math.PI * 2) / dimensionKeys.length : 0
+
+	// Center the chart's bounding box (including labels) within the viewBox.
+	// The pentagon is asymmetric vertically: with a vertex pointing up, the
+	// top vertex sits at -radius from center, but the bottom vertices only
+	// reach +radius * sin(54°) ≈ +0.809 * radius. Account for label sizing
+	// so the chart looks visually centered.
+	const verticalExtents = React.useMemo(() => {
+		let topMost = 0
+		let bottomMost = 0
+		for (let i = 0; i < dimensionKeys.length; i += 1) {
+			const angle = -Math.PI / 2 + angleStep * i
+			const labelY = Math.sin(angle) * labelRadius
+			const isAbove = labelY < -10
+			const isBelow = labelY > 10
+			const textHalfHeight = 6
+			const top = isAbove
+				? labelY - textHalfHeight * 2
+				: labelY - textHalfHeight
+			const bottom = isBelow
+				? labelY + textHalfHeight * 2
+				: labelY + textHalfHeight
+			if (top < topMost) {
+				topMost = top
+			}
+			if (bottom > bottomMost) {
+				bottomMost = bottom
+			}
+		}
+		return { topMost, bottomMost }
+	}, [angleStep, dimensionKeys.length, labelRadius])
+
+	const cx = chartSize / 2
+	const cy =
+		chartSize / 2 - (verticalExtents.topMost + verticalExtents.bottomMost) / 2
+
+	const series = React.useMemo<RadarSeries[]>(() => {
+		return items.map((item, index) => {
+			const labelValue = labelKey ? item.propertiesByKey[labelKey] : undefined
+			return {
+				id: item.id,
+				label:
+					(typeof labelValue === "string" && labelValue) ||
+					`Series ${index + 1}`,
+				color: SERIES_COLORS[index % SERIES_COLORS.length],
+				values: dimensionKeys.map(key => {
+					const value = item.propertiesByKey[key]
+					return isFiniteNumber(value) ? value : 0
+				}),
+			}
+		})
+	}, [dimensionKeys, items, labelKey])
+
+	function getPoint(value: number, index: number) {
+		const ratio = Math.max(0, Math.min(1, value / maxValue))
+		const angle = -Math.PI / 2 + angleStep * index
+		return {
+			x: cx + Math.cos(angle) * radius * ratio,
+			y: cy + Math.sin(angle) * radius * ratio,
+		}
+	}
+
+	function getPath(values: number[]) {
+		return (
+			values
+				.map((value, index) => {
+					const point = getPoint(value, index)
+					return `${index === 0 ? "M" : "L"} ${point.x} ${point.y}`
+				})
+				.join(" ") + " Z"
+		)
+	}
+
+	return (
+		<div className="grid gap-5">
+			<div className="rounded-xl border border-(--border) bg-(--card-bg) px-4 py-4 text-sm leading-6 text-(--muted)">
+				{isUsingFallbackData
+					? "Showing fake sample data until a collection is mapped."
+					: `Showing ${items.length} row${items.length === 1 ? "" : "s"} from the mapped collection.`}
+				{queryError ? ` Query note: ${queryError}` : ""}
+			</div>
+
+			<div className="grid grid-cols-[minmax(0,1fr)_220px] items-start gap-6">
+				<div className="overflow-x-auto rounded-2xl border border-(--border) bg-(--surface-bg) p-5">
+					<svg
+						className="block h-auto min-w-[360px] w-full"
+						viewBox={`0 0 ${chartSize} ${chartSize}`}
+					>
+						{Array.from({ length: levels }, (_, levelIndex) => {
+							const level = (levelIndex + 1) / levels
+							const points = dimensionKeys
+								.map((_, index) => {
+									const angle = -Math.PI / 2 + angleStep * index
+									const x = cx + Math.cos(angle) * radius * level
+									const y = cy + Math.sin(angle) * radius * level
+									return `${x},${y}`
+								})
+								.join(" ")
+
+							return (
+								<polygon
+									key={level}
+									points={points}
+									fill="none"
+									stroke="var(--grid-stroke)"
+									strokeWidth={1}
+								/>
+							)
+						})}
+
+						{dimensionKeys.map((key, index) => {
+							const angle = -Math.PI / 2 + angleStep * index
+							const cosA = Math.cos(angle)
+							const sinA = Math.sin(angle)
+							const axisX = cx + cosA * radius
+							const axisY = cy + sinA * radius
+							const labelX = cx + cosA * labelRadius
+							const labelY = cy + sinA * labelRadius
+							const horizontalThreshold = 0.15
+
+							return (
+								<g key={key}>
+									<line
+										x1={cx}
+										y1={cy}
+										x2={axisX}
+										y2={axisY}
+										stroke="var(--grid-stroke)"
+										strokeWidth={1}
+									/>
+									<text
+										x={labelX}
+										y={labelY}
+										fill="var(--foreground)"
+										fontSize={12}
+										textAnchor={
+											Math.abs(cosA) < horizontalThreshold
+												? "middle"
+												: cosA < 0
+													? "end"
+													: "start"
+										}
+										dominantBaseline={
+											Math.abs(sinA) < horizontalThreshold
+												? "middle"
+												: sinA < 0
+													? "auto"
+													: "hanging"
+										}
+									>
+										{formatDimensionLabel(key)}
+									</text>
+								</g>
+							)
+						})}
+
+						{series.map(seriesItem => (
+							<path
+								key={seriesItem.id}
+								d={getPath(seriesItem.values)}
+								fill={seriesItem.color}
+								fillOpacity={0.14}
+								stroke={seriesItem.color}
+								strokeWidth={2}
+							/>
+						))}
+
+						{series.flatMap(seriesItem =>
+							seriesItem.values.map((value, index) => {
+								const point = getPoint(value, index)
+								return (
+									<circle
+										key={`${seriesItem.id}-${dimensionKeys[index]}`}
+										cx={point.x}
+										cy={point.y}
+										r={4}
+										fill={seriesItem.color}
+									/>
+								)
+							}),
+						)}
+					</svg>
+				</div>
+
+				<div className="rounded-2xl border border-(--border) bg-(--card-bg) p-5">
+					<div className="mb-3 text-base font-semibold text-(--foreground)">
+						Legend
+					</div>
+					<div className="mb-5 grid gap-2.5">
+						{series.map(seriesItem => (
+							<div
+								key={seriesItem.id}
+								className="grid grid-cols-[12px_minmax(0,1fr)] items-center gap-2.5"
+							>
+								<div
+									className="h-3 w-3 rounded-full"
+									style={{
+										background: seriesItem.color,
+									}}
+								/>
+								<div className="text-sm text-(--foreground)">
+									{seriesItem.label}
+								</div>
+							</div>
+						))}
+					</div>
+
+					<div className="text-[13px] leading-[1.7] text-(--muted)">
+						<div>Max scale: {maxValue}</div>
+						<div>Label field: {labelKey ?? "name"}</div>
+						<div>Dimensions: {dimensionKeys.join(", ")}</div>
+					</div>
+
+					{hasMore ? (
+						<button
+							onClick={onFetchMore}
+							disabled={isLoading}
+							className="mt-4 w-full rounded-lg border border-(--border) bg-(--surface-bg) px-3 py-2.5 text-(--foreground)"
+							style={{ cursor: isLoading ? "progress" : "pointer" }}
+						>
+							{isLoading ? "Loading..." : "Fetch more"}
+						</button>
+					) : null}
+				</div>
+			</div>
+		</div>
+	)
+}
+
+function SetupHint(props: {
+	missingFields: string[]
+	dataSourceKey: string
+	isUsingFallbackData: boolean
+}) {
+	const { missingFields, dataSourceKey, isUsingFallbackData } = props
+
+	return (
+		<div className="mb-6 rounded-[14px] border border-(--border) bg-(--card-bg) p-5">
+			<div className="mb-2 text-lg font-semibold text-(--foreground)">
+				Set up the source database
+			</div>
+			<div className="mb-3 text-sm leading-[1.7] text-(--muted)">
+				This demo is hardcoded to one radar schema. Map a data source with key{" "}
+				<code>{dataSourceKey}</code> and create these exact semantic fields:
+			</div>
+			<div className="mb-3 text-sm leading-[1.8] text-(--foreground)">
+				<div>
+					<code>name</code> or <code>title</code> as the row label
+				</div>
+				<div>
+					<code>speed</code>, <code>quality</code>, <code>focus</code>,{" "}
+					<code>collaboration</code>, <code>execution</code> as number columns
+				</div>
+			</div>
+			{missingFields.length > 0 ? (
+				<div className="text-sm leading-[1.7] text-(--muted)">
+					Missing right now: <code>{missingFields.join(", ")}</code>
+				</div>
+			) : null}
+			<div className="mt-3 text-sm leading-[1.7] text-(--muted)">
+				{isUsingFallbackData
+					? "Showing built-in sample data below until the mapped collection matches this schema."
+					: "Showing your mapped collection below."}
+			</div>
+		</div>
+	)
+}
+
+function App() {
+	const theme = useTheme()
+	const dataSources = useDataSourceDefinitions()
+	const activeDataSourceKey = dataSources[0]?.key ?? "default"
+	const query = useDataSource(activeDataSourceKey)
+	const colorTheme = theme === "dark" ? "dark" : "light"
+	const mappedAnalysis = analyzeRadarSchema(query.items)
+	const isUsingFallbackData = !mappedAnalysis.isReady
+	const items = isUsingFallbackData ? FAKE_ITEMS : query.items
+	const analysis = isUsingFallbackData
+		? analyzeRadarSchema(FAKE_ITEMS)
+		: mappedAnalysis
+
+	return (
+		<div
+			data-theme={colorTheme}
+			className="bg-(--app-bg) p-8 text-(--foreground)"
+		>
+			<div className="mb-6">
+				<h1 className="mb-2 text-[32px] font-bold leading-tight tracking-[-0.03em]">
+					Radar Chart
+				</h1>
+				<p className="m-0 max-w-[760px] text-[15px] leading-6 text-(--muted)">
+					Each row in the mapped collection becomes one spider-chart polygon.
+					One text field is used for the legend, and this demo expects one fixed
+					set of score columns.
+				</p>
+			</div>
+
+			<div className="mb-6 grid grid-cols-[repeat(auto-fit,minmax(220px,1fr))] gap-5">
+				{[
+					{
+						label: "Active data source",
+						value: activeDataSourceKey,
+					},
+					{
+						label: "Rows",
+						value: String(items.length),
+					},
+					{
+						label: "Mode",
+						value: isUsingFallbackData
+							? "Sample preview data"
+							: "Mapped collection",
+					},
+				].map(card => (
+					<div
+						key={card.label}
+						className="rounded-[14px] border border-(--border) bg-(--card-bg) p-[18px]"
+					>
+						<div className="mb-2 text-xs font-semibold uppercase tracking-[0.04em] text-(--muted)">
+							{card.label}
+						</div>
+						<div className="text-lg font-semibold text-(--foreground)">
+							{card.value}
+						</div>
+					</div>
+				))}
+			</div>
+
+			{isUsingFallbackData ? (
+				<SetupHint
+					missingFields={mappedAnalysis.missingFields}
+					dataSourceKey={activeDataSourceKey}
+					isUsingFallbackData={isUsingFallbackData}
+				/>
+			) : null}
+
+			<RadarChart
+				items={items}
+				isUsingFallbackData={isUsingFallbackData}
+				analysis={analysis}
+				queryError={query.error}
+				hasMore={query.hasMore}
+				isLoading={query.isLoading}
+				onFetchMore={query.fetchMore}
+			/>
+		</div>
+	)
+}
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+	<NotionCustomBlock>
+		<App />
+	</NotionCustomBlock>,
+)

package/templates/radar-chart/tsconfig.json

@@ -0,0 +1,17 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"strict": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"types": ["vite/client"],
+		"lib": ["ES2022", "DOM", "DOM.Iterable"],
+		"skipLibCheck": true,
+		"esModuleInterop": true,
+		"isolatedModules": true,
+		"jsx": "react-jsx"
+	},
+	"include": ["src", "vite.config.ts"]
+}

package/templates/radar-chart/vite.config.ts

@@ -0,0 +1,8 @@
+import tailwindcss from "@tailwindcss/vite"
+import react from "@vitejs/plugin-react"
+import { notionCustomBlock } from "ncblock/vite"
+import { defineConfig } from "vite"
+
+export default defineConfig({
+	plugins: [react(), tailwindcss(), notionCustomBlock()],
+})

package/templates/table-view/README.md

@@ -0,0 +1,43 @@
+# {{name}}
+
+A [Notion custom view](https://developers.notion.com) block.
+
+## Development
+
+```bash
+npm run dev    # Start Vite dev server
+npm run build  # Build to dist/
+```
+
+From the repo root you can also run just this template with:
+
+```bash
+pnpm --filter table-view dev
+```
+
+If you run `pnpm run dev` at the repo root, every template starts at once and
+`table-view` is available at `http://localhost:9882`.
+
+## Project structure
+
+```text
+src/
+  index.tsx    # TanStack Table-powered custom view
+  index.css    # Tailwind CSS entrypoint
+index.html     # Vite entry HTML
+custom_blocks.json # Manifest declaring required data sources (served at runtime)
+dist/              # Built output: index.html + assets/ + custom_blocks.json
+```
+
+This template includes Tailwind by default and renders every supported
+`ncblock` value shape: text, numbers, booleans, dates,
+string arrays, and relations. It also includes search, column visibility
+controls, density switching, and relation pills that render `-> title` when a
+related page is loaded or `-> uuid` when it is not.
+
+## SDK hooks
+
+- **`useCustomBlockContext()`** -- returns `{ customBlockId, parent, page }` describing the block's location in the document tree
+- **`useTheme()`** -- returns the host's current theme (`"light"` or `"dark"`)
+- **`useDataSourceDefinitions()`** -- returns resolved data-source definitions
+- **`useDataSource(key)`** -- returns `{ items, collectionSchema, propertySchemasById, propertySchemasByKey, isLoading, hasMore, fetchMore, error }`. Each `item` has `{ id, propertiesById, propertiesByKey }`. The four built-ins (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`) appear in `propertiesById` / `propertySchemasById`, never in the `*ByKey` views.

package/templates/table-view/_gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

package/templates/table-view/custom_blocks.json

@@ -0,0 +1,9 @@
+{
+	"version": 1,
+	"dataSources": {
+		"default": {
+			"name": "Table data",
+			"description": "Rows to render in the tabular view."
+		}
+	}
+}