Scroll Progress

/** @jsxImportSource hono/jsx */
import { cn, type ClassValue } from "@/registry/lib/cn"

// Scroll Progress — shadcn-htmx, htmx v4 + Tailwind v4.
//
// A reading-position indicator: a thin bar whose fill tracks how far the user
// has scrolled the page (or a named scroller). This is DISTINCT from Progress
// (registry/ui/progress.tsx), which is value-driven via aria-valuenow — here
// there is no value, just scroll position the user already controls.
//
// Built entirely on CSS scroll-driven animations — ZERO JavaScript, no scroll
// listeners. The platform progresses a keyframe animation along a scroll
// progress timeline instead of the document's time-based timeline:
//   - animation-timeline: scroll(root block) ties the fill's animation to the
//     root scroller's block axis (i.e. the page's vertical scrollbar):
//       repos/mdn/files/en-us/web/css/reference/properties/animation-timeline/scroll/index.md
//       repos/mdn/files/en-us/web/css/reference/properties/animation-timeline/index.md
//   - a named timeline (scroll-timeline-name on the scroller, referenced as a
//     <dashed-ident> in animation-timeline) drives progress from any scroll
//     container, not just the page:
//       repos/mdn/files/en-us/web/css/reference/properties/scroll-timeline-name/index.md
//   - overview of the module:
//       repos/mdn/files/en-us/web/css/guides/scroll-driven_animations/index.md
//
// The fill animation (scn-scroll-progress: scaleX(0) -> scaleX(1)) lives in
// app/styles/input.css alongside the other scn-* keyframes. animation-timeline
// is a reset-only part of the `animation` shorthand, so the keyframe + timeline
// are applied from CSS keyed on data-slot rather than a Tailwind animate-[…]
// utility (which would reset the timeline back to auto). The CSS also pins a
// prefers-reduced-motion fallback (full bar, no animation) per:
//   repos/mdn/files/en-us/web/css/reference/at-rules/@media/prefers-reduced-motion/index.md
//
// Accessibility: this is a decorative affordance that mirrors the scroll
// position the user already commands — there is no value to announce and we
// can't update aria-valuenow without scroll listeners (which we don't ship).
// So the bar is aria-hidden; it adds no noise to the accessibility tree.
//   repos/mdn/files/en-us/web/accessibility/aria/reference/attributes/aria-hidden/

export type ScrollProgressPosition = "top" | "bottom"

// The track is fixed to the viewport edge and spans the full inline size. It
// sits above page content (z-50) and never intercepts pointer events.
const trackBase =
  "pointer-events-none fixed inset-x-0 z-50 h-1 w-full overflow-hidden bg-primary/15"

const positions: Record<ScrollProgressPosition, string> = {
  top: "top-0",
  bottom: "bottom-0",
}

// The fill grows from the inline-start edge. transform-origin + the scaleX
// keyframe is set in input.css (keyed on data-slot="scroll-progress-indicator").
const fillBase = "h-full w-full origin-left bg-primary"

type ScrollProgressProps = {
  // Which viewport edge the bar pins to. top (default) is the classic reading
  // bar under a sticky header; bottom hugs the foot of the page.
  position?: ScrollProgressPosition
  // Drive the bar from a named scroller instead of the page. Set the matching
  // scroll-timeline-name (a --dashed-ident) on that scroll container's CSS;
  // the bar then references it via animation-timeline. Omit to track the page
  // root (scroll(root block)).
  timeline?: string
  class?: ClassValue
  id?: string
  // htmx + arbitrary attributes ride onto the root track element.
  [key: `hx-${string}`]: any
  [key: `data-${string}`]: any
  [key: `aria-${string}`]: any
}

export function ScrollProgress(props: ScrollProgressProps) {
  const {
    position = "top",
    timeline,
    class: className,
    id,
    ...rest
  } = props as ScrollProgressProps & Record<string, any>
  return (
    <div
      id={id}
      data-slot="scroll-progress"
      data-position={position}
      aria-hidden="true"
      class={cn(trackBase, positions[position as ScrollProgressPosition], className)}
      {...rest}
    >
      <div
        data-slot="scroll-progress-indicator"
        // A named timeline overrides the default page-root timeline. Set as an
        // inline property so it cascades after the keyframe (which is reset-only
        // inside the `animation` shorthand).
        style={timeline ? `animation-timeline: ${timeline}` : undefined}
        class={fillBase}
      />
    </div>
  )
}

