@refraction-ui/astro 0.4.0 → 0.4.4

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
+    },
+  }
+}

package/dist/shared/tokens.ts

@@ -0,0 +1,16 @@
+/** Defines the CSS custom properties a component reads */
+export interface TokenContract {
+  /** Component name */
+  name: string
+  /** Map of token name → CSS custom property info */
+  tokens: Record<string, TokenDefinition>
+}
+
+export interface TokenDefinition {
+  /** CSS custom property name (e.g., '--rfr-button-bg') */
+  variable: string
+  /** Fallback value when the variable is not set */
+  fallback: string
+  /** Description of what this token controls */
+  description?: string
+}

package/dist/shared/types.ts

@@ -0,0 +1,45 @@
+/**
+ * Framework-agnostic base prop types for all refraction-ui components.
+ * These are headless core types — no React, Angular, or Astro imports.
+ * Framework wrappers extend these with framework-specific types.
+ */
+
+/** Base props shared by all components */
+export interface BaseProps {
+  id?: string
+  className?: string
+  style?: Record<string, string | number>
+  [dataAttr: `data-${string}`]: string | undefined
+}
+
+/** Accessibility props */
+export interface AccessibilityProps {
+  role?: string
+  tabIndex?: number
+  'aria-label'?: string
+  'aria-labelledby'?: string
+  'aria-describedby'?: string
+  'aria-controls'?: string
+  'aria-expanded'?: boolean
+  'aria-selected'?: boolean
+  'aria-hidden'?: boolean
+  'aria-disabled'?: boolean
+  'aria-pressed'?: boolean | 'mixed'
+  'aria-checked'?: boolean | 'mixed'
+  'aria-current'?: boolean | 'page' | 'step' | 'location' | 'date' | 'time'
+  'aria-live'?: 'off' | 'assertive' | 'polite'
+  'aria-atomic'?: boolean
+}
+
+/** Theme customization props (framework-agnostic) */
+export interface ThemeProps {
+  variant?: string
+  size?: string
+  colorScheme?: string
+  disabled?: boolean
+}
+
+/** Composition props (framework-agnostic) */
+export interface CompositionProps {
+  asChild?: boolean
+}

package/dist/shared/variants.ts

@@ -0,0 +1,17 @@
+/** Standard size scale */
+export type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+
+/** Standard component variants */
+export type Variant = 'default' | 'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link'
+
+/** Layout orientation */
+export type Orientation = 'horizontal' | 'vertical'
+
+/** Positioning side */
+export type Side = 'top' | 'right' | 'bottom' | 'left'
+
+/** Alignment */
+export type Align = 'start' | 'center' | 'end'
+
+/** Data state attribute values */
+export type DataState = 'open' | 'closed' | 'active' | 'inactive'

package/dist/sidebar/index.ts

@@ -0,0 +1,9 @@
+export {
+  createSidebar,
+  type SidebarItem,
+  type SidebarSection,
+  type SidebarProps,
+  type SidebarAPI,
+} from './sidebar.js'
+
+export { sidebarVariants, sidebarItemVariants } from './sidebar.styles.js'

package/dist/sidebar/sidebar.styles.ts

@@ -0,0 +1,27 @@
+import { cva } from '../shared/index.ts'
+
+export const sidebarVariants = cva({
+  base: 'hidden md:flex flex-col border-r bg-background',
+  variants: {
+    collapsed: {
+      true: 'w-16',
+      false: 'w-64',
+    },
+  },
+  defaultVariants: {
+    collapsed: 'false',
+  },
+})
+
+export const sidebarItemVariants = cva({
+  base: 'flex items-center gap-3 rounded-md px-3 py-2 text-sm font-medium transition-colors',
+  variants: {
+    active: {
+      true: 'bg-accent text-accent-foreground',
+      false: 'text-muted-foreground hover:bg-muted hover:text-foreground',
+    },
+  },
+  defaultVariants: {
+    active: 'false',
+  },
+})

package/dist/sidebar/sidebar.ts

@@ -0,0 +1,59 @@
+export interface SidebarItem {
+  label: string
+  href: string
+  icon?: string
+  /** Roles required to see this item */
+  roles?: string[]
+  /** Nested items */
+  children?: SidebarItem[]
+}
+
+export interface SidebarSection {
+  title?: string
+  items: SidebarItem[]
+}
+
+export interface SidebarProps {
+  sections?: SidebarSection[]
+  currentPath?: string
+  collapsed?: boolean
+  userRoles?: string[]
+}
+
+export interface SidebarAPI {
+  ariaProps: Record<string, string>
+  isActive: (href: string) => boolean
+  isVisible: (item: SidebarItem) => boolean
+  itemAriaProps: (href: string) => Record<string, string>
+  visibleSections: SidebarSection[]
+}
+
+export function createSidebar(props: SidebarProps = {}): SidebarAPI {
+  const { sections = [], currentPath = '/', userRoles = [] } = props
+
+  function isActive(href: string): boolean {
+    if (href === '/') return currentPath === '/'
+    return currentPath.startsWith(href)
+  }
+
+  function isVisible(item: SidebarItem): boolean {
+    if (!item.roles || item.roles.length === 0) return true
+    return item.roles.some((role) => userRoles.includes(role))
+  }
+
+  const visibleSections = sections
+    .map((section) => ({
+      ...section,
+      items: section.items.filter(isVisible),
+    }))
+    .filter((section) => section.items.length > 0)
+
+  return {
+    ariaProps: { role: 'navigation', 'aria-label': 'Sidebar' },
+    isActive,
+    isVisible,
+    itemAriaProps: (href: string): Record<string, string> =>
+      isActive(href) ? { 'aria-current': 'page' } : {},
+    visibleSections,
+  }
+}