@refraction-ui/astro 0.4.0 → 0.4.4

package/dist/rich-editor/slash-commands.ts

@@ -0,0 +1,212 @@
+/**
+ * Slash command system.
+ * When user types "/" at the start of a block or after a space, a menu appears
+ * with available commands that can be filtered by typing.
+ */
+
+import type { Document, BlockType } from './model.js'
+import type { Selection } from './selection.js'
+import type { EditorState } from './operations.js'
+import { changeBlockType, insertBlock, deleteSelection } from './operations.js'
+import { createCollapsedSelection, createSelection, createPosition } from './selection.js'
+import { findBlockById, getBlockText, cloneDocument, createTextSegment } from './model.js'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SlashCommand {
+  name: string
+  label: string
+  description: string
+  icon?: string
+  keywords: string[]
+  action: (doc: Document, sel: Selection) => EditorState
+}
+
+export interface SlashCommandMenu {
+  isOpen: boolean
+  query: string
+  filteredCommands: SlashCommand[]
+  selectedIndex: number
+  open(query?: string): void
+  close(): void
+  search(query: string): void
+  selectNext(): void
+  selectPrevious(): void
+  execute(doc: Document, sel: Selection): EditorState | null
+}
+
+// ---------------------------------------------------------------------------
+// Built-in commands
+// ---------------------------------------------------------------------------
+
+function makeBlockCommand(
+  name: string,
+  label: string,
+  description: string,
+  keywords: string[],
+  blockType: BlockType,
+  meta?: Record<string, unknown>,
+): SlashCommand {
+  return {
+    name,
+    label,
+    description,
+    keywords,
+    action: (doc: Document, sel: Selection): EditorState => {
+      return changeBlockType(doc, sel, blockType, meta)
+    },
+  }
+}
+
+export const BUILT_IN_COMMANDS: SlashCommand[] = [
+  makeBlockCommand('heading1', 'Heading 1', 'Large section heading', ['h1', 'title', 'heading'], 'heading', { level: 1 }),
+  makeBlockCommand('heading2', 'Heading 2', 'Medium section heading', ['h2', 'subtitle', 'heading'], 'heading', { level: 2 }),
+  makeBlockCommand('heading3', 'Heading 3', 'Small section heading', ['h3', 'heading'], 'heading', { level: 3 }),
+  makeBlockCommand('bullet-list', 'Bullet List', 'Create a bulleted list', ['ul', 'unordered', 'bullet', 'list'], 'list-item', { listType: 'bullet' }),
+  makeBlockCommand('numbered-list', 'Numbered List', 'Create a numbered list', ['ol', 'ordered', 'number', 'list'], 'list-item', { listType: 'ordered' }),
+  makeBlockCommand('quote', 'Quote', 'Create a blockquote', ['blockquote', 'citation', 'quote'], 'blockquote'),
+  makeBlockCommand('code', 'Code Block', 'Create a code block', ['code', 'pre', 'snippet', 'programming'], 'code-block'),
+  makeBlockCommand('divider', 'Divider', 'Insert a horizontal divider', ['hr', 'horizontal', 'rule', 'separator', 'line'], 'divider'),
+  {
+    name: 'image',
+    label: 'Image',
+    description: 'Insert an image',
+    keywords: ['img', 'picture', 'photo'],
+    action: (doc: Document, sel: Selection): EditorState => {
+      return changeBlockType(doc, sel, 'image')
+    },
+  },
+]
+
+// ---------------------------------------------------------------------------
+// Fuzzy filter
+// ---------------------------------------------------------------------------
+function matchesQuery(command: SlashCommand, query: string): boolean {
+  const q = query.toLowerCase()
+  if (q === '') return true
+  if (command.name.toLowerCase().includes(q)) return true
+  if (command.label.toLowerCase().includes(q)) return true
+  if (command.description.toLowerCase().includes(q)) return true
+  return command.keywords.some((kw) => kw.toLowerCase().includes(q))
+}
+
+// ---------------------------------------------------------------------------
+// Menu factory
+// ---------------------------------------------------------------------------
+
+export function createSlashCommandMenu(commands?: SlashCommand[]): SlashCommandMenu {
+  const allCommands = commands ?? BUILT_IN_COMMANDS
+
+  const state = {
+    isOpen: false,
+    query: '',
+    filteredCommands: [] as SlashCommand[],
+    selectedIndex: 0,
+  }
+
+  function updateFiltered() {
+    state.filteredCommands = allCommands.filter((cmd) => matchesQuery(cmd, state.query))
+    if (state.selectedIndex >= state.filteredCommands.length) {
+      state.selectedIndex = Math.max(0, state.filteredCommands.length - 1)
+    }
+  }
+
+  const menu: SlashCommandMenu = {
+    get isOpen() { return state.isOpen },
+    get query() { return state.query },
+    get filteredCommands() { return state.filteredCommands },
+    get selectedIndex() { return state.selectedIndex },
+
+    open(query?: string) {
+      state.isOpen = true
+      state.query = query ?? ''
+      state.selectedIndex = 0
+      updateFiltered()
+    },
+
+    close() {
+      state.isOpen = false
+      state.query = ''
+      state.filteredCommands = []
+      state.selectedIndex = 0
+    },
+
+    search(query: string) {
+      state.query = query
+      updateFiltered()
+    },
+
+    selectNext() {
+      if (state.filteredCommands.length === 0) return
+      state.selectedIndex = (state.selectedIndex + 1) % state.filteredCommands.length
+    },
+
+    selectPrevious() {
+      if (state.filteredCommands.length === 0) return
+      state.selectedIndex =
+        (state.selectedIndex - 1 + state.filteredCommands.length) % state.filteredCommands.length
+    },
+
+    execute(doc: Document, sel: Selection): EditorState | null {
+      if (!state.isOpen || state.filteredCommands.length === 0) return null
+      const command = state.filteredCommands[state.selectedIndex]
+      if (!command) return null
+
+      // Remove the slash and query text from the block before executing
+      const block = findBlockById(doc, sel.anchor.blockId)
+      if (block) {
+        const text = getBlockText(block)
+        // Find the "/" that started this command
+        const slashIdx = text.lastIndexOf('/', sel.anchor.offset)
+        if (slashIdx !== -1) {
+          const d = cloneDocument(doc)
+          const b = d.blocks.find((bl) => bl.id === block.id)!
+          const beforeSlash = text.slice(0, slashIdx)
+          const afterCursor = text.slice(sel.anchor.offset)
+          b.content = [createTextSegment(beforeSlash + afterCursor)]
+          const newSel = createCollapsedSelection(b.id, slashIdx)
+          const result = command.action(d, newSel)
+          menu.close()
+          return result
+        }
+      }
+
+      const result = command.action(doc, sel)
+      menu.close()
+      return result
+    },
+  }
+
+  return menu
+}
+
+/**
+ * Detect whether the user has typed a "/" that should trigger the slash command menu.
+ */
+export function detectSlashTrigger(
+  doc: Document,
+  sel: Selection,
+): { triggered: boolean; query: string } {
+  const block = findBlockById(doc, sel.anchor.blockId)
+  if (!block) return { triggered: false, query: '' }
+
+  const text = getBlockText(block)
+  const textBeforeCursor = text.slice(0, sel.anchor.offset)
+
+  // Look for "/" preceded by start-of-text or a space
+  const slashIdx = textBeforeCursor.lastIndexOf('/')
+  if (slashIdx === -1) return { triggered: false, query: '' }
+
+  // The slash must be at position 0 or preceded by a space
+  if (slashIdx > 0 && textBeforeCursor[slashIdx - 1] !== ' ') {
+    return { triggered: false, query: '' }
+  }
+
+  const query = textBeforeCursor.slice(slashIdx + 1)
+  // If query contains spaces, the slash command is no longer active
+  if (query.includes(' ')) return { triggered: false, query: '' }
+
+  return { triggered: true, query }
+}

