shadcn_view_component 0.3.3

data/app/javascript/shadcn/scroll_geometry.js

@@ -0,0 +1,267 @@
+// The measurements a message scroller runs on, ported from
+// `vendor/shadcn-react/message-scroller/geometry.ts`.
+//
+// Every function here is pure: it reads rects, `scrollTop`, computed padding
+// and two `data-` attributes, and returns a number, an element or null. Nothing
+// writes, nothing schedules, nothing holds state — which is why this is a module
+// of its own rather than methods on the controller, and why it can be tested
+// without a browser opening anything.
+//
+// One function of upstream's is deliberately missing:
+// `getMessageScrollerVisibilityState`, the largest in the file, which exists to
+// feed `useMessageScrollerVisibility`. That surface is not reproduced — see
+// `.claude/docs/features/message-scroller.md` for the measurement behind that
+// decision. Nothing else in this file referenced it.
+
+// Upstream's `EMPTY_MESSAGE_SCROLLER_SCROLLABLE` (types.ts:193). A frozen
+// object rather than a fresh one per call, so a caller cannot mutate the answer
+// for the next.
+const NOT_SCROLLABLE = Object.freeze({ start: false, end: false })
+
+// The rows, in document order. The spacer is a sibling of the items and has to
+// be excluded by identity rather than by a selector: it carries no `data-slot`
+// of its own, and upstream filters it the same way (geometry.ts:108-116).
+export function getMessageScrollerItems(content, spacer) {
+  return Array.from(content.children).filter(
+    (child) => child instanceof HTMLElement && child !== spacer
+  )
+}
+
+// Whether there is anything to scroll to in each direction — which is what
+// decides the two buttons' `data-active`. `end` is measured against the
+// content's own bottom rather than `scrollHeight`, because the tail spacer
+// inflates `scrollHeight` on purpose and would keep the button lit forever.
+export function getMessageScrollerScrollable({
+  content,
+  scrollEdgeThreshold,
+  spacer,
+  viewport
+}) {
+  if (!viewport || !content) return NOT_SCROLLABLE
+
+  const contentBottom = getContentBottom({ content, spacer, viewport })
+
+  return {
+    start: viewport.scrollTop > scrollEdgeThreshold,
+    end:
+      contentBottom - viewport.scrollTop - viewport.clientHeight >
+      scrollEdgeThreshold
+  }
+}
+
+// The first anchor among rows added since the last count — what a newly
+// arrived turn scrolls to.
+export function getNewScrollAnchor(items, previousItemCount) {
+  for (let index = previousItemCount; index < items.length; index++) {
+    if (items[index]?.dataset.scrollAnchor === "true") return items[index]
+  }
+
+  return null
+}
+
+// `handledAnchors` is anything with a `has(element)` — upstream passes a
+// `WeakSet` of anchors already scrolled to, so one is never handled twice.
+export function getUnanchoredScrollAnchor(items, handledAnchors) {
+  for (const item of items) {
+    if (item.dataset.scrollAnchor === "true" && !handledAnchors.has(item)) {
+      return item
+    }
+  }
+
+  return null
+}
+
+// Two turns arriving in one batch cannot both be scrolled to, so the caller
+// needs to know before it tries. Stops at two rather than counting them all.
+export function hasMultipleNewScrollAnchors(items, previousItemCount) {
+  let count = 0
+
+  for (let index = previousItemCount; index < items.length; index++) {
+    if (items[index]?.dataset.scrollAnchor !== "true") continue
+
+    count += 1
+    if (count > 1) return true
+  }
+
+  return false
+}
+
+export function getLastScrollAnchor(items) {
+  for (let index = items.length - 1; index >= 0; index--) {
+    if (items[index]?.dataset.scrollAnchor === "true") return items[index]
+  }
+
+  return null
+}
+
+// Rows without a `data-message-id` are skipped: the spacer is already gone, but
+// a host may put its own markup in the content column and it should not count
+// as a message.
+export function getFirstVisibleMessageItem({ content, spacer, viewport }) {
+  const viewportRect = viewport.getBoundingClientRect()
+
+  for (const item of getMessageScrollerItems(content, spacer)) {
+    if (!item.dataset.messageId) continue
+
+    const rect = item.getBoundingClientRect()
+
+    if (rect.bottom > viewportRect.top && rect.top < viewportRect.bottom) {
+      return item
+    }
+  }
+
+  return null
+}
+
+// Where the viewport has to be scrolled for `element` to sit at `align`.
+// `scrollMargin` is the caller's breathing room above it; the content's own
+// block padding is subtracted so the row lands where it looks right rather than
+// where the box model puts it (geometry.ts:204-265).
+export function getElementScrollTop({
+  align,
+  element,
+  scrollMargin,
+  spacer,
+  viewport
+}) {
+  const elementTop = getElementTop(element, viewport)
+  const elementHeight = element.getBoundingClientRect().height
+  const contentPadding = getContentBlockPadding(spacer)
+
+  if (align === "center") {
+    const insetHeight = Math.max(
+      0,
+      viewport.clientHeight - contentPadding.start - contentPadding.end
+    )
+
+    return (
+      elementTop -
+      contentPadding.start -
+      (insetHeight - elementHeight) / 2 -
+      scrollMargin
+    )
+  }
+
+  if (align === "end") {
+    return (
+      elementTop -
+      viewport.clientHeight +
+      elementHeight +
+      contentPadding.end +
+      scrollMargin
+    )
+  }
+
+  // `nearest` is the only one that can answer "do not move".
+  if (align === "nearest") {
+    const elementBottom = elementTop + elementHeight
+    const viewportTop = viewport.scrollTop + contentPadding.start
+    const viewportBottom =
+      viewport.scrollTop + viewport.clientHeight - contentPadding.end
+
+    if (elementTop >= viewportTop && elementBottom <= viewportBottom) {
+      return viewport.scrollTop
+    }
+
+    if (elementTop < viewportTop) {
+      return elementTop - contentPadding.start - scrollMargin
+    }
+
+    return (
+      elementBottom - viewport.clientHeight + contentPadding.end + scrollMargin
+    )
+  }
+
+  return elementTop - contentPadding.start - scrollMargin
+}
+
+// In the scroll container's own coordinates, not the viewport's: the rect
+// difference plus the current `scrollTop` is what makes the answer survive
+// being scrolled.
+export function getElementTop(element, viewport) {
+  const elementRect = element.getBoundingClientRect()
+  const viewportRect = viewport.getBoundingClientRect()
+
+  return elementRect.top - viewportRect.top + viewport.scrollTop
+}
+
+export function getElementViewportTop(element, viewport) {
+  return (
+    element.getBoundingClientRect().top - viewport.getBoundingClientRect().top
+  )
+}
+
+// How tall the spacer under the last message has to be for that message to be
+// able to reach the top of the viewport. Negative means none is needed.
+export function getTailSpacerHeight({ content, scrollTop, spacer, viewport }) {
+  const contentBottom = getContentBottom({ content, spacer, viewport })
+
+  return scrollTop + viewport.clientHeight - contentBottom
+}
+
+// The bottom of the real content, spacer excluded — measured from the rows
+// rather than read off `scrollHeight`, which the spacer inflates. Starts at the
+// padding so an empty column still answers sensibly.
+export function getContentBottom({ content, spacer, viewport }) {
+  const items = getMessageScrollerItems(content, spacer)
+  const padding = getBlockPadding(content)
+  const viewportRect = viewport.getBoundingClientRect()
+  const scrollTop = viewport.scrollTop
+  let contentBottom = padding.start + padding.end
+
+  for (const item of items) {
+    const rect = item.getBoundingClientRect()
+
+    contentBottom = Math.max(
+      contentBottom,
+      rect.bottom - viewportRect.top + scrollTop + padding.end
+    )
+  }
+
+  return contentBottom
+}
+
+export function getMaxScrollTop(viewport) {
+  return Math.max(0, viewport.scrollHeight - viewport.clientHeight)
+}
+
+// `paddingBlock*` first so a vertical writing mode measures the axis that
+// actually scrolls; `paddingTop`/`paddingBottom` is the fallback.
+export function getBlockPadding(element) {
+  const style = window.getComputedStyle(element)
+
+  return {
+    end: readCssPixel(style.paddingBlockEnd || style.paddingBottom),
+    start: readCssPixel(style.paddingBlockStart || style.paddingTop)
+  }
+}
+
+// Reached through the spacer rather than by taking the content element as an
+// argument, because the callers that need it are holding the spacer.
+export function getContentBlockPadding(spacer) {
+  const content = spacer?.parentElement
+
+  if (!content) return { end: 0, start: 0 }
+
+  return getBlockPadding(content)
+}
+
+export function getFlexGap(element) {
+  if (!element) return 0
+
+  const style = window.getComputedStyle(element)
+  const gap = style.rowGap === "normal" ? style.gap : style.rowGap
+
+  return readCssPixel(gap)
+}
+
+// `parseFloat` on a computed length, with everything unparseable — `normal`,
+// `auto`, an empty string — collapsing to 0 rather than to `NaN`, which would
+// poison every sum it reaches.
+function readCssPixel(value) {
+  if (!value) return 0
+
+  const number = Number.parseFloat(value)
+
+  return Number.isFinite(number) ? number : 0
+}

