@remix-run/ui 0.0.0 → 0.1.0

package/src/interactions/typeahead/typeahead-mixin.ts

@@ -0,0 +1,89 @@
+import { createMixin, on, type ElementProps } from '@remix-run/ui'
+
+const HIDDEN_TYPEAHEAD_TIMEOUT = 750
+
+export type SearchValue = string | string[]
+
+type HiddenTypeaheadHandler = (text: string) => void
+
+export const hiddenTypeahead = createMixin<
+  HTMLElement,
+  [onTypeahead: HiddenTypeaheadHandler],
+  ElementProps
+>((handle) => {
+  let text = ''
+  let timeoutId = 0
+
+  function clearTypeahead() {
+    clearTimeout(timeoutId)
+    timeoutId = 0
+    text = ''
+  }
+
+  function updateTypeahead(nextText: string, onTypeahead: HiddenTypeaheadHandler) {
+    text = nextText
+    onTypeahead(text)
+  }
+
+  handle.addEventListener('remove', clearTypeahead)
+
+  return (onTypeahead) => [
+    on('focusout', (event) => {
+      if (
+        event.relatedTarget instanceof Node &&
+        event.currentTarget.contains(event.relatedTarget)
+      ) {
+        return
+      }
+
+      clearTypeahead()
+    }),
+    on('keydown', (event) => {
+      if (event.key.length === 1 && !event.ctrlKey && !event.altKey && !event.metaKey) {
+        clearTimeout(timeoutId)
+        updateTypeahead(text + event.key.toLowerCase(), onTypeahead)
+        timeoutId = window.setTimeout(clearTypeahead, HIDDEN_TYPEAHEAD_TIMEOUT)
+      } else if (event.key === 'Escape') {
+        clearTypeahead()
+      } else if (event.key === 'Backspace' && text.length > 0) {
+        clearTimeout(timeoutId)
+        updateTypeahead(text.slice(0, -1), onTypeahead)
+        timeoutId = window.setTimeout(clearTypeahead, HIDDEN_TYPEAHEAD_TIMEOUT)
+      }
+    }),
+  ]
+})
+
+export function itemMatchesSearchText<item>(
+  item: item,
+  text: string,
+  getSearchValues: (item: item) => SearchValue,
+) {
+  let values = getSearchValues(item)
+  let searchValues = Array.isArray(values) ? values : [values]
+  let normalizedText = text.toLowerCase()
+
+  return searchValues.some((value) => value.toLowerCase().startsWith(normalizedText))
+}
+
+export function matchNextItemBySearchText<item>(
+  text: string,
+  items: item[],
+  options: {
+    fromIndex: number
+    getSearchValues: (item: item) => SearchValue
+  },
+) {
+  if (text === '') {
+    return null
+  }
+
+  for (let offset = 1; offset <= items.length; offset++) {
+    let item = items[(options.fromIndex + offset + items.length) % items.length]
+    if (itemMatchesSearchText(item, text, options.getSearchValues)) {
+      return item
+    }
+  }
+
+  return null
+}

package/src/jsx-runtime.ts

@@ -0,0 +1,2 @@
+export * from './runtime/jsx.ts'
+export { Fragment } from './runtime/component.ts'

package/src/runtime/client-entries.ts

