{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "icon-rail",
  "title": "Icon Rail",
  "description": "Narrow vertical strip of icon-only navigation destinations.",
  "dependencies": [
    "class-variance-authority@^0.7.1"
  ],
  "registryDependencies": [
    "@pestoui/style",
    "@pestoui/utils"
  ],
  "files": [
    {
      "path": "pestoui/components/icon-rail.tsx",
      "content": "import * as React from \"react\"\nimport { cva, type VariantProps } from \"class-variance-authority\"\n\nimport { cn } from \"@/lib/utils\"\n\n/* ---------------------------------------------------------------------------\n   Icon rail — the narrow vertical strip of icon-only destinations that stands\n   in for a sidebar when it collapses, or sits beside one as a persistent\n   app-level switcher.\n\n   Compound rather than an `items={[…]}` prop, for the same reason the rest of\n   the navigation primitives are: the caller owns the interactive element. A\n   rail row is a router `<Link>` in one app, an `<a>` in another and a plain\n   click handler in a third, and a data prop pushes all three through a render\n   callback.\n\n   ## Why the colour axis is `surface` and not `tone`\n\n   `tone` is a fixed contract here — `selected | success | warning |\n   destructive | info | muted | chart-1…5` — and it answers \"what does this\n   thing mean\": a status, a category, a series. Every toned component accepts\n   the whole set, and accepting the whole set is what makes the word portable.\n\n   A rail means nothing. What varies is which end of the neutral ramp it is\n   painted from: a near-black strip inside a light page, or a light one that\n   matches the surrounding chrome. That is two values, not eleven, and no\n   member of the `tone` set would ever be a legal answer to it. Spelling that\n   as `tone=\"dark\"` would make `tone` mean something in this file that it means\n   nowhere else in the system — the drift the shared contract exists to\n   prevent. So the axis gets its own name and leaves `tone` alone.\n\n   ## Tooltips are not built in\n\n   `IconRailItem` is a real `<button>` that forwards its props and ref, so\n   `<TooltipTrigger asChild>` wraps one directly. Packaging a tooltip inside\n   would force a `TooltipProvider` into every rail and hand every item a second\n   copy of its `srLabel` that the caller cannot turn off — and on a rail beside\n   an expanded sidebar, where the labels are already on screen, that is noise.\n--------------------------------------------------------------------------- */\n\n/* The rail's width is `--rail-item` plus its own padding on both sides, so the\n   two move together: at `default` 40 + 8 + 8 = 56, at `sm` 32 + 8 + 8 = 48.\n   Overriding one without the other is what leaves the icons off-centre.\n\n   The item metrics are handed down as custom properties rather than read back\n   off `data-size`, so only the values that actually render ship, and an item\n   composed outside a rail still has the `default` numbers as var() fallbacks.\n\n   Radius is keyed to a ratio, not to a step: the discovered squircle ramp in\n   this system is r ≈ 0.30 × edge, so a 40px box wants ~12px (`--radius-md`,\n   12.8) and a 32px box wants ~9.6px (`--radius-sm`, 9.6 exactly). Holding one\n   radius across both sizes would make the small rail read as noticeably\n   rounder than the large one. */\nconst iconRailVariants = cva(\"group/icon-rail flex shrink-0 flex-col p-2\", {\n  variants: {\n    surface: {\n      light: \"bg-card text-card-foreground ring-1 ring-border\",\n      /* No hairline on this one: a near-black strip against a light page is\n         already its own edge, and a ring would draw a second one. */\n      dark: \"bg-inverse text-inverse-foreground\",\n    },\n    size: {\n      default:\n        \"w-14 [--rail-item:--spacing(10)] [--rail-icon:--spacing(5)] [--rail-radius:var(--radius-md)]\",\n      sm: \"w-12 [--rail-item:--spacing(8)] [--rail-icon:--spacing(4)] [--rail-radius:var(--radius-sm)]\",\n    },\n  },\n  defaultVariants: {\n    surface: \"light\",\n    size: \"default\",\n  },\n})\n\ntype IconRailSurface = NonNullable<VariantProps<typeof iconRailVariants>[\"surface\"]>\ntype IconRailSize = NonNullable<VariantProps<typeof iconRailVariants>[\"size\"]>\n\ntype IconRailProps = React.ComponentProps<\"nav\"> &\n  VariantProps<typeof iconRailVariants> & {\n    /** Names the rail for assistive tech. Required because a rail carries no\n     *  visible heading of its own, so there is nowhere else the name could\n     *  come from — and a page with two unnamed `<nav>`s is a page a screen\n     *  reader user cannot tell apart. */\n    srLabel: string\n  }\n\n/**\n * The rail surface. Renders a `<nav>` around the item list.\n *\n * Height is left to the caller — as a flex or grid child the rail stretches on\n * its own, which is what `IconRailSpacer` needs to have room to give away.\n */\nfunction IconRail({\n  className,\n  srLabel,\n  surface = \"light\",\n  size = \"default\",\n  children,\n  ...props\n}: IconRailProps) {\n  return (\n    <nav\n      data-slot=\"icon-rail\"\n      /* Emitted for descendants — the items select on `data-surface` to pick\n         their palette. The rail's own classes come from the cva. */\n      data-surface={surface}\n      data-size={size}\n      /* Declared before the spread so a caller with a visible heading can\n         point `aria-labelledby` at it and win. */\n      aria-label={srLabel}\n      className={cn(iconRailVariants({ surface, size }), className)}\n      {...props}\n    >\n      <ul\n        data-slot=\"icon-rail-list\"\n        /* Preflight strips list-style, which drops list semantics in Safari —\n           restore them explicitly, same as the activity feed does. */\n        role=\"list\"\n        className=\"flex min-h-0 flex-1 flex-col items-center gap-1\"\n      >\n        {children}\n      </ul>\n    </nav>\n  )\n}\n\ntype IconRailItemProps = React.ComponentProps<\"button\"> & {\n  /** The mark. Pass the bare icon — the rail sizes it, so a wrapper with its\n   *  own dimensions will fight `--rail-icon`. */\n  icon: React.ReactNode\n  /** The control's accessible name, and not optional: an icon-only button has\n   *  no text node, no `alt` and no visible label, so without this it is\n   *  announced as \"button\" and the rail becomes unusable. */\n  srLabel: string\n  /** Current destination. Paints the filled pill and sets `aria-current`. */\n  active?: boolean\n}\n\n/**\n * One destination. A real `<button>`, so it is focusable, reachable by\n * keyboard and announced as a control.\n *\n * Anything passed as `children` stacks with the icon inside the pill — the\n * button is `relative`, so an absolutely positioned unread dot works without\n * a prop for it.\n */\nfunction IconRailItem({\n  className,\n  icon,\n  srLabel,\n  active = false,\n  /* A rail dropped inside a form must not submit it. Declared with a default\n     rather than hardcoded so a genuine submit button can still say so. */\n  type = \"button\",\n  children,\n  ...props\n}: IconRailItemProps) {\n  return (\n    /* The `<li>` exists only to keep the list valid — a `role=\"list\"` whose\n       children are buttons reports no items at all. All props, including\n       `className`, land on the button, because the button is the component. */\n    <li data-slot=\"icon-rail-item\">\n      <button\n        data-slot=\"icon-rail-button\"\n        type={type}\n        /* `data-active` is a hook for descendants and tests; `aria-current` is\n           what actually tells a screen reader which one you are on. */\n        data-active={active}\n        aria-current={active ? \"page\" : undefined}\n        className={cn(\n          \"relative flex shrink-0 items-center justify-center\",\n          \"size-[var(--rail-item,calc(var(--spacing)*10))]\",\n          \"rounded-[var(--rail-radius,var(--radius-md))]\",\n          /* The highlight has to land under the cursor: this is a strip the\n             user crosses constantly, and anything slower reads as lag. */\n          \"outline-hidden transition-colors duration-instant ease-out-expo\",\n          /* The press squeezes the glyph, never the button — the same split\n             sidebar-nav makes. A button scaled under the pointer shrinks away\n             from it: at 0.96 on 40px a press landing within 0.8px of the edge\n             is released outside the box, the click goes to the common\n             ancestor, and the navigation is lost. Measured in headed and\n             headless Chromium, five held presses 0.5px inside the right edge:\n             0 clicks of 5 with the box at 0.96, 5 of 5 with the glyph at 0.9.\n             `--press-squeeze` goes to 1 under reduced motion, so the press is\n             a distance that goes too. A disabled item is\n             `pointer-events-none`, and measured it never matches :active, so\n             it does not squeeze. */\n          \"[&_svg]:transition-[scale] [&_svg]:duration-spring-press [&_svg]:ease-spring-press active:[&_svg]:scale-(--press-squeeze)\",\n          \"focus-visible:ring-2 focus-visible:ring-ring\",\n          \"disabled:pointer-events-none disabled:opacity-50\",\n          \"[&_svg]:size-[var(--rail-icon,calc(var(--spacing)*5))] [&_svg]:shrink-0\",\n          /* Branching instead of layering both sets and letting the cascade\n             sort it out — only the state that renders ships, and the result\n             does not depend on twMerge's conflict ordering.\n           *\n           * On the light rail the pill is `--selected`, the system's one token\n           * for \"this is the chosen thing\". On the dark rail it is a neutral\n           * wash instead: at 10–15% over the inverse surface the green is\n           * invisible, and its ink barely clears 4:1 there, so the light\n           * neutral is simply the strongest signal that surface has. Neither\n           * reading is used for anything else on a rail, so neither is\n           * ambiguous. */\n          active\n            ? cn(\n                \"bg-selected/10 text-selected hover:bg-selected/15\",\n                \"group-data-[surface=dark]/icon-rail:bg-inverse-foreground/15\",\n                \"group-data-[surface=dark]/icon-rail:text-inverse-foreground\",\n                \"group-data-[surface=dark]/icon-rail:hover:bg-inverse-foreground/20\"\n              )\n            : cn(\n                \"text-muted-foreground hover:bg-accent hover:text-accent-foreground\",\n                \"group-data-[surface=dark]/icon-rail:text-inverse-muted\",\n                \"group-data-[surface=dark]/icon-rail:hover:bg-inverse-foreground/10\",\n                \"group-data-[surface=dark]/icon-rail:hover:text-inverse-foreground\"\n              ),\n          className\n        )}\n        {...props}\n      >\n        {icon}\n        {children}\n        <span className=\"sr-only\">{srLabel}</span>\n      </button>\n    </li>\n  )\n}\n\n/**\n * Eats the leftover vertical space, pushing everything after it to the bottom\n * of the rail — settings and the account switcher, typically.\n */\nfunction IconRailSpacer({ className, ...props }: React.ComponentProps<\"li\">) {\n  return (\n    <li\n      data-slot=\"icon-rail-spacer\"\n      /* An empty `<li>` would be announced as a list item and inflate the\n         count, so the role is dropped. It stays an `<li>` because the flex\n         column it grows inside is the list. */\n      role=\"none\"\n      className={cn(\"flex-1\", className)}\n      {...props}\n    />\n  )\n}\n\nexport { IconRail, IconRailItem, IconRailSpacer, iconRailVariants }\nexport type { IconRailItemProps, IconRailProps, IconRailSize, IconRailSurface }\n",
      "type": "registry:component"
    }
  ],
  "type": "registry:component"
}