@loworbitstudio/visor 1.16.1 → 1.18.0

package/dist/visor-manifest.json

@@ -1,6 +1,6 @@
 {
   "version": "0.4.0",
-  "generated_at": "2026-07-07T17:14:24.746Z",
+  "generated_at": "2026-07-09T19:24:03.742Z",
   "components": {
     "accessibility-specimen": {
       "category": "specimen",
@@ -3429,6 +3429,213 @@
       ],
       "example": "<Dialog>\n  <DialogTrigger asChild>\n    <Button>Edit profile</Button>\n  </DialogTrigger>\n  <DialogContent>\n    <DialogHeader>\n      <DialogTitle>Edit profile</DialogTitle>\n      <DialogDescription>Make changes to your profile here.</DialogDescription>\n    </DialogHeader>\n    {/* form content */}\n  </DialogContent>\n</Dialog>\n"
     },
+    "doc-frame": {
+      "category": "navigation",
+      "description": "The themed doc-page shell that wraps DocNav. A sticky header with a flexible brand/logo slot, the DocNav slot, and a content wrapper for the doc. Reads a single docs manifest, derives the active product, and passes the slice + active-state down to DocNav. Themed entirely by Visor tokens. Replaces the vanilla-JS doc shell (nav.js + docs.css) on the React/route track.",
+      "when_to_use": [
+        "The surrounding themed page shell for a documentation site — sticky header, brand/logo slot, and content wrapper around a manifest-driven DocNav",
+        "A doc host that must theme its whole chrome from Visor tokens and adopt the active project theme without modification",
+        "A brand/logo slot that resolves an explicit logo, then the active theme's mode-aware brand logo, then a text wordmark",
+        "Multi-product doc sets where the frame derives the active product from the route and drives the DocNav accordion"
+      ],
+      "when_not_to_use": [
+        "The nav internals themselves — the peer groups, accordion, pinned Shared, and Appendix (use DocNav — rendered in the slot)",
+        "Top-level site navigation with brand and actions across an app (use Navbar)",
+        "A generic app page layout or shell unrelated to docs (use Container, Stack, or a page-header composition)",
+        "Manifest parsing, tiering, or routing resolution (owned upstream; DocFrame consumes the parsed manifest)"
+      ],
+      "variants": {},
+      "props": [
+        {
+          "name": "manifest",
+          "type": "DocsManifest",
+          "required": true,
+          "description": "The parsed manifest (docs[], optional products[], optional brand text, optional dispositions) — the single input everything derives from."
+        },
+        {
+          "name": "children",
+          "type": "React.ReactNode",
+          "required": true,
+          "description": "The doc content, rendered in the content wrapper below the nav."
+        },
+        {
+          "name": "logo",
+          "type": "React.ReactNode",
+          "description": "The brand slot. Any node — an <img> of an SVG, an inline <svg>, or a full component. Resolution order — explicit logo → the active theme's brand logo SVG (mode-aware via --brand-logo, upgraded only once it loads so a 404 keeps the wordmark) → the manifest brand text (a leading glyph chip + the name)."
+        },
+        {
+          "name": "home",
+          "type": "DocFrameHome",
+          "description": "The OVERVIEW / home pill rendered after the brand — a bordered mono chip with a leading compass glyph and a { href, label }. Omit to hide it."
+        },
+        {
+          "name": "meta",
+          "type": "React.ReactNode",
+          "description": "A right-aligned breadcrumb / status slot in the header (mono, UPPERCASE, --text-tertiary) — e.g. ARTIST · BUILD-READY."
+        },
+        {
+          "name": "groupAccents",
+          "type": "Record<string, string>",
+          "description": "Per-group nav accent overrides keyed by DocNav group id or role, driving its --doc-nav-group-accent hook. Merged over the default palette (pro → --warning, the amber Pro dot); DocNav already defaults shared → --info, other products → --accent, appendix → --text-tertiary."
+        },
+        {
+          "name": "borderless",
+          "type": "boolean",
+          "description": "Force the borderless treatment — null the pinned Shared group's frame for borderless themes (Animal / ENTR) that carry structure from surface contrast. Auto-detected from theme for the known borderless set; pass explicitly when the theme is applied by an ancestor."
+        },
+        {
+          "name": "activeProduct",
+          "type": "string",
+          "description": "Which product group is expanded (the accordion). Defaults to the route's product, else the first product in the roster. Absent roster → single-product mode."
+        },
+        {
+          "name": "currentPath",
+          "type": "string",
+          "description": "The active route for active-state. Next consumers pass usePathname(); a static page passes location.pathname. Defaults to window.location.pathname in the browser, or \"/\" during SSR."
+        },
+        {
+          "name": "theme",
+          "type": "string",
+          "description": "A Visor theme class name applied to the shell root, scoping all doc-shell CSS variables. Defaults to the app's ambient theme."
+        }
+      ],
+      "dependencies": [
+        "@phosphor-icons/react",
+        "@loworbitstudio/visor-core"
+      ],
+      "tokens_used": [
+        "--border-default",
+        "--border-focus",
+        "--brand-logo",
+        "--brand-logo-aspect-ratio",
+        "--doc-frame-glyph-radius",
+        "--doc-frame-logo-height",
+        "--doc-frame-max-width",
+        "--focus-ring-offset",
+        "--focus-ring-width",
+        "--font-mono",
+        "--font-size-2xs",
+        "--font-size-lg",
+        "--font-size-sm",
+        "--font-size-xs",
+        "--font-weight-bold",
+        "--font-weight-medium",
+        "--hairline",
+        "--hairline-strong",
+        "--motion-duration-fast",
+        "--motion-easing-standard",
+        "--primary",
+        "--primary-text",
+        "--radius-full",
+        "--spacing-1",
+        "--spacing-2",
+        "--spacing-3",
+        "--spacing-4",
+        "--spacing-5",
+        "--spacing-6",
+        "--spacing-8",
+        "--stroke-width-thin",
+        "--surface-card",
+        "--surface-page",
+        "--text-primary",
+        "--text-tertiary"
+      ],
+      "example": "import { DocFrame, type DocsManifest } from '@/components/ui/doc-frame/doc-frame'\n\nconst manifest: DocsManifest = {\n  brand: 'Blacklight',\n  products: [{ id: 'artist' }, { id: 'pro' }],\n  docs: [\n    { order: 1, label: 'Charter', href: '/docs/charter.html', group: 'Shared' },\n    { order: 3, label: 'Screens', href: '/docs/artist/screens', scope: ['artist'], group: 'Artist' },\n    { order: 2, label: 'Journeys', href: '/docs/pro/journeys', scope: ['pro'], group: 'Pro' },\n    { order: 11, label: 'Q3 Audit', href: '/docs/q3-audit.html' },\n  ],\n}\n\nexport function Shell({ children }: { children: React.ReactNode }) {\n  return (\n    <DocFrame manifest={manifest} currentPath=\"/docs/artist/screens\">\n      {children}\n    </DocFrame>\n  )\n}\n"
+    },
+    "doc-nav": {
+      "category": "navigation",
+      "description": "A manifest-driven, grouped/collapsible, multi-product-aware documentation navigation. Renders peer collapsible groups from a manifest slice — a pinned Shared set, accordion product groups (one open at a time), and an Appendix bucket for ad-hoc docs — resolving the active pill from the current path. The group row wraps and is never an overflow-x scroll strip. Replaces the vanilla-JS doc nav (nav.js).",
+      "when_to_use": [
+        "A documentation shell that must group docs by product/section and collapse them, driven by a docs manifest",
+        "Multi-product doc sets where a pinned Shared group sits beside accordion product groups (switching product = expanding its group)",
+        "Ad-hoc/one-off docs with no canonical slot that should tuck into an Appendix instead of widening the row",
+        "Any doc nav that must never run off the edge — groups wrap, they do not scroll horizontally"
+      ],
+      "when_not_to_use": [
+        "The surrounding themed page shell, sticky header, and brand/logo slot (use DocFrame — VI-609)",
+        "In-app section sub-navigation with count pills across a detail view (use SectionNav)",
+        "Top-level site navigation with brand + actions (use Navbar)",
+        "A single expandable section (use Collapsible) or a grouped side rail (use Sidebar)"
+      ],
+      "variants": {},
+      "props": [
+        {
+          "name": "docs",
+          "type": "DocEntry[]",
+          "required": true,
+          "description": "The manifest slice for the active view (Shared + product-scoped), pre-filtered by DocFrame. Each DocEntry carries order, label, href, and optional kind/scope/group/tier/external."
+        },
+        {
+          "name": "currentPath",
+          "type": "string",
+          "required": true,
+          "description": "The active route (or static location.pathname). Resolves the active pill (with aria-current=\"page\") and auto-expands its group."
+        },
+        {
+          "name": "activeProduct",
+          "type": "string",
+          "description": "Which product group is open (the accordion). Absent → single-product mode with no accordion."
+        },
+        {
+          "name": "onProductToggle",
+          "type": "(id: string) => void",
+          "description": "Accordion callback — the parent expands a product group and collapses the sibling by swapping activeProduct. Absent → groups render as plain, independently expandable links (static-doc mode)."
+        },
+        {
+          "name": "pinnedGroups",
+          "type": "string[]",
+          "default": "[\"shared\"]",
+          "description": "Group ids that stay open regardless of the accordion."
+        },
+        {
+          "name": "defaultCollapsed",
+          "type": "boolean",
+          "default": "true",
+          "description": "Whether non-active, non-pinned groups start collapsed — the anti-wall rule."
+        }
+      ],
+      "dependencies": [
+        "@phosphor-icons/react",
+        "@loworbitstudio/visor-core"
+      ],
+      "tokens_used": [
+        "--accent",
+        "--border-default",
+        "--border-focus",
+        "--color-neutral-950",
+        "--doc-nav-accent",
+        "--doc-nav-group-accent",
+        "--doc-nav-group-radius",
+        "--doc-nav-pill-bg",
+        "--doc-nav-pin-bg",
+        "--doc-nav-pin-border",
+        "--focus-ring-offset",
+        "--focus-ring-width",
+        "--font-mono",
+        "--font-size-2xs",
+        "--font-size-xs",
+        "--font-weight-bold",
+        "--font-weight-medium",
+        "--hairline",
+        "--info",
+        "--motion-duration-fast",
+        "--motion-easing-standard",
+        "--radius-full",
+        "--radius-md",
+        "--radius-sm",
+        "--spacing-1",
+        "--spacing-2",
+        "--spacing-3",
+        "--spacing-4",
+        "--stroke-width-thin",
+        "--surface-card",
+        "--surface-selected",
+        "--text-primary",
+        "--text-secondary",
+        "--text-tertiary"
+      ],
+      "example": "import { DocNav, type DocEntry } from '@/components/ui/doc-nav/doc-nav'\n\nconst docs: DocEntry[] = [\n  { order: 0, label: 'Overview', href: '/docs', group: 'Shared' },\n  { order: 1, label: 'Charter', href: '/docs/charter', group: 'Shared' },\n  { order: 3, label: 'Screens', href: '/docs/artist-screens', scope: ['artist'], group: 'Artist' },\n  { order: 2, label: 'Journeys', href: '/docs/pro-journeys', scope: ['pro'], group: 'Pro' },\n  { order: 11, label: 'Q3 Audit', href: '/docs/q3-audit' },\n]\n\nexport function Nav({ product }: { product: string }) {\n  const [open, setOpen] = React.useState(product)\n  return (\n    <DocNav\n      docs={docs}\n      currentPath=\"/docs/artist-screens\"\n      activeProduct={open}\n      onProductToggle={setOpen}\n    />\n  )\n}\n"
+    },
     "dropdown-menu": {
       "category": "overlay",
       "description": "Menu of actions or options that opens from a trigger button.",
@@ -10816,6 +11023,28 @@
         "Settings forms (use admin-settings-page)"
       ]
     },