@@ -0,0 +1,137 @@
+import type { Handle, NoContext, RemixNode, RenderFn } from './component.ts'
+
+/**
+ * Serializable primitive types that can be passed as props to entry components
+ */
+export type SerializablePrimitive = string | number | boolean | null | undefined
+
+/**
+ * Serializable object types that can be passed as props to entry components
+ */
+export type SerializableObject = {
+  [key: string]: SerializableValue
+}
+
+/**
+ * Serializable array types that can be passed as props to entry components
+ */
+export type SerializableArray = SerializableValue[]
+
+/**
+ * All serializable values that can be passed as props to entry components.
+ * This includes primitives, objects, arrays, and Remix Elements.
+ */
+export type SerializableValue =
+  | SerializablePrimitive
+  | SerializableObject
+  | SerializableArray
+  | RemixNode
+
+/**
+ * Constraint that ensures all properties in an object are serializable.
+ */
+export type SerializableProps = {
+  [K in string]: SerializableValue
+}
+
+/**
+ * Metadata added to entry components
+ */
+export type EntryMetadata = {
+  $entry: true
+  $entryId: string
+}
+
+/**
+ * An entry component preserves the exact function type with added metadata
+ */
+export type EntryComponent<props extends SerializableProps = {}, context = NoContext> = ((
+  handle: Handle<props, context>,
+) => RenderFn<props>) &
+  EntryMetadata
+
+/**
+ * Marks a component as a client entry for client-side hydration.
+ *
+ * @param entryId Module URL with optional export name (format: "/js/module.js#ExportName") by
+ * default, or a custom entry identifier when paired with `resolveClientEntry`
+ * @param component Component function that will be hydrated on the client
+ * @returns The component augmented with entry metadata
+ *
+ * @example
+ * ```tsx
+ * export const Counter = clientEntry(
+ *   '/js/counter.js#Counter',
+ *   function Counter(handle: Handle<{ initialCount?: number; label: string }>) {
+ *     let count = handle.props.initialCount ?? 0
+ *
+ *     return () => (
+ *       <button
+ *         type="button"
+ *         mix={[
+ *           on('click', () => {
+ *             count++
+ *             handle.update()
+ *           }),
+ *         ]}
+ *       >
+ *         {handle.props.label} {count}
+ *       </button>
+ *     )
+ *   }
+ * )
+ * ```
+ */
+export function clientEntry<props extends SerializableProps = {}, context = NoContext>(
+  entryId: string,
+  component: (handle: Handle<props, context>) => RenderFn,
+): EntryComponent<props, context>
+export function clientEntry<props extends SerializableProps = {}, context = NoContext>(
+  entryId: string,
+  component: (handle: Handle<Record<string, never>, context>) => RenderFn<props>,
+): EntryComponent<props, context>
+
+// Implementation
+export function clientEntry(entryId: string, component: any): any {
+  if (!entryId) {
+    throw new Error('clientEntry() requires an entry ID')
+  }
+
+  // Augment the component with entry metadata
+  component.$entry = true
+  component.$entryId = entryId
+
+  return component
+}
+
+/**
+ * Type guard to check if a component is an entry component
+ *
+ * @param component The component to check
+ * @returns True if the component has entry metadata
+ */
+export function isEntry(component: unknown): component is EntryComponent {
+  return Boolean(component && typeof component === 'function' && (component as any).$entry === true)
+}
+
+/**
+ * Logs a client-hydration mismatch to the console.
+ *
+ * @param msg Message parts to forward to the logger.
+ */
+export function logHydrationMismatch(...msg: any[]) {
+  console.error('Hydration mismatch:', ...msg)
+}
+
+/**
+ * Advances a DOM cursor past consecutive comment nodes.
+ *
+ * @param cursor Starting DOM node.
+ * @returns The first non-comment node, or `null` when none remains.
+ */
+export function skipComments(cursor: Node | null): Node | null {
+  while (cursor && cursor.nodeType === Node.COMMENT_NODE) {
+    cursor = cursor.nextSibling
+  }
+  return cursor
+}

package/src/runtime/component.ts

