{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"line-charts-step-annotations","type":"registry:component","title":"Line charts · Step with annotations","description":"A step line for values that change in jumps, a dashed plan limit and numbered notes that pop a callout on hover or focus and step with arrow keys.","author":"GetUrUI <hello@geturui.dev>","dependencies":["motion","lucide-react"],"registryDependencies":[],"files":[{"path":"registry/geturui/examples/line-charts/step-annotations.tsx","type":"registry:component","target":"components/examples/line-charts/step-annotations.tsx","content":"\"use client\";\n\nimport * as React from \"react\";\nimport { AnimatePresence, motion, useInView, useReducedMotion } from \"motion/react\";\nimport { cn } from \"@/lib/utils\";\n\nexport interface StepAnnotation {\n  /** Index of the point the note belongs to. */\n  index: number;\n  title: string;\n  body: string;\n}\n\nexport interface StepAnnotationsChartProps {\n  title?: string;\n  subtitle?: string;\n  labels?: string[];\n  /** Value held from each label until the next. */\n  values?: number[];\n  annotations?: StepAnnotation[];\n  /** Optional plan limit drawn as a dashed ceiling. */\n  limit?: number;\n  unit?: string;\n  className?: string;\n}\n\nconst LABELS = [\"Oct\", \"Nov\", \"Dec\", \"Jan\", \"Feb\", \"Mar\", \"Apr\", \"May\", \"Jun\", \"Jul\", \"Aug\", \"Sep\"];\nconst VALUES = [14, 14, 18, 18, 18, 31, 31, 34, 34, 27, 29, 38];\nconst NOTES: StepAnnotation[] = [\n  { index: 2, title: \"Support team onboarded\", body: \"Four agents added for the holiday queue.\" },\n  { index: 5, title: \"Design moved to the workspace\", body: \"Thirteen seats migrated from the old tool.\" },\n  { index: 9, title: \"Contractors offboarded\", body: \"Seven guest seats released after the launch.\" },\n  { index: 11, title: \"Annual plan renewed\", body: \"Limit raised to 40 seats at the new rate.\" },\n];\n\n/** Step line for values that change in jumps, with numbered annotations you can hover, focus or step through to read what moved the line. */\nexport function StepAnnotationsChart({\n  title = \"Active seats\",\n  subtitle = \"Workspace members billed each month\",\n  labels = LABELS,\n  values = VALUES,\n  annotations = NOTES,\n  limit = 40,\n  unit = \"seats\",\n  className,\n}: StepAnnotationsChartProps) {\n  const reduce = useReducedMotion() ?? false;\n  const ref = React.useRef<HTMLDivElement>(null);\n  const inView = useInView(ref, { once: true, margin: \"-40px\" });\n  const uid = React.useId().replace(/[^a-zA-Z0-9_-]/g, \"\");\n  const [active, setActive] = React.useState<number | null>(null);\n  const btns = React.useRef<(HTMLButtonElement | null)[]>([]);\n\n  const n = values.length;\n  const top = Math.ceil((Math.max(...values, limit) * 1.1) / 10) * 10;\n  const ticks = [0, top / 2, top];\n  const xp = (i: number) => (i / n) * 100;\n  const yp = (v: number) => (1 - v / top) * 100;\n  const d = values.map((v, i) => `${i ? `H${xp(i).toFixed(2)}V` : `M0,`}${yp(v).toFixed(2)}`).join(\"\") + `H100`;\n  const note = active !== null ? annotations[active] : null;\n\n  function onKey(e: React.KeyboardEvent, i: number) {\n    if (e.key !== \"ArrowLeft\" && e.key !== \"ArrowRight\") return;\n    e.preventDefault();\n    const next = (i + (e.key === \"ArrowRight\" ? 1 : -1) + annotations.length) % annotations.length;\n    btns.current[next]?.focus();\n  }\n\n  return (\n    <figure className={cn(\"@container w-full rounded-xl border border-border bg-surface-raised p-4 shadow-sm sm:p-5\", className)}>\n      <figcaption className=\"flex flex-wrap items-end justify-between gap-2\">\n        <div>\n          <p className=\"text-[15px] font-semibold text-ink\">{title}</p>\n          <p className=\"text-[12.5px] text-ink-subtle\">{subtitle}</p>\n        </div>\n        <p className=\"text-[12px] text-ink-muted\">\n          <span className=\"font-mono text-[18px] font-semibold tabular-nums text-ink\">{values[n - 1]}</span> of {limit} {unit}\n        </p>\n      </figcaption>\n\n      <div className=\"mt-6 grid grid-cols-[1.75rem_minmax(0,1fr)] gap-x-2\">\n        <div aria-hidden className=\"relative h-44 @md:h-52\">\n          {ticks.map((t) => (\n            <span key={t} className=\"absolute right-0 -translate-y-1/2 font-mono text-[10.5px] tabular-nums text-ink-subtle\" style={{ top: `${yp(t)}%` }}>\n              {t}\n            </span>\n          ))}\n        </div>\n        <div ref={ref} className=\"relative h-44 @md:h-52\" onPointerLeave={() => setActive(null)}>\n          <svg\n            role=\"img\"\n            aria-label={`${title}: ${values[0]} in ${labels[0]} to ${values[n - 1]} in ${labels[n - 1]}, against a limit of ${limit}. ${annotations.length} annotated changes listed below.`}\n            viewBox=\"0 0 100 100\"\n            preserveAspectRatio=\"none\"\n            className=\"absolute inset-0 size-full overflow-visible\"\n          >\n            <defs>\n              <linearGradient id={`${uid}-fill`} x1=\"0\" x2=\"0\" y1=\"0\" y2=\"1\">\n                <stop offset=\"0%\" style={{ stopColor: \"var(--volt-ink)\", stopOpacity: 0.18 }} />\n                <stop offset=\"100%\" style={{ stopColor: \"var(--volt-ink)\", stopOpacity: 0 }} />\n              </linearGradient>\n              <clipPath id={`${uid}-reveal`}>\n                <motion.rect x={-2} y={-10} height={120} initial={{ width: reduce ? 104 : 0 }} animate={{ width: inView || reduce ? 104 : 0 }} transition={{ duration: reduce ? 0 : 1.3, ease: [0.65, 0, 0.35, 1] }} />\n              </clipPath>\n            </defs>\n            {ticks.map((t) => (\n              <line key={t} x1={0} x2={100} y1={yp(t)} y2={yp(t)} className=\"stroke-border\" strokeDasharray={t ? \"2 4\" : undefined} vectorEffect=\"non-scaling-stroke\" />\n            ))}\n            <line x1={0} x2={100} y1={yp(limit)} y2={yp(limit)} className=\"stroke-ink-muted\" strokeDasharray=\"6 4\" vectorEffect=\"non-scaling-stroke\" />\n            <g clipPath={`url(#${uid}-reveal)`}>\n              <path d={`${d}V100H0Z`} fill={`url(#${uid}-fill)`} />\n              <path d={d} fill=\"none\" style={{ stroke: \"var(--volt-ink)\" }} strokeWidth={2.25} strokeLinejoin=\"round\" vectorEffect=\"non-scaling-stroke\" />\n            </g>\n            {note && <line x1={xp(note.index)} x2={xp(note.index)} y1={0} y2={100} className=\"stroke-ink-subtle\" strokeDasharray=\"3 3\" vectorEffect=\"non-scaling-stroke\" />}\n          </svg>\n          <span aria-hidden className=\"absolute left-1 -translate-y-full pb-0.5 text-[10.5px] font-medium text-ink-muted\" style={{ top: `${yp(limit)}%` }}>\n            Plan limit · {limit}\n          </span>\n\n          {annotations.map((a, i) => (\n            <motion.button\n              key={a.index}\n              ref={(el) => {\n                btns.current[i] = el;\n              }}\n              type=\"button\"\n              aria-label={`${labels[a.index]}: ${a.title}. ${a.body}`}\n              aria-describedby={active === i ? `${uid}-note` : undefined}\n              initial={{ opacity: 0, scale: 0.4 }}\n              animate={inView || reduce ? { opacity: 1, scale: active === i ? 1.15 : 1 } : undefined}\n              transition={{ type: \"spring\", stiffness: 420, damping: 22, delay: reduce || active !== null ? 0 : 1 + i * 0.12 }}\n              onPointerEnter={() => setActive(i)}\n              onFocus={() => setActive(i)}\n              onBlur={() => setActive(null)}\n              onKeyDown={(e) => onKey(e, i)}\n              className={cn(\n                \"absolute -ml-3 -mt-3 grid size-6 place-items-center rounded-full border-2 font-mono text-[11px] font-semibold outline-none focus-visible:shadow-[var(--focus-ring)]\",\n                active === i ? \"border-volt-ink bg-volt text-on-volt\" : \"border-volt-ink bg-surface-raised text-ink\",\n              )}\n              style={{ left: `${xp(a.index)}%`, top: `${yp(values[a.index] ?? 0)}%` }}\n            >\n              {i + 1}\n            </motion.button>\n          ))}\n\n          <AnimatePresence>\n            {note && active !== null && (\n              <motion.div\n                key={active}\n                id={`${uid}-note`}\n                role=\"note\"\n                initial={{ opacity: 0, y: 6, filter: \"blur(6px)\" }}\n                animate={{ opacity: 1, y: 0, filter: \"blur(0px)\" }}\n                exit={{ opacity: 0, filter: \"blur(6px)\", transition: { duration: 0.12 } }}\n                transition={reduce ? { duration: 0 } : { type: \"spring\", stiffness: 380, damping: 30 }}\n                className={cn(\"pointer-events-none absolute bottom-2 z-10 w-56 rounded-sm border border-border bg-surface-raised p-2.5 shadow-md\", xp(note.index) > 50 ? \"-translate-x-[calc(100%+16px)]\" : \"translate-x-4\")}\n                style={{ left: `${xp(note.index)}%` }}\n              >\n                <p className=\"font-mono text-[10.5px] uppercase tracking-wide text-ink-subtle\">\n                  {labels[note.index]} · {values[note.index]} {unit}\n                </p>\n                <p className=\"mt-0.5 text-[13px] font-semibold text-ink\">{note.title}</p>\n                <p className=\"mt-0.5 text-[12px] leading-[17px] text-ink-muted\">{note.body}</p>\n              </motion.div>\n            )}\n          </AnimatePresence>\n        </div>\n        <div />\n        <div aria-hidden className=\"relative mt-2 h-4\">\n          {labels.map((l, i) => (\n            <span key={l + i} className={cn(\"absolute -translate-x-1/2 font-mono text-[10.5px] text-ink-subtle\", i % 2 === 1 && \"hidden @md:block\")} style={{ left: `${xp(i + 0.5)}%` }}>\n              {l}\n            </span>\n          ))}\n        </div>\n      </div>\n\n      <ol className=\"mt-4 grid gap-1 @md:grid-cols-2\">\n        {annotations.map((a, i) => (\n          <li key={a.index} onPointerEnter={() => setActive(i)} onPointerLeave={() => setActive(null)} className={cn(\"flex items-start gap-2 rounded-sm px-2 py-1.5 transition-colors\", active === i ? \"bg-surface-hover\" : \"\")}>\n            <span aria-hidden className={cn(\"mt-px grid size-5 shrink-0 place-items-center rounded-full font-mono text-[10.5px] font-semibold transition-colors\", active === i ? \"bg-volt text-on-volt\" : \"bg-surface text-ink-muted\")}>\n              {i + 1}\n            </span>\n            <span className=\"min-w-0 text-[12.5px] leading-[18px]\">\n              <span className=\"font-medium text-ink\">{a.title}</span>\n              <span className=\"text-ink-subtle\"> · {labels[a.index]}</span>\n            </span>\n          </li>\n        ))}\n      </ol>\n    </figure>\n  );\n}\n"},{"path":"LICENSE-geturui.md","type":"registry:file","target":"LICENSE-geturui.md","content":"MIT License\n\nCopyright (c) 2026 geturui.com\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"}],"categories":["examples","chart","line chart","time series","comparison","annotations","tooltip","crosshair","svg"],"meta":{"tier":"free","license":"MIT","docs":"https://geturui.com/docs/line-charts#step-annotations"}}