+    "admin-detail": {
+      "category": "admin",
+      "description": "Full-page, read-oriented detail RECORD for the admin-shell main column. Composes an identity header (media + title + StatusBadge + actions), N key-value sections built on KeyValueList, an optional sensitive/reveal panel gated behind a Switch, and optional sub-list slots for ledgers or history — separated by hairline dividers. The full-page sibling to admin-detail-drawer (a drawer) and admin-list-page.",
+      "components_used": [
+        "key-value-list",
+        "status-badge",
+        "switch",
+        "separator"
+      ],
+      "when_to_use": [
+        "Read-oriented single-record detail pages rendered in the admin-shell main column",
+        "Records with an identity header plus grouped key-value facts (profile, account, metadata)",
+        "Detail pages that expose sensitive data (tax IDs, banking, W-9) behind a reveal control",
+        "Records with sub-ledgers or history tables beneath the key-value sections"
+      ],
+      "when_not_to_use": [
+        "Inline editing of a record from a list without leaving the page (use admin-detail-drawer)",
+        "Full-page multi-section editors with save/cancel (use admin-settings-page)",
+        "Multi-step create/edit flows (use admin-wizard)",
+        "Tabular lists of many records (use admin-list-page)"
+      ]
+    },
     "admin-detail-drawer": {
       "category": "admin",
       "description": "Right-side slide-out panel for viewing or editing a single record. Composes Sheet with a sticky save/cancel footer, async save handler with pending state, an unsaved-changes guard powered by ConfirmDialog, sm/md/lg/xl width variants, and optional header customization via hideHeader and customHeader props.",
@@ -11171,6 +11400,21 @@
         "Registration forms (extend with additional fields)"
       ]
     },