data/app/javascript/shadcn/theme.js

@@ -0,0 +1,161 @@
+// The theming store — the port of what `next-themes` does for shadcn's own
+// site, plus the colour-theme switching from its `ActiveThemeProvider`.
+//
+// Two independent axes, exactly as upstream:
+//
+//   mode   "light" | "dark" | "system"  → toggles `.dark` on <html>
+//   theme  a palette name               → swaps `theme-*` on <body>
+//
+// Both are kept in `localStorage` and mirrored into a cookie, so a Rails layout
+// can render the right classes server-side and avoid a flash without relying on
+// the inline script.
+
+export const MODE_STORAGE_KEY = "shadcn-ui-mode"
+export const THEME_STORAGE_KEY = "shadcn-ui-theme"
+export const CHANGE_EVENT = "shadcn:theme-change"
+
+export const MODES = [ "light", "dark", "system" ]
+
+const DARK_QUERY = "(prefers-color-scheme: dark)"
+
+function read(key, fallback) {
+  try {
+    return window.localStorage.getItem(key) || fallback
+  } catch {
+    // Private browsing, or storage disabled.
+    return fallback
+  }
+}
+
+function write(key, value) {
+  try {
+    window.localStorage.setItem(key, value)
+  } catch {
+    // Ignore: the cookie mirror below is enough to survive a reload.
+  }
+
+  document.cookie = `${key}=${encodeURIComponent(value)}; path=/; max-age=31536000; samesite=lax`
+}
+
+export function systemMode() {
+  return window.matchMedia(DARK_QUERY).matches ? "dark" : "light"
+}
+
+export function getMode() {
+  const mode = read(MODE_STORAGE_KEY, "system")
+  return MODES.includes(mode) ? mode : "system"
+}
+
+// The mode actually in effect: `system` resolved against the OS preference.
+export function resolvedMode() {
+  const mode = getMode()
+  return mode === "system" ? systemMode() : mode
+}
+
+export function setMode(mode) {
+  if (!MODES.includes(mode)) return
+
+  write(MODE_STORAGE_KEY, mode)
+  applyMode()
+  announce()
+}
+
+export function toggleMode() {
+  setMode(resolvedMode() === "dark" ? "light" : "dark")
+}
+
+// The palette in effect: what the visitor chose, or what the *document* says.
+//
+// The fallback used to be the literal "neutral", and that threw away the
+// server's answer. `shadcn_theme_script_tag` writes the theme the page was
+// rendered with onto `<html>` (`data-shadcn-theme`), and a host that sets
+// `shadcn_theme_class(default: "sky")` renders `<body class="theme-sky">` — and
+// then `applyTheme()` ran, found nothing in storage, and swapped the class back
+// to `theme-neutral` on the first paint. The palette a host had chosen was
+// visible only until the JavaScript booted, with nothing to explain it.
+//
+// Reading the document keeps one source of truth: the script tag has already
+// resolved storage against the host's default, so this returns the same value
+// when the visitor has chosen, and the host's when they have not.
+export function getTheme() {
+  return read(THEME_STORAGE_KEY, documentTheme())
+}
+
+// Two places a host publishes it, and the rendered class comes first.
+//
+// The class is what the **server** decided, reading the cookie this module
+// mirrors every choice into and falling back to the host's own default. The
+// attribute is what the script tag decided a moment later, reading
+// `localStorage` against the same default. They agree whenever both are
+// present — the cookie is the mirror of the storage — and where they differ the
+// class is the better informed of the two: storage cleared with the cookie
+// still there is a visitor whose choice the server can still see and the script
+// cannot.
+function documentTheme() {
+  const target = document.body || document.documentElement
+  const rendered = Array.from(target.classList).find((name) =>
+    name.startsWith("theme-")
+  )
+  if (rendered) return rendered.slice("theme-".length)
+
+  return document.documentElement.dataset.shadcnTheme || "neutral"
+}
+
+export function setTheme(theme) {
+  if (!theme) return
+
+  write(THEME_STORAGE_KEY, theme)
+  applyTheme()
+  announce()
+}
+
+export function applyMode() {
+  const root = document.documentElement
+
+  root.classList.toggle("dark", resolvedMode() === "dark")
+  root.style.colorScheme = resolvedMode()
+}
+
+export function applyTheme() {
+  const target = document.body
+  if (!target) return
+
+  // Resolved **before** the classes come off. `getTheme()` falls back to what
+  // the document already says, and the loop below is what erases the answer:
+  // asking afterwards read a body with no `theme-*` left on it, and every boot
+  // fell back to the default no matter what the server had rendered.
+  const theme = getTheme()
+
+  for (const name of Array.from(target.classList)) {
+    if (name.startsWith("theme-")) target.classList.remove(name)
+  }
+  target.classList.add(`theme-${theme}`)
+}
+
+export function apply() {
+  applyMode()
+  applyTheme()
+}
+
+function announce() {
+  document.dispatchEvent(
+    new CustomEvent(CHANGE_EVENT, {
+      detail: { mode: getMode(), resolvedMode: resolvedMode(), theme: getTheme() }
+    })
+  )
+}
+
+// Follow the OS while the mode is "system", like next-themes does.
+let watching = false
+
+export function watchSystem() {
+  if (watching) return
+  watching = true
+
+  window.matchMedia(DARK_QUERY).addEventListener("change", () => {
+    if (getMode() !== "system") return
+
+    applyMode()
+    announce()
+  })
+}

data/app/javascript/shadcn/top_layer.js

@@ -0,0 +1,59 @@
+// Promotes floating content to the browser's top layer.
+//
+// `position: fixed` escapes overflow clipping but never escapes a *stacking
+// context*: a layer's `z-50` is scoped to the nearest positioned ancestor with a
+// z-index, so a `sticky z-40` header, an `isolate` card or anything with
+// `opacity < 1` can bury it. No z-index can fix that from the inside.
+//
+// The Popover API does. `showPopover()` paints the element above every stacking
+// context while leaving it exactly where it is in the DOM — which is what makes
+// it usable here, since moving it would unbind the Stimulus actions on the close
+// buttons and menu items.
+//
+// `manual` rather than `auto`: `auto` brings its own light-dismiss and its own
+// nesting stack, which would fight the layer stack in `dismiss.js`.
+
+export const SUPPORTED =
+  typeof HTMLElement !== "undefined" && Object.hasOwn(HTMLElement.prototype, "popover")
+
+// Older browsers keep the previous behaviour: still `position: fixed`, still
+// correct in the common case, just vulnerable to a stacking context above it.
+const usable = (element) => SUPPORTED && !!element
+
+export function enable(element) {
+  if (!usable(element)) return false
+
+  element.popover = "manual"
+  return true
+}
+
+export function show(element) {
+  if (!usable(element) || !element.popover) return false
+
+  // Throws if it is already showing, or not connected yet.
+  try { element.showPopover() } catch { /* already open */ }
+  return true
+}
+
+export function hide(element) {
+  if (!usable(element) || !element.popover) return false
+
+  try { element.hidePopover() } catch { /* already closed */ }
+  return true
+}
+
+// Hiding a popover does not put it back in the page's flow: the UA gives
+// `[popover]` `position: fixed`, and that applies open or closed. `shadcn.css`
+// neutralises the rest of those defaults but deliberately not `position`, which
+// every other caller here wants — they enable it on a wrapper that is fixed
+// anyway.
+//
+// The Sidebar is the one caller that enables it on an element the page is laid
+// out around. Left enabled, the panel stays out of flow after the mobile sheet
+// closes, and the page is drawn over a sidebar that is still visible.
+export function disable(element) {
+  if (!usable(element)) return false
+
+  element.removeAttribute("popover")
+  return true
+}

data/app/javascript/shadcn/typeahead.js

@@ -0,0 +1,99 @@
+// A one-second character buffer shared by any roving-focus list (menu items,
+// select options): each keystroke is appended to the buffer, which clears
+// itself after a second of silence, and the caller gets back the item to
+// move the highlight to next, or nothing when there is nowhere new to move —
+// ported from Radix's `findNextItem` (vendor/radix/ui/select.tsx:1906-1921),
+// whose body is identical to the dropdown menu's own `getNextMatch`
+// (vendor/radix/ui/menu.tsx:1336-1347), so the search starts at the item
+// currently highlighted and wraps, rather than always scanning from the top
+// of the list.
+//
+// The input differs in Radix's *menu*, not in the file above: `getNextMatch`
+// is handed an array of label strings and the winner mapped back to an item
+// (vendor/radix/ui/menu.tsx:451-454), so two items sharing a label are one
+// candidate there and two here. `findNextItem`'s own callers pass items and
+// compare by identity, exactly as this does.
+//
+// **That difference is kept, and it is a decision rather than an oversight.**
+// With `["Copy", "Copy", "Delete"]` and the second Copy highlighted, Radix's
+// menu takes `values.indexOf("Copy")` — which is 0, the *first* one — then the
+// single-character filter drops every value equal to the current match, so both
+// Copies leave the candidates and the highlight does not move: the second
+// duplicate is unreachable by typing. Here the two are separate elements, so
+// pressing `c` walks from one to the other, which is what a typeahead is for
+// and what a person with two identically named commands in a menu expects.
+//
+// Nothing else diverges: Radix's own *select* compares by identity too, and
+// this is a port of that file. `spec/system/dropdown_menu_spec.rb` pins the
+// duplicate-label case so the choice cannot be undone by accident.
+//
+// Deliberately does not know how the caller moves focus — that stays in each
+// controller, which owns its own item list and highlighting. The current
+// item is a parameter rather than something read off the DOM here.
+export class Typeahead {
+  constructor() {
+    this.buffer = ""
+    this.timer = null
+  }
+
+  search(character, items, currentItem) {
+    clearTimeout(this.timer)
+    // Raw case, not lowercased: Radix compares the raw characters to decide
+    // whether they repeat (select.tsx:1911) and only lowercases for the
+    // `startsWith` match (select.tsx:1918) — "Bb" is not a repeat of "b".
+    this.buffer += character
+    this.timer = setTimeout(() => (this.buffer = ""), 1000)
+
+    return findNextItem(items, this.buffer, currentItem)
+  }
+
+  // Drops the buffer without waiting for its second to elapse. Radix does this
+  // at a *different moment* in each of the two components this class serves:
+  // the select on open — "reset typeahead when we open",
+  // vendor/radix/ui/select.tsx:331-336 — and the menu whenever focus leaves the
+  // content, vendor/radix/ui/menu.tsx:585-590. So the moment is each
+  // controller's to choose, and neither is hardcoded here.
+  reset() {
+    clearTimeout(this.timer)
+    this.buffer = ""
+  }
+}
+
+// This is the "meat" of the typeahead matching logic (vendor/radix/ui/select.tsx:1906-1921,
+// vendor/radix/ui/menu.tsx:1336-1347). It takes a list of items, the search
+// and the current item, and returns the next item (or `undefined`).
+//
+// The search is normalized because if a user has repeatedly pressed a
+// character, we want the exact same behavior as if we only had that one
+// character (ie. cycle through items starting with that character).
+//
+// The items are also reordered by wrapping the array around the current
+// item, so we always look forward from the current item and picking the
+// first match is always the correct one.
+//
+// Finally, if the normalized search is exactly one character, the current
+// item is excluded from the candidates, because otherwise it would always be
+// the first to match and focus would never move. This is as opposed to the
+// regular case, where focus should stay put if the current item still
+// matches.
+function findNextItem(items, search, currentItem) {
+  const isRepeated = search.length > 1 && Array.from(search).every((char) => char === search[0])
+  const normalizedSearch = isRepeated ? search[0] : search
+  const currentItemIndex = currentItem ? items.indexOf(currentItem) : -1
+  let wrapped = wrapArray(items, Math.max(currentItemIndex, 0))
+
+  if (normalizedSearch.length === 1) wrapped = wrapped.filter((item) => item !== currentItem)
+
+  const nextItem = wrapped.find((item) =>
+    item.textContent.trim().toLowerCase().startsWith(normalizedSearch.toLowerCase())
+  )
+
+  return nextItem !== currentItem ? nextItem : undefined
+}
+
+// Wraps an array around itself at a given start index
+// (vendor/radix/ui/select.tsx:1923-1929).
+// Example: `wrapArray([ "a", "b", "c", "d" ], 2)` is `[ "c", "d", "a", "b" ]`.
+function wrapArray(array, startIndex) {
+  return array.map((_, index) => array[(startIndex + index) % array.length])
+}

data/config/importmap.rb

@@ -0,0 +1,6 @@
+# Importmap pins contributed by the engine to the host application.
+pin "shadcn", to: "shadcn/index.js"
+
+pin_all_from ShadcnViewComponent::Engine.root.join("app/javascript/shadcn"),
+             under: "shadcn",
+             to: "shadcn"

data/config/locales/en.yml

@@ -0,0 +1,62 @@
+# Every user-visible string the components render. shadcn hardcodes these in
+# English; a Rails app is likely not English-only, so they go through I18n with
+# the upstream text as the default. Override any key in your own locale files.
+en:
+  shadcn_view_component:
+    breadcrumb:
+      label: breadcrumb
+      more: More
+    calendar:
+      previous: Go to the Previous Month
+      next: Go to the Next Month
+      today_label: "Today, %{date}"
+      selected_label: "%{date}, selected"
+      week_number_header: Week Number
+      week_number: "Week %{number}"
+      choose_month: Choose the Month
+      choose_year: Choose the Year
+    chart:
+      label: Chart
+      value: Value
+    combobox:
+      clear: Clear
+      toggle: Show options
+      remove: Remove
+      # The chips field's accessible name, when the caller gave it no
+      # placeholder to borrow one from.
+      add: Add an item
+    carousel:
+      previous: Previous slide
+      next: Next slide
+    dialog:
+      close: Close
+    pagination:
+      label: pagination
+      previous: Previous
+      next: Next
+      go_to_previous: Go to previous page
+      go_to_next: Go to next page
+      more: More pages
+    toaster:
+      label: Notifications
+      dismiss: Dismiss
+    select:
+      search_label: Search options
+      empty: No results found.
+      dialog_label: Select an option
+      list_label: Options
+    message_scroller:
+      scroll_to_end: Scroll to end
+      scroll_to_start: Scroll to start
+    sidebar:
+      toggle: Toggle Sidebar
+      title: Sidebar
+      description: Displays the mobile sidebar.
+    spinner:
+      loading: Loading
+    theme:
+      toggle: Toggle theme
+      label: Theme
+      light: Light
+      dark: Dark
+      system: System