@refraction-ui/astro 0.4.0 → 0.4.2

package/dist/index.ts

@@ -0,0 +1,77 @@
+// Auto-generated meta-package index
+export * from './astro-accordion/index.ts';
+export * from './astro-ai/index.ts';
+export * from './astro-animated-text/index.ts';
+export * from './astro-app-shell/index.ts';
+export * from './astro-auth/index.ts';
+export * from './astro-avatar/index.ts';
+export * from './astro-avatar-group/index.ts';
+export * from './astro-badge/index.ts';
+export * from './astro-bottom-nav/index.ts';
+export * from './astro-breadcrumbs/index.ts';
+export * from './astro-button/index.ts';
+export * from './astro-calendar/index.ts';
+export * from './astro-card/index.ts';
+export * from './astro-charts/index.ts';
+export * from './astro-checkbox/index.ts';
+export * from './astro-code-editor/index.ts';
+export * from './astro-collapsible/index.ts';
+export * from './astro-command/index.ts';
+export * from './astro-content-protection/index.ts';
+export * from './astro-data-table/index.ts';
+export * from './astro-date-picker/index.ts';
+export * from './astro-device-frame/index.ts';
+export * from './astro-dialog/index.ts';
+export * from './astro-diff-viewer/index.ts';
+export * from './astro-dropdown-menu/index.ts';
+export * from './astro-emoji-picker/index.ts';
+export * from './astro-feedback-dialog/index.ts';
+export * from './astro-file-upload/index.ts';
+export * from './astro-footer/index.ts';
+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-keyboard-shortcut/index.ts';
+export * from './astro-language-selector/index.ts';
+export * from './astro-markdown-renderer/index.ts';
+export * from './astro-mobile-nav/index.ts';
+export * from './astro-navbar/index.ts';
+export * from './astro-otp-input/index.ts';
+export * from './astro-popover/index.ts';
+export * from './astro-presence-indicator/index.ts';
+export * from './astro-progress-display/index.ts';
+export * from './astro-radio/index.ts';
+export * from './astro-reaction-bar/index.ts';
+export * from './astro-resizable-layout/index.ts';
+export * from './astro-rich-editor/index.ts';
+export * from './astro-search-bar/index.ts';
+export * from './astro-select/index.ts';
+export * from './astro-sidebar/index.ts';
+export * from './astro-skeleton/index.ts';
+export * from './astro-slide-viewer/index.ts';
+export * from './astro-status-indicator/index.ts';
+export * from './astro-switch/index.ts';
+export * from './astro-tabs/index.ts';
+export * from './astro-textarea/index.ts';
+export * from './astro-theme/index.ts';
+export * from './astro-thread-view/index.ts';
+export * from './astro-toast/index.ts';
+export * from './astro-tooltip/index.ts';
+export * from './astro-version-selector/index.ts';
+export * from './astro-video-player/index.ts';
+export * from './shared/index.ts';
+export * from './astro-table-of-contents/index.ts';
+export * from './astro-carousel/index.ts';
+export * from './astro-slider/index.ts';
+export * from './astro-pagination/index.ts';
+export * from './astro-callout/index.ts';
+export * from './astro-steps/index.ts';
+export * from './astro-file-tree/index.ts';
+export * from './astro-icon-system/index.ts';
+export * from './astro-skip-to-content/index.ts';
+export * from './astro-code-block/index.ts';
+export * from './astro-link-card/index.ts';
+export * from './astro-card-grid/index.ts';
+export * from './astro-payment/index.ts';
+export * from './astro-command-input/index.ts';

package/dist/shared/a11y.ts

@@ -0,0 +1,33 @@
+/**
+ * Accessibility constants and utilities used across all components.
+ *
+ * Refraction UI Accessibility Principles:
+ * 1. NEVER convey meaning through color alone — always provide icon, text, or pattern
+ * 2. All interactive elements are keyboard navigable
+ * 3. All dynamic content has aria-live announcements
+ * 4. All colors meet WCAG AA contrast ratios (4.5:1 normal, 3:1 large)
+ * 5. Respect prefers-reduced-motion
+ * 6. Respect prefers-contrast
+ * 7. Focus indicators are always visible on keyboard navigation
+ */
+
+/** Standard icon names used across components for status indication */
+export const STATUS_ICONS = {
+  success: 'check-circle',
+  error: 'x-circle',
+  warning: 'alert-triangle',
+  info: 'info-circle',
+} as const
+
+export type StatusIconName = typeof STATUS_ICONS[keyof typeof STATUS_ICONS]
+
+/** Check if a component state relies on color alone (for testing) */
+export function hasNonColorIndicator(config: {
+  hasIcon?: boolean
+  hasText?: boolean
+  hasPattern?: boolean
+  hasBorder?: boolean
+  hasShape?: boolean
+}): boolean {
+  return Object.values(config).some(Boolean)
+}

