{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "chart-10", "title": "Dot histogram", "description": "A distribution stacked from dots with a target pin you drag, flick or move with the arrow keys, where the pin catches on each column and the dots past it turn red one column after the other while the sentence on top counts them.", "dependencies": [], "registryDependencies": [ "https://ui.ndekocode.dev/r/badge.json", "https://ui.ndekocode.dev/r/demonstration.json", "https://ui.ndekocode.dev/r/motion-number.json", "https://ui.ndekocode.dev/r/motion-word-roll.json", "https://ui.ndekocode.dev/r/theme.json", "https://ui.ndekocode.dev/r/use-autoplay.json", "https://ui.ndekocode.dev/r/use-kept-height.json", "https://ui.ndekocode.dev/r/use-timeouts.json", "https://ui.ndekocode.dev/r/utils.json" ], "files": [ { "path": "registry/ndeko/components/chart/chart-10.tsx", "content": "'use client';\n\nimport { useState } from 'react';\n\nimport { MotionNumber } from '@/components/core/motion-number';\nimport { WordRoll } from '@/components/core/word-roll';\nimport type { AutoplayStep } from '@/registry/ndeko/hooks/use-autoplay';\nimport { hold } from '@/registry/ndeko/lib/demonstration';\nimport { cn } from '@/registry/ndeko/lib/utils';\n\nimport { CategoryAxis, LABEL_ROOM_PX, type AxisLabel } from './_parts/axis';\nimport { ChartCard } from './_parts/chart-card';\nimport { DataTable, type DataRow } from './_parts/data-table';\nimport { walkSteps } from './_parts/demo';\nimport { formatCount } from './_parts/format';\nimport { PLOT_SURFACE } from './_parts/plot';\nimport { clamp, positionsTo, sumOf } from './_parts/scale';\nimport { useChartDemo } from './_parts/use-chart-demo';\nimport { usePlotWidth } from './_parts/use-plot-width';\nimport { useStepDrag } from './_parts/use-step-drag';\n\nexport type HistogramBin = {\n /** Where the bin starts and where it ends, in the unit of the measure. */\n from: number;\n to: number;\n /** How many readings fell in it. */\n count: number;\n};\n\nexport type DotHistogramProps = {\n title: string;\n /** A short mark beside the title, such as \"Illustrative\" over sample data. */\n note?: string;\n /** The bins from the lowest to the highest, each as wide as the others. */\n bins: readonly HistogramBin[];\n /** How many readings one dot stands for. */\n perDot: number;\n /** The edge the target sits on: 0 is before the first bin, `bins.length` is after the last. */\n targetEdge: number;\n onTargetEdgeChange: (edge: number) => void;\n /** The unit of the measure, written after a figure: \"ms\". */\n unit: string;\n /** What is counted, in the plural: \"requests\". */\n noun: string;\n className?: string;\n};\n\nconst DOT_PX = 10;\n\nconst DOT_GAP_PX = 2;\n\nconst DOT_PITCH_PX = DOT_PX + DOT_GAP_PX;\n\n/** Room above the tallest column for the label of the target. */\nconst PIN_ROOM_PX = 28;\n\n/** Columns change colour one after the other, starting from the one beside the pin. */\nconst STAGGER_MS = 30;\n\n/** One label of the axis every this many edges: the first step that leaves each label its room, so the values stay round. */\nconst LABEL_STEPS = [4, 8];\n\nconst WIDEST_LABEL_STEP = 16;\n\nconst FALLBACK_WIDTH = 420;\n\nfunction labelStepFor(binCount: number, plotWidth: number) {\n for (const step of LABEL_STEPS) {\n const gapCount = Math.floor(binCount / step);\n const labelCount = gapCount + 1;\n const room = plotWidth / labelCount;\n if (room >= LABEL_ROOM_PX) {\n return step;\n }\n }\n return WIDEST_LABEL_STEP;\n}\n\nfunction dotCountOf(bin: HistogramBin, perDot: number) {\n const dots = bin.count / perDot;\n return Math.round(dots);\n}\n\nfunction tallestOf(bins: readonly HistogramBin[], perDot: number) {\n let tallest = 1;\n for (const bin of bins) {\n const dots = dotCountOf(bin, perDot);\n tallest = Math.max(tallest, dots);\n }\n return tallest;\n}\n\n/** The value an edge sits on: the start of the bin after it, or the end of the last bin. */\nfunction edgeValueOf(bins: readonly HistogramBin[], edge: number) {\n const bin = bins[edge];\n if (bin) {\n return bin.from;\n }\n const last = bins.at(-1);\n return last?.to ?? 0;\n}\n\nfunction countPast(bins: readonly HistogramBin[], edge: number) {\n const past = bins.slice(edge);\n const counts = past.map((bin) => bin.count);\n return sumOf(counts);\n}\n\n/** How many columns lie between a column and the pin, on whichever side of it the column is. */\nfunction distanceFromPin(column: number, edge: number) {\n if (column >= edge) {\n return column - edge;\n }\n const lastBefore = edge - 1;\n return lastBefore - column;\n}\n\nfunction dotToneOf(isPastTarget: boolean) {\n if (isPastTarget) {\n return 'bg-destructive';\n }\n return 'bg-primary';\n}\n\ntype DotColumnProps = {\n dotCount: number;\n isPastTarget: boolean;\n /** How many columns away from the pin this one is: the further, the later it changes colour. */\n distance: number;\n};\n\nfunction DotColumn({ dotCount, isPastTarget, distance }: DotColumnProps) {\n const dots = Array.from({ length: dotCount }, (_, index) => index);\n const delayMs = distance * STAGGER_MS;\n\n return (\n \n {dots.map((dot) => (\n \n ))}\n \n );\n}\n\nfunction axisLabelsOf(\n bins: readonly HistogramBin[],\n unit: string,\n plotWidth: number\n) {\n const edgeCount = bins.length + 1;\n const edges = Array.from({ length: edgeCount }, (_, edge) => edge);\n const step = labelStepFor(bins.length, plotWidth);\n const written = edges.filter((edge) => edge % step === 0);\n return written.map((edge): AxisLabel => {\n const edgeValue = edgeValueOf(bins, edge);\n const value = formatCount(edgeValue);\n const isLast = edge === bins.length;\n return {\n id: String(edge),\n text: labelTextOf(value, unit, isLast),\n ratio: edge / bins.length,\n };\n });\n}\n\n/** Only the last label carries the unit, so the axis is not a row of the same two letters. */\nfunction labelTextOf(value: string, unit: string, isLast: boolean) {\n if (isLast) {\n return `${value}${unit}`;\n }\n return value;\n}\n\nfunction rangeTextOf(bin: HistogramBin, unit: string) {\n const from = formatCount(bin.from);\n const to = formatCount(bin.to);\n return `${from} to ${to}${unit}`;\n}\n\nfunction standingOf(isPastTarget: boolean) {\n if (isPastTarget) {\n return 'Slower than the target';\n }\n return 'Within the target';\n}\n\nexport function DotHistogram({\n title,\n note,\n bins,\n perDot,\n targetEdge,\n onTargetEdgeChange,\n unit,\n noun,\n className,\n}: DotHistogramProps) {\n const { plotRef, width } = usePlotWidth(FALLBACK_WIDTH);\n const binCount = Math.max(bins.length, 1);\n const edge = clamp(targetEdge, 0, bins.length);\n const drag = useStepDrag({\n count: bins.length + 1,\n index: edge,\n onIndexChange: onTargetEdgeChange,\n placement: 'edges',\n });\n const tallest = tallestOf(bins, perDot);\n const columnsHeight = tallest * DOT_PITCH_PX;\n const plotHeight = columnsHeight + PIN_ROOM_PX;\n const counts = bins.map((bin) => bin.count);\n const counted = sumOf(counts);\n const total = Math.max(counted, 1);\n const slowCount = countPast(bins, edge);\n const slowShare = slowCount / total;\n const slowPercent = Math.round(slowShare * 100);\n const edgeValue = edgeValueOf(bins, edge);\n const targetValue = formatCount(edgeValue);\n const targetText = `${targetValue}${unit}`;\n const sentence = `${slowPercent}% of ${noun} are slower than ${targetText}`;\n const pinRatio = edge / binCount;\n const pinShare = pinRatio * 100;\n\n const rows: DataRow[] = bins.map((bin, column) => ({\n id: String(bin.from),\n label: rangeTextOf(bin, unit),\n cells: [formatCount(bin.count), standingOf(column >= edge)],\n }));\n\n return (\n \n

\n \n \n of {noun} are slower than{' '}\n \n \n

\n
\n \n {bins.map((bin, column) => (\n = edge}\n distance={distanceFromPin(column, edge)}\n />\n ))}\n
\n \n ))}\n \n );\n}\n\n/** Zero is drawn stronger when values go below it, since bars start there. */\nexport function gridToneOf(tick: number, scale: Scale) {\n const isZero = tick === 0;\n const crossesZero = scale.min < 0;\n if (isZero && crossesZero) {\n return 'border-foreground/25';\n }\n return 'border-border';\n}\n\ntype GridLinesProps = {\n scale: Scale;\n height: number;\n};\n\nexport function GridLines({ scale, height }: GridLinesProps) {\n return (\n \n );\n}\n\nexport type AxisLabel = {\n id: string;\n text: string;\n /** From 0 at the left edge of the plot to 1 at its right edge. */\n ratio: number;\n isStrong?: boolean;\n};\n\n/** Every how many positions a label is written, so the labels that are written never touch. */\nexport function labelStepOf(count: number, plotWidth: number) {\n const fitting = Math.floor(plotWidth / LABEL_ROOM_PX);\n const labelCount = Math.max(fitting, 1);\n const step = Math.ceil(count / labelCount);\n return Math.max(step, 1);\n}\n\n/** The labels kept when one in `step` is written, counted back from the last so the latest is always named. */\nexport function spacedLabelsOf(labels: readonly AxisLabel[], step: number) {\n const lastIndex = labels.length - 1;\n return labels.filter((_, index) => {\n const fromLast = lastIndex - index;\n return fromLast % step === 0;\n });\n}\n\n/**\n * One label per position, under the middle of its column, written as often as the room allows. The\n * one at `strongIndex`, such as today, is set stronger.\n */\nexport function positionLabelsOf(\n labels: readonly string[],\n plotWidth: number,\n strongIndex?: number\n) {\n const all: AxisLabel[] = labels.map((text, index) => ({\n id: `${index}-${text}`,\n text,\n ratio: columnCenterOf(index, labels.length),\n isStrong: index === strongIndex,\n }));\n const step = labelStepOf(labels.length, plotWidth);\n return spacedLabelsOf(all, step);\n}\n\nfunction strongOf(isStrong: boolean | undefined) {\n if (isStrong) {\n return 'text-foreground font-medium';\n }\n return 'text-muted-foreground';\n}\n\ntype LabelAlign = 'spread' | 'center';\n\n/**\n * A spread label slides from its left edge to its right edge as it crosses the plot, like the\n * readout, so the first and the last never stick out of the piece. A centred label sits under its\n * mark, for the few wide columns of a bar chart.\n */\nfunction labelStyleOf(\n label: AxisLabel,\n align: LabelAlign\n): React.CSSProperties {\n const left = percentOf(label.ratio);\n if (align === 'center') {\n return { left, transform: 'translateX(-50%)' };\n }\n const shift = percentOf(-label.ratio);\n return { left, transform: `translateX(${shift})` };\n}\n\ntype CategoryAxisProps = {\n labels: readonly AxisLabel[];\n align?: LabelAlign;\n className?: string;\n};\n\nexport function CategoryAxis({\n labels,\n align = 'spread',\n className,\n}: CategoryAxisProps) {\n return (\n \n );\n}\n", "type": "registry:component", "target": "components/chart/_parts/axis.tsx" }, { "path": "registry/ndeko/components/chart/_parts/chart-card.tsx", "content": "import { useId } from 'react';\n\nimport { cn } from '@/registry/ndeko/lib/utils';\nimport { Badge } from '@/registry/ndeko/ui/badge';\n\ntype ChartCardProps = {\n title: string;\n /** A short mark beside the title, such as \"Illustrative\" over sample data. */\n note?: string;\n /** One line that says what the chart shows, read by screen readers with the title. */\n summary: string;\n /** Controls that change what the chart draws: a period, a view. */\n actions?: React.ReactNode;\n className?: string;\n children: React.ReactNode;\n};\n\n/**\n * The surface every chart sits on. It is a query container, so a chart lays itself out by the\n * room it has, and it is positioned, so the hidden table of a chart never widens the page.\n */\nexport function ChartCard({\n title,\n note,\n summary,\n actions,\n className,\n children,\n}: ChartCardProps) {\n const titleId = useId();\n const summaryId = useId();\n\n return (\n \n
\n
\n

\n {title}\n

\n {note && {note}}\n
\n {actions}\n
\n {children}\n

\n {summary}\n

\n \n );\n}\n", "type": "registry:component", "target": "components/chart/_parts/chart-card.tsx" }, { "path": "registry/ndeko/components/chart/_parts/data-table.tsx", "content": "export type DataRow = {\n id: string;\n /** The heading of the row: a day, a category, a step. */\n label: string;\n cells: readonly string[];\n};\n\ntype DataTableProps = {\n caption: string;\n /** The heading of the label column first, then one per cell. */\n columns: readonly string[];\n rows: readonly DataRow[];\n};\n\n/**\n * The numbers a chart draws, as a table for screen readers. It is taken out of the flow, so the\n * piece it sits in has to be positioned: a hidden box inside an area that scrolls sideways widens\n * the page otherwise.\n */\nexport function DataTable({ caption, columns, rows }: DataTableProps) {\n return (\n \n \n \n \n {columns.map((column) => (\n \n ))}\n \n \n \n {rows.map((row) => (\n \n \n {row.cells.map((cell, index) => (\n \n ))}\n \n ))}\n \n
{caption}
\n {column}\n
{row.label}{cell}
\n );\n}\n", "type": "registry:component", "target": "components/chart/_parts/data-table.tsx" }, { "path": "registry/ndeko/components/chart/_parts/demo.ts", "content": "import type { AutoplayStep } from '@/registry/ndeko/hooks/use-autoplay';\nimport { keyDelayOf } from '@/registry/ndeko/lib/demonstration';\n\ntype WalkOptions = {\n /** Milliseconds before the first position. */\n startAfter?: number;\n /** Milliseconds between two positions. */\n stepMs?: number;\n};\n\n/** One step per position, so a reading crosses a plot the way a pointer does. */\nexport function walkSteps(\n positions: readonly Position[],\n moveTo: (position: Position) => void,\n { startAfter = 700, stepMs = 240 }: WalkOptions = {}\n): AutoplayStep[] {\n return positions.map((position, index) => {\n const after = keyDelayOf(index, startAfter, stepMs);\n return { after, run: () => moveTo(position) };\n });\n}\n\n/** What a demonstration points at lets go the moment a person takes over. */\nexport function whileDemonstrating(\n isDemonstrating: boolean,\n value: Value | null\n) {\n if (isDemonstrating) {\n return value;\n }\n return null;\n}\n", "type": "registry:component", "target": "components/chart/_parts/demo.ts" }, { "path": "registry/ndeko/components/chart/_parts/format.ts", "content": "const LOCALE = 'en-US';\n\nexport const COUNT_FORMAT: Intl.NumberFormatOptions = {\n maximumFractionDigits: 0,\n};\n\nexport const SIGNED_FORMAT: Intl.NumberFormatOptions = {\n maximumFractionDigits: 0,\n signDisplay: 'exceptZero',\n};\n\nexport const USD_COMPACT_FORMAT: Intl.NumberFormatOptions = {\n style: 'currency',\n currency: 'USD',\n notation: 'compact',\n maximumFractionDigits: 1,\n};\n\nconst COMPACT_FORMAT: Intl.NumberFormatOptions = {\n notation: 'compact',\n maximumFractionDigits: 1,\n};\n\nconst COUNT = new Intl.NumberFormat(LOCALE, COUNT_FORMAT);\n\nconst SIGNED = new Intl.NumberFormat(LOCALE, SIGNED_FORMAT);\n\nconst COMPACT = new Intl.NumberFormat(LOCALE, COMPACT_FORMAT);\n\nconst USD_COMPACT = new Intl.NumberFormat(LOCALE, USD_COMPACT_FORMAT);\n\nconst DAY = new Intl.DateTimeFormat(LOCALE, {\n month: 'short',\n day: 'numeric',\n timeZone: 'UTC',\n});\n\nconst MS_PER_DAY = 86_400_000;\n\nexport function formatCount(value: number) {\n return COUNT.format(value);\n}\n\nexport function formatSigned(value: number) {\n return SIGNED.format(value);\n}\n\nexport function formatCompact(value: number) {\n return COMPACT.format(value);\n}\n\nexport function formatUsd(value: number) {\n return USD_COMPACT.format(value);\n}\n\nexport function formatShare(share: number) {\n const percent = Math.round(share * 100);\n return `${percent}%`;\n}\n\n/** A start at zero has no percentage to grow from: it reads as no change. */\nexport function percentChangeOf(current: number, previous: number) {\n if (previous === 0) {\n return 0;\n }\n const difference = current - previous;\n const ratio = difference / Math.abs(previous);\n return Math.round(ratio * 100);\n}\n\nexport function changeWordsOf(percent: number, reference: string) {\n if (percent === 0) {\n return `level with ${reference}`;\n }\n const size = Math.abs(percent);\n if (percent > 0) {\n return `up ${size}% on ${reference}`;\n }\n return `down ${size}% on ${reference}`;\n}\n\nexport function nounOf(count: number, singular: string, plural: string) {\n if (count === 1) {\n return singular;\n }\n return plural;\n}\n\n/**\n * One label per day, or per `everyDays` days for a weekly series. Days are counted in UTC so the\n * server and the browser write the same label.\n */\nexport function dayLabelsOf(firstDay: string, count: number, everyDays = 1) {\n const start = Date.parse(`${firstDay}T00:00:00Z`);\n const stride = everyDays * MS_PER_DAY;\n return Array.from({ length: count }, (_, index) => {\n const elapsed = index * stride;\n return DAY.format(start + elapsed);\n });\n}\n", "type": "registry:component", "target": "components/chart/_parts/format.ts" }, { "path": "registry/ndeko/components/chart/_parts/path.ts", "content": "import { columnCenterOf, lerp, ratioOf, type Domain } from './scale';\n\nexport type Point = {\n x: number;\n y: number;\n};\n\n/** Paths are drawn in a box this wide and stretched to the plot, so a change of width never redraws them. */\nexport const VIEW_WIDTH = 1000;\n\nfunction commandOf(point: Point, index: number) {\n const x = point.x.toFixed(1);\n const y = point.y.toFixed(1);\n if (index === 0) {\n return `M${x} ${y}`;\n }\n return `L${x} ${y}`;\n}\n\nexport function linePathOf(points: readonly Point[]) {\n const commands = points.map((point, index) => commandOf(point, index));\n return commands.join(' ');\n}\n\n/** The line closed down (or up) to a level, for the wash under a line. */\nexport function areaPathOf(points: readonly Point[], levelY: number) {\n if (points.length === 0) {\n return '';\n }\n const line = linePathOf(points);\n const lastIndex = points.length - 1;\n const firstX = points[0].x.toFixed(1);\n const lastX = points[lastIndex].x.toFixed(1);\n const level = levelY.toFixed(1);\n return `${line} L${lastX} ${level} L${firstX} ${level} Z`;\n}\n\n/** The surface between two lines that share their x positions, for a range around a line. */\nexport function bandPathOf(upper: readonly Point[], lower: readonly Point[]) {\n if (upper.length === 0) {\n return '';\n }\n const backwards = [...lower].reverse();\n const outline = [...upper, ...backwards];\n const line = linePathOf(outline);\n return `${line} Z`;\n}\n\n/** The pixel height of a value in a plot: the top of the domain is 0, its bottom is the plot height. */\nexport function yOf(value: number, domain: Domain, height: number) {\n const ratio = ratioOf(value, domain);\n const fromBottom = ratio * height;\n return height - fromBottom;\n}\n\n/** One point per value, each in the middle of its column. */\nexport function plotPointsOf(\n values: readonly number[],\n domain: Domain,\n height: number\n): Point[] {\n return values.map((value, index) => {\n const share = columnCenterOf(index, values.length);\n const x = share * VIEW_WIDTH;\n const y = yOf(value, domain, height);\n return { x, y };\n });\n}\n\n/** How many of the pieces lie before a segment when they are shared out evenly. */\nfunction piecesBefore(\n segment: number,\n segmentCount: number,\n pieceCount: number\n) {\n const share = segment / segmentCount;\n return Math.floor(share * pieceCount);\n}\n\n/**\n * The same line through exactly `count` points: each segment is cut into equal parts, so two lines\n * of different lengths share one structure and one can glide into the other.\n */\nexport function densifyOf(points: readonly Point[], count: number): Point[] {\n const segmentCount = points.length - 1;\n const hasSegments = segmentCount >= 1;\n const hasRoom = count > points.length;\n if (!hasSegments || !hasRoom) {\n return [...points];\n }\n const pieceCount = count - 1;\n const dense: Point[] = [points[0]];\n for (let segment = 0; segment < segmentCount; segment += 1) {\n const from = points[segment];\n const to = points[segment + 1];\n const start = piecesBefore(segment, segmentCount, pieceCount);\n const end = piecesBefore(segment + 1, segmentCount, pieceCount);\n const parts = end - start;\n for (let part = 1; part <= parts; part += 1) {\n const amount = part / parts;\n const x = lerp(from.x, to.x, amount);\n const y = lerp(from.y, to.y, amount);\n dense.push({ x, y });\n }\n }\n return dense;\n}\n", "type": "registry:component", "target": "components/chart/_parts/path.ts" }, { "path": "registry/ndeko/components/chart/_parts/plot.tsx", "content": "import { cn } from '@/registry/ndeko/lib/utils';\n\nimport { CategoryAxis, GridLines, ValueAxis, type AxisLabel } from './axis';\nimport { VIEW_WIDTH } from './path';\nimport type { Scale } from './scale';\n\n/**\n * A plot is a query container, so the readout and the marks inside it are placed in shares of its\n * width, and it lets the page scroll vertically under a finger while a sideways move reads values.\n */\nexport const PLOT_SURFACE =\n 'focus-visible:ring-ring/25 @container relative touch-pan-y rounded-md outline-none focus-visible:ring-[3px]';\n\ntype PlotFrameProps = {\n /** The name of the plot and how to read it, for screen readers. */\n label: string;\n scale: Scale;\n height: number;\n formatTick: (value: number) => string;\n axisLabels: readonly AxisLabel[];\n axisAlign?: 'spread' | 'center';\n /** Receives the plot element, for a chart that measures the room it has. */\n plotRef?: (element: HTMLDivElement | null) => void;\n /** The handlers of the reading: the plot is the one tab stop of the chart. */\n plotProps?: React.HTMLAttributes;\n plotClassName?: string;\n /** For a chart whose marks carry their own figures, which can drop the axis on a narrow piece. */\n valueAxisClassName?: string;\n /** Labels laid out by the chart itself, in place of one row of `axisLabels`. */\n categoryAxis?: React.ReactNode;\n className?: string;\n children: React.ReactNode;\n};\n\n/**\n * A plot between its value axis on the left and its category axis underneath. Each part has its own\n * cell: placed in turn, a plot whose value axis is hidden would fall into the axis column, which is\n * only as wide as its content, and nothing in a plot has a width of its own, so every mark would\n * stack at the left edge.\n */\nexport function PlotFrame({\n label,\n scale,\n height,\n formatTick,\n axisLabels,\n axisAlign,\n plotRef,\n plotProps,\n plotClassName,\n valueAxisClassName,\n categoryAxis,\n className,\n children,\n}: PlotFrameProps) {\n return (\n \n \n \n \n {children}\n \n
\n {categoryAxis}\n {!categoryAxis && (\n \n )}\n
\n \n );\n}\n\ntype PathLayerProps = {\n height: number;\n className?: string;\n children: React.ReactNode;\n};\n\n/**\n * The layer the paths are drawn in: `VIEW_WIDTH` units across whatever the width of the plot, and\n * real pixels down. Strokes keep their thickness because each path opts out of the stretch.\n */\nexport function PathLayer({ height, className, children }: PathLayerProps) {\n return (\n