package/dist/search-bar/index.ts

@@ -0,0 +1,7 @@
+export {
+  createSearchBar,
+  type SearchBarProps,
+  type SearchBarAPI,
+} from './search-bar.js'
+
+export { searchBarVariants, searchResultVariants } from './search-bar.styles.js'

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

@@ -0,0 +1,29 @@
+import { cva } from '../shared/index.ts'
+
+export const searchBarVariants = cva({
+  base: 'relative flex items-center w-full rounded-md border bg-background text-foreground',
+  variants: {
+    size: {
+      sm: 'h-8 text-sm px-2',
+      md: 'h-10 text-base px-3',
+      lg: 'h-12 text-lg px-4',
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+  },
+})
+
+export const searchResultVariants = cva({
+  base: 'absolute top-full left-0 w-full mt-1 rounded-md border bg-popover text-popover-foreground shadow-md z-50 overflow-hidden',
+  variants: {
+    size: {
+      sm: 'text-sm',
+      md: 'text-base',
+      lg: 'text-lg',
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+  },
+})

package/dist/search-bar/search-bar.ts

@@ -0,0 +1,130 @@
+import type { KeyboardHandlerMap } from '../shared/index.ts'
+import { generateId, Keys, createKeyboardHandler } from '../shared/index.ts'
+
+export interface SearchBarProps {
+  value?: string
+  onValueChange?: (value: string) => void
+  onSearch?: (value: string) => void
+  debounceMs?: number
+  placeholder?: string
+  loading?: boolean
+}
+
+export interface SearchBarAPI {
+  /** Current state */
+  state: { value: string; isSearching: boolean }
+  /** Props to spread on the input element */
+  inputProps: {
+    role: 'combobox'
+    'aria-expanded': boolean
+    'aria-controls': string
+    'aria-autocomplete': 'list'
+  }
+  /** Props to spread on the results list element */
+  listProps: {
+    role: 'listbox'
+    id: string
+  }
+  /** Set the search value */
+  setValue: (value: string) => void
+  /** Clear the search value */
+  clear: () => void
+  /** Keyboard handler map */
+  keyboardHandlers: KeyboardHandlerMap
+  /** Pre-built keyboard event handler */
+  handleKeyDown: (event: KeyboardEvent) => void
+}
+
+export function createSearchBar(props: SearchBarProps = {}): SearchBarAPI {
+  const {
+    value: initialValue = '',
+    onValueChange,
+    onSearch,
+    debounceMs = 300,
+    placeholder: _placeholder,
+    loading = false,
+  } = props
+
+  const listId = generateId('rfr-search-list')
+
+  let currentValue = initialValue
+  let isSearching = loading
+  let debounceTimer: ReturnType<typeof setTimeout> | undefined
+
+  const state = { value: currentValue, isSearching }
+
+  function setValue(value: string) {
+    currentValue = value
+    state.value = value
+    onValueChange?.(value)
+
+    if (debounceTimer !== undefined) {
+      clearTimeout(debounceTimer)
+    }
+
+    if (value.length > 0) {
+      isSearching = true
+      state.isSearching = true
+      debounceTimer = setTimeout(() => {
+        onSearch?.(value)
+        isSearching = false
+        state.isSearching = false
+      }, debounceMs)
+    } else {
+      isSearching = false
+      state.isSearching = false
+    }
+  }
+
+  function clear() {
+    if (debounceTimer !== undefined) {
+      clearTimeout(debounceTimer)
+    }
+    currentValue = ''
+    state.value = ''
+    isSearching = false
+    state.isSearching = false
+    onValueChange?.('')
+  }
+
+  const inputProps = {
+    role: 'combobox' as const,
+    'aria-expanded': currentValue.length > 0,
+    'aria-controls': listId,
+    'aria-autocomplete': 'list' as const,
+  }
+
+  const listProps = {
+    role: 'listbox' as const,
+    id: listId,
+  }
+
+  const keyboardHandlers: KeyboardHandlerMap = {
+    [Keys.ArrowDown]: () => {
+      // Focus first result - signaled via handler
+    },
+    [Keys.Escape]: () => {
+      clear()
+    },
+    [Keys.Enter]: () => {
+      if (debounceTimer !== undefined) {
+        clearTimeout(debounceTimer)
+      }
+      onSearch?.(currentValue)
+      isSearching = false
+      state.isSearching = false
+    },
+  }
+
+  const handleKeyDown = createKeyboardHandler(keyboardHandlers)
+
+  return {
+    state,
+    inputProps,
+    listProps,
+    setValue,
+    clear,
+    keyboardHandlers,
+    handleKeyDown,
+  }
+}

package/dist/select/index.ts

@@ -0,0 +1,13 @@
+export {
+  createSelect,
+  type SelectProps,
+  type SelectAPI,
+  type SelectOption,
+} from './select.js'
+
+export {
+  selectTriggerVariants,
+  selectContentVariants,
+  selectItemVariants,
+  selectTokens,
+} from './select.styles.js'

package/dist/select/select.styles.ts

@@ -0,0 +1,52 @@
+import { cva } from '../shared/index.ts'
+import type { TokenContract } from '../shared/index.ts'
+
+export const selectTokens: TokenContract = {
+  name: 'select',
+  tokens: {
+    bg: { variable: '--rfr-select-bg', fallback: 'hsl(var(--background))' },
+    fg: { variable: '--rfr-select-fg', fallback: 'hsl(var(--foreground))' },
+    border: { variable: '--rfr-select-border', fallback: 'hsl(var(--border))' },
+    ring: { variable: '--rfr-select-ring', fallback: 'hsl(var(--ring))' },
+  },
+}
+
+export const selectTriggerVariants = cva({
+  base: 'flex h-9 w-full items-center justify-between rounded-md border border-input bg-transparent px-3 py-2 text-sm shadow-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-1 focus:ring-ring disabled:cursor-not-allowed disabled:opacity-50',
+  variants: {
+    size: {
+      sm: 'h-8 text-xs',
+      default: 'h-9 text-sm',
+      lg: 'h-10 text-base',
+    },
+  },
+  defaultVariants: {
+    size: 'default',
+  },
+})
+
+export const selectContentVariants = cva({
+  base: 'relative z-50 max-h-96 min-w-[8rem] overflow-hidden rounded-md border bg-popover text-popover-foreground shadow-md animate-in fade-in-0 zoom-in-95',
+  variants: {
+    position: {
+      popper: 'translate-y-1',
+      'item-aligned': '',
+    },
+  },
+  defaultVariants: {
+    position: 'popper',
+  },
+})
+
+export const selectItemVariants = cva({
+  base: 'relative flex w-full cursor-default select-none items-center rounded-sm py-1.5 pl-2 pr-8 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+  variants: {
+    selected: {
+      true: 'bg-accent/50',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    selected: 'false',
+  },
+})

package/dist/select/select.ts

@@ -0,0 +1,152 @@
+import type { AccessibilityProps, KeyboardHandlerMap } from '../shared/index.ts'
+import { Keys, generateId } from '../shared/index.ts'
+
+export interface SelectOption {
+  value: string
+  label: string
+  disabled?: boolean
+}
+
+export interface SelectProps {
+  value?: string
+  options?: SelectOption[]
+  placeholder?: string
+  disabled?: boolean
+  open?: boolean
+  name?: string
+}
+
+export interface SelectAPI {
+  /** Trigger element ARIA + keyboard props */
+  triggerProps: {
+    ariaProps: Partial<AccessibilityProps>
+    keyboardHandlers: KeyboardHandlerMap
+    dataAttributes: Record<string, string>
+  }
+  /** Content (dropdown) props */
+  contentProps: {
+    ariaProps: Partial<AccessibilityProps>
+    dataAttributes: Record<string, string>
+  }
+  /** Get props for a single option */
+  getOptionProps: (option: SelectOption) => {
+    ariaProps: Partial<AccessibilityProps>
+    dataAttributes: Record<string, string>
+    isSelected: boolean
+  }
+  /** Whether interaction should be blocked */
+  isInteractive: boolean
+  /** Current state */
+  state: {
+    open: boolean
+    selectedValue: string | undefined
+    selectedLabel: string | undefined
+    disabled: boolean
+    placeholder: string
+  }
+  /** Generated IDs for trigger/content association */
+  ids: {
+    trigger: string
+    content: string
+  }
+}
+
+export function createSelect(props: SelectProps = {}): SelectAPI {
+  const {
+    value,
+    options = [],
+    placeholder = 'Select an option',
+    disabled = false,
+    open = false,
+  } = props
+
+  const isInteractive = !disabled
+  const selectedOption = options.find((o) => o.value === value)
+
+  const triggerId = generateId('select-trigger')
+  const contentId = generateId('select-content')
+
+  const triggerAriaProps: Partial<AccessibilityProps> = {
+    role: 'combobox',
+    'aria-expanded': open,
+    'aria-controls': contentId,
+    'aria-labelledby': triggerId,
+  }
+  if (disabled) {
+    triggerAriaProps['aria-disabled'] = true
+  }
+
+  const triggerKeyboardHandlers: KeyboardHandlerMap = {}
+  if (!isInteractive) {
+    triggerKeyboardHandlers[Keys.Enter] = (e) => e.preventDefault()
+    triggerKeyboardHandlers[Keys.Space] = (e) => e.preventDefault()
+    triggerKeyboardHandlers[Keys.ArrowDown] = (e) => e.preventDefault()
+    triggerKeyboardHandlers[Keys.ArrowUp] = (e) => e.preventDefault()
+  }
+
+  const triggerDataAttributes: Record<string, string> = {
+    'data-state': open ? 'open' : 'closed',
+  }
+  if (disabled) {
+    triggerDataAttributes['data-disabled'] = ''
+  }
+
+  const contentAriaProps: Partial<AccessibilityProps> = {
+    role: 'listbox',
+    'aria-labelledby': triggerId,
+  }
+
+  const contentDataAttributes: Record<string, string> = {
+    'data-state': open ? 'open' : 'closed',
+  }
+
+  function getOptionProps(option: SelectOption) {
+    const isSelected = option.value === value
+    const optionAriaProps: Partial<AccessibilityProps> = {
+      role: 'option',
+      'aria-selected': isSelected,
+    }
+    if (option.disabled) {
+      optionAriaProps['aria-disabled'] = true
+    }
+
+    const optionDataAttributes: Record<string, string> = {}
+    if (isSelected) {
+      optionDataAttributes['data-state'] = 'checked'
+    }
+    if (option.disabled) {
+      optionDataAttributes['data-disabled'] = ''
+    }
+
+    return {
+      ariaProps: optionAriaProps,
+      dataAttributes: optionDataAttributes,
+      isSelected,
+    }
+  }
+
+  return {
+    triggerProps: {
+      ariaProps: triggerAriaProps,
+      keyboardHandlers: triggerKeyboardHandlers,
+      dataAttributes: triggerDataAttributes,
+    },
+    contentProps: {
+      ariaProps: contentAriaProps,
+      dataAttributes: contentDataAttributes,
+    },
+    getOptionProps,
+    isInteractive,
+    state: {
+      open,
+      selectedValue: selectedOption?.value,
+      selectedLabel: selectedOption?.label,
+      disabled,
+      placeholder,
+    },
+    ids: {
+      trigger: triggerId,
+      content: contentId,
+    },
+  }
+}

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(' ')
+}