package/dist/shared/aria.ts

@@ -0,0 +1,30 @@
+/** Merge multiple ARIA prop objects, later values override earlier ones */
+export function mergeAriaProps(
+  ...propSets: Array<Record<string, unknown>>
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  for (const props of propSets) {
+    for (const [key, value] of Object.entries(props)) {
+      if (value !== undefined) {
+        result[key] = value
+      }
+    }
+  }
+  return result
+}
+
+let idCounter = 0
+
+/**
+ * Generate a unique ID, safe for SSR (deterministic within a render pass).
+ * In browsers, uses crypto.randomUUID when available.
+ */
+export function generateId(prefix = 'rfr'): string {
+  idCounter++
+  return `${prefix}-${idCounter}`
+}
+
+/** Reset the ID counter (useful for tests) */
+export function resetIdCounter(): void {
+  idCounter = 0
+}

package/dist/shared/cn.ts

@@ -0,0 +1,35 @@
+/**
+ * Lightweight class name utility — our own implementation.
+ * Handles conditional classes, arrays, and falsy values.
+ * No external dependencies (no clsx, no tailwind-merge).
+ *
+ * For Tailwind class conflict resolution (e.g., 'p-2 p-4' → 'p-4'),
+ * consumers can use @refraction-ui/tailwind-config which provides
+ * a tw-merge-aware variant of this function.
+ */
+
+type ClassValue = string | number | boolean | undefined | null | ClassValue[]
+type ClassRecord = Record<string, boolean | undefined | null>
+
+export function cn(...inputs: Array<ClassValue | ClassRecord>): string {
+  const classes: string[] = []
+
+  for (const input of inputs) {
+    if (!input) continue
+
+    if (typeof input === 'string') {
+      classes.push(input)
+    } else if (typeof input === 'number') {
+      classes.push(String(input))
+    } else if (Array.isArray(input)) {
+      const nested = cn(...input)
+      if (nested) classes.push(nested)
+    } else if (typeof input === 'object') {
+      for (const [key, value] of Object.entries(input)) {
+        if (value) classes.push(key)
+      }
+    }
+  }
+
+  return classes.join(' ')
+}

package/dist/shared/cva.ts

@@ -0,0 +1,79 @@
+/**
+ * Lightweight class-variance-authority alternative — zero dependencies.
+ * Creates variant-driven class name functions for components.
+ */
+
+interface VariantConfig {
+  [variant: string]: Record<string, string>
+}
+
+interface CVAConfig<V extends VariantConfig> {
+  base?: string
+  variants?: V
+  defaultVariants?: {
+    [K in keyof V]?: keyof V[K]
+  }
+  compoundVariants?: Array<
+    {
+      [K in keyof V]?: keyof V[K]
+    } & { class: string }
+  >
+}
+
+type VariantProps<V extends VariantConfig> = {
+  [K in keyof V]?: keyof V[K]
+}
+
+export function cva<V extends VariantConfig>(config: CVAConfig<V>) {
+  return (props?: VariantProps<V> & { className?: string }): string => {
+    const classes: string[] = []
+
+    if (config.base) {
+      classes.push(config.base)
+    }
+
+    if (config.variants) {
+      for (const [variantKey, variantOptions] of Object.entries(config.variants)) {
+        const selectedValue =
+          (props as Record<string, unknown> | undefined)?.[variantKey] ??
+          config.defaultVariants?.[variantKey]
+
+        if (selectedValue != null) {
+          const variantClass = (variantOptions as Record<string, string>)[
+            selectedValue as string
+          ]
+          if (variantClass) {
+            classes.push(variantClass)
+          }
+        }
+      }
+    }
+
+    if (config.compoundVariants) {
+      for (const compound of config.compoundVariants) {
+        const { class: compoundClass, ...conditions } = compound
+        let matches = true
+
+        for (const [key, value] of Object.entries(conditions)) {
+          const propValue =
+            (props as Record<string, unknown>)?.[key] ??
+            config.defaultVariants?.[key]
+          if (propValue !== value) {
+            matches = false
+            break
+          }
+        }
+
+        if (matches) {
+          classes.push(compoundClass as string)
+        }
+      }
+    }
+
+    if (props?.className) {
+      classes.push(props.className)
+    }
+
+    return classes.filter(Boolean).join(' ')
+  }
+}

