@refraction-ui/astro 0.13.0 → 0.15.0

package/dist/kanban-board/kanban-board.styles.ts

@@ -0,0 +1,78 @@
+import { cva } from '../shared/index.ts'
+
+/** The outer board: horizontal scroll, flex row, gap between columns. */
+export const kanbanBoardVariants = cva({
+  base: 'flex flex-row gap-4 overflow-x-auto pb-4',
+  variants: {},
+  defaultVariants: {},
+})
+
+/** A single column: muted background, rounded, fixed minimum width. */
+export const kanbanColumnVariants = cva({
+  base: 'flex flex-col min-w-[260px] max-w-[300px] flex-shrink-0 rounded-xl bg-muted/40',
+  variants: {},
+  defaultVariants: {},
+})
+
+/** Column header row: icon slot + title + count badge. */
+export const kanbanColumnHeaderClass =
+  'flex items-center gap-2 px-4 pt-4 pb-2'
+
+/** Column title text. */
+export const kanbanColumnTitleClass = 'flex-1 text-sm font-semibold text-foreground truncate'
+
+/**
+ * Column count badge: a compact pill to the right of the title.
+ * Uses muted tokens so it sits quietly against any column accent.
+ */
+export const kanbanColumnCountClass =
+  'ml-auto inline-flex items-center justify-center rounded-full bg-muted px-2 py-0.5 text-xs font-medium text-muted-foreground'
+
+/**
+ * Thin accent bar directly below the header.
+ * Callers apply `style={{ '--kanban-accent': def.accent }}` on the column
+ * element; this bar reads `var(--kanban-accent)` via an inline style.
+ * When no accent is supplied the bar is invisible (transparent).
+ */
+export const kanbanAccentBarClass = 'h-0.5 w-full'
+
+/**
+ * Note/gate bar shown beneath the accent bar.
+ * Displays brief stage notes (e.g. "Technical screen required").
+ */
+export const kanbanNoteBarClass =
+  'mx-4 mb-2 rounded-md bg-muted px-3 py-1.5 text-xs text-muted-foreground'
+
+/** Column body: card stack with gap, padded sides and bottom. */
+export const kanbanColumnBodyClass = 'flex flex-col gap-2 px-3 pb-3'
+
+/**
+ * "+N more" overflow button.
+ * Styled as a subtle full-width ghost button inside the column.
+ */
+export const kanbanOverflowButtonClass = [
+  'mt-1 w-full rounded-lg border border-dashed border-border',
+  'py-1.5 text-center text-xs text-muted-foreground',
+  'transition-colors hover:bg-muted hover:text-foreground',
+  'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+].join(' ')
+
+/**
+ * Default card surface.
+ *
+ * Variants:
+ * - `clickable: 'true'`  — adds hover treatment for interactive cards.
+ * - `clickable: 'false'` — static (default).
+ */
+export const kanbanCardVariants = cva({
+  base: 'rounded-lg border border-border bg-card p-3 text-sm text-foreground',
+  variants: {
+    clickable: {
+      true: 'cursor-pointer transition-colors hover:bg-muted/60',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    clickable: 'false',
+  },
+})

package/dist/kanban-board/kanban-board.ts

@@ -0,0 +1,82 @@
+/** A single column definition for the Kanban board. */
+export type KanbanColumnDef = {
+  /** Unique identifier for this column (matches cards' column id). */
+  id: string
+  /** Display title of the column (e.g. stage name). */
+  title: string
+  /** Optional accent color applied via CSS var `--kanban-accent`. */
+  accent?: string
+  /** Optional note or gate description shown below the column header. */
+  note?: string
+}
+
+export interface KanbanBoardAPI {
+  /** ARIA attributes to spread on the board container. */
+  ariaProps: { role: 'group'; 'aria-label': string }
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic board props.
+ *
+ * Returns `role="group"` with a fixed accessible label and data attributes
+ * so adapters can style based on state without inlining logic.
+ */
+export function createKanbanBoard(): KanbanBoardAPI {
+  return {
+    ariaProps: {
+      role: 'group',
+      'aria-label': 'Board',
+    },
+    dataAttributes: {
+      'data-component': 'kanban-board',
+    },
+  }
+}
+
+/**
+ * Bucket cards into a Map keyed by column id, preserving column order.
+ * Columns that have no cards get an empty array entry so callers can always
+ * iterate `columns` and look up their bucket safely.
+ *
+ * @param cards - All cards to distribute.
+ * @param getColumnId - Selector that reads the column id from a card.
+ * @param columns - Column definitions (determines output order).
+ */
+export function cardsByColumn<T>(
+  cards: T[],
+  getColumnId: (c: T) => string,
+  columns: KanbanColumnDef[],
+): Map<string, T[]> {
+  const map = new Map<string, T[]>()
+  // Pre-populate every column so empty columns are present.
+  for (const col of columns) {
+    map.set(col.id, [])
+  }
+  for (const card of cards) {
+    const colId = getColumnId(card)
+    const bucket = map.get(colId)
+    if (bucket !== undefined) {
+      bucket.push(card)
+    }
+    // Cards referencing unknown columns are silently dropped.
+  }
+  return map
+}
+
+/**
+ * Split a card list into a visible slice and an overflow count.
+ *
+ * @param cards - Full list of cards in the column.
+ * @param cap - Maximum visible cards. Defaults to 5.
+ */
+export function visibleAndOverflow<T>(
+  cards: T[],
+  cap = 5,
+): { visible: T[]; overflow: number } {
+  if (cards.length <= cap) {
+    return { visible: cards, overflow: 0 }
+  }
+  return { visible: cards.slice(0, cap), overflow: cards.length - cap }
+}

package/dist/marquee-strip/index.ts

@@ -0,0 +1,14 @@
+export {
+  createMarqueeStrip,
+  type MarqueeStripProps,
+  type MarqueeStripAPI,
+} from './marquee-strip.js'
+
+export {
+  marqueeStripVariants,
+  marqueeStripInnerClass,
+  marqueeStripScrollOuterClass,
+  marqueeStripScrollTrackClass,
+  marqueeStripLabelClass,
+  marqueeStripItemClass,
+} from './marquee-strip.styles.js'

package/dist/marquee-strip/marquee-strip.styles.ts

@@ -0,0 +1,61 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Container — a full-width band with a subtle muted background and border.
+ *
+ * The `scroll` variant switches the inner track from wrapping flex to an
+ * overflow-hidden marquee track. See {@link marqueeStripInnerClass} and
+ * {@link marqueeStripScrollTrackClass} for the corresponding track classes.
+ */
+export const marqueeStripVariants = cva({
+  base: 'w-full bg-muted/30 border-y border-border py-3',
+  variants: {
+    scroll: {
+      true: '',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    scroll: 'false',
+  },
+})
+
+/**
+ * Inner wrapper for static (non-scroll) mode.
+ *
+ * Items wrap naturally so they never overflow on narrow viewports.
+ */
+export const marqueeStripInnerClass =
+  'flex flex-wrap items-center gap-3 px-4'
+
+/**
+ * Outer clip track for scroll mode — hides overflow so the looping animation
+ * is invisible at the edges.
+ */
+export const marqueeStripScrollOuterClass = 'overflow-hidden px-4'
+
+/**
+ * Moving track for scroll mode.
+ *
+ * The `marquee` keyframe must be defined in the consuming app's global CSS
+ * (or via a Tailwind plugin). The canonical definition is:
+ *
+ * ```css
+ * @keyframes marquee {
+ *   from { transform: translateX(0); }
+ *   to   { transform: translateX(-50%); }
+ * }
+ * ```
+ *
+ * Items are duplicated once by the adapter so the strip appears seamless
+ * (the track is effectively 200 % wide and translates to –50 %).
+ */
+export const marqueeStripScrollTrackClass =
+  'flex items-center gap-3 w-max animate-[marquee_30s_linear_infinite]'
+
+/** Strip label — shown before the items (uppercase eyebrow style). */
+export const marqueeStripLabelClass =
+  'text-xs font-semibold uppercase tracking-widest text-muted-foreground shrink-0'
+
+/** Individual item text. */
+export const marqueeStripItemClass = 'text-sm text-foreground'

package/dist/marquee-strip/marquee-strip.ts

@@ -0,0 +1,35 @@
+import type { AccessibilityProps } from '../shared/index.ts'
+
+export interface MarqueeStripProps {
+  /** Whether to continuously scroll the items. */
+  scroll?: boolean
+}
+
+export interface MarqueeStripAPI {
+  /** ARIA attributes to spread on the container element (`role="group"`). */
+  ariaProps: Partial<AccessibilityProps>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic container props for a marquee strip.
+ *
+ * Returns `role="group"` plus a `data-scroll` attribute. Adapters spread these
+ * onto their container and render the label and items themselves. In scroll mode
+ * the adapter is responsible for duplicating items once to achieve a seamless
+ * loop (the CSS `marquee` keyframe translates from 0 to –50%).
+ */
+export function createMarqueeStrip(props: MarqueeStripProps = {}): MarqueeStripAPI {
+  const { scroll = false } = props
+
+  const ariaProps: Partial<AccessibilityProps> = {
+    role: 'group',
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-scroll': String(scroll),
+  }
+
+  return { ariaProps, dataAttributes }
+}

package/dist/mastery-bar/index.ts

@@ -0,0 +1,15 @@
+export {
+  clampPercent,
+  createMasteryBar,
+  type MasteryBarSize,
+  type MasteryBarProps,
+  type MasteryBarAPI,
+} from './mastery-bar.js'
+
+export {
+  masteryBarVariants,
+  masteryBarFillVariants,
+  masteryBarLabelClass,
+  masteryBarLeadingLabelClass,
+  masteryBarHeaderClass,
+} from './mastery-bar.styles.js'

package/dist/mastery-bar/mastery-bar.styles.ts

@@ -0,0 +1,45 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Track (outer container): rounded, muted background.
+ * `size` variant controls the track height.
+ */
+export const masteryBarVariants = cva({
+  base: 'w-full overflow-hidden rounded-full bg-muted',
+  variants: {
+    size: {
+      sm: 'h-1.5',
+      md: 'h-2',
+      lg: 'h-3',
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+  },
+})
+
+/**
+ * Fill (inner bar): rounded, primary background.
+ * `muted` variant renders at reduced opacity for secondary/inactive states.
+ */
+export const masteryBarFillVariants = cva({
+  base: 'h-full rounded-full bg-primary',
+  variants: {
+    muted: {
+      true: 'bg-primary/70',
+      false: 'bg-primary',
+    },
+  },
+  defaultVariants: {
+    muted: 'false',
+  },
+})
+
+/** Class applied to each text label (leading or trailing). */
+export const masteryBarLabelClass = 'text-xs text-muted-foreground'
+
+/** Class for the leading (left-side) label. */
+export const masteryBarLeadingLabelClass = 'text-xs text-muted-foreground'
+
+/** Header row above the track: leading label on the left, label on the right. */
+export const masteryBarHeaderClass = 'flex justify-between items-baseline mb-1'

package/dist/mastery-bar/mastery-bar.ts

@@ -0,0 +1,55 @@
+/** Visual size of a mastery bar. */
+export type MasteryBarSize = 'sm' | 'md' | 'lg'
+
+export interface MasteryBarProps {
+  /** Progress value (0–100). Values outside this range are clamped. */
+  value: number
+  /** Label shown on the right side of the header row. */
+  label?: string
+  /** Label shown on the left side of the header row. */
+  leadingLabel?: string
+  /** Visual size of the track. */
+  size?: MasteryBarSize
+  /** Renders the fill at reduced opacity to indicate a muted/secondary state. */
+  muted?: boolean
+}
+
+export interface MasteryBarAPI {
+  /** ARIA attributes to spread on the progressbar element. */
+  ariaProps: Record<string, string | number | boolean>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Clamp a raw numeric value to the [0, 100] range.
+ *
+ * Values below 0 become 0; values above 100 become 100; NaN is treated as 0.
+ */
+export function clampPercent(value: number): number {
+  if (Number.isNaN(value)) return 0
+  return Math.min(100, Math.max(0, value))
+}
+
+/**
+ * Build the framework-agnostic progressbar props for a mastery bar.
+ *
+ * Returns `role="progressbar"` ARIA attributes plus data attributes; adapters
+ * spread these onto their track element.
+ */
+export function createMasteryBar({ value }: Pick<MasteryBarProps, 'value'>): MasteryBarAPI {
+  const clamped = clampPercent(value)
+
+  const ariaProps: Record<string, string | number | boolean> = {
+    role: 'progressbar',
+    'aria-valuenow': clamped,
+    'aria-valuemin': 0,
+    'aria-valuemax': 100,
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-value': String(clamped),
+  }
+
+  return { ariaProps, dataAttributes }
+}

package/dist/numbered-steps/index.ts

@@ -0,0 +1,16 @@
+export {
+  createNumberedSteps,
+  padOrdinal,
+  stepColumns,
+  type NumberedStepItem,
+  type NumberedStepsProps,
+  type NumberedStepsAPI,
+} from './numbered-steps.js'
+
+export {
+  numberedStepsVariants,
+  numberedStepsItemClass,
+  numberedStepsOrdinalClass,
+  numberedStepsTitleClass,
+  numberedStepsBodyClass,
+} from './numbered-steps.styles.js'

package/dist/numbered-steps/numbered-steps.styles.ts

@@ -0,0 +1,36 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Container grid for the numbered steps. The `columns` variant maps to a
+ * fixed Tailwind grid-cols class; adapters that need a dynamic column count
+ * use `gridTemplateColumns` inline style via {@link stepColumns} instead and
+ * omit this variant.
+ */
+export const numberedStepsVariants = cva({
+  base: 'grid gap-6',
+  variants: {
+    columns: {
+      '2': 'grid-cols-2',
+      '3': 'grid-cols-3',
+      '4': 'grid-cols-4',
+      '5': 'grid-cols-5',
+    },
+  },
+  defaultVariants: {
+    columns: '3',
+  },
+})
+
+/** Individual step card. */
+export const numberedStepsItemClass =
+  'rounded-xl border border-border bg-card p-5'
+
+/** Zero-padded ordinal badge above each step title. */
+export const numberedStepsOrdinalClass = 'font-mono text-sm text-primary'
+
+/** Step title. */
+export const numberedStepsTitleClass = 'mt-2 text-sm font-bold text-foreground'
+
+/** Step body copy. */
+export const numberedStepsBodyClass =
+  'mt-1 text-xs text-muted-foreground leading-relaxed'

package/dist/numbered-steps/numbered-steps.ts

@@ -0,0 +1,64 @@
+/** A single step item in the numbered steps grid. */
+export type NumberedStepItem = {
+  /** Step title displayed prominently below the ordinal badge. */
+  title: string
+  /** Step body copy displayed below the title. */
+  body: string
+}
+
+export interface NumberedStepsProps {
+  /** The step items to display. */
+  items: NumberedStepItem[]
+  /**
+   * Number of grid columns. When omitted, defaults to clamping the item count
+   * to the 2–5 range via {@link stepColumns}.
+   */
+  columns?: number
+}
+
+export interface NumberedStepsAPI {
+  /** ARIA attributes to spread on the container element (`role="list"`). */
+  ariaProps: { role: 'list' }
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Zero-pad a 1-indexed ordinal to at least two digits.
+ *
+ * @example
+ * padOrdinal(1)  // '01'
+ * padOrdinal(10) // '10'
+ */
+export function padOrdinal(n: number): string {
+  return String(n).padStart(2, '0')
+}
+
+/**
+ * Derive the number of grid columns from the item count.
+ * Clamps the count to the 2–5 range.
+ *
+ * @example
+ * stepColumns(3) // 3
+ * stepColumns(1) // 2
+ * stepColumns(6) // 5
+ */
+export function stepColumns(count: number): number {
+  return Math.min(5, Math.max(2, count))
+}
+
+/**
+ * Build the framework-agnostic container props for a numbered-steps grid.
+ *
+ * Returns `role="list"` plus data attributes; adapters spread these onto their
+ * container and render each step as a `role="listitem"`.
+ */
+export function createNumberedSteps(): NumberedStepsAPI {
+  const ariaProps = { role: 'list' } as const
+
+  const dataAttributes: Record<string, string> = {
+    'data-component': 'numbered-steps',
+  }
+
+  return { ariaProps, dataAttributes }
+}

package/dist/pricing-card/index.ts

@@ -0,0 +1,19 @@
+export {
+  createPricingCard,
+  type PricingCtaVariant,
+  type PricingCardOptions,
+  type PricingCardAPI,
+} from './pricing-card.js'
+
+export {
+  pricingCardVariants,
+  pricingCardBadgeClass,
+  pricingCardNameClass,
+  pricingCardPriceClass,
+  pricingCardPeriodClass,
+  pricingCardDescriptionClass,
+  pricingCardFeatureListClass,
+  pricingCardFeatureRowClass,
+  pricingCardFeatureTickClass,
+  pricingCtaVariants,
+} from './pricing-card.styles.js'

package/dist/pricing-card/pricing-card.styles.ts

@@ -0,0 +1,71 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Root pricing card container. The `featured` variant adds a primary-coloured
+ * ring to draw the eye to the recommended plan.
+ */
+export const pricingCardVariants = cva({
+  base: [
+    'relative flex flex-col rounded-2xl border border-border bg-card p-6',
+    'transition-shadow',
+  ].join(' '),
+  variants: {
+    featured: {
+      true: 'ring-1 ring-primary',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    featured: 'false',
+  },
+})
+
+/** "Best value" / "Most popular" badge above the plan name. */
+export const pricingCardBadgeClass =
+  'mb-3 inline-flex items-center rounded-full bg-primary/10 px-2.5 py-0.5 text-xs font-medium text-primary'
+
+/** Plan name (e.g. "Pro", "Starter"). */
+export const pricingCardNameClass = 'text-lg font-bold text-foreground'
+
+/** Main price figure (e.g. "$29", "Free"). */
+export const pricingCardPriceClass = 'text-3xl font-bold text-foreground'
+
+/** Billing period or qualifier (e.g. "/ month", "forever"). */
+export const pricingCardPeriodClass = 'text-sm text-muted-foreground'
+
+/** Short marketing description beneath the price. */
+export const pricingCardDescriptionClass = 'text-sm text-muted-foreground'
+
+/** Unordered list of included features. */
+export const pricingCardFeatureListClass = 'flex flex-col gap-2'
+
+/** A single feature row — tick icon + text. */
+export const pricingCardFeatureRowClass = 'flex items-start gap-2 text-sm text-foreground'
+
+/** Inline check SVG rendered before each feature string. */
+export const pricingCardFeatureTickClass = 'mt-0.5 size-4 shrink-0 text-primary'
+
+/**
+ * CTA button/link that appears at the bottom of the card.
+ *
+ * `default` — filled primary style (call to action on featured plans).
+ * `outline` — bordered secondary style (for non-featured plans).
+ */
+export const pricingCtaVariants = cva({
+  base: [
+    'mt-auto inline-flex w-full items-center justify-center rounded-lg px-4 py-2',
+    'text-sm font-medium transition-colors',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+    'disabled:pointer-events-none disabled:opacity-50',
+  ].join(' '),
+  variants: {
+    variant: {
+      default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+      outline:
+        'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+  },
+})

package/dist/pricing-card/pricing-card.ts

@@ -0,0 +1,37 @@
+import type { AccessibilityProps } from '../shared/index.ts'
+
+/** CTA button/link visual variant. */
+export type PricingCtaVariant = 'default' | 'outline'
+
+export interface PricingCardOptions {
+  /** Whether this card is highlighted as the featured / recommended plan. */
+  featured?: boolean
+}
+
+export interface PricingCardAPI {
+  /** ARIA props to spread on the card container. */
+  ariaProps: Partial<AccessibilityProps>
+  /** Data attributes for styling hooks and CSS selectors. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic props for a pricing plan card.
+ *
+ * Returns `role="group"` (semantically groups the plan's content without
+ * imposing listitem semantics on a standalone card) and a `data-featured`
+ * attribute that adapters can use for conditional ring/highlight styling.
+ */
+export function createPricingCard(options: PricingCardOptions = {}): PricingCardAPI {
+  const { featured = false } = options
+
+  const ariaProps: Partial<AccessibilityProps> = {
+    role: 'group',
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-featured': String(featured),
+  }
+
+  return { ariaProps, dataAttributes }
+}

package/dist/section-head/index.ts

@@ -0,0 +1,13 @@
+export {
+  createSectionHead,
+  type SectionHeadAlign,
+  type SectionHeadProps,
+  type SectionHeadAPI,
+} from './section-head.js'
+
+export {
+  sectionHeadVariants,
+  sectionHeadKickerClass,
+  sectionHeadTitleClass,
+  sectionHeadLedeClass,
+} from './section-head.styles.js'

package/dist/section-head/section-head.styles.ts

@@ -0,0 +1,30 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Container variant that controls the alignment of the whole cluster.
+ * Center: auto-margins + text-center + constrained max-width for comfortable
+ * line length. Left: no margin constraint, flush left.
+ */
+export const sectionHeadVariants = cva({
+  base: 'flex flex-col',
+  variants: {
+    align: {
+      center: 'mx-auto text-center max-w-2xl',
+      left: 'text-left',
+    },
+  },
+  defaultVariants: {
+    align: 'center',
+  },
+})
+
+/** Small-caps eyebrow label above the title. */
+export const sectionHeadKickerClass =
+  'text-[11px] uppercase tracking-widest text-primary font-semibold'
+
+/** Primary h2 heading. */
+export const sectionHeadTitleClass =
+  'text-3xl sm:text-4xl font-bold tracking-tight text-foreground'
+
+/** Optional lede paragraph below the title. */
+export const sectionHeadLedeClass = 'mt-3 text-muted-foreground leading-relaxed'