@refraction-ui/astro 0.14.0 → 0.15.1

package/dist/index.ts

@@ -56,6 +56,7 @@ export * from './astro-inline-editor/index.ts';
 export * from './astro-input/index.ts';
 export * from './astro-input-group/index.ts';
 export * from './astro-install-prompt/index.ts';
+export * from './astro-kanban-board/index.ts';
 export * from './astro-keyboard-shortcut/index.ts';
 export * from './astro-language-selector/index.ts';
 export * from './astro-link-card/index.ts';
@@ -66,6 +67,7 @@ export * from './astro-logger/index.ts';
 export * from './astro-markdown-renderer/index.ts';
 export * from './astro-marquee-strip/index.ts';
 export * from './astro-mastery-bar/index.ts';
+export * from './astro-mascot/index.ts';
 export * from './astro-mini-map/index.ts';
 export * from './astro-mobile-nav/index.ts';
 export * from './astro-navbar/index.ts';
@@ -95,7 +97,9 @@ export * from './astro-skeleton/index.ts';
 export * from './astro-skip-to-content/index.ts';
 export * from './astro-slide-viewer/index.ts';
 export * from './astro-slider/index.ts';
+export * from './astro-slot-picker/index.ts';
 export * from './astro-social-auth-button/index.ts';
+export * from './astro-sortable-list/index.ts';
 export * from './astro-stat-grid/index.ts';
 export * from './astro-status-indicator/index.ts';
 export * from './astro-steps/index.ts';

package/dist/kanban-board/index.ts

@@ -0,0 +1,20 @@
+export {
+  createKanbanBoard,
+  cardsByColumn,
+  visibleAndOverflow,
+  type KanbanColumnDef,
+  type KanbanBoardAPI,
+} from './kanban-board.js'
+
+export {
+  kanbanBoardVariants,
+  kanbanColumnVariants,
+  kanbanColumnHeaderClass,
+  kanbanColumnTitleClass,
+  kanbanColumnCountClass,
+  kanbanAccentBarClass,
+  kanbanNoteBarClass,
+  kanbanColumnBodyClass,
+  kanbanOverflowButtonClass,
+  kanbanCardVariants,
+} from './kanban-board.styles.js'

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/mascot/index.ts

@@ -0,0 +1,2 @@
+export * from './mascot.ts'
+export * from './mascot.styles.ts'

package/dist/mascot/mascot.styles.ts