package/dist/shared/engine-adapter.ts

@@ -0,0 +1,10 @@
+export interface EngineAdapter<
+  TState = Record<string, unknown>,
+  TMethods = Record<string, unknown>,
+  TReturnProps = Record<string, unknown>
+> {
+  name: string;
+  state: TState;
+  methods: TMethods;
+  getProps: (elementName: string, props?: Record<string, unknown>) => TReturnProps;
+}

package/dist/shared/focus-trap.ts

@@ -0,0 +1,123 @@
+/**
+ * Focus trap utilities — keeps keyboard focus within a container.
+ * Used by Dialog, DropdownMenu, and other overlay components.
+ * Pure TypeScript, no DOM dependency (accepts element via parameter).
+ */
+
+/** Selector for all natively focusable elements */
+export const FOCUSABLE_SELECTOR =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+/** Get all focusable elements within a container */
+export function getFocusableElements(container: Element): Element[] {
+  return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR))
+}
+
+/** Configuration for creating a focus trap */
+export interface FocusTrapConfig {
+  /** The container element */
+  container: Element
+  /** Called to get the initial focus target */
+  initialFocus?: () => Element | null
+  /** Called when Escape is pressed */
+  onEscape?: () => void
+  /** Whether to return focus to trigger on deactivate */
+  returnFocusOnDeactivate?: boolean
+}
+
+/** A focus trap instance */
+export interface FocusTrap {
+  activate(): void
+  deactivate(): void
+  isActive(): boolean
+}
+
+/** Create a focus trap that keeps Tab/Shift+Tab within a container */
+export function createFocusTrap(config: FocusTrapConfig): FocusTrap {
+  let active = false
+  let previouslyFocused: Element | null = null
+
+  function handleKeyDown(event: KeyboardEvent): void {
+    if (event.key === 'Escape' && config.onEscape) {
+      event.preventDefault()
+      config.onEscape()
+      return
+    }
+
+    if (event.key !== 'Tab') return
+
+    const focusable = getFocusableElements(config.container)
+    if (focusable.length === 0) return
+
+    const first = focusable[0] as HTMLElement
+    const last = focusable[focusable.length - 1] as HTMLElement
+
+    if (event.shiftKey) {
+      // Shift+Tab: if on first element, wrap to last
+      if (document.activeElement === first) {
+        event.preventDefault()
+        last.focus()
+      }
+    } else {
+      // Tab: if on last element, wrap to first
+      if (document.activeElement === last) {
+        event.preventDefault()
+        first.focus()
+      }
+    }
+  }
+
+  return {
+    activate() {
+      if (active) return
+      active = true
+
+      // Remember the currently focused element so we can restore it later
+      if (typeof document !== 'undefined') {
+        previouslyFocused = document.activeElement
+      }
+
+      // Set initial focus
+      if (config.initialFocus) {
+        const target = config.initialFocus()
+        if (target && 'focus' in target) {
+          (target as HTMLElement).focus()
+        }
+      } else {
+        const focusable = getFocusableElements(config.container)
+        if (focusable.length > 0) {
+          (focusable[0] as HTMLElement).focus()
+        }
+      }
+
+      // Attach keydown listener to the container
+      config.container.addEventListener(
+        'keydown',
+        handleKeyDown as EventListener,
+      )
+    },
+
+    deactivate() {
+      if (!active) return
+      active = false
+
+      config.container.removeEventListener(
+        'keydown',
+        handleKeyDown as EventListener,
+      )
+
+      // Restore focus to the previously focused element
+      if (
+        config.returnFocusOnDeactivate !== false &&
+        previouslyFocused &&
+        'focus' in previouslyFocused
+      ) {
+        (previouslyFocused as HTMLElement).focus()
+      }
+    },
+
+    isActive() {
+      return active
+    },
+  }
+}

package/dist/shared/index.ts