@@ -0,0 +1,402 @@
+import type { ElementProps, ElementType, RemixNode, Renderable } from './jsx.ts'
+import { TypedEventTarget } from './typed-event-target.ts'
+
+/**
+ * Task queued to run after a component update completes.
+ */
+export type Task = (signal: AbortSignal) => void
+
+/**
+ * Runtime handle passed to component setup functions.
+ */
+export interface Handle<Props = Record<string, never>, ContextValue = NoContext> {
+  /**
+   * Stable identifier per component instance. Useful for HTML APIs like
+   * htmlFor, aria-owns, etc. so consumers don't have to supply an id.
+   */
+  id: string
+
+  /**
+   * Stable props object for the component instance. The object identity does not
+   * change across updates, but its values are updated before each render.
+   */
+  props: Props
+
+  /**
+   * Set and get values in an element tree for indirect ancestor/descendant
+   * communication.
+   */
+  context: Context<ContextValue>
+
+  /**
+   * Schedules an update for the component to render again. Returns a promise
+   * that resolves with an AbortSignal after the update completes. The signal
+   * is aborted when the component re-renders or is removed.
+   *
+   * @returns A promise that resolves with an AbortSignal after the update
+   */
+  update(): Promise<AbortSignal>
+
+  /**
+   * Schedules a task to run after the next update.
+   *
+   * @param task
+   */
+  queueTask(task: Task): void
+
+  /**
+   * The component's closest frame
+   */
+  frame: FrameHandle
+
+  /**
+   * Access named frames in the current runtime tree.
+   */
+  frames: {
+    /**
+     * The root frame for the current runtime tree.
+     */
+    readonly top: FrameHandle
+    get(name: string): FrameHandle | undefined
+  }
+
+  /**
+   * A signal indicating the connected status of the component. When the
+   * component is disconnected from the tree the signal will be aborted.
+   * Useful for setup scope cleanup.
+   *
+   * @example Clear a timer
+   * ```ts
+   * function Clock(handle: Handle) {
+   *   let interval = setInterval(() => {
+   *     if (handle.signal.aborted) {
+   *       clearInterval(interval)
+   *       return
+   *     }
+   *     handle.update()
+   *   }, 1000)
+   *   return () => <span>{new Date().toString()}</span>
+   * }
+   * ```
+   *
+   * Because signals are event targets, you can also add an event instead.
+   * ```ts
+   * function Clock(handle: Handle) {
+   *   let interval = setInterval(handle.update)
+   *   handle.signal.addEventListener("abort", () => clearInterval(interval))
+   *   return () => <span>{new Date().toString()}</span>
+   * }
+   * ```
+   *
+   * You don't need to check both this.signal and a render/event signal as
+   * render/event signals are aborted when the component disconnects.
+   */
+  signal: AbortSignal
+}
+
+/**
+ * Default Handle context so types must be declared explicitly.
+ */
+export type NoContext = Record<string, never>
+
+/**
+ * Component factory shape used by the Remix component runtime.
+ */
+export type Component<Props = ElementProps, ContextValue = NoContext> = (
+  handle: Handle<Props, ContextValue>,
+) => RenderFn
+
+/**
+ * Infers the context provided by a component or handle-compatible function.
+ */
+export type ContextFrom<ComponentType> =
+  ComponentType extends Component<any, infer Provided>
+    ? Provided
+    : ComponentType extends (handle: Handle<any, infer Provided>, ...args: any[]) => any
+      ? Provided
+      : never
+
+/**
+ * Context storage API exposed on component handles.
+ */
+export interface Context<C> {
+  /** Replaces the current context value for this component instance. */
+  set(values: C): void
+  /** Reads the context value associated with the given component type. */
+  get<ComponentType>(component: ComponentType): ContextFrom<ComponentType>
+  /** Reads the context value associated with the given component key. */
+  get(component: ElementType | symbol): unknown | undefined
+}
+
+/**
+ * Content that can be rendered into a frame.
+ */
+export type FrameContent = ReadableStream<Uint8Array> | string | RemixNode
+
+/**
+ * Events emitted by frame handles during reloads.
+ */
+export type FrameHandleEventMap = {
+  reloadStart: Event
+  reloadComplete: Event
+}
+
+/**
+ * Public API for interacting with a frame instance.
+ */
+export type FrameHandle = TypedEventTarget<FrameHandleEventMap> & {
+  src: string
+  reload(): Promise<AbortSignal>
+  replace(content: FrameContent): Promise<void>
+  // Internal runtime context used by client-rendered Frame reconciliation.
+  $runtime?: unknown
+}
+
+/**
+ * Props accepted by the built-in {@link Frame} component.
+ */
+export interface FrameProps {
+  /** Optional frame name used for targeted navigation and lookups. */
+  name?: string
+  /** Source URL used when the frame loads or reloads its content. */
+  src: string
+  /** Fallback content to render while the frame is pending. */
+  fallback?: Renderable
+  /** Event handlers invoked for events dispatched from the frame element. */
+  on?: Record<string, (event: Event, signal: AbortSignal) => void | Promise<void>>
+}
+
+/**
+ * Component factory function that receives a handle and returns a render function.
+ */
+export type ComponentFn<Props = Record<string, never>, ContextValue = NoContext> = (
+  handle: Handle<Props, ContextValue>,
+) => RenderFn
+
+/**
+ * Render function returned by a component factory.
+ */
+export type RenderFn<Props = ElementProps> = (props: Props) => RemixNode
+
+export type { RemixNode } from './jsx.ts'
+
+// Handle is already exported as an interface above, no need to re-export
+
+/**
+ * Props accepted by the built-in {@link Fragment} component.
+ */
+export interface FragmentProps {
+  /** Child nodes to render without adding an extra host element. */
+  children?: RemixNode
+}
+
+/**
+ * Mapping of built-in component names to their prop shapes.
+ */
+export interface BuiltinElements {
+  /** Props accepted by the built-in fragment component. */
+  Fragment: FragmentProps
+  /** Props accepted by the built-in frame component. */
+  Frame: FrameProps
+}
+
+/**
+ * Key type used to stabilize host elements and components during reconciliation.
+ */
+export type Key = string | number | bigint
+
+type ComponentConfig = {
+  id: string
+  type: Function
+  frame: FrameHandle
+  getContext: (type: Component) => unknown
+  getFrameByName: (name: string) => FrameHandle | undefined
+  getTopFrame?: () => FrameHandle | undefined
+  signal?: AbortSignal
+}
+
+/**
+ * Runtime handle returned by {@link createComponent}.
+ */
+export type ComponentHandle = ReturnType<typeof createComponent>
+
+/**
+ * Creates the internal runtime wrapper for a component instance.
+ *
+ * @param config Component runtime configuration.
+ * @returns Component runtime helpers used by the reconciler.
+ */
+export function createComponent<C = NoContext>(config: ComponentConfig) {
+  let taskQueue: Task[] = []
+  let renderCtrl: AbortController | null = null
+  let connectedCtrl: AbortController | null = null
+  let contextValue: C | undefined = undefined
+
+  function getConnectedSignal() {
+    if (!connectedCtrl) connectedCtrl = new AbortController()
+    return connectedCtrl.signal
+  }
+
+  let getContent: null | RenderFn = null
+  let scheduleUpdate: () => void = () => {
+    throw new Error('scheduleUpdate not implemented')
+  }
+  let props = {} as ElementProps
+
+  let context: Context<C> = {
+    set: (value: C) => {
+      contextValue = value
+    },
+    get: (type: Component) => config.getContext(type),
+  }
+
+  let handle: Handle<ElementProps, C> = {
+    id: config.id,
+    props,
+    update: () =>
+      new Promise((resolve) => {
+        taskQueue.push((signal) => resolve(signal))
+        scheduleUpdate()
+      }),
+    queueTask: (task: Task) => {
+      taskQueue.push(task)
+    },
+    frame: config.frame,
+    frames: {
+      get top() {
+        return config.getTopFrame?.() ?? config.frame
+      },
+      get(name: string) {
+        return config.getFrameByName(name)
+      },
+    },
+    context: context,
+    get signal() {
+      return config.signal ?? getConnectedSignal()
+    },
+  }
+
+  function dequeueTasks(): (() => void)[] {
+    // Only create render controller if any task expects a signal (has length >= 1)
+    let needsSignal = taskQueue.some((task) => task.length >= 1)
+    if (needsSignal && !renderCtrl) {
+      renderCtrl = new AbortController()
+    }
+    let signal = renderCtrl?.signal
+    return taskQueue.splice(0, taskQueue.length).map((task) => () => task(signal!))
+  }
+
+  function render(props: ElementProps): [RemixNode, Array<() => void>] {
+    if (connectedCtrl?.signal.aborted) {
+      console.warn('render called after component was removed, potential application memory leak')
+      return [null, []]
+    }
+
+    // Only abort render controller if it was initialized
+    if (renderCtrl) {
+      renderCtrl.abort()
+      renderCtrl = null
+    }
+
+    syncProps(handle.props, props)
+
+    let renderContent = getContent
+    if (!renderContent) {
+      let result = config.type(handle)
+      if (typeof result !== 'function') {
+        let name = config.type.name || 'Anonymous'
+        throw new Error(`${name} must return a render function, received ${typeof result}`)
+      } else {
+        getContent = result
+        renderContent = result
+      }
+    }
+    if (!renderContent) {
+      throw new Error('component render function was not initialized')
+    }
+
+    let node = renderContent(handle.props)
+    return [node, dequeueTasks()]
+  }
+
+  function remove(): (() => void)[] {
+    connectedCtrl?.abort()
+    renderCtrl?.abort()
+    return dequeueTasks()
+  }
+
+  function setScheduleUpdate(nextScheduleUpdate: () => void) {
+    scheduleUpdate = nextScheduleUpdate
+  }
+
+  function getContextValue(): C | undefined {
+    return contextValue
+  }
+
+  return { render, remove, setScheduleUpdate, frame: config.frame, getContextValue }
+}
+
+function syncProps(target: ElementProps, next: ElementProps): void {
+  for (let key in target) {
+    if (!(key in next)) {
+      delete target[key]
+    }
+  }
+
+  for (let key in next) {
+    target[key] = next[key]
+  }
+}
+
+/**
+ * Built-in component used to render nested frame content.
+ *
+ * @param handle Component handle for the frame instance.
+ * @returns A placeholder render function handled by the reconciler.
+ */
+export function Frame(handle: Handle<FrameProps, FrameHandle>) {
+  void handle
+  return () => null // reconciler renders
+}
+
+/**
+ * Built-in component used to group children without adding a host element.
+ *
+ * @param handle Component handle for the fragment instance.
+ * @returns A placeholder render function handled by the reconciler.
+ */
+export function Fragment(handle: Handle<FragmentProps>) {
+  void handle
+  return () => null // reconciler renders
+}
+
+/**
+ * Creates a frame handle with default no-op implementations for testing and internal wiring.
+ *
+ * @param def Partial frame-handle implementation to merge with the defaults.
+ * @returns A frame handle object.
+ */
+export function createFrameHandle(
+  def?: Partial<{
+    src: string
+    replace: FrameHandle['replace']
+    reload: FrameHandle['reload']
+    $runtime: FrameHandle['$runtime']
+  }>,
+): FrameHandle {
+  return Object.assign(
+    new TypedEventTarget<FrameHandleEventMap>(),
+    {
+      src: '/',
+      replace: notImplemented('replace not implemented'),
+      reload: notImplemented('reload not implemented'),
+    },
+    def,
+  )
+}
+
+function notImplemented(msg: string) {
+  return (): never => {
+    throw new Error(msg)
+  }
+}

package/src/runtime/create-element.ts

@@ -0,0 +1,38 @@
+import { jsx } from './jsx.ts'
+import type { ElementType, RemixElement } from './jsx.ts'
+
+/**
+ * Creates a Remix virtual element from a JSX-like call signature.
+ *
+ * @param type Host tag, component function, or mixin host placeholder.
+ * @param props Element props.
+ * @param children Child nodes.
+ * @returns A Remix virtual element.
+ */
+export function createElement(
+  type: ElementType,
+  props?: Record<string, any>,
+  ...children: any[]
+): RemixElement {
+  let nextProps = { ...(props ?? {}) }
+  if (isMixinElementType(type)) {
+    if (children.length > 0) {
+      console.error(new Error('mixin elements must not receive children'))
+    }
+  } else {
+    nextProps.children = children
+  }
+
+  if (nextProps.key != null) {
+    let { key, ...rest } = nextProps
+    return jsx(type, rest, key)
+  }
+
+  return jsx(type, nextProps)
+}
+
+function isMixinElementType(
+  type: ElementType,
+): type is ((...args: unknown[]) => unknown) & { __rmxMixinElementType: string } {
+  return typeof type === 'function' && '__rmxMixinElementType' in type
+}