@@ -0,0 +1,33 @@
+import { cva } from '../shared/index.ts'
+import type { TokenContract } from '../shared/index.ts'
+
+export const mascotTokens: TokenContract = {
+  name: 'mascot',
+  tokens: {
+    primary: { variable: '--rfr-mascot-primary', fallback: '138 60% 51%' },
+    secondary: { variable: '--rfr-mascot-secondary', fallback: '138 60% 83%' },
+    accent: { variable: '--rfr-mascot-accent', fallback: '26 100% 67%' },
+    stroke: { variable: '--rfr-mascot-stroke', fallback: '139 59% 16%' },
+  },
+}
+
+export const mascotVariants = cva({
+  base: 'inline-block select-none transition-all duration-300',
+  variants: {
+    size: {
+      sm: 'w-24 h-auto',
+      md: 'w-36 h-auto',
+      lg: 'w-48 h-auto',
+      xl: 'w-64 h-auto',
+    },
+    animation: {
+      none: '',
+      bounce: 'motion-safe:animate-bounce',
+      float: 'rfr-mascot-float',
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+    animation: 'none',
+  },
+})

package/dist/mascot/mascot.ts

@@ -0,0 +1,121 @@
+import type { AccessibilityProps } from '../shared/index.ts'
+
+export type MascotMood = 'happy' | 'think' | 'wave'
+export type MascotAnimation = 'none' | 'bounce' | 'float'
+export type MascotSize = 'sm' | 'md' | 'lg' | 'xl'
+
+export interface MascotProps {
+  mood?: MascotMood
+  animation?: MascotAnimation
+  size?: MascotSize
+  animate?: boolean
+}
+
+export interface MascotAPI {
+  /** ARIA attributes to spread on the root element */
+  ariaProps: Record<string, string | number | boolean>
+  /** Data attributes for CSS styling hooks and states */
+  dataAttributes: Record<string, string>
+  /** Active mascot state configuration */
+  state: {
+    mood: MascotMood
+    animation: MascotAnimation
+    size: MascotSize
+    animate: boolean
+  }
+  /** Mood styles mapping moods to CSS custom properties */
+  style: Record<string, string>
+}
+
+/**
+ * Maps mascot moods ('happy', 'think', 'wave') to CSS custom properties (variables).
+ */
+export function getMascotMoodStyles(mood: MascotMood): Record<string, string> {
+  switch (mood) {
+    case 'happy':
+      return {
+        '--rfr-mascot-shell': 'var(--primary, 138 60% 51%)',
+        '--rfr-mascot-shell-rim': 'var(--primary-700, 138 58% 36%)',
+        '--rfr-mascot-belly': 'var(--primary-200, 138 60% 83%)',
+        '--rfr-mascot-skin': 'var(--primary-400, 138 59% 63%)',
+        '--rfr-mascot-skin-d': 'var(--primary-600, 138 58% 43%)',
+        '--rfr-mascot-scute': 'var(--sunshine, 42 100% 62%)',
+        '--rfr-mascot-scute-alt': 'var(--primary-300, 138 59% 74%)',
+        '--rfr-mascot-cheek': 'var(--accent-solid, 26 100% 67%)',
+      }
+    case 'think':
+      return {
+        // Indigo / purple tones
+        '--rfr-mascot-shell': '250 65% 55%',
+        '--rfr-mascot-shell-rim': '250 65% 40%',
+        '--rfr-mascot-belly': '250 65% 85%',
+        '--rfr-mascot-skin': '250 65% 72%',
+        '--rfr-mascot-skin-d': '250 65% 62%',
+        '--rfr-mascot-scute': '280 65% 60%',
+        '--rfr-mascot-scute-alt': '280 65% 50%',
+        '--rfr-mascot-cheek': '320 80% 65%',
+      }
+    case 'wave':
+      return {
+        // Orange / warm tones
+        '--rfr-mascot-shell': '24 85% 50%',
+        '--rfr-mascot-shell-rim': '24 85% 40%',
+        '--rfr-mascot-belly': '24 85% 85%',
+        '--rfr-mascot-skin': '24 85% 68%',
+        '--rfr-mascot-skin-d': '24 85% 58%',
+        '--rfr-mascot-scute': '160 60% 45%',
+        '--rfr-mascot-scute-alt': '160 60% 35%',
+        '--rfr-mascot-cheek': '15 90% 65%',
+      }
+  }
+}
+
+/**
+ * Creates a cleanup-enabled interval timer for Tobi's blinking state.
+ * Blinks for 150ms every 4000ms.
+ */
+export function startMascotBlinkInterval(
+  onBlinkChange: (isBlinking: boolean) => void,
+  intervalMs = 4000,
+  durationMs = 150,
+): () => void {
+  const timer = setInterval(() => {
+    onBlinkChange(true)
+    setTimeout(() => {
+      onBlinkChange(false)
+    }, durationMs)
+  }, intervalMs)
+
+  return () => {
+    clearInterval(timer)
+  }
+}
+
+export function createMascot(props: MascotProps = {}): MascotAPI {
+  const { mood = 'happy', animation = 'none', size = 'md', animate = true } = props
+
+  const ariaProps: Record<string, string | number | boolean> = {
+    role: 'img',
+    'aria-label': `Tobi the Tortoise feeling ${mood}`,
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-slot': 'mascot',
+    'data-mood': mood,
+    'data-animation': animation,
+    'data-size': size,
+    'data-animate': animate ? 'true' : 'false',
+  }
+
+  return {
+    ariaProps,
+    dataAttributes,
+    state: {
+      mood,
+      animation,
+      size,
+      animate,
+    },
+    style: getMascotMoodStyles(mood),
+  }
+}

package/dist/slot-picker/index.ts

@@ -0,0 +1,18 @@
+export {
+  slotsForDay,
+  isSlotSelected,
+  createSlotPicker,
+  type SlotDay,
+  type SlotSelection,
+  type SlotPickerAPI,
+} from './slot-picker.js'
+
+export {
+  slotPickerVariants,
+  slotPickerDayRowClass,
+  slotPickerDayVariants,
+  slotPickerGridClass,
+  slotPickerSlotVariants,
+  slotPickerSectionLabelClass,
+  slotPickerTimezoneClass,
+} from './slot-picker.styles.js'

package/dist/slot-picker/slot-picker.styles.ts

@@ -0,0 +1,70 @@
+import { cva } from '../shared/index.ts'
+
+/** Root wrapper for the entire slot picker (day row + slots grid). */
+export const slotPickerVariants = cva({
+  base: 'flex flex-col gap-4',
+  variants: {},
+  defaultVariants: {},
+})
+
+/** Scrollable row of day chips. */
+export const slotPickerDayRowClass = 'flex items-center gap-2 overflow-x-auto pb-1'
+
+/**
+ * Individual day chip.
+ *
+ * `selected` → primary treatment; `unselected` → card with border.
+ */
+export const slotPickerDayVariants = cva({
+  base: [
+    'inline-flex flex-col items-center justify-center rounded-lg px-3 py-2 min-w-[3.5rem]',
+    'text-sm font-medium cursor-pointer transition-colors',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+    'disabled:pointer-events-none disabled:opacity-50',
+  ].join(' '),
+  variants: {
+    selected: {
+      true: 'bg-primary text-primary-foreground',
+      false: 'bg-card border border-input text-foreground hover:bg-muted',
+    },
+  },
+  defaultVariants: {
+    selected: 'false',
+  },
+})
+
+/** Grid that holds the time-slot buttons. */
+export const slotPickerGridClass = 'grid grid-cols-3 gap-2 sm:grid-cols-4'
+
+/**
+ * Individual time-slot button.
+ *
+ * `selected` → primary; `disabled` → dimmed regardless of selection.
+ */
+export const slotPickerSlotVariants = cva({
+  base: [
+    'inline-flex items-center justify-center rounded-md border px-3 py-2 text-sm font-medium',
+    'transition-colors cursor-pointer',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+  ].join(' '),
+  variants: {
+    selected: {
+      true: 'bg-primary text-primary-foreground border-primary',
+      false: 'bg-card border-input text-foreground hover:bg-muted',
+    },
+    disabled: {
+      true: 'opacity-40 pointer-events-none',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    selected: 'false',
+    disabled: 'false',
+  },
+})
+
+/** Section label above the day row or slot grid (e.g. "Pick a day"). */
+export const slotPickerSectionLabelClass = 'text-sm font-semibold text-foreground'
+
+/** Timezone label rendered beside the "Pick a time" heading. */
+export const slotPickerTimezoneClass = 'text-xs text-muted-foreground ml-2'

package/dist/slot-picker/slot-picker.ts

@@ -0,0 +1,64 @@
+/** A single day chip shown in the day-selector row. */
+export type SlotDay = {
+  /** Unique identifier for the day (e.g. "2024-06-14"). */
+  id: string
+  /** Short weekday label (e.g. "Fri"). */
+  weekday: string
+  /** Day-of-month label (e.g. "14" or 14). */
+  dayNum: string | number
+}
+
+/** The currently-selected day + time slot pair. */
+export type SlotSelection = {
+  /** The `id` of the selected day. */
+  dayId: string
+  /** The selected time slot string (e.g. "10:00 AM"). */
+  slot: string
+}
+
+/**
+ * Return the list of available time slots for a given day.
+ * Returns an empty array when `dayId` has no entry in `slotsByDay`.
+ */
+export function slotsForDay(
+  slotsByDay: Record<string, string[]>,
+  dayId: string,
+): string[] {
+  return slotsByDay[dayId] ?? []
+}
+
+/**
+ * Check whether a specific slot in a specific day is currently selected.
+ */
+export function isSlotSelected(
+  value: SlotSelection | undefined,
+  dayId: string,
+  slot: string,
+): boolean {
+  return value?.dayId === dayId && value?.slot === slot
+}
+
+export interface SlotPickerAPI {
+  /** ARIA attributes to spread on the root group element. */
+  ariaProps: { role: 'group'; 'aria-label': string }
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic root props for a slot picker.
+ *
+ * Returns `role="group"` with an accessible label and data attributes.
+ * Adapters spread these onto their container element.
+ */
+export function createSlotPicker(): SlotPickerAPI {
+  return {
+    ariaProps: {
+      role: 'group',
+      'aria-label': 'Pick a time',
+    },
+    dataAttributes: {
+      'data-component': 'slot-picker',
+    },
+  }
+}

package/dist/sortable-list/index.ts

@@ -0,0 +1,13 @@
+export {
+  reorder,
+  getNextOrderIndex,
+  createSortableList,
+  type SortableListAPI,
+} from './sortable-list.js'
+
+export {
+  sortableListVariants,
+  sortableListRowVariants,
+  sortableListGripClass,
+  sortableListContentClass,
+} from './sortable-list.styles.js'

package/dist/sortable-list/sortable-list.styles.ts

@@ -0,0 +1,42 @@
+import { cva } from '../shared/index.ts'
+
+/** The outer list container. */
+export const sortableListVariants = cva({
+  base: 'flex flex-col gap-1 w-full',
+  variants: {
+    disabled: {
+      true: 'opacity-50 pointer-events-none',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    disabled: 'false',
+  },
+})
+
+/**
+ * A single row in the list. The `dragging` variant visually lifts the row
+ * while it is being dragged.
+ */
+export const sortableListRowVariants = cva({
+  base: [
+    'flex items-center gap-3 rounded-md border border-border bg-card px-3 py-2',
+    'transition-opacity',
+  ].join(' '),
+  variants: {
+    dragging: {
+      true: 'opacity-50 ring-2 ring-ring',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    dragging: 'false',
+  },
+})
+
+/** The drag-grip handle button/icon area. */
+export const sortableListGripClass =
+  'cursor-grab text-muted-foreground shrink-0 flex items-center focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background rounded'
+
+/** Wraps the caller-supplied row content (fills remaining space). */
+export const sortableListContentClass = 'flex-1 min-w-0'

package/dist/sortable-list/sortable-list.ts

@@ -0,0 +1,90 @@
+/**
+ * Pure, JSX-free headless logic for a drag-to-reorder vertical list.
+ *
+ * Three exports:
+ *   - `reorder`           — immutable array move, clamped
+ *   - `getNextOrderIndex` — keyboard navigation rule (clamped, no wrap)
+ *   - `createSortableList` — builds ARIA props for the list container
+ */
+
+export interface SortableListAPI {
+  /** ARIA attributes to spread on the list element. */
+  ariaProps: Record<string, string | number | boolean>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Move an item from index `from` to index `to` in `items`, returning a new
+ * array. Out-of-range indices return a shallow copy of the original array
+ * (no mutation, no throw).
+ */
+export function reorder<T>(items: T[], from: number, to: number): T[] {
+  const len = items.length
+  if (
+    len === 0 ||
+    from < 0 ||
+    from >= len ||
+    to < 0 ||
+    to >= len ||
+    from === to
+  ) {
+    return [...items]
+  }
+  const result = [...items]
+  const [moved] = result.splice(from, 1)
+  result.splice(to, 0, moved)
+  return result
+}
+
+/**
+ * Keyboard reorder navigation — returns the next index for a given key.
+ *
+ * - ArrowUp / ArrowLeft   → max(0, current - 1)
+ * - ArrowDown / ArrowRight → min(count - 1, current + 1)
+ * - Home → 0
+ * - End → count - 1
+ * - All other keys / empty list → current (clamped to valid range)
+ *
+ * Never wraps.
+ */
+export function getNextOrderIndex(
+  current: number,
+  key: string,
+  count: number,
+): number {
+  if (count <= 0) return current
+  const clamped = Math.max(0, Math.min(current, count - 1))
+
+  switch (key) {
+    case 'ArrowUp':
+    case 'ArrowLeft':
+      return Math.max(0, clamped - 1)
+    case 'ArrowDown':
+    case 'ArrowRight':
+      return Math.min(count - 1, clamped + 1)
+    case 'Home':
+      return 0
+    case 'End':
+      return count - 1
+    default:
+      return clamped
+  }
+}
+
+/**
+ * Build the framework-agnostic props for a sortable list container.
+ *
+ * Returns `role="list"` so screen readers announce the number of items
+ * correctly, plus a `data-component` hook for styling.
+ */
+export function createSortableList(): SortableListAPI {
+  return {
+    ariaProps: {
+      role: 'list',
+    },
+    dataAttributes: {
+      'data-component': 'sortable-list',
+    },
+  }
+}