@@ -0,0 +1,60 @@
+// Types
+export type {
+  BaseProps,
+  AccessibilityProps,
+  ThemeProps,
+  CompositionProps,
+} from './types.js'
+
+export type {
+  Size,
+  Variant,
+  Orientation,
+  Side,
+  Align,
+  DataState,
+} from './variants.js'
+
+export type {
+  TokenContract,
+  TokenDefinition,
+} from './tokens.js'
+
+export type {
+  KeyboardKey,
+  KeyboardHandlerMap,
+} from './keyboard.js'
+
+export type {
+  MachineConfig,
+  Machine,
+} from './state-machine.js'
+
+export type {
+  FocusTrapConfig,
+  FocusTrap,
+} from './focus-trap.js'
+
+export type {
+  LiveRegionConfig,
+  LiveRegion,
+} from './live-region.js'
+
+export type {
+  EngineAdapter,
+} from './engine-adapter.js'
+
+export type {
+  SkipLinkProps,
+} from './skip-link.js'
+
+// Functions
+export { mergeAriaProps, generateId, resetIdCounter } from './aria.js'
+export { Keys, createKeyboardHandler } from './keyboard.js'
+export { createMachine } from './state-machine.js'
+export { cn } from './cn.js'
+export { cva } from './cva.js'
+export { FOCUSABLE_SELECTOR, getFocusableElements, createFocusTrap } from './focus-trap.js'
+export { createLiveRegion } from './live-region.js'
+export { prefersReducedMotion, getAnimationDuration } from './motion.js'
+export { createSkipLink } from './skip-link.js'

package/dist/shared/keyboard.ts

@@ -0,0 +1,36 @@
+/** Standard keyboard key constants */
+export const Keys = {
+  Enter: 'Enter',
+  Space: ' ',
+  Escape: 'Escape',
+  Tab: 'Tab',
+  ArrowUp: 'ArrowUp',
+  ArrowDown: 'ArrowDown',
+  ArrowLeft: 'ArrowLeft',
+  ArrowRight: 'ArrowRight',
+  Home: 'Home',
+  End: 'End',
+  PageUp: 'PageUp',
+  PageDown: 'PageDown',
+  Backspace: 'Backspace',
+  Delete: 'Delete',
+} as const
+
+export type KeyboardKey = (typeof Keys)[keyof typeof Keys]
+
+/** Map of key → handler function */
+export type KeyboardHandlerMap = Partial<
+  Record<string, (event: KeyboardEvent) => void>
+>
+
+/** Create a keyboard event handler from a handler map */
+export function createKeyboardHandler(
+  handlers: KeyboardHandlerMap,
+): (event: KeyboardEvent) => void {
+  return (event: KeyboardEvent) => {
+    const handler = handlers[event.key]
+    if (handler) {
+      handler(event)
+    }
+  }
+}

package/dist/shared/live-region.ts

@@ -0,0 +1,90 @@
+/**
+ * Screen reader announcement utility.
+ * Creates and manages an aria-live region for dynamic content updates.
+ */
+
+export interface LiveRegionConfig {
+  /** 'polite' (default) or 'assertive' */
+  politeness?: 'polite' | 'assertive'
+  /** Clear the announcement after this many ms. Default: 5000 */
+  clearAfterMs?: number
+}
+
+export interface LiveRegion {
+  announce(message: string): void
+  clear(): void
+  destroy(): void
+}
+
+/** Create a live region that announces messages to screen readers */
+export function createLiveRegion(config: LiveRegionConfig = {}): LiveRegion {
+  const { politeness = 'polite', clearAfterMs = 5000 } = config
+  let element: HTMLElement | null = null
+  let clearTimeout: ReturnType<typeof setTimeout> | null = null
+
+  function getElement(): HTMLElement {
+    if (!element && typeof document !== 'undefined') {
+      element = document.createElement('div')
+      element.setAttribute('role', 'status')
+      element.setAttribute('aria-live', politeness)
+      element.setAttribute('aria-atomic', 'true')
+      // Visually hidden but accessible to screen readers
+      Object.assign(element.style, {
+        position: 'absolute',
+        width: '1px',
+        height: '1px',
+        padding: '0',
+        margin: '-1px',
+        overflow: 'hidden',
+        clip: 'rect(0, 0, 0, 0)',
+        whiteSpace: 'nowrap',
+        border: '0',
+      })
+      document.body.appendChild(element)
+    }
+    return element!
+  }
+
+  return {
+    announce(message: string): void {
+      const el = getElement()
+      if (!el) return
+
+      // Clear any pending timeout
+      if (clearTimeout !== null) {
+        globalThis.clearTimeout(clearTimeout)
+      }
+
+      // Set text content — screen readers will detect the change via aria-live
+      el.textContent = message
+
+      if (clearAfterMs > 0) {
+        clearTimeout = globalThis.setTimeout(() => {
+          el.textContent = ''
+          clearTimeout = null
+        }, clearAfterMs)
+      }
+    },
+
+    clear(): void {
+      if (clearTimeout !== null) {
+        globalThis.clearTimeout(clearTimeout)
+        clearTimeout = null
+      }
+      if (element) {
+        element.textContent = ''
+      }
+    },
+
+    destroy(): void {
+      if (clearTimeout !== null) {
+        globalThis.clearTimeout(clearTimeout)
+        clearTimeout = null
+      }
+      if (element && element.parentNode) {
+        element.parentNode.removeChild(element)
+        element = null
+      }
+    },
+  }
+}