+    "month-calendar": {
+      "category": "data-display",
+      "description": "A theme-portable month event-grid (scheduler) block. Renders a 6×7 day-cell grid under a localized weekday header, with prev/next month navigation, a view-mode segmented control (Month / Week / Day), and per-cell event chips. Each chip carries a status-dot slot (success / warning / danger / info) and an optional series tint (1–5) keyed to the theme's chart ramp for color-coding a recurring series or resource lane. Days outside the displayed month are dimmed; optional today and selected-day highlighting. Fully token-driven — every color, spacing, stroke, radius, shadow, opacity, and motion value binds to a Visor token, so the grid adopts the active theme without modification.",
+      "components_used": [],
+      "when_to_use": [
+        "Admin or booking surfaces that show events-in-a-month (the most common scheduling view)",
+        "Color-coding recurring series or resource lanes via the per-chip series tint",
+        "Status-at-a-glance calendars where each event needs a success / warning / danger / info dot"
+      ],
+      "when_not_to_use": [
+        "Picking a single date or date range (use calendar, date-picker, or date-range-picker)",
+        "Time-slot / day-timeline scheduling with hour rows (use a dedicated day/week scheduler)",
+        "Dense agenda lists with no month context (use a table or activity-feed)"
+      ]
+    },
     "pricing-section": {
       "category": "marketing",
       "description": "A responsive pricing tier grid with feature lists, highlighted plan, and per-tier CTAs.",
@@ -12073,6 +12317,8 @@
     "navigation": [
       "breadcrumb",
       "command",
+      "doc-frame",
+      "doc-nav",
       "navbar",
       "page-header",
       "pagination",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loworbitstudio/visor",
-  "version": "1.16.1",
+  "version": "1.18.0",
   "description": "CLI for the Visor design system — add components, hooks, and utilities to your project.",
   "type": "module",
   "bin": {