{# Scroll Progress macro — shadcn-htmx, htmx v4 + Tailwind v4.
   Mirrors registry/ui/scroll-progress.tsx. A reading-position bar whose fill
   tracks scroll position — ZERO JavaScript, pure CSS scroll-driven animation.

   Built on CSS scroll-driven animations:
     - animation-timeline: scroll(root block) ties the fill to the page scroller
       repos/mdn/.../css/reference/properties/animation-timeline/scroll
       repos/mdn/.../css/reference/properties/animation-timeline
     - a named timeline (scroll-timeline-name on the scroller) drives it from
       any scroll container
       repos/mdn/.../css/reference/properties/scroll-timeline-name
     - module overview: repos/mdn/.../css/guides/scroll-driven_animations

   The fill keyframe (scn-scroll-progress: scaleX(0)->scaleX(1)) + the default
   animation-timeline live in app/styles/input.css keyed on data-slot, plus a
   prefers-reduced-motion fallback. The bar is decorative (aria-hidden) — it
   mirrors scroll position the user already controls.

   Usage:
     {% from "components/scroll-progress.html" import scroll_progress %}
     {{ scroll_progress() }}                          {# tracks the page #}
     {{ scroll_progress(timeline="--article") }}      {# named scroller #} #}

{% macro scroll_progress(position="top", timeline=none, id=none, extra_class="", attrs={}) -%}
{%- set edge = "top-0" if position == "top" else "bottom-0" -%}
<div {% if id %}id="{{ id }}"{% endif %}
     data-slot="scroll-progress"
     data-position="{{ position }}"
     aria-hidden="true"
     class="pointer-events-none fixed inset-x-0 z-50 h-1 w-full overflow-hidden bg-primary/15 {{ edge }} {{ extra_class }}"
     {%- for k, v in attrs.items() %} {{ k|replace('_','-') }}="{{ v }}"{% endfor %}>
  <div data-slot="scroll-progress-indicator"
       {% if timeline %}style="animation-timeline: {{ timeline }}"{% endif %}
       class="h-full w-full origin-left bg-primary"></div>
</div>
{%- endmacro %}

{{/* Scroll Progress template — shadcn-htmx, htmx v4 + Tailwind v4.
     Mirrors registry/ui/scroll-progress.tsx. A reading-position bar whose fill
     tracks scroll position — ZERO JavaScript, pure CSS scroll-driven animation.

     Built on CSS scroll-driven animations:
       - animation-timeline: scroll(root block) ties the fill to the page scroller
         repos/mdn/.../css/reference/properties/animation-timeline/scroll
       - a named timeline (scroll-timeline-name on the scroller) drives it from
         any scroll container
         repos/mdn/.../css/reference/properties/scroll-timeline-name

     The fill keyframe (scn-scroll-progress) + default animation-timeline live in
     app/styles/input.css keyed on data-slot, with a prefers-reduced-motion
     fallback. The bar is decorative (aria-hidden). */}}

{{define "scroll-progress"}}
{{- $position := or .Position "top" -}}
{{- $edge := "top-0" -}}{{- if eq $position "bottom" -}}{{- $edge = "bottom-0" -}}{{- end -}}
<div {{if .ID}}id="{{.ID}}"{{end}}
     data-slot="scroll-progress"
     data-position="{{$position}}"
     aria-hidden="true"
     class="pointer-events-none fixed inset-x-0 z-50 h-1 w-full overflow-hidden bg-primary/15 {{$edge}}">
  <div data-slot="scroll-progress-indicator"
       {{if .Timeline}}style="animation-timeline: {{.Timeline}}"{{end}}
       class="h-full w-full origin-left bg-primary"></div>
</div>
{{end}}

defmodule ShadcnHtmx.Components.ScrollProgress do
  @moduledoc """
  Scroll Progress — shadcn-htmx, htmx v4 + Tailwind v4 for Phoenix.

  Mirrors registry/ui/scroll-progress.tsx. A reading-position bar whose fill
  tracks how far the user has scrolled the page (or a named scroller). This is
  DISTINCT from Progress (value-driven via aria-valuenow) — here there is no
  value, just scroll position the user already controls.

  Built entirely on CSS scroll-driven animations — ZERO JavaScript, no scroll
  listeners:
    - animation-timeline: scroll(root block) ties the fill to the page scroller
      repos/mdn/.../css/reference/properties/animation-timeline/scroll
      repos/mdn/.../css/reference/properties/animation-timeline
    - a named timeline (scroll-timeline-name on the scroller, referenced as a
      <dashed-ident>) drives progress from any scroll container
      repos/mdn/.../css/reference/properties/scroll-timeline-name
    - module overview: repos/mdn/.../css/guides/scroll-driven_animations

  The fill keyframe (scn-scroll-progress: scaleX(0)->scaleX(1)) + the default
  animation-timeline live in app/styles/input.css keyed on data-slot, with a
  prefers-reduced-motion fallback. The bar is decorative (aria-hidden) — it
  mirrors scroll position the user already commands.

  ## Examples

      <.scroll_progress />                        # tracks the page
      <.scroll_progress position="bottom" />
      <.scroll_progress timeline="--article" />   # named scroller
  """

  use Phoenix.Component

  attr :position, :string, default: "top", values: ~w(top bottom)
  attr :timeline, :string, default: nil
  attr :class, :string, default: nil
  attr :rest, :global

  def scroll_progress(assigns) do
    edge = if assigns.position == "bottom", do: "bottom-0", else: "top-0"
    assigns = assign(assigns, :edge, edge)

    ~H"""
    <div
      data-slot="scroll-progress"
      data-position={@position}
      aria-hidden="true"
      class={[
        "pointer-events-none fixed inset-x-0 z-50 h-1 w-full overflow-hidden bg-primary/15",
        @edge,
        @class
      ]}
      {@rest}
    >
      <div
        data-slot="scroll-progress-indicator"
        style={if @timeline, do: "animation-timeline: #{@timeline}"}
        class="h-full w-full origin-left bg-primary"
      />
    </div>
    """
  end
end

<!--
  shadcn-htmx — raw HTML scroll-progress snippets.

  A reading-position bar whose fill tracks scroll position — ZERO JavaScript,
  pure CSS scroll-driven animation. The fill keyframe (scn-scroll-progress)
  and the default animation-timeline: scroll(root block) live in input.css
  keyed on data-slot="scroll-progress-indicator", with a prefers-reduced-motion
  fallback. The bar is decorative (aria-hidden) — it mirrors the scroll
  position the user already controls. Relies only on theme tokens.

  Built on CSS scroll-driven animations:
    animation-timeline: scroll() / scroll-timeline-name — see
    repos/mdn/.../css/reference/properties/animation-timeline.
-->

<!-- Page reading bar (pinned to the top, tracks the page scroll) -->
<div data-slot="scroll-progress" data-position="top" aria-hidden="true"
     class="pointer-events-none fixed inset-x-0 top-0 z-50 h-1 w-full overflow-hidden bg-primary/15">
  <div data-slot="scroll-progress-indicator" class="h-full w-full origin-left bg-primary"></div>
</div>

<!-- Pinned to the bottom edge instead -->
<div data-slot="scroll-progress" data-position="bottom" aria-hidden="true"
     class="pointer-events-none fixed inset-x-0 bottom-0 z-50 h-1 w-full overflow-hidden bg-primary/15">
  <div data-slot="scroll-progress-indicator" class="h-full w-full origin-left bg-primary"></div>
</div>

<!-- Driven by a named scroller: put `scroll-timeline-name: --article` on the
     scroll container in your CSS, then point the fill at it. -->
<div data-slot="scroll-progress" data-position="top" aria-hidden="true"
     class="pointer-events-none fixed inset-x-0 top-0 z-50 h-1 w-full overflow-hidden bg-primary/15">
  <div data-slot="scroll-progress-indicator" style="animation-timeline: --article"
       class="h-full w-full origin-left bg-primary"></div>
</div>