package/dist/shared/motion.ts

@@ -0,0 +1,15 @@
+/**
+ * Reduced motion utilities.
+ * Respects user preferences for reduced motion.
+ */
+
+/** Check if user prefers reduced motion */
+export function prefersReducedMotion(): boolean {
+  if (typeof window === 'undefined') return false
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches
+}
+
+/** Get animation duration — returns '0ms' if reduced motion preferred */
+export function getAnimationDuration(normalDuration: string): string {
+  return prefersReducedMotion() ? '0ms' : normalDuration
+}

package/dist/shared/skip-link.ts

@@ -0,0 +1,35 @@
+/**
+ * Skip-to-content link utility.
+ * Provides a keyboard-accessible link that is visually hidden until focused.
+ */
+
+/** Props for a skip-to-content link */
+export interface SkipLinkProps {
+  /** ID of the target element. Default: 'main-content' */
+  targetId?: string
+  /** Label text for the link. Default: 'Skip to main content' */
+  label?: string
+}
+
+/** Create props for a skip-to-content link */
+export function createSkipLink(props: SkipLinkProps = {}): {
+  ariaProps: Record<string, string>
+  href: string
+  label: string
+  /** CSS classes — visually hidden until focused */
+  className: string
+} {
+  const targetId = props.targetId ?? 'main-content'
+  const label = props.label ?? 'Skip to main content'
+
+  return {
+    ariaProps: {
+      role: 'link',
+      'aria-label': label,
+    },
+    href: `#${targetId}`,
+    label,
+    className:
+      'sr-only focus:not-sr-only focus:absolute focus:z-50 focus:p-4 focus:bg-white focus:text-black focus:underline',
+  }
+}

package/dist/shared/state-machine.ts

@@ -0,0 +1,57 @@
+/**
+ * Minimal state machine — zero dependencies, < 1KB.
+ * Inspired by XState concepts but dramatically simpler.
+ */
+
+export interface MachineConfig<TState extends string, TEvent extends string> {
+  initial: TState
+  states: Record<TState, {
+    on?: Partial<Record<TEvent, TState>>
+  }>
+}
+
+export interface Machine<TState extends string, TEvent extends string> {
+  /** Current state */
+  state: TState
+  /** Send an event to transition */
+  send(event: TEvent): void
+  /** Subscribe to state changes. Returns unsubscribe function. */
+  subscribe(fn: (state: TState) => void): () => void
+  /** Check if machine is in a given state */
+  matches(state: TState): boolean
+}
+
+export function createMachine<TState extends string, TEvent extends string>(
+  config: MachineConfig<TState, TEvent>,
+): Machine<TState, TEvent> {
+  let current = config.initial
+  const listeners = new Set<(state: TState) => void>()
+
+  return {
+    get state() {
+      return current
+    },
+
+    send(event: TEvent) {
+      const stateConfig = config.states[current]
+      const next = stateConfig?.on?.[event]
+      if (next && next !== current) {
+        current = next
+        for (const fn of listeners) {
+          fn(current)
+        }
+      }
+    },
+
+    subscribe(fn: (state: TState) => void) {
+      listeners.add(fn)
+      return () => {
+        listeners.delete(fn)
+      }
+    },
+
+    matches(state: TState) {
+      return current === state
+    },